sqlite3.c

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         if(j+1 < ArraySize(apCopy))
57030         pOld = apCopy[++j];
57031         iNextOld = i + !leafData + pOld->nCell + pOld->nOverflow;
57032         if( pOld->nOverflow ){
57033           nOverflow = pOld->nOverflow;
57034           iOverflow = i + !leafData + pOld->aiOvfl[0];
57035         }
57036         isDivider = !leafData;  
57037       }
57038 
57039       assert(nOverflow>0 || iOverflow<i );
57040       assert(nOverflow<2 || pOld->aiOvfl[0]==pOld->aiOvfl[1]-1);
57041       assert(nOverflow<3 || pOld->aiOvfl[1]==pOld->aiOvfl[2]-1);
57042       if( i==iOverflow ){
57043         isDivider = 1;
57044         if( (--nOverflow)>0 ){
57045           iOverflow++;
57046         }
57047       }
57048 
57049       if( i==cntNew[k] ){
57050         /* Cell i is the cell immediately following the last cell on new
57051         ** sibling page k. If the siblings are not leaf pages of an
57052         ** intkey b-tree, then cell i is a divider cell.  */
57053         pNew = apNew[++k];
57054         if( !leafData ) continue;
57055       }
57056       assert( j<nOld );
57057       assert( k<nNew );
57058 
57059       /* If the cell was originally divider cell (and is not now) or
57060       ** an overflow cell, or if the cell was located on a different sibling
57061       ** page before the balancing, then the pointer map entries associated
57062       ** with any child or overflow pages need to be updated.  */
57063       if( isDivider || pOld->pgno!=pNew->pgno ){
57064         if( !leafCorrection ){
57065           ptrmapPut(pBt, get4byte(apCell[i]), PTRMAP_BTREE, pNew->pgno, &rc);
57066         }
57067         if( szCell[i]>pNew->minLocal ){
57068           ptrmapPutOvflPtr(pNew, apCell[i], &rc);
57069         }
57070       }
57071     }
57072 
57073     if( !leafCorrection ){
57074       for(i=0; i<nNew; i++){
57075         u32 key = get4byte(&apNew[i]->aData[8]);
57076         ptrmapPut(pBt, key, PTRMAP_BTREE, apNew[i]->pgno, &rc);
57077       }
57078     }
57079 
57080 #if 0
57081     /* The ptrmapCheckPages() contains assert() statements that verify that
57082     ** all pointer map pages are set correctly. This is helpful while 
57083     ** debugging. This is usually disabled because a corrupt database may
57084     ** cause an assert() statement to fail.  */
57085     ptrmapCheckPages(apNew, nNew);
57086     ptrmapCheckPages(&pParent, 1);
57087 #endif
57088   }
57089 
57090   assert( pParent->isInit );
57091   TRACE(("BALANCE: finished: old=%d new=%d cells=%d\n",
57092           nOld, nNew, nCell));
57093 
57094   /*
57095   ** Cleanup before returning.
57096   */
57097 balance_cleanup:
57098   sqlite3ScratchFree(apCell);
57099   for(i=0; i<nOld; i++){
57100     releasePage(apOld[i]);
57101   }
57102   for(i=0; i<nNew; i++){
57103     releasePage(apNew[i]);
57104   }
57105 
57106   return rc;
57107 }
57108 #if defined(_MSC_VER) && _MSC_VER >= 1700 && defined(_M_ARM)
57109 #pragma optimize("", on)
57110 #endif
57111 
57112 
57113 /*
57114 ** This function is called when the root page of a b-tree structure is
57115 ** overfull (has one or more overflow pages).
57116 **
57117 ** A new child page is allocated and the contents of the current root
57118 ** page, including overflow cells, are copied into the child. The root
57119 ** page is then overwritten to make it an empty page with the right-child 
57120 ** pointer pointing to the new page.
57121 **
57122 ** Before returning, all pointer-map entries corresponding to pages 
57123 ** that the new child-page now contains pointers to are updated. The
57124 ** entry corresponding to the new right-child pointer of the root
57125 ** page is also updated.
57126 **
57127 ** If successful, *ppChild is set to contain a reference to the child 
57128 ** page and SQLITE_OK is returned. In this case the caller is required
57129 ** to call releasePage() on *ppChild exactly once. If an error occurs,
57130 ** an error code is returned and *ppChild is set to 0.
57131 */
57132 static int balance_deeper(MemPage *pRoot, MemPage **ppChild){
57133   int rc;                        /* Return value from subprocedures */
57134   MemPage *pChild = 0;           /* Pointer to a new child page */
57135   Pgno pgnoChild = 0;            /* Page number of the new child page */
57136   BtShared *pBt = pRoot->pBt;    /* The BTree */
57137 
57138   assert( pRoot->nOverflow>0 );
57139   assert( sqlite3_mutex_held(pBt->mutex) );
57140 
57141   /* Make pRoot, the root page of the b-tree, writable. Allocate a new 
57142   ** page that will become the new right-child of pPage. Copy the contents
57143   ** of the node stored on pRoot into the new child page.
57144   */
57145   rc = sqlite3PagerWrite(pRoot->pDbPage);
57146   if( rc==SQLITE_OK ){
57147     rc = allocateBtreePage(pBt,&pChild,&pgnoChild,pRoot->pgno,0);
57148     copyNodeContent(pRoot, pChild, &rc);
57149     if( ISAUTOVACUUM ){
57150       ptrmapPut(pBt, pgnoChild, PTRMAP_BTREE, pRoot->pgno, &rc);
57151     }
57152   }
57153   if( rc ){
57154     *ppChild = 0;
57155     releasePage(pChild);
57156     return rc;
57157   }
57158   assert( sqlite3PagerIswriteable(pChild->pDbPage) );
57159   assert( sqlite3PagerIswriteable(pRoot->pDbPage) );
57160   assert( pChild->nCell==pRoot->nCell );
57161 
57162   TRACE(("BALANCE: copy root %d into %d\n", pRoot->pgno, pChild->pgno));
57163 
57164   /* Copy the overflow cells from pRoot to pChild */
57165   memcpy(pChild->aiOvfl, pRoot->aiOvfl,
57166          pRoot->nOverflow*sizeof(pRoot->aiOvfl[0]));
57167   memcpy(pChild->apOvfl, pRoot->apOvfl,
57168          pRoot->nOverflow*sizeof(pRoot->apOvfl[0]));
57169   pChild->nOverflow = pRoot->nOverflow;
57170 
57171   /* Zero the contents of pRoot. Then install pChild as the right-child. */
57172   zeroPage(pRoot, pChild->aData[0] & ~PTF_LEAF);
57173   put4byte(&pRoot->aData[pRoot->hdrOffset+8], pgnoChild);
57174 
57175   *ppChild = pChild;
57176   return SQLITE_OK;
57177 }
57178 
57179 /*
57180 ** The page that pCur currently points to has just been modified in
57181 ** some way. This function figures out if this modification means the
57182 ** tree needs to be balanced, and if so calls the appropriate balancing 
57183 ** routine. Balancing routines are:
57184 **
57185 **   balance_quick()
57186 **   balance_deeper()
57187 **   balance_nonroot()
57188 */
57189 static int balance(BtCursor *pCur){
57190   int rc = SQLITE_OK;
57191   const int nMin = pCur->pBt->usableSize * 2 / 3;
57192   u8 aBalanceQuickSpace[13];
57193   u8 *pFree = 0;
57194 
57195   TESTONLY( int balance_quick_called = 0 );
57196   TESTONLY( int balance_deeper_called = 0 );
57197 
57198   do {
57199     int iPage = pCur->iPage;
57200     MemPage *pPage = pCur->apPage[iPage];
57201 
57202     if( iPage==0 ){
57203       if( pPage->nOverflow ){
57204         /* The root page of the b-tree is overfull. In this case call the
57205         ** balance_deeper() function to create a new child for the root-page
57206         ** and copy the current contents of the root-page to it. The
57207         ** next iteration of the do-loop will balance the child page.
57208         */ 
57209         assert( (balance_deeper_called++)==0 );
57210         rc = balance_deeper(pPage, &pCur->apPage[1]);
57211         if( rc==SQLITE_OK ){
57212           pCur->iPage = 1;
57213           pCur->aiIdx[0] = 0;
57214           pCur->aiIdx[1] = 0;
57215           assert( pCur->apPage[1]->nOverflow );
57216         }
57217       }else{
57218         break;
57219       }
57220     }else if( pPage->nOverflow==0 && pPage->nFree<=nMin ){
57221       break;
57222     }else{
57223       MemPage * const pParent = pCur->apPage[iPage-1];
57224       int const iIdx = pCur->aiIdx[iPage-1];
57225 
57226       rc = sqlite3PagerWrite(pParent->pDbPage);
57227       if( rc==SQLITE_OK ){
57228 #ifndef SQLITE_OMIT_QUICKBALANCE
57229         if( pPage->hasData
57230          && pPage->nOverflow==1
57231          && pPage->aiOvfl[0]==pPage->nCell
57232          && pParent->pgno!=1
57233          && pParent->nCell==iIdx
57234         ){
57235           /* Call balance_quick() to create a new sibling of pPage on which
57236           ** to store the overflow cell. balance_quick() inserts a new cell
57237           ** into pParent, which may cause pParent overflow. If this
57238           ** happens, the next interation of the do-loop will balance pParent 
57239           ** use either balance_nonroot() or balance_deeper(). Until this
57240           ** happens, the overflow cell is stored in the aBalanceQuickSpace[]
57241           ** buffer. 
57242           **
57243           ** The purpose of the following assert() is to check that only a
57244           ** single call to balance_quick() is made for each call to this
57245           ** function. If this were not verified, a subtle bug involving reuse
57246           ** of the aBalanceQuickSpace[] might sneak in.
57247           */
57248           assert( (balance_quick_called++)==0 );
57249           rc = balance_quick(pParent, pPage, aBalanceQuickSpace);
57250         }else
57251 #endif
57252         {
57253           /* In this case, call balance_nonroot() to redistribute cells
57254           ** between pPage and up to 2 of its sibling pages. This involves
57255           ** modifying the contents of pParent, which may cause pParent to
57256           ** become overfull or underfull. The next iteration of the do-loop
57257           ** will balance the parent page to correct this.
57258           ** 
57259           ** If the parent page becomes overfull, the overflow cell or cells
57260           ** are stored in the pSpace buffer allocated immediately below. 
57261           ** A subsequent iteration of the do-loop will deal with this by
57262           ** calling balance_nonroot() (balance_deeper() may be called first,
57263           ** but it doesn't deal with overflow cells - just moves them to a
57264           ** different page). Once this subsequent call to balance_nonroot() 
57265           ** has completed, it is safe to release the pSpace buffer used by
57266           ** the previous call, as the overflow cell data will have been 
57267           ** copied either into the body of a database page or into the new
57268           ** pSpace buffer passed to the latter call to balance_nonroot().
57269           */
57270           u8 *pSpace = sqlite3PageMalloc(pCur->pBt->pageSize);
57271           rc = balance_nonroot(pParent, iIdx, pSpace, iPage==1, pCur->hints);
57272           if( pFree ){
57273             /* If pFree is not NULL, it points to the pSpace buffer used 
57274             ** by a previous call to balance_nonroot(). Its contents are
57275             ** now stored either on real database pages or within the 
57276             ** new pSpace buffer, so it may be safely freed here. */
57277             sqlite3PageFree(pFree);
57278           }
57279 
57280           /* The pSpace buffer will be freed after the next call to
57281           ** balance_nonroot(), or just before this function returns, whichever
57282           ** comes first. */
57283           pFree = pSpace;
57284         }
57285       }
57286 
57287       pPage->nOverflow = 0;
57288 
57289       /* The next iteration of the do-loop balances the parent page. */
57290       releasePage(pPage);
57291       pCur->iPage--;
57292     }
57293   }while( rc==SQLITE_OK );
57294 
57295   if( pFree ){
57296     sqlite3PageFree(pFree);
57297   }
57298   return rc;
57299 }
57300 
57301 
57302 /*
57303 ** Insert a new record into the BTree.  The key is given by (pKey,nKey)
57304 ** and the data is given by (pData,nData).  The cursor is used only to
57305 ** define what table the record should be inserted into.  The cursor
57306 ** is left pointing at a random location.
57307 **
57308 ** For an INTKEY table, only the nKey value of the key is used.  pKey is
57309 ** ignored.  For a ZERODATA table, the pData and nData are both ignored.
57310 **
57311 ** If the seekResult parameter is non-zero, then a successful call to
57312 ** MovetoUnpacked() to seek cursor pCur to (pKey, nKey) has already
57313 ** been performed. seekResult is the search result returned (a negative
57314 ** number if pCur points at an entry that is smaller than (pKey, nKey), or
57315 ** a positive value if pCur points at an etry that is larger than 
57316 ** (pKey, nKey)). 
57317 **
57318 ** If the seekResult parameter is non-zero, then the caller guarantees that
57319 ** cursor pCur is pointing at the existing copy of a row that is to be
57320 ** overwritten.  If the seekResult parameter is 0, then cursor pCur may
57321 ** point to any entry or to no entry at all and so this function has to seek
57322 ** the cursor before the new key can be inserted.
57323 */
57324 SQLITE_PRIVATE int sqlite3BtreeInsert(
57325   BtCursor *pCur,                /* Insert data into the table of this cursor */
57326   const void *pKey, i64 nKey,    /* The key of the new record */
57327   const void *pData, int nData,  /* The data of the new record */
57328   int nZero,                     /* Number of extra 0 bytes to append to data */
57329   int appendBias,                /* True if this is likely an append */
57330   int seekResult                 /* Result of prior MovetoUnpacked() call */
57331 ){
57332   int rc;
57333   int loc = seekResult;          /* -1: before desired location  +1: after */
57334   int szNew = 0;
57335   int idx;
57336   MemPage *pPage;
57337   Btree *p = pCur->pBtree;
57338   BtShared *pBt = p->pBt;
57339   unsigned char *oldCell;
57340   unsigned char *newCell = 0;
57341 
57342   if( pCur->eState==CURSOR_FAULT ){
57343     assert( pCur->skipNext!=SQLITE_OK );
57344     return pCur->skipNext;
57345   }
57346 
57347   assert( cursorHoldsMutex(pCur) );
57348   assert( pCur->wrFlag && pBt->inTransaction==TRANS_WRITE
57349               && (pBt->btsFlags & BTS_READ_ONLY)==0 );
57350   assert( hasSharedCacheTableLock(p, pCur->pgnoRoot, pCur->pKeyInfo!=0, 2) );
57351 
57352   /* Assert that the caller has been consistent. If this cursor was opened
57353   ** expecting an index b-tree, then the caller should be inserting blob
57354   ** keys with no associated data. If the cursor was opened expecting an
57355   ** intkey table, the caller should be inserting integer keys with a
57356   ** blob of associated data.  */
57357   assert( (pKey==0)==(pCur->pKeyInfo==0) );
57358 
57359   /* Save the positions of any other cursors open on this table.
57360   **
57361   ** In some cases, the call to btreeMoveto() below is a no-op. For
57362   ** example, when inserting data into a table with auto-generated integer
57363   ** keys, the VDBE layer invokes sqlite3BtreeLast() to figure out the 
57364   ** integer key to use. It then calls this function to actually insert the 
57365   ** data into the intkey B-Tree. In this case btreeMoveto() recognizes
57366   ** that the cursor is already where it needs to be and returns without
57367   ** doing any work. To avoid thwarting these optimizations, it is important
57368   ** not to clear the cursor here.
57369   */
57370   rc = saveAllCursors(pBt, pCur->pgnoRoot, pCur);
57371   if( rc ) return rc;
57372 
57373   /* If this is an insert into a table b-tree, invalidate any incrblob 
57374   ** cursors open on the row being replaced (assuming this is a replace
57375   ** operation - if it is not, the following is a no-op).  */
57376   if( pCur->pKeyInfo==0 ){
57377     invalidateIncrblobCursors(p, nKey, 0);
57378   }
57379 
57380   if( !loc ){
57381     rc = btreeMoveto(pCur, pKey, nKey, appendBias, &loc);
57382     if( rc ) return rc;
57383   }
57384   assert( pCur->eState==CURSOR_VALID || (pCur->eState==CURSOR_INVALID && loc) );
57385 
57386   pPage = pCur->apPage[pCur->iPage];
57387   assert( pPage->intKey || nKey>=0 );
57388   assert( pPage->leaf || !pPage->intKey );
57389 
57390   TRACE(("INSERT: table=%d nkey=%lld ndata=%d page=%d %s\n",
57391           pCur->pgnoRoot, nKey, nData, pPage->pgno,
57392           loc==0 ? "overwrite" : "new entry"));
57393   assert( pPage->isInit );
57394   allocateTempSpace(pBt);
57395   newCell = pBt->pTmpSpace;
57396   if( newCell==0 ) return SQLITE_NOMEM;
57397   rc = fillInCell(pPage, newCell, pKey, nKey, pData, nData, nZero, &szNew);
57398   if( rc ) goto end_insert;
57399   assert( szNew==cellSizePtr(pPage, newCell) );
57400   assert( szNew <= MX_CELL_SIZE(pBt) );
57401   idx = pCur->aiIdx[pCur->iPage];
57402   if( loc==0 ){
57403     u16 szOld;
57404     assert( idx<pPage->nCell );
57405     rc = sqlite3PagerWrite(pPage->pDbPage);
57406     if( rc ){
57407       goto end_insert;
57408     }
57409     oldCell = findCell(pPage, idx);
57410     if( !pPage->leaf ){
57411       memcpy(newCell, oldCell, 4);
57412     }
57413     szOld = cellSizePtr(pPage, oldCell);
57414     rc = clearCell(pPage, oldCell);
57415     dropCell(pPage, idx, szOld, &rc);
57416     if( rc ) goto end_insert;
57417   }else if( loc<0 && pPage->nCell>0 ){
57418     assert( pPage->leaf );
57419     idx = ++pCur->aiIdx[pCur->iPage];
57420   }else{
57421     assert( pPage->leaf );
57422   }
57423   insertCell(pPage, idx, newCell, szNew, 0, 0, &rc);
57424   assert( rc!=SQLITE_OK || pPage->nCell>0 || pPage->nOverflow>0 );
57425 
57426   /* If no error has occurred and pPage has an overflow cell, call balance() 
57427   ** to redistribute the cells within the tree. Since balance() may move
57428   ** the cursor, zero the BtCursor.info.nSize and BtCursor.validNKey
57429   ** variables.
57430   **
57431   ** Previous versions of SQLite called moveToRoot() to move the cursor
57432   ** back to the root page as balance() used to invalidate the contents
57433   ** of BtCursor.apPage[] and BtCursor.aiIdx[]. Instead of doing that,
57434   ** set the cursor state to "invalid". This makes common insert operations
57435   ** slightly faster.
57436   **
57437   ** There is a subtle but important optimization here too. When inserting
57438   ** multiple records into an intkey b-tree using a single cursor (as can
57439   ** happen while processing an "INSERT INTO ... SELECT" statement), it
57440   ** is advantageous to leave the cursor pointing to the last entry in
57441   ** the b-tree if possible. If the cursor is left pointing to the last
57442   ** entry in the table, and the next row inserted has an integer key
57443   ** larger than the largest existing key, it is possible to insert the
57444   ** row without seeking the cursor. This can be a big performance boost.
57445   */
57446   pCur->info.nSize = 0;
57447   pCur->validNKey = 0;
57448   if( rc==SQLITE_OK && pPage->nOverflow ){
57449     rc = balance(pCur);
57450 
57451     /* Must make sure nOverflow is reset to zero even if the balance()
57452     ** fails. Internal data structure corruption will result otherwise. 
57453     ** Also, set the cursor state to invalid. This stops saveCursorPosition()
57454     ** from trying to save the current position of the cursor.  */
57455     pCur->apPage[pCur->iPage]->nOverflow = 0;
57456     pCur->eState = CURSOR_INVALID;
57457   }
57458   assert( pCur->apPage[pCur->iPage]->nOverflow==0 );
57459 
57460 end_insert:
57461   return rc;
57462 }
57463 
57464 /*
57465 ** Delete the entry that the cursor is pointing to.  The cursor
57466 ** is left pointing at a arbitrary location.
57467 */
57468 SQLITE_PRIVATE int sqlite3BtreeDelete(BtCursor *pCur){
57469   Btree *p = pCur->pBtree;
57470   BtShared *pBt = p->pBt;              
57471   int rc;                              /* Return code */
57472   MemPage *pPage;                      /* Page to delete cell from */
57473   unsigned char *pCell;                /* Pointer to cell to delete */
57474   int iCellIdx;                        /* Index of cell to delete */
57475   int iCellDepth;                      /* Depth of node containing pCell */ 
57476 
57477   assert( cursorHoldsMutex(pCur) );
57478   assert( pBt->inTransaction==TRANS_WRITE );
57479   assert( (pBt->btsFlags & BTS_READ_ONLY)==0 );
57480   assert( pCur->wrFlag );
57481   assert( hasSharedCacheTableLock(p, pCur->pgnoRoot, pCur->pKeyInfo!=0, 2) );
57482   assert( !hasReadConflicts(p, pCur->pgnoRoot) );
57483 
57484   if( NEVER(pCur->aiIdx[pCur->iPage]>=pCur->apPage[pCur->iPage]->nCell) 
57485    || NEVER(pCur->eState!=CURSOR_VALID)
57486   ){
57487     return SQLITE_ERROR;  /* Something has gone awry. */
57488   }
57489 
57490   iCellDepth = pCur->iPage;
57491   iCellIdx = pCur->aiIdx[iCellDepth];
57492   pPage = pCur->apPage[iCellDepth];
57493   pCell = findCell(pPage, iCellIdx);
57494 
57495   /* If the page containing the entry to delete is not a leaf page, move
57496   ** the cursor to the largest entry in the tree that is smaller than
57497   ** the entry being deleted. This cell will replace the cell being deleted
57498   ** from the internal node. The 'previous' entry is used for this instead
57499   ** of the 'next' entry, as the previous entry is always a part of the
57500   ** sub-tree headed by the child page of the cell being deleted. This makes
57501   ** balancing the tree following the delete operation easier.  */
57502   if( !pPage->leaf ){
57503     int notUsed;
57504     rc = sqlite3BtreePrevious(pCur, &notUsed);
57505     if( rc ) return rc;
57506   }
57507 
57508   /* Save the positions of any other cursors open on this table before
57509   ** making any modifications. Make the page containing the entry to be 
57510   ** deleted writable. Then free any overflow pages associated with the 
57511   ** entry and finally remove the cell itself from within the page.  
57512   */
57513   rc = saveAllCursors(pBt, pCur->pgnoRoot, pCur);
57514   if( rc ) return rc;
57515 
57516   /* If this is a delete operation to remove a row from a table b-tree,
57517   ** invalidate any incrblob cursors open on the row being deleted.  */
57518   if( pCur->pKeyInfo==0 ){
57519     invalidateIncrblobCursors(p, pCur->info.nKey, 0);
57520   }
57521 
57522   rc = sqlite3PagerWrite(pPage->pDbPage);
57523   if( rc ) return rc;
57524   rc = clearCell(pPage, pCell);
57525   dropCell(pPage, iCellIdx, cellSizePtr(pPage, pCell), &rc);
57526   if( rc ) return rc;
57527 
57528   /* If the cell deleted was not located on a leaf page, then the cursor
57529   ** is currently pointing to the largest entry in the sub-tree headed
57530   ** by the child-page of the cell that was just deleted from an internal
57531   ** node. The cell from the leaf node needs to be moved to the internal
57532   ** node to replace the deleted cell.  */
57533   if( !pPage->leaf ){
57534     MemPage *pLeaf = pCur->apPage[pCur->iPage];
57535     int nCell;
57536     Pgno n = pCur->apPage[iCellDepth+1]->pgno;
57537     unsigned char *pTmp;
57538 
57539     pCell = findCell(pLeaf, pLeaf->nCell-1);
57540     nCell = cellSizePtr(pLeaf, pCell);
57541     assert( MX_CELL_SIZE(pBt) >= nCell );
57542 
57543     allocateTempSpace(pBt);
57544     pTmp = pBt->pTmpSpace;
57545 
57546     rc = sqlite3PagerWrite(pLeaf->pDbPage);
57547     insertCell(pPage, iCellIdx, pCell-4, nCell+4, pTmp, n, &rc);
57548     dropCell(pLeaf, pLeaf->nCell-1, nCell, &rc);
57549     if( rc ) return rc;
57550   }
57551 
57552   /* Balance the tree. If the entry deleted was located on a leaf page,
57553   ** then the cursor still points to that page. In this case the first
57554   ** call to balance() repairs the tree, and the if(...) condition is
57555   ** never true.
57556   **
57557   ** Otherwise, if the entry deleted was on an internal node page, then
57558   ** pCur is pointing to the leaf page from which a cell was removed to
57559   ** replace the cell deleted from the internal node. This is slightly
57560   ** tricky as the leaf node may be underfull, and the internal node may
57561   ** be either under or overfull. In this case run the balancing algorithm
57562   ** on the leaf node first. If the balance proceeds far enough up the
57563   ** tree that we can be sure that any problem in the internal node has
57564   ** been corrected, so be it. Otherwise, after balancing the leaf node,
57565   ** walk the cursor up the tree to the internal node and balance it as 
57566   ** well.  */
57567   rc = balance(pCur);
57568   if( rc==SQLITE_OK && pCur->iPage>iCellDepth ){
57569     while( pCur->iPage>iCellDepth ){
57570       releasePage(pCur->apPage[pCur->iPage--]);
57571     }
57572     rc = balance(pCur);
57573   }
57574 
57575   if( rc==SQLITE_OK ){
57576     moveToRoot(pCur);
57577   }
57578   return rc;
57579 }
57580 
57581 /*
57582 ** Create a new BTree table.  Write into *piTable the page
57583 ** number for the root page of the new table.
57584 **
57585 ** The type of type is determined by the flags parameter.  Only the
57586 ** following values of flags are currently in use.  Other values for
57587 ** flags might not work:
57588 **
57589 **     BTREE_INTKEY|BTREE_LEAFDATA     Used for SQL tables with rowid keys
57590 **     BTREE_ZERODATA                  Used for SQL indices
57591 */
57592 static int btreeCreateTable(Btree *p, int *piTable, int createTabFlags){
57593   BtShared *pBt = p->pBt;
57594   MemPage *pRoot;
57595   Pgno pgnoRoot;
57596   int rc;
57597   int ptfFlags;          /* Page-type flage for the root page of new table */
57598 
57599   assert( sqlite3BtreeHoldsMutex(p) );
57600   assert( pBt->inTransaction==TRANS_WRITE );
57601   assert( (pBt->btsFlags & BTS_READ_ONLY)==0 );
57602 
57603 #ifdef SQLITE_OMIT_AUTOVACUUM
57604   rc = allocateBtreePage(pBt, &pRoot, &pgnoRoot, 1, 0);
57605   if( rc ){
57606     return rc;
57607   }
57608 #else
57609   if( pBt->autoVacuum ){
57610     Pgno pgnoMove;      /* Move a page here to make room for the root-page */
57611     MemPage *pPageMove; /* The page to move to. */
57612 
57613     /* Creating a new table may probably require moving an existing database
57614     ** to make room for the new tables root page. In case this page turns
57615     ** out to be an overflow page, delete all overflow page-map caches
57616     ** held by open cursors.
57617     */
57618     invalidateAllOverflowCache(pBt);
57619 
57620     /* Read the value of meta[3] from the database to determine where the
57621     ** root page of the new table should go. meta[3] is the largest root-page
57622     ** created so far, so the new root-page is (meta[3]+1).
57623     */
57624     sqlite3BtreeGetMeta(p, BTREE_LARGEST_ROOT_PAGE, &pgnoRoot);
57625     pgnoRoot++;
57626 
57627     /* The new root-page may not be allocated on a pointer-map page, or the
57628     ** PENDING_BYTE page.
57629     */
57630     while( pgnoRoot==PTRMAP_PAGENO(pBt, pgnoRoot) ||
57631         pgnoRoot==PENDING_BYTE_PAGE(pBt) ){
57632       pgnoRoot++;
57633     }
57634     assert( pgnoRoot>=3 );
57635 
57636     /* Allocate a page. The page that currently resides at pgnoRoot will
57637     ** be moved to the allocated page (unless the allocated page happens
57638     ** to reside at pgnoRoot).
57639     */
57640     rc = allocateBtreePage(pBt, &pPageMove, &pgnoMove, pgnoRoot, BTALLOC_EXACT);
57641     if( rc!=SQLITE_OK ){
57642       return rc;
57643     }
57644 
57645     if( pgnoMove!=pgnoRoot ){
57646       /* pgnoRoot is the page that will be used for the root-page of
57647       ** the new table (assuming an error did not occur). But we were
57648       ** allocated pgnoMove. If required (i.e. if it was not allocated
57649       ** by extending the file), the current page at position pgnoMove
57650       ** is already journaled.
57651       */
57652       u8 eType = 0;
57653       Pgno iPtrPage = 0;
57654 
57655       /* Save the positions of any open cursors. This is required in
57656       ** case they are holding a reference to an xFetch reference
57657       ** corresponding to page pgnoRoot.  */
57658       rc = saveAllCursors(pBt, 0, 0);
57659       releasePage(pPageMove);
57660       if( rc!=SQLITE_OK ){
57661         return rc;
57662       }
57663 
57664       /* Move the page currently at pgnoRoot to pgnoMove. */
57665       rc = btreeGetPage(pBt, pgnoRoot, &pRoot, 0);
57666       if( rc!=SQLITE_OK ){
57667         return rc;
57668       }
57669       rc = ptrmapGet(pBt, pgnoRoot, &eType, &iPtrPage);
57670       if( eType==PTRMAP_ROOTPAGE || eType==PTRMAP_FREEPAGE ){
57671         rc = SQLITE_CORRUPT_BKPT;
57672       }
57673       if( rc!=SQLITE_OK ){
57674         releasePage(pRoot);
57675         return rc;
57676       }
57677       assert( eType!=PTRMAP_ROOTPAGE );
57678       assert( eType!=PTRMAP_FREEPAGE );
57679       rc = relocatePage(pBt, pRoot, eType, iPtrPage, pgnoMove, 0);
57680       releasePage(pRoot);
57681 
57682       /* Obtain the page at pgnoRoot */
57683       if( rc!=SQLITE_OK ){
57684         return rc;
57685       }
57686       rc = btreeGetPage(pBt, pgnoRoot, &pRoot, 0);
57687       if( rc!=SQLITE_OK ){
57688         return rc;
57689       }
57690       rc = sqlite3PagerWrite(pRoot->pDbPage);
57691       if( rc!=SQLITE_OK ){
57692         releasePage(pRoot);
57693         return rc;
57694       }
57695     }else{
57696       pRoot = pPageMove;
57697     } 
57698 
57699     /* Update the pointer-map and meta-data with the new root-page number. */
57700     ptrmapPut(pBt, pgnoRoot, PTRMAP_ROOTPAGE, 0, &rc);
57701     if( rc ){
57702       releasePage(pRoot);
57703       return rc;
57704     }
57705 
57706     /* When the new root page was allocated, page 1 was made writable in
57707     ** order either to increase the database filesize, or to decrement the
57708     ** freelist count.  Hence, the sqlite3BtreeUpdateMeta() call cannot fail.
57709     */
57710     assert( sqlite3PagerIswriteable(pBt->pPage1->pDbPage) );
57711     rc = sqlite3BtreeUpdateMeta(p, 4, pgnoRoot);
57712     if( NEVER(rc) ){
57713       releasePage(pRoot);
57714       return rc;
57715     }
57716 
57717   }else{
57718     rc = allocateBtreePage(pBt, &pRoot, &pgnoRoot, 1, 0);
57719     if( rc ) return rc;
57720   }
57721 #endif
57722   assert( sqlite3PagerIswriteable(pRoot->pDbPage) );
57723   if( createTabFlags & BTREE_INTKEY ){
57724     ptfFlags = PTF_INTKEY | PTF_LEAFDATA | PTF_LEAF;
57725   }else{
57726     ptfFlags = PTF_ZERODATA | PTF_LEAF;
57727   }
57728   zeroPage(pRoot, ptfFlags);
57729   sqlite3PagerUnref(pRoot->pDbPage);
57730   assert( (pBt->openFlags & BTREE_SINGLE)==0 || pgnoRoot==2 );
57731   *piTable = (int)pgnoRoot;
57732   return SQLITE_OK;
57733 }
57734 SQLITE_PRIVATE int sqlite3BtreeCreateTable(Btree *p, int *piTable, int flags){
57735   int rc;
57736   sqlite3BtreeEnter(p);
57737   rc = btreeCreateTable(p, piTable, flags);
57738   sqlite3BtreeLeave(p);
57739   return rc;
57740 }
57741 
57742 /*
57743 ** Erase the given database page and all its children.  Return
57744 ** the page to the freelist.
57745 */
57746 static int clearDatabasePage(
57747   BtShared *pBt,           /* The BTree that contains the table */
57748   Pgno pgno,               /* Page number to clear */
57749   int freePageFlag,        /* Deallocate page if true */
57750   int *pnChange            /* Add number of Cells freed to this counter */
57751 ){
57752   MemPage *pPage;
57753   int rc;
57754   unsigned char *pCell;
57755   int i;
57756 
57757   assert( sqlite3_mutex_held(pBt->mutex) );
57758   if( pgno>btreePagecount(pBt) ){
57759     return SQLITE_CORRUPT_BKPT;
57760   }
57761 
57762   rc = getAndInitPage(pBt, pgno, &pPage, 0);
57763   if( rc ) return rc;
57764   for(i=0; i<pPage->nCell; i++){
57765     pCell = findCell(pPage, i);
57766     if( !pPage->leaf ){
57767       rc = clearDatabasePage(pBt, get4byte(pCell), 1, pnChange);
57768       if( rc ) goto cleardatabasepage_out;
57769     }
57770     rc = clearCell(pPage, pCell);
57771     if( rc ) goto cleardatabasepage_out;
57772   }
57773   if( !pPage->leaf ){
57774     rc = clearDatabasePage(pBt, get4byte(&pPage->aData[8]), 1, pnChange);
57775     if( rc ) goto cleardatabasepage_out;
57776   }else if( pnChange ){
57777     assert( pPage->intKey );
57778     *pnChange += pPage->nCell;
57779   }
57780   if( freePageFlag ){
57781     freePage(pPage, &rc);
57782   }else if( (rc = sqlite3PagerWrite(pPage->pDbPage))==0 ){
57783     zeroPage(pPage, pPage->aData[0] | PTF_LEAF);
57784   }
57785 
57786 cleardatabasepage_out:
57787   releasePage(pPage);
57788   return rc;
57789 }
57790 
57791 /*
57792 ** Delete all information from a single table in the database.  iTable is
57793 ** the page number of the root of the table.  After this routine returns,
57794 ** the root page is empty, but still exists.
57795 **
57796 ** This routine will fail with SQLITE_LOCKED if there are any open
57797 ** read cursors on the table.  Open write cursors are moved to the
57798 ** root of the table.
57799 **
57800 ** If pnChange is not NULL, then table iTable must be an intkey table. The
57801 ** integer value pointed to by pnChange is incremented by the number of
57802 ** entries in the table.
57803 */
57804 SQLITE_PRIVATE int sqlite3BtreeClearTable(Btree *p, int iTable, int *pnChange){
57805   int rc;
57806   BtShared *pBt = p->pBt;
57807   sqlite3BtreeEnter(p);
57808   assert( p->inTrans==TRANS_WRITE );
57809 
57810   rc = saveAllCursors(pBt, (Pgno)iTable, 0);
57811 
57812   if( SQLITE_OK==rc ){
57813     /* Invalidate all incrblob cursors open on table iTable (assuming iTable
57814     ** is the root of a table b-tree - if it is not, the following call is
57815     ** a no-op).  */
57816     invalidateIncrblobCursors(p, 0, 1);
57817     rc = clearDatabasePage(pBt, (Pgno)iTable, 0, pnChange);
57818   }
57819   sqlite3BtreeLeave(p);
57820   return rc;
57821 }
57822 
57823 /*
57824 ** Erase all information in a table and add the root of the table to
57825 ** the freelist.  Except, the root of the principle table (the one on
57826 ** page 1) is never added to the freelist.
57827 **
57828 ** This routine will fail with SQLITE_LOCKED if there are any open
57829 ** cursors on the table.
57830 **
57831 ** If AUTOVACUUM is enabled and the page at iTable is not the last
57832 ** root page in the database file, then the last root page 
57833 ** in the database file is moved into the slot formerly occupied by
57834 ** iTable and that last slot formerly occupied by the last root page
57835 ** is added to the freelist instead of iTable.  In this say, all
57836 ** root pages are kept at the beginning of the database file, which
57837 ** is necessary for AUTOVACUUM to work right.  *piMoved is set to the 
57838 ** page number that used to be the last root page in the file before
57839 ** the move.  If no page gets moved, *piMoved is set to 0.
57840 ** The last root page is recorded in meta[3] and the value of
57841 ** meta[3] is updated by this procedure.
57842 */
57843 static int btreeDropTable(Btree *p, Pgno iTable, int *piMoved){
57844   int rc;
57845   MemPage *pPage = 0;
57846   BtShared *pBt = p->pBt;
57847 
57848   assert( sqlite3BtreeHoldsMutex(p) );
57849   assert( p->inTrans==TRANS_WRITE );
57850 
57851   /* It is illegal to drop a table if any cursors are open on the
57852   ** database. This is because in auto-vacuum mode the backend may
57853   ** need to move another root-page to fill a gap left by the deleted
57854   ** root page. If an open cursor was using this page a problem would 
57855   ** occur.
57856   **
57857   ** This error is caught long before control reaches this point.
57858   */
57859   if( NEVER(pBt->pCursor) ){
57860     sqlite3ConnectionBlocked(p->db, pBt->pCursor->pBtree->db);
57861     return SQLITE_LOCKED_SHAREDCACHE;
57862   }
57863 
57864   rc = btreeGetPage(pBt, (Pgno)iTable, &pPage, 0);
57865   if( rc ) return rc;
57866   rc = sqlite3BtreeClearTable(p, iTable, 0);
57867   if( rc ){
57868     releasePage(pPage);
57869     return rc;
57870   }
57871 
57872   *piMoved = 0;
57873 
57874   if( iTable>1 ){
57875 #ifdef SQLITE_OMIT_AUTOVACUUM
57876     freePage(pPage, &rc);
57877     releasePage(pPage);
57878 #else
57879     if( pBt->autoVacuum ){
57880       Pgno maxRootPgno;
57881       sqlite3BtreeGetMeta(p, BTREE_LARGEST_ROOT_PAGE, &maxRootPgno);
57882 
57883       if( iTable==maxRootPgno ){
57884         /* If the table being dropped is the table with the largest root-page
57885         ** number in the database, put the root page on the free list. 
57886         */
57887         freePage(pPage, &rc);
57888         releasePage(pPage);
57889         if( rc!=SQLITE_OK ){
57890           return rc;
57891         }
57892       }else{
57893         /* The table being dropped does not have the largest root-page
57894         ** number in the database. So move the page that does into the 
57895         ** gap left by the deleted root-page.
57896         */
57897         MemPage *pMove;
57898         releasePage(pPage);
57899         rc = btreeGetPage(pBt, maxRootPgno, &pMove, 0);
57900         if( rc!=SQLITE_OK ){
57901           return rc;
57902         }
57903         rc = relocatePage(pBt, pMove, PTRMAP_ROOTPAGE, 0, iTable, 0);
57904         releasePage(pMove);
57905         if( rc!=SQLITE_OK ){
57906           return rc;
57907         }
57908         pMove = 0;
57909         rc = btreeGetPage(pBt, maxRootPgno, &pMove, 0);
57910         freePage(pMove, &rc);
57911         releasePage(pMove);
57912         if( rc!=SQLITE_OK ){
57913           return rc;
57914         }
57915         *piMoved = maxRootPgno;
57916       }
57917 
57918       /* Set the new 'max-root-page' value in the database header. This
57919       ** is the old value less one, less one more if that happens to
57920       ** be a root-page number, less one again if that is the
57921       ** PENDING_BYTE_PAGE.
57922       */
57923       maxRootPgno--;
57924       while( maxRootPgno==PENDING_BYTE_PAGE(pBt)
57925              || PTRMAP_ISPAGE(pBt, maxRootPgno) ){
57926         maxRootPgno--;
57927       }
57928       assert( maxRootPgno!=PENDING_BYTE_PAGE(pBt) );
57929 
57930       rc = sqlite3BtreeUpdateMeta(p, 4, maxRootPgno);
57931     }else{
57932       freePage(pPage, &rc);
57933       releasePage(pPage);
57934     }
57935 #endif
57936   }else{
57937     /* If sqlite3BtreeDropTable was called on page 1.
57938     ** This really never should happen except in a corrupt
57939     ** database. 
57940     */
57941     zeroPage(pPage, PTF_INTKEY|PTF_LEAF );
57942     releasePage(pPage);
57943   }
57944   return rc;  
57945 }
57946 SQLITE_PRIVATE int sqlite3BtreeDropTable(Btree *p, int iTable, int *piMoved){
57947   int rc;
57948   sqlite3BtreeEnter(p);
57949   rc = btreeDropTable(p, iTable, piMoved);
57950   sqlite3BtreeLeave(p);
57951   return rc;
57952 }
57953 
57954 
57955 /*
57956 ** This function may only be called if the b-tree connection already
57957 ** has a read or write transaction open on the database.
57958 **
57959 ** Read the meta-information out of a database file.  Meta[0]
57960 ** is the number of free pages currently in the database.  Meta[1]
57961 ** through meta[15] are available for use by higher layers.  Meta[0]
57962 ** is read-only, the others are read/write.
57963 ** 
57964 ** The schema layer numbers meta values differently.  At the schema
57965 ** layer (and the SetCookie and ReadCookie opcodes) the number of
57966 ** free pages is not visible.  So Cookie[0] is the same as Meta[1].
57967 */
57968 SQLITE_PRIVATE void sqlite3BtreeGetMeta(Btree *p, int idx, u32 *pMeta){
57969   BtShared *pBt = p->pBt;
57970 
57971   sqlite3BtreeEnter(p);
57972   assert( p->inTrans>TRANS_NONE );
57973   assert( SQLITE_OK==querySharedCacheTableLock(p, MASTER_ROOT, READ_LOCK) );
57974   assert( pBt->pPage1 );
57975   assert( idx>=0 && idx<=15 );
57976 
57977   *pMeta = get4byte(&pBt->pPage1->aData[36 + idx*4]);
57978 
57979   /* If auto-vacuum is disabled in this build and this is an auto-vacuum
57980   ** database, mark the database as read-only.  */
57981 #ifdef SQLITE_OMIT_AUTOVACUUM
57982   if( idx==BTREE_LARGEST_ROOT_PAGE && *pMeta>0 ){
57983     pBt->btsFlags |= BTS_READ_ONLY;
57984   }
57985 #endif
57986 
57987   sqlite3BtreeLeave(p);
57988 }
57989 
57990 /*
57991 ** Write meta-information back into the database.  Meta[0] is
57992 ** read-only and may not be written.
57993 */
57994 SQLITE_PRIVATE int sqlite3BtreeUpdateMeta(Btree *p, int idx, u32 iMeta){
57995   BtShared *pBt = p->pBt;
57996   unsigned char *pP1;
57997   int rc;
57998   assert( idx>=1 && idx<=15 );
57999   sqlite3BtreeEnter(p);
58000   assert( p->inTrans==TRANS_WRITE );
58001   assert( pBt->pPage1!=0 );
58002   pP1 = pBt->pPage1->aData;
58003   rc = sqlite3PagerWrite(pBt->pPage1->pDbPage);
58004   if( rc==SQLITE_OK ){
58005     put4byte(&pP1[36 + idx*4], iMeta);
58006 #ifndef SQLITE_OMIT_AUTOVACUUM
58007     if( idx==BTREE_INCR_VACUUM ){
58008       assert( pBt->autoVacuum || iMeta==0 );
58009       assert( iMeta==0 || iMeta==1 );
58010       pBt->incrVacuum = (u8)iMeta;
58011     }
58012 #endif
58013   }
58014   sqlite3BtreeLeave(p);
58015   return rc;
58016 }
58017 
58018 #ifndef SQLITE_OMIT_BTREECOUNT
58019 /*
58020 ** The first argument, pCur, is a cursor opened on some b-tree. Count the
58021 ** number of entries in the b-tree and write the result to *pnEntry.
58022 **
58023 ** SQLITE_OK is returned if the operation is successfully executed. 
58024 ** Otherwise, if an error is encountered (i.e. an IO error or database
58025 ** corruption) an SQLite error code is returned.
58026 */
58027 SQLITE_PRIVATE int sqlite3BtreeCount(BtCursor *pCur, i64 *pnEntry){
58028   i64 nEntry = 0;                      /* Value to return in *pnEntry */
58029   int rc;                              /* Return code */
58030 
58031   if( pCur->pgnoRoot==0 ){
58032     *pnEntry = 0;
58033     return SQLITE_OK;
58034   }
58035   rc = moveToRoot(pCur);
58036 
58037   /* Unless an error occurs, the following loop runs one iteration for each
58038   ** page in the B-Tree structure (not including overflow pages). 
58039   */
58040   while( rc==SQLITE_OK ){
58041     int iIdx;                          /* Index of child node in parent */
58042     MemPage *pPage;                    /* Current page of the b-tree */
58043 
58044     /* If this is a leaf page or the tree is not an int-key tree, then 
58045     ** this page contains countable entries. Increment the entry counter
58046     ** accordingly.
58047     */
58048     pPage = pCur->apPage[pCur->iPage];
58049     if( pPage->leaf || !pPage->intKey ){
58050       nEntry += pPage->nCell;
58051     }
58052 
58053     /* pPage is a leaf node. This loop navigates the cursor so that it 
58054     ** points to the first interior cell that it points to the parent of
58055     ** the next page in the tree that has not yet been visited. The
58056     ** pCur->aiIdx[pCur->iPage] value is set to the index of the parent cell
58057     ** of the page, or to the number of cells in the page if the next page
58058     ** to visit is the right-child of its parent.
58059     **
58060     ** If all pages in the tree have been visited, return SQLITE_OK to the
58061     ** caller.
58062     */
58063     if( pPage->leaf ){
58064       do {
58065         if( pCur->iPage==0 ){
58066           /* All pages of the b-tree have been visited. Return successfully. */
58067           *pnEntry = nEntry;
58068           return SQLITE_OK;
58069         }
58070         moveToParent(pCur);
58071       }while ( pCur->aiIdx[pCur->iPage]>=pCur->apPage[pCur->iPage]->nCell );
58072 
58073       pCur->aiIdx[pCur->iPage]++;
58074       pPage = pCur->apPage[pCur->iPage];
58075     }
58076 
58077     /* Descend to the child node of the cell that the cursor currently 
58078     ** points at. This is the right-child if (iIdx==pPage->nCell).
58079     */
58080     iIdx = pCur->aiIdx[pCur->iPage];
58081     if( iIdx==pPage->nCell ){
58082       rc = moveToChild(pCur, get4byte(&pPage->aData[pPage->hdrOffset+8]));
58083     }else{
58084       rc = moveToChild(pCur, get4byte(findCell(pPage, iIdx)));
58085     }
58086   }
58087 
58088   /* An error has occurred. Return an error code. */
58089   return rc;
58090 }
58091 #endif
58092 
58093 /*
58094 ** Return the pager associated with a BTree.  This routine is used for
58095 ** testing and debugging only.
58096 */
58097 SQLITE_PRIVATE Pager *sqlite3BtreePager(Btree *p){
58098   return p->pBt->pPager;
58099 }
58100 
58101 #ifndef SQLITE_OMIT_INTEGRITY_CHECK
58102 /*
58103 ** Append a message to the error message string.
58104 */
58105 static void checkAppendMsg(
58106   IntegrityCk *pCheck,
58107   char *zMsg1,
58108   const char *zFormat,
58109   ...
58110 ){
58111   va_list ap;
58112   if( !pCheck->mxErr ) return;
58113   pCheck->mxErr--;
58114   pCheck->nErr++;
58115   va_start(ap, zFormat);
58116   if( pCheck->errMsg.nChar ){
58117     sqlite3StrAccumAppend(&pCheck->errMsg, "\n", 1);
58118   }
58119   if( zMsg1 ){
58120     sqlite3StrAccumAppend(&pCheck->errMsg, zMsg1, -1);
58121   }
58122   sqlite3VXPrintf(&pCheck->errMsg, 1, zFormat, ap);
58123   va_end(ap);
58124   if( pCheck->errMsg.accError==STRACCUM_NOMEM ){
58125     pCheck->mallocFailed = 1;
58126   }
58127 }
58128 #endif /* SQLITE_OMIT_INTEGRITY_CHECK */
58129 
58130 #ifndef SQLITE_OMIT_INTEGRITY_CHECK
58131 
58132 /*
58133 ** Return non-zero if the bit in the IntegrityCk.aPgRef[] array that
58134 ** corresponds to page iPg is already set.
58135 */
58136 static int getPageReferenced(IntegrityCk *pCheck, Pgno iPg){
58137   assert( iPg<=pCheck->nPage && sizeof(pCheck->aPgRef[0])==1 );
58138   return (pCheck->aPgRef[iPg/8] & (1 << (iPg & 0x07)));
58139 }
58140 
58141 /*
58142 ** Set the bit in the IntegrityCk.aPgRef[] array that corresponds to page iPg.
58143 */
58144 static void setPageReferenced(IntegrityCk *pCheck, Pgno iPg){
58145   assert( iPg<=pCheck->nPage && sizeof(pCheck->aPgRef[0])==1 );
58146   pCheck->aPgRef[iPg/8] |= (1 << (iPg & 0x07));
58147 }
58148 
58149 
58150 /*
58151 ** Add 1 to the reference count for page iPage.  If this is the second
58152 ** reference to the page, add an error message to pCheck->zErrMsg.
58153 ** Return 1 if there are 2 ore more references to the page and 0 if
58154 ** if this is the first reference to the page.
58155 **
58156 ** Also check that the page number is in bounds.
58157 */
58158 static int checkRef(IntegrityCk *pCheck, Pgno iPage, char *zContext){
58159   if( iPage==0 ) return 1;
58160   if( iPage>pCheck->nPage ){
58161     checkAppendMsg(pCheck, zContext, "invalid page number %d", iPage);
58162     return 1;
58163   }
58164   if( getPageReferenced(pCheck, iPage) ){
58165     checkAppendMsg(pCheck, zContext, "2nd reference to page %d", iPage);
58166     return 1;
58167   }
58168   setPageReferenced(pCheck, iPage);
58169   return 0;
58170 }
58171 
58172 #ifndef SQLITE_OMIT_AUTOVACUUM
58173 /*
58174 ** Check that the entry in the pointer-map for page iChild maps to 
58175 ** page iParent, pointer type ptrType. If not, append an error message
58176 ** to pCheck.
58177 */
58178 static void checkPtrmap(
58179   IntegrityCk *pCheck,   /* Integrity check context */
58180   Pgno iChild,           /* Child page number */
58181   u8 eType,              /* Expected pointer map type */
58182   Pgno iParent,          /* Expected pointer map parent page number */
58183   char *zContext         /* Context description (used for error msg) */
58184 ){
58185   int rc;
58186   u8 ePtrmapType = 0;
58187   Pgno iPtrmapParent = 0;
58188 
58189   rc = ptrmapGet(pCheck->pBt, iChild, &ePtrmapType, &iPtrmapParent);
58190   if( rc!=SQLITE_OK ){
58191     if( rc==SQLITE_NOMEM || rc==SQLITE_IOERR_NOMEM ) pCheck->mallocFailed = 1;
58192     checkAppendMsg(pCheck, zContext, "Failed to read ptrmap key=%d", iChild);
58193     return;
58194   }
58195 
58196   if( ePtrmapType!=eType || iPtrmapParent!=iParent ){
58197     checkAppendMsg(pCheck, zContext, 
58198       "Bad ptr map entry key=%d expected=(%d,%d) got=(%d,%d)", 
58199       iChild, eType, iParent, ePtrmapType, iPtrmapParent);
58200   }
58201 }
58202 #endif
58203 
58204 /*
58205 ** Check the integrity of the freelist or of an overflow page list.
58206 ** Verify that the number of pages on the list is N.
58207 */
58208 static void checkList(
58209   IntegrityCk *pCheck,  /* Integrity checking context */
58210   int isFreeList,       /* True for a freelist.  False for overflow page list */
58211   int iPage,            /* Page number for first page in the list */
58212   int N,                /* Expected number of pages in the list */
58213   char *zContext        /* Context for error messages */
58214 ){
58215   int i;
58216   int expected = N;
58217   int iFirst = iPage;
58218   while( N-- > 0 && pCheck->mxErr ){
58219     DbPage *pOvflPage;
58220     unsigned char *pOvflData;
58221     if( iPage<1 ){
58222       checkAppendMsg(pCheck, zContext,
58223          "%d of %d pages missing from overflow list starting at %d",
58224           N+1, expected, iFirst);
58225       break;
58226     }
58227     if( checkRef(pCheck, iPage, zContext) ) break;
58228     if( sqlite3PagerGet(pCheck->pPager, (Pgno)iPage, &pOvflPage) ){
58229       checkAppendMsg(pCheck, zContext, "failed to get page %d", iPage);
58230       break;
58231     }
58232     pOvflData = (unsigned char *)sqlite3PagerGetData(pOvflPage);
58233     if( isFreeList ){
58234       int n = get4byte(&pOvflData[4]);
58235 #ifndef SQLITE_OMIT_AUTOVACUUM
58236       if( pCheck->pBt->autoVacuum ){
58237         checkPtrmap(pCheck, iPage, PTRMAP_FREEPAGE, 0, zContext);
58238       }
58239 #endif
58240       if( n>(int)pCheck->pBt->usableSize/4-2 ){
58241         checkAppendMsg(pCheck, zContext,
58242            "freelist leaf count too big on page %d", iPage);
58243         N--;
58244       }else{
58245         for(i=0; i<n; i++){
58246           Pgno iFreePage = get4byte(&pOvflData[8+i*4]);
58247 #ifndef SQLITE_OMIT_AUTOVACUUM
58248           if( pCheck->pBt->autoVacuum ){
58249             checkPtrmap(pCheck, iFreePage, PTRMAP_FREEPAGE, 0, zContext);
58250           }
58251 #endif
58252           checkRef(pCheck, iFreePage, zContext);
58253         }
58254         N -= n;
58255       }
58256     }
58257 #ifndef SQLITE_OMIT_AUTOVACUUM
58258     else{
58259       /* If this database supports auto-vacuum and iPage is not the last
58260       ** page in this overflow list, check that the pointer-map entry for
58261       ** the following page matches iPage.
58262       */
58263       if( pCheck->pBt->autoVacuum && N>0 ){
58264         i = get4byte(pOvflData);
58265         checkPtrmap(pCheck, i, PTRMAP_OVERFLOW2, iPage, zContext);
58266       }
58267     }
58268 #endif
58269     iPage = get4byte(pOvflData);
58270     sqlite3PagerUnref(pOvflPage);
58271   }
58272 }
58273 #endif /* SQLITE_OMIT_INTEGRITY_CHECK */
58274 
58275 #ifndef SQLITE_OMIT_INTEGRITY_CHECK
58276 /*
58277 ** Do various sanity checks on a single page of a tree.  Return
58278 ** the tree depth.  Root pages return 0.  Parents of root pages
58279 ** return 1, and so forth.
58280 ** 
58281 ** These checks are done:
58282 **
58283 **      1.  Make sure that cells and freeblocks do not overlap
58284 **          but combine to completely cover the page.
58285 **  NO  2.  Make sure cell keys are in order.
58286 **  NO  3.  Make sure no key is less than or equal to zLowerBound.
58287 **  NO  4.  Make sure no key is greater than or equal to zUpperBound.
58288 **      5.  Check the integrity of overflow pages.
58289 **      6.  Recursively call checkTreePage on all children.
58290 **      7.  Verify that the depth of all children is the same.
58291 **      8.  Make sure this page is at least 33% full or else it is
58292 **          the root of the tree.
58293 */
58294 static int checkTreePage(
58295   IntegrityCk *pCheck,  /* Context for the sanity check */
58296   int iPage,            /* Page number of the page to check */
58297   char *zParentContext, /* Parent context */
58298   i64 *pnParentMinKey, 
58299   i64 *pnParentMaxKey
58300 ){
58301   MemPage *pPage;
58302   int i, rc, depth, d2, pgno, cnt;
58303   int hdr, cellStart;
58304   int nCell;
58305   u8 *data;
58306   BtShared *pBt;
58307   int usableSize;
58308   char zContext[100];
58309   char *hit = 0;
58310   i64 nMinKey = 0;
58311   i64 nMaxKey = 0;
58312 
58313   sqlite3_snprintf(sizeof(zContext), zContext, "Page %d: ", iPage);
58314 
58315   /* Check that the page exists
58316   */
58317   pBt = pCheck->pBt;
58318   usableSize = pBt->usableSize;
58319   if( iPage==0 ) return 0;
58320   if( checkRef(pCheck, iPage, zParentContext) ) return 0;
58321   if( (rc = btreeGetPage(pBt, (Pgno)iPage, &pPage, 0))!=0 ){
58322     checkAppendMsg(pCheck, zContext,
58323        "unable to get the page. error code=%d", rc);
58324     return 0;
58325   }
58326 
58327   /* Clear MemPage.isInit to make sure the corruption detection code in
58328   ** btreeInitPage() is executed.  */
58329   pPage->isInit = 0;
58330   if( (rc = btreeInitPage(pPage))!=0 ){
58331     assert( rc==SQLITE_CORRUPT );  /* The only possible error from InitPage */
58332     checkAppendMsg(pCheck, zContext, 
58333                    "btreeInitPage() returns error code %d", rc);
58334     releasePage(pPage);
58335     return 0;
58336   }
58337 
58338   /* Check out all the cells.
58339   */
58340   depth = 0;
58341   for(i=0; i<pPage->nCell && pCheck->mxErr; i++){
58342     u8 *pCell;
58343     u32 sz;
58344     CellInfo info;
58345 
58346     /* Check payload overflow pages
58347     */
58348     sqlite3_snprintf(sizeof(zContext), zContext,
58349              "On tree page %d cell %d: ", iPage, i);
58350     pCell = findCell(pPage,i);
58351     btreeParseCellPtr(pPage, pCell, &info);
58352     sz = info.nData;
58353     if( !pPage->intKey ) sz += (int)info.nKey;
58354     /* For intKey pages, check that the keys are in order.
58355     */
58356     else if( i==0 ) nMinKey = nMaxKey = info.nKey;
58357     else{
58358       if( info.nKey <= nMaxKey ){
58359         checkAppendMsg(pCheck, zContext, 
58360             "Rowid %lld out of order (previous was %lld)", info.nKey, nMaxKey);
58361       }
58362       nMaxKey = info.nKey;
58363     }
58364     assert( sz==info.nPayload );
58365     if( (sz>info.nLocal) 
58366      && (&pCell[info.iOverflow]<=&pPage->aData[pBt->usableSize])
58367     ){
58368       int nPage = (sz - info.nLocal + usableSize - 5)/(usableSize - 4);
58369       Pgno pgnoOvfl = get4byte(&pCell[info.iOverflow]);
58370 #ifndef SQLITE_OMIT_AUTOVACUUM
58371       if( pBt->autoVacuum ){
58372         checkPtrmap(pCheck, pgnoOvfl, PTRMAP_OVERFLOW1, iPage, zContext);
58373       }
58374 #endif
58375       checkList(pCheck, 0, pgnoOvfl, nPage, zContext);
58376     }
58377 
58378     /* Check sanity of left child page.
58379     */
58380     if( !pPage->leaf ){
58381       pgno = get4byte(pCell);
58382 #ifndef SQLITE_OMIT_AUTOVACUUM
58383       if( pBt->autoVacuum ){
58384         checkPtrmap(pCheck, pgno, PTRMAP_BTREE, iPage, zContext);
58385       }
58386 #endif
58387       d2 = checkTreePage(pCheck, pgno, zContext, &nMinKey, i==0 ? NULL : &nMaxKey);
58388       if( i>0 && d2!=depth ){
58389         checkAppendMsg(pCheck, zContext, "Child page depth differs");
58390       }
58391       depth = d2;
58392     }
58393   }
58394 
58395   if( !pPage->leaf ){
58396     pgno = get4byte(&pPage->aData[pPage->hdrOffset+8]);
58397     sqlite3_snprintf(sizeof(zContext), zContext, 
58398                      "On page %d at right child: ", iPage);
58399 #ifndef SQLITE_OMIT_AUTOVACUUM
58400     if( pBt->autoVacuum ){
58401       checkPtrmap(pCheck, pgno, PTRMAP_BTREE, iPage, zContext);
58402     }
58403 #endif
58404     checkTreePage(pCheck, pgno, zContext, NULL, !pPage->nCell ? NULL : &nMaxKey);
58405   }
58406  
58407   /* For intKey leaf pages, check that the min/max keys are in order
58408   ** with any left/parent/right pages.
58409   */
58410   if( pPage->leaf && pPage->intKey ){
58411     /* if we are a left child page */
58412     if( pnParentMinKey ){
58413       /* if we are the left most child page */
58414       if( !pnParentMaxKey ){
58415         if( nMaxKey > *pnParentMinKey ){
58416           checkAppendMsg(pCheck, zContext, 
58417               "Rowid %lld out of order (max larger than parent min of %lld)",
58418               nMaxKey, *pnParentMinKey);
58419         }
58420       }else{
58421         if( nMinKey <= *pnParentMinKey ){
58422           checkAppendMsg(pCheck, zContext, 
58423               "Rowid %lld out of order (min less than parent min of %lld)",
58424               nMinKey, *pnParentMinKey);
58425         }
58426         if( nMaxKey > *pnParentMaxKey ){
58427           checkAppendMsg(pCheck, zContext, 
58428               "Rowid %lld out of order (max larger than parent max of %lld)",
58429               nMaxKey, *pnParentMaxKey);
58430         }
58431         *pnParentMinKey = nMaxKey;
58432       }
58433     /* else if we're a right child page */
58434     } else if( pnParentMaxKey ){
58435       if( nMinKey <= *pnParentMaxKey ){
58436         checkAppendMsg(pCheck, zContext, 
58437             "Rowid %lld out of order (min less than parent max of %lld)",
58438             nMinKey, *pnParentMaxKey);
58439       }
58440     }
58441   }
58442 
58443   /* Check for complete coverage of the page
58444   */
58445   data = pPage->aData;
58446   hdr = pPage->hdrOffset;
58447   hit = sqlite3PageMalloc( pBt->pageSize );
58448   if( hit==0 ){
58449     pCheck->mallocFailed = 1;
58450   }else{
58451     int contentOffset = get2byteNotZero(&data[hdr+5]);
58452     assert( contentOffset<=usableSize );  /* Enforced by btreeInitPage() */
58453     memset(hit+contentOffset, 0, usableSize-contentOffset);
58454     memset(hit, 1, contentOffset);
58455     nCell = get2byte(&data[hdr+3]);
58456     cellStart = hdr + 12 - 4*pPage->leaf;
58457     for(i=0; i<nCell; i++){
58458       int pc = get2byte(&data[cellStart+i*2]);
58459       u32 size = 65536;
58460       int j;
58461       if( pc<=usableSize-4 ){
58462         size = cellSizePtr(pPage, &data[pc]);
58463       }
58464       if( (int)(pc+size-1)>=usableSize ){
58465         checkAppendMsg(pCheck, 0, 
58466             "Corruption detected in cell %d on page %d",i,iPage);
58467       }else{
58468         for(j=pc+size-1; j>=pc; j--) hit[j]++;
58469       }
58470     }
58471     i = get2byte(&data[hdr+1]);
58472     while( i>0 ){
58473       int size, j;
58474       assert( i<=usableSize-4 );     /* Enforced by btreeInitPage() */
58475       size = get2byte(&data[i+2]);
58476       assert( i+size<=usableSize );  /* Enforced by btreeInitPage() */
58477       for(j=i+size-1; j>=i; j--) hit[j]++;
58478       j = get2byte(&data[i]);
58479       assert( j==0 || j>i+size );  /* Enforced by btreeInitPage() */
58480       assert( j<=usableSize-4 );   /* Enforced by btreeInitPage() */
58481       i = j;
58482     }
58483     for(i=cnt=0; i<usableSize; i++){
58484       if( hit[i]==0 ){
58485         cnt++;
58486       }else if( hit[i]>1 ){
58487         checkAppendMsg(pCheck, 0,
58488           "Multiple uses for byte %d of page %d", i, iPage);
58489         break;
58490       }
58491     }
58492     if( cnt!=data[hdr+7] ){
58493       checkAppendMsg(pCheck, 0, 
58494           "Fragmentation of %d bytes reported as %d on page %d",
58495           cnt, data[hdr+7], iPage);
58496     }
58497   }
58498   sqlite3PageFree(hit);
58499   releasePage(pPage);
58500   return depth+1;
58501 }
58502 #endif /* SQLITE_OMIT_INTEGRITY_CHECK */
58503 
58504 #ifndef SQLITE_OMIT_INTEGRITY_CHECK
58505 /*
58506 ** This routine does a complete check of the given BTree file.  aRoot[] is
58507 ** an array of pages numbers were each page number is the root page of
58508 ** a table.  nRoot is the number of entries in aRoot.
58509 **
58510 ** A read-only or read-write transaction must be opened before calling
58511 ** this function.
58512 **
58513 ** Write the number of error seen in *pnErr.  Except for some memory
58514 ** allocation errors,  an error message held in memory obtained from
58515 ** malloc is returned if *pnErr is non-zero.  If *pnErr==0 then NULL is
58516 ** returned.  If a memory allocation error occurs, NULL is returned.
58517 */
58518 SQLITE_PRIVATE char *sqlite3BtreeIntegrityCheck(
58519   Btree *p,     /* The btree to be checked */
58520   int *aRoot,   /* An array of root pages numbers for individual trees */
58521   int nRoot,    /* Number of entries in aRoot[] */
58522   int mxErr,    /* Stop reporting errors after this many */
58523   int *pnErr    /* Write number of errors seen to this variable */
58524 ){
58525   Pgno i;
58526   int nRef;
58527   IntegrityCk sCheck;
58528   BtShared *pBt = p->pBt;
58529   char zErr[100];
58530 
58531   sqlite3BtreeEnter(p);
58532   assert( p->inTrans>TRANS_NONE && pBt->inTransaction>TRANS_NONE );
58533   nRef = sqlite3PagerRefcount(pBt->pPager);
58534   sCheck.pBt = pBt;
58535   sCheck.pPager = pBt->pPager;
58536   sCheck.nPage = btreePagecount(sCheck.pBt);
58537   sCheck.mxErr = mxErr;
58538   sCheck.nErr = 0;
58539   sCheck.mallocFailed = 0;
58540   *pnErr = 0;
58541   if( sCheck.nPage==0 ){
58542     sqlite3BtreeLeave(p);
58543     return 0;
58544   }
58545 
58546   sCheck.aPgRef = sqlite3MallocZero((sCheck.nPage / 8)+ 1);
58547   if( !sCheck.aPgRef ){
58548     *pnErr = 1;
58549     sqlite3BtreeLeave(p);
58550     return 0;
58551   }
58552   i = PENDING_BYTE_PAGE(pBt);
58553   if( i<=sCheck.nPage ) setPageReferenced(&sCheck, i);
58554   sqlite3StrAccumInit(&sCheck.errMsg, zErr, sizeof(zErr), SQLITE_MAX_LENGTH);
58555   sCheck.errMsg.useMalloc = 2;
58556 
58557   /* Check the integrity of the freelist
58558   */
58559   checkList(&sCheck, 1, get4byte(&pBt->pPage1->aData[32]),
58560             get4byte(&pBt->pPage1->aData[36]), "Main freelist: ");
58561 
58562   /* Check all the tables.
58563   */
58564   for(i=0; (int)i<nRoot && sCheck.mxErr; i++){
58565     if( aRoot[i]==0 ) continue;
58566 #ifndef SQLITE_OMIT_AUTOVACUUM
58567     if( pBt->autoVacuum && aRoot[i]>1 ){
58568       checkPtrmap(&sCheck, aRoot[i], PTRMAP_ROOTPAGE, 0, 0);
58569     }
58570 #endif
58571     checkTreePage(&sCheck, aRoot[i], "List of tree roots: ", NULL, NULL);
58572   }
58573 
58574   /* Make sure every page in the file is referenced
58575   */
58576   for(i=1; i<=sCheck.nPage && sCheck.mxErr; i++){
58577 #ifdef SQLITE_OMIT_AUTOVACUUM
58578     if( getPageReferenced(&sCheck, i)==0 ){
58579       checkAppendMsg(&sCheck, 0, "Page %d is never used", i);
58580     }
58581 #else
58582     /* If the database supports auto-vacuum, make sure no tables contain
58583     ** references to pointer-map pages.
58584     */
58585     if( getPageReferenced(&sCheck, i)==0 && 
58586        (PTRMAP_PAGENO(pBt, i)!=i || !pBt->autoVacuum) ){
58587       checkAppendMsg(&sCheck, 0, "Page %d is never used", i);
58588     }
58589     if( getPageReferenced(&sCheck, i)!=0 && 
58590        (PTRMAP_PAGENO(pBt, i)==i && pBt->autoVacuum) ){
58591       checkAppendMsg(&sCheck, 0, "Pointer map page %d is referenced", i);
58592     }
58593 #endif
58594   }
58595 
58596   /* Make sure this analysis did not leave any unref() pages.
58597   ** This is an internal consistency check; an integrity check
58598   ** of the integrity check.
58599   */
58600   if( NEVER(nRef != sqlite3PagerRefcount(pBt->pPager)) ){
58601     checkAppendMsg(&sCheck, 0, 
58602       "Outstanding page count goes from %d to %d during this analysis",
58603       nRef, sqlite3PagerRefcount(pBt->pPager)
58604     );
58605   }
58606 
58607   /* Clean  up and report errors.
58608   */
58609   sqlite3BtreeLeave(p);
58610   sqlite3_free(sCheck.aPgRef);
58611   if( sCheck.mallocFailed ){
58612     sqlite3StrAccumReset(&sCheck.errMsg);
58613     *pnErr = sCheck.nErr+1;
58614     return 0;
58615   }
58616   *pnErr = sCheck.nErr;
58617   if( sCheck.nErr==0 ) sqlite3StrAccumReset(&sCheck.errMsg);
58618   return sqlite3StrAccumFinish(&sCheck.errMsg);
58619 }
58620 #endif /* SQLITE_OMIT_INTEGRITY_CHECK */
58621 
58622 /*
58623 ** Return the full pathname of the underlying database file.  Return
58624 ** an empty string if the database is in-memory or a TEMP database.
58625 **
58626 ** The pager filename is invariant as long as the pager is
58627 ** open so it is safe to access without the BtShared mutex.
58628 */
58629 SQLITE_PRIVATE const char *sqlite3BtreeGetFilename(Btree *p){
58630   assert( p->pBt->pPager!=0 );
58631   return sqlite3PagerFilename(p->pBt->pPager, 1);
58632 }
58633 
58634 /*
58635 ** Return the pathname of the journal file for this database. The return
58636 ** value of this routine is the same regardless of whether the journal file
58637 ** has been created or not.
58638 **
58639 ** The pager journal filename is invariant as long as the pager is
58640 ** open so it is safe to access without the BtShared mutex.
58641 */
58642 SQLITE_PRIVATE const char *sqlite3BtreeGetJournalname(Btree *p){
58643   assert( p->pBt->pPager!=0 );
58644   return sqlite3PagerJournalname(p->pBt->pPager);
58645 }
58646 
58647 /*
58648 ** Return non-zero if a transaction is active.
58649 */
58650 SQLITE_PRIVATE int sqlite3BtreeIsInTrans(Btree *p){
58651   assert( p==0 || sqlite3_mutex_held(p->db->mutex) );
58652   return (p && (p->inTrans==TRANS_WRITE));
58653 }
58654 
58655 #ifndef SQLITE_OMIT_WAL
58656 /*
58657 ** Run a checkpoint on the Btree passed as the first argument.
58658 **
58659 ** Return SQLITE_LOCKED if this or any other connection has an open 
58660 ** transaction on the shared-cache the argument Btree is connected to.
58661 **
58662 ** Parameter eMode is one of SQLITE_CHECKPOINT_PASSIVE, FULL or RESTART.
58663 */
58664 SQLITE_PRIVATE int sqlite3BtreeCheckpoint(Btree *p, int eMode, int *pnLog, int *pnCkpt){
58665   int rc = SQLITE_OK;
58666   if( p ){
58667     BtShared *pBt = p->pBt;
58668     sqlite3BtreeEnter(p);
58669     if( pBt->inTransaction!=TRANS_NONE ){
58670       rc = SQLITE_LOCKED;
58671     }else{
58672       rc = sqlite3PagerCheckpoint(pBt->pPager, eMode, pnLog, pnCkpt);
58673     }
58674     sqlite3BtreeLeave(p);
58675   }
58676   return rc;
58677 }
58678 #endif
58679 
58680 /*
58681 ** Return non-zero if a read (or write) transaction is active.
58682 */
58683 SQLITE_PRIVATE int sqlite3BtreeIsInReadTrans(Btree *p){
58684   assert( p );
58685   assert( sqlite3_mutex_held(p->db->mutex) );
58686   return p->inTrans!=TRANS_NONE;
58687 }
58688 
58689 SQLITE_PRIVATE int sqlite3BtreeIsInBackup(Btree *p){
58690   assert( p );
58691   assert( sqlite3_mutex_held(p->db->mutex) );
58692   return p->nBackup!=0;
58693 }
58694 
58695 /*
58696 ** This function returns a pointer to a blob of memory associated with
58697 ** a single shared-btree. The memory is used by client code for its own
58698 ** purposes (for example, to store a high-level schema associated with 
58699 ** the shared-btree). The btree layer manages reference counting issues.
58700 **
58701 ** The first time this is called on a shared-btree, nBytes bytes of memory
58702 ** are allocated, zeroed, and returned to the caller. For each subsequent 
58703 ** call the nBytes parameter is ignored and a pointer to the same blob
58704 ** of memory returned. 
58705 **
58706 ** If the nBytes parameter is 0 and the blob of memory has not yet been
58707 ** allocated, a null pointer is returned. If the blob has already been
58708 ** allocated, it is returned as normal.
58709 **
58710 ** Just before the shared-btree is closed, the function passed as the 
58711 ** xFree argument when the memory allocation was made is invoked on the 
58712 ** blob of allocated memory. The xFree function should not call sqlite3_free()
58713 ** on the memory, the btree layer does that.
58714 */
58715 SQLITE_PRIVATE void *sqlite3BtreeSchema(Btree *p, int nBytes, void(*xFree)(void *)){
58716   BtShared *pBt = p->pBt;
58717   sqlite3BtreeEnter(p);
58718   if( !pBt->pSchema && nBytes ){
58719     pBt->pSchema = sqlite3DbMallocZero(0, nBytes);
58720     pBt->xFreeSchema = xFree;
58721   }
58722   sqlite3BtreeLeave(p);
58723   return pBt->pSchema;
58724 }
58725 
58726 /*
58727 ** Return SQLITE_LOCKED_SHAREDCACHE if another user of the same shared 
58728 ** btree as the argument handle holds an exclusive lock on the 
58729 ** sqlite_master table. Otherwise SQLITE_OK.
58730 */
58731 SQLITE_PRIVATE int sqlite3BtreeSchemaLocked(Btree *p){
58732   int rc;
58733   assert( sqlite3_mutex_held(p->db->mutex) );
58734   sqlite3BtreeEnter(p);
58735   rc = querySharedCacheTableLock(p, MASTER_ROOT, READ_LOCK);
58736   assert( rc==SQLITE_OK || rc==SQLITE_LOCKED_SHAREDCACHE );
58737   sqlite3BtreeLeave(p);
58738   return rc;
58739 }
58740 
58741 
58742 #ifndef SQLITE_OMIT_SHARED_CACHE
58743 /*
58744 ** Obtain a lock on the table whose root page is iTab.  The
58745 ** lock is a write lock if isWritelock is true or a read lock
58746 ** if it is false.
58747 */
58748 SQLITE_PRIVATE int sqlite3BtreeLockTable(Btree *p, int iTab, u8 isWriteLock){
58749   int rc = SQLITE_OK;
58750   assert( p->inTrans!=TRANS_NONE );
58751   if( p->sharable ){
58752     u8 lockType = READ_LOCK + isWriteLock;
58753     assert( READ_LOCK+1==WRITE_LOCK );
58754     assert( isWriteLock==0 || isWriteLock==1 );
58755 
58756     sqlite3BtreeEnter(p);
58757     rc = querySharedCacheTableLock(p, iTab, lockType);
58758     if( rc==SQLITE_OK ){
58759       rc = setSharedCacheTableLock(p, iTab, lockType);
58760     }
58761     sqlite3BtreeLeave(p);
58762   }
58763   return rc;
58764 }
58765 #endif
58766 
58767 #ifndef SQLITE_OMIT_INCRBLOB
58768 /*
58769 ** Argument pCsr must be a cursor opened for writing on an 
58770 ** INTKEY table currently pointing at a valid table entry. 
58771 ** This function modifies the data stored as part of that entry.
58772 **
58773 ** Only the data content may only be modified, it is not possible to 
58774 ** change the length of the data stored. If this function is called with
58775 ** parameters that attempt to write past the end of the existing data,
58776 ** no modifications are made and SQLITE_CORRUPT is returned.
58777 */
58778 SQLITE_PRIVATE int sqlite3BtreePutData(BtCursor *pCsr, u32 offset, u32 amt, void *z){
58779   int rc;
58780   assert( cursorHoldsMutex(pCsr) );
58781   assert( sqlite3_mutex_held(pCsr->pBtree->db->mutex) );
58782   assert( pCsr->isIncrblobHandle );
58783 
58784   rc = restoreCursorPosition(pCsr);
58785   if( rc!=SQLITE_OK ){
58786     return rc;
58787   }
58788   assert( pCsr->eState!=CURSOR_REQUIRESEEK );
58789   if( pCsr->eState!=CURSOR_VALID ){
58790     return SQLITE_ABORT;
58791   }
58792 
58793   /* Save the positions of all other cursors open on this table. This is
58794   ** required in case any of them are holding references to an xFetch
58795   ** version of the b-tree page modified by the accessPayload call below.
58796   **
58797   ** Note that pCsr must be open on a BTREE_INTKEY table and saveCursorPosition()
58798   ** and hence saveAllCursors() cannot fail on a BTREE_INTKEY table, hence
58799   ** saveAllCursors can only return SQLITE_OK.
58800   */
58801   VVA_ONLY(rc =) saveAllCursors(pCsr->pBt, pCsr->pgnoRoot, pCsr);
58802   assert( rc==SQLITE_OK );
58803 
58804   /* Check some assumptions: 
58805   **   (a) the cursor is open for writing,
58806   **   (b) there is a read/write transaction open,
58807   **   (c) the connection holds a write-lock on the table (if required),
58808   **   (d) there are no conflicting read-locks, and
58809   **   (e) the cursor points at a valid row of an intKey table.
58810   */
58811   if( !pCsr->wrFlag ){
58812     return SQLITE_READONLY;
58813   }
58814   assert( (pCsr->pBt->btsFlags & BTS_READ_ONLY)==0
58815               && pCsr->pBt->inTransaction==TRANS_WRITE );
58816   assert( hasSharedCacheTableLock(pCsr->pBtree, pCsr->pgnoRoot, 0, 2) );
58817   assert( !hasReadConflicts(pCsr->pBtree, pCsr->pgnoRoot) );
58818   assert( pCsr->apPage[pCsr->iPage]->intKey );
58819 
58820   return accessPayload(pCsr, offset, amt, (unsigned char *)z, 1);
58821 }
58822 
58823 /* 
58824 ** Set a flag on this cursor to cache the locations of pages from the 
58825 ** overflow list for the current row. This is used by cursors opened
58826 ** for incremental blob IO only.
58827 **
58828 ** This function sets a flag only. The actual page location cache
58829 ** (stored in BtCursor.aOverflow[]) is allocated and used by function
58830 ** accessPayload() (the worker function for sqlite3BtreeData() and
58831 ** sqlite3BtreePutData()).
58832 */
58833 SQLITE_PRIVATE void sqlite3BtreeCacheOverflow(BtCursor *pCur){
58834   assert( cursorHoldsMutex(pCur) );
58835   assert( sqlite3_mutex_held(pCur->pBtree->db->mutex) );
58836   invalidateOverflowCache(pCur);
58837   pCur->isIncrblobHandle = 1;
58838 }
58839 #endif
58840 
58841 /*
58842 ** Set both the "read version" (single byte at byte offset 18) and 
58843 ** "write version" (single byte at byte offset 19) fields in the database
58844 ** header to iVersion.
58845 */
58846 SQLITE_PRIVATE int sqlite3BtreeSetVersion(Btree *pBtree, int iVersion){
58847   BtShared *pBt = pBtree->pBt;
58848   int rc;                         /* Return code */
58849  
58850   assert( iVersion==1 || iVersion==2 );
58851 
58852   /* If setting the version fields to 1, do not automatically open the
58853   ** WAL connection, even if the version fields are currently set to 2.
58854   */
58855   pBt->btsFlags &= ~BTS_NO_WAL;
58856   if( iVersion==1 ) pBt->btsFlags |= BTS_NO_WAL;
58857 
58858   rc = sqlite3BtreeBeginTrans(pBtree, 0);
58859   if( rc==SQLITE_OK ){
58860     u8 *aData = pBt->pPage1->aData;
58861     if( aData[18]!=(u8)iVersion || aData[19]!=(u8)iVersion ){
58862       rc = sqlite3BtreeBeginTrans(pBtree, 2);
58863       if( rc==SQLITE_OK ){
58864         rc = sqlite3PagerWrite(pBt->pPage1->pDbPage);
58865         if( rc==SQLITE_OK ){
58866           aData[18] = (u8)iVersion;
58867           aData[19] = (u8)iVersion;
58868         }
58869       }
58870     }
58871   }
58872 
58873   pBt->btsFlags &= ~BTS_NO_WAL;
58874   return rc;
58875 }
58876 
58877 /*
58878 ** set the mask of hint flags for cursor pCsr. Currently the only valid
58879 ** values are 0 and BTREE_BULKLOAD.
58880 */
58881 SQLITE_PRIVATE void sqlite3BtreeCursorHints(BtCursor *pCsr, unsigned int mask){
58882   assert( mask==BTREE_BULKLOAD || mask==0 );
58883   pCsr->hints = mask;
58884 }
58885 
58886 /************** End of btree.c ***********************************************/
58887 /************** Begin file backup.c ******************************************/
58888 /*
58889 ** 2009 January 28
58890 **
58891 ** The author disclaims copyright to this source code.  In place of
58892 ** a legal notice, here is a blessing:
58893 **
58894 **    May you do good and not evil.
58895 **    May you find forgiveness for yourself and forgive others.
58896 **    May you share freely, never taking more than you give.
58897 **
58898 *************************************************************************
58899 ** This file contains the implementation of the sqlite3_backup_XXX() 
58900 ** API functions and the related features.
58901 */
58902 
58903 /*
58904 ** Structure allocated for each backup operation.
58905 */
58906 struct sqlite3_backup {
58907   sqlite3* pDestDb;        /* Destination database handle */
58908   Btree *pDest;            /* Destination b-tree file */
58909   u32 iDestSchema;         /* Original schema cookie in destination */
58910   int bDestLocked;         /* True once a write-transaction is open on pDest */
58911 
58912   Pgno iNext;              /* Page number of the next source page to copy */
58913   sqlite3* pSrcDb;         /* Source database handle */
58914   Btree *pSrc;             /* Source b-tree file */
58915 
58916   int rc;                  /* Backup process error code */
58917 
58918   /* These two variables are set by every call to backup_step(). They are
58919   ** read by calls to backup_remaining() and backup_pagecount().
58920   */
58921   Pgno nRemaining;         /* Number of pages left to copy */
58922   Pgno nPagecount;         /* Total number of pages to copy */
58923 
58924   int isAttached;          /* True once backup has been registered with pager */
58925   sqlite3_backup *pNext;   /* Next backup associated with source pager */
58926 };
58927 
58928 /*
58929 ** THREAD SAFETY NOTES:
58930 **
58931 **   Once it has been created using backup_init(), a single sqlite3_backup
58932 **   structure may be accessed via two groups of thread-safe entry points:
58933 **
58934 **     * Via the sqlite3_backup_XXX() API function backup_step() and 
58935 **       backup_finish(). Both these functions obtain the source database
58936 **       handle mutex and the mutex associated with the source BtShared 
58937 **       structure, in that order.
58938 **
58939 **     * Via the BackupUpdate() and BackupRestart() functions, which are
58940 **       invoked by the pager layer to report various state changes in
58941 **       the page cache associated with the source database. The mutex
58942 **       associated with the source database BtShared structure will always 
58943 **       be held when either of these functions are invoked.
58944 **
58945 **   The other sqlite3_backup_XXX() API functions, backup_remaining() and
58946 **   backup_pagecount() are not thread-safe functions. If they are called
58947 **   while some other thread is calling backup_step() or backup_finish(),
58948 **   the values returned may be invalid. There is no way for a call to
58949 **   BackupUpdate() or BackupRestart() to interfere with backup_remaining()
58950 **   or backup_pagecount().
58951 **
58952 **   Depending on the SQLite configuration, the database handles and/or
58953 **   the Btree objects may have their own mutexes that require locking.
58954 **   Non-sharable Btrees (in-memory databases for example), do not have
58955 **   associated mutexes.
58956 */
58957 
58958 /*
58959 ** Return a pointer corresponding to database zDb (i.e. "main", "temp")
58960 ** in connection handle pDb. If such a database cannot be found, return
58961 ** a NULL pointer and write an error message to pErrorDb.
58962 **
58963 ** If the "temp" database is requested, it may need to be opened by this 
58964 ** function. If an error occurs while doing so, return 0 and write an 
58965 ** error message to pErrorDb.
58966 */
58967 static Btree *findBtree(sqlite3 *pErrorDb, sqlite3 *pDb, const char *zDb){
58968   int i = sqlite3FindDbName(pDb, zDb);
58969 
58970   if( i==1 ){
58971     Parse *pParse;
58972     int rc = 0;
58973     pParse = sqlite3StackAllocZero(pErrorDb, sizeof(*pParse));
58974     if( pParse==0 ){
58975       sqlite3Error(pErrorDb, SQLITE_NOMEM, "out of memory");
58976       rc = SQLITE_NOMEM;
58977     }else{
58978       pParse->db = pDb;
58979       if( sqlite3OpenTempDatabase(pParse) ){
58980         sqlite3Error(pErrorDb, pParse->rc, "%s", pParse->zErrMsg);
58981         rc = SQLITE_ERROR;
58982       }
58983       sqlite3DbFree(pErrorDb, pParse->zErrMsg);
58984       sqlite3ParserReset(pParse);
58985       sqlite3StackFree(pErrorDb, pParse);
58986     }
58987     if( rc ){
58988       return 0;
58989     }
58990   }
58991 
58992   if( i<0 ){
58993     sqlite3Error(pErrorDb, SQLITE_ERROR, "unknown database %s", zDb);
58994     return 0;
58995   }
58996 
58997   return pDb->aDb[i].pBt;
58998 }
58999 
59000 /*
59001 ** Attempt to set the page size of the destination to match the page size
59002 ** of the source.
59003 */
59004 static int setDestPgsz(sqlite3_backup *p){
59005   int rc;
59006   rc = sqlite3BtreeSetPageSize(p->pDest,sqlite3BtreeGetPageSize(p->pSrc),-1,0);
59007   return rc;
59008 }
59009 
59010 /*
59011 ** Create an sqlite3_backup process to copy the contents of zSrcDb from
59012 ** connection handle pSrcDb to zDestDb in pDestDb. If successful, return
59013 ** a pointer to the new sqlite3_backup object.
59014 **
59015 ** If an error occurs, NULL is returned and an error code and error message
59016 ** stored in database handle pDestDb.
59017 */
59018 SQLITE_API sqlite3_backup *sqlite3_backup_init(
59019   sqlite3* pDestDb,                     /* Database to write to */
59020   const char *zDestDb,                  /* Name of database within pDestDb */
59021   sqlite3* pSrcDb,                      /* Database connection to read from */
59022   const char *zSrcDb                    /* Name of database within pSrcDb */
59023 ){
59024   sqlite3_backup *p;                    /* Value to return */
59025 
59026   /* Lock the source database handle. The destination database
59027   ** handle is not locked in this routine, but it is locked in
59028   ** sqlite3_backup_step(). The user is required to ensure that no
59029   ** other thread accesses the destination handle for the duration
59030   ** of the backup operation.  Any attempt to use the destination
59031   ** database connection while a backup is in progress may cause
59032   ** a malfunction or a deadlock.
59033   */
59034   sqlite3_mutex_enter(pSrcDb->mutex);
59035   sqlite3_mutex_enter(pDestDb->mutex);
59036 
59037   if( pSrcDb==pDestDb ){
59038     sqlite3Error(
59039         pDestDb, SQLITE_ERROR, "source and destination must be distinct"
59040     );
59041     p = 0;
59042   }else {
59043     /* Allocate space for a new sqlite3_backup object...
59044     ** EVIDENCE-OF: R-64852-21591 The sqlite3_backup object is created by a
59045     ** call to sqlite3_backup_init() and is destroyed by a call to
59046     ** sqlite3_backup_finish(). */
59047     p = (sqlite3_backup *)sqlite3MallocZero(sizeof(sqlite3_backup));
59048     if( !p ){
59049       sqlite3Error(pDestDb, SQLITE_NOMEM, 0);
59050     }
59051   }
59052 
59053   /* If the allocation succeeded, populate the new object. */
59054   if( p ){
59055     p->pSrc = findBtree(pDestDb, pSrcDb, zSrcDb);
59056     p->pDest = findBtree(pDestDb, pDestDb, zDestDb);
59057     p->pDestDb = pDestDb;
59058     p->pSrcDb = pSrcDb;
59059     p->iNext = 1;
59060     p->isAttached = 0;
59061 
59062     if( 0==p->pSrc || 0==p->pDest || setDestPgsz(p)==SQLITE_NOMEM ){
59063       /* One (or both) of the named databases did not exist or an OOM
59064       ** error was hit.  The error has already been written into the
59065       ** pDestDb handle.  All that is left to do here is free the
59066       ** sqlite3_backup structure.
59067       */
59068       sqlite3_free(p);
59069       p = 0;
59070     }
59071   }
59072   if( p ){
59073     p->pSrc->nBackup++;
59074   }
59075 
59076   sqlite3_mutex_leave(pDestDb->mutex);
59077   sqlite3_mutex_leave(pSrcDb->mutex);
59078   return p;
59079 }
59080 
59081 /*
59082 ** Argument rc is an SQLite error code. Return true if this error is 
59083 ** considered fatal if encountered during a backup operation. All errors
59084 ** are considered fatal except for SQLITE_BUSY and SQLITE_LOCKED.
59085 */
59086 static int isFatalError(int rc){
59087   return (rc!=SQLITE_OK && rc!=SQLITE_BUSY && ALWAYS(rc!=SQLITE_LOCKED));
59088 }
59089 
59090 /*
59091 ** Parameter zSrcData points to a buffer containing the data for 
59092 ** page iSrcPg from the source database. Copy this data into the 
59093 ** destination database.
59094 */
59095 static int backupOnePage(
59096   sqlite3_backup *p,              /* Backup handle */
59097   Pgno iSrcPg,                    /* Source database page to backup */
59098   const u8 *zSrcData,             /* Source database page data */
59099   int bUpdate                     /* True for an update, false otherwise */
59100 ){
59101   Pager * const pDestPager = sqlite3BtreePager(p->pDest);
59102   const int nSrcPgsz = sqlite3BtreeGetPageSize(p->pSrc);
59103   int nDestPgsz = sqlite3BtreeGetPageSize(p->pDest);
59104   const int nCopy = MIN(nSrcPgsz, nDestPgsz);
59105   const i64 iEnd = (i64)iSrcPg*(i64)nSrcPgsz;
59106 #ifdef SQLITE_HAS_CODEC
59107   /* Use BtreeGetReserveNoMutex() for the source b-tree, as although it is
59108   ** guaranteed that the shared-mutex is held by this thread, handle
59109   ** p->pSrc may not actually be the owner.  */
59110   int nSrcReserve = sqlite3BtreeGetReserveNoMutex(p->pSrc);
59111   int nDestReserve = sqlite3BtreeGetReserve(p->pDest);
59112 #endif
59113   int rc = SQLITE_OK;
59114   i64 iOff;
59115 
59116   assert( sqlite3BtreeGetReserveNoMutex(p->pSrc)>=0 );
59117   assert( p->bDestLocked );
59118   assert( !isFatalError(p->rc) );
59119   assert( iSrcPg!=PENDING_BYTE_PAGE(p->pSrc->pBt) );
59120   assert( zSrcData );
59121 
59122   /* Catch the case where the destination is an in-memory database and the
59123   ** page sizes of the source and destination differ. 
59124   */
59125   if( nSrcPgsz!=nDestPgsz && sqlite3PagerIsMemdb(pDestPager) ){
59126     rc = SQLITE_READONLY;
59127   }
59128 
59129 #ifdef SQLITE_HAS_CODEC
59130   /* Backup is not possible if the page size of the destination is changing
59131   ** and a codec is in use.
59132   */
59133   if( nSrcPgsz!=nDestPgsz && sqlite3PagerGetCodec(pDestPager)!=0 ){
59134     rc = SQLITE_READONLY;
59135   }
59136 
59137   /* Backup is not possible if the number of bytes of reserve space differ
59138   ** between source and destination.  If there is a difference, try to
59139   ** fix the destination to agree with the source.  If that is not possible,
59140   ** then the backup cannot proceed.
59141   */
59142   if( nSrcReserve!=nDestReserve ){
59143     u32 newPgsz = nSrcPgsz;
59144     rc = sqlite3PagerSetPagesize(pDestPager, &newPgsz, nSrcReserve);
59145     if( rc==SQLITE_OK && newPgsz!=nSrcPgsz ) rc = SQLITE_READONLY;
59146   }
59147 #endif
59148 
59149   /* This loop runs once for each destination page spanned by the source 
59150   ** page. For each iteration, variable iOff is set to the byte offset
59151   ** of the destination page.
59152   */
59153   for(iOff=iEnd-(i64)nSrcPgsz; rc==SQLITE_OK && iOff<iEnd; iOff+=nDestPgsz){
59154     DbPage *pDestPg = 0;
59155     Pgno iDest = (Pgno)(iOff/nDestPgsz)+1;
59156     if( iDest==PENDING_BYTE_PAGE(p->pDest->pBt) ) continue;
59157     if( SQLITE_OK==(rc = sqlite3PagerGet(pDestPager, iDest, &pDestPg))
59158      && SQLITE_OK==(rc = sqlite3PagerWrite(pDestPg))
59159     ){
59160       const u8 *zIn = &zSrcData[iOff%nSrcPgsz];
59161       u8 *zDestData = sqlite3PagerGetData(pDestPg);
59162       u8 *zOut = &zDestData[iOff%nDestPgsz];
59163 
59164       /* Copy the data from the source page into the destination page.
59165       ** Then clear the Btree layer MemPage.isInit flag. Both this module
59166       ** and the pager code use this trick (clearing the first byte
59167       ** of the page 'extra' space to invalidate the Btree layers
59168       ** cached parse of the page). MemPage.isInit is marked 
59169       ** "MUST BE FIRST" for this purpose.
59170       */
59171       memcpy(zOut, zIn, nCopy);
59172       ((u8 *)sqlite3PagerGetExtra(pDestPg))[0] = 0;
59173       if( iOff==0 && bUpdate==0 ){
59174         sqlite3Put4byte(&zOut[28], sqlite3BtreeLastPage(p->pSrc));
59175       }
59176     }
59177     sqlite3PagerUnref(pDestPg);
59178   }
59179 
59180   return rc;
59181 }
59182 
59183 /*
59184 ** If pFile is currently larger than iSize bytes, then truncate it to
59185 ** exactly iSize bytes. If pFile is not larger than iSize bytes, then
59186 ** this function is a no-op.
59187 **
59188 ** Return SQLITE_OK if everything is successful, or an SQLite error 
59189 ** code if an error occurs.
59190 */
59191 static int backupTruncateFile(sqlite3_file *pFile, i64 iSize){
59192   i64 iCurrent;
59193   int rc = sqlite3OsFileSize(pFile, &iCurrent);
59194   if( rc==SQLITE_OK && iCurrent>iSize ){
59195     rc = sqlite3OsTruncate(pFile, iSize);
59196   }
59197   return rc;
59198 }
59199 
59200 /*
59201 ** Register this backup object with the associated source pager for
59202 ** callbacks when pages are changed or the cache invalidated.
59203 */
59204 static void attachBackupObject(sqlite3_backup *p){
59205   sqlite3_backup **pp;
59206   assert( sqlite3BtreeHoldsMutex(p->pSrc) );
59207   pp = sqlite3PagerBackupPtr(sqlite3BtreePager(p->pSrc));
59208   p->pNext = *pp;
59209   *pp = p;
59210   p->isAttached = 1;
59211 }
59212 
59213 /*
59214 ** Copy nPage pages from the source b-tree to the destination.
59215 */
59216 SQLITE_API int sqlite3_backup_step(sqlite3_backup *p, int nPage){
59217   int rc;
59218   int destMode;       /* Destination journal mode */
59219   int pgszSrc = 0;    /* Source page size */
59220   int pgszDest = 0;   /* Destination page size */
59221 
59222   sqlite3_mutex_enter(p->pSrcDb->mutex);
59223   sqlite3BtreeEnter(p->pSrc);
59224   if( p->pDestDb ){
59225     sqlite3_mutex_enter(p->pDestDb->mutex);
59226   }
59227 
59228   rc = p->rc;
59229   if( !isFatalError(rc) ){
59230     Pager * const pSrcPager = sqlite3BtreePager(p->pSrc);     /* Source pager */
59231     Pager * const pDestPager = sqlite3BtreePager(p->pDest);   /* Dest pager */
59232     int ii;                            /* Iterator variable */
59233     int nSrcPage = -1;                 /* Size of source db in pages */
59234     int bCloseTrans = 0;               /* True if src db requires unlocking */
59235 
59236     /* If the source pager is currently in a write-transaction, return
59237     ** SQLITE_BUSY immediately.
59238     */
59239     if( p->pDestDb && p->pSrc->pBt->inTransaction==TRANS_WRITE ){
59240       rc = SQLITE_BUSY;
59241     }else{
59242       rc = SQLITE_OK;
59243     }
59244 
59245     /* Lock the destination database, if it is not locked already. */
59246     if( SQLITE_OK==rc && p->bDestLocked==0
59247      && SQLITE_OK==(rc = sqlite3BtreeBeginTrans(p->pDest, 2)) 
59248     ){
59249       p->bDestLocked = 1;
59250       sqlite3BtreeGetMeta(p->pDest, BTREE_SCHEMA_VERSION, &p->iDestSchema);
59251     }
59252 
59253     /* If there is no open read-transaction on the source database, open
59254     ** one now. If a transaction is opened here, then it will be closed
59255     ** before this function exits.
59256     */
59257     if( rc==SQLITE_OK && 0==sqlite3BtreeIsInReadTrans(p->pSrc) ){
59258       rc = sqlite3BtreeBeginTrans(p->pSrc, 0);
59259       bCloseTrans = 1;
59260     }
59261 
59262     /* Do not allow backup if the destination database is in WAL mode
59263     ** and the page sizes are different between source and destination */
59264     pgszSrc = sqlite3BtreeGetPageSize(p->pSrc);
59265     pgszDest = sqlite3BtreeGetPageSize(p->pDest);
59266     destMode = sqlite3PagerGetJournalMode(sqlite3BtreePager(p->pDest));
59267     if( SQLITE_OK==rc && destMode==PAGER_JOURNALMODE_WAL && pgszSrc!=pgszDest ){
59268       rc = SQLITE_READONLY;
59269     }
59270   
59271     /* Now that there is a read-lock on the source database, query the
59272     ** source pager for the number of pages in the database.
59273     */
59274     nSrcPage = (int)sqlite3BtreeLastPage(p->pSrc);
59275     assert( nSrcPage>=0 );
59276     for(ii=0; (nPage<0 || ii<nPage) && p->iNext<=(Pgno)nSrcPage && !rc; ii++){
59277       const Pgno iSrcPg = p->iNext;                 /* Source page number */
59278       if( iSrcPg!=PENDING_BYTE_PAGE(p->pSrc->pBt) ){
59279         DbPage *pSrcPg;                             /* Source page object */
59280         rc = sqlite3PagerAcquire(pSrcPager, iSrcPg, &pSrcPg,
59281                                  PAGER_GET_READONLY);
59282         if( rc==SQLITE_OK ){
59283           rc = backupOnePage(p, iSrcPg, sqlite3PagerGetData(pSrcPg), 0);
59284           sqlite3PagerUnref(pSrcPg);
59285         }
59286       }
59287       p->iNext++;
59288     }
59289     if( rc==SQLITE_OK ){
59290       p->nPagecount = nSrcPage;
59291       p->nRemaining = nSrcPage+1-p->iNext;
59292       if( p->iNext>(Pgno)nSrcPage ){
59293         rc = SQLITE_DONE;
59294       }else if( !p->isAttached ){
59295         attachBackupObject(p);
59296       }
59297     }
59298   
59299     /* Update the schema version field in the destination database. This
59300     ** is to make sure that the schema-version really does change in
59301     ** the case where the source and destination databases have the
59302     ** same schema version.
59303     */
59304     if( rc==SQLITE_DONE ){
59305       if( nSrcPage==0 ){
59306         rc = sqlite3BtreeNewDb(p->pDest);
59307         nSrcPage = 1;
59308       }
59309       if( rc==SQLITE_OK || rc==SQLITE_DONE ){
59310         rc = sqlite3BtreeUpdateMeta(p->pDest,1,p->iDestSchema+1);
59311       }
59312       if( rc==SQLITE_OK ){
59313         if( p->pDestDb ){
59314           sqlite3ResetAllSchemasOfConnection(p->pDestDb);
59315         }
59316         if( destMode==PAGER_JOURNALMODE_WAL ){
59317           rc = sqlite3BtreeSetVersion(p->pDest, 2);
59318         }
59319       }
59320       if( rc==SQLITE_OK ){
59321         int nDestTruncate;
59322         /* Set nDestTruncate to the final number of pages in the destination
59323         ** database. The complication here is that the destination page
59324         ** size may be different to the source page size. 
59325         **
59326         ** If the source page size is smaller than the destination page size, 
59327         ** round up. In this case the call to sqlite3OsTruncate() below will
59328         ** fix the size of the file. However it is important to call
59329         ** sqlite3PagerTruncateImage() here so that any pages in the 
59330         ** destination file that lie beyond the nDestTruncate page mark are
59331         ** journalled by PagerCommitPhaseOne() before they are destroyed
59332         ** by the file truncation.
59333         */
59334         assert( pgszSrc==sqlite3BtreeGetPageSize(p->pSrc) );
59335         assert( pgszDest==sqlite3BtreeGetPageSize(p->pDest) );
59336         if( pgszSrc<pgszDest ){
59337           int ratio = pgszDest/pgszSrc;
59338           nDestTruncate = (nSrcPage+ratio-1)/ratio;
59339           if( nDestTruncate==(int)PENDING_BYTE_PAGE(p->pDest->pBt) ){
59340             nDestTruncate--;
59341           }
59342         }else{
59343           nDestTruncate = nSrcPage * (pgszSrc/pgszDest);
59344         }
59345         assert( nDestTruncate>0 );
59346 
59347         if( pgszSrc<pgszDest ){
59348           /* If the source page-size is smaller than the destination page-size,
59349           ** two extra things may need to happen:
59350           **
59351           **   * The destination may need to be truncated, and
59352           **
59353           **   * Data stored on the pages immediately following the 
59354           **     pending-byte page in the source database may need to be
59355           **     copied into the destination database.
59356           */
59357           const i64 iSize = (i64)pgszSrc * (i64)nSrcPage;
59358           sqlite3_file * const pFile = sqlite3PagerFile(pDestPager);
59359           Pgno iPg;
59360           int nDstPage;
59361           i64 iOff;
59362           i64 iEnd;
59363 
59364           assert( pFile );
59365           assert( nDestTruncate==0 
59366               || (i64)nDestTruncate*(i64)pgszDest >= iSize || (
59367                 nDestTruncate==(int)(PENDING_BYTE_PAGE(p->pDest->pBt)-1)
59368              && iSize>=PENDING_BYTE && iSize<=PENDING_BYTE+pgszDest
59369           ));
59370 
59371           /* This block ensures that all data required to recreate the original
59372           ** database has been stored in the journal for pDestPager and the
59373           ** journal synced to disk. So at this point we may safely modify
59374           ** the database file in any way, knowing that if a power failure
59375           ** occurs, the original database will be reconstructed from the 
59376           ** journal file.  */
59377           sqlite3PagerPagecount(pDestPager, &nDstPage);
59378           for(iPg=nDestTruncate; rc==SQLITE_OK && iPg<=(Pgno)nDstPage; iPg++){
59379             if( iPg!=PENDING_BYTE_PAGE(p->pDest->pBt) ){
59380               DbPage *pPg;
59381               rc = sqlite3PagerGet(pDestPager, iPg, &pPg);
59382               if( rc==SQLITE_OK ){
59383                 rc = sqlite3PagerWrite(pPg);
59384                 sqlite3PagerUnref(pPg);
59385               }
59386             }
59387           }
59388           if( rc==SQLITE_OK ){
59389             rc = sqlite3PagerCommitPhaseOne(pDestPager, 0, 1);
59390           }
59391 
59392           /* Write the extra pages and truncate the database file as required */
59393           iEnd = MIN(PENDING_BYTE + pgszDest, iSize);
59394           for(
59395             iOff=PENDING_BYTE+pgszSrc; 
59396             rc==SQLITE_OK && iOff<iEnd; 
59397             iOff+=pgszSrc
59398           ){
59399             PgHdr *pSrcPg = 0;
59400             const Pgno iSrcPg = (Pgno)((iOff/pgszSrc)+1);
59401             rc = sqlite3PagerGet(pSrcPager, iSrcPg, &pSrcPg);
59402             if( rc==SQLITE_OK ){
59403               u8 *zData = sqlite3PagerGetData(pSrcPg);
59404               rc = sqlite3OsWrite(pFile, zData, pgszSrc, iOff);
59405             }
59406             sqlite3PagerUnref(pSrcPg);
59407           }
59408           if( rc==SQLITE_OK ){
59409             rc = backupTruncateFile(pFile, iSize);
59410           }
59411 
59412           /* Sync the database file to disk. */
59413           if( rc==SQLITE_OK ){
59414             rc = sqlite3PagerSync(pDestPager);
59415           }
59416         }else{
59417           sqlite3PagerTruncateImage(pDestPager, nDestTruncate);
59418           rc = sqlite3PagerCommitPhaseOne(pDestPager, 0, 0);
59419         }
59420     
59421         /* Finish committing the transaction to the destination database. */
59422         if( SQLITE_OK==rc
59423          && SQLITE_OK==(rc = sqlite3BtreeCommitPhaseTwo(p->pDest, 0))
59424         ){
59425           rc = SQLITE_DONE;
59426         }
59427       }
59428     }
59429   
59430     /* If bCloseTrans is true, then this function opened a read transaction
59431     ** on the source database. Close the read transaction here. There is
59432     ** no need to check the return values of the btree methods here, as
59433     ** "committing" a read-only transaction cannot fail.
59434     */
59435     if( bCloseTrans ){
59436       TESTONLY( int rc2 );
59437       TESTONLY( rc2  = ) sqlite3BtreeCommitPhaseOne(p->pSrc, 0);
59438       TESTONLY( rc2 |= ) sqlite3BtreeCommitPhaseTwo(p->pSrc, 0);
59439       assert( rc2==SQLITE_OK );
59440     }
59441   
59442     if( rc==SQLITE_IOERR_NOMEM ){
59443       rc = SQLITE_NOMEM;
59444     }
59445     p->rc = rc;
59446   }
59447   if( p->pDestDb ){
59448     sqlite3_mutex_leave(p->pDestDb->mutex);
59449   }
59450   sqlite3BtreeLeave(p->pSrc);
59451   sqlite3_mutex_leave(p->pSrcDb->mutex);
59452   return rc;
59453 }
59454 
59455 /*
59456 ** Release all resources associated with an sqlite3_backup* handle.
59457 */
59458 SQLITE_API int sqlite3_backup_finish(sqlite3_backup *p){
59459   sqlite3_backup **pp;                 /* Ptr to head of pagers backup list */
59460   sqlite3 *pSrcDb;                     /* Source database connection */
59461   int rc;                              /* Value to return */
59462 
59463   /* Enter the mutexes */
59464   if( p==0 ) return SQLITE_OK;
59465   pSrcDb = p->pSrcDb;
59466   sqlite3_mutex_enter(pSrcDb->mutex);
59467   sqlite3BtreeEnter(p->pSrc);
59468   if( p->pDestDb ){
59469     sqlite3_mutex_enter(p->pDestDb->mutex);
59470   }
59471 
59472   /* Detach this backup from the source pager. */
59473   if( p->pDestDb ){
59474     p->pSrc->nBackup--;
59475   }
59476   if( p->isAttached ){
59477     pp = sqlite3PagerBackupPtr(sqlite3BtreePager(p->pSrc));
59478     while( *pp!=p ){
59479       pp = &(*pp)->pNext;
59480     }
59481     *pp = p->pNext;
59482   }
59483 
59484   /* If a transaction is still open on the Btree, roll it back. */
59485   sqlite3BtreeRollback(p->pDest, SQLITE_OK);
59486 
59487   /* Set the error code of the destination database handle. */
59488   rc = (p->rc==SQLITE_DONE) ? SQLITE_OK : p->rc;
59489   sqlite3Error(p->pDestDb, rc, 0);
59490 
59491   /* Exit the mutexes and free the backup context structure. */
59492   if( p->pDestDb ){
59493     sqlite3LeaveMutexAndCloseZombie(p->pDestDb);
59494   }
59495   sqlite3BtreeLeave(p->pSrc);
59496   if( p->pDestDb ){
59497     /* EVIDENCE-OF: R-64852-21591 The sqlite3_backup object is created by a
59498     ** call to sqlite3_backup_init() and is destroyed by a call to
59499     ** sqlite3_backup_finish(). */
59500     sqlite3_free(p);
59501   }
59502   sqlite3LeaveMutexAndCloseZombie(pSrcDb);
59503   return rc;
59504 }
59505 
59506 /*
59507 ** Return the number of pages still to be backed up as of the most recent
59508 ** call to sqlite3_backup_step().
59509 */
59510 SQLITE_API int sqlite3_backup_remaining(sqlite3_backup *p){
59511   return p->nRemaining;
59512 }
59513 
59514 /*
59515 ** Return the total number of pages in the source database as of the most 
59516 ** recent call to sqlite3_backup_step().
59517 */
59518 SQLITE_API int sqlite3_backup_pagecount(sqlite3_backup *p){
59519   return p->nPagecount;
59520 }
59521 
59522 /*
59523 ** This function is called after the contents of page iPage of the
59524 ** source database have been modified. If page iPage has already been 
59525 ** copied into the destination database, then the data written to the
59526 ** destination is now invalidated. The destination copy of iPage needs
59527 ** to be updated with the new data before the backup operation is
59528 ** complete.
59529 **
59530 ** It is assumed that the mutex associated with the BtShared object
59531 ** corresponding to the source database is held when this function is
59532 ** called.
59533 */
59534 SQLITE_PRIVATE void sqlite3BackupUpdate(sqlite3_backup *pBackup, Pgno iPage, const u8 *aData){
59535   sqlite3_backup *p;                   /* Iterator variable */
59536   for(p=pBackup; p; p=p->pNext){
59537     assert( sqlite3_mutex_held(p->pSrc->pBt->mutex) );
59538     if( !isFatalError(p->rc) && iPage<p->iNext ){
59539       /* The backup process p has already copied page iPage. But now it
59540       ** has been modified by a transaction on the source pager. Copy
59541       ** the new data into the backup.
59542       */
59543       int rc;
59544       assert( p->pDestDb );
59545       sqlite3_mutex_enter(p->pDestDb->mutex);
59546       rc = backupOnePage(p, iPage, aData, 1);
59547       sqlite3_mutex_leave(p->pDestDb->mutex);
59548       assert( rc!=SQLITE_BUSY && rc!=SQLITE_LOCKED );
59549       if( rc!=SQLITE_OK ){
59550         p->rc = rc;
59551       }
59552     }
59553   }
59554 }
59555 
59556 /*
59557 ** Restart the backup process. This is called when the pager layer
59558 ** detects that the database has been modified by an external database
59559 ** connection. In this case there is no way of knowing which of the
59560 ** pages that have been copied into the destination database are still 
59561 ** valid and which are not, so the entire process needs to be restarted.
59562 **
59563 ** It is assumed that the mutex associated with the BtShared object
59564 ** corresponding to the source database is held when this function is
59565 ** called.
59566 */
59567 SQLITE_PRIVATE void sqlite3BackupRestart(sqlite3_backup *pBackup){
59568   sqlite3_backup *p;                   /* Iterator variable */
59569   for(p=pBackup; p; p=p->pNext){
59570     assert( sqlite3_mutex_held(p->pSrc->pBt->mutex) );
59571     p->iNext = 1;
59572   }
59573 }
59574 
59575 #ifndef SQLITE_OMIT_VACUUM
59576 /*
59577 ** Copy the complete content of pBtFrom into pBtTo.  A transaction
59578 ** must be active for both files.
59579 **
59580 ** The size of file pTo may be reduced by this operation. If anything 
59581 ** goes wrong, the transaction on pTo is rolled back. If successful, the 
59582 ** transaction is committed before returning.
59583 */
59584 SQLITE_PRIVATE int sqlite3BtreeCopyFile(Btree *pTo, Btree *pFrom){
59585   int rc;
59586   sqlite3_file *pFd;              /* File descriptor for database pTo */
59587   sqlite3_backup b;
59588   sqlite3BtreeEnter(pTo);
59589   sqlite3BtreeEnter(pFrom);
59590 
59591   assert( sqlite3BtreeIsInTrans(pTo) );
59592   pFd = sqlite3PagerFile(sqlite3BtreePager(pTo));
59593   if( pFd->pMethods ){
59594     i64 nByte = sqlite3BtreeGetPageSize(pFrom)*(i64)sqlite3BtreeLastPage(pFrom);
59595     rc = sqlite3OsFileControl(pFd, SQLITE_FCNTL_OVERWRITE, &nByte);
59596     if( rc==SQLITE_NOTFOUND ) rc = SQLITE_OK;
59597     if( rc ) goto copy_finished;
59598   }
59599 
59600   /* Set up an sqlite3_backup object. sqlite3_backup.pDestDb must be set
59601   ** to 0. This is used by the implementations of sqlite3_backup_step()
59602   ** and sqlite3_backup_finish() to detect that they are being called
59603   ** from this function, not directly by the user.
59604   */
59605   memset(&b, 0, sizeof(b));
59606   b.pSrcDb = pFrom->db;
59607   b.pSrc = pFrom;
59608   b.pDest = pTo;
59609   b.iNext = 1;
59610 
59611   /* 0x7FFFFFFF is the hard limit for the number of pages in a database
59612   ** file. By passing this as the number of pages to copy to
59613   ** sqlite3_backup_step(), we can guarantee that the copy finishes 
59614   ** within a single call (unless an error occurs). The assert() statement
59615   ** checks this assumption - (p->rc) should be set to either SQLITE_DONE 
59616   ** or an error code.
59617   */
59618   sqlite3_backup_step(&b, 0x7FFFFFFF);
59619   assert( b.rc!=SQLITE_OK );
59620   rc = sqlite3_backup_finish(&b);
59621   if( rc==SQLITE_OK ){
59622     pTo->pBt->btsFlags &= ~BTS_PAGESIZE_FIXED;
59623   }else{
59624     sqlite3PagerClearCache(sqlite3BtreePager(b.pDest));
59625   }
59626 
59627   assert( sqlite3BtreeIsInTrans(pTo)==0 );
59628 copy_finished:
59629   sqlite3BtreeLeave(pFrom);
59630   sqlite3BtreeLeave(pTo);
59631   return rc;
59632 }
59633 #endif /* SQLITE_OMIT_VACUUM */
59634 
59635 /************** End of backup.c **********************************************/
59636 /************** Begin file vdbemem.c *****************************************/
59637 /*
59638 ** 2004 May 26
59639 **
59640 ** The author disclaims copyright to this source code.  In place of
59641 ** a legal notice, here is a blessing:
59642 **
59643 **    May you do good and not evil.
59644 **    May you find forgiveness for yourself and forgive others.
59645 **    May you share freely, never taking more than you give.
59646 **
59647 *************************************************************************
59648 **
59649 ** This file contains code use to manipulate "Mem" structure.  A "Mem"
59650 ** stores a single value in the VDBE.  Mem is an opaque structure visible
59651 ** only within the VDBE.  Interface routines refer to a Mem using the
59652 ** name sqlite_value
59653 */
59654 
59655 /*
59656 ** If pMem is an object with a valid string representation, this routine
59657 ** ensures the internal encoding for the string representation is
59658 ** 'desiredEnc', one of SQLITE_UTF8, SQLITE_UTF16LE or SQLITE_UTF16BE.
59659 **
59660 ** If pMem is not a string object, or the encoding of the string
59661 ** representation is already stored using the requested encoding, then this
59662 ** routine is a no-op.
59663 **
59664 ** SQLITE_OK is returned if the conversion is successful (or not required).
59665 ** SQLITE_NOMEM may be returned if a malloc() fails during conversion
59666 ** between formats.
59667 */
59668 SQLITE_PRIVATE int sqlite3VdbeChangeEncoding(Mem *pMem, int desiredEnc){
59669 #ifndef SQLITE_OMIT_UTF16
59670   int rc;
59671 #endif
59672   assert( (pMem->flags&MEM_RowSet)==0 );
59673   assert( desiredEnc==SQLITE_UTF8 || desiredEnc==SQLITE_UTF16LE
59674            || desiredEnc==SQLITE_UTF16BE );
59675   if( !(pMem->flags&MEM_Str) || pMem->enc==desiredEnc ){
59676     return SQLITE_OK;
59677   }
59678   assert( pMem->db==0 || sqlite3_mutex_held(pMem->db->mutex) );
59679 #ifdef SQLITE_OMIT_UTF16
59680   return SQLITE_ERROR;
59681 #else
59682 
59683   /* MemTranslate() may return SQLITE_OK or SQLITE_NOMEM. If NOMEM is returned,
59684   ** then the encoding of the value may not have changed.
59685   */
59686   rc = sqlite3VdbeMemTranslate(pMem, (u8)desiredEnc);
59687   assert(rc==SQLITE_OK    || rc==SQLITE_NOMEM);
59688   assert(rc==SQLITE_OK    || pMem->enc!=desiredEnc);
59689   assert(rc==SQLITE_NOMEM || pMem->enc==desiredEnc);
59690   return rc;
59691 #endif
59692 }
59693 
59694 /*
59695 ** Make sure pMem->z points to a writable allocation of at least 
59696 ** n bytes.
59697 **
59698 ** If the third argument passed to this function is true, then memory
59699 ** cell pMem must contain a string or blob. In this case the content is
59700 ** preserved. Otherwise, if the third parameter to this function is false,
59701 ** any current string or blob value may be discarded.
59702 **
59703 ** This function sets the MEM_Dyn flag and clears any xDel callback.
59704 ** It also clears MEM_Ephem and MEM_Static. If the preserve flag is 
59705 ** not set, Mem.n is zeroed.
59706 */
59707 SQLITE_PRIVATE int sqlite3VdbeMemGrow(Mem *pMem, int n, int preserve){
59708   assert( 1 >=
59709     ((pMem->zMalloc && pMem->zMalloc==pMem->z) ? 1 : 0) +
59710     (((pMem->flags&MEM_Dyn)&&pMem->xDel) ? 1 : 0) + 
59711     ((pMem->flags&MEM_Ephem) ? 1 : 0) + 
59712     ((pMem->flags&MEM_Static) ? 1 : 0)
59713   );
59714   assert( (pMem->flags&MEM_RowSet)==0 );
59715 
59716   /* If the preserve flag is set to true, then the memory cell must already
59717   ** contain a valid string or blob value.  */
59718   assert( preserve==0 || pMem->flags&(MEM_Blob|MEM_Str) );
59719 
59720   if( n<32 ) n = 32;
59721   if( sqlite3DbMallocSize(pMem->db, pMem->zMalloc)<n ){
59722     if( preserve && pMem->z==pMem->zMalloc ){
59723       pMem->z = pMem->zMalloc = sqlite3DbReallocOrFree(pMem->db, pMem->z, n);
59724       preserve = 0;
59725     }else{
59726       sqlite3DbFree(pMem->db, pMem->zMalloc);
59727       pMem->zMalloc = sqlite3DbMallocRaw(pMem->db, n);
59728     }
59729   }
59730 
59731   if( pMem->z && preserve && pMem->zMalloc && pMem->z!=pMem->zMalloc ){
59732     memcpy(pMem->zMalloc, pMem->z, pMem->n);
59733   }
59734   if( pMem->flags&MEM_Dyn && pMem->xDel ){
59735     assert( pMem->xDel!=SQLITE_DYNAMIC );
59736     pMem->xDel((void *)(pMem->z));
59737   }
59738 
59739   pMem->z = pMem->zMalloc;
59740   if( pMem->z==0 ){
59741     pMem->flags = MEM_Null;
59742   }else{
59743     pMem->flags &= ~(MEM_Ephem|MEM_Static);
59744   }
59745   pMem->xDel = 0;
59746   return (pMem->z ? SQLITE_OK : SQLITE_NOMEM);
59747 }
59748 
59749 /*
59750 ** Make the given Mem object MEM_Dyn.  In other words, make it so
59751 ** that any TEXT or BLOB content is stored in memory obtained from
59752 ** malloc().  In this way, we know that the memory is safe to be
59753 ** overwritten or altered.
59754 **
59755 ** Return SQLITE_OK on success or SQLITE_NOMEM if malloc fails.
59756 */
59757 SQLITE_PRIVATE int sqlite3VdbeMemMakeWriteable(Mem *pMem){
59758   int f;
59759   assert( pMem->db==0 || sqlite3_mutex_held(pMem->db->mutex) );
59760   assert( (pMem->flags&MEM_RowSet)==0 );
59761   ExpandBlob(pMem);
59762   f = pMem->flags;
59763   if( (f&(MEM_Str|MEM_Blob)) && pMem->z!=pMem->zMalloc ){
59764     if( sqlite3VdbeMemGrow(pMem, pMem->n + 2, 1) ){
59765       return SQLITE_NOMEM;
59766     }
59767     pMem->z[pMem->n] = 0;
59768     pMem->z[pMem->n+1] = 0;
59769     pMem->flags |= MEM_Term;
59770 #ifdef SQLITE_DEBUG
59771     pMem->pScopyFrom = 0;
59772 #endif
59773   }
59774 
59775   return SQLITE_OK;
59776 }
59777 
59778 /*
59779 ** If the given Mem* has a zero-filled tail, turn it into an ordinary
59780 ** blob stored in dynamically allocated space.
59781 */
59782 #ifndef SQLITE_OMIT_INCRBLOB
59783 SQLITE_PRIVATE int sqlite3VdbeMemExpandBlob(Mem *pMem){
59784   if( pMem->flags & MEM_Zero ){
59785     int nByte;
59786     assert( pMem->flags&MEM_Blob );
59787     assert( (pMem->flags&MEM_RowSet)==0 );
59788     assert( pMem->db==0 || sqlite3_mutex_held(pMem->db->mutex) );
59789 
59790     /* Set nByte to the number of bytes required to store the expanded blob. */
59791     nByte = pMem->n + pMem->u.nZero;
59792     if( nByte<=0 ){
59793       nByte = 1;
59794     }
59795     if( sqlite3VdbeMemGrow(pMem, nByte, 1) ){
59796       return SQLITE_NOMEM;
59797     }
59798 
59799     memset(&pMem->z[pMem->n], 0, pMem->u.nZero);
59800     pMem->n += pMem->u.nZero;
59801     pMem->flags &= ~(MEM_Zero|MEM_Term);
59802   }
59803   return SQLITE_OK;
59804 }
59805 #endif
59806 
59807 
59808 /*
59809 ** Make sure the given Mem is \u0000 terminated.
59810 */
59811 SQLITE_PRIVATE int sqlite3VdbeMemNulTerminate(Mem *pMem){
59812   assert( pMem->db==0 || sqlite3_mutex_held(pMem->db->mutex) );
59813   if( (pMem->flags & MEM_Term)!=0 || (pMem->flags & MEM_Str)==0 ){
59814     return SQLITE_OK;   /* Nothing to do */
59815   }
59816   if( sqlite3VdbeMemGrow(pMem, pMem->n+2, 1) ){
59817     return SQLITE_NOMEM;
59818   }
59819   pMem->z[pMem->n] = 0;
59820   pMem->z[pMem->n+1] = 0;
59821   pMem->flags |= MEM_Term;
59822   return SQLITE_OK;
59823 }
59824 
59825 /*
59826 ** Add MEM_Str to the set of representations for the given Mem.  Numbers
59827 ** are converted using sqlite3_snprintf().  Converting a BLOB to a string
59828 ** is a no-op.
59829 **
59830 ** Existing representations MEM_Int and MEM_Real are *not* invalidated.
59831 **
59832 ** A MEM_Null value will never be passed to this function. This function is
59833 ** used for converting values to text for returning to the user (i.e. via
59834 ** sqlite3_value_text()), or for ensuring that values to be used as btree
59835 ** keys are strings. In the former case a NULL pointer is returned the
59836 ** user and the later is an internal programming error.
59837 */
59838 SQLITE_PRIVATE int sqlite3VdbeMemStringify(Mem *pMem, int enc){
59839   int rc = SQLITE_OK;
59840   int fg = pMem->flags;
59841   const int nByte = 32;
59842 
59843   assert( pMem->db==0 || sqlite3_mutex_held(pMem->db->mutex) );
59844   assert( !(fg&MEM_Zero) );
59845   assert( !(fg&(MEM_Str|MEM_Blob)) );
59846   assert( fg&(MEM_Int|MEM_Real) );
59847   assert( (pMem->flags&MEM_RowSet)==0 );
59848   assert( EIGHT_BYTE_ALIGNMENT(pMem) );
59849 
59850 
59851   if( sqlite3VdbeMemGrow(pMem, nByte, 0) ){
59852     return SQLITE_NOMEM;
59853   }
59854 
59855   /* For a Real or Integer, use sqlite3_mprintf() to produce the UTF-8
59856   ** string representation of the value. Then, if the required encoding
59857   ** is UTF-16le or UTF-16be do a translation.
59858   ** 
59859   ** FIX ME: It would be better if sqlite3_snprintf() could do UTF-16.
59860   */
59861   if( fg & MEM_Int ){
59862     sqlite3_snprintf(nByte, pMem->z, "%lld", pMem->u.i);
59863   }else{
59864     assert( fg & MEM_Real );
59865     sqlite3_snprintf(nByte, pMem->z, "%!.15g", pMem->r);
59866   }
59867   pMem->n = sqlite3Strlen30(pMem->z);
59868   pMem->enc = SQLITE_UTF8;
59869   pMem->flags |= MEM_Str|MEM_Term;
59870   sqlite3VdbeChangeEncoding(pMem, enc);
59871   return rc;
59872 }
59873 
59874 /*
59875 ** Memory cell pMem contains the context of an aggregate function.
59876 ** This routine calls the finalize method for that function.  The
59877 ** result of the aggregate is stored back into pMem.
59878 **
59879 ** Return SQLITE_ERROR if the finalizer reports an error.  SQLITE_OK
59880 ** otherwise.
59881 */
59882 SQLITE_PRIVATE int sqlite3VdbeMemFinalize(Mem *pMem, FuncDef *pFunc){
59883   int rc = SQLITE_OK;
59884   if( ALWAYS(pFunc && pFunc->xFinalize) ){
59885     sqlite3_context ctx;
59886     assert( (pMem->flags & MEM_Null)!=0 || pFunc==pMem->u.pDef );
59887     assert( pMem->db==0 || sqlite3_mutex_held(pMem->db->mutex) );
59888     memset(&ctx, 0, sizeof(ctx));
59889     ctx.s.flags = MEM_Null;
59890     ctx.s.db = pMem->db;
59891     ctx.pMem = pMem;
59892     ctx.pFunc = pFunc;
59893     pFunc->xFinalize(&ctx); /* IMP: R-24505-23230 */
59894     assert( 0==(pMem->flags&MEM_Dyn) && !pMem->xDel );
59895     sqlite3DbFree(pMem->db, pMem->zMalloc);
59896     memcpy(pMem, &ctx.s, sizeof(ctx.s));
59897     rc = ctx.isError;
59898   }
59899   return rc;
59900 }
59901 
59902 /*
59903 ** If the memory cell contains a string value that must be freed by
59904 ** invoking an external callback, free it now. Calling this function
59905 ** does not free any Mem.zMalloc buffer.
59906 */
59907 SQLITE_PRIVATE void sqlite3VdbeMemReleaseExternal(Mem *p){
59908   assert( p->db==0 || sqlite3_mutex_held(p->db->mutex) );
59909   if( p->flags&MEM_Agg ){
59910     sqlite3VdbeMemFinalize(p, p->u.pDef);
59911     assert( (p->flags & MEM_Agg)==0 );
59912     sqlite3VdbeMemRelease(p);
59913   }else if( p->flags&MEM_Dyn && p->xDel ){
59914     assert( (p->flags&MEM_RowSet)==0 );
59915     assert( p->xDel!=SQLITE_DYNAMIC );
59916     p->xDel((void *)p->z);
59917     p->xDel = 0;
59918   }else if( p->flags&MEM_RowSet ){
59919     sqlite3RowSetClear(p->u.pRowSet);
59920   }else if( p->flags&MEM_Frame ){
59921     sqlite3VdbeMemSetNull(p);
59922   }
59923 }
59924 
59925 /*
59926 ** Release any memory held by the Mem. This may leave the Mem in an
59927 ** inconsistent state, for example with (Mem.z==0) and
59928 ** (Mem.type==SQLITE_TEXT).
59929 */
59930 SQLITE_PRIVATE void sqlite3VdbeMemRelease(Mem *p){
59931   VdbeMemRelease(p);
59932   sqlite3DbFree(p->db, p->zMalloc);
59933   p->z = 0;
59934   p->zMalloc = 0;
59935   p->xDel = 0;
59936 }
59937 
59938 /*
59939 ** Convert a 64-bit IEEE double into a 64-bit signed integer.
59940 ** If the double is out of range of a 64-bit signed integer then
59941 ** return the closest available 64-bit signed integer.
59942 */
59943 static i64 doubleToInt64(double r){
59944 #ifdef SQLITE_OMIT_FLOATING_POINT
59945   /* When floating-point is omitted, double and int64 are the same thing */
59946   return r;
59947 #else
59948   /*
59949   ** Many compilers we encounter do not define constants for the
59950   ** minimum and maximum 64-bit integers, or they define them
59951   ** inconsistently.  And many do not understand the "LL" notation.
59952   ** So we define our own static constants here using nothing
59953   ** larger than a 32-bit integer constant.
59954   */
59955   static const i64 maxInt = LARGEST_INT64;
59956   static const i64 minInt = SMALLEST_INT64;
59957 
59958   if( r<=(double)minInt ){
59959     return minInt;
59960   }else if( r>=(double)maxInt ){
59961     return maxInt;
59962   }else{
59963     return (i64)r;
59964   }
59965 #endif
59966 }
59967 
59968 /*
59969 ** Return some kind of integer value which is the best we can do
59970 ** at representing the value that *pMem describes as an integer.
59971 ** If pMem is an integer, then the value is exact.  If pMem is
59972 ** a floating-point then the value returned is the integer part.
59973 ** If pMem is a string or blob, then we make an attempt to convert
59974 ** it into a integer and return that.  If pMem represents an
59975 ** an SQL-NULL value, return 0.
59976 **
59977 ** If pMem represents a string value, its encoding might be changed.
59978 */
59979 SQLITE_PRIVATE i64 sqlite3VdbeIntValue(Mem *pMem){
59980   int flags;
59981   assert( pMem->db==0 || sqlite3_mutex_held(pMem->db->mutex) );
59982   assert( EIGHT_BYTE_ALIGNMENT(pMem) );
59983   flags = pMem->flags;
59984   if( flags & MEM_Int ){
59985     return pMem->u.i;
59986   }else if( flags & MEM_Real ){
59987     return doubleToInt64(pMem->r);
59988   }else if( flags & (MEM_Str|MEM_Blob) ){
59989     i64 value = 0;
59990     assert( pMem->z || pMem->n==0 );
59991     testcase( pMem->z==0 );
59992     sqlite3Atoi64(pMem->z, &value, pMem->n, pMem->enc);
59993     return value;
59994   }else{
59995     return 0;
59996   }
59997 }
59998 
59999 /*
60000 ** Return the best representation of pMem that we can get into a
60001 ** double.  If pMem is already a double or an integer, return its
60002 ** value.  If it is a string or blob, try to convert it to a double.
60003 ** If it is a NULL, return 0.0.
60004 */
60005 SQLITE_PRIVATE double sqlite3VdbeRealValue(Mem *pMem){
60006   assert( pMem->db==0 || sqlite3_mutex_held(pMem->db->mutex) );
60007   assert( EIGHT_BYTE_ALIGNMENT(pMem) );
60008   if( pMem->flags & MEM_Real ){
60009     return pMem->r;
60010   }else if( pMem->flags & MEM_Int ){
60011     return (double)pMem->u.i;
60012   }else if( pMem->flags & (MEM_Str|MEM_Blob) ){
60013     /* (double)0 In case of SQLITE_OMIT_FLOATING_POINT... */
60014     double val = (double)0;
60015     sqlite3AtoF(pMem->z, &val, pMem->n, pMem->enc);
60016     return val;
60017   }else{
60018     /* (double)0 In case of SQLITE_OMIT_FLOATING_POINT... */
60019     return (double)0;
60020   }
60021 }
60022 
60023 /*
60024 ** The MEM structure is already a MEM_Real.  Try to also make it a
60025 ** MEM_Int if we can.
60026 */
60027 SQLITE_PRIVATE void sqlite3VdbeIntegerAffinity(Mem *pMem){
60028   assert( pMem->flags & MEM_Real );
60029   assert( (pMem->flags & MEM_RowSet)==0 );
60030   assert( pMem->db==0 || sqlite3_mutex_held(pMem->db->mutex) );
60031   assert( EIGHT_BYTE_ALIGNMENT(pMem) );
60032 
60033   pMem->u.i = doubleToInt64(pMem->r);
60034 
60035   /* Only mark the value as an integer if
60036   **
60037   **    (1) the round-trip conversion real->int->real is a no-op, and
60038   **    (2) The integer is neither the largest nor the smallest
60039   **        possible integer (ticket #3922)
60040   **
60041   ** The second and third terms in the following conditional enforces
60042   ** the second condition under the assumption that addition overflow causes
60043   ** values to wrap around.
60044   */
60045   if( pMem->r==(double)pMem->u.i
60046    && pMem->u.i>SMALLEST_INT64
60047    && pMem->u.i<LARGEST_INT64
60048   ){
60049     pMem->flags |= MEM_Int;
60050   }
60051 }
60052 
60053 /*
60054 ** Convert pMem to type integer.  Invalidate any prior representations.
60055 */
60056 SQLITE_PRIVATE int sqlite3VdbeMemIntegerify(Mem *pMem){
60057   assert( pMem->db==0 || sqlite3_mutex_held(pMem->db->mutex) );
60058   assert( (pMem->flags & MEM_RowSet)==0 );
60059   assert( EIGHT_BYTE_ALIGNMENT(pMem) );
60060 
60061   pMem->u.i = sqlite3VdbeIntValue(pMem);
60062   MemSetTypeFlag(pMem, MEM_Int);
60063   return SQLITE_OK;
60064 }
60065 
60066 /*
60067 ** Convert pMem so that it is of type MEM_Real.
60068 ** Invalidate any prior representations.
60069 */
60070 SQLITE_PRIVATE int sqlite3VdbeMemRealify(Mem *pMem){
60071   assert( pMem->db==0 || sqlite3_mutex_held(pMem->db->mutex) );
60072   assert( EIGHT_BYTE_ALIGNMENT(pMem) );
60073 
60074   pMem->r = sqlite3VdbeRealValue(pMem);
60075   MemSetTypeFlag(pMem, MEM_Real);
60076   return SQLITE_OK;
60077 }
60078 
60079 /*
60080 ** Convert pMem so that it has types MEM_Real or MEM_Int or both.
60081 ** Invalidate any prior representations.
60082 **
60083 ** Every effort is made to force the conversion, even if the input
60084 ** is a string that does not look completely like a number.  Convert
60085 ** as much of the string as we can and ignore the rest.
60086 */
60087 SQLITE_PRIVATE int sqlite3VdbeMemNumerify(Mem *pMem){
60088   if( (pMem->flags & (MEM_Int|MEM_Real|MEM_Null))==0 ){
60089     assert( (pMem->flags & (MEM_Blob|MEM_Str))!=0 );
60090     assert( pMem->db==0 || sqlite3_mutex_held(pMem->db->mutex) );
60091     if( 0==sqlite3Atoi64(pMem->z, &pMem->u.i, pMem->n, pMem->enc) ){
60092       MemSetTypeFlag(pMem, MEM_Int);
60093     }else{
60094       pMem->r = sqlite3VdbeRealValue(pMem);
60095       MemSetTypeFlag(pMem, MEM_Real);
60096       sqlite3VdbeIntegerAffinity(pMem);
60097     }
60098   }
60099   assert( (pMem->flags & (MEM_Int|MEM_Real|MEM_Null))!=0 );
60100   pMem->flags &= ~(MEM_Str|MEM_Blob);
60101   return SQLITE_OK;
60102 }
60103 
60104 /*
60105 ** Delete any previous value and set the value stored in *pMem to NULL.
60106 */
60107 SQLITE_PRIVATE void sqlite3VdbeMemSetNull(Mem *pMem){
60108   if( pMem->flags & MEM_Frame ){
60109     VdbeFrame *pFrame = pMem->u.pFrame;
60110     pFrame->pParent = pFrame->v->pDelFrame;
60111     pFrame->v->pDelFrame = pFrame;
60112   }
60113   if( pMem->flags & MEM_RowSet ){
60114     sqlite3RowSetClear(pMem->u.pRowSet);
60115   }
60116   MemSetTypeFlag(pMem, MEM_Null);
60117   pMem->type = SQLITE_NULL;
60118 }
60119 
60120 /*
60121 ** Delete any previous value and set the value to be a BLOB of length
60122 ** n containing all zeros.
60123 */
60124 SQLITE_PRIVATE void sqlite3VdbeMemSetZeroBlob(Mem *pMem, int n){
60125   sqlite3VdbeMemRelease(pMem);
60126   pMem->flags = MEM_Blob|MEM_Zero;
60127   pMem->type = SQLITE_BLOB;
60128   pMem->n = 0;
60129   if( n<0 ) n = 0;
60130   pMem->u.nZero = n;
60131   pMem->enc = SQLITE_UTF8;
60132 
60133 #ifdef SQLITE_OMIT_INCRBLOB
60134   sqlite3VdbeMemGrow(pMem, n, 0);
60135   if( pMem->z ){
60136     pMem->n = n;
60137     memset(pMem->z, 0, n);
60138   }
60139 #endif
60140 }
60141 
60142 /*
60143 ** Delete any previous value and set the value stored in *pMem to val,
60144 ** manifest type INTEGER.
60145 */
60146 SQLITE_PRIVATE void sqlite3VdbeMemSetInt64(Mem *pMem, i64 val){
60147   sqlite3VdbeMemRelease(pMem);
60148   pMem->u.i = val;
60149   pMem->flags = MEM_Int;
60150   pMem->type = SQLITE_INTEGER;
60151 }
60152 
60153 #ifndef SQLITE_OMIT_FLOATING_POINT
60154 /*
60155 ** Delete any previous value and set the value stored in *pMem to val,
60156 ** manifest type REAL.
60157 */
60158 SQLITE_PRIVATE void sqlite3VdbeMemSetDouble(Mem *pMem, double val){
60159   if( sqlite3IsNaN(val) ){
60160     sqlite3VdbeMemSetNull(pMem);
60161   }else{
60162     sqlite3VdbeMemRelease(pMem);
60163     pMem->r = val;
60164     pMem->flags = MEM_Real;
60165     pMem->type = SQLITE_FLOAT;
60166   }
60167 }
60168 #endif
60169 
60170 /*
60171 ** Delete any previous value and set the value of pMem to be an
60172 ** empty boolean index.
60173 */
60174 SQLITE_PRIVATE void sqlite3VdbeMemSetRowSet(Mem *pMem){
60175   sqlite3 *db = pMem->db;
60176   assert( db!=0 );
60177   assert( (pMem->flags & MEM_RowSet)==0 );
60178   sqlite3VdbeMemRelease(pMem);
60179   pMem->zMalloc = sqlite3DbMallocRaw(db, 64);
60180   if( db->mallocFailed ){
60181     pMem->flags = MEM_Null;
60182   }else{
60183     assert( pMem->zMalloc );
60184     pMem->u.pRowSet = sqlite3RowSetInit(db, pMem->zMalloc, 
60185                                        sqlite3DbMallocSize(db, pMem->zMalloc));
60186     assert( pMem->u.pRowSet!=0 );
60187     pMem->flags = MEM_RowSet;
60188   }
60189 }
60190 
60191 /*
60192 ** Return true if the Mem object contains a TEXT or BLOB that is
60193 ** too large - whose size exceeds SQLITE_MAX_LENGTH.
60194 */
60195 SQLITE_PRIVATE int sqlite3VdbeMemTooBig(Mem *p){
60196   assert( p->db!=0 );
60197   if( p->flags & (MEM_Str|MEM_Blob) ){
60198     int n = p->n;
60199     if( p->flags & MEM_Zero ){
60200       n += p->u.nZero;
60201     }
60202     return n>p->db->aLimit[SQLITE_LIMIT_LENGTH];
60203   }
60204   return 0; 
60205 }
60206 
60207 #ifdef SQLITE_DEBUG
60208 /*
60209 ** This routine prepares a memory cell for modication by breaking
60210 ** its link to a shallow copy and by marking any current shallow
60211 ** copies of this cell as invalid.
60212 **
60213 ** This is used for testing and debugging only - to make sure shallow
60214 ** copies are not misused.
60215 */
60216 SQLITE_PRIVATE void sqlite3VdbeMemAboutToChange(Vdbe *pVdbe, Mem *pMem){
60217   int i;
60218   Mem *pX;
60219   for(i=1, pX=&pVdbe->aMem[1]; i<=pVdbe->nMem; i++, pX++){
60220     if( pX->pScopyFrom==pMem ){
60221       pX->flags |= MEM_Invalid;
60222       pX->pScopyFrom = 0;
60223     }
60224   }
60225   pMem->pScopyFrom = 0;
60226 }
60227 #endif /* SQLITE_DEBUG */
60228 
60229 /*
60230 ** Size of struct Mem not including the Mem.zMalloc member.
60231 */
60232 #define MEMCELLSIZE (size_t)(&(((Mem *)0)->zMalloc))
60233 
60234 /*
60235 ** Make an shallow copy of pFrom into pTo.  Prior contents of
60236 ** pTo are freed.  The pFrom->z field is not duplicated.  If
60237 ** pFrom->z is used, then pTo->z points to the same thing as pFrom->z
60238 ** and flags gets srcType (either MEM_Ephem or MEM_Static).
60239 */
60240 SQLITE_PRIVATE void sqlite3VdbeMemShallowCopy(Mem *pTo, const Mem *pFrom, int srcType){
60241   assert( (pFrom->flags & MEM_RowSet)==0 );
60242   VdbeMemRelease(pTo);
60243   memcpy(pTo, pFrom, MEMCELLSIZE);
60244   pTo->xDel = 0;
60245   if( (pFrom->flags&MEM_Static)==0 ){
60246     pTo->flags &= ~(MEM_Dyn|MEM_Static|MEM_Ephem);
60247     assert( srcType==MEM_Ephem || srcType==MEM_Static );
60248     pTo->flags |= srcType;
60249   }
60250 }
60251 
60252 /*
60253 ** Make a full copy of pFrom into pTo.  Prior contents of pTo are
60254 ** freed before the copy is made.
60255 */
60256 SQLITE_PRIVATE int sqlite3VdbeMemCopy(Mem *pTo, const Mem *pFrom){
60257   int rc = SQLITE_OK;
60258 
60259   assert( (pFrom->flags & MEM_RowSet)==0 );
60260   VdbeMemRelease(pTo);
60261   memcpy(pTo, pFrom, MEMCELLSIZE);
60262   pTo->flags &= ~MEM_Dyn;
60263 
60264   if( pTo->flags&(MEM_Str|MEM_Blob) ){
60265     if( 0==(pFrom->flags&MEM_Static) ){
60266       pTo->flags |= MEM_Ephem;
60267       rc = sqlite3VdbeMemMakeWriteable(pTo);
60268     }
60269   }
60270 
60271   return rc;
60272 }
60273 
60274 /*
60275 ** Transfer the contents of pFrom to pTo. Any existing value in pTo is
60276 ** freed. If pFrom contains ephemeral data, a copy is made.
60277 **
60278 ** pFrom contains an SQL NULL when this routine returns.
60279 */
60280 SQLITE_PRIVATE void sqlite3VdbeMemMove(Mem *pTo, Mem *pFrom){
60281   assert( pFrom->db==0 || sqlite3_mutex_held(pFrom->db->mutex) );
60282   assert( pTo->db==0 || sqlite3_mutex_held(pTo->db->mutex) );
60283   assert( pFrom->db==0 || pTo->db==0 || pFrom->db==pTo->db );
60284 
60285   sqlite3VdbeMemRelease(pTo);
60286   memcpy(pTo, pFrom, sizeof(Mem));
60287   pFrom->flags = MEM_Null;
60288   pFrom->xDel = 0;
60289   pFrom->zMalloc = 0;
60290 }
60291 
60292 /*
60293 ** Change the value of a Mem to be a string or a BLOB.
60294 **
60295 ** The memory management strategy depends on the value of the xDel
60296 ** parameter. If the value passed is SQLITE_TRANSIENT, then the 
60297 ** string is copied into a (possibly existing) buffer managed by the 
60298 ** Mem structure. Otherwise, any existing buffer is freed and the
60299 ** pointer copied.
60300 **
60301 ** If the string is too large (if it exceeds the SQLITE_LIMIT_LENGTH
60302 ** size limit) then no memory allocation occurs.  If the string can be
60303 ** stored without allocating memory, then it is.  If a memory allocation
60304 ** is required to store the string, then value of pMem is unchanged.  In
60305 ** either case, SQLITE_TOOBIG is returned.
60306 */
60307 SQLITE_PRIVATE int sqlite3VdbeMemSetStr(
60308   Mem *pMem,          /* Memory cell to set to string value */
60309   const char *z,      /* String pointer */
60310   int n,              /* Bytes in string, or negative */
60311   u8 enc,             /* Encoding of z.  0 for BLOBs */
60312   void (*xDel)(void*) /* Destructor function */
60313 ){
60314   int nByte = n;      /* New value for pMem->n */
60315   int iLimit;         /* Maximum allowed string or blob size */
60316   u16 flags = 0;      /* New value for pMem->flags */
60317 
60318   assert( pMem->db==0 || sqlite3_mutex_held(pMem->db->mutex) );
60319   assert( (pMem->flags & MEM_RowSet)==0 );
60320 
60321   /* If z is a NULL pointer, set pMem to contain an SQL NULL. */
60322   if( !z ){
60323     sqlite3VdbeMemSetNull(pMem);
60324     return SQLITE_OK;
60325   }
60326 
60327   if( pMem->db ){
60328     iLimit = pMem->db->aLimit[SQLITE_LIMIT_LENGTH];
60329   }else{
60330     iLimit = SQLITE_MAX_LENGTH;
60331   }
60332   flags = (enc==0?MEM_Blob:MEM_Str);
60333   if( nByte<0 ){
60334     assert( enc!=0 );
60335     if( enc==SQLITE_UTF8 ){
60336       for(nByte=0; nByte<=iLimit && z[nByte]; nByte++){}
60337     }else{
60338       for(nByte=0; nByte<=iLimit && (z[nByte] | z[nByte+1]); nByte+=2){}
60339     }
60340     flags |= MEM_Term;
60341   }
60342 
60343   /* The following block sets the new values of Mem.z and Mem.xDel. It
60344   ** also sets a flag in local variable "flags" to indicate the memory
60345   ** management (one of MEM_Dyn or MEM_Static).
60346   */
60347   if( xDel==SQLITE_TRANSIENT ){
60348     int nAlloc = nByte;
60349     if( flags&MEM_Term ){
60350       nAlloc += (enc==SQLITE_UTF8?1:2);
60351     }
60352     if( nByte>iLimit ){
60353       return SQLITE_TOOBIG;
60354     }
60355     if( sqlite3VdbeMemGrow(pMem, nAlloc, 0) ){
60356       return SQLITE_NOMEM;
60357     }
60358     memcpy(pMem->z, z, nAlloc);
60359   }else if( xDel==SQLITE_DYNAMIC ){
60360     sqlite3VdbeMemRelease(pMem);
60361     pMem->zMalloc = pMem->z = (char *)z;
60362     pMem->xDel = 0;
60363   }else{
60364     sqlite3VdbeMemRelease(pMem);
60365     pMem->z = (char *)z;
60366     pMem->xDel = xDel;
60367     flags |= ((xDel==SQLITE_STATIC)?MEM_Static:MEM_Dyn);
60368   }
60369 
60370   pMem->n = nByte;
60371   pMem->flags = flags;
60372   pMem->enc = (enc==0 ? SQLITE_UTF8 : enc);
60373   pMem->type = (enc==0 ? SQLITE_BLOB : SQLITE_TEXT);
60374 
60375 #ifndef SQLITE_OMIT_UTF16
60376   if( pMem->enc!=SQLITE_UTF8 && sqlite3VdbeMemHandleBom(pMem) ){
60377     return SQLITE_NOMEM;
60378   }
60379 #endif
60380 
60381   if( nByte>iLimit ){
60382     return SQLITE_TOOBIG;
60383   }
60384 
60385   return SQLITE_OK;
60386 }
60387 
60388 /*
60389 ** Compare the values contained by the two memory cells, returning
60390 ** negative, zero or positive if pMem1 is less than, equal to, or greater
60391 ** than pMem2. Sorting order is NULL's first, followed by numbers (integers
60392 ** and reals) sorted numerically, followed by text ordered by the collating
60393 ** sequence pColl and finally blob's ordered by memcmp().
60394 **
60395 ** Two NULL values are considered equal by this function.
60396 */
60397 SQLITE_PRIVATE int sqlite3MemCompare(const Mem *pMem1, const Mem *pMem2, const CollSeq *pColl){
60398   int rc;
60399   int f1, f2;
60400   int combined_flags;
60401 
60402   f1 = pMem1->flags;
60403   f2 = pMem2->flags;
60404   combined_flags = f1|f2;
60405   assert( (combined_flags & MEM_RowSet)==0 );
60406  
60407   /* If one value is NULL, it is less than the other. If both values
60408   ** are NULL, return 0.
60409   */
60410   if( combined_flags&MEM_Null ){
60411     return (f2&MEM_Null) - (f1&MEM_Null);
60412   }
60413 
60414   /* If one value is a number and the other is not, the number is less.
60415   ** If both are numbers, compare as reals if one is a real, or as integers
60416   ** if both values are integers.
60417   */
60418   if( combined_flags&(MEM_Int|MEM_Real) ){
60419     double r1, r2;
60420     if( (f1 & f2 & MEM_Int)!=0 ){
60421       if( pMem1->u.i < pMem2->u.i ) return -1;
60422       if( pMem1->u.i > pMem2->u.i ) return 1;
60423       return 0;
60424     }
60425     if( (f1&MEM_Real)!=0 ){
60426       r1 = pMem1->r;
60427     }else if( (f1&MEM_Int)!=0 ){
60428       r1 = (double)pMem1->u.i;
60429     }else{
60430       return 1;
60431     }
60432     if( (f2&MEM_Real)!=0 ){
60433       r2 = pMem2->r;
60434     }else if( (f2&MEM_Int)!=0 ){
60435       r2 = (double)pMem2->u.i;
60436     }else{
60437       return -1;
60438     }
60439     if( r1<r2 ) return -1;
60440     if( r1>r2 ) return 1;
60441     return 0;
60442   }
60443 
60444   /* If one value is a string and the other is a blob, the string is less.
60445   ** If both are strings, compare using the collating functions.
60446   */
60447   if( combined_flags&MEM_Str ){
60448     if( (f1 & MEM_Str)==0 ){
60449       return 1;
60450     }
60451     if( (f2 & MEM_Str)==0 ){
60452       return -1;
60453     }
60454 
60455     assert( pMem1->enc==pMem2->enc );
60456     assert( pMem1->enc==SQLITE_UTF8 || 
60457             pMem1->enc==SQLITE_UTF16LE || pMem1->enc==SQLITE_UTF16BE );
60458 
60459     /* The collation sequence must be defined at this point, even if
60460     ** the user deletes the collation sequence after the vdbe program is
60461     ** compiled (this was not always the case).
60462     */
60463     assert( !pColl || pColl->xCmp );
60464 
60465     if( pColl ){
60466       if( pMem1->enc==pColl->enc ){
60467         /* The strings are already in the correct encoding.  Call the
60468         ** comparison function directly */
60469         return pColl->xCmp(pColl->pUser,pMem1->n,pMem1->z,pMem2->n,pMem2->z);
60470       }else{
60471         const void *v1, *v2;
60472         int n1, n2;
60473         Mem c1;
60474         Mem c2;
60475         memset(&c1, 0, sizeof(c1));
60476         memset(&c2, 0, sizeof(c2));
60477         sqlite3VdbeMemShallowCopy(&c1, pMem1, MEM_Ephem);
60478         sqlite3VdbeMemShallowCopy(&c2, pMem2, MEM_Ephem);
60479         v1 = sqlite3ValueText((sqlite3_value*)&c1, pColl->enc);
60480         n1 = v1==0 ? 0 : c1.n;
60481         v2 = sqlite3ValueText((sqlite3_value*)&c2, pColl->enc);
60482         n2 = v2==0 ? 0 : c2.n;
60483         rc = pColl->xCmp(pColl->pUser, n1, v1, n2, v2);
60484         sqlite3VdbeMemRelease(&c1);
60485         sqlite3VdbeMemRelease(&c2);
60486         return rc;
60487       }
60488     }
60489     /* If a NULL pointer was passed as the collate function, fall through
60490     ** to the blob case and use memcmp().  */
60491   }
60492  
60493   /* Both values must be blobs.  Compare using memcmp().  */
60494   rc = memcmp(pMem1->z, pMem2->z, (pMem1->n>pMem2->n)?pMem2->n:pMem1->n);
60495   if( rc==0 ){
60496     rc = pMem1->n - pMem2->n;
60497   }
60498   return rc;
60499 }
60500 
60501 /*
60502 ** Move data out of a btree key or data field and into a Mem structure.
60503 ** The data or key is taken from the entry that pCur is currently pointing
60504 ** to.  offset and amt determine what portion of the data or key to retrieve.
60505 ** key is true to get the key or false to get data.  The result is written
60506 ** into the pMem element.
60507 **
60508 ** The pMem structure is assumed to be uninitialized.  Any prior content
60509 ** is overwritten without being freed.
60510 **
60511 ** If this routine fails for any reason (malloc returns NULL or unable
60512 ** to read from the disk) then the pMem is left in an inconsistent state.
60513 */
60514 SQLITE_PRIVATE int sqlite3VdbeMemFromBtree(
60515   BtCursor *pCur,   /* Cursor pointing at record to retrieve. */
60516   u32 offset,       /* Offset from the start of data to return bytes from. */
60517   u32 amt,          /* Number of bytes to return. */
60518   int key,          /* If true, retrieve from the btree key, not data. */
60519   Mem *pMem         /* OUT: Return data in this Mem structure. */
60520 ){
60521   char *zData;        /* Data from the btree layer */
60522   u32 available = 0;  /* Number of bytes available on the local btree page */
60523   int rc = SQLITE_OK; /* Return code */
60524 
60525   assert( sqlite3BtreeCursorIsValid(pCur) );
60526 
60527   /* Note: the calls to BtreeKeyFetch() and DataFetch() below assert() 
60528   ** that both the BtShared and database handle mutexes are held. */
60529   assert( (pMem->flags & MEM_RowSet)==0 );
60530   if( key ){
60531     zData = (char *)sqlite3BtreeKeyFetch(pCur, &available);
60532   }else{
60533     zData = (char *)sqlite3BtreeDataFetch(pCur, &available);
60534   }
60535   assert( zData!=0 );
60536 
60537   if( offset+amt<=available ){
60538     sqlite3VdbeMemRelease(pMem);
60539     pMem->z = &zData[offset];
60540     pMem->flags = MEM_Blob|MEM_Ephem;
60541   }else if( SQLITE_OK==(rc = sqlite3VdbeMemGrow(pMem, amt+2, 0)) ){
60542     pMem->flags = MEM_Blob|MEM_Dyn|MEM_Term;
60543     pMem->enc = 0;
60544     pMem->type = SQLITE_BLOB;
60545     if( key ){
60546       rc = sqlite3BtreeKey(pCur, offset, amt, pMem->z);
60547     }else{
60548       rc = sqlite3BtreeData(pCur, offset, amt, pMem->z);
60549     }
60550     pMem->z[amt] = 0;
60551     pMem->z[amt+1] = 0;
60552     if( rc!=SQLITE_OK ){
60553       sqlite3VdbeMemRelease(pMem);
60554     }
60555   }
60556   pMem->n = (int)amt;
60557 
60558   return rc;
60559 }
60560 
60561 /* This function is only available internally, it is not part of the
60562 ** external API. It works in a similar way to sqlite3_value_text(),
60563 ** except the data returned is in the encoding specified by the second
60564 ** parameter, which must be one of SQLITE_UTF16BE, SQLITE_UTF16LE or
60565 ** SQLITE_UTF8.
60566 **
60567 ** (2006-02-16:)  The enc value can be or-ed with SQLITE_UTF16_ALIGNED.
60568 ** If that is the case, then the result must be aligned on an even byte
60569 ** boundary.
60570 */
60571 SQLITE_PRIVATE const void *sqlite3ValueText(sqlite3_value* pVal, u8 enc){
60572   if( !pVal ) return 0;
60573 
60574   assert( pVal->db==0 || sqlite3_mutex_held(pVal->db->mutex) );
60575   assert( (enc&3)==(enc&~SQLITE_UTF16_ALIGNED) );
60576   assert( (pVal->flags & MEM_RowSet)==0 );
60577 
60578   if( pVal->flags&MEM_Null ){
60579     return 0;
60580   }
60581   assert( (MEM_Blob>>3) == MEM_Str );
60582   pVal->flags |= (pVal->flags & MEM_Blob)>>3;
60583   ExpandBlob(pVal);
60584   if( pVal->flags&MEM_Str ){
60585     sqlite3VdbeChangeEncoding(pVal, enc & ~SQLITE_UTF16_ALIGNED);
60586     if( (enc & SQLITE_UTF16_ALIGNED)!=0 && 1==(1&SQLITE_PTR_TO_INT(pVal->z)) ){
60587       assert( (pVal->flags & (MEM_Ephem|MEM_Static))!=0 );
60588       if( sqlite3VdbeMemMakeWriteable(pVal)!=SQLITE_OK ){
60589         return 0;
60590       }
60591     }
60592     sqlite3VdbeMemNulTerminate(pVal); /* IMP: R-31275-44060 */
60593   }else{
60594     assert( (pVal->flags&MEM_Blob)==0 );
60595     sqlite3VdbeMemStringify(pVal, enc);
60596     assert( 0==(1&SQLITE_PTR_TO_INT(pVal->z)) );
60597   }
60598   assert(pVal->enc==(enc & ~SQLITE_UTF16_ALIGNED) || pVal->db==0
60599               || pVal->db->mallocFailed );
60600   if( pVal->enc==(enc & ~SQLITE_UTF16_ALIGNED) ){
60601     return pVal->z;
60602   }else{
60603     return 0;
60604   }
60605 }
60606 
60607 /*
60608 ** Create a new sqlite3_value object.
60609 */
60610 SQLITE_PRIVATE sqlite3_value *sqlite3ValueNew(sqlite3 *db){
60611   Mem *p = sqlite3DbMallocZero(db, sizeof(*p));
60612   if( p ){
60613     p->flags = MEM_Null;
60614     p->type = SQLITE_NULL;
60615     p->db = db;
60616   }
60617   return p;
60618 }
60619 
60620 /*
60621 ** Context object passed by sqlite3Stat4ProbeSetValue() through to 
60622 ** valueNew(). See comments above valueNew() for details.
60623 */
60624 struct ValueNewStat4Ctx {
60625   Parse *pParse;
60626   Index *pIdx;
60627   UnpackedRecord **ppRec;
60628   int iVal;
60629 };
60630 
60631 /*
60632 ** Allocate and return a pointer to a new sqlite3_value object. If
60633 ** the second argument to this function is NULL, the object is allocated
60634 ** by calling sqlite3ValueNew().
60635 **
60636 ** Otherwise, if the second argument is non-zero, then this function is 
60637 ** being called indirectly by sqlite3Stat4ProbeSetValue(). If it has not
60638 ** already been allocated, allocate the UnpackedRecord structure that 
60639 ** that function will return to its caller here. Then return a pointer 
60640 ** an sqlite3_value within the UnpackedRecord.a[] array.
60641 */
60642 static sqlite3_value *valueNew(sqlite3 *db, struct ValueNewStat4Ctx *p){
60643 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
60644   if( p ){
60645     UnpackedRecord *pRec = p->ppRec[0];
60646 
60647     if( pRec==0 ){
60648       Index *pIdx = p->pIdx;      /* Index being probed */
60649       int nByte;                  /* Bytes of space to allocate */
60650       int i;                      /* Counter variable */
60651       int nCol = pIdx->nColumn;   /* Number of index columns including rowid */
60652   
60653       nByte = sizeof(Mem) * nCol + ROUND8(sizeof(UnpackedRecord));
60654       pRec = (UnpackedRecord*)sqlite3DbMallocZero(db, nByte);
60655       if( pRec ){
60656         pRec->pKeyInfo = sqlite3KeyInfoOfIndex(p->pParse, pIdx);
60657         if( pRec->pKeyInfo ){
60658           assert( pRec->pKeyInfo->nField+pRec->pKeyInfo->nXField==nCol );
60659           assert( pRec->pKeyInfo->enc==ENC(db) );
60660           pRec->flags = UNPACKED_PREFIX_MATCH;
60661           pRec->aMem = (Mem *)((u8*)pRec + ROUND8(sizeof(UnpackedRecord)));
60662           for(i=0; i<nCol; i++){
60663             pRec->aMem[i].flags = MEM_Null;
60664             pRec->aMem[i].type = SQLITE_NULL;
60665             pRec->aMem[i].db = db;
60666           }
60667         }else{
60668           sqlite3DbFree(db, pRec);
60669           pRec = 0;
60670         }
60671       }
60672       if( pRec==0 ) return 0;
60673       p->ppRec[0] = pRec;
60674     }
60675   
60676     pRec->nField = p->iVal+1;
60677     return &pRec->aMem[p->iVal];
60678   }
60679 #else
60680   UNUSED_PARAMETER(p);
60681 #endif /* defined(SQLITE_ENABLE_STAT3_OR_STAT4) */
60682   return sqlite3ValueNew(db);
60683 }
60684 
60685 /*
60686 ** Extract a value from the supplied expression in the manner described
60687 ** above sqlite3ValueFromExpr(). Allocate the sqlite3_value object
60688 ** using valueNew().
60689 **
60690 ** If pCtx is NULL and an error occurs after the sqlite3_value object
60691 ** has been allocated, it is freed before returning. Or, if pCtx is not
60692 ** NULL, it is assumed that the caller will free any allocated object
60693 ** in all cases.
60694 */
60695 static int valueFromExpr(
60696   sqlite3 *db,                    /* The database connection */
60697   Expr *pExpr,                    /* The expression to evaluate */
60698   u8 enc,                         /* Encoding to use */
60699   u8 affinity,                    /* Affinity to use */
60700   sqlite3_value **ppVal,          /* Write the new value here */
60701   struct ValueNewStat4Ctx *pCtx   /* Second argument for valueNew() */
60702 ){
60703   int op;
60704   char *zVal = 0;
60705   sqlite3_value *pVal = 0;
60706   int negInt = 1;
60707   const char *zNeg = "";
60708   int rc = SQLITE_OK;
60709 
60710   if( !pExpr ){
60711     *ppVal = 0;
60712     return SQLITE_OK;
60713   }
60714   op = pExpr->op;
60715   if( NEVER(op==TK_REGISTER) ) op = pExpr->op2;
60716 
60717   /* Handle negative integers in a single step.  This is needed in the
60718   ** case when the value is -9223372036854775808.
60719   */
60720   if( op==TK_UMINUS
60721    && (pExpr->pLeft->op==TK_INTEGER || pExpr->pLeft->op==TK_FLOAT) ){
60722     pExpr = pExpr->pLeft;
60723     op = pExpr->op;
60724     negInt = -1;
60725     zNeg = "-";
60726   }
60727 
60728   if( op==TK_STRING || op==TK_FLOAT || op==TK_INTEGER ){
60729     pVal = valueNew(db, pCtx);
60730     if( pVal==0 ) goto no_mem;
60731     if( ExprHasProperty(pExpr, EP_IntValue) ){
60732       sqlite3VdbeMemSetInt64(pVal, (i64)pExpr->u.iValue*negInt);
60733     }else{
60734       zVal = sqlite3MPrintf(db, "%s%s", zNeg, pExpr->u.zToken);
60735       if( zVal==0 ) goto no_mem;
60736       sqlite3ValueSetStr(pVal, -1, zVal, SQLITE_UTF8, SQLITE_DYNAMIC);
60737       if( op==TK_FLOAT ) pVal->type = SQLITE_FLOAT;
60738     }
60739     if( (op==TK_INTEGER || op==TK_FLOAT ) && affinity==SQLITE_AFF_NONE ){
60740       sqlite3ValueApplyAffinity(pVal, SQLITE_AFF_NUMERIC, SQLITE_UTF8);
60741     }else{
60742       sqlite3ValueApplyAffinity(pVal, affinity, SQLITE_UTF8);
60743     }
60744     if( pVal->flags & (MEM_Int|MEM_Real) ) pVal->flags &= ~MEM_Str;
60745     if( enc!=SQLITE_UTF8 ){
60746       rc = sqlite3VdbeChangeEncoding(pVal, enc);
60747     }
60748   }else if( op==TK_UMINUS ) {
60749     /* This branch happens for multiple negative signs.  Ex: -(-5) */
60750     if( SQLITE_OK==sqlite3ValueFromExpr(db,pExpr->pLeft,enc,affinity,&pVal) 
60751      && pVal!=0
60752     ){
60753       sqlite3VdbeMemNumerify(pVal);
60754       if( pVal->u.i==SMALLEST_INT64 ){
60755         pVal->flags &= MEM_Int;
60756         pVal->flags |= MEM_Real;
60757         pVal->r = (double)LARGEST_INT64;
60758       }else{
60759         pVal->u.i = -pVal->u.i;
60760       }
60761       pVal->r = -pVal->r;
60762       sqlite3ValueApplyAffinity(pVal, affinity, enc);
60763     }
60764   }else if( op==TK_NULL ){
60765     pVal = valueNew(db, pCtx);
60766     if( pVal==0 ) goto no_mem;
60767   }
60768 #ifndef SQLITE_OMIT_BLOB_LITERAL
60769   else if( op==TK_BLOB ){
60770     int nVal;
60771     assert( pExpr->u.zToken[0]=='x' || pExpr->u.zToken[0]=='X' );
60772     assert( pExpr->u.zToken[1]=='\'' );
60773     pVal = valueNew(db, pCtx);
60774     if( !pVal ) goto no_mem;
60775     zVal = &pExpr->u.zToken[2];
60776     nVal = sqlite3Strlen30(zVal)-1;
60777     assert( zVal[nVal]=='\'' );
60778     sqlite3VdbeMemSetStr(pVal, sqlite3HexToBlob(db, zVal, nVal), nVal/2,
60779                          0, SQLITE_DYNAMIC);
60780   }
60781 #endif
60782 
60783   if( pVal ){
60784     sqlite3VdbeMemStoreType(pVal);
60785   }
60786   *ppVal = pVal;
60787   return rc;
60788 
60789 no_mem:
60790   db->mallocFailed = 1;
60791   sqlite3DbFree(db, zVal);
60792   assert( *ppVal==0 );
60793 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
60794   if( pCtx==0 ) sqlite3ValueFree(pVal);
60795 #else
60796   assert( pCtx==0 ); sqlite3ValueFree(pVal);
60797 #endif
60798   return SQLITE_NOMEM;
60799 }
60800 
60801 /*
60802 ** Create a new sqlite3_value object, containing the value of pExpr.
60803 **
60804 ** This only works for very simple expressions that consist of one constant
60805 ** token (i.e. "5", "5.1", "'a string'"). If the expression can
60806 ** be converted directly into a value, then the value is allocated and
60807 ** a pointer written to *ppVal. The caller is responsible for deallocating
60808 ** the value by passing it to sqlite3ValueFree() later on. If the expression
60809 ** cannot be converted to a value, then *ppVal is set to NULL.
60810 */
60811 SQLITE_PRIVATE int sqlite3ValueFromExpr(
60812   sqlite3 *db,              /* The database connection */
60813   Expr *pExpr,              /* The expression to evaluate */
60814   u8 enc,                   /* Encoding to use */
60815   u8 affinity,              /* Affinity to use */
60816   sqlite3_value **ppVal     /* Write the new value here */
60817 ){
60818   return valueFromExpr(db, pExpr, enc, affinity, ppVal, 0);
60819 }
60820 
60821 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
60822 /*
60823 ** The implementation of the sqlite_record() function. This function accepts
60824 ** a single argument of any type. The return value is a formatted database 
60825 ** record (a blob) containing the argument value.
60826 **
60827 ** This is used to convert the value stored in the 'sample' column of the
60828 ** sqlite_stat3 table to the record format SQLite uses internally.
60829 */
60830 static void recordFunc(
60831   sqlite3_context *context,
60832   int argc,
60833   sqlite3_value **argv
60834 ){
60835   const int file_format = 1;
60836   int iSerial;                    /* Serial type */
60837   int nSerial;                    /* Bytes of space for iSerial as varint */
60838   int nVal;                       /* Bytes of space required for argv[0] */
60839   int nRet;
60840   sqlite3 *db;
60841   u8 *aRet;
60842 
60843   UNUSED_PARAMETER( argc );
60844   iSerial = sqlite3VdbeSerialType(argv[0], file_format);
60845   nSerial = sqlite3VarintLen(iSerial);
60846   nVal = sqlite3VdbeSerialTypeLen(iSerial);
60847   db = sqlite3_context_db_handle(context);
60848 
60849   nRet = 1 + nSerial + nVal;
60850   aRet = sqlite3DbMallocRaw(db, nRet);
60851   if( aRet==0 ){
60852     sqlite3_result_error_nomem(context);
60853   }else{
60854     aRet[0] = nSerial+1;
60855     sqlite3PutVarint(&aRet[1], iSerial);
60856     sqlite3VdbeSerialPut(&aRet[1+nSerial], nVal, argv[0], file_format);
60857     sqlite3_result_blob(context, aRet, nRet, SQLITE_TRANSIENT);
60858     sqlite3DbFree(db, aRet);
60859   }
60860 }
60861 
60862 /*
60863 ** Register built-in functions used to help read ANALYZE data.
60864 */
60865 SQLITE_PRIVATE void sqlite3AnalyzeFunctions(void){
60866   static SQLITE_WSD FuncDef aAnalyzeTableFuncs[] = {
60867     FUNCTION(sqlite_record,   1, 0, 0, recordFunc),
60868   };
60869   int i;
60870   FuncDefHash *pHash = &GLOBAL(FuncDefHash, sqlite3GlobalFunctions);
60871   FuncDef *aFunc = (FuncDef*)&GLOBAL(FuncDef, aAnalyzeTableFuncs);
60872   for(i=0; i<ArraySize(aAnalyzeTableFuncs); i++){
60873     sqlite3FuncDefInsert(pHash, &aFunc[i]);
60874   }
60875 }
60876 
60877 /*
60878 ** This function is used to allocate and populate UnpackedRecord 
60879 ** structures intended to be compared against sample index keys stored 
60880 ** in the sqlite_stat4 table.
60881 **
60882 ** A single call to this function attempts to populates field iVal (leftmost 
60883 ** is 0 etc.) of the unpacked record with a value extracted from expression
60884 ** pExpr. Extraction of values is possible if:
60885 **
60886 **  * (pExpr==0). In this case the value is assumed to be an SQL NULL,
60887 **
60888 **  * The expression is a bound variable, and this is a reprepare, or
60889 **
60890 **  * The sqlite3ValueFromExpr() function is able to extract a value 
60891 **    from the expression (i.e. the expression is a literal value).
60892 **
60893 ** If a value can be extracted, the affinity passed as the 5th argument
60894 ** is applied to it before it is copied into the UnpackedRecord. Output
60895 ** parameter *pbOk is set to true if a value is extracted, or false 
60896 ** otherwise.
60897 **
60898 ** When this function is called, *ppRec must either point to an object
60899 ** allocated by an earlier call to this function, or must be NULL. If it
60900 ** is NULL and a value can be successfully extracted, a new UnpackedRecord
60901 ** is allocated (and *ppRec set to point to it) before returning.
60902 **
60903 ** Unless an error is encountered, SQLITE_OK is returned. It is not an
60904 ** error if a value cannot be extracted from pExpr. If an error does
60905 ** occur, an SQLite error code is returned.
60906 */
60907 SQLITE_PRIVATE int sqlite3Stat4ProbeSetValue(
60908   Parse *pParse,                  /* Parse context */
60909   Index *pIdx,                    /* Index being probed */
60910   UnpackedRecord **ppRec,         /* IN/OUT: Probe record */
60911   Expr *pExpr,                    /* The expression to extract a value from */
60912   u8 affinity,                    /* Affinity to use */
60913   int iVal,                       /* Array element to populate */
60914   int *pbOk                       /* OUT: True if value was extracted */
60915 ){
60916   int rc = SQLITE_OK;
60917   sqlite3_value *pVal = 0;
60918   sqlite3 *db = pParse->db;
60919 
60920 
60921   struct ValueNewStat4Ctx alloc;
60922   alloc.pParse = pParse;
60923   alloc.pIdx = pIdx;
60924   alloc.ppRec = ppRec;
60925   alloc.iVal = iVal;
60926 
60927   /* Skip over any TK_COLLATE nodes */
60928   pExpr = sqlite3ExprSkipCollate(pExpr);
60929 
60930   if( !pExpr ){
60931     pVal = valueNew(db, &alloc);
60932     if( pVal ){
60933       sqlite3VdbeMemSetNull((Mem*)pVal);
60934     }
60935   }else if( pExpr->op==TK_VARIABLE
60936         || NEVER(pExpr->op==TK_REGISTER && pExpr->op2==TK_VARIABLE)
60937   ){
60938     Vdbe *v;
60939     int iBindVar = pExpr->iColumn;
60940     sqlite3VdbeSetVarmask(pParse->pVdbe, iBindVar);
60941     if( (v = pParse->pReprepare)!=0 ){
60942       pVal = valueNew(db, &alloc);
60943       if( pVal ){
60944         rc = sqlite3VdbeMemCopy((Mem*)pVal, &v->aVar[iBindVar-1]);
60945         if( rc==SQLITE_OK ){
60946           sqlite3ValueApplyAffinity(pVal, affinity, ENC(db));
60947         }
60948         pVal->db = pParse->db;
60949         sqlite3VdbeMemStoreType((Mem*)pVal);
60950       }
60951     }
60952   }else{
60953     rc = valueFromExpr(db, pExpr, ENC(db), affinity, &pVal, &alloc);
60954   }
60955   *pbOk = (pVal!=0);
60956 
60957   assert( pVal==0 || pVal->db==db );
60958   return rc;
60959 }
60960 
60961 /*
60962 ** Unless it is NULL, the argument must be an UnpackedRecord object returned
60963 ** by an earlier call to sqlite3Stat4ProbeSetValue(). This call deletes
60964 ** the object.
60965 */
60966 SQLITE_PRIVATE void sqlite3Stat4ProbeFree(UnpackedRecord *pRec){
60967   if( pRec ){
60968     int i;
60969     int nCol = pRec->pKeyInfo->nField+pRec->pKeyInfo->nXField;
60970     Mem *aMem = pRec->aMem;
60971     sqlite3 *db = aMem[0].db;
60972     for(i=0; i<nCol; i++){
60973       sqlite3DbFree(db, aMem[i].zMalloc);
60974     }
60975     sqlite3KeyInfoUnref(pRec->pKeyInfo);
60976     sqlite3DbFree(db, pRec);
60977   }
60978 }
60979 #endif /* ifdef SQLITE_ENABLE_STAT4 */
60980 
60981 /*
60982 ** Change the string value of an sqlite3_value object
60983 */
60984 SQLITE_PRIVATE void sqlite3ValueSetStr(
60985   sqlite3_value *v,     /* Value to be set */
60986   int n,                /* Length of string z */
60987   const void *z,        /* Text of the new string */
60988   u8 enc,               /* Encoding to use */
60989   void (*xDel)(void*)   /* Destructor for the string */
60990 ){
60991   if( v ) sqlite3VdbeMemSetStr((Mem *)v, z, n, enc, xDel);
60992 }
60993 
60994 /*
60995 ** Free an sqlite3_value object
60996 */
60997 SQLITE_PRIVATE void sqlite3ValueFree(sqlite3_value *v){
60998   if( !v ) return;
60999   sqlite3VdbeMemRelease((Mem *)v);
61000   sqlite3DbFree(((Mem*)v)->db, v);
61001 }
61002 
61003 /*
61004 ** Return the number of bytes in the sqlite3_value object assuming
61005 ** that it uses the encoding "enc"
61006 */
61007 SQLITE_PRIVATE int sqlite3ValueBytes(sqlite3_value *pVal, u8 enc){
61008   Mem *p = (Mem*)pVal;
61009   if( (p->flags & MEM_Blob)!=0 || sqlite3ValueText(pVal, enc) ){
61010     if( p->flags & MEM_Zero ){
61011       return p->n + p->u.nZero;
61012     }else{
61013       return p->n;
61014     }
61015   }
61016   return 0;
61017 }
61018 
61019 /************** End of vdbemem.c *********************************************/
61020 /************** Begin file vdbeaux.c *****************************************/
61021 /*
61022 ** 2003 September 6
61023 **
61024 ** The author disclaims copyright to this source code.  In place of
61025 ** a legal notice, here is a blessing:
61026 **
61027 **    May you do good and not evil.
61028 **    May you find forgiveness for yourself and forgive others.
61029 **    May you share freely, never taking more than you give.
61030 **
61031 *************************************************************************
61032 ** This file contains code used for creating, destroying, and populating
61033 ** a VDBE (or an "sqlite3_stmt" as it is known to the outside world.)  Prior
61034 ** to version 2.8.7, all this code was combined into the vdbe.c source file.
61035 ** But that file was getting too big so this subroutines were split out.
61036 */
61037 
61038 /*
61039 ** Create a new virtual database engine.
61040 */
61041 SQLITE_PRIVATE Vdbe *sqlite3VdbeCreate(sqlite3 *db){
61042   Vdbe *p;
61043   p = sqlite3DbMallocZero(db, sizeof(Vdbe) );
61044   if( p==0 ) return 0;
61045   p->db = db;
61046   if( db->pVdbe ){
61047     db->pVdbe->pPrev = p;
61048   }
61049   p->pNext = db->pVdbe;
61050   p->pPrev = 0;
61051   db->pVdbe = p;
61052   p->magic = VDBE_MAGIC_INIT;
61053   return p;
61054 }
61055 
61056 /*
61057 ** Remember the SQL string for a prepared statement.
61058 */
61059 SQLITE_PRIVATE void sqlite3VdbeSetSql(Vdbe *p, const char *z, int n, int isPrepareV2){
61060   assert( isPrepareV2==1 || isPrepareV2==0 );
61061   if( p==0 ) return;
61062 #if defined(SQLITE_OMIT_TRACE) && !defined(SQLITE_ENABLE_SQLLOG)
61063   if( !isPrepareV2 ) return;
61064 #endif
61065   assert( p->zSql==0 );
61066   p->zSql = sqlite3DbStrNDup(p->db, z, n);
61067   p->isPrepareV2 = (u8)isPrepareV2;
61068 }
61069 
61070 /*
61071 ** Return the SQL associated with a prepared statement
61072 */
61073 SQLITE_API const char *sqlite3_sql(sqlite3_stmt *pStmt){
61074   Vdbe *p = (Vdbe *)pStmt;
61075   return (p && p->isPrepareV2) ? p->zSql : 0;
61076 }
61077 
61078 /*
61079 ** Swap all content between two VDBE structures.
61080 */
61081 SQLITE_PRIVATE void sqlite3VdbeSwap(Vdbe *pA, Vdbe *pB){
61082   Vdbe tmp, *pTmp;
61083   char *zTmp;
61084   tmp = *pA;
61085   *pA = *pB;
61086   *pB = tmp;
61087   pTmp = pA->pNext;
61088   pA->pNext = pB->pNext;
61089   pB->pNext = pTmp;
61090   pTmp = pA->pPrev;
61091   pA->pPrev = pB->pPrev;
61092   pB->pPrev = pTmp;
61093   zTmp = pA->zSql;
61094   pA->zSql = pB->zSql;
61095   pB->zSql = zTmp;
61096   pB->isPrepareV2 = pA->isPrepareV2;
61097 }
61098 
61099 /*
61100 ** Resize the Vdbe.aOp array so that it is at least one op larger than 
61101 ** it was.
61102 **
61103 ** If an out-of-memory error occurs while resizing the array, return
61104 ** SQLITE_NOMEM. In this case Vdbe.aOp and Vdbe.nOpAlloc remain 
61105 ** unchanged (this is so that any opcodes already allocated can be 
61106 ** correctly deallocated along with the rest of the Vdbe).
61107 */
61108 static int growOpArray(Vdbe *p){
61109   VdbeOp *pNew;
61110   int nNew = (p->nOpAlloc ? p->nOpAlloc*2 : (int)(1024/sizeof(Op)));
61111   pNew = sqlite3DbRealloc(p->db, p->aOp, nNew*sizeof(Op));
61112   if( pNew ){
61113     p->nOpAlloc = sqlite3DbMallocSize(p->db, pNew)/sizeof(Op);
61114     p->aOp = pNew;
61115   }
61116   return (pNew ? SQLITE_OK : SQLITE_NOMEM);
61117 }
61118 
61119 #ifdef SQLITE_DEBUG
61120 /* This routine is just a convenient place to set a breakpoint that will
61121 ** fire after each opcode is inserted and displayed using
61122 ** "PRAGMA vdbe_addoptrace=on".
61123 */
61124 static void test_addop_breakpoint(void){
61125   static int n = 0;
61126   n++;
61127 }
61128 #endif
61129 
61130 /*
61131 ** Add a new instruction to the list of instructions current in the
61132 ** VDBE.  Return the address of the new instruction.
61133 **
61134 ** Parameters:
61135 **
61136 **    p               Pointer to the VDBE
61137 **
61138 **    op              The opcode for this instruction
61139 **
61140 **    p1, p2, p3      Operands
61141 **
61142 ** Use the sqlite3VdbeResolveLabel() function to fix an address and
61143 ** the sqlite3VdbeChangeP4() function to change the value of the P4
61144 ** operand.
61145 */
61146 SQLITE_PRIVATE int sqlite3VdbeAddOp3(Vdbe *p, int op, int p1, int p2, int p3){
61147   int i;
61148   VdbeOp *pOp;
61149 
61150   i = p->nOp;
61151   assert( p->magic==VDBE_MAGIC_INIT );
61152   assert( op>0 && op<0xff );
61153   if( p->nOpAlloc<=i ){
61154     if( growOpArray(p) ){
61155       return 1;
61156     }
61157   }
61158   p->nOp++;
61159   pOp = &p->aOp[i];
61160   pOp->opcode = (u8)op;
61161   pOp->p5 = 0;
61162   pOp->p1 = p1;
61163   pOp->p2 = p2;
61164   pOp->p3 = p3;
61165   pOp->p4.p = 0;
61166   pOp->p4type = P4_NOTUSED;
61167 #ifdef SQLITE_ENABLE_EXPLAIN_COMMENTS
61168   pOp->zComment = 0;
61169 #endif
61170 #ifdef SQLITE_DEBUG
61171   if( p->db->flags & SQLITE_VdbeAddopTrace ){
61172     sqlite3VdbePrintOp(0, i, &p->aOp[i]);
61173     test_addop_breakpoint();
61174   }
61175 #endif
61176 #ifdef VDBE_PROFILE
61177   pOp->cycles = 0;
61178   pOp->cnt = 0;
61179 #endif
61180   return i;
61181 }
61182 SQLITE_PRIVATE int sqlite3VdbeAddOp0(Vdbe *p, int op){
61183   return sqlite3VdbeAddOp3(p, op, 0, 0, 0);
61184 }
61185 SQLITE_PRIVATE int sqlite3VdbeAddOp1(Vdbe *p, int op, int p1){
61186   return sqlite3VdbeAddOp3(p, op, p1, 0, 0);
61187 }
61188 SQLITE_PRIVATE int sqlite3VdbeAddOp2(Vdbe *p, int op, int p1, int p2){
61189   return sqlite3VdbeAddOp3(p, op, p1, p2, 0);
61190 }
61191 
61192 
61193 /*
61194 ** Add an opcode that includes the p4 value as a pointer.
61195 */
61196 SQLITE_PRIVATE int sqlite3VdbeAddOp4(
61197   Vdbe *p,            /* Add the opcode to this VM */
61198   int op,             /* The new opcode */
61199   int p1,             /* The P1 operand */
61200   int p2,             /* The P2 operand */
61201   int p3,             /* The P3 operand */
61202   const char *zP4,    /* The P4 operand */
61203   int p4type          /* P4 operand type */
61204 ){
61205   int addr = sqlite3VdbeAddOp3(p, op, p1, p2, p3);
61206   sqlite3VdbeChangeP4(p, addr, zP4, p4type);
61207   return addr;
61208 }
61209 
61210 /*
61211 ** Add an OP_ParseSchema opcode.  This routine is broken out from
61212 ** sqlite3VdbeAddOp4() since it needs to also needs to mark all btrees
61213 ** as having been used.
61214 **
61215 ** The zWhere string must have been obtained from sqlite3_malloc().
61216 ** This routine will take ownership of the allocated memory.
61217 */
61218 SQLITE_PRIVATE void sqlite3VdbeAddParseSchemaOp(Vdbe *p, int iDb, char *zWhere){
61219   int j;
61220   int addr = sqlite3VdbeAddOp3(p, OP_ParseSchema, iDb, 0, 0);
61221   sqlite3VdbeChangeP4(p, addr, zWhere, P4_DYNAMIC);
61222   for(j=0; j<p->db->nDb; j++) sqlite3VdbeUsesBtree(p, j);
61223 }
61224 
61225 /*
61226 ** Add an opcode that includes the p4 value as an integer.
61227 */
61228 SQLITE_PRIVATE int sqlite3VdbeAddOp4Int(
61229   Vdbe *p,            /* Add the opcode to this VM */
61230   int op,             /* The new opcode */
61231   int p1,             /* The P1 operand */
61232   int p2,             /* The P2 operand */
61233   int p3,             /* The P3 operand */
61234   int p4              /* The P4 operand as an integer */
61235 ){
61236   int addr = sqlite3VdbeAddOp3(p, op, p1, p2, p3);
61237   sqlite3VdbeChangeP4(p, addr, SQLITE_INT_TO_PTR(p4), P4_INT32);
61238   return addr;
61239 }
61240 
61241 /*
61242 ** Create a new symbolic label for an instruction that has yet to be
61243 ** coded.  The symbolic label is really just a negative number.  The
61244 ** label can be used as the P2 value of an operation.  Later, when
61245 ** the label is resolved to a specific address, the VDBE will scan
61246 ** through its operation list and change all values of P2 which match
61247 ** the label into the resolved address.
61248 **
61249 ** The VDBE knows that a P2 value is a label because labels are
61250 ** always negative and P2 values are suppose to be non-negative.
61251 ** Hence, a negative P2 value is a label that has yet to be resolved.
61252 **
61253 ** Zero is returned if a malloc() fails.
61254 */
61255 SQLITE_PRIVATE int sqlite3VdbeMakeLabel(Vdbe *p){
61256   int i = p->nLabel++;
61257   assert( p->magic==VDBE_MAGIC_INIT );
61258   if( (i & (i-1))==0 ){
61259     p->aLabel = sqlite3DbReallocOrFree(p->db, p->aLabel, 
61260                                        (i*2+1)*sizeof(p->aLabel[0]));
61261   }
61262   if( p->aLabel ){
61263     p->aLabel[i] = -1;
61264   }
61265   return -1-i;
61266 }
61267 
61268 /*
61269 ** Resolve label "x" to be the address of the next instruction to
61270 ** be inserted.  The parameter "x" must have been obtained from
61271 ** a prior call to sqlite3VdbeMakeLabel().
61272 */
61273 SQLITE_PRIVATE void sqlite3VdbeResolveLabel(Vdbe *p, int x){
61274   int j = -1-x;
61275   assert( p->magic==VDBE_MAGIC_INIT );
61276   assert( j<p->nLabel );
61277   if( j>=0 && p->aLabel ){
61278     p->aLabel[j] = p->nOp;
61279   }
61280 }
61281 
61282 /*
61283 ** Mark the VDBE as one that can only be run one time.
61284 */
61285 SQLITE_PRIVATE void sqlite3VdbeRunOnlyOnce(Vdbe *p){
61286   p->runOnlyOnce = 1;
61287 }
61288 
61289 #ifdef SQLITE_DEBUG /* sqlite3AssertMayAbort() logic */
61290 
61291 /*
61292 ** The following type and function are used to iterate through all opcodes
61293 ** in a Vdbe main program and each of the sub-programs (triggers) it may 
61294 ** invoke directly or indirectly. It should be used as follows:
61295 **
61296 **   Op *pOp;
61297 **   VdbeOpIter sIter;
61298 **
61299 **   memset(&sIter, 0, sizeof(sIter));
61300 **   sIter.v = v;                            // v is of type Vdbe* 
61301 **   while( (pOp = opIterNext(&sIter)) ){
61302 **     // Do something with pOp
61303 **   }
61304 **   sqlite3DbFree(v->db, sIter.apSub);
61305 ** 
61306 */
61307 typedef struct VdbeOpIter VdbeOpIter;
61308 struct VdbeOpIter {
61309   Vdbe *v;                   /* Vdbe to iterate through the opcodes of */
61310   SubProgram **apSub;        /* Array of subprograms */
61311   int nSub;                  /* Number of entries in apSub */
61312   int iAddr;                 /* Address of next instruction to return */
61313   int iSub;                  /* 0 = main program, 1 = first sub-program etc. */
61314 };
61315 static Op *opIterNext(VdbeOpIter *p){
61316   Vdbe *v = p->v;
61317   Op *pRet = 0;
61318   Op *aOp;
61319   int nOp;
61320 
61321   if( p->iSub<=p->nSub ){
61322 
61323     if( p->iSub==0 ){
61324       aOp = v->aOp;
61325       nOp = v->nOp;
61326     }else{
61327       aOp = p->apSub[p->iSub-1]->aOp;
61328       nOp = p->apSub[p->iSub-1]->nOp;
61329     }
61330     assert( p->iAddr<nOp );
61331 
61332     pRet = &aOp[p->iAddr];
61333     p->iAddr++;
61334     if( p->iAddr==nOp ){
61335       p->iSub++;
61336       p->iAddr = 0;
61337     }
61338   
61339     if( pRet->p4type==P4_SUBPROGRAM ){
61340       int nByte = (p->nSub+1)*sizeof(SubProgram*);
61341       int j;
61342       for(j=0; j<p->nSub; j++){
61343         if( p->apSub[j]==pRet->p4.pProgram ) break;
61344       }
61345       if( j==p->nSub ){
61346         p->apSub = sqlite3DbReallocOrFree(v->db, p->apSub, nByte);
61347         if( !p->apSub ){
61348           pRet = 0;
61349         }else{
61350           p->apSub[p->nSub++] = pRet->p4.pProgram;
61351         }
61352       }
61353     }
61354   }
61355 
61356   return pRet;
61357 }
61358 
61359 /*
61360 ** Check if the program stored in the VM associated with pParse may
61361 ** throw an ABORT exception (causing the statement, but not entire transaction
61362 ** to be rolled back). This condition is true if the main program or any
61363 ** sub-programs contains any of the following:
61364 **
61365 **   *  OP_Halt with P1=SQLITE_CONSTRAINT and P2=OE_Abort.
61366 **   *  OP_HaltIfNull with P1=SQLITE_CONSTRAINT and P2=OE_Abort.
61367 **   *  OP_Destroy
61368 **   *  OP_VUpdate
61369 **   *  OP_VRename
61370 **   *  OP_FkCounter with P2==0 (immediate foreign key constraint)
61371 **
61372 ** Then check that the value of Parse.mayAbort is true if an
61373 ** ABORT may be thrown, or false otherwise. Return true if it does
61374 ** match, or false otherwise. This function is intended to be used as
61375 ** part of an assert statement in the compiler. Similar to:
61376 **
61377 **   assert( sqlite3VdbeAssertMayAbort(pParse->pVdbe, pParse->mayAbort) );
61378 */
61379 SQLITE_PRIVATE int sqlite3VdbeAssertMayAbort(Vdbe *v, int mayAbort){
61380   int hasAbort = 0;
61381   Op *pOp;
61382   VdbeOpIter sIter;
61383   memset(&sIter, 0, sizeof(sIter));
61384   sIter.v = v;
61385 
61386   while( (pOp = opIterNext(&sIter))!=0 ){
61387     int opcode = pOp->opcode;
61388     if( opcode==OP_Destroy || opcode==OP_VUpdate || opcode==OP_VRename 
61389 #ifndef SQLITE_OMIT_FOREIGN_KEY
61390      || (opcode==OP_FkCounter && pOp->p1==0 && pOp->p2==1) 
61391 #endif
61392      || ((opcode==OP_Halt || opcode==OP_HaltIfNull) 
61393       && ((pOp->p1&0xff)==SQLITE_CONSTRAINT && pOp->p2==OE_Abort))
61394     ){
61395       hasAbort = 1;
61396       break;
61397     }
61398   }
61399   sqlite3DbFree(v->db, sIter.apSub);
61400 
61401   /* Return true if hasAbort==mayAbort. Or if a malloc failure occurred.
61402   ** If malloc failed, then the while() loop above may not have iterated
61403   ** through all opcodes and hasAbort may be set incorrectly. Return
61404   ** true for this case to prevent the assert() in the callers frame
61405   ** from failing.  */
61406   return ( v->db->mallocFailed || hasAbort==mayAbort );
61407 }
61408 #endif /* SQLITE_DEBUG - the sqlite3AssertMayAbort() function */
61409 
61410 /*
61411 ** Loop through the program looking for P2 values that are negative
61412 ** on jump instructions.  Each such value is a label.  Resolve the
61413 ** label by setting the P2 value to its correct non-zero value.
61414 **
61415 ** This routine is called once after all opcodes have been inserted.
61416 **
61417 ** Variable *pMaxFuncArgs is set to the maximum value of any P2 argument 
61418 ** to an OP_Function, OP_AggStep or OP_VFilter opcode. This is used by 
61419 ** sqlite3VdbeMakeReady() to size the Vdbe.apArg[] array.
61420 **
61421 ** The Op.opflags field is set on all opcodes.
61422 */
61423 static void resolveP2Values(Vdbe *p, int *pMaxFuncArgs){
61424   int i;
61425   int nMaxArgs = *pMaxFuncArgs;
61426   Op *pOp;
61427   int *aLabel = p->aLabel;
61428   p->readOnly = 1;
61429   p->bIsReader = 0;
61430   for(pOp=p->aOp, i=p->nOp-1; i>=0; i--, pOp++){
61431     u8 opcode = pOp->opcode;
61432 
61433     /* NOTE: Be sure to update mkopcodeh.awk when adding or removing
61434     ** cases from this switch! */
61435     switch( opcode ){
61436       case OP_Function:
61437       case OP_AggStep: {
61438         if( pOp->p5>nMaxArgs ) nMaxArgs = pOp->p5;
61439         break;
61440       }
61441       case OP_Transaction: {
61442         if( pOp->p2!=0 ) p->readOnly = 0;
61443         /* fall thru */
61444       }
61445       case OP_AutoCommit:
61446       case OP_Savepoint: {
61447         p->bIsReader = 1;
61448         break;
61449       }
61450 #ifndef SQLITE_OMIT_WAL
61451       case OP_Checkpoint:
61452 #endif
61453       case OP_Vacuum:
61454       case OP_JournalMode: {
61455         p->readOnly = 0;
61456         p->bIsReader = 1;
61457         break;
61458       }
61459 #ifndef SQLITE_OMIT_VIRTUALTABLE
61460       case OP_VUpdate: {
61461         if( pOp->p2>nMaxArgs ) nMaxArgs = pOp->p2;
61462         break;
61463       }
61464       case OP_VFilter: {
61465         int n;
61466         assert( p->nOp - i >= 3 );
61467         assert( pOp[-1].opcode==OP_Integer );
61468         n = pOp[-1].p1;
61469         if( n>nMaxArgs ) nMaxArgs = n;
61470         break;
61471       }
61472 #endif
61473       case OP_Next:
61474       case OP_NextIfOpen:
61475       case OP_SorterNext: {
61476         pOp->p4.xAdvance = sqlite3BtreeNext;
61477         pOp->p4type = P4_ADVANCE;
61478         break;
61479       }
61480       case OP_Prev:
61481       case OP_PrevIfOpen: {
61482         pOp->p4.xAdvance = sqlite3BtreePrevious;
61483         pOp->p4type = P4_ADVANCE;
61484         break;
61485       }
61486     }
61487 
61488     pOp->opflags = sqlite3OpcodeProperty[opcode];
61489     if( (pOp->opflags & OPFLG_JUMP)!=0 && pOp->p2<0 ){
61490       assert( -1-pOp->p2<p->nLabel );
61491       pOp->p2 = aLabel[-1-pOp->p2];
61492     }
61493   }
61494   sqlite3DbFree(p->db, p->aLabel);
61495   p->aLabel = 0;
61496   *pMaxFuncArgs = nMaxArgs;
61497   assert( p->bIsReader!=0 || p->btreeMask==0 );
61498 }
61499 
61500 /*
61501 ** Return the address of the next instruction to be inserted.
61502 */
61503 SQLITE_PRIVATE int sqlite3VdbeCurrentAddr(Vdbe *p){
61504   assert( p->magic==VDBE_MAGIC_INIT );
61505   return p->nOp;
61506 }
61507 
61508 /*
61509 ** This function returns a pointer to the array of opcodes associated with
61510 ** the Vdbe passed as the first argument. It is the callers responsibility
61511 ** to arrange for the returned array to be eventually freed using the 
61512 ** vdbeFreeOpArray() function.
61513 **
61514 ** Before returning, *pnOp is set to the number of entries in the returned
61515 ** array. Also, *pnMaxArg is set to the larger of its current value and 
61516 ** the number of entries in the Vdbe.apArg[] array required to execute the 
61517 ** returned program.
61518 */
61519 SQLITE_PRIVATE VdbeOp *sqlite3VdbeTakeOpArray(Vdbe *p, int *pnOp, int *pnMaxArg){
61520   VdbeOp *aOp = p->aOp;
61521   assert( aOp && !p->db->mallocFailed );
61522 
61523   /* Check that sqlite3VdbeUsesBtree() was not called on this VM */
61524   assert( p->btreeMask==0 );
61525 
61526   resolveP2Values(p, pnMaxArg);
61527   *pnOp = p->nOp;
61528   p->aOp = 0;
61529   return aOp;
61530 }
61531 
61532 /*
61533 ** Add a whole list of operations to the operation stack.  Return the
61534 ** address of the first operation added.
61535 */
61536 SQLITE_PRIVATE int sqlite3VdbeAddOpList(Vdbe *p, int nOp, VdbeOpList const *aOp){
61537   int addr;
61538   assert( p->magic==VDBE_MAGIC_INIT );
61539   if( p->nOp + nOp > p->nOpAlloc && growOpArray(p) ){
61540     return 0;
61541   }
61542   addr = p->nOp;
61543   if( ALWAYS(nOp>0) ){
61544     int i;
61545     VdbeOpList const *pIn = aOp;
61546     for(i=0; i<nOp; i++, pIn++){
61547       int p2 = pIn->p2;
61548       VdbeOp *pOut = &p->aOp[i+addr];
61549       pOut->opcode = pIn->opcode;
61550       pOut->p1 = pIn->p1;
61551       if( p2<0 ){
61552         assert( sqlite3OpcodeProperty[pOut->opcode] & OPFLG_JUMP );
61553         pOut->p2 = addr + ADDR(p2);
61554       }else{
61555         pOut->p2 = p2;
61556       }
61557       pOut->p3 = pIn->p3;
61558       pOut->p4type = P4_NOTUSED;
61559       pOut->p4.p = 0;
61560       pOut->p5 = 0;
61561 #ifdef SQLITE_ENABLE_EXPLAIN_COMMENTS
61562       pOut->zComment = 0;
61563 #endif
61564 #ifdef SQLITE_DEBUG
61565       if( p->db->flags & SQLITE_VdbeAddopTrace ){
61566         sqlite3VdbePrintOp(0, i+addr, &p->aOp[i+addr]);
61567       }
61568 #endif
61569     }
61570     p->nOp += nOp;
61571   }
61572   return addr;
61573 }
61574 
61575 /*
61576 ** Change the value of the P1 operand for a specific instruction.
61577 ** This routine is useful when a large program is loaded from a
61578 ** static array using sqlite3VdbeAddOpList but we want to make a
61579 ** few minor changes to the program.
61580 */
61581 SQLITE_PRIVATE void sqlite3VdbeChangeP1(Vdbe *p, u32 addr, int val){
61582   assert( p!=0 );
61583   if( ((u32)p->nOp)>addr ){
61584     p->aOp[addr].p1 = val;
61585   }
61586 }
61587 
61588 /*
61589 ** Change the value of the P2 operand for a specific instruction.
61590 ** This routine is useful for setting a jump destination.
61591 */
61592 SQLITE_PRIVATE void sqlite3VdbeChangeP2(Vdbe *p, u32 addr, int val){
61593   assert( p!=0 );
61594   if( ((u32)p->nOp)>addr ){
61595     p->aOp[addr].p2 = val;
61596   }
61597 }
61598 
61599 /*
61600 ** Change the value of the P3 operand for a specific instruction.
61601 */
61602 SQLITE_PRIVATE void sqlite3VdbeChangeP3(Vdbe *p, u32 addr, int val){
61603   assert( p!=0 );
61604   if( ((u32)p->nOp)>addr ){
61605     p->aOp[addr].p3 = val;
61606   }
61607 }
61608 
61609 /*
61610 ** Change the value of the P5 operand for the most recently
61611 ** added operation.
61612 */
61613 SQLITE_PRIVATE void sqlite3VdbeChangeP5(Vdbe *p, u8 val){
61614   assert( p!=0 );
61615   if( p->aOp ){
61616     assert( p->nOp>0 );
61617     p->aOp[p->nOp-1].p5 = val;
61618   }
61619 }
61620 
61621 /*
61622 ** Change the P2 operand of instruction addr so that it points to
61623 ** the address of the next instruction to be coded.
61624 */
61625 SQLITE_PRIVATE void sqlite3VdbeJumpHere(Vdbe *p, int addr){
61626   if( ALWAYS(addr>=0) ) sqlite3VdbeChangeP2(p, addr, p->nOp);
61627 }
61628 
61629 
61630 /*
61631 ** If the input FuncDef structure is ephemeral, then free it.  If
61632 ** the FuncDef is not ephermal, then do nothing.
61633 */
61634 static void freeEphemeralFunction(sqlite3 *db, FuncDef *pDef){
61635   if( ALWAYS(pDef) && (pDef->funcFlags & SQLITE_FUNC_EPHEM)!=0 ){
61636     sqlite3DbFree(db, pDef);
61637   }
61638 }
61639 
61640 static void vdbeFreeOpArray(sqlite3 *, Op *, int);
61641 
61642 /*
61643 ** Delete a P4 value if necessary.
61644 */
61645 static void freeP4(sqlite3 *db, int p4type, void *p4){
61646   if( p4 ){
61647     assert( db );
61648     switch( p4type ){
61649       case P4_REAL:
61650       case P4_INT64:
61651       case P4_DYNAMIC:
61652       case P4_INTARRAY: {
61653         sqlite3DbFree(db, p4);
61654         break;
61655       }
61656       case P4_KEYINFO: {
61657         if( db->pnBytesFreed==0 ) sqlite3KeyInfoUnref((KeyInfo*)p4);
61658         break;
61659       }
61660       case P4_MPRINTF: {
61661         if( db->pnBytesFreed==0 ) sqlite3_free(p4);
61662         break;
61663       }
61664       case P4_FUNCDEF: {
61665         freeEphemeralFunction(db, (FuncDef*)p4);
61666         break;
61667       }
61668       case P4_MEM: {
61669         if( db->pnBytesFreed==0 ){
61670           sqlite3ValueFree((sqlite3_value*)p4);
61671         }else{
61672           Mem *p = (Mem*)p4;
61673           sqlite3DbFree(db, p->zMalloc);
61674           sqlite3DbFree(db, p);
61675         }
61676         break;
61677       }
61678       case P4_VTAB : {
61679         if( db->pnBytesFreed==0 ) sqlite3VtabUnlock((VTable *)p4);
61680         break;
61681       }
61682     }
61683   }
61684 }
61685 
61686 /*
61687 ** Free the space allocated for aOp and any p4 values allocated for the
61688 ** opcodes contained within. If aOp is not NULL it is assumed to contain 
61689 ** nOp entries. 
61690 */
61691 static void vdbeFreeOpArray(sqlite3 *db, Op *aOp, int nOp){
61692   if( aOp ){
61693     Op *pOp;
61694     for(pOp=aOp; pOp<&aOp[nOp]; pOp++){
61695       freeP4(db, pOp->p4type, pOp->p4.p);
61696 #ifdef SQLITE_ENABLE_EXPLAIN_COMMENTS
61697       sqlite3DbFree(db, pOp->zComment);
61698 #endif     
61699     }
61700   }
61701   sqlite3DbFree(db, aOp);
61702 }
61703 
61704 /*
61705 ** Link the SubProgram object passed as the second argument into the linked
61706 ** list at Vdbe.pSubProgram. This list is used to delete all sub-program
61707 ** objects when the VM is no longer required.
61708 */
61709 SQLITE_PRIVATE void sqlite3VdbeLinkSubProgram(Vdbe *pVdbe, SubProgram *p){
61710   p->pNext = pVdbe->pProgram;
61711   pVdbe->pProgram = p;
61712 }
61713 
61714 /*
61715 ** Change the opcode at addr into OP_Noop
61716 */
61717 SQLITE_PRIVATE void sqlite3VdbeChangeToNoop(Vdbe *p, int addr){
61718   if( p->aOp ){
61719     VdbeOp *pOp = &p->aOp[addr];
61720     sqlite3 *db = p->db;
61721     freeP4(db, pOp->p4type, pOp->p4.p);
61722     memset(pOp, 0, sizeof(pOp[0]));
61723     pOp->opcode = OP_Noop;
61724     if( addr==p->nOp-1 ) p->nOp--;
61725   }
61726 }
61727 
61728 /*
61729 ** Change the value of the P4 operand for a specific instruction.
61730 ** This routine is useful when a large program is loaded from a
61731 ** static array using sqlite3VdbeAddOpList but we want to make a
61732 ** few minor changes to the program.
61733 **
61734 ** If n>=0 then the P4 operand is dynamic, meaning that a copy of
61735 ** the string is made into memory obtained from sqlite3_malloc().
61736 ** A value of n==0 means copy bytes of zP4 up to and including the
61737 ** first null byte.  If n>0 then copy n+1 bytes of zP4.
61738 ** 
61739 ** Other values of n (P4_STATIC, P4_COLLSEQ etc.) indicate that zP4 points
61740 ** to a string or structure that is guaranteed to exist for the lifetime of
61741 ** the Vdbe. In these cases we can just copy the pointer.
61742 **
61743 ** If addr<0 then change P4 on the most recently inserted instruction.
61744 */
61745 SQLITE_PRIVATE void sqlite3VdbeChangeP4(Vdbe *p, int addr, const char *zP4, int n){
61746   Op *pOp;
61747   sqlite3 *db;
61748   assert( p!=0 );
61749   db = p->db;
61750   assert( p->magic==VDBE_MAGIC_INIT );
61751   if( p->aOp==0 || db->mallocFailed ){
61752     if( n!=P4_VTAB ){
61753       freeP4(db, n, (void*)*(char**)&zP4);
61754     }
61755     return;
61756   }
61757   assert( p->nOp>0 );
61758   assert( addr<p->nOp );
61759   if( addr<0 ){
61760     addr = p->nOp - 1;
61761   }
61762   pOp = &p->aOp[addr];
61763   assert( pOp->p4type==P4_NOTUSED || pOp->p4type==P4_INT32 );
61764   freeP4(db, pOp->p4type, pOp->p4.p);
61765   pOp->p4.p = 0;
61766   if( n==P4_INT32 ){
61767     /* Note: this cast is safe, because the origin data point was an int
61768     ** that was cast to a (const char *). */
61769     pOp->p4.i = SQLITE_PTR_TO_INT(zP4);
61770     pOp->p4type = P4_INT32;
61771   }else if( zP4==0 ){
61772     pOp->p4.p = 0;
61773     pOp->p4type = P4_NOTUSED;
61774   }else if( n==P4_KEYINFO ){
61775     pOp->p4.p = (void*)zP4;
61776     pOp->p4type = P4_KEYINFO;
61777   }else if( n==P4_VTAB ){
61778     pOp->p4.p = (void*)zP4;
61779     pOp->p4type = P4_VTAB;
61780     sqlite3VtabLock((VTable *)zP4);
61781     assert( ((VTable *)zP4)->db==p->db );
61782   }else if( n<0 ){
61783     pOp->p4.p = (void*)zP4;
61784     pOp->p4type = (signed char)n;
61785   }else{
61786     if( n==0 ) n = sqlite3Strlen30(zP4);
61787     pOp->p4.z = sqlite3DbStrNDup(p->db, zP4, n);
61788     pOp->p4type = P4_DYNAMIC;
61789   }
61790 }
61791 
61792 /*
61793 ** Set the P4 on the most recently added opcode to the KeyInfo for the
61794 ** index given.
61795 */
61796 SQLITE_PRIVATE void sqlite3VdbeSetP4KeyInfo(Parse *pParse, Index *pIdx){
61797   Vdbe *v = pParse->pVdbe;
61798   assert( v!=0 );
61799   assert( pIdx!=0 );
61800   sqlite3VdbeChangeP4(v, -1, (char*)sqlite3KeyInfoOfIndex(pParse, pIdx),
61801                       P4_KEYINFO);
61802 }
61803 
61804 #ifdef SQLITE_ENABLE_EXPLAIN_COMMENTS
61805 /*
61806 ** Change the comment on the most recently coded instruction.  Or
61807 ** insert a No-op and add the comment to that new instruction.  This
61808 ** makes the code easier to read during debugging.  None of this happens
61809 ** in a production build.
61810 */
61811 static void vdbeVComment(Vdbe *p, const char *zFormat, va_list ap){
61812   assert( p->nOp>0 || p->aOp==0 );
61813   assert( p->aOp==0 || p->aOp[p->nOp-1].zComment==0 || p->db->mallocFailed );
61814   if( p->nOp ){
61815     assert( p->aOp );
61816     sqlite3DbFree(p->db, p->aOp[p->nOp-1].zComment);
61817     p->aOp[p->nOp-1].zComment = sqlite3VMPrintf(p->db, zFormat, ap);
61818   }
61819 }
61820 SQLITE_PRIVATE void sqlite3VdbeComment(Vdbe *p, const char *zFormat, ...){
61821   va_list ap;
61822   if( p ){
61823     va_start(ap, zFormat);
61824     vdbeVComment(p, zFormat, ap);
61825     va_end(ap);
61826   }
61827 }
61828 SQLITE_PRIVATE void sqlite3VdbeNoopComment(Vdbe *p, const char *zFormat, ...){
61829   va_list ap;
61830   if( p ){
61831     sqlite3VdbeAddOp0(p, OP_Noop);
61832     va_start(ap, zFormat);
61833     vdbeVComment(p, zFormat, ap);
61834     va_end(ap);
61835   }
61836 }
61837 #endif  /* NDEBUG */
61838 
61839 /*
61840 ** Return the opcode for a given address.  If the address is -1, then
61841 ** return the most recently inserted opcode.
61842 **
61843 ** If a memory allocation error has occurred prior to the calling of this
61844 ** routine, then a pointer to a dummy VdbeOp will be returned.  That opcode
61845 ** is readable but not writable, though it is cast to a writable value.
61846 ** The return of a dummy opcode allows the call to continue functioning
61847 ** after a OOM fault without having to check to see if the return from 
61848 ** this routine is a valid pointer.  But because the dummy.opcode is 0,
61849 ** dummy will never be written to.  This is verified by code inspection and
61850 ** by running with Valgrind.
61851 **
61852 ** About the #ifdef SQLITE_OMIT_TRACE:  Normally, this routine is never called
61853 ** unless p->nOp>0.  This is because in the absense of SQLITE_OMIT_TRACE,
61854 ** an OP_Trace instruction is always inserted by sqlite3VdbeGet() as soon as
61855 ** a new VDBE is created.  So we are free to set addr to p->nOp-1 without
61856 ** having to double-check to make sure that the result is non-negative. But
61857 ** if SQLITE_OMIT_TRACE is defined, the OP_Trace is omitted and we do need to
61858 ** check the value of p->nOp-1 before continuing.
61859 */
61860 SQLITE_PRIVATE VdbeOp *sqlite3VdbeGetOp(Vdbe *p, int addr){
61861   /* C89 specifies that the constant "dummy" will be initialized to all
61862   ** zeros, which is correct.  MSVC generates a warning, nevertheless. */
61863   static VdbeOp dummy;  /* Ignore the MSVC warning about no initializer */
61864   assert( p->magic==VDBE_MAGIC_INIT );
61865   if( addr<0 ){
61866 #ifdef SQLITE_OMIT_TRACE
61867     if( p->nOp==0 ) return (VdbeOp*)&dummy;
61868 #endif
61869     addr = p->nOp - 1;
61870   }
61871   assert( (addr>=0 && addr<p->nOp) || p->db->mallocFailed );
61872   if( p->db->mallocFailed ){
61873     return (VdbeOp*)&dummy;
61874   }else{
61875     return &p->aOp[addr];
61876   }
61877 }
61878 
61879 #if defined(SQLITE_ENABLE_EXPLAIN_COMMENTS)
61880 /*
61881 ** Return an integer value for one of the parameters to the opcode pOp
61882 ** determined by character c.
61883 */
61884 static int translateP(char c, const Op *pOp){
61885   if( c=='1' ) return pOp->p1;
61886   if( c=='2' ) return pOp->p2;
61887   if( c=='3' ) return pOp->p3;
61888   if( c=='4' ) return pOp->p4.i;
61889   return pOp->p5;
61890 }
61891 
61892 /*
61893 ** Compute a string for the "comment" field of a VDBE opcode listing
61894 */
61895 static int displayComment(
61896   const Op *pOp,     /* The opcode to be commented */
61897   const char *zP4,   /* Previously obtained value for P4 */
61898   char *zTemp,       /* Write result here */
61899   int nTemp          /* Space available in zTemp[] */
61900 ){
61901   const char *zOpName;
61902   const char *zSynopsis;
61903   int nOpName;
61904   int ii, jj;
61905   zOpName = sqlite3OpcodeName(pOp->opcode);
61906   nOpName = sqlite3Strlen30(zOpName);
61907   if( zOpName[nOpName+1] ){
61908     int seenCom = 0;
61909     char c;
61910     zSynopsis = zOpName += nOpName + 1;
61911     for(ii=jj=0; jj<nTemp-1 && (c = zSynopsis[ii])!=0; ii++){
61912       if( c=='P' ){
61913         c = zSynopsis[++ii];
61914         if( c=='4' ){
61915           sqlite3_snprintf(nTemp-jj, zTemp+jj, "%s", zP4);
61916         }else if( c=='X' ){
61917           sqlite3_snprintf(nTemp-jj, zTemp+jj, "%s", pOp->zComment);
61918           seenCom = 1;
61919         }else{
61920           int v1 = translateP(c, pOp);
61921           int v2;
61922           sqlite3_snprintf(nTemp-jj, zTemp+jj, "%d", v1);
61923           if( strncmp(zSynopsis+ii+1, "@P", 2)==0 ){
61924             ii += 3;
61925             jj += sqlite3Strlen30(zTemp+jj);
61926             v2 = translateP(zSynopsis[ii], pOp);
61927             if( v2>1 ) sqlite3_snprintf(nTemp-jj, zTemp+jj, "..%d", v1+v2-1);
61928           }else if( strncmp(zSynopsis+ii+1, "..P3", 4)==0 && pOp->p3==0 ){
61929             ii += 4;
61930           }
61931         }
61932         jj += sqlite3Strlen30(zTemp+jj);
61933       }else{
61934         zTemp[jj++] = c;
61935       }
61936     }
61937     if( !seenCom && jj<nTemp-5 && pOp->zComment ){
61938       sqlite3_snprintf(nTemp-jj, zTemp+jj, "; %s", pOp->zComment);
61939       jj += sqlite3Strlen30(zTemp+jj);
61940     }
61941     if( jj<nTemp ) zTemp[jj] = 0;
61942   }else if( pOp->zComment ){
61943     sqlite3_snprintf(nTemp, zTemp, "%s", pOp->zComment);
61944     jj = sqlite3Strlen30(zTemp);
61945   }else{
61946     zTemp[0] = 0;
61947     jj = 0;
61948   }
61949   return jj;
61950 }
61951 #endif /* SQLITE_DEBUG */
61952 
61953 
61954 #if !defined(SQLITE_OMIT_EXPLAIN) || !defined(NDEBUG) \
61955      || defined(VDBE_PROFILE) || defined(SQLITE_DEBUG)
61956 /*
61957 ** Compute a string that describes the P4 parameter for an opcode.
61958 ** Use zTemp for any required temporary buffer space.
61959 */
61960 static char *displayP4(Op *pOp, char *zTemp, int nTemp){
61961   char *zP4 = zTemp;
61962   assert( nTemp>=20 );
61963   switch( pOp->p4type ){
61964     case P4_KEYINFO: {
61965       int i, j;
61966       KeyInfo *pKeyInfo = pOp->p4.pKeyInfo;
61967       assert( pKeyInfo->aSortOrder!=0 );
61968       sqlite3_snprintf(nTemp, zTemp, "k(%d", pKeyInfo->nField);
61969       i = sqlite3Strlen30(zTemp);
61970       for(j=0; j<pKeyInfo->nField; j++){
61971         CollSeq *pColl = pKeyInfo->aColl[j];
61972         const char *zColl = pColl ? pColl->zName : "nil";
61973         int n = sqlite3Strlen30(zColl);
61974         if( n==6 && memcmp(zColl,"BINARY",6)==0 ){
61975           zColl = "B";
61976           n = 1;
61977         }
61978         if( i+n>nTemp-6 ){
61979           memcpy(&zTemp[i],",...",4);
61980           break;
61981         }
61982         zTemp[i++] = ',';
61983         if( pKeyInfo->aSortOrder[j] ){
61984           zTemp[i++] = '-';
61985         }
61986         memcpy(&zTemp[i], zColl, n+1);
61987         i += n;
61988       }
61989       zTemp[i++] = ')';
61990       zTemp[i] = 0;
61991       assert( i<nTemp );
61992       break;
61993     }
61994     case P4_COLLSEQ: {
61995       CollSeq *pColl = pOp->p4.pColl;
61996       sqlite3_snprintf(nTemp, zTemp, "(%.20s)", pColl->zName);
61997       break;
61998     }
61999     case P4_FUNCDEF: {
62000       FuncDef *pDef = pOp->p4.pFunc;
62001       sqlite3_snprintf(nTemp, zTemp, "%s(%d)", pDef->zName, pDef->nArg);
62002       break;
62003     }
62004     case P4_INT64: {
62005       sqlite3_snprintf(nTemp, zTemp, "%lld", *pOp->p4.pI64);
62006       break;
62007     }
62008     case P4_INT32: {
62009       sqlite3_snprintf(nTemp, zTemp, "%d", pOp->p4.i);
62010       break;
62011     }
62012     case P4_REAL: {
62013       sqlite3_snprintf(nTemp, zTemp, "%.16g", *pOp->p4.pReal);
62014       break;
62015     }
62016     case P4_MEM: {
62017       Mem *pMem = pOp->p4.pMem;
62018       if( pMem->flags & MEM_Str ){
62019         zP4 = pMem->z;
62020       }else if( pMem->flags & MEM_Int ){
62021         sqlite3_snprintf(nTemp, zTemp, "%lld", pMem->u.i);
62022       }else if( pMem->flags & MEM_Real ){
62023         sqlite3_snprintf(nTemp, zTemp, "%.16g", pMem->r);
62024       }else if( pMem->flags & MEM_Null ){
62025         sqlite3_snprintf(nTemp, zTemp, "NULL");
62026       }else{
62027         assert( pMem->flags & MEM_Blob );
62028         zP4 = "(blob)";
62029       }
62030       break;
62031     }
62032 #ifndef SQLITE_OMIT_VIRTUALTABLE
62033     case P4_VTAB: {
62034       sqlite3_vtab *pVtab = pOp->p4.pVtab->pVtab;
62035       sqlite3_snprintf(nTemp, zTemp, "vtab:%p:%p", pVtab, pVtab->pModule);
62036       break;
62037     }
62038 #endif
62039     case P4_INTARRAY: {
62040       sqlite3_snprintf(nTemp, zTemp, "intarray");
62041       break;
62042     }
62043     case P4_SUBPROGRAM: {
62044       sqlite3_snprintf(nTemp, zTemp, "program");
62045       break;
62046     }
62047     case P4_ADVANCE: {
62048       zTemp[0] = 0;
62049       break;
62050     }
62051     default: {
62052       zP4 = pOp->p4.z;
62053       if( zP4==0 ){
62054         zP4 = zTemp;
62055         zTemp[0] = 0;
62056       }
62057     }
62058   }
62059   assert( zP4!=0 );
62060   return zP4;
62061 }
62062 #endif
62063 
62064 /*
62065 ** Declare to the Vdbe that the BTree object at db->aDb[i] is used.
62066 **
62067 ** The prepared statements need to know in advance the complete set of
62068 ** attached databases that will be use.  A mask of these databases
62069 ** is maintained in p->btreeMask.  The p->lockMask value is the subset of
62070 ** p->btreeMask of databases that will require a lock.
62071 */
62072 SQLITE_PRIVATE void sqlite3VdbeUsesBtree(Vdbe *p, int i){
62073   assert( i>=0 && i<p->db->nDb && i<(int)sizeof(yDbMask)*8 );
62074   assert( i<(int)sizeof(p->btreeMask)*8 );
62075   p->btreeMask |= ((yDbMask)1)<<i;
62076   if( i!=1 && sqlite3BtreeSharable(p->db->aDb[i].pBt) ){
62077     p->lockMask |= ((yDbMask)1)<<i;
62078   }
62079 }
62080 
62081 #if !defined(SQLITE_OMIT_SHARED_CACHE) && SQLITE_THREADSAFE>0
62082 /*
62083 ** If SQLite is compiled to support shared-cache mode and to be threadsafe,
62084 ** this routine obtains the mutex associated with each BtShared structure
62085 ** that may be accessed by the VM passed as an argument. In doing so it also
62086 ** sets the BtShared.db member of each of the BtShared structures, ensuring
62087 ** that the correct busy-handler callback is invoked if required.
62088 **
62089 ** If SQLite is not threadsafe but does support shared-cache mode, then
62090 ** sqlite3BtreeEnter() is invoked to set the BtShared.db variables
62091 ** of all of BtShared structures accessible via the database handle 
62092 ** associated with the VM.
62093 **
62094 ** If SQLite is not threadsafe and does not support shared-cache mode, this
62095 ** function is a no-op.
62096 **
62097 ** The p->btreeMask field is a bitmask of all btrees that the prepared 
62098 ** statement p will ever use.  Let N be the number of bits in p->btreeMask
62099 ** corresponding to btrees that use shared cache.  Then the runtime of
62100 ** this routine is N*N.  But as N is rarely more than 1, this should not
62101 ** be a problem.
62102 */
62103 SQLITE_PRIVATE void sqlite3VdbeEnter(Vdbe *p){
62104   int i;
62105   yDbMask mask;
62106   sqlite3 *db;
62107   Db *aDb;
62108   int nDb;
62109   if( p->lockMask==0 ) return;  /* The common case */
62110   db = p->db;
62111   aDb = db->aDb;
62112   nDb = db->nDb;
62113   for(i=0, mask=1; i<nDb; i++, mask += mask){
62114     if( i!=1 && (mask & p->lockMask)!=0 && ALWAYS(aDb[i].pBt!=0) ){
62115       sqlite3BtreeEnter(aDb[i].pBt);
62116     }
62117   }
62118 }
62119 #endif
62120 
62121 #if !defined(SQLITE_OMIT_SHARED_CACHE) && SQLITE_THREADSAFE>0
62122 /*
62123 ** Unlock all of the btrees previously locked by a call to sqlite3VdbeEnter().
62124 */
62125 SQLITE_PRIVATE void sqlite3VdbeLeave(Vdbe *p){
62126   int i;
62127   yDbMask mask;
62128   sqlite3 *db;
62129   Db *aDb;
62130   int nDb;
62131   if( p->lockMask==0 ) return;  /* The common case */
62132   db = p->db;
62133   aDb = db->aDb;
62134   nDb = db->nDb;
62135   for(i=0, mask=1; i<nDb; i++, mask += mask){
62136     if( i!=1 && (mask & p->lockMask)!=0 && ALWAYS(aDb[i].pBt!=0) ){
62137       sqlite3BtreeLeave(aDb[i].pBt);
62138     }
62139   }
62140 }
62141 #endif
62142 
62143 #if defined(VDBE_PROFILE) || defined(SQLITE_DEBUG)
62144 /*
62145 ** Print a single opcode.  This routine is used for debugging only.
62146 */
62147 SQLITE_PRIVATE void sqlite3VdbePrintOp(FILE *pOut, int pc, Op *pOp){
62148   char *zP4;
62149   char zPtr[50];
62150   char zCom[100];
62151   static const char *zFormat1 = "%4d %-13s %4d %4d %4d %-13s %.2X %s\n";
62152   if( pOut==0 ) pOut = stdout;
62153   zP4 = displayP4(pOp, zPtr, sizeof(zPtr));
62154 #ifdef SQLITE_ENABLE_EXPLAIN_COMMENTS
62155   displayComment(pOp, zP4, zCom, sizeof(zCom));
62156 #else
62157   zCom[0] = 0
62158 #endif
62159   fprintf(pOut, zFormat1, pc, 
62160       sqlite3OpcodeName(pOp->opcode), pOp->p1, pOp->p2, pOp->p3, zP4, pOp->p5,
62161       zCom
62162   );
62163   fflush(pOut);
62164 }
62165 #endif
62166 
62167 /*
62168 ** Release an array of N Mem elements
62169 */
62170 static void releaseMemArray(Mem *p, int N){
62171   if( p && N ){
62172     Mem *pEnd;
62173     sqlite3 *db = p->db;
62174     u8 malloc_failed = db->mallocFailed;
62175     if( db->pnBytesFreed ){
62176       for(pEnd=&p[N]; p<pEnd; p++){
62177         sqlite3DbFree(db, p->zMalloc);
62178       }
62179       return;
62180     }
62181     for(pEnd=&p[N]; p<pEnd; p++){
62182       assert( (&p[1])==pEnd || p[0].db==p[1].db );
62183 
62184       /* This block is really an inlined version of sqlite3VdbeMemRelease()
62185       ** that takes advantage of the fact that the memory cell value is 
62186       ** being set to NULL after releasing any dynamic resources.
62187       **
62188       ** The justification for duplicating code is that according to 
62189       ** callgrind, this causes a certain test case to hit the CPU 4.7 
62190       ** percent less (x86 linux, gcc version 4.1.2, -O6) than if 
62191       ** sqlite3MemRelease() were called from here. With -O2, this jumps
62192       ** to 6.6 percent. The test case is inserting 1000 rows into a table 
62193       ** with no indexes using a single prepared INSERT statement, bind() 
62194       ** and reset(). Inserts are grouped into a transaction.
62195       */
62196       if( p->flags&(MEM_Agg|MEM_Dyn|MEM_Frame|MEM_RowSet) ){
62197         sqlite3VdbeMemRelease(p);
62198       }else if( p->zMalloc ){
62199         sqlite3DbFree(db, p->zMalloc);
62200         p->zMalloc = 0;
62201       }
62202 
62203       p->flags = MEM_Invalid;
62204     }
62205     db->mallocFailed = malloc_failed;
62206   }
62207 }
62208 
62209 /*
62210 ** Delete a VdbeFrame object and its contents. VdbeFrame objects are
62211 ** allocated by the OP_Program opcode in sqlite3VdbeExec().
62212 */
62213 SQLITE_PRIVATE void sqlite3VdbeFrameDelete(VdbeFrame *p){
62214   int i;
62215   Mem *aMem = VdbeFrameMem(p);
62216   VdbeCursor **apCsr = (VdbeCursor **)&aMem[p->nChildMem];
62217   for(i=0; i<p->nChildCsr; i++){
62218     sqlite3VdbeFreeCursor(p->v, apCsr[i]);
62219   }
62220   releaseMemArray(aMem, p->nChildMem);
62221   sqlite3DbFree(p->v->db, p);
62222 }
62223 
62224 #ifndef SQLITE_OMIT_EXPLAIN
62225 /*
62226 ** Give a listing of the program in the virtual machine.
62227 **
62228 ** The interface is the same as sqlite3VdbeExec().  But instead of
62229 ** running the code, it invokes the callback once for each instruction.
62230 ** This feature is used to implement "EXPLAIN".
62231 **
62232 ** When p->explain==1, each instruction is listed.  When
62233 ** p->explain==2, only OP_Explain instructions are listed and these
62234 ** are shown in a different format.  p->explain==2 is used to implement
62235 ** EXPLAIN QUERY PLAN.
62236 **
62237 ** When p->explain==1, first the main program is listed, then each of
62238 ** the trigger subprograms are listed one by one.
62239 */
62240 SQLITE_PRIVATE int sqlite3VdbeList(
62241   Vdbe *p                   /* The VDBE */
62242 ){
62243   int nRow;                            /* Stop when row count reaches this */
62244   int nSub = 0;                        /* Number of sub-vdbes seen so far */
62245   SubProgram **apSub = 0;              /* Array of sub-vdbes */
62246   Mem *pSub = 0;                       /* Memory cell hold array of subprogs */
62247   sqlite3 *db = p->db;                 /* The database connection */
62248   int i;                               /* Loop counter */
62249   int rc = SQLITE_OK;                  /* Return code */
62250   Mem *pMem = &p->aMem[1];             /* First Mem of result set */
62251 
62252   assert( p->explain );
62253   assert( p->magic==VDBE_MAGIC_RUN );
62254   assert( p->rc==SQLITE_OK || p->rc==SQLITE_BUSY || p->rc==SQLITE_NOMEM );
62255 
62256   /* Even though this opcode does not use dynamic strings for
62257   ** the result, result columns may become dynamic if the user calls
62258   ** sqlite3_column_text16(), causing a translation to UTF-16 encoding.
62259   */
62260   releaseMemArray(pMem, 8);
62261   p->pResultSet = 0;
62262 
62263   if( p->rc==SQLITE_NOMEM ){
62264     /* This happens if a malloc() inside a call to sqlite3_column_text() or
62265     ** sqlite3_column_text16() failed.  */
62266     db->mallocFailed = 1;
62267     return SQLITE_ERROR;
62268   }
62269 
62270   /* When the number of output rows reaches nRow, that means the
62271   ** listing has finished and sqlite3_step() should return SQLITE_DONE.
62272   ** nRow is the sum of the number of rows in the main program, plus
62273   ** the sum of the number of rows in all trigger subprograms encountered
62274   ** so far.  The nRow value will increase as new trigger subprograms are
62275   ** encountered, but p->pc will eventually catch up to nRow.
62276   */
62277   nRow = p->nOp;
62278   if( p->explain==1 ){
62279     /* The first 8 memory cells are used for the result set.  So we will
62280     ** commandeer the 9th cell to use as storage for an array of pointers
62281     ** to trigger subprograms.  The VDBE is guaranteed to have at least 9
62282     ** cells.  */
62283     assert( p->nMem>9 );
62284     pSub = &p->aMem[9];
62285     if( pSub->flags&MEM_Blob ){
62286       /* On the first call to sqlite3_step(), pSub will hold a NULL.  It is
62287       ** initialized to a BLOB by the P4_SUBPROGRAM processing logic below */
62288       nSub = pSub->n/sizeof(Vdbe*);
62289       apSub = (SubProgram **)pSub->z;
62290     }
62291     for(i=0; i<nSub; i++){
62292       nRow += apSub[i]->nOp;
62293     }
62294   }
62295 
62296   do{
62297     i = p->pc++;
62298   }while( i<nRow && p->explain==2 && p->aOp[i].opcode!=OP_Explain );
62299   if( i>=nRow ){
62300     p->rc = SQLITE_OK;
62301     rc = SQLITE_DONE;
62302   }else if( db->u1.isInterrupted ){
62303     p->rc = SQLITE_INTERRUPT;
62304     rc = SQLITE_ERROR;
62305     sqlite3SetString(&p->zErrMsg, db, "%s", sqlite3ErrStr(p->rc));
62306   }else{
62307     char *zP4;
62308     Op *pOp;
62309     if( i<p->nOp ){
62310       /* The output line number is small enough that we are still in the
62311       ** main program. */
62312       pOp = &p->aOp[i];
62313     }else{
62314       /* We are currently listing subprograms.  Figure out which one and
62315       ** pick up the appropriate opcode. */
62316       int j;
62317       i -= p->nOp;
62318       for(j=0; i>=apSub[j]->nOp; j++){
62319         i -= apSub[j]->nOp;
62320       }
62321       pOp = &apSub[j]->aOp[i];
62322     }
62323     if( p->explain==1 ){
62324       pMem->flags = MEM_Int;
62325       pMem->type = SQLITE_INTEGER;
62326       pMem->u.i = i;                                /* Program counter */
62327       pMem++;
62328   
62329       pMem->flags = MEM_Static|MEM_Str|MEM_Term;
62330       pMem->z = (char*)sqlite3OpcodeName(pOp->opcode); /* Opcode */
62331       assert( pMem->z!=0 );
62332       pMem->n = sqlite3Strlen30(pMem->z);
62333       pMem->type = SQLITE_TEXT;
62334       pMem->enc = SQLITE_UTF8;
62335       pMem++;
62336 
62337       /* When an OP_Program opcode is encounter (the only opcode that has
62338       ** a P4_SUBPROGRAM argument), expand the size of the array of subprograms
62339       ** kept in p->aMem[9].z to hold the new program - assuming this subprogram
62340       ** has not already been seen.
62341       */
62342       if( pOp->p4type==P4_SUBPROGRAM ){
62343         int nByte = (nSub+1)*sizeof(SubProgram*);
62344         int j;
62345         for(j=0; j<nSub; j++){
62346           if( apSub[j]==pOp->p4.pProgram ) break;
62347         }
62348         if( j==nSub && SQLITE_OK==sqlite3VdbeMemGrow(pSub, nByte, nSub!=0) ){
62349           apSub = (SubProgram **)pSub->z;
62350           apSub[nSub++] = pOp->p4.pProgram;
62351           pSub->flags |= MEM_Blob;
62352           pSub->n = nSub*sizeof(SubProgram*);
62353         }
62354       }
62355     }
62356 
62357     pMem->flags = MEM_Int;
62358     pMem->u.i = pOp->p1;                          /* P1 */
62359     pMem->type = SQLITE_INTEGER;
62360     pMem++;
62361 
62362     pMem->flags = MEM_Int;
62363     pMem->u.i = pOp->p2;                          /* P2 */
62364     pMem->type = SQLITE_INTEGER;
62365     pMem++;
62366 
62367     pMem->flags = MEM_Int;
62368     pMem->u.i = pOp->p3;                          /* P3 */
62369     pMem->type = SQLITE_INTEGER;
62370     pMem++;
62371 
62372     if( sqlite3VdbeMemGrow(pMem, 32, 0) ){            /* P4 */
62373       assert( p->db->mallocFailed );
62374       return SQLITE_ERROR;
62375     }
62376     pMem->flags = MEM_Dyn|MEM_Str|MEM_Term;
62377     zP4 = displayP4(pOp, pMem->z, 32);
62378     if( zP4!=pMem->z ){
62379       sqlite3VdbeMemSetStr(pMem, zP4, -1, SQLITE_UTF8, 0);
62380     }else{
62381       assert( pMem->z!=0 );
62382       pMem->n = sqlite3Strlen30(pMem->z);
62383       pMem->enc = SQLITE_UTF8;
62384     }
62385     pMem->type = SQLITE_TEXT;
62386     pMem++;
62387 
62388     if( p->explain==1 ){
62389       if( sqlite3VdbeMemGrow(pMem, 4, 0) ){
62390         assert( p->db->mallocFailed );
62391         return SQLITE_ERROR;
62392       }
62393       pMem->flags = MEM_Dyn|MEM_Str|MEM_Term;
62394       pMem->n = 2;
62395       sqlite3_snprintf(3, pMem->z, "%.2x", pOp->p5);   /* P5 */
62396       pMem->type = SQLITE_TEXT;
62397       pMem->enc = SQLITE_UTF8;
62398       pMem++;
62399   
62400 #ifdef SQLITE_ENABLE_EXPLAIN_COMMENTS
62401       if( sqlite3VdbeMemGrow(pMem, 500, 0) ){
62402         assert( p->db->mallocFailed );
62403         return SQLITE_ERROR;
62404       }
62405       pMem->flags = MEM_Dyn|MEM_Str|MEM_Term;
62406       pMem->n = displayComment(pOp, zP4, pMem->z, 500);
62407       pMem->type = SQLITE_TEXT;
62408       pMem->enc = SQLITE_UTF8;
62409 #else
62410       pMem->flags = MEM_Null;                       /* Comment */
62411       pMem->type = SQLITE_NULL;
62412 #endif
62413     }
62414 
62415     p->nResColumn = 8 - 4*(p->explain-1);
62416     p->pResultSet = &p->aMem[1];
62417     p->rc = SQLITE_OK;
62418     rc = SQLITE_ROW;
62419   }
62420   return rc;
62421 }
62422 #endif /* SQLITE_OMIT_EXPLAIN */
62423 
62424 #ifdef SQLITE_DEBUG
62425 /*
62426 ** Print the SQL that was used to generate a VDBE program.
62427 */
62428 SQLITE_PRIVATE void sqlite3VdbePrintSql(Vdbe *p){
62429   const char *z = 0;
62430   if( p->zSql ){
62431     z = p->zSql;
62432   }else if( p->nOp>=1 ){
62433     const VdbeOp *pOp = &p->aOp[0];
62434     if( pOp->opcode==OP_Trace && pOp->p4.z!=0 ){
62435       z = pOp->p4.z;
62436       while( sqlite3Isspace(*z) ) z++;
62437     }
62438   }
62439   if( z ) printf("SQL: [%s]\n", z);
62440 }
62441 #endif
62442 
62443 #if !defined(SQLITE_OMIT_TRACE) && defined(SQLITE_ENABLE_IOTRACE)
62444 /*
62445 ** Print an IOTRACE message showing SQL content.
62446 */
62447 SQLITE_PRIVATE void sqlite3VdbeIOTraceSql(Vdbe *p){
62448   int nOp = p->nOp;
62449   VdbeOp *pOp;
62450   if( sqlite3IoTrace==0 ) return;
62451   if( nOp<1 ) return;
62452   pOp = &p->aOp[0];
62453   if( pOp->opcode==OP_Trace && pOp->p4.z!=0 ){
62454     int i, j;
62455     char z[1000];
62456     sqlite3_snprintf(sizeof(z), z, "%s", pOp->p4.z);
62457     for(i=0; sqlite3Isspace(z[i]); i++){}
62458     for(j=0; z[i]; i++){
62459       if( sqlite3Isspace(z[i]) ){
62460         if( z[i-1]!=' ' ){
62461           z[j++] = ' ';
62462         }
62463       }else{
62464         z[j++] = z[i];
62465       }
62466     }
62467     z[j] = 0;
62468     sqlite3IoTrace("SQL %s\n", z);
62469   }
62470 }
62471 #endif /* !SQLITE_OMIT_TRACE && SQLITE_ENABLE_IOTRACE */
62472 
62473 /*
62474 ** Allocate space from a fixed size buffer and return a pointer to
62475 ** that space.  If insufficient space is available, return NULL.
62476 **
62477 ** The pBuf parameter is the initial value of a pointer which will
62478 ** receive the new memory.  pBuf is normally NULL.  If pBuf is not
62479 ** NULL, it means that memory space has already been allocated and that
62480 ** this routine should not allocate any new memory.  When pBuf is not
62481 ** NULL simply return pBuf.  Only allocate new memory space when pBuf
62482 ** is NULL.
62483 **
62484 ** nByte is the number of bytes of space needed.
62485 **
62486 ** *ppFrom points to available space and pEnd points to the end of the
62487 ** available space.  When space is allocated, *ppFrom is advanced past
62488 ** the end of the allocated space.
62489 **
62490 ** *pnByte is a counter of the number of bytes of space that have failed
62491 ** to allocate.  If there is insufficient space in *ppFrom to satisfy the
62492 ** request, then increment *pnByte by the amount of the request.
62493 */
62494 static void *allocSpace(
62495   void *pBuf,          /* Where return pointer will be stored */
62496   int nByte,           /* Number of bytes to allocate */
62497   u8 **ppFrom,         /* IN/OUT: Allocate from *ppFrom */
62498   u8 *pEnd,            /* Pointer to 1 byte past the end of *ppFrom buffer */
62499   int *pnByte          /* If allocation cannot be made, increment *pnByte */
62500 ){
62501   assert( EIGHT_BYTE_ALIGNMENT(*ppFrom) );
62502   if( pBuf ) return pBuf;
62503   nByte = ROUND8(nByte);
62504   if( &(*ppFrom)[nByte] <= pEnd ){
62505     pBuf = (void*)*ppFrom;
62506     *ppFrom += nByte;
62507   }else{
62508     *pnByte += nByte;
62509   }
62510   return pBuf;
62511 }
62512 
62513 /*
62514 ** Rewind the VDBE back to the beginning in preparation for
62515 ** running it.
62516 */
62517 SQLITE_PRIVATE void sqlite3VdbeRewind(Vdbe *p){
62518 #if defined(SQLITE_DEBUG) || defined(VDBE_PROFILE)
62519   int i;
62520 #endif
62521   assert( p!=0 );
62522   assert( p->magic==VDBE_MAGIC_INIT );
62523 
62524   /* There should be at least one opcode.
62525   */
62526   assert( p->nOp>0 );
62527 
62528   /* Set the magic to VDBE_MAGIC_RUN sooner rather than later. */
62529   p->magic = VDBE_MAGIC_RUN;
62530 
62531 #ifdef SQLITE_DEBUG
62532   for(i=1; i<p->nMem; i++){
62533     assert( p->aMem[i].db==p->db );
62534   }
62535 #endif
62536   p->pc = -1;
62537   p->rc = SQLITE_OK;
62538   p->errorAction = OE_Abort;
62539   p->magic = VDBE_MAGIC_RUN;
62540   p->nChange = 0;
62541   p->cacheCtr = 1;
62542   p->minWriteFileFormat = 255;
62543   p->iStatement = 0;
62544   p->nFkConstraint = 0;
62545 #ifdef VDBE_PROFILE
62546   for(i=0; i<p->nOp; i++){
62547     p->aOp[i].cnt = 0;
62548     p->aOp[i].cycles = 0;
62549   }
62550 #endif
62551 }
62552 
62553 /*
62554 ** Prepare a virtual machine for execution for the first time after
62555 ** creating the virtual machine.  This involves things such
62556 ** as allocating stack space and initializing the program counter.
62557 ** After the VDBE has be prepped, it can be executed by one or more
62558 ** calls to sqlite3VdbeExec().  
62559 **
62560 ** This function may be called exact once on a each virtual machine.
62561 ** After this routine is called the VM has been "packaged" and is ready
62562 ** to run.  After this routine is called, futher calls to 
62563 ** sqlite3VdbeAddOp() functions are prohibited.  This routine disconnects
62564 ** the Vdbe from the Parse object that helped generate it so that the
62565 ** the Vdbe becomes an independent entity and the Parse object can be
62566 ** destroyed.
62567 **
62568 ** Use the sqlite3VdbeRewind() procedure to restore a virtual machine back
62569 ** to its initial state after it has been run.
62570 */
62571 SQLITE_PRIVATE void sqlite3VdbeMakeReady(
62572   Vdbe *p,                       /* The VDBE */
62573   Parse *pParse                  /* Parsing context */
62574 ){
62575   sqlite3 *db;                   /* The database connection */
62576   int nVar;                      /* Number of parameters */
62577   int nMem;                      /* Number of VM memory registers */
62578   int nCursor;                   /* Number of cursors required */
62579   int nArg;                      /* Number of arguments in subprograms */
62580   int nOnce;                     /* Number of OP_Once instructions */
62581   int n;                         /* Loop counter */
62582   u8 *zCsr;                      /* Memory available for allocation */
62583   u8 *zEnd;                      /* First byte past allocated memory */
62584   int nByte;                     /* How much extra memory is needed */
62585 
62586   assert( p!=0 );
62587   assert( p->nOp>0 );
62588   assert( pParse!=0 );
62589   assert( p->magic==VDBE_MAGIC_INIT );
62590   db = p->db;
62591   assert( db->mallocFailed==0 );
62592   nVar = pParse->nVar;
62593   nMem = pParse->nMem;
62594   nCursor = pParse->nTab;
62595   nArg = pParse->nMaxArg;
62596   nOnce = pParse->nOnce;
62597   if( nOnce==0 ) nOnce = 1; /* Ensure at least one byte in p->aOnceFlag[] */
62598   
62599   /* For each cursor required, also allocate a memory cell. Memory
62600   ** cells (nMem+1-nCursor)..nMem, inclusive, will never be used by
62601   ** the vdbe program. Instead they are used to allocate space for
62602   ** VdbeCursor/BtCursor structures. The blob of memory associated with 
62603   ** cursor 0 is stored in memory cell nMem. Memory cell (nMem-1)
62604   ** stores the blob of memory associated with cursor 1, etc.
62605   **
62606   ** See also: allocateCursor().
62607   */
62608   nMem += nCursor;
62609 
62610   /* Allocate space for memory registers, SQL variables, VDBE cursors and 
62611   ** an array to marshal SQL function arguments in.
62612   */
62613   zCsr = (u8*)&p->aOp[p->nOp];       /* Memory avaliable for allocation */
62614   zEnd = (u8*)&p->aOp[p->nOpAlloc];  /* First byte past end of zCsr[] */
62615 
62616   resolveP2Values(p, &nArg);
62617   p->usesStmtJournal = (u8)(pParse->isMultiWrite && pParse->mayAbort);
62618   if( pParse->explain && nMem<10 ){
62619     nMem = 10;
62620   }
62621   memset(zCsr, 0, zEnd-zCsr);
62622   zCsr += (zCsr - (u8*)0)&7;
62623   assert( EIGHT_BYTE_ALIGNMENT(zCsr) );
62624   p->expired = 0;
62625 
62626   /* Memory for registers, parameters, cursor, etc, is allocated in two
62627   ** passes.  On the first pass, we try to reuse unused space at the 
62628   ** end of the opcode array.  If we are unable to satisfy all memory
62629   ** requirements by reusing the opcode array tail, then the second
62630   ** pass will fill in the rest using a fresh allocation.  
62631   **
62632   ** This two-pass approach that reuses as much memory as possible from
62633   ** the leftover space at the end of the opcode array can significantly
62634   ** reduce the amount of memory held by a prepared statement.
62635   */
62636   do {
62637     nByte = 0;
62638     p->aMem = allocSpace(p->aMem, nMem*sizeof(Mem), &zCsr, zEnd, &nByte);
62639     p->aVar = allocSpace(p->aVar, nVar*sizeof(Mem), &zCsr, zEnd, &nByte);
62640     p->apArg = allocSpace(p->apArg, nArg*sizeof(Mem*), &zCsr, zEnd, &nByte);
62641     p->azVar = allocSpace(p->azVar, nVar*sizeof(char*), &zCsr, zEnd, &nByte);
62642     p->apCsr = allocSpace(p->apCsr, nCursor*sizeof(VdbeCursor*),
62643                           &zCsr, zEnd, &nByte);
62644     p->aOnceFlag = allocSpace(p->aOnceFlag, nOnce, &zCsr, zEnd, &nByte);
62645     if( nByte ){
62646       p->pFree = sqlite3DbMallocZero(db, nByte);
62647     }
62648     zCsr = p->pFree;
62649     zEnd = &zCsr[nByte];
62650   }while( nByte && !db->mallocFailed );
62651 
62652   p->nCursor = nCursor;
62653   p->nOnceFlag = nOnce;
62654   if( p->aVar ){
62655     p->nVar = (ynVar)nVar;
62656     for(n=0; n<nVar; n++){
62657       p->aVar[n].flags = MEM_Null;
62658       p->aVar[n].db = db;
62659     }
62660   }
62661   if( p->azVar ){
62662     p->nzVar = pParse->nzVar;
62663     memcpy(p->azVar, pParse->azVar, p->nzVar*sizeof(p->azVar[0]));
62664     memset(pParse->azVar, 0, pParse->nzVar*sizeof(pParse->azVar[0]));
62665   }
62666   if( p->aMem ){
62667     p->aMem--;                      /* aMem[] goes from 1..nMem */
62668     p->nMem = nMem;                 /*       not from 0..nMem-1 */
62669     for(n=1; n<=nMem; n++){
62670       p->aMem[n].flags = MEM_Invalid;
62671       p->aMem[n].db = db;
62672     }
62673   }
62674   p->explain = pParse->explain;
62675   sqlite3VdbeRewind(p);
62676 }
62677 
62678 /*
62679 ** Close a VDBE cursor and release all the resources that cursor 
62680 ** happens to hold.
62681 */
62682 SQLITE_PRIVATE void sqlite3VdbeFreeCursor(Vdbe *p, VdbeCursor *pCx){
62683   if( pCx==0 ){
62684     return;
62685   }
62686   sqlite3VdbeSorterClose(p->db, pCx);
62687   if( pCx->pBt ){
62688     sqlite3BtreeClose(pCx->pBt);
62689     /* The pCx->pCursor will be close automatically, if it exists, by
62690     ** the call above. */
62691   }else if( pCx->pCursor ){
62692     sqlite3BtreeCloseCursor(pCx->pCursor);
62693   }
62694 #ifndef SQLITE_OMIT_VIRTUALTABLE
62695   if( pCx->pVtabCursor ){
62696     sqlite3_vtab_cursor *pVtabCursor = pCx->pVtabCursor;
62697     const sqlite3_module *pModule = pVtabCursor->pVtab->pModule;
62698     p->inVtabMethod = 1;
62699     pModule->xClose(pVtabCursor);
62700     p->inVtabMethod = 0;
62701   }
62702 #endif
62703 }
62704 
62705 /*
62706 ** Copy the values stored in the VdbeFrame structure to its Vdbe. This
62707 ** is used, for example, when a trigger sub-program is halted to restore
62708 ** control to the main program.
62709 */
62710 SQLITE_PRIVATE int sqlite3VdbeFrameRestore(VdbeFrame *pFrame){
62711   Vdbe *v = pFrame->v;
62712   v->aOnceFlag = pFrame->aOnceFlag;
62713   v->nOnceFlag = pFrame->nOnceFlag;
62714   v->aOp = pFrame->aOp;
62715   v->nOp = pFrame->nOp;
62716   v->aMem = pFrame->aMem;
62717   v->nMem = pFrame->nMem;
62718   v->apCsr = pFrame->apCsr;
62719   v->nCursor = pFrame->nCursor;
62720   v->db->lastRowid = pFrame->lastRowid;
62721   v->nChange = pFrame->nChange;
62722   return pFrame->pc;
62723 }
62724 
62725 /*
62726 ** Close all cursors.
62727 **
62728 ** Also release any dynamic memory held by the VM in the Vdbe.aMem memory 
62729 ** cell array. This is necessary as the memory cell array may contain
62730 ** pointers to VdbeFrame objects, which may in turn contain pointers to
62731 ** open cursors.
62732 */
62733 static void closeAllCursors(Vdbe *p){
62734   if( p->pFrame ){
62735     VdbeFrame *pFrame;
62736     for(pFrame=p->pFrame; pFrame->pParent; pFrame=pFrame->pParent);
62737     sqlite3VdbeFrameRestore(pFrame);
62738   }
62739   p->pFrame = 0;
62740   p->nFrame = 0;
62741 
62742   if( p->apCsr ){
62743     int i;
62744     for(i=0; i<p->nCursor; i++){
62745       VdbeCursor *pC = p->apCsr[i];
62746       if( pC ){
62747         sqlite3VdbeFreeCursor(p, pC);
62748         p->apCsr[i] = 0;
62749       }
62750     }
62751   }
62752   if( p->aMem ){
62753     releaseMemArray(&p->aMem[1], p->nMem);
62754   }
62755   while( p->pDelFrame ){
62756     VdbeFrame *pDel = p->pDelFrame;
62757     p->pDelFrame = pDel->pParent;
62758     sqlite3VdbeFrameDelete(pDel);
62759   }
62760 
62761   /* Delete any auxdata allocations made by the VM */
62762   sqlite3VdbeDeleteAuxData(p, -1, 0);
62763   assert( p->pAuxData==0 );
62764 }
62765 
62766 /*
62767 ** Clean up the VM after execution.
62768 **
62769 ** This routine will automatically close any cursors, lists, and/or
62770 ** sorters that were left open.  It also deletes the values of
62771 ** variables in the aVar[] array.
62772 */
62773 static void Cleanup(Vdbe *p){
62774   sqlite3 *db = p->db;
62775 
62776 #ifdef SQLITE_DEBUG
62777   /* Execute assert() statements to ensure that the Vdbe.apCsr[] and 
62778   ** Vdbe.aMem[] arrays have already been cleaned up.  */
62779   int i;
62780   if( p->apCsr ) for(i=0; i<p->nCursor; i++) assert( p->apCsr[i]==0 );
62781   if( p->aMem ){
62782     for(i=1; i<=p->nMem; i++) assert( p->aMem[i].flags==MEM_Invalid );
62783   }
62784 #endif
62785 
62786   sqlite3DbFree(db, p->zErrMsg);
62787   p->zErrMsg = 0;
62788   p->pResultSet = 0;
62789 }
62790 
62791 /*
62792 ** Set the number of result columns that will be returned by this SQL
62793 ** statement. This is now set at compile time, rather than during
62794 ** execution of the vdbe program so that sqlite3_column_count() can
62795 ** be called on an SQL statement before sqlite3_step().
62796 */
62797 SQLITE_PRIVATE void sqlite3VdbeSetNumCols(Vdbe *p, int nResColumn){
62798   Mem *pColName;
62799   int n;
62800   sqlite3 *db = p->db;
62801 
62802   releaseMemArray(p->aColName, p->nResColumn*COLNAME_N);
62803   sqlite3DbFree(db, p->aColName);
62804   n = nResColumn*COLNAME_N;
62805   p->nResColumn = (u16)nResColumn;
62806   p->aColName = pColName = (Mem*)sqlite3DbMallocZero(db, sizeof(Mem)*n );
62807   if( p->aColName==0 ) return;
62808   while( n-- > 0 ){
62809     pColName->flags = MEM_Null;
62810     pColName->db = p->db;
62811     pColName++;
62812   }
62813 }
62814 
62815 /*
62816 ** Set the name of the idx'th column to be returned by the SQL statement.
62817 ** zName must be a pointer to a nul terminated string.
62818 **
62819 ** This call must be made after a call to sqlite3VdbeSetNumCols().
62820 **
62821 ** The final parameter, xDel, must be one of SQLITE_DYNAMIC, SQLITE_STATIC
62822 ** or SQLITE_TRANSIENT. If it is SQLITE_DYNAMIC, then the buffer pointed
62823 ** to by zName will be freed by sqlite3DbFree() when the vdbe is destroyed.
62824 */
62825 SQLITE_PRIVATE int sqlite3VdbeSetColName(
62826   Vdbe *p,                         /* Vdbe being configured */
62827   int idx,                         /* Index of column zName applies to */
62828   int var,                         /* One of the COLNAME_* constants */
62829   const char *zName,               /* Pointer to buffer containing name */
62830   void (*xDel)(void*)              /* Memory management strategy for zName */
62831 ){
62832   int rc;
62833   Mem *pColName;
62834   assert( idx<p->nResColumn );
62835   assert( var<COLNAME_N );
62836   if( p->db->mallocFailed ){
62837     assert( !zName || xDel!=SQLITE_DYNAMIC );
62838     return SQLITE_NOMEM;
62839   }
62840   assert( p->aColName!=0 );
62841   pColName = &(p->aColName[idx+var*p->nResColumn]);
62842   rc = sqlite3VdbeMemSetStr(pColName, zName, -1, SQLITE_UTF8, xDel);
62843   assert( rc!=0 || !zName || (pColName->flags&MEM_Term)!=0 );
62844   return rc;
62845 }
62846 
62847 /*
62848 ** A read or write transaction may or may not be active on database handle
62849 ** db. If a transaction is active, commit it. If there is a
62850 ** write-transaction spanning more than one database file, this routine
62851 ** takes care of the master journal trickery.
62852 */
62853 static int vdbeCommit(sqlite3 *db, Vdbe *p){
62854   int i;
62855   int nTrans = 0;  /* Number of databases with an active write-transaction */
62856   int rc = SQLITE_OK;
62857   int needXcommit = 0;
62858 
62859 #ifdef SQLITE_OMIT_VIRTUALTABLE
62860   /* With this option, sqlite3VtabSync() is defined to be simply 
62861   ** SQLITE_OK so p is not used. 
62862   */
62863   UNUSED_PARAMETER(p);
62864 #endif
62865 
62866   /* Before doing anything else, call the xSync() callback for any
62867   ** virtual module tables written in this transaction. This has to
62868   ** be done before determining whether a master journal file is 
62869   ** required, as an xSync() callback may add an attached database
62870   ** to the transaction.
62871   */
62872   rc = sqlite3VtabSync(db, p);
62873 
62874   /* This loop determines (a) if the commit hook should be invoked and
62875   ** (b) how many database files have open write transactions, not 
62876   ** including the temp database. (b) is important because if more than 
62877   ** one database file has an open write transaction, a master journal
62878   ** file is required for an atomic commit.
62879   */ 
62880   for(i=0; rc==SQLITE_OK && i<db->nDb; i++){ 
62881     Btree *pBt = db->aDb[i].pBt;
62882     if( sqlite3BtreeIsInTrans(pBt) ){
62883       needXcommit = 1;
62884       if( i!=1 ) nTrans++;
62885       sqlite3BtreeEnter(pBt);
62886       rc = sqlite3PagerExclusiveLock(sqlite3BtreePager(pBt));
62887       sqlite3BtreeLeave(pBt);
62888     }
62889   }
62890   if( rc!=SQLITE_OK ){
62891     return rc;
62892   }
62893 
62894   /* If there are any write-transactions at all, invoke the commit hook */
62895   if( needXcommit && db->xCommitCallback ){
62896     rc = db->xCommitCallback(db->pCommitArg);
62897     if( rc ){
62898       return SQLITE_CONSTRAINT_COMMITHOOK;
62899     }
62900   }
62901 
62902   /* The simple case - no more than one database file (not counting the
62903   ** TEMP database) has a transaction active.   There is no need for the
62904   ** master-journal.
62905   **
62906   ** If the return value of sqlite3BtreeGetFilename() is a zero length
62907   ** string, it means the main database is :memory: or a temp file.  In 
62908   ** that case we do not support atomic multi-file commits, so use the 
62909   ** simple case then too.
62910   */
62911   if( 0==sqlite3Strlen30(sqlite3BtreeGetFilename(db->aDb[0].pBt))
62912    || nTrans<=1
62913   ){
62914     for(i=0; rc==SQLITE_OK && i<db->nDb; i++){
62915       Btree *pBt = db->aDb[i].pBt;
62916       if( pBt ){
62917         rc = sqlite3BtreeCommitPhaseOne(pBt, 0);
62918       }
62919     }
62920 
62921     /* Do the commit only if all databases successfully complete phase 1. 
62922     ** If one of the BtreeCommitPhaseOne() calls fails, this indicates an
62923     ** IO error while deleting or truncating a journal file. It is unlikely,
62924     ** but could happen. In this case abandon processing and return the error.
62925     */
62926     for(i=0; rc==SQLITE_OK && i<db->nDb; i++){
62927       Btree *pBt = db->aDb[i].pBt;
62928       if( pBt ){
62929         rc = sqlite3BtreeCommitPhaseTwo(pBt, 0);
62930       }
62931     }
62932     if( rc==SQLITE_OK ){
62933       sqlite3VtabCommit(db);
62934     }
62935   }
62936 
62937   /* The complex case - There is a multi-file write-transaction active.
62938   ** This requires a master journal file to ensure the transaction is
62939   ** committed atomicly.
62940   */
62941 #ifndef SQLITE_OMIT_DISKIO
62942   else{
62943     sqlite3_vfs *pVfs = db->pVfs;
62944     int needSync = 0;
62945     char *zMaster = 0;   /* File-name for the master journal */
62946     char const *zMainFile = sqlite3BtreeGetFilename(db->aDb[0].pBt);
62947     sqlite3_file *pMaster = 0;
62948     i64 offset = 0;
62949     int res;
62950     int retryCount = 0;
62951     int nMainFile;
62952 
62953     /* Select a master journal file name */
62954     nMainFile = sqlite3Strlen30(zMainFile);
62955     zMaster = sqlite3MPrintf(db, "%s-mjXXXXXX9XXz", zMainFile);
62956     if( zMaster==0 ) return SQLITE_NOMEM;
62957     do {
62958       u32 iRandom;
62959       if( retryCount ){
62960         if( retryCount>100 ){
62961           sqlite3_log(SQLITE_FULL, "MJ delete: %s", zMaster);
62962           sqlite3OsDelete(pVfs, zMaster, 0);
62963           break;
62964         }else if( retryCount==1 ){
62965           sqlite3_log(SQLITE_FULL, "MJ collide: %s", zMaster);
62966         }
62967       }
62968       retryCount++;
62969       sqlite3_randomness(sizeof(iRandom), &iRandom);
62970       sqlite3_snprintf(13, &zMaster[nMainFile], "-mj%06X9%02X",
62971                                (iRandom>>8)&0xffffff, iRandom&0xff);
62972       /* The antipenultimate character of the master journal name must
62973       ** be "9" to avoid name collisions when using 8+3 filenames. */
62974       assert( zMaster[sqlite3Strlen30(zMaster)-3]=='9' );
62975       sqlite3FileSuffix3(zMainFile, zMaster);
62976       rc = sqlite3OsAccess(pVfs, zMaster, SQLITE_ACCESS_EXISTS, &res);
62977     }while( rc==SQLITE_OK && res );
62978     if( rc==SQLITE_OK ){
62979       /* Open the master journal. */
62980       rc = sqlite3OsOpenMalloc(pVfs, zMaster, &pMaster, 
62981           SQLITE_OPEN_READWRITE|SQLITE_OPEN_CREATE|
62982           SQLITE_OPEN_EXCLUSIVE|SQLITE_OPEN_MASTER_JOURNAL, 0
62983       );
62984     }
62985     if( rc!=SQLITE_OK ){
62986       sqlite3DbFree(db, zMaster);
62987       return rc;
62988     }
62989  
62990     /* Write the name of each database file in the transaction into the new
62991     ** master journal file. If an error occurs at this point close
62992     ** and delete the master journal file. All the individual journal files
62993     ** still have 'null' as the master journal pointer, so they will roll
62994     ** back independently if a failure occurs.
62995     */
62996     for(i=0; i<db->nDb; i++){
62997       Btree *pBt = db->aDb[i].pBt;
62998       if( sqlite3BtreeIsInTrans(pBt) ){
62999         char const *zFile = sqlite3BtreeGetJournalname(pBt);
63000         if( zFile==0 ){
63001           continue;  /* Ignore TEMP and :memory: databases */
63002         }
63003         assert( zFile[0]!=0 );
63004         if( !needSync && !sqlite3BtreeSyncDisabled(pBt) ){
63005           needSync = 1;
63006         }
63007         rc = sqlite3OsWrite(pMaster, zFile, sqlite3Strlen30(zFile)+1, offset);
63008         offset += sqlite3Strlen30(zFile)+1;
63009         if( rc!=SQLITE_OK ){
63010           sqlite3OsCloseFree(pMaster);
63011           sqlite3OsDelete(pVfs, zMaster, 0);
63012           sqlite3DbFree(db, zMaster);
63013           return rc;
63014         }
63015       }
63016     }
63017 
63018     /* Sync the master journal file. If the IOCAP_SEQUENTIAL device
63019     ** flag is set this is not required.
63020     */
63021     if( needSync 
63022      && 0==(sqlite3OsDeviceCharacteristics(pMaster)&SQLITE_IOCAP_SEQUENTIAL)
63023      && SQLITE_OK!=(rc = sqlite3OsSync(pMaster, SQLITE_SYNC_NORMAL))
63024     ){
63025       sqlite3OsCloseFree(pMaster);
63026       sqlite3OsDelete(pVfs, zMaster, 0);
63027       sqlite3DbFree(db, zMaster);
63028       return rc;
63029     }
63030 
63031     /* Sync all the db files involved in the transaction. The same call
63032     ** sets the master journal pointer in each individual journal. If
63033     ** an error occurs here, do not delete the master journal file.
63034     **
63035     ** If the error occurs during the first call to
63036     ** sqlite3BtreeCommitPhaseOne(), then there is a chance that the
63037     ** master journal file will be orphaned. But we cannot delete it,
63038     ** in case the master journal file name was written into the journal
63039     ** file before the failure occurred.
63040     */
63041     for(i=0; rc==SQLITE_OK && i<db->nDb; i++){ 
63042       Btree *pBt = db->aDb[i].pBt;
63043       if( pBt ){
63044         rc = sqlite3BtreeCommitPhaseOne(pBt, zMaster);
63045       }
63046     }
63047     sqlite3OsCloseFree(pMaster);
63048     assert( rc!=SQLITE_BUSY );
63049     if( rc!=SQLITE_OK ){
63050       sqlite3DbFree(db, zMaster);
63051       return rc;
63052     }
63053 
63054     /* Delete the master journal file. This commits the transaction. After
63055     ** doing this the directory is synced again before any individual
63056     ** transaction files are deleted.
63057     */
63058     rc = sqlite3OsDelete(pVfs, zMaster, 1);
63059     sqlite3DbFree(db, zMaster);
63060     zMaster = 0;
63061     if( rc ){
63062       return rc;
63063     }
63064 
63065     /* All files and directories have already been synced, so the following
63066     ** calls to sqlite3BtreeCommitPhaseTwo() are only closing files and
63067     ** deleting or truncating journals. If something goes wrong while
63068     ** this is happening we don't really care. The integrity of the
63069     ** transaction is already guaranteed, but some stray 'cold' journals
63070     ** may be lying around. Returning an error code won't help matters.
63071     */
63072     disable_simulated_io_errors();
63073     sqlite3BeginBenignMalloc();
63074     for(i=0; i<db->nDb; i++){ 
63075       Btree *pBt = db->aDb[i].pBt;
63076       if( pBt ){
63077         sqlite3BtreeCommitPhaseTwo(pBt, 1);
63078       }
63079     }
63080     sqlite3EndBenignMalloc();
63081     enable_simulated_io_errors();
63082 
63083     sqlite3VtabCommit(db);
63084   }
63085 #endif
63086 
63087   return rc;
63088 }
63089 
63090 /* 
63091 ** This routine checks that the sqlite3.nVdbeActive count variable
63092 ** matches the number of vdbe's in the list sqlite3.pVdbe that are
63093 ** currently active. An assertion fails if the two counts do not match.
63094 ** This is an internal self-check only - it is not an essential processing
63095 ** step.
63096 **
63097 ** This is a no-op if NDEBUG is defined.
63098 */
63099 #ifndef NDEBUG
63100 static void checkActiveVdbeCnt(sqlite3 *db){
63101   Vdbe *p;
63102   int cnt = 0;
63103   int nWrite = 0;
63104   int nRead = 0;
63105   p = db->pVdbe;
63106   while( p ){
63107     if( p->magic==VDBE_MAGIC_RUN && p->pc>=0 ){
63108       cnt++;
63109       if( p->readOnly==0 ) nWrite++;
63110       if( p->bIsReader ) nRead++;
63111     }
63112     p = p->pNext;
63113   }
63114   assert( cnt==db->nVdbeActive );
63115   assert( nWrite==db->nVdbeWrite );
63116   assert( nRead==db->nVdbeRead );
63117 }
63118 #else
63119 #define checkActiveVdbeCnt(x)
63120 #endif
63121 
63122 /*
63123 ** If the Vdbe passed as the first argument opened a statement-transaction,
63124 ** close it now. Argument eOp must be either SAVEPOINT_ROLLBACK or
63125 ** SAVEPOINT_RELEASE. If it is SAVEPOINT_ROLLBACK, then the statement
63126 ** transaction is rolled back. If eOp is SAVEPOINT_RELEASE, then the 
63127 ** statement transaction is committed.
63128 **
63129 ** If an IO error occurs, an SQLITE_IOERR_XXX error code is returned. 
63130 ** Otherwise SQLITE_OK.
63131 */
63132 SQLITE_PRIVATE int sqlite3VdbeCloseStatement(Vdbe *p, int eOp){
63133   sqlite3 *const db = p->db;
63134   int rc = SQLITE_OK;
63135 
63136   /* If p->iStatement is greater than zero, then this Vdbe opened a 
63137   ** statement transaction that should be closed here. The only exception
63138   ** is that an IO error may have occurred, causing an emergency rollback.
63139   ** In this case (db->nStatement==0), and there is nothing to do.
63140   */
63141   if( db->nStatement && p->iStatement ){
63142     int i;
63143     const int iSavepoint = p->iStatement-1;
63144 
63145     assert( eOp==SAVEPOINT_ROLLBACK || eOp==SAVEPOINT_RELEASE);
63146     assert( db->nStatement>0 );
63147     assert( p->iStatement==(db->nStatement+db->nSavepoint) );
63148 
63149     for(i=0; i<db->nDb; i++){ 
63150       int rc2 = SQLITE_OK;
63151       Btree *pBt = db->aDb[i].pBt;
63152       if( pBt ){
63153         if( eOp==SAVEPOINT_ROLLBACK ){
63154           rc2 = sqlite3BtreeSavepoint(pBt, SAVEPOINT_ROLLBACK, iSavepoint);
63155         }
63156         if( rc2==SQLITE_OK ){
63157           rc2 = sqlite3BtreeSavepoint(pBt, SAVEPOINT_RELEASE, iSavepoint);
63158         }
63159         if( rc==SQLITE_OK ){
63160           rc = rc2;
63161         }
63162       }
63163     }
63164     db->nStatement--;
63165     p->iStatement = 0;
63166 
63167     if( rc==SQLITE_OK ){
63168       if( eOp==SAVEPOINT_ROLLBACK ){
63169         rc = sqlite3VtabSavepoint(db, SAVEPOINT_ROLLBACK, iSavepoint);
63170       }
63171       if( rc==SQLITE_OK ){
63172         rc = sqlite3VtabSavepoint(db, SAVEPOINT_RELEASE, iSavepoint);
63173       }
63174     }
63175 
63176     /* If the statement transaction is being rolled back, also restore the 
63177     ** database handles deferred constraint counter to the value it had when 
63178     ** the statement transaction was opened.  */
63179     if( eOp==SAVEPOINT_ROLLBACK ){
63180       db->nDeferredCons = p->nStmtDefCons;
63181       db->nDeferredImmCons = p->nStmtDefImmCons;
63182     }
63183   }
63184   return rc;
63185 }
63186 
63187 /*
63188 ** This function is called when a transaction opened by the database 
63189 ** handle associated with the VM passed as an argument is about to be 
63190 ** committed. If there are outstanding deferred foreign key constraint
63191 ** violations, return SQLITE_ERROR. Otherwise, SQLITE_OK.
63192 **
63193 ** If there are outstanding FK violations and this function returns 
63194 ** SQLITE_ERROR, set the result of the VM to SQLITE_CONSTRAINT_FOREIGNKEY
63195 ** and write an error message to it. Then return SQLITE_ERROR.
63196 */
63197 #ifndef SQLITE_OMIT_FOREIGN_KEY
63198 SQLITE_PRIVATE int sqlite3VdbeCheckFk(Vdbe *p, int deferred){
63199   sqlite3 *db = p->db;
63200   if( (deferred && (db->nDeferredCons+db->nDeferredImmCons)>0) 
63201    || (!deferred && p->nFkConstraint>0) 
63202   ){
63203     p->rc = SQLITE_CONSTRAINT_FOREIGNKEY;
63204     p->errorAction = OE_Abort;
63205     sqlite3SetString(&p->zErrMsg, db, "FOREIGN KEY constraint failed");
63206     return SQLITE_ERROR;
63207   }
63208   return SQLITE_OK;
63209 }
63210 #endif
63211 
63212 /*
63213 ** This routine is called the when a VDBE tries to halt.  If the VDBE
63214 ** has made changes and is in autocommit mode, then commit those
63215 ** changes.  If a rollback is needed, then do the rollback.
63216 **
63217 ** This routine is the only way to move the state of a VM from
63218 ** SQLITE_MAGIC_RUN to SQLITE_MAGIC_HALT.  It is harmless to
63219 ** call this on a VM that is in the SQLITE_MAGIC_HALT state.
63220 **
63221 ** Return an error code.  If the commit could not complete because of
63222 ** lock contention, return SQLITE_BUSY.  If SQLITE_BUSY is returned, it
63223 ** means the close did not happen and needs to be repeated.
63224 */
63225 SQLITE_PRIVATE int sqlite3VdbeHalt(Vdbe *p){
63226   int rc;                         /* Used to store transient return codes */
63227   sqlite3 *db = p->db;
63228 
63229   /* This function contains the logic that determines if a statement or
63230   ** transaction will be committed or rolled back as a result of the
63231   ** execution of this virtual machine. 
63232   **
63233   ** If any of the following errors occur:
63234   **
63235   **     SQLITE_NOMEM
63236   **     SQLITE_IOERR
63237   **     SQLITE_FULL
63238   **     SQLITE_INTERRUPT
63239   **
63240   ** Then the internal cache might have been left in an inconsistent
63241   ** state.  We need to rollback the statement transaction, if there is
63242   ** one, or the complete transaction if there is no statement transaction.
63243   */
63244 
63245   if( p->db->mallocFailed ){
63246     p->rc = SQLITE_NOMEM;
63247   }
63248   if( p->aOnceFlag ) memset(p->aOnceFlag, 0, p->nOnceFlag);
63249   closeAllCursors(p);
63250   if( p->magic!=VDBE_MAGIC_RUN ){
63251     return SQLITE_OK;
63252   }
63253   checkActiveVdbeCnt(db);
63254 
63255   /* No commit or rollback needed if the program never started or if the
63256   ** SQL statement does not read or write a database file.  */
63257   if( p->pc>=0 && p->bIsReader ){
63258     int mrc;   /* Primary error code from p->rc */
63259     int eStatementOp = 0;
63260     int isSpecialError;            /* Set to true if a 'special' error */
63261 
63262     /* Lock all btrees used by the statement */
63263     sqlite3VdbeEnter(p);
63264 
63265     /* Check for one of the special errors */
63266     mrc = p->rc & 0xff;
63267     assert( p->rc!=SQLITE_IOERR_BLOCKED );  /* This error no longer exists */
63268     isSpecialError = mrc==SQLITE_NOMEM || mrc==SQLITE_IOERR
63269                      || mrc==SQLITE_INTERRUPT || mrc==SQLITE_FULL;
63270     if( isSpecialError ){
63271       /* If the query was read-only and the error code is SQLITE_INTERRUPT, 
63272       ** no rollback is necessary. Otherwise, at least a savepoint 
63273       ** transaction must be rolled back to restore the database to a 
63274       ** consistent state.
63275       **
63276       ** Even if the statement is read-only, it is important to perform
63277       ** a statement or transaction rollback operation. If the error 
63278       ** occurred while writing to the journal, sub-journal or database
63279       ** file as part of an effort to free up cache space (see function
63280       ** pagerStress() in pager.c), the rollback is required to restore 
63281       ** the pager to a consistent state.
63282       */
63283       if( !p->readOnly || mrc!=SQLITE_INTERRUPT ){
63284         if( (mrc==SQLITE_NOMEM || mrc==SQLITE_FULL) && p->usesStmtJournal ){
63285           eStatementOp = SAVEPOINT_ROLLBACK;
63286         }else{
63287           /* We are forced to roll back the active transaction. Before doing
63288           ** so, abort any other statements this handle currently has active.
63289           */
63290           sqlite3RollbackAll(db, SQLITE_ABORT_ROLLBACK);
63291           sqlite3CloseSavepoints(db);
63292           db->autoCommit = 1;
63293         }
63294       }
63295     }
63296 
63297     /* Check for immediate foreign key violations. */
63298     if( p->rc==SQLITE_OK ){
63299       sqlite3VdbeCheckFk(p, 0);
63300     }
63301   
63302     /* If the auto-commit flag is set and this is the only active writer 
63303     ** VM, then we do either a commit or rollback of the current transaction. 
63304     **
63305     ** Note: This block also runs if one of the special errors handled 
63306     ** above has occurred. 
63307     */
63308     if( !sqlite3VtabInSync(db) 
63309      && db->autoCommit 
63310      && db->nVdbeWrite==(p->readOnly==0) 
63311     ){
63312       if( p->rc==SQLITE_OK || (p->errorAction==OE_Fail && !isSpecialError) ){
63313         rc = sqlite3VdbeCheckFk(p, 1);
63314         if( rc!=SQLITE_OK ){
63315           if( NEVER(p->readOnly) ){
63316             sqlite3VdbeLeave(p);
63317             return SQLITE_ERROR;
63318           }
63319           rc = SQLITE_CONSTRAINT_FOREIGNKEY;
63320         }else{ 
63321           /* The auto-commit flag is true, the vdbe program was successful 
63322           ** or hit an 'OR FAIL' constraint and there are no deferred foreign
63323           ** key constraints to hold up the transaction. This means a commit 
63324           ** is required. */
63325           rc = vdbeCommit(db, p);
63326         }
63327         if( rc==SQLITE_BUSY && p->readOnly ){
63328           sqlite3VdbeLeave(p);
63329           return SQLITE_BUSY;
63330         }else if( rc!=SQLITE_OK ){
63331           p->rc = rc;
63332           sqlite3RollbackAll(db, SQLITE_OK);
63333         }else{
63334           db->nDeferredCons = 0;
63335           db->nDeferredImmCons = 0;
63336           db->flags &= ~SQLITE_DeferFKs;
63337           sqlite3CommitInternalChanges(db);
63338         }
63339       }else{
63340         sqlite3RollbackAll(db, SQLITE_OK);
63341       }
63342       db->nStatement = 0;
63343     }else if( eStatementOp==0 ){
63344       if( p->rc==SQLITE_OK || p->errorAction==OE_Fail ){
63345         eStatementOp = SAVEPOINT_RELEASE;
63346       }else if( p->errorAction==OE_Abort ){
63347         eStatementOp = SAVEPOINT_ROLLBACK;
63348       }else{
63349         sqlite3RollbackAll(db, SQLITE_ABORT_ROLLBACK);
63350         sqlite3CloseSavepoints(db);
63351         db->autoCommit = 1;
63352       }
63353     }
63354   
63355     /* If eStatementOp is non-zero, then a statement transaction needs to
63356     ** be committed or rolled back. Call sqlite3VdbeCloseStatement() to
63357     ** do so. If this operation returns an error, and the current statement
63358     ** error code is SQLITE_OK or SQLITE_CONSTRAINT, then promote the
63359     ** current statement error code.
63360     */
63361     if( eStatementOp ){
63362       rc = sqlite3VdbeCloseStatement(p, eStatementOp);
63363       if( rc ){
63364         if( p->rc==SQLITE_OK || (p->rc&0xff)==SQLITE_CONSTRAINT ){
63365           p->rc = rc;
63366           sqlite3DbFree(db, p->zErrMsg);
63367           p->zErrMsg = 0;
63368         }
63369         sqlite3RollbackAll(db, SQLITE_ABORT_ROLLBACK);
63370         sqlite3CloseSavepoints(db);
63371         db->autoCommit = 1;
63372       }
63373     }
63374   
63375     /* If this was an INSERT, UPDATE or DELETE and no statement transaction
63376     ** has been rolled back, update the database connection change-counter. 
63377     */
63378     if( p->changeCntOn ){
63379       if( eStatementOp!=SAVEPOINT_ROLLBACK ){
63380         sqlite3VdbeSetChanges(db, p->nChange);
63381       }else{
63382         sqlite3VdbeSetChanges(db, 0);
63383       }
63384       p->nChange = 0;
63385     }
63386 
63387     /* Release the locks */
63388     sqlite3VdbeLeave(p);
63389   }
63390 
63391   /* We have successfully halted and closed the VM.  Record this fact. */
63392   if( p->pc>=0 ){
63393     db->nVdbeActive--;
63394     if( !p->readOnly ) db->nVdbeWrite--;
63395     if( p->bIsReader ) db->nVdbeRead--;
63396     assert( db->nVdbeActive>=db->nVdbeRead );
63397     assert( db->nVdbeRead>=db->nVdbeWrite );
63398     assert( db->nVdbeWrite>=0 );
63399   }
63400   p->magic = VDBE_MAGIC_HALT;
63401   checkActiveVdbeCnt(db);
63402   if( p->db->mallocFailed ){
63403     p->rc = SQLITE_NOMEM;
63404   }
63405 
63406   /* If the auto-commit flag is set to true, then any locks that were held
63407   ** by connection db have now been released. Call sqlite3ConnectionUnlocked() 
63408   ** to invoke any required unlock-notify callbacks.
63409   */
63410   if( db->autoCommit ){
63411     sqlite3ConnectionUnlocked(db);
63412   }
63413 
63414   assert( db->nVdbeActive>0 || db->autoCommit==0 || db->nStatement==0 );
63415   return (p->rc==SQLITE_BUSY ? SQLITE_BUSY : SQLITE_OK);
63416 }
63417 
63418 
63419 /*
63420 ** Each VDBE holds the result of the most recent sqlite3_step() call
63421 ** in p->rc.  This routine sets that result back to SQLITE_OK.
63422 */
63423 SQLITE_PRIVATE void sqlite3VdbeResetStepResult(Vdbe *p){
63424   p->rc = SQLITE_OK;
63425 }
63426 
63427 /*
63428 ** Copy the error code and error message belonging to the VDBE passed
63429 ** as the first argument to its database handle (so that they will be 
63430 ** returned by calls to sqlite3_errcode() and sqlite3_errmsg()).
63431 **
63432 ** This function does not clear the VDBE error code or message, just
63433 ** copies them to the database handle.
63434 */
63435 SQLITE_PRIVATE int sqlite3VdbeTransferError(Vdbe *p){
63436   sqlite3 *db = p->db;
63437   int rc = p->rc;
63438   if( p->zErrMsg ){
63439     u8 mallocFailed = db->mallocFailed;
63440     sqlite3BeginBenignMalloc();
63441     sqlite3ValueSetStr(db->pErr, -1, p->zErrMsg, SQLITE_UTF8, SQLITE_TRANSIENT);
63442     sqlite3EndBenignMalloc();
63443     db->mallocFailed = mallocFailed;
63444     db->errCode = rc;
63445   }else{
63446     sqlite3Error(db, rc, 0);
63447   }
63448   return rc;
63449 }
63450 
63451 #ifdef SQLITE_ENABLE_SQLLOG
63452 /*
63453 ** If an SQLITE_CONFIG_SQLLOG hook is registered and the VM has been run, 
63454 ** invoke it.
63455 */
63456 static void vdbeInvokeSqllog(Vdbe *v){
63457   if( sqlite3GlobalConfig.xSqllog && v->rc==SQLITE_OK && v->zSql && v->pc>=0 ){
63458     char *zExpanded = sqlite3VdbeExpandSql(v, v->zSql);
63459     assert( v->db->init.busy==0 );
63460     if( zExpanded ){
63461       sqlite3GlobalConfig.xSqllog(
63462           sqlite3GlobalConfig.pSqllogArg, v->db, zExpanded, 1
63463       );
63464       sqlite3DbFree(v->db, zExpanded);
63465     }
63466   }
63467 }
63468 #else
63469 # define vdbeInvokeSqllog(x)
63470 #endif
63471 
63472 /*
63473 ** Clean up a VDBE after execution but do not delete the VDBE just yet.
63474 ** Write any error messages into *pzErrMsg.  Return the result code.
63475 **
63476 ** After this routine is run, the VDBE should be ready to be executed
63477 ** again.
63478 **
63479 ** To look at it another way, this routine resets the state of the
63480 ** virtual machine from VDBE_MAGIC_RUN or VDBE_MAGIC_HALT back to
63481 ** VDBE_MAGIC_INIT.
63482 */
63483 SQLITE_PRIVATE int sqlite3VdbeReset(Vdbe *p){
63484   sqlite3 *db;
63485   db = p->db;
63486 
63487   /* If the VM did not run to completion or if it encountered an
63488   ** error, then it might not have been halted properly.  So halt
63489   ** it now.
63490   */
63491   sqlite3VdbeHalt(p);
63492 
63493   /* If the VDBE has be run even partially, then transfer the error code
63494   ** and error message from the VDBE into the main database structure.  But
63495   ** if the VDBE has just been set to run but has not actually executed any
63496   ** instructions yet, leave the main database error information unchanged.
63497   */
63498   if( p->pc>=0 ){
63499     vdbeInvokeSqllog(p);
63500     sqlite3VdbeTransferError(p);
63501     sqlite3DbFree(db, p->zErrMsg);
63502     p->zErrMsg = 0;
63503     if( p->runOnlyOnce ) p->expired = 1;
63504   }else if( p->rc && p->expired ){
63505     /* The expired flag was set on the VDBE before the first call
63506     ** to sqlite3_step(). For consistency (since sqlite3_step() was
63507     ** called), set the database error in this case as well.
63508     */
63509     sqlite3Error(db, p->rc, 0);
63510     sqlite3ValueSetStr(db->pErr, -1, p->zErrMsg, SQLITE_UTF8, SQLITE_TRANSIENT);
63511     sqlite3DbFree(db, p->zErrMsg);
63512     p->zErrMsg = 0;
63513   }
63514 
63515   /* Reclaim all memory used by the VDBE
63516   */
63517   Cleanup(p);
63518 
63519   /* Save profiling information from this VDBE run.
63520   */
63521 #ifdef VDBE_PROFILE
63522   {
63523     FILE *out = fopen("vdbe_profile.out", "a");
63524     if( out ){
63525       int i;
63526       fprintf(out, "---- ");
63527       for(i=0; i<p->nOp; i++){
63528         fprintf(out, "%02x", p->aOp[i].opcode);
63529       }
63530       fprintf(out, "\n");
63531       for(i=0; i<p->nOp; i++){
63532         fprintf(out, "%6d %10lld %8lld ",
63533            p->aOp[i].cnt,
63534            p->aOp[i].cycles,
63535            p->aOp[i].cnt>0 ? p->aOp[i].cycles/p->aOp[i].cnt : 0
63536         );
63537         sqlite3VdbePrintOp(out, i, &p->aOp[i]);
63538       }
63539       fclose(out);
63540     }
63541   }
63542 #endif
63543   p->iCurrentTime = 0;
63544   p->magic = VDBE_MAGIC_INIT;
63545   return p->rc & db->errMask;
63546 }
63547  
63548 /*
63549 ** Clean up and delete a VDBE after execution.  Return an integer which is
63550 ** the result code.  Write any error message text into *pzErrMsg.
63551 */
63552 SQLITE_PRIVATE int sqlite3VdbeFinalize(Vdbe *p){
63553   int rc = SQLITE_OK;
63554   if( p->magic==VDBE_MAGIC_RUN || p->magic==VDBE_MAGIC_HALT ){
63555     rc = sqlite3VdbeReset(p);
63556     assert( (rc & p->db->errMask)==rc );
63557   }
63558   sqlite3VdbeDelete(p);
63559   return rc;
63560 }
63561 
63562 /*
63563 ** If parameter iOp is less than zero, then invoke the destructor for
63564 ** all auxiliary data pointers currently cached by the VM passed as
63565 ** the first argument.
63566 **
63567 ** Or, if iOp is greater than or equal to zero, then the destructor is
63568 ** only invoked for those auxiliary data pointers created by the user 
63569 ** function invoked by the OP_Function opcode at instruction iOp of 
63570 ** VM pVdbe, and only then if:
63571 **
63572 **    * the associated function parameter is the 32nd or later (counting
63573 **      from left to right), or
63574 **
63575 **    * the corresponding bit in argument mask is clear (where the first
63576 **      function parameter corrsponds to bit 0 etc.).
63577 */
63578 SQLITE_PRIVATE void sqlite3VdbeDeleteAuxData(Vdbe *pVdbe, int iOp, int mask){
63579   AuxData **pp = &pVdbe->pAuxData;
63580   while( *pp ){
63581     AuxData *pAux = *pp;
63582     if( (iOp<0)
63583      || (pAux->iOp==iOp && (pAux->iArg>31 || !(mask & ((u32)1<<pAux->iArg))))
63584     ){
63585       if( pAux->xDelete ){
63586         pAux->xDelete(pAux->pAux);
63587       }
63588       *pp = pAux->pNext;
63589       sqlite3DbFree(pVdbe->db, pAux);
63590     }else{
63591       pp= &pAux->pNext;
63592     }
63593   }
63594 }
63595 
63596 /*
63597 ** Free all memory associated with the Vdbe passed as the second argument,
63598 ** except for object itself, which is preserved.
63599 **
63600 ** The difference between this function and sqlite3VdbeDelete() is that
63601 ** VdbeDelete() also unlinks the Vdbe from the list of VMs associated with
63602 ** the database connection and frees the object itself.
63603 */
63604 SQLITE_PRIVATE void sqlite3VdbeClearObject(sqlite3 *db, Vdbe *p){
63605   SubProgram *pSub, *pNext;
63606   int i;
63607   assert( p->db==0 || p->db==db );
63608   releaseMemArray(p->aVar, p->nVar);
63609   releaseMemArray(p->aColName, p->nResColumn*COLNAME_N);
63610   for(pSub=p->pProgram; pSub; pSub=pNext){
63611     pNext = pSub->pNext;
63612     vdbeFreeOpArray(db, pSub->aOp, pSub->nOp);
63613     sqlite3DbFree(db, pSub);
63614   }
63615   for(i=p->nzVar-1; i>=0; i--) sqlite3DbFree(db, p->azVar[i]);
63616   vdbeFreeOpArray(db, p->aOp, p->nOp);
63617   sqlite3DbFree(db, p->aLabel);
63618   sqlite3DbFree(db, p->aColName);
63619   sqlite3DbFree(db, p->zSql);
63620   sqlite3DbFree(db, p->pFree);
63621 #if defined(SQLITE_ENABLE_TREE_EXPLAIN)
63622   sqlite3DbFree(db, p->zExplain);
63623   sqlite3DbFree(db, p->pExplain);
63624 #endif
63625 }
63626 
63627 /*
63628 ** Delete an entire VDBE.
63629 */
63630 SQLITE_PRIVATE void sqlite3VdbeDelete(Vdbe *p){
63631   sqlite3 *db;
63632 
63633   if( NEVER(p==0) ) return;
63634   db = p->db;
63635   assert( sqlite3_mutex_held(db->mutex) );
63636   sqlite3VdbeClearObject(db, p);
63637   if( p->pPrev ){
63638     p->pPrev->pNext = p->pNext;
63639   }else{
63640     assert( db->pVdbe==p );
63641     db->pVdbe = p->pNext;
63642   }
63643   if( p->pNext ){
63644     p->pNext->pPrev = p->pPrev;
63645   }
63646   p->magic = VDBE_MAGIC_DEAD;
63647   p->db = 0;
63648   sqlite3DbFree(db, p);
63649 }
63650 
63651 /*
63652 ** Make sure the cursor p is ready to read or write the row to which it
63653 ** was last positioned.  Return an error code if an OOM fault or I/O error
63654 ** prevents us from positioning the cursor to its correct position.
63655 **
63656 ** If a MoveTo operation is pending on the given cursor, then do that
63657 ** MoveTo now.  If no move is pending, check to see if the row has been
63658 ** deleted out from under the cursor and if it has, mark the row as
63659 ** a NULL row.
63660 **
63661 ** If the cursor is already pointing to the correct row and that row has
63662 ** not been deleted out from under the cursor, then this routine is a no-op.
63663 */
63664 SQLITE_PRIVATE int sqlite3VdbeCursorMoveto(VdbeCursor *p){
63665   if( p->deferredMoveto ){
63666     int res, rc;
63667 #ifdef SQLITE_TEST
63668     extern int sqlite3_search_count;
63669 #endif
63670     assert( p->isTable );
63671     rc = sqlite3BtreeMovetoUnpacked(p->pCursor, 0, p->movetoTarget, 0, &res);
63672     if( rc ) return rc;
63673     p->lastRowid = p->movetoTarget;
63674     if( res!=0 ) return SQLITE_CORRUPT_BKPT;
63675     p->rowidIsValid = 1;
63676 #ifdef SQLITE_TEST
63677     sqlite3_search_count++;
63678 #endif
63679     p->deferredMoveto = 0;
63680     p->cacheStatus = CACHE_STALE;
63681   }else if( p->pCursor ){
63682     int hasMoved;
63683     int rc = sqlite3BtreeCursorHasMoved(p->pCursor, &hasMoved);
63684     if( rc ) return rc;
63685     if( hasMoved ){
63686       p->cacheStatus = CACHE_STALE;
63687       p->nullRow = 1;
63688     }
63689   }
63690   return SQLITE_OK;
63691 }
63692 
63693 /*
63694 ** The following functions:
63695 **
63696 ** sqlite3VdbeSerialType()
63697 ** sqlite3VdbeSerialTypeLen()
63698 ** sqlite3VdbeSerialLen()
63699 ** sqlite3VdbeSerialPut()
63700 ** sqlite3VdbeSerialGet()
63701 **
63702 ** encapsulate the code that serializes values for storage in SQLite
63703 ** data and index records. Each serialized value consists of a
63704 ** 'serial-type' and a blob of data. The serial type is an 8-byte unsigned
63705 ** integer, stored as a varint.
63706 **
63707 ** In an SQLite index record, the serial type is stored directly before
63708 ** the blob of data that it corresponds to. In a table record, all serial
63709 ** types are stored at the start of the record, and the blobs of data at
63710 ** the end. Hence these functions allow the caller to handle the
63711 ** serial-type and data blob separately.
63712 **
63713 ** The following table describes the various storage classes for data:
63714 **
63715 **   serial type        bytes of data      type
63716 **   --------------     ---------------    ---------------
63717 **      0                     0            NULL
63718 **      1                     1            signed integer
63719 **      2                     2            signed integer
63720 **      3                     3            signed integer
63721 **      4                     4            signed integer
63722 **      5                     6            signed integer
63723 **      6                     8            signed integer
63724 **      7                     8            IEEE float
63725 **      8                     0            Integer constant 0
63726 **      9                     0            Integer constant 1
63727 **     10,11                               reserved for expansion
63728 **    N>=12 and even       (N-12)/2        BLOB
63729 **    N>=13 and odd        (N-13)/2        text
63730 **
63731 ** The 8 and 9 types were added in 3.3.0, file format 4.  Prior versions
63732 ** of SQLite will not understand those serial types.
63733 */
63734 
63735 /*
63736 ** Return the serial-type for the value stored in pMem.
63737 */
63738 SQLITE_PRIVATE u32 sqlite3VdbeSerialType(Mem *pMem, int file_format){
63739   int flags = pMem->flags;
63740   int n;
63741 
63742   if( flags&MEM_Null ){
63743     return 0;
63744   }
63745   if( flags&MEM_Int ){
63746     /* Figure out whether to use 1, 2, 4, 6 or 8 bytes. */
63747 #   define MAX_6BYTE ((((i64)0x00008000)<<32)-1)
63748     i64 i = pMem->u.i;
63749     u64 u;
63750     if( i<0 ){
63751       if( i<(-MAX_6BYTE) ) return 6;
63752       /* Previous test prevents:  u = -(-9223372036854775808) */
63753       u = -i;
63754     }else{
63755       u = i;
63756     }
63757     if( u<=127 ){
63758       return ((i&1)==i && file_format>=4) ? 8+(u32)u : 1;
63759     }
63760     if( u<=32767 ) return 2;
63761     if( u<=8388607 ) return 3;
63762     if( u<=2147483647 ) return 4;
63763     if( u<=MAX_6BYTE ) return 5;
63764     return 6;
63765   }
63766   if( flags&MEM_Real ){
63767     return 7;
63768   }
63769   assert( pMem->db->mallocFailed || flags&(MEM_Str|MEM_Blob) );
63770   n = pMem->n;
63771   if( flags & MEM_Zero ){
63772     n += pMem->u.nZero;
63773   }
63774   assert( n>=0 );
63775   return ((n*2) + 12 + ((flags&MEM_Str)!=0));
63776 }
63777 
63778 /*
63779 ** Return the length of the data corresponding to the supplied serial-type.
63780 */
63781 SQLITE_PRIVATE u32 sqlite3VdbeSerialTypeLen(u32 serial_type){
63782   if( serial_type>=12 ){
63783     return (serial_type-12)/2;
63784   }else{
63785     static const u8 aSize[] = { 0, 1, 2, 3, 4, 6, 8, 8, 0, 0, 0, 0 };
63786     return aSize[serial_type];
63787   }
63788 }
63789 
63790 /*
63791 ** If we are on an architecture with mixed-endian floating 
63792 ** points (ex: ARM7) then swap the lower 4 bytes with the 
63793 ** upper 4 bytes.  Return the result.
63794 **
63795 ** For most architectures, this is a no-op.
63796 **
63797 ** (later):  It is reported to me that the mixed-endian problem
63798 ** on ARM7 is an issue with GCC, not with the ARM7 chip.  It seems
63799 ** that early versions of GCC stored the two words of a 64-bit
63800 ** float in the wrong order.  And that error has been propagated
63801 ** ever since.  The blame is not necessarily with GCC, though.
63802 ** GCC might have just copying the problem from a prior compiler.
63803 ** I am also told that newer versions of GCC that follow a different
63804 ** ABI get the byte order right.
63805 **
63806 ** Developers using SQLite on an ARM7 should compile and run their
63807 ** application using -DSQLITE_DEBUG=1 at least once.  With DEBUG
63808 ** enabled, some asserts below will ensure that the byte order of
63809 ** floating point values is correct.
63810 **
63811 ** (2007-08-30)  Frank van Vugt has studied this problem closely
63812 ** and has send his findings to the SQLite developers.  Frank
63813 ** writes that some Linux kernels offer floating point hardware
63814 ** emulation that uses only 32-bit mantissas instead of a full 
63815 ** 48-bits as required by the IEEE standard.  (This is the
63816 ** CONFIG_FPE_FASTFPE option.)  On such systems, floating point
63817 ** byte swapping becomes very complicated.  To avoid problems,
63818 ** the necessary byte swapping is carried out using a 64-bit integer
63819 ** rather than a 64-bit float.  Frank assures us that the code here
63820 ** works for him.  We, the developers, have no way to independently
63821 ** verify this, but Frank seems to know what he is talking about
63822 ** so we trust him.
63823 */
63824 #ifdef SQLITE_MIXED_ENDIAN_64BIT_FLOAT
63825 static u64 floatSwap(u64 in){
63826   union {
63827     u64 r;
63828     u32 i[2];
63829   } u;
63830   u32 t;
63831 
63832   u.r = in;
63833   t = u.i[0];
63834   u.i[0] = u.i[1];
63835   u.i[1] = t;
63836   return u.r;
63837 }
63838 # define swapMixedEndianFloat(X)  X = floatSwap(X)
63839 #else
63840 # define swapMixedEndianFloat(X)
63841 #endif
63842 
63843 /*
63844 ** Write the serialized data blob for the value stored in pMem into 
63845 ** buf. It is assumed that the caller has allocated sufficient space.
63846 ** Return the number of bytes written.
63847 **
63848 ** nBuf is the amount of space left in buf[].  nBuf must always be
63849 ** large enough to hold the entire field.  Except, if the field is
63850 ** a blob with a zero-filled tail, then buf[] might be just the right
63851 ** size to hold everything except for the zero-filled tail.  If buf[]
63852 ** is only big enough to hold the non-zero prefix, then only write that
63853 ** prefix into buf[].  But if buf[] is large enough to hold both the
63854 ** prefix and the tail then write the prefix and set the tail to all
63855 ** zeros.
63856 **
63857 ** Return the number of bytes actually written into buf[].  The number
63858 ** of bytes in the zero-filled tail is included in the return value only
63859 ** if those bytes were zeroed in buf[].
63860 */ 
63861 SQLITE_PRIVATE u32 sqlite3VdbeSerialPut(u8 *buf, int nBuf, Mem *pMem, int file_format){
63862   u32 serial_type = sqlite3VdbeSerialType(pMem, file_format);
63863   u32 len;
63864 
63865   /* Integer and Real */
63866   if( serial_type<=7 && serial_type>0 ){
63867     u64 v;
63868     u32 i;
63869     if( serial_type==7 ){
63870       assert( sizeof(v)==sizeof(pMem->r) );
63871       memcpy(&v, &pMem->r, sizeof(v));
63872       swapMixedEndianFloat(v);
63873     }else{
63874       v = pMem->u.i;
63875     }
63876     len = i = sqlite3VdbeSerialTypeLen(serial_type);
63877     assert( len<=(u32)nBuf );
63878     while( i-- ){
63879       buf[i] = (u8)(v&0xFF);
63880       v >>= 8;
63881     }
63882     return len;
63883   }
63884 
63885   /* String or blob */
63886   if( serial_type>=12 ){
63887     assert( pMem->n + ((pMem->flags & MEM_Zero)?pMem->u.nZero:0)
63888              == (int)sqlite3VdbeSerialTypeLen(serial_type) );
63889     assert( pMem->n<=nBuf );
63890     len = pMem->n;
63891     memcpy(buf, pMem->z, len);
63892     if( pMem->flags & MEM_Zero ){
63893       len += pMem->u.nZero;
63894       assert( nBuf>=0 );
63895       if( len > (u32)nBuf ){
63896         len = (u32)nBuf;
63897       }
63898       memset(&buf[pMem->n], 0, len-pMem->n);
63899     }
63900     return len;
63901   }
63902 
63903   /* NULL or constants 0 or 1 */
63904   return 0;
63905 }
63906 
63907 /*
63908 ** Deserialize the data blob pointed to by buf as serial type serial_type
63909 ** and store the result in pMem.  Return the number of bytes read.
63910 */ 
63911 SQLITE_PRIVATE u32 sqlite3VdbeSerialGet(
63912   const unsigned char *buf,     /* Buffer to deserialize from */
63913   u32 serial_type,              /* Serial type to deserialize */
63914   Mem *pMem                     /* Memory cell to write value into */
63915 ){
63916   switch( serial_type ){
63917     case 10:   /* Reserved for future use */
63918     case 11:   /* Reserved for future use */
63919     case 0: {  /* NULL */
63920       pMem->flags = MEM_Null;
63921       break;
63922     }
63923     case 1: { /* 1-byte signed integer */
63924       pMem->u.i = (signed char)buf[0];
63925       pMem->flags = MEM_Int;
63926       return 1;
63927     }
63928     case 2: { /* 2-byte signed integer */
63929       pMem->u.i = (((signed char)buf[0])<<8) | buf[1];
63930       pMem->flags = MEM_Int;
63931       return 2;
63932     }
63933     case 3: { /* 3-byte signed integer */
63934       pMem->u.i = (((signed char)buf[0])<<16) | (buf[1]<<8) | buf[2];
63935       pMem->flags = MEM_Int;
63936       return 3;
63937     }
63938     case 4: { /* 4-byte signed integer */
63939       pMem->u.i = (buf[0]<<24) | (buf[1]<<16) | (buf[2]<<8) | buf[3];
63940       pMem->flags = MEM_Int;
63941       return 4;
63942     }
63943     case 5: { /* 6-byte signed integer */
63944       u64 x = (((signed char)buf[0])<<8) | buf[1];
63945       u32 y = (buf[2]<<24) | (buf[3]<<16) | (buf[4]<<8) | buf[5];
63946       x = (x<<32) | y;
63947       pMem->u.i = *(i64*)&x;
63948       pMem->flags = MEM_Int;
63949       return 6;
63950     }
63951     case 6:   /* 8-byte signed integer */
63952     case 7: { /* IEEE floating point */
63953       u64 x;
63954       u32 y;
63955 #if !defined(NDEBUG) && !defined(SQLITE_OMIT_FLOATING_POINT)
63956       /* Verify that integers and floating point values use the same
63957       ** byte order.  Or, that if SQLITE_MIXED_ENDIAN_64BIT_FLOAT is
63958       ** defined that 64-bit floating point values really are mixed
63959       ** endian.
63960       */
63961       static const u64 t1 = ((u64)0x3ff00000)<<32;
63962       static const double r1 = 1.0;
63963       u64 t2 = t1;
63964       swapMixedEndianFloat(t2);
63965       assert( sizeof(r1)==sizeof(t2) && memcmp(&r1, &t2, sizeof(r1))==0 );
63966 #endif
63967 
63968       x = (buf[0]<<24) | (buf[1]<<16) | (buf[2]<<8) | buf[3];
63969       y = (buf[4]<<24) | (buf[5]<<16) | (buf[6]<<8) | buf[7];
63970       x = (x<<32) | y;
63971       if( serial_type==6 ){
63972         pMem->u.i = *(i64*)&x;
63973         pMem->flags = MEM_Int;
63974       }else{
63975         assert( sizeof(x)==8 && sizeof(pMem->r)==8 );
63976         swapMixedEndianFloat(x);
63977         memcpy(&pMem->r, &x, sizeof(x));
63978         pMem->flags = sqlite3IsNaN(pMem->r) ? MEM_Null : MEM_Real;
63979       }
63980       return 8;
63981     }
63982     case 8:    /* Integer 0 */
63983     case 9: {  /* Integer 1 */
63984       pMem->u.i = serial_type-8;
63985       pMem->flags = MEM_Int;
63986       return 0;
63987     }
63988     default: {
63989       static const u16 aFlag[] = { MEM_Blob|MEM_Ephem, MEM_Str|MEM_Ephem };
63990       u32 len = (serial_type-12)/2;
63991       pMem->z = (char *)buf;
63992       pMem->n = len;
63993       pMem->xDel = 0;
63994       pMem->flags = aFlag[serial_type&1];
63995       return len;
63996     }
63997   }
63998   return 0;
63999 }
64000 
64001 /*
64002 ** This routine is used to allocate sufficient space for an UnpackedRecord
64003 ** structure large enough to be used with sqlite3VdbeRecordUnpack() if
64004 ** the first argument is a pointer to KeyInfo structure pKeyInfo.
64005 **
64006 ** The space is either allocated using sqlite3DbMallocRaw() or from within
64007 ** the unaligned buffer passed via the second and third arguments (presumably
64008 ** stack space). If the former, then *ppFree is set to a pointer that should
64009 ** be eventually freed by the caller using sqlite3DbFree(). Or, if the 
64010 ** allocation comes from the pSpace/szSpace buffer, *ppFree is set to NULL
64011 ** before returning.
64012 **
64013 ** If an OOM error occurs, NULL is returned.
64014 */
64015 SQLITE_PRIVATE UnpackedRecord *sqlite3VdbeAllocUnpackedRecord(
64016   KeyInfo *pKeyInfo,              /* Description of the record */
64017   char *pSpace,                   /* Unaligned space available */
64018   int szSpace,                    /* Size of pSpace[] in bytes */
64019   char **ppFree                   /* OUT: Caller should free this pointer */
64020 ){
64021   UnpackedRecord *p;              /* Unpacked record to return */
64022   int nOff;                       /* Increment pSpace by nOff to align it */
64023   int nByte;                      /* Number of bytes required for *p */
64024 
64025   /* We want to shift the pointer pSpace up such that it is 8-byte aligned.
64026   ** Thus, we need to calculate a value, nOff, between 0 and 7, to shift 
64027   ** it by.  If pSpace is already 8-byte aligned, nOff should be zero.
64028   */
64029   nOff = (8 - (SQLITE_PTR_TO_INT(pSpace) & 7)) & 7;
64030   nByte = ROUND8(sizeof(UnpackedRecord)) + sizeof(Mem)*(pKeyInfo->nField+1);
64031   if( nByte>szSpace+nOff ){
64032     p = (UnpackedRecord *)sqlite3DbMallocRaw(pKeyInfo->db, nByte);
64033     *ppFree = (char *)p;
64034     if( !p ) return 0;
64035   }else{
64036     p = (UnpackedRecord*)&pSpace[nOff];
64037     *ppFree = 0;
64038   }
64039 
64040   p->aMem = (Mem*)&((char*)p)[ROUND8(sizeof(UnpackedRecord))];
64041   assert( pKeyInfo->aSortOrder!=0 );
64042   p->pKeyInfo = pKeyInfo;
64043   p->nField = pKeyInfo->nField + 1;
64044   return p;
64045 }
64046 
64047 /*
64048 ** Given the nKey-byte encoding of a record in pKey[], populate the 
64049 ** UnpackedRecord structure indicated by the fourth argument with the
64050 ** contents of the decoded record.
64051 */ 
64052 SQLITE_PRIVATE void sqlite3VdbeRecordUnpack(
64053   KeyInfo *pKeyInfo,     /* Information about the record format */
64054   int nKey,              /* Size of the binary record */
64055   const void *pKey,      /* The binary record */
64056   UnpackedRecord *p      /* Populate this structure before returning. */
64057 ){
64058   const unsigned char *aKey = (const unsigned char *)pKey;
64059   int d; 
64060   u32 idx;                        /* Offset in aKey[] to read from */
64061   u16 u;                          /* Unsigned loop counter */
64062   u32 szHdr;
64063   Mem *pMem = p->aMem;
64064 
64065   p->flags = 0;
64066   assert( EIGHT_BYTE_ALIGNMENT(pMem) );
64067   idx = getVarint32(aKey, szHdr);
64068   d = szHdr;
64069   u = 0;
64070   while( idx<szHdr && u<p->nField && d<=nKey ){
64071     u32 serial_type;
64072 
64073     idx += getVarint32(&aKey[idx], serial_type);
64074     pMem->enc = pKeyInfo->enc;
64075     pMem->db = pKeyInfo->db;
64076     /* pMem->flags = 0; // sqlite3VdbeSerialGet() will set this for us */
64077     pMem->zMalloc = 0;
64078     d += sqlite3VdbeSerialGet(&aKey[d], serial_type, pMem);
64079     pMem++;
64080     u++;
64081   }
64082   assert( u<=pKeyInfo->nField + 1 );
64083   p->nField = u;
64084 }
64085 
64086 /*
64087 ** This function compares the two table rows or index records
64088 ** specified by {nKey1, pKey1} and pPKey2.  It returns a negative, zero
64089 ** or positive integer if key1 is less than, equal to or 
64090 ** greater than key2.  The {nKey1, pKey1} key must be a blob
64091 ** created by th OP_MakeRecord opcode of the VDBE.  The pPKey2
64092 ** key must be a parsed key such as obtained from
64093 ** sqlite3VdbeParseRecord.
64094 **
64095 ** Key1 and Key2 do not have to contain the same number of fields.
64096 ** The key with fewer fields is usually compares less than the 
64097 ** longer key.  However if the UNPACKED_INCRKEY flags in pPKey2 is set
64098 ** and the common prefixes are equal, then key1 is less than key2.
64099 ** Or if the UNPACKED_MATCH_PREFIX flag is set and the prefixes are
64100 ** equal, then the keys are considered to be equal and
64101 ** the parts beyond the common prefix are ignored.
64102 */
64103 SQLITE_PRIVATE int sqlite3VdbeRecordCompare(
64104   int nKey1, const void *pKey1, /* Left key */
64105   UnpackedRecord *pPKey2        /* Right key */
64106 ){
64107   u32 d1;            /* Offset into aKey[] of next data element */
64108   u32 idx1;          /* Offset into aKey[] of next header element */
64109   u32 szHdr1;        /* Number of bytes in header */
64110   int i = 0;
64111   int rc = 0;
64112   const unsigned char *aKey1 = (const unsigned char *)pKey1;
64113   KeyInfo *pKeyInfo;
64114   Mem mem1;
64115 
64116   pKeyInfo = pPKey2->pKeyInfo;
64117   mem1.enc = pKeyInfo->enc;
64118   mem1.db = pKeyInfo->db;
64119   /* mem1.flags = 0;  // Will be initialized by sqlite3VdbeSerialGet() */
64120   VVA_ONLY( mem1.zMalloc = 0; ) /* Only needed by assert() statements */
64121 
64122   /* Compilers may complain that mem1.u.i is potentially uninitialized.
64123   ** We could initialize it, as shown here, to silence those complaints.
64124   ** But in fact, mem1.u.i will never actually be used uninitialized, and doing 
64125   ** the unnecessary initialization has a measurable negative performance
64126   ** impact, since this routine is a very high runner.  And so, we choose
64127   ** to ignore the compiler warnings and leave this variable uninitialized.
64128   */
64129   /*  mem1.u.i = 0;  // not needed, here to silence compiler warning */
64130   
64131   idx1 = getVarint32(aKey1, szHdr1);
64132   d1 = szHdr1;
64133   assert( pKeyInfo->nField+pKeyInfo->nXField>=pPKey2->nField || CORRUPT_DB );
64134   assert( pKeyInfo->aSortOrder!=0 );
64135   assert( pKeyInfo->nField>0 );
64136   assert( idx1<=szHdr1 || CORRUPT_DB );
64137   do{
64138     u32 serial_type1;
64139 
64140     /* Read the serial types for the next element in each key. */
64141     idx1 += getVarint32( aKey1+idx1, serial_type1 );
64142 
64143     /* Verify that there is enough key space remaining to avoid
64144     ** a buffer overread.  The "d1+serial_type1+2" subexpression will
64145     ** always be greater than or equal to the amount of required key space.
64146     ** Use that approximation to avoid the more expensive call to
64147     ** sqlite3VdbeSerialTypeLen() in the common case.
64148     */
64149     if( d1+serial_type1+2>(u32)nKey1
64150      && d1+sqlite3VdbeSerialTypeLen(serial_type1)>(u32)nKey1 
64151     ){
64152       break;
64153     }
64154 
64155     /* Extract the values to be compared.
64156     */
64157     d1 += sqlite3VdbeSerialGet(&aKey1[d1], serial_type1, &mem1);
64158 
64159     /* Do the comparison
64160     */
64161     rc = sqlite3MemCompare(&mem1, &pPKey2->aMem[i], pKeyInfo->aColl[i]);
64162     if( rc!=0 ){
64163       assert( mem1.zMalloc==0 );  /* See comment below */
64164       if( pKeyInfo->aSortOrder[i] ){
64165         rc = -rc;  /* Invert the result for DESC sort order. */
64166       }
64167       return rc;
64168     }
64169     i++;
64170   }while( idx1<szHdr1 && i<pPKey2->nField );
64171 
64172   /* No memory allocation is ever used on mem1.  Prove this using
64173   ** the following assert().  If the assert() fails, it indicates a
64174   ** memory leak and a need to call sqlite3VdbeMemRelease(&mem1).
64175   */
64176   assert( mem1.zMalloc==0 );
64177 
64178   /* rc==0 here means that one of the keys ran out of fields and
64179   ** all the fields up to that point were equal. If the UNPACKED_INCRKEY
64180   ** flag is set, then break the tie by treating key2 as larger.
64181   ** If the UPACKED_PREFIX_MATCH flag is set, then keys with common prefixes
64182   ** are considered to be equal.  Otherwise, the longer key is the 
64183   ** larger.  As it happens, the pPKey2 will always be the longer
64184   ** if there is a difference.
64185   */
64186   assert( rc==0 );
64187   if( pPKey2->flags & UNPACKED_INCRKEY ){
64188     rc = -1;
64189   }else if( pPKey2->flags & UNPACKED_PREFIX_MATCH ){
64190     /* Leave rc==0 */
64191   }else if( idx1<szHdr1 ){
64192     rc = 1;
64193   }
64194   return rc;
64195 }
64196  
64197 
64198 /*
64199 ** pCur points at an index entry created using the OP_MakeRecord opcode.
64200 ** Read the rowid (the last field in the record) and store it in *rowid.
64201 ** Return SQLITE_OK if everything works, or an error code otherwise.
64202 **
64203 ** pCur might be pointing to text obtained from a corrupt database file.
64204 ** So the content cannot be trusted.  Do appropriate checks on the content.
64205 */
64206 SQLITE_PRIVATE int sqlite3VdbeIdxRowid(sqlite3 *db, BtCursor *pCur, i64 *rowid){
64207   i64 nCellKey = 0;
64208   int rc;
64209   u32 szHdr;        /* Size of the header */
64210   u32 typeRowid;    /* Serial type of the rowid */
64211   u32 lenRowid;     /* Size of the rowid */
64212   Mem m, v;
64213 
64214   UNUSED_PARAMETER(db);
64215 
64216   /* Get the size of the index entry.  Only indices entries of less
64217   ** than 2GiB are support - anything large must be database corruption.
64218   ** Any corruption is detected in sqlite3BtreeParseCellPtr(), though, so
64219   ** this code can safely assume that nCellKey is 32-bits  
64220   */
64221   assert( sqlite3BtreeCursorIsValid(pCur) );
64222   VVA_ONLY(rc =) sqlite3BtreeKeySize(pCur, &nCellKey);
64223   assert( rc==SQLITE_OK );     /* pCur is always valid so KeySize cannot fail */
64224   assert( (nCellKey & SQLITE_MAX_U32)==(u64)nCellKey );
64225 
64226   /* Read in the complete content of the index entry */
64227   memset(&m, 0, sizeof(m));
64228   rc = sqlite3VdbeMemFromBtree(pCur, 0, (u32)nCellKey, 1, &m);
64229   if( rc ){
64230     return rc;
64231   }
64232 
64233   /* The index entry must begin with a header size */
64234   (void)getVarint32((u8*)m.z, szHdr);
64235   testcase( szHdr==3 );
64236   testcase( szHdr==m.n );
64237   if( unlikely(szHdr<3 || (int)szHdr>m.n) ){
64238     goto idx_rowid_corruption;
64239   }
64240 
64241   /* The last field of the index should be an integer - the ROWID.
64242   ** Verify that the last entry really is an integer. */
64243   (void)getVarint32((u8*)&m.z[szHdr-1], typeRowid);
64244   testcase( typeRowid==1 );
64245   testcase( typeRowid==2 );
64246   testcase( typeRowid==3 );
64247   testcase( typeRowid==4 );
64248   testcase( typeRowid==5 );
64249   testcase( typeRowid==6 );
64250   testcase( typeRowid==8 );
64251   testcase( typeRowid==9 );
64252   if( unlikely(typeRowid<1 || typeRowid>9 || typeRowid==7) ){
64253     goto idx_rowid_corruption;
64254   }
64255   lenRowid = sqlite3VdbeSerialTypeLen(typeRowid);
64256   testcase( (u32)m.n==szHdr+lenRowid );
64257   if( unlikely((u32)m.n<szHdr+lenRowid) ){
64258     goto idx_rowid_corruption;
64259   }
64260 
64261   /* Fetch the integer off the end of the index record */
64262   sqlite3VdbeSerialGet((u8*)&m.z[m.n-lenRowid], typeRowid, &v);
64263   *rowid = v.u.i;
64264   sqlite3VdbeMemRelease(&m);
64265   return SQLITE_OK;
64266 
64267   /* Jump here if database corruption is detected after m has been
64268   ** allocated.  Free the m object and return SQLITE_CORRUPT. */
64269 idx_rowid_corruption:
64270   testcase( m.zMalloc!=0 );
64271   sqlite3VdbeMemRelease(&m);
64272   return SQLITE_CORRUPT_BKPT;
64273 }
64274 
64275 /*
64276 ** Compare the key of the index entry that cursor pC is pointing to against
64277 ** the key string in pUnpacked.  Write into *pRes a number
64278 ** that is negative, zero, or positive if pC is less than, equal to,
64279 ** or greater than pUnpacked.  Return SQLITE_OK on success.
64280 **
64281 ** pUnpacked is either created without a rowid or is truncated so that it
64282 ** omits the rowid at the end.  The rowid at the end of the index entry
64283 ** is ignored as well.  Hence, this routine only compares the prefixes 
64284 ** of the keys prior to the final rowid, not the entire key.
64285 */
64286 SQLITE_PRIVATE int sqlite3VdbeIdxKeyCompare(
64287   VdbeCursor *pC,             /* The cursor to compare against */
64288   UnpackedRecord *pUnpacked,  /* Unpacked version of key to compare against */
64289   int *res                    /* Write the comparison result here */
64290 ){
64291   i64 nCellKey = 0;
64292   int rc;
64293   BtCursor *pCur = pC->pCursor;
64294   Mem m;
64295 
64296   assert( sqlite3BtreeCursorIsValid(pCur) );
64297   VVA_ONLY(rc =) sqlite3BtreeKeySize(pCur, &nCellKey);
64298   assert( rc==SQLITE_OK );    /* pCur is always valid so KeySize cannot fail */
64299   /* nCellKey will always be between 0 and 0xffffffff because of the say
64300   ** that btreeParseCellPtr() and sqlite3GetVarint32() are implemented */
64301   if( nCellKey<=0 || nCellKey>0x7fffffff ){
64302     *res = 0;
64303     return SQLITE_CORRUPT_BKPT;
64304   }
64305   memset(&m, 0, sizeof(m));
64306   rc = sqlite3VdbeMemFromBtree(pC->pCursor, 0, (u32)nCellKey, 1, &m);
64307   if( rc ){
64308     return rc;
64309   }
64310   assert( pUnpacked->flags & UNPACKED_PREFIX_MATCH );
64311   *res = sqlite3VdbeRecordCompare(m.n, m.z, pUnpacked);
64312   sqlite3VdbeMemRelease(&m);
64313   return SQLITE_OK;
64314 }
64315 
64316 /*
64317 ** This routine sets the value to be returned by subsequent calls to
64318 ** sqlite3_changes() on the database handle 'db'. 
64319 */
64320 SQLITE_PRIVATE void sqlite3VdbeSetChanges(sqlite3 *db, int nChange){
64321   assert( sqlite3_mutex_held(db->mutex) );
64322   db->nChange = nChange;
64323   db->nTotalChange += nChange;
64324 }
64325 
64326 /*
64327 ** Set a flag in the vdbe to update the change counter when it is finalised
64328 ** or reset.
64329 */
64330 SQLITE_PRIVATE void sqlite3VdbeCountChanges(Vdbe *v){
64331   v->changeCntOn = 1;
64332 }
64333 
64334 /*
64335 ** Mark every prepared statement associated with a database connection
64336 ** as expired.
64337 **
64338 ** An expired statement means that recompilation of the statement is
64339 ** recommend.  Statements expire when things happen that make their
64340 ** programs obsolete.  Removing user-defined functions or collating
64341 ** sequences, or changing an authorization function are the types of
64342 ** things that make prepared statements obsolete.
64343 */
64344 SQLITE_PRIVATE void sqlite3ExpirePreparedStatements(sqlite3 *db){
64345   Vdbe *p;
64346   for(p = db->pVdbe; p; p=p->pNext){
64347     p->expired = 1;
64348   }
64349 }
64350 
64351 /*
64352 ** Return the database associated with the Vdbe.
64353 */
64354 SQLITE_PRIVATE sqlite3 *sqlite3VdbeDb(Vdbe *v){
64355   return v->db;
64356 }
64357 
64358 /*
64359 ** Return a pointer to an sqlite3_value structure containing the value bound
64360 ** parameter iVar of VM v. Except, if the value is an SQL NULL, return 
64361 ** 0 instead. Unless it is NULL, apply affinity aff (one of the SQLITE_AFF_*
64362 ** constants) to the value before returning it.
64363 **
64364 ** The returned value must be freed by the caller using sqlite3ValueFree().
64365 */
64366 SQLITE_PRIVATE sqlite3_value *sqlite3VdbeGetBoundValue(Vdbe *v, int iVar, u8 aff){
64367   assert( iVar>0 );
64368   if( v ){
64369     Mem *pMem = &v->aVar[iVar-1];
64370     if( 0==(pMem->flags & MEM_Null) ){
64371       sqlite3_value *pRet = sqlite3ValueNew(v->db);
64372       if( pRet ){
64373         sqlite3VdbeMemCopy((Mem *)pRet, pMem);
64374         sqlite3ValueApplyAffinity(pRet, aff, SQLITE_UTF8);
64375         sqlite3VdbeMemStoreType((Mem *)pRet);
64376       }
64377       return pRet;
64378     }
64379   }
64380   return 0;
64381 }
64382 
64383 /*
64384 ** Configure SQL variable iVar so that binding a new value to it signals
64385 ** to sqlite3_reoptimize() that re-preparing the statement may result
64386 ** in a better query plan.
64387 */
64388 SQLITE_PRIVATE void sqlite3VdbeSetVarmask(Vdbe *v, int iVar){
64389   assert( iVar>0 );
64390   if( iVar>32 ){
64391     v->expmask = 0xffffffff;
64392   }else{
64393     v->expmask |= ((u32)1 << (iVar-1));
64394   }
64395 }
64396 
64397 #ifndef SQLITE_OMIT_VIRTUALTABLE
64398 /*
64399 ** Transfer error message text from an sqlite3_vtab.zErrMsg (text stored
64400 ** in memory obtained from sqlite3_malloc) into a Vdbe.zErrMsg (text stored
64401 ** in memory obtained from sqlite3DbMalloc).
64402 */
64403 SQLITE_PRIVATE void sqlite3VtabImportErrmsg(Vdbe *p, sqlite3_vtab *pVtab){
64404   sqlite3 *db = p->db;
64405   sqlite3DbFree(db, p->zErrMsg);
64406   p->zErrMsg = sqlite3DbStrDup(db, pVtab->zErrMsg);
64407   sqlite3_free(pVtab->zErrMsg);
64408   pVtab->zErrMsg = 0;
64409 }
64410 #endif /* SQLITE_OMIT_VIRTUALTABLE */
64411 
64412 /************** End of vdbeaux.c *********************************************/
64413 /************** Begin file vdbeapi.c *****************************************/
64414 /*
64415 ** 2004 May 26
64416 **
64417 ** The author disclaims copyright to this source code.  In place of
64418 ** a legal notice, here is a blessing:
64419 **
64420 **    May you do good and not evil.
64421 **    May you find forgiveness for yourself and forgive others.
64422 **    May you share freely, never taking more than you give.
64423 **
64424 *************************************************************************
64425 **
64426 ** This file contains code use to implement APIs that are part of the
64427 ** VDBE.
64428 */
64429 
64430 #ifndef SQLITE_OMIT_DEPRECATED
64431 /*
64432 ** Return TRUE (non-zero) of the statement supplied as an argument needs
64433 ** to be recompiled.  A statement needs to be recompiled whenever the
64434 ** execution environment changes in a way that would alter the program
64435 ** that sqlite3_prepare() generates.  For example, if new functions or
64436 ** collating sequences are registered or if an authorizer function is
64437 ** added or changed.
64438 */
64439 SQLITE_API int sqlite3_expired(sqlite3_stmt *pStmt){
64440   Vdbe *p = (Vdbe*)pStmt;
64441   return p==0 || p->expired;
64442 }
64443 #endif
64444 
64445 /*
64446 ** Check on a Vdbe to make sure it has not been finalized.  Log
64447 ** an error and return true if it has been finalized (or is otherwise
64448 ** invalid).  Return false if it is ok.
64449 */
64450 static int vdbeSafety(Vdbe *p){
64451   if( p->db==0 ){
64452     sqlite3_log(SQLITE_MISUSE, "API called with finalized prepared statement");
64453     return 1;
64454   }else{
64455     return 0;
64456   }
64457 }
64458 static int vdbeSafetyNotNull(Vdbe *p){
64459   if( p==0 ){
64460     sqlite3_log(SQLITE_MISUSE, "API called with NULL prepared statement");
64461     return 1;
64462   }else{
64463     return vdbeSafety(p);
64464   }
64465 }
64466 
64467 /*
64468 ** The following routine destroys a virtual machine that is created by
64469 ** the sqlite3_compile() routine. The integer returned is an SQLITE_
64470 ** success/failure code that describes the result of executing the virtual
64471 ** machine.
64472 **
64473 ** This routine sets the error code and string returned by
64474 ** sqlite3_errcode(), sqlite3_errmsg() and sqlite3_errmsg16().
64475 */
64476 SQLITE_API int sqlite3_finalize(sqlite3_stmt *pStmt){
64477   int rc;
64478   if( pStmt==0 ){
64479     /* IMPLEMENTATION-OF: R-57228-12904 Invoking sqlite3_finalize() on a NULL
64480     ** pointer is a harmless no-op. */
64481     rc = SQLITE_OK;
64482   }else{
64483     Vdbe *v = (Vdbe*)pStmt;
64484     sqlite3 *db = v->db;
64485     if( vdbeSafety(v) ) return SQLITE_MISUSE_BKPT;
64486     sqlite3_mutex_enter(db->mutex);
64487     rc = sqlite3VdbeFinalize(v);
64488     rc = sqlite3ApiExit(db, rc);
64489     sqlite3LeaveMutexAndCloseZombie(db);
64490   }
64491   return rc;
64492 }
64493 
64494 /*
64495 ** Terminate the current execution of an SQL statement and reset it
64496 ** back to its starting state so that it can be reused. A success code from
64497 ** the prior execution is returned.
64498 **
64499 ** This routine sets the error code and string returned by
64500 ** sqlite3_errcode(), sqlite3_errmsg() and sqlite3_errmsg16().
64501 */
64502 SQLITE_API int sqlite3_reset(sqlite3_stmt *pStmt){
64503   int rc;
64504   if( pStmt==0 ){
64505     rc = SQLITE_OK;
64506   }else{
64507     Vdbe *v = (Vdbe*)pStmt;
64508     sqlite3_mutex_enter(v->db->mutex);
64509     rc = sqlite3VdbeReset(v);
64510     sqlite3VdbeRewind(v);
64511     assert( (rc & (v->db->errMask))==rc );
64512     rc = sqlite3ApiExit(v->db, rc);
64513     sqlite3_mutex_leave(v->db->mutex);
64514   }
64515   return rc;
64516 }
64517 
64518 /*
64519 ** Set all the parameters in the compiled SQL statement to NULL.
64520 */
64521 SQLITE_API int sqlite3_clear_bindings(sqlite3_stmt *pStmt){
64522   int i;
64523   int rc = SQLITE_OK;
64524   Vdbe *p = (Vdbe*)pStmt;
64525 #if SQLITE_THREADSAFE
64526   sqlite3_mutex *mutex = ((Vdbe*)pStmt)->db->mutex;
64527 #endif
64528   sqlite3_mutex_enter(mutex);
64529   for(i=0; i<p->nVar; i++){
64530     sqlite3VdbeMemRelease(&p->aVar[i]);
64531     p->aVar[i].flags = MEM_Null;
64532   }
64533   if( p->isPrepareV2 && p->expmask ){
64534     p->expired = 1;
64535   }
64536   sqlite3_mutex_leave(mutex);
64537   return rc;
64538 }
64539 
64540 
64541 /**************************** sqlite3_value_  *******************************
64542 ** The following routines extract information from a Mem or sqlite3_value
64543 ** structure.
64544 */
64545 SQLITE_API const void *sqlite3_value_blob(sqlite3_value *pVal){
64546   Mem *p = (Mem*)pVal;
64547   if( p->flags & (MEM_Blob|MEM_Str) ){
64548     sqlite3VdbeMemExpandBlob(p);
64549     p->flags &= ~MEM_Str;
64550     p->flags |= MEM_Blob;
64551     return p->n ? p->z : 0;
64552   }else{
64553     return sqlite3_value_text(pVal);
64554   }
64555 }
64556 SQLITE_API int sqlite3_value_bytes(sqlite3_value *pVal){
64557   return sqlite3ValueBytes(pVal, SQLITE_UTF8);
64558 }
64559 SQLITE_API int sqlite3_value_bytes16(sqlite3_value *pVal){
64560   return sqlite3ValueBytes(pVal, SQLITE_UTF16NATIVE);
64561 }
64562 SQLITE_API double sqlite3_value_double(sqlite3_value *pVal){
64563   return sqlite3VdbeRealValue((Mem*)pVal);
64564 }
64565 SQLITE_API int sqlite3_value_int(sqlite3_value *pVal){
64566   return (int)sqlite3VdbeIntValue((Mem*)pVal);
64567 }
64568 SQLITE_API sqlite_int64 sqlite3_value_int64(sqlite3_value *pVal){
64569   return sqlite3VdbeIntValue((Mem*)pVal);
64570 }
64571 SQLITE_API const unsigned char *sqlite3_value_text(sqlite3_value *pVal){
64572   return (const unsigned char *)sqlite3ValueText(pVal, SQLITE_UTF8);
64573 }
64574 #ifndef SQLITE_OMIT_UTF16
64575 SQLITE_API const void *sqlite3_value_text16(sqlite3_value* pVal){
64576   return sqlite3ValueText(pVal, SQLITE_UTF16NATIVE);
64577 }
64578 SQLITE_API const void *sqlite3_value_text16be(sqlite3_value *pVal){
64579   return sqlite3ValueText(pVal, SQLITE_UTF16BE);
64580 }
64581 SQLITE_API const void *sqlite3_value_text16le(sqlite3_value *pVal){
64582   return sqlite3ValueText(pVal, SQLITE_UTF16LE);
64583 }
64584 #endif /* SQLITE_OMIT_UTF16 */
64585 SQLITE_API int sqlite3_value_type(sqlite3_value* pVal){
64586   return pVal->type;
64587 }
64588 
64589 /**************************** sqlite3_result_  *******************************
64590 ** The following routines are used by user-defined functions to specify
64591 ** the function result.
64592 **
64593 ** The setStrOrError() funtion calls sqlite3VdbeMemSetStr() to store the
64594 ** result as a string or blob but if the string or blob is too large, it
64595 ** then sets the error code to SQLITE_TOOBIG
64596 */
64597 static void setResultStrOrError(
64598   sqlite3_context *pCtx,  /* Function context */
64599   const char *z,          /* String pointer */
64600   int n,                  /* Bytes in string, or negative */
64601   u8 enc,                 /* Encoding of z.  0 for BLOBs */
64602   void (*xDel)(void*)     /* Destructor function */
64603 ){
64604   if( sqlite3VdbeMemSetStr(&pCtx->s, z, n, enc, xDel)==SQLITE_TOOBIG ){
64605     sqlite3_result_error_toobig(pCtx);
64606   }
64607 }
64608 SQLITE_API void sqlite3_result_blob(
64609   sqlite3_context *pCtx, 
64610   const void *z, 
64611   int n, 
64612   void (*xDel)(void *)
64613 ){
64614   assert( n>=0 );
64615   assert( sqlite3_mutex_held(pCtx->s.db->mutex) );
64616   setResultStrOrError(pCtx, z, n, 0, xDel);
64617 }
64618 SQLITE_API void sqlite3_result_double(sqlite3_context *pCtx, double rVal){
64619   assert( sqlite3_mutex_held(pCtx->s.db->mutex) );
64620   sqlite3VdbeMemSetDouble(&pCtx->s, rVal);
64621 }
64622 SQLITE_API void sqlite3_result_error(sqlite3_context *pCtx, const char *z, int n){
64623   assert( sqlite3_mutex_held(pCtx->s.db->mutex) );
64624   pCtx->isError = SQLITE_ERROR;
64625   pCtx->fErrorOrAux = 1;
64626   sqlite3VdbeMemSetStr(&pCtx->s, z, n, SQLITE_UTF8, SQLITE_TRANSIENT);
64627 }
64628 #ifndef SQLITE_OMIT_UTF16
64629 SQLITE_API void sqlite3_result_error16(sqlite3_context *pCtx, const void *z, int n){
64630   assert( sqlite3_mutex_held(pCtx->s.db->mutex) );
64631   pCtx->isError = SQLITE_ERROR;
64632   pCtx->fErrorOrAux = 1;
64633   sqlite3VdbeMemSetStr(&pCtx->s, z, n, SQLITE_UTF16NATIVE, SQLITE_TRANSIENT);
64634 }
64635 #endif
64636 SQLITE_API void sqlite3_result_int(sqlite3_context *pCtx, int iVal){
64637   assert( sqlite3_mutex_held(pCtx->s.db->mutex) );
64638   sqlite3VdbeMemSetInt64(&pCtx->s, (i64)iVal);
64639 }
64640 SQLITE_API void sqlite3_result_int64(sqlite3_context *pCtx, i64 iVal){
64641   assert( sqlite3_mutex_held(pCtx->s.db->mutex) );
64642   sqlite3VdbeMemSetInt64(&pCtx->s, iVal);
64643 }
64644 SQLITE_API void sqlite3_result_null(sqlite3_context *pCtx){
64645   assert( sqlite3_mutex_held(pCtx->s.db->mutex) );
64646   sqlite3VdbeMemSetNull(&pCtx->s);
64647 }
64648 SQLITE_API void sqlite3_result_text(
64649   sqlite3_context *pCtx, 
64650   const char *z, 
64651   int n,
64652   void (*xDel)(void *)
64653 ){
64654   assert( sqlite3_mutex_held(pCtx->s.db->mutex) );
64655   setResultStrOrError(pCtx, z, n, SQLITE_UTF8, xDel);
64656 }
64657 #ifndef SQLITE_OMIT_UTF16
64658 SQLITE_API void sqlite3_result_text16(
64659   sqlite3_context *pCtx, 
64660   const void *z, 
64661   int n, 
64662   void (*xDel)(void *)
64663 ){
64664   assert( sqlite3_mutex_held(pCtx->s.db->mutex) );
64665   setResultStrOrError(pCtx, z, n, SQLITE_UTF16NATIVE, xDel);
64666 }
64667 SQLITE_API void sqlite3_result_text16be(
64668   sqlite3_context *pCtx, 
64669   const void *z, 
64670   int n, 
64671   void (*xDel)(void *)
64672 ){
64673   assert( sqlite3_mutex_held(pCtx->s.db->mutex) );
64674   setResultStrOrError(pCtx, z, n, SQLITE_UTF16BE, xDel);
64675 }
64676 SQLITE_API void sqlite3_result_text16le(
64677   sqlite3_context *pCtx, 
64678   const void *z, 
64679   int n, 
64680   void (*xDel)(void *)
64681 ){
64682   assert( sqlite3_mutex_held(pCtx->s.db->mutex) );
64683   setResultStrOrError(pCtx, z, n, SQLITE_UTF16LE, xDel);
64684 }
64685 #endif /* SQLITE_OMIT_UTF16 */
64686 SQLITE_API void sqlite3_result_value(sqlite3_context *pCtx, sqlite3_value *pValue){
64687   assert( sqlite3_mutex_held(pCtx->s.db->mutex) );
64688   sqlite3VdbeMemCopy(&pCtx->s, pValue);
64689 }
64690 SQLITE_API void sqlite3_result_zeroblob(sqlite3_context *pCtx, int n){
64691   assert( sqlite3_mutex_held(pCtx->s.db->mutex) );
64692   sqlite3VdbeMemSetZeroBlob(&pCtx->s, n);
64693 }
64694 SQLITE_API void sqlite3_result_error_code(sqlite3_context *pCtx, int errCode){
64695   pCtx->isError = errCode;
64696   pCtx->fErrorOrAux = 1;
64697   if( pCtx->s.flags & MEM_Null ){
64698     sqlite3VdbeMemSetStr(&pCtx->s, sqlite3ErrStr(errCode), -1, 
64699                          SQLITE_UTF8, SQLITE_STATIC);
64700   }
64701 }
64702 
64703 /* Force an SQLITE_TOOBIG error. */
64704 SQLITE_API void sqlite3_result_error_toobig(sqlite3_context *pCtx){
64705   assert( sqlite3_mutex_held(pCtx->s.db->mutex) );
64706   pCtx->isError = SQLITE_TOOBIG;
64707   pCtx->fErrorOrAux = 1;
64708   sqlite3VdbeMemSetStr(&pCtx->s, "string or blob too big", -1, 
64709                        SQLITE_UTF8, SQLITE_STATIC);
64710 }
64711 
64712 /* An SQLITE_NOMEM error. */
64713 SQLITE_API void sqlite3_result_error_nomem(sqlite3_context *pCtx){
64714   assert( sqlite3_mutex_held(pCtx->s.db->mutex) );
64715   sqlite3VdbeMemSetNull(&pCtx->s);
64716   pCtx->isError = SQLITE_NOMEM;
64717   pCtx->fErrorOrAux = 1;
64718   pCtx->s.db->mallocFailed = 1;
64719 }
64720 
64721 /*
64722 ** This function is called after a transaction has been committed. It 
64723 ** invokes callbacks registered with sqlite3_wal_hook() as required.
64724 */
64725 static int doWalCallbacks(sqlite3 *db){
64726   int rc = SQLITE_OK;
64727 #ifndef SQLITE_OMIT_WAL
64728   int i;
64729   for(i=0; i<db->nDb; i++){
64730     Btree *pBt = db->aDb[i].pBt;
64731     if( pBt ){
64732       int nEntry = sqlite3PagerWalCallback(sqlite3BtreePager(pBt));
64733       if( db->xWalCallback && nEntry>0 && rc==SQLITE_OK ){
64734         rc = db->xWalCallback(db->pWalArg, db, db->aDb[i].zName, nEntry);
64735       }
64736     }
64737   }
64738 #endif
64739   return rc;
64740 }
64741 
64742 /*
64743 ** Execute the statement pStmt, either until a row of data is ready, the
64744 ** statement is completely executed or an error occurs.
64745 **
64746 ** This routine implements the bulk of the logic behind the sqlite_step()
64747 ** API.  The only thing omitted is the automatic recompile if a 
64748 ** schema change has occurred.  That detail is handled by the
64749 ** outer sqlite3_step() wrapper procedure.
64750 */
64751 static int sqlite3Step(Vdbe *p){
64752   sqlite3 *db;
64753   int rc;
64754 
64755   assert(p);
64756   if( p->magic!=VDBE_MAGIC_RUN ){
64757     /* We used to require that sqlite3_reset() be called before retrying
64758     ** sqlite3_step() after any error or after SQLITE_DONE.  But beginning
64759     ** with version 3.7.0, we changed this so that sqlite3_reset() would
64760     ** be called automatically instead of throwing the SQLITE_MISUSE error.
64761     ** This "automatic-reset" change is not technically an incompatibility, 
64762     ** since any application that receives an SQLITE_MISUSE is broken by
64763     ** definition.
64764     **
64765     ** Nevertheless, some published applications that were originally written
64766     ** for version 3.6.23 or earlier do in fact depend on SQLITE_MISUSE 
64767     ** returns, and those were broken by the automatic-reset change.  As a
64768     ** a work-around, the SQLITE_OMIT_AUTORESET compile-time restores the
64769     ** legacy behavior of returning SQLITE_MISUSE for cases where the 
64770     ** previous sqlite3_step() returned something other than a SQLITE_LOCKED
64771     ** or SQLITE_BUSY error.
64772     */
64773 #ifdef SQLITE_OMIT_AUTORESET
64774     if( p->rc==SQLITE_BUSY || p->rc==SQLITE_LOCKED ){
64775       sqlite3_reset((sqlite3_stmt*)p);
64776     }else{
64777       return SQLITE_MISUSE_BKPT;
64778     }
64779 #else
64780     sqlite3_reset((sqlite3_stmt*)p);
64781 #endif
64782   }
64783 
64784   /* Check that malloc() has not failed. If it has, return early. */
64785   db = p->db;
64786   if( db->mallocFailed ){
64787     p->rc = SQLITE_NOMEM;
64788     return SQLITE_NOMEM;
64789   }
64790 
64791   if( p->pc<=0 && p->expired ){
64792     p->rc = SQLITE_SCHEMA;
64793     rc = SQLITE_ERROR;
64794     goto end_of_step;
64795   }
64796   if( p->pc<0 ){
64797     /* If there are no other statements currently running, then
64798     ** reset the interrupt flag.  This prevents a call to sqlite3_interrupt
64799     ** from interrupting a statement that has not yet started.
64800     */
64801     if( db->nVdbeActive==0 ){
64802       db->u1.isInterrupted = 0;
64803     }
64804 
64805     assert( db->nVdbeWrite>0 || db->autoCommit==0 
64806         || (db->nDeferredCons==0 && db->nDeferredImmCons==0)
64807     );
64808 
64809 #ifndef SQLITE_OMIT_TRACE
64810     if( db->xProfile && !db->init.busy ){
64811       sqlite3OsCurrentTimeInt64(db->pVfs, &p->startTime);
64812     }
64813 #endif
64814 
64815     db->nVdbeActive++;
64816     if( p->readOnly==0 ) db->nVdbeWrite++;
64817     if( p->bIsReader ) db->nVdbeRead++;
64818     p->pc = 0;
64819   }
64820 #ifndef SQLITE_OMIT_EXPLAIN
64821   if( p->explain ){
64822     rc = sqlite3VdbeList(p);
64823   }else
64824 #endif /* SQLITE_OMIT_EXPLAIN */
64825   {
64826     db->nVdbeExec++;
64827     rc = sqlite3VdbeExec(p);
64828     db->nVdbeExec--;
64829   }
64830 
64831 #ifndef SQLITE_OMIT_TRACE
64832   /* Invoke the profile callback if there is one
64833   */
64834   if( rc!=SQLITE_ROW && db->xProfile && !db->init.busy && p->zSql ){
64835     sqlite3_int64 iNow;
64836     sqlite3OsCurrentTimeInt64(db->pVfs, &iNow);
64837     db->xProfile(db->pProfileArg, p->zSql, (iNow - p->startTime)*1000000);
64838   }
64839 #endif
64840 
64841   if( rc==SQLITE_DONE ){
64842     assert( p->rc==SQLITE_OK );
64843     p->rc = doWalCallbacks(db);
64844     if( p->rc!=SQLITE_OK ){
64845       rc = SQLITE_ERROR;
64846     }
64847   }
64848 
64849   db->errCode = rc;
64850   if( SQLITE_NOMEM==sqlite3ApiExit(p->db, p->rc) ){
64851     p->rc = SQLITE_NOMEM;
64852   }
64853 end_of_step:
64854   /* At this point local variable rc holds the value that should be 
64855   ** returned if this statement was compiled using the legacy 
64856   ** sqlite3_prepare() interface. According to the docs, this can only
64857   ** be one of the values in the first assert() below. Variable p->rc 
64858   ** contains the value that would be returned if sqlite3_finalize() 
64859   ** were called on statement p.
64860   */
64861   assert( rc==SQLITE_ROW  || rc==SQLITE_DONE   || rc==SQLITE_ERROR 
64862        || rc==SQLITE_BUSY || rc==SQLITE_MISUSE
64863   );
64864   assert( p->rc!=SQLITE_ROW && p->rc!=SQLITE_DONE );
64865   if( p->isPrepareV2 && rc!=SQLITE_ROW && rc!=SQLITE_DONE ){
64866     /* If this statement was prepared using sqlite3_prepare_v2(), and an
64867     ** error has occurred, then return the error code in p->rc to the
64868     ** caller. Set the error code in the database handle to the same value.
64869     */ 
64870     rc = sqlite3VdbeTransferError(p);
64871   }
64872   return (rc&db->errMask);
64873 }
64874 
64875 /*
64876 ** This is the top-level implementation of sqlite3_step().  Call
64877 ** sqlite3Step() to do most of the work.  If a schema error occurs,
64878 ** call sqlite3Reprepare() and try again.
64879 */
64880 SQLITE_API int sqlite3_step(sqlite3_stmt *pStmt){
64881   int rc = SQLITE_OK;      /* Result from sqlite3Step() */
64882   int rc2 = SQLITE_OK;     /* Result from sqlite3Reprepare() */
64883   Vdbe *v = (Vdbe*)pStmt;  /* the prepared statement */
64884   int cnt = 0;             /* Counter to prevent infinite loop of reprepares */
64885   sqlite3 *db;             /* The database connection */
64886 
64887   if( vdbeSafetyNotNull(v) ){
64888     return SQLITE_MISUSE_BKPT;
64889   }
64890   db = v->db;
64891   sqlite3_mutex_enter(db->mutex);
64892   v->doingRerun = 0;
64893   while( (rc = sqlite3Step(v))==SQLITE_SCHEMA
64894          && cnt++ < SQLITE_MAX_SCHEMA_RETRY
64895          && (rc2 = rc = sqlite3Reprepare(v))==SQLITE_OK ){
64896     sqlite3_reset(pStmt);
64897     v->doingRerun = 1;
64898     assert( v->expired==0 );
64899   }
64900   if( rc2!=SQLITE_OK && ALWAYS(v->isPrepareV2) && ALWAYS(db->pErr) ){
64901     /* This case occurs after failing to recompile an sql statement. 
64902     ** The error message from the SQL compiler has already been loaded 
64903     ** into the database handle. This block copies the error message 
64904     ** from the database handle into the statement and sets the statement
64905     ** program counter to 0 to ensure that when the statement is 
64906     ** finalized or reset the parser error message is available via
64907     ** sqlite3_errmsg() and sqlite3_errcode().
64908     */
64909     const char *zErr = (const char *)sqlite3_value_text(db->pErr); 
64910     sqlite3DbFree(db, v->zErrMsg);
64911     if( !db->mallocFailed ){
64912       v->zErrMsg = sqlite3DbStrDup(db, zErr);
64913       v->rc = rc2;
64914     } else {
64915       v->zErrMsg = 0;
64916       v->rc = rc = SQLITE_NOMEM;
64917     }
64918   }
64919   rc = sqlite3ApiExit(db, rc);
64920   sqlite3_mutex_leave(db->mutex);
64921   return rc;
64922 }
64923 
64924 
64925 /*
64926 ** Extract the user data from a sqlite3_context structure and return a
64927 ** pointer to it.
64928 */
64929 SQLITE_API void *sqlite3_user_data(sqlite3_context *p){
64930   assert( p && p->pFunc );
64931   return p->pFunc->pUserData;
64932 }
64933 
64934 /*
64935 ** Extract the user data from a sqlite3_context structure and return a
64936 ** pointer to it.
64937 **
64938 ** IMPLEMENTATION-OF: R-46798-50301 The sqlite3_context_db_handle() interface
64939 ** returns a copy of the pointer to the database connection (the 1st
64940 ** parameter) of the sqlite3_create_function() and
64941 ** sqlite3_create_function16() routines that originally registered the
64942 ** application defined function.
64943 */
64944 SQLITE_API sqlite3 *sqlite3_context_db_handle(sqlite3_context *p){
64945   assert( p && p->pFunc );
64946   return p->s.db;
64947 }
64948 
64949 /*
64950 ** Return the current time for a statement
64951 */
64952 SQLITE_PRIVATE sqlite3_int64 sqlite3StmtCurrentTime(sqlite3_context *p){
64953   Vdbe *v = p->pVdbe;
64954   int rc;
64955   if( v->iCurrentTime==0 ){
64956     rc = sqlite3OsCurrentTimeInt64(p->s.db->pVfs, &v->iCurrentTime);
64957     if( rc ) v->iCurrentTime = 0;
64958   }
64959   return v->iCurrentTime;
64960 }
64961 
64962 /*
64963 ** The following is the implementation of an SQL function that always
64964 ** fails with an error message stating that the function is used in the
64965 ** wrong context.  The sqlite3_overload_function() API might construct
64966 ** SQL function that use this routine so that the functions will exist
64967 ** for name resolution but are actually overloaded by the xFindFunction
64968 ** method of virtual tables.
64969 */
64970 SQLITE_PRIVATE void sqlite3InvalidFunction(
64971   sqlite3_context *context,  /* The function calling context */
64972   int NotUsed,               /* Number of arguments to the function */
64973   sqlite3_value **NotUsed2   /* Value of each argument */
64974 ){
64975   const char *zName = context->pFunc->zName;
64976   char *zErr;
64977   UNUSED_PARAMETER2(NotUsed, NotUsed2);
64978   zErr = sqlite3_mprintf(
64979       "unable to use function %s in the requested context", zName);
64980   sqlite3_result_error(context, zErr, -1);
64981   sqlite3_free(zErr);
64982 }
64983 
64984 /*
64985 ** Allocate or return the aggregate context for a user function.  A new
64986 ** context is allocated on the first call.  Subsequent calls return the
64987 ** same context that was returned on prior calls.
64988 */
64989 SQLITE_API void *sqlite3_aggregate_context(sqlite3_context *p, int nByte){
64990   Mem *pMem;
64991   assert( p && p->pFunc && p->pFunc->xStep );
64992   assert( sqlite3_mutex_held(p->s.db->mutex) );
64993   pMem = p->pMem;
64994   testcase( nByte<0 );
64995   if( (pMem->flags & MEM_Agg)==0 ){
64996     if( nByte<=0 ){
64997       sqlite3VdbeMemReleaseExternal(pMem);
64998       pMem->flags = MEM_Null;
64999       pMem->z = 0;
65000     }else{
65001       sqlite3VdbeMemGrow(pMem, nByte, 0);
65002       pMem->flags = MEM_Agg;
65003       pMem->u.pDef = p->pFunc;
65004       if( pMem->z ){
65005         memset(pMem->z, 0, nByte);
65006       }
65007     }
65008   }
65009   return (void*)pMem->z;
65010 }
65011 
65012 /*
65013 ** Return the auxilary data pointer, if any, for the iArg'th argument to
65014 ** the user-function defined by pCtx.
65015 */
65016 SQLITE_API void *sqlite3_get_auxdata(sqlite3_context *pCtx, int iArg){
65017   AuxData *pAuxData;
65018 
65019   assert( sqlite3_mutex_held(pCtx->s.db->mutex) );
65020   for(pAuxData=pCtx->pVdbe->pAuxData; pAuxData; pAuxData=pAuxData->pNext){
65021     if( pAuxData->iOp==pCtx->iOp && pAuxData->iArg==iArg ) break;
65022   }
65023 
65024   return (pAuxData ? pAuxData->pAux : 0);
65025 }
65026 
65027 /*
65028 ** Set the auxilary data pointer and delete function, for the iArg'th
65029 ** argument to the user-function defined by pCtx. Any previous value is
65030 ** deleted by calling the delete function specified when it was set.
65031 */
65032 SQLITE_API void sqlite3_set_auxdata(
65033   sqlite3_context *pCtx, 
65034   int iArg, 
65035   void *pAux, 
65036   void (*xDelete)(void*)
65037 ){
65038   AuxData *pAuxData;
65039   Vdbe *pVdbe = pCtx->pVdbe;
65040 
65041   assert( sqlite3_mutex_held(pCtx->s.db->mutex) );
65042   if( iArg<0 ) goto failed;
65043 
65044   for(pAuxData=pVdbe->pAuxData; pAuxData; pAuxData=pAuxData->pNext){
65045     if( pAuxData->iOp==pCtx->iOp && pAuxData->iArg==iArg ) break;
65046   }
65047   if( pAuxData==0 ){
65048     pAuxData = sqlite3DbMallocZero(pVdbe->db, sizeof(AuxData));
65049     if( !pAuxData ) goto failed;
65050     pAuxData->iOp = pCtx->iOp;
65051     pAuxData->iArg = iArg;
65052     pAuxData->pNext = pVdbe->pAuxData;
65053     pVdbe->pAuxData = pAuxData;
65054     if( pCtx->fErrorOrAux==0 ){
65055       pCtx->isError = 0;
65056       pCtx->fErrorOrAux = 1;
65057     }
65058   }else if( pAuxData->xDelete ){
65059     pAuxData->xDelete(pAuxData->pAux);
65060   }
65061 
65062   pAuxData->pAux = pAux;
65063   pAuxData->xDelete = xDelete;
65064   return;
65065 
65066 failed:
65067   if( xDelete ){
65068     xDelete(pAux);
65069   }
65070 }
65071 
65072 #ifndef SQLITE_OMIT_DEPRECATED
65073 /*
65074 ** Return the number of times the Step function of a aggregate has been 
65075 ** called.
65076 **
65077 ** This function is deprecated.  Do not use it for new code.  It is
65078 ** provide only to avoid breaking legacy code.  New aggregate function
65079 ** implementations should keep their own counts within their aggregate
65080 ** context.
65081 */
65082 SQLITE_API int sqlite3_aggregate_count(sqlite3_context *p){
65083   assert( p && p->pMem && p->pFunc && p->pFunc->xStep );
65084   return p->pMem->n;
65085 }
65086 #endif
65087 
65088 /*
65089 ** Return the number of columns in the result set for the statement pStmt.
65090 */
65091 SQLITE_API int sqlite3_column_count(sqlite3_stmt *pStmt){
65092   Vdbe *pVm = (Vdbe *)pStmt;
65093   return pVm ? pVm->nResColumn : 0;
65094 }
65095 
65096 /*
65097 ** Return the number of values available from the current row of the
65098 ** currently executing statement pStmt.
65099 */
65100 SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt){
65101   Vdbe *pVm = (Vdbe *)pStmt;
65102   if( pVm==0 || pVm->pResultSet==0 ) return 0;
65103   return pVm->nResColumn;
65104 }
65105 
65106 
65107 /*
65108 ** Check to see if column iCol of the given statement is valid.  If
65109 ** it is, return a pointer to the Mem for the value of that column.
65110 ** If iCol is not valid, return a pointer to a Mem which has a value
65111 ** of NULL.
65112 */
65113 static Mem *columnMem(sqlite3_stmt *pStmt, int i){
65114   Vdbe *pVm;
65115   Mem *pOut;
65116 
65117   pVm = (Vdbe *)pStmt;
65118   if( pVm && pVm->pResultSet!=0 && i<pVm->nResColumn && i>=0 ){
65119     sqlite3_mutex_enter(pVm->db->mutex);
65120     pOut = &pVm->pResultSet[i];
65121   }else{
65122     /* If the value passed as the second argument is out of range, return
65123     ** a pointer to the following static Mem object which contains the
65124     ** value SQL NULL. Even though the Mem structure contains an element
65125     ** of type i64, on certain architectures (x86) with certain compiler
65126     ** switches (-Os), gcc may align this Mem object on a 4-byte boundary
65127     ** instead of an 8-byte one. This all works fine, except that when
65128     ** running with SQLITE_DEBUG defined the SQLite code sometimes assert()s
65129     ** that a Mem structure is located on an 8-byte boundary. To prevent
65130     ** these assert()s from failing, when building with SQLITE_DEBUG defined
65131     ** using gcc, we force nullMem to be 8-byte aligned using the magical
65132     ** __attribute__((aligned(8))) macro.  */
65133     static const Mem nullMem 
65134 #if defined(SQLITE_DEBUG) && defined(__GNUC__)
65135       __attribute__((aligned(8))) 
65136 #endif
65137       = {0, "", (double)0, {0}, 0, MEM_Null, SQLITE_NULL, 0,
65138 #ifdef SQLITE_DEBUG
65139          0, 0,  /* pScopyFrom, pFiller */
65140 #endif
65141          0, 0 };
65142 
65143     if( pVm && ALWAYS(pVm->db) ){
65144       sqlite3_mutex_enter(pVm->db->mutex);
65145       sqlite3Error(pVm->db, SQLITE_RANGE, 0);
65146     }
65147     pOut = (Mem*)&nullMem;
65148   }
65149   return pOut;
65150 }
65151 
65152 /*
65153 ** This function is called after invoking an sqlite3_value_XXX function on a 
65154 ** column value (i.e. a value returned by evaluating an SQL expression in the
65155 ** select list of a SELECT statement) that may cause a malloc() failure. If 
65156 ** malloc() has failed, the threads mallocFailed flag is cleared and the result
65157 ** code of statement pStmt set to SQLITE_NOMEM.
65158 **
65159 ** Specifically, this is called from within:
65160 **
65161 **     sqlite3_column_int()
65162 **     sqlite3_column_int64()
65163 **     sqlite3_column_text()
65164 **     sqlite3_column_text16()
65165 **     sqlite3_column_real()
65166 **     sqlite3_column_bytes()
65167 **     sqlite3_column_bytes16()
65168 **     sqiite3_column_blob()
65169 */
65170 static void columnMallocFailure(sqlite3_stmt *pStmt)
65171 {
65172   /* If malloc() failed during an encoding conversion within an
65173   ** sqlite3_column_XXX API, then set the return code of the statement to
65174   ** SQLITE_NOMEM. The next call to _step() (if any) will return SQLITE_ERROR
65175   ** and _finalize() will return NOMEM.
65176   */
65177   Vdbe *p = (Vdbe *)pStmt;
65178   if( p ){
65179     p->rc = sqlite3ApiExit(p->db, p->rc);
65180     sqlite3_mutex_leave(p->db->mutex);
65181   }
65182 }
65183 
65184 /**************************** sqlite3_column_  *******************************
65185 ** The following routines are used to access elements of the current row
65186 ** in the result set.
65187 */
65188 SQLITE_API const void *sqlite3_column_blob(sqlite3_stmt *pStmt, int i){
65189   const void *val;
65190   val = sqlite3_value_blob( columnMem(pStmt,i) );
65191   /* Even though there is no encoding conversion, value_blob() might
65192   ** need to call malloc() to expand the result of a zeroblob() 
65193   ** expression. 
65194   */
65195   columnMallocFailure(pStmt);
65196   return val;
65197 }
65198 SQLITE_API int sqlite3_column_bytes(sqlite3_stmt *pStmt, int i){
65199   int val = sqlite3_value_bytes( columnMem(pStmt,i) );
65200   columnMallocFailure(pStmt);
65201   return val;
65202 }
65203 SQLITE_API int sqlite3_column_bytes16(sqlite3_stmt *pStmt, int i){
65204   int val = sqlite3_value_bytes16( columnMem(pStmt,i) );
65205   columnMallocFailure(pStmt);
65206   return val;
65207 }
65208 SQLITE_API double sqlite3_column_double(sqlite3_stmt *pStmt, int i){
65209   double val = sqlite3_value_double( columnMem(pStmt,i) );
65210   columnMallocFailure(pStmt);
65211   return val;
65212 }
65213 SQLITE_API int sqlite3_column_int(sqlite3_stmt *pStmt, int i){
65214   int val = sqlite3_value_int( columnMem(pStmt,i) );
65215   columnMallocFailure(pStmt);
65216   return val;
65217 }
65218 SQLITE_API sqlite_int64 sqlite3_column_int64(sqlite3_stmt *pStmt, int i){
65219   sqlite_int64 val = sqlite3_value_int64( columnMem(pStmt,i) );
65220   columnMallocFailure(pStmt);
65221   return val;
65222 }
65223 SQLITE_API const unsigned char *sqlite3_column_text(sqlite3_stmt *pStmt, int i){
65224   const unsigned char *val = sqlite3_value_text( columnMem(pStmt,i) );
65225   columnMallocFailure(pStmt);
65226   return val;
65227 }
65228 SQLITE_API sqlite3_value *sqlite3_column_value(sqlite3_stmt *pStmt, int i){
65229   Mem *pOut = columnMem(pStmt, i);
65230   if( pOut->flags&MEM_Static ){
65231     pOut->flags &= ~MEM_Static;
65232     pOut->flags |= MEM_Ephem;
65233   }
65234   columnMallocFailure(pStmt);
65235   return (sqlite3_value *)pOut;
65236 }
65237 #ifndef SQLITE_OMIT_UTF16
65238 SQLITE_API const void *sqlite3_column_text16(sqlite3_stmt *pStmt, int i){
65239   const void *val = sqlite3_value_text16( columnMem(pStmt,i) );
65240   columnMallocFailure(pStmt);
65241   return val;
65242 }
65243 #endif /* SQLITE_OMIT_UTF16 */
65244 SQLITE_API int sqlite3_column_type(sqlite3_stmt *pStmt, int i){
65245   int iType = sqlite3_value_type( columnMem(pStmt,i) );
65246   columnMallocFailure(pStmt);
65247   return iType;
65248 }
65249 
65250 /*
65251 ** Convert the N-th element of pStmt->pColName[] into a string using
65252 ** xFunc() then return that string.  If N is out of range, return 0.
65253 **
65254 ** There are up to 5 names for each column.  useType determines which
65255 ** name is returned.  Here are the names:
65256 **
65257 **    0      The column name as it should be displayed for output
65258 **    1      The datatype name for the column
65259 **    2      The name of the database that the column derives from
65260 **    3      The name of the table that the column derives from
65261 **    4      The name of the table column that the result column derives from
65262 **
65263 ** If the result is not a simple column reference (if it is an expression
65264 ** or a constant) then useTypes 2, 3, and 4 return NULL.
65265 */
65266 static const void *columnName(
65267   sqlite3_stmt *pStmt,
65268   int N,
65269   const void *(*xFunc)(Mem*),
65270   int useType
65271 ){
65272   const void *ret = 0;
65273   Vdbe *p = (Vdbe *)pStmt;
65274   int n;
65275   sqlite3 *db = p->db;
65276   
65277   assert( db!=0 );
65278   n = sqlite3_column_count(pStmt);
65279   if( N<n && N>=0 ){
65280     N += useType*n;
65281     sqlite3_mutex_enter(db->mutex);
65282     assert( db->mallocFailed==0 );
65283     ret = xFunc(&p->aColName[N]);
65284      /* A malloc may have failed inside of the xFunc() call. If this
65285     ** is the case, clear the mallocFailed flag and return NULL.
65286     */
65287     if( db->mallocFailed ){
65288       db->mallocFailed = 0;
65289       ret = 0;
65290     }
65291     sqlite3_mutex_leave(db->mutex);
65292   }
65293   return ret;
65294 }
65295 
65296 /*
65297 ** Return the name of the Nth column of the result set returned by SQL
65298 ** statement pStmt.
65299 */
65300 SQLITE_API const char *sqlite3_column_name(sqlite3_stmt *pStmt, int N){
65301   return columnName(
65302       pStmt, N, (const void*(*)(Mem*))sqlite3_value_text, COLNAME_NAME);
65303 }
65304 #ifndef SQLITE_OMIT_UTF16
65305 SQLITE_API const void *sqlite3_column_name16(sqlite3_stmt *pStmt, int N){
65306   return columnName(
65307       pStmt, N, (const void*(*)(Mem*))sqlite3_value_text16, COLNAME_NAME);
65308 }
65309 #endif
65310 
65311 /*
65312 ** Constraint:  If you have ENABLE_COLUMN_METADATA then you must
65313 ** not define OMIT_DECLTYPE.
65314 */
65315 #if defined(SQLITE_OMIT_DECLTYPE) && defined(SQLITE_ENABLE_COLUMN_METADATA)
65316 # error "Must not define both SQLITE_OMIT_DECLTYPE \
65317          and SQLITE_ENABLE_COLUMN_METADATA"
65318 #endif
65319 
65320 #ifndef SQLITE_OMIT_DECLTYPE
65321 /*
65322 ** Return the column declaration type (if applicable) of the 'i'th column
65323 ** of the result set of SQL statement pStmt.
65324 */
65325 SQLITE_API const char *sqlite3_column_decltype(sqlite3_stmt *pStmt, int N){
65326   return columnName(
65327       pStmt, N, (const void*(*)(Mem*))sqlite3_value_text, COLNAME_DECLTYPE);
65328 }
65329 #ifndef SQLITE_OMIT_UTF16
65330 SQLITE_API const void *sqlite3_column_decltype16(sqlite3_stmt *pStmt, int N){
65331   return columnName(
65332       pStmt, N, (const void*(*)(Mem*))sqlite3_value_text16, COLNAME_DECLTYPE);
65333 }
65334 #endif /* SQLITE_OMIT_UTF16 */
65335 #endif /* SQLITE_OMIT_DECLTYPE */
65336 
65337 #ifdef SQLITE_ENABLE_COLUMN_METADATA
65338 /*
65339 ** Return the name of the database from which a result column derives.
65340 ** NULL is returned if the result column is an expression or constant or
65341 ** anything else which is not an unabiguous reference to a database column.
65342 */
65343 SQLITE_API const char *sqlite3_column_database_name(sqlite3_stmt *pStmt, int N){
65344   return columnName(
65345       pStmt, N, (const void*(*)(Mem*))sqlite3_value_text, COLNAME_DATABASE);
65346 }
65347 #ifndef SQLITE_OMIT_UTF16
65348 SQLITE_API const void *sqlite3_column_database_name16(sqlite3_stmt *pStmt, int N){
65349   return columnName(
65350       pStmt, N, (const void*(*)(Mem*))sqlite3_value_text16, COLNAME_DATABASE);
65351 }
65352 #endif /* SQLITE_OMIT_UTF16 */
65353 
65354 /*
65355 ** Return the name of the table from which a result column derives.
65356 ** NULL is returned if the result column is an expression or constant or
65357 ** anything else which is not an unabiguous reference to a database column.
65358 */
65359 SQLITE_API const char *sqlite3_column_table_name(sqlite3_stmt *pStmt, int N){
65360   return columnName(
65361       pStmt, N, (const void*(*)(Mem*))sqlite3_value_text, COLNAME_TABLE);
65362 }
65363 #ifndef SQLITE_OMIT_UTF16
65364 SQLITE_API const void *sqlite3_column_table_name16(sqlite3_stmt *pStmt, int N){
65365   return columnName(
65366       pStmt, N, (const void*(*)(Mem*))sqlite3_value_text16, COLNAME_TABLE);
65367 }
65368 #endif /* SQLITE_OMIT_UTF16 */
65369 
65370 /*
65371 ** Return the name of the table column from which a result column derives.
65372 ** NULL is returned if the result column is an expression or constant or
65373 ** anything else which is not an unabiguous reference to a database column.
65374 */
65375 SQLITE_API const char *sqlite3_column_origin_name(sqlite3_stmt *pStmt, int N){
65376   return columnName(
65377       pStmt, N, (const void*(*)(Mem*))sqlite3_value_text, COLNAME_COLUMN);
65378 }
65379 #ifndef SQLITE_OMIT_UTF16
65380 SQLITE_API const void *sqlite3_column_origin_name16(sqlite3_stmt *pStmt, int N){
65381   return columnName(
65382       pStmt, N, (const void*(*)(Mem*))sqlite3_value_text16, COLNAME_COLUMN);
65383 }
65384 #endif /* SQLITE_OMIT_UTF16 */
65385 #endif /* SQLITE_ENABLE_COLUMN_METADATA */
65386 
65387 
65388 /******************************* sqlite3_bind_  ***************************
65389 ** 
65390 ** Routines used to attach values to wildcards in a compiled SQL statement.
65391 */
65392 /*
65393 ** Unbind the value bound to variable i in virtual machine p. This is the 
65394 ** the same as binding a NULL value to the column. If the "i" parameter is
65395 ** out of range, then SQLITE_RANGE is returned. Othewise SQLITE_OK.
65396 **
65397 ** A successful evaluation of this routine acquires the mutex on p.
65398 ** the mutex is released if any kind of error occurs.
65399 **
65400 ** The error code stored in database p->db is overwritten with the return
65401 ** value in any case.
65402 */
65403 static int vdbeUnbind(Vdbe *p, int i){
65404   Mem *pVar;
65405   if( vdbeSafetyNotNull(p) ){
65406     return SQLITE_MISUSE_BKPT;
65407   }
65408   sqlite3_mutex_enter(p->db->mutex);
65409   if( p->magic!=VDBE_MAGIC_RUN || p->pc>=0 ){
65410     sqlite3Error(p->db, SQLITE_MISUSE, 0);
65411     sqlite3_mutex_leave(p->db->mutex);
65412     sqlite3_log(SQLITE_MISUSE, 
65413         "bind on a busy prepared statement: [%s]", p->zSql);
65414     return SQLITE_MISUSE_BKPT;
65415   }
65416   if( i<1 || i>p->nVar ){
65417     sqlite3Error(p->db, SQLITE_RANGE, 0);
65418     sqlite3_mutex_leave(p->db->mutex);
65419     return SQLITE_RANGE;
65420   }
65421   i--;
65422   pVar = &p->aVar[i];
65423   sqlite3VdbeMemRelease(pVar);
65424   pVar->flags = MEM_Null;
65425   sqlite3Error(p->db, SQLITE_OK, 0);
65426 
65427   /* If the bit corresponding to this variable in Vdbe.expmask is set, then 
65428   ** binding a new value to this variable invalidates the current query plan.
65429   **
65430   ** IMPLEMENTATION-OF: R-48440-37595 If the specific value bound to host
65431   ** parameter in the WHERE clause might influence the choice of query plan
65432   ** for a statement, then the statement will be automatically recompiled,
65433   ** as if there had been a schema change, on the first sqlite3_step() call
65434   ** following any change to the bindings of that parameter.
65435   */
65436   if( p->isPrepareV2 &&
65437      ((i<32 && p->expmask & ((u32)1 << i)) || p->expmask==0xffffffff)
65438   ){
65439     p->expired = 1;
65440   }
65441   return SQLITE_OK;
65442 }
65443 
65444 /*
65445 ** Bind a text or BLOB value.
65446 */
65447 static int bindText(
65448   sqlite3_stmt *pStmt,   /* The statement to bind against */
65449   int i,                 /* Index of the parameter to bind */
65450   const void *zData,     /* Pointer to the data to be bound */
65451   int nData,             /* Number of bytes of data to be bound */
65452   void (*xDel)(void*),   /* Destructor for the data */
65453   u8 encoding            /* Encoding for the data */
65454 ){
65455   Vdbe *p = (Vdbe *)pStmt;
65456   Mem *pVar;
65457   int rc;
65458 
65459   rc = vdbeUnbind(p, i);
65460   if( rc==SQLITE_OK ){
65461     if( zData!=0 ){
65462       pVar = &p->aVar[i-1];
65463       rc = sqlite3VdbeMemSetStr(pVar, zData, nData, encoding, xDel);
65464       if( rc==SQLITE_OK && encoding!=0 ){
65465         rc = sqlite3VdbeChangeEncoding(pVar, ENC(p->db));
65466       }
65467       sqlite3Error(p->db, rc, 0);
65468       rc = sqlite3ApiExit(p->db, rc);
65469     }
65470     sqlite3_mutex_leave(p->db->mutex);
65471   }else if( xDel!=SQLITE_STATIC && xDel!=SQLITE_TRANSIENT ){
65472     xDel((void*)zData);
65473   }
65474   return rc;
65475 }
65476 
65477 
65478 /*
65479 ** Bind a blob value to an SQL statement variable.
65480 */
65481 SQLITE_API int sqlite3_bind_blob(
65482   sqlite3_stmt *pStmt, 
65483   int i, 
65484   const void *zData, 
65485   int nData, 
65486   void (*xDel)(void*)
65487 ){
65488   return bindText(pStmt, i, zData, nData, xDel, 0);
65489 }
65490 SQLITE_API int sqlite3_bind_double(sqlite3_stmt *pStmt, int i, double rValue){
65491   int rc;
65492   Vdbe *p = (Vdbe *)pStmt;
65493   rc = vdbeUnbind(p, i);
65494   if( rc==SQLITE_OK ){
65495     sqlite3VdbeMemSetDouble(&p->aVar[i-1], rValue);
65496     sqlite3_mutex_leave(p->db->mutex);
65497   }
65498   return rc;
65499 }
65500 SQLITE_API int sqlite3_bind_int(sqlite3_stmt *p, int i, int iValue){
65501   return sqlite3_bind_int64(p, i, (i64)iValue);
65502 }
65503 SQLITE_API int sqlite3_bind_int64(sqlite3_stmt *pStmt, int i, sqlite_int64 iValue){
65504   int rc;
65505   Vdbe *p = (Vdbe *)pStmt;
65506   rc = vdbeUnbind(p, i);
65507   if( rc==SQLITE_OK ){
65508     sqlite3VdbeMemSetInt64(&p->aVar[i-1], iValue);
65509     sqlite3_mutex_leave(p->db->mutex);
65510   }
65511   return rc;
65512 }
65513 SQLITE_API int sqlite3_bind_null(sqlite3_stmt *pStmt, int i){
65514   int rc;
65515   Vdbe *p = (Vdbe*)pStmt;
65516   rc = vdbeUnbind(p, i);
65517   if( rc==SQLITE_OK ){
65518     sqlite3_mutex_leave(p->db->mutex);
65519   }
65520   return rc;
65521 }
65522 SQLITE_API int sqlite3_bind_text( 
65523   sqlite3_stmt *pStmt, 
65524   int i, 
65525   const char *zData, 
65526   int nData, 
65527   void (*xDel)(void*)
65528 ){
65529   return bindText(pStmt, i, zData, nData, xDel, SQLITE_UTF8);
65530 }
65531 #ifndef SQLITE_OMIT_UTF16
65532 SQLITE_API int sqlite3_bind_text16(
65533   sqlite3_stmt *pStmt, 
65534   int i, 
65535   const void *zData, 
65536   int nData, 
65537   void (*xDel)(void*)
65538 ){
65539   return bindText(pStmt, i, zData, nData, xDel, SQLITE_UTF16NATIVE);
65540 }
65541 #endif /* SQLITE_OMIT_UTF16 */
65542 SQLITE_API int sqlite3_bind_value(sqlite3_stmt *pStmt, int i, const sqlite3_value *pValue){
65543   int rc;
65544   switch( pValue->type ){
65545     case SQLITE_INTEGER: {
65546       rc = sqlite3_bind_int64(pStmt, i, pValue->u.i);
65547       break;
65548     }
65549     case SQLITE_FLOAT: {
65550       rc = sqlite3_bind_double(pStmt, i, pValue->r);
65551       break;
65552     }
65553     case SQLITE_BLOB: {
65554       if( pValue->flags & MEM_Zero ){
65555         rc = sqlite3_bind_zeroblob(pStmt, i, pValue->u.nZero);
65556       }else{
65557         rc = sqlite3_bind_blob(pStmt, i, pValue->z, pValue->n,SQLITE_TRANSIENT);
65558       }
65559       break;
65560     }
65561     case SQLITE_TEXT: {
65562       rc = bindText(pStmt,i,  pValue->z, pValue->n, SQLITE_TRANSIENT,
65563                               pValue->enc);
65564       break;
65565     }
65566     default: {
65567       rc = sqlite3_bind_null(pStmt, i);
65568       break;
65569     }
65570   }
65571   return rc;
65572 }
65573 SQLITE_API int sqlite3_bind_zeroblob(sqlite3_stmt *pStmt, int i, int n){
65574   int rc;
65575   Vdbe *p = (Vdbe *)pStmt;
65576   rc = vdbeUnbind(p, i);
65577   if( rc==SQLITE_OK ){
65578     sqlite3VdbeMemSetZeroBlob(&p->aVar[i-1], n);
65579     sqlite3_mutex_leave(p->db->mutex);
65580   }
65581   return rc;
65582 }
65583 
65584 /*
65585 ** Return the number of wildcards that can be potentially bound to.
65586 ** This routine is added to support DBD::SQLite.  
65587 */
65588 SQLITE_API int sqlite3_bind_parameter_count(sqlite3_stmt *pStmt){
65589   Vdbe *p = (Vdbe*)pStmt;
65590   return p ? p->nVar : 0;
65591 }
65592 
65593 /*
65594 ** Return the name of a wildcard parameter.  Return NULL if the index
65595 ** is out of range or if the wildcard is unnamed.
65596 **
65597 ** The result is always UTF-8.
65598 */
65599 SQLITE_API const char *sqlite3_bind_parameter_name(sqlite3_stmt *pStmt, int i){
65600   Vdbe *p = (Vdbe*)pStmt;
65601   if( p==0 || i<1 || i>p->nzVar ){
65602     return 0;
65603   }
65604   return p->azVar[i-1];
65605 }
65606 
65607 /*
65608 ** Given a wildcard parameter name, return the index of the variable
65609 ** with that name.  If there is no variable with the given name,
65610 ** return 0.
65611 */
65612 SQLITE_PRIVATE int sqlite3VdbeParameterIndex(Vdbe *p, const char *zName, int nName){
65613   int i;
65614   if( p==0 ){
65615     return 0;
65616   }
65617   if( zName ){
65618     for(i=0; i<p->nzVar; i++){
65619       const char *z = p->azVar[i];
65620       if( z && strncmp(z,zName,nName)==0 && z[nName]==0 ){
65621         return i+1;
65622       }
65623     }
65624   }
65625   return 0;
65626 }
65627 SQLITE_API int sqlite3_bind_parameter_index(sqlite3_stmt *pStmt, const char *zName){
65628   return sqlite3VdbeParameterIndex((Vdbe*)pStmt, zName, sqlite3Strlen30(zName));
65629 }
65630 
65631 /*
65632 ** Transfer all bindings from the first statement over to the second.
65633 */
65634 SQLITE_PRIVATE int sqlite3TransferBindings(sqlite3_stmt *pFromStmt, sqlite3_stmt *pToStmt){
65635   Vdbe *pFrom = (Vdbe*)pFromStmt;
65636   Vdbe *pTo = (Vdbe*)pToStmt;
65637   int i;
65638   assert( pTo->db==pFrom->db );
65639   assert( pTo->nVar==pFrom->nVar );
65640   sqlite3_mutex_enter(pTo->db->mutex);
65641   for(i=0; i<pFrom->nVar; i++){
65642     sqlite3VdbeMemMove(&pTo->aVar[i], &pFrom->aVar[i]);
65643   }
65644   sqlite3_mutex_leave(pTo->db->mutex);
65645   return SQLITE_OK;
65646 }
65647 
65648 #ifndef SQLITE_OMIT_DEPRECATED
65649 /*
65650 ** Deprecated external interface.  Internal/core SQLite code
65651 ** should call sqlite3TransferBindings.
65652 **
65653 ** Is is misuse to call this routine with statements from different
65654 ** database connections.  But as this is a deprecated interface, we
65655 ** will not bother to check for that condition.
65656 **
65657 ** If the two statements contain a different number of bindings, then
65658 ** an SQLITE_ERROR is returned.  Nothing else can go wrong, so otherwise
65659 ** SQLITE_OK is returned.
65660 */
65661 SQLITE_API int sqlite3_transfer_bindings(sqlite3_stmt *pFromStmt, sqlite3_stmt *pToStmt){
65662   Vdbe *pFrom = (Vdbe*)pFromStmt;
65663   Vdbe *pTo = (Vdbe*)pToStmt;
65664   if( pFrom->nVar!=pTo->nVar ){
65665     return SQLITE_ERROR;
65666   }
65667   if( pTo->isPrepareV2 && pTo->expmask ){
65668     pTo->expired = 1;
65669   }
65670   if( pFrom->isPrepareV2 && pFrom->expmask ){
65671     pFrom->expired = 1;
65672   }
65673   return sqlite3TransferBindings(pFromStmt, pToStmt);
65674 }
65675 #endif
65676 
65677 /*
65678 ** Return the sqlite3* database handle to which the prepared statement given
65679 ** in the argument belongs.  This is the same database handle that was
65680 ** the first argument to the sqlite3_prepare() that was used to create
65681 ** the statement in the first place.
65682 */
65683 SQLITE_API sqlite3 *sqlite3_db_handle(sqlite3_stmt *pStmt){
65684   return pStmt ? ((Vdbe*)pStmt)->db : 0;
65685 }
65686 
65687 /*
65688 ** Return true if the prepared statement is guaranteed to not modify the
65689 ** database.
65690 */
65691 SQLITE_API int sqlite3_stmt_readonly(sqlite3_stmt *pStmt){
65692   return pStmt ? ((Vdbe*)pStmt)->readOnly : 1;
65693 }
65694 
65695 /*
65696 ** Return true if the prepared statement is in need of being reset.
65697 */
65698 SQLITE_API int sqlite3_stmt_busy(sqlite3_stmt *pStmt){
65699   Vdbe *v = (Vdbe*)pStmt;
65700   return v!=0 && v->pc>0 && v->magic==VDBE_MAGIC_RUN;
65701 }
65702 
65703 /*
65704 ** Return a pointer to the next prepared statement after pStmt associated
65705 ** with database connection pDb.  If pStmt is NULL, return the first
65706 ** prepared statement for the database connection.  Return NULL if there
65707 ** are no more.
65708 */
65709 SQLITE_API sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt){
65710   sqlite3_stmt *pNext;
65711   sqlite3_mutex_enter(pDb->mutex);
65712   if( pStmt==0 ){
65713     pNext = (sqlite3_stmt*)pDb->pVdbe;
65714   }else{
65715     pNext = (sqlite3_stmt*)((Vdbe*)pStmt)->pNext;
65716   }
65717   sqlite3_mutex_leave(pDb->mutex);
65718   return pNext;
65719 }
65720 
65721 /*
65722 ** Return the value of a status counter for a prepared statement
65723 */
65724 SQLITE_API int sqlite3_stmt_status(sqlite3_stmt *pStmt, int op, int resetFlag){
65725   Vdbe *pVdbe = (Vdbe*)pStmt;
65726   u32 v = pVdbe->aCounter[op];
65727   if( resetFlag ) pVdbe->aCounter[op] = 0;
65728   return (int)v;
65729 }
65730 
65731 /************** End of vdbeapi.c *********************************************/
65732 /************** Begin file vdbetrace.c ***************************************/
65733 /*
65734 ** 2009 November 25
65735 **
65736 ** The author disclaims copyright to this source code.  In place of
65737 ** a legal notice, here is a blessing:
65738 **
65739 **    May you do good and not evil.
65740 **    May you find forgiveness for yourself and forgive others.
65741 **    May you share freely, never taking more than you give.
65742 **
65743 *************************************************************************
65744 **
65745 ** This file contains code used to insert the values of host parameters
65746 ** (aka "wildcards") into the SQL text output by sqlite3_trace().
65747 **
65748 ** The Vdbe parse-tree explainer is also found here.
65749 */
65750 
65751 #ifndef SQLITE_OMIT_TRACE
65752 
65753 /*
65754 ** zSql is a zero-terminated string of UTF-8 SQL text.  Return the number of
65755 ** bytes in this text up to but excluding the first character in
65756 ** a host parameter.  If the text contains no host parameters, return
65757 ** the total number of bytes in the text.
65758 */
65759 static int findNextHostParameter(const char *zSql, int *pnToken){
65760   int tokenType;
65761   int nTotal = 0;
65762   int n;
65763 
65764   *pnToken = 0;
65765   while( zSql[0] ){
65766     n = sqlite3GetToken((u8*)zSql, &tokenType);
65767     assert( n>0 && tokenType!=TK_ILLEGAL );
65768     if( tokenType==TK_VARIABLE ){
65769       *pnToken = n;
65770       break;
65771     }
65772     nTotal += n;
65773     zSql += n;
65774   }
65775   return nTotal;
65776 }
65777 
65778 /*
65779 ** This function returns a pointer to a nul-terminated string in memory
65780 ** obtained from sqlite3DbMalloc(). If sqlite3.nVdbeExec is 1, then the
65781 ** string contains a copy of zRawSql but with host parameters expanded to 
65782 ** their current bindings. Or, if sqlite3.nVdbeExec is greater than 1, 
65783 ** then the returned string holds a copy of zRawSql with "-- " prepended
65784 ** to each line of text.
65785 **
65786 ** If the SQLITE_TRACE_SIZE_LIMIT macro is defined to an integer, then
65787 ** then long strings and blobs are truncated to that many bytes.  This
65788 ** can be used to prevent unreasonably large trace strings when dealing
65789 ** with large (multi-megabyte) strings and blobs.
65790 **
65791 ** The calling function is responsible for making sure the memory returned
65792 ** is eventually freed.
65793 **
65794 ** ALGORITHM:  Scan the input string looking for host parameters in any of
65795 ** these forms:  ?, ?N, $A, @A, :A.  Take care to avoid text within
65796 ** string literals, quoted identifier names, and comments.  For text forms,
65797 ** the host parameter index is found by scanning the perpared
65798 ** statement for the corresponding OP_Variable opcode.  Once the host
65799 ** parameter index is known, locate the value in p->aVar[].  Then render
65800 ** the value as a literal in place of the host parameter name.
65801 */
65802 SQLITE_PRIVATE char *sqlite3VdbeExpandSql(
65803   Vdbe *p,                 /* The prepared statement being evaluated */
65804   const char *zRawSql      /* Raw text of the SQL statement */
65805 ){
65806   sqlite3 *db;             /* The database connection */
65807   int idx = 0;             /* Index of a host parameter */
65808   int nextIndex = 1;       /* Index of next ? host parameter */
65809   int n;                   /* Length of a token prefix */
65810   int nToken;              /* Length of the parameter token */
65811   int i;                   /* Loop counter */
65812   Mem *pVar;               /* Value of a host parameter */
65813   StrAccum out;            /* Accumulate the output here */
65814   char zBase[100];         /* Initial working space */
65815 
65816   db = p->db;
65817   sqlite3StrAccumInit(&out, zBase, sizeof(zBase), 
65818                       db->aLimit[SQLITE_LIMIT_LENGTH]);
65819   out.db = db;
65820   if( db->nVdbeExec>1 ){
65821     while( *zRawSql ){
65822       const char *zStart = zRawSql;
65823       while( *(zRawSql++)!='\n' && *zRawSql );
65824       sqlite3StrAccumAppend(&out, "-- ", 3);
65825       sqlite3StrAccumAppend(&out, zStart, (int)(zRawSql-zStart));
65826     }
65827   }else{
65828     while( zRawSql[0] ){
65829       n = findNextHostParameter(zRawSql, &nToken);
65830       assert( n>0 );
65831       sqlite3StrAccumAppend(&out, zRawSql, n);
65832       zRawSql += n;
65833       assert( zRawSql[0] || nToken==0 );
65834       if( nToken==0 ) break;
65835       if( zRawSql[0]=='?' ){
65836         if( nToken>1 ){
65837           assert( sqlite3Isdigit(zRawSql[1]) );
65838           sqlite3GetInt32(&zRawSql[1], &idx);
65839         }else{
65840           idx = nextIndex;
65841         }
65842       }else{
65843         assert( zRawSql[0]==':' || zRawSql[0]=='$' || zRawSql[0]=='@' );
65844         testcase( zRawSql[0]==':' );
65845         testcase( zRawSql[0]=='$' );
65846         testcase( zRawSql[0]=='@' );
65847         idx = sqlite3VdbeParameterIndex(p, zRawSql, nToken);
65848         assert( idx>0 );
65849       }
65850       zRawSql += nToken;
65851       nextIndex = idx + 1;
65852       assert( idx>0 && idx<=p->nVar );
65853       pVar = &p->aVar[idx-1];
65854       if( pVar->flags & MEM_Null ){
65855         sqlite3StrAccumAppend(&out, "NULL", 4);
65856       }else if( pVar->flags & MEM_Int ){
65857         sqlite3XPrintf(&out, "%lld", pVar->u.i);
65858       }else if( pVar->flags & MEM_Real ){
65859         sqlite3XPrintf(&out, "%!.15g", pVar->r);
65860       }else if( pVar->flags & MEM_Str ){
65861         int nOut;  /* Number of bytes of the string text to include in output */
65862 #ifndef SQLITE_OMIT_UTF16
65863         u8 enc = ENC(db);
65864         Mem utf8;
65865         if( enc!=SQLITE_UTF8 ){
65866           memset(&utf8, 0, sizeof(utf8));
65867           utf8.db = db;
65868           sqlite3VdbeMemSetStr(&utf8, pVar->z, pVar->n, enc, SQLITE_STATIC);
65869           sqlite3VdbeChangeEncoding(&utf8, SQLITE_UTF8);
65870           pVar = &utf8;
65871         }
65872 #endif
65873         nOut = pVar->n;
65874 #ifdef SQLITE_TRACE_SIZE_LIMIT
65875         if( nOut>SQLITE_TRACE_SIZE_LIMIT ){
65876           nOut = SQLITE_TRACE_SIZE_LIMIT;
65877           while( nOut<pVar->n && (pVar->z[nOut]&0xc0)==0x80 ){ nOut++; }
65878         }
65879 #endif    
65880         sqlite3XPrintf(&out, "'%.*q'", nOut, pVar->z);
65881 #ifdef SQLITE_TRACE_SIZE_LIMIT
65882         if( nOut<pVar->n ) sqlite3XPrintf(&out, "/*+%d bytes*/", pVar->n-nOut);
65883 #endif
65884 #ifndef SQLITE_OMIT_UTF16
65885         if( enc!=SQLITE_UTF8 ) sqlite3VdbeMemRelease(&utf8);
65886 #endif
65887       }else if( pVar->flags & MEM_Zero ){
65888         sqlite3XPrintf(&out, "zeroblob(%d)", pVar->u.nZero);
65889       }else{
65890         int nOut;  /* Number of bytes of the blob to include in output */
65891         assert( pVar->flags & MEM_Blob );
65892         sqlite3StrAccumAppend(&out, "x'", 2);
65893         nOut = pVar->n;
65894 #ifdef SQLITE_TRACE_SIZE_LIMIT
65895         if( nOut>SQLITE_TRACE_SIZE_LIMIT ) nOut = SQLITE_TRACE_SIZE_LIMIT;
65896 #endif
65897         for(i=0; i<nOut; i++){
65898           sqlite3XPrintf(&out, "%02x", pVar->z[i]&0xff);
65899         }
65900         sqlite3StrAccumAppend(&out, "'", 1);
65901 #ifdef SQLITE_TRACE_SIZE_LIMIT
65902         if( nOut<pVar->n ) sqlite3XPrintf(&out, "/*+%d bytes*/", pVar->n-nOut);
65903 #endif
65904       }
65905     }
65906   }
65907   return sqlite3StrAccumFinish(&out);
65908 }
65909 
65910 #endif /* #ifndef SQLITE_OMIT_TRACE */
65911 
65912 /*****************************************************************************
65913 ** The following code implements the data-structure explaining logic
65914 ** for the Vdbe.
65915 */
65916 
65917 #if defined(SQLITE_ENABLE_TREE_EXPLAIN)
65918 
65919 /*
65920 ** Allocate a new Explain object
65921 */
65922 SQLITE_PRIVATE void sqlite3ExplainBegin(Vdbe *pVdbe){
65923   if( pVdbe ){
65924     Explain *p;
65925     sqlite3BeginBenignMalloc();
65926     p = (Explain *)sqlite3MallocZero( sizeof(Explain) );
65927     if( p ){
65928       p->pVdbe = pVdbe;
65929       sqlite3_free(pVdbe->pExplain);
65930       pVdbe->pExplain = p;
65931       sqlite3StrAccumInit(&p->str, p->zBase, sizeof(p->zBase),
65932                           SQLITE_MAX_LENGTH);
65933       p->str.useMalloc = 2;
65934     }else{
65935       sqlite3EndBenignMalloc();
65936     }
65937   }
65938 }
65939 
65940 /*
65941 ** Return true if the Explain ends with a new-line.
65942 */
65943 static int endsWithNL(Explain *p){
65944   return p && p->str.zText && p->str.nChar
65945            && p->str.zText[p->str.nChar-1]=='\n';
65946 }
65947     
65948 /*
65949 ** Append text to the indentation
65950 */
65951 SQLITE_PRIVATE void sqlite3ExplainPrintf(Vdbe *pVdbe, const char *zFormat, ...){
65952   Explain *p;
65953   if( pVdbe && (p = pVdbe->pExplain)!=0 ){
65954     va_list ap;
65955     if( p->nIndent && endsWithNL(p) ){
65956       int n = p->nIndent;
65957       if( n>ArraySize(p->aIndent) ) n = ArraySize(p->aIndent);
65958       sqlite3AppendSpace(&p->str, p->aIndent[n-1]);
65959     }   
65960     va_start(ap, zFormat);
65961     sqlite3VXPrintf(&p->str, 1, zFormat, ap);
65962     va_end(ap);
65963   }
65964 }
65965 
65966 /*
65967 ** Append a '\n' if there is not already one.
65968 */
65969 SQLITE_PRIVATE void sqlite3ExplainNL(Vdbe *pVdbe){
65970   Explain *p;
65971   if( pVdbe && (p = pVdbe->pExplain)!=0 && !endsWithNL(p) ){
65972     sqlite3StrAccumAppend(&p->str, "\n", 1);
65973   }
65974 }
65975 
65976 /*
65977 ** Push a new indentation level.  Subsequent lines will be indented
65978 ** so that they begin at the current cursor position.
65979 */
65980 SQLITE_PRIVATE void sqlite3ExplainPush(Vdbe *pVdbe){
65981   Explain *p;
65982   if( pVdbe && (p = pVdbe->pExplain)!=0 ){
65983     if( p->str.zText && p->nIndent<ArraySize(p->aIndent) ){
65984       const char *z = p->str.zText;
65985       int i = p->str.nChar-1;
65986       int x;
65987       while( i>=0 && z[i]!='\n' ){ i--; }
65988       x = (p->str.nChar - 1) - i;
65989       if( p->nIndent && x<p->aIndent[p->nIndent-1] ){
65990         x = p->aIndent[p->nIndent-1];
65991       }
65992       p->aIndent[p->nIndent] = x;
65993     }
65994     p->nIndent++;
65995   }
65996 }
65997 
65998 /*
65999 ** Pop the indentation stack by one level.
66000 */
66001 SQLITE_PRIVATE void sqlite3ExplainPop(Vdbe *p){
66002   if( p && p->pExplain ) p->pExplain->nIndent--;
66003 }
66004 
66005 /*
66006 ** Free the indentation structure
66007 */
66008 SQLITE_PRIVATE void sqlite3ExplainFinish(Vdbe *pVdbe){
66009   if( pVdbe && pVdbe->pExplain ){
66010     sqlite3_free(pVdbe->zExplain);
66011     sqlite3ExplainNL(pVdbe);
66012     pVdbe->zExplain = sqlite3StrAccumFinish(&pVdbe->pExplain->str);
66013     sqlite3_free(pVdbe->pExplain);
66014     pVdbe->pExplain = 0;
66015     sqlite3EndBenignMalloc();
66016   }
66017 }
66018 
66019 /*
66020 ** Return the explanation of a virtual machine.
66021 */
66022 SQLITE_PRIVATE const char *sqlite3VdbeExplanation(Vdbe *pVdbe){
66023   return (pVdbe && pVdbe->zExplain) ? pVdbe->zExplain : 0;
66024 }
66025 #endif /* defined(SQLITE_DEBUG) */
66026 
66027 /************** End of vdbetrace.c *******************************************/
66028 /************** Begin file vdbe.c ********************************************/
66029 /*
66030 ** 2001 September 15
66031 **
66032 ** The author disclaims copyright to this source code.  In place of
66033 ** a legal notice, here is a blessing:
66034 **
66035 **    May you do good and not evil.
66036 **    May you find forgiveness for yourself and forgive others.
66037 **    May you share freely, never taking more than you give.
66038 **
66039 *************************************************************************
66040 ** The code in this file implements execution method of the 
66041 ** Virtual Database Engine (VDBE).  A separate file ("vdbeaux.c")
66042 ** handles housekeeping details such as creating and deleting
66043 ** VDBE instances.  This file is solely interested in executing
66044 ** the VDBE program.
66045 **
66046 ** In the external interface, an "sqlite3_stmt*" is an opaque pointer
66047 ** to a VDBE.
66048 **
66049 ** The SQL parser generates a program which is then executed by
66050 ** the VDBE to do the work of the SQL statement.  VDBE programs are 
66051 ** similar in form to assembly language.  The program consists of
66052 ** a linear sequence of operations.  Each operation has an opcode 
66053 ** and 5 operands.  Operands P1, P2, and P3 are integers.  Operand P4 
66054 ** is a null-terminated string.  Operand P5 is an unsigned character.
66055 ** Few opcodes use all 5 operands.
66056 **
66057 ** Computation results are stored on a set of registers numbered beginning
66058 ** with 1 and going up to Vdbe.nMem.  Each register can store
66059 ** either an integer, a null-terminated string, a floating point
66060 ** number, or the SQL "NULL" value.  An implicit conversion from one
66061 ** type to the other occurs as necessary.
66062 ** 
66063 ** Most of the code in this file is taken up by the sqlite3VdbeExec()
66064 ** function which does the work of interpreting a VDBE program.
66065 ** But other routines are also provided to help in building up
66066 ** a program instruction by instruction.
66067 **
66068 ** Various scripts scan this source file in order to generate HTML
66069 ** documentation, headers files, or other derived files.  The formatting
66070 ** of the code in this file is, therefore, important.  See other comments
66071 ** in this file for details.  If in doubt, do not deviate from existing
66072 ** commenting and indentation practices when changing or adding code.
66073 */
66074 
66075 /*
66076 ** Invoke this macro on memory cells just prior to changing the
66077 ** value of the cell.  This macro verifies that shallow copies are
66078 ** not misused.
66079 */
66080 #ifdef SQLITE_DEBUG
66081 # define memAboutToChange(P,M) sqlite3VdbeMemAboutToChange(P,M)
66082 #else
66083 # define memAboutToChange(P,M)
66084 #endif
66085 
66086 /*
66087 ** The following global variable is incremented every time a cursor
66088 ** moves, either by the OP_SeekXX, OP_Next, or OP_Prev opcodes.  The test
66089 ** procedures use this information to make sure that indices are
66090 ** working correctly.  This variable has no function other than to
66091 ** help verify the correct operation of the library.
66092 */
66093 #ifdef SQLITE_TEST
66094 SQLITE_API int sqlite3_search_count = 0;
66095 #endif
66096 
66097 /*
66098 ** When this global variable is positive, it gets decremented once before
66099 ** each instruction in the VDBE.  When it reaches zero, the u1.isInterrupted
66100 ** field of the sqlite3 structure is set in order to simulate an interrupt.
66101 **
66102 ** This facility is used for testing purposes only.  It does not function
66103 ** in an ordinary build.
66104 */
66105 #ifdef SQLITE_TEST
66106 SQLITE_API int sqlite3_interrupt_count = 0;
66107 #endif
66108 
66109 /*
66110 ** The next global variable is incremented each type the OP_Sort opcode
66111 ** is executed.  The test procedures use this information to make sure that
66112 ** sorting is occurring or not occurring at appropriate times.   This variable
66113 ** has no function other than to help verify the correct operation of the
66114 ** library.
66115 */
66116 #ifdef SQLITE_TEST
66117 SQLITE_API int sqlite3_sort_count = 0;
66118 #endif
66119 
66120 /*
66121 ** The next global variable records the size of the largest MEM_Blob
66122 ** or MEM_Str that has been used by a VDBE opcode.  The test procedures
66123 ** use this information to make sure that the zero-blob functionality
66124 ** is working correctly.   This variable has no function other than to
66125 ** help verify the correct operation of the library.
66126 */
66127 #ifdef SQLITE_TEST
66128 SQLITE_API int sqlite3_max_blobsize = 0;
66129 static void updateMaxBlobsize(Mem *p){
66130   if( (p->flags & (MEM_Str|MEM_Blob))!=0 && p->n>sqlite3_max_blobsize ){
66131     sqlite3_max_blobsize = p->n;
66132   }
66133 }
66134 #endif
66135 
66136 /*
66137 ** The next global variable is incremented each type the OP_Found opcode
66138 ** is executed. This is used to test whether or not the foreign key
66139 ** operation implemented using OP_FkIsZero is working. This variable
66140 ** has no function other than to help verify the correct operation of the
66141 ** library.
66142 */
66143 #ifdef SQLITE_TEST
66144 SQLITE_API int sqlite3_found_count = 0;
66145 #endif
66146 
66147 /*
66148 ** Test a register to see if it exceeds the current maximum blob size.
66149 ** If it does, record the new maximum blob size.
66150 */
66151 #if defined(SQLITE_TEST) && !defined(SQLITE_OMIT_BUILTIN_TEST)
66152 # define UPDATE_MAX_BLOBSIZE(P)  updateMaxBlobsize(P)
66153 #else
66154 # define UPDATE_MAX_BLOBSIZE(P)
66155 #endif
66156 
66157 /*
66158 ** Convert the given register into a string if it isn't one
66159 ** already. Return non-zero if a malloc() fails.
66160 */
66161 #define Stringify(P, enc) \
66162    if(((P)->flags&(MEM_Str|MEM_Blob))==0 && sqlite3VdbeMemStringify(P,enc)) \
66163      { goto no_mem; }
66164 
66165 /*
66166 ** An ephemeral string value (signified by the MEM_Ephem flag) contains
66167 ** a pointer to a dynamically allocated string where some other entity
66168 ** is responsible for deallocating that string.  Because the register
66169 ** does not control the string, it might be deleted without the register
66170 ** knowing it.
66171 **
66172 ** This routine converts an ephemeral string into a dynamically allocated
66173 ** string that the register itself controls.  In other words, it
66174 ** converts an MEM_Ephem string into an MEM_Dyn string.
66175 */
66176 #define Deephemeralize(P) \
66177    if( ((P)->flags&MEM_Ephem)!=0 \
66178        && sqlite3VdbeMemMakeWriteable(P) ){ goto no_mem;}
66179 
66180 /* Return true if the cursor was opened using the OP_OpenSorter opcode. */
66181 # define isSorter(x) ((x)->pSorter!=0)
66182 
66183 /*
66184 ** Argument pMem points at a register that will be passed to a
66185 ** user-defined function or returned to the user as the result of a query.
66186 ** This routine sets the pMem->type variable used by the sqlite3_value_*() 
66187 ** routines.
66188 */
66189 SQLITE_PRIVATE void sqlite3VdbeMemStoreType(Mem *pMem){
66190   int flags = pMem->flags;
66191   if( flags & MEM_Null ){
66192     pMem->type = SQLITE_NULL;
66193   }
66194   else if( flags & MEM_Int ){
66195     pMem->type = SQLITE_INTEGER;
66196   }
66197   else if( flags & MEM_Real ){
66198     pMem->type = SQLITE_FLOAT;
66199   }
66200   else if( flags & MEM_Str ){
66201     pMem->type = SQLITE_TEXT;
66202   }else{
66203     pMem->type = SQLITE_BLOB;
66204   }
66205 }
66206 
66207 /*
66208 ** Allocate VdbeCursor number iCur.  Return a pointer to it.  Return NULL
66209 ** if we run out of memory.
66210 */
66211 static VdbeCursor *allocateCursor(
66212   Vdbe *p,              /* The virtual machine */
66213   int iCur,             /* Index of the new VdbeCursor */
66214   int nField,           /* Number of fields in the table or index */
66215   int iDb,              /* Database the cursor belongs to, or -1 */
66216   int isBtreeCursor     /* True for B-Tree.  False for pseudo-table or vtab */
66217 ){
66218   /* Find the memory cell that will be used to store the blob of memory
66219   ** required for this VdbeCursor structure. It is convenient to use a 
66220   ** vdbe memory cell to manage the memory allocation required for a
66221   ** VdbeCursor structure for the following reasons:
66222   **
66223   **   * Sometimes cursor numbers are used for a couple of different
66224   **     purposes in a vdbe program. The different uses might require
66225   **     different sized allocations. Memory cells provide growable
66226   **     allocations.
66227   **
66228   **   * When using ENABLE_MEMORY_MANAGEMENT, memory cell buffers can
66229   **     be freed lazily via the sqlite3_release_memory() API. This
66230   **     minimizes the number of malloc calls made by the system.
66231   **
66232   ** Memory cells for cursors are allocated at the top of the address
66233   ** space. Memory cell (p->nMem) corresponds to cursor 0. Space for
66234   ** cursor 1 is managed by memory cell (p->nMem-1), etc.
66235   */
66236   Mem *pMem = &p->aMem[p->nMem-iCur];
66237 
66238   int nByte;
66239   VdbeCursor *pCx = 0;
66240   nByte = 
66241       ROUND8(sizeof(VdbeCursor)) + 2*sizeof(u32)*nField + 
66242       (isBtreeCursor?sqlite3BtreeCursorSize():0);
66243 
66244   assert( iCur<p->nCursor );
66245   if( p->apCsr[iCur] ){
66246     sqlite3VdbeFreeCursor(p, p->apCsr[iCur]);
66247     p->apCsr[iCur] = 0;
66248   }
66249   if( SQLITE_OK==sqlite3VdbeMemGrow(pMem, nByte, 0) ){
66250     p->apCsr[iCur] = pCx = (VdbeCursor*)pMem->z;
66251     memset(pCx, 0, sizeof(VdbeCursor));
66252     pCx->iDb = iDb;
66253     pCx->nField = nField;
66254     if( isBtreeCursor ){
66255       pCx->pCursor = (BtCursor*)
66256           &pMem->z[ROUND8(sizeof(VdbeCursor))+2*sizeof(u32)*nField];
66257       sqlite3BtreeCursorZero(pCx->pCursor);
66258     }
66259   }
66260   return pCx;
66261 }
66262 
66263 /*
66264 ** Try to convert a value into a numeric representation if we can
66265 ** do so without loss of information.  In other words, if the string
66266 ** looks like a number, convert it into a number.  If it does not
66267 ** look like a number, leave it alone.
66268 */
66269 static void applyNumericAffinity(Mem *pRec){
66270   if( (pRec->flags & (MEM_Real|MEM_Int))==0 ){
66271     double rValue;
66272     i64 iValue;
66273     u8 enc = pRec->enc;
66274     if( (pRec->flags&MEM_Str)==0 ) return;
66275     if( sqlite3AtoF(pRec->z, &rValue, pRec->n, enc)==0 ) return;
66276     if( 0==sqlite3Atoi64(pRec->z, &iValue, pRec->n, enc) ){
66277       pRec->u.i = iValue;
66278       pRec->flags |= MEM_Int;
66279     }else{
66280       pRec->r = rValue;
66281       pRec->flags |= MEM_Real;
66282     }
66283   }
66284 }
66285 
66286 /*
66287 ** Processing is determine by the affinity parameter:
66288 **
66289 ** SQLITE_AFF_INTEGER:
66290 ** SQLITE_AFF_REAL:
66291 ** SQLITE_AFF_NUMERIC:
66292 **    Try to convert pRec to an integer representation or a 
66293 **    floating-point representation if an integer representation
66294 **    is not possible.  Note that the integer representation is
66295 **    always preferred, even if the affinity is REAL, because
66296 **    an integer representation is more space efficient on disk.
66297 **
66298 ** SQLITE_AFF_TEXT:
66299 **    Convert pRec to a text representation.
66300 **
66301 ** SQLITE_AFF_NONE:
66302 **    No-op.  pRec is unchanged.
66303 */
66304 static void applyAffinity(
66305   Mem *pRec,          /* The value to apply affinity to */
66306   char affinity,      /* The affinity to be applied */
66307   u8 enc              /* Use this text encoding */
66308 ){
66309   if( affinity==SQLITE_AFF_TEXT ){
66310     /* Only attempt the conversion to TEXT if there is an integer or real
66311     ** representation (blob and NULL do not get converted) but no string
66312     ** representation.
66313     */
66314     if( 0==(pRec->flags&MEM_Str) && (pRec->flags&(MEM_Real|MEM_Int)) ){
66315       sqlite3VdbeMemStringify(pRec, enc);
66316     }
66317     pRec->flags &= ~(MEM_Real|MEM_Int);
66318   }else if( affinity!=SQLITE_AFF_NONE ){
66319     assert( affinity==SQLITE_AFF_INTEGER || affinity==SQLITE_AFF_REAL
66320              || affinity==SQLITE_AFF_NUMERIC );
66321     applyNumericAffinity(pRec);
66322     if( pRec->flags & MEM_Real ){
66323       sqlite3VdbeIntegerAffinity(pRec);
66324     }
66325   }
66326 }
66327 
66328 /*
66329 ** Try to convert the type of a function argument or a result column
66330 ** into a numeric representation.  Use either INTEGER or REAL whichever
66331 ** is appropriate.  But only do the conversion if it is possible without
66332 ** loss of information and return the revised type of the argument.
66333 */
66334 SQLITE_API int sqlite3_value_numeric_type(sqlite3_value *pVal){
66335   Mem *pMem = (Mem*)pVal;
66336   if( pMem->type==SQLITE_TEXT ){
66337     applyNumericAffinity(pMem);
66338     sqlite3VdbeMemStoreType(pMem);
66339   }
66340   return pMem->type;
66341 }
66342 
66343 /*
66344 ** Exported version of applyAffinity(). This one works on sqlite3_value*, 
66345 ** not the internal Mem* type.
66346 */
66347 SQLITE_PRIVATE void sqlite3ValueApplyAffinity(
66348   sqlite3_value *pVal, 
66349   u8 affinity, 
66350   u8 enc
66351 ){
66352   applyAffinity((Mem *)pVal, affinity, enc);
66353 }
66354 
66355 #ifdef SQLITE_DEBUG
66356 /*
66357 ** Write a nice string representation of the contents of cell pMem
66358 ** into buffer zBuf, length nBuf.
66359 */
66360 SQLITE_PRIVATE void sqlite3VdbeMemPrettyPrint(Mem *pMem, char *zBuf){
66361   char *zCsr = zBuf;
66362   int f = pMem->flags;
66363 
66364   static const char *const encnames[] = {"(X)", "(8)", "(16LE)", "(16BE)"};
66365 
66366   if( f&MEM_Blob ){
66367     int i;
66368     char c;
66369     if( f & MEM_Dyn ){
66370       c = 'z';
66371       assert( (f & (MEM_Static|MEM_Ephem))==0 );
66372     }else if( f & MEM_Static ){
66373       c = 't';
66374       assert( (f & (MEM_Dyn|MEM_Ephem))==0 );
66375     }else if( f & MEM_Ephem ){
66376       c = 'e';
66377       assert( (f & (MEM_Static|MEM_Dyn))==0 );
66378     }else{
66379       c = 's';
66380     }
66381 
66382     sqlite3_snprintf(100, zCsr, "%c", c);
66383     zCsr += sqlite3Strlen30(zCsr);
66384     sqlite3_snprintf(100, zCsr, "%d[", pMem->n);
66385     zCsr += sqlite3Strlen30(zCsr);
66386     for(i=0; i<16 && i<pMem->n; i++){
66387       sqlite3_snprintf(100, zCsr, "%02X", ((int)pMem->z[i] & 0xFF));
66388       zCsr += sqlite3Strlen30(zCsr);
66389     }
66390     for(i=0; i<16 && i<pMem->n; i++){
66391       char z = pMem->z[i];
66392       if( z<32 || z>126 ) *zCsr++ = '.';
66393       else *zCsr++ = z;
66394     }
66395 
66396     sqlite3_snprintf(100, zCsr, "]%s", encnames[pMem->enc]);
66397     zCsr += sqlite3Strlen30(zCsr);
66398     if( f & MEM_Zero ){
66399       sqlite3_snprintf(100, zCsr,"+%dz",pMem->u.nZero);
66400       zCsr += sqlite3Strlen30(zCsr);
66401     }
66402     *zCsr = '\0';
66403   }else if( f & MEM_Str ){
66404     int j, k;
66405     zBuf[0] = ' ';
66406     if( f & MEM_Dyn ){
66407       zBuf[1] = 'z';
66408       assert( (f & (MEM_Static|MEM_Ephem))==0 );
66409     }else if( f & MEM_Static ){
66410       zBuf[1] = 't';
66411       assert( (f & (MEM_Dyn|MEM_Ephem))==0 );
66412     }else if( f & MEM_Ephem ){
66413       zBuf[1] = 'e';
66414       assert( (f & (MEM_Static|MEM_Dyn))==0 );
66415     }else{
66416       zBuf[1] = 's';
66417     }
66418     k = 2;
66419     sqlite3_snprintf(100, &zBuf[k], "%d", pMem->n);
66420     k += sqlite3Strlen30(&zBuf[k]);
66421     zBuf[k++] = '[';
66422     for(j=0; j<15 && j<pMem->n; j++){
66423       u8 c = pMem->z[j];
66424       if( c>=0x20 && c<0x7f ){
66425         zBuf[k++] = c;
66426       }else{
66427         zBuf[k++] = '.';
66428       }
66429     }
66430     zBuf[k++] = ']';
66431     sqlite3_snprintf(100,&zBuf[k], encnames[pMem->enc]);
66432     k += sqlite3Strlen30(&zBuf[k]);
66433     zBuf[k++] = 0;
66434   }
66435 }
66436 #endif
66437 
66438 #ifdef SQLITE_DEBUG
66439 /*
66440 ** Print the value of a register for tracing purposes:
66441 */
66442 static void memTracePrint(Mem *p){
66443   if( p->flags & MEM_Invalid ){
66444     printf(" undefined");
66445   }else if( p->flags & MEM_Null ){
66446     printf(" NULL");
66447   }else if( (p->flags & (MEM_Int|MEM_Str))==(MEM_Int|MEM_Str) ){
66448     printf(" si:%lld", p->u.i);
66449   }else if( p->flags & MEM_Int ){
66450     printf(" i:%lld", p->u.i);
66451 #ifndef SQLITE_OMIT_FLOATING_POINT
66452   }else if( p->flags & MEM_Real ){
66453     printf(" r:%g", p->r);
66454 #endif
66455   }else if( p->flags & MEM_RowSet ){
66456     printf(" (rowset)");
66457   }else{
66458     char zBuf[200];
66459     sqlite3VdbeMemPrettyPrint(p, zBuf);
66460     printf(" %s", zBuf);
66461   }
66462 }
66463 static void registerTrace(int iReg, Mem *p){
66464   printf("REG[%d] = ", iReg);
66465   memTracePrint(p);
66466   printf("\n");
66467 }
66468 #endif
66469 
66470 #ifdef SQLITE_DEBUG
66471 #  define REGISTER_TRACE(R,M) if(db->flags&SQLITE_VdbeTrace)registerTrace(R,M)
66472 #else
66473 #  define REGISTER_TRACE(R,M)
66474 #endif
66475 
66476 
66477 #ifdef VDBE_PROFILE
66478 
66479 /* 
66480 ** hwtime.h contains inline assembler code for implementing 
66481 ** high-performance timing routines.
66482 */
66483 /************** Include hwtime.h in the middle of vdbe.c *********************/
66484 /************** Begin file hwtime.h ******************************************/
66485 /*
66486 ** 2008 May 27
66487 **
66488 ** The author disclaims copyright to this source code.  In place of
66489 ** a legal notice, here is a blessing:
66490 **
66491 **    May you do good and not evil.
66492 **    May you find forgiveness for yourself and forgive others.
66493 **    May you share freely, never taking more than you give.
66494 **
66495 ******************************************************************************
66496 **
66497 ** This file contains inline asm code for retrieving "high-performance"
66498 ** counters for x86 class CPUs.
66499 */
66500 #ifndef _HWTIME_H_
66501 #define _HWTIME_H_
66502 
66503 /*
66504 ** The following routine only works on pentium-class (or newer) processors.
66505 ** It uses the RDTSC opcode to read the cycle count value out of the
66506 ** processor and returns that value.  This can be used for high-res
66507 ** profiling.
66508 */
66509 #if (defined(__GNUC__) || defined(_MSC_VER)) && \
66510       (defined(i386) || defined(__i386__) || defined(_M_IX86))
66511 
66512   #if defined(__GNUC__)
66513 
66514   __inline__ sqlite_uint64 sqlite3Hwtime(void){
66515      unsigned int lo, hi;
66516      __asm__ __volatile__ ("rdtsc" : "=a" (lo), "=d" (hi));
66517      return (sqlite_uint64)hi << 32 | lo;
66518   }
66519 
66520   #elif defined(_MSC_VER)
66521 
66522   __declspec(naked) __inline sqlite_uint64 __cdecl sqlite3Hwtime(void){
66523      __asm {
66524         rdtsc
66525         ret       ; return value at EDX:EAX
66526      }
66527   }
66528 
66529   #endif
66530 
66531 #elif (defined(__GNUC__) && defined(__x86_64__))
66532 
66533   __inline__ sqlite_uint64 sqlite3Hwtime(void){
66534       unsigned long val;
66535       __asm__ __volatile__ ("rdtsc" : "=A" (val));
66536       return val;
66537   }
66538  
66539 #elif (defined(__GNUC__) && defined(__ppc__))
66540 
66541   __inline__ sqlite_uint64 sqlite3Hwtime(void){
66542       unsigned long long retval;
66543       unsigned long junk;
66544       __asm__ __volatile__ ("\n\
66545           1:      mftbu   %1\n\
66546                   mftb    %L0\n\
66547                   mftbu   %0\n\
66548                   cmpw    %0,%1\n\
66549                   bne     1b"
66550                   : "=r" (retval), "=r" (junk));
66551       return retval;
66552   }
66553 
66554 #else
66555 
66556   #error Need implementation of sqlite3Hwtime() for your platform.
66557 
66558   /*
66559   ** To compile without implementing sqlite3Hwtime() for your platform,
66560   ** you can remove the above #error and use the following
66561   ** stub function.  You will lose timing support for many
66562   ** of the debugging and testing utilities, but it should at
66563   ** least compile and run.
66564   */
66565 SQLITE_PRIVATE   sqlite_uint64 sqlite3Hwtime(void){ return ((sqlite_uint64)0); }
66566 
66567 #endif
66568 
66569 #endif /* !defined(_HWTIME_H_) */
66570 
66571 /************** End of hwtime.h **********************************************/
66572 /************** Continuing where we left off in vdbe.c ***********************/
66573 
66574 #endif
66575 
66576 /*
66577 ** The CHECK_FOR_INTERRUPT macro defined here looks to see if the
66578 ** sqlite3_interrupt() routine has been called.  If it has been, then
66579 ** processing of the VDBE program is interrupted.
66580 **
66581 ** This macro added to every instruction that does a jump in order to
66582 ** implement a loop.  This test used to be on every single instruction,
66583 ** but that meant we more testing than we needed.  By only testing the
66584 ** flag on jump instructions, we get a (small) speed improvement.
66585 */
66586 #define CHECK_FOR_INTERRUPT \
66587    if( db->u1.isInterrupted ) goto abort_due_to_interrupt;
66588 
66589 
66590 #ifndef NDEBUG
66591 /*
66592 ** This function is only called from within an assert() expression. It
66593 ** checks that the sqlite3.nTransaction variable is correctly set to
66594 ** the number of non-transaction savepoints currently in the 
66595 ** linked list starting at sqlite3.pSavepoint.
66596 ** 
66597 ** Usage:
66598 **
66599 **     assert( checkSavepointCount(db) );
66600 */
66601 static int checkSavepointCount(sqlite3 *db){
66602   int n = 0;
66603   Savepoint *p;
66604   for(p=db->pSavepoint; p; p=p->pNext) n++;
66605   assert( n==(db->nSavepoint + db->isTransactionSavepoint) );
66606   return 1;
66607 }
66608 #endif
66609 
66610 
66611 /*
66612 ** Execute as much of a VDBE program as we can then return.
66613 **
66614 ** sqlite3VdbeMakeReady() must be called before this routine in order to
66615 ** close the program with a final OP_Halt and to set up the callbacks
66616 ** and the error message pointer.
66617 **
66618 ** Whenever a row or result data is available, this routine will either
66619 ** invoke the result callback (if there is one) or return with
66620 ** SQLITE_ROW.
66621 **
66622 ** If an attempt is made to open a locked database, then this routine
66623 ** will either invoke the busy callback (if there is one) or it will
66624 ** return SQLITE_BUSY.
66625 **
66626 ** If an error occurs, an error message is written to memory obtained
66627 ** from sqlite3_malloc() and p->zErrMsg is made to point to that memory.
66628 ** The error code is stored in p->rc and this routine returns SQLITE_ERROR.
66629 **
66630 ** If the callback ever returns non-zero, then the program exits
66631 ** immediately.  There will be no error message but the p->rc field is
66632 ** set to SQLITE_ABORT and this routine will return SQLITE_ERROR.
66633 **
66634 ** A memory allocation error causes p->rc to be set to SQLITE_NOMEM and this
66635 ** routine to return SQLITE_ERROR.
66636 **
66637 ** Other fatal errors return SQLITE_ERROR.
66638 **
66639 ** After this routine has finished, sqlite3VdbeFinalize() should be
66640 ** used to clean up the mess that was left behind.
66641 */
66642 SQLITE_PRIVATE int sqlite3VdbeExec(
66643   Vdbe *p                    /* The VDBE */
66644 ){
66645   int pc=0;                  /* The program counter */
66646   Op *aOp = p->aOp;          /* Copy of p->aOp */
66647   Op *pOp;                   /* Current operation */
66648   int rc = SQLITE_OK;        /* Value to return */
66649   sqlite3 *db = p->db;       /* The database */
66650   u8 resetSchemaOnFault = 0; /* Reset schema after an error if positive */
66651   u8 encoding = ENC(db);     /* The database encoding */
66652   int iCompare = 0;          /* Result of last OP_Compare operation */
66653   unsigned nVmStep = 0;      /* Number of virtual machine steps */
66654 #ifndef SQLITE_OMIT_PROGRESS_CALLBACK
66655   unsigned nProgressLimit = 0;/* Invoke xProgress() when nVmStep reaches this */
66656 #endif
66657   Mem *aMem = p->aMem;       /* Copy of p->aMem */
66658   Mem *pIn1 = 0;             /* 1st input operand */
66659   Mem *pIn2 = 0;             /* 2nd input operand */
66660   Mem *pIn3 = 0;             /* 3rd input operand */
66661   Mem *pOut = 0;             /* Output operand */
66662   int *aPermute = 0;         /* Permutation of columns for OP_Compare */
66663   i64 lastRowid = db->lastRowid;  /* Saved value of the last insert ROWID */
66664 #ifdef VDBE_PROFILE
66665   u64 start;                 /* CPU clock count at start of opcode */
66666   int origPc;                /* Program counter at start of opcode */
66667 #endif
66668   /********************************************************************
66669   ** Automatically generated code
66670   **
66671   ** The following union is automatically generated by the
66672   ** vdbe-compress.tcl script.  The purpose of this union is to
66673   ** reduce the amount of stack space required by this function.
66674   ** See comments in the vdbe-compress.tcl script for details.
66675   */
66676   union vdbeExecUnion {
66677     struct OP_Yield_stack_vars {
66678       int pcDest;
66679     } aa;
66680     struct OP_Halt_stack_vars {
66681       const char *zType;
66682       const char *zLogFmt;
66683     } ab;
66684     struct OP_Null_stack_vars {
66685       int cnt;
66686       u16 nullFlag;
66687     } ac;
66688     struct OP_Variable_stack_vars {
66689       Mem *pVar;       /* Value being transferred */
66690     } ad;
66691     struct OP_Move_stack_vars {
66692       char *zMalloc;   /* Holding variable for allocated memory */
66693       int n;           /* Number of registers left to copy */
66694       int p1;          /* Register to copy from */
66695       int p2;          /* Register to copy to */
66696     } ae;
66697     struct OP_Copy_stack_vars {
66698       int n;
66699     } af;
66700     struct OP_ResultRow_stack_vars {
66701       Mem *pMem;
66702       int i;
66703     } ag;
66704     struct OP_Concat_stack_vars {
66705       i64 nByte;
66706     } ah;
66707     struct OP_Remainder_stack_vars {
66708       char bIntint;   /* Started out as two integer operands */
66709       int flags;      /* Combined MEM_* flags from both inputs */
66710       i64 iA;         /* Integer value of left operand */
66711       i64 iB;         /* Integer value of right operand */
66712       double rA;      /* Real value of left operand */
66713       double rB;      /* Real value of right operand */
66714     } ai;
66715     struct OP_Function_stack_vars {
66716       int i;
66717       Mem *pArg;
66718       sqlite3_context ctx;
66719       sqlite3_value **apVal;
66720       int n;
66721     } aj;
66722     struct OP_ShiftRight_stack_vars {
66723       i64 iA;
66724       u64 uA;
66725       i64 iB;
66726       u8 op;
66727     } ak;
66728     struct OP_Ge_stack_vars {
66729       int res;            /* Result of the comparison of pIn1 against pIn3 */
66730       char affinity;      /* Affinity to use for comparison */
66731       u16 flags1;         /* Copy of initial value of pIn1->flags */
66732       u16 flags3;         /* Copy of initial value of pIn3->flags */
66733     } al;
66734     struct OP_Compare_stack_vars {
66735       int n;
66736       int i;
66737       int p1;
66738       int p2;
66739       const KeyInfo *pKeyInfo;
66740       int idx;
66741       CollSeq *pColl;    /* Collating sequence to use on this term */
66742       int bRev;          /* True for DESCENDING sort order */
66743     } am;
66744     struct OP_Or_stack_vars {
66745       int v1;    /* Left operand:  0==FALSE, 1==TRUE, 2==UNKNOWN or NULL */
66746       int v2;    /* Right operand: 0==FALSE, 1==TRUE, 2==UNKNOWN or NULL */
66747     } an;
66748     struct OP_IfNot_stack_vars {
66749       int c;
66750     } ao;
66751     struct OP_Column_stack_vars {
66752       i64 payloadSize64; /* Number of bytes in the record */
66753       int p2;            /* column number to retrieve */
66754       VdbeCursor *pC;    /* The VDBE cursor */
66755       BtCursor *pCrsr;   /* The BTree cursor */
66756       u32 *aType;        /* aType[i] holds the numeric type of the i-th column */
66757       u32 *aOffset;      /* aOffset[i] is offset to start of data for i-th column */
66758       int len;           /* The length of the serialized data for the column */
66759       int i;             /* Loop counter */
66760       Mem *pDest;        /* Where to write the extracted value */
66761       Mem sMem;          /* For storing the record being decoded */
66762       const u8 *zData;   /* Part of the record being decoded */
66763       const u8 *zHdr;    /* Next unparsed byte of the header */
66764       const u8 *zEndHdr; /* Pointer to first byte after the header */
66765       u32 offset;        /* Offset into the data */
66766       u32 szField;       /* Number of bytes in the content of a field */
66767       u32 avail;         /* Number of bytes of available data */
66768       u32 t;             /* A type code from the record header */
66769       Mem *pReg;         /* PseudoTable input register */
66770     } ap;
66771     struct OP_Affinity_stack_vars {
66772       const char *zAffinity;   /* The affinity to be applied */
66773       char cAff;               /* A single character of affinity */
66774     } aq;
66775     struct OP_MakeRecord_stack_vars {
66776       u8 *zNewRecord;        /* A buffer to hold the data for the new record */
66777       Mem *pRec;             /* The new record */
66778       u64 nData;             /* Number of bytes of data space */
66779       int nHdr;              /* Number of bytes of header space */
66780       i64 nByte;             /* Data space required for this record */
66781       int nZero;             /* Number of zero bytes at the end of the record */
66782       int nVarint;           /* Number of bytes in a varint */
66783       u32 serial_type;       /* Type field */
66784       Mem *pData0;           /* First field to be combined into the record */
66785       Mem *pLast;            /* Last field of the record */
66786       int nField;            /* Number of fields in the record */
66787       char *zAffinity;       /* The affinity string for the record */
66788       int file_format;       /* File format to use for encoding */
66789       int i;                 /* Space used in zNewRecord[] */
66790       int len;               /* Length of a field */
66791     } ar;
66792     struct OP_Count_stack_vars {
66793       i64 nEntry;
66794       BtCursor *pCrsr;
66795     } as;
66796     struct OP_Savepoint_stack_vars {
66797       int p1;                         /* Value of P1 operand */
66798       char *zName;                    /* Name of savepoint */
66799       int nName;
66800       Savepoint *pNew;
66801       Savepoint *pSavepoint;
66802       Savepoint *pTmp;
66803       int iSavepoint;
66804       int ii;
66805     } at;
66806     struct OP_AutoCommit_stack_vars {
66807       int desiredAutoCommit;
66808       int iRollback;
66809       int turnOnAC;
66810     } au;
66811     struct OP_Transaction_stack_vars {
66812       Btree *pBt;
66813     } av;
66814     struct OP_ReadCookie_stack_vars {
66815       int iMeta;
66816       int iDb;
66817       int iCookie;
66818     } aw;
66819     struct OP_SetCookie_stack_vars {
66820       Db *pDb;
66821     } ax;
66822     struct OP_VerifyCookie_stack_vars {
66823       int iMeta;
66824       int iGen;
66825       Btree *pBt;
66826     } ay;
66827     struct OP_OpenWrite_stack_vars {
66828       int nField;
66829       KeyInfo *pKeyInfo;
66830       int p2;
66831       int iDb;
66832       int wrFlag;
66833       Btree *pX;
66834       VdbeCursor *pCur;
66835       Db *pDb;
66836     } az;
66837     struct OP_OpenEphemeral_stack_vars {
66838       VdbeCursor *pCx;
66839       KeyInfo *pKeyInfo;
66840     } ba;
66841     struct OP_SorterOpen_stack_vars {
66842       VdbeCursor *pCx;
66843     } bb;
66844     struct OP_OpenPseudo_stack_vars {
66845       VdbeCursor *pCx;
66846     } bc;
66847     struct OP_SeekGt_stack_vars {
66848       int res;
66849       int oc;
66850       VdbeCursor *pC;
66851       UnpackedRecord r;
66852       int nField;
66853       i64 iKey;      /* The rowid we are to seek to */
66854     } bd;
66855     struct OP_Seek_stack_vars {
66856       VdbeCursor *pC;
66857     } be;
66858     struct OP_Found_stack_vars {
66859       int alreadyExists;
66860       int ii;
66861       VdbeCursor *pC;
66862       int res;
66863       char *pFree;
66864       UnpackedRecord *pIdxKey;
66865       UnpackedRecord r;
66866       char aTempRec[ROUND8(sizeof(UnpackedRecord)) + sizeof(Mem)*4 + 7];
66867     } bf;
66868     struct OP_NotExists_stack_vars {
66869       VdbeCursor *pC;
66870       BtCursor *pCrsr;
66871       int res;
66872       u64 iKey;
66873     } bg;
66874     struct OP_NewRowid_stack_vars {
66875       i64 v;                 /* The new rowid */
66876       VdbeCursor *pC;        /* Cursor of table to get the new rowid */
66877       int res;               /* Result of an sqlite3BtreeLast() */
66878       int cnt;               /* Counter to limit the number of searches */
66879       Mem *pMem;             /* Register holding largest rowid for AUTOINCREMENT */
66880       VdbeFrame *pFrame;     /* Root frame of VDBE */
66881     } bh;
66882     struct OP_InsertInt_stack_vars {
66883       Mem *pData;       /* MEM cell holding data for the record to be inserted */
66884       Mem *pKey;        /* MEM cell holding key  for the record */
66885       i64 iKey;         /* The integer ROWID or key for the record to be inserted */
66886       VdbeCursor *pC;   /* Cursor to table into which insert is written */
66887       int nZero;        /* Number of zero-bytes to append */
66888       int seekResult;   /* Result of prior seek or 0 if no USESEEKRESULT flag */
66889       const char *zDb;  /* database name - used by the update hook */
66890       const char *zTbl; /* Table name - used by the opdate hook */
66891       int op;           /* Opcode for update hook: SQLITE_UPDATE or SQLITE_INSERT */
66892     } bi;
66893     struct OP_Delete_stack_vars {
66894       i64 iKey;
66895       VdbeCursor *pC;
66896     } bj;
66897     struct OP_SorterCompare_stack_vars {
66898       VdbeCursor *pC;
66899       int res;
66900       int nIgnore;
66901     } bk;
66902     struct OP_SorterData_stack_vars {
66903       VdbeCursor *pC;
66904     } bl;
66905     struct OP_RowData_stack_vars {
66906       VdbeCursor *pC;
66907       BtCursor *pCrsr;
66908       u32 n;
66909       i64 n64;
66910     } bm;
66911     struct OP_Rowid_stack_vars {
66912       VdbeCursor *pC;
66913       i64 v;
66914       sqlite3_vtab *pVtab;
66915       const sqlite3_module *pModule;
66916     } bn;
66917     struct OP_NullRow_stack_vars {
66918       VdbeCursor *pC;
66919     } bo;
66920     struct OP_Last_stack_vars {
66921       VdbeCursor *pC;
66922       BtCursor *pCrsr;
66923       int res;
66924     } bp;
66925     struct OP_Rewind_stack_vars {
66926       VdbeCursor *pC;
66927       BtCursor *pCrsr;
66928       int res;
66929     } bq;
66930     struct OP_SorterNext_stack_vars {
66931       VdbeCursor *pC;
66932       int res;
66933     } br;
66934     struct OP_IdxInsert_stack_vars {
66935       VdbeCursor *pC;
66936       BtCursor *pCrsr;
66937       int nKey;
66938       const char *zKey;
66939     } bs;
66940     struct OP_IdxDelete_stack_vars {
66941       VdbeCursor *pC;
66942       BtCursor *pCrsr;
66943       int res;
66944       UnpackedRecord r;
66945     } bt;
66946     struct OP_IdxRowid_stack_vars {
66947       BtCursor *pCrsr;
66948       VdbeCursor *pC;
66949       i64 rowid;
66950     } bu;
66951     struct OP_IdxGE_stack_vars {
66952       VdbeCursor *pC;
66953       int res;
66954       UnpackedRecord r;
66955     } bv;
66956     struct OP_Destroy_stack_vars {
66957       int iMoved;
66958       int iCnt;
66959       Vdbe *pVdbe;
66960       int iDb;
66961     } bw;
66962     struct OP_Clear_stack_vars {
66963       int nChange;
66964     } bx;
66965     struct OP_CreateTable_stack_vars {
66966       int pgno;
66967       int flags;
66968       Db *pDb;
66969     } by;
66970     struct OP_ParseSchema_stack_vars {
66971       int iDb;
66972       const char *zMaster;
66973       char *zSql;
66974       InitData initData;
66975     } bz;
66976     struct OP_IntegrityCk_stack_vars {
66977       int nRoot;      /* Number of tables to check.  (Number of root pages.) */
66978       int *aRoot;     /* Array of rootpage numbers for tables to be checked */
66979       int j;          /* Loop counter */
66980       int nErr;       /* Number of errors reported */
66981       char *z;        /* Text of the error report */
66982       Mem *pnErr;     /* Register keeping track of errors remaining */
66983     } ca;
66984     struct OP_RowSetRead_stack_vars {
66985       i64 val;
66986     } cb;
66987     struct OP_RowSetTest_stack_vars {
66988       int iSet;
66989       int exists;
66990     } cc;
66991     struct OP_Program_stack_vars {
66992       int nMem;               /* Number of memory registers for sub-program */
66993       int nByte;              /* Bytes of runtime space required for sub-program */
66994       Mem *pRt;               /* Register to allocate runtime space */
66995       Mem *pMem;              /* Used to iterate through memory cells */
66996       Mem *pEnd;              /* Last memory cell in new array */
66997       VdbeFrame *pFrame;      /* New vdbe frame to execute in */
66998       SubProgram *pProgram;   /* Sub-program to execute */
66999       void *t;                /* Token identifying trigger */
67000     } cd;
67001     struct OP_Param_stack_vars {
67002       VdbeFrame *pFrame;
67003       Mem *pIn;
67004     } ce;
67005     struct OP_MemMax_stack_vars {
67006       Mem *pIn1;
67007       VdbeFrame *pFrame;
67008     } cf;
67009     struct OP_AggStep_stack_vars {
67010       int n;
67011       int i;
67012       Mem *pMem;
67013       Mem *pRec;
67014       sqlite3_context ctx;
67015       sqlite3_value **apVal;
67016     } cg;
67017     struct OP_AggFinal_stack_vars {
67018       Mem *pMem;
67019     } ch;
67020     struct OP_Checkpoint_stack_vars {
67021       int i;                          /* Loop counter */
67022       int aRes[3];                    /* Results */
67023       Mem *pMem;                      /* Write results here */
67024     } ci;
67025     struct OP_JournalMode_stack_vars {
67026       Btree *pBt;                     /* Btree to change journal mode of */
67027       Pager *pPager;                  /* Pager associated with pBt */
67028       int eNew;                       /* New journal mode */
67029       int eOld;                       /* The old journal mode */
67030 #ifndef SQLITE_OMIT_WAL
67031       const char *zFilename;          /* Name of database file for pPager */
67032 #endif
67033     } cj;
67034     struct OP_IncrVacuum_stack_vars {
67035       Btree *pBt;
67036     } ck;
67037     struct OP_VBegin_stack_vars {
67038       VTable *pVTab;
67039     } cl;
67040     struct OP_VOpen_stack_vars {
67041       VdbeCursor *pCur;
67042       sqlite3_vtab_cursor *pVtabCursor;
67043       sqlite3_vtab *pVtab;
67044       sqlite3_module *pModule;
67045     } cm;
67046     struct OP_VFilter_stack_vars {
67047       int nArg;
67048       int iQuery;
67049       const sqlite3_module *pModule;
67050       Mem *pQuery;
67051       Mem *pArgc;
67052       sqlite3_vtab_cursor *pVtabCursor;
67053       sqlite3_vtab *pVtab;
67054       VdbeCursor *pCur;
67055       int res;
67056       int i;
67057       Mem **apArg;
67058     } cn;
67059     struct OP_VColumn_stack_vars {
67060       sqlite3_vtab *pVtab;
67061       const sqlite3_module *pModule;
67062       Mem *pDest;
67063       sqlite3_context sContext;
67064     } co;
67065     struct OP_VNext_stack_vars {
67066       sqlite3_vtab *pVtab;
67067       const sqlite3_module *pModule;
67068       int res;
67069       VdbeCursor *pCur;
67070     } cp;
67071     struct OP_VRename_stack_vars {
67072       sqlite3_vtab *pVtab;
67073       Mem *pName;
67074     } cq;
67075     struct OP_VUpdate_stack_vars {
67076       sqlite3_vtab *pVtab;
67077       sqlite3_module *pModule;
67078       int nArg;
67079       int i;
67080       sqlite_int64 rowid;
67081       Mem **apArg;
67082       Mem *pX;
67083     } cr;
67084     struct OP_Trace_stack_vars {
67085       char *zTrace;
67086       char *z;
67087     } cs;
67088   } u;
67089   /* End automatically generated code
67090   ********************************************************************/
67091 
67092   assert( p->magic==VDBE_MAGIC_RUN );  /* sqlite3_step() verifies this */
67093   sqlite3VdbeEnter(p);
67094   if( p->rc==SQLITE_NOMEM ){
67095     /* This happens if a malloc() inside a call to sqlite3_column_text() or
67096     ** sqlite3_column_text16() failed.  */
67097     goto no_mem;
67098   }
67099   assert( p->rc==SQLITE_OK || p->rc==SQLITE_BUSY );
67100   assert( p->bIsReader || p->readOnly!=0 );
67101   p->rc = SQLITE_OK;
67102   p->iCurrentTime = 0;
67103   assert( p->explain==0 );
67104   p->pResultSet = 0;
67105   db->busyHandler.nBusy = 0;
67106   CHECK_FOR_INTERRUPT;
67107   sqlite3VdbeIOTraceSql(p);
67108 #ifndef SQLITE_OMIT_PROGRESS_CALLBACK
67109   if( db->xProgress ){
67110     assert( 0 < db->nProgressOps );
67111     nProgressLimit = (unsigned)p->aCounter[SQLITE_STMTSTATUS_VM_STEP];
67112     if( nProgressLimit==0 ){
67113       nProgressLimit = db->nProgressOps;
67114     }else{
67115       nProgressLimit %= (unsigned)db->nProgressOps;
67116     }
67117   }
67118 #endif
67119 #ifdef SQLITE_DEBUG
67120   sqlite3BeginBenignMalloc();
67121   if( p->pc==0
67122    && (p->db->flags & (SQLITE_VdbeListing|SQLITE_VdbeEQP|SQLITE_VdbeTrace))!=0
67123   ){
67124     int i;
67125     int once = 1;
67126     sqlite3VdbePrintSql(p);
67127     if( p->db->flags & SQLITE_VdbeListing ){
67128       printf("VDBE Program Listing:\n");
67129       for(i=0; i<p->nOp; i++){
67130         sqlite3VdbePrintOp(stdout, i, &aOp[i]);
67131       }
67132     }
67133     if( p->db->flags & SQLITE_VdbeEQP ){
67134       for(i=0; i<p->nOp; i++){
67135         if( aOp[i].opcode==OP_Explain ){
67136           if( once ) printf("VDBE Query Plan:\n");
67137           printf("%s\n", aOp[i].p4.z);
67138           once = 0;
67139         }
67140       }
67141     }
67142     if( p->db->flags & SQLITE_VdbeTrace )  printf("VDBE Trace:\n");
67143   }
67144   sqlite3EndBenignMalloc();
67145 #endif
67146   for(pc=p->pc; rc==SQLITE_OK; pc++){
67147     assert( pc>=0 && pc<p->nOp );
67148     if( db->mallocFailed ) goto no_mem;
67149 #ifdef VDBE_PROFILE
67150     origPc = pc;
67151     start = sqlite3Hwtime();
67152 #endif
67153     nVmStep++;
67154     pOp = &aOp[pc];
67155 
67156     /* Only allow tracing if SQLITE_DEBUG is defined.
67157     */
67158 #ifdef SQLITE_DEBUG
67159     if( db->flags & SQLITE_VdbeTrace ){
67160       sqlite3VdbePrintOp(stdout, pc, pOp);
67161     }
67162 #endif
67163       
67164 
67165     /* Check to see if we need to simulate an interrupt.  This only happens
67166     ** if we have a special test build.
67167     */
67168 #ifdef SQLITE_TEST
67169     if( sqlite3_interrupt_count>0 ){
67170       sqlite3_interrupt_count--;
67171       if( sqlite3_interrupt_count==0 ){
67172         sqlite3_interrupt(db);
67173       }
67174     }
67175 #endif
67176 
67177     /* On any opcode with the "out2-prerelease" tag, free any
67178     ** external allocations out of mem[p2] and set mem[p2] to be
67179     ** an undefined integer.  Opcodes will either fill in the integer
67180     ** value or convert mem[p2] to a different type.
67181     */
67182     assert( pOp->opflags==sqlite3OpcodeProperty[pOp->opcode] );
67183     if( pOp->opflags & OPFLG_OUT2_PRERELEASE ){
67184       assert( pOp->p2>0 );
67185       assert( pOp->p2<=(p->nMem-p->nCursor) );
67186       pOut = &aMem[pOp->p2];
67187       memAboutToChange(p, pOut);
67188       VdbeMemRelease(pOut);
67189       pOut->flags = MEM_Int;
67190     }
67191 
67192     /* Sanity checking on other operands */
67193 #ifdef SQLITE_DEBUG
67194     if( (pOp->opflags & OPFLG_IN1)!=0 ){
67195       assert( pOp->p1>0 );
67196       assert( pOp->p1<=(p->nMem-p->nCursor) );
67197       assert( memIsValid(&aMem[pOp->p1]) );
67198       REGISTER_TRACE(pOp->p1, &aMem[pOp->p1]);
67199     }
67200     if( (pOp->opflags & OPFLG_IN2)!=0 ){
67201       assert( pOp->p2>0 );
67202       assert( pOp->p2<=(p->nMem-p->nCursor) );
67203       assert( memIsValid(&aMem[pOp->p2]) );
67204       REGISTER_TRACE(pOp->p2, &aMem[pOp->p2]);
67205     }
67206     if( (pOp->opflags & OPFLG_IN3)!=0 ){
67207       assert( pOp->p3>0 );
67208       assert( pOp->p3<=(p->nMem-p->nCursor) );
67209       assert( memIsValid(&aMem[pOp->p3]) );
67210       REGISTER_TRACE(pOp->p3, &aMem[pOp->p3]);
67211     }
67212     if( (pOp->opflags & OPFLG_OUT2)!=0 ){
67213       assert( pOp->p2>0 );
67214       assert( pOp->p2<=(p->nMem-p->nCursor) );
67215       memAboutToChange(p, &aMem[pOp->p2]);
67216     }
67217     if( (pOp->opflags & OPFLG_OUT3)!=0 ){
67218       assert( pOp->p3>0 );
67219       assert( pOp->p3<=(p->nMem-p->nCursor) );
67220       memAboutToChange(p, &aMem[pOp->p3]);
67221     }
67222 #endif
67223   
67224     switch( pOp->opcode ){
67225 
67226 /*****************************************************************************
67227 ** What follows is a massive switch statement where each case implements a
67228 ** separate instruction in the virtual machine.  If we follow the usual
67229 ** indentation conventions, each case should be indented by 6 spaces.  But
67230 ** that is a lot of wasted space on the left margin.  So the code within
67231 ** the switch statement will break with convention and be flush-left. Another
67232 ** big comment (similar to this one) will mark the point in the code where
67233 ** we transition back to normal indentation.
67234 **
67235 ** The formatting of each case is important.  The makefile for SQLite
67236 ** generates two C files "opcodes.h" and "opcodes.c" by scanning this
67237 ** file looking for lines that begin with "case OP_".  The opcodes.h files
67238 ** will be filled with #defines that give unique integer values to each
67239 ** opcode and the opcodes.c file is filled with an array of strings where
67240 ** each string is the symbolic name for the corresponding opcode.  If the
67241 ** case statement is followed by a comment of the form "/# same as ... #/"
67242 ** that comment is used to determine the particular value of the opcode.
67243 **
67244 ** Other keywords in the comment that follows each case are used to
67245 ** construct the OPFLG_INITIALIZER value that initializes opcodeProperty[].
67246 ** Keywords include: in1, in2, in3, out2_prerelease, out2, out3.  See
67247 ** the mkopcodeh.awk script for additional information.
67248 **
67249 ** Documentation about VDBE opcodes is generated by scanning this file
67250 ** for lines of that contain "Opcode:".  That line and all subsequent
67251 ** comment lines are used in the generation of the opcode.html documentation
67252 ** file.
67253 **
67254 ** SUMMARY:
67255 **
67256 **     Formatting is important to scripts that scan this file.
67257 **     Do not deviate from the formatting style currently in use.
67258 **
67259 *****************************************************************************/
67260 
67261 /* Opcode:  Goto * P2 * * *
67262 **
67263 ** An unconditional jump to address P2.
67264 ** The next instruction executed will be 
67265 ** the one at index P2 from the beginning of
67266 ** the program.
67267 */
67268 case OP_Goto: {             /* jump */
67269   pc = pOp->p2 - 1;
67270 
67271   /* Opcodes that are used as the bottom of a loop (OP_Next, OP_Prev,
67272   ** OP_VNext, OP_RowSetNext, or OP_SorterNext) all jump here upon
67273   ** completion.  Check to see if sqlite3_interrupt() has been called
67274   ** or if the progress callback needs to be invoked. 
67275   **
67276   ** This code uses unstructured "goto" statements and does not look clean.
67277   ** But that is not due to sloppy coding habits. The code is written this
67278   ** way for performance, to avoid having to run the interrupt and progress
67279   ** checks on every opcode.  This helps sqlite3_step() to run about 1.5%
67280   ** faster according to "valgrind --tool=cachegrind" */
67281 check_for_interrupt:
67282   CHECK_FOR_INTERRUPT;
67283 #ifndef SQLITE_OMIT_PROGRESS_CALLBACK
67284   /* Call the progress callback if it is configured and the required number
67285   ** of VDBE ops have been executed (either since this invocation of
67286   ** sqlite3VdbeExec() or since last time the progress callback was called).
67287   ** If the progress callback returns non-zero, exit the virtual machine with
67288   ** a return code SQLITE_ABORT.
67289   */
67290   if( db->xProgress!=0 && nVmStep>=nProgressLimit ){
67291     assert( db->nProgressOps!=0 );
67292     nProgressLimit = nVmStep + db->nProgressOps - (nVmStep%db->nProgressOps);
67293     if( db->xProgress(db->pProgressArg) ){
67294       rc = SQLITE_INTERRUPT;
67295       goto vdbe_error_halt;
67296     }
67297   }
67298 #endif
67299   
67300   break;
67301 }
67302 
67303 /* Opcode:  Gosub P1 P2 * * *
67304 **
67305 ** Write the current address onto register P1
67306 ** and then jump to address P2.
67307 */
67308 case OP_Gosub: {            /* jump */
67309   assert( pOp->p1>0 && pOp->p1<=(p->nMem-p->nCursor) );
67310   pIn1 = &aMem[pOp->p1];
67311   assert( (pIn1->flags & MEM_Dyn)==0 );
67312   memAboutToChange(p, pIn1);
67313   pIn1->flags = MEM_Int;
67314   pIn1->u.i = pc;
67315   REGISTER_TRACE(pOp->p1, pIn1);
67316   pc = pOp->p2 - 1;
67317   break;
67318 }
67319 
67320 /* Opcode:  Return P1 * * * *
67321 **
67322 ** Jump to the next instruction after the address in register P1.
67323 */
67324 case OP_Return: {           /* in1 */
67325   pIn1 = &aMem[pOp->p1];
67326   assert( pIn1->flags & MEM_Int );
67327   pc = (int)pIn1->u.i;
67328   break;
67329 }
67330 
67331 /* Opcode:  Yield P1 * * * *
67332 **
67333 ** Swap the program counter with the value in register P1.
67334 */
67335 case OP_Yield: {            /* in1 */
67336 #if 0  /* local variables moved into u.aa */
67337   int pcDest;
67338 #endif /* local variables moved into u.aa */
67339   pIn1 = &aMem[pOp->p1];
67340   assert( (pIn1->flags & MEM_Dyn)==0 );
67341   pIn1->flags = MEM_Int;
67342   u.aa.pcDest = (int)pIn1->u.i;
67343   pIn1->u.i = pc;
67344   REGISTER_TRACE(pOp->p1, pIn1);
67345   pc = u.aa.pcDest;
67346   break;
67347 }
67348 
67349 /* Opcode:  HaltIfNull  P1 P2 P3 P4 P5
67350 ** Synopsis:  if r[P3] null then halt
67351 **
67352 ** Check the value in register P3.  If it is NULL then Halt using
67353 ** parameter P1, P2, and P4 as if this were a Halt instruction.  If the
67354 ** value in register P3 is not NULL, then this routine is a no-op.
67355 ** The P5 parameter should be 1.
67356 */
67357 case OP_HaltIfNull: {      /* in3 */
67358   pIn3 = &aMem[pOp->p3];
67359   if( (pIn3->flags & MEM_Null)==0 ) break;
67360   /* Fall through into OP_Halt */
67361 }
67362 
67363 /* Opcode:  Halt P1 P2 * P4 P5
67364 **
67365 ** Exit immediately.  All open cursors, etc are closed
67366 ** automatically.
67367 **
67368 ** P1 is the result code returned by sqlite3_exec(), sqlite3_reset(),
67369 ** or sqlite3_finalize().  For a normal halt, this should be SQLITE_OK (0).
67370 ** For errors, it can be some other value.  If P1!=0 then P2 will determine
67371 ** whether or not to rollback the current transaction.  Do not rollback
67372 ** if P2==OE_Fail. Do the rollback if P2==OE_Rollback.  If P2==OE_Abort,
67373 ** then back out all changes that have occurred during this execution of the
67374 ** VDBE, but do not rollback the transaction. 
67375 **
67376 ** If P4 is not null then it is an error message string.
67377 **
67378 ** P5 is a value between 0 and 4, inclusive, that modifies the P4 string.
67379 **
67380 **    0:  (no change)
67381 **    1:  NOT NULL contraint failed: P4
67382 **    2:  UNIQUE constraint failed: P4
67383 **    3:  CHECK constraint failed: P4
67384 **    4:  FOREIGN KEY constraint failed: P4
67385 **
67386 ** If P5 is not zero and P4 is NULL, then everything after the ":" is
67387 ** omitted.
67388 **
67389 ** There is an implied "Halt 0 0 0" instruction inserted at the very end of
67390 ** every program.  So a jump past the last instruction of the program
67391 ** is the same as executing Halt.
67392 */
67393 case OP_Halt: {
67394 #if 0  /* local variables moved into u.ab */
67395   const char *zType;
67396   const char *zLogFmt;
67397 #endif /* local variables moved into u.ab */
67398 
67399   if( pOp->p1==SQLITE_OK && p->pFrame ){
67400     /* Halt the sub-program. Return control to the parent frame. */
67401     VdbeFrame *pFrame = p->pFrame;
67402     p->pFrame = pFrame->pParent;
67403     p->nFrame--;
67404     sqlite3VdbeSetChanges(db, p->nChange);
67405     pc = sqlite3VdbeFrameRestore(pFrame);
67406     lastRowid = db->lastRowid;
67407     if( pOp->p2==OE_Ignore ){
67408       /* Instruction pc is the OP_Program that invoked the sub-program
67409       ** currently being halted. If the p2 instruction of this OP_Halt
67410       ** instruction is set to OE_Ignore, then the sub-program is throwing
67411       ** an IGNORE exception. In this case jump to the address specified
67412       ** as the p2 of the calling OP_Program.  */
67413       pc = p->aOp[pc].p2-1;
67414     }
67415     aOp = p->aOp;
67416     aMem = p->aMem;
67417     break;
67418   }
67419   p->rc = pOp->p1;
67420   p->errorAction = (u8)pOp->p2;
67421   p->pc = pc;
67422   if( p->rc ){
67423     if( pOp->p5 ){
67424       static const char * const azType[] = { "NOT NULL", "UNIQUE", "CHECK",
67425                                              "FOREIGN KEY" };
67426       assert( pOp->p5>=1 && pOp->p5<=4 );
67427       testcase( pOp->p5==1 );
67428       testcase( pOp->p5==2 );
67429       testcase( pOp->p5==3 );
67430       testcase( pOp->p5==4 );
67431       u.ab.zType = azType[pOp->p5-1];
67432     }else{
67433       u.ab.zType = 0;
67434     }
67435     assert( u.ab.zType!=0 || pOp->p4.z!=0 );
67436     u.ab.zLogFmt = "abort at %d in [%s]: %s";
67437     if( u.ab.zType && pOp->p4.z ){
67438       sqlite3SetString(&p->zErrMsg, db, "%s constraint failed: %s",
67439                        u.ab.zType, pOp->p4.z);
67440     }else if( pOp->p4.z ){
67441       sqlite3SetString(&p->zErrMsg, db, "%s", pOp->p4.z);
67442     }else{
67443       sqlite3SetString(&p->zErrMsg, db, "%s constraint failed", u.ab.zType);
67444     }
67445     sqlite3_log(pOp->p1, u.ab.zLogFmt, pc, p->zSql, p->zErrMsg);
67446   }
67447   rc = sqlite3VdbeHalt(p);
67448   assert( rc==SQLITE_BUSY || rc==SQLITE_OK || rc==SQLITE_ERROR );
67449   if( rc==SQLITE_BUSY ){
67450     p->rc = rc = SQLITE_BUSY;
67451   }else{
67452     assert( rc==SQLITE_OK || (p->rc&0xff)==SQLITE_CONSTRAINT );
67453     assert( rc==SQLITE_OK || db->nDeferredCons>0 || db->nDeferredImmCons>0 );
67454     rc = p->rc ? SQLITE_ERROR : SQLITE_DONE;
67455   }
67456   goto vdbe_return;
67457 }
67458 
67459 /* Opcode: Integer P1 P2 * * *
67460 ** Synopsis: r[P2]=P1
67461 **
67462 ** The 32-bit integer value P1 is written into register P2.
67463 */
67464 case OP_Integer: {         /* out2-prerelease */
67465   pOut->u.i = pOp->p1;
67466   break;
67467 }
67468 
67469 /* Opcode: Int64 * P2 * P4 *
67470 ** Synopsis: r[P2]=P4
67471 **
67472 ** P4 is a pointer to a 64-bit integer value.
67473 ** Write that value into register P2.
67474 */
67475 case OP_Int64: {           /* out2-prerelease */
67476   assert( pOp->p4.pI64!=0 );
67477   pOut->u.i = *pOp->p4.pI64;
67478   break;
67479 }
67480 
67481 #ifndef SQLITE_OMIT_FLOATING_POINT
67482 /* Opcode: Real * P2 * P4 *
67483 ** Synopsis: r[P2]=P4
67484 **
67485 ** P4 is a pointer to a 64-bit floating point value.
67486 ** Write that value into register P2.
67487 */
67488 case OP_Real: {            /* same as TK_FLOAT, out2-prerelease */
67489   pOut->flags = MEM_Real;
67490   assert( !sqlite3IsNaN(*pOp->p4.pReal) );
67491   pOut->r = *pOp->p4.pReal;
67492   break;
67493 }
67494 #endif
67495 
67496 /* Opcode: String8 * P2 * P4 *
67497 ** Synopsis: r[P2]='P4'
67498 **
67499 ** P4 points to a nul terminated UTF-8 string. This opcode is transformed 
67500 ** into an OP_String before it is executed for the first time.
67501 */
67502 case OP_String8: {         /* same as TK_STRING, out2-prerelease */
67503   assert( pOp->p4.z!=0 );
67504   pOp->opcode = OP_String;
67505   pOp->p1 = sqlite3Strlen30(pOp->p4.z);
67506 
67507 #ifndef SQLITE_OMIT_UTF16
67508   if( encoding!=SQLITE_UTF8 ){
67509     rc = sqlite3VdbeMemSetStr(pOut, pOp->p4.z, -1, SQLITE_UTF8, SQLITE_STATIC);
67510     if( rc==SQLITE_TOOBIG ) goto too_big;
67511     if( SQLITE_OK!=sqlite3VdbeChangeEncoding(pOut, encoding) ) goto no_mem;
67512     assert( pOut->zMalloc==pOut->z );
67513     assert( pOut->flags & MEM_Dyn );
67514     pOut->zMalloc = 0;
67515     pOut->flags |= MEM_Static;
67516     pOut->flags &= ~MEM_Dyn;
67517     if( pOp->p4type==P4_DYNAMIC ){
67518       sqlite3DbFree(db, pOp->p4.z);
67519     }
67520     pOp->p4type = P4_DYNAMIC;
67521     pOp->p4.z = pOut->z;
67522     pOp->p1 = pOut->n;
67523   }
67524 #endif
67525   if( pOp->p1>db->aLimit[SQLITE_LIMIT_LENGTH] ){
67526     goto too_big;
67527   }
67528   /* Fall through to the next case, OP_String */
67529 }
67530   
67531 /* Opcode: String P1 P2 * P4 *
67532 ** Synopsis: r[P2]='P4' (len=P1)
67533 **
67534 ** The string value P4 of length P1 (bytes) is stored in register P2.
67535 */
67536 case OP_String: {          /* out2-prerelease */
67537   assert( pOp->p4.z!=0 );
67538   pOut->flags = MEM_Str|MEM_Static|MEM_Term;
67539   pOut->z = pOp->p4.z;
67540   pOut->n = pOp->p1;
67541   pOut->enc = encoding;
67542   UPDATE_MAX_BLOBSIZE(pOut);
67543   break;
67544 }
67545 
67546 /* Opcode: Null P1 P2 P3 * *
67547 ** Synopsis:  r[P2..P3]=NULL
67548 **
67549 ** Write a NULL into registers P2.  If P3 greater than P2, then also write
67550 ** NULL into register P3 and every register in between P2 and P3.  If P3
67551 ** is less than P2 (typically P3 is zero) then only register P2 is
67552 ** set to NULL.
67553 **
67554 ** If the P1 value is non-zero, then also set the MEM_Cleared flag so that
67555 ** NULL values will not compare equal even if SQLITE_NULLEQ is set on
67556 ** OP_Ne or OP_Eq.
67557 */
67558 case OP_Null: {           /* out2-prerelease */
67559 #if 0  /* local variables moved into u.ac */
67560   int cnt;
67561   u16 nullFlag;
67562 #endif /* local variables moved into u.ac */
67563   u.ac.cnt = pOp->p3-pOp->p2;
67564   assert( pOp->p3<=(p->nMem-p->nCursor) );
67565   pOut->flags = u.ac.nullFlag = pOp->p1 ? (MEM_Null|MEM_Cleared) : MEM_Null;
67566   while( u.ac.cnt>0 ){
67567     pOut++;
67568     memAboutToChange(p, pOut);
67569     VdbeMemRelease(pOut);
67570     pOut->flags = u.ac.nullFlag;
67571     u.ac.cnt--;
67572   }
67573   break;
67574 }
67575 
67576 
67577 /* Opcode: Blob P1 P2 * P4
67578 ** Synopsis: r[P2]=P4 (len=P1)
67579 **
67580 ** P4 points to a blob of data P1 bytes long.  Store this
67581 ** blob in register P2.
67582 */
67583 case OP_Blob: {                /* out2-prerelease */
67584   assert( pOp->p1 <= SQLITE_MAX_LENGTH );
67585   sqlite3VdbeMemSetStr(pOut, pOp->p4.z, pOp->p1, 0, 0);
67586   pOut->enc = encoding;
67587   UPDATE_MAX_BLOBSIZE(pOut);
67588   break;
67589 }
67590 
67591 /* Opcode: Variable P1 P2 * P4 *
67592 ** Synopsis: r[P2]=parameter(P1,P4)
67593 **
67594 ** Transfer the values of bound parameter P1 into register P2
67595 **
67596 ** If the parameter is named, then its name appears in P4 and P3==1.
67597 ** The P4 value is used by sqlite3_bind_parameter_name().
67598 */
67599 case OP_Variable: {            /* out2-prerelease */
67600 #if 0  /* local variables moved into u.ad */
67601   Mem *pVar;       /* Value being transferred */
67602 #endif /* local variables moved into u.ad */
67603 
67604   assert( pOp->p1>0 && pOp->p1<=p->nVar );
67605   assert( pOp->p4.z==0 || pOp->p4.z==p->azVar[pOp->p1-1] );
67606   u.ad.pVar = &p->aVar[pOp->p1 - 1];
67607   if( sqlite3VdbeMemTooBig(u.ad.pVar) ){
67608     goto too_big;
67609   }
67610   sqlite3VdbeMemShallowCopy(pOut, u.ad.pVar, MEM_Static);
67611   UPDATE_MAX_BLOBSIZE(pOut);
67612   break;
67613 }
67614 
67615 /* Opcode: Move P1 P2 P3 * *
67616 ** Synopsis:  r[P2@P3]=r[P1@P3]
67617 **
67618 ** Move the values in register P1..P1+P3 over into
67619 ** registers P2..P2+P3.  Registers P1..P1+P3 are
67620 ** left holding a NULL.  It is an error for register ranges
67621 ** P1..P1+P3 and P2..P2+P3 to overlap.
67622 */
67623 case OP_Move: {
67624 #if 0  /* local variables moved into u.ae */
67625   char *zMalloc;   /* Holding variable for allocated memory */
67626   int n;           /* Number of registers left to copy */
67627   int p1;          /* Register to copy from */
67628   int p2;          /* Register to copy to */
67629 #endif /* local variables moved into u.ae */
67630 
67631   u.ae.n = pOp->p3;
67632   u.ae.p1 = pOp->p1;
67633   u.ae.p2 = pOp->p2;
67634   assert( u.ae.n>=0 && u.ae.p1>0 && u.ae.p2>0 );
67635   assert( u.ae.p1+u.ae.n<=u.ae.p2 || u.ae.p2+u.ae.n<=u.ae.p1 );
67636 
67637   pIn1 = &aMem[u.ae.p1];
67638   pOut = &aMem[u.ae.p2];
67639   do{
67640     assert( pOut<=&aMem[(p->nMem-p->nCursor)] );
67641     assert( pIn1<=&aMem[(p->nMem-p->nCursor)] );
67642     assert( memIsValid(pIn1) );
67643     memAboutToChange(p, pOut);
67644     u.ae.zMalloc = pOut->zMalloc;
67645     pOut->zMalloc = 0;
67646     sqlite3VdbeMemMove(pOut, pIn1);
67647 #ifdef SQLITE_DEBUG
67648     if( pOut->pScopyFrom>=&aMem[u.ae.p1] && pOut->pScopyFrom<&aMem[u.ae.p1+pOp->p3] ){
67649       pOut->pScopyFrom += u.ae.p1 - pOp->p2;
67650     }
67651 #endif
67652     pIn1->zMalloc = u.ae.zMalloc;
67653     REGISTER_TRACE(u.ae.p2++, pOut);
67654     pIn1++;
67655     pOut++;
67656   }while( u.ae.n-- );
67657   break;
67658 }
67659 
67660 /* Opcode: Copy P1 P2 P3 * *
67661 ** Synopsis: r[P2@P3]=r[P1@P3]
67662 **
67663 ** Make a copy of registers P1..P1+P3 into registers P2..P2+P3.
67664 **
67665 ** This instruction makes a deep copy of the value.  A duplicate
67666 ** is made of any string or blob constant.  See also OP_SCopy.
67667 */
67668 case OP_Copy: {
67669 #if 0  /* local variables moved into u.af */
67670   int n;
67671 #endif /* local variables moved into u.af */
67672 
67673   u.af.n = pOp->p3;
67674   pIn1 = &aMem[pOp->p1];
67675   pOut = &aMem[pOp->p2];
67676   assert( pOut!=pIn1 );
67677   while( 1 ){
67678     sqlite3VdbeMemShallowCopy(pOut, pIn1, MEM_Ephem);
67679     Deephemeralize(pOut);
67680 #ifdef SQLITE_DEBUG
67681     pOut->pScopyFrom = 0;
67682 #endif
67683     REGISTER_TRACE(pOp->p2+pOp->p3-u.af.n, pOut);
67684     if( (u.af.n--)==0 ) break;
67685     pOut++;
67686     pIn1++;
67687   }
67688   break;
67689 }
67690 
67691 /* Opcode: SCopy P1 P2 * * *
67692 ** Synopsis: r[P2]=r[P1]
67693 **
67694 ** Make a shallow copy of register P1 into register P2.
67695 **
67696 ** This instruction makes a shallow copy of the value.  If the value
67697 ** is a string or blob, then the copy is only a pointer to the
67698 ** original and hence if the original changes so will the copy.
67699 ** Worse, if the original is deallocated, the copy becomes invalid.
67700 ** Thus the program must guarantee that the original will not change
67701 ** during the lifetime of the copy.  Use OP_Copy to make a complete
67702 ** copy.
67703 */
67704 case OP_SCopy: {            /* out2 */
67705   pIn1 = &aMem[pOp->p1];
67706   pOut = &aMem[pOp->p2];
67707   assert( pOut!=pIn1 );
67708   sqlite3VdbeMemShallowCopy(pOut, pIn1, MEM_Ephem);
67709 #ifdef SQLITE_DEBUG
67710   if( pOut->pScopyFrom==0 ) pOut->pScopyFrom = pIn1;
67711 #endif
67712   break;
67713 }
67714 
67715 /* Opcode: ResultRow P1 P2 * * *
67716 ** Synopsis:  output=r[P1@P2]
67717 **
67718 ** The registers P1 through P1+P2-1 contain a single row of
67719 ** results. This opcode causes the sqlite3_step() call to terminate
67720 ** with an SQLITE_ROW return code and it sets up the sqlite3_stmt
67721 ** structure to provide access to the top P1 values as the result
67722 ** row.
67723 */
67724 case OP_ResultRow: {
67725 #if 0  /* local variables moved into u.ag */
67726   Mem *pMem;
67727   int i;
67728 #endif /* local variables moved into u.ag */
67729   assert( p->nResColumn==pOp->p2 );
67730   assert( pOp->p1>0 );
67731   assert( pOp->p1+pOp->p2<=(p->nMem-p->nCursor)+1 );
67732 
67733 #ifndef SQLITE_OMIT_PROGRESS_CALLBACK
67734   /* Run the progress counter just before returning.
67735   */
67736   if( db->xProgress!=0
67737    && nVmStep>=nProgressLimit
67738    && db->xProgress(db->pProgressArg)!=0
67739   ){
67740     rc = SQLITE_INTERRUPT;
67741     goto vdbe_error_halt;
67742   }
67743 #endif
67744 
67745   /* If this statement has violated immediate foreign key constraints, do
67746   ** not return the number of rows modified. And do not RELEASE the statement
67747   ** transaction. It needs to be rolled back.  */
67748   if( SQLITE_OK!=(rc = sqlite3VdbeCheckFk(p, 0)) ){
67749     assert( db->flags&SQLITE_CountRows );
67750     assert( p->usesStmtJournal );
67751     break;
67752   }
67753 
67754   /* If the SQLITE_CountRows flag is set in sqlite3.flags mask, then
67755   ** DML statements invoke this opcode to return the number of rows
67756   ** modified to the user. This is the only way that a VM that
67757   ** opens a statement transaction may invoke this opcode.
67758   **
67759   ** In case this is such a statement, close any statement transaction
67760   ** opened by this VM before returning control to the user. This is to
67761   ** ensure that statement-transactions are always nested, not overlapping.
67762   ** If the open statement-transaction is not closed here, then the user
67763   ** may step another VM that opens its own statement transaction. This
67764   ** may lead to overlapping statement transactions.
67765   **
67766   ** The statement transaction is never a top-level transaction.  Hence
67767   ** the RELEASE call below can never fail.
67768   */
67769   assert( p->iStatement==0 || db->flags&SQLITE_CountRows );
67770   rc = sqlite3VdbeCloseStatement(p, SAVEPOINT_RELEASE);
67771   if( NEVER(rc!=SQLITE_OK) ){
67772     break;
67773   }
67774 
67775   /* Invalidate all ephemeral cursor row caches */
67776   p->cacheCtr = (p->cacheCtr + 2)|1;
67777 
67778   /* Make sure the results of the current row are \000 terminated
67779   ** and have an assigned type.  The results are de-ephemeralized as
67780   ** a side effect.
67781   */
67782   u.ag.pMem = p->pResultSet = &aMem[pOp->p1];
67783   for(u.ag.i=0; u.ag.i<pOp->p2; u.ag.i++){
67784     assert( memIsValid(&u.ag.pMem[u.ag.i]) );
67785     Deephemeralize(&u.ag.pMem[u.ag.i]);
67786     assert( (u.ag.pMem[u.ag.i].flags & MEM_Ephem)==0
67787             || (u.ag.pMem[u.ag.i].flags & (MEM_Str|MEM_Blob))==0 );
67788     sqlite3VdbeMemNulTerminate(&u.ag.pMem[u.ag.i]);
67789     sqlite3VdbeMemStoreType(&u.ag.pMem[u.ag.i]);
67790     REGISTER_TRACE(pOp->p1+u.ag.i, &u.ag.pMem[u.ag.i]);
67791   }
67792   if( db->mallocFailed ) goto no_mem;
67793 
67794   /* Return SQLITE_ROW
67795   */
67796   p->pc = pc + 1;
67797   rc = SQLITE_ROW;
67798   goto vdbe_return;
67799 }
67800 
67801 /* Opcode: Concat P1 P2 P3 * *
67802 ** Synopsis: r[P3]=r[P2]+r[P1]
67803 **
67804 ** Add the text in register P1 onto the end of the text in
67805 ** register P2 and store the result in register P3.
67806 ** If either the P1 or P2 text are NULL then store NULL in P3.
67807 **
67808 **   P3 = P2 || P1
67809 **
67810 ** It is illegal for P1 and P3 to be the same register. Sometimes,
67811 ** if P3 is the same register as P2, the implementation is able
67812 ** to avoid a memcpy().
67813 */
67814 case OP_Concat: {           /* same as TK_CONCAT, in1, in2, out3 */
67815 #if 0  /* local variables moved into u.ah */
67816   i64 nByte;
67817 #endif /* local variables moved into u.ah */
67818 
67819   pIn1 = &aMem[pOp->p1];
67820   pIn2 = &aMem[pOp->p2];
67821   pOut = &aMem[pOp->p3];
67822   assert( pIn1!=pOut );
67823   if( (pIn1->flags | pIn2->flags) & MEM_Null ){
67824     sqlite3VdbeMemSetNull(pOut);
67825     break;
67826   }
67827   if( ExpandBlob(pIn1) || ExpandBlob(pIn2) ) goto no_mem;
67828   Stringify(pIn1, encoding);
67829   Stringify(pIn2, encoding);
67830   u.ah.nByte = pIn1->n + pIn2->n;
67831   if( u.ah.nByte>db->aLimit[SQLITE_LIMIT_LENGTH] ){
67832     goto too_big;
67833   }
67834   MemSetTypeFlag(pOut, MEM_Str);
67835   if( sqlite3VdbeMemGrow(pOut, (int)u.ah.nByte+2, pOut==pIn2) ){
67836     goto no_mem;
67837   }
67838   if( pOut!=pIn2 ){
67839     memcpy(pOut->z, pIn2->z, pIn2->n);
67840   }
67841   memcpy(&pOut->z[pIn2->n], pIn1->z, pIn1->n);
67842   pOut->z[u.ah.nByte]=0;
67843   pOut->z[u.ah.nByte+1] = 0;
67844   pOut->flags |= MEM_Term;
67845   pOut->n = (int)u.ah.nByte;
67846   pOut->enc = encoding;
67847   UPDATE_MAX_BLOBSIZE(pOut);
67848   break;
67849 }
67850 
67851 /* Opcode: Add P1 P2 P3 * *
67852 ** Synopsis:  r[P3]=r[P1]+r[P2]
67853 **
67854 ** Add the value in register P1 to the value in register P2
67855 ** and store the result in register P3.
67856 ** If either input is NULL, the result is NULL.
67857 */
67858 /* Opcode: Multiply P1 P2 P3 * *
67859 ** Synopsis:  r[P3]=r[P1]*r[P2]
67860 **
67861 **
67862 ** Multiply the value in register P1 by the value in register P2
67863 ** and store the result in register P3.
67864 ** If either input is NULL, the result is NULL.
67865 */
67866 /* Opcode: Subtract P1 P2 P3 * *
67867 ** Synopsis:  r[P3]=r[P2]-r[P1]
67868 **
67869 ** Subtract the value in register P1 from the value in register P2
67870 ** and store the result in register P3.
67871 ** If either input is NULL, the result is NULL.
67872 */
67873 /* Opcode: Divide P1 P2 P3 * *
67874 ** Synopsis:  r[P3]=r[P2]/r[P1]
67875 **
67876 ** Divide the value in register P1 by the value in register P2
67877 ** and store the result in register P3 (P3=P2/P1). If the value in 
67878 ** register P1 is zero, then the result is NULL. If either input is 
67879 ** NULL, the result is NULL.
67880 */
67881 /* Opcode: Remainder P1 P2 P3 * *
67882 ** Synopsis:  r[P3]=r[P2]%r[P1]
67883 **
67884 ** Compute the remainder after integer register P2 is divided by 
67885 ** register P1 and store the result in register P3. 
67886 ** If the value in register P1 is zero the result is NULL.
67887 ** If either operand is NULL, the result is NULL.
67888 */
67889 case OP_Add:                   /* same as TK_PLUS, in1, in2, out3 */
67890 case OP_Subtract:              /* same as TK_MINUS, in1, in2, out3 */
67891 case OP_Multiply:              /* same as TK_STAR, in1, in2, out3 */
67892 case OP_Divide:                /* same as TK_SLASH, in1, in2, out3 */
67893 case OP_Remainder: {           /* same as TK_REM, in1, in2, out3 */
67894 #if 0  /* local variables moved into u.ai */
67895   char bIntint;   /* Started out as two integer operands */
67896   int flags;      /* Combined MEM_* flags from both inputs */
67897   i64 iA;         /* Integer value of left operand */
67898   i64 iB;         /* Integer value of right operand */
67899   double rA;      /* Real value of left operand */
67900   double rB;      /* Real value of right operand */
67901 #endif /* local variables moved into u.ai */
67902 
67903   pIn1 = &aMem[pOp->p1];
67904   applyNumericAffinity(pIn1);
67905   pIn2 = &aMem[pOp->p2];
67906   applyNumericAffinity(pIn2);
67907   pOut = &aMem[pOp->p3];
67908   u.ai.flags = pIn1->flags | pIn2->flags;
67909   if( (u.ai.flags & MEM_Null)!=0 ) goto arithmetic_result_is_null;
67910   if( (pIn1->flags & pIn2->flags & MEM_Int)==MEM_Int ){
67911     u.ai.iA = pIn1->u.i;
67912     u.ai.iB = pIn2->u.i;
67913     u.ai.bIntint = 1;
67914     switch( pOp->opcode ){
67915       case OP_Add:       if( sqlite3AddInt64(&u.ai.iB,u.ai.iA) ) goto fp_math;  break;
67916       case OP_Subtract:  if( sqlite3SubInt64(&u.ai.iB,u.ai.iA) ) goto fp_math;  break;
67917       case OP_Multiply:  if( sqlite3MulInt64(&u.ai.iB,u.ai.iA) ) goto fp_math;  break;
67918       case OP_Divide: {
67919         if( u.ai.iA==0 ) goto arithmetic_result_is_null;
67920         if( u.ai.iA==-1 && u.ai.iB==SMALLEST_INT64 ) goto fp_math;
67921         u.ai.iB /= u.ai.iA;
67922         break;
67923       }
67924       default: {
67925         if( u.ai.iA==0 ) goto arithmetic_result_is_null;
67926         if( u.ai.iA==-1 ) u.ai.iA = 1;
67927         u.ai.iB %= u.ai.iA;
67928         break;
67929       }
67930     }
67931     pOut->u.i = u.ai.iB;
67932     MemSetTypeFlag(pOut, MEM_Int);
67933   }else{
67934     u.ai.bIntint = 0;
67935 fp_math:
67936     u.ai.rA = sqlite3VdbeRealValue(pIn1);
67937     u.ai.rB = sqlite3VdbeRealValue(pIn2);
67938     switch( pOp->opcode ){
67939       case OP_Add:         u.ai.rB += u.ai.rA;       break;
67940       case OP_Subtract:    u.ai.rB -= u.ai.rA;       break;
67941       case OP_Multiply:    u.ai.rB *= u.ai.rA;       break;
67942       case OP_Divide: {
67943         /* (double)0 In case of SQLITE_OMIT_FLOATING_POINT... */
67944         if( u.ai.rA==(double)0 ) goto arithmetic_result_is_null;
67945         u.ai.rB /= u.ai.rA;
67946         break;
67947       }
67948       default: {
67949         u.ai.iA = (i64)u.ai.rA;
67950         u.ai.iB = (i64)u.ai.rB;
67951         if( u.ai.iA==0 ) goto arithmetic_result_is_null;
67952         if( u.ai.iA==-1 ) u.ai.iA = 1;
67953         u.ai.rB = (double)(u.ai.iB % u.ai.iA);
67954         break;
67955       }
67956     }
67957 #ifdef SQLITE_OMIT_FLOATING_POINT
67958     pOut->u.i = u.ai.rB;
67959     MemSetTypeFlag(pOut, MEM_Int);
67960 #else
67961     if( sqlite3IsNaN(u.ai.rB) ){
67962       goto arithmetic_result_is_null;
67963     }
67964     pOut->r = u.ai.rB;
67965     MemSetTypeFlag(pOut, MEM_Real);
67966     if( (u.ai.flags & MEM_Real)==0 && !u.ai.bIntint ){
67967       sqlite3VdbeIntegerAffinity(pOut);
67968     }
67969 #endif
67970   }
67971   break;
67972 
67973 arithmetic_result_is_null:
67974   sqlite3VdbeMemSetNull(pOut);
67975   break;
67976 }
67977 
67978 /* Opcode: CollSeq P1 * * P4
67979 **
67980 ** P4 is a pointer to a CollSeq struct. If the next call to a user function
67981 ** or aggregate calls sqlite3GetFuncCollSeq(), this collation sequence will
67982 ** be returned. This is used by the built-in min(), max() and nullif()
67983 ** functions.
67984 **
67985 ** If P1 is not zero, then it is a register that a subsequent min() or
67986 ** max() aggregate will set to 1 if the current row is not the minimum or
67987 ** maximum.  The P1 register is initialized to 0 by this instruction.
67988 **
67989 ** The interface used by the implementation of the aforementioned functions
67990 ** to retrieve the collation sequence set by this opcode is not available
67991 ** publicly, only to user functions defined in func.c.
67992 */
67993 case OP_CollSeq: {
67994   assert( pOp->p4type==P4_COLLSEQ );
67995   if( pOp->p1 ){
67996     sqlite3VdbeMemSetInt64(&aMem[pOp->p1], 0);
67997   }
67998   break;
67999 }
68000 
68001 /* Opcode: Function P1 P2 P3 P4 P5
68002 ** Synopsis: r[P3]=func(r[P2@P5])
68003 **
68004 ** Invoke a user function (P4 is a pointer to a Function structure that
68005 ** defines the function) with P5 arguments taken from register P2 and
68006 ** successors.  The result of the function is stored in register P3.
68007 ** Register P3 must not be one of the function inputs.
68008 **
68009 ** P1 is a 32-bit bitmask indicating whether or not each argument to the 
68010 ** function was determined to be constant at compile time. If the first
68011 ** argument was constant then bit 0 of P1 is set. This is used to determine
68012 ** whether meta data associated with a user function argument using the
68013 ** sqlite3_set_auxdata() API may be safely retained until the next
68014 ** invocation of this opcode.
68015 **
68016 ** See also: AggStep and AggFinal
68017 */
68018 case OP_Function: {
68019 #if 0  /* local variables moved into u.aj */
68020   int i;
68021   Mem *pArg;
68022   sqlite3_context ctx;
68023   sqlite3_value **apVal;
68024   int n;
68025 #endif /* local variables moved into u.aj */
68026 
68027   u.aj.n = pOp->p5;
68028   u.aj.apVal = p->apArg;
68029   assert( u.aj.apVal || u.aj.n==0 );
68030   assert( pOp->p3>0 && pOp->p3<=(p->nMem-p->nCursor) );
68031   pOut = &aMem[pOp->p3];
68032   memAboutToChange(p, pOut);
68033 
68034   assert( u.aj.n==0 || (pOp->p2>0 && pOp->p2+u.aj.n<=(p->nMem-p->nCursor)+1) );
68035   assert( pOp->p3<pOp->p2 || pOp->p3>=pOp->p2+u.aj.n );
68036   u.aj.pArg = &aMem[pOp->p2];
68037   for(u.aj.i=0; u.aj.i<u.aj.n; u.aj.i++, u.aj.pArg++){
68038     assert( memIsValid(u.aj.pArg) );
68039     u.aj.apVal[u.aj.i] = u.aj.pArg;
68040     Deephemeralize(u.aj.pArg);
68041     sqlite3VdbeMemStoreType(u.aj.pArg);
68042     REGISTER_TRACE(pOp->p2+u.aj.i, u.aj.pArg);
68043   }
68044 
68045   assert( pOp->p4type==P4_FUNCDEF );
68046   u.aj.ctx.pFunc = pOp->p4.pFunc;
68047   u.aj.ctx.iOp = pc;
68048   u.aj.ctx.pVdbe = p;
68049 
68050   /* The output cell may already have a buffer allocated. Move
68051   ** the pointer to u.aj.ctx.s so in case the user-function can use
68052   ** the already allocated buffer instead of allocating a new one.
68053   */
68054   memcpy(&u.aj.ctx.s, pOut, sizeof(Mem));
68055   pOut->flags = MEM_Null;
68056   pOut->xDel = 0;
68057   pOut->zMalloc = 0;
68058   MemSetTypeFlag(&u.aj.ctx.s, MEM_Null);
68059 
68060   u.aj.ctx.fErrorOrAux = 0;
68061   if( u.aj.ctx.pFunc->funcFlags & SQLITE_FUNC_NEEDCOLL ){
68062     assert( pOp>aOp );
68063     assert( pOp[-1].p4type==P4_COLLSEQ );
68064     assert( pOp[-1].opcode==OP_CollSeq );
68065     u.aj.ctx.pColl = pOp[-1].p4.pColl;
68066   }
68067   db->lastRowid = lastRowid;
68068   (*u.aj.ctx.pFunc->xFunc)(&u.aj.ctx, u.aj.n, u.aj.apVal); /* IMP: R-24505-23230 */
68069   lastRowid = db->lastRowid;
68070 
68071   if( db->mallocFailed ){
68072     /* Even though a malloc() has failed, the implementation of the
68073     ** user function may have called an sqlite3_result_XXX() function
68074     ** to return a value. The following call releases any resources
68075     ** associated with such a value.
68076     */
68077     sqlite3VdbeMemRelease(&u.aj.ctx.s);
68078     goto no_mem;
68079   }
68080 
68081   /* If the function returned an error, throw an exception */
68082   if( u.aj.ctx.fErrorOrAux ){
68083     if( u.aj.ctx.isError ){
68084       sqlite3SetString(&p->zErrMsg, db, "%s", sqlite3_value_text(&u.aj.ctx.s));
68085       rc = u.aj.ctx.isError;
68086     }
68087     sqlite3VdbeDeleteAuxData(p, pc, pOp->p1);
68088   }
68089 
68090   /* Copy the result of the function into register P3 */
68091   sqlite3VdbeChangeEncoding(&u.aj.ctx.s, encoding);
68092   assert( pOut->flags==MEM_Null );
68093   memcpy(pOut, &u.aj.ctx.s, sizeof(Mem));
68094   if( sqlite3VdbeMemTooBig(pOut) ){
68095     goto too_big;
68096   }
68097 
68098 #if 0
68099   /* The app-defined function has done something that as caused this
68100   ** statement to expire.  (Perhaps the function called sqlite3_exec()
68101   ** with a CREATE TABLE statement.)
68102   */
68103   if( p->expired ) rc = SQLITE_ABORT;
68104 #endif
68105 
68106   REGISTER_TRACE(pOp->p3, pOut);
68107   UPDATE_MAX_BLOBSIZE(pOut);
68108   break;
68109 }
68110 
68111 /* Opcode: BitAnd P1 P2 P3 * *
68112 ** Synopsis:  r[P3]=r[P1]&r[P2]
68113 **
68114 ** Take the bit-wise AND of the values in register P1 and P2 and
68115 ** store the result in register P3.
68116 ** If either input is NULL, the result is NULL.
68117 */
68118 /* Opcode: BitOr P1 P2 P3 * *
68119 ** Synopsis:  r[P3]=r[P1]|r[P2]
68120 **
68121 ** Take the bit-wise OR of the values in register P1 and P2 and
68122 ** store the result in register P3.
68123 ** If either input is NULL, the result is NULL.
68124 */
68125 /* Opcode: ShiftLeft P1 P2 P3 * *
68126 ** Synopsis:  r[P3]=r[P2]<<r[P1]
68127 **
68128 ** Shift the integer value in register P2 to the left by the
68129 ** number of bits specified by the integer in register P1.
68130 ** Store the result in register P3.
68131 ** If either input is NULL, the result is NULL.
68132 */
68133 /* Opcode: ShiftRight P1 P2 P3 * *
68134 ** Synopsis:  r[P3]=r[P2]>>r[P1]
68135 **
68136 ** Shift the integer value in register P2 to the right by the
68137 ** number of bits specified by the integer in register P1.
68138 ** Store the result in register P3.
68139 ** If either input is NULL, the result is NULL.
68140 */
68141 case OP_BitAnd:                 /* same as TK_BITAND, in1, in2, out3 */
68142 case OP_BitOr:                  /* same as TK_BITOR, in1, in2, out3 */
68143 case OP_ShiftLeft:              /* same as TK_LSHIFT, in1, in2, out3 */
68144 case OP_ShiftRight: {           /* same as TK_RSHIFT, in1, in2, out3 */
68145 #if 0  /* local variables moved into u.ak */
68146   i64 iA;
68147   u64 uA;
68148   i64 iB;
68149   u8 op;
68150 #endif /* local variables moved into u.ak */
68151 
68152   pIn1 = &aMem[pOp->p1];
68153   pIn2 = &aMem[pOp->p2];
68154   pOut = &aMem[pOp->p3];
68155   if( (pIn1->flags | pIn2->flags) & MEM_Null ){
68156     sqlite3VdbeMemSetNull(pOut);
68157     break;
68158   }
68159   u.ak.iA = sqlite3VdbeIntValue(pIn2);
68160   u.ak.iB = sqlite3VdbeIntValue(pIn1);
68161   u.ak.op = pOp->opcode;
68162   if( u.ak.op==OP_BitAnd ){
68163     u.ak.iA &= u.ak.iB;
68164   }else if( u.ak.op==OP_BitOr ){
68165     u.ak.iA |= u.ak.iB;
68166   }else if( u.ak.iB!=0 ){
68167     assert( u.ak.op==OP_ShiftRight || u.ak.op==OP_ShiftLeft );
68168 
68169     /* If shifting by a negative amount, shift in the other direction */
68170     if( u.ak.iB<0 ){
68171       assert( OP_ShiftRight==OP_ShiftLeft+1 );
68172       u.ak.op = 2*OP_ShiftLeft + 1 - u.ak.op;
68173       u.ak.iB = u.ak.iB>(-64) ? -u.ak.iB : 64;
68174     }
68175 
68176     if( u.ak.iB>=64 ){
68177       u.ak.iA = (u.ak.iA>=0 || u.ak.op==OP_ShiftLeft) ? 0 : -1;
68178     }else{
68179       memcpy(&u.ak.uA, &u.ak.iA, sizeof(u.ak.uA));
68180       if( u.ak.op==OP_ShiftLeft ){
68181         u.ak.uA <<= u.ak.iB;
68182       }else{
68183         u.ak.uA >>= u.ak.iB;
68184         /* Sign-extend on a right shift of a negative number */
68185         if( u.ak.iA<0 ) u.ak.uA |= ((((u64)0xffffffff)<<32)|0xffffffff) << (64-u.ak.iB);
68186       }
68187       memcpy(&u.ak.iA, &u.ak.uA, sizeof(u.ak.iA));
68188     }
68189   }
68190   pOut->u.i = u.ak.iA;
68191   MemSetTypeFlag(pOut, MEM_Int);
68192   break;
68193 }
68194 
68195 /* Opcode: AddImm  P1 P2 * * *
68196 ** Synopsis:  r[P1]=r[P1]+P2
68197 ** 
68198 ** Add the constant P2 to the value in register P1.
68199 ** The result is always an integer.
68200 **
68201 ** To force any register to be an integer, just add 0.
68202 */
68203 case OP_AddImm: {            /* in1 */
68204   pIn1 = &aMem[pOp->p1];
68205   memAboutToChange(p, pIn1);
68206   sqlite3VdbeMemIntegerify(pIn1);
68207   pIn1->u.i += pOp->p2;
68208   break;
68209 }
68210 
68211 /* Opcode: MustBeInt P1 P2 * * *
68212 ** 
68213 ** Force the value in register P1 to be an integer.  If the value
68214 ** in P1 is not an integer and cannot be converted into an integer
68215 ** without data loss, then jump immediately to P2, or if P2==0
68216 ** raise an SQLITE_MISMATCH exception.
68217 */
68218 case OP_MustBeInt: {            /* jump, in1 */
68219   pIn1 = &aMem[pOp->p1];
68220   if( (pIn1->flags & MEM_Int)==0 ){
68221     applyAffinity(pIn1, SQLITE_AFF_NUMERIC, encoding);
68222     if( (pIn1->flags & MEM_Int)==0 ){
68223       if( pOp->p2==0 ){
68224         rc = SQLITE_MISMATCH;
68225         goto abort_due_to_error;
68226       }else{
68227         pc = pOp->p2 - 1;
68228         break;
68229       }
68230     }
68231   }
68232   MemSetTypeFlag(pIn1, MEM_Int);
68233   break;
68234 }
68235 
68236 #ifndef SQLITE_OMIT_FLOATING_POINT
68237 /* Opcode: RealAffinity P1 * * * *
68238 **
68239 ** If register P1 holds an integer convert it to a real value.
68240 **
68241 ** This opcode is used when extracting information from a column that
68242 ** has REAL affinity.  Such column values may still be stored as
68243 ** integers, for space efficiency, but after extraction we want them
68244 ** to have only a real value.
68245 */
68246 case OP_RealAffinity: {                  /* in1 */
68247   pIn1 = &aMem[pOp->p1];
68248   if( pIn1->flags & MEM_Int ){
68249     sqlite3VdbeMemRealify(pIn1);
68250   }
68251   break;
68252 }
68253 #endif
68254 
68255 #ifndef SQLITE_OMIT_CAST
68256 /* Opcode: ToText P1 * * * *
68257 **
68258 ** Force the value in register P1 to be text.
68259 ** If the value is numeric, convert it to a string using the
68260 ** equivalent of printf().  Blob values are unchanged and
68261 ** are afterwards simply interpreted as text.
68262 **
68263 ** A NULL value is not changed by this routine.  It remains NULL.
68264 */
68265 case OP_ToText: {                  /* same as TK_TO_TEXT, in1 */
68266   pIn1 = &aMem[pOp->p1];
68267   memAboutToChange(p, pIn1);
68268   if( pIn1->flags & MEM_Null ) break;
68269   assert( MEM_Str==(MEM_Blob>>3) );
68270   pIn1->flags |= (pIn1->flags&MEM_Blob)>>3;
68271   applyAffinity(pIn1, SQLITE_AFF_TEXT, encoding);
68272   rc = ExpandBlob(pIn1);
68273   assert( pIn1->flags & MEM_Str || db->mallocFailed );
68274   pIn1->flags &= ~(MEM_Int|MEM_Real|MEM_Blob|MEM_Zero);
68275   UPDATE_MAX_BLOBSIZE(pIn1);
68276   break;
68277 }
68278 
68279 /* Opcode: ToBlob P1 * * * *
68280 **
68281 ** Force the value in register P1 to be a BLOB.
68282 ** If the value is numeric, convert it to a string first.
68283 ** Strings are simply reinterpreted as blobs with no change
68284 ** to the underlying data.
68285 **
68286 ** A NULL value is not changed by this routine.  It remains NULL.
68287 */
68288 case OP_ToBlob: {                  /* same as TK_TO_BLOB, in1 */
68289   pIn1 = &aMem[pOp->p1];
68290   if( pIn1->flags & MEM_Null ) break;
68291   if( (pIn1->flags & MEM_Blob)==0 ){
68292     applyAffinity(pIn1, SQLITE_AFF_TEXT, encoding);
68293     assert( pIn1->flags & MEM_Str || db->mallocFailed );
68294     MemSetTypeFlag(pIn1, MEM_Blob);
68295   }else{
68296     pIn1->flags &= ~(MEM_TypeMask&~MEM_Blob);
68297   }
68298   UPDATE_MAX_BLOBSIZE(pIn1);
68299   break;
68300 }
68301 
68302 /* Opcode: ToNumeric P1 * * * *
68303 **
68304 ** Force the value in register P1 to be numeric (either an
68305 ** integer or a floating-point number.)
68306 ** If the value is text or blob, try to convert it to an using the
68307 ** equivalent of atoi() or atof() and store 0 if no such conversion 
68308 ** is possible.
68309 **
68310 ** A NULL value is not changed by this routine.  It remains NULL.
68311 */
68312 case OP_ToNumeric: {                  /* same as TK_TO_NUMERIC, in1 */
68313   pIn1 = &aMem[pOp->p1];
68314   sqlite3VdbeMemNumerify(pIn1);
68315   break;
68316 }
68317 #endif /* SQLITE_OMIT_CAST */
68318 
68319 /* Opcode: ToInt P1 * * * *
68320 **
68321 ** Force the value in register P1 to be an integer.  If
68322 ** The value is currently a real number, drop its fractional part.
68323 ** If the value is text or blob, try to convert it to an integer using the
68324 ** equivalent of atoi() and store 0 if no such conversion is possible.
68325 **
68326 ** A NULL value is not changed by this routine.  It remains NULL.
68327 */
68328 case OP_ToInt: {                  /* same as TK_TO_INT, in1 */
68329   pIn1 = &aMem[pOp->p1];
68330   if( (pIn1->flags & MEM_Null)==0 ){
68331     sqlite3VdbeMemIntegerify(pIn1);
68332   }
68333   break;
68334 }
68335 
68336 #if !defined(SQLITE_OMIT_CAST) && !defined(SQLITE_OMIT_FLOATING_POINT)
68337 /* Opcode: ToReal P1 * * * *
68338 **
68339 ** Force the value in register P1 to be a floating point number.
68340 ** If The value is currently an integer, convert it.
68341 ** If the value is text or blob, try to convert it to an integer using the
68342 ** equivalent of atoi() and store 0.0 if no such conversion is possible.
68343 **
68344 ** A NULL value is not changed by this routine.  It remains NULL.
68345 */
68346 case OP_ToReal: {                  /* same as TK_TO_REAL, in1 */
68347   pIn1 = &aMem[pOp->p1];
68348   memAboutToChange(p, pIn1);
68349   if( (pIn1->flags & MEM_Null)==0 ){
68350     sqlite3VdbeMemRealify(pIn1);
68351   }
68352   break;
68353 }
68354 #endif /* !defined(SQLITE_OMIT_CAST) && !defined(SQLITE_OMIT_FLOATING_POINT) */
68355 
68356 /* Opcode: Lt P1 P2 P3 P4 P5
68357 ** Synopsis: if r[P1]<r[P3] goto P2
68358 **
68359 ** Compare the values in register P1 and P3.  If reg(P3)<reg(P1) then
68360 ** jump to address P2.  
68361 **
68362 ** If the SQLITE_JUMPIFNULL bit of P5 is set and either reg(P1) or
68363 ** reg(P3) is NULL then take the jump.  If the SQLITE_JUMPIFNULL 
68364 ** bit is clear then fall through if either operand is NULL.
68365 **
68366 ** The SQLITE_AFF_MASK portion of P5 must be an affinity character -
68367 ** SQLITE_AFF_TEXT, SQLITE_AFF_INTEGER, and so forth. An attempt is made 
68368 ** to coerce both inputs according to this affinity before the
68369 ** comparison is made. If the SQLITE_AFF_MASK is 0x00, then numeric
68370 ** affinity is used. Note that the affinity conversions are stored
68371 ** back into the input registers P1 and P3.  So this opcode can cause
68372 ** persistent changes to registers P1 and P3.
68373 **
68374 ** Once any conversions have taken place, and neither value is NULL, 
68375 ** the values are compared. If both values are blobs then memcmp() is
68376 ** used to determine the results of the comparison.  If both values
68377 ** are text, then the appropriate collating function specified in
68378 ** P4 is  used to do the comparison.  If P4 is not specified then
68379 ** memcmp() is used to compare text string.  If both values are
68380 ** numeric, then a numeric comparison is used. If the two values
68381 ** are of different types, then numbers are considered less than
68382 ** strings and strings are considered less than blobs.
68383 **
68384 ** If the SQLITE_STOREP2 bit of P5 is set, then do not jump.  Instead,
68385 ** store a boolean result (either 0, or 1, or NULL) in register P2.
68386 **
68387 ** If the SQLITE_NULLEQ bit is set in P5, then NULL values are considered
68388 ** equal to one another, provided that they do not have their MEM_Cleared
68389 ** bit set.
68390 */
68391 /* Opcode: Ne P1 P2 P3 P4 P5
68392 ** Synopsis: if r[P1]!=r[P3] goto P2
68393 **
68394 ** This works just like the Lt opcode except that the jump is taken if
68395 ** the operands in registers P1 and P3 are not equal.  See the Lt opcode for
68396 ** additional information.
68397 **
68398 ** If SQLITE_NULLEQ is set in P5 then the result of comparison is always either
68399 ** true or false and is never NULL.  If both operands are NULL then the result
68400 ** of comparison is false.  If either operand is NULL then the result is true.
68401 ** If neither operand is NULL the result is the same as it would be if
68402 ** the SQLITE_NULLEQ flag were omitted from P5.
68403 */
68404 /* Opcode: Eq P1 P2 P3 P4 P5
68405 ** Synopsis: if r[P1]==r[P3] goto P2
68406 **
68407 ** This works just like the Lt opcode except that the jump is taken if
68408 ** the operands in registers P1 and P3 are equal.
68409 ** See the Lt opcode for additional information.
68410 **
68411 ** If SQLITE_NULLEQ is set in P5 then the result of comparison is always either
68412 ** true or false and is never NULL.  If both operands are NULL then the result
68413 ** of comparison is true.  If either operand is NULL then the result is false.
68414 ** If neither operand is NULL the result is the same as it would be if
68415 ** the SQLITE_NULLEQ flag were omitted from P5.
68416 */
68417 /* Opcode: Le P1 P2 P3 P4 P5
68418 ** Synopsis: if r[P1]<=r[P3] goto P2
68419 **
68420 ** This works just like the Lt opcode except that the jump is taken if
68421 ** the content of register P3 is less than or equal to the content of
68422 ** register P1.  See the Lt opcode for additional information.
68423 */
68424 /* Opcode: Gt P1 P2 P3 P4 P5
68425 ** Synopsis: if r[P1]>r[P3] goto P2
68426 **
68427 ** This works just like the Lt opcode except that the jump is taken if
68428 ** the content of register P3 is greater than the content of
68429 ** register P1.  See the Lt opcode for additional information.
68430 */
68431 /* Opcode: Ge P1 P2 P3 P4 P5
68432 ** Synopsis: if r[P1]>=r[P3] goto P2
68433 **
68434 ** This works just like the Lt opcode except that the jump is taken if
68435 ** the content of register P3 is greater than or equal to the content of
68436 ** register P1.  See the Lt opcode for additional information.
68437 */
68438 case OP_Eq:               /* same as TK_EQ, jump, in1, in3 */
68439 case OP_Ne:               /* same as TK_NE, jump, in1, in3 */
68440 case OP_Lt:               /* same as TK_LT, jump, in1, in3 */
68441 case OP_Le:               /* same as TK_LE, jump, in1, in3 */
68442 case OP_Gt:               /* same as TK_GT, jump, in1, in3 */
68443 case OP_Ge: {             /* same as TK_GE, jump, in1, in3 */
68444 #if 0  /* local variables moved into u.al */
68445   int res;            /* Result of the comparison of pIn1 against pIn3 */
68446   char affinity;      /* Affinity to use for comparison */
68447   u16 flags1;         /* Copy of initial value of pIn1->flags */
68448   u16 flags3;         /* Copy of initial value of pIn3->flags */
68449 #endif /* local variables moved into u.al */
68450 
68451   pIn1 = &aMem[pOp->p1];
68452   pIn3 = &aMem[pOp->p3];
68453   u.al.flags1 = pIn1->flags;
68454   u.al.flags3 = pIn3->flags;
68455   if( (u.al.flags1 | u.al.flags3)&MEM_Null ){
68456     /* One or both operands are NULL */
68457     if( pOp->p5 & SQLITE_NULLEQ ){
68458       /* If SQLITE_NULLEQ is set (which will only happen if the operator is
68459       ** OP_Eq or OP_Ne) then take the jump or not depending on whether
68460       ** or not both operands are null.
68461       */
68462       assert( pOp->opcode==OP_Eq || pOp->opcode==OP_Ne );
68463       assert( (u.al.flags1 & MEM_Cleared)==0 );
68464       if( (u.al.flags1&MEM_Null)!=0
68465        && (u.al.flags3&MEM_Null)!=0
68466        && (u.al.flags3&MEM_Cleared)==0
68467       ){
68468         u.al.res = 0;  /* Results are equal */
68469       }else{
68470         u.al.res = 1;  /* Results are not equal */
68471       }
68472     }else{
68473       /* SQLITE_NULLEQ is clear and at least one operand is NULL,
68474       ** then the result is always NULL.
68475       ** The jump is taken if the SQLITE_JUMPIFNULL bit is set.
68476       */
68477       if( pOp->p5 & SQLITE_JUMPIFNULL ){
68478         pc = pOp->p2-1;
68479       }else if( pOp->p5 & SQLITE_STOREP2 ){
68480         pOut = &aMem[pOp->p2];
68481         MemSetTypeFlag(pOut, MEM_Null);
68482         REGISTER_TRACE(pOp->p2, pOut);
68483       }
68484       break;
68485     }
68486   }else{
68487     /* Neither operand is NULL.  Do a comparison. */
68488     u.al.affinity = pOp->p5 & SQLITE_AFF_MASK;
68489     if( u.al.affinity ){
68490       applyAffinity(pIn1, u.al.affinity, encoding);
68491       applyAffinity(pIn3, u.al.affinity, encoding);
68492       if( db->mallocFailed ) goto no_mem;
68493     }
68494 
68495     assert( pOp->p4type==P4_COLLSEQ || pOp->p4.pColl==0 );
68496     ExpandBlob(pIn1);
68497     ExpandBlob(pIn3);
68498     u.al.res = sqlite3MemCompare(pIn3, pIn1, pOp->p4.pColl);
68499   }
68500   switch( pOp->opcode ){
68501     case OP_Eq:    u.al.res = u.al.res==0;     break;
68502     case OP_Ne:    u.al.res = u.al.res!=0;     break;
68503     case OP_Lt:    u.al.res = u.al.res<0;      break;
68504     case OP_Le:    u.al.res = u.al.res<=0;     break;
68505     case OP_Gt:    u.al.res = u.al.res>0;      break;
68506     default:       u.al.res = u.al.res>=0;     break;
68507   }
68508 
68509   if( pOp->p5 & SQLITE_STOREP2 ){
68510     pOut = &aMem[pOp->p2];
68511     memAboutToChange(p, pOut);
68512     MemSetTypeFlag(pOut, MEM_Int);
68513     pOut->u.i = u.al.res;
68514     REGISTER_TRACE(pOp->p2, pOut);
68515   }else if( u.al.res ){
68516     pc = pOp->p2-1;
68517   }
68518 
68519   /* Undo any changes made by applyAffinity() to the input registers. */
68520   pIn1->flags = (pIn1->flags&~MEM_TypeMask) | (u.al.flags1&MEM_TypeMask);
68521   pIn3->flags = (pIn3->flags&~MEM_TypeMask) | (u.al.flags3&MEM_TypeMask);
68522   break;
68523 }
68524 
68525 /* Opcode: Permutation * * * P4 *
68526 **
68527 ** Set the permutation used by the OP_Compare operator to be the array
68528 ** of integers in P4.
68529 **
68530 ** The permutation is only valid until the next OP_Compare that has
68531 ** the OPFLAG_PERMUTE bit set in P5. Typically the OP_Permutation should 
68532 ** occur immediately prior to the OP_Compare.
68533 */
68534 case OP_Permutation: {
68535   assert( pOp->p4type==P4_INTARRAY );
68536   assert( pOp->p4.ai );
68537   aPermute = pOp->p4.ai;
68538   break;
68539 }
68540 
68541 /* Opcode: Compare P1 P2 P3 P4 P5
68542 **
68543 ** Compare two vectors of registers in reg(P1)..reg(P1+P3-1) (call this
68544 ** vector "A") and in reg(P2)..reg(P2+P3-1) ("B").  Save the result of
68545 ** the comparison for use by the next OP_Jump instruct.
68546 **
68547 ** If P5 has the OPFLAG_PERMUTE bit set, then the order of comparison is
68548 ** determined by the most recent OP_Permutation operator.  If the
68549 ** OPFLAG_PERMUTE bit is clear, then register are compared in sequential
68550 ** order.
68551 **
68552 ** P4 is a KeyInfo structure that defines collating sequences and sort
68553 ** orders for the comparison.  The permutation applies to registers
68554 ** only.  The KeyInfo elements are used sequentially.
68555 **
68556 ** The comparison is a sort comparison, so NULLs compare equal,
68557 ** NULLs are less than numbers, numbers are less than strings,
68558 ** and strings are less than blobs.
68559 */
68560 case OP_Compare: {
68561 #if 0  /* local variables moved into u.am */
68562   int n;
68563   int i;
68564   int p1;
68565   int p2;
68566   const KeyInfo *pKeyInfo;
68567   int idx;
68568   CollSeq *pColl;    /* Collating sequence to use on this term */
68569   int bRev;          /* True for DESCENDING sort order */
68570 #endif /* local variables moved into u.am */
68571 
68572   if( (pOp->p5 & OPFLAG_PERMUTE)==0 ) aPermute = 0;
68573   u.am.n = pOp->p3;
68574   u.am.pKeyInfo = pOp->p4.pKeyInfo;
68575   assert( u.am.n>0 );
68576   assert( u.am.pKeyInfo!=0 );
68577   u.am.p1 = pOp->p1;
68578   u.am.p2 = pOp->p2;
68579 #if SQLITE_DEBUG
68580   if( aPermute ){
68581     int k, mx = 0;
68582     for(k=0; k<u.am.n; k++) if( aPermute[k]>mx ) mx = aPermute[k];
68583     assert( u.am.p1>0 && u.am.p1+mx<=(p->nMem-p->nCursor)+1 );
68584     assert( u.am.p2>0 && u.am.p2+mx<=(p->nMem-p->nCursor)+1 );
68585   }else{
68586     assert( u.am.p1>0 && u.am.p1+u.am.n<=(p->nMem-p->nCursor)+1 );
68587     assert( u.am.p2>0 && u.am.p2+u.am.n<=(p->nMem-p->nCursor)+1 );
68588   }
68589 #endif /* SQLITE_DEBUG */
68590   for(u.am.i=0; u.am.i<u.am.n; u.am.i++){
68591     u.am.idx = aPermute ? aPermute[u.am.i] : u.am.i;
68592     assert( memIsValid(&aMem[u.am.p1+u.am.idx]) );
68593     assert( memIsValid(&aMem[u.am.p2+u.am.idx]) );
68594     REGISTER_TRACE(u.am.p1+u.am.idx, &aMem[u.am.p1+u.am.idx]);
68595     REGISTER_TRACE(u.am.p2+u.am.idx, &aMem[u.am.p2+u.am.idx]);
68596     assert( u.am.i<u.am.pKeyInfo->nField );
68597     u.am.pColl = u.am.pKeyInfo->aColl[u.am.i];
68598     u.am.bRev = u.am.pKeyInfo->aSortOrder[u.am.i];
68599     iCompare = sqlite3MemCompare(&aMem[u.am.p1+u.am.idx], &aMem[u.am.p2+u.am.idx], u.am.pColl);
68600     if( iCompare ){
68601       if( u.am.bRev ) iCompare = -iCompare;
68602       break;
68603     }
68604   }
68605   aPermute = 0;
68606   break;
68607 }
68608 
68609 /* Opcode: Jump P1 P2 P3 * *
68610 **
68611 ** Jump to the instruction at address P1, P2, or P3 depending on whether
68612 ** in the most recent OP_Compare instruction the P1 vector was less than
68613 ** equal to, or greater than the P2 vector, respectively.
68614 */
68615 case OP_Jump: {             /* jump */
68616   if( iCompare<0 ){
68617     pc = pOp->p1 - 1;
68618   }else if( iCompare==0 ){
68619     pc = pOp->p2 - 1;
68620   }else{
68621     pc = pOp->p3 - 1;
68622   }
68623   break;
68624 }
68625 
68626 /* Opcode: And P1 P2 P3 * *
68627 ** Synopsis: r[P3]=(r[P1] && r[P2])
68628 **
68629 ** Take the logical AND of the values in registers P1 and P2 and
68630 ** write the result into register P3.
68631 **
68632 ** If either P1 or P2 is 0 (false) then the result is 0 even if
68633 ** the other input is NULL.  A NULL and true or two NULLs give
68634 ** a NULL output.
68635 */
68636 /* Opcode: Or P1 P2 P3 * *
68637 ** Synopsis: r[P3]=(r[P1] || r[P2])
68638 **
68639 ** Take the logical OR of the values in register P1 and P2 and
68640 ** store the answer in register P3.
68641 **
68642 ** If either P1 or P2 is nonzero (true) then the result is 1 (true)
68643 ** even if the other input is NULL.  A NULL and false or two NULLs
68644 ** give a NULL output.
68645 */
68646 case OP_And:              /* same as TK_AND, in1, in2, out3 */
68647 case OP_Or: {             /* same as TK_OR, in1, in2, out3 */
68648 #if 0  /* local variables moved into u.an */
68649   int v1;    /* Left operand:  0==FALSE, 1==TRUE, 2==UNKNOWN or NULL */
68650   int v2;    /* Right operand: 0==FALSE, 1==TRUE, 2==UNKNOWN or NULL */
68651 #endif /* local variables moved into u.an */
68652 
68653   pIn1 = &aMem[pOp->p1];
68654   if( pIn1->flags & MEM_Null ){
68655     u.an.v1 = 2;
68656   }else{
68657     u.an.v1 = sqlite3VdbeIntValue(pIn1)!=0;
68658   }
68659   pIn2 = &aMem[pOp->p2];
68660   if( pIn2->flags & MEM_Null ){
68661     u.an.v2 = 2;
68662   }else{
68663     u.an.v2 = sqlite3VdbeIntValue(pIn2)!=0;
68664   }
68665   if( pOp->opcode==OP_And ){
68666     static const unsigned char and_logic[] = { 0, 0, 0, 0, 1, 2, 0, 2, 2 };
68667     u.an.v1 = and_logic[u.an.v1*3+u.an.v2];
68668   }else{
68669     static const unsigned char or_logic[] = { 0, 1, 2, 1, 1, 1, 2, 1, 2 };
68670     u.an.v1 = or_logic[u.an.v1*3+u.an.v2];
68671   }
68672   pOut = &aMem[pOp->p3];
68673   if( u.an.v1==2 ){
68674     MemSetTypeFlag(pOut, MEM_Null);
68675   }else{
68676     pOut->u.i = u.an.v1;
68677     MemSetTypeFlag(pOut, MEM_Int);
68678   }
68679   break;
68680 }
68681 
68682 /* Opcode: Not P1 P2 * * *
68683 ** Synopsis: r[P2]= !r[P1]
68684 **
68685 ** Interpret the value in register P1 as a boolean value.  Store the
68686 ** boolean complement in register P2.  If the value in register P1 is 
68687 ** NULL, then a NULL is stored in P2.
68688 */
68689 case OP_Not: {                /* same as TK_NOT, in1, out2 */
68690   pIn1 = &aMem[pOp->p1];
68691   pOut = &aMem[pOp->p2];
68692   if( pIn1->flags & MEM_Null ){
68693     sqlite3VdbeMemSetNull(pOut);
68694   }else{
68695     sqlite3VdbeMemSetInt64(pOut, !sqlite3VdbeIntValue(pIn1));
68696   }
68697   break;
68698 }
68699 
68700 /* Opcode: BitNot P1 P2 * * *
68701 ** Synopsis: r[P1]= ~r[P1]
68702 **
68703 ** Interpret the content of register P1 as an integer.  Store the
68704 ** ones-complement of the P1 value into register P2.  If P1 holds
68705 ** a NULL then store a NULL in P2.
68706 */
68707 case OP_BitNot: {             /* same as TK_BITNOT, in1, out2 */
68708   pIn1 = &aMem[pOp->p1];
68709   pOut = &aMem[pOp->p2];
68710   if( pIn1->flags & MEM_Null ){
68711     sqlite3VdbeMemSetNull(pOut);
68712   }else{
68713     sqlite3VdbeMemSetInt64(pOut, ~sqlite3VdbeIntValue(pIn1));
68714   }
68715   break;
68716 }
68717 
68718 /* Opcode: Once P1 P2 * * *
68719 **
68720 ** Check if OP_Once flag P1 is set. If so, jump to instruction P2. Otherwise,
68721 ** set the flag and fall through to the next instruction.
68722 */
68723 case OP_Once: {             /* jump */
68724   assert( pOp->p1<p->nOnceFlag );
68725   if( p->aOnceFlag[pOp->p1] ){
68726     pc = pOp->p2-1;
68727   }else{
68728     p->aOnceFlag[pOp->p1] = 1;
68729   }
68730   break;
68731 }
68732 
68733 /* Opcode: If P1 P2 P3 * *
68734 **
68735 ** Jump to P2 if the value in register P1 is true.  The value
68736 ** is considered true if it is numeric and non-zero.  If the value
68737 ** in P1 is NULL then take the jump if P3 is non-zero.
68738 */
68739 /* Opcode: IfNot P1 P2 P3 * *
68740 **
68741 ** Jump to P2 if the value in register P1 is False.  The value
68742 ** is considered false if it has a numeric value of zero.  If the value
68743 ** in P1 is NULL then take the jump if P3 is zero.
68744 */
68745 case OP_If:                 /* jump, in1 */
68746 case OP_IfNot: {            /* jump, in1 */
68747 #if 0  /* local variables moved into u.ao */
68748   int c;
68749 #endif /* local variables moved into u.ao */
68750   pIn1 = &aMem[pOp->p1];
68751   if( pIn1->flags & MEM_Null ){
68752     u.ao.c = pOp->p3;
68753   }else{
68754 #ifdef SQLITE_OMIT_FLOATING_POINT
68755     u.ao.c = sqlite3VdbeIntValue(pIn1)!=0;
68756 #else
68757     u.ao.c = sqlite3VdbeRealValue(pIn1)!=0.0;
68758 #endif
68759     if( pOp->opcode==OP_IfNot ) u.ao.c = !u.ao.c;
68760   }
68761   if( u.ao.c ){
68762     pc = pOp->p2-1;
68763   }
68764   break;
68765 }
68766 
68767 /* Opcode: IsNull P1 P2 * * *
68768 ** Synopsis:  if r[P1]==NULL goto P2
68769 **
68770 ** Jump to P2 if the value in register P1 is NULL.
68771 */
68772 case OP_IsNull: {            /* same as TK_ISNULL, jump, in1 */
68773   pIn1 = &aMem[pOp->p1];
68774   if( (pIn1->flags & MEM_Null)!=0 ){
68775     pc = pOp->p2 - 1;
68776   }
68777   break;
68778 }
68779 
68780 /* Opcode: NotNull P1 P2 * * *
68781 ** Synopsis: if r[P1]!=NULL goto P2
68782 **
68783 ** Jump to P2 if the value in register P1 is not NULL.  
68784 */
68785 case OP_NotNull: {            /* same as TK_NOTNULL, jump, in1 */
68786   pIn1 = &aMem[pOp->p1];
68787   if( (pIn1->flags & MEM_Null)==0 ){
68788     pc = pOp->p2 - 1;
68789   }
68790   break;
68791 }
68792 
68793 /* Opcode: Column P1 P2 P3 P4 P5
68794 ** Synopsis:  r[P3]=PX
68795 **
68796 ** Interpret the data that cursor P1 points to as a structure built using
68797 ** the MakeRecord instruction.  (See the MakeRecord opcode for additional
68798 ** information about the format of the data.)  Extract the P2-th column
68799 ** from this record.  If there are less that (P2+1) 
68800 ** values in the record, extract a NULL.
68801 **
68802 ** The value extracted is stored in register P3.
68803 **
68804 ** If the column contains fewer than P2 fields, then extract a NULL.  Or,
68805 ** if the P4 argument is a P4_MEM use the value of the P4 argument as
68806 ** the result.
68807 **
68808 ** If the OPFLAG_CLEARCACHE bit is set on P5 and P1 is a pseudo-table cursor,
68809 ** then the cache of the cursor is reset prior to extracting the column.
68810 ** The first OP_Column against a pseudo-table after the value of the content
68811 ** register has changed should have this bit set.
68812 **
68813 ** If the OPFLAG_LENGTHARG and OPFLAG_TYPEOFARG bits are set on P5 when
68814 ** the result is guaranteed to only be used as the argument of a length()
68815 ** or typeof() function, respectively.  The loading of large blobs can be
68816 ** skipped for length() and all content loading can be skipped for typeof().
68817 */
68818 case OP_Column: {
68819 #if 0  /* local variables moved into u.ap */
68820   i64 payloadSize64; /* Number of bytes in the record */
68821   int p2;            /* column number to retrieve */
68822   VdbeCursor *pC;    /* The VDBE cursor */
68823   BtCursor *pCrsr;   /* The BTree cursor */
68824   u32 *aType;        /* aType[i] holds the numeric type of the i-th column */
68825   u32 *aOffset;      /* aOffset[i] is offset to start of data for i-th column */
68826   int len;           /* The length of the serialized data for the column */
68827   int i;             /* Loop counter */
68828   Mem *pDest;        /* Where to write the extracted value */
68829   Mem sMem;          /* For storing the record being decoded */
68830   const u8 *zData;   /* Part of the record being decoded */
68831   const u8 *zHdr;    /* Next unparsed byte of the header */
68832   const u8 *zEndHdr; /* Pointer to first byte after the header */
68833   u32 offset;        /* Offset into the data */
68834   u32 szField;       /* Number of bytes in the content of a field */
68835   u32 avail;         /* Number of bytes of available data */
68836   u32 t;             /* A type code from the record header */
68837   Mem *pReg;         /* PseudoTable input register */
68838 #endif /* local variables moved into u.ap */
68839 
68840   u.ap.p2 = pOp->p2;
68841   assert( pOp->p3>0 && pOp->p3<=(p->nMem-p->nCursor) );
68842   u.ap.pDest = &aMem[pOp->p3];
68843   memAboutToChange(p, u.ap.pDest);
68844   assert( pOp->p1>=0 && pOp->p1<p->nCursor );
68845   u.ap.pC = p->apCsr[pOp->p1];
68846   assert( u.ap.pC!=0 );
68847   assert( u.ap.p2<u.ap.pC->nField );
68848   u.ap.aType = u.ap.pC->aType;
68849   u.ap.aOffset = u.ap.aType + u.ap.pC->nField;
68850 #ifndef SQLITE_OMIT_VIRTUALTABLE
68851   assert( u.ap.pC->pVtabCursor==0 ); /* OP_Column never called on virtual table */
68852 #endif
68853   u.ap.pCrsr = u.ap.pC->pCursor;
68854   assert( u.ap.pCrsr!=0 || u.ap.pC->pseudoTableReg>0 ); /* u.ap.pCrsr NULL on PseudoTables */
68855   assert( u.ap.pCrsr!=0 || u.ap.pC->nullRow );          /* u.ap.pC->nullRow on PseudoTables */
68856 
68857   /* If the cursor cache is stale, bring it up-to-date */
68858   rc = sqlite3VdbeCursorMoveto(u.ap.pC);
68859   if( rc ) goto abort_due_to_error;
68860   if( u.ap.pC->cacheStatus!=p->cacheCtr || (pOp->p5&OPFLAG_CLEARCACHE)!=0 ){
68861     if( u.ap.pC->nullRow ){
68862       if( u.ap.pCrsr==0 ){
68863         assert( u.ap.pC->pseudoTableReg>0 );
68864         u.ap.pReg = &aMem[u.ap.pC->pseudoTableReg];
68865         if( u.ap.pC->multiPseudo ){
68866           sqlite3VdbeMemShallowCopy(u.ap.pDest, u.ap.pReg+u.ap.p2, MEM_Ephem);
68867           Deephemeralize(u.ap.pDest);
68868           goto op_column_out;
68869         }
68870         assert( u.ap.pReg->flags & MEM_Blob );
68871         assert( memIsValid(u.ap.pReg) );
68872         u.ap.pC->payloadSize = u.ap.pC->szRow = u.ap.avail = u.ap.pReg->n;
68873         u.ap.pC->aRow = (u8*)u.ap.pReg->z;
68874       }else{
68875         MemSetTypeFlag(u.ap.pDest, MEM_Null);
68876         goto op_column_out;
68877       }
68878     }else{
68879       assert( u.ap.pCrsr );
68880       if( u.ap.pC->isTable==0 ){
68881         assert( sqlite3BtreeCursorIsValid(u.ap.pCrsr) );
68882         VVA_ONLY(rc =) sqlite3BtreeKeySize(u.ap.pCrsr, &u.ap.payloadSize64);
68883         assert( rc==SQLITE_OK ); /* True because of CursorMoveto() call above */
68884         /* sqlite3BtreeParseCellPtr() uses getVarint32() to extract the
68885         ** payload size, so it is impossible for u.ap.payloadSize64 to be
68886         ** larger than 32 bits. */
68887         assert( (u.ap.payloadSize64 & SQLITE_MAX_U32)==(u64)u.ap.payloadSize64 );
68888         u.ap.pC->aRow = sqlite3BtreeKeyFetch(u.ap.pCrsr, &u.ap.avail);
68889         u.ap.pC->payloadSize = (u32)u.ap.payloadSize64;
68890       }else{
68891         assert( sqlite3BtreeCursorIsValid(u.ap.pCrsr) );
68892         VVA_ONLY(rc =) sqlite3BtreeDataSize(u.ap.pCrsr, &u.ap.pC->payloadSize);
68893         assert( rc==SQLITE_OK );   /* DataSize() cannot fail */
68894         u.ap.pC->aRow = sqlite3BtreeDataFetch(u.ap.pCrsr, &u.ap.avail);
68895       }
68896       assert( u.ap.avail<=65536 );  /* Maximum page size is 64KiB */
68897       if( u.ap.pC->payloadSize <= (u32)u.ap.avail ){
68898         u.ap.pC->szRow = u.ap.pC->payloadSize;
68899       }else{
68900         u.ap.pC->szRow = u.ap.avail;
68901       }
68902       if( u.ap.pC->payloadSize > (u32)db->aLimit[SQLITE_LIMIT_LENGTH] ){
68903         goto too_big;
68904       }
68905     }
68906     u.ap.pC->cacheStatus = p->cacheCtr;
68907     u.ap.pC->iHdrOffset = getVarint32(u.ap.pC->aRow, u.ap.offset);
68908     u.ap.pC->nHdrParsed = 0;
68909     u.ap.aOffset[0] = u.ap.offset;
68910     if( u.ap.avail<u.ap.offset ){
68911       /* u.ap.pC->aRow does not have to hold the entire row, but it does at least
68912       ** need to cover the header of the record.  If u.ap.pC->aRow does not contain
68913       ** the complete header, then set it to zero, forcing the header to be
68914       ** dynamically allocated. */
68915       u.ap.pC->aRow = 0;
68916       u.ap.pC->szRow = 0;
68917     }
68918 
68919     /* Make sure a corrupt database has not given us an oversize header.
68920     ** Do this now to avoid an oversize memory allocation.
68921     **
68922     ** Type entries can be between 1 and 5 bytes each.  But 4 and 5 byte
68923     ** types use so much data space that there can only be 4096 and 32 of
68924     ** them, respectively.  So the maximum header length results from a
68925     ** 3-byte type for each of the maximum of 32768 columns plus three
68926     ** extra bytes for the header length itself.  32768*3 + 3 = 98307.
68927     */
68928     if( u.ap.offset > 98307 || u.ap.offset > u.ap.pC->payloadSize ){
68929       rc = SQLITE_CORRUPT_BKPT;
68930       goto op_column_error;
68931     }
68932   }
68933 
68934   /* Make sure at least the first u.ap.p2+1 entries of the header have been
68935   ** parsed and valid information is in u.ap.aOffset[] and u.ap.aType[].
68936   */
68937   if( u.ap.pC->nHdrParsed<=u.ap.p2 ){
68938     /* If there is more header available for parsing in the record, try
68939     ** to extract additional fields up through the u.ap.p2+1-th field
68940     */
68941     if( u.ap.pC->iHdrOffset<u.ap.aOffset[0] ){
68942       /* Make sure u.ap.zData points to enough of the record to cover the header. */
68943       if( u.ap.pC->aRow==0 ){
68944         memset(&u.ap.sMem, 0, sizeof(u.ap.sMem));
68945         rc = sqlite3VdbeMemFromBtree(u.ap.pCrsr, 0, u.ap.aOffset[0],
68946                                      !u.ap.pC->isTable, &u.ap.sMem);
68947         if( rc!=SQLITE_OK ){
68948           goto op_column_error;
68949         }
68950         u.ap.zData = (u8*)u.ap.sMem.z;
68951       }else{
68952         u.ap.zData = u.ap.pC->aRow;
68953       }
68954 
68955       /* Fill in u.ap.aType[u.ap.i] and u.ap.aOffset[u.ap.i] values through the u.ap.p2-th field. */
68956       u.ap.i = u.ap.pC->nHdrParsed;
68957       u.ap.offset = u.ap.aOffset[u.ap.i];
68958       u.ap.zHdr = u.ap.zData + u.ap.pC->iHdrOffset;
68959       u.ap.zEndHdr = u.ap.zData + u.ap.aOffset[0];
68960       assert( u.ap.i<=u.ap.p2 && u.ap.zHdr<u.ap.zEndHdr );
68961       do{
68962         if( u.ap.zHdr[0]<0x80 ){
68963           u.ap.t = u.ap.zHdr[0];
68964           u.ap.zHdr++;
68965         }else{
68966           u.ap.zHdr += sqlite3GetVarint32(u.ap.zHdr, &u.ap.t);
68967         }
68968         u.ap.aType[u.ap.i] = u.ap.t;
68969         u.ap.szField = sqlite3VdbeSerialTypeLen(u.ap.t);
68970         u.ap.offset += u.ap.szField;
68971         if( u.ap.offset<u.ap.szField ){  /* True if u.ap.offset overflows */
68972           u.ap.zHdr = &u.ap.zEndHdr[1];  /* Forces SQLITE_CORRUPT return below */
68973           break;
68974         }
68975         u.ap.i++;
68976         u.ap.aOffset[u.ap.i] = u.ap.offset;
68977       }while( u.ap.i<=u.ap.p2 && u.ap.zHdr<u.ap.zEndHdr );
68978       u.ap.pC->nHdrParsed = u.ap.i;
68979       u.ap.pC->iHdrOffset = (u32)(u.ap.zHdr - u.ap.zData);
68980       if( u.ap.pC->aRow==0 ){
68981         sqlite3VdbeMemRelease(&u.ap.sMem);
68982         u.ap.sMem.flags = MEM_Null;
68983       }
68984 
68985       /* If we have read more header data than was contained in the header,
68986       ** or if the end of the last field appears to be past the end of the
68987       ** record, or if the end of the last field appears to be before the end
68988       ** of the record (when all fields present), then we must be dealing
68989       ** with a corrupt database.
68990       */
68991       if( (u.ap.zHdr > u.ap.zEndHdr)
68992        || (u.ap.offset > u.ap.pC->payloadSize)
68993        || (u.ap.zHdr==u.ap.zEndHdr && u.ap.offset!=u.ap.pC->payloadSize)
68994       ){
68995         rc = SQLITE_CORRUPT_BKPT;
68996         goto op_column_error;
68997       }
68998     }
68999 
69000     /* If after trying to extra new entries from the header, nHdrParsed is
69001     ** still not up to u.ap.p2, that means that the record has fewer than u.ap.p2
69002     ** columns.  So the result will be either the default value or a NULL.
69003     */
69004     if( u.ap.pC->nHdrParsed<=u.ap.p2 ){
69005       if( pOp->p4type==P4_MEM ){
69006         sqlite3VdbeMemShallowCopy(u.ap.pDest, pOp->p4.pMem, MEM_Static);
69007       }else{
69008         MemSetTypeFlag(u.ap.pDest, MEM_Null);
69009       }
69010       goto op_column_out;
69011     }
69012   }
69013 
69014   /* Extract the content for the u.ap.p2+1-th column.  Control can only
69015   ** 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
69016   ** all valid.
69017   */
69018   assert( u.ap.p2<u.ap.pC->nHdrParsed );
69019   assert( rc==SQLITE_OK );
69020   if( u.ap.pC->szRow>=u.ap.aOffset[u.ap.p2+1] ){
69021     /* This is the common case where the desired content fits on the original
69022     ** page - where the content is not on an overflow page */
69023     VdbeMemRelease(u.ap.pDest);
69024     sqlite3VdbeSerialGet(u.ap.pC->aRow+u.ap.aOffset[u.ap.p2], u.ap.aType[u.ap.p2], u.ap.pDest);
69025   }else{
69026     /* This branch happens only when content is on overflow pages */
69027     u.ap.t = u.ap.aType[u.ap.p2];
69028     if( ((pOp->p5 & (OPFLAG_LENGTHARG|OPFLAG_TYPEOFARG))!=0
69029           && ((u.ap.t>=12 && (u.ap.t&1)==0) || (pOp->p5 & OPFLAG_TYPEOFARG)!=0))
69030      || (u.ap.len = sqlite3VdbeSerialTypeLen(u.ap.t))==0
69031     ){
69032       /* Content is irrelevant for the typeof() function and for
69033       ** the length(X) function if X is a blob.  So we might as well use
69034       ** bogus content rather than reading content from disk.  NULL works
69035       ** for text and blob and whatever is in the u.ap.payloadSize64 variable
69036       ** will work for everything else.  Content is also irrelevant if
69037       ** the content length is 0. */
69038       u.ap.zData = u.ap.t<=13 ? (u8*)&u.ap.payloadSize64 : 0;
69039       u.ap.sMem.zMalloc = 0;
69040     }else{
69041       memset(&u.ap.sMem, 0, sizeof(u.ap.sMem));
69042       sqlite3VdbeMemMove(&u.ap.sMem, u.ap.pDest);
69043       rc = sqlite3VdbeMemFromBtree(u.ap.pCrsr, u.ap.aOffset[u.ap.p2], u.ap.len, !u.ap.pC->isTable,
69044                                    &u.ap.sMem);
69045       if( rc!=SQLITE_OK ){
69046         goto op_column_error;
69047       }
69048       u.ap.zData = (u8*)u.ap.sMem.z;
69049     }
69050     sqlite3VdbeSerialGet(u.ap.zData, u.ap.t, u.ap.pDest);
69051     /* If we dynamically allocated space to hold the data (in the
69052     ** sqlite3VdbeMemFromBtree() call above) then transfer control of that
69053     ** dynamically allocated space over to the u.ap.pDest structure.
69054     ** This prevents a memory copy. */
69055     if( u.ap.sMem.zMalloc ){
69056       assert( u.ap.sMem.z==u.ap.sMem.zMalloc );
69057       assert( !(u.ap.pDest->flags & MEM_Dyn) );
69058       assert( !(u.ap.pDest->flags & (MEM_Blob|MEM_Str)) || u.ap.pDest->z==u.ap.sMem.z );
69059       u.ap.pDest->flags &= ~(MEM_Ephem|MEM_Static);
69060       u.ap.pDest->flags |= MEM_Term;
69061       u.ap.pDest->z = u.ap.sMem.z;
69062       u.ap.pDest->zMalloc = u.ap.sMem.zMalloc;
69063     }
69064   }
69065   u.ap.pDest->enc = encoding;
69066 
69067 op_column_out:
69068   rc = sqlite3VdbeMemMakeWriteable(u.ap.pDest);
69069 op_column_error:
69070   UPDATE_MAX_BLOBSIZE(u.ap.pDest);
69071   REGISTER_TRACE(pOp->p3, u.ap.pDest);
69072   break;
69073 }
69074 
69075 /* Opcode: Affinity P1 P2 * P4 *
69076 ** Synopsis: affinity(r[P1@P2])
69077 **
69078 ** Apply affinities to a range of P2 registers starting with P1.
69079 **
69080 ** P4 is a string that is P2 characters long. The nth character of the
69081 ** string indicates the column affinity that should be used for the nth
69082 ** memory cell in the range.
69083 */
69084 case OP_Affinity: {
69085 #if 0  /* local variables moved into u.aq */
69086   const char *zAffinity;   /* The affinity to be applied */
69087   char cAff;               /* A single character of affinity */
69088 #endif /* local variables moved into u.aq */
69089 
69090   u.aq.zAffinity = pOp->p4.z;
69091   assert( u.aq.zAffinity!=0 );
69092   assert( u.aq.zAffinity[pOp->p2]==0 );
69093   pIn1 = &aMem[pOp->p1];
69094   while( (u.aq.cAff = *(u.aq.zAffinity++))!=0 ){
69095     assert( pIn1 <= &p->aMem[(p->nMem-p->nCursor)] );
69096     assert( memIsValid(pIn1) );
69097     ExpandBlob(pIn1);
69098     applyAffinity(pIn1, u.aq.cAff, encoding);
69099     pIn1++;
69100   }
69101   break;
69102 }
69103 
69104 /* Opcode: MakeRecord P1 P2 P3 P4 *
69105 ** Synopsis: r[P3]=mkrec(r[P1@P2])
69106 **
69107 ** Convert P2 registers beginning with P1 into the [record format]
69108 ** use as a data record in a database table or as a key
69109 ** in an index.  The OP_Column opcode can decode the record later.
69110 **
69111 ** P4 may be a string that is P2 characters long.  The nth character of the
69112 ** string indicates the column affinity that should be used for the nth
69113 ** field of the index key.
69114 **
69115 ** The mapping from character to affinity is given by the SQLITE_AFF_
69116 ** macros defined in sqliteInt.h.
69117 **
69118 ** If P4 is NULL then all index fields have the affinity NONE.
69119 */
69120 case OP_MakeRecord: {
69121 #if 0  /* local variables moved into u.ar */
69122   u8 *zNewRecord;        /* A buffer to hold the data for the new record */
69123   Mem *pRec;             /* The new record */
69124   u64 nData;             /* Number of bytes of data space */
69125   int nHdr;              /* Number of bytes of header space */
69126   i64 nByte;             /* Data space required for this record */
69127   int nZero;             /* Number of zero bytes at the end of the record */
69128   int nVarint;           /* Number of bytes in a varint */
69129   u32 serial_type;       /* Type field */
69130   Mem *pData0;           /* First field to be combined into the record */
69131   Mem *pLast;            /* Last field of the record */
69132   int nField;            /* Number of fields in the record */
69133   char *zAffinity;       /* The affinity string for the record */
69134   int file_format;       /* File format to use for encoding */
69135   int i;                 /* Space used in zNewRecord[] */
69136   int len;               /* Length of a field */
69137 #endif /* local variables moved into u.ar */
69138 
69139   /* Assuming the record contains N fields, the record format looks
69140   ** like this:
69141   **
69142   ** ------------------------------------------------------------------------
69143   ** | hdr-size | type 0 | type 1 | ... | type N-1 | data0 | ... | data N-1 |
69144   ** ------------------------------------------------------------------------
69145   **
69146   ** Data(0) is taken from register P1.  Data(1) comes from register P1+1
69147   ** and so froth.
69148   **
69149   ** Each type field is a varint representing the serial type of the
69150   ** corresponding data element (see sqlite3VdbeSerialType()). The
69151   ** hdr-size field is also a varint which is the offset from the beginning
69152   ** of the record to data0.
69153   */
69154   u.ar.nData = 0;         /* Number of bytes of data space */
69155   u.ar.nHdr = 0;          /* Number of bytes of header space */
69156   u.ar.nZero = 0;         /* Number of zero bytes at the end of the record */
69157   u.ar.nField = pOp->p1;
69158   u.ar.zAffinity = pOp->p4.z;
69159   assert( u.ar.nField>0 && pOp->p2>0 && pOp->p2+u.ar.nField<=(p->nMem-p->nCursor)+1 );
69160   u.ar.pData0 = &aMem[u.ar.nField];
69161   u.ar.nField = pOp->p2;
69162   u.ar.pLast = &u.ar.pData0[u.ar.nField-1];
69163   u.ar.file_format = p->minWriteFileFormat;
69164 
69165   /* Identify the output register */
69166   assert( pOp->p3<pOp->p1 || pOp->p3>=pOp->p1+pOp->p2 );
69167   pOut = &aMem[pOp->p3];
69168   memAboutToChange(p, pOut);
69169 
69170   /* Loop through the elements that will make up the record to figure
69171   ** out how much space is required for the new record.
69172   */
69173   for(u.ar.pRec=u.ar.pData0; u.ar.pRec<=u.ar.pLast; u.ar.pRec++){
69174     assert( memIsValid(u.ar.pRec) );
69175     if( u.ar.zAffinity ){
69176       applyAffinity(u.ar.pRec, u.ar.zAffinity[u.ar.pRec-u.ar.pData0], encoding);
69177     }
69178     if( u.ar.pRec->flags&MEM_Zero && u.ar.pRec->n>0 ){
69179       sqlite3VdbeMemExpandBlob(u.ar.pRec);
69180     }
69181     u.ar.serial_type = sqlite3VdbeSerialType(u.ar.pRec, u.ar.file_format);
69182     u.ar.len = sqlite3VdbeSerialTypeLen(u.ar.serial_type);
69183     u.ar.nData += u.ar.len;
69184     u.ar.nHdr += sqlite3VarintLen(u.ar.serial_type);
69185     if( u.ar.pRec->flags & MEM_Zero ){
69186       /* Only pure zero-filled BLOBs can be input to this Opcode.
69187       ** We do not allow blobs with a prefix and a zero-filled tail. */
69188       u.ar.nZero += u.ar.pRec->u.nZero;
69189     }else if( u.ar.len ){
69190       u.ar.nZero = 0;
69191     }
69192   }
69193 
69194   /* Add the initial header varint and total the size */
69195   u.ar.nHdr += u.ar.nVarint = sqlite3VarintLen(u.ar.nHdr);
69196   if( u.ar.nVarint<sqlite3VarintLen(u.ar.nHdr) ){
69197     u.ar.nHdr++;
69198   }
69199   u.ar.nByte = u.ar.nHdr+u.ar.nData-u.ar.nZero;
69200   if( u.ar.nByte>db->aLimit[SQLITE_LIMIT_LENGTH] ){
69201     goto too_big;
69202   }
69203 
69204   /* Make sure the output register has a buffer large enough to store
69205   ** the new record. The output register (pOp->p3) is not allowed to
69206   ** be one of the input registers (because the following call to
69207   ** sqlite3VdbeMemGrow() could clobber the value before it is used).
69208   */
69209   if( sqlite3VdbeMemGrow(pOut, (int)u.ar.nByte, 0) ){
69210     goto no_mem;
69211   }
69212   u.ar.zNewRecord = (u8 *)pOut->z;
69213 
69214   /* Write the record */
69215   u.ar.i = putVarint32(u.ar.zNewRecord, u.ar.nHdr);
69216   for(u.ar.pRec=u.ar.pData0; u.ar.pRec<=u.ar.pLast; u.ar.pRec++){
69217     u.ar.serial_type = sqlite3VdbeSerialType(u.ar.pRec, u.ar.file_format);
69218     u.ar.i += putVarint32(&u.ar.zNewRecord[u.ar.i], u.ar.serial_type);      /* serial type */
69219   }
69220   for(u.ar.pRec=u.ar.pData0; u.ar.pRec<=u.ar.pLast; u.ar.pRec++){  /* serial data */
69221     u.ar.i += sqlite3VdbeSerialPut(&u.ar.zNewRecord[u.ar.i], (int)(u.ar.nByte-u.ar.i), u.ar.pRec,u.ar.file_format);
69222   }
69223   assert( u.ar.i==u.ar.nByte );
69224 
69225   assert( pOp->p3>0 && pOp->p3<=(p->nMem-p->nCursor) );
69226   pOut->n = (int)u.ar.nByte;
69227   pOut->flags = MEM_Blob | MEM_Dyn;
69228   pOut->xDel = 0;
69229   if( u.ar.nZero ){
69230     pOut->u.nZero = u.ar.nZero;
69231     pOut->flags |= MEM_Zero;
69232   }
69233   pOut->enc = SQLITE_UTF8;  /* In case the blob is ever converted to text */
69234   REGISTER_TRACE(pOp->p3, pOut);
69235   UPDATE_MAX_BLOBSIZE(pOut);
69236   break;
69237 }
69238 
69239 /* Opcode: Count P1 P2 * * *
69240 ** Synopsis: r[P2]=count()
69241 **
69242 ** Store the number of entries (an integer value) in the table or index 
69243 ** opened by cursor P1 in register P2
69244 */
69245 #ifndef SQLITE_OMIT_BTREECOUNT
69246 case OP_Count: {         /* out2-prerelease */
69247 #if 0  /* local variables moved into u.as */
69248   i64 nEntry;
69249   BtCursor *pCrsr;
69250 #endif /* local variables moved into u.as */
69251 
69252   u.as.pCrsr = p->apCsr[pOp->p1]->pCursor;
69253   assert( u.as.pCrsr );
69254   rc = sqlite3BtreeCount(u.as.pCrsr, &u.as.nEntry);
69255   pOut->u.i = u.as.nEntry;
69256   break;
69257 }
69258 #endif
69259 
69260 /* Opcode: Savepoint P1 * * P4 *
69261 **
69262 ** Open, release or rollback the savepoint named by parameter P4, depending
69263 ** on the value of P1. To open a new savepoint, P1==0. To release (commit) an
69264 ** existing savepoint, P1==1, or to rollback an existing savepoint P1==2.
69265 */
69266 case OP_Savepoint: {
69267 #if 0  /* local variables moved into u.at */
69268   int p1;                         /* Value of P1 operand */
69269   char *zName;                    /* Name of savepoint */
69270   int nName;
69271   Savepoint *pNew;
69272   Savepoint *pSavepoint;
69273   Savepoint *pTmp;
69274   int iSavepoint;
69275   int ii;
69276 #endif /* local variables moved into u.at */
69277 
69278   u.at.p1 = pOp->p1;
69279   u.at.zName = pOp->p4.z;
69280 
69281   /* Assert that the u.at.p1 parameter is valid. Also that if there is no open
69282   ** transaction, then there cannot be any savepoints.
69283   */
69284   assert( db->pSavepoint==0 || db->autoCommit==0 );
69285   assert( u.at.p1==SAVEPOINT_BEGIN||u.at.p1==SAVEPOINT_RELEASE||u.at.p1==SAVEPOINT_ROLLBACK );
69286   assert( db->pSavepoint || db->isTransactionSavepoint==0 );
69287   assert( checkSavepointCount(db) );
69288   assert( p->bIsReader );
69289 
69290   if( u.at.p1==SAVEPOINT_BEGIN ){
69291     if( db->nVdbeWrite>0 ){
69292       /* A new savepoint cannot be created if there are active write
69293       ** statements (i.e. open read/write incremental blob handles).
69294       */
69295       sqlite3SetString(&p->zErrMsg, db, "cannot open savepoint - "
69296         "SQL statements in progress");
69297       rc = SQLITE_BUSY;
69298     }else{
69299       u.at.nName = sqlite3Strlen30(u.at.zName);
69300 
69301 #ifndef SQLITE_OMIT_VIRTUALTABLE
69302       /* This call is Ok even if this savepoint is actually a transaction
69303       ** savepoint (and therefore should not prompt xSavepoint()) callbacks.
69304       ** If this is a transaction savepoint being opened, it is guaranteed
69305       ** that the db->aVTrans[] array is empty.  */
69306       assert( db->autoCommit==0 || db->nVTrans==0 );
69307       rc = sqlite3VtabSavepoint(db, SAVEPOINT_BEGIN,
69308                                 db->nStatement+db->nSavepoint);
69309       if( rc!=SQLITE_OK ) goto abort_due_to_error;
69310 #endif
69311 
69312       /* Create a new savepoint structure. */
69313       u.at.pNew = sqlite3DbMallocRaw(db, sizeof(Savepoint)+u.at.nName+1);
69314       if( u.at.pNew ){
69315         u.at.pNew->zName = (char *)&u.at.pNew[1];
69316         memcpy(u.at.pNew->zName, u.at.zName, u.at.nName+1);
69317 
69318         /* If there is no open transaction, then mark this as a special
69319         ** "transaction savepoint". */
69320         if( db->autoCommit ){
69321           db->autoCommit = 0;
69322           db->isTransactionSavepoint = 1;
69323         }else{
69324           db->nSavepoint++;
69325         }
69326 
69327         /* Link the new savepoint into the database handle's list. */
69328         u.at.pNew->pNext = db->pSavepoint;
69329         db->pSavepoint = u.at.pNew;
69330         u.at.pNew->nDeferredCons = db->nDeferredCons;
69331         u.at.pNew->nDeferredImmCons = db->nDeferredImmCons;
69332       }
69333     }
69334   }else{
69335     u.at.iSavepoint = 0;
69336 
69337     /* Find the named savepoint. If there is no such savepoint, then an
69338     ** an error is returned to the user.  */
69339     for(
69340       u.at.pSavepoint = db->pSavepoint;
69341       u.at.pSavepoint && sqlite3StrICmp(u.at.pSavepoint->zName, u.at.zName);
69342       u.at.pSavepoint = u.at.pSavepoint->pNext
69343     ){
69344       u.at.iSavepoint++;
69345     }
69346     if( !u.at.pSavepoint ){
69347       sqlite3SetString(&p->zErrMsg, db, "no such savepoint: %s", u.at.zName);
69348       rc = SQLITE_ERROR;
69349     }else if( db->nVdbeWrite>0 && u.at.p1==SAVEPOINT_RELEASE ){
69350       /* It is not possible to release (commit) a savepoint if there are
69351       ** active write statements.
69352       */
69353       sqlite3SetString(&p->zErrMsg, db,
69354         "cannot release savepoint - SQL statements in progress"
69355       );
69356       rc = SQLITE_BUSY;
69357     }else{
69358 
69359       /* Determine whether or not this is a transaction savepoint. If so,
69360       ** and this is a RELEASE command, then the current transaction
69361       ** is committed.
69362       */
69363       int isTransaction = u.at.pSavepoint->pNext==0 && db->isTransactionSavepoint;
69364       if( isTransaction && u.at.p1==SAVEPOINT_RELEASE ){
69365         if( (rc = sqlite3VdbeCheckFk(p, 1))!=SQLITE_OK ){
69366           goto vdbe_return;
69367         }
69368         db->autoCommit = 1;
69369         if( sqlite3VdbeHalt(p)==SQLITE_BUSY ){
69370           p->pc = pc;
69371           db->autoCommit = 0;
69372           p->rc = rc = SQLITE_BUSY;
69373           goto vdbe_return;
69374         }
69375         db->isTransactionSavepoint = 0;
69376         rc = p->rc;
69377       }else{
69378         u.at.iSavepoint = db->nSavepoint - u.at.iSavepoint - 1;
69379         if( u.at.p1==SAVEPOINT_ROLLBACK ){
69380           for(u.at.ii=0; u.at.ii<db->nDb; u.at.ii++){
69381             sqlite3BtreeTripAllCursors(db->aDb[u.at.ii].pBt, SQLITE_ABORT);
69382           }
69383         }
69384         for(u.at.ii=0; u.at.ii<db->nDb; u.at.ii++){
69385           rc = sqlite3BtreeSavepoint(db->aDb[u.at.ii].pBt, u.at.p1, u.at.iSavepoint);
69386           if( rc!=SQLITE_OK ){
69387             goto abort_due_to_error;
69388           }
69389         }
69390         if( u.at.p1==SAVEPOINT_ROLLBACK && (db->flags&SQLITE_InternChanges)!=0 ){
69391           sqlite3ExpirePreparedStatements(db);
69392           sqlite3ResetAllSchemasOfConnection(db);
69393           db->flags = (db->flags | SQLITE_InternChanges);
69394         }
69395       }
69396 
69397       /* Regardless of whether this is a RELEASE or ROLLBACK, destroy all
69398       ** savepoints nested inside of the savepoint being operated on. */
69399       while( db->pSavepoint!=u.at.pSavepoint ){
69400         u.at.pTmp = db->pSavepoint;
69401         db->pSavepoint = u.at.pTmp->pNext;
69402         sqlite3DbFree(db, u.at.pTmp);
69403         db->nSavepoint--;
69404       }
69405 
69406       /* If it is a RELEASE, then destroy the savepoint being operated on
69407       ** too. If it is a ROLLBACK TO, then set the number of deferred
69408       ** constraint violations present in the database to the value stored
69409       ** when the savepoint was created.  */
69410       if( u.at.p1==SAVEPOINT_RELEASE ){
69411         assert( u.at.pSavepoint==db->pSavepoint );
69412         db->pSavepoint = u.at.pSavepoint->pNext;
69413         sqlite3DbFree(db, u.at.pSavepoint);
69414         if( !isTransaction ){
69415           db->nSavepoint--;
69416         }
69417       }else{
69418         db->nDeferredCons = u.at.pSavepoint->nDeferredCons;
69419         db->nDeferredImmCons = u.at.pSavepoint->nDeferredImmCons;
69420       }
69421 
69422       if( !isTransaction ){
69423         rc = sqlite3VtabSavepoint(db, u.at.p1, u.at.iSavepoint);
69424         if( rc!=SQLITE_OK ) goto abort_due_to_error;
69425       }
69426     }
69427   }
69428 
69429   break;
69430 }
69431 
69432 /* Opcode: AutoCommit P1 P2 * * *
69433 **
69434 ** Set the database auto-commit flag to P1 (1 or 0). If P2 is true, roll
69435 ** back any currently active btree transactions. If there are any active
69436 ** VMs (apart from this one), then a ROLLBACK fails.  A COMMIT fails if
69437 ** there are active writing VMs or active VMs that use shared cache.
69438 **
69439 ** This instruction causes the VM to halt.
69440 */
69441 case OP_AutoCommit: {
69442 #if 0  /* local variables moved into u.au */
69443   int desiredAutoCommit;
69444   int iRollback;
69445   int turnOnAC;
69446 #endif /* local variables moved into u.au */
69447 
69448   u.au.desiredAutoCommit = pOp->p1;
69449   u.au.iRollback = pOp->p2;
69450   u.au.turnOnAC = u.au.desiredAutoCommit && !db->autoCommit;
69451   assert( u.au.desiredAutoCommit==1 || u.au.desiredAutoCommit==0 );
69452   assert( u.au.desiredAutoCommit==1 || u.au.iRollback==0 );
69453   assert( db->nVdbeActive>0 );  /* At least this one VM is active */
69454   assert( p->bIsReader );
69455 
69456 #if 0
69457   if( u.au.turnOnAC && u.au.iRollback && db->nVdbeActive>1 ){
69458     /* If this instruction implements a ROLLBACK and other VMs are
69459     ** still running, and a transaction is active, return an error indicating
69460     ** that the other VMs must complete first.
69461     */
69462     sqlite3SetString(&p->zErrMsg, db, "cannot rollback transaction - "
69463         "SQL statements in progress");
69464     rc = SQLITE_BUSY;
69465   }else
69466 #endif
69467   if( u.au.turnOnAC && !u.au.iRollback && db->nVdbeWrite>0 ){
69468     /* If this instruction implements a COMMIT and other VMs are writing
69469     ** return an error indicating that the other VMs must complete first.
69470     */
69471     sqlite3SetString(&p->zErrMsg, db, "cannot commit transaction - "
69472         "SQL statements in progress");
69473     rc = SQLITE_BUSY;
69474   }else if( u.au.desiredAutoCommit!=db->autoCommit ){
69475     if( u.au.iRollback ){
69476       assert( u.au.desiredAutoCommit==1 );
69477       sqlite3RollbackAll(db, SQLITE_ABORT_ROLLBACK);
69478       db->autoCommit = 1;
69479     }else if( (rc = sqlite3VdbeCheckFk(p, 1))!=SQLITE_OK ){
69480       goto vdbe_return;
69481     }else{
69482       db->autoCommit = (u8)u.au.desiredAutoCommit;
69483       if( sqlite3VdbeHalt(p)==SQLITE_BUSY ){
69484         p->pc = pc;
69485         db->autoCommit = (u8)(1-u.au.desiredAutoCommit);
69486         p->rc = rc = SQLITE_BUSY;
69487         goto vdbe_return;
69488       }
69489     }
69490     assert( db->nStatement==0 );
69491     sqlite3CloseSavepoints(db);
69492     if( p->rc==SQLITE_OK ){
69493       rc = SQLITE_DONE;
69494     }else{
69495       rc = SQLITE_ERROR;
69496     }
69497     goto vdbe_return;
69498   }else{
69499     sqlite3SetString(&p->zErrMsg, db,
69500         (!u.au.desiredAutoCommit)?"cannot start a transaction within a transaction":(
69501         (u.au.iRollback)?"cannot rollback - no transaction is active":
69502                    "cannot commit - no transaction is active"));
69503 
69504     rc = SQLITE_ERROR;
69505   }
69506   break;
69507 }
69508 
69509 /* Opcode: Transaction P1 P2 * * *
69510 **
69511 ** Begin a transaction.  The transaction ends when a Commit or Rollback
69512 ** opcode is encountered.  Depending on the ON CONFLICT setting, the
69513 ** transaction might also be rolled back if an error is encountered.
69514 **
69515 ** P1 is the index of the database file on which the transaction is
69516 ** started.  Index 0 is the main database file and index 1 is the
69517 ** file used for temporary tables.  Indices of 2 or more are used for
69518 ** attached databases.
69519 **
69520 ** If P2 is non-zero, then a write-transaction is started.  A RESERVED lock is
69521 ** obtained on the database file when a write-transaction is started.  No
69522 ** other process can start another write transaction while this transaction is
69523 ** underway.  Starting a write transaction also creates a rollback journal. A
69524 ** write transaction must be started before any changes can be made to the
69525 ** database.  If P2 is greater than or equal to 2 then an EXCLUSIVE lock is
69526 ** also obtained on the file.
69527 **
69528 ** If a write-transaction is started and the Vdbe.usesStmtJournal flag is
69529 ** true (this flag is set if the Vdbe may modify more than one row and may
69530 ** throw an ABORT exception), a statement transaction may also be opened.
69531 ** More specifically, a statement transaction is opened iff the database
69532 ** connection is currently not in autocommit mode, or if there are other
69533 ** active statements. A statement transaction allows the changes made by this
69534 ** VDBE to be rolled back after an error without having to roll back the
69535 ** entire transaction. If no error is encountered, the statement transaction
69536 ** will automatically commit when the VDBE halts.
69537 **
69538 ** If P2 is zero, then a read-lock is obtained on the database file.
69539 */
69540 case OP_Transaction: {
69541 #if 0  /* local variables moved into u.av */
69542   Btree *pBt;
69543 #endif /* local variables moved into u.av */
69544 
69545   assert( p->bIsReader );
69546   assert( p->readOnly==0 || pOp->p2==0 );
69547   assert( pOp->p1>=0 && pOp->p1<db->nDb );
69548   assert( (p->btreeMask & (((yDbMask)1)<<pOp->p1))!=0 );
69549   if( pOp->p2 && (db->flags & SQLITE_QueryOnly)!=0 ){
69550     rc = SQLITE_READONLY;
69551     goto abort_due_to_error;
69552   }
69553   u.av.pBt = db->aDb[pOp->p1].pBt;
69554 
69555   if( u.av.pBt ){
69556     rc = sqlite3BtreeBeginTrans(u.av.pBt, pOp->p2);
69557     if( rc==SQLITE_BUSY ){
69558       p->pc = pc;
69559       p->rc = rc = SQLITE_BUSY;
69560       goto vdbe_return;
69561     }
69562     if( rc!=SQLITE_OK ){
69563       goto abort_due_to_error;
69564     }
69565 
69566     if( pOp->p2 && p->usesStmtJournal
69567      && (db->autoCommit==0 || db->nVdbeRead>1)
69568     ){
69569       assert( sqlite3BtreeIsInTrans(u.av.pBt) );
69570       if( p->iStatement==0 ){
69571         assert( db->nStatement>=0 && db->nSavepoint>=0 );
69572         db->nStatement++;
69573         p->iStatement = db->nSavepoint + db->nStatement;
69574       }
69575 
69576       rc = sqlite3VtabSavepoint(db, SAVEPOINT_BEGIN, p->iStatement-1);
69577       if( rc==SQLITE_OK ){
69578         rc = sqlite3BtreeBeginStmt(u.av.pBt, p->iStatement);
69579       }
69580 
69581       /* Store the current value of the database handles deferred constraint
69582       ** counter. If the statement transaction needs to be rolled back,
69583       ** the value of this counter needs to be restored too.  */
69584       p->nStmtDefCons = db->nDeferredCons;
69585       p->nStmtDefImmCons = db->nDeferredImmCons;
69586     }
69587   }
69588   break;
69589 }
69590 
69591 /* Opcode: ReadCookie P1 P2 P3 * *
69592 **
69593 ** Read cookie number P3 from database P1 and write it into register P2.
69594 ** P3==1 is the schema version.  P3==2 is the database format.
69595 ** P3==3 is the recommended pager cache size, and so forth.  P1==0 is
69596 ** the main database file and P1==1 is the database file used to store
69597 ** temporary tables.
69598 **
69599 ** There must be a read-lock on the database (either a transaction
69600 ** must be started or there must be an open cursor) before
69601 ** executing this instruction.
69602 */
69603 case OP_ReadCookie: {               /* out2-prerelease */
69604 #if 0  /* local variables moved into u.aw */
69605   int iMeta;
69606   int iDb;
69607   int iCookie;
69608 #endif /* local variables moved into u.aw */
69609 
69610   assert( p->bIsReader );
69611   u.aw.iDb = pOp->p1;
69612   u.aw.iCookie = pOp->p3;
69613   assert( pOp->p3<SQLITE_N_BTREE_META );
69614   assert( u.aw.iDb>=0 && u.aw.iDb<db->nDb );
69615   assert( db->aDb[u.aw.iDb].pBt!=0 );
69616   assert( (p->btreeMask & (((yDbMask)1)<<u.aw.iDb))!=0 );
69617 
69618   sqlite3BtreeGetMeta(db->aDb[u.aw.iDb].pBt, u.aw.iCookie, (u32 *)&u.aw.iMeta);
69619   pOut->u.i = u.aw.iMeta;
69620   break;
69621 }
69622 
69623 /* Opcode: SetCookie P1 P2 P3 * *
69624 **
69625 ** Write the content of register P3 (interpreted as an integer)
69626 ** into cookie number P2 of database P1.  P2==1 is the schema version.  
69627 ** P2==2 is the database format. P2==3 is the recommended pager cache 
69628 ** size, and so forth.  P1==0 is the main database file and P1==1 is the 
69629 ** database file used to store temporary tables.
69630 **
69631 ** A transaction must be started before executing this opcode.
69632 */
69633 case OP_SetCookie: {       /* in3 */
69634 #if 0  /* local variables moved into u.ax */
69635   Db *pDb;
69636 #endif /* local variables moved into u.ax */
69637   assert( pOp->p2<SQLITE_N_BTREE_META );
69638   assert( pOp->p1>=0 && pOp->p1<db->nDb );
69639   assert( (p->btreeMask & (((yDbMask)1)<<pOp->p1))!=0 );
69640   assert( p->readOnly==0 );
69641   u.ax.pDb = &db->aDb[pOp->p1];
69642   assert( u.ax.pDb->pBt!=0 );
69643   assert( sqlite3SchemaMutexHeld(db, pOp->p1, 0) );
69644   pIn3 = &aMem[pOp->p3];
69645   sqlite3VdbeMemIntegerify(pIn3);
69646   /* See note about index shifting on OP_ReadCookie */
69647   rc = sqlite3BtreeUpdateMeta(u.ax.pDb->pBt, pOp->p2, (int)pIn3->u.i);
69648   if( pOp->p2==BTREE_SCHEMA_VERSION ){
69649     /* When the schema cookie changes, record the new cookie internally */
69650     u.ax.pDb->pSchema->schema_cookie = (int)pIn3->u.i;
69651     db->flags |= SQLITE_InternChanges;
69652   }else if( pOp->p2==BTREE_FILE_FORMAT ){
69653     /* Record changes in the file format */
69654     u.ax.pDb->pSchema->file_format = (u8)pIn3->u.i;
69655   }
69656   if( pOp->p1==1 ){
69657     /* Invalidate all prepared statements whenever the TEMP database
69658     ** schema is changed.  Ticket #1644 */
69659     sqlite3ExpirePreparedStatements(db);
69660     p->expired = 0;
69661   }
69662   break;
69663 }
69664 
69665 /* Opcode: VerifyCookie P1 P2 P3 * *
69666 **
69667 ** Check the value of global database parameter number 0 (the
69668 ** schema version) and make sure it is equal to P2 and that the
69669 ** generation counter on the local schema parse equals P3.
69670 **
69671 ** P1 is the database number which is 0 for the main database file
69672 ** and 1 for the file holding temporary tables and some higher number
69673 ** for auxiliary databases.
69674 **
69675 ** The cookie changes its value whenever the database schema changes.
69676 ** This operation is used to detect when that the cookie has changed
69677 ** and that the current process needs to reread the schema.
69678 **
69679 ** Either a transaction needs to have been started or an OP_Open needs
69680 ** to be executed (to establish a read lock) before this opcode is
69681 ** invoked.
69682 */
69683 case OP_VerifyCookie: {
69684 #if 0  /* local variables moved into u.ay */
69685   int iMeta;
69686   int iGen;
69687   Btree *pBt;
69688 #endif /* local variables moved into u.ay */
69689 
69690   assert( pOp->p1>=0 && pOp->p1<db->nDb );
69691   assert( (p->btreeMask & (((yDbMask)1)<<pOp->p1))!=0 );
69692   assert( sqlite3SchemaMutexHeld(db, pOp->p1, 0) );
69693   assert( p->bIsReader );
69694   u.ay.pBt = db->aDb[pOp->p1].pBt;
69695   if( u.ay.pBt ){
69696     sqlite3BtreeGetMeta(u.ay.pBt, BTREE_SCHEMA_VERSION, (u32 *)&u.ay.iMeta);
69697     u.ay.iGen = db->aDb[pOp->p1].pSchema->iGeneration;
69698   }else{
69699     u.ay.iGen = u.ay.iMeta = 0;
69700   }
69701   if( u.ay.iMeta!=pOp->p2 || u.ay.iGen!=pOp->p3 ){
69702     sqlite3DbFree(db, p->zErrMsg);
69703     p->zErrMsg = sqlite3DbStrDup(db, "database schema has changed");
69704     /* If the schema-cookie from the database file matches the cookie
69705     ** stored with the in-memory representation of the schema, do
69706     ** not reload the schema from the database file.
69707     **
69708     ** If virtual-tables are in use, this is not just an optimization.
69709     ** Often, v-tables store their data in other SQLite tables, which
69710     ** are queried from within xNext() and other v-table methods using
69711     ** prepared queries. If such a query is out-of-date, we do not want to
69712     ** discard the database schema, as the user code implementing the
69713     ** v-table would have to be ready for the sqlite3_vtab structure itself
69714     ** to be invalidated whenever sqlite3_step() is called from within
69715     ** a v-table method.
69716     */
69717     if( db->aDb[pOp->p1].pSchema->schema_cookie!=u.ay.iMeta ){
69718       sqlite3ResetOneSchema(db, pOp->p1);
69719     }
69720 
69721     p->expired = 1;
69722     rc = SQLITE_SCHEMA;
69723   }
69724   break;
69725 }
69726 
69727 /* Opcode: OpenRead P1 P2 P3 P4 P5
69728 ** Synopsis: root=P2 iDb=P3
69729 **
69730 ** Open a read-only cursor for the database table whose root page is
69731 ** P2 in a database file.  The database file is determined by P3. 
69732 ** P3==0 means the main database, P3==1 means the database used for 
69733 ** temporary tables, and P3>1 means used the corresponding attached
69734 ** database.  Give the new cursor an identifier of P1.  The P1
69735 ** values need not be contiguous but all P1 values should be small integers.
69736 ** It is an error for P1 to be negative.
69737 **
69738 ** If P5!=0 then use the content of register P2 as the root page, not
69739 ** the value of P2 itself.
69740 **
69741 ** There will be a read lock on the database whenever there is an
69742 ** open cursor.  If the database was unlocked prior to this instruction
69743 ** then a read lock is acquired as part of this instruction.  A read
69744 ** lock allows other processes to read the database but prohibits
69745 ** any other process from modifying the database.  The read lock is
69746 ** released when all cursors are closed.  If this instruction attempts
69747 ** to get a read lock but fails, the script terminates with an
69748 ** SQLITE_BUSY error code.
69749 **
69750 ** The P4 value may be either an integer (P4_INT32) or a pointer to
69751 ** a KeyInfo structure (P4_KEYINFO). If it is a pointer to a KeyInfo 
69752 ** structure, then said structure defines the content and collating 
69753 ** sequence of the index being opened. Otherwise, if P4 is an integer 
69754 ** value, it is set to the number of columns in the table.
69755 **
69756 ** See also OpenWrite.
69757 */
69758 /* Opcode: OpenWrite P1 P2 P3 P4 P5
69759 ** Synopsis: root=P2 iDb=P3
69760 **
69761 ** Open a read/write cursor named P1 on the table or index whose root
69762 ** page is P2.  Or if P5!=0 use the content of register P2 to find the
69763 ** root page.
69764 **
69765 ** The P4 value may be either an integer (P4_INT32) or a pointer to
69766 ** a KeyInfo structure (P4_KEYINFO). If it is a pointer to a KeyInfo 
69767 ** structure, then said structure defines the content and collating 
69768 ** sequence of the index being opened. Otherwise, if P4 is an integer 
69769 ** value, it is set to the number of columns in the table, or to the
69770 ** largest index of any column of the table that is actually used.
69771 **
69772 ** This instruction works just like OpenRead except that it opens the cursor
69773 ** in read/write mode.  For a given table, there can be one or more read-only
69774 ** cursors or a single read/write cursor but not both.
69775 **
69776 ** See also OpenRead.
69777 */
69778 case OP_OpenRead:
69779 case OP_OpenWrite: {
69780 #if 0  /* local variables moved into u.az */
69781   int nField;
69782   KeyInfo *pKeyInfo;
69783   int p2;
69784   int iDb;
69785   int wrFlag;
69786   Btree *pX;
69787   VdbeCursor *pCur;
69788   Db *pDb;
69789 #endif /* local variables moved into u.az */
69790 
69791   assert( (pOp->p5&(OPFLAG_P2ISREG|OPFLAG_BULKCSR))==pOp->p5 );
69792   assert( pOp->opcode==OP_OpenWrite || pOp->p5==0 );
69793   assert( p->bIsReader );
69794   assert( pOp->opcode==OP_OpenRead || p->readOnly==0 );
69795 
69796   if( p->expired ){
69797     rc = SQLITE_ABORT;
69798     break;
69799   }
69800 
69801   u.az.nField = 0;
69802   u.az.pKeyInfo = 0;
69803   u.az.p2 = pOp->p2;
69804   u.az.iDb = pOp->p3;
69805   assert( u.az.iDb>=0 && u.az.iDb<db->nDb );
69806   assert( (p->btreeMask & (((yDbMask)1)<<u.az.iDb))!=0 );
69807   u.az.pDb = &db->aDb[u.az.iDb];
69808   u.az.pX = u.az.pDb->pBt;
69809   assert( u.az.pX!=0 );
69810   if( pOp->opcode==OP_OpenWrite ){
69811     u.az.wrFlag = 1;
69812     assert( sqlite3SchemaMutexHeld(db, u.az.iDb, 0) );
69813     if( u.az.pDb->pSchema->file_format < p->minWriteFileFormat ){
69814       p->minWriteFileFormat = u.az.pDb->pSchema->file_format;
69815     }
69816   }else{
69817     u.az.wrFlag = 0;
69818   }
69819   if( pOp->p5 & OPFLAG_P2ISREG ){
69820     assert( u.az.p2>0 );
69821     assert( u.az.p2<=(p->nMem-p->nCursor) );
69822     pIn2 = &aMem[u.az.p2];
69823     assert( memIsValid(pIn2) );
69824     assert( (pIn2->flags & MEM_Int)!=0 );
69825     sqlite3VdbeMemIntegerify(pIn2);
69826     u.az.p2 = (int)pIn2->u.i;
69827     /* The u.az.p2 value always comes from a prior OP_CreateTable opcode and
69828     ** that opcode will always set the u.az.p2 value to 2 or more or else fail.
69829     ** If there were a failure, the prepared statement would have halted
69830     ** before reaching this instruction. */
69831     if( NEVER(u.az.p2<2) ) {
69832       rc = SQLITE_CORRUPT_BKPT;
69833       goto abort_due_to_error;
69834     }
69835   }
69836   if( pOp->p4type==P4_KEYINFO ){
69837     u.az.pKeyInfo = pOp->p4.pKeyInfo;
69838     assert( u.az.pKeyInfo->enc==ENC(db) );
69839     assert( u.az.pKeyInfo->db==db );
69840     u.az.nField = u.az.pKeyInfo->nField+u.az.pKeyInfo->nXField;
69841   }else if( pOp->p4type==P4_INT32 ){
69842     u.az.nField = pOp->p4.i;
69843   }
69844   assert( pOp->p1>=0 );
69845   assert( u.az.nField>=0 );
69846   testcase( u.az.nField==0 );  /* Table with INTEGER PRIMARY KEY and nothing else */
69847   u.az.pCur = allocateCursor(p, pOp->p1, u.az.nField, u.az.iDb, 1);
69848   if( u.az.pCur==0 ) goto no_mem;
69849   u.az.pCur->nullRow = 1;
69850   u.az.pCur->isOrdered = 1;
69851   rc = sqlite3BtreeCursor(u.az.pX, u.az.p2, u.az.wrFlag, u.az.pKeyInfo, u.az.pCur->pCursor);
69852   u.az.pCur->pKeyInfo = u.az.pKeyInfo;
69853   assert( OPFLAG_BULKCSR==BTREE_BULKLOAD );
69854   sqlite3BtreeCursorHints(u.az.pCur->pCursor, (pOp->p5 & OPFLAG_BULKCSR));
69855 
69856   /* Since it performs no memory allocation or IO, the only value that
69857   ** sqlite3BtreeCursor() may return is SQLITE_OK. */
69858   assert( rc==SQLITE_OK );
69859 
69860   /* Set the VdbeCursor.isTable variable. Previous versions of
69861   ** SQLite used to check if the root-page flags were sane at this point
69862   ** and report database corruption if they were not, but this check has
69863   ** since moved into the btree layer.  */
69864   u.az.pCur->isTable = pOp->p4type!=P4_KEYINFO;
69865   break;
69866 }
69867 
69868 /* Opcode: OpenEphemeral P1 P2 * P4 P5
69869 ** Synopsis: nColumn=P2
69870 **
69871 ** Open a new cursor P1 to a transient table.
69872 ** The cursor is always opened read/write even if 
69873 ** the main database is read-only.  The ephemeral
69874 ** table is deleted automatically when the cursor is closed.
69875 **
69876 ** P2 is the number of columns in the ephemeral table.
69877 ** The cursor points to a BTree table if P4==0 and to a BTree index
69878 ** if P4 is not 0.  If P4 is not NULL, it points to a KeyInfo structure
69879 ** that defines the format of keys in the index.
69880 **
69881 ** The P5 parameter can be a mask of the BTREE_* flags defined
69882 ** in btree.h.  These flags control aspects of the operation of
69883 ** the btree.  The BTREE_OMIT_JOURNAL and BTREE_SINGLE flags are
69884 ** added automatically.
69885 */
69886 /* Opcode: OpenAutoindex P1 P2 * P4 *
69887 ** Synopsis: nColumn=P2
69888 **
69889 ** This opcode works the same as OP_OpenEphemeral.  It has a
69890 ** different name to distinguish its use.  Tables created using
69891 ** by this opcode will be used for automatically created transient
69892 ** indices in joins.
69893 */
69894 case OP_OpenAutoindex: 
69895 case OP_OpenEphemeral: {
69896 #if 0  /* local variables moved into u.ba */
69897   VdbeCursor *pCx;
69898   KeyInfo *pKeyInfo;
69899 #endif /* local variables moved into u.ba */
69900 
69901   static const int vfsFlags =
69902       SQLITE_OPEN_READWRITE |
69903       SQLITE_OPEN_CREATE |
69904       SQLITE_OPEN_EXCLUSIVE |
69905       SQLITE_OPEN_DELETEONCLOSE |
69906       SQLITE_OPEN_TRANSIENT_DB;
69907   assert( pOp->p1>=0 );
69908   assert( pOp->p2>=0 );
69909   u.ba.pCx = allocateCursor(p, pOp->p1, pOp->p2, -1, 1);
69910   if( u.ba.pCx==0 ) goto no_mem;
69911   u.ba.pCx->nullRow = 1;
69912   rc = sqlite3BtreeOpen(db->pVfs, 0, db, &u.ba.pCx->pBt,
69913                         BTREE_OMIT_JOURNAL | BTREE_SINGLE | pOp->p5, vfsFlags);
69914   if( rc==SQLITE_OK ){
69915     rc = sqlite3BtreeBeginTrans(u.ba.pCx->pBt, 1);
69916   }
69917   if( rc==SQLITE_OK ){
69918     /* If a transient index is required, create it by calling
69919     ** sqlite3BtreeCreateTable() with the BTREE_BLOBKEY flag before
69920     ** opening it. If a transient table is required, just use the
69921     ** automatically created table with root-page 1 (an BLOB_INTKEY table).
69922     */
69923     if( (u.ba.pKeyInfo = pOp->p4.pKeyInfo)!=0 ){
69924       int pgno;
69925       assert( pOp->p4type==P4_KEYINFO );
69926       rc = sqlite3BtreeCreateTable(u.ba.pCx->pBt, &pgno, BTREE_BLOBKEY | pOp->p5);
69927       if( rc==SQLITE_OK ){
69928         assert( pgno==MASTER_ROOT+1 );
69929         assert( u.ba.pKeyInfo->db==db );
69930         assert( u.ba.pKeyInfo->enc==ENC(db) );
69931         u.ba.pCx->pKeyInfo = u.ba.pKeyInfo;
69932         rc = sqlite3BtreeCursor(u.ba.pCx->pBt, pgno, 1, u.ba.pKeyInfo, u.ba.pCx->pCursor);
69933       }
69934       u.ba.pCx->isTable = 0;
69935     }else{
69936       rc = sqlite3BtreeCursor(u.ba.pCx->pBt, MASTER_ROOT, 1, 0, u.ba.pCx->pCursor);
69937       u.ba.pCx->isTable = 1;
69938     }
69939   }
69940   u.ba.pCx->isOrdered = (pOp->p5!=BTREE_UNORDERED);
69941   break;
69942 }
69943 
69944 /* Opcode: SorterOpen P1 * * P4 *
69945 **
69946 ** This opcode works like OP_OpenEphemeral except that it opens
69947 ** a transient index that is specifically designed to sort large
69948 ** tables using an external merge-sort algorithm.
69949 */
69950 case OP_SorterOpen: {
69951 #if 0  /* local variables moved into u.bb */
69952   VdbeCursor *pCx;
69953 #endif /* local variables moved into u.bb */
69954 
69955   assert( pOp->p1>=0 );
69956   assert( pOp->p2>=0 );
69957   u.bb.pCx = allocateCursor(p, pOp->p1, pOp->p2, -1, 1);
69958   if( u.bb.pCx==0 ) goto no_mem;
69959   u.bb.pCx->pKeyInfo = pOp->p4.pKeyInfo;
69960   assert( u.bb.pCx->pKeyInfo->db==db );
69961   assert( u.bb.pCx->pKeyInfo->enc==ENC(db) );
69962   rc = sqlite3VdbeSorterInit(db, u.bb.pCx);
69963   break;
69964 }
69965 
69966 /* Opcode: OpenPseudo P1 P2 P3 * P5
69967 ** Synopsis: content in r[P2@P3]
69968 **
69969 ** Open a new cursor that points to a fake table that contains a single
69970 ** row of data.  The content of that one row in the content of memory
69971 ** register P2 when P5==0.  In other words, cursor P1 becomes an alias for the 
69972 ** MEM_Blob content contained in register P2.  When P5==1, then the
69973 ** row is represented by P3 consecutive registers beginning with P2.
69974 **
69975 ** A pseudo-table created by this opcode is used to hold a single
69976 ** row output from the sorter so that the row can be decomposed into
69977 ** individual columns using the OP_Column opcode.  The OP_Column opcode
69978 ** is the only cursor opcode that works with a pseudo-table.
69979 **
69980 ** P3 is the number of fields in the records that will be stored by
69981 ** the pseudo-table.
69982 */
69983 case OP_OpenPseudo: {
69984 #if 0  /* local variables moved into u.bc */
69985   VdbeCursor *pCx;
69986 #endif /* local variables moved into u.bc */
69987 
69988   assert( pOp->p1>=0 );
69989   assert( pOp->p3>=0 );
69990   u.bc.pCx = allocateCursor(p, pOp->p1, pOp->p3, -1, 0);
69991   if( u.bc.pCx==0 ) goto no_mem;
69992   u.bc.pCx->nullRow = 1;
69993   u.bc.pCx->pseudoTableReg = pOp->p2;
69994   u.bc.pCx->isTable = 1;
69995   u.bc.pCx->multiPseudo = pOp->p5;
69996   break;
69997 }
69998 
69999 /* Opcode: Close P1 * * * *
70000 **
70001 ** Close a cursor previously opened as P1.  If P1 is not
70002 ** currently open, this instruction is a no-op.
70003 */
70004 case OP_Close: {
70005   assert( pOp->p1>=0 && pOp->p1<p->nCursor );
70006   sqlite3VdbeFreeCursor(p, p->apCsr[pOp->p1]);
70007   p->apCsr[pOp->p1] = 0;
70008   break;
70009 }
70010 
70011 /* Opcode: SeekGe P1 P2 P3 P4 *
70012 ** Synopsis: key=r[P3@P4]
70013 **
70014 ** If cursor P1 refers to an SQL table (B-Tree that uses integer keys), 
70015 ** use the value in register P3 as the key.  If cursor P1 refers 
70016 ** to an SQL index, then P3 is the first in an array of P4 registers 
70017 ** that are used as an unpacked index key. 
70018 **
70019 ** Reposition cursor P1 so that  it points to the smallest entry that 
70020 ** is greater than or equal to the key value. If there are no records 
70021 ** greater than or equal to the key and P2 is not zero, then jump to P2.
70022 **
70023 ** See also: Found, NotFound, Distinct, SeekLt, SeekGt, SeekLe
70024 */
70025 /* Opcode: SeekGt P1 P2 P3 P4 *
70026 ** Synopsis: key=r[P3@P4]
70027 **
70028 ** If cursor P1 refers to an SQL table (B-Tree that uses integer keys), 
70029 ** use the value in register P3 as a key. If cursor P1 refers 
70030 ** to an SQL index, then P3 is the first in an array of P4 registers 
70031 ** that are used as an unpacked index key. 
70032 **
70033 ** Reposition cursor P1 so that  it points to the smallest entry that 
70034 ** is greater than the key value. If there are no records greater than 
70035 ** the key and P2 is not zero, then jump to P2.
70036 **
70037 ** See also: Found, NotFound, Distinct, SeekLt, SeekGe, SeekLe
70038 */
70039 /* Opcode: SeekLt P1 P2 P3 P4 * 
70040 ** Synopsis: key=r[P3@P4]
70041 **
70042 ** If cursor P1 refers to an SQL table (B-Tree that uses integer keys), 
70043 ** use the value in register P3 as a key. If cursor P1 refers 
70044 ** to an SQL index, then P3 is the first in an array of P4 registers 
70045 ** that are used as an unpacked index key. 
70046 **
70047 ** Reposition cursor P1 so that  it points to the largest entry that 
70048 ** is less than the key value. If there are no records less than 
70049 ** the key and P2 is not zero, then jump to P2.
70050 **
70051 ** See also: Found, NotFound, Distinct, SeekGt, SeekGe, SeekLe
70052 */
70053 /* Opcode: SeekLe P1 P2 P3 P4 *
70054 ** Synopsis: key=r[P3@P4]
70055 **
70056 ** If cursor P1 refers to an SQL table (B-Tree that uses integer keys), 
70057 ** use the value in register P3 as a key. If cursor P1 refers 
70058 ** to an SQL index, then P3 is the first in an array of P4 registers 
70059 ** that are used as an unpacked index key. 
70060 **
70061 ** Reposition cursor P1 so that it points to the largest entry that 
70062 ** is less than or equal to the key value. If there are no records 
70063 ** less than or equal to the key and P2 is not zero, then jump to P2.
70064 **
70065 ** See also: Found, NotFound, Distinct, SeekGt, SeekGe, SeekLt
70066 */
70067 case OP_SeekLt:         /* jump, in3 */
70068 case OP_SeekLe:         /* jump, in3 */
70069 case OP_SeekGe:         /* jump, in3 */
70070 case OP_SeekGt: {       /* jump, in3 */
70071 #if 0  /* local variables moved into u.bd */
70072   int res;
70073   int oc;
70074   VdbeCursor *pC;
70075   UnpackedRecord r;
70076   int nField;
70077   i64 iKey;      /* The rowid we are to seek to */
70078 #endif /* local variables moved into u.bd */
70079 
70080   assert( pOp->p1>=0 && pOp->p1<p->nCursor );
70081   assert( pOp->p2!=0 );
70082   u.bd.pC = p->apCsr[pOp->p1];
70083   assert( u.bd.pC!=0 );
70084   assert( u.bd.pC->pseudoTableReg==0 );
70085   assert( OP_SeekLe == OP_SeekLt+1 );
70086   assert( OP_SeekGe == OP_SeekLt+2 );
70087   assert( OP_SeekGt == OP_SeekLt+3 );
70088   assert( u.bd.pC->isOrdered );
70089   assert( u.bd.pC->pCursor!=0 );
70090   u.bd.oc = pOp->opcode;
70091   u.bd.pC->nullRow = 0;
70092   if( u.bd.pC->isTable ){
70093     /* The input value in P3 might be of any type: integer, real, string,
70094     ** blob, or NULL.  But it needs to be an integer before we can do
70095     ** the seek, so covert it. */
70096     pIn3 = &aMem[pOp->p3];
70097     applyNumericAffinity(pIn3);
70098     u.bd.iKey = sqlite3VdbeIntValue(pIn3);
70099     u.bd.pC->rowidIsValid = 0;
70100 
70101     /* If the P3 value could not be converted into an integer without
70102     ** loss of information, then special processing is required... */
70103     if( (pIn3->flags & MEM_Int)==0 ){
70104       if( (pIn3->flags & MEM_Real)==0 ){
70105         /* If the P3 value cannot be converted into any kind of a number,
70106         ** then the seek is not possible, so jump to P2 */
70107         pc = pOp->p2 - 1;
70108         break;
70109       }
70110 
70111       /* If the approximation u.bd.iKey is larger than the actual real search
70112       ** term, substitute >= for > and < for <=. e.g. if the search term
70113       ** is 4.9 and the integer approximation 5:
70114       **
70115       **        (x >  4.9)    ->     (x >= 5)
70116       **        (x <= 4.9)    ->     (x <  5)
70117       */
70118       if( pIn3->r<(double)u.bd.iKey ){
70119         assert( OP_SeekGe==(OP_SeekGt-1) );
70120         assert( OP_SeekLt==(OP_SeekLe-1) );
70121         assert( (OP_SeekLe & 0x0001)==(OP_SeekGt & 0x0001) );
70122         if( (u.bd.oc & 0x0001)==(OP_SeekGt & 0x0001) ) u.bd.oc--;
70123       }
70124 
70125       /* If the approximation u.bd.iKey is smaller than the actual real search
70126       ** term, substitute <= for < and > for >=.  */
70127       else if( pIn3->r>(double)u.bd.iKey ){
70128         assert( OP_SeekLe==(OP_SeekLt+1) );
70129         assert( OP_SeekGt==(OP_SeekGe+1) );
70130         assert( (OP_SeekLt & 0x0001)==(OP_SeekGe & 0x0001) );
70131         if( (u.bd.oc & 0x0001)==(OP_SeekLt & 0x0001) ) u.bd.oc++;
70132       }
70133     }
70134     rc = sqlite3BtreeMovetoUnpacked(u.bd.pC->pCursor, 0, (u64)u.bd.iKey, 0, &u.bd.res);
70135     if( rc!=SQLITE_OK ){
70136       goto abort_due_to_error;
70137     }
70138     if( u.bd.res==0 ){
70139       u.bd.pC->rowidIsValid = 1;
70140       u.bd.pC->lastRowid = u.bd.iKey;
70141     }
70142   }else{
70143     u.bd.nField = pOp->p4.i;
70144     assert( pOp->p4type==P4_INT32 );
70145     assert( u.bd.nField>0 );
70146     u.bd.r.pKeyInfo = u.bd.pC->pKeyInfo;
70147     u.bd.r.nField = (u16)u.bd.nField;
70148 
70149     /* The next line of code computes as follows, only faster:
70150     **   if( u.bd.oc==OP_SeekGt || u.bd.oc==OP_SeekLe ){
70151     **     u.bd.r.flags = UNPACKED_INCRKEY;
70152     **   }else{
70153     **     u.bd.r.flags = 0;
70154     **   }
70155     */
70156     u.bd.r.flags = (u8)(UNPACKED_INCRKEY * (1 & (u.bd.oc - OP_SeekLt)));
70157     assert( u.bd.oc!=OP_SeekGt || u.bd.r.flags==UNPACKED_INCRKEY );
70158     assert( u.bd.oc!=OP_SeekLe || u.bd.r.flags==UNPACKED_INCRKEY );
70159     assert( u.bd.oc!=OP_SeekGe || u.bd.r.flags==0 );
70160     assert( u.bd.oc!=OP_SeekLt || u.bd.r.flags==0 );
70161 
70162     u.bd.r.aMem = &aMem[pOp->p3];
70163 #ifdef SQLITE_DEBUG
70164     { int i; for(i=0; i<u.bd.r.nField; i++) assert( memIsValid(&u.bd.r.aMem[i]) ); }
70165 #endif
70166     ExpandBlob(u.bd.r.aMem);
70167     rc = sqlite3BtreeMovetoUnpacked(u.bd.pC->pCursor, &u.bd.r, 0, 0, &u.bd.res);
70168     if( rc!=SQLITE_OK ){
70169       goto abort_due_to_error;
70170     }
70171     u.bd.pC->rowidIsValid = 0;
70172   }
70173   u.bd.pC->deferredMoveto = 0;
70174   u.bd.pC->cacheStatus = CACHE_STALE;
70175 #ifdef SQLITE_TEST
70176   sqlite3_search_count++;
70177 #endif
70178   if( u.bd.oc>=OP_SeekGe ){  assert( u.bd.oc==OP_SeekGe || u.bd.oc==OP_SeekGt );
70179     if( u.bd.res<0 || (u.bd.res==0 && u.bd.oc==OP_SeekGt) ){
70180       rc = sqlite3BtreeNext(u.bd.pC->pCursor, &u.bd.res);
70181       if( rc!=SQLITE_OK ) goto abort_due_to_error;
70182       u.bd.pC->rowidIsValid = 0;
70183     }else{
70184       u.bd.res = 0;
70185     }
70186   }else{
70187     assert( u.bd.oc==OP_SeekLt || u.bd.oc==OP_SeekLe );
70188     if( u.bd.res>0 || (u.bd.res==0 && u.bd.oc==OP_SeekLt) ){
70189       rc = sqlite3BtreePrevious(u.bd.pC->pCursor, &u.bd.res);
70190       if( rc!=SQLITE_OK ) goto abort_due_to_error;
70191       u.bd.pC->rowidIsValid = 0;
70192     }else{
70193       /* u.bd.res might be negative because the table is empty.  Check to
70194       ** see if this is the case.
70195       */
70196       u.bd.res = sqlite3BtreeEof(u.bd.pC->pCursor);
70197     }
70198   }
70199   assert( pOp->p2>0 );
70200   if( u.bd.res ){
70201     pc = pOp->p2 - 1;
70202   }
70203   break;
70204 }
70205 
70206 /* Opcode: Seek P1 P2 * * *
70207 ** Synopsis:  intkey=r[P2]
70208 **
70209 ** P1 is an open table cursor and P2 is a rowid integer.  Arrange
70210 ** for P1 to move so that it points to the rowid given by P2.
70211 **
70212 ** This is actually a deferred seek.  Nothing actually happens until
70213 ** the cursor is used to read a record.  That way, if no reads
70214 ** occur, no unnecessary I/O happens.
70215 */
70216 case OP_Seek: {    /* in2 */
70217 #if 0  /* local variables moved into u.be */
70218   VdbeCursor *pC;
70219 #endif /* local variables moved into u.be */
70220 
70221   assert( pOp->p1>=0 && pOp->p1<p->nCursor );
70222   u.be.pC = p->apCsr[pOp->p1];
70223   assert( u.be.pC!=0 );
70224   assert( u.be.pC->pCursor!=0 );
70225   assert( u.be.pC->isTable );
70226   u.be.pC->nullRow = 0;
70227   pIn2 = &aMem[pOp->p2];
70228   u.be.pC->movetoTarget = sqlite3VdbeIntValue(pIn2);
70229   u.be.pC->rowidIsValid = 0;
70230   u.be.pC->deferredMoveto = 1;
70231   break;
70232 }
70233   
70234 
70235 /* Opcode: Found P1 P2 P3 P4 *
70236 ** Synopsis: key=r[P3@P4]
70237 **
70238 ** If P4==0 then register P3 holds a blob constructed by MakeRecord.  If
70239 ** P4>0 then register P3 is the first of P4 registers that form an unpacked
70240 ** record.
70241 **
70242 ** Cursor P1 is on an index btree.  If the record identified by P3 and P4
70243 ** is a prefix of any entry in P1 then a jump is made to P2 and
70244 ** P1 is left pointing at the matching entry.
70245 **
70246 ** See also: NotFound, NoConflict, NotExists. SeekGe
70247 */
70248 /* Opcode: NotFound P1 P2 P3 P4 *
70249 ** Synopsis: key=r[P3@P4]
70250 **
70251 ** If P4==0 then register P3 holds a blob constructed by MakeRecord.  If
70252 ** P4>0 then register P3 is the first of P4 registers that form an unpacked
70253 ** record.
70254 ** 
70255 ** Cursor P1 is on an index btree.  If the record identified by P3 and P4
70256 ** is not the prefix of any entry in P1 then a jump is made to P2.  If P1 
70257 ** does contain an entry whose prefix matches the P3/P4 record then control
70258 ** falls through to the next instruction and P1 is left pointing at the
70259 ** matching entry.
70260 **
70261 ** See also: Found, NotExists, NoConflict
70262 */
70263 /* Opcode: NoConflict P1 P2 P3 P4 *
70264 ** Synopsis: key=r[P3@P4]
70265 **
70266 ** If P4==0 then register P3 holds a blob constructed by MakeRecord.  If
70267 ** P4>0 then register P3 is the first of P4 registers that form an unpacked
70268 ** record.
70269 ** 
70270 ** Cursor P1 is on an index btree.  If the record identified by P3 and P4
70271 ** contains any NULL value, jump immediately to P2.  If all terms of the
70272 ** record are not-NULL then a check is done to determine if any row in the
70273 ** P1 index btree has a matching key prefix.  If there are no matches, jump
70274 ** immediately to P2.  If there is a match, fall through and leave the P1
70275 ** cursor pointing to the matching row.
70276 **
70277 ** This opcode is similar to OP_NotFound with the exceptions that the
70278 ** branch is always taken if any part of the search key input is NULL.
70279 **
70280 ** See also: NotFound, Found, NotExists
70281 */
70282 case OP_NoConflict:     /* jump, in3 */
70283 case OP_NotFound:       /* jump, in3 */
70284 case OP_Found: {        /* jump, in3 */
70285 #if 0  /* local variables moved into u.bf */
70286   int alreadyExists;
70287   int ii;
70288   VdbeCursor *pC;
70289   int res;
70290   char *pFree;
70291   UnpackedRecord *pIdxKey;
70292   UnpackedRecord r;
70293   char aTempRec[ROUND8(sizeof(UnpackedRecord)) + sizeof(Mem)*4 + 7];
70294 #endif /* local variables moved into u.bf */
70295 
70296 #ifdef SQLITE_TEST
70297   if( pOp->opcode!=OP_NoConflict ) sqlite3_found_count++;
70298 #endif
70299 
70300   u.bf.alreadyExists = 0;
70301   assert( pOp->p1>=0 && pOp->p1<p->nCursor );
70302   assert( pOp->p4type==P4_INT32 );
70303   u.bf.pC = p->apCsr[pOp->p1];
70304   assert( u.bf.pC!=0 );
70305   pIn3 = &aMem[pOp->p3];
70306   assert( u.bf.pC->pCursor!=0 );
70307   assert( u.bf.pC->isTable==0 );
70308   if( pOp->p4.i>0 ){
70309     u.bf.r.pKeyInfo = u.bf.pC->pKeyInfo;
70310     u.bf.r.nField = (u16)pOp->p4.i;
70311     u.bf.r.aMem = pIn3;
70312 #ifdef SQLITE_DEBUG
70313     {
70314       int i;
70315       for(i=0; i<u.bf.r.nField; i++){
70316         assert( memIsValid(&u.bf.r.aMem[i]) );
70317         if( i ) REGISTER_TRACE(pOp->p3+i, &u.bf.r.aMem[i]);
70318       }
70319     }
70320 #endif
70321     u.bf.r.flags = UNPACKED_PREFIX_MATCH;
70322     u.bf.pIdxKey = &u.bf.r;
70323   }else{
70324     u.bf.pIdxKey = sqlite3VdbeAllocUnpackedRecord(
70325         u.bf.pC->pKeyInfo, u.bf.aTempRec, sizeof(u.bf.aTempRec), &u.bf.pFree
70326     );
70327     if( u.bf.pIdxKey==0 ) goto no_mem;
70328     assert( pIn3->flags & MEM_Blob );
70329     assert( (pIn3->flags & MEM_Zero)==0 );  /* zeroblobs already expanded */
70330     sqlite3VdbeRecordUnpack(u.bf.pC->pKeyInfo, pIn3->n, pIn3->z, u.bf.pIdxKey);
70331     u.bf.pIdxKey->flags |= UNPACKED_PREFIX_MATCH;
70332   }
70333   if( pOp->opcode==OP_NoConflict ){
70334     /* For the OP_NoConflict opcode, take the jump if any of the
70335     ** input fields are NULL, since any key with a NULL will not
70336     ** conflict */
70337     for(u.bf.ii=0; u.bf.ii<u.bf.r.nField; u.bf.ii++){
70338       if( u.bf.r.aMem[u.bf.ii].flags & MEM_Null ){
70339         pc = pOp->p2 - 1;
70340         break;
70341       }
70342     }
70343   }
70344   rc = sqlite3BtreeMovetoUnpacked(u.bf.pC->pCursor, u.bf.pIdxKey, 0, 0, &u.bf.res);
70345   if( pOp->p4.i==0 ){
70346     sqlite3DbFree(db, u.bf.pFree);
70347   }
70348   if( rc!=SQLITE_OK ){
70349     break;
70350   }
70351   u.bf.pC->seekResult = u.bf.res;
70352   u.bf.alreadyExists = (u.bf.res==0);
70353   u.bf.pC->nullRow = 1-u.bf.alreadyExists;
70354   u.bf.pC->deferredMoveto = 0;
70355   u.bf.pC->cacheStatus = CACHE_STALE;
70356   if( pOp->opcode==OP_Found ){
70357     if( u.bf.alreadyExists ) pc = pOp->p2 - 1;
70358   }else{
70359     if( !u.bf.alreadyExists ) pc = pOp->p2 - 1;
70360   }
70361   break;
70362 }
70363 
70364 /* Opcode: NotExists P1 P2 P3 * *
70365 ** Synopsis: intkey=r[P3]
70366 **
70367 ** P1 is the index of a cursor open on an SQL table btree (with integer
70368 ** keys).  P3 is an integer rowid.  If P1 does not contain a record with
70369 ** rowid P3 then jump immediately to P2.  If P1 does contain a record
70370 ** with rowid P3 then leave the cursor pointing at that record and fall
70371 ** through to the next instruction.
70372 **
70373 ** The OP_NotFound opcode performs the same operation on index btrees
70374 ** (with arbitrary multi-value keys).
70375 **
70376 ** See also: Found, NotFound, NoConflict
70377 */
70378 case OP_NotExists: {        /* jump, in3 */
70379 #if 0  /* local variables moved into u.bg */
70380   VdbeCursor *pC;
70381   BtCursor *pCrsr;
70382   int res;
70383   u64 iKey;
70384 #endif /* local variables moved into u.bg */
70385 
70386   pIn3 = &aMem[pOp->p3];
70387   assert( pIn3->flags & MEM_Int );
70388   assert( pOp->p1>=0 && pOp->p1<p->nCursor );
70389   u.bg.pC = p->apCsr[pOp->p1];
70390   assert( u.bg.pC!=0 );
70391   assert( u.bg.pC->isTable );
70392   assert( u.bg.pC->pseudoTableReg==0 );
70393   u.bg.pCrsr = u.bg.pC->pCursor;
70394   assert( u.bg.pCrsr!=0 );
70395   u.bg.res = 0;
70396   u.bg.iKey = pIn3->u.i;
70397   rc = sqlite3BtreeMovetoUnpacked(u.bg.pCrsr, 0, u.bg.iKey, 0, &u.bg.res);
70398   u.bg.pC->lastRowid = pIn3->u.i;
70399   u.bg.pC->rowidIsValid = u.bg.res==0 ?1:0;
70400   u.bg.pC->nullRow = 0;
70401   u.bg.pC->cacheStatus = CACHE_STALE;
70402   u.bg.pC->deferredMoveto = 0;
70403   if( u.bg.res!=0 ){
70404     pc = pOp->p2 - 1;
70405     assert( u.bg.pC->rowidIsValid==0 );
70406   }
70407   u.bg.pC->seekResult = u.bg.res;
70408   break;
70409 }
70410 
70411 /* Opcode: Sequence P1 P2 * * *
70412 ** Synopsis: r[P2]=rowid
70413 **
70414 ** Find the next available sequence number for cursor P1.
70415 ** Write the sequence number into register P2.
70416 ** The sequence number on the cursor is incremented after this
70417 ** instruction.  
70418 */
70419 case OP_Sequence: {           /* out2-prerelease */
70420   assert( pOp->p1>=0 && pOp->p1<p->nCursor );
70421   assert( p->apCsr[pOp->p1]!=0 );
70422   pOut->u.i = p->apCsr[pOp->p1]->seqCount++;
70423   break;
70424 }
70425 
70426 
70427 /* Opcode: NewRowid P1 P2 P3 * *
70428 ** Synopsis: r[P2]=rowid
70429 **
70430 ** Get a new integer record number (a.k.a "rowid") used as the key to a table.
70431 ** The record number is not previously used as a key in the database
70432 ** table that cursor P1 points to.  The new record number is written
70433 ** written to register P2.
70434 **
70435 ** If P3>0 then P3 is a register in the root frame of this VDBE that holds 
70436 ** the largest previously generated record number. No new record numbers are
70437 ** allowed to be less than this value. When this value reaches its maximum, 
70438 ** an SQLITE_FULL error is generated. The P3 register is updated with the '
70439 ** generated record number. This P3 mechanism is used to help implement the
70440 ** AUTOINCREMENT feature.
70441 */
70442 case OP_NewRowid: {           /* out2-prerelease */
70443 #if 0  /* local variables moved into u.bh */
70444   i64 v;                 /* The new rowid */
70445   VdbeCursor *pC;        /* Cursor of table to get the new rowid */
70446   int res;               /* Result of an sqlite3BtreeLast() */
70447   int cnt;               /* Counter to limit the number of searches */
70448   Mem *pMem;             /* Register holding largest rowid for AUTOINCREMENT */
70449   VdbeFrame *pFrame;     /* Root frame of VDBE */
70450 #endif /* local variables moved into u.bh */
70451 
70452   u.bh.v = 0;
70453   u.bh.res = 0;
70454   assert( pOp->p1>=0 && pOp->p1<p->nCursor );
70455   u.bh.pC = p->apCsr[pOp->p1];
70456   assert( u.bh.pC!=0 );
70457   if( NEVER(u.bh.pC->pCursor==0) ){
70458     /* The zero initialization above is all that is needed */
70459   }else{
70460     /* The next rowid or record number (different terms for the same
70461     ** thing) is obtained in a two-step algorithm.
70462     **
70463     ** First we attempt to find the largest existing rowid and add one
70464     ** to that.  But if the largest existing rowid is already the maximum
70465     ** positive integer, we have to fall through to the second
70466     ** probabilistic algorithm
70467     **
70468     ** The second algorithm is to select a rowid at random and see if
70469     ** it already exists in the table.  If it does not exist, we have
70470     ** succeeded.  If the random rowid does exist, we select a new one
70471     ** and try again, up to 100 times.
70472     */
70473     assert( u.bh.pC->isTable );
70474 
70475 #ifdef SQLITE_32BIT_ROWID
70476 #   define MAX_ROWID 0x7fffffff
70477 #else
70478     /* Some compilers complain about constants of the form 0x7fffffffffffffff.
70479     ** Others complain about 0x7ffffffffffffffffLL.  The following macro seems
70480     ** to provide the constant while making all compilers happy.
70481     */
70482 #   define MAX_ROWID  (i64)( (((u64)0x7fffffff)<<32) | (u64)0xffffffff )
70483 #endif
70484 
70485     if( !u.bh.pC->useRandomRowid ){
70486       u.bh.v = sqlite3BtreeGetCachedRowid(u.bh.pC->pCursor);
70487       if( u.bh.v==0 ){
70488         rc = sqlite3BtreeLast(u.bh.pC->pCursor, &u.bh.res);
70489         if( rc!=SQLITE_OK ){
70490           goto abort_due_to_error;
70491         }
70492         if( u.bh.res ){
70493           u.bh.v = 1;   /* IMP: R-61914-48074 */
70494         }else{
70495           assert( sqlite3BtreeCursorIsValid(u.bh.pC->pCursor) );
70496           rc = sqlite3BtreeKeySize(u.bh.pC->pCursor, &u.bh.v);
70497           assert( rc==SQLITE_OK );   /* Cannot fail following BtreeLast() */
70498           if( u.bh.v>=MAX_ROWID ){
70499             u.bh.pC->useRandomRowid = 1;
70500           }else{
70501             u.bh.v++;   /* IMP: R-29538-34987 */
70502           }
70503         }
70504       }
70505 
70506 #ifndef SQLITE_OMIT_AUTOINCREMENT
70507       if( pOp->p3 ){
70508         /* Assert that P3 is a valid memory cell. */
70509         assert( pOp->p3>0 );
70510         if( p->pFrame ){
70511           for(u.bh.pFrame=p->pFrame; u.bh.pFrame->pParent; u.bh.pFrame=u.bh.pFrame->pParent);
70512           /* Assert that P3 is a valid memory cell. */
70513           assert( pOp->p3<=u.bh.pFrame->nMem );
70514           u.bh.pMem = &u.bh.pFrame->aMem[pOp->p3];
70515         }else{
70516           /* Assert that P3 is a valid memory cell. */
70517           assert( pOp->p3<=(p->nMem-p->nCursor) );
70518           u.bh.pMem = &aMem[pOp->p3];
70519           memAboutToChange(p, u.bh.pMem);
70520         }
70521         assert( memIsValid(u.bh.pMem) );
70522 
70523         REGISTER_TRACE(pOp->p3, u.bh.pMem);
70524         sqlite3VdbeMemIntegerify(u.bh.pMem);
70525         assert( (u.bh.pMem->flags & MEM_Int)!=0 );  /* mem(P3) holds an integer */
70526         if( u.bh.pMem->u.i==MAX_ROWID || u.bh.pC->useRandomRowid ){
70527           rc = SQLITE_FULL;   /* IMP: R-12275-61338 */
70528           goto abort_due_to_error;
70529         }
70530         if( u.bh.v<u.bh.pMem->u.i+1 ){
70531           u.bh.v = u.bh.pMem->u.i + 1;
70532         }
70533         u.bh.pMem->u.i = u.bh.v;
70534       }
70535 #endif
70536 
70537       sqlite3BtreeSetCachedRowid(u.bh.pC->pCursor, u.bh.v<MAX_ROWID ? u.bh.v+1 : 0);
70538     }
70539     if( u.bh.pC->useRandomRowid ){
70540       /* IMPLEMENTATION-OF: R-07677-41881 If the largest ROWID is equal to the
70541       ** largest possible integer (9223372036854775807) then the database
70542       ** engine starts picking positive candidate ROWIDs at random until
70543       ** it finds one that is not previously used. */
70544       assert( pOp->p3==0 );  /* We cannot be in random rowid mode if this is
70545                              ** an AUTOINCREMENT table. */
70546       /* on the first attempt, simply do one more than previous */
70547       u.bh.v = lastRowid;
70548       u.bh.v &= (MAX_ROWID>>1); /* ensure doesn't go negative */
70549       u.bh.v++; /* ensure non-zero */
70550       u.bh.cnt = 0;
70551       while(   ((rc = sqlite3BtreeMovetoUnpacked(u.bh.pC->pCursor, 0, (u64)u.bh.v,
70552                                                  0, &u.bh.res))==SQLITE_OK)
70553             && (u.bh.res==0)
70554             && (++u.bh.cnt<100)){
70555         /* collision - try another random rowid */
70556         sqlite3_randomness(sizeof(u.bh.v), &u.bh.v);
70557         if( u.bh.cnt<5 ){
70558           /* try "small" random rowids for the initial attempts */
70559           u.bh.v &= 0xffffff;
70560         }else{
70561           u.bh.v &= (MAX_ROWID>>1); /* ensure doesn't go negative */
70562         }
70563         u.bh.v++; /* ensure non-zero */
70564       }
70565       if( rc==SQLITE_OK && u.bh.res==0 ){
70566         rc = SQLITE_FULL;   /* IMP: R-38219-53002 */
70567         goto abort_due_to_error;
70568       }
70569       assert( u.bh.v>0 );  /* EV: R-40812-03570 */
70570     }
70571     u.bh.pC->rowidIsValid = 0;
70572     u.bh.pC->deferredMoveto = 0;
70573     u.bh.pC->cacheStatus = CACHE_STALE;
70574   }
70575   pOut->u.i = u.bh.v;
70576   break;
70577 }
70578 
70579 /* Opcode: Insert P1 P2 P3 P4 P5
70580 ** Synopsis: intkey=r[P3] data=r[P2]
70581 **
70582 ** Write an entry into the table of cursor P1.  A new entry is
70583 ** created if it doesn't already exist or the data for an existing
70584 ** entry is overwritten.  The data is the value MEM_Blob stored in register
70585 ** number P2. The key is stored in register P3. The key must
70586 ** be a MEM_Int.
70587 **
70588 ** If the OPFLAG_NCHANGE flag of P5 is set, then the row change count is
70589 ** incremented (otherwise not).  If the OPFLAG_LASTROWID flag of P5 is set,
70590 ** then rowid is stored for subsequent return by the
70591 ** sqlite3_last_insert_rowid() function (otherwise it is unmodified).
70592 **
70593 ** If the OPFLAG_USESEEKRESULT flag of P5 is set and if the result of
70594 ** the last seek operation (OP_NotExists) was a success, then this
70595 ** operation will not attempt to find the appropriate row before doing
70596 ** the insert but will instead overwrite the row that the cursor is
70597 ** currently pointing to.  Presumably, the prior OP_NotExists opcode
70598 ** has already positioned the cursor correctly.  This is an optimization
70599 ** that boosts performance by avoiding redundant seeks.
70600 **
70601 ** If the OPFLAG_ISUPDATE flag is set, then this opcode is part of an
70602 ** UPDATE operation.  Otherwise (if the flag is clear) then this opcode
70603 ** is part of an INSERT operation.  The difference is only important to
70604 ** the update hook.
70605 **
70606 ** Parameter P4 may point to a string containing the table-name, or
70607 ** may be NULL. If it is not NULL, then the update-hook 
70608 ** (sqlite3.xUpdateCallback) is invoked following a successful insert.
70609 **
70610 ** (WARNING/TODO: If P1 is a pseudo-cursor and P2 is dynamically
70611 ** allocated, then ownership of P2 is transferred to the pseudo-cursor
70612 ** and register P2 becomes ephemeral.  If the cursor is changed, the
70613 ** value of register P2 will then change.  Make sure this does not
70614 ** cause any problems.)
70615 **
70616 ** This instruction only works on tables.  The equivalent instruction
70617 ** for indices is OP_IdxInsert.
70618 */
70619 /* Opcode: InsertInt P1 P2 P3 P4 P5
70620 ** Synopsis:  intkey=P3 data=r[P2]
70621 **
70622 ** This works exactly like OP_Insert except that the key is the
70623 ** integer value P3, not the value of the integer stored in register P3.
70624 */
70625 case OP_Insert: 
70626 case OP_InsertInt: {
70627 #if 0  /* local variables moved into u.bi */
70628   Mem *pData;       /* MEM cell holding data for the record to be inserted */
70629   Mem *pKey;        /* MEM cell holding key  for the record */
70630   i64 iKey;         /* The integer ROWID or key for the record to be inserted */
70631   VdbeCursor *pC;   /* Cursor to table into which insert is written */
70632   int nZero;        /* Number of zero-bytes to append */
70633   int seekResult;   /* Result of prior seek or 0 if no USESEEKRESULT flag */
70634   const char *zDb;  /* database name - used by the update hook */
70635   const char *zTbl; /* Table name - used by the opdate hook */
70636   int op;           /* Opcode for update hook: SQLITE_UPDATE or SQLITE_INSERT */
70637 #endif /* local variables moved into u.bi */
70638 
70639   u.bi.pData = &aMem[pOp->p2];
70640   assert( pOp->p1>=0 && pOp->p1<p->nCursor );
70641   assert( memIsValid(u.bi.pData) );
70642   u.bi.pC = p->apCsr[pOp->p1];
70643   assert( u.bi.pC!=0 );
70644   assert( u.bi.pC->pCursor!=0 );
70645   assert( u.bi.pC->pseudoTableReg==0 );
70646   assert( u.bi.pC->isTable );
70647   REGISTER_TRACE(pOp->p2, u.bi.pData);
70648 
70649   if( pOp->opcode==OP_Insert ){
70650     u.bi.pKey = &aMem[pOp->p3];
70651     assert( u.bi.pKey->flags & MEM_Int );
70652     assert( memIsValid(u.bi.pKey) );
70653     REGISTER_TRACE(pOp->p3, u.bi.pKey);
70654     u.bi.iKey = u.bi.pKey->u.i;
70655   }else{
70656     assert( pOp->opcode==OP_InsertInt );
70657     u.bi.iKey = pOp->p3;
70658   }
70659 
70660   if( pOp->p5 & OPFLAG_NCHANGE ) p->nChange++;
70661   if( pOp->p5 & OPFLAG_LASTROWID ) db->lastRowid = lastRowid = u.bi.iKey;
70662   if( u.bi.pData->flags & MEM_Null ){
70663     u.bi.pData->z = 0;
70664     u.bi.pData->n = 0;
70665   }else{
70666     assert( u.bi.pData->flags & (MEM_Blob|MEM_Str) );
70667   }
70668   u.bi.seekResult = ((pOp->p5 & OPFLAG_USESEEKRESULT) ? u.bi.pC->seekResult : 0);
70669   if( u.bi.pData->flags & MEM_Zero ){
70670     u.bi.nZero = u.bi.pData->u.nZero;
70671   }else{
70672     u.bi.nZero = 0;
70673   }
70674   sqlite3BtreeSetCachedRowid(u.bi.pC->pCursor, 0);
70675   rc = sqlite3BtreeInsert(u.bi.pC->pCursor, 0, u.bi.iKey,
70676                           u.bi.pData->z, u.bi.pData->n, u.bi.nZero,
70677                           (pOp->p5 & OPFLAG_APPEND)!=0, u.bi.seekResult
70678   );
70679   u.bi.pC->rowidIsValid = 0;
70680   u.bi.pC->deferredMoveto = 0;
70681   u.bi.pC->cacheStatus = CACHE_STALE;
70682 
70683   /* Invoke the update-hook if required. */
70684   if( rc==SQLITE_OK && db->xUpdateCallback && pOp->p4.z ){
70685     u.bi.zDb = db->aDb[u.bi.pC->iDb].zName;
70686     u.bi.zTbl = pOp->p4.z;
70687     u.bi.op = ((pOp->p5 & OPFLAG_ISUPDATE) ? SQLITE_UPDATE : SQLITE_INSERT);
70688     assert( u.bi.pC->isTable );
70689     db->xUpdateCallback(db->pUpdateArg, u.bi.op, u.bi.zDb, u.bi.zTbl, u.bi.iKey);
70690     assert( u.bi.pC->iDb>=0 );
70691   }
70692   break;
70693 }
70694 
70695 /* Opcode: Delete P1 P2 * P4 *
70696 **
70697 ** Delete the record at which the P1 cursor is currently pointing.
70698 **
70699 ** The cursor will be left pointing at either the next or the previous
70700 ** record in the table. If it is left pointing at the next record, then
70701 ** the next Next instruction will be a no-op.  Hence it is OK to delete
70702 ** a record from within an Next loop.
70703 **
70704 ** If the OPFLAG_NCHANGE flag of P2 is set, then the row change count is
70705 ** incremented (otherwise not).
70706 **
70707 ** P1 must not be pseudo-table.  It has to be a real table with
70708 ** multiple rows.
70709 **
70710 ** If P4 is not NULL, then it is the name of the table that P1 is
70711 ** pointing to.  The update hook will be invoked, if it exists.
70712 ** If P4 is not NULL then the P1 cursor must have been positioned
70713 ** using OP_NotFound prior to invoking this opcode.
70714 */
70715 case OP_Delete: {
70716 #if 0  /* local variables moved into u.bj */
70717   i64 iKey;
70718   VdbeCursor *pC;
70719 #endif /* local variables moved into u.bj */
70720 
70721   assert( pOp->p1>=0 && pOp->p1<p->nCursor );
70722   u.bj.pC = p->apCsr[pOp->p1];
70723   assert( u.bj.pC!=0 );
70724   assert( u.bj.pC->pCursor!=0 );  /* Only valid for real tables, no pseudotables */
70725   u.bj.iKey = u.bj.pC->lastRowid;      /* Only used for the update hook */
70726 
70727   /* The OP_Delete opcode always follows an OP_NotExists or OP_Last or
70728   ** OP_Column on the same table without any intervening operations that
70729   ** might move or invalidate the cursor.  Hence cursor u.bj.pC is always pointing
70730   ** to the row to be deleted and the sqlite3VdbeCursorMoveto() operation
70731   ** below is always a no-op and cannot fail.  We will run it anyhow, though,
70732   ** to guard against future changes to the code generator.
70733   **/
70734   assert( u.bj.pC->deferredMoveto==0 );
70735   rc = sqlite3VdbeCursorMoveto(u.bj.pC);
70736   if( NEVER(rc!=SQLITE_OK) ) goto abort_due_to_error;
70737 
70738   sqlite3BtreeSetCachedRowid(u.bj.pC->pCursor, 0);
70739   rc = sqlite3BtreeDelete(u.bj.pC->pCursor);
70740   u.bj.pC->cacheStatus = CACHE_STALE;
70741 
70742   /* Invoke the update-hook if required. */
70743   if( rc==SQLITE_OK && db->xUpdateCallback && pOp->p4.z && u.bj.pC->isTable ){
70744     db->xUpdateCallback(db->pUpdateArg, SQLITE_DELETE,
70745                         db->aDb[u.bj.pC->iDb].zName, pOp->p4.z, u.bj.iKey);
70746     assert( u.bj.pC->iDb>=0 );
70747   }
70748   if( pOp->p2 & OPFLAG_NCHANGE ) p->nChange++;
70749   break;
70750 }
70751 /* Opcode: ResetCount * * * * *
70752 **
70753 ** The value of the change counter is copied to the database handle
70754 ** change counter (returned by subsequent calls to sqlite3_changes()).
70755 ** Then the VMs internal change counter resets to 0.
70756 ** This is used by trigger programs.
70757 */
70758 case OP_ResetCount: {
70759   sqlite3VdbeSetChanges(db, p->nChange);
70760   p->nChange = 0;
70761   break;
70762 }
70763 
70764 /* Opcode: SorterCompare P1 P2 P3 P4
70765 ** Synopsis:  if key(P1)!=rtrim(r[P3],P4) goto P2
70766 **
70767 ** P1 is a sorter cursor. This instruction compares a prefix of the
70768 ** the record blob in register P3 against a prefix of the entry that 
70769 ** the sorter cursor currently points to.  The final P4 fields of both
70770 ** the P3 and sorter record are ignored.
70771 **
70772 ** If either P3 or the sorter contains a NULL in one of their significant
70773 ** fields (not counting the P4 fields at the end which are ignored) then
70774 ** the comparison is assumed to be equal.
70775 **
70776 ** Fall through to next instruction if the two records compare equal to
70777 ** each other.  Jump to P2 if they are different.
70778 */
70779 case OP_SorterCompare: {
70780 #if 0  /* local variables moved into u.bk */
70781   VdbeCursor *pC;
70782   int res;
70783   int nIgnore;
70784 #endif /* local variables moved into u.bk */
70785 
70786   u.bk.pC = p->apCsr[pOp->p1];
70787   assert( isSorter(u.bk.pC) );
70788   assert( pOp->p4type==P4_INT32 );
70789   pIn3 = &aMem[pOp->p3];
70790   u.bk.nIgnore = pOp->p4.i;
70791   rc = sqlite3VdbeSorterCompare(u.bk.pC, pIn3, u.bk.nIgnore, &u.bk.res);
70792   if( u.bk.res ){
70793     pc = pOp->p2-1;
70794   }
70795   break;
70796 };
70797 
70798 /* Opcode: SorterData P1 P2 * * *
70799 ** Synopsis: r[P2]=data
70800 **
70801 ** Write into register P2 the current sorter data for sorter cursor P1.
70802 */
70803 case OP_SorterData: {
70804 #if 0  /* local variables moved into u.bl */
70805   VdbeCursor *pC;
70806 #endif /* local variables moved into u.bl */
70807 
70808   pOut = &aMem[pOp->p2];
70809   u.bl.pC = p->apCsr[pOp->p1];
70810   assert( isSorter(u.bl.pC) );
70811   rc = sqlite3VdbeSorterRowkey(u.bl.pC, pOut);
70812   break;
70813 }
70814 
70815 /* Opcode: RowData P1 P2 * * *
70816 ** Synopsis: r[P2]=data
70817 **
70818 ** Write into register P2 the complete row data for cursor P1.
70819 ** There is no interpretation of the data.  
70820 ** It is just copied onto the P2 register exactly as 
70821 ** it is found in the database file.
70822 **
70823 ** If the P1 cursor must be pointing to a valid row (not a NULL row)
70824 ** of a real table, not a pseudo-table.
70825 */
70826 /* Opcode: RowKey P1 P2 * * *
70827 ** Synopsis: r[P2]=key
70828 **
70829 ** Write into register P2 the complete row key for cursor P1.
70830 ** There is no interpretation of the data.  
70831 ** The key is copied onto the P3 register exactly as 
70832 ** it is found in the database file.
70833 **
70834 ** If the P1 cursor must be pointing to a valid row (not a NULL row)
70835 ** of a real table, not a pseudo-table.
70836 */
70837 case OP_RowKey:
70838 case OP_RowData: {
70839 #if 0  /* local variables moved into u.bm */
70840   VdbeCursor *pC;
70841   BtCursor *pCrsr;
70842   u32 n;
70843   i64 n64;
70844 #endif /* local variables moved into u.bm */
70845 
70846   pOut = &aMem[pOp->p2];
70847   memAboutToChange(p, pOut);
70848 
70849   /* Note that RowKey and RowData are really exactly the same instruction */
70850   assert( pOp->p1>=0 && pOp->p1<p->nCursor );
70851   u.bm.pC = p->apCsr[pOp->p1];
70852   assert( isSorter(u.bm.pC)==0 );
70853   assert( u.bm.pC->isTable || pOp->opcode!=OP_RowData );
70854   assert( u.bm.pC->isTable==0 || pOp->opcode==OP_RowData );
70855   assert( u.bm.pC!=0 );
70856   assert( u.bm.pC->nullRow==0 );
70857   assert( u.bm.pC->pseudoTableReg==0 );
70858   assert( u.bm.pC->pCursor!=0 );
70859   u.bm.pCrsr = u.bm.pC->pCursor;
70860   assert( sqlite3BtreeCursorIsValid(u.bm.pCrsr) );
70861 
70862   /* The OP_RowKey and OP_RowData opcodes always follow OP_NotExists or
70863   ** OP_Rewind/Op_Next with no intervening instructions that might invalidate
70864   ** the cursor.  Hence the following sqlite3VdbeCursorMoveto() call is always
70865   ** a no-op and can never fail.  But we leave it in place as a safety.
70866   */
70867   assert( u.bm.pC->deferredMoveto==0 );
70868   rc = sqlite3VdbeCursorMoveto(u.bm.pC);
70869   if( NEVER(rc!=SQLITE_OK) ) goto abort_due_to_error;
70870 
70871   if( u.bm.pC->isTable==0 ){
70872     assert( !u.bm.pC->isTable );
70873     VVA_ONLY(rc =) sqlite3BtreeKeySize(u.bm.pCrsr, &u.bm.n64);
70874     assert( rc==SQLITE_OK );    /* True because of CursorMoveto() call above */
70875     if( u.bm.n64>db->aLimit[SQLITE_LIMIT_LENGTH] ){
70876       goto too_big;
70877     }
70878     u.bm.n = (u32)u.bm.n64;
70879   }else{
70880     VVA_ONLY(rc =) sqlite3BtreeDataSize(u.bm.pCrsr, &u.bm.n);
70881     assert( rc==SQLITE_OK );    /* DataSize() cannot fail */
70882     if( u.bm.n>(u32)db->aLimit[SQLITE_LIMIT_LENGTH] ){
70883       goto too_big;
70884     }
70885   }
70886   if( sqlite3VdbeMemGrow(pOut, u.bm.n, 0) ){
70887     goto no_mem;
70888   }
70889   pOut->n = u.bm.n;
70890   MemSetTypeFlag(pOut, MEM_Blob);
70891   if( u.bm.pC->isTable==0 ){
70892     rc = sqlite3BtreeKey(u.bm.pCrsr, 0, u.bm.n, pOut->z);
70893   }else{
70894     rc = sqlite3BtreeData(u.bm.pCrsr, 0, u.bm.n, pOut->z);
70895   }
70896   pOut->enc = SQLITE_UTF8;  /* In case the blob is ever cast to text */
70897   UPDATE_MAX_BLOBSIZE(pOut);
70898   REGISTER_TRACE(pOp->p2, pOut);
70899   break;
70900 }
70901 
70902 /* Opcode: Rowid P1 P2 * * *
70903 ** Synopsis: r[P2]=rowid
70904 **
70905 ** Store in register P2 an integer which is the key of the table entry that
70906 ** P1 is currently point to.
70907 **
70908 ** P1 can be either an ordinary table or a virtual table.  There used to
70909 ** be a separate OP_VRowid opcode for use with virtual tables, but this
70910 ** one opcode now works for both table types.
70911 */
70912 case OP_Rowid: {                 /* out2-prerelease */
70913 #if 0  /* local variables moved into u.bn */
70914   VdbeCursor *pC;
70915   i64 v;
70916   sqlite3_vtab *pVtab;
70917   const sqlite3_module *pModule;
70918 #endif /* local variables moved into u.bn */
70919 
70920   assert( pOp->p1>=0 && pOp->p1<p->nCursor );
70921   u.bn.pC = p->apCsr[pOp->p1];
70922   assert( u.bn.pC!=0 );
70923   assert( u.bn.pC->pseudoTableReg==0 || u.bn.pC->nullRow );
70924   if( u.bn.pC->nullRow ){
70925     pOut->flags = MEM_Null;
70926     break;
70927   }else if( u.bn.pC->deferredMoveto ){
70928     u.bn.v = u.bn.pC->movetoTarget;
70929 #ifndef SQLITE_OMIT_VIRTUALTABLE
70930   }else if( u.bn.pC->pVtabCursor ){
70931     u.bn.pVtab = u.bn.pC->pVtabCursor->pVtab;
70932     u.bn.pModule = u.bn.pVtab->pModule;
70933     assert( u.bn.pModule->xRowid );
70934     rc = u.bn.pModule->xRowid(u.bn.pC->pVtabCursor, &u.bn.v);
70935     sqlite3VtabImportErrmsg(p, u.bn.pVtab);
70936 #endif /* SQLITE_OMIT_VIRTUALTABLE */
70937   }else{
70938     assert( u.bn.pC->pCursor!=0 );
70939     rc = sqlite3VdbeCursorMoveto(u.bn.pC);
70940     if( rc ) goto abort_due_to_error;
70941     if( u.bn.pC->rowidIsValid ){
70942       u.bn.v = u.bn.pC->lastRowid;
70943     }else{
70944       rc = sqlite3BtreeKeySize(u.bn.pC->pCursor, &u.bn.v);
70945       assert( rc==SQLITE_OK );  /* Always so because of CursorMoveto() above */
70946     }
70947   }
70948   pOut->u.i = u.bn.v;
70949   break;
70950 }
70951 
70952 /* Opcode: NullRow P1 * * * *
70953 **
70954 ** Move the cursor P1 to a null row.  Any OP_Column operations
70955 ** that occur while the cursor is on the null row will always
70956 ** write a NULL.
70957 */
70958 case OP_NullRow: {
70959 #if 0  /* local variables moved into u.bo */
70960   VdbeCursor *pC;
70961 #endif /* local variables moved into u.bo */
70962 
70963   assert( pOp->p1>=0 && pOp->p1<p->nCursor );
70964   u.bo.pC = p->apCsr[pOp->p1];
70965   assert( u.bo.pC!=0 );
70966   u.bo.pC->nullRow = 1;
70967   u.bo.pC->rowidIsValid = 0;
70968   u.bo.pC->cacheStatus = CACHE_STALE;
70969   assert( u.bo.pC->pCursor || u.bo.pC->pVtabCursor );
70970   if( u.bo.pC->pCursor ){
70971     sqlite3BtreeClearCursor(u.bo.pC->pCursor);
70972   }
70973   break;
70974 }
70975 
70976 /* Opcode: Last P1 P2 * * *
70977 **
70978 ** The next use of the Rowid or Column or Next instruction for P1 
70979 ** will refer to the last entry in the database table or index.
70980 ** If the table or index is empty and P2>0, then jump immediately to P2.
70981 ** If P2 is 0 or if the table or index is not empty, fall through
70982 ** to the following instruction.
70983 */
70984 case OP_Last: {        /* jump */
70985 #if 0  /* local variables moved into u.bp */
70986   VdbeCursor *pC;
70987   BtCursor *pCrsr;
70988   int res;
70989 #endif /* local variables moved into u.bp */
70990 
70991   assert( pOp->p1>=0 && pOp->p1<p->nCursor );
70992   u.bp.pC = p->apCsr[pOp->p1];
70993   assert( u.bp.pC!=0 );
70994   u.bp.pCrsr = u.bp.pC->pCursor;
70995   u.bp.res = 0;
70996   assert( u.bp.pCrsr!=0 );
70997   rc = sqlite3BtreeLast(u.bp.pCrsr, &u.bp.res);
70998   u.bp.pC->nullRow = (u8)u.bp.res;
70999   u.bp.pC->deferredMoveto = 0;
71000   u.bp.pC->rowidIsValid = 0;
71001   u.bp.pC->cacheStatus = CACHE_STALE;
71002   if( pOp->p2>0 && u.bp.res ){
71003     pc = pOp->p2 - 1;
71004   }
71005   break;
71006 }
71007 
71008 
71009 /* Opcode: Sort P1 P2 * * *
71010 **
71011 ** This opcode does exactly the same thing as OP_Rewind except that
71012 ** it increments an undocumented global variable used for testing.
71013 **
71014 ** Sorting is accomplished by writing records into a sorting index,
71015 ** then rewinding that index and playing it back from beginning to
71016 ** end.  We use the OP_Sort opcode instead of OP_Rewind to do the
71017 ** rewinding so that the global variable will be incremented and
71018 ** regression tests can determine whether or not the optimizer is
71019 ** correctly optimizing out sorts.
71020 */
71021 case OP_SorterSort:    /* jump */
71022 case OP_Sort: {        /* jump */
71023 #ifdef SQLITE_TEST
71024   sqlite3_sort_count++;
71025   sqlite3_search_count--;
71026 #endif
71027   p->aCounter[SQLITE_STMTSTATUS_SORT]++;
71028   /* Fall through into OP_Rewind */
71029 }
71030 /* Opcode: Rewind P1 P2 * * *
71031 **
71032 ** The next use of the Rowid or Column or Next instruction for P1 
71033 ** will refer to the first entry in the database table or index.
71034 ** If the table or index is empty and P2>0, then jump immediately to P2.
71035 ** If P2 is 0 or if the table or index is not empty, fall through
71036 ** to the following instruction.
71037 */
71038 case OP_Rewind: {        /* jump */
71039 #if 0  /* local variables moved into u.bq */
71040   VdbeCursor *pC;
71041   BtCursor *pCrsr;
71042   int res;
71043 #endif /* local variables moved into u.bq */
71044 
71045   assert( pOp->p1>=0 && pOp->p1<p->nCursor );
71046   u.bq.pC = p->apCsr[pOp->p1];
71047   assert( u.bq.pC!=0 );
71048   assert( isSorter(u.bq.pC)==(pOp->opcode==OP_SorterSort) );
71049   u.bq.res = 1;
71050   if( isSorter(u.bq.pC) ){
71051     rc = sqlite3VdbeSorterRewind(db, u.bq.pC, &u.bq.res);
71052   }else{
71053     u.bq.pCrsr = u.bq.pC->pCursor;
71054     assert( u.bq.pCrsr );
71055     rc = sqlite3BtreeFirst(u.bq.pCrsr, &u.bq.res);
71056     u.bq.pC->deferredMoveto = 0;
71057     u.bq.pC->cacheStatus = CACHE_STALE;
71058     u.bq.pC->rowidIsValid = 0;
71059   }
71060   u.bq.pC->nullRow = (u8)u.bq.res;
71061   assert( pOp->p2>0 && pOp->p2<p->nOp );
71062   if( u.bq.res ){
71063     pc = pOp->p2 - 1;
71064   }
71065   break;
71066 }
71067 
71068 /* Opcode: Next P1 P2 * * P5
71069 **
71070 ** Advance cursor P1 so that it points to the next key/data pair in its
71071 ** table or index.  If there are no more key/value pairs then fall through
71072 ** to the following instruction.  But if the cursor advance was successful,
71073 ** jump immediately to P2.
71074 **
71075 ** The P1 cursor must be for a real table, not a pseudo-table.  P1 must have
71076 ** been opened prior to this opcode or the program will segfault.
71077 **
71078 ** P4 is always of type P4_ADVANCE. The function pointer points to
71079 ** sqlite3BtreeNext().
71080 **
71081 ** If P5 is positive and the jump is taken, then event counter
71082 ** number P5-1 in the prepared statement is incremented.
71083 **
71084 ** See also: Prev, NextIfOpen
71085 */
71086 /* Opcode: NextIfOpen P1 P2 * * P5
71087 **
71088 ** This opcode works just like OP_Next except that if cursor P1 is not
71089 ** open it behaves a no-op.
71090 */
71091 /* Opcode: Prev P1 P2 * * P5
71092 **
71093 ** Back up cursor P1 so that it points to the previous key/data pair in its
71094 ** table or index.  If there is no previous key/value pairs then fall through
71095 ** to the following instruction.  But if the cursor backup was successful,
71096 ** jump immediately to P2.
71097 **
71098 ** The P1 cursor must be for a real table, not a pseudo-table.  If P1 is
71099 ** not open then the behavior is undefined.
71100 **
71101 ** P4 is always of type P4_ADVANCE. The function pointer points to
71102 ** sqlite3BtreePrevious().
71103 **
71104 ** If P5 is positive and the jump is taken, then event counter
71105 ** number P5-1 in the prepared statement is incremented.
71106 */
71107 /* Opcode: PrevIfOpen P1 P2 * * P5
71108 **
71109 ** This opcode works just like OP_Prev except that if cursor P1 is not
71110 ** open it behaves a no-op.
71111 */
71112 case OP_SorterNext: {  /* jump */
71113 #if 0  /* local variables moved into u.br */
71114   VdbeCursor *pC;
71115   int res;
71116 #endif /* local variables moved into u.br */
71117 
71118   u.br.pC = p->apCsr[pOp->p1];
71119   assert( isSorter(u.br.pC) );
71120   rc = sqlite3VdbeSorterNext(db, u.br.pC, &u.br.res);
71121   goto next_tail;
71122 case OP_PrevIfOpen:    /* jump */
71123 case OP_NextIfOpen:    /* jump */
71124   if( p->apCsr[pOp->p1]==0 ) break;
71125   /* Fall through */
71126 case OP_Prev:          /* jump */
71127 case OP_Next:          /* jump */
71128   assert( pOp->p1>=0 && pOp->p1<p->nCursor );
71129   assert( pOp->p5<ArraySize(p->aCounter) );
71130   u.br.pC = p->apCsr[pOp->p1];
71131   assert( u.br.pC!=0 );
71132   assert( u.br.pC->deferredMoveto==0 );
71133   assert( u.br.pC->pCursor );
71134   assert( pOp->opcode!=OP_Next || pOp->p4.xAdvance==sqlite3BtreeNext );
71135   assert( pOp->opcode!=OP_Prev || pOp->p4.xAdvance==sqlite3BtreePrevious );
71136   assert( pOp->opcode!=OP_NextIfOpen || pOp->p4.xAdvance==sqlite3BtreeNext );
71137   assert( pOp->opcode!=OP_PrevIfOpen || pOp->p4.xAdvance==sqlite3BtreePrevious);
71138   rc = pOp->p4.xAdvance(u.br.pC->pCursor, &u.br.res);
71139 next_tail:
71140   u.br.pC->cacheStatus = CACHE_STALE;
71141   if( u.br.res==0 ){
71142     u.br.pC->nullRow = 0;
71143     pc = pOp->p2 - 1;
71144     p->aCounter[pOp->p5]++;
71145 #ifdef SQLITE_TEST
71146     sqlite3_search_count++;
71147 #endif
71148   }else{
71149     u.br.pC->nullRow = 1;
71150   }
71151   u.br.pC->rowidIsValid = 0;
71152   goto check_for_interrupt;
71153 }
71154 
71155 /* Opcode: IdxInsert P1 P2 P3 * P5
71156 ** Synopsis: key=r[P2]
71157 **
71158 ** Register P2 holds an SQL index key made using the
71159 ** MakeRecord instructions.  This opcode writes that key
71160 ** into the index P1.  Data for the entry is nil.
71161 **
71162 ** P3 is a flag that provides a hint to the b-tree layer that this
71163 ** insert is likely to be an append.
71164 **
71165 ** This instruction only works for indices.  The equivalent instruction
71166 ** for tables is OP_Insert.
71167 */
71168 case OP_SorterInsert:       /* in2 */
71169 case OP_IdxInsert: {        /* in2 */
71170 #if 0  /* local variables moved into u.bs */
71171   VdbeCursor *pC;
71172   BtCursor *pCrsr;
71173   int nKey;
71174   const char *zKey;
71175 #endif /* local variables moved into u.bs */
71176 
71177   assert( pOp->p1>=0 && pOp->p1<p->nCursor );
71178   u.bs.pC = p->apCsr[pOp->p1];
71179   assert( u.bs.pC!=0 );
71180   assert( isSorter(u.bs.pC)==(pOp->opcode==OP_SorterInsert) );
71181   pIn2 = &aMem[pOp->p2];
71182   assert( pIn2->flags & MEM_Blob );
71183   u.bs.pCrsr = u.bs.pC->pCursor;
71184   if( pOp->p5 & OPFLAG_NCHANGE ) p->nChange++;
71185   assert( u.bs.pCrsr!=0 );
71186   assert( u.bs.pC->isTable==0 );
71187   rc = ExpandBlob(pIn2);
71188   if( rc==SQLITE_OK ){
71189     if( isSorter(u.bs.pC) ){
71190       rc = sqlite3VdbeSorterWrite(db, u.bs.pC, pIn2);
71191     }else{
71192       u.bs.nKey = pIn2->n;
71193       u.bs.zKey = pIn2->z;
71194       rc = sqlite3BtreeInsert(u.bs.pCrsr, u.bs.zKey, u.bs.nKey, "", 0, 0, pOp->p3,
71195           ((pOp->p5 & OPFLAG_USESEEKRESULT) ? u.bs.pC->seekResult : 0)
71196           );
71197       assert( u.bs.pC->deferredMoveto==0 );
71198       u.bs.pC->cacheStatus = CACHE_STALE;
71199     }
71200   }
71201   break;
71202 }
71203 
71204 /* Opcode: IdxDelete P1 P2 P3 * *
71205 ** Synopsis: key=r[P2@P3]
71206 **
71207 ** The content of P3 registers starting at register P2 form
71208 ** an unpacked index key. This opcode removes that entry from the 
71209 ** index opened by cursor P1.
71210 */
71211 case OP_IdxDelete: {
71212 #if 0  /* local variables moved into u.bt */
71213   VdbeCursor *pC;
71214   BtCursor *pCrsr;
71215   int res;
71216   UnpackedRecord r;
71217 #endif /* local variables moved into u.bt */
71218 
71219   assert( pOp->p3>0 );
71220   assert( pOp->p2>0 && pOp->p2+pOp->p3<=(p->nMem-p->nCursor)+1 );
71221   assert( pOp->p1>=0 && pOp->p1<p->nCursor );
71222   u.bt.pC = p->apCsr[pOp->p1];
71223   assert( u.bt.pC!=0 );
71224   u.bt.pCrsr = u.bt.pC->pCursor;
71225   assert( u.bt.pCrsr!=0 );
71226   assert( pOp->p5==0 );
71227   u.bt.r.pKeyInfo = u.bt.pC->pKeyInfo;
71228   u.bt.r.nField = (u16)pOp->p3;
71229   u.bt.r.flags = UNPACKED_PREFIX_MATCH;
71230   u.bt.r.aMem = &aMem[pOp->p2];
71231 #ifdef SQLITE_DEBUG
71232   { int i; for(i=0; i<u.bt.r.nField; i++) assert( memIsValid(&u.bt.r.aMem[i]) ); }
71233 #endif
71234   rc = sqlite3BtreeMovetoUnpacked(u.bt.pCrsr, &u.bt.r, 0, 0, &u.bt.res);
71235   if( rc==SQLITE_OK && u.bt.res==0 ){
71236     rc = sqlite3BtreeDelete(u.bt.pCrsr);
71237   }
71238   assert( u.bt.pC->deferredMoveto==0 );
71239   u.bt.pC->cacheStatus = CACHE_STALE;
71240   break;
71241 }
71242 
71243 /* Opcode: IdxRowid P1 P2 * * *
71244 ** Synopsis: r[P2]=rowid
71245 **
71246 ** Write into register P2 an integer which is the last entry in the record at
71247 ** the end of the index key pointed to by cursor P1.  This integer should be
71248 ** the rowid of the table entry to which this index entry points.
71249 **
71250 ** See also: Rowid, MakeRecord.
71251 */
71252 case OP_IdxRowid: {              /* out2-prerelease */
71253 #if 0  /* local variables moved into u.bu */
71254   BtCursor *pCrsr;
71255   VdbeCursor *pC;
71256   i64 rowid;
71257 #endif /* local variables moved into u.bu */
71258 
71259   assert( pOp->p1>=0 && pOp->p1<p->nCursor );
71260   u.bu.pC = p->apCsr[pOp->p1];
71261   assert( u.bu.pC!=0 );
71262   u.bu.pCrsr = u.bu.pC->pCursor;
71263   assert( u.bu.pCrsr!=0 );
71264   pOut->flags = MEM_Null;
71265   rc = sqlite3VdbeCursorMoveto(u.bu.pC);
71266   if( NEVER(rc) ) goto abort_due_to_error;
71267   assert( u.bu.pC->deferredMoveto==0 );
71268   assert( u.bu.pC->isTable==0 );
71269   if( !u.bu.pC->nullRow ){
71270     rc = sqlite3VdbeIdxRowid(db, u.bu.pCrsr, &u.bu.rowid);
71271     if( rc!=SQLITE_OK ){
71272       goto abort_due_to_error;
71273     }
71274     pOut->u.i = u.bu.rowid;
71275     pOut->flags = MEM_Int;
71276   }
71277   break;
71278 }
71279 
71280 /* Opcode: IdxGE P1 P2 P3 P4 P5
71281 ** Synopsis: key=r[P3@P4]
71282 **
71283 ** The P4 register values beginning with P3 form an unpacked index 
71284 ** key that omits the ROWID.  Compare this key value against the index 
71285 ** that P1 is currently pointing to, ignoring the ROWID on the P1 index.
71286 **
71287 ** If the P1 index entry is greater than or equal to the key value
71288 ** then jump to P2.  Otherwise fall through to the next instruction.
71289 **
71290 ** If P5 is non-zero then the key value is increased by an epsilon 
71291 ** prior to the comparison.  This make the opcode work like IdxGT except
71292 ** that if the key from register P3 is a prefix of the key in the cursor,
71293 ** the result is false whereas it would be true with IdxGT.
71294 */
71295 /* Opcode: IdxLT P1 P2 P3 P4 P5
71296 ** Synopsis: key=r[P3@P4]
71297 **
71298 ** The P4 register values beginning with P3 form an unpacked index 
71299 ** key that omits the ROWID.  Compare this key value against the index 
71300 ** that P1 is currently pointing to, ignoring the ROWID on the P1 index.
71301 **
71302 ** If the P1 index entry is less than the key value then jump to P2.
71303 ** Otherwise fall through to the next instruction.
71304 **
71305 ** If P5 is non-zero then the key value is increased by an epsilon prior 
71306 ** to the comparison.  This makes the opcode work like IdxLE.
71307 */
71308 case OP_IdxLT:          /* jump */
71309 case OP_IdxGE: {        /* jump */
71310 #if 0  /* local variables moved into u.bv */
71311   VdbeCursor *pC;
71312   int res;
71313   UnpackedRecord r;
71314 #endif /* local variables moved into u.bv */
71315 
71316   assert( pOp->p1>=0 && pOp->p1<p->nCursor );
71317   u.bv.pC = p->apCsr[pOp->p1];
71318   assert( u.bv.pC!=0 );
71319   assert( u.bv.pC->isOrdered );
71320   assert( u.bv.pC->pCursor!=0);
71321   assert( u.bv.pC->deferredMoveto==0 );
71322   assert( pOp->p5==0 || pOp->p5==1 );
71323   assert( pOp->p4type==P4_INT32 );
71324   u.bv.r.pKeyInfo = u.bv.pC->pKeyInfo;
71325   u.bv.r.nField = (u16)pOp->p4.i;
71326   if( pOp->p5 ){
71327     u.bv.r.flags = UNPACKED_INCRKEY | UNPACKED_PREFIX_MATCH;
71328   }else{
71329     u.bv.r.flags = UNPACKED_PREFIX_MATCH;
71330   }
71331   u.bv.r.aMem = &aMem[pOp->p3];
71332 #ifdef SQLITE_DEBUG
71333   { int i; for(i=0; i<u.bv.r.nField; i++) assert( memIsValid(&u.bv.r.aMem[i]) ); }
71334 #endif
71335   rc = sqlite3VdbeIdxKeyCompare(u.bv.pC, &u.bv.r, &u.bv.res);
71336   if( pOp->opcode==OP_IdxLT ){
71337     u.bv.res = -u.bv.res;
71338   }else{
71339     assert( pOp->opcode==OP_IdxGE );
71340     u.bv.res++;
71341   }
71342   if( u.bv.res>0 ){
71343     pc = pOp->p2 - 1 ;
71344   }
71345   break;
71346 }
71347 
71348 /* Opcode: Destroy P1 P2 P3 * *
71349 **
71350 ** Delete an entire database table or index whose root page in the database
71351 ** file is given by P1.
71352 **
71353 ** The table being destroyed is in the main database file if P3==0.  If
71354 ** P3==1 then the table to be clear is in the auxiliary database file
71355 ** that is used to store tables create using CREATE TEMPORARY TABLE.
71356 **
71357 ** If AUTOVACUUM is enabled then it is possible that another root page
71358 ** might be moved into the newly deleted root page in order to keep all
71359 ** root pages contiguous at the beginning of the database.  The former
71360 ** value of the root page that moved - its value before the move occurred -
71361 ** is stored in register P2.  If no page 
71362 ** movement was required (because the table being dropped was already 
71363 ** the last one in the database) then a zero is stored in register P2.
71364 ** If AUTOVACUUM is disabled then a zero is stored in register P2.
71365 **
71366 ** See also: Clear
71367 */
71368 case OP_Destroy: {     /* out2-prerelease */
71369 #if 0  /* local variables moved into u.bw */
71370   int iMoved;
71371   int iCnt;
71372   Vdbe *pVdbe;
71373   int iDb;
71374 #endif /* local variables moved into u.bw */
71375 
71376   assert( p->readOnly==0 );
71377 #ifndef SQLITE_OMIT_VIRTUALTABLE
71378   u.bw.iCnt = 0;
71379   for(u.bw.pVdbe=db->pVdbe; u.bw.pVdbe; u.bw.pVdbe = u.bw.pVdbe->pNext){
71380     if( u.bw.pVdbe->magic==VDBE_MAGIC_RUN && u.bw.pVdbe->bIsReader
71381      && u.bw.pVdbe->inVtabMethod<2 && u.bw.pVdbe->pc>=0
71382     ){
71383       u.bw.iCnt++;
71384     }
71385   }
71386 #else
71387   u.bw.iCnt = db->nVdbeRead;
71388 #endif
71389   pOut->flags = MEM_Null;
71390   if( u.bw.iCnt>1 ){
71391     rc = SQLITE_LOCKED;
71392     p->errorAction = OE_Abort;
71393   }else{
71394     u.bw.iDb = pOp->p3;
71395     assert( u.bw.iCnt==1 );
71396     assert( (p->btreeMask & (((yDbMask)1)<<u.bw.iDb))!=0 );
71397     rc = sqlite3BtreeDropTable(db->aDb[u.bw.iDb].pBt, pOp->p1, &u.bw.iMoved);
71398     pOut->flags = MEM_Int;
71399     pOut->u.i = u.bw.iMoved;
71400 #ifndef SQLITE_OMIT_AUTOVACUUM
71401     if( rc==SQLITE_OK && u.bw.iMoved!=0 ){
71402       sqlite3RootPageMoved(db, u.bw.iDb, u.bw.iMoved, pOp->p1);
71403       /* All OP_Destroy operations occur on the same btree */
71404       assert( resetSchemaOnFault==0 || resetSchemaOnFault==u.bw.iDb+1 );
71405       resetSchemaOnFault = u.bw.iDb+1;
71406     }
71407 #endif
71408   }
71409   break;
71410 }
71411 
71412 /* Opcode: Clear P1 P2 P3
71413 **
71414 ** Delete all contents of the database table or index whose root page
71415 ** in the database file is given by P1.  But, unlike Destroy, do not
71416 ** remove the table or index from the database file.
71417 **
71418 ** The table being clear is in the main database file if P2==0.  If
71419 ** P2==1 then the table to be clear is in the auxiliary database file
71420 ** that is used to store tables create using CREATE TEMPORARY TABLE.
71421 **
71422 ** If the P3 value is non-zero, then the table referred to must be an
71423 ** intkey table (an SQL table, not an index). In this case the row change 
71424 ** count is incremented by the number of rows in the table being cleared. 
71425 ** If P3 is greater than zero, then the value stored in register P3 is
71426 ** also incremented by the number of rows in the table being cleared.
71427 **
71428 ** See also: Destroy
71429 */
71430 case OP_Clear: {
71431 #if 0  /* local variables moved into u.bx */
71432   int nChange;
71433 #endif /* local variables moved into u.bx */
71434 
71435   u.bx.nChange = 0;
71436   assert( p->readOnly==0 );
71437   assert( pOp->p1!=1 );
71438   assert( (p->btreeMask & (((yDbMask)1)<<pOp->p2))!=0 );
71439   rc = sqlite3BtreeClearTable(
71440       db->aDb[pOp->p2].pBt, pOp->p1, (pOp->p3 ? &u.bx.nChange : 0)
71441   );
71442   if( pOp->p3 ){
71443     p->nChange += u.bx.nChange;
71444     if( pOp->p3>0 ){
71445       assert( memIsValid(&aMem[pOp->p3]) );
71446       memAboutToChange(p, &aMem[pOp->p3]);
71447       aMem[pOp->p3].u.i += u.bx.nChange;
71448     }
71449   }
71450   break;
71451 }
71452 
71453 /* Opcode: CreateTable P1 P2 * * *
71454 ** Synopsis: r[P2]=root iDb=P1
71455 **
71456 ** Allocate a new table in the main database file if P1==0 or in the
71457 ** auxiliary database file if P1==1 or in an attached database if
71458 ** P1>1.  Write the root page number of the new table into
71459 ** register P2
71460 **
71461 ** The difference between a table and an index is this:  A table must
71462 ** have a 4-byte integer key and can have arbitrary data.  An index
71463 ** has an arbitrary key but no data.
71464 **
71465 ** See also: CreateIndex
71466 */
71467 /* Opcode: CreateIndex P1 P2 * * *
71468 ** Synopsis: r[P2]=root iDb=P1
71469 **
71470 ** Allocate a new index in the main database file if P1==0 or in the
71471 ** auxiliary database file if P1==1 or in an attached database if
71472 ** P1>1.  Write the root page number of the new table into
71473 ** register P2.
71474 **
71475 ** See documentation on OP_CreateTable for additional information.
71476 */
71477 case OP_CreateIndex:            /* out2-prerelease */
71478 case OP_CreateTable: {          /* out2-prerelease */
71479 #if 0  /* local variables moved into u.by */
71480   int pgno;
71481   int flags;
71482   Db *pDb;
71483 #endif /* local variables moved into u.by */
71484 
71485   u.by.pgno = 0;
71486   assert( pOp->p1>=0 && pOp->p1<db->nDb );
71487   assert( (p->btreeMask & (((yDbMask)1)<<pOp->p1))!=0 );
71488   assert( p->readOnly==0 );
71489   u.by.pDb = &db->aDb[pOp->p1];
71490   assert( u.by.pDb->pBt!=0 );
71491   if( pOp->opcode==OP_CreateTable ){
71492     /* u.by.flags = BTREE_INTKEY; */
71493     u.by.flags = BTREE_INTKEY;
71494   }else{
71495     u.by.flags = BTREE_BLOBKEY;
71496   }
71497   rc = sqlite3BtreeCreateTable(u.by.pDb->pBt, &u.by.pgno, u.by.flags);
71498   pOut->u.i = u.by.pgno;
71499   break;
71500 }
71501 
71502 /* Opcode: ParseSchema P1 * * P4 *
71503 **
71504 ** Read and parse all entries from the SQLITE_MASTER table of database P1
71505 ** that match the WHERE clause P4. 
71506 **
71507 ** This opcode invokes the parser to create a new virtual machine,
71508 ** then runs the new virtual machine.  It is thus a re-entrant opcode.
71509 */
71510 case OP_ParseSchema: {
71511 #if 0  /* local variables moved into u.bz */
71512   int iDb;
71513   const char *zMaster;
71514   char *zSql;
71515   InitData initData;
71516 #endif /* local variables moved into u.bz */
71517 
71518   /* Any prepared statement that invokes this opcode will hold mutexes
71519   ** on every btree.  This is a prerequisite for invoking
71520   ** sqlite3InitCallback().
71521   */
71522 #ifdef SQLITE_DEBUG
71523   for(u.bz.iDb=0; u.bz.iDb<db->nDb; u.bz.iDb++){
71524     assert( u.bz.iDb==1 || sqlite3BtreeHoldsMutex(db->aDb[u.bz.iDb].pBt) );
71525   }
71526 #endif
71527 
71528   u.bz.iDb = pOp->p1;
71529   assert( u.bz.iDb>=0 && u.bz.iDb<db->nDb );
71530   assert( DbHasProperty(db, u.bz.iDb, DB_SchemaLoaded) );
71531   /* Used to be a conditional */ {
71532     u.bz.zMaster = SCHEMA_TABLE(u.bz.iDb);
71533     u.bz.initData.db = db;
71534     u.bz.initData.iDb = pOp->p1;
71535     u.bz.initData.pzErrMsg = &p->zErrMsg;
71536     u.bz.zSql = sqlite3MPrintf(db,
71537        "SELECT name, rootpage, sql FROM '%q'.%s WHERE %s ORDER BY rowid",
71538        db->aDb[u.bz.iDb].zName, u.bz.zMaster, pOp->p4.z);
71539     if( u.bz.zSql==0 ){
71540       rc = SQLITE_NOMEM;
71541     }else{
71542       assert( db->init.busy==0 );
71543       db->init.busy = 1;
71544       u.bz.initData.rc = SQLITE_OK;
71545       assert( !db->mallocFailed );
71546       rc = sqlite3_exec(db, u.bz.zSql, sqlite3InitCallback, &u.bz.initData, 0);
71547       if( rc==SQLITE_OK ) rc = u.bz.initData.rc;
71548       sqlite3DbFree(db, u.bz.zSql);
71549       db->init.busy = 0;
71550     }
71551   }
71552   if( rc ) sqlite3ResetAllSchemasOfConnection(db);
71553   if( rc==SQLITE_NOMEM ){
71554     goto no_mem;
71555   }
71556   break;
71557 }
71558 
71559 #if !defined(SQLITE_OMIT_ANALYZE)
71560 /* Opcode: LoadAnalysis P1 * * * *
71561 **
71562 ** Read the sqlite_stat1 table for database P1 and load the content
71563 ** of that table into the internal index hash table.  This will cause
71564 ** the analysis to be used when preparing all subsequent queries.
71565 */
71566 case OP_LoadAnalysis: {
71567   assert( pOp->p1>=0 && pOp->p1<db->nDb );
71568   rc = sqlite3AnalysisLoad(db, pOp->p1);
71569   break;  
71570 }
71571 #endif /* !defined(SQLITE_OMIT_ANALYZE) */
71572 
71573 /* Opcode: DropTable P1 * * P4 *
71574 **
71575 ** Remove the internal (in-memory) data structures that describe
71576 ** the table named P4 in database P1.  This is called after a table
71577 ** is dropped in order to keep the internal representation of the
71578 ** schema consistent with what is on disk.
71579 */
71580 case OP_DropTable: {
71581   sqlite3UnlinkAndDeleteTable(db, pOp->p1, pOp->p4.z);
71582   break;
71583 }
71584 
71585 /* Opcode: DropIndex P1 * * P4 *
71586 **
71587 ** Remove the internal (in-memory) data structures that describe
71588 ** the index named P4 in database P1.  This is called after an index
71589 ** is dropped in order to keep the internal representation of the
71590 ** schema consistent with what is on disk.
71591 */
71592 case OP_DropIndex: {
71593   sqlite3UnlinkAndDeleteIndex(db, pOp->p1, pOp->p4.z);
71594   break;
71595 }
71596 
71597 /* Opcode: DropTrigger P1 * * P4 *
71598 **
71599 ** Remove the internal (in-memory) data structures that describe
71600 ** the trigger named P4 in database P1.  This is called after a trigger
71601 ** is dropped in order to keep the internal representation of the
71602 ** schema consistent with what is on disk.
71603 */
71604 case OP_DropTrigger: {
71605   sqlite3UnlinkAndDeleteTrigger(db, pOp->p1, pOp->p4.z);
71606   break;
71607 }
71608 
71609 
71610 #ifndef SQLITE_OMIT_INTEGRITY_CHECK
71611 /* Opcode: IntegrityCk P1 P2 P3 * P5
71612 **
71613 ** Do an analysis of the currently open database.  Store in
71614 ** register P1 the text of an error message describing any problems.
71615 ** If no problems are found, store a NULL in register P1.
71616 **
71617 ** The register P3 contains the maximum number of allowed errors.
71618 ** At most reg(P3) errors will be reported.
71619 ** In other words, the analysis stops as soon as reg(P1) errors are 
71620 ** seen.  Reg(P1) is updated with the number of errors remaining.
71621 **
71622 ** The root page numbers of all tables in the database are integer
71623 ** stored in reg(P1), reg(P1+1), reg(P1+2), ....  There are P2 tables
71624 ** total.
71625 **
71626 ** If P5 is not zero, the check is done on the auxiliary database
71627 ** file, not the main database file.
71628 **
71629 ** This opcode is used to implement the integrity_check pragma.
71630 */
71631 case OP_IntegrityCk: {
71632 #if 0  /* local variables moved into u.ca */
71633   int nRoot;      /* Number of tables to check.  (Number of root pages.) */
71634   int *aRoot;     /* Array of rootpage numbers for tables to be checked */
71635   int j;          /* Loop counter */
71636   int nErr;       /* Number of errors reported */
71637   char *z;        /* Text of the error report */
71638   Mem *pnErr;     /* Register keeping track of errors remaining */
71639 #endif /* local variables moved into u.ca */
71640 
71641   assert( p->bIsReader );
71642   u.ca.nRoot = pOp->p2;
71643   assert( u.ca.nRoot>0 );
71644   u.ca.aRoot = sqlite3DbMallocRaw(db, sizeof(int)*(u.ca.nRoot+1) );
71645   if( u.ca.aRoot==0 ) goto no_mem;
71646   assert( pOp->p3>0 && pOp->p3<=(p->nMem-p->nCursor) );
71647   u.ca.pnErr = &aMem[pOp->p3];
71648   assert( (u.ca.pnErr->flags & MEM_Int)!=0 );
71649   assert( (u.ca.pnErr->flags & (MEM_Str|MEM_Blob))==0 );
71650   pIn1 = &aMem[pOp->p1];
71651   for(u.ca.j=0; u.ca.j<u.ca.nRoot; u.ca.j++){
71652     u.ca.aRoot[u.ca.j] = (int)sqlite3VdbeIntValue(&pIn1[u.ca.j]);
71653   }
71654   u.ca.aRoot[u.ca.j] = 0;
71655   assert( pOp->p5<db->nDb );
71656   assert( (p->btreeMask & (((yDbMask)1)<<pOp->p5))!=0 );
71657   u.ca.z = sqlite3BtreeIntegrityCheck(db->aDb[pOp->p5].pBt, u.ca.aRoot, u.ca.nRoot,
71658                                  (int)u.ca.pnErr->u.i, &u.ca.nErr);
71659   sqlite3DbFree(db, u.ca.aRoot);
71660   u.ca.pnErr->u.i -= u.ca.nErr;
71661   sqlite3VdbeMemSetNull(pIn1);
71662   if( u.ca.nErr==0 ){
71663     assert( u.ca.z==0 );
71664   }else if( u.ca.z==0 ){
71665     goto no_mem;
71666   }else{
71667     sqlite3VdbeMemSetStr(pIn1, u.ca.z, -1, SQLITE_UTF8, sqlite3_free);
71668   }
71669   UPDATE_MAX_BLOBSIZE(pIn1);
71670   sqlite3VdbeChangeEncoding(pIn1, encoding);
71671   break;
71672 }
71673 #endif /* SQLITE_OMIT_INTEGRITY_CHECK */
71674 
71675 /* Opcode: RowSetAdd P1 P2 * * *
71676 ** Synopsis:  rowset(P1)=r[P2]
71677 **
71678 ** Insert the integer value held by register P2 into a boolean index
71679 ** held in register P1.
71680 **
71681 ** An assertion fails if P2 is not an integer.
71682 */
71683 case OP_RowSetAdd: {       /* in1, in2 */
71684   pIn1 = &aMem[pOp->p1];
71685   pIn2 = &aMem[pOp->p2];
71686   assert( (pIn2->flags & MEM_Int)!=0 );
71687   if( (pIn1->flags & MEM_RowSet)==0 ){
71688     sqlite3VdbeMemSetRowSet(pIn1);
71689     if( (pIn1->flags & MEM_RowSet)==0 ) goto no_mem;
71690   }
71691   sqlite3RowSetInsert(pIn1->u.pRowSet, pIn2->u.i);
71692   break;
71693 }
71694 
71695 /* Opcode: RowSetRead P1 P2 P3 * *
71696 ** Synopsis:  r[P3]=rowset(P1)
71697 **
71698 ** Extract the smallest value from boolean index P1 and put that value into
71699 ** register P3.  Or, if boolean index P1 is initially empty, leave P3
71700 ** unchanged and jump to instruction P2.
71701 */
71702 case OP_RowSetRead: {       /* jump, in1, out3 */
71703 #if 0  /* local variables moved into u.cb */
71704   i64 val;
71705 #endif /* local variables moved into u.cb */
71706 
71707   pIn1 = &aMem[pOp->p1];
71708   if( (pIn1->flags & MEM_RowSet)==0
71709    || sqlite3RowSetNext(pIn1->u.pRowSet, &u.cb.val)==0
71710   ){
71711     /* The boolean index is empty */
71712     sqlite3VdbeMemSetNull(pIn1);
71713     pc = pOp->p2 - 1;
71714   }else{
71715     /* A value was pulled from the index */
71716     sqlite3VdbeMemSetInt64(&aMem[pOp->p3], u.cb.val);
71717   }
71718   goto check_for_interrupt;
71719 }
71720 
71721 /* Opcode: RowSetTest P1 P2 P3 P4
71722 ** Synopsis: if r[P3] in rowset(P1) goto P2
71723 **
71724 ** Register P3 is assumed to hold a 64-bit integer value. If register P1
71725 ** contains a RowSet object and that RowSet object contains
71726 ** the value held in P3, jump to register P2. Otherwise, insert the
71727 ** integer in P3 into the RowSet and continue on to the
71728 ** next opcode.
71729 **
71730 ** The RowSet object is optimized for the case where successive sets
71731 ** of integers, where each set contains no duplicates. Each set
71732 ** of values is identified by a unique P4 value. The first set
71733 ** must have P4==0, the final set P4=-1.  P4 must be either -1 or
71734 ** non-negative.  For non-negative values of P4 only the lower 4
71735 ** bits are significant.
71736 **
71737 ** This allows optimizations: (a) when P4==0 there is no need to test
71738 ** the rowset object for P3, as it is guaranteed not to contain it,
71739 ** (b) when P4==-1 there is no need to insert the value, as it will
71740 ** never be tested for, and (c) when a value that is part of set X is
71741 ** inserted, there is no need to search to see if the same value was
71742 ** previously inserted as part of set X (only if it was previously
71743 ** inserted as part of some other set).
71744 */
71745 case OP_RowSetTest: {                     /* jump, in1, in3 */
71746 #if 0  /* local variables moved into u.cc */
71747   int iSet;
71748   int exists;
71749 #endif /* local variables moved into u.cc */
71750 
71751   pIn1 = &aMem[pOp->p1];
71752   pIn3 = &aMem[pOp->p3];
71753   u.cc.iSet = pOp->p4.i;
71754   assert( pIn3->flags&MEM_Int );
71755 
71756   /* If there is anything other than a rowset object in memory cell P1,
71757   ** delete it now and initialize P1 with an empty rowset
71758   */
71759   if( (pIn1->flags & MEM_RowSet)==0 ){
71760     sqlite3VdbeMemSetRowSet(pIn1);
71761     if( (pIn1->flags & MEM_RowSet)==0 ) goto no_mem;
71762   }
71763 
71764   assert( pOp->p4type==P4_INT32 );
71765   assert( u.cc.iSet==-1 || u.cc.iSet>=0 );
71766   if( u.cc.iSet ){
71767     u.cc.exists = sqlite3RowSetTest(pIn1->u.pRowSet,
71768                                (u8)(u.cc.iSet>=0 ? u.cc.iSet & 0xf : 0xff),
71769                                pIn3->u.i);
71770     if( u.cc.exists ){
71771       pc = pOp->p2 - 1;
71772       break;
71773     }
71774   }
71775   if( u.cc.iSet>=0 ){
71776     sqlite3RowSetInsert(pIn1->u.pRowSet, pIn3->u.i);
71777   }
71778   break;
71779 }
71780 
71781 
71782 #ifndef SQLITE_OMIT_TRIGGER
71783 
71784 /* Opcode: Program P1 P2 P3 P4 *
71785 **
71786 ** Execute the trigger program passed as P4 (type P4_SUBPROGRAM). 
71787 **
71788 ** P1 contains the address of the memory cell that contains the first memory 
71789 ** cell in an array of values used as arguments to the sub-program. P2 
71790 ** contains the address to jump to if the sub-program throws an IGNORE 
71791 ** exception using the RAISE() function. Register P3 contains the address 
71792 ** of a memory cell in this (the parent) VM that is used to allocate the 
71793 ** memory required by the sub-vdbe at runtime.
71794 **
71795 ** P4 is a pointer to the VM containing the trigger program.
71796 */
71797 case OP_Program: {        /* jump */
71798 #if 0  /* local variables moved into u.cd */
71799   int nMem;               /* Number of memory registers for sub-program */
71800   int nByte;              /* Bytes of runtime space required for sub-program */
71801   Mem *pRt;               /* Register to allocate runtime space */
71802   Mem *pMem;              /* Used to iterate through memory cells */
71803   Mem *pEnd;              /* Last memory cell in new array */
71804   VdbeFrame *pFrame;      /* New vdbe frame to execute in */
71805   SubProgram *pProgram;   /* Sub-program to execute */
71806   void *t;                /* Token identifying trigger */
71807 #endif /* local variables moved into u.cd */
71808 
71809   u.cd.pProgram = pOp->p4.pProgram;
71810   u.cd.pRt = &aMem[pOp->p3];
71811   assert( u.cd.pProgram->nOp>0 );
71812 
71813   /* If the p5 flag is clear, then recursive invocation of triggers is
71814   ** disabled for backwards compatibility (p5 is set if this sub-program
71815   ** is really a trigger, not a foreign key action, and the flag set
71816   ** and cleared by the "PRAGMA recursive_triggers" command is clear).
71817   **
71818   ** It is recursive invocation of triggers, at the SQL level, that is
71819   ** disabled. In some cases a single trigger may generate more than one
71820   ** SubProgram (if the trigger may be executed with more than one different
71821   ** ON CONFLICT algorithm). SubProgram structures associated with a
71822   ** single trigger all have the same value for the SubProgram.token
71823   ** variable.  */
71824   if( pOp->p5 ){
71825     u.cd.t = u.cd.pProgram->token;
71826     for(u.cd.pFrame=p->pFrame; u.cd.pFrame && u.cd.pFrame->token!=u.cd.t; u.cd.pFrame=u.cd.pFrame->pParent);
71827     if( u.cd.pFrame ) break;
71828   }
71829 
71830   if( p->nFrame>=db->aLimit[SQLITE_LIMIT_TRIGGER_DEPTH] ){
71831     rc = SQLITE_ERROR;
71832     sqlite3SetString(&p->zErrMsg, db, "too many levels of trigger recursion");
71833     break;
71834   }
71835 
71836   /* Register u.cd.pRt is used to store the memory required to save the state
71837   ** of the current program, and the memory required at runtime to execute
71838   ** the trigger program. If this trigger has been fired before, then u.cd.pRt
71839   ** is already allocated. Otherwise, it must be initialized.  */
71840   if( (u.cd.pRt->flags&MEM_Frame)==0 ){
71841     /* SubProgram.nMem is set to the number of memory cells used by the
71842     ** program stored in SubProgram.aOp. As well as these, one memory
71843     ** cell is required for each cursor used by the program. Set local
71844     ** variable u.cd.nMem (and later, VdbeFrame.nChildMem) to this value.
71845     */
71846     u.cd.nMem = u.cd.pProgram->nMem + u.cd.pProgram->nCsr;
71847     u.cd.nByte = ROUND8(sizeof(VdbeFrame))
71848               + u.cd.nMem * sizeof(Mem)
71849               + u.cd.pProgram->nCsr * sizeof(VdbeCursor *)
71850               + u.cd.pProgram->nOnce * sizeof(u8);
71851     u.cd.pFrame = sqlite3DbMallocZero(db, u.cd.nByte);
71852     if( !u.cd.pFrame ){
71853       goto no_mem;
71854     }
71855     sqlite3VdbeMemRelease(u.cd.pRt);
71856     u.cd.pRt->flags = MEM_Frame;
71857     u.cd.pRt->u.pFrame = u.cd.pFrame;
71858 
71859     u.cd.pFrame->v = p;
71860     u.cd.pFrame->nChildMem = u.cd.nMem;
71861     u.cd.pFrame->nChildCsr = u.cd.pProgram->nCsr;
71862     u.cd.pFrame->pc = pc;
71863     u.cd.pFrame->aMem = p->aMem;
71864     u.cd.pFrame->nMem = p->nMem;
71865     u.cd.pFrame->apCsr = p->apCsr;
71866     u.cd.pFrame->nCursor = p->nCursor;
71867     u.cd.pFrame->aOp = p->aOp;
71868     u.cd.pFrame->nOp = p->nOp;
71869     u.cd.pFrame->token = u.cd.pProgram->token;
71870     u.cd.pFrame->aOnceFlag = p->aOnceFlag;
71871     u.cd.pFrame->nOnceFlag = p->nOnceFlag;
71872 
71873     u.cd.pEnd = &VdbeFrameMem(u.cd.pFrame)[u.cd.pFrame->nChildMem];
71874     for(u.cd.pMem=VdbeFrameMem(u.cd.pFrame); u.cd.pMem!=u.cd.pEnd; u.cd.pMem++){
71875       u.cd.pMem->flags = MEM_Invalid;
71876       u.cd.pMem->db = db;
71877     }
71878   }else{
71879     u.cd.pFrame = u.cd.pRt->u.pFrame;
71880     assert( u.cd.pProgram->nMem+u.cd.pProgram->nCsr==u.cd.pFrame->nChildMem );
71881     assert( u.cd.pProgram->nCsr==u.cd.pFrame->nChildCsr );
71882     assert( pc==u.cd.pFrame->pc );
71883   }
71884 
71885   p->nFrame++;
71886   u.cd.pFrame->pParent = p->pFrame;
71887   u.cd.pFrame->lastRowid = lastRowid;
71888   u.cd.pFrame->nChange = p->nChange;
71889   p->nChange = 0;
71890   p->pFrame = u.cd.pFrame;
71891   p->aMem = aMem = &VdbeFrameMem(u.cd.pFrame)[-1];
71892   p->nMem = u.cd.pFrame->nChildMem;
71893   p->nCursor = (u16)u.cd.pFrame->nChildCsr;
71894   p->apCsr = (VdbeCursor **)&aMem[p->nMem+1];
71895   p->aOp = aOp = u.cd.pProgram->aOp;
71896   p->nOp = u.cd.pProgram->nOp;
71897   p->aOnceFlag = (u8 *)&p->apCsr[p->nCursor];
71898   p->nOnceFlag = u.cd.pProgram->nOnce;
71899   pc = -1;
71900   memset(p->aOnceFlag, 0, p->nOnceFlag);
71901 
71902   break;
71903 }
71904 
71905 /* Opcode: Param P1 P2 * * *
71906 **
71907 ** This opcode is only ever present in sub-programs called via the 
71908 ** OP_Program instruction. Copy a value currently stored in a memory 
71909 ** cell of the calling (parent) frame to cell P2 in the current frames 
71910 ** address space. This is used by trigger programs to access the new.* 
71911 ** and old.* values.
71912 **
71913 ** The address of the cell in the parent frame is determined by adding
71914 ** the value of the P1 argument to the value of the P1 argument to the
71915 ** calling OP_Program instruction.
71916 */
71917 case OP_Param: {           /* out2-prerelease */
71918 #if 0  /* local variables moved into u.ce */
71919   VdbeFrame *pFrame;
71920   Mem *pIn;
71921 #endif /* local variables moved into u.ce */
71922   u.ce.pFrame = p->pFrame;
71923   u.ce.pIn = &u.ce.pFrame->aMem[pOp->p1 + u.ce.pFrame->aOp[u.ce.pFrame->pc].p1];
71924   sqlite3VdbeMemShallowCopy(pOut, u.ce.pIn, MEM_Ephem);
71925   break;
71926 }
71927 
71928 #endif /* #ifndef SQLITE_OMIT_TRIGGER */
71929 
71930 #ifndef SQLITE_OMIT_FOREIGN_KEY
71931 /* Opcode: FkCounter P1 P2 * * *
71932 ** Synopsis: fkctr[P1]+=P2
71933 **
71934 ** Increment a "constraint counter" by P2 (P2 may be negative or positive).
71935 ** If P1 is non-zero, the database constraint counter is incremented 
71936 ** (deferred foreign key constraints). Otherwise, if P1 is zero, the 
71937 ** statement counter is incremented (immediate foreign key constraints).
71938 */
71939 case OP_FkCounter: {
71940   if( db->flags & SQLITE_DeferFKs ){
71941     db->nDeferredImmCons += pOp->p2;
71942   }else if( pOp->p1 ){
71943     db->nDeferredCons += pOp->p2;
71944   }else{
71945     p->nFkConstraint += pOp->p2;
71946   }
71947   break;
71948 }
71949 
71950 /* Opcode: FkIfZero P1 P2 * * *
71951 ** Synopsis: if fkctr[P1]==0 goto P2
71952 **
71953 ** This opcode tests if a foreign key constraint-counter is currently zero.
71954 ** If so, jump to instruction P2. Otherwise, fall through to the next 
71955 ** instruction.
71956 **
71957 ** If P1 is non-zero, then the jump is taken if the database constraint-counter
71958 ** is zero (the one that counts deferred constraint violations). If P1 is
71959 ** zero, the jump is taken if the statement constraint-counter is zero
71960 ** (immediate foreign key constraint violations).
71961 */
71962 case OP_FkIfZero: {         /* jump */
71963   if( pOp->p1 ){
71964     if( db->nDeferredCons==0 && db->nDeferredImmCons==0 ) pc = pOp->p2-1;
71965   }else{
71966     if( p->nFkConstraint==0 && db->nDeferredImmCons==0 ) pc = pOp->p2-1;
71967   }
71968   break;
71969 }
71970 #endif /* #ifndef SQLITE_OMIT_FOREIGN_KEY */
71971 
71972 #ifndef SQLITE_OMIT_AUTOINCREMENT
71973 /* Opcode: MemMax P1 P2 * * *
71974 ** Synopsis: r[P1]=max(r[P1],r[P2])
71975 **
71976 ** P1 is a register in the root frame of this VM (the root frame is
71977 ** different from the current frame if this instruction is being executed
71978 ** within a sub-program). Set the value of register P1 to the maximum of 
71979 ** its current value and the value in register P2.
71980 **
71981 ** This instruction throws an error if the memory cell is not initially
71982 ** an integer.
71983 */
71984 case OP_MemMax: {        /* in2 */
71985 #if 0  /* local variables moved into u.cf */
71986   Mem *pIn1;
71987   VdbeFrame *pFrame;
71988 #endif /* local variables moved into u.cf */
71989   if( p->pFrame ){
71990     for(u.cf.pFrame=p->pFrame; u.cf.pFrame->pParent; u.cf.pFrame=u.cf.pFrame->pParent);
71991     u.cf.pIn1 = &u.cf.pFrame->aMem[pOp->p1];
71992   }else{
71993     u.cf.pIn1 = &aMem[pOp->p1];
71994   }
71995   assert( memIsValid(u.cf.pIn1) );
71996   sqlite3VdbeMemIntegerify(u.cf.pIn1);
71997   pIn2 = &aMem[pOp->p2];
71998   sqlite3VdbeMemIntegerify(pIn2);
71999   if( u.cf.pIn1->u.i<pIn2->u.i){
72000     u.cf.pIn1->u.i = pIn2->u.i;
72001   }
72002   break;
72003 }
72004 #endif /* SQLITE_OMIT_AUTOINCREMENT */
72005 
72006 /* Opcode: IfPos P1 P2 * * *
72007 ** Synopsis: if r[P1]>0 goto P2
72008 **
72009 ** If the value of register P1 is 1 or greater, jump to P2.
72010 **
72011 ** It is illegal to use this instruction on a register that does
72012 ** not contain an integer.  An assertion fault will result if you try.
72013 */
72014 case OP_IfPos: {        /* jump, in1 */
72015   pIn1 = &aMem[pOp->p1];
72016   assert( pIn1->flags&MEM_Int );
72017   if( pIn1->u.i>0 ){
72018      pc = pOp->p2 - 1;
72019   }
72020   break;
72021 }
72022 
72023 /* Opcode: IfNeg P1 P2 * * *
72024 ** Synopsis: if r[P1]<0 goto P2
72025 **
72026 ** If the value of register P1 is less than zero, jump to P2. 
72027 **
72028 ** It is illegal to use this instruction on a register that does
72029 ** not contain an integer.  An assertion fault will result if you try.
72030 */
72031 case OP_IfNeg: {        /* jump, in1 */
72032   pIn1 = &aMem[pOp->p1];
72033   assert( pIn1->flags&MEM_Int );
72034   if( pIn1->u.i<0 ){
72035      pc = pOp->p2 - 1;
72036   }
72037   break;
72038 }
72039 
72040 /* Opcode: IfZero P1 P2 P3 * *
72041 ** Synopsis: r[P1]+=P3, if r[P1]==0 goto P2
72042 **
72043 ** The register P1 must contain an integer.  Add literal P3 to the
72044 ** value in register P1.  If the result is exactly 0, jump to P2. 
72045 **
72046 ** It is illegal to use this instruction on a register that does
72047 ** not contain an integer.  An assertion fault will result if you try.
72048 */
72049 case OP_IfZero: {        /* jump, in1 */
72050   pIn1 = &aMem[pOp->p1];
72051   assert( pIn1->flags&MEM_Int );
72052   pIn1->u.i += pOp->p3;
72053   if( pIn1->u.i==0 ){
72054      pc = pOp->p2 - 1;
72055   }
72056   break;
72057 }
72058 
72059 /* Opcode: AggStep * P2 P3 P4 P5
72060 ** Synopsis: accum=r[P3] step(r[P2@P5])
72061 **
72062 ** Execute the step function for an aggregate.  The
72063 ** function has P5 arguments.   P4 is a pointer to the FuncDef
72064 ** structure that specifies the function.  Use register
72065 ** P3 as the accumulator.
72066 **
72067 ** The P5 arguments are taken from register P2 and its
72068 ** successors.
72069 */
72070 case OP_AggStep: {
72071 #if 0  /* local variables moved into u.cg */
72072   int n;
72073   int i;
72074   Mem *pMem;
72075   Mem *pRec;
72076   sqlite3_context ctx;
72077   sqlite3_value **apVal;
72078 #endif /* local variables moved into u.cg */
72079 
72080   u.cg.n = pOp->p5;
72081   assert( u.cg.n>=0 );
72082   u.cg.pRec = &aMem[pOp->p2];
72083   u.cg.apVal = p->apArg;
72084   assert( u.cg.apVal || u.cg.n==0 );
72085   for(u.cg.i=0; u.cg.i<u.cg.n; u.cg.i++, u.cg.pRec++){
72086     assert( memIsValid(u.cg.pRec) );
72087     u.cg.apVal[u.cg.i] = u.cg.pRec;
72088     memAboutToChange(p, u.cg.pRec);
72089     sqlite3VdbeMemStoreType(u.cg.pRec);
72090   }
72091   u.cg.ctx.pFunc = pOp->p4.pFunc;
72092   assert( pOp->p3>0 && pOp->p3<=(p->nMem-p->nCursor) );
72093   u.cg.ctx.pMem = u.cg.pMem = &aMem[pOp->p3];
72094   u.cg.pMem->n++;
72095   u.cg.ctx.s.flags = MEM_Null;
72096   u.cg.ctx.s.z = 0;
72097   u.cg.ctx.s.zMalloc = 0;
72098   u.cg.ctx.s.xDel = 0;
72099   u.cg.ctx.s.db = db;
72100   u.cg.ctx.isError = 0;
72101   u.cg.ctx.pColl = 0;
72102   u.cg.ctx.skipFlag = 0;
72103   if( u.cg.ctx.pFunc->funcFlags & SQLITE_FUNC_NEEDCOLL ){
72104     assert( pOp>p->aOp );
72105     assert( pOp[-1].p4type==P4_COLLSEQ );
72106     assert( pOp[-1].opcode==OP_CollSeq );
72107     u.cg.ctx.pColl = pOp[-1].p4.pColl;
72108   }
72109   (u.cg.ctx.pFunc->xStep)(&u.cg.ctx, u.cg.n, u.cg.apVal); /* IMP: R-24505-23230 */
72110   if( u.cg.ctx.isError ){
72111     sqlite3SetString(&p->zErrMsg, db, "%s", sqlite3_value_text(&u.cg.ctx.s));
72112     rc = u.cg.ctx.isError;
72113   }
72114   if( u.cg.ctx.skipFlag ){
72115     assert( pOp[-1].opcode==OP_CollSeq );
72116     u.cg.i = pOp[-1].p1;
72117     if( u.cg.i ) sqlite3VdbeMemSetInt64(&aMem[u.cg.i], 1);
72118   }
72119 
72120   sqlite3VdbeMemRelease(&u.cg.ctx.s);
72121 
72122   break;
72123 }
72124 
72125 /* Opcode: AggFinal P1 P2 * P4 *
72126 ** Synopsis: accum=r[P1] N=P2
72127 **
72128 ** Execute the finalizer function for an aggregate.  P1 is
72129 ** the memory location that is the accumulator for the aggregate.
72130 **
72131 ** P2 is the number of arguments that the step function takes and
72132 ** P4 is a pointer to the FuncDef for this function.  The P2
72133 ** argument is not used by this opcode.  It is only there to disambiguate
72134 ** functions that can take varying numbers of arguments.  The
72135 ** P4 argument is only needed for the degenerate case where
72136 ** the step function was not previously called.
72137 */
72138 case OP_AggFinal: {
72139 #if 0  /* local variables moved into u.ch */
72140   Mem *pMem;
72141 #endif /* local variables moved into u.ch */
72142   assert( pOp->p1>0 && pOp->p1<=(p->nMem-p->nCursor) );
72143   u.ch.pMem = &aMem[pOp->p1];
72144   assert( (u.ch.pMem->flags & ~(MEM_Null|MEM_Agg))==0 );
72145   rc = sqlite3VdbeMemFinalize(u.ch.pMem, pOp->p4.pFunc);
72146   if( rc ){
72147     sqlite3SetString(&p->zErrMsg, db, "%s", sqlite3_value_text(u.ch.pMem));
72148   }
72149   sqlite3VdbeChangeEncoding(u.ch.pMem, encoding);
72150   UPDATE_MAX_BLOBSIZE(u.ch.pMem);
72151   if( sqlite3VdbeMemTooBig(u.ch.pMem) ){
72152     goto too_big;
72153   }
72154   break;
72155 }
72156 
72157 #ifndef SQLITE_OMIT_WAL
72158 /* Opcode: Checkpoint P1 P2 P3 * *
72159 **
72160 ** Checkpoint database P1. This is a no-op if P1 is not currently in
72161 ** WAL mode. Parameter P2 is one of SQLITE_CHECKPOINT_PASSIVE, FULL
72162 ** or RESTART.  Write 1 or 0 into mem[P3] if the checkpoint returns
72163 ** SQLITE_BUSY or not, respectively.  Write the number of pages in the
72164 ** WAL after the checkpoint into mem[P3+1] and the number of pages
72165 ** in the WAL that have been checkpointed after the checkpoint
72166 ** completes into mem[P3+2].  However on an error, mem[P3+1] and
72167 ** mem[P3+2] are initialized to -1.
72168 */
72169 case OP_Checkpoint: {
72170 #if 0  /* local variables moved into u.ci */
72171   int i;                          /* Loop counter */
72172   int aRes[3];                    /* Results */
72173   Mem *pMem;                      /* Write results here */
72174 #endif /* local variables moved into u.ci */
72175 
72176   assert( p->readOnly==0 );
72177   u.ci.aRes[0] = 0;
72178   u.ci.aRes[1] = u.ci.aRes[2] = -1;
72179   assert( pOp->p2==SQLITE_CHECKPOINT_PASSIVE
72180        || pOp->p2==SQLITE_CHECKPOINT_FULL
72181        || pOp->p2==SQLITE_CHECKPOINT_RESTART
72182   );
72183   rc = sqlite3Checkpoint(db, pOp->p1, pOp->p2, &u.ci.aRes[1], &u.ci.aRes[2]);
72184   if( rc==SQLITE_BUSY ){
72185     rc = SQLITE_OK;
72186     u.ci.aRes[0] = 1;
72187   }
72188   for(u.ci.i=0, u.ci.pMem = &aMem[pOp->p3]; u.ci.i<3; u.ci.i++, u.ci.pMem++){
72189     sqlite3VdbeMemSetInt64(u.ci.pMem, (i64)u.ci.aRes[u.ci.i]);
72190   }
72191   break;
72192 };  
72193 #endif
72194 
72195 #ifndef SQLITE_OMIT_PRAGMA
72196 /* Opcode: JournalMode P1 P2 P3 * P5
72197 **
72198 ** Change the journal mode of database P1 to P3. P3 must be one of the
72199 ** PAGER_JOURNALMODE_XXX values. If changing between the various rollback
72200 ** modes (delete, truncate, persist, off and memory), this is a simple
72201 ** operation. No IO is required.
72202 **
72203 ** If changing into or out of WAL mode the procedure is more complicated.
72204 **
72205 ** Write a string containing the final journal-mode to register P2.
72206 */
72207 case OP_JournalMode: {    /* out2-prerelease */
72208 #if 0  /* local variables moved into u.cj */
72209   Btree *pBt;                     /* Btree to change journal mode of */
72210   Pager *pPager;                  /* Pager associated with pBt */
72211   int eNew;                       /* New journal mode */
72212   int eOld;                       /* The old journal mode */
72213 #ifndef SQLITE_OMIT_WAL
72214   const char *zFilename;          /* Name of database file for pPager */
72215 #endif
72216 #endif /* local variables moved into u.cj */
72217 
72218   u.cj.eNew = pOp->p3;
72219   assert( u.cj.eNew==PAGER_JOURNALMODE_DELETE
72220        || u.cj.eNew==PAGER_JOURNALMODE_TRUNCATE
72221        || u.cj.eNew==PAGER_JOURNALMODE_PERSIST
72222        || u.cj.eNew==PAGER_JOURNALMODE_OFF
72223        || u.cj.eNew==PAGER_JOURNALMODE_MEMORY
72224        || u.cj.eNew==PAGER_JOURNALMODE_WAL
72225        || u.cj.eNew==PAGER_JOURNALMODE_QUERY
72226   );
72227   assert( pOp->p1>=0 && pOp->p1<db->nDb );
72228   assert( p->readOnly==0 );
72229 
72230   u.cj.pBt = db->aDb[pOp->p1].pBt;
72231   u.cj.pPager = sqlite3BtreePager(u.cj.pBt);
72232   u.cj.eOld = sqlite3PagerGetJournalMode(u.cj.pPager);
72233   if( u.cj.eNew==PAGER_JOURNALMODE_QUERY ) u.cj.eNew = u.cj.eOld;
72234   if( !sqlite3PagerOkToChangeJournalMode(u.cj.pPager) ) u.cj.eNew = u.cj.eOld;
72235 
72236 #ifndef SQLITE_OMIT_WAL
72237   u.cj.zFilename = sqlite3PagerFilename(u.cj.pPager, 1);
72238 
72239   /* Do not allow a transition to journal_mode=WAL for a database
72240   ** in temporary storage or if the VFS does not support shared memory
72241   */
72242   if( u.cj.eNew==PAGER_JOURNALMODE_WAL
72243    && (sqlite3Strlen30(u.cj.zFilename)==0           /* Temp file */
72244        || !sqlite3PagerWalSupported(u.cj.pPager))   /* No shared-memory support */
72245   ){
72246     u.cj.eNew = u.cj.eOld;
72247   }
72248 
72249   if( (u.cj.eNew!=u.cj.eOld)
72250    && (u.cj.eOld==PAGER_JOURNALMODE_WAL || u.cj.eNew==PAGER_JOURNALMODE_WAL)
72251   ){
72252     if( !db->autoCommit || db->nVdbeRead>1 ){
72253       rc = SQLITE_ERROR;
72254       sqlite3SetString(&p->zErrMsg, db,
72255           "cannot change %s wal mode from within a transaction",
72256           (u.cj.eNew==PAGER_JOURNALMODE_WAL ? "into" : "out of")
72257       );
72258       break;
72259     }else{
72260 
72261       if( u.cj.eOld==PAGER_JOURNALMODE_WAL ){
72262         /* If leaving WAL mode, close the log file. If successful, the call
72263         ** to PagerCloseWal() checkpoints and deletes the write-ahead-log
72264         ** file. An EXCLUSIVE lock may still be held on the database file
72265         ** after a successful return.
72266         */
72267         rc = sqlite3PagerCloseWal(u.cj.pPager);
72268         if( rc==SQLITE_OK ){
72269           sqlite3PagerSetJournalMode(u.cj.pPager, u.cj.eNew);
72270         }
72271       }else if( u.cj.eOld==PAGER_JOURNALMODE_MEMORY ){
72272         /* Cannot transition directly from MEMORY to WAL.  Use mode OFF
72273         ** as an intermediate */
72274         sqlite3PagerSetJournalMode(u.cj.pPager, PAGER_JOURNALMODE_OFF);
72275       }
72276 
72277       /* Open a transaction on the database file. Regardless of the journal
72278       ** mode, this transaction always uses a rollback journal.
72279       */
72280       assert( sqlite3BtreeIsInTrans(u.cj.pBt)==0 );
72281       if( rc==SQLITE_OK ){
72282         rc = sqlite3BtreeSetVersion(u.cj.pBt, (u.cj.eNew==PAGER_JOURNALMODE_WAL ? 2 : 1));
72283       }
72284     }
72285   }
72286 #endif /* ifndef SQLITE_OMIT_WAL */
72287 
72288   if( rc ){
72289     u.cj.eNew = u.cj.eOld;
72290   }
72291   u.cj.eNew = sqlite3PagerSetJournalMode(u.cj.pPager, u.cj.eNew);
72292 
72293   pOut = &aMem[pOp->p2];
72294   pOut->flags = MEM_Str|MEM_Static|MEM_Term;
72295   pOut->z = (char *)sqlite3JournalModename(u.cj.eNew);
72296   pOut->n = sqlite3Strlen30(pOut->z);
72297   pOut->enc = SQLITE_UTF8;
72298   sqlite3VdbeChangeEncoding(pOut, encoding);
72299   break;
72300 };
72301 #endif /* SQLITE_OMIT_PRAGMA */
72302 
72303 #if !defined(SQLITE_OMIT_VACUUM) && !defined(SQLITE_OMIT_ATTACH)
72304 /* Opcode: Vacuum * * * * *
72305 **
72306 ** Vacuum the entire database.  This opcode will cause other virtual
72307 ** machines to be created and run.  It may not be called from within
72308 ** a transaction.
72309 */
72310 case OP_Vacuum: {
72311   assert( p->readOnly==0 );
72312   rc = sqlite3RunVacuum(&p->zErrMsg, db);
72313   break;
72314 }
72315 #endif
72316 
72317 #if !defined(SQLITE_OMIT_AUTOVACUUM)
72318 /* Opcode: IncrVacuum P1 P2 * * *
72319 **
72320 ** Perform a single step of the incremental vacuum procedure on
72321 ** the P1 database. If the vacuum has finished, jump to instruction
72322 ** P2. Otherwise, fall through to the next instruction.
72323 */
72324 case OP_IncrVacuum: {        /* jump */
72325 #if 0  /* local variables moved into u.ck */
72326   Btree *pBt;
72327 #endif /* local variables moved into u.ck */
72328 
72329   assert( pOp->p1>=0 && pOp->p1<db->nDb );
72330   assert( (p->btreeMask & (((yDbMask)1)<<pOp->p1))!=0 );
72331   assert( p->readOnly==0 );
72332   u.ck.pBt = db->aDb[pOp->p1].pBt;
72333   rc = sqlite3BtreeIncrVacuum(u.ck.pBt);
72334   if( rc==SQLITE_DONE ){
72335     pc = pOp->p2 - 1;
72336     rc = SQLITE_OK;
72337   }
72338   break;
72339 }
72340 #endif
72341 
72342 /* Opcode: Expire P1 * * * *
72343 **
72344 ** Cause precompiled statements to become expired. An expired statement
72345 ** fails with an error code of SQLITE_SCHEMA if it is ever executed 
72346 ** (via sqlite3_step()).
72347 ** 
72348 ** If P1 is 0, then all SQL statements become expired. If P1 is non-zero,
72349 ** then only the currently executing statement is affected. 
72350 */
72351 case OP_Expire: {
72352   if( !pOp->p1 ){
72353     sqlite3ExpirePreparedStatements(db);
72354   }else{
72355     p->expired = 1;
72356   }
72357   break;
72358 }
72359 
72360 #ifndef SQLITE_OMIT_SHARED_CACHE
72361 /* Opcode: TableLock P1 P2 P3 P4 *
72362 ** Synopsis: iDb=P1 root=P2 write=P3
72363 **
72364 ** Obtain a lock on a particular table. This instruction is only used when
72365 ** the shared-cache feature is enabled. 
72366 **
72367 ** P1 is the index of the database in sqlite3.aDb[] of the database
72368 ** on which the lock is acquired.  A readlock is obtained if P3==0 or
72369 ** a write lock if P3==1.
72370 **
72371 ** P2 contains the root-page of the table to lock.
72372 **
72373 ** P4 contains a pointer to the name of the table being locked. This is only
72374 ** used to generate an error message if the lock cannot be obtained.
72375 */
72376 case OP_TableLock: {
72377   u8 isWriteLock = (u8)pOp->p3;
72378   if( isWriteLock || 0==(db->flags&SQLITE_ReadUncommitted) ){
72379     int p1 = pOp->p1; 
72380     assert( p1>=0 && p1<db->nDb );
72381     assert( (p->btreeMask & (((yDbMask)1)<<p1))!=0 );
72382     assert( isWriteLock==0 || isWriteLock==1 );
72383     rc = sqlite3BtreeLockTable(db->aDb[p1].pBt, pOp->p2, isWriteLock);
72384     if( (rc&0xFF)==SQLITE_LOCKED ){
72385       const char *z = pOp->p4.z;
72386       sqlite3SetString(&p->zErrMsg, db, "database table is locked: %s", z);
72387     }
72388   }
72389   break;
72390 }
72391 #endif /* SQLITE_OMIT_SHARED_CACHE */
72392 
72393 #ifndef SQLITE_OMIT_VIRTUALTABLE
72394 /* Opcode: VBegin * * * P4 *
72395 **
72396 ** P4 may be a pointer to an sqlite3_vtab structure. If so, call the 
72397 ** xBegin method for that table.
72398 **
72399 ** Also, whether or not P4 is set, check that this is not being called from
72400 ** within a callback to a virtual table xSync() method. If it is, the error
72401 ** code will be set to SQLITE_LOCKED.
72402 */
72403 case OP_VBegin: {
72404 #if 0  /* local variables moved into u.cl */
72405   VTable *pVTab;
72406 #endif /* local variables moved into u.cl */
72407   u.cl.pVTab = pOp->p4.pVtab;
72408   rc = sqlite3VtabBegin(db, u.cl.pVTab);
72409   if( u.cl.pVTab ) sqlite3VtabImportErrmsg(p, u.cl.pVTab->pVtab);
72410   break;
72411 }
72412 #endif /* SQLITE_OMIT_VIRTUALTABLE */
72413 
72414 #ifndef SQLITE_OMIT_VIRTUALTABLE
72415 /* Opcode: VCreate P1 * * P4 *
72416 **
72417 ** P4 is the name of a virtual table in database P1. Call the xCreate method
72418 ** for that table.
72419 */
72420 case OP_VCreate: {
72421   rc = sqlite3VtabCallCreate(db, pOp->p1, pOp->p4.z, &p->zErrMsg);
72422   break;
72423 }
72424 #endif /* SQLITE_OMIT_VIRTUALTABLE */
72425 
72426 #ifndef SQLITE_OMIT_VIRTUALTABLE
72427 /* Opcode: VDestroy P1 * * P4 *
72428 **
72429 ** P4 is the name of a virtual table in database P1.  Call the xDestroy method
72430 ** of that table.
72431 */
72432 case OP_VDestroy: {
72433   p->inVtabMethod = 2;
72434   rc = sqlite3VtabCallDestroy(db, pOp->p1, pOp->p4.z);
72435   p->inVtabMethod = 0;
72436   break;
72437 }
72438 #endif /* SQLITE_OMIT_VIRTUALTABLE */
72439 
72440 #ifndef SQLITE_OMIT_VIRTUALTABLE
72441 /* Opcode: VOpen P1 * * P4 *
72442 **
72443 ** P4 is a pointer to a virtual table object, an sqlite3_vtab structure.
72444 ** P1 is a cursor number.  This opcode opens a cursor to the virtual
72445 ** table and stores that cursor in P1.
72446 */
72447 case OP_VOpen: {
72448 #if 0  /* local variables moved into u.cm */
72449   VdbeCursor *pCur;
72450   sqlite3_vtab_cursor *pVtabCursor;
72451   sqlite3_vtab *pVtab;
72452   sqlite3_module *pModule;
72453 #endif /* local variables moved into u.cm */
72454 
72455   assert( p->bIsReader );
72456   u.cm.pCur = 0;
72457   u.cm.pVtabCursor = 0;
72458   u.cm.pVtab = pOp->p4.pVtab->pVtab;
72459   u.cm.pModule = (sqlite3_module *)u.cm.pVtab->pModule;
72460   assert(u.cm.pVtab && u.cm.pModule);
72461   rc = u.cm.pModule->xOpen(u.cm.pVtab, &u.cm.pVtabCursor);
72462   sqlite3VtabImportErrmsg(p, u.cm.pVtab);
72463   if( SQLITE_OK==rc ){
72464     /* Initialize sqlite3_vtab_cursor base class */
72465     u.cm.pVtabCursor->pVtab = u.cm.pVtab;
72466 
72467     /* Initialize vdbe cursor object */
72468     u.cm.pCur = allocateCursor(p, pOp->p1, 0, -1, 0);
72469     if( u.cm.pCur ){
72470       u.cm.pCur->pVtabCursor = u.cm.pVtabCursor;
72471     }else{
72472       db->mallocFailed = 1;
72473       u.cm.pModule->xClose(u.cm.pVtabCursor);
72474     }
72475   }
72476   break;
72477 }
72478 #endif /* SQLITE_OMIT_VIRTUALTABLE */
72479 
72480 #ifndef SQLITE_OMIT_VIRTUALTABLE
72481 /* Opcode: VFilter P1 P2 P3 P4 *
72482 ** Synopsis: iPlan=r[P3] zPlan='P4'
72483 **
72484 ** P1 is a cursor opened using VOpen.  P2 is an address to jump to if
72485 ** the filtered result set is empty.
72486 **
72487 ** P4 is either NULL or a string that was generated by the xBestIndex
72488 ** method of the module.  The interpretation of the P4 string is left
72489 ** to the module implementation.
72490 **
72491 ** This opcode invokes the xFilter method on the virtual table specified
72492 ** by P1.  The integer query plan parameter to xFilter is stored in register
72493 ** P3. Register P3+1 stores the argc parameter to be passed to the
72494 ** xFilter method. Registers P3+2..P3+1+argc are the argc
72495 ** additional parameters which are passed to
72496 ** xFilter as argv. Register P3+2 becomes argv[0] when passed to xFilter.
72497 **
72498 ** A jump is made to P2 if the result set after filtering would be empty.
72499 */
72500 case OP_VFilter: {   /* jump */
72501 #if 0  /* local variables moved into u.cn */
72502   int nArg;
72503   int iQuery;
72504   const sqlite3_module *pModule;
72505   Mem *pQuery;
72506   Mem *pArgc;
72507   sqlite3_vtab_cursor *pVtabCursor;
72508   sqlite3_vtab *pVtab;
72509   VdbeCursor *pCur;
72510   int res;
72511   int i;
72512   Mem **apArg;
72513 #endif /* local variables moved into u.cn */
72514 
72515   u.cn.pQuery = &aMem[pOp->p3];
72516   u.cn.pArgc = &u.cn.pQuery[1];
72517   u.cn.pCur = p->apCsr[pOp->p1];
72518   assert( memIsValid(u.cn.pQuery) );
72519   REGISTER_TRACE(pOp->p3, u.cn.pQuery);
72520   assert( u.cn.pCur->pVtabCursor );
72521   u.cn.pVtabCursor = u.cn.pCur->pVtabCursor;
72522   u.cn.pVtab = u.cn.pVtabCursor->pVtab;
72523   u.cn.pModule = u.cn.pVtab->pModule;
72524 
72525   /* Grab the index number and argc parameters */
72526   assert( (u.cn.pQuery->flags&MEM_Int)!=0 && u.cn.pArgc->flags==MEM_Int );
72527   u.cn.nArg = (int)u.cn.pArgc->u.i;
72528   u.cn.iQuery = (int)u.cn.pQuery->u.i;
72529 
72530   /* Invoke the xFilter method */
72531   {
72532     u.cn.res = 0;
72533     u.cn.apArg = p->apArg;
72534     for(u.cn.i = 0; u.cn.i<u.cn.nArg; u.cn.i++){
72535       u.cn.apArg[u.cn.i] = &u.cn.pArgc[u.cn.i+1];
72536       sqlite3VdbeMemStoreType(u.cn.apArg[u.cn.i]);
72537     }
72538 
72539     p->inVtabMethod = 1;
72540     rc = u.cn.pModule->xFilter(u.cn.pVtabCursor, u.cn.iQuery, pOp->p4.z, u.cn.nArg, u.cn.apArg);
72541     p->inVtabMethod = 0;
72542     sqlite3VtabImportErrmsg(p, u.cn.pVtab);
72543     if( rc==SQLITE_OK ){
72544       u.cn.res = u.cn.pModule->xEof(u.cn.pVtabCursor);
72545     }
72546 
72547     if( u.cn.res ){
72548       pc = pOp->p2 - 1;
72549     }
72550   }
72551   u.cn.pCur->nullRow = 0;
72552 
72553   break;
72554 }
72555 #endif /* SQLITE_OMIT_VIRTUALTABLE */
72556 
72557 #ifndef SQLITE_OMIT_VIRTUALTABLE
72558 /* Opcode: VColumn P1 P2 P3 * *
72559 ** Synopsis: r[P3]=vcolumn(P2)
72560 **
72561 ** Store the value of the P2-th column of
72562 ** the row of the virtual-table that the 
72563 ** P1 cursor is pointing to into register P3.
72564 */
72565 case OP_VColumn: {
72566 #if 0  /* local variables moved into u.co */
72567   sqlite3_vtab *pVtab;
72568   const sqlite3_module *pModule;
72569   Mem *pDest;
72570   sqlite3_context sContext;
72571 #endif /* local variables moved into u.co */
72572 
72573   VdbeCursor *pCur = p->apCsr[pOp->p1];
72574   assert( pCur->pVtabCursor );
72575   assert( pOp->p3>0 && pOp->p3<=(p->nMem-p->nCursor) );
72576   u.co.pDest = &aMem[pOp->p3];
72577   memAboutToChange(p, u.co.pDest);
72578   if( pCur->nullRow ){
72579     sqlite3VdbeMemSetNull(u.co.pDest);
72580     break;
72581   }
72582   u.co.pVtab = pCur->pVtabCursor->pVtab;
72583   u.co.pModule = u.co.pVtab->pModule;
72584   assert( u.co.pModule->xColumn );
72585   memset(&u.co.sContext, 0, sizeof(u.co.sContext));
72586 
72587   /* The output cell may already have a buffer allocated. Move
72588   ** the current contents to u.co.sContext.s so in case the user-function
72589   ** can use the already allocated buffer instead of allocating a
72590   ** new one.
72591   */
72592   sqlite3VdbeMemMove(&u.co.sContext.s, u.co.pDest);
72593   MemSetTypeFlag(&u.co.sContext.s, MEM_Null);
72594 
72595   rc = u.co.pModule->xColumn(pCur->pVtabCursor, &u.co.sContext, pOp->p2);
72596   sqlite3VtabImportErrmsg(p, u.co.pVtab);
72597   if( u.co.sContext.isError ){
72598     rc = u.co.sContext.isError;
72599   }
72600 
72601   /* Copy the result of the function to the P3 register. We
72602   ** do this regardless of whether or not an error occurred to ensure any
72603   ** dynamic allocation in u.co.sContext.s (a Mem struct) is  released.
72604   */
72605   sqlite3VdbeChangeEncoding(&u.co.sContext.s, encoding);
72606   sqlite3VdbeMemMove(u.co.pDest, &u.co.sContext.s);
72607   REGISTER_TRACE(pOp->p3, u.co.pDest);
72608   UPDATE_MAX_BLOBSIZE(u.co.pDest);
72609 
72610   if( sqlite3VdbeMemTooBig(u.co.pDest) ){
72611     goto too_big;
72612   }
72613   break;
72614 }
72615 #endif /* SQLITE_OMIT_VIRTUALTABLE */
72616 
72617 #ifndef SQLITE_OMIT_VIRTUALTABLE
72618 /* Opcode: VNext P1 P2 * * *
72619 **
72620 ** Advance virtual table P1 to the next row in its result set and
72621 ** jump to instruction P2.  Or, if the virtual table has reached
72622 ** the end of its result set, then fall through to the next instruction.
72623 */
72624 case OP_VNext: {   /* jump */
72625 #if 0  /* local variables moved into u.cp */
72626   sqlite3_vtab *pVtab;
72627   const sqlite3_module *pModule;
72628   int res;
72629   VdbeCursor *pCur;
72630 #endif /* local variables moved into u.cp */
72631 
72632   u.cp.res = 0;
72633   u.cp.pCur = p->apCsr[pOp->p1];
72634   assert( u.cp.pCur->pVtabCursor );
72635   if( u.cp.pCur->nullRow ){
72636     break;
72637   }
72638   u.cp.pVtab = u.cp.pCur->pVtabCursor->pVtab;
72639   u.cp.pModule = u.cp.pVtab->pModule;
72640   assert( u.cp.pModule->xNext );
72641 
72642   /* Invoke the xNext() method of the module. There is no way for the
72643   ** underlying implementation to return an error if one occurs during
72644   ** xNext(). Instead, if an error occurs, true is returned (indicating that
72645   ** data is available) and the error code returned when xColumn or
72646   ** some other method is next invoked on the save virtual table cursor.
72647   */
72648   p->inVtabMethod = 1;
72649   rc = u.cp.pModule->xNext(u.cp.pCur->pVtabCursor);
72650   p->inVtabMethod = 0;
72651   sqlite3VtabImportErrmsg(p, u.cp.pVtab);
72652   if( rc==SQLITE_OK ){
72653     u.cp.res = u.cp.pModule->xEof(u.cp.pCur->pVtabCursor);
72654   }
72655 
72656   if( !u.cp.res ){
72657     /* If there is data, jump to P2 */
72658     pc = pOp->p2 - 1;
72659   }
72660   goto check_for_interrupt;
72661 }
72662 #endif /* SQLITE_OMIT_VIRTUALTABLE */
72663 
72664 #ifndef SQLITE_OMIT_VIRTUALTABLE
72665 /* Opcode: VRename P1 * * P4 *
72666 **
72667 ** P4 is a pointer to a virtual table object, an sqlite3_vtab structure.
72668 ** This opcode invokes the corresponding xRename method. The value
72669 ** in register P1 is passed as the zName argument to the xRename method.
72670 */
72671 case OP_VRename: {
72672 #if 0  /* local variables moved into u.cq */
72673   sqlite3_vtab *pVtab;
72674   Mem *pName;
72675 #endif /* local variables moved into u.cq */
72676 
72677   u.cq.pVtab = pOp->p4.pVtab->pVtab;
72678   u.cq.pName = &aMem[pOp->p1];
72679   assert( u.cq.pVtab->pModule->xRename );
72680   assert( memIsValid(u.cq.pName) );
72681   assert( p->readOnly==0 );
72682   REGISTER_TRACE(pOp->p1, u.cq.pName);
72683   assert( u.cq.pName->flags & MEM_Str );
72684   testcase( u.cq.pName->enc==SQLITE_UTF8 );
72685   testcase( u.cq.pName->enc==SQLITE_UTF16BE );
72686   testcase( u.cq.pName->enc==SQLITE_UTF16LE );
72687   rc = sqlite3VdbeChangeEncoding(u.cq.pName, SQLITE_UTF8);
72688   if( rc==SQLITE_OK ){
72689     rc = u.cq.pVtab->pModule->xRename(u.cq.pVtab, u.cq.pName->z);
72690     sqlite3VtabImportErrmsg(p, u.cq.pVtab);
72691     p->expired = 0;
72692   }
72693   break;
72694 }
72695 #endif
72696 
72697 #ifndef SQLITE_OMIT_VIRTUALTABLE
72698 /* Opcode: VUpdate P1 P2 P3 P4 *
72699 ** Synopsis: data=r[P3@P2]
72700 **
72701 ** P4 is a pointer to a virtual table object, an sqlite3_vtab structure.
72702 ** This opcode invokes the corresponding xUpdate method. P2 values
72703 ** are contiguous memory cells starting at P3 to pass to the xUpdate 
72704 ** invocation. The value in register (P3+P2-1) corresponds to the 
72705 ** p2th element of the argv array passed to xUpdate.
72706 **
72707 ** The xUpdate method will do a DELETE or an INSERT or both.
72708 ** The argv[0] element (which corresponds to memory cell P3)
72709 ** is the rowid of a row to delete.  If argv[0] is NULL then no 
72710 ** deletion occurs.  The argv[1] element is the rowid of the new 
72711 ** row.  This can be NULL to have the virtual table select the new 
72712 ** rowid for itself.  The subsequent elements in the array are 
72713 ** the values of columns in the new row.
72714 **
72715 ** If P2==1 then no insert is performed.  argv[0] is the rowid of
72716 ** a row to delete.
72717 **
72718 ** P1 is a boolean flag. If it is set to true and the xUpdate call
72719 ** is successful, then the value returned by sqlite3_last_insert_rowid() 
72720 ** is set to the value of the rowid for the row just inserted.
72721 */
72722 case OP_VUpdate: {
72723 #if 0  /* local variables moved into u.cr */
72724   sqlite3_vtab *pVtab;
72725   sqlite3_module *pModule;
72726   int nArg;
72727   int i;
72728   sqlite_int64 rowid;
72729   Mem **apArg;
72730   Mem *pX;
72731 #endif /* local variables moved into u.cr */
72732 
72733   assert( pOp->p2==1        || pOp->p5==OE_Fail   || pOp->p5==OE_Rollback
72734        || pOp->p5==OE_Abort || pOp->p5==OE_Ignore || pOp->p5==OE_Replace
72735   );
72736   assert( p->readOnly==0 );
72737   u.cr.pVtab = pOp->p4.pVtab->pVtab;
72738   u.cr.pModule = (sqlite3_module *)u.cr.pVtab->pModule;
72739   u.cr.nArg = pOp->p2;
72740   assert( pOp->p4type==P4_VTAB );
72741   if( ALWAYS(u.cr.pModule->xUpdate) ){
72742     u8 vtabOnConflict = db->vtabOnConflict;
72743     u.cr.apArg = p->apArg;
72744     u.cr.pX = &aMem[pOp->p3];
72745     for(u.cr.i=0; u.cr.i<u.cr.nArg; u.cr.i++){
72746       assert( memIsValid(u.cr.pX) );
72747       memAboutToChange(p, u.cr.pX);
72748       sqlite3VdbeMemStoreType(u.cr.pX);
72749       u.cr.apArg[u.cr.i] = u.cr.pX;
72750       u.cr.pX++;
72751     }
72752     db->vtabOnConflict = pOp->p5;
72753     rc = u.cr.pModule->xUpdate(u.cr.pVtab, u.cr.nArg, u.cr.apArg, &u.cr.rowid);
72754     db->vtabOnConflict = vtabOnConflict;
72755     sqlite3VtabImportErrmsg(p, u.cr.pVtab);
72756     if( rc==SQLITE_OK && pOp->p1 ){
72757       assert( u.cr.nArg>1 && u.cr.apArg[0] && (u.cr.apArg[0]->flags&MEM_Null) );
72758       db->lastRowid = lastRowid = u.cr.rowid;
72759     }
72760     if( (rc&0xff)==SQLITE_CONSTRAINT && pOp->p4.pVtab->bConstraint ){
72761       if( pOp->p5==OE_Ignore ){
72762         rc = SQLITE_OK;
72763       }else{
72764         p->errorAction = ((pOp->p5==OE_Replace) ? OE_Abort : pOp->p5);
72765       }
72766     }else{
72767       p->nChange++;
72768     }
72769   }
72770   break;
72771 }
72772 #endif /* SQLITE_OMIT_VIRTUALTABLE */
72773 
72774 #ifndef  SQLITE_OMIT_PAGER_PRAGMAS
72775 /* Opcode: Pagecount P1 P2 * * *
72776 **
72777 ** Write the current number of pages in database P1 to memory cell P2.
72778 */
72779 case OP_Pagecount: {            /* out2-prerelease */
72780   pOut->u.i = sqlite3BtreeLastPage(db->aDb[pOp->p1].pBt);
72781   break;
72782 }
72783 #endif
72784 
72785 
72786 #ifndef  SQLITE_OMIT_PAGER_PRAGMAS
72787 /* Opcode: MaxPgcnt P1 P2 P3 * *
72788 **
72789 ** Try to set the maximum page count for database P1 to the value in P3.
72790 ** Do not let the maximum page count fall below the current page count and
72791 ** do not change the maximum page count value if P3==0.
72792 **
72793 ** Store the maximum page count after the change in register P2.
72794 */
72795 case OP_MaxPgcnt: {            /* out2-prerelease */
72796   unsigned int newMax;
72797   Btree *pBt;
72798 
72799   pBt = db->aDb[pOp->p1].pBt;
72800   newMax = 0;
72801   if( pOp->p3 ){
72802     newMax = sqlite3BtreeLastPage(pBt);
72803     if( newMax < (unsigned)pOp->p3 ) newMax = (unsigned)pOp->p3;
72804   }
72805   pOut->u.i = sqlite3BtreeMaxPageCount(pBt, newMax);
72806   break;
72807 }
72808 #endif
72809 
72810 
72811 #ifndef SQLITE_OMIT_TRACE
72812 /* Opcode: Trace * * * P4 *
72813 **
72814 ** If tracing is enabled (by the sqlite3_trace()) interface, then
72815 ** the UTF-8 string contained in P4 is emitted on the trace callback.
72816 */
72817 case OP_Trace: {
72818 #if 0  /* local variables moved into u.cs */
72819   char *zTrace;
72820   char *z;
72821 #endif /* local variables moved into u.cs */
72822 
72823   if( db->xTrace
72824    && !p->doingRerun
72825    && (u.cs.zTrace = (pOp->p4.z ? pOp->p4.z : p->zSql))!=0
72826   ){
72827     u.cs.z = sqlite3VdbeExpandSql(p, u.cs.zTrace);
72828     db->xTrace(db->pTraceArg, u.cs.z);
72829     sqlite3DbFree(db, u.cs.z);
72830   }
72831 #ifdef SQLITE_USE_FCNTL_TRACE
72832   u.cs.zTrace = (pOp->p4.z ? pOp->p4.z : p->zSql);
72833   if( u.cs.zTrace ){
72834     int i;
72835     for(i=0; i<db->nDb; i++){
72836       if( ((1<<i) & p->btreeMask)==0 ) continue;
72837       sqlite3_file_control(db, db->aDb[i].zName, SQLITE_FCNTL_TRACE, u.cs.zTrace);
72838     }
72839   }
72840 #endif /* SQLITE_USE_FCNTL_TRACE */
72841 #ifdef SQLITE_DEBUG
72842   if( (db->flags & SQLITE_SqlTrace)!=0
72843    && (u.cs.zTrace = (pOp->p4.z ? pOp->p4.z : p->zSql))!=0
72844   ){
72845     sqlite3DebugPrintf("SQL-trace: %s\n", u.cs.zTrace);
72846   }
72847 #endif /* SQLITE_DEBUG */
72848   break;
72849 }
72850 #endif
72851 
72852 
72853 /* Opcode: Noop * * * * *
72854 **
72855 ** Do nothing.  This instruction is often useful as a jump
72856 ** destination.
72857 */
72858 /*
72859 ** The magic Explain opcode are only inserted when explain==2 (which
72860 ** is to say when the EXPLAIN QUERY PLAN syntax is used.)
72861 ** This opcode records information from the optimizer.  It is the
72862 ** the same as a no-op.  This opcodesnever appears in a real VM program.
72863 */
72864 default: {          /* This is really OP_Noop and OP_Explain */
72865   assert( pOp->opcode==OP_Noop || pOp->opcode==OP_Explain );
72866   break;
72867 }
72868 
72869 /*****************************************************************************
72870 ** The cases of the switch statement above this line should all be indented
72871 ** by 6 spaces.  But the left-most 6 spaces have been removed to improve the
72872 ** readability.  From this point on down, the normal indentation rules are
72873 ** restored.
72874 *****************************************************************************/
72875     }
72876 
72877 #ifdef VDBE_PROFILE
72878     {
72879       u64 elapsed = sqlite3Hwtime() - start;
72880       pOp->cycles += elapsed;
72881       pOp->cnt++;
72882 #if 0
72883         fprintf(stdout, "%10llu ", elapsed);
72884         sqlite3VdbePrintOp(stdout, origPc, &aOp[origPc]);
72885 #endif
72886     }
72887 #endif
72888 
72889     /* The following code adds nothing to the actual functionality
72890     ** of the program.  It is only here for testing and debugging.
72891     ** On the other hand, it does burn CPU cycles every time through
72892     ** the evaluator loop.  So we can leave it out when NDEBUG is defined.
72893     */
72894 #ifndef NDEBUG
72895     assert( pc>=-1 && pc<p->nOp );
72896 
72897 #ifdef SQLITE_DEBUG
72898     if( db->flags & SQLITE_VdbeTrace ){
72899       if( rc!=0 ) printf("rc=%d\n",rc);
72900       if( pOp->opflags & (OPFLG_OUT2_PRERELEASE|OPFLG_OUT2) ){
72901         registerTrace(pOp->p2, &aMem[pOp->p2]);
72902       }
72903       if( pOp->opflags & OPFLG_OUT3 ){
72904         registerTrace(pOp->p3, &aMem[pOp->p3]);
72905       }
72906     }
72907 #endif  /* SQLITE_DEBUG */
72908 #endif  /* NDEBUG */
72909   }  /* The end of the for(;;) loop the loops through opcodes */
72910 
72911   /* If we reach this point, it means that execution is finished with
72912   ** an error of some kind.
72913   */
72914 vdbe_error_halt:
72915   assert( rc );
72916   p->rc = rc;
72917   testcase( sqlite3GlobalConfig.xLog!=0 );
72918   sqlite3_log(rc, "statement aborts at %d: [%s] %s", 
72919                    pc, p->zSql, p->zErrMsg);
72920   sqlite3VdbeHalt(p);
72921   if( rc==SQLITE_IOERR_NOMEM ) db->mallocFailed = 1;
72922   rc = SQLITE_ERROR;
72923   if( resetSchemaOnFault>0 ){
72924     sqlite3ResetOneSchema(db, resetSchemaOnFault-1);
72925   }
72926 
72927   /* This is the only way out of this procedure.  We have to
72928   ** release the mutexes on btrees that were acquired at the
72929   ** top. */
72930 vdbe_return:
72931   db->lastRowid = lastRowid;
72932   testcase( nVmStep>0 );
72933   p->aCounter[SQLITE_STMTSTATUS_VM_STEP] += (int)nVmStep;
72934   sqlite3VdbeLeave(p);
72935   return rc;
72936 
72937   /* Jump to here if a string or blob larger than SQLITE_MAX_LENGTH
72938   ** is encountered.
72939   */
72940 too_big:
72941   sqlite3SetString(&p->zErrMsg, db, "string or blob too big");
72942   rc = SQLITE_TOOBIG;
72943   goto vdbe_error_halt;
72944 
72945   /* Jump to here if a malloc() fails.
72946   */
72947 no_mem:
72948   db->mallocFailed = 1;
72949   sqlite3SetString(&p->zErrMsg, db, "out of memory");
72950   rc = SQLITE_NOMEM;
72951   goto vdbe_error_halt;
72952 
72953   /* Jump to here for any other kind of fatal error.  The "rc" variable
72954   ** should hold the error number.
72955   */
72956 abort_due_to_error:
72957   assert( p->zErrMsg==0 );
72958   if( db->mallocFailed ) rc = SQLITE_NOMEM;
72959   if( rc!=SQLITE_IOERR_NOMEM ){
72960     sqlite3SetString(&p->zErrMsg, db, "%s", sqlite3ErrStr(rc));
72961   }
72962   goto vdbe_error_halt;
72963 
72964   /* Jump to here if the sqlite3_interrupt() API sets the interrupt
72965   ** flag.
72966   */
72967 abort_due_to_interrupt:
72968   assert( db->u1.isInterrupted );
72969   rc = SQLITE_INTERRUPT;
72970   p->rc = rc;
72971   sqlite3SetString(&p->zErrMsg, db, "%s", sqlite3ErrStr(rc));
72972   goto vdbe_error_halt;
72973 }
72974 
72975 /************** End of vdbe.c ************************************************/
72976 /************** Begin file vdbeblob.c ****************************************/
72977 /*
72978 ** 2007 May 1
72979 **
72980 ** The author disclaims copyright to this source code.  In place of
72981 ** a legal notice, here is a blessing:
72982 **
72983 **    May you do good and not evil.
72984 **    May you find forgiveness for yourself and forgive others.
72985 **    May you share freely, never taking more than you give.
72986 **
72987 *************************************************************************
72988 **
72989 ** This file contains code used to implement incremental BLOB I/O.
72990 */
72991 
72992 
72993 #ifndef SQLITE_OMIT_INCRBLOB
72994 
72995 /*
72996 ** Valid sqlite3_blob* handles point to Incrblob structures.
72997 */
72998 typedef struct Incrblob Incrblob;
72999 struct Incrblob {
73000   int flags;              /* Copy of "flags" passed to sqlite3_blob_open() */
73001   int nByte;              /* Size of open blob, in bytes */
73002   int iOffset;            /* Byte offset of blob in cursor data */
73003   int iCol;               /* Table column this handle is open on */
73004   BtCursor *pCsr;         /* Cursor pointing at blob row */
73005   sqlite3_stmt *pStmt;    /* Statement holding cursor open */
73006   sqlite3 *db;            /* The associated database */
73007 };
73008 
73009 
73010 /*
73011 ** This function is used by both blob_open() and blob_reopen(). It seeks
73012 ** the b-tree cursor associated with blob handle p to point to row iRow.
73013 ** If successful, SQLITE_OK is returned and subsequent calls to
73014 ** sqlite3_blob_read() or sqlite3_blob_write() access the specified row.
73015 **
73016 ** If an error occurs, or if the specified row does not exist or does not
73017 ** contain a value of type TEXT or BLOB in the column nominated when the
73018 ** blob handle was opened, then an error code is returned and *pzErr may
73019 ** be set to point to a buffer containing an error message. It is the
73020 ** responsibility of the caller to free the error message buffer using
73021 ** sqlite3DbFree().
73022 **
73023 ** If an error does occur, then the b-tree cursor is closed. All subsequent
73024 ** calls to sqlite3_blob_read(), blob_write() or blob_reopen() will 
73025 ** immediately return SQLITE_ABORT.
73026 */
73027 static int blobSeekToRow(Incrblob *p, sqlite3_int64 iRow, char **pzErr){
73028   int rc;                         /* Error code */
73029   char *zErr = 0;                 /* Error message */
73030   Vdbe *v = (Vdbe *)p->pStmt;
73031 
73032   /* Set the value of the SQL statements only variable to integer iRow. 
73033   ** This is done directly instead of using sqlite3_bind_int64() to avoid 
73034   ** triggering asserts related to mutexes.
73035   */
73036   assert( v->aVar[0].flags&MEM_Int );
73037   v->aVar[0].u.i = iRow;
73038 
73039   rc = sqlite3_step(p->pStmt);
73040   if( rc==SQLITE_ROW ){
73041     VdbeCursor *pC = v->apCsr[0];
73042     u32 type = pC->aType[p->iCol];
73043     if( type<12 ){
73044       zErr = sqlite3MPrintf(p->db, "cannot open value of type %s",
73045           type==0?"null": type==7?"real": "integer"
73046       );
73047       rc = SQLITE_ERROR;
73048       sqlite3_finalize(p->pStmt);
73049       p->pStmt = 0;
73050     }else{
73051       p->iOffset = pC->aType[p->iCol + pC->nField];
73052       p->nByte = sqlite3VdbeSerialTypeLen(type);
73053       p->pCsr =  pC->pCursor;
73054       sqlite3BtreeEnterCursor(p->pCsr);
73055       sqlite3BtreeCacheOverflow(p->pCsr);
73056       sqlite3BtreeLeaveCursor(p->pCsr);
73057     }
73058   }
73059 
73060   if( rc==SQLITE_ROW ){
73061     rc = SQLITE_OK;
73062   }else if( p->pStmt ){
73063     rc = sqlite3_finalize(p->pStmt);
73064     p->pStmt = 0;
73065     if( rc==SQLITE_OK ){
73066       zErr = sqlite3MPrintf(p->db, "no such rowid: %lld", iRow);
73067       rc = SQLITE_ERROR;
73068     }else{
73069       zErr = sqlite3MPrintf(p->db, "%s", sqlite3_errmsg(p->db));
73070     }
73071   }
73072 
73073   assert( rc!=SQLITE_OK || zErr==0 );
73074   assert( rc!=SQLITE_ROW && rc!=SQLITE_DONE );
73075 
73076   *pzErr = zErr;
73077   return rc;
73078 }
73079 
73080 /*
73081 ** Open a blob handle.
73082 */
73083 SQLITE_API int sqlite3_blob_open(
73084   sqlite3* db,            /* The database connection */
73085   const char *zDb,        /* The attached database containing the blob */
73086   const char *zTable,     /* The table containing the blob */
73087   const char *zColumn,    /* The column containing the blob */
73088   sqlite_int64 iRow,      /* The row containing the glob */
73089   int flags,              /* True -> read/write access, false -> read-only */
73090   sqlite3_blob **ppBlob   /* Handle for accessing the blob returned here */
73091 ){
73092   int nAttempt = 0;
73093   int iCol;               /* Index of zColumn in row-record */
73094 
73095   /* This VDBE program seeks a btree cursor to the identified 
73096   ** db/table/row entry. The reason for using a vdbe program instead
73097   ** of writing code to use the b-tree layer directly is that the
73098   ** vdbe program will take advantage of the various transaction,
73099   ** locking and error handling infrastructure built into the vdbe.
73100   **
73101   ** After seeking the cursor, the vdbe executes an OP_ResultRow.
73102   ** Code external to the Vdbe then "borrows" the b-tree cursor and
73103   ** uses it to implement the blob_read(), blob_write() and 
73104   ** blob_bytes() functions.
73105   **
73106   ** The sqlite3_blob_close() function finalizes the vdbe program,
73107   ** which closes the b-tree cursor and (possibly) commits the 
73108   ** transaction.
73109   */
73110   static const VdbeOpList openBlob[] = {
73111     {OP_Transaction, 0, 0, 0},     /* 0: Start a transaction */
73112     {OP_VerifyCookie, 0, 0, 0},    /* 1: Check the schema cookie */
73113     {OP_TableLock, 0, 0, 0},       /* 2: Acquire a read or write lock */
73114 
73115     /* One of the following two instructions is replaced by an OP_Noop. */
73116     {OP_OpenRead, 0, 0, 0},        /* 3: Open cursor 0 for reading */
73117     {OP_OpenWrite, 0, 0, 0},       /* 4: Open cursor 0 for read/write */
73118 
73119     {OP_Variable, 1, 1, 1},        /* 5: Push the rowid to the stack */
73120     {OP_NotExists, 0, 10, 1},      /* 6: Seek the cursor */
73121     {OP_Column, 0, 0, 1},          /* 7  */
73122     {OP_ResultRow, 1, 0, 0},       /* 8  */
73123     {OP_Goto, 0, 5, 0},            /* 9  */
73124     {OP_Close, 0, 0, 0},           /* 10 */
73125     {OP_Halt, 0, 0, 0},            /* 11 */
73126   };
73127 
73128   int rc = SQLITE_OK;
73129   char *zErr = 0;
73130   Table *pTab;
73131   Parse *pParse = 0;
73132   Incrblob *pBlob = 0;
73133 
73134   flags = !!flags;                /* flags = (flags ? 1 : 0); */
73135   *ppBlob = 0;
73136 
73137   sqlite3_mutex_enter(db->mutex);
73138 
73139   pBlob = (Incrblob *)sqlite3DbMallocZero(db, sizeof(Incrblob));
73140   if( !pBlob ) goto blob_open_out;
73141   pParse = sqlite3StackAllocRaw(db, sizeof(*pParse));
73142   if( !pParse ) goto blob_open_out;
73143 
73144   do {
73145     memset(pParse, 0, sizeof(Parse));
73146     pParse->db = db;
73147     sqlite3DbFree(db, zErr);
73148     zErr = 0;
73149 
73150     sqlite3BtreeEnterAll(db);
73151     pTab = sqlite3LocateTable(pParse, 0, zTable, zDb);
73152     if( pTab && IsVirtual(pTab) ){
73153       pTab = 0;
73154       sqlite3ErrorMsg(pParse, "cannot open virtual table: %s", zTable);
73155     }
73156     if( pTab && !HasRowid(pTab) ){
73157       pTab = 0;
73158       sqlite3ErrorMsg(pParse, "cannot open table without rowid: %s", zTable);
73159     }
73160 #ifndef SQLITE_OMIT_VIEW
73161     if( pTab && pTab->pSelect ){
73162       pTab = 0;
73163       sqlite3ErrorMsg(pParse, "cannot open view: %s", zTable);
73164     }
73165 #endif
73166     if( !pTab ){
73167       if( pParse->zErrMsg ){
73168         sqlite3DbFree(db, zErr);
73169         zErr = pParse->zErrMsg;
73170         pParse->zErrMsg = 0;
73171       }
73172       rc = SQLITE_ERROR;
73173       sqlite3BtreeLeaveAll(db);
73174       goto blob_open_out;
73175     }
73176 
73177     /* Now search pTab for the exact column. */
73178     for(iCol=0; iCol<pTab->nCol; iCol++) {
73179       if( sqlite3StrICmp(pTab->aCol[iCol].zName, zColumn)==0 ){
73180         break;
73181       }
73182     }
73183     if( iCol==pTab->nCol ){
73184       sqlite3DbFree(db, zErr);
73185       zErr = sqlite3MPrintf(db, "no such column: \"%s\"", zColumn);
73186       rc = SQLITE_ERROR;
73187       sqlite3BtreeLeaveAll(db);
73188       goto blob_open_out;
73189     }
73190 
73191     /* If the value is being opened for writing, check that the
73192     ** column is not indexed, and that it is not part of a foreign key. 
73193     ** It is against the rules to open a column to which either of these
73194     ** descriptions applies for writing.  */
73195     if( flags ){
73196       const char *zFault = 0;
73197       Index *pIdx;
73198 #ifndef SQLITE_OMIT_FOREIGN_KEY
73199       if( db->flags&SQLITE_ForeignKeys ){
73200         /* Check that the column is not part of an FK child key definition. It
73201         ** is not necessary to check if it is part of a parent key, as parent
73202         ** key columns must be indexed. The check below will pick up this 
73203         ** case.  */
73204         FKey *pFKey;
73205         for(pFKey=pTab->pFKey; pFKey; pFKey=pFKey->pNextFrom){
73206           int j;
73207           for(j=0; j<pFKey->nCol; j++){
73208             if( pFKey->aCol[j].iFrom==iCol ){
73209               zFault = "foreign key";
73210             }
73211           }
73212         }
73213       }
73214 #endif
73215       for(pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext){
73216         int j;
73217         for(j=0; j<pIdx->nKeyCol; j++){
73218           if( pIdx->aiColumn[j]==iCol ){
73219             zFault = "indexed";
73220           }
73221         }
73222       }
73223       if( zFault ){
73224         sqlite3DbFree(db, zErr);
73225         zErr = sqlite3MPrintf(db, "cannot open %s column for writing", zFault);
73226         rc = SQLITE_ERROR;
73227         sqlite3BtreeLeaveAll(db);
73228         goto blob_open_out;
73229       }
73230     }
73231 
73232     pBlob->pStmt = (sqlite3_stmt *)sqlite3VdbeCreate(db);
73233     assert( pBlob->pStmt || db->mallocFailed );
73234     if( pBlob->pStmt ){
73235       Vdbe *v = (Vdbe *)pBlob->pStmt;
73236       int iDb = sqlite3SchemaToIndex(db, pTab->pSchema);
73237 
73238       sqlite3VdbeAddOpList(v, sizeof(openBlob)/sizeof(VdbeOpList), openBlob);
73239 
73240 
73241       /* Configure the OP_Transaction */
73242       sqlite3VdbeChangeP1(v, 0, iDb);
73243       sqlite3VdbeChangeP2(v, 0, flags);
73244 
73245       /* Configure the OP_VerifyCookie */
73246       sqlite3VdbeChangeP1(v, 1, iDb);
73247       sqlite3VdbeChangeP2(v, 1, pTab->pSchema->schema_cookie);
73248       sqlite3VdbeChangeP3(v, 1, pTab->pSchema->iGeneration);
73249 
73250       /* Make sure a mutex is held on the table to be accessed */
73251       sqlite3VdbeUsesBtree(v, iDb); 
73252 
73253       /* Configure the OP_TableLock instruction */
73254 #ifdef SQLITE_OMIT_SHARED_CACHE
73255       sqlite3VdbeChangeToNoop(v, 2);
73256 #else
73257       sqlite3VdbeChangeP1(v, 2, iDb);
73258       sqlite3VdbeChangeP2(v, 2, pTab->tnum);
73259       sqlite3VdbeChangeP3(v, 2, flags);
73260       sqlite3VdbeChangeP4(v, 2, pTab->zName, P4_TRANSIENT);
73261 #endif
73262 
73263       /* Remove either the OP_OpenWrite or OpenRead. Set the P2 
73264       ** parameter of the other to pTab->tnum.  */
73265       sqlite3VdbeChangeToNoop(v, 4 - flags);
73266       sqlite3VdbeChangeP2(v, 3 + flags, pTab->tnum);
73267       sqlite3VdbeChangeP3(v, 3 + flags, iDb);
73268 
73269       /* Configure the number of columns. Configure the cursor to
73270       ** think that the table has one more column than it really
73271       ** does. An OP_Column to retrieve this imaginary column will
73272       ** always return an SQL NULL. This is useful because it means
73273       ** we can invoke OP_Column to fill in the vdbe cursors type 
73274       ** and offset cache without causing any IO.
73275       */
73276       sqlite3VdbeChangeP4(v, 3+flags, SQLITE_INT_TO_PTR(pTab->nCol+1),P4_INT32);
73277       sqlite3VdbeChangeP2(v, 7, pTab->nCol);
73278       if( !db->mallocFailed ){
73279         pParse->nVar = 1;
73280         pParse->nMem = 1;
73281         pParse->nTab = 1;
73282         sqlite3VdbeMakeReady(v, pParse);
73283       }
73284     }
73285    
73286     pBlob->flags = flags;
73287     pBlob->iCol = iCol;
73288     pBlob->db = db;
73289     sqlite3BtreeLeaveAll(db);
73290     if( db->mallocFailed ){
73291       goto blob_open_out;
73292     }
73293     sqlite3_bind_int64(pBlob->pStmt, 1, iRow);
73294     rc = blobSeekToRow(pBlob, iRow, &zErr);
73295   } while( (++nAttempt)<SQLITE_MAX_SCHEMA_RETRY && rc==SQLITE_SCHEMA );
73296 
73297 blob_open_out:
73298   if( rc==SQLITE_OK && db->mallocFailed==0 ){
73299     *ppBlob = (sqlite3_blob *)pBlob;
73300   }else{
73301     if( pBlob && pBlob->pStmt ) sqlite3VdbeFinalize((Vdbe *)pBlob->pStmt);
73302     sqlite3DbFree(db, pBlob);
73303   }
73304   sqlite3Error(db, rc, (zErr ? "%s" : 0), zErr);
73305   sqlite3DbFree(db, zErr);
73306   sqlite3ParserReset(pParse);
73307   sqlite3StackFree(db, pParse);
73308   rc = sqlite3ApiExit(db, rc);
73309   sqlite3_mutex_leave(db->mutex);
73310   return rc;
73311 }
73312 
73313 /*
73314 ** Close a blob handle that was previously created using
73315 ** sqlite3_blob_open().
73316 */
73317 SQLITE_API int sqlite3_blob_close(sqlite3_blob *pBlob){
73318   Incrblob *p = (Incrblob *)pBlob;
73319   int rc;
73320   sqlite3 *db;
73321 
73322   if( p ){
73323     db = p->db;
73324     sqlite3_mutex_enter(db->mutex);
73325     rc = sqlite3_finalize(p->pStmt);
73326     sqlite3DbFree(db, p);
73327     sqlite3_mutex_leave(db->mutex);
73328   }else{
73329     rc = SQLITE_OK;
73330   }
73331   return rc;
73332 }
73333 
73334 /*
73335 ** Perform a read or write operation on a blob
73336 */
73337 static int blobReadWrite(
73338   sqlite3_blob *pBlob, 
73339   void *z, 
73340   int n, 
73341   int iOffset, 
73342   int (*xCall)(BtCursor*, u32, u32, void*)
73343 ){
73344   int rc;
73345   Incrblob *p = (Incrblob *)pBlob;
73346   Vdbe *v;
73347   sqlite3 *db;
73348 
73349   if( p==0 ) return SQLITE_MISUSE_BKPT;
73350   db = p->db;
73351   sqlite3_mutex_enter(db->mutex);
73352   v = (Vdbe*)p->pStmt;
73353 
73354   if( n<0 || iOffset<0 || (iOffset+n)>p->nByte ){
73355     /* Request is out of range. Return a transient error. */
73356     rc = SQLITE_ERROR;
73357     sqlite3Error(db, SQLITE_ERROR, 0);
73358   }else if( v==0 ){
73359     /* If there is no statement handle, then the blob-handle has
73360     ** already been invalidated. Return SQLITE_ABORT in this case.
73361     */
73362     rc = SQLITE_ABORT;
73363   }else{
73364     /* Call either BtreeData() or BtreePutData(). If SQLITE_ABORT is
73365     ** returned, clean-up the statement handle.
73366     */
73367     assert( db == v->db );
73368     sqlite3BtreeEnterCursor(p->pCsr);
73369     rc = xCall(p->pCsr, iOffset+p->iOffset, n, z);
73370     sqlite3BtreeLeaveCursor(p->pCsr);
73371     if( rc==SQLITE_ABORT ){
73372       sqlite3VdbeFinalize(v);
73373       p->pStmt = 0;
73374     }else{
73375       db->errCode = rc;
73376       v->rc = rc;
73377     }
73378   }
73379   rc = sqlite3ApiExit(db, rc);
73380   sqlite3_mutex_leave(db->mutex);
73381   return rc;
73382 }
73383 
73384 /*
73385 ** Read data from a blob handle.
73386 */
73387 SQLITE_API int sqlite3_blob_read(sqlite3_blob *pBlob, void *z, int n, int iOffset){
73388   return blobReadWrite(pBlob, z, n, iOffset, sqlite3BtreeData);
73389 }
73390 
73391 /*
73392 ** Write data to a blob handle.
73393 */
73394 SQLITE_API int sqlite3_blob_write(sqlite3_blob *pBlob, const void *z, int n, int iOffset){
73395   return blobReadWrite(pBlob, (void *)z, n, iOffset, sqlite3BtreePutData);
73396 }
73397 
73398 /*
73399 ** Query a blob handle for the size of the data.
73400 **
73401 ** The Incrblob.nByte field is fixed for the lifetime of the Incrblob
73402 ** so no mutex is required for access.
73403 */
73404 SQLITE_API int sqlite3_blob_bytes(sqlite3_blob *pBlob){
73405   Incrblob *p = (Incrblob *)pBlob;
73406   return (p && p->pStmt) ? p->nByte : 0;
73407 }
73408 
73409 /*
73410 ** Move an existing blob handle to point to a different row of the same
73411 ** database table.
73412 **
73413 ** If an error occurs, or if the specified row does not exist or does not
73414 ** contain a blob or text value, then an error code is returned and the
73415 ** database handle error code and message set. If this happens, then all 
73416 ** subsequent calls to sqlite3_blob_xxx() functions (except blob_close()) 
73417 ** immediately return SQLITE_ABORT.
73418 */
73419 SQLITE_API int sqlite3_blob_reopen(sqlite3_blob *pBlob, sqlite3_int64 iRow){
73420   int rc;
73421   Incrblob *p = (Incrblob *)pBlob;
73422   sqlite3 *db;
73423 
73424   if( p==0 ) return SQLITE_MISUSE_BKPT;
73425   db = p->db;
73426   sqlite3_mutex_enter(db->mutex);
73427 
73428   if( p->pStmt==0 ){
73429     /* If there is no statement handle, then the blob-handle has
73430     ** already been invalidated. Return SQLITE_ABORT in this case.
73431     */
73432     rc = SQLITE_ABORT;
73433   }else{
73434     char *zErr;
73435     rc = blobSeekToRow(p, iRow, &zErr);
73436     if( rc!=SQLITE_OK ){
73437       sqlite3Error(db, rc, (zErr ? "%s" : 0), zErr);
73438       sqlite3DbFree(db, zErr);
73439     }
73440     assert( rc!=SQLITE_SCHEMA );
73441   }
73442 
73443   rc = sqlite3ApiExit(db, rc);
73444   assert( rc==SQLITE_OK || p->pStmt==0 );
73445   sqlite3_mutex_leave(db->mutex);
73446   return rc;
73447 }
73448 
73449 #endif /* #ifndef SQLITE_OMIT_INCRBLOB */
73450 
73451 /************** End of vdbeblob.c ********************************************/
73452 /************** Begin file vdbesort.c ****************************************/
73453 /*
73454 ** 2011 July 9
73455 **
73456 ** The author disclaims copyright to this source code.  In place of
73457 ** a legal notice, here is a blessing:
73458 **
73459 **    May you do good and not evil.
73460 **    May you find forgiveness for yourself and forgive others.
73461 **    May you share freely, never taking more than you give.
73462 **
73463 *************************************************************************
73464 ** This file contains code for the VdbeSorter object, used in concert with
73465 ** a VdbeCursor to sort large numbers of keys (as may be required, for
73466 ** example, by CREATE INDEX statements on tables too large to fit in main
73467 ** memory).
73468 */
73469 
73470 
73471 
73472 typedef struct VdbeSorterIter VdbeSorterIter;
73473 typedef struct SorterRecord SorterRecord;
73474 typedef struct FileWriter FileWriter;
73475 
73476 /*
73477 ** NOTES ON DATA STRUCTURE USED FOR N-WAY MERGES:
73478 **
73479 ** As keys are added to the sorter, they are written to disk in a series
73480 ** of sorted packed-memory-arrays (PMAs). The size of each PMA is roughly
73481 ** the same as the cache-size allowed for temporary databases. In order
73482 ** to allow the caller to extract keys from the sorter in sorted order,
73483 ** all PMAs currently stored on disk must be merged together. This comment
73484 ** describes the data structure used to do so. The structure supports 
73485 ** merging any number of arrays in a single pass with no redundant comparison 
73486 ** operations.
73487 **
73488 ** The aIter[] array contains an iterator for each of the PMAs being merged.
73489 ** An aIter[] iterator either points to a valid key or else is at EOF. For 
73490 ** the purposes of the paragraphs below, we assume that the array is actually 
73491 ** N elements in size, where N is the smallest power of 2 greater to or equal 
73492 ** to the number of iterators being merged. The extra aIter[] elements are 
73493 ** treated as if they are empty (always at EOF).
73494 **
73495 ** The aTree[] array is also N elements in size. The value of N is stored in
73496 ** the VdbeSorter.nTree variable.
73497 **
73498 ** The final (N/2) elements of aTree[] contain the results of comparing
73499 ** pairs of iterator keys together. Element i contains the result of 
73500 ** comparing aIter[2*i-N] and aIter[2*i-N+1]. Whichever key is smaller, the
73501 ** aTree element is set to the index of it. 
73502 **
73503 ** For the purposes of this comparison, EOF is considered greater than any
73504 ** other key value. If the keys are equal (only possible with two EOF
73505 ** values), it doesn't matter which index is stored.
73506 **
73507 ** The (N/4) elements of aTree[] that precede the final (N/2) described 
73508 ** above contains the index of the smallest of each block of 4 iterators.
73509 ** And so on. So that aTree[1] contains the index of the iterator that 
73510 ** currently points to the smallest key value. aTree[0] is unused.
73511 **
73512 ** Example:
73513 **
73514 **     aIter[0] -> Banana
73515 **     aIter[1] -> Feijoa
73516 **     aIter[2] -> Elderberry
73517 **     aIter[3] -> Currant
73518 **     aIter[4] -> Grapefruit
73519 **     aIter[5] -> Apple
73520 **     aIter[6] -> Durian
73521 **     aIter[7] -> EOF
73522 **
73523 **     aTree[] = { X, 5   0, 5    0, 3, 5, 6 }
73524 **
73525 ** The current element is "Apple" (the value of the key indicated by 
73526 ** iterator 5). When the Next() operation is invoked, iterator 5 will
73527 ** be advanced to the next key in its segment. Say the next key is
73528 ** "Eggplant":
73529 **
73530 **     aIter[5] -> Eggplant
73531 **
73532 ** The contents of aTree[] are updated first by comparing the new iterator
73533 ** 5 key to the current key of iterator 4 (still "Grapefruit"). The iterator
73534 ** 5 value is still smaller, so aTree[6] is set to 5. And so on up the tree.
73535 ** The value of iterator 6 - "Durian" - is now smaller than that of iterator
73536 ** 5, so aTree[3] is set to 6. Key 0 is smaller than key 6 (Banana<Durian),
73537 ** so the value written into element 1 of the array is 0. As follows:
73538 **
73539 **     aTree[] = { X, 0   0, 6    0, 3, 5, 6 }
73540 **
73541 ** In other words, each time we advance to the next sorter element, log2(N)
73542 ** key comparison operations are required, where N is the number of segments
73543 ** being merged (rounded up to the next power of 2).
73544 */
73545 struct VdbeSorter {
73546   i64 iWriteOff;                  /* Current write offset within file pTemp1 */
73547   i64 iReadOff;                   /* Current read offset within file pTemp1 */
73548   int nInMemory;                  /* Current size of pRecord list as PMA */
73549   int nTree;                      /* Used size of aTree/aIter (power of 2) */
73550   int nPMA;                       /* Number of PMAs stored in pTemp1 */
73551   int mnPmaSize;                  /* Minimum PMA size, in bytes */
73552   int mxPmaSize;                  /* Maximum PMA size, in bytes.  0==no limit */
73553   VdbeSorterIter *aIter;          /* Array of iterators to merge */
73554   int *aTree;                     /* Current state of incremental merge */
73555   sqlite3_file *pTemp1;           /* PMA file 1 */
73556   SorterRecord *pRecord;          /* Head of in-memory record list */
73557   UnpackedRecord *pUnpacked;      /* Used to unpack keys */
73558 };
73559 
73560 /*
73561 ** The following type is an iterator for a PMA. It caches the current key in 
73562 ** variables nKey/aKey. If the iterator is at EOF, pFile==0.
73563 */
73564 struct VdbeSorterIter {
73565   i64 iReadOff;                   /* Current read offset */
73566   i64 iEof;                       /* 1 byte past EOF for this iterator */
73567   int nAlloc;                     /* Bytes of space at aAlloc */
73568   int nKey;                       /* Number of bytes in key */
73569   sqlite3_file *pFile;            /* File iterator is reading from */
73570   u8 *aAlloc;                     /* Allocated space */
73571   u8 *aKey;                       /* Pointer to current key */
73572   u8 *aBuffer;                    /* Current read buffer */
73573   int nBuffer;                    /* Size of read buffer in bytes */
73574 };
73575 
73576 /*
73577 ** An instance of this structure is used to organize the stream of records
73578 ** being written to files by the merge-sort code into aligned, page-sized
73579 ** blocks.  Doing all I/O in aligned page-sized blocks helps I/O to go
73580 ** faster on many operating systems.
73581 */
73582 struct FileWriter {
73583   int eFWErr;                     /* Non-zero if in an error state */
73584   u8 *aBuffer;                    /* Pointer to write buffer */
73585   int nBuffer;                    /* Size of write buffer in bytes */
73586   int iBufStart;                  /* First byte of buffer to write */
73587   int iBufEnd;                    /* Last byte of buffer to write */
73588   i64 iWriteOff;                  /* Offset of start of buffer in file */
73589   sqlite3_file *pFile;            /* File to write to */
73590 };
73591 
73592 /*
73593 ** A structure to store a single record. All in-memory records are connected
73594 ** together into a linked list headed at VdbeSorter.pRecord using the 
73595 ** SorterRecord.pNext pointer.
73596 */
73597 struct SorterRecord {
73598   void *pVal;
73599   int nVal;
73600   SorterRecord *pNext;
73601 };
73602 
73603 /* Minimum allowable value for the VdbeSorter.nWorking variable */
73604 #define SORTER_MIN_WORKING 10
73605 
73606 /* Maximum number of segments to merge in a single pass. */
73607 #define SORTER_MAX_MERGE_COUNT 16
73608 
73609 /*
73610 ** Free all memory belonging to the VdbeSorterIter object passed as the second
73611 ** argument. All structure fields are set to zero before returning.
73612 */
73613 static void vdbeSorterIterZero(sqlite3 *db, VdbeSorterIter *pIter){
73614   sqlite3DbFree(db, pIter->aAlloc);
73615   sqlite3DbFree(db, pIter->aBuffer);
73616   memset(pIter, 0, sizeof(VdbeSorterIter));
73617 }
73618 
73619 /*
73620 ** Read nByte bytes of data from the stream of data iterated by object p.
73621 ** If successful, set *ppOut to point to a buffer containing the data
73622 ** and return SQLITE_OK. Otherwise, if an error occurs, return an SQLite
73623 ** error code.
73624 **
73625 ** The buffer indicated by *ppOut may only be considered valid until the
73626 ** next call to this function.
73627 */
73628 static int vdbeSorterIterRead(
73629   sqlite3 *db,                    /* Database handle (for malloc) */
73630   VdbeSorterIter *p,              /* Iterator */
73631   int nByte,                      /* Bytes of data to read */
73632   u8 **ppOut                      /* OUT: Pointer to buffer containing data */
73633 ){
73634   int iBuf;                       /* Offset within buffer to read from */
73635   int nAvail;                     /* Bytes of data available in buffer */
73636   assert( p->aBuffer );
73637 
73638   /* If there is no more data to be read from the buffer, read the next 
73639   ** p->nBuffer bytes of data from the file into it. Or, if there are less
73640   ** than p->nBuffer bytes remaining in the PMA, read all remaining data.  */
73641   iBuf = p->iReadOff % p->nBuffer;
73642   if( iBuf==0 ){
73643     int nRead;                    /* Bytes to read from disk */
73644     int rc;                       /* sqlite3OsRead() return code */
73645 
73646     /* Determine how many bytes of data to read. */
73647     if( (p->iEof - p->iReadOff) > (i64)p->nBuffer ){
73648       nRead = p->nBuffer;
73649     }else{
73650       nRead = (int)(p->iEof - p->iReadOff);
73651     }
73652     assert( nRead>0 );
73653 
73654     /* Read data from the file. Return early if an error occurs. */
73655     rc = sqlite3OsRead(p->pFile, p->aBuffer, nRead, p->iReadOff);
73656     assert( rc!=SQLITE_IOERR_SHORT_READ );
73657     if( rc!=SQLITE_OK ) return rc;
73658   }
73659   nAvail = p->nBuffer - iBuf; 
73660 
73661   if( nByte<=nAvail ){
73662     /* The requested data is available in the in-memory buffer. In this
73663     ** case there is no need to make a copy of the data, just return a 
73664     ** pointer into the buffer to the caller.  */
73665     *ppOut = &p->aBuffer[iBuf];
73666     p->iReadOff += nByte;
73667   }else{
73668     /* The requested data is not all available in the in-memory buffer.
73669     ** In this case, allocate space at p->aAlloc[] to copy the requested
73670     ** range into. Then return a copy of pointer p->aAlloc to the caller.  */
73671     int nRem;                     /* Bytes remaining to copy */
73672 
73673     /* Extend the p->aAlloc[] allocation if required. */
73674     if( p->nAlloc<nByte ){
73675       int nNew = p->nAlloc*2;
73676       while( nByte>nNew ) nNew = nNew*2;
73677       p->aAlloc = sqlite3DbReallocOrFree(db, p->aAlloc, nNew);
73678       if( !p->aAlloc ) return SQLITE_NOMEM;
73679       p->nAlloc = nNew;
73680     }
73681 
73682     /* Copy as much data as is available in the buffer into the start of
73683     ** p->aAlloc[].  */
73684     memcpy(p->aAlloc, &p->aBuffer[iBuf], nAvail);
73685     p->iReadOff += nAvail;
73686     nRem = nByte - nAvail;
73687 
73688     /* The following loop copies up to p->nBuffer bytes per iteration into
73689     ** the p->aAlloc[] buffer.  */
73690     while( nRem>0 ){
73691       int rc;                     /* vdbeSorterIterRead() return code */
73692       int nCopy;                  /* Number of bytes to copy */
73693       u8 *aNext;                  /* Pointer to buffer to copy data from */
73694 
73695       nCopy = nRem;
73696       if( nRem>p->nBuffer ) nCopy = p->nBuffer;
73697       rc = vdbeSorterIterRead(db, p, nCopy, &aNext);
73698       if( rc!=SQLITE_OK ) return rc;
73699       assert( aNext!=p->aAlloc );
73700       memcpy(&p->aAlloc[nByte - nRem], aNext, nCopy);
73701       nRem -= nCopy;
73702     }
73703 
73704     *ppOut = p->aAlloc;
73705   }
73706 
73707   return SQLITE_OK;
73708 }
73709 
73710 /*
73711 ** Read a varint from the stream of data accessed by p. Set *pnOut to
73712 ** the value read.
73713 */
73714 static int vdbeSorterIterVarint(sqlite3 *db, VdbeSorterIter *p, u64 *pnOut){
73715   int iBuf;
73716 
73717   iBuf = p->iReadOff % p->nBuffer;
73718   if( iBuf && (p->nBuffer-iBuf)>=9 ){
73719     p->iReadOff += sqlite3GetVarint(&p->aBuffer[iBuf], pnOut);
73720   }else{
73721     u8 aVarint[16], *a;
73722     int i = 0, rc;
73723     do{
73724       rc = vdbeSorterIterRead(db, p, 1, &a);
73725       if( rc ) return rc;
73726       aVarint[(i++)&0xf] = a[0];
73727     }while( (a[0]&0x80)!=0 );
73728     sqlite3GetVarint(aVarint, pnOut);
73729   }
73730 
73731   return SQLITE_OK;
73732 }
73733 
73734 
73735 /*
73736 ** Advance iterator pIter to the next key in its PMA. Return SQLITE_OK if
73737 ** no error occurs, or an SQLite error code if one does.
73738 */
73739 static int vdbeSorterIterNext(
73740   sqlite3 *db,                    /* Database handle (for sqlite3DbMalloc() ) */
73741   VdbeSorterIter *pIter           /* Iterator to advance */
73742 ){
73743   int rc;                         /* Return Code */
73744   u64 nRec = 0;                   /* Size of record in bytes */
73745 
73746   if( pIter->iReadOff>=pIter->iEof ){
73747     /* This is an EOF condition */
73748     vdbeSorterIterZero(db, pIter);
73749     return SQLITE_OK;
73750   }
73751 
73752   rc = vdbeSorterIterVarint(db, pIter, &nRec);
73753   if( rc==SQLITE_OK ){
73754     pIter->nKey = (int)nRec;
73755     rc = vdbeSorterIterRead(db, pIter, (int)nRec, &pIter->aKey);
73756   }
73757 
73758   return rc;
73759 }
73760 
73761 /*
73762 ** Initialize iterator pIter to scan through the PMA stored in file pFile
73763 ** starting at offset iStart and ending at offset iEof-1. This function 
73764 ** leaves the iterator pointing to the first key in the PMA (or EOF if the 
73765 ** PMA is empty).
73766 */
73767 static int vdbeSorterIterInit(
73768   sqlite3 *db,                    /* Database handle */
73769   const VdbeSorter *pSorter,      /* Sorter object */
73770   i64 iStart,                     /* Start offset in pFile */
73771   VdbeSorterIter *pIter,          /* Iterator to populate */
73772   i64 *pnByte                     /* IN/OUT: Increment this value by PMA size */
73773 ){
73774   int rc = SQLITE_OK;
73775   int nBuf;
73776 
73777   nBuf = sqlite3BtreeGetPageSize(db->aDb[0].pBt);
73778 
73779   assert( pSorter->iWriteOff>iStart );
73780   assert( pIter->aAlloc==0 );
73781   assert( pIter->aBuffer==0 );
73782   pIter->pFile = pSorter->pTemp1;
73783   pIter->iReadOff = iStart;
73784   pIter->nAlloc = 128;
73785   pIter->aAlloc = (u8 *)sqlite3DbMallocRaw(db, pIter->nAlloc);
73786   pIter->nBuffer = nBuf;
73787   pIter->aBuffer = (u8 *)sqlite3DbMallocRaw(db, nBuf);
73788 
73789   if( !pIter->aBuffer ){
73790     rc = SQLITE_NOMEM;
73791   }else{
73792     int iBuf;
73793 
73794     iBuf = iStart % nBuf;
73795     if( iBuf ){
73796       int nRead = nBuf - iBuf;
73797       if( (iStart + nRead) > pSorter->iWriteOff ){
73798         nRead = (int)(pSorter->iWriteOff - iStart);
73799       }
73800       rc = sqlite3OsRead(
73801           pSorter->pTemp1, &pIter->aBuffer[iBuf], nRead, iStart
73802       );
73803       assert( rc!=SQLITE_IOERR_SHORT_READ );
73804     }
73805 
73806     if( rc==SQLITE_OK ){
73807       u64 nByte;                       /* Size of PMA in bytes */
73808       pIter->iEof = pSorter->iWriteOff;
73809       rc = vdbeSorterIterVarint(db, pIter, &nByte);
73810       pIter->iEof = pIter->iReadOff + nByte;
73811       *pnByte += nByte;
73812     }
73813   }
73814 
73815   if( rc==SQLITE_OK ){
73816     rc = vdbeSorterIterNext(db, pIter);
73817   }
73818   return rc;
73819 }
73820 
73821 
73822 /*
73823 ** Compare key1 (buffer pKey1, size nKey1 bytes) with key2 (buffer pKey2, 
73824 ** size nKey2 bytes).  Argument pKeyInfo supplies the collation functions
73825 ** used by the comparison. If an error occurs, return an SQLite error code.
73826 ** Otherwise, return SQLITE_OK and set *pRes to a negative, zero or positive
73827 ** value, depending on whether key1 is smaller, equal to or larger than key2.
73828 **
73829 ** If the bOmitRowid argument is non-zero, assume both keys end in a rowid
73830 ** field. For the purposes of the comparison, ignore it. Also, if bOmitRowid
73831 ** is true and key1 contains even a single NULL value, it is considered to
73832 ** be less than key2. Even if key2 also contains NULL values.
73833 **
73834 ** If pKey2 is passed a NULL pointer, then it is assumed that the pCsr->aSpace
73835 ** has been allocated and contains an unpacked record that is used as key2.
73836 */
73837 static void vdbeSorterCompare(
73838   const VdbeCursor *pCsr,         /* Cursor object (for pKeyInfo) */
73839   int nIgnore,                    /* Ignore the last nIgnore fields */
73840   const void *pKey1, int nKey1,   /* Left side of comparison */
73841   const void *pKey2, int nKey2,   /* Right side of comparison */
73842   int *pRes                       /* OUT: Result of comparison */
73843 ){
73844   KeyInfo *pKeyInfo = pCsr->pKeyInfo;
73845   VdbeSorter *pSorter = pCsr->pSorter;
73846   UnpackedRecord *r2 = pSorter->pUnpacked;
73847   int i;
73848 
73849   if( pKey2 ){
73850     sqlite3VdbeRecordUnpack(pKeyInfo, nKey2, pKey2, r2);
73851   }
73852 
73853   if( nIgnore ){
73854     r2->nField = pKeyInfo->nField - nIgnore;
73855     assert( r2->nField>0 );
73856     for(i=0; i<r2->nField; i++){
73857       if( r2->aMem[i].flags & MEM_Null ){
73858         *pRes = -1;
73859         return;
73860       }
73861     }
73862     r2->flags |= UNPACKED_PREFIX_MATCH;
73863   }
73864 
73865   *pRes = sqlite3VdbeRecordCompare(nKey1, pKey1, r2);
73866 }
73867 
73868 /*
73869 ** This function is called to compare two iterator keys when merging 
73870 ** multiple b-tree segments. Parameter iOut is the index of the aTree[] 
73871 ** value to recalculate.
73872 */
73873 static int vdbeSorterDoCompare(const VdbeCursor *pCsr, int iOut){
73874   VdbeSorter *pSorter = pCsr->pSorter;
73875   int i1;
73876   int i2;
73877   int iRes;
73878   VdbeSorterIter *p1;
73879   VdbeSorterIter *p2;
73880 
73881   assert( iOut<pSorter->nTree && iOut>0 );
73882 
73883   if( iOut>=(pSorter->nTree/2) ){
73884     i1 = (iOut - pSorter->nTree/2) * 2;
73885     i2 = i1 + 1;
73886   }else{
73887     i1 = pSorter->aTree[iOut*2];
73888     i2 = pSorter->aTree[iOut*2+1];
73889   }
73890 
73891   p1 = &pSorter->aIter[i1];
73892   p2 = &pSorter->aIter[i2];
73893 
73894   if( p1->pFile==0 ){
73895     iRes = i2;
73896   }else if( p2->pFile==0 ){
73897     iRes = i1;
73898   }else{
73899     int res;
73900     assert( pCsr->pSorter->pUnpacked!=0 );  /* allocated in vdbeSorterMerge() */
73901     vdbeSorterCompare(
73902         pCsr, 0, p1->aKey, p1->nKey, p2->aKey, p2->nKey, &res
73903     );
73904     if( res<=0 ){
73905       iRes = i1;
73906     }else{
73907       iRes = i2;
73908     }
73909   }
73910 
73911   pSorter->aTree[iOut] = iRes;
73912   return SQLITE_OK;
73913 }
73914 
73915 /*
73916 ** Initialize the temporary index cursor just opened as a sorter cursor.
73917 */
73918 SQLITE_PRIVATE int sqlite3VdbeSorterInit(sqlite3 *db, VdbeCursor *pCsr){
73919   int pgsz;                       /* Page size of main database */
73920   int mxCache;                    /* Cache size */
73921   VdbeSorter *pSorter;            /* The new sorter */
73922   char *d;                        /* Dummy */
73923 
73924   assert( pCsr->pKeyInfo && pCsr->pBt==0 );
73925   pCsr->pSorter = pSorter = sqlite3DbMallocZero(db, sizeof(VdbeSorter));
73926   if( pSorter==0 ){
73927     return SQLITE_NOMEM;
73928   }
73929   
73930   pSorter->pUnpacked = sqlite3VdbeAllocUnpackedRecord(pCsr->pKeyInfo, 0, 0, &d);
73931   if( pSorter->pUnpacked==0 ) return SQLITE_NOMEM;
73932   assert( pSorter->pUnpacked==(UnpackedRecord *)d );
73933 
73934   if( !sqlite3TempInMemory(db) ){
73935     pgsz = sqlite3BtreeGetPageSize(db->aDb[0].pBt);
73936     pSorter->mnPmaSize = SORTER_MIN_WORKING * pgsz;
73937     mxCache = db->aDb[0].pSchema->cache_size;
73938     if( mxCache<SORTER_MIN_WORKING ) mxCache = SORTER_MIN_WORKING;
73939     pSorter->mxPmaSize = mxCache * pgsz;
73940   }
73941 
73942   return SQLITE_OK;
73943 }
73944 
73945 /*
73946 ** Free the list of sorted records starting at pRecord.
73947 */
73948 static void vdbeSorterRecordFree(sqlite3 *db, SorterRecord *pRecord){
73949   SorterRecord *p;
73950   SorterRecord *pNext;
73951   for(p=pRecord; p; p=pNext){
73952     pNext = p->pNext;
73953     sqlite3DbFree(db, p);
73954   }
73955 }
73956 
73957 /*
73958 ** Free any cursor components allocated by sqlite3VdbeSorterXXX routines.
73959 */
73960 SQLITE_PRIVATE void sqlite3VdbeSorterClose(sqlite3 *db, VdbeCursor *pCsr){
73961   VdbeSorter *pSorter = pCsr->pSorter;
73962   if( pSorter ){
73963     if( pSorter->aIter ){
73964       int i;
73965       for(i=0; i<pSorter->nTree; i++){
73966         vdbeSorterIterZero(db, &pSorter->aIter[i]);
73967       }
73968       sqlite3DbFree(db, pSorter->aIter);
73969     }
73970     if( pSorter->pTemp1 ){
73971       sqlite3OsCloseFree(pSorter->pTemp1);
73972     }
73973     vdbeSorterRecordFree(db, pSorter->pRecord);
73974     sqlite3DbFree(db, pSorter->pUnpacked);
73975     sqlite3DbFree(db, pSorter);
73976     pCsr->pSorter = 0;
73977   }
73978 }
73979 
73980 /*
73981 ** Allocate space for a file-handle and open a temporary file. If successful,
73982 ** set *ppFile to point to the malloc'd file-handle and return SQLITE_OK.
73983 ** Otherwise, set *ppFile to 0 and return an SQLite error code.
73984 */
73985 static int vdbeSorterOpenTempFile(sqlite3 *db, sqlite3_file **ppFile){
73986   int dummy;
73987   return sqlite3OsOpenMalloc(db->pVfs, 0, ppFile,
73988       SQLITE_OPEN_TEMP_JOURNAL |
73989       SQLITE_OPEN_READWRITE    | SQLITE_OPEN_CREATE |
73990       SQLITE_OPEN_EXCLUSIVE    | SQLITE_OPEN_DELETEONCLOSE, &dummy
73991   );
73992 }
73993 
73994 /*
73995 ** Merge the two sorted lists p1 and p2 into a single list.
73996 ** Set *ppOut to the head of the new list.
73997 */
73998 static void vdbeSorterMerge(
73999   const VdbeCursor *pCsr,         /* For pKeyInfo */
74000   SorterRecord *p1,               /* First list to merge */
74001   SorterRecord *p2,               /* Second list to merge */
74002   SorterRecord **ppOut            /* OUT: Head of merged list */
74003 ){
74004   SorterRecord *pFinal = 0;
74005   SorterRecord **pp = &pFinal;
74006   void *pVal2 = p2 ? p2->pVal : 0;
74007 
74008   while( p1 && p2 ){
74009     int res;
74010     vdbeSorterCompare(pCsr, 0, p1->pVal, p1->nVal, pVal2, p2->nVal, &res);
74011     if( res<=0 ){
74012       *pp = p1;
74013       pp = &p1->pNext;
74014       p1 = p1->pNext;
74015       pVal2 = 0;
74016     }else{
74017       *pp = p2;
74018        pp = &p2->pNext;
74019       p2 = p2->pNext;
74020       if( p2==0 ) break;
74021       pVal2 = p2->pVal;
74022     }
74023   }
74024   *pp = p1 ? p1 : p2;
74025   *ppOut = pFinal;
74026 }
74027 
74028 /*
74029 ** Sort the linked list of records headed at pCsr->pRecord. Return SQLITE_OK
74030 ** if successful, or an SQLite error code (i.e. SQLITE_NOMEM) if an error
74031 ** occurs.
74032 */
74033 static int vdbeSorterSort(const VdbeCursor *pCsr){
74034   int i;
74035   SorterRecord **aSlot;
74036   SorterRecord *p;
74037   VdbeSorter *pSorter = pCsr->pSorter;
74038 
74039   aSlot = (SorterRecord **)sqlite3MallocZero(64 * sizeof(SorterRecord *));
74040   if( !aSlot ){
74041     return SQLITE_NOMEM;
74042   }
74043 
74044   p = pSorter->pRecord;
74045   while( p ){
74046     SorterRecord *pNext = p->pNext;
74047     p->pNext = 0;
74048     for(i=0; aSlot[i]; i++){
74049       vdbeSorterMerge(pCsr, p, aSlot[i], &p);
74050       aSlot[i] = 0;
74051     }
74052     aSlot[i] = p;
74053     p = pNext;
74054   }
74055 
74056   p = 0;
74057   for(i=0; i<64; i++){
74058     vdbeSorterMerge(pCsr, p, aSlot[i], &p);
74059   }
74060   pSorter->pRecord = p;
74061 
74062   sqlite3_free(aSlot);
74063   return SQLITE_OK;
74064 }
74065 
74066 /*
74067 ** Initialize a file-writer object.
74068 */
74069 static void fileWriterInit(
74070   sqlite3 *db,                    /* Database (for malloc) */
74071   sqlite3_file *pFile,            /* File to write to */
74072   FileWriter *p,                  /* Object to populate */
74073   i64 iStart                      /* Offset of pFile to begin writing at */
74074 ){
74075   int nBuf = sqlite3BtreeGetPageSize(db->aDb[0].pBt);
74076 
74077   memset(p, 0, sizeof(FileWriter));
74078   p->aBuffer = (u8 *)sqlite3DbMallocRaw(db, nBuf);
74079   if( !p->aBuffer ){
74080     p->eFWErr = SQLITE_NOMEM;
74081   }else{
74082     p->iBufEnd = p->iBufStart = (iStart % nBuf);
74083     p->iWriteOff = iStart - p->iBufStart;
74084     p->nBuffer = nBuf;
74085     p->pFile = pFile;
74086   }
74087 }
74088 
74089 /*
74090 ** Write nData bytes of data to the file-write object. Return SQLITE_OK
74091 ** if successful, or an SQLite error code if an error occurs.
74092 */
74093 static void fileWriterWrite(FileWriter *p, u8 *pData, int nData){
74094   int nRem = nData;
74095   while( nRem>0 && p->eFWErr==0 ){
74096     int nCopy = nRem;
74097     if( nCopy>(p->nBuffer - p->iBufEnd) ){
74098       nCopy = p->nBuffer - p->iBufEnd;
74099     }
74100 
74101     memcpy(&p->aBuffer[p->iBufEnd], &pData[nData-nRem], nCopy);
74102     p->iBufEnd += nCopy;
74103     if( p->iBufEnd==p->nBuffer ){
74104       p->eFWErr = sqlite3OsWrite(p->pFile, 
74105           &p->aBuffer[p->iBufStart], p->iBufEnd - p->iBufStart, 
74106           p->iWriteOff + p->iBufStart
74107       );
74108       p->iBufStart = p->iBufEnd = 0;
74109       p->iWriteOff += p->nBuffer;
74110     }
74111     assert( p->iBufEnd<p->nBuffer );
74112 
74113     nRem -= nCopy;
74114   }
74115 }
74116 
74117 /*
74118 ** Flush any buffered data to disk and clean up the file-writer object.
74119 ** The results of using the file-writer after this call are undefined.
74120 ** Return SQLITE_OK if flushing the buffered data succeeds or is not 
74121 ** required. Otherwise, return an SQLite error code.
74122 **
74123 ** Before returning, set *piEof to the offset immediately following the
74124 ** last byte written to the file.
74125 */
74126 static int fileWriterFinish(sqlite3 *db, FileWriter *p, i64 *piEof){
74127   int rc;
74128   if( p->eFWErr==0 && ALWAYS(p->aBuffer) && p->iBufEnd>p->iBufStart ){
74129     p->eFWErr = sqlite3OsWrite(p->pFile, 
74130         &p->aBuffer[p->iBufStart], p->iBufEnd - p->iBufStart, 
74131         p->iWriteOff + p->iBufStart
74132     );
74133   }
74134   *piEof = (p->iWriteOff + p->iBufEnd);
74135   sqlite3DbFree(db, p->aBuffer);
74136   rc = p->eFWErr;
74137   memset(p, 0, sizeof(FileWriter));
74138   return rc;
74139 }
74140 
74141 /*
74142 ** Write value iVal encoded as a varint to the file-write object. Return 
74143 ** SQLITE_OK if successful, or an SQLite error code if an error occurs.
74144 */
74145 static void fileWriterWriteVarint(FileWriter *p, u64 iVal){
74146   int nByte; 
74147   u8 aByte[10];
74148   nByte = sqlite3PutVarint(aByte, iVal);
74149   fileWriterWrite(p, aByte, nByte);
74150 }
74151 
74152 /*
74153 ** Write the current contents of the in-memory linked-list to a PMA. Return
74154 ** SQLITE_OK if successful, or an SQLite error code otherwise.
74155 **
74156 ** The format of a PMA is:
74157 **
74158 **     * A varint. This varint contains the total number of bytes of content
74159 **       in the PMA (not including the varint itself).
74160 **
74161 **     * One or more records packed end-to-end in order of ascending keys. 
74162 **       Each record consists of a varint followed by a blob of data (the 
74163 **       key). The varint is the number of bytes in the blob of data.
74164 */
74165 static int vdbeSorterListToPMA(sqlite3 *db, const VdbeCursor *pCsr){
74166   int rc = SQLITE_OK;             /* Return code */
74167   VdbeSorter *pSorter = pCsr->pSorter;
74168   FileWriter writer;
74169 
74170   memset(&writer, 0, sizeof(FileWriter));
74171 
74172   if( pSorter->nInMemory==0 ){
74173     assert( pSorter->pRecord==0 );
74174     return rc;
74175   }
74176 
74177   rc = vdbeSorterSort(pCsr);
74178 
74179   /* If the first temporary PMA file has not been opened, open it now. */
74180   if( rc==SQLITE_OK && pSorter->pTemp1==0 ){
74181     rc = vdbeSorterOpenTempFile(db, &pSorter->pTemp1);
74182     assert( rc!=SQLITE_OK || pSorter->pTemp1 );
74183     assert( pSorter->iWriteOff==0 );
74184     assert( pSorter->nPMA==0 );
74185   }
74186 
74187   if( rc==SQLITE_OK ){
74188     SorterRecord *p;
74189     SorterRecord *pNext = 0;
74190 
74191     fileWriterInit(db, pSorter->pTemp1, &writer, pSorter->iWriteOff);
74192     pSorter->nPMA++;
74193     fileWriterWriteVarint(&writer, pSorter->nInMemory);
74194     for(p=pSorter->pRecord; p; p=pNext){
74195       pNext = p->pNext;
74196       fileWriterWriteVarint(&writer, p->nVal);
74197       fileWriterWrite(&writer, p->pVal, p->nVal);
74198       sqlite3DbFree(db, p);
74199     }
74200     pSorter->pRecord = p;
74201     rc = fileWriterFinish(db, &writer, &pSorter->iWriteOff);
74202   }
74203 
74204   return rc;
74205 }
74206 
74207 /*
74208 ** Add a record to the sorter.
74209 */
74210 SQLITE_PRIVATE int sqlite3VdbeSorterWrite(
74211   sqlite3 *db,                    /* Database handle */
74212   const VdbeCursor *pCsr,               /* Sorter cursor */
74213   Mem *pVal                       /* Memory cell containing record */
74214 ){
74215   VdbeSorter *pSorter = pCsr->pSorter;
74216   int rc = SQLITE_OK;             /* Return Code */
74217   SorterRecord *pNew;             /* New list element */
74218 
74219   assert( pSorter );
74220   pSorter->nInMemory += sqlite3VarintLen(pVal->n) + pVal->n;
74221 
74222   pNew = (SorterRecord *)sqlite3DbMallocRaw(db, pVal->n + sizeof(SorterRecord));
74223   if( pNew==0 ){
74224     rc = SQLITE_NOMEM;
74225   }else{
74226     pNew->pVal = (void *)&pNew[1];
74227     memcpy(pNew->pVal, pVal->z, pVal->n);
74228     pNew->nVal = pVal->n;
74229     pNew->pNext = pSorter->pRecord;
74230     pSorter->pRecord = pNew;
74231   }
74232 
74233   /* See if the contents of the sorter should now be written out. They
74234   ** are written out when either of the following are true:
74235   **
74236   **   * The total memory allocated for the in-memory list is greater 
74237   **     than (page-size * cache-size), or
74238   **
74239   **   * The total memory allocated for the in-memory list is greater 
74240   **     than (page-size * 10) and sqlite3HeapNearlyFull() returns true.
74241   */
74242   if( rc==SQLITE_OK && pSorter->mxPmaSize>0 && (
74243         (pSorter->nInMemory>pSorter->mxPmaSize)
74244      || (pSorter->nInMemory>pSorter->mnPmaSize && sqlite3HeapNearlyFull())
74245   )){
74246 #ifdef SQLITE_DEBUG
74247     i64 nExpect = pSorter->iWriteOff
74248                 + sqlite3VarintLen(pSorter->nInMemory)
74249                 + pSorter->nInMemory;
74250 #endif
74251     rc = vdbeSorterListToPMA(db, pCsr);
74252     pSorter->nInMemory = 0;
74253     assert( rc!=SQLITE_OK || (nExpect==pSorter->iWriteOff) );
74254   }
74255 
74256   return rc;
74257 }
74258 
74259 /*
74260 ** Helper function for sqlite3VdbeSorterRewind(). 
74261 */
74262 static int vdbeSorterInitMerge(
74263   sqlite3 *db,                    /* Database handle */
74264   const VdbeCursor *pCsr,         /* Cursor handle for this sorter */
74265   i64 *pnByte                     /* Sum of bytes in all opened PMAs */
74266 ){
74267   VdbeSorter *pSorter = pCsr->pSorter;
74268   int rc = SQLITE_OK;             /* Return code */
74269   int i;                          /* Used to iterator through aIter[] */
74270   i64 nByte = 0;                  /* Total bytes in all opened PMAs */
74271 
74272   /* Initialize the iterators. */
74273   for(i=0; i<SORTER_MAX_MERGE_COUNT; i++){
74274     VdbeSorterIter *pIter = &pSorter->aIter[i];
74275     rc = vdbeSorterIterInit(db, pSorter, pSorter->iReadOff, pIter, &nByte);
74276     pSorter->iReadOff = pIter->iEof;
74277     assert( rc!=SQLITE_OK || pSorter->iReadOff<=pSorter->iWriteOff );
74278     if( rc!=SQLITE_OK || pSorter->iReadOff>=pSorter->iWriteOff ) break;
74279   }
74280 
74281   /* Initialize the aTree[] array. */
74282   for(i=pSorter->nTree-1; rc==SQLITE_OK && i>0; i--){
74283     rc = vdbeSorterDoCompare(pCsr, i);
74284   }
74285 
74286   *pnByte = nByte;
74287   return rc;
74288 }
74289 
74290 /*
74291 ** Once the sorter has been populated, this function is called to prepare
74292 ** for iterating through its contents in sorted order.
74293 */
74294 SQLITE_PRIVATE int sqlite3VdbeSorterRewind(sqlite3 *db, const VdbeCursor *pCsr, int *pbEof){
74295   VdbeSorter *pSorter = pCsr->pSorter;
74296   int rc;                         /* Return code */
74297   sqlite3_file *pTemp2 = 0;       /* Second temp file to use */
74298   i64 iWrite2 = 0;                /* Write offset for pTemp2 */
74299   int nIter;                      /* Number of iterators used */
74300   int nByte;                      /* Bytes of space required for aIter/aTree */
74301   int N = 2;                      /* Power of 2 >= nIter */
74302 
74303   assert( pSorter );
74304 
74305   /* If no data has been written to disk, then do not do so now. Instead,
74306   ** sort the VdbeSorter.pRecord list. The vdbe layer will read data directly
74307   ** from the in-memory list.  */
74308   if( pSorter->nPMA==0 ){
74309     *pbEof = !pSorter->pRecord;
74310     assert( pSorter->aTree==0 );
74311     return vdbeSorterSort(pCsr);
74312   }
74313 
74314   /* Write the current in-memory list to a PMA. */
74315   rc = vdbeSorterListToPMA(db, pCsr);
74316   if( rc!=SQLITE_OK ) return rc;
74317 
74318   /* Allocate space for aIter[] and aTree[]. */
74319   nIter = pSorter->nPMA;
74320   if( nIter>SORTER_MAX_MERGE_COUNT ) nIter = SORTER_MAX_MERGE_COUNT;
74321   assert( nIter>0 );
74322   while( N<nIter ) N += N;
74323   nByte = N * (sizeof(int) + sizeof(VdbeSorterIter));
74324   pSorter->aIter = (VdbeSorterIter *)sqlite3DbMallocZero(db, nByte);
74325   if( !pSorter->aIter ) return SQLITE_NOMEM;
74326   pSorter->aTree = (int *)&pSorter->aIter[N];
74327   pSorter->nTree = N;
74328 
74329   do {
74330     int iNew;                     /* Index of new, merged, PMA */
74331 
74332     for(iNew=0; 
74333         rc==SQLITE_OK && iNew*SORTER_MAX_MERGE_COUNT<pSorter->nPMA; 
74334         iNew++
74335     ){
74336       int rc2;                    /* Return code from fileWriterFinish() */
74337       FileWriter writer;          /* Object used to write to disk */
74338       i64 nWrite;                 /* Number of bytes in new PMA */
74339 
74340       memset(&writer, 0, sizeof(FileWriter));
74341 
74342       /* If there are SORTER_MAX_MERGE_COUNT or less PMAs in file pTemp1,
74343       ** initialize an iterator for each of them and break out of the loop.
74344       ** These iterators will be incrementally merged as the VDBE layer calls
74345       ** sqlite3VdbeSorterNext().
74346       **
74347       ** Otherwise, if pTemp1 contains more than SORTER_MAX_MERGE_COUNT PMAs,
74348       ** initialize interators for SORTER_MAX_MERGE_COUNT of them. These PMAs
74349       ** are merged into a single PMA that is written to file pTemp2.
74350       */
74351       rc = vdbeSorterInitMerge(db, pCsr, &nWrite);
74352       assert( rc!=SQLITE_OK || pSorter->aIter[ pSorter->aTree[1] ].pFile );
74353       if( rc!=SQLITE_OK || pSorter->nPMA<=SORTER_MAX_MERGE_COUNT ){
74354         break;
74355       }
74356 
74357       /* Open the second temp file, if it is not already open. */
74358       if( pTemp2==0 ){
74359         assert( iWrite2==0 );
74360         rc = vdbeSorterOpenTempFile(db, &pTemp2);
74361       }
74362 
74363       if( rc==SQLITE_OK ){
74364         int bEof = 0;
74365         fileWriterInit(db, pTemp2, &writer, iWrite2);
74366         fileWriterWriteVarint(&writer, nWrite);
74367         while( rc==SQLITE_OK && bEof==0 ){
74368           VdbeSorterIter *pIter = &pSorter->aIter[ pSorter->aTree[1] ];
74369           assert( pIter->pFile );
74370 
74371           fileWriterWriteVarint(&writer, pIter->nKey);
74372           fileWriterWrite(&writer, pIter->aKey, pIter->nKey);
74373           rc = sqlite3VdbeSorterNext(db, pCsr, &bEof);
74374         }
74375         rc2 = fileWriterFinish(db, &writer, &iWrite2);
74376         if( rc==SQLITE_OK ) rc = rc2;
74377       }
74378     }
74379 
74380     if( pSorter->nPMA<=SORTER_MAX_MERGE_COUNT ){
74381       break;
74382     }else{
74383       sqlite3_file *pTmp = pSorter->pTemp1;
74384       pSorter->nPMA = iNew;
74385       pSorter->pTemp1 = pTemp2;
74386       pTemp2 = pTmp;
74387       pSorter->iWriteOff = iWrite2;
74388       pSorter->iReadOff = 0;
74389       iWrite2 = 0;
74390     }
74391   }while( rc==SQLITE_OK );
74392 
74393   if( pTemp2 ){
74394     sqlite3OsCloseFree(pTemp2);
74395   }
74396   *pbEof = (pSorter->aIter[pSorter->aTree[1]].pFile==0);
74397   return rc;
74398 }
74399 
74400 /*
74401 ** Advance to the next element in the sorter.
74402 */
74403 SQLITE_PRIVATE int sqlite3VdbeSorterNext(sqlite3 *db, const VdbeCursor *pCsr, int *pbEof){
74404   VdbeSorter *pSorter = pCsr->pSorter;
74405   int rc;                         /* Return code */
74406 
74407   if( pSorter->aTree ){
74408     int iPrev = pSorter->aTree[1];/* Index of iterator to advance */
74409     int i;                        /* Index of aTree[] to recalculate */
74410 
74411     rc = vdbeSorterIterNext(db, &pSorter->aIter[iPrev]);
74412     for(i=(pSorter->nTree+iPrev)/2; rc==SQLITE_OK && i>0; i=i/2){
74413       rc = vdbeSorterDoCompare(pCsr, i);
74414     }
74415 
74416     *pbEof = (pSorter->aIter[pSorter->aTree[1]].pFile==0);
74417   }else{
74418     SorterRecord *pFree = pSorter->pRecord;
74419     pSorter->pRecord = pFree->pNext;
74420     pFree->pNext = 0;
74421     vdbeSorterRecordFree(db, pFree);
74422     *pbEof = !pSorter->pRecord;
74423     rc = SQLITE_OK;
74424   }
74425   return rc;
74426 }
74427 
74428 /*
74429 ** Return a pointer to a buffer owned by the sorter that contains the 
74430 ** current key.
74431 */
74432 static void *vdbeSorterRowkey(
74433   const VdbeSorter *pSorter,      /* Sorter object */
74434   int *pnKey                      /* OUT: Size of current key in bytes */
74435 ){
74436   void *pKey;
74437   if( pSorter->aTree ){
74438     VdbeSorterIter *pIter;
74439     pIter = &pSorter->aIter[ pSorter->aTree[1] ];
74440     *pnKey = pIter->nKey;
74441     pKey = pIter->aKey;
74442   }else{
74443     *pnKey = pSorter->pRecord->nVal;
74444     pKey = pSorter->pRecord->pVal;
74445   }
74446   return pKey;
74447 }
74448 
74449 /*
74450 ** Copy the current sorter key into the memory cell pOut.
74451 */
74452 SQLITE_PRIVATE int sqlite3VdbeSorterRowkey(const VdbeCursor *pCsr, Mem *pOut){
74453   VdbeSorter *pSorter = pCsr->pSorter;
74454   void *pKey; int nKey;           /* Sorter key to copy into pOut */
74455 
74456   pKey = vdbeSorterRowkey(pSorter, &nKey);
74457   if( sqlite3VdbeMemGrow(pOut, nKey, 0) ){
74458     return SQLITE_NOMEM;
74459   }
74460   pOut->n = nKey;
74461   MemSetTypeFlag(pOut, MEM_Blob);
74462   memcpy(pOut->z, pKey, nKey);
74463 
74464   return SQLITE_OK;
74465 }
74466 
74467 /*
74468 ** Compare the key in memory cell pVal with the key that the sorter cursor
74469 ** passed as the first argument currently points to. For the purposes of
74470 ** the comparison, ignore the rowid field at the end of each record.
74471 **
74472 ** If an error occurs, return an SQLite error code (i.e. SQLITE_NOMEM).
74473 ** Otherwise, set *pRes to a negative, zero or positive value if the
74474 ** key in pVal is smaller than, equal to or larger than the current sorter
74475 ** key.
74476 */
74477 SQLITE_PRIVATE int sqlite3VdbeSorterCompare(
74478   const VdbeCursor *pCsr,         /* Sorter cursor */
74479   Mem *pVal,                      /* Value to compare to current sorter key */
74480   int nIgnore,                    /* Ignore this many fields at the end */
74481   int *pRes                       /* OUT: Result of comparison */
74482 ){
74483   VdbeSorter *pSorter = pCsr->pSorter;
74484   void *pKey; int nKey;           /* Sorter key to compare pVal with */
74485 
74486   pKey = vdbeSorterRowkey(pSorter, &nKey);
74487   vdbeSorterCompare(pCsr, nIgnore, pVal->z, pVal->n, pKey, nKey, pRes);
74488   return SQLITE_OK;
74489 }
74490 
74491 /************** End of vdbesort.c ********************************************/
74492 /************** Begin file journal.c *****************************************/
74493 /*
74494 ** 2007 August 22
74495 **
74496 ** The author disclaims copyright to this source code.  In place of
74497 ** a legal notice, here is a blessing:
74498 **
74499 **    May you do good and not evil.
74500 **    May you find forgiveness for yourself and forgive others.
74501 **    May you share freely, never taking more than you give.
74502 **
74503 *************************************************************************
74504 **
74505 ** This file implements a special kind of sqlite3_file object used
74506 ** by SQLite to create journal files if the atomic-write optimization
74507 ** is enabled.
74508 **
74509 ** The distinctive characteristic of this sqlite3_file is that the
74510 ** actual on disk file is created lazily. When the file is created,
74511 ** the caller specifies a buffer size for an in-memory buffer to
74512 ** be used to service read() and write() requests. The actual file
74513 ** on disk is not created or populated until either:
74514 **
74515 **   1) The in-memory representation grows too large for the allocated 
74516 **      buffer, or
74517 **   2) The sqlite3JournalCreate() function is called.
74518 */
74519 #ifdef SQLITE_ENABLE_ATOMIC_WRITE
74520 
74521 
74522 /*
74523 ** A JournalFile object is a subclass of sqlite3_file used by
74524 ** as an open file handle for journal files.
74525 */
74526 struct JournalFile {
74527   sqlite3_io_methods *pMethod;    /* I/O methods on journal files */
74528   int nBuf;                       /* Size of zBuf[] in bytes */
74529   char *zBuf;                     /* Space to buffer journal writes */
74530   int iSize;                      /* Amount of zBuf[] currently used */
74531   int flags;                      /* xOpen flags */
74532   sqlite3_vfs *pVfs;              /* The "real" underlying VFS */
74533   sqlite3_file *pReal;            /* The "real" underlying file descriptor */
74534   const char *zJournal;           /* Name of the journal file */
74535 };
74536 typedef struct JournalFile JournalFile;
74537 
74538 /*
74539 ** If it does not already exists, create and populate the on-disk file 
74540 ** for JournalFile p.
74541 */
74542 static int createFile(JournalFile *p){
74543   int rc = SQLITE_OK;
74544   if( !p->pReal ){
74545     sqlite3_file *pReal = (sqlite3_file *)&p[1];
74546     rc = sqlite3OsOpen(p->pVfs, p->zJournal, pReal, p->flags, 0);
74547     if( rc==SQLITE_OK ){
74548       p->pReal = pReal;
74549       if( p->iSize>0 ){
74550         assert(p->iSize<=p->nBuf);
74551         rc = sqlite3OsWrite(p->pReal, p->zBuf, p->iSize, 0);
74552       }
74553       if( rc!=SQLITE_OK ){
74554         /* If an error occurred while writing to the file, close it before
74555         ** returning. This way, SQLite uses the in-memory journal data to 
74556         ** roll back changes made to the internal page-cache before this
74557         ** function was called.  */
74558         sqlite3OsClose(pReal);
74559         p->pReal = 0;
74560       }
74561     }
74562   }
74563   return rc;
74564 }
74565 
74566 /*
74567 ** Close the file.
74568 */
74569 static int jrnlClose(sqlite3_file *pJfd){
74570   JournalFile *p = (JournalFile *)pJfd;
74571   if( p->pReal ){
74572     sqlite3OsClose(p->pReal);
74573   }
74574   sqlite3_free(p->zBuf);
74575   return SQLITE_OK;
74576 }
74577 
74578 /*
74579 ** Read data from the file.
74580 */
74581 static int jrnlRead(
74582   sqlite3_file *pJfd,    /* The journal file from which to read */
74583   void *zBuf,            /* Put the results here */
74584   int iAmt,              /* Number of bytes to read */
74585   sqlite_int64 iOfst     /* Begin reading at this offset */
74586 ){
74587   int rc = SQLITE_OK;
74588   JournalFile *p = (JournalFile *)pJfd;
74589   if( p->pReal ){
74590     rc = sqlite3OsRead(p->pReal, zBuf, iAmt, iOfst);
74591   }else if( (iAmt+iOfst)>p->iSize ){
74592     rc = SQLITE_IOERR_SHORT_READ;
74593   }else{
74594     memcpy(zBuf, &p->zBuf[iOfst], iAmt);
74595   }
74596   return rc;
74597 }
74598 
74599 /*
74600 ** Write data to the file.
74601 */
74602 static int jrnlWrite(
74603   sqlite3_file *pJfd,    /* The journal file into which to write */
74604   const void *zBuf,      /* Take data to be written from here */
74605   int iAmt,              /* Number of bytes to write */
74606   sqlite_int64 iOfst     /* Begin writing at this offset into the file */
74607 ){
74608   int rc = SQLITE_OK;
74609   JournalFile *p = (JournalFile *)pJfd;
74610   if( !p->pReal && (iOfst+iAmt)>p->nBuf ){
74611     rc = createFile(p);
74612   }
74613   if( rc==SQLITE_OK ){
74614     if( p->pReal ){
74615       rc = sqlite3OsWrite(p->pReal, zBuf, iAmt, iOfst);
74616     }else{
74617       memcpy(&p->zBuf[iOfst], zBuf, iAmt);
74618       if( p->iSize<(iOfst+iAmt) ){
74619         p->iSize = (iOfst+iAmt);
74620       }
74621     }
74622   }
74623   return rc;
74624 }
74625 
74626 /*
74627 ** Truncate the file.
74628 */
74629 static int jrnlTruncate(sqlite3_file *pJfd, sqlite_int64 size){
74630   int rc = SQLITE_OK;
74631   JournalFile *p = (JournalFile *)pJfd;
74632   if( p->pReal ){
74633     rc = sqlite3OsTruncate(p->pReal, size);
74634   }else if( size<p->iSize ){
74635     p->iSize = size;
74636   }
74637   return rc;
74638 }
74639 
74640 /*
74641 ** Sync the file.
74642 */
74643 static int jrnlSync(sqlite3_file *pJfd, int flags){
74644   int rc;
74645   JournalFile *p = (JournalFile *)pJfd;
74646   if( p->pReal ){
74647     rc = sqlite3OsSync(p->pReal, flags);
74648   }else{
74649     rc = SQLITE_OK;
74650   }
74651   return rc;
74652 }
74653 
74654 /*
74655 ** Query the size of the file in bytes.
74656 */
74657 static int jrnlFileSize(sqlite3_file *pJfd, sqlite_int64 *pSize){
74658   int rc = SQLITE_OK;
74659   JournalFile *p = (JournalFile *)pJfd;
74660   if( p->pReal ){
74661     rc = sqlite3OsFileSize(p->pReal, pSize);
74662   }else{
74663     *pSize = (sqlite_int64) p->iSize;
74664   }
74665   return rc;
74666 }
74667 
74668 /*
74669 ** Table of methods for JournalFile sqlite3_file object.
74670 */
74671 static struct sqlite3_io_methods JournalFileMethods = {
74672   1,             /* iVersion */
74673   jrnlClose,     /* xClose */
74674   jrnlRead,      /* xRead */
74675   jrnlWrite,     /* xWrite */
74676   jrnlTruncate,  /* xTruncate */
74677   jrnlSync,      /* xSync */
74678   jrnlFileSize,  /* xFileSize */
74679   0,             /* xLock */
74680   0,             /* xUnlock */
74681   0,             /* xCheckReservedLock */
74682   0,             /* xFileControl */
74683   0,             /* xSectorSize */
74684   0,             /* xDeviceCharacteristics */
74685   0,             /* xShmMap */
74686   0,             /* xShmLock */
74687   0,             /* xShmBarrier */
74688   0              /* xShmUnmap */
74689 };
74690 
74691 /* 
74692 ** Open a journal file.
74693 */
74694 SQLITE_PRIVATE int sqlite3JournalOpen(
74695   sqlite3_vfs *pVfs,         /* The VFS to use for actual file I/O */
74696   const char *zName,         /* Name of the journal file */
74697   sqlite3_file *pJfd,        /* Preallocated, blank file handle */
74698   int flags,                 /* Opening flags */
74699   int nBuf                   /* Bytes buffered before opening the file */
74700 ){
74701   JournalFile *p = (JournalFile *)pJfd;
74702   memset(p, 0, sqlite3JournalSize(pVfs));
74703   if( nBuf>0 ){
74704     p->zBuf = sqlite3MallocZero(nBuf);
74705     if( !p->zBuf ){
74706       return SQLITE_NOMEM;
74707     }
74708   }else{
74709     return sqlite3OsOpen(pVfs, zName, pJfd, flags, 0);
74710   }
74711   p->pMethod = &JournalFileMethods;
74712   p->nBuf = nBuf;
74713   p->flags = flags;
74714   p->zJournal = zName;
74715   p->pVfs = pVfs;
74716   return SQLITE_OK;
74717 }
74718 
74719 /*
74720 ** If the argument p points to a JournalFile structure, and the underlying
74721 ** file has not yet been created, create it now.
74722 */
74723 SQLITE_PRIVATE int sqlite3JournalCreate(sqlite3_file *p){
74724   if( p->pMethods!=&JournalFileMethods ){
74725     return SQLITE_OK;
74726   }
74727   return createFile((JournalFile *)p);
74728 }
74729 
74730 /*
74731 ** The file-handle passed as the only argument is guaranteed to be an open
74732 ** file. It may or may not be of class JournalFile. If the file is a
74733 ** JournalFile, and the underlying file on disk has not yet been opened,
74734 ** return 0. Otherwise, return 1.
74735 */
74736 SQLITE_PRIVATE int sqlite3JournalExists(sqlite3_file *p){
74737   return (p->pMethods!=&JournalFileMethods || ((JournalFile *)p)->pReal!=0);
74738 }
74739 
74740 /* 
74741 ** Return the number of bytes required to store a JournalFile that uses vfs
74742 ** pVfs to create the underlying on-disk files.
74743 */
74744 SQLITE_PRIVATE int sqlite3JournalSize(sqlite3_vfs *pVfs){
74745   return (pVfs->szOsFile+sizeof(JournalFile));
74746 }
74747 #endif
74748 
74749 /************** End of journal.c *********************************************/
74750 /************** Begin file memjournal.c **************************************/
74751 /*
74752 ** 2008 October 7
74753 **
74754 ** The author disclaims copyright to this source code.  In place of
74755 ** a legal notice, here is a blessing:
74756 **
74757 **    May you do good and not evil.
74758 **    May you find forgiveness for yourself and forgive others.
74759 **    May you share freely, never taking more than you give.
74760 **
74761 *************************************************************************
74762 **
74763 ** This file contains code use to implement an in-memory rollback journal.
74764 ** The in-memory rollback journal is used to journal transactions for
74765 ** ":memory:" databases and when the journal_mode=MEMORY pragma is used.
74766 */
74767 
74768 /* Forward references to internal structures */
74769 typedef struct MemJournal MemJournal;
74770 typedef struct FilePoint FilePoint;
74771 typedef struct FileChunk FileChunk;
74772 
74773 /* Space to hold the rollback journal is allocated in increments of
74774 ** this many bytes.
74775 **
74776 ** The size chosen is a little less than a power of two.  That way,
74777 ** the FileChunk object will have a size that almost exactly fills
74778 ** a power-of-two allocation.  This mimimizes wasted space in power-of-two
74779 ** memory allocators.
74780 */
74781 #define JOURNAL_CHUNKSIZE ((int)(1024-sizeof(FileChunk*)))
74782 
74783 /*
74784 ** The rollback journal is composed of a linked list of these structures.
74785 */
74786 struct FileChunk {
74787   FileChunk *pNext;               /* Next chunk in the journal */
74788   u8 zChunk[JOURNAL_CHUNKSIZE];   /* Content of this chunk */
74789 };
74790 
74791 /*
74792 ** An instance of this object serves as a cursor into the rollback journal.
74793 ** The cursor can be either for reading or writing.
74794 */
74795 struct FilePoint {
74796   sqlite3_int64 iOffset;          /* Offset from the beginning of the file */
74797   FileChunk *pChunk;              /* Specific chunk into which cursor points */
74798 };
74799 
74800 /*
74801 ** This subclass is a subclass of sqlite3_file.  Each open memory-journal
74802 ** is an instance of this class.
74803 */
74804 struct MemJournal {
74805   sqlite3_io_methods *pMethod;    /* Parent class. MUST BE FIRST */
74806   FileChunk *pFirst;              /* Head of in-memory chunk-list */
74807   FilePoint endpoint;             /* Pointer to the end of the file */
74808   FilePoint readpoint;            /* Pointer to the end of the last xRead() */
74809 };
74810 
74811 /*
74812 ** Read data from the in-memory journal file.  This is the implementation
74813 ** of the sqlite3_vfs.xRead method.
74814 */
74815 static int memjrnlRead(
74816   sqlite3_file *pJfd,    /* The journal file from which to read */
74817   void *zBuf,            /* Put the results here */
74818   int iAmt,              /* Number of bytes to read */
74819   sqlite_int64 iOfst     /* Begin reading at this offset */
74820 ){
74821   MemJournal *p = (MemJournal *)pJfd;
74822   u8 *zOut = zBuf;
74823   int nRead = iAmt;
74824   int iChunkOffset;
74825   FileChunk *pChunk;
74826 
74827   /* SQLite never tries to read past the end of a rollback journal file */
74828   assert( iOfst+iAmt<=p->endpoint.iOffset );
74829 
74830   if( p->readpoint.iOffset!=iOfst || iOfst==0 ){
74831     sqlite3_int64 iOff = 0;
74832     for(pChunk=p->pFirst; 
74833         ALWAYS(pChunk) && (iOff+JOURNAL_CHUNKSIZE)<=iOfst;
74834         pChunk=pChunk->pNext
74835     ){
74836       iOff += JOURNAL_CHUNKSIZE;
74837     }
74838   }else{
74839     pChunk = p->readpoint.pChunk;
74840   }
74841 
74842   iChunkOffset = (int)(iOfst%JOURNAL_CHUNKSIZE);
74843   do {
74844     int iSpace = JOURNAL_CHUNKSIZE - iChunkOffset;
74845     int nCopy = MIN(nRead, (JOURNAL_CHUNKSIZE - iChunkOffset));
74846     memcpy(zOut, &pChunk->zChunk[iChunkOffset], nCopy);
74847     zOut += nCopy;
74848     nRead -= iSpace;
74849     iChunkOffset = 0;
74850   } while( nRead>=0 && (pChunk=pChunk->pNext)!=0 && nRead>0 );
74851   p->readpoint.iOffset = iOfst+iAmt;
74852   p->readpoint.pChunk = pChunk;
74853 
74854   return SQLITE_OK;
74855 }
74856 
74857 /*
74858 ** Write data to the file.
74859 */
74860 static int memjrnlWrite(
74861   sqlite3_file *pJfd,    /* The journal file into which to write */
74862   const void *zBuf,      /* Take data to be written from here */
74863   int iAmt,              /* Number of bytes to write */
74864   sqlite_int64 iOfst     /* Begin writing at this offset into the file */
74865 ){
74866   MemJournal *p = (MemJournal *)pJfd;
74867   int nWrite = iAmt;
74868   u8 *zWrite = (u8 *)zBuf;
74869 
74870   /* An in-memory journal file should only ever be appended to. Random
74871   ** access writes are not required by sqlite.
74872   */
74873   assert( iOfst==p->endpoint.iOffset );
74874   UNUSED_PARAMETER(iOfst);
74875 
74876   while( nWrite>0 ){
74877     FileChunk *pChunk = p->endpoint.pChunk;
74878     int iChunkOffset = (int)(p->endpoint.iOffset%JOURNAL_CHUNKSIZE);
74879     int iSpace = MIN(nWrite, JOURNAL_CHUNKSIZE - iChunkOffset);
74880 
74881     if( iChunkOffset==0 ){
74882       /* New chunk is required to extend the file. */
74883       FileChunk *pNew = sqlite3_malloc(sizeof(FileChunk));
74884       if( !pNew ){
74885         return SQLITE_IOERR_NOMEM;
74886       }
74887       pNew->pNext = 0;
74888       if( pChunk ){
74889         assert( p->pFirst );
74890         pChunk->pNext = pNew;
74891       }else{
74892         assert( !p->pFirst );
74893         p->pFirst = pNew;
74894       }
74895       p->endpoint.pChunk = pNew;
74896     }
74897 
74898     memcpy(&p->endpoint.pChunk->zChunk[iChunkOffset], zWrite, iSpace);
74899     zWrite += iSpace;
74900     nWrite -= iSpace;
74901     p->endpoint.iOffset += iSpace;
74902   }
74903 
74904   return SQLITE_OK;
74905 }
74906 
74907 /*
74908 ** Truncate the file.
74909 */
74910 static int memjrnlTruncate(sqlite3_file *pJfd, sqlite_int64 size){
74911   MemJournal *p = (MemJournal *)pJfd;
74912   FileChunk *pChunk;
74913   assert(size==0);
74914   UNUSED_PARAMETER(size);
74915   pChunk = p->pFirst;
74916   while( pChunk ){
74917     FileChunk *pTmp = pChunk;
74918     pChunk = pChunk->pNext;
74919     sqlite3_free(pTmp);
74920   }
74921   sqlite3MemJournalOpen(pJfd);
74922   return SQLITE_OK;
74923 }
74924 
74925 /*
74926 ** Close the file.
74927 */
74928 static int memjrnlClose(sqlite3_file *pJfd){
74929   memjrnlTruncate(pJfd, 0);
74930   return SQLITE_OK;
74931 }
74932 
74933 
74934 /*
74935 ** Sync the file.
74936 **
74937 ** Syncing an in-memory journal is a no-op.  And, in fact, this routine
74938 ** is never called in a working implementation.  This implementation
74939 ** exists purely as a contingency, in case some malfunction in some other
74940 ** part of SQLite causes Sync to be called by mistake.
74941 */
74942 static int memjrnlSync(sqlite3_file *NotUsed, int NotUsed2){
74943   UNUSED_PARAMETER2(NotUsed, NotUsed2);
74944   return SQLITE_OK;
74945 }
74946 
74947 /*
74948 ** Query the size of the file in bytes.
74949 */
74950 static int memjrnlFileSize(sqlite3_file *pJfd, sqlite_int64 *pSize){
74951   MemJournal *p = (MemJournal *)pJfd;
74952   *pSize = (sqlite_int64) p->endpoint.iOffset;
74953   return SQLITE_OK;
74954 }
74955 
74956 /*
74957 ** Table of methods for MemJournal sqlite3_file object.
74958 */
74959 static const struct sqlite3_io_methods MemJournalMethods = {
74960   1,                /* iVersion */
74961   memjrnlClose,     /* xClose */
74962   memjrnlRead,      /* xRead */
74963   memjrnlWrite,     /* xWrite */
74964   memjrnlTruncate,  /* xTruncate */
74965   memjrnlSync,      /* xSync */
74966   memjrnlFileSize,  /* xFileSize */
74967   0,                /* xLock */
74968   0,                /* xUnlock */
74969   0,                /* xCheckReservedLock */
74970   0,                /* xFileControl */
74971   0,                /* xSectorSize */
74972   0,                /* xDeviceCharacteristics */
74973   0,                /* xShmMap */
74974   0,                /* xShmLock */
74975   0,                /* xShmBarrier */
74976   0,                /* xShmUnmap */
74977   0,                /* xFetch */
74978   0                 /* xUnfetch */
74979 };
74980 
74981 /* 
74982 ** Open a journal file.
74983 */
74984 SQLITE_PRIVATE void sqlite3MemJournalOpen(sqlite3_file *pJfd){
74985   MemJournal *p = (MemJournal *)pJfd;
74986   assert( EIGHT_BYTE_ALIGNMENT(p) );
74987   memset(p, 0, sqlite3MemJournalSize());
74988   p->pMethod = (sqlite3_io_methods*)&MemJournalMethods;
74989 }
74990 
74991 /*
74992 ** Return true if the file-handle passed as an argument is 
74993 ** an in-memory journal 
74994 */
74995 SQLITE_PRIVATE int sqlite3IsMemJournal(sqlite3_file *pJfd){
74996   return pJfd->pMethods==&MemJournalMethods;
74997 }
74998 
74999 /* 
75000 ** Return the number of bytes required to store a MemJournal file descriptor.
75001 */
75002 SQLITE_PRIVATE int sqlite3MemJournalSize(void){
75003   return sizeof(MemJournal);
75004 }
75005 
75006 /************** End of memjournal.c ******************************************/
75007 /************** Begin file walker.c ******************************************/
75008 /*
75009 ** 2008 August 16
75010 **
75011 ** The author disclaims copyright to this source code.  In place of
75012 ** a legal notice, here is a blessing:
75013 **
75014 **    May you do good and not evil.
75015 **    May you find forgiveness for yourself and forgive others.
75016 **    May you share freely, never taking more than you give.
75017 **
75018 *************************************************************************
75019 ** This file contains routines used for walking the parser tree for
75020 ** an SQL statement.
75021 */
75022 /* #include <stdlib.h> */
75023 /* #include <string.h> */
75024 
75025 
75026 /*
75027 ** Walk an expression tree.  Invoke the callback once for each node
75028 ** of the expression, while decending.  (In other words, the callback
75029 ** is invoked before visiting children.)
75030 **
75031 ** The return value from the callback should be one of the WRC_*
75032 ** constants to specify how to proceed with the walk.
75033 **
75034 **    WRC_Continue      Continue descending down the tree.
75035 **
75036 **    WRC_Prune         Do not descend into child nodes.  But allow
75037 **                      the walk to continue with sibling nodes.
75038 **
75039 **    WRC_Abort         Do no more callbacks.  Unwind the stack and
75040 **                      return the top-level walk call.
75041 **
75042 ** The return value from this routine is WRC_Abort to abandon the tree walk
75043 ** and WRC_Continue to continue.
75044 */
75045 SQLITE_PRIVATE int sqlite3WalkExpr(Walker *pWalker, Expr *pExpr){
75046   int rc;
75047   if( pExpr==0 ) return WRC_Continue;
75048   testcase( ExprHasProperty(pExpr, EP_TokenOnly) );
75049   testcase( ExprHasProperty(pExpr, EP_Reduced) );
75050   rc = pWalker->xExprCallback(pWalker, pExpr);
75051   if( rc==WRC_Continue
75052               && !ExprHasProperty(pExpr,EP_TokenOnly) ){
75053     if( sqlite3WalkExpr(pWalker, pExpr->pLeft) ) return WRC_Abort;
75054     if( sqlite3WalkExpr(pWalker, pExpr->pRight) ) return WRC_Abort;
75055     if( ExprHasProperty(pExpr, EP_xIsSelect) ){
75056       if( sqlite3WalkSelect(pWalker, pExpr->x.pSelect) ) return WRC_Abort;
75057     }else{
75058       if( sqlite3WalkExprList(pWalker, pExpr->x.pList) ) return WRC_Abort;
75059     }
75060   }
75061   return rc & WRC_Abort;
75062 }
75063 
75064 /*
75065 ** Call sqlite3WalkExpr() for every expression in list p or until
75066 ** an abort request is seen.
75067 */
75068 SQLITE_PRIVATE int sqlite3WalkExprList(Walker *pWalker, ExprList *p){
75069   int i;
75070   struct ExprList_item *pItem;
75071   if( p ){
75072     for(i=p->nExpr, pItem=p->a; i>0; i--, pItem++){
75073       if( sqlite3WalkExpr(pWalker, pItem->pExpr) ) return WRC_Abort;
75074     }
75075   }
75076   return WRC_Continue;
75077 }
75078 
75079 /*
75080 ** Walk all expressions associated with SELECT statement p.  Do
75081 ** not invoke the SELECT callback on p, but do (of course) invoke
75082 ** any expr callbacks and SELECT callbacks that come from subqueries.
75083 ** Return WRC_Abort or WRC_Continue.
75084 */
75085 SQLITE_PRIVATE int sqlite3WalkSelectExpr(Walker *pWalker, Select *p){
75086   if( sqlite3WalkExprList(pWalker, p->pEList) ) return WRC_Abort;
75087   if( sqlite3WalkExpr(pWalker, p->pWhere) ) return WRC_Abort;
75088   if( sqlite3WalkExprList(pWalker, p->pGroupBy) ) return WRC_Abort;
75089   if( sqlite3WalkExpr(pWalker, p->pHaving) ) return WRC_Abort;
75090   if( sqlite3WalkExprList(pWalker, p->pOrderBy) ) return WRC_Abort;
75091   if( sqlite3WalkExpr(pWalker, p->pLimit) ) return WRC_Abort;
75092   if( sqlite3WalkExpr(pWalker, p->pOffset) ) return WRC_Abort;
75093   return WRC_Continue;
75094 }
75095 
75096 /*
75097 ** Walk the parse trees associated with all subqueries in the
75098 ** FROM clause of SELECT statement p.  Do not invoke the select
75099 ** callback on p, but do invoke it on each FROM clause subquery
75100 ** and on any subqueries further down in the tree.  Return 
75101 ** WRC_Abort or WRC_Continue;
75102 */
75103 SQLITE_PRIVATE int sqlite3WalkSelectFrom(Walker *pWalker, Select *p){
75104   SrcList *pSrc;
75105   int i;
75106   struct SrcList_item *pItem;
75107 
75108   pSrc = p->pSrc;
75109   if( ALWAYS(pSrc) ){
75110     for(i=pSrc->nSrc, pItem=pSrc->a; i>0; i--, pItem++){
75111       if( sqlite3WalkSelect(pWalker, pItem->pSelect) ){
75112         return WRC_Abort;
75113       }
75114     }
75115   }
75116   return WRC_Continue;
75117 } 
75118 
75119 /*
75120 ** Call sqlite3WalkExpr() for every expression in Select statement p.
75121 ** Invoke sqlite3WalkSelect() for subqueries in the FROM clause and
75122 ** on the compound select chain, p->pPrior.  Invoke the xSelectCallback()
75123 ** either before or after the walk of expressions and FROM clause, depending
75124 ** on whether pWalker->bSelectDepthFirst is false or true, respectively.
75125 **
75126 ** Return WRC_Continue under normal conditions.  Return WRC_Abort if
75127 ** there is an abort request.
75128 **
75129 ** If the Walker does not have an xSelectCallback() then this routine
75130 ** is a no-op returning WRC_Continue.
75131 */
75132 SQLITE_PRIVATE int sqlite3WalkSelect(Walker *pWalker, Select *p){
75133   int rc;
75134   if( p==0 || pWalker->xSelectCallback==0 ) return WRC_Continue;
75135   rc = WRC_Continue;
75136   pWalker->walkerDepth++;
75137   while( p ){
75138     if( !pWalker->bSelectDepthFirst ){
75139        rc = pWalker->xSelectCallback(pWalker, p);
75140        if( rc ) break;
75141     }
75142     if( sqlite3WalkSelectExpr(pWalker, p)
75143      || sqlite3WalkSelectFrom(pWalker, p)
75144     ){
75145       pWalker->walkerDepth--;
75146       return WRC_Abort;
75147     }
75148     if( pWalker->bSelectDepthFirst ){
75149       rc = pWalker->xSelectCallback(pWalker, p);
75150       /* Depth-first search is currently only used for
75151       ** selectAddSubqueryTypeInfo() and that routine always returns
75152       ** WRC_Continue (0).  So the following branch is never taken. */
75153       if( NEVER(rc) ) break;
75154     }
75155     p = p->pPrior;
75156   }
75157   pWalker->walkerDepth--;
75158   return rc & WRC_Abort;
75159 }
75160 
75161 /************** End of walker.c **********************************************/
75162 /************** Begin file resolve.c *****************************************/
75163 /*
75164 ** 2008 August 18
75165 **
75166 ** The author disclaims copyright to this source code.  In place of
75167 ** a legal notice, here is a blessing:
75168 **
75169 **    May you do good and not evil.
75170 **    May you find forgiveness for yourself and forgive others.
75171 **    May you share freely, never taking more than you give.
75172 **
75173 *************************************************************************
75174 **
75175 ** This file contains routines used for walking the parser tree and
75176 ** resolve all identifiers by associating them with a particular
75177 ** table and column.
75178 */
75179 /* #include <stdlib.h> */
75180 /* #include <string.h> */
75181 
75182 /*
75183 ** Walk the expression tree pExpr and increase the aggregate function
75184 ** depth (the Expr.op2 field) by N on every TK_AGG_FUNCTION node.
75185 ** This needs to occur when copying a TK_AGG_FUNCTION node from an
75186 ** outer query into an inner subquery.
75187 **
75188 ** incrAggFunctionDepth(pExpr,n) is the main routine.  incrAggDepth(..)
75189 ** is a helper function - a callback for the tree walker.
75190 */
75191 static int incrAggDepth(Walker *pWalker, Expr *pExpr){
75192   if( pExpr->op==TK_AGG_FUNCTION ) pExpr->op2 += pWalker->u.i;
75193   return WRC_Continue;
75194 }
75195 static void incrAggFunctionDepth(Expr *pExpr, int N){
75196   if( N>0 ){
75197     Walker w;
75198     memset(&w, 0, sizeof(w));
75199     w.xExprCallback = incrAggDepth;
75200     w.u.i = N;
75201     sqlite3WalkExpr(&w, pExpr);
75202   }
75203 }
75204 
75205 /*
75206 ** Turn the pExpr expression into an alias for the iCol-th column of the
75207 ** result set in pEList.
75208 **
75209 ** If the result set column is a simple column reference, then this routine
75210 ** makes an exact copy.  But for any other kind of expression, this
75211 ** routine make a copy of the result set column as the argument to the
75212 ** TK_AS operator.  The TK_AS operator causes the expression to be
75213 ** evaluated just once and then reused for each alias.
75214 **
75215 ** The reason for suppressing the TK_AS term when the expression is a simple
75216 ** column reference is so that the column reference will be recognized as
75217 ** usable by indices within the WHERE clause processing logic. 
75218 **
75219 ** The TK_AS operator is inhibited if zType[0]=='G'.  This means
75220 ** that in a GROUP BY clause, the expression is evaluated twice.  Hence:
75221 **
75222 **     SELECT random()%5 AS x, count(*) FROM tab GROUP BY x
75223 **
75224 ** Is equivalent to:
75225 **
75226 **     SELECT random()%5 AS x, count(*) FROM tab GROUP BY random()%5
75227 **
75228 ** The result of random()%5 in the GROUP BY clause is probably different
75229 ** from the result in the result-set.  On the other hand Standard SQL does
75230 ** not allow the GROUP BY clause to contain references to result-set columns.
75231 ** So this should never come up in well-formed queries.
75232 **
75233 ** If the reference is followed by a COLLATE operator, then make sure
75234 ** the COLLATE operator is preserved.  For example:
75235 **
75236 **     SELECT a+b, c+d FROM t1 ORDER BY 1 COLLATE nocase;
75237 **
75238 ** Should be transformed into:
75239 **
75240 **     SELECT a+b, c+d FROM t1 ORDER BY (a+b) COLLATE nocase;
75241 **
75242 ** The nSubquery parameter specifies how many levels of subquery the
75243 ** alias is removed from the original expression.  The usually value is
75244 ** zero but it might be more if the alias is contained within a subquery
75245 ** of the original expression.  The Expr.op2 field of TK_AGG_FUNCTION
75246 ** structures must be increased by the nSubquery amount.
75247 */
75248 static void resolveAlias(
75249   Parse *pParse,         /* Parsing context */
75250   ExprList *pEList,      /* A result set */
75251   int iCol,              /* A column in the result set.  0..pEList->nExpr-1 */
75252   Expr *pExpr,           /* Transform this into an alias to the result set */
75253   const char *zType,     /* "GROUP" or "ORDER" or "" */
75254   int nSubquery          /* Number of subqueries that the label is moving */
75255 ){
75256   Expr *pOrig;           /* The iCol-th column of the result set */
75257   Expr *pDup;            /* Copy of pOrig */
75258   sqlite3 *db;           /* The database connection */
75259 
75260   assert( iCol>=0 && iCol<pEList->nExpr );
75261   pOrig = pEList->a[iCol].pExpr;
75262   assert( pOrig!=0 );
75263   assert( pOrig->flags & EP_Resolved );
75264   db = pParse->db;
75265   pDup = sqlite3ExprDup(db, pOrig, 0);
75266   if( pDup==0 ) return;
75267   if( pOrig->op!=TK_COLUMN && zType[0]!='G' ){
75268     incrAggFunctionDepth(pDup, nSubquery);
75269     pDup = sqlite3PExpr(pParse, TK_AS, pDup, 0, 0);
75270     if( pDup==0 ) return;
75271     ExprSetProperty(pDup, EP_Skip);
75272     if( pEList->a[iCol].u.x.iAlias==0 ){
75273       pEList->a[iCol].u.x.iAlias = (u16)(++pParse->nAlias);
75274     }
75275     pDup->iTable = pEList->a[iCol].u.x.iAlias;
75276   }
75277   if( pExpr->op==TK_COLLATE ){
75278     pDup = sqlite3ExprAddCollateString(pParse, pDup, pExpr->u.zToken);
75279   }
75280 
75281   /* Before calling sqlite3ExprDelete(), set the EP_Static flag. This 
75282   ** prevents ExprDelete() from deleting the Expr structure itself,
75283   ** allowing it to be repopulated by the memcpy() on the following line.
75284   ** The pExpr->u.zToken might point into memory that will be freed by the
75285   ** sqlite3DbFree(db, pDup) on the last line of this block, so be sure to
75286   ** make a copy of the token before doing the sqlite3DbFree().
75287   */
75288   ExprSetProperty(pExpr, EP_Static);
75289   sqlite3ExprDelete(db, pExpr);
75290   memcpy(pExpr, pDup, sizeof(*pExpr));
75291   if( !ExprHasProperty(pExpr, EP_IntValue) && pExpr->u.zToken!=0 ){
75292     assert( (pExpr->flags & (EP_Reduced|EP_TokenOnly))==0 );
75293     pExpr->u.zToken = sqlite3DbStrDup(db, pExpr->u.zToken);
75294     pExpr->flags |= EP_MemToken;
75295   }
75296   sqlite3DbFree(db, pDup);
75297 }
75298 
75299 
75300 /*
75301 ** Return TRUE if the name zCol occurs anywhere in the USING clause.
75302 **
75303 ** Return FALSE if the USING clause is NULL or if it does not contain
75304 ** zCol.
75305 */
75306 static int nameInUsingClause(IdList *pUsing, const char *zCol){
75307   if( pUsing ){
75308     int k;
75309     for(k=0; k<pUsing->nId; k++){
75310       if( sqlite3StrICmp(pUsing->a[k].zName, zCol)==0 ) return 1;
75311     }
75312   }
75313   return 0;
75314 }
75315 
75316 /*
75317 ** Subqueries stores the original database, table and column names for their
75318 ** result sets in ExprList.a[].zSpan, in the form "DATABASE.TABLE.COLUMN".
75319 ** Check to see if the zSpan given to this routine matches the zDb, zTab,
75320 ** and zCol.  If any of zDb, zTab, and zCol are NULL then those fields will
75321 ** match anything.
75322 */
75323 SQLITE_PRIVATE int sqlite3MatchSpanName(
75324   const char *zSpan,
75325   const char *zCol,
75326   const char *zTab,
75327   const char *zDb
75328 ){
75329   int n;
75330   for(n=0; ALWAYS(zSpan[n]) && zSpan[n]!='.'; n++){}
75331   if( zDb && (sqlite3StrNICmp(zSpan, zDb, n)!=0 || zDb[n]!=0) ){
75332     return 0;
75333   }
75334   zSpan += n+1;
75335   for(n=0; ALWAYS(zSpan[n]) && zSpan[n]!='.'; n++){}
75336   if( zTab && (sqlite3StrNICmp(zSpan, zTab, n)!=0 || zTab[n]!=0) ){
75337     return 0;
75338   }
75339   zSpan += n+1;
75340   if( zCol && sqlite3StrICmp(zSpan, zCol)!=0 ){
75341     return 0;
75342   }
75343   return 1;
75344 }
75345 
75346 /*
75347 ** Given the name of a column of the form X.Y.Z or Y.Z or just Z, look up
75348 ** that name in the set of source tables in pSrcList and make the pExpr 
75349 ** expression node refer back to that source column.  The following changes
75350 ** are made to pExpr:
75351 **
75352 **    pExpr->iDb           Set the index in db->aDb[] of the database X
75353 **                         (even if X is implied).
75354 **    pExpr->iTable        Set to the cursor number for the table obtained
75355 **                         from pSrcList.
75356 **    pExpr->pTab          Points to the Table structure of X.Y (even if
75357 **                         X and/or Y are implied.)
75358 **    pExpr->iColumn       Set to the column number within the table.
75359 **    pExpr->op            Set to TK_COLUMN.
75360 **    pExpr->pLeft         Any expression this points to is deleted
75361 **    pExpr->pRight        Any expression this points to is deleted.
75362 **
75363 ** The zDb variable is the name of the database (the "X").  This value may be
75364 ** NULL meaning that name is of the form Y.Z or Z.  Any available database
75365 ** can be used.  The zTable variable is the name of the table (the "Y").  This
75366 ** value can be NULL if zDb is also NULL.  If zTable is NULL it
75367 ** means that the form of the name is Z and that columns from any table
75368 ** can be used.
75369 **
75370 ** If the name cannot be resolved unambiguously, leave an error message
75371 ** in pParse and return WRC_Abort.  Return WRC_Prune on success.
75372 */
75373 static int lookupName(
75374   Parse *pParse,       /* The parsing context */
75375   const char *zDb,     /* Name of the database containing table, or NULL */
75376   const char *zTab,    /* Name of table containing column, or NULL */
75377   const char *zCol,    /* Name of the column. */
75378   NameContext *pNC,    /* The name context used to resolve the name */
75379   Expr *pExpr          /* Make this EXPR node point to the selected column */
75380 ){
75381   int i, j;                         /* Loop counters */
75382   int cnt = 0;                      /* Number of matching column names */
75383   int cntTab = 0;                   /* Number of matching table names */
75384   int nSubquery = 0;                /* How many levels of subquery */
75385   sqlite3 *db = pParse->db;         /* The database connection */
75386   struct SrcList_item *pItem;       /* Use for looping over pSrcList items */
75387   struct SrcList_item *pMatch = 0;  /* The matching pSrcList item */
75388   NameContext *pTopNC = pNC;        /* First namecontext in the list */
75389   Schema *pSchema = 0;              /* Schema of the expression */
75390   int isTrigger = 0;                /* True if resolved to a trigger column */
75391   Table *pTab = 0;                  /* Table hold the row */
75392   Column *pCol;                     /* A column of pTab */
75393 
75394   assert( pNC );     /* the name context cannot be NULL. */
75395   assert( zCol );    /* The Z in X.Y.Z cannot be NULL */
75396   assert( !ExprHasProperty(pExpr, EP_TokenOnly|EP_Reduced) );
75397 
75398   /* Initialize the node to no-match */
75399   pExpr->iTable = -1;
75400   pExpr->pTab = 0;
75401   ExprSetVVAProperty(pExpr, EP_NoReduce);
75402 
75403   /* Translate the schema name in zDb into a pointer to the corresponding
75404   ** schema.  If not found, pSchema will remain NULL and nothing will match
75405   ** resulting in an appropriate error message toward the end of this routine
75406   */
75407   if( zDb ){
75408     testcase( pNC->ncFlags & NC_PartIdx );
75409     testcase( pNC->ncFlags & NC_IsCheck );
75410     if( (pNC->ncFlags & (NC_PartIdx|NC_IsCheck))!=0 ){
75411       /* Silently ignore database qualifiers inside CHECK constraints and partial
75412       ** indices.  Do not raise errors because that might break legacy and
75413       ** because it does not hurt anything to just ignore the database name. */
75414       zDb = 0;
75415     }else{
75416       for(i=0; i<db->nDb; i++){
75417         assert( db->aDb[i].zName );
75418         if( sqlite3StrICmp(db->aDb[i].zName,zDb)==0 ){
75419           pSchema = db->aDb[i].pSchema;
75420           break;
75421         }
75422       }
75423     }
75424   }
75425 
75426   /* Start at the inner-most context and move outward until a match is found */
75427   while( pNC && cnt==0 ){
75428     ExprList *pEList;
75429     SrcList *pSrcList = pNC->pSrcList;
75430 
75431     if( pSrcList ){
75432       for(i=0, pItem=pSrcList->a; i<pSrcList->nSrc; i++, pItem++){
75433         pTab = pItem->pTab;
75434         assert( pTab!=0 && pTab->zName!=0 );
75435         assert( pTab->nCol>0 );
75436         if( pItem->pSelect && (pItem->pSelect->selFlags & SF_NestedFrom)!=0 ){
75437           int hit = 0;
75438           pEList = pItem->pSelect->pEList;
75439           for(j=0; j<pEList->nExpr; j++){
75440             if( sqlite3MatchSpanName(pEList->a[j].zSpan, zCol, zTab, zDb) ){
75441               cnt++;
75442               cntTab = 2;
75443               pMatch = pItem;
75444               pExpr->iColumn = j;
75445               hit = 1;
75446             }
75447           }
75448           if( hit || zTab==0 ) continue;
75449         }
75450         if( zDb && pTab->pSchema!=pSchema ){
75451           continue;
75452         }
75453         if( zTab ){
75454           const char *zTabName = pItem->zAlias ? pItem->zAlias : pTab->zName;
75455           assert( zTabName!=0 );
75456           if( sqlite3StrICmp(zTabName, zTab)!=0 ){
75457             continue;
75458           }
75459         }
75460         if( 0==(cntTab++) ){
75461           pMatch = pItem;
75462         }
75463         for(j=0, pCol=pTab->aCol; j<pTab->nCol; j++, pCol++){
75464           if( sqlite3StrICmp(pCol->zName, zCol)==0 ){
75465             /* If there has been exactly one prior match and this match
75466             ** is for the right-hand table of a NATURAL JOIN or is in a 
75467             ** USING clause, then skip this match.
75468             */
75469             if( cnt==1 ){
75470               if( pItem->jointype & JT_NATURAL ) continue;
75471               if( nameInUsingClause(pItem->pUsing, zCol) ) continue;
75472             }
75473             cnt++;
75474             pMatch = pItem;
75475             /* Substitute the rowid (column -1) for the INTEGER PRIMARY KEY */
75476             pExpr->iColumn = j==pTab->iPKey ? -1 : (i16)j;
75477             break;
75478           }
75479         }
75480       }
75481       if( pMatch ){
75482         pExpr->iTable = pMatch->iCursor;
75483         pExpr->pTab = pMatch->pTab;
75484         pSchema = pExpr->pTab->pSchema;
75485       }
75486     } /* if( pSrcList ) */
75487 
75488 #ifndef SQLITE_OMIT_TRIGGER
75489     /* If we have not already resolved the name, then maybe 
75490     ** it is a new.* or old.* trigger argument reference
75491     */
75492     if( zDb==0 && zTab!=0 && cntTab==0 && pParse->pTriggerTab!=0 ){
75493       int op = pParse->eTriggerOp;
75494       assert( op==TK_DELETE || op==TK_UPDATE || op==TK_INSERT );
75495       if( op!=TK_DELETE && sqlite3StrICmp("new",zTab) == 0 ){
75496         pExpr->iTable = 1;
75497         pTab = pParse->pTriggerTab;
75498       }else if( op!=TK_INSERT && sqlite3StrICmp("old",zTab)==0 ){
75499         pExpr->iTable = 0;
75500         pTab = pParse->pTriggerTab;
75501       }
75502 
75503       if( pTab ){ 
75504         int iCol;
75505         pSchema = pTab->pSchema;
75506         cntTab++;
75507         for(iCol=0, pCol=pTab->aCol; iCol<pTab->nCol; iCol++, pCol++){
75508           if( sqlite3StrICmp(pCol->zName, zCol)==0 ){
75509             if( iCol==pTab->iPKey ){
75510               iCol = -1;
75511             }
75512             break;
75513           }
75514         }
75515         if( iCol>=pTab->nCol && sqlite3IsRowid(zCol) && HasRowid(pTab) ){
75516           /* IMP: R-24309-18625 */
75517           /* IMP: R-44911-55124 */
75518           iCol = -1;
75519         }
75520         if( iCol<pTab->nCol ){
75521           cnt++;
75522           if( iCol<0 ){
75523             pExpr->affinity = SQLITE_AFF_INTEGER;
75524           }else if( pExpr->iTable==0 ){
75525             testcase( iCol==31 );
75526             testcase( iCol==32 );
75527             pParse->oldmask |= (iCol>=32 ? 0xffffffff : (((u32)1)<<iCol));
75528           }else{
75529             testcase( iCol==31 );
75530             testcase( iCol==32 );
75531             pParse->newmask |= (iCol>=32 ? 0xffffffff : (((u32)1)<<iCol));
75532           }
75533           pExpr->iColumn = (i16)iCol;
75534           pExpr->pTab = pTab;
75535           isTrigger = 1;
75536         }
75537       }
75538     }
75539 #endif /* !defined(SQLITE_OMIT_TRIGGER) */
75540 
75541     /*
75542     ** Perhaps the name is a reference to the ROWID
75543     */
75544     assert( pTab!=0 || cntTab==0 );
75545     if( cnt==0 && cntTab==1 && sqlite3IsRowid(zCol) && HasRowid(pTab) ){
75546       cnt = 1;
75547       pExpr->iColumn = -1;     /* IMP: R-44911-55124 */
75548       pExpr->affinity = SQLITE_AFF_INTEGER;
75549     }
75550 
75551     /*
75552     ** If the input is of the form Z (not Y.Z or X.Y.Z) then the name Z
75553     ** might refer to an result-set alias.  This happens, for example, when
75554     ** we are resolving names in the WHERE clause of the following command:
75555     **
75556     **     SELECT a+b AS x FROM table WHERE x<10;
75557     **
75558     ** In cases like this, replace pExpr with a copy of the expression that
75559     ** forms the result set entry ("a+b" in the example) and return immediately.
75560     ** Note that the expression in the result set should have already been
75561     ** resolved by the time the WHERE clause is resolved.
75562     **
75563     ** The ability to use an output result-set column in the WHERE, GROUP BY,
75564     ** or HAVING clauses, or as part of a larger expression in the ORDRE BY
75565     ** clause is not standard SQL.  This is a (goofy) SQLite extension, that
75566     ** is supported for backwards compatibility only.  TO DO: Issue a warning
75567     ** on sqlite3_log() whenever the capability is used.
75568     */
75569     if( (pEList = pNC->pEList)!=0
75570      && zTab==0
75571      && cnt==0
75572     ){
75573       for(j=0; j<pEList->nExpr; j++){
75574         char *zAs = pEList->a[j].zName;
75575         if( zAs!=0 && sqlite3StrICmp(zAs, zCol)==0 ){
75576           Expr *pOrig;
75577           assert( pExpr->pLeft==0 && pExpr->pRight==0 );
75578           assert( pExpr->x.pList==0 );
75579           assert( pExpr->x.pSelect==0 );
75580           pOrig = pEList->a[j].pExpr;
75581           if( (pNC->ncFlags&NC_AllowAgg)==0 && ExprHasProperty(pOrig, EP_Agg) ){
75582             sqlite3ErrorMsg(pParse, "misuse of aliased aggregate %s", zAs);
75583             return WRC_Abort;
75584           }
75585           resolveAlias(pParse, pEList, j, pExpr, "", nSubquery);
75586           cnt = 1;
75587           pMatch = 0;
75588           assert( zTab==0 && zDb==0 );
75589           goto lookupname_end;
75590         }
75591       } 
75592     }
75593 
75594     /* Advance to the next name context.  The loop will exit when either
75595     ** we have a match (cnt>0) or when we run out of name contexts.
75596     */
75597     if( cnt==0 ){
75598       pNC = pNC->pNext;
75599       nSubquery++;
75600     }
75601   }
75602 
75603   /*
75604   ** If X and Y are NULL (in other words if only the column name Z is
75605   ** supplied) and the value of Z is enclosed in double-quotes, then
75606   ** Z is a string literal if it doesn't match any column names.  In that
75607   ** case, we need to return right away and not make any changes to
75608   ** pExpr.
75609   **
75610   ** Because no reference was made to outer contexts, the pNC->nRef
75611   ** fields are not changed in any context.
75612   */
75613   if( cnt==0 && zTab==0 && ExprHasProperty(pExpr,EP_DblQuoted) ){
75614     pExpr->op = TK_STRING;
75615     pExpr->pTab = 0;
75616     return WRC_Prune;
75617   }
75618 
75619   /*
75620   ** cnt==0 means there was not match.  cnt>1 means there were two or
75621   ** more matches.  Either way, we have an error.
75622   */
75623   if( cnt!=1 ){
75624     const char *zErr;
75625     zErr = cnt==0 ? "no such column" : "ambiguous column name";
75626     if( zDb ){
75627       sqlite3ErrorMsg(pParse, "%s: %s.%s.%s", zErr, zDb, zTab, zCol);
75628     }else if( zTab ){
75629       sqlite3ErrorMsg(pParse, "%s: %s.%s", zErr, zTab, zCol);
75630     }else{
75631       sqlite3ErrorMsg(pParse, "%s: %s", zErr, zCol);
75632     }
75633     pParse->checkSchema = 1;
75634     pTopNC->nErr++;
75635   }
75636 
75637   /* If a column from a table in pSrcList is referenced, then record
75638   ** this fact in the pSrcList.a[].colUsed bitmask.  Column 0 causes
75639   ** bit 0 to be set.  Column 1 sets bit 1.  And so forth.  If the
75640   ** column number is greater than the number of bits in the bitmask
75641   ** then set the high-order bit of the bitmask.
75642   */
75643   if( pExpr->iColumn>=0 && pMatch!=0 ){
75644     int n = pExpr->iColumn;
75645     testcase( n==BMS-1 );
75646     if( n>=BMS ){
75647       n = BMS-1;
75648     }
75649     assert( pMatch->iCursor==pExpr->iTable );
75650     pMatch->colUsed |= ((Bitmask)1)<<n;
75651   }
75652 
75653   /* Clean up and return
75654   */
75655   sqlite3ExprDelete(db, pExpr->pLeft);
75656   pExpr->pLeft = 0;
75657   sqlite3ExprDelete(db, pExpr->pRight);
75658   pExpr->pRight = 0;
75659   pExpr->op = (isTrigger ? TK_TRIGGER : TK_COLUMN);
75660 lookupname_end:
75661   if( cnt==1 ){
75662     assert( pNC!=0 );
75663     if( pExpr->op!=TK_AS ){
75664       sqlite3AuthRead(pParse, pExpr, pSchema, pNC->pSrcList);
75665     }
75666     /* Increment the nRef value on all name contexts from TopNC up to
75667     ** the point where the name matched. */
75668     for(;;){
75669       assert( pTopNC!=0 );
75670       pTopNC->nRef++;
75671       if( pTopNC==pNC ) break;
75672       pTopNC = pTopNC->pNext;
75673     }
75674     return WRC_Prune;
75675   } else {
75676     return WRC_Abort;
75677   }
75678 }
75679 
75680 /*
75681 ** Allocate and return a pointer to an expression to load the column iCol
75682 ** from datasource iSrc in SrcList pSrc.
75683 */
75684 SQLITE_PRIVATE Expr *sqlite3CreateColumnExpr(sqlite3 *db, SrcList *pSrc, int iSrc, int iCol){
75685   Expr *p = sqlite3ExprAlloc(db, TK_COLUMN, 0, 0);
75686   if( p ){
75687     struct SrcList_item *pItem = &pSrc->a[iSrc];
75688     p->pTab = pItem->pTab;
75689     p->iTable = pItem->iCursor;
75690     if( p->pTab->iPKey==iCol ){
75691       p->iColumn = -1;
75692     }else{
75693       p->iColumn = (ynVar)iCol;
75694       testcase( iCol==BMS );
75695       testcase( iCol==BMS-1 );
75696       pItem->colUsed |= ((Bitmask)1)<<(iCol>=BMS ? BMS-1 : iCol);
75697     }
75698     ExprSetProperty(p, EP_Resolved);
75699   }
75700   return p;
75701 }
75702 
75703 /*
75704 ** Report an error that an expression is not valid for a partial index WHERE
75705 ** clause.
75706 */
75707 static void notValidPartIdxWhere(
75708   Parse *pParse,       /* Leave error message here */
75709   NameContext *pNC,    /* The name context */
75710   const char *zMsg     /* Type of error */
75711 ){
75712   if( (pNC->ncFlags & NC_PartIdx)!=0 ){
75713     sqlite3ErrorMsg(pParse, "%s prohibited in partial index WHERE clauses",
75714                     zMsg);
75715   }
75716 }
75717 
75718 #ifndef SQLITE_OMIT_CHECK
75719 /*
75720 ** Report an error that an expression is not valid for a CHECK constraint.
75721 */
75722 static void notValidCheckConstraint(
75723   Parse *pParse,       /* Leave error message here */
75724   NameContext *pNC,    /* The name context */
75725   const char *zMsg     /* Type of error */
75726 ){
75727   if( (pNC->ncFlags & NC_IsCheck)!=0 ){
75728     sqlite3ErrorMsg(pParse,"%s prohibited in CHECK constraints", zMsg);
75729   }
75730 }
75731 #else
75732 # define notValidCheckConstraint(P,N,M)
75733 #endif
75734 
75735 /*
75736 ** Expression p should encode a floating point value between 1.0 and 0.0.
75737 ** Return 1024 times this value.  Or return -1 if p is not a floating point
75738 ** value between 1.0 and 0.0.
75739 */
75740 static int exprProbability(Expr *p){
75741   double r = -1.0;
75742   if( p->op!=TK_FLOAT ) return -1;
75743   sqlite3AtoF(p->u.zToken, &r, sqlite3Strlen30(p->u.zToken), SQLITE_UTF8);
75744   assert( r>=0.0 );
75745   if( r>1.0 ) return -1;
75746   return (int)(r*1000.0);
75747 }
75748 
75749 /*
75750 ** This routine is callback for sqlite3WalkExpr().
75751 **
75752 ** Resolve symbolic names into TK_COLUMN operators for the current
75753 ** node in the expression tree.  Return 0 to continue the search down
75754 ** the tree or 2 to abort the tree walk.
75755 **
75756 ** This routine also does error checking and name resolution for
75757 ** function names.  The operator for aggregate functions is changed
75758 ** to TK_AGG_FUNCTION.
75759 */
75760 static int resolveExprStep(Walker *pWalker, Expr *pExpr){
75761   NameContext *pNC;
75762   Parse *pParse;
75763 
75764   pNC = pWalker->u.pNC;
75765   assert( pNC!=0 );
75766   pParse = pNC->pParse;
75767   assert( pParse==pWalker->pParse );
75768 
75769   if( ExprHasProperty(pExpr, EP_Resolved) ) return WRC_Prune;
75770   ExprSetProperty(pExpr, EP_Resolved);
75771 #ifndef NDEBUG
75772   if( pNC->pSrcList && pNC->pSrcList->nAlloc>0 ){
75773     SrcList *pSrcList = pNC->pSrcList;
75774     int i;
75775     for(i=0; i<pNC->pSrcList->nSrc; i++){
75776       assert( pSrcList->a[i].iCursor>=0 && pSrcList->a[i].iCursor<pParse->nTab);
75777     }
75778   }
75779 #endif
75780   switch( pExpr->op ){
75781 
75782 #if defined(SQLITE_ENABLE_UPDATE_DELETE_LIMIT) && !defined(SQLITE_OMIT_SUBQUERY)
75783     /* The special operator TK_ROW means use the rowid for the first
75784     ** column in the FROM clause.  This is used by the LIMIT and ORDER BY
75785     ** clause processing on UPDATE and DELETE statements.
75786     */
75787     case TK_ROW: {
75788       SrcList *pSrcList = pNC->pSrcList;
75789       struct SrcList_item *pItem;
75790       assert( pSrcList && pSrcList->nSrc==1 );
75791       pItem = pSrcList->a; 
75792       pExpr->op = TK_COLUMN;
75793       pExpr->pTab = pItem->pTab;
75794       pExpr->iTable = pItem->iCursor;
75795       pExpr->iColumn = -1;
75796       pExpr->affinity = SQLITE_AFF_INTEGER;
75797       break;
75798     }
75799 #endif /* defined(SQLITE_ENABLE_UPDATE_DELETE_LIMIT) && !defined(SQLITE_OMIT_SUBQUERY) */
75800 
75801     /* A lone identifier is the name of a column.
75802     */
75803     case TK_ID: {
75804       return lookupName(pParse, 0, 0, pExpr->u.zToken, pNC, pExpr);
75805     }
75806   
75807     /* A table name and column name:     ID.ID
75808     ** Or a database, table and column:  ID.ID.ID
75809     */
75810     case TK_DOT: {
75811       const char *zColumn;
75812       const char *zTable;
75813       const char *zDb;
75814       Expr *pRight;
75815 
75816       /* if( pSrcList==0 ) break; */
75817       pRight = pExpr->pRight;
75818       if( pRight->op==TK_ID ){
75819         zDb = 0;
75820         zTable = pExpr->pLeft->u.zToken;
75821         zColumn = pRight->u.zToken;
75822       }else{
75823         assert( pRight->op==TK_DOT );
75824         zDb = pExpr->pLeft->u.zToken;
75825         zTable = pRight->pLeft->u.zToken;
75826         zColumn = pRight->pRight->u.zToken;
75827       }
75828       return lookupName(pParse, zDb, zTable, zColumn, pNC, pExpr);
75829     }
75830 
75831     /* Resolve function names
75832     */
75833     case TK_FUNCTION: {
75834       ExprList *pList = pExpr->x.pList;    /* The argument list */
75835       int n = pList ? pList->nExpr : 0;    /* Number of arguments */
75836       int no_such_func = 0;       /* True if no such function exists */
75837       int wrong_num_args = 0;     /* True if wrong number of arguments */
75838       int is_agg = 0;             /* True if is an aggregate function */
75839       int auth;                   /* Authorization to use the function */
75840       int nId;                    /* Number of characters in function name */
75841       const char *zId;            /* The function name. */
75842       FuncDef *pDef;              /* Information about the function */
75843       u8 enc = ENC(pParse->db);   /* The database encoding */
75844 
75845       assert( !ExprHasProperty(pExpr, EP_xIsSelect) );
75846       notValidPartIdxWhere(pParse, pNC, "functions");
75847       zId = pExpr->u.zToken;
75848       nId = sqlite3Strlen30(zId);
75849       pDef = sqlite3FindFunction(pParse->db, zId, nId, n, enc, 0);
75850       if( pDef==0 ){
75851         pDef = sqlite3FindFunction(pParse->db, zId, nId, -2, enc, 0);
75852         if( pDef==0 ){
75853           no_such_func = 1;
75854         }else{
75855           wrong_num_args = 1;
75856         }
75857       }else{
75858         is_agg = pDef->xFunc==0;
75859         if( pDef->funcFlags & SQLITE_FUNC_UNLIKELY ){
75860           ExprSetProperty(pExpr, EP_Unlikely|EP_Skip);
75861           if( n==2 ){
75862             pExpr->iTable = exprProbability(pList->a[1].pExpr);
75863             if( pExpr->iTable<0 ){
75864               sqlite3ErrorMsg(pParse, "second argument to likelihood() must be a "
75865                                       "constant between 0.0 and 1.0");
75866               pNC->nErr++;
75867             }
75868           }else{
75869             /* EVIDENCE-OF: R-61304-29449 The unlikely(X) function is equivalent to
75870             ** likelihood(X, 0.0625).
75871             ** EVIDENCE-OF: R-01283-11636 The unlikely(X) function is short-hand for
75872             ** likelihood(X,0.0625). */
75873             pExpr->iTable = 62;  /* TUNING:  Default 2nd arg to unlikely() is 0.0625 */
75874           }             
75875         }
75876       }
75877 #ifndef SQLITE_OMIT_AUTHORIZATION
75878       if( pDef ){
75879         auth = sqlite3AuthCheck(pParse, SQLITE_FUNCTION, 0, pDef->zName, 0);
75880         if( auth!=SQLITE_OK ){
75881           if( auth==SQLITE_DENY ){
75882             sqlite3ErrorMsg(pParse, "not authorized to use function: %s",
75883                                     pDef->zName);
75884             pNC->nErr++;
75885           }
75886           pExpr->op = TK_NULL;
75887           return WRC_Prune;
75888         }
75889         if( pDef->funcFlags & SQLITE_FUNC_CONSTANT ) ExprSetProperty(pExpr,EP_Constant);
75890       }
75891 #endif
75892       if( is_agg && (pNC->ncFlags & NC_AllowAgg)==0 ){
75893         sqlite3ErrorMsg(pParse, "misuse of aggregate function %.*s()", nId,zId);
75894         pNC->nErr++;
75895         is_agg = 0;
75896       }else if( no_such_func && pParse->db->init.busy==0 ){
75897         sqlite3ErrorMsg(pParse, "no such function: %.*s", nId, zId);
75898         pNC->nErr++;
75899       }else if( wrong_num_args ){
75900         sqlite3ErrorMsg(pParse,"wrong number of arguments to function %.*s()",
75901              nId, zId);
75902         pNC->nErr++;
75903       }
75904       if( is_agg ) pNC->ncFlags &= ~NC_AllowAgg;
75905       sqlite3WalkExprList(pWalker, pList);
75906       if( is_agg ){
75907         NameContext *pNC2 = pNC;
75908         pExpr->op = TK_AGG_FUNCTION;
75909         pExpr->op2 = 0;
75910         while( pNC2 && !sqlite3FunctionUsesThisSrc(pExpr, pNC2->pSrcList) ){
75911           pExpr->op2++;
75912           pNC2 = pNC2->pNext;
75913         }
75914         if( pNC2 ) pNC2->ncFlags |= NC_HasAgg;
75915         pNC->ncFlags |= NC_AllowAgg;
75916       }
75917       /* FIX ME:  Compute pExpr->affinity based on the expected return
75918       ** type of the function 
75919       */
75920       return WRC_Prune;
75921     }
75922 #ifndef SQLITE_OMIT_SUBQUERY
75923     case TK_SELECT:
75924     case TK_EXISTS:  testcase( pExpr->op==TK_EXISTS );
75925 #endif
75926     case TK_IN: {
75927       testcase( pExpr->op==TK_IN );
75928       if( ExprHasProperty(pExpr, EP_xIsSelect) ){
75929         int nRef = pNC->nRef;
75930         notValidCheckConstraint(pParse, pNC, "subqueries");
75931         notValidPartIdxWhere(pParse, pNC, "subqueries");
75932         sqlite3WalkSelect(pWalker, pExpr->x.pSelect);
75933         assert( pNC->nRef>=nRef );
75934         if( nRef!=pNC->nRef ){
75935           ExprSetProperty(pExpr, EP_VarSelect);
75936         }
75937       }
75938       break;
75939     }
75940     case TK_VARIABLE: {
75941       notValidCheckConstraint(pParse, pNC, "parameters");
75942       notValidPartIdxWhere(pParse, pNC, "parameters");
75943       break;
75944     }
75945   }
75946   return (pParse->nErr || pParse->db->mallocFailed) ? WRC_Abort : WRC_Continue;
75947 }
75948 
75949 /*
75950 ** pEList is a list of expressions which are really the result set of the
75951 ** a SELECT statement.  pE is a term in an ORDER BY or GROUP BY clause.
75952 ** This routine checks to see if pE is a simple identifier which corresponds
75953 ** to the AS-name of one of the terms of the expression list.  If it is,
75954 ** this routine return an integer between 1 and N where N is the number of
75955 ** elements in pEList, corresponding to the matching entry.  If there is
75956 ** no match, or if pE is not a simple identifier, then this routine
75957 ** return 0.
75958 **
75959 ** pEList has been resolved.  pE has not.
75960 */
75961 static int resolveAsName(
75962   Parse *pParse,     /* Parsing context for error messages */
75963   ExprList *pEList,  /* List of expressions to scan */
75964   Expr *pE           /* Expression we are trying to match */
75965 ){
75966   int i;             /* Loop counter */
75967 
75968   UNUSED_PARAMETER(pParse);
75969 
75970   if( pE->op==TK_ID ){
75971     char *zCol = pE->u.zToken;
75972     for(i=0; i<pEList->nExpr; i++){
75973       char *zAs = pEList->a[i].zName;
75974       if( zAs!=0 && sqlite3StrICmp(zAs, zCol)==0 ){
75975         return i+1;
75976       }
75977     }
75978   }
75979   return 0;
75980 }
75981 
75982 /*
75983 ** pE is a pointer to an expression which is a single term in the
75984 ** ORDER BY of a compound SELECT.  The expression has not been
75985 ** name resolved.
75986 **
75987 ** At the point this routine is called, we already know that the
75988 ** ORDER BY term is not an integer index into the result set.  That
75989 ** case is handled by the calling routine.
75990 **
75991 ** Attempt to match pE against result set columns in the left-most
75992 ** SELECT statement.  Return the index i of the matching column,
75993 ** as an indication to the caller that it should sort by the i-th column.
75994 ** The left-most column is 1.  In other words, the value returned is the
75995 ** same integer value that would be used in the SQL statement to indicate
75996 ** the column.
75997 **
75998 ** If there is no match, return 0.  Return -1 if an error occurs.
75999 */
76000 static int resolveOrderByTermToExprList(
76001   Parse *pParse,     /* Parsing context for error messages */
76002   Select *pSelect,   /* The SELECT statement with the ORDER BY clause */
76003   Expr *pE           /* The specific ORDER BY term */
76004 ){
76005   int i;             /* Loop counter */
76006   ExprList *pEList;  /* The columns of the result set */
76007   NameContext nc;    /* Name context for resolving pE */
76008   sqlite3 *db;       /* Database connection */
76009   int rc;            /* Return code from subprocedures */
76010   u8 savedSuppErr;   /* Saved value of db->suppressErr */
76011 
76012   assert( sqlite3ExprIsInteger(pE, &i)==0 );
76013   pEList = pSelect->pEList;
76014 
76015   /* Resolve all names in the ORDER BY term expression
76016   */
76017   memset(&nc, 0, sizeof(nc));
76018   nc.pParse = pParse;
76019   nc.pSrcList = pSelect->pSrc;
76020   nc.pEList = pEList;
76021   nc.ncFlags = NC_AllowAgg;
76022   nc.nErr = 0;
76023   db = pParse->db;
76024   savedSuppErr = db->suppressErr;
76025   db->suppressErr = 1;
76026   rc = sqlite3ResolveExprNames(&nc, pE);
76027   db->suppressErr = savedSuppErr;
76028   if( rc ) return 0;
76029 
76030   /* Try to match the ORDER BY expression against an expression
76031   ** in the result set.  Return an 1-based index of the matching
76032   ** result-set entry.
76033   */
76034   for(i=0; i<pEList->nExpr; i++){
76035     if( sqlite3ExprCompare(pEList->a[i].pExpr, pE, -1)<2 ){
76036       return i+1;
76037     }
76038   }
76039 
76040   /* If no match, return 0. */
76041   return 0;
76042 }
76043 
76044 /*
76045 ** Generate an ORDER BY or GROUP BY term out-of-range error.
76046 */
76047 static void resolveOutOfRangeError(
76048   Parse *pParse,         /* The error context into which to write the error */
76049   const char *zType,     /* "ORDER" or "GROUP" */
76050   int i,                 /* The index (1-based) of the term out of range */
76051   int mx                 /* Largest permissible value of i */
76052 ){
76053   sqlite3ErrorMsg(pParse, 
76054     "%r %s BY term out of range - should be "
76055     "between 1 and %d", i, zType, mx);
76056 }
76057 
76058 /*
76059 ** Analyze the ORDER BY clause in a compound SELECT statement.   Modify
76060 ** each term of the ORDER BY clause is a constant integer between 1
76061 ** and N where N is the number of columns in the compound SELECT.
76062 **
76063 ** ORDER BY terms that are already an integer between 1 and N are
76064 ** unmodified.  ORDER BY terms that are integers outside the range of
76065 ** 1 through N generate an error.  ORDER BY terms that are expressions
76066 ** are matched against result set expressions of compound SELECT
76067 ** beginning with the left-most SELECT and working toward the right.
76068 ** At the first match, the ORDER BY expression is transformed into
76069 ** the integer column number.
76070 **
76071 ** Return the number of errors seen.
76072 */
76073 static int resolveCompoundOrderBy(
76074   Parse *pParse,        /* Parsing context.  Leave error messages here */
76075   Select *pSelect       /* The SELECT statement containing the ORDER BY */
76076 ){
76077   int i;
76078   ExprList *pOrderBy;
76079   ExprList *pEList;
76080   sqlite3 *db;
76081   int moreToDo = 1;
76082 
76083   pOrderBy = pSelect->pOrderBy;
76084   if( pOrderBy==0 ) return 0;
76085   db = pParse->db;
76086 #if SQLITE_MAX_COLUMN
76087   if( pOrderBy->nExpr>db->aLimit[SQLITE_LIMIT_COLUMN] ){
76088     sqlite3ErrorMsg(pParse, "too many terms in ORDER BY clause");
76089     return 1;
76090   }
76091 #endif
76092   for(i=0; i<pOrderBy->nExpr; i++){
76093     pOrderBy->a[i].done = 0;
76094   }
76095   pSelect->pNext = 0;
76096   while( pSelect->pPrior ){
76097     pSelect->pPrior->pNext = pSelect;
76098     pSelect = pSelect->pPrior;
76099   }
76100   while( pSelect && moreToDo ){
76101     struct ExprList_item *pItem;
76102     moreToDo = 0;
76103     pEList = pSelect->pEList;
76104     assert( pEList!=0 );
76105     for(i=0, pItem=pOrderBy->a; i<pOrderBy->nExpr; i++, pItem++){
76106       int iCol = -1;
76107       Expr *pE, *pDup;
76108       if( pItem->done ) continue;
76109       pE = sqlite3ExprSkipCollate(pItem->pExpr);
76110       if( sqlite3ExprIsInteger(pE, &iCol) ){
76111         if( iCol<=0 || iCol>pEList->nExpr ){
76112           resolveOutOfRangeError(pParse, "ORDER", i+1, pEList->nExpr);
76113           return 1;
76114         }
76115       }else{
76116         iCol = resolveAsName(pParse, pEList, pE);
76117         if( iCol==0 ){
76118           pDup = sqlite3ExprDup(db, pE, 0);
76119           if( !db->mallocFailed ){
76120             assert(pDup);
76121             iCol = resolveOrderByTermToExprList(pParse, pSelect, pDup);
76122           }
76123           sqlite3ExprDelete(db, pDup);
76124         }
76125       }
76126       if( iCol>0 ){
76127         /* Convert the ORDER BY term into an integer column number iCol,
76128         ** taking care to preserve the COLLATE clause if it exists */
76129         Expr *pNew = sqlite3Expr(db, TK_INTEGER, 0);
76130         if( pNew==0 ) return 1;
76131         pNew->flags |= EP_IntValue;
76132         pNew->u.iValue = iCol;
76133         if( pItem->pExpr==pE ){
76134           pItem->pExpr = pNew;
76135         }else{
76136           assert( pItem->pExpr->op==TK_COLLATE );
76137           assert( pItem->pExpr->pLeft==pE );
76138           pItem->pExpr->pLeft = pNew;
76139         }
76140         sqlite3ExprDelete(db, pE);
76141         pItem->u.x.iOrderByCol = (u16)iCol;
76142         pItem->done = 1;
76143       }else{
76144         moreToDo = 1;
76145       }
76146     }
76147     pSelect = pSelect->pNext;
76148   }
76149   for(i=0; i<pOrderBy->nExpr; i++){
76150     if( pOrderBy->a[i].done==0 ){
76151       sqlite3ErrorMsg(pParse, "%r ORDER BY term does not match any "
76152             "column in the result set", i+1);
76153       return 1;
76154     }
76155   }
76156   return 0;
76157 }
76158 
76159 /*
76160 ** Check every term in the ORDER BY or GROUP BY clause pOrderBy of
76161 ** the SELECT statement pSelect.  If any term is reference to a
76162 ** result set expression (as determined by the ExprList.a.u.x.iOrderByCol
76163 ** field) then convert that term into a copy of the corresponding result set
76164 ** column.
76165 **
76166 ** If any errors are detected, add an error message to pParse and
76167 ** return non-zero.  Return zero if no errors are seen.
76168 */
76169 SQLITE_PRIVATE int sqlite3ResolveOrderGroupBy(
76170   Parse *pParse,        /* Parsing context.  Leave error messages here */
76171   Select *pSelect,      /* The SELECT statement containing the clause */
76172   ExprList *pOrderBy,   /* The ORDER BY or GROUP BY clause to be processed */
76173   const char *zType     /* "ORDER" or "GROUP" */
76174 ){
76175   int i;
76176   sqlite3 *db = pParse->db;
76177   ExprList *pEList;
76178   struct ExprList_item *pItem;
76179 
76180   if( pOrderBy==0 || pParse->db->mallocFailed ) return 0;
76181 #if SQLITE_MAX_COLUMN
76182   if( pOrderBy->nExpr>db->aLimit[SQLITE_LIMIT_COLUMN] ){
76183     sqlite3ErrorMsg(pParse, "too many terms in %s BY clause", zType);
76184     return 1;
76185   }
76186 #endif
76187   pEList = pSelect->pEList;
76188   assert( pEList!=0 );  /* sqlite3SelectNew() guarantees this */
76189   for(i=0, pItem=pOrderBy->a; i<pOrderBy->nExpr; i++, pItem++){
76190     if( pItem->u.x.iOrderByCol ){
76191       if( pItem->u.x.iOrderByCol>pEList->nExpr ){
76192         resolveOutOfRangeError(pParse, zType, i+1, pEList->nExpr);
76193         return 1;
76194       }
76195       resolveAlias(pParse, pEList, pItem->u.x.iOrderByCol-1, pItem->pExpr, zType,0);
76196     }
76197   }
76198   return 0;
76199 }
76200 
76201 /*
76202 ** pOrderBy is an ORDER BY or GROUP BY clause in SELECT statement pSelect.
76203 ** The Name context of the SELECT statement is pNC.  zType is either
76204 ** "ORDER" or "GROUP" depending on which type of clause pOrderBy is.
76205 **
76206 ** This routine resolves each term of the clause into an expression.
76207 ** If the order-by term is an integer I between 1 and N (where N is the
76208 ** number of columns in the result set of the SELECT) then the expression
76209 ** in the resolution is a copy of the I-th result-set expression.  If
76210 ** the order-by term is an identifier that corresponds to the AS-name of
76211 ** a result-set expression, then the term resolves to a copy of the
76212 ** result-set expression.  Otherwise, the expression is resolved in
76213 ** the usual way - using sqlite3ResolveExprNames().
76214 **
76215 ** This routine returns the number of errors.  If errors occur, then
76216 ** an appropriate error message might be left in pParse.  (OOM errors
76217 ** excepted.)
76218 */
76219 static int resolveOrderGroupBy(
76220   NameContext *pNC,     /* The name context of the SELECT statement */
76221   Select *pSelect,      /* The SELECT statement holding pOrderBy */
76222   ExprList *pOrderBy,   /* An ORDER BY or GROUP BY clause to resolve */
76223   const char *zType     /* Either "ORDER" or "GROUP", as appropriate */
76224 ){
76225   int i, j;                      /* Loop counters */
76226   int iCol;                      /* Column number */
76227   struct ExprList_item *pItem;   /* A term of the ORDER BY clause */
76228   Parse *pParse;                 /* Parsing context */
76229   int nResult;                   /* Number of terms in the result set */
76230 
76231   if( pOrderBy==0 ) return 0;
76232   nResult = pSelect->pEList->nExpr;
76233   pParse = pNC->pParse;
76234   for(i=0, pItem=pOrderBy->a; i<pOrderBy->nExpr; i++, pItem++){
76235     Expr *pE = pItem->pExpr;
76236     Expr *pE2 = sqlite3ExprSkipCollate(pE);
76237     if( zType[0]!='G' ){
76238       iCol = resolveAsName(pParse, pSelect->pEList, pE2);
76239       if( iCol>0 ){
76240         /* If an AS-name match is found, mark this ORDER BY column as being
76241         ** a copy of the iCol-th result-set column.  The subsequent call to
76242         ** sqlite3ResolveOrderGroupBy() will convert the expression to a
76243         ** copy of the iCol-th result-set expression. */
76244         pItem->u.x.iOrderByCol = (u16)iCol;
76245         continue;
76246       }
76247     }
76248     if( sqlite3ExprIsInteger(pE2, &iCol) ){
76249       /* The ORDER BY term is an integer constant.  Again, set the column
76250       ** number so that sqlite3ResolveOrderGroupBy() will convert the
76251       ** order-by term to a copy of the result-set expression */
76252       if( iCol<1 || iCol>0xffff ){
76253         resolveOutOfRangeError(pParse, zType, i+1, nResult);
76254         return 1;
76255       }
76256       pItem->u.x.iOrderByCol = (u16)iCol;
76257       continue;
76258     }
76259 
76260     /* Otherwise, treat the ORDER BY term as an ordinary expression */
76261     pItem->u.x.iOrderByCol = 0;
76262     if( sqlite3ResolveExprNames(pNC, pE) ){
76263       return 1;
76264     }
76265     for(j=0; j<pSelect->pEList->nExpr; j++){
76266       if( sqlite3ExprCompare(pE, pSelect->pEList->a[j].pExpr, -1)==0 ){
76267         pItem->u.x.iOrderByCol = j+1;
76268       }
76269     }
76270   }
76271   return sqlite3ResolveOrderGroupBy(pParse, pSelect, pOrderBy, zType);
76272 }
76273 
76274 /*
76275 ** Resolve names in the SELECT statement p and all of its descendents.
76276 */
76277 static int resolveSelectStep(Walker *pWalker, Select *p){
76278   NameContext *pOuterNC;  /* Context that contains this SELECT */
76279   NameContext sNC;        /* Name context of this SELECT */
76280   int isCompound;         /* True if p is a compound select */
76281   int nCompound;          /* Number of compound terms processed so far */
76282   Parse *pParse;          /* Parsing context */
76283   ExprList *pEList;       /* Result set expression list */
76284   int i;                  /* Loop counter */
76285   ExprList *pGroupBy;     /* The GROUP BY clause */
76286   Select *pLeftmost;      /* Left-most of SELECT of a compound */
76287   sqlite3 *db;            /* Database connection */
76288   
76289 
76290   assert( p!=0 );
76291   if( p->selFlags & SF_Resolved ){
76292     return WRC_Prune;
76293   }
76294   pOuterNC = pWalker->u.pNC;
76295   pParse = pWalker->pParse;
76296   db = pParse->db;
76297 
76298   /* Normally sqlite3SelectExpand() will be called first and will have
76299   ** already expanded this SELECT.  However, if this is a subquery within
76300   ** an expression, sqlite3ResolveExprNames() will be called without a
76301   ** prior call to sqlite3SelectExpand().  When that happens, let
76302   ** sqlite3SelectPrep() do all of the processing for this SELECT.
76303   ** sqlite3SelectPrep() will invoke both sqlite3SelectExpand() and
76304   ** this routine in the correct order.
76305   */
76306   if( (p->selFlags & SF_Expanded)==0 ){
76307     sqlite3SelectPrep(pParse, p, pOuterNC);
76308     return (pParse->nErr || db->mallocFailed) ? WRC_Abort : WRC_Prune;
76309   }
76310 
76311   isCompound = p->pPrior!=0;
76312   nCompound = 0;
76313   pLeftmost = p;
76314   while( p ){
76315     assert( (p->selFlags & SF_Expanded)!=0 );
76316     assert( (p->selFlags & SF_Resolved)==0 );
76317     p->selFlags |= SF_Resolved;
76318 
76319     /* Resolve the expressions in the LIMIT and OFFSET clauses. These
76320     ** are not allowed to refer to any names, so pass an empty NameContext.
76321     */
76322     memset(&sNC, 0, sizeof(sNC));
76323     sNC.pParse = pParse;
76324     if( sqlite3ResolveExprNames(&sNC, p->pLimit) ||
76325         sqlite3ResolveExprNames(&sNC, p->pOffset) ){
76326       return WRC_Abort;
76327     }
76328   
76329     /* Recursively resolve names in all subqueries
76330     */
76331     for(i=0; i<p->pSrc->nSrc; i++){
76332       struct SrcList_item *pItem = &p->pSrc->a[i];
76333       if( pItem->pSelect ){
76334         NameContext *pNC;         /* Used to iterate name contexts */
76335         int nRef = 0;             /* Refcount for pOuterNC and outer contexts */
76336         const char *zSavedContext = pParse->zAuthContext;
76337 
76338         /* Count the total number of references to pOuterNC and all of its
76339         ** parent contexts. After resolving references to expressions in
76340         ** pItem->pSelect, check if this value has changed. If so, then
76341         ** SELECT statement pItem->pSelect must be correlated. Set the
76342         ** pItem->isCorrelated flag if this is the case. */
76343         for(pNC=pOuterNC; pNC; pNC=pNC->pNext) nRef += pNC->nRef;
76344 
76345         if( pItem->zName ) pParse->zAuthContext = pItem->zName;
76346         sqlite3ResolveSelectNames(pParse, pItem->pSelect, pOuterNC);
76347         pParse->zAuthContext = zSavedContext;
76348         if( pParse->nErr || db->mallocFailed ) return WRC_Abort;
76349 
76350         for(pNC=pOuterNC; pNC; pNC=pNC->pNext) nRef -= pNC->nRef;
76351         assert( pItem->isCorrelated==0 && nRef<=0 );
76352         pItem->isCorrelated = (nRef!=0);
76353       }
76354     }
76355   
76356     /* Set up the local name-context to pass to sqlite3ResolveExprNames() to
76357     ** resolve the result-set expression list.
76358     */
76359     sNC.ncFlags = NC_AllowAgg;
76360     sNC.pSrcList = p->pSrc;
76361     sNC.pNext = pOuterNC;
76362   
76363     /* Resolve names in the result set. */
76364     pEList = p->pEList;
76365     assert( pEList!=0 );
76366     for(i=0; i<pEList->nExpr; i++){
76367       Expr *pX = pEList->a[i].pExpr;
76368       if( sqlite3ResolveExprNames(&sNC, pX) ){
76369         return WRC_Abort;
76370       }
76371     }
76372   
76373     /* If there are no aggregate functions in the result-set, and no GROUP BY 
76374     ** expression, do not allow aggregates in any of the other expressions.
76375     */
76376     assert( (p->selFlags & SF_Aggregate)==0 );
76377     pGroupBy = p->pGroupBy;
76378     if( pGroupBy || (sNC.ncFlags & NC_HasAgg)!=0 ){
76379       p->selFlags |= SF_Aggregate;
76380     }else{
76381       sNC.ncFlags &= ~NC_AllowAgg;
76382     }
76383   
76384     /* If a HAVING clause is present, then there must be a GROUP BY clause.
76385     */
76386     if( p->pHaving && !pGroupBy ){
76387       sqlite3ErrorMsg(pParse, "a GROUP BY clause is required before HAVING");
76388       return WRC_Abort;
76389     }
76390   
76391     /* Add the output column list to the name-context before parsing the
76392     ** other expressions in the SELECT statement. This is so that
76393     ** expressions in the WHERE clause (etc.) can refer to expressions by
76394     ** aliases in the result set.
76395     **
76396     ** Minor point: If this is the case, then the expression will be
76397     ** re-evaluated for each reference to it.
76398     */
76399     sNC.pEList = p->pEList;
76400     if( sqlite3ResolveExprNames(&sNC, p->pHaving) ) return WRC_Abort;
76401     if( sqlite3ResolveExprNames(&sNC, p->pWhere) ) return WRC_Abort;
76402 
76403     /* The ORDER BY and GROUP BY clauses may not refer to terms in
76404     ** outer queries 
76405     */
76406     sNC.pNext = 0;
76407     sNC.ncFlags |= NC_AllowAgg;
76408 
76409     /* Process the ORDER BY clause for singleton SELECT statements.
76410     ** The ORDER BY clause for compounds SELECT statements is handled
76411     ** below, after all of the result-sets for all of the elements of
76412     ** the compound have been resolved.
76413     */
76414     if( !isCompound && resolveOrderGroupBy(&sNC, p, p->pOrderBy, "ORDER") ){
76415       return WRC_Abort;
76416     }
76417     if( db->mallocFailed ){
76418       return WRC_Abort;
76419     }
76420   
76421     /* Resolve the GROUP BY clause.  At the same time, make sure 
76422     ** the GROUP BY clause does not contain aggregate functions.
76423     */
76424     if( pGroupBy ){
76425       struct ExprList_item *pItem;
76426     
76427       if( resolveOrderGroupBy(&sNC, p, pGroupBy, "GROUP") || db->mallocFailed ){
76428         return WRC_Abort;
76429       }
76430       for(i=0, pItem=pGroupBy->a; i<pGroupBy->nExpr; i++, pItem++){
76431         if( ExprHasProperty(pItem->pExpr, EP_Agg) ){
76432           sqlite3ErrorMsg(pParse, "aggregate functions are not allowed in "
76433               "the GROUP BY clause");
76434           return WRC_Abort;
76435         }
76436       }
76437     }
76438 
76439     /* Advance to the next term of the compound
76440     */
76441     p = p->pPrior;
76442     nCompound++;
76443   }
76444 
76445   /* Resolve the ORDER BY on a compound SELECT after all terms of
76446   ** the compound have been resolved.
76447   */
76448   if( isCompound && resolveCompoundOrderBy(pParse, pLeftmost) ){
76449     return WRC_Abort;
76450   }
76451 
76452   return WRC_Prune;
76453 }
76454 
76455 /*
76456 ** This routine walks an expression tree and resolves references to
76457 ** table columns and result-set columns.  At the same time, do error
76458 ** checking on function usage and set a flag if any aggregate functions
76459 ** are seen.
76460 **
76461 ** To resolve table columns references we look for nodes (or subtrees) of the 
76462 ** form X.Y.Z or Y.Z or just Z where
76463 **
76464 **      X:   The name of a database.  Ex:  "main" or "temp" or
76465 **           the symbolic name assigned to an ATTACH-ed database.
76466 **
76467 **      Y:   The name of a table in a FROM clause.  Or in a trigger
76468 **           one of the special names "old" or "new".
76469 **
76470 **      Z:   The name of a column in table Y.
76471 **
76472 ** The node at the root of the subtree is modified as follows:
76473 **
76474 **    Expr.op        Changed to TK_COLUMN
76475 **    Expr.pTab      Points to the Table object for X.Y
76476 **    Expr.iColumn   The column index in X.Y.  -1 for the rowid.
76477 **    Expr.iTable    The VDBE cursor number for X.Y
76478 **
76479 **
76480 ** To resolve result-set references, look for expression nodes of the
76481 ** form Z (with no X and Y prefix) where the Z matches the right-hand
76482 ** size of an AS clause in the result-set of a SELECT.  The Z expression
76483 ** is replaced by a copy of the left-hand side of the result-set expression.
76484 ** Table-name and function resolution occurs on the substituted expression
76485 ** tree.  For example, in:
76486 **
76487 **      SELECT a+b AS x, c+d AS y FROM t1 ORDER BY x;
76488 **
76489 ** The "x" term of the order by is replaced by "a+b" to render:
76490 **
76491 **      SELECT a+b AS x, c+d AS y FROM t1 ORDER BY a+b;
76492 **
76493 ** Function calls are checked to make sure that the function is 
76494 ** defined and that the correct number of arguments are specified.
76495 ** If the function is an aggregate function, then the NC_HasAgg flag is
76496 ** set and the opcode is changed from TK_FUNCTION to TK_AGG_FUNCTION.
76497 ** If an expression contains aggregate functions then the EP_Agg
76498 ** property on the expression is set.
76499 **
76500 ** An error message is left in pParse if anything is amiss.  The number
76501 ** if errors is returned.
76502 */
76503 SQLITE_PRIVATE int sqlite3ResolveExprNames( 
76504   NameContext *pNC,       /* Namespace to resolve expressions in. */
76505   Expr *pExpr             /* The expression to be analyzed. */
76506 ){
76507   u8 savedHasAgg;
76508   Walker w;
76509 
76510   if( pExpr==0 ) return 0;
76511 #if SQLITE_MAX_EXPR_DEPTH>0
76512   {
76513     Parse *pParse = pNC->pParse;
76514     if( sqlite3ExprCheckHeight(pParse, pExpr->nHeight+pNC->pParse->nHeight) ){
76515       return 1;
76516     }
76517     pParse->nHeight += pExpr->nHeight;
76518   }
76519 #endif
76520   savedHasAgg = pNC->ncFlags & NC_HasAgg;
76521   pNC->ncFlags &= ~NC_HasAgg;
76522   memset(&w, 0, sizeof(w));
76523   w.xExprCallback = resolveExprStep;
76524   w.xSelectCallback = resolveSelectStep;
76525   w.pParse = pNC->pParse;
76526   w.u.pNC = pNC;
76527   sqlite3WalkExpr(&w, pExpr);
76528 #if SQLITE_MAX_EXPR_DEPTH>0
76529   pNC->pParse->nHeight -= pExpr->nHeight;
76530 #endif
76531   if( pNC->nErr>0 || w.pParse->nErr>0 ){
76532     ExprSetProperty(pExpr, EP_Error);
76533   }
76534   if( pNC->ncFlags & NC_HasAgg ){
76535     ExprSetProperty(pExpr, EP_Agg);
76536   }else if( savedHasAgg ){
76537     pNC->ncFlags |= NC_HasAgg;
76538   }
76539   return ExprHasProperty(pExpr, EP_Error);
76540 }
76541 
76542 
76543 /*
76544 ** Resolve all names in all expressions of a SELECT and in all
76545 ** decendents of the SELECT, including compounds off of p->pPrior,
76546 ** subqueries in expressions, and subqueries used as FROM clause
76547 ** terms.
76548 **
76549 ** See sqlite3ResolveExprNames() for a description of the kinds of
76550 ** transformations that occur.
76551 **
76552 ** All SELECT statements should have been expanded using
76553 ** sqlite3SelectExpand() prior to invoking this routine.
76554 */
76555 SQLITE_PRIVATE void sqlite3ResolveSelectNames(
76556   Parse *pParse,         /* The parser context */
76557   Select *p,             /* The SELECT statement being coded. */
76558   NameContext *pOuterNC  /* Name context for parent SELECT statement */
76559 ){
76560   Walker w;
76561 
76562   assert( p!=0 );
76563   memset(&w, 0, sizeof(w));
76564   w.xExprCallback = resolveExprStep;
76565   w.xSelectCallback = resolveSelectStep;
76566   w.pParse = pParse;
76567   w.u.pNC = pOuterNC;
76568   sqlite3WalkSelect(&w, p);
76569 }
76570 
76571 /*
76572 ** Resolve names in expressions that can only reference a single table:
76573 **
76574 **    *   CHECK constraints
76575 **    *   WHERE clauses on partial indices
76576 **
76577 ** The Expr.iTable value for Expr.op==TK_COLUMN nodes of the expression
76578 ** is set to -1 and the Expr.iColumn value is set to the column number.
76579 **
76580 ** Any errors cause an error message to be set in pParse.
76581 */
76582 SQLITE_PRIVATE void sqlite3ResolveSelfReference(
76583   Parse *pParse,      /* Parsing context */
76584   Table *pTab,        /* The table being referenced */
76585   int type,           /* NC_IsCheck or NC_PartIdx */
76586   Expr *pExpr,        /* Expression to resolve.  May be NULL. */
76587   ExprList *pList     /* Expression list to resolve.  May be NUL. */
76588 ){
76589   SrcList sSrc;                   /* Fake SrcList for pParse->pNewTable */
76590   NameContext sNC;                /* Name context for pParse->pNewTable */
76591   int i;                          /* Loop counter */
76592 
76593   assert( type==NC_IsCheck || type==NC_PartIdx );
76594   memset(&sNC, 0, sizeof(sNC));
76595   memset(&sSrc, 0, sizeof(sSrc));
76596   sSrc.nSrc = 1;
76597   sSrc.a[0].zName = pTab->zName;
76598   sSrc.a[0].pTab = pTab;
76599   sSrc.a[0].iCursor = -1;
76600   sNC.pParse = pParse;
76601   sNC.pSrcList = &sSrc;
76602   sNC.ncFlags = type;
76603   if( sqlite3ResolveExprNames(&sNC, pExpr) ) return;
76604   if( pList ){
76605     for(i=0; i<pList->nExpr; i++){
76606       if( sqlite3ResolveExprNames(&sNC, pList->a[i].pExpr) ){
76607         return;
76608       }
76609     }
76610   }
76611 }
76612 
76613 /************** End of resolve.c *********************************************/
76614 /************** Begin file expr.c ********************************************/
76615 /*
76616 ** 2001 September 15
76617 **
76618 ** The author disclaims copyright to this source code.  In place of
76619 ** a legal notice, here is a blessing:
76620 **
76621 **    May you do good and not evil.
76622 **    May you find forgiveness for yourself and forgive others.
76623 **    May you share freely, never taking more than you give.
76624 **
76625 *************************************************************************
76626 ** This file contains routines used for analyzing expressions and
76627 ** for generating VDBE code that evaluates expressions in SQLite.
76628 */
76629 
76630 /*
76631 ** Return the 'affinity' of the expression pExpr if any.
76632 **
76633 ** If pExpr is a column, a reference to a column via an 'AS' alias,
76634 ** or a sub-select with a column as the return value, then the 
76635 ** affinity of that column is returned. Otherwise, 0x00 is returned,
76636 ** indicating no affinity for the expression.
76637 **
76638 ** i.e. the WHERE clause expresssions in the following statements all
76639 ** have an affinity:
76640 **
76641 ** CREATE TABLE t1(a);
76642 ** SELECT * FROM t1 WHERE a;
76643 ** SELECT a AS b FROM t1 WHERE b;
76644 ** SELECT * FROM t1 WHERE (select a from t1);
76645 */
76646 SQLITE_PRIVATE char sqlite3ExprAffinity(Expr *pExpr){
76647   int op;
76648   pExpr = sqlite3ExprSkipCollate(pExpr);
76649   op = pExpr->op;
76650   if( op==TK_SELECT ){
76651     assert( pExpr->flags&EP_xIsSelect );
76652     return sqlite3ExprAffinity(pExpr->x.pSelect->pEList->a[0].pExpr);
76653   }
76654 #ifndef SQLITE_OMIT_CAST
76655   if( op==TK_CAST ){
76656     assert( !ExprHasProperty(pExpr, EP_IntValue) );
76657     return sqlite3AffinityType(pExpr->u.zToken, 0);
76658   }
76659 #endif
76660   if( (op==TK_AGG_COLUMN || op==TK_COLUMN || op==TK_REGISTER) 
76661    && pExpr->pTab!=0
76662   ){
76663     /* op==TK_REGISTER && pExpr->pTab!=0 happens when pExpr was originally
76664     ** a TK_COLUMN but was previously evaluated and cached in a register */
76665     int j = pExpr->iColumn;
76666     if( j<0 ) return SQLITE_AFF_INTEGER;
76667     assert( pExpr->pTab && j<pExpr->pTab->nCol );
76668     return pExpr->pTab->aCol[j].affinity;
76669   }
76670   return pExpr->affinity;
76671 }
76672 
76673 /*
76674 ** Set the collating sequence for expression pExpr to be the collating
76675 ** sequence named by pToken.   Return a pointer to a new Expr node that
76676 ** implements the COLLATE operator.
76677 **
76678 ** If a memory allocation error occurs, that fact is recorded in pParse->db
76679 ** and the pExpr parameter is returned unchanged.
76680 */
76681 SQLITE_PRIVATE Expr *sqlite3ExprAddCollateToken(Parse *pParse, Expr *pExpr, Token *pCollName){
76682   if( pCollName->n>0 ){
76683     Expr *pNew = sqlite3ExprAlloc(pParse->db, TK_COLLATE, pCollName, 1);
76684     if( pNew ){
76685       pNew->pLeft = pExpr;
76686       pNew->flags |= EP_Collate|EP_Skip;
76687       pExpr = pNew;
76688     }
76689   }
76690   return pExpr;
76691 }
76692 SQLITE_PRIVATE Expr *sqlite3ExprAddCollateString(Parse *pParse, Expr *pExpr, const char *zC){
76693   Token s;
76694   assert( zC!=0 );
76695   s.z = zC;
76696   s.n = sqlite3Strlen30(s.z);
76697   return sqlite3ExprAddCollateToken(pParse, pExpr, &s);
76698 }
76699 
76700 /*
76701 ** Skip over any TK_COLLATE or TK_AS operators and any unlikely()
76702 ** or likelihood() function at the root of an expression.
76703 */
76704 SQLITE_PRIVATE Expr *sqlite3ExprSkipCollate(Expr *pExpr){
76705   while( pExpr && ExprHasProperty(pExpr, EP_Skip) ){
76706     if( ExprHasProperty(pExpr, EP_Unlikely) ){
76707       assert( !ExprHasProperty(pExpr, EP_xIsSelect) );
76708       assert( pExpr->x.pList->nExpr>0 );
76709       assert( pExpr->op==TK_FUNCTION );
76710       pExpr = pExpr->x.pList->a[0].pExpr;
76711     }else{
76712       assert( pExpr->op==TK_COLLATE || pExpr->op==TK_AS );
76713       pExpr = pExpr->pLeft;
76714     }
76715   }   
76716   return pExpr;
76717 }
76718 
76719 /*
76720 ** Return the collation sequence for the expression pExpr. If
76721 ** there is no defined collating sequence, return NULL.
76722 **
76723 ** The collating sequence might be determined by a COLLATE operator
76724 ** or by the presence of a column with a defined collating sequence.
76725 ** COLLATE operators take first precedence.  Left operands take
76726 ** precedence over right operands.
76727 */
76728 SQLITE_PRIVATE CollSeq *sqlite3ExprCollSeq(Parse *pParse, Expr *pExpr){
76729   sqlite3 *db = pParse->db;
76730   CollSeq *pColl = 0;
76731   Expr *p = pExpr;
76732   while( p ){
76733     int op = p->op;
76734     if( op==TK_CAST || op==TK_UPLUS ){
76735       p = p->pLeft;
76736       continue;
76737     }
76738     if( op==TK_COLLATE || (op==TK_REGISTER && p->op2==TK_COLLATE) ){
76739       pColl = sqlite3GetCollSeq(pParse, ENC(db), 0, p->u.zToken);
76740       break;
76741     }
76742     if( p->pTab!=0
76743      && (op==TK_AGG_COLUMN || op==TK_COLUMN
76744           || op==TK_REGISTER || op==TK_TRIGGER)
76745     ){
76746       /* op==TK_REGISTER && p->pTab!=0 happens when pExpr was originally
76747       ** a TK_COLUMN but was previously evaluated and cached in a register */
76748       int j = p->iColumn;
76749       if( j>=0 ){
76750         const char *zColl = p->pTab->aCol[j].zColl;
76751         pColl = sqlite3FindCollSeq(db, ENC(db), zColl, 0);
76752       }
76753       break;
76754     }
76755     if( p->flags & EP_Collate ){
76756       if( ALWAYS(p->pLeft) && (p->pLeft->flags & EP_Collate)!=0 ){
76757         p = p->pLeft;
76758       }else{
76759         p = p->pRight;
76760       }
76761     }else{
76762       break;
76763     }
76764   }
76765   if( sqlite3CheckCollSeq(pParse, pColl) ){ 
76766     pColl = 0;
76767   }
76768   return pColl;
76769 }
76770 
76771 /*
76772 ** pExpr is an operand of a comparison operator.  aff2 is the
76773 ** type affinity of the other operand.  This routine returns the
76774 ** type affinity that should be used for the comparison operator.
76775 */
76776 SQLITE_PRIVATE char sqlite3CompareAffinity(Expr *pExpr, char aff2){
76777   char aff1 = sqlite3ExprAffinity(pExpr);
76778   if( aff1 && aff2 ){
76779     /* Both sides of the comparison are columns. If one has numeric
76780     ** affinity, use that. Otherwise use no affinity.
76781     */
76782     if( sqlite3IsNumericAffinity(aff1) || sqlite3IsNumericAffinity(aff2) ){
76783       return SQLITE_AFF_NUMERIC;
76784     }else{
76785       return SQLITE_AFF_NONE;
76786     }
76787   }else if( !aff1 && !aff2 ){
76788     /* Neither side of the comparison is a column.  Compare the
76789     ** results directly.
76790     */
76791     return SQLITE_AFF_NONE;
76792   }else{
76793     /* One side is a column, the other is not. Use the columns affinity. */
76794     assert( aff1==0 || aff2==0 );
76795     return (aff1 + aff2);
76796   }
76797 }
76798 
76799 /*
76800 ** pExpr is a comparison operator.  Return the type affinity that should
76801 ** be applied to both operands prior to doing the comparison.
76802 */
76803 static char comparisonAffinity(Expr *pExpr){
76804   char aff;
76805   assert( pExpr->op==TK_EQ || pExpr->op==TK_IN || pExpr->op==TK_LT ||
76806           pExpr->op==TK_GT || pExpr->op==TK_GE || pExpr->op==TK_LE ||
76807           pExpr->op==TK_NE || pExpr->op==TK_IS || pExpr->op==TK_ISNOT );
76808   assert( pExpr->pLeft );
76809   aff = sqlite3ExprAffinity(pExpr->pLeft);
76810   if( pExpr->pRight ){
76811     aff = sqlite3CompareAffinity(pExpr->pRight, aff);
76812   }else if( ExprHasProperty(pExpr, EP_xIsSelect) ){
76813     aff = sqlite3CompareAffinity(pExpr->x.pSelect->pEList->a[0].pExpr, aff);
76814   }else if( !aff ){
76815     aff = SQLITE_AFF_NONE;
76816   }
76817   return aff;
76818 }
76819 
76820 /*
76821 ** pExpr is a comparison expression, eg. '=', '<', IN(...) etc.
76822 ** idx_affinity is the affinity of an indexed column. Return true
76823 ** if the index with affinity idx_affinity may be used to implement
76824 ** the comparison in pExpr.
76825 */
76826 SQLITE_PRIVATE int sqlite3IndexAffinityOk(Expr *pExpr, char idx_affinity){
76827   char aff = comparisonAffinity(pExpr);
76828   switch( aff ){
76829     case SQLITE_AFF_NONE:
76830       return 1;
76831     case SQLITE_AFF_TEXT:
76832       return idx_affinity==SQLITE_AFF_TEXT;
76833     default:
76834       return sqlite3IsNumericAffinity(idx_affinity);
76835   }
76836 }
76837 
76838 /*
76839 ** Return the P5 value that should be used for a binary comparison
76840 ** opcode (OP_Eq, OP_Ge etc.) used to compare pExpr1 and pExpr2.
76841 */
76842 static u8 binaryCompareP5(Expr *pExpr1, Expr *pExpr2, int jumpIfNull){
76843   u8 aff = (char)sqlite3ExprAffinity(pExpr2);
76844   aff = (u8)sqlite3CompareAffinity(pExpr1, aff) | (u8)jumpIfNull;
76845   return aff;
76846 }
76847 
76848 /*
76849 ** Return a pointer to the collation sequence that should be used by
76850 ** a binary comparison operator comparing pLeft and pRight.
76851 **
76852 ** If the left hand expression has a collating sequence type, then it is
76853 ** used. Otherwise the collation sequence for the right hand expression
76854 ** is used, or the default (BINARY) if neither expression has a collating
76855 ** type.
76856 **
76857 ** Argument pRight (but not pLeft) may be a null pointer. In this case,
76858 ** it is not considered.
76859 */
76860 SQLITE_PRIVATE CollSeq *sqlite3BinaryCompareCollSeq(
76861   Parse *pParse, 
76862   Expr *pLeft, 
76863   Expr *pRight
76864 ){
76865   CollSeq *pColl;
76866   assert( pLeft );
76867   if( pLeft->flags & EP_Collate ){
76868     pColl = sqlite3ExprCollSeq(pParse, pLeft);
76869   }else if( pRight && (pRight->flags & EP_Collate)!=0 ){
76870     pColl = sqlite3ExprCollSeq(pParse, pRight);
76871   }else{
76872     pColl = sqlite3ExprCollSeq(pParse, pLeft);
76873     if( !pColl ){
76874       pColl = sqlite3ExprCollSeq(pParse, pRight);
76875     }
76876   }
76877   return pColl;
76878 }
76879 
76880 /*
76881 ** Generate code for a comparison operator.
76882 */
76883 static int codeCompare(
76884   Parse *pParse,    /* The parsing (and code generating) context */
76885   Expr *pLeft,      /* The left operand */
76886   Expr *pRight,     /* The right operand */
76887   int opcode,       /* The comparison opcode */
76888   int in1, int in2, /* Register holding operands */
76889   int dest,         /* Jump here if true.  */
76890   int jumpIfNull    /* If true, jump if either operand is NULL */
76891 ){
76892   int p5;
76893   int addr;
76894   CollSeq *p4;
76895 
76896   p4 = sqlite3BinaryCompareCollSeq(pParse, pLeft, pRight);
76897   p5 = binaryCompareP5(pLeft, pRight, jumpIfNull);
76898   addr = sqlite3VdbeAddOp4(pParse->pVdbe, opcode, in2, dest, in1,
76899                            (void*)p4, P4_COLLSEQ);
76900   sqlite3VdbeChangeP5(pParse->pVdbe, (u8)p5);
76901   return addr;
76902 }
76903 
76904 #if SQLITE_MAX_EXPR_DEPTH>0
76905 /*
76906 ** Check that argument nHeight is less than or equal to the maximum
76907 ** expression depth allowed. If it is not, leave an error message in
76908 ** pParse.
76909 */
76910 SQLITE_PRIVATE int sqlite3ExprCheckHeight(Parse *pParse, int nHeight){
76911   int rc = SQLITE_OK;
76912   int mxHeight = pParse->db->aLimit[SQLITE_LIMIT_EXPR_DEPTH];
76913   if( nHeight>mxHeight ){
76914     sqlite3ErrorMsg(pParse, 
76915        "Expression tree is too large (maximum depth %d)", mxHeight
76916     );
76917     rc = SQLITE_ERROR;
76918   }
76919   return rc;
76920 }
76921 
76922 /* The following three functions, heightOfExpr(), heightOfExprList()
76923 ** and heightOfSelect(), are used to determine the maximum height
76924 ** of any expression tree referenced by the structure passed as the
76925 ** first argument.
76926 **
76927 ** If this maximum height is greater than the current value pointed
76928 ** to by pnHeight, the second parameter, then set *pnHeight to that
76929 ** value.
76930 */
76931 static void heightOfExpr(Expr *p, int *pnHeight){
76932   if( p ){
76933     if( p->nHeight>*pnHeight ){
76934       *pnHeight = p->nHeight;
76935     }
76936   }
76937 }
76938 static void heightOfExprList(ExprList *p, int *pnHeight){
76939   if( p ){
76940     int i;
76941     for(i=0; i<p->nExpr; i++){
76942       heightOfExpr(p->a[i].pExpr, pnHeight);
76943     }
76944   }
76945 }
76946 static void heightOfSelect(Select *p, int *pnHeight){
76947   if( p ){
76948     heightOfExpr(p->pWhere, pnHeight);
76949     heightOfExpr(p->pHaving, pnHeight);
76950     heightOfExpr(p->pLimit, pnHeight);
76951     heightOfExpr(p->pOffset, pnHeight);
76952     heightOfExprList(p->pEList, pnHeight);
76953     heightOfExprList(p->pGroupBy, pnHeight);
76954     heightOfExprList(p->pOrderBy, pnHeight);
76955     heightOfSelect(p->pPrior, pnHeight);
76956   }
76957 }
76958 
76959 /*
76960 ** Set the Expr.nHeight variable in the structure passed as an 
76961 ** argument. An expression with no children, Expr.pList or 
76962 ** Expr.pSelect member has a height of 1. Any other expression
76963 ** has a height equal to the maximum height of any other 
76964 ** referenced Expr plus one.
76965 */
76966 static void exprSetHeight(Expr *p){
76967   int nHeight = 0;
76968   heightOfExpr(p->pLeft, &nHeight);
76969   heightOfExpr(p->pRight, &nHeight);
76970   if( ExprHasProperty(p, EP_xIsSelect) ){
76971     heightOfSelect(p->x.pSelect, &nHeight);
76972   }else{
76973     heightOfExprList(p->x.pList, &nHeight);
76974   }
76975   p->nHeight = nHeight + 1;
76976 }
76977 
76978 /*
76979 ** Set the Expr.nHeight variable using the exprSetHeight() function. If
76980 ** the height is greater than the maximum allowed expression depth,
76981 ** leave an error in pParse.
76982 */
76983 SQLITE_PRIVATE void sqlite3ExprSetHeight(Parse *pParse, Expr *p){
76984   exprSetHeight(p);
76985   sqlite3ExprCheckHeight(pParse, p->nHeight);
76986 }
76987 
76988 /*
76989 ** Return the maximum height of any expression tree referenced
76990 ** by the select statement passed as an argument.
76991 */
76992 SQLITE_PRIVATE int sqlite3SelectExprHeight(Select *p){
76993   int nHeight = 0;
76994   heightOfSelect(p, &nHeight);
76995   return nHeight;
76996 }
76997 #else
76998   #define exprSetHeight(y)
76999 #endif /* SQLITE_MAX_EXPR_DEPTH>0 */
77000 
77001 /*
77002 ** This routine is the core allocator for Expr nodes.
77003 **
77004 ** Construct a new expression node and return a pointer to it.  Memory
77005 ** for this node and for the pToken argument is a single allocation
77006 ** obtained from sqlite3DbMalloc().  The calling function
77007 ** is responsible for making sure the node eventually gets freed.
77008 **
77009 ** If dequote is true, then the token (if it exists) is dequoted.
77010 ** If dequote is false, no dequoting is performance.  The deQuote
77011 ** parameter is ignored if pToken is NULL or if the token does not
77012 ** appear to be quoted.  If the quotes were of the form "..." (double-quotes)
77013 ** then the EP_DblQuoted flag is set on the expression node.
77014 **
77015 ** Special case:  If op==TK_INTEGER and pToken points to a string that
77016 ** can be translated into a 32-bit integer, then the token is not
77017 ** stored in u.zToken.  Instead, the integer values is written
77018 ** into u.iValue and the EP_IntValue flag is set.  No extra storage
77019 ** is allocated to hold the integer text and the dequote flag is ignored.
77020 */
77021 SQLITE_PRIVATE Expr *sqlite3ExprAlloc(
77022   sqlite3 *db,            /* Handle for sqlite3DbMallocZero() (may be null) */
77023   int op,                 /* Expression opcode */
77024   const Token *pToken,    /* Token argument.  Might be NULL */
77025   int dequote             /* True to dequote */
77026 ){
77027   Expr *pNew;
77028   int nExtra = 0;
77029   int iValue = 0;
77030 
77031   if( pToken ){
77032     if( op!=TK_INTEGER || pToken->z==0
77033           || sqlite3GetInt32(pToken->z, &iValue)==0 ){
77034       nExtra = pToken->n+1;
77035       assert( iValue>=0 );
77036     }
77037   }
77038   pNew = sqlite3DbMallocZero(db, sizeof(Expr)+nExtra);
77039   if( pNew ){
77040     pNew->op = (u8)op;
77041     pNew->iAgg = -1;
77042     if( pToken ){
77043       if( nExtra==0 ){
77044         pNew->flags |= EP_IntValue;
77045         pNew->u.iValue = iValue;
77046       }else{
77047         int c;
77048         pNew->u.zToken = (char*)&pNew[1];
77049         assert( pToken->z!=0 || pToken->n==0 );
77050         if( pToken->n ) memcpy(pNew->u.zToken, pToken->z, pToken->n);
77051         pNew->u.zToken[pToken->n] = 0;
77052         if( dequote && nExtra>=3 
77053              && ((c = pToken->z[0])=='\'' || c=='"' || c=='[' || c=='`') ){
77054           sqlite3Dequote(pNew->u.zToken);
77055           if( c=='"' ) pNew->flags |= EP_DblQuoted;
77056         }
77057       }
77058     }
77059 #if SQLITE_MAX_EXPR_DEPTH>0
77060     pNew->nHeight = 1;
77061 #endif  
77062   }
77063   return pNew;
77064 }
77065 
77066 /*
77067 ** Allocate a new expression node from a zero-terminated token that has
77068 ** already been dequoted.
77069 */
77070 SQLITE_PRIVATE Expr *sqlite3Expr(
77071   sqlite3 *db,            /* Handle for sqlite3DbMallocZero() (may be null) */
77072   int op,                 /* Expression opcode */
77073   const char *zToken      /* Token argument.  Might be NULL */
77074 ){
77075   Token x;
77076   x.z = zToken;
77077   x.n = zToken ? sqlite3Strlen30(zToken) : 0;
77078   return sqlite3ExprAlloc(db, op, &x, 0);
77079 }
77080 
77081 /*
77082 ** Attach subtrees pLeft and pRight to the Expr node pRoot.
77083 **
77084 ** If pRoot==NULL that means that a memory allocation error has occurred.
77085 ** In that case, delete the subtrees pLeft and pRight.
77086 */
77087 SQLITE_PRIVATE void sqlite3ExprAttachSubtrees(
77088   sqlite3 *db,
77089   Expr *pRoot,
77090   Expr *pLeft,
77091   Expr *pRight
77092 ){
77093   if( pRoot==0 ){
77094     assert( db->mallocFailed );
77095     sqlite3ExprDelete(db, pLeft);
77096     sqlite3ExprDelete(db, pRight);
77097   }else{
77098     if( pRight ){
77099       pRoot->pRight = pRight;
77100       pRoot->flags |= EP_Collate & pRight->flags;
77101     }
77102     if( pLeft ){
77103       pRoot->pLeft = pLeft;
77104       pRoot->flags |= EP_Collate & pLeft->flags;
77105     }
77106     exprSetHeight(pRoot);
77107   }
77108 }
77109 
77110 /*
77111 ** Allocate a Expr node which joins as many as two subtrees.
77112 **
77113 ** One or both of the subtrees can be NULL.  Return a pointer to the new
77114 ** Expr node.  Or, if an OOM error occurs, set pParse->db->mallocFailed,
77115 ** free the subtrees and return NULL.
77116 */
77117 SQLITE_PRIVATE Expr *sqlite3PExpr(
77118   Parse *pParse,          /* Parsing context */
77119   int op,                 /* Expression opcode */
77120   Expr *pLeft,            /* Left operand */
77121   Expr *pRight,           /* Right operand */
77122   const Token *pToken     /* Argument token */
77123 ){
77124   Expr *p;
77125   if( op==TK_AND && pLeft && pRight ){
77126     /* Take advantage of short-circuit false optimization for AND */
77127     p = sqlite3ExprAnd(pParse->db, pLeft, pRight);
77128   }else{
77129     p = sqlite3ExprAlloc(pParse->db, op, pToken, 1);
77130     sqlite3ExprAttachSubtrees(pParse->db, p, pLeft, pRight);
77131   }
77132   if( p ) {
77133     sqlite3ExprCheckHeight(pParse, p->nHeight);
77134   }
77135   return p;
77136 }
77137 
77138 /*
77139 ** Return 1 if an expression must be FALSE in all cases and 0 if the
77140 ** expression might be true.  This is an optimization.  If is OK to
77141 ** return 0 here even if the expression really is always false (a 
77142 ** false negative).  But it is a bug to return 1 if the expression
77143 ** might be true in some rare circumstances (a false positive.)
77144 **
77145 ** Note that if the expression is part of conditional for a
77146 ** LEFT JOIN, then we cannot determine at compile-time whether or not
77147 ** is it true or false, so always return 0.
77148 */
77149 static int exprAlwaysFalse(Expr *p){
77150   int v = 0;
77151   if( ExprHasProperty(p, EP_FromJoin) ) return 0;
77152   if( !sqlite3ExprIsInteger(p, &v) ) return 0;
77153   return v==0;
77154 }
77155 
77156 /*
77157 ** Join two expressions using an AND operator.  If either expression is
77158 ** NULL, then just return the other expression.
77159 **
77160 ** If one side or the other of the AND is known to be false, then instead
77161 ** of returning an AND expression, just return a constant expression with
77162 ** a value of false.
77163 */
77164 SQLITE_PRIVATE Expr *sqlite3ExprAnd(sqlite3 *db, Expr *pLeft, Expr *pRight){
77165   if( pLeft==0 ){
77166     return pRight;
77167   }else if( pRight==0 ){
77168     return pLeft;
77169   }else if( exprAlwaysFalse(pLeft) || exprAlwaysFalse(pRight) ){
77170     sqlite3ExprDelete(db, pLeft);
77171     sqlite3ExprDelete(db, pRight);
77172     return sqlite3ExprAlloc(db, TK_INTEGER, &sqlite3IntTokens[0], 0);
77173   }else{
77174     Expr *pNew = sqlite3ExprAlloc(db, TK_AND, 0, 0);
77175     sqlite3ExprAttachSubtrees(db, pNew, pLeft, pRight);
77176     return pNew;
77177   }
77178 }
77179 
77180 /*
77181 ** Construct a new expression node for a function with multiple
77182 ** arguments.
77183 */
77184 SQLITE_PRIVATE Expr *sqlite3ExprFunction(Parse *pParse, ExprList *pList, Token *pToken){
77185   Expr *pNew;
77186   sqlite3 *db = pParse->db;
77187   assert( pToken );
77188   pNew = sqlite3ExprAlloc(db, TK_FUNCTION, pToken, 1);
77189   if( pNew==0 ){
77190     sqlite3ExprListDelete(db, pList); /* Avoid memory leak when malloc fails */
77191     return 0;
77192   }
77193   pNew->x.pList = pList;
77194   assert( !ExprHasProperty(pNew, EP_xIsSelect) );
77195   sqlite3ExprSetHeight(pParse, pNew);
77196   return pNew;
77197 }
77198 
77199 /*
77200 ** Assign a variable number to an expression that encodes a wildcard
77201 ** in the original SQL statement.  
77202 **
77203 ** Wildcards consisting of a single "?" are assigned the next sequential
77204 ** variable number.
77205 **
77206 ** Wildcards of the form "?nnn" are assigned the number "nnn".  We make
77207 ** sure "nnn" is not too be to avoid a denial of service attack when
77208 ** the SQL statement comes from an external source.
77209 **
77210 ** Wildcards of the form ":aaa", "@aaa", or "$aaa" are assigned the same number
77211 ** as the previous instance of the same wildcard.  Or if this is the first
77212 ** instance of the wildcard, the next sequenial variable number is
77213 ** assigned.
77214 */
77215 SQLITE_PRIVATE void sqlite3ExprAssignVarNumber(Parse *pParse, Expr *pExpr){
77216   sqlite3 *db = pParse->db;
77217   const char *z;
77218 
77219   if( pExpr==0 ) return;
77220   assert( !ExprHasProperty(pExpr, EP_IntValue|EP_Reduced|EP_TokenOnly) );
77221   z = pExpr->u.zToken;
77222   assert( z!=0 );
77223   assert( z[0]!=0 );
77224   if( z[1]==0 ){
77225     /* Wildcard of the form "?".  Assign the next variable number */
77226     assert( z[0]=='?' );
77227     pExpr->iColumn = (ynVar)(++pParse->nVar);
77228   }else{
77229     ynVar x = 0;
77230     u32 n = sqlite3Strlen30(z);
77231     if( z[0]=='?' ){
77232       /* Wildcard of the form "?nnn".  Convert "nnn" to an integer and
77233       ** use it as the variable number */
77234       i64 i;
77235       int bOk = 0==sqlite3Atoi64(&z[1], &i, n-1, SQLITE_UTF8);
77236       pExpr->iColumn = x = (ynVar)i;
77237       testcase( i==0 );
77238       testcase( i==1 );
77239       testcase( i==db->aLimit[SQLITE_LIMIT_VARIABLE_NUMBER]-1 );
77240       testcase( i==db->aLimit[SQLITE_LIMIT_VARIABLE_NUMBER] );
77241       if( bOk==0 || i<1 || i>db->aLimit[SQLITE_LIMIT_VARIABLE_NUMBER] ){
77242         sqlite3ErrorMsg(pParse, "variable number must be between ?1 and ?%d",
77243             db->aLimit[SQLITE_LIMIT_VARIABLE_NUMBER]);
77244         x = 0;
77245       }
77246       if( i>pParse->nVar ){
77247         pParse->nVar = (int)i;
77248       }
77249     }else{
77250       /* Wildcards like ":aaa", "$aaa" or "@aaa".  Reuse the same variable
77251       ** number as the prior appearance of the same name, or if the name
77252       ** has never appeared before, reuse the same variable number
77253       */
77254       ynVar i;
77255       for(i=0; i<pParse->nzVar; i++){
77256         if( pParse->azVar[i] && strcmp(pParse->azVar[i],z)==0 ){
77257           pExpr->iColumn = x = (ynVar)i+1;
77258           break;
77259         }
77260       }
77261       if( x==0 ) x = pExpr->iColumn = (ynVar)(++pParse->nVar);
77262     }
77263     if( x>0 ){
77264       if( x>pParse->nzVar ){
77265         char **a;
77266         a = sqlite3DbRealloc(db, pParse->azVar, x*sizeof(a[0]));
77267         if( a==0 ) return;  /* Error reported through db->mallocFailed */
77268         pParse->azVar = a;
77269         memset(&a[pParse->nzVar], 0, (x-pParse->nzVar)*sizeof(a[0]));
77270         pParse->nzVar = x;
77271       }
77272       if( z[0]!='?' || pParse->azVar[x-1]==0 ){
77273         sqlite3DbFree(db, pParse->azVar[x-1]);
77274         pParse->azVar[x-1] = sqlite3DbStrNDup(db, z, n);
77275       }
77276     }
77277   } 
77278   if( !pParse->nErr && pParse->nVar>db->aLimit[SQLITE_LIMIT_VARIABLE_NUMBER] ){
77279     sqlite3ErrorMsg(pParse, "too many SQL variables");
77280   }
77281 }
77282 
77283 /*
77284 ** Recursively delete an expression tree.
77285 */
77286 SQLITE_PRIVATE void sqlite3ExprDelete(sqlite3 *db, Expr *p){
77287   if( p==0 ) return;
77288   /* Sanity check: Assert that the IntValue is non-negative if it exists */
77289   assert( !ExprHasProperty(p, EP_IntValue) || p->u.iValue>=0 );
77290   if( !ExprHasProperty(p, EP_TokenOnly) ){
77291     /* The Expr.x union is never used at the same time as Expr.pRight */
77292     assert( p->x.pList==0 || p->pRight==0 );
77293     sqlite3ExprDelete(db, p->pLeft);
77294     sqlite3ExprDelete(db, p->pRight);
77295     if( ExprHasProperty(p, EP_MemToken) ) sqlite3DbFree(db, p->u.zToken);
77296     if( ExprHasProperty(p, EP_xIsSelect) ){
77297       sqlite3SelectDelete(db, p->x.pSelect);
77298     }else{
77299       sqlite3ExprListDelete(db, p->x.pList);
77300     }
77301   }
77302   if( !ExprHasProperty(p, EP_Static) ){
77303     sqlite3DbFree(db, p);
77304   }
77305 }
77306 
77307 /*
77308 ** Return the number of bytes allocated for the expression structure 
77309 ** passed as the first argument. This is always one of EXPR_FULLSIZE,
77310 ** EXPR_REDUCEDSIZE or EXPR_TOKENONLYSIZE.
77311 */
77312 static int exprStructSize(Expr *p){
77313   if( ExprHasProperty(p, EP_TokenOnly) ) return EXPR_TOKENONLYSIZE;
77314   if( ExprHasProperty(p, EP_Reduced) ) return EXPR_REDUCEDSIZE;
77315   return EXPR_FULLSIZE;
77316 }
77317 
77318 /*
77319 ** The dupedExpr*Size() routines each return the number of bytes required
77320 ** to store a copy of an expression or expression tree.  They differ in
77321 ** how much of the tree is measured.
77322 **
77323 **     dupedExprStructSize()     Size of only the Expr structure 
77324 **     dupedExprNodeSize()       Size of Expr + space for token
77325 **     dupedExprSize()           Expr + token + subtree components
77326 **
77327 ***************************************************************************
77328 **
77329 ** The dupedExprStructSize() function returns two values OR-ed together:  
77330 ** (1) the space required for a copy of the Expr structure only and 
77331 ** (2) the EP_xxx flags that indicate what the structure size should be.
77332 ** The return values is always one of:
77333 **
77334 **      EXPR_FULLSIZE
77335 **      EXPR_REDUCEDSIZE   | EP_Reduced
77336 **      EXPR_TOKENONLYSIZE | EP_TokenOnly
77337 **
77338 ** The size of the structure can be found by masking the return value
77339 ** of this routine with 0xfff.  The flags can be found by masking the
77340 ** return value with EP_Reduced|EP_TokenOnly.
77341 **
77342 ** Note that with flags==EXPRDUP_REDUCE, this routines works on full-size
77343 ** (unreduced) Expr objects as they or originally constructed by the parser.
77344 ** During expression analysis, extra information is computed and moved into
77345 ** later parts of teh Expr object and that extra information might get chopped
77346 ** off if the expression is reduced.  Note also that it does not work to
77347 ** make a EXPRDUP_REDUCE copy of a reduced expression.  It is only legal
77348 ** to reduce a pristine expression tree from the parser.  The implementation
77349 ** of dupedExprStructSize() contain multiple assert() statements that attempt
77350 ** to enforce this constraint.
77351 */
77352 static int dupedExprStructSize(Expr *p, int flags){
77353   int nSize;
77354   assert( flags==EXPRDUP_REDUCE || flags==0 ); /* Only one flag value allowed */
77355   assert( EXPR_FULLSIZE<=0xfff );
77356   assert( (0xfff & (EP_Reduced|EP_TokenOnly))==0 );
77357   if( 0==(flags&EXPRDUP_REDUCE) ){
77358     nSize = EXPR_FULLSIZE;
77359   }else{
77360     assert( !ExprHasProperty(p, EP_TokenOnly|EP_Reduced) );
77361     assert( !ExprHasProperty(p, EP_FromJoin) ); 
77362     assert( !ExprHasProperty(p, EP_MemToken) );
77363     assert( !ExprHasProperty(p, EP_NoReduce) );
77364     if( p->pLeft || p->x.pList ){
77365       nSize = EXPR_REDUCEDSIZE | EP_Reduced;
77366     }else{
77367       assert( p->pRight==0 );
77368       nSize = EXPR_TOKENONLYSIZE | EP_TokenOnly;
77369     }
77370   }
77371   return nSize;
77372 }
77373 
77374 /*
77375 ** This function returns the space in bytes required to store the copy 
77376 ** of the Expr structure and a copy of the Expr.u.zToken string (if that
77377 ** string is defined.)
77378 */
77379 static int dupedExprNodeSize(Expr *p, int flags){
77380   int nByte = dupedExprStructSize(p, flags) & 0xfff;
77381   if( !ExprHasProperty(p, EP_IntValue) && p->u.zToken ){
77382     nByte += sqlite3Strlen30(p->u.zToken)+1;
77383   }
77384   return ROUND8(nByte);
77385 }
77386 
77387 /*
77388 ** Return the number of bytes required to create a duplicate of the 
77389 ** expression passed as the first argument. The second argument is a
77390 ** mask containing EXPRDUP_XXX flags.
77391 **
77392 ** The value returned includes space to create a copy of the Expr struct
77393 ** itself and the buffer referred to by Expr.u.zToken, if any.
77394 **
77395 ** If the EXPRDUP_REDUCE flag is set, then the return value includes 
77396 ** space to duplicate all Expr nodes in the tree formed by Expr.pLeft 
77397 ** and Expr.pRight variables (but not for any structures pointed to or 
77398 ** descended from the Expr.x.pList or Expr.x.pSelect variables).
77399 */
77400 static int dupedExprSize(Expr *p, int flags){
77401   int nByte = 0;
77402   if( p ){
77403     nByte = dupedExprNodeSize(p, flags);
77404     if( flags&EXPRDUP_REDUCE ){
77405       nByte += dupedExprSize(p->pLeft, flags) + dupedExprSize(p->pRight, flags);
77406     }
77407   }
77408   return nByte;
77409 }
77410 
77411 /*
77412 ** This function is similar to sqlite3ExprDup(), except that if pzBuffer 
77413 ** is not NULL then *pzBuffer is assumed to point to a buffer large enough 
77414 ** to store the copy of expression p, the copies of p->u.zToken
77415 ** (if applicable), and the copies of the p->pLeft and p->pRight expressions,
77416 ** if any. Before returning, *pzBuffer is set to the first byte passed the
77417 ** portion of the buffer copied into by this function.
77418 */
77419 static Expr *exprDup(sqlite3 *db, Expr *p, int flags, u8 **pzBuffer){
77420   Expr *pNew = 0;                      /* Value to return */
77421   if( p ){
77422     const int isReduced = (flags&EXPRDUP_REDUCE);
77423     u8 *zAlloc;
77424     u32 staticFlag = 0;
77425 
77426     assert( pzBuffer==0 || isReduced );
77427 
77428     /* Figure out where to write the new Expr structure. */
77429     if( pzBuffer ){
77430       zAlloc = *pzBuffer;
77431       staticFlag = EP_Static;
77432     }else{
77433       zAlloc = sqlite3DbMallocRaw(db, dupedExprSize(p, flags));
77434     }
77435     pNew = (Expr *)zAlloc;
77436 
77437     if( pNew ){
77438       /* Set nNewSize to the size allocated for the structure pointed to
77439       ** by pNew. This is either EXPR_FULLSIZE, EXPR_REDUCEDSIZE or
77440       ** EXPR_TOKENONLYSIZE. nToken is set to the number of bytes consumed
77441       ** by the copy of the p->u.zToken string (if any).
77442       */
77443       const unsigned nStructSize = dupedExprStructSize(p, flags);
77444       const int nNewSize = nStructSize & 0xfff;
77445       int nToken;
77446       if( !ExprHasProperty(p, EP_IntValue) && p->u.zToken ){
77447         nToken = sqlite3Strlen30(p->u.zToken) + 1;
77448       }else{
77449         nToken = 0;
77450       }
77451       if( isReduced ){
77452         assert( ExprHasProperty(p, EP_Reduced)==0 );
77453         memcpy(zAlloc, p, nNewSize);
77454       }else{
77455         int nSize = exprStructSize(p);
77456         memcpy(zAlloc, p, nSize);
77457         memset(&zAlloc[nSize], 0, EXPR_FULLSIZE-nSize);
77458       }
77459 
77460       /* Set the EP_Reduced, EP_TokenOnly, and EP_Static flags appropriately. */
77461       pNew->flags &= ~(EP_Reduced|EP_TokenOnly|EP_Static|EP_MemToken);
77462       pNew->flags |= nStructSize & (EP_Reduced|EP_TokenOnly);
77463       pNew->flags |= staticFlag;
77464 
77465       /* Copy the p->u.zToken string, if any. */
77466       if( nToken ){
77467         char *zToken = pNew->u.zToken = (char*)&zAlloc[nNewSize];
77468         memcpy(zToken, p->u.zToken, nToken);
77469       }
77470 
77471       if( 0==((p->flags|pNew->flags) & EP_TokenOnly) ){
77472         /* Fill in the pNew->x.pSelect or pNew->x.pList member. */
77473         if( ExprHasProperty(p, EP_xIsSelect) ){
77474           pNew->x.pSelect = sqlite3SelectDup(db, p->x.pSelect, isReduced);
77475         }else{
77476           pNew->x.pList = sqlite3ExprListDup(db, p->x.pList, isReduced);
77477         }
77478       }
77479 
77480       /* Fill in pNew->pLeft and pNew->pRight. */
77481       if( ExprHasProperty(pNew, EP_Reduced|EP_TokenOnly) ){
77482         zAlloc += dupedExprNodeSize(p, flags);
77483         if( ExprHasProperty(pNew, EP_Reduced) ){
77484           pNew->pLeft = exprDup(db, p->pLeft, EXPRDUP_REDUCE, &zAlloc);
77485           pNew->pRight = exprDup(db, p->pRight, EXPRDUP_REDUCE, &zAlloc);
77486         }
77487         if( pzBuffer ){
77488           *pzBuffer = zAlloc;
77489         }
77490       }else{
77491         if( !ExprHasProperty(p, EP_TokenOnly) ){
77492           pNew->pLeft = sqlite3ExprDup(db, p->pLeft, 0);
77493           pNew->pRight = sqlite3ExprDup(db, p->pRight, 0);
77494         }
77495       }
77496 
77497     }
77498   }
77499   return pNew;
77500 }
77501 
77502 /*
77503 ** The following group of routines make deep copies of expressions,
77504 ** expression lists, ID lists, and select statements.  The copies can
77505 ** be deleted (by being passed to their respective ...Delete() routines)
77506 ** without effecting the originals.
77507 **
77508 ** The expression list, ID, and source lists return by sqlite3ExprListDup(),
77509 ** sqlite3IdListDup(), and sqlite3SrcListDup() can not be further expanded 
77510 ** by subsequent calls to sqlite*ListAppend() routines.
77511 **
77512 ** Any tables that the SrcList might point to are not duplicated.
77513 **
77514 ** The flags parameter contains a combination of the EXPRDUP_XXX flags.
77515 ** If the EXPRDUP_REDUCE flag is set, then the structure returned is a
77516 ** truncated version of the usual Expr structure that will be stored as
77517 ** part of the in-memory representation of the database schema.
77518 */
77519 SQLITE_PRIVATE Expr *sqlite3ExprDup(sqlite3 *db, Expr *p, int flags){
77520   return exprDup(db, p, flags, 0);
77521 }
77522 SQLITE_PRIVATE ExprList *sqlite3ExprListDup(sqlite3 *db, ExprList *p, int flags){
77523   ExprList *pNew;
77524   struct ExprList_item *pItem, *pOldItem;
77525   int i;
77526   if( p==0 ) return 0;
77527   pNew = sqlite3DbMallocRaw(db, sizeof(*pNew) );
77528   if( pNew==0 ) return 0;
77529   pNew->iECursor = 0;
77530   pNew->nExpr = i = p->nExpr;
77531   if( (flags & EXPRDUP_REDUCE)==0 ) for(i=1; i<p->nExpr; i+=i){}
77532   pNew->a = pItem = sqlite3DbMallocRaw(db,  i*sizeof(p->a[0]) );
77533   if( pItem==0 ){
77534     sqlite3DbFree(db, pNew);
77535     return 0;
77536   } 
77537   pOldItem = p->a;
77538   for(i=0; i<p->nExpr; i++, pItem++, pOldItem++){
77539     Expr *pOldExpr = pOldItem->pExpr;
77540     pItem->pExpr = sqlite3ExprDup(db, pOldExpr, flags);
77541     pItem->zName = sqlite3DbStrDup(db, pOldItem->zName);
77542     pItem->zSpan = sqlite3DbStrDup(db, pOldItem->zSpan);
77543     pItem->sortOrder = pOldItem->sortOrder;
77544     pItem->done = 0;
77545     pItem->bSpanIsTab = pOldItem->bSpanIsTab;
77546     pItem->u = pOldItem->u;
77547   }
77548   return pNew;
77549 }
77550 
77551 /*
77552 ** If cursors, triggers, views and subqueries are all omitted from
77553 ** the build, then none of the following routines, except for 
77554 ** sqlite3SelectDup(), can be called. sqlite3SelectDup() is sometimes
77555 ** called with a NULL argument.
77556 */
77557 #if !defined(SQLITE_OMIT_VIEW) || !defined(SQLITE_OMIT_TRIGGER) \
77558  || !defined(SQLITE_OMIT_SUBQUERY)
77559 SQLITE_PRIVATE SrcList *sqlite3SrcListDup(sqlite3 *db, SrcList *p, int flags){
77560   SrcList *pNew;
77561   int i;
77562   int nByte;
77563   if( p==0 ) return 0;
77564   nByte = sizeof(*p) + (p->nSrc>0 ? sizeof(p->a[0]) * (p->nSrc-1) : 0);
77565   pNew = sqlite3DbMallocRaw(db, nByte );
77566   if( pNew==0 ) return 0;
77567   pNew->nSrc = pNew->nAlloc = p->nSrc;
77568   for(i=0; i<p->nSrc; i++){
77569     struct SrcList_item *pNewItem = &pNew->a[i];
77570     struct SrcList_item *pOldItem = &p->a[i];
77571     Table *pTab;
77572     pNewItem->pSchema = pOldItem->pSchema;
77573     pNewItem->zDatabase = sqlite3DbStrDup(db, pOldItem->zDatabase);
77574     pNewItem->zName = sqlite3DbStrDup(db, pOldItem->zName);
77575     pNewItem->zAlias = sqlite3DbStrDup(db, pOldItem->zAlias);
77576     pNewItem->jointype = pOldItem->jointype;
77577     pNewItem->iCursor = pOldItem->iCursor;
77578     pNewItem->addrFillSub = pOldItem->addrFillSub;
77579     pNewItem->regReturn = pOldItem->regReturn;
77580     pNewItem->isCorrelated = pOldItem->isCorrelated;
77581     pNewItem->viaCoroutine = pOldItem->viaCoroutine;
77582     pNewItem->zIndex = sqlite3DbStrDup(db, pOldItem->zIndex);
77583     pNewItem->notIndexed = pOldItem->notIndexed;
77584     pNewItem->pIndex = pOldItem->pIndex;
77585     pTab = pNewItem->pTab = pOldItem->pTab;
77586     if( pTab ){
77587       pTab->nRef++;
77588     }
77589     pNewItem->pSelect = sqlite3SelectDup(db, pOldItem->pSelect, flags);
77590     pNewItem->pOn = sqlite3ExprDup(db, pOldItem->pOn, flags);
77591     pNewItem->pUsing = sqlite3IdListDup(db, pOldItem->pUsing);
77592     pNewItem->colUsed = pOldItem->colUsed;
77593   }
77594   return pNew;
77595 }
77596 SQLITE_PRIVATE IdList *sqlite3IdListDup(sqlite3 *db, IdList *p){
77597   IdList *pNew;
77598   int i;
77599   if( p==0 ) return 0;
77600   pNew = sqlite3DbMallocRaw(db, sizeof(*pNew) );
77601   if( pNew==0 ) return 0;
77602   pNew->nId = p->nId;
77603   pNew->a = sqlite3DbMallocRaw(db, p->nId*sizeof(p->a[0]) );
77604   if( pNew->a==0 ){
77605     sqlite3DbFree(db, pNew);
77606     return 0;
77607   }
77608   /* Note that because the size of the allocation for p->a[] is not
77609   ** necessarily a power of two, sqlite3IdListAppend() may not be called
77610   ** on the duplicate created by this function. */
77611   for(i=0; i<p->nId; i++){
77612     struct IdList_item *pNewItem = &pNew->a[i];
77613     struct IdList_item *pOldItem = &p->a[i];
77614     pNewItem->zName = sqlite3DbStrDup(db, pOldItem->zName);
77615     pNewItem->idx = pOldItem->idx;
77616   }
77617   return pNew;
77618 }
77619 SQLITE_PRIVATE Select *sqlite3SelectDup(sqlite3 *db, Select *p, int flags){
77620   Select *pNew, *pPrior;
77621   if( p==0 ) return 0;
77622   pNew = sqlite3DbMallocRaw(db, sizeof(*p) );
77623   if( pNew==0 ) return 0;
77624   pNew->pEList = sqlite3ExprListDup(db, p->pEList, flags);
77625   pNew->pSrc = sqlite3SrcListDup(db, p->pSrc, flags);
77626   pNew->pWhere = sqlite3ExprDup(db, p->pWhere, flags);
77627   pNew->pGroupBy = sqlite3ExprListDup(db, p->pGroupBy, flags);
77628   pNew->pHaving = sqlite3ExprDup(db, p->pHaving, flags);
77629   pNew->pOrderBy = sqlite3ExprListDup(db, p->pOrderBy, flags);
77630   pNew->op = p->op;
77631   pNew->pPrior = pPrior = sqlite3SelectDup(db, p->pPrior, flags);
77632   if( pPrior ) pPrior->pNext = pNew;
77633   pNew->pNext = 0;
77634   pNew->pLimit = sqlite3ExprDup(db, p->pLimit, flags);
77635   pNew->pOffset = sqlite3ExprDup(db, p->pOffset, flags);
77636   pNew->iLimit = 0;
77637   pNew->iOffset = 0;
77638   pNew->selFlags = p->selFlags & ~SF_UsesEphemeral;
77639   pNew->pRightmost = 0;
77640   pNew->addrOpenEphm[0] = -1;
77641   pNew->addrOpenEphm[1] = -1;
77642   pNew->addrOpenEphm[2] = -1;
77643   return pNew;
77644 }
77645 #else
77646 SQLITE_PRIVATE Select *sqlite3SelectDup(sqlite3 *db, Select *p, int flags){
77647   assert( p==0 );
77648   return 0;
77649 }
77650 #endif
77651 
77652 
77653 /*
77654 ** Add a new element to the end of an expression list.  If pList is
77655 ** initially NULL, then create a new expression list.
77656 **
77657 ** If a memory allocation error occurs, the entire list is freed and
77658 ** NULL is returned.  If non-NULL is returned, then it is guaranteed
77659 ** that the new entry was successfully appended.
77660 */
77661 SQLITE_PRIVATE ExprList *sqlite3ExprListAppend(
77662   Parse *pParse,          /* Parsing context */
77663   ExprList *pList,        /* List to which to append. Might be NULL */
77664   Expr *pExpr             /* Expression to be appended. Might be NULL */
77665 ){
77666   sqlite3 *db = pParse->db;
77667   if( pList==0 ){
77668     pList = sqlite3DbMallocZero(db, sizeof(ExprList) );
77669     if( pList==0 ){
77670       goto no_mem;
77671     }
77672     pList->a = sqlite3DbMallocRaw(db, sizeof(pList->a[0]));
77673     if( pList->a==0 ) goto no_mem;
77674   }else if( (pList->nExpr & (pList->nExpr-1))==0 ){
77675     struct ExprList_item *a;
77676     assert( pList->nExpr>0 );
77677     a = sqlite3DbRealloc(db, pList->a, pList->nExpr*2*sizeof(pList->a[0]));
77678     if( a==0 ){
77679       goto no_mem;
77680     }
77681     pList->a = a;
77682   }
77683   assert( pList->a!=0 );
77684   if( 1 ){
77685     struct ExprList_item *pItem = &pList->a[pList->nExpr++];
77686     memset(pItem, 0, sizeof(*pItem));
77687     pItem->pExpr = pExpr;
77688   }
77689   return pList;
77690 
77691 no_mem:     
77692   /* Avoid leaking memory if malloc has failed. */
77693   sqlite3ExprDelete(db, pExpr);
77694   sqlite3ExprListDelete(db, pList);
77695   return 0;
77696 }
77697 
77698 /*
77699 ** Set the ExprList.a[].zName element of the most recently added item
77700 ** on the expression list.
77701 **
77702 ** pList might be NULL following an OOM error.  But pName should never be
77703 ** NULL.  If a memory allocation fails, the pParse->db->mallocFailed flag
77704 ** is set.
77705 */
77706 SQLITE_PRIVATE void sqlite3ExprListSetName(
77707   Parse *pParse,          /* Parsing context */
77708   ExprList *pList,        /* List to which to add the span. */
77709   Token *pName,           /* Name to be added */
77710   int dequote             /* True to cause the name to be dequoted */
77711 ){
77712   assert( pList!=0 || pParse->db->mallocFailed!=0 );
77713   if( pList ){
77714     struct ExprList_item *pItem;
77715     assert( pList->nExpr>0 );
77716     pItem = &pList->a[pList->nExpr-1];
77717     assert( pItem->zName==0 );
77718     pItem->zName = sqlite3DbStrNDup(pParse->db, pName->z, pName->n);
77719     if( dequote && pItem->zName ) sqlite3Dequote(pItem->zName);
77720   }
77721 }
77722 
77723 /*
77724 ** Set the ExprList.a[].zSpan element of the most recently added item
77725 ** on the expression list.
77726 **
77727 ** pList might be NULL following an OOM error.  But pSpan should never be
77728 ** NULL.  If a memory allocation fails, the pParse->db->mallocFailed flag
77729 ** is set.
77730 */
77731 SQLITE_PRIVATE void sqlite3ExprListSetSpan(
77732   Parse *pParse,          /* Parsing context */
77733   ExprList *pList,        /* List to which to add the span. */
77734   ExprSpan *pSpan         /* The span to be added */
77735 ){
77736   sqlite3 *db = pParse->db;
77737   assert( pList!=0 || db->mallocFailed!=0 );
77738   if( pList ){
77739     struct ExprList_item *pItem = &pList->a[pList->nExpr-1];
77740     assert( pList->nExpr>0 );
77741     assert( db->mallocFailed || pItem->pExpr==pSpan->pExpr );
77742     sqlite3DbFree(db, pItem->zSpan);
77743     pItem->zSpan = sqlite3DbStrNDup(db, (char*)pSpan->zStart,
77744                                     (int)(pSpan->zEnd - pSpan->zStart));
77745   }
77746 }
77747 
77748 /*
77749 ** If the expression list pEList contains more than iLimit elements,
77750 ** leave an error message in pParse.
77751 */
77752 SQLITE_PRIVATE void sqlite3ExprListCheckLength(
77753   Parse *pParse,
77754   ExprList *pEList,
77755   const char *zObject
77756 ){
77757   int mx = pParse->db->aLimit[SQLITE_LIMIT_COLUMN];
77758   testcase( pEList && pEList->nExpr==mx );
77759   testcase( pEList && pEList->nExpr==mx+1 );
77760   if( pEList && pEList->nExpr>mx ){
77761     sqlite3ErrorMsg(pParse, "too many columns in %s", zObject);
77762   }
77763 }
77764 
77765 /*
77766 ** Delete an entire expression list.
77767 */
77768 SQLITE_PRIVATE void sqlite3ExprListDelete(sqlite3 *db, ExprList *pList){
77769   int i;
77770   struct ExprList_item *pItem;
77771   if( pList==0 ) return;
77772   assert( pList->a!=0 || pList->nExpr==0 );
77773   for(pItem=pList->a, i=0; i<pList->nExpr; i++, pItem++){
77774     sqlite3ExprDelete(db, pItem->pExpr);
77775     sqlite3DbFree(db, pItem->zName);
77776     sqlite3DbFree(db, pItem->zSpan);
77777   }
77778   sqlite3DbFree(db, pList->a);
77779   sqlite3DbFree(db, pList);
77780 }
77781 
77782 /*
77783 ** These routines are Walker callbacks.  Walker.u.pi is a pointer
77784 ** to an integer.  These routines are checking an expression to see
77785 ** if it is a constant.  Set *Walker.u.pi to 0 if the expression is
77786 ** not constant.
77787 **
77788 ** These callback routines are used to implement the following:
77789 **
77790 **     sqlite3ExprIsConstant()
77791 **     sqlite3ExprIsConstantNotJoin()
77792 **     sqlite3ExprIsConstantOrFunction()
77793 **
77794 */
77795 static int exprNodeIsConstant(Walker *pWalker, Expr *pExpr){
77796 
77797   /* If pWalker->u.i is 3 then any term of the expression that comes from
77798   ** the ON or USING clauses of a join disqualifies the expression
77799   ** from being considered constant. */
77800   if( pWalker->u.i==3 && ExprHasProperty(pExpr, EP_FromJoin) ){
77801     pWalker->u.i = 0;
77802     return WRC_Abort;
77803   }
77804 
77805   switch( pExpr->op ){
77806     /* Consider functions to be constant if all their arguments are constant
77807     ** and either pWalker->u.i==2 or the function as the SQLITE_FUNC_CONST
77808     ** flag. */
77809     case TK_FUNCTION:
77810       if( pWalker->u.i==2 || ExprHasProperty(pExpr,EP_Constant) ){
77811         return WRC_Continue;
77812       }
77813       /* Fall through */
77814     case TK_ID:
77815     case TK_COLUMN:
77816     case TK_AGG_FUNCTION:
77817     case TK_AGG_COLUMN:
77818       testcase( pExpr->op==TK_ID );
77819       testcase( pExpr->op==TK_COLUMN );
77820       testcase( pExpr->op==TK_AGG_FUNCTION );
77821       testcase( pExpr->op==TK_AGG_COLUMN );
77822       pWalker->u.i = 0;
77823       return WRC_Abort;
77824     default:
77825       testcase( pExpr->op==TK_SELECT ); /* selectNodeIsConstant will disallow */
77826       testcase( pExpr->op==TK_EXISTS ); /* selectNodeIsConstant will disallow */
77827       return WRC_Continue;
77828   }
77829 }
77830 static int selectNodeIsConstant(Walker *pWalker, Select *NotUsed){
77831   UNUSED_PARAMETER(NotUsed);
77832   pWalker->u.i = 0;
77833   return WRC_Abort;
77834 }
77835 static int exprIsConst(Expr *p, int initFlag){
77836   Walker w;
77837   memset(&w, 0, sizeof(w));
77838   w.u.i = initFlag;
77839   w.xExprCallback = exprNodeIsConstant;
77840   w.xSelectCallback = selectNodeIsConstant;
77841   sqlite3WalkExpr(&w, p);
77842   return w.u.i;
77843 }
77844 
77845 /*
77846 ** Walk an expression tree.  Return 1 if the expression is constant
77847 ** and 0 if it involves variables or function calls.
77848 **
77849 ** For the purposes of this function, a double-quoted string (ex: "abc")
77850 ** is considered a variable but a single-quoted string (ex: 'abc') is
77851 ** a constant.
77852 */
77853 SQLITE_PRIVATE int sqlite3ExprIsConstant(Expr *p){
77854   return exprIsConst(p, 1);
77855 }
77856 
77857 /*
77858 ** Walk an expression tree.  Return 1 if the expression is constant
77859 ** that does no originate from the ON or USING clauses of a join.
77860 ** Return 0 if it involves variables or function calls or terms from
77861 ** an ON or USING clause.
77862 */
77863 SQLITE_PRIVATE int sqlite3ExprIsConstantNotJoin(Expr *p){
77864   return exprIsConst(p, 3);
77865 }
77866 
77867 /*
77868 ** Walk an expression tree.  Return 1 if the expression is constant
77869 ** or a function call with constant arguments.  Return and 0 if there
77870 ** are any variables.
77871 **
77872 ** For the purposes of this function, a double-quoted string (ex: "abc")
77873 ** is considered a variable but a single-quoted string (ex: 'abc') is
77874 ** a constant.
77875 */
77876 SQLITE_PRIVATE int sqlite3ExprIsConstantOrFunction(Expr *p){
77877   return exprIsConst(p, 2);
77878 }
77879 
77880 /*
77881 ** If the expression p codes a constant integer that is small enough
77882 ** to fit in a 32-bit integer, return 1 and put the value of the integer
77883 ** in *pValue.  If the expression is not an integer or if it is too big
77884 ** to fit in a signed 32-bit integer, return 0 and leave *pValue unchanged.
77885 */
77886 SQLITE_PRIVATE int sqlite3ExprIsInteger(Expr *p, int *pValue){
77887   int rc = 0;
77888 
77889   /* If an expression is an integer literal that fits in a signed 32-bit
77890   ** integer, then the EP_IntValue flag will have already been set */
77891   assert( p->op!=TK_INTEGER || (p->flags & EP_IntValue)!=0
77892            || sqlite3GetInt32(p->u.zToken, &rc)==0 );
77893 
77894   if( p->flags & EP_IntValue ){
77895     *pValue = p->u.iValue;
77896     return 1;
77897   }
77898   switch( p->op ){
77899     case TK_UPLUS: {
77900       rc = sqlite3ExprIsInteger(p->pLeft, pValue);
77901       break;
77902     }
77903     case TK_UMINUS: {
77904       int v;
77905       if( sqlite3ExprIsInteger(p->pLeft, &v) ){
77906         assert( v!=(-2147483647-1) );
77907         *pValue = -v;
77908         rc = 1;
77909       }
77910       break;
77911     }
77912     default: break;
77913   }
77914   return rc;
77915 }
77916 
77917 /*
77918 ** Return FALSE if there is no chance that the expression can be NULL.
77919 **
77920 ** If the expression might be NULL or if the expression is too complex
77921 ** to tell return TRUE.  
77922 **
77923 ** This routine is used as an optimization, to skip OP_IsNull opcodes
77924 ** when we know that a value cannot be NULL.  Hence, a false positive
77925 ** (returning TRUE when in fact the expression can never be NULL) might
77926 ** be a small performance hit but is otherwise harmless.  On the other
77927 ** hand, a false negative (returning FALSE when the result could be NULL)
77928 ** will likely result in an incorrect answer.  So when in doubt, return
77929 ** TRUE.
77930 */
77931 SQLITE_PRIVATE int sqlite3ExprCanBeNull(const Expr *p){
77932   u8 op;
77933   while( p->op==TK_UPLUS || p->op==TK_UMINUS ){ p = p->pLeft; }
77934   op = p->op;
77935   if( op==TK_REGISTER ) op = p->op2;
77936   switch( op ){
77937     case TK_INTEGER:
77938     case TK_STRING:
77939     case TK_FLOAT:
77940     case TK_BLOB:
77941       return 0;
77942     default:
77943       return 1;
77944   }
77945 }
77946 
77947 /*
77948 ** Generate an OP_IsNull instruction that tests register iReg and jumps
77949 ** to location iDest if the value in iReg is NULL.  The value in iReg 
77950 ** was computed by pExpr.  If we can look at pExpr at compile-time and
77951 ** determine that it can never generate a NULL, then the OP_IsNull operation
77952 ** can be omitted.
77953 */
77954 SQLITE_PRIVATE void sqlite3ExprCodeIsNullJump(
77955   Vdbe *v,            /* The VDBE under construction */
77956   const Expr *pExpr,  /* Only generate OP_IsNull if this expr can be NULL */
77957   int iReg,           /* Test the value in this register for NULL */
77958   int iDest           /* Jump here if the value is null */
77959 ){
77960   if( sqlite3ExprCanBeNull(pExpr) ){
77961     sqlite3VdbeAddOp2(v, OP_IsNull, iReg, iDest);
77962   }
77963 }
77964 
77965 /*
77966 ** Return TRUE if the given expression is a constant which would be
77967 ** unchanged by OP_Affinity with the affinity given in the second
77968 ** argument.
77969 **
77970 ** This routine is used to determine if the OP_Affinity operation
77971 ** can be omitted.  When in doubt return FALSE.  A false negative
77972 ** is harmless.  A false positive, however, can result in the wrong
77973 ** answer.
77974 */
77975 SQLITE_PRIVATE int sqlite3ExprNeedsNoAffinityChange(const Expr *p, char aff){
77976   u8 op;
77977   if( aff==SQLITE_AFF_NONE ) return 1;
77978   while( p->op==TK_UPLUS || p->op==TK_UMINUS ){ p = p->pLeft; }
77979   op = p->op;
77980   if( op==TK_REGISTER ) op = p->op2;
77981   switch( op ){
77982     case TK_INTEGER: {
77983       return aff==SQLITE_AFF_INTEGER || aff==SQLITE_AFF_NUMERIC;
77984     }
77985     case TK_FLOAT: {
77986       return aff==SQLITE_AFF_REAL || aff==SQLITE_AFF_NUMERIC;
77987     }
77988     case TK_STRING: {
77989       return aff==SQLITE_AFF_TEXT;
77990     }
77991     case TK_BLOB: {
77992       return 1;
77993     }
77994     case TK_COLUMN: {
77995       assert( p->iTable>=0 );  /* p cannot be part of a CHECK constraint */
77996       return p->iColumn<0
77997           && (aff==SQLITE_AFF_INTEGER || aff==SQLITE_AFF_NUMERIC);
77998     }
77999     default: {
78000       return 0;
78001     }
78002   }
78003 }
78004 
78005 /*
78006 ** Return TRUE if the given string is a row-id column name.
78007 */
78008 SQLITE_PRIVATE int sqlite3IsRowid(const char *z){
78009   if( sqlite3StrICmp(z, "_ROWID_")==0 ) return 1;
78010   if( sqlite3StrICmp(z, "ROWID")==0 ) return 1;
78011   if( sqlite3StrICmp(z, "OID")==0 ) return 1;
78012   return 0;
78013 }
78014 
78015 /*
78016 ** Return true if we are able to the IN operator optimization on a
78017 ** query of the form
78018 **
78019 **       x IN (SELECT ...)
78020 **
78021 ** Where the SELECT... clause is as specified by the parameter to this
78022 ** routine.
78023 **
78024 ** The Select object passed in has already been preprocessed and no
78025 ** errors have been found.
78026 */
78027 #ifndef SQLITE_OMIT_SUBQUERY
78028 static int isCandidateForInOpt(Select *p){
78029   SrcList *pSrc;
78030   ExprList *pEList;
78031   Table *pTab;
78032   if( p==0 ) return 0;                   /* right-hand side of IN is SELECT */
78033   if( p->pPrior ) return 0;              /* Not a compound SELECT */
78034   if( p->selFlags & (SF_Distinct|SF_Aggregate) ){
78035     testcase( (p->selFlags & (SF_Distinct|SF_Aggregate))==SF_Distinct );
78036     testcase( (p->selFlags & (SF_Distinct|SF_Aggregate))==SF_Aggregate );
78037     return 0; /* No DISTINCT keyword and no aggregate functions */
78038   }
78039   assert( p->pGroupBy==0 );              /* Has no GROUP BY clause */
78040   if( p->pLimit ) return 0;              /* Has no LIMIT clause */
78041   assert( p->pOffset==0 );               /* No LIMIT means no OFFSET */
78042   if( p->pWhere ) return 0;              /* Has no WHERE clause */
78043   pSrc = p->pSrc;
78044   assert( pSrc!=0 );
78045   if( pSrc->nSrc!=1 ) return 0;          /* Single term in FROM clause */
78046   if( pSrc->a[0].pSelect ) return 0;     /* FROM is not a subquery or view */
78047   pTab = pSrc->a[0].pTab;
78048   if( NEVER(pTab==0) ) return 0;
78049   assert( pTab->pSelect==0 );            /* FROM clause is not a view */
78050   if( IsVirtual(pTab) ) return 0;        /* FROM clause not a virtual table */
78051   pEList = p->pEList;
78052   if( pEList->nExpr!=1 ) return 0;       /* One column in the result set */
78053   if( pEList->a[0].pExpr->op!=TK_COLUMN ) return 0; /* Result is a column */
78054   return 1;
78055 }
78056 #endif /* SQLITE_OMIT_SUBQUERY */
78057 
78058 /*
78059 ** Code an OP_Once instruction and allocate space for its flag. Return the 
78060 ** address of the new instruction.
78061 */
78062 SQLITE_PRIVATE int sqlite3CodeOnce(Parse *pParse){
78063   Vdbe *v = sqlite3GetVdbe(pParse);      /* Virtual machine being coded */
78064   return sqlite3VdbeAddOp1(v, OP_Once, pParse->nOnce++);
78065 }
78066 
78067 /*
78068 ** This function is used by the implementation of the IN (...) operator.
78069 ** The pX parameter is the expression on the RHS of the IN operator, which
78070 ** might be either a list of expressions or a subquery.
78071 **
78072 ** The job of this routine is to find or create a b-tree object that can
78073 ** be used either to test for membership in the RHS set or to iterate through
78074 ** all members of the RHS set, skipping duplicates.
78075 **
78076 ** A cursor is opened on the b-tree object that the RHS of the IN operator
78077 ** and pX->iTable is set to the index of that cursor.
78078 **
78079 ** The returned value of this function indicates the b-tree type, as follows:
78080 **
78081 **   IN_INDEX_ROWID      - The cursor was opened on a database table.
78082 **   IN_INDEX_INDEX_ASC  - The cursor was opened on an ascending index.
78083 **   IN_INDEX_INDEX_DESC - The cursor was opened on a descending index.
78084 **   IN_INDEX_EPH        - The cursor was opened on a specially created and
78085 **                         populated epheremal table.
78086 **
78087 ** An existing b-tree might be used if the RHS expression pX is a simple
78088 ** subquery such as:
78089 **
78090 **     SELECT <column> FROM <table>
78091 **
78092 ** If the RHS of the IN operator is a list or a more complex subquery, then
78093 ** an ephemeral table might need to be generated from the RHS and then
78094 ** pX->iTable made to point to the ephermeral table instead of an
78095 ** existing table.  
78096 **
78097 ** If the prNotFound parameter is 0, then the b-tree will be used to iterate
78098 ** through the set members, skipping any duplicates. In this case an
78099 ** epheremal table must be used unless the selected <column> is guaranteed
78100 ** to be unique - either because it is an INTEGER PRIMARY KEY or it
78101 ** has a UNIQUE constraint or UNIQUE index.
78102 **
78103 ** If the prNotFound parameter is not 0, then the b-tree will be used 
78104 ** for fast set membership tests. In this case an epheremal table must 
78105 ** be used unless <column> is an INTEGER PRIMARY KEY or an index can 
78106 ** be found with <column> as its left-most column.
78107 **
78108 ** When the b-tree is being used for membership tests, the calling function
78109 ** needs to know whether or not the structure contains an SQL NULL 
78110 ** value in order to correctly evaluate expressions like "X IN (Y, Z)".
78111 ** If there is any chance that the (...) might contain a NULL value at
78112 ** runtime, then a register is allocated and the register number written
78113 ** to *prNotFound. If there is no chance that the (...) contains a
78114 ** NULL value, then *prNotFound is left unchanged.
78115 **
78116 ** If a register is allocated and its location stored in *prNotFound, then
78117 ** its initial value is NULL.  If the (...) does not remain constant
78118 ** for the duration of the query (i.e. the SELECT within the (...)
78119 ** is a correlated subquery) then the value of the allocated register is
78120 ** reset to NULL each time the subquery is rerun. This allows the
78121 ** caller to use vdbe code equivalent to the following:
78122 **
78123 **   if( register==NULL ){
78124 **     has_null = <test if data structure contains null>
78125 **     register = 1
78126 **   }
78127 **
78128 ** in order to avoid running the <test if data structure contains null>
78129 ** test more often than is necessary.
78130 */
78131 #ifndef SQLITE_OMIT_SUBQUERY
78132 SQLITE_PRIVATE int sqlite3FindInIndex(Parse *pParse, Expr *pX, int *prNotFound){
78133   Select *p;                            /* SELECT to the right of IN operator */
78134   int eType = 0;                        /* Type of RHS table. IN_INDEX_* */
78135   int iTab = pParse->nTab++;            /* Cursor of the RHS table */
78136   int mustBeUnique = (prNotFound==0);   /* True if RHS must be unique */
78137   Vdbe *v = sqlite3GetVdbe(pParse);     /* Virtual machine being coded */
78138 
78139   assert( pX->op==TK_IN );
78140 
78141   /* Check to see if an existing table or index can be used to
78142   ** satisfy the query.  This is preferable to generating a new 
78143   ** ephemeral table.
78144   */
78145   p = (ExprHasProperty(pX, EP_xIsSelect) ? pX->x.pSelect : 0);
78146   if( ALWAYS(pParse->nErr==0) && isCandidateForInOpt(p) ){
78147     sqlite3 *db = pParse->db;              /* Database connection */
78148     Table *pTab;                           /* Table <table>. */
78149     Expr *pExpr;                           /* Expression <column> */
78150     i16 iCol;                              /* Index of column <column> */
78151     i16 iDb;                               /* Database idx for pTab */
78152 
78153     assert( p );                        /* Because of isCandidateForInOpt(p) */
78154     assert( p->pEList!=0 );             /* Because of isCandidateForInOpt(p) */
78155     assert( p->pEList->a[0].pExpr!=0 ); /* Because of isCandidateForInOpt(p) */
78156     assert( p->pSrc!=0 );               /* Because of isCandidateForInOpt(p) */
78157     pTab = p->pSrc->a[0].pTab;
78158     pExpr = p->pEList->a[0].pExpr;
78159     iCol = (i16)pExpr->iColumn;
78160    
78161     /* Code an OP_VerifyCookie and OP_TableLock for <table>. */
78162     iDb = sqlite3SchemaToIndex(db, pTab->pSchema);
78163     sqlite3CodeVerifySchema(pParse, iDb);
78164     sqlite3TableLock(pParse, iDb, pTab->tnum, 0, pTab->zName);
78165 
78166     /* This function is only called from two places. In both cases the vdbe
78167     ** has already been allocated. So assume sqlite3GetVdbe() is always
78168     ** successful here.
78169     */
78170     assert(v);
78171     if( iCol<0 ){
78172       int iAddr;
78173 
78174       iAddr = sqlite3CodeOnce(pParse);
78175 
78176       sqlite3OpenTable(pParse, iTab, iDb, pTab, OP_OpenRead);
78177       eType = IN_INDEX_ROWID;
78178 
78179       sqlite3VdbeJumpHere(v, iAddr);
78180     }else{
78181       Index *pIdx;                         /* Iterator variable */
78182 
78183       /* The collation sequence used by the comparison. If an index is to
78184       ** be used in place of a temp-table, it must be ordered according
78185       ** to this collation sequence.  */
78186       CollSeq *pReq = sqlite3BinaryCompareCollSeq(pParse, pX->pLeft, pExpr);
78187 
78188       /* Check that the affinity that will be used to perform the 
78189       ** comparison is the same as the affinity of the column. If
78190       ** it is not, it is not possible to use any index.
78191       */
78192       int affinity_ok = sqlite3IndexAffinityOk(pX, pTab->aCol[iCol].affinity);
78193 
78194       for(pIdx=pTab->pIndex; pIdx && eType==0 && affinity_ok; pIdx=pIdx->pNext){
78195         if( (pIdx->aiColumn[0]==iCol)
78196          && sqlite3FindCollSeq(db, ENC(db), pIdx->azColl[0], 0)==pReq
78197          && (!mustBeUnique || (pIdx->nKeyCol==1 && pIdx->onError!=OE_None))
78198         ){
78199           int iAddr = sqlite3CodeOnce(pParse);
78200           sqlite3VdbeAddOp3(v, OP_OpenRead, iTab, pIdx->tnum, iDb);
78201           sqlite3VdbeSetP4KeyInfo(pParse, pIdx);
78202           VdbeComment((v, "%s", pIdx->zName));
78203           assert( IN_INDEX_INDEX_DESC == IN_INDEX_INDEX_ASC+1 );
78204           eType = IN_INDEX_INDEX_ASC + pIdx->aSortOrder[0];
78205 
78206           sqlite3VdbeJumpHere(v, iAddr);
78207           if( prNotFound && !pTab->aCol[iCol].notNull ){
78208             *prNotFound = ++pParse->nMem;
78209             sqlite3VdbeAddOp2(v, OP_Null, 0, *prNotFound);
78210           }
78211         }
78212       }
78213     }
78214   }
78215 
78216   if( eType==0 ){
78217     /* Could not found an existing table or index to use as the RHS b-tree.
78218     ** We will have to generate an ephemeral table to do the job.
78219     */
78220     u32 savedNQueryLoop = pParse->nQueryLoop;
78221     int rMayHaveNull = 0;
78222     eType = IN_INDEX_EPH;
78223     if( prNotFound ){
78224       *prNotFound = rMayHaveNull = ++pParse->nMem;
78225       sqlite3VdbeAddOp2(v, OP_Null, 0, *prNotFound);
78226     }else{
78227       testcase( pParse->nQueryLoop>0 );
78228       pParse->nQueryLoop = 0;
78229       if( pX->pLeft->iColumn<0 && !ExprHasProperty(pX, EP_xIsSelect) ){
78230         eType = IN_INDEX_ROWID;
78231       }
78232     }
78233     sqlite3CodeSubselect(pParse, pX, rMayHaveNull, eType==IN_INDEX_ROWID);
78234     pParse->nQueryLoop = savedNQueryLoop;
78235   }else{
78236     pX->iTable = iTab;
78237   }
78238   return eType;
78239 }
78240 #endif
78241 
78242 /*
78243 ** Generate code for scalar subqueries used as a subquery expression, EXISTS,
78244 ** or IN operators.  Examples:
78245 **
78246 **     (SELECT a FROM b)          -- subquery
78247 **     EXISTS (SELECT a FROM b)   -- EXISTS subquery
78248 **     x IN (4,5,11)              -- IN operator with list on right-hand side
78249 **     x IN (SELECT a FROM b)     -- IN operator with subquery on the right
78250 **
78251 ** The pExpr parameter describes the expression that contains the IN
78252 ** operator or subquery.
78253 **
78254 ** If parameter isRowid is non-zero, then expression pExpr is guaranteed
78255 ** to be of the form "<rowid> IN (?, ?, ?)", where <rowid> is a reference
78256 ** to some integer key column of a table B-Tree. In this case, use an
78257 ** intkey B-Tree to store the set of IN(...) values instead of the usual
78258 ** (slower) variable length keys B-Tree.
78259 **
78260 ** If rMayHaveNull is non-zero, that means that the operation is an IN
78261 ** (not a SELECT or EXISTS) and that the RHS might contains NULLs.
78262 ** Furthermore, the IN is in a WHERE clause and that we really want
78263 ** to iterate over the RHS of the IN operator in order to quickly locate
78264 ** all corresponding LHS elements.  All this routine does is initialize
78265 ** the register given by rMayHaveNull to NULL.  Calling routines will take
78266 ** care of changing this register value to non-NULL if the RHS is NULL-free.
78267 **
78268 ** If rMayHaveNull is zero, that means that the subquery is being used
78269 ** for membership testing only.  There is no need to initialize any
78270 ** registers to indicate the presence or absence of NULLs on the RHS.
78271 **
78272 ** For a SELECT or EXISTS operator, return the register that holds the
78273 ** result.  For IN operators or if an error occurs, the return value is 0.
78274 */
78275 #ifndef SQLITE_OMIT_SUBQUERY
78276 SQLITE_PRIVATE int sqlite3CodeSubselect(
78277   Parse *pParse,          /* Parsing context */
78278   Expr *pExpr,            /* The IN, SELECT, or EXISTS operator */
78279   int rMayHaveNull,       /* Register that records whether NULLs exist in RHS */
78280   int isRowid             /* If true, LHS of IN operator is a rowid */
78281 ){
78282   int testAddr = -1;                      /* One-time test address */
78283   int rReg = 0;                           /* Register storing resulting */
78284   Vdbe *v = sqlite3GetVdbe(pParse);
78285   if( NEVER(v==0) ) return 0;
78286   sqlite3ExprCachePush(pParse);
78287 
78288   /* This code must be run in its entirety every time it is encountered
78289   ** if any of the following is true:
78290   **
78291   **    *  The right-hand side is a correlated subquery
78292   **    *  The right-hand side is an expression list containing variables
78293   **    *  We are inside a trigger
78294   **
78295   ** If all of the above are false, then we can run this code just once
78296   ** save the results, and reuse the same result on subsequent invocations.
78297   */
78298   if( !ExprHasProperty(pExpr, EP_VarSelect) ){
78299     testAddr = sqlite3CodeOnce(pParse);
78300   }
78301 
78302 #ifndef SQLITE_OMIT_EXPLAIN
78303   if( pParse->explain==2 ){
78304     char *zMsg = sqlite3MPrintf(
78305         pParse->db, "EXECUTE %s%s SUBQUERY %d", testAddr>=0?"":"CORRELATED ",
78306         pExpr->op==TK_IN?"LIST":"SCALAR", pParse->iNextSelectId
78307     );
78308     sqlite3VdbeAddOp4(v, OP_Explain, pParse->iSelectId, 0, 0, zMsg, P4_DYNAMIC);
78309   }
78310 #endif
78311 
78312   switch( pExpr->op ){
78313     case TK_IN: {
78314       char affinity;              /* Affinity of the LHS of the IN */
78315       int addr;                   /* Address of OP_OpenEphemeral instruction */
78316       Expr *pLeft = pExpr->pLeft; /* the LHS of the IN operator */
78317       KeyInfo *pKeyInfo = 0;      /* Key information */
78318 
78319       if( rMayHaveNull ){
78320         sqlite3VdbeAddOp2(v, OP_Null, 0, rMayHaveNull);
78321       }
78322 
78323       affinity = sqlite3ExprAffinity(pLeft);
78324 
78325       /* Whether this is an 'x IN(SELECT...)' or an 'x IN(<exprlist>)'
78326       ** expression it is handled the same way.  An ephemeral table is 
78327       ** filled with single-field index keys representing the results
78328       ** from the SELECT or the <exprlist>.
78329       **
78330       ** If the 'x' expression is a column value, or the SELECT...
78331       ** statement returns a column value, then the affinity of that
78332       ** column is used to build the index keys. If both 'x' and the
78333       ** SELECT... statement are columns, then numeric affinity is used
78334       ** if either column has NUMERIC or INTEGER affinity. If neither
78335       ** 'x' nor the SELECT... statement are columns, then numeric affinity
78336       ** is used.
78337       */
78338       pExpr->iTable = pParse->nTab++;
78339       addr = sqlite3VdbeAddOp2(v, OP_OpenEphemeral, pExpr->iTable, !isRowid);
78340       if( rMayHaveNull==0 ) sqlite3VdbeChangeP5(v, BTREE_UNORDERED);
78341       pKeyInfo = isRowid ? 0 : sqlite3KeyInfoAlloc(pParse->db, 1, 1);
78342 
78343       if( ExprHasProperty(pExpr, EP_xIsSelect) ){
78344         /* Case 1:     expr IN (SELECT ...)
78345         **
78346         ** Generate code to write the results of the select into the temporary
78347         ** table allocated and opened above.
78348         */
78349         SelectDest dest;
78350         ExprList *pEList;
78351 
78352         assert( !isRowid );
78353         sqlite3SelectDestInit(&dest, SRT_Set, pExpr->iTable);
78354         dest.affSdst = (u8)affinity;
78355         assert( (pExpr->iTable&0x0000FFFF)==pExpr->iTable );
78356         pExpr->x.pSelect->iLimit = 0;
78357         testcase( pKeyInfo==0 ); /* Caused by OOM in sqlite3KeyInfoAlloc() */
78358         if( sqlite3Select(pParse, pExpr->x.pSelect, &dest) ){
78359           sqlite3KeyInfoUnref(pKeyInfo);
78360           return 0;
78361         }
78362         pEList = pExpr->x.pSelect->pEList;
78363         assert( pKeyInfo!=0 ); /* OOM will cause exit after sqlite3Select() */
78364         assert( pEList!=0 );
78365         assert( pEList->nExpr>0 );
78366         assert( sqlite3KeyInfoIsWriteable(pKeyInfo) );
78367         pKeyInfo->aColl[0] = sqlite3BinaryCompareCollSeq(pParse, pExpr->pLeft,
78368                                                          pEList->a[0].pExpr);
78369       }else if( ALWAYS(pExpr->x.pList!=0) ){
78370         /* Case 2:     expr IN (exprlist)
78371         **
78372         ** For each expression, build an index key from the evaluation and
78373         ** store it in the temporary table. If <expr> is a column, then use
78374         ** that columns affinity when building index keys. If <expr> is not
78375         ** a column, use numeric affinity.
78376         */
78377         int i;
78378         ExprList *pList = pExpr->x.pList;
78379         struct ExprList_item *pItem;
78380         int r1, r2, r3;
78381 
78382         if( !affinity ){
78383           affinity = SQLITE_AFF_NONE;
78384         }
78385         if( pKeyInfo ){
78386           assert( sqlite3KeyInfoIsWriteable(pKeyInfo) );
78387           pKeyInfo->aColl[0] = sqlite3ExprCollSeq(pParse, pExpr->pLeft);
78388         }
78389 
78390         /* Loop through each expression in <exprlist>. */
78391         r1 = sqlite3GetTempReg(pParse);
78392         r2 = sqlite3GetTempReg(pParse);
78393         sqlite3VdbeAddOp2(v, OP_Null, 0, r2);
78394         for(i=pList->nExpr, pItem=pList->a; i>0; i--, pItem++){
78395           Expr *pE2 = pItem->pExpr;
78396           int iValToIns;
78397 
78398           /* If the expression is not constant then we will need to
78399           ** disable the test that was generated above that makes sure
78400           ** this code only executes once.  Because for a non-constant
78401           ** expression we need to rerun this code each time.
78402           */
78403           if( testAddr>=0 && !sqlite3ExprIsConstant(pE2) ){
78404             sqlite3VdbeChangeToNoop(v, testAddr);
78405             testAddr = -1;
78406           }
78407 
78408           /* Evaluate the expression and insert it into the temp table */
78409           if( isRowid && sqlite3ExprIsInteger(pE2, &iValToIns) ){
78410             sqlite3VdbeAddOp3(v, OP_InsertInt, pExpr->iTable, r2, iValToIns);
78411           }else{
78412             r3 = sqlite3ExprCodeTarget(pParse, pE2, r1);
78413             if( isRowid ){
78414               sqlite3VdbeAddOp2(v, OP_MustBeInt, r3,
78415                                 sqlite3VdbeCurrentAddr(v)+2);
78416               sqlite3VdbeAddOp3(v, OP_Insert, pExpr->iTable, r2, r3);
78417             }else{
78418               sqlite3VdbeAddOp4(v, OP_MakeRecord, r3, 1, r2, &affinity, 1);
78419               sqlite3ExprCacheAffinityChange(pParse, r3, 1);
78420               sqlite3VdbeAddOp2(v, OP_IdxInsert, pExpr->iTable, r2);
78421             }
78422           }
78423         }
78424         sqlite3ReleaseTempReg(pParse, r1);
78425         sqlite3ReleaseTempReg(pParse, r2);
78426       }
78427       if( pKeyInfo ){
78428         sqlite3VdbeChangeP4(v, addr, (void *)pKeyInfo, P4_KEYINFO);
78429       }
78430       break;
78431     }
78432 
78433     case TK_EXISTS:
78434     case TK_SELECT:
78435     default: {
78436       /* If this has to be a scalar SELECT.  Generate code to put the
78437       ** value of this select in a memory cell and record the number
78438       ** of the memory cell in iColumn.  If this is an EXISTS, write
78439       ** an integer 0 (not exists) or 1 (exists) into a memory cell
78440       ** and record that memory cell in iColumn.
78441       */
78442       Select *pSel;                         /* SELECT statement to encode */
78443       SelectDest dest;                      /* How to deal with SELECt result */
78444 
78445       testcase( pExpr->op==TK_EXISTS );
78446       testcase( pExpr->op==TK_SELECT );
78447       assert( pExpr->op==TK_EXISTS || pExpr->op==TK_SELECT );
78448 
78449       assert( ExprHasProperty(pExpr, EP_xIsSelect) );
78450       pSel = pExpr->x.pSelect;
78451       sqlite3SelectDestInit(&dest, 0, ++pParse->nMem);
78452       if( pExpr->op==TK_SELECT ){
78453         dest.eDest = SRT_Mem;
78454         sqlite3VdbeAddOp2(v, OP_Null, 0, dest.iSDParm);
78455         VdbeComment((v, "Init subquery result"));
78456       }else{
78457         dest.eDest = SRT_Exists;
78458         sqlite3VdbeAddOp2(v, OP_Integer, 0, dest.iSDParm);
78459         VdbeComment((v, "Init EXISTS result"));
78460       }
78461       sqlite3ExprDelete(pParse->db, pSel->pLimit);
78462       pSel->pLimit = sqlite3PExpr(pParse, TK_INTEGER, 0, 0,
78463                                   &sqlite3IntTokens[1]);
78464       pSel->iLimit = 0;
78465       if( sqlite3Select(pParse, pSel, &dest) ){
78466         return 0;
78467       }
78468       rReg = dest.iSDParm;
78469       ExprSetVVAProperty(pExpr, EP_NoReduce);
78470       break;
78471     }
78472   }
78473 
78474   if( testAddr>=0 ){
78475     sqlite3VdbeJumpHere(v, testAddr);
78476   }
78477   sqlite3ExprCachePop(pParse, 1);
78478 
78479   return rReg;
78480 }
78481 #endif /* SQLITE_OMIT_SUBQUERY */
78482 
78483 #ifndef SQLITE_OMIT_SUBQUERY
78484 /*
78485 ** Generate code for an IN expression.
78486 **
78487 **      x IN (SELECT ...)
78488 **      x IN (value, value, ...)
78489 **
78490 ** The left-hand side (LHS) is a scalar expression.  The right-hand side (RHS)
78491 ** is an array of zero or more values.  The expression is true if the LHS is
78492 ** contained within the RHS.  The value of the expression is unknown (NULL)
78493 ** if the LHS is NULL or if the LHS is not contained within the RHS and the
78494 ** RHS contains one or more NULL values.
78495 **
78496 ** This routine generates code will jump to destIfFalse if the LHS is not 
78497 ** contained within the RHS.  If due to NULLs we cannot determine if the LHS
78498 ** is contained in the RHS then jump to destIfNull.  If the LHS is contained
78499 ** within the RHS then fall through.
78500 */
78501 static void sqlite3ExprCodeIN(
78502   Parse *pParse,        /* Parsing and code generating context */
78503   Expr *pExpr,          /* The IN expression */
78504   int destIfFalse,      /* Jump here if LHS is not contained in the RHS */
78505   int destIfNull        /* Jump here if the results are unknown due to NULLs */
78506 ){
78507   int rRhsHasNull = 0;  /* Register that is true if RHS contains NULL values */
78508   char affinity;        /* Comparison affinity to use */
78509   int eType;            /* Type of the RHS */
78510   int r1;               /* Temporary use register */
78511   Vdbe *v;              /* Statement under construction */
78512 
78513   /* Compute the RHS.   After this step, the table with cursor
78514   ** pExpr->iTable will contains the values that make up the RHS.
78515   */
78516   v = pParse->pVdbe;
78517   assert( v!=0 );       /* OOM detected prior to this routine */
78518   VdbeNoopComment((v, "begin IN expr"));
78519   eType = sqlite3FindInIndex(pParse, pExpr, &rRhsHasNull);
78520 
78521   /* Figure out the affinity to use to create a key from the results
78522   ** of the expression. affinityStr stores a static string suitable for
78523   ** P4 of OP_MakeRecord.
78524   */
78525   affinity = comparisonAffinity(pExpr);
78526 
78527   /* Code the LHS, the <expr> from "<expr> IN (...)".
78528   */
78529   sqlite3ExprCachePush(pParse);
78530   r1 = sqlite3GetTempReg(pParse);
78531   sqlite3ExprCode(pParse, pExpr->pLeft, r1);
78532 
78533   /* If the LHS is NULL, then the result is either false or NULL depending
78534   ** on whether the RHS is empty or not, respectively.
78535   */
78536   if( destIfNull==destIfFalse ){
78537     /* Shortcut for the common case where the false and NULL outcomes are
78538     ** the same. */
78539     sqlite3VdbeAddOp2(v, OP_IsNull, r1, destIfNull);
78540   }else{
78541     int addr1 = sqlite3VdbeAddOp1(v, OP_NotNull, r1);
78542     sqlite3VdbeAddOp2(v, OP_Rewind, pExpr->iTable, destIfFalse);
78543     sqlite3VdbeAddOp2(v, OP_Goto, 0, destIfNull);
78544     sqlite3VdbeJumpHere(v, addr1);
78545   }
78546 
78547   if( eType==IN_INDEX_ROWID ){
78548     /* In this case, the RHS is the ROWID of table b-tree
78549     */
78550     sqlite3VdbeAddOp2(v, OP_MustBeInt, r1, destIfFalse);
78551     sqlite3VdbeAddOp3(v, OP_NotExists, pExpr->iTable, destIfFalse, r1);
78552   }else{
78553     /* In this case, the RHS is an index b-tree.
78554     */
78555     sqlite3VdbeAddOp4(v, OP_Affinity, r1, 1, 0, &affinity, 1);
78556 
78557     /* If the set membership test fails, then the result of the 
78558     ** "x IN (...)" expression must be either 0 or NULL. If the set
78559     ** contains no NULL values, then the result is 0. If the set 
78560     ** contains one or more NULL values, then the result of the
78561     ** expression is also NULL.
78562     */
78563     if( rRhsHasNull==0 || destIfFalse==destIfNull ){
78564       /* This branch runs if it is known at compile time that the RHS
78565       ** cannot contain NULL values. This happens as the result
78566       ** of a "NOT NULL" constraint in the database schema.
78567       **
78568       ** Also run this branch if NULL is equivalent to FALSE
78569       ** for this particular IN operator.
78570       */
78571       sqlite3VdbeAddOp4Int(v, OP_NotFound, pExpr->iTable, destIfFalse, r1, 1);
78572 
78573     }else{
78574       /* In this branch, the RHS of the IN might contain a NULL and
78575       ** the presence of a NULL on the RHS makes a difference in the
78576       ** outcome.
78577       */
78578       int j1, j2, j3;
78579 
78580       /* First check to see if the LHS is contained in the RHS.  If so,
78581       ** then the presence of NULLs in the RHS does not matter, so jump
78582       ** over all of the code that follows.
78583       */
78584       j1 = sqlite3VdbeAddOp4Int(v, OP_Found, pExpr->iTable, 0, r1, 1);
78585 
78586       /* Here we begin generating code that runs if the LHS is not
78587       ** contained within the RHS.  Generate additional code that
78588       ** tests the RHS for NULLs.  If the RHS contains a NULL then
78589       ** jump to destIfNull.  If there are no NULLs in the RHS then
78590       ** jump to destIfFalse.
78591       */
78592       j2 = sqlite3VdbeAddOp1(v, OP_NotNull, rRhsHasNull);
78593       j3 = sqlite3VdbeAddOp4Int(v, OP_Found, pExpr->iTable, 0, rRhsHasNull, 1);
78594       sqlite3VdbeAddOp2(v, OP_Integer, -1, rRhsHasNull);
78595       sqlite3VdbeJumpHere(v, j3);
78596       sqlite3VdbeAddOp2(v, OP_AddImm, rRhsHasNull, 1);
78597       sqlite3VdbeJumpHere(v, j2);
78598 
78599       /* Jump to the appropriate target depending on whether or not
78600       ** the RHS contains a NULL
78601       */
78602       sqlite3VdbeAddOp2(v, OP_If, rRhsHasNull, destIfNull);
78603       sqlite3VdbeAddOp2(v, OP_Goto, 0, destIfFalse);
78604 
78605       /* The OP_Found at the top of this branch jumps here when true, 
78606       ** causing the overall IN expression evaluation to fall through.
78607       */
78608       sqlite3VdbeJumpHere(v, j1);
78609     }
78610   }
78611   sqlite3ReleaseTempReg(pParse, r1);
78612   sqlite3ExprCachePop(pParse, 1);
78613   VdbeComment((v, "end IN expr"));
78614 }
78615 #endif /* SQLITE_OMIT_SUBQUERY */
78616 
78617 /*
78618 ** Duplicate an 8-byte value
78619 */
78620 static char *dup8bytes(Vdbe *v, const char *in){
78621   char *out = sqlite3DbMallocRaw(sqlite3VdbeDb(v), 8);
78622   if( out ){
78623     memcpy(out, in, 8);
78624   }
78625   return out;
78626 }
78627 
78628 #ifndef SQLITE_OMIT_FLOATING_POINT
78629 /*
78630 ** Generate an instruction that will put the floating point
78631 ** value described by z[0..n-1] into register iMem.
78632 **
78633 ** The z[] string will probably not be zero-terminated.  But the 
78634 ** z[n] character is guaranteed to be something that does not look
78635 ** like the continuation of the number.
78636 */
78637 static void codeReal(Vdbe *v, const char *z, int negateFlag, int iMem){
78638   if( ALWAYS(z!=0) ){
78639     double value;
78640     char *zV;
78641     sqlite3AtoF(z, &value, sqlite3Strlen30(z), SQLITE_UTF8);
78642     assert( !sqlite3IsNaN(value) ); /* The new AtoF never returns NaN */
78643     if( negateFlag ) value = -value;
78644     zV = dup8bytes(v, (char*)&value);
78645     sqlite3VdbeAddOp4(v, OP_Real, 0, iMem, 0, zV, P4_REAL);
78646   }
78647 }
78648 #endif
78649 
78650 
78651 /*
78652 ** Generate an instruction that will put the integer describe by
78653 ** text z[0..n-1] into register iMem.
78654 **
78655 ** Expr.u.zToken is always UTF8 and zero-terminated.
78656 */
78657 static void codeInteger(Parse *pParse, Expr *pExpr, int negFlag, int iMem){
78658   Vdbe *v = pParse->pVdbe;
78659   if( pExpr->flags & EP_IntValue ){
78660     int i = pExpr->u.iValue;
78661     assert( i>=0 );
78662     if( negFlag ) i = -i;
78663     sqlite3VdbeAddOp2(v, OP_Integer, i, iMem);
78664   }else{
78665     int c;
78666     i64 value;
78667     const char *z = pExpr->u.zToken;
78668     assert( z!=0 );
78669     c = sqlite3Atoi64(z, &value, sqlite3Strlen30(z), SQLITE_UTF8);
78670     if( c==0 || (c==2 && negFlag) ){
78671       char *zV;
78672       if( negFlag ){ value = c==2 ? SMALLEST_INT64 : -value; }
78673       zV = dup8bytes(v, (char*)&value);
78674       sqlite3VdbeAddOp4(v, OP_Int64, 0, iMem, 0, zV, P4_INT64);
78675     }else{
78676 #ifdef SQLITE_OMIT_FLOATING_POINT
78677       sqlite3ErrorMsg(pParse, "oversized integer: %s%s", negFlag ? "-" : "", z);
78678 #else
78679       codeReal(v, z, negFlag, iMem);
78680 #endif
78681     }
78682   }
78683 }
78684 
78685 /*
78686 ** Clear a cache entry.
78687 */
78688 static void cacheEntryClear(Parse *pParse, struct yColCache *p){
78689   if( p->tempReg ){
78690     if( pParse->nTempReg<ArraySize(pParse->aTempReg) ){
78691       pParse->aTempReg[pParse->nTempReg++] = p->iReg;
78692     }
78693     p->tempReg = 0;
78694   }
78695 }
78696 
78697 
78698 /*
78699 ** Record in the column cache that a particular column from a
78700 ** particular table is stored in a particular register.
78701 */
78702 SQLITE_PRIVATE void sqlite3ExprCacheStore(Parse *pParse, int iTab, int iCol, int iReg){
78703   int i;
78704   int minLru;
78705   int idxLru;
78706   struct yColCache *p;
78707 
78708   assert( iReg>0 );  /* Register numbers are always positive */
78709   assert( iCol>=-1 && iCol<32768 );  /* Finite column numbers */
78710 
78711   /* The SQLITE_ColumnCache flag disables the column cache.  This is used
78712   ** for testing only - to verify that SQLite always gets the same answer
78713   ** with and without the column cache.
78714   */
78715   if( OptimizationDisabled(pParse->db, SQLITE_ColumnCache) ) return;
78716 
78717   /* First replace any existing entry.
78718   **
78719   ** Actually, the way the column cache is currently used, we are guaranteed
78720   ** that the object will never already be in cache.  Verify this guarantee.
78721   */
78722 #ifndef NDEBUG
78723   for(i=0, p=pParse->aColCache; i<SQLITE_N_COLCACHE; i++, p++){
78724     assert( p->iReg==0 || p->iTable!=iTab || p->iColumn!=iCol );
78725   }
78726 #endif
78727 
78728   /* Find an empty slot and replace it */
78729   for(i=0, p=pParse->aColCache; i<SQLITE_N_COLCACHE; i++, p++){
78730     if( p->iReg==0 ){
78731       p->iLevel = pParse->iCacheLevel;
78732       p->iTable = iTab;
78733       p->iColumn = iCol;
78734       p->iReg = iReg;
78735       p->tempReg = 0;
78736       p->lru = pParse->iCacheCnt++;
78737       return;
78738     }
78739   }
78740 
78741   /* Replace the last recently used */
78742   minLru = 0x7fffffff;
78743   idxLru = -1;
78744   for(i=0, p=pParse->aColCache; i<SQLITE_N_COLCACHE; i++, p++){
78745     if( p->lru<minLru ){
78746       idxLru = i;
78747       minLru = p->lru;
78748     }
78749   }
78750   if( ALWAYS(idxLru>=0) ){
78751     p = &pParse->aColCache[idxLru];
78752     p->iLevel = pParse->iCacheLevel;
78753     p->iTable = iTab;
78754     p->iColumn = iCol;
78755     p->iReg = iReg;
78756     p->tempReg = 0;
78757     p->lru = pParse->iCacheCnt++;
78758     return;
78759   }
78760 }
78761 
78762 /*
78763 ** Indicate that registers between iReg..iReg+nReg-1 are being overwritten.
78764 ** Purge the range of registers from the column cache.
78765 */
78766 SQLITE_PRIVATE void sqlite3ExprCacheRemove(Parse *pParse, int iReg, int nReg){
78767   int i;
78768   int iLast = iReg + nReg - 1;
78769   struct yColCache *p;
78770   for(i=0, p=pParse->aColCache; i<SQLITE_N_COLCACHE; i++, p++){
78771     int r = p->iReg;
78772     if( r>=iReg && r<=iLast ){
78773       cacheEntryClear(pParse, p);
78774       p->iReg = 0;
78775     }
78776   }
78777 }
78778 
78779 /*
78780 ** Remember the current column cache context.  Any new entries added
78781 ** added to the column cache after this call are removed when the
78782 ** corresponding pop occurs.
78783 */
78784 SQLITE_PRIVATE void sqlite3ExprCachePush(Parse *pParse){
78785   pParse->iCacheLevel++;
78786 }
78787 
78788 /*
78789 ** Remove from the column cache any entries that were added since the
78790 ** the previous N Push operations.  In other words, restore the cache
78791 ** to the state it was in N Pushes ago.
78792 */
78793 SQLITE_PRIVATE void sqlite3ExprCachePop(Parse *pParse, int N){
78794   int i;
78795   struct yColCache *p;
78796   assert( N>0 );
78797   assert( pParse->iCacheLevel>=N );
78798   pParse->iCacheLevel -= N;
78799   for(i=0, p=pParse->aColCache; i<SQLITE_N_COLCACHE; i++, p++){
78800     if( p->iReg && p->iLevel>pParse->iCacheLevel ){
78801       cacheEntryClear(pParse, p);
78802       p->iReg = 0;
78803     }
78804   }
78805 }
78806 
78807 /*
78808 ** When a cached column is reused, make sure that its register is
78809 ** no longer available as a temp register.  ticket #3879:  that same
78810 ** register might be in the cache in multiple places, so be sure to
78811 ** get them all.
78812 */
78813 static void sqlite3ExprCachePinRegister(Parse *pParse, int iReg){
78814   int i;
78815   struct yColCache *p;
78816   for(i=0, p=pParse->aColCache; i<SQLITE_N_COLCACHE; i++, p++){
78817     if( p->iReg==iReg ){
78818       p->tempReg = 0;
78819     }
78820   }
78821 }
78822 
78823 /*
78824 ** Generate code to extract the value of the iCol-th column of a table.
78825 */
78826 SQLITE_PRIVATE void sqlite3ExprCodeGetColumnOfTable(
78827   Vdbe *v,        /* The VDBE under construction */
78828   Table *pTab,    /* The table containing the value */
78829   int iTabCur,    /* The table cursor.  Or the PK cursor for WITHOUT ROWID */
78830   int iCol,       /* Index of the column to extract */
78831   int regOut      /* Extract the value into this register */
78832 ){
78833   if( iCol<0 || iCol==pTab->iPKey ){
78834     sqlite3VdbeAddOp2(v, OP_Rowid, iTabCur, regOut);
78835   }else{
78836     int op = IsVirtual(pTab) ? OP_VColumn : OP_Column;
78837     int x = iCol;
78838     if( !HasRowid(pTab) ){
78839       x = sqlite3ColumnOfIndex(sqlite3PrimaryKeyIndex(pTab), iCol);
78840     }
78841     sqlite3VdbeAddOp3(v, op, iTabCur, x, regOut);
78842   }
78843   if( iCol>=0 ){
78844     sqlite3ColumnDefault(v, pTab, iCol, regOut);
78845   }
78846 }
78847 
78848 /*
78849 ** Generate code that will extract the iColumn-th column from
78850 ** table pTab and store the column value in a register.  An effort
78851 ** is made to store the column value in register iReg, but this is
78852 ** not guaranteed.  The location of the column value is returned.
78853 **
78854 ** There must be an open cursor to pTab in iTable when this routine
78855 ** is called.  If iColumn<0 then code is generated that extracts the rowid.
78856 */
78857 SQLITE_PRIVATE int sqlite3ExprCodeGetColumn(
78858   Parse *pParse,   /* Parsing and code generating context */
78859   Table *pTab,     /* Description of the table we are reading from */
78860   int iColumn,     /* Index of the table column */
78861   int iTable,      /* The cursor pointing to the table */
78862   int iReg,        /* Store results here */
78863   u8 p5            /* P5 value for OP_Column */
78864 ){
78865   Vdbe *v = pParse->pVdbe;
78866   int i;
78867   struct yColCache *p;
78868 
78869   for(i=0, p=pParse->aColCache; i<SQLITE_N_COLCACHE; i++, p++){
78870     if( p->iReg>0 && p->iTable==iTable && p->iColumn==iColumn ){
78871       p->lru = pParse->iCacheCnt++;
78872       sqlite3ExprCachePinRegister(pParse, p->iReg);
78873       return p->iReg;
78874     }
78875   }  
78876   assert( v!=0 );
78877   sqlite3ExprCodeGetColumnOfTable(v, pTab, iTable, iColumn, iReg);
78878   if( p5 ){
78879     sqlite3VdbeChangeP5(v, p5);
78880   }else{   
78881     sqlite3ExprCacheStore(pParse, iTable, iColumn, iReg);
78882   }
78883   return iReg;
78884 }
78885 
78886 /*
78887 ** Clear all column cache entries.
78888 */
78889 SQLITE_PRIVATE void sqlite3ExprCacheClear(Parse *pParse){
78890   int i;
78891   struct yColCache *p;
78892 
78893   for(i=0, p=pParse->aColCache; i<SQLITE_N_COLCACHE; i++, p++){
78894     if( p->iReg ){
78895       cacheEntryClear(pParse, p);
78896       p->iReg = 0;
78897     }
78898   }
78899 }
78900 
78901 /*
78902 ** Record the fact that an affinity change has occurred on iCount
78903 ** registers starting with iStart.
78904 */
78905 SQLITE_PRIVATE void sqlite3ExprCacheAffinityChange(Parse *pParse, int iStart, int iCount){
78906   sqlite3ExprCacheRemove(pParse, iStart, iCount);
78907 }
78908 
78909 /*
78910 ** Generate code to move content from registers iFrom...iFrom+nReg-1
78911 ** over to iTo..iTo+nReg-1. Keep the column cache up-to-date.
78912 */
78913 SQLITE_PRIVATE void sqlite3ExprCodeMove(Parse *pParse, int iFrom, int iTo, int nReg){
78914   int i;
78915   struct yColCache *p;
78916   assert( iFrom>=iTo+nReg || iFrom+nReg<=iTo );
78917   sqlite3VdbeAddOp3(pParse->pVdbe, OP_Move, iFrom, iTo, nReg-1);
78918   for(i=0, p=pParse->aColCache; i<SQLITE_N_COLCACHE; i++, p++){
78919     int x = p->iReg;
78920     if( x>=iFrom && x<iFrom+nReg ){
78921       p->iReg += iTo-iFrom;
78922     }
78923   }
78924 }
78925 
78926 #if defined(SQLITE_DEBUG) || defined(SQLITE_COVERAGE_TEST)
78927 /*
78928 ** Return true if any register in the range iFrom..iTo (inclusive)
78929 ** is used as part of the column cache.
78930 **
78931 ** This routine is used within assert() and testcase() macros only
78932 ** and does not appear in a normal build.
78933 */
78934 static int usedAsColumnCache(Parse *pParse, int iFrom, int iTo){
78935   int i;
78936   struct yColCache *p;
78937   for(i=0, p=pParse->aColCache; i<SQLITE_N_COLCACHE; i++, p++){
78938     int r = p->iReg;
78939     if( r>=iFrom && r<=iTo ) return 1;    /*NO_TEST*/
78940   }
78941   return 0;
78942 }
78943 #endif /* SQLITE_DEBUG || SQLITE_COVERAGE_TEST */
78944 
78945 /*
78946 ** Convert an expression node to a TK_REGISTER
78947 */
78948 static void exprToRegister(Expr *p, int iReg){
78949   p->op2 = p->op;
78950   p->op = TK_REGISTER;
78951   p->iTable = iReg;
78952   ExprClearProperty(p, EP_Skip);
78953 }
78954 
78955 /*
78956 ** Generate code into the current Vdbe to evaluate the given
78957 ** expression.  Attempt to store the results in register "target".
78958 ** Return the register where results are stored.
78959 **
78960 ** With this routine, there is no guarantee that results will
78961 ** be stored in target.  The result might be stored in some other
78962 ** register if it is convenient to do so.  The calling function
78963 ** must check the return code and move the results to the desired
78964 ** register.
78965 */
78966 SQLITE_PRIVATE int sqlite3ExprCodeTarget(Parse *pParse, Expr *pExpr, int target){
78967   Vdbe *v = pParse->pVdbe;  /* The VM under construction */
78968   int op;                   /* The opcode being coded */
78969   int inReg = target;       /* Results stored in register inReg */
78970   int regFree1 = 0;         /* If non-zero free this temporary register */
78971   int regFree2 = 0;         /* If non-zero free this temporary register */
78972   int r1, r2, r3, r4;       /* Various register numbers */
78973   sqlite3 *db = pParse->db; /* The database connection */
78974   Expr tempX;               /* Temporary expression node */
78975 
78976   assert( target>0 && target<=pParse->nMem );
78977   if( v==0 ){
78978     assert( pParse->db->mallocFailed );
78979     return 0;
78980   }
78981 
78982   if( pExpr==0 ){
78983     op = TK_NULL;
78984   }else{
78985     op = pExpr->op;
78986   }
78987   switch( op ){
78988     case TK_AGG_COLUMN: {
78989       AggInfo *pAggInfo = pExpr->pAggInfo;
78990       struct AggInfo_col *pCol = &pAggInfo->aCol[pExpr->iAgg];
78991       if( !pAggInfo->directMode ){
78992         assert( pCol->iMem>0 );
78993         inReg = pCol->iMem;
78994         break;
78995       }else if( pAggInfo->useSortingIdx ){
78996         sqlite3VdbeAddOp3(v, OP_Column, pAggInfo->sortingIdxPTab,
78997                               pCol->iSorterColumn, target);
78998         break;
78999       }
79000       /* Otherwise, fall thru into the TK_COLUMN case */
79001     }
79002     case TK_COLUMN: {
79003       int iTab = pExpr->iTable;
79004       if( iTab<0 ){
79005         if( pParse->ckBase>0 ){
79006           /* Generating CHECK constraints or inserting into partial index */
79007           inReg = pExpr->iColumn + pParse->ckBase;
79008           break;
79009         }else{
79010           /* Deleting from a partial index */
79011           iTab = pParse->iPartIdxTab;
79012         }
79013       }
79014       inReg = sqlite3ExprCodeGetColumn(pParse, pExpr->pTab,
79015                                pExpr->iColumn, iTab, target,
79016                                pExpr->op2);
79017       break;
79018     }
79019     case TK_INTEGER: {
79020       codeInteger(pParse, pExpr, 0, target);
79021       break;
79022     }
79023 #ifndef SQLITE_OMIT_FLOATING_POINT
79024     case TK_FLOAT: {
79025       assert( !ExprHasProperty(pExpr, EP_IntValue) );
79026       codeReal(v, pExpr->u.zToken, 0, target);
79027       break;
79028     }
79029 #endif
79030     case TK_STRING: {
79031       assert( !ExprHasProperty(pExpr, EP_IntValue) );
79032       sqlite3VdbeAddOp4(v, OP_String8, 0, target, 0, pExpr->u.zToken, 0);
79033       break;
79034     }
79035     case TK_NULL: {
79036       sqlite3VdbeAddOp2(v, OP_Null, 0, target);
79037       break;
79038     }
79039 #ifndef SQLITE_OMIT_BLOB_LITERAL
79040     case TK_BLOB: {
79041       int n;
79042       const char *z;
79043       char *zBlob;
79044       assert( !ExprHasProperty(pExpr, EP_IntValue) );
79045       assert( pExpr->u.zToken[0]=='x' || pExpr->u.zToken[0]=='X' );
79046       assert( pExpr->u.zToken[1]=='\'' );
79047       z = &pExpr->u.zToken[2];
79048       n = sqlite3Strlen30(z) - 1;
79049       assert( z[n]=='\'' );
79050       zBlob = sqlite3HexToBlob(sqlite3VdbeDb(v), z, n);
79051       sqlite3VdbeAddOp4(v, OP_Blob, n/2, target, 0, zBlob, P4_DYNAMIC);
79052       break;
79053     }
79054 #endif
79055     case TK_VARIABLE: {
79056       assert( !ExprHasProperty(pExpr, EP_IntValue) );
79057       assert( pExpr->u.zToken!=0 );
79058       assert( pExpr->u.zToken[0]!=0 );
79059       sqlite3VdbeAddOp2(v, OP_Variable, pExpr->iColumn, target);
79060       if( pExpr->u.zToken[1]!=0 ){
79061         assert( pExpr->u.zToken[0]=='?' 
79062              || strcmp(pExpr->u.zToken, pParse->azVar[pExpr->iColumn-1])==0 );
79063         sqlite3VdbeChangeP4(v, -1, pParse->azVar[pExpr->iColumn-1], P4_STATIC);
79064       }
79065       break;
79066     }
79067     case TK_REGISTER: {
79068       inReg = pExpr->iTable;
79069       break;
79070     }
79071     case TK_AS: {
79072       inReg = sqlite3ExprCodeTarget(pParse, pExpr->pLeft, target);
79073       break;
79074     }
79075 #ifndef SQLITE_OMIT_CAST
79076     case TK_CAST: {
79077       /* Expressions of the form:   CAST(pLeft AS token) */
79078       int aff, to_op;
79079       inReg = sqlite3ExprCodeTarget(pParse, pExpr->pLeft, target);
79080       assert( !ExprHasProperty(pExpr, EP_IntValue) );
79081       aff = sqlite3AffinityType(pExpr->u.zToken, 0);
79082       to_op = aff - SQLITE_AFF_TEXT + OP_ToText;
79083       assert( to_op==OP_ToText    || aff!=SQLITE_AFF_TEXT    );
79084       assert( to_op==OP_ToBlob    || aff!=SQLITE_AFF_NONE    );
79085       assert( to_op==OP_ToNumeric || aff!=SQLITE_AFF_NUMERIC );
79086       assert( to_op==OP_ToInt     || aff!=SQLITE_AFF_INTEGER );
79087       assert( to_op==OP_ToReal    || aff!=SQLITE_AFF_REAL    );
79088       testcase( to_op==OP_ToText );
79089       testcase( to_op==OP_ToBlob );
79090       testcase( to_op==OP_ToNumeric );
79091       testcase( to_op==OP_ToInt );
79092       testcase( to_op==OP_ToReal );
79093       if( inReg!=target ){
79094         sqlite3VdbeAddOp2(v, OP_SCopy, inReg, target);
79095         inReg = target;
79096       }
79097       sqlite3VdbeAddOp1(v, to_op, inReg);
79098       testcase( usedAsColumnCache(pParse, inReg, inReg) );
79099       sqlite3ExprCacheAffinityChange(pParse, inReg, 1);
79100       break;
79101     }
79102 #endif /* SQLITE_OMIT_CAST */
79103     case TK_LT:
79104     case TK_LE:
79105     case TK_GT:
79106     case TK_GE:
79107     case TK_NE:
79108     case TK_EQ: {
79109       assert( TK_LT==OP_Lt );
79110       assert( TK_LE==OP_Le );
79111       assert( TK_GT==OP_Gt );
79112       assert( TK_GE==OP_Ge );
79113       assert( TK_EQ==OP_Eq );
79114       assert( TK_NE==OP_Ne );
79115       testcase( op==TK_LT );
79116       testcase( op==TK_LE );
79117       testcase( op==TK_GT );
79118       testcase( op==TK_GE );
79119       testcase( op==TK_EQ );
79120       testcase( op==TK_NE );
79121       r1 = sqlite3ExprCodeTemp(pParse, pExpr->pLeft, &regFree1);
79122       r2 = sqlite3ExprCodeTemp(pParse, pExpr->pRight, &regFree2);
79123       codeCompare(pParse, pExpr->pLeft, pExpr->pRight, op,
79124                   r1, r2, inReg, SQLITE_STOREP2);
79125       testcase( regFree1==0 );
79126       testcase( regFree2==0 );
79127       break;
79128     }
79129     case TK_IS:
79130     case TK_ISNOT: {
79131       testcase( op==TK_IS );
79132       testcase( op==TK_ISNOT );
79133       r1 = sqlite3ExprCodeTemp(pParse, pExpr->pLeft, &regFree1);
79134       r2 = sqlite3ExprCodeTemp(pParse, pExpr->pRight, &regFree2);
79135       op = (op==TK_IS) ? TK_EQ : TK_NE;
79136       codeCompare(pParse, pExpr->pLeft, pExpr->pRight, op,
79137                   r1, r2, inReg, SQLITE_STOREP2 | SQLITE_NULLEQ);
79138       testcase( regFree1==0 );
79139       testcase( regFree2==0 );
79140       break;
79141     }
79142     case TK_AND:
79143     case TK_OR:
79144     case TK_PLUS:
79145     case TK_STAR:
79146     case TK_MINUS:
79147     case TK_REM:
79148     case TK_BITAND:
79149     case TK_BITOR:
79150     case TK_SLASH:
79151     case TK_LSHIFT:
79152     case TK_RSHIFT: 
79153     case TK_CONCAT: {
79154       assert( TK_AND==OP_And );
79155       assert( TK_OR==OP_Or );
79156       assert( TK_PLUS==OP_Add );
79157       assert( TK_MINUS==OP_Subtract );
79158       assert( TK_REM==OP_Remainder );
79159       assert( TK_BITAND==OP_BitAnd );
79160       assert( TK_BITOR==OP_BitOr );
79161       assert( TK_SLASH==OP_Divide );
79162       assert( TK_LSHIFT==OP_ShiftLeft );
79163       assert( TK_RSHIFT==OP_ShiftRight );
79164       assert( TK_CONCAT==OP_Concat );
79165       testcase( op==TK_AND );
79166       testcase( op==TK_OR );
79167       testcase( op==TK_PLUS );
79168       testcase( op==TK_MINUS );
79169       testcase( op==TK_REM );
79170       testcase( op==TK_BITAND );
79171       testcase( op==TK_BITOR );
79172       testcase( op==TK_SLASH );
79173       testcase( op==TK_LSHIFT );
79174       testcase( op==TK_RSHIFT );
79175       testcase( op==TK_CONCAT );
79176       r1 = sqlite3ExprCodeTemp(pParse, pExpr->pLeft, &regFree1);
79177       r2 = sqlite3ExprCodeTemp(pParse, pExpr->pRight, &regFree2);
79178       sqlite3VdbeAddOp3(v, op, r2, r1, target);
79179       testcase( regFree1==0 );
79180       testcase( regFree2==0 );
79181       break;
79182     }
79183     case TK_UMINUS: {
79184       Expr *pLeft = pExpr->pLeft;
79185       assert( pLeft );
79186       if( pLeft->op==TK_INTEGER ){
79187         codeInteger(pParse, pLeft, 1, target);
79188 #ifndef SQLITE_OMIT_FLOATING_POINT
79189       }else if( pLeft->op==TK_FLOAT ){
79190         assert( !ExprHasProperty(pExpr, EP_IntValue) );
79191         codeReal(v, pLeft->u.zToken, 1, target);
79192 #endif
79193       }else{
79194         tempX.op = TK_INTEGER;
79195         tempX.flags = EP_IntValue|EP_TokenOnly;
79196         tempX.u.iValue = 0;
79197         r1 = sqlite3ExprCodeTemp(pParse, &tempX, &regFree1);
79198         r2 = sqlite3ExprCodeTemp(pParse, pExpr->pLeft, &regFree2);
79199         sqlite3VdbeAddOp3(v, OP_Subtract, r2, r1, target);
79200         testcase( regFree2==0 );
79201       }
79202       inReg = target;
79203       break;
79204     }
79205     case TK_BITNOT:
79206     case TK_NOT: {
79207       assert( TK_BITNOT==OP_BitNot );
79208       assert( TK_NOT==OP_Not );
79209       testcase( op==TK_BITNOT );
79210       testcase( op==TK_NOT );
79211       r1 = sqlite3ExprCodeTemp(pParse, pExpr->pLeft, &regFree1);
79212       testcase( regFree1==0 );
79213       inReg = target;
79214       sqlite3VdbeAddOp2(v, op, r1, inReg);
79215       break;
79216     }
79217     case TK_ISNULL:
79218     case TK_NOTNULL: {
79219       int addr;
79220       assert( TK_ISNULL==OP_IsNull );
79221       assert( TK_NOTNULL==OP_NotNull );
79222       testcase( op==TK_ISNULL );
79223       testcase( op==TK_NOTNULL );
79224       sqlite3VdbeAddOp2(v, OP_Integer, 1, target);
79225       r1 = sqlite3ExprCodeTemp(pParse, pExpr->pLeft, &regFree1);
79226       testcase( regFree1==0 );
79227       addr = sqlite3VdbeAddOp1(v, op, r1);
79228       sqlite3VdbeAddOp2(v, OP_AddImm, target, -1);
79229       sqlite3VdbeJumpHere(v, addr);
79230       break;
79231     }
79232     case TK_AGG_FUNCTION: {
79233       AggInfo *pInfo = pExpr->pAggInfo;
79234       if( pInfo==0 ){
79235         assert( !ExprHasProperty(pExpr, EP_IntValue) );
79236         sqlite3ErrorMsg(pParse, "misuse of aggregate: %s()", pExpr->u.zToken);
79237       }else{
79238         inReg = pInfo->aFunc[pExpr->iAgg].iMem;
79239       }
79240       break;
79241     }
79242     case TK_FUNCTION: {
79243       ExprList *pFarg;       /* List of function arguments */
79244       int nFarg;             /* Number of function arguments */
79245       FuncDef *pDef;         /* The function definition object */
79246       int nId;               /* Length of the function name in bytes */
79247       const char *zId;       /* The function name */
79248       int constMask = 0;     /* Mask of function arguments that are constant */
79249       int i;                 /* Loop counter */
79250       u8 enc = ENC(db);      /* The text encoding used by this database */
79251       CollSeq *pColl = 0;    /* A collating sequence */
79252 
79253       assert( !ExprHasProperty(pExpr, EP_xIsSelect) );
79254       if( ExprHasProperty(pExpr, EP_TokenOnly) ){
79255         pFarg = 0;
79256       }else{
79257         pFarg = pExpr->x.pList;
79258       }
79259       nFarg = pFarg ? pFarg->nExpr : 0;
79260       assert( !ExprHasProperty(pExpr, EP_IntValue) );
79261       zId = pExpr->u.zToken;
79262       nId = sqlite3Strlen30(zId);
79263       pDef = sqlite3FindFunction(db, zId, nId, nFarg, enc, 0);
79264       if( pDef==0 ){
79265         sqlite3ErrorMsg(pParse, "unknown function: %.*s()", nId, zId);
79266         break;
79267       }
79268 
79269       /* Attempt a direct implementation of the built-in COALESCE() and
79270       ** IFNULL() functions.  This avoids unnecessary evalation of
79271       ** arguments past the first non-NULL argument.
79272       */
79273       if( pDef->funcFlags & SQLITE_FUNC_COALESCE ){
79274         int endCoalesce = sqlite3VdbeMakeLabel(v);
79275         assert( nFarg>=2 );
79276         sqlite3ExprCode(pParse, pFarg->a[0].pExpr, target);
79277         for(i=1; i<nFarg; i++){
79278           sqlite3VdbeAddOp2(v, OP_NotNull, target, endCoalesce);
79279           sqlite3ExprCacheRemove(pParse, target, 1);
79280           sqlite3ExprCachePush(pParse);
79281           sqlite3ExprCode(pParse, pFarg->a[i].pExpr, target);
79282           sqlite3ExprCachePop(pParse, 1);
79283         }
79284         sqlite3VdbeResolveLabel(v, endCoalesce);
79285         break;
79286       }
79287 
79288       /* The UNLIKELY() function is a no-op.  The result is the value
79289       ** of the first argument.
79290       */
79291       if( pDef->funcFlags & SQLITE_FUNC_UNLIKELY ){
79292         assert( nFarg>=1 );
79293         sqlite3ExprCode(pParse, pFarg->a[0].pExpr, target);
79294         break;
79295       }
79296 
79297       for(i=0; i<nFarg; i++){
79298         if( i<32 && sqlite3ExprIsConstant(pFarg->a[i].pExpr) ){
79299           constMask |= (1<<i);
79300         }
79301         if( (pDef->funcFlags & SQLITE_FUNC_NEEDCOLL)!=0 && !pColl ){
79302           pColl = sqlite3ExprCollSeq(pParse, pFarg->a[i].pExpr);
79303         }
79304       }
79305       if( pFarg ){
79306         if( constMask ){
79307           r1 = pParse->nMem+1;
79308           pParse->nMem += nFarg;
79309         }else{
79310           r1 = sqlite3GetTempRange(pParse, nFarg);
79311         }
79312 
79313         /* For length() and typeof() functions with a column argument,
79314         ** set the P5 parameter to the OP_Column opcode to OPFLAG_LENGTHARG
79315         ** or OPFLAG_TYPEOFARG respectively, to avoid unnecessary data
79316         ** loading.
79317         */
79318         if( (pDef->funcFlags & (SQLITE_FUNC_LENGTH|SQLITE_FUNC_TYPEOF))!=0 ){
79319           u8 exprOp;
79320           assert( nFarg==1 );
79321           assert( pFarg->a[0].pExpr!=0 );
79322           exprOp = pFarg->a[0].pExpr->op;
79323           if( exprOp==TK_COLUMN || exprOp==TK_AGG_COLUMN ){
79324             assert( SQLITE_FUNC_LENGTH==OPFLAG_LENGTHARG );
79325             assert( SQLITE_FUNC_TYPEOF==OPFLAG_TYPEOFARG );
79326             testcase( pDef->funcFlags & OPFLAG_LENGTHARG );
79327             pFarg->a[0].pExpr->op2 = 
79328                   pDef->funcFlags & (OPFLAG_LENGTHARG|OPFLAG_TYPEOFARG);
79329           }
79330         }
79331 
79332         sqlite3ExprCachePush(pParse);     /* Ticket 2ea2425d34be */
79333         sqlite3ExprCodeExprList(pParse, pFarg, r1, 
79334                                 SQLITE_ECEL_DUP|SQLITE_ECEL_FACTOR);
79335         sqlite3ExprCachePop(pParse, 1);   /* Ticket 2ea2425d34be */
79336       }else{
79337         r1 = 0;
79338       }
79339 #ifndef SQLITE_OMIT_VIRTUALTABLE
79340       /* Possibly overload the function if the first argument is
79341       ** a virtual table column.
79342       **
79343       ** For infix functions (LIKE, GLOB, REGEXP, and MATCH) use the
79344       ** second argument, not the first, as the argument to test to
79345       ** see if it is a column in a virtual table.  This is done because
79346       ** the left operand of infix functions (the operand we want to
79347       ** control overloading) ends up as the second argument to the
79348       ** function.  The expression "A glob B" is equivalent to 
79349       ** "glob(B,A).  We want to use the A in "A glob B" to test
79350       ** for function overloading.  But we use the B term in "glob(B,A)".
79351       */
79352       if( nFarg>=2 && (pExpr->flags & EP_InfixFunc) ){
79353         pDef = sqlite3VtabOverloadFunction(db, pDef, nFarg, pFarg->a[1].pExpr);
79354       }else if( nFarg>0 ){
79355         pDef = sqlite3VtabOverloadFunction(db, pDef, nFarg, pFarg->a[0].pExpr);
79356       }
79357 #endif
79358       if( pDef->funcFlags & SQLITE_FUNC_NEEDCOLL ){
79359         if( !pColl ) pColl = db->pDfltColl; 
79360         sqlite3VdbeAddOp4(v, OP_CollSeq, 0, 0, 0, (char *)pColl, P4_COLLSEQ);
79361       }
79362       sqlite3VdbeAddOp4(v, OP_Function, constMask, r1, target,
79363                         (char*)pDef, P4_FUNCDEF);
79364       sqlite3VdbeChangeP5(v, (u8)nFarg);
79365       if( nFarg && constMask==0 ){
79366         sqlite3ReleaseTempRange(pParse, r1, nFarg);
79367       }
79368       break;
79369     }
79370 #ifndef SQLITE_OMIT_SUBQUERY
79371     case TK_EXISTS:
79372     case TK_SELECT: {
79373       testcase( op==TK_EXISTS );
79374       testcase( op==TK_SELECT );
79375       inReg = sqlite3CodeSubselect(pParse, pExpr, 0, 0);
79376       break;
79377     }
79378     case TK_IN: {
79379       int destIfFalse = sqlite3VdbeMakeLabel(v);
79380       int destIfNull = sqlite3VdbeMakeLabel(v);
79381       sqlite3VdbeAddOp2(v, OP_Null, 0, target);
79382       sqlite3ExprCodeIN(pParse, pExpr, destIfFalse, destIfNull);
79383       sqlite3VdbeAddOp2(v, OP_Integer, 1, target);
79384       sqlite3VdbeResolveLabel(v, destIfFalse);
79385       sqlite3VdbeAddOp2(v, OP_AddImm, target, 0);
79386       sqlite3VdbeResolveLabel(v, destIfNull);
79387       break;
79388     }
79389 #endif /* SQLITE_OMIT_SUBQUERY */
79390 
79391 
79392     /*
79393     **    x BETWEEN y AND z
79394     **
79395     ** This is equivalent to
79396     **
79397     **    x>=y AND x<=z
79398     **
79399     ** X is stored in pExpr->pLeft.
79400     ** Y is stored in pExpr->pList->a[0].pExpr.
79401     ** Z is stored in pExpr->pList->a[1].pExpr.
79402     */
79403     case TK_BETWEEN: {
79404       Expr *pLeft = pExpr->pLeft;
79405       struct ExprList_item *pLItem = pExpr->x.pList->a;
79406       Expr *pRight = pLItem->pExpr;
79407 
79408       r1 = sqlite3ExprCodeTemp(pParse, pLeft, &regFree1);
79409       r2 = sqlite3ExprCodeTemp(pParse, pRight, &regFree2);
79410       testcase( regFree1==0 );
79411       testcase( regFree2==0 );
79412       r3 = sqlite3GetTempReg(pParse);
79413       r4 = sqlite3GetTempReg(pParse);
79414       codeCompare(pParse, pLeft, pRight, OP_Ge,
79415                   r1, r2, r3, SQLITE_STOREP2);
79416       pLItem++;
79417       pRight = pLItem->pExpr;
79418       sqlite3ReleaseTempReg(pParse, regFree2);
79419       r2 = sqlite3ExprCodeTemp(pParse, pRight, &regFree2);
79420       testcase( regFree2==0 );
79421       codeCompare(pParse, pLeft, pRight, OP_Le, r1, r2, r4, SQLITE_STOREP2);
79422       sqlite3VdbeAddOp3(v, OP_And, r3, r4, target);
79423       sqlite3ReleaseTempReg(pParse, r3);
79424       sqlite3ReleaseTempReg(pParse, r4);
79425       break;
79426     }
79427     case TK_COLLATE: 
79428     case TK_UPLUS: {
79429       inReg = sqlite3ExprCodeTarget(pParse, pExpr->pLeft, target);
79430       break;
79431     }
79432 
79433     case TK_TRIGGER: {
79434       /* If the opcode is TK_TRIGGER, then the expression is a reference
79435       ** to a column in the new.* or old.* pseudo-tables available to
79436       ** trigger programs. In this case Expr.iTable is set to 1 for the
79437       ** new.* pseudo-table, or 0 for the old.* pseudo-table. Expr.iColumn
79438       ** is set to the column of the pseudo-table to read, or to -1 to
79439       ** read the rowid field.
79440       **
79441       ** The expression is implemented using an OP_Param opcode. The p1
79442       ** parameter is set to 0 for an old.rowid reference, or to (i+1)
79443       ** to reference another column of the old.* pseudo-table, where 
79444       ** i is the index of the column. For a new.rowid reference, p1 is
79445       ** set to (n+1), where n is the number of columns in each pseudo-table.
79446       ** For a reference to any other column in the new.* pseudo-table, p1
79447       ** is set to (n+2+i), where n and i are as defined previously. For
79448       ** example, if the table on which triggers are being fired is
79449       ** declared as:
79450       **
79451       **   CREATE TABLE t1(a, b);
79452       **
79453       ** Then p1 is interpreted as follows:
79454       **
79455       **   p1==0   ->    old.rowid     p1==3   ->    new.rowid
79456       **   p1==1   ->    old.a         p1==4   ->    new.a
79457       **   p1==2   ->    old.b         p1==5   ->    new.b       
79458       */
79459       Table *pTab = pExpr->pTab;
79460       int p1 = pExpr->iTable * (pTab->nCol+1) + 1 + pExpr->iColumn;
79461 
79462       assert( pExpr->iTable==0 || pExpr->iTable==1 );
79463       assert( pExpr->iColumn>=-1 && pExpr->iColumn<pTab->nCol );
79464       assert( pTab->iPKey<0 || pExpr->iColumn!=pTab->iPKey );
79465       assert( p1>=0 && p1<(pTab->nCol*2+2) );
79466 
79467       sqlite3VdbeAddOp2(v, OP_Param, p1, target);
79468       VdbeComment((v, "%s.%s -> $%d",
79469         (pExpr->iTable ? "new" : "old"),
79470         (pExpr->iColumn<0 ? "rowid" : pExpr->pTab->aCol[pExpr->iColumn].zName),
79471         target
79472       ));
79473 
79474 #ifndef SQLITE_OMIT_FLOATING_POINT
79475       /* If the column has REAL affinity, it may currently be stored as an
79476       ** integer. Use OP_RealAffinity to make sure it is really real.  */
79477       if( pExpr->iColumn>=0 
79478        && pTab->aCol[pExpr->iColumn].affinity==SQLITE_AFF_REAL
79479       ){
79480         sqlite3VdbeAddOp1(v, OP_RealAffinity, target);
79481       }
79482 #endif
79483       break;
79484     }
79485 
79486 
79487     /*
79488     ** Form A:
79489     **   CASE x WHEN e1 THEN r1 WHEN e2 THEN r2 ... WHEN eN THEN rN ELSE y END
79490     **
79491     ** Form B:
79492     **   CASE WHEN e1 THEN r1 WHEN e2 THEN r2 ... WHEN eN THEN rN ELSE y END
79493     **
79494     ** Form A is can be transformed into the equivalent form B as follows:
79495     **   CASE WHEN x=e1 THEN r1 WHEN x=e2 THEN r2 ...
79496     **        WHEN x=eN THEN rN ELSE y END
79497     **
79498     ** X (if it exists) is in pExpr->pLeft.
79499     ** Y is in the last element of pExpr->x.pList if pExpr->x.pList->nExpr is
79500     ** odd.  The Y is also optional.  If the number of elements in x.pList
79501     ** is even, then Y is omitted and the "otherwise" result is NULL.
79502     ** Ei is in pExpr->pList->a[i*2] and Ri is pExpr->pList->a[i*2+1].
79503     **
79504     ** The result of the expression is the Ri for the first matching Ei,
79505     ** or if there is no matching Ei, the ELSE term Y, or if there is
79506     ** no ELSE term, NULL.
79507     */
79508     default: assert( op==TK_CASE ); {
79509       int endLabel;                     /* GOTO label for end of CASE stmt */
79510       int nextCase;                     /* GOTO label for next WHEN clause */
79511       int nExpr;                        /* 2x number of WHEN terms */
79512       int i;                            /* Loop counter */
79513       ExprList *pEList;                 /* List of WHEN terms */
79514       struct ExprList_item *aListelem;  /* Array of WHEN terms */
79515       Expr opCompare;                   /* The X==Ei expression */
79516       Expr *pX;                         /* The X expression */
79517       Expr *pTest = 0;                  /* X==Ei (form A) or just Ei (form B) */
79518       VVA_ONLY( int iCacheLevel = pParse->iCacheLevel; )
79519 
79520       assert( !ExprHasProperty(pExpr, EP_xIsSelect) && pExpr->x.pList );
79521       assert(pExpr->x.pList->nExpr > 0);
79522       pEList = pExpr->x.pList;
79523       aListelem = pEList->a;
79524       nExpr = pEList->nExpr;
79525       endLabel = sqlite3VdbeMakeLabel(v);
79526       if( (pX = pExpr->pLeft)!=0 ){
79527         tempX = *pX;
79528         testcase( pX->op==TK_COLUMN );
79529         exprToRegister(&tempX, sqlite3ExprCodeTemp(pParse, pX, &regFree1));
79530         testcase( regFree1==0 );
79531         opCompare.op = TK_EQ;
79532         opCompare.pLeft = &tempX;
79533         pTest = &opCompare;
79534         /* Ticket b351d95f9cd5ef17e9d9dbae18f5ca8611190001:
79535         ** The value in regFree1 might get SCopy-ed into the file result.
79536         ** So make sure that the regFree1 register is not reused for other
79537         ** purposes and possibly overwritten.  */
79538         regFree1 = 0;
79539       }
79540       for(i=0; i<nExpr-1; i=i+2){
79541         sqlite3ExprCachePush(pParse);
79542         if( pX ){
79543           assert( pTest!=0 );
79544           opCompare.pRight = aListelem[i].pExpr;
79545         }else{
79546           pTest = aListelem[i].pExpr;
79547         }
79548         nextCase = sqlite3VdbeMakeLabel(v);
79549         testcase( pTest->op==TK_COLUMN );
79550         sqlite3ExprIfFalse(pParse, pTest, nextCase, SQLITE_JUMPIFNULL);
79551         testcase( aListelem[i+1].pExpr->op==TK_COLUMN );
79552         sqlite3ExprCode(pParse, aListelem[i+1].pExpr, target);
79553         sqlite3VdbeAddOp2(v, OP_Goto, 0, endLabel);
79554         sqlite3ExprCachePop(pParse, 1);
79555         sqlite3VdbeResolveLabel(v, nextCase);
79556       }
79557       if( (nExpr&1)!=0 ){
79558         sqlite3ExprCachePush(pParse);
79559         sqlite3ExprCode(pParse, pEList->a[nExpr-1].pExpr, target);
79560         sqlite3ExprCachePop(pParse, 1);
79561       }else{
79562         sqlite3VdbeAddOp2(v, OP_Null, 0, target);
79563       }
79564       assert( db->mallocFailed || pParse->nErr>0 
79565            || pParse->iCacheLevel==iCacheLevel );
79566       sqlite3VdbeResolveLabel(v, endLabel);
79567       break;
79568     }
79569 #ifndef SQLITE_OMIT_TRIGGER
79570     case TK_RAISE: {
79571       assert( pExpr->affinity==OE_Rollback 
79572            || pExpr->affinity==OE_Abort
79573            || pExpr->affinity==OE_Fail
79574            || pExpr->affinity==OE_Ignore
79575       );
79576       if( !pParse->pTriggerTab ){
79577         sqlite3ErrorMsg(pParse,
79578                        "RAISE() may only be used within a trigger-program");
79579         return 0;
79580       }
79581       if( pExpr->affinity==OE_Abort ){
79582         sqlite3MayAbort(pParse);
79583       }
79584       assert( !ExprHasProperty(pExpr, EP_IntValue) );
79585       if( pExpr->affinity==OE_Ignore ){
79586         sqlite3VdbeAddOp4(
79587             v, OP_Halt, SQLITE_OK, OE_Ignore, 0, pExpr->u.zToken,0);
79588       }else{
79589         sqlite3HaltConstraint(pParse, SQLITE_CONSTRAINT_TRIGGER,
79590                               pExpr->affinity, pExpr->u.zToken, 0, 0);
79591       }
79592 
79593       break;
79594     }
79595 #endif
79596   }
79597   sqlite3ReleaseTempReg(pParse, regFree1);
79598   sqlite3ReleaseTempReg(pParse, regFree2);
79599   return inReg;
79600 }
79601 
79602 /*
79603 ** Factor out the code of the given expression to initialization time.
79604 */
79605 SQLITE_PRIVATE void sqlite3ExprCodeAtInit(
79606   Parse *pParse,    /* Parsing context */
79607   Expr *pExpr,      /* The expression to code when the VDBE initializes */
79608   int regDest,      /* Store the value in this register */
79609   u8 reusable       /* True if this expression is reusable */
79610 ){
79611   ExprList *p;
79612   assert( ConstFactorOk(pParse) );
79613   p = pParse->pConstExpr;
79614   pExpr = sqlite3ExprDup(pParse->db, pExpr, 0);
79615   p = sqlite3ExprListAppend(pParse, p, pExpr);
79616   if( p ){
79617      struct ExprList_item *pItem = &p->a[p->nExpr-1];
79618      pItem->u.iConstExprReg = regDest;
79619      pItem->reusable = reusable;
79620   }
79621   pParse->pConstExpr = p;
79622 }
79623 
79624 /*
79625 ** Generate code to evaluate an expression and store the results
79626 ** into a register.  Return the register number where the results
79627 ** are stored.
79628 **
79629 ** If the register is a temporary register that can be deallocated,
79630 ** then write its number into *pReg.  If the result register is not
79631 ** a temporary, then set *pReg to zero.
79632 **
79633 ** If pExpr is a constant, then this routine might generate this
79634 ** code to fill the register in the initialization section of the
79635 ** VDBE program, in order to factor it out of the evaluation loop.
79636 */
79637 SQLITE_PRIVATE int sqlite3ExprCodeTemp(Parse *pParse, Expr *pExpr, int *pReg){
79638   int r2;
79639   pExpr = sqlite3ExprSkipCollate(pExpr);
79640   if( ConstFactorOk(pParse)
79641    && pExpr->op!=TK_REGISTER
79642    && sqlite3ExprIsConstantNotJoin(pExpr)
79643   ){
79644     ExprList *p = pParse->pConstExpr;
79645     int i;
79646     *pReg  = 0;
79647     if( p ){
79648       struct ExprList_item *pItem;
79649       for(pItem=p->a, i=p->nExpr; i>0; pItem++, i--){
79650         if( pItem->reusable && sqlite3ExprCompare(pItem->pExpr,pExpr,-1)==0 ){
79651           return pItem->u.iConstExprReg;
79652         }
79653       }
79654     }
79655     r2 = ++pParse->nMem;
79656     sqlite3ExprCodeAtInit(pParse, pExpr, r2, 1);
79657   }else{
79658     int r1 = sqlite3GetTempReg(pParse);
79659     r2 = sqlite3ExprCodeTarget(pParse, pExpr, r1);
79660     if( r2==r1 ){
79661       *pReg = r1;
79662     }else{
79663       sqlite3ReleaseTempReg(pParse, r1);
79664       *pReg = 0;
79665     }
79666   }
79667   return r2;
79668 }
79669 
79670 /*
79671 ** Generate code that will evaluate expression pExpr and store the
79672 ** results in register target.  The results are guaranteed to appear
79673 ** in register target.
79674 */
79675 SQLITE_PRIVATE int sqlite3ExprCode(Parse *pParse, Expr *pExpr, int target){
79676   int inReg;
79677 
79678   assert( target>0 && target<=pParse->nMem );
79679   if( pExpr && pExpr->op==TK_REGISTER ){
79680     sqlite3VdbeAddOp2(pParse->pVdbe, OP_Copy, pExpr->iTable, target);
79681   }else{
79682     inReg = sqlite3ExprCodeTarget(pParse, pExpr, target);
79683     assert( pParse->pVdbe || pParse->db->mallocFailed );
79684     if( inReg!=target && pParse->pVdbe ){
79685       sqlite3VdbeAddOp2(pParse->pVdbe, OP_SCopy, inReg, target);
79686     }
79687   }
79688   return target;
79689 }
79690 
79691 /*
79692 ** Generate code that evalutes the given expression and puts the result
79693 ** in register target.
79694 **
79695 ** Also make a copy of the expression results into another "cache" register
79696 ** and modify the expression so that the next time it is evaluated,
79697 ** the result is a copy of the cache register.
79698 **
79699 ** This routine is used for expressions that are used multiple 
79700 ** times.  They are evaluated once and the results of the expression
79701 ** are reused.
79702 */
79703 SQLITE_PRIVATE int sqlite3ExprCodeAndCache(Parse *pParse, Expr *pExpr, int target){
79704   Vdbe *v = pParse->pVdbe;
79705   int inReg;
79706   inReg = sqlite3ExprCode(pParse, pExpr, target);
79707   assert( target>0 );
79708   /* The only place, other than this routine, where expressions can be
79709   ** converted to TK_REGISTER is internal subexpressions in BETWEEN and
79710   ** CASE operators.  Neither ever calls this routine.  And this routine
79711   ** is never called twice on the same expression.  Hence it is impossible
79712   ** for the input to this routine to already be a register.  Nevertheless,
79713   ** it seems prudent to keep the ALWAYS() in case the conditions above
79714   ** change with future modifications or enhancements. */
79715   if( ALWAYS(pExpr->op!=TK_REGISTER) ){  
79716     int iMem;
79717     iMem = ++pParse->nMem;
79718     sqlite3VdbeAddOp2(v, OP_Copy, inReg, iMem);
79719     exprToRegister(pExpr, iMem);
79720   }
79721   return inReg;
79722 }
79723 
79724 #if defined(SQLITE_ENABLE_TREE_EXPLAIN)
79725 /*
79726 ** Generate a human-readable explanation of an expression tree.
79727 */
79728 SQLITE_PRIVATE void sqlite3ExplainExpr(Vdbe *pOut, Expr *pExpr){
79729   int op;                   /* The opcode being coded */
79730   const char *zBinOp = 0;   /* Binary operator */
79731   const char *zUniOp = 0;   /* Unary operator */
79732   if( pExpr==0 ){
79733     op = TK_NULL;
79734   }else{
79735     op = pExpr->op;
79736   }
79737   switch( op ){
79738     case TK_AGG_COLUMN: {
79739       sqlite3ExplainPrintf(pOut, "AGG{%d:%d}",
79740             pExpr->iTable, pExpr->iColumn);
79741       break;
79742     }
79743     case TK_COLUMN: {
79744       if( pExpr->iTable<0 ){
79745         /* This only happens when coding check constraints */
79746         sqlite3ExplainPrintf(pOut, "COLUMN(%d)", pExpr->iColumn);
79747       }else{
79748         sqlite3ExplainPrintf(pOut, "{%d:%d}",
79749                              pExpr->iTable, pExpr->iColumn);
79750       }
79751       break;
79752     }
79753     case TK_INTEGER: {
79754       if( pExpr->flags & EP_IntValue ){
79755         sqlite3ExplainPrintf(pOut, "%d", pExpr->u.iValue);
79756       }else{
79757         sqlite3ExplainPrintf(pOut, "%s", pExpr->u.zToken);
79758       }
79759       break;
79760     }
79761 #ifndef SQLITE_OMIT_FLOATING_POINT
79762     case TK_FLOAT: {
79763       sqlite3ExplainPrintf(pOut,"%s", pExpr->u.zToken);
79764       break;
79765     }
79766 #endif
79767     case TK_STRING: {
79768       sqlite3ExplainPrintf(pOut,"%Q", pExpr->u.zToken);
79769       break;
79770     }
79771     case TK_NULL: {
79772       sqlite3ExplainPrintf(pOut,"NULL");
79773       break;
79774     }
79775 #ifndef SQLITE_OMIT_BLOB_LITERAL
79776     case TK_BLOB: {
79777       sqlite3ExplainPrintf(pOut,"%s", pExpr->u.zToken);
79778       break;
79779     }
79780 #endif
79781     case TK_VARIABLE: {
79782       sqlite3ExplainPrintf(pOut,"VARIABLE(%s,%d)",
79783                            pExpr->u.zToken, pExpr->iColumn);
79784       break;
79785     }
79786     case TK_REGISTER: {
79787       sqlite3ExplainPrintf(pOut,"REGISTER(%d)", pExpr->iTable);
79788       break;
79789     }
79790     case TK_AS: {
79791       sqlite3ExplainExpr(pOut, pExpr->pLeft);
79792       break;
79793     }
79794 #ifndef SQLITE_OMIT_CAST
79795     case TK_CAST: {
79796       /* Expressions of the form:   CAST(pLeft AS token) */
79797       const char *zAff = "unk";
79798       switch( sqlite3AffinityType(pExpr->u.zToken, 0) ){
79799         case SQLITE_AFF_TEXT:    zAff = "TEXT";     break;
79800         case SQLITE_AFF_NONE:    zAff = "NONE";     break;
79801         case SQLITE_AFF_NUMERIC: zAff = "NUMERIC";  break;
79802         case SQLITE_AFF_INTEGER: zAff = "INTEGER";  break;
79803         case SQLITE_AFF_REAL:    zAff = "REAL";     break;
79804       }
79805       sqlite3ExplainPrintf(pOut, "CAST-%s(", zAff);
79806       sqlite3ExplainExpr(pOut, pExpr->pLeft);
79807       sqlite3ExplainPrintf(pOut, ")");
79808       break;
79809     }
79810 #endif /* SQLITE_OMIT_CAST */
79811     case TK_LT:      zBinOp = "LT";     break;
79812     case TK_LE:      zBinOp = "LE";     break;
79813     case TK_GT:      zBinOp = "GT";     break;
79814     case TK_GE:      zBinOp = "GE";     break;
79815     case TK_NE:      zBinOp = "NE";     break;
79816     case TK_EQ:      zBinOp = "EQ";     break;
79817     case TK_IS:      zBinOp = "IS";     break;
79818     case TK_ISNOT:   zBinOp = "ISNOT";  break;
79819     case TK_AND:     zBinOp = "AND";    break;
79820     case TK_OR:      zBinOp = "OR";     break;
79821     case TK_PLUS:    zBinOp = "ADD";    break;
79822     case TK_STAR:    zBinOp = "MUL";    break;
79823     case TK_MINUS:   zBinOp = "SUB";    break;
79824     case TK_REM:     zBinOp = "REM";    break;
79825     case TK_BITAND:  zBinOp = "BITAND"; break;
79826     case TK_BITOR:   zBinOp = "BITOR";  break;
79827     case TK_SLASH:   zBinOp = "DIV";    break;
79828     case TK_LSHIFT:  zBinOp = "LSHIFT"; break;
79829     case TK_RSHIFT:  zBinOp = "RSHIFT"; break;
79830     case TK_CONCAT:  zBinOp = "CONCAT"; break;
79831 
79832     case TK_UMINUS:  zUniOp = "UMINUS"; break;
79833     case TK_UPLUS:   zUniOp = "UPLUS";  break;
79834     case TK_BITNOT:  zUniOp = "BITNOT"; break;
79835     case TK_NOT:     zUniOp = "NOT";    break;
79836     case TK_ISNULL:  zUniOp = "ISNULL"; break;
79837     case TK_NOTNULL: zUniOp = "NOTNULL"; break;
79838 
79839     case TK_COLLATE: {
79840       sqlite3ExplainExpr(pOut, pExpr->pLeft);
79841       sqlite3ExplainPrintf(pOut,".COLLATE(%s)",pExpr->u.zToken);
79842       break;
79843     }
79844 
79845     case TK_AGG_FUNCTION:
79846     case TK_FUNCTION: {
79847       ExprList *pFarg;       /* List of function arguments */
79848       if( ExprHasProperty(pExpr, EP_TokenOnly) ){
79849         pFarg = 0;
79850       }else{
79851         pFarg = pExpr->x.pList;
79852       }
79853       if( op==TK_AGG_FUNCTION ){
79854         sqlite3ExplainPrintf(pOut, "AGG_FUNCTION%d:%s(",
79855                              pExpr->op2, pExpr->u.zToken);
79856       }else{
79857         sqlite3ExplainPrintf(pOut, "FUNCTION:%s(", pExpr->u.zToken);
79858       }
79859       if( pFarg ){
79860         sqlite3ExplainExprList(pOut, pFarg);
79861       }
79862       sqlite3ExplainPrintf(pOut, ")");
79863       break;
79864     }
79865 #ifndef SQLITE_OMIT_SUBQUERY
79866     case TK_EXISTS: {
79867       sqlite3ExplainPrintf(pOut, "EXISTS(");
79868       sqlite3ExplainSelect(pOut, pExpr->x.pSelect);
79869       sqlite3ExplainPrintf(pOut,")");
79870       break;
79871     }
79872     case TK_SELECT: {
79873       sqlite3ExplainPrintf(pOut, "(");
79874       sqlite3ExplainSelect(pOut, pExpr->x.pSelect);
79875       sqlite3ExplainPrintf(pOut, ")");
79876       break;
79877     }
79878     case TK_IN: {
79879       sqlite3ExplainPrintf(pOut, "IN(");
79880       sqlite3ExplainExpr(pOut, pExpr->pLeft);
79881       sqlite3ExplainPrintf(pOut, ",");
79882       if( ExprHasProperty(pExpr, EP_xIsSelect) ){
79883         sqlite3ExplainSelect(pOut, pExpr->x.pSelect);
79884       }else{
79885         sqlite3ExplainExprList(pOut, pExpr->x.pList);
79886       }
79887       sqlite3ExplainPrintf(pOut, ")");
79888       break;
79889     }
79890 #endif /* SQLITE_OMIT_SUBQUERY */
79891 
79892     /*
79893     **    x BETWEEN y AND z
79894     **
79895     ** This is equivalent to
79896     **
79897     **    x>=y AND x<=z
79898     **
79899     ** X is stored in pExpr->pLeft.
79900     ** Y is stored in pExpr->pList->a[0].pExpr.
79901     ** Z is stored in pExpr->pList->a[1].pExpr.
79902     */
79903     case TK_BETWEEN: {
79904       Expr *pX = pExpr->pLeft;
79905       Expr *pY = pExpr->x.pList->a[0].pExpr;
79906       Expr *pZ = pExpr->x.pList->a[1].pExpr;
79907       sqlite3ExplainPrintf(pOut, "BETWEEN(");
79908       sqlite3ExplainExpr(pOut, pX);
79909       sqlite3ExplainPrintf(pOut, ",");
79910       sqlite3ExplainExpr(pOut, pY);
79911       sqlite3ExplainPrintf(pOut, ",");
79912       sqlite3ExplainExpr(pOut, pZ);
79913       sqlite3ExplainPrintf(pOut, ")");
79914       break;
79915     }
79916     case TK_TRIGGER: {
79917       /* If the opcode is TK_TRIGGER, then the expression is a reference
79918       ** to a column in the new.* or old.* pseudo-tables available to
79919       ** trigger programs. In this case Expr.iTable is set to 1 for the
79920       ** new.* pseudo-table, or 0 for the old.* pseudo-table. Expr.iColumn
79921       ** is set to the column of the pseudo-table to read, or to -1 to
79922       ** read the rowid field.
79923       */
79924       sqlite3ExplainPrintf(pOut, "%s(%d)", 
79925           pExpr->iTable ? "NEW" : "OLD", pExpr->iColumn);
79926       break;
79927     }
79928     case TK_CASE: {
79929       sqlite3ExplainPrintf(pOut, "CASE(");
79930       sqlite3ExplainExpr(pOut, pExpr->pLeft);
79931       sqlite3ExplainPrintf(pOut, ",");
79932       sqlite3ExplainExprList(pOut, pExpr->x.pList);
79933       break;
79934     }
79935 #ifndef SQLITE_OMIT_TRIGGER
79936     case TK_RAISE: {
79937       const char *zType = "unk";
79938       switch( pExpr->affinity ){
79939         case OE_Rollback:   zType = "rollback";  break;
79940         case OE_Abort:      zType = "abort";     break;
79941         case OE_Fail:       zType = "fail";      break;
79942         case OE_Ignore:     zType = "ignore";    break;
79943       }
79944       sqlite3ExplainPrintf(pOut, "RAISE-%s(%s)", zType, pExpr->u.zToken);
79945       break;
79946     }
79947 #endif
79948   }
79949   if( zBinOp ){
79950     sqlite3ExplainPrintf(pOut,"%s(", zBinOp);
79951     sqlite3ExplainExpr(pOut, pExpr->pLeft);
79952     sqlite3ExplainPrintf(pOut,",");
79953     sqlite3ExplainExpr(pOut, pExpr->pRight);
79954     sqlite3ExplainPrintf(pOut,")");
79955   }else if( zUniOp ){
79956     sqlite3ExplainPrintf(pOut,"%s(", zUniOp);
79957     sqlite3ExplainExpr(pOut, pExpr->pLeft);
79958     sqlite3ExplainPrintf(pOut,")");
79959   }
79960 }
79961 #endif /* defined(SQLITE_ENABLE_TREE_EXPLAIN) */
79962 
79963 #if defined(SQLITE_ENABLE_TREE_EXPLAIN)
79964 /*
79965 ** Generate a human-readable explanation of an expression list.
79966 */
79967 SQLITE_PRIVATE void sqlite3ExplainExprList(Vdbe *pOut, ExprList *pList){
79968   int i;
79969   if( pList==0 || pList->nExpr==0 ){
79970     sqlite3ExplainPrintf(pOut, "(empty-list)");
79971     return;
79972   }else if( pList->nExpr==1 ){
79973     sqlite3ExplainExpr(pOut, pList->a[0].pExpr);
79974   }else{
79975     sqlite3ExplainPush(pOut);
79976     for(i=0; i<pList->nExpr; i++){
79977       sqlite3ExplainPrintf(pOut, "item[%d] = ", i);
79978       sqlite3ExplainPush(pOut);
79979       sqlite3ExplainExpr(pOut, pList->a[i].pExpr);
79980       sqlite3ExplainPop(pOut);
79981       if( pList->a[i].zName ){
79982         sqlite3ExplainPrintf(pOut, " AS %s", pList->a[i].zName);
79983       }
79984       if( pList->a[i].bSpanIsTab ){
79985         sqlite3ExplainPrintf(pOut, " (%s)", pList->a[i].zSpan);
79986       }
79987       if( i<pList->nExpr-1 ){
79988         sqlite3ExplainNL(pOut);
79989       }
79990     }
79991     sqlite3ExplainPop(pOut);
79992   }
79993 }
79994 #endif /* SQLITE_DEBUG */
79995 
79996 /*
79997 ** Generate code that pushes the value of every element of the given
79998 ** expression list into a sequence of registers beginning at target.
79999 **
80000 ** Return the number of elements evaluated.
80001 **
80002 ** The SQLITE_ECEL_DUP flag prevents the arguments from being
80003 ** filled using OP_SCopy.  OP_Copy must be used instead.
80004 **
80005 ** The SQLITE_ECEL_FACTOR argument allows constant arguments to be
80006 ** factored out into initialization code.
80007 */
80008 SQLITE_PRIVATE int sqlite3ExprCodeExprList(
80009   Parse *pParse,     /* Parsing context */
80010   ExprList *pList,   /* The expression list to be coded */
80011   int target,        /* Where to write results */
80012   u8 flags           /* SQLITE_ECEL_* flags */
80013 ){
80014   struct ExprList_item *pItem;
80015   int i, n;
80016   u8 copyOp = (flags & SQLITE_ECEL_DUP) ? OP_Copy : OP_SCopy;
80017   assert( pList!=0 );
80018   assert( target>0 );
80019   assert( pParse->pVdbe!=0 );  /* Never gets this far otherwise */
80020   n = pList->nExpr;
80021   if( !ConstFactorOk(pParse) ) flags &= ~SQLITE_ECEL_FACTOR;
80022   for(pItem=pList->a, i=0; i<n; i++, pItem++){
80023     Expr *pExpr = pItem->pExpr;
80024     if( (flags & SQLITE_ECEL_FACTOR)!=0 && sqlite3ExprIsConstant(pExpr) ){
80025       sqlite3ExprCodeAtInit(pParse, pExpr, target+i, 0);
80026     }else{
80027       int inReg = sqlite3ExprCodeTarget(pParse, pExpr, target+i);
80028       if( inReg!=target+i ){
80029         sqlite3VdbeAddOp2(pParse->pVdbe, copyOp, inReg, target+i);
80030       }
80031     }
80032   }
80033   return n;
80034 }
80035 
80036 /*
80037 ** Generate code for a BETWEEN operator.
80038 **
80039 **    x BETWEEN y AND z
80040 **
80041 ** The above is equivalent to 
80042 **
80043 **    x>=y AND x<=z
80044 **
80045 ** Code it as such, taking care to do the common subexpression
80046 ** elementation of x.
80047 */
80048 static void exprCodeBetween(
80049   Parse *pParse,    /* Parsing and code generating context */
80050   Expr *pExpr,      /* The BETWEEN expression */
80051   int dest,         /* Jump here if the jump is taken */
80052   int jumpIfTrue,   /* Take the jump if the BETWEEN is true */
80053   int jumpIfNull    /* Take the jump if the BETWEEN is NULL */
80054 ){
80055   Expr exprAnd;     /* The AND operator in  x>=y AND x<=z  */
80056   Expr compLeft;    /* The  x>=y  term */
80057   Expr compRight;   /* The  x<=z  term */
80058   Expr exprX;       /* The  x  subexpression */
80059   int regFree1 = 0; /* Temporary use register */
80060 
80061   assert( !ExprHasProperty(pExpr, EP_xIsSelect) );
80062   exprX = *pExpr->pLeft;
80063   exprAnd.op = TK_AND;
80064   exprAnd.pLeft = &compLeft;
80065   exprAnd.pRight = &compRight;
80066   compLeft.op = TK_GE;
80067   compLeft.pLeft = &exprX;
80068   compLeft.pRight = pExpr->x.pList->a[0].pExpr;
80069   compRight.op = TK_LE;
80070   compRight.pLeft = &exprX;
80071   compRight.pRight = pExpr->x.pList->a[1].pExpr;
80072   exprToRegister(&exprX, sqlite3ExprCodeTemp(pParse, &exprX, &regFree1));
80073   if( jumpIfTrue ){
80074     sqlite3ExprIfTrue(pParse, &exprAnd, dest, jumpIfNull);
80075   }else{
80076     sqlite3ExprIfFalse(pParse, &exprAnd, dest, jumpIfNull);
80077   }
80078   sqlite3ReleaseTempReg(pParse, regFree1);
80079 
80080   /* Ensure adequate test coverage */
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   testcase( jumpIfTrue!=0 && jumpIfNull!=0 && regFree1!=0 );
80089 }
80090 
80091 /*
80092 ** Generate code for a boolean expression such that a jump is made
80093 ** to the label "dest" if the expression is true but execution
80094 ** continues straight thru if the expression is false.
80095 **
80096 ** If the expression evaluates to NULL (neither true nor false), then
80097 ** take the jump if the jumpIfNull flag is SQLITE_JUMPIFNULL.
80098 **
80099 ** This code depends on the fact that certain token values (ex: TK_EQ)
80100 ** are the same as opcode values (ex: OP_Eq) that implement the corresponding
80101 ** operation.  Special comments in vdbe.c and the mkopcodeh.awk script in
80102 ** the make process cause these values to align.  Assert()s in the code
80103 ** below verify that the numbers are aligned correctly.
80104 */
80105 SQLITE_PRIVATE void sqlite3ExprIfTrue(Parse *pParse, Expr *pExpr, int dest, int jumpIfNull){
80106   Vdbe *v = pParse->pVdbe;
80107   int op = 0;
80108   int regFree1 = 0;
80109   int regFree2 = 0;
80110   int r1, r2;
80111 
80112   assert( jumpIfNull==SQLITE_JUMPIFNULL || jumpIfNull==0 );
80113   if( NEVER(v==0) )     return;  /* Existence of VDBE checked by caller */
80114   if( NEVER(pExpr==0) ) return;  /* No way this can happen */
80115   op = pExpr->op;
80116   switch( op ){
80117     case TK_AND: {
80118       int d2 = sqlite3VdbeMakeLabel(v);
80119       testcase( jumpIfNull==0 );
80120       sqlite3ExprCachePush(pParse);
80121       sqlite3ExprIfFalse(pParse, pExpr->pLeft, d2,jumpIfNull^SQLITE_JUMPIFNULL);
80122       sqlite3ExprIfTrue(pParse, pExpr->pRight, dest, jumpIfNull);
80123       sqlite3VdbeResolveLabel(v, d2);
80124       sqlite3ExprCachePop(pParse, 1);
80125       break;
80126     }
80127     case TK_OR: {
80128       testcase( jumpIfNull==0 );
80129       sqlite3ExprIfTrue(pParse, pExpr->pLeft, dest, jumpIfNull);
80130       sqlite3ExprIfTrue(pParse, pExpr->pRight, dest, jumpIfNull);
80131       break;
80132     }
80133     case TK_NOT: {
80134       testcase( jumpIfNull==0 );
80135       sqlite3ExprIfFalse(pParse, pExpr->pLeft, dest, jumpIfNull);
80136       break;
80137     }
80138     case TK_LT:
80139     case TK_LE:
80140     case TK_GT:
80141     case TK_GE:
80142     case TK_NE:
80143     case TK_EQ: {
80144       assert( TK_LT==OP_Lt );
80145       assert( TK_LE==OP_Le );
80146       assert( TK_GT==OP_Gt );
80147       assert( TK_GE==OP_Ge );
80148       assert( TK_EQ==OP_Eq );
80149       assert( TK_NE==OP_Ne );
80150       testcase( op==TK_LT );
80151       testcase( op==TK_LE );
80152       testcase( op==TK_GT );
80153       testcase( op==TK_GE );
80154       testcase( op==TK_EQ );
80155       testcase( op==TK_NE );
80156       testcase( jumpIfNull==0 );
80157       r1 = sqlite3ExprCodeTemp(pParse, pExpr->pLeft, &regFree1);
80158       r2 = sqlite3ExprCodeTemp(pParse, pExpr->pRight, &regFree2);
80159       codeCompare(pParse, pExpr->pLeft, pExpr->pRight, op,
80160                   r1, r2, dest, jumpIfNull);
80161       testcase( regFree1==0 );
80162       testcase( regFree2==0 );
80163       break;
80164     }
80165     case TK_IS:
80166     case TK_ISNOT: {
80167       testcase( op==TK_IS );
80168       testcase( op==TK_ISNOT );
80169       r1 = sqlite3ExprCodeTemp(pParse, pExpr->pLeft, &regFree1);
80170       r2 = sqlite3ExprCodeTemp(pParse, pExpr->pRight, &regFree2);
80171       op = (op==TK_IS) ? TK_EQ : TK_NE;
80172       codeCompare(pParse, pExpr->pLeft, pExpr->pRight, op,
80173                   r1, r2, dest, SQLITE_NULLEQ);
80174       testcase( regFree1==0 );
80175       testcase( regFree2==0 );
80176       break;
80177     }
80178     case TK_ISNULL:
80179     case TK_NOTNULL: {
80180       assert( TK_ISNULL==OP_IsNull );
80181       assert( TK_NOTNULL==OP_NotNull );
80182       testcase( op==TK_ISNULL );
80183       testcase( op==TK_NOTNULL );
80184       r1 = sqlite3ExprCodeTemp(pParse, pExpr->pLeft, &regFree1);
80185       sqlite3VdbeAddOp2(v, op, r1, dest);
80186       testcase( regFree1==0 );
80187       break;
80188     }
80189     case TK_BETWEEN: {
80190       testcase( jumpIfNull==0 );
80191       exprCodeBetween(pParse, pExpr, dest, 1, jumpIfNull);
80192       break;
80193     }
80194 #ifndef SQLITE_OMIT_SUBQUERY
80195     case TK_IN: {
80196       int destIfFalse = sqlite3VdbeMakeLabel(v);
80197       int destIfNull = jumpIfNull ? dest : destIfFalse;
80198       sqlite3ExprCodeIN(pParse, pExpr, destIfFalse, destIfNull);
80199       sqlite3VdbeAddOp2(v, OP_Goto, 0, dest);
80200       sqlite3VdbeResolveLabel(v, destIfFalse);
80201       break;
80202     }
80203 #endif
80204     default: {
80205       r1 = sqlite3ExprCodeTemp(pParse, pExpr, &regFree1);
80206       sqlite3VdbeAddOp3(v, OP_If, r1, dest, jumpIfNull!=0);
80207       testcase( regFree1==0 );
80208       testcase( jumpIfNull==0 );
80209       break;
80210     }
80211   }
80212   sqlite3ReleaseTempReg(pParse, regFree1);
80213   sqlite3ReleaseTempReg(pParse, regFree2);  
80214 }
80215 
80216 /*
80217 ** Generate code for a boolean expression such that a jump is made
80218 ** to the label "dest" if the expression is false but execution
80219 ** continues straight thru if the expression is true.
80220 **
80221 ** If the expression evaluates to NULL (neither true nor false) then
80222 ** jump if jumpIfNull is SQLITE_JUMPIFNULL or fall through if jumpIfNull
80223 ** is 0.
80224 */
80225 SQLITE_PRIVATE void sqlite3ExprIfFalse(Parse *pParse, Expr *pExpr, int dest, int jumpIfNull){
80226   Vdbe *v = pParse->pVdbe;
80227   int op = 0;
80228   int regFree1 = 0;
80229   int regFree2 = 0;
80230   int r1, r2;
80231 
80232   assert( jumpIfNull==SQLITE_JUMPIFNULL || jumpIfNull==0 );
80233   if( NEVER(v==0) ) return; /* Existence of VDBE checked by caller */
80234   if( pExpr==0 )    return;
80235 
80236   /* The value of pExpr->op and op are related as follows:
80237   **
80238   **       pExpr->op            op
80239   **       ---------          ----------
80240   **       TK_ISNULL          OP_NotNull
80241   **       TK_NOTNULL         OP_IsNull
80242   **       TK_NE              OP_Eq
80243   **       TK_EQ              OP_Ne
80244   **       TK_GT              OP_Le
80245   **       TK_LE              OP_Gt
80246   **       TK_GE              OP_Lt
80247   **       TK_LT              OP_Ge
80248   **
80249   ** For other values of pExpr->op, op is undefined and unused.
80250   ** The value of TK_ and OP_ constants are arranged such that we
80251   ** can compute the mapping above using the following expression.
80252   ** Assert()s verify that the computation is correct.
80253   */
80254   op = ((pExpr->op+(TK_ISNULL&1))^1)-(TK_ISNULL&1);
80255 
80256   /* Verify correct alignment of TK_ and OP_ constants
80257   */
80258   assert( pExpr->op!=TK_ISNULL || op==OP_NotNull );
80259   assert( pExpr->op!=TK_NOTNULL || op==OP_IsNull );
80260   assert( pExpr->op!=TK_NE || op==OP_Eq );
80261   assert( pExpr->op!=TK_EQ || op==OP_Ne );
80262   assert( pExpr->op!=TK_LT || op==OP_Ge );
80263   assert( pExpr->op!=TK_LE || op==OP_Gt );
80264   assert( pExpr->op!=TK_GT || op==OP_Le );
80265   assert( pExpr->op!=TK_GE || op==OP_Lt );
80266 
80267   switch( pExpr->op ){
80268     case TK_AND: {
80269       testcase( jumpIfNull==0 );
80270       sqlite3ExprIfFalse(pParse, pExpr->pLeft, dest, jumpIfNull);
80271       sqlite3ExprIfFalse(pParse, pExpr->pRight, dest, jumpIfNull);
80272       break;
80273     }
80274     case TK_OR: {
80275       int d2 = sqlite3VdbeMakeLabel(v);
80276       testcase( jumpIfNull==0 );
80277       sqlite3ExprCachePush(pParse);
80278       sqlite3ExprIfTrue(pParse, pExpr->pLeft, d2, jumpIfNull^SQLITE_JUMPIFNULL);
80279       sqlite3ExprIfFalse(pParse, pExpr->pRight, dest, jumpIfNull);
80280       sqlite3VdbeResolveLabel(v, d2);
80281       sqlite3ExprCachePop(pParse, 1);
80282       break;
80283     }
80284     case TK_NOT: {
80285       testcase( jumpIfNull==0 );
80286       sqlite3ExprIfTrue(pParse, pExpr->pLeft, dest, jumpIfNull);
80287       break;
80288     }
80289     case TK_LT:
80290     case TK_LE:
80291     case TK_GT:
80292     case TK_GE:
80293     case TK_NE:
80294     case TK_EQ: {
80295       testcase( op==TK_LT );
80296       testcase( op==TK_LE );
80297       testcase( op==TK_GT );
80298       testcase( op==TK_GE );
80299       testcase( op==TK_EQ );
80300       testcase( op==TK_NE );
80301       testcase( jumpIfNull==0 );
80302       r1 = sqlite3ExprCodeTemp(pParse, pExpr->pLeft, &regFree1);
80303       r2 = sqlite3ExprCodeTemp(pParse, pExpr->pRight, &regFree2);
80304       codeCompare(pParse, pExpr->pLeft, pExpr->pRight, op,
80305                   r1, r2, dest, jumpIfNull);
80306       testcase( regFree1==0 );
80307       testcase( regFree2==0 );
80308       break;
80309     }
80310     case TK_IS:
80311     case TK_ISNOT: {
80312       testcase( pExpr->op==TK_IS );
80313       testcase( pExpr->op==TK_ISNOT );
80314       r1 = sqlite3ExprCodeTemp(pParse, pExpr->pLeft, &regFree1);
80315       r2 = sqlite3ExprCodeTemp(pParse, pExpr->pRight, &regFree2);
80316       op = (pExpr->op==TK_IS) ? TK_NE : TK_EQ;
80317       codeCompare(pParse, pExpr->pLeft, pExpr->pRight, op,
80318                   r1, r2, dest, SQLITE_NULLEQ);
80319       testcase( regFree1==0 );
80320       testcase( regFree2==0 );
80321       break;
80322     }
80323     case TK_ISNULL:
80324     case TK_NOTNULL: {
80325       testcase( op==TK_ISNULL );
80326       testcase( op==TK_NOTNULL );
80327       r1 = sqlite3ExprCodeTemp(pParse, pExpr->pLeft, &regFree1);
80328       sqlite3VdbeAddOp2(v, op, r1, dest);
80329       testcase( regFree1==0 );
80330       break;
80331     }
80332     case TK_BETWEEN: {
80333       testcase( jumpIfNull==0 );
80334       exprCodeBetween(pParse, pExpr, dest, 0, jumpIfNull);
80335       break;
80336     }
80337 #ifndef SQLITE_OMIT_SUBQUERY
80338     case TK_IN: {
80339       if( jumpIfNull ){
80340         sqlite3ExprCodeIN(pParse, pExpr, dest, dest);
80341       }else{
80342         int destIfNull = sqlite3VdbeMakeLabel(v);
80343         sqlite3ExprCodeIN(pParse, pExpr, dest, destIfNull);
80344         sqlite3VdbeResolveLabel(v, destIfNull);
80345       }
80346       break;
80347     }
80348 #endif
80349     default: {
80350       r1 = sqlite3ExprCodeTemp(pParse, pExpr, &regFree1);
80351       sqlite3VdbeAddOp3(v, OP_IfNot, r1, dest, jumpIfNull!=0);
80352       testcase( regFree1==0 );
80353       testcase( jumpIfNull==0 );
80354       break;
80355     }
80356   }
80357   sqlite3ReleaseTempReg(pParse, regFree1);
80358   sqlite3ReleaseTempReg(pParse, regFree2);
80359 }
80360 
80361 /*
80362 ** Do a deep comparison of two expression trees.  Return 0 if the two
80363 ** expressions are completely identical.  Return 1 if they differ only
80364 ** by a COLLATE operator at the top level.  Return 2 if there are differences
80365 ** other than the top-level COLLATE operator.
80366 **
80367 ** If any subelement of pB has Expr.iTable==(-1) then it is allowed
80368 ** to compare equal to an equivalent element in pA with Expr.iTable==iTab.
80369 **
80370 ** The pA side might be using TK_REGISTER.  If that is the case and pB is
80371 ** not using TK_REGISTER but is otherwise equivalent, then still return 0.
80372 **
80373 ** Sometimes this routine will return 2 even if the two expressions
80374 ** really are equivalent.  If we cannot prove that the expressions are
80375 ** identical, we return 2 just to be safe.  So if this routine
80376 ** returns 2, then you do not really know for certain if the two
80377 ** expressions are the same.  But if you get a 0 or 1 return, then you
80378 ** can be sure the expressions are the same.  In the places where
80379 ** this routine is used, it does not hurt to get an extra 2 - that
80380 ** just might result in some slightly slower code.  But returning
80381 ** an incorrect 0 or 1 could lead to a malfunction.
80382 */
80383 SQLITE_PRIVATE int sqlite3ExprCompare(Expr *pA, Expr *pB, int iTab){
80384   u32 combinedFlags;
80385   if( pA==0 || pB==0 ){
80386     return pB==pA ? 0 : 2;
80387   }
80388   combinedFlags = pA->flags | pB->flags;
80389   if( combinedFlags & EP_IntValue ){
80390     if( (pA->flags&pB->flags&EP_IntValue)!=0 && pA->u.iValue==pB->u.iValue ){
80391       return 0;
80392     }
80393     return 2;
80394   }
80395   if( pA->op!=pB->op ){
80396     if( pA->op==TK_COLLATE && sqlite3ExprCompare(pA->pLeft, pB, iTab)<2 ){
80397       return 1;
80398     }
80399     if( pB->op==TK_COLLATE && sqlite3ExprCompare(pA, pB->pLeft, iTab)<2 ){
80400       return 1;
80401     }
80402     return 2;
80403   }
80404   if( pA->op!=TK_COLUMN && ALWAYS(pA->op!=TK_AGG_COLUMN) && pA->u.zToken ){
80405     if( strcmp(pA->u.zToken,pB->u.zToken)!=0 ){
80406       return pA->op==TK_COLLATE ? 1 : 2;
80407     }
80408   }
80409   if( (pA->flags & EP_Distinct)!=(pB->flags & EP_Distinct) ) return 2;
80410   if( ALWAYS((combinedFlags & EP_TokenOnly)==0) ){
80411     if( combinedFlags & EP_xIsSelect ) return 2;
80412     if( sqlite3ExprCompare(pA->pLeft, pB->pLeft, iTab) ) return 2;
80413     if( sqlite3ExprCompare(pA->pRight, pB->pRight, iTab) ) return 2;
80414     if( sqlite3ExprListCompare(pA->x.pList, pB->x.pList, iTab) ) return 2;
80415     if( ALWAYS((combinedFlags & EP_Reduced)==0) ){
80416       if( pA->iColumn!=pB->iColumn ) return 2;
80417       if( pA->iTable!=pB->iTable 
80418        && (pA->iTable!=iTab || NEVER(pB->iTable>=0)) ) return 2;
80419     }
80420   }
80421   return 0;
80422 }
80423 
80424 /*
80425 ** Compare two ExprList objects.  Return 0 if they are identical and 
80426 ** non-zero if they differ in any way.
80427 **
80428 ** If any subelement of pB has Expr.iTable==(-1) then it is allowed
80429 ** to compare equal to an equivalent element in pA with Expr.iTable==iTab.
80430 **
80431 ** This routine might return non-zero for equivalent ExprLists.  The
80432 ** only consequence will be disabled optimizations.  But this routine
80433 ** must never return 0 if the two ExprList objects are different, or
80434 ** a malfunction will result.
80435 **
80436 ** Two NULL pointers are considered to be the same.  But a NULL pointer
80437 ** always differs from a non-NULL pointer.
80438 */
80439 SQLITE_PRIVATE int sqlite3ExprListCompare(ExprList *pA, ExprList *pB, int iTab){
80440   int i;
80441   if( pA==0 && pB==0 ) return 0;
80442   if( pA==0 || pB==0 ) return 1;
80443   if( pA->nExpr!=pB->nExpr ) return 1;
80444   for(i=0; i<pA->nExpr; i++){
80445     Expr *pExprA = pA->a[i].pExpr;
80446     Expr *pExprB = pB->a[i].pExpr;
80447     if( pA->a[i].sortOrder!=pB->a[i].sortOrder ) return 1;
80448     if( sqlite3ExprCompare(pExprA, pExprB, iTab) ) return 1;
80449   }
80450   return 0;
80451 }
80452 
80453 /*
80454 ** Return true if we can prove the pE2 will always be true if pE1 is
80455 ** true.  Return false if we cannot complete the proof or if pE2 might
80456 ** be false.  Examples:
80457 **
80458 **     pE1: x==5       pE2: x==5             Result: true
80459 **     pE1: x>0        pE2: x==5             Result: false
80460 **     pE1: x=21       pE2: x=21 OR y=43     Result: true
80461 **     pE1: x!=123     pE2: x IS NOT NULL    Result: true
80462 **     pE1: x!=?1      pE2: x IS NOT NULL    Result: true
80463 **     pE1: x IS NULL  pE2: x IS NOT NULL    Result: false
80464 **     pE1: x IS ?2    pE2: x IS NOT NULL    Reuslt: false
80465 **
80466 ** When comparing TK_COLUMN nodes between pE1 and pE2, if pE2 has
80467 ** Expr.iTable<0 then assume a table number given by iTab.
80468 **
80469 ** When in doubt, return false.  Returning true might give a performance
80470 ** improvement.  Returning false might cause a performance reduction, but
80471 ** it will always give the correct answer and is hence always safe.
80472 */
80473 SQLITE_PRIVATE int sqlite3ExprImpliesExpr(Expr *pE1, Expr *pE2, int iTab){
80474   if( sqlite3ExprCompare(pE1, pE2, iTab)==0 ){
80475     return 1;
80476   }
80477   if( pE2->op==TK_OR
80478    && (sqlite3ExprImpliesExpr(pE1, pE2->pLeft, iTab)
80479              || sqlite3ExprImpliesExpr(pE1, pE2->pRight, iTab) )
80480   ){
80481     return 1;
80482   }
80483   if( pE2->op==TK_NOTNULL
80484    && sqlite3ExprCompare(pE1->pLeft, pE2->pLeft, iTab)==0
80485    && (pE1->op!=TK_ISNULL && pE1->op!=TK_IS)
80486   ){
80487     return 1;
80488   }
80489   return 0;
80490 }
80491 
80492 /*
80493 ** An instance of the following structure is used by the tree walker
80494 ** to count references to table columns in the arguments of an 
80495 ** aggregate function, in order to implement the
80496 ** sqlite3FunctionThisSrc() routine.
80497 */
80498 struct SrcCount {
80499   SrcList *pSrc;   /* One particular FROM clause in a nested query */
80500   int nThis;       /* Number of references to columns in pSrcList */
80501   int nOther;      /* Number of references to columns in other FROM clauses */
80502 };
80503 
80504 /*
80505 ** Count the number of references to columns.
80506 */
80507 static int exprSrcCount(Walker *pWalker, Expr *pExpr){
80508   /* The NEVER() on the second term is because sqlite3FunctionUsesThisSrc()
80509   ** is always called before sqlite3ExprAnalyzeAggregates() and so the
80510   ** TK_COLUMNs have not yet been converted into TK_AGG_COLUMN.  If
80511   ** sqlite3FunctionUsesThisSrc() is used differently in the future, the
80512   ** NEVER() will need to be removed. */
80513   if( pExpr->op==TK_COLUMN || NEVER(pExpr->op==TK_AGG_COLUMN) ){
80514     int i;
80515     struct SrcCount *p = pWalker->u.pSrcCount;
80516     SrcList *pSrc = p->pSrc;
80517     for(i=0; i<pSrc->nSrc; i++){
80518       if( pExpr->iTable==pSrc->a[i].iCursor ) break;
80519     }
80520     if( i<pSrc->nSrc ){
80521       p->nThis++;
80522     }else{
80523       p->nOther++;
80524     }
80525   }
80526   return WRC_Continue;
80527 }
80528 
80529 /*
80530 ** Determine if any of the arguments to the pExpr Function reference
80531 ** pSrcList.  Return true if they do.  Also return true if the function
80532 ** has no arguments or has only constant arguments.  Return false if pExpr
80533 ** references columns but not columns of tables found in pSrcList.
80534 */
80535 SQLITE_PRIVATE int sqlite3FunctionUsesThisSrc(Expr *pExpr, SrcList *pSrcList){
80536   Walker w;
80537   struct SrcCount cnt;
80538   assert( pExpr->op==TK_AGG_FUNCTION );
80539   memset(&w, 0, sizeof(w));
80540   w.xExprCallback = exprSrcCount;
80541   w.u.pSrcCount = &cnt;
80542   cnt.pSrc = pSrcList;
80543   cnt.nThis = 0;
80544   cnt.nOther = 0;
80545   sqlite3WalkExprList(&w, pExpr->x.pList);
80546   return cnt.nThis>0 || cnt.nOther==0;
80547 }
80548 
80549 /*
80550 ** Add a new element to the pAggInfo->aCol[] array.  Return the index of
80551 ** the new element.  Return a negative number if malloc fails.
80552 */
80553 static int addAggInfoColumn(sqlite3 *db, AggInfo *pInfo){
80554   int i;
80555   pInfo->aCol = sqlite3ArrayAllocate(
80556        db,
80557        pInfo->aCol,
80558        sizeof(pInfo->aCol[0]),
80559        &pInfo->nColumn,
80560        &i
80561   );
80562   return i;
80563 }    
80564 
80565 /*
80566 ** Add a new element to the pAggInfo->aFunc[] array.  Return the index of
80567 ** the new element.  Return a negative number if malloc fails.
80568 */
80569 static int addAggInfoFunc(sqlite3 *db, AggInfo *pInfo){
80570   int i;
80571   pInfo->aFunc = sqlite3ArrayAllocate(
80572        db, 
80573        pInfo->aFunc,
80574        sizeof(pInfo->aFunc[0]),
80575        &pInfo->nFunc,
80576        &i
80577   );
80578   return i;
80579 }    
80580 
80581 /*
80582 ** This is the xExprCallback for a tree walker.  It is used to
80583 ** implement sqlite3ExprAnalyzeAggregates().  See sqlite3ExprAnalyzeAggregates
80584 ** for additional information.
80585 */
80586 static int analyzeAggregate(Walker *pWalker, Expr *pExpr){
80587   int i;
80588   NameContext *pNC = pWalker->u.pNC;
80589   Parse *pParse = pNC->pParse;
80590   SrcList *pSrcList = pNC->pSrcList;
80591   AggInfo *pAggInfo = pNC->pAggInfo;
80592 
80593   switch( pExpr->op ){
80594     case TK_AGG_COLUMN:
80595     case TK_COLUMN: {
80596       testcase( pExpr->op==TK_AGG_COLUMN );
80597       testcase( pExpr->op==TK_COLUMN );
80598       /* Check to see if the column is in one of the tables in the FROM
80599       ** clause of the aggregate query */
80600       if( ALWAYS(pSrcList!=0) ){
80601         struct SrcList_item *pItem = pSrcList->a;
80602         for(i=0; i<pSrcList->nSrc; i++, pItem++){
80603           struct AggInfo_col *pCol;
80604           assert( !ExprHasProperty(pExpr, EP_TokenOnly|EP_Reduced) );
80605           if( pExpr->iTable==pItem->iCursor ){
80606             /* If we reach this point, it means that pExpr refers to a table
80607             ** that is in the FROM clause of the aggregate query.  
80608             **
80609             ** Make an entry for the column in pAggInfo->aCol[] if there
80610             ** is not an entry there already.
80611             */
80612             int k;
80613             pCol = pAggInfo->aCol;
80614             for(k=0; k<pAggInfo->nColumn; k++, pCol++){
80615               if( pCol->iTable==pExpr->iTable &&
80616                   pCol->iColumn==pExpr->iColumn ){
80617                 break;
80618               }
80619             }
80620             if( (k>=pAggInfo->nColumn)
80621              && (k = addAggInfoColumn(pParse->db, pAggInfo))>=0 
80622             ){
80623               pCol = &pAggInfo->aCol[k];
80624               pCol->pTab = pExpr->pTab;
80625               pCol->iTable = pExpr->iTable;
80626               pCol->iColumn = pExpr->iColumn;
80627               pCol->iMem = ++pParse->nMem;
80628               pCol->iSorterColumn = -1;
80629               pCol->pExpr = pExpr;
80630               if( pAggInfo->pGroupBy ){
80631                 int j, n;
80632                 ExprList *pGB = pAggInfo->pGroupBy;
80633                 struct ExprList_item *pTerm = pGB->a;
80634                 n = pGB->nExpr;
80635                 for(j=0; j<n; j++, pTerm++){
80636                   Expr *pE = pTerm->pExpr;
80637                   if( pE->op==TK_COLUMN && pE->iTable==pExpr->iTable &&
80638                       pE->iColumn==pExpr->iColumn ){
80639                     pCol->iSorterColumn = j;
80640                     break;
80641                   }
80642                 }
80643               }
80644               if( pCol->iSorterColumn<0 ){
80645                 pCol->iSorterColumn = pAggInfo->nSortingColumn++;
80646               }
80647             }
80648             /* There is now an entry for pExpr in pAggInfo->aCol[] (either
80649             ** because it was there before or because we just created it).
80650             ** Convert the pExpr to be a TK_AGG_COLUMN referring to that
80651             ** pAggInfo->aCol[] entry.
80652             */
80653             ExprSetVVAProperty(pExpr, EP_NoReduce);
80654             pExpr->pAggInfo = pAggInfo;
80655             pExpr->op = TK_AGG_COLUMN;
80656             pExpr->iAgg = (i16)k;
80657             break;
80658           } /* endif pExpr->iTable==pItem->iCursor */
80659         } /* end loop over pSrcList */
80660       }
80661       return WRC_Prune;
80662     }
80663     case TK_AGG_FUNCTION: {
80664       if( (pNC->ncFlags & NC_InAggFunc)==0
80665        && pWalker->walkerDepth==pExpr->op2
80666       ){
80667         /* Check to see if pExpr is a duplicate of another aggregate 
80668         ** function that is already in the pAggInfo structure
80669         */
80670         struct AggInfo_func *pItem = pAggInfo->aFunc;
80671         for(i=0; i<pAggInfo->nFunc; i++, pItem++){
80672           if( sqlite3ExprCompare(pItem->pExpr, pExpr, -1)==0 ){
80673             break;
80674           }
80675         }
80676         if( i>=pAggInfo->nFunc ){
80677           /* pExpr is original.  Make a new entry in pAggInfo->aFunc[]
80678           */
80679           u8 enc = ENC(pParse->db);
80680           i = addAggInfoFunc(pParse->db, pAggInfo);
80681           if( i>=0 ){
80682             assert( !ExprHasProperty(pExpr, EP_xIsSelect) );
80683             pItem = &pAggInfo->aFunc[i];
80684             pItem->pExpr = pExpr;
80685             pItem->iMem = ++pParse->nMem;
80686             assert( !ExprHasProperty(pExpr, EP_IntValue) );
80687             pItem->pFunc = sqlite3FindFunction(pParse->db,
80688                    pExpr->u.zToken, sqlite3Strlen30(pExpr->u.zToken),
80689                    pExpr->x.pList ? pExpr->x.pList->nExpr : 0, enc, 0);
80690             if( pExpr->flags & EP_Distinct ){
80691               pItem->iDistinct = pParse->nTab++;
80692             }else{
80693               pItem->iDistinct = -1;
80694             }
80695           }
80696         }
80697         /* Make pExpr point to the appropriate pAggInfo->aFunc[] entry
80698         */
80699         assert( !ExprHasProperty(pExpr, EP_TokenOnly|EP_Reduced) );
80700         ExprSetVVAProperty(pExpr, EP_NoReduce);
80701         pExpr->iAgg = (i16)i;
80702         pExpr->pAggInfo = pAggInfo;
80703         return WRC_Prune;
80704       }else{
80705         return WRC_Continue;
80706       }
80707     }
80708   }
80709   return WRC_Continue;
80710 }
80711 static int analyzeAggregatesInSelect(Walker *pWalker, Select *pSelect){
80712   UNUSED_PARAMETER(pWalker);
80713   UNUSED_PARAMETER(pSelect);
80714   return WRC_Continue;
80715 }
80716 
80717 /*
80718 ** Analyze the pExpr expression looking for aggregate functions and
80719 ** for variables that need to be added to AggInfo object that pNC->pAggInfo
80720 ** points to.  Additional entries are made on the AggInfo object as
80721 ** necessary.
80722 **
80723 ** This routine should only be called after the expression has been
80724 ** analyzed by sqlite3ResolveExprNames().
80725 */
80726 SQLITE_PRIVATE void sqlite3ExprAnalyzeAggregates(NameContext *pNC, Expr *pExpr){
80727   Walker w;
80728   memset(&w, 0, sizeof(w));
80729   w.xExprCallback = analyzeAggregate;
80730   w.xSelectCallback = analyzeAggregatesInSelect;
80731   w.u.pNC = pNC;
80732   assert( pNC->pSrcList!=0 );
80733   sqlite3WalkExpr(&w, pExpr);
80734 }
80735 
80736 /*
80737 ** Call sqlite3ExprAnalyzeAggregates() for every expression in an
80738 ** expression list.  Return the number of errors.
80739 **
80740 ** If an error is found, the analysis is cut short.
80741 */
80742 SQLITE_PRIVATE void sqlite3ExprAnalyzeAggList(NameContext *pNC, ExprList *pList){
80743   struct ExprList_item *pItem;
80744   int i;
80745   if( pList ){
80746     for(pItem=pList->a, i=0; i<pList->nExpr; i++, pItem++){
80747       sqlite3ExprAnalyzeAggregates(pNC, pItem->pExpr);
80748     }
80749   }
80750 }
80751 
80752 /*
80753 ** Allocate a single new register for use to hold some intermediate result.
80754 */
80755 SQLITE_PRIVATE int sqlite3GetTempReg(Parse *pParse){
80756   if( pParse->nTempReg==0 ){
80757     return ++pParse->nMem;
80758   }
80759   return pParse->aTempReg[--pParse->nTempReg];
80760 }
80761 
80762 /*
80763 ** Deallocate a register, making available for reuse for some other
80764 ** purpose.
80765 **
80766 ** If a register is currently being used by the column cache, then
80767 ** the dallocation is deferred until the column cache line that uses
80768 ** the register becomes stale.
80769 */
80770 SQLITE_PRIVATE void sqlite3ReleaseTempReg(Parse *pParse, int iReg){
80771   if( iReg && pParse->nTempReg<ArraySize(pParse->aTempReg) ){
80772     int i;
80773     struct yColCache *p;
80774     for(i=0, p=pParse->aColCache; i<SQLITE_N_COLCACHE; i++, p++){
80775       if( p->iReg==iReg ){
80776         p->tempReg = 1;
80777         return;
80778       }
80779     }
80780     pParse->aTempReg[pParse->nTempReg++] = iReg;
80781   }
80782 }
80783 
80784 /*
80785 ** Allocate or deallocate a block of nReg consecutive registers
80786 */
80787 SQLITE_PRIVATE int sqlite3GetTempRange(Parse *pParse, int nReg){
80788   int i, n;
80789   i = pParse->iRangeReg;
80790   n = pParse->nRangeReg;
80791   if( nReg<=n ){
80792     assert( !usedAsColumnCache(pParse, i, i+n-1) );
80793     pParse->iRangeReg += nReg;
80794     pParse->nRangeReg -= nReg;
80795   }else{
80796     i = pParse->nMem+1;
80797     pParse->nMem += nReg;
80798   }
80799   return i;
80800 }
80801 SQLITE_PRIVATE void sqlite3ReleaseTempRange(Parse *pParse, int iReg, int nReg){
80802   sqlite3ExprCacheRemove(pParse, iReg, nReg);
80803   if( nReg>pParse->nRangeReg ){
80804     pParse->nRangeReg = nReg;
80805     pParse->iRangeReg = iReg;
80806   }
80807 }
80808 
80809 /*
80810 ** Mark all temporary registers as being unavailable for reuse.
80811 */
80812 SQLITE_PRIVATE void sqlite3ClearTempRegCache(Parse *pParse){
80813   pParse->nTempReg = 0;
80814   pParse->nRangeReg = 0;
80815 }
80816 
80817 /************** End of expr.c ************************************************/
80818 /************** Begin file alter.c *******************************************/
80819 /*
80820 ** 2005 February 15
80821 **
80822 ** The author disclaims copyright to this source code.  In place of
80823 ** a legal notice, here is a blessing:
80824 **
80825 **    May you do good and not evil.
80826 **    May you find forgiveness for yourself and forgive others.
80827 **    May you share freely, never taking more than you give.
80828 **
80829 *************************************************************************
80830 ** This file contains C code routines that used to generate VDBE code
80831 ** that implements the ALTER TABLE command.
80832 */
80833 
80834 /*
80835 ** The code in this file only exists if we are not omitting the
80836 ** ALTER TABLE logic from the build.
80837 */
80838 #ifndef SQLITE_OMIT_ALTERTABLE
80839 
80840 
80841 /*
80842 ** This function is used by SQL generated to implement the 
80843 ** ALTER TABLE command. The first argument is the text of a CREATE TABLE or
80844 ** CREATE INDEX command. The second is a table name. The table name in 
80845 ** the CREATE TABLE or CREATE INDEX statement is replaced with the third
80846 ** argument and the result returned. Examples:
80847 **
80848 ** sqlite_rename_table('CREATE TABLE abc(a, b, c)', 'def')
80849 **     -> 'CREATE TABLE def(a, b, c)'
80850 **
80851 ** sqlite_rename_table('CREATE INDEX i ON abc(a)', 'def')
80852 **     -> 'CREATE INDEX i ON def(a, b, c)'
80853 */
80854 static void renameTableFunc(
80855   sqlite3_context *context,
80856   int NotUsed,
80857   sqlite3_value **argv
80858 ){
80859   unsigned char const *zSql = sqlite3_value_text(argv[0]);
80860   unsigned char const *zTableName = sqlite3_value_text(argv[1]);
80861 
80862   int token;
80863   Token tname;
80864   unsigned char const *zCsr = zSql;
80865   int len = 0;
80866   char *zRet;
80867 
80868   sqlite3 *db = sqlite3_context_db_handle(context);
80869 
80870   UNUSED_PARAMETER(NotUsed);
80871 
80872   /* The principle used to locate the table name in the CREATE TABLE 
80873   ** statement is that the table name is the first non-space token that
80874   ** is immediately followed by a TK_LP or TK_USING token.
80875   */
80876   if( zSql ){
80877     do {
80878       if( !*zCsr ){
80879         /* Ran out of input before finding an opening bracket. Return NULL. */
80880         return;
80881       }
80882 
80883       /* Store the token that zCsr points to in tname. */
80884       tname.z = (char*)zCsr;
80885       tname.n = len;
80886 
80887       /* Advance zCsr to the next token. Store that token type in 'token',
80888       ** and its length in 'len' (to be used next iteration of this loop).
80889       */
80890       do {
80891         zCsr += len;
80892         len = sqlite3GetToken(zCsr, &token);
80893       } while( token==TK_SPACE );
80894       assert( len>0 );
80895     } while( token!=TK_LP && token!=TK_USING );
80896 
80897     zRet = sqlite3MPrintf(db, "%.*s\"%w\"%s", ((u8*)tname.z) - zSql, zSql, 
80898        zTableName, tname.z+tname.n);
80899     sqlite3_result_text(context, zRet, -1, SQLITE_DYNAMIC);
80900   }
80901 }
80902 
80903 /*
80904 ** This C function implements an SQL user function that is used by SQL code
80905 ** generated by the ALTER TABLE ... RENAME command to modify the definition
80906 ** of any foreign key constraints that use the table being renamed as the 
80907 ** parent table. It is passed three arguments:
80908 **
80909 **   1) The complete text of the CREATE TABLE statement being modified,
80910 **   2) The old name of the table being renamed, and
80911 **   3) The new name of the table being renamed.
80912 **
80913 ** It returns the new CREATE TABLE statement. For example:
80914 **
80915 **   sqlite_rename_parent('CREATE TABLE t1(a REFERENCES t2)', 't2', 't3')
80916 **       -> 'CREATE TABLE t1(a REFERENCES t3)'
80917 */
80918 #ifndef SQLITE_OMIT_FOREIGN_KEY
80919 static void renameParentFunc(
80920   sqlite3_context *context,
80921   int NotUsed,
80922   sqlite3_value **argv
80923 ){
80924   sqlite3 *db = sqlite3_context_db_handle(context);
80925   char *zOutput = 0;
80926   char *zResult;
80927   unsigned char const *zInput = sqlite3_value_text(argv[0]);
80928   unsigned char const *zOld = sqlite3_value_text(argv[1]);
80929   unsigned char const *zNew = sqlite3_value_text(argv[2]);
80930 
80931   unsigned const char *z;         /* Pointer to token */
80932   int n;                          /* Length of token z */
80933   int token;                      /* Type of token */
80934 
80935   UNUSED_PARAMETER(NotUsed);
80936   for(z=zInput; *z; z=z+n){
80937     n = sqlite3GetToken(z, &token);
80938     if( token==TK_REFERENCES ){
80939       char *zParent;
80940       do {
80941         z += n;
80942         n = sqlite3GetToken(z, &token);
80943       }while( token==TK_SPACE );
80944 
80945       zParent = sqlite3DbStrNDup(db, (const char *)z, n);
80946       if( zParent==0 ) break;
80947       sqlite3Dequote(zParent);
80948       if( 0==sqlite3StrICmp((const char *)zOld, zParent) ){
80949         char *zOut = sqlite3MPrintf(db, "%s%.*s\"%w\"", 
80950             (zOutput?zOutput:""), z-zInput, zInput, (const char *)zNew
80951         );
80952         sqlite3DbFree(db, zOutput);
80953         zOutput = zOut;
80954         zInput = &z[n];
80955       }
80956       sqlite3DbFree(db, zParent);
80957     }
80958   }
80959 
80960   zResult = sqlite3MPrintf(db, "%s%s", (zOutput?zOutput:""), zInput), 
80961   sqlite3_result_text(context, zResult, -1, SQLITE_DYNAMIC);
80962   sqlite3DbFree(db, zOutput);
80963 }
80964 #endif
80965 
80966 #ifndef SQLITE_OMIT_TRIGGER
80967 /* This function is used by SQL generated to implement the
80968 ** ALTER TABLE command. The first argument is the text of a CREATE TRIGGER 
80969 ** statement. The second is a table name. The table name in the CREATE 
80970 ** TRIGGER statement is replaced with the third argument and the result 
80971 ** returned. This is analagous to renameTableFunc() above, except for CREATE
80972 ** TRIGGER, not CREATE INDEX and CREATE TABLE.
80973 */
80974 static void renameTriggerFunc(
80975   sqlite3_context *context,
80976   int NotUsed,
80977   sqlite3_value **argv
80978 ){
80979   unsigned char const *zSql = sqlite3_value_text(argv[0]);
80980   unsigned char const *zTableName = sqlite3_value_text(argv[1]);
80981 
80982   int token;
80983   Token tname;
80984   int dist = 3;
80985   unsigned char const *zCsr = zSql;
80986   int len = 0;
80987   char *zRet;
80988   sqlite3 *db = sqlite3_context_db_handle(context);
80989 
80990   UNUSED_PARAMETER(NotUsed);
80991 
80992   /* The principle used to locate the table name in the CREATE TRIGGER 
80993   ** statement is that the table name is the first token that is immediatedly
80994   ** preceded by either TK_ON or TK_DOT and immediatedly followed by one
80995   ** of TK_WHEN, TK_BEGIN or TK_FOR.
80996   */
80997   if( zSql ){
80998     do {
80999 
81000       if( !*zCsr ){
81001         /* Ran out of input before finding the table name. Return NULL. */
81002         return;
81003       }
81004 
81005       /* Store the token that zCsr points to in tname. */
81006       tname.z = (char*)zCsr;
81007       tname.n = len;
81008 
81009       /* Advance zCsr to the next token. Store that token type in 'token',
81010       ** and its length in 'len' (to be used next iteration of this loop).
81011       */
81012       do {
81013         zCsr += len;
81014         len = sqlite3GetToken(zCsr, &token);
81015       }while( token==TK_SPACE );
81016       assert( len>0 );
81017 
81018       /* Variable 'dist' stores the number of tokens read since the most
81019       ** recent TK_DOT or TK_ON. This means that when a WHEN, FOR or BEGIN 
81020       ** token is read and 'dist' equals 2, the condition stated above
81021       ** to be met.
81022       **
81023       ** Note that ON cannot be a database, table or column name, so
81024       ** there is no need to worry about syntax like 
81025       ** "CREATE TRIGGER ... ON ON.ON BEGIN ..." etc.
81026       */
81027       dist++;
81028       if( token==TK_DOT || token==TK_ON ){
81029         dist = 0;
81030       }
81031     } while( dist!=2 || (token!=TK_WHEN && token!=TK_FOR && token!=TK_BEGIN) );
81032 
81033     /* Variable tname now contains the token that is the old table-name
81034     ** in the CREATE TRIGGER statement.
81035     */
81036     zRet = sqlite3MPrintf(db, "%.*s\"%w\"%s", ((u8*)tname.z) - zSql, zSql, 
81037        zTableName, tname.z+tname.n);
81038     sqlite3_result_text(context, zRet, -1, SQLITE_DYNAMIC);
81039   }
81040 }
81041 #endif   /* !SQLITE_OMIT_TRIGGER */
81042 
81043 /*
81044 ** Register built-in functions used to help implement ALTER TABLE
81045 */
81046 SQLITE_PRIVATE void sqlite3AlterFunctions(void){
81047   static SQLITE_WSD FuncDef aAlterTableFuncs[] = {
81048     FUNCTION(sqlite_rename_table,   2, 0, 0, renameTableFunc),
81049 #ifndef SQLITE_OMIT_TRIGGER
81050     FUNCTION(sqlite_rename_trigger, 2, 0, 0, renameTriggerFunc),
81051 #endif
81052 #ifndef SQLITE_OMIT_FOREIGN_KEY
81053     FUNCTION(sqlite_rename_parent,  3, 0, 0, renameParentFunc),
81054 #endif
81055   };
81056   int i;
81057   FuncDefHash *pHash = &GLOBAL(FuncDefHash, sqlite3GlobalFunctions);
81058   FuncDef *aFunc = (FuncDef*)&GLOBAL(FuncDef, aAlterTableFuncs);
81059 
81060   for(i=0; i<ArraySize(aAlterTableFuncs); i++){
81061     sqlite3FuncDefInsert(pHash, &aFunc[i]);
81062   }
81063 }
81064 
81065 /*
81066 ** This function is used to create the text of expressions of the form:
81067 **
81068 **   name=<constant1> OR name=<constant2> OR ...
81069 **
81070 ** If argument zWhere is NULL, then a pointer string containing the text 
81071 ** "name=<constant>" is returned, where <constant> is the quoted version
81072 ** of the string passed as argument zConstant. The returned buffer is
81073 ** allocated using sqlite3DbMalloc(). It is the responsibility of the
81074 ** caller to ensure that it is eventually freed.
81075 **
81076 ** If argument zWhere is not NULL, then the string returned is 
81077 ** "<where> OR name=<constant>", where <where> is the contents of zWhere.
81078 ** In this case zWhere is passed to sqlite3DbFree() before returning.
81079 ** 
81080 */
81081 static char *whereOrName(sqlite3 *db, char *zWhere, char *zConstant){
81082   char *zNew;
81083   if( !zWhere ){
81084     zNew = sqlite3MPrintf(db, "name=%Q", zConstant);
81085   }else{
81086     zNew = sqlite3MPrintf(db, "%s OR name=%Q", zWhere, zConstant);
81087     sqlite3DbFree(db, zWhere);
81088   }
81089   return zNew;
81090 }
81091 
81092 #if !defined(SQLITE_OMIT_FOREIGN_KEY) && !defined(SQLITE_OMIT_TRIGGER)
81093 /*
81094 ** Generate the text of a WHERE expression which can be used to select all
81095 ** tables that have foreign key constraints that refer to table pTab (i.e.
81096 ** constraints for which pTab is the parent table) from the sqlite_master
81097 ** table.
81098 */
81099 static char *whereForeignKeys(Parse *pParse, Table *pTab){
81100   FKey *p;
81101   char *zWhere = 0;
81102   for(p=sqlite3FkReferences(pTab); p; p=p->pNextTo){
81103     zWhere = whereOrName(pParse->db, zWhere, p->pFrom->zName);
81104   }
81105   return zWhere;
81106 }
81107 #endif
81108 
81109 /*
81110 ** Generate the text of a WHERE expression which can be used to select all
81111 ** temporary triggers on table pTab from the sqlite_temp_master table. If
81112 ** table pTab has no temporary triggers, or is itself stored in the 
81113 ** temporary database, NULL is returned.
81114 */
81115 static char *whereTempTriggers(Parse *pParse, Table *pTab){
81116   Trigger *pTrig;
81117   char *zWhere = 0;
81118   const Schema *pTempSchema = pParse->db->aDb[1].pSchema; /* Temp db schema */
81119 
81120   /* If the table is not located in the temp-db (in which case NULL is 
81121   ** returned, loop through the tables list of triggers. For each trigger
81122   ** that is not part of the temp-db schema, add a clause to the WHERE 
81123   ** expression being built up in zWhere.
81124   */
81125   if( pTab->pSchema!=pTempSchema ){
81126     sqlite3 *db = pParse->db;
81127     for(pTrig=sqlite3TriggerList(pParse, pTab); pTrig; pTrig=pTrig->pNext){
81128       if( pTrig->pSchema==pTempSchema ){
81129         zWhere = whereOrName(db, zWhere, pTrig->zName);
81130       }
81131     }
81132   }
81133   if( zWhere ){
81134     char *zNew = sqlite3MPrintf(pParse->db, "type='trigger' AND (%s)", zWhere);
81135     sqlite3DbFree(pParse->db, zWhere);
81136     zWhere = zNew;
81137   }
81138   return zWhere;
81139 }
81140 
81141 /*
81142 ** Generate code to drop and reload the internal representation of table
81143 ** pTab from the database, including triggers and temporary triggers.
81144 ** Argument zName is the name of the table in the database schema at
81145 ** the time the generated code is executed. This can be different from
81146 ** pTab->zName if this function is being called to code part of an 
81147 ** "ALTER TABLE RENAME TO" statement.
81148 */
81149 static void reloadTableSchema(Parse *pParse, Table *pTab, const char *zName){
81150   Vdbe *v;
81151   char *zWhere;
81152   int iDb;                   /* Index of database containing pTab */
81153 #ifndef SQLITE_OMIT_TRIGGER
81154   Trigger *pTrig;
81155 #endif
81156 
81157   v = sqlite3GetVdbe(pParse);
81158   if( NEVER(v==0) ) return;
81159   assert( sqlite3BtreeHoldsAllMutexes(pParse->db) );
81160   iDb = sqlite3SchemaToIndex(pParse->db, pTab->pSchema);
81161   assert( iDb>=0 );
81162 
81163 #ifndef SQLITE_OMIT_TRIGGER
81164   /* Drop any table triggers from the internal schema. */
81165   for(pTrig=sqlite3TriggerList(pParse, pTab); pTrig; pTrig=pTrig->pNext){
81166     int iTrigDb = sqlite3SchemaToIndex(pParse->db, pTrig->pSchema);
81167     assert( iTrigDb==iDb || iTrigDb==1 );
81168     sqlite3VdbeAddOp4(v, OP_DropTrigger, iTrigDb, 0, 0, pTrig->zName, 0);
81169   }
81170 #endif
81171 
81172   /* Drop the table and index from the internal schema.  */
81173   sqlite3VdbeAddOp4(v, OP_DropTable, iDb, 0, 0, pTab->zName, 0);
81174 
81175   /* Reload the table, index and permanent trigger schemas. */
81176   zWhere = sqlite3MPrintf(pParse->db, "tbl_name=%Q", zName);
81177   if( !zWhere ) return;
81178   sqlite3VdbeAddParseSchemaOp(v, iDb, zWhere);
81179 
81180 #ifndef SQLITE_OMIT_TRIGGER
81181   /* Now, if the table is not stored in the temp database, reload any temp 
81182   ** triggers. Don't use IN(...) in case SQLITE_OMIT_SUBQUERY is defined. 
81183   */
81184   if( (zWhere=whereTempTriggers(pParse, pTab))!=0 ){
81185     sqlite3VdbeAddParseSchemaOp(v, 1, zWhere);
81186   }
81187 #endif
81188 }
81189 
81190 /*
81191 ** Parameter zName is the name of a table that is about to be altered
81192 ** (either with ALTER TABLE ... RENAME TO or ALTER TABLE ... ADD COLUMN).
81193 ** If the table is a system table, this function leaves an error message
81194 ** in pParse->zErr (system tables may not be altered) and returns non-zero.
81195 **
81196 ** Or, if zName is not a system table, zero is returned.
81197 */
81198 static int isSystemTable(Parse *pParse, const char *zName){
81199   if( sqlite3Strlen30(zName)>6 && 0==sqlite3StrNICmp(zName, "sqlite_", 7) ){
81200     sqlite3ErrorMsg(pParse, "table %s may not be altered", zName);
81201     return 1;
81202   }
81203   return 0;
81204 }
81205 
81206 /*
81207 ** Generate code to implement the "ALTER TABLE xxx RENAME TO yyy" 
81208 ** command. 
81209 */
81210 SQLITE_PRIVATE void sqlite3AlterRenameTable(
81211   Parse *pParse,            /* Parser context. */
81212   SrcList *pSrc,            /* The table to rename. */
81213   Token *pName              /* The new table name. */
81214 ){
81215   int iDb;                  /* Database that contains the table */
81216   char *zDb;                /* Name of database iDb */
81217   Table *pTab;              /* Table being renamed */
81218   char *zName = 0;          /* NULL-terminated version of pName */ 
81219   sqlite3 *db = pParse->db; /* Database connection */
81220   int nTabName;             /* Number of UTF-8 characters in zTabName */
81221   const char *zTabName;     /* Original name of the table */
81222   Vdbe *v;
81223 #ifndef SQLITE_OMIT_TRIGGER
81224   char *zWhere = 0;         /* Where clause to locate temp triggers */
81225 #endif
81226   VTable *pVTab = 0;        /* Non-zero if this is a v-tab with an xRename() */
81227   int savedDbFlags;         /* Saved value of db->flags */
81228 
81229   savedDbFlags = db->flags;  
81230   if( NEVER(db->mallocFailed) ) goto exit_rename_table;
81231   assert( pSrc->nSrc==1 );
81232   assert( sqlite3BtreeHoldsAllMutexes(pParse->db) );
81233 
81234   pTab = sqlite3LocateTableItem(pParse, 0, &pSrc->a[0]);
81235   if( !pTab ) goto exit_rename_table;
81236   iDb = sqlite3SchemaToIndex(pParse->db, pTab->pSchema);
81237   zDb = db->aDb[iDb].zName;
81238   db->flags |= SQLITE_PreferBuiltin;
81239 
81240   /* Get a NULL terminated version of the new table name. */
81241   zName = sqlite3NameFromToken(db, pName);
81242   if( !zName ) goto exit_rename_table;
81243 
81244   /* Check that a table or index named 'zName' does not already exist
81245   ** in database iDb. If so, this is an error.
81246   */
81247   if( sqlite3FindTable(db, zName, zDb) || sqlite3FindIndex(db, zName, zDb) ){
81248     sqlite3ErrorMsg(pParse, 
81249         "there is already another table or index with this name: %s", zName);
81250     goto exit_rename_table;
81251   }
81252 
81253   /* Make sure it is not a system table being altered, or a reserved name
81254   ** that the table is being renamed to.
81255   */
81256   if( SQLITE_OK!=isSystemTable(pParse, pTab->zName) ){
81257     goto exit_rename_table;
81258   }
81259   if( SQLITE_OK!=sqlite3CheckObjectName(pParse, zName) ){ goto
81260     exit_rename_table;
81261   }
81262 
81263 #ifndef SQLITE_OMIT_VIEW
81264   if( pTab->pSelect ){
81265     sqlite3ErrorMsg(pParse, "view %s may not be altered", pTab->zName);
81266     goto exit_rename_table;
81267   }
81268 #endif
81269 
81270 #ifndef SQLITE_OMIT_AUTHORIZATION
81271   /* Invoke the authorization callback. */
81272   if( sqlite3AuthCheck(pParse, SQLITE_ALTER_TABLE, zDb, pTab->zName, 0) ){
81273     goto exit_rename_table;
81274   }
81275 #endif
81276 
81277 #ifndef SQLITE_OMIT_VIRTUALTABLE
81278   if( sqlite3ViewGetColumnNames(pParse, pTab) ){
81279     goto exit_rename_table;
81280   }
81281   if( IsVirtual(pTab) ){
81282     pVTab = sqlite3GetVTable(db, pTab);
81283     if( pVTab->pVtab->pModule->xRename==0 ){
81284       pVTab = 0;
81285     }
81286   }
81287 #endif
81288 
81289   /* Begin a transaction and code the VerifyCookie for database iDb. 
81290   ** Then modify the schema cookie (since the ALTER TABLE modifies the
81291   ** schema). Open a statement transaction if the table is a virtual
81292   ** table.
81293   */
81294   v = sqlite3GetVdbe(pParse);
81295   if( v==0 ){
81296     goto exit_rename_table;
81297   }
81298   sqlite3BeginWriteOperation(pParse, pVTab!=0, iDb);
81299   sqlite3ChangeCookie(pParse, iDb);
81300 
81301   /* If this is a virtual table, invoke the xRename() function if
81302   ** one is defined. The xRename() callback will modify the names
81303   ** of any resources used by the v-table implementation (including other
81304   ** SQLite tables) that are identified by the name of the virtual table.
81305   */
81306 #ifndef SQLITE_OMIT_VIRTUALTABLE
81307   if( pVTab ){
81308     int i = ++pParse->nMem;
81309     sqlite3VdbeAddOp4(v, OP_String8, 0, i, 0, zName, 0);
81310     sqlite3VdbeAddOp4(v, OP_VRename, i, 0, 0,(const char*)pVTab, P4_VTAB);
81311     sqlite3MayAbort(pParse);
81312   }
81313 #endif
81314 
81315   /* figure out how many UTF-8 characters are in zName */
81316   zTabName = pTab->zName;
81317   nTabName = sqlite3Utf8CharLen(zTabName, -1);
81318 
81319 #if !defined(SQLITE_OMIT_FOREIGN_KEY) && !defined(SQLITE_OMIT_TRIGGER)
81320   if( db->flags&SQLITE_ForeignKeys ){
81321     /* If foreign-key support is enabled, rewrite the CREATE TABLE 
81322     ** statements corresponding to all child tables of foreign key constraints
81323     ** for which the renamed table is the parent table.  */
81324     if( (zWhere=whereForeignKeys(pParse, pTab))!=0 ){
81325       sqlite3NestedParse(pParse, 
81326           "UPDATE \"%w\".%s SET "
81327               "sql = sqlite_rename_parent(sql, %Q, %Q) "
81328               "WHERE %s;", zDb, SCHEMA_TABLE(iDb), zTabName, zName, zWhere);
81329       sqlite3DbFree(db, zWhere);
81330     }
81331   }
81332 #endif
81333 
81334   /* Modify the sqlite_master table to use the new table name. */
81335   sqlite3NestedParse(pParse,
81336       "UPDATE %Q.%s SET "
81337 #ifdef SQLITE_OMIT_TRIGGER
81338           "sql = sqlite_rename_table(sql, %Q), "
81339 #else
81340           "sql = CASE "
81341             "WHEN type = 'trigger' THEN sqlite_rename_trigger(sql, %Q)"
81342             "ELSE sqlite_rename_table(sql, %Q) END, "
81343 #endif
81344           "tbl_name = %Q, "
81345           "name = CASE "
81346             "WHEN type='table' THEN %Q "
81347             "WHEN name LIKE 'sqlite_autoindex%%' AND type='index' THEN "
81348              "'sqlite_autoindex_' || %Q || substr(name,%d+18) "
81349             "ELSE name END "
81350       "WHERE tbl_name=%Q COLLATE nocase AND "
81351           "(type='table' OR type='index' OR type='trigger');", 
81352       zDb, SCHEMA_TABLE(iDb), zName, zName, zName, 
81353 #ifndef SQLITE_OMIT_TRIGGER
81354       zName,
81355 #endif
81356       zName, nTabName, zTabName
81357   );
81358 
81359 #ifndef SQLITE_OMIT_AUTOINCREMENT
81360   /* If the sqlite_sequence table exists in this database, then update 
81361   ** it with the new table name.
81362   */
81363   if( sqlite3FindTable(db, "sqlite_sequence", zDb) ){
81364     sqlite3NestedParse(pParse,
81365         "UPDATE \"%w\".sqlite_sequence set name = %Q WHERE name = %Q",
81366         zDb, zName, pTab->zName);
81367   }
81368 #endif
81369 
81370 #ifndef SQLITE_OMIT_TRIGGER
81371   /* If there are TEMP triggers on this table, modify the sqlite_temp_master
81372   ** table. Don't do this if the table being ALTERed is itself located in
81373   ** the temp database.
81374   */
81375   if( (zWhere=whereTempTriggers(pParse, pTab))!=0 ){
81376     sqlite3NestedParse(pParse, 
81377         "UPDATE sqlite_temp_master SET "
81378             "sql = sqlite_rename_trigger(sql, %Q), "
81379             "tbl_name = %Q "
81380             "WHERE %s;", zName, zName, zWhere);
81381     sqlite3DbFree(db, zWhere);
81382   }
81383 #endif
81384 
81385 #if !defined(SQLITE_OMIT_FOREIGN_KEY) && !defined(SQLITE_OMIT_TRIGGER)
81386   if( db->flags&SQLITE_ForeignKeys ){
81387     FKey *p;
81388     for(p=sqlite3FkReferences(pTab); p; p=p->pNextTo){
81389       Table *pFrom = p->pFrom;
81390       if( pFrom!=pTab ){
81391         reloadTableSchema(pParse, p->pFrom, pFrom->zName);
81392       }
81393     }
81394   }
81395 #endif
81396 
81397   /* Drop and reload the internal table schema. */
81398   reloadTableSchema(pParse, pTab, zName);
81399 
81400 exit_rename_table:
81401   sqlite3SrcListDelete(db, pSrc);
81402   sqlite3DbFree(db, zName);
81403   db->flags = savedDbFlags;
81404 }
81405 
81406 
81407 /*
81408 ** Generate code to make sure the file format number is at least minFormat.
81409 ** The generated code will increase the file format number if necessary.
81410 */
81411 SQLITE_PRIVATE void sqlite3MinimumFileFormat(Parse *pParse, int iDb, int minFormat){
81412   Vdbe *v;
81413   v = sqlite3GetVdbe(pParse);
81414   /* The VDBE should have been allocated before this routine is called.
81415   ** If that allocation failed, we would have quit before reaching this
81416   ** point */
81417   if( ALWAYS(v) ){
81418     int r1 = sqlite3GetTempReg(pParse);
81419     int r2 = sqlite3GetTempReg(pParse);
81420     int j1;
81421     sqlite3VdbeAddOp3(v, OP_ReadCookie, iDb, r1, BTREE_FILE_FORMAT);
81422     sqlite3VdbeUsesBtree(v, iDb);
81423     sqlite3VdbeAddOp2(v, OP_Integer, minFormat, r2);
81424     j1 = sqlite3VdbeAddOp3(v, OP_Ge, r2, 0, r1);
81425     sqlite3VdbeAddOp3(v, OP_SetCookie, iDb, BTREE_FILE_FORMAT, r2);
81426     sqlite3VdbeJumpHere(v, j1);
81427     sqlite3ReleaseTempReg(pParse, r1);
81428     sqlite3ReleaseTempReg(pParse, r2);
81429   }
81430 }
81431 
81432 /*
81433 ** This function is called after an "ALTER TABLE ... ADD" statement
81434 ** has been parsed. Argument pColDef contains the text of the new
81435 ** column definition.
81436 **
81437 ** The Table structure pParse->pNewTable was extended to include
81438 ** the new column during parsing.
81439 */
81440 SQLITE_PRIVATE void sqlite3AlterFinishAddColumn(Parse *pParse, Token *pColDef){
81441   Table *pNew;              /* Copy of pParse->pNewTable */
81442   Table *pTab;              /* Table being altered */
81443   int iDb;                  /* Database number */
81444   const char *zDb;          /* Database name */
81445   const char *zTab;         /* Table name */
81446   char *zCol;               /* Null-terminated column definition */
81447   Column *pCol;             /* The new column */
81448   Expr *pDflt;              /* Default value for the new column */
81449   sqlite3 *db;              /* The database connection; */
81450 
81451   db = pParse->db;
81452   if( pParse->nErr || db->mallocFailed ) return;
81453   pNew = pParse->pNewTable;
81454   assert( pNew );
81455 
81456   assert( sqlite3BtreeHoldsAllMutexes(db) );
81457   iDb = sqlite3SchemaToIndex(db, pNew->pSchema);
81458   zDb = db->aDb[iDb].zName;
81459   zTab = &pNew->zName[16];  /* Skip the "sqlite_altertab_" prefix on the name */
81460   pCol = &pNew->aCol[pNew->nCol-1];
81461   pDflt = pCol->pDflt;
81462   pTab = sqlite3FindTable(db, zTab, zDb);
81463   assert( pTab );
81464 
81465 #ifndef SQLITE_OMIT_AUTHORIZATION
81466   /* Invoke the authorization callback. */
81467   if( sqlite3AuthCheck(pParse, SQLITE_ALTER_TABLE, zDb, pTab->zName, 0) ){
81468     return;
81469   }
81470 #endif
81471 
81472   /* If the default value for the new column was specified with a 
81473   ** literal NULL, then set pDflt to 0. This simplifies checking
81474   ** for an SQL NULL default below.
81475   */
81476   if( pDflt && pDflt->op==TK_NULL ){
81477     pDflt = 0;
81478   }
81479 
81480   /* Check that the new column is not specified as PRIMARY KEY or UNIQUE.
81481   ** If there is a NOT NULL constraint, then the default value for the
81482   ** column must not be NULL.
81483   */
81484   if( pCol->colFlags & COLFLAG_PRIMKEY ){
81485     sqlite3ErrorMsg(pParse, "Cannot add a PRIMARY KEY column");
81486     return;
81487   }
81488   if( pNew->pIndex ){
81489     sqlite3ErrorMsg(pParse, "Cannot add a UNIQUE column");
81490     return;
81491   }
81492   if( (db->flags&SQLITE_ForeignKeys) && pNew->pFKey && pDflt ){
81493     sqlite3ErrorMsg(pParse, 
81494         "Cannot add a REFERENCES column with non-NULL default value");
81495     return;
81496   }
81497   if( pCol->notNull && !pDflt ){
81498     sqlite3ErrorMsg(pParse, 
81499         "Cannot add a NOT NULL column with default value NULL");
81500     return;
81501   }
81502 
81503   /* Ensure the default expression is something that sqlite3ValueFromExpr()
81504   ** can handle (i.e. not CURRENT_TIME etc.)
81505   */
81506   if( pDflt ){
81507     sqlite3_value *pVal = 0;
81508     if( sqlite3ValueFromExpr(db, pDflt, SQLITE_UTF8, SQLITE_AFF_NONE, &pVal) ){
81509       db->mallocFailed = 1;
81510       return;
81511     }
81512     if( !pVal ){
81513       sqlite3ErrorMsg(pParse, "Cannot add a column with non-constant default");
81514       return;
81515     }
81516     sqlite3ValueFree(pVal);
81517   }
81518 
81519   /* Modify the CREATE TABLE statement. */
81520   zCol = sqlite3DbStrNDup(db, (char*)pColDef->z, pColDef->n);
81521   if( zCol ){
81522     char *zEnd = &zCol[pColDef->n-1];
81523     int savedDbFlags = db->flags;
81524     while( zEnd>zCol && (*zEnd==';' || sqlite3Isspace(*zEnd)) ){
81525       *zEnd-- = '\0';
81526     }
81527     db->flags |= SQLITE_PreferBuiltin;
81528     sqlite3NestedParse(pParse, 
81529         "UPDATE \"%w\".%s SET "
81530           "sql = substr(sql,1,%d) || ', ' || %Q || substr(sql,%d) "
81531         "WHERE type = 'table' AND name = %Q", 
81532       zDb, SCHEMA_TABLE(iDb), pNew->addColOffset, zCol, pNew->addColOffset+1,
81533       zTab
81534     );
81535     sqlite3DbFree(db, zCol);
81536     db->flags = savedDbFlags;
81537   }
81538 
81539   /* If the default value of the new column is NULL, then set the file
81540   ** format to 2. If the default value of the new column is not NULL,
81541   ** the file format becomes 3.
81542   */
81543   sqlite3MinimumFileFormat(pParse, iDb, pDflt ? 3 : 2);
81544 
81545   /* Reload the schema of the modified table. */
81546   reloadTableSchema(pParse, pTab, pTab->zName);
81547 }
81548 
81549 /*
81550 ** This function is called by the parser after the table-name in
81551 ** an "ALTER TABLE <table-name> ADD" statement is parsed. Argument 
81552 ** pSrc is the full-name of the table being altered.
81553 **
81554 ** This routine makes a (partial) copy of the Table structure
81555 ** for the table being altered and sets Parse.pNewTable to point
81556 ** to it. Routines called by the parser as the column definition
81557 ** is parsed (i.e. sqlite3AddColumn()) add the new Column data to 
81558 ** the copy. The copy of the Table structure is deleted by tokenize.c 
81559 ** after parsing is finished.
81560 **
81561 ** Routine sqlite3AlterFinishAddColumn() will be called to complete
81562 ** coding the "ALTER TABLE ... ADD" statement.
81563 */
81564 SQLITE_PRIVATE void sqlite3AlterBeginAddColumn(Parse *pParse, SrcList *pSrc){
81565   Table *pNew;
81566   Table *pTab;
81567   Vdbe *v;
81568   int iDb;
81569   int i;
81570   int nAlloc;
81571   sqlite3 *db = pParse->db;
81572 
81573   /* Look up the table being altered. */
81574   assert( pParse->pNewTable==0 );
81575   assert( sqlite3BtreeHoldsAllMutexes(db) );
81576   if( db->mallocFailed ) goto exit_begin_add_column;
81577   pTab = sqlite3LocateTableItem(pParse, 0, &pSrc->a[0]);
81578   if( !pTab ) goto exit_begin_add_column;
81579 
81580 #ifndef SQLITE_OMIT_VIRTUALTABLE
81581   if( IsVirtual(pTab) ){
81582     sqlite3ErrorMsg(pParse, "virtual tables may not be altered");
81583     goto exit_begin_add_column;
81584   }
81585 #endif
81586 
81587   /* Make sure this is not an attempt to ALTER a view. */
81588   if( pTab->pSelect ){
81589     sqlite3ErrorMsg(pParse, "Cannot add a column to a view");
81590     goto exit_begin_add_column;
81591   }
81592   if( SQLITE_OK!=isSystemTable(pParse, pTab->zName) ){
81593     goto exit_begin_add_column;
81594   }
81595 
81596   assert( pTab->addColOffset>0 );
81597   iDb = sqlite3SchemaToIndex(db, pTab->pSchema);
81598 
81599   /* Put a copy of the Table struct in Parse.pNewTable for the
81600   ** sqlite3AddColumn() function and friends to modify.  But modify
81601   ** the name by adding an "sqlite_altertab_" prefix.  By adding this
81602   ** prefix, we insure that the name will not collide with an existing
81603   ** table because user table are not allowed to have the "sqlite_"
81604   ** prefix on their name.
81605   */
81606   pNew = (Table*)sqlite3DbMallocZero(db, sizeof(Table));
81607   if( !pNew ) goto exit_begin_add_column;
81608   pParse->pNewTable = pNew;
81609   pNew->nRef = 1;
81610   pNew->nCol = pTab->nCol;
81611   assert( pNew->nCol>0 );
81612   nAlloc = (((pNew->nCol-1)/8)*8)+8;
81613   assert( nAlloc>=pNew->nCol && nAlloc%8==0 && nAlloc-pNew->nCol<8 );
81614   pNew->aCol = (Column*)sqlite3DbMallocZero(db, sizeof(Column)*nAlloc);
81615   pNew->zName = sqlite3MPrintf(db, "sqlite_altertab_%s", pTab->zName);
81616   if( !pNew->aCol || !pNew->zName ){
81617     db->mallocFailed = 1;
81618     goto exit_begin_add_column;
81619   }
81620   memcpy(pNew->aCol, pTab->aCol, sizeof(Column)*pNew->nCol);
81621   for(i=0; i<pNew->nCol; i++){
81622     Column *pCol = &pNew->aCol[i];
81623     pCol->zName = sqlite3DbStrDup(db, pCol->zName);
81624     pCol->zColl = 0;
81625     pCol->zType = 0;
81626     pCol->pDflt = 0;
81627     pCol->zDflt = 0;
81628   }
81629   pNew->pSchema = db->aDb[iDb].pSchema;
81630   pNew->addColOffset = pTab->addColOffset;
81631   pNew->nRef = 1;
81632 
81633   /* Begin a transaction and increment the schema cookie.  */
81634   sqlite3BeginWriteOperation(pParse, 0, iDb);
81635   v = sqlite3GetVdbe(pParse);
81636   if( !v ) goto exit_begin_add_column;
81637   sqlite3ChangeCookie(pParse, iDb);
81638 
81639 exit_begin_add_column:
81640   sqlite3SrcListDelete(db, pSrc);
81641   return;
81642 }
81643 #endif  /* SQLITE_ALTER_TABLE */
81644 
81645 /************** End of alter.c ***********************************************/
81646 /************** Begin file analyze.c *****************************************/
81647 /*
81648 ** 2005-07-08
81649 **
81650 ** The author disclaims copyright to this source code.  In place of
81651 ** a legal notice, here is a blessing:
81652 **
81653 **    May you do good and not evil.
81654 **    May you find forgiveness for yourself and forgive others.
81655 **    May you share freely, never taking more than you give.
81656 **
81657 *************************************************************************
81658 ** This file contains code associated with the ANALYZE command.
81659 **
81660 ** The ANALYZE command gather statistics about the content of tables
81661 ** and indices.  These statistics are made available to the query planner
81662 ** to help it make better decisions about how to perform queries.
81663 **
81664 ** The following system tables are or have been supported:
81665 **
81666 **    CREATE TABLE sqlite_stat1(tbl, idx, stat);
81667 **    CREATE TABLE sqlite_stat2(tbl, idx, sampleno, sample);
81668 **    CREATE TABLE sqlite_stat3(tbl, idx, nEq, nLt, nDLt, sample);
81669 **    CREATE TABLE sqlite_stat4(tbl, idx, nEq, nLt, nDLt, sample);
81670 **
81671 ** Additional tables might be added in future releases of SQLite.
81672 ** The sqlite_stat2 table is not created or used unless the SQLite version
81673 ** is between 3.6.18 and 3.7.8, inclusive, and unless SQLite is compiled
81674 ** with SQLITE_ENABLE_STAT2.  The sqlite_stat2 table is deprecated.
81675 ** The sqlite_stat2 table is superseded by sqlite_stat3, which is only
81676 ** created and used by SQLite versions 3.7.9 and later and with
81677 ** SQLITE_ENABLE_STAT3 defined.  The functionality of sqlite_stat3
81678 ** is a superset of sqlite_stat2.  The sqlite_stat4 is an enhanced
81679 ** version of sqlite_stat3 and is only available when compiled with
81680 ** SQLITE_ENABLE_STAT4 and in SQLite versions 3.8.1 and later.  It is
81681 ** not possible to enable both STAT3 and STAT4 at the same time.  If they
81682 ** are both enabled, then STAT4 takes precedence.
81683 **
81684 ** For most applications, sqlite_stat1 provides all the statisics required
81685 ** for the query planner to make good choices.
81686 **
81687 ** Format of sqlite_stat1:
81688 **
81689 ** There is normally one row per index, with the index identified by the
81690 ** name in the idx column.  The tbl column is the name of the table to
81691 ** which the index belongs.  In each such row, the stat column will be
81692 ** a string consisting of a list of integers.  The first integer in this
81693 ** list is the number of rows in the index.  (This is the same as the
81694 ** number of rows in the table, except for partial indices.)  The second
81695 ** integer is the average number of rows in the index that have the same
81696 ** value in the first column of the index.  The third integer is the average
81697 ** number of rows in the index that have the same value for the first two
81698 ** columns.  The N-th integer (for N>1) is the average number of rows in 
81699 ** the index which have the same value for the first N-1 columns.  For
81700 ** a K-column index, there will be K+1 integers in the stat column.  If
81701 ** the index is unique, then the last integer will be 1.
81702 **
81703 ** The list of integers in the stat column can optionally be followed
81704 ** by the keyword "unordered".  The "unordered" keyword, if it is present,
81705 ** must be separated from the last integer by a single space.  If the
81706 ** "unordered" keyword is present, then the query planner assumes that
81707 ** the index is unordered and will not use the index for a range query.
81708 ** 
81709 ** If the sqlite_stat1.idx column is NULL, then the sqlite_stat1.stat
81710 ** column contains a single integer which is the (estimated) number of
81711 ** rows in the table identified by sqlite_stat1.tbl.
81712 **
81713 ** Format of sqlite_stat2:
81714 **
81715 ** The sqlite_stat2 is only created and is only used if SQLite is compiled
81716 ** with SQLITE_ENABLE_STAT2 and if the SQLite version number is between
81717 ** 3.6.18 and 3.7.8.  The "stat2" table contains additional information
81718 ** about the distribution of keys within an index.  The index is identified by
81719 ** the "idx" column and the "tbl" column is the name of the table to which
81720 ** the index belongs.  There are usually 10 rows in the sqlite_stat2
81721 ** table for each index.
81722 **
81723 ** The sqlite_stat2 entries for an index that have sampleno between 0 and 9
81724 ** inclusive are samples of the left-most key value in the index taken at
81725 ** evenly spaced points along the index.  Let the number of samples be S
81726 ** (10 in the standard build) and let C be the number of rows in the index.
81727 ** Then the sampled rows are given by:
81728 **
81729 **     rownumber = (i*C*2 + C)/(S*2)
81730 **
81731 ** For i between 0 and S-1.  Conceptually, the index space is divided into
81732 ** S uniform buckets and the samples are the middle row from each bucket.
81733 **
81734 ** The format for sqlite_stat2 is recorded here for legacy reference.  This
81735 ** version of SQLite does not support sqlite_stat2.  It neither reads nor
81736 ** writes the sqlite_stat2 table.  This version of SQLite only supports
81737 ** sqlite_stat3.
81738 **
81739 ** Format for sqlite_stat3:
81740 **
81741 ** The sqlite_stat3 format is a subset of sqlite_stat4.  Hence, the
81742 ** sqlite_stat4 format will be described first.  Further information
81743 ** about sqlite_stat3 follows the sqlite_stat4 description.
81744 **
81745 ** Format for sqlite_stat4:
81746 **
81747 ** As with sqlite_stat2, the sqlite_stat4 table contains histogram data
81748 ** to aid the query planner in choosing good indices based on the values
81749 ** that indexed columns are compared against in the WHERE clauses of
81750 ** queries.
81751 **
81752 ** The sqlite_stat4 table contains multiple entries for each index.
81753 ** The idx column names the index and the tbl column is the table of the
81754 ** index.  If the idx and tbl columns are the same, then the sample is
81755 ** of the INTEGER PRIMARY KEY.  The sample column is a blob which is the
81756 ** binary encoding of a key from the index.  The nEq column is a
81757 ** list of integers.  The first integer is the approximate number
81758 ** of entries in the index whose left-most column exactly matches
81759 ** the left-most column of the sample.  The second integer in nEq
81760 ** is the approximate number of entries in the index where the
81761 ** first two columns match the first two columns of the sample.
81762 ** And so forth.  nLt is another list of integers that show the approximate
81763 ** number of entries that are strictly less than the sample.  The first
81764 ** integer in nLt contains the number of entries in the index where the
81765 ** left-most column is less than the left-most column of the sample.
81766 ** The K-th integer in the nLt entry is the number of index entries 
81767 ** where the first K columns are less than the first K columns of the
81768 ** sample.  The nDLt column is like nLt except that it contains the 
81769 ** number of distinct entries in the index that are less than the
81770 ** sample.
81771 **
81772 ** There can be an arbitrary number of sqlite_stat4 entries per index.
81773 ** The ANALYZE command will typically generate sqlite_stat4 tables
81774 ** that contain between 10 and 40 samples which are distributed across
81775 ** the key space, though not uniformly, and which include samples with
81776 ** large nEq values.
81777 **
81778 ** Format for sqlite_stat3 redux:
81779 **
81780 ** The sqlite_stat3 table is like sqlite_stat4 except that it only
81781 ** looks at the left-most column of the index.  The sqlite_stat3.sample
81782 ** column contains the actual value of the left-most column instead
81783 ** of a blob encoding of the complete index key as is found in
81784 ** sqlite_stat4.sample.  The nEq, nLt, and nDLt entries of sqlite_stat3
81785 ** all contain just a single integer which is the same as the first
81786 ** integer in the equivalent columns in sqlite_stat4.
81787 */
81788 #ifndef SQLITE_OMIT_ANALYZE
81789 
81790 #if defined(SQLITE_ENABLE_STAT4)
81791 # define IsStat4     1
81792 # define IsStat3     0
81793 #elif defined(SQLITE_ENABLE_STAT3)
81794 # define IsStat4     0
81795 # define IsStat3     1
81796 #else
81797 # define IsStat4     0
81798 # define IsStat3     0
81799 # undef SQLITE_STAT4_SAMPLES
81800 # define SQLITE_STAT4_SAMPLES 1
81801 #endif
81802 #define IsStat34    (IsStat3+IsStat4)  /* 1 for STAT3 or STAT4. 0 otherwise */
81803 
81804 /*
81805 ** This routine generates code that opens the sqlite_statN tables.
81806 ** The sqlite_stat1 table is always relevant.  sqlite_stat2 is now
81807 ** obsolete.  sqlite_stat3 and sqlite_stat4 are only opened when
81808 ** appropriate compile-time options are provided.
81809 **
81810 ** If the sqlite_statN tables do not previously exist, it is created.
81811 **
81812 ** Argument zWhere may be a pointer to a buffer containing a table name,
81813 ** or it may be a NULL pointer. If it is not NULL, then all entries in
81814 ** the sqlite_statN tables associated with the named table are deleted.
81815 ** If zWhere==0, then code is generated to delete all stat table entries.
81816 */
81817 static void openStatTable(
81818   Parse *pParse,          /* Parsing context */
81819   int iDb,                /* The database we are looking in */
81820   int iStatCur,           /* Open the sqlite_stat1 table on this cursor */
81821   const char *zWhere,     /* Delete entries for this table or index */
81822   const char *zWhereType  /* Either "tbl" or "idx" */
81823 ){
81824   static const struct {
81825     const char *zName;
81826     const char *zCols;
81827   } aTable[] = {
81828     { "sqlite_stat1", "tbl,idx,stat" },
81829 #if defined(SQLITE_ENABLE_STAT4)
81830     { "sqlite_stat4", "tbl,idx,neq,nlt,ndlt,sample" },
81831     { "sqlite_stat3", 0 },
81832 #elif defined(SQLITE_ENABLE_STAT3)
81833     { "sqlite_stat3", "tbl,idx,neq,nlt,ndlt,sample" },
81834     { "sqlite_stat4", 0 },
81835 #else
81836     { "sqlite_stat3", 0 },
81837     { "sqlite_stat4", 0 },
81838 #endif
81839   };
81840   int i;
81841   sqlite3 *db = pParse->db;
81842   Db *pDb;
81843   Vdbe *v = sqlite3GetVdbe(pParse);
81844   int aRoot[ArraySize(aTable)];
81845   u8 aCreateTbl[ArraySize(aTable)];
81846 
81847   if( v==0 ) return;
81848   assert( sqlite3BtreeHoldsAllMutexes(db) );
81849   assert( sqlite3VdbeDb(v)==db );
81850   pDb = &db->aDb[iDb];
81851 
81852   /* Create new statistic tables if they do not exist, or clear them
81853   ** if they do already exist.
81854   */
81855   for(i=0; i<ArraySize(aTable); i++){
81856     const char *zTab = aTable[i].zName;
81857     Table *pStat;
81858     if( (pStat = sqlite3FindTable(db, zTab, pDb->zName))==0 ){
81859       if( aTable[i].zCols ){
81860         /* The sqlite_statN table does not exist. Create it. Note that a 
81861         ** side-effect of the CREATE TABLE statement is to leave the rootpage 
81862         ** of the new table in register pParse->regRoot. This is important 
81863         ** because the OpenWrite opcode below will be needing it. */
81864         sqlite3NestedParse(pParse,
81865             "CREATE TABLE %Q.%s(%s)", pDb->zName, zTab, aTable[i].zCols
81866         );
81867         aRoot[i] = pParse->regRoot;
81868         aCreateTbl[i] = OPFLAG_P2ISREG;
81869       }
81870     }else{
81871       /* The table already exists. If zWhere is not NULL, delete all entries 
81872       ** associated with the table zWhere. If zWhere is NULL, delete the
81873       ** entire contents of the table. */
81874       aRoot[i] = pStat->tnum;
81875       aCreateTbl[i] = 0;
81876       sqlite3TableLock(pParse, iDb, aRoot[i], 1, zTab);
81877       if( zWhere ){
81878         sqlite3NestedParse(pParse,
81879            "DELETE FROM %Q.%s WHERE %s=%Q",
81880            pDb->zName, zTab, zWhereType, zWhere
81881         );
81882       }else{
81883         /* The sqlite_stat[134] table already exists.  Delete all rows. */
81884         sqlite3VdbeAddOp2(v, OP_Clear, aRoot[i], iDb);
81885       }
81886     }
81887   }
81888 
81889   /* Open the sqlite_stat[134] tables for writing. */
81890   for(i=0; aTable[i].zCols; i++){
81891     assert( i<ArraySize(aTable) );
81892     sqlite3VdbeAddOp4Int(v, OP_OpenWrite, iStatCur+i, aRoot[i], iDb, 3);
81893     sqlite3VdbeChangeP5(v, aCreateTbl[i]);
81894   }
81895 }
81896 
81897 /*
81898 ** Recommended number of samples for sqlite_stat4
81899 */
81900 #ifndef SQLITE_STAT4_SAMPLES
81901 # define SQLITE_STAT4_SAMPLES 24
81902 #endif
81903 
81904 /*
81905 ** Three SQL functions - stat_init(), stat_push(), and stat_get() -
81906 ** share an instance of the following structure to hold their state
81907 ** information.
81908 */
81909 typedef struct Stat4Accum Stat4Accum;
81910 typedef struct Stat4Sample Stat4Sample;
81911 struct Stat4Sample {
81912   tRowcnt *anEq;                  /* sqlite_stat4.nEq */
81913   tRowcnt *anDLt;                 /* sqlite_stat4.nDLt */
81914 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
81915   tRowcnt *anLt;                  /* sqlite_stat4.nLt */
81916   union {
81917     i64 iRowid;                     /* Rowid in main table of the key */
81918     u8 *aRowid;                     /* Key for WITHOUT ROWID tables */
81919   } u;
81920   u32 nRowid;                     /* Sizeof aRowid[] */
81921   u8 isPSample;                   /* True if a periodic sample */
81922   int iCol;                       /* If !isPSample, the reason for inclusion */
81923   u32 iHash;                      /* Tiebreaker hash */
81924 #endif
81925 };                                                    
81926 struct Stat4Accum {
81927   tRowcnt nRow;             /* Number of rows in the entire table */
81928   tRowcnt nPSample;         /* How often to do a periodic sample */
81929   int nCol;                 /* Number of columns in index + rowid */
81930   int mxSample;             /* Maximum number of samples to accumulate */
81931   Stat4Sample current;      /* Current row as a Stat4Sample */
81932   u32 iPrn;                 /* Pseudo-random number used for sampling */
81933   Stat4Sample *aBest;       /* Array of nCol best samples */
81934   int iMin;                 /* Index in a[] of entry with minimum score */
81935   int nSample;              /* Current number of samples */
81936   int iGet;                 /* Index of current sample accessed by stat_get() */
81937   Stat4Sample *a;           /* Array of mxSample Stat4Sample objects */
81938   sqlite3 *db;              /* Database connection, for malloc() */
81939 };
81940 
81941 /* Reclaim memory used by a Stat4Sample
81942 */
81943 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
81944 static void sampleClear(sqlite3 *db, Stat4Sample *p){
81945   assert( db!=0 );
81946   if( p->nRowid ){
81947     sqlite3DbFree(db, p->u.aRowid);
81948     p->nRowid = 0;
81949   }
81950 }
81951 #endif
81952 
81953 /* Initialize the BLOB value of a ROWID
81954 */
81955 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
81956 static void sampleSetRowid(sqlite3 *db, Stat4Sample *p, int n, const u8 *pData){
81957   assert( db!=0 );
81958   if( p->nRowid ) sqlite3DbFree(db, p->u.aRowid);
81959   p->u.aRowid = sqlite3DbMallocRaw(db, n);
81960   if( p->u.aRowid ){
81961     p->nRowid = n;
81962     memcpy(p->u.aRowid, pData, n);
81963   }else{
81964     p->nRowid = 0;
81965   }
81966 }
81967 #endif
81968 
81969 /* Initialize the INTEGER value of a ROWID.
81970 */
81971 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
81972 static void sampleSetRowidInt64(sqlite3 *db, Stat4Sample *p, i64 iRowid){
81973   assert( db!=0 );
81974   if( p->nRowid ) sqlite3DbFree(db, p->u.aRowid);
81975   p->nRowid = 0;
81976   p->u.iRowid = iRowid;
81977 }
81978 #endif
81979 
81980 
81981 /*
81982 ** Copy the contents of object (*pFrom) into (*pTo).
81983 */
81984 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
81985 static void sampleCopy(Stat4Accum *p, Stat4Sample *pTo, Stat4Sample *pFrom){
81986   pTo->isPSample = pFrom->isPSample;
81987   pTo->iCol = pFrom->iCol;
81988   pTo->iHash = pFrom->iHash;
81989   memcpy(pTo->anEq, pFrom->anEq, sizeof(tRowcnt)*p->nCol);
81990   memcpy(pTo->anLt, pFrom->anLt, sizeof(tRowcnt)*p->nCol);
81991   memcpy(pTo->anDLt, pFrom->anDLt, sizeof(tRowcnt)*p->nCol);
81992   if( pFrom->nRowid ){
81993     sampleSetRowid(p->db, pTo, pFrom->nRowid, pFrom->u.aRowid);
81994   }else{
81995     sampleSetRowidInt64(p->db, pTo, pFrom->u.iRowid);
81996   }
81997 }
81998 #endif
81999 
82000 /*
82001 ** Reclaim all memory of a Stat4Accum structure.
82002 */
82003 static void stat4Destructor(void *pOld){
82004   Stat4Accum *p = (Stat4Accum*)pOld;
82005 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
82006   int i;
82007   for(i=0; i<p->nCol; i++) sampleClear(p->db, p->aBest+i);
82008   for(i=0; i<p->mxSample; i++) sampleClear(p->db, p->a+i);
82009   sampleClear(p->db, &p->current);
82010 #endif
82011   sqlite3DbFree(p->db, p);
82012 }
82013 
82014 /*
82015 ** Implementation of the stat_init(N,C) SQL function. The two parameters
82016 ** are the number of rows in the table or index (C) and the number of columns
82017 ** in the index (N).  The second argument (C) is only used for STAT3 and STAT4.
82018 **
82019 ** This routine allocates the Stat4Accum object in heap memory. The return 
82020 ** value is a pointer to the the Stat4Accum object encoded as a blob (i.e. 
82021 ** the size of the blob is sizeof(void*) bytes). 
82022 */
82023 static void statInit(
82024   sqlite3_context *context,
82025   int argc,
82026   sqlite3_value **argv
82027 ){
82028   Stat4Accum *p;
82029   int nCol;                       /* Number of columns in index being sampled */
82030   int nColUp;                     /* nCol rounded up for alignment */
82031   int n;                          /* Bytes of space to allocate */
82032   sqlite3 *db;                    /* Database connection */
82033 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
82034   int mxSample = SQLITE_STAT4_SAMPLES;
82035 #endif
82036 
82037   /* Decode the three function arguments */
82038   UNUSED_PARAMETER(argc);
82039   nCol = sqlite3_value_int(argv[0]);
82040   assert( nCol>1 );               /* >1 because it includes the rowid column */
82041   nColUp = sizeof(tRowcnt)<8 ? (nCol+1)&~1 : nCol;
82042 
82043   /* Allocate the space required for the Stat4Accum object */
82044   n = sizeof(*p) 
82045     + sizeof(tRowcnt)*nColUp                  /* Stat4Accum.anEq */
82046     + sizeof(tRowcnt)*nColUp                  /* Stat4Accum.anDLt */
82047 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
82048     + sizeof(tRowcnt)*nColUp                  /* Stat4Accum.anLt */
82049     + sizeof(Stat4Sample)*(nCol+mxSample)     /* Stat4Accum.aBest[], a[] */
82050     + sizeof(tRowcnt)*3*nColUp*(nCol+mxSample)
82051 #endif
82052   ;
82053   db = sqlite3_context_db_handle(context);
82054   p = sqlite3DbMallocZero(db, n);
82055   if( p==0 ){
82056     sqlite3_result_error_nomem(context);
82057     return;
82058   }
82059 
82060   p->db = db;
82061   p->nRow = 0;
82062   p->nCol = nCol;
82063   p->current.anDLt = (tRowcnt*)&p[1];
82064   p->current.anEq = &p->current.anDLt[nColUp];
82065 
82066 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
82067   {
82068     u8 *pSpace;                     /* Allocated space not yet assigned */
82069     int i;                          /* Used to iterate through p->aSample[] */
82070 
82071     p->iGet = -1;
82072     p->mxSample = mxSample;
82073     p->nPSample = (tRowcnt)(sqlite3_value_int64(argv[1])/(mxSample/3+1) + 1);
82074     p->current.anLt = &p->current.anEq[nColUp];
82075     p->iPrn = nCol*0x689e962d ^ sqlite3_value_int(argv[1])*0xd0944565;
82076   
82077     /* Set up the Stat4Accum.a[] and aBest[] arrays */
82078     p->a = (struct Stat4Sample*)&p->current.anLt[nColUp];
82079     p->aBest = &p->a[mxSample];
82080     pSpace = (u8*)(&p->a[mxSample+nCol]);
82081     for(i=0; i<(mxSample+nCol); i++){
82082       p->a[i].anEq = (tRowcnt *)pSpace; pSpace += (sizeof(tRowcnt) * nColUp);
82083       p->a[i].anLt = (tRowcnt *)pSpace; pSpace += (sizeof(tRowcnt) * nColUp);
82084       p->a[i].anDLt = (tRowcnt *)pSpace; pSpace += (sizeof(tRowcnt) * nColUp);
82085     }
82086     assert( (pSpace - (u8*)p)==n );
82087   
82088     for(i=0; i<nCol; i++){
82089       p->aBest[i].iCol = i;
82090     }
82091   }
82092 #endif
82093 
82094   /* Return a pointer to the allocated object to the caller */
82095   sqlite3_result_blob(context, p, sizeof(p), stat4Destructor);
82096 }
82097 static const FuncDef statInitFuncdef = {
82098   1+IsStat34,      /* nArg */
82099   SQLITE_UTF8,     /* funcFlags */
82100   0,               /* pUserData */
82101   0,               /* pNext */
82102   statInit,        /* xFunc */
82103   0,               /* xStep */
82104   0,               /* xFinalize */
82105   "stat_init",     /* zName */
82106   0,               /* pHash */
82107   0                /* pDestructor */
82108 };
82109 
82110 #ifdef SQLITE_ENABLE_STAT4
82111 /*
82112 ** pNew and pOld are both candidate non-periodic samples selected for 
82113 ** the same column (pNew->iCol==pOld->iCol). Ignoring this column and 
82114 ** considering only any trailing columns and the sample hash value, this
82115 ** function returns true if sample pNew is to be preferred over pOld.
82116 ** In other words, if we assume that the cardinalities of the selected
82117 ** column for pNew and pOld are equal, is pNew to be preferred over pOld.
82118 **
82119 ** This function assumes that for each argument sample, the contents of
82120 ** the anEq[] array from pSample->anEq[pSample->iCol+1] onwards are valid. 
82121 */
82122 static int sampleIsBetterPost(
82123   Stat4Accum *pAccum, 
82124   Stat4Sample *pNew, 
82125   Stat4Sample *pOld
82126 ){
82127   int nCol = pAccum->nCol;
82128   int i;
82129   assert( pNew->iCol==pOld->iCol );
82130   for(i=pNew->iCol+1; i<nCol; i++){
82131     if( pNew->anEq[i]>pOld->anEq[i] ) return 1;
82132     if( pNew->anEq[i]<pOld->anEq[i] ) return 0;
82133   }
82134   if( pNew->iHash>pOld->iHash ) return 1;
82135   return 0;
82136 }
82137 #endif
82138 
82139 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
82140 /*
82141 ** Return true if pNew is to be preferred over pOld.
82142 **
82143 ** This function assumes that for each argument sample, the contents of
82144 ** the anEq[] array from pSample->anEq[pSample->iCol] onwards are valid. 
82145 */
82146 static int sampleIsBetter(
82147   Stat4Accum *pAccum, 
82148   Stat4Sample *pNew, 
82149   Stat4Sample *pOld
82150 ){
82151   tRowcnt nEqNew = pNew->anEq[pNew->iCol];
82152   tRowcnt nEqOld = pOld->anEq[pOld->iCol];
82153 
82154   assert( pOld->isPSample==0 && pNew->isPSample==0 );
82155   assert( IsStat4 || (pNew->iCol==0 && pOld->iCol==0) );
82156 
82157   if( (nEqNew>nEqOld) ) return 1;
82158 #ifdef SQLITE_ENABLE_STAT4
82159   if( nEqNew==nEqOld ){
82160     if( pNew->iCol<pOld->iCol ) return 1;
82161     return (pNew->iCol==pOld->iCol && sampleIsBetterPost(pAccum, pNew, pOld));
82162   }
82163   return 0;
82164 #else
82165   return (nEqNew==nEqOld && pNew->iHash>pOld->iHash);
82166 #endif
82167 }
82168 
82169 /*
82170 ** Copy the contents of sample *pNew into the p->a[] array. If necessary,
82171 ** remove the least desirable sample from p->a[] to make room.
82172 */
82173 static void sampleInsert(Stat4Accum *p, Stat4Sample *pNew, int nEqZero){
82174   Stat4Sample *pSample = 0;
82175   int i;
82176 
82177   assert( IsStat4 || nEqZero==0 );
82178 
82179 #ifdef SQLITE_ENABLE_STAT4
82180   if( pNew->isPSample==0 ){
82181     Stat4Sample *pUpgrade = 0;
82182     assert( pNew->anEq[pNew->iCol]>0 );
82183 
82184     /* This sample is being added because the prefix that ends in column 
82185     ** iCol occurs many times in the table. However, if we have already
82186     ** added a sample that shares this prefix, there is no need to add
82187     ** this one. Instead, upgrade the priority of the highest priority
82188     ** existing sample that shares this prefix.  */
82189     for(i=p->nSample-1; i>=0; i--){
82190       Stat4Sample *pOld = &p->a[i];
82191       if( pOld->anEq[pNew->iCol]==0 ){
82192         if( pOld->isPSample ) return;
82193         assert( pOld->iCol>pNew->iCol );
82194         assert( sampleIsBetter(p, pNew, pOld) );
82195         if( pUpgrade==0 || sampleIsBetter(p, pOld, pUpgrade) ){
82196           pUpgrade = pOld;
82197         }
82198       }
82199     }
82200     if( pUpgrade ){
82201       pUpgrade->iCol = pNew->iCol;
82202       pUpgrade->anEq[pUpgrade->iCol] = pNew->anEq[pUpgrade->iCol];
82203       goto find_new_min;
82204     }
82205   }
82206 #endif
82207 
82208   /* If necessary, remove sample iMin to make room for the new sample. */
82209   if( p->nSample>=p->mxSample ){
82210     Stat4Sample *pMin = &p->a[p->iMin];
82211     tRowcnt *anEq = pMin->anEq;
82212     tRowcnt *anLt = pMin->anLt;
82213     tRowcnt *anDLt = pMin->anDLt;
82214     sampleClear(p->db, pMin);
82215     memmove(pMin, &pMin[1], sizeof(p->a[0])*(p->nSample-p->iMin-1));
82216     pSample = &p->a[p->nSample-1];
82217     pSample->nRowid = 0;
82218     pSample->anEq = anEq;
82219     pSample->anDLt = anDLt;
82220     pSample->anLt = anLt;
82221     p->nSample = p->mxSample-1;
82222   }
82223 
82224   /* The "rows less-than" for the rowid column must be greater than that
82225   ** for the last sample in the p->a[] array. Otherwise, the samples would
82226   ** be out of order. */
82227 #ifdef SQLITE_ENABLE_STAT4
82228   assert( p->nSample==0 
82229        || pNew->anLt[p->nCol-1] > p->a[p->nSample-1].anLt[p->nCol-1] );
82230 #endif
82231 
82232   /* Insert the new sample */
82233   pSample = &p->a[p->nSample];
82234   sampleCopy(p, pSample, pNew);
82235   p->nSample++;
82236 
82237   /* Zero the first nEqZero entries in the anEq[] array. */
82238   memset(pSample->anEq, 0, sizeof(tRowcnt)*nEqZero);
82239 
82240 #ifdef SQLITE_ENABLE_STAT4
82241  find_new_min:
82242 #endif
82243   if( p->nSample>=p->mxSample ){
82244     int iMin = -1;
82245     for(i=0; i<p->mxSample; i++){
82246       if( p->a[i].isPSample ) continue;
82247       if( iMin<0 || sampleIsBetter(p, &p->a[iMin], &p->a[i]) ){
82248         iMin = i;
82249       }
82250     }
82251     assert( iMin>=0 );
82252     p->iMin = iMin;
82253   }
82254 }
82255 #endif /* SQLITE_ENABLE_STAT3_OR_STAT4 */
82256 
82257 /*
82258 ** Field iChng of the index being scanned has changed. So at this point
82259 ** p->current contains a sample that reflects the previous row of the
82260 ** index. The value of anEq[iChng] and subsequent anEq[] elements are
82261 ** correct at this point.
82262 */
82263 static void samplePushPrevious(Stat4Accum *p, int iChng){
82264 #ifdef SQLITE_ENABLE_STAT4
82265   int i;
82266 
82267   /* Check if any samples from the aBest[] array should be pushed
82268   ** into IndexSample.a[] at this point.  */
82269   for(i=(p->nCol-2); i>=iChng; i--){
82270     Stat4Sample *pBest = &p->aBest[i];
82271     pBest->anEq[i] = p->current.anEq[i];
82272     if( p->nSample<p->mxSample || sampleIsBetter(p, pBest, &p->a[p->iMin]) ){
82273       sampleInsert(p, pBest, i);
82274     }
82275   }
82276 
82277   /* Update the anEq[] fields of any samples already collected. */
82278   for(i=p->nSample-1; i>=0; i--){
82279     int j;
82280     for(j=iChng; j<p->nCol; j++){
82281       if( p->a[i].anEq[j]==0 ) p->a[i].anEq[j] = p->current.anEq[j];
82282     }
82283   }
82284 #endif
82285 
82286 #if defined(SQLITE_ENABLE_STAT3) && !defined(SQLITE_ENABLE_STAT4)
82287   if( iChng==0 ){
82288     tRowcnt nLt = p->current.anLt[0];
82289     tRowcnt nEq = p->current.anEq[0];
82290 
82291     /* Check if this is to be a periodic sample. If so, add it. */
82292     if( (nLt/p->nPSample)!=(nLt+nEq)/p->nPSample ){
82293       p->current.isPSample = 1;
82294       sampleInsert(p, &p->current, 0);
82295       p->current.isPSample = 0;
82296     }else 
82297 
82298     /* Or if it is a non-periodic sample. Add it in this case too. */
82299     if( p->nSample<p->mxSample 
82300      || sampleIsBetter(p, &p->current, &p->a[p->iMin]) 
82301     ){
82302       sampleInsert(p, &p->current, 0);
82303     }
82304   }
82305 #endif
82306 
82307 #ifndef SQLITE_ENABLE_STAT3_OR_STAT4
82308   UNUSED_PARAMETER( p );
82309   UNUSED_PARAMETER( iChng );
82310 #endif
82311 }
82312 
82313 /*
82314 ** Implementation of the stat_push SQL function:  stat_push(P,C,R)
82315 ** Arguments:
82316 **
82317 **    P     Pointer to the Stat4Accum object created by stat_init()
82318 **    C     Index of left-most column to differ from previous row
82319 **    R     Rowid for the current row.  Might be a key record for
82320 **          WITHOUT ROWID tables.
82321 **
82322 ** The SQL function always returns NULL.
82323 **
82324 ** The R parameter is only used for STAT3 and STAT4
82325 */
82326 static void statPush(
82327   sqlite3_context *context,
82328   int argc,
82329   sqlite3_value **argv
82330 ){
82331   int i;
82332 
82333   /* The three function arguments */
82334   Stat4Accum *p = (Stat4Accum*)sqlite3_value_blob(argv[0]);
82335   int iChng = sqlite3_value_int(argv[1]);
82336 
82337   UNUSED_PARAMETER( argc );
82338   UNUSED_PARAMETER( context );
82339   assert( p->nCol>1 );        /* Includes rowid field */
82340   assert( iChng<p->nCol );
82341 
82342   if( p->nRow==0 ){
82343     /* This is the first call to this function. Do initialization. */
82344     for(i=0; i<p->nCol; i++) p->current.anEq[i] = 1;
82345   }else{
82346     /* Second and subsequent calls get processed here */
82347     samplePushPrevious(p, iChng);
82348 
82349     /* Update anDLt[], anLt[] and anEq[] to reflect the values that apply
82350     ** to the current row of the index. */
82351     for(i=0; i<iChng; i++){
82352       p->current.anEq[i]++;
82353     }
82354     for(i=iChng; i<p->nCol; i++){
82355       p->current.anDLt[i]++;
82356 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
82357       p->current.anLt[i] += p->current.anEq[i];
82358 #endif
82359       p->current.anEq[i] = 1;
82360     }
82361   }
82362   p->nRow++;
82363 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
82364   if( sqlite3_value_type(argv[2])==SQLITE_INTEGER ){
82365     sampleSetRowidInt64(p->db, &p->current, sqlite3_value_int64(argv[2]));
82366   }else{
82367     sampleSetRowid(p->db, &p->current, sqlite3_value_bytes(argv[2]),
82368                                        sqlite3_value_blob(argv[2]));
82369   }
82370   p->current.iHash = p->iPrn = p->iPrn*1103515245 + 12345;
82371 #endif
82372 
82373 #ifdef SQLITE_ENABLE_STAT4
82374   {
82375     tRowcnt nLt = p->current.anLt[p->nCol-1];
82376 
82377     /* Check if this is to be a periodic sample. If so, add it. */
82378     if( (nLt/p->nPSample)!=(nLt+1)/p->nPSample ){
82379       p->current.isPSample = 1;
82380       p->current.iCol = 0;
82381       sampleInsert(p, &p->current, p->nCol-1);
82382       p->current.isPSample = 0;
82383     }
82384 
82385     /* Update the aBest[] array. */
82386     for(i=0; i<(p->nCol-1); i++){
82387       p->current.iCol = i;
82388       if( i>=iChng || sampleIsBetterPost(p, &p->current, &p->aBest[i]) ){
82389         sampleCopy(p, &p->aBest[i], &p->current);
82390       }
82391     }
82392   }
82393 #endif
82394 }
82395 static const FuncDef statPushFuncdef = {
82396   2+IsStat34,      /* nArg */
82397   SQLITE_UTF8,     /* funcFlags */
82398   0,               /* pUserData */
82399   0,               /* pNext */
82400   statPush,        /* xFunc */
82401   0,               /* xStep */
82402   0,               /* xFinalize */
82403   "stat_push",     /* zName */
82404   0,               /* pHash */
82405   0                /* pDestructor */
82406 };
82407 
82408 #define STAT_GET_STAT1 0          /* "stat" column of stat1 table */
82409 #define STAT_GET_ROWID 1          /* "rowid" column of stat[34] entry */
82410 #define STAT_GET_NEQ   2          /* "neq" column of stat[34] entry */
82411 #define STAT_GET_NLT   3          /* "nlt" column of stat[34] entry */
82412 #define STAT_GET_NDLT  4          /* "ndlt" column of stat[34] entry */
82413 
82414 /*
82415 ** Implementation of the stat_get(P,J) SQL function.  This routine is
82416 ** used to query the results.  Content is returned for parameter J
82417 ** which is one of the STAT_GET_xxxx values defined above.
82418 **
82419 ** If neither STAT3 nor STAT4 are enabled, then J is always
82420 ** STAT_GET_STAT1 and is hence omitted and this routine becomes
82421 ** a one-parameter function, stat_get(P), that always returns the
82422 ** stat1 table entry information.
82423 */
82424 static void statGet(
82425   sqlite3_context *context,
82426   int argc,
82427   sqlite3_value **argv
82428 ){
82429   Stat4Accum *p = (Stat4Accum*)sqlite3_value_blob(argv[0]);
82430 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
82431   /* STAT3 and STAT4 have a parameter on this routine. */
82432   int eCall = sqlite3_value_int(argv[1]);
82433   assert( argc==2 );
82434   assert( eCall==STAT_GET_STAT1 || eCall==STAT_GET_NEQ 
82435        || eCall==STAT_GET_ROWID || eCall==STAT_GET_NLT
82436        || eCall==STAT_GET_NDLT 
82437   );
82438   if( eCall==STAT_GET_STAT1 )
82439 #else
82440   assert( argc==1 );
82441 #endif
82442   {
82443     /* Return the value to store in the "stat" column of the sqlite_stat1
82444     ** table for this index.
82445     **
82446     ** The value is a string composed of a list of integers describing 
82447     ** the index. The first integer in the list is the total number of 
82448     ** entries in the index. There is one additional integer in the list 
82449     ** for each indexed column. This additional integer is an estimate of
82450     ** the number of rows matched by a stabbing query on the index using
82451     ** a key with the corresponding number of fields. In other words,
82452     ** if the index is on columns (a,b) and the sqlite_stat1 value is 
82453     ** "100 10 2", then SQLite estimates that:
82454     **
82455     **   * the index contains 100 rows,
82456     **   * "WHERE a=?" matches 10 rows, and
82457     **   * "WHERE a=? AND b=?" matches 2 rows.
82458     **
82459     ** If D is the count of distinct values and K is the total number of 
82460     ** rows, then each estimate is computed as:
82461     **
82462     **        I = (K+D-1)/D
82463     */
82464     char *z;
82465     int i;
82466 
82467     char *zRet = sqlite3MallocZero(p->nCol * 25);
82468     if( zRet==0 ){
82469       sqlite3_result_error_nomem(context);
82470       return;
82471     }
82472 
82473     sqlite3_snprintf(24, zRet, "%llu", (u64)p->nRow);
82474     z = zRet + sqlite3Strlen30(zRet);
82475     for(i=0; i<(p->nCol-1); i++){
82476       u64 nDistinct = p->current.anDLt[i] + 1;
82477       u64 iVal = (p->nRow + nDistinct - 1) / nDistinct;
82478       sqlite3_snprintf(24, z, " %llu", iVal);
82479       z += sqlite3Strlen30(z);
82480       assert( p->current.anEq[i] );
82481     }
82482     assert( z[0]=='\0' && z>zRet );
82483 
82484     sqlite3_result_text(context, zRet, -1, sqlite3_free);
82485   }
82486 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
82487   else if( eCall==STAT_GET_ROWID ){
82488     if( p->iGet<0 ){
82489       samplePushPrevious(p, 0);
82490       p->iGet = 0;
82491     }
82492     if( p->iGet<p->nSample ){
82493       Stat4Sample *pS = p->a + p->iGet;
82494       if( pS->nRowid==0 ){
82495         sqlite3_result_int64(context, pS->u.iRowid);
82496       }else{
82497         sqlite3_result_blob(context, pS->u.aRowid, pS->nRowid,
82498                             SQLITE_TRANSIENT);
82499       }
82500     }
82501   }else{
82502     tRowcnt *aCnt = 0;
82503 
82504     assert( p->iGet<p->nSample );
82505     switch( eCall ){
82506       case STAT_GET_NEQ:  aCnt = p->a[p->iGet].anEq; break;
82507       case STAT_GET_NLT:  aCnt = p->a[p->iGet].anLt; break;
82508       default: {
82509         aCnt = p->a[p->iGet].anDLt; 
82510         p->iGet++;
82511         break;
82512       }
82513     }
82514 
82515     if( IsStat3 ){
82516       sqlite3_result_int64(context, (i64)aCnt[0]);
82517     }else{
82518       char *zRet = sqlite3MallocZero(p->nCol * 25);
82519       if( zRet==0 ){
82520         sqlite3_result_error_nomem(context);
82521       }else{
82522         int i;
82523         char *z = zRet;
82524         for(i=0; i<p->nCol; i++){
82525           sqlite3_snprintf(24, z, "%llu ", (u64)aCnt[i]);
82526           z += sqlite3Strlen30(z);
82527         }
82528         assert( z[0]=='\0' && z>zRet );
82529         z[-1] = '\0';
82530         sqlite3_result_text(context, zRet, -1, sqlite3_free);
82531       }
82532     }
82533   }
82534 #endif /* SQLITE_ENABLE_STAT3_OR_STAT4 */
82535 #ifndef SQLITE_DEBUG
82536   UNUSED_PARAMETER( argc );
82537 #endif
82538 }
82539 static const FuncDef statGetFuncdef = {
82540   1+IsStat34,      /* nArg */
82541   SQLITE_UTF8,     /* funcFlags */
82542   0,               /* pUserData */
82543   0,               /* pNext */
82544   statGet,         /* xFunc */
82545   0,               /* xStep */
82546   0,               /* xFinalize */
82547   "stat_get",      /* zName */
82548   0,               /* pHash */
82549   0                /* pDestructor */
82550 };
82551 
82552 static void callStatGet(Vdbe *v, int regStat4, int iParam, int regOut){
82553   assert( regOut!=regStat4 && regOut!=regStat4+1 );
82554 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
82555   sqlite3VdbeAddOp2(v, OP_Integer, iParam, regStat4+1);
82556 #elif SQLITE_DEBUG
82557   assert( iParam==STAT_GET_STAT1 );
82558 #else
82559   UNUSED_PARAMETER( iParam );
82560 #endif
82561   sqlite3VdbeAddOp3(v, OP_Function, 0, regStat4, regOut);
82562   sqlite3VdbeChangeP4(v, -1, (char*)&statGetFuncdef, P4_FUNCDEF);
82563   sqlite3VdbeChangeP5(v, 1 + IsStat34);
82564 }
82565 
82566 /*
82567 ** Generate code to do an analysis of all indices associated with
82568 ** a single table.
82569 */
82570 static void analyzeOneTable(
82571   Parse *pParse,   /* Parser context */
82572   Table *pTab,     /* Table whose indices are to be analyzed */
82573   Index *pOnlyIdx, /* If not NULL, only analyze this one index */
82574   int iStatCur,    /* Index of VdbeCursor that writes the sqlite_stat1 table */
82575   int iMem,        /* Available memory locations begin here */
82576   int iTab         /* Next available cursor */
82577 ){
82578   sqlite3 *db = pParse->db;    /* Database handle */
82579   Index *pIdx;                 /* An index to being analyzed */
82580   int iIdxCur;                 /* Cursor open on index being analyzed */
82581   int iTabCur;                 /* Table cursor */
82582   Vdbe *v;                     /* The virtual machine being built up */
82583   int i;                       /* Loop counter */
82584   int jZeroRows = -1;          /* Jump from here if number of rows is zero */
82585   int iDb;                     /* Index of database containing pTab */
82586   u8 needTableCnt = 1;         /* True to count the table */
82587   int regNewRowid = iMem++;    /* Rowid for the inserted record */
82588   int regStat4 = iMem++;       /* Register to hold Stat4Accum object */
82589   int regChng = iMem++;        /* Index of changed index field */
82590 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
82591   int regRowid = iMem++;       /* Rowid argument passed to stat_push() */
82592 #endif
82593   int regTemp = iMem++;        /* Temporary use register */
82594   int regTabname = iMem++;     /* Register containing table name */
82595   int regIdxname = iMem++;     /* Register containing index name */
82596   int regStat1 = iMem++;       /* Value for the stat column of sqlite_stat1 */
82597   int regPrev = iMem;          /* MUST BE LAST (see below) */
82598 
82599   pParse->nMem = MAX(pParse->nMem, iMem);
82600   v = sqlite3GetVdbe(pParse);
82601   if( v==0 || NEVER(pTab==0) ){
82602     return;
82603   }
82604   if( pTab->tnum==0 ){
82605     /* Do not gather statistics on views or virtual tables */
82606     return;
82607   }
82608   if( sqlite3_strnicmp(pTab->zName, "sqlite_", 7)==0 ){
82609     /* Do not gather statistics on system tables */
82610     return;
82611   }
82612   assert( sqlite3BtreeHoldsAllMutexes(db) );
82613   iDb = sqlite3SchemaToIndex(db, pTab->pSchema);
82614   assert( iDb>=0 );
82615   assert( sqlite3SchemaMutexHeld(db, iDb, 0) );
82616 #ifndef SQLITE_OMIT_AUTHORIZATION
82617   if( sqlite3AuthCheck(pParse, SQLITE_ANALYZE, pTab->zName, 0,
82618       db->aDb[iDb].zName ) ){
82619     return;
82620   }
82621 #endif
82622 
82623   /* Establish a read-lock on the table at the shared-cache level. 
82624   ** Open a read-only cursor on the table. Also allocate a cursor number
82625   ** to use for scanning indexes (iIdxCur). No index cursor is opened at
82626   ** this time though.  */
82627   sqlite3TableLock(pParse, iDb, pTab->tnum, 0, pTab->zName);
82628   iTabCur = iTab++;
82629   iIdxCur = iTab++;
82630   pParse->nTab = MAX(pParse->nTab, iTab);
82631   sqlite3OpenTable(pParse, iTabCur, iDb, pTab, OP_OpenRead);
82632   sqlite3VdbeAddOp4(v, OP_String8, 0, regTabname, 0, pTab->zName, 0);
82633 
82634   for(pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext){
82635     int nCol;                     /* Number of columns indexed by pIdx */
82636     int *aGotoChng;               /* Array of jump instruction addresses */
82637     int addrRewind;               /* Address of "OP_Rewind iIdxCur" */
82638     int addrGotoChng0;            /* Address of "Goto addr_chng_0" */
82639     int addrNextRow;              /* Address of "next_row:" */
82640     const char *zIdxName;         /* Name of the index */
82641 
82642     if( pOnlyIdx && pOnlyIdx!=pIdx ) continue;
82643     if( pIdx->pPartIdxWhere==0 ) needTableCnt = 0;
82644     VdbeNoopComment((v, "Begin analysis of %s", pIdx->zName));
82645     nCol = pIdx->nKeyCol;
82646     aGotoChng = sqlite3DbMallocRaw(db, sizeof(int)*(nCol+1));
82647     if( aGotoChng==0 ) continue;
82648 
82649     /* Populate the register containing the index name. */
82650     if( pIdx->autoIndex==2 && !HasRowid(pTab) ){
82651       zIdxName = pTab->zName;
82652     }else{
82653       zIdxName = pIdx->zName;
82654     }
82655     sqlite3VdbeAddOp4(v, OP_String8, 0, regIdxname, 0, zIdxName, 0);
82656 
82657     /*
82658     ** Pseudo-code for loop that calls stat_push():
82659     **
82660     **   Rewind csr
82661     **   if eof(csr) goto end_of_scan;
82662     **   regChng = 0
82663     **   goto chng_addr_0;
82664     **
82665     **  next_row:
82666     **   regChng = 0
82667     **   if( idx(0) != regPrev(0) ) goto chng_addr_0
82668     **   regChng = 1
82669     **   if( idx(1) != regPrev(1) ) goto chng_addr_1
82670     **   ...
82671     **   regChng = N
82672     **   goto chng_addr_N
82673     **
82674     **  chng_addr_0:
82675     **   regPrev(0) = idx(0)
82676     **  chng_addr_1:
82677     **   regPrev(1) = idx(1)
82678     **  ...
82679     **
82680     **  chng_addr_N:
82681     **   regRowid = idx(rowid)
82682     **   stat_push(P, regChng, regRowid)
82683     **   Next csr
82684     **   if !eof(csr) goto next_row;
82685     **
82686     **  end_of_scan:
82687     */
82688 
82689     /* Make sure there are enough memory cells allocated to accommodate 
82690     ** the regPrev array and a trailing rowid (the rowid slot is required
82691     ** when building a record to insert into the sample column of 
82692     ** the sqlite_stat4 table.  */
82693     pParse->nMem = MAX(pParse->nMem, regPrev+nCol);
82694 
82695     /* Open a read-only cursor on the index being analyzed. */
82696     assert( iDb==sqlite3SchemaToIndex(db, pIdx->pSchema) );
82697     sqlite3VdbeAddOp3(v, OP_OpenRead, iIdxCur, pIdx->tnum, iDb);
82698     sqlite3VdbeSetP4KeyInfo(pParse, pIdx);
82699     VdbeComment((v, "%s", pIdx->zName));
82700 
82701     /* Invoke the stat_init() function. The arguments are:
82702     ** 
82703     **    (1) the number of columns in the index including the rowid,
82704     **    (2) the number of rows in the index,
82705     **
82706     ** The second argument is only used for STAT3 and STAT4
82707     */
82708 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
82709     sqlite3VdbeAddOp2(v, OP_Count, iIdxCur, regStat4+2);
82710 #endif
82711     sqlite3VdbeAddOp2(v, OP_Integer, nCol+1, regStat4+1);
82712     sqlite3VdbeAddOp3(v, OP_Function, 0, regStat4+1, regStat4);
82713     sqlite3VdbeChangeP4(v, -1, (char*)&statInitFuncdef, P4_FUNCDEF);
82714     sqlite3VdbeChangeP5(v, 1+IsStat34);
82715 
82716     /* Implementation of the following:
82717     **
82718     **   Rewind csr
82719     **   if eof(csr) goto end_of_scan;
82720     **   regChng = 0
82721     **   goto next_push_0;
82722     **
82723     */
82724     addrRewind = sqlite3VdbeAddOp1(v, OP_Rewind, iIdxCur);
82725     sqlite3VdbeAddOp2(v, OP_Integer, 0, regChng);
82726     addrGotoChng0 = sqlite3VdbeAddOp0(v, OP_Goto);
82727 
82728     /*
82729     **  next_row:
82730     **   regChng = 0
82731     **   if( idx(0) != regPrev(0) ) goto chng_addr_0
82732     **   regChng = 1
82733     **   if( idx(1) != regPrev(1) ) goto chng_addr_1
82734     **   ...
82735     **   regChng = N
82736     **   goto chng_addr_N
82737     */
82738     addrNextRow = sqlite3VdbeCurrentAddr(v);
82739     for(i=0; i<nCol; i++){
82740       char *pColl = (char*)sqlite3LocateCollSeq(pParse, pIdx->azColl[i]);
82741       sqlite3VdbeAddOp2(v, OP_Integer, i, regChng);
82742       sqlite3VdbeAddOp3(v, OP_Column, iIdxCur, i, regTemp);
82743       aGotoChng[i] = 
82744       sqlite3VdbeAddOp4(v, OP_Ne, regTemp, 0, regPrev+i, pColl, P4_COLLSEQ);
82745       sqlite3VdbeChangeP5(v, SQLITE_NULLEQ);
82746     }
82747     sqlite3VdbeAddOp2(v, OP_Integer, nCol, regChng);
82748     aGotoChng[nCol] = sqlite3VdbeAddOp0(v, OP_Goto);
82749 
82750     /*
82751     **  chng_addr_0:
82752     **   regPrev(0) = idx(0)
82753     **  chng_addr_1:
82754     **   regPrev(1) = idx(1)
82755     **  ...
82756     */
82757     sqlite3VdbeJumpHere(v, addrGotoChng0);
82758     for(i=0; i<nCol; i++){
82759       sqlite3VdbeJumpHere(v, aGotoChng[i]);
82760       sqlite3VdbeAddOp3(v, OP_Column, iIdxCur, i, regPrev+i);
82761     }
82762 
82763     /*
82764     **  chng_addr_N:
82765     **   regRowid = idx(rowid)            // STAT34 only
82766     **   stat_push(P, regChng, regRowid)  // 3rd parameter STAT34 only
82767     **   Next csr
82768     **   if !eof(csr) goto next_row;
82769     */
82770     sqlite3VdbeJumpHere(v, aGotoChng[nCol]);
82771 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
82772     assert( regRowid==(regStat4+2) );
82773     if( HasRowid(pTab) ){
82774       sqlite3VdbeAddOp2(v, OP_IdxRowid, iIdxCur, regRowid);
82775     }else{
82776       Index *pPk = sqlite3PrimaryKeyIndex(pIdx->pTable);
82777       int j, k, regKey;
82778       regKey = sqlite3GetTempRange(pParse, pPk->nKeyCol);
82779       for(j=0; j<pPk->nKeyCol; j++){
82780         k = sqlite3ColumnOfIndex(pIdx, pPk->aiColumn[j]);
82781         sqlite3VdbeAddOp3(v, OP_Column, iIdxCur, k, regKey+j);
82782         VdbeComment((v, "%s", pTab->aCol[pPk->aiColumn[j]].zName));
82783       }
82784       sqlite3VdbeAddOp3(v, OP_MakeRecord, regKey, pPk->nKeyCol, regRowid);
82785       sqlite3ReleaseTempRange(pParse, regKey, pPk->nKeyCol);
82786     }
82787 #endif
82788     assert( regChng==(regStat4+1) );
82789     sqlite3VdbeAddOp3(v, OP_Function, 1, regStat4, regTemp);
82790     sqlite3VdbeChangeP4(v, -1, (char*)&statPushFuncdef, P4_FUNCDEF);
82791     sqlite3VdbeChangeP5(v, 2+IsStat34);
82792     sqlite3VdbeAddOp2(v, OP_Next, iIdxCur, addrNextRow);
82793 
82794     /* Add the entry to the stat1 table. */
82795     callStatGet(v, regStat4, STAT_GET_STAT1, regStat1);
82796     sqlite3VdbeAddOp4(v, OP_MakeRecord, regTabname, 3, regTemp, "aaa", 0);
82797     sqlite3VdbeAddOp2(v, OP_NewRowid, iStatCur, regNewRowid);
82798     sqlite3VdbeAddOp3(v, OP_Insert, iStatCur, regTemp, regNewRowid);
82799     sqlite3VdbeChangeP5(v, OPFLAG_APPEND);
82800 
82801     /* Add the entries to the stat3 or stat4 table. */
82802 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
82803     {
82804       int regEq = regStat1;
82805       int regLt = regStat1+1;
82806       int regDLt = regStat1+2;
82807       int regSample = regStat1+3;
82808       int regCol = regStat1+4;
82809       int regSampleRowid = regCol + nCol;
82810       int addrNext;
82811       int addrIsNull;
82812       u8 seekOp = HasRowid(pTab) ? OP_NotExists : OP_NotFound;
82813 
82814       pParse->nMem = MAX(pParse->nMem, regCol+nCol+1);
82815 
82816       addrNext = sqlite3VdbeCurrentAddr(v);
82817       callStatGet(v, regStat4, STAT_GET_ROWID, regSampleRowid);
82818       addrIsNull = sqlite3VdbeAddOp1(v, OP_IsNull, regSampleRowid);
82819       callStatGet(v, regStat4, STAT_GET_NEQ, regEq);
82820       callStatGet(v, regStat4, STAT_GET_NLT, regLt);
82821       callStatGet(v, regStat4, STAT_GET_NDLT, regDLt);
82822       sqlite3VdbeAddOp4Int(v, seekOp, iTabCur, addrNext, regSampleRowid, 0);
82823 #ifdef SQLITE_ENABLE_STAT3
82824       sqlite3ExprCodeGetColumnOfTable(v, pTab, iTabCur, 
82825                                       pIdx->aiColumn[0], regSample);
82826 #else
82827       for(i=0; i<nCol; i++){
82828         i16 iCol = pIdx->aiColumn[i];
82829         sqlite3ExprCodeGetColumnOfTable(v, pTab, iTabCur, iCol, regCol+i);
82830       }
82831       sqlite3VdbeAddOp3(v, OP_MakeRecord, regCol, nCol+1, regSample);
82832 #endif
82833       sqlite3VdbeAddOp4(v, OP_MakeRecord, regTabname, 6, regTemp, "bbbbbb", 0);
82834       sqlite3VdbeAddOp2(v, OP_NewRowid, iStatCur+1, regNewRowid);
82835       sqlite3VdbeAddOp3(v, OP_Insert, iStatCur+1, regTemp, regNewRowid);
82836       sqlite3VdbeAddOp2(v, OP_Goto, 0, addrNext);
82837       sqlite3VdbeJumpHere(v, addrIsNull);
82838     }
82839 #endif /* SQLITE_ENABLE_STAT3_OR_STAT4 */
82840 
82841     /* End of analysis */
82842     sqlite3VdbeJumpHere(v, addrRewind);
82843     sqlite3DbFree(db, aGotoChng);
82844   }
82845 
82846 
82847   /* Create a single sqlite_stat1 entry containing NULL as the index
82848   ** name and the row count as the content.
82849   */
82850   if( pOnlyIdx==0 && needTableCnt ){
82851     VdbeComment((v, "%s", pTab->zName));
82852     sqlite3VdbeAddOp2(v, OP_Count, iTabCur, regStat1);
82853     jZeroRows = sqlite3VdbeAddOp1(v, OP_IfNot, regStat1);
82854     sqlite3VdbeAddOp2(v, OP_Null, 0, regIdxname);
82855     sqlite3VdbeAddOp4(v, OP_MakeRecord, regTabname, 3, regTemp, "aaa", 0);
82856     sqlite3VdbeAddOp2(v, OP_NewRowid, iStatCur, regNewRowid);
82857     sqlite3VdbeAddOp3(v, OP_Insert, iStatCur, regTemp, regNewRowid);
82858     sqlite3VdbeChangeP5(v, OPFLAG_APPEND);
82859     sqlite3VdbeJumpHere(v, jZeroRows);
82860   }
82861 }
82862 
82863 
82864 /*
82865 ** Generate code that will cause the most recent index analysis to
82866 ** be loaded into internal hash tables where is can be used.
82867 */
82868 static void loadAnalysis(Parse *pParse, int iDb){
82869   Vdbe *v = sqlite3GetVdbe(pParse);
82870   if( v ){
82871     sqlite3VdbeAddOp1(v, OP_LoadAnalysis, iDb);
82872   }
82873 }
82874 
82875 /*
82876 ** Generate code that will do an analysis of an entire database
82877 */
82878 static void analyzeDatabase(Parse *pParse, int iDb){
82879   sqlite3 *db = pParse->db;
82880   Schema *pSchema = db->aDb[iDb].pSchema;    /* Schema of database iDb */
82881   HashElem *k;
82882   int iStatCur;
82883   int iMem;
82884   int iTab;
82885 
82886   sqlite3BeginWriteOperation(pParse, 0, iDb);
82887   iStatCur = pParse->nTab;
82888   pParse->nTab += 3;
82889   openStatTable(pParse, iDb, iStatCur, 0, 0);
82890   iMem = pParse->nMem+1;
82891   iTab = pParse->nTab;
82892   assert( sqlite3SchemaMutexHeld(db, iDb, 0) );
82893   for(k=sqliteHashFirst(&pSchema->tblHash); k; k=sqliteHashNext(k)){
82894     Table *pTab = (Table*)sqliteHashData(k);
82895     analyzeOneTable(pParse, pTab, 0, iStatCur, iMem, iTab);
82896   }
82897   loadAnalysis(pParse, iDb);
82898 }
82899 
82900 /*
82901 ** Generate code that will do an analysis of a single table in
82902 ** a database.  If pOnlyIdx is not NULL then it is a single index
82903 ** in pTab that should be analyzed.
82904 */
82905 static void analyzeTable(Parse *pParse, Table *pTab, Index *pOnlyIdx){
82906   int iDb;
82907   int iStatCur;
82908 
82909   assert( pTab!=0 );
82910   assert( sqlite3BtreeHoldsAllMutexes(pParse->db) );
82911   iDb = sqlite3SchemaToIndex(pParse->db, pTab->pSchema);
82912   sqlite3BeginWriteOperation(pParse, 0, iDb);
82913   iStatCur = pParse->nTab;
82914   pParse->nTab += 3;
82915   if( pOnlyIdx ){
82916     openStatTable(pParse, iDb, iStatCur, pOnlyIdx->zName, "idx");
82917   }else{
82918     openStatTable(pParse, iDb, iStatCur, pTab->zName, "tbl");
82919   }
82920   analyzeOneTable(pParse, pTab, pOnlyIdx, iStatCur,pParse->nMem+1,pParse->nTab);
82921   loadAnalysis(pParse, iDb);
82922 }
82923 
82924 /*
82925 ** Generate code for the ANALYZE command.  The parser calls this routine
82926 ** when it recognizes an ANALYZE command.
82927 **
82928 **        ANALYZE                            -- 1
82929 **        ANALYZE  <database>                -- 2
82930 **        ANALYZE  ?<database>.?<tablename>  -- 3
82931 **
82932 ** Form 1 causes all indices in all attached databases to be analyzed.
82933 ** Form 2 analyzes all indices the single database named.
82934 ** Form 3 analyzes all indices associated with the named table.
82935 */
82936 SQLITE_PRIVATE void sqlite3Analyze(Parse *pParse, Token *pName1, Token *pName2){
82937   sqlite3 *db = pParse->db;
82938   int iDb;
82939   int i;
82940   char *z, *zDb;
82941   Table *pTab;
82942   Index *pIdx;
82943   Token *pTableName;
82944 
82945   /* Read the database schema. If an error occurs, leave an error message
82946   ** and code in pParse and return NULL. */
82947   assert( sqlite3BtreeHoldsAllMutexes(pParse->db) );
82948   if( SQLITE_OK!=sqlite3ReadSchema(pParse) ){
82949     return;
82950   }
82951 
82952   assert( pName2!=0 || pName1==0 );
82953   if( pName1==0 ){
82954     /* Form 1:  Analyze everything */
82955     for(i=0; i<db->nDb; i++){
82956       if( i==1 ) continue;  /* Do not analyze the TEMP database */
82957       analyzeDatabase(pParse, i);
82958     }
82959   }else if( pName2->n==0 ){
82960     /* Form 2:  Analyze the database or table named */
82961     iDb = sqlite3FindDb(db, pName1);
82962     if( iDb>=0 ){
82963       analyzeDatabase(pParse, iDb);
82964     }else{
82965       z = sqlite3NameFromToken(db, pName1);
82966       if( z ){
82967         if( (pIdx = sqlite3FindIndex(db, z, 0))!=0 ){
82968           analyzeTable(pParse, pIdx->pTable, pIdx);
82969         }else if( (pTab = sqlite3LocateTable(pParse, 0, z, 0))!=0 ){
82970           analyzeTable(pParse, pTab, 0);
82971         }
82972         sqlite3DbFree(db, z);
82973       }
82974     }
82975   }else{
82976     /* Form 3: Analyze the fully qualified table name */
82977     iDb = sqlite3TwoPartName(pParse, pName1, pName2, &pTableName);
82978     if( iDb>=0 ){
82979       zDb = db->aDb[iDb].zName;
82980       z = sqlite3NameFromToken(db, pTableName);
82981       if( z ){
82982         if( (pIdx = sqlite3FindIndex(db, z, zDb))!=0 ){
82983           analyzeTable(pParse, pIdx->pTable, pIdx);
82984         }else if( (pTab = sqlite3LocateTable(pParse, 0, z, zDb))!=0 ){
82985           analyzeTable(pParse, pTab, 0);
82986         }
82987         sqlite3DbFree(db, z);
82988       }
82989     }   
82990   }
82991 }
82992 
82993 /*
82994 ** Used to pass information from the analyzer reader through to the
82995 ** callback routine.
82996 */
82997 typedef struct analysisInfo analysisInfo;
82998 struct analysisInfo {
82999   sqlite3 *db;
83000   const char *zDatabase;
83001 };
83002 
83003 /*
83004 ** The first argument points to a nul-terminated string containing a
83005 ** list of space separated integers. Read the first nOut of these into
83006 ** the array aOut[].
83007 */
83008 static void decodeIntArray(
83009   char *zIntArray,       /* String containing int array to decode */
83010   int nOut,              /* Number of slots in aOut[] */
83011   tRowcnt *aOut,         /* Store integers here */
83012   Index *pIndex          /* Handle extra flags for this index, if not NULL */
83013 ){
83014   char *z = zIntArray;
83015   int c;
83016   int i;
83017   tRowcnt v;
83018 
83019 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
83020   if( z==0 ) z = "";
83021 #else
83022   if( NEVER(z==0) ) z = "";
83023 #endif
83024   for(i=0; *z && i<nOut; i++){
83025     v = 0;
83026     while( (c=z[0])>='0' && c<='9' ){
83027       v = v*10 + c - '0';
83028       z++;
83029     }
83030     aOut[i] = v;
83031     if( *z==' ' ) z++;
83032   }
83033 #ifndef SQLITE_ENABLE_STAT3_OR_STAT4
83034   assert( pIndex!=0 );
83035 #else
83036   if( pIndex )
83037 #endif
83038   {
83039     if( strcmp(z, "unordered")==0 ){
83040       pIndex->bUnordered = 1;
83041     }else if( sqlite3_strglob("sz=[0-9]*", z)==0 ){
83042       int v32 = 0;
83043       sqlite3GetInt32(z+3, &v32);
83044       pIndex->szIdxRow = sqlite3LogEst(v32);
83045     }
83046   }
83047 }
83048 
83049 /*
83050 ** This callback is invoked once for each index when reading the
83051 ** sqlite_stat1 table.  
83052 **
83053 **     argv[0] = name of the table
83054 **     argv[1] = name of the index (might be NULL)
83055 **     argv[2] = results of analysis - on integer for each column
83056 **
83057 ** Entries for which argv[1]==NULL simply record the number of rows in
83058 ** the table.
83059 */
83060 static int analysisLoader(void *pData, int argc, char **argv, char **NotUsed){
83061   analysisInfo *pInfo = (analysisInfo*)pData;
83062   Index *pIndex;
83063   Table *pTable;
83064   const char *z;
83065 
83066   assert( argc==3 );
83067   UNUSED_PARAMETER2(NotUsed, argc);
83068 
83069   if( argv==0 || argv[0]==0 || argv[2]==0 ){
83070     return 0;
83071   }
83072   pTable = sqlite3FindTable(pInfo->db, argv[0], pInfo->zDatabase);
83073   if( pTable==0 ){
83074     return 0;
83075   }
83076   if( argv[1]==0 ){
83077     pIndex = 0;
83078   }else if( sqlite3_stricmp(argv[0],argv[1])==0 ){
83079     pIndex = sqlite3PrimaryKeyIndex(pTable);
83080   }else{
83081     pIndex = sqlite3FindIndex(pInfo->db, argv[1], pInfo->zDatabase);
83082   }
83083   z = argv[2];
83084 
83085   if( pIndex ){
83086     decodeIntArray((char*)z, pIndex->nKeyCol+1, pIndex->aiRowEst, pIndex);
83087     if( pIndex->pPartIdxWhere==0 ) pTable->nRowEst = pIndex->aiRowEst[0];
83088   }else{
83089     Index fakeIdx;
83090     fakeIdx.szIdxRow = pTable->szTabRow;
83091     decodeIntArray((char*)z, 1, &pTable->nRowEst, &fakeIdx);
83092     pTable->szTabRow = fakeIdx.szIdxRow;
83093   }
83094 
83095   return 0;
83096 }
83097 
83098 /*
83099 ** If the Index.aSample variable is not NULL, delete the aSample[] array
83100 ** and its contents.
83101 */
83102 SQLITE_PRIVATE void sqlite3DeleteIndexSamples(sqlite3 *db, Index *pIdx){
83103 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
83104   if( pIdx->aSample ){
83105     int j;
83106     for(j=0; j<pIdx->nSample; j++){
83107       IndexSample *p = &pIdx->aSample[j];
83108       sqlite3DbFree(db, p->p);
83109     }
83110     sqlite3DbFree(db, pIdx->aSample);
83111   }
83112   if( db && db->pnBytesFreed==0 ){
83113     pIdx->nSample = 0;
83114     pIdx->aSample = 0;
83115   }
83116 #else
83117   UNUSED_PARAMETER(db);
83118   UNUSED_PARAMETER(pIdx);
83119 #endif /* SQLITE_ENABLE_STAT3_OR_STAT4 */
83120 }
83121 
83122 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
83123 /*
83124 ** Populate the pIdx->aAvgEq[] array based on the samples currently
83125 ** stored in pIdx->aSample[]. 
83126 */
83127 static void initAvgEq(Index *pIdx){
83128   if( pIdx ){
83129     IndexSample *aSample = pIdx->aSample;
83130     IndexSample *pFinal = &aSample[pIdx->nSample-1];
83131     int iCol;
83132     for(iCol=0; iCol<pIdx->nKeyCol; iCol++){
83133       int i;                    /* Used to iterate through samples */
83134       tRowcnt sumEq = 0;        /* Sum of the nEq values */
83135       tRowcnt nSum = 0;         /* Number of terms contributing to sumEq */
83136       tRowcnt avgEq = 0;
83137       tRowcnt nDLt = pFinal->anDLt[iCol];
83138 
83139       /* Set nSum to the number of distinct (iCol+1) field prefixes that
83140       ** occur in the stat4 table for this index before pFinal. Set
83141       ** sumEq to the sum of the nEq values for column iCol for the same
83142       ** set (adding the value only once where there exist dupicate 
83143       ** prefixes).  */
83144       for(i=0; i<(pIdx->nSample-1); i++){
83145         if( aSample[i].anDLt[iCol]!=aSample[i+1].anDLt[iCol] ){
83146           sumEq += aSample[i].anEq[iCol];
83147           nSum++;
83148         }
83149       }
83150       if( nDLt>nSum ){
83151         avgEq = (pFinal->anLt[iCol] - sumEq)/(nDLt - nSum);
83152       }
83153       if( avgEq==0 ) avgEq = 1;
83154       pIdx->aAvgEq[iCol] = avgEq;
83155       if( pIdx->nSampleCol==1 ) break;
83156     }
83157   }
83158 }
83159 
83160 /*
83161 ** Look up an index by name.  Or, if the name of a WITHOUT ROWID table
83162 ** is supplied instead, find the PRIMARY KEY index for that table.
83163 */
83164 static Index *findIndexOrPrimaryKey(
83165   sqlite3 *db,
83166   const char *zName,
83167   const char *zDb
83168 ){
83169   Index *pIdx = sqlite3FindIndex(db, zName, zDb);
83170   if( pIdx==0 ){
83171     Table *pTab = sqlite3FindTable(db, zName, zDb);
83172     if( pTab && !HasRowid(pTab) ) pIdx = sqlite3PrimaryKeyIndex(pTab);
83173   }
83174   return pIdx;
83175 }
83176 
83177 /*
83178 ** Load the content from either the sqlite_stat4 or sqlite_stat3 table 
83179 ** into the relevant Index.aSample[] arrays.
83180 **
83181 ** Arguments zSql1 and zSql2 must point to SQL statements that return
83182 ** data equivalent to the following (statements are different for stat3,
83183 ** see the caller of this function for details):
83184 **
83185 **    zSql1: SELECT idx,count(*) FROM %Q.sqlite_stat4 GROUP BY idx
83186 **    zSql2: SELECT idx,neq,nlt,ndlt,sample FROM %Q.sqlite_stat4
83187 **
83188 ** where %Q is replaced with the database name before the SQL is executed.
83189 */
83190 static int loadStatTbl(
83191   sqlite3 *db,                  /* Database handle */
83192   int bStat3,                   /* Assume single column records only */
83193   const char *zSql1,            /* SQL statement 1 (see above) */
83194   const char *zSql2,            /* SQL statement 2 (see above) */
83195   const char *zDb               /* Database name (e.g. "main") */
83196 ){
83197   int rc;                       /* Result codes from subroutines */
83198   sqlite3_stmt *pStmt = 0;      /* An SQL statement being run */
83199   char *zSql;                   /* Text of the SQL statement */
83200   Index *pPrevIdx = 0;          /* Previous index in the loop */
83201   IndexSample *pSample;         /* A slot in pIdx->aSample[] */
83202 
83203   assert( db->lookaside.bEnabled==0 );
83204   zSql = sqlite3MPrintf(db, zSql1, zDb);
83205   if( !zSql ){
83206     return SQLITE_NOMEM;
83207   }
83208   rc = sqlite3_prepare(db, zSql, -1, &pStmt, 0);
83209   sqlite3DbFree(db, zSql);
83210   if( rc ) return rc;
83211 
83212   while( sqlite3_step(pStmt)==SQLITE_ROW ){
83213     int nIdxCol = 1;              /* Number of columns in stat4 records */
83214     int nAvgCol = 1;              /* Number of entries in Index.aAvgEq */
83215 
83216     char *zIndex;   /* Index name */
83217     Index *pIdx;    /* Pointer to the index object */
83218     int nSample;    /* Number of samples */
83219     int nByte;      /* Bytes of space required */
83220     int i;          /* Bytes of space required */
83221     tRowcnt *pSpace;
83222 
83223     zIndex = (char *)sqlite3_column_text(pStmt, 0);
83224     if( zIndex==0 ) continue;
83225     nSample = sqlite3_column_int(pStmt, 1);
83226     pIdx = findIndexOrPrimaryKey(db, zIndex, zDb);
83227     assert( pIdx==0 || bStat3 || pIdx->nSample==0 );
83228     /* Index.nSample is non-zero at this point if data has already been
83229     ** loaded from the stat4 table. In this case ignore stat3 data.  */
83230     if( pIdx==0 || pIdx->nSample ) continue;
83231     if( bStat3==0 ){
83232       nIdxCol = pIdx->nKeyCol+1;
83233       nAvgCol = pIdx->nKeyCol;
83234     }
83235     pIdx->nSampleCol = nIdxCol;
83236     nByte = sizeof(IndexSample) * nSample;
83237     nByte += sizeof(tRowcnt) * nIdxCol * 3 * nSample;
83238     nByte += nAvgCol * sizeof(tRowcnt);     /* Space for Index.aAvgEq[] */
83239 
83240     pIdx->aSample = sqlite3DbMallocZero(db, nByte);
83241     if( pIdx->aSample==0 ){
83242       sqlite3_finalize(pStmt);
83243       return SQLITE_NOMEM;
83244     }
83245     pSpace = (tRowcnt*)&pIdx->aSample[nSample];
83246     pIdx->aAvgEq = pSpace; pSpace += nAvgCol;
83247     for(i=0; i<nSample; i++){
83248       pIdx->aSample[i].anEq = pSpace; pSpace += nIdxCol;
83249       pIdx->aSample[i].anLt = pSpace; pSpace += nIdxCol;
83250       pIdx->aSample[i].anDLt = pSpace; pSpace += nIdxCol;
83251     }
83252     assert( ((u8*)pSpace)-nByte==(u8*)(pIdx->aSample) );
83253   }
83254   rc = sqlite3_finalize(pStmt);
83255   if( rc ) return rc;
83256 
83257   zSql = sqlite3MPrintf(db, zSql2, zDb);
83258   if( !zSql ){
83259     return SQLITE_NOMEM;
83260   }
83261   rc = sqlite3_prepare(db, zSql, -1, &pStmt, 0);
83262   sqlite3DbFree(db, zSql);
83263   if( rc ) return rc;
83264 
83265   while( sqlite3_step(pStmt)==SQLITE_ROW ){
83266     char *zIndex;                 /* Index name */
83267     Index *pIdx;                  /* Pointer to the index object */
83268     int nCol = 1;                 /* Number of columns in index */
83269 
83270     zIndex = (char *)sqlite3_column_text(pStmt, 0);
83271     if( zIndex==0 ) continue;
83272     pIdx = findIndexOrPrimaryKey(db, zIndex, zDb);
83273     if( pIdx==0 ) continue;
83274     /* This next condition is true if data has already been loaded from 
83275     ** the sqlite_stat4 table. In this case ignore stat3 data.  */
83276     nCol = pIdx->nSampleCol;
83277     if( bStat3 && nCol>1 ) continue;
83278     if( pIdx!=pPrevIdx ){
83279       initAvgEq(pPrevIdx);
83280       pPrevIdx = pIdx;
83281     }
83282     pSample = &pIdx->aSample[pIdx->nSample];
83283     decodeIntArray((char*)sqlite3_column_text(pStmt,1), nCol, pSample->anEq, 0);
83284     decodeIntArray((char*)sqlite3_column_text(pStmt,2), nCol, pSample->anLt, 0);
83285     decodeIntArray((char*)sqlite3_column_text(pStmt,3), nCol, pSample->anDLt,0);
83286 
83287     /* Take a copy of the sample. Add two 0x00 bytes the end of the buffer.
83288     ** This is in case the sample record is corrupted. In that case, the
83289     ** sqlite3VdbeRecordCompare() may read up to two varints past the
83290     ** end of the allocated buffer before it realizes it is dealing with
83291     ** a corrupt record. Adding the two 0x00 bytes prevents this from causing
83292     ** a buffer overread.  */
83293     pSample->n = sqlite3_column_bytes(pStmt, 4);
83294     pSample->p = sqlite3DbMallocZero(db, pSample->n + 2);
83295     if( pSample->p==0 ){
83296       sqlite3_finalize(pStmt);
83297       return SQLITE_NOMEM;
83298     }
83299     memcpy(pSample->p, sqlite3_column_blob(pStmt, 4), pSample->n);
83300     pIdx->nSample++;
83301   }
83302   rc = sqlite3_finalize(pStmt);
83303   if( rc==SQLITE_OK ) initAvgEq(pPrevIdx);
83304   return rc;
83305 }
83306 
83307 /*
83308 ** Load content from the sqlite_stat4 and sqlite_stat3 tables into 
83309 ** the Index.aSample[] arrays of all indices.
83310 */
83311 static int loadStat4(sqlite3 *db, const char *zDb){
83312   int rc = SQLITE_OK;             /* Result codes from subroutines */
83313 
83314   assert( db->lookaside.bEnabled==0 );
83315   if( sqlite3FindTable(db, "sqlite_stat4", zDb) ){
83316     rc = loadStatTbl(db, 0,
83317       "SELECT idx,count(*) FROM %Q.sqlite_stat4 GROUP BY idx", 
83318       "SELECT idx,neq,nlt,ndlt,sample FROM %Q.sqlite_stat4",
83319       zDb
83320     );
83321   }
83322 
83323   if( rc==SQLITE_OK && sqlite3FindTable(db, "sqlite_stat3", zDb) ){
83324     rc = loadStatTbl(db, 1,
83325       "SELECT idx,count(*) FROM %Q.sqlite_stat3 GROUP BY idx", 
83326       "SELECT idx,neq,nlt,ndlt,sqlite_record(sample) FROM %Q.sqlite_stat3",
83327       zDb
83328     );
83329   }
83330 
83331   return rc;
83332 }
83333 #endif /* SQLITE_ENABLE_STAT3_OR_STAT4 */
83334 
83335 /*
83336 ** Load the content of the sqlite_stat1 and sqlite_stat3/4 tables. The
83337 ** contents of sqlite_stat1 are used to populate the Index.aiRowEst[]
83338 ** arrays. The contents of sqlite_stat3/4 are used to populate the
83339 ** Index.aSample[] arrays.
83340 **
83341 ** If the sqlite_stat1 table is not present in the database, SQLITE_ERROR
83342 ** is returned. In this case, even if SQLITE_ENABLE_STAT3/4 was defined 
83343 ** during compilation and the sqlite_stat3/4 table is present, no data is 
83344 ** read from it.
83345 **
83346 ** If SQLITE_ENABLE_STAT3/4 was defined during compilation and the 
83347 ** sqlite_stat4 table is not present in the database, SQLITE_ERROR is
83348 ** returned. However, in this case, data is read from the sqlite_stat1
83349 ** table (if it is present) before returning.
83350 **
83351 ** If an OOM error occurs, this function always sets db->mallocFailed.
83352 ** This means if the caller does not care about other errors, the return
83353 ** code may be ignored.
83354 */
83355 SQLITE_PRIVATE int sqlite3AnalysisLoad(sqlite3 *db, int iDb){
83356   analysisInfo sInfo;
83357   HashElem *i;
83358   char *zSql;
83359   int rc;
83360 
83361   assert( iDb>=0 && iDb<db->nDb );
83362   assert( db->aDb[iDb].pBt!=0 );
83363 
83364   /* Clear any prior statistics */
83365   assert( sqlite3SchemaMutexHeld(db, iDb, 0) );
83366   for(i=sqliteHashFirst(&db->aDb[iDb].pSchema->idxHash);i;i=sqliteHashNext(i)){
83367     Index *pIdx = sqliteHashData(i);
83368     sqlite3DefaultRowEst(pIdx);
83369 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
83370     sqlite3DeleteIndexSamples(db, pIdx);
83371     pIdx->aSample = 0;
83372 #endif
83373   }
83374 
83375   /* Check to make sure the sqlite_stat1 table exists */
83376   sInfo.db = db;
83377   sInfo.zDatabase = db->aDb[iDb].zName;
83378   if( sqlite3FindTable(db, "sqlite_stat1", sInfo.zDatabase)==0 ){
83379     return SQLITE_ERROR;
83380   }
83381 
83382   /* Load new statistics out of the sqlite_stat1 table */
83383   zSql = sqlite3MPrintf(db, 
83384       "SELECT tbl,idx,stat FROM %Q.sqlite_stat1", sInfo.zDatabase);
83385   if( zSql==0 ){
83386     rc = SQLITE_NOMEM;
83387   }else{
83388     rc = sqlite3_exec(db, zSql, analysisLoader, &sInfo, 0);
83389     sqlite3DbFree(db, zSql);
83390   }
83391 
83392 
83393   /* Load the statistics from the sqlite_stat4 table. */
83394 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
83395   if( rc==SQLITE_OK ){
83396     int lookasideEnabled = db->lookaside.bEnabled;
83397     db->lookaside.bEnabled = 0;
83398     rc = loadStat4(db, sInfo.zDatabase);
83399     db->lookaside.bEnabled = lookasideEnabled;
83400   }
83401 #endif
83402 
83403   if( rc==SQLITE_NOMEM ){
83404     db->mallocFailed = 1;
83405   }
83406   return rc;
83407 }
83408 
83409 
83410 #endif /* SQLITE_OMIT_ANALYZE */
83411 
83412 /************** End of analyze.c *********************************************/
83413 /************** Begin file attach.c ******************************************/
83414 /*
83415 ** 2003 April 6
83416 **
83417 ** The author disclaims copyright to this source code.  In place of
83418 ** a legal notice, here is a blessing:
83419 **
83420 **    May you do good and not evil.
83421 **    May you find forgiveness for yourself and forgive others.
83422 **    May you share freely, never taking more than you give.
83423 **
83424 *************************************************************************
83425 ** This file contains code used to implement the ATTACH and DETACH commands.
83426 */
83427 
83428 #ifndef SQLITE_OMIT_ATTACH
83429 /*
83430 ** Resolve an expression that was part of an ATTACH or DETACH statement. This
83431 ** is slightly different from resolving a normal SQL expression, because simple
83432 ** identifiers are treated as strings, not possible column names or aliases.
83433 **
83434 ** i.e. if the parser sees:
83435 **
83436 **     ATTACH DATABASE abc AS def
83437 **
83438 ** it treats the two expressions as literal strings 'abc' and 'def' instead of
83439 ** looking for columns of the same name.
83440 **
83441 ** This only applies to the root node of pExpr, so the statement:
83442 **
83443 **     ATTACH DATABASE abc||def AS 'db2'
83444 **
83445 ** will fail because neither abc or def can be resolved.
83446 */
83447 static int resolveAttachExpr(NameContext *pName, Expr *pExpr)
83448 {
83449   int rc = SQLITE_OK;
83450   if( pExpr ){
83451     if( pExpr->op!=TK_ID ){
83452       rc = sqlite3ResolveExprNames(pName, pExpr);
83453       if( rc==SQLITE_OK && !sqlite3ExprIsConstant(pExpr) ){
83454         sqlite3ErrorMsg(pName->pParse, "invalid name: \"%s\"", pExpr->u.zToken);
83455         return SQLITE_ERROR;
83456       }
83457     }else{
83458       pExpr->op = TK_STRING;
83459     }
83460   }
83461   return rc;
83462 }
83463 
83464 /*
83465 ** An SQL user-function registered to do the work of an ATTACH statement. The
83466 ** three arguments to the function come directly from an attach statement:
83467 **
83468 **     ATTACH DATABASE x AS y KEY z
83469 **
83470 **     SELECT sqlite_attach(x, y, z)
83471 **
83472 ** If the optional "KEY z" syntax is omitted, an SQL NULL is passed as the
83473 ** third argument.
83474 */
83475 static void attachFunc(
83476   sqlite3_context *context,
83477   int NotUsed,
83478   sqlite3_value **argv
83479 ){
83480   int i;
83481   int rc = 0;
83482   sqlite3 *db = sqlite3_context_db_handle(context);
83483   const char *zName;
83484   const char *zFile;
83485   char *zPath = 0;
83486   char *zErr = 0;
83487   unsigned int flags;
83488   Db *aNew;
83489   char *zErrDyn = 0;
83490   sqlite3_vfs *pVfs;
83491 
83492   UNUSED_PARAMETER(NotUsed);
83493 
83494   zFile = (const char *)sqlite3_value_text(argv[0]);
83495   zName = (const char *)sqlite3_value_text(argv[1]);
83496   if( zFile==0 ) zFile = "";
83497   if( zName==0 ) zName = "";
83498 
83499   /* Check for the following errors:
83500   **
83501   **     * Too many attached databases,
83502   **     * Transaction currently open
83503   **     * Specified database name already being used.
83504   */
83505   if( db->nDb>=db->aLimit[SQLITE_LIMIT_ATTACHED]+2 ){
83506     zErrDyn = sqlite3MPrintf(db, "too many attached databases - max %d", 
83507       db->aLimit[SQLITE_LIMIT_ATTACHED]
83508     );
83509     goto attach_error;
83510   }
83511   if( !db->autoCommit ){
83512     zErrDyn = sqlite3MPrintf(db, "cannot ATTACH database within transaction");
83513     goto attach_error;
83514   }
83515   for(i=0; i<db->nDb; i++){
83516     char *z = db->aDb[i].zName;
83517     assert( z && zName );
83518     if( sqlite3StrICmp(z, zName)==0 ){
83519       zErrDyn = sqlite3MPrintf(db, "database %s is already in use", zName);
83520       goto attach_error;
83521     }
83522   }
83523 
83524   /* Allocate the new entry in the db->aDb[] array and initialize the schema
83525   ** hash tables.
83526   */
83527   if( db->aDb==db->aDbStatic ){
83528     aNew = sqlite3DbMallocRaw(db, sizeof(db->aDb[0])*3 );
83529     if( aNew==0 ) return;
83530     memcpy(aNew, db->aDb, sizeof(db->aDb[0])*2);
83531   }else{
83532     aNew = sqlite3DbRealloc(db, db->aDb, sizeof(db->aDb[0])*(db->nDb+1) );
83533     if( aNew==0 ) return;
83534   }
83535   db->aDb = aNew;
83536   aNew = &db->aDb[db->nDb];
83537   memset(aNew, 0, sizeof(*aNew));
83538 
83539   /* Open the database file. If the btree is successfully opened, use
83540   ** it to obtain the database schema. At this point the schema may
83541   ** or may not be initialized.
83542   */
83543   flags = db->openFlags;
83544   rc = sqlite3ParseUri(db->pVfs->zName, zFile, &flags, &pVfs, &zPath, &zErr);
83545   if( rc!=SQLITE_OK ){
83546     if( rc==SQLITE_NOMEM ) db->mallocFailed = 1;
83547     sqlite3_result_error(context, zErr, -1);
83548     sqlite3_free(zErr);
83549     return;
83550   }
83551   assert( pVfs );
83552   flags |= SQLITE_OPEN_MAIN_DB;
83553   rc = sqlite3BtreeOpen(pVfs, zPath, db, &aNew->pBt, 0, flags);
83554   sqlite3_free( zPath );
83555   db->nDb++;
83556   if( rc==SQLITE_CONSTRAINT ){
83557     rc = SQLITE_ERROR;
83558     zErrDyn = sqlite3MPrintf(db, "database is already attached");
83559   }else if( rc==SQLITE_OK ){
83560     Pager *pPager;
83561     aNew->pSchema = sqlite3SchemaGet(db, aNew->pBt);
83562     if( !aNew->pSchema ){
83563       rc = SQLITE_NOMEM;
83564     }else if( aNew->pSchema->file_format && aNew->pSchema->enc!=ENC(db) ){
83565       zErrDyn = sqlite3MPrintf(db, 
83566         "attached databases must use the same text encoding as main database");
83567       rc = SQLITE_ERROR;
83568     }
83569     pPager = sqlite3BtreePager(aNew->pBt);
83570     sqlite3PagerLockingMode(pPager, db->dfltLockMode);
83571     sqlite3BtreeSecureDelete(aNew->pBt,
83572                              sqlite3BtreeSecureDelete(db->aDb[0].pBt,-1) );
83573 #ifndef SQLITE_OMIT_PAGER_PRAGMAS
83574     sqlite3BtreeSetPagerFlags(aNew->pBt, 3 | (db->flags & PAGER_FLAGS_MASK));
83575 #endif
83576   }
83577   aNew->safety_level = 3;
83578   aNew->zName = sqlite3DbStrDup(db, zName);
83579   if( rc==SQLITE_OK && aNew->zName==0 ){
83580     rc = SQLITE_NOMEM;
83581   }
83582 
83583 
83584 #ifdef SQLITE_HAS_CODEC
83585   if( rc==SQLITE_OK ){
83586     extern int sqlite3CodecAttach(sqlite3*, int, const void*, int);
83587     extern void sqlite3CodecGetKey(sqlite3*, int, void**, int*);
83588     int nKey;
83589     char *zKey;
83590     int t = sqlite3_value_type(argv[2]);
83591     switch( t ){
83592       case SQLITE_INTEGER:
83593       case SQLITE_FLOAT:
83594         zErrDyn = sqlite3DbStrDup(db, "Invalid key value");
83595         rc = SQLITE_ERROR;
83596         break;
83597         
83598       case SQLITE_TEXT:
83599       case SQLITE_BLOB:
83600         nKey = sqlite3_value_bytes(argv[2]);
83601         zKey = (char *)sqlite3_value_blob(argv[2]);
83602         rc = sqlite3CodecAttach(db, db->nDb-1, zKey, nKey);
83603         break;
83604 
83605       case SQLITE_NULL:
83606         /* No key specified.  Use the key from the main database */
83607         sqlite3CodecGetKey(db, 0, (void**)&zKey, &nKey);
83608         if( nKey>0 || sqlite3BtreeGetReserve(db->aDb[0].pBt)>0 ){
83609           rc = sqlite3CodecAttach(db, db->nDb-1, zKey, nKey);
83610         }
83611         break;
83612     }
83613   }
83614 #endif
83615 
83616   /* If the file was opened successfully, read the schema for the new database.
83617   ** If this fails, or if opening the file failed, then close the file and 
83618   ** remove the entry from the db->aDb[] array. i.e. put everything back the way
83619   ** we found it.
83620   */
83621   if( rc==SQLITE_OK ){
83622     sqlite3BtreeEnterAll(db);
83623     rc = sqlite3Init(db, &zErrDyn);
83624     sqlite3BtreeLeaveAll(db);
83625   }
83626   if( rc ){
83627     int iDb = db->nDb - 1;
83628     assert( iDb>=2 );
83629     if( db->aDb[iDb].pBt ){
83630       sqlite3BtreeClose(db->aDb[iDb].pBt);
83631       db->aDb[iDb].pBt = 0;
83632       db->aDb[iDb].pSchema = 0;
83633     }
83634     sqlite3ResetAllSchemasOfConnection(db);
83635     db->nDb = iDb;
83636     if( rc==SQLITE_NOMEM || rc==SQLITE_IOERR_NOMEM ){
83637       db->mallocFailed = 1;
83638       sqlite3DbFree(db, zErrDyn);
83639       zErrDyn = sqlite3MPrintf(db, "out of memory");
83640     }else if( zErrDyn==0 ){
83641       zErrDyn = sqlite3MPrintf(db, "unable to open database: %s", zFile);
83642     }
83643     goto attach_error;
83644   }
83645   
83646   return;
83647 
83648 attach_error:
83649   /* Return an error if we get here */
83650   if( zErrDyn ){
83651     sqlite3_result_error(context, zErrDyn, -1);
83652     sqlite3DbFree(db, zErrDyn);
83653   }
83654   if( rc ) sqlite3_result_error_code(context, rc);
83655 }
83656 
83657 /*
83658 ** An SQL user-function registered to do the work of an DETACH statement. The
83659 ** three arguments to the function come directly from a detach statement:
83660 **
83661 **     DETACH DATABASE x
83662 **
83663 **     SELECT sqlite_detach(x)
83664 */
83665 static void detachFunc(
83666   sqlite3_context *context,
83667   int NotUsed,
83668   sqlite3_value **argv
83669 ){
83670   const char *zName = (const char *)sqlite3_value_text(argv[0]);
83671   sqlite3 *db = sqlite3_context_db_handle(context);
83672   int i;
83673   Db *pDb = 0;
83674   char zErr[128];
83675 
83676   UNUSED_PARAMETER(NotUsed);
83677 
83678   if( zName==0 ) zName = "";
83679   for(i=0; i<db->nDb; i++){
83680     pDb = &db->aDb[i];
83681     if( pDb->pBt==0 ) continue;
83682     if( sqlite3StrICmp(pDb->zName, zName)==0 ) break;
83683   }
83684 
83685   if( i>=db->nDb ){
83686     sqlite3_snprintf(sizeof(zErr),zErr, "no such database: %s", zName);
83687     goto detach_error;
83688   }
83689   if( i<2 ){
83690     sqlite3_snprintf(sizeof(zErr),zErr, "cannot detach database %s", zName);
83691     goto detach_error;
83692   }
83693   if( !db->autoCommit ){
83694     sqlite3_snprintf(sizeof(zErr), zErr,
83695                      "cannot DETACH database within transaction");
83696     goto detach_error;
83697   }
83698   if( sqlite3BtreeIsInReadTrans(pDb->pBt) || sqlite3BtreeIsInBackup(pDb->pBt) ){
83699     sqlite3_snprintf(sizeof(zErr),zErr, "database %s is locked", zName);
83700     goto detach_error;
83701   }
83702 
83703   sqlite3BtreeClose(pDb->pBt);
83704   pDb->pBt = 0;
83705   pDb->pSchema = 0;
83706   sqlite3ResetAllSchemasOfConnection(db);
83707   return;
83708 
83709 detach_error:
83710   sqlite3_result_error(context, zErr, -1);
83711 }
83712 
83713 /*
83714 ** This procedure generates VDBE code for a single invocation of either the
83715 ** sqlite_detach() or sqlite_attach() SQL user functions.
83716 */
83717 static void codeAttach(
83718   Parse *pParse,       /* The parser context */
83719   int type,            /* Either SQLITE_ATTACH or SQLITE_DETACH */
83720   FuncDef const *pFunc,/* FuncDef wrapper for detachFunc() or attachFunc() */
83721   Expr *pAuthArg,      /* Expression to pass to authorization callback */
83722   Expr *pFilename,     /* Name of database file */
83723   Expr *pDbname,       /* Name of the database to use internally */
83724   Expr *pKey           /* Database key for encryption extension */
83725 ){
83726   int rc;
83727   NameContext sName;
83728   Vdbe *v;
83729   sqlite3* db = pParse->db;
83730   int regArgs;
83731 
83732   memset(&sName, 0, sizeof(NameContext));
83733   sName.pParse = pParse;
83734 
83735   if( 
83736       SQLITE_OK!=(rc = resolveAttachExpr(&sName, pFilename)) ||
83737       SQLITE_OK!=(rc = resolveAttachExpr(&sName, pDbname)) ||
83738       SQLITE_OK!=(rc = resolveAttachExpr(&sName, pKey))
83739   ){
83740     pParse->nErr++;
83741     goto attach_end;
83742   }
83743 
83744 #ifndef SQLITE_OMIT_AUTHORIZATION
83745   if( pAuthArg ){
83746     char *zAuthArg;
83747     if( pAuthArg->op==TK_STRING ){
83748       zAuthArg = pAuthArg->u.zToken;
83749     }else{
83750       zAuthArg = 0;
83751     }
83752     rc = sqlite3AuthCheck(pParse, type, zAuthArg, 0, 0);
83753     if(rc!=SQLITE_OK ){
83754       goto attach_end;
83755     }
83756   }
83757 #endif /* SQLITE_OMIT_AUTHORIZATION */
83758 
83759 
83760   v = sqlite3GetVdbe(pParse);
83761   regArgs = sqlite3GetTempRange(pParse, 4);
83762   sqlite3ExprCode(pParse, pFilename, regArgs);
83763   sqlite3ExprCode(pParse, pDbname, regArgs+1);
83764   sqlite3ExprCode(pParse, pKey, regArgs+2);
83765 
83766   assert( v || db->mallocFailed );
83767   if( v ){
83768     sqlite3VdbeAddOp3(v, OP_Function, 0, regArgs+3-pFunc->nArg, regArgs+3);
83769     assert( pFunc->nArg==-1 || (pFunc->nArg&0xff)==pFunc->nArg );
83770     sqlite3VdbeChangeP5(v, (u8)(pFunc->nArg));
83771     sqlite3VdbeChangeP4(v, -1, (char *)pFunc, P4_FUNCDEF);
83772 
83773     /* Code an OP_Expire. For an ATTACH statement, set P1 to true (expire this
83774     ** statement only). For DETACH, set it to false (expire all existing
83775     ** statements).
83776     */
83777     sqlite3VdbeAddOp1(v, OP_Expire, (type==SQLITE_ATTACH));
83778   }
83779   
83780 attach_end:
83781   sqlite3ExprDelete(db, pFilename);
83782   sqlite3ExprDelete(db, pDbname);
83783   sqlite3ExprDelete(db, pKey);
83784 }
83785 
83786 /*
83787 ** Called by the parser to compile a DETACH statement.
83788 **
83789 **     DETACH pDbname
83790 */
83791 SQLITE_PRIVATE void sqlite3Detach(Parse *pParse, Expr *pDbname){
83792   static const FuncDef detach_func = {
83793     1,                /* nArg */
83794     SQLITE_UTF8,      /* funcFlags */
83795     0,                /* pUserData */
83796     0,                /* pNext */
83797     detachFunc,       /* xFunc */
83798     0,                /* xStep */
83799     0,                /* xFinalize */
83800     "sqlite_detach",  /* zName */
83801     0,                /* pHash */
83802     0                 /* pDestructor */
83803   };
83804   codeAttach(pParse, SQLITE_DETACH, &detach_func, pDbname, 0, 0, pDbname);
83805 }
83806 
83807 /*
83808 ** Called by the parser to compile an ATTACH statement.
83809 **
83810 **     ATTACH p AS pDbname KEY pKey
83811 */
83812 SQLITE_PRIVATE void sqlite3Attach(Parse *pParse, Expr *p, Expr *pDbname, Expr *pKey){
83813   static const FuncDef attach_func = {
83814     3,                /* nArg */
83815     SQLITE_UTF8,      /* funcFlags */
83816     0,                /* pUserData */
83817     0,                /* pNext */
83818     attachFunc,       /* xFunc */
83819     0,                /* xStep */
83820     0,                /* xFinalize */
83821     "sqlite_attach",  /* zName */
83822     0,                /* pHash */
83823     0                 /* pDestructor */
83824   };
83825   codeAttach(pParse, SQLITE_ATTACH, &attach_func, p, p, pDbname, pKey);
83826 }
83827 #endif /* SQLITE_OMIT_ATTACH */
83828 
83829 /*
83830 ** Initialize a DbFixer structure.  This routine must be called prior
83831 ** to passing the structure to one of the sqliteFixAAAA() routines below.
83832 */
83833 SQLITE_PRIVATE void sqlite3FixInit(
83834   DbFixer *pFix,      /* The fixer to be initialized */
83835   Parse *pParse,      /* Error messages will be written here */
83836   int iDb,            /* This is the database that must be used */
83837   const char *zType,  /* "view", "trigger", or "index" */
83838   const Token *pName  /* Name of the view, trigger, or index */
83839 ){
83840   sqlite3 *db;
83841 
83842   db = pParse->db;
83843   assert( db->nDb>iDb );
83844   pFix->pParse = pParse;
83845   pFix->zDb = db->aDb[iDb].zName;
83846   pFix->pSchema = db->aDb[iDb].pSchema;
83847   pFix->zType = zType;
83848   pFix->pName = pName;
83849   pFix->bVarOnly = (iDb==1);
83850 }
83851 
83852 /*
83853 ** The following set of routines walk through the parse tree and assign
83854 ** a specific database to all table references where the database name
83855 ** was left unspecified in the original SQL statement.  The pFix structure
83856 ** must have been initialized by a prior call to sqlite3FixInit().
83857 **
83858 ** These routines are used to make sure that an index, trigger, or
83859 ** view in one database does not refer to objects in a different database.
83860 ** (Exception: indices, triggers, and views in the TEMP database are
83861 ** allowed to refer to anything.)  If a reference is explicitly made
83862 ** to an object in a different database, an error message is added to
83863 ** pParse->zErrMsg and these routines return non-zero.  If everything
83864 ** checks out, these routines return 0.
83865 */
83866 SQLITE_PRIVATE int sqlite3FixSrcList(
83867   DbFixer *pFix,       /* Context of the fixation */
83868   SrcList *pList       /* The Source list to check and modify */
83869 ){
83870   int i;
83871   const char *zDb;
83872   struct SrcList_item *pItem;
83873 
83874   if( NEVER(pList==0) ) return 0;
83875   zDb = pFix->zDb;
83876   for(i=0, pItem=pList->a; i<pList->nSrc; i++, pItem++){
83877     if( pFix->bVarOnly==0 ){
83878       if( pItem->zDatabase && sqlite3StrICmp(pItem->zDatabase, zDb) ){
83879         sqlite3ErrorMsg(pFix->pParse,
83880             "%s %T cannot reference objects in database %s",
83881             pFix->zType, pFix->pName, pItem->zDatabase);
83882         return 1;
83883       }
83884       sqlite3DbFree(pFix->pParse->db, pItem->zDatabase);
83885       pItem->zDatabase = 0;
83886       pItem->pSchema = pFix->pSchema;
83887     }
83888 #if !defined(SQLITE_OMIT_VIEW) || !defined(SQLITE_OMIT_TRIGGER)
83889     if( sqlite3FixSelect(pFix, pItem->pSelect) ) return 1;
83890     if( sqlite3FixExpr(pFix, pItem->pOn) ) return 1;
83891 #endif
83892   }
83893   return 0;
83894 }
83895 #if !defined(SQLITE_OMIT_VIEW) || !defined(SQLITE_OMIT_TRIGGER)
83896 SQLITE_PRIVATE int sqlite3FixSelect(
83897   DbFixer *pFix,       /* Context of the fixation */
83898   Select *pSelect      /* The SELECT statement to be fixed to one database */
83899 ){
83900   while( pSelect ){
83901     if( sqlite3FixExprList(pFix, pSelect->pEList) ){
83902       return 1;
83903     }
83904     if( sqlite3FixSrcList(pFix, pSelect->pSrc) ){
83905       return 1;
83906     }
83907     if( sqlite3FixExpr(pFix, pSelect->pWhere) ){
83908       return 1;
83909     }
83910     if( sqlite3FixExprList(pFix, pSelect->pGroupBy) ){
83911       return 1;
83912     }
83913     if( sqlite3FixExpr(pFix, pSelect->pHaving) ){
83914       return 1;
83915     }
83916     if( sqlite3FixExprList(pFix, pSelect->pOrderBy) ){
83917       return 1;
83918     }
83919     if( sqlite3FixExpr(pFix, pSelect->pLimit) ){
83920       return 1;
83921     }
83922     if( sqlite3FixExpr(pFix, pSelect->pOffset) ){
83923       return 1;
83924     }
83925     pSelect = pSelect->pPrior;
83926   }
83927   return 0;
83928 }
83929 SQLITE_PRIVATE int sqlite3FixExpr(
83930   DbFixer *pFix,     /* Context of the fixation */
83931   Expr *pExpr        /* The expression to be fixed to one database */
83932 ){
83933   while( pExpr ){
83934     if( pExpr->op==TK_VARIABLE ){
83935       if( pFix->pParse->db->init.busy ){
83936         pExpr->op = TK_NULL;
83937       }else{
83938         sqlite3ErrorMsg(pFix->pParse, "%s cannot use variables", pFix->zType);
83939         return 1;
83940       }
83941     }
83942     if( ExprHasProperty(pExpr, EP_TokenOnly) ) break;
83943     if( ExprHasProperty(pExpr, EP_xIsSelect) ){
83944       if( sqlite3FixSelect(pFix, pExpr->x.pSelect) ) return 1;
83945     }else{
83946       if( sqlite3FixExprList(pFix, pExpr->x.pList) ) return 1;
83947     }
83948     if( sqlite3FixExpr(pFix, pExpr->pRight) ){
83949       return 1;
83950     }
83951     pExpr = pExpr->pLeft;
83952   }
83953   return 0;
83954 }
83955 SQLITE_PRIVATE int sqlite3FixExprList(
83956   DbFixer *pFix,     /* Context of the fixation */
83957   ExprList *pList    /* The expression to be fixed to one database */
83958 ){
83959   int i;
83960   struct ExprList_item *pItem;
83961   if( pList==0 ) return 0;
83962   for(i=0, pItem=pList->a; i<pList->nExpr; i++, pItem++){
83963     if( sqlite3FixExpr(pFix, pItem->pExpr) ){
83964       return 1;
83965     }
83966   }
83967   return 0;
83968 }
83969 #endif
83970 
83971 #ifndef SQLITE_OMIT_TRIGGER
83972 SQLITE_PRIVATE int sqlite3FixTriggerStep(
83973   DbFixer *pFix,     /* Context of the fixation */
83974   TriggerStep *pStep /* The trigger step be fixed to one database */
83975 ){
83976   while( pStep ){
83977     if( sqlite3FixSelect(pFix, pStep->pSelect) ){
83978       return 1;
83979     }
83980     if( sqlite3FixExpr(pFix, pStep->pWhere) ){
83981       return 1;
83982     }
83983     if( sqlite3FixExprList(pFix, pStep->pExprList) ){
83984       return 1;
83985     }
83986     pStep = pStep->pNext;
83987   }
83988   return 0;
83989 }
83990 #endif
83991 
83992 /************** End of attach.c **********************************************/
83993 /************** Begin file auth.c ********************************************/
83994 /*
83995 ** 2003 January 11
83996 **
83997 ** The author disclaims copyright to this source code.  In place of
83998 ** a legal notice, here is a blessing:
83999 **
84000 **    May you do good and not evil.
84001 **    May you find forgiveness for yourself and forgive others.
84002 **    May you share freely, never taking more than you give.
84003 **
84004 *************************************************************************
84005 ** This file contains code used to implement the sqlite3_set_authorizer()
84006 ** API.  This facility is an optional feature of the library.  Embedded
84007 ** systems that do not need this facility may omit it by recompiling
84008 ** the library with -DSQLITE_OMIT_AUTHORIZATION=1
84009 */
84010 
84011 /*
84012 ** All of the code in this file may be omitted by defining a single
84013 ** macro.
84014 */
84015 #ifndef SQLITE_OMIT_AUTHORIZATION
84016 
84017 /*
84018 ** Set or clear the access authorization function.
84019 **
84020 ** The access authorization function is be called during the compilation
84021 ** phase to verify that the user has read and/or write access permission on
84022 ** various fields of the database.  The first argument to the auth function
84023 ** is a copy of the 3rd argument to this routine.  The second argument
84024 ** to the auth function is one of these constants:
84025 **
84026 **       SQLITE_CREATE_INDEX
84027 **       SQLITE_CREATE_TABLE
84028 **       SQLITE_CREATE_TEMP_INDEX
84029 **       SQLITE_CREATE_TEMP_TABLE
84030 **       SQLITE_CREATE_TEMP_TRIGGER
84031 **       SQLITE_CREATE_TEMP_VIEW
84032 **       SQLITE_CREATE_TRIGGER
84033 **       SQLITE_CREATE_VIEW
84034 **       SQLITE_DELETE
84035 **       SQLITE_DROP_INDEX
84036 **       SQLITE_DROP_TABLE
84037 **       SQLITE_DROP_TEMP_INDEX
84038 **       SQLITE_DROP_TEMP_TABLE
84039 **       SQLITE_DROP_TEMP_TRIGGER
84040 **       SQLITE_DROP_TEMP_VIEW
84041 **       SQLITE_DROP_TRIGGER
84042 **       SQLITE_DROP_VIEW
84043 **       SQLITE_INSERT
84044 **       SQLITE_PRAGMA
84045 **       SQLITE_READ
84046 **       SQLITE_SELECT
84047 **       SQLITE_TRANSACTION
84048 **       SQLITE_UPDATE
84049 **
84050 ** The third and fourth arguments to the auth function are the name of
84051 ** the table and the column that are being accessed.  The auth function
84052 ** should return either SQLITE_OK, SQLITE_DENY, or SQLITE_IGNORE.  If
84053 ** SQLITE_OK is returned, it means that access is allowed.  SQLITE_DENY
84054 ** means that the SQL statement will never-run - the sqlite3_exec() call
84055 ** will return with an error.  SQLITE_IGNORE means that the SQL statement
84056 ** should run but attempts to read the specified column will return NULL
84057 ** and attempts to write the column will be ignored.
84058 **
84059 ** Setting the auth function to NULL disables this hook.  The default
84060 ** setting of the auth function is NULL.
84061 */
84062 SQLITE_API int sqlite3_set_authorizer(
84063   sqlite3 *db,
84064   int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
84065   void *pArg
84066 ){
84067   sqlite3_mutex_enter(db->mutex);
84068   db->xAuth = xAuth;
84069   db->pAuthArg = pArg;
84070   sqlite3ExpirePreparedStatements(db);
84071   sqlite3_mutex_leave(db->mutex);
84072   return SQLITE_OK;
84073 }
84074 
84075 /*
84076 ** Write an error message into pParse->zErrMsg that explains that the
84077 ** user-supplied authorization function returned an illegal value.
84078 */
84079 static void sqliteAuthBadReturnCode(Parse *pParse){
84080   sqlite3ErrorMsg(pParse, "authorizer malfunction");
84081   pParse->rc = SQLITE_ERROR;
84082 }
84083 
84084 /*
84085 ** Invoke the authorization callback for permission to read column zCol from
84086 ** table zTab in database zDb. This function assumes that an authorization
84087 ** callback has been registered (i.e. that sqlite3.xAuth is not NULL).
84088 **
84089 ** If SQLITE_IGNORE is returned and pExpr is not NULL, then pExpr is changed
84090 ** to an SQL NULL expression. Otherwise, if pExpr is NULL, then SQLITE_IGNORE
84091 ** is treated as SQLITE_DENY. In this case an error is left in pParse.
84092 */
84093 SQLITE_PRIVATE int sqlite3AuthReadCol(
84094   Parse *pParse,                  /* The parser context */
84095   const char *zTab,               /* Table name */
84096   const char *zCol,               /* Column name */
84097   int iDb                         /* Index of containing database. */
84098 ){
84099   sqlite3 *db = pParse->db;       /* Database handle */
84100   char *zDb = db->aDb[iDb].zName; /* Name of attached database */
84101   int rc;                         /* Auth callback return code */
84102 
84103   rc = db->xAuth(db->pAuthArg, SQLITE_READ, zTab,zCol,zDb,pParse->zAuthContext);
84104   if( rc==SQLITE_DENY ){
84105     if( db->nDb>2 || iDb!=0 ){
84106       sqlite3ErrorMsg(pParse, "access to %s.%s.%s is prohibited",zDb,zTab,zCol);
84107     }else{
84108       sqlite3ErrorMsg(pParse, "access to %s.%s is prohibited", zTab, zCol);
84109     }
84110     pParse->rc = SQLITE_AUTH;
84111   }else if( rc!=SQLITE_IGNORE && rc!=SQLITE_OK ){
84112     sqliteAuthBadReturnCode(pParse);
84113   }
84114   return rc;
84115 }
84116 
84117 /*
84118 ** The pExpr should be a TK_COLUMN expression.  The table referred to
84119 ** is in pTabList or else it is the NEW or OLD table of a trigger.  
84120 ** Check to see if it is OK to read this particular column.
84121 **
84122 ** If the auth function returns SQLITE_IGNORE, change the TK_COLUMN 
84123 ** instruction into a TK_NULL.  If the auth function returns SQLITE_DENY,
84124 ** then generate an error.
84125 */
84126 SQLITE_PRIVATE void sqlite3AuthRead(
84127   Parse *pParse,        /* The parser context */
84128   Expr *pExpr,          /* The expression to check authorization on */
84129   Schema *pSchema,      /* The schema of the expression */
84130   SrcList *pTabList     /* All table that pExpr might refer to */
84131 ){
84132   sqlite3 *db = pParse->db;
84133   Table *pTab = 0;      /* The table being read */
84134   const char *zCol;     /* Name of the column of the table */
84135   int iSrc;             /* Index in pTabList->a[] of table being read */
84136   int iDb;              /* The index of the database the expression refers to */
84137   int iCol;             /* Index of column in table */
84138 
84139   if( db->xAuth==0 ) return;
84140   iDb = sqlite3SchemaToIndex(pParse->db, pSchema);
84141   if( iDb<0 ){
84142     /* An attempt to read a column out of a subquery or other
84143     ** temporary table. */
84144     return;
84145   }
84146 
84147   assert( pExpr->op==TK_COLUMN || pExpr->op==TK_TRIGGER );
84148   if( pExpr->op==TK_TRIGGER ){
84149     pTab = pParse->pTriggerTab;
84150   }else{
84151     assert( pTabList );
84152     for(iSrc=0; ALWAYS(iSrc<pTabList->nSrc); iSrc++){
84153       if( pExpr->iTable==pTabList->a[iSrc].iCursor ){
84154         pTab = pTabList->a[iSrc].pTab;
84155         break;
84156       }
84157     }
84158   }
84159   iCol = pExpr->iColumn;
84160   if( NEVER(pTab==0) ) return;
84161 
84162   if( iCol>=0 ){
84163     assert( iCol<pTab->nCol );
84164     zCol = pTab->aCol[iCol].zName;
84165   }else if( pTab->iPKey>=0 ){
84166     assert( pTab->iPKey<pTab->nCol );
84167     zCol = pTab->aCol[pTab->iPKey].zName;
84168   }else{
84169     zCol = "ROWID";
84170   }
84171   assert( iDb>=0 && iDb<db->nDb );
84172   if( SQLITE_IGNORE==sqlite3AuthReadCol(pParse, pTab->zName, zCol, iDb) ){
84173     pExpr->op = TK_NULL;
84174   }
84175 }
84176 
84177 /*
84178 ** Do an authorization check using the code and arguments given.  Return
84179 ** either SQLITE_OK (zero) or SQLITE_IGNORE or SQLITE_DENY.  If SQLITE_DENY
84180 ** is returned, then the error count and error message in pParse are
84181 ** modified appropriately.
84182 */
84183 SQLITE_PRIVATE int sqlite3AuthCheck(
84184   Parse *pParse,
84185   int code,
84186   const char *zArg1,
84187   const char *zArg2,
84188   const char *zArg3
84189 ){
84190   sqlite3 *db = pParse->db;
84191   int rc;
84192 
84193   /* Don't do any authorization checks if the database is initialising
84194   ** or if the parser is being invoked from within sqlite3_declare_vtab.
84195   */
84196   if( db->init.busy || IN_DECLARE_VTAB ){
84197     return SQLITE_OK;
84198   }
84199 
84200   if( db->xAuth==0 ){
84201     return SQLITE_OK;
84202   }
84203   rc = db->xAuth(db->pAuthArg, code, zArg1, zArg2, zArg3, pParse->zAuthContext);
84204   if( rc==SQLITE_DENY ){
84205     sqlite3ErrorMsg(pParse, "not authorized");
84206     pParse->rc = SQLITE_AUTH;
84207   }else if( rc!=SQLITE_OK && rc!=SQLITE_IGNORE ){
84208     rc = SQLITE_DENY;
84209     sqliteAuthBadReturnCode(pParse);
84210   }
84211   return rc;
84212 }
84213 
84214 /*
84215 ** Push an authorization context.  After this routine is called, the
84216 ** zArg3 argument to authorization callbacks will be zContext until
84217 ** popped.  Or if pParse==0, this routine is a no-op.
84218 */
84219 SQLITE_PRIVATE void sqlite3AuthContextPush(
84220   Parse *pParse,
84221   AuthContext *pContext, 
84222   const char *zContext
84223 ){
84224   assert( pParse );
84225   pContext->pParse = pParse;
84226   pContext->zAuthContext = pParse->zAuthContext;
84227   pParse->zAuthContext = zContext;
84228 }
84229 
84230 /*
84231 ** Pop an authorization context that was previously pushed
84232 ** by sqlite3AuthContextPush
84233 */
84234 SQLITE_PRIVATE void sqlite3AuthContextPop(AuthContext *pContext){
84235   if( pContext->pParse ){
84236     pContext->pParse->zAuthContext = pContext->zAuthContext;
84237     pContext->pParse = 0;
84238   }
84239 }
84240 
84241 #endif /* SQLITE_OMIT_AUTHORIZATION */
84242 
84243 /************** End of auth.c ************************************************/
84244 /************** Begin file build.c *******************************************/
84245 /*
84246 ** 2001 September 15
84247 **
84248 ** The author disclaims copyright to this source code.  In place of
84249 ** a legal notice, here is a blessing:
84250 **
84251 **    May you do good and not evil.
84252 **    May you find forgiveness for yourself and forgive others.
84253 **    May you share freely, never taking more than you give.
84254 **
84255 *************************************************************************
84256 ** This file contains C code routines that are called by the SQLite parser
84257 ** when syntax rules are reduced.  The routines in this file handle the
84258 ** following kinds of SQL syntax:
84259 **
84260 **     CREATE TABLE
84261 **     DROP TABLE
84262 **     CREATE INDEX
84263 **     DROP INDEX
84264 **     creating ID lists
84265 **     BEGIN TRANSACTION
84266 **     COMMIT
84267 **     ROLLBACK
84268 */
84269 
84270 /*
84271 ** This routine is called when a new SQL statement is beginning to
84272 ** be parsed.  Initialize the pParse structure as needed.
84273 */
84274 SQLITE_PRIVATE void sqlite3BeginParse(Parse *pParse, int explainFlag){
84275   pParse->explain = (u8)explainFlag;
84276   pParse->nVar = 0;
84277 }
84278 
84279 #ifndef SQLITE_OMIT_SHARED_CACHE
84280 /*
84281 ** The TableLock structure is only used by the sqlite3TableLock() and
84282 ** codeTableLocks() functions.
84283 */
84284 struct TableLock {
84285   int iDb;             /* The database containing the table to be locked */
84286   int iTab;            /* The root page of the table to be locked */
84287   u8 isWriteLock;      /* True for write lock.  False for a read lock */
84288   const char *zName;   /* Name of the table */
84289 };
84290 
84291 /*
84292 ** Record the fact that we want to lock a table at run-time.  
84293 **
84294 ** The table to be locked has root page iTab and is found in database iDb.
84295 ** A read or a write lock can be taken depending on isWritelock.
84296 **
84297 ** This routine just records the fact that the lock is desired.  The
84298 ** code to make the lock occur is generated by a later call to
84299 ** codeTableLocks() which occurs during sqlite3FinishCoding().
84300 */
84301 SQLITE_PRIVATE void sqlite3TableLock(
84302   Parse *pParse,     /* Parsing context */
84303   int iDb,           /* Index of the database containing the table to lock */
84304   int iTab,          /* Root page number of the table to be locked */
84305   u8 isWriteLock,    /* True for a write lock */
84306   const char *zName  /* Name of the table to be locked */
84307 ){
84308   Parse *pToplevel = sqlite3ParseToplevel(pParse);
84309   int i;
84310   int nBytes;
84311   TableLock *p;
84312   assert( iDb>=0 );
84313 
84314   for(i=0; i<pToplevel->nTableLock; i++){
84315     p = &pToplevel->aTableLock[i];
84316     if( p->iDb==iDb && p->iTab==iTab ){
84317       p->isWriteLock = (p->isWriteLock || isWriteLock);
84318       return;
84319     }
84320   }
84321 
84322   nBytes = sizeof(TableLock) * (pToplevel->nTableLock+1);
84323   pToplevel->aTableLock =
84324       sqlite3DbReallocOrFree(pToplevel->db, pToplevel->aTableLock, nBytes);
84325   if( pToplevel->aTableLock ){
84326     p = &pToplevel->aTableLock[pToplevel->nTableLock++];
84327     p->iDb = iDb;
84328     p->iTab = iTab;
84329     p->isWriteLock = isWriteLock;
84330     p->zName = zName;
84331   }else{
84332     pToplevel->nTableLock = 0;
84333     pToplevel->db->mallocFailed = 1;
84334   }
84335 }
84336 
84337 /*
84338 ** Code an OP_TableLock instruction for each table locked by the
84339 ** statement (configured by calls to sqlite3TableLock()).
84340 */
84341 static void codeTableLocks(Parse *pParse){
84342   int i;
84343   Vdbe *pVdbe; 
84344 
84345   pVdbe = sqlite3GetVdbe(pParse);
84346   assert( pVdbe!=0 ); /* sqlite3GetVdbe cannot fail: VDBE already allocated */
84347 
84348   for(i=0; i<pParse->nTableLock; i++){
84349     TableLock *p = &pParse->aTableLock[i];
84350     int p1 = p->iDb;
84351     sqlite3VdbeAddOp4(pVdbe, OP_TableLock, p1, p->iTab, p->isWriteLock,
84352                       p->zName, P4_STATIC);
84353   }
84354 }
84355 #else
84356   #define codeTableLocks(x)
84357 #endif
84358 
84359 /*
84360 ** This routine is called after a single SQL statement has been
84361 ** parsed and a VDBE program to execute that statement has been
84362 ** prepared.  This routine puts the finishing touches on the
84363 ** VDBE program and resets the pParse structure for the next
84364 ** parse.
84365 **
84366 ** Note that if an error occurred, it might be the case that
84367 ** no VDBE code was generated.
84368 */
84369 SQLITE_PRIVATE void sqlite3FinishCoding(Parse *pParse){
84370   sqlite3 *db;
84371   Vdbe *v;
84372 
84373   assert( pParse->pToplevel==0 );
84374   db = pParse->db;
84375   if( db->mallocFailed ) return;
84376   if( pParse->nested ) return;
84377   if( pParse->nErr ) return;
84378 
84379   /* Begin by generating some termination code at the end of the
84380   ** vdbe program
84381   */
84382   v = sqlite3GetVdbe(pParse);
84383   assert( !pParse->isMultiWrite 
84384        || sqlite3VdbeAssertMayAbort(v, pParse->mayAbort));
84385   if( v ){
84386     sqlite3VdbeAddOp0(v, OP_Halt);
84387 
84388     /* The cookie mask contains one bit for each database file open.
84389     ** (Bit 0 is for main, bit 1 is for temp, and so forth.)  Bits are
84390     ** set for each database that is used.  Generate code to start a
84391     ** transaction on each used database and to verify the schema cookie
84392     ** on each used database.
84393     */
84394     if( pParse->cookieGoto>0 ){
84395       yDbMask mask;
84396       int iDb, i, addr;
84397       sqlite3VdbeJumpHere(v, pParse->cookieGoto-1);
84398       for(iDb=0, mask=1; iDb<db->nDb; mask<<=1, iDb++){
84399         if( (mask & pParse->cookieMask)==0 ) continue;
84400         sqlite3VdbeUsesBtree(v, iDb);
84401         sqlite3VdbeAddOp2(v,OP_Transaction, iDb, (mask & pParse->writeMask)!=0);
84402         if( db->init.busy==0 ){
84403           assert( sqlite3SchemaMutexHeld(db, iDb, 0) );
84404           sqlite3VdbeAddOp3(v, OP_VerifyCookie,
84405                             iDb, pParse->cookieValue[iDb],
84406                             db->aDb[iDb].pSchema->iGeneration);
84407         }
84408       }
84409 #ifndef SQLITE_OMIT_VIRTUALTABLE
84410       for(i=0; i<pParse->nVtabLock; i++){
84411         char *vtab = (char *)sqlite3GetVTable(db, pParse->apVtabLock[i]);
84412         sqlite3VdbeAddOp4(v, OP_VBegin, 0, 0, 0, vtab, P4_VTAB);
84413       }
84414       pParse->nVtabLock = 0;
84415 #endif
84416 
84417       /* Once all the cookies have been verified and transactions opened, 
84418       ** obtain the required table-locks. This is a no-op unless the 
84419       ** shared-cache feature is enabled.
84420       */
84421       codeTableLocks(pParse);
84422 
84423       /* Initialize any AUTOINCREMENT data structures required.
84424       */
84425       sqlite3AutoincrementBegin(pParse);
84426 
84427       /* Code constant expressions that where factored out of inner loops */
84428       addr = pParse->cookieGoto;
84429       if( pParse->pConstExpr ){
84430         ExprList *pEL = pParse->pConstExpr;
84431         pParse->cookieGoto = 0;
84432         for(i=0; i<pEL->nExpr; i++){
84433           sqlite3ExprCode(pParse, pEL->a[i].pExpr, pEL->a[i].u.iConstExprReg);
84434         }
84435       }
84436 
84437       /* Finally, jump back to the beginning of the executable code. */
84438       sqlite3VdbeAddOp2(v, OP_Goto, 0, addr);
84439     }
84440   }
84441 
84442 
84443   /* Get the VDBE program ready for execution
84444   */
84445   if( v && ALWAYS(pParse->nErr==0) && !db->mallocFailed ){
84446     assert( pParse->iCacheLevel==0 );  /* Disables and re-enables match */
84447     /* A minimum of one cursor is required if autoincrement is used
84448     *  See ticket [a696379c1f08866] */
84449     if( pParse->pAinc!=0 && pParse->nTab==0 ) pParse->nTab = 1;
84450     sqlite3VdbeMakeReady(v, pParse);
84451     pParse->rc = SQLITE_DONE;
84452     pParse->colNamesSet = 0;
84453   }else{
84454     pParse->rc = SQLITE_ERROR;
84455   }
84456   pParse->nTab = 0;
84457   pParse->nMem = 0;
84458   pParse->nSet = 0;
84459   pParse->nVar = 0;
84460   pParse->cookieMask = 0;
84461   pParse->cookieGoto = 0;
84462 }
84463 
84464 /*
84465 ** Run the parser and code generator recursively in order to generate
84466 ** code for the SQL statement given onto the end of the pParse context
84467 ** currently under construction.  When the parser is run recursively
84468 ** this way, the final OP_Halt is not appended and other initialization
84469 ** and finalization steps are omitted because those are handling by the
84470 ** outermost parser.
84471 **
84472 ** Not everything is nestable.  This facility is designed to permit
84473 ** INSERT, UPDATE, and DELETE operations against SQLITE_MASTER.  Use
84474 ** care if you decide to try to use this routine for some other purposes.
84475 */
84476 SQLITE_PRIVATE void sqlite3NestedParse(Parse *pParse, const char *zFormat, ...){
84477   va_list ap;
84478   char *zSql;
84479   char *zErrMsg = 0;
84480   sqlite3 *db = pParse->db;
84481 # define SAVE_SZ  (sizeof(Parse) - offsetof(Parse,nVar))
84482   char saveBuf[SAVE_SZ];
84483 
84484   if( pParse->nErr ) return;
84485   assert( pParse->nested<10 );  /* Nesting should only be of limited depth */
84486   va_start(ap, zFormat);
84487   zSql = sqlite3VMPrintf(db, zFormat, ap);
84488   va_end(ap);
84489   if( zSql==0 ){
84490     return;   /* A malloc must have failed */
84491   }
84492   pParse->nested++;
84493   memcpy(saveBuf, &pParse->nVar, SAVE_SZ);
84494   memset(&pParse->nVar, 0, SAVE_SZ);
84495   sqlite3RunParser(pParse, zSql, &zErrMsg);
84496   sqlite3DbFree(db, zErrMsg);
84497   sqlite3DbFree(db, zSql);
84498   memcpy(&pParse->nVar, saveBuf, SAVE_SZ);
84499   pParse->nested--;
84500 }
84501 
84502 /*
84503 ** Locate the in-memory structure that describes a particular database
84504 ** table given the name of that table and (optionally) the name of the
84505 ** database containing the table.  Return NULL if not found.
84506 **
84507 ** If zDatabase is 0, all databases are searched for the table and the
84508 ** first matching table is returned.  (No checking for duplicate table
84509 ** names is done.)  The search order is TEMP first, then MAIN, then any
84510 ** auxiliary databases added using the ATTACH command.
84511 **
84512 ** See also sqlite3LocateTable().
84513 */
84514 SQLITE_PRIVATE Table *sqlite3FindTable(sqlite3 *db, const char *zName, const char *zDatabase){
84515   Table *p = 0;
84516   int i;
84517   int nName;
84518   assert( zName!=0 );
84519   nName = sqlite3Strlen30(zName);
84520   /* All mutexes are required for schema access.  Make sure we hold them. */
84521   assert( zDatabase!=0 || sqlite3BtreeHoldsAllMutexes(db) );
84522   for(i=OMIT_TEMPDB; i<db->nDb; i++){
84523     int j = (i<2) ? i^1 : i;   /* Search TEMP before MAIN */
84524     if( zDatabase!=0 && sqlite3StrICmp(zDatabase, db->aDb[j].zName) ) continue;
84525     assert( sqlite3SchemaMutexHeld(db, j, 0) );
84526     p = sqlite3HashFind(&db->aDb[j].pSchema->tblHash, zName, nName);
84527     if( p ) break;
84528   }
84529   return p;
84530 }
84531 
84532 /*
84533 ** Locate the in-memory structure that describes a particular database
84534 ** table given the name of that table and (optionally) the name of the
84535 ** database containing the table.  Return NULL if not found.  Also leave an
84536 ** error message in pParse->zErrMsg.
84537 **
84538 ** The difference between this routine and sqlite3FindTable() is that this
84539 ** routine leaves an error message in pParse->zErrMsg where
84540 ** sqlite3FindTable() does not.
84541 */
84542 SQLITE_PRIVATE Table *sqlite3LocateTable(
84543   Parse *pParse,         /* context in which to report errors */
84544   int isView,            /* True if looking for a VIEW rather than a TABLE */
84545   const char *zName,     /* Name of the table we are looking for */
84546   const char *zDbase     /* Name of the database.  Might be NULL */
84547 ){
84548   Table *p;
84549 
84550   /* Read the database schema. If an error occurs, leave an error message
84551   ** and code in pParse and return NULL. */
84552   if( SQLITE_OK!=sqlite3ReadSchema(pParse) ){
84553     return 0;
84554   }
84555 
84556   p = sqlite3FindTable(pParse->db, zName, zDbase);
84557   if( p==0 ){
84558     const char *zMsg = isView ? "no such view" : "no such table";
84559     if( zDbase ){
84560       sqlite3ErrorMsg(pParse, "%s: %s.%s", zMsg, zDbase, zName);
84561     }else{
84562       sqlite3ErrorMsg(pParse, "%s: %s", zMsg, zName);
84563     }
84564     pParse->checkSchema = 1;
84565   }
84566   return p;
84567 }
84568 
84569 /*
84570 ** Locate the table identified by *p.
84571 **
84572 ** This is a wrapper around sqlite3LocateTable(). The difference between
84573 ** sqlite3LocateTable() and this function is that this function restricts
84574 ** the search to schema (p->pSchema) if it is not NULL. p->pSchema may be
84575 ** non-NULL if it is part of a view or trigger program definition. See
84576 ** sqlite3FixSrcList() for details.
84577 */
84578 SQLITE_PRIVATE Table *sqlite3LocateTableItem(
84579   Parse *pParse, 
84580   int isView, 
84581   struct SrcList_item *p
84582 ){
84583   const char *zDb;
84584   assert( p->pSchema==0 || p->zDatabase==0 );
84585   if( p->pSchema ){
84586     int iDb = sqlite3SchemaToIndex(pParse->db, p->pSchema);
84587     zDb = pParse->db->aDb[iDb].zName;
84588   }else{
84589     zDb = p->zDatabase;
84590   }
84591   return sqlite3LocateTable(pParse, isView, p->zName, zDb);
84592 }
84593 
84594 /*
84595 ** Locate the in-memory structure that describes 
84596 ** a particular index given the name of that index
84597 ** and the name of the database that contains the index.
84598 ** Return NULL if not found.
84599 **
84600 ** If zDatabase is 0, all databases are searched for the
84601 ** table and the first matching index is returned.  (No checking
84602 ** for duplicate index names is done.)  The search order is
84603 ** TEMP first, then MAIN, then any auxiliary databases added
84604 ** using the ATTACH command.
84605 */
84606 SQLITE_PRIVATE Index *sqlite3FindIndex(sqlite3 *db, const char *zName, const char *zDb){
84607   Index *p = 0;
84608   int i;
84609   int nName = sqlite3Strlen30(zName);
84610   /* All mutexes are required for schema access.  Make sure we hold them. */
84611   assert( zDb!=0 || sqlite3BtreeHoldsAllMutexes(db) );
84612   for(i=OMIT_TEMPDB; i<db->nDb; i++){
84613     int j = (i<2) ? i^1 : i;  /* Search TEMP before MAIN */
84614     Schema *pSchema = db->aDb[j].pSchema;
84615     assert( pSchema );
84616     if( zDb && sqlite3StrICmp(zDb, db->aDb[j].zName) ) continue;
84617     assert( sqlite3SchemaMutexHeld(db, j, 0) );
84618     p = sqlite3HashFind(&pSchema->idxHash, zName, nName);
84619     if( p ) break;
84620   }
84621   return p;
84622 }
84623 
84624 /*
84625 ** Reclaim the memory used by an index
84626 */
84627 static void freeIndex(sqlite3 *db, Index *p){
84628 #ifndef SQLITE_OMIT_ANALYZE
84629   sqlite3DeleteIndexSamples(db, p);
84630 #endif
84631   if( db==0 || db->pnBytesFreed==0 ) sqlite3KeyInfoUnref(p->pKeyInfo);
84632   sqlite3ExprDelete(db, p->pPartIdxWhere);
84633   sqlite3DbFree(db, p->zColAff);
84634   if( p->isResized ) sqlite3DbFree(db, p->azColl);
84635   sqlite3DbFree(db, p);
84636 }
84637 
84638 /*
84639 ** For the index called zIdxName which is found in the database iDb,
84640 ** unlike that index from its Table then remove the index from
84641 ** the index hash table and free all memory structures associated
84642 ** with the index.
84643 */
84644 SQLITE_PRIVATE void sqlite3UnlinkAndDeleteIndex(sqlite3 *db, int iDb, const char *zIdxName){
84645   Index *pIndex;
84646   int len;
84647   Hash *pHash;
84648 
84649   assert( sqlite3SchemaMutexHeld(db, iDb, 0) );
84650   pHash = &db->aDb[iDb].pSchema->idxHash;
84651   len = sqlite3Strlen30(zIdxName);
84652   pIndex = sqlite3HashInsert(pHash, zIdxName, len, 0);
84653   if( ALWAYS(pIndex) ){
84654     if( pIndex->pTable->pIndex==pIndex ){
84655       pIndex->pTable->pIndex = pIndex->pNext;
84656     }else{
84657       Index *p;
84658       /* Justification of ALWAYS();  The index must be on the list of
84659       ** indices. */
84660       p = pIndex->pTable->pIndex;
84661       while( ALWAYS(p) && p->pNext!=pIndex ){ p = p->pNext; }
84662       if( ALWAYS(p && p->pNext==pIndex) ){
84663         p->pNext = pIndex->pNext;
84664       }
84665     }
84666     freeIndex(db, pIndex);
84667   }
84668   db->flags |= SQLITE_InternChanges;
84669 }
84670 
84671 /*
84672 ** Look through the list of open database files in db->aDb[] and if
84673 ** any have been closed, remove them from the list.  Reallocate the
84674 ** db->aDb[] structure to a smaller size, if possible.
84675 **
84676 ** Entry 0 (the "main" database) and entry 1 (the "temp" database)
84677 ** are never candidates for being collapsed.
84678 */
84679 SQLITE_PRIVATE void sqlite3CollapseDatabaseArray(sqlite3 *db){
84680   int i, j;
84681   for(i=j=2; i<db->nDb; i++){
84682     struct Db *pDb = &db->aDb[i];
84683     if( pDb->pBt==0 ){
84684       sqlite3DbFree(db, pDb->zName);
84685       pDb->zName = 0;
84686       continue;
84687     }
84688     if( j<i ){
84689       db->aDb[j] = db->aDb[i];
84690     }
84691     j++;
84692   }
84693   memset(&db->aDb[j], 0, (db->nDb-j)*sizeof(db->aDb[j]));
84694   db->nDb = j;
84695   if( db->nDb<=2 && db->aDb!=db->aDbStatic ){
84696     memcpy(db->aDbStatic, db->aDb, 2*sizeof(db->aDb[0]));
84697     sqlite3DbFree(db, db->aDb);
84698     db->aDb = db->aDbStatic;
84699   }
84700 }
84701 
84702 /*
84703 ** Reset the schema for the database at index iDb.  Also reset the
84704 ** TEMP schema.
84705 */
84706 SQLITE_PRIVATE void sqlite3ResetOneSchema(sqlite3 *db, int iDb){
84707   Db *pDb;
84708   assert( iDb<db->nDb );
84709 
84710   /* Case 1:  Reset the single schema identified by iDb */
84711   pDb = &db->aDb[iDb];
84712   assert( sqlite3SchemaMutexHeld(db, iDb, 0) );
84713   assert( pDb->pSchema!=0 );
84714   sqlite3SchemaClear(pDb->pSchema);
84715 
84716   /* If any database other than TEMP is reset, then also reset TEMP
84717   ** since TEMP might be holding triggers that reference tables in the
84718   ** other database.
84719   */
84720   if( iDb!=1 ){
84721     pDb = &db->aDb[1];
84722     assert( pDb->pSchema!=0 );
84723     sqlite3SchemaClear(pDb->pSchema);
84724   }
84725   return;
84726 }
84727 
84728 /*
84729 ** Erase all schema information from all attached databases (including
84730 ** "main" and "temp") for a single database connection.
84731 */
84732 SQLITE_PRIVATE void sqlite3ResetAllSchemasOfConnection(sqlite3 *db){
84733   int i;
84734   sqlite3BtreeEnterAll(db);
84735   for(i=0; i<db->nDb; i++){
84736     Db *pDb = &db->aDb[i];
84737     if( pDb->pSchema ){
84738       sqlite3SchemaClear(pDb->pSchema);
84739     }
84740   }
84741   db->flags &= ~SQLITE_InternChanges;
84742   sqlite3VtabUnlockList(db);
84743   sqlite3BtreeLeaveAll(db);
84744   sqlite3CollapseDatabaseArray(db);
84745 }
84746 
84747 /*
84748 ** This routine is called when a commit occurs.
84749 */
84750 SQLITE_PRIVATE void sqlite3CommitInternalChanges(sqlite3 *db){
84751   db->flags &= ~SQLITE_InternChanges;
84752 }
84753 
84754 /*
84755 ** Delete memory allocated for the column names of a table or view (the
84756 ** Table.aCol[] array).
84757 */
84758 static void sqliteDeleteColumnNames(sqlite3 *db, Table *pTable){
84759   int i;
84760   Column *pCol;
84761   assert( pTable!=0 );
84762   if( (pCol = pTable->aCol)!=0 ){
84763     for(i=0; i<pTable->nCol; i++, pCol++){
84764       sqlite3DbFree(db, pCol->zName);
84765       sqlite3ExprDelete(db, pCol->pDflt);
84766       sqlite3DbFree(db, pCol->zDflt);
84767       sqlite3DbFree(db, pCol->zType);
84768       sqlite3DbFree(db, pCol->zColl);
84769     }
84770     sqlite3DbFree(db, pTable->aCol);
84771   }
84772 }
84773 
84774 /*
84775 ** Remove the memory data structures associated with the given
84776 ** Table.  No changes are made to disk by this routine.
84777 **
84778 ** This routine just deletes the data structure.  It does not unlink
84779 ** the table data structure from the hash table.  But it does destroy
84780 ** memory structures of the indices and foreign keys associated with 
84781 ** the table.
84782 **
84783 ** The db parameter is optional.  It is needed if the Table object 
84784 ** contains lookaside memory.  (Table objects in the schema do not use
84785 ** lookaside memory, but some ephemeral Table objects do.)  Or the
84786 ** db parameter can be used with db->pnBytesFreed to measure the memory
84787 ** used by the Table object.
84788 */
84789 SQLITE_PRIVATE void sqlite3DeleteTable(sqlite3 *db, Table *pTable){
84790   Index *pIndex, *pNext;
84791   TESTONLY( int nLookaside; ) /* Used to verify lookaside not used for schema */
84792 
84793   assert( !pTable || pTable->nRef>0 );
84794 
84795   /* Do not delete the table until the reference count reaches zero. */
84796   if( !pTable ) return;
84797   if( ((!db || db->pnBytesFreed==0) && (--pTable->nRef)>0) ) return;
84798 
84799   /* Record the number of outstanding lookaside allocations in schema Tables
84800   ** prior to doing any free() operations.  Since schema Tables do not use
84801   ** lookaside, this number should not change. */
84802   TESTONLY( nLookaside = (db && (pTable->tabFlags & TF_Ephemeral)==0) ?
84803                          db->lookaside.nOut : 0 );
84804 
84805   /* Delete all indices associated with this table. */
84806   for(pIndex = pTable->pIndex; pIndex; pIndex=pNext){
84807     pNext = pIndex->pNext;
84808     assert( pIndex->pSchema==pTable->pSchema );
84809     if( !db || db->pnBytesFreed==0 ){
84810       char *zName = pIndex->zName; 
84811       TESTONLY ( Index *pOld = ) sqlite3HashInsert(
84812          &pIndex->pSchema->idxHash, zName, sqlite3Strlen30(zName), 0
84813       );
84814       assert( db==0 || sqlite3SchemaMutexHeld(db, 0, pIndex->pSchema) );
84815       assert( pOld==pIndex || pOld==0 );
84816     }
84817     freeIndex(db, pIndex);
84818   }
84819 
84820   /* Delete any foreign keys attached to this table. */
84821   sqlite3FkDelete(db, pTable);
84822 
84823   /* Delete the Table structure itself.
84824   */
84825   sqliteDeleteColumnNames(db, pTable);
84826   sqlite3DbFree(db, pTable->zName);
84827   sqlite3DbFree(db, pTable->zColAff);
84828   sqlite3SelectDelete(db, pTable->pSelect);
84829 #ifndef SQLITE_OMIT_CHECK
84830   sqlite3ExprListDelete(db, pTable->pCheck);
84831 #endif
84832 #ifndef SQLITE_OMIT_VIRTUALTABLE
84833   sqlite3VtabClear(db, pTable);
84834 #endif
84835   sqlite3DbFree(db, pTable);
84836 
84837   /* Verify that no lookaside memory was used by schema tables */
84838   assert( nLookaside==0 || nLookaside==db->lookaside.nOut );
84839 }
84840 
84841 /*
84842 ** Unlink the given table from the hash tables and the delete the
84843 ** table structure with all its indices and foreign keys.
84844 */
84845 SQLITE_PRIVATE void sqlite3UnlinkAndDeleteTable(sqlite3 *db, int iDb, const char *zTabName){
84846   Table *p;
84847   Db *pDb;
84848 
84849   assert( db!=0 );
84850   assert( iDb>=0 && iDb<db->nDb );
84851   assert( zTabName );
84852   assert( sqlite3SchemaMutexHeld(db, iDb, 0) );
84853   testcase( zTabName[0]==0 );  /* Zero-length table names are allowed */
84854   pDb = &db->aDb[iDb];
84855   p = sqlite3HashInsert(&pDb->pSchema->tblHash, zTabName,
84856                         sqlite3Strlen30(zTabName),0);
84857   sqlite3DeleteTable(db, p);
84858   db->flags |= SQLITE_InternChanges;
84859 }
84860 
84861 /*
84862 ** Given a token, return a string that consists of the text of that
84863 ** token.  Space to hold the returned string
84864 ** is obtained from sqliteMalloc() and must be freed by the calling
84865 ** function.
84866 **
84867 ** Any quotation marks (ex:  "name", 'name', [name], or `name`) that
84868 ** surround the body of the token are removed.
84869 **
84870 ** Tokens are often just pointers into the original SQL text and so
84871 ** are not \000 terminated and are not persistent.  The returned string
84872 ** is \000 terminated and is persistent.
84873 */
84874 SQLITE_PRIVATE char *sqlite3NameFromToken(sqlite3 *db, Token *pName){
84875   char *zName;
84876   if( pName ){
84877     zName = sqlite3DbStrNDup(db, (char*)pName->z, pName->n);
84878     sqlite3Dequote(zName);
84879   }else{
84880     zName = 0;
84881   }
84882   return zName;
84883 }
84884 
84885 /*
84886 ** Open the sqlite_master table stored in database number iDb for
84887 ** writing. The table is opened using cursor 0.
84888 */
84889 SQLITE_PRIVATE void sqlite3OpenMasterTable(Parse *p, int iDb){
84890   Vdbe *v = sqlite3GetVdbe(p);
84891   sqlite3TableLock(p, iDb, MASTER_ROOT, 1, SCHEMA_TABLE(iDb));
84892   sqlite3VdbeAddOp4Int(v, OP_OpenWrite, 0, MASTER_ROOT, iDb, 5);
84893   if( p->nTab==0 ){
84894     p->nTab = 1;
84895   }
84896 }
84897 
84898 /*
84899 ** Parameter zName points to a nul-terminated buffer containing the name
84900 ** of a database ("main", "temp" or the name of an attached db). This
84901 ** function returns the index of the named database in db->aDb[], or
84902 ** -1 if the named db cannot be found.
84903 */
84904 SQLITE_PRIVATE int sqlite3FindDbName(sqlite3 *db, const char *zName){
84905   int i = -1;         /* Database number */
84906   if( zName ){
84907     Db *pDb;
84908     int n = sqlite3Strlen30(zName);
84909     for(i=(db->nDb-1), pDb=&db->aDb[i]; i>=0; i--, pDb--){
84910       if( (!OMIT_TEMPDB || i!=1 ) && n==sqlite3Strlen30(pDb->zName) && 
84911           0==sqlite3StrICmp(pDb->zName, zName) ){
84912         break;
84913       }
84914     }
84915   }
84916   return i;
84917 }
84918 
84919 /*
84920 ** The token *pName contains the name of a database (either "main" or
84921 ** "temp" or the name of an attached db). This routine returns the
84922 ** index of the named database in db->aDb[], or -1 if the named db 
84923 ** does not exist.
84924 */
84925 SQLITE_PRIVATE int sqlite3FindDb(sqlite3 *db, Token *pName){
84926   int i;                               /* Database number */
84927   char *zName;                         /* Name we are searching for */
84928   zName = sqlite3NameFromToken(db, pName);
84929   i = sqlite3FindDbName(db, zName);
84930   sqlite3DbFree(db, zName);
84931   return i;
84932 }
84933 
84934 /* The table or view or trigger name is passed to this routine via tokens
84935 ** pName1 and pName2. If the table name was fully qualified, for example:
84936 **
84937 ** CREATE TABLE xxx.yyy (...);
84938 ** 
84939 ** Then pName1 is set to "xxx" and pName2 "yyy". On the other hand if
84940 ** the table name is not fully qualified, i.e.:
84941 **
84942 ** CREATE TABLE yyy(...);
84943 **
84944 ** Then pName1 is set to "yyy" and pName2 is "".
84945 **
84946 ** This routine sets the *ppUnqual pointer to point at the token (pName1 or
84947 ** pName2) that stores the unqualified table name.  The index of the
84948 ** database "xxx" is returned.
84949 */
84950 SQLITE_PRIVATE int sqlite3TwoPartName(
84951   Parse *pParse,      /* Parsing and code generating context */
84952   Token *pName1,      /* The "xxx" in the name "xxx.yyy" or "xxx" */
84953   Token *pName2,      /* The "yyy" in the name "xxx.yyy" */
84954   Token **pUnqual     /* Write the unqualified object name here */
84955 ){
84956   int iDb;                    /* Database holding the object */
84957   sqlite3 *db = pParse->db;
84958 
84959   if( ALWAYS(pName2!=0) && pName2->n>0 ){
84960     if( db->init.busy ) {
84961       sqlite3ErrorMsg(pParse, "corrupt database");
84962       pParse->nErr++;
84963       return -1;
84964     }
84965     *pUnqual = pName2;
84966     iDb = sqlite3FindDb(db, pName1);
84967     if( iDb<0 ){
84968       sqlite3ErrorMsg(pParse, "unknown database %T", pName1);
84969       pParse->nErr++;
84970       return -1;
84971     }
84972   }else{
84973     assert( db->init.iDb==0 || db->init.busy );
84974     iDb = db->init.iDb;
84975     *pUnqual = pName1;
84976   }
84977   return iDb;
84978 }
84979 
84980 /*
84981 ** This routine is used to check if the UTF-8 string zName is a legal
84982 ** unqualified name for a new schema object (table, index, view or
84983 ** trigger). All names are legal except those that begin with the string
84984 ** "sqlite_" (in upper, lower or mixed case). This portion of the namespace
84985 ** is reserved for internal use.
84986 */
84987 SQLITE_PRIVATE int sqlite3CheckObjectName(Parse *pParse, const char *zName){
84988   if( !pParse->db->init.busy && pParse->nested==0 
84989           && (pParse->db->flags & SQLITE_WriteSchema)==0
84990           && 0==sqlite3StrNICmp(zName, "sqlite_", 7) ){
84991     sqlite3ErrorMsg(pParse, "object name reserved for internal use: %s", zName);
84992     return SQLITE_ERROR;
84993   }
84994   return SQLITE_OK;
84995 }
84996 
84997 /*
84998 ** Return the PRIMARY KEY index of a table
84999 */
85000 SQLITE_PRIVATE Index *sqlite3PrimaryKeyIndex(Table *pTab){
85001   Index *p;
85002   for(p=pTab->pIndex; p && p->autoIndex!=2; p=p->pNext){}
85003   return p;
85004 }
85005 
85006 /*
85007 ** Return the column of index pIdx that corresponds to table
85008 ** column iCol.  Return -1 if not found.
85009 */
85010 SQLITE_PRIVATE i16 sqlite3ColumnOfIndex(Index *pIdx, i16 iCol){
85011   int i;
85012   for(i=0; i<pIdx->nColumn; i++){
85013     if( iCol==pIdx->aiColumn[i] ) return i;
85014   }
85015   return -1;
85016 }
85017 
85018 /*
85019 ** Begin constructing a new table representation in memory.  This is
85020 ** the first of several action routines that get called in response
85021 ** to a CREATE TABLE statement.  In particular, this routine is called
85022 ** after seeing tokens "CREATE" and "TABLE" and the table name. The isTemp
85023 ** flag is true if the table should be stored in the auxiliary database
85024 ** file instead of in the main database file.  This is normally the case
85025 ** when the "TEMP" or "TEMPORARY" keyword occurs in between
85026 ** CREATE and TABLE.
85027 **
85028 ** The new table record is initialized and put in pParse->pNewTable.
85029 ** As more of the CREATE TABLE statement is parsed, additional action
85030 ** routines will be called to add more information to this record.
85031 ** At the end of the CREATE TABLE statement, the sqlite3EndTable() routine
85032 ** is called to complete the construction of the new table record.
85033 */
85034 SQLITE_PRIVATE void sqlite3StartTable(
85035   Parse *pParse,   /* Parser context */
85036   Token *pName1,   /* First part of the name of the table or view */
85037   Token *pName2,   /* Second part of the name of the table or view */
85038   int isTemp,      /* True if this is a TEMP table */
85039   int isView,      /* True if this is a VIEW */
85040   int isVirtual,   /* True if this is a VIRTUAL table */
85041   int noErr        /* Do nothing if table already exists */
85042 ){
85043   Table *pTable;
85044   char *zName = 0; /* The name of the new table */
85045   sqlite3 *db = pParse->db;
85046   Vdbe *v;
85047   int iDb;         /* Database number to create the table in */
85048   Token *pName;    /* Unqualified name of the table to create */
85049 
85050   /* The table or view name to create is passed to this routine via tokens
85051   ** pName1 and pName2. If the table name was fully qualified, for example:
85052   **
85053   ** CREATE TABLE xxx.yyy (...);
85054   ** 
85055   ** Then pName1 is set to "xxx" and pName2 "yyy". On the other hand if
85056   ** the table name is not fully qualified, i.e.:
85057   **
85058   ** CREATE TABLE yyy(...);
85059   **
85060   ** Then pName1 is set to "yyy" and pName2 is "".
85061   **
85062   ** The call below sets the pName pointer to point at the token (pName1 or
85063   ** pName2) that stores the unqualified table name. The variable iDb is
85064   ** set to the index of the database that the table or view is to be
85065   ** created in.
85066   */
85067   iDb = sqlite3TwoPartName(pParse, pName1, pName2, &pName);
85068   if( iDb<0 ) return;
85069   if( !OMIT_TEMPDB && isTemp && pName2->n>0 && iDb!=1 ){
85070     /* If creating a temp table, the name may not be qualified. Unless 
85071     ** the database name is "temp" anyway.  */
85072     sqlite3ErrorMsg(pParse, "temporary table name must be unqualified");
85073     return;
85074   }
85075   if( !OMIT_TEMPDB && isTemp ) iDb = 1;
85076 
85077   pParse->sNameToken = *pName;
85078   zName = sqlite3NameFromToken(db, pName);
85079   if( zName==0 ) return;
85080   if( SQLITE_OK!=sqlite3CheckObjectName(pParse, zName) ){
85081     goto begin_table_error;
85082   }
85083   if( db->init.iDb==1 ) isTemp = 1;
85084 #ifndef SQLITE_OMIT_AUTHORIZATION
85085   assert( (isTemp & 1)==isTemp );
85086   {
85087     int code;
85088     char *zDb = db->aDb[iDb].zName;
85089     if( sqlite3AuthCheck(pParse, SQLITE_INSERT, SCHEMA_TABLE(isTemp), 0, zDb) ){
85090       goto begin_table_error;
85091     }
85092     if( isView ){
85093       if( !OMIT_TEMPDB && isTemp ){
85094         code = SQLITE_CREATE_TEMP_VIEW;
85095       }else{
85096         code = SQLITE_CREATE_VIEW;
85097       }
85098     }else{
85099       if( !OMIT_TEMPDB && isTemp ){
85100         code = SQLITE_CREATE_TEMP_TABLE;
85101       }else{
85102         code = SQLITE_CREATE_TABLE;
85103       }
85104     }
85105     if( !isVirtual && sqlite3AuthCheck(pParse, code, zName, 0, zDb) ){
85106       goto begin_table_error;
85107     }
85108   }
85109 #endif
85110 
85111   /* Make sure the new table name does not collide with an existing
85112   ** index or table name in the same database.  Issue an error message if
85113   ** it does. The exception is if the statement being parsed was passed
85114   ** to an sqlite3_declare_vtab() call. In that case only the column names
85115   ** and types will be used, so there is no need to test for namespace
85116   ** collisions.
85117   */
85118   if( !IN_DECLARE_VTAB ){
85119     char *zDb = db->aDb[iDb].zName;
85120     if( SQLITE_OK!=sqlite3ReadSchema(pParse) ){
85121       goto begin_table_error;
85122     }
85123     pTable = sqlite3FindTable(db, zName, zDb);
85124     if( pTable ){
85125       if( !noErr ){
85126         sqlite3ErrorMsg(pParse, "table %T already exists", pName);
85127       }else{
85128         assert( !db->init.busy );
85129         sqlite3CodeVerifySchema(pParse, iDb);
85130       }
85131       goto begin_table_error;
85132     }
85133     if( sqlite3FindIndex(db, zName, zDb)!=0 ){
85134       sqlite3ErrorMsg(pParse, "there is already an index named %s", zName);
85135       goto begin_table_error;
85136     }
85137   }
85138 
85139   pTable = sqlite3DbMallocZero(db, sizeof(Table));
85140   if( pTable==0 ){
85141     db->mallocFailed = 1;
85142     pParse->rc = SQLITE_NOMEM;
85143     pParse->nErr++;
85144     goto begin_table_error;
85145   }
85146   pTable->zName = zName;
85147   pTable->iPKey = -1;
85148   pTable->pSchema = db->aDb[iDb].pSchema;
85149   pTable->nRef = 1;
85150   pTable->nRowEst = 1048576;
85151   assert( pParse->pNewTable==0 );
85152   pParse->pNewTable = pTable;
85153 
85154   /* If this is the magic sqlite_sequence table used by autoincrement,
85155   ** then record a pointer to this table in the main database structure
85156   ** so that INSERT can find the table easily.
85157   */
85158 #ifndef SQLITE_OMIT_AUTOINCREMENT
85159   if( !pParse->nested && strcmp(zName, "sqlite_sequence")==0 ){
85160     assert( sqlite3SchemaMutexHeld(db, iDb, 0) );
85161     pTable->pSchema->pSeqTab = pTable;
85162   }
85163 #endif
85164 
85165   /* Begin generating the code that will insert the table record into
85166   ** the SQLITE_MASTER table.  Note in particular that we must go ahead
85167   ** and allocate the record number for the table entry now.  Before any
85168   ** PRIMARY KEY or UNIQUE keywords are parsed.  Those keywords will cause
85169   ** indices to be created and the table record must come before the 
85170   ** indices.  Hence, the record number for the table must be allocated
85171   ** now.
85172   */
85173   if( !db->init.busy && (v = sqlite3GetVdbe(pParse))!=0 ){
85174     int j1;
85175     int fileFormat;
85176     int reg1, reg2, reg3;
85177     sqlite3BeginWriteOperation(pParse, 0, iDb);
85178 
85179 #ifndef SQLITE_OMIT_VIRTUALTABLE
85180     if( isVirtual ){
85181       sqlite3VdbeAddOp0(v, OP_VBegin);
85182     }
85183 #endif
85184 
85185     /* If the file format and encoding in the database have not been set, 
85186     ** set them now.
85187     */
85188     reg1 = pParse->regRowid = ++pParse->nMem;
85189     reg2 = pParse->regRoot = ++pParse->nMem;
85190     reg3 = ++pParse->nMem;
85191     sqlite3VdbeAddOp3(v, OP_ReadCookie, iDb, reg3, BTREE_FILE_FORMAT);
85192     sqlite3VdbeUsesBtree(v, iDb);
85193     j1 = sqlite3VdbeAddOp1(v, OP_If, reg3);
85194     fileFormat = (db->flags & SQLITE_LegacyFileFmt)!=0 ?
85195                   1 : SQLITE_MAX_FILE_FORMAT;
85196     sqlite3VdbeAddOp2(v, OP_Integer, fileFormat, reg3);
85197     sqlite3VdbeAddOp3(v, OP_SetCookie, iDb, BTREE_FILE_FORMAT, reg3);
85198     sqlite3VdbeAddOp2(v, OP_Integer, ENC(db), reg3);
85199     sqlite3VdbeAddOp3(v, OP_SetCookie, iDb, BTREE_TEXT_ENCODING, reg3);
85200     sqlite3VdbeJumpHere(v, j1);
85201 
85202     /* This just creates a place-holder record in the sqlite_master table.
85203     ** The record created does not contain anything yet.  It will be replaced
85204     ** by the real entry in code generated at sqlite3EndTable().
85205     **
85206     ** The rowid for the new entry is left in register pParse->regRowid.
85207     ** The root page number of the new table is left in reg pParse->regRoot.
85208     ** The rowid and root page number values are needed by the code that
85209     ** sqlite3EndTable will generate.
85210     */
85211 #if !defined(SQLITE_OMIT_VIEW) || !defined(SQLITE_OMIT_VIRTUALTABLE)
85212     if( isView || isVirtual ){
85213       sqlite3VdbeAddOp2(v, OP_Integer, 0, reg2);
85214     }else
85215 #endif
85216     {
85217       pParse->addrCrTab = sqlite3VdbeAddOp2(v, OP_CreateTable, iDb, reg2);
85218     }
85219     sqlite3OpenMasterTable(pParse, iDb);
85220     sqlite3VdbeAddOp2(v, OP_NewRowid, 0, reg1);
85221     sqlite3VdbeAddOp2(v, OP_Null, 0, reg3);
85222     sqlite3VdbeAddOp3(v, OP_Insert, 0, reg3, reg1);
85223     sqlite3VdbeChangeP5(v, OPFLAG_APPEND);
85224     sqlite3VdbeAddOp0(v, OP_Close);
85225   }
85226 
85227   /* Normal (non-error) return. */
85228   return;
85229 
85230   /* If an error occurs, we jump here */
85231 begin_table_error:
85232   sqlite3DbFree(db, zName);
85233   return;
85234 }
85235 
85236 /*
85237 ** This macro is used to compare two strings in a case-insensitive manner.
85238 ** It is slightly faster than calling sqlite3StrICmp() directly, but
85239 ** produces larger code.
85240 **
85241 ** WARNING: This macro is not compatible with the strcmp() family. It
85242 ** returns true if the two strings are equal, otherwise false.
85243 */
85244 #define STRICMP(x, y) (\
85245 sqlite3UpperToLower[*(unsigned char *)(x)]==   \
85246 sqlite3UpperToLower[*(unsigned char *)(y)]     \
85247 && sqlite3StrICmp((x)+1,(y)+1)==0 )
85248 
85249 /*
85250 ** Add a new column to the table currently being constructed.
85251 **
85252 ** The parser calls this routine once for each column declaration
85253 ** in a CREATE TABLE statement.  sqlite3StartTable() gets called
85254 ** first to get things going.  Then this routine is called for each
85255 ** column.
85256 */
85257 SQLITE_PRIVATE void sqlite3AddColumn(Parse *pParse, Token *pName){
85258   Table *p;
85259   int i;
85260   char *z;
85261   Column *pCol;
85262   sqlite3 *db = pParse->db;
85263   if( (p = pParse->pNewTable)==0 ) return;
85264 #if SQLITE_MAX_COLUMN
85265   if( p->nCol+1>db->aLimit[SQLITE_LIMIT_COLUMN] ){
85266     sqlite3ErrorMsg(pParse, "too many columns on %s", p->zName);
85267     return;
85268   }
85269 #endif
85270   z = sqlite3NameFromToken(db, pName);
85271   if( z==0 ) return;
85272   for(i=0; i<p->nCol; i++){
85273     if( STRICMP(z, p->aCol[i].zName) ){
85274       sqlite3ErrorMsg(pParse, "duplicate column name: %s", z);
85275       sqlite3DbFree(db, z);
85276       return;
85277     }
85278   }
85279   if( (p->nCol & 0x7)==0 ){
85280     Column *aNew;
85281     aNew = sqlite3DbRealloc(db,p->aCol,(p->nCol+8)*sizeof(p->aCol[0]));
85282     if( aNew==0 ){
85283       sqlite3DbFree(db, z);
85284       return;
85285     }
85286     p->aCol = aNew;
85287   }
85288   pCol = &p->aCol[p->nCol];
85289   memset(pCol, 0, sizeof(p->aCol[0]));
85290   pCol->zName = z;
85291  
85292   /* If there is no type specified, columns have the default affinity
85293   ** 'NONE'. If there is a type specified, then sqlite3AddColumnType() will
85294   ** be called next to set pCol->affinity correctly.
85295   */
85296   pCol->affinity = SQLITE_AFF_NONE;
85297   pCol->szEst = 1;
85298   p->nCol++;
85299 }
85300 
85301 /*
85302 ** This routine is called by the parser while in the middle of
85303 ** parsing a CREATE TABLE statement.  A "NOT NULL" constraint has
85304 ** been seen on a column.  This routine sets the notNull flag on
85305 ** the column currently under construction.
85306 */
85307 SQLITE_PRIVATE void sqlite3AddNotNull(Parse *pParse, int onError){
85308   Table *p;
85309   p = pParse->pNewTable;
85310   if( p==0 || NEVER(p->nCol<1) ) return;
85311   p->aCol[p->nCol-1].notNull = (u8)onError;
85312 }
85313 
85314 /*
85315 ** Scan the column type name zType (length nType) and return the
85316 ** associated affinity type.
85317 **
85318 ** This routine does a case-independent search of zType for the 
85319 ** substrings in the following table. If one of the substrings is
85320 ** found, the corresponding affinity is returned. If zType contains
85321 ** more than one of the substrings, entries toward the top of 
85322 ** the table take priority. For example, if zType is 'BLOBINT', 
85323 ** SQLITE_AFF_INTEGER is returned.
85324 **
85325 ** Substring     | Affinity
85326 ** --------------------------------
85327 ** 'INT'         | SQLITE_AFF_INTEGER
85328 ** 'CHAR'        | SQLITE_AFF_TEXT
85329 ** 'CLOB'        | SQLITE_AFF_TEXT
85330 ** 'TEXT'        | SQLITE_AFF_TEXT
85331 ** 'BLOB'        | SQLITE_AFF_NONE
85332 ** 'REAL'        | SQLITE_AFF_REAL
85333 ** 'FLOA'        | SQLITE_AFF_REAL
85334 ** 'DOUB'        | SQLITE_AFF_REAL
85335 **
85336 ** If none of the substrings in the above table are found,
85337 ** SQLITE_AFF_NUMERIC is returned.
85338 */
85339 SQLITE_PRIVATE char sqlite3AffinityType(const char *zIn, u8 *pszEst){
85340   u32 h = 0;
85341   char aff = SQLITE_AFF_NUMERIC;
85342   const char *zChar = 0;
85343 
85344   if( zIn==0 ) return aff;
85345   while( zIn[0] ){
85346     h = (h<<8) + sqlite3UpperToLower[(*zIn)&0xff];
85347     zIn++;
85348     if( h==(('c'<<24)+('h'<<16)+('a'<<8)+'r') ){             /* CHAR */
85349       aff = SQLITE_AFF_TEXT;
85350       zChar = zIn;
85351     }else if( h==(('c'<<24)+('l'<<16)+('o'<<8)+'b') ){       /* CLOB */
85352       aff = SQLITE_AFF_TEXT;
85353     }else if( h==(('t'<<24)+('e'<<16)+('x'<<8)+'t') ){       /* TEXT */
85354       aff = SQLITE_AFF_TEXT;
85355     }else if( h==(('b'<<24)+('l'<<16)+('o'<<8)+'b')          /* BLOB */
85356         && (aff==SQLITE_AFF_NUMERIC || aff==SQLITE_AFF_REAL) ){
85357       aff = SQLITE_AFF_NONE;
85358       if( zIn[0]=='(' ) zChar = zIn;
85359 #ifndef SQLITE_OMIT_FLOATING_POINT
85360     }else if( h==(('r'<<24)+('e'<<16)+('a'<<8)+'l')          /* REAL */
85361         && aff==SQLITE_AFF_NUMERIC ){
85362       aff = SQLITE_AFF_REAL;
85363     }else if( h==(('f'<<24)+('l'<<16)+('o'<<8)+'a')          /* FLOA */
85364         && aff==SQLITE_AFF_NUMERIC ){
85365       aff = SQLITE_AFF_REAL;
85366     }else if( h==(('d'<<24)+('o'<<16)+('u'<<8)+'b')          /* DOUB */
85367         && aff==SQLITE_AFF_NUMERIC ){
85368       aff = SQLITE_AFF_REAL;
85369 #endif
85370     }else if( (h&0x00FFFFFF)==(('i'<<16)+('n'<<8)+'t') ){    /* INT */
85371       aff = SQLITE_AFF_INTEGER;
85372       break;
85373     }
85374   }
85375 
85376   /* If pszEst is not NULL, store an estimate of the field size.  The
85377   ** estimate is scaled so that the size of an integer is 1.  */
85378   if( pszEst ){
85379     *pszEst = 1;   /* default size is approx 4 bytes */
85380     if( aff<=SQLITE_AFF_NONE ){
85381       if( zChar ){
85382         while( zChar[0] ){
85383           if( sqlite3Isdigit(zChar[0]) ){
85384             int v = 0;
85385             sqlite3GetInt32(zChar, &v);
85386             v = v/4 + 1;
85387             if( v>255 ) v = 255;
85388             *pszEst = v; /* BLOB(k), VARCHAR(k), CHAR(k) -> r=(k/4+1) */
85389             break;
85390           }
85391           zChar++;
85392         }
85393       }else{
85394         *pszEst = 5;   /* BLOB, TEXT, CLOB -> r=5  (approx 20 bytes)*/
85395       }
85396     }
85397   }
85398   return aff;
85399 }
85400 
85401 /*
85402 ** This routine is called by the parser while in the middle of
85403 ** parsing a CREATE TABLE statement.  The pFirst token is the first
85404 ** token in the sequence of tokens that describe the type of the
85405 ** column currently under construction.   pLast is the last token
85406 ** in the sequence.  Use this information to construct a string
85407 ** that contains the typename of the column and store that string
85408 ** in zType.
85409 */ 
85410 SQLITE_PRIVATE void sqlite3AddColumnType(Parse *pParse, Token *pType){
85411   Table *p;
85412   Column *pCol;
85413 
85414   p = pParse->pNewTable;
85415   if( p==0 || NEVER(p->nCol<1) ) return;
85416   pCol = &p->aCol[p->nCol-1];
85417   assert( pCol->zType==0 );
85418   pCol->zType = sqlite3NameFromToken(pParse->db, pType);
85419   pCol->affinity = sqlite3AffinityType(pCol->zType, &pCol->szEst);
85420 }
85421 
85422 /*
85423 ** The expression is the default value for the most recently added column
85424 ** of the table currently under construction.
85425 **
85426 ** Default value expressions must be constant.  Raise an exception if this
85427 ** is not the case.
85428 **
85429 ** This routine is called by the parser while in the middle of
85430 ** parsing a CREATE TABLE statement.
85431 */
85432 SQLITE_PRIVATE void sqlite3AddDefaultValue(Parse *pParse, ExprSpan *pSpan){
85433   Table *p;
85434   Column *pCol;
85435   sqlite3 *db = pParse->db;
85436   p = pParse->pNewTable;
85437   if( p!=0 ){
85438     pCol = &(p->aCol[p->nCol-1]);
85439     if( !sqlite3ExprIsConstantOrFunction(pSpan->pExpr) ){
85440       sqlite3ErrorMsg(pParse, "default value of column [%s] is not constant",
85441           pCol->zName);
85442     }else{
85443       /* A copy of pExpr is used instead of the original, as pExpr contains
85444       ** tokens that point to volatile memory. The 'span' of the expression
85445       ** is required by pragma table_info.
85446       */
85447       sqlite3ExprDelete(db, pCol->pDflt);
85448       pCol->pDflt = sqlite3ExprDup(db, pSpan->pExpr, EXPRDUP_REDUCE);
85449       sqlite3DbFree(db, pCol->zDflt);
85450       pCol->zDflt = sqlite3DbStrNDup(db, (char*)pSpan->zStart,
85451                                      (int)(pSpan->zEnd - pSpan->zStart));
85452     }
85453   }
85454   sqlite3ExprDelete(db, pSpan->pExpr);
85455 }
85456 
85457 /*
85458 ** Designate the PRIMARY KEY for the table.  pList is a list of names 
85459 ** of columns that form the primary key.  If pList is NULL, then the
85460 ** most recently added column of the table is the primary key.
85461 **
85462 ** A table can have at most one primary key.  If the table already has
85463 ** a primary key (and this is the second primary key) then create an
85464 ** error.
85465 **
85466 ** If the PRIMARY KEY is on a single column whose datatype is INTEGER,
85467 ** then we will try to use that column as the rowid.  Set the Table.iPKey
85468 ** field of the table under construction to be the index of the
85469 ** INTEGER PRIMARY KEY column.  Table.iPKey is set to -1 if there is
85470 ** no INTEGER PRIMARY KEY.
85471 **
85472 ** If the key is not an INTEGER PRIMARY KEY, then create a unique
85473 ** index for the key.  No index is created for INTEGER PRIMARY KEYs.
85474 */
85475 SQLITE_PRIVATE void sqlite3AddPrimaryKey(
85476   Parse *pParse,    /* Parsing context */
85477   ExprList *pList,  /* List of field names to be indexed */
85478   int onError,      /* What to do with a uniqueness conflict */
85479   int autoInc,      /* True if the AUTOINCREMENT keyword is present */
85480   int sortOrder     /* SQLITE_SO_ASC or SQLITE_SO_DESC */
85481 ){
85482   Table *pTab = pParse->pNewTable;
85483   char *zType = 0;
85484   int iCol = -1, i;
85485   int nTerm;
85486   if( pTab==0 || IN_DECLARE_VTAB ) goto primary_key_exit;
85487   if( pTab->tabFlags & TF_HasPrimaryKey ){
85488     sqlite3ErrorMsg(pParse, 
85489       "table \"%s\" has more than one primary key", pTab->zName);
85490     goto primary_key_exit;
85491   }
85492   pTab->tabFlags |= TF_HasPrimaryKey;
85493   if( pList==0 ){
85494     iCol = pTab->nCol - 1;
85495     pTab->aCol[iCol].colFlags |= COLFLAG_PRIMKEY;
85496     zType = pTab->aCol[iCol].zType;
85497     nTerm = 1;
85498   }else{
85499     nTerm = pList->nExpr;
85500     for(i=0; i<nTerm; i++){
85501       for(iCol=0; iCol<pTab->nCol; iCol++){
85502         if( sqlite3StrICmp(pList->a[i].zName, pTab->aCol[iCol].zName)==0 ){
85503           pTab->aCol[iCol].colFlags |= COLFLAG_PRIMKEY;
85504           zType = pTab->aCol[iCol].zType;
85505           break;
85506         }
85507       }
85508     }
85509   }
85510   if( nTerm==1
85511    && zType && sqlite3StrICmp(zType, "INTEGER")==0
85512    && sortOrder==SQLITE_SO_ASC
85513   ){
85514     pTab->iPKey = iCol;
85515     pTab->keyConf = (u8)onError;
85516     assert( autoInc==0 || autoInc==1 );
85517     pTab->tabFlags |= autoInc*TF_Autoincrement;
85518     if( pList ) pParse->iPkSortOrder = pList->a[0].sortOrder;
85519   }else if( autoInc ){
85520 #ifndef SQLITE_OMIT_AUTOINCREMENT
85521     sqlite3ErrorMsg(pParse, "AUTOINCREMENT is only allowed on an "
85522        "INTEGER PRIMARY KEY");
85523 #endif
85524   }else{
85525     Vdbe *v = pParse->pVdbe;
85526     Index *p;
85527     if( v ) pParse->addrSkipPK = sqlite3VdbeAddOp0(v, OP_Noop);
85528     p = sqlite3CreateIndex(pParse, 0, 0, 0, pList, onError, 0,
85529                            0, sortOrder, 0);
85530     if( p ){
85531       p->autoIndex = 2;
85532       if( v ) sqlite3VdbeJumpHere(v, pParse->addrSkipPK);
85533     }
85534     pList = 0;
85535   }
85536 
85537 primary_key_exit:
85538   sqlite3ExprListDelete(pParse->db, pList);
85539   return;
85540 }
85541 
85542 /*
85543 ** Add a new CHECK constraint to the table currently under construction.
85544 */
85545 SQLITE_PRIVATE void sqlite3AddCheckConstraint(
85546   Parse *pParse,    /* Parsing context */
85547   Expr *pCheckExpr  /* The check expression */
85548 ){
85549 #ifndef SQLITE_OMIT_CHECK
85550   Table *pTab = pParse->pNewTable;
85551   if( pTab && !IN_DECLARE_VTAB ){
85552     pTab->pCheck = sqlite3ExprListAppend(pParse, pTab->pCheck, pCheckExpr);
85553     if( pParse->constraintName.n ){
85554       sqlite3ExprListSetName(pParse, pTab->pCheck, &pParse->constraintName, 1);
85555     }
85556   }else
85557 #endif
85558   {
85559     sqlite3ExprDelete(pParse->db, pCheckExpr);
85560   }
85561 }
85562 
85563 /*
85564 ** Set the collation function of the most recently parsed table column
85565 ** to the CollSeq given.
85566 */
85567 SQLITE_PRIVATE void sqlite3AddCollateType(Parse *pParse, Token *pToken){
85568   Table *p;
85569   int i;
85570   char *zColl;              /* Dequoted name of collation sequence */
85571   sqlite3 *db;
85572 
85573   if( (p = pParse->pNewTable)==0 ) return;
85574   i = p->nCol-1;
85575   db = pParse->db;
85576   zColl = sqlite3NameFromToken(db, pToken);
85577   if( !zColl ) return;
85578 
85579   if( sqlite3LocateCollSeq(pParse, zColl) ){
85580     Index *pIdx;
85581     sqlite3DbFree(db, p->aCol[i].zColl);
85582     p->aCol[i].zColl = zColl;
85583   
85584     /* If the column is declared as "<name> PRIMARY KEY COLLATE <type>",
85585     ** then an index may have been created on this column before the
85586     ** collation type was added. Correct this if it is the case.
85587     */
85588     for(pIdx=p->pIndex; pIdx; pIdx=pIdx->pNext){
85589       assert( pIdx->nKeyCol==1 );
85590       if( pIdx->aiColumn[0]==i ){
85591         pIdx->azColl[0] = p->aCol[i].zColl;
85592       }
85593     }
85594   }else{
85595     sqlite3DbFree(db, zColl);
85596   }
85597 }
85598 
85599 /*
85600 ** This function returns the collation sequence for database native text
85601 ** encoding identified by the string zName, length nName.
85602 **
85603 ** If the requested collation sequence is not available, or not available
85604 ** in the database native encoding, the collation factory is invoked to
85605 ** request it. If the collation factory does not supply such a sequence,
85606 ** and the sequence is available in another text encoding, then that is
85607 ** returned instead.
85608 **
85609 ** If no versions of the requested collations sequence are available, or
85610 ** another error occurs, NULL is returned and an error message written into
85611 ** pParse.
85612 **
85613 ** This routine is a wrapper around sqlite3FindCollSeq().  This routine
85614 ** invokes the collation factory if the named collation cannot be found
85615 ** and generates an error message.
85616 **
85617 ** See also: sqlite3FindCollSeq(), sqlite3GetCollSeq()
85618 */
85619 SQLITE_PRIVATE CollSeq *sqlite3LocateCollSeq(Parse *pParse, const char *zName){
85620   sqlite3 *db = pParse->db;
85621   u8 enc = ENC(db);
85622   u8 initbusy = db->init.busy;
85623   CollSeq *pColl;
85624 
85625   pColl = sqlite3FindCollSeq(db, enc, zName, initbusy);
85626   if( !initbusy && (!pColl || !pColl->xCmp) ){
85627     pColl = sqlite3GetCollSeq(pParse, enc, pColl, zName);
85628   }
85629 
85630   return pColl;
85631 }
85632 
85633 
85634 /*
85635 ** Generate code that will increment the schema cookie.
85636 **
85637 ** The schema cookie is used to determine when the schema for the
85638 ** database changes.  After each schema change, the cookie value
85639 ** changes.  When a process first reads the schema it records the
85640 ** cookie.  Thereafter, whenever it goes to access the database,
85641 ** it checks the cookie to make sure the schema has not changed
85642 ** since it was last read.
85643 **
85644 ** This plan is not completely bullet-proof.  It is possible for
85645 ** the schema to change multiple times and for the cookie to be
85646 ** set back to prior value.  But schema changes are infrequent
85647 ** and the probability of hitting the same cookie value is only
85648 ** 1 chance in 2^32.  So we're safe enough.
85649 */
85650 SQLITE_PRIVATE void sqlite3ChangeCookie(Parse *pParse, int iDb){
85651   int r1 = sqlite3GetTempReg(pParse);
85652   sqlite3 *db = pParse->db;
85653   Vdbe *v = pParse->pVdbe;
85654   assert( sqlite3SchemaMutexHeld(db, iDb, 0) );
85655   sqlite3VdbeAddOp2(v, OP_Integer, db->aDb[iDb].pSchema->schema_cookie+1, r1);
85656   sqlite3VdbeAddOp3(v, OP_SetCookie, iDb, BTREE_SCHEMA_VERSION, r1);
85657   sqlite3ReleaseTempReg(pParse, r1);
85658 }
85659 
85660 /*
85661 ** Measure the number of characters needed to output the given
85662 ** identifier.  The number returned includes any quotes used
85663 ** but does not include the null terminator.
85664 **
85665 ** The estimate is conservative.  It might be larger that what is
85666 ** really needed.
85667 */
85668 static int identLength(const char *z){
85669   int n;
85670   for(n=0; *z; n++, z++){
85671     if( *z=='"' ){ n++; }
85672   }
85673   return n + 2;
85674 }
85675 
85676 /*
85677 ** The first parameter is a pointer to an output buffer. The second 
85678 ** parameter is a pointer to an integer that contains the offset at
85679 ** which to write into the output buffer. This function copies the
85680 ** nul-terminated string pointed to by the third parameter, zSignedIdent,
85681 ** to the specified offset in the buffer and updates *pIdx to refer
85682 ** to the first byte after the last byte written before returning.
85683 ** 
85684 ** If the string zSignedIdent consists entirely of alpha-numeric
85685 ** characters, does not begin with a digit and is not an SQL keyword,
85686 ** then it is copied to the output buffer exactly as it is. Otherwise,
85687 ** it is quoted using double-quotes.
85688 */
85689 static void identPut(char *z, int *pIdx, char *zSignedIdent){
85690   unsigned char *zIdent = (unsigned char*)zSignedIdent;
85691   int i, j, needQuote;
85692   i = *pIdx;
85693 
85694   for(j=0; zIdent[j]; j++){
85695     if( !sqlite3Isalnum(zIdent[j]) && zIdent[j]!='_' ) break;
85696   }
85697   needQuote = sqlite3Isdigit(zIdent[0]) || sqlite3KeywordCode(zIdent, j)!=TK_ID;
85698   if( !needQuote ){
85699     needQuote = zIdent[j];
85700   }
85701 
85702   if( needQuote ) z[i++] = '"';
85703   for(j=0; zIdent[j]; j++){
85704     z[i++] = zIdent[j];
85705     if( zIdent[j]=='"' ) z[i++] = '"';
85706   }
85707   if( needQuote ) z[i++] = '"';
85708   z[i] = 0;
85709   *pIdx = i;
85710 }
85711 
85712 /*
85713 ** Generate a CREATE TABLE statement appropriate for the given
85714 ** table.  Memory to hold the text of the statement is obtained
85715 ** from sqliteMalloc() and must be freed by the calling function.
85716 */
85717 static char *createTableStmt(sqlite3 *db, Table *p){
85718   int i, k, n;
85719   char *zStmt;
85720   char *zSep, *zSep2, *zEnd;
85721   Column *pCol;
85722   n = 0;
85723   for(pCol = p->aCol, i=0; i<p->nCol; i++, pCol++){
85724     n += identLength(pCol->zName) + 5;
85725   }
85726   n += identLength(p->zName);
85727   if( n<50 ){ 
85728     zSep = "";
85729     zSep2 = ",";
85730     zEnd = ")";
85731   }else{
85732     zSep = "\n  ";
85733     zSep2 = ",\n  ";
85734     zEnd = "\n)";
85735   }
85736   n += 35 + 6*p->nCol;
85737   zStmt = sqlite3DbMallocRaw(0, n);
85738   if( zStmt==0 ){
85739     db->mallocFailed = 1;
85740     return 0;
85741   }
85742   sqlite3_snprintf(n, zStmt, "CREATE TABLE ");
85743   k = sqlite3Strlen30(zStmt);
85744   identPut(zStmt, &k, p->zName);
85745   zStmt[k++] = '(';
85746   for(pCol=p->aCol, i=0; i<p->nCol; i++, pCol++){
85747     static const char * const azType[] = {
85748         /* SQLITE_AFF_TEXT    */ " TEXT",
85749         /* SQLITE_AFF_NONE    */ "",
85750         /* SQLITE_AFF_NUMERIC */ " NUM",
85751         /* SQLITE_AFF_INTEGER */ " INT",
85752         /* SQLITE_AFF_REAL    */ " REAL"
85753     };
85754     int len;
85755     const char *zType;
85756 
85757     sqlite3_snprintf(n-k, &zStmt[k], zSep);
85758     k += sqlite3Strlen30(&zStmt[k]);
85759     zSep = zSep2;
85760     identPut(zStmt, &k, pCol->zName);
85761     assert( pCol->affinity-SQLITE_AFF_TEXT >= 0 );
85762     assert( pCol->affinity-SQLITE_AFF_TEXT < ArraySize(azType) );
85763     testcase( pCol->affinity==SQLITE_AFF_TEXT );
85764     testcase( pCol->affinity==SQLITE_AFF_NONE );
85765     testcase( pCol->affinity==SQLITE_AFF_NUMERIC );
85766     testcase( pCol->affinity==SQLITE_AFF_INTEGER );
85767     testcase( pCol->affinity==SQLITE_AFF_REAL );
85768     
85769     zType = azType[pCol->affinity - SQLITE_AFF_TEXT];
85770     len = sqlite3Strlen30(zType);
85771     assert( pCol->affinity==SQLITE_AFF_NONE 
85772             || pCol->affinity==sqlite3AffinityType(zType, 0) );
85773     memcpy(&zStmt[k], zType, len);
85774     k += len;
85775     assert( k<=n );
85776   }
85777   sqlite3_snprintf(n-k, &zStmt[k], "%s", zEnd);
85778   return zStmt;
85779 }
85780 
85781 /*
85782 ** Resize an Index object to hold N columns total.  Return SQLITE_OK
85783 ** on success and SQLITE_NOMEM on an OOM error.
85784 */
85785 static int resizeIndexObject(sqlite3 *db, Index *pIdx, int N){
85786   char *zExtra;
85787   int nByte;
85788   if( pIdx->nColumn>=N ) return SQLITE_OK;
85789   assert( pIdx->isResized==0 );
85790   nByte = (sizeof(char*) + sizeof(i16) + 1)*N;
85791   zExtra = sqlite3DbMallocZero(db, nByte);
85792   if( zExtra==0 ) return SQLITE_NOMEM;
85793   memcpy(zExtra, pIdx->azColl, sizeof(char*)*pIdx->nColumn);
85794   pIdx->azColl = (char**)zExtra;
85795   zExtra += sizeof(char*)*N;
85796   memcpy(zExtra, pIdx->aiColumn, sizeof(i16)*pIdx->nColumn);
85797   pIdx->aiColumn = (i16*)zExtra;
85798   zExtra += sizeof(i16)*N;
85799   memcpy(zExtra, pIdx->aSortOrder, pIdx->nColumn);
85800   pIdx->aSortOrder = (u8*)zExtra;
85801   pIdx->nColumn = N;
85802   pIdx->isResized = 1;
85803   return SQLITE_OK;
85804 }
85805 
85806 /*
85807 ** Estimate the total row width for a table.
85808 */
85809 static void estimateTableWidth(Table *pTab){
85810   unsigned wTable = 0;
85811   const Column *pTabCol;
85812   int i;
85813   for(i=pTab->nCol, pTabCol=pTab->aCol; i>0; i--, pTabCol++){
85814     wTable += pTabCol->szEst;
85815   }
85816   if( pTab->iPKey<0 ) wTable++;
85817   pTab->szTabRow = sqlite3LogEst(wTable*4);
85818 }
85819 
85820 /*
85821 ** Estimate the average size of a row for an index.
85822 */
85823 static void estimateIndexWidth(Index *pIdx){
85824   unsigned wIndex = 0;
85825   int i;
85826   const Column *aCol = pIdx->pTable->aCol;
85827   for(i=0; i<pIdx->nColumn; i++){
85828     i16 x = pIdx->aiColumn[i];
85829     assert( x<pIdx->pTable->nCol );
85830     wIndex += x<0 ? 1 : aCol[pIdx->aiColumn[i]].szEst;
85831   }
85832   pIdx->szIdxRow = sqlite3LogEst(wIndex*4);
85833 }
85834 
85835 /* Return true if value x is found any of the first nCol entries of aiCol[]
85836 */
85837 static int hasColumn(const i16 *aiCol, int nCol, int x){
85838   while( nCol-- > 0 ) if( x==*(aiCol++) ) return 1;
85839   return 0;
85840 }
85841 
85842 /*
85843 ** This routine runs at the end of parsing a CREATE TABLE statement that
85844 ** has a WITHOUT ROWID clause.  The job of this routine is to convert both
85845 ** internal schema data structures and the generated VDBE code so that they
85846 ** are appropriate for a WITHOUT ROWID table instead of a rowid table.
85847 ** Changes include:
85848 **
85849 **     (1)  Convert the OP_CreateTable into an OP_CreateIndex.  There is
85850 **          no rowid btree for a WITHOUT ROWID.  Instead, the canonical
85851 **          data storage is a covering index btree.
85852 **     (2)  Bypass the creation of the sqlite_master table entry
85853 **          for the PRIMARY KEY as the the primary key index is now
85854 **          identified by the sqlite_master table entry of the table itself.
85855 **     (3)  Set the Index.tnum of the PRIMARY KEY Index object in the
85856 **          schema to the rootpage from the main table.
85857 **     (4)  Set all columns of the PRIMARY KEY schema object to be NOT NULL.
85858 **     (5)  Add all table columns to the PRIMARY KEY Index object
85859 **          so that the PRIMARY KEY is a covering index.  The surplus
85860 **          columns are part of KeyInfo.nXField and are not used for
85861 **          sorting or lookup or uniqueness checks.
85862 **     (6)  Replace the rowid tail on all automatically generated UNIQUE
85863 **          indices with the PRIMARY KEY columns.
85864 */
85865 static void convertToWithoutRowidTable(Parse *pParse, Table *pTab){
85866   Index *pIdx;
85867   Index *pPk;
85868   int nPk;
85869   int i, j;
85870   sqlite3 *db = pParse->db;
85871   Vdbe *v = pParse->pVdbe;
85872 
85873   /* Convert the OP_CreateTable opcode that would normally create the
85874   ** root-page for the table into a OP_CreateIndex opcode.  The index
85875   ** created will become the PRIMARY KEY index.
85876   */
85877   if( pParse->addrCrTab ){
85878     assert( v );
85879     sqlite3VdbeGetOp(v, pParse->addrCrTab)->opcode = OP_CreateIndex;
85880   }
85881 
85882   /* Bypass the creation of the PRIMARY KEY btree and the sqlite_master
85883   ** table entry.
85884   */
85885   if( pParse->addrSkipPK ){
85886     assert( v );
85887     sqlite3VdbeGetOp(v, pParse->addrSkipPK)->opcode = OP_Goto;
85888   }
85889 
85890   /* Locate the PRIMARY KEY index.  Or, if this table was originally
85891   ** an INTEGER PRIMARY KEY table, create a new PRIMARY KEY index. 
85892   */
85893   if( pTab->iPKey>=0 ){
85894     ExprList *pList;
85895     pList = sqlite3ExprListAppend(pParse, 0, 0);
85896     if( pList==0 ) return;
85897     pList->a[0].zName = sqlite3DbStrDup(pParse->db,
85898                                         pTab->aCol[pTab->iPKey].zName);
85899     pList->a[0].sortOrder = pParse->iPkSortOrder;
85900     assert( pParse->pNewTable==pTab );
85901     pPk = sqlite3CreateIndex(pParse, 0, 0, 0, pList, pTab->keyConf, 0, 0, 0, 0);
85902     if( pPk==0 ) return;
85903     pPk->autoIndex = 2;
85904     pTab->iPKey = -1;
85905   }else{
85906     pPk = sqlite3PrimaryKeyIndex(pTab);
85907   }
85908   pPk->isCovering = 1;
85909   assert( pPk!=0 );
85910   nPk = pPk->nKeyCol;
85911 
85912   /* Make sure every column of the PRIMARY KEY is NOT NULL */
85913   for(i=0; i<nPk; i++){
85914     pTab->aCol[pPk->aiColumn[i]].notNull = 1;
85915   }
85916   pPk->uniqNotNull = 1;
85917 
85918   /* The root page of the PRIMARY KEY is the table root page */
85919   pPk->tnum = pTab->tnum;
85920 
85921   /* Update the in-memory representation of all UNIQUE indices by converting
85922   ** the final rowid column into one or more columns of the PRIMARY KEY.
85923   */
85924   for(pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext){
85925     int n;
85926     if( pIdx->autoIndex==2 ) continue;
85927     for(i=n=0; i<nPk; i++){
85928       if( !hasColumn(pIdx->aiColumn, pIdx->nKeyCol, pPk->aiColumn[i]) ) n++;
85929     }
85930     if( n==0 ){
85931       /* This index is a superset of the primary key */
85932       pIdx->nColumn = pIdx->nKeyCol;
85933       continue;
85934     }
85935     if( resizeIndexObject(db, pIdx, pIdx->nKeyCol+n) ) return;
85936     for(i=0, j=pIdx->nKeyCol; i<nPk; i++){
85937       if( !hasColumn(pIdx->aiColumn, pIdx->nKeyCol, pPk->aiColumn[i]) ){
85938         pIdx->aiColumn[j] = pPk->aiColumn[i];
85939         pIdx->azColl[j] = pPk->azColl[i];
85940         j++;
85941       }
85942     }
85943     assert( pIdx->nColumn>=pIdx->nKeyCol+n );
85944     assert( pIdx->nColumn>=j );
85945   }
85946 
85947   /* Add all table columns to the PRIMARY KEY index
85948   */
85949   if( nPk<pTab->nCol ){
85950     if( resizeIndexObject(db, pPk, pTab->nCol) ) return;
85951     for(i=0, j=nPk; i<pTab->nCol; i++){
85952       if( !hasColumn(pPk->aiColumn, j, i) ){
85953         assert( j<pPk->nColumn );
85954         pPk->aiColumn[j] = i;
85955         pPk->azColl[j] = "BINARY";
85956         j++;
85957       }
85958     }
85959     assert( pPk->nColumn==j );
85960     assert( pTab->nCol==j );
85961   }else{
85962     pPk->nColumn = pTab->nCol;
85963   }
85964 }
85965 
85966 /*
85967 ** This routine is called to report the final ")" that terminates
85968 ** a CREATE TABLE statement.
85969 **
85970 ** The table structure that other action routines have been building
85971 ** is added to the internal hash tables, assuming no errors have
85972 ** occurred.
85973 **
85974 ** An entry for the table is made in the master table on disk, unless
85975 ** this is a temporary table or db->init.busy==1.  When db->init.busy==1
85976 ** it means we are reading the sqlite_master table because we just
85977 ** connected to the database or because the sqlite_master table has
85978 ** recently changed, so the entry for this table already exists in
85979 ** the sqlite_master table.  We do not want to create it again.
85980 **
85981 ** If the pSelect argument is not NULL, it means that this routine
85982 ** was called to create a table generated from a 
85983 ** "CREATE TABLE ... AS SELECT ..." statement.  The column names of
85984 ** the new table will match the result set of the SELECT.
85985 */
85986 SQLITE_PRIVATE void sqlite3EndTable(
85987   Parse *pParse,          /* Parse context */
85988   Token *pCons,           /* The ',' token after the last column defn. */
85989   Token *pEnd,            /* The ')' before options in the CREATE TABLE */
85990   u8 tabOpts,             /* Extra table options. Usually 0. */
85991   Select *pSelect         /* Select from a "CREATE ... AS SELECT" */
85992 ){
85993   Table *p;                 /* The new table */
85994   sqlite3 *db = pParse->db; /* The database connection */
85995   int iDb;                  /* Database in which the table lives */
85996   Index *pIdx;              /* An implied index of the table */
85997 
85998   if( (pEnd==0 && pSelect==0) || db->mallocFailed ){
85999     return;
86000   }
86001   p = pParse->pNewTable;
86002   if( p==0 ) return;
86003 
86004   assert( !db->init.busy || !pSelect );
86005 
86006   /* If the db->init.busy is 1 it means we are reading the SQL off the
86007   ** "sqlite_master" or "sqlite_temp_master" table on the disk.
86008   ** So do not write to the disk again.  Extract the root page number
86009   ** for the table from the db->init.newTnum field.  (The page number
86010   ** should have been put there by the sqliteOpenCb routine.)
86011   */
86012   if( db->init.busy ){
86013     p->tnum = db->init.newTnum;
86014   }
86015 
86016   /* Special processing for WITHOUT ROWID Tables */
86017   if( tabOpts & TF_WithoutRowid ){
86018     if( (p->tabFlags & TF_Autoincrement) ){
86019       sqlite3ErrorMsg(pParse,
86020           "AUTOINCREMENT not allowed on WITHOUT ROWID tables");
86021       return;
86022     }
86023     if( (p->tabFlags & TF_HasPrimaryKey)==0 ){
86024       sqlite3ErrorMsg(pParse, "PRIMARY KEY missing on table %s", p->zName);
86025     }else{
86026       p->tabFlags |= TF_WithoutRowid;
86027       convertToWithoutRowidTable(pParse, p);
86028     }
86029   }
86030 
86031   iDb = sqlite3SchemaToIndex(db, p->pSchema);
86032 
86033 #ifndef SQLITE_OMIT_CHECK
86034   /* Resolve names in all CHECK constraint expressions.
86035   */
86036   if( p->pCheck ){
86037     sqlite3ResolveSelfReference(pParse, p, NC_IsCheck, 0, p->pCheck);
86038   }
86039 #endif /* !defined(SQLITE_OMIT_CHECK) */
86040 
86041   /* Estimate the average row size for the table and for all implied indices */
86042   estimateTableWidth(p);
86043   for(pIdx=p->pIndex; pIdx; pIdx=pIdx->pNext){
86044     estimateIndexWidth(pIdx);
86045   }
86046 
86047   /* If not initializing, then create a record for the new table
86048   ** in the SQLITE_MASTER table of the database.
86049   **
86050   ** If this is a TEMPORARY table, write the entry into the auxiliary
86051   ** file instead of into the main database file.
86052   */
86053   if( !db->init.busy ){
86054     int n;
86055     Vdbe *v;
86056     char *zType;    /* "view" or "table" */
86057     char *zType2;   /* "VIEW" or "TABLE" */
86058     char *zStmt;    /* Text of the CREATE TABLE or CREATE VIEW statement */
86059 
86060     v = sqlite3GetVdbe(pParse);
86061     if( NEVER(v==0) ) return;
86062 
86063     sqlite3VdbeAddOp1(v, OP_Close, 0);
86064 
86065     /* 
86066     ** Initialize zType for the new view or table.
86067     */
86068     if( p->pSelect==0 ){
86069       /* A regular table */
86070       zType = "table";
86071       zType2 = "TABLE";
86072 #ifndef SQLITE_OMIT_VIEW
86073     }else{
86074       /* A view */
86075       zType = "view";
86076       zType2 = "VIEW";
86077 #endif
86078     }
86079 
86080     /* If this is a CREATE TABLE xx AS SELECT ..., execute the SELECT
86081     ** statement to populate the new table. The root-page number for the
86082     ** new table is in register pParse->regRoot.
86083     **
86084     ** Once the SELECT has been coded by sqlite3Select(), it is in a
86085     ** suitable state to query for the column names and types to be used
86086     ** by the new table.
86087     **
86088     ** A shared-cache write-lock is not required to write to the new table,
86089     ** as a schema-lock must have already been obtained to create it. Since
86090     ** a schema-lock excludes all other database users, the write-lock would
86091     ** be redundant.
86092     */
86093     if( pSelect ){
86094       SelectDest dest;
86095       Table *pSelTab;
86096 
86097       assert(pParse->nTab==1);
86098       sqlite3VdbeAddOp3(v, OP_OpenWrite, 1, pParse->regRoot, iDb);
86099       sqlite3VdbeChangeP5(v, OPFLAG_P2ISREG);
86100       pParse->nTab = 2;
86101       sqlite3SelectDestInit(&dest, SRT_Table, 1);
86102       sqlite3Select(pParse, pSelect, &dest);
86103       sqlite3VdbeAddOp1(v, OP_Close, 1);
86104       if( pParse->nErr==0 ){
86105         pSelTab = sqlite3ResultSetOfSelect(pParse, pSelect);
86106         if( pSelTab==0 ) return;
86107         assert( p->aCol==0 );
86108         p->nCol = pSelTab->nCol;
86109         p->aCol = pSelTab->aCol;
86110         pSelTab->nCol = 0;
86111         pSelTab->aCol = 0;
86112         sqlite3DeleteTable(db, pSelTab);
86113       }
86114     }
86115 
86116     /* Compute the complete text of the CREATE statement */
86117     if( pSelect ){
86118       zStmt = createTableStmt(db, p);
86119     }else{
86120       Token *pEnd2 = tabOpts ? &pParse->sLastToken : pEnd;
86121       n = (int)(pEnd2->z - pParse->sNameToken.z);
86122       if( pEnd2->z[0]!=';' ) n += pEnd2->n;
86123       zStmt = sqlite3MPrintf(db, 
86124           "CREATE %s %.*s", zType2, n, pParse->sNameToken.z
86125       );
86126     }
86127 
86128     /* A slot for the record has already been allocated in the 
86129     ** SQLITE_MASTER table.  We just need to update that slot with all
86130     ** the information we've collected.
86131     */
86132     sqlite3NestedParse(pParse,
86133       "UPDATE %Q.%s "
86134          "SET type='%s', name=%Q, tbl_name=%Q, rootpage=#%d, sql=%Q "
86135        "WHERE rowid=#%d",
86136       db->aDb[iDb].zName, SCHEMA_TABLE(iDb),
86137       zType,
86138       p->zName,
86139       p->zName,
86140       pParse->regRoot,
86141       zStmt,
86142       pParse->regRowid
86143     );
86144     sqlite3DbFree(db, zStmt);
86145     sqlite3ChangeCookie(pParse, iDb);
86146 
86147 #ifndef SQLITE_OMIT_AUTOINCREMENT
86148     /* Check to see if we need to create an sqlite_sequence table for
86149     ** keeping track of autoincrement keys.
86150     */
86151     if( p->tabFlags & TF_Autoincrement ){
86152       Db *pDb = &db->aDb[iDb];
86153       assert( sqlite3SchemaMutexHeld(db, iDb, 0) );
86154       if( pDb->pSchema->pSeqTab==0 ){
86155         sqlite3NestedParse(pParse,
86156           "CREATE TABLE %Q.sqlite_sequence(name,seq)",
86157           pDb->zName
86158         );
86159       }
86160     }
86161 #endif
86162 
86163     /* Reparse everything to update our internal data structures */
86164     sqlite3VdbeAddParseSchemaOp(v, iDb,
86165            sqlite3MPrintf(db, "tbl_name='%q' AND type!='trigger'", p->zName));
86166   }
86167 
86168 
86169   /* Add the table to the in-memory representation of the database.
86170   */
86171   if( db->init.busy ){
86172     Table *pOld;
86173     Schema *pSchema = p->pSchema;
86174     assert( sqlite3SchemaMutexHeld(db, iDb, 0) );
86175     pOld = sqlite3HashInsert(&pSchema->tblHash, p->zName,
86176                              sqlite3Strlen30(p->zName),p);
86177     if( pOld ){
86178       assert( p==pOld );  /* Malloc must have failed inside HashInsert() */
86179       db->mallocFailed = 1;
86180       return;
86181     }
86182     pParse->pNewTable = 0;
86183     db->flags |= SQLITE_InternChanges;
86184 
86185 #ifndef SQLITE_OMIT_ALTERTABLE
86186     if( !p->pSelect ){
86187       const char *zName = (const char *)pParse->sNameToken.z;
86188       int nName;
86189       assert( !pSelect && pCons && pEnd );
86190       if( pCons->z==0 ){
86191         pCons = pEnd;
86192       }
86193       nName = (int)((const char *)pCons->z - zName);
86194       p->addColOffset = 13 + sqlite3Utf8CharLen(zName, nName);
86195     }
86196 #endif
86197   }
86198 }
86199 
86200 #ifndef SQLITE_OMIT_VIEW
86201 /*
86202 ** The parser calls this routine in order to create a new VIEW
86203 */
86204 SQLITE_PRIVATE void sqlite3CreateView(
86205   Parse *pParse,     /* The parsing context */
86206   Token *pBegin,     /* The CREATE token that begins the statement */
86207   Token *pName1,     /* The token that holds the name of the view */
86208   Token *pName2,     /* The token that holds the name of the view */
86209   Select *pSelect,   /* A SELECT statement that will become the new view */
86210   int isTemp,        /* TRUE for a TEMPORARY view */
86211   int noErr          /* Suppress error messages if VIEW already exists */
86212 ){
86213   Table *p;
86214   int n;
86215   const char *z;
86216   Token sEnd;
86217   DbFixer sFix;
86218   Token *pName = 0;
86219   int iDb;
86220   sqlite3 *db = pParse->db;
86221 
86222   if( pParse->nVar>0 ){
86223     sqlite3ErrorMsg(pParse, "parameters are not allowed in views");
86224     sqlite3SelectDelete(db, pSelect);
86225     return;
86226   }
86227   sqlite3StartTable(pParse, pName1, pName2, isTemp, 1, 0, noErr);
86228   p = pParse->pNewTable;
86229   if( p==0 || pParse->nErr ){
86230     sqlite3SelectDelete(db, pSelect);
86231     return;
86232   }
86233   sqlite3TwoPartName(pParse, pName1, pName2, &pName);
86234   iDb = sqlite3SchemaToIndex(db, p->pSchema);
86235   sqlite3FixInit(&sFix, pParse, iDb, "view", pName);
86236   if( sqlite3FixSelect(&sFix, pSelect) ){
86237     sqlite3SelectDelete(db, pSelect);
86238     return;
86239   }
86240 
86241   /* Make a copy of the entire SELECT statement that defines the view.
86242   ** This will force all the Expr.token.z values to be dynamically
86243   ** allocated rather than point to the input string - which means that
86244   ** they will persist after the current sqlite3_exec() call returns.
86245   */
86246   p->pSelect = sqlite3SelectDup(db, pSelect, EXPRDUP_REDUCE);
86247   sqlite3SelectDelete(db, pSelect);
86248   if( db->mallocFailed ){
86249     return;
86250   }
86251   if( !db->init.busy ){
86252     sqlite3ViewGetColumnNames(pParse, p);
86253   }
86254 
86255   /* Locate the end of the CREATE VIEW statement.  Make sEnd point to
86256   ** the end.
86257   */
86258   sEnd = pParse->sLastToken;
86259   if( ALWAYS(sEnd.z[0]!=0) && sEnd.z[0]!=';' ){
86260     sEnd.z += sEnd.n;
86261   }
86262   sEnd.n = 0;
86263   n = (int)(sEnd.z - pBegin->z);
86264   z = pBegin->z;
86265   while( ALWAYS(n>0) && sqlite3Isspace(z[n-1]) ){ n--; }
86266   sEnd.z = &z[n-1];
86267   sEnd.n = 1;
86268 
86269   /* Use sqlite3EndTable() to add the view to the SQLITE_MASTER table */
86270   sqlite3EndTable(pParse, 0, &sEnd, 0, 0);
86271   return;
86272 }
86273 #endif /* SQLITE_OMIT_VIEW */
86274 
86275 #if !defined(SQLITE_OMIT_VIEW) || !defined(SQLITE_OMIT_VIRTUALTABLE)
86276 /*
86277 ** The Table structure pTable is really a VIEW.  Fill in the names of
86278 ** the columns of the view in the pTable structure.  Return the number
86279 ** of errors.  If an error is seen leave an error message in pParse->zErrMsg.
86280 */
86281 SQLITE_PRIVATE int sqlite3ViewGetColumnNames(Parse *pParse, Table *pTable){
86282   Table *pSelTab;   /* A fake table from which we get the result set */
86283   Select *pSel;     /* Copy of the SELECT that implements the view */
86284   int nErr = 0;     /* Number of errors encountered */
86285   int n;            /* Temporarily holds the number of cursors assigned */
86286   sqlite3 *db = pParse->db;  /* Database connection for malloc errors */
86287   int (*xAuth)(void*,int,const char*,const char*,const char*,const char*);
86288 
86289   assert( pTable );
86290 
86291 #ifndef SQLITE_OMIT_VIRTUALTABLE
86292   if( sqlite3VtabCallConnect(pParse, pTable) ){
86293     return SQLITE_ERROR;
86294   }
86295   if( IsVirtual(pTable) ) return 0;
86296 #endif
86297 
86298 #ifndef SQLITE_OMIT_VIEW
86299   /* A positive nCol means the columns names for this view are
86300   ** already known.
86301   */
86302   if( pTable->nCol>0 ) return 0;
86303 
86304   /* A negative nCol is a special marker meaning that we are currently
86305   ** trying to compute the column names.  If we enter this routine with
86306   ** a negative nCol, it means two or more views form a loop, like this:
86307   **
86308   **     CREATE VIEW one AS SELECT * FROM two;
86309   **     CREATE VIEW two AS SELECT * FROM one;
86310   **
86311   ** Actually, the error above is now caught prior to reaching this point.
86312   ** But the following test is still important as it does come up
86313   ** in the following:
86314   ** 
86315   **     CREATE TABLE main.ex1(a);
86316   **     CREATE TEMP VIEW ex1 AS SELECT a FROM ex1;
86317   **     SELECT * FROM temp.ex1;
86318   */
86319   if( pTable->nCol<0 ){
86320     sqlite3ErrorMsg(pParse, "view %s is circularly defined", pTable->zName);
86321     return 1;
86322   }
86323   assert( pTable->nCol>=0 );
86324 
86325   /* If we get this far, it means we need to compute the table names.
86326   ** Note that the call to sqlite3ResultSetOfSelect() will expand any
86327   ** "*" elements in the results set of the view and will assign cursors
86328   ** to the elements of the FROM clause.  But we do not want these changes
86329   ** to be permanent.  So the computation is done on a copy of the SELECT
86330   ** statement that defines the view.
86331   */
86332   assert( pTable->pSelect );
86333   pSel = sqlite3SelectDup(db, pTable->pSelect, 0);
86334   if( pSel ){
86335     u8 enableLookaside = db->lookaside.bEnabled;
86336     n = pParse->nTab;
86337     sqlite3SrcListAssignCursors(pParse, pSel->pSrc);
86338     pTable->nCol = -1;
86339     db->lookaside.bEnabled = 0;
86340 #ifndef SQLITE_OMIT_AUTHORIZATION
86341     xAuth = db->xAuth;
86342     db->xAuth = 0;
86343     pSelTab = sqlite3ResultSetOfSelect(pParse, pSel);
86344     db->xAuth = xAuth;
86345 #else
86346     pSelTab = sqlite3ResultSetOfSelect(pParse, pSel);
86347 #endif
86348     db->lookaside.bEnabled = enableLookaside;
86349     pParse->nTab = n;
86350     if( pSelTab ){
86351       assert( pTable->aCol==0 );
86352       pTable->nCol = pSelTab->nCol;
86353       pTable->aCol = pSelTab->aCol;
86354       pSelTab->nCol = 0;
86355       pSelTab->aCol = 0;
86356       sqlite3DeleteTable(db, pSelTab);
86357       assert( sqlite3SchemaMutexHeld(db, 0, pTable->pSchema) );
86358       pTable->pSchema->flags |= DB_UnresetViews;
86359     }else{
86360       pTable->nCol = 0;
86361       nErr++;
86362     }
86363     sqlite3SelectDelete(db, pSel);
86364   } else {
86365     nErr++;
86366   }
86367 #endif /* SQLITE_OMIT_VIEW */
86368   return nErr;  
86369 }
86370 #endif /* !defined(SQLITE_OMIT_VIEW) || !defined(SQLITE_OMIT_VIRTUALTABLE) */
86371 
86372 #ifndef SQLITE_OMIT_VIEW
86373 /*
86374 ** Clear the column names from every VIEW in database idx.
86375 */
86376 static void sqliteViewResetAll(sqlite3 *db, int idx){
86377   HashElem *i;
86378   assert( sqlite3SchemaMutexHeld(db, idx, 0) );
86379   if( !DbHasProperty(db, idx, DB_UnresetViews) ) return;
86380   for(i=sqliteHashFirst(&db->aDb[idx].pSchema->tblHash); i;i=sqliteHashNext(i)){
86381     Table *pTab = sqliteHashData(i);
86382     if( pTab->pSelect ){
86383       sqliteDeleteColumnNames(db, pTab);
86384       pTab->aCol = 0;
86385       pTab->nCol = 0;
86386     }
86387   }
86388   DbClearProperty(db, idx, DB_UnresetViews);
86389 }
86390 #else
86391 # define sqliteViewResetAll(A,B)
86392 #endif /* SQLITE_OMIT_VIEW */
86393 
86394 /*
86395 ** This function is called by the VDBE to adjust the internal schema
86396 ** used by SQLite when the btree layer moves a table root page. The
86397 ** root-page of a table or index in database iDb has changed from iFrom
86398 ** to iTo.
86399 **
86400 ** Ticket #1728:  The symbol table might still contain information
86401 ** on tables and/or indices that are the process of being deleted.
86402 ** If you are unlucky, one of those deleted indices or tables might
86403 ** have the same rootpage number as the real table or index that is
86404 ** being moved.  So we cannot stop searching after the first match 
86405 ** because the first match might be for one of the deleted indices
86406 ** or tables and not the table/index that is actually being moved.
86407 ** We must continue looping until all tables and indices with
86408 ** rootpage==iFrom have been converted to have a rootpage of iTo
86409 ** in order to be certain that we got the right one.
86410 */
86411 #ifndef SQLITE_OMIT_AUTOVACUUM
86412 SQLITE_PRIVATE void sqlite3RootPageMoved(sqlite3 *db, int iDb, int iFrom, int iTo){
86413   HashElem *pElem;
86414   Hash *pHash;
86415   Db *pDb;
86416 
86417   assert( sqlite3SchemaMutexHeld(db, iDb, 0) );
86418   pDb = &db->aDb[iDb];
86419   pHash = &pDb->pSchema->tblHash;
86420   for(pElem=sqliteHashFirst(pHash); pElem; pElem=sqliteHashNext(pElem)){
86421     Table *pTab = sqliteHashData(pElem);
86422     if( pTab->tnum==iFrom ){
86423       pTab->tnum = iTo;
86424     }
86425   }
86426   pHash = &pDb->pSchema->idxHash;
86427   for(pElem=sqliteHashFirst(pHash); pElem; pElem=sqliteHashNext(pElem)){
86428     Index *pIdx = sqliteHashData(pElem);
86429     if( pIdx->tnum==iFrom ){
86430       pIdx->tnum = iTo;
86431     }
86432   }
86433 }
86434 #endif
86435 
86436 /*
86437 ** Write code to erase the table with root-page iTable from database iDb.
86438 ** Also write code to modify the sqlite_master table and internal schema
86439 ** if a root-page of another table is moved by the btree-layer whilst
86440 ** erasing iTable (this can happen with an auto-vacuum database).
86441 */ 
86442 static void destroyRootPage(Parse *pParse, int iTable, int iDb){
86443   Vdbe *v = sqlite3GetVdbe(pParse);
86444   int r1 = sqlite3GetTempReg(pParse);
86445   sqlite3VdbeAddOp3(v, OP_Destroy, iTable, r1, iDb);
86446   sqlite3MayAbort(pParse);
86447 #ifndef SQLITE_OMIT_AUTOVACUUM
86448   /* OP_Destroy stores an in integer r1. If this integer
86449   ** is non-zero, then it is the root page number of a table moved to
86450   ** location iTable. The following code modifies the sqlite_master table to
86451   ** reflect this.
86452   **
86453   ** The "#NNN" in the SQL is a special constant that means whatever value
86454   ** is in register NNN.  See grammar rules associated with the TK_REGISTER
86455   ** token for additional information.
86456   */
86457   sqlite3NestedParse(pParse, 
86458      "UPDATE %Q.%s SET rootpage=%d WHERE #%d AND rootpage=#%d",
86459      pParse->db->aDb[iDb].zName, SCHEMA_TABLE(iDb), iTable, r1, r1);
86460 #endif
86461   sqlite3ReleaseTempReg(pParse, r1);
86462 }
86463 
86464 /*
86465 ** Write VDBE code to erase table pTab and all associated indices on disk.
86466 ** Code to update the sqlite_master tables and internal schema definitions
86467 ** in case a root-page belonging to another table is moved by the btree layer
86468 ** is also added (this can happen with an auto-vacuum database).
86469 */
86470 static void destroyTable(Parse *pParse, Table *pTab){
86471 #ifdef SQLITE_OMIT_AUTOVACUUM
86472   Index *pIdx;
86473   int iDb = sqlite3SchemaToIndex(pParse->db, pTab->pSchema);
86474   destroyRootPage(pParse, pTab->tnum, iDb);
86475   for(pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext){
86476     destroyRootPage(pParse, pIdx->tnum, iDb);
86477   }
86478 #else
86479   /* If the database may be auto-vacuum capable (if SQLITE_OMIT_AUTOVACUUM
86480   ** is not defined), then it is important to call OP_Destroy on the
86481   ** table and index root-pages in order, starting with the numerically 
86482   ** largest root-page number. This guarantees that none of the root-pages
86483   ** to be destroyed is relocated by an earlier OP_Destroy. i.e. if the
86484   ** following were coded:
86485   **
86486   ** OP_Destroy 4 0
86487   ** ...
86488   ** OP_Destroy 5 0
86489   **
86490   ** and root page 5 happened to be the largest root-page number in the
86491   ** database, then root page 5 would be moved to page 4 by the 
86492   ** "OP_Destroy 4 0" opcode. The subsequent "OP_Destroy 5 0" would hit
86493   ** a free-list page.
86494   */
86495   int iTab = pTab->tnum;
86496   int iDestroyed = 0;
86497 
86498   while( 1 ){
86499     Index *pIdx;
86500     int iLargest = 0;
86501 
86502     if( iDestroyed==0 || iTab<iDestroyed ){
86503       iLargest = iTab;
86504     }
86505     for(pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext){
86506       int iIdx = pIdx->tnum;
86507       assert( pIdx->pSchema==pTab->pSchema );
86508       if( (iDestroyed==0 || (iIdx<iDestroyed)) && iIdx>iLargest ){
86509         iLargest = iIdx;
86510       }
86511     }
86512     if( iLargest==0 ){
86513       return;
86514     }else{
86515       int iDb = sqlite3SchemaToIndex(pParse->db, pTab->pSchema);
86516       assert( iDb>=0 && iDb<pParse->db->nDb );
86517       destroyRootPage(pParse, iLargest, iDb);
86518       iDestroyed = iLargest;
86519     }
86520   }
86521 #endif
86522 }
86523 
86524 /*
86525 ** Remove entries from the sqlite_statN tables (for N in (1,2,3))
86526 ** after a DROP INDEX or DROP TABLE command.
86527 */
86528 static void sqlite3ClearStatTables(
86529   Parse *pParse,         /* The parsing context */
86530   int iDb,               /* The database number */
86531   const char *zType,     /* "idx" or "tbl" */
86532   const char *zName      /* Name of index or table */
86533 ){
86534   int i;
86535   const char *zDbName = pParse->db->aDb[iDb].zName;
86536   for(i=1; i<=4; i++){
86537     char zTab[24];
86538     sqlite3_snprintf(sizeof(zTab),zTab,"sqlite_stat%d",i);
86539     if( sqlite3FindTable(pParse->db, zTab, zDbName) ){
86540       sqlite3NestedParse(pParse,
86541         "DELETE FROM %Q.%s WHERE %s=%Q",
86542         zDbName, zTab, zType, zName
86543       );
86544     }
86545   }
86546 }
86547 
86548 /*
86549 ** Generate code to drop a table.
86550 */
86551 SQLITE_PRIVATE void sqlite3CodeDropTable(Parse *pParse, Table *pTab, int iDb, int isView){
86552   Vdbe *v;
86553   sqlite3 *db = pParse->db;
86554   Trigger *pTrigger;
86555   Db *pDb = &db->aDb[iDb];
86556 
86557   v = sqlite3GetVdbe(pParse);
86558   assert( v!=0 );
86559   sqlite3BeginWriteOperation(pParse, 1, iDb);
86560 
86561 #ifndef SQLITE_OMIT_VIRTUALTABLE
86562   if( IsVirtual(pTab) ){
86563     sqlite3VdbeAddOp0(v, OP_VBegin);
86564   }
86565 #endif
86566 
86567   /* Drop all triggers associated with the table being dropped. Code
86568   ** is generated to remove entries from sqlite_master and/or
86569   ** sqlite_temp_master if required.
86570   */
86571   pTrigger = sqlite3TriggerList(pParse, pTab);
86572   while( pTrigger ){
86573     assert( pTrigger->pSchema==pTab->pSchema || 
86574         pTrigger->pSchema==db->aDb[1].pSchema );
86575     sqlite3DropTriggerPtr(pParse, pTrigger);
86576     pTrigger = pTrigger->pNext;
86577   }
86578 
86579 #ifndef SQLITE_OMIT_AUTOINCREMENT
86580   /* Remove any entries of the sqlite_sequence table associated with
86581   ** the table being dropped. This is done before the table is dropped
86582   ** at the btree level, in case the sqlite_sequence table needs to
86583   ** move as a result of the drop (can happen in auto-vacuum mode).
86584   */
86585   if( pTab->tabFlags & TF_Autoincrement ){
86586     sqlite3NestedParse(pParse,
86587       "DELETE FROM %Q.sqlite_sequence WHERE name=%Q",
86588       pDb->zName, pTab->zName
86589     );
86590   }
86591 #endif
86592 
86593   /* Drop all SQLITE_MASTER table and index entries that refer to the
86594   ** table. The program name loops through the master table and deletes
86595   ** every row that refers to a table of the same name as the one being
86596   ** dropped. Triggers are handled separately because a trigger can be
86597   ** created in the temp database that refers to a table in another
86598   ** database.
86599   */
86600   sqlite3NestedParse(pParse, 
86601       "DELETE FROM %Q.%s WHERE tbl_name=%Q and type!='trigger'",
86602       pDb->zName, SCHEMA_TABLE(iDb), pTab->zName);
86603   if( !isView && !IsVirtual(pTab) ){
86604     destroyTable(pParse, pTab);
86605   }
86606 
86607   /* Remove the table entry from SQLite's internal schema and modify
86608   ** the schema cookie.
86609   */
86610   if( IsVirtual(pTab) ){
86611     sqlite3VdbeAddOp4(v, OP_VDestroy, iDb, 0, 0, pTab->zName, 0);
86612   }
86613   sqlite3VdbeAddOp4(v, OP_DropTable, iDb, 0, 0, pTab->zName, 0);
86614   sqlite3ChangeCookie(pParse, iDb);
86615   sqliteViewResetAll(db, iDb);
86616 }
86617 
86618 /*
86619 ** This routine is called to do the work of a DROP TABLE statement.
86620 ** pName is the name of the table to be dropped.
86621 */
86622 SQLITE_PRIVATE void sqlite3DropTable(Parse *pParse, SrcList *pName, int isView, int noErr){
86623   Table *pTab;
86624   Vdbe *v;
86625   sqlite3 *db = pParse->db;
86626   int iDb;
86627 
86628   if( db->mallocFailed ){
86629     goto exit_drop_table;
86630   }
86631   assert( pParse->nErr==0 );
86632   assert( pName->nSrc==1 );
86633   if( noErr ) db->suppressErr++;
86634   pTab = sqlite3LocateTableItem(pParse, isView, &pName->a[0]);
86635   if( noErr ) db->suppressErr--;
86636 
86637   if( pTab==0 ){
86638     if( noErr ) sqlite3CodeVerifyNamedSchema(pParse, pName->a[0].zDatabase);
86639     goto exit_drop_table;
86640   }
86641   iDb = sqlite3SchemaToIndex(db, pTab->pSchema);
86642   assert( iDb>=0 && iDb<db->nDb );
86643 
86644   /* If pTab is a virtual table, call ViewGetColumnNames() to ensure
86645   ** it is initialized.
86646   */
86647   if( IsVirtual(pTab) && sqlite3ViewGetColumnNames(pParse, pTab) ){
86648     goto exit_drop_table;
86649   }
86650 #ifndef SQLITE_OMIT_AUTHORIZATION
86651   {
86652     int code;
86653     const char *zTab = SCHEMA_TABLE(iDb);
86654     const char *zDb = db->aDb[iDb].zName;
86655     const char *zArg2 = 0;
86656     if( sqlite3AuthCheck(pParse, SQLITE_DELETE, zTab, 0, zDb)){
86657       goto exit_drop_table;
86658     }
86659     if( isView ){
86660       if( !OMIT_TEMPDB && iDb==1 ){
86661         code = SQLITE_DROP_TEMP_VIEW;
86662       }else{
86663         code = SQLITE_DROP_VIEW;
86664       }
86665 #ifndef SQLITE_OMIT_VIRTUALTABLE
86666     }else if( IsVirtual(pTab) ){
86667       code = SQLITE_DROP_VTABLE;
86668       zArg2 = sqlite3GetVTable(db, pTab)->pMod->zName;
86669 #endif
86670     }else{
86671       if( !OMIT_TEMPDB && iDb==1 ){
86672         code = SQLITE_DROP_TEMP_TABLE;
86673       }else{
86674         code = SQLITE_DROP_TABLE;
86675       }
86676     }
86677     if( sqlite3AuthCheck(pParse, code, pTab->zName, zArg2, zDb) ){
86678       goto exit_drop_table;
86679     }
86680     if( sqlite3AuthCheck(pParse, SQLITE_DELETE, pTab->zName, 0, zDb) ){
86681       goto exit_drop_table;
86682     }
86683   }
86684 #endif
86685   if( sqlite3StrNICmp(pTab->zName, "sqlite_", 7)==0 
86686     && sqlite3StrNICmp(pTab->zName, "sqlite_stat", 11)!=0 ){
86687     sqlite3ErrorMsg(pParse, "table %s may not be dropped", pTab->zName);
86688     goto exit_drop_table;
86689   }
86690 
86691 #ifndef SQLITE_OMIT_VIEW
86692   /* Ensure DROP TABLE is not used on a view, and DROP VIEW is not used
86693   ** on a table.
86694   */
86695   if( isView && pTab->pSelect==0 ){
86696     sqlite3ErrorMsg(pParse, "use DROP TABLE to delete table %s", pTab->zName);
86697     goto exit_drop_table;
86698   }
86699   if( !isView && pTab->pSelect ){
86700     sqlite3ErrorMsg(pParse, "use DROP VIEW to delete view %s", pTab->zName);
86701     goto exit_drop_table;
86702   }
86703 #endif
86704 
86705   /* Generate code to remove the table from the master table
86706   ** on disk.
86707   */
86708   v = sqlite3GetVdbe(pParse);
86709   if( v ){
86710     sqlite3BeginWriteOperation(pParse, 1, iDb);
86711     sqlite3ClearStatTables(pParse, iDb, "tbl", pTab->zName);
86712     sqlite3FkDropTable(pParse, pName, pTab);
86713     sqlite3CodeDropTable(pParse, pTab, iDb, isView);
86714   }
86715 
86716 exit_drop_table:
86717   sqlite3SrcListDelete(db, pName);
86718 }
86719 
86720 /*
86721 ** This routine is called to create a new foreign key on the table
86722 ** currently under construction.  pFromCol determines which columns
86723 ** in the current table point to the foreign key.  If pFromCol==0 then
86724 ** connect the key to the last column inserted.  pTo is the name of
86725 ** the table referred to (a.k.a the "parent" table).  pToCol is a list
86726 ** of tables in the parent pTo table.  flags contains all
86727 ** information about the conflict resolution algorithms specified
86728 ** in the ON DELETE, ON UPDATE and ON INSERT clauses.
86729 **
86730 ** An FKey structure is created and added to the table currently
86731 ** under construction in the pParse->pNewTable field.
86732 **
86733 ** The foreign key is set for IMMEDIATE processing.  A subsequent call
86734 ** to sqlite3DeferForeignKey() might change this to DEFERRED.
86735 */
86736 SQLITE_PRIVATE void sqlite3CreateForeignKey(
86737   Parse *pParse,       /* Parsing context */
86738   ExprList *pFromCol,  /* Columns in this table that point to other table */
86739   Token *pTo,          /* Name of the other table */
86740   ExprList *pToCol,    /* Columns in the other table */
86741   int flags            /* Conflict resolution algorithms. */
86742 ){
86743   sqlite3 *db = pParse->db;
86744 #ifndef SQLITE_OMIT_FOREIGN_KEY
86745   FKey *pFKey = 0;
86746   FKey *pNextTo;
86747   Table *p = pParse->pNewTable;
86748   int nByte;
86749   int i;
86750   int nCol;
86751   char *z;
86752 
86753   assert( pTo!=0 );
86754   if( p==0 || IN_DECLARE_VTAB ) goto fk_end;
86755   if( pFromCol==0 ){
86756     int iCol = p->nCol-1;
86757     if( NEVER(iCol<0) ) goto fk_end;
86758     if( pToCol && pToCol->nExpr!=1 ){
86759       sqlite3ErrorMsg(pParse, "foreign key on %s"
86760          " should reference only one column of table %T",
86761          p->aCol[iCol].zName, pTo);
86762       goto fk_end;
86763     }
86764     nCol = 1;
86765   }else if( pToCol && pToCol->nExpr!=pFromCol->nExpr ){
86766     sqlite3ErrorMsg(pParse,
86767         "number of columns in foreign key does not match the number of "
86768         "columns in the referenced table");
86769     goto fk_end;
86770   }else{
86771     nCol = pFromCol->nExpr;
86772   }
86773   nByte = sizeof(*pFKey) + (nCol-1)*sizeof(pFKey->aCol[0]) + pTo->n + 1;
86774   if( pToCol ){
86775     for(i=0; i<pToCol->nExpr; i++){
86776       nByte += sqlite3Strlen30(pToCol->a[i].zName) + 1;
86777     }
86778   }
86779   pFKey = sqlite3DbMallocZero(db, nByte );
86780   if( pFKey==0 ){
86781     goto fk_end;
86782   }
86783   pFKey->pFrom = p;
86784   pFKey->pNextFrom = p->pFKey;
86785   z = (char*)&pFKey->aCol[nCol];
86786   pFKey->zTo = z;
86787   memcpy(z, pTo->z, pTo->n);
86788   z[pTo->n] = 0;
86789   sqlite3Dequote(z);
86790   z += pTo->n+1;
86791   pFKey->nCol = nCol;
86792   if( pFromCol==0 ){
86793     pFKey->aCol[0].iFrom = p->nCol-1;
86794   }else{
86795     for(i=0; i<nCol; i++){
86796       int j;
86797       for(j=0; j<p->nCol; j++){
86798         if( sqlite3StrICmp(p->aCol[j].zName, pFromCol->a[i].zName)==0 ){
86799           pFKey->aCol[i].iFrom = j;
86800           break;
86801         }
86802       }
86803       if( j>=p->nCol ){
86804         sqlite3ErrorMsg(pParse, 
86805           "unknown column \"%s\" in foreign key definition", 
86806           pFromCol->a[i].zName);
86807         goto fk_end;
86808       }
86809     }
86810   }
86811   if( pToCol ){
86812     for(i=0; i<nCol; i++){
86813       int n = sqlite3Strlen30(pToCol->a[i].zName);
86814       pFKey->aCol[i].zCol = z;
86815       memcpy(z, pToCol->a[i].zName, n);
86816       z[n] = 0;
86817       z += n+1;
86818     }
86819   }
86820   pFKey->isDeferred = 0;
86821   pFKey->aAction[0] = (u8)(flags & 0xff);            /* ON DELETE action */
86822   pFKey->aAction[1] = (u8)((flags >> 8 ) & 0xff);    /* ON UPDATE action */
86823 
86824   assert( sqlite3SchemaMutexHeld(db, 0, p->pSchema) );
86825   pNextTo = (FKey *)sqlite3HashInsert(&p->pSchema->fkeyHash, 
86826       pFKey->zTo, sqlite3Strlen30(pFKey->zTo), (void *)pFKey
86827   );
86828   if( pNextTo==pFKey ){
86829     db->mallocFailed = 1;
86830     goto fk_end;
86831   }
86832   if( pNextTo ){
86833     assert( pNextTo->pPrevTo==0 );
86834     pFKey->pNextTo = pNextTo;
86835     pNextTo->pPrevTo = pFKey;
86836   }
86837 
86838   /* Link the foreign key to the table as the last step.
86839   */
86840   p->pFKey = pFKey;
86841   pFKey = 0;
86842 
86843 fk_end:
86844   sqlite3DbFree(db, pFKey);
86845 #endif /* !defined(SQLITE_OMIT_FOREIGN_KEY) */
86846   sqlite3ExprListDelete(db, pFromCol);
86847   sqlite3ExprListDelete(db, pToCol);
86848 }
86849 
86850 /*
86851 ** This routine is called when an INITIALLY IMMEDIATE or INITIALLY DEFERRED
86852 ** clause is seen as part of a foreign key definition.  The isDeferred
86853 ** parameter is 1 for INITIALLY DEFERRED and 0 for INITIALLY IMMEDIATE.
86854 ** The behavior of the most recently created foreign key is adjusted
86855 ** accordingly.
86856 */
86857 SQLITE_PRIVATE void sqlite3DeferForeignKey(Parse *pParse, int isDeferred){
86858 #ifndef SQLITE_OMIT_FOREIGN_KEY
86859   Table *pTab;
86860   FKey *pFKey;
86861   if( (pTab = pParse->pNewTable)==0 || (pFKey = pTab->pFKey)==0 ) return;
86862   assert( isDeferred==0 || isDeferred==1 ); /* EV: R-30323-21917 */
86863   pFKey->isDeferred = (u8)isDeferred;
86864 #endif
86865 }
86866 
86867 /*
86868 ** Generate code that will erase and refill index *pIdx.  This is
86869 ** used to initialize a newly created index or to recompute the
86870 ** content of an index in response to a REINDEX command.
86871 **
86872 ** if memRootPage is not negative, it means that the index is newly
86873 ** created.  The register specified by memRootPage contains the
86874 ** root page number of the index.  If memRootPage is negative, then
86875 ** the index already exists and must be cleared before being refilled and
86876 ** the root page number of the index is taken from pIndex->tnum.
86877 */
86878 static void sqlite3RefillIndex(Parse *pParse, Index *pIndex, int memRootPage){
86879   Table *pTab = pIndex->pTable;  /* The table that is indexed */
86880   int iTab = pParse->nTab++;     /* Btree cursor used for pTab */
86881   int iIdx = pParse->nTab++;     /* Btree cursor used for pIndex */
86882   int iSorter;                   /* Cursor opened by OpenSorter (if in use) */
86883   int addr1;                     /* Address of top of loop */
86884   int addr2;                     /* Address to jump to for next iteration */
86885   int tnum;                      /* Root page of index */
86886   int iPartIdxLabel;             /* Jump to this label to skip a row */
86887   Vdbe *v;                       /* Generate code into this virtual machine */
86888   KeyInfo *pKey;                 /* KeyInfo for index */
86889   int regRecord;                 /* Register holding assemblied index record */
86890   sqlite3 *db = pParse->db;      /* The database connection */
86891   int iDb = sqlite3SchemaToIndex(db, pIndex->pSchema);
86892 
86893 #ifndef SQLITE_OMIT_AUTHORIZATION
86894   if( sqlite3AuthCheck(pParse, SQLITE_REINDEX, pIndex->zName, 0,
86895       db->aDb[iDb].zName ) ){
86896     return;
86897   }
86898 #endif
86899 
86900   /* Require a write-lock on the table to perform this operation */
86901   sqlite3TableLock(pParse, iDb, pTab->tnum, 1, pTab->zName);
86902 
86903   v = sqlite3GetVdbe(pParse);
86904   if( v==0 ) return;
86905   if( memRootPage>=0 ){
86906     tnum = memRootPage;
86907   }else{
86908     tnum = pIndex->tnum;
86909   }
86910   pKey = sqlite3KeyInfoOfIndex(pParse, pIndex);
86911 
86912   /* Open the sorter cursor if we are to use one. */
86913   iSorter = pParse->nTab++;
86914   sqlite3VdbeAddOp4(v, OP_SorterOpen, iSorter, 0, 0, (char*)
86915                     sqlite3KeyInfoRef(pKey), P4_KEYINFO);
86916 
86917   /* Open the table. Loop through all rows of the table, inserting index
86918   ** records into the sorter. */
86919   sqlite3OpenTable(pParse, iTab, iDb, pTab, OP_OpenRead);
86920   addr1 = sqlite3VdbeAddOp2(v, OP_Rewind, iTab, 0);
86921   regRecord = sqlite3GetTempReg(pParse);
86922 
86923   sqlite3GenerateIndexKey(pParse, pIndex, iTab, regRecord, 0, &iPartIdxLabel);
86924   sqlite3VdbeAddOp2(v, OP_SorterInsert, iSorter, regRecord);
86925   sqlite3VdbeResolveLabel(v, iPartIdxLabel);
86926   sqlite3VdbeAddOp2(v, OP_Next, iTab, addr1+1);
86927   sqlite3VdbeJumpHere(v, addr1);
86928   if( memRootPage<0 ) sqlite3VdbeAddOp2(v, OP_Clear, tnum, iDb);
86929   sqlite3VdbeAddOp4(v, OP_OpenWrite, iIdx, tnum, iDb, 
86930                     (char *)pKey, P4_KEYINFO);
86931   sqlite3VdbeChangeP5(v, OPFLAG_BULKCSR|((memRootPage>=0)?OPFLAG_P2ISREG:0));
86932 
86933   addr1 = sqlite3VdbeAddOp2(v, OP_SorterSort, iSorter, 0);
86934   assert( pKey!=0 || db->mallocFailed || pParse->nErr );
86935   if( pIndex->onError!=OE_None && pKey!=0 ){
86936     int j2 = sqlite3VdbeCurrentAddr(v) + 3;
86937     sqlite3VdbeAddOp2(v, OP_Goto, 0, j2);
86938     addr2 = sqlite3VdbeCurrentAddr(v);
86939     sqlite3VdbeAddOp4Int(v, OP_SorterCompare, iSorter, j2, regRecord,
86940                          pKey->nField - pIndex->nKeyCol);
86941     sqlite3UniqueConstraint(pParse, OE_Abort, pIndex);
86942   }else{
86943     addr2 = sqlite3VdbeCurrentAddr(v);
86944   }
86945   sqlite3VdbeAddOp2(v, OP_SorterData, iSorter, regRecord);
86946   sqlite3VdbeAddOp3(v, OP_IdxInsert, iIdx, regRecord, 1);
86947   sqlite3VdbeChangeP5(v, OPFLAG_USESEEKRESULT);
86948   sqlite3ReleaseTempReg(pParse, regRecord);
86949   sqlite3VdbeAddOp2(v, OP_SorterNext, iSorter, addr2);
86950   sqlite3VdbeJumpHere(v, addr1);
86951 
86952   sqlite3VdbeAddOp1(v, OP_Close, iTab);
86953   sqlite3VdbeAddOp1(v, OP_Close, iIdx);
86954   sqlite3VdbeAddOp1(v, OP_Close, iSorter);
86955 }
86956 
86957 /*
86958 ** Allocate heap space to hold an Index object with nCol columns.
86959 **
86960 ** Increase the allocation size to provide an extra nExtra bytes
86961 ** of 8-byte aligned space after the Index object and return a
86962 ** pointer to this extra space in *ppExtra.
86963 */
86964 SQLITE_PRIVATE Index *sqlite3AllocateIndexObject(
86965   sqlite3 *db,         /* Database connection */
86966   i16 nCol,            /* Total number of columns in the index */
86967   int nExtra,          /* Number of bytes of extra space to alloc */
86968   char **ppExtra       /* Pointer to the "extra" space */
86969 ){
86970   Index *p;            /* Allocated index object */
86971   int nByte;           /* Bytes of space for Index object + arrays */
86972 
86973   nByte = ROUND8(sizeof(Index)) +              /* Index structure  */
86974           ROUND8(sizeof(char*)*nCol) +         /* Index.azColl     */
86975           ROUND8(sizeof(tRowcnt)*(nCol+1) +    /* Index.aiRowEst   */
86976                  sizeof(i16)*nCol +            /* Index.aiColumn   */
86977                  sizeof(u8)*nCol);             /* Index.aSortOrder */
86978   p = sqlite3DbMallocZero(db, nByte + nExtra);
86979   if( p ){
86980     char *pExtra = ((char*)p)+ROUND8(sizeof(Index));
86981     p->azColl = (char**)pExtra;      pExtra += ROUND8(sizeof(char*)*nCol);
86982     p->aiRowEst = (tRowcnt*)pExtra;  pExtra += sizeof(tRowcnt)*(nCol+1);
86983     p->aiColumn = (i16*)pExtra;      pExtra += sizeof(i16)*nCol;
86984     p->aSortOrder = (u8*)pExtra;
86985     p->nColumn = nCol;
86986     p->nKeyCol = nCol - 1;
86987     *ppExtra = ((char*)p) + nByte;
86988   }
86989   return p;
86990 }
86991 
86992 /*
86993 ** Create a new index for an SQL table.  pName1.pName2 is the name of the index 
86994 ** and pTblList is the name of the table that is to be indexed.  Both will 
86995 ** be NULL for a primary key or an index that is created to satisfy a
86996 ** UNIQUE constraint.  If pTable and pIndex are NULL, use pParse->pNewTable
86997 ** as the table to be indexed.  pParse->pNewTable is a table that is
86998 ** currently being constructed by a CREATE TABLE statement.
86999 **
87000 ** pList is a list of columns to be indexed.  pList will be NULL if this
87001 ** is a primary key or unique-constraint on the most recent column added
87002 ** to the table currently under construction.  
87003 **
87004 ** If the index is created successfully, return a pointer to the new Index
87005 ** structure. This is used by sqlite3AddPrimaryKey() to mark the index
87006 ** as the tables primary key (Index.autoIndex==2).
87007 */
87008 SQLITE_PRIVATE Index *sqlite3CreateIndex(
87009   Parse *pParse,     /* All information about this parse */
87010   Token *pName1,     /* First part of index name. May be NULL */
87011   Token *pName2,     /* Second part of index name. May be NULL */
87012   SrcList *pTblName, /* Table to index. Use pParse->pNewTable if 0 */
87013   ExprList *pList,   /* A list of columns to be indexed */
87014   int onError,       /* OE_Abort, OE_Ignore, OE_Replace, or OE_None */
87015   Token *pStart,     /* The CREATE token that begins this statement */
87016   Expr *pPIWhere,    /* WHERE clause for partial indices */
87017   int sortOrder,     /* Sort order of primary key when pList==NULL */
87018   int ifNotExist     /* Omit error if index already exists */
87019 ){
87020   Index *pRet = 0;     /* Pointer to return */
87021   Table *pTab = 0;     /* Table to be indexed */
87022   Index *pIndex = 0;   /* The index to be created */
87023   char *zName = 0;     /* Name of the index */
87024   int nName;           /* Number of characters in zName */
87025   int i, j;
87026   DbFixer sFix;        /* For assigning database names to pTable */
87027   int sortOrderMask;   /* 1 to honor DESC in index.  0 to ignore. */
87028   sqlite3 *db = pParse->db;
87029   Db *pDb;             /* The specific table containing the indexed database */
87030   int iDb;             /* Index of the database that is being written */
87031   Token *pName = 0;    /* Unqualified name of the index to create */
87032   struct ExprList_item *pListItem; /* For looping over pList */
87033   const Column *pTabCol;           /* A column in the table */
87034   int nExtra = 0;                  /* Space allocated for zExtra[] */
87035   int nExtraCol;                   /* Number of extra columns needed */
87036   char *zExtra = 0;                /* Extra space after the Index object */
87037   Index *pPk = 0;      /* PRIMARY KEY index for WITHOUT ROWID tables */
87038 
87039   assert( pParse->nErr==0 );      /* Never called with prior errors */
87040   if( db->mallocFailed || IN_DECLARE_VTAB ){
87041     goto exit_create_index;
87042   }
87043   if( SQLITE_OK!=sqlite3ReadSchema(pParse) ){
87044     goto exit_create_index;
87045   }
87046 
87047   /*
87048   ** Find the table that is to be indexed.  Return early if not found.
87049   */
87050   if( pTblName!=0 ){
87051 
87052     /* Use the two-part index name to determine the database 
87053     ** to search for the table. 'Fix' the table name to this db
87054     ** before looking up the table.
87055     */
87056     assert( pName1 && pName2 );
87057     iDb = sqlite3TwoPartName(pParse, pName1, pName2, &pName);
87058     if( iDb<0 ) goto exit_create_index;
87059     assert( pName && pName->z );
87060 
87061 #ifndef SQLITE_OMIT_TEMPDB
87062     /* If the index name was unqualified, check if the table
87063     ** is a temp table. If so, set the database to 1. Do not do this
87064     ** if initialising a database schema.
87065     */
87066     if( !db->init.busy ){
87067       pTab = sqlite3SrcListLookup(pParse, pTblName);
87068       if( pName2->n==0 && pTab && pTab->pSchema==db->aDb[1].pSchema ){
87069         iDb = 1;
87070       }
87071     }
87072 #endif
87073 
87074     sqlite3FixInit(&sFix, pParse, iDb, "index", pName);
87075     if( sqlite3FixSrcList(&sFix, pTblName) ){
87076       /* Because the parser constructs pTblName from a single identifier,
87077       ** sqlite3FixSrcList can never fail. */
87078       assert(0);
87079     }
87080     pTab = sqlite3LocateTableItem(pParse, 0, &pTblName->a[0]);
87081     assert( db->mallocFailed==0 || pTab==0 );
87082     if( pTab==0 ) goto exit_create_index;
87083     if( iDb==1 && db->aDb[iDb].pSchema!=pTab->pSchema ){
87084       sqlite3ErrorMsg(pParse, 
87085            "cannot create a TEMP index on non-TEMP table \"%s\"",
87086            pTab->zName);
87087       goto exit_create_index;
87088     }
87089     if( !HasRowid(pTab) ) pPk = sqlite3PrimaryKeyIndex(pTab);
87090   }else{
87091     assert( pName==0 );
87092     assert( pStart==0 );
87093     pTab = pParse->pNewTable;
87094     if( !pTab ) goto exit_create_index;
87095     iDb = sqlite3SchemaToIndex(db, pTab->pSchema);
87096   }
87097   pDb = &db->aDb[iDb];
87098 
87099   assert( pTab!=0 );
87100   assert( pParse->nErr==0 );
87101   if( sqlite3StrNICmp(pTab->zName, "sqlite_", 7)==0 
87102        && sqlite3StrNICmp(&pTab->zName[7],"altertab_",9)!=0 ){
87103     sqlite3ErrorMsg(pParse, "table %s may not be indexed", pTab->zName);
87104     goto exit_create_index;
87105   }
87106 #ifndef SQLITE_OMIT_VIEW
87107   if( pTab->pSelect ){
87108     sqlite3ErrorMsg(pParse, "views may not be indexed");
87109     goto exit_create_index;
87110   }
87111 #endif
87112 #ifndef SQLITE_OMIT_VIRTUALTABLE
87113   if( IsVirtual(pTab) ){
87114     sqlite3ErrorMsg(pParse, "virtual tables may not be indexed");
87115     goto exit_create_index;
87116   }
87117 #endif
87118 
87119   /*
87120   ** Find the name of the index.  Make sure there is not already another
87121   ** index or table with the same name.  
87122   **
87123   ** Exception:  If we are reading the names of permanent indices from the
87124   ** sqlite_master table (because some other process changed the schema) and
87125   ** one of the index names collides with the name of a temporary table or
87126   ** index, then we will continue to process this index.
87127   **
87128   ** If pName==0 it means that we are
87129   ** dealing with a primary key or UNIQUE constraint.  We have to invent our
87130   ** own name.
87131   */
87132   if( pName ){
87133     zName = sqlite3NameFromToken(db, pName);
87134     if( zName==0 ) goto exit_create_index;
87135     assert( pName->z!=0 );
87136     if( SQLITE_OK!=sqlite3CheckObjectName(pParse, zName) ){
87137       goto exit_create_index;
87138     }
87139     if( !db->init.busy ){
87140       if( sqlite3FindTable(db, zName, 0)!=0 ){
87141         sqlite3ErrorMsg(pParse, "there is already a table named %s", zName);
87142         goto exit_create_index;
87143       }
87144     }
87145     if( sqlite3FindIndex(db, zName, pDb->zName)!=0 ){
87146       if( !ifNotExist ){
87147         sqlite3ErrorMsg(pParse, "index %s already exists", zName);
87148       }else{
87149         assert( !db->init.busy );
87150         sqlite3CodeVerifySchema(pParse, iDb);
87151       }
87152       goto exit_create_index;
87153     }
87154   }else{
87155     int n;
87156     Index *pLoop;
87157     for(pLoop=pTab->pIndex, n=1; pLoop; pLoop=pLoop->pNext, n++){}
87158     zName = sqlite3MPrintf(db, "sqlite_autoindex_%s_%d", pTab->zName, n);
87159     if( zName==0 ){
87160       goto exit_create_index;
87161     }
87162   }
87163 
87164   /* Check for authorization to create an index.
87165   */
87166 #ifndef SQLITE_OMIT_AUTHORIZATION
87167   {
87168     const char *zDb = pDb->zName;
87169     if( sqlite3AuthCheck(pParse, SQLITE_INSERT, SCHEMA_TABLE(iDb), 0, zDb) ){
87170       goto exit_create_index;
87171     }
87172     i = SQLITE_CREATE_INDEX;
87173     if( !OMIT_TEMPDB && iDb==1 ) i = SQLITE_CREATE_TEMP_INDEX;
87174     if( sqlite3AuthCheck(pParse, i, zName, pTab->zName, zDb) ){
87175       goto exit_create_index;
87176     }
87177   }
87178 #endif
87179 
87180   /* If pList==0, it means this routine was called to make a primary
87181   ** key out of the last column added to the table under construction.
87182   ** So create a fake list to simulate this.
87183   */
87184   if( pList==0 ){
87185     pList = sqlite3ExprListAppend(pParse, 0, 0);
87186     if( pList==0 ) goto exit_create_index;
87187     pList->a[0].zName = sqlite3DbStrDup(pParse->db,
87188                                         pTab->aCol[pTab->nCol-1].zName);
87189     pList->a[0].sortOrder = (u8)sortOrder;
87190   }
87191 
87192   /* Figure out how many bytes of space are required to store explicitly
87193   ** specified collation sequence names.
87194   */
87195   for(i=0; i<pList->nExpr; i++){
87196     Expr *pExpr = pList->a[i].pExpr;
87197     if( pExpr ){
87198       assert( pExpr->op==TK_COLLATE );
87199       nExtra += (1 + sqlite3Strlen30(pExpr->u.zToken));
87200     }
87201   }
87202 
87203   /* 
87204   ** Allocate the index structure. 
87205   */
87206   nName = sqlite3Strlen30(zName);
87207   nExtraCol = pPk ? pPk->nKeyCol : 1;
87208   pIndex = sqlite3AllocateIndexObject(db, pList->nExpr + nExtraCol,
87209                                       nName + nExtra + 1, &zExtra);
87210   if( db->mallocFailed ){
87211     goto exit_create_index;
87212   }
87213   assert( EIGHT_BYTE_ALIGNMENT(pIndex->aiRowEst) );
87214   assert( EIGHT_BYTE_ALIGNMENT(pIndex->azColl) );
87215   pIndex->zName = zExtra;
87216   zExtra += nName + 1;
87217   memcpy(pIndex->zName, zName, nName+1);
87218   pIndex->pTable = pTab;
87219   pIndex->onError = (u8)onError;
87220   pIndex->uniqNotNull = onError!=OE_None;
87221   pIndex->autoIndex = (u8)(pName==0);
87222   pIndex->pSchema = db->aDb[iDb].pSchema;
87223   pIndex->nKeyCol = pList->nExpr;
87224   if( pPIWhere ){
87225     sqlite3ResolveSelfReference(pParse, pTab, NC_PartIdx, pPIWhere, 0);
87226     pIndex->pPartIdxWhere = pPIWhere;
87227     pPIWhere = 0;
87228   }
87229   assert( sqlite3SchemaMutexHeld(db, iDb, 0) );
87230 
87231   /* Check to see if we should honor DESC requests on index columns
87232   */
87233   if( pDb->pSchema->file_format>=4 ){
87234     sortOrderMask = -1;   /* Honor DESC */
87235   }else{
87236     sortOrderMask = 0;    /* Ignore DESC */
87237   }
87238 
87239   /* Scan the names of the columns of the table to be indexed and
87240   ** load the column indices into the Index structure.  Report an error
87241   ** if any column is not found.
87242   **
87243   ** TODO:  Add a test to make sure that the same column is not named
87244   ** more than once within the same index.  Only the first instance of
87245   ** the column will ever be used by the optimizer.  Note that using the
87246   ** same column more than once cannot be an error because that would 
87247   ** break backwards compatibility - it needs to be a warning.
87248   */
87249   for(i=0, pListItem=pList->a; i<pList->nExpr; i++, pListItem++){
87250     const char *zColName = pListItem->zName;
87251     int requestedSortOrder;
87252     char *zColl;                   /* Collation sequence name */
87253 
87254     for(j=0, pTabCol=pTab->aCol; j<pTab->nCol; j++, pTabCol++){
87255       if( sqlite3StrICmp(zColName, pTabCol->zName)==0 ) break;
87256     }
87257     if( j>=pTab->nCol ){
87258       sqlite3ErrorMsg(pParse, "table %s has no column named %s",
87259         pTab->zName, zColName);
87260       pParse->checkSchema = 1;
87261       goto exit_create_index;
87262     }
87263     assert( pTab->nCol<=0x7fff && j<=0x7fff );
87264     pIndex->aiColumn[i] = (i16)j;
87265     if( pListItem->pExpr ){
87266       int nColl;
87267       assert( pListItem->pExpr->op==TK_COLLATE );
87268       zColl = pListItem->pExpr->u.zToken;
87269       nColl = sqlite3Strlen30(zColl) + 1;
87270       assert( nExtra>=nColl );
87271       memcpy(zExtra, zColl, nColl);
87272       zColl = zExtra;
87273       zExtra += nColl;
87274       nExtra -= nColl;
87275     }else{
87276       zColl = pTab->aCol[j].zColl;
87277       if( !zColl ) zColl = "BINARY";
87278     }
87279     if( !db->init.busy && !sqlite3LocateCollSeq(pParse, zColl) ){
87280       goto exit_create_index;
87281     }
87282     pIndex->azColl[i] = zColl;
87283     requestedSortOrder = pListItem->sortOrder & sortOrderMask;
87284     pIndex->aSortOrder[i] = (u8)requestedSortOrder;
87285     if( pTab->aCol[j].notNull==0 ) pIndex->uniqNotNull = 0;
87286   }
87287   if( pPk ){
87288     for(j=0; j<pPk->nKeyCol; j++){
87289       int x = pPk->aiColumn[j];
87290       if( hasColumn(pIndex->aiColumn, pIndex->nKeyCol, x) ){
87291         pIndex->nColumn--; 
87292       }else{
87293         pIndex->aiColumn[i] = x;
87294         pIndex->azColl[i] = pPk->azColl[j];
87295         pIndex->aSortOrder[i] = pPk->aSortOrder[j];
87296         i++;
87297       }
87298     }
87299     assert( i==pIndex->nColumn );
87300   }else{
87301     pIndex->aiColumn[i] = -1;
87302     pIndex->azColl[i] = "BINARY";
87303   }
87304   sqlite3DefaultRowEst(pIndex);
87305   if( pParse->pNewTable==0 ) estimateIndexWidth(pIndex);
87306 
87307   if( pTab==pParse->pNewTable ){
87308     /* This routine has been called to create an automatic index as a
87309     ** result of a PRIMARY KEY or UNIQUE clause on a column definition, or
87310     ** a PRIMARY KEY or UNIQUE clause following the column definitions.
87311     ** i.e. one of:
87312     **
87313     ** CREATE TABLE t(x PRIMARY KEY, y);
87314     ** CREATE TABLE t(x, y, UNIQUE(x, y));
87315     **
87316     ** Either way, check to see if the table already has such an index. If
87317     ** so, don't bother creating this one. This only applies to
87318     ** automatically created indices. Users can do as they wish with
87319     ** explicit indices.
87320     **
87321     ** Two UNIQUE or PRIMARY KEY constraints are considered equivalent
87322     ** (and thus suppressing the second one) even if they have different
87323     ** sort orders.
87324     **
87325     ** If there are different collating sequences or if the columns of
87326     ** the constraint occur in different orders, then the constraints are
87327     ** considered distinct and both result in separate indices.
87328     */
87329     Index *pIdx;
87330     for(pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext){
87331       int k;
87332       assert( pIdx->onError!=OE_None );
87333       assert( pIdx->autoIndex );
87334       assert( pIndex->onError!=OE_None );
87335 
87336       if( pIdx->nKeyCol!=pIndex->nKeyCol ) continue;
87337       for(k=0; k<pIdx->nKeyCol; k++){
87338         const char *z1;
87339         const char *z2;
87340         if( pIdx->aiColumn[k]!=pIndex->aiColumn[k] ) break;
87341         z1 = pIdx->azColl[k];
87342         z2 = pIndex->azColl[k];
87343         if( z1!=z2 && sqlite3StrICmp(z1, z2) ) break;
87344       }
87345       if( k==pIdx->nKeyCol ){
87346         if( pIdx->onError!=pIndex->onError ){
87347           /* This constraint creates the same index as a previous
87348           ** constraint specified somewhere in the CREATE TABLE statement.
87349           ** However the ON CONFLICT clauses are different. If both this 
87350           ** constraint and the previous equivalent constraint have explicit
87351           ** ON CONFLICT clauses this is an error. Otherwise, use the
87352           ** explicitly specified behavior for the index.
87353           */
87354           if( !(pIdx->onError==OE_Default || pIndex->onError==OE_Default) ){
87355             sqlite3ErrorMsg(pParse, 
87356                 "conflicting ON CONFLICT clauses specified", 0);
87357           }
87358           if( pIdx->onError==OE_Default ){
87359             pIdx->onError = pIndex->onError;
87360           }
87361         }
87362         goto exit_create_index;
87363       }
87364     }
87365   }
87366 
87367   /* Link the new Index structure to its table and to the other
87368   ** in-memory database structures. 
87369   */
87370   if( db->init.busy ){
87371     Index *p;
87372     assert( sqlite3SchemaMutexHeld(db, 0, pIndex->pSchema) );
87373     p = sqlite3HashInsert(&pIndex->pSchema->idxHash, 
87374                           pIndex->zName, sqlite3Strlen30(pIndex->zName),
87375                           pIndex);
87376     if( p ){
87377       assert( p==pIndex );  /* Malloc must have failed */
87378       db->mallocFailed = 1;
87379       goto exit_create_index;
87380     }
87381     db->flags |= SQLITE_InternChanges;
87382     if( pTblName!=0 ){
87383       pIndex->tnum = db->init.newTnum;
87384     }
87385   }
87386 
87387   /* If this is the initial CREATE INDEX statement (or CREATE TABLE if the
87388   ** index is an implied index for a UNIQUE or PRIMARY KEY constraint) then
87389   ** emit code to allocate the index rootpage on disk and make an entry for
87390   ** the index in the sqlite_master table and populate the index with
87391   ** content.  But, do not do this if we are simply reading the sqlite_master
87392   ** table to parse the schema, or if this index is the PRIMARY KEY index
87393   ** of a WITHOUT ROWID table.
87394   **
87395   ** If pTblName==0 it means this index is generated as an implied PRIMARY KEY
87396   ** or UNIQUE index in a CREATE TABLE statement.  Since the table
87397   ** has just been created, it contains no data and the index initialization
87398   ** step can be skipped.
87399   */
87400   else if( pParse->nErr==0 && (HasRowid(pTab) || pTblName!=0) ){
87401     Vdbe *v;
87402     char *zStmt;
87403     int iMem = ++pParse->nMem;
87404 
87405     v = sqlite3GetVdbe(pParse);
87406     if( v==0 ) goto exit_create_index;
87407 
87408 
87409     /* Create the rootpage for the index
87410     */
87411     sqlite3BeginWriteOperation(pParse, 1, iDb);
87412     sqlite3VdbeAddOp2(v, OP_CreateIndex, iDb, iMem);
87413 
87414     /* Gather the complete text of the CREATE INDEX statement into
87415     ** the zStmt variable
87416     */
87417     if( pStart ){
87418       int n = (int)(pParse->sLastToken.z - pName->z) + pParse->sLastToken.n;
87419       if( pName->z[n-1]==';' ) n--;
87420       /* A named index with an explicit CREATE INDEX statement */
87421       zStmt = sqlite3MPrintf(db, "CREATE%s INDEX %.*s",
87422         onError==OE_None ? "" : " UNIQUE", n, pName->z);
87423     }else{
87424       /* An automatic index created by a PRIMARY KEY or UNIQUE constraint */
87425       /* zStmt = sqlite3MPrintf(""); */
87426       zStmt = 0;
87427     }
87428 
87429     /* Add an entry in sqlite_master for this index
87430     */
87431     sqlite3NestedParse(pParse, 
87432         "INSERT INTO %Q.%s VALUES('index',%Q,%Q,#%d,%Q);",
87433         db->aDb[iDb].zName, SCHEMA_TABLE(iDb),
87434         pIndex->zName,
87435         pTab->zName,
87436         iMem,
87437         zStmt
87438     );
87439     sqlite3DbFree(db, zStmt);
87440 
87441     /* Fill the index with data and reparse the schema. Code an OP_Expire
87442     ** to invalidate all pre-compiled statements.
87443     */
87444     if( pTblName ){
87445       sqlite3RefillIndex(pParse, pIndex, iMem);
87446       sqlite3ChangeCookie(pParse, iDb);
87447       sqlite3VdbeAddParseSchemaOp(v, iDb,
87448          sqlite3MPrintf(db, "name='%q' AND type='index'", pIndex->zName));
87449       sqlite3VdbeAddOp1(v, OP_Expire, 0);
87450     }
87451   }
87452 
87453   /* When adding an index to the list of indices for a table, make
87454   ** sure all indices labeled OE_Replace come after all those labeled
87455   ** OE_Ignore.  This is necessary for the correct constraint check
87456   ** processing (in sqlite3GenerateConstraintChecks()) as part of
87457   ** UPDATE and INSERT statements.  
87458   */
87459   if( db->init.busy || pTblName==0 ){
87460     if( onError!=OE_Replace || pTab->pIndex==0
87461          || pTab->pIndex->onError==OE_Replace){
87462       pIndex->pNext = pTab->pIndex;
87463       pTab->pIndex = pIndex;
87464     }else{
87465       Index *pOther = pTab->pIndex;
87466       while( pOther->pNext && pOther->pNext->onError!=OE_Replace ){
87467         pOther = pOther->pNext;
87468       }
87469       pIndex->pNext = pOther->pNext;
87470       pOther->pNext = pIndex;
87471     }
87472     pRet = pIndex;
87473     pIndex = 0;
87474   }
87475 
87476   /* Clean up before exiting */
87477 exit_create_index:
87478   if( pIndex ) freeIndex(db, pIndex);
87479   sqlite3ExprDelete(db, pPIWhere);
87480   sqlite3ExprListDelete(db, pList);
87481   sqlite3SrcListDelete(db, pTblName);
87482   sqlite3DbFree(db, zName);
87483   return pRet;
87484 }
87485 
87486 /*
87487 ** Fill the Index.aiRowEst[] array with default information - information
87488 ** to be used when we have not run the ANALYZE command.
87489 **
87490 ** aiRowEst[0] is suppose to contain the number of elements in the index.
87491 ** Since we do not know, guess 1 million.  aiRowEst[1] is an estimate of the
87492 ** number of rows in the table that match any particular value of the
87493 ** first column of the index.  aiRowEst[2] is an estimate of the number
87494 ** of rows that match any particular combiniation of the first 2 columns
87495 ** of the index.  And so forth.  It must always be the case that
87496 *
87497 **           aiRowEst[N]<=aiRowEst[N-1]
87498 **           aiRowEst[N]>=1
87499 **
87500 ** Apart from that, we have little to go on besides intuition as to
87501 ** how aiRowEst[] should be initialized.  The numbers generated here
87502 ** are based on typical values found in actual indices.
87503 */
87504 SQLITE_PRIVATE void sqlite3DefaultRowEst(Index *pIdx){
87505   tRowcnt *a = pIdx->aiRowEst;
87506   int i;
87507   tRowcnt n;
87508   assert( a!=0 );
87509   a[0] = pIdx->pTable->nRowEst;
87510   if( a[0]<10 ) a[0] = 10;
87511   n = 10;
87512   for(i=1; i<=pIdx->nKeyCol; i++){
87513     a[i] = n;
87514     if( n>5 ) n--;
87515   }
87516   if( pIdx->onError!=OE_None ){
87517     a[pIdx->nKeyCol] = 1;
87518   }
87519 }
87520 
87521 /*
87522 ** This routine will drop an existing named index.  This routine
87523 ** implements the DROP INDEX statement.
87524 */
87525 SQLITE_PRIVATE void sqlite3DropIndex(Parse *pParse, SrcList *pName, int ifExists){
87526   Index *pIndex;
87527   Vdbe *v;
87528   sqlite3 *db = pParse->db;
87529   int iDb;
87530 
87531   assert( pParse->nErr==0 );   /* Never called with prior errors */
87532   if( db->mallocFailed ){
87533     goto exit_drop_index;
87534   }
87535   assert( pName->nSrc==1 );
87536   if( SQLITE_OK!=sqlite3ReadSchema(pParse) ){
87537     goto exit_drop_index;
87538   }
87539   pIndex = sqlite3FindIndex(db, pName->a[0].zName, pName->a[0].zDatabase);
87540   if( pIndex==0 ){
87541     if( !ifExists ){
87542       sqlite3ErrorMsg(pParse, "no such index: %S", pName, 0);
87543     }else{
87544       sqlite3CodeVerifyNamedSchema(pParse, pName->a[0].zDatabase);
87545     }
87546     pParse->checkSchema = 1;
87547     goto exit_drop_index;
87548   }
87549   if( pIndex->autoIndex ){
87550     sqlite3ErrorMsg(pParse, "index associated with UNIQUE "
87551       "or PRIMARY KEY constraint cannot be dropped", 0);
87552     goto exit_drop_index;
87553   }
87554   iDb = sqlite3SchemaToIndex(db, pIndex->pSchema);
87555 #ifndef SQLITE_OMIT_AUTHORIZATION
87556   {
87557     int code = SQLITE_DROP_INDEX;
87558     Table *pTab = pIndex->pTable;
87559     const char *zDb = db->aDb[iDb].zName;
87560     const char *zTab = SCHEMA_TABLE(iDb);
87561     if( sqlite3AuthCheck(pParse, SQLITE_DELETE, zTab, 0, zDb) ){
87562       goto exit_drop_index;
87563     }
87564     if( !OMIT_TEMPDB && iDb ) code = SQLITE_DROP_TEMP_INDEX;
87565     if( sqlite3AuthCheck(pParse, code, pIndex->zName, pTab->zName, zDb) ){
87566       goto exit_drop_index;
87567     }
87568   }
87569 #endif
87570 
87571   /* Generate code to remove the index and from the master table */
87572   v = sqlite3GetVdbe(pParse);
87573   if( v ){
87574     sqlite3BeginWriteOperation(pParse, 1, iDb);
87575     sqlite3NestedParse(pParse,
87576        "DELETE FROM %Q.%s WHERE name=%Q AND type='index'",
87577        db->aDb[iDb].zName, SCHEMA_TABLE(iDb), pIndex->zName
87578     );
87579     sqlite3ClearStatTables(pParse, iDb, "idx", pIndex->zName);
87580     sqlite3ChangeCookie(pParse, iDb);
87581     destroyRootPage(pParse, pIndex->tnum, iDb);
87582     sqlite3VdbeAddOp4(v, OP_DropIndex, iDb, 0, 0, pIndex->zName, 0);
87583   }
87584 
87585 exit_drop_index:
87586   sqlite3SrcListDelete(db, pName);
87587 }
87588 
87589 /*
87590 ** pArray is a pointer to an array of objects. Each object in the
87591 ** array is szEntry bytes in size. This routine uses sqlite3DbRealloc()
87592 ** to extend the array so that there is space for a new object at the end.
87593 **
87594 ** When this function is called, *pnEntry contains the current size of
87595 ** the array (in entries - so the allocation is ((*pnEntry) * szEntry) bytes
87596 ** in total).
87597 **
87598 ** If the realloc() is successful (i.e. if no OOM condition occurs), the
87599 ** space allocated for the new object is zeroed, *pnEntry updated to
87600 ** reflect the new size of the array and a pointer to the new allocation
87601 ** returned. *pIdx is set to the index of the new array entry in this case.
87602 **
87603 ** Otherwise, if the realloc() fails, *pIdx is set to -1, *pnEntry remains
87604 ** unchanged and a copy of pArray returned.
87605 */
87606 SQLITE_PRIVATE void *sqlite3ArrayAllocate(
87607   sqlite3 *db,      /* Connection to notify of malloc failures */
87608   void *pArray,     /* Array of objects.  Might be reallocated */
87609   int szEntry,      /* Size of each object in the array */
87610   int *pnEntry,     /* Number of objects currently in use */
87611   int *pIdx         /* Write the index of a new slot here */
87612 ){
87613   char *z;
87614   int n = *pnEntry;
87615   if( (n & (n-1))==0 ){
87616     int sz = (n==0) ? 1 : 2*n;
87617     void *pNew = sqlite3DbRealloc(db, pArray, sz*szEntry);
87618     if( pNew==0 ){
87619       *pIdx = -1;
87620       return pArray;
87621     }
87622     pArray = pNew;
87623   }
87624   z = (char*)pArray;
87625   memset(&z[n * szEntry], 0, szEntry);
87626   *pIdx = n;
87627   ++*pnEntry;
87628   return pArray;
87629 }
87630 
87631 /*
87632 ** Append a new element to the given IdList.  Create a new IdList if
87633 ** need be.
87634 **
87635 ** A new IdList is returned, or NULL if malloc() fails.
87636 */
87637 SQLITE_PRIVATE IdList *sqlite3IdListAppend(sqlite3 *db, IdList *pList, Token *pToken){
87638   int i;
87639   if( pList==0 ){
87640     pList = sqlite3DbMallocZero(db, sizeof(IdList) );
87641     if( pList==0 ) return 0;
87642   }
87643   pList->a = sqlite3ArrayAllocate(
87644       db,
87645       pList->a,
87646       sizeof(pList->a[0]),
87647       &pList->nId,
87648       &i
87649   );
87650   if( i<0 ){
87651     sqlite3IdListDelete(db, pList);
87652     return 0;
87653   }
87654   pList->a[i].zName = sqlite3NameFromToken(db, pToken);
87655   return pList;
87656 }
87657 
87658 /*
87659 ** Delete an IdList.
87660 */
87661 SQLITE_PRIVATE void sqlite3IdListDelete(sqlite3 *db, IdList *pList){
87662   int i;
87663   if( pList==0 ) return;
87664   for(i=0; i<pList->nId; i++){
87665     sqlite3DbFree(db, pList->a[i].zName);
87666   }
87667   sqlite3DbFree(db, pList->a);
87668   sqlite3DbFree(db, pList);
87669 }
87670 
87671 /*
87672 ** Return the index in pList of the identifier named zId.  Return -1
87673 ** if not found.
87674 */
87675 SQLITE_PRIVATE int sqlite3IdListIndex(IdList *pList, const char *zName){
87676   int i;
87677   if( pList==0 ) return -1;
87678   for(i=0; i<pList->nId; i++){
87679     if( sqlite3StrICmp(pList->a[i].zName, zName)==0 ) return i;
87680   }
87681   return -1;
87682 }
87683 
87684 /*
87685 ** Expand the space allocated for the given SrcList object by
87686 ** creating nExtra new slots beginning at iStart.  iStart is zero based.
87687 ** New slots are zeroed.
87688 **
87689 ** For example, suppose a SrcList initially contains two entries: A,B.
87690 ** To append 3 new entries onto the end, do this:
87691 **
87692 **    sqlite3SrcListEnlarge(db, pSrclist, 3, 2);
87693 **
87694 ** After the call above it would contain:  A, B, nil, nil, nil.
87695 ** If the iStart argument had been 1 instead of 2, then the result
87696 ** would have been:  A, nil, nil, nil, B.  To prepend the new slots,
87697 ** the iStart value would be 0.  The result then would
87698 ** be: nil, nil, nil, A, B.
87699 **
87700 ** If a memory allocation fails the SrcList is unchanged.  The
87701 ** db->mallocFailed flag will be set to true.
87702 */
87703 SQLITE_PRIVATE SrcList *sqlite3SrcListEnlarge(
87704   sqlite3 *db,       /* Database connection to notify of OOM errors */
87705   SrcList *pSrc,     /* The SrcList to be enlarged */
87706   int nExtra,        /* Number of new slots to add to pSrc->a[] */
87707   int iStart         /* Index in pSrc->a[] of first new slot */
87708 ){
87709   int i;
87710 
87711   /* Sanity checking on calling parameters */
87712   assert( iStart>=0 );
87713   assert( nExtra>=1 );
87714   assert( pSrc!=0 );
87715   assert( iStart<=pSrc->nSrc );
87716 
87717   /* Allocate additional space if needed */
87718   if( pSrc->nSrc+nExtra>pSrc->nAlloc ){
87719     SrcList *pNew;
87720     int nAlloc = pSrc->nSrc+nExtra;
87721     int nGot;
87722     pNew = sqlite3DbRealloc(db, pSrc,
87723                sizeof(*pSrc) + (nAlloc-1)*sizeof(pSrc->a[0]) );
87724     if( pNew==0 ){
87725       assert( db->mallocFailed );
87726       return pSrc;
87727     }
87728     pSrc = pNew;
87729     nGot = (sqlite3DbMallocSize(db, pNew) - sizeof(*pSrc))/sizeof(pSrc->a[0])+1;
87730     pSrc->nAlloc = (u8)nGot;
87731   }
87732 
87733   /* Move existing slots that come after the newly inserted slots
87734   ** out of the way */
87735   for(i=pSrc->nSrc-1; i>=iStart; i--){
87736     pSrc->a[i+nExtra] = pSrc->a[i];
87737   }
87738   pSrc->nSrc += (i8)nExtra;
87739 
87740   /* Zero the newly allocated slots */
87741   memset(&pSrc->a[iStart], 0, sizeof(pSrc->a[0])*nExtra);
87742   for(i=iStart; i<iStart+nExtra; i++){
87743     pSrc->a[i].iCursor = -1;
87744   }
87745 
87746   /* Return a pointer to the enlarged SrcList */
87747   return pSrc;
87748 }
87749 
87750 
87751 /*
87752 ** Append a new table name to the given SrcList.  Create a new SrcList if
87753 ** need be.  A new entry is created in the SrcList even if pTable is NULL.
87754 **
87755 ** A SrcList is returned, or NULL if there is an OOM error.  The returned
87756 ** SrcList might be the same as the SrcList that was input or it might be
87757 ** a new one.  If an OOM error does occurs, then the prior value of pList
87758 ** that is input to this routine is automatically freed.
87759 **
87760 ** If pDatabase is not null, it means that the table has an optional
87761 ** database name prefix.  Like this:  "database.table".  The pDatabase
87762 ** points to the table name and the pTable points to the database name.
87763 ** The SrcList.a[].zName field is filled with the table name which might
87764 ** come from pTable (if pDatabase is NULL) or from pDatabase.  
87765 ** SrcList.a[].zDatabase is filled with the database name from pTable,
87766 ** or with NULL if no database is specified.
87767 **
87768 ** In other words, if call like this:
87769 **
87770 **         sqlite3SrcListAppend(D,A,B,0);
87771 **
87772 ** Then B is a table name and the database name is unspecified.  If called
87773 ** like this:
87774 **
87775 **         sqlite3SrcListAppend(D,A,B,C);
87776 **
87777 ** Then C is the table name and B is the database name.  If C is defined
87778 ** then so is B.  In other words, we never have a case where:
87779 **
87780 **         sqlite3SrcListAppend(D,A,0,C);
87781 **
87782 ** Both pTable and pDatabase are assumed to be quoted.  They are dequoted
87783 ** before being added to the SrcList.
87784 */
87785 SQLITE_PRIVATE SrcList *sqlite3SrcListAppend(
87786   sqlite3 *db,        /* Connection to notify of malloc failures */
87787   SrcList *pList,     /* Append to this SrcList. NULL creates a new SrcList */
87788   Token *pTable,      /* Table to append */
87789   Token *pDatabase    /* Database of the table */
87790 ){
87791   struct SrcList_item *pItem;
87792   assert( pDatabase==0 || pTable!=0 );  /* Cannot have C without B */
87793   if( pList==0 ){
87794     pList = sqlite3DbMallocZero(db, sizeof(SrcList) );
87795     if( pList==0 ) return 0;
87796     pList->nAlloc = 1;
87797   }
87798   pList = sqlite3SrcListEnlarge(db, pList, 1, pList->nSrc);
87799   if( db->mallocFailed ){
87800     sqlite3SrcListDelete(db, pList);
87801     return 0;
87802   }
87803   pItem = &pList->a[pList->nSrc-1];
87804   if( pDatabase && pDatabase->z==0 ){
87805     pDatabase = 0;
87806   }
87807   if( pDatabase ){
87808     Token *pTemp = pDatabase;
87809     pDatabase = pTable;
87810     pTable = pTemp;
87811   }
87812   pItem->zName = sqlite3NameFromToken(db, pTable);
87813   pItem->zDatabase = sqlite3NameFromToken(db, pDatabase);
87814   return pList;
87815 }
87816 
87817 /*
87818 ** Assign VdbeCursor index numbers to all tables in a SrcList
87819 */
87820 SQLITE_PRIVATE void sqlite3SrcListAssignCursors(Parse *pParse, SrcList *pList){
87821   int i;
87822   struct SrcList_item *pItem;
87823   assert(pList || pParse->db->mallocFailed );
87824   if( pList ){
87825     for(i=0, pItem=pList->a; i<pList->nSrc; i++, pItem++){
87826       if( pItem->iCursor>=0 ) break;
87827       pItem->iCursor = pParse->nTab++;
87828       if( pItem->pSelect ){
87829         sqlite3SrcListAssignCursors(pParse, pItem->pSelect->pSrc);
87830       }
87831     }
87832   }
87833 }
87834 
87835 /*
87836 ** Delete an entire SrcList including all its substructure.
87837 */
87838 SQLITE_PRIVATE void sqlite3SrcListDelete(sqlite3 *db, SrcList *pList){
87839   int i;
87840   struct SrcList_item *pItem;
87841   if( pList==0 ) return;
87842   for(pItem=pList->a, i=0; i<pList->nSrc; i++, pItem++){
87843     sqlite3DbFree(db, pItem->zDatabase);
87844     sqlite3DbFree(db, pItem->zName);
87845     sqlite3DbFree(db, pItem->zAlias);
87846     sqlite3DbFree(db, pItem->zIndex);
87847     sqlite3DeleteTable(db, pItem->pTab);
87848     sqlite3SelectDelete(db, pItem->pSelect);
87849     sqlite3ExprDelete(db, pItem->pOn);
87850     sqlite3IdListDelete(db, pItem->pUsing);
87851   }
87852   sqlite3DbFree(db, pList);
87853 }
87854 
87855 /*
87856 ** This routine is called by the parser to add a new term to the
87857 ** end of a growing FROM clause.  The "p" parameter is the part of
87858 ** the FROM clause that has already been constructed.  "p" is NULL
87859 ** if this is the first term of the FROM clause.  pTable and pDatabase
87860 ** are the name of the table and database named in the FROM clause term.
87861 ** pDatabase is NULL if the database name qualifier is missing - the
87862 ** usual case.  If the term has a alias, then pAlias points to the
87863 ** alias token.  If the term is a subquery, then pSubquery is the
87864 ** SELECT statement that the subquery encodes.  The pTable and
87865 ** pDatabase parameters are NULL for subqueries.  The pOn and pUsing
87866 ** parameters are the content of the ON and USING clauses.
87867 **
87868 ** Return a new SrcList which encodes is the FROM with the new
87869 ** term added.
87870 */
87871 SQLITE_PRIVATE SrcList *sqlite3SrcListAppendFromTerm(
87872   Parse *pParse,          /* Parsing context */
87873   SrcList *p,             /* The left part of the FROM clause already seen */
87874   Token *pTable,          /* Name of the table to add to the FROM clause */
87875   Token *pDatabase,       /* Name of the database containing pTable */
87876   Token *pAlias,          /* The right-hand side of the AS subexpression */
87877   Select *pSubquery,      /* A subquery used in place of a table name */
87878   Expr *pOn,              /* The ON clause of a join */
87879   IdList *pUsing          /* The USING clause of a join */
87880 ){
87881   struct SrcList_item *pItem;
87882   sqlite3 *db = pParse->db;
87883   if( !p && (pOn || pUsing) ){
87884     sqlite3ErrorMsg(pParse, "a JOIN clause is required before %s", 
87885       (pOn ? "ON" : "USING")
87886     );
87887     goto append_from_error;
87888   }
87889   p = sqlite3SrcListAppend(db, p, pTable, pDatabase);
87890   if( p==0 || NEVER(p->nSrc==0) ){
87891     goto append_from_error;
87892   }
87893   pItem = &p->a[p->nSrc-1];
87894   assert( pAlias!=0 );
87895   if( pAlias->n ){
87896     pItem->zAlias = sqlite3NameFromToken(db, pAlias);
87897   }
87898   pItem->pSelect = pSubquery;
87899   pItem->pOn = pOn;
87900   pItem->pUsing = pUsing;
87901   return p;
87902 
87903  append_from_error:
87904   assert( p==0 );
87905   sqlite3ExprDelete(db, pOn);
87906   sqlite3IdListDelete(db, pUsing);
87907   sqlite3SelectDelete(db, pSubquery);
87908   return 0;
87909 }
87910 
87911 /*
87912 ** Add an INDEXED BY or NOT INDEXED clause to the most recently added 
87913 ** element of the source-list passed as the second argument.
87914 */
87915 SQLITE_PRIVATE void sqlite3SrcListIndexedBy(Parse *pParse, SrcList *p, Token *pIndexedBy){
87916   assert( pIndexedBy!=0 );
87917   if( p && ALWAYS(p->nSrc>0) ){
87918     struct SrcList_item *pItem = &p->a[p->nSrc-1];
87919     assert( pItem->notIndexed==0 && pItem->zIndex==0 );
87920     if( pIndexedBy->n==1 && !pIndexedBy->z ){
87921       /* A "NOT INDEXED" clause was supplied. See parse.y 
87922       ** construct "indexed_opt" for details. */
87923       pItem->notIndexed = 1;
87924     }else{
87925       pItem->zIndex = sqlite3NameFromToken(pParse->db, pIndexedBy);
87926     }
87927   }
87928 }
87929 
87930 /*
87931 ** When building up a FROM clause in the parser, the join operator
87932 ** is initially attached to the left operand.  But the code generator
87933 ** expects the join operator to be on the right operand.  This routine
87934 ** Shifts all join operators from left to right for an entire FROM
87935 ** clause.
87936 **
87937 ** Example: Suppose the join is like this:
87938 **
87939 **           A natural cross join B
87940 **
87941 ** The operator is "natural cross join".  The A and B operands are stored
87942 ** in p->a[0] and p->a[1], respectively.  The parser initially stores the
87943 ** operator with A.  This routine shifts that operator over to B.
87944 */
87945 SQLITE_PRIVATE void sqlite3SrcListShiftJoinType(SrcList *p){
87946   if( p ){
87947     int i;
87948     assert( p->a || p->nSrc==0 );
87949     for(i=p->nSrc-1; i>0; i--){
87950       p->a[i].jointype = p->a[i-1].jointype;
87951     }
87952     p->a[0].jointype = 0;
87953   }
87954 }
87955 
87956 /*
87957 ** Begin a transaction
87958 */
87959 SQLITE_PRIVATE void sqlite3BeginTransaction(Parse *pParse, int type){
87960   sqlite3 *db;
87961   Vdbe *v;
87962   int i;
87963 
87964   assert( pParse!=0 );
87965   db = pParse->db;
87966   assert( db!=0 );
87967 /*  if( db->aDb[0].pBt==0 ) return; */
87968   if( sqlite3AuthCheck(pParse, SQLITE_TRANSACTION, "BEGIN", 0, 0) ){
87969     return;
87970   }
87971   v = sqlite3GetVdbe(pParse);
87972   if( !v ) return;
87973   if( type!=TK_DEFERRED ){
87974     for(i=0; i<db->nDb; i++){
87975       sqlite3VdbeAddOp2(v, OP_Transaction, i, (type==TK_EXCLUSIVE)+1);
87976       sqlite3VdbeUsesBtree(v, i);
87977     }
87978   }
87979   sqlite3VdbeAddOp2(v, OP_AutoCommit, 0, 0);
87980 }
87981 
87982 /*
87983 ** Commit a transaction
87984 */
87985 SQLITE_PRIVATE void sqlite3CommitTransaction(Parse *pParse){
87986   Vdbe *v;
87987 
87988   assert( pParse!=0 );
87989   assert( pParse->db!=0 );
87990   if( sqlite3AuthCheck(pParse, SQLITE_TRANSACTION, "COMMIT", 0, 0) ){
87991     return;
87992   }
87993   v = sqlite3GetVdbe(pParse);
87994   if( v ){
87995     sqlite3VdbeAddOp2(v, OP_AutoCommit, 1, 0);
87996   }
87997 }
87998 
87999 /*
88000 ** Rollback a transaction
88001 */
88002 SQLITE_PRIVATE void sqlite3RollbackTransaction(Parse *pParse){
88003   Vdbe *v;
88004 
88005   assert( pParse!=0 );
88006   assert( pParse->db!=0 );
88007   if( sqlite3AuthCheck(pParse, SQLITE_TRANSACTION, "ROLLBACK", 0, 0) ){
88008     return;
88009   }
88010   v = sqlite3GetVdbe(pParse);
88011   if( v ){
88012     sqlite3VdbeAddOp2(v, OP_AutoCommit, 1, 1);
88013   }
88014 }
88015 
88016 /*
88017 ** This function is called by the parser when it parses a command to create,
88018 ** release or rollback an SQL savepoint. 
88019 */
88020 SQLITE_PRIVATE void sqlite3Savepoint(Parse *pParse, int op, Token *pName){
88021   char *zName = sqlite3NameFromToken(pParse->db, pName);
88022   if( zName ){
88023     Vdbe *v = sqlite3GetVdbe(pParse);
88024 #ifndef SQLITE_OMIT_AUTHORIZATION
88025     static const char * const az[] = { "BEGIN", "RELEASE", "ROLLBACK" };
88026     assert( !SAVEPOINT_BEGIN && SAVEPOINT_RELEASE==1 && SAVEPOINT_ROLLBACK==2 );
88027 #endif
88028     if( !v || sqlite3AuthCheck(pParse, SQLITE_SAVEPOINT, az[op], zName, 0) ){
88029       sqlite3DbFree(pParse->db, zName);
88030       return;
88031     }
88032     sqlite3VdbeAddOp4(v, OP_Savepoint, op, 0, 0, zName, P4_DYNAMIC);
88033   }
88034 }
88035 
88036 /*
88037 ** Make sure the TEMP database is open and available for use.  Return
88038 ** the number of errors.  Leave any error messages in the pParse structure.
88039 */
88040 SQLITE_PRIVATE int sqlite3OpenTempDatabase(Parse *pParse){
88041   sqlite3 *db = pParse->db;
88042   if( db->aDb[1].pBt==0 && !pParse->explain ){
88043     int rc;
88044     Btree *pBt;
88045     static const int flags = 
88046           SQLITE_OPEN_READWRITE |
88047           SQLITE_OPEN_CREATE |
88048           SQLITE_OPEN_EXCLUSIVE |
88049           SQLITE_OPEN_DELETEONCLOSE |
88050           SQLITE_OPEN_TEMP_DB;
88051 
88052     rc = sqlite3BtreeOpen(db->pVfs, 0, db, &pBt, 0, flags);
88053     if( rc!=SQLITE_OK ){
88054       sqlite3ErrorMsg(pParse, "unable to open a temporary database "
88055         "file for storing temporary tables");
88056       pParse->rc = rc;
88057       return 1;
88058     }
88059     db->aDb[1].pBt = pBt;
88060     assert( db->aDb[1].pSchema );
88061     if( SQLITE_NOMEM==sqlite3BtreeSetPageSize(pBt, db->nextPagesize, -1, 0) ){
88062       db->mallocFailed = 1;
88063       return 1;
88064     }
88065   }
88066   return 0;
88067 }
88068 
88069 /*
88070 ** Generate VDBE code that will verify the schema cookie and start
88071 ** a read-transaction for all named database files.
88072 **
88073 ** It is important that all schema cookies be verified and all
88074 ** read transactions be started before anything else happens in
88075 ** the VDBE program.  But this routine can be called after much other
88076 ** code has been generated.  So here is what we do:
88077 **
88078 ** The first time this routine is called, we code an OP_Goto that
88079 ** will jump to a subroutine at the end of the program.  Then we
88080 ** record every database that needs its schema verified in the
88081 ** pParse->cookieMask field.  Later, after all other code has been
88082 ** generated, the subroutine that does the cookie verifications and
88083 ** starts the transactions will be coded and the OP_Goto P2 value
88084 ** will be made to point to that subroutine.  The generation of the
88085 ** cookie verification subroutine code happens in sqlite3FinishCoding().
88086 **
88087 ** If iDb<0 then code the OP_Goto only - don't set flag to verify the
88088 ** schema on any databases.  This can be used to position the OP_Goto
88089 ** early in the code, before we know if any database tables will be used.
88090 */
88091 SQLITE_PRIVATE void sqlite3CodeVerifySchema(Parse *pParse, int iDb){
88092   Parse *pToplevel = sqlite3ParseToplevel(pParse);
88093 
88094 #ifndef SQLITE_OMIT_TRIGGER
88095   if( pToplevel!=pParse ){
88096     /* This branch is taken if a trigger is currently being coded. In this
88097     ** case, set cookieGoto to a non-zero value to show that this function
88098     ** has been called. This is used by the sqlite3ExprCodeConstants()
88099     ** function. */
88100     pParse->cookieGoto = -1;
88101   }
88102 #endif
88103   if( pToplevel->cookieGoto==0 ){
88104     Vdbe *v = sqlite3GetVdbe(pToplevel);
88105     if( v==0 ) return;  /* This only happens if there was a prior error */
88106     pToplevel->cookieGoto = sqlite3VdbeAddOp2(v, OP_Goto, 0, 0)+1;
88107   }
88108   if( iDb>=0 ){
88109     sqlite3 *db = pToplevel->db;
88110     yDbMask mask;
88111 
88112     assert( iDb<db->nDb );
88113     assert( db->aDb[iDb].pBt!=0 || iDb==1 );
88114     assert( iDb<SQLITE_MAX_ATTACHED+2 );
88115     assert( sqlite3SchemaMutexHeld(db, iDb, 0) );
88116     mask = ((yDbMask)1)<<iDb;
88117     if( (pToplevel->cookieMask & mask)==0 ){
88118       pToplevel->cookieMask |= mask;
88119       pToplevel->cookieValue[iDb] = db->aDb[iDb].pSchema->schema_cookie;
88120       if( !OMIT_TEMPDB && iDb==1 ){
88121         sqlite3OpenTempDatabase(pToplevel);
88122       }
88123     }
88124   }
88125 }
88126 
88127 /*
88128 ** If argument zDb is NULL, then call sqlite3CodeVerifySchema() for each 
88129 ** attached database. Otherwise, invoke it for the database named zDb only.
88130 */
88131 SQLITE_PRIVATE void sqlite3CodeVerifyNamedSchema(Parse *pParse, const char *zDb){
88132   sqlite3 *db = pParse->db;
88133   int i;
88134   for(i=0; i<db->nDb; i++){
88135     Db *pDb = &db->aDb[i];
88136     if( pDb->pBt && (!zDb || 0==sqlite3StrICmp(zDb, pDb->zName)) ){
88137       sqlite3CodeVerifySchema(pParse, i);
88138     }
88139   }
88140 }
88141 
88142 /*
88143 ** Generate VDBE code that prepares for doing an operation that
88144 ** might change the database.
88145 **
88146 ** This routine starts a new transaction if we are not already within
88147 ** a transaction.  If we are already within a transaction, then a checkpoint
88148 ** is set if the setStatement parameter is true.  A checkpoint should
88149 ** be set for operations that might fail (due to a constraint) part of
88150 ** the way through and which will need to undo some writes without having to
88151 ** rollback the whole transaction.  For operations where all constraints
88152 ** can be checked before any changes are made to the database, it is never
88153 ** necessary to undo a write and the checkpoint should not be set.
88154 */
88155 SQLITE_PRIVATE void sqlite3BeginWriteOperation(Parse *pParse, int setStatement, int iDb){
88156   Parse *pToplevel = sqlite3ParseToplevel(pParse);
88157   sqlite3CodeVerifySchema(pParse, iDb);
88158   pToplevel->writeMask |= ((yDbMask)1)<<iDb;
88159   pToplevel->isMultiWrite |= setStatement;
88160 }
88161 
88162 /*
88163 ** Indicate that the statement currently under construction might write
88164 ** more than one entry (example: deleting one row then inserting another,
88165 ** inserting multiple rows in a table, or inserting a row and index entries.)
88166 ** If an abort occurs after some of these writes have completed, then it will
88167 ** be necessary to undo the completed writes.
88168 */
88169 SQLITE_PRIVATE void sqlite3MultiWrite(Parse *pParse){
88170   Parse *pToplevel = sqlite3ParseToplevel(pParse);
88171   pToplevel->isMultiWrite = 1;
88172 }
88173 
88174 /* 
88175 ** The code generator calls this routine if is discovers that it is
88176 ** possible to abort a statement prior to completion.  In order to 
88177 ** perform this abort without corrupting the database, we need to make
88178 ** sure that the statement is protected by a statement transaction.
88179 **
88180 ** Technically, we only need to set the mayAbort flag if the
88181 ** isMultiWrite flag was previously set.  There is a time dependency
88182 ** such that the abort must occur after the multiwrite.  This makes
88183 ** some statements involving the REPLACE conflict resolution algorithm
88184 ** go a little faster.  But taking advantage of this time dependency
88185 ** makes it more difficult to prove that the code is correct (in 
88186 ** particular, it prevents us from writing an effective
88187 ** implementation of sqlite3AssertMayAbort()) and so we have chosen
88188 ** to take the safe route and skip the optimization.
88189 */
88190 SQLITE_PRIVATE void sqlite3MayAbort(Parse *pParse){
88191   Parse *pToplevel = sqlite3ParseToplevel(pParse);
88192   pToplevel->mayAbort = 1;
88193 }
88194 
88195 /*
88196 ** Code an OP_Halt that causes the vdbe to return an SQLITE_CONSTRAINT
88197 ** error. The onError parameter determines which (if any) of the statement
88198 ** and/or current transaction is rolled back.
88199 */
88200 SQLITE_PRIVATE void sqlite3HaltConstraint(
88201   Parse *pParse,    /* Parsing context */
88202   int errCode,      /* extended error code */
88203   int onError,      /* Constraint type */
88204   char *p4,         /* Error message */
88205   i8 p4type,        /* P4_STATIC or P4_TRANSIENT */
88206   u8 p5Errmsg       /* P5_ErrMsg type */
88207 ){
88208   Vdbe *v = sqlite3GetVdbe(pParse);
88209   assert( (errCode&0xff)==SQLITE_CONSTRAINT );
88210   if( onError==OE_Abort ){
88211     sqlite3MayAbort(pParse);
88212   }
88213   sqlite3VdbeAddOp4(v, OP_Halt, errCode, onError, 0, p4, p4type);
88214   if( p5Errmsg ) sqlite3VdbeChangeP5(v, p5Errmsg);
88215 }
88216 
88217 /*
88218 ** Code an OP_Halt due to UNIQUE or PRIMARY KEY constraint violation.
88219 */
88220 SQLITE_PRIVATE void sqlite3UniqueConstraint(
88221   Parse *pParse,    /* Parsing context */
88222   int onError,      /* Constraint type */
88223   Index *pIdx       /* The index that triggers the constraint */
88224 ){
88225   char *zErr;
88226   int j;
88227   StrAccum errMsg;
88228   Table *pTab = pIdx->pTable;
88229 
88230   sqlite3StrAccumInit(&errMsg, 0, 0, 200);
88231   errMsg.db = pParse->db;
88232   for(j=0; j<pIdx->nKeyCol; j++){
88233     char *zCol = pTab->aCol[pIdx->aiColumn[j]].zName;
88234     if( j ) sqlite3StrAccumAppend(&errMsg, ", ", 2);
88235     sqlite3StrAccumAppend(&errMsg, pTab->zName, -1);
88236     sqlite3StrAccumAppend(&errMsg, ".", 1);
88237     sqlite3StrAccumAppend(&errMsg, zCol, -1);
88238   }
88239   zErr = sqlite3StrAccumFinish(&errMsg);
88240   sqlite3HaltConstraint(pParse, 
88241     (pIdx->autoIndex==2)?SQLITE_CONSTRAINT_PRIMARYKEY:SQLITE_CONSTRAINT_UNIQUE,
88242     onError, zErr, P4_DYNAMIC, P5_ConstraintUnique);
88243 }
88244 
88245 
88246 /*
88247 ** Code an OP_Halt due to non-unique rowid.
88248 */
88249 SQLITE_PRIVATE void sqlite3RowidConstraint(
88250   Parse *pParse,    /* Parsing context */
88251   int onError,      /* Conflict resolution algorithm */
88252   Table *pTab       /* The table with the non-unique rowid */ 
88253 ){
88254   char *zMsg;
88255   int rc;
88256   if( pTab->iPKey>=0 ){
88257     zMsg = sqlite3MPrintf(pParse->db, "%s.%s", pTab->zName,
88258                           pTab->aCol[pTab->iPKey].zName);
88259     rc = SQLITE_CONSTRAINT_PRIMARYKEY;
88260   }else{
88261     zMsg = sqlite3MPrintf(pParse->db, "%s.rowid", pTab->zName);
88262     rc = SQLITE_CONSTRAINT_ROWID;
88263   }
88264   sqlite3HaltConstraint(pParse, rc, onError, zMsg, P4_DYNAMIC,
88265                         P5_ConstraintUnique);
88266 }
88267 
88268 /*
88269 ** Check to see if pIndex uses the collating sequence pColl.  Return
88270 ** true if it does and false if it does not.
88271 */
88272 #ifndef SQLITE_OMIT_REINDEX
88273 static int collationMatch(const char *zColl, Index *pIndex){
88274   int i;
88275   assert( zColl!=0 );
88276   for(i=0; i<pIndex->nColumn; i++){
88277     const char *z = pIndex->azColl[i];
88278     assert( z!=0 || pIndex->aiColumn[i]<0 );
88279     if( pIndex->aiColumn[i]>=0 && 0==sqlite3StrICmp(z, zColl) ){
88280       return 1;
88281     }
88282   }
88283   return 0;
88284 }
88285 #endif
88286 
88287 /*
88288 ** Recompute all indices of pTab that use the collating sequence pColl.
88289 ** If pColl==0 then recompute all indices of pTab.
88290 */
88291 #ifndef SQLITE_OMIT_REINDEX
88292 static void reindexTable(Parse *pParse, Table *pTab, char const *zColl){
88293   Index *pIndex;              /* An index associated with pTab */
88294 
88295   for(pIndex=pTab->pIndex; pIndex; pIndex=pIndex->pNext){
88296     if( zColl==0 || collationMatch(zColl, pIndex) ){
88297       int iDb = sqlite3SchemaToIndex(pParse->db, pTab->pSchema);
88298       sqlite3BeginWriteOperation(pParse, 0, iDb);
88299       sqlite3RefillIndex(pParse, pIndex, -1);
88300     }
88301   }
88302 }
88303 #endif
88304 
88305 /*
88306 ** Recompute all indices of all tables in all databases where the
88307 ** indices use the collating sequence pColl.  If pColl==0 then recompute
88308 ** all indices everywhere.
88309 */
88310 #ifndef SQLITE_OMIT_REINDEX
88311 static void reindexDatabases(Parse *pParse, char const *zColl){
88312   Db *pDb;                    /* A single database */
88313   int iDb;                    /* The database index number */
88314   sqlite3 *db = pParse->db;   /* The database connection */
88315   HashElem *k;                /* For looping over tables in pDb */
88316   Table *pTab;                /* A table in the database */
88317 
88318   assert( sqlite3BtreeHoldsAllMutexes(db) );  /* Needed for schema access */
88319   for(iDb=0, pDb=db->aDb; iDb<db->nDb; iDb++, pDb++){
88320     assert( pDb!=0 );
88321     for(k=sqliteHashFirst(&pDb->pSchema->tblHash);  k; k=sqliteHashNext(k)){
88322       pTab = (Table*)sqliteHashData(k);
88323       reindexTable(pParse, pTab, zColl);
88324     }
88325   }
88326 }
88327 #endif
88328 
88329 /*
88330 ** Generate code for the REINDEX command.
88331 **
88332 **        REINDEX                            -- 1
88333 **        REINDEX  <collation>               -- 2
88334 **        REINDEX  ?<database>.?<tablename>  -- 3
88335 **        REINDEX  ?<database>.?<indexname>  -- 4
88336 **
88337 ** Form 1 causes all indices in all attached databases to be rebuilt.
88338 ** Form 2 rebuilds all indices in all databases that use the named
88339 ** collating function.  Forms 3 and 4 rebuild the named index or all
88340 ** indices associated with the named table.
88341 */
88342 #ifndef SQLITE_OMIT_REINDEX
88343 SQLITE_PRIVATE void sqlite3Reindex(Parse *pParse, Token *pName1, Token *pName2){
88344   CollSeq *pColl;             /* Collating sequence to be reindexed, or NULL */
88345   char *z;                    /* Name of a table or index */
88346   const char *zDb;            /* Name of the database */
88347   Table *pTab;                /* A table in the database */
88348   Index *pIndex;              /* An index associated with pTab */
88349   int iDb;                    /* The database index number */
88350   sqlite3 *db = pParse->db;   /* The database connection */
88351   Token *pObjName;            /* Name of the table or index to be reindexed */
88352 
88353   /* Read the database schema. If an error occurs, leave an error message
88354   ** and code in pParse and return NULL. */
88355   if( SQLITE_OK!=sqlite3ReadSchema(pParse) ){
88356     return;
88357   }
88358 
88359   if( pName1==0 ){
88360     reindexDatabases(pParse, 0);
88361     return;
88362   }else if( NEVER(pName2==0) || pName2->z==0 ){
88363     char *zColl;
88364     assert( pName1->z );
88365     zColl = sqlite3NameFromToken(pParse->db, pName1);
88366     if( !zColl ) return;
88367     pColl = sqlite3FindCollSeq(db, ENC(db), zColl, 0);
88368     if( pColl ){
88369       reindexDatabases(pParse, zColl);
88370       sqlite3DbFree(db, zColl);
88371       return;
88372     }
88373     sqlite3DbFree(db, zColl);
88374   }
88375   iDb = sqlite3TwoPartName(pParse, pName1, pName2, &pObjName);
88376   if( iDb<0 ) return;
88377   z = sqlite3NameFromToken(db, pObjName);
88378   if( z==0 ) return;
88379   zDb = db->aDb[iDb].zName;
88380   pTab = sqlite3FindTable(db, z, zDb);
88381   if( pTab ){
88382     reindexTable(pParse, pTab, 0);
88383     sqlite3DbFree(db, z);
88384     return;
88385   }
88386   pIndex = sqlite3FindIndex(db, z, zDb);
88387   sqlite3DbFree(db, z);
88388   if( pIndex ){
88389     sqlite3BeginWriteOperation(pParse, 0, iDb);
88390     sqlite3RefillIndex(pParse, pIndex, -1);
88391     return;
88392   }
88393   sqlite3ErrorMsg(pParse, "unable to identify the object to be reindexed");
88394 }
88395 #endif
88396 
88397 /*
88398 ** Return a KeyInfo structure that is appropriate for the given Index.
88399 **
88400 ** The KeyInfo structure for an index is cached in the Index object.
88401 ** So there might be multiple references to the returned pointer.  The
88402 ** caller should not try to modify the KeyInfo object.
88403 **
88404 ** The caller should invoke sqlite3KeyInfoUnref() on the returned object
88405 ** when it has finished using it.
88406 */
88407 SQLITE_PRIVATE KeyInfo *sqlite3KeyInfoOfIndex(Parse *pParse, Index *pIdx){
88408   if( pParse->nErr ) return 0;
88409 #ifndef SQLITE_OMIT_SHARED_CACHE
88410   if( pIdx->pKeyInfo && pIdx->pKeyInfo->db!=pParse->db ){
88411     sqlite3KeyInfoUnref(pIdx->pKeyInfo);
88412     pIdx->pKeyInfo = 0;
88413   }
88414 #endif
88415   if( pIdx->pKeyInfo==0 ){
88416     int i;
88417     int nCol = pIdx->nColumn;
88418     int nKey = pIdx->nKeyCol;
88419     KeyInfo *pKey;
88420     if( pIdx->uniqNotNull ){
88421       pKey = sqlite3KeyInfoAlloc(pParse->db, nKey, nCol-nKey);
88422     }else{
88423       pKey = sqlite3KeyInfoAlloc(pParse->db, nCol, 0);
88424     }
88425     if( pKey ){
88426       assert( sqlite3KeyInfoIsWriteable(pKey) );
88427       for(i=0; i<nCol; i++){
88428         char *zColl = pIdx->azColl[i];
88429         if( NEVER(zColl==0) ) zColl = "BINARY";
88430         pKey->aColl[i] = sqlite3LocateCollSeq(pParse, zColl);
88431         pKey->aSortOrder[i] = pIdx->aSortOrder[i];
88432       }
88433       if( pParse->nErr ){
88434         sqlite3KeyInfoUnref(pKey);
88435       }else{
88436         pIdx->pKeyInfo = pKey;
88437       }
88438     }
88439   }
88440   return sqlite3KeyInfoRef(pIdx->pKeyInfo);
88441 }
88442 
88443 /************** End of build.c ***********************************************/
88444 /************** Begin file callback.c ****************************************/
88445 /*
88446 ** 2005 May 23 
88447 **
88448 ** The author disclaims copyright to this source code.  In place of
88449 ** a legal notice, here is a blessing:
88450 **
88451 **    May you do good and not evil.
88452 **    May you find forgiveness for yourself and forgive others.
88453 **    May you share freely, never taking more than you give.
88454 **
88455 *************************************************************************
88456 **
88457 ** This file contains functions used to access the internal hash tables
88458 ** of user defined functions and collation sequences.
88459 */
88460 
88461 
88462 /*
88463 ** Invoke the 'collation needed' callback to request a collation sequence
88464 ** in the encoding enc of name zName, length nName.
88465 */
88466 static void callCollNeeded(sqlite3 *db, int enc, const char *zName){
88467   assert( !db->xCollNeeded || !db->xCollNeeded16 );
88468   if( db->xCollNeeded ){
88469     char *zExternal = sqlite3DbStrDup(db, zName);
88470     if( !zExternal ) return;
88471     db->xCollNeeded(db->pCollNeededArg, db, enc, zExternal);
88472     sqlite3DbFree(db, zExternal);
88473   }
88474 #ifndef SQLITE_OMIT_UTF16
88475   if( db->xCollNeeded16 ){
88476     char const *zExternal;
88477     sqlite3_value *pTmp = sqlite3ValueNew(db);
88478     sqlite3ValueSetStr(pTmp, -1, zName, SQLITE_UTF8, SQLITE_STATIC);
88479     zExternal = sqlite3ValueText(pTmp, SQLITE_UTF16NATIVE);
88480     if( zExternal ){
88481       db->xCollNeeded16(db->pCollNeededArg, db, (int)ENC(db), zExternal);
88482     }
88483     sqlite3ValueFree(pTmp);
88484   }
88485 #endif
88486 }
88487 
88488 /*
88489 ** This routine is called if the collation factory fails to deliver a
88490 ** collation function in the best encoding but there may be other versions
88491 ** of this collation function (for other text encodings) available. Use one
88492 ** of these instead if they exist. Avoid a UTF-8 <-> UTF-16 conversion if
88493 ** possible.
88494 */
88495 static int synthCollSeq(sqlite3 *db, CollSeq *pColl){
88496   CollSeq *pColl2;
88497   char *z = pColl->zName;
88498   int i;
88499   static const u8 aEnc[] = { SQLITE_UTF16BE, SQLITE_UTF16LE, SQLITE_UTF8 };
88500   for(i=0; i<3; i++){
88501     pColl2 = sqlite3FindCollSeq(db, aEnc[i], z, 0);
88502     if( pColl2->xCmp!=0 ){
88503       memcpy(pColl, pColl2, sizeof(CollSeq));
88504       pColl->xDel = 0;         /* Do not copy the destructor */
88505       return SQLITE_OK;
88506     }
88507   }
88508   return SQLITE_ERROR;
88509 }
88510 
88511 /*
88512 ** This function is responsible for invoking the collation factory callback
88513 ** or substituting a collation sequence of a different encoding when the
88514 ** requested collation sequence is not available in the desired encoding.
88515 ** 
88516 ** If it is not NULL, then pColl must point to the database native encoding 
88517 ** collation sequence with name zName, length nName.
88518 **
88519 ** The return value is either the collation sequence to be used in database
88520 ** db for collation type name zName, length nName, or NULL, if no collation
88521 ** sequence can be found.  If no collation is found, leave an error message.
88522 **
88523 ** See also: sqlite3LocateCollSeq(), sqlite3FindCollSeq()
88524 */
88525 SQLITE_PRIVATE CollSeq *sqlite3GetCollSeq(
88526   Parse *pParse,        /* Parsing context */
88527   u8 enc,               /* The desired encoding for the collating sequence */
88528   CollSeq *pColl,       /* Collating sequence with native encoding, or NULL */
88529   const char *zName     /* Collating sequence name */
88530 ){
88531   CollSeq *p;
88532   sqlite3 *db = pParse->db;
88533 
88534   p = pColl;
88535   if( !p ){
88536     p = sqlite3FindCollSeq(db, enc, zName, 0);
88537   }
88538   if( !p || !p->xCmp ){
88539     /* No collation sequence of this type for this encoding is registered.
88540     ** Call the collation factory to see if it can supply us with one.
88541     */
88542     callCollNeeded(db, enc, zName);
88543     p = sqlite3FindCollSeq(db, enc, zName, 0);
88544   }
88545   if( p && !p->xCmp && synthCollSeq(db, p) ){
88546     p = 0;
88547   }
88548   assert( !p || p->xCmp );
88549   if( p==0 ){
88550     sqlite3ErrorMsg(pParse, "no such collation sequence: %s", zName);
88551   }
88552   return p;
88553 }
88554 
88555 /*
88556 ** This routine is called on a collation sequence before it is used to
88557 ** check that it is defined. An undefined collation sequence exists when
88558 ** a database is loaded that contains references to collation sequences
88559 ** that have not been defined by sqlite3_create_collation() etc.
88560 **
88561 ** If required, this routine calls the 'collation needed' callback to
88562 ** request a definition of the collating sequence. If this doesn't work, 
88563 ** an equivalent collating sequence that uses a text encoding different
88564 ** from the main database is substituted, if one is available.
88565 */
88566 SQLITE_PRIVATE int sqlite3CheckCollSeq(Parse *pParse, CollSeq *pColl){
88567   if( pColl ){
88568     const char *zName = pColl->zName;
88569     sqlite3 *db = pParse->db;
88570     CollSeq *p = sqlite3GetCollSeq(pParse, ENC(db), pColl, zName);
88571     if( !p ){
88572       return SQLITE_ERROR;
88573     }
88574     assert( p==pColl );
88575   }
88576   return SQLITE_OK;
88577 }
88578 
88579 
88580 
88581 /*
88582 ** Locate and return an entry from the db.aCollSeq hash table. If the entry
88583 ** specified by zName and nName is not found and parameter 'create' is
88584 ** true, then create a new entry. Otherwise return NULL.
88585 **
88586 ** Each pointer stored in the sqlite3.aCollSeq hash table contains an
88587 ** array of three CollSeq structures. The first is the collation sequence
88588 ** prefferred for UTF-8, the second UTF-16le, and the third UTF-16be.
88589 **
88590 ** Stored immediately after the three collation sequences is a copy of
88591 ** the collation sequence name. A pointer to this string is stored in
88592 ** each collation sequence structure.
88593 */
88594 static CollSeq *findCollSeqEntry(
88595   sqlite3 *db,          /* Database connection */
88596   const char *zName,    /* Name of the collating sequence */
88597   int create            /* Create a new entry if true */
88598 ){
88599   CollSeq *pColl;
88600   int nName = sqlite3Strlen30(zName);
88601   pColl = sqlite3HashFind(&db->aCollSeq, zName, nName);
88602 
88603   if( 0==pColl && create ){
88604     pColl = sqlite3DbMallocZero(db, 3*sizeof(*pColl) + nName + 1 );
88605     if( pColl ){
88606       CollSeq *pDel = 0;
88607       pColl[0].zName = (char*)&pColl[3];
88608       pColl[0].enc = SQLITE_UTF8;
88609       pColl[1].zName = (char*)&pColl[3];
88610       pColl[1].enc = SQLITE_UTF16LE;
88611       pColl[2].zName = (char*)&pColl[3];
88612       pColl[2].enc = SQLITE_UTF16BE;
88613       memcpy(pColl[0].zName, zName, nName);
88614       pColl[0].zName[nName] = 0;
88615       pDel = sqlite3HashInsert(&db->aCollSeq, pColl[0].zName, nName, pColl);
88616 
88617       /* If a malloc() failure occurred in sqlite3HashInsert(), it will 
88618       ** return the pColl pointer to be deleted (because it wasn't added
88619       ** to the hash table).
88620       */
88621       assert( pDel==0 || pDel==pColl );
88622       if( pDel!=0 ){
88623         db->mallocFailed = 1;
88624         sqlite3DbFree(db, pDel);
88625         pColl = 0;
88626       }
88627     }
88628   }
88629   return pColl;
88630 }
88631 
88632 /*
88633 ** Parameter zName points to a UTF-8 encoded string nName bytes long.
88634 ** Return the CollSeq* pointer for the collation sequence named zName
88635 ** for the encoding 'enc' from the database 'db'.
88636 **
88637 ** If the entry specified is not found and 'create' is true, then create a
88638 ** new entry.  Otherwise return NULL.
88639 **
88640 ** A separate function sqlite3LocateCollSeq() is a wrapper around
88641 ** this routine.  sqlite3LocateCollSeq() invokes the collation factory
88642 ** if necessary and generates an error message if the collating sequence
88643 ** cannot be found.
88644 **
88645 ** See also: sqlite3LocateCollSeq(), sqlite3GetCollSeq()
88646 */
88647 SQLITE_PRIVATE CollSeq *sqlite3FindCollSeq(
88648   sqlite3 *db,
88649   u8 enc,
88650   const char *zName,
88651   int create
88652 ){
88653   CollSeq *pColl;
88654   if( zName ){
88655     pColl = findCollSeqEntry(db, zName, create);
88656   }else{
88657     pColl = db->pDfltColl;
88658   }
88659   assert( SQLITE_UTF8==1 && SQLITE_UTF16LE==2 && SQLITE_UTF16BE==3 );
88660   assert( enc>=SQLITE_UTF8 && enc<=SQLITE_UTF16BE );
88661   if( pColl ) pColl += enc-1;
88662   return pColl;
88663 }
88664 
88665 /* During the search for the best function definition, this procedure
88666 ** is called to test how well the function passed as the first argument
88667 ** matches the request for a function with nArg arguments in a system
88668 ** that uses encoding enc. The value returned indicates how well the
88669 ** request is matched. A higher value indicates a better match.
88670 **
88671 ** If nArg is -1 that means to only return a match (non-zero) if p->nArg
88672 ** is also -1.  In other words, we are searching for a function that
88673 ** takes a variable number of arguments.
88674 **
88675 ** If nArg is -2 that means that we are searching for any function 
88676 ** regardless of the number of arguments it uses, so return a positive
88677 ** match score for any
88678 **
88679 ** The returned value is always between 0 and 6, as follows:
88680 **
88681 ** 0: Not a match.
88682 ** 1: UTF8/16 conversion required and function takes any number of arguments.
88683 ** 2: UTF16 byte order change required and function takes any number of args.
88684 ** 3: encoding matches and function takes any number of arguments
88685 ** 4: UTF8/16 conversion required - argument count matches exactly
88686 ** 5: UTF16 byte order conversion required - argument count matches exactly
88687 ** 6: Perfect match:  encoding and argument count match exactly.
88688 **
88689 ** If nArg==(-2) then any function with a non-null xStep or xFunc is
88690 ** a perfect match and any function with both xStep and xFunc NULL is
88691 ** a non-match.
88692 */
88693 #define FUNC_PERFECT_MATCH 6  /* The score for a perfect match */
88694 static int matchQuality(
88695   FuncDef *p,     /* The function we are evaluating for match quality */
88696   int nArg,       /* Desired number of arguments.  (-1)==any */
88697   u8 enc          /* Desired text encoding */
88698 ){
88699   int match;
88700 
88701   /* nArg of -2 is a special case */
88702   if( nArg==(-2) ) return (p->xFunc==0 && p->xStep==0) ? 0 : FUNC_PERFECT_MATCH;
88703 
88704   /* Wrong number of arguments means "no match" */
88705   if( p->nArg!=nArg && p->nArg>=0 ) return 0;
88706 
88707   /* Give a better score to a function with a specific number of arguments
88708   ** than to function that accepts any number of arguments. */
88709   if( p->nArg==nArg ){
88710     match = 4;
88711   }else{
88712     match = 1;
88713   }
88714 
88715   /* Bonus points if the text encoding matches */
88716   if( enc==(p->funcFlags & SQLITE_FUNC_ENCMASK) ){
88717     match += 2;  /* Exact encoding match */
88718   }else if( (enc & p->funcFlags & 2)!=0 ){
88719     match += 1;  /* Both are UTF16, but with different byte orders */
88720   }
88721 
88722   return match;
88723 }
88724 
88725 /*
88726 ** Search a FuncDefHash for a function with the given name.  Return
88727 ** a pointer to the matching FuncDef if found, or 0 if there is no match.
88728 */
88729 static FuncDef *functionSearch(
88730   FuncDefHash *pHash,  /* Hash table to search */
88731   int h,               /* Hash of the name */
88732   const char *zFunc,   /* Name of function */
88733   int nFunc            /* Number of bytes in zFunc */
88734 ){
88735   FuncDef *p;
88736   for(p=pHash->a[h]; p; p=p->pHash){
88737     if( sqlite3StrNICmp(p->zName, zFunc, nFunc)==0 && p->zName[nFunc]==0 ){
88738       return p;
88739     }
88740   }
88741   return 0;
88742 }
88743 
88744 /*
88745 ** Insert a new FuncDef into a FuncDefHash hash table.
88746 */
88747 SQLITE_PRIVATE void sqlite3FuncDefInsert(
88748   FuncDefHash *pHash,  /* The hash table into which to insert */
88749   FuncDef *pDef        /* The function definition to insert */
88750 ){
88751   FuncDef *pOther;
88752   int nName = sqlite3Strlen30(pDef->zName);
88753   u8 c1 = (u8)pDef->zName[0];
88754   int h = (sqlite3UpperToLower[c1] + nName) % ArraySize(pHash->a);
88755   pOther = functionSearch(pHash, h, pDef->zName, nName);
88756   if( pOther ){
88757     assert( pOther!=pDef && pOther->pNext!=pDef );
88758     pDef->pNext = pOther->pNext;
88759     pOther->pNext = pDef;
88760   }else{
88761     pDef->pNext = 0;
88762     pDef->pHash = pHash->a[h];
88763     pHash->a[h] = pDef;
88764   }
88765 }
88766   
88767   
88768 
88769 /*
88770 ** Locate a user function given a name, a number of arguments and a flag
88771 ** indicating whether the function prefers UTF-16 over UTF-8.  Return a
88772 ** pointer to the FuncDef structure that defines that function, or return
88773 ** NULL if the function does not exist.
88774 **
88775 ** If the createFlag argument is true, then a new (blank) FuncDef
88776 ** structure is created and liked into the "db" structure if a
88777 ** no matching function previously existed.
88778 **
88779 ** If nArg is -2, then the first valid function found is returned.  A
88780 ** function is valid if either xFunc or xStep is non-zero.  The nArg==(-2)
88781 ** case is used to see if zName is a valid function name for some number
88782 ** of arguments.  If nArg is -2, then createFlag must be 0.
88783 **
88784 ** If createFlag is false, then a function with the required name and
88785 ** number of arguments may be returned even if the eTextRep flag does not
88786 ** match that requested.
88787 */
88788 SQLITE_PRIVATE FuncDef *sqlite3FindFunction(
88789   sqlite3 *db,       /* An open database */
88790   const char *zName, /* Name of the function.  Not null-terminated */
88791   int nName,         /* Number of characters in the name */
88792   int nArg,          /* Number of arguments.  -1 means any number */
88793   u8 enc,            /* Preferred text encoding */
88794   u8 createFlag      /* Create new entry if true and does not otherwise exist */
88795 ){
88796   FuncDef *p;         /* Iterator variable */
88797   FuncDef *pBest = 0; /* Best match found so far */
88798   int bestScore = 0;  /* Score of best match */
88799   int h;              /* Hash value */
88800 
88801   assert( nArg>=(-2) );
88802   assert( nArg>=(-1) || createFlag==0 );
88803   assert( enc==SQLITE_UTF8 || enc==SQLITE_UTF16LE || enc==SQLITE_UTF16BE );
88804   h = (sqlite3UpperToLower[(u8)zName[0]] + nName) % ArraySize(db->aFunc.a);
88805 
88806   /* First search for a match amongst the application-defined functions.
88807   */
88808   p = functionSearch(&db->aFunc, h, zName, nName);
88809   while( p ){
88810     int score = matchQuality(p, nArg, enc);
88811     if( score>bestScore ){
88812       pBest = p;
88813       bestScore = score;
88814     }
88815     p = p->pNext;
88816   }
88817 
88818   /* If no match is found, search the built-in functions.
88819   **
88820   ** If the SQLITE_PreferBuiltin flag is set, then search the built-in
88821   ** functions even if a prior app-defined function was found.  And give
88822   ** priority to built-in functions.
88823   **
88824   ** Except, if createFlag is true, that means that we are trying to
88825   ** install a new function.  Whatever FuncDef structure is returned it will
88826   ** have fields overwritten with new information appropriate for the
88827   ** new function.  But the FuncDefs for built-in functions are read-only.
88828   ** So we must not search for built-ins when creating a new function.
88829   */ 
88830   if( !createFlag && (pBest==0 || (db->flags & SQLITE_PreferBuiltin)!=0) ){
88831     FuncDefHash *pHash = &GLOBAL(FuncDefHash, sqlite3GlobalFunctions);
88832     bestScore = 0;
88833     p = functionSearch(pHash, h, zName, nName);
88834     while( p ){
88835       int score = matchQuality(p, nArg, enc);
88836       if( score>bestScore ){
88837         pBest = p;
88838         bestScore = score;
88839       }
88840       p = p->pNext;
88841     }
88842   }
88843 
88844   /* If the createFlag parameter is true and the search did not reveal an
88845   ** exact match for the name, number of arguments and encoding, then add a
88846   ** new entry to the hash table and return it.
88847   */
88848   if( createFlag && bestScore<FUNC_PERFECT_MATCH && 
88849       (pBest = sqlite3DbMallocZero(db, sizeof(*pBest)+nName+1))!=0 ){
88850     pBest->zName = (char *)&pBest[1];
88851     pBest->nArg = (u16)nArg;
88852     pBest->funcFlags = enc;
88853     memcpy(pBest->zName, zName, nName);
88854     pBest->zName[nName] = 0;
88855     sqlite3FuncDefInsert(&db->aFunc, pBest);
88856   }
88857 
88858   if( pBest && (pBest->xStep || pBest->xFunc || createFlag) ){
88859     return pBest;
88860   }
88861   return 0;
88862 }
88863 
88864 /*
88865 ** Free all resources held by the schema structure. The void* argument points
88866 ** at a Schema struct. This function does not call sqlite3DbFree(db, ) on the 
88867 ** pointer itself, it just cleans up subsidiary resources (i.e. the contents
88868 ** of the schema hash tables).
88869 **
88870 ** The Schema.cache_size variable is not cleared.
88871 */
88872 SQLITE_PRIVATE void sqlite3SchemaClear(void *p){
88873   Hash temp1;
88874   Hash temp2;
88875   HashElem *pElem;
88876   Schema *pSchema = (Schema *)p;
88877 
88878   temp1 = pSchema->tblHash;
88879   temp2 = pSchema->trigHash;
88880   sqlite3HashInit(&pSchema->trigHash);
88881   sqlite3HashClear(&pSchema->idxHash);
88882   for(pElem=sqliteHashFirst(&temp2); pElem; pElem=sqliteHashNext(pElem)){
88883     sqlite3DeleteTrigger(0, (Trigger*)sqliteHashData(pElem));
88884   }
88885   sqlite3HashClear(&temp2);
88886   sqlite3HashInit(&pSchema->tblHash);
88887   for(pElem=sqliteHashFirst(&temp1); pElem; pElem=sqliteHashNext(pElem)){
88888     Table *pTab = sqliteHashData(pElem);
88889     sqlite3DeleteTable(0, pTab);
88890   }
88891   sqlite3HashClear(&temp1);
88892   sqlite3HashClear(&pSchema->fkeyHash);
88893   pSchema->pSeqTab = 0;
88894   if( pSchema->flags & DB_SchemaLoaded ){
88895     pSchema->iGeneration++;
88896     pSchema->flags &= ~DB_SchemaLoaded;
88897   }
88898 }
88899 
88900 /*
88901 ** Find and return the schema associated with a BTree.  Create
88902 ** a new one if necessary.
88903 */
88904 SQLITE_PRIVATE Schema *sqlite3SchemaGet(sqlite3 *db, Btree *pBt){
88905   Schema * p;
88906   if( pBt ){
88907     p = (Schema *)sqlite3BtreeSchema(pBt, sizeof(Schema), sqlite3SchemaClear);
88908   }else{
88909     p = (Schema *)sqlite3DbMallocZero(0, sizeof(Schema));
88910   }
88911   if( !p ){
88912     db->mallocFailed = 1;
88913   }else if ( 0==p->file_format ){
88914     sqlite3HashInit(&p->tblHash);
88915     sqlite3HashInit(&p->idxHash);
88916     sqlite3HashInit(&p->trigHash);
88917     sqlite3HashInit(&p->fkeyHash);
88918     p->enc = SQLITE_UTF8;
88919   }
88920   return p;
88921 }
88922 
88923 /************** End of callback.c ********************************************/
88924 /************** Begin file delete.c ******************************************/
88925 /*
88926 ** 2001 September 15
88927 **
88928 ** The author disclaims copyright to this source code.  In place of
88929 ** a legal notice, here is a blessing:
88930 **
88931 **    May you do good and not evil.
88932 **    May you find forgiveness for yourself and forgive others.
88933 **    May you share freely, never taking more than you give.
88934 **
88935 *************************************************************************
88936 ** This file contains C code routines that are called by the parser
88937 ** in order to generate code for DELETE FROM statements.
88938 */
88939 
88940 /*
88941 ** While a SrcList can in general represent multiple tables and subqueries
88942 ** (as in the FROM clause of a SELECT statement) in this case it contains
88943 ** the name of a single table, as one might find in an INSERT, DELETE,
88944 ** or UPDATE statement.  Look up that table in the symbol table and
88945 ** return a pointer.  Set an error message and return NULL if the table 
88946 ** name is not found or if any other error occurs.
88947 **
88948 ** The following fields are initialized appropriate in pSrc:
88949 **
88950 **    pSrc->a[0].pTab       Pointer to the Table object
88951 **    pSrc->a[0].pIndex     Pointer to the INDEXED BY index, if there is one
88952 **
88953 */
88954 SQLITE_PRIVATE Table *sqlite3SrcListLookup(Parse *pParse, SrcList *pSrc){
88955   struct SrcList_item *pItem = pSrc->a;
88956   Table *pTab;
88957   assert( pItem && pSrc->nSrc==1 );
88958   pTab = sqlite3LocateTableItem(pParse, 0, pItem);
88959   sqlite3DeleteTable(pParse->db, pItem->pTab);
88960   pItem->pTab = pTab;
88961   if( pTab ){
88962     pTab->nRef++;
88963   }
88964   if( sqlite3IndexedByLookup(pParse, pItem) ){
88965     pTab = 0;
88966   }
88967   return pTab;
88968 }
88969 
88970 /*
88971 ** Check to make sure the given table is writable.  If it is not
88972 ** writable, generate an error message and return 1.  If it is
88973 ** writable return 0;
88974 */
88975 SQLITE_PRIVATE int sqlite3IsReadOnly(Parse *pParse, Table *pTab, int viewOk){
88976   /* A table is not writable under the following circumstances:
88977   **
88978   **   1) It is a virtual table and no implementation of the xUpdate method
88979   **      has been provided, or
88980   **   2) It is a system table (i.e. sqlite_master), this call is not
88981   **      part of a nested parse and writable_schema pragma has not 
88982   **      been specified.
88983   **
88984   ** In either case leave an error message in pParse and return non-zero.
88985   */
88986   if( ( IsVirtual(pTab) 
88987      && sqlite3GetVTable(pParse->db, pTab)->pMod->pModule->xUpdate==0 )
88988    || ( (pTab->tabFlags & TF_Readonly)!=0
88989      && (pParse->db->flags & SQLITE_WriteSchema)==0
88990      && pParse->nested==0 )
88991   ){
88992     sqlite3ErrorMsg(pParse, "table %s may not be modified", pTab->zName);
88993     return 1;
88994   }
88995 
88996 #ifndef SQLITE_OMIT_VIEW
88997   if( !viewOk && pTab->pSelect ){
88998     sqlite3ErrorMsg(pParse,"cannot modify %s because it is a view",pTab->zName);
88999     return 1;
89000   }
89001 #endif
89002   return 0;
89003 }
89004 
89005 
89006 #if !defined(SQLITE_OMIT_VIEW) && !defined(SQLITE_OMIT_TRIGGER)
89007 /*
89008 ** Evaluate a view and store its result in an ephemeral table.  The
89009 ** pWhere argument is an optional WHERE clause that restricts the
89010 ** set of rows in the view that are to be added to the ephemeral table.
89011 */
89012 SQLITE_PRIVATE void sqlite3MaterializeView(
89013   Parse *pParse,       /* Parsing context */
89014   Table *pView,        /* View definition */
89015   Expr *pWhere,        /* Optional WHERE clause to be added */
89016   int iCur             /* Cursor number for ephemerial table */
89017 ){
89018   SelectDest dest;
89019   Select *pSel;
89020   SrcList *pFrom;
89021   sqlite3 *db = pParse->db;
89022   int iDb = sqlite3SchemaToIndex(db, pView->pSchema);
89023 
89024   pWhere = sqlite3ExprDup(db, pWhere, 0);
89025   pFrom = sqlite3SrcListAppend(db, 0, 0, 0);
89026 
89027   if( pFrom ){
89028     assert( pFrom->nSrc==1 );
89029     pFrom->a[0].zName = sqlite3DbStrDup(db, pView->zName);
89030     pFrom->a[0].zDatabase = sqlite3DbStrDup(db, db->aDb[iDb].zName);
89031     assert( pFrom->a[0].pOn==0 );
89032     assert( pFrom->a[0].pUsing==0 );
89033   }
89034 
89035   pSel = sqlite3SelectNew(pParse, 0, pFrom, pWhere, 0, 0, 0, 0, 0, 0);
89036   if( pSel ) pSel->selFlags |= SF_Materialize;
89037 
89038   sqlite3SelectDestInit(&dest, SRT_EphemTab, iCur);
89039   sqlite3Select(pParse, pSel, &dest);
89040   sqlite3SelectDelete(db, pSel);
89041 }
89042 #endif /* !defined(SQLITE_OMIT_VIEW) && !defined(SQLITE_OMIT_TRIGGER) */
89043 
89044 #if defined(SQLITE_ENABLE_UPDATE_DELETE_LIMIT) && !defined(SQLITE_OMIT_SUBQUERY)
89045 /*
89046 ** Generate an expression tree to implement the WHERE, ORDER BY,
89047 ** and LIMIT/OFFSET portion of DELETE and UPDATE statements.
89048 **
89049 **     DELETE FROM table_wxyz WHERE a<5 ORDER BY a LIMIT 1;
89050 **                            \__________________________/
89051 **                               pLimitWhere (pInClause)
89052 */
89053 SQLITE_PRIVATE Expr *sqlite3LimitWhere(
89054   Parse *pParse,               /* The parser context */
89055   SrcList *pSrc,               /* the FROM clause -- which tables to scan */
89056   Expr *pWhere,                /* The WHERE clause.  May be null */
89057   ExprList *pOrderBy,          /* The ORDER BY clause.  May be null */
89058   Expr *pLimit,                /* The LIMIT clause.  May be null */
89059   Expr *pOffset,               /* The OFFSET clause.  May be null */
89060   char *zStmtType              /* Either DELETE or UPDATE.  For err msgs. */
89061 ){
89062   Expr *pWhereRowid = NULL;    /* WHERE rowid .. */
89063   Expr *pInClause = NULL;      /* WHERE rowid IN ( select ) */
89064   Expr *pSelectRowid = NULL;   /* SELECT rowid ... */
89065   ExprList *pEList = NULL;     /* Expression list contaning only pSelectRowid */
89066   SrcList *pSelectSrc = NULL;  /* SELECT rowid FROM x ... (dup of pSrc) */
89067   Select *pSelect = NULL;      /* Complete SELECT tree */
89068 
89069   /* Check that there isn't an ORDER BY without a LIMIT clause.
89070   */
89071   if( pOrderBy && (pLimit == 0) ) {
89072     sqlite3ErrorMsg(pParse, "ORDER BY without LIMIT on %s", zStmtType);
89073     goto limit_where_cleanup_2;
89074   }
89075 
89076   /* We only need to generate a select expression if there
89077   ** is a limit/offset term to enforce.
89078   */
89079   if( pLimit == 0 ) {
89080     /* if pLimit is null, pOffset will always be null as well. */
89081     assert( pOffset == 0 );
89082     return pWhere;
89083   }
89084 
89085   /* Generate a select expression tree to enforce the limit/offset 
89086   ** term for the DELETE or UPDATE statement.  For example:
89087   **   DELETE FROM table_a WHERE col1=1 ORDER BY col2 LIMIT 1 OFFSET 1
89088   ** becomes:
89089   **   DELETE FROM table_a WHERE rowid IN ( 
89090   **     SELECT rowid FROM table_a WHERE col1=1 ORDER BY col2 LIMIT 1 OFFSET 1
89091   **   );
89092   */
89093 
89094   pSelectRowid = sqlite3PExpr(pParse, TK_ROW, 0, 0, 0);
89095   if( pSelectRowid == 0 ) goto limit_where_cleanup_2;
89096   pEList = sqlite3ExprListAppend(pParse, 0, pSelectRowid);
89097   if( pEList == 0 ) goto limit_where_cleanup_2;
89098 
89099   /* duplicate the FROM clause as it is needed by both the DELETE/UPDATE tree
89100   ** and the SELECT subtree. */
89101   pSelectSrc = sqlite3SrcListDup(pParse->db, pSrc, 0);
89102   if( pSelectSrc == 0 ) {
89103     sqlite3ExprListDelete(pParse->db, pEList);
89104     goto limit_where_cleanup_2;
89105   }
89106 
89107   /* generate the SELECT expression tree. */
89108   pSelect = sqlite3SelectNew(pParse,pEList,pSelectSrc,pWhere,0,0,
89109                              pOrderBy,0,pLimit,pOffset);
89110   if( pSelect == 0 ) return 0;
89111 
89112   /* now generate the new WHERE rowid IN clause for the DELETE/UDPATE */
89113   pWhereRowid = sqlite3PExpr(pParse, TK_ROW, 0, 0, 0);
89114   if( pWhereRowid == 0 ) goto limit_where_cleanup_1;
89115   pInClause = sqlite3PExpr(pParse, TK_IN, pWhereRowid, 0, 0);
89116   if( pInClause == 0 ) goto limit_where_cleanup_1;
89117 
89118   pInClause->x.pSelect = pSelect;
89119   pInClause->flags |= EP_xIsSelect;
89120   sqlite3ExprSetHeight(pParse, pInClause);
89121   return pInClause;
89122 
89123   /* something went wrong. clean up anything allocated. */
89124 limit_where_cleanup_1:
89125   sqlite3SelectDelete(pParse->db, pSelect);
89126   return 0;
89127 
89128 limit_where_cleanup_2:
89129   sqlite3ExprDelete(pParse->db, pWhere);
89130   sqlite3ExprListDelete(pParse->db, pOrderBy);
89131   sqlite3ExprDelete(pParse->db, pLimit);
89132   sqlite3ExprDelete(pParse->db, pOffset);
89133   return 0;
89134 }
89135 #endif /* defined(SQLITE_ENABLE_UPDATE_DELETE_LIMIT) */
89136        /*      && !defined(SQLITE_OMIT_SUBQUERY) */
89137 
89138 /*
89139 ** Generate code for a DELETE FROM statement.
89140 **
89141 **     DELETE FROM table_wxyz WHERE a<5 AND b NOT NULL;
89142 **                 \________/       \________________/
89143 **                  pTabList              pWhere
89144 */
89145 SQLITE_PRIVATE void sqlite3DeleteFrom(
89146   Parse *pParse,         /* The parser context */
89147   SrcList *pTabList,     /* The table from which we should delete things */
89148   Expr *pWhere           /* The WHERE clause.  May be null */
89149 ){
89150   Vdbe *v;               /* The virtual database engine */
89151   Table *pTab;           /* The table from which records will be deleted */
89152   const char *zDb;       /* Name of database holding pTab */
89153   int i;                 /* Loop counter */
89154   WhereInfo *pWInfo;     /* Information about the WHERE clause */
89155   Index *pIdx;           /* For looping over indices of the table */
89156   int iTabCur;           /* Cursor number for the table */
89157   int iDataCur;          /* VDBE cursor for the canonical data source */
89158   int iIdxCur;           /* Cursor number of the first index */
89159   int nIdx;              /* Number of indices */
89160   sqlite3 *db;           /* Main database structure */
89161   AuthContext sContext;  /* Authorization context */
89162   NameContext sNC;       /* Name context to resolve expressions in */
89163   int iDb;               /* Database number */
89164   int memCnt = -1;       /* Memory cell used for change counting */
89165   int rcauth;            /* Value returned by authorization callback */
89166   int okOnePass;         /* True for one-pass algorithm without the FIFO */
89167   int aiCurOnePass[2];   /* The write cursors opened by WHERE_ONEPASS */
89168   u8 *aToOpen = 0;       /* Open cursor iTabCur+j if aToOpen[j] is true */
89169   Index *pPk;            /* The PRIMARY KEY index on the table */
89170   int iPk = 0;           /* First of nPk registers holding PRIMARY KEY value */
89171   i16 nPk = 1;           /* Number of columns in the PRIMARY KEY */
89172   int iKey;              /* Memory cell holding key of row to be deleted */
89173   i16 nKey;              /* Number of memory cells in the row key */
89174   int iEphCur = 0;       /* Ephemeral table holding all primary key values */
89175   int iRowSet = 0;       /* Register for rowset of rows to delete */
89176   int addrBypass = 0;    /* Address of jump over the delete logic */
89177   int addrLoop = 0;      /* Top of the delete loop */
89178   int addrDelete = 0;    /* Jump directly to the delete logic */
89179   int addrEphOpen = 0;   /* Instruction to open the Ephermeral table */
89180  
89181 #ifndef SQLITE_OMIT_TRIGGER
89182   int isView;                  /* True if attempting to delete from a view */
89183   Trigger *pTrigger;           /* List of table triggers, if required */
89184 #endif
89185 
89186   memset(&sContext, 0, sizeof(sContext));
89187   db = pParse->db;
89188   if( pParse->nErr || db->mallocFailed ){
89189     goto delete_from_cleanup;
89190   }
89191   assert( pTabList->nSrc==1 );
89192 
89193   /* Locate the table which we want to delete.  This table has to be
89194   ** put in an SrcList structure because some of the subroutines we
89195   ** will be calling are designed to work with multiple tables and expect
89196   ** an SrcList* parameter instead of just a Table* parameter.
89197   */
89198   pTab = sqlite3SrcListLookup(pParse, pTabList);
89199   if( pTab==0 )  goto delete_from_cleanup;
89200 
89201   /* Figure out if we have any triggers and if the table being
89202   ** deleted from is a view
89203   */
89204 #ifndef SQLITE_OMIT_TRIGGER
89205   pTrigger = sqlite3TriggersExist(pParse, pTab, TK_DELETE, 0, 0);
89206   isView = pTab->pSelect!=0;
89207 #else
89208 # define pTrigger 0
89209 # define isView 0
89210 #endif
89211 #ifdef SQLITE_OMIT_VIEW
89212 # undef isView
89213 # define isView 0
89214 #endif
89215 
89216   /* If pTab is really a view, make sure it has been initialized.
89217   */
89218   if( sqlite3ViewGetColumnNames(pParse, pTab) ){
89219     goto delete_from_cleanup;
89220   }
89221 
89222   if( sqlite3IsReadOnly(pParse, pTab, (pTrigger?1:0)) ){
89223     goto delete_from_cleanup;
89224   }
89225   iDb = sqlite3SchemaToIndex(db, pTab->pSchema);
89226   assert( iDb<db->nDb );
89227   zDb = db->aDb[iDb].zName;
89228   rcauth = sqlite3AuthCheck(pParse, SQLITE_DELETE, pTab->zName, 0, zDb);
89229   assert( rcauth==SQLITE_OK || rcauth==SQLITE_DENY || rcauth==SQLITE_IGNORE );
89230   if( rcauth==SQLITE_DENY ){
89231     goto delete_from_cleanup;
89232   }
89233   assert(!isView || pTrigger);
89234 
89235   /* Assign cursor numbers to the table and all its indices.
89236   */
89237   assert( pTabList->nSrc==1 );
89238   iTabCur = pTabList->a[0].iCursor = pParse->nTab++;
89239   for(nIdx=0, pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext, nIdx++){
89240     pParse->nTab++;
89241   }
89242 
89243   /* Start the view context
89244   */
89245   if( isView ){
89246     sqlite3AuthContextPush(pParse, &sContext, pTab->zName);
89247   }
89248 
89249   /* Begin generating code.
89250   */
89251   v = sqlite3GetVdbe(pParse);
89252   if( v==0 ){
89253     goto delete_from_cleanup;
89254   }
89255   if( pParse->nested==0 ) sqlite3VdbeCountChanges(v);
89256   sqlite3BeginWriteOperation(pParse, 1, iDb);
89257 
89258   /* If we are trying to delete from a view, realize that view into
89259   ** a ephemeral table.
89260   */
89261 #if !defined(SQLITE_OMIT_VIEW) && !defined(SQLITE_OMIT_TRIGGER)
89262   if( isView ){
89263     sqlite3MaterializeView(pParse, pTab, pWhere, iTabCur);
89264     iDataCur = iIdxCur = iTabCur;
89265   }
89266 #endif
89267 
89268   /* Resolve the column names in the WHERE clause.
89269   */
89270   memset(&sNC, 0, sizeof(sNC));
89271   sNC.pParse = pParse;
89272   sNC.pSrcList = pTabList;
89273   if( sqlite3ResolveExprNames(&sNC, pWhere) ){
89274     goto delete_from_cleanup;
89275   }
89276 
89277   /* Initialize the counter of the number of rows deleted, if
89278   ** we are counting rows.
89279   */
89280   if( db->flags & SQLITE_CountRows ){
89281     memCnt = ++pParse->nMem;
89282     sqlite3VdbeAddOp2(v, OP_Integer, 0, memCnt);
89283   }
89284 
89285 #ifndef SQLITE_OMIT_TRUNCATE_OPTIMIZATION
89286   /* Special case: A DELETE without a WHERE clause deletes everything.
89287   ** It is easier just to erase the whole table. Prior to version 3.6.5,
89288   ** this optimization caused the row change count (the value returned by 
89289   ** API function sqlite3_count_changes) to be set incorrectly.  */
89290   if( rcauth==SQLITE_OK && pWhere==0 && !pTrigger && !IsVirtual(pTab) 
89291    && 0==sqlite3FkRequired(pParse, pTab, 0, 0)
89292   ){
89293     assert( !isView );
89294     sqlite3TableLock(pParse, iDb, pTab->tnum, 1, pTab->zName);
89295     if( HasRowid(pTab) ){
89296       sqlite3VdbeAddOp4(v, OP_Clear, pTab->tnum, iDb, memCnt,
89297                         pTab->zName, P4_STATIC);
89298     }
89299     for(pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext){
89300       assert( pIdx->pSchema==pTab->pSchema );
89301       sqlite3VdbeAddOp2(v, OP_Clear, pIdx->tnum, iDb);
89302     }
89303   }else
89304 #endif /* SQLITE_OMIT_TRUNCATE_OPTIMIZATION */
89305   {
89306     if( HasRowid(pTab) ){
89307       /* For a rowid table, initialize the RowSet to an empty set */
89308       pPk = 0;
89309       nPk = 1;
89310       iRowSet = ++pParse->nMem;
89311       sqlite3VdbeAddOp2(v, OP_Null, 0, iRowSet);
89312     }else{
89313       /* For a WITHOUT ROWID table, create an ephermeral table used to
89314       ** hold all primary keys for rows to be deleted. */
89315       pPk = sqlite3PrimaryKeyIndex(pTab);
89316       assert( pPk!=0 );
89317       nPk = pPk->nKeyCol;
89318       iPk = pParse->nMem+1;
89319       pParse->nMem += nPk;
89320       iEphCur = pParse->nTab++;
89321       addrEphOpen = sqlite3VdbeAddOp2(v, OP_OpenEphemeral, iEphCur, nPk);
89322       sqlite3VdbeSetP4KeyInfo(pParse, pPk);
89323     }
89324   
89325     /* Construct a query to find the rowid or primary key for every row
89326     ** to be deleted, based on the WHERE clause.
89327     */
89328     pWInfo = sqlite3WhereBegin(pParse, pTabList, pWhere, 0, 0, 
89329                                WHERE_ONEPASS_DESIRED|WHERE_DUPLICATES_OK,
89330                                iTabCur+1);
89331     if( pWInfo==0 ) goto delete_from_cleanup;
89332     okOnePass = sqlite3WhereOkOnePass(pWInfo, aiCurOnePass);
89333   
89334     /* Keep track of the number of rows to be deleted */
89335     if( db->flags & SQLITE_CountRows ){
89336       sqlite3VdbeAddOp2(v, OP_AddImm, memCnt, 1);
89337     }
89338   
89339     /* Extract the rowid or primary key for the current row */
89340     if( pPk ){
89341       for(i=0; i<nPk; i++){
89342         sqlite3ExprCodeGetColumnOfTable(v, pTab, iTabCur,
89343                                         pPk->aiColumn[i], iPk+i);
89344       }
89345       iKey = iPk;
89346     }else{
89347       iKey = pParse->nMem + 1;
89348       iKey = sqlite3ExprCodeGetColumn(pParse, pTab, -1, iTabCur, iKey, 0);
89349       if( iKey>pParse->nMem ) pParse->nMem = iKey;
89350     }
89351   
89352     if( okOnePass ){
89353       /* For ONEPASS, no need to store the rowid/primary-key.  There is only
89354       ** one, so just keep it in its register(s) and fall through to the
89355       ** delete code.
89356       */
89357       nKey = nPk; /* OP_Found will use an unpacked key */
89358       aToOpen = sqlite3DbMallocRaw(db, nIdx+2);
89359       if( aToOpen==0 ){
89360         sqlite3WhereEnd(pWInfo);
89361         goto delete_from_cleanup;
89362       }
89363       memset(aToOpen, 1, nIdx+1);
89364       aToOpen[nIdx+1] = 0;
89365       if( aiCurOnePass[0]>=0 ) aToOpen[aiCurOnePass[0]-iTabCur] = 0;
89366       if( aiCurOnePass[1]>=0 ) aToOpen[aiCurOnePass[1]-iTabCur] = 0;
89367       if( addrEphOpen ) sqlite3VdbeChangeToNoop(v, addrEphOpen);
89368       addrDelete = sqlite3VdbeAddOp0(v, OP_Goto); /* Jump to DELETE logic */
89369     }else if( pPk ){
89370       /* Construct a composite key for the row to be deleted and remember it */
89371       iKey = ++pParse->nMem;
89372       nKey = 0;   /* Zero tells OP_Found to use a composite key */
89373       sqlite3VdbeAddOp4(v, OP_MakeRecord, iPk, nPk, iKey,
89374                         sqlite3IndexAffinityStr(v, pPk), P4_TRANSIENT);
89375       sqlite3VdbeAddOp2(v, OP_IdxInsert, iEphCur, iKey);
89376     }else{
89377       /* Get the rowid of the row to be deleted and remember it in the RowSet */
89378       nKey = 1;  /* OP_Seek always uses a single rowid */
89379       sqlite3VdbeAddOp2(v, OP_RowSetAdd, iRowSet, iKey);
89380     }
89381   
89382     /* End of the WHERE loop */
89383     sqlite3WhereEnd(pWInfo);
89384     if( okOnePass ){
89385       /* Bypass the delete logic below if the WHERE loop found zero rows */
89386       addrBypass = sqlite3VdbeMakeLabel(v);
89387       sqlite3VdbeAddOp2(v, OP_Goto, 0, addrBypass);
89388       sqlite3VdbeJumpHere(v, addrDelete);
89389     }
89390   
89391     /* Unless this is a view, open cursors for the table we are 
89392     ** deleting from and all its indices. If this is a view, then the
89393     ** only effect this statement has is to fire the INSTEAD OF 
89394     ** triggers.
89395     */
89396     if( !isView ){
89397       sqlite3OpenTableAndIndices(pParse, pTab, OP_OpenWrite, iTabCur, aToOpen,
89398                                  &iDataCur, &iIdxCur);
89399       assert( pPk || iDataCur==iTabCur );
89400       assert( pPk || iIdxCur==iDataCur+1 );
89401     }
89402   
89403     /* Set up a loop over the rowids/primary-keys that were found in the
89404     ** where-clause loop above.
89405     */
89406     if( okOnePass ){
89407       /* Just one row.  Hence the top-of-loop is a no-op */
89408       assert( nKey==nPk ); /* OP_Found will use an unpacked key */
89409       if( aToOpen[iDataCur-iTabCur] ){
89410         assert( pPk!=0 );
89411         sqlite3VdbeAddOp4Int(v, OP_NotFound, iDataCur, addrBypass, iKey, nKey);
89412       }
89413     }else if( pPk ){
89414       addrLoop = sqlite3VdbeAddOp1(v, OP_Rewind, iEphCur);
89415       sqlite3VdbeAddOp2(v, OP_RowKey, iEphCur, iKey);
89416       assert( nKey==0 );  /* OP_Found will use a composite key */
89417     }else{
89418       addrLoop = sqlite3VdbeAddOp3(v, OP_RowSetRead, iRowSet, 0, iKey);
89419       assert( nKey==1 );
89420     }  
89421   
89422     /* Delete the row */
89423 #ifndef SQLITE_OMIT_VIRTUALTABLE
89424     if( IsVirtual(pTab) ){
89425       const char *pVTab = (const char *)sqlite3GetVTable(db, pTab);
89426       sqlite3VtabMakeWritable(pParse, pTab);
89427       sqlite3VdbeAddOp4(v, OP_VUpdate, 0, 1, iKey, pVTab, P4_VTAB);
89428       sqlite3VdbeChangeP5(v, OE_Abort);
89429       sqlite3MayAbort(pParse);
89430     }else
89431 #endif
89432     {
89433       int count = (pParse->nested==0);    /* True to count changes */
89434       sqlite3GenerateRowDelete(pParse, pTab, pTrigger, iDataCur, iIdxCur,
89435                                iKey, nKey, count, OE_Default, okOnePass);
89436     }
89437   
89438     /* End of the loop over all rowids/primary-keys. */
89439     if( okOnePass ){
89440       sqlite3VdbeResolveLabel(v, addrBypass);
89441     }else if( pPk ){
89442       sqlite3VdbeAddOp2(v, OP_Next, iEphCur, addrLoop+1);
89443       sqlite3VdbeJumpHere(v, addrLoop);
89444     }else{
89445       sqlite3VdbeAddOp2(v, OP_Goto, 0, addrLoop);
89446       sqlite3VdbeJumpHere(v, addrLoop);
89447     }     
89448   
89449     /* Close the cursors open on the table and its indexes. */
89450     if( !isView && !IsVirtual(pTab) ){
89451       if( !pPk ) sqlite3VdbeAddOp1(v, OP_Close, iDataCur);
89452       for(i=0, pIdx=pTab->pIndex; pIdx; i++, pIdx=pIdx->pNext){
89453         sqlite3VdbeAddOp1(v, OP_Close, iIdxCur + i);
89454       }
89455     }
89456   } /* End non-truncate path */
89457 
89458   /* Update the sqlite_sequence table by storing the content of the
89459   ** maximum rowid counter values recorded while inserting into
89460   ** autoincrement tables.
89461   */
89462   if( pParse->nested==0 && pParse->pTriggerTab==0 ){
89463     sqlite3AutoincrementEnd(pParse);
89464   }
89465 
89466   /* Return the number of rows that were deleted. If this routine is 
89467   ** generating code because of a call to sqlite3NestedParse(), do not
89468   ** invoke the callback function.
89469   */
89470   if( (db->flags&SQLITE_CountRows) && !pParse->nested && !pParse->pTriggerTab ){
89471     sqlite3VdbeAddOp2(v, OP_ResultRow, memCnt, 1);
89472     sqlite3VdbeSetNumCols(v, 1);
89473     sqlite3VdbeSetColName(v, 0, COLNAME_NAME, "rows deleted", SQLITE_STATIC);
89474   }
89475 
89476 delete_from_cleanup:
89477   sqlite3AuthContextPop(&sContext);
89478   sqlite3SrcListDelete(db, pTabList);
89479   sqlite3ExprDelete(db, pWhere);
89480   sqlite3DbFree(db, aToOpen);
89481   return;
89482 }
89483 /* Make sure "isView" and other macros defined above are undefined. Otherwise
89484 ** thely may interfere with compilation of other functions in this file
89485 ** (or in another file, if this file becomes part of the amalgamation).  */
89486 #ifdef isView
89487  #undef isView
89488 #endif
89489 #ifdef pTrigger
89490  #undef pTrigger
89491 #endif
89492 
89493 /*
89494 ** This routine generates VDBE code that causes a single row of a
89495 ** single table to be deleted.  Both the original table entry and
89496 ** all indices are removed.
89497 **
89498 ** Preconditions:
89499 **
89500 **   1.  iDataCur is an open cursor on the btree that is the canonical data
89501 **       store for the table.  (This will be either the table itself,
89502 **       in the case of a rowid table, or the PRIMARY KEY index in the case
89503 **       of a WITHOUT ROWID table.)
89504 **
89505 **   2.  Read/write cursors for all indices of pTab must be open as
89506 **       cursor number iIdxCur+i for the i-th index.
89507 **
89508 **   3.  The primary key for the row to be deleted must be stored in a
89509 **       sequence of nPk memory cells starting at iPk.  If nPk==0 that means
89510 **       that a search record formed from OP_MakeRecord is contained in the
89511 **       single memory location iPk.
89512 */
89513 SQLITE_PRIVATE void sqlite3GenerateRowDelete(
89514   Parse *pParse,     /* Parsing context */
89515   Table *pTab,       /* Table containing the row to be deleted */
89516   Trigger *pTrigger, /* List of triggers to (potentially) fire */
89517   int iDataCur,      /* Cursor from which column data is extracted */
89518   int iIdxCur,       /* First index cursor */
89519   int iPk,           /* First memory cell containing the PRIMARY KEY */
89520   i16 nPk,           /* Number of PRIMARY KEY memory cells */
89521   u8 count,          /* If non-zero, increment the row change counter */
89522   u8 onconf,         /* Default ON CONFLICT policy for triggers */
89523   u8 bNoSeek         /* iDataCur is already pointing to the row to delete */
89524 ){
89525   Vdbe *v = pParse->pVdbe;        /* Vdbe */
89526   int iOld = 0;                   /* First register in OLD.* array */
89527   int iLabel;                     /* Label resolved to end of generated code */
89528   u8 opSeek;                      /* Seek opcode */
89529 
89530   /* Vdbe is guaranteed to have been allocated by this stage. */
89531   assert( v );
89532   VdbeModuleComment((v, "BEGIN: GenRowDel(%d,%d,%d,%d)",
89533                          iDataCur, iIdxCur, iPk, (int)nPk));
89534 
89535   /* Seek cursor iCur to the row to delete. If this row no longer exists 
89536   ** (this can happen if a trigger program has already deleted it), do
89537   ** not attempt to delete it or fire any DELETE triggers.  */
89538   iLabel = sqlite3VdbeMakeLabel(v);
89539   opSeek = HasRowid(pTab) ? OP_NotExists : OP_NotFound;
89540   if( !bNoSeek ) sqlite3VdbeAddOp4Int(v, opSeek, iDataCur, iLabel, iPk, nPk);
89541  
89542   /* If there are any triggers to fire, allocate a range of registers to
89543   ** use for the old.* references in the triggers.  */
89544   if( sqlite3FkRequired(pParse, pTab, 0, 0) || pTrigger ){
89545     u32 mask;                     /* Mask of OLD.* columns in use */
89546     int iCol;                     /* Iterator used while populating OLD.* */
89547     int addrStart;                /* Start of BEFORE trigger programs */
89548 
89549     /* TODO: Could use temporary registers here. Also could attempt to
89550     ** avoid copying the contents of the rowid register.  */
89551     mask = sqlite3TriggerColmask(
89552         pParse, pTrigger, 0, 0, TRIGGER_BEFORE|TRIGGER_AFTER, pTab, onconf
89553     );
89554     mask |= sqlite3FkOldmask(pParse, pTab);
89555     iOld = pParse->nMem+1;
89556     pParse->nMem += (1 + pTab->nCol);
89557 
89558     /* Populate the OLD.* pseudo-table register array. These values will be 
89559     ** used by any BEFORE and AFTER triggers that exist.  */
89560     sqlite3VdbeAddOp2(v, OP_Copy, iPk, iOld);
89561     for(iCol=0; iCol<pTab->nCol; iCol++){
89562       if( mask==0xffffffff || mask&(1<<iCol) ){
89563         sqlite3ExprCodeGetColumnOfTable(v, pTab, iDataCur, iCol, iOld+iCol+1);
89564       }
89565     }
89566 
89567     /* Invoke BEFORE DELETE trigger programs. */
89568     addrStart = sqlite3VdbeCurrentAddr(v);
89569     sqlite3CodeRowTrigger(pParse, pTrigger, 
89570         TK_DELETE, 0, TRIGGER_BEFORE, pTab, iOld, onconf, iLabel
89571     );
89572 
89573     /* If any BEFORE triggers were coded, then seek the cursor to the 
89574     ** row to be deleted again. It may be that the BEFORE triggers moved
89575     ** the cursor or of already deleted the row that the cursor was
89576     ** pointing to.
89577     */
89578     if( addrStart<sqlite3VdbeCurrentAddr(v) ){
89579       sqlite3VdbeAddOp4Int(v, opSeek, iDataCur, iLabel, iPk, nPk);
89580     }
89581 
89582     /* Do FK processing. This call checks that any FK constraints that
89583     ** refer to this table (i.e. constraints attached to other tables) 
89584     ** are not violated by deleting this row.  */
89585     sqlite3FkCheck(pParse, pTab, iOld, 0, 0, 0);
89586   }
89587 
89588   /* Delete the index and table entries. Skip this step if pTab is really
89589   ** a view (in which case the only effect of the DELETE statement is to
89590   ** fire the INSTEAD OF triggers).  */ 
89591   if( pTab->pSelect==0 ){
89592     sqlite3GenerateRowIndexDelete(pParse, pTab, iDataCur, iIdxCur, 0);
89593     sqlite3VdbeAddOp2(v, OP_Delete, iDataCur, (count?OPFLAG_NCHANGE:0));
89594     if( count ){
89595       sqlite3VdbeChangeP4(v, -1, pTab->zName, P4_TRANSIENT);
89596     }
89597   }
89598 
89599   /* Do any ON CASCADE, SET NULL or SET DEFAULT operations required to
89600   ** handle rows (possibly in other tables) that refer via a foreign key
89601   ** to the row just deleted. */ 
89602   sqlite3FkActions(pParse, pTab, 0, iOld, 0, 0);
89603 
89604   /* Invoke AFTER DELETE trigger programs. */
89605   sqlite3CodeRowTrigger(pParse, pTrigger, 
89606       TK_DELETE, 0, TRIGGER_AFTER, pTab, iOld, onconf, iLabel
89607   );
89608 
89609   /* Jump here if the row had already been deleted before any BEFORE
89610   ** trigger programs were invoked. Or if a trigger program throws a 
89611   ** RAISE(IGNORE) exception.  */
89612   sqlite3VdbeResolveLabel(v, iLabel);
89613   VdbeModuleComment((v, "END: GenRowDel()"));
89614 }
89615 
89616 /*
89617 ** This routine generates VDBE code that causes the deletion of all
89618 ** index entries associated with a single row of a single table, pTab
89619 **
89620 ** Preconditions:
89621 **
89622 **   1.  A read/write cursor "iDataCur" must be open on the canonical storage
89623 **       btree for the table pTab.  (This will be either the table itself
89624 **       for rowid tables or to the primary key index for WITHOUT ROWID
89625 **       tables.)
89626 **
89627 **   2.  Read/write cursors for all indices of pTab must be open as
89628 **       cursor number iIdxCur+i for the i-th index.  (The pTab->pIndex
89629 **       index is the 0-th index.)
89630 **
89631 **   3.  The "iDataCur" cursor must be already be positioned on the row
89632 **       that is to be deleted.
89633 */
89634 SQLITE_PRIVATE void sqlite3GenerateRowIndexDelete(
89635   Parse *pParse,     /* Parsing and code generating context */
89636   Table *pTab,       /* Table containing the row to be deleted */
89637   int iDataCur,      /* Cursor of table holding data. */
89638   int iIdxCur,       /* First index cursor */
89639   int *aRegIdx       /* Only delete if aRegIdx!=0 && aRegIdx[i]>0 */
89640 ){
89641   int i;             /* Index loop counter */
89642   int r1;            /* Register holding an index key */
89643   int iPartIdxLabel; /* Jump destination for skipping partial index entries */
89644   Index *pIdx;       /* Current index */
89645   Vdbe *v;           /* The prepared statement under construction */
89646   Index *pPk;        /* PRIMARY KEY index, or NULL for rowid tables */
89647 
89648   v = pParse->pVdbe;
89649   pPk = HasRowid(pTab) ? 0 : sqlite3PrimaryKeyIndex(pTab);
89650   for(i=0, pIdx=pTab->pIndex; pIdx; i++, pIdx=pIdx->pNext){
89651     assert( iIdxCur+i!=iDataCur || pPk==pIdx );
89652     if( aRegIdx!=0 && aRegIdx[i]==0 ) continue;
89653     if( pIdx==pPk ) continue;
89654     VdbeModuleComment((v, "GenRowIdxDel for %s", pIdx->zName));
89655     r1 = sqlite3GenerateIndexKey(pParse, pIdx, iDataCur, 0, 1, &iPartIdxLabel);
89656     sqlite3VdbeAddOp3(v, OP_IdxDelete, iIdxCur+i, r1,
89657                       pIdx->uniqNotNull ? pIdx->nKeyCol : pIdx->nColumn);
89658     sqlite3VdbeResolveLabel(v, iPartIdxLabel);
89659   }
89660 }
89661 
89662 /*
89663 ** Generate code that will assemble an index key and stores it in register
89664 ** regOut.  The key with be for index pIdx which is an index on pTab.
89665 ** iCur is the index of a cursor open on the pTab table and pointing to
89666 ** the entry that needs indexing.  If pTab is a WITHOUT ROWID table, then
89667 ** iCur must be the cursor of the PRIMARY KEY index.
89668 **
89669 ** Return a register number which is the first in a block of
89670 ** registers that holds the elements of the index key.  The
89671 ** block of registers has already been deallocated by the time
89672 ** this routine returns.
89673 **
89674 ** If *piPartIdxLabel is not NULL, fill it in with a label and jump
89675 ** to that label if pIdx is a partial index that should be skipped.
89676 ** A partial index should be skipped if its WHERE clause evaluates
89677 ** to false or null.  If pIdx is not a partial index, *piPartIdxLabel
89678 ** will be set to zero which is an empty label that is ignored by
89679 ** sqlite3VdbeResolveLabel().
89680 */
89681 SQLITE_PRIVATE int sqlite3GenerateIndexKey(
89682   Parse *pParse,       /* Parsing context */
89683   Index *pIdx,         /* The index for which to generate a key */
89684   int iDataCur,        /* Cursor number from which to take column data */
89685   int regOut,          /* Put the new key into this register if not 0 */
89686   int prefixOnly,      /* Compute only a unique prefix of the key */
89687   int *piPartIdxLabel  /* OUT: Jump to this label to skip partial index */
89688 ){
89689   Vdbe *v = pParse->pVdbe;
89690   int j;
89691   Table *pTab = pIdx->pTable;
89692   int regBase;
89693   int nCol;
89694   Index *pPk;
89695 
89696   if( piPartIdxLabel ){
89697     if( pIdx->pPartIdxWhere ){
89698       *piPartIdxLabel = sqlite3VdbeMakeLabel(v);
89699       pParse->iPartIdxTab = iDataCur;
89700       sqlite3ExprIfFalse(pParse, pIdx->pPartIdxWhere, *piPartIdxLabel, 
89701                          SQLITE_JUMPIFNULL);
89702     }else{
89703       *piPartIdxLabel = 0;
89704     }
89705   }
89706   nCol = (prefixOnly && pIdx->uniqNotNull) ? pIdx->nKeyCol : pIdx->nColumn;
89707   regBase = sqlite3GetTempRange(pParse, nCol);
89708   pPk = HasRowid(pTab) ? 0 : sqlite3PrimaryKeyIndex(pTab);
89709   for(j=0; j<nCol; j++){
89710     i16 idx = pIdx->aiColumn[j];
89711     if( pPk ) idx = sqlite3ColumnOfIndex(pPk, idx);
89712     if( idx<0 || idx==pTab->iPKey ){
89713       sqlite3VdbeAddOp2(v, OP_Rowid, iDataCur, regBase+j);
89714     }else{
89715       sqlite3VdbeAddOp3(v, OP_Column, iDataCur, idx, regBase+j);
89716       sqlite3ColumnDefault(v, pTab, pIdx->aiColumn[j], -1);
89717     }
89718   }
89719   if( regOut ){
89720     const char *zAff;
89721     if( pTab->pSelect
89722      || OptimizationDisabled(pParse->db, SQLITE_IdxRealAsInt)
89723     ){
89724       zAff = 0;
89725     }else{
89726       zAff = sqlite3IndexAffinityStr(v, pIdx);
89727     }
89728     sqlite3VdbeAddOp3(v, OP_MakeRecord, regBase, nCol, regOut);
89729     sqlite3VdbeChangeP4(v, -1, zAff, P4_TRANSIENT);
89730   }
89731   sqlite3ReleaseTempRange(pParse, regBase, nCol);
89732   return regBase;
89733 }
89734 
89735 /************** End of delete.c **********************************************/
89736 /************** Begin file func.c ********************************************/
89737 /*
89738 ** 2002 February 23
89739 **
89740 ** The author disclaims copyright to this source code.  In place of
89741 ** a legal notice, here is a blessing:
89742 **
89743 **    May you do good and not evil.
89744 **    May you find forgiveness for yourself and forgive others.
89745 **    May you share freely, never taking more than you give.
89746 **
89747 *************************************************************************
89748 ** This file contains the C functions that implement various SQL
89749 ** functions of SQLite.  
89750 **
89751 ** There is only one exported symbol in this file - the function
89752 ** sqliteRegisterBuildinFunctions() found at the bottom of the file.
89753 ** All other code has file scope.
89754 */
89755 /* #include <stdlib.h> */
89756 /* #include <assert.h> */
89757 
89758 /*
89759 ** Return the collating function associated with a function.
89760 */
89761 static CollSeq *sqlite3GetFuncCollSeq(sqlite3_context *context){
89762   return context->pColl;
89763 }
89764 
89765 /*
89766 ** Indicate that the accumulator load should be skipped on this
89767 ** iteration of the aggregate loop.
89768 */
89769 static void sqlite3SkipAccumulatorLoad(sqlite3_context *context){
89770   context->skipFlag = 1;
89771 }
89772 
89773 /*
89774 ** Implementation of the non-aggregate min() and max() functions
89775 */
89776 static void minmaxFunc(
89777   sqlite3_context *context,
89778   int argc,
89779   sqlite3_value **argv
89780 ){
89781   int i;
89782   int mask;    /* 0 for min() or 0xffffffff for max() */
89783   int iBest;
89784   CollSeq *pColl;
89785 
89786   assert( argc>1 );
89787   mask = sqlite3_user_data(context)==0 ? 0 : -1;
89788   pColl = sqlite3GetFuncCollSeq(context);
89789   assert( pColl );
89790   assert( mask==-1 || mask==0 );
89791   iBest = 0;
89792   if( sqlite3_value_type(argv[0])==SQLITE_NULL ) return;
89793   for(i=1; i<argc; i++){
89794     if( sqlite3_value_type(argv[i])==SQLITE_NULL ) return;
89795     if( (sqlite3MemCompare(argv[iBest], argv[i], pColl)^mask)>=0 ){
89796       testcase( mask==0 );
89797       iBest = i;
89798     }
89799   }
89800   sqlite3_result_value(context, argv[iBest]);
89801 }
89802 
89803 /*
89804 ** Return the type of the argument.
89805 */
89806 static void typeofFunc(
89807   sqlite3_context *context,
89808   int NotUsed,
89809   sqlite3_value **argv
89810 ){
89811   const char *z = 0;
89812   UNUSED_PARAMETER(NotUsed);
89813   switch( sqlite3_value_type(argv[0]) ){
89814     case SQLITE_INTEGER: z = "integer"; break;
89815     case SQLITE_TEXT:    z = "text";    break;
89816     case SQLITE_FLOAT:   z = "real";    break;
89817     case SQLITE_BLOB:    z = "blob";    break;
89818     default:             z = "null";    break;
89819   }
89820   sqlite3_result_text(context, z, -1, SQLITE_STATIC);
89821 }
89822 
89823 
89824 /*
89825 ** Implementation of the length() function
89826 */
89827 static void lengthFunc(
89828   sqlite3_context *context,
89829   int argc,
89830   sqlite3_value **argv
89831 ){
89832   int len;
89833 
89834   assert( argc==1 );
89835   UNUSED_PARAMETER(argc);
89836   switch( sqlite3_value_type(argv[0]) ){
89837     case SQLITE_BLOB:
89838     case SQLITE_INTEGER:
89839     case SQLITE_FLOAT: {
89840       sqlite3_result_int(context, sqlite3_value_bytes(argv[0]));
89841       break;
89842     }
89843     case SQLITE_TEXT: {
89844       const unsigned char *z = sqlite3_value_text(argv[0]);
89845       if( z==0 ) return;
89846       len = 0;
89847       while( *z ){
89848         len++;
89849         SQLITE_SKIP_UTF8(z);
89850       }
89851       sqlite3_result_int(context, len);
89852       break;
89853     }
89854     default: {
89855       sqlite3_result_null(context);
89856       break;
89857     }
89858   }
89859 }
89860 
89861 /*
89862 ** Implementation of the abs() function.
89863 **
89864 ** IMP: R-23979-26855 The abs(X) function returns the absolute value of
89865 ** the numeric argument X. 
89866 */
89867 static void absFunc(sqlite3_context *context, int argc, sqlite3_value **argv){
89868   assert( argc==1 );
89869   UNUSED_PARAMETER(argc);
89870   switch( sqlite3_value_type(argv[0]) ){
89871     case SQLITE_INTEGER: {
89872       i64 iVal = sqlite3_value_int64(argv[0]);
89873       if( iVal<0 ){
89874         if( (iVal<<1)==0 ){
89875           /* IMP: R-31676-45509 If X is the integer -9223372036854775808
89876           ** then abs(X) throws an integer overflow error since there is no
89877           ** equivalent positive 64-bit two complement value. */
89878           sqlite3_result_error(context, "integer overflow", -1);
89879           return;
89880         }
89881         iVal = -iVal;
89882       } 
89883       sqlite3_result_int64(context, iVal);
89884       break;
89885     }
89886     case SQLITE_NULL: {
89887       /* IMP: R-37434-19929 Abs(X) returns NULL if X is NULL. */
89888       sqlite3_result_null(context);
89889       break;
89890     }
89891     default: {
89892       /* Because sqlite3_value_double() returns 0.0 if the argument is not
89893       ** something that can be converted into a number, we have:
89894       ** IMP: R-57326-31541 Abs(X) return 0.0 if X is a string or blob that
89895       ** cannot be converted to a numeric value. 
89896       */
89897       double rVal = sqlite3_value_double(argv[0]);
89898       if( rVal<0 ) rVal = -rVal;
89899       sqlite3_result_double(context, rVal);
89900       break;
89901     }
89902   }
89903 }
89904 
89905 /*
89906 ** Implementation of the instr() function.
89907 **
89908 ** instr(haystack,needle) finds the first occurrence of needle
89909 ** in haystack and returns the number of previous characters plus 1,
89910 ** or 0 if needle does not occur within haystack.
89911 **
89912 ** If both haystack and needle are BLOBs, then the result is one more than
89913 ** the number of bytes in haystack prior to the first occurrence of needle,
89914 ** or 0 if needle never occurs in haystack.
89915 */
89916 static void instrFunc(
89917   sqlite3_context *context,
89918   int argc,
89919   sqlite3_value **argv
89920 ){
89921   const unsigned char *zHaystack;
89922   const unsigned char *zNeedle;
89923   int nHaystack;
89924   int nNeedle;
89925   int typeHaystack, typeNeedle;
89926   int N = 1;
89927   int isText;
89928 
89929   UNUSED_PARAMETER(argc);
89930   typeHaystack = sqlite3_value_type(argv[0]);
89931   typeNeedle = sqlite3_value_type(argv[1]);
89932   if( typeHaystack==SQLITE_NULL || typeNeedle==SQLITE_NULL ) return;
89933   nHaystack = sqlite3_value_bytes(argv[0]);
89934   nNeedle = sqlite3_value_bytes(argv[1]);
89935   if( typeHaystack==SQLITE_BLOB && typeNeedle==SQLITE_BLOB ){
89936     zHaystack = sqlite3_value_blob(argv[0]);
89937     zNeedle = sqlite3_value_blob(argv[1]);
89938     isText = 0;
89939   }else{
89940     zHaystack = sqlite3_value_text(argv[0]);
89941     zNeedle = sqlite3_value_text(argv[1]);
89942     isText = 1;
89943   }
89944   while( nNeedle<=nHaystack && memcmp(zHaystack, zNeedle, nNeedle)!=0 ){
89945     N++;
89946     do{
89947       nHaystack--;
89948       zHaystack++;
89949     }while( isText && (zHaystack[0]&0xc0)==0x80 );
89950   }
89951   if( nNeedle>nHaystack ) N = 0;
89952   sqlite3_result_int(context, N);
89953 }
89954 
89955 /*
89956 ** Implementation of the substr() function.
89957 **
89958 ** substr(x,p1,p2)  returns p2 characters of x[] beginning with p1.
89959 ** p1 is 1-indexed.  So substr(x,1,1) returns the first character
89960 ** of x.  If x is text, then we actually count UTF-8 characters.
89961 ** If x is a blob, then we count bytes.
89962 **
89963 ** If p1 is negative, then we begin abs(p1) from the end of x[].
89964 **
89965 ** If p2 is negative, return the p2 characters preceding p1.
89966 */
89967 static void substrFunc(
89968   sqlite3_context *context,
89969   int argc,
89970   sqlite3_value **argv
89971 ){
89972   const unsigned char *z;
89973   const unsigned char *z2;
89974   int len;
89975   int p0type;
89976   i64 p1, p2;
89977   int negP2 = 0;
89978 
89979   assert( argc==3 || argc==2 );
89980   if( sqlite3_value_type(argv[1])==SQLITE_NULL
89981    || (argc==3 && sqlite3_value_type(argv[2])==SQLITE_NULL)
89982   ){
89983     return;
89984   }
89985   p0type = sqlite3_value_type(argv[0]);
89986   p1 = sqlite3_value_int(argv[1]);
89987   if( p0type==SQLITE_BLOB ){
89988     len = sqlite3_value_bytes(argv[0]);
89989     z = sqlite3_value_blob(argv[0]);
89990     if( z==0 ) return;
89991     assert( len==sqlite3_value_bytes(argv[0]) );
89992   }else{
89993     z = sqlite3_value_text(argv[0]);
89994     if( z==0 ) return;
89995     len = 0;
89996     if( p1<0 ){
89997       for(z2=z; *z2; len++){
89998         SQLITE_SKIP_UTF8(z2);
89999       }
90000     }
90001   }
90002   if( argc==3 ){
90003     p2 = sqlite3_value_int(argv[2]);
90004     if( p2<0 ){
90005       p2 = -p2;
90006       negP2 = 1;
90007     }
90008   }else{
90009     p2 = sqlite3_context_db_handle(context)->aLimit[SQLITE_LIMIT_LENGTH];
90010   }
90011   if( p1<0 ){
90012     p1 += len;
90013     if( p1<0 ){
90014       p2 += p1;
90015       if( p2<0 ) p2 = 0;
90016       p1 = 0;
90017     }
90018   }else if( p1>0 ){
90019     p1--;
90020   }else if( p2>0 ){
90021     p2--;
90022   }
90023   if( negP2 ){
90024     p1 -= p2;
90025     if( p1<0 ){
90026       p2 += p1;
90027       p1 = 0;
90028     }
90029   }
90030   assert( p1>=0 && p2>=0 );
90031   if( p0type!=SQLITE_BLOB ){
90032     while( *z && p1 ){
90033       SQLITE_SKIP_UTF8(z);
90034       p1--;
90035     }
90036     for(z2=z; *z2 && p2; p2--){
90037       SQLITE_SKIP_UTF8(z2);
90038     }
90039     sqlite3_result_text(context, (char*)z, (int)(z2-z), SQLITE_TRANSIENT);
90040   }else{
90041     if( p1+p2>len ){
90042       p2 = len-p1;
90043       if( p2<0 ) p2 = 0;
90044     }
90045     sqlite3_result_blob(context, (char*)&z[p1], (int)p2, SQLITE_TRANSIENT);
90046   }
90047 }
90048 
90049 /*
90050 ** Implementation of the round() function
90051 */
90052 #ifndef SQLITE_OMIT_FLOATING_POINT
90053 static void roundFunc(sqlite3_context *context, int argc, sqlite3_value **argv){
90054   int n = 0;
90055   double r;
90056   char *zBuf;
90057   assert( argc==1 || argc==2 );
90058   if( argc==2 ){
90059     if( SQLITE_NULL==sqlite3_value_type(argv[1]) ) return;
90060     n = sqlite3_value_int(argv[1]);
90061     if( n>30 ) n = 30;
90062     if( n<0 ) n = 0;
90063   }
90064   if( sqlite3_value_type(argv[0])==SQLITE_NULL ) return;
90065   r = sqlite3_value_double(argv[0]);
90066   /* If Y==0 and X will fit in a 64-bit int,
90067   ** handle the rounding directly,
90068   ** otherwise use printf.
90069   */
90070   if( n==0 && r>=0 && r<LARGEST_INT64-1 ){
90071     r = (double)((sqlite_int64)(r+0.5));
90072   }else if( n==0 && r<0 && (-r)<LARGEST_INT64-1 ){
90073     r = -(double)((sqlite_int64)((-r)+0.5));
90074   }else{
90075     zBuf = sqlite3_mprintf("%.*f",n,r);
90076     if( zBuf==0 ){
90077       sqlite3_result_error_nomem(context);
90078       return;
90079     }
90080     sqlite3AtoF(zBuf, &r, sqlite3Strlen30(zBuf), SQLITE_UTF8);
90081     sqlite3_free(zBuf);
90082   }
90083   sqlite3_result_double(context, r);
90084 }
90085 #endif
90086 
90087 /*
90088 ** Allocate nByte bytes of space using sqlite3_malloc(). If the
90089 ** allocation fails, call sqlite3_result_error_nomem() to notify
90090 ** the database handle that malloc() has failed and return NULL.
90091 ** If nByte is larger than the maximum string or blob length, then
90092 ** raise an SQLITE_TOOBIG exception and return NULL.
90093 */
90094 static void *contextMalloc(sqlite3_context *context, i64 nByte){
90095   char *z;
90096   sqlite3 *db = sqlite3_context_db_handle(context);
90097   assert( nByte>0 );
90098   testcase( nByte==db->aLimit[SQLITE_LIMIT_LENGTH] );
90099   testcase( nByte==db->aLimit[SQLITE_LIMIT_LENGTH]+1 );
90100   if( nByte>db->aLimit[SQLITE_LIMIT_LENGTH] ){
90101     sqlite3_result_error_toobig(context);
90102     z = 0;
90103   }else{
90104     z = sqlite3Malloc((int)nByte);
90105     if( !z ){
90106       sqlite3_result_error_nomem(context);
90107     }
90108   }
90109   return z;
90110 }
90111 
90112 /*
90113 ** Implementation of the upper() and lower() SQL functions.
90114 */
90115 static void upperFunc(sqlite3_context *context, int argc, sqlite3_value **argv){
90116   char *z1;
90117   const char *z2;
90118   int i, n;
90119   UNUSED_PARAMETER(argc);
90120   z2 = (char*)sqlite3_value_text(argv[0]);
90121   n = sqlite3_value_bytes(argv[0]);
90122   /* Verify that the call to _bytes() does not invalidate the _text() pointer */
90123   assert( z2==(char*)sqlite3_value_text(argv[0]) );
90124   if( z2 ){
90125     z1 = contextMalloc(context, ((i64)n)+1);
90126     if( z1 ){
90127       for(i=0; i<n; i++){
90128         z1[i] = (char)sqlite3Toupper(z2[i]);
90129       }
90130       sqlite3_result_text(context, z1, n, sqlite3_free);
90131     }
90132   }
90133 }
90134 static void lowerFunc(sqlite3_context *context, int argc, sqlite3_value **argv){
90135   char *z1;
90136   const char *z2;
90137   int i, n;
90138   UNUSED_PARAMETER(argc);
90139   z2 = (char*)sqlite3_value_text(argv[0]);
90140   n = sqlite3_value_bytes(argv[0]);
90141   /* Verify that the call to _bytes() does not invalidate the _text() pointer */
90142   assert( z2==(char*)sqlite3_value_text(argv[0]) );
90143   if( z2 ){
90144     z1 = contextMalloc(context, ((i64)n)+1);
90145     if( z1 ){
90146       for(i=0; i<n; i++){
90147         z1[i] = sqlite3Tolower(z2[i]);
90148       }
90149       sqlite3_result_text(context, z1, n, sqlite3_free);
90150     }
90151   }
90152 }
90153 
90154 /*
90155 ** Some functions like COALESCE() and IFNULL() and UNLIKELY() are implemented
90156 ** as VDBE code so that unused argument values do not have to be computed.
90157 ** However, we still need some kind of function implementation for this
90158 ** routines in the function table.  The noopFunc macro provides this.
90159 ** noopFunc will never be called so it doesn't matter what the implementation
90160 ** is.  We might as well use the "version()" function as a substitute.
90161 */
90162 #define noopFunc versionFunc   /* Substitute function - never called */
90163 
90164 /*
90165 ** Implementation of random().  Return a random integer.  
90166 */
90167 static void randomFunc(
90168   sqlite3_context *context,
90169   int NotUsed,
90170   sqlite3_value **NotUsed2
90171 ){
90172   sqlite_int64 r;
90173   UNUSED_PARAMETER2(NotUsed, NotUsed2);
90174   sqlite3_randomness(sizeof(r), &r);
90175   if( r<0 ){
90176     /* We need to prevent a random number of 0x8000000000000000 
90177     ** (or -9223372036854775808) since when you do abs() of that
90178     ** number of you get the same value back again.  To do this
90179     ** in a way that is testable, mask the sign bit off of negative
90180     ** values, resulting in a positive value.  Then take the 
90181     ** 2s complement of that positive value.  The end result can
90182     ** therefore be no less than -9223372036854775807.
90183     */
90184     r = -(r & LARGEST_INT64);
90185   }
90186   sqlite3_result_int64(context, r);
90187 }
90188 
90189 /*
90190 ** Implementation of randomblob(N).  Return a random blob
90191 ** that is N bytes long.
90192 */
90193 static void randomBlob(
90194   sqlite3_context *context,
90195   int argc,
90196   sqlite3_value **argv
90197 ){
90198   int n;
90199   unsigned char *p;
90200   assert( argc==1 );
90201   UNUSED_PARAMETER(argc);
90202   n = sqlite3_value_int(argv[0]);
90203   if( n<1 ){
90204     n = 1;
90205   }
90206   p = contextMalloc(context, n);
90207   if( p ){
90208     sqlite3_randomness(n, p);
90209     sqlite3_result_blob(context, (char*)p, n, sqlite3_free);
90210   }
90211 }
90212 
90213 /*
90214 ** Implementation of the last_insert_rowid() SQL function.  The return
90215 ** value is the same as the sqlite3_last_insert_rowid() API function.
90216 */
90217 static void last_insert_rowid(
90218   sqlite3_context *context, 
90219   int NotUsed, 
90220   sqlite3_value **NotUsed2
90221 ){
90222   sqlite3 *db = sqlite3_context_db_handle(context);
90223   UNUSED_PARAMETER2(NotUsed, NotUsed2);
90224   /* IMP: R-51513-12026 The last_insert_rowid() SQL function is a
90225   ** wrapper around the sqlite3_last_insert_rowid() C/C++ interface
90226   ** function. */
90227   sqlite3_result_int64(context, sqlite3_last_insert_rowid(db));
90228 }
90229 
90230 /*
90231 ** Implementation of the changes() SQL function.
90232 **
90233 ** IMP: R-62073-11209 The changes() SQL function is a wrapper
90234 ** around the sqlite3_changes() C/C++ function and hence follows the same
90235 ** rules for counting changes.
90236 */
90237 static void changes(
90238   sqlite3_context *context,
90239   int NotUsed,
90240   sqlite3_value **NotUsed2
90241 ){
90242   sqlite3 *db = sqlite3_context_db_handle(context);
90243   UNUSED_PARAMETER2(NotUsed, NotUsed2);
90244   sqlite3_result_int(context, sqlite3_changes(db));
90245 }
90246 
90247 /*
90248 ** Implementation of the total_changes() SQL function.  The return value is
90249 ** the same as the sqlite3_total_changes() API function.
90250 */
90251 static void total_changes(
90252   sqlite3_context *context,
90253   int NotUsed,
90254   sqlite3_value **NotUsed2
90255 ){
90256   sqlite3 *db = sqlite3_context_db_handle(context);
90257   UNUSED_PARAMETER2(NotUsed, NotUsed2);
90258   /* IMP: R-52756-41993 This function is a wrapper around the
90259   ** sqlite3_total_changes() C/C++ interface. */
90260   sqlite3_result_int(context, sqlite3_total_changes(db));
90261 }
90262 
90263 /*
90264 ** A structure defining how to do GLOB-style comparisons.
90265 */
90266 struct compareInfo {
90267   u8 matchAll;
90268   u8 matchOne;
90269   u8 matchSet;
90270   u8 noCase;
90271 };
90272 
90273 /*
90274 ** For LIKE and GLOB matching on EBCDIC machines, assume that every
90275 ** character is exactly one byte in size.  Also, all characters are
90276 ** able to participate in upper-case-to-lower-case mappings in EBCDIC
90277 ** whereas only characters less than 0x80 do in ASCII.
90278 */
90279 #if defined(SQLITE_EBCDIC)
90280 # define sqlite3Utf8Read(A)    (*((*A)++))
90281 # define GlobUpperToLower(A)   A = sqlite3UpperToLower[A]
90282 #else
90283 # define GlobUpperToLower(A)   if( !((A)&~0x7f) ){ A = sqlite3UpperToLower[A]; }
90284 #endif
90285 
90286 static const struct compareInfo globInfo = { '*', '?', '[', 0 };
90287 /* The correct SQL-92 behavior is for the LIKE operator to ignore
90288 ** case.  Thus  'a' LIKE 'A' would be true. */
90289 static const struct compareInfo likeInfoNorm = { '%', '_',   0, 1 };
90290 /* If SQLITE_CASE_SENSITIVE_LIKE is defined, then the LIKE operator
90291 ** is case sensitive causing 'a' LIKE 'A' to be false */
90292 static const struct compareInfo likeInfoAlt = { '%', '_',   0, 0 };
90293 
90294 /*
90295 ** Compare two UTF-8 strings for equality where the first string can
90296 ** potentially be a "glob" expression.  Return true (1) if they
90297 ** are the same and false (0) if they are different.
90298 **
90299 ** Globbing rules:
90300 **
90301 **      '*'       Matches any sequence of zero or more characters.
90302 **
90303 **      '?'       Matches exactly one character.
90304 **
90305 **     [...]      Matches one character from the enclosed list of
90306 **                characters.
90307 **
90308 **     [^...]     Matches one character not in the enclosed list.
90309 **
90310 ** With the [...] and [^...] matching, a ']' character can be included
90311 ** in the list by making it the first character after '[' or '^'.  A
90312 ** range of characters can be specified using '-'.  Example:
90313 ** "[a-z]" matches any single lower-case letter.  To match a '-', make
90314 ** it the last character in the list.
90315 **
90316 ** This routine is usually quick, but can be N**2 in the worst case.
90317 **
90318 ** Hints: to match '*' or '?', put them in "[]".  Like this:
90319 **
90320 **         abc[*]xyz        Matches "abc*xyz" only
90321 */
90322 static int patternCompare(
90323   const u8 *zPattern,              /* The glob pattern */
90324   const u8 *zString,               /* The string to compare against the glob */
90325   const struct compareInfo *pInfo, /* Information about how to do the compare */
90326   u32 esc                          /* The escape character */
90327 ){
90328   u32 c, c2;
90329   int invert;
90330   int seen;
90331   u8 matchOne = pInfo->matchOne;
90332   u8 matchAll = pInfo->matchAll;
90333   u8 matchSet = pInfo->matchSet;
90334   u8 noCase = pInfo->noCase; 
90335   int prevEscape = 0;     /* True if the previous character was 'escape' */
90336 
90337   while( (c = sqlite3Utf8Read(&zPattern))!=0 ){
90338     if( c==matchAll && !prevEscape ){
90339       while( (c=sqlite3Utf8Read(&zPattern)) == matchAll
90340                || c == matchOne ){
90341         if( c==matchOne && sqlite3Utf8Read(&zString)==0 ){
90342           return 0;
90343         }
90344       }
90345       if( c==0 ){
90346         return 1;
90347       }else if( c==esc ){
90348         c = sqlite3Utf8Read(&zPattern);
90349         if( c==0 ){
90350           return 0;
90351         }
90352       }else if( c==matchSet ){
90353         assert( esc==0 );         /* This is GLOB, not LIKE */
90354         assert( matchSet<0x80 );  /* '[' is a single-byte character */
90355         while( *zString && patternCompare(&zPattern[-1],zString,pInfo,esc)==0 ){
90356           SQLITE_SKIP_UTF8(zString);
90357         }
90358         return *zString!=0;
90359       }
90360       while( (c2 = sqlite3Utf8Read(&zString))!=0 ){
90361         if( noCase ){
90362           GlobUpperToLower(c2);
90363           GlobUpperToLower(c);
90364           while( c2 != 0 && c2 != c ){
90365             c2 = sqlite3Utf8Read(&zString);
90366             GlobUpperToLower(c2);
90367           }
90368         }else{
90369           while( c2 != 0 && c2 != c ){
90370             c2 = sqlite3Utf8Read(&zString);
90371           }
90372         }
90373         if( c2==0 ) return 0;
90374         if( patternCompare(zPattern,zString,pInfo,esc) ) return 1;
90375       }
90376       return 0;
90377     }else if( c==matchOne && !prevEscape ){
90378       if( sqlite3Utf8Read(&zString)==0 ){
90379         return 0;
90380       }
90381     }else if( c==matchSet ){
90382       u32 prior_c = 0;
90383       assert( esc==0 );    /* This only occurs for GLOB, not LIKE */
90384       seen = 0;
90385       invert = 0;
90386       c = sqlite3Utf8Read(&zString);
90387       if( c==0 ) return 0;
90388       c2 = sqlite3Utf8Read(&zPattern);
90389       if( c2=='^' ){
90390         invert = 1;
90391         c2 = sqlite3Utf8Read(&zPattern);
90392       }
90393       if( c2==']' ){
90394         if( c==']' ) seen = 1;
90395         c2 = sqlite3Utf8Read(&zPattern);
90396       }
90397       while( c2 && c2!=']' ){
90398         if( c2=='-' && zPattern[0]!=']' && zPattern[0]!=0 && prior_c>0 ){
90399           c2 = sqlite3Utf8Read(&zPattern);
90400           if( c>=prior_c && c<=c2 ) seen = 1;
90401           prior_c = 0;
90402         }else{
90403           if( c==c2 ){
90404             seen = 1;
90405           }
90406           prior_c = c2;
90407         }
90408         c2 = sqlite3Utf8Read(&zPattern);
90409       }
90410       if( c2==0 || (seen ^ invert)==0 ){
90411         return 0;
90412       }
90413     }else if( esc==c && !prevEscape ){
90414       prevEscape = 1;
90415     }else{
90416       c2 = sqlite3Utf8Read(&zString);
90417       if( noCase ){
90418         GlobUpperToLower(c);
90419         GlobUpperToLower(c2);
90420       }
90421       if( c!=c2 ){
90422         return 0;
90423       }
90424       prevEscape = 0;
90425     }
90426   }
90427   return *zString==0;
90428 }
90429 
90430 /*
90431 ** The sqlite3_strglob() interface.
90432 */
90433 SQLITE_API int sqlite3_strglob(const char *zGlobPattern, const char *zString){
90434   return patternCompare((u8*)zGlobPattern, (u8*)zString, &globInfo, 0)==0;
90435 }
90436 
90437 /*
90438 ** Count the number of times that the LIKE operator (or GLOB which is
90439 ** just a variation of LIKE) gets called.  This is used for testing
90440 ** only.
90441 */
90442 #ifdef SQLITE_TEST
90443 SQLITE_API int sqlite3_like_count = 0;
90444 #endif
90445 
90446 
90447 /*
90448 ** Implementation of the like() SQL function.  This function implements
90449 ** the build-in LIKE operator.  The first argument to the function is the
90450 ** pattern and the second argument is the string.  So, the SQL statements:
90451 **
90452 **       A LIKE B
90453 **
90454 ** is implemented as like(B,A).
90455 **
90456 ** This same function (with a different compareInfo structure) computes
90457 ** the GLOB operator.
90458 */
90459 static void likeFunc(
90460   sqlite3_context *context, 
90461   int argc, 
90462   sqlite3_value **argv
90463 ){
90464   const unsigned char *zA, *zB;
90465   u32 escape = 0;
90466   int nPat;
90467   sqlite3 *db = sqlite3_context_db_handle(context);
90468 
90469   zB = sqlite3_value_text(argv[0]);
90470   zA = sqlite3_value_text(argv[1]);
90471 
90472   /* Limit the length of the LIKE or GLOB pattern to avoid problems
90473   ** of deep recursion and N*N behavior in patternCompare().
90474   */
90475   nPat = sqlite3_value_bytes(argv[0]);
90476   testcase( nPat==db->aLimit[SQLITE_LIMIT_LIKE_PATTERN_LENGTH] );
90477   testcase( nPat==db->aLimit[SQLITE_LIMIT_LIKE_PATTERN_LENGTH]+1 );
90478   if( nPat > db->aLimit[SQLITE_LIMIT_LIKE_PATTERN_LENGTH] ){
90479     sqlite3_result_error(context, "LIKE or GLOB pattern too complex", -1);
90480     return;
90481   }
90482   assert( zB==sqlite3_value_text(argv[0]) );  /* Encoding did not change */
90483 
90484   if( argc==3 ){
90485     /* The escape character string must consist of a single UTF-8 character.
90486     ** Otherwise, return an error.
90487     */
90488     const unsigned char *zEsc = sqlite3_value_text(argv[2]);
90489     if( zEsc==0 ) return;
90490     if( sqlite3Utf8CharLen((char*)zEsc, -1)!=1 ){
90491       sqlite3_result_error(context, 
90492           "ESCAPE expression must be a single character", -1);
90493       return;
90494     }
90495     escape = sqlite3Utf8Read(&zEsc);
90496   }
90497   if( zA && zB ){
90498     struct compareInfo *pInfo = sqlite3_user_data(context);
90499 #ifdef SQLITE_TEST
90500     sqlite3_like_count++;
90501 #endif
90502     
90503     sqlite3_result_int(context, patternCompare(zB, zA, pInfo, escape));
90504   }
90505 }
90506 
90507 /*
90508 ** Implementation of the NULLIF(x,y) function.  The result is the first
90509 ** argument if the arguments are different.  The result is NULL if the
90510 ** arguments are equal to each other.
90511 */
90512 static void nullifFunc(
90513   sqlite3_context *context,
90514   int NotUsed,
90515   sqlite3_value **argv
90516 ){
90517   CollSeq *pColl = sqlite3GetFuncCollSeq(context);
90518   UNUSED_PARAMETER(NotUsed);
90519   if( sqlite3MemCompare(argv[0], argv[1], pColl)!=0 ){
90520     sqlite3_result_value(context, argv[0]);
90521   }
90522 }
90523 
90524 /*
90525 ** Implementation of the sqlite_version() function.  The result is the version
90526 ** of the SQLite library that is running.
90527 */
90528 static void versionFunc(
90529   sqlite3_context *context,
90530   int NotUsed,
90531   sqlite3_value **NotUsed2
90532 ){
90533   UNUSED_PARAMETER2(NotUsed, NotUsed2);
90534   /* IMP: R-48699-48617 This function is an SQL wrapper around the
90535   ** sqlite3_libversion() C-interface. */
90536   sqlite3_result_text(context, sqlite3_libversion(), -1, SQLITE_STATIC);
90537 }
90538 
90539 /*
90540 ** Implementation of the sqlite_source_id() function. The result is a string
90541 ** that identifies the particular version of the source code used to build
90542 ** SQLite.
90543 */
90544 static void sourceidFunc(
90545   sqlite3_context *context,
90546   int NotUsed,
90547   sqlite3_value **NotUsed2
90548 ){
90549   UNUSED_PARAMETER2(NotUsed, NotUsed2);
90550   /* IMP: R-24470-31136 This function is an SQL wrapper around the
90551   ** sqlite3_sourceid() C interface. */
90552   sqlite3_result_text(context, sqlite3_sourceid(), -1, SQLITE_STATIC);
90553 }
90554 
90555 /*
90556 ** Implementation of the sqlite_log() function.  This is a wrapper around
90557 ** sqlite3_log().  The return value is NULL.  The function exists purely for
90558 ** its side-effects.
90559 */
90560 static void errlogFunc(
90561   sqlite3_context *context,
90562   int argc,
90563   sqlite3_value **argv
90564 ){
90565   UNUSED_PARAMETER(argc);
90566   UNUSED_PARAMETER(context);
90567   sqlite3_log(sqlite3_value_int(argv[0]), "%s", sqlite3_value_text(argv[1]));
90568 }
90569 
90570 /*
90571 ** Implementation of the sqlite_compileoption_used() function.
90572 ** The result is an integer that identifies if the compiler option
90573 ** was used to build SQLite.
90574 */
90575 #ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS
90576 static void compileoptionusedFunc(
90577   sqlite3_context *context,
90578   int argc,
90579   sqlite3_value **argv
90580 ){
90581   const char *zOptName;
90582   assert( argc==1 );
90583   UNUSED_PARAMETER(argc);
90584   /* IMP: R-39564-36305 The sqlite_compileoption_used() SQL
90585   ** function is a wrapper around the sqlite3_compileoption_used() C/C++
90586   ** function.
90587   */
90588   if( (zOptName = (const char*)sqlite3_value_text(argv[0]))!=0 ){
90589     sqlite3_result_int(context, sqlite3_compileoption_used(zOptName));
90590   }
90591 }
90592 #endif /* SQLITE_OMIT_COMPILEOPTION_DIAGS */
90593 
90594 /*
90595 ** Implementation of the sqlite_compileoption_get() function. 
90596 ** The result is a string that identifies the compiler options 
90597 ** used to build SQLite.
90598 */
90599 #ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS
90600 static void compileoptiongetFunc(
90601   sqlite3_context *context,
90602   int argc,
90603   sqlite3_value **argv
90604 ){
90605   int n;
90606   assert( argc==1 );
90607   UNUSED_PARAMETER(argc);
90608   /* IMP: R-04922-24076 The sqlite_compileoption_get() SQL function
90609   ** is a wrapper around the sqlite3_compileoption_get() C/C++ function.
90610   */
90611   n = sqlite3_value_int(argv[0]);
90612   sqlite3_result_text(context, sqlite3_compileoption_get(n), -1, SQLITE_STATIC);
90613 }
90614 #endif /* SQLITE_OMIT_COMPILEOPTION_DIAGS */
90615 
90616 /* Array for converting from half-bytes (nybbles) into ASCII hex
90617 ** digits. */
90618 static const char hexdigits[] = {
90619   '0', '1', '2', '3', '4', '5', '6', '7',
90620   '8', '9', 'A', 'B', 'C', 'D', 'E', 'F' 
90621 };
90622 
90623 /*
90624 ** Implementation of the QUOTE() function.  This function takes a single
90625 ** argument.  If the argument is numeric, the return value is the same as
90626 ** the argument.  If the argument is NULL, the return value is the string
90627 ** "NULL".  Otherwise, the argument is enclosed in single quotes with
90628 ** single-quote escapes.
90629 */
90630 static void quoteFunc(sqlite3_context *context, int argc, sqlite3_value **argv){
90631   assert( argc==1 );
90632   UNUSED_PARAMETER(argc);
90633   switch( sqlite3_value_type(argv[0]) ){
90634     case SQLITE_FLOAT: {
90635       double r1, r2;
90636       char zBuf[50];
90637       r1 = sqlite3_value_double(argv[0]);
90638       sqlite3_snprintf(sizeof(zBuf), zBuf, "%!.15g", r1);
90639       sqlite3AtoF(zBuf, &r2, 20, SQLITE_UTF8);
90640       if( r1!=r2 ){
90641         sqlite3_snprintf(sizeof(zBuf), zBuf, "%!.20e", r1);
90642       }
90643       sqlite3_result_text(context, zBuf, -1, SQLITE_TRANSIENT);
90644       break;
90645     }
90646     case SQLITE_INTEGER: {
90647       sqlite3_result_value(context, argv[0]);
90648       break;
90649     }
90650     case SQLITE_BLOB: {
90651       char *zText = 0;
90652       char const *zBlob = sqlite3_value_blob(argv[0]);
90653       int nBlob = sqlite3_value_bytes(argv[0]);
90654       assert( zBlob==sqlite3_value_blob(argv[0]) ); /* No encoding change */
90655       zText = (char *)contextMalloc(context, (2*(i64)nBlob)+4); 
90656       if( zText ){
90657         int i;
90658         for(i=0; i<nBlob; i++){
90659           zText[(i*2)+2] = hexdigits[(zBlob[i]>>4)&0x0F];
90660           zText[(i*2)+3] = hexdigits[(zBlob[i])&0x0F];
90661         }
90662         zText[(nBlob*2)+2] = '\'';
90663         zText[(nBlob*2)+3] = '\0';
90664         zText[0] = 'X';
90665         zText[1] = '\'';
90666         sqlite3_result_text(context, zText, -1, SQLITE_TRANSIENT);
90667         sqlite3_free(zText);
90668       }
90669       break;
90670     }
90671     case SQLITE_TEXT: {
90672       int i,j;
90673       u64 n;
90674       const unsigned char *zArg = sqlite3_value_text(argv[0]);
90675       char *z;
90676 
90677       if( zArg==0 ) return;
90678       for(i=0, n=0; zArg[i]; i++){ if( zArg[i]=='\'' ) n++; }
90679       z = contextMalloc(context, ((i64)i)+((i64)n)+3);
90680       if( z ){
90681         z[0] = '\'';
90682         for(i=0, j=1; zArg[i]; i++){
90683           z[j++] = zArg[i];
90684           if( zArg[i]=='\'' ){
90685             z[j++] = '\'';
90686           }
90687         }
90688         z[j++] = '\'';
90689         z[j] = 0;
90690         sqlite3_result_text(context, z, j, sqlite3_free);
90691       }
90692       break;
90693     }
90694     default: {
90695       assert( sqlite3_value_type(argv[0])==SQLITE_NULL );
90696       sqlite3_result_text(context, "NULL", 4, SQLITE_STATIC);
90697       break;
90698     }
90699   }
90700 }
90701 
90702 /*
90703 ** The unicode() function.  Return the integer unicode code-point value
90704 ** for the first character of the input string. 
90705 */
90706 static void unicodeFunc(
90707   sqlite3_context *context,
90708   int argc,
90709   sqlite3_value **argv
90710 ){
90711   const unsigned char *z = sqlite3_value_text(argv[0]);
90712   (void)argc;
90713   if( z && z[0] ) sqlite3_result_int(context, sqlite3Utf8Read(&z));
90714 }
90715 
90716 /*
90717 ** The char() function takes zero or more arguments, each of which is
90718 ** an integer.  It constructs a string where each character of the string
90719 ** is the unicode character for the corresponding integer argument.
90720 */
90721 static void charFunc(
90722   sqlite3_context *context,
90723   int argc,
90724   sqlite3_value **argv
90725 ){
90726   unsigned char *z, *zOut;
90727   int i;
90728   zOut = z = sqlite3_malloc( argc*4 );
90729   if( z==0 ){
90730     sqlite3_result_error_nomem(context);
90731     return;
90732   }
90733   for(i=0; i<argc; i++){
90734     sqlite3_int64 x;
90735     unsigned c;
90736     x = sqlite3_value_int64(argv[i]);
90737     if( x<0 || x>0x10ffff ) x = 0xfffd;
90738     c = (unsigned)(x & 0x1fffff);
90739     if( c<0x00080 ){
90740       *zOut++ = (u8)(c&0xFF);
90741     }else if( c<0x00800 ){
90742       *zOut++ = 0xC0 + (u8)((c>>6)&0x1F);
90743       *zOut++ = 0x80 + (u8)(c & 0x3F);
90744     }else if( c<0x10000 ){
90745       *zOut++ = 0xE0 + (u8)((c>>12)&0x0F);
90746       *zOut++ = 0x80 + (u8)((c>>6) & 0x3F);
90747       *zOut++ = 0x80 + (u8)(c & 0x3F);
90748     }else{
90749       *zOut++ = 0xF0 + (u8)((c>>18) & 0x07);
90750       *zOut++ = 0x80 + (u8)((c>>12) & 0x3F);
90751       *zOut++ = 0x80 + (u8)((c>>6) & 0x3F);
90752       *zOut++ = 0x80 + (u8)(c & 0x3F);
90753     }                                                    \
90754   }
90755   sqlite3_result_text(context, (char*)z, (int)(zOut-z), sqlite3_free);
90756 }
90757 
90758 /*
90759 ** The hex() function.  Interpret the argument as a blob.  Return
90760 ** a hexadecimal rendering as text.
90761 */
90762 static void hexFunc(
90763   sqlite3_context *context,
90764   int argc,
90765   sqlite3_value **argv
90766 ){
90767   int i, n;
90768   const unsigned char *pBlob;
90769   char *zHex, *z;
90770   assert( argc==1 );
90771   UNUSED_PARAMETER(argc);
90772   pBlob = sqlite3_value_blob(argv[0]);
90773   n = sqlite3_value_bytes(argv[0]);
90774   assert( pBlob==sqlite3_value_blob(argv[0]) );  /* No encoding change */
90775   z = zHex = contextMalloc(context, ((i64)n)*2 + 1);
90776   if( zHex ){
90777     for(i=0; i<n; i++, pBlob++){
90778       unsigned char c = *pBlob;
90779       *(z++) = hexdigits[(c>>4)&0xf];
90780       *(z++) = hexdigits[c&0xf];
90781     }
90782     *z = 0;
90783     sqlite3_result_text(context, zHex, n*2, sqlite3_free);
90784   }
90785 }
90786 
90787 /*
90788 ** The zeroblob(N) function returns a zero-filled blob of size N bytes.
90789 */
90790 static void zeroblobFunc(
90791   sqlite3_context *context,
90792   int argc,
90793   sqlite3_value **argv
90794 ){
90795   i64 n;
90796   sqlite3 *db = sqlite3_context_db_handle(context);
90797   assert( argc==1 );
90798   UNUSED_PARAMETER(argc);
90799   n = sqlite3_value_int64(argv[0]);
90800   testcase( n==db->aLimit[SQLITE_LIMIT_LENGTH] );
90801   testcase( n==db->aLimit[SQLITE_LIMIT_LENGTH]+1 );
90802   if( n>db->aLimit[SQLITE_LIMIT_LENGTH] ){
90803     sqlite3_result_error_toobig(context);
90804   }else{
90805     sqlite3_result_zeroblob(context, (int)n); /* IMP: R-00293-64994 */
90806   }
90807 }
90808 
90809 /*
90810 ** The replace() function.  Three arguments are all strings: call
90811 ** them A, B, and C. The result is also a string which is derived
90812 ** from A by replacing every occurrence of B with C.  The match
90813 ** must be exact.  Collating sequences are not used.
90814 */
90815 static void replaceFunc(
90816   sqlite3_context *context,
90817   int argc,
90818   sqlite3_value **argv
90819 ){
90820   const unsigned char *zStr;        /* The input string A */
90821   const unsigned char *zPattern;    /* The pattern string B */
90822   const unsigned char *zRep;        /* The replacement string C */
90823   unsigned char *zOut;              /* The output */
90824   int nStr;                /* Size of zStr */
90825   int nPattern;            /* Size of zPattern */
90826   int nRep;                /* Size of zRep */
90827   i64 nOut;                /* Maximum size of zOut */
90828   int loopLimit;           /* Last zStr[] that might match zPattern[] */
90829   int i, j;                /* Loop counters */
90830 
90831   assert( argc==3 );
90832   UNUSED_PARAMETER(argc);
90833   zStr = sqlite3_value_text(argv[0]);
90834   if( zStr==0 ) return;
90835   nStr = sqlite3_value_bytes(argv[0]);
90836   assert( zStr==sqlite3_value_text(argv[0]) );  /* No encoding change */
90837   zPattern = sqlite3_value_text(argv[1]);
90838   if( zPattern==0 ){
90839     assert( sqlite3_value_type(argv[1])==SQLITE_NULL
90840             || sqlite3_context_db_handle(context)->mallocFailed );
90841     return;
90842   }
90843   if( zPattern[0]==0 ){
90844     assert( sqlite3_value_type(argv[1])!=SQLITE_NULL );
90845     sqlite3_result_value(context, argv[0]);
90846     return;
90847   }
90848   nPattern = sqlite3_value_bytes(argv[1]);
90849   assert( zPattern==sqlite3_value_text(argv[1]) );  /* No encoding change */
90850   zRep = sqlite3_value_text(argv[2]);
90851   if( zRep==0 ) return;
90852   nRep = sqlite3_value_bytes(argv[2]);
90853   assert( zRep==sqlite3_value_text(argv[2]) );
90854   nOut = nStr + 1;
90855   assert( nOut<SQLITE_MAX_LENGTH );
90856   zOut = contextMalloc(context, (i64)nOut);
90857   if( zOut==0 ){
90858     return;
90859   }
90860   loopLimit = nStr - nPattern;  
90861   for(i=j=0; i<=loopLimit; i++){
90862     if( zStr[i]!=zPattern[0] || memcmp(&zStr[i], zPattern, nPattern) ){
90863       zOut[j++] = zStr[i];
90864     }else{
90865       u8 *zOld;
90866       sqlite3 *db = sqlite3_context_db_handle(context);
90867       nOut += nRep - nPattern;
90868       testcase( nOut-1==db->aLimit[SQLITE_LIMIT_LENGTH] );
90869       testcase( nOut-2==db->aLimit[SQLITE_LIMIT_LENGTH] );
90870       if( nOut-1>db->aLimit[SQLITE_LIMIT_LENGTH] ){
90871         sqlite3_result_error_toobig(context);
90872         sqlite3_free(zOut);
90873         return;
90874       }
90875       zOld = zOut;
90876       zOut = sqlite3_realloc(zOut, (int)nOut);
90877       if( zOut==0 ){
90878         sqlite3_result_error_nomem(context);
90879         sqlite3_free(zOld);
90880         return;
90881       }
90882       memcpy(&zOut[j], zRep, nRep);
90883       j += nRep;
90884       i += nPattern-1;
90885     }
90886   }
90887   assert( j+nStr-i+1==nOut );
90888   memcpy(&zOut[j], &zStr[i], nStr-i);
90889   j += nStr - i;
90890   assert( j<=nOut );
90891   zOut[j] = 0;
90892   sqlite3_result_text(context, (char*)zOut, j, sqlite3_free);
90893 }
90894 
90895 /*
90896 ** Implementation of the TRIM(), LTRIM(), and RTRIM() functions.
90897 ** The userdata is 0x1 for left trim, 0x2 for right trim, 0x3 for both.
90898 */
90899 static void trimFunc(
90900   sqlite3_context *context,
90901   int argc,
90902   sqlite3_value **argv
90903 ){
90904   const unsigned char *zIn;         /* Input string */
90905   const unsigned char *zCharSet;    /* Set of characters to trim */
90906   int nIn;                          /* Number of bytes in input */
90907   int flags;                        /* 1: trimleft  2: trimright  3: trim */
90908   int i;                            /* Loop counter */
90909   unsigned char *aLen = 0;          /* Length of each character in zCharSet */
90910   unsigned char **azChar = 0;       /* Individual characters in zCharSet */
90911   int nChar;                        /* Number of characters in zCharSet */
90912 
90913   if( sqlite3_value_type(argv[0])==SQLITE_NULL ){
90914     return;
90915   }
90916   zIn = sqlite3_value_text(argv[0]);
90917   if( zIn==0 ) return;
90918   nIn = sqlite3_value_bytes(argv[0]);
90919   assert( zIn==sqlite3_value_text(argv[0]) );
90920   if( argc==1 ){
90921     static const unsigned char lenOne[] = { 1 };
90922     static unsigned char * const azOne[] = { (u8*)" " };
90923     nChar = 1;
90924     aLen = (u8*)lenOne;
90925     azChar = (unsigned char **)azOne;
90926     zCharSet = 0;
90927   }else if( (zCharSet = sqlite3_value_text(argv[1]))==0 ){
90928     return;
90929   }else{
90930     const unsigned char *z;
90931     for(z=zCharSet, nChar=0; *z; nChar++){
90932       SQLITE_SKIP_UTF8(z);
90933     }
90934     if( nChar>0 ){
90935       azChar = contextMalloc(context, ((i64)nChar)*(sizeof(char*)+1));
90936       if( azChar==0 ){
90937         return;
90938       }
90939       aLen = (unsigned char*)&azChar[nChar];
90940       for(z=zCharSet, nChar=0; *z; nChar++){
90941         azChar[nChar] = (unsigned char *)z;
90942         SQLITE_SKIP_UTF8(z);
90943         aLen[nChar] = (u8)(z - azChar[nChar]);
90944       }
90945     }
90946   }
90947   if( nChar>0 ){
90948     flags = SQLITE_PTR_TO_INT(sqlite3_user_data(context));
90949     if( flags & 1 ){
90950       while( nIn>0 ){
90951         int len = 0;
90952         for(i=0; i<nChar; i++){
90953           len = aLen[i];
90954           if( len<=nIn && memcmp(zIn, azChar[i], len)==0 ) break;
90955         }
90956         if( i>=nChar ) break;
90957         zIn += len;
90958         nIn -= len;
90959       }
90960     }
90961     if( flags & 2 ){
90962       while( nIn>0 ){
90963         int len = 0;
90964         for(i=0; i<nChar; i++){
90965           len = aLen[i];
90966           if( len<=nIn && memcmp(&zIn[nIn-len],azChar[i],len)==0 ) break;
90967         }
90968         if( i>=nChar ) break;
90969         nIn -= len;
90970       }
90971     }
90972     if( zCharSet ){
90973       sqlite3_free(azChar);
90974     }
90975   }
90976   sqlite3_result_text(context, (char*)zIn, nIn, SQLITE_TRANSIENT);
90977 }
90978 
90979 
90980 /* IMP: R-25361-16150 This function is omitted from SQLite by default. It
90981 ** is only available if the SQLITE_SOUNDEX compile-time option is used
90982 ** when SQLite is built.
90983 */
90984 #ifdef SQLITE_SOUNDEX
90985 /*
90986 ** Compute the soundex encoding of a word.
90987 **
90988 ** IMP: R-59782-00072 The soundex(X) function returns a string that is the
90989 ** soundex encoding of the string X. 
90990 */
90991 static void soundexFunc(
90992   sqlite3_context *context,
90993   int argc,
90994   sqlite3_value **argv
90995 ){
90996   char zResult[8];
90997   const u8 *zIn;
90998   int i, j;
90999   static const unsigned char iCode[] = {
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, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
91004     0, 0, 1, 2, 3, 0, 1, 2, 0, 0, 2, 2, 4, 5, 5, 0,
91005     1, 2, 6, 2, 3, 0, 1, 0, 2, 0, 2, 0, 0, 0, 0, 0,
91006     0, 0, 1, 2, 3, 0, 1, 2, 0, 0, 2, 2, 4, 5, 5, 0,
91007     1, 2, 6, 2, 3, 0, 1, 0, 2, 0, 2, 0, 0, 0, 0, 0,
91008   };
91009   assert( argc==1 );
91010   zIn = (u8*)sqlite3_value_text(argv[0]);
91011   if( zIn==0 ) zIn = (u8*)"";
91012   for(i=0; zIn[i] && !sqlite3Isalpha(zIn[i]); i++){}
91013   if( zIn[i] ){
91014     u8 prevcode = iCode[zIn[i]&0x7f];
91015     zResult[0] = sqlite3Toupper(zIn[i]);
91016     for(j=1; j<4 && zIn[i]; i++){
91017       int code = iCode[zIn[i]&0x7f];
91018       if( code>0 ){
91019         if( code!=prevcode ){
91020           prevcode = code;
91021           zResult[j++] = code + '0';
91022         }
91023       }else{
91024         prevcode = 0;
91025       }
91026     }
91027     while( j<4 ){
91028       zResult[j++] = '0';
91029     }
91030     zResult[j] = 0;
91031     sqlite3_result_text(context, zResult, 4, SQLITE_TRANSIENT);
91032   }else{
91033     /* IMP: R-64894-50321 The string "?000" is returned if the argument
91034     ** is NULL or contains no ASCII alphabetic characters. */
91035     sqlite3_result_text(context, "?000", 4, SQLITE_STATIC);
91036   }
91037 }
91038 #endif /* SQLITE_SOUNDEX */
91039 
91040 #ifndef SQLITE_OMIT_LOAD_EXTENSION
91041 /*
91042 ** A function that loads a shared-library extension then returns NULL.
91043 */
91044 static void loadExt(sqlite3_context *context, int argc, sqlite3_value **argv){
91045   const char *zFile = (const char *)sqlite3_value_text(argv[0]);
91046   const char *zProc;
91047   sqlite3 *db = sqlite3_context_db_handle(context);
91048   char *zErrMsg = 0;
91049 
91050   if( argc==2 ){
91051     zProc = (const char *)sqlite3_value_text(argv[1]);
91052   }else{
91053     zProc = 0;
91054   }
91055   if( zFile && sqlite3_load_extension(db, zFile, zProc, &zErrMsg) ){
91056     sqlite3_result_error(context, zErrMsg, -1);
91057     sqlite3_free(zErrMsg);
91058   }
91059 }
91060 #endif
91061 
91062 
91063 /*
91064 ** An instance of the following structure holds the context of a
91065 ** sum() or avg() aggregate computation.
91066 */
91067 typedef struct SumCtx SumCtx;
91068 struct SumCtx {
91069   double rSum;      /* Floating point sum */
91070   i64 iSum;         /* Integer sum */   
91071   i64 cnt;          /* Number of elements summed */
91072   u8 overflow;      /* True if integer overflow seen */
91073   u8 approx;        /* True if non-integer value was input to the sum */
91074 };
91075 
91076 /*
91077 ** Routines used to compute the sum, average, and total.
91078 **
91079 ** The SUM() function follows the (broken) SQL standard which means
91080 ** that it returns NULL if it sums over no inputs.  TOTAL returns
91081 ** 0.0 in that case.  In addition, TOTAL always returns a float where
91082 ** SUM might return an integer if it never encounters a floating point
91083 ** value.  TOTAL never fails, but SUM might through an exception if
91084 ** it overflows an integer.
91085 */
91086 static void sumStep(sqlite3_context *context, int argc, sqlite3_value **argv){
91087   SumCtx *p;
91088   int type;
91089   assert( argc==1 );
91090   UNUSED_PARAMETER(argc);
91091   p = sqlite3_aggregate_context(context, sizeof(*p));
91092   type = sqlite3_value_numeric_type(argv[0]);
91093   if( p && type!=SQLITE_NULL ){
91094     p->cnt++;
91095     if( type==SQLITE_INTEGER ){
91096       i64 v = sqlite3_value_int64(argv[0]);
91097       p->rSum += v;
91098       if( (p->approx|p->overflow)==0 && sqlite3AddInt64(&p->iSum, v) ){
91099         p->overflow = 1;
91100       }
91101     }else{
91102       p->rSum += sqlite3_value_double(argv[0]);
91103       p->approx = 1;
91104     }
91105   }
91106 }
91107 static void sumFinalize(sqlite3_context *context){
91108   SumCtx *p;
91109   p = sqlite3_aggregate_context(context, 0);
91110   if( p && p->cnt>0 ){
91111     if( p->overflow ){
91112       sqlite3_result_error(context,"integer overflow",-1);
91113     }else if( p->approx ){
91114       sqlite3_result_double(context, p->rSum);
91115     }else{
91116       sqlite3_result_int64(context, p->iSum);
91117     }
91118   }
91119 }
91120 static void avgFinalize(sqlite3_context *context){
91121   SumCtx *p;
91122   p = sqlite3_aggregate_context(context, 0);
91123   if( p && p->cnt>0 ){
91124     sqlite3_result_double(context, p->rSum/(double)p->cnt);
91125   }
91126 }
91127 static void totalFinalize(sqlite3_context *context){
91128   SumCtx *p;
91129   p = sqlite3_aggregate_context(context, 0);
91130   /* (double)0 In case of SQLITE_OMIT_FLOATING_POINT... */
91131   sqlite3_result_double(context, p ? p->rSum : (double)0);
91132 }
91133 
91134 /*
91135 ** The following structure keeps track of state information for the
91136 ** count() aggregate function.
91137 */
91138 typedef struct CountCtx CountCtx;
91139 struct CountCtx {
91140   i64 n;
91141 };
91142 
91143 /*
91144 ** Routines to implement the count() aggregate function.
91145 */
91146 static void countStep(sqlite3_context *context, int argc, sqlite3_value **argv){
91147   CountCtx *p;
91148   p = sqlite3_aggregate_context(context, sizeof(*p));
91149   if( (argc==0 || SQLITE_NULL!=sqlite3_value_type(argv[0])) && p ){
91150     p->n++;
91151   }
91152 
91153 #ifndef SQLITE_OMIT_DEPRECATED
91154   /* The sqlite3_aggregate_count() function is deprecated.  But just to make
91155   ** sure it still operates correctly, verify that its count agrees with our 
91156   ** internal count when using count(*) and when the total count can be
91157   ** expressed as a 32-bit integer. */
91158   assert( argc==1 || p==0 || p->n>0x7fffffff
91159           || p->n==sqlite3_aggregate_count(context) );
91160 #endif
91161 }   
91162 static void countFinalize(sqlite3_context *context){
91163   CountCtx *p;
91164   p = sqlite3_aggregate_context(context, 0);
91165   sqlite3_result_int64(context, p ? p->n : 0);
91166 }
91167 
91168 /*
91169 ** Routines to implement min() and max() aggregate functions.
91170 */
91171 static void minmaxStep(
91172   sqlite3_context *context, 
91173   int NotUsed, 
91174   sqlite3_value **argv
91175 ){
91176   Mem *pArg  = (Mem *)argv[0];
91177   Mem *pBest;
91178   UNUSED_PARAMETER(NotUsed);
91179 
91180   pBest = (Mem *)sqlite3_aggregate_context(context, sizeof(*pBest));
91181   if( !pBest ) return;
91182 
91183   if( sqlite3_value_type(argv[0])==SQLITE_NULL ){
91184     if( pBest->flags ) sqlite3SkipAccumulatorLoad(context);
91185   }else if( pBest->flags ){
91186     int max;
91187     int cmp;
91188     CollSeq *pColl = sqlite3GetFuncCollSeq(context);
91189     /* This step function is used for both the min() and max() aggregates,
91190     ** the only difference between the two being that the sense of the
91191     ** comparison is inverted. For the max() aggregate, the
91192     ** sqlite3_user_data() function returns (void *)-1. For min() it
91193     ** returns (void *)db, where db is the sqlite3* database pointer.
91194     ** Therefore the next statement sets variable 'max' to 1 for the max()
91195     ** aggregate, or 0 for min().
91196     */
91197     max = sqlite3_user_data(context)!=0;
91198     cmp = sqlite3MemCompare(pBest, pArg, pColl);
91199     if( (max && cmp<0) || (!max && cmp>0) ){
91200       sqlite3VdbeMemCopy(pBest, pArg);
91201     }else{
91202       sqlite3SkipAccumulatorLoad(context);
91203     }
91204   }else{
91205     sqlite3VdbeMemCopy(pBest, pArg);
91206   }
91207 }
91208 static void minMaxFinalize(sqlite3_context *context){
91209   sqlite3_value *pRes;
91210   pRes = (sqlite3_value *)sqlite3_aggregate_context(context, 0);
91211   if( pRes ){
91212     if( pRes->flags ){
91213       sqlite3_result_value(context, pRes);
91214     }
91215     sqlite3VdbeMemRelease(pRes);
91216   }
91217 }
91218 
91219 /*
91220 ** group_concat(EXPR, ?SEPARATOR?)
91221 */
91222 static void groupConcatStep(
91223   sqlite3_context *context,
91224   int argc,
91225   sqlite3_value **argv
91226 ){
91227   const char *zVal;
91228   StrAccum *pAccum;
91229   const char *zSep;
91230   int nVal, nSep;
91231   assert( argc==1 || argc==2 );
91232   if( sqlite3_value_type(argv[0])==SQLITE_NULL ) return;
91233   pAccum = (StrAccum*)sqlite3_aggregate_context(context, sizeof(*pAccum));
91234 
91235   if( pAccum ){
91236     sqlite3 *db = sqlite3_context_db_handle(context);
91237     int firstTerm = pAccum->useMalloc==0;
91238     pAccum->useMalloc = 2;
91239     pAccum->mxAlloc = db->aLimit[SQLITE_LIMIT_LENGTH];
91240     if( !firstTerm ){
91241       if( argc==2 ){
91242         zSep = (char*)sqlite3_value_text(argv[1]);
91243         nSep = sqlite3_value_bytes(argv[1]);
91244       }else{
91245         zSep = ",";
91246         nSep = 1;
91247       }
91248       sqlite3StrAccumAppend(pAccum, zSep, nSep);
91249     }
91250     zVal = (char*)sqlite3_value_text(argv[0]);
91251     nVal = sqlite3_value_bytes(argv[0]);
91252     sqlite3StrAccumAppend(pAccum, zVal, nVal);
91253   }
91254 }
91255 static void groupConcatFinalize(sqlite3_context *context){
91256   StrAccum *pAccum;
91257   pAccum = sqlite3_aggregate_context(context, 0);
91258   if( pAccum ){
91259     if( pAccum->accError==STRACCUM_TOOBIG ){
91260       sqlite3_result_error_toobig(context);
91261     }else if( pAccum->accError==STRACCUM_NOMEM ){
91262       sqlite3_result_error_nomem(context);
91263     }else{    
91264       sqlite3_result_text(context, sqlite3StrAccumFinish(pAccum), -1, 
91265                           sqlite3_free);
91266     }
91267   }
91268 }
91269 
91270 /*
91271 ** This routine does per-connection function registration.  Most
91272 ** of the built-in functions above are part of the global function set.
91273 ** This routine only deals with those that are not global.
91274 */
91275 SQLITE_PRIVATE void sqlite3RegisterBuiltinFunctions(sqlite3 *db){
91276   int rc = sqlite3_overload_function(db, "MATCH", 2);
91277   assert( rc==SQLITE_NOMEM || rc==SQLITE_OK );
91278   if( rc==SQLITE_NOMEM ){
91279     db->mallocFailed = 1;
91280   }
91281 }
91282 
91283 /*
91284 ** Set the LIKEOPT flag on the 2-argument function with the given name.
91285 */
91286 static void setLikeOptFlag(sqlite3 *db, const char *zName, u8 flagVal){
91287   FuncDef *pDef;
91288   pDef = sqlite3FindFunction(db, zName, sqlite3Strlen30(zName),
91289                              2, SQLITE_UTF8, 0);
91290   if( ALWAYS(pDef) ){
91291     pDef->funcFlags |= flagVal;
91292   }
91293 }
91294 
91295 /*
91296 ** Register the built-in LIKE and GLOB functions.  The caseSensitive
91297 ** parameter determines whether or not the LIKE operator is case
91298 ** sensitive.  GLOB is always case sensitive.
91299 */
91300 SQLITE_PRIVATE void sqlite3RegisterLikeFunctions(sqlite3 *db, int caseSensitive){
91301   struct compareInfo *pInfo;
91302   if( caseSensitive ){
91303     pInfo = (struct compareInfo*)&likeInfoAlt;
91304   }else{
91305     pInfo = (struct compareInfo*)&likeInfoNorm;
91306   }
91307   sqlite3CreateFunc(db, "like", 2, SQLITE_UTF8, pInfo, likeFunc, 0, 0, 0);
91308   sqlite3CreateFunc(db, "like", 3, SQLITE_UTF8, pInfo, likeFunc, 0, 0, 0);
91309   sqlite3CreateFunc(db, "glob", 2, SQLITE_UTF8, 
91310       (struct compareInfo*)&globInfo, likeFunc, 0, 0, 0);
91311   setLikeOptFlag(db, "glob", SQLITE_FUNC_LIKE | SQLITE_FUNC_CASE);
91312   setLikeOptFlag(db, "like", 
91313       caseSensitive ? (SQLITE_FUNC_LIKE | SQLITE_FUNC_CASE) : SQLITE_FUNC_LIKE);
91314 }
91315 
91316 /*
91317 ** pExpr points to an expression which implements a function.  If
91318 ** it is appropriate to apply the LIKE optimization to that function
91319 ** then set aWc[0] through aWc[2] to the wildcard characters and
91320 ** return TRUE.  If the function is not a LIKE-style function then
91321 ** return FALSE.
91322 */
91323 SQLITE_PRIVATE int sqlite3IsLikeFunction(sqlite3 *db, Expr *pExpr, int *pIsNocase, char *aWc){
91324   FuncDef *pDef;
91325   if( pExpr->op!=TK_FUNCTION 
91326    || !pExpr->x.pList 
91327    || pExpr->x.pList->nExpr!=2
91328   ){
91329     return 0;
91330   }
91331   assert( !ExprHasProperty(pExpr, EP_xIsSelect) );
91332   pDef = sqlite3FindFunction(db, pExpr->u.zToken, 
91333                              sqlite3Strlen30(pExpr->u.zToken),
91334                              2, SQLITE_UTF8, 0);
91335   if( NEVER(pDef==0) || (pDef->funcFlags & SQLITE_FUNC_LIKE)==0 ){
91336     return 0;
91337   }
91338 
91339   /* The memcpy() statement assumes that the wildcard characters are
91340   ** the first three statements in the compareInfo structure.  The
91341   ** asserts() that follow verify that assumption
91342   */
91343   memcpy(aWc, pDef->pUserData, 3);
91344   assert( (char*)&likeInfoAlt == (char*)&likeInfoAlt.matchAll );
91345   assert( &((char*)&likeInfoAlt)[1] == (char*)&likeInfoAlt.matchOne );
91346   assert( &((char*)&likeInfoAlt)[2] == (char*)&likeInfoAlt.matchSet );
91347   *pIsNocase = (pDef->funcFlags & SQLITE_FUNC_CASE)==0;
91348   return 1;
91349 }
91350 
91351 /*
91352 ** All all of the FuncDef structures in the aBuiltinFunc[] array above
91353 ** to the global function hash table.  This occurs at start-time (as
91354 ** a consequence of calling sqlite3_initialize()).
91355 **
91356 ** After this routine runs
91357 */
91358 SQLITE_PRIVATE void sqlite3RegisterGlobalFunctions(void){
91359   /*
91360   ** The following array holds FuncDef structures for all of the functions
91361   ** defined in this file.
91362   **
91363   ** The array cannot be constant since changes are made to the
91364   ** FuncDef.pHash elements at start-time.  The elements of this array
91365   ** are read-only after initialization is complete.
91366   */
91367   static SQLITE_WSD FuncDef aBuiltinFunc[] = {
91368     FUNCTION(ltrim,              1, 1, 0, trimFunc         ),
91369     FUNCTION(ltrim,              2, 1, 0, trimFunc         ),
91370     FUNCTION(rtrim,              1, 2, 0, trimFunc         ),
91371     FUNCTION(rtrim,              2, 2, 0, trimFunc         ),
91372     FUNCTION(trim,               1, 3, 0, trimFunc         ),
91373     FUNCTION(trim,               2, 3, 0, trimFunc         ),
91374     FUNCTION(min,               -1, 0, 1, minmaxFunc       ),
91375     FUNCTION(min,                0, 0, 1, 0                ),
91376     AGGREGATE(min,               1, 0, 1, minmaxStep,      minMaxFinalize ),
91377     FUNCTION(max,               -1, 1, 1, minmaxFunc       ),
91378     FUNCTION(max,                0, 1, 1, 0                ),
91379     AGGREGATE(max,               1, 1, 1, minmaxStep,      minMaxFinalize ),
91380     FUNCTION2(typeof,            1, 0, 0, typeofFunc,  SQLITE_FUNC_TYPEOF),
91381     FUNCTION2(length,            1, 0, 0, lengthFunc,  SQLITE_FUNC_LENGTH),
91382     FUNCTION(instr,              2, 0, 0, instrFunc        ),
91383     FUNCTION(substr,             2, 0, 0, substrFunc       ),
91384     FUNCTION(substr,             3, 0, 0, substrFunc       ),
91385     FUNCTION(unicode,            1, 0, 0, unicodeFunc      ),
91386     FUNCTION(char,              -1, 0, 0, charFunc         ),
91387     FUNCTION(abs,                1, 0, 0, absFunc          ),
91388 #ifndef SQLITE_OMIT_FLOATING_POINT
91389     FUNCTION(round,              1, 0, 0, roundFunc        ),
91390     FUNCTION(round,              2, 0, 0, roundFunc        ),
91391 #endif
91392     FUNCTION(upper,              1, 0, 0, upperFunc        ),
91393     FUNCTION(lower,              1, 0, 0, lowerFunc        ),
91394     FUNCTION(coalesce,           1, 0, 0, 0                ),
91395     FUNCTION(coalesce,           0, 0, 0, 0                ),
91396     FUNCTION2(coalesce,         -1, 0, 0, noopFunc,  SQLITE_FUNC_COALESCE),
91397     FUNCTION(hex,                1, 0, 0, hexFunc          ),
91398     FUNCTION2(ifnull,            2, 0, 0, noopFunc,  SQLITE_FUNC_COALESCE),
91399     FUNCTION2(unlikely,          1, 0, 0, noopFunc,  SQLITE_FUNC_UNLIKELY),
91400     FUNCTION2(likelihood,        2, 0, 0, noopFunc,  SQLITE_FUNC_UNLIKELY),
91401     VFUNCTION(random,            0, 0, 0, randomFunc       ),
91402     VFUNCTION(randomblob,        1, 0, 0, randomBlob       ),
91403     FUNCTION(nullif,             2, 0, 1, nullifFunc       ),
91404     FUNCTION(sqlite_version,     0, 0, 0, versionFunc      ),
91405     FUNCTION(sqlite_source_id,   0, 0, 0, sourceidFunc     ),
91406     FUNCTION(sqlite_log,         2, 0, 0, errlogFunc       ),
91407 #ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS
91408     FUNCTION(sqlite_compileoption_used,1, 0, 0, compileoptionusedFunc  ),
91409     FUNCTION(sqlite_compileoption_get, 1, 0, 0, compileoptiongetFunc  ),
91410 #endif /* SQLITE_OMIT_COMPILEOPTION_DIAGS */
91411     FUNCTION(quote,              1, 0, 0, quoteFunc        ),
91412     VFUNCTION(last_insert_rowid, 0, 0, 0, last_insert_rowid),
91413     VFUNCTION(changes,           0, 0, 0, changes          ),
91414     VFUNCTION(total_changes,     0, 0, 0, total_changes    ),
91415     FUNCTION(replace,            3, 0, 0, replaceFunc      ),
91416     FUNCTION(zeroblob,           1, 0, 0, zeroblobFunc     ),
91417   #ifdef SQLITE_SOUNDEX
91418     FUNCTION(soundex,            1, 0, 0, soundexFunc      ),
91419   #endif
91420   #ifndef SQLITE_OMIT_LOAD_EXTENSION
91421     FUNCTION(load_extension,     1, 0, 0, loadExt          ),
91422     FUNCTION(load_extension,     2, 0, 0, loadExt          ),
91423   #endif
91424     AGGREGATE(sum,               1, 0, 0, sumStep,         sumFinalize    ),
91425     AGGREGATE(total,             1, 0, 0, sumStep,         totalFinalize    ),
91426     AGGREGATE(avg,               1, 0, 0, sumStep,         avgFinalize    ),
91427  /* AGGREGATE(count,             0, 0, 0, countStep,       countFinalize  ), */
91428     {0,SQLITE_UTF8|SQLITE_FUNC_COUNT,0,0,0,countStep,countFinalize,"count",0,0},
91429     AGGREGATE(count,             1, 0, 0, countStep,       countFinalize  ),
91430     AGGREGATE(group_concat,      1, 0, 0, groupConcatStep, groupConcatFinalize),
91431     AGGREGATE(group_concat,      2, 0, 0, groupConcatStep, groupConcatFinalize),
91432   
91433     LIKEFUNC(glob, 2, &globInfo, SQLITE_FUNC_LIKE|SQLITE_FUNC_CASE),
91434   #ifdef SQLITE_CASE_SENSITIVE_LIKE
91435     LIKEFUNC(like, 2, &likeInfoAlt, SQLITE_FUNC_LIKE|SQLITE_FUNC_CASE),
91436     LIKEFUNC(like, 3, &likeInfoAlt, SQLITE_FUNC_LIKE|SQLITE_FUNC_CASE),
91437   #else
91438     LIKEFUNC(like, 2, &likeInfoNorm, SQLITE_FUNC_LIKE),
91439     LIKEFUNC(like, 3, &likeInfoNorm, SQLITE_FUNC_LIKE),
91440   #endif
91441   };
91442 
91443   int i;
91444   FuncDefHash *pHash = &GLOBAL(FuncDefHash, sqlite3GlobalFunctions);
91445   FuncDef *aFunc = (FuncDef*)&GLOBAL(FuncDef, aBuiltinFunc);
91446 
91447   for(i=0; i<ArraySize(aBuiltinFunc); i++){
91448     sqlite3FuncDefInsert(pHash, &aFunc[i]);
91449   }
91450   sqlite3RegisterDateTimeFunctions();
91451 #ifndef SQLITE_OMIT_ALTERTABLE
91452   sqlite3AlterFunctions();
91453 #endif
91454 #if defined(SQLITE_ENABLE_STAT3) || defined(SQLITE_ENABLE_STAT4)
91455   sqlite3AnalyzeFunctions();
91456 #endif
91457 }
91458 
91459 /************** End of func.c ************************************************/
91460 /************** Begin file fkey.c ********************************************/
91461 /*
91462 **
91463 ** The author disclaims copyright to this source code.  In place of
91464 ** a legal notice, here is a blessing:
91465 **
91466 **    May you do good and not evil.
91467 **    May you find forgiveness for yourself and forgive others.
91468 **    May you share freely, never taking more than you give.
91469 **
91470 *************************************************************************
91471 ** This file contains code used by the compiler to add foreign key
91472 ** support to compiled SQL statements.
91473 */
91474 
91475 #ifndef SQLITE_OMIT_FOREIGN_KEY
91476 #ifndef SQLITE_OMIT_TRIGGER
91477 
91478 /*
91479 ** Deferred and Immediate FKs
91480 ** --------------------------
91481 **
91482 ** Foreign keys in SQLite come in two flavours: deferred and immediate.
91483 ** If an immediate foreign key constraint is violated,
91484 ** SQLITE_CONSTRAINT_FOREIGNKEY is returned and the current
91485 ** statement transaction rolled back. If a 
91486 ** deferred foreign key constraint is violated, no action is taken 
91487 ** immediately. However if the application attempts to commit the 
91488 ** transaction before fixing the constraint violation, the attempt fails.
91489 **
91490 ** Deferred constraints are implemented using a simple counter associated
91491 ** with the database handle. The counter is set to zero each time a 
91492 ** database transaction is opened. Each time a statement is executed 
91493 ** that causes a foreign key violation, the counter is incremented. Each
91494 ** time a statement is executed that removes an existing violation from
91495 ** the database, the counter is decremented. When the transaction is
91496 ** committed, the commit fails if the current value of the counter is
91497 ** greater than zero. This scheme has two big drawbacks:
91498 **
91499 **   * When a commit fails due to a deferred foreign key constraint, 
91500 **     there is no way to tell which foreign constraint is not satisfied,
91501 **     or which row it is not satisfied for.
91502 **
91503 **   * If the database contains foreign key violations when the 
91504 **     transaction is opened, this may cause the mechanism to malfunction.
91505 **
91506 ** Despite these problems, this approach is adopted as it seems simpler
91507 ** than the alternatives.
91508 **
91509 ** INSERT operations:
91510 **
91511 **   I.1) For each FK for which the table is the child table, search
91512 **        the parent table for a match. If none is found increment the
91513 **        constraint counter.
91514 **
91515 **   I.2) For each FK for which the table is the parent table, 
91516 **        search the child table for rows that correspond to the new
91517 **        row in the parent table. Decrement the counter for each row
91518 **        found (as the constraint is now satisfied).
91519 **
91520 ** DELETE operations:
91521 **
91522 **   D.1) For each FK for which the table is the child table, 
91523 **        search the parent table for a row that corresponds to the 
91524 **        deleted row in the child table. If such a row is not found, 
91525 **        decrement the counter.
91526 **
91527 **   D.2) For each FK for which the table is the parent table, search 
91528 **        the child table for rows that correspond to the deleted row 
91529 **        in the parent table. For each found increment the counter.
91530 **
91531 ** UPDATE operations:
91532 **
91533 **   An UPDATE command requires that all 4 steps above are taken, but only
91534 **   for FK constraints for which the affected columns are actually 
91535 **   modified (values must be compared at runtime).
91536 **
91537 ** Note that I.1 and D.1 are very similar operations, as are I.2 and D.2.
91538 ** This simplifies the implementation a bit.
91539 **
91540 ** For the purposes of immediate FK constraints, the OR REPLACE conflict
91541 ** resolution is considered to delete rows before the new row is inserted.
91542 ** If a delete caused by OR REPLACE violates an FK constraint, an exception
91543 ** is thrown, even if the FK constraint would be satisfied after the new 
91544 ** row is inserted.
91545 **
91546 ** Immediate constraints are usually handled similarly. The only difference 
91547 ** is that the counter used is stored as part of each individual statement
91548 ** object (struct Vdbe). If, after the statement has run, its immediate
91549 ** constraint counter is greater than zero,
91550 ** it returns SQLITE_CONSTRAINT_FOREIGNKEY
91551 ** and the statement transaction is rolled back. An exception is an INSERT
91552 ** statement that inserts a single row only (no triggers). In this case,
91553 ** instead of using a counter, an exception is thrown immediately if the
91554 ** INSERT violates a foreign key constraint. This is necessary as such
91555 ** an INSERT does not open a statement transaction.
91556 **
91557 ** TODO: How should dropping a table be handled? How should renaming a 
91558 ** table be handled?
91559 **
91560 **
91561 ** Query API Notes
91562 ** ---------------
91563 **
91564 ** Before coding an UPDATE or DELETE row operation, the code-generator
91565 ** for those two operations needs to know whether or not the operation
91566 ** requires any FK processing and, if so, which columns of the original
91567 ** row are required by the FK processing VDBE code (i.e. if FKs were
91568 ** implemented using triggers, which of the old.* columns would be 
91569 ** accessed). No information is required by the code-generator before
91570 ** coding an INSERT operation. The functions used by the UPDATE/DELETE
91571 ** generation code to query for this information are:
91572 **
91573 **   sqlite3FkRequired() - Test to see if FK processing is required.
91574 **   sqlite3FkOldmask()  - Query for the set of required old.* columns.
91575 **
91576 **
91577 ** Externally accessible module functions
91578 ** --------------------------------------
91579 **
91580 **   sqlite3FkCheck()    - Check for foreign key violations.
91581 **   sqlite3FkActions()  - Code triggers for ON UPDATE/ON DELETE actions.
91582 **   sqlite3FkDelete()   - Delete an FKey structure.
91583 */
91584 
91585 /*
91586 ** VDBE Calling Convention
91587 ** -----------------------
91588 **
91589 ** Example:
91590 **
91591 **   For the following INSERT statement:
91592 **
91593 **     CREATE TABLE t1(a, b INTEGER PRIMARY KEY, c);
91594 **     INSERT INTO t1 VALUES(1, 2, 3.1);
91595 **
91596 **   Register (x):        2    (type integer)
91597 **   Register (x+1):      1    (type integer)
91598 **   Register (x+2):      NULL (type NULL)
91599 **   Register (x+3):      3.1  (type real)
91600 */
91601 
91602 /*
91603 ** A foreign key constraint requires that the key columns in the parent
91604 ** table are collectively subject to a UNIQUE or PRIMARY KEY constraint.
91605 ** Given that pParent is the parent table for foreign key constraint pFKey, 
91606 ** search the schema for a unique index on the parent key columns. 
91607 **
91608 ** If successful, zero is returned. If the parent key is an INTEGER PRIMARY 
91609 ** KEY column, then output variable *ppIdx is set to NULL. Otherwise, *ppIdx 
91610 ** is set to point to the unique index. 
91611 ** 
91612 ** If the parent key consists of a single column (the foreign key constraint
91613 ** is not a composite foreign key), output variable *paiCol is set to NULL.
91614 ** Otherwise, it is set to point to an allocated array of size N, where
91615 ** N is the number of columns in the parent key. The first element of the
91616 ** array is the index of the child table column that is mapped by the FK
91617 ** constraint to the parent table column stored in the left-most column
91618 ** of index *ppIdx. The second element of the array is the index of the
91619 ** child table column that corresponds to the second left-most column of
91620 ** *ppIdx, and so on.
91621 **
91622 ** If the required index cannot be found, either because:
91623 **
91624 **   1) The named parent key columns do not exist, or
91625 **
91626 **   2) The named parent key columns do exist, but are not subject to a
91627 **      UNIQUE or PRIMARY KEY constraint, or
91628 **
91629 **   3) No parent key columns were provided explicitly as part of the
91630 **      foreign key definition, and the parent table does not have a
91631 **      PRIMARY KEY, or
91632 **
91633 **   4) No parent key columns were provided explicitly as part of the
91634 **      foreign key definition, and the PRIMARY KEY of the parent table 
91635 **      consists of a a different number of columns to the child key in 
91636 **      the child table.
91637 **
91638 ** then non-zero is returned, and a "foreign key mismatch" error loaded
91639 ** into pParse. If an OOM error occurs, non-zero is returned and the
91640 ** pParse->db->mallocFailed flag is set.
91641 */
91642 SQLITE_PRIVATE int sqlite3FkLocateIndex(
91643   Parse *pParse,                  /* Parse context to store any error in */
91644   Table *pParent,                 /* Parent table of FK constraint pFKey */
91645   FKey *pFKey,                    /* Foreign key to find index for */
91646   Index **ppIdx,                  /* OUT: Unique index on parent table */
91647   int **paiCol                    /* OUT: Map of index columns in pFKey */
91648 ){
91649   Index *pIdx = 0;                    /* Value to return via *ppIdx */
91650   int *aiCol = 0;                     /* Value to return via *paiCol */
91651   int nCol = pFKey->nCol;             /* Number of columns in parent key */
91652   char *zKey = pFKey->aCol[0].zCol;   /* Name of left-most parent key column */
91653 
91654   /* The caller is responsible for zeroing output parameters. */
91655   assert( ppIdx && *ppIdx==0 );
91656   assert( !paiCol || *paiCol==0 );
91657   assert( pParse );
91658 
91659   /* If this is a non-composite (single column) foreign key, check if it 
91660   ** maps to the INTEGER PRIMARY KEY of table pParent. If so, leave *ppIdx 
91661   ** and *paiCol set to zero and return early. 
91662   **
91663   ** Otherwise, for a composite foreign key (more than one column), allocate
91664   ** space for the aiCol array (returned via output parameter *paiCol).
91665   ** Non-composite foreign keys do not require the aiCol array.
91666   */
91667   if( nCol==1 ){
91668     /* The FK maps to the IPK if any of the following are true:
91669     **
91670     **   1) There is an INTEGER PRIMARY KEY column and the FK is implicitly 
91671     **      mapped to the primary key of table pParent, or
91672     **   2) The FK is explicitly mapped to a column declared as INTEGER
91673     **      PRIMARY KEY.
91674     */
91675     if( pParent->iPKey>=0 ){
91676       if( !zKey ) return 0;
91677       if( !sqlite3StrICmp(pParent->aCol[pParent->iPKey].zName, zKey) ) return 0;
91678     }
91679   }else if( paiCol ){
91680     assert( nCol>1 );
91681     aiCol = (int *)sqlite3DbMallocRaw(pParse->db, nCol*sizeof(int));
91682     if( !aiCol ) return 1;
91683     *paiCol = aiCol;
91684   }
91685 
91686   for(pIdx=pParent->pIndex; pIdx; pIdx=pIdx->pNext){
91687     if( pIdx->nKeyCol==nCol && pIdx->onError!=OE_None ){ 
91688       /* pIdx is a UNIQUE index (or a PRIMARY KEY) and has the right number
91689       ** of columns. If each indexed column corresponds to a foreign key
91690       ** column of pFKey, then this index is a winner.  */
91691 
91692       if( zKey==0 ){
91693         /* If zKey is NULL, then this foreign key is implicitly mapped to 
91694         ** the PRIMARY KEY of table pParent. The PRIMARY KEY index may be 
91695         ** identified by the test (Index.autoIndex==2).  */
91696         if( pIdx->autoIndex==2 ){
91697           if( aiCol ){
91698             int i;
91699             for(i=0; i<nCol; i++) aiCol[i] = pFKey->aCol[i].iFrom;
91700           }
91701           break;
91702         }
91703       }else{
91704         /* If zKey is non-NULL, then this foreign key was declared to
91705         ** map to an explicit list of columns in table pParent. Check if this
91706         ** index matches those columns. Also, check that the index uses
91707         ** the default collation sequences for each column. */
91708         int i, j;
91709         for(i=0; i<nCol; i++){
91710           i16 iCol = pIdx->aiColumn[i];     /* Index of column in parent tbl */
91711           char *zDfltColl;                  /* Def. collation for column */
91712           char *zIdxCol;                    /* Name of indexed column */
91713 
91714           /* If the index uses a collation sequence that is different from
91715           ** the default collation sequence for the column, this index is
91716           ** unusable. Bail out early in this case.  */
91717           zDfltColl = pParent->aCol[iCol].zColl;
91718           if( !zDfltColl ){
91719             zDfltColl = "BINARY";
91720           }
91721           if( sqlite3StrICmp(pIdx->azColl[i], zDfltColl) ) break;
91722 
91723           zIdxCol = pParent->aCol[iCol].zName;
91724           for(j=0; j<nCol; j++){
91725             if( sqlite3StrICmp(pFKey->aCol[j].zCol, zIdxCol)==0 ){
91726               if( aiCol ) aiCol[i] = pFKey->aCol[j].iFrom;
91727               break;
91728             }
91729           }
91730           if( j==nCol ) break;
91731         }
91732         if( i==nCol ) break;      /* pIdx is usable */
91733       }
91734     }
91735   }
91736 
91737   if( !pIdx ){
91738     if( !pParse->disableTriggers ){
91739       sqlite3ErrorMsg(pParse,
91740            "foreign key mismatch - \"%w\" referencing \"%w\"",
91741            pFKey->pFrom->zName, pFKey->zTo);
91742     }
91743     sqlite3DbFree(pParse->db, aiCol);
91744     return 1;
91745   }
91746 
91747   *ppIdx = pIdx;
91748   return 0;
91749 }
91750 
91751 /*
91752 ** This function is called when a row is inserted into or deleted from the 
91753 ** child table of foreign key constraint pFKey. If an SQL UPDATE is executed 
91754 ** on the child table of pFKey, this function is invoked twice for each row
91755 ** affected - once to "delete" the old row, and then again to "insert" the
91756 ** new row.
91757 **
91758 ** Each time it is called, this function generates VDBE code to locate the
91759 ** row in the parent table that corresponds to the row being inserted into 
91760 ** or deleted from the child table. If the parent row can be found, no 
91761 ** special action is taken. Otherwise, if the parent row can *not* be
91762 ** found in the parent table:
91763 **
91764 **   Operation | FK type   | Action taken
91765 **   --------------------------------------------------------------------------
91766 **   INSERT      immediate   Increment the "immediate constraint counter".
91767 **
91768 **   DELETE      immediate   Decrement the "immediate constraint counter".
91769 **
91770 **   INSERT      deferred    Increment the "deferred constraint counter".
91771 **
91772 **   DELETE      deferred    Decrement the "deferred constraint counter".
91773 **
91774 ** These operations are identified in the comment at the top of this file 
91775 ** (fkey.c) as "I.1" and "D.1".
91776 */
91777 static void fkLookupParent(
91778   Parse *pParse,        /* Parse context */
91779   int iDb,              /* Index of database housing pTab */
91780   Table *pTab,          /* Parent table of FK pFKey */
91781   Index *pIdx,          /* Unique index on parent key columns in pTab */
91782   FKey *pFKey,          /* Foreign key constraint */
91783   int *aiCol,           /* Map from parent key columns to child table columns */
91784   int regData,          /* Address of array containing child table row */
91785   int nIncr,            /* Increment constraint counter by this */
91786   int isIgnore          /* If true, pretend pTab contains all NULL values */
91787 ){
91788   int i;                                    /* Iterator variable */
91789   Vdbe *v = sqlite3GetVdbe(pParse);         /* Vdbe to add code to */
91790   int iCur = pParse->nTab - 1;              /* Cursor number to use */
91791   int iOk = sqlite3VdbeMakeLabel(v);        /* jump here if parent key found */
91792 
91793   /* If nIncr is less than zero, then check at runtime if there are any
91794   ** outstanding constraints to resolve. If there are not, there is no need
91795   ** to check if deleting this row resolves any outstanding violations.
91796   **
91797   ** Check if any of the key columns in the child table row are NULL. If 
91798   ** any are, then the constraint is considered satisfied. No need to 
91799   ** search for a matching row in the parent table.  */
91800   if( nIncr<0 ){
91801     sqlite3VdbeAddOp2(v, OP_FkIfZero, pFKey->isDeferred, iOk);
91802   }
91803   for(i=0; i<pFKey->nCol; i++){
91804     int iReg = aiCol[i] + regData + 1;
91805     sqlite3VdbeAddOp2(v, OP_IsNull, iReg, iOk);
91806   }
91807 
91808   if( isIgnore==0 ){
91809     if( pIdx==0 ){
91810       /* If pIdx is NULL, then the parent key is the INTEGER PRIMARY KEY
91811       ** column of the parent table (table pTab).  */
91812       int iMustBeInt;               /* Address of MustBeInt instruction */
91813       int regTemp = sqlite3GetTempReg(pParse);
91814   
91815       /* Invoke MustBeInt to coerce the child key value to an integer (i.e. 
91816       ** apply the affinity of the parent key). If this fails, then there
91817       ** is no matching parent key. Before using MustBeInt, make a copy of
91818       ** the value. Otherwise, the value inserted into the child key column
91819       ** will have INTEGER affinity applied to it, which may not be correct.  */
91820       sqlite3VdbeAddOp2(v, OP_SCopy, aiCol[0]+1+regData, regTemp);
91821       iMustBeInt = sqlite3VdbeAddOp2(v, OP_MustBeInt, regTemp, 0);
91822   
91823       /* If the parent table is the same as the child table, and we are about
91824       ** to increment the constraint-counter (i.e. this is an INSERT operation),
91825       ** then check if the row being inserted matches itself. If so, do not
91826       ** increment the constraint-counter.  */
91827       if( pTab==pFKey->pFrom && nIncr==1 ){
91828         sqlite3VdbeAddOp3(v, OP_Eq, regData, iOk, regTemp);
91829       }
91830   
91831       sqlite3OpenTable(pParse, iCur, iDb, pTab, OP_OpenRead);
91832       sqlite3VdbeAddOp3(v, OP_NotExists, iCur, 0, regTemp);
91833       sqlite3VdbeAddOp2(v, OP_Goto, 0, iOk);
91834       sqlite3VdbeJumpHere(v, sqlite3VdbeCurrentAddr(v)-2);
91835       sqlite3VdbeJumpHere(v, iMustBeInt);
91836       sqlite3ReleaseTempReg(pParse, regTemp);
91837     }else{
91838       int nCol = pFKey->nCol;
91839       int regTemp = sqlite3GetTempRange(pParse, nCol);
91840       int regRec = sqlite3GetTempReg(pParse);
91841   
91842       sqlite3VdbeAddOp3(v, OP_OpenRead, iCur, pIdx->tnum, iDb);
91843       sqlite3VdbeSetP4KeyInfo(pParse, pIdx);
91844       for(i=0; i<nCol; i++){
91845         sqlite3VdbeAddOp2(v, OP_Copy, aiCol[i]+1+regData, regTemp+i);
91846       }
91847   
91848       /* If the parent table is the same as the child table, and we are about
91849       ** to increment the constraint-counter (i.e. this is an INSERT operation),
91850       ** then check if the row being inserted matches itself. If so, do not
91851       ** increment the constraint-counter. 
91852       **
91853       ** If any of the parent-key values are NULL, then the row cannot match 
91854       ** itself. So set JUMPIFNULL to make sure we do the OP_Found if any
91855       ** of the parent-key values are NULL (at this point it is known that
91856       ** none of the child key values are).
91857       */
91858       if( pTab==pFKey->pFrom && nIncr==1 ){
91859         int iJump = sqlite3VdbeCurrentAddr(v) + nCol + 1;
91860         for(i=0; i<nCol; i++){
91861           int iChild = aiCol[i]+1+regData;
91862           int iParent = pIdx->aiColumn[i]+1+regData;
91863           assert( aiCol[i]!=pTab->iPKey );
91864           if( pIdx->aiColumn[i]==pTab->iPKey ){
91865             /* The parent key is a composite key that includes the IPK column */
91866             iParent = regData;
91867           }
91868           sqlite3VdbeAddOp3(v, OP_Ne, iChild, iJump, iParent);
91869           sqlite3VdbeChangeP5(v, SQLITE_JUMPIFNULL);
91870         }
91871         sqlite3VdbeAddOp2(v, OP_Goto, 0, iOk);
91872       }
91873   
91874       sqlite3VdbeAddOp3(v, OP_MakeRecord, regTemp, nCol, regRec);
91875       sqlite3VdbeChangeP4(v, -1, sqlite3IndexAffinityStr(v,pIdx), P4_TRANSIENT);
91876       sqlite3VdbeAddOp4Int(v, OP_Found, iCur, iOk, regRec, 0);
91877   
91878       sqlite3ReleaseTempReg(pParse, regRec);
91879       sqlite3ReleaseTempRange(pParse, regTemp, nCol);
91880     }
91881   }
91882 
91883   if( !pFKey->isDeferred && !(pParse->db->flags & SQLITE_DeferFKs)
91884    && !pParse->pToplevel 
91885    && !pParse->isMultiWrite 
91886   ){
91887     /* Special case: If this is an INSERT statement that will insert exactly
91888     ** one row into the table, raise a constraint immediately instead of
91889     ** incrementing a counter. This is necessary as the VM code is being
91890     ** generated for will not open a statement transaction.  */
91891     assert( nIncr==1 );
91892     sqlite3HaltConstraint(pParse, SQLITE_CONSTRAINT_FOREIGNKEY,
91893         OE_Abort, 0, P4_STATIC, P5_ConstraintFK);
91894   }else{
91895     if( nIncr>0 && pFKey->isDeferred==0 ){
91896       sqlite3ParseToplevel(pParse)->mayAbort = 1;
91897     }
91898     sqlite3VdbeAddOp2(v, OP_FkCounter, pFKey->isDeferred, nIncr);
91899   }
91900 
91901   sqlite3VdbeResolveLabel(v, iOk);
91902   sqlite3VdbeAddOp1(v, OP_Close, iCur);
91903 }
91904 
91905 
91906 /*
91907 ** Return an Expr object that refers to a memory register corresponding
91908 ** to column iCol of table pTab.
91909 **
91910 ** regBase is the first of an array of register that contains the data
91911 ** for pTab.  regBase itself holds the rowid.  regBase+1 holds the first
91912 ** column.  regBase+2 holds the second column, and so forth.
91913 */
91914 static Expr *exprTableRegister(
91915   Parse *pParse,     /* Parsing and code generating context */
91916   Table *pTab,       /* The table whose content is at r[regBase]... */
91917   int regBase,       /* Contents of table pTab */
91918   i16 iCol           /* Which column of pTab is desired */
91919 ){
91920   Expr *pExpr;
91921   Column *pCol;
91922   const char *zColl;
91923   sqlite3 *db = pParse->db;
91924 
91925   pExpr = sqlite3Expr(db, TK_REGISTER, 0);
91926   if( pExpr ){
91927     if( iCol>=0 && iCol!=pTab->iPKey ){
91928       pCol = &pTab->aCol[iCol];
91929       pExpr->iTable = regBase + iCol + 1;
91930       pExpr->affinity = pCol->affinity;
91931       zColl = pCol->zColl;
91932       if( zColl==0 ) zColl = db->pDfltColl->zName;
91933       pExpr = sqlite3ExprAddCollateString(pParse, pExpr, zColl);
91934     }else{
91935       pExpr->iTable = regBase;
91936       pExpr->affinity = SQLITE_AFF_INTEGER;
91937     }
91938   }
91939   return pExpr;
91940 }
91941 
91942 /*
91943 ** Return an Expr object that refers to column iCol of table pTab which
91944 ** has cursor iCur.
91945 */
91946 static Expr *exprTableColumn(
91947   sqlite3 *db,      /* The database connection */
91948   Table *pTab,      /* The table whose column is desired */
91949   int iCursor,      /* The open cursor on the table */
91950   i16 iCol          /* The column that is wanted */
91951 ){
91952   Expr *pExpr = sqlite3Expr(db, TK_COLUMN, 0);
91953   if( pExpr ){
91954     pExpr->pTab = pTab;
91955     pExpr->iTable = iCursor;
91956     pExpr->iColumn = iCol;
91957   }
91958   return pExpr;
91959 }
91960 
91961 /*
91962 ** This function is called to generate code executed when a row is deleted
91963 ** from the parent table of foreign key constraint pFKey and, if pFKey is 
91964 ** deferred, when a row is inserted into the same table. When generating
91965 ** code for an SQL UPDATE operation, this function may be called twice -
91966 ** once to "delete" the old row and once to "insert" the new row.
91967 **
91968 ** The code generated by this function scans through the rows in the child
91969 ** table that correspond to the parent table row being deleted or inserted.
91970 ** For each child row found, one of the following actions is taken:
91971 **
91972 **   Operation | FK type   | Action taken
91973 **   --------------------------------------------------------------------------
91974 **   DELETE      immediate   Increment the "immediate constraint counter".
91975 **                           Or, if the ON (UPDATE|DELETE) action is RESTRICT,
91976 **                           throw a "FOREIGN KEY constraint failed" exception.
91977 **
91978 **   INSERT      immediate   Decrement the "immediate constraint counter".
91979 **
91980 **   DELETE      deferred    Increment the "deferred constraint counter".
91981 **                           Or, if the ON (UPDATE|DELETE) action is RESTRICT,
91982 **                           throw a "FOREIGN KEY constraint failed" exception.
91983 **
91984 **   INSERT      deferred    Decrement the "deferred constraint counter".
91985 **
91986 ** These operations are identified in the comment at the top of this file 
91987 ** (fkey.c) as "I.2" and "D.2".
91988 */
91989 static void fkScanChildren(
91990   Parse *pParse,                  /* Parse context */
91991   SrcList *pSrc,                  /* The child table to be scanned */
91992   Table *pTab,                    /* The parent table */
91993   Index *pIdx,                    /* Index on parent covering the foreign key */
91994   FKey *pFKey,                    /* The foreign key linking pSrc to pTab */
91995   int *aiCol,                     /* Map from pIdx cols to child table cols */
91996   int regData,                    /* Parent row data starts here */
91997   int nIncr                       /* Amount to increment deferred counter by */
91998 ){
91999   sqlite3 *db = pParse->db;       /* Database handle */
92000   int i;                          /* Iterator variable */
92001   Expr *pWhere = 0;               /* WHERE clause to scan with */
92002   NameContext sNameContext;       /* Context used to resolve WHERE clause */
92003   WhereInfo *pWInfo;              /* Context used by sqlite3WhereXXX() */
92004   int iFkIfZero = 0;              /* Address of OP_FkIfZero */
92005   Vdbe *v = sqlite3GetVdbe(pParse);
92006 
92007   assert( pIdx==0 || pIdx->pTable==pTab );
92008   assert( pIdx==0 || pIdx->nKeyCol==pFKey->nCol );
92009   assert( pIdx!=0 || pFKey->nCol==1 );
92010   assert( pIdx!=0 || HasRowid(pTab) );
92011 
92012   if( nIncr<0 ){
92013     iFkIfZero = sqlite3VdbeAddOp2(v, OP_FkIfZero, pFKey->isDeferred, 0);
92014   }
92015 
92016   /* Create an Expr object representing an SQL expression like:
92017   **
92018   **   <parent-key1> = <child-key1> AND <parent-key2> = <child-key2> ...
92019   **
92020   ** The collation sequence used for the comparison should be that of
92021   ** the parent key columns. The affinity of the parent key column should
92022   ** be applied to each child key value before the comparison takes place.
92023   */
92024   for(i=0; i<pFKey->nCol; i++){
92025     Expr *pLeft;                  /* Value from parent table row */
92026     Expr *pRight;                 /* Column ref to child table */
92027     Expr *pEq;                    /* Expression (pLeft = pRight) */
92028     i16 iCol;                     /* Index of column in child table */ 
92029     const char *zCol;             /* Name of column in child table */
92030 
92031     iCol = pIdx ? pIdx->aiColumn[i] : -1;
92032     pLeft = exprTableRegister(pParse, pTab, regData, iCol);
92033     iCol = aiCol ? aiCol[i] : pFKey->aCol[0].iFrom;
92034     assert( iCol>=0 );
92035     zCol = pFKey->pFrom->aCol[iCol].zName;
92036     pRight = sqlite3Expr(db, TK_ID, zCol);
92037     pEq = sqlite3PExpr(pParse, TK_EQ, pLeft, pRight, 0);
92038     pWhere = sqlite3ExprAnd(db, pWhere, pEq);
92039   }
92040 
92041   /* If the child table is the same as the parent table, then add terms
92042   ** to the WHERE clause that prevent this entry from being scanned.
92043   ** The added WHERE clause terms are like this:
92044   **
92045   **     $current_rowid!=rowid
92046   **     NOT( $current_a==a AND $current_b==b AND ... )
92047   **
92048   ** The first form is used for rowid tables.  The second form is used
92049   ** for WITHOUT ROWID tables.  In the second form, the primary key is
92050   ** (a,b,...)
92051   */
92052   if( pTab==pFKey->pFrom && nIncr>0 ){
92053     Expr *pNe;                    /* Expression (pLeft != pRight) */
92054     Expr *pLeft;                  /* Value from parent table row */
92055     Expr *pRight;                 /* Column ref to child table */
92056     if( HasRowid(pTab) ){
92057       pLeft = exprTableRegister(pParse, pTab, regData, -1);
92058       pRight = exprTableColumn(db, pTab, pSrc->a[0].iCursor, -1);
92059       pNe = sqlite3PExpr(pParse, TK_NE, pLeft, pRight, 0);
92060     }else{
92061       Expr *pEq, *pAll = 0;
92062       Index *pPk = sqlite3PrimaryKeyIndex(pTab);
92063       assert( pIdx!=0 );
92064       for(i=0; i<pPk->nKeyCol; i++){
92065         i16 iCol = pIdx->aiColumn[i];
92066         pLeft = exprTableRegister(pParse, pTab, regData, iCol);
92067         pRight = exprTableColumn(db, pTab, pSrc->a[0].iCursor, iCol);
92068         pEq = sqlite3PExpr(pParse, TK_EQ, pLeft, pRight, 0);
92069         pAll = sqlite3ExprAnd(db, pAll, pEq);
92070       }
92071       pNe = sqlite3PExpr(pParse, TK_NOT, pAll, 0, 0);
92072     }
92073     pWhere = sqlite3ExprAnd(db, pWhere, pNe);
92074   }
92075 
92076   /* Resolve the references in the WHERE clause. */
92077   memset(&sNameContext, 0, sizeof(NameContext));
92078   sNameContext.pSrcList = pSrc;
92079   sNameContext.pParse = pParse;
92080   sqlite3ResolveExprNames(&sNameContext, pWhere);
92081 
92082   /* Create VDBE to loop through the entries in pSrc that match the WHERE
92083   ** clause. If the constraint is not deferred, throw an exception for
92084   ** each row found. Otherwise, for deferred constraints, increment the
92085   ** deferred constraint counter by nIncr for each row selected.  */
92086   pWInfo = sqlite3WhereBegin(pParse, pSrc, pWhere, 0, 0, 0, 0);
92087   if( nIncr>0 && pFKey->isDeferred==0 ){
92088     sqlite3ParseToplevel(pParse)->mayAbort = 1;
92089   }
92090   sqlite3VdbeAddOp2(v, OP_FkCounter, pFKey->isDeferred, nIncr);
92091   if( pWInfo ){
92092     sqlite3WhereEnd(pWInfo);
92093   }
92094 
92095   /* Clean up the WHERE clause constructed above. */
92096   sqlite3ExprDelete(db, pWhere);
92097   if( iFkIfZero ){
92098     sqlite3VdbeJumpHere(v, iFkIfZero);
92099   }
92100 }
92101 
92102 /*
92103 ** This function returns a linked list of FKey objects (connected by
92104 ** FKey.pNextTo) holding all children of table pTab.  For example,
92105 ** given the following schema:
92106 **
92107 **   CREATE TABLE t1(a PRIMARY KEY);
92108 **   CREATE TABLE t2(b REFERENCES t1(a);
92109 **
92110 ** Calling this function with table "t1" as an argument returns a pointer
92111 ** to the FKey structure representing the foreign key constraint on table
92112 ** "t2". Calling this function with "t2" as the argument would return a
92113 ** NULL pointer (as there are no FK constraints for which t2 is the parent
92114 ** table).
92115 */
92116 SQLITE_PRIVATE FKey *sqlite3FkReferences(Table *pTab){
92117   int nName = sqlite3Strlen30(pTab->zName);
92118   return (FKey *)sqlite3HashFind(&pTab->pSchema->fkeyHash, pTab->zName, nName);
92119 }
92120 
92121 /*
92122 ** The second argument is a Trigger structure allocated by the 
92123 ** fkActionTrigger() routine. This function deletes the Trigger structure
92124 ** and all of its sub-components.
92125 **
92126 ** The Trigger structure or any of its sub-components may be allocated from
92127 ** the lookaside buffer belonging to database handle dbMem.
92128 */
92129 static void fkTriggerDelete(sqlite3 *dbMem, Trigger *p){
92130   if( p ){
92131     TriggerStep *pStep = p->step_list;
92132     sqlite3ExprDelete(dbMem, pStep->pWhere);
92133     sqlite3ExprListDelete(dbMem, pStep->pExprList);
92134     sqlite3SelectDelete(dbMem, pStep->pSelect);
92135     sqlite3ExprDelete(dbMem, p->pWhen);
92136     sqlite3DbFree(dbMem, p);
92137   }
92138 }
92139 
92140 /*
92141 ** This function is called to generate code that runs when table pTab is
92142 ** being dropped from the database. The SrcList passed as the second argument
92143 ** to this function contains a single entry guaranteed to resolve to
92144 ** table pTab.
92145 **
92146 ** Normally, no code is required. However, if either
92147 **
92148 **   (a) The table is the parent table of a FK constraint, or
92149 **   (b) The table is the child table of a deferred FK constraint and it is
92150 **       determined at runtime that there are outstanding deferred FK 
92151 **       constraint violations in the database,
92152 **
92153 ** then the equivalent of "DELETE FROM <tbl>" is executed before dropping
92154 ** the table from the database. Triggers are disabled while running this
92155 ** DELETE, but foreign key actions are not.
92156 */
92157 SQLITE_PRIVATE void sqlite3FkDropTable(Parse *pParse, SrcList *pName, Table *pTab){
92158   sqlite3 *db = pParse->db;
92159   if( (db->flags&SQLITE_ForeignKeys) && !IsVirtual(pTab) && !pTab->pSelect ){
92160     int iSkip = 0;
92161     Vdbe *v = sqlite3GetVdbe(pParse);
92162 
92163     assert( v );                  /* VDBE has already been allocated */
92164     if( sqlite3FkReferences(pTab)==0 ){
92165       /* Search for a deferred foreign key constraint for which this table
92166       ** is the child table. If one cannot be found, return without 
92167       ** generating any VDBE code. If one can be found, then jump over
92168       ** the entire DELETE if there are no outstanding deferred constraints
92169       ** when this statement is run.  */
92170       FKey *p;
92171       for(p=pTab->pFKey; p; p=p->pNextFrom){
92172         if( p->isDeferred || (db->flags & SQLITE_DeferFKs) ) break;
92173       }
92174       if( !p ) return;
92175       iSkip = sqlite3VdbeMakeLabel(v);
92176       sqlite3VdbeAddOp2(v, OP_FkIfZero, 1, iSkip);
92177     }
92178 
92179     pParse->disableTriggers = 1;
92180     sqlite3DeleteFrom(pParse, sqlite3SrcListDup(db, pName, 0), 0);
92181     pParse->disableTriggers = 0;
92182 
92183     /* If the DELETE has generated immediate foreign key constraint 
92184     ** violations, halt the VDBE and return an error at this point, before
92185     ** any modifications to the schema are made. This is because statement
92186     ** transactions are not able to rollback schema changes.  
92187     **
92188     ** If the SQLITE_DeferFKs flag is set, then this is not required, as
92189     ** the statement transaction will not be rolled back even if FK
92190     ** constraints are violated.
92191     */
92192     if( (db->flags & SQLITE_DeferFKs)==0 ){
92193       sqlite3VdbeAddOp2(v, OP_FkIfZero, 0, sqlite3VdbeCurrentAddr(v)+2);
92194       sqlite3HaltConstraint(pParse, SQLITE_CONSTRAINT_FOREIGNKEY,
92195           OE_Abort, 0, P4_STATIC, P5_ConstraintFK);
92196     }
92197 
92198     if( iSkip ){
92199       sqlite3VdbeResolveLabel(v, iSkip);
92200     }
92201   }
92202 }
92203 
92204 
92205 /*
92206 ** The second argument points to an FKey object representing a foreign key
92207 ** for which pTab is the child table. An UPDATE statement against pTab
92208 ** is currently being processed. For each column of the table that is 
92209 ** actually updated, the corresponding element in the aChange[] array
92210 ** is zero or greater (if a column is unmodified the corresponding element
92211 ** is set to -1). If the rowid column is modified by the UPDATE statement
92212 ** the bChngRowid argument is non-zero.
92213 **
92214 ** This function returns true if any of the columns that are part of the
92215 ** child key for FK constraint *p are modified.
92216 */
92217 static int fkChildIsModified(
92218   Table *pTab,                    /* Table being updated */
92219   FKey *p,                        /* Foreign key for which pTab is the child */
92220   int *aChange,                   /* Array indicating modified columns */
92221   int bChngRowid                  /* True if rowid is modified by this update */
92222 ){
92223   int i;
92224   for(i=0; i<p->nCol; i++){
92225     int iChildKey = p->aCol[i].iFrom;
92226     if( aChange[iChildKey]>=0 ) return 1;
92227     if( iChildKey==pTab->iPKey && bChngRowid ) return 1;
92228   }
92229   return 0;
92230 }
92231 
92232 /*
92233 ** The second argument points to an FKey object representing a foreign key
92234 ** for which pTab is the parent table. An UPDATE statement against pTab
92235 ** is currently being processed. For each column of the table that is 
92236 ** actually updated, the corresponding element in the aChange[] array
92237 ** is zero or greater (if a column is unmodified the corresponding element
92238 ** is set to -1). If the rowid column is modified by the UPDATE statement
92239 ** the bChngRowid argument is non-zero.
92240 **
92241 ** This function returns true if any of the columns that are part of the
92242 ** parent key for FK constraint *p are modified.
92243 */
92244 static int fkParentIsModified(
92245   Table *pTab, 
92246   FKey *p, 
92247   int *aChange, 
92248   int bChngRowid
92249 ){
92250   int i;
92251   for(i=0; i<p->nCol; i++){
92252     char *zKey = p->aCol[i].zCol;
92253     int iKey;
92254     for(iKey=0; iKey<pTab->nCol; iKey++){
92255       if( aChange[iKey]>=0 || (iKey==pTab->iPKey && bChngRowid) ){
92256         Column *pCol = &pTab->aCol[iKey];
92257         if( zKey ){
92258           if( 0==sqlite3StrICmp(pCol->zName, zKey) ) return 1;
92259         }else if( pCol->colFlags & COLFLAG_PRIMKEY ){
92260           return 1;
92261         }
92262       }
92263     }
92264   }
92265   return 0;
92266 }
92267 
92268 /*
92269 ** This function is called when inserting, deleting or updating a row of
92270 ** table pTab to generate VDBE code to perform foreign key constraint 
92271 ** processing for the operation.
92272 **
92273 ** For a DELETE operation, parameter regOld is passed the index of the
92274 ** first register in an array of (pTab->nCol+1) registers containing the
92275 ** rowid of the row being deleted, followed by each of the column values
92276 ** of the row being deleted, from left to right. Parameter regNew is passed
92277 ** zero in this case.
92278 **
92279 ** For an INSERT operation, regOld is passed zero and regNew is passed the
92280 ** first register of an array of (pTab->nCol+1) registers containing the new
92281 ** row data.
92282 **
92283 ** For an UPDATE operation, this function is called twice. Once before
92284 ** the original record is deleted from the table using the calling convention
92285 ** described for DELETE. Then again after the original record is deleted
92286 ** but before the new record is inserted using the INSERT convention. 
92287 */
92288 SQLITE_PRIVATE void sqlite3FkCheck(
92289   Parse *pParse,                  /* Parse context */
92290   Table *pTab,                    /* Row is being deleted from this table */ 
92291   int regOld,                     /* Previous row data is stored here */
92292   int regNew,                     /* New row data is stored here */
92293   int *aChange,                   /* Array indicating UPDATEd columns (or 0) */
92294   int bChngRowid                  /* True if rowid is UPDATEd */
92295 ){
92296   sqlite3 *db = pParse->db;       /* Database handle */
92297   FKey *pFKey;                    /* Used to iterate through FKs */
92298   int iDb;                        /* Index of database containing pTab */
92299   const char *zDb;                /* Name of database containing pTab */
92300   int isIgnoreErrors = pParse->disableTriggers;
92301 
92302   /* Exactly one of regOld and regNew should be non-zero. */
92303   assert( (regOld==0)!=(regNew==0) );
92304 
92305   /* If foreign-keys are disabled, this function is a no-op. */
92306   if( (db->flags&SQLITE_ForeignKeys)==0 ) return;
92307 
92308   iDb = sqlite3SchemaToIndex(db, pTab->pSchema);
92309   zDb = db->aDb[iDb].zName;
92310 
92311   /* Loop through all the foreign key constraints for which pTab is the
92312   ** child table (the table that the foreign key definition is part of).  */
92313   for(pFKey=pTab->pFKey; pFKey; pFKey=pFKey->pNextFrom){
92314     Table *pTo;                   /* Parent table of foreign key pFKey */
92315     Index *pIdx = 0;              /* Index on key columns in pTo */
92316     int *aiFree = 0;
92317     int *aiCol;
92318     int iCol;
92319     int i;
92320     int isIgnore = 0;
92321 
92322     if( aChange 
92323      && sqlite3_stricmp(pTab->zName, pFKey->zTo)!=0
92324      && fkChildIsModified(pTab, pFKey, aChange, bChngRowid)==0 
92325     ){
92326       continue;
92327     }
92328 
92329     /* Find the parent table of this foreign key. Also find a unique index 
92330     ** on the parent key columns in the parent table. If either of these 
92331     ** schema items cannot be located, set an error in pParse and return 
92332     ** early.  */
92333     if( pParse->disableTriggers ){
92334       pTo = sqlite3FindTable(db, pFKey->zTo, zDb);
92335     }else{
92336       pTo = sqlite3LocateTable(pParse, 0, pFKey->zTo, zDb);
92337     }
92338     if( !pTo || sqlite3FkLocateIndex(pParse, pTo, pFKey, &pIdx, &aiFree) ){
92339       assert( isIgnoreErrors==0 || (regOld!=0 && regNew==0) );
92340       if( !isIgnoreErrors || db->mallocFailed ) return;
92341       if( pTo==0 ){
92342         /* If isIgnoreErrors is true, then a table is being dropped. In this
92343         ** case SQLite runs a "DELETE FROM xxx" on the table being dropped
92344         ** before actually dropping it in order to check FK constraints.
92345         ** If the parent table of an FK constraint on the current table is
92346         ** missing, behave as if it is empty. i.e. decrement the relevant
92347         ** FK counter for each row of the current table with non-NULL keys.
92348         */
92349         Vdbe *v = sqlite3GetVdbe(pParse);
92350         int iJump = sqlite3VdbeCurrentAddr(v) + pFKey->nCol + 1;
92351         for(i=0; i<pFKey->nCol; i++){
92352           int iReg = pFKey->aCol[i].iFrom + regOld + 1;
92353           sqlite3VdbeAddOp2(v, OP_IsNull, iReg, iJump);
92354         }
92355         sqlite3VdbeAddOp2(v, OP_FkCounter, pFKey->isDeferred, -1);
92356       }
92357       continue;
92358     }
92359     assert( pFKey->nCol==1 || (aiFree && pIdx) );
92360 
92361     if( aiFree ){
92362       aiCol = aiFree;
92363     }else{
92364       iCol = pFKey->aCol[0].iFrom;
92365       aiCol = &iCol;
92366     }
92367     for(i=0; i<pFKey->nCol; i++){
92368       if( aiCol[i]==pTab->iPKey ){
92369         aiCol[i] = -1;
92370       }
92371 #ifndef SQLITE_OMIT_AUTHORIZATION
92372       /* Request permission to read the parent key columns. If the 
92373       ** authorization callback returns SQLITE_IGNORE, behave as if any
92374       ** values read from the parent table are NULL. */
92375       if( db->xAuth ){
92376         int rcauth;
92377         char *zCol = pTo->aCol[pIdx ? pIdx->aiColumn[i] : pTo->iPKey].zName;
92378         rcauth = sqlite3AuthReadCol(pParse, pTo->zName, zCol, iDb);
92379         isIgnore = (rcauth==SQLITE_IGNORE);
92380       }
92381 #endif
92382     }
92383 
92384     /* Take a shared-cache advisory read-lock on the parent table. Allocate 
92385     ** a cursor to use to search the unique index on the parent key columns 
92386     ** in the parent table.  */
92387     sqlite3TableLock(pParse, iDb, pTo->tnum, 0, pTo->zName);
92388     pParse->nTab++;
92389 
92390     if( regOld!=0 ){
92391       /* A row is being removed from the child table. Search for the parent.
92392       ** If the parent does not exist, removing the child row resolves an 
92393       ** outstanding foreign key constraint violation. */
92394       fkLookupParent(pParse, iDb, pTo, pIdx, pFKey, aiCol, regOld, -1,isIgnore);
92395     }
92396     if( regNew!=0 ){
92397       /* A row is being added to the child table. If a parent row cannot
92398       ** be found, adding the child row has violated the FK constraint. */ 
92399       fkLookupParent(pParse, iDb, pTo, pIdx, pFKey, aiCol, regNew, +1,isIgnore);
92400     }
92401 
92402     sqlite3DbFree(db, aiFree);
92403   }
92404 
92405   /* Loop through all the foreign key constraints that refer to this table.
92406   ** (the "child" constraints) */
92407   for(pFKey = sqlite3FkReferences(pTab); pFKey; pFKey=pFKey->pNextTo){
92408     Index *pIdx = 0;              /* Foreign key index for pFKey */
92409     SrcList *pSrc;
92410     int *aiCol = 0;
92411 
92412     if( aChange && fkParentIsModified(pTab, pFKey, aChange, bChngRowid)==0 ){
92413       continue;
92414     }
92415 
92416     if( !pFKey->isDeferred && !(db->flags & SQLITE_DeferFKs) 
92417      && !pParse->pToplevel && !pParse->isMultiWrite 
92418     ){
92419       assert( regOld==0 && regNew!=0 );
92420       /* Inserting a single row into a parent table cannot cause an immediate
92421       ** foreign key violation. So do nothing in this case.  */
92422       continue;
92423     }
92424 
92425     if( sqlite3FkLocateIndex(pParse, pTab, pFKey, &pIdx, &aiCol) ){
92426       if( !isIgnoreErrors || db->mallocFailed ) return;
92427       continue;
92428     }
92429     assert( aiCol || pFKey->nCol==1 );
92430 
92431     /* Create a SrcList structure containing the child table.  We need the
92432     ** child table as a SrcList for sqlite3WhereBegin() */
92433     pSrc = sqlite3SrcListAppend(db, 0, 0, 0);
92434     if( pSrc ){
92435       struct SrcList_item *pItem = pSrc->a;
92436       pItem->pTab = pFKey->pFrom;
92437       pItem->zName = pFKey->pFrom->zName;
92438       pItem->pTab->nRef++;
92439       pItem->iCursor = pParse->nTab++;
92440   
92441       if( regNew!=0 ){
92442         fkScanChildren(pParse, pSrc, pTab, pIdx, pFKey, aiCol, regNew, -1);
92443       }
92444       if( regOld!=0 ){
92445         /* If there is a RESTRICT action configured for the current operation
92446         ** on the parent table of this FK, then throw an exception 
92447         ** immediately if the FK constraint is violated, even if this is a
92448         ** deferred trigger. That's what RESTRICT means. To defer checking
92449         ** the constraint, the FK should specify NO ACTION (represented
92450         ** using OE_None). NO ACTION is the default.  */
92451         fkScanChildren(pParse, pSrc, pTab, pIdx, pFKey, aiCol, regOld, 1);
92452       }
92453       pItem->zName = 0;
92454       sqlite3SrcListDelete(db, pSrc);
92455     }
92456     sqlite3DbFree(db, aiCol);
92457   }
92458 }
92459 
92460 #define COLUMN_MASK(x) (((x)>31) ? 0xffffffff : ((u32)1<<(x)))
92461 
92462 /*
92463 ** This function is called before generating code to update or delete a 
92464 ** row contained in table pTab.
92465 */
92466 SQLITE_PRIVATE u32 sqlite3FkOldmask(
92467   Parse *pParse,                  /* Parse context */
92468   Table *pTab                     /* Table being modified */
92469 ){
92470   u32 mask = 0;
92471   if( pParse->db->flags&SQLITE_ForeignKeys ){
92472     FKey *p;
92473     int i;
92474     for(p=pTab->pFKey; p; p=p->pNextFrom){
92475       for(i=0; i<p->nCol; i++) mask |= COLUMN_MASK(p->aCol[i].iFrom);
92476     }
92477     for(p=sqlite3FkReferences(pTab); p; p=p->pNextTo){
92478       Index *pIdx = 0;
92479       sqlite3FkLocateIndex(pParse, pTab, p, &pIdx, 0);
92480       if( pIdx ){
92481         for(i=0; i<pIdx->nKeyCol; i++) mask |= COLUMN_MASK(pIdx->aiColumn[i]);
92482       }
92483     }
92484   }
92485   return mask;
92486 }
92487 
92488 
92489 /*
92490 ** This function is called before generating code to update or delete a 
92491 ** row contained in table pTab. If the operation is a DELETE, then
92492 ** parameter aChange is passed a NULL value. For an UPDATE, aChange points
92493 ** to an array of size N, where N is the number of columns in table pTab.
92494 ** If the i'th column is not modified by the UPDATE, then the corresponding 
92495 ** entry in the aChange[] array is set to -1. If the column is modified,
92496 ** the value is 0 or greater. Parameter chngRowid is set to true if the
92497 ** UPDATE statement modifies the rowid fields of the table.
92498 **
92499 ** If any foreign key processing will be required, this function returns
92500 ** true. If there is no foreign key related processing, this function 
92501 ** returns false.
92502 */
92503 SQLITE_PRIVATE int sqlite3FkRequired(
92504   Parse *pParse,                  /* Parse context */
92505   Table *pTab,                    /* Table being modified */
92506   int *aChange,                   /* Non-NULL for UPDATE operations */
92507   int chngRowid                   /* True for UPDATE that affects rowid */
92508 ){
92509   if( pParse->db->flags&SQLITE_ForeignKeys ){
92510     if( !aChange ){
92511       /* A DELETE operation. Foreign key processing is required if the 
92512       ** table in question is either the child or parent table for any 
92513       ** foreign key constraint.  */
92514       return (sqlite3FkReferences(pTab) || pTab->pFKey);
92515     }else{
92516       /* This is an UPDATE. Foreign key processing is only required if the
92517       ** operation modifies one or more child or parent key columns. */
92518       FKey *p;
92519 
92520       /* Check if any child key columns are being modified. */
92521       for(p=pTab->pFKey; p; p=p->pNextFrom){
92522         if( fkChildIsModified(pTab, p, aChange, chngRowid) ) return 1;
92523       }
92524 
92525       /* Check if any parent key columns are being modified. */
92526       for(p=sqlite3FkReferences(pTab); p; p=p->pNextTo){
92527         if( fkParentIsModified(pTab, p, aChange, chngRowid) ) return 1;
92528       }
92529     }
92530   }
92531   return 0;
92532 }
92533 
92534 /*
92535 ** This function is called when an UPDATE or DELETE operation is being 
92536 ** compiled on table pTab, which is the parent table of foreign-key pFKey.
92537 ** If the current operation is an UPDATE, then the pChanges parameter is
92538 ** passed a pointer to the list of columns being modified. If it is a
92539 ** DELETE, pChanges is passed a NULL pointer.
92540 **
92541 ** It returns a pointer to a Trigger structure containing a trigger
92542 ** equivalent to the ON UPDATE or ON DELETE action specified by pFKey.
92543 ** If the action is "NO ACTION" or "RESTRICT", then a NULL pointer is
92544 ** returned (these actions require no special handling by the triggers
92545 ** sub-system, code for them is created by fkScanChildren()).
92546 **
92547 ** For example, if pFKey is the foreign key and pTab is table "p" in 
92548 ** the following schema:
92549 **
92550 **   CREATE TABLE p(pk PRIMARY KEY);
92551 **   CREATE TABLE c(ck REFERENCES p ON DELETE CASCADE);
92552 **
92553 ** then the returned trigger structure is equivalent to:
92554 **
92555 **   CREATE TRIGGER ... DELETE ON p BEGIN
92556 **     DELETE FROM c WHERE ck = old.pk;
92557 **   END;
92558 **
92559 ** The returned pointer is cached as part of the foreign key object. It
92560 ** is eventually freed along with the rest of the foreign key object by 
92561 ** sqlite3FkDelete().
92562 */
92563 static Trigger *fkActionTrigger(
92564   Parse *pParse,                  /* Parse context */
92565   Table *pTab,                    /* Table being updated or deleted from */
92566   FKey *pFKey,                    /* Foreign key to get action for */
92567   ExprList *pChanges              /* Change-list for UPDATE, NULL for DELETE */
92568 ){
92569   sqlite3 *db = pParse->db;       /* Database handle */
92570   int action;                     /* One of OE_None, OE_Cascade etc. */
92571   Trigger *pTrigger;              /* Trigger definition to return */
92572   int iAction = (pChanges!=0);    /* 1 for UPDATE, 0 for DELETE */
92573 
92574   action = pFKey->aAction[iAction];
92575   pTrigger = pFKey->apTrigger[iAction];
92576 
92577   if( action!=OE_None && !pTrigger ){
92578     u8 enableLookaside;           /* Copy of db->lookaside.bEnabled */
92579     char const *zFrom;            /* Name of child table */
92580     int nFrom;                    /* Length in bytes of zFrom */
92581     Index *pIdx = 0;              /* Parent key index for this FK */
92582     int *aiCol = 0;               /* child table cols -> parent key cols */
92583     TriggerStep *pStep = 0;        /* First (only) step of trigger program */
92584     Expr *pWhere = 0;             /* WHERE clause of trigger step */
92585     ExprList *pList = 0;          /* Changes list if ON UPDATE CASCADE */
92586     Select *pSelect = 0;          /* If RESTRICT, "SELECT RAISE(...)" */
92587     int i;                        /* Iterator variable */
92588     Expr *pWhen = 0;              /* WHEN clause for the trigger */
92589 
92590     if( sqlite3FkLocateIndex(pParse, pTab, pFKey, &pIdx, &aiCol) ) return 0;
92591     assert( aiCol || pFKey->nCol==1 );
92592 
92593     for(i=0; i<pFKey->nCol; i++){
92594       Token tOld = { "old", 3 };  /* Literal "old" token */
92595       Token tNew = { "new", 3 };  /* Literal "new" token */
92596       Token tFromCol;             /* Name of column in child table */
92597       Token tToCol;               /* Name of column in parent table */
92598       int iFromCol;               /* Idx of column in child table */
92599       Expr *pEq;                  /* tFromCol = OLD.tToCol */
92600 
92601       iFromCol = aiCol ? aiCol[i] : pFKey->aCol[0].iFrom;
92602       assert( iFromCol>=0 );
92603       tToCol.z = pIdx ? pTab->aCol[pIdx->aiColumn[i]].zName : "oid";
92604       tFromCol.z = pFKey->pFrom->aCol[iFromCol].zName;
92605 
92606       tToCol.n = sqlite3Strlen30(tToCol.z);
92607       tFromCol.n = sqlite3Strlen30(tFromCol.z);
92608 
92609       /* Create the expression "OLD.zToCol = zFromCol". It is important
92610       ** that the "OLD.zToCol" term is on the LHS of the = operator, so
92611       ** that the affinity and collation sequence associated with the
92612       ** parent table are used for the comparison. */
92613       pEq = sqlite3PExpr(pParse, TK_EQ,
92614           sqlite3PExpr(pParse, TK_DOT, 
92615             sqlite3PExpr(pParse, TK_ID, 0, 0, &tOld),
92616             sqlite3PExpr(pParse, TK_ID, 0, 0, &tToCol)
92617           , 0),
92618           sqlite3PExpr(pParse, TK_ID, 0, 0, &tFromCol)
92619       , 0);
92620       pWhere = sqlite3ExprAnd(db, pWhere, pEq);
92621 
92622       /* For ON UPDATE, construct the next term of the WHEN clause.
92623       ** The final WHEN clause will be like this:
92624       **
92625       **    WHEN NOT(old.col1 IS new.col1 AND ... AND old.colN IS new.colN)
92626       */
92627       if( pChanges ){
92628         pEq = sqlite3PExpr(pParse, TK_IS,
92629             sqlite3PExpr(pParse, TK_DOT, 
92630               sqlite3PExpr(pParse, TK_ID, 0, 0, &tOld),
92631               sqlite3PExpr(pParse, TK_ID, 0, 0, &tToCol),
92632               0),
92633             sqlite3PExpr(pParse, TK_DOT, 
92634               sqlite3PExpr(pParse, TK_ID, 0, 0, &tNew),
92635               sqlite3PExpr(pParse, TK_ID, 0, 0, &tToCol),
92636               0),
92637             0);
92638         pWhen = sqlite3ExprAnd(db, pWhen, pEq);
92639       }
92640   
92641       if( action!=OE_Restrict && (action!=OE_Cascade || pChanges) ){
92642         Expr *pNew;
92643         if( action==OE_Cascade ){
92644           pNew = sqlite3PExpr(pParse, TK_DOT, 
92645             sqlite3PExpr(pParse, TK_ID, 0, 0, &tNew),
92646             sqlite3PExpr(pParse, TK_ID, 0, 0, &tToCol)
92647           , 0);
92648         }else if( action==OE_SetDflt ){
92649           Expr *pDflt = pFKey->pFrom->aCol[iFromCol].pDflt;
92650           if( pDflt ){
92651             pNew = sqlite3ExprDup(db, pDflt, 0);
92652           }else{
92653             pNew = sqlite3PExpr(pParse, TK_NULL, 0, 0, 0);
92654           }
92655         }else{
92656           pNew = sqlite3PExpr(pParse, TK_NULL, 0, 0, 0);
92657         }
92658         pList = sqlite3ExprListAppend(pParse, pList, pNew);
92659         sqlite3ExprListSetName(pParse, pList, &tFromCol, 0);
92660       }
92661     }
92662     sqlite3DbFree(db, aiCol);
92663 
92664     zFrom = pFKey->pFrom->zName;
92665     nFrom = sqlite3Strlen30(zFrom);
92666 
92667     if( action==OE_Restrict ){
92668       Token tFrom;
92669       Expr *pRaise; 
92670 
92671       tFrom.z = zFrom;
92672       tFrom.n = nFrom;
92673       pRaise = sqlite3Expr(db, TK_RAISE, "FOREIGN KEY constraint failed");
92674       if( pRaise ){
92675         pRaise->affinity = OE_Abort;
92676       }
92677       pSelect = sqlite3SelectNew(pParse, 
92678           sqlite3ExprListAppend(pParse, 0, pRaise),
92679           sqlite3SrcListAppend(db, 0, &tFrom, 0),
92680           pWhere,
92681           0, 0, 0, 0, 0, 0
92682       );
92683       pWhere = 0;
92684     }
92685 
92686     /* Disable lookaside memory allocation */
92687     enableLookaside = db->lookaside.bEnabled;
92688     db->lookaside.bEnabled = 0;
92689 
92690     pTrigger = (Trigger *)sqlite3DbMallocZero(db, 
92691         sizeof(Trigger) +         /* struct Trigger */
92692         sizeof(TriggerStep) +     /* Single step in trigger program */
92693         nFrom + 1                 /* Space for pStep->target.z */
92694     );
92695     if( pTrigger ){
92696       pStep = pTrigger->step_list = (TriggerStep *)&pTrigger[1];
92697       pStep->target.z = (char *)&pStep[1];
92698       pStep->target.n = nFrom;
92699       memcpy((char *)pStep->target.z, zFrom, nFrom);
92700   
92701       pStep->pWhere = sqlite3ExprDup(db, pWhere, EXPRDUP_REDUCE);
92702       pStep->pExprList = sqlite3ExprListDup(db, pList, EXPRDUP_REDUCE);
92703       pStep->pSelect = sqlite3SelectDup(db, pSelect, EXPRDUP_REDUCE);
92704       if( pWhen ){
92705         pWhen = sqlite3PExpr(pParse, TK_NOT, pWhen, 0, 0);
92706         pTrigger->pWhen = sqlite3ExprDup(db, pWhen, EXPRDUP_REDUCE);
92707       }
92708     }
92709 
92710     /* Re-enable the lookaside buffer, if it was disabled earlier. */
92711     db->lookaside.bEnabled = enableLookaside;
92712 
92713     sqlite3ExprDelete(db, pWhere);
92714     sqlite3ExprDelete(db, pWhen);
92715     sqlite3ExprListDelete(db, pList);
92716     sqlite3SelectDelete(db, pSelect);
92717     if( db->mallocFailed==1 ){
92718       fkTriggerDelete(db, pTrigger);
92719       return 0;
92720     }
92721     assert( pStep!=0 );
92722 
92723     switch( action ){
92724       case OE_Restrict:
92725         pStep->op = TK_SELECT; 
92726         break;
92727       case OE_Cascade: 
92728         if( !pChanges ){ 
92729           pStep->op = TK_DELETE; 
92730           break; 
92731         }
92732       default:
92733         pStep->op = TK_UPDATE;
92734     }
92735     pStep->pTrig = pTrigger;
92736     pTrigger->pSchema = pTab->pSchema;
92737     pTrigger->pTabSchema = pTab->pSchema;
92738     pFKey->apTrigger[iAction] = pTrigger;
92739     pTrigger->op = (pChanges ? TK_UPDATE : TK_DELETE);
92740   }
92741 
92742   return pTrigger;
92743 }
92744 
92745 /*
92746 ** This function is called when deleting or updating a row to implement
92747 ** any required CASCADE, SET NULL or SET DEFAULT actions.
92748 */
92749 SQLITE_PRIVATE void sqlite3FkActions(
92750   Parse *pParse,                  /* Parse context */
92751   Table *pTab,                    /* Table being updated or deleted from */
92752   ExprList *pChanges,             /* Change-list for UPDATE, NULL for DELETE */
92753   int regOld,                     /* Address of array containing old row */
92754   int *aChange,                   /* Array indicating UPDATEd columns (or 0) */
92755   int bChngRowid                  /* True if rowid is UPDATEd */
92756 ){
92757   /* If foreign-key support is enabled, iterate through all FKs that 
92758   ** refer to table pTab. If there is an action associated with the FK 
92759   ** for this operation (either update or delete), invoke the associated 
92760   ** trigger sub-program.  */
92761   if( pParse->db->flags&SQLITE_ForeignKeys ){
92762     FKey *pFKey;                  /* Iterator variable */
92763     for(pFKey = sqlite3FkReferences(pTab); pFKey; pFKey=pFKey->pNextTo){
92764       if( aChange==0 || fkParentIsModified(pTab, pFKey, aChange, bChngRowid) ){
92765         Trigger *pAct = fkActionTrigger(pParse, pTab, pFKey, pChanges);
92766         if( pAct ){
92767           sqlite3CodeRowTriggerDirect(pParse, pAct, pTab, regOld, OE_Abort, 0);
92768         }
92769       }
92770     }
92771   }
92772 }
92773 
92774 #endif /* ifndef SQLITE_OMIT_TRIGGER */
92775 
92776 /*
92777 ** Free all memory associated with foreign key definitions attached to
92778 ** table pTab. Remove the deleted foreign keys from the Schema.fkeyHash
92779 ** hash table.
92780 */
92781 SQLITE_PRIVATE void sqlite3FkDelete(sqlite3 *db, Table *pTab){
92782   FKey *pFKey;                    /* Iterator variable */
92783   FKey *pNext;                    /* Copy of pFKey->pNextFrom */
92784 
92785   assert( db==0 || sqlite3SchemaMutexHeld(db, 0, pTab->pSchema) );
92786   for(pFKey=pTab->pFKey; pFKey; pFKey=pNext){
92787 
92788     /* Remove the FK from the fkeyHash hash table. */
92789     if( !db || db->pnBytesFreed==0 ){
92790       if( pFKey->pPrevTo ){
92791         pFKey->pPrevTo->pNextTo = pFKey->pNextTo;
92792       }else{
92793         void *p = (void *)pFKey->pNextTo;
92794         const char *z = (p ? pFKey->pNextTo->zTo : pFKey->zTo);
92795         sqlite3HashInsert(&pTab->pSchema->fkeyHash, z, sqlite3Strlen30(z), p);
92796       }
92797       if( pFKey->pNextTo ){
92798         pFKey->pNextTo->pPrevTo = pFKey->pPrevTo;
92799       }
92800     }
92801 
92802     /* EV: R-30323-21917 Each foreign key constraint in SQLite is
92803     ** classified as either immediate or deferred.
92804     */
92805     assert( pFKey->isDeferred==0 || pFKey->isDeferred==1 );
92806 
92807     /* Delete any triggers created to implement actions for this FK. */
92808 #ifndef SQLITE_OMIT_TRIGGER
92809     fkTriggerDelete(db, pFKey->apTrigger[0]);
92810     fkTriggerDelete(db, pFKey->apTrigger[1]);
92811 #endif
92812 
92813     pNext = pFKey->pNextFrom;
92814     sqlite3DbFree(db, pFKey);
92815   }
92816 }
92817 #endif /* ifndef SQLITE_OMIT_FOREIGN_KEY */
92818 
92819 /************** End of fkey.c ************************************************/
92820 /************** Begin file insert.c ******************************************/
92821 /*
92822 ** 2001 September 15
92823 **
92824 ** The author disclaims copyright to this source code.  In place of
92825 ** a legal notice, here is a blessing:
92826 **
92827 **    May you do good and not evil.
92828 **    May you find forgiveness for yourself and forgive others.
92829 **    May you share freely, never taking more than you give.
92830 **
92831 *************************************************************************
92832 ** This file contains C code routines that are called by the parser
92833 ** to handle INSERT statements in SQLite.
92834 */
92835 
92836 /*
92837 ** Generate code that will 
92838 **
92839 **   (1) acquire a lock for table pTab then
92840 **   (2) open pTab as cursor iCur.
92841 **
92842 ** If pTab is a WITHOUT ROWID table, then it is the PRIMARY KEY index
92843 ** for that table that is actually opened.
92844 */
92845 SQLITE_PRIVATE void sqlite3OpenTable(
92846   Parse *pParse,  /* Generate code into this VDBE */
92847   int iCur,       /* The cursor number of the table */
92848   int iDb,        /* The database index in sqlite3.aDb[] */
92849   Table *pTab,    /* The table to be opened */
92850   int opcode      /* OP_OpenRead or OP_OpenWrite */
92851 ){
92852   Vdbe *v;
92853   assert( !IsVirtual(pTab) );
92854   v = sqlite3GetVdbe(pParse);
92855   assert( opcode==OP_OpenWrite || opcode==OP_OpenRead );
92856   sqlite3TableLock(pParse, iDb, pTab->tnum, 
92857                    (opcode==OP_OpenWrite)?1:0, pTab->zName);
92858   if( HasRowid(pTab) ){
92859     sqlite3VdbeAddOp4Int(v, opcode, iCur, pTab->tnum, iDb, pTab->nCol);
92860     VdbeComment((v, "%s", pTab->zName));
92861   }else{
92862     Index *pPk = sqlite3PrimaryKeyIndex(pTab);
92863     assert( pPk!=0 );
92864     assert( pPk->tnum=pTab->tnum );
92865     sqlite3VdbeAddOp3(v, opcode, iCur, pPk->tnum, iDb);
92866     sqlite3VdbeSetP4KeyInfo(pParse, pPk);
92867     VdbeComment((v, "%s", pTab->zName));
92868   }
92869 }
92870 
92871 /*
92872 ** Return a pointer to the column affinity string associated with index
92873 ** pIdx. A column affinity string has one character for each column in 
92874 ** the table, according to the affinity of the column:
92875 **
92876 **  Character      Column affinity
92877 **  ------------------------------
92878 **  'a'            TEXT
92879 **  'b'            NONE
92880 **  'c'            NUMERIC
92881 **  'd'            INTEGER
92882 **  'e'            REAL
92883 **
92884 ** An extra 'd' is appended to the end of the string to cover the
92885 ** rowid that appears as the last column in every index.
92886 **
92887 ** Memory for the buffer containing the column index affinity string
92888 ** is managed along with the rest of the Index structure. It will be
92889 ** released when sqlite3DeleteIndex() is called.
92890 */
92891 SQLITE_PRIVATE const char *sqlite3IndexAffinityStr(Vdbe *v, Index *pIdx){
92892   if( !pIdx->zColAff ){
92893     /* The first time a column affinity string for a particular index is
92894     ** required, it is allocated and populated here. It is then stored as
92895     ** a member of the Index structure for subsequent use.
92896     **
92897     ** The column affinity string will eventually be deleted by
92898     ** sqliteDeleteIndex() when the Index structure itself is cleaned
92899     ** up.
92900     */
92901     int n;
92902     Table *pTab = pIdx->pTable;
92903     sqlite3 *db = sqlite3VdbeDb(v);
92904     pIdx->zColAff = (char *)sqlite3DbMallocRaw(0, pIdx->nColumn+1);
92905     if( !pIdx->zColAff ){
92906       db->mallocFailed = 1;
92907       return 0;
92908     }
92909     for(n=0; n<pIdx->nColumn; n++){
92910       i16 x = pIdx->aiColumn[n];
92911       pIdx->zColAff[n] = x<0 ? SQLITE_AFF_INTEGER : pTab->aCol[x].affinity;
92912     }
92913     pIdx->zColAff[n] = 0;
92914   }
92915  
92916   return pIdx->zColAff;
92917 }
92918 
92919 /*
92920 ** Set P4 of the most recently inserted opcode to a column affinity
92921 ** string for table pTab. A column affinity string has one character
92922 ** for each column indexed by the index, according to the affinity of the
92923 ** column:
92924 **
92925 **  Character      Column affinity
92926 **  ------------------------------
92927 **  'a'            TEXT
92928 **  'b'            NONE
92929 **  'c'            NUMERIC
92930 **  'd'            INTEGER
92931 **  'e'            REAL
92932 */
92933 SQLITE_PRIVATE void sqlite3TableAffinityStr(Vdbe *v, Table *pTab){
92934   /* The first time a column affinity string for a particular table
92935   ** is required, it is allocated and populated here. It is then 
92936   ** stored as a member of the Table structure for subsequent use.
92937   **
92938   ** The column affinity string will eventually be deleted by
92939   ** sqlite3DeleteTable() when the Table structure itself is cleaned up.
92940   */
92941   if( !pTab->zColAff ){
92942     char *zColAff;
92943     int i;
92944     sqlite3 *db = sqlite3VdbeDb(v);
92945 
92946     zColAff = (char *)sqlite3DbMallocRaw(0, pTab->nCol+1);
92947     if( !zColAff ){
92948       db->mallocFailed = 1;
92949       return;
92950     }
92951 
92952     for(i=0; i<pTab->nCol; i++){
92953       zColAff[i] = pTab->aCol[i].affinity;
92954     }
92955     zColAff[pTab->nCol] = '\0';
92956 
92957     pTab->zColAff = zColAff;
92958   }
92959 
92960   sqlite3VdbeChangeP4(v, -1, pTab->zColAff, P4_TRANSIENT);
92961 }
92962 
92963 /*
92964 ** Return non-zero if the table pTab in database iDb or any of its indices
92965 ** have been opened at any point in the VDBE program beginning at location
92966 ** iStartAddr throught the end of the program.  This is used to see if 
92967 ** a statement of the form  "INSERT INTO <iDb, pTab> SELECT ..." can 
92968 ** run without using temporary table for the results of the SELECT. 
92969 */
92970 static int readsTable(Parse *p, int iStartAddr, int iDb, Table *pTab){
92971   Vdbe *v = sqlite3GetVdbe(p);
92972   int i;
92973   int iEnd = sqlite3VdbeCurrentAddr(v);
92974 #ifndef SQLITE_OMIT_VIRTUALTABLE
92975   VTable *pVTab = IsVirtual(pTab) ? sqlite3GetVTable(p->db, pTab) : 0;
92976 #endif
92977 
92978   for(i=iStartAddr; i<iEnd; i++){
92979     VdbeOp *pOp = sqlite3VdbeGetOp(v, i);
92980     assert( pOp!=0 );
92981     if( pOp->opcode==OP_OpenRead && pOp->p3==iDb ){
92982       Index *pIndex;
92983       int tnum = pOp->p2;
92984       if( tnum==pTab->tnum ){
92985         return 1;
92986       }
92987       for(pIndex=pTab->pIndex; pIndex; pIndex=pIndex->pNext){
92988         if( tnum==pIndex->tnum ){
92989           return 1;
92990         }
92991       }
92992     }
92993 #ifndef SQLITE_OMIT_VIRTUALTABLE
92994     if( pOp->opcode==OP_VOpen && pOp->p4.pVtab==pVTab ){
92995       assert( pOp->p4.pVtab!=0 );
92996       assert( pOp->p4type==P4_VTAB );
92997       return 1;
92998     }
92999 #endif
93000   }
93001   return 0;
93002 }
93003 
93004 #ifndef SQLITE_OMIT_AUTOINCREMENT
93005 /*
93006 ** Locate or create an AutoincInfo structure associated with table pTab
93007 ** which is in database iDb.  Return the register number for the register
93008 ** that holds the maximum rowid.
93009 **
93010 ** There is at most one AutoincInfo structure per table even if the
93011 ** same table is autoincremented multiple times due to inserts within
93012 ** triggers.  A new AutoincInfo structure is created if this is the
93013 ** first use of table pTab.  On 2nd and subsequent uses, the original
93014 ** AutoincInfo structure is used.
93015 **
93016 ** Three memory locations are allocated:
93017 **
93018 **   (1)  Register to hold the name of the pTab table.
93019 **   (2)  Register to hold the maximum ROWID of pTab.
93020 **   (3)  Register to hold the rowid in sqlite_sequence of pTab
93021 **
93022 ** The 2nd register is the one that is returned.  That is all the
93023 ** insert routine needs to know about.
93024 */
93025 static int autoIncBegin(
93026   Parse *pParse,      /* Parsing context */
93027   int iDb,            /* Index of the database holding pTab */
93028   Table *pTab         /* The table we are writing to */
93029 ){
93030   int memId = 0;      /* Register holding maximum rowid */
93031   if( pTab->tabFlags & TF_Autoincrement ){
93032     Parse *pToplevel = sqlite3ParseToplevel(pParse);
93033     AutoincInfo *pInfo;
93034 
93035     pInfo = pToplevel->pAinc;
93036     while( pInfo && pInfo->pTab!=pTab ){ pInfo = pInfo->pNext; }
93037     if( pInfo==0 ){
93038       pInfo = sqlite3DbMallocRaw(pParse->db, sizeof(*pInfo));
93039       if( pInfo==0 ) return 0;
93040       pInfo->pNext = pToplevel->pAinc;
93041       pToplevel->pAinc = pInfo;
93042       pInfo->pTab = pTab;
93043       pInfo->iDb = iDb;
93044       pToplevel->nMem++;                  /* Register to hold name of table */
93045       pInfo->regCtr = ++pToplevel->nMem;  /* Max rowid register */
93046       pToplevel->nMem++;                  /* Rowid in sqlite_sequence */
93047     }
93048     memId = pInfo->regCtr;
93049   }
93050   return memId;
93051 }
93052 
93053 /*
93054 ** This routine generates code that will initialize all of the
93055 ** register used by the autoincrement tracker.  
93056 */
93057 SQLITE_PRIVATE void sqlite3AutoincrementBegin(Parse *pParse){
93058   AutoincInfo *p;            /* Information about an AUTOINCREMENT */
93059   sqlite3 *db = pParse->db;  /* The database connection */
93060   Db *pDb;                   /* Database only autoinc table */
93061   int memId;                 /* Register holding max rowid */
93062   int addr;                  /* A VDBE address */
93063   Vdbe *v = pParse->pVdbe;   /* VDBE under construction */
93064 
93065   /* This routine is never called during trigger-generation.  It is
93066   ** only called from the top-level */
93067   assert( pParse->pTriggerTab==0 );
93068   assert( pParse==sqlite3ParseToplevel(pParse) );
93069 
93070   assert( v );   /* We failed long ago if this is not so */
93071   for(p = pParse->pAinc; p; p = p->pNext){
93072     pDb = &db->aDb[p->iDb];
93073     memId = p->regCtr;
93074     assert( sqlite3SchemaMutexHeld(db, 0, pDb->pSchema) );
93075     sqlite3OpenTable(pParse, 0, p->iDb, pDb->pSchema->pSeqTab, OP_OpenRead);
93076     sqlite3VdbeAddOp3(v, OP_Null, 0, memId, memId+1);
93077     addr = sqlite3VdbeCurrentAddr(v);
93078     sqlite3VdbeAddOp4(v, OP_String8, 0, memId-1, 0, p->pTab->zName, 0);
93079     sqlite3VdbeAddOp2(v, OP_Rewind, 0, addr+9);
93080     sqlite3VdbeAddOp3(v, OP_Column, 0, 0, memId);
93081     sqlite3VdbeAddOp3(v, OP_Ne, memId-1, addr+7, memId);
93082     sqlite3VdbeChangeP5(v, SQLITE_JUMPIFNULL);
93083     sqlite3VdbeAddOp2(v, OP_Rowid, 0, memId+1);
93084     sqlite3VdbeAddOp3(v, OP_Column, 0, 1, memId);
93085     sqlite3VdbeAddOp2(v, OP_Goto, 0, addr+9);
93086     sqlite3VdbeAddOp2(v, OP_Next, 0, addr+2);
93087     sqlite3VdbeAddOp2(v, OP_Integer, 0, memId);
93088     sqlite3VdbeAddOp0(v, OP_Close);
93089   }
93090 }
93091 
93092 /*
93093 ** Update the maximum rowid for an autoincrement calculation.
93094 **
93095 ** This routine should be called when the top of the stack holds a
93096 ** new rowid that is about to be inserted.  If that new rowid is
93097 ** larger than the maximum rowid in the memId memory cell, then the
93098 ** memory cell is updated.  The stack is unchanged.
93099 */
93100 static void autoIncStep(Parse *pParse, int memId, int regRowid){
93101   if( memId>0 ){
93102     sqlite3VdbeAddOp2(pParse->pVdbe, OP_MemMax, memId, regRowid);
93103   }
93104 }
93105 
93106 /*
93107 ** This routine generates the code needed to write autoincrement
93108 ** maximum rowid values back into the sqlite_sequence register.
93109 ** Every statement that might do an INSERT into an autoincrement
93110 ** table (either directly or through triggers) needs to call this
93111 ** routine just before the "exit" code.
93112 */
93113 SQLITE_PRIVATE void sqlite3AutoincrementEnd(Parse *pParse){
93114   AutoincInfo *p;
93115   Vdbe *v = pParse->pVdbe;
93116   sqlite3 *db = pParse->db;
93117 
93118   assert( v );
93119   for(p = pParse->pAinc; p; p = p->pNext){
93120     Db *pDb = &db->aDb[p->iDb];
93121     int j1, j2, j3, j4, j5;
93122     int iRec;
93123     int memId = p->regCtr;
93124 
93125     iRec = sqlite3GetTempReg(pParse);
93126     assert( sqlite3SchemaMutexHeld(db, 0, pDb->pSchema) );
93127     sqlite3OpenTable(pParse, 0, p->iDb, pDb->pSchema->pSeqTab, OP_OpenWrite);
93128     j1 = sqlite3VdbeAddOp1(v, OP_NotNull, memId+1);
93129     j2 = sqlite3VdbeAddOp0(v, OP_Rewind);
93130     j3 = sqlite3VdbeAddOp3(v, OP_Column, 0, 0, iRec);
93131     j4 = sqlite3VdbeAddOp3(v, OP_Eq, memId-1, 0, iRec);
93132     sqlite3VdbeAddOp2(v, OP_Next, 0, j3);
93133     sqlite3VdbeJumpHere(v, j2);
93134     sqlite3VdbeAddOp2(v, OP_NewRowid, 0, memId+1);
93135     j5 = sqlite3VdbeAddOp0(v, OP_Goto);
93136     sqlite3VdbeJumpHere(v, j4);
93137     sqlite3VdbeAddOp2(v, OP_Rowid, 0, memId+1);
93138     sqlite3VdbeJumpHere(v, j1);
93139     sqlite3VdbeJumpHere(v, j5);
93140     sqlite3VdbeAddOp3(v, OP_MakeRecord, memId-1, 2, iRec);
93141     sqlite3VdbeAddOp3(v, OP_Insert, 0, iRec, memId+1);
93142     sqlite3VdbeChangeP5(v, OPFLAG_APPEND);
93143     sqlite3VdbeAddOp0(v, OP_Close);
93144     sqlite3ReleaseTempReg(pParse, iRec);
93145   }
93146 }
93147 #else
93148 /*
93149 ** If SQLITE_OMIT_AUTOINCREMENT is defined, then the three routines
93150 ** above are all no-ops
93151 */
93152 # define autoIncBegin(A,B,C) (0)
93153 # define autoIncStep(A,B,C)
93154 #endif /* SQLITE_OMIT_AUTOINCREMENT */
93155 
93156 
93157 /*
93158 ** Generate code for a co-routine that will evaluate a subquery one
93159 ** row at a time.
93160 **
93161 ** The pSelect parameter is the subquery that the co-routine will evaluation.
93162 ** Information about the location of co-routine and the registers it will use
93163 ** is returned by filling in the pDest object.
93164 **
93165 ** Registers are allocated as follows:
93166 **
93167 **   pDest->iSDParm      The register holding the next entry-point of the
93168 **                       co-routine.  Run the co-routine to its next breakpoint
93169 **                       by calling "OP_Yield $X" where $X is pDest->iSDParm.
93170 **
93171 **   pDest->iSDParm+1    The register holding the "completed" flag for the
93172 **                       co-routine. This register is 0 if the previous Yield
93173 **                       generated a new result row, or 1 if the subquery
93174 **                       has completed.  If the Yield is called again
93175 **                       after this register becomes 1, then the VDBE will
93176 **                       halt with an SQLITE_INTERNAL error.
93177 **
93178 **   pDest->iSdst        First result register.
93179 **
93180 **   pDest->nSdst        Number of result registers.
93181 **
93182 ** This routine handles all of the register allocation and fills in the
93183 ** pDest structure appropriately.
93184 **
93185 ** Here is a schematic of the generated code assuming that X is the 
93186 ** co-routine entry-point register reg[pDest->iSDParm], that EOF is the
93187 ** completed flag reg[pDest->iSDParm+1], and R and S are the range of
93188 ** registers that hold the result set, reg[pDest->iSdst] through
93189 ** reg[pDest->iSdst+pDest->nSdst-1]:
93190 **
93191 **         X <- A
93192 **         EOF <- 0
93193 **         goto B
93194 **      A: setup for the SELECT
93195 **         loop rows in the SELECT
93196 **           load results into registers R..S
93197 **           yield X
93198 **         end loop
93199 **         cleanup after the SELECT
93200 **         EOF <- 1
93201 **         yield X
93202 **         halt-error
93203 **      B:
93204 **
93205 ** To use this subroutine, the caller generates code as follows:
93206 **
93207 **         [ Co-routine generated by this subroutine, shown above ]
93208 **      S: yield X
93209 **         if EOF goto E
93210 **         if skip this row, goto C
93211 **         if terminate loop, goto E
93212 **         deal with this row
93213 **      C: goto S
93214 **      E:
93215 */
93216 SQLITE_PRIVATE int sqlite3CodeCoroutine(Parse *pParse, Select *pSelect, SelectDest *pDest){
93217   int regYield;       /* Register holding co-routine entry-point */
93218   int regEof;         /* Register holding co-routine completion flag */
93219   int addrTop;        /* Top of the co-routine */
93220   int j1;             /* Jump instruction */
93221   int rc;             /* Result code */
93222   Vdbe *v;            /* VDBE under construction */
93223 
93224   regYield = ++pParse->nMem;
93225   regEof = ++pParse->nMem;
93226   v = sqlite3GetVdbe(pParse);
93227   addrTop = sqlite3VdbeCurrentAddr(v);
93228   sqlite3VdbeAddOp2(v, OP_Integer, addrTop+2, regYield); /* X <- A */
93229   VdbeComment((v, "Co-routine entry point"));
93230   sqlite3VdbeAddOp2(v, OP_Integer, 0, regEof);           /* EOF <- 0 */
93231   VdbeComment((v, "Co-routine completion flag"));
93232   sqlite3SelectDestInit(pDest, SRT_Coroutine, regYield);
93233   j1 = sqlite3VdbeAddOp2(v, OP_Goto, 0, 0);
93234   rc = sqlite3Select(pParse, pSelect, pDest);
93235   assert( pParse->nErr==0 || rc );
93236   if( pParse->db->mallocFailed && rc==SQLITE_OK ) rc = SQLITE_NOMEM;
93237   if( rc ) return rc;
93238   sqlite3VdbeAddOp2(v, OP_Integer, 1, regEof);            /* EOF <- 1 */
93239   sqlite3VdbeAddOp1(v, OP_Yield, regYield);   /* yield X */
93240   sqlite3VdbeAddOp2(v, OP_Halt, SQLITE_INTERNAL, OE_Abort);
93241   VdbeComment((v, "End of coroutine"));
93242   sqlite3VdbeJumpHere(v, j1);                             /* label B: */
93243   return rc;
93244 }
93245 
93246 
93247 
93248 /* Forward declaration */
93249 static int xferOptimization(
93250   Parse *pParse,        /* Parser context */
93251   Table *pDest,         /* The table we are inserting into */
93252   Select *pSelect,      /* A SELECT statement to use as the data source */
93253   int onError,          /* How to handle constraint errors */
93254   int iDbDest           /* The database of pDest */
93255 );
93256 
93257 /*
93258 ** This routine is called to handle SQL of the following forms:
93259 **
93260 **    insert into TABLE (IDLIST) values(EXPRLIST)
93261 **    insert into TABLE (IDLIST) select
93262 **
93263 ** The IDLIST following the table name is always optional.  If omitted,
93264 ** then a list of all columns for the table is substituted.  The IDLIST
93265 ** appears in the pColumn parameter.  pColumn is NULL if IDLIST is omitted.
93266 **
93267 ** The pList parameter holds EXPRLIST in the first form of the INSERT
93268 ** statement above, and pSelect is NULL.  For the second form, pList is
93269 ** NULL and pSelect is a pointer to the select statement used to generate
93270 ** data for the insert.
93271 **
93272 ** The code generated follows one of four templates.  For a simple
93273 ** insert with data coming from a VALUES clause, the code executes
93274 ** once straight down through.  Pseudo-code follows (we call this
93275 ** the "1st template"):
93276 **
93277 **         open write cursor to <table> and its indices
93278 **         put VALUES clause expressions into registers
93279 **         write the resulting record into <table>
93280 **         cleanup
93281 **
93282 ** The three remaining templates assume the statement is of the form
93283 **
93284 **   INSERT INTO <table> SELECT ...
93285 **
93286 ** If the SELECT clause is of the restricted form "SELECT * FROM <table2>" -
93287 ** in other words if the SELECT pulls all columns from a single table
93288 ** and there is no WHERE or LIMIT or GROUP BY or ORDER BY clauses, and
93289 ** if <table2> and <table1> are distinct tables but have identical
93290 ** schemas, including all the same indices, then a special optimization
93291 ** is invoked that copies raw records from <table2> over to <table1>.
93292 ** See the xferOptimization() function for the implementation of this
93293 ** template.  This is the 2nd template.
93294 **
93295 **         open a write cursor to <table>
93296 **         open read cursor on <table2>
93297 **         transfer all records in <table2> over to <table>
93298 **         close cursors
93299 **         foreach index on <table>
93300 **           open a write cursor on the <table> index
93301 **           open a read cursor on the corresponding <table2> index
93302 **           transfer all records from the read to the write cursors
93303 **           close cursors
93304 **         end foreach
93305 **
93306 ** The 3rd template is for when the second template does not apply
93307 ** and the SELECT clause does not read from <table> at any time.
93308 ** The generated code follows this template:
93309 **
93310 **         EOF <- 0
93311 **         X <- A
93312 **         goto B
93313 **      A: setup for the SELECT
93314 **         loop over the rows in the SELECT
93315 **           load values into registers R..R+n
93316 **           yield X
93317 **         end loop
93318 **         cleanup after the SELECT
93319 **         EOF <- 1
93320 **         yield X
93321 **         goto A
93322 **      B: open write cursor to <table> and its indices
93323 **      C: yield X
93324 **         if EOF goto D
93325 **         insert the select result into <table> from R..R+n
93326 **         goto C
93327 **      D: cleanup
93328 **
93329 ** The 4th template is used if the insert statement takes its
93330 ** values from a SELECT but the data is being inserted into a table
93331 ** that is also read as part of the SELECT.  In the third form,
93332 ** we have to use a intermediate table to store the results of
93333 ** the select.  The template is like this:
93334 **
93335 **         EOF <- 0
93336 **         X <- A
93337 **         goto B
93338 **      A: setup for the SELECT
93339 **         loop over the tables in the SELECT
93340 **           load value into register R..R+n
93341 **           yield X
93342 **         end loop
93343 **         cleanup after the SELECT
93344 **         EOF <- 1
93345 **         yield X
93346 **         halt-error
93347 **      B: open temp table
93348 **      L: yield X
93349 **         if EOF goto M
93350 **         insert row from R..R+n into temp table
93351 **         goto L
93352 **      M: open write cursor to <table> and its indices
93353 **         rewind temp table
93354 **      C: loop over rows of intermediate table
93355 **           transfer values form intermediate table into <table>
93356 **         end loop
93357 **      D: cleanup
93358 */
93359 SQLITE_PRIVATE void sqlite3Insert(
93360   Parse *pParse,        /* Parser context */
93361   SrcList *pTabList,    /* Name of table into which we are inserting */
93362   ExprList *pList,      /* List of values to be inserted */
93363   Select *pSelect,      /* A SELECT statement to use as the data source */
93364   IdList *pColumn,      /* Column names corresponding to IDLIST. */
93365   int onError           /* How to handle constraint errors */
93366 ){
93367   sqlite3 *db;          /* The main database structure */
93368   Table *pTab;          /* The table to insert into.  aka TABLE */
93369   char *zTab;           /* Name of the table into which we are inserting */
93370   const char *zDb;      /* Name of the database holding this table */
93371   int i, j, idx;        /* Loop counters */
93372   Vdbe *v;              /* Generate code into this virtual machine */
93373   Index *pIdx;          /* For looping over indices of the table */
93374   int nColumn;          /* Number of columns in the data */
93375   int nHidden = 0;      /* Number of hidden columns if TABLE is virtual */
93376   int iDataCur = 0;     /* VDBE cursor that is the main data repository */
93377   int iIdxCur = 0;      /* First index cursor */
93378   int ipkColumn = -1;   /* Column that is the INTEGER PRIMARY KEY */
93379   int endOfLoop;        /* Label for the end of the insertion loop */
93380   int useTempTable = 0; /* Store SELECT results in intermediate table */
93381   int srcTab = 0;       /* Data comes from this temporary cursor if >=0 */
93382   int addrInsTop = 0;   /* Jump to label "D" */
93383   int addrCont = 0;     /* Top of insert loop. Label "C" in templates 3 and 4 */
93384   int addrSelect = 0;   /* Address of coroutine that implements the SELECT */
93385   SelectDest dest;      /* Destination for SELECT on rhs of INSERT */
93386   int iDb;              /* Index of database holding TABLE */
93387   Db *pDb;              /* The database containing table being inserted into */
93388   int appendFlag = 0;   /* True if the insert is likely to be an append */
93389   int withoutRowid;     /* 0 for normal table.  1 for WITHOUT ROWID table */
93390 
93391   /* Register allocations */
93392   int regFromSelect = 0;/* Base register for data coming from SELECT */
93393   int regAutoinc = 0;   /* Register holding the AUTOINCREMENT counter */
93394   int regRowCount = 0;  /* Memory cell used for the row counter */
93395   int regIns;           /* Block of regs holding rowid+data being inserted */
93396   int regRowid;         /* registers holding insert rowid */
93397   int regData;          /* register holding first column to insert */
93398   int regEof = 0;       /* Register recording end of SELECT data */
93399   int *aRegIdx = 0;     /* One register allocated to each index */
93400 
93401 #ifndef SQLITE_OMIT_TRIGGER
93402   int isView;                 /* True if attempting to insert into a view */
93403   Trigger *pTrigger;          /* List of triggers on pTab, if required */
93404   int tmask;                  /* Mask of trigger times */
93405 #endif
93406 
93407   db = pParse->db;
93408   memset(&dest, 0, sizeof(dest));
93409   if( pParse->nErr || db->mallocFailed ){
93410     goto insert_cleanup;
93411   }
93412 
93413   /* Locate the table into which we will be inserting new information.
93414   */
93415   assert( pTabList->nSrc==1 );
93416   zTab = pTabList->a[0].zName;
93417   if( NEVER(zTab==0) ) goto insert_cleanup;
93418   pTab = sqlite3SrcListLookup(pParse, pTabList);
93419   if( pTab==0 ){
93420     goto insert_cleanup;
93421   }
93422   iDb = sqlite3SchemaToIndex(db, pTab->pSchema);
93423   assert( iDb<db->nDb );
93424   pDb = &db->aDb[iDb];
93425   zDb = pDb->zName;
93426   if( sqlite3AuthCheck(pParse, SQLITE_INSERT, pTab->zName, 0, zDb) ){
93427     goto insert_cleanup;
93428   }
93429   withoutRowid = !HasRowid(pTab);
93430 
93431   /* Figure out if we have any triggers and if the table being
93432   ** inserted into is a view
93433   */
93434 #ifndef SQLITE_OMIT_TRIGGER
93435   pTrigger = sqlite3TriggersExist(pParse, pTab, TK_INSERT, 0, &tmask);
93436   isView = pTab->pSelect!=0;
93437 #else
93438 # define pTrigger 0
93439 # define tmask 0
93440 # define isView 0
93441 #endif
93442 #ifdef SQLITE_OMIT_VIEW
93443 # undef isView
93444 # define isView 0
93445 #endif
93446   assert( (pTrigger && tmask) || (pTrigger==0 && tmask==0) );
93447 
93448   /* If pTab is really a view, make sure it has been initialized.
93449   ** ViewGetColumnNames() is a no-op if pTab is not a view.
93450   */
93451   if( sqlite3ViewGetColumnNames(pParse, pTab) ){
93452     goto insert_cleanup;
93453   }
93454 
93455   /* Cannot insert into a read-only table.
93456   */
93457   if( sqlite3IsReadOnly(pParse, pTab, tmask) ){
93458     goto insert_cleanup;
93459   }
93460 
93461   /* Allocate a VDBE
93462   */
93463   v = sqlite3GetVdbe(pParse);
93464   if( v==0 ) goto insert_cleanup;
93465   if( pParse->nested==0 ) sqlite3VdbeCountChanges(v);
93466   sqlite3BeginWriteOperation(pParse, pSelect || pTrigger, iDb);
93467 
93468 #ifndef SQLITE_OMIT_XFER_OPT
93469   /* If the statement is of the form
93470   **
93471   **       INSERT INTO <table1> SELECT * FROM <table2>;
93472   **
93473   ** Then special optimizations can be applied that make the transfer
93474   ** very fast and which reduce fragmentation of indices.
93475   **
93476   ** This is the 2nd template.
93477   */
93478   if( pColumn==0 && xferOptimization(pParse, pTab, pSelect, onError, iDb) ){
93479     assert( !pTrigger );
93480     assert( pList==0 );
93481     goto insert_end;
93482   }
93483 #endif /* SQLITE_OMIT_XFER_OPT */
93484 
93485   /* If this is an AUTOINCREMENT table, look up the sequence number in the
93486   ** sqlite_sequence table and store it in memory cell regAutoinc.
93487   */
93488   regAutoinc = autoIncBegin(pParse, iDb, pTab);
93489 
93490   /* Figure out how many columns of data are supplied.  If the data
93491   ** is coming from a SELECT statement, then generate a co-routine that
93492   ** produces a single row of the SELECT on each invocation.  The
93493   ** co-routine is the common header to the 3rd and 4th templates.
93494   */
93495   if( pSelect ){
93496     /* Data is coming from a SELECT.  Generate a co-routine to run the SELECT */
93497     int rc = sqlite3CodeCoroutine(pParse, pSelect, &dest);
93498     if( rc ) goto insert_cleanup;
93499 
93500     regEof = dest.iSDParm + 1;
93501     regFromSelect = dest.iSdst;
93502     assert( pSelect->pEList );
93503     nColumn = pSelect->pEList->nExpr;
93504     assert( dest.nSdst==nColumn );
93505 
93506     /* Set useTempTable to TRUE if the result of the SELECT statement
93507     ** should be written into a temporary table (template 4).  Set to
93508     ** FALSE if each output row of the SELECT can be written directly into
93509     ** the destination table (template 3).
93510     **
93511     ** A temp table must be used if the table being updated is also one
93512     ** of the tables being read by the SELECT statement.  Also use a 
93513     ** temp table in the case of row triggers.
93514     */
93515     if( pTrigger || readsTable(pParse, addrSelect, iDb, pTab) ){
93516       useTempTable = 1;
93517     }
93518 
93519     if( useTempTable ){
93520       /* Invoke the coroutine to extract information from the SELECT
93521       ** and add it to a transient table srcTab.  The code generated
93522       ** here is from the 4th template:
93523       **
93524       **      B: open temp table
93525       **      L: yield X
93526       **         if EOF goto M
93527       **         insert row from R..R+n into temp table
93528       **         goto L
93529       **      M: ...
93530       */
93531       int regRec;          /* Register to hold packed record */
93532       int regTempRowid;    /* Register to hold temp table ROWID */
93533       int addrTop;         /* Label "L" */
93534       int addrIf;          /* Address of jump to M */
93535 
93536       srcTab = pParse->nTab++;
93537       regRec = sqlite3GetTempReg(pParse);
93538       regTempRowid = sqlite3GetTempReg(pParse);
93539       sqlite3VdbeAddOp2(v, OP_OpenEphemeral, srcTab, nColumn);
93540       addrTop = sqlite3VdbeAddOp1(v, OP_Yield, dest.iSDParm);
93541       addrIf = sqlite3VdbeAddOp1(v, OP_If, regEof);
93542       sqlite3VdbeAddOp3(v, OP_MakeRecord, regFromSelect, nColumn, regRec);
93543       sqlite3VdbeAddOp2(v, OP_NewRowid, srcTab, regTempRowid);
93544       sqlite3VdbeAddOp3(v, OP_Insert, srcTab, regRec, regTempRowid);
93545       sqlite3VdbeAddOp2(v, OP_Goto, 0, addrTop);
93546       sqlite3VdbeJumpHere(v, addrIf);
93547       sqlite3ReleaseTempReg(pParse, regRec);
93548       sqlite3ReleaseTempReg(pParse, regTempRowid);
93549     }
93550   }else{
93551     /* This is the case if the data for the INSERT is coming from a VALUES
93552     ** clause
93553     */
93554     NameContext sNC;
93555     memset(&sNC, 0, sizeof(sNC));
93556     sNC.pParse = pParse;
93557     srcTab = -1;
93558     assert( useTempTable==0 );
93559     nColumn = pList ? pList->nExpr : 0;
93560     for(i=0; i<nColumn; i++){
93561       if( sqlite3ResolveExprNames(&sNC, pList->a[i].pExpr) ){
93562         goto insert_cleanup;
93563       }
93564     }
93565   }
93566 
93567   /* Make sure the number of columns in the source data matches the number
93568   ** of columns to be inserted into the table.
93569   */
93570   if( IsVirtual(pTab) ){
93571     for(i=0; i<pTab->nCol; i++){
93572       nHidden += (IsHiddenColumn(&pTab->aCol[i]) ? 1 : 0);
93573     }
93574   }
93575   if( pColumn==0 && nColumn && nColumn!=(pTab->nCol-nHidden) ){
93576     sqlite3ErrorMsg(pParse, 
93577        "table %S has %d columns but %d values were supplied",
93578        pTabList, 0, pTab->nCol-nHidden, nColumn);
93579     goto insert_cleanup;
93580   }
93581   if( pColumn!=0 && nColumn!=pColumn->nId ){
93582     sqlite3ErrorMsg(pParse, "%d values for %d columns", nColumn, pColumn->nId);
93583     goto insert_cleanup;
93584   }
93585 
93586   /* If the INSERT statement included an IDLIST term, then make sure
93587   ** all elements of the IDLIST really are columns of the table and 
93588   ** remember the column indices.
93589   **
93590   ** If the table has an INTEGER PRIMARY KEY column and that column
93591   ** is named in the IDLIST, then record in the ipkColumn variable
93592   ** the index into IDLIST of the primary key column.  ipkColumn is
93593   ** the index of the primary key as it appears in IDLIST, not as
93594   ** is appears in the original table.  (The index of the INTEGER
93595   ** PRIMARY KEY in the original table is pTab->iPKey.)
93596   */
93597   if( pColumn ){
93598     for(i=0; i<pColumn->nId; i++){
93599       pColumn->a[i].idx = -1;
93600     }
93601     for(i=0; i<pColumn->nId; i++){
93602       for(j=0; j<pTab->nCol; j++){
93603         if( sqlite3StrICmp(pColumn->a[i].zName, pTab->aCol[j].zName)==0 ){
93604           pColumn->a[i].idx = j;
93605           if( j==pTab->iPKey ){
93606             ipkColumn = i;  assert( !withoutRowid );
93607           }
93608           break;
93609         }
93610       }
93611       if( j>=pTab->nCol ){
93612         if( sqlite3IsRowid(pColumn->a[i].zName) && !withoutRowid ){
93613           ipkColumn = i;
93614         }else{
93615           sqlite3ErrorMsg(pParse, "table %S has no column named %s",
93616               pTabList, 0, pColumn->a[i].zName);
93617           pParse->checkSchema = 1;
93618           goto insert_cleanup;
93619         }
93620       }
93621     }
93622   }
93623 
93624   /* If there is no IDLIST term but the table has an integer primary
93625   ** key, the set the ipkColumn variable to the integer primary key 
93626   ** column index in the original table definition.
93627   */
93628   if( pColumn==0 && nColumn>0 ){
93629     ipkColumn = pTab->iPKey;
93630   }
93631     
93632   /* Initialize the count of rows to be inserted
93633   */
93634   if( db->flags & SQLITE_CountRows ){
93635     regRowCount = ++pParse->nMem;
93636     sqlite3VdbeAddOp2(v, OP_Integer, 0, regRowCount);
93637   }
93638 
93639   /* If this is not a view, open the table and and all indices */
93640   if( !isView ){
93641     int nIdx;
93642     nIdx = sqlite3OpenTableAndIndices(pParse, pTab, OP_OpenWrite, -1, 0,
93643                                       &iDataCur, &iIdxCur);
93644     aRegIdx = sqlite3DbMallocRaw(db, sizeof(int)*(nIdx+1));
93645     if( aRegIdx==0 ){
93646       goto insert_cleanup;
93647     }
93648     for(i=0; i<nIdx; i++){
93649       aRegIdx[i] = ++pParse->nMem;
93650     }
93651   }
93652 
93653   /* This is the top of the main insertion loop */
93654   if( useTempTable ){
93655     /* This block codes the top of loop only.  The complete loop is the
93656     ** following pseudocode (template 4):
93657     **
93658     **         rewind temp table
93659     **      C: loop over rows of intermediate table
93660     **           transfer values form intermediate table into <table>
93661     **         end loop
93662     **      D: ...
93663     */
93664     addrInsTop = sqlite3VdbeAddOp1(v, OP_Rewind, srcTab);
93665     addrCont = sqlite3VdbeCurrentAddr(v);
93666   }else if( pSelect ){
93667     /* This block codes the top of loop only.  The complete loop is the
93668     ** following pseudocode (template 3):
93669     **
93670     **      C: yield X
93671     **         if EOF goto D
93672     **         insert the select result into <table> from R..R+n
93673     **         goto C
93674     **      D: ...
93675     */
93676     addrCont = sqlite3VdbeAddOp1(v, OP_Yield, dest.iSDParm);
93677     addrInsTop = sqlite3VdbeAddOp1(v, OP_If, regEof);
93678   }
93679 
93680   /* Allocate registers for holding the rowid of the new row,
93681   ** the content of the new row, and the assemblied row record.
93682   */
93683   regRowid = regIns = pParse->nMem+1;
93684   pParse->nMem += pTab->nCol + 1;
93685   if( IsVirtual(pTab) ){
93686     regRowid++;
93687     pParse->nMem++;
93688   }
93689   regData = regRowid+1;
93690 
93691   /* Run the BEFORE and INSTEAD OF triggers, if there are any
93692   */
93693   endOfLoop = sqlite3VdbeMakeLabel(v);
93694   if( tmask & TRIGGER_BEFORE ){
93695     int regCols = sqlite3GetTempRange(pParse, pTab->nCol+1);
93696 
93697     /* build the NEW.* reference row.  Note that if there is an INTEGER
93698     ** PRIMARY KEY into which a NULL is being inserted, that NULL will be
93699     ** translated into a unique ID for the row.  But on a BEFORE trigger,
93700     ** we do not know what the unique ID will be (because the insert has
93701     ** not happened yet) so we substitute a rowid of -1
93702     */
93703     if( ipkColumn<0 ){
93704       sqlite3VdbeAddOp2(v, OP_Integer, -1, regCols);
93705     }else{
93706       int j1;
93707       assert( !withoutRowid );
93708       if( useTempTable ){
93709         sqlite3VdbeAddOp3(v, OP_Column, srcTab, ipkColumn, regCols);
93710       }else{
93711         assert( pSelect==0 );  /* Otherwise useTempTable is true */
93712         sqlite3ExprCode(pParse, pList->a[ipkColumn].pExpr, regCols);
93713       }
93714       j1 = sqlite3VdbeAddOp1(v, OP_NotNull, regCols);
93715       sqlite3VdbeAddOp2(v, OP_Integer, -1, regCols);
93716       sqlite3VdbeJumpHere(v, j1);
93717       sqlite3VdbeAddOp1(v, OP_MustBeInt, regCols);
93718     }
93719 
93720     /* Cannot have triggers on a virtual table. If it were possible,
93721     ** this block would have to account for hidden column.
93722     */
93723     assert( !IsVirtual(pTab) );
93724 
93725     /* Create the new column data
93726     */
93727     for(i=0; i<pTab->nCol; i++){
93728       if( pColumn==0 ){
93729         j = i;
93730       }else{
93731         for(j=0; j<pColumn->nId; j++){
93732           if( pColumn->a[j].idx==i ) break;
93733         }
93734       }
93735       if( (!useTempTable && !pList) || (pColumn && j>=pColumn->nId) ){
93736         sqlite3ExprCode(pParse, pTab->aCol[i].pDflt, regCols+i+1);
93737       }else if( useTempTable ){
93738         sqlite3VdbeAddOp3(v, OP_Column, srcTab, j, regCols+i+1); 
93739       }else{
93740         assert( pSelect==0 ); /* Otherwise useTempTable is true */
93741         sqlite3ExprCodeAndCache(pParse, pList->a[j].pExpr, regCols+i+1);
93742       }
93743     }
93744 
93745     /* If this is an INSERT on a view with an INSTEAD OF INSERT trigger,
93746     ** do not attempt any conversions before assembling the record.
93747     ** If this is a real table, attempt conversions as required by the
93748     ** table column affinities.
93749     */
93750     if( !isView ){
93751       sqlite3VdbeAddOp2(v, OP_Affinity, regCols+1, pTab->nCol);
93752       sqlite3TableAffinityStr(v, pTab);
93753     }
93754 
93755     /* Fire BEFORE or INSTEAD OF triggers */
93756     sqlite3CodeRowTrigger(pParse, pTrigger, TK_INSERT, 0, TRIGGER_BEFORE, 
93757         pTab, regCols-pTab->nCol-1, onError, endOfLoop);
93758 
93759     sqlite3ReleaseTempRange(pParse, regCols, pTab->nCol+1);
93760   }
93761 
93762   /* Compute the content of the next row to insert into a range of
93763   ** registers beginning at regIns.
93764   */
93765   if( !isView ){
93766     if( IsVirtual(pTab) ){
93767       /* The row that the VUpdate opcode will delete: none */
93768       sqlite3VdbeAddOp2(v, OP_Null, 0, regIns);
93769     }
93770     if( ipkColumn>=0 ){
93771       if( useTempTable ){
93772         sqlite3VdbeAddOp3(v, OP_Column, srcTab, ipkColumn, regRowid);
93773       }else if( pSelect ){
93774         sqlite3VdbeAddOp2(v, OP_SCopy, regFromSelect+ipkColumn, regRowid);
93775       }else{
93776         VdbeOp *pOp;
93777         sqlite3ExprCode(pParse, pList->a[ipkColumn].pExpr, regRowid);
93778         pOp = sqlite3VdbeGetOp(v, -1);
93779         if( ALWAYS(pOp) && pOp->opcode==OP_Null && !IsVirtual(pTab) ){
93780           appendFlag = 1;
93781           pOp->opcode = OP_NewRowid;
93782           pOp->p1 = iDataCur;
93783           pOp->p2 = regRowid;
93784           pOp->p3 = regAutoinc;
93785         }
93786       }
93787       /* If the PRIMARY KEY expression is NULL, then use OP_NewRowid
93788       ** to generate a unique primary key value.
93789       */
93790       if( !appendFlag ){
93791         int j1;
93792         if( !IsVirtual(pTab) ){
93793           j1 = sqlite3VdbeAddOp1(v, OP_NotNull, regRowid);
93794           sqlite3VdbeAddOp3(v, OP_NewRowid, iDataCur, regRowid, regAutoinc);
93795           sqlite3VdbeJumpHere(v, j1);
93796         }else{
93797           j1 = sqlite3VdbeCurrentAddr(v);
93798           sqlite3VdbeAddOp2(v, OP_IsNull, regRowid, j1+2);
93799         }
93800         sqlite3VdbeAddOp1(v, OP_MustBeInt, regRowid);
93801       }
93802     }else if( IsVirtual(pTab) || withoutRowid ){
93803       sqlite3VdbeAddOp2(v, OP_Null, 0, regRowid);
93804     }else{
93805       sqlite3VdbeAddOp3(v, OP_NewRowid, iDataCur, regRowid, regAutoinc);
93806       appendFlag = 1;
93807     }
93808     autoIncStep(pParse, regAutoinc, regRowid);
93809 
93810     /* Compute data for all columns of the new entry, beginning
93811     ** with the first column.
93812     */
93813     nHidden = 0;
93814     for(i=0; i<pTab->nCol; i++){
93815       int iRegStore = regRowid+1+i;
93816       if( i==pTab->iPKey ){
93817         /* The value of the INTEGER PRIMARY KEY column is always a NULL.
93818         ** Whenever this column is read, the rowid will be substituted
93819         ** in its place.  Hence, fill this column with a NULL to avoid
93820         ** taking up data space with information that will never be used. */
93821         sqlite3VdbeAddOp2(v, OP_Null, 0, iRegStore);
93822         continue;
93823       }
93824       if( pColumn==0 ){
93825         if( IsHiddenColumn(&pTab->aCol[i]) ){
93826           assert( IsVirtual(pTab) );
93827           j = -1;
93828           nHidden++;
93829         }else{
93830           j = i - nHidden;
93831         }
93832       }else{
93833         for(j=0; j<pColumn->nId; j++){
93834           if( pColumn->a[j].idx==i ) break;
93835         }
93836       }
93837       if( j<0 || nColumn==0 || (pColumn && j>=pColumn->nId) ){
93838         sqlite3ExprCode(pParse, pTab->aCol[i].pDflt, iRegStore);
93839       }else if( useTempTable ){
93840         sqlite3VdbeAddOp3(v, OP_Column, srcTab, j, iRegStore); 
93841       }else if( pSelect ){
93842         sqlite3VdbeAddOp2(v, OP_SCopy, regFromSelect+j, iRegStore);
93843       }else{
93844         sqlite3ExprCode(pParse, pList->a[j].pExpr, iRegStore);
93845       }
93846     }
93847 
93848     /* Generate code to check constraints and generate index keys and
93849     ** do the insertion.
93850     */
93851 #ifndef SQLITE_OMIT_VIRTUALTABLE
93852     if( IsVirtual(pTab) ){
93853       const char *pVTab = (const char *)sqlite3GetVTable(db, pTab);
93854       sqlite3VtabMakeWritable(pParse, pTab);
93855       sqlite3VdbeAddOp4(v, OP_VUpdate, 1, pTab->nCol+2, regIns, pVTab, P4_VTAB);
93856       sqlite3VdbeChangeP5(v, onError==OE_Default ? OE_Abort : onError);
93857       sqlite3MayAbort(pParse);
93858     }else
93859 #endif
93860     {
93861       int isReplace;    /* Set to true if constraints may cause a replace */
93862       sqlite3GenerateConstraintChecks(pParse, pTab, aRegIdx, iDataCur, iIdxCur,
93863           regIns, 0, ipkColumn>=0, onError, endOfLoop, &isReplace
93864       );
93865       sqlite3FkCheck(pParse, pTab, 0, regIns, 0, 0);
93866       sqlite3CompleteInsertion(pParse, pTab, iDataCur, iIdxCur,
93867                                regIns, aRegIdx, 0, appendFlag, isReplace==0);
93868     }
93869   }
93870 
93871   /* Update the count of rows that are inserted
93872   */
93873   if( (db->flags & SQLITE_CountRows)!=0 ){
93874     sqlite3VdbeAddOp2(v, OP_AddImm, regRowCount, 1);
93875   }
93876 
93877   if( pTrigger ){
93878     /* Code AFTER triggers */
93879     sqlite3CodeRowTrigger(pParse, pTrigger, TK_INSERT, 0, TRIGGER_AFTER, 
93880         pTab, regData-2-pTab->nCol, onError, endOfLoop);
93881   }
93882 
93883   /* The bottom of the main insertion loop, if the data source
93884   ** is a SELECT statement.
93885   */
93886   sqlite3VdbeResolveLabel(v, endOfLoop);
93887   if( useTempTable ){
93888     sqlite3VdbeAddOp2(v, OP_Next, srcTab, addrCont);
93889     sqlite3VdbeJumpHere(v, addrInsTop);
93890     sqlite3VdbeAddOp1(v, OP_Close, srcTab);
93891   }else if( pSelect ){
93892     sqlite3VdbeAddOp2(v, OP_Goto, 0, addrCont);
93893     sqlite3VdbeJumpHere(v, addrInsTop);
93894   }
93895 
93896   if( !IsVirtual(pTab) && !isView ){
93897     /* Close all tables opened */
93898     if( iDataCur<iIdxCur ) sqlite3VdbeAddOp1(v, OP_Close, iDataCur);
93899     for(idx=0, pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext, idx++){
93900       sqlite3VdbeAddOp1(v, OP_Close, idx+iIdxCur);
93901     }
93902   }
93903 
93904 insert_end:
93905   /* Update the sqlite_sequence table by storing the content of the
93906   ** maximum rowid counter values recorded while inserting into
93907   ** autoincrement tables.
93908   */
93909   if( pParse->nested==0 && pParse->pTriggerTab==0 ){
93910     sqlite3AutoincrementEnd(pParse);
93911   }
93912 
93913   /*
93914   ** Return the number of rows inserted. If this routine is 
93915   ** generating code because of a call to sqlite3NestedParse(), do not
93916   ** invoke the callback function.
93917   */
93918   if( (db->flags&SQLITE_CountRows) && !pParse->nested && !pParse->pTriggerTab ){
93919     sqlite3VdbeAddOp2(v, OP_ResultRow, regRowCount, 1);
93920     sqlite3VdbeSetNumCols(v, 1);
93921     sqlite3VdbeSetColName(v, 0, COLNAME_NAME, "rows inserted", SQLITE_STATIC);
93922   }
93923 
93924 insert_cleanup:
93925   sqlite3SrcListDelete(db, pTabList);
93926   sqlite3ExprListDelete(db, pList);
93927   sqlite3SelectDelete(db, pSelect);
93928   sqlite3IdListDelete(db, pColumn);
93929   sqlite3DbFree(db, aRegIdx);
93930 }
93931 
93932 /* Make sure "isView" and other macros defined above are undefined. Otherwise
93933 ** thely may interfere with compilation of other functions in this file
93934 ** (or in another file, if this file becomes part of the amalgamation).  */
93935 #ifdef isView
93936  #undef isView
93937 #endif
93938 #ifdef pTrigger
93939  #undef pTrigger
93940 #endif
93941 #ifdef tmask
93942  #undef tmask
93943 #endif
93944 
93945 /*
93946 ** Generate code to do constraint checks prior to an INSERT or an UPDATE
93947 ** on table pTab.
93948 **
93949 ** The regNewData parameter is the first register in a range that contains
93950 ** the data to be inserted or the data after the update.  There will be
93951 ** pTab->nCol+1 registers in this range.  The first register (the one
93952 ** that regNewData points to) will contain the new rowid, or NULL in the
93953 ** case of a WITHOUT ROWID table.  The second register in the range will
93954 ** contain the content of the first table column.  The third register will
93955 ** contain the content of the second table column.  And so forth.
93956 **
93957 ** The regOldData parameter is similar to regNewData except that it contains
93958 ** the data prior to an UPDATE rather than afterwards.  regOldData is zero
93959 ** for an INSERT.  This routine can distinguish between UPDATE and INSERT by
93960 ** checking regOldData for zero.
93961 **
93962 ** For an UPDATE, the pkChng boolean is true if the true primary key (the
93963 ** rowid for a normal table or the PRIMARY KEY for a WITHOUT ROWID table)
93964 ** might be modified by the UPDATE.  If pkChng is false, then the key of
93965 ** the iDataCur content table is guaranteed to be unchanged by the UPDATE.
93966 **
93967 ** For an INSERT, the pkChng boolean indicates whether or not the rowid
93968 ** was explicitly specified as part of the INSERT statement.  If pkChng
93969 ** is zero, it means that the either rowid is computed automatically or
93970 ** that the table is a WITHOUT ROWID table and has no rowid.  On an INSERT,
93971 ** pkChng will only be true if the INSERT statement provides an integer
93972 ** value for either the rowid column or its INTEGER PRIMARY KEY alias.
93973 **
93974 ** The code generated by this routine will store new index entries into
93975 ** registers identified by aRegIdx[].  No index entry is created for
93976 ** indices where aRegIdx[i]==0.  The order of indices in aRegIdx[] is
93977 ** the same as the order of indices on the linked list of indices
93978 ** at pTab->pIndex.
93979 **
93980 ** The caller must have already opened writeable cursors on the main
93981 ** table and all applicable indices (that is to say, all indices for which
93982 ** aRegIdx[] is not zero).  iDataCur is the cursor for the main table when
93983 ** inserting or updating a rowid table, or the cursor for the PRIMARY KEY
93984 ** index when operating on a WITHOUT ROWID table.  iIdxCur is the cursor
93985 ** for the first index in the pTab->pIndex list.  Cursors for other indices
93986 ** are at iIdxCur+N for the N-th element of the pTab->pIndex list.
93987 **
93988 ** This routine also generates code to check constraints.  NOT NULL,
93989 ** CHECK, and UNIQUE constraints are all checked.  If a constraint fails,
93990 ** then the appropriate action is performed.  There are five possible
93991 ** actions: ROLLBACK, ABORT, FAIL, REPLACE, and IGNORE.
93992 **
93993 **  Constraint type  Action       What Happens
93994 **  ---------------  ----------   ----------------------------------------
93995 **  any              ROLLBACK     The current transaction is rolled back and
93996 **                                sqlite3_step() returns immediately with a
93997 **                                return code of SQLITE_CONSTRAINT.
93998 **
93999 **  any              ABORT        Back out changes from the current command
94000 **                                only (do not do a complete rollback) then
94001 **                                cause sqlite3_step() to return immediately
94002 **                                with SQLITE_CONSTRAINT.
94003 **
94004 **  any              FAIL         Sqlite3_step() returns immediately with a
94005 **                                return code of SQLITE_CONSTRAINT.  The
94006 **                                transaction is not rolled back and any
94007 **                                changes to prior rows are retained.
94008 **
94009 **  any              IGNORE       The attempt in insert or update the current
94010 **                                row is skipped, without throwing an error.
94011 **                                Processing continues with the next row.
94012 **                                (There is an immediate jump to ignoreDest.)
94013 **
94014 **  NOT NULL         REPLACE      The NULL value is replace by the default
94015 **                                value for that column.  If the default value
94016 **                                is NULL, the action is the same as ABORT.
94017 **
94018 **  UNIQUE           REPLACE      The other row that conflicts with the row
94019 **                                being inserted is removed.
94020 **
94021 **  CHECK            REPLACE      Illegal.  The results in an exception.
94022 **
94023 ** Which action to take is determined by the overrideError parameter.
94024 ** Or if overrideError==OE_Default, then the pParse->onError parameter
94025 ** is used.  Or if pParse->onError==OE_Default then the onError value
94026 ** for the constraint is used.
94027 */
94028 SQLITE_PRIVATE void sqlite3GenerateConstraintChecks(
94029   Parse *pParse,       /* The parser context */
94030   Table *pTab,         /* The table being inserted or updated */
94031   int *aRegIdx,        /* Use register aRegIdx[i] for index i.  0 for unused */
94032   int iDataCur,        /* Canonical data cursor (main table or PK index) */
94033   int iIdxCur,         /* First index cursor */
94034   int regNewData,      /* First register in a range holding values to insert */
94035   int regOldData,      /* Previous content.  0 for INSERTs */
94036   u8 pkChng,           /* Non-zero if the rowid or PRIMARY KEY changed */
94037   u8 overrideError,    /* Override onError to this if not OE_Default */
94038   int ignoreDest,      /* Jump to this label on an OE_Ignore resolution */
94039   int *pbMayReplace    /* OUT: Set to true if constraint may cause a replace */
94040 ){
94041   Vdbe *v;             /* VDBE under constrution */
94042   Index *pIdx;         /* Pointer to one of the indices */
94043   Index *pPk = 0;      /* The PRIMARY KEY index */
94044   sqlite3 *db;         /* Database connection */
94045   int i;               /* loop counter */
94046   int ix;              /* Index loop counter */
94047   int nCol;            /* Number of columns */
94048   int onError;         /* Conflict resolution strategy */
94049   int j1;              /* Addresss of jump instruction */
94050   int seenReplace = 0; /* True if REPLACE is used to resolve INT PK conflict */
94051   int nPkField;        /* Number of fields in PRIMARY KEY. 1 for ROWID tables */
94052   int ipkTop = 0;      /* Top of the rowid change constraint check */
94053   int ipkBottom = 0;   /* Bottom of the rowid change constraint check */
94054   u8 isUpdate;         /* True if this is an UPDATE operation */
94055 
94056   isUpdate = regOldData!=0;
94057   db = pParse->db;
94058   v = sqlite3GetVdbe(pParse);
94059   assert( v!=0 );
94060   assert( pTab->pSelect==0 );  /* This table is not a VIEW */
94061   nCol = pTab->nCol;
94062   
94063   /* pPk is the PRIMARY KEY index for WITHOUT ROWID tables and NULL for
94064   ** normal rowid tables.  nPkField is the number of key fields in the 
94065   ** pPk index or 1 for a rowid table.  In other words, nPkField is the
94066   ** number of fields in the true primary key of the table. */
94067   if( HasRowid(pTab) ){
94068     pPk = 0;
94069     nPkField = 1;
94070   }else{
94071     pPk = sqlite3PrimaryKeyIndex(pTab);
94072     nPkField = pPk->nKeyCol;
94073   }
94074 
94075   /* Record that this module has started */
94076   VdbeModuleComment((v, "BEGIN: GenCnstCks(%d,%d,%d,%d,%d)",
94077                      iDataCur, iIdxCur, regNewData, regOldData, pkChng));
94078 
94079   /* Test all NOT NULL constraints.
94080   */
94081   for(i=0; i<nCol; i++){
94082     if( i==pTab->iPKey ){
94083       continue;
94084     }
94085     onError = pTab->aCol[i].notNull;
94086     if( onError==OE_None ) continue;
94087     if( overrideError!=OE_Default ){
94088       onError = overrideError;
94089     }else if( onError==OE_Default ){
94090       onError = OE_Abort;
94091     }
94092     if( onError==OE_Replace && pTab->aCol[i].pDflt==0 ){
94093       onError = OE_Abort;
94094     }
94095     assert( onError==OE_Rollback || onError==OE_Abort || onError==OE_Fail
94096         || onError==OE_Ignore || onError==OE_Replace );
94097     switch( onError ){
94098       case OE_Abort:
94099         sqlite3MayAbort(pParse);
94100         /* Fall through */
94101       case OE_Rollback:
94102       case OE_Fail: {
94103         char *zMsg = sqlite3MPrintf(db, "%s.%s", pTab->zName,
94104                                     pTab->aCol[i].zName);
94105         sqlite3VdbeAddOp4(v, OP_HaltIfNull, SQLITE_CONSTRAINT_NOTNULL, onError,
94106                           regNewData+1+i, zMsg, P4_DYNAMIC);
94107         sqlite3VdbeChangeP5(v, P5_ConstraintNotNull);
94108         break;
94109       }
94110       case OE_Ignore: {
94111         sqlite3VdbeAddOp2(v, OP_IsNull, regNewData+1+i, ignoreDest);
94112         break;
94113       }
94114       default: {
94115         assert( onError==OE_Replace );
94116         j1 = sqlite3VdbeAddOp1(v, OP_NotNull, regNewData+1+i);
94117         sqlite3ExprCode(pParse, pTab->aCol[i].pDflt, regNewData+1+i);
94118         sqlite3VdbeJumpHere(v, j1);
94119         break;
94120       }
94121     }
94122   }
94123 
94124   /* Test all CHECK constraints
94125   */
94126 #ifndef SQLITE_OMIT_CHECK
94127   if( pTab->pCheck && (db->flags & SQLITE_IgnoreChecks)==0 ){
94128     ExprList *pCheck = pTab->pCheck;
94129     pParse->ckBase = regNewData+1;
94130     onError = overrideError!=OE_Default ? overrideError : OE_Abort;
94131     for(i=0; i<pCheck->nExpr; i++){
94132       int allOk = sqlite3VdbeMakeLabel(v);
94133       sqlite3ExprIfTrue(pParse, pCheck->a[i].pExpr, allOk, SQLITE_JUMPIFNULL);
94134       if( onError==OE_Ignore ){
94135         sqlite3VdbeAddOp2(v, OP_Goto, 0, ignoreDest);
94136       }else{
94137         char *zName = pCheck->a[i].zName;
94138         if( zName==0 ) zName = pTab->zName;
94139         if( onError==OE_Replace ) onError = OE_Abort; /* IMP: R-15569-63625 */
94140         sqlite3HaltConstraint(pParse, SQLITE_CONSTRAINT_CHECK,
94141                               onError, zName, P4_TRANSIENT,
94142                               P5_ConstraintCheck);
94143       }
94144       sqlite3VdbeResolveLabel(v, allOk);
94145     }
94146   }
94147 #endif /* !defined(SQLITE_OMIT_CHECK) */
94148 
94149   /* If rowid is changing, make sure the new rowid does not previously
94150   ** exist in the table.
94151   */
94152   if( pkChng && pPk==0 ){
94153     int addrRowidOk = sqlite3VdbeMakeLabel(v);
94154 
94155     /* Figure out what action to take in case of a rowid collision */
94156     onError = pTab->keyConf;
94157     if( overrideError!=OE_Default ){
94158       onError = overrideError;
94159     }else if( onError==OE_Default ){
94160       onError = OE_Abort;
94161     }
94162 
94163     if( isUpdate ){
94164       /* pkChng!=0 does not mean that the rowid has change, only that
94165       ** it might have changed.  Skip the conflict logic below if the rowid
94166       ** is unchanged. */
94167       sqlite3VdbeAddOp3(v, OP_Eq, regNewData, addrRowidOk, regOldData);
94168     }
94169 
94170     /* If the response to a rowid conflict is REPLACE but the response
94171     ** to some other UNIQUE constraint is FAIL or IGNORE, then we need
94172     ** to defer the running of the rowid conflict checking until after
94173     ** the UNIQUE constraints have run.
94174     */
94175     if( onError==OE_Replace && overrideError!=OE_Replace ){
94176       for(pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext){
94177         if( pIdx->onError==OE_Ignore || pIdx->onError==OE_Fail ){
94178           ipkTop = sqlite3VdbeAddOp0(v, OP_Goto);
94179           break;
94180         }
94181       }
94182     }
94183 
94184     /* Check to see if the new rowid already exists in the table.  Skip
94185     ** the following conflict logic if it does not. */
94186     sqlite3VdbeAddOp3(v, OP_NotExists, iDataCur, addrRowidOk, regNewData);
94187 
94188     /* Generate code that deals with a rowid collision */
94189     switch( onError ){
94190       default: {
94191         onError = OE_Abort;
94192         /* Fall thru into the next case */
94193       }
94194       case OE_Rollback:
94195       case OE_Abort:
94196       case OE_Fail: {
94197         sqlite3RowidConstraint(pParse, onError, pTab);
94198         break;
94199       }
94200       case OE_Replace: {
94201         /* If there are DELETE triggers on this table and the
94202         ** recursive-triggers flag is set, call GenerateRowDelete() to
94203         ** remove the conflicting row from the table. This will fire
94204         ** the triggers and remove both the table and index b-tree entries.
94205         **
94206         ** Otherwise, if there are no triggers or the recursive-triggers
94207         ** flag is not set, but the table has one or more indexes, call 
94208         ** GenerateRowIndexDelete(). This removes the index b-tree entries 
94209         ** only. The table b-tree entry will be replaced by the new entry 
94210         ** when it is inserted.  
94211         **
94212         ** If either GenerateRowDelete() or GenerateRowIndexDelete() is called,
94213         ** also invoke MultiWrite() to indicate that this VDBE may require
94214         ** statement rollback (if the statement is aborted after the delete
94215         ** takes place). Earlier versions called sqlite3MultiWrite() regardless,
94216         ** but being more selective here allows statements like:
94217         **
94218         **   REPLACE INTO t(rowid) VALUES($newrowid)
94219         **
94220         ** to run without a statement journal if there are no indexes on the
94221         ** table.
94222         */
94223         Trigger *pTrigger = 0;
94224         if( db->flags&SQLITE_RecTriggers ){
94225           pTrigger = sqlite3TriggersExist(pParse, pTab, TK_DELETE, 0, 0);
94226         }
94227         if( pTrigger || sqlite3FkRequired(pParse, pTab, 0, 0) ){
94228           sqlite3MultiWrite(pParse);
94229           sqlite3GenerateRowDelete(pParse, pTab, pTrigger, iDataCur, iIdxCur,
94230                                    regNewData, 1, 0, OE_Replace, 1);
94231         }else if( pTab->pIndex ){
94232           sqlite3MultiWrite(pParse);
94233           sqlite3GenerateRowIndexDelete(pParse, pTab, iDataCur, iIdxCur, 0);
94234         }
94235         seenReplace = 1;
94236         break;
94237       }
94238       case OE_Ignore: {
94239         /*assert( seenReplace==0 );*/
94240         sqlite3VdbeAddOp2(v, OP_Goto, 0, ignoreDest);
94241         break;
94242       }
94243     }
94244     sqlite3VdbeResolveLabel(v, addrRowidOk);
94245     if( ipkTop ){
94246       ipkBottom = sqlite3VdbeAddOp0(v, OP_Goto);
94247       sqlite3VdbeJumpHere(v, ipkTop);
94248     }
94249   }
94250 
94251   /* Test all UNIQUE constraints by creating entries for each UNIQUE
94252   ** index and making sure that duplicate entries do not already exist.
94253   ** Compute the revised record entries for indices as we go.
94254   **
94255   ** This loop also handles the case of the PRIMARY KEY index for a
94256   ** WITHOUT ROWID table.
94257   */
94258   for(ix=0, pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext, ix++){
94259     int regIdx;          /* Range of registers hold conent for pIdx */
94260     int regR;            /* Range of registers holding conflicting PK */
94261     int iThisCur;        /* Cursor for this UNIQUE index */
94262     int addrUniqueOk;    /* Jump here if the UNIQUE constraint is satisfied */
94263 
94264     if( aRegIdx[ix]==0 ) continue;  /* Skip indices that do not change */
94265     iThisCur = iIdxCur+ix;
94266     addrUniqueOk = sqlite3VdbeMakeLabel(v);
94267 
94268     /* Skip partial indices for which the WHERE clause is not true */
94269     if( pIdx->pPartIdxWhere ){
94270       sqlite3VdbeAddOp2(v, OP_Null, 0, aRegIdx[ix]);
94271       pParse->ckBase = regNewData+1;
94272       sqlite3ExprIfFalse(pParse, pIdx->pPartIdxWhere, addrUniqueOk,
94273                          SQLITE_JUMPIFNULL);
94274       pParse->ckBase = 0;
94275     }
94276 
94277     /* Create a record for this index entry as it should appear after
94278     ** the insert or update.  Store that record in the aRegIdx[ix] register
94279     */
94280     regIdx = sqlite3GetTempRange(pParse, pIdx->nColumn);
94281     for(i=0; i<pIdx->nColumn; i++){
94282       int iField = pIdx->aiColumn[i];
94283       int x;
94284       if( iField<0 || iField==pTab->iPKey ){
94285         x = regNewData;
94286       }else{
94287         x = iField + regNewData + 1;
94288       }
94289       sqlite3VdbeAddOp2(v, OP_SCopy, x, regIdx+i);
94290       VdbeComment((v, "%s", iField<0 ? "rowid" : pTab->aCol[iField].zName));
94291     }
94292     sqlite3VdbeAddOp3(v, OP_MakeRecord, regIdx, pIdx->nColumn, aRegIdx[ix]);
94293     sqlite3VdbeChangeP4(v, -1, sqlite3IndexAffinityStr(v, pIdx), P4_TRANSIENT);
94294     VdbeComment((v, "for %s", pIdx->zName));
94295     sqlite3ExprCacheAffinityChange(pParse, regIdx, pIdx->nColumn);
94296 
94297     /* In an UPDATE operation, if this index is the PRIMARY KEY index 
94298     ** of a WITHOUT ROWID table and there has been no change the
94299     ** primary key, then no collision is possible.  The collision detection
94300     ** logic below can all be skipped. */
94301     if( isUpdate && pPk==pIdx && pkChng==0 ){
94302       sqlite3VdbeResolveLabel(v, addrUniqueOk);
94303       continue;
94304     }
94305 
94306     /* Find out what action to take in case there is a uniqueness conflict */
94307     onError = pIdx->onError;
94308     if( onError==OE_None ){ 
94309       sqlite3ReleaseTempRange(pParse, regIdx, pIdx->nColumn);
94310       sqlite3VdbeResolveLabel(v, addrUniqueOk);
94311       continue;  /* pIdx is not a UNIQUE index */
94312     }
94313     if( overrideError!=OE_Default ){
94314       onError = overrideError;
94315     }else if( onError==OE_Default ){
94316       onError = OE_Abort;
94317     }
94318     
94319     /* Check to see if the new index entry will be unique */
94320     sqlite3VdbeAddOp4Int(v, OP_NoConflict, iThisCur, addrUniqueOk,
94321                          regIdx, pIdx->nKeyCol);
94322 
94323     /* Generate code to handle collisions */
94324     regR = (pIdx==pPk) ? regIdx : sqlite3GetTempRange(pParse, nPkField);
94325     if( HasRowid(pTab) ){
94326       sqlite3VdbeAddOp2(v, OP_IdxRowid, iThisCur, regR);
94327       /* Conflict only if the rowid of the existing index entry
94328       ** is different from old-rowid */
94329       if( isUpdate ){
94330         sqlite3VdbeAddOp3(v, OP_Eq, regR, addrUniqueOk, regOldData);
94331       }
94332     }else{
94333       int x;
94334       /* Extract the PRIMARY KEY from the end of the index entry and
94335       ** store it in registers regR..regR+nPk-1 */
94336       if( (isUpdate || onError==OE_Replace) && pIdx!=pPk ){
94337         for(i=0; i<pPk->nKeyCol; i++){
94338           x = sqlite3ColumnOfIndex(pIdx, pPk->aiColumn[i]);
94339           sqlite3VdbeAddOp3(v, OP_Column, iThisCur, x, regR+i);
94340           VdbeComment((v, "%s.%s", pTab->zName,
94341                        pTab->aCol[pPk->aiColumn[i]].zName));
94342         }
94343       }
94344       if( isUpdate ){
94345         /* If currently processing the PRIMARY KEY of a WITHOUT ROWID 
94346         ** table, only conflict if the new PRIMARY KEY values are actually
94347         ** different from the old.
94348         **
94349         ** For a UNIQUE index, only conflict if the PRIMARY KEY values
94350         ** of the matched index row are different from the original PRIMARY
94351         ** KEY values of this row before the update.  */
94352         int addrJump = sqlite3VdbeCurrentAddr(v)+pPk->nKeyCol;
94353         int op = OP_Ne;
94354         int regCmp = (pIdx->autoIndex==2 ? regIdx : regR);
94355 
94356         for(i=0; i<pPk->nKeyCol; i++){
94357           char *p4 = (char*)sqlite3LocateCollSeq(pParse, pPk->azColl[i]);
94358           x = pPk->aiColumn[i];
94359           if( i==(pPk->nKeyCol-1) ){
94360             addrJump = addrUniqueOk;
94361             op = OP_Eq;
94362           }
94363           sqlite3VdbeAddOp4(v, op, 
94364               regOldData+1+x, addrJump, regCmp+i, p4, P4_COLLSEQ
94365           );
94366         }
94367       }
94368     }
94369 
94370     /* Generate code that executes if the new index entry is not unique */
94371     assert( onError==OE_Rollback || onError==OE_Abort || onError==OE_Fail
94372         || onError==OE_Ignore || onError==OE_Replace );
94373     switch( onError ){
94374       case OE_Rollback:
94375       case OE_Abort:
94376       case OE_Fail: {
94377         sqlite3UniqueConstraint(pParse, onError, pIdx);
94378         break;
94379       }
94380       case OE_Ignore: {
94381         sqlite3VdbeAddOp2(v, OP_Goto, 0, ignoreDest);
94382         break;
94383       }
94384       default: {
94385         Trigger *pTrigger = 0;
94386         assert( onError==OE_Replace );
94387         sqlite3MultiWrite(pParse);
94388         if( db->flags&SQLITE_RecTriggers ){
94389           pTrigger = sqlite3TriggersExist(pParse, pTab, TK_DELETE, 0, 0);
94390         }
94391         sqlite3GenerateRowDelete(pParse, pTab, pTrigger, iDataCur, iIdxCur,
94392                                  regR, nPkField, 0, OE_Replace, pIdx==pPk);
94393         seenReplace = 1;
94394         break;
94395       }
94396     }
94397     sqlite3VdbeResolveLabel(v, addrUniqueOk);
94398     sqlite3ReleaseTempRange(pParse, regIdx, pIdx->nColumn);
94399     if( regR!=regIdx ) sqlite3ReleaseTempRange(pParse, regR, nPkField);
94400   }
94401   if( ipkTop ){
94402     sqlite3VdbeAddOp2(v, OP_Goto, 0, ipkTop+1);
94403     sqlite3VdbeJumpHere(v, ipkBottom);
94404   }
94405   
94406   *pbMayReplace = seenReplace;
94407   VdbeModuleComment((v, "END: GenCnstCks(%d)", seenReplace));
94408 }
94409 
94410 /*
94411 ** This routine generates code to finish the INSERT or UPDATE operation
94412 ** that was started by a prior call to sqlite3GenerateConstraintChecks.
94413 ** A consecutive range of registers starting at regNewData contains the
94414 ** rowid and the content to be inserted.
94415 **
94416 ** The arguments to this routine should be the same as the first six
94417 ** arguments to sqlite3GenerateConstraintChecks.
94418 */
94419 SQLITE_PRIVATE void sqlite3CompleteInsertion(
94420   Parse *pParse,      /* The parser context */
94421   Table *pTab,        /* the table into which we are inserting */
94422   int iDataCur,       /* Cursor of the canonical data source */
94423   int iIdxCur,        /* First index cursor */
94424   int regNewData,     /* Range of content */
94425   int *aRegIdx,       /* Register used by each index.  0 for unused indices */
94426   int isUpdate,       /* True for UPDATE, False for INSERT */
94427   int appendBias,     /* True if this is likely to be an append */
94428   int useSeekResult   /* True to set the USESEEKRESULT flag on OP_[Idx]Insert */
94429 ){
94430   Vdbe *v;            /* Prepared statements under construction */
94431   Index *pIdx;        /* An index being inserted or updated */
94432   u8 pik_flags;       /* flag values passed to the btree insert */
94433   int regData;        /* Content registers (after the rowid) */
94434   int regRec;         /* Register holding assemblied record for the table */
94435   int i;              /* Loop counter */
94436 
94437   v = sqlite3GetVdbe(pParse);
94438   assert( v!=0 );
94439   assert( pTab->pSelect==0 );  /* This table is not a VIEW */
94440   for(i=0, pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext, i++){
94441     if( aRegIdx[i]==0 ) continue;
94442     if( pIdx->pPartIdxWhere ){
94443       sqlite3VdbeAddOp2(v, OP_IsNull, aRegIdx[i], sqlite3VdbeCurrentAddr(v)+2);
94444     }
94445     sqlite3VdbeAddOp2(v, OP_IdxInsert, iIdxCur+i, aRegIdx[i]);
94446     pik_flags = 0;
94447     if( useSeekResult ) pik_flags = OPFLAG_USESEEKRESULT;
94448     if( pIdx->autoIndex==2 && !HasRowid(pTab) ){
94449       assert( pParse->nested==0 );
94450       pik_flags |= OPFLAG_NCHANGE;
94451     }
94452     if( pik_flags )  sqlite3VdbeChangeP5(v, pik_flags);
94453   }
94454   if( !HasRowid(pTab) ) return;
94455   regData = regNewData + 1;
94456   regRec = sqlite3GetTempReg(pParse);
94457   sqlite3VdbeAddOp3(v, OP_MakeRecord, regData, pTab->nCol, regRec);
94458   sqlite3TableAffinityStr(v, pTab);
94459   sqlite3ExprCacheAffinityChange(pParse, regData, pTab->nCol);
94460   if( pParse->nested ){
94461     pik_flags = 0;
94462   }else{
94463     pik_flags = OPFLAG_NCHANGE;
94464     pik_flags |= (isUpdate?OPFLAG_ISUPDATE:OPFLAG_LASTROWID);
94465   }
94466   if( appendBias ){
94467     pik_flags |= OPFLAG_APPEND;
94468   }
94469   if( useSeekResult ){
94470     pik_flags |= OPFLAG_USESEEKRESULT;
94471   }
94472   sqlite3VdbeAddOp3(v, OP_Insert, iDataCur, regRec, regNewData);
94473   if( !pParse->nested ){
94474     sqlite3VdbeChangeP4(v, -1, pTab->zName, P4_TRANSIENT);
94475   }
94476   sqlite3VdbeChangeP5(v, pik_flags);
94477 }
94478 
94479 /*
94480 ** Allocate cursors for the pTab table and all its indices and generate
94481 ** code to open and initialized those cursors.
94482 **
94483 ** The cursor for the object that contains the complete data (normally
94484 ** the table itself, but the PRIMARY KEY index in the case of a WITHOUT
94485 ** ROWID table) is returned in *piDataCur.  The first index cursor is
94486 ** returned in *piIdxCur.  The number of indices is returned.
94487 **
94488 ** Use iBase as the first cursor (either the *piDataCur for rowid tables
94489 ** or the first index for WITHOUT ROWID tables) if it is non-negative.
94490 ** If iBase is negative, then allocate the next available cursor.
94491 **
94492 ** For a rowid table, *piDataCur will be exactly one less than *piIdxCur.
94493 ** For a WITHOUT ROWID table, *piDataCur will be somewhere in the range
94494 ** of *piIdxCurs, depending on where the PRIMARY KEY index appears on the
94495 ** pTab->pIndex list.
94496 */
94497 SQLITE_PRIVATE int sqlite3OpenTableAndIndices(
94498   Parse *pParse,   /* Parsing context */
94499   Table *pTab,     /* Table to be opened */
94500   int op,          /* OP_OpenRead or OP_OpenWrite */
94501   int iBase,       /* Use this for the table cursor, if there is one */
94502   u8 *aToOpen,     /* If not NULL: boolean for each table and index */
94503   int *piDataCur,  /* Write the database source cursor number here */
94504   int *piIdxCur    /* Write the first index cursor number here */
94505 ){
94506   int i;
94507   int iDb;
94508   int iDataCur;
94509   Index *pIdx;
94510   Vdbe *v;
94511 
94512   assert( op==OP_OpenRead || op==OP_OpenWrite );
94513   if( IsVirtual(pTab) ){
94514     assert( aToOpen==0 );
94515     *piDataCur = 0;
94516     *piIdxCur = 1;
94517     return 0;
94518   }
94519   iDb = sqlite3SchemaToIndex(pParse->db, pTab->pSchema);
94520   v = sqlite3GetVdbe(pParse);
94521   assert( v!=0 );
94522   if( iBase<0 ) iBase = pParse->nTab;
94523   iDataCur = iBase++;
94524   if( piDataCur ) *piDataCur = iDataCur;
94525   if( HasRowid(pTab) && (aToOpen==0 || aToOpen[0]) ){
94526     sqlite3OpenTable(pParse, iDataCur, iDb, pTab, op);
94527   }else{
94528     sqlite3TableLock(pParse, iDb, pTab->tnum, op==OP_OpenWrite, pTab->zName);
94529   }
94530   if( piIdxCur ) *piIdxCur = iBase;
94531   for(i=0, pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext, i++){
94532     int iIdxCur = iBase++;
94533     assert( pIdx->pSchema==pTab->pSchema );
94534     if( pIdx->autoIndex==2 && !HasRowid(pTab) && piDataCur ){
94535       *piDataCur = iIdxCur;
94536     }
94537     if( aToOpen==0 || aToOpen[i+1] ){
94538       sqlite3VdbeAddOp3(v, op, iIdxCur, pIdx->tnum, iDb);
94539       sqlite3VdbeSetP4KeyInfo(pParse, pIdx);
94540       VdbeComment((v, "%s", pIdx->zName));
94541     }
94542   }
94543   if( iBase>pParse->nTab ) pParse->nTab = iBase;
94544   return i;
94545 }
94546 
94547 
94548 #ifdef SQLITE_TEST
94549 /*
94550 ** The following global variable is incremented whenever the
94551 ** transfer optimization is used.  This is used for testing
94552 ** purposes only - to make sure the transfer optimization really
94553 ** is happening when it is suppose to.
94554 */
94555 SQLITE_API int sqlite3_xferopt_count;
94556 #endif /* SQLITE_TEST */
94557 
94558 
94559 #ifndef SQLITE_OMIT_XFER_OPT
94560 /*
94561 ** Check to collation names to see if they are compatible.
94562 */
94563 static int xferCompatibleCollation(const char *z1, const char *z2){
94564   if( z1==0 ){
94565     return z2==0;
94566   }
94567   if( z2==0 ){
94568     return 0;
94569   }
94570   return sqlite3StrICmp(z1, z2)==0;
94571 }
94572 
94573 
94574 /*
94575 ** Check to see if index pSrc is compatible as a source of data
94576 ** for index pDest in an insert transfer optimization.  The rules
94577 ** for a compatible index:
94578 **
94579 **    *   The index is over the same set of columns
94580 **    *   The same DESC and ASC markings occurs on all columns
94581 **    *   The same onError processing (OE_Abort, OE_Ignore, etc)
94582 **    *   The same collating sequence on each column
94583 **    *   The index has the exact same WHERE clause
94584 */
94585 static int xferCompatibleIndex(Index *pDest, Index *pSrc){
94586   int i;
94587   assert( pDest && pSrc );
94588   assert( pDest->pTable!=pSrc->pTable );
94589   if( pDest->nKeyCol!=pSrc->nKeyCol ){
94590     return 0;   /* Different number of columns */
94591   }
94592   if( pDest->onError!=pSrc->onError ){
94593     return 0;   /* Different conflict resolution strategies */
94594   }
94595   for(i=0; i<pSrc->nKeyCol; i++){
94596     if( pSrc->aiColumn[i]!=pDest->aiColumn[i] ){
94597       return 0;   /* Different columns indexed */
94598     }
94599     if( pSrc->aSortOrder[i]!=pDest->aSortOrder[i] ){
94600       return 0;   /* Different sort orders */
94601     }
94602     if( !xferCompatibleCollation(pSrc->azColl[i],pDest->azColl[i]) ){
94603       return 0;   /* Different collating sequences */
94604     }
94605   }
94606   if( sqlite3ExprCompare(pSrc->pPartIdxWhere, pDest->pPartIdxWhere, -1) ){
94607     return 0;     /* Different WHERE clauses */
94608   }
94609 
94610   /* If no test above fails then the indices must be compatible */
94611   return 1;
94612 }
94613 
94614 /*
94615 ** Attempt the transfer optimization on INSERTs of the form
94616 **
94617 **     INSERT INTO tab1 SELECT * FROM tab2;
94618 **
94619 ** The xfer optimization transfers raw records from tab2 over to tab1.  
94620 ** Columns are not decoded and reassemblied, which greatly improves
94621 ** performance.  Raw index records are transferred in the same way.
94622 **
94623 ** The xfer optimization is only attempted if tab1 and tab2 are compatible.
94624 ** There are lots of rules for determining compatibility - see comments
94625 ** embedded in the code for details.
94626 **
94627 ** This routine returns TRUE if the optimization is guaranteed to be used.
94628 ** Sometimes the xfer optimization will only work if the destination table
94629 ** is empty - a factor that can only be determined at run-time.  In that
94630 ** case, this routine generates code for the xfer optimization but also
94631 ** does a test to see if the destination table is empty and jumps over the
94632 ** xfer optimization code if the test fails.  In that case, this routine
94633 ** returns FALSE so that the caller will know to go ahead and generate
94634 ** an unoptimized transfer.  This routine also returns FALSE if there
94635 ** is no chance that the xfer optimization can be applied.
94636 **
94637 ** This optimization is particularly useful at making VACUUM run faster.
94638 */
94639 static int xferOptimization(
94640   Parse *pParse,        /* Parser context */
94641   Table *pDest,         /* The table we are inserting into */
94642   Select *pSelect,      /* A SELECT statement to use as the data source */
94643   int onError,          /* How to handle constraint errors */
94644   int iDbDest           /* The database of pDest */
94645 ){
94646   ExprList *pEList;                /* The result set of the SELECT */
94647   Table *pSrc;                     /* The table in the FROM clause of SELECT */
94648   Index *pSrcIdx, *pDestIdx;       /* Source and destination indices */
94649   struct SrcList_item *pItem;      /* An element of pSelect->pSrc */
94650   int i;                           /* Loop counter */
94651   int iDbSrc;                      /* The database of pSrc */
94652   int iSrc, iDest;                 /* Cursors from source and destination */
94653   int addr1, addr2;                /* Loop addresses */
94654   int emptyDestTest = 0;           /* Address of test for empty pDest */
94655   int emptySrcTest = 0;            /* Address of test for empty pSrc */
94656   Vdbe *v;                         /* The VDBE we are building */
94657   int regAutoinc;                  /* Memory register used by AUTOINC */
94658   int destHasUniqueIdx = 0;        /* True if pDest has a UNIQUE index */
94659   int regData, regRowid;           /* Registers holding data and rowid */
94660 
94661   if( pSelect==0 ){
94662     return 0;   /* Must be of the form  INSERT INTO ... SELECT ... */
94663   }
94664   if( sqlite3TriggerList(pParse, pDest) ){
94665     return 0;   /* tab1 must not have triggers */
94666   }
94667 #ifndef SQLITE_OMIT_VIRTUALTABLE
94668   if( pDest->tabFlags & TF_Virtual ){
94669     return 0;   /* tab1 must not be a virtual table */
94670   }
94671 #endif
94672   if( onError==OE_Default ){
94673     if( pDest->iPKey>=0 ) onError = pDest->keyConf;
94674     if( onError==OE_Default ) onError = OE_Abort;
94675   }
94676   assert(pSelect->pSrc);   /* allocated even if there is no FROM clause */
94677   if( pSelect->pSrc->nSrc!=1 ){
94678     return 0;   /* FROM clause must have exactly one term */
94679   }
94680   if( pSelect->pSrc->a[0].pSelect ){
94681     return 0;   /* FROM clause cannot contain a subquery */
94682   }
94683   if( pSelect->pWhere ){
94684     return 0;   /* SELECT may not have a WHERE clause */
94685   }
94686   if( pSelect->pOrderBy ){
94687     return 0;   /* SELECT may not have an ORDER BY clause */
94688   }
94689   /* Do not need to test for a HAVING clause.  If HAVING is present but
94690   ** there is no ORDER BY, we will get an error. */
94691   if( pSelect->pGroupBy ){
94692     return 0;   /* SELECT may not have a GROUP BY clause */
94693   }
94694   if( pSelect->pLimit ){
94695     return 0;   /* SELECT may not have a LIMIT clause */
94696   }
94697   assert( pSelect->pOffset==0 );  /* Must be so if pLimit==0 */
94698   if( pSelect->pPrior ){
94699     return 0;   /* SELECT may not be a compound query */
94700   }
94701   if( pSelect->selFlags & SF_Distinct ){
94702     return 0;   /* SELECT may not be DISTINCT */
94703   }
94704   pEList = pSelect->pEList;
94705   assert( pEList!=0 );
94706   if( pEList->nExpr!=1 ){
94707     return 0;   /* The result set must have exactly one column */
94708   }
94709   assert( pEList->a[0].pExpr );
94710   if( pEList->a[0].pExpr->op!=TK_ALL ){
94711     return 0;   /* The result set must be the special operator "*" */
94712   }
94713 
94714   /* At this point we have established that the statement is of the
94715   ** correct syntactic form to participate in this optimization.  Now
94716   ** we have to check the semantics.
94717   */
94718   pItem = pSelect->pSrc->a;
94719   pSrc = sqlite3LocateTableItem(pParse, 0, pItem);
94720   if( pSrc==0 ){
94721     return 0;   /* FROM clause does not contain a real table */
94722   }
94723   if( pSrc==pDest ){
94724     return 0;   /* tab1 and tab2 may not be the same table */
94725   }
94726   if( HasRowid(pDest)!=HasRowid(pSrc) ){
94727     return 0;   /* source and destination must both be WITHOUT ROWID or not */
94728   }
94729 #ifndef SQLITE_OMIT_VIRTUALTABLE
94730   if( pSrc->tabFlags & TF_Virtual ){
94731     return 0;   /* tab2 must not be a virtual table */
94732   }
94733 #endif
94734   if( pSrc->pSelect ){
94735     return 0;   /* tab2 may not be a view */
94736   }
94737   if( pDest->nCol!=pSrc->nCol ){
94738     return 0;   /* Number of columns must be the same in tab1 and tab2 */
94739   }
94740   if( pDest->iPKey!=pSrc->iPKey ){
94741     return 0;   /* Both tables must have the same INTEGER PRIMARY KEY */
94742   }
94743   for(i=0; i<pDest->nCol; i++){
94744     if( pDest->aCol[i].affinity!=pSrc->aCol[i].affinity ){
94745       return 0;    /* Affinity must be the same on all columns */
94746     }
94747     if( !xferCompatibleCollation(pDest->aCol[i].zColl, pSrc->aCol[i].zColl) ){
94748       return 0;    /* Collating sequence must be the same on all columns */
94749     }
94750     if( pDest->aCol[i].notNull && !pSrc->aCol[i].notNull ){
94751       return 0;    /* tab2 must be NOT NULL if tab1 is */
94752     }
94753   }
94754   for(pDestIdx=pDest->pIndex; pDestIdx; pDestIdx=pDestIdx->pNext){
94755     if( pDestIdx->onError!=OE_None ){
94756       destHasUniqueIdx = 1;
94757     }
94758     for(pSrcIdx=pSrc->pIndex; pSrcIdx; pSrcIdx=pSrcIdx->pNext){
94759       if( xferCompatibleIndex(pDestIdx, pSrcIdx) ) break;
94760     }
94761     if( pSrcIdx==0 ){
94762       return 0;    /* pDestIdx has no corresponding index in pSrc */
94763     }
94764   }
94765 #ifndef SQLITE_OMIT_CHECK
94766   if( pDest->pCheck && sqlite3ExprListCompare(pSrc->pCheck,pDest->pCheck,-1) ){
94767     return 0;   /* Tables have different CHECK constraints.  Ticket #2252 */
94768   }
94769 #endif
94770 #ifndef SQLITE_OMIT_FOREIGN_KEY
94771   /* Disallow the transfer optimization if the destination table constains
94772   ** any foreign key constraints.  This is more restrictive than necessary.
94773   ** But the main beneficiary of the transfer optimization is the VACUUM 
94774   ** command, and the VACUUM command disables foreign key constraints.  So
94775   ** the extra complication to make this rule less restrictive is probably
94776   ** not worth the effort.  Ticket [6284df89debdfa61db8073e062908af0c9b6118e]
94777   */
94778   if( (pParse->db->flags & SQLITE_ForeignKeys)!=0 && pDest->pFKey!=0 ){
94779     return 0;
94780   }
94781 #endif
94782   if( (pParse->db->flags & SQLITE_CountRows)!=0 ){
94783     return 0;  /* xfer opt does not play well with PRAGMA count_changes */
94784   }
94785 
94786   /* If we get this far, it means that the xfer optimization is at
94787   ** least a possibility, though it might only work if the destination
94788   ** table (tab1) is initially empty.
94789   */
94790 #ifdef SQLITE_TEST
94791   sqlite3_xferopt_count++;
94792 #endif
94793   iDbSrc = sqlite3SchemaToIndex(pParse->db, pSrc->pSchema);
94794   v = sqlite3GetVdbe(pParse);
94795   sqlite3CodeVerifySchema(pParse, iDbSrc);
94796   iSrc = pParse->nTab++;
94797   iDest = pParse->nTab++;
94798   regAutoinc = autoIncBegin(pParse, iDbDest, pDest);
94799   regData = sqlite3GetTempReg(pParse);
94800   regRowid = sqlite3GetTempReg(pParse);
94801   sqlite3OpenTable(pParse, iDest, iDbDest, pDest, OP_OpenWrite);
94802   assert( HasRowid(pDest) || destHasUniqueIdx );
94803   if( (pDest->iPKey<0 && pDest->pIndex!=0)          /* (1) */
94804    || destHasUniqueIdx                              /* (2) */
94805    || (onError!=OE_Abort && onError!=OE_Rollback)   /* (3) */
94806   ){
94807     /* In some circumstances, we are able to run the xfer optimization
94808     ** only if the destination table is initially empty.  This code makes
94809     ** that determination.  Conditions under which the destination must
94810     ** be empty:
94811     **
94812     ** (1) There is no INTEGER PRIMARY KEY but there are indices.
94813     **     (If the destination is not initially empty, the rowid fields
94814     **     of index entries might need to change.)
94815     **
94816     ** (2) The destination has a unique index.  (The xfer optimization 
94817     **     is unable to test uniqueness.)
94818     **
94819     ** (3) onError is something other than OE_Abort and OE_Rollback.
94820     */
94821     addr1 = sqlite3VdbeAddOp2(v, OP_Rewind, iDest, 0);
94822     emptyDestTest = sqlite3VdbeAddOp2(v, OP_Goto, 0, 0);
94823     sqlite3VdbeJumpHere(v, addr1);
94824   }
94825   if( HasRowid(pSrc) ){
94826     sqlite3OpenTable(pParse, iSrc, iDbSrc, pSrc, OP_OpenRead);
94827     emptySrcTest = sqlite3VdbeAddOp2(v, OP_Rewind, iSrc, 0);
94828     if( pDest->iPKey>=0 ){
94829       addr1 = sqlite3VdbeAddOp2(v, OP_Rowid, iSrc, regRowid);
94830       addr2 = sqlite3VdbeAddOp3(v, OP_NotExists, iDest, 0, regRowid);
94831       sqlite3RowidConstraint(pParse, onError, pDest);
94832       sqlite3VdbeJumpHere(v, addr2);
94833       autoIncStep(pParse, regAutoinc, regRowid);
94834     }else if( pDest->pIndex==0 ){
94835       addr1 = sqlite3VdbeAddOp2(v, OP_NewRowid, iDest, regRowid);
94836     }else{
94837       addr1 = sqlite3VdbeAddOp2(v, OP_Rowid, iSrc, regRowid);
94838       assert( (pDest->tabFlags & TF_Autoincrement)==0 );
94839     }
94840     sqlite3VdbeAddOp2(v, OP_RowData, iSrc, regData);
94841     sqlite3VdbeAddOp3(v, OP_Insert, iDest, regData, regRowid);
94842     sqlite3VdbeChangeP5(v, OPFLAG_NCHANGE|OPFLAG_LASTROWID|OPFLAG_APPEND);
94843     sqlite3VdbeChangeP4(v, -1, pDest->zName, 0);
94844     sqlite3VdbeAddOp2(v, OP_Next, iSrc, addr1);
94845     sqlite3VdbeAddOp2(v, OP_Close, iSrc, 0);
94846     sqlite3VdbeAddOp2(v, OP_Close, iDest, 0);
94847   }else{
94848     sqlite3TableLock(pParse, iDbDest, pDest->tnum, 1, pDest->zName);
94849     sqlite3TableLock(pParse, iDbSrc, pSrc->tnum, 0, pSrc->zName);
94850   }
94851   for(pDestIdx=pDest->pIndex; pDestIdx; pDestIdx=pDestIdx->pNext){
94852     for(pSrcIdx=pSrc->pIndex; ALWAYS(pSrcIdx); pSrcIdx=pSrcIdx->pNext){
94853       if( xferCompatibleIndex(pDestIdx, pSrcIdx) ) break;
94854     }
94855     assert( pSrcIdx );
94856     sqlite3VdbeAddOp3(v, OP_OpenRead, iSrc, pSrcIdx->tnum, iDbSrc);
94857     sqlite3VdbeSetP4KeyInfo(pParse, pSrcIdx);
94858     VdbeComment((v, "%s", pSrcIdx->zName));
94859     sqlite3VdbeAddOp3(v, OP_OpenWrite, iDest, pDestIdx->tnum, iDbDest);
94860     sqlite3VdbeSetP4KeyInfo(pParse, pDestIdx);
94861     sqlite3VdbeChangeP5(v, OPFLAG_BULKCSR);
94862     VdbeComment((v, "%s", pDestIdx->zName));
94863     addr1 = sqlite3VdbeAddOp2(v, OP_Rewind, iSrc, 0);
94864     sqlite3VdbeAddOp2(v, OP_RowKey, iSrc, regData);
94865     sqlite3VdbeAddOp3(v, OP_IdxInsert, iDest, regData, 1);
94866     sqlite3VdbeAddOp2(v, OP_Next, iSrc, addr1+1);
94867     sqlite3VdbeJumpHere(v, addr1);
94868     sqlite3VdbeAddOp2(v, OP_Close, iSrc, 0);
94869     sqlite3VdbeAddOp2(v, OP_Close, iDest, 0);
94870   }
94871   sqlite3VdbeJumpHere(v, emptySrcTest);
94872   sqlite3ReleaseTempReg(pParse, regRowid);
94873   sqlite3ReleaseTempReg(pParse, regData);
94874   if( emptyDestTest ){
94875     sqlite3VdbeAddOp2(v, OP_Halt, SQLITE_OK, 0);
94876     sqlite3VdbeJumpHere(v, emptyDestTest);
94877     sqlite3VdbeAddOp2(v, OP_Close, iDest, 0);
94878     return 0;
94879   }else{
94880     return 1;
94881   }
94882 }
94883 #endif /* SQLITE_OMIT_XFER_OPT */
94884 
94885 /************** End of insert.c **********************************************/
94886 /************** Begin file legacy.c ******************************************/
94887 /*
94888 ** 2001 September 15
94889 **
94890 ** The author disclaims copyright to this source code.  In place of
94891 ** a legal notice, here is a blessing:
94892 **
94893 **    May you do good and not evil.
94894 **    May you find forgiveness for yourself and forgive others.
94895 **    May you share freely, never taking more than you give.
94896 **
94897 *************************************************************************
94898 ** Main file for the SQLite library.  The routines in this file
94899 ** implement the programmer interface to the library.  Routines in
94900 ** other files are for internal use by SQLite and should not be
94901 ** accessed by users of the library.
94902 */
94903 
94904 
94905 /*
94906 ** Execute SQL code.  Return one of the SQLITE_ success/failure
94907 ** codes.  Also write an error message into memory obtained from
94908 ** malloc() and make *pzErrMsg point to that message.
94909 **
94910 ** If the SQL is a query, then for each row in the query result
94911 ** the xCallback() function is called.  pArg becomes the first
94912 ** argument to xCallback().  If xCallback=NULL then no callback
94913 ** is invoked, even for queries.
94914 */
94915 SQLITE_API int sqlite3_exec(
94916   sqlite3 *db,                /* The database on which the SQL executes */
94917   const char *zSql,           /* The SQL to be executed */
94918   sqlite3_callback xCallback, /* Invoke this callback routine */
94919   void *pArg,                 /* First argument to xCallback() */
94920   char **pzErrMsg             /* Write error messages here */
94921 ){
94922   int rc = SQLITE_OK;         /* Return code */
94923   const char *zLeftover;      /* Tail of unprocessed SQL */
94924   sqlite3_stmt *pStmt = 0;    /* The current SQL statement */
94925   char **azCols = 0;          /* Names of result columns */
94926   int callbackIsInit;         /* True if callback data is initialized */
94927 
94928   if( !sqlite3SafetyCheckOk(db) ) return SQLITE_MISUSE_BKPT;
94929   if( zSql==0 ) zSql = "";
94930 
94931   sqlite3_mutex_enter(db->mutex);
94932   sqlite3Error(db, SQLITE_OK, 0);
94933   while( rc==SQLITE_OK && zSql[0] ){
94934     int nCol;
94935     char **azVals = 0;
94936 
94937     pStmt = 0;
94938     rc = sqlite3_prepare_v2(db, zSql, -1, &pStmt, &zLeftover);
94939     assert( rc==SQLITE_OK || pStmt==0 );
94940     if( rc!=SQLITE_OK ){
94941       continue;
94942     }
94943     if( !pStmt ){
94944       /* this happens for a comment or white-space */
94945       zSql = zLeftover;
94946       continue;
94947     }
94948 
94949     callbackIsInit = 0;
94950     nCol = sqlite3_column_count(pStmt);
94951 
94952     while( 1 ){
94953       int i;
94954       rc = sqlite3_step(pStmt);
94955 
94956       /* Invoke the callback function if required */
94957       if( xCallback && (SQLITE_ROW==rc || 
94958           (SQLITE_DONE==rc && !callbackIsInit
94959                            && db->flags&SQLITE_NullCallback)) ){
94960         if( !callbackIsInit ){
94961           azCols = sqlite3DbMallocZero(db, 2*nCol*sizeof(const char*) + 1);
94962           if( azCols==0 ){
94963             goto exec_out;
94964           }
94965           for(i=0; i<nCol; i++){
94966             azCols[i] = (char *)sqlite3_column_name(pStmt, i);
94967             /* sqlite3VdbeSetColName() installs column names as UTF8
94968             ** strings so there is no way for sqlite3_column_name() to fail. */
94969             assert( azCols[i]!=0 );
94970           }
94971           callbackIsInit = 1;
94972         }
94973         if( rc==SQLITE_ROW ){
94974           azVals = &azCols[nCol];
94975           for(i=0; i<nCol; i++){
94976             azVals[i] = (char *)sqlite3_column_text(pStmt, i);
94977             if( !azVals[i] && sqlite3_column_type(pStmt, i)!=SQLITE_NULL ){
94978               db->mallocFailed = 1;
94979               goto exec_out;
94980             }
94981           }
94982         }
94983         if( xCallback(pArg, nCol, azVals, azCols) ){
94984           rc = SQLITE_ABORT;
94985           sqlite3VdbeFinalize((Vdbe *)pStmt);
94986           pStmt = 0;
94987           sqlite3Error(db, SQLITE_ABORT, 0);
94988           goto exec_out;
94989         }
94990       }
94991 
94992       if( rc!=SQLITE_ROW ){
94993         rc = sqlite3VdbeFinalize((Vdbe *)pStmt);
94994         pStmt = 0;
94995         zSql = zLeftover;
94996         while( sqlite3Isspace(zSql[0]) ) zSql++;
94997         break;
94998       }
94999     }
95000 
95001     sqlite3DbFree(db, azCols);
95002     azCols = 0;
95003   }
95004 
95005 exec_out:
95006   if( pStmt ) sqlite3VdbeFinalize((Vdbe *)pStmt);
95007   sqlite3DbFree(db, azCols);
95008 
95009   rc = sqlite3ApiExit(db, rc);
95010   if( rc!=SQLITE_OK && ALWAYS(rc==sqlite3_errcode(db)) && pzErrMsg ){
95011     int nErrMsg = 1 + sqlite3Strlen30(sqlite3_errmsg(db));
95012     *pzErrMsg = sqlite3Malloc(nErrMsg);
95013     if( *pzErrMsg ){
95014       memcpy(*pzErrMsg, sqlite3_errmsg(db), nErrMsg);
95015     }else{
95016       rc = SQLITE_NOMEM;
95017       sqlite3Error(db, SQLITE_NOMEM, 0);
95018     }
95019   }else if( pzErrMsg ){
95020     *pzErrMsg = 0;
95021   }
95022 
95023   assert( (rc&db->errMask)==rc );
95024   sqlite3_mutex_leave(db->mutex);
95025   return rc;
95026 }
95027 
95028 /************** End of legacy.c **********************************************/
95029 /************** Begin file loadext.c *****************************************/
95030 /*
95031 ** 2006 June 7
95032 **
95033 ** The author disclaims copyright to this source code.  In place of
95034 ** a legal notice, here is a blessing:
95035 **
95036 **    May you do good and not evil.
95037 **    May you find forgiveness for yourself and forgive others.
95038 **    May you share freely, never taking more than you give.
95039 **
95040 *************************************************************************
95041 ** This file contains code used to dynamically load extensions into
95042 ** the SQLite library.
95043 */
95044 
95045 #ifndef SQLITE_CORE
95046   #define SQLITE_CORE 1  /* Disable the API redefinition in sqlite3ext.h */
95047 #endif
95048 /************** Include sqlite3ext.h in the middle of loadext.c **************/
95049 /************** Begin file sqlite3ext.h **************************************/
95050 /*
95051 ** 2006 June 7
95052 **
95053 ** The author disclaims copyright to this source code.  In place of
95054 ** a legal notice, here is a blessing:
95055 **
95056 **    May you do good and not evil.
95057 **    May you find forgiveness for yourself and forgive others.
95058 **    May you share freely, never taking more than you give.
95059 **
95060 *************************************************************************
95061 ** This header file defines the SQLite interface for use by
95062 ** shared libraries that want to be imported as extensions into
95063 ** an SQLite instance.  Shared libraries that intend to be loaded
95064 ** as extensions by SQLite should #include this file instead of 
95065 ** sqlite3.h.
95066 */
95067 #ifndef _SQLITE3EXT_H_
95068 #define _SQLITE3EXT_H_
95069 
95070 typedef struct sqlite3_api_routines sqlite3_api_routines;
95071 
95072 /*
95073 ** The following structure holds pointers to all of the SQLite API
95074 ** routines.
95075 **
95076 ** WARNING:  In order to maintain backwards compatibility, add new
95077 ** interfaces to the end of this structure only.  If you insert new
95078 ** interfaces in the middle of this structure, then older different
95079 ** versions of SQLite will not be able to load each others' shared
95080 ** libraries!
95081 */
95082 struct sqlite3_api_routines {
95083   void * (*aggregate_context)(sqlite3_context*,int nBytes);
95084   int  (*aggregate_count)(sqlite3_context*);
95085   int  (*bind_blob)(sqlite3_stmt*,int,const void*,int n,void(*)(void*));
95086   int  (*bind_double)(sqlite3_stmt*,int,double);
95087   int  (*bind_int)(sqlite3_stmt*,int,int);
95088   int  (*bind_int64)(sqlite3_stmt*,int,sqlite_int64);
95089   int  (*bind_null)(sqlite3_stmt*,int);
95090   int  (*bind_parameter_count)(sqlite3_stmt*);
95091   int  (*bind_parameter_index)(sqlite3_stmt*,const char*zName);
95092   const char * (*bind_parameter_name)(sqlite3_stmt*,int);
95093   int  (*bind_text)(sqlite3_stmt*,int,const char*,int n,void(*)(void*));
95094   int  (*bind_text16)(sqlite3_stmt*,int,const void*,int,void(*)(void*));
95095   int  (*bind_value)(sqlite3_stmt*,int,const sqlite3_value*);
95096   int  (*busy_handler)(sqlite3*,int(*)(void*,int),void*);
95097   int  (*busy_timeout)(sqlite3*,int ms);
95098   int  (*changes)(sqlite3*);
95099   int  (*close)(sqlite3*);
95100   int  (*collation_needed)(sqlite3*,void*,void(*)(void*,sqlite3*,
95101                            int eTextRep,const char*));
95102   int  (*collation_needed16)(sqlite3*,void*,void(*)(void*,sqlite3*,
95103                              int eTextRep,const void*));
95104   const void * (*column_blob)(sqlite3_stmt*,int iCol);
95105   int  (*column_bytes)(sqlite3_stmt*,int iCol);
95106   int  (*column_bytes16)(sqlite3_stmt*,int iCol);
95107   int  (*column_count)(sqlite3_stmt*pStmt);
95108   const char * (*column_database_name)(sqlite3_stmt*,int);
95109   const void * (*column_database_name16)(sqlite3_stmt*,int);
95110   const char * (*column_decltype)(sqlite3_stmt*,int i);
95111   const void * (*column_decltype16)(sqlite3_stmt*,int);
95112   double  (*column_double)(sqlite3_stmt*,int iCol);
95113   int  (*column_int)(sqlite3_stmt*,int iCol);
95114   sqlite_int64  (*column_int64)(sqlite3_stmt*,int iCol);
95115   const char * (*column_name)(sqlite3_stmt*,int);
95116   const void * (*column_name16)(sqlite3_stmt*,int);
95117   const char * (*column_origin_name)(sqlite3_stmt*,int);
95118   const void * (*column_origin_name16)(sqlite3_stmt*,int);
95119   const char * (*column_table_name)(sqlite3_stmt*,int);
95120   const void * (*column_table_name16)(sqlite3_stmt*,int);
95121   const unsigned char * (*column_text)(sqlite3_stmt*,int iCol);
95122   const void * (*column_text16)(sqlite3_stmt*,int iCol);
95123   int  (*column_type)(sqlite3_stmt*,int iCol);
95124   sqlite3_value* (*column_value)(sqlite3_stmt*,int iCol);
95125   void * (*commit_hook)(sqlite3*,int(*)(void*),void*);
95126   int  (*complete)(const char*sql);
95127   int  (*complete16)(const void*sql);
95128   int  (*create_collation)(sqlite3*,const char*,int,void*,
95129                            int(*)(void*,int,const void*,int,const void*));
95130   int  (*create_collation16)(sqlite3*,const void*,int,void*,
95131                              int(*)(void*,int,const void*,int,const void*));
95132   int  (*create_function)(sqlite3*,const char*,int,int,void*,
95133                           void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
95134                           void (*xStep)(sqlite3_context*,int,sqlite3_value**),
95135                           void (*xFinal)(sqlite3_context*));
95136   int  (*create_function16)(sqlite3*,const void*,int,int,void*,
95137                             void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
95138                             void (*xStep)(sqlite3_context*,int,sqlite3_value**),
95139                             void (*xFinal)(sqlite3_context*));
95140   int (*create_module)(sqlite3*,const char*,const sqlite3_module*,void*);
95141   int  (*data_count)(sqlite3_stmt*pStmt);
95142   sqlite3 * (*db_handle)(sqlite3_stmt*);
95143   int (*declare_vtab)(sqlite3*,const char*);
95144   int  (*enable_shared_cache)(int);
95145   int  (*errcode)(sqlite3*db);
95146   const char * (*errmsg)(sqlite3*);
95147   const void * (*errmsg16)(sqlite3*);
95148   int  (*exec)(sqlite3*,const char*,sqlite3_callback,void*,char**);
95149   int  (*expired)(sqlite3_stmt*);
95150   int  (*finalize)(sqlite3_stmt*pStmt);
95151   void  (*free)(void*);
95152   void  (*free_table)(char**result);
95153   int  (*get_autocommit)(sqlite3*);
95154   void * (*get_auxdata)(sqlite3_context*,int);
95155   int  (*get_table)(sqlite3*,const char*,char***,int*,int*,char**);
95156   int  (*global_recover)(void);
95157   void  (*interruptx)(sqlite3*);
95158   sqlite_int64  (*last_insert_rowid)(sqlite3*);
95159   const char * (*libversion)(void);
95160   int  (*libversion_number)(void);
95161   void *(*malloc)(int);
95162   char * (*mprintf)(const char*,...);
95163   int  (*open)(const char*,sqlite3**);
95164   int  (*open16)(const void*,sqlite3**);
95165   int  (*prepare)(sqlite3*,const char*,int,sqlite3_stmt**,const char**);
95166   int  (*prepare16)(sqlite3*,const void*,int,sqlite3_stmt**,const void**);
95167   void * (*profile)(sqlite3*,void(*)(void*,const char*,sqlite_uint64),void*);
95168   void  (*progress_handler)(sqlite3*,int,int(*)(void*),void*);
95169   void *(*realloc)(void*,int);
95170   int  (*reset)(sqlite3_stmt*pStmt);
95171   void  (*result_blob)(sqlite3_context*,const void*,int,void(*)(void*));
95172   void  (*result_double)(sqlite3_context*,double);
95173   void  (*result_error)(sqlite3_context*,const char*,int);
95174   void  (*result_error16)(sqlite3_context*,const void*,int);
95175   void  (*result_int)(sqlite3_context*,int);
95176   void  (*result_int64)(sqlite3_context*,sqlite_int64);
95177   void  (*result_null)(sqlite3_context*);
95178   void  (*result_text)(sqlite3_context*,const char*,int,void(*)(void*));
95179   void  (*result_text16)(sqlite3_context*,const void*,int,void(*)(void*));
95180   void  (*result_text16be)(sqlite3_context*,const void*,int,void(*)(void*));
95181   void  (*result_text16le)(sqlite3_context*,const void*,int,void(*)(void*));
95182   void  (*result_value)(sqlite3_context*,sqlite3_value*);
95183   void * (*rollback_hook)(sqlite3*,void(*)(void*),void*);
95184   int  (*set_authorizer)(sqlite3*,int(*)(void*,int,const char*,const char*,
95185                          const char*,const char*),void*);
95186   void  (*set_auxdata)(sqlite3_context*,int,void*,void (*)(void*));
95187   char * (*snprintf)(int,char*,const char*,...);
95188   int  (*step)(sqlite3_stmt*);
95189   int  (*table_column_metadata)(sqlite3*,const char*,const char*,const char*,
95190                                 char const**,char const**,int*,int*,int*);
95191   void  (*thread_cleanup)(void);
95192   int  (*total_changes)(sqlite3*);
95193   void * (*trace)(sqlite3*,void(*xTrace)(void*,const char*),void*);
95194   int  (*transfer_bindings)(sqlite3_stmt*,sqlite3_stmt*);
95195   void * (*update_hook)(sqlite3*,void(*)(void*,int ,char const*,char const*,
95196                                          sqlite_int64),void*);
95197   void * (*user_data)(sqlite3_context*);
95198   const void * (*value_blob)(sqlite3_value*);
95199   int  (*value_bytes)(sqlite3_value*);
95200   int  (*value_bytes16)(sqlite3_value*);
95201   double  (*value_double)(sqlite3_value*);
95202   int  (*value_int)(sqlite3_value*);
95203   sqlite_int64  (*value_int64)(sqlite3_value*);
95204   int  (*value_numeric_type)(sqlite3_value*);
95205   const unsigned char * (*value_text)(sqlite3_value*);
95206   const void * (*value_text16)(sqlite3_value*);
95207   const void * (*value_text16be)(sqlite3_value*);
95208   const void * (*value_text16le)(sqlite3_value*);
95209   int  (*value_type)(sqlite3_value*);
95210   char *(*vmprintf)(const char*,va_list);
95211   /* Added ??? */
95212   int (*overload_function)(sqlite3*, const char *zFuncName, int nArg);
95213   /* Added by 3.3.13 */
95214   int (*prepare_v2)(sqlite3*,const char*,int,sqlite3_stmt**,const char**);
95215   int (*prepare16_v2)(sqlite3*,const void*,int,sqlite3_stmt**,const void**);
95216   int (*clear_bindings)(sqlite3_stmt*);
95217   /* Added by 3.4.1 */
95218   int (*create_module_v2)(sqlite3*,const char*,const sqlite3_module*,void*,
95219                           void (*xDestroy)(void *));
95220   /* Added by 3.5.0 */
95221   int (*bind_zeroblob)(sqlite3_stmt*,int,int);
95222   int (*blob_bytes)(sqlite3_blob*);
95223   int (*blob_close)(sqlite3_blob*);
95224   int (*blob_open)(sqlite3*,const char*,const char*,const char*,sqlite3_int64,
95225                    int,sqlite3_blob**);
95226   int (*blob_read)(sqlite3_blob*,void*,int,int);
95227   int (*blob_write)(sqlite3_blob*,const void*,int,int);
95228   int (*create_collation_v2)(sqlite3*,const char*,int,void*,
95229                              int(*)(void*,int,const void*,int,const void*),
95230                              void(*)(void*));
95231   int (*file_control)(sqlite3*,const char*,int,void*);
95232   sqlite3_int64 (*memory_highwater)(int);
95233   sqlite3_int64 (*memory_used)(void);
95234   sqlite3_mutex *(*mutex_alloc)(int);
95235   void (*mutex_enter)(sqlite3_mutex*);
95236   void (*mutex_free)(sqlite3_mutex*);
95237   void (*mutex_leave)(sqlite3_mutex*);
95238   int (*mutex_try)(sqlite3_mutex*);
95239   int (*open_v2)(const char*,sqlite3**,int,const char*);
95240   int (*release_memory)(int);
95241   void (*result_error_nomem)(sqlite3_context*);
95242   void (*result_error_toobig)(sqlite3_context*);
95243   int (*sleep)(int);
95244   void (*soft_heap_limit)(int);
95245   sqlite3_vfs *(*vfs_find)(const char*);
95246   int (*vfs_register)(sqlite3_vfs*,int);
95247   int (*vfs_unregister)(sqlite3_vfs*);
95248   int (*xthreadsafe)(void);
95249   void (*result_zeroblob)(sqlite3_context*,int);
95250   void (*result_error_code)(sqlite3_context*,int);
95251   int (*test_control)(int, ...);
95252   void (*randomness)(int,void*);
95253   sqlite3 *(*context_db_handle)(sqlite3_context*);
95254   int (*extended_result_codes)(sqlite3*,int);
95255   int (*limit)(sqlite3*,int,int);
95256   sqlite3_stmt *(*next_stmt)(sqlite3*,sqlite3_stmt*);
95257   const char *(*sql)(sqlite3_stmt*);
95258   int (*status)(int,int*,int*,int);
95259   int (*backup_finish)(sqlite3_backup*);
95260   sqlite3_backup *(*backup_init)(sqlite3*,const char*,sqlite3*,const char*);
95261   int (*backup_pagecount)(sqlite3_backup*);
95262   int (*backup_remaining)(sqlite3_backup*);
95263   int (*backup_step)(sqlite3_backup*,int);
95264   const char *(*compileoption_get)(int);
95265   int (*compileoption_used)(const char*);
95266   int (*create_function_v2)(sqlite3*,const char*,int,int,void*,
95267                             void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
95268                             void (*xStep)(sqlite3_context*,int,sqlite3_value**),
95269                             void (*xFinal)(sqlite3_context*),
95270                             void(*xDestroy)(void*));
95271   int (*db_config)(sqlite3*,int,...);
95272   sqlite3_mutex *(*db_mutex)(sqlite3*);
95273   int (*db_status)(sqlite3*,int,int*,int*,int);
95274   int (*extended_errcode)(sqlite3*);
95275   void (*log)(int,const char*,...);
95276   sqlite3_int64 (*soft_heap_limit64)(sqlite3_int64);
95277   const char *(*sourceid)(void);
95278   int (*stmt_status)(sqlite3_stmt*,int,int);
95279   int (*strnicmp)(const char*,const char*,int);
95280   int (*unlock_notify)(sqlite3*,void(*)(void**,int),void*);
95281   int (*wal_autocheckpoint)(sqlite3*,int);
95282   int (*wal_checkpoint)(sqlite3*,const char*);
95283   void *(*wal_hook)(sqlite3*,int(*)(void*,sqlite3*,const char*,int),void*);
95284   int (*blob_reopen)(sqlite3_blob*,sqlite3_int64);
95285   int (*vtab_config)(sqlite3*,int op,...);
95286   int (*vtab_on_conflict)(sqlite3*);
95287   /* Version 3.7.16 and later */
95288   int (*close_v2)(sqlite3*);
95289   const char *(*db_filename)(sqlite3*,const char*);
95290   int (*db_readonly)(sqlite3*,const char*);
95291   int (*db_release_memory)(sqlite3*);
95292   const char *(*errstr)(int);
95293   int (*stmt_busy)(sqlite3_stmt*);
95294   int (*stmt_readonly)(sqlite3_stmt*);
95295   int (*stricmp)(const char*,const char*);
95296   int (*uri_boolean)(const char*,const char*,int);
95297   sqlite3_int64 (*uri_int64)(const char*,const char*,sqlite3_int64);
95298   const char *(*uri_parameter)(const char*,const char*);
95299   char *(*vsnprintf)(int,char*,const char*,va_list);
95300   int (*wal_checkpoint_v2)(sqlite3*,const char*,int,int*,int*);
95301 };
95302 
95303 /*
95304 ** The following macros redefine the API routines so that they are
95305 ** redirected throught the global sqlite3_api structure.
95306 **
95307 ** This header file is also used by the loadext.c source file
95308 ** (part of the main SQLite library - not an extension) so that
95309 ** it can get access to the sqlite3_api_routines structure
95310 ** definition.  But the main library does not want to redefine
95311 ** the API.  So the redefinition macros are only valid if the
95312 ** SQLITE_CORE macros is undefined.
95313 */
95314 #ifndef SQLITE_CORE
95315 #define sqlite3_aggregate_context      sqlite3_api->aggregate_context
95316 #ifndef SQLITE_OMIT_DEPRECATED
95317 #define sqlite3_aggregate_count        sqlite3_api->aggregate_count
95318 #endif
95319 #define sqlite3_bind_blob              sqlite3_api->bind_blob
95320 #define sqlite3_bind_double            sqlite3_api->bind_double
95321 #define sqlite3_bind_int               sqlite3_api->bind_int
95322 #define sqlite3_bind_int64             sqlite3_api->bind_int64
95323 #define sqlite3_bind_null              sqlite3_api->bind_null
95324 #define sqlite3_bind_parameter_count   sqlite3_api->bind_parameter_count
95325 #define sqlite3_bind_parameter_index   sqlite3_api->bind_parameter_index
95326 #define sqlite3_bind_parameter_name    sqlite3_api->bind_parameter_name
95327 #define sqlite3_bind_text              sqlite3_api->bind_text
95328 #define sqlite3_bind_text16            sqlite3_api->bind_text16
95329 #define sqlite3_bind_value             sqlite3_api->bind_value
95330 #define sqlite3_busy_handler           sqlite3_api->busy_handler
95331 #define sqlite3_busy_timeout           sqlite3_api->busy_timeout
95332 #define sqlite3_changes                sqlite3_api->changes
95333 #define sqlite3_close                  sqlite3_api->close
95334 #define sqlite3_collation_needed       sqlite3_api->collation_needed
95335 #define sqlite3_collation_needed16     sqlite3_api->collation_needed16
95336 #define sqlite3_column_blob            sqlite3_api->column_blob
95337 #define sqlite3_column_bytes           sqlite3_api->column_bytes
95338 #define sqlite3_column_bytes16         sqlite3_api->column_bytes16
95339 #define sqlite3_column_count           sqlite3_api->column_count
95340 #define sqlite3_column_database_name   sqlite3_api->column_database_name
95341 #define sqlite3_column_database_name16 sqlite3_api->column_database_name16
95342 #define sqlite3_column_decltype        sqlite3_api->column_decltype
95343 #define sqlite3_column_decltype16      sqlite3_api->column_decltype16
95344 #define sqlite3_column_double          sqlite3_api->column_double
95345 #define sqlite3_column_int             sqlite3_api->column_int
95346 #define sqlite3_column_int64           sqlite3_api->column_int64
95347 #define sqlite3_column_name            sqlite3_api->column_name
95348 #define sqlite3_column_name16          sqlite3_api->column_name16
95349 #define sqlite3_column_origin_name     sqlite3_api->column_origin_name
95350 #define sqlite3_column_origin_name16   sqlite3_api->column_origin_name16
95351 #define sqlite3_column_table_name      sqlite3_api->column_table_name
95352 #define sqlite3_column_table_name16    sqlite3_api->column_table_name16
95353 #define sqlite3_column_text            sqlite3_api->column_text
95354 #define sqlite3_column_text16          sqlite3_api->column_text16
95355 #define sqlite3_column_type            sqlite3_api->column_type
95356 #define sqlite3_column_value           sqlite3_api->column_value
95357 #define sqlite3_commit_hook            sqlite3_api->commit_hook
95358 #define sqlite3_complete               sqlite3_api->complete
95359 #define sqlite3_complete16             sqlite3_api->complete16
95360 #define sqlite3_create_collation       sqlite3_api->create_collation
95361 #define sqlite3_create_collation16     sqlite3_api->create_collation16
95362 #define sqlite3_create_function        sqlite3_api->create_function
95363 #define sqlite3_create_function16      sqlite3_api->create_function16
95364 #define sqlite3_create_module          sqlite3_api->create_module
95365 #define sqlite3_create_module_v2       sqlite3_api->create_module_v2
95366 #define sqlite3_data_count             sqlite3_api->data_count
95367 #define sqlite3_db_handle              sqlite3_api->db_handle
95368 #define sqlite3_declare_vtab           sqlite3_api->declare_vtab
95369 #define sqlite3_enable_shared_cache    sqlite3_api->enable_shared_cache
95370 #define sqlite3_errcode                sqlite3_api->errcode
95371 #define sqlite3_errmsg                 sqlite3_api->errmsg
95372 #define sqlite3_errmsg16               sqlite3_api->errmsg16
95373 #define sqlite3_exec                   sqlite3_api->exec
95374 #ifndef SQLITE_OMIT_DEPRECATED
95375 #define sqlite3_expired                sqlite3_api->expired
95376 #endif
95377 #define sqlite3_finalize               sqlite3_api->finalize
95378 #define sqlite3_free                   sqlite3_api->free
95379 #define sqlite3_free_table             sqlite3_api->free_table
95380 #define sqlite3_get_autocommit         sqlite3_api->get_autocommit
95381 #define sqlite3_get_auxdata            sqlite3_api->get_auxdata
95382 #define sqlite3_get_table              sqlite3_api->get_table
95383 #ifndef SQLITE_OMIT_DEPRECATED
95384 #define sqlite3_global_recover         sqlite3_api->global_recover
95385 #endif
95386 #define sqlite3_interrupt              sqlite3_api->interruptx
95387 #define sqlite3_last_insert_rowid      sqlite3_api->last_insert_rowid
95388 #define sqlite3_libversion             sqlite3_api->libversion
95389 #define sqlite3_libversion_number      sqlite3_api->libversion_number
95390 #define sqlite3_malloc                 sqlite3_api->malloc
95391 #define sqlite3_mprintf                sqlite3_api->mprintf
95392 #define sqlite3_open                   sqlite3_api->open
95393 #define sqlite3_open16                 sqlite3_api->open16
95394 #define sqlite3_prepare                sqlite3_api->prepare
95395 #define sqlite3_prepare16              sqlite3_api->prepare16
95396 #define sqlite3_prepare_v2             sqlite3_api->prepare_v2
95397 #define sqlite3_prepare16_v2           sqlite3_api->prepare16_v2
95398 #define sqlite3_profile                sqlite3_api->profile
95399 #define sqlite3_progress_handler       sqlite3_api->progress_handler
95400 #define sqlite3_realloc                sqlite3_api->realloc
95401 #define sqlite3_reset                  sqlite3_api->reset
95402 #define sqlite3_result_blob            sqlite3_api->result_blob
95403 #define sqlite3_result_double          sqlite3_api->result_double
95404 #define sqlite3_result_error           sqlite3_api->result_error
95405 #define sqlite3_result_error16         sqlite3_api->result_error16
95406 #define sqlite3_result_int             sqlite3_api->result_int
95407 #define sqlite3_result_int64           sqlite3_api->result_int64
95408 #define sqlite3_result_null            sqlite3_api->result_null
95409 #define sqlite3_result_text            sqlite3_api->result_text
95410 #define sqlite3_result_text16          sqlite3_api->result_text16
95411 #define sqlite3_result_text16be        sqlite3_api->result_text16be
95412 #define sqlite3_result_text16le        sqlite3_api->result_text16le
95413 #define sqlite3_result_value           sqlite3_api->result_value
95414 #define sqlite3_rollback_hook          sqlite3_api->rollback_hook
95415 #define sqlite3_set_authorizer         sqlite3_api->set_authorizer
95416 #define sqlite3_set_auxdata            sqlite3_api->set_auxdata
95417 #define sqlite3_snprintf               sqlite3_api->snprintf
95418 #define sqlite3_step                   sqlite3_api->step
95419 #define sqlite3_table_column_metadata  sqlite3_api->table_column_metadata
95420 #define sqlite3_thread_cleanup         sqlite3_api->thread_cleanup
95421 #define sqlite3_total_changes          sqlite3_api->total_changes
95422 #define sqlite3_trace                  sqlite3_api->trace
95423 #ifndef SQLITE_OMIT_DEPRECATED
95424 #define sqlite3_transfer_bindings      sqlite3_api->transfer_bindings
95425 #endif
95426 #define sqlite3_update_hook            sqlite3_api->update_hook
95427 #define sqlite3_user_data              sqlite3_api->user_data
95428 #define sqlite3_value_blob             sqlite3_api->value_blob
95429 #define sqlite3_value_bytes            sqlite3_api->value_bytes
95430 #define sqlite3_value_bytes16          sqlite3_api->value_bytes16
95431 #define sqlite3_value_double           sqlite3_api->value_double
95432 #define sqlite3_value_int              sqlite3_api->value_int
95433 #define sqlite3_value_int64            sqlite3_api->value_int64
95434 #define sqlite3_value_numeric_type     sqlite3_api->value_numeric_type
95435 #define sqlite3_value_text             sqlite3_api->value_text
95436 #define sqlite3_value_text16           sqlite3_api->value_text16
95437 #define sqlite3_value_text16be         sqlite3_api->value_text16be
95438 #define sqlite3_value_text16le         sqlite3_api->value_text16le
95439 #define sqlite3_value_type             sqlite3_api->value_type
95440 #define sqlite3_vmprintf               sqlite3_api->vmprintf
95441 #define sqlite3_overload_function      sqlite3_api->overload_function
95442 #define sqlite3_prepare_v2             sqlite3_api->prepare_v2
95443 #define sqlite3_prepare16_v2           sqlite3_api->prepare16_v2
95444 #define sqlite3_clear_bindings         sqlite3_api->clear_bindings
95445 #define sqlite3_bind_zeroblob          sqlite3_api->bind_zeroblob
95446 #define sqlite3_blob_bytes             sqlite3_api->blob_bytes
95447 #define sqlite3_blob_close             sqlite3_api->blob_close
95448 #define sqlite3_blob_open              sqlite3_api->blob_open
95449 #define sqlite3_blob_read              sqlite3_api->blob_read
95450 #define sqlite3_blob_write             sqlite3_api->blob_write
95451 #define sqlite3_create_collation_v2    sqlite3_api->create_collation_v2
95452 #define sqlite3_file_control           sqlite3_api->file_control
95453 #define sqlite3_memory_highwater       sqlite3_api->memory_highwater
95454 #define sqlite3_memory_used            sqlite3_api->memory_used
95455 #define sqlite3_mutex_alloc            sqlite3_api->mutex_alloc
95456 #define sqlite3_mutex_enter            sqlite3_api->mutex_enter
95457 #define sqlite3_mutex_free             sqlite3_api->mutex_free
95458 #define sqlite3_mutex_leave            sqlite3_api->mutex_leave
95459 #define sqlite3_mutex_try              sqlite3_api->mutex_try
95460 #define sqlite3_open_v2                sqlite3_api->open_v2
95461 #define sqlite3_release_memory         sqlite3_api->release_memory
95462 #define sqlite3_result_error_nomem     sqlite3_api->result_error_nomem
95463 #define sqlite3_result_error_toobig    sqlite3_api->result_error_toobig
95464 #define sqlite3_sleep                  sqlite3_api->sleep
95465 #define sqlite3_soft_heap_limit        sqlite3_api->soft_heap_limit
95466 #define sqlite3_vfs_find               sqlite3_api->vfs_find
95467 #define sqlite3_vfs_register           sqlite3_api->vfs_register
95468 #define sqlite3_vfs_unregister         sqlite3_api->vfs_unregister
95469 #define sqlite3_threadsafe             sqlite3_api->xthreadsafe
95470 #define sqlite3_result_zeroblob        sqlite3_api->result_zeroblob
95471 #define sqlite3_result_error_code      sqlite3_api->result_error_code
95472 #define sqlite3_test_control           sqlite3_api->test_control
95473 #define sqlite3_randomness             sqlite3_api->randomness
95474 #define sqlite3_context_db_handle      sqlite3_api->context_db_handle
95475 #define sqlite3_extended_result_codes  sqlite3_api->extended_result_codes
95476 #define sqlite3_limit                  sqlite3_api->limit
95477 #define sqlite3_next_stmt              sqlite3_api->next_stmt
95478 #define sqlite3_sql                    sqlite3_api->sql
95479 #define sqlite3_status                 sqlite3_api->status
95480 #define sqlite3_backup_finish          sqlite3_api->backup_finish
95481 #define sqlite3_backup_init            sqlite3_api->backup_init
95482 #define sqlite3_backup_pagecount       sqlite3_api->backup_pagecount
95483 #define sqlite3_backup_remaining       sqlite3_api->backup_remaining
95484 #define sqlite3_backup_step            sqlite3_api->backup_step
95485 #define sqlite3_compileoption_get      sqlite3_api->compileoption_get
95486 #define sqlite3_compileoption_used     sqlite3_api->compileoption_used
95487 #define sqlite3_create_function_v2     sqlite3_api->create_function_v2
95488 #define sqlite3_db_config              sqlite3_api->db_config
95489 #define sqlite3_db_mutex               sqlite3_api->db_mutex
95490 #define sqlite3_db_status              sqlite3_api->db_status
95491 #define sqlite3_extended_errcode       sqlite3_api->extended_errcode
95492 #define sqlite3_log                    sqlite3_api->log
95493 #define sqlite3_soft_heap_limit64      sqlite3_api->soft_heap_limit64
95494 #define sqlite3_sourceid               sqlite3_api->sourceid
95495 #define sqlite3_stmt_status            sqlite3_api->stmt_status
95496 #define sqlite3_strnicmp               sqlite3_api->strnicmp
95497 #define sqlite3_unlock_notify          sqlite3_api->unlock_notify
95498 #define sqlite3_wal_autocheckpoint     sqlite3_api->wal_autocheckpoint
95499 #define sqlite3_wal_checkpoint         sqlite3_api->wal_checkpoint
95500 #define sqlite3_wal_hook               sqlite3_api->wal_hook
95501 #define sqlite3_blob_reopen            sqlite3_api->blob_reopen
95502 #define sqlite3_vtab_config            sqlite3_api->vtab_config
95503 #define sqlite3_vtab_on_conflict       sqlite3_api->vtab_on_conflict
95504 /* Version 3.7.16 and later */
95505 #define sqlite3_close_v2               sqlite3_api->close_v2
95506 #define sqlite3_db_filename            sqlite3_api->db_filename
95507 #define sqlite3_db_readonly            sqlite3_api->db_readonly
95508 #define sqlite3_db_release_memory      sqlite3_api->db_release_memory
95509 #define sqlite3_errstr                 sqlite3_api->errstr
95510 #define sqlite3_stmt_busy              sqlite3_api->stmt_busy
95511 #define sqlite3_stmt_readonly          sqlite3_api->stmt_readonly
95512 #define sqlite3_stricmp                sqlite3_api->stricmp
95513 #define sqlite3_uri_boolean            sqlite3_api->uri_boolean
95514 #define sqlite3_uri_int64              sqlite3_api->uri_int64
95515 #define sqlite3_uri_parameter          sqlite3_api->uri_parameter
95516 #define sqlite3_uri_vsnprintf          sqlite3_api->vsnprintf
95517 #define sqlite3_wal_checkpoint_v2      sqlite3_api->wal_checkpoint_v2
95518 #endif /* SQLITE_CORE */
95519 
95520 #ifndef SQLITE_CORE
95521   /* This case when the file really is being compiled as a loadable 
95522   ** extension */
95523 # define SQLITE_EXTENSION_INIT1     const sqlite3_api_routines *sqlite3_api=0;
95524 # define SQLITE_EXTENSION_INIT2(v)  sqlite3_api=v;
95525 # define SQLITE_EXTENSION_INIT3     \
95526     extern const sqlite3_api_routines *sqlite3_api;
95527 #else
95528   /* This case when the file is being statically linked into the 
95529   ** application */
95530 # define SQLITE_EXTENSION_INIT1     /*no-op*/
95531 # define SQLITE_EXTENSION_INIT2(v)  (void)v; /* unused parameter */
95532 # define SQLITE_EXTENSION_INIT3     /*no-op*/
95533 #endif
95534 
95535 #endif /* _SQLITE3EXT_H_ */
95536 
95537 /************** End of sqlite3ext.h ******************************************/
95538 /************** Continuing where we left off in loadext.c ********************/
95539 /* #include <string.h> */
95540 
95541 #ifndef SQLITE_OMIT_LOAD_EXTENSION
95542 
95543 /*
95544 ** Some API routines are omitted when various features are
95545 ** excluded from a build of SQLite.  Substitute a NULL pointer
95546 ** for any missing APIs.
95547 */
95548 #ifndef SQLITE_ENABLE_COLUMN_METADATA
95549 # define sqlite3_column_database_name   0
95550 # define sqlite3_column_database_name16 0
95551 # define sqlite3_column_table_name      0
95552 # define sqlite3_column_table_name16    0
95553 # define sqlite3_column_origin_name     0
95554 # define sqlite3_column_origin_name16   0
95555 # define sqlite3_table_column_metadata  0
95556 #endif
95557 
95558 #ifdef SQLITE_OMIT_AUTHORIZATION
95559 # define sqlite3_set_authorizer         0
95560 #endif
95561 
95562 #ifdef SQLITE_OMIT_UTF16
95563 # define sqlite3_bind_text16            0
95564 # define sqlite3_collation_needed16     0
95565 # define sqlite3_column_decltype16      0
95566 # define sqlite3_column_name16          0
95567 # define sqlite3_column_text16          0
95568 # define sqlite3_complete16             0
95569 # define sqlite3_create_collation16     0
95570 # define sqlite3_create_function16      0
95571 # define sqlite3_errmsg16               0
95572 # define sqlite3_open16                 0
95573 # define sqlite3_prepare16              0
95574 # define sqlite3_prepare16_v2           0
95575 # define sqlite3_result_error16         0
95576 # define sqlite3_result_text16          0
95577 # define sqlite3_result_text16be        0
95578 # define sqlite3_result_text16le        0
95579 # define sqlite3_value_text16           0
95580 # define sqlite3_value_text16be         0
95581 # define sqlite3_value_text16le         0
95582 # define sqlite3_column_database_name16 0
95583 # define sqlite3_column_table_name16    0
95584 # define sqlite3_column_origin_name16   0
95585 #endif
95586 
95587 #ifdef SQLITE_OMIT_COMPLETE
95588 # define sqlite3_complete 0
95589 # define sqlite3_complete16 0
95590 #endif
95591 
95592 #ifdef SQLITE_OMIT_DECLTYPE
95593 # define sqlite3_column_decltype16      0
95594 # define sqlite3_column_decltype        0
95595 #endif
95596 
95597 #ifdef SQLITE_OMIT_PROGRESS_CALLBACK
95598 # define sqlite3_progress_handler 0
95599 #endif
95600 
95601 #ifdef SQLITE_OMIT_VIRTUALTABLE
95602 # define sqlite3_create_module 0
95603 # define sqlite3_create_module_v2 0
95604 # define sqlite3_declare_vtab 0
95605 # define sqlite3_vtab_config 0
95606 # define sqlite3_vtab_on_conflict 0
95607 #endif
95608 
95609 #ifdef SQLITE_OMIT_SHARED_CACHE
95610 # define sqlite3_enable_shared_cache 0
95611 #endif
95612 
95613 #ifdef SQLITE_OMIT_TRACE
95614 # define sqlite3_profile       0
95615 # define sqlite3_trace         0
95616 #endif
95617 
95618 #ifdef SQLITE_OMIT_GET_TABLE
95619 # define sqlite3_free_table    0
95620 # define sqlite3_get_table     0
95621 #endif
95622 
95623 #ifdef SQLITE_OMIT_INCRBLOB
95624 #define sqlite3_bind_zeroblob  0
95625 #define sqlite3_blob_bytes     0
95626 #define sqlite3_blob_close     0
95627 #define sqlite3_blob_open      0
95628 #define sqlite3_blob_read      0
95629 #define sqlite3_blob_write     0
95630 #define sqlite3_blob_reopen    0
95631 #endif
95632 
95633 /*
95634 ** The following structure contains pointers to all SQLite API routines.
95635 ** A pointer to this structure is passed into extensions when they are
95636 ** loaded so that the extension can make calls back into the SQLite
95637 ** library.
95638 **
95639 ** When adding new APIs, add them to the bottom of this structure
95640 ** in order to preserve backwards compatibility.
95641 **
95642 ** Extensions that use newer APIs should first call the
95643 ** sqlite3_libversion_number() to make sure that the API they
95644 ** intend to use is supported by the library.  Extensions should
95645 ** also check to make sure that the pointer to the function is
95646 ** not NULL before calling it.
95647 */
95648 static const sqlite3_api_routines sqlite3Apis = {
95649   sqlite3_aggregate_context,
95650 #ifndef SQLITE_OMIT_DEPRECATED
95651   sqlite3_aggregate_count,
95652 #else
95653   0,
95654 #endif
95655   sqlite3_bind_blob,
95656   sqlite3_bind_double,
95657   sqlite3_bind_int,
95658   sqlite3_bind_int64,
95659   sqlite3_bind_null,
95660   sqlite3_bind_parameter_count,
95661   sqlite3_bind_parameter_index,
95662   sqlite3_bind_parameter_name,
95663   sqlite3_bind_text,
95664   sqlite3_bind_text16,
95665   sqlite3_bind_value,
95666   sqlite3_busy_handler,
95667   sqlite3_busy_timeout,
95668   sqlite3_changes,
95669   sqlite3_close,
95670   sqlite3_collation_needed,
95671   sqlite3_collation_needed16,
95672   sqlite3_column_blob,
95673   sqlite3_column_bytes,
95674   sqlite3_column_bytes16,
95675   sqlite3_column_count,
95676   sqlite3_column_database_name,
95677   sqlite3_column_database_name16,
95678   sqlite3_column_decltype,
95679   sqlite3_column_decltype16,
95680   sqlite3_column_double,
95681   sqlite3_column_int,
95682   sqlite3_column_int64,
95683   sqlite3_column_name,
95684   sqlite3_column_name16,
95685   sqlite3_column_origin_name,
95686   sqlite3_column_origin_name16,
95687   sqlite3_column_table_name,
95688   sqlite3_column_table_name16,
95689   sqlite3_column_text,
95690   sqlite3_column_text16,
95691   sqlite3_column_type,
95692   sqlite3_column_value,
95693   sqlite3_commit_hook,
95694   sqlite3_complete,
95695   sqlite3_complete16,
95696   sqlite3_create_collation,
95697   sqlite3_create_collation16,
95698   sqlite3_create_function,
95699   sqlite3_create_function16,
95700   sqlite3_create_module,
95701   sqlite3_data_count,
95702   sqlite3_db_handle,
95703   sqlite3_declare_vtab,
95704   sqlite3_enable_shared_cache,
95705   sqlite3_errcode,
95706   sqlite3_errmsg,
95707   sqlite3_errmsg16,
95708   sqlite3_exec,
95709 #ifndef SQLITE_OMIT_DEPRECATED
95710   sqlite3_expired,
95711 #else
95712   0,
95713 #endif
95714   sqlite3_finalize,
95715   sqlite3_free,
95716   sqlite3_free_table,
95717   sqlite3_get_autocommit,
95718   sqlite3_get_auxdata,
95719   sqlite3_get_table,
95720   0,     /* Was sqlite3_global_recover(), but that function is deprecated */
95721   sqlite3_interrupt,
95722   sqlite3_last_insert_rowid,
95723   sqlite3_libversion,
95724   sqlite3_libversion_number,
95725   sqlite3_malloc,
95726   sqlite3_mprintf,
95727   sqlite3_open,
95728   sqlite3_open16,
95729   sqlite3_prepare,
95730   sqlite3_prepare16,
95731   sqlite3_profile,
95732   sqlite3_progress_handler,
95733   sqlite3_realloc,
95734   sqlite3_reset,
95735   sqlite3_result_blob,
95736   sqlite3_result_double,
95737   sqlite3_result_error,
95738   sqlite3_result_error16,
95739   sqlite3_result_int,
95740   sqlite3_result_int64,
95741   sqlite3_result_null,
95742   sqlite3_result_text,
95743   sqlite3_result_text16,
95744   sqlite3_result_text16be,
95745   sqlite3_result_text16le,
95746   sqlite3_result_value,
95747   sqlite3_rollback_hook,
95748   sqlite3_set_authorizer,
95749   sqlite3_set_auxdata,
95750   sqlite3_snprintf,
95751   sqlite3_step,
95752   sqlite3_table_column_metadata,
95753 #ifndef SQLITE_OMIT_DEPRECATED
95754   sqlite3_thread_cleanup,
95755 #else
95756   0,
95757 #endif
95758   sqlite3_total_changes,
95759   sqlite3_trace,
95760 #ifndef SQLITE_OMIT_DEPRECATED
95761   sqlite3_transfer_bindings,
95762 #else
95763   0,
95764 #endif
95765   sqlite3_update_hook,
95766   sqlite3_user_data,
95767   sqlite3_value_blob,
95768   sqlite3_value_bytes,
95769   sqlite3_value_bytes16,
95770   sqlite3_value_double,
95771   sqlite3_value_int,
95772   sqlite3_value_int64,
95773   sqlite3_value_numeric_type,
95774   sqlite3_value_text,
95775   sqlite3_value_text16,
95776   sqlite3_value_text16be,
95777   sqlite3_value_text16le,
95778   sqlite3_value_type,
95779   sqlite3_vmprintf,
95780   /*
95781   ** The original API set ends here.  All extensions can call any
95782   ** of the APIs above provided that the pointer is not NULL.  But
95783   ** before calling APIs that follow, extension should check the
95784   ** sqlite3_libversion_number() to make sure they are dealing with
95785   ** a library that is new enough to support that API.
95786   *************************************************************************
95787   */
95788   sqlite3_overload_function,
95789 
95790   /*
95791   ** Added after 3.3.13
95792   */
95793   sqlite3_prepare_v2,
95794   sqlite3_prepare16_v2,
95795   sqlite3_clear_bindings,
95796 
95797   /*
95798   ** Added for 3.4.1
95799   */
95800   sqlite3_create_module_v2,
95801 
95802   /*
95803   ** Added for 3.5.0
95804   */
95805   sqlite3_bind_zeroblob,
95806   sqlite3_blob_bytes,
95807   sqlite3_blob_close,
95808   sqlite3_blob_open,
95809   sqlite3_blob_read,
95810   sqlite3_blob_write,
95811   sqlite3_create_collation_v2,
95812   sqlite3_file_control,
95813   sqlite3_memory_highwater,
95814   sqlite3_memory_used,
95815 #ifdef SQLITE_MUTEX_OMIT
95816   0, 
95817   0, 
95818   0,
95819   0,
95820   0,
95821 #else
95822   sqlite3_mutex_alloc,
95823   sqlite3_mutex_enter,
95824   sqlite3_mutex_free,
95825   sqlite3_mutex_leave,
95826   sqlite3_mutex_try,
95827 #endif
95828   sqlite3_open_v2,
95829   sqlite3_release_memory,
95830   sqlite3_result_error_nomem,
95831   sqlite3_result_error_toobig,
95832   sqlite3_sleep,
95833   sqlite3_soft_heap_limit,
95834   sqlite3_vfs_find,
95835   sqlite3_vfs_register,
95836   sqlite3_vfs_unregister,
95837 
95838   /*
95839   ** Added for 3.5.8
95840   */
95841   sqlite3_threadsafe,
95842   sqlite3_result_zeroblob,
95843   sqlite3_result_error_code,
95844   sqlite3_test_control,
95845   sqlite3_randomness,
95846   sqlite3_context_db_handle,
95847 
95848   /*
95849   ** Added for 3.6.0
95850   */
95851   sqlite3_extended_result_codes,
95852   sqlite3_limit,
95853   sqlite3_next_stmt,
95854   sqlite3_sql,
95855   sqlite3_status,
95856 
95857   /*
95858   ** Added for 3.7.4
95859   */
95860   sqlite3_backup_finish,
95861   sqlite3_backup_init,
95862   sqlite3_backup_pagecount,
95863   sqlite3_backup_remaining,
95864   sqlite3_backup_step,
95865 #ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS
95866   sqlite3_compileoption_get,
95867   sqlite3_compileoption_used,
95868 #else
95869   0,
95870   0,
95871 #endif
95872   sqlite3_create_function_v2,
95873   sqlite3_db_config,
95874   sqlite3_db_mutex,
95875   sqlite3_db_status,
95876   sqlite3_extended_errcode,
95877   sqlite3_log,
95878   sqlite3_soft_heap_limit64,
95879   sqlite3_sourceid,
95880   sqlite3_stmt_status,
95881   sqlite3_strnicmp,
95882 #ifdef SQLITE_ENABLE_UNLOCK_NOTIFY
95883   sqlite3_unlock_notify,
95884 #else
95885   0,
95886 #endif
95887 #ifndef SQLITE_OMIT_WAL
95888   sqlite3_wal_autocheckpoint,
95889   sqlite3_wal_checkpoint,
95890   sqlite3_wal_hook,
95891 #else
95892   0,
95893   0,
95894   0,
95895 #endif
95896   sqlite3_blob_reopen,
95897   sqlite3_vtab_config,
95898   sqlite3_vtab_on_conflict,
95899   sqlite3_close_v2,
95900   sqlite3_db_filename,
95901   sqlite3_db_readonly,
95902   sqlite3_db_release_memory,
95903   sqlite3_errstr,
95904   sqlite3_stmt_busy,
95905   sqlite3_stmt_readonly,
95906   sqlite3_stricmp,
95907   sqlite3_uri_boolean,
95908   sqlite3_uri_int64,
95909   sqlite3_uri_parameter,
95910   sqlite3_vsnprintf,
95911   sqlite3_wal_checkpoint_v2
95912 };
95913 
95914 /*
95915 ** Attempt to load an SQLite extension library contained in the file
95916 ** zFile.  The entry point is zProc.  zProc may be 0 in which case a
95917 ** default entry point name (sqlite3_extension_init) is used.  Use
95918 ** of the default name is recommended.
95919 **
95920 ** Return SQLITE_OK on success and SQLITE_ERROR if something goes wrong.
95921 **
95922 ** If an error occurs and pzErrMsg is not 0, then fill *pzErrMsg with 
95923 ** error message text.  The calling function should free this memory
95924 ** by calling sqlite3DbFree(db, ).
95925 */
95926 static int sqlite3LoadExtension(
95927   sqlite3 *db,          /* Load the extension into this database connection */
95928   const char *zFile,    /* Name of the shared library containing extension */
95929   const char *zProc,    /* Entry point.  Use "sqlite3_extension_init" if 0 */
95930   char **pzErrMsg       /* Put error message here if not 0 */
95931 ){
95932   sqlite3_vfs *pVfs = db->pVfs;
95933   void *handle;
95934   int (*xInit)(sqlite3*,char**,const sqlite3_api_routines*);
95935   char *zErrmsg = 0;
95936   const char *zEntry;
95937   char *zAltEntry = 0;
95938   void **aHandle;
95939   int nMsg = 300 + sqlite3Strlen30(zFile);
95940   int ii;
95941 
95942   /* Shared library endings to try if zFile cannot be loaded as written */
95943   static const char *azEndings[] = {
95944 #if SQLITE_OS_WIN
95945      "dll"   
95946 #elif defined(__APPLE__)
95947      "dylib"
95948 #else
95949      "so"
95950 #endif
95951   };
95952 
95953 
95954   if( pzErrMsg ) *pzErrMsg = 0;
95955 
95956   /* Ticket #1863.  To avoid a creating security problems for older
95957   ** applications that relink against newer versions of SQLite, the
95958   ** ability to run load_extension is turned off by default.  One
95959   ** must call sqlite3_enable_load_extension() to turn on extension
95960   ** loading.  Otherwise you get the following error.
95961   */
95962   if( (db->flags & SQLITE_LoadExtension)==0 ){
95963     if( pzErrMsg ){
95964       *pzErrMsg = sqlite3_mprintf("not authorized");
95965     }
95966     return SQLITE_ERROR;
95967   }
95968 
95969   zEntry = zProc ? zProc : "sqlite3_extension_init";
95970 
95971   handle = sqlite3OsDlOpen(pVfs, zFile);
95972 #if SQLITE_OS_UNIX || SQLITE_OS_WIN
95973   for(ii=0; ii<ArraySize(azEndings) && handle==0; ii++){
95974     char *zAltFile = sqlite3_mprintf("%s.%s", zFile, azEndings[ii]);
95975     if( zAltFile==0 ) return SQLITE_NOMEM;
95976     handle = sqlite3OsDlOpen(pVfs, zAltFile);
95977     sqlite3_free(zAltFile);
95978   }
95979 #endif
95980   if( handle==0 ){
95981     if( pzErrMsg ){
95982       *pzErrMsg = zErrmsg = sqlite3_malloc(nMsg);
95983       if( zErrmsg ){
95984         sqlite3_snprintf(nMsg, zErrmsg, 
95985             "unable to open shared library [%s]", zFile);
95986         sqlite3OsDlError(pVfs, nMsg-1, zErrmsg);
95987       }
95988     }
95989     return SQLITE_ERROR;
95990   }
95991   xInit = (int(*)(sqlite3*,char**,const sqlite3_api_routines*))
95992                    sqlite3OsDlSym(pVfs, handle, zEntry);
95993 
95994   /* If no entry point was specified and the default legacy
95995   ** entry point name "sqlite3_extension_init" was not found, then
95996   ** construct an entry point name "sqlite3_X_init" where the X is
95997   ** replaced by the lowercase value of every ASCII alphabetic 
95998   ** character in the filename after the last "/" upto the first ".",
95999   ** and eliding the first three characters if they are "lib".  
96000   ** Examples:
96001   **
96002   **    /usr/local/lib/libExample5.4.3.so ==>  sqlite3_example_init
96003   **    C:/lib/mathfuncs.dll              ==>  sqlite3_mathfuncs_init
96004   */
96005   if( xInit==0 && zProc==0 ){
96006     int iFile, iEntry, c;
96007     int ncFile = sqlite3Strlen30(zFile);
96008     zAltEntry = sqlite3_malloc(ncFile+30);
96009     if( zAltEntry==0 ){
96010       sqlite3OsDlClose(pVfs, handle);
96011       return SQLITE_NOMEM;
96012     }
96013     memcpy(zAltEntry, "sqlite3_", 8);
96014     for(iFile=ncFile-1; iFile>=0 && zFile[iFile]!='/'; iFile--){}
96015     iFile++;
96016     if( sqlite3_strnicmp(zFile+iFile, "lib", 3)==0 ) iFile += 3;
96017     for(iEntry=8; (c = zFile[iFile])!=0 && c!='.'; iFile++){
96018       if( sqlite3Isalpha(c) ){
96019         zAltEntry[iEntry++] = (char)sqlite3UpperToLower[(unsigned)c];
96020       }
96021     }
96022     memcpy(zAltEntry+iEntry, "_init", 6);
96023     zEntry = zAltEntry;
96024     xInit = (int(*)(sqlite3*,char**,const sqlite3_api_routines*))
96025                      sqlite3OsDlSym(pVfs, handle, zEntry);
96026   }
96027   if( xInit==0 ){
96028     if( pzErrMsg ){
96029       nMsg += sqlite3Strlen30(zEntry);
96030       *pzErrMsg = zErrmsg = sqlite3_malloc(nMsg);
96031       if( zErrmsg ){
96032         sqlite3_snprintf(nMsg, zErrmsg,
96033             "no entry point [%s] in shared library [%s]", zEntry, zFile);
96034         sqlite3OsDlError(pVfs, nMsg-1, zErrmsg);
96035       }
96036     }
96037     sqlite3OsDlClose(pVfs, handle);
96038     sqlite3_free(zAltEntry);
96039     return SQLITE_ERROR;
96040   }
96041   sqlite3_free(zAltEntry);
96042   if( xInit(db, &zErrmsg, &sqlite3Apis) ){
96043     if( pzErrMsg ){
96044       *pzErrMsg = sqlite3_mprintf("error during initialization: %s", zErrmsg);
96045     }
96046     sqlite3_free(zErrmsg);
96047     sqlite3OsDlClose(pVfs, handle);
96048     return SQLITE_ERROR;
96049   }
96050 
96051   /* Append the new shared library handle to the db->aExtension array. */
96052   aHandle = sqlite3DbMallocZero(db, sizeof(handle)*(db->nExtension+1));
96053   if( aHandle==0 ){
96054     return SQLITE_NOMEM;
96055   }
96056   if( db->nExtension>0 ){
96057     memcpy(aHandle, db->aExtension, sizeof(handle)*db->nExtension);
96058   }
96059   sqlite3DbFree(db, db->aExtension);
96060   db->aExtension = aHandle;
96061 
96062   db->aExtension[db->nExtension++] = handle;
96063   return SQLITE_OK;
96064 }
96065 SQLITE_API int sqlite3_load_extension(
96066   sqlite3 *db,          /* Load the extension into this database connection */
96067   const char *zFile,    /* Name of the shared library containing extension */
96068   const char *zProc,    /* Entry point.  Use "sqlite3_extension_init" if 0 */
96069   char **pzErrMsg       /* Put error message here if not 0 */
96070 ){
96071   int rc;
96072   sqlite3_mutex_enter(db->mutex);
96073   rc = sqlite3LoadExtension(db, zFile, zProc, pzErrMsg);
96074   rc = sqlite3ApiExit(db, rc);
96075   sqlite3_mutex_leave(db->mutex);
96076   return rc;
96077 }
96078 
96079 /*
96080 ** Call this routine when the database connection is closing in order
96081 ** to clean up loaded extensions
96082 */
96083 SQLITE_PRIVATE void sqlite3CloseExtensions(sqlite3 *db){
96084   int i;
96085   assert( sqlite3_mutex_held(db->mutex) );
96086   for(i=0; i<db->nExtension; i++){
96087     sqlite3OsDlClose(db->pVfs, db->aExtension[i]);
96088   }
96089   sqlite3DbFree(db, db->aExtension);
96090 }
96091 
96092 /*
96093 ** Enable or disable extension loading.  Extension loading is disabled by
96094 ** default so as not to open security holes in older applications.
96095 */
96096 SQLITE_API int sqlite3_enable_load_extension(sqlite3 *db, int onoff){
96097   sqlite3_mutex_enter(db->mutex);
96098   if( onoff ){
96099     db->flags |= SQLITE_LoadExtension;
96100   }else{
96101     db->flags &= ~SQLITE_LoadExtension;
96102   }
96103   sqlite3_mutex_leave(db->mutex);
96104   return SQLITE_OK;
96105 }
96106 
96107 #endif /* SQLITE_OMIT_LOAD_EXTENSION */
96108 
96109 /*
96110 ** The auto-extension code added regardless of whether or not extension
96111 ** loading is supported.  We need a dummy sqlite3Apis pointer for that
96112 ** code if regular extension loading is not available.  This is that
96113 ** dummy pointer.
96114 */
96115 #ifdef SQLITE_OMIT_LOAD_EXTENSION
96116 static const sqlite3_api_routines sqlite3Apis = { 0 };
96117 #endif
96118 
96119 
96120 /*
96121 ** The following object holds the list of automatically loaded
96122 ** extensions.
96123 **
96124 ** This list is shared across threads.  The SQLITE_MUTEX_STATIC_MASTER
96125 ** mutex must be held while accessing this list.
96126 */
96127 typedef struct sqlite3AutoExtList sqlite3AutoExtList;
96128 static SQLITE_WSD struct sqlite3AutoExtList {
96129   int nExt;              /* Number of entries in aExt[] */          
96130   void (**aExt)(void);   /* Pointers to the extension init functions */
96131 } sqlite3Autoext = { 0, 0 };
96132 
96133 /* The "wsdAutoext" macro will resolve to the autoextension
96134 ** state vector.  If writable static data is unsupported on the target,
96135 ** we have to locate the state vector at run-time.  In the more common
96136 ** case where writable static data is supported, wsdStat can refer directly
96137 ** to the "sqlite3Autoext" state vector declared above.
96138 */
96139 #ifdef SQLITE_OMIT_WSD
96140 # define wsdAutoextInit \
96141   sqlite3AutoExtList *x = &GLOBAL(sqlite3AutoExtList,sqlite3Autoext)
96142 # define wsdAutoext x[0]
96143 #else
96144 # define wsdAutoextInit
96145 # define wsdAutoext sqlite3Autoext
96146 #endif
96147 
96148 
96149 /*
96150 ** Register a statically linked extension that is automatically
96151 ** loaded by every new database connection.
96152 */
96153 SQLITE_API int sqlite3_auto_extension(void (*xInit)(void)){
96154   int rc = SQLITE_OK;
96155 #ifndef SQLITE_OMIT_AUTOINIT
96156   rc = sqlite3_initialize();
96157   if( rc ){
96158     return rc;
96159   }else
96160 #endif
96161   {
96162     int i;
96163 #if SQLITE_THREADSAFE
96164     sqlite3_mutex *mutex = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER);
96165 #endif
96166     wsdAutoextInit;
96167     sqlite3_mutex_enter(mutex);
96168     for(i=0; i<wsdAutoext.nExt; i++){
96169       if( wsdAutoext.aExt[i]==xInit ) break;
96170     }
96171     if( i==wsdAutoext.nExt ){
96172       int nByte = (wsdAutoext.nExt+1)*sizeof(wsdAutoext.aExt[0]);
96173       void (**aNew)(void);
96174       aNew = sqlite3_realloc(wsdAutoext.aExt, nByte);
96175       if( aNew==0 ){
96176         rc = SQLITE_NOMEM;
96177       }else{
96178         wsdAutoext.aExt = aNew;
96179         wsdAutoext.aExt[wsdAutoext.nExt] = xInit;
96180         wsdAutoext.nExt++;
96181       }
96182     }
96183     sqlite3_mutex_leave(mutex);
96184     assert( (rc&0xff)==rc );
96185     return rc;
96186   }
96187 }
96188 
96189 /*
96190 ** Cancel a prior call to sqlite3_auto_extension.  Remove xInit from the
96191 ** set of routines that is invoked for each new database connection, if it
96192 ** is currently on the list.  If xInit is not on the list, then this
96193 ** routine is a no-op.
96194 **
96195 ** Return 1 if xInit was found on the list and removed.  Return 0 if xInit
96196 ** was not on the list.
96197 */
96198 SQLITE_API int sqlite3_cancel_auto_extension(void (*xInit)(void)){
96199 #if SQLITE_THREADSAFE
96200   sqlite3_mutex *mutex = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER);
96201 #endif
96202   int i;
96203   int n = 0;
96204   wsdAutoextInit;
96205   sqlite3_mutex_enter(mutex);
96206   for(i=wsdAutoext.nExt-1; i>=0; i--){
96207     if( wsdAutoext.aExt[i]==xInit ){
96208       wsdAutoext.nExt--;
96209       wsdAutoext.aExt[i] = wsdAutoext.aExt[wsdAutoext.nExt];
96210       n++;
96211       break;
96212     }
96213   }
96214   sqlite3_mutex_leave(mutex);
96215   return n;
96216 }
96217 
96218 /*
96219 ** Reset the automatic extension loading mechanism.
96220 */
96221 SQLITE_API void sqlite3_reset_auto_extension(void){
96222 #ifndef SQLITE_OMIT_AUTOINIT
96223   if( sqlite3_initialize()==SQLITE_OK )
96224 #endif
96225   {
96226 #if SQLITE_THREADSAFE
96227     sqlite3_mutex *mutex = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER);
96228 #endif
96229     wsdAutoextInit;
96230     sqlite3_mutex_enter(mutex);
96231     sqlite3_free(wsdAutoext.aExt);
96232     wsdAutoext.aExt = 0;
96233     wsdAutoext.nExt = 0;
96234     sqlite3_mutex_leave(mutex);
96235   }
96236 }
96237 
96238 /*
96239 ** Load all automatic extensions.
96240 **
96241 ** If anything goes wrong, set an error in the database connection.
96242 */
96243 SQLITE_PRIVATE void sqlite3AutoLoadExtensions(sqlite3 *db){
96244   int i;
96245   int go = 1;
96246   int rc;
96247   int (*xInit)(sqlite3*,char**,const sqlite3_api_routines*);
96248 
96249   wsdAutoextInit;
96250   if( wsdAutoext.nExt==0 ){
96251     /* Common case: early out without every having to acquire a mutex */
96252     return;
96253   }
96254   for(i=0; go; i++){
96255     char *zErrmsg;
96256 #if SQLITE_THREADSAFE
96257     sqlite3_mutex *mutex = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER);
96258 #endif
96259     sqlite3_mutex_enter(mutex);
96260     if( i>=wsdAutoext.nExt ){
96261       xInit = 0;
96262       go = 0;
96263     }else{
96264       xInit = (int(*)(sqlite3*,char**,const sqlite3_api_routines*))
96265               wsdAutoext.aExt[i];
96266     }
96267     sqlite3_mutex_leave(mutex);
96268     zErrmsg = 0;
96269     if( xInit && (rc = xInit(db, &zErrmsg, &sqlite3Apis))!=0 ){
96270       sqlite3Error(db, rc,
96271             "automatic extension loading failed: %s", zErrmsg);
96272       go = 0;
96273     }
96274     sqlite3_free(zErrmsg);
96275   }
96276 }
96277 
96278 /************** End of loadext.c *********************************************/
96279 /************** Begin file pragma.c ******************************************/
96280 /*
96281 ** 2003 April 6
96282 **
96283 ** The author disclaims copyright to this source code.  In place of
96284 ** a legal notice, here is a blessing:
96285 **
96286 **    May you do good and not evil.
96287 **    May you find forgiveness for yourself and forgive others.
96288 **    May you share freely, never taking more than you give.
96289 **
96290 *************************************************************************
96291 ** This file contains code used to implement the PRAGMA command.
96292 */
96293 
96294 #if !defined(SQLITE_ENABLE_LOCKING_STYLE)
96295 #  if defined(__APPLE__)
96296 #    define SQLITE_ENABLE_LOCKING_STYLE 1
96297 #  else
96298 #    define SQLITE_ENABLE_LOCKING_STYLE 0
96299 #  endif
96300 #endif
96301 
96302 /***************************************************************************
96303 ** The next block of code, including the PragTyp_XXXX macro definitions and
96304 ** the aPragmaName[] object is composed of generated code. DO NOT EDIT.
96305 **
96306 ** To add new pragmas, edit the code in ../tool/mkpragmatab.tcl and rerun
96307 ** that script.  Then copy/paste the output in place of the following:
96308 */
96309 #define PragTyp_HEADER_VALUE                   0
96310 #define PragTyp_AUTO_VACUUM                    1
96311 #define PragTyp_FLAG                           2
96312 #define PragTyp_BUSY_TIMEOUT                   3
96313 #define PragTyp_CACHE_SIZE                     4
96314 #define PragTyp_CASE_SENSITIVE_LIKE            5
96315 #define PragTyp_COLLATION_LIST                 6
96316 #define PragTyp_COMPILE_OPTIONS                7
96317 #define PragTyp_DATA_STORE_DIRECTORY           8
96318 #define PragTyp_DATABASE_LIST                  9
96319 #define PragTyp_DEFAULT_CACHE_SIZE            10
96320 #define PragTyp_ENCODING                      11
96321 #define PragTyp_FOREIGN_KEY_CHECK             12
96322 #define PragTyp_FOREIGN_KEY_LIST              13
96323 #define PragTyp_INCREMENTAL_VACUUM            14
96324 #define PragTyp_INDEX_INFO                    15
96325 #define PragTyp_INDEX_LIST                    16
96326 #define PragTyp_INTEGRITY_CHECK               17
96327 #define PragTyp_JOURNAL_MODE                  18
96328 #define PragTyp_JOURNAL_SIZE_LIMIT            19
96329 #define PragTyp_LOCK_PROXY_FILE               20
96330 #define PragTyp_LOCKING_MODE                  21
96331 #define PragTyp_PAGE_COUNT                    22
96332 #define PragTyp_MMAP_SIZE                     23
96333 #define PragTyp_PAGE_SIZE                     24
96334 #define PragTyp_SECURE_DELETE                 25
96335 #define PragTyp_SHRINK_MEMORY                 26
96336 #define PragTyp_SOFT_HEAP_LIMIT               27
96337 #define PragTyp_STATS                         28
96338 #define PragTyp_SYNCHRONOUS                   29
96339 #define PragTyp_TABLE_INFO                    30
96340 #define PragTyp_TEMP_STORE                    31
96341 #define PragTyp_TEMP_STORE_DIRECTORY          32
96342 #define PragTyp_WAL_AUTOCHECKPOINT            33
96343 #define PragTyp_WAL_CHECKPOINT                34
96344 #define PragTyp_ACTIVATE_EXTENSIONS           35
96345 #define PragTyp_HEXKEY                        36
96346 #define PragTyp_KEY                           37
96347 #define PragTyp_REKEY                         38
96348 #define PragTyp_LOCK_STATUS                   39
96349 #define PragTyp_PARSER_TRACE                  40
96350 #define PragFlag_NeedSchema           0x01
96351 static const struct sPragmaNames {
96352   const char *const zName;  /* Name of pragma */
96353   u8 ePragTyp;              /* PragTyp_XXX value */
96354   u8 mPragFlag;             /* Zero or more PragFlag_XXX values */
96355   u32 iArg;                 /* Extra argument */
96356 } aPragmaNames[] = {
96357 #if defined(SQLITE_HAS_CODEC) || defined(SQLITE_ENABLE_CEROD)
96358   { /* zName:     */ "activate_extensions",
96359     /* ePragTyp:  */ PragTyp_ACTIVATE_EXTENSIONS,
96360     /* ePragFlag: */ 0,
96361     /* iArg:      */ 0 },
96362 #endif
96363 #if !defined(SQLITE_OMIT_SCHEMA_VERSION_PRAGMAS)
96364   { /* zName:     */ "application_id",
96365     /* ePragTyp:  */ PragTyp_HEADER_VALUE,
96366     /* ePragFlag: */ 0,
96367     /* iArg:      */ 0 },
96368 #endif
96369 #if !defined(SQLITE_OMIT_AUTOVACUUM)
96370   { /* zName:     */ "auto_vacuum",
96371     /* ePragTyp:  */ PragTyp_AUTO_VACUUM,
96372     /* ePragFlag: */ PragFlag_NeedSchema,
96373     /* iArg:      */ 0 },
96374 #endif
96375 #if !defined(SQLITE_OMIT_FLAG_PRAGMAS)
96376 #if !defined(SQLITE_OMIT_AUTOMATIC_INDEX)
96377   { /* zName:     */ "automatic_index",
96378     /* ePragTyp:  */ PragTyp_FLAG,
96379     /* ePragFlag: */ 0,
96380     /* iArg:      */ SQLITE_AutoIndex },
96381 #endif
96382 #endif
96383   { /* zName:     */ "busy_timeout",
96384     /* ePragTyp:  */ PragTyp_BUSY_TIMEOUT,
96385     /* ePragFlag: */ 0,
96386     /* iArg:      */ 0 },
96387 #if !defined(SQLITE_OMIT_PAGER_PRAGMAS)
96388   { /* zName:     */ "cache_size",
96389     /* ePragTyp:  */ PragTyp_CACHE_SIZE,
96390     /* ePragFlag: */ PragFlag_NeedSchema,
96391     /* iArg:      */ 0 },
96392 #endif
96393 #if !defined(SQLITE_OMIT_FLAG_PRAGMAS)
96394   { /* zName:     */ "cache_spill",
96395     /* ePragTyp:  */ PragTyp_FLAG,
96396     /* ePragFlag: */ 0,
96397     /* iArg:      */ SQLITE_CacheSpill },
96398 #endif
96399   { /* zName:     */ "case_sensitive_like",
96400     /* ePragTyp:  */ PragTyp_CASE_SENSITIVE_LIKE,
96401     /* ePragFlag: */ 0,
96402     /* iArg:      */ 0 },
96403 #if !defined(SQLITE_OMIT_FLAG_PRAGMAS)
96404   { /* zName:     */ "checkpoint_fullfsync",
96405     /* ePragTyp:  */ PragTyp_FLAG,
96406     /* ePragFlag: */ 0,
96407     /* iArg:      */ SQLITE_CkptFullFSync },
96408 #endif
96409 #if !defined(SQLITE_OMIT_SCHEMA_PRAGMAS)
96410   { /* zName:     */ "collation_list",
96411     /* ePragTyp:  */ PragTyp_COLLATION_LIST,
96412     /* ePragFlag: */ 0,
96413     /* iArg:      */ 0 },
96414 #endif
96415 #if !defined(SQLITE_OMIT_COMPILEOPTION_DIAGS)
96416   { /* zName:     */ "compile_options",
96417     /* ePragTyp:  */ PragTyp_COMPILE_OPTIONS,
96418     /* ePragFlag: */ 0,
96419     /* iArg:      */ 0 },
96420 #endif
96421 #if !defined(SQLITE_OMIT_FLAG_PRAGMAS)
96422   { /* zName:     */ "count_changes",
96423     /* ePragTyp:  */ PragTyp_FLAG,
96424     /* ePragFlag: */ 0,
96425     /* iArg:      */ SQLITE_CountRows },
96426 #endif
96427 #if !defined(SQLITE_OMIT_PAGER_PRAGMAS) && SQLITE_OS_WIN
96428   { /* zName:     */ "data_store_directory",
96429     /* ePragTyp:  */ PragTyp_DATA_STORE_DIRECTORY,
96430     /* ePragFlag: */ 0,
96431     /* iArg:      */ 0 },
96432 #endif
96433 #if !defined(SQLITE_OMIT_SCHEMA_PRAGMAS)
96434   { /* zName:     */ "database_list",
96435     /* ePragTyp:  */ PragTyp_DATABASE_LIST,
96436     /* ePragFlag: */ PragFlag_NeedSchema,
96437     /* iArg:      */ 0 },
96438 #endif
96439 #if !defined(SQLITE_OMIT_PAGER_PRAGMAS) && !defined(SQLITE_OMIT_DEPRECATED)
96440   { /* zName:     */ "default_cache_size",
96441     /* ePragTyp:  */ PragTyp_DEFAULT_CACHE_SIZE,
96442     /* ePragFlag: */ PragFlag_NeedSchema,
96443     /* iArg:      */ 0 },
96444 #endif
96445 #if !defined(SQLITE_OMIT_FLAG_PRAGMAS)
96446 #if !defined(SQLITE_OMIT_FOREIGN_KEY) && !defined(SQLITE_OMIT_TRIGGER)
96447   { /* zName:     */ "defer_foreign_keys",
96448     /* ePragTyp:  */ PragTyp_FLAG,
96449     /* ePragFlag: */ 0,
96450     /* iArg:      */ SQLITE_DeferFKs },
96451 #endif
96452 #endif
96453 #if !defined(SQLITE_OMIT_FLAG_PRAGMAS)
96454   { /* zName:     */ "empty_result_callbacks",
96455     /* ePragTyp:  */ PragTyp_FLAG,
96456     /* ePragFlag: */ 0,
96457     /* iArg:      */ SQLITE_NullCallback },
96458 #endif
96459 #if !defined(SQLITE_OMIT_UTF16)
96460   { /* zName:     */ "encoding",
96461     /* ePragTyp:  */ PragTyp_ENCODING,
96462     /* ePragFlag: */ 0,
96463     /* iArg:      */ 0 },
96464 #endif
96465 #if !defined(SQLITE_OMIT_FOREIGN_KEY) && !defined(SQLITE_OMIT_TRIGGER)
96466   { /* zName:     */ "foreign_key_check",
96467     /* ePragTyp:  */ PragTyp_FOREIGN_KEY_CHECK,
96468     /* ePragFlag: */ PragFlag_NeedSchema,
96469     /* iArg:      */ 0 },
96470 #endif
96471 #if !defined(SQLITE_OMIT_FOREIGN_KEY)
96472   { /* zName:     */ "foreign_key_list",
96473     /* ePragTyp:  */ PragTyp_FOREIGN_KEY_LIST,
96474     /* ePragFlag: */ PragFlag_NeedSchema,
96475     /* iArg:      */ 0 },
96476 #endif
96477 #if !defined(SQLITE_OMIT_FLAG_PRAGMAS)
96478 #if !defined(SQLITE_OMIT_FOREIGN_KEY) && !defined(SQLITE_OMIT_TRIGGER)
96479   { /* zName:     */ "foreign_keys",
96480     /* ePragTyp:  */ PragTyp_FLAG,
96481     /* ePragFlag: */ 0,
96482     /* iArg:      */ SQLITE_ForeignKeys },
96483 #endif
96484 #endif
96485 #if !defined(SQLITE_OMIT_SCHEMA_VERSION_PRAGMAS)
96486   { /* zName:     */ "freelist_count",
96487     /* ePragTyp:  */ PragTyp_HEADER_VALUE,
96488     /* ePragFlag: */ 0,
96489     /* iArg:      */ 0 },
96490 #endif
96491 #if !defined(SQLITE_OMIT_FLAG_PRAGMAS)
96492   { /* zName:     */ "full_column_names",
96493     /* ePragTyp:  */ PragTyp_FLAG,
96494     /* ePragFlag: */ 0,
96495     /* iArg:      */ SQLITE_FullColNames },
96496   { /* zName:     */ "fullfsync",
96497     /* ePragTyp:  */ PragTyp_FLAG,
96498     /* ePragFlag: */ 0,
96499     /* iArg:      */ SQLITE_FullFSync },
96500 #endif
96501 #if defined(SQLITE_HAS_CODEC)
96502   { /* zName:     */ "hexkey",
96503     /* ePragTyp:  */ PragTyp_HEXKEY,
96504     /* ePragFlag: */ 0,
96505     /* iArg:      */ 0 },
96506   { /* zName:     */ "hexrekey",
96507     /* ePragTyp:  */ PragTyp_HEXKEY,
96508     /* ePragFlag: */ 0,
96509     /* iArg:      */ 0 },
96510 #endif
96511 #if !defined(SQLITE_OMIT_FLAG_PRAGMAS)
96512 #if !defined(SQLITE_OMIT_CHECK)
96513   { /* zName:     */ "ignore_check_constraints",
96514     /* ePragTyp:  */ PragTyp_FLAG,
96515     /* ePragFlag: */ 0,
96516     /* iArg:      */ SQLITE_IgnoreChecks },
96517 #endif
96518 #endif
96519 #if !defined(SQLITE_OMIT_AUTOVACUUM)
96520   { /* zName:     */ "incremental_vacuum",
96521     /* ePragTyp:  */ PragTyp_INCREMENTAL_VACUUM,
96522     /* ePragFlag: */ PragFlag_NeedSchema,
96523     /* iArg:      */ 0 },
96524 #endif
96525 #if !defined(SQLITE_OMIT_SCHEMA_PRAGMAS)
96526   { /* zName:     */ "index_info",
96527     /* ePragTyp:  */ PragTyp_INDEX_INFO,
96528     /* ePragFlag: */ PragFlag_NeedSchema,
96529     /* iArg:      */ 0 },
96530   { /* zName:     */ "index_list",
96531     /* ePragTyp:  */ PragTyp_INDEX_LIST,
96532     /* ePragFlag: */ PragFlag_NeedSchema,
96533     /* iArg:      */ 0 },
96534 #endif
96535 #if !defined(SQLITE_OMIT_INTEGRITY_CHECK)
96536   { /* zName:     */ "integrity_check",
96537     /* ePragTyp:  */ PragTyp_INTEGRITY_CHECK,
96538     /* ePragFlag: */ PragFlag_NeedSchema,
96539     /* iArg:      */ 0 },
96540 #endif
96541 #if !defined(SQLITE_OMIT_PAGER_PRAGMAS)
96542   { /* zName:     */ "journal_mode",
96543     /* ePragTyp:  */ PragTyp_JOURNAL_MODE,
96544     /* ePragFlag: */ PragFlag_NeedSchema,
96545     /* iArg:      */ 0 },
96546   { /* zName:     */ "journal_size_limit",
96547     /* ePragTyp:  */ PragTyp_JOURNAL_SIZE_LIMIT,
96548     /* ePragFlag: */ 0,
96549     /* iArg:      */ 0 },
96550 #endif
96551 #if defined(SQLITE_HAS_CODEC)
96552   { /* zName:     */ "key",
96553     /* ePragTyp:  */ PragTyp_KEY,
96554     /* ePragFlag: */ 0,
96555     /* iArg:      */ 0 },
96556 #endif
96557 #if !defined(SQLITE_OMIT_FLAG_PRAGMAS)
96558   { /* zName:     */ "legacy_file_format",
96559     /* ePragTyp:  */ PragTyp_FLAG,
96560     /* ePragFlag: */ 0,
96561     /* iArg:      */ SQLITE_LegacyFileFmt },
96562 #endif
96563 #if !defined(SQLITE_OMIT_PAGER_PRAGMAS) && SQLITE_ENABLE_LOCKING_STYLE
96564   { /* zName:     */ "lock_proxy_file",
96565     /* ePragTyp:  */ PragTyp_LOCK_PROXY_FILE,
96566     /* ePragFlag: */ 0,
96567     /* iArg:      */ 0 },
96568 #endif
96569 #if defined(SQLITE_DEBUG) || defined(SQLITE_TEST)
96570   { /* zName:     */ "lock_status",
96571     /* ePragTyp:  */ PragTyp_LOCK_STATUS,
96572     /* ePragFlag: */ 0,
96573     /* iArg:      */ 0 },
96574 #endif
96575 #if !defined(SQLITE_OMIT_PAGER_PRAGMAS)
96576   { /* zName:     */ "locking_mode",
96577     /* ePragTyp:  */ PragTyp_LOCKING_MODE,
96578     /* ePragFlag: */ 0,
96579     /* iArg:      */ 0 },
96580   { /* zName:     */ "max_page_count",
96581     /* ePragTyp:  */ PragTyp_PAGE_COUNT,
96582     /* ePragFlag: */ PragFlag_NeedSchema,
96583     /* iArg:      */ 0 },
96584   { /* zName:     */ "mmap_size",
96585     /* ePragTyp:  */ PragTyp_MMAP_SIZE,
96586     /* ePragFlag: */ 0,
96587     /* iArg:      */ 0 },
96588   { /* zName:     */ "page_count",
96589     /* ePragTyp:  */ PragTyp_PAGE_COUNT,
96590     /* ePragFlag: */ PragFlag_NeedSchema,
96591     /* iArg:      */ 0 },
96592   { /* zName:     */ "page_size",
96593     /* ePragTyp:  */ PragTyp_PAGE_SIZE,
96594     /* ePragFlag: */ 0,
96595     /* iArg:      */ 0 },
96596 #endif
96597 #if defined(SQLITE_DEBUG)
96598   { /* zName:     */ "parser_trace",
96599     /* ePragTyp:  */ PragTyp_PARSER_TRACE,
96600     /* ePragFlag: */ 0,
96601     /* iArg:      */ 0 },
96602 #endif
96603 #if !defined(SQLITE_OMIT_FLAG_PRAGMAS)
96604   { /* zName:     */ "query_only",
96605     /* ePragTyp:  */ PragTyp_FLAG,
96606     /* ePragFlag: */ 0,
96607     /* iArg:      */ SQLITE_QueryOnly },
96608 #endif
96609 #if !defined(SQLITE_OMIT_INTEGRITY_CHECK)
96610   { /* zName:     */ "quick_check",
96611     /* ePragTyp:  */ PragTyp_INTEGRITY_CHECK,
96612     /* ePragFlag: */ PragFlag_NeedSchema,
96613     /* iArg:      */ 0 },
96614 #endif
96615 #if !defined(SQLITE_OMIT_FLAG_PRAGMAS)
96616   { /* zName:     */ "read_uncommitted",
96617     /* ePragTyp:  */ PragTyp_FLAG,
96618     /* ePragFlag: */ 0,
96619     /* iArg:      */ SQLITE_ReadUncommitted },
96620   { /* zName:     */ "recursive_triggers",
96621     /* ePragTyp:  */ PragTyp_FLAG,
96622     /* ePragFlag: */ 0,
96623     /* iArg:      */ SQLITE_RecTriggers },
96624 #endif
96625 #if defined(SQLITE_HAS_CODEC)
96626   { /* zName:     */ "rekey",
96627     /* ePragTyp:  */ PragTyp_REKEY,
96628     /* ePragFlag: */ 0,
96629     /* iArg:      */ 0 },
96630 #endif
96631 #if !defined(SQLITE_OMIT_FLAG_PRAGMAS)
96632   { /* zName:     */ "reverse_unordered_selects",
96633     /* ePragTyp:  */ PragTyp_FLAG,
96634     /* ePragFlag: */ 0,
96635     /* iArg:      */ SQLITE_ReverseOrder },
96636 #endif
96637 #if !defined(SQLITE_OMIT_SCHEMA_VERSION_PRAGMAS)
96638   { /* zName:     */ "schema_version",
96639     /* ePragTyp:  */ PragTyp_HEADER_VALUE,
96640     /* ePragFlag: */ 0,
96641     /* iArg:      */ 0 },
96642 #endif
96643 #if !defined(SQLITE_OMIT_PAGER_PRAGMAS)
96644   { /* zName:     */ "secure_delete",
96645     /* ePragTyp:  */ PragTyp_SECURE_DELETE,
96646     /* ePragFlag: */ 0,
96647     /* iArg:      */ 0 },
96648 #endif
96649 #if !defined(SQLITE_OMIT_FLAG_PRAGMAS)
96650   { /* zName:     */ "short_column_names",
96651     /* ePragTyp:  */ PragTyp_FLAG,
96652     /* ePragFlag: */ 0,
96653     /* iArg:      */ SQLITE_ShortColNames },
96654 #endif
96655   { /* zName:     */ "shrink_memory",
96656     /* ePragTyp:  */ PragTyp_SHRINK_MEMORY,
96657     /* ePragFlag: */ 0,
96658     /* iArg:      */ 0 },
96659   { /* zName:     */ "soft_heap_limit",
96660     /* ePragTyp:  */ PragTyp_SOFT_HEAP_LIMIT,
96661     /* ePragFlag: */ 0,
96662     /* iArg:      */ 0 },
96663 #if !defined(SQLITE_OMIT_FLAG_PRAGMAS)
96664 #if defined(SQLITE_DEBUG)
96665   { /* zName:     */ "sql_trace",
96666     /* ePragTyp:  */ PragTyp_FLAG,
96667     /* ePragFlag: */ 0,
96668     /* iArg:      */ SQLITE_SqlTrace },
96669 #endif
96670 #endif
96671 #if !defined(SQLITE_OMIT_SCHEMA_PRAGMAS)
96672   { /* zName:     */ "stats",
96673     /* ePragTyp:  */ PragTyp_STATS,
96674     /* ePragFlag: */ PragFlag_NeedSchema,
96675     /* iArg:      */ 0 },
96676 #endif
96677 #if !defined(SQLITE_OMIT_PAGER_PRAGMAS)
96678   { /* zName:     */ "synchronous",
96679     /* ePragTyp:  */ PragTyp_SYNCHRONOUS,
96680     /* ePragFlag: */ PragFlag_NeedSchema,
96681     /* iArg:      */ 0 },
96682 #endif
96683 #if !defined(SQLITE_OMIT_SCHEMA_PRAGMAS)
96684   { /* zName:     */ "table_info",
96685     /* ePragTyp:  */ PragTyp_TABLE_INFO,
96686     /* ePragFlag: */ PragFlag_NeedSchema,
96687     /* iArg:      */ 0 },
96688 #endif
96689 #if !defined(SQLITE_OMIT_PAGER_PRAGMAS)
96690   { /* zName:     */ "temp_store",
96691     /* ePragTyp:  */ PragTyp_TEMP_STORE,
96692     /* ePragFlag: */ 0,
96693     /* iArg:      */ 0 },
96694   { /* zName:     */ "temp_store_directory",
96695     /* ePragTyp:  */ PragTyp_TEMP_STORE_DIRECTORY,
96696     /* ePragFlag: */ 0,
96697     /* iArg:      */ 0 },
96698 #endif
96699 #if !defined(SQLITE_OMIT_SCHEMA_VERSION_PRAGMAS)
96700   { /* zName:     */ "user_version",
96701     /* ePragTyp:  */ PragTyp_HEADER_VALUE,
96702     /* ePragFlag: */ 0,
96703     /* iArg:      */ 0 },
96704 #endif
96705 #if !defined(SQLITE_OMIT_FLAG_PRAGMAS)
96706 #if defined(SQLITE_DEBUG)
96707   { /* zName:     */ "vdbe_addoptrace",
96708     /* ePragTyp:  */ PragTyp_FLAG,
96709     /* ePragFlag: */ 0,
96710     /* iArg:      */ SQLITE_VdbeAddopTrace },
96711   { /* zName:     */ "vdbe_debug",
96712     /* ePragTyp:  */ PragTyp_FLAG,
96713     /* ePragFlag: */ 0,
96714     /* iArg:      */ SQLITE_SqlTrace|SQLITE_VdbeListing|SQLITE_VdbeTrace },
96715   { /* zName:     */ "vdbe_eqp",
96716     /* ePragTyp:  */ PragTyp_FLAG,
96717     /* ePragFlag: */ 0,
96718     /* iArg:      */ SQLITE_VdbeEQP },
96719   { /* zName:     */ "vdbe_listing",
96720     /* ePragTyp:  */ PragTyp_FLAG,
96721     /* ePragFlag: */ 0,
96722     /* iArg:      */ SQLITE_VdbeListing },
96723   { /* zName:     */ "vdbe_trace",
96724     /* ePragTyp:  */ PragTyp_FLAG,
96725     /* ePragFlag: */ 0,
96726     /* iArg:      */ SQLITE_VdbeTrace },
96727 #endif
96728 #endif
96729 #if !defined(SQLITE_OMIT_WAL)
96730   { /* zName:     */ "wal_autocheckpoint",
96731     /* ePragTyp:  */ PragTyp_WAL_AUTOCHECKPOINT,
96732     /* ePragFlag: */ 0,
96733     /* iArg:      */ 0 },
96734   { /* zName:     */ "wal_checkpoint",
96735     /* ePragTyp:  */ PragTyp_WAL_CHECKPOINT,
96736     /* ePragFlag: */ PragFlag_NeedSchema,
96737     /* iArg:      */ 0 },
96738 #endif
96739 #if !defined(SQLITE_OMIT_FLAG_PRAGMAS)
96740   { /* zName:     */ "writable_schema",
96741     /* ePragTyp:  */ PragTyp_FLAG,
96742     /* ePragFlag: */ 0,
96743     /* iArg:      */ SQLITE_WriteSchema|SQLITE_RecoveryMode },
96744 #endif
96745 };
96746 /* Number of pragmas: 56 on by default, 69 total. */
96747 /* End of the automatically generated pragma table.
96748 ***************************************************************************/
96749 
96750 /*
96751 ** Interpret the given string as a safety level.  Return 0 for OFF,
96752 ** 1 for ON or NORMAL and 2 for FULL.  Return 1 for an empty or 
96753 ** unrecognized string argument.  The FULL option is disallowed
96754 ** if the omitFull parameter it 1.
96755 **
96756 ** Note that the values returned are one less that the values that
96757 ** should be passed into sqlite3BtreeSetSafetyLevel().  The is done
96758 ** to support legacy SQL code.  The safety level used to be boolean
96759 ** and older scripts may have used numbers 0 for OFF and 1 for ON.
96760 */
96761 static u8 getSafetyLevel(const char *z, int omitFull, int dflt){
96762                              /* 123456789 123456789 */
96763   static const char zText[] = "onoffalseyestruefull";
96764   static const u8 iOffset[] = {0, 1, 2, 4, 9, 12, 16};
96765   static const u8 iLength[] = {2, 2, 3, 5, 3, 4, 4};
96766   static const u8 iValue[] =  {1, 0, 0, 0, 1, 1, 2};
96767   int i, n;
96768   if( sqlite3Isdigit(*z) ){
96769     return (u8)sqlite3Atoi(z);
96770   }
96771   n = sqlite3Strlen30(z);
96772   for(i=0; i<ArraySize(iLength)-omitFull; i++){
96773     if( iLength[i]==n && sqlite3StrNICmp(&zText[iOffset[i]],z,n)==0 ){
96774       return iValue[i];
96775     }
96776   }
96777   return dflt;
96778 }
96779 
96780 /*
96781 ** Interpret the given string as a boolean value.
96782 */
96783 SQLITE_PRIVATE u8 sqlite3GetBoolean(const char *z, int dflt){
96784   return getSafetyLevel(z,1,dflt)!=0;
96785 }
96786 
96787 /* The sqlite3GetBoolean() function is used by other modules but the
96788 ** remainder of this file is specific to PRAGMA processing.  So omit
96789 ** the rest of the file if PRAGMAs are omitted from the build.
96790 */
96791 #if !defined(SQLITE_OMIT_PRAGMA)
96792 
96793 /*
96794 ** Interpret the given string as a locking mode value.
96795 */
96796 static int getLockingMode(const char *z){
96797   if( z ){
96798     if( 0==sqlite3StrICmp(z, "exclusive") ) return PAGER_LOCKINGMODE_EXCLUSIVE;
96799     if( 0==sqlite3StrICmp(z, "normal") ) return PAGER_LOCKINGMODE_NORMAL;
96800   }
96801   return PAGER_LOCKINGMODE_QUERY;
96802 }
96803 
96804 #ifndef SQLITE_OMIT_AUTOVACUUM
96805 /*
96806 ** Interpret the given string as an auto-vacuum mode value.
96807 **
96808 ** The following strings, "none", "full" and "incremental" are 
96809 ** acceptable, as are their numeric equivalents: 0, 1 and 2 respectively.
96810 */
96811 static int getAutoVacuum(const char *z){
96812   int i;
96813   if( 0==sqlite3StrICmp(z, "none") ) return BTREE_AUTOVACUUM_NONE;
96814   if( 0==sqlite3StrICmp(z, "full") ) return BTREE_AUTOVACUUM_FULL;
96815   if( 0==sqlite3StrICmp(z, "incremental") ) return BTREE_AUTOVACUUM_INCR;
96816   i = sqlite3Atoi(z);
96817   return (u8)((i>=0&&i<=2)?i:0);
96818 }
96819 #endif /* ifndef SQLITE_OMIT_AUTOVACUUM */
96820 
96821 #ifndef SQLITE_OMIT_PAGER_PRAGMAS
96822 /*
96823 ** Interpret the given string as a temp db location. Return 1 for file
96824 ** backed temporary databases, 2 for the Red-Black tree in memory database
96825 ** and 0 to use the compile-time default.
96826 */
96827 static int getTempStore(const char *z){
96828   if( z[0]>='0' && z[0]<='2' ){
96829     return z[0] - '0';
96830   }else if( sqlite3StrICmp(z, "file")==0 ){
96831     return 1;
96832   }else if( sqlite3StrICmp(z, "memory")==0 ){
96833     return 2;
96834   }else{
96835     return 0;
96836   }
96837 }
96838 #endif /* SQLITE_PAGER_PRAGMAS */
96839 
96840 #ifndef SQLITE_OMIT_PAGER_PRAGMAS
96841 /*
96842 ** Invalidate temp storage, either when the temp storage is changed
96843 ** from default, or when 'file' and the temp_store_directory has changed
96844 */
96845 static int invalidateTempStorage(Parse *pParse){
96846   sqlite3 *db = pParse->db;
96847   if( db->aDb[1].pBt!=0 ){
96848     if( !db->autoCommit || sqlite3BtreeIsInReadTrans(db->aDb[1].pBt) ){
96849       sqlite3ErrorMsg(pParse, "temporary storage cannot be changed "
96850         "from within a transaction");
96851       return SQLITE_ERROR;
96852     }
96853     sqlite3BtreeClose(db->aDb[1].pBt);
96854     db->aDb[1].pBt = 0;
96855     sqlite3ResetAllSchemasOfConnection(db);
96856   }
96857   return SQLITE_OK;
96858 }
96859 #endif /* SQLITE_PAGER_PRAGMAS */
96860 
96861 #ifndef SQLITE_OMIT_PAGER_PRAGMAS
96862 /*
96863 ** If the TEMP database is open, close it and mark the database schema
96864 ** as needing reloading.  This must be done when using the SQLITE_TEMP_STORE
96865 ** or DEFAULT_TEMP_STORE pragmas.
96866 */
96867 static int changeTempStorage(Parse *pParse, const char *zStorageType){
96868   int ts = getTempStore(zStorageType);
96869   sqlite3 *db = pParse->db;
96870   if( db->temp_store==ts ) return SQLITE_OK;
96871   if( invalidateTempStorage( pParse ) != SQLITE_OK ){
96872     return SQLITE_ERROR;
96873   }
96874   db->temp_store = (u8)ts;
96875   return SQLITE_OK;
96876 }
96877 #endif /* SQLITE_PAGER_PRAGMAS */
96878 
96879 /*
96880 ** Generate code to return a single integer value.
96881 */
96882 static void returnSingleInt(Parse *pParse, const char *zLabel, i64 value){
96883   Vdbe *v = sqlite3GetVdbe(pParse);
96884   int mem = ++pParse->nMem;
96885   i64 *pI64 = sqlite3DbMallocRaw(pParse->db, sizeof(value));
96886   if( pI64 ){
96887     memcpy(pI64, &value, sizeof(value));
96888   }
96889   sqlite3VdbeAddOp4(v, OP_Int64, 0, mem, 0, (char*)pI64, P4_INT64);
96890   sqlite3VdbeSetNumCols(v, 1);
96891   sqlite3VdbeSetColName(v, 0, COLNAME_NAME, zLabel, SQLITE_STATIC);
96892   sqlite3VdbeAddOp2(v, OP_ResultRow, mem, 1);
96893 }
96894 
96895 
96896 /*
96897 ** Set the safety_level and pager flags for pager iDb.  Or if iDb<0
96898 ** set these values for all pagers.
96899 */
96900 #ifndef SQLITE_OMIT_PAGER_PRAGMAS
96901 static void setAllPagerFlags(sqlite3 *db){
96902   if( db->autoCommit ){
96903     Db *pDb = db->aDb;
96904     int n = db->nDb;
96905     assert( SQLITE_FullFSync==PAGER_FULLFSYNC );
96906     assert( SQLITE_CkptFullFSync==PAGER_CKPT_FULLFSYNC );
96907     assert( SQLITE_CacheSpill==PAGER_CACHESPILL );
96908     assert( (PAGER_FULLFSYNC | PAGER_CKPT_FULLFSYNC | PAGER_CACHESPILL)
96909              ==  PAGER_FLAGS_MASK );
96910     assert( (pDb->safety_level & PAGER_SYNCHRONOUS_MASK)==pDb->safety_level );
96911     while( (n--) > 0 ){
96912       if( pDb->pBt ){
96913         sqlite3BtreeSetPagerFlags(pDb->pBt,
96914                  pDb->safety_level | (db->flags & PAGER_FLAGS_MASK) );
96915       }
96916       pDb++;
96917     }
96918   }
96919 }
96920 #else
96921 # define setAllPagerFlags(X)  /* no-op */
96922 #endif
96923 
96924 
96925 /*
96926 ** Return a human-readable name for a constraint resolution action.
96927 */
96928 #ifndef SQLITE_OMIT_FOREIGN_KEY
96929 static const char *actionName(u8 action){
96930   const char *zName;
96931   switch( action ){
96932     case OE_SetNull:  zName = "SET NULL";        break;
96933     case OE_SetDflt:  zName = "SET DEFAULT";     break;
96934     case OE_Cascade:  zName = "CASCADE";         break;
96935     case OE_Restrict: zName = "RESTRICT";        break;
96936     default:          zName = "NO ACTION";  
96937                       assert( action==OE_None ); break;
96938   }
96939   return zName;
96940 }
96941 #endif
96942 
96943 
96944 /*
96945 ** Parameter eMode must be one of the PAGER_JOURNALMODE_XXX constants
96946 ** defined in pager.h. This function returns the associated lowercase
96947 ** journal-mode name.
96948 */
96949 SQLITE_PRIVATE const char *sqlite3JournalModename(int eMode){
96950   static char * const azModeName[] = {
96951     "delete", "persist", "off", "truncate", "memory"
96952 #ifndef SQLITE_OMIT_WAL
96953      , "wal"
96954 #endif
96955   };
96956   assert( PAGER_JOURNALMODE_DELETE==0 );
96957   assert( PAGER_JOURNALMODE_PERSIST==1 );
96958   assert( PAGER_JOURNALMODE_OFF==2 );
96959   assert( PAGER_JOURNALMODE_TRUNCATE==3 );
96960   assert( PAGER_JOURNALMODE_MEMORY==4 );
96961   assert( PAGER_JOURNALMODE_WAL==5 );
96962   assert( eMode>=0 && eMode<=ArraySize(azModeName) );
96963 
96964   if( eMode==ArraySize(azModeName) ) return 0;
96965   return azModeName[eMode];
96966 }
96967 
96968 /*
96969 ** Process a pragma statement.  
96970 **
96971 ** Pragmas are of this form:
96972 **
96973 **      PRAGMA [database.]id [= value]
96974 **
96975 ** The identifier might also be a string.  The value is a string, and
96976 ** identifier, or a number.  If minusFlag is true, then the value is
96977 ** a number that was preceded by a minus sign.
96978 **
96979 ** If the left side is "database.id" then pId1 is the database name
96980 ** and pId2 is the id.  If the left side is just "id" then pId1 is the
96981 ** id and pId2 is any empty string.
96982 */
96983 SQLITE_PRIVATE void sqlite3Pragma(
96984   Parse *pParse, 
96985   Token *pId1,        /* First part of [database.]id field */
96986   Token *pId2,        /* Second part of [database.]id field, or NULL */
96987   Token *pValue,      /* Token for <value>, or NULL */
96988   int minusFlag       /* True if a '-' sign preceded <value> */
96989 ){
96990   char *zLeft = 0;       /* Nul-terminated UTF-8 string <id> */
96991   char *zRight = 0;      /* Nul-terminated UTF-8 string <value>, or NULL */
96992   const char *zDb = 0;   /* The database name */
96993   Token *pId;            /* Pointer to <id> token */
96994   char *aFcntl[4];       /* Argument to SQLITE_FCNTL_PRAGMA */
96995   int iDb;               /* Database index for <database> */
96996   int lwr, upr, mid;           /* Binary search bounds */
96997   int rc;                      /* return value form SQLITE_FCNTL_PRAGMA */
96998   sqlite3 *db = pParse->db;    /* The database connection */
96999   Db *pDb;                     /* The specific database being pragmaed */
97000   Vdbe *v = sqlite3GetVdbe(pParse);  /* Prepared statement */
97001 
97002   if( v==0 ) return;
97003   sqlite3VdbeRunOnlyOnce(v);
97004   pParse->nMem = 2;
97005 
97006   /* Interpret the [database.] part of the pragma statement. iDb is the
97007   ** index of the database this pragma is being applied to in db.aDb[]. */
97008   iDb = sqlite3TwoPartName(pParse, pId1, pId2, &pId);
97009   if( iDb<0 ) return;
97010   pDb = &db->aDb[iDb];
97011 
97012   /* If the temp database has been explicitly named as part of the 
97013   ** pragma, make sure it is open. 
97014   */
97015   if( iDb==1 && sqlite3OpenTempDatabase(pParse) ){
97016     return;
97017   }
97018 
97019   zLeft = sqlite3NameFromToken(db, pId);
97020   if( !zLeft ) return;
97021   if( minusFlag ){
97022     zRight = sqlite3MPrintf(db, "-%T", pValue);
97023   }else{
97024     zRight = sqlite3NameFromToken(db, pValue);
97025   }
97026 
97027   assert( pId2 );
97028   zDb = pId2->n>0 ? pDb->zName : 0;
97029   if( sqlite3AuthCheck(pParse, SQLITE_PRAGMA, zLeft, zRight, zDb) ){
97030     goto pragma_out;
97031   }
97032 
97033   /* Send an SQLITE_FCNTL_PRAGMA file-control to the underlying VFS
97034   ** connection.  If it returns SQLITE_OK, then assume that the VFS
97035   ** handled the pragma and generate a no-op prepared statement.
97036   */
97037   aFcntl[0] = 0;
97038   aFcntl[1] = zLeft;
97039   aFcntl[2] = zRight;
97040   aFcntl[3] = 0;
97041   db->busyHandler.nBusy = 0;
97042   rc = sqlite3_file_control(db, zDb, SQLITE_FCNTL_PRAGMA, (void*)aFcntl);
97043   if( rc==SQLITE_OK ){
97044     if( aFcntl[0] ){
97045       int mem = ++pParse->nMem;
97046       sqlite3VdbeAddOp4(v, OP_String8, 0, mem, 0, aFcntl[0], 0);
97047       sqlite3VdbeSetNumCols(v, 1);
97048       sqlite3VdbeSetColName(v, 0, COLNAME_NAME, "result", SQLITE_STATIC);
97049       sqlite3VdbeAddOp2(v, OP_ResultRow, mem, 1);
97050       sqlite3_free(aFcntl[0]);
97051     }
97052     goto pragma_out;
97053   }
97054   if( rc!=SQLITE_NOTFOUND ){
97055     if( aFcntl[0] ){
97056       sqlite3ErrorMsg(pParse, "%s", aFcntl[0]);
97057       sqlite3_free(aFcntl[0]);
97058     }
97059     pParse->nErr++;
97060     pParse->rc = rc;
97061     goto pragma_out;
97062   }
97063 
97064   /* Locate the pragma in the lookup table */
97065   lwr = 0;
97066   upr = ArraySize(aPragmaNames)-1;
97067   while( lwr<=upr ){
97068     mid = (lwr+upr)/2;
97069     rc = sqlite3_stricmp(zLeft, aPragmaNames[mid].zName);
97070     if( rc==0 ) break;
97071     if( rc<0 ){
97072       upr = mid - 1;
97073     }else{
97074       lwr = mid + 1;
97075     }
97076   }
97077   if( lwr>upr ) goto pragma_out;
97078 
97079   /* Make sure the database schema is loaded if the pragma requires that */
97080   if( (aPragmaNames[mid].mPragFlag & PragFlag_NeedSchema)!=0 ){
97081     if( sqlite3ReadSchema(pParse) ) goto pragma_out;
97082   }
97083 
97084   /* Jump to the appropriate pragma handler */
97085   switch( aPragmaNames[mid].ePragTyp ){
97086   
97087 #if !defined(SQLITE_OMIT_PAGER_PRAGMAS) && !defined(SQLITE_OMIT_DEPRECATED)
97088   /*
97089   **  PRAGMA [database.]default_cache_size
97090   **  PRAGMA [database.]default_cache_size=N
97091   **
97092   ** The first form reports the current persistent setting for the
97093   ** page cache size.  The value returned is the maximum number of
97094   ** pages in the page cache.  The second form sets both the current
97095   ** page cache size value and the persistent page cache size value
97096   ** stored in the database file.
97097   **
97098   ** Older versions of SQLite would set the default cache size to a
97099   ** negative number to indicate synchronous=OFF.  These days, synchronous
97100   ** is always on by default regardless of the sign of the default cache
97101   ** size.  But continue to take the absolute value of the default cache
97102   ** size of historical compatibility.
97103   */
97104   case PragTyp_DEFAULT_CACHE_SIZE: {
97105     static const VdbeOpList getCacheSize[] = {
97106       { OP_Transaction, 0, 0,        0},                         /* 0 */
97107       { OP_ReadCookie,  0, 1,        BTREE_DEFAULT_CACHE_SIZE},  /* 1 */
97108       { OP_IfPos,       1, 8,        0},
97109       { OP_Integer,     0, 2,        0},
97110       { OP_Subtract,    1, 2,        1},
97111       { OP_IfPos,       1, 8,        0},
97112       { OP_Integer,     0, 1,        0},                         /* 6 */
97113       { OP_Noop,        0, 0,        0},
97114       { OP_ResultRow,   1, 1,        0},
97115     };
97116     int addr;
97117     sqlite3VdbeUsesBtree(v, iDb);
97118     if( !zRight ){
97119       sqlite3VdbeSetNumCols(v, 1);
97120       sqlite3VdbeSetColName(v, 0, COLNAME_NAME, "cache_size", SQLITE_STATIC);
97121       pParse->nMem += 2;
97122       addr = sqlite3VdbeAddOpList(v, ArraySize(getCacheSize), getCacheSize);
97123       sqlite3VdbeChangeP1(v, addr, iDb);
97124       sqlite3VdbeChangeP1(v, addr+1, iDb);
97125       sqlite3VdbeChangeP1(v, addr+6, SQLITE_DEFAULT_CACHE_SIZE);
97126     }else{
97127       int size = sqlite3AbsInt32(sqlite3Atoi(zRight));
97128       sqlite3BeginWriteOperation(pParse, 0, iDb);
97129       sqlite3VdbeAddOp2(v, OP_Integer, size, 1);
97130       sqlite3VdbeAddOp3(v, OP_SetCookie, iDb, BTREE_DEFAULT_CACHE_SIZE, 1);
97131       assert( sqlite3SchemaMutexHeld(db, iDb, 0) );
97132       pDb->pSchema->cache_size = size;
97133       sqlite3BtreeSetCacheSize(pDb->pBt, pDb->pSchema->cache_size);
97134     }
97135     break;
97136   }
97137 #endif /* !SQLITE_OMIT_PAGER_PRAGMAS && !SQLITE_OMIT_DEPRECATED */
97138 
97139 #if !defined(SQLITE_OMIT_PAGER_PRAGMAS)
97140   /*
97141   **  PRAGMA [database.]page_size
97142   **  PRAGMA [database.]page_size=N
97143   **
97144   ** The first form reports the current setting for the
97145   ** database page size in bytes.  The second form sets the
97146   ** database page size value.  The value can only be set if
97147   ** the database has not yet been created.
97148   */
97149   case PragTyp_PAGE_SIZE: {
97150     Btree *pBt = pDb->pBt;
97151     assert( pBt!=0 );
97152     if( !zRight ){
97153       int size = ALWAYS(pBt) ? sqlite3BtreeGetPageSize(pBt) : 0;
97154       returnSingleInt(pParse, "page_size", size);
97155     }else{
97156       /* Malloc may fail when setting the page-size, as there is an internal
97157       ** buffer that the pager module resizes using sqlite3_realloc().
97158       */
97159       db->nextPagesize = sqlite3Atoi(zRight);
97160       if( SQLITE_NOMEM==sqlite3BtreeSetPageSize(pBt, db->nextPagesize,-1,0) ){
97161         db->mallocFailed = 1;
97162       }
97163     }
97164     break;
97165   }
97166 
97167   /*
97168   **  PRAGMA [database.]secure_delete
97169   **  PRAGMA [database.]secure_delete=ON/OFF
97170   **
97171   ** The first form reports the current setting for the
97172   ** secure_delete flag.  The second form changes the secure_delete
97173   ** flag setting and reports thenew value.
97174   */
97175   case PragTyp_SECURE_DELETE: {
97176     Btree *pBt = pDb->pBt;
97177     int b = -1;
97178     assert( pBt!=0 );
97179     if( zRight ){
97180       b = sqlite3GetBoolean(zRight, 0);
97181     }
97182     if( pId2->n==0 && b>=0 ){
97183       int ii;
97184       for(ii=0; ii<db->nDb; ii++){
97185         sqlite3BtreeSecureDelete(db->aDb[ii].pBt, b);
97186       }
97187     }
97188     b = sqlite3BtreeSecureDelete(pBt, b);
97189     returnSingleInt(pParse, "secure_delete", b);
97190     break;
97191   }
97192 
97193   /*
97194   **  PRAGMA [database.]max_page_count
97195   **  PRAGMA [database.]max_page_count=N
97196   **
97197   ** The first form reports the current setting for the
97198   ** maximum number of pages in the database file.  The 
97199   ** second form attempts to change this setting.  Both
97200   ** forms return the current setting.
97201   **
97202   ** The absolute value of N is used.  This is undocumented and might
97203   ** change.  The only purpose is to provide an easy way to test
97204   ** the sqlite3AbsInt32() function.
97205   **
97206   **  PRAGMA [database.]page_count
97207   **
97208   ** Return the number of pages in the specified database.
97209   */
97210   case PragTyp_PAGE_COUNT: {
97211     int iReg;
97212     sqlite3CodeVerifySchema(pParse, iDb);
97213     iReg = ++pParse->nMem;
97214     if( sqlite3Tolower(zLeft[0])=='p' ){
97215       sqlite3VdbeAddOp2(v, OP_Pagecount, iDb, iReg);
97216     }else{
97217       sqlite3VdbeAddOp3(v, OP_MaxPgcnt, iDb, iReg, 
97218                         sqlite3AbsInt32(sqlite3Atoi(zRight)));
97219     }
97220     sqlite3VdbeAddOp2(v, OP_ResultRow, iReg, 1);
97221     sqlite3VdbeSetNumCols(v, 1);
97222     sqlite3VdbeSetColName(v, 0, COLNAME_NAME, zLeft, SQLITE_TRANSIENT);
97223     break;
97224   }
97225 
97226   /*
97227   **  PRAGMA [database.]locking_mode
97228   **  PRAGMA [database.]locking_mode = (normal|exclusive)
97229   */
97230   case PragTyp_LOCKING_MODE: {
97231     const char *zRet = "normal";
97232     int eMode = getLockingMode(zRight);
97233 
97234     if( pId2->n==0 && eMode==PAGER_LOCKINGMODE_QUERY ){
97235       /* Simple "PRAGMA locking_mode;" statement. This is a query for
97236       ** the current default locking mode (which may be different to
97237       ** the locking-mode of the main database).
97238       */
97239       eMode = db->dfltLockMode;
97240     }else{
97241       Pager *pPager;
97242       if( pId2->n==0 ){
97243         /* This indicates that no database name was specified as part
97244         ** of the PRAGMA command. In this case the locking-mode must be
97245         ** set on all attached databases, as well as the main db file.
97246         **
97247         ** Also, the sqlite3.dfltLockMode variable is set so that
97248         ** any subsequently attached databases also use the specified
97249         ** locking mode.
97250         */
97251         int ii;
97252         assert(pDb==&db->aDb[0]);
97253         for(ii=2; ii<db->nDb; ii++){
97254           pPager = sqlite3BtreePager(db->aDb[ii].pBt);
97255           sqlite3PagerLockingMode(pPager, eMode);
97256         }
97257         db->dfltLockMode = (u8)eMode;
97258       }
97259       pPager = sqlite3BtreePager(pDb->pBt);
97260       eMode = sqlite3PagerLockingMode(pPager, eMode);
97261     }
97262 
97263     assert( eMode==PAGER_LOCKINGMODE_NORMAL
97264             || eMode==PAGER_LOCKINGMODE_EXCLUSIVE );
97265     if( eMode==PAGER_LOCKINGMODE_EXCLUSIVE ){
97266       zRet = "exclusive";
97267     }
97268     sqlite3VdbeSetNumCols(v, 1);
97269     sqlite3VdbeSetColName(v, 0, COLNAME_NAME, "locking_mode", SQLITE_STATIC);
97270     sqlite3VdbeAddOp4(v, OP_String8, 0, 1, 0, zRet, 0);
97271     sqlite3VdbeAddOp2(v, OP_ResultRow, 1, 1);
97272     break;
97273   }
97274 
97275   /*
97276   **  PRAGMA [database.]journal_mode
97277   **  PRAGMA [database.]journal_mode =
97278   **                      (delete|persist|off|truncate|memory|wal|off)
97279   */
97280   case PragTyp_JOURNAL_MODE: {
97281     int eMode;        /* One of the PAGER_JOURNALMODE_XXX symbols */
97282     int ii;           /* Loop counter */
97283 
97284     sqlite3VdbeSetNumCols(v, 1);
97285     sqlite3VdbeSetColName(v, 0, COLNAME_NAME, "journal_mode", SQLITE_STATIC);
97286 
97287     if( zRight==0 ){
97288       /* If there is no "=MODE" part of the pragma, do a query for the
97289       ** current mode */
97290       eMode = PAGER_JOURNALMODE_QUERY;
97291     }else{
97292       const char *zMode;
97293       int n = sqlite3Strlen30(zRight);
97294       for(eMode=0; (zMode = sqlite3JournalModename(eMode))!=0; eMode++){
97295         if( sqlite3StrNICmp(zRight, zMode, n)==0 ) break;
97296       }
97297       if( !zMode ){
97298         /* If the "=MODE" part does not match any known journal mode,
97299         ** then do a query */
97300         eMode = PAGER_JOURNALMODE_QUERY;
97301       }
97302     }
97303     if( eMode==PAGER_JOURNALMODE_QUERY && pId2->n==0 ){
97304       /* Convert "PRAGMA journal_mode" into "PRAGMA main.journal_mode" */
97305       iDb = 0;
97306       pId2->n = 1;
97307     }
97308     for(ii=db->nDb-1; ii>=0; ii--){
97309       if( db->aDb[ii].pBt && (ii==iDb || pId2->n==0) ){
97310         sqlite3VdbeUsesBtree(v, ii);
97311         sqlite3VdbeAddOp3(v, OP_JournalMode, ii, 1, eMode);
97312       }
97313     }
97314     sqlite3VdbeAddOp2(v, OP_ResultRow, 1, 1);
97315     break;
97316   }
97317 
97318   /*
97319   **  PRAGMA [database.]journal_size_limit
97320   **  PRAGMA [database.]journal_size_limit=N
97321   **
97322   ** Get or set the size limit on rollback journal files.
97323   */
97324   case PragTyp_JOURNAL_SIZE_LIMIT: {
97325     Pager *pPager = sqlite3BtreePager(pDb->pBt);
97326     i64 iLimit = -2;
97327     if( zRight ){
97328       sqlite3Atoi64(zRight, &iLimit, sqlite3Strlen30(zRight), SQLITE_UTF8);
97329       if( iLimit<-1 ) iLimit = -1;
97330     }
97331     iLimit = sqlite3PagerJournalSizeLimit(pPager, iLimit);
97332     returnSingleInt(pParse, "journal_size_limit", iLimit);
97333     break;
97334   }
97335 
97336 #endif /* SQLITE_OMIT_PAGER_PRAGMAS */
97337 
97338   /*
97339   **  PRAGMA [database.]auto_vacuum
97340   **  PRAGMA [database.]auto_vacuum=N
97341   **
97342   ** Get or set the value of the database 'auto-vacuum' parameter.
97343   ** The value is one of:  0 NONE 1 FULL 2 INCREMENTAL
97344   */
97345 #ifndef SQLITE_OMIT_AUTOVACUUM
97346   case PragTyp_AUTO_VACUUM: {
97347     Btree *pBt = pDb->pBt;
97348     assert( pBt!=0 );
97349     if( !zRight ){
97350       returnSingleInt(pParse, "auto_vacuum", sqlite3BtreeGetAutoVacuum(pBt));
97351     }else{
97352       int eAuto = getAutoVacuum(zRight);
97353       assert( eAuto>=0 && eAuto<=2 );
97354       db->nextAutovac = (u8)eAuto;
97355       /* Call SetAutoVacuum() to set initialize the internal auto and
97356       ** incr-vacuum flags. This is required in case this connection
97357       ** creates the database file. It is important that it is created
97358       ** as an auto-vacuum capable db.
97359       */
97360       rc = sqlite3BtreeSetAutoVacuum(pBt, eAuto);
97361       if( rc==SQLITE_OK && (eAuto==1 || eAuto==2) ){
97362         /* When setting the auto_vacuum mode to either "full" or 
97363         ** "incremental", write the value of meta[6] in the database
97364         ** file. Before writing to meta[6], check that meta[3] indicates
97365         ** that this really is an auto-vacuum capable database.
97366         */
97367         static const VdbeOpList setMeta6[] = {
97368           { OP_Transaction,    0,         1,                 0},    /* 0 */
97369           { OP_ReadCookie,     0,         1,         BTREE_LARGEST_ROOT_PAGE},
97370           { OP_If,             1,         0,                 0},    /* 2 */
97371           { OP_Halt,           SQLITE_OK, OE_Abort,          0},    /* 3 */
97372           { OP_Integer,        0,         1,                 0},    /* 4 */
97373           { OP_SetCookie,      0,         BTREE_INCR_VACUUM, 1},    /* 5 */
97374         };
97375         int iAddr;
97376         iAddr = sqlite3VdbeAddOpList(v, ArraySize(setMeta6), setMeta6);
97377         sqlite3VdbeChangeP1(v, iAddr, iDb);
97378         sqlite3VdbeChangeP1(v, iAddr+1, iDb);
97379         sqlite3VdbeChangeP2(v, iAddr+2, iAddr+4);
97380         sqlite3VdbeChangeP1(v, iAddr+4, eAuto-1);
97381         sqlite3VdbeChangeP1(v, iAddr+5, iDb);
97382         sqlite3VdbeUsesBtree(v, iDb);
97383       }
97384     }
97385     break;
97386   }
97387 #endif
97388 
97389   /*
97390   **  PRAGMA [database.]incremental_vacuum(N)
97391   **
97392   ** Do N steps of incremental vacuuming on a database.
97393   */
97394 #ifndef SQLITE_OMIT_AUTOVACUUM
97395   case PragTyp_INCREMENTAL_VACUUM: {
97396     int iLimit, addr;
97397     if( zRight==0 || !sqlite3GetInt32(zRight, &iLimit) || iLimit<=0 ){
97398       iLimit = 0x7fffffff;
97399     }
97400     sqlite3BeginWriteOperation(pParse, 0, iDb);
97401     sqlite3VdbeAddOp2(v, OP_Integer, iLimit, 1);
97402     addr = sqlite3VdbeAddOp1(v, OP_IncrVacuum, iDb);
97403     sqlite3VdbeAddOp1(v, OP_ResultRow, 1);
97404     sqlite3VdbeAddOp2(v, OP_AddImm, 1, -1);
97405     sqlite3VdbeAddOp2(v, OP_IfPos, 1, addr);
97406     sqlite3VdbeJumpHere(v, addr);
97407     break;
97408   }
97409 #endif
97410 
97411 #ifndef SQLITE_OMIT_PAGER_PRAGMAS
97412   /*
97413   **  PRAGMA [database.]cache_size
97414   **  PRAGMA [database.]cache_size=N
97415   **
97416   ** The first form reports the current local setting for the
97417   ** page cache size. The second form sets the local
97418   ** page cache size value.  If N is positive then that is the
97419   ** number of pages in the cache.  If N is negative, then the
97420   ** number of pages is adjusted so that the cache uses -N kibibytes
97421   ** of memory.
97422   */
97423   case PragTyp_CACHE_SIZE: {
97424     assert( sqlite3SchemaMutexHeld(db, iDb, 0) );
97425     if( !zRight ){
97426       returnSingleInt(pParse, "cache_size", pDb->pSchema->cache_size);
97427     }else{
97428       int size = sqlite3Atoi(zRight);
97429       pDb->pSchema->cache_size = size;
97430       sqlite3BtreeSetCacheSize(pDb->pBt, pDb->pSchema->cache_size);
97431     }
97432     break;
97433   }
97434 
97435   /*
97436   **  PRAGMA [database.]mmap_size(N)
97437   **
97438   ** Used to set mapping size limit. The mapping size limit is
97439   ** used to limit the aggregate size of all memory mapped regions of the
97440   ** database file. If this parameter is set to zero, then memory mapping
97441   ** is not used at all.  If N is negative, then the default memory map
97442   ** limit determined by sqlite3_config(SQLITE_CONFIG_MMAP_SIZE) is set.
97443   ** The parameter N is measured in bytes.
97444   **
97445   ** This value is advisory.  The underlying VFS is free to memory map
97446   ** as little or as much as it wants.  Except, if N is set to 0 then the
97447   ** upper layers will never invoke the xFetch interfaces to the VFS.
97448   */
97449   case PragTyp_MMAP_SIZE: {
97450     sqlite3_int64 sz;
97451 #if SQLITE_MAX_MMAP_SIZE>0
97452     assert( sqlite3SchemaMutexHeld(db, iDb, 0) );
97453     if( zRight ){
97454       int ii;
97455       sqlite3Atoi64(zRight, &sz, sqlite3Strlen30(zRight), SQLITE_UTF8);
97456       if( sz<0 ) sz = sqlite3GlobalConfig.szMmap;
97457       if( pId2->n==0 ) db->szMmap = sz;
97458       for(ii=db->nDb-1; ii>=0; ii--){
97459         if( db->aDb[ii].pBt && (ii==iDb || pId2->n==0) ){
97460           sqlite3BtreeSetMmapLimit(db->aDb[ii].pBt, sz);
97461         }
97462       }
97463     }
97464     sz = -1;
97465     rc = sqlite3_file_control(db, zDb, SQLITE_FCNTL_MMAP_SIZE, &sz);
97466 #else
97467     sz = 0;
97468     rc = SQLITE_OK;
97469 #endif
97470     if( rc==SQLITE_OK ){
97471       returnSingleInt(pParse, "mmap_size", sz);
97472     }else if( rc!=SQLITE_NOTFOUND ){
97473       pParse->nErr++;
97474       pParse->rc = rc;
97475     }
97476     break;
97477   }
97478 
97479   /*
97480   **   PRAGMA temp_store
97481   **   PRAGMA temp_store = "default"|"memory"|"file"
97482   **
97483   ** Return or set the local value of the temp_store flag.  Changing
97484   ** the local value does not make changes to the disk file and the default
97485   ** value will be restored the next time the database is opened.
97486   **
97487   ** Note that it is possible for the library compile-time options to
97488   ** override this setting
97489   */
97490   case PragTyp_TEMP_STORE: {
97491     if( !zRight ){
97492       returnSingleInt(pParse, "temp_store", db->temp_store);
97493     }else{
97494       changeTempStorage(pParse, zRight);
97495     }
97496     break;
97497   }
97498 
97499   /*
97500   **   PRAGMA temp_store_directory
97501   **   PRAGMA temp_store_directory = ""|"directory_name"
97502   **
97503   ** Return or set the local value of the temp_store_directory flag.  Changing
97504   ** the value sets a specific directory to be used for temporary files.
97505   ** Setting to a null string reverts to the default temporary directory search.
97506   ** If temporary directory is changed, then invalidateTempStorage.
97507   **
97508   */
97509   case PragTyp_TEMP_STORE_DIRECTORY: {
97510     if( !zRight ){
97511       if( sqlite3_temp_directory ){
97512         sqlite3VdbeSetNumCols(v, 1);
97513         sqlite3VdbeSetColName(v, 0, COLNAME_NAME, 
97514             "temp_store_directory", SQLITE_STATIC);
97515         sqlite3VdbeAddOp4(v, OP_String8, 0, 1, 0, sqlite3_temp_directory, 0);
97516         sqlite3VdbeAddOp2(v, OP_ResultRow, 1, 1);
97517       }
97518     }else{
97519 #ifndef SQLITE_OMIT_WSD
97520       if( zRight[0] ){
97521         int res;
97522         rc = sqlite3OsAccess(db->pVfs, zRight, SQLITE_ACCESS_READWRITE, &res);
97523         if( rc!=SQLITE_OK || res==0 ){
97524           sqlite3ErrorMsg(pParse, "not a writable directory");
97525           goto pragma_out;
97526         }
97527       }
97528       if( SQLITE_TEMP_STORE==0
97529        || (SQLITE_TEMP_STORE==1 && db->temp_store<=1)
97530        || (SQLITE_TEMP_STORE==2 && db->temp_store==1)
97531       ){
97532         invalidateTempStorage(pParse);
97533       }
97534       sqlite3_free(sqlite3_temp_directory);
97535       if( zRight[0] ){
97536         sqlite3_temp_directory = sqlite3_mprintf("%s", zRight);
97537       }else{
97538         sqlite3_temp_directory = 0;
97539       }
97540 #endif /* SQLITE_OMIT_WSD */
97541     }
97542     break;
97543   }
97544 
97545 #if SQLITE_OS_WIN
97546   /*
97547   **   PRAGMA data_store_directory
97548   **   PRAGMA data_store_directory = ""|"directory_name"
97549   **
97550   ** Return or set the local value of the data_store_directory flag.  Changing
97551   ** the value sets a specific directory to be used for database files that
97552   ** were specified with a relative pathname.  Setting to a null string reverts
97553   ** to the default database directory, which for database files specified with
97554   ** a relative path will probably be based on the current directory for the
97555   ** process.  Database file specified with an absolute path are not impacted
97556   ** by this setting, regardless of its value.
97557   **
97558   */
97559   case PragTyp_DATA_STORE_DIRECTORY: {
97560     if( !zRight ){
97561       if( sqlite3_data_directory ){
97562         sqlite3VdbeSetNumCols(v, 1);
97563         sqlite3VdbeSetColName(v, 0, COLNAME_NAME, 
97564             "data_store_directory", SQLITE_STATIC);
97565         sqlite3VdbeAddOp4(v, OP_String8, 0, 1, 0, sqlite3_data_directory, 0);
97566         sqlite3VdbeAddOp2(v, OP_ResultRow, 1, 1);
97567       }
97568     }else{
97569 #ifndef SQLITE_OMIT_WSD
97570       if( zRight[0] ){
97571         int res;
97572         rc = sqlite3OsAccess(db->pVfs, zRight, SQLITE_ACCESS_READWRITE, &res);
97573         if( rc!=SQLITE_OK || res==0 ){
97574           sqlite3ErrorMsg(pParse, "not a writable directory");
97575           goto pragma_out;
97576         }
97577       }
97578       sqlite3_free(sqlite3_data_directory);
97579       if( zRight[0] ){
97580         sqlite3_data_directory = sqlite3_mprintf("%s", zRight);
97581       }else{
97582         sqlite3_data_directory = 0;
97583       }
97584 #endif /* SQLITE_OMIT_WSD */
97585     }
97586     break;
97587   }
97588 #endif
97589 
97590 #if SQLITE_ENABLE_LOCKING_STYLE
97591   /*
97592   **   PRAGMA [database.]lock_proxy_file
97593   **   PRAGMA [database.]lock_proxy_file = ":auto:"|"lock_file_path"
97594   **
97595   ** Return or set the value of the lock_proxy_file flag.  Changing
97596   ** the value sets a specific file to be used for database access locks.
97597   **
97598   */
97599   case PragTyp_LOCK_PROXY_FILE: {
97600     if( !zRight ){
97601       Pager *pPager = sqlite3BtreePager(pDb->pBt);
97602       char *proxy_file_path = NULL;
97603       sqlite3_file *pFile = sqlite3PagerFile(pPager);
97604       sqlite3OsFileControlHint(pFile, SQLITE_GET_LOCKPROXYFILE, 
97605                            &proxy_file_path);
97606       
97607       if( proxy_file_path ){
97608         sqlite3VdbeSetNumCols(v, 1);
97609         sqlite3VdbeSetColName(v, 0, COLNAME_NAME, 
97610                               "lock_proxy_file", SQLITE_STATIC);
97611         sqlite3VdbeAddOp4(v, OP_String8, 0, 1, 0, proxy_file_path, 0);
97612         sqlite3VdbeAddOp2(v, OP_ResultRow, 1, 1);
97613       }
97614     }else{
97615       Pager *pPager = sqlite3BtreePager(pDb->pBt);
97616       sqlite3_file *pFile = sqlite3PagerFile(pPager);
97617       int res;
97618       if( zRight[0] ){
97619         res=sqlite3OsFileControl(pFile, SQLITE_SET_LOCKPROXYFILE, 
97620                                      zRight);
97621       } else {
97622         res=sqlite3OsFileControl(pFile, SQLITE_SET_LOCKPROXYFILE, 
97623                                      NULL);
97624       }
97625       if( res!=SQLITE_OK ){
97626         sqlite3ErrorMsg(pParse, "failed to set lock proxy file");
97627         goto pragma_out;
97628       }
97629     }
97630     break;
97631   }
97632 #endif /* SQLITE_ENABLE_LOCKING_STYLE */      
97633     
97634   /*
97635   **   PRAGMA [database.]synchronous
97636   **   PRAGMA [database.]synchronous=OFF|ON|NORMAL|FULL
97637   **
97638   ** Return or set the local value of the synchronous flag.  Changing
97639   ** the local value does not make changes to the disk file and the
97640   ** default value will be restored the next time the database is
97641   ** opened.
97642   */
97643   case PragTyp_SYNCHRONOUS: {
97644     if( !zRight ){
97645       returnSingleInt(pParse, "synchronous", pDb->safety_level-1);
97646     }else{
97647       if( !db->autoCommit ){
97648         sqlite3ErrorMsg(pParse, 
97649             "Safety level may not be changed inside a transaction");
97650       }else{
97651         pDb->safety_level = getSafetyLevel(zRight,0,1)+1;
97652         setAllPagerFlags(db);
97653       }
97654     }
97655     break;
97656   }
97657 #endif /* SQLITE_OMIT_PAGER_PRAGMAS */
97658 
97659 #ifndef SQLITE_OMIT_FLAG_PRAGMAS
97660   case PragTyp_FLAG: {
97661     if( zRight==0 ){
97662       returnSingleInt(pParse, aPragmaNames[mid].zName,
97663                      (db->flags & aPragmaNames[mid].iArg)!=0 );
97664     }else{
97665       int mask = aPragmaNames[mid].iArg;    /* Mask of bits to set or clear. */
97666       if( db->autoCommit==0 ){
97667         /* Foreign key support may not be enabled or disabled while not
97668         ** in auto-commit mode.  */
97669         mask &= ~(SQLITE_ForeignKeys);
97670       }
97671 
97672       if( sqlite3GetBoolean(zRight, 0) ){
97673         db->flags |= mask;
97674       }else{
97675         db->flags &= ~mask;
97676         if( mask==SQLITE_DeferFKs ) db->nDeferredImmCons = 0;
97677       }
97678 
97679       /* Many of the flag-pragmas modify the code generated by the SQL 
97680       ** compiler (eg. count_changes). So add an opcode to expire all
97681       ** compiled SQL statements after modifying a pragma value.
97682       */
97683       sqlite3VdbeAddOp2(v, OP_Expire, 0, 0);
97684       setAllPagerFlags(db);
97685     }
97686     break;
97687   }
97688 #endif /* SQLITE_OMIT_FLAG_PRAGMAS */
97689 
97690 #ifndef SQLITE_OMIT_SCHEMA_PRAGMAS
97691   /*
97692   **   PRAGMA table_info(<table>)
97693   **
97694   ** Return a single row for each column of the named table. The columns of
97695   ** the returned data set are:
97696   **
97697   ** cid:        Column id (numbered from left to right, starting at 0)
97698   ** name:       Column name
97699   ** type:       Column declaration type.
97700   ** notnull:    True if 'NOT NULL' is part of column declaration
97701   ** dflt_value: The default value for the column, if any.
97702   */
97703   case PragTyp_TABLE_INFO: if( zRight ){
97704     Table *pTab;
97705     pTab = sqlite3FindTable(db, zRight, zDb);
97706     if( pTab ){
97707       int i, k;
97708       int nHidden = 0;
97709       Column *pCol;
97710       Index *pPk = sqlite3PrimaryKeyIndex(pTab);
97711       sqlite3VdbeSetNumCols(v, 6);
97712       pParse->nMem = 6;
97713       sqlite3CodeVerifySchema(pParse, iDb);
97714       sqlite3VdbeSetColName(v, 0, COLNAME_NAME, "cid", SQLITE_STATIC);
97715       sqlite3VdbeSetColName(v, 1, COLNAME_NAME, "name", SQLITE_STATIC);
97716       sqlite3VdbeSetColName(v, 2, COLNAME_NAME, "type", SQLITE_STATIC);
97717       sqlite3VdbeSetColName(v, 3, COLNAME_NAME, "notnull", SQLITE_STATIC);
97718       sqlite3VdbeSetColName(v, 4, COLNAME_NAME, "dflt_value", SQLITE_STATIC);
97719       sqlite3VdbeSetColName(v, 5, COLNAME_NAME, "pk", SQLITE_STATIC);
97720       sqlite3ViewGetColumnNames(pParse, pTab);
97721       for(i=0, pCol=pTab->aCol; i<pTab->nCol; i++, pCol++){
97722         if( IsHiddenColumn(pCol) ){
97723           nHidden++;
97724           continue;
97725         }
97726         sqlite3VdbeAddOp2(v, OP_Integer, i-nHidden, 1);
97727         sqlite3VdbeAddOp4(v, OP_String8, 0, 2, 0, pCol->zName, 0);
97728         sqlite3VdbeAddOp4(v, OP_String8, 0, 3, 0,
97729            pCol->zType ? pCol->zType : "", 0);
97730         sqlite3VdbeAddOp2(v, OP_Integer, (pCol->notNull ? 1 : 0), 4);
97731         if( pCol->zDflt ){
97732           sqlite3VdbeAddOp4(v, OP_String8, 0, 5, 0, (char*)pCol->zDflt, 0);
97733         }else{
97734           sqlite3VdbeAddOp2(v, OP_Null, 0, 5);
97735         }
97736         if( (pCol->colFlags & COLFLAG_PRIMKEY)==0 ){
97737           k = 0;
97738         }else if( pPk==0 ){
97739           k = 1;
97740         }else{
97741           for(k=1; ALWAYS(k<=pTab->nCol) && pPk->aiColumn[k-1]!=i; k++){}
97742         }
97743         sqlite3VdbeAddOp2(v, OP_Integer, k, 6);
97744         sqlite3VdbeAddOp2(v, OP_ResultRow, 1, 6);
97745       }
97746     }
97747   }
97748   break;
97749 
97750   case PragTyp_STATS: {
97751     Index *pIdx;
97752     HashElem *i;
97753     v = sqlite3GetVdbe(pParse);
97754     sqlite3VdbeSetNumCols(v, 4);
97755     pParse->nMem = 4;
97756     sqlite3CodeVerifySchema(pParse, iDb);
97757     sqlite3VdbeSetColName(v, 0, COLNAME_NAME, "table", SQLITE_STATIC);
97758     sqlite3VdbeSetColName(v, 1, COLNAME_NAME, "index", SQLITE_STATIC);
97759     sqlite3VdbeSetColName(v, 2, COLNAME_NAME, "width", SQLITE_STATIC);
97760     sqlite3VdbeSetColName(v, 3, COLNAME_NAME, "height", SQLITE_STATIC);
97761     for(i=sqliteHashFirst(&pDb->pSchema->tblHash); i; i=sqliteHashNext(i)){
97762       Table *pTab = sqliteHashData(i);
97763       sqlite3VdbeAddOp4(v, OP_String8, 0, 1, 0, pTab->zName, 0);
97764       sqlite3VdbeAddOp2(v, OP_Null, 0, 2);
97765       sqlite3VdbeAddOp2(v, OP_Integer,
97766                            (int)sqlite3LogEstToInt(pTab->szTabRow), 3);
97767       sqlite3VdbeAddOp2(v, OP_Integer, (int)pTab->nRowEst, 4);
97768       sqlite3VdbeAddOp2(v, OP_ResultRow, 1, 4);
97769       for(pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext){
97770         sqlite3VdbeAddOp4(v, OP_String8, 0, 2, 0, pIdx->zName, 0);
97771         sqlite3VdbeAddOp2(v, OP_Integer,
97772                              (int)sqlite3LogEstToInt(pIdx->szIdxRow), 3);
97773         sqlite3VdbeAddOp2(v, OP_Integer, (int)pIdx->aiRowEst[0], 4);
97774         sqlite3VdbeAddOp2(v, OP_ResultRow, 1, 4);
97775       }
97776     }
97777   }
97778   break;
97779 
97780   case PragTyp_INDEX_INFO: if( zRight ){
97781     Index *pIdx;
97782     Table *pTab;
97783     pIdx = sqlite3FindIndex(db, zRight, zDb);
97784     if( pIdx ){
97785       int i;
97786       pTab = pIdx->pTable;
97787       sqlite3VdbeSetNumCols(v, 3);
97788       pParse->nMem = 3;
97789       sqlite3CodeVerifySchema(pParse, iDb);
97790       sqlite3VdbeSetColName(v, 0, COLNAME_NAME, "seqno", SQLITE_STATIC);
97791       sqlite3VdbeSetColName(v, 1, COLNAME_NAME, "cid", SQLITE_STATIC);
97792       sqlite3VdbeSetColName(v, 2, COLNAME_NAME, "name", SQLITE_STATIC);
97793       for(i=0; i<pIdx->nKeyCol; i++){
97794         i16 cnum = pIdx->aiColumn[i];
97795         sqlite3VdbeAddOp2(v, OP_Integer, i, 1);
97796         sqlite3VdbeAddOp2(v, OP_Integer, cnum, 2);
97797         assert( pTab->nCol>cnum );
97798         sqlite3VdbeAddOp4(v, OP_String8, 0, 3, 0, pTab->aCol[cnum].zName, 0);
97799         sqlite3VdbeAddOp2(v, OP_ResultRow, 1, 3);
97800       }
97801     }
97802   }
97803   break;
97804 
97805   case PragTyp_INDEX_LIST: if( zRight ){
97806     Index *pIdx;
97807     Table *pTab;
97808     int i;
97809     pTab = sqlite3FindTable(db, zRight, zDb);
97810     if( pTab ){
97811       v = sqlite3GetVdbe(pParse);
97812       sqlite3VdbeSetNumCols(v, 3);
97813       pParse->nMem = 3;
97814       sqlite3CodeVerifySchema(pParse, iDb);
97815       sqlite3VdbeSetColName(v, 0, COLNAME_NAME, "seq", SQLITE_STATIC);
97816       sqlite3VdbeSetColName(v, 1, COLNAME_NAME, "name", SQLITE_STATIC);
97817       sqlite3VdbeSetColName(v, 2, COLNAME_NAME, "unique", SQLITE_STATIC);
97818       for(pIdx=pTab->pIndex, i=0; pIdx; pIdx=pIdx->pNext, i++){
97819         sqlite3VdbeAddOp2(v, OP_Integer, i, 1);
97820         sqlite3VdbeAddOp4(v, OP_String8, 0, 2, 0, pIdx->zName, 0);
97821         sqlite3VdbeAddOp2(v, OP_Integer, pIdx->onError!=OE_None, 3);
97822         sqlite3VdbeAddOp2(v, OP_ResultRow, 1, 3);
97823       }
97824     }
97825   }
97826   break;
97827 
97828   case PragTyp_DATABASE_LIST: {
97829     int i;
97830     sqlite3VdbeSetNumCols(v, 3);
97831     pParse->nMem = 3;
97832     sqlite3VdbeSetColName(v, 0, COLNAME_NAME, "seq", SQLITE_STATIC);
97833     sqlite3VdbeSetColName(v, 1, COLNAME_NAME, "name", SQLITE_STATIC);
97834     sqlite3VdbeSetColName(v, 2, COLNAME_NAME, "file", SQLITE_STATIC);
97835     for(i=0; i<db->nDb; i++){
97836       if( db->aDb[i].pBt==0 ) continue;
97837       assert( db->aDb[i].zName!=0 );
97838       sqlite3VdbeAddOp2(v, OP_Integer, i, 1);
97839       sqlite3VdbeAddOp4(v, OP_String8, 0, 2, 0, db->aDb[i].zName, 0);
97840       sqlite3VdbeAddOp4(v, OP_String8, 0, 3, 0,
97841            sqlite3BtreeGetFilename(db->aDb[i].pBt), 0);
97842       sqlite3VdbeAddOp2(v, OP_ResultRow, 1, 3);
97843     }
97844   }
97845   break;
97846 
97847   case PragTyp_COLLATION_LIST: {
97848     int i = 0;
97849     HashElem *p;
97850     sqlite3VdbeSetNumCols(v, 2);
97851     pParse->nMem = 2;
97852     sqlite3VdbeSetColName(v, 0, COLNAME_NAME, "seq", SQLITE_STATIC);
97853     sqlite3VdbeSetColName(v, 1, COLNAME_NAME, "name", SQLITE_STATIC);
97854     for(p=sqliteHashFirst(&db->aCollSeq); p; p=sqliteHashNext(p)){
97855       CollSeq *pColl = (CollSeq *)sqliteHashData(p);
97856       sqlite3VdbeAddOp2(v, OP_Integer, i++, 1);
97857       sqlite3VdbeAddOp4(v, OP_String8, 0, 2, 0, pColl->zName, 0);
97858       sqlite3VdbeAddOp2(v, OP_ResultRow, 1, 2);
97859     }
97860   }
97861   break;
97862 #endif /* SQLITE_OMIT_SCHEMA_PRAGMAS */
97863 
97864 #ifndef SQLITE_OMIT_FOREIGN_KEY
97865   case PragTyp_FOREIGN_KEY_LIST: if( zRight ){
97866     FKey *pFK;
97867     Table *pTab;
97868     pTab = sqlite3FindTable(db, zRight, zDb);
97869     if( pTab ){
97870       v = sqlite3GetVdbe(pParse);
97871       pFK = pTab->pFKey;
97872       if( pFK ){
97873         int i = 0; 
97874         sqlite3VdbeSetNumCols(v, 8);
97875         pParse->nMem = 8;
97876         sqlite3CodeVerifySchema(pParse, iDb);
97877         sqlite3VdbeSetColName(v, 0, COLNAME_NAME, "id", SQLITE_STATIC);
97878         sqlite3VdbeSetColName(v, 1, COLNAME_NAME, "seq", SQLITE_STATIC);
97879         sqlite3VdbeSetColName(v, 2, COLNAME_NAME, "table", SQLITE_STATIC);
97880         sqlite3VdbeSetColName(v, 3, COLNAME_NAME, "from", SQLITE_STATIC);
97881         sqlite3VdbeSetColName(v, 4, COLNAME_NAME, "to", SQLITE_STATIC);
97882         sqlite3VdbeSetColName(v, 5, COLNAME_NAME, "on_update", SQLITE_STATIC);
97883         sqlite3VdbeSetColName(v, 6, COLNAME_NAME, "on_delete", SQLITE_STATIC);
97884         sqlite3VdbeSetColName(v, 7, COLNAME_NAME, "match", SQLITE_STATIC);
97885         while(pFK){
97886           int j;
97887           for(j=0; j<pFK->nCol; j++){
97888             char *zCol = pFK->aCol[j].zCol;
97889             char *zOnDelete = (char *)actionName(pFK->aAction[0]);
97890             char *zOnUpdate = (char *)actionName(pFK->aAction[1]);
97891             sqlite3VdbeAddOp2(v, OP_Integer, i, 1);
97892             sqlite3VdbeAddOp2(v, OP_Integer, j, 2);
97893             sqlite3VdbeAddOp4(v, OP_String8, 0, 3, 0, pFK->zTo, 0);
97894             sqlite3VdbeAddOp4(v, OP_String8, 0, 4, 0,
97895                               pTab->aCol[pFK->aCol[j].iFrom].zName, 0);
97896             sqlite3VdbeAddOp4(v, zCol ? OP_String8 : OP_Null, 0, 5, 0, zCol, 0);
97897             sqlite3VdbeAddOp4(v, OP_String8, 0, 6, 0, zOnUpdate, 0);
97898             sqlite3VdbeAddOp4(v, OP_String8, 0, 7, 0, zOnDelete, 0);
97899             sqlite3VdbeAddOp4(v, OP_String8, 0, 8, 0, "NONE", 0);
97900             sqlite3VdbeAddOp2(v, OP_ResultRow, 1, 8);
97901           }
97902           ++i;
97903           pFK = pFK->pNextFrom;
97904         }
97905       }
97906     }
97907   }
97908   break;
97909 #endif /* !defined(SQLITE_OMIT_FOREIGN_KEY) */
97910 
97911 #ifndef SQLITE_OMIT_FOREIGN_KEY
97912 #ifndef SQLITE_OMIT_TRIGGER
97913   case PragTyp_FOREIGN_KEY_CHECK: {
97914     FKey *pFK;             /* A foreign key constraint */
97915     Table *pTab;           /* Child table contain "REFERENCES" keyword */
97916     Table *pParent;        /* Parent table that child points to */
97917     Index *pIdx;           /* Index in the parent table */
97918     int i;                 /* Loop counter:  Foreign key number for pTab */
97919     int j;                 /* Loop counter:  Field of the foreign key */
97920     HashElem *k;           /* Loop counter:  Next table in schema */
97921     int x;                 /* result variable */
97922     int regResult;         /* 3 registers to hold a result row */
97923     int regKey;            /* Register to hold key for checking the FK */
97924     int regRow;            /* Registers to hold a row from pTab */
97925     int addrTop;           /* Top of a loop checking foreign keys */
97926     int addrOk;            /* Jump here if the key is OK */
97927     int *aiCols;           /* child to parent column mapping */
97928 
97929     regResult = pParse->nMem+1;
97930     pParse->nMem += 4;
97931     regKey = ++pParse->nMem;
97932     regRow = ++pParse->nMem;
97933     v = sqlite3GetVdbe(pParse);
97934     sqlite3VdbeSetNumCols(v, 4);
97935     sqlite3VdbeSetColName(v, 0, COLNAME_NAME, "table", SQLITE_STATIC);
97936     sqlite3VdbeSetColName(v, 1, COLNAME_NAME, "rowid", SQLITE_STATIC);
97937     sqlite3VdbeSetColName(v, 2, COLNAME_NAME, "parent", SQLITE_STATIC);
97938     sqlite3VdbeSetColName(v, 3, COLNAME_NAME, "fkid", SQLITE_STATIC);
97939     sqlite3CodeVerifySchema(pParse, iDb);
97940     k = sqliteHashFirst(&db->aDb[iDb].pSchema->tblHash);
97941     while( k ){
97942       if( zRight ){
97943         pTab = sqlite3LocateTable(pParse, 0, zRight, zDb);
97944         k = 0;
97945       }else{
97946         pTab = (Table*)sqliteHashData(k);
97947         k = sqliteHashNext(k);
97948       }
97949       if( pTab==0 || pTab->pFKey==0 ) continue;
97950       sqlite3TableLock(pParse, iDb, pTab->tnum, 0, pTab->zName);
97951       if( pTab->nCol+regRow>pParse->nMem ) pParse->nMem = pTab->nCol + regRow;
97952       sqlite3OpenTable(pParse, 0, iDb, pTab, OP_OpenRead);
97953       sqlite3VdbeAddOp4(v, OP_String8, 0, regResult, 0, pTab->zName,
97954                         P4_TRANSIENT);
97955       for(i=1, pFK=pTab->pFKey; pFK; i++, pFK=pFK->pNextFrom){
97956         pParent = sqlite3FindTable(db, pFK->zTo, zDb);
97957         if( pParent==0 ) continue;
97958         pIdx = 0;
97959         sqlite3TableLock(pParse, iDb, pParent->tnum, 0, pParent->zName);
97960         x = sqlite3FkLocateIndex(pParse, pParent, pFK, &pIdx, 0);
97961         if( x==0 ){
97962           if( pIdx==0 ){
97963             sqlite3OpenTable(pParse, i, iDb, pParent, OP_OpenRead);
97964           }else{
97965             sqlite3VdbeAddOp3(v, OP_OpenRead, i, pIdx->tnum, iDb);
97966             sqlite3VdbeSetP4KeyInfo(pParse, pIdx);
97967           }
97968         }else{
97969           k = 0;
97970           break;
97971         }
97972       }
97973       assert( pParse->nErr>0 || pFK==0 );
97974       if( pFK ) break;
97975       if( pParse->nTab<i ) pParse->nTab = i;
97976       addrTop = sqlite3VdbeAddOp1(v, OP_Rewind, 0);
97977       for(i=1, pFK=pTab->pFKey; pFK; i++, pFK=pFK->pNextFrom){
97978         pParent = sqlite3FindTable(db, pFK->zTo, zDb);
97979         pIdx = 0;
97980         aiCols = 0;
97981         if( pParent ){
97982           x = sqlite3FkLocateIndex(pParse, pParent, pFK, &pIdx, &aiCols);
97983           assert( x==0 );
97984         }
97985         addrOk = sqlite3VdbeMakeLabel(v);
97986         if( pParent && pIdx==0 ){
97987           int iKey = pFK->aCol[0].iFrom;
97988           assert( iKey>=0 && iKey<pTab->nCol );
97989           if( iKey!=pTab->iPKey ){
97990             sqlite3VdbeAddOp3(v, OP_Column, 0, iKey, regRow);
97991             sqlite3ColumnDefault(v, pTab, iKey, regRow);
97992             sqlite3VdbeAddOp2(v, OP_IsNull, regRow, addrOk);
97993             sqlite3VdbeAddOp2(v, OP_MustBeInt, regRow,
97994                sqlite3VdbeCurrentAddr(v)+3);
97995           }else{
97996             sqlite3VdbeAddOp2(v, OP_Rowid, 0, regRow);
97997           }
97998           sqlite3VdbeAddOp3(v, OP_NotExists, i, 0, regRow);
97999           sqlite3VdbeAddOp2(v, OP_Goto, 0, addrOk);
98000           sqlite3VdbeJumpHere(v, sqlite3VdbeCurrentAddr(v)-2);
98001         }else{
98002           for(j=0; j<pFK->nCol; j++){
98003             sqlite3ExprCodeGetColumnOfTable(v, pTab, 0,
98004                             aiCols ? aiCols[j] : pFK->aCol[j].iFrom, regRow+j);
98005             sqlite3VdbeAddOp2(v, OP_IsNull, regRow+j, addrOk);
98006           }
98007           if( pParent ){
98008             sqlite3VdbeAddOp3(v, OP_MakeRecord, regRow, pFK->nCol, regKey);
98009             sqlite3VdbeChangeP4(v, -1,
98010                      sqlite3IndexAffinityStr(v,pIdx), P4_TRANSIENT);
98011             sqlite3VdbeAddOp4Int(v, OP_Found, i, addrOk, regKey, 0);
98012           }
98013         }
98014         sqlite3VdbeAddOp2(v, OP_Rowid, 0, regResult+1);
98015         sqlite3VdbeAddOp4(v, OP_String8, 0, regResult+2, 0, 
98016                           pFK->zTo, P4_TRANSIENT);
98017         sqlite3VdbeAddOp2(v, OP_Integer, i-1, regResult+3);
98018         sqlite3VdbeAddOp2(v, OP_ResultRow, regResult, 4);
98019         sqlite3VdbeResolveLabel(v, addrOk);
98020         sqlite3DbFree(db, aiCols);
98021       }
98022       sqlite3VdbeAddOp2(v, OP_Next, 0, addrTop+1);
98023       sqlite3VdbeJumpHere(v, addrTop);
98024     }
98025   }
98026   break;
98027 #endif /* !defined(SQLITE_OMIT_TRIGGER) */
98028 #endif /* !defined(SQLITE_OMIT_FOREIGN_KEY) */
98029 
98030 #ifndef NDEBUG
98031   case PragTyp_PARSER_TRACE: {
98032     if( zRight ){
98033       if( sqlite3GetBoolean(zRight, 0) ){
98034         sqlite3ParserTrace(stderr, "parser: ");
98035       }else{
98036         sqlite3ParserTrace(0, 0);
98037       }
98038     }
98039   }
98040   break;
98041 #endif
98042 
98043   /* Reinstall the LIKE and GLOB functions.  The variant of LIKE
98044   ** used will be case sensitive or not depending on the RHS.
98045   */
98046   case PragTyp_CASE_SENSITIVE_LIKE: {
98047     if( zRight ){
98048       sqlite3RegisterLikeFunctions(db, sqlite3GetBoolean(zRight, 0));
98049     }
98050   }
98051   break;
98052 
98053 #ifndef SQLITE_INTEGRITY_CHECK_ERROR_MAX
98054 # define SQLITE_INTEGRITY_CHECK_ERROR_MAX 100
98055 #endif
98056 
98057 #ifndef SQLITE_OMIT_INTEGRITY_CHECK
98058   /* Pragma "quick_check" is reduced version of 
98059   ** integrity_check designed to detect most database corruption
98060   ** without most of the overhead of a full integrity-check.
98061   */
98062   case PragTyp_INTEGRITY_CHECK: {
98063     int i, j, addr, mxErr;
98064 
98065     /* Code that appears at the end of the integrity check.  If no error
98066     ** messages have been generated, output OK.  Otherwise output the
98067     ** error message
98068     */
98069     static const VdbeOpList endCode[] = {
98070       { OP_AddImm,      1, 0,        0},    /* 0 */
98071       { OP_IfNeg,       1, 0,        0},    /* 1 */
98072       { OP_String8,     0, 3,        0},    /* 2 */
98073       { OP_ResultRow,   3, 1,        0},
98074     };
98075 
98076     int isQuick = (sqlite3Tolower(zLeft[0])=='q');
98077 
98078     /* If the PRAGMA command was of the form "PRAGMA <db>.integrity_check",
98079     ** then iDb is set to the index of the database identified by <db>.
98080     ** In this case, the integrity of database iDb only is verified by
98081     ** the VDBE created below.
98082     **
98083     ** Otherwise, if the command was simply "PRAGMA integrity_check" (or
98084     ** "PRAGMA quick_check"), then iDb is set to 0. In this case, set iDb
98085     ** to -1 here, to indicate that the VDBE should verify the integrity
98086     ** of all attached databases.  */
98087     assert( iDb>=0 );
98088     assert( iDb==0 || pId2->z );
98089     if( pId2->z==0 ) iDb = -1;
98090 
98091     /* Initialize the VDBE program */
98092     pParse->nMem = 6;
98093     sqlite3VdbeSetNumCols(v, 1);
98094     sqlite3VdbeSetColName(v, 0, COLNAME_NAME, "integrity_check", SQLITE_STATIC);
98095 
98096     /* Set the maximum error count */
98097     mxErr = SQLITE_INTEGRITY_CHECK_ERROR_MAX;
98098     if( zRight ){
98099       sqlite3GetInt32(zRight, &mxErr);
98100       if( mxErr<=0 ){
98101         mxErr = SQLITE_INTEGRITY_CHECK_ERROR_MAX;
98102       }
98103     }
98104     sqlite3VdbeAddOp2(v, OP_Integer, mxErr, 1);  /* reg[1] holds errors left */
98105 
98106     /* Do an integrity check on each database file */
98107     for(i=0; i<db->nDb; i++){
98108       HashElem *x;
98109       Hash *pTbls;
98110       int cnt = 0;
98111 
98112       if( OMIT_TEMPDB && i==1 ) continue;
98113       if( iDb>=0 && i!=iDb ) continue;
98114 
98115       sqlite3CodeVerifySchema(pParse, i);
98116       addr = sqlite3VdbeAddOp1(v, OP_IfPos, 1); /* Halt if out of errors */
98117       sqlite3VdbeAddOp2(v, OP_Halt, 0, 0);
98118       sqlite3VdbeJumpHere(v, addr);
98119 
98120       /* Do an integrity check of the B-Tree
98121       **
98122       ** Begin by filling registers 2, 3, ... with the root pages numbers
98123       ** for all tables and indices in the database.
98124       */
98125       assert( sqlite3SchemaMutexHeld(db, i, 0) );
98126       pTbls = &db->aDb[i].pSchema->tblHash;
98127       for(x=sqliteHashFirst(pTbls); x; x=sqliteHashNext(x)){
98128         Table *pTab = sqliteHashData(x);
98129         Index *pIdx;
98130         if( HasRowid(pTab) ){
98131           sqlite3VdbeAddOp2(v, OP_Integer, pTab->tnum, 2+cnt);
98132           VdbeComment((v, "%s", pTab->zName));
98133           cnt++;
98134         }
98135         for(pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext){
98136           sqlite3VdbeAddOp2(v, OP_Integer, pIdx->tnum, 2+cnt);
98137           VdbeComment((v, "%s", pIdx->zName));
98138           cnt++;
98139         }
98140       }
98141 
98142       /* Make sure sufficient number of registers have been allocated */
98143       pParse->nMem = MAX( pParse->nMem, cnt+8 );
98144 
98145       /* Do the b-tree integrity checks */
98146       sqlite3VdbeAddOp3(v, OP_IntegrityCk, 2, cnt, 1);
98147       sqlite3VdbeChangeP5(v, (u8)i);
98148       addr = sqlite3VdbeAddOp1(v, OP_IsNull, 2);
98149       sqlite3VdbeAddOp4(v, OP_String8, 0, 3, 0,
98150          sqlite3MPrintf(db, "*** in database %s ***\n", db->aDb[i].zName),
98151          P4_DYNAMIC);
98152       sqlite3VdbeAddOp2(v, OP_Move, 2, 4);
98153       sqlite3VdbeAddOp3(v, OP_Concat, 4, 3, 2);
98154       sqlite3VdbeAddOp2(v, OP_ResultRow, 2, 1);
98155       sqlite3VdbeJumpHere(v, addr);
98156 
98157       /* Make sure all the indices are constructed correctly.
98158       */
98159       for(x=sqliteHashFirst(pTbls); x && !isQuick; x=sqliteHashNext(x)){
98160         Table *pTab = sqliteHashData(x);
98161         Index *pIdx, *pPk;
98162         int loopTop;
98163         int iDataCur, iIdxCur;
98164 
98165         if( pTab->pIndex==0 ) continue;
98166         pPk = HasRowid(pTab) ? 0 : sqlite3PrimaryKeyIndex(pTab);
98167         addr = sqlite3VdbeAddOp1(v, OP_IfPos, 1);  /* Stop if out of errors */
98168         sqlite3VdbeAddOp2(v, OP_Halt, 0, 0);
98169         sqlite3VdbeJumpHere(v, addr);
98170         sqlite3ExprCacheClear(pParse);
98171         sqlite3OpenTableAndIndices(pParse, pTab, OP_OpenRead,
98172                                    1, 0, &iDataCur, &iIdxCur);
98173         sqlite3VdbeAddOp2(v, OP_Integer, 0, 7);
98174         for(j=0, pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext, j++){
98175           sqlite3VdbeAddOp2(v, OP_Integer, 0, 8+j); /* index entries counter */
98176         }
98177         pParse->nMem = MAX(pParse->nMem, 8+j);
98178         sqlite3VdbeAddOp2(v, OP_Rewind, iDataCur, 0);
98179         loopTop = sqlite3VdbeAddOp2(v, OP_AddImm, 7, 1);
98180         for(j=0, pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext, j++){
98181           int jmp2, jmp3, jmp4;
98182           int r1;
98183           if( pPk==pIdx ) continue;
98184           r1 = sqlite3GenerateIndexKey(pParse, pIdx, iDataCur, 0, 0, &jmp3);
98185           sqlite3VdbeAddOp2(v, OP_AddImm, 8+j, 1);  /* increment entry count */
98186           jmp2 = sqlite3VdbeAddOp4Int(v, OP_Found, iIdxCur+j, 0, r1,
98187                                       pIdx->nColumn);
98188           sqlite3VdbeAddOp2(v, OP_AddImm, 1, -1); /* Decrement error limit */
98189           sqlite3VdbeAddOp4(v, OP_String8, 0, 3, 0, "row ", P4_STATIC);
98190           sqlite3VdbeAddOp3(v, OP_Concat, 7, 3, 3);
98191           sqlite3VdbeAddOp4(v, OP_String8, 0, 4, 0, " missing from index ",
98192                             P4_STATIC);
98193           sqlite3VdbeAddOp3(v, OP_Concat, 4, 3, 3);
98194           sqlite3VdbeAddOp4(v, OP_String8, 0, 4, 0, pIdx->zName, P4_TRANSIENT);
98195           sqlite3VdbeAddOp3(v, OP_Concat, 4, 3, 3);
98196           sqlite3VdbeAddOp2(v, OP_ResultRow, 3, 1);
98197           jmp4 = sqlite3VdbeAddOp1(v, OP_IfPos, 1);
98198           sqlite3VdbeAddOp0(v, OP_Halt);
98199           sqlite3VdbeJumpHere(v, jmp4);
98200           sqlite3VdbeJumpHere(v, jmp2);
98201           sqlite3VdbeResolveLabel(v, jmp3);
98202         }
98203         sqlite3VdbeAddOp2(v, OP_Next, iDataCur, loopTop);
98204         sqlite3VdbeJumpHere(v, loopTop-1);
98205 #ifndef SQLITE_OMIT_BTREECOUNT
98206         sqlite3VdbeAddOp4(v, OP_String8, 0, 2, 0, 
98207                      "wrong # of entries in index ", P4_STATIC);
98208         for(j=0, pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext, j++){
98209           if( pPk==pIdx ) continue;
98210           addr = sqlite3VdbeCurrentAddr(v);
98211           sqlite3VdbeAddOp2(v, OP_IfPos, 1, addr+2);
98212           sqlite3VdbeAddOp2(v, OP_Halt, 0, 0);
98213           sqlite3VdbeAddOp2(v, OP_Count, iIdxCur+j, 3);
98214           sqlite3VdbeAddOp3(v, OP_Eq, 8+j, addr+8, 3);
98215           sqlite3VdbeAddOp2(v, OP_AddImm, 1, -1);
98216           sqlite3VdbeAddOp4(v, OP_String8, 0, 3, 0, pIdx->zName, P4_TRANSIENT);
98217           sqlite3VdbeAddOp3(v, OP_Concat, 3, 2, 7);
98218           sqlite3VdbeAddOp2(v, OP_ResultRow, 7, 1);
98219         }
98220 #endif /* SQLITE_OMIT_BTREECOUNT */
98221       } 
98222     }
98223     addr = sqlite3VdbeAddOpList(v, ArraySize(endCode), endCode);
98224     sqlite3VdbeChangeP2(v, addr, -mxErr);
98225     sqlite3VdbeJumpHere(v, addr+1);
98226     sqlite3VdbeChangeP4(v, addr+2, "ok", P4_STATIC);
98227   }
98228   break;
98229 #endif /* SQLITE_OMIT_INTEGRITY_CHECK */
98230 
98231 #ifndef SQLITE_OMIT_UTF16
98232   /*
98233   **   PRAGMA encoding
98234   **   PRAGMA encoding = "utf-8"|"utf-16"|"utf-16le"|"utf-16be"
98235   **
98236   ** In its first form, this pragma returns the encoding of the main
98237   ** database. If the database is not initialized, it is initialized now.
98238   **
98239   ** The second form of this pragma is a no-op if the main database file
98240   ** has not already been initialized. In this case it sets the default
98241   ** encoding that will be used for the main database file if a new file
98242   ** is created. If an existing main database file is opened, then the
98243   ** default text encoding for the existing database is used.
98244   ** 
98245   ** In all cases new databases created using the ATTACH command are
98246   ** created to use the same default text encoding as the main database. If
98247   ** the main database has not been initialized and/or created when ATTACH
98248   ** is executed, this is done before the ATTACH operation.
98249   **
98250   ** In the second form this pragma sets the text encoding to be used in
98251   ** new database files created using this database handle. It is only
98252   ** useful if invoked immediately after the main database i
98253   */
98254   case PragTyp_ENCODING: {
98255     static const struct EncName {
98256       char *zName;
98257       u8 enc;
98258     } encnames[] = {
98259       { "UTF8",     SQLITE_UTF8        },
98260       { "UTF-8",    SQLITE_UTF8        },  /* Must be element [1] */
98261       { "UTF-16le", SQLITE_UTF16LE     },  /* Must be element [2] */
98262       { "UTF-16be", SQLITE_UTF16BE     },  /* Must be element [3] */
98263       { "UTF16le",  SQLITE_UTF16LE     },
98264       { "UTF16be",  SQLITE_UTF16BE     },
98265       { "UTF-16",   0                  }, /* SQLITE_UTF16NATIVE */
98266       { "UTF16",    0                  }, /* SQLITE_UTF16NATIVE */
98267       { 0, 0 }
98268     };
98269     const struct EncName *pEnc;
98270     if( !zRight ){    /* "PRAGMA encoding" */
98271       if( sqlite3ReadSchema(pParse) ) goto pragma_out;
98272       sqlite3VdbeSetNumCols(v, 1);
98273       sqlite3VdbeSetColName(v, 0, COLNAME_NAME, "encoding", SQLITE_STATIC);
98274       sqlite3VdbeAddOp2(v, OP_String8, 0, 1);
98275       assert( encnames[SQLITE_UTF8].enc==SQLITE_UTF8 );
98276       assert( encnames[SQLITE_UTF16LE].enc==SQLITE_UTF16LE );
98277       assert( encnames[SQLITE_UTF16BE].enc==SQLITE_UTF16BE );
98278       sqlite3VdbeChangeP4(v, -1, encnames[ENC(pParse->db)].zName, P4_STATIC);
98279       sqlite3VdbeAddOp2(v, OP_ResultRow, 1, 1);
98280     }else{                        /* "PRAGMA encoding = XXX" */
98281       /* Only change the value of sqlite.enc if the database handle is not
98282       ** initialized. If the main database exists, the new sqlite.enc value
98283       ** will be overwritten when the schema is next loaded. If it does not
98284       ** already exists, it will be created to use the new encoding value.
98285       */
98286       if( 
98287         !(DbHasProperty(db, 0, DB_SchemaLoaded)) || 
98288         DbHasProperty(db, 0, DB_Empty) 
98289       ){
98290         for(pEnc=&encnames[0]; pEnc->zName; pEnc++){
98291           if( 0==sqlite3StrICmp(zRight, pEnc->zName) ){
98292             ENC(pParse->db) = pEnc->enc ? pEnc->enc : SQLITE_UTF16NATIVE;
98293             break;
98294           }
98295         }
98296         if( !pEnc->zName ){
98297           sqlite3ErrorMsg(pParse, "unsupported encoding: %s", zRight);
98298         }
98299       }
98300     }
98301   }
98302   break;
98303 #endif /* SQLITE_OMIT_UTF16 */
98304 
98305 #ifndef SQLITE_OMIT_SCHEMA_VERSION_PRAGMAS
98306   /*
98307   **   PRAGMA [database.]schema_version
98308   **   PRAGMA [database.]schema_version = <integer>
98309   **
98310   **   PRAGMA [database.]user_version
98311   **   PRAGMA [database.]user_version = <integer>
98312   **
98313   **   PRAGMA [database.]freelist_count = <integer>
98314   **
98315   **   PRAGMA [database.]application_id
98316   **   PRAGMA [database.]application_id = <integer>
98317   **
98318   ** The pragma's schema_version and user_version are used to set or get
98319   ** the value of the schema-version and user-version, respectively. Both
98320   ** the schema-version and the user-version are 32-bit signed integers
98321   ** stored in the database header.
98322   **
98323   ** The schema-cookie is usually only manipulated internally by SQLite. It
98324   ** is incremented by SQLite whenever the database schema is modified (by
98325   ** creating or dropping a table or index). The schema version is used by
98326   ** SQLite each time a query is executed to ensure that the internal cache
98327   ** of the schema used when compiling the SQL query matches the schema of
98328   ** the database against which the compiled query is actually executed.
98329   ** Subverting this mechanism by using "PRAGMA schema_version" to modify
98330   ** the schema-version is potentially dangerous and may lead to program
98331   ** crashes or database corruption. Use with caution!
98332   **
98333   ** The user-version is not used internally by SQLite. It may be used by
98334   ** applications for any purpose.
98335   */
98336   case PragTyp_HEADER_VALUE: {
98337     int iCookie;   /* Cookie index. 1 for schema-cookie, 6 for user-cookie. */
98338     sqlite3VdbeUsesBtree(v, iDb);
98339     switch( zLeft[0] ){
98340       case 'a': case 'A':
98341         iCookie = BTREE_APPLICATION_ID;
98342         break;
98343       case 'f': case 'F':
98344         iCookie = BTREE_FREE_PAGE_COUNT;
98345         break;
98346       case 's': case 'S':
98347         iCookie = BTREE_SCHEMA_VERSION;
98348         break;
98349       default:
98350         iCookie = BTREE_USER_VERSION;
98351         break;
98352     }
98353 
98354     if( zRight && iCookie!=BTREE_FREE_PAGE_COUNT ){
98355       /* Write the specified cookie value */
98356       static const VdbeOpList setCookie[] = {
98357         { OP_Transaction,    0,  1,  0},    /* 0 */
98358         { OP_Integer,        0,  1,  0},    /* 1 */
98359         { OP_SetCookie,      0,  0,  1},    /* 2 */
98360       };
98361       int addr = sqlite3VdbeAddOpList(v, ArraySize(setCookie), setCookie);
98362       sqlite3VdbeChangeP1(v, addr, iDb);
98363       sqlite3VdbeChangeP1(v, addr+1, sqlite3Atoi(zRight));
98364       sqlite3VdbeChangeP1(v, addr+2, iDb);
98365       sqlite3VdbeChangeP2(v, addr+2, iCookie);
98366     }else{
98367       /* Read the specified cookie value */
98368       static const VdbeOpList readCookie[] = {
98369         { OP_Transaction,     0,  0,  0},    /* 0 */
98370         { OP_ReadCookie,      0,  1,  0},    /* 1 */
98371         { OP_ResultRow,       1,  1,  0}
98372       };
98373       int addr = sqlite3VdbeAddOpList(v, ArraySize(readCookie), readCookie);
98374       sqlite3VdbeChangeP1(v, addr, iDb);
98375       sqlite3VdbeChangeP1(v, addr+1, iDb);
98376       sqlite3VdbeChangeP3(v, addr+1, iCookie);
98377       sqlite3VdbeSetNumCols(v, 1);
98378       sqlite3VdbeSetColName(v, 0, COLNAME_NAME, zLeft, SQLITE_TRANSIENT);
98379     }
98380   }
98381   break;
98382 #endif /* SQLITE_OMIT_SCHEMA_VERSION_PRAGMAS */
98383 
98384 #ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS
98385   /*
98386   **   PRAGMA compile_options
98387   **
98388   ** Return the names of all compile-time options used in this build,
98389   ** one option per row.
98390   */
98391   case PragTyp_COMPILE_OPTIONS: {
98392     int i = 0;
98393     const char *zOpt;
98394     sqlite3VdbeSetNumCols(v, 1);
98395     pParse->nMem = 1;
98396     sqlite3VdbeSetColName(v, 0, COLNAME_NAME, "compile_option", SQLITE_STATIC);
98397     while( (zOpt = sqlite3_compileoption_get(i++))!=0 ){
98398       sqlite3VdbeAddOp4(v, OP_String8, 0, 1, 0, zOpt, 0);
98399       sqlite3VdbeAddOp2(v, OP_ResultRow, 1, 1);
98400     }
98401   }
98402   break;
98403 #endif /* SQLITE_OMIT_COMPILEOPTION_DIAGS */
98404 
98405 #ifndef SQLITE_OMIT_WAL
98406   /*
98407   **   PRAGMA [database.]wal_checkpoint = passive|full|restart
98408   **
98409   ** Checkpoint the database.
98410   */
98411   case PragTyp_WAL_CHECKPOINT: {
98412     int iBt = (pId2->z?iDb:SQLITE_MAX_ATTACHED);
98413     int eMode = SQLITE_CHECKPOINT_PASSIVE;
98414     if( zRight ){
98415       if( sqlite3StrICmp(zRight, "full")==0 ){
98416         eMode = SQLITE_CHECKPOINT_FULL;
98417       }else if( sqlite3StrICmp(zRight, "restart")==0 ){
98418         eMode = SQLITE_CHECKPOINT_RESTART;
98419       }
98420     }
98421     sqlite3VdbeSetNumCols(v, 3);
98422     pParse->nMem = 3;
98423     sqlite3VdbeSetColName(v, 0, COLNAME_NAME, "busy", SQLITE_STATIC);
98424     sqlite3VdbeSetColName(v, 1, COLNAME_NAME, "log", SQLITE_STATIC);
98425     sqlite3VdbeSetColName(v, 2, COLNAME_NAME, "checkpointed", SQLITE_STATIC);
98426 
98427     sqlite3VdbeAddOp3(v, OP_Checkpoint, iBt, eMode, 1);
98428     sqlite3VdbeAddOp2(v, OP_ResultRow, 1, 3);
98429   }
98430   break;
98431 
98432   /*
98433   **   PRAGMA wal_autocheckpoint
98434   **   PRAGMA wal_autocheckpoint = N
98435   **
98436   ** Configure a database connection to automatically checkpoint a database
98437   ** after accumulating N frames in the log. Or query for the current value
98438   ** of N.
98439   */
98440   case PragTyp_WAL_AUTOCHECKPOINT: {
98441     if( zRight ){
98442       sqlite3_wal_autocheckpoint(db, sqlite3Atoi(zRight));
98443     }
98444     returnSingleInt(pParse, "wal_autocheckpoint", 
98445        db->xWalCallback==sqlite3WalDefaultHook ? 
98446            SQLITE_PTR_TO_INT(db->pWalArg) : 0);
98447   }
98448   break;
98449 #endif
98450 
98451   /*
98452   **  PRAGMA shrink_memory
98453   **
98454   ** This pragma attempts to free as much memory as possible from the
98455   ** current database connection.
98456   */
98457   case PragTyp_SHRINK_MEMORY: {
98458     sqlite3_db_release_memory(db);
98459     break;
98460   }
98461 
98462   /*
98463   **   PRAGMA busy_timeout
98464   **   PRAGMA busy_timeout = N
98465   **
98466   ** Call sqlite3_busy_timeout(db, N).  Return the current timeout value
98467   ** if one is set.  If no busy handler or a different busy handler is set
98468   ** then 0 is returned.  Setting the busy_timeout to 0 or negative
98469   ** disables the timeout.
98470   */
98471   /*case PragTyp_BUSY_TIMEOUT*/ default: {
98472     assert( aPragmaNames[mid].ePragTyp==PragTyp_BUSY_TIMEOUT );
98473     if( zRight ){
98474       sqlite3_busy_timeout(db, sqlite3Atoi(zRight));
98475     }
98476     returnSingleInt(pParse, "timeout",  db->busyTimeout);
98477     break;
98478   }
98479 
98480   /*
98481   **   PRAGMA soft_heap_limit
98482   **   PRAGMA soft_heap_limit = N
98483   **
98484   ** Call sqlite3_soft_heap_limit64(N).  Return the result.  If N is omitted,
98485   ** use -1.
98486   */
98487   case PragTyp_SOFT_HEAP_LIMIT: {
98488     sqlite3_int64 N;
98489     if( zRight && sqlite3Atoi64(zRight, &N, 1000000, SQLITE_UTF8)==SQLITE_OK ){
98490       sqlite3_soft_heap_limit64(N);
98491     }
98492     returnSingleInt(pParse, "soft_heap_limit",  sqlite3_soft_heap_limit64(-1));
98493     break;
98494   }
98495 
98496 #if defined(SQLITE_DEBUG) || defined(SQLITE_TEST)
98497   /*
98498   ** Report the current state of file logs for all databases
98499   */
98500   case PragTyp_LOCK_STATUS: {
98501     static const char *const azLockName[] = {
98502       "unlocked", "shared", "reserved", "pending", "exclusive"
98503     };
98504     int i;
98505     sqlite3VdbeSetNumCols(v, 2);
98506     pParse->nMem = 2;
98507     sqlite3VdbeSetColName(v, 0, COLNAME_NAME, "database", SQLITE_STATIC);
98508     sqlite3VdbeSetColName(v, 1, COLNAME_NAME, "status", SQLITE_STATIC);
98509     for(i=0; i<db->nDb; i++){
98510       Btree *pBt;
98511       const char *zState = "unknown";
98512       int j;
98513       if( db->aDb[i].zName==0 ) continue;
98514       sqlite3VdbeAddOp4(v, OP_String8, 0, 1, 0, db->aDb[i].zName, P4_STATIC);
98515       pBt = db->aDb[i].pBt;
98516       if( pBt==0 || sqlite3BtreePager(pBt)==0 ){
98517         zState = "closed";
98518       }else if( sqlite3_file_control(db, i ? db->aDb[i].zName : 0, 
98519                                      SQLITE_FCNTL_LOCKSTATE, &j)==SQLITE_OK ){
98520          zState = azLockName[j];
98521       }
98522       sqlite3VdbeAddOp4(v, OP_String8, 0, 2, 0, zState, P4_STATIC);
98523       sqlite3VdbeAddOp2(v, OP_ResultRow, 1, 2);
98524     }
98525     break;
98526   }
98527 #endif
98528 
98529 #ifdef SQLITE_HAS_CODEC
98530   case PragTyp_KEY: {
98531     if( zRight ) sqlite3_key_v2(db, zDb, zRight, sqlite3Strlen30(zRight));
98532     break;
98533   }
98534   case PragTyp_REKEY: {
98535     if( zRight ) sqlite3_rekey_v2(db, zDb, zRight, sqlite3Strlen30(zRight));
98536     break;
98537   }
98538   case PragTyp_HEXKEY: {
98539     if( zRight ){
98540       u8 iByte;
98541       int i;
98542       char zKey[40];
98543       for(i=0, iByte=0; i<sizeof(zKey)*2 && sqlite3Isxdigit(zRight[i]); i++){
98544         iByte = (iByte<<4) + sqlite3HexToInt(zRight[i]);
98545         if( (i&1)!=0 ) zKey[i/2] = iByte;
98546       }
98547       if( (zLeft[3] & 0xf)==0xb ){
98548         sqlite3_key_v2(db, zDb, zKey, i/2);
98549       }else{
98550         sqlite3_rekey_v2(db, zDb, zKey, i/2);
98551       }
98552     }
98553     break;
98554   }
98555 #endif
98556 #if defined(SQLITE_HAS_CODEC) || defined(SQLITE_ENABLE_CEROD)
98557   case PragTyp_ACTIVATE_EXTENSIONS: if( zRight ){
98558 #ifdef SQLITE_HAS_CODEC
98559     if( sqlite3StrNICmp(zRight, "see-", 4)==0 ){
98560       sqlite3_activate_see(&zRight[4]);
98561     }
98562 #endif
98563 #ifdef SQLITE_ENABLE_CEROD
98564     if( sqlite3StrNICmp(zRight, "cerod-", 6)==0 ){
98565       sqlite3_activate_cerod(&zRight[6]);
98566     }
98567 #endif
98568   }
98569   break;
98570 #endif
98571 
98572   } /* End of the PRAGMA switch */
98573 
98574 pragma_out:
98575   sqlite3DbFree(db, zLeft);
98576   sqlite3DbFree(db, zRight);
98577 }
98578 
98579 #endif /* SQLITE_OMIT_PRAGMA */
98580 
98581 /************** End of pragma.c **********************************************/
98582 /************** Begin file prepare.c *****************************************/
98583 /*
98584 ** 2005 May 25
98585 **
98586 ** The author disclaims copyright to this source code.  In place of
98587 ** a legal notice, here is a blessing:
98588 **
98589 **    May you do good and not evil.
98590 **    May you find forgiveness for yourself and forgive others.
98591 **    May you share freely, never taking more than you give.
98592 **
98593 *************************************************************************
98594 ** This file contains the implementation of the sqlite3_prepare()
98595 ** interface, and routines that contribute to loading the database schema
98596 ** from disk.
98597 */
98598 
98599 /*
98600 ** Fill the InitData structure with an error message that indicates
98601 ** that the database is corrupt.
98602 */
98603 static void corruptSchema(
98604   InitData *pData,     /* Initialization context */
98605   const char *zObj,    /* Object being parsed at the point of error */
98606   const char *zExtra   /* Error information */
98607 ){
98608   sqlite3 *db = pData->db;
98609   if( !db->mallocFailed && (db->flags & SQLITE_RecoveryMode)==0 ){
98610     if( zObj==0 ) zObj = "?";
98611     sqlite3SetString(pData->pzErrMsg, db,
98612       "malformed database schema (%s)", zObj);
98613     if( zExtra ){
98614       *pData->pzErrMsg = sqlite3MAppendf(db, *pData->pzErrMsg, 
98615                                  "%s - %s", *pData->pzErrMsg, zExtra);
98616     }
98617   }
98618   pData->rc = db->mallocFailed ? SQLITE_NOMEM : SQLITE_CORRUPT_BKPT;
98619 }
98620 
98621 /*
98622 ** This is the callback routine for the code that initializes the
98623 ** database.  See sqlite3Init() below for additional information.
98624 ** This routine is also called from the OP_ParseSchema opcode of the VDBE.
98625 **
98626 ** Each callback contains the following information:
98627 **
98628 **     argv[0] = name of thing being created
98629 **     argv[1] = root page number for table or index. 0 for trigger or view.
98630 **     argv[2] = SQL text for the CREATE statement.
98631 **
98632 */
98633 SQLITE_PRIVATE int sqlite3InitCallback(void *pInit, int argc, char **argv, char **NotUsed){
98634   InitData *pData = (InitData*)pInit;
98635   sqlite3 *db = pData->db;
98636   int iDb = pData->iDb;
98637 
98638   assert( argc==3 );
98639   UNUSED_PARAMETER2(NotUsed, argc);
98640   assert( sqlite3_mutex_held(db->mutex) );
98641   DbClearProperty(db, iDb, DB_Empty);
98642   if( db->mallocFailed ){
98643     corruptSchema(pData, argv[0], 0);
98644     return 1;
98645   }
98646 
98647   assert( iDb>=0 && iDb<db->nDb );
98648   if( argv==0 ) return 0;   /* Might happen if EMPTY_RESULT_CALLBACKS are on */
98649   if( argv[1]==0 ){
98650     corruptSchema(pData, argv[0], 0);
98651   }else if( argv[2] && argv[2][0] ){
98652     /* Call the parser to process a CREATE TABLE, INDEX or VIEW.
98653     ** But because db->init.busy is set to 1, no VDBE code is generated
98654     ** or executed.  All the parser does is build the internal data
98655     ** structures that describe the table, index, or view.
98656     */
98657     int rc;
98658     sqlite3_stmt *pStmt;
98659     TESTONLY(int rcp);            /* Return code from sqlite3_prepare() */
98660 
98661     assert( db->init.busy );
98662     db->init.iDb = iDb;
98663     db->init.newTnum = sqlite3Atoi(argv[1]);
98664     db->init.orphanTrigger = 0;
98665     TESTONLY(rcp = ) sqlite3_prepare(db, argv[2], -1, &pStmt, 0);
98666     rc = db->errCode;
98667     assert( (rc&0xFF)==(rcp&0xFF) );
98668     db->init.iDb = 0;
98669     if( SQLITE_OK!=rc ){
98670       if( db->init.orphanTrigger ){
98671         assert( iDb==1 );
98672       }else{
98673         pData->rc = rc;
98674         if( rc==SQLITE_NOMEM ){
98675           db->mallocFailed = 1;
98676         }else if( rc!=SQLITE_INTERRUPT && (rc&0xFF)!=SQLITE_LOCKED ){
98677           corruptSchema(pData, argv[0], sqlite3_errmsg(db));
98678         }
98679       }
98680     }
98681     sqlite3_finalize(pStmt);
98682   }else if( argv[0]==0 ){
98683     corruptSchema(pData, 0, 0);
98684   }else{
98685     /* If the SQL column is blank it means this is an index that
98686     ** was created to be the PRIMARY KEY or to fulfill a UNIQUE
98687     ** constraint for a CREATE TABLE.  The index should have already
98688     ** been created when we processed the CREATE TABLE.  All we have
98689     ** to do here is record the root page number for that index.
98690     */
98691     Index *pIndex;
98692     pIndex = sqlite3FindIndex(db, argv[0], db->aDb[iDb].zName);
98693     if( pIndex==0 ){
98694       /* This can occur if there exists an index on a TEMP table which
98695       ** has the same name as another index on a permanent index.  Since
98696       ** the permanent table is hidden by the TEMP table, we can also
98697       ** safely ignore the index on the permanent table.
98698       */
98699       /* Do Nothing */;
98700     }else if( sqlite3GetInt32(argv[1], &pIndex->tnum)==0 ){
98701       corruptSchema(pData, argv[0], "invalid rootpage");
98702     }
98703   }
98704   return 0;
98705 }
98706 
98707 /*
98708 ** Attempt to read the database schema and initialize internal
98709 ** data structures for a single database file.  The index of the
98710 ** database file is given by iDb.  iDb==0 is used for the main
98711 ** database.  iDb==1 should never be used.  iDb>=2 is used for
98712 ** auxiliary databases.  Return one of the SQLITE_ error codes to
98713 ** indicate success or failure.
98714 */
98715 static int sqlite3InitOne(sqlite3 *db, int iDb, char **pzErrMsg){
98716   int rc;
98717   int i;
98718 #ifndef SQLITE_OMIT_DEPRECATED
98719   int size;
98720 #endif
98721   Table *pTab;
98722   Db *pDb;
98723   char const *azArg[4];
98724   int meta[5];
98725   InitData initData;
98726   char const *zMasterSchema;
98727   char const *zMasterName;
98728   int openedTransaction = 0;
98729 
98730   /*
98731   ** The master database table has a structure like this
98732   */
98733   static const char master_schema[] = 
98734      "CREATE TABLE sqlite_master(\n"
98735      "  type text,\n"
98736      "  name text,\n"
98737      "  tbl_name text,\n"
98738      "  rootpage integer,\n"
98739      "  sql text\n"
98740      ")"
98741   ;
98742 #ifndef SQLITE_OMIT_TEMPDB
98743   static const char temp_master_schema[] = 
98744      "CREATE TEMP TABLE sqlite_temp_master(\n"
98745      "  type text,\n"
98746      "  name text,\n"
98747      "  tbl_name text,\n"
98748      "  rootpage integer,\n"
98749      "  sql text\n"
98750      ")"
98751   ;
98752 #else
98753   #define temp_master_schema 0
98754 #endif
98755 
98756   assert( iDb>=0 && iDb<db->nDb );
98757   assert( db->aDb[iDb].pSchema );
98758   assert( sqlite3_mutex_held(db->mutex) );
98759   assert( iDb==1 || sqlite3BtreeHoldsMutex(db->aDb[iDb].pBt) );
98760 
98761   /* zMasterSchema and zInitScript are set to point at the master schema
98762   ** and initialisation script appropriate for the database being
98763   ** initialized. zMasterName is the name of the master table.
98764   */
98765   if( !OMIT_TEMPDB && iDb==1 ){
98766     zMasterSchema = temp_master_schema;
98767   }else{
98768     zMasterSchema = master_schema;
98769   }
98770   zMasterName = SCHEMA_TABLE(iDb);
98771 
98772   /* Construct the schema tables.  */
98773   azArg[0] = zMasterName;
98774   azArg[1] = "1";
98775   azArg[2] = zMasterSchema;
98776   azArg[3] = 0;
98777   initData.db = db;
98778   initData.iDb = iDb;
98779   initData.rc = SQLITE_OK;
98780   initData.pzErrMsg = pzErrMsg;
98781   sqlite3InitCallback(&initData, 3, (char **)azArg, 0);
98782   if( initData.rc ){
98783     rc = initData.rc;
98784     goto error_out;
98785   }
98786   pTab = sqlite3FindTable(db, zMasterName, db->aDb[iDb].zName);
98787   if( ALWAYS(pTab) ){
98788     pTab->tabFlags |= TF_Readonly;
98789   }
98790 
98791   /* Create a cursor to hold the database open
98792   */
98793   pDb = &db->aDb[iDb];
98794   if( pDb->pBt==0 ){
98795     if( !OMIT_TEMPDB && ALWAYS(iDb==1) ){
98796       DbSetProperty(db, 1, DB_SchemaLoaded);
98797     }
98798     return SQLITE_OK;
98799   }
98800 
98801   /* If there is not already a read-only (or read-write) transaction opened
98802   ** on the b-tree database, open one now. If a transaction is opened, it 
98803   ** will be closed before this function returns.  */
98804   sqlite3BtreeEnter(pDb->pBt);
98805   if( !sqlite3BtreeIsInReadTrans(pDb->pBt) ){
98806     rc = sqlite3BtreeBeginTrans(pDb->pBt, 0);
98807     if( rc!=SQLITE_OK ){
98808       sqlite3SetString(pzErrMsg, db, "%s", sqlite3ErrStr(rc));
98809       goto initone_error_out;
98810     }
98811     openedTransaction = 1;
98812   }
98813 
98814   /* Get the database meta information.
98815   **
98816   ** Meta values are as follows:
98817   **    meta[0]   Schema cookie.  Changes with each schema change.
98818   **    meta[1]   File format of schema layer.
98819   **    meta[2]   Size of the page cache.
98820   **    meta[3]   Largest rootpage (auto/incr_vacuum mode)
98821   **    meta[4]   Db text encoding. 1:UTF-8 2:UTF-16LE 3:UTF-16BE
98822   **    meta[5]   User version
98823   **    meta[6]   Incremental vacuum mode
98824   **    meta[7]   unused
98825   **    meta[8]   unused
98826   **    meta[9]   unused
98827   **
98828   ** Note: The #defined SQLITE_UTF* symbols in sqliteInt.h correspond to
98829   ** the possible values of meta[4].
98830   */
98831   for(i=0; i<ArraySize(meta); i++){
98832     sqlite3BtreeGetMeta(pDb->pBt, i+1, (u32 *)&meta[i]);
98833   }
98834   pDb->pSchema->schema_cookie = meta[BTREE_SCHEMA_VERSION-1];
98835 
98836   /* If opening a non-empty database, check the text encoding. For the
98837   ** main database, set sqlite3.enc to the encoding of the main database.
98838   ** For an attached db, it is an error if the encoding is not the same
98839   ** as sqlite3.enc.
98840   */
98841   if( meta[BTREE_TEXT_ENCODING-1] ){  /* text encoding */
98842     if( iDb==0 ){
98843 #ifndef SQLITE_OMIT_UTF16
98844       u8 encoding;
98845       /* If opening the main database, set ENC(db). */
98846       encoding = (u8)meta[BTREE_TEXT_ENCODING-1] & 3;
98847       if( encoding==0 ) encoding = SQLITE_UTF8;
98848       ENC(db) = encoding;
98849 #else
98850       ENC(db) = SQLITE_UTF8;
98851 #endif
98852     }else{
98853       /* If opening an attached database, the encoding much match ENC(db) */
98854       if( meta[BTREE_TEXT_ENCODING-1]!=ENC(db) ){
98855         sqlite3SetString(pzErrMsg, db, "attached databases must use the same"
98856             " text encoding as main database");
98857         rc = SQLITE_ERROR;
98858         goto initone_error_out;
98859       }
98860     }
98861   }else{
98862     DbSetProperty(db, iDb, DB_Empty);
98863   }
98864   pDb->pSchema->enc = ENC(db);
98865 
98866   if( pDb->pSchema->cache_size==0 ){
98867 #ifndef SQLITE_OMIT_DEPRECATED
98868     size = sqlite3AbsInt32(meta[BTREE_DEFAULT_CACHE_SIZE-1]);
98869     if( size==0 ){ size = SQLITE_DEFAULT_CACHE_SIZE; }
98870     pDb->pSchema->cache_size = size;
98871 #else
98872     pDb->pSchema->cache_size = SQLITE_DEFAULT_CACHE_SIZE;
98873 #endif
98874     sqlite3BtreeSetCacheSize(pDb->pBt, pDb->pSchema->cache_size);
98875   }
98876 
98877   /*
98878   ** file_format==1    Version 3.0.0.
98879   ** file_format==2    Version 3.1.3.  // ALTER TABLE ADD COLUMN
98880   ** file_format==3    Version 3.1.4.  // ditto but with non-NULL defaults
98881   ** file_format==4    Version 3.3.0.  // DESC indices.  Boolean constants
98882   */
98883   pDb->pSchema->file_format = (u8)meta[BTREE_FILE_FORMAT-1];
98884   if( pDb->pSchema->file_format==0 ){
98885     pDb->pSchema->file_format = 1;
98886   }
98887   if( pDb->pSchema->file_format>SQLITE_MAX_FILE_FORMAT ){
98888     sqlite3SetString(pzErrMsg, db, "unsupported file format");
98889     rc = SQLITE_ERROR;
98890     goto initone_error_out;
98891   }
98892 
98893   /* Ticket #2804:  When we open a database in the newer file format,
98894   ** clear the legacy_file_format pragma flag so that a VACUUM will
98895   ** not downgrade the database and thus invalidate any descending
98896   ** indices that the user might have created.
98897   */
98898   if( iDb==0 && meta[BTREE_FILE_FORMAT-1]>=4 ){
98899     db->flags &= ~SQLITE_LegacyFileFmt;
98900   }
98901 
98902   /* Read the schema information out of the schema tables
98903   */
98904   assert( db->init.busy );
98905   {
98906     char *zSql;
98907     zSql = sqlite3MPrintf(db, 
98908         "SELECT name, rootpage, sql FROM '%q'.%s ORDER BY rowid",
98909         db->aDb[iDb].zName, zMasterName);
98910 #ifndef SQLITE_OMIT_AUTHORIZATION
98911     {
98912       int (*xAuth)(void*,int,const char*,const char*,const char*,const char*);
98913       xAuth = db->xAuth;
98914       db->xAuth = 0;
98915 #endif
98916       rc = sqlite3_exec(db, zSql, sqlite3InitCallback, &initData, 0);
98917 #ifndef SQLITE_OMIT_AUTHORIZATION
98918       db->xAuth = xAuth;
98919     }
98920 #endif
98921     if( rc==SQLITE_OK ) rc = initData.rc;
98922     sqlite3DbFree(db, zSql);
98923 #ifndef SQLITE_OMIT_ANALYZE
98924     if( rc==SQLITE_OK ){
98925       sqlite3AnalysisLoad(db, iDb);
98926     }
98927 #endif
98928   }
98929   if( db->mallocFailed ){
98930     rc = SQLITE_NOMEM;
98931     sqlite3ResetAllSchemasOfConnection(db);
98932   }
98933   if( rc==SQLITE_OK || (db->flags&SQLITE_RecoveryMode)){
98934     /* Black magic: If the SQLITE_RecoveryMode flag is set, then consider
98935     ** the schema loaded, even if errors occurred. In this situation the 
98936     ** current sqlite3_prepare() operation will fail, but the following one
98937     ** will attempt to compile the supplied statement against whatever subset
98938     ** of the schema was loaded before the error occurred. The primary
98939     ** purpose of this is to allow access to the sqlite_master table
98940     ** even when its contents have been corrupted.
98941     */
98942     DbSetProperty(db, iDb, DB_SchemaLoaded);
98943     rc = SQLITE_OK;
98944   }
98945 
98946   /* Jump here for an error that occurs after successfully allocating
98947   ** curMain and calling sqlite3BtreeEnter(). For an error that occurs
98948   ** before that point, jump to error_out.
98949   */
98950 initone_error_out:
98951   if( openedTransaction ){
98952     sqlite3BtreeCommit(pDb->pBt);
98953   }
98954   sqlite3BtreeLeave(pDb->pBt);
98955 
98956 error_out:
98957   if( rc==SQLITE_NOMEM || rc==SQLITE_IOERR_NOMEM ){
98958     db->mallocFailed = 1;
98959   }
98960   return rc;
98961 }
98962 
98963 /*
98964 ** Initialize all database files - the main database file, the file
98965 ** used to store temporary tables, and any additional database files
98966 ** created using ATTACH statements.  Return a success code.  If an
98967 ** error occurs, write an error message into *pzErrMsg.
98968 **
98969 ** After a database is initialized, the DB_SchemaLoaded bit is set
98970 ** bit is set in the flags field of the Db structure. If the database
98971 ** file was of zero-length, then the DB_Empty flag is also set.
98972 */
98973 SQLITE_PRIVATE int sqlite3Init(sqlite3 *db, char **pzErrMsg){
98974   int i, rc;
98975   int commit_internal = !(db->flags&SQLITE_InternChanges);
98976   
98977   assert( sqlite3_mutex_held(db->mutex) );
98978   rc = SQLITE_OK;
98979   db->init.busy = 1;
98980   for(i=0; rc==SQLITE_OK && i<db->nDb; i++){
98981     if( DbHasProperty(db, i, DB_SchemaLoaded) || i==1 ) continue;
98982     rc = sqlite3InitOne(db, i, pzErrMsg);
98983     if( rc ){
98984       sqlite3ResetOneSchema(db, i);
98985     }
98986   }
98987 
98988   /* Once all the other databases have been initialized, load the schema
98989   ** for the TEMP database. This is loaded last, as the TEMP database
98990   ** schema may contain references to objects in other databases.
98991   */
98992 #ifndef SQLITE_OMIT_TEMPDB
98993   if( rc==SQLITE_OK && ALWAYS(db->nDb>1)
98994                     && !DbHasProperty(db, 1, DB_SchemaLoaded) ){
98995     rc = sqlite3InitOne(db, 1, pzErrMsg);
98996     if( rc ){
98997       sqlite3ResetOneSchema(db, 1);
98998     }
98999   }
99000 #endif
99001 
99002   db->init.busy = 0;
99003   if( rc==SQLITE_OK && commit_internal ){
99004     sqlite3CommitInternalChanges(db);
99005   }
99006 
99007   return rc; 
99008 }
99009 
99010 /*
99011 ** This routine is a no-op if the database schema is already initialized.
99012 ** Otherwise, the schema is loaded. An error code is returned.
99013 */
99014 SQLITE_PRIVATE int sqlite3ReadSchema(Parse *pParse){
99015   int rc = SQLITE_OK;
99016   sqlite3 *db = pParse->db;
99017   assert( sqlite3_mutex_held(db->mutex) );
99018   if( !db->init.busy ){
99019     rc = sqlite3Init(db, &pParse->zErrMsg);
99020   }
99021   if( rc!=SQLITE_OK ){
99022     pParse->rc = rc;
99023     pParse->nErr++;
99024   }
99025   return rc;
99026 }
99027 
99028 
99029 /*
99030 ** Check schema cookies in all databases.  If any cookie is out
99031 ** of date set pParse->rc to SQLITE_SCHEMA.  If all schema cookies
99032 ** make no changes to pParse->rc.
99033 */
99034 static void schemaIsValid(Parse *pParse){
99035   sqlite3 *db = pParse->db;
99036   int iDb;
99037   int rc;
99038   int cookie;
99039 
99040   assert( pParse->checkSchema );
99041   assert( sqlite3_mutex_held(db->mutex) );
99042   for(iDb=0; iDb<db->nDb; iDb++){
99043     int openedTransaction = 0;         /* True if a transaction is opened */
99044     Btree *pBt = db->aDb[iDb].pBt;     /* Btree database to read cookie from */
99045     if( pBt==0 ) continue;
99046 
99047     /* If there is not already a read-only (or read-write) transaction opened
99048     ** on the b-tree database, open one now. If a transaction is opened, it 
99049     ** will be closed immediately after reading the meta-value. */
99050     if( !sqlite3BtreeIsInReadTrans(pBt) ){
99051       rc = sqlite3BtreeBeginTrans(pBt, 0);
99052       if( rc==SQLITE_NOMEM || rc==SQLITE_IOERR_NOMEM ){
99053         db->mallocFailed = 1;
99054       }
99055       if( rc!=SQLITE_OK ) return;
99056       openedTransaction = 1;
99057     }
99058 
99059     /* Read the schema cookie from the database. If it does not match the 
99060     ** value stored as part of the in-memory schema representation,
99061     ** set Parse.rc to SQLITE_SCHEMA. */
99062     sqlite3BtreeGetMeta(pBt, BTREE_SCHEMA_VERSION, (u32 *)&cookie);
99063     assert( sqlite3SchemaMutexHeld(db, iDb, 0) );
99064     if( cookie!=db->aDb[iDb].pSchema->schema_cookie ){
99065       sqlite3ResetOneSchema(db, iDb);
99066       pParse->rc = SQLITE_SCHEMA;
99067     }
99068 
99069     /* Close the transaction, if one was opened. */
99070     if( openedTransaction ){
99071       sqlite3BtreeCommit(pBt);
99072     }
99073   }
99074 }
99075 
99076 /*
99077 ** Convert a schema pointer into the iDb index that indicates
99078 ** which database file in db->aDb[] the schema refers to.
99079 **
99080 ** If the same database is attached more than once, the first
99081 ** attached database is returned.
99082 */
99083 SQLITE_PRIVATE int sqlite3SchemaToIndex(sqlite3 *db, Schema *pSchema){
99084   int i = -1000000;
99085 
99086   /* If pSchema is NULL, then return -1000000. This happens when code in 
99087   ** expr.c is trying to resolve a reference to a transient table (i.e. one
99088   ** created by a sub-select). In this case the return value of this 
99089   ** function should never be used.
99090   **
99091   ** We return -1000000 instead of the more usual -1 simply because using
99092   ** -1000000 as the incorrect index into db->aDb[] is much 
99093   ** more likely to cause a segfault than -1 (of course there are assert()
99094   ** statements too, but it never hurts to play the odds).
99095   */
99096   assert( sqlite3_mutex_held(db->mutex) );
99097   if( pSchema ){
99098     for(i=0; ALWAYS(i<db->nDb); i++){
99099       if( db->aDb[i].pSchema==pSchema ){
99100         break;
99101       }
99102     }
99103     assert( i>=0 && i<db->nDb );
99104   }
99105   return i;
99106 }
99107 
99108 /*
99109 ** Free all memory allocations in the pParse object
99110 */
99111 SQLITE_PRIVATE void sqlite3ParserReset(Parse *pParse){
99112   if( pParse ) sqlite3ExprListDelete(pParse->db, pParse->pConstExpr);
99113 }
99114 
99115 /*
99116 ** Compile the UTF-8 encoded SQL statement zSql into a statement handle.
99117 */
99118 static int sqlite3Prepare(
99119   sqlite3 *db,              /* Database handle. */
99120   const char *zSql,         /* UTF-8 encoded SQL statement. */
99121   int nBytes,               /* Length of zSql in bytes. */
99122   int saveSqlFlag,          /* True to copy SQL text into the sqlite3_stmt */
99123   Vdbe *pReprepare,         /* VM being reprepared */
99124   sqlite3_stmt **ppStmt,    /* OUT: A pointer to the prepared statement */
99125   const char **pzTail       /* OUT: End of parsed string */
99126 ){
99127   Parse *pParse;            /* Parsing context */
99128   char *zErrMsg = 0;        /* Error message */
99129   int rc = SQLITE_OK;       /* Result code */
99130   int i;                    /* Loop counter */
99131 
99132   /* Allocate the parsing context */
99133   pParse = sqlite3StackAllocZero(db, sizeof(*pParse));
99134   if( pParse==0 ){
99135     rc = SQLITE_NOMEM;
99136     goto end_prepare;
99137   }
99138   pParse->pReprepare = pReprepare;
99139   assert( ppStmt && *ppStmt==0 );
99140   assert( !db->mallocFailed );
99141   assert( sqlite3_mutex_held(db->mutex) );
99142 
99143   /* Check to verify that it is possible to get a read lock on all
99144   ** database schemas.  The inability to get a read lock indicates that
99145   ** some other database connection is holding a write-lock, which in
99146   ** turn means that the other connection has made uncommitted changes
99147   ** to the schema.
99148   **
99149   ** Were we to proceed and prepare the statement against the uncommitted
99150   ** schema changes and if those schema changes are subsequently rolled
99151   ** back and different changes are made in their place, then when this
99152   ** prepared statement goes to run the schema cookie would fail to detect
99153   ** the schema change.  Disaster would follow.
99154   **
99155   ** This thread is currently holding mutexes on all Btrees (because
99156   ** of the sqlite3BtreeEnterAll() in sqlite3LockAndPrepare()) so it
99157   ** is not possible for another thread to start a new schema change
99158   ** while this routine is running.  Hence, we do not need to hold 
99159   ** locks on the schema, we just need to make sure nobody else is 
99160   ** holding them.
99161   **
99162   ** Note that setting READ_UNCOMMITTED overrides most lock detection,
99163   ** but it does *not* override schema lock detection, so this all still
99164   ** works even if READ_UNCOMMITTED is set.
99165   */
99166   for(i=0; i<db->nDb; i++) {
99167     Btree *pBt = db->aDb[i].pBt;
99168     if( pBt ){
99169       assert( sqlite3BtreeHoldsMutex(pBt) );
99170       rc = sqlite3BtreeSchemaLocked(pBt);
99171       if( rc ){
99172         const char *zDb = db->aDb[i].zName;
99173         sqlite3Error(db, rc, "database schema is locked: %s", zDb);
99174         testcase( db->flags & SQLITE_ReadUncommitted );
99175         goto end_prepare;
99176       }
99177     }
99178   }
99179 
99180   sqlite3VtabUnlockList(db);
99181 
99182   pParse->db = db;
99183   pParse->nQueryLoop = 0;  /* Logarithmic, so 0 really means 1 */
99184   if( nBytes>=0 && (nBytes==0 || zSql[nBytes-1]!=0) ){
99185     char *zSqlCopy;
99186     int mxLen = db->aLimit[SQLITE_LIMIT_SQL_LENGTH];
99187     testcase( nBytes==mxLen );
99188     testcase( nBytes==mxLen+1 );
99189     if( nBytes>mxLen ){
99190       sqlite3Error(db, SQLITE_TOOBIG, "statement too long");
99191       rc = sqlite3ApiExit(db, SQLITE_TOOBIG);
99192       goto end_prepare;
99193     }
99194     zSqlCopy = sqlite3DbStrNDup(db, zSql, nBytes);
99195     if( zSqlCopy ){
99196       sqlite3RunParser(pParse, zSqlCopy, &zErrMsg);
99197       sqlite3DbFree(db, zSqlCopy);
99198       pParse->zTail = &zSql[pParse->zTail-zSqlCopy];
99199     }else{
99200       pParse->zTail = &zSql[nBytes];
99201     }
99202   }else{
99203     sqlite3RunParser(pParse, zSql, &zErrMsg);
99204   }
99205   assert( 0==pParse->nQueryLoop );
99206 
99207   if( db->mallocFailed ){
99208     pParse->rc = SQLITE_NOMEM;
99209   }
99210   if( pParse->rc==SQLITE_DONE ) pParse->rc = SQLITE_OK;
99211   if( pParse->checkSchema ){
99212     schemaIsValid(pParse);
99213   }
99214   if( db->mallocFailed ){
99215     pParse->rc = SQLITE_NOMEM;
99216   }
99217   if( pzTail ){
99218     *pzTail = pParse->zTail;
99219   }
99220   rc = pParse->rc;
99221 
99222 #ifndef SQLITE_OMIT_EXPLAIN
99223   if( rc==SQLITE_OK && pParse->pVdbe && pParse->explain ){
99224     static const char * const azColName[] = {
99225        "addr", "opcode", "p1", "p2", "p3", "p4", "p5", "comment",
99226        "selectid", "order", "from", "detail"
99227     };
99228     int iFirst, mx;
99229     if( pParse->explain==2 ){
99230       sqlite3VdbeSetNumCols(pParse->pVdbe, 4);
99231       iFirst = 8;
99232       mx = 12;
99233     }else{
99234       sqlite3VdbeSetNumCols(pParse->pVdbe, 8);
99235       iFirst = 0;
99236       mx = 8;
99237     }
99238     for(i=iFirst; i<mx; i++){
99239       sqlite3VdbeSetColName(pParse->pVdbe, i-iFirst, COLNAME_NAME,
99240                             azColName[i], SQLITE_STATIC);
99241     }
99242   }
99243 #endif
99244 
99245   if( db->init.busy==0 ){
99246     Vdbe *pVdbe = pParse->pVdbe;
99247     sqlite3VdbeSetSql(pVdbe, zSql, (int)(pParse->zTail-zSql), saveSqlFlag);
99248   }
99249   if( pParse->pVdbe && (rc!=SQLITE_OK || db->mallocFailed) ){
99250     sqlite3VdbeFinalize(pParse->pVdbe);
99251     assert(!(*ppStmt));
99252   }else{
99253     *ppStmt = (sqlite3_stmt*)pParse->pVdbe;
99254   }
99255 
99256   if( zErrMsg ){
99257     sqlite3Error(db, rc, "%s", zErrMsg);
99258     sqlite3DbFree(db, zErrMsg);
99259   }else{
99260     sqlite3Error(db, rc, 0);
99261   }
99262 
99263   /* Delete any TriggerPrg structures allocated while parsing this statement. */
99264   while( pParse->pTriggerPrg ){
99265     TriggerPrg *pT = pParse->pTriggerPrg;
99266     pParse->pTriggerPrg = pT->pNext;
99267     sqlite3DbFree(db, pT);
99268   }
99269 
99270 end_prepare:
99271 
99272   sqlite3ParserReset(pParse);
99273   sqlite3StackFree(db, pParse);
99274   rc = sqlite3ApiExit(db, rc);
99275   assert( (rc&db->errMask)==rc );
99276   return rc;
99277 }
99278 static int sqlite3LockAndPrepare(
99279   sqlite3 *db,              /* Database handle. */
99280   const char *zSql,         /* UTF-8 encoded SQL statement. */
99281   int nBytes,               /* Length of zSql in bytes. */
99282   int saveSqlFlag,          /* True to copy SQL text into the sqlite3_stmt */
99283   Vdbe *pOld,               /* VM being reprepared */
99284   sqlite3_stmt **ppStmt,    /* OUT: A pointer to the prepared statement */
99285   const char **pzTail       /* OUT: End of parsed string */
99286 ){
99287   int rc;
99288   assert( ppStmt!=0 );
99289   *ppStmt = 0;
99290   if( !sqlite3SafetyCheckOk(db) ){
99291     return SQLITE_MISUSE_BKPT;
99292   }
99293   sqlite3_mutex_enter(db->mutex);
99294   sqlite3BtreeEnterAll(db);
99295   rc = sqlite3Prepare(db, zSql, nBytes, saveSqlFlag, pOld, ppStmt, pzTail);
99296   if( rc==SQLITE_SCHEMA ){
99297     sqlite3_finalize(*ppStmt);
99298     rc = sqlite3Prepare(db, zSql, nBytes, saveSqlFlag, pOld, ppStmt, pzTail);
99299   }
99300   sqlite3BtreeLeaveAll(db);
99301   sqlite3_mutex_leave(db->mutex);
99302   assert( rc==SQLITE_OK || *ppStmt==0 );
99303   return rc;
99304 }
99305 
99306 /*
99307 ** Rerun the compilation of a statement after a schema change.
99308 **
99309 ** If the statement is successfully recompiled, return SQLITE_OK. Otherwise,
99310 ** if the statement cannot be recompiled because another connection has
99311 ** locked the sqlite3_master table, return SQLITE_LOCKED. If any other error
99312 ** occurs, return SQLITE_SCHEMA.
99313 */
99314 SQLITE_PRIVATE int sqlite3Reprepare(Vdbe *p){
99315   int rc;
99316   sqlite3_stmt *pNew;
99317   const char *zSql;
99318   sqlite3 *db;
99319 
99320   assert( sqlite3_mutex_held(sqlite3VdbeDb(p)->mutex) );
99321   zSql = sqlite3_sql((sqlite3_stmt *)p);
99322   assert( zSql!=0 );  /* Reprepare only called for prepare_v2() statements */
99323   db = sqlite3VdbeDb(p);
99324   assert( sqlite3_mutex_held(db->mutex) );
99325   rc = sqlite3LockAndPrepare(db, zSql, -1, 0, p, &pNew, 0);
99326   if( rc ){
99327     if( rc==SQLITE_NOMEM ){
99328       db->mallocFailed = 1;
99329     }
99330     assert( pNew==0 );
99331     return rc;
99332   }else{
99333     assert( pNew!=0 );
99334   }
99335   sqlite3VdbeSwap((Vdbe*)pNew, p);
99336   sqlite3TransferBindings(pNew, (sqlite3_stmt*)p);
99337   sqlite3VdbeResetStepResult((Vdbe*)pNew);
99338   sqlite3VdbeFinalize((Vdbe*)pNew);
99339   return SQLITE_OK;
99340 }
99341 
99342 
99343 /*
99344 ** Two versions of the official API.  Legacy and new use.  In the legacy
99345 ** version, the original SQL text is not saved in the prepared statement
99346 ** and so if a schema change occurs, SQLITE_SCHEMA is returned by
99347 ** sqlite3_step().  In the new version, the original SQL text is retained
99348 ** and the statement is automatically recompiled if an schema change
99349 ** occurs.
99350 */
99351 SQLITE_API int sqlite3_prepare(
99352   sqlite3 *db,              /* Database handle. */
99353   const char *zSql,         /* UTF-8 encoded SQL statement. */
99354   int nBytes,               /* Length of zSql in bytes. */
99355   sqlite3_stmt **ppStmt,    /* OUT: A pointer to the prepared statement */
99356   const char **pzTail       /* OUT: End of parsed string */
99357 ){
99358   int rc;
99359   rc = sqlite3LockAndPrepare(db,zSql,nBytes,0,0,ppStmt,pzTail);
99360   assert( rc==SQLITE_OK || ppStmt==0 || *ppStmt==0 );  /* VERIFY: F13021 */
99361   return rc;
99362 }
99363 SQLITE_API int sqlite3_prepare_v2(
99364   sqlite3 *db,              /* Database handle. */
99365   const char *zSql,         /* UTF-8 encoded SQL statement. */
99366   int nBytes,               /* Length of zSql in bytes. */
99367   sqlite3_stmt **ppStmt,    /* OUT: A pointer to the prepared statement */
99368   const char **pzTail       /* OUT: End of parsed string */
99369 ){
99370   int rc;
99371   rc = sqlite3LockAndPrepare(db,zSql,nBytes,1,0,ppStmt,pzTail);
99372   assert( rc==SQLITE_OK || ppStmt==0 || *ppStmt==0 );  /* VERIFY: F13021 */
99373   return rc;
99374 }
99375 
99376 
99377 #ifndef SQLITE_OMIT_UTF16
99378 /*
99379 ** Compile the UTF-16 encoded SQL statement zSql into a statement handle.
99380 */
99381 static int sqlite3Prepare16(
99382   sqlite3 *db,              /* Database handle. */ 
99383   const void *zSql,         /* UTF-16 encoded SQL statement. */
99384   int nBytes,               /* Length of zSql in bytes. */
99385   int saveSqlFlag,          /* True to save SQL text into the sqlite3_stmt */
99386   sqlite3_stmt **ppStmt,    /* OUT: A pointer to the prepared statement */
99387   const void **pzTail       /* OUT: End of parsed string */
99388 ){
99389   /* This function currently works by first transforming the UTF-16
99390   ** encoded string to UTF-8, then invoking sqlite3_prepare(). The
99391   ** tricky bit is figuring out the pointer to return in *pzTail.
99392   */
99393   char *zSql8;
99394   const char *zTail8 = 0;
99395   int rc = SQLITE_OK;
99396 
99397   assert( ppStmt );
99398   *ppStmt = 0;
99399   if( !sqlite3SafetyCheckOk(db) ){
99400     return SQLITE_MISUSE_BKPT;
99401   }
99402   if( nBytes>=0 ){
99403     int sz;
99404     const char *z = (const char*)zSql;
99405     for(sz=0; sz<nBytes && (z[sz]!=0 || z[sz+1]!=0); sz += 2){}
99406     nBytes = sz;
99407   }
99408   sqlite3_mutex_enter(db->mutex);
99409   zSql8 = sqlite3Utf16to8(db, zSql, nBytes, SQLITE_UTF16NATIVE);
99410   if( zSql8 ){
99411     rc = sqlite3LockAndPrepare(db, zSql8, -1, saveSqlFlag, 0, ppStmt, &zTail8);
99412   }
99413 
99414   if( zTail8 && pzTail ){
99415     /* If sqlite3_prepare returns a tail pointer, we calculate the
99416     ** equivalent pointer into the UTF-16 string by counting the unicode
99417     ** characters between zSql8 and zTail8, and then returning a pointer
99418     ** the same number of characters into the UTF-16 string.
99419     */
99420     int chars_parsed = sqlite3Utf8CharLen(zSql8, (int)(zTail8-zSql8));
99421     *pzTail = (u8 *)zSql + sqlite3Utf16ByteLen(zSql, chars_parsed);
99422   }
99423   sqlite3DbFree(db, zSql8); 
99424   rc = sqlite3ApiExit(db, rc);
99425   sqlite3_mutex_leave(db->mutex);
99426   return rc;
99427 }
99428 
99429 /*
99430 ** Two versions of the official API.  Legacy and new use.  In the legacy
99431 ** version, the original SQL text is not saved in the prepared statement
99432 ** and so if a schema change occurs, SQLITE_SCHEMA is returned by
99433 ** sqlite3_step().  In the new version, the original SQL text is retained
99434 ** and the statement is automatically recompiled if an schema change
99435 ** occurs.
99436 */
99437 SQLITE_API int sqlite3_prepare16(
99438   sqlite3 *db,              /* Database handle. */ 
99439   const void *zSql,         /* UTF-16 encoded SQL statement. */
99440   int nBytes,               /* Length of zSql in bytes. */
99441   sqlite3_stmt **ppStmt,    /* OUT: A pointer to the prepared statement */
99442   const void **pzTail       /* OUT: End of parsed string */
99443 ){
99444   int rc;
99445   rc = sqlite3Prepare16(db,zSql,nBytes,0,ppStmt,pzTail);
99446   assert( rc==SQLITE_OK || ppStmt==0 || *ppStmt==0 );  /* VERIFY: F13021 */
99447   return rc;
99448 }
99449 SQLITE_API int sqlite3_prepare16_v2(
99450   sqlite3 *db,              /* Database handle. */ 
99451   const void *zSql,         /* UTF-16 encoded SQL statement. */
99452   int nBytes,               /* Length of zSql in bytes. */
99453   sqlite3_stmt **ppStmt,    /* OUT: A pointer to the prepared statement */
99454   const void **pzTail       /* OUT: End of parsed string */
99455 ){
99456   int rc;
99457   rc = sqlite3Prepare16(db,zSql,nBytes,1,ppStmt,pzTail);
99458   assert( rc==SQLITE_OK || ppStmt==0 || *ppStmt==0 );  /* VERIFY: F13021 */
99459   return rc;
99460 }
99461 
99462 #endif /* SQLITE_OMIT_UTF16 */
99463 
99464 /************** End of prepare.c *********************************************/
99465 /************** Begin file select.c ******************************************/
99466 /*
99467 ** 2001 September 15
99468 **
99469 ** The author disclaims copyright to this source code.  In place of
99470 ** a legal notice, here is a blessing:
99471 **
99472 **    May you do good and not evil.
99473 **    May you find forgiveness for yourself and forgive others.
99474 **    May you share freely, never taking more than you give.
99475 **
99476 *************************************************************************
99477 ** This file contains C code routines that are called by the parser
99478 ** to handle SELECT statements in SQLite.
99479 */
99480 
99481 
99482 /*
99483 ** Delete all the content of a Select structure but do not deallocate
99484 ** the select structure itself.
99485 */
99486 static void clearSelect(sqlite3 *db, Select *p){
99487   sqlite3ExprListDelete(db, p->pEList);
99488   sqlite3SrcListDelete(db, p->pSrc);
99489   sqlite3ExprDelete(db, p->pWhere);
99490   sqlite3ExprListDelete(db, p->pGroupBy);
99491   sqlite3ExprDelete(db, p->pHaving);
99492   sqlite3ExprListDelete(db, p->pOrderBy);
99493   sqlite3SelectDelete(db, p->pPrior);
99494   sqlite3ExprDelete(db, p->pLimit);
99495   sqlite3ExprDelete(db, p->pOffset);
99496 }
99497 
99498 /*
99499 ** Initialize a SelectDest structure.
99500 */
99501 SQLITE_PRIVATE void sqlite3SelectDestInit(SelectDest *pDest, int eDest, int iParm){
99502   pDest->eDest = (u8)eDest;
99503   pDest->iSDParm = iParm;
99504   pDest->affSdst = 0;
99505   pDest->iSdst = 0;
99506   pDest->nSdst = 0;
99507 }
99508 
99509 
99510 /*
99511 ** Allocate a new Select structure and return a pointer to that
99512 ** structure.
99513 */
99514 SQLITE_PRIVATE Select *sqlite3SelectNew(
99515   Parse *pParse,        /* Parsing context */
99516   ExprList *pEList,     /* which columns to include in the result */
99517   SrcList *pSrc,        /* the FROM clause -- which tables to scan */
99518   Expr *pWhere,         /* the WHERE clause */
99519   ExprList *pGroupBy,   /* the GROUP BY clause */
99520   Expr *pHaving,        /* the HAVING clause */
99521   ExprList *pOrderBy,   /* the ORDER BY clause */
99522   u16 selFlags,         /* Flag parameters, such as SF_Distinct */
99523   Expr *pLimit,         /* LIMIT value.  NULL means not used */
99524   Expr *pOffset         /* OFFSET value.  NULL means no offset */
99525 ){
99526   Select *pNew;
99527   Select standin;
99528   sqlite3 *db = pParse->db;
99529   pNew = sqlite3DbMallocZero(db, sizeof(*pNew) );
99530   assert( db->mallocFailed || !pOffset || pLimit ); /* OFFSET implies LIMIT */
99531   if( pNew==0 ){
99532     assert( db->mallocFailed );
99533     pNew = &standin;
99534     memset(pNew, 0, sizeof(*pNew));
99535   }
99536   if( pEList==0 ){
99537     pEList = sqlite3ExprListAppend(pParse, 0, sqlite3Expr(db,TK_ALL,0));
99538   }
99539   pNew->pEList = pEList;
99540   if( pSrc==0 ) pSrc = sqlite3DbMallocZero(db, sizeof(*pSrc));
99541   pNew->pSrc = pSrc;
99542   pNew->pWhere = pWhere;
99543   pNew->pGroupBy = pGroupBy;
99544   pNew->pHaving = pHaving;
99545   pNew->pOrderBy = pOrderBy;
99546   pNew->selFlags = selFlags;
99547   pNew->op = TK_SELECT;
99548   pNew->pLimit = pLimit;
99549   pNew->pOffset = pOffset;
99550   assert( pOffset==0 || pLimit!=0 );
99551   pNew->addrOpenEphm[0] = -1;
99552   pNew->addrOpenEphm[1] = -1;
99553   pNew->addrOpenEphm[2] = -1;
99554   if( db->mallocFailed ) {
99555     clearSelect(db, pNew);
99556     if( pNew!=&standin ) sqlite3DbFree(db, pNew);
99557     pNew = 0;
99558   }else{
99559     assert( pNew->pSrc!=0 || pParse->nErr>0 );
99560   }
99561   assert( pNew!=&standin );
99562   return pNew;
99563 }
99564 
99565 /*
99566 ** Delete the given Select structure and all of its substructures.
99567 */
99568 SQLITE_PRIVATE void sqlite3SelectDelete(sqlite3 *db, Select *p){
99569   if( p ){
99570     clearSelect(db, p);
99571     sqlite3DbFree(db, p);
99572   }
99573 }
99574 
99575 /*
99576 ** Given 1 to 3 identifiers preceding the JOIN keyword, determine the
99577 ** type of join.  Return an integer constant that expresses that type
99578 ** in terms of the following bit values:
99579 **
99580 **     JT_INNER
99581 **     JT_CROSS
99582 **     JT_OUTER
99583 **     JT_NATURAL
99584 **     JT_LEFT
99585 **     JT_RIGHT
99586 **
99587 ** A full outer join is the combination of JT_LEFT and JT_RIGHT.
99588 **
99589 ** If an illegal or unsupported join type is seen, then still return
99590 ** a join type, but put an error in the pParse structure.
99591 */
99592 SQLITE_PRIVATE int sqlite3JoinType(Parse *pParse, Token *pA, Token *pB, Token *pC){
99593   int jointype = 0;
99594   Token *apAll[3];
99595   Token *p;
99596                              /*   0123456789 123456789 123456789 123 */
99597   static const char zKeyText[] = "naturaleftouterightfullinnercross";
99598   static const struct {
99599     u8 i;        /* Beginning of keyword text in zKeyText[] */
99600     u8 nChar;    /* Length of the keyword in characters */
99601     u8 code;     /* Join type mask */
99602   } aKeyword[] = {
99603     /* natural */ { 0,  7, JT_NATURAL                },
99604     /* left    */ { 6,  4, JT_LEFT|JT_OUTER          },
99605     /* outer   */ { 10, 5, JT_OUTER                  },
99606     /* right   */ { 14, 5, JT_RIGHT|JT_OUTER         },
99607     /* full    */ { 19, 4, JT_LEFT|JT_RIGHT|JT_OUTER },
99608     /* inner   */ { 23, 5, JT_INNER                  },
99609     /* cross   */ { 28, 5, JT_INNER|JT_CROSS         },
99610   };
99611   int i, j;
99612   apAll[0] = pA;
99613   apAll[1] = pB;
99614   apAll[2] = pC;
99615   for(i=0; i<3 && apAll[i]; i++){
99616     p = apAll[i];
99617     for(j=0; j<ArraySize(aKeyword); j++){
99618       if( p->n==aKeyword[j].nChar 
99619           && sqlite3StrNICmp((char*)p->z, &zKeyText[aKeyword[j].i], p->n)==0 ){
99620         jointype |= aKeyword[j].code;
99621         break;
99622       }
99623     }
99624     testcase( j==0 || j==1 || j==2 || j==3 || j==4 || j==5 || j==6 );
99625     if( j>=ArraySize(aKeyword) ){
99626       jointype |= JT_ERROR;
99627       break;
99628     }
99629   }
99630   if(
99631      (jointype & (JT_INNER|JT_OUTER))==(JT_INNER|JT_OUTER) ||
99632      (jointype & JT_ERROR)!=0
99633   ){
99634     const char *zSp = " ";
99635     assert( pB!=0 );
99636     if( pC==0 ){ zSp++; }
99637     sqlite3ErrorMsg(pParse, "unknown or unsupported join type: "
99638        "%T %T%s%T", pA, pB, zSp, pC);
99639     jointype = JT_INNER;
99640   }else if( (jointype & JT_OUTER)!=0 
99641          && (jointype & (JT_LEFT|JT_RIGHT))!=JT_LEFT ){
99642     sqlite3ErrorMsg(pParse, 
99643       "RIGHT and FULL OUTER JOINs are not currently supported");
99644     jointype = JT_INNER;
99645   }
99646   return jointype;
99647 }
99648 
99649 /*
99650 ** Return the index of a column in a table.  Return -1 if the column
99651 ** is not contained in the table.
99652 */
99653 static int columnIndex(Table *pTab, const char *zCol){
99654   int i;
99655   for(i=0; i<pTab->nCol; i++){
99656     if( sqlite3StrICmp(pTab->aCol[i].zName, zCol)==0 ) return i;
99657   }
99658   return -1;
99659 }
99660 
99661 /*
99662 ** Search the first N tables in pSrc, from left to right, looking for a
99663 ** table that has a column named zCol.  
99664 **
99665 ** When found, set *piTab and *piCol to the table index and column index
99666 ** of the matching column and return TRUE.
99667 **
99668 ** If not found, return FALSE.
99669 */
99670 static int tableAndColumnIndex(
99671   SrcList *pSrc,       /* Array of tables to search */
99672   int N,               /* Number of tables in pSrc->a[] to search */
99673   const char *zCol,    /* Name of the column we are looking for */
99674   int *piTab,          /* Write index of pSrc->a[] here */
99675   int *piCol           /* Write index of pSrc->a[*piTab].pTab->aCol[] here */
99676 ){
99677   int i;               /* For looping over tables in pSrc */
99678   int iCol;            /* Index of column matching zCol */
99679 
99680   assert( (piTab==0)==(piCol==0) );  /* Both or neither are NULL */
99681   for(i=0; i<N; i++){
99682     iCol = columnIndex(pSrc->a[i].pTab, zCol);
99683     if( iCol>=0 ){
99684       if( piTab ){
99685         *piTab = i;
99686         *piCol = iCol;
99687       }
99688       return 1;
99689     }
99690   }
99691   return 0;
99692 }
99693 
99694 /*
99695 ** This function is used to add terms implied by JOIN syntax to the
99696 ** WHERE clause expression of a SELECT statement. The new term, which
99697 ** is ANDed with the existing WHERE clause, is of the form:
99698 **
99699 **    (tab1.col1 = tab2.col2)
99700 **
99701 ** where tab1 is the iSrc'th table in SrcList pSrc and tab2 is the 
99702 ** (iSrc+1)'th. Column col1 is column iColLeft of tab1, and col2 is
99703 ** column iColRight of tab2.
99704 */
99705 static void addWhereTerm(
99706   Parse *pParse,                  /* Parsing context */
99707   SrcList *pSrc,                  /* List of tables in FROM clause */
99708   int iLeft,                      /* Index of first table to join in pSrc */
99709   int iColLeft,                   /* Index of column in first table */
99710   int iRight,                     /* Index of second table in pSrc */
99711   int iColRight,                  /* Index of column in second table */
99712   int isOuterJoin,                /* True if this is an OUTER join */
99713   Expr **ppWhere                  /* IN/OUT: The WHERE clause to add to */
99714 ){
99715   sqlite3 *db = pParse->db;
99716   Expr *pE1;
99717   Expr *pE2;
99718   Expr *pEq;
99719 
99720   assert( iLeft<iRight );
99721   assert( pSrc->nSrc>iRight );
99722   assert( pSrc->a[iLeft].pTab );
99723   assert( pSrc->a[iRight].pTab );
99724 
99725   pE1 = sqlite3CreateColumnExpr(db, pSrc, iLeft, iColLeft);
99726   pE2 = sqlite3CreateColumnExpr(db, pSrc, iRight, iColRight);
99727 
99728   pEq = sqlite3PExpr(pParse, TK_EQ, pE1, pE2, 0);
99729   if( pEq && isOuterJoin ){
99730     ExprSetProperty(pEq, EP_FromJoin);
99731     assert( !ExprHasProperty(pEq, EP_TokenOnly|EP_Reduced) );
99732     ExprSetVVAProperty(pEq, EP_NoReduce);
99733     pEq->iRightJoinTable = (i16)pE2->iTable;
99734   }
99735   *ppWhere = sqlite3ExprAnd(db, *ppWhere, pEq);
99736 }
99737 
99738 /*
99739 ** Set the EP_FromJoin property on all terms of the given expression.
99740 ** And set the Expr.iRightJoinTable to iTable for every term in the
99741 ** expression.
99742 **
99743 ** The EP_FromJoin property is used on terms of an expression to tell
99744 ** the LEFT OUTER JOIN processing logic that this term is part of the
99745 ** join restriction specified in the ON or USING clause and not a part
99746 ** of the more general WHERE clause.  These terms are moved over to the
99747 ** WHERE clause during join processing but we need to remember that they
99748 ** originated in the ON or USING clause.
99749 **
99750 ** The Expr.iRightJoinTable tells the WHERE clause processing that the
99751 ** expression depends on table iRightJoinTable even if that table is not
99752 ** explicitly mentioned in the expression.  That information is needed
99753 ** for cases like this:
99754 **
99755 **    SELECT * FROM t1 LEFT JOIN t2 ON t1.a=t2.b AND t1.x=5
99756 **
99757 ** The where clause needs to defer the handling of the t1.x=5
99758 ** term until after the t2 loop of the join.  In that way, a
99759 ** NULL t2 row will be inserted whenever t1.x!=5.  If we do not
99760 ** defer the handling of t1.x=5, it will be processed immediately
99761 ** after the t1 loop and rows with t1.x!=5 will never appear in
99762 ** the output, which is incorrect.
99763 */
99764 static void setJoinExpr(Expr *p, int iTable){
99765   while( p ){
99766     ExprSetProperty(p, EP_FromJoin);
99767     assert( !ExprHasProperty(p, EP_TokenOnly|EP_Reduced) );
99768     ExprSetVVAProperty(p, EP_NoReduce);
99769     p->iRightJoinTable = (i16)iTable;
99770     setJoinExpr(p->pLeft, iTable);
99771     p = p->pRight;
99772   } 
99773 }
99774 
99775 /*
99776 ** This routine processes the join information for a SELECT statement.
99777 ** ON and USING clauses are converted into extra terms of the WHERE clause.
99778 ** NATURAL joins also create extra WHERE clause terms.
99779 **
99780 ** The terms of a FROM clause are contained in the Select.pSrc structure.
99781 ** The left most table is the first entry in Select.pSrc.  The right-most
99782 ** table is the last entry.  The join operator is held in the entry to
99783 ** the left.  Thus entry 0 contains the join operator for the join between
99784 ** entries 0 and 1.  Any ON or USING clauses associated with the join are
99785 ** also attached to the left entry.
99786 **
99787 ** This routine returns the number of errors encountered.
99788 */
99789 static int sqliteProcessJoin(Parse *pParse, Select *p){
99790   SrcList *pSrc;                  /* All tables in the FROM clause */
99791   int i, j;                       /* Loop counters */
99792   struct SrcList_item *pLeft;     /* Left table being joined */
99793   struct SrcList_item *pRight;    /* Right table being joined */
99794 
99795   pSrc = p->pSrc;
99796   pLeft = &pSrc->a[0];
99797   pRight = &pLeft[1];
99798   for(i=0; i<pSrc->nSrc-1; i++, pRight++, pLeft++){
99799     Table *pLeftTab = pLeft->pTab;
99800     Table *pRightTab = pRight->pTab;
99801     int isOuter;
99802 
99803     if( NEVER(pLeftTab==0 || pRightTab==0) ) continue;
99804     isOuter = (pRight->jointype & JT_OUTER)!=0;
99805 
99806     /* When the NATURAL keyword is present, add WHERE clause terms for
99807     ** every column that the two tables have in common.
99808     */
99809     if( pRight->jointype & JT_NATURAL ){
99810       if( pRight->pOn || pRight->pUsing ){
99811         sqlite3ErrorMsg(pParse, "a NATURAL join may not have "
99812            "an ON or USING clause", 0);
99813         return 1;
99814       }
99815       for(j=0; j<pRightTab->nCol; j++){
99816         char *zName;   /* Name of column in the right table */
99817         int iLeft;     /* Matching left table */
99818         int iLeftCol;  /* Matching column in the left table */
99819 
99820         zName = pRightTab->aCol[j].zName;
99821         if( tableAndColumnIndex(pSrc, i+1, zName, &iLeft, &iLeftCol) ){
99822           addWhereTerm(pParse, pSrc, iLeft, iLeftCol, i+1, j,
99823                        isOuter, &p->pWhere);
99824         }
99825       }
99826     }
99827 
99828     /* Disallow both ON and USING clauses in the same join
99829     */
99830     if( pRight->pOn && pRight->pUsing ){
99831       sqlite3ErrorMsg(pParse, "cannot have both ON and USING "
99832         "clauses in the same join");
99833       return 1;
99834     }
99835 
99836     /* Add the ON clause to the end of the WHERE clause, connected by
99837     ** an AND operator.
99838     */
99839     if( pRight->pOn ){
99840       if( isOuter ) setJoinExpr(pRight->pOn, pRight->iCursor);
99841       p->pWhere = sqlite3ExprAnd(pParse->db, p->pWhere, pRight->pOn);
99842       pRight->pOn = 0;
99843     }
99844 
99845     /* Create extra terms on the WHERE clause for each column named
99846     ** in the USING clause.  Example: If the two tables to be joined are 
99847     ** A and B and the USING clause names X, Y, and Z, then add this
99848     ** to the WHERE clause:    A.X=B.X AND A.Y=B.Y AND A.Z=B.Z
99849     ** Report an error if any column mentioned in the USING clause is
99850     ** not contained in both tables to be joined.
99851     */
99852     if( pRight->pUsing ){
99853       IdList *pList = pRight->pUsing;
99854       for(j=0; j<pList->nId; j++){
99855         char *zName;     /* Name of the term in the USING clause */
99856         int iLeft;       /* Table on the left with matching column name */
99857         int iLeftCol;    /* Column number of matching column on the left */
99858         int iRightCol;   /* Column number of matching column on the right */
99859 
99860         zName = pList->a[j].zName;
99861         iRightCol = columnIndex(pRightTab, zName);
99862         if( iRightCol<0
99863          || !tableAndColumnIndex(pSrc, i+1, zName, &iLeft, &iLeftCol)
99864         ){
99865           sqlite3ErrorMsg(pParse, "cannot join using column %s - column "
99866             "not present in both tables", zName);
99867           return 1;
99868         }
99869         addWhereTerm(pParse, pSrc, iLeft, iLeftCol, i+1, iRightCol,
99870                      isOuter, &p->pWhere);
99871       }
99872     }
99873   }
99874   return 0;
99875 }
99876 
99877 /*
99878 ** Insert code into "v" that will push the record on the top of the
99879 ** stack into the sorter.
99880 */
99881 static void pushOntoSorter(
99882   Parse *pParse,         /* Parser context */
99883   ExprList *pOrderBy,    /* The ORDER BY clause */
99884   Select *pSelect,       /* The whole SELECT statement */
99885   int regData            /* Register holding data to be sorted */
99886 ){
99887   Vdbe *v = pParse->pVdbe;
99888   int nExpr = pOrderBy->nExpr;
99889   int regBase = sqlite3GetTempRange(pParse, nExpr+2);
99890   int regRecord = sqlite3GetTempReg(pParse);
99891   int op;
99892   sqlite3ExprCacheClear(pParse);
99893   sqlite3ExprCodeExprList(pParse, pOrderBy, regBase, 0);
99894   sqlite3VdbeAddOp2(v, OP_Sequence, pOrderBy->iECursor, regBase+nExpr);
99895   sqlite3ExprCodeMove(pParse, regData, regBase+nExpr+1, 1);
99896   sqlite3VdbeAddOp3(v, OP_MakeRecord, regBase, nExpr + 2, regRecord);
99897   if( pSelect->selFlags & SF_UseSorter ){
99898     op = OP_SorterInsert;
99899   }else{
99900     op = OP_IdxInsert;
99901   }
99902   sqlite3VdbeAddOp2(v, op, pOrderBy->iECursor, regRecord);
99903   sqlite3ReleaseTempReg(pParse, regRecord);
99904   sqlite3ReleaseTempRange(pParse, regBase, nExpr+2);
99905   if( pSelect->iLimit ){
99906     int addr1, addr2;
99907     int iLimit;
99908     if( pSelect->iOffset ){
99909       iLimit = pSelect->iOffset+1;
99910     }else{
99911       iLimit = pSelect->iLimit;
99912     }
99913     addr1 = sqlite3VdbeAddOp1(v, OP_IfZero, iLimit);
99914     sqlite3VdbeAddOp2(v, OP_AddImm, iLimit, -1);
99915     addr2 = sqlite3VdbeAddOp0(v, OP_Goto);
99916     sqlite3VdbeJumpHere(v, addr1);
99917     sqlite3VdbeAddOp1(v, OP_Last, pOrderBy->iECursor);
99918     sqlite3VdbeAddOp1(v, OP_Delete, pOrderBy->iECursor);
99919     sqlite3VdbeJumpHere(v, addr2);
99920   }
99921 }
99922 
99923 /*
99924 ** Add code to implement the OFFSET
99925 */
99926 static void codeOffset(
99927   Vdbe *v,          /* Generate code into this VM */
99928   Select *p,        /* The SELECT statement being coded */
99929   int iContinue     /* Jump here to skip the current record */
99930 ){
99931   if( p->iOffset && iContinue!=0 ){
99932     int addr;
99933     sqlite3VdbeAddOp2(v, OP_AddImm, p->iOffset, -1);
99934     addr = sqlite3VdbeAddOp1(v, OP_IfNeg, p->iOffset);
99935     sqlite3VdbeAddOp2(v, OP_Goto, 0, iContinue);
99936     VdbeComment((v, "skip OFFSET records"));
99937     sqlite3VdbeJumpHere(v, addr);
99938   }
99939 }
99940 
99941 /*
99942 ** Add code that will check to make sure the N registers starting at iMem
99943 ** form a distinct entry.  iTab is a sorting index that holds previously
99944 ** seen combinations of the N values.  A new entry is made in iTab
99945 ** if the current N values are new.
99946 **
99947 ** A jump to addrRepeat is made and the N+1 values are popped from the
99948 ** stack if the top N elements are not distinct.
99949 */
99950 static void codeDistinct(
99951   Parse *pParse,     /* Parsing and code generating context */
99952   int iTab,          /* A sorting index used to test for distinctness */
99953   int addrRepeat,    /* Jump to here if not distinct */
99954   int N,             /* Number of elements */
99955   int iMem           /* First element */
99956 ){
99957   Vdbe *v;
99958   int r1;
99959 
99960   v = pParse->pVdbe;
99961   r1 = sqlite3GetTempReg(pParse);
99962   sqlite3VdbeAddOp4Int(v, OP_Found, iTab, addrRepeat, iMem, N);
99963   sqlite3VdbeAddOp3(v, OP_MakeRecord, iMem, N, r1);
99964   sqlite3VdbeAddOp2(v, OP_IdxInsert, iTab, r1);
99965   sqlite3ReleaseTempReg(pParse, r1);
99966 }
99967 
99968 #ifndef SQLITE_OMIT_SUBQUERY
99969 /*
99970 ** Generate an error message when a SELECT is used within a subexpression
99971 ** (example:  "a IN (SELECT * FROM table)") but it has more than 1 result
99972 ** column.  We do this in a subroutine because the error used to occur
99973 ** in multiple places.  (The error only occurs in one place now, but we
99974 ** retain the subroutine to minimize code disruption.)
99975 */
99976 static int checkForMultiColumnSelectError(
99977   Parse *pParse,       /* Parse context. */
99978   SelectDest *pDest,   /* Destination of SELECT results */
99979   int nExpr            /* Number of result columns returned by SELECT */
99980 ){
99981   int eDest = pDest->eDest;
99982   if( nExpr>1 && (eDest==SRT_Mem || eDest==SRT_Set) ){
99983     sqlite3ErrorMsg(pParse, "only a single result allowed for "
99984        "a SELECT that is part of an expression");
99985     return 1;
99986   }else{
99987     return 0;
99988   }
99989 }
99990 #endif
99991 
99992 /*
99993 ** An instance of the following object is used to record information about
99994 ** how to process the DISTINCT keyword, to simplify passing that information
99995 ** into the selectInnerLoop() routine.
99996 */
99997 typedef struct DistinctCtx DistinctCtx;
99998 struct DistinctCtx {
99999   u8 isTnct;      /* True if the DISTINCT keyword is present */
100000   u8 eTnctType;   /* One of the WHERE_DISTINCT_* operators */
100001   int tabTnct;    /* Ephemeral table used for DISTINCT processing */
100002   int addrTnct;   /* Address of OP_OpenEphemeral opcode for tabTnct */
100003 };
100004 
100005 /*
100006 ** This routine generates the code for the inside of the inner loop
100007 ** of a SELECT.
100008 **
100009 ** If srcTab and nColumn are both zero, then the pEList expressions
100010 ** are evaluated in order to get the data for this row.  If nColumn>0
100011 ** then data is pulled from srcTab and pEList is used only to get the
100012 ** datatypes for each column.
100013 */
100014 static void selectInnerLoop(
100015   Parse *pParse,          /* The parser context */
100016   Select *p,              /* The complete select statement being coded */
100017   ExprList *pEList,       /* List of values being extracted */
100018   int srcTab,             /* Pull data from this table */
100019   int nColumn,            /* Number of columns in the source table */
100020   ExprList *pOrderBy,     /* If not NULL, sort results using this key */
100021   DistinctCtx *pDistinct, /* If not NULL, info on how to process DISTINCT */
100022   SelectDest *pDest,      /* How to dispose of the results */
100023   int iContinue,          /* Jump here to continue with next row */
100024   int iBreak              /* Jump here to break out of the inner loop */
100025 ){
100026   Vdbe *v = pParse->pVdbe;
100027   int i;
100028   int hasDistinct;        /* True if the DISTINCT keyword is present */
100029   int regResult;              /* Start of memory holding result set */
100030   int eDest = pDest->eDest;   /* How to dispose of results */
100031   int iParm = pDest->iSDParm; /* First argument to disposal method */
100032   int nResultCol;             /* Number of result columns */
100033 
100034   assert( v );
100035   if( NEVER(v==0) ) return;
100036   assert( pEList!=0 );
100037   hasDistinct = pDistinct ? pDistinct->eTnctType : WHERE_DISTINCT_NOOP;
100038   if( pOrderBy==0 && !hasDistinct ){
100039     codeOffset(v, p, iContinue);
100040   }
100041 
100042   /* Pull the requested columns.
100043   */
100044   if( nColumn>0 ){
100045     nResultCol = nColumn;
100046   }else{
100047     nResultCol = pEList->nExpr;
100048   }
100049   if( pDest->iSdst==0 ){
100050     pDest->iSdst = pParse->nMem+1;
100051     pDest->nSdst = nResultCol;
100052     pParse->nMem += nResultCol;
100053   }else{ 
100054     assert( pDest->nSdst==nResultCol );
100055   }
100056   regResult = pDest->iSdst;
100057   if( nColumn>0 ){
100058     for(i=0; i<nColumn; i++){
100059       sqlite3VdbeAddOp3(v, OP_Column, srcTab, i, regResult+i);
100060     }
100061   }else if( eDest!=SRT_Exists ){
100062     /* If the destination is an EXISTS(...) expression, the actual
100063     ** values returned by the SELECT are not required.
100064     */
100065     sqlite3ExprCacheClear(pParse);
100066     sqlite3ExprCodeExprList(pParse, pEList, regResult,
100067                             (eDest==SRT_Output)?SQLITE_ECEL_DUP:0);
100068   }
100069   nColumn = nResultCol;
100070 
100071   /* If the DISTINCT keyword was present on the SELECT statement
100072   ** and this row has been seen before, then do not make this row
100073   ** part of the result.
100074   */
100075   if( hasDistinct ){
100076     assert( pEList!=0 );
100077     assert( pEList->nExpr==nColumn );
100078     switch( pDistinct->eTnctType ){
100079       case WHERE_DISTINCT_ORDERED: {
100080         VdbeOp *pOp;            /* No longer required OpenEphemeral instr. */
100081         int iJump;              /* Jump destination */
100082         int regPrev;            /* Previous row content */
100083 
100084         /* Allocate space for the previous row */
100085         regPrev = pParse->nMem+1;
100086         pParse->nMem += nColumn;
100087 
100088         /* Change the OP_OpenEphemeral coded earlier to an OP_Null
100089         ** sets the MEM_Cleared bit on the first register of the
100090         ** previous value.  This will cause the OP_Ne below to always
100091         ** fail on the first iteration of the loop even if the first
100092         ** row is all NULLs.
100093         */
100094         sqlite3VdbeChangeToNoop(v, pDistinct->addrTnct);
100095         pOp = sqlite3VdbeGetOp(v, pDistinct->addrTnct);
100096         pOp->opcode = OP_Null;
100097         pOp->p1 = 1;
100098         pOp->p2 = regPrev;
100099 
100100         iJump = sqlite3VdbeCurrentAddr(v) + nColumn;
100101         for(i=0; i<nColumn; i++){
100102           CollSeq *pColl = sqlite3ExprCollSeq(pParse, pEList->a[i].pExpr);
100103           if( i<nColumn-1 ){
100104             sqlite3VdbeAddOp3(v, OP_Ne, regResult+i, iJump, regPrev+i);
100105           }else{
100106             sqlite3VdbeAddOp3(v, OP_Eq, regResult+i, iContinue, regPrev+i);
100107           }
100108           sqlite3VdbeChangeP4(v, -1, (const char *)pColl, P4_COLLSEQ);
100109           sqlite3VdbeChangeP5(v, SQLITE_NULLEQ);
100110         }
100111         assert( sqlite3VdbeCurrentAddr(v)==iJump );
100112         sqlite3VdbeAddOp3(v, OP_Copy, regResult, regPrev, nColumn-1);
100113         break;
100114       }
100115 
100116       case WHERE_DISTINCT_UNIQUE: {
100117         sqlite3VdbeChangeToNoop(v, pDistinct->addrTnct);
100118         break;
100119       }
100120 
100121       default: {
100122         assert( pDistinct->eTnctType==WHERE_DISTINCT_UNORDERED );
100123         codeDistinct(pParse, pDistinct->tabTnct, iContinue, nColumn, regResult);
100124         break;
100125       }
100126     }
100127     if( pOrderBy==0 ){
100128       codeOffset(v, p, iContinue);
100129     }
100130   }
100131 
100132   switch( eDest ){
100133     /* In this mode, write each query result to the key of the temporary
100134     ** table iParm.
100135     */
100136 #ifndef SQLITE_OMIT_COMPOUND_SELECT
100137     case SRT_Union: {
100138       int r1;
100139       r1 = sqlite3GetTempReg(pParse);
100140       sqlite3VdbeAddOp3(v, OP_MakeRecord, regResult, nColumn, r1);
100141       sqlite3VdbeAddOp2(v, OP_IdxInsert, iParm, r1);
100142       sqlite3ReleaseTempReg(pParse, r1);
100143       break;
100144     }
100145 
100146     /* Construct a record from the query result, but instead of
100147     ** saving that record, use it as a key to delete elements from
100148     ** the temporary table iParm.
100149     */
100150     case SRT_Except: {
100151       sqlite3VdbeAddOp3(v, OP_IdxDelete, iParm, regResult, nColumn);
100152       break;
100153     }
100154 #endif
100155 
100156     /* Store the result as data using a unique key.
100157     */
100158     case SRT_Table:
100159     case SRT_EphemTab: {
100160       int r1 = sqlite3GetTempReg(pParse);
100161       testcase( eDest==SRT_Table );
100162       testcase( eDest==SRT_EphemTab );
100163       sqlite3VdbeAddOp3(v, OP_MakeRecord, regResult, nColumn, r1);
100164       if( pOrderBy ){
100165         pushOntoSorter(pParse, pOrderBy, p, r1);
100166       }else{
100167         int r2 = sqlite3GetTempReg(pParse);
100168         sqlite3VdbeAddOp2(v, OP_NewRowid, iParm, r2);
100169         sqlite3VdbeAddOp3(v, OP_Insert, iParm, r1, r2);
100170         sqlite3VdbeChangeP5(v, OPFLAG_APPEND);
100171         sqlite3ReleaseTempReg(pParse, r2);
100172       }
100173       sqlite3ReleaseTempReg(pParse, r1);
100174       break;
100175     }
100176 
100177 #ifndef SQLITE_OMIT_SUBQUERY
100178     /* If we are creating a set for an "expr IN (SELECT ...)" construct,
100179     ** then there should be a single item on the stack.  Write this
100180     ** item into the set table with bogus data.
100181     */
100182     case SRT_Set: {
100183       assert( nColumn==1 );
100184       pDest->affSdst =
100185                   sqlite3CompareAffinity(pEList->a[0].pExpr, pDest->affSdst);
100186       if( pOrderBy ){
100187         /* At first glance you would think we could optimize out the
100188         ** ORDER BY in this case since the order of entries in the set
100189         ** does not matter.  But there might be a LIMIT clause, in which
100190         ** case the order does matter */
100191         pushOntoSorter(pParse, pOrderBy, p, regResult);
100192       }else{
100193         int r1 = sqlite3GetTempReg(pParse);
100194         sqlite3VdbeAddOp4(v, OP_MakeRecord, regResult,1,r1, &pDest->affSdst, 1);
100195         sqlite3ExprCacheAffinityChange(pParse, regResult, 1);
100196         sqlite3VdbeAddOp2(v, OP_IdxInsert, iParm, r1);
100197         sqlite3ReleaseTempReg(pParse, r1);
100198       }
100199       break;
100200     }
100201 
100202     /* If any row exist in the result set, record that fact and abort.
100203     */
100204     case SRT_Exists: {
100205       sqlite3VdbeAddOp2(v, OP_Integer, 1, iParm);
100206       /* The LIMIT clause will terminate the loop for us */
100207       break;
100208     }
100209 
100210     /* If this is a scalar select that is part of an expression, then
100211     ** store the results in the appropriate memory cell and break out
100212     ** of the scan loop.
100213     */
100214     case SRT_Mem: {
100215       assert( nColumn==1 );
100216       if( pOrderBy ){
100217         pushOntoSorter(pParse, pOrderBy, p, regResult);
100218       }else{
100219         sqlite3ExprCodeMove(pParse, regResult, iParm, 1);
100220         /* The LIMIT clause will jump out of the loop for us */
100221       }
100222       break;
100223     }
100224 #endif /* #ifndef SQLITE_OMIT_SUBQUERY */
100225 
100226     /* Send the data to the callback function or to a subroutine.  In the
100227     ** case of a subroutine, the subroutine itself is responsible for
100228     ** popping the data from the stack.
100229     */
100230     case SRT_Coroutine:
100231     case SRT_Output: {
100232       testcase( eDest==SRT_Coroutine );
100233       testcase( eDest==SRT_Output );
100234       if( pOrderBy ){
100235         int r1 = sqlite3GetTempReg(pParse);
100236         sqlite3VdbeAddOp3(v, OP_MakeRecord, regResult, nColumn, r1);
100237         pushOntoSorter(pParse, pOrderBy, p, r1);
100238         sqlite3ReleaseTempReg(pParse, r1);
100239       }else if( eDest==SRT_Coroutine ){
100240         sqlite3VdbeAddOp1(v, OP_Yield, pDest->iSDParm);
100241       }else{
100242         sqlite3VdbeAddOp2(v, OP_ResultRow, regResult, nColumn);
100243         sqlite3ExprCacheAffinityChange(pParse, regResult, nColumn);
100244       }
100245       break;
100246     }
100247 
100248 #if !defined(SQLITE_OMIT_TRIGGER)
100249     /* Discard the results.  This is used for SELECT statements inside
100250     ** the body of a TRIGGER.  The purpose of such selects is to call
100251     ** user-defined functions that have side effects.  We do not care
100252     ** about the actual results of the select.
100253     */
100254     default: {
100255       assert( eDest==SRT_Discard );
100256       break;
100257     }
100258 #endif
100259   }
100260 
100261   /* Jump to the end of the loop if the LIMIT is reached.  Except, if
100262   ** there is a sorter, in which case the sorter has already limited
100263   ** the output for us.
100264   */
100265   if( pOrderBy==0 && p->iLimit ){
100266     sqlite3VdbeAddOp3(v, OP_IfZero, p->iLimit, iBreak, -1);
100267   }
100268 }
100269 
100270 /*
100271 ** Allocate a KeyInfo object sufficient for an index of N key columns and
100272 ** X extra columns.
100273 */
100274 SQLITE_PRIVATE KeyInfo *sqlite3KeyInfoAlloc(sqlite3 *db, int N, int X){
100275   KeyInfo *p = sqlite3DbMallocZero(0, 
100276                    sizeof(KeyInfo) + (N+X)*(sizeof(CollSeq*)+1));
100277   if( p ){
100278     p->aSortOrder = (u8*)&p->aColl[N+X];
100279     p->nField = (u16)N;
100280     p->nXField = (u16)X;
100281     p->enc = ENC(db);
100282     p->db = db;
100283     p->nRef = 1;
100284   }else{
100285     db->mallocFailed = 1;
100286   }
100287   return p;
100288 }
100289 
100290 /*
100291 ** Deallocate a KeyInfo object
100292 */
100293 SQLITE_PRIVATE void sqlite3KeyInfoUnref(KeyInfo *p){
100294   if( p ){
100295     assert( p->nRef>0 );
100296     p->nRef--;
100297     if( p->nRef==0 ) sqlite3DbFree(0, p);
100298   }
100299 }
100300 
100301 /*
100302 ** Make a new pointer to a KeyInfo object
100303 */
100304 SQLITE_PRIVATE KeyInfo *sqlite3KeyInfoRef(KeyInfo *p){
100305   if( p ){
100306     assert( p->nRef>0 );
100307     p->nRef++;
100308   }
100309   return p;
100310 }
100311 
100312 #ifdef SQLITE_DEBUG
100313 /*
100314 ** Return TRUE if a KeyInfo object can be change.  The KeyInfo object
100315 ** can only be changed if this is just a single reference to the object.
100316 **
100317 ** This routine is used only inside of assert() statements.
100318 */
100319 SQLITE_PRIVATE int sqlite3KeyInfoIsWriteable(KeyInfo *p){ return p->nRef==1; }
100320 #endif /* SQLITE_DEBUG */
100321 
100322 /*
100323 ** Given an expression list, generate a KeyInfo structure that records
100324 ** the collating sequence for each expression in that expression list.
100325 **
100326 ** If the ExprList is an ORDER BY or GROUP BY clause then the resulting
100327 ** KeyInfo structure is appropriate for initializing a virtual index to
100328 ** implement that clause.  If the ExprList is the result set of a SELECT
100329 ** then the KeyInfo structure is appropriate for initializing a virtual
100330 ** index to implement a DISTINCT test.
100331 **
100332 ** Space to hold the KeyInfo structure is obtain from malloc.  The calling
100333 ** function is responsible for seeing that this structure is eventually
100334 ** freed.
100335 */
100336 static KeyInfo *keyInfoFromExprList(Parse *pParse, ExprList *pList){
100337   int nExpr;
100338   KeyInfo *pInfo;
100339   struct ExprList_item *pItem;
100340   sqlite3 *db = pParse->db;
100341   int i;
100342 
100343   nExpr = pList->nExpr;
100344   pInfo = sqlite3KeyInfoAlloc(db, nExpr, 1);
100345   if( pInfo ){
100346     assert( sqlite3KeyInfoIsWriteable(pInfo) );
100347     for(i=0, pItem=pList->a; i<nExpr; i++, pItem++){
100348       CollSeq *pColl;
100349       pColl = sqlite3ExprCollSeq(pParse, pItem->pExpr);
100350       if( !pColl ) pColl = db->pDfltColl;
100351       pInfo->aColl[i] = pColl;
100352       pInfo->aSortOrder[i] = pItem->sortOrder;
100353     }
100354   }
100355   return pInfo;
100356 }
100357 
100358 #ifndef SQLITE_OMIT_COMPOUND_SELECT
100359 /*
100360 ** Name of the connection operator, used for error messages.
100361 */
100362 static const char *selectOpName(int id){
100363   char *z;
100364   switch( id ){
100365     case TK_ALL:       z = "UNION ALL";   break;
100366     case TK_INTERSECT: z = "INTERSECT";   break;
100367     case TK_EXCEPT:    z = "EXCEPT";      break;
100368     default:           z = "UNION";       break;
100369   }
100370   return z;
100371 }
100372 #endif /* SQLITE_OMIT_COMPOUND_SELECT */
100373 
100374 #ifndef SQLITE_OMIT_EXPLAIN
100375 /*
100376 ** Unless an "EXPLAIN QUERY PLAN" command is being processed, this function
100377 ** is a no-op. Otherwise, it adds a single row of output to the EQP result,
100378 ** where the caption is of the form:
100379 **
100380 **   "USE TEMP B-TREE FOR xxx"
100381 **
100382 ** where xxx is one of "DISTINCT", "ORDER BY" or "GROUP BY". Exactly which
100383 ** is determined by the zUsage argument.
100384 */
100385 static void explainTempTable(Parse *pParse, const char *zUsage){
100386   if( pParse->explain==2 ){
100387     Vdbe *v = pParse->pVdbe;
100388     char *zMsg = sqlite3MPrintf(pParse->db, "USE TEMP B-TREE FOR %s", zUsage);
100389     sqlite3VdbeAddOp4(v, OP_Explain, pParse->iSelectId, 0, 0, zMsg, P4_DYNAMIC);
100390   }
100391 }
100392 
100393 /*
100394 ** Assign expression b to lvalue a. A second, no-op, version of this macro
100395 ** is provided when SQLITE_OMIT_EXPLAIN is defined. This allows the code
100396 ** in sqlite3Select() to assign values to structure member variables that
100397 ** only exist if SQLITE_OMIT_EXPLAIN is not defined without polluting the
100398 ** code with #ifndef directives.
100399 */
100400 # define explainSetInteger(a, b) a = b
100401 
100402 #else
100403 /* No-op versions of the explainXXX() functions and macros. */
100404 # define explainTempTable(y,z)
100405 # define explainSetInteger(y,z)
100406 #endif
100407 
100408 #if !defined(SQLITE_OMIT_EXPLAIN) && !defined(SQLITE_OMIT_COMPOUND_SELECT)
100409 /*
100410 ** Unless an "EXPLAIN QUERY PLAN" command is being processed, this function
100411 ** is a no-op. Otherwise, it adds a single row of output to the EQP result,
100412 ** where the caption is of one of the two forms:
100413 **
100414 **   "COMPOSITE SUBQUERIES iSub1 and iSub2 (op)"
100415 **   "COMPOSITE SUBQUERIES iSub1 and iSub2 USING TEMP B-TREE (op)"
100416 **
100417 ** where iSub1 and iSub2 are the integers passed as the corresponding
100418 ** function parameters, and op is the text representation of the parameter
100419 ** of the same name. The parameter "op" must be one of TK_UNION, TK_EXCEPT,
100420 ** TK_INTERSECT or TK_ALL. The first form is used if argument bUseTmp is 
100421 ** false, or the second form if it is true.
100422 */
100423 static void explainComposite(
100424   Parse *pParse,                  /* Parse context */
100425   int op,                         /* One of TK_UNION, TK_EXCEPT etc. */
100426   int iSub1,                      /* Subquery id 1 */
100427   int iSub2,                      /* Subquery id 2 */
100428   int bUseTmp                     /* True if a temp table was used */
100429 ){
100430   assert( op==TK_UNION || op==TK_EXCEPT || op==TK_INTERSECT || op==TK_ALL );
100431   if( pParse->explain==2 ){
100432     Vdbe *v = pParse->pVdbe;
100433     char *zMsg = sqlite3MPrintf(
100434         pParse->db, "COMPOUND SUBQUERIES %d AND %d %s(%s)", iSub1, iSub2,
100435         bUseTmp?"USING TEMP B-TREE ":"", selectOpName(op)
100436     );
100437     sqlite3VdbeAddOp4(v, OP_Explain, pParse->iSelectId, 0, 0, zMsg, P4_DYNAMIC);
100438   }
100439 }
100440 #else
100441 /* No-op versions of the explainXXX() functions and macros. */
100442 # define explainComposite(v,w,x,y,z)
100443 #endif
100444 
100445 /*
100446 ** If the inner loop was generated using a non-null pOrderBy argument,
100447 ** then the results were placed in a sorter.  After the loop is terminated
100448 ** we need to run the sorter and output the results.  The following
100449 ** routine generates the code needed to do that.
100450 */
100451 static void generateSortTail(
100452   Parse *pParse,    /* Parsing context */
100453   Select *p,        /* The SELECT statement */
100454   Vdbe *v,          /* Generate code into this VDBE */
100455   int nColumn,      /* Number of columns of data */
100456   SelectDest *pDest /* Write the sorted results here */
100457 ){
100458   int addrBreak = sqlite3VdbeMakeLabel(v);     /* Jump here to exit loop */
100459   int addrContinue = sqlite3VdbeMakeLabel(v);  /* Jump here for next cycle */
100460   int addr;
100461   int iTab;
100462   int pseudoTab = 0;
100463   ExprList *pOrderBy = p->pOrderBy;
100464 
100465   int eDest = pDest->eDest;
100466   int iParm = pDest->iSDParm;
100467 
100468   int regRow;
100469   int regRowid;
100470 
100471   iTab = pOrderBy->iECursor;
100472   regRow = sqlite3GetTempReg(pParse);
100473   if( eDest==SRT_Output || eDest==SRT_Coroutine ){
100474     pseudoTab = pParse->nTab++;
100475     sqlite3VdbeAddOp3(v, OP_OpenPseudo, pseudoTab, regRow, nColumn);
100476     regRowid = 0;
100477   }else{
100478     regRowid = sqlite3GetTempReg(pParse);
100479   }
100480   if( p->selFlags & SF_UseSorter ){
100481     int regSortOut = ++pParse->nMem;
100482     int ptab2 = pParse->nTab++;
100483     sqlite3VdbeAddOp3(v, OP_OpenPseudo, ptab2, regSortOut, pOrderBy->nExpr+2);
100484     addr = 1 + sqlite3VdbeAddOp2(v, OP_SorterSort, iTab, addrBreak);
100485     codeOffset(v, p, addrContinue);
100486     sqlite3VdbeAddOp2(v, OP_SorterData, iTab, regSortOut);
100487     sqlite3VdbeAddOp3(v, OP_Column, ptab2, pOrderBy->nExpr+1, regRow);
100488     sqlite3VdbeChangeP5(v, OPFLAG_CLEARCACHE);
100489   }else{
100490     addr = 1 + sqlite3VdbeAddOp2(v, OP_Sort, iTab, addrBreak);
100491     codeOffset(v, p, addrContinue);
100492     sqlite3VdbeAddOp3(v, OP_Column, iTab, pOrderBy->nExpr+1, regRow);
100493   }
100494   switch( eDest ){
100495     case SRT_Table:
100496     case SRT_EphemTab: {
100497       testcase( eDest==SRT_Table );
100498       testcase( eDest==SRT_EphemTab );
100499       sqlite3VdbeAddOp2(v, OP_NewRowid, iParm, regRowid);
100500       sqlite3VdbeAddOp3(v, OP_Insert, iParm, regRow, regRowid);
100501       sqlite3VdbeChangeP5(v, OPFLAG_APPEND);
100502       break;
100503     }
100504 #ifndef SQLITE_OMIT_SUBQUERY
100505     case SRT_Set: {
100506       assert( nColumn==1 );
100507       sqlite3VdbeAddOp4(v, OP_MakeRecord, regRow, 1, regRowid,
100508                         &pDest->affSdst, 1);
100509       sqlite3ExprCacheAffinityChange(pParse, regRow, 1);
100510       sqlite3VdbeAddOp2(v, OP_IdxInsert, iParm, regRowid);
100511       break;
100512     }
100513     case SRT_Mem: {
100514       assert( nColumn==1 );
100515       sqlite3ExprCodeMove(pParse, regRow, iParm, 1);
100516       /* The LIMIT clause will terminate the loop for us */
100517       break;
100518     }
100519 #endif
100520     default: {
100521       int i;
100522       assert( eDest==SRT_Output || eDest==SRT_Coroutine ); 
100523       testcase( eDest==SRT_Output );
100524       testcase( eDest==SRT_Coroutine );
100525       for(i=0; i<nColumn; i++){
100526         assert( regRow!=pDest->iSdst+i );
100527         sqlite3VdbeAddOp3(v, OP_Column, pseudoTab, i, pDest->iSdst+i);
100528         if( i==0 ){
100529           sqlite3VdbeChangeP5(v, OPFLAG_CLEARCACHE);
100530         }
100531       }
100532       if( eDest==SRT_Output ){
100533         sqlite3VdbeAddOp2(v, OP_ResultRow, pDest->iSdst, nColumn);
100534         sqlite3ExprCacheAffinityChange(pParse, pDest->iSdst, nColumn);
100535       }else{
100536         sqlite3VdbeAddOp1(v, OP_Yield, pDest->iSDParm);
100537       }
100538       break;
100539     }
100540   }
100541   sqlite3ReleaseTempReg(pParse, regRow);
100542   sqlite3ReleaseTempReg(pParse, regRowid);
100543 
100544   /* The bottom of the loop
100545   */
100546   sqlite3VdbeResolveLabel(v, addrContinue);
100547   if( p->selFlags & SF_UseSorter ){
100548     sqlite3VdbeAddOp2(v, OP_SorterNext, iTab, addr);
100549   }else{
100550     sqlite3VdbeAddOp2(v, OP_Next, iTab, addr);
100551   }
100552   sqlite3VdbeResolveLabel(v, addrBreak);
100553   if( eDest==SRT_Output || eDest==SRT_Coroutine ){
100554     sqlite3VdbeAddOp2(v, OP_Close, pseudoTab, 0);
100555   }
100556 }
100557 
100558 /*
100559 ** Return a pointer to a string containing the 'declaration type' of the
100560 ** expression pExpr. The string may be treated as static by the caller.
100561 **
100562 ** Also try to estimate the size of the returned value and return that
100563 ** result in *pEstWidth.
100564 **
100565 ** The declaration type is the exact datatype definition extracted from the
100566 ** original CREATE TABLE statement if the expression is a column. The
100567 ** declaration type for a ROWID field is INTEGER. Exactly when an expression
100568 ** is considered a column can be complex in the presence of subqueries. The
100569 ** result-set expression in all of the following SELECT statements is 
100570 ** considered a column by this function.
100571 **
100572 **   SELECT col FROM tbl;
100573 **   SELECT (SELECT col FROM tbl;
100574 **   SELECT (SELECT col FROM tbl);
100575 **   SELECT abc FROM (SELECT col AS abc FROM tbl);
100576 ** 
100577 ** The declaration type for any expression other than a column is NULL.
100578 **
100579 ** This routine has either 3 or 6 parameters depending on whether or not
100580 ** the SQLITE_ENABLE_COLUMN_METADATA compile-time option is used.
100581 */
100582 #ifdef SQLITE_ENABLE_COLUMN_METADATA
100583 # define columnType(A,B,C,D,E,F) columnTypeImpl(A,B,C,D,E,F)
100584 static const char *columnTypeImpl(
100585   NameContext *pNC, 
100586   Expr *pExpr,
100587   const char **pzOrigDb,
100588   const char **pzOrigTab,
100589   const char **pzOrigCol,
100590   u8 *pEstWidth
100591 ){
100592   char const *zOrigDb = 0;
100593   char const *zOrigTab = 0;
100594   char const *zOrigCol = 0;
100595 #else /* if !defined(SQLITE_ENABLE_COLUMN_METADATA) */
100596 # define columnType(A,B,C,D,E,F) columnTypeImpl(A,B,F)
100597 static const char *columnTypeImpl(
100598   NameContext *pNC, 
100599   Expr *pExpr,
100600   u8 *pEstWidth
100601 ){
100602 #endif /* !defined(SQLITE_ENABLE_COLUMN_METADATA) */
100603   char const *zType = 0;
100604   int j;
100605   u8 estWidth = 1;
100606 
100607   if( NEVER(pExpr==0) || pNC->pSrcList==0 ) return 0;
100608   switch( pExpr->op ){
100609     case TK_AGG_COLUMN:
100610     case TK_COLUMN: {
100611       /* The expression is a column. Locate the table the column is being
100612       ** extracted from in NameContext.pSrcList. This table may be real
100613       ** database table or a subquery.
100614       */
100615       Table *pTab = 0;            /* Table structure column is extracted from */
100616       Select *pS = 0;             /* Select the column is extracted from */
100617       int iCol = pExpr->iColumn;  /* Index of column in pTab */
100618       testcase( pExpr->op==TK_AGG_COLUMN );
100619       testcase( pExpr->op==TK_COLUMN );
100620       while( pNC && !pTab ){
100621         SrcList *pTabList = pNC->pSrcList;
100622         for(j=0;j<pTabList->nSrc && pTabList->a[j].iCursor!=pExpr->iTable;j++);
100623         if( j<pTabList->nSrc ){
100624           pTab = pTabList->a[j].pTab;
100625           pS = pTabList->a[j].pSelect;
100626         }else{
100627           pNC = pNC->pNext;
100628         }
100629       }
100630 
100631       if( pTab==0 ){
100632         /* At one time, code such as "SELECT new.x" within a trigger would
100633         ** cause this condition to run.  Since then, we have restructured how
100634         ** trigger code is generated and so this condition is no longer 
100635         ** possible. However, it can still be true for statements like
100636         ** the following:
100637         **
100638         **   CREATE TABLE t1(col INTEGER);
100639         **   SELECT (SELECT t1.col) FROM FROM t1;
100640         **
100641         ** when columnType() is called on the expression "t1.col" in the 
100642         ** sub-select. In this case, set the column type to NULL, even
100643         ** though it should really be "INTEGER".
100644         **
100645         ** This is not a problem, as the column type of "t1.col" is never
100646         ** used. When columnType() is called on the expression 
100647         ** "(SELECT t1.col)", the correct type is returned (see the TK_SELECT
100648         ** branch below.  */
100649         break;
100650       }
100651 
100652       assert( pTab && pExpr->pTab==pTab );
100653       if( pS ){
100654         /* The "table" is actually a sub-select or a view in the FROM clause
100655         ** of the SELECT statement. Return the declaration type and origin
100656         ** data for the result-set column of the sub-select.
100657         */
100658         if( iCol>=0 && ALWAYS(iCol<pS->pEList->nExpr) ){
100659           /* If iCol is less than zero, then the expression requests the
100660           ** rowid of the sub-select or view. This expression is legal (see 
100661           ** test case misc2.2.2) - it always evaluates to NULL.
100662           */
100663           NameContext sNC;
100664           Expr *p = pS->pEList->a[iCol].pExpr;
100665           sNC.pSrcList = pS->pSrc;
100666           sNC.pNext = pNC;
100667           sNC.pParse = pNC->pParse;
100668           zType = columnType(&sNC, p,&zOrigDb,&zOrigTab,&zOrigCol, &estWidth); 
100669         }
100670       }else if( ALWAYS(pTab->pSchema) ){
100671         /* A real table */
100672         assert( !pS );
100673         if( iCol<0 ) iCol = pTab->iPKey;
100674         assert( iCol==-1 || (iCol>=0 && iCol<pTab->nCol) );
100675 #ifdef SQLITE_ENABLE_COLUMN_METADATA
100676         if( iCol<0 ){
100677           zType = "INTEGER";
100678           zOrigCol = "rowid";
100679         }else{
100680           zType = pTab->aCol[iCol].zType;
100681           zOrigCol = pTab->aCol[iCol].zName;
100682           estWidth = pTab->aCol[iCol].szEst;
100683         }
100684         zOrigTab = pTab->zName;
100685         if( pNC->pParse ){
100686           int iDb = sqlite3SchemaToIndex(pNC->pParse->db, pTab->pSchema);
100687           zOrigDb = pNC->pParse->db->aDb[iDb].zName;
100688         }
100689 #else
100690         if( iCol<0 ){
100691           zType = "INTEGER";
100692         }else{
100693           zType = pTab->aCol[iCol].zType;
100694           estWidth = pTab->aCol[iCol].szEst;
100695         }
100696 #endif
100697       }
100698       break;
100699     }
100700 #ifndef SQLITE_OMIT_SUBQUERY
100701     case TK_SELECT: {
100702       /* The expression is a sub-select. Return the declaration type and
100703       ** origin info for the single column in the result set of the SELECT
100704       ** statement.
100705       */
100706       NameContext sNC;
100707       Select *pS = pExpr->x.pSelect;
100708       Expr *p = pS->pEList->a[0].pExpr;
100709       assert( ExprHasProperty(pExpr, EP_xIsSelect) );
100710       sNC.pSrcList = pS->pSrc;
100711       sNC.pNext = pNC;
100712       sNC.pParse = pNC->pParse;
100713       zType = columnType(&sNC, p, &zOrigDb, &zOrigTab, &zOrigCol, &estWidth); 
100714       break;
100715     }
100716 #endif
100717   }
100718 
100719 #ifdef SQLITE_ENABLE_COLUMN_METADATA  
100720   if( pzOrigDb ){
100721     assert( pzOrigTab && pzOrigCol );
100722     *pzOrigDb = zOrigDb;
100723     *pzOrigTab = zOrigTab;
100724     *pzOrigCol = zOrigCol;
100725   }
100726 #endif
100727   if( pEstWidth ) *pEstWidth = estWidth;
100728   return zType;
100729 }
100730 
100731 /*
100732 ** Generate code that will tell the VDBE the declaration types of columns
100733 ** in the result set.
100734 */
100735 static void generateColumnTypes(
100736   Parse *pParse,      /* Parser context */
100737   SrcList *pTabList,  /* List of tables */
100738   ExprList *pEList    /* Expressions defining the result set */
100739 ){
100740 #ifndef SQLITE_OMIT_DECLTYPE
100741   Vdbe *v = pParse->pVdbe;
100742   int i;
100743   NameContext sNC;
100744   sNC.pSrcList = pTabList;
100745   sNC.pParse = pParse;
100746   for(i=0; i<pEList->nExpr; i++){
100747     Expr *p = pEList->a[i].pExpr;
100748     const char *zType;
100749 #ifdef SQLITE_ENABLE_COLUMN_METADATA
100750     const char *zOrigDb = 0;
100751     const char *zOrigTab = 0;
100752     const char *zOrigCol = 0;
100753     zType = columnType(&sNC, p, &zOrigDb, &zOrigTab, &zOrigCol, 0);
100754 
100755     /* The vdbe must make its own copy of the column-type and other 
100756     ** column specific strings, in case the schema is reset before this
100757     ** virtual machine is deleted.
100758     */
100759     sqlite3VdbeSetColName(v, i, COLNAME_DATABASE, zOrigDb, SQLITE_TRANSIENT);
100760     sqlite3VdbeSetColName(v, i, COLNAME_TABLE, zOrigTab, SQLITE_TRANSIENT);
100761     sqlite3VdbeSetColName(v, i, COLNAME_COLUMN, zOrigCol, SQLITE_TRANSIENT);
100762 #else
100763     zType = columnType(&sNC, p, 0, 0, 0, 0);
100764 #endif
100765     sqlite3VdbeSetColName(v, i, COLNAME_DECLTYPE, zType, SQLITE_TRANSIENT);
100766   }
100767 #endif /* !defined(SQLITE_OMIT_DECLTYPE) */
100768 }
100769 
100770 /*
100771 ** Generate code that will tell the VDBE the names of columns
100772 ** in the result set.  This information is used to provide the
100773 ** azCol[] values in the callback.
100774 */
100775 static void generateColumnNames(
100776   Parse *pParse,      /* Parser context */
100777   SrcList *pTabList,  /* List of tables */
100778   ExprList *pEList    /* Expressions defining the result set */
100779 ){
100780   Vdbe *v = pParse->pVdbe;
100781   int i, j;
100782   sqlite3 *db = pParse->db;
100783   int fullNames, shortNames;
100784 
100785 #ifndef SQLITE_OMIT_EXPLAIN
100786   /* If this is an EXPLAIN, skip this step */
100787   if( pParse->explain ){
100788     return;
100789   }
100790 #endif
100791 
100792   if( pParse->colNamesSet || NEVER(v==0) || db->mallocFailed ) return;
100793   pParse->colNamesSet = 1;
100794   fullNames = (db->flags & SQLITE_FullColNames)!=0;
100795   shortNames = (db->flags & SQLITE_ShortColNames)!=0;
100796   sqlite3VdbeSetNumCols(v, pEList->nExpr);
100797   for(i=0; i<pEList->nExpr; i++){
100798     Expr *p;
100799     p = pEList->a[i].pExpr;
100800     if( NEVER(p==0) ) continue;
100801     if( pEList->a[i].zName ){
100802       char *zName = pEList->a[i].zName;
100803       sqlite3VdbeSetColName(v, i, COLNAME_NAME, zName, SQLITE_TRANSIENT);
100804     }else if( (p->op==TK_COLUMN || p->op==TK_AGG_COLUMN) && pTabList ){
100805       Table *pTab;
100806       char *zCol;
100807       int iCol = p->iColumn;
100808       for(j=0; ALWAYS(j<pTabList->nSrc); j++){
100809         if( pTabList->a[j].iCursor==p->iTable ) break;
100810       }
100811       assert( j<pTabList->nSrc );
100812       pTab = pTabList->a[j].pTab;
100813       if( iCol<0 ) iCol = pTab->iPKey;
100814       assert( iCol==-1 || (iCol>=0 && iCol<pTab->nCol) );
100815       if( iCol<0 ){
100816         zCol = "rowid";
100817       }else{
100818         zCol = pTab->aCol[iCol].zName;
100819       }
100820       if( !shortNames && !fullNames ){
100821         sqlite3VdbeSetColName(v, i, COLNAME_NAME, 
100822             sqlite3DbStrDup(db, pEList->a[i].zSpan), SQLITE_DYNAMIC);
100823       }else if( fullNames ){
100824         char *zName = 0;
100825         zName = sqlite3MPrintf(db, "%s.%s", pTab->zName, zCol);
100826         sqlite3VdbeSetColName(v, i, COLNAME_NAME, zName, SQLITE_DYNAMIC);
100827       }else{
100828         sqlite3VdbeSetColName(v, i, COLNAME_NAME, zCol, SQLITE_TRANSIENT);
100829       }
100830     }else{
100831       sqlite3VdbeSetColName(v, i, COLNAME_NAME, 
100832           sqlite3DbStrDup(db, pEList->a[i].zSpan), SQLITE_DYNAMIC);
100833     }
100834   }
100835   generateColumnTypes(pParse, pTabList, pEList);
100836 }
100837 
100838 /*
100839 ** Given a an expression list (which is really the list of expressions
100840 ** that form the result set of a SELECT statement) compute appropriate
100841 ** column names for a table that would hold the expression list.
100842 **
100843 ** All column names will be unique.
100844 **
100845 ** Only the column names are computed.  Column.zType, Column.zColl,
100846 ** and other fields of Column are zeroed.
100847 **
100848 ** Return SQLITE_OK on success.  If a memory allocation error occurs,
100849 ** store NULL in *paCol and 0 in *pnCol and return SQLITE_NOMEM.
100850 */
100851 static int selectColumnsFromExprList(
100852   Parse *pParse,          /* Parsing context */
100853   ExprList *pEList,       /* Expr list from which to derive column names */
100854   i16 *pnCol,             /* Write the number of columns here */
100855   Column **paCol          /* Write the new column list here */
100856 ){
100857   sqlite3 *db = pParse->db;   /* Database connection */
100858   int i, j;                   /* Loop counters */
100859   int cnt;                    /* Index added to make the name unique */
100860   Column *aCol, *pCol;        /* For looping over result columns */
100861   int nCol;                   /* Number of columns in the result set */
100862   Expr *p;                    /* Expression for a single result column */
100863   char *zName;                /* Column name */
100864   int nName;                  /* Size of name in zName[] */
100865 
100866   if( pEList ){
100867     nCol = pEList->nExpr;
100868     aCol = sqlite3DbMallocZero(db, sizeof(aCol[0])*nCol);
100869     testcase( aCol==0 );
100870   }else{
100871     nCol = 0;
100872     aCol = 0;
100873   }
100874   *pnCol = nCol;
100875   *paCol = aCol;
100876 
100877   for(i=0, pCol=aCol; i<nCol; i++, pCol++){
100878     /* Get an appropriate name for the column
100879     */
100880     p = sqlite3ExprSkipCollate(pEList->a[i].pExpr);
100881     if( (zName = pEList->a[i].zName)!=0 ){
100882       /* If the column contains an "AS <name>" phrase, use <name> as the name */
100883       zName = sqlite3DbStrDup(db, zName);
100884     }else{
100885       Expr *pColExpr = p;  /* The expression that is the result column name */
100886       Table *pTab;         /* Table associated with this expression */
100887       while( pColExpr->op==TK_DOT ){
100888         pColExpr = pColExpr->pRight;
100889         assert( pColExpr!=0 );
100890       }
100891       if( pColExpr->op==TK_COLUMN && ALWAYS(pColExpr->pTab!=0) ){
100892         /* For columns use the column name name */
100893         int iCol = pColExpr->iColumn;
100894         pTab = pColExpr->pTab;
100895         if( iCol<0 ) iCol = pTab->iPKey;
100896         zName = sqlite3MPrintf(db, "%s",
100897                  iCol>=0 ? pTab->aCol[iCol].zName : "rowid");
100898       }else if( pColExpr->op==TK_ID ){
100899         assert( !ExprHasProperty(pColExpr, EP_IntValue) );
100900         zName = sqlite3MPrintf(db, "%s", pColExpr->u.zToken);
100901       }else{
100902         /* Use the original text of the column expression as its name */
100903         zName = sqlite3MPrintf(db, "%s", pEList->a[i].zSpan);
100904       }
100905     }
100906     if( db->mallocFailed ){
100907       sqlite3DbFree(db, zName);
100908       break;
100909     }
100910 
100911     /* Make sure the column name is unique.  If the name is not unique,
100912     ** append a integer to the name so that it becomes unique.
100913     */
100914     nName = sqlite3Strlen30(zName);
100915     for(j=cnt=0; j<i; j++){
100916       if( sqlite3StrICmp(aCol[j].zName, zName)==0 ){
100917         char *zNewName;
100918         int k;
100919         for(k=nName-1; k>1 && sqlite3Isdigit(zName[k]); k--){}
100920         if( zName[k]==':' ) nName = k;
100921         zName[nName] = 0;
100922         zNewName = sqlite3MPrintf(db, "%s:%d", zName, ++cnt);
100923         sqlite3DbFree(db, zName);
100924         zName = zNewName;
100925         j = -1;
100926         if( zName==0 ) break;
100927       }
100928     }
100929     pCol->zName = zName;
100930   }
100931   if( db->mallocFailed ){
100932     for(j=0; j<i; j++){
100933       sqlite3DbFree(db, aCol[j].zName);
100934     }
100935     sqlite3DbFree(db, aCol);
100936     *paCol = 0;
100937     *pnCol = 0;
100938     return SQLITE_NOMEM;
100939   }
100940   return SQLITE_OK;
100941 }
100942 
100943 /*
100944 ** Add type and collation information to a column list based on
100945 ** a SELECT statement.
100946 ** 
100947 ** The column list presumably came from selectColumnNamesFromExprList().
100948 ** The column list has only names, not types or collations.  This
100949 ** routine goes through and adds the types and collations.
100950 **
100951 ** This routine requires that all identifiers in the SELECT
100952 ** statement be resolved.
100953 */
100954 static void selectAddColumnTypeAndCollation(
100955   Parse *pParse,        /* Parsing contexts */
100956   Table *pTab,          /* Add column type information to this table */
100957   Select *pSelect       /* SELECT used to determine types and collations */
100958 ){
100959   sqlite3 *db = pParse->db;
100960   NameContext sNC;
100961   Column *pCol;
100962   CollSeq *pColl;
100963   int i;
100964   Expr *p;
100965   struct ExprList_item *a;
100966   u64 szAll = 0;
100967 
100968   assert( pSelect!=0 );
100969   assert( (pSelect->selFlags & SF_Resolved)!=0 );
100970   assert( pTab->nCol==pSelect->pEList->nExpr || db->mallocFailed );
100971   if( db->mallocFailed ) return;
100972   memset(&sNC, 0, sizeof(sNC));
100973   sNC.pSrcList = pSelect->pSrc;
100974   a = pSelect->pEList->a;
100975   for(i=0, pCol=pTab->aCol; i<pTab->nCol; i++, pCol++){
100976     p = a[i].pExpr;
100977     pCol->zType = sqlite3DbStrDup(db, columnType(&sNC, p,0,0,0, &pCol->szEst));
100978     szAll += pCol->szEst;
100979     pCol->affinity = sqlite3ExprAffinity(p);
100980     if( pCol->affinity==0 ) pCol->affinity = SQLITE_AFF_NONE;
100981     pColl = sqlite3ExprCollSeq(pParse, p);
100982     if( pColl ){
100983       pCol->zColl = sqlite3DbStrDup(db, pColl->zName);
100984     }
100985   }
100986   pTab->szTabRow = sqlite3LogEst(szAll*4);
100987 }
100988 
100989 /*
100990 ** Given a SELECT statement, generate a Table structure that describes
100991 ** the result set of that SELECT.
100992 */
100993 SQLITE_PRIVATE Table *sqlite3ResultSetOfSelect(Parse *pParse, Select *pSelect){
100994   Table *pTab;
100995   sqlite3 *db = pParse->db;
100996   int savedFlags;
100997 
100998   savedFlags = db->flags;
100999   db->flags &= ~SQLITE_FullColNames;
101000   db->flags |= SQLITE_ShortColNames;
101001   sqlite3SelectPrep(pParse, pSelect, 0);
101002   if( pParse->nErr ) return 0;
101003   while( pSelect->pPrior ) pSelect = pSelect->pPrior;
101004   db->flags = savedFlags;
101005   pTab = sqlite3DbMallocZero(db, sizeof(Table) );
101006   if( pTab==0 ){
101007     return 0;
101008   }
101009   /* The sqlite3ResultSetOfSelect() is only used n contexts where lookaside
101010   ** is disabled */
101011   assert( db->lookaside.bEnabled==0 );
101012   pTab->nRef = 1;
101013   pTab->zName = 0;
101014   pTab->nRowEst = 1048576;
101015   selectColumnsFromExprList(pParse, pSelect->pEList, &pTab->nCol, &pTab->aCol);
101016   selectAddColumnTypeAndCollation(pParse, pTab, pSelect);
101017   pTab->iPKey = -1;
101018   if( db->mallocFailed ){
101019     sqlite3DeleteTable(db, pTab);
101020     return 0;
101021   }
101022   return pTab;
101023 }
101024 
101025 /*
101026 ** Get a VDBE for the given parser context.  Create a new one if necessary.
101027 ** If an error occurs, return NULL and leave a message in pParse.
101028 */
101029 SQLITE_PRIVATE Vdbe *sqlite3GetVdbe(Parse *pParse){
101030   Vdbe *v = pParse->pVdbe;
101031   if( v==0 ){
101032     v = pParse->pVdbe = sqlite3VdbeCreate(pParse->db);
101033 #ifndef SQLITE_OMIT_TRACE
101034     if( v ){
101035       sqlite3VdbeAddOp0(v, OP_Trace);
101036     }
101037 #endif
101038   }
101039   return v;
101040 }
101041 
101042 
101043 /*
101044 ** Compute the iLimit and iOffset fields of the SELECT based on the
101045 ** pLimit and pOffset expressions.  pLimit and pOffset hold the expressions
101046 ** that appear in the original SQL statement after the LIMIT and OFFSET
101047 ** keywords.  Or NULL if those keywords are omitted. iLimit and iOffset 
101048 ** are the integer memory register numbers for counters used to compute 
101049 ** the limit and offset.  If there is no limit and/or offset, then 
101050 ** iLimit and iOffset are negative.
101051 **
101052 ** This routine changes the values of iLimit and iOffset only if
101053 ** a limit or offset is defined by pLimit and pOffset.  iLimit and
101054 ** iOffset should have been preset to appropriate default values
101055 ** (usually but not always -1) prior to calling this routine.
101056 ** Only if pLimit!=0 or pOffset!=0 do the limit registers get
101057 ** redefined.  The UNION ALL operator uses this property to force
101058 ** the reuse of the same limit and offset registers across multiple
101059 ** SELECT statements.
101060 */
101061 static void computeLimitRegisters(Parse *pParse, Select *p, int iBreak){
101062   Vdbe *v = 0;
101063   int iLimit = 0;
101064   int iOffset;
101065   int addr1, n;
101066   if( p->iLimit ) return;
101067 
101068   /* 
101069   ** "LIMIT -1" always shows all rows.  There is some
101070   ** controversy about what the correct behavior should be.
101071   ** The current implementation interprets "LIMIT 0" to mean
101072   ** no rows.
101073   */
101074   sqlite3ExprCacheClear(pParse);
101075   assert( p->pOffset==0 || p->pLimit!=0 );
101076   if( p->pLimit ){
101077     p->iLimit = iLimit = ++pParse->nMem;
101078     v = sqlite3GetVdbe(pParse);
101079     if( NEVER(v==0) ) return;  /* VDBE should have already been allocated */
101080     if( sqlite3ExprIsInteger(p->pLimit, &n) ){
101081       sqlite3VdbeAddOp2(v, OP_Integer, n, iLimit);
101082       VdbeComment((v, "LIMIT counter"));
101083       if( n==0 ){
101084         sqlite3VdbeAddOp2(v, OP_Goto, 0, iBreak);
101085       }else if( n>=0 && p->nSelectRow>(u64)n ){
101086         p->nSelectRow = n;
101087       }
101088     }else{
101089       sqlite3ExprCode(pParse, p->pLimit, iLimit);
101090       sqlite3VdbeAddOp1(v, OP_MustBeInt, iLimit);
101091       VdbeComment((v, "LIMIT counter"));
101092       sqlite3VdbeAddOp2(v, OP_IfZero, iLimit, iBreak);
101093     }
101094     if( p->pOffset ){
101095       p->iOffset = iOffset = ++pParse->nMem;
101096       pParse->nMem++;   /* Allocate an extra register for limit+offset */
101097       sqlite3ExprCode(pParse, p->pOffset, iOffset);
101098       sqlite3VdbeAddOp1(v, OP_MustBeInt, iOffset);
101099       VdbeComment((v, "OFFSET counter"));
101100       addr1 = sqlite3VdbeAddOp1(v, OP_IfPos, iOffset);
101101       sqlite3VdbeAddOp2(v, OP_Integer, 0, iOffset);
101102       sqlite3VdbeJumpHere(v, addr1);
101103       sqlite3VdbeAddOp3(v, OP_Add, iLimit, iOffset, iOffset+1);
101104       VdbeComment((v, "LIMIT+OFFSET"));
101105       addr1 = sqlite3VdbeAddOp1(v, OP_IfPos, iLimit);
101106       sqlite3VdbeAddOp2(v, OP_Integer, -1, iOffset+1);
101107       sqlite3VdbeJumpHere(v, addr1);
101108     }
101109   }
101110 }
101111 
101112 #ifndef SQLITE_OMIT_COMPOUND_SELECT
101113 /*
101114 ** Return the appropriate collating sequence for the iCol-th column of
101115 ** the result set for the compound-select statement "p".  Return NULL if
101116 ** the column has no default collating sequence.
101117 **
101118 ** The collating sequence for the compound select is taken from the
101119 ** left-most term of the select that has a collating sequence.
101120 */
101121 static CollSeq *multiSelectCollSeq(Parse *pParse, Select *p, int iCol){
101122   CollSeq *pRet;
101123   if( p->pPrior ){
101124     pRet = multiSelectCollSeq(pParse, p->pPrior, iCol);
101125   }else{
101126     pRet = 0;
101127   }
101128   assert( iCol>=0 );
101129   if( pRet==0 && iCol<p->pEList->nExpr ){
101130     pRet = sqlite3ExprCollSeq(pParse, p->pEList->a[iCol].pExpr);
101131   }
101132   return pRet;
101133 }
101134 #endif /* SQLITE_OMIT_COMPOUND_SELECT */
101135 
101136 /* Forward reference */
101137 static int multiSelectOrderBy(
101138   Parse *pParse,        /* Parsing context */
101139   Select *p,            /* The right-most of SELECTs to be coded */
101140   SelectDest *pDest     /* What to do with query results */
101141 );
101142 
101143 
101144 #ifndef SQLITE_OMIT_COMPOUND_SELECT
101145 /*
101146 ** This routine is called to process a compound query form from
101147 ** two or more separate queries using UNION, UNION ALL, EXCEPT, or
101148 ** INTERSECT
101149 **
101150 ** "p" points to the right-most of the two queries.  the query on the
101151 ** left is p->pPrior.  The left query could also be a compound query
101152 ** in which case this routine will be called recursively. 
101153 **
101154 ** The results of the total query are to be written into a destination
101155 ** of type eDest with parameter iParm.
101156 **
101157 ** Example 1:  Consider a three-way compound SQL statement.
101158 **
101159 **     SELECT a FROM t1 UNION SELECT b FROM t2 UNION SELECT c FROM t3
101160 **
101161 ** This statement is parsed up as follows:
101162 **
101163 **     SELECT c FROM t3
101164 **      |
101165 **      `----->  SELECT b FROM t2
101166 **                |
101167 **                `------>  SELECT a FROM t1
101168 **
101169 ** The arrows in the diagram above represent the Select.pPrior pointer.
101170 ** So if this routine is called with p equal to the t3 query, then
101171 ** pPrior will be the t2 query.  p->op will be TK_UNION in this case.
101172 **
101173 ** Notice that because of the way SQLite parses compound SELECTs, the
101174 ** individual selects always group from left to right.
101175 */
101176 static int multiSelect(
101177   Parse *pParse,        /* Parsing context */
101178   Select *p,            /* The right-most of SELECTs to be coded */
101179   SelectDest *pDest     /* What to do with query results */
101180 ){
101181   int rc = SQLITE_OK;   /* Success code from a subroutine */
101182   Select *pPrior;       /* Another SELECT immediately to our left */
101183   Vdbe *v;              /* Generate code to this VDBE */
101184   SelectDest dest;      /* Alternative data destination */
101185   Select *pDelete = 0;  /* Chain of simple selects to delete */
101186   sqlite3 *db;          /* Database connection */
101187 #ifndef SQLITE_OMIT_EXPLAIN
101188   int iSub1;            /* EQP id of left-hand query */
101189   int iSub2;            /* EQP id of right-hand query */
101190 #endif
101191 
101192   /* Make sure there is no ORDER BY or LIMIT clause on prior SELECTs.  Only
101193   ** the last (right-most) SELECT in the series may have an ORDER BY or LIMIT.
101194   */
101195   assert( p && p->pPrior );  /* Calling function guarantees this much */
101196   db = pParse->db;
101197   pPrior = p->pPrior;
101198   assert( pPrior->pRightmost!=pPrior );
101199   assert( pPrior->pRightmost==p->pRightmost );
101200   dest = *pDest;
101201   if( pPrior->pOrderBy ){
101202     sqlite3ErrorMsg(pParse,"ORDER BY clause should come after %s not before",
101203       selectOpName(p->op));
101204     rc = 1;
101205     goto multi_select_end;
101206   }
101207   if( pPrior->pLimit ){
101208     sqlite3ErrorMsg(pParse,"LIMIT clause should come after %s not before",
101209       selectOpName(p->op));
101210     rc = 1;
101211     goto multi_select_end;
101212   }
101213 
101214   v = sqlite3GetVdbe(pParse);
101215   assert( v!=0 );  /* The VDBE already created by calling function */
101216 
101217   /* Create the destination temporary table if necessary
101218   */
101219   if( dest.eDest==SRT_EphemTab ){
101220     assert( p->pEList );
101221     sqlite3VdbeAddOp2(v, OP_OpenEphemeral, dest.iSDParm, p->pEList->nExpr);
101222     sqlite3VdbeChangeP5(v, BTREE_UNORDERED);
101223     dest.eDest = SRT_Table;
101224   }
101225 
101226   /* Make sure all SELECTs in the statement have the same number of elements
101227   ** in their result sets.
101228   */
101229   assert( p->pEList && pPrior->pEList );
101230   if( p->pEList->nExpr!=pPrior->pEList->nExpr ){
101231     if( p->selFlags & SF_Values ){
101232       sqlite3ErrorMsg(pParse, "all VALUES must have the same number of terms");
101233     }else{
101234       sqlite3ErrorMsg(pParse, "SELECTs to the left and right of %s"
101235         " do not have the same number of result columns", selectOpName(p->op));
101236     }
101237     rc = 1;
101238     goto multi_select_end;
101239   }
101240 
101241   /* Compound SELECTs that have an ORDER BY clause are handled separately.
101242   */
101243   if( p->pOrderBy ){
101244     return multiSelectOrderBy(pParse, p, pDest);
101245   }
101246 
101247   /* Generate code for the left and right SELECT statements.
101248   */
101249   switch( p->op ){
101250     case TK_ALL: {
101251       int addr = 0;
101252       int nLimit;
101253       assert( !pPrior->pLimit );
101254       pPrior->iLimit = p->iLimit;
101255       pPrior->iOffset = p->iOffset;
101256       pPrior->pLimit = p->pLimit;
101257       pPrior->pOffset = p->pOffset;
101258       explainSetInteger(iSub1, pParse->iNextSelectId);
101259       rc = sqlite3Select(pParse, pPrior, &dest);
101260       p->pLimit = 0;
101261       p->pOffset = 0;
101262       if( rc ){
101263         goto multi_select_end;
101264       }
101265       p->pPrior = 0;
101266       p->iLimit = pPrior->iLimit;
101267       p->iOffset = pPrior->iOffset;
101268       if( p->iLimit ){
101269         addr = sqlite3VdbeAddOp1(v, OP_IfZero, p->iLimit);
101270         VdbeComment((v, "Jump ahead if LIMIT reached"));
101271       }
101272       explainSetInteger(iSub2, pParse->iNextSelectId);
101273       rc = sqlite3Select(pParse, p, &dest);
101274       testcase( rc!=SQLITE_OK );
101275       pDelete = p->pPrior;
101276       p->pPrior = pPrior;
101277       p->nSelectRow += pPrior->nSelectRow;
101278       if( pPrior->pLimit
101279        && sqlite3ExprIsInteger(pPrior->pLimit, &nLimit)
101280        && nLimit>0 && p->nSelectRow > (u64)nLimit 
101281       ){
101282         p->nSelectRow = nLimit;
101283       }
101284       if( addr ){
101285         sqlite3VdbeJumpHere(v, addr);
101286       }
101287       break;
101288     }
101289     case TK_EXCEPT:
101290     case TK_UNION: {
101291       int unionTab;    /* Cursor number of the temporary table holding result */
101292       u8 op = 0;       /* One of the SRT_ operations to apply to self */
101293       int priorOp;     /* The SRT_ operation to apply to prior selects */
101294       Expr *pLimit, *pOffset; /* Saved values of p->nLimit and p->nOffset */
101295       int addr;
101296       SelectDest uniondest;
101297 
101298       testcase( p->op==TK_EXCEPT );
101299       testcase( p->op==TK_UNION );
101300       priorOp = SRT_Union;
101301       if( dest.eDest==priorOp && ALWAYS(!p->pLimit &&!p->pOffset) ){
101302         /* We can reuse a temporary table generated by a SELECT to our
101303         ** right.
101304         */
101305         assert( p->pRightmost!=p );  /* Can only happen for leftward elements
101306                                      ** of a 3-way or more compound */
101307         assert( p->pLimit==0 );      /* Not allowed on leftward elements */
101308         assert( p->pOffset==0 );     /* Not allowed on leftward elements */
101309         unionTab = dest.iSDParm;
101310       }else{
101311         /* We will need to create our own temporary table to hold the
101312         ** intermediate results.
101313         */
101314         unionTab = pParse->nTab++;
101315         assert( p->pOrderBy==0 );
101316         addr = sqlite3VdbeAddOp2(v, OP_OpenEphemeral, unionTab, 0);
101317         assert( p->addrOpenEphm[0] == -1 );
101318         p->addrOpenEphm[0] = addr;
101319         p->pRightmost->selFlags |= SF_UsesEphemeral;
101320         assert( p->pEList );
101321       }
101322 
101323       /* Code the SELECT statements to our left
101324       */
101325       assert( !pPrior->pOrderBy );
101326       sqlite3SelectDestInit(&uniondest, priorOp, unionTab);
101327       explainSetInteger(iSub1, pParse->iNextSelectId);
101328       rc = sqlite3Select(pParse, pPrior, &uniondest);
101329       if( rc ){
101330         goto multi_select_end;
101331       }
101332 
101333       /* Code the current SELECT statement
101334       */
101335       if( p->op==TK_EXCEPT ){
101336         op = SRT_Except;
101337       }else{
101338         assert( p->op==TK_UNION );
101339         op = SRT_Union;
101340       }
101341       p->pPrior = 0;
101342       pLimit = p->pLimit;
101343       p->pLimit = 0;
101344       pOffset = p->pOffset;
101345       p->pOffset = 0;
101346       uniondest.eDest = op;
101347       explainSetInteger(iSub2, pParse->iNextSelectId);
101348       rc = sqlite3Select(pParse, p, &uniondest);
101349       testcase( rc!=SQLITE_OK );
101350       /* Query flattening in sqlite3Select() might refill p->pOrderBy.
101351       ** Be sure to delete p->pOrderBy, therefore, to avoid a memory leak. */
101352       sqlite3ExprListDelete(db, p->pOrderBy);
101353       pDelete = p->pPrior;
101354       p->pPrior = pPrior;
101355       p->pOrderBy = 0;
101356       if( p->op==TK_UNION ) p->nSelectRow += pPrior->nSelectRow;
101357       sqlite3ExprDelete(db, p->pLimit);
101358       p->pLimit = pLimit;
101359       p->pOffset = pOffset;
101360       p->iLimit = 0;
101361       p->iOffset = 0;
101362 
101363       /* Convert the data in the temporary table into whatever form
101364       ** it is that we currently need.
101365       */
101366       assert( unionTab==dest.iSDParm || dest.eDest!=priorOp );
101367       if( dest.eDest!=priorOp ){
101368         int iCont, iBreak, iStart;
101369         assert( p->pEList );
101370         if( dest.eDest==SRT_Output ){
101371           Select *pFirst = p;
101372           while( pFirst->pPrior ) pFirst = pFirst->pPrior;
101373           generateColumnNames(pParse, 0, pFirst->pEList);
101374         }
101375         iBreak = sqlite3VdbeMakeLabel(v);
101376         iCont = sqlite3VdbeMakeLabel(v);
101377         computeLimitRegisters(pParse, p, iBreak);
101378         sqlite3VdbeAddOp2(v, OP_Rewind, unionTab, iBreak);
101379         iStart = sqlite3VdbeCurrentAddr(v);
101380         selectInnerLoop(pParse, p, p->pEList, unionTab, p->pEList->nExpr,
101381                         0, 0, &dest, iCont, iBreak);
101382         sqlite3VdbeResolveLabel(v, iCont);
101383         sqlite3VdbeAddOp2(v, OP_Next, unionTab, iStart);
101384         sqlite3VdbeResolveLabel(v, iBreak);
101385         sqlite3VdbeAddOp2(v, OP_Close, unionTab, 0);
101386       }
101387       break;
101388     }
101389     default: assert( p->op==TK_INTERSECT ); {
101390       int tab1, tab2;
101391       int iCont, iBreak, iStart;
101392       Expr *pLimit, *pOffset;
101393       int addr;
101394       SelectDest intersectdest;
101395       int r1;
101396 
101397       /* INTERSECT is different from the others since it requires
101398       ** two temporary tables.  Hence it has its own case.  Begin
101399       ** by allocating the tables we will need.
101400       */
101401       tab1 = pParse->nTab++;
101402       tab2 = pParse->nTab++;
101403       assert( p->pOrderBy==0 );
101404 
101405       addr = sqlite3VdbeAddOp2(v, OP_OpenEphemeral, tab1, 0);
101406       assert( p->addrOpenEphm[0] == -1 );
101407       p->addrOpenEphm[0] = addr;
101408       p->pRightmost->selFlags |= SF_UsesEphemeral;
101409       assert( p->pEList );
101410 
101411       /* Code the SELECTs to our left into temporary table "tab1".
101412       */
101413       sqlite3SelectDestInit(&intersectdest, SRT_Union, tab1);
101414       explainSetInteger(iSub1, pParse->iNextSelectId);
101415       rc = sqlite3Select(pParse, pPrior, &intersectdest);
101416       if( rc ){
101417         goto multi_select_end;
101418       }
101419 
101420       /* Code the current SELECT into temporary table "tab2"
101421       */
101422       addr = sqlite3VdbeAddOp2(v, OP_OpenEphemeral, tab2, 0);
101423       assert( p->addrOpenEphm[1] == -1 );
101424       p->addrOpenEphm[1] = addr;
101425       p->pPrior = 0;
101426       pLimit = p->pLimit;
101427       p->pLimit = 0;
101428       pOffset = p->pOffset;
101429       p->pOffset = 0;
101430       intersectdest.iSDParm = tab2;
101431       explainSetInteger(iSub2, pParse->iNextSelectId);
101432       rc = sqlite3Select(pParse, p, &intersectdest);
101433       testcase( rc!=SQLITE_OK );
101434       pDelete = p->pPrior;
101435       p->pPrior = pPrior;
101436       if( p->nSelectRow>pPrior->nSelectRow ) p->nSelectRow = pPrior->nSelectRow;
101437       sqlite3ExprDelete(db, p->pLimit);
101438       p->pLimit = pLimit;
101439       p->pOffset = pOffset;
101440 
101441       /* Generate code to take the intersection of the two temporary
101442       ** tables.
101443       */
101444       assert( p->pEList );
101445       if( dest.eDest==SRT_Output ){
101446         Select *pFirst = p;
101447         while( pFirst->pPrior ) pFirst = pFirst->pPrior;
101448         generateColumnNames(pParse, 0, pFirst->pEList);
101449       }
101450       iBreak = sqlite3VdbeMakeLabel(v);
101451       iCont = sqlite3VdbeMakeLabel(v);
101452       computeLimitRegisters(pParse, p, iBreak);
101453       sqlite3VdbeAddOp2(v, OP_Rewind, tab1, iBreak);
101454       r1 = sqlite3GetTempReg(pParse);
101455       iStart = sqlite3VdbeAddOp2(v, OP_RowKey, tab1, r1);
101456       sqlite3VdbeAddOp4Int(v, OP_NotFound, tab2, iCont, r1, 0);
101457       sqlite3ReleaseTempReg(pParse, r1);
101458       selectInnerLoop(pParse, p, p->pEList, tab1, p->pEList->nExpr,
101459                       0, 0, &dest, iCont, iBreak);
101460       sqlite3VdbeResolveLabel(v, iCont);
101461       sqlite3VdbeAddOp2(v, OP_Next, tab1, iStart);
101462       sqlite3VdbeResolveLabel(v, iBreak);
101463       sqlite3VdbeAddOp2(v, OP_Close, tab2, 0);
101464       sqlite3VdbeAddOp2(v, OP_Close, tab1, 0);
101465       break;
101466     }
101467   }
101468 
101469   explainComposite(pParse, p->op, iSub1, iSub2, p->op!=TK_ALL);
101470 
101471   /* Compute collating sequences used by 
101472   ** temporary tables needed to implement the compound select.
101473   ** Attach the KeyInfo structure to all temporary tables.
101474   **
101475   ** This section is run by the right-most SELECT statement only.
101476   ** SELECT statements to the left always skip this part.  The right-most
101477   ** SELECT might also skip this part if it has no ORDER BY clause and
101478   ** no temp tables are required.
101479   */
101480   if( p->selFlags & SF_UsesEphemeral ){
101481     int i;                        /* Loop counter */
101482     KeyInfo *pKeyInfo;            /* Collating sequence for the result set */
101483     Select *pLoop;                /* For looping through SELECT statements */
101484     CollSeq **apColl;             /* For looping through pKeyInfo->aColl[] */
101485     int nCol;                     /* Number of columns in result set */
101486 
101487     assert( p->pRightmost==p );
101488     nCol = p->pEList->nExpr;
101489     pKeyInfo = sqlite3KeyInfoAlloc(db, nCol, 1);
101490     if( !pKeyInfo ){
101491       rc = SQLITE_NOMEM;
101492       goto multi_select_end;
101493     }
101494     for(i=0, apColl=pKeyInfo->aColl; i<nCol; i++, apColl++){
101495       *apColl = multiSelectCollSeq(pParse, p, i);
101496       if( 0==*apColl ){
101497         *apColl = db->pDfltColl;
101498       }
101499     }
101500 
101501     for(pLoop=p; pLoop; pLoop=pLoop->pPrior){
101502       for(i=0; i<2; i++){
101503         int addr = pLoop->addrOpenEphm[i];
101504         if( addr<0 ){
101505           /* If [0] is unused then [1] is also unused.  So we can
101506           ** always safely abort as soon as the first unused slot is found */
101507           assert( pLoop->addrOpenEphm[1]<0 );
101508           break;
101509         }
101510         sqlite3VdbeChangeP2(v, addr, nCol);
101511         sqlite3VdbeChangeP4(v, addr, (char*)sqlite3KeyInfoRef(pKeyInfo),
101512                             P4_KEYINFO);
101513         pLoop->addrOpenEphm[i] = -1;
101514       }
101515     }
101516     sqlite3KeyInfoUnref(pKeyInfo);
101517   }
101518 
101519 multi_select_end:
101520   pDest->iSdst = dest.iSdst;
101521   pDest->nSdst = dest.nSdst;
101522   sqlite3SelectDelete(db, pDelete);
101523   return rc;
101524 }
101525 #endif /* SQLITE_OMIT_COMPOUND_SELECT */
101526 
101527 /*
101528 ** Code an output subroutine for a coroutine implementation of a
101529 ** SELECT statment.
101530 **
101531 ** The data to be output is contained in pIn->iSdst.  There are
101532 ** pIn->nSdst columns to be output.  pDest is where the output should
101533 ** be sent.
101534 **
101535 ** regReturn is the number of the register holding the subroutine
101536 ** return address.
101537 **
101538 ** If regPrev>0 then it is the first register in a vector that
101539 ** records the previous output.  mem[regPrev] is a flag that is false
101540 ** if there has been no previous output.  If regPrev>0 then code is
101541 ** generated to suppress duplicates.  pKeyInfo is used for comparing
101542 ** keys.
101543 **
101544 ** If the LIMIT found in p->iLimit is reached, jump immediately to
101545 ** iBreak.
101546 */
101547 static int generateOutputSubroutine(
101548   Parse *pParse,          /* Parsing context */
101549   Select *p,              /* The SELECT statement */
101550   SelectDest *pIn,        /* Coroutine supplying data */
101551   SelectDest *pDest,      /* Where to send the data */
101552   int regReturn,          /* The return address register */
101553   int regPrev,            /* Previous result register.  No uniqueness if 0 */
101554   KeyInfo *pKeyInfo,      /* For comparing with previous entry */
101555   int iBreak              /* Jump here if we hit the LIMIT */
101556 ){
101557   Vdbe *v = pParse->pVdbe;
101558   int iContinue;
101559   int addr;
101560 
101561   addr = sqlite3VdbeCurrentAddr(v);
101562   iContinue = sqlite3VdbeMakeLabel(v);
101563 
101564   /* Suppress duplicates for UNION, EXCEPT, and INTERSECT 
101565   */
101566   if( regPrev ){
101567     int j1, j2;
101568     j1 = sqlite3VdbeAddOp1(v, OP_IfNot, regPrev);
101569     j2 = sqlite3VdbeAddOp4(v, OP_Compare, pIn->iSdst, regPrev+1, pIn->nSdst,
101570                               (char*)sqlite3KeyInfoRef(pKeyInfo), P4_KEYINFO);
101571     sqlite3VdbeAddOp3(v, OP_Jump, j2+2, iContinue, j2+2);
101572     sqlite3VdbeJumpHere(v, j1);
101573     sqlite3VdbeAddOp3(v, OP_Copy, pIn->iSdst, regPrev+1, pIn->nSdst-1);
101574     sqlite3VdbeAddOp2(v, OP_Integer, 1, regPrev);
101575   }
101576   if( pParse->db->mallocFailed ) return 0;
101577 
101578   /* Suppress the first OFFSET entries if there is an OFFSET clause
101579   */
101580   codeOffset(v, p, iContinue);
101581 
101582   switch( pDest->eDest ){
101583     /* Store the result as data using a unique key.
101584     */
101585     case SRT_Table:
101586     case SRT_EphemTab: {
101587       int r1 = sqlite3GetTempReg(pParse);
101588       int r2 = sqlite3GetTempReg(pParse);
101589       testcase( pDest->eDest==SRT_Table );
101590       testcase( pDest->eDest==SRT_EphemTab );
101591       sqlite3VdbeAddOp3(v, OP_MakeRecord, pIn->iSdst, pIn->nSdst, r1);
101592       sqlite3VdbeAddOp2(v, OP_NewRowid, pDest->iSDParm, r2);
101593       sqlite3VdbeAddOp3(v, OP_Insert, pDest->iSDParm, r1, r2);
101594       sqlite3VdbeChangeP5(v, OPFLAG_APPEND);
101595       sqlite3ReleaseTempReg(pParse, r2);
101596       sqlite3ReleaseTempReg(pParse, r1);
101597       break;
101598     }
101599 
101600 #ifndef SQLITE_OMIT_SUBQUERY
101601     /* If we are creating a set for an "expr IN (SELECT ...)" construct,
101602     ** then there should be a single item on the stack.  Write this
101603     ** item into the set table with bogus data.
101604     */
101605     case SRT_Set: {
101606       int r1;
101607       assert( pIn->nSdst==1 );
101608       pDest->affSdst = 
101609          sqlite3CompareAffinity(p->pEList->a[0].pExpr, pDest->affSdst);
101610       r1 = sqlite3GetTempReg(pParse);
101611       sqlite3VdbeAddOp4(v, OP_MakeRecord, pIn->iSdst, 1, r1, &pDest->affSdst,1);
101612       sqlite3ExprCacheAffinityChange(pParse, pIn->iSdst, 1);
101613       sqlite3VdbeAddOp2(v, OP_IdxInsert, pDest->iSDParm, r1);
101614       sqlite3ReleaseTempReg(pParse, r1);
101615       break;
101616     }
101617 
101618 #if 0  /* Never occurs on an ORDER BY query */
101619     /* If any row exist in the result set, record that fact and abort.
101620     */
101621     case SRT_Exists: {
101622       sqlite3VdbeAddOp2(v, OP_Integer, 1, pDest->iSDParm);
101623       /* The LIMIT clause will terminate the loop for us */
101624       break;
101625     }
101626 #endif
101627 
101628     /* If this is a scalar select that is part of an expression, then
101629     ** store the results in the appropriate memory cell and break out
101630     ** of the scan loop.
101631     */
101632     case SRT_Mem: {
101633       assert( pIn->nSdst==1 );
101634       sqlite3ExprCodeMove(pParse, pIn->iSdst, pDest->iSDParm, 1);
101635       /* The LIMIT clause will jump out of the loop for us */
101636       break;
101637     }
101638 #endif /* #ifndef SQLITE_OMIT_SUBQUERY */
101639 
101640     /* The results are stored in a sequence of registers
101641     ** starting at pDest->iSdst.  Then the co-routine yields.
101642     */
101643     case SRT_Coroutine: {
101644       if( pDest->iSdst==0 ){
101645         pDest->iSdst = sqlite3GetTempRange(pParse, pIn->nSdst);
101646         pDest->nSdst = pIn->nSdst;
101647       }
101648       sqlite3ExprCodeMove(pParse, pIn->iSdst, pDest->iSdst, pDest->nSdst);
101649       sqlite3VdbeAddOp1(v, OP_Yield, pDest->iSDParm);
101650       break;
101651     }
101652 
101653     /* If none of the above, then the result destination must be
101654     ** SRT_Output.  This routine is never called with any other
101655     ** destination other than the ones handled above or SRT_Output.
101656     **
101657     ** For SRT_Output, results are stored in a sequence of registers.  
101658     ** Then the OP_ResultRow opcode is used to cause sqlite3_step() to
101659     ** return the next row of result.
101660     */
101661     default: {
101662       assert( pDest->eDest==SRT_Output );
101663       sqlite3VdbeAddOp2(v, OP_ResultRow, pIn->iSdst, pIn->nSdst);
101664       sqlite3ExprCacheAffinityChange(pParse, pIn->iSdst, pIn->nSdst);
101665       break;
101666     }
101667   }
101668 
101669   /* Jump to the end of the loop if the LIMIT is reached.
101670   */
101671   if( p->iLimit ){
101672     sqlite3VdbeAddOp3(v, OP_IfZero, p->iLimit, iBreak, -1);
101673   }
101674 
101675   /* Generate the subroutine return
101676   */
101677   sqlite3VdbeResolveLabel(v, iContinue);
101678   sqlite3VdbeAddOp1(v, OP_Return, regReturn);
101679 
101680   return addr;
101681 }
101682 
101683 /*
101684 ** Alternative compound select code generator for cases when there
101685 ** is an ORDER BY clause.
101686 **
101687 ** We assume a query of the following form:
101688 **
101689 **      <selectA>  <operator>  <selectB>  ORDER BY <orderbylist>
101690 **
101691 ** <operator> is one of UNION ALL, UNION, EXCEPT, or INTERSECT.  The idea
101692 ** is to code both <selectA> and <selectB> with the ORDER BY clause as
101693 ** co-routines.  Then run the co-routines in parallel and merge the results
101694 ** into the output.  In addition to the two coroutines (called selectA and
101695 ** selectB) there are 7 subroutines:
101696 **
101697 **    outA:    Move the output of the selectA coroutine into the output
101698 **             of the compound query.
101699 **
101700 **    outB:    Move the output of the selectB coroutine into the output
101701 **             of the compound query.  (Only generated for UNION and
101702 **             UNION ALL.  EXCEPT and INSERTSECT never output a row that
101703 **             appears only in B.)
101704 **
101705 **    AltB:    Called when there is data from both coroutines and A<B.
101706 **
101707 **    AeqB:    Called when there is data from both coroutines and A==B.
101708 **
101709 **    AgtB:    Called when there is data from both coroutines and A>B.
101710 **
101711 **    EofA:    Called when data is exhausted from selectA.
101712 **
101713 **    EofB:    Called when data is exhausted from selectB.
101714 **
101715 ** The implementation of the latter five subroutines depend on which 
101716 ** <operator> is used:
101717 **
101718 **
101719 **             UNION ALL         UNION            EXCEPT          INTERSECT
101720 **          -------------  -----------------  --------------  -----------------
101721 **   AltB:   outA, nextA      outA, nextA       outA, nextA         nextA
101722 **
101723 **   AeqB:   outA, nextA         nextA             nextA         outA, nextA
101724 **
101725 **   AgtB:   outB, nextB      outB, nextB          nextB            nextB
101726 **
101727 **   EofA:   outB, nextB      outB, nextB          halt             halt
101728 **
101729 **   EofB:   outA, nextA      outA, nextA       outA, nextA         halt
101730 **
101731 ** In the AltB, AeqB, and AgtB subroutines, an EOF on A following nextA
101732 ** causes an immediate jump to EofA and an EOF on B following nextB causes
101733 ** an immediate jump to EofB.  Within EofA and EofB, and EOF on entry or
101734 ** following nextX causes a jump to the end of the select processing.
101735 **
101736 ** Duplicate removal in the UNION, EXCEPT, and INTERSECT cases is handled
101737 ** within the output subroutine.  The regPrev register set holds the previously
101738 ** output value.  A comparison is made against this value and the output
101739 ** is skipped if the next results would be the same as the previous.
101740 **
101741 ** The implementation plan is to implement the two coroutines and seven
101742 ** subroutines first, then put the control logic at the bottom.  Like this:
101743 **
101744 **          goto Init
101745 **     coA: coroutine for left query (A)
101746 **     coB: coroutine for right query (B)
101747 **    outA: output one row of A
101748 **    outB: output one row of B (UNION and UNION ALL only)
101749 **    EofA: ...
101750 **    EofB: ...
101751 **    AltB: ...
101752 **    AeqB: ...
101753 **    AgtB: ...
101754 **    Init: initialize coroutine registers
101755 **          yield coA
101756 **          if eof(A) goto EofA
101757 **          yield coB
101758 **          if eof(B) goto EofB
101759 **    Cmpr: Compare A, B
101760 **          Jump AltB, AeqB, AgtB
101761 **     End: ...
101762 **
101763 ** We call AltB, AeqB, AgtB, EofA, and EofB "subroutines" but they are not
101764 ** actually called using Gosub and they do not Return.  EofA and EofB loop
101765 ** until all data is exhausted then jump to the "end" labe.  AltB, AeqB,
101766 ** and AgtB jump to either L2 or to one of EofA or EofB.
101767 */
101768 #ifndef SQLITE_OMIT_COMPOUND_SELECT
101769 static int multiSelectOrderBy(
101770   Parse *pParse,        /* Parsing context */
101771   Select *p,            /* The right-most of SELECTs to be coded */
101772   SelectDest *pDest     /* What to do with query results */
101773 ){
101774   int i, j;             /* Loop counters */
101775   Select *pPrior;       /* Another SELECT immediately to our left */
101776   Vdbe *v;              /* Generate code to this VDBE */
101777   SelectDest destA;     /* Destination for coroutine A */
101778   SelectDest destB;     /* Destination for coroutine B */
101779   int regAddrA;         /* Address register for select-A coroutine */
101780   int regEofA;          /* Flag to indicate when select-A is complete */
101781   int regAddrB;         /* Address register for select-B coroutine */
101782   int regEofB;          /* Flag to indicate when select-B is complete */
101783   int addrSelectA;      /* Address of the select-A coroutine */
101784   int addrSelectB;      /* Address of the select-B coroutine */
101785   int regOutA;          /* Address register for the output-A subroutine */
101786   int regOutB;          /* Address register for the output-B subroutine */
101787   int addrOutA;         /* Address of the output-A subroutine */
101788   int addrOutB = 0;     /* Address of the output-B subroutine */
101789   int addrEofA;         /* Address of the select-A-exhausted subroutine */
101790   int addrEofB;         /* Address of the select-B-exhausted subroutine */
101791   int addrAltB;         /* Address of the A<B subroutine */
101792   int addrAeqB;         /* Address of the A==B subroutine */
101793   int addrAgtB;         /* Address of the A>B subroutine */
101794   int regLimitA;        /* Limit register for select-A */
101795   int regLimitB;        /* Limit register for select-A */
101796   int regPrev;          /* A range of registers to hold previous output */
101797   int savedLimit;       /* Saved value of p->iLimit */
101798   int savedOffset;      /* Saved value of p->iOffset */
101799   int labelCmpr;        /* Label for the start of the merge algorithm */
101800   int labelEnd;         /* Label for the end of the overall SELECT stmt */
101801   int j1;               /* Jump instructions that get retargetted */
101802   int op;               /* One of TK_ALL, TK_UNION, TK_EXCEPT, TK_INTERSECT */
101803   KeyInfo *pKeyDup = 0; /* Comparison information for duplicate removal */
101804   KeyInfo *pKeyMerge;   /* Comparison information for merging rows */
101805   sqlite3 *db;          /* Database connection */
101806   ExprList *pOrderBy;   /* The ORDER BY clause */
101807   int nOrderBy;         /* Number of terms in the ORDER BY clause */
101808   int *aPermute;        /* Mapping from ORDER BY terms to result set columns */
101809 #ifndef SQLITE_OMIT_EXPLAIN
101810   int iSub1;            /* EQP id of left-hand query */
101811   int iSub2;            /* EQP id of right-hand query */
101812 #endif
101813 
101814   assert( p->pOrderBy!=0 );
101815   assert( pKeyDup==0 ); /* "Managed" code needs this.  Ticket #3382. */
101816   db = pParse->db;
101817   v = pParse->pVdbe;
101818   assert( v!=0 );       /* Already thrown the error if VDBE alloc failed */
101819   labelEnd = sqlite3VdbeMakeLabel(v);
101820   labelCmpr = sqlite3VdbeMakeLabel(v);
101821 
101822 
101823   /* Patch up the ORDER BY clause
101824   */
101825   op = p->op;  
101826   pPrior = p->pPrior;
101827   assert( pPrior->pOrderBy==0 );
101828   pOrderBy = p->pOrderBy;
101829   assert( pOrderBy );
101830   nOrderBy = pOrderBy->nExpr;
101831 
101832   /* For operators other than UNION ALL we have to make sure that
101833   ** the ORDER BY clause covers every term of the result set.  Add
101834   ** terms to the ORDER BY clause as necessary.
101835   */
101836   if( op!=TK_ALL ){
101837     for(i=1; db->mallocFailed==0 && i<=p->pEList->nExpr; i++){
101838       struct ExprList_item *pItem;
101839       for(j=0, pItem=pOrderBy->a; j<nOrderBy; j++, pItem++){
101840         assert( pItem->u.x.iOrderByCol>0 );
101841         if( pItem->u.x.iOrderByCol==i ) break;
101842       }
101843       if( j==nOrderBy ){
101844         Expr *pNew = sqlite3Expr(db, TK_INTEGER, 0);
101845         if( pNew==0 ) return SQLITE_NOMEM;
101846         pNew->flags |= EP_IntValue;
101847         pNew->u.iValue = i;
101848         pOrderBy = sqlite3ExprListAppend(pParse, pOrderBy, pNew);
101849         if( pOrderBy ) pOrderBy->a[nOrderBy++].u.x.iOrderByCol = (u16)i;
101850       }
101851     }
101852   }
101853 
101854   /* Compute the comparison permutation and keyinfo that is used with
101855   ** the permutation used to determine if the next
101856   ** row of results comes from selectA or selectB.  Also add explicit
101857   ** collations to the ORDER BY clause terms so that when the subqueries
101858   ** to the right and the left are evaluated, they use the correct
101859   ** collation.
101860   */
101861   aPermute = sqlite3DbMallocRaw(db, sizeof(int)*nOrderBy);
101862   if( aPermute ){
101863     struct ExprList_item *pItem;
101864     for(i=0, pItem=pOrderBy->a; i<nOrderBy; i++, pItem++){
101865       assert( pItem->u.x.iOrderByCol>0
101866           && pItem->u.x.iOrderByCol<=p->pEList->nExpr );
101867       aPermute[i] = pItem->u.x.iOrderByCol - 1;
101868     }
101869     pKeyMerge = sqlite3KeyInfoAlloc(db, nOrderBy, 1);
101870     if( pKeyMerge ){
101871       for(i=0; i<nOrderBy; i++){
101872         CollSeq *pColl;
101873         Expr *pTerm = pOrderBy->a[i].pExpr;
101874         if( pTerm->flags & EP_Collate ){
101875           pColl = sqlite3ExprCollSeq(pParse, pTerm);
101876         }else{
101877           pColl = multiSelectCollSeq(pParse, p, aPermute[i]);
101878           if( pColl==0 ) pColl = db->pDfltColl;
101879           pOrderBy->a[i].pExpr =
101880              sqlite3ExprAddCollateString(pParse, pTerm, pColl->zName);
101881         }
101882         assert( sqlite3KeyInfoIsWriteable(pKeyMerge) );
101883         pKeyMerge->aColl[i] = pColl;
101884         pKeyMerge->aSortOrder[i] = pOrderBy->a[i].sortOrder;
101885       }
101886     }
101887   }else{
101888     pKeyMerge = 0;
101889   }
101890 
101891   /* Reattach the ORDER BY clause to the query.
101892   */
101893   p->pOrderBy = pOrderBy;
101894   pPrior->pOrderBy = sqlite3ExprListDup(pParse->db, pOrderBy, 0);
101895 
101896   /* Allocate a range of temporary registers and the KeyInfo needed
101897   ** for the logic that removes duplicate result rows when the
101898   ** operator is UNION, EXCEPT, or INTERSECT (but not UNION ALL).
101899   */
101900   if( op==TK_ALL ){
101901     regPrev = 0;
101902   }else{
101903     int nExpr = p->pEList->nExpr;
101904     assert( nOrderBy>=nExpr || db->mallocFailed );
101905     regPrev = pParse->nMem+1;
101906     pParse->nMem += nExpr+1;
101907     sqlite3VdbeAddOp2(v, OP_Integer, 0, regPrev);
101908     pKeyDup = sqlite3KeyInfoAlloc(db, nExpr, 1);
101909     if( pKeyDup ){
101910       assert( sqlite3KeyInfoIsWriteable(pKeyDup) );
101911       for(i=0; i<nExpr; i++){
101912         pKeyDup->aColl[i] = multiSelectCollSeq(pParse, p, i);
101913         pKeyDup->aSortOrder[i] = 0;
101914       }
101915     }
101916   }
101917  
101918   /* Separate the left and the right query from one another
101919   */
101920   p->pPrior = 0;
101921   sqlite3ResolveOrderGroupBy(pParse, p, p->pOrderBy, "ORDER");
101922   if( pPrior->pPrior==0 ){
101923     sqlite3ResolveOrderGroupBy(pParse, pPrior, pPrior->pOrderBy, "ORDER");
101924   }
101925 
101926   /* Compute the limit registers */
101927   computeLimitRegisters(pParse, p, labelEnd);
101928   if( p->iLimit && op==TK_ALL ){
101929     regLimitA = ++pParse->nMem;
101930     regLimitB = ++pParse->nMem;
101931     sqlite3VdbeAddOp2(v, OP_Copy, p->iOffset ? p->iOffset+1 : p->iLimit,
101932                                   regLimitA);
101933     sqlite3VdbeAddOp2(v, OP_Copy, regLimitA, regLimitB);
101934   }else{
101935     regLimitA = regLimitB = 0;
101936   }
101937   sqlite3ExprDelete(db, p->pLimit);
101938   p->pLimit = 0;
101939   sqlite3ExprDelete(db, p->pOffset);
101940   p->pOffset = 0;
101941 
101942   regAddrA = ++pParse->nMem;
101943   regEofA = ++pParse->nMem;
101944   regAddrB = ++pParse->nMem;
101945   regEofB = ++pParse->nMem;
101946   regOutA = ++pParse->nMem;
101947   regOutB = ++pParse->nMem;
101948   sqlite3SelectDestInit(&destA, SRT_Coroutine, regAddrA);
101949   sqlite3SelectDestInit(&destB, SRT_Coroutine, regAddrB);
101950 
101951   /* Jump past the various subroutines and coroutines to the main
101952   ** merge loop
101953   */
101954   j1 = sqlite3VdbeAddOp0(v, OP_Goto);
101955   addrSelectA = sqlite3VdbeCurrentAddr(v);
101956 
101957 
101958   /* Generate a coroutine to evaluate the SELECT statement to the
101959   ** left of the compound operator - the "A" select.
101960   */
101961   VdbeNoopComment((v, "Begin coroutine for left SELECT"));
101962   pPrior->iLimit = regLimitA;
101963   explainSetInteger(iSub1, pParse->iNextSelectId);
101964   sqlite3Select(pParse, pPrior, &destA);
101965   sqlite3VdbeAddOp2(v, OP_Integer, 1, regEofA);
101966   sqlite3VdbeAddOp1(v, OP_Yield, regAddrA);
101967   VdbeNoopComment((v, "End coroutine for left SELECT"));
101968 
101969   /* Generate a coroutine to evaluate the SELECT statement on 
101970   ** the right - the "B" select
101971   */
101972   addrSelectB = sqlite3VdbeCurrentAddr(v);
101973   VdbeNoopComment((v, "Begin coroutine for right SELECT"));
101974   savedLimit = p->iLimit;
101975   savedOffset = p->iOffset;
101976   p->iLimit = regLimitB;
101977   p->iOffset = 0;  
101978   explainSetInteger(iSub2, pParse->iNextSelectId);
101979   sqlite3Select(pParse, p, &destB);
101980   p->iLimit = savedLimit;
101981   p->iOffset = savedOffset;
101982   sqlite3VdbeAddOp2(v, OP_Integer, 1, regEofB);
101983   sqlite3VdbeAddOp1(v, OP_Yield, regAddrB);
101984   VdbeNoopComment((v, "End coroutine for right SELECT"));
101985 
101986   /* Generate a subroutine that outputs the current row of the A
101987   ** select as the next output row of the compound select.
101988   */
101989   VdbeNoopComment((v, "Output routine for A"));
101990   addrOutA = generateOutputSubroutine(pParse,
101991                  p, &destA, pDest, regOutA,
101992                  regPrev, pKeyDup, labelEnd);
101993   
101994   /* Generate a subroutine that outputs the current row of the B
101995   ** select as the next output row of the compound select.
101996   */
101997   if( op==TK_ALL || op==TK_UNION ){
101998     VdbeNoopComment((v, "Output routine for B"));
101999     addrOutB = generateOutputSubroutine(pParse,
102000                  p, &destB, pDest, regOutB,
102001                  regPrev, pKeyDup, labelEnd);
102002   }
102003   sqlite3KeyInfoUnref(pKeyDup);
102004 
102005   /* Generate a subroutine to run when the results from select A
102006   ** are exhausted and only data in select B remains.
102007   */
102008   VdbeNoopComment((v, "eof-A subroutine"));
102009   if( op==TK_EXCEPT || op==TK_INTERSECT ){
102010     addrEofA = sqlite3VdbeAddOp2(v, OP_Goto, 0, labelEnd);
102011   }else{  
102012     addrEofA = sqlite3VdbeAddOp2(v, OP_If, regEofB, labelEnd);
102013     sqlite3VdbeAddOp2(v, OP_Gosub, regOutB, addrOutB);
102014     sqlite3VdbeAddOp1(v, OP_Yield, regAddrB);
102015     sqlite3VdbeAddOp2(v, OP_Goto, 0, addrEofA);
102016     p->nSelectRow += pPrior->nSelectRow;
102017   }
102018 
102019   /* Generate a subroutine to run when the results from select B
102020   ** are exhausted and only data in select A remains.
102021   */
102022   if( op==TK_INTERSECT ){
102023     addrEofB = addrEofA;
102024     if( p->nSelectRow > pPrior->nSelectRow ) p->nSelectRow = pPrior->nSelectRow;
102025   }else{  
102026     VdbeNoopComment((v, "eof-B subroutine"));
102027     addrEofB = sqlite3VdbeAddOp2(v, OP_If, regEofA, labelEnd);
102028     sqlite3VdbeAddOp2(v, OP_Gosub, regOutA, addrOutA);
102029     sqlite3VdbeAddOp1(v, OP_Yield, regAddrA);
102030     sqlite3VdbeAddOp2(v, OP_Goto, 0, addrEofB);
102031   }
102032 
102033   /* Generate code to handle the case of A<B
102034   */
102035   VdbeNoopComment((v, "A-lt-B subroutine"));
102036   addrAltB = sqlite3VdbeAddOp2(v, OP_Gosub, regOutA, addrOutA);
102037   sqlite3VdbeAddOp1(v, OP_Yield, regAddrA);
102038   sqlite3VdbeAddOp2(v, OP_If, regEofA, addrEofA);
102039   sqlite3VdbeAddOp2(v, OP_Goto, 0, labelCmpr);
102040 
102041   /* Generate code to handle the case of A==B
102042   */
102043   if( op==TK_ALL ){
102044     addrAeqB = addrAltB;
102045   }else if( op==TK_INTERSECT ){
102046     addrAeqB = addrAltB;
102047     addrAltB++;
102048   }else{
102049     VdbeNoopComment((v, "A-eq-B subroutine"));
102050     addrAeqB =
102051     sqlite3VdbeAddOp1(v, OP_Yield, regAddrA);
102052     sqlite3VdbeAddOp2(v, OP_If, regEofA, addrEofA);
102053     sqlite3VdbeAddOp2(v, OP_Goto, 0, labelCmpr);
102054   }
102055 
102056   /* Generate code to handle the case of A>B
102057   */
102058   VdbeNoopComment((v, "A-gt-B subroutine"));
102059   addrAgtB = sqlite3VdbeCurrentAddr(v);
102060   if( op==TK_ALL || op==TK_UNION ){
102061     sqlite3VdbeAddOp2(v, OP_Gosub, regOutB, addrOutB);
102062   }
102063   sqlite3VdbeAddOp1(v, OP_Yield, regAddrB);
102064   sqlite3VdbeAddOp2(v, OP_If, regEofB, addrEofB);
102065   sqlite3VdbeAddOp2(v, OP_Goto, 0, labelCmpr);
102066 
102067   /* This code runs once to initialize everything.
102068   */
102069   sqlite3VdbeJumpHere(v, j1);
102070   sqlite3VdbeAddOp2(v, OP_Integer, 0, regEofA);
102071   sqlite3VdbeAddOp2(v, OP_Integer, 0, regEofB);
102072   sqlite3VdbeAddOp2(v, OP_Gosub, regAddrA, addrSelectA);
102073   sqlite3VdbeAddOp2(v, OP_Gosub, regAddrB, addrSelectB);
102074   sqlite3VdbeAddOp2(v, OP_If, regEofA, addrEofA);
102075   sqlite3VdbeAddOp2(v, OP_If, regEofB, addrEofB);
102076 
102077   /* Implement the main merge loop
102078   */
102079   sqlite3VdbeResolveLabel(v, labelCmpr);
102080   sqlite3VdbeAddOp4(v, OP_Permutation, 0, 0, 0, (char*)aPermute, P4_INTARRAY);
102081   sqlite3VdbeAddOp4(v, OP_Compare, destA.iSdst, destB.iSdst, nOrderBy,
102082                          (char*)pKeyMerge, P4_KEYINFO);
102083   sqlite3VdbeChangeP5(v, OPFLAG_PERMUTE);
102084   sqlite3VdbeAddOp3(v, OP_Jump, addrAltB, addrAeqB, addrAgtB);
102085 
102086   /* Jump to the this point in order to terminate the query.
102087   */
102088   sqlite3VdbeResolveLabel(v, labelEnd);
102089 
102090   /* Set the number of output columns
102091   */
102092   if( pDest->eDest==SRT_Output ){
102093     Select *pFirst = pPrior;
102094     while( pFirst->pPrior ) pFirst = pFirst->pPrior;
102095     generateColumnNames(pParse, 0, pFirst->pEList);
102096   }
102097 
102098   /* Reassembly the compound query so that it will be freed correctly
102099   ** by the calling function */
102100   if( p->pPrior ){
102101     sqlite3SelectDelete(db, p->pPrior);
102102   }
102103   p->pPrior = pPrior;
102104 
102105   /*** TBD:  Insert subroutine calls to close cursors on incomplete
102106   **** subqueries ****/
102107   explainComposite(pParse, p->op, iSub1, iSub2, 0);
102108   return SQLITE_OK;
102109 }
102110 #endif
102111 
102112 #if !defined(SQLITE_OMIT_SUBQUERY) || !defined(SQLITE_OMIT_VIEW)
102113 /* Forward Declarations */
102114 static void substExprList(sqlite3*, ExprList*, int, ExprList*);
102115 static void substSelect(sqlite3*, Select *, int, ExprList *);
102116 
102117 /*
102118 ** Scan through the expression pExpr.  Replace every reference to
102119 ** a column in table number iTable with a copy of the iColumn-th
102120 ** entry in pEList.  (But leave references to the ROWID column 
102121 ** unchanged.)
102122 **
102123 ** This routine is part of the flattening procedure.  A subquery
102124 ** whose result set is defined by pEList appears as entry in the
102125 ** FROM clause of a SELECT such that the VDBE cursor assigned to that
102126 ** FORM clause entry is iTable.  This routine make the necessary 
102127 ** changes to pExpr so that it refers directly to the source table
102128 ** of the subquery rather the result set of the subquery.
102129 */
102130 static Expr *substExpr(
102131   sqlite3 *db,        /* Report malloc errors to this connection */
102132   Expr *pExpr,        /* Expr in which substitution occurs */
102133   int iTable,         /* Table to be substituted */
102134   ExprList *pEList    /* Substitute expressions */
102135 ){
102136   if( pExpr==0 ) return 0;
102137   if( pExpr->op==TK_COLUMN && pExpr->iTable==iTable ){
102138     if( pExpr->iColumn<0 ){
102139       pExpr->op = TK_NULL;
102140     }else{
102141       Expr *pNew;
102142       assert( pEList!=0 && pExpr->iColumn<pEList->nExpr );
102143       assert( pExpr->pLeft==0 && pExpr->pRight==0 );
102144       pNew = sqlite3ExprDup(db, pEList->a[pExpr->iColumn].pExpr, 0);
102145       sqlite3ExprDelete(db, pExpr);
102146       pExpr = pNew;
102147     }
102148   }else{
102149     pExpr->pLeft = substExpr(db, pExpr->pLeft, iTable, pEList);
102150     pExpr->pRight = substExpr(db, pExpr->pRight, iTable, pEList);
102151     if( ExprHasProperty(pExpr, EP_xIsSelect) ){
102152       substSelect(db, pExpr->x.pSelect, iTable, pEList);
102153     }else{
102154       substExprList(db, pExpr->x.pList, iTable, pEList);
102155     }
102156   }
102157   return pExpr;
102158 }
102159 static void substExprList(
102160   sqlite3 *db,         /* Report malloc errors here */
102161   ExprList *pList,     /* List to scan and in which to make substitutes */
102162   int iTable,          /* Table to be substituted */
102163   ExprList *pEList     /* Substitute values */
102164 ){
102165   int i;
102166   if( pList==0 ) return;
102167   for(i=0; i<pList->nExpr; i++){
102168     pList->a[i].pExpr = substExpr(db, pList->a[i].pExpr, iTable, pEList);
102169   }
102170 }
102171 static void substSelect(
102172   sqlite3 *db,         /* Report malloc errors here */
102173   Select *p,           /* SELECT statement in which to make substitutions */
102174   int iTable,          /* Table to be replaced */
102175   ExprList *pEList     /* Substitute values */
102176 ){
102177   SrcList *pSrc;
102178   struct SrcList_item *pItem;
102179   int i;
102180   if( !p ) return;
102181   substExprList(db, p->pEList, iTable, pEList);
102182   substExprList(db, p->pGroupBy, iTable, pEList);
102183   substExprList(db, p->pOrderBy, iTable, pEList);
102184   p->pHaving = substExpr(db, p->pHaving, iTable, pEList);
102185   p->pWhere = substExpr(db, p->pWhere, iTable, pEList);
102186   substSelect(db, p->pPrior, iTable, pEList);
102187   pSrc = p->pSrc;
102188   assert( pSrc );  /* Even for (SELECT 1) we have: pSrc!=0 but pSrc->nSrc==0 */
102189   if( ALWAYS(pSrc) ){
102190     for(i=pSrc->nSrc, pItem=pSrc->a; i>0; i--, pItem++){
102191       substSelect(db, pItem->pSelect, iTable, pEList);
102192     }
102193   }
102194 }
102195 #endif /* !defined(SQLITE_OMIT_SUBQUERY) || !defined(SQLITE_OMIT_VIEW) */
102196 
102197 #if !defined(SQLITE_OMIT_SUBQUERY) || !defined(SQLITE_OMIT_VIEW)
102198 /*
102199 ** This routine attempts to flatten subqueries as a performance optimization.
102200 ** This routine returns 1 if it makes changes and 0 if no flattening occurs.
102201 **
102202 ** To understand the concept of flattening, consider the following
102203 ** query:
102204 **
102205 **     SELECT a FROM (SELECT x+y AS a FROM t1 WHERE z<100) WHERE a>5
102206 **
102207 ** The default way of implementing this query is to execute the
102208 ** subquery first and store the results in a temporary table, then
102209 ** run the outer query on that temporary table.  This requires two
102210 ** passes over the data.  Furthermore, because the temporary table
102211 ** has no indices, the WHERE clause on the outer query cannot be
102212 ** optimized.
102213 **
102214 ** This routine attempts to rewrite queries such as the above into
102215 ** a single flat select, like this:
102216 **
102217 **     SELECT x+y AS a FROM t1 WHERE z<100 AND a>5
102218 **
102219 ** The code generated for this simpification gives the same result
102220 ** but only has to scan the data once.  And because indices might 
102221 ** exist on the table t1, a complete scan of the data might be
102222 ** avoided.
102223 **
102224 ** Flattening is only attempted if all of the following are true:
102225 **
102226 **   (1)  The subquery and the outer query do not both use aggregates.
102227 **
102228 **   (2)  The subquery is not an aggregate or the outer query is not a join.
102229 **
102230 **   (3)  The subquery is not the right operand of a left outer join
102231 **        (Originally ticket #306.  Strengthened by ticket #3300)
102232 **
102233 **   (4)  The subquery is not DISTINCT.
102234 **
102235 **  (**)  At one point restrictions (4) and (5) defined a subset of DISTINCT
102236 **        sub-queries that were excluded from this optimization. Restriction 
102237 **        (4) has since been expanded to exclude all DISTINCT subqueries.
102238 **
102239 **   (6)  The subquery does not use aggregates or the outer query is not
102240 **        DISTINCT.
102241 **
102242 **   (7)  The subquery has a FROM clause.  TODO:  For subqueries without
102243 **        A FROM clause, consider adding a FROM close with the special
102244 **        table sqlite_once that consists of a single row containing a
102245 **        single NULL.
102246 **
102247 **   (8)  The subquery does not use LIMIT or the outer query is not a join.
102248 **
102249 **   (9)  The subquery does not use LIMIT or the outer query does not use
102250 **        aggregates.
102251 **
102252 **  (10)  The subquery does not use aggregates or the outer query does not
102253 **        use LIMIT.
102254 **
102255 **  (11)  The subquery and the outer query do not both have ORDER BY clauses.
102256 **
102257 **  (**)  Not implemented.  Subsumed into restriction (3).  Was previously
102258 **        a separate restriction deriving from ticket #350.
102259 **
102260 **  (13)  The subquery and outer query do not both use LIMIT.
102261 **
102262 **  (14)  The subquery does not use OFFSET.
102263 **
102264 **  (15)  The outer query is not part of a compound select or the
102265 **        subquery does not have a LIMIT clause.
102266 **        (See ticket #2339 and ticket [02a8e81d44]).
102267 **
102268 **  (16)  The outer query is not an aggregate or the subquery does
102269 **        not contain ORDER BY.  (Ticket #2942)  This used to not matter
102270 **        until we introduced the group_concat() function.  
102271 **
102272 **  (17)  The sub-query is not a compound select, or it is a UNION ALL 
102273 **        compound clause made up entirely of non-aggregate queries, and 
102274 **        the parent query:
102275 **
102276 **          * is not itself part of a compound select,
102277 **          * is not an aggregate or DISTINCT query, and
102278 **          * is not a join
102279 **
102280 **        The parent and sub-query may contain WHERE clauses. Subject to
102281 **        rules (11), (13) and (14), they may also contain ORDER BY,
102282 **        LIMIT and OFFSET clauses.  The subquery cannot use any compound
102283 **        operator other than UNION ALL because all the other compound
102284 **        operators have an implied DISTINCT which is disallowed by
102285 **        restriction (4).
102286 **
102287 **        Also, each component of the sub-query must return the same number
102288 **        of result columns. This is actually a requirement for any compound
102289 **        SELECT statement, but all the code here does is make sure that no
102290 **        such (illegal) sub-query is flattened. The caller will detect the
102291 **        syntax error and return a detailed message.
102292 **
102293 **  (18)  If the sub-query is a compound select, then all terms of the
102294 **        ORDER by clause of the parent must be simple references to 
102295 **        columns of the sub-query.
102296 **
102297 **  (19)  The subquery does not use LIMIT or the outer query does not
102298 **        have a WHERE clause.
102299 **
102300 **  (20)  If the sub-query is a compound select, then it must not use
102301 **        an ORDER BY clause.  Ticket #3773.  We could relax this constraint
102302 **        somewhat by saying that the terms of the ORDER BY clause must
102303 **        appear as unmodified result columns in the outer query.  But we
102304 **        have other optimizations in mind to deal with that case.
102305 **
102306 **  (21)  The subquery does not use LIMIT or the outer query is not
102307 **        DISTINCT.  (See ticket [752e1646fc]).
102308 **
102309 ** In this routine, the "p" parameter is a pointer to the outer query.
102310 ** The subquery is p->pSrc->a[iFrom].  isAgg is true if the outer query
102311 ** uses aggregates and subqueryIsAgg is true if the subquery uses aggregates.
102312 **
102313 ** If flattening is not attempted, this routine is a no-op and returns 0.
102314 ** If flattening is attempted this routine returns 1.
102315 **
102316 ** All of the expression analysis must occur on both the outer query and
102317 ** the subquery before this routine runs.
102318 */
102319 static int flattenSubquery(
102320   Parse *pParse,       /* Parsing context */
102321   Select *p,           /* The parent or outer SELECT statement */
102322   int iFrom,           /* Index in p->pSrc->a[] of the inner subquery */
102323   int isAgg,           /* True if outer SELECT uses aggregate functions */
102324   int subqueryIsAgg    /* True if the subquery uses aggregate functions */
102325 ){
102326   const char *zSavedAuthContext = pParse->zAuthContext;
102327   Select *pParent;
102328   Select *pSub;       /* The inner query or "subquery" */
102329   Select *pSub1;      /* Pointer to the rightmost select in sub-query */
102330   SrcList *pSrc;      /* The FROM clause of the outer query */
102331   SrcList *pSubSrc;   /* The FROM clause of the subquery */
102332   ExprList *pList;    /* The result set of the outer query */
102333   int iParent;        /* VDBE cursor number of the pSub result set temp table */
102334   int i;              /* Loop counter */
102335   Expr *pWhere;                    /* The WHERE clause */
102336   struct SrcList_item *pSubitem;   /* The subquery */
102337   sqlite3 *db = pParse->db;
102338 
102339   /* Check to see if flattening is permitted.  Return 0 if not.
102340   */
102341   assert( p!=0 );
102342   assert( p->pPrior==0 );  /* Unable to flatten compound queries */
102343   if( OptimizationDisabled(db, SQLITE_QueryFlattener) ) return 0;
102344   pSrc = p->pSrc;
102345   assert( pSrc && iFrom>=0 && iFrom<pSrc->nSrc );
102346   pSubitem = &pSrc->a[iFrom];
102347   iParent = pSubitem->iCursor;
102348   pSub = pSubitem->pSelect;
102349   assert( pSub!=0 );
102350   if( isAgg && subqueryIsAgg ) return 0;                 /* Restriction (1)  */
102351   if( subqueryIsAgg && pSrc->nSrc>1 ) return 0;          /* Restriction (2)  */
102352   pSubSrc = pSub->pSrc;
102353   assert( pSubSrc );
102354   /* Prior to version 3.1.2, when LIMIT and OFFSET had to be simple constants,
102355   ** not arbitrary expresssions, we allowed some combining of LIMIT and OFFSET
102356   ** because they could be computed at compile-time.  But when LIMIT and OFFSET
102357   ** became arbitrary expressions, we were forced to add restrictions (13)
102358   ** and (14). */
102359   if( pSub->pLimit && p->pLimit ) return 0;              /* Restriction (13) */
102360   if( pSub->pOffset ) return 0;                          /* Restriction (14) */
102361   if( p->pRightmost && pSub->pLimit ){
102362     return 0;                                            /* Restriction (15) */
102363   }
102364   if( pSubSrc->nSrc==0 ) return 0;                       /* Restriction (7)  */
102365   if( pSub->selFlags & SF_Distinct ) return 0;           /* Restriction (5)  */
102366   if( pSub->pLimit && (pSrc->nSrc>1 || isAgg) ){
102367      return 0;         /* Restrictions (8)(9) */
102368   }
102369   if( (p->selFlags & SF_Distinct)!=0 && subqueryIsAgg ){
102370      return 0;         /* Restriction (6)  */
102371   }
102372   if( p->pOrderBy && pSub->pOrderBy ){
102373      return 0;                                           /* Restriction (11) */
102374   }
102375   if( isAgg && pSub->pOrderBy ) return 0;                /* Restriction (16) */
102376   if( pSub->pLimit && p->pWhere ) return 0;              /* Restriction (19) */
102377   if( pSub->pLimit && (p->selFlags & SF_Distinct)!=0 ){
102378      return 0;         /* Restriction (21) */
102379   }
102380 
102381   /* OBSOLETE COMMENT 1:
102382   ** Restriction 3:  If the subquery is a join, make sure the subquery is 
102383   ** not used as the right operand of an outer join.  Examples of why this
102384   ** is not allowed:
102385   **
102386   **         t1 LEFT OUTER JOIN (t2 JOIN t3)
102387   **
102388   ** If we flatten the above, we would get
102389   **
102390   **         (t1 LEFT OUTER JOIN t2) JOIN t3
102391   **
102392   ** which is not at all the same thing.
102393   **
102394   ** OBSOLETE COMMENT 2:
102395   ** Restriction 12:  If the subquery is the right operand of a left outer
102396   ** join, make sure the subquery has no WHERE clause.
102397   ** An examples of why this is not allowed:
102398   **
102399   **         t1 LEFT OUTER JOIN (SELECT * FROM t2 WHERE t2.x>0)
102400   **
102401   ** If we flatten the above, we would get
102402   **
102403   **         (t1 LEFT OUTER JOIN t2) WHERE t2.x>0
102404   **
102405   ** But the t2.x>0 test will always fail on a NULL row of t2, which
102406   ** effectively converts the OUTER JOIN into an INNER JOIN.
102407   **
102408   ** THIS OVERRIDES OBSOLETE COMMENTS 1 AND 2 ABOVE:
102409   ** Ticket #3300 shows that flattening the right term of a LEFT JOIN
102410   ** is fraught with danger.  Best to avoid the whole thing.  If the
102411   ** subquery is the right term of a LEFT JOIN, then do not flatten.
102412   */
102413   if( (pSubitem->jointype & JT_OUTER)!=0 ){
102414     return 0;
102415   }
102416 
102417   /* Restriction 17: If the sub-query is a compound SELECT, then it must
102418   ** use only the UNION ALL operator. And none of the simple select queries
102419   ** that make up the compound SELECT are allowed to be aggregate or distinct
102420   ** queries.
102421   */
102422   if( pSub->pPrior ){
102423     if( pSub->pOrderBy ){
102424       return 0;  /* Restriction 20 */
102425     }
102426     if( isAgg || (p->selFlags & SF_Distinct)!=0 || pSrc->nSrc!=1 ){
102427       return 0;
102428     }
102429     for(pSub1=pSub; pSub1; pSub1=pSub1->pPrior){
102430       testcase( (pSub1->selFlags & (SF_Distinct|SF_Aggregate))==SF_Distinct );
102431       testcase( (pSub1->selFlags & (SF_Distinct|SF_Aggregate))==SF_Aggregate );
102432       assert( pSub->pSrc!=0 );
102433       if( (pSub1->selFlags & (SF_Distinct|SF_Aggregate))!=0
102434        || (pSub1->pPrior && pSub1->op!=TK_ALL) 
102435        || pSub1->pSrc->nSrc<1
102436        || pSub->pEList->nExpr!=pSub1->pEList->nExpr
102437       ){
102438         return 0;
102439       }
102440       testcase( pSub1->pSrc->nSrc>1 );
102441     }
102442 
102443     /* Restriction 18. */
102444     if( p->pOrderBy ){
102445       int ii;
102446       for(ii=0; ii<p->pOrderBy->nExpr; ii++){
102447         if( p->pOrderBy->a[ii].u.x.iOrderByCol==0 ) return 0;
102448       }
102449     }
102450   }
102451 
102452   /***** If we reach this point, flattening is permitted. *****/
102453 
102454   /* Authorize the subquery */
102455   pParse->zAuthContext = pSubitem->zName;
102456   TESTONLY(i =) sqlite3AuthCheck(pParse, SQLITE_SELECT, 0, 0, 0);
102457   testcase( i==SQLITE_DENY );
102458   pParse->zAuthContext = zSavedAuthContext;
102459 
102460   /* If the sub-query is a compound SELECT statement, then (by restrictions
102461   ** 17 and 18 above) it must be a UNION ALL and the parent query must 
102462   ** be of the form:
102463   **
102464   **     SELECT <expr-list> FROM (<sub-query>) <where-clause> 
102465   **
102466   ** followed by any ORDER BY, LIMIT and/or OFFSET clauses. This block
102467   ** creates N-1 copies of the parent query without any ORDER BY, LIMIT or 
102468   ** OFFSET clauses and joins them to the left-hand-side of the original
102469   ** using UNION ALL operators. In this case N is the number of simple
102470   ** select statements in the compound sub-query.
102471   **
102472   ** Example:
102473   **
102474   **     SELECT a+1 FROM (
102475   **        SELECT x FROM tab
102476   **        UNION ALL
102477   **        SELECT y FROM tab
102478   **        UNION ALL
102479   **        SELECT abs(z*2) FROM tab2
102480   **     ) WHERE a!=5 ORDER BY 1
102481   **
102482   ** Transformed into:
102483   **
102484   **     SELECT x+1 FROM tab WHERE x+1!=5
102485   **     UNION ALL
102486   **     SELECT y+1 FROM tab WHERE y+1!=5
102487   **     UNION ALL
102488   **     SELECT abs(z*2)+1 FROM tab2 WHERE abs(z*2)+1!=5
102489   **     ORDER BY 1
102490   **
102491   ** We call this the "compound-subquery flattening".
102492   */
102493   for(pSub=pSub->pPrior; pSub; pSub=pSub->pPrior){
102494     Select *pNew;
102495     ExprList *pOrderBy = p->pOrderBy;
102496     Expr *pLimit = p->pLimit;
102497     Expr *pOffset = p->pOffset;
102498     Select *pPrior = p->pPrior;
102499     p->pOrderBy = 0;
102500     p->pSrc = 0;
102501     p->pPrior = 0;
102502     p->pLimit = 0;
102503     p->pOffset = 0;
102504     pNew = sqlite3SelectDup(db, p, 0);
102505     p->pOffset = pOffset;
102506     p->pLimit = pLimit;
102507     p->pOrderBy = pOrderBy;
102508     p->pSrc = pSrc;
102509     p->op = TK_ALL;
102510     p->pRightmost = 0;
102511     if( pNew==0 ){
102512       pNew = pPrior;
102513     }else{
102514       pNew->pPrior = pPrior;
102515       pNew->pRightmost = 0;
102516     }
102517     p->pPrior = pNew;
102518     if( db->mallocFailed ) return 1;
102519   }
102520 
102521   /* Begin flattening the iFrom-th entry of the FROM clause 
102522   ** in the outer query.
102523   */
102524   pSub = pSub1 = pSubitem->pSelect;
102525 
102526   /* Delete the transient table structure associated with the
102527   ** subquery
102528   */
102529   sqlite3DbFree(db, pSubitem->zDatabase);
102530   sqlite3DbFree(db, pSubitem->zName);
102531   sqlite3DbFree(db, pSubitem->zAlias);
102532   pSubitem->zDatabase = 0;
102533   pSubitem->zName = 0;
102534   pSubitem->zAlias = 0;
102535   pSubitem->pSelect = 0;
102536 
102537   /* Defer deleting the Table object associated with the
102538   ** subquery until code generation is
102539   ** complete, since there may still exist Expr.pTab entries that
102540   ** refer to the subquery even after flattening.  Ticket #3346.
102541   **
102542   ** pSubitem->pTab is always non-NULL by test restrictions and tests above.
102543   */
102544   if( ALWAYS(pSubitem->pTab!=0) ){
102545     Table *pTabToDel = pSubitem->pTab;
102546     if( pTabToDel->nRef==1 ){
102547       Parse *pToplevel = sqlite3ParseToplevel(pParse);
102548       pTabToDel->pNextZombie = pToplevel->pZombieTab;
102549       pToplevel->pZombieTab = pTabToDel;
102550     }else{
102551       pTabToDel->nRef--;
102552     }
102553     pSubitem->pTab = 0;
102554   }
102555 
102556   /* The following loop runs once for each term in a compound-subquery
102557   ** flattening (as described above).  If we are doing a different kind
102558   ** of flattening - a flattening other than a compound-subquery flattening -
102559   ** then this loop only runs once.
102560   **
102561   ** This loop moves all of the FROM elements of the subquery into the
102562   ** the FROM clause of the outer query.  Before doing this, remember
102563   ** the cursor number for the original outer query FROM element in
102564   ** iParent.  The iParent cursor will never be used.  Subsequent code
102565   ** will scan expressions looking for iParent references and replace
102566   ** those references with expressions that resolve to the subquery FROM
102567   ** elements we are now copying in.
102568   */
102569   for(pParent=p; pParent; pParent=pParent->pPrior, pSub=pSub->pPrior){
102570     int nSubSrc;
102571     u8 jointype = 0;
102572     pSubSrc = pSub->pSrc;     /* FROM clause of subquery */
102573     nSubSrc = pSubSrc->nSrc;  /* Number of terms in subquery FROM clause */
102574     pSrc = pParent->pSrc;     /* FROM clause of the outer query */
102575 
102576     if( pSrc ){
102577       assert( pParent==p );  /* First time through the loop */
102578       jointype = pSubitem->jointype;
102579     }else{
102580       assert( pParent!=p );  /* 2nd and subsequent times through the loop */
102581       pSrc = pParent->pSrc = sqlite3SrcListAppend(db, 0, 0, 0);
102582       if( pSrc==0 ){
102583         assert( db->mallocFailed );
102584         break;
102585       }
102586     }
102587 
102588     /* The subquery uses a single slot of the FROM clause of the outer
102589     ** query.  If the subquery has more than one element in its FROM clause,
102590     ** then expand the outer query to make space for it to hold all elements
102591     ** of the subquery.
102592     **
102593     ** Example:
102594     **
102595     **    SELECT * FROM tabA, (SELECT * FROM sub1, sub2), tabB;
102596     **
102597     ** The outer query has 3 slots in its FROM clause.  One slot of the
102598     ** outer query (the middle slot) is used by the subquery.  The next
102599     ** block of code will expand the out query to 4 slots.  The middle
102600     ** slot is expanded to two slots in order to make space for the
102601     ** two elements in the FROM clause of the subquery.
102602     */
102603     if( nSubSrc>1 ){
102604       pParent->pSrc = pSrc = sqlite3SrcListEnlarge(db, pSrc, nSubSrc-1,iFrom+1);
102605       if( db->mallocFailed ){
102606         break;
102607       }
102608     }
102609 
102610     /* Transfer the FROM clause terms from the subquery into the
102611     ** outer query.
102612     */
102613     for(i=0; i<nSubSrc; i++){
102614       sqlite3IdListDelete(db, pSrc->a[i+iFrom].pUsing);
102615       pSrc->a[i+iFrom] = pSubSrc->a[i];
102616       memset(&pSubSrc->a[i], 0, sizeof(pSubSrc->a[i]));
102617     }
102618     pSrc->a[iFrom].jointype = jointype;
102619   
102620     /* Now begin substituting subquery result set expressions for 
102621     ** references to the iParent in the outer query.
102622     ** 
102623     ** Example:
102624     **
102625     **   SELECT a+5, b*10 FROM (SELECT x*3 AS a, y+10 AS b FROM t1) WHERE a>b;
102626     **   \                     \_____________ subquery __________/          /
102627     **    \_____________________ outer query ______________________________/
102628     **
102629     ** We look at every expression in the outer query and every place we see
102630     ** "a" we substitute "x*3" and every place we see "b" we substitute "y+10".
102631     */
102632     pList = pParent->pEList;
102633     for(i=0; i<pList->nExpr; i++){
102634       if( pList->a[i].zName==0 ){
102635         char *zName = sqlite3DbStrDup(db, pList->a[i].zSpan);
102636         sqlite3Dequote(zName);
102637         pList->a[i].zName = zName;
102638       }
102639     }
102640     substExprList(db, pParent->pEList, iParent, pSub->pEList);
102641     if( isAgg ){
102642       substExprList(db, pParent->pGroupBy, iParent, pSub->pEList);
102643       pParent->pHaving = substExpr(db, pParent->pHaving, iParent, pSub->pEList);
102644     }
102645     if( pSub->pOrderBy ){
102646       assert( pParent->pOrderBy==0 );
102647       pParent->pOrderBy = pSub->pOrderBy;
102648       pSub->pOrderBy = 0;
102649     }else if( pParent->pOrderBy ){
102650       substExprList(db, pParent->pOrderBy, iParent, pSub->pEList);
102651     }
102652     if( pSub->pWhere ){
102653       pWhere = sqlite3ExprDup(db, pSub->pWhere, 0);
102654     }else{
102655       pWhere = 0;
102656     }
102657     if( subqueryIsAgg ){
102658       assert( pParent->pHaving==0 );
102659       pParent->pHaving = pParent->pWhere;
102660       pParent->pWhere = pWhere;
102661       pParent->pHaving = substExpr(db, pParent->pHaving, iParent, pSub->pEList);
102662       pParent->pHaving = sqlite3ExprAnd(db, pParent->pHaving, 
102663                                   sqlite3ExprDup(db, pSub->pHaving, 0));
102664       assert( pParent->pGroupBy==0 );
102665       pParent->pGroupBy = sqlite3ExprListDup(db, pSub->pGroupBy, 0);
102666     }else{
102667       pParent->pWhere = substExpr(db, pParent->pWhere, iParent, pSub->pEList);
102668       pParent->pWhere = sqlite3ExprAnd(db, pParent->pWhere, pWhere);
102669     }
102670   
102671     /* The flattened query is distinct if either the inner or the
102672     ** outer query is distinct. 
102673     */
102674     pParent->selFlags |= pSub->selFlags & SF_Distinct;
102675   
102676     /*
102677     ** SELECT ... FROM (SELECT ... LIMIT a OFFSET b) LIMIT x OFFSET y;
102678     **
102679     ** One is tempted to try to add a and b to combine the limits.  But this
102680     ** does not work if either limit is negative.
102681     */
102682     if( pSub->pLimit ){
102683       pParent->pLimit = pSub->pLimit;
102684       pSub->pLimit = 0;
102685     }
102686   }
102687 
102688   /* Finially, delete what is left of the subquery and return
102689   ** success.
102690   */
102691   sqlite3SelectDelete(db, pSub1);
102692 
102693   return 1;
102694 }
102695 #endif /* !defined(SQLITE_OMIT_SUBQUERY) || !defined(SQLITE_OMIT_VIEW) */
102696 
102697 /*
102698 ** Based on the contents of the AggInfo structure indicated by the first
102699 ** argument, this function checks if the following are true:
102700 **
102701 **    * the query contains just a single aggregate function,
102702 **    * the aggregate function is either min() or max(), and
102703 **    * the argument to the aggregate function is a column value.
102704 **
102705 ** If all of the above are true, then WHERE_ORDERBY_MIN or WHERE_ORDERBY_MAX
102706 ** is returned as appropriate. Also, *ppMinMax is set to point to the 
102707 ** list of arguments passed to the aggregate before returning.
102708 **
102709 ** Or, if the conditions above are not met, *ppMinMax is set to 0 and
102710 ** WHERE_ORDERBY_NORMAL is returned.
102711 */
102712 static u8 minMaxQuery(AggInfo *pAggInfo, ExprList **ppMinMax){
102713   int eRet = WHERE_ORDERBY_NORMAL;          /* Return value */
102714 
102715   *ppMinMax = 0;
102716   if( pAggInfo->nFunc==1 ){
102717     Expr *pExpr = pAggInfo->aFunc[0].pExpr; /* Aggregate function */
102718     ExprList *pEList = pExpr->x.pList;      /* Arguments to agg function */
102719 
102720     assert( pExpr->op==TK_AGG_FUNCTION );
102721     if( pEList && pEList->nExpr==1 && pEList->a[0].pExpr->op==TK_AGG_COLUMN ){
102722       const char *zFunc = pExpr->u.zToken;
102723       if( sqlite3StrICmp(zFunc, "min")==0 ){
102724         eRet = WHERE_ORDERBY_MIN;
102725         *ppMinMax = pEList;
102726       }else if( sqlite3StrICmp(zFunc, "max")==0 ){
102727         eRet = WHERE_ORDERBY_MAX;
102728         *ppMinMax = pEList;
102729       }
102730     }
102731   }
102732 
102733   assert( *ppMinMax==0 || (*ppMinMax)->nExpr==1 );
102734   return eRet;
102735 }
102736 
102737 /*
102738 ** The select statement passed as the first argument is an aggregate query.
102739 ** The second argment is the associated aggregate-info object. This 
102740 ** function tests if the SELECT is of the form:
102741 **
102742 **   SELECT count(*) FROM <tbl>
102743 **
102744 ** where table is a database table, not a sub-select or view. If the query
102745 ** does match this pattern, then a pointer to the Table object representing
102746 ** <tbl> is returned. Otherwise, 0 is returned.
102747 */
102748 static Table *isSimpleCount(Select *p, AggInfo *pAggInfo){
102749   Table *pTab;
102750   Expr *pExpr;
102751 
102752   assert( !p->pGroupBy );
102753 
102754   if( p->pWhere || p->pEList->nExpr!=1 
102755    || p->pSrc->nSrc!=1 || p->pSrc->a[0].pSelect
102756   ){
102757     return 0;
102758   }
102759   pTab = p->pSrc->a[0].pTab;
102760   pExpr = p->pEList->a[0].pExpr;
102761   assert( pTab && !pTab->pSelect && pExpr );
102762 
102763   if( IsVirtual(pTab) ) return 0;
102764   if( pExpr->op!=TK_AGG_FUNCTION ) return 0;
102765   if( NEVER(pAggInfo->nFunc==0) ) return 0;
102766   if( (pAggInfo->aFunc[0].pFunc->funcFlags&SQLITE_FUNC_COUNT)==0 ) return 0;
102767   if( pExpr->flags&EP_Distinct ) return 0;
102768 
102769   return pTab;
102770 }
102771 
102772 /*
102773 ** If the source-list item passed as an argument was augmented with an
102774 ** INDEXED BY clause, then try to locate the specified index. If there
102775 ** was such a clause and the named index cannot be found, return 
102776 ** SQLITE_ERROR and leave an error in pParse. Otherwise, populate 
102777 ** pFrom->pIndex and return SQLITE_OK.
102778 */
102779 SQLITE_PRIVATE int sqlite3IndexedByLookup(Parse *pParse, struct SrcList_item *pFrom){
102780   if( pFrom->pTab && pFrom->zIndex ){
102781     Table *pTab = pFrom->pTab;
102782     char *zIndex = pFrom->zIndex;
102783     Index *pIdx;
102784     for(pIdx=pTab->pIndex; 
102785         pIdx && sqlite3StrICmp(pIdx->zName, zIndex); 
102786         pIdx=pIdx->pNext
102787     );
102788     if( !pIdx ){
102789       sqlite3ErrorMsg(pParse, "no such index: %s", zIndex, 0);
102790       pParse->checkSchema = 1;
102791       return SQLITE_ERROR;
102792     }
102793     pFrom->pIndex = pIdx;
102794   }
102795   return SQLITE_OK;
102796 }
102797 /*
102798 ** Detect compound SELECT statements that use an ORDER BY clause with 
102799 ** an alternative collating sequence.
102800 **
102801 **    SELECT ... FROM t1 EXCEPT SELECT ... FROM t2 ORDER BY .. COLLATE ...
102802 **
102803 ** These are rewritten as a subquery:
102804 **
102805 **    SELECT * FROM (SELECT ... FROM t1 EXCEPT SELECT ... FROM t2)
102806 **     ORDER BY ... COLLATE ...
102807 **
102808 ** This transformation is necessary because the multiSelectOrderBy() routine
102809 ** above that generates the code for a compound SELECT with an ORDER BY clause
102810 ** uses a merge algorithm that requires the same collating sequence on the
102811 ** result columns as on the ORDER BY clause.  See ticket
102812 ** http://www.sqlite.org/src/info/6709574d2a
102813 **
102814 ** This transformation is only needed for EXCEPT, INTERSECT, and UNION.
102815 ** The UNION ALL operator works fine with multiSelectOrderBy() even when
102816 ** there are COLLATE terms in the ORDER BY.
102817 */
102818 static int convertCompoundSelectToSubquery(Walker *pWalker, Select *p){
102819   int i;
102820   Select *pNew;
102821   Select *pX;
102822   sqlite3 *db;
102823   struct ExprList_item *a;
102824   SrcList *pNewSrc;
102825   Parse *pParse;
102826   Token dummy;
102827 
102828   if( p->pPrior==0 ) return WRC_Continue;
102829   if( p->pOrderBy==0 ) return WRC_Continue;
102830   for(pX=p; pX && (pX->op==TK_ALL || pX->op==TK_SELECT); pX=pX->pPrior){}
102831   if( pX==0 ) return WRC_Continue;
102832   a = p->pOrderBy->a;
102833   for(i=p->pOrderBy->nExpr-1; i>=0; i--){
102834     if( a[i].pExpr->flags & EP_Collate ) break;
102835   }
102836   if( i<0 ) return WRC_Continue;
102837 
102838   /* If we reach this point, that means the transformation is required. */
102839 
102840   pParse = pWalker->pParse;
102841   db = pParse->db;
102842   pNew = sqlite3DbMallocZero(db, sizeof(*pNew) );
102843   if( pNew==0 ) return WRC_Abort;
102844   memset(&dummy, 0, sizeof(dummy));
102845   pNewSrc = sqlite3SrcListAppendFromTerm(pParse,0,0,0,&dummy,pNew,0,0);
102846   if( pNewSrc==0 ) return WRC_Abort;
102847   *pNew = *p;
102848   p->pSrc = pNewSrc;
102849   p->pEList = sqlite3ExprListAppend(pParse, 0, sqlite3Expr(db, TK_ALL, 0));
102850   p->op = TK_SELECT;
102851   p->pWhere = 0;
102852   pNew->pGroupBy = 0;
102853   pNew->pHaving = 0;
102854   pNew->pOrderBy = 0;
102855   p->pPrior = 0;
102856   pNew->pLimit = 0;
102857   pNew->pOffset = 0;
102858   return WRC_Continue;
102859 }
102860 
102861 /*
102862 ** This routine is a Walker callback for "expanding" a SELECT statement.
102863 ** "Expanding" means to do the following:
102864 **
102865 **    (1)  Make sure VDBE cursor numbers have been assigned to every
102866 **         element of the FROM clause.
102867 **
102868 **    (2)  Fill in the pTabList->a[].pTab fields in the SrcList that 
102869 **         defines FROM clause.  When views appear in the FROM clause,
102870 **         fill pTabList->a[].pSelect with a copy of the SELECT statement
102871 **         that implements the view.  A copy is made of the view's SELECT
102872 **         statement so that we can freely modify or delete that statement
102873 **         without worrying about messing up the presistent representation
102874 **         of the view.
102875 **
102876 **    (3)  Add terms to the WHERE clause to accomodate the NATURAL keyword
102877 **         on joins and the ON and USING clause of joins.
102878 **
102879 **    (4)  Scan the list of columns in the result set (pEList) looking
102880 **         for instances of the "*" operator or the TABLE.* operator.
102881 **         If found, expand each "*" to be every column in every table
102882 **         and TABLE.* to be every column in TABLE.
102883 **
102884 */
102885 static int selectExpander(Walker *pWalker, Select *p){
102886   Parse *pParse = pWalker->pParse;
102887   int i, j, k;
102888   SrcList *pTabList;
102889   ExprList *pEList;
102890   struct SrcList_item *pFrom;
102891   sqlite3 *db = pParse->db;
102892   Expr *pE, *pRight, *pExpr;
102893   u16 selFlags = p->selFlags;
102894 
102895   p->selFlags |= SF_Expanded;
102896   if( db->mallocFailed  ){
102897     return WRC_Abort;
102898   }
102899   if( NEVER(p->pSrc==0) || (selFlags & SF_Expanded)!=0 ){
102900     return WRC_Prune;
102901   }
102902   pTabList = p->pSrc;
102903   pEList = p->pEList;
102904 
102905   /* Make sure cursor numbers have been assigned to all entries in
102906   ** the FROM clause of the SELECT statement.
102907   */
102908   sqlite3SrcListAssignCursors(pParse, pTabList);
102909 
102910   /* Look up every table named in the FROM clause of the select.  If
102911   ** an entry of the FROM clause is a subquery instead of a table or view,
102912   ** then create a transient table structure to describe the subquery.
102913   */
102914   for(i=0, pFrom=pTabList->a; i<pTabList->nSrc; i++, pFrom++){
102915     Table *pTab;
102916     if( pFrom->pTab!=0 ){
102917       /* This statement has already been prepared.  There is no need
102918       ** to go further. */
102919       assert( i==0 );
102920       return WRC_Prune;
102921     }
102922     if( pFrom->zName==0 ){
102923 #ifndef SQLITE_OMIT_SUBQUERY
102924       Select *pSel = pFrom->pSelect;
102925       /* A sub-query in the FROM clause of a SELECT */
102926       assert( pSel!=0 );
102927       assert( pFrom->pTab==0 );
102928       sqlite3WalkSelect(pWalker, pSel);
102929       pFrom->pTab = pTab = sqlite3DbMallocZero(db, sizeof(Table));
102930       if( pTab==0 ) return WRC_Abort;
102931       pTab->nRef = 1;
102932       pTab->zName = sqlite3MPrintf(db, "sqlite_sq_%p", (void*)pTab);
102933       while( pSel->pPrior ){ pSel = pSel->pPrior; }
102934       selectColumnsFromExprList(pParse, pSel->pEList, &pTab->nCol, &pTab->aCol);
102935       pTab->iPKey = -1;
102936       pTab->nRowEst = 1048576;
102937       pTab->tabFlags |= TF_Ephemeral;
102938 #endif
102939     }else{
102940       /* An ordinary table or view name in the FROM clause */
102941       assert( pFrom->pTab==0 );
102942       pFrom->pTab = pTab = sqlite3LocateTableItem(pParse, 0, pFrom);
102943       if( pTab==0 ) return WRC_Abort;
102944       if( pTab->nRef==0xffff ){
102945         sqlite3ErrorMsg(pParse, "too many references to \"%s\": max 65535",
102946            pTab->zName);
102947         pFrom->pTab = 0;
102948         return WRC_Abort;
102949       }
102950       pTab->nRef++;
102951 #if !defined(SQLITE_OMIT_VIEW) || !defined (SQLITE_OMIT_VIRTUALTABLE)
102952       if( pTab->pSelect || IsVirtual(pTab) ){
102953         /* We reach here if the named table is a really a view */
102954         if( sqlite3ViewGetColumnNames(pParse, pTab) ) return WRC_Abort;
102955         assert( pFrom->pSelect==0 );
102956         pFrom->pSelect = sqlite3SelectDup(db, pTab->pSelect, 0);
102957         sqlite3WalkSelect(pWalker, pFrom->pSelect);
102958       }
102959 #endif
102960     }
102961 
102962     /* Locate the index named by the INDEXED BY clause, if any. */
102963     if( sqlite3IndexedByLookup(pParse, pFrom) ){
102964       return WRC_Abort;
102965     }
102966   }
102967 
102968   /* Process NATURAL keywords, and ON and USING clauses of joins.
102969   */
102970   if( db->mallocFailed || sqliteProcessJoin(pParse, p) ){
102971     return WRC_Abort;
102972   }
102973 
102974   /* For every "*" that occurs in the column list, insert the names of
102975   ** all columns in all tables.  And for every TABLE.* insert the names
102976   ** of all columns in TABLE.  The parser inserted a special expression
102977   ** with the TK_ALL operator for each "*" that it found in the column list.
102978   ** The following code just has to locate the TK_ALL expressions and expand
102979   ** each one to the list of all columns in all tables.
102980   **
102981   ** The first loop just checks to see if there are any "*" operators
102982   ** that need expanding.
102983   */
102984   for(k=0; k<pEList->nExpr; k++){
102985     pE = pEList->a[k].pExpr;
102986     if( pE->op==TK_ALL ) break;
102987     assert( pE->op!=TK_DOT || pE->pRight!=0 );
102988     assert( pE->op!=TK_DOT || (pE->pLeft!=0 && pE->pLeft->op==TK_ID) );
102989     if( pE->op==TK_DOT && pE->pRight->op==TK_ALL ) break;
102990   }
102991   if( k<pEList->nExpr ){
102992     /*
102993     ** If we get here it means the result set contains one or more "*"
102994     ** operators that need to be expanded.  Loop through each expression
102995     ** in the result set and expand them one by one.
102996     */
102997     struct ExprList_item *a = pEList->a;
102998     ExprList *pNew = 0;
102999     int flags = pParse->db->flags;
103000     int longNames = (flags & SQLITE_FullColNames)!=0
103001                       && (flags & SQLITE_ShortColNames)==0;
103002 
103003     /* When processing FROM-clause subqueries, it is always the case
103004     ** that full_column_names=OFF and short_column_names=ON.  The
103005     ** sqlite3ResultSetOfSelect() routine makes it so. */
103006     assert( (p->selFlags & SF_NestedFrom)==0
103007           || ((flags & SQLITE_FullColNames)==0 &&
103008               (flags & SQLITE_ShortColNames)!=0) );
103009 
103010     for(k=0; k<pEList->nExpr; k++){
103011       pE = a[k].pExpr;
103012       pRight = pE->pRight;
103013       assert( pE->op!=TK_DOT || pRight!=0 );
103014       if( pE->op!=TK_ALL && (pE->op!=TK_DOT || pRight->op!=TK_ALL) ){
103015         /* This particular expression does not need to be expanded.
103016         */
103017         pNew = sqlite3ExprListAppend(pParse, pNew, a[k].pExpr);
103018         if( pNew ){
103019           pNew->a[pNew->nExpr-1].zName = a[k].zName;
103020           pNew->a[pNew->nExpr-1].zSpan = a[k].zSpan;
103021           a[k].zName = 0;
103022           a[k].zSpan = 0;
103023         }
103024         a[k].pExpr = 0;
103025       }else{
103026         /* This expression is a "*" or a "TABLE.*" and needs to be
103027         ** expanded. */
103028         int tableSeen = 0;      /* Set to 1 when TABLE matches */
103029         char *zTName = 0;       /* text of name of TABLE */
103030         if( pE->op==TK_DOT ){
103031           assert( pE->pLeft!=0 );
103032           assert( !ExprHasProperty(pE->pLeft, EP_IntValue) );
103033           zTName = pE->pLeft->u.zToken;
103034         }
103035         for(i=0, pFrom=pTabList->a; i<pTabList->nSrc; i++, pFrom++){
103036           Table *pTab = pFrom->pTab;
103037           Select *pSub = pFrom->pSelect;
103038           char *zTabName = pFrom->zAlias;
103039           const char *zSchemaName = 0;
103040           int iDb;
103041           if( zTabName==0 ){
103042             zTabName = pTab->zName;
103043           }
103044           if( db->mallocFailed ) break;
103045           if( pSub==0 || (pSub->selFlags & SF_NestedFrom)==0 ){
103046             pSub = 0;
103047             if( zTName && sqlite3StrICmp(zTName, zTabName)!=0 ){
103048               continue;
103049             }
103050             iDb = sqlite3SchemaToIndex(db, pTab->pSchema);
103051             zSchemaName = iDb>=0 ? db->aDb[iDb].zName : "*";
103052           }
103053           for(j=0; j<pTab->nCol; j++){
103054             char *zName = pTab->aCol[j].zName;
103055             char *zColname;  /* The computed column name */
103056             char *zToFree;   /* Malloced string that needs to be freed */
103057             Token sColname;  /* Computed column name as a token */
103058 
103059             assert( zName );
103060             if( zTName && pSub
103061              && sqlite3MatchSpanName(pSub->pEList->a[j].zSpan, 0, zTName, 0)==0
103062             ){
103063               continue;
103064             }
103065 
103066             /* If a column is marked as 'hidden' (currently only possible
103067             ** for virtual tables), do not include it in the expanded
103068             ** result-set list.
103069             */
103070             if( IsHiddenColumn(&pTab->aCol[j]) ){
103071               assert(IsVirtual(pTab));
103072               continue;
103073             }
103074             tableSeen = 1;
103075 
103076             if( i>0 && zTName==0 ){
103077               if( (pFrom->jointype & JT_NATURAL)!=0
103078                 && tableAndColumnIndex(pTabList, i, zName, 0, 0)
103079               ){
103080                 /* In a NATURAL join, omit the join columns from the 
103081                 ** table to the right of the join */
103082                 continue;
103083               }
103084               if( sqlite3IdListIndex(pFrom->pUsing, zName)>=0 ){
103085                 /* In a join with a USING clause, omit columns in the
103086                 ** using clause from the table on the right. */
103087                 continue;
103088               }
103089             }
103090             pRight = sqlite3Expr(db, TK_ID, zName);
103091             zColname = zName;
103092             zToFree = 0;
103093             if( longNames || pTabList->nSrc>1 ){
103094               Expr *pLeft;
103095               pLeft = sqlite3Expr(db, TK_ID, zTabName);
103096               pExpr = sqlite3PExpr(pParse, TK_DOT, pLeft, pRight, 0);
103097               if( zSchemaName ){
103098                 pLeft = sqlite3Expr(db, TK_ID, zSchemaName);
103099                 pExpr = sqlite3PExpr(pParse, TK_DOT, pLeft, pExpr, 0);
103100               }
103101               if( longNames ){
103102                 zColname = sqlite3MPrintf(db, "%s.%s", zTabName, zName);
103103                 zToFree = zColname;
103104               }
103105             }else{
103106               pExpr = pRight;
103107             }
103108             pNew = sqlite3ExprListAppend(pParse, pNew, pExpr);
103109             sColname.z = zColname;
103110             sColname.n = sqlite3Strlen30(zColname);
103111             sqlite3ExprListSetName(pParse, pNew, &sColname, 0);
103112             if( pNew && (p->selFlags & SF_NestedFrom)!=0 ){
103113               struct ExprList_item *pX = &pNew->a[pNew->nExpr-1];
103114               if( pSub ){
103115                 pX->zSpan = sqlite3DbStrDup(db, pSub->pEList->a[j].zSpan);
103116                 testcase( pX->zSpan==0 );
103117               }else{
103118                 pX->zSpan = sqlite3MPrintf(db, "%s.%s.%s",
103119                                            zSchemaName, zTabName, zColname);
103120                 testcase( pX->zSpan==0 );
103121               }
103122               pX->bSpanIsTab = 1;
103123             }
103124             sqlite3DbFree(db, zToFree);
103125           }
103126         }
103127         if( !tableSeen ){
103128           if( zTName ){
103129             sqlite3ErrorMsg(pParse, "no such table: %s", zTName);
103130           }else{
103131             sqlite3ErrorMsg(pParse, "no tables specified");
103132           }
103133         }
103134       }
103135     }
103136     sqlite3ExprListDelete(db, pEList);
103137     p->pEList = pNew;
103138   }
103139 #if SQLITE_MAX_COLUMN
103140   if( p->pEList && p->pEList->nExpr>db->aLimit[SQLITE_LIMIT_COLUMN] ){
103141     sqlite3ErrorMsg(pParse, "too many columns in result set");
103142   }
103143 #endif
103144   return WRC_Continue;
103145 }
103146 
103147 /*
103148 ** No-op routine for the parse-tree walker.
103149 **
103150 ** When this routine is the Walker.xExprCallback then expression trees
103151 ** are walked without any actions being taken at each node.  Presumably,
103152 ** when this routine is used for Walker.xExprCallback then 
103153 ** Walker.xSelectCallback is set to do something useful for every 
103154 ** subquery in the parser tree.
103155 */
103156 static int exprWalkNoop(Walker *NotUsed, Expr *NotUsed2){
103157   UNUSED_PARAMETER2(NotUsed, NotUsed2);
103158   return WRC_Continue;
103159 }
103160 
103161 /*
103162 ** This routine "expands" a SELECT statement and all of its subqueries.
103163 ** For additional information on what it means to "expand" a SELECT
103164 ** statement, see the comment on the selectExpand worker callback above.
103165 **
103166 ** Expanding a SELECT statement is the first step in processing a
103167 ** SELECT statement.  The SELECT statement must be expanded before
103168 ** name resolution is performed.
103169 **
103170 ** If anything goes wrong, an error message is written into pParse.
103171 ** The calling function can detect the problem by looking at pParse->nErr
103172 ** and/or pParse->db->mallocFailed.
103173 */
103174 static void sqlite3SelectExpand(Parse *pParse, Select *pSelect){
103175   Walker w;
103176   memset(&w, 0, sizeof(w));
103177   w.xExprCallback = exprWalkNoop;
103178   w.pParse = pParse;
103179   if( pParse->hasCompound ){
103180     w.xSelectCallback = convertCompoundSelectToSubquery;
103181     sqlite3WalkSelect(&w, pSelect);
103182   }
103183   w.xSelectCallback = selectExpander;
103184   sqlite3WalkSelect(&w, pSelect);
103185 }
103186 
103187 
103188 #ifndef SQLITE_OMIT_SUBQUERY
103189 /*
103190 ** This is a Walker.xSelectCallback callback for the sqlite3SelectTypeInfo()
103191 ** interface.
103192 **
103193 ** For each FROM-clause subquery, add Column.zType and Column.zColl
103194 ** information to the Table structure that represents the result set
103195 ** of that subquery.
103196 **
103197 ** The Table structure that represents the result set was constructed
103198 ** by selectExpander() but the type and collation information was omitted
103199 ** at that point because identifiers had not yet been resolved.  This
103200 ** routine is called after identifier resolution.
103201 */
103202 static int selectAddSubqueryTypeInfo(Walker *pWalker, Select *p){
103203   Parse *pParse;
103204   int i;
103205   SrcList *pTabList;
103206   struct SrcList_item *pFrom;
103207 
103208   assert( p->selFlags & SF_Resolved );
103209   if( (p->selFlags & SF_HasTypeInfo)==0 ){
103210     p->selFlags |= SF_HasTypeInfo;
103211     pParse = pWalker->pParse;
103212     pTabList = p->pSrc;
103213     for(i=0, pFrom=pTabList->a; i<pTabList->nSrc; i++, pFrom++){
103214       Table *pTab = pFrom->pTab;
103215       if( ALWAYS(pTab!=0) && (pTab->tabFlags & TF_Ephemeral)!=0 ){
103216         /* A sub-query in the FROM clause of a SELECT */
103217         Select *pSel = pFrom->pSelect;
103218         assert( pSel );
103219         while( pSel->pPrior ) pSel = pSel->pPrior;
103220         selectAddColumnTypeAndCollation(pParse, pTab, pSel);
103221       }
103222     }
103223   }
103224   return WRC_Continue;
103225 }
103226 #endif
103227 
103228 
103229 /*
103230 ** This routine adds datatype and collating sequence information to
103231 ** the Table structures of all FROM-clause subqueries in a
103232 ** SELECT statement.
103233 **
103234 ** Use this routine after name resolution.
103235 */
103236 static void sqlite3SelectAddTypeInfo(Parse *pParse, Select *pSelect){
103237 #ifndef SQLITE_OMIT_SUBQUERY
103238   Walker w;
103239   memset(&w, 0, sizeof(w));
103240   w.xSelectCallback = selectAddSubqueryTypeInfo;
103241   w.xExprCallback = exprWalkNoop;
103242   w.pParse = pParse;
103243   w.bSelectDepthFirst = 1;
103244   sqlite3WalkSelect(&w, pSelect);
103245 #endif
103246 }
103247 
103248 
103249 /*
103250 ** This routine sets up a SELECT statement for processing.  The
103251 ** following is accomplished:
103252 **
103253 **     *  VDBE Cursor numbers are assigned to all FROM-clause terms.
103254 **     *  Ephemeral Table objects are created for all FROM-clause subqueries.
103255 **     *  ON and USING clauses are shifted into WHERE statements
103256 **     *  Wildcards "*" and "TABLE.*" in result sets are expanded.
103257 **     *  Identifiers in expression are matched to tables.
103258 **
103259 ** This routine acts recursively on all subqueries within the SELECT.
103260 */
103261 SQLITE_PRIVATE void sqlite3SelectPrep(
103262   Parse *pParse,         /* The parser context */
103263   Select *p,             /* The SELECT statement being coded. */
103264   NameContext *pOuterNC  /* Name context for container */
103265 ){
103266   sqlite3 *db;
103267   if( NEVER(p==0) ) return;
103268   db = pParse->db;
103269   if( db->mallocFailed ) return;
103270   if( p->selFlags & SF_HasTypeInfo ) return;
103271   sqlite3SelectExpand(pParse, p);
103272   if( pParse->nErr || db->mallocFailed ) return;
103273   sqlite3ResolveSelectNames(pParse, p, pOuterNC);
103274   if( pParse->nErr || db->mallocFailed ) return;
103275   sqlite3SelectAddTypeInfo(pParse, p);
103276 }
103277 
103278 /*
103279 ** Reset the aggregate accumulator.
103280 **
103281 ** The aggregate accumulator is a set of memory cells that hold
103282 ** intermediate results while calculating an aggregate.  This
103283 ** routine generates code that stores NULLs in all of those memory
103284 ** cells.
103285 */
103286 static void resetAccumulator(Parse *pParse, AggInfo *pAggInfo){
103287   Vdbe *v = pParse->pVdbe;
103288   int i;
103289   struct AggInfo_func *pFunc;
103290   if( pAggInfo->nFunc+pAggInfo->nColumn==0 ){
103291     return;
103292   }
103293   for(i=0; i<pAggInfo->nColumn; i++){
103294     sqlite3VdbeAddOp2(v, OP_Null, 0, pAggInfo->aCol[i].iMem);
103295   }
103296   for(pFunc=pAggInfo->aFunc, i=0; i<pAggInfo->nFunc; i++, pFunc++){
103297     sqlite3VdbeAddOp2(v, OP_Null, 0, pFunc->iMem);
103298     if( pFunc->iDistinct>=0 ){
103299       Expr *pE = pFunc->pExpr;
103300       assert( !ExprHasProperty(pE, EP_xIsSelect) );
103301       if( pE->x.pList==0 || pE->x.pList->nExpr!=1 ){
103302         sqlite3ErrorMsg(pParse, "DISTINCT aggregates must have exactly one "
103303            "argument");
103304         pFunc->iDistinct = -1;
103305       }else{
103306         KeyInfo *pKeyInfo = keyInfoFromExprList(pParse, pE->x.pList);
103307         sqlite3VdbeAddOp4(v, OP_OpenEphemeral, pFunc->iDistinct, 0, 0,
103308                           (char*)pKeyInfo, P4_KEYINFO);
103309       }
103310     }
103311   }
103312 }
103313 
103314 /*
103315 ** Invoke the OP_AggFinalize opcode for every aggregate function
103316 ** in the AggInfo structure.
103317 */
103318 static void finalizeAggFunctions(Parse *pParse, AggInfo *pAggInfo){
103319   Vdbe *v = pParse->pVdbe;
103320   int i;
103321   struct AggInfo_func *pF;
103322   for(i=0, pF=pAggInfo->aFunc; i<pAggInfo->nFunc; i++, pF++){
103323     ExprList *pList = pF->pExpr->x.pList;
103324     assert( !ExprHasProperty(pF->pExpr, EP_xIsSelect) );
103325     sqlite3VdbeAddOp4(v, OP_AggFinal, pF->iMem, pList ? pList->nExpr : 0, 0,
103326                       (void*)pF->pFunc, P4_FUNCDEF);
103327   }
103328 }
103329 
103330 /*
103331 ** Update the accumulator memory cells for an aggregate based on
103332 ** the current cursor position.
103333 */
103334 static void updateAccumulator(Parse *pParse, AggInfo *pAggInfo){
103335   Vdbe *v = pParse->pVdbe;
103336   int i;
103337   int regHit = 0;
103338   int addrHitTest = 0;
103339   struct AggInfo_func *pF;
103340   struct AggInfo_col *pC;
103341 
103342   pAggInfo->directMode = 1;
103343   sqlite3ExprCacheClear(pParse);
103344   for(i=0, pF=pAggInfo->aFunc; i<pAggInfo->nFunc; i++, pF++){
103345     int nArg;
103346     int addrNext = 0;
103347     int regAgg;
103348     ExprList *pList = pF->pExpr->x.pList;
103349     assert( !ExprHasProperty(pF->pExpr, EP_xIsSelect) );
103350     if( pList ){
103351       nArg = pList->nExpr;
103352       regAgg = sqlite3GetTempRange(pParse, nArg);
103353       sqlite3ExprCodeExprList(pParse, pList, regAgg, SQLITE_ECEL_DUP);
103354     }else{
103355       nArg = 0;
103356       regAgg = 0;
103357     }
103358     if( pF->iDistinct>=0 ){
103359       addrNext = sqlite3VdbeMakeLabel(v);
103360       assert( nArg==1 );
103361       codeDistinct(pParse, pF->iDistinct, addrNext, 1, regAgg);
103362     }
103363     if( pF->pFunc->funcFlags & SQLITE_FUNC_NEEDCOLL ){
103364       CollSeq *pColl = 0;
103365       struct ExprList_item *pItem;
103366       int j;
103367       assert( pList!=0 );  /* pList!=0 if pF->pFunc has NEEDCOLL */
103368       for(j=0, pItem=pList->a; !pColl && j<nArg; j++, pItem++){
103369         pColl = sqlite3ExprCollSeq(pParse, pItem->pExpr);
103370       }
103371       if( !pColl ){
103372         pColl = pParse->db->pDfltColl;
103373       }
103374       if( regHit==0 && pAggInfo->nAccumulator ) regHit = ++pParse->nMem;
103375       sqlite3VdbeAddOp4(v, OP_CollSeq, regHit, 0, 0, (char *)pColl, P4_COLLSEQ);
103376     }
103377     sqlite3VdbeAddOp4(v, OP_AggStep, 0, regAgg, pF->iMem,
103378                       (void*)pF->pFunc, P4_FUNCDEF);
103379     sqlite3VdbeChangeP5(v, (u8)nArg);
103380     sqlite3ExprCacheAffinityChange(pParse, regAgg, nArg);
103381     sqlite3ReleaseTempRange(pParse, regAgg, nArg);
103382     if( addrNext ){
103383       sqlite3VdbeResolveLabel(v, addrNext);
103384       sqlite3ExprCacheClear(pParse);
103385     }
103386   }
103387 
103388   /* Before populating the accumulator registers, clear the column cache.
103389   ** Otherwise, if any of the required column values are already present 
103390   ** in registers, sqlite3ExprCode() may use OP_SCopy to copy the value
103391   ** to pC->iMem. But by the time the value is used, the original register
103392   ** may have been used, invalidating the underlying buffer holding the
103393   ** text or blob value. See ticket [883034dcb5].
103394   **
103395   ** Another solution would be to change the OP_SCopy used to copy cached
103396   ** values to an OP_Copy.
103397   */
103398   if( regHit ){
103399     addrHitTest = sqlite3VdbeAddOp1(v, OP_If, regHit);
103400   }
103401   sqlite3ExprCacheClear(pParse);
103402   for(i=0, pC=pAggInfo->aCol; i<pAggInfo->nAccumulator; i++, pC++){
103403     sqlite3ExprCode(pParse, pC->pExpr, pC->iMem);
103404   }
103405   pAggInfo->directMode = 0;
103406   sqlite3ExprCacheClear(pParse);
103407   if( addrHitTest ){
103408     sqlite3VdbeJumpHere(v, addrHitTest);
103409   }
103410 }
103411 
103412 /*
103413 ** Add a single OP_Explain instruction to the VDBE to explain a simple
103414 ** count(*) query ("SELECT count(*) FROM pTab").
103415 */
103416 #ifndef SQLITE_OMIT_EXPLAIN
103417 static void explainSimpleCount(
103418   Parse *pParse,                  /* Parse context */
103419   Table *pTab,                    /* Table being queried */
103420   Index *pIdx                     /* Index used to optimize scan, or NULL */
103421 ){
103422   if( pParse->explain==2 ){
103423     char *zEqp = sqlite3MPrintf(pParse->db, "SCAN TABLE %s%s%s",
103424         pTab->zName, 
103425         pIdx ? " USING COVERING INDEX " : "",
103426         pIdx ? pIdx->zName : ""
103427     );
103428     sqlite3VdbeAddOp4(
103429         pParse->pVdbe, OP_Explain, pParse->iSelectId, 0, 0, zEqp, P4_DYNAMIC
103430     );
103431   }
103432 }
103433 #else
103434 # define explainSimpleCount(a,b,c)
103435 #endif
103436 
103437 /*
103438 ** Generate code for the SELECT statement given in the p argument.  
103439 **
103440 ** The results are distributed in various ways depending on the
103441 ** contents of the SelectDest structure pointed to by argument pDest
103442 ** as follows:
103443 **
103444 **     pDest->eDest    Result
103445 **     ------------    -------------------------------------------
103446 **     SRT_Output      Generate a row of output (using the OP_ResultRow
103447 **                     opcode) for each row in the result set.
103448 **
103449 **     SRT_Mem         Only valid if the result is a single column.
103450 **                     Store the first column of the first result row
103451 **                     in register pDest->iSDParm then abandon the rest
103452 **                     of the query.  This destination implies "LIMIT 1".
103453 **
103454 **     SRT_Set         The result must be a single column.  Store each
103455 **                     row of result as the key in table pDest->iSDParm. 
103456 **                     Apply the affinity pDest->affSdst before storing
103457 **                     results.  Used to implement "IN (SELECT ...)".
103458 **
103459 **     SRT_Union       Store results as a key in a temporary table 
103460 **                     identified by pDest->iSDParm.
103461 **
103462 **     SRT_Except      Remove results from the temporary table pDest->iSDParm.
103463 **
103464 **     SRT_Table       Store results in temporary table pDest->iSDParm.
103465 **                     This is like SRT_EphemTab except that the table
103466 **                     is assumed to already be open.
103467 **
103468 **     SRT_EphemTab    Create an temporary table pDest->iSDParm and store
103469 **                     the result there. The cursor is left open after
103470 **                     returning.  This is like SRT_Table except that
103471 **                     this destination uses OP_OpenEphemeral to create
103472 **                     the table first.
103473 **
103474 **     SRT_Coroutine   Generate a co-routine that returns a new row of
103475 **                     results each time it is invoked.  The entry point
103476 **                     of the co-routine is stored in register pDest->iSDParm.
103477 **
103478 **     SRT_Exists      Store a 1 in memory cell pDest->iSDParm if the result
103479 **                     set is not empty.
103480 **
103481 **     SRT_Discard     Throw the results away.  This is used by SELECT
103482 **                     statements within triggers whose only purpose is
103483 **                     the side-effects of functions.
103484 **
103485 ** This routine returns the number of errors.  If any errors are
103486 ** encountered, then an appropriate error message is left in
103487 ** pParse->zErrMsg.
103488 **
103489 ** This routine does NOT free the Select structure passed in.  The
103490 ** calling function needs to do that.
103491 */
103492 SQLITE_PRIVATE int sqlite3Select(
103493   Parse *pParse,         /* The parser context */
103494   Select *p,             /* The SELECT statement being coded. */
103495   SelectDest *pDest      /* What to do with the query results */
103496 ){
103497   int i, j;              /* Loop counters */
103498   WhereInfo *pWInfo;     /* Return from sqlite3WhereBegin() */
103499   Vdbe *v;               /* The virtual machine under construction */
103500   int isAgg;             /* True for select lists like "count(*)" */
103501   ExprList *pEList;      /* List of columns to extract. */
103502   SrcList *pTabList;     /* List of tables to select from */
103503   Expr *pWhere;          /* The WHERE clause.  May be NULL */
103504   ExprList *pOrderBy;    /* The ORDER BY clause.  May be NULL */
103505   ExprList *pGroupBy;    /* The GROUP BY clause.  May be NULL */
103506   Expr *pHaving;         /* The HAVING clause.  May be NULL */
103507   int rc = 1;            /* Value to return from this function */
103508   int addrSortIndex;     /* Address of an OP_OpenEphemeral instruction */
103509   DistinctCtx sDistinct; /* Info on how to code the DISTINCT keyword */
103510   AggInfo sAggInfo;      /* Information used by aggregate queries */
103511   int iEnd;              /* Address of the end of the query */
103512   sqlite3 *db;           /* The database connection */
103513 
103514 #ifndef SQLITE_OMIT_EXPLAIN
103515   int iRestoreSelectId = pParse->iSelectId;
103516   pParse->iSelectId = pParse->iNextSelectId++;
103517 #endif
103518 
103519   db = pParse->db;
103520   if( p==0 || db->mallocFailed || pParse->nErr ){
103521     return 1;
103522   }
103523   if( sqlite3AuthCheck(pParse, SQLITE_SELECT, 0, 0, 0) ) return 1;
103524   memset(&sAggInfo, 0, sizeof(sAggInfo));
103525 
103526   if( IgnorableOrderby(pDest) ){
103527     assert(pDest->eDest==SRT_Exists || pDest->eDest==SRT_Union || 
103528            pDest->eDest==SRT_Except || pDest->eDest==SRT_Discard);
103529     /* If ORDER BY makes no difference in the output then neither does
103530     ** DISTINCT so it can be removed too. */
103531     sqlite3ExprListDelete(db, p->pOrderBy);
103532     p->pOrderBy = 0;
103533     p->selFlags &= ~SF_Distinct;
103534   }
103535   sqlite3SelectPrep(pParse, p, 0);
103536   pOrderBy = p->pOrderBy;
103537   pTabList = p->pSrc;
103538   pEList = p->pEList;
103539   if( pParse->nErr || db->mallocFailed ){
103540     goto select_end;
103541   }
103542   isAgg = (p->selFlags & SF_Aggregate)!=0;
103543   assert( pEList!=0 );
103544 
103545   /* Begin generating code.
103546   */
103547   v = sqlite3GetVdbe(pParse);
103548   if( v==0 ) goto select_end;
103549 
103550   /* If writing to memory or generating a set
103551   ** only a single column may be output.
103552   */
103553 #ifndef SQLITE_OMIT_SUBQUERY
103554   if( checkForMultiColumnSelectError(pParse, pDest, pEList->nExpr) ){
103555     goto select_end;
103556   }
103557 #endif
103558 
103559   /* Generate code for all sub-queries in the FROM clause
103560   */
103561 #if !defined(SQLITE_OMIT_SUBQUERY) || !defined(SQLITE_OMIT_VIEW)
103562   for(i=0; !p->pPrior && i<pTabList->nSrc; i++){
103563     struct SrcList_item *pItem = &pTabList->a[i];
103564     SelectDest dest;
103565     Select *pSub = pItem->pSelect;
103566     int isAggSub;
103567 
103568     if( pSub==0 ) continue;
103569 
103570     /* Sometimes the code for a subquery will be generated more than
103571     ** once, if the subquery is part of the WHERE clause in a LEFT JOIN,
103572     ** for example.  In that case, do not regenerate the code to manifest
103573     ** a view or the co-routine to implement a view.  The first instance
103574     ** is sufficient, though the subroutine to manifest the view does need
103575     ** to be invoked again. */
103576     if( pItem->addrFillSub ){
103577       if( pItem->viaCoroutine==0 ){
103578         sqlite3VdbeAddOp2(v, OP_Gosub, pItem->regReturn, pItem->addrFillSub);
103579       }
103580       continue;
103581     }
103582 
103583     /* Increment Parse.nHeight by the height of the largest expression
103584     ** tree referred to by this, the parent select. The child select
103585     ** may contain expression trees of at most
103586     ** (SQLITE_MAX_EXPR_DEPTH-Parse.nHeight) height. This is a bit
103587     ** more conservative than necessary, but much easier than enforcing
103588     ** an exact limit.
103589     */
103590     pParse->nHeight += sqlite3SelectExprHeight(p);
103591 
103592     isAggSub = (pSub->selFlags & SF_Aggregate)!=0;
103593     if( flattenSubquery(pParse, p, i, isAgg, isAggSub) ){
103594       /* This subquery can be absorbed into its parent. */
103595       if( isAggSub ){
103596         isAgg = 1;
103597         p->selFlags |= SF_Aggregate;
103598       }
103599       i = -1;
103600     }else if( pTabList->nSrc==1 && (p->selFlags & SF_Materialize)==0
103601       && OptimizationEnabled(db, SQLITE_SubqCoroutine)
103602     ){
103603       /* Implement a co-routine that will return a single row of the result
103604       ** set on each invocation.
103605       */
103606       int addrTop;
103607       int addrEof;
103608       pItem->regReturn = ++pParse->nMem;
103609       addrEof = ++pParse->nMem;
103610       /* Before coding the OP_Goto to jump to the start of the main routine,
103611       ** ensure that the jump to the verify-schema routine has already
103612       ** been coded. Otherwise, the verify-schema would likely be coded as 
103613       ** part of the co-routine. If the main routine then accessed the 
103614       ** database before invoking the co-routine for the first time (for 
103615       ** example to initialize a LIMIT register from a sub-select), it would 
103616       ** be doing so without having verified the schema version and obtained 
103617       ** the required db locks. See ticket d6b36be38.  */
103618       sqlite3CodeVerifySchema(pParse, -1);
103619       sqlite3VdbeAddOp0(v, OP_Goto);
103620       addrTop = sqlite3VdbeAddOp1(v, OP_OpenPseudo, pItem->iCursor);
103621       sqlite3VdbeChangeP5(v, 1);
103622       VdbeComment((v, "coroutine for %s", pItem->pTab->zName));
103623       pItem->addrFillSub = addrTop;
103624       sqlite3VdbeAddOp2(v, OP_Integer, 0, addrEof);
103625       sqlite3VdbeChangeP5(v, 1);
103626       sqlite3SelectDestInit(&dest, SRT_Coroutine, pItem->regReturn);
103627       explainSetInteger(pItem->iSelectId, (u8)pParse->iNextSelectId);
103628       sqlite3Select(pParse, pSub, &dest);
103629       pItem->pTab->nRowEst = (unsigned)pSub->nSelectRow;
103630       pItem->viaCoroutine = 1;
103631       sqlite3VdbeChangeP2(v, addrTop, dest.iSdst);
103632       sqlite3VdbeChangeP3(v, addrTop, dest.nSdst);
103633       sqlite3VdbeAddOp2(v, OP_Integer, 1, addrEof);
103634       sqlite3VdbeAddOp1(v, OP_Yield, pItem->regReturn);
103635       VdbeComment((v, "end %s", pItem->pTab->zName));
103636       sqlite3VdbeJumpHere(v, addrTop-1);
103637       sqlite3ClearTempRegCache(pParse);
103638     }else{
103639       /* Generate a subroutine that will fill an ephemeral table with
103640       ** the content of this subquery.  pItem->addrFillSub will point
103641       ** to the address of the generated subroutine.  pItem->regReturn
103642       ** is a register allocated to hold the subroutine return address
103643       */
103644       int topAddr;
103645       int onceAddr = 0;
103646       int retAddr;
103647       assert( pItem->addrFillSub==0 );
103648       pItem->regReturn = ++pParse->nMem;
103649       topAddr = sqlite3VdbeAddOp2(v, OP_Integer, 0, pItem->regReturn);
103650       pItem->addrFillSub = topAddr+1;
103651       VdbeNoopComment((v, "materialize %s", pItem->pTab->zName));
103652       if( pItem->isCorrelated==0 ){
103653         /* If the subquery is not correlated and if we are not inside of
103654         ** a trigger, then we only need to compute the value of the subquery
103655         ** once. */
103656         onceAddr = sqlite3CodeOnce(pParse);
103657       }
103658       sqlite3SelectDestInit(&dest, SRT_EphemTab, pItem->iCursor);
103659       explainSetInteger(pItem->iSelectId, (u8)pParse->iNextSelectId);
103660       sqlite3Select(pParse, pSub, &dest);
103661       pItem->pTab->nRowEst = (unsigned)pSub->nSelectRow;
103662       if( onceAddr ) sqlite3VdbeJumpHere(v, onceAddr);
103663       retAddr = sqlite3VdbeAddOp1(v, OP_Return, pItem->regReturn);
103664       VdbeComment((v, "end %s", pItem->pTab->zName));
103665       sqlite3VdbeChangeP1(v, topAddr, retAddr);
103666       sqlite3ClearTempRegCache(pParse);
103667     }
103668     if( /*pParse->nErr ||*/ db->mallocFailed ){
103669       goto select_end;
103670     }
103671     pParse->nHeight -= sqlite3SelectExprHeight(p);
103672     pTabList = p->pSrc;
103673     if( !IgnorableOrderby(pDest) ){
103674       pOrderBy = p->pOrderBy;
103675     }
103676   }
103677   pEList = p->pEList;
103678 #endif
103679   pWhere = p->pWhere;
103680   pGroupBy = p->pGroupBy;
103681   pHaving = p->pHaving;
103682   sDistinct.isTnct = (p->selFlags & SF_Distinct)!=0;
103683 
103684 #ifndef SQLITE_OMIT_COMPOUND_SELECT
103685   /* If there is are a sequence of queries, do the earlier ones first.
103686   */
103687   if( p->pPrior ){
103688     if( p->pRightmost==0 ){
103689       Select *pLoop, *pRight = 0;
103690       int cnt = 0;
103691       int mxSelect;
103692       for(pLoop=p; pLoop; pLoop=pLoop->pPrior, cnt++){
103693         pLoop->pRightmost = p;
103694         pLoop->pNext = pRight;
103695         pRight = pLoop;
103696       }
103697       mxSelect = db->aLimit[SQLITE_LIMIT_COMPOUND_SELECT];
103698       if( mxSelect && cnt>mxSelect ){
103699         sqlite3ErrorMsg(pParse, "too many terms in compound SELECT");
103700         goto select_end;
103701       }
103702     }
103703     rc = multiSelect(pParse, p, pDest);
103704     explainSetInteger(pParse->iSelectId, iRestoreSelectId);
103705     return rc;
103706   }
103707 #endif
103708 
103709   /* If there is both a GROUP BY and an ORDER BY clause and they are
103710   ** identical, then disable the ORDER BY clause since the GROUP BY
103711   ** will cause elements to come out in the correct order.  This is
103712   ** an optimization - the correct answer should result regardless.
103713   ** Use the SQLITE_GroupByOrder flag with SQLITE_TESTCTRL_OPTIMIZER
103714   ** to disable this optimization for testing purposes.
103715   */
103716   if( sqlite3ExprListCompare(p->pGroupBy, pOrderBy, -1)==0
103717          && OptimizationEnabled(db, SQLITE_GroupByOrder) ){
103718     pOrderBy = 0;
103719   }
103720 
103721   /* If the query is DISTINCT with an ORDER BY but is not an aggregate, and 
103722   ** if the select-list is the same as the ORDER BY list, then this query
103723   ** can be rewritten as a GROUP BY. In other words, this:
103724   **
103725   **     SELECT DISTINCT xyz FROM ... ORDER BY xyz
103726   **
103727   ** is transformed to:
103728   **
103729   **     SELECT xyz FROM ... GROUP BY xyz
103730   **
103731   ** The second form is preferred as a single index (or temp-table) may be 
103732   ** used for both the ORDER BY and DISTINCT processing. As originally 
103733   ** written the query must use a temp-table for at least one of the ORDER 
103734   ** BY and DISTINCT, and an index or separate temp-table for the other.
103735   */
103736   if( (p->selFlags & (SF_Distinct|SF_Aggregate))==SF_Distinct 
103737    && sqlite3ExprListCompare(pOrderBy, p->pEList, -1)==0
103738   ){
103739     p->selFlags &= ~SF_Distinct;
103740     p->pGroupBy = sqlite3ExprListDup(db, p->pEList, 0);
103741     pGroupBy = p->pGroupBy;
103742     pOrderBy = 0;
103743     /* Notice that even thought SF_Distinct has been cleared from p->selFlags,
103744     ** the sDistinct.isTnct is still set.  Hence, isTnct represents the
103745     ** original setting of the SF_Distinct flag, not the current setting */
103746     assert( sDistinct.isTnct );
103747   }
103748 
103749   /* If there is an ORDER BY clause, then this sorting
103750   ** index might end up being unused if the data can be 
103751   ** extracted in pre-sorted order.  If that is the case, then the
103752   ** OP_OpenEphemeral instruction will be changed to an OP_Noop once
103753   ** we figure out that the sorting index is not needed.  The addrSortIndex
103754   ** variable is used to facilitate that change.
103755   */
103756   if( pOrderBy ){
103757     KeyInfo *pKeyInfo;
103758     pKeyInfo = keyInfoFromExprList(pParse, pOrderBy);
103759     pOrderBy->iECursor = pParse->nTab++;
103760     p->addrOpenEphm[2] = addrSortIndex =
103761       sqlite3VdbeAddOp4(v, OP_OpenEphemeral,
103762                            pOrderBy->iECursor, pOrderBy->nExpr+2, 0,
103763                            (char*)pKeyInfo, P4_KEYINFO);
103764   }else{
103765     addrSortIndex = -1;
103766   }
103767 
103768   /* If the output is destined for a temporary table, open that table.
103769   */
103770   if( pDest->eDest==SRT_EphemTab ){
103771     sqlite3VdbeAddOp2(v, OP_OpenEphemeral, pDest->iSDParm, pEList->nExpr);
103772   }
103773 
103774   /* Set the limiter.
103775   */
103776   iEnd = sqlite3VdbeMakeLabel(v);
103777   p->nSelectRow = LARGEST_INT64;
103778   computeLimitRegisters(pParse, p, iEnd);
103779   if( p->iLimit==0 && addrSortIndex>=0 ){
103780     sqlite3VdbeGetOp(v, addrSortIndex)->opcode = OP_SorterOpen;
103781     p->selFlags |= SF_UseSorter;
103782   }
103783 
103784   /* Open a virtual index to use for the distinct set.
103785   */
103786   if( p->selFlags & SF_Distinct ){
103787     sDistinct.tabTnct = pParse->nTab++;
103788     sDistinct.addrTnct = sqlite3VdbeAddOp4(v, OP_OpenEphemeral,
103789                                 sDistinct.tabTnct, 0, 0,
103790                                 (char*)keyInfoFromExprList(pParse, p->pEList),
103791                                 P4_KEYINFO);
103792     sqlite3VdbeChangeP5(v, BTREE_UNORDERED);
103793     sDistinct.eTnctType = WHERE_DISTINCT_UNORDERED;
103794   }else{
103795     sDistinct.eTnctType = WHERE_DISTINCT_NOOP;
103796   }
103797 
103798   if( !isAgg && pGroupBy==0 ){
103799     /* No aggregate functions and no GROUP BY clause */
103800     u16 wctrlFlags = (sDistinct.isTnct ? WHERE_WANT_DISTINCT : 0);
103801 
103802     /* Begin the database scan. */
103803     pWInfo = sqlite3WhereBegin(pParse, pTabList, pWhere, pOrderBy, p->pEList,
103804                                wctrlFlags, 0);
103805     if( pWInfo==0 ) goto select_end;
103806     if( sqlite3WhereOutputRowCount(pWInfo) < p->nSelectRow ){
103807       p->nSelectRow = sqlite3WhereOutputRowCount(pWInfo);
103808     }
103809     if( sDistinct.isTnct && sqlite3WhereIsDistinct(pWInfo) ){
103810       sDistinct.eTnctType = sqlite3WhereIsDistinct(pWInfo);
103811     }
103812     if( pOrderBy && sqlite3WhereIsOrdered(pWInfo) ) pOrderBy = 0;
103813 
103814     /* If sorting index that was created by a prior OP_OpenEphemeral 
103815     ** instruction ended up not being needed, then change the OP_OpenEphemeral
103816     ** into an OP_Noop.
103817     */
103818     if( addrSortIndex>=0 && pOrderBy==0 ){
103819       sqlite3VdbeChangeToNoop(v, addrSortIndex);
103820       p->addrOpenEphm[2] = -1;
103821     }
103822 
103823     /* Use the standard inner loop. */
103824     selectInnerLoop(pParse, p, pEList, 0, 0, pOrderBy, &sDistinct, pDest,
103825                     sqlite3WhereContinueLabel(pWInfo),
103826                     sqlite3WhereBreakLabel(pWInfo));
103827 
103828     /* End the database scan loop.
103829     */
103830     sqlite3WhereEnd(pWInfo);
103831   }else{
103832     /* This case when there exist aggregate functions or a GROUP BY clause
103833     ** or both */
103834     NameContext sNC;    /* Name context for processing aggregate information */
103835     int iAMem;          /* First Mem address for storing current GROUP BY */
103836     int iBMem;          /* First Mem address for previous GROUP BY */
103837     int iUseFlag;       /* Mem address holding flag indicating that at least
103838                         ** one row of the input to the aggregator has been
103839                         ** processed */
103840     int iAbortFlag;     /* Mem address which causes query abort if positive */
103841     int groupBySort;    /* Rows come from source in GROUP BY order */
103842     int addrEnd;        /* End of processing for this SELECT */
103843     int sortPTab = 0;   /* Pseudotable used to decode sorting results */
103844     int sortOut = 0;    /* Output register from the sorter */
103845 
103846     /* Remove any and all aliases between the result set and the
103847     ** GROUP BY clause.
103848     */
103849     if( pGroupBy ){
103850       int k;                        /* Loop counter */
103851       struct ExprList_item *pItem;  /* For looping over expression in a list */
103852 
103853       for(k=p->pEList->nExpr, pItem=p->pEList->a; k>0; k--, pItem++){
103854         pItem->u.x.iAlias = 0;
103855       }
103856       for(k=pGroupBy->nExpr, pItem=pGroupBy->a; k>0; k--, pItem++){
103857         pItem->u.x.iAlias = 0;
103858       }
103859       if( p->nSelectRow>100 ) p->nSelectRow = 100;
103860     }else{
103861       p->nSelectRow = 1;
103862     }
103863 
103864  
103865     /* Create a label to jump to when we want to abort the query */
103866     addrEnd = sqlite3VdbeMakeLabel(v);
103867 
103868     /* Convert TK_COLUMN nodes into TK_AGG_COLUMN and make entries in
103869     ** sAggInfo for all TK_AGG_FUNCTION nodes in expressions of the
103870     ** SELECT statement.
103871     */
103872     memset(&sNC, 0, sizeof(sNC));
103873     sNC.pParse = pParse;
103874     sNC.pSrcList = pTabList;
103875     sNC.pAggInfo = &sAggInfo;
103876     sAggInfo.nSortingColumn = pGroupBy ? pGroupBy->nExpr+1 : 0;
103877     sAggInfo.pGroupBy = pGroupBy;
103878     sqlite3ExprAnalyzeAggList(&sNC, pEList);
103879     sqlite3ExprAnalyzeAggList(&sNC, pOrderBy);
103880     if( pHaving ){
103881       sqlite3ExprAnalyzeAggregates(&sNC, pHaving);
103882     }
103883     sAggInfo.nAccumulator = sAggInfo.nColumn;
103884     for(i=0; i<sAggInfo.nFunc; i++){
103885       assert( !ExprHasProperty(sAggInfo.aFunc[i].pExpr, EP_xIsSelect) );
103886       sNC.ncFlags |= NC_InAggFunc;
103887       sqlite3ExprAnalyzeAggList(&sNC, sAggInfo.aFunc[i].pExpr->x.pList);
103888       sNC.ncFlags &= ~NC_InAggFunc;
103889     }
103890     if( db->mallocFailed ) goto select_end;
103891 
103892     /* Processing for aggregates with GROUP BY is very different and
103893     ** much more complex than aggregates without a GROUP BY.
103894     */
103895     if( pGroupBy ){
103896       KeyInfo *pKeyInfo;  /* Keying information for the group by clause */
103897       int j1;             /* A-vs-B comparision jump */
103898       int addrOutputRow;  /* Start of subroutine that outputs a result row */
103899       int regOutputRow;   /* Return address register for output subroutine */
103900       int addrSetAbort;   /* Set the abort flag and return */
103901       int addrTopOfLoop;  /* Top of the input loop */
103902       int addrSortingIdx; /* The OP_OpenEphemeral for the sorting index */
103903       int addrReset;      /* Subroutine for resetting the accumulator */
103904       int regReset;       /* Return address register for reset subroutine */
103905 
103906       /* If there is a GROUP BY clause we might need a sorting index to
103907       ** implement it.  Allocate that sorting index now.  If it turns out
103908       ** that we do not need it after all, the OP_SorterOpen instruction
103909       ** will be converted into a Noop.  
103910       */
103911       sAggInfo.sortingIdx = pParse->nTab++;
103912       pKeyInfo = keyInfoFromExprList(pParse, pGroupBy);
103913       addrSortingIdx = sqlite3VdbeAddOp4(v, OP_SorterOpen, 
103914           sAggInfo.sortingIdx, sAggInfo.nSortingColumn, 
103915           0, (char*)pKeyInfo, P4_KEYINFO);
103916 
103917       /* Initialize memory locations used by GROUP BY aggregate processing
103918       */
103919       iUseFlag = ++pParse->nMem;
103920       iAbortFlag = ++pParse->nMem;
103921       regOutputRow = ++pParse->nMem;
103922       addrOutputRow = sqlite3VdbeMakeLabel(v);
103923       regReset = ++pParse->nMem;
103924       addrReset = sqlite3VdbeMakeLabel(v);
103925       iAMem = pParse->nMem + 1;
103926       pParse->nMem += pGroupBy->nExpr;
103927       iBMem = pParse->nMem + 1;
103928       pParse->nMem += pGroupBy->nExpr;
103929       sqlite3VdbeAddOp2(v, OP_Integer, 0, iAbortFlag);
103930       VdbeComment((v, "clear abort flag"));
103931       sqlite3VdbeAddOp2(v, OP_Integer, 0, iUseFlag);
103932       VdbeComment((v, "indicate accumulator empty"));
103933       sqlite3VdbeAddOp3(v, OP_Null, 0, iAMem, iAMem+pGroupBy->nExpr-1);
103934 
103935       /* Begin a loop that will extract all source rows in GROUP BY order.
103936       ** This might involve two separate loops with an OP_Sort in between, or
103937       ** it might be a single loop that uses an index to extract information
103938       ** in the right order to begin with.
103939       */
103940       sqlite3VdbeAddOp2(v, OP_Gosub, regReset, addrReset);
103941       pWInfo = sqlite3WhereBegin(pParse, pTabList, pWhere, pGroupBy, 0, 
103942                                  WHERE_GROUPBY, 0);
103943       if( pWInfo==0 ) goto select_end;
103944       if( sqlite3WhereIsOrdered(pWInfo) ){
103945         /* The optimizer is able to deliver rows in group by order so
103946         ** we do not have to sort.  The OP_OpenEphemeral table will be
103947         ** cancelled later because we still need to use the pKeyInfo
103948         */
103949         groupBySort = 0;
103950       }else{
103951         /* Rows are coming out in undetermined order.  We have to push
103952         ** each row into a sorting index, terminate the first loop,
103953         ** then loop over the sorting index in order to get the output
103954         ** in sorted order
103955         */
103956         int regBase;
103957         int regRecord;
103958         int nCol;
103959         int nGroupBy;
103960 
103961         explainTempTable(pParse, 
103962             (sDistinct.isTnct && (p->selFlags&SF_Distinct)==0) ?
103963                     "DISTINCT" : "GROUP BY");
103964 
103965         groupBySort = 1;
103966         nGroupBy = pGroupBy->nExpr;
103967         nCol = nGroupBy + 1;
103968         j = nGroupBy+1;
103969         for(i=0; i<sAggInfo.nColumn; i++){
103970           if( sAggInfo.aCol[i].iSorterColumn>=j ){
103971             nCol++;
103972             j++;
103973           }
103974         }
103975         regBase = sqlite3GetTempRange(pParse, nCol);
103976         sqlite3ExprCacheClear(pParse);
103977         sqlite3ExprCodeExprList(pParse, pGroupBy, regBase, 0);
103978         sqlite3VdbeAddOp2(v, OP_Sequence, sAggInfo.sortingIdx,regBase+nGroupBy);
103979         j = nGroupBy+1;
103980         for(i=0; i<sAggInfo.nColumn; i++){
103981           struct AggInfo_col *pCol = &sAggInfo.aCol[i];
103982           if( pCol->iSorterColumn>=j ){
103983             int r1 = j + regBase;
103984             int r2;
103985 
103986             r2 = sqlite3ExprCodeGetColumn(pParse, 
103987                                pCol->pTab, pCol->iColumn, pCol->iTable, r1, 0);
103988             if( r1!=r2 ){
103989               sqlite3VdbeAddOp2(v, OP_SCopy, r2, r1);
103990             }
103991             j++;
103992           }
103993         }
103994         regRecord = sqlite3GetTempReg(pParse);
103995         sqlite3VdbeAddOp3(v, OP_MakeRecord, regBase, nCol, regRecord);
103996         sqlite3VdbeAddOp2(v, OP_SorterInsert, sAggInfo.sortingIdx, regRecord);
103997         sqlite3ReleaseTempReg(pParse, regRecord);
103998         sqlite3ReleaseTempRange(pParse, regBase, nCol);
103999         sqlite3WhereEnd(pWInfo);
104000         sAggInfo.sortingIdxPTab = sortPTab = pParse->nTab++;
104001         sortOut = sqlite3GetTempReg(pParse);
104002         sqlite3VdbeAddOp3(v, OP_OpenPseudo, sortPTab, sortOut, nCol);
104003         sqlite3VdbeAddOp2(v, OP_SorterSort, sAggInfo.sortingIdx, addrEnd);
104004         VdbeComment((v, "GROUP BY sort"));
104005         sAggInfo.useSortingIdx = 1;
104006         sqlite3ExprCacheClear(pParse);
104007       }
104008 
104009       /* Evaluate the current GROUP BY terms and store in b0, b1, b2...
104010       ** (b0 is memory location iBMem+0, b1 is iBMem+1, and so forth)
104011       ** Then compare the current GROUP BY terms against the GROUP BY terms
104012       ** from the previous row currently stored in a0, a1, a2...
104013       */
104014       addrTopOfLoop = sqlite3VdbeCurrentAddr(v);
104015       sqlite3ExprCacheClear(pParse);
104016       if( groupBySort ){
104017         sqlite3VdbeAddOp2(v, OP_SorterData, sAggInfo.sortingIdx, sortOut);
104018       }
104019       for(j=0; j<pGroupBy->nExpr; j++){
104020         if( groupBySort ){
104021           sqlite3VdbeAddOp3(v, OP_Column, sortPTab, j, iBMem+j);
104022           if( j==0 ) sqlite3VdbeChangeP5(v, OPFLAG_CLEARCACHE);
104023         }else{
104024           sAggInfo.directMode = 1;
104025           sqlite3ExprCode(pParse, pGroupBy->a[j].pExpr, iBMem+j);
104026         }
104027       }
104028       sqlite3VdbeAddOp4(v, OP_Compare, iAMem, iBMem, pGroupBy->nExpr,
104029                           (char*)sqlite3KeyInfoRef(pKeyInfo), P4_KEYINFO);
104030       j1 = sqlite3VdbeCurrentAddr(v);
104031       sqlite3VdbeAddOp3(v, OP_Jump, j1+1, 0, j1+1);
104032 
104033       /* Generate code that runs whenever the GROUP BY changes.
104034       ** Changes in the GROUP BY are detected by the previous code
104035       ** block.  If there were no changes, this block is skipped.
104036       **
104037       ** This code copies current group by terms in b0,b1,b2,...
104038       ** over to a0,a1,a2.  It then calls the output subroutine
104039       ** and resets the aggregate accumulator registers in preparation
104040       ** for the next GROUP BY batch.
104041       */
104042       sqlite3ExprCodeMove(pParse, iBMem, iAMem, pGroupBy->nExpr);
104043       sqlite3VdbeAddOp2(v, OP_Gosub, regOutputRow, addrOutputRow);
104044       VdbeComment((v, "output one row"));
104045       sqlite3VdbeAddOp2(v, OP_IfPos, iAbortFlag, addrEnd);
104046       VdbeComment((v, "check abort flag"));
104047       sqlite3VdbeAddOp2(v, OP_Gosub, regReset, addrReset);
104048       VdbeComment((v, "reset accumulator"));
104049 
104050       /* Update the aggregate accumulators based on the content of
104051       ** the current row
104052       */
104053       sqlite3VdbeJumpHere(v, j1);
104054       updateAccumulator(pParse, &sAggInfo);
104055       sqlite3VdbeAddOp2(v, OP_Integer, 1, iUseFlag);
104056       VdbeComment((v, "indicate data in accumulator"));
104057 
104058       /* End of the loop
104059       */
104060       if( groupBySort ){
104061         sqlite3VdbeAddOp2(v, OP_SorterNext, sAggInfo.sortingIdx, addrTopOfLoop);
104062       }else{
104063         sqlite3WhereEnd(pWInfo);
104064         sqlite3VdbeChangeToNoop(v, addrSortingIdx);
104065       }
104066 
104067       /* Output the final row of result
104068       */
104069       sqlite3VdbeAddOp2(v, OP_Gosub, regOutputRow, addrOutputRow);
104070       VdbeComment((v, "output final row"));
104071 
104072       /* Jump over the subroutines
104073       */
104074       sqlite3VdbeAddOp2(v, OP_Goto, 0, addrEnd);
104075 
104076       /* Generate a subroutine that outputs a single row of the result
104077       ** set.  This subroutine first looks at the iUseFlag.  If iUseFlag
104078       ** is less than or equal to zero, the subroutine is a no-op.  If
104079       ** the processing calls for the query to abort, this subroutine
104080       ** increments the iAbortFlag memory location before returning in
104081       ** order to signal the caller to abort.
104082       */
104083       addrSetAbort = sqlite3VdbeCurrentAddr(v);
104084       sqlite3VdbeAddOp2(v, OP_Integer, 1, iAbortFlag);
104085       VdbeComment((v, "set abort flag"));
104086       sqlite3VdbeAddOp1(v, OP_Return, regOutputRow);
104087       sqlite3VdbeResolveLabel(v, addrOutputRow);
104088       addrOutputRow = sqlite3VdbeCurrentAddr(v);
104089       sqlite3VdbeAddOp2(v, OP_IfPos, iUseFlag, addrOutputRow+2);
104090       VdbeComment((v, "Groupby result generator entry point"));
104091       sqlite3VdbeAddOp1(v, OP_Return, regOutputRow);
104092       finalizeAggFunctions(pParse, &sAggInfo);
104093       sqlite3ExprIfFalse(pParse, pHaving, addrOutputRow+1, SQLITE_JUMPIFNULL);
104094       selectInnerLoop(pParse, p, p->pEList, 0, 0, pOrderBy,
104095                       &sDistinct, pDest,
104096                       addrOutputRow+1, addrSetAbort);
104097       sqlite3VdbeAddOp1(v, OP_Return, regOutputRow);
104098       VdbeComment((v, "end groupby result generator"));
104099 
104100       /* Generate a subroutine that will reset the group-by accumulator
104101       */
104102       sqlite3VdbeResolveLabel(v, addrReset);
104103       resetAccumulator(pParse, &sAggInfo);
104104       sqlite3VdbeAddOp1(v, OP_Return, regReset);
104105      
104106     } /* endif pGroupBy.  Begin aggregate queries without GROUP BY: */
104107     else {
104108       ExprList *pDel = 0;
104109 #ifndef SQLITE_OMIT_BTREECOUNT
104110       Table *pTab;
104111       if( (pTab = isSimpleCount(p, &sAggInfo))!=0 ){
104112         /* If isSimpleCount() returns a pointer to a Table structure, then
104113         ** the SQL statement is of the form:
104114         **
104115         **   SELECT count(*) FROM <tbl>
104116         **
104117         ** where the Table structure returned represents table <tbl>.
104118         **
104119         ** This statement is so common that it is optimized specially. The
104120         ** OP_Count instruction is executed either on the intkey table that
104121         ** contains the data for table <tbl> or on one of its indexes. It
104122         ** is better to execute the op on an index, as indexes are almost
104123         ** always spread across less pages than their corresponding tables.
104124         */
104125         const int iDb = sqlite3SchemaToIndex(pParse->db, pTab->pSchema);
104126         const int iCsr = pParse->nTab++;     /* Cursor to scan b-tree */
104127         Index *pIdx;                         /* Iterator variable */
104128         KeyInfo *pKeyInfo = 0;               /* Keyinfo for scanned index */
104129         Index *pBest = 0;                    /* Best index found so far */
104130         int iRoot = pTab->tnum;              /* Root page of scanned b-tree */
104131 
104132         sqlite3CodeVerifySchema(pParse, iDb);
104133         sqlite3TableLock(pParse, iDb, pTab->tnum, 0, pTab->zName);
104134 
104135         /* Search for the index that has the lowest scan cost.
104136         **
104137         ** (2011-04-15) Do not do a full scan of an unordered index.
104138         **
104139         ** (2013-10-03) Do not count the entries in a partial index.
104140         **
104141         ** In practice the KeyInfo structure will not be used. It is only 
104142         ** passed to keep OP_OpenRead happy.
104143         */
104144         if( !HasRowid(pTab) ) pBest = sqlite3PrimaryKeyIndex(pTab);
104145         for(pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext){
104146           if( pIdx->bUnordered==0
104147            && pIdx->szIdxRow<pTab->szTabRow
104148            && pIdx->pPartIdxWhere==0
104149            && (!pBest || pIdx->szIdxRow<pBest->szIdxRow)
104150           ){
104151             pBest = pIdx;
104152           }
104153         }
104154         if( pBest ){
104155           iRoot = pBest->tnum;
104156           pKeyInfo = sqlite3KeyInfoOfIndex(pParse, pBest);
104157         }
104158 
104159         /* Open a read-only cursor, execute the OP_Count, close the cursor. */
104160         sqlite3VdbeAddOp4Int(v, OP_OpenRead, iCsr, iRoot, iDb, 1);
104161         if( pKeyInfo ){
104162           sqlite3VdbeChangeP4(v, -1, (char *)pKeyInfo, P4_KEYINFO);
104163         }
104164         sqlite3VdbeAddOp2(v, OP_Count, iCsr, sAggInfo.aFunc[0].iMem);
104165         sqlite3VdbeAddOp1(v, OP_Close, iCsr);
104166         explainSimpleCount(pParse, pTab, pBest);
104167       }else
104168 #endif /* SQLITE_OMIT_BTREECOUNT */
104169       {
104170         /* Check if the query is of one of the following forms:
104171         **
104172         **   SELECT min(x) FROM ...
104173         **   SELECT max(x) FROM ...
104174         **
104175         ** If it is, then ask the code in where.c to attempt to sort results
104176         ** as if there was an "ORDER ON x" or "ORDER ON x DESC" clause. 
104177         ** If where.c is able to produce results sorted in this order, then
104178         ** add vdbe code to break out of the processing loop after the 
104179         ** first iteration (since the first iteration of the loop is 
104180         ** guaranteed to operate on the row with the minimum or maximum 
104181         ** value of x, the only row required).
104182         **
104183         ** A special flag must be passed to sqlite3WhereBegin() to slightly
104184         ** modify behavior as follows:
104185         **
104186         **   + If the query is a "SELECT min(x)", then the loop coded by
104187         **     where.c should not iterate over any values with a NULL value
104188         **     for x.
104189         **
104190         **   + The optimizer code in where.c (the thing that decides which
104191         **     index or indices to use) should place a different priority on 
104192         **     satisfying the 'ORDER BY' clause than it does in other cases.
104193         **     Refer to code and comments in where.c for details.
104194         */
104195         ExprList *pMinMax = 0;
104196         u8 flag = WHERE_ORDERBY_NORMAL;
104197         
104198         assert( p->pGroupBy==0 );
104199         assert( flag==0 );
104200         if( p->pHaving==0 ){
104201           flag = minMaxQuery(&sAggInfo, &pMinMax);
104202         }
104203         assert( flag==0 || (pMinMax!=0 && pMinMax->nExpr==1) );
104204 
104205         if( flag ){
104206           pMinMax = sqlite3ExprListDup(db, pMinMax, 0);
104207           pDel = pMinMax;
104208           if( pMinMax && !db->mallocFailed ){
104209             pMinMax->a[0].sortOrder = flag!=WHERE_ORDERBY_MIN ?1:0;
104210             pMinMax->a[0].pExpr->op = TK_COLUMN;
104211           }
104212         }
104213   
104214         /* This case runs if the aggregate has no GROUP BY clause.  The
104215         ** processing is much simpler since there is only a single row
104216         ** of output.
104217         */
104218         resetAccumulator(pParse, &sAggInfo);
104219         pWInfo = sqlite3WhereBegin(pParse, pTabList, pWhere, pMinMax,0,flag,0);
104220         if( pWInfo==0 ){
104221           sqlite3ExprListDelete(db, pDel);
104222           goto select_end;
104223         }
104224         updateAccumulator(pParse, &sAggInfo);
104225         assert( pMinMax==0 || pMinMax->nExpr==1 );
104226         if( sqlite3WhereIsOrdered(pWInfo) ){
104227           sqlite3VdbeAddOp2(v, OP_Goto, 0, sqlite3WhereBreakLabel(pWInfo));
104228           VdbeComment((v, "%s() by index",
104229                 (flag==WHERE_ORDERBY_MIN?"min":"max")));
104230         }
104231         sqlite3WhereEnd(pWInfo);
104232         finalizeAggFunctions(pParse, &sAggInfo);
104233       }
104234 
104235       pOrderBy = 0;
104236       sqlite3ExprIfFalse(pParse, pHaving, addrEnd, SQLITE_JUMPIFNULL);
104237       selectInnerLoop(pParse, p, p->pEList, 0, 0, 0, 0, 
104238                       pDest, addrEnd, addrEnd);
104239       sqlite3ExprListDelete(db, pDel);
104240     }
104241     sqlite3VdbeResolveLabel(v, addrEnd);
104242     
104243   } /* endif aggregate query */
104244 
104245   if( sDistinct.eTnctType==WHERE_DISTINCT_UNORDERED ){
104246     explainTempTable(pParse, "DISTINCT");
104247   }
104248 
104249   /* If there is an ORDER BY clause, then we need to sort the results
104250   ** and send them to the callback one by one.
104251   */
104252   if( pOrderBy ){
104253     explainTempTable(pParse, "ORDER BY");
104254     generateSortTail(pParse, p, v, pEList->nExpr, pDest);
104255   }
104256 
104257   /* Jump here to skip this query
104258   */
104259   sqlite3VdbeResolveLabel(v, iEnd);
104260 
104261   /* The SELECT was successfully coded.   Set the return code to 0
104262   ** to indicate no errors.
104263   */
104264   rc = 0;
104265 
104266   /* Control jumps to here if an error is encountered above, or upon
104267   ** successful coding of the SELECT.
104268   */
104269 select_end:
104270   explainSetInteger(pParse->iSelectId, iRestoreSelectId);
104271 
104272   /* Identify column names if results of the SELECT are to be output.
104273   */
104274   if( rc==SQLITE_OK && pDest->eDest==SRT_Output ){
104275     generateColumnNames(pParse, pTabList, pEList);
104276   }
104277 
104278   sqlite3DbFree(db, sAggInfo.aCol);
104279   sqlite3DbFree(db, sAggInfo.aFunc);
104280   return rc;
104281 }
104282 
104283 #if defined(SQLITE_ENABLE_TREE_EXPLAIN)
104284 /*
104285 ** Generate a human-readable description of a the Select object.
104286 */
104287 static void explainOneSelect(Vdbe *pVdbe, Select *p){
104288   sqlite3ExplainPrintf(pVdbe, "SELECT ");
104289   if( p->selFlags & (SF_Distinct|SF_Aggregate) ){
104290     if( p->selFlags & SF_Distinct ){
104291       sqlite3ExplainPrintf(pVdbe, "DISTINCT ");
104292     }
104293     if( p->selFlags & SF_Aggregate ){
104294       sqlite3ExplainPrintf(pVdbe, "agg_flag ");
104295     }
104296     sqlite3ExplainNL(pVdbe);
104297     sqlite3ExplainPrintf(pVdbe, "   ");
104298   }
104299   sqlite3ExplainExprList(pVdbe, p->pEList);
104300   sqlite3ExplainNL(pVdbe);
104301   if( p->pSrc && p->pSrc->nSrc ){
104302     int i;
104303     sqlite3ExplainPrintf(pVdbe, "FROM ");
104304     sqlite3ExplainPush(pVdbe);
104305     for(i=0; i<p->pSrc->nSrc; i++){
104306       struct SrcList_item *pItem = &p->pSrc->a[i];
104307       sqlite3ExplainPrintf(pVdbe, "{%d,*} = ", pItem->iCursor);
104308       if( pItem->pSelect ){
104309         sqlite3ExplainSelect(pVdbe, pItem->pSelect);
104310         if( pItem->pTab ){
104311           sqlite3ExplainPrintf(pVdbe, " (tabname=%s)", pItem->pTab->zName);
104312         }
104313       }else if( pItem->zName ){
104314         sqlite3ExplainPrintf(pVdbe, "%s", pItem->zName);
104315       }
104316       if( pItem->zAlias ){
104317         sqlite3ExplainPrintf(pVdbe, " (AS %s)", pItem->zAlias);
104318       }
104319       if( pItem->jointype & JT_LEFT ){
104320         sqlite3ExplainPrintf(pVdbe, " LEFT-JOIN");
104321       }
104322       sqlite3ExplainNL(pVdbe);
104323     }
104324     sqlite3ExplainPop(pVdbe);
104325   }
104326   if( p->pWhere ){
104327     sqlite3ExplainPrintf(pVdbe, "WHERE ");
104328     sqlite3ExplainExpr(pVdbe, p->pWhere);
104329     sqlite3ExplainNL(pVdbe);
104330   }
104331   if( p->pGroupBy ){
104332     sqlite3ExplainPrintf(pVdbe, "GROUPBY ");
104333     sqlite3ExplainExprList(pVdbe, p->pGroupBy);
104334     sqlite3ExplainNL(pVdbe);
104335   }
104336   if( p->pHaving ){
104337     sqlite3ExplainPrintf(pVdbe, "HAVING ");
104338     sqlite3ExplainExpr(pVdbe, p->pHaving);
104339     sqlite3ExplainNL(pVdbe);
104340   }
104341   if( p->pOrderBy ){
104342     sqlite3ExplainPrintf(pVdbe, "ORDERBY ");
104343     sqlite3ExplainExprList(pVdbe, p->pOrderBy);
104344     sqlite3ExplainNL(pVdbe);
104345   }
104346   if( p->pLimit ){
104347     sqlite3ExplainPrintf(pVdbe, "LIMIT ");
104348     sqlite3ExplainExpr(pVdbe, p->pLimit);
104349     sqlite3ExplainNL(pVdbe);
104350   }
104351   if( p->pOffset ){
104352     sqlite3ExplainPrintf(pVdbe, "OFFSET ");
104353     sqlite3ExplainExpr(pVdbe, p->pOffset);
104354     sqlite3ExplainNL(pVdbe);
104355   }
104356 }
104357 SQLITE_PRIVATE void sqlite3ExplainSelect(Vdbe *pVdbe, Select *p){
104358   if( p==0 ){
104359     sqlite3ExplainPrintf(pVdbe, "(null-select)");
104360     return;
104361   }
104362   while( p->pPrior ){
104363     p->pPrior->pNext = p;
104364     p = p->pPrior;
104365   }
104366   sqlite3ExplainPush(pVdbe);
104367   while( p ){
104368     explainOneSelect(pVdbe, p);
104369     p = p->pNext;
104370     if( p==0 ) break;
104371     sqlite3ExplainNL(pVdbe);
104372     sqlite3ExplainPrintf(pVdbe, "%s\n", selectOpName(p->op));
104373   }
104374   sqlite3ExplainPrintf(pVdbe, "END");
104375   sqlite3ExplainPop(pVdbe);
104376 }
104377 
104378 /* End of the structure debug printing code
104379 *****************************************************************************/
104380 #endif /* defined(SQLITE_ENABLE_TREE_EXPLAIN) */
104381 
104382 /************** End of select.c **********************************************/
104383 /************** Begin file table.c *******************************************/
104384 /*
104385 ** 2001 September 15
104386 **
104387 ** The author disclaims copyright to this source code.  In place of
104388 ** a legal notice, here is a blessing:
104389 **
104390 **    May you do good and not evil.
104391 **    May you find forgiveness for yourself and forgive others.
104392 **    May you share freely, never taking more than you give.
104393 **
104394 *************************************************************************
104395 ** This file contains the sqlite3_get_table() and sqlite3_free_table()
104396 ** interface routines.  These are just wrappers around the main
104397 ** interface routine of sqlite3_exec().
104398 **
104399 ** These routines are in a separate files so that they will not be linked
104400 ** if they are not used.
104401 */
104402 /* #include <stdlib.h> */
104403 /* #include <string.h> */
104404 
104405 #ifndef SQLITE_OMIT_GET_TABLE
104406 
104407 /*
104408 ** This structure is used to pass data from sqlite3_get_table() through
104409 ** to the callback function is uses to build the result.
104410 */
104411 typedef struct TabResult {
104412   char **azResult;   /* Accumulated output */
104413   char *zErrMsg;     /* Error message text, if an error occurs */
104414   int nAlloc;        /* Slots allocated for azResult[] */
104415   int nRow;          /* Number of rows in the result */
104416   int nColumn;       /* Number of columns in the result */
104417   int nData;         /* Slots used in azResult[].  (nRow+1)*nColumn */
104418   int rc;            /* Return code from sqlite3_exec() */
104419 } TabResult;
104420 
104421 /*
104422 ** This routine is called once for each row in the result table.  Its job
104423 ** is to fill in the TabResult structure appropriately, allocating new
104424 ** memory as necessary.
104425 */
104426 static int sqlite3_get_table_cb(void *pArg, int nCol, char **argv, char **colv){
104427   TabResult *p = (TabResult*)pArg;  /* Result accumulator */
104428   int need;                         /* Slots needed in p->azResult[] */
104429   int i;                            /* Loop counter */
104430   char *z;                          /* A single column of result */
104431 
104432   /* Make sure there is enough space in p->azResult to hold everything
104433   ** we need to remember from this invocation of the callback.
104434   */
104435   if( p->nRow==0 && argv!=0 ){
104436     need = nCol*2;
104437   }else{
104438     need = nCol;
104439   }
104440   if( p->nData + need > p->nAlloc ){
104441     char **azNew;
104442     p->nAlloc = p->nAlloc*2 + need;
104443     azNew = sqlite3_realloc( p->azResult, sizeof(char*)*p->nAlloc );
104444     if( azNew==0 ) goto malloc_failed;
104445     p->azResult = azNew;
104446   }
104447 
104448   /* If this is the first row, then generate an extra row containing
104449   ** the names of all columns.
104450   */
104451   if( p->nRow==0 ){
104452     p->nColumn = nCol;
104453     for(i=0; i<nCol; i++){
104454       z = sqlite3_mprintf("%s", colv[i]);
104455       if( z==0 ) goto malloc_failed;
104456       p->azResult[p->nData++] = z;
104457     }
104458   }else if( p->nColumn!=nCol ){
104459     sqlite3_free(p->zErrMsg);
104460     p->zErrMsg = sqlite3_mprintf(
104461        "sqlite3_get_table() called with two or more incompatible queries"
104462     );
104463     p->rc = SQLITE_ERROR;
104464     return 1;
104465   }
104466 
104467   /* Copy over the row data
104468   */
104469   if( argv!=0 ){
104470     for(i=0; i<nCol; i++){
104471       if( argv[i]==0 ){
104472         z = 0;
104473       }else{
104474         int n = sqlite3Strlen30(argv[i])+1;
104475         z = sqlite3_malloc( n );
104476         if( z==0 ) goto malloc_failed;
104477         memcpy(z, argv[i], n);
104478       }
104479       p->azResult[p->nData++] = z;
104480     }
104481     p->nRow++;
104482   }
104483   return 0;
104484 
104485 malloc_failed:
104486   p->rc = SQLITE_NOMEM;
104487   return 1;
104488 }
104489 
104490 /*
104491 ** Query the database.  But instead of invoking a callback for each row,
104492 ** malloc() for space to hold the result and return the entire results
104493 ** at the conclusion of the call.
104494 **
104495 ** The result that is written to ***pazResult is held in memory obtained
104496 ** from malloc().  But the caller cannot free this memory directly.  
104497 ** Instead, the entire table should be passed to sqlite3_free_table() when
104498 ** the calling procedure is finished using it.
104499 */
104500 SQLITE_API int sqlite3_get_table(
104501   sqlite3 *db,                /* The database on which the SQL executes */
104502   const char *zSql,           /* The SQL to be executed */
104503   char ***pazResult,          /* Write the result table here */
104504   int *pnRow,                 /* Write the number of rows in the result here */
104505   int *pnColumn,              /* Write the number of columns of result here */
104506   char **pzErrMsg             /* Write error messages here */
104507 ){
104508   int rc;
104509   TabResult res;
104510 
104511   *pazResult = 0;
104512   if( pnColumn ) *pnColumn = 0;
104513   if( pnRow ) *pnRow = 0;
104514   if( pzErrMsg ) *pzErrMsg = 0;
104515   res.zErrMsg = 0;
104516   res.nRow = 0;
104517   res.nColumn = 0;
104518   res.nData = 1;
104519   res.nAlloc = 20;
104520   res.rc = SQLITE_OK;
104521   res.azResult = sqlite3_malloc(sizeof(char*)*res.nAlloc );
104522   if( res.azResult==0 ){
104523      db->errCode = SQLITE_NOMEM;
104524      return SQLITE_NOMEM;
104525   }
104526   res.azResult[0] = 0;
104527   rc = sqlite3_exec(db, zSql, sqlite3_get_table_cb, &res, pzErrMsg);
104528   assert( sizeof(res.azResult[0])>= sizeof(res.nData) );
104529   res.azResult[0] = SQLITE_INT_TO_PTR(res.nData);
104530   if( (rc&0xff)==SQLITE_ABORT ){
104531     sqlite3_free_table(&res.azResult[1]);
104532     if( res.zErrMsg ){
104533       if( pzErrMsg ){
104534         sqlite3_free(*pzErrMsg);
104535         *pzErrMsg = sqlite3_mprintf("%s",res.zErrMsg);
104536       }
104537       sqlite3_free(res.zErrMsg);
104538     }
104539     db->errCode = res.rc;  /* Assume 32-bit assignment is atomic */
104540     return res.rc;
104541   }
104542   sqlite3_free(res.zErrMsg);
104543   if( rc!=SQLITE_OK ){
104544     sqlite3_free_table(&res.azResult[1]);
104545     return rc;
104546   }
104547   if( res.nAlloc>res.nData ){
104548     char **azNew;
104549     azNew = sqlite3_realloc( res.azResult, sizeof(char*)*res.nData );
104550     if( azNew==0 ){
104551       sqlite3_free_table(&res.azResult[1]);
104552       db->errCode = SQLITE_NOMEM;
104553       return SQLITE_NOMEM;
104554     }
104555     res.azResult = azNew;
104556   }
104557   *pazResult = &res.azResult[1];
104558   if( pnColumn ) *pnColumn = res.nColumn;
104559   if( pnRow ) *pnRow = res.nRow;
104560   return rc;
104561 }
104562 
104563 /*
104564 ** This routine frees the space the sqlite3_get_table() malloced.
104565 */
104566 SQLITE_API void sqlite3_free_table(
104567   char **azResult            /* Result returned from from sqlite3_get_table() */
104568 ){
104569   if( azResult ){
104570     int i, n;
104571     azResult--;
104572     assert( azResult!=0 );
104573     n = SQLITE_PTR_TO_INT(azResult[0]);
104574     for(i=1; i<n; i++){ if( azResult[i] ) sqlite3_free(azResult[i]); }
104575     sqlite3_free(azResult);
104576   }
104577 }
104578 
104579 #endif /* SQLITE_OMIT_GET_TABLE */
104580 
104581 /************** End of table.c ***********************************************/
104582 /************** Begin file trigger.c *****************************************/
104583 /*
104584 **
104585 ** The author disclaims copyright to this source code.  In place of
104586 ** a legal notice, here is a blessing:
104587 **
104588 **    May you do good and not evil.
104589 **    May you find forgiveness for yourself and forgive others.
104590 **    May you share freely, never taking more than you give.
104591 **
104592 *************************************************************************
104593 ** This file contains the implementation for TRIGGERs
104594 */
104595 
104596 #ifndef SQLITE_OMIT_TRIGGER
104597 /*
104598 ** Delete a linked list of TriggerStep structures.
104599 */
104600 SQLITE_PRIVATE void sqlite3DeleteTriggerStep(sqlite3 *db, TriggerStep *pTriggerStep){
104601   while( pTriggerStep ){
104602     TriggerStep * pTmp = pTriggerStep;
104603     pTriggerStep = pTriggerStep->pNext;
104604 
104605     sqlite3ExprDelete(db, pTmp->pWhere);
104606     sqlite3ExprListDelete(db, pTmp->pExprList);
104607     sqlite3SelectDelete(db, pTmp->pSelect);
104608     sqlite3IdListDelete(db, pTmp->pIdList);
104609 
104610     sqlite3DbFree(db, pTmp);
104611   }
104612 }
104613 
104614 /*
104615 ** Given table pTab, return a list of all the triggers attached to 
104616 ** the table. The list is connected by Trigger.pNext pointers.
104617 **
104618 ** All of the triggers on pTab that are in the same database as pTab
104619 ** are already attached to pTab->pTrigger.  But there might be additional
104620 ** triggers on pTab in the TEMP schema.  This routine prepends all
104621 ** TEMP triggers on pTab to the beginning of the pTab->pTrigger list
104622 ** and returns the combined list.
104623 **
104624 ** To state it another way:  This routine returns a list of all triggers
104625 ** that fire off of pTab.  The list will include any TEMP triggers on
104626 ** pTab as well as the triggers lised in pTab->pTrigger.
104627 */
104628 SQLITE_PRIVATE Trigger *sqlite3TriggerList(Parse *pParse, Table *pTab){
104629   Schema * const pTmpSchema = pParse->db->aDb[1].pSchema;
104630   Trigger *pList = 0;                  /* List of triggers to return */
104631 
104632   if( pParse->disableTriggers ){
104633     return 0;
104634   }
104635 
104636   if( pTmpSchema!=pTab->pSchema ){
104637     HashElem *p;
104638     assert( sqlite3SchemaMutexHeld(pParse->db, 0, pTmpSchema) );
104639     for(p=sqliteHashFirst(&pTmpSchema->trigHash); p; p=sqliteHashNext(p)){
104640       Trigger *pTrig = (Trigger *)sqliteHashData(p);
104641       if( pTrig->pTabSchema==pTab->pSchema
104642        && 0==sqlite3StrICmp(pTrig->table, pTab->zName) 
104643       ){
104644         pTrig->pNext = (pList ? pList : pTab->pTrigger);
104645         pList = pTrig;
104646       }
104647     }
104648   }
104649 
104650   return (pList ? pList : pTab->pTrigger);
104651 }
104652 
104653 /*
104654 ** This is called by the parser when it sees a CREATE TRIGGER statement
104655 ** up to the point of the BEGIN before the trigger actions.  A Trigger
104656 ** structure is generated based on the information available and stored
104657 ** in pParse->pNewTrigger.  After the trigger actions have been parsed, the
104658 ** sqlite3FinishTrigger() function is called to complete the trigger
104659 ** construction process.
104660 */
104661 SQLITE_PRIVATE void sqlite3BeginTrigger(
104662   Parse *pParse,      /* The parse context of the CREATE TRIGGER statement */
104663   Token *pName1,      /* The name of the trigger */
104664   Token *pName2,      /* The name of the trigger */
104665   int tr_tm,          /* One of TK_BEFORE, TK_AFTER, TK_INSTEAD */
104666   int op,             /* One of TK_INSERT, TK_UPDATE, TK_DELETE */
104667   IdList *pColumns,   /* column list if this is an UPDATE OF trigger */
104668   SrcList *pTableName,/* The name of the table/view the trigger applies to */
104669   Expr *pWhen,        /* WHEN clause */
104670   int isTemp,         /* True if the TEMPORARY keyword is present */
104671   int noErr           /* Suppress errors if the trigger already exists */
104672 ){
104673   Trigger *pTrigger = 0;  /* The new trigger */
104674   Table *pTab;            /* Table that the trigger fires off of */
104675   char *zName = 0;        /* Name of the trigger */
104676   sqlite3 *db = pParse->db;  /* The database connection */
104677   int iDb;                /* The database to store the trigger in */
104678   Token *pName;           /* The unqualified db name */
104679   DbFixer sFix;           /* State vector for the DB fixer */
104680   int iTabDb;             /* Index of the database holding pTab */
104681 
104682   assert( pName1!=0 );   /* pName1->z might be NULL, but not pName1 itself */
104683   assert( pName2!=0 );
104684   assert( op==TK_INSERT || op==TK_UPDATE || op==TK_DELETE );
104685   assert( op>0 && op<0xff );
104686   if( isTemp ){
104687     /* If TEMP was specified, then the trigger name may not be qualified. */
104688     if( pName2->n>0 ){
104689       sqlite3ErrorMsg(pParse, "temporary trigger may not have qualified name");
104690       goto trigger_cleanup;
104691     }
104692     iDb = 1;
104693     pName = pName1;
104694   }else{
104695     /* Figure out the db that the trigger will be created in */
104696     iDb = sqlite3TwoPartName(pParse, pName1, pName2, &pName);
104697     if( iDb<0 ){
104698       goto trigger_cleanup;
104699     }
104700   }
104701   if( !pTableName || db->mallocFailed ){
104702     goto trigger_cleanup;
104703   }
104704 
104705   /* A long-standing parser bug is that this syntax was allowed:
104706   **
104707   **    CREATE TRIGGER attached.demo AFTER INSERT ON attached.tab ....
104708   **                                                 ^^^^^^^^
104709   **
104710   ** To maintain backwards compatibility, ignore the database
104711   ** name on pTableName if we are reparsing our of SQLITE_MASTER.
104712   */
104713   if( db->init.busy && iDb!=1 ){
104714     sqlite3DbFree(db, pTableName->a[0].zDatabase);
104715     pTableName->a[0].zDatabase = 0;
104716   }
104717 
104718   /* If the trigger name was unqualified, and the table is a temp table,
104719   ** then set iDb to 1 to create the trigger in the temporary database.
104720   ** If sqlite3SrcListLookup() returns 0, indicating the table does not
104721   ** exist, the error is caught by the block below.
104722   */
104723   pTab = sqlite3SrcListLookup(pParse, pTableName);
104724   if( db->init.busy==0 && pName2->n==0 && pTab
104725         && pTab->pSchema==db->aDb[1].pSchema ){
104726     iDb = 1;
104727   }
104728 
104729   /* Ensure the table name matches database name and that the table exists */
104730   if( db->mallocFailed ) goto trigger_cleanup;
104731   assert( pTableName->nSrc==1 );
104732   sqlite3FixInit(&sFix, pParse, iDb, "trigger", pName);
104733   if( sqlite3FixSrcList(&sFix, pTableName) ){
104734     goto trigger_cleanup;
104735   }
104736   pTab = sqlite3SrcListLookup(pParse, pTableName);
104737   if( !pTab ){
104738     /* The table does not exist. */
104739     if( db->init.iDb==1 ){
104740       /* Ticket #3810.
104741       ** Normally, whenever a table is dropped, all associated triggers are
104742       ** dropped too.  But if a TEMP trigger is created on a non-TEMP table
104743       ** and the table is dropped by a different database connection, the
104744       ** trigger is not visible to the database connection that does the
104745       ** drop so the trigger cannot be dropped.  This results in an
104746       ** "orphaned trigger" - a trigger whose associated table is missing.
104747       */
104748       db->init.orphanTrigger = 1;
104749     }
104750     goto trigger_cleanup;
104751   }
104752   if( IsVirtual(pTab) ){
104753     sqlite3ErrorMsg(pParse, "cannot create triggers on virtual tables");
104754     goto trigger_cleanup;
104755   }
104756 
104757   /* Check that the trigger name is not reserved and that no trigger of the
104758   ** specified name exists */
104759   zName = sqlite3NameFromToken(db, pName);
104760   if( !zName || SQLITE_OK!=sqlite3CheckObjectName(pParse, zName) ){
104761     goto trigger_cleanup;
104762   }
104763   assert( sqlite3SchemaMutexHeld(db, iDb, 0) );
104764   if( sqlite3HashFind(&(db->aDb[iDb].pSchema->trigHash),
104765                       zName, sqlite3Strlen30(zName)) ){
104766     if( !noErr ){
104767       sqlite3ErrorMsg(pParse, "trigger %T already exists", pName);
104768     }else{
104769       assert( !db->init.busy );
104770       sqlite3CodeVerifySchema(pParse, iDb);
104771     }
104772     goto trigger_cleanup;
104773   }
104774 
104775   /* Do not create a trigger on a system table */
104776   if( sqlite3StrNICmp(pTab->zName, "sqlite_", 7)==0 ){
104777     sqlite3ErrorMsg(pParse, "cannot create trigger on system table");
104778     pParse->nErr++;
104779     goto trigger_cleanup;
104780   }
104781 
104782   /* INSTEAD of triggers are only for views and views only support INSTEAD
104783   ** of triggers.
104784   */
104785   if( pTab->pSelect && tr_tm!=TK_INSTEAD ){
104786     sqlite3ErrorMsg(pParse, "cannot create %s trigger on view: %S", 
104787         (tr_tm == TK_BEFORE)?"BEFORE":"AFTER", pTableName, 0);
104788     goto trigger_cleanup;
104789   }
104790   if( !pTab->pSelect && tr_tm==TK_INSTEAD ){
104791     sqlite3ErrorMsg(pParse, "cannot create INSTEAD OF"
104792         " trigger on table: %S", pTableName, 0);
104793     goto trigger_cleanup;
104794   }
104795   iTabDb = sqlite3SchemaToIndex(db, pTab->pSchema);
104796 
104797 #ifndef SQLITE_OMIT_AUTHORIZATION
104798   {
104799     int code = SQLITE_CREATE_TRIGGER;
104800     const char *zDb = db->aDb[iTabDb].zName;
104801     const char *zDbTrig = isTemp ? db->aDb[1].zName : zDb;
104802     if( iTabDb==1 || isTemp ) code = SQLITE_CREATE_TEMP_TRIGGER;
104803     if( sqlite3AuthCheck(pParse, code, zName, pTab->zName, zDbTrig) ){
104804       goto trigger_cleanup;
104805     }
104806     if( sqlite3AuthCheck(pParse, SQLITE_INSERT, SCHEMA_TABLE(iTabDb),0,zDb)){
104807       goto trigger_cleanup;
104808     }
104809   }
104810 #endif
104811 
104812   /* INSTEAD OF triggers can only appear on views and BEFORE triggers
104813   ** cannot appear on views.  So we might as well translate every
104814   ** INSTEAD OF trigger into a BEFORE trigger.  It simplifies code
104815   ** elsewhere.
104816   */
104817   if (tr_tm == TK_INSTEAD){
104818     tr_tm = TK_BEFORE;
104819   }
104820 
104821   /* Build the Trigger object */
104822   pTrigger = (Trigger*)sqlite3DbMallocZero(db, sizeof(Trigger));
104823   if( pTrigger==0 ) goto trigger_cleanup;
104824   pTrigger->zName = zName;
104825   zName = 0;
104826   pTrigger->table = sqlite3DbStrDup(db, pTableName->a[0].zName);
104827   pTrigger->pSchema = db->aDb[iDb].pSchema;
104828   pTrigger->pTabSchema = pTab->pSchema;
104829   pTrigger->op = (u8)op;
104830   pTrigger->tr_tm = tr_tm==TK_BEFORE ? TRIGGER_BEFORE : TRIGGER_AFTER;
104831   pTrigger->pWhen = sqlite3ExprDup(db, pWhen, EXPRDUP_REDUCE);
104832   pTrigger->pColumns = sqlite3IdListDup(db, pColumns);
104833   assert( pParse->pNewTrigger==0 );
104834   pParse->pNewTrigger = pTrigger;
104835 
104836 trigger_cleanup:
104837   sqlite3DbFree(db, zName);
104838   sqlite3SrcListDelete(db, pTableName);
104839   sqlite3IdListDelete(db, pColumns);
104840   sqlite3ExprDelete(db, pWhen);
104841   if( !pParse->pNewTrigger ){
104842     sqlite3DeleteTrigger(db, pTrigger);
104843   }else{
104844     assert( pParse->pNewTrigger==pTrigger );
104845   }
104846 }
104847 
104848 /*
104849 ** This routine is called after all of the trigger actions have been parsed
104850 ** in order to complete the process of building the trigger.
104851 */
104852 SQLITE_PRIVATE void sqlite3FinishTrigger(
104853   Parse *pParse,          /* Parser context */
104854   TriggerStep *pStepList, /* The triggered program */
104855   Token *pAll             /* Token that describes the complete CREATE TRIGGER */
104856 ){
104857   Trigger *pTrig = pParse->pNewTrigger;   /* Trigger being finished */
104858   char *zName;                            /* Name of trigger */
104859   sqlite3 *db = pParse->db;               /* The database */
104860   DbFixer sFix;                           /* Fixer object */
104861   int iDb;                                /* Database containing the trigger */
104862   Token nameToken;                        /* Trigger name for error reporting */
104863 
104864   pParse->pNewTrigger = 0;
104865   if( NEVER(pParse->nErr) || !pTrig ) goto triggerfinish_cleanup;
104866   zName = pTrig->zName;
104867   iDb = sqlite3SchemaToIndex(pParse->db, pTrig->pSchema);
104868   pTrig->step_list = pStepList;
104869   while( pStepList ){
104870     pStepList->pTrig = pTrig;
104871     pStepList = pStepList->pNext;
104872   }
104873   nameToken.z = pTrig->zName;
104874   nameToken.n = sqlite3Strlen30(nameToken.z);
104875   sqlite3FixInit(&sFix, pParse, iDb, "trigger", &nameToken);
104876   if( sqlite3FixTriggerStep(&sFix, pTrig->step_list) 
104877    || sqlite3FixExpr(&sFix, pTrig->pWhen) 
104878   ){
104879     goto triggerfinish_cleanup;
104880   }
104881 
104882   /* if we are not initializing,
104883   ** build the sqlite_master entry
104884   */
104885   if( !db->init.busy ){
104886     Vdbe *v;
104887     char *z;
104888 
104889     /* Make an entry in the sqlite_master table */
104890     v = sqlite3GetVdbe(pParse);
104891     if( v==0 ) goto triggerfinish_cleanup;
104892     sqlite3BeginWriteOperation(pParse, 0, iDb);
104893     z = sqlite3DbStrNDup(db, (char*)pAll->z, pAll->n);
104894     sqlite3NestedParse(pParse,
104895        "INSERT INTO %Q.%s VALUES('trigger',%Q,%Q,0,'CREATE TRIGGER %q')",
104896        db->aDb[iDb].zName, SCHEMA_TABLE(iDb), zName,
104897        pTrig->table, z);
104898     sqlite3DbFree(db, z);
104899     sqlite3ChangeCookie(pParse, iDb);
104900     sqlite3VdbeAddParseSchemaOp(v, iDb,
104901         sqlite3MPrintf(db, "type='trigger' AND name='%q'", zName));
104902   }
104903 
104904   if( db->init.busy ){
104905     Trigger *pLink = pTrig;
104906     Hash *pHash = &db->aDb[iDb].pSchema->trigHash;
104907     assert( sqlite3SchemaMutexHeld(db, iDb, 0) );
104908     pTrig = sqlite3HashInsert(pHash, zName, sqlite3Strlen30(zName), pTrig);
104909     if( pTrig ){
104910       db->mallocFailed = 1;
104911     }else if( pLink->pSchema==pLink->pTabSchema ){
104912       Table *pTab;
104913       int n = sqlite3Strlen30(pLink->table);
104914       pTab = sqlite3HashFind(&pLink->pTabSchema->tblHash, pLink->table, n);
104915       assert( pTab!=0 );
104916       pLink->pNext = pTab->pTrigger;
104917       pTab->pTrigger = pLink;
104918     }
104919   }
104920 
104921 triggerfinish_cleanup:
104922   sqlite3DeleteTrigger(db, pTrig);
104923   assert( !pParse->pNewTrigger );
104924   sqlite3DeleteTriggerStep(db, pStepList);
104925 }
104926 
104927 /*
104928 ** Turn a SELECT statement (that the pSelect parameter points to) into
104929 ** a trigger step.  Return a pointer to a TriggerStep structure.
104930 **
104931 ** The parser calls this routine when it finds a SELECT statement in
104932 ** body of a TRIGGER.  
104933 */
104934 SQLITE_PRIVATE TriggerStep *sqlite3TriggerSelectStep(sqlite3 *db, Select *pSelect){
104935   TriggerStep *pTriggerStep = sqlite3DbMallocZero(db, sizeof(TriggerStep));
104936   if( pTriggerStep==0 ) {
104937     sqlite3SelectDelete(db, pSelect);
104938     return 0;
104939   }
104940   pTriggerStep->op = TK_SELECT;
104941   pTriggerStep->pSelect = pSelect;
104942   pTriggerStep->orconf = OE_Default;
104943   return pTriggerStep;
104944 }
104945 
104946 /*
104947 ** Allocate space to hold a new trigger step.  The allocated space
104948 ** holds both the TriggerStep object and the TriggerStep.target.z string.
104949 **
104950 ** If an OOM error occurs, NULL is returned and db->mallocFailed is set.
104951 */
104952 static TriggerStep *triggerStepAllocate(
104953   sqlite3 *db,                /* Database connection */
104954   u8 op,                      /* Trigger opcode */
104955   Token *pName                /* The target name */
104956 ){
104957   TriggerStep *pTriggerStep;
104958 
104959   pTriggerStep = sqlite3DbMallocZero(db, sizeof(TriggerStep) + pName->n);
104960   if( pTriggerStep ){
104961     char *z = (char*)&pTriggerStep[1];
104962     memcpy(z, pName->z, pName->n);
104963     pTriggerStep->target.z = z;
104964     pTriggerStep->target.n = pName->n;
104965     pTriggerStep->op = op;
104966   }
104967   return pTriggerStep;
104968 }
104969 
104970 /*
104971 ** Build a trigger step out of an INSERT statement.  Return a pointer
104972 ** to the new trigger step.
104973 **
104974 ** The parser calls this routine when it sees an INSERT inside the
104975 ** body of a trigger.
104976 */
104977 SQLITE_PRIVATE TriggerStep *sqlite3TriggerInsertStep(
104978   sqlite3 *db,        /* The database connection */
104979   Token *pTableName,  /* Name of the table into which we insert */
104980   IdList *pColumn,    /* List of columns in pTableName to insert into */
104981   ExprList *pEList,   /* The VALUE clause: a list of values to be inserted */
104982   Select *pSelect,    /* A SELECT statement that supplies values */
104983   u8 orconf           /* The conflict algorithm (OE_Abort, OE_Replace, etc.) */
104984 ){
104985   TriggerStep *pTriggerStep;
104986 
104987   assert(pEList == 0 || pSelect == 0);
104988   assert(pEList != 0 || pSelect != 0 || db->mallocFailed);
104989 
104990   pTriggerStep = triggerStepAllocate(db, TK_INSERT, pTableName);
104991   if( pTriggerStep ){
104992     pTriggerStep->pSelect = sqlite3SelectDup(db, pSelect, EXPRDUP_REDUCE);
104993     pTriggerStep->pIdList = pColumn;
104994     pTriggerStep->pExprList = sqlite3ExprListDup(db, pEList, EXPRDUP_REDUCE);
104995     pTriggerStep->orconf = orconf;
104996   }else{
104997     sqlite3IdListDelete(db, pColumn);
104998   }
104999   sqlite3ExprListDelete(db, pEList);
105000   sqlite3SelectDelete(db, pSelect);
105001 
105002   return pTriggerStep;
105003 }
105004 
105005 /*
105006 ** Construct a trigger step that implements an UPDATE statement and return
105007 ** a pointer to that trigger step.  The parser calls this routine when it
105008 ** sees an UPDATE statement inside the body of a CREATE TRIGGER.
105009 */
105010 SQLITE_PRIVATE TriggerStep *sqlite3TriggerUpdateStep(
105011   sqlite3 *db,         /* The database connection */
105012   Token *pTableName,   /* Name of the table to be updated */
105013   ExprList *pEList,    /* The SET clause: list of column and new values */
105014   Expr *pWhere,        /* The WHERE clause */
105015   u8 orconf            /* The conflict algorithm. (OE_Abort, OE_Ignore, etc) */
105016 ){
105017   TriggerStep *pTriggerStep;
105018 
105019   pTriggerStep = triggerStepAllocate(db, TK_UPDATE, pTableName);
105020   if( pTriggerStep ){
105021     pTriggerStep->pExprList = sqlite3ExprListDup(db, pEList, EXPRDUP_REDUCE);
105022     pTriggerStep->pWhere = sqlite3ExprDup(db, pWhere, EXPRDUP_REDUCE);
105023     pTriggerStep->orconf = orconf;
105024   }
105025   sqlite3ExprListDelete(db, pEList);
105026   sqlite3ExprDelete(db, pWhere);
105027   return pTriggerStep;
105028 }
105029 
105030 /*
105031 ** Construct a trigger step that implements a DELETE statement and return
105032 ** a pointer to that trigger step.  The parser calls this routine when it
105033 ** sees a DELETE statement inside the body of a CREATE TRIGGER.
105034 */
105035 SQLITE_PRIVATE TriggerStep *sqlite3TriggerDeleteStep(
105036   sqlite3 *db,            /* Database connection */
105037   Token *pTableName,      /* The table from which rows are deleted */
105038   Expr *pWhere            /* The WHERE clause */
105039 ){
105040   TriggerStep *pTriggerStep;
105041 
105042   pTriggerStep = triggerStepAllocate(db, TK_DELETE, pTableName);
105043   if( pTriggerStep ){
105044     pTriggerStep->pWhere = sqlite3ExprDup(db, pWhere, EXPRDUP_REDUCE);
105045     pTriggerStep->orconf = OE_Default;
105046   }
105047   sqlite3ExprDelete(db, pWhere);
105048   return pTriggerStep;
105049 }
105050 
105051 /* 
105052 ** Recursively delete a Trigger structure
105053 */
105054 SQLITE_PRIVATE void sqlite3DeleteTrigger(sqlite3 *db, Trigger *pTrigger){
105055   if( pTrigger==0 ) return;
105056   sqlite3DeleteTriggerStep(db, pTrigger->step_list);
105057   sqlite3DbFree(db, pTrigger->zName);
105058   sqlite3DbFree(db, pTrigger->table);
105059   sqlite3ExprDelete(db, pTrigger->pWhen);
105060   sqlite3IdListDelete(db, pTrigger->pColumns);
105061   sqlite3DbFree(db, pTrigger);
105062 }
105063 
105064 /*
105065 ** This function is called to drop a trigger from the database schema. 
105066 **
105067 ** This may be called directly from the parser and therefore identifies
105068 ** the trigger by name.  The sqlite3DropTriggerPtr() routine does the
105069 ** same job as this routine except it takes a pointer to the trigger
105070 ** instead of the trigger name.
105071 **/
105072 SQLITE_PRIVATE void sqlite3DropTrigger(Parse *pParse, SrcList *pName, int noErr){
105073   Trigger *pTrigger = 0;
105074   int i;
105075   const char *zDb;
105076   const char *zName;
105077   int nName;
105078   sqlite3 *db = pParse->db;
105079 
105080   if( db->mallocFailed ) goto drop_trigger_cleanup;
105081   if( SQLITE_OK!=sqlite3ReadSchema(pParse) ){
105082     goto drop_trigger_cleanup;
105083   }
105084 
105085   assert( pName->nSrc==1 );
105086   zDb = pName->a[0].zDatabase;
105087   zName = pName->a[0].zName;
105088   nName = sqlite3Strlen30(zName);
105089   assert( zDb!=0 || sqlite3BtreeHoldsAllMutexes(db) );
105090   for(i=OMIT_TEMPDB; i<db->nDb; i++){
105091     int j = (i<2) ? i^1 : i;  /* Search TEMP before MAIN */
105092     if( zDb && sqlite3StrICmp(db->aDb[j].zName, zDb) ) continue;
105093     assert( sqlite3SchemaMutexHeld(db, j, 0) );
105094     pTrigger = sqlite3HashFind(&(db->aDb[j].pSchema->trigHash), zName, nName);
105095     if( pTrigger ) break;
105096   }
105097   if( !pTrigger ){
105098     if( !noErr ){
105099       sqlite3ErrorMsg(pParse, "no such trigger: %S", pName, 0);
105100     }else{
105101       sqlite3CodeVerifyNamedSchema(pParse, zDb);
105102     }
105103     pParse->checkSchema = 1;
105104     goto drop_trigger_cleanup;
105105   }
105106   sqlite3DropTriggerPtr(pParse, pTrigger);
105107 
105108 drop_trigger_cleanup:
105109   sqlite3SrcListDelete(db, pName);
105110 }
105111 
105112 /*
105113 ** Return a pointer to the Table structure for the table that a trigger
105114 ** is set on.
105115 */
105116 static Table *tableOfTrigger(Trigger *pTrigger){
105117   int n = sqlite3Strlen30(pTrigger->table);
105118   return sqlite3HashFind(&pTrigger->pTabSchema->tblHash, pTrigger->table, n);
105119 }
105120 
105121 
105122 /*
105123 ** Drop a trigger given a pointer to that trigger. 
105124 */
105125 SQLITE_PRIVATE void sqlite3DropTriggerPtr(Parse *pParse, Trigger *pTrigger){
105126   Table   *pTable;
105127   Vdbe *v;
105128   sqlite3 *db = pParse->db;
105129   int iDb;
105130 
105131   iDb = sqlite3SchemaToIndex(pParse->db, pTrigger->pSchema);
105132   assert( iDb>=0 && iDb<db->nDb );
105133   pTable = tableOfTrigger(pTrigger);
105134   assert( pTable );
105135   assert( pTable->pSchema==pTrigger->pSchema || iDb==1 );
105136 #ifndef SQLITE_OMIT_AUTHORIZATION
105137   {
105138     int code = SQLITE_DROP_TRIGGER;
105139     const char *zDb = db->aDb[iDb].zName;
105140     const char *zTab = SCHEMA_TABLE(iDb);
105141     if( iDb==1 ) code = SQLITE_DROP_TEMP_TRIGGER;
105142     if( sqlite3AuthCheck(pParse, code, pTrigger->zName, pTable->zName, zDb) ||
105143       sqlite3AuthCheck(pParse, SQLITE_DELETE, zTab, 0, zDb) ){
105144       return;
105145     }
105146   }
105147 #endif
105148 
105149   /* Generate code to destroy the database record of the trigger.
105150   */
105151   assert( pTable!=0 );
105152   if( (v = sqlite3GetVdbe(pParse))!=0 ){
105153     int base;
105154     static const VdbeOpList dropTrigger[] = {
105155       { OP_Rewind,     0, ADDR(9),  0},
105156       { OP_String8,    0, 1,        0}, /* 1 */
105157       { OP_Column,     0, 1,        2},
105158       { OP_Ne,         2, ADDR(8),  1},
105159       { OP_String8,    0, 1,        0}, /* 4: "trigger" */
105160       { OP_Column,     0, 0,        2},
105161       { OP_Ne,         2, ADDR(8),  1},
105162       { OP_Delete,     0, 0,        0},
105163       { OP_Next,       0, ADDR(1),  0}, /* 8 */
105164     };
105165 
105166     sqlite3BeginWriteOperation(pParse, 0, iDb);
105167     sqlite3OpenMasterTable(pParse, iDb);
105168     base = sqlite3VdbeAddOpList(v,  ArraySize(dropTrigger), dropTrigger);
105169     sqlite3VdbeChangeP4(v, base+1, pTrigger->zName, P4_TRANSIENT);
105170     sqlite3VdbeChangeP4(v, base+4, "trigger", P4_STATIC);
105171     sqlite3ChangeCookie(pParse, iDb);
105172     sqlite3VdbeAddOp2(v, OP_Close, 0, 0);
105173     sqlite3VdbeAddOp4(v, OP_DropTrigger, iDb, 0, 0, pTrigger->zName, 0);
105174     if( pParse->nMem<3 ){
105175       pParse->nMem = 3;
105176     }
105177   }
105178 }
105179 
105180 /*
105181 ** Remove a trigger from the hash tables of the sqlite* pointer.
105182 */
105183 SQLITE_PRIVATE void sqlite3UnlinkAndDeleteTrigger(sqlite3 *db, int iDb, const char *zName){
105184   Trigger *pTrigger;
105185   Hash *pHash;
105186 
105187   assert( sqlite3SchemaMutexHeld(db, iDb, 0) );
105188   pHash = &(db->aDb[iDb].pSchema->trigHash);
105189   pTrigger = sqlite3HashInsert(pHash, zName, sqlite3Strlen30(zName), 0);
105190   if( ALWAYS(pTrigger) ){
105191     if( pTrigger->pSchema==pTrigger->pTabSchema ){
105192       Table *pTab = tableOfTrigger(pTrigger);
105193       Trigger **pp;
105194       for(pp=&pTab->pTrigger; *pp!=pTrigger; pp=&((*pp)->pNext));
105195       *pp = (*pp)->pNext;
105196     }
105197     sqlite3DeleteTrigger(db, pTrigger);
105198     db->flags |= SQLITE_InternChanges;
105199   }
105200 }
105201 
105202 /*
105203 ** pEList is the SET clause of an UPDATE statement.  Each entry
105204 ** in pEList is of the format <id>=<expr>.  If any of the entries
105205 ** in pEList have an <id> which matches an identifier in pIdList,
105206 ** then return TRUE.  If pIdList==NULL, then it is considered a
105207 ** wildcard that matches anything.  Likewise if pEList==NULL then
105208 ** it matches anything so always return true.  Return false only
105209 ** if there is no match.
105210 */
105211 static int checkColumnOverlap(IdList *pIdList, ExprList *pEList){
105212   int e;
105213   if( pIdList==0 || NEVER(pEList==0) ) return 1;
105214   for(e=0; e<pEList->nExpr; e++){
105215     if( sqlite3IdListIndex(pIdList, pEList->a[e].zName)>=0 ) return 1;
105216   }
105217   return 0; 
105218 }
105219 
105220 /*
105221 ** Return a list of all triggers on table pTab if there exists at least
105222 ** one trigger that must be fired when an operation of type 'op' is 
105223 ** performed on the table, and, if that operation is an UPDATE, if at
105224 ** least one of the columns in pChanges is being modified.
105225 */
105226 SQLITE_PRIVATE Trigger *sqlite3TriggersExist(
105227   Parse *pParse,          /* Parse context */
105228   Table *pTab,            /* The table the contains the triggers */
105229   int op,                 /* one of TK_DELETE, TK_INSERT, TK_UPDATE */
105230   ExprList *pChanges,     /* Columns that change in an UPDATE statement */
105231   int *pMask              /* OUT: Mask of TRIGGER_BEFORE|TRIGGER_AFTER */
105232 ){
105233   int mask = 0;
105234   Trigger *pList = 0;
105235   Trigger *p;
105236 
105237   if( (pParse->db->flags & SQLITE_EnableTrigger)!=0 ){
105238     pList = sqlite3TriggerList(pParse, pTab);
105239   }
105240   assert( pList==0 || IsVirtual(pTab)==0 );
105241   for(p=pList; p; p=p->pNext){
105242     if( p->op==op && checkColumnOverlap(p->pColumns, pChanges) ){
105243       mask |= p->tr_tm;
105244     }
105245   }
105246   if( pMask ){
105247     *pMask = mask;
105248   }
105249   return (mask ? pList : 0);
105250 }
105251 
105252 /*
105253 ** Convert the pStep->target token into a SrcList and return a pointer
105254 ** to that SrcList.
105255 **
105256 ** This routine adds a specific database name, if needed, to the target when
105257 ** forming the SrcList.  This prevents a trigger in one database from
105258 ** referring to a target in another database.  An exception is when the
105259 ** trigger is in TEMP in which case it can refer to any other database it
105260 ** wants.
105261 */
105262 static SrcList *targetSrcList(
105263   Parse *pParse,       /* The parsing context */
105264   TriggerStep *pStep   /* The trigger containing the target token */
105265 ){
105266   int iDb;             /* Index of the database to use */
105267   SrcList *pSrc;       /* SrcList to be returned */
105268 
105269   pSrc = sqlite3SrcListAppend(pParse->db, 0, &pStep->target, 0);
105270   if( pSrc ){
105271     assert( pSrc->nSrc>0 );
105272     assert( pSrc->a!=0 );
105273     iDb = sqlite3SchemaToIndex(pParse->db, pStep->pTrig->pSchema);
105274     if( iDb==0 || iDb>=2 ){
105275       sqlite3 *db = pParse->db;
105276       assert( iDb<pParse->db->nDb );
105277       pSrc->a[pSrc->nSrc-1].zDatabase = sqlite3DbStrDup(db, db->aDb[iDb].zName);
105278     }
105279   }
105280   return pSrc;
105281 }
105282 
105283 /*
105284 ** Generate VDBE code for the statements inside the body of a single 
105285 ** trigger.
105286 */
105287 static int codeTriggerProgram(
105288   Parse *pParse,            /* The parser context */
105289   TriggerStep *pStepList,   /* List of statements inside the trigger body */
105290   int orconf                /* Conflict algorithm. (OE_Abort, etc) */  
105291 ){
105292   TriggerStep *pStep;
105293   Vdbe *v = pParse->pVdbe;
105294   sqlite3 *db = pParse->db;
105295 
105296   assert( pParse->pTriggerTab && pParse->pToplevel );
105297   assert( pStepList );
105298   assert( v!=0 );
105299   for(pStep=pStepList; pStep; pStep=pStep->pNext){
105300     /* Figure out the ON CONFLICT policy that will be used for this step
105301     ** of the trigger program. If the statement that caused this trigger
105302     ** to fire had an explicit ON CONFLICT, then use it. Otherwise, use
105303     ** the ON CONFLICT policy that was specified as part of the trigger
105304     ** step statement. Example:
105305     **
105306     **   CREATE TRIGGER AFTER INSERT ON t1 BEGIN;
105307     **     INSERT OR REPLACE INTO t2 VALUES(new.a, new.b);
105308     **   END;
105309     **
105310     **   INSERT INTO t1 ... ;            -- insert into t2 uses REPLACE policy
105311     **   INSERT OR IGNORE INTO t1 ... ;  -- insert into t2 uses IGNORE policy
105312     */
105313     pParse->eOrconf = (orconf==OE_Default)?pStep->orconf:(u8)orconf;
105314 
105315     /* Clear the cookieGoto flag. When coding triggers, the cookieGoto 
105316     ** variable is used as a flag to indicate to sqlite3ExprCodeConstants()
105317     ** that it is not safe to refactor constants (this happens after the
105318     ** start of the first loop in the SQL statement is coded - at that 
105319     ** point code may be conditionally executed, so it is no longer safe to 
105320     ** initialize constant register values).  */
105321     assert( pParse->cookieGoto==0 || pParse->cookieGoto==-1 );
105322     pParse->cookieGoto = 0;
105323 
105324     switch( pStep->op ){
105325       case TK_UPDATE: {
105326         sqlite3Update(pParse, 
105327           targetSrcList(pParse, pStep),
105328           sqlite3ExprListDup(db, pStep->pExprList, 0), 
105329           sqlite3ExprDup(db, pStep->pWhere, 0), 
105330           pParse->eOrconf
105331         );
105332         break;
105333       }
105334       case TK_INSERT: {
105335         sqlite3Insert(pParse, 
105336           targetSrcList(pParse, pStep),
105337           sqlite3ExprListDup(db, pStep->pExprList, 0), 
105338           sqlite3SelectDup(db, pStep->pSelect, 0), 
105339           sqlite3IdListDup(db, pStep->pIdList), 
105340           pParse->eOrconf
105341         );
105342         break;
105343       }
105344       case TK_DELETE: {
105345         sqlite3DeleteFrom(pParse, 
105346           targetSrcList(pParse, pStep),
105347           sqlite3ExprDup(db, pStep->pWhere, 0)
105348         );
105349         break;
105350       }
105351       default: assert( pStep->op==TK_SELECT ); {
105352         SelectDest sDest;
105353         Select *pSelect = sqlite3SelectDup(db, pStep->pSelect, 0);
105354         sqlite3SelectDestInit(&sDest, SRT_Discard, 0);
105355         sqlite3Select(pParse, pSelect, &sDest);
105356         sqlite3SelectDelete(db, pSelect);
105357         break;
105358       }
105359     } 
105360     if( pStep->op!=TK_SELECT ){
105361       sqlite3VdbeAddOp0(v, OP_ResetCount);
105362     }
105363   }
105364 
105365   return 0;
105366 }
105367 
105368 #ifdef SQLITE_ENABLE_EXPLAIN_COMMENTS
105369 /*
105370 ** This function is used to add VdbeComment() annotations to a VDBE
105371 ** program. It is not used in production code, only for debugging.
105372 */
105373 static const char *onErrorText(int onError){
105374   switch( onError ){
105375     case OE_Abort:    return "abort";
105376     case OE_Rollback: return "rollback";
105377     case OE_Fail:     return "fail";
105378     case OE_Replace:  return "replace";
105379     case OE_Ignore:   return "ignore";
105380     case OE_Default:  return "default";
105381   }
105382   return "n/a";
105383 }
105384 #endif
105385 
105386 /*
105387 ** Parse context structure pFrom has just been used to create a sub-vdbe
105388 ** (trigger program). If an error has occurred, transfer error information
105389 ** from pFrom to pTo.
105390 */
105391 static void transferParseError(Parse *pTo, Parse *pFrom){
105392   assert( pFrom->zErrMsg==0 || pFrom->nErr );
105393   assert( pTo->zErrMsg==0 || pTo->nErr );
105394   if( pTo->nErr==0 ){
105395     pTo->zErrMsg = pFrom->zErrMsg;
105396     pTo->nErr = pFrom->nErr;
105397   }else{
105398     sqlite3DbFree(pFrom->db, pFrom->zErrMsg);
105399   }
105400 }
105401 
105402 /*
105403 ** Create and populate a new TriggerPrg object with a sub-program 
105404 ** implementing trigger pTrigger with ON CONFLICT policy orconf.
105405 */
105406 static TriggerPrg *codeRowTrigger(
105407   Parse *pParse,       /* Current parse context */
105408   Trigger *pTrigger,   /* Trigger to code */
105409   Table *pTab,         /* The table pTrigger is attached to */
105410   int orconf           /* ON CONFLICT policy to code trigger program with */
105411 ){
105412   Parse *pTop = sqlite3ParseToplevel(pParse);
105413   sqlite3 *db = pParse->db;   /* Database handle */
105414   TriggerPrg *pPrg;           /* Value to return */
105415   Expr *pWhen = 0;            /* Duplicate of trigger WHEN expression */
105416   Vdbe *v;                    /* Temporary VM */
105417   NameContext sNC;            /* Name context for sub-vdbe */
105418   SubProgram *pProgram = 0;   /* Sub-vdbe for trigger program */
105419   Parse *pSubParse;           /* Parse context for sub-vdbe */
105420   int iEndTrigger = 0;        /* Label to jump to if WHEN is false */
105421 
105422   assert( pTrigger->zName==0 || pTab==tableOfTrigger(pTrigger) );
105423   assert( pTop->pVdbe );
105424 
105425   /* Allocate the TriggerPrg and SubProgram objects. To ensure that they
105426   ** are freed if an error occurs, link them into the Parse.pTriggerPrg 
105427   ** list of the top-level Parse object sooner rather than later.  */
105428   pPrg = sqlite3DbMallocZero(db, sizeof(TriggerPrg));
105429   if( !pPrg ) return 0;
105430   pPrg->pNext = pTop->pTriggerPrg;
105431   pTop->pTriggerPrg = pPrg;
105432   pPrg->pProgram = pProgram = sqlite3DbMallocZero(db, sizeof(SubProgram));
105433   if( !pProgram ) return 0;
105434   sqlite3VdbeLinkSubProgram(pTop->pVdbe, pProgram);
105435   pPrg->pTrigger = pTrigger;
105436   pPrg->orconf = orconf;
105437   pPrg->aColmask[0] = 0xffffffff;
105438   pPrg->aColmask[1] = 0xffffffff;
105439 
105440   /* Allocate and populate a new Parse context to use for coding the 
105441   ** trigger sub-program.  */
105442   pSubParse = sqlite3StackAllocZero(db, sizeof(Parse));
105443   if( !pSubParse ) return 0;
105444   memset(&sNC, 0, sizeof(sNC));
105445   sNC.pParse = pSubParse;
105446   pSubParse->db = db;
105447   pSubParse->pTriggerTab = pTab;
105448   pSubParse->pToplevel = pTop;
105449   pSubParse->zAuthContext = pTrigger->zName;
105450   pSubParse->eTriggerOp = pTrigger->op;
105451   pSubParse->nQueryLoop = pParse->nQueryLoop;
105452 
105453   v = sqlite3GetVdbe(pSubParse);
105454   if( v ){
105455     VdbeComment((v, "Start: %s.%s (%s %s%s%s ON %s)", 
105456       pTrigger->zName, onErrorText(orconf),
105457       (pTrigger->tr_tm==TRIGGER_BEFORE ? "BEFORE" : "AFTER"),
105458         (pTrigger->op==TK_UPDATE ? "UPDATE" : ""),
105459         (pTrigger->op==TK_INSERT ? "INSERT" : ""),
105460         (pTrigger->op==TK_DELETE ? "DELETE" : ""),
105461       pTab->zName
105462     ));
105463 #ifndef SQLITE_OMIT_TRACE
105464     sqlite3VdbeChangeP4(v, -1, 
105465       sqlite3MPrintf(db, "-- TRIGGER %s", pTrigger->zName), P4_DYNAMIC
105466     );
105467 #endif
105468 
105469     /* If one was specified, code the WHEN clause. If it evaluates to false
105470     ** (or NULL) the sub-vdbe is immediately halted by jumping to the 
105471     ** OP_Halt inserted at the end of the program.  */
105472     if( pTrigger->pWhen ){
105473       pWhen = sqlite3ExprDup(db, pTrigger->pWhen, 0);
105474       if( SQLITE_OK==sqlite3ResolveExprNames(&sNC, pWhen) 
105475        && db->mallocFailed==0 
105476       ){
105477         iEndTrigger = sqlite3VdbeMakeLabel(v);
105478         sqlite3ExprIfFalse(pSubParse, pWhen, iEndTrigger, SQLITE_JUMPIFNULL);
105479       }
105480       sqlite3ExprDelete(db, pWhen);
105481     }
105482 
105483     /* Code the trigger program into the sub-vdbe. */
105484     codeTriggerProgram(pSubParse, pTrigger->step_list, orconf);
105485 
105486     /* Insert an OP_Halt at the end of the sub-program. */
105487     if( iEndTrigger ){
105488       sqlite3VdbeResolveLabel(v, iEndTrigger);
105489     }
105490     sqlite3VdbeAddOp0(v, OP_Halt);
105491     VdbeComment((v, "End: %s.%s", pTrigger->zName, onErrorText(orconf)));
105492 
105493     transferParseError(pParse, pSubParse);
105494     if( db->mallocFailed==0 ){
105495       pProgram->aOp = sqlite3VdbeTakeOpArray(v, &pProgram->nOp, &pTop->nMaxArg);
105496     }
105497     pProgram->nMem = pSubParse->nMem;
105498     pProgram->nCsr = pSubParse->nTab;
105499     pProgram->nOnce = pSubParse->nOnce;
105500     pProgram->token = (void *)pTrigger;
105501     pPrg->aColmask[0] = pSubParse->oldmask;
105502     pPrg->aColmask[1] = pSubParse->newmask;
105503     sqlite3VdbeDelete(v);
105504   }
105505 
105506   assert( !pSubParse->pAinc       && !pSubParse->pZombieTab );
105507   assert( !pSubParse->pTriggerPrg && !pSubParse->nMaxArg );
105508   sqlite3ParserReset(pSubParse);
105509   sqlite3StackFree(db, pSubParse);
105510 
105511   return pPrg;
105512 }
105513     
105514 /*
105515 ** Return a pointer to a TriggerPrg object containing the sub-program for
105516 ** trigger pTrigger with default ON CONFLICT algorithm orconf. If no such
105517 ** TriggerPrg object exists, a new object is allocated and populated before
105518 ** being returned.
105519 */
105520 static TriggerPrg *getRowTrigger(
105521   Parse *pParse,       /* Current parse context */
105522   Trigger *pTrigger,   /* Trigger to code */
105523   Table *pTab,         /* The table trigger pTrigger is attached to */
105524   int orconf           /* ON CONFLICT algorithm. */
105525 ){
105526   Parse *pRoot = sqlite3ParseToplevel(pParse);
105527   TriggerPrg *pPrg;
105528 
105529   assert( pTrigger->zName==0 || pTab==tableOfTrigger(pTrigger) );
105530 
105531   /* It may be that this trigger has already been coded (or is in the
105532   ** process of being coded). If this is the case, then an entry with
105533   ** a matching TriggerPrg.pTrigger field will be present somewhere
105534   ** in the Parse.pTriggerPrg list. Search for such an entry.  */
105535   for(pPrg=pRoot->pTriggerPrg; 
105536       pPrg && (pPrg->pTrigger!=pTrigger || pPrg->orconf!=orconf); 
105537       pPrg=pPrg->pNext
105538   );
105539 
105540   /* If an existing TriggerPrg could not be located, create a new one. */
105541   if( !pPrg ){
105542     pPrg = codeRowTrigger(pParse, pTrigger, pTab, orconf);
105543   }
105544 
105545   return pPrg;
105546 }
105547 
105548 /*
105549 ** Generate code for the trigger program associated with trigger p on 
105550 ** table pTab. The reg, orconf and ignoreJump parameters passed to this
105551 ** function are the same as those described in the header function for
105552 ** sqlite3CodeRowTrigger()
105553 */
105554 SQLITE_PRIVATE void sqlite3CodeRowTriggerDirect(
105555   Parse *pParse,       /* Parse context */
105556   Trigger *p,          /* Trigger to code */
105557   Table *pTab,         /* The table to code triggers from */
105558   int reg,             /* Reg array containing OLD.* and NEW.* values */
105559   int orconf,          /* ON CONFLICT policy */
105560   int ignoreJump       /* Instruction to jump to for RAISE(IGNORE) */
105561 ){
105562   Vdbe *v = sqlite3GetVdbe(pParse); /* Main VM */
105563   TriggerPrg *pPrg;
105564   pPrg = getRowTrigger(pParse, p, pTab, orconf);
105565   assert( pPrg || pParse->nErr || pParse->db->mallocFailed );
105566 
105567   /* Code the OP_Program opcode in the parent VDBE. P4 of the OP_Program 
105568   ** is a pointer to the sub-vdbe containing the trigger program.  */
105569   if( pPrg ){
105570     int bRecursive = (p->zName && 0==(pParse->db->flags&SQLITE_RecTriggers));
105571 
105572     sqlite3VdbeAddOp3(v, OP_Program, reg, ignoreJump, ++pParse->nMem);
105573     sqlite3VdbeChangeP4(v, -1, (const char *)pPrg->pProgram, P4_SUBPROGRAM);
105574     VdbeComment(
105575         (v, "Call: %s.%s", (p->zName?p->zName:"fkey"), onErrorText(orconf)));
105576 
105577     /* Set the P5 operand of the OP_Program instruction to non-zero if
105578     ** recursive invocation of this trigger program is disallowed. Recursive
105579     ** invocation is disallowed if (a) the sub-program is really a trigger,
105580     ** not a foreign key action, and (b) the flag to enable recursive triggers
105581     ** is clear.  */
105582     sqlite3VdbeChangeP5(v, (u8)bRecursive);
105583   }
105584 }
105585 
105586 /*
105587 ** This is called to code the required FOR EACH ROW triggers for an operation
105588 ** on table pTab. The operation to code triggers for (INSERT, UPDATE or DELETE)
105589 ** is given by the op parameter. The tr_tm parameter determines whether the
105590 ** BEFORE or AFTER triggers are coded. If the operation is an UPDATE, then
105591 ** parameter pChanges is passed the list of columns being modified.
105592 **
105593 ** If there are no triggers that fire at the specified time for the specified
105594 ** operation on pTab, this function is a no-op.
105595 **
105596 ** The reg argument is the address of the first in an array of registers 
105597 ** that contain the values substituted for the new.* and old.* references
105598 ** in the trigger program. If N is the number of columns in table pTab
105599 ** (a copy of pTab->nCol), then registers are populated as follows:
105600 **
105601 **   Register       Contains
105602 **   ------------------------------------------------------
105603 **   reg+0          OLD.rowid
105604 **   reg+1          OLD.* value of left-most column of pTab
105605 **   ...            ...
105606 **   reg+N          OLD.* value of right-most column of pTab
105607 **   reg+N+1        NEW.rowid
105608 **   reg+N+2        OLD.* value of left-most column of pTab
105609 **   ...            ...
105610 **   reg+N+N+1      NEW.* value of right-most column of pTab
105611 **
105612 ** For ON DELETE triggers, the registers containing the NEW.* values will
105613 ** never be accessed by the trigger program, so they are not allocated or 
105614 ** populated by the caller (there is no data to populate them with anyway). 
105615 ** Similarly, for ON INSERT triggers the values stored in the OLD.* registers
105616 ** are never accessed, and so are not allocated by the caller. So, for an
105617 ** ON INSERT trigger, the value passed to this function as parameter reg
105618 ** is not a readable register, although registers (reg+N) through 
105619 ** (reg+N+N+1) are.
105620 **
105621 ** Parameter orconf is the default conflict resolution algorithm for the
105622 ** trigger program to use (REPLACE, IGNORE etc.). Parameter ignoreJump
105623 ** is the instruction that control should jump to if a trigger program
105624 ** raises an IGNORE exception.
105625 */
105626 SQLITE_PRIVATE void sqlite3CodeRowTrigger(
105627   Parse *pParse,       /* Parse context */
105628   Trigger *pTrigger,   /* List of triggers on table pTab */
105629   int op,              /* One of TK_UPDATE, TK_INSERT, TK_DELETE */
105630   ExprList *pChanges,  /* Changes list for any UPDATE OF triggers */
105631   int tr_tm,           /* One of TRIGGER_BEFORE, TRIGGER_AFTER */
105632   Table *pTab,         /* The table to code triggers from */
105633   int reg,             /* The first in an array of registers (see above) */
105634   int orconf,          /* ON CONFLICT policy */
105635   int ignoreJump       /* Instruction to jump to for RAISE(IGNORE) */
105636 ){
105637   Trigger *p;          /* Used to iterate through pTrigger list */
105638 
105639   assert( op==TK_UPDATE || op==TK_INSERT || op==TK_DELETE );
105640   assert( tr_tm==TRIGGER_BEFORE || tr_tm==TRIGGER_AFTER );
105641   assert( (op==TK_UPDATE)==(pChanges!=0) );
105642 
105643   for(p=pTrigger; p; p=p->pNext){
105644 
105645     /* Sanity checking:  The schema for the trigger and for the table are
105646     ** always defined.  The trigger must be in the same schema as the table
105647     ** or else it must be a TEMP trigger. */
105648     assert( p->pSchema!=0 );
105649     assert( p->pTabSchema!=0 );
105650     assert( p->pSchema==p->pTabSchema 
105651          || p->pSchema==pParse->db->aDb[1].pSchema );
105652 
105653     /* Determine whether we should code this trigger */
105654     if( p->op==op 
105655      && p->tr_tm==tr_tm 
105656      && checkColumnOverlap(p->pColumns, pChanges)
105657     ){
105658       sqlite3CodeRowTriggerDirect(pParse, p, pTab, reg, orconf, ignoreJump);
105659     }
105660   }
105661 }
105662 
105663 /*
105664 ** Triggers may access values stored in the old.* or new.* pseudo-table. 
105665 ** This function returns a 32-bit bitmask indicating which columns of the 
105666 ** old.* or new.* tables actually are used by triggers. This information 
105667 ** may be used by the caller, for example, to avoid having to load the entire
105668 ** old.* record into memory when executing an UPDATE or DELETE command.
105669 **
105670 ** Bit 0 of the returned mask is set if the left-most column of the
105671 ** table may be accessed using an [old|new].<col> reference. Bit 1 is set if
105672 ** the second leftmost column value is required, and so on. If there
105673 ** are more than 32 columns in the table, and at least one of the columns
105674 ** with an index greater than 32 may be accessed, 0xffffffff is returned.
105675 **
105676 ** It is not possible to determine if the old.rowid or new.rowid column is 
105677 ** accessed by triggers. The caller must always assume that it is.
105678 **
105679 ** Parameter isNew must be either 1 or 0. If it is 0, then the mask returned
105680 ** applies to the old.* table. If 1, the new.* table.
105681 **
105682 ** Parameter tr_tm must be a mask with one or both of the TRIGGER_BEFORE
105683 ** and TRIGGER_AFTER bits set. Values accessed by BEFORE triggers are only
105684 ** included in the returned mask if the TRIGGER_BEFORE bit is set in the
105685 ** tr_tm parameter. Similarly, values accessed by AFTER triggers are only
105686 ** included in the returned mask if the TRIGGER_AFTER bit is set in tr_tm.
105687 */
105688 SQLITE_PRIVATE u32 sqlite3TriggerColmask(
105689   Parse *pParse,       /* Parse context */
105690   Trigger *pTrigger,   /* List of triggers on table pTab */
105691   ExprList *pChanges,  /* Changes list for any UPDATE OF triggers */
105692   int isNew,           /* 1 for new.* ref mask, 0 for old.* ref mask */
105693   int tr_tm,           /* Mask of TRIGGER_BEFORE|TRIGGER_AFTER */
105694   Table *pTab,         /* The table to code triggers from */
105695   int orconf           /* Default ON CONFLICT policy for trigger steps */
105696 ){
105697   const int op = pChanges ? TK_UPDATE : TK_DELETE;
105698   u32 mask = 0;
105699   Trigger *p;
105700 
105701   assert( isNew==1 || isNew==0 );
105702   for(p=pTrigger; p; p=p->pNext){
105703     if( p->op==op && (tr_tm&p->tr_tm)
105704      && checkColumnOverlap(p->pColumns,pChanges)
105705     ){
105706       TriggerPrg *pPrg;
105707       pPrg = getRowTrigger(pParse, p, pTab, orconf);
105708       if( pPrg ){
105709         mask |= pPrg->aColmask[isNew];
105710       }
105711     }
105712   }
105713 
105714   return mask;
105715 }
105716 
105717 #endif /* !defined(SQLITE_OMIT_TRIGGER) */
105718 
105719 /************** End of trigger.c *********************************************/
105720 /************** Begin file update.c ******************************************/
105721 /*
105722 ** 2001 September 15
105723 **
105724 ** The author disclaims copyright to this source code.  In place of
105725 ** a legal notice, here is a blessing:
105726 **
105727 **    May you do good and not evil.
105728 **    May you find forgiveness for yourself and forgive others.
105729 **    May you share freely, never taking more than you give.
105730 **
105731 *************************************************************************
105732 ** This file contains C code routines that are called by the parser
105733 ** to handle UPDATE statements.
105734 */
105735 
105736 #ifndef SQLITE_OMIT_VIRTUALTABLE
105737 /* Forward declaration */
105738 static void updateVirtualTable(
105739   Parse *pParse,       /* The parsing context */
105740   SrcList *pSrc,       /* The virtual table to be modified */
105741   Table *pTab,         /* The virtual table */
105742   ExprList *pChanges,  /* The columns to change in the UPDATE statement */
105743   Expr *pRowidExpr,    /* Expression used to recompute the rowid */
105744   int *aXRef,          /* Mapping from columns of pTab to entries in pChanges */
105745   Expr *pWhere,        /* WHERE clause of the UPDATE statement */
105746   int onError          /* ON CONFLICT strategy */
105747 );
105748 #endif /* SQLITE_OMIT_VIRTUALTABLE */
105749 
105750 /*
105751 ** The most recently coded instruction was an OP_Column to retrieve the
105752 ** i-th column of table pTab. This routine sets the P4 parameter of the 
105753 ** OP_Column to the default value, if any.
105754 **
105755 ** The default value of a column is specified by a DEFAULT clause in the 
105756 ** column definition. This was either supplied by the user when the table
105757 ** was created, or added later to the table definition by an ALTER TABLE
105758 ** command. If the latter, then the row-records in the table btree on disk
105759 ** may not contain a value for the column and the default value, taken
105760 ** from the P4 parameter of the OP_Column instruction, is returned instead.
105761 ** If the former, then all row-records are guaranteed to include a value
105762 ** for the column and the P4 value is not required.
105763 **
105764 ** Column definitions created by an ALTER TABLE command may only have 
105765 ** literal default values specified: a number, null or a string. (If a more
105766 ** complicated default expression value was provided, it is evaluated 
105767 ** when the ALTER TABLE is executed and one of the literal values written
105768 ** into the sqlite_master table.)
105769 **
105770 ** Therefore, the P4 parameter is only required if the default value for
105771 ** the column is a literal number, string or null. The sqlite3ValueFromExpr()
105772 ** function is capable of transforming these types of expressions into
105773 ** sqlite3_value objects.
105774 **
105775 ** If parameter iReg is not negative, code an OP_RealAffinity instruction
105776 ** on register iReg. This is used when an equivalent integer value is 
105777 ** stored in place of an 8-byte floating point value in order to save 
105778 ** space.
105779 */
105780 SQLITE_PRIVATE void sqlite3ColumnDefault(Vdbe *v, Table *pTab, int i, int iReg){
105781   assert( pTab!=0 );
105782   if( !pTab->pSelect ){
105783     sqlite3_value *pValue = 0;
105784     u8 enc = ENC(sqlite3VdbeDb(v));
105785     Column *pCol = &pTab->aCol[i];
105786     VdbeComment((v, "%s.%s", pTab->zName, pCol->zName));
105787     assert( i<pTab->nCol );
105788     sqlite3ValueFromExpr(sqlite3VdbeDb(v), pCol->pDflt, enc, 
105789                          pCol->affinity, &pValue);
105790     if( pValue ){
105791       sqlite3VdbeChangeP4(v, -1, (const char *)pValue, P4_MEM);
105792     }
105793 #ifndef SQLITE_OMIT_FLOATING_POINT
105794     if( iReg>=0 && pTab->aCol[i].affinity==SQLITE_AFF_REAL ){
105795       sqlite3VdbeAddOp1(v, OP_RealAffinity, iReg);
105796     }
105797 #endif
105798   }
105799 }
105800 
105801 /*
105802 ** Process an UPDATE statement.
105803 **
105804 **   UPDATE OR IGNORE table_wxyz SET a=b, c=d WHERE e<5 AND f NOT NULL;
105805 **          \_______/ \________/     \______/       \________________/
105806 *            onError   pTabList      pChanges             pWhere
105807 */
105808 SQLITE_PRIVATE void sqlite3Update(
105809   Parse *pParse,         /* The parser context */
105810   SrcList *pTabList,     /* The table in which we should change things */
105811   ExprList *pChanges,    /* Things to be changed */
105812   Expr *pWhere,          /* The WHERE clause.  May be null */
105813   int onError            /* How to handle constraint errors */
105814 ){
105815   int i, j;              /* Loop counters */
105816   Table *pTab;           /* The table to be updated */
105817   int addrTop = 0;       /* VDBE instruction address of the start of the loop */
105818   WhereInfo *pWInfo;     /* Information about the WHERE clause */
105819   Vdbe *v;               /* The virtual database engine */
105820   Index *pIdx;           /* For looping over indices */
105821   Index *pPk;            /* The PRIMARY KEY index for WITHOUT ROWID tables */
105822   int nIdx;              /* Number of indices that need updating */
105823   int iBaseCur;          /* Base cursor number */
105824   int iDataCur;          /* Cursor for the canonical data btree */
105825   int iIdxCur;           /* Cursor for the first index */
105826   sqlite3 *db;           /* The database structure */
105827   int *aRegIdx = 0;      /* One register assigned to each index to be updated */
105828   int *aXRef = 0;        /* aXRef[i] is the index in pChanges->a[] of the
105829                          ** an expression for the i-th column of the table.
105830                          ** aXRef[i]==-1 if the i-th column is not changed. */
105831   u8 *aToOpen;           /* 1 for tables and indices to be opened */
105832   u8 chngPk;             /* PRIMARY KEY changed in a WITHOUT ROWID table */
105833   u8 chngRowid;          /* Rowid changed in a normal table */
105834   u8 chngKey;            /* Either chngPk or chngRowid */
105835   Expr *pRowidExpr = 0;  /* Expression defining the new record number */
105836   AuthContext sContext;  /* The authorization context */
105837   NameContext sNC;       /* The name-context to resolve expressions in */
105838   int iDb;               /* Database containing the table being updated */
105839   int okOnePass;         /* True for one-pass algorithm without the FIFO */
105840   int hasFK;             /* True if foreign key processing is required */
105841   int labelBreak;        /* Jump here to break out of UPDATE loop */
105842   int labelContinue;     /* Jump here to continue next step of UPDATE loop */
105843 
105844 #ifndef SQLITE_OMIT_TRIGGER
105845   int isView;            /* True when updating a view (INSTEAD OF trigger) */
105846   Trigger *pTrigger;     /* List of triggers on pTab, if required */
105847   int tmask;             /* Mask of TRIGGER_BEFORE|TRIGGER_AFTER */
105848 #endif
105849   int newmask;           /* Mask of NEW.* columns accessed by BEFORE triggers */
105850   int iEph = 0;          /* Ephemeral table holding all primary key values */
105851   int nKey = 0;          /* Number of elements in regKey for WITHOUT ROWID */
105852   int aiCurOnePass[2];   /* The write cursors opened by WHERE_ONEPASS */
105853 
105854   /* Register Allocations */
105855   int regRowCount = 0;   /* A count of rows changed */
105856   int regOldRowid;       /* The old rowid */
105857   int regNewRowid;       /* The new rowid */
105858   int regNew;            /* Content of the NEW.* table in triggers */
105859   int regOld = 0;        /* Content of OLD.* table in triggers */
105860   int regRowSet = 0;     /* Rowset of rows to be updated */
105861   int regKey = 0;        /* composite PRIMARY KEY value */
105862 
105863   memset(&sContext, 0, sizeof(sContext));
105864   db = pParse->db;
105865   if( pParse->nErr || db->mallocFailed ){
105866     goto update_cleanup;
105867   }
105868   assert( pTabList->nSrc==1 );
105869 
105870   /* Locate the table which we want to update. 
105871   */
105872   pTab = sqlite3SrcListLookup(pParse, pTabList);
105873   if( pTab==0 ) goto update_cleanup;
105874   iDb = sqlite3SchemaToIndex(pParse->db, pTab->pSchema);
105875 
105876   /* Figure out if we have any triggers and if the table being
105877   ** updated is a view.
105878   */
105879 #ifndef SQLITE_OMIT_TRIGGER
105880   pTrigger = sqlite3TriggersExist(pParse, pTab, TK_UPDATE, pChanges, &tmask);
105881   isView = pTab->pSelect!=0;
105882   assert( pTrigger || tmask==0 );
105883 #else
105884 # define pTrigger 0
105885 # define isView 0
105886 # define tmask 0
105887 #endif
105888 #ifdef SQLITE_OMIT_VIEW
105889 # undef isView
105890 # define isView 0
105891 #endif
105892 
105893   if( sqlite3ViewGetColumnNames(pParse, pTab) ){
105894     goto update_cleanup;
105895   }
105896   if( sqlite3IsReadOnly(pParse, pTab, tmask) ){
105897     goto update_cleanup;
105898   }
105899 
105900   /* Allocate a cursors for the main database table and for all indices.
105901   ** The index cursors might not be used, but if they are used they
105902   ** need to occur right after the database cursor.  So go ahead and
105903   ** allocate enough space, just in case.
105904   */
105905   pTabList->a[0].iCursor = iBaseCur = iDataCur = pParse->nTab++;
105906   iIdxCur = iDataCur+1;
105907   pPk = HasRowid(pTab) ? 0 : sqlite3PrimaryKeyIndex(pTab);
105908   for(nIdx=0, pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext, nIdx++){
105909     if( pIdx->autoIndex==2 && pPk!=0 ){
105910       iDataCur = pParse->nTab;
105911       pTabList->a[0].iCursor = iDataCur;
105912     }
105913     pParse->nTab++;
105914   }
105915 
105916   /* Allocate space for aXRef[], aRegIdx[], and aToOpen[].  
105917   ** Initialize aXRef[] and aToOpen[] to their default values.
105918   */
105919   aXRef = sqlite3DbMallocRaw(db, sizeof(int) * (pTab->nCol+nIdx) + nIdx+2 );
105920   if( aXRef==0 ) goto update_cleanup;
105921   aRegIdx = aXRef+pTab->nCol;
105922   aToOpen = (u8*)(aRegIdx+nIdx);
105923   memset(aToOpen, 1, nIdx+1);
105924   aToOpen[nIdx+1] = 0;
105925   for(i=0; i<pTab->nCol; i++) aXRef[i] = -1;
105926 
105927   /* Initialize the name-context */
105928   memset(&sNC, 0, sizeof(sNC));
105929   sNC.pParse = pParse;
105930   sNC.pSrcList = pTabList;
105931 
105932   /* Resolve the column names in all the expressions of the
105933   ** of the UPDATE statement.  Also find the column index
105934   ** for each column to be updated in the pChanges array.  For each
105935   ** column to be updated, make sure we have authorization to change
105936   ** that column.
105937   */
105938   chngRowid = chngPk = 0;
105939   for(i=0; i<pChanges->nExpr; i++){
105940     if( sqlite3ResolveExprNames(&sNC, pChanges->a[i].pExpr) ){
105941       goto update_cleanup;
105942     }
105943     for(j=0; j<pTab->nCol; j++){
105944       if( sqlite3StrICmp(pTab->aCol[j].zName, pChanges->a[i].zName)==0 ){
105945         if( j==pTab->iPKey ){
105946           chngRowid = 1;
105947           pRowidExpr = pChanges->a[i].pExpr;
105948         }else if( pPk && (pTab->aCol[j].colFlags & COLFLAG_PRIMKEY)!=0 ){
105949           chngPk = 1;
105950         }
105951         aXRef[j] = i;
105952         break;
105953       }
105954     }
105955     if( j>=pTab->nCol ){
105956       if( pPk==0 && sqlite3IsRowid(pChanges->a[i].zName) ){
105957         j = -1;
105958         chngRowid = 1;
105959         pRowidExpr = pChanges->a[i].pExpr;
105960       }else{
105961         sqlite3ErrorMsg(pParse, "no such column: %s", pChanges->a[i].zName);
105962         pParse->checkSchema = 1;
105963         goto update_cleanup;
105964       }
105965     }
105966 #ifndef SQLITE_OMIT_AUTHORIZATION
105967     {
105968       int rc;
105969       rc = sqlite3AuthCheck(pParse, SQLITE_UPDATE, pTab->zName,
105970                             j<0 ? "ROWID" : pTab->aCol[j].zName,
105971                             db->aDb[iDb].zName);
105972       if( rc==SQLITE_DENY ){
105973         goto update_cleanup;
105974       }else if( rc==SQLITE_IGNORE ){
105975         aXRef[j] = -1;
105976       }
105977     }
105978 #endif
105979   }
105980   assert( (chngRowid & chngPk)==0 );
105981   assert( chngRowid==0 || chngRowid==1 );
105982   assert( chngPk==0 || chngPk==1 );
105983   chngKey = chngRowid + chngPk;
105984 
105985   /* The SET expressions are not actually used inside the WHERE loop.
105986   ** So reset the colUsed mask
105987   */
105988   pTabList->a[0].colUsed = 0;
105989 
105990   hasFK = sqlite3FkRequired(pParse, pTab, aXRef, chngKey);
105991 
105992   /* There is one entry in the aRegIdx[] array for each index on the table
105993   ** being updated.  Fill in aRegIdx[] with a register number that will hold
105994   ** the key for accessing each index.  
105995   */
105996   for(j=0, pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext, j++){
105997     int reg;
105998     if( chngKey || hasFK || pIdx->pPartIdxWhere || pIdx==pPk ){
105999       reg = ++pParse->nMem;
106000     }else{
106001       reg = 0;
106002       for(i=0; i<pIdx->nKeyCol; i++){
106003         if( aXRef[pIdx->aiColumn[i]]>=0 ){
106004           reg = ++pParse->nMem;
106005           break;
106006         }
106007       }
106008     }
106009     if( reg==0 ) aToOpen[j+1] = 0;
106010     aRegIdx[j] = reg;
106011   }
106012 
106013   /* Begin generating code. */
106014   v = sqlite3GetVdbe(pParse);
106015   if( v==0 ) goto update_cleanup;
106016   if( pParse->nested==0 ) sqlite3VdbeCountChanges(v);
106017   sqlite3BeginWriteOperation(pParse, 1, iDb);
106018 
106019 #ifndef SQLITE_OMIT_VIRTUALTABLE
106020   /* Virtual tables must be handled separately */
106021   if( IsVirtual(pTab) ){
106022     updateVirtualTable(pParse, pTabList, pTab, pChanges, pRowidExpr, aXRef,
106023                        pWhere, onError);
106024     pWhere = 0;
106025     pTabList = 0;
106026     goto update_cleanup;
106027   }
106028 #endif
106029 
106030   /* Allocate required registers. */
106031   regRowSet = ++pParse->nMem;
106032   regOldRowid = regNewRowid = ++pParse->nMem;
106033   if( chngPk || pTrigger || hasFK ){
106034     regOld = pParse->nMem + 1;
106035     pParse->nMem += pTab->nCol;
106036   }
106037   if( chngKey || pTrigger || hasFK ){
106038     regNewRowid = ++pParse->nMem;
106039   }
106040   regNew = pParse->nMem + 1;
106041   pParse->nMem += pTab->nCol;
106042 
106043   /* Start the view context. */
106044   if( isView ){
106045     sqlite3AuthContextPush(pParse, &sContext, pTab->zName);
106046   }
106047 
106048   /* If we are trying to update a view, realize that view into
106049   ** a ephemeral table.
106050   */
106051 #if !defined(SQLITE_OMIT_VIEW) && !defined(SQLITE_OMIT_TRIGGER)
106052   if( isView ){
106053     sqlite3MaterializeView(pParse, pTab, pWhere, iDataCur);
106054   }
106055 #endif
106056 
106057   /* Resolve the column names in all the expressions in the
106058   ** WHERE clause.
106059   */
106060   if( sqlite3ResolveExprNames(&sNC, pWhere) ){
106061     goto update_cleanup;
106062   }
106063 
106064   /* Begin the database scan
106065   */
106066   if( HasRowid(pTab) ){
106067     sqlite3VdbeAddOp3(v, OP_Null, 0, regRowSet, regOldRowid);
106068     pWInfo = sqlite3WhereBegin(
106069         pParse, pTabList, pWhere, 0, 0, WHERE_ONEPASS_DESIRED, iIdxCur
106070     );
106071     if( pWInfo==0 ) goto update_cleanup;
106072     okOnePass = sqlite3WhereOkOnePass(pWInfo, aiCurOnePass);
106073   
106074     /* Remember the rowid of every item to be updated.
106075     */
106076     sqlite3VdbeAddOp2(v, OP_Rowid, iDataCur, regOldRowid);
106077     if( !okOnePass ){
106078       sqlite3VdbeAddOp2(v, OP_RowSetAdd, regRowSet, regOldRowid);
106079     }
106080   
106081     /* End the database scan loop.
106082     */
106083     sqlite3WhereEnd(pWInfo);
106084   }else{
106085     int iPk;         /* First of nPk memory cells holding PRIMARY KEY value */
106086     i16 nPk;         /* Number of components of the PRIMARY KEY */
106087     int addrOpen;    /* Address of the OpenEphemeral instruction */
106088 
106089     assert( pPk!=0 );
106090     nPk = pPk->nKeyCol;
106091     iPk = pParse->nMem+1;
106092     pParse->nMem += nPk;
106093     regKey = ++pParse->nMem;
106094     iEph = pParse->nTab++;
106095     sqlite3VdbeAddOp2(v, OP_Null, 0, iPk);
106096     addrOpen = sqlite3VdbeAddOp2(v, OP_OpenEphemeral, iEph, nPk);
106097     sqlite3VdbeSetP4KeyInfo(pParse, pPk);
106098     pWInfo = sqlite3WhereBegin(pParse, pTabList, pWhere, 0, 0, 
106099                                WHERE_ONEPASS_DESIRED, iIdxCur);
106100     if( pWInfo==0 ) goto update_cleanup;
106101     okOnePass = sqlite3WhereOkOnePass(pWInfo, aiCurOnePass);
106102     for(i=0; i<nPk; i++){
106103       sqlite3ExprCodeGetColumnOfTable(v, pTab, iDataCur, pPk->aiColumn[i],
106104                                       iPk+i);
106105     }
106106     if( okOnePass ){
106107       sqlite3VdbeChangeToNoop(v, addrOpen);
106108       nKey = nPk;
106109       regKey = iPk;
106110     }else{
106111       sqlite3VdbeAddOp4(v, OP_MakeRecord, iPk, nPk, regKey,
106112                         sqlite3IndexAffinityStr(v, pPk), P4_TRANSIENT);
106113       sqlite3VdbeAddOp2(v, OP_IdxInsert, iEph, regKey);
106114     }
106115     sqlite3WhereEnd(pWInfo);
106116   }
106117 
106118   /* Initialize the count of updated rows
106119   */
106120   if( (db->flags & SQLITE_CountRows) && !pParse->pTriggerTab ){
106121     regRowCount = ++pParse->nMem;
106122     sqlite3VdbeAddOp2(v, OP_Integer, 0, regRowCount);
106123   }
106124 
106125   labelBreak = sqlite3VdbeMakeLabel(v);
106126   if( !isView ){
106127     /* 
106128     ** Open every index that needs updating.  Note that if any
106129     ** index could potentially invoke a REPLACE conflict resolution 
106130     ** action, then we need to open all indices because we might need
106131     ** to be deleting some records.
106132     */
106133     if( onError==OE_Replace ){
106134       memset(aToOpen, 1, nIdx+1);
106135     }else{
106136       for(pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext){
106137         if( pIdx->onError==OE_Replace ){
106138           memset(aToOpen, 1, nIdx+1);
106139           break;
106140         }
106141       }
106142     }
106143     if( okOnePass ){
106144       if( aiCurOnePass[0]>=0 ) aToOpen[aiCurOnePass[0]-iBaseCur] = 0;
106145       if( aiCurOnePass[1]>=0 ) aToOpen[aiCurOnePass[1]-iBaseCur] = 0;
106146     }
106147     sqlite3OpenTableAndIndices(pParse, pTab, OP_OpenWrite, iBaseCur, aToOpen,
106148                                0, 0);
106149   }
106150 
106151   /* Top of the update loop */
106152   if( okOnePass ){
106153     if( aToOpen[iDataCur-iBaseCur] ){
106154       assert( pPk!=0 );
106155       sqlite3VdbeAddOp4Int(v, OP_NotFound, iDataCur, labelBreak, regKey, nKey);
106156     }
106157     labelContinue = labelBreak;
106158     sqlite3VdbeAddOp2(v, OP_IsNull, pPk ? regKey : regOldRowid, labelBreak);
106159   }else if( pPk ){
106160     labelContinue = sqlite3VdbeMakeLabel(v);
106161     sqlite3VdbeAddOp2(v, OP_Rewind, iEph, labelBreak);
106162     addrTop = sqlite3VdbeAddOp2(v, OP_RowKey, iEph, regKey);
106163     sqlite3VdbeAddOp4Int(v, OP_NotFound, iDataCur, labelContinue, regKey, 0);
106164   }else{
106165     labelContinue = sqlite3VdbeAddOp3(v, OP_RowSetRead, regRowSet, labelBreak,
106166                              regOldRowid);
106167     sqlite3VdbeAddOp3(v, OP_NotExists, iDataCur, labelContinue, regOldRowid);
106168   }
106169 
106170   /* If the record number will change, set register regNewRowid to
106171   ** contain the new value. If the record number is not being modified,
106172   ** then regNewRowid is the same register as regOldRowid, which is
106173   ** already populated.  */
106174   assert( chngKey || pTrigger || hasFK || regOldRowid==regNewRowid );
106175   if( chngRowid ){
106176     sqlite3ExprCode(pParse, pRowidExpr, regNewRowid);
106177     sqlite3VdbeAddOp1(v, OP_MustBeInt, regNewRowid);
106178   }
106179 
106180   /* Compute the old pre-UPDATE content of the row being changed, if that
106181   ** information is needed */
106182   if( chngPk || hasFK || pTrigger ){
106183     u32 oldmask = (hasFK ? sqlite3FkOldmask(pParse, pTab) : 0);
106184     oldmask |= sqlite3TriggerColmask(pParse, 
106185         pTrigger, pChanges, 0, TRIGGER_BEFORE|TRIGGER_AFTER, pTab, onError
106186     );
106187     for(i=0; i<pTab->nCol; i++){
106188       if( oldmask==0xffffffff
106189        || (i<32 && (oldmask & (1<<i)))
106190        || (pTab->aCol[i].colFlags & COLFLAG_PRIMKEY)!=0
106191       ){
106192         sqlite3ExprCodeGetColumnOfTable(v, pTab, iDataCur, i, regOld+i);
106193       }else{
106194         sqlite3VdbeAddOp2(v, OP_Null, 0, regOld+i);
106195       }
106196     }
106197     if( chngRowid==0 && pPk==0 ){
106198       sqlite3VdbeAddOp2(v, OP_Copy, regOldRowid, regNewRowid);
106199     }
106200   }
106201 
106202   /* Populate the array of registers beginning at regNew with the new
106203   ** row data. This array is used to check constaints, create the new
106204   ** table and index records, and as the values for any new.* references
106205   ** made by triggers.
106206   **
106207   ** If there are one or more BEFORE triggers, then do not populate the
106208   ** registers associated with columns that are (a) not modified by
106209   ** this UPDATE statement and (b) not accessed by new.* references. The
106210   ** values for registers not modified by the UPDATE must be reloaded from 
106211   ** the database after the BEFORE triggers are fired anyway (as the trigger 
106212   ** may have modified them). So not loading those that are not going to
106213   ** be used eliminates some redundant opcodes.
106214   */
106215   newmask = sqlite3TriggerColmask(
106216       pParse, pTrigger, pChanges, 1, TRIGGER_BEFORE, pTab, onError
106217   );
106218   sqlite3VdbeAddOp3(v, OP_Null, 0, regNew, regNew+pTab->nCol-1);
106219   for(i=0; i<pTab->nCol; i++){
106220     if( i==pTab->iPKey ){
106221       /*sqlite3VdbeAddOp2(v, OP_Null, 0, regNew+i);*/
106222     }else{
106223       j = aXRef[i];
106224       if( j>=0 ){
106225         sqlite3ExprCode(pParse, pChanges->a[j].pExpr, regNew+i);
106226       }else if( 0==(tmask&TRIGGER_BEFORE) || i>31 || (newmask&(1<<i)) ){
106227         /* This branch loads the value of a column that will not be changed 
106228         ** into a register. This is done if there are no BEFORE triggers, or
106229         ** if there are one or more BEFORE triggers that use this value via
106230         ** a new.* reference in a trigger program.
106231         */
106232         testcase( i==31 );
106233         testcase( i==32 );
106234         sqlite3ExprCodeGetColumnOfTable(v, pTab, iDataCur, i, regNew+i);
106235       }
106236     }
106237   }
106238 
106239   /* Fire any BEFORE UPDATE triggers. This happens before constraints are
106240   ** verified. One could argue that this is wrong.
106241   */
106242   if( tmask&TRIGGER_BEFORE ){
106243     sqlite3VdbeAddOp2(v, OP_Affinity, regNew, pTab->nCol);
106244     sqlite3TableAffinityStr(v, pTab);
106245     sqlite3CodeRowTrigger(pParse, pTrigger, TK_UPDATE, pChanges, 
106246         TRIGGER_BEFORE, pTab, regOldRowid, onError, labelContinue);
106247 
106248     /* The row-trigger may have deleted the row being updated. In this
106249     ** case, jump to the next row. No updates or AFTER triggers are 
106250     ** required. This behavior - what happens when the row being updated
106251     ** is deleted or renamed by a BEFORE trigger - is left undefined in the
106252     ** documentation.
106253     */
106254     if( pPk ){
106255       sqlite3VdbeAddOp4Int(v, OP_NotFound, iDataCur, labelContinue,regKey,nKey);
106256     }else{
106257       sqlite3VdbeAddOp3(v, OP_NotExists, iDataCur, labelContinue, regOldRowid);
106258     }
106259 
106260     /* If it did not delete it, the row-trigger may still have modified 
106261     ** some of the columns of the row being updated. Load the values for 
106262     ** all columns not modified by the update statement into their 
106263     ** registers in case this has happened.
106264     */
106265     for(i=0; i<pTab->nCol; i++){
106266       if( aXRef[i]<0 && i!=pTab->iPKey ){
106267         sqlite3ExprCodeGetColumnOfTable(v, pTab, iDataCur, i, regNew+i);
106268       }
106269     }
106270   }
106271 
106272   if( !isView ){
106273     int j1 = 0;           /* Address of jump instruction */
106274     int bReplace = 0;     /* True if REPLACE conflict resolution might happen */
106275 
106276     /* Do constraint checks. */
106277     assert( regOldRowid>0 );
106278     sqlite3GenerateConstraintChecks(pParse, pTab, aRegIdx, iDataCur, iIdxCur,
106279         regNewRowid, regOldRowid, chngKey, onError, labelContinue, &bReplace);
106280 
106281     /* Do FK constraint checks. */
106282     if( hasFK ){
106283       sqlite3FkCheck(pParse, pTab, regOldRowid, 0, aXRef, chngKey);
106284     }
106285 
106286     /* Delete the index entries associated with the current record.  */
106287     if( bReplace || chngKey ){
106288       if( pPk ){
106289         j1 = sqlite3VdbeAddOp4Int(v, OP_NotFound, iDataCur, 0, regKey, nKey);
106290       }else{
106291         j1 = sqlite3VdbeAddOp3(v, OP_NotExists, iDataCur, 0, regOldRowid);
106292       }
106293     }
106294     sqlite3GenerateRowIndexDelete(pParse, pTab, iDataCur, iIdxCur, aRegIdx);
106295   
106296     /* If changing the record number, delete the old record.  */
106297     if( hasFK || chngKey || pPk!=0 ){
106298       sqlite3VdbeAddOp2(v, OP_Delete, iDataCur, 0);
106299     }
106300     if( bReplace || chngKey ){
106301       sqlite3VdbeJumpHere(v, j1);
106302     }
106303 
106304     if( hasFK ){
106305       sqlite3FkCheck(pParse, pTab, 0, regNewRowid, aXRef, chngKey);
106306     }
106307   
106308     /* Insert the new index entries and the new record. */
106309     sqlite3CompleteInsertion(pParse, pTab, iDataCur, iIdxCur,
106310                              regNewRowid, aRegIdx, 1, 0, 0);
106311 
106312     /* Do any ON CASCADE, SET NULL or SET DEFAULT operations required to
106313     ** handle rows (possibly in other tables) that refer via a foreign key
106314     ** to the row just updated. */ 
106315     if( hasFK ){
106316       sqlite3FkActions(pParse, pTab, pChanges, regOldRowid, aXRef, chngKey);
106317     }
106318   }
106319 
106320   /* Increment the row counter 
106321   */
106322   if( (db->flags & SQLITE_CountRows) && !pParse->pTriggerTab){
106323     sqlite3VdbeAddOp2(v, OP_AddImm, regRowCount, 1);
106324   }
106325 
106326   sqlite3CodeRowTrigger(pParse, pTrigger, TK_UPDATE, pChanges, 
106327       TRIGGER_AFTER, pTab, regOldRowid, onError, labelContinue);
106328 
106329   /* Repeat the above with the next record to be updated, until
106330   ** all record selected by the WHERE clause have been updated.
106331   */
106332   if( okOnePass ){
106333     /* Nothing to do at end-of-loop for a single-pass */
106334   }else if( pPk ){
106335     sqlite3VdbeResolveLabel(v, labelContinue);
106336     sqlite3VdbeAddOp2(v, OP_Next, iEph, addrTop);
106337   }else{
106338     sqlite3VdbeAddOp2(v, OP_Goto, 0, labelContinue);
106339   }
106340   sqlite3VdbeResolveLabel(v, labelBreak);
106341 
106342   /* Close all tables */
106343   for(i=0, pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext, i++){
106344     assert( aRegIdx );
106345     if( aToOpen[i+1] ){
106346       sqlite3VdbeAddOp2(v, OP_Close, iIdxCur+i, 0);
106347     }
106348   }
106349   if( iDataCur<iIdxCur ) sqlite3VdbeAddOp2(v, OP_Close, iDataCur, 0);
106350 
106351   /* Update the sqlite_sequence table by storing the content of the
106352   ** maximum rowid counter values recorded while inserting into
106353   ** autoincrement tables.
106354   */
106355   if( pParse->nested==0 && pParse->pTriggerTab==0 ){
106356     sqlite3AutoincrementEnd(pParse);
106357   }
106358 
106359   /*
106360   ** Return the number of rows that were changed. If this routine is 
106361   ** generating code because of a call to sqlite3NestedParse(), do not
106362   ** invoke the callback function.
106363   */
106364   if( (db->flags&SQLITE_CountRows) && !pParse->pTriggerTab && !pParse->nested ){
106365     sqlite3VdbeAddOp2(v, OP_ResultRow, regRowCount, 1);
106366     sqlite3VdbeSetNumCols(v, 1);
106367     sqlite3VdbeSetColName(v, 0, COLNAME_NAME, "rows updated", SQLITE_STATIC);
106368   }
106369 
106370 update_cleanup:
106371   sqlite3AuthContextPop(&sContext);
106372   sqlite3DbFree(db, aXRef); /* Also frees aRegIdx[] and aToOpen[] */
106373   sqlite3SrcListDelete(db, pTabList);
106374   sqlite3ExprListDelete(db, pChanges);
106375   sqlite3ExprDelete(db, pWhere);
106376   return;
106377 }
106378 /* Make sure "isView" and other macros defined above are undefined. Otherwise
106379 ** thely may interfere with compilation of other functions in this file
106380 ** (or in another file, if this file becomes part of the amalgamation).  */
106381 #ifdef isView
106382  #undef isView
106383 #endif
106384 #ifdef pTrigger
106385  #undef pTrigger
106386 #endif
106387 
106388 #ifndef SQLITE_OMIT_VIRTUALTABLE
106389 /*
106390 ** Generate code for an UPDATE of a virtual table.
106391 **
106392 ** The strategy is that we create an ephemerial table that contains
106393 ** for each row to be changed:
106394 **
106395 **   (A)  The original rowid of that row.
106396 **   (B)  The revised rowid for the row. (note1)
106397 **   (C)  The content of every column in the row.
106398 **
106399 ** Then we loop over this ephemeral table and for each row in
106400 ** the ephermeral table call VUpdate.
106401 **
106402 ** When finished, drop the ephemeral table.
106403 **
106404 ** (note1) Actually, if we know in advance that (A) is always the same
106405 ** as (B) we only store (A), then duplicate (A) when pulling
106406 ** it out of the ephemeral table before calling VUpdate.
106407 */
106408 static void updateVirtualTable(
106409   Parse *pParse,       /* The parsing context */
106410   SrcList *pSrc,       /* The virtual table to be modified */
106411   Table *pTab,         /* The virtual table */
106412   ExprList *pChanges,  /* The columns to change in the UPDATE statement */
106413   Expr *pRowid,        /* Expression used to recompute the rowid */
106414   int *aXRef,          /* Mapping from columns of pTab to entries in pChanges */
106415   Expr *pWhere,        /* WHERE clause of the UPDATE statement */
106416   int onError          /* ON CONFLICT strategy */
106417 ){
106418   Vdbe *v = pParse->pVdbe;  /* Virtual machine under construction */
106419   ExprList *pEList = 0;     /* The result set of the SELECT statement */
106420   Select *pSelect = 0;      /* The SELECT statement */
106421   Expr *pExpr;              /* Temporary expression */
106422   int ephemTab;             /* Table holding the result of the SELECT */
106423   int i;                    /* Loop counter */
106424   int addr;                 /* Address of top of loop */
106425   int iReg;                 /* First register in set passed to OP_VUpdate */
106426   sqlite3 *db = pParse->db; /* Database connection */
106427   const char *pVTab = (const char*)sqlite3GetVTable(db, pTab);
106428   SelectDest dest;
106429 
106430   /* Construct the SELECT statement that will find the new values for
106431   ** all updated rows. 
106432   */
106433   pEList = sqlite3ExprListAppend(pParse, 0, sqlite3Expr(db, TK_ID, "_rowid_"));
106434   if( pRowid ){
106435     pEList = sqlite3ExprListAppend(pParse, pEList,
106436                                    sqlite3ExprDup(db, pRowid, 0));
106437   }
106438   assert( pTab->iPKey<0 );
106439   for(i=0; i<pTab->nCol; i++){
106440     if( aXRef[i]>=0 ){
106441       pExpr = sqlite3ExprDup(db, pChanges->a[aXRef[i]].pExpr, 0);
106442     }else{
106443       pExpr = sqlite3Expr(db, TK_ID, pTab->aCol[i].zName);
106444     }
106445     pEList = sqlite3ExprListAppend(pParse, pEList, pExpr);
106446   }
106447   pSelect = sqlite3SelectNew(pParse, pEList, pSrc, pWhere, 0, 0, 0, 0, 0, 0);
106448   
106449   /* Create the ephemeral table into which the update results will
106450   ** be stored.
106451   */
106452   assert( v );
106453   ephemTab = pParse->nTab++;
106454   sqlite3VdbeAddOp2(v, OP_OpenEphemeral, ephemTab, pTab->nCol+1+(pRowid!=0));
106455   sqlite3VdbeChangeP5(v, BTREE_UNORDERED);
106456 
106457   /* fill the ephemeral table 
106458   */
106459   sqlite3SelectDestInit(&dest, SRT_Table, ephemTab);
106460   sqlite3Select(pParse, pSelect, &dest);
106461 
106462   /* Generate code to scan the ephemeral table and call VUpdate. */
106463   iReg = ++pParse->nMem;
106464   pParse->nMem += pTab->nCol+1;
106465   addr = sqlite3VdbeAddOp2(v, OP_Rewind, ephemTab, 0);
106466   sqlite3VdbeAddOp3(v, OP_Column,  ephemTab, 0, iReg);
106467   sqlite3VdbeAddOp3(v, OP_Column, ephemTab, (pRowid?1:0), iReg+1);
106468   for(i=0; i<pTab->nCol; i++){
106469     sqlite3VdbeAddOp3(v, OP_Column, ephemTab, i+1+(pRowid!=0), iReg+2+i);
106470   }
106471   sqlite3VtabMakeWritable(pParse, pTab);
106472   sqlite3VdbeAddOp4(v, OP_VUpdate, 0, pTab->nCol+2, iReg, pVTab, P4_VTAB);
106473   sqlite3VdbeChangeP5(v, onError==OE_Default ? OE_Abort : onError);
106474   sqlite3MayAbort(pParse);
106475   sqlite3VdbeAddOp2(v, OP_Next, ephemTab, addr+1);
106476   sqlite3VdbeJumpHere(v, addr);
106477   sqlite3VdbeAddOp2(v, OP_Close, ephemTab, 0);
106478 
106479   /* Cleanup */
106480   sqlite3SelectDelete(db, pSelect);  
106481 }
106482 #endif /* SQLITE_OMIT_VIRTUALTABLE */
106483 
106484 /************** End of update.c **********************************************/
106485 /************** Begin file vacuum.c ******************************************/
106486 /*
106487 ** 2003 April 6
106488 **
106489 ** The author disclaims copyright to this source code.  In place of
106490 ** a legal notice, here is a blessing:
106491 **
106492 **    May you do good and not evil.
106493 **    May you find forgiveness for yourself and forgive others.
106494 **    May you share freely, never taking more than you give.
106495 **
106496 *************************************************************************
106497 ** This file contains code used to implement the VACUUM command.
106498 **
106499 ** Most of the code in this file may be omitted by defining the
106500 ** SQLITE_OMIT_VACUUM macro.
106501 */
106502 
106503 #if !defined(SQLITE_OMIT_VACUUM) && !defined(SQLITE_OMIT_ATTACH)
106504 /*
106505 ** Finalize a prepared statement.  If there was an error, store the
106506 ** text of the error message in *pzErrMsg.  Return the result code.
106507 */
106508 static int vacuumFinalize(sqlite3 *db, sqlite3_stmt *pStmt, char **pzErrMsg){
106509   int rc;
106510   rc = sqlite3VdbeFinalize((Vdbe*)pStmt);
106511   if( rc ){
106512     sqlite3SetString(pzErrMsg, db, sqlite3_errmsg(db));
106513   }
106514   return rc;
106515 }
106516 
106517 /*
106518 ** Execute zSql on database db. Return an error code.
106519 */
106520 static int execSql(sqlite3 *db, char **pzErrMsg, const char *zSql){
106521   sqlite3_stmt *pStmt;
106522   VVA_ONLY( int rc; )
106523   if( !zSql ){
106524     return SQLITE_NOMEM;
106525   }
106526   if( SQLITE_OK!=sqlite3_prepare(db, zSql, -1, &pStmt, 0) ){
106527     sqlite3SetString(pzErrMsg, db, sqlite3_errmsg(db));
106528     return sqlite3_errcode(db);
106529   }
106530   VVA_ONLY( rc = ) sqlite3_step(pStmt);
106531   assert( rc!=SQLITE_ROW || (db->flags&SQLITE_CountRows) );
106532   return vacuumFinalize(db, pStmt, pzErrMsg);
106533 }
106534 
106535 /*
106536 ** Execute zSql on database db. The statement returns exactly
106537 ** one column. Execute this as SQL on the same database.
106538 */
106539 static int execExecSql(sqlite3 *db, char **pzErrMsg, const char *zSql){
106540   sqlite3_stmt *pStmt;
106541   int rc;
106542 
106543   rc = sqlite3_prepare(db, zSql, -1, &pStmt, 0);
106544   if( rc!=SQLITE_OK ) return rc;
106545 
106546   while( SQLITE_ROW==sqlite3_step(pStmt) ){
106547     rc = execSql(db, pzErrMsg, (char*)sqlite3_column_text(pStmt, 0));
106548     if( rc!=SQLITE_OK ){
106549       vacuumFinalize(db, pStmt, pzErrMsg);
106550       return rc;
106551     }
106552   }
106553 
106554   return vacuumFinalize(db, pStmt, pzErrMsg);
106555 }
106556 
106557 /*
106558 ** The VACUUM command is used to clean up the database,
106559 ** collapse free space, etc.  It is modelled after the VACUUM command
106560 ** in PostgreSQL.  The VACUUM command works as follows:
106561 **
106562 **   (1)  Create a new transient database file
106563 **   (2)  Copy all content from the database being vacuumed into
106564 **        the new transient database file
106565 **   (3)  Copy content from the transient database back into the
106566 **        original database.
106567 **
106568 ** The transient database requires temporary disk space approximately
106569 ** equal to the size of the original database.  The copy operation of
106570 ** step (3) requires additional temporary disk space approximately equal
106571 ** to the size of the original database for the rollback journal.
106572 ** Hence, temporary disk space that is approximately 2x the size of the
106573 ** orginal database is required.  Every page of the database is written
106574 ** approximately 3 times:  Once for step (2) and twice for step (3).
106575 ** Two writes per page are required in step (3) because the original
106576 ** database content must be written into the rollback journal prior to
106577 ** overwriting the database with the vacuumed content.
106578 **
106579 ** Only 1x temporary space and only 1x writes would be required if
106580 ** the copy of step (3) were replace by deleting the original database
106581 ** and renaming the transient database as the original.  But that will
106582 ** not work if other processes are attached to the original database.
106583 ** And a power loss in between deleting the original and renaming the
106584 ** transient would cause the database file to appear to be deleted
106585 ** following reboot.
106586 */
106587 SQLITE_PRIVATE void sqlite3Vacuum(Parse *pParse){
106588   Vdbe *v = sqlite3GetVdbe(pParse);
106589   if( v ){
106590     sqlite3VdbeAddOp2(v, OP_Vacuum, 0, 0);
106591     sqlite3VdbeUsesBtree(v, 0);
106592   }
106593   return;
106594 }
106595 
106596 /*
106597 ** This routine implements the OP_Vacuum opcode of the VDBE.
106598 */
106599 SQLITE_PRIVATE int sqlite3RunVacuum(char **pzErrMsg, sqlite3 *db){
106600   int rc = SQLITE_OK;     /* Return code from service routines */
106601   Btree *pMain;           /* The database being vacuumed */
106602   Btree *pTemp;           /* The temporary database we vacuum into */
106603   char *zSql = 0;         /* SQL statements */
106604   int saved_flags;        /* Saved value of the db->flags */
106605   int saved_nChange;      /* Saved value of db->nChange */
106606   int saved_nTotalChange; /* Saved value of db->nTotalChange */
106607   void (*saved_xTrace)(void*,const char*);  /* Saved db->xTrace */
106608   Db *pDb = 0;            /* Database to detach at end of vacuum */
106609   int isMemDb;            /* True if vacuuming a :memory: database */
106610   int nRes;               /* Bytes of reserved space at the end of each page */
106611   int nDb;                /* Number of attached databases */
106612 
106613   if( !db->autoCommit ){
106614     sqlite3SetString(pzErrMsg, db, "cannot VACUUM from within a transaction");
106615     return SQLITE_ERROR;
106616   }
106617   if( db->nVdbeActive>1 ){
106618     sqlite3SetString(pzErrMsg, db,"cannot VACUUM - SQL statements in progress");
106619     return SQLITE_ERROR;
106620   }
106621 
106622   /* Save the current value of the database flags so that it can be 
106623   ** restored before returning. Then set the writable-schema flag, and
106624   ** disable CHECK and foreign key constraints.  */
106625   saved_flags = db->flags;
106626   saved_nChange = db->nChange;
106627   saved_nTotalChange = db->nTotalChange;
106628   saved_xTrace = db->xTrace;
106629   db->flags |= SQLITE_WriteSchema | SQLITE_IgnoreChecks | SQLITE_PreferBuiltin;
106630   db->flags &= ~(SQLITE_ForeignKeys | SQLITE_ReverseOrder);
106631   db->xTrace = 0;
106632 
106633   pMain = db->aDb[0].pBt;
106634   isMemDb = sqlite3PagerIsMemdb(sqlite3BtreePager(pMain));
106635 
106636   /* Attach the temporary database as 'vacuum_db'. The synchronous pragma
106637   ** can be set to 'off' for this file, as it is not recovered if a crash
106638   ** occurs anyway. The integrity of the database is maintained by a
106639   ** (possibly synchronous) transaction opened on the main database before
106640   ** sqlite3BtreeCopyFile() is called.
106641   **
106642   ** An optimisation would be to use a non-journaled pager.
106643   ** (Later:) I tried setting "PRAGMA vacuum_db.journal_mode=OFF" but
106644   ** that actually made the VACUUM run slower.  Very little journalling
106645   ** actually occurs when doing a vacuum since the vacuum_db is initially
106646   ** empty.  Only the journal header is written.  Apparently it takes more
106647   ** time to parse and run the PRAGMA to turn journalling off than it does
106648   ** to write the journal header file.
106649   */
106650   nDb = db->nDb;
106651   if( sqlite3TempInMemory(db) ){
106652     zSql = "ATTACH ':memory:' AS vacuum_db;";
106653   }else{
106654     zSql = "ATTACH '' AS vacuum_db;";
106655   }
106656   rc = execSql(db, pzErrMsg, zSql);
106657   if( db->nDb>nDb ){
106658     pDb = &db->aDb[db->nDb-1];
106659     assert( strcmp(pDb->zName,"vacuum_db")==0 );
106660   }
106661   if( rc!=SQLITE_OK ) goto end_of_vacuum;
106662   pTemp = db->aDb[db->nDb-1].pBt;
106663 
106664   /* The call to execSql() to attach the temp database has left the file
106665   ** locked (as there was more than one active statement when the transaction
106666   ** to read the schema was concluded. Unlock it here so that this doesn't
106667   ** cause problems for the call to BtreeSetPageSize() below.  */
106668   sqlite3BtreeCommit(pTemp);
106669 
106670   nRes = sqlite3BtreeGetReserve(pMain);
106671 
106672   /* A VACUUM cannot change the pagesize of an encrypted database. */
106673 #ifdef SQLITE_HAS_CODEC
106674   if( db->nextPagesize ){
106675     extern void sqlite3CodecGetKey(sqlite3*, int, void**, int*);
106676     int nKey;
106677     char *zKey;
106678     sqlite3CodecGetKey(db, 0, (void**)&zKey, &nKey);
106679     if( nKey ) db->nextPagesize = 0;
106680   }
106681 #endif
106682 
106683   rc = execSql(db, pzErrMsg, "PRAGMA vacuum_db.synchronous=OFF");
106684   if( rc!=SQLITE_OK ) goto end_of_vacuum;
106685 
106686   /* Begin a transaction and take an exclusive lock on the main database
106687   ** file. This is done before the sqlite3BtreeGetPageSize(pMain) call below,
106688   ** to ensure that we do not try to change the page-size on a WAL database.
106689   */
106690   rc = execSql(db, pzErrMsg, "BEGIN;");
106691   if( rc!=SQLITE_OK ) goto end_of_vacuum;
106692   rc = sqlite3BtreeBeginTrans(pMain, 2);
106693   if( rc!=SQLITE_OK ) goto end_of_vacuum;
106694 
106695   /* Do not attempt to change the page size for a WAL database */
106696   if( sqlite3PagerGetJournalMode(sqlite3BtreePager(pMain))
106697                                                ==PAGER_JOURNALMODE_WAL ){
106698     db->nextPagesize = 0;
106699   }
106700 
106701   if( sqlite3BtreeSetPageSize(pTemp, sqlite3BtreeGetPageSize(pMain), nRes, 0)
106702    || (!isMemDb && sqlite3BtreeSetPageSize(pTemp, db->nextPagesize, nRes, 0))
106703    || NEVER(db->mallocFailed)
106704   ){
106705     rc = SQLITE_NOMEM;
106706     goto end_of_vacuum;
106707   }
106708 
106709 #ifndef SQLITE_OMIT_AUTOVACUUM
106710   sqlite3BtreeSetAutoVacuum(pTemp, db->nextAutovac>=0 ? db->nextAutovac :
106711                                            sqlite3BtreeGetAutoVacuum(pMain));
106712 #endif
106713 
106714   /* Query the schema of the main database. Create a mirror schema
106715   ** in the temporary database.
106716   */
106717   rc = execExecSql(db, pzErrMsg,
106718       "SELECT 'CREATE TABLE vacuum_db.' || substr(sql,14) "
106719       "  FROM sqlite_master WHERE type='table' AND name!='sqlite_sequence'"
106720       "   AND coalesce(rootpage,1)>0"
106721   );
106722   if( rc!=SQLITE_OK ) goto end_of_vacuum;
106723   rc = execExecSql(db, pzErrMsg,
106724       "SELECT 'CREATE INDEX vacuum_db.' || substr(sql,14)"
106725       "  FROM sqlite_master WHERE sql LIKE 'CREATE INDEX %' ");
106726   if( rc!=SQLITE_OK ) goto end_of_vacuum;
106727   rc = execExecSql(db, pzErrMsg,
106728       "SELECT 'CREATE UNIQUE INDEX vacuum_db.' || substr(sql,21) "
106729       "  FROM sqlite_master WHERE sql LIKE 'CREATE UNIQUE INDEX %'");
106730   if( rc!=SQLITE_OK ) goto end_of_vacuum;
106731 
106732   /* Loop through the tables in the main database. For each, do
106733   ** an "INSERT INTO vacuum_db.xxx SELECT * FROM main.xxx;" to copy
106734   ** the contents to the temporary database.
106735   */
106736   rc = execExecSql(db, pzErrMsg,
106737       "SELECT 'INSERT INTO vacuum_db.' || quote(name) "
106738       "|| ' SELECT * FROM main.' || quote(name) || ';'"
106739       "FROM main.sqlite_master "
106740       "WHERE type = 'table' AND name!='sqlite_sequence' "
106741       "  AND coalesce(rootpage,1)>0"
106742   );
106743   if( rc!=SQLITE_OK ) goto end_of_vacuum;
106744 
106745   /* Copy over the sequence table
106746   */
106747   rc = execExecSql(db, pzErrMsg,
106748       "SELECT 'DELETE FROM vacuum_db.' || quote(name) || ';' "
106749       "FROM vacuum_db.sqlite_master WHERE name='sqlite_sequence' "
106750   );
106751   if( rc!=SQLITE_OK ) goto end_of_vacuum;
106752   rc = execExecSql(db, pzErrMsg,
106753       "SELECT 'INSERT INTO vacuum_db.' || quote(name) "
106754       "|| ' SELECT * FROM main.' || quote(name) || ';' "
106755       "FROM vacuum_db.sqlite_master WHERE name=='sqlite_sequence';"
106756   );
106757   if( rc!=SQLITE_OK ) goto end_of_vacuum;
106758 
106759 
106760   /* Copy the triggers, views, and virtual tables from the main database
106761   ** over to the temporary database.  None of these objects has any
106762   ** associated storage, so all we have to do is copy their entries
106763   ** from the SQLITE_MASTER table.
106764   */
106765   rc = execSql(db, pzErrMsg,
106766       "INSERT INTO vacuum_db.sqlite_master "
106767       "  SELECT type, name, tbl_name, rootpage, sql"
106768       "    FROM main.sqlite_master"
106769       "   WHERE type='view' OR type='trigger'"
106770       "      OR (type='table' AND rootpage=0)"
106771   );
106772   if( rc ) goto end_of_vacuum;
106773 
106774   /* At this point, there is a write transaction open on both the 
106775   ** vacuum database and the main database. Assuming no error occurs,
106776   ** both transactions are closed by this block - the main database
106777   ** transaction by sqlite3BtreeCopyFile() and the other by an explicit
106778   ** call to sqlite3BtreeCommit().
106779   */
106780   {
106781     u32 meta;
106782     int i;
106783 
106784     /* This array determines which meta meta values are preserved in the
106785     ** vacuum.  Even entries are the meta value number and odd entries
106786     ** are an increment to apply to the meta value after the vacuum.
106787     ** The increment is used to increase the schema cookie so that other
106788     ** connections to the same database will know to reread the schema.
106789     */
106790     static const unsigned char aCopy[] = {
106791        BTREE_SCHEMA_VERSION,     1,  /* Add one to the old schema cookie */
106792        BTREE_DEFAULT_CACHE_SIZE, 0,  /* Preserve the default page cache size */
106793        BTREE_TEXT_ENCODING,      0,  /* Preserve the text encoding */
106794        BTREE_USER_VERSION,       0,  /* Preserve the user version */
106795        BTREE_APPLICATION_ID,     0,  /* Preserve the application id */
106796     };
106797 
106798     assert( 1==sqlite3BtreeIsInTrans(pTemp) );
106799     assert( 1==sqlite3BtreeIsInTrans(pMain) );
106800 
106801     /* Copy Btree meta values */
106802     for(i=0; i<ArraySize(aCopy); i+=2){
106803       /* GetMeta() and UpdateMeta() cannot fail in this context because
106804       ** we already have page 1 loaded into cache and marked dirty. */
106805       sqlite3BtreeGetMeta(pMain, aCopy[i], &meta);
106806       rc = sqlite3BtreeUpdateMeta(pTemp, aCopy[i], meta+aCopy[i+1]);
106807       if( NEVER(rc!=SQLITE_OK) ) goto end_of_vacuum;
106808     }
106809 
106810     rc = sqlite3BtreeCopyFile(pMain, pTemp);
106811     if( rc!=SQLITE_OK ) goto end_of_vacuum;
106812     rc = sqlite3BtreeCommit(pTemp);
106813     if( rc!=SQLITE_OK ) goto end_of_vacuum;
106814 #ifndef SQLITE_OMIT_AUTOVACUUM
106815     sqlite3BtreeSetAutoVacuum(pMain, sqlite3BtreeGetAutoVacuum(pTemp));
106816 #endif
106817   }
106818 
106819   assert( rc==SQLITE_OK );
106820   rc = sqlite3BtreeSetPageSize(pMain, sqlite3BtreeGetPageSize(pTemp), nRes,1);
106821 
106822 end_of_vacuum:
106823   /* Restore the original value of db->flags */
106824   db->flags = saved_flags;
106825   db->nChange = saved_nChange;
106826   db->nTotalChange = saved_nTotalChange;
106827   db->xTrace = saved_xTrace;
106828   sqlite3BtreeSetPageSize(pMain, -1, -1, 1);
106829 
106830   /* Currently there is an SQL level transaction open on the vacuum
106831   ** database. No locks are held on any other files (since the main file
106832   ** was committed at the btree level). So it safe to end the transaction
106833   ** by manually setting the autoCommit flag to true and detaching the
106834   ** vacuum database. The vacuum_db journal file is deleted when the pager
106835   ** is closed by the DETACH.
106836   */
106837   db->autoCommit = 1;
106838 
106839   if( pDb ){
106840     sqlite3BtreeClose(pDb->pBt);
106841     pDb->pBt = 0;
106842     pDb->pSchema = 0;
106843   }
106844 
106845   /* This both clears the schemas and reduces the size of the db->aDb[]
106846   ** array. */ 
106847   sqlite3ResetAllSchemasOfConnection(db);
106848 
106849   return rc;
106850 }
106851 
106852 #endif  /* SQLITE_OMIT_VACUUM && SQLITE_OMIT_ATTACH */
106853 
106854 /************** End of vacuum.c **********************************************/
106855 /************** Begin file vtab.c ********************************************/
106856 /*
106857 ** 2006 June 10
106858 **
106859 ** The author disclaims copyright to this source code.  In place of
106860 ** a legal notice, here is a blessing:
106861 **
106862 **    May you do good and not evil.
106863 **    May you find forgiveness for yourself and forgive others.
106864 **    May you share freely, never taking more than you give.
106865 **
106866 *************************************************************************
106867 ** This file contains code used to help implement virtual tables.
106868 */
106869 #ifndef SQLITE_OMIT_VIRTUALTABLE
106870 
106871 /*
106872 ** Before a virtual table xCreate() or xConnect() method is invoked, the
106873 ** sqlite3.pVtabCtx member variable is set to point to an instance of
106874 ** this struct allocated on the stack. It is used by the implementation of 
106875 ** the sqlite3_declare_vtab() and sqlite3_vtab_config() APIs, both of which
106876 ** are invoked only from within xCreate and xConnect methods.
106877 */
106878 struct VtabCtx {
106879   VTable *pVTable;    /* The virtual table being constructed */
106880   Table *pTab;        /* The Table object to which the virtual table belongs */
106881 };
106882 
106883 /*
106884 ** The actual function that does the work of creating a new module.
106885 ** This function implements the sqlite3_create_module() and
106886 ** sqlite3_create_module_v2() interfaces.
106887 */
106888 static int createModule(
106889   sqlite3 *db,                    /* Database in which module is registered */
106890   const char *zName,              /* Name assigned to this module */
106891   const sqlite3_module *pModule,  /* The definition of the module */
106892   void *pAux,                     /* Context pointer for xCreate/xConnect */
106893   void (*xDestroy)(void *)        /* Module destructor function */
106894 ){
106895   int rc = SQLITE_OK;
106896   int nName;
106897 
106898   sqlite3_mutex_enter(db->mutex);
106899   nName = sqlite3Strlen30(zName);
106900   if( sqlite3HashFind(&db->aModule, zName, nName) ){
106901     rc = SQLITE_MISUSE_BKPT;
106902   }else{
106903     Module *pMod;
106904     pMod = (Module *)sqlite3DbMallocRaw(db, sizeof(Module) + nName + 1);
106905     if( pMod ){
106906       Module *pDel;
106907       char *zCopy = (char *)(&pMod[1]);
106908       memcpy(zCopy, zName, nName+1);
106909       pMod->zName = zCopy;
106910       pMod->pModule = pModule;
106911       pMod->pAux = pAux;
106912       pMod->xDestroy = xDestroy;
106913       pDel = (Module *)sqlite3HashInsert(&db->aModule,zCopy,nName,(void*)pMod);
106914       assert( pDel==0 || pDel==pMod );
106915       if( pDel ){
106916         db->mallocFailed = 1;
106917         sqlite3DbFree(db, pDel);
106918       }
106919     }
106920   }
106921   rc = sqlite3ApiExit(db, rc);
106922   if( rc!=SQLITE_OK && xDestroy ) xDestroy(pAux);
106923 
106924   sqlite3_mutex_leave(db->mutex);
106925   return rc;
106926 }
106927 
106928 
106929 /*
106930 ** External API function used to create a new virtual-table module.
106931 */
106932 SQLITE_API int sqlite3_create_module(
106933   sqlite3 *db,                    /* Database in which module is registered */
106934   const char *zName,              /* Name assigned to this module */
106935   const sqlite3_module *pModule,  /* The definition of the module */
106936   void *pAux                      /* Context pointer for xCreate/xConnect */
106937 ){
106938   return createModule(db, zName, pModule, pAux, 0);
106939 }
106940 
106941 /*
106942 ** External API function used to create a new virtual-table module.
106943 */
106944 SQLITE_API int sqlite3_create_module_v2(
106945   sqlite3 *db,                    /* Database in which module is registered */
106946   const char *zName,              /* Name assigned to this module */
106947   const sqlite3_module *pModule,  /* The definition of the module */
106948   void *pAux,                     /* Context pointer for xCreate/xConnect */
106949   void (*xDestroy)(void *)        /* Module destructor function */
106950 ){
106951   return createModule(db, zName, pModule, pAux, xDestroy);
106952 }
106953 
106954 /*
106955 ** Lock the virtual table so that it cannot be disconnected.
106956 ** Locks nest.  Every lock should have a corresponding unlock.
106957 ** If an unlock is omitted, resources leaks will occur.  
106958 **
106959 ** If a disconnect is attempted while a virtual table is locked,
106960 ** the disconnect is deferred until all locks have been removed.
106961 */
106962 SQLITE_PRIVATE void sqlite3VtabLock(VTable *pVTab){
106963   pVTab->nRef++;
106964 }
106965 
106966 
106967 /*
106968 ** pTab is a pointer to a Table structure representing a virtual-table.
106969 ** Return a pointer to the VTable object used by connection db to access 
106970 ** this virtual-table, if one has been created, or NULL otherwise.
106971 */
106972 SQLITE_PRIVATE VTable *sqlite3GetVTable(sqlite3 *db, Table *pTab){
106973   VTable *pVtab;
106974   assert( IsVirtual(pTab) );
106975   for(pVtab=pTab->pVTable; pVtab && pVtab->db!=db; pVtab=pVtab->pNext);
106976   return pVtab;
106977 }
106978 
106979 /*
106980 ** Decrement the ref-count on a virtual table object. When the ref-count
106981 ** reaches zero, call the xDisconnect() method to delete the object.
106982 */
106983 SQLITE_PRIVATE void sqlite3VtabUnlock(VTable *pVTab){
106984   sqlite3 *db = pVTab->db;
106985 
106986   assert( db );
106987   assert( pVTab->nRef>0 );
106988   assert( db->magic==SQLITE_MAGIC_OPEN || db->magic==SQLITE_MAGIC_ZOMBIE );
106989 
106990   pVTab->nRef--;
106991   if( pVTab->nRef==0 ){
106992     sqlite3_vtab *p = pVTab->pVtab;
106993     if( p ){
106994       p->pModule->xDisconnect(p);
106995     }
106996     sqlite3DbFree(db, pVTab);
106997   }
106998 }
106999 
107000 /*
107001 ** Table p is a virtual table. This function moves all elements in the
107002 ** p->pVTable list to the sqlite3.pDisconnect lists of their associated
107003 ** database connections to be disconnected at the next opportunity. 
107004 ** Except, if argument db is not NULL, then the entry associated with
107005 ** connection db is left in the p->pVTable list.
107006 */
107007 static VTable *vtabDisconnectAll(sqlite3 *db, Table *p){
107008   VTable *pRet = 0;
107009   VTable *pVTable = p->pVTable;
107010   p->pVTable = 0;
107011 
107012   /* Assert that the mutex (if any) associated with the BtShared database 
107013   ** that contains table p is held by the caller. See header comments 
107014   ** above function sqlite3VtabUnlockList() for an explanation of why
107015   ** this makes it safe to access the sqlite3.pDisconnect list of any
107016   ** database connection that may have an entry in the p->pVTable list.
107017   */
107018   assert( db==0 || sqlite3SchemaMutexHeld(db, 0, p->pSchema) );
107019 
107020   while( pVTable ){
107021     sqlite3 *db2 = pVTable->db;
107022     VTable *pNext = pVTable->pNext;
107023     assert( db2 );
107024     if( db2==db ){
107025       pRet = pVTable;
107026       p->pVTable = pRet;
107027       pRet->pNext = 0;
107028     }else{
107029       pVTable->pNext = db2->pDisconnect;
107030       db2->pDisconnect = pVTable;
107031     }
107032     pVTable = pNext;
107033   }
107034 
107035   assert( !db || pRet );
107036   return pRet;
107037 }
107038 
107039 /*
107040 ** Table *p is a virtual table. This function removes the VTable object
107041 ** for table *p associated with database connection db from the linked
107042 ** list in p->pVTab. It also decrements the VTable ref count. This is
107043 ** used when closing database connection db to free all of its VTable
107044 ** objects without disturbing the rest of the Schema object (which may
107045 ** be being used by other shared-cache connections).
107046 */
107047 SQLITE_PRIVATE void sqlite3VtabDisconnect(sqlite3 *db, Table *p){
107048   VTable **ppVTab;
107049 
107050   assert( IsVirtual(p) );
107051   assert( sqlite3BtreeHoldsAllMutexes(db) );
107052   assert( sqlite3_mutex_held(db->mutex) );
107053 
107054   for(ppVTab=&p->pVTable; *ppVTab; ppVTab=&(*ppVTab)->pNext){
107055     if( (*ppVTab)->db==db  ){
107056       VTable *pVTab = *ppVTab;
107057       *ppVTab = pVTab->pNext;
107058       sqlite3VtabUnlock(pVTab);
107059       break;
107060     }
107061   }
107062 }
107063 
107064 
107065 /*
107066 ** Disconnect all the virtual table objects in the sqlite3.pDisconnect list.
107067 **
107068 ** This function may only be called when the mutexes associated with all
107069 ** shared b-tree databases opened using connection db are held by the 
107070 ** caller. This is done to protect the sqlite3.pDisconnect list. The
107071 ** sqlite3.pDisconnect list is accessed only as follows:
107072 **
107073 **   1) By this function. In this case, all BtShared mutexes and the mutex
107074 **      associated with the database handle itself must be held.
107075 **
107076 **   2) By function vtabDisconnectAll(), when it adds a VTable entry to
107077 **      the sqlite3.pDisconnect list. In this case either the BtShared mutex
107078 **      associated with the database the virtual table is stored in is held
107079 **      or, if the virtual table is stored in a non-sharable database, then
107080 **      the database handle mutex is held.
107081 **
107082 ** As a result, a sqlite3.pDisconnect cannot be accessed simultaneously 
107083 ** by multiple threads. It is thread-safe.
107084 */
107085 SQLITE_PRIVATE void sqlite3VtabUnlockList(sqlite3 *db){
107086   VTable *p = db->pDisconnect;
107087   db->pDisconnect = 0;
107088 
107089   assert( sqlite3BtreeHoldsAllMutexes(db) );
107090   assert( sqlite3_mutex_held(db->mutex) );
107091 
107092   if( p ){
107093     sqlite3ExpirePreparedStatements(db);
107094     do {
107095       VTable *pNext = p->pNext;
107096       sqlite3VtabUnlock(p);
107097       p = pNext;
107098     }while( p );
107099   }
107100 }
107101 
107102 /*
107103 ** Clear any and all virtual-table information from the Table record.
107104 ** This routine is called, for example, just before deleting the Table
107105 ** record.
107106 **
107107 ** Since it is a virtual-table, the Table structure contains a pointer
107108 ** to the head of a linked list of VTable structures. Each VTable 
107109 ** structure is associated with a single sqlite3* user of the schema.
107110 ** The reference count of the VTable structure associated with database 
107111 ** connection db is decremented immediately (which may lead to the 
107112 ** structure being xDisconnected and free). Any other VTable structures
107113 ** in the list are moved to the sqlite3.pDisconnect list of the associated 
107114 ** database connection.
107115 */
107116 SQLITE_PRIVATE void sqlite3VtabClear(sqlite3 *db, Table *p){
107117   if( !db || db->pnBytesFreed==0 ) vtabDisconnectAll(0, p);
107118   if( p->azModuleArg ){
107119     int i;
107120     for(i=0; i<p->nModuleArg; i++){
107121       if( i!=1 ) sqlite3DbFree(db, p->azModuleArg[i]);
107122     }
107123     sqlite3DbFree(db, p->azModuleArg);
107124   }
107125 }
107126 
107127 /*
107128 ** Add a new module argument to pTable->azModuleArg[].
107129 ** The string is not copied - the pointer is stored.  The
107130 ** string will be freed automatically when the table is
107131 ** deleted.
107132 */
107133 static void addModuleArgument(sqlite3 *db, Table *pTable, char *zArg){
107134   int i = pTable->nModuleArg++;
107135   int nBytes = sizeof(char *)*(1+pTable->nModuleArg);
107136   char **azModuleArg;
107137   azModuleArg = sqlite3DbRealloc(db, pTable->azModuleArg, nBytes);
107138   if( azModuleArg==0 ){
107139     int j;
107140     for(j=0; j<i; j++){
107141       sqlite3DbFree(db, pTable->azModuleArg[j]);
107142     }
107143     sqlite3DbFree(db, zArg);
107144     sqlite3DbFree(db, pTable->azModuleArg);
107145     pTable->nModuleArg = 0;
107146   }else{
107147     azModuleArg[i] = zArg;
107148     azModuleArg[i+1] = 0;
107149   }
107150   pTable->azModuleArg = azModuleArg;
107151 }
107152 
107153 /*
107154 ** The parser calls this routine when it first sees a CREATE VIRTUAL TABLE
107155 ** statement.  The module name has been parsed, but the optional list
107156 ** of parameters that follow the module name are still pending.
107157 */
107158 SQLITE_PRIVATE void sqlite3VtabBeginParse(
107159   Parse *pParse,        /* Parsing context */
107160   Token *pName1,        /* Name of new table, or database name */
107161   Token *pName2,        /* Name of new table or NULL */
107162   Token *pModuleName,   /* Name of the module for the virtual table */
107163   int ifNotExists       /* No error if the table already exists */
107164 ){
107165   int iDb;              /* The database the table is being created in */
107166   Table *pTable;        /* The new virtual table */
107167   sqlite3 *db;          /* Database connection */
107168 
107169   sqlite3StartTable(pParse, pName1, pName2, 0, 0, 1, ifNotExists);
107170   pTable = pParse->pNewTable;
107171   if( pTable==0 ) return;
107172   assert( 0==pTable->pIndex );
107173 
107174   db = pParse->db;
107175   iDb = sqlite3SchemaToIndex(db, pTable->pSchema);
107176   assert( iDb>=0 );
107177 
107178   pTable->tabFlags |= TF_Virtual;
107179   pTable->nModuleArg = 0;
107180   addModuleArgument(db, pTable, sqlite3NameFromToken(db, pModuleName));
107181   addModuleArgument(db, pTable, 0);
107182   addModuleArgument(db, pTable, sqlite3DbStrDup(db, pTable->zName));
107183   pParse->sNameToken.n = (int)(&pModuleName->z[pModuleName->n] - pName1->z);
107184 
107185 #ifndef SQLITE_OMIT_AUTHORIZATION
107186   /* Creating a virtual table invokes the authorization callback twice.
107187   ** The first invocation, to obtain permission to INSERT a row into the
107188   ** sqlite_master table, has already been made by sqlite3StartTable().
107189   ** The second call, to obtain permission to create the table, is made now.
107190   */
107191   if( pTable->azModuleArg ){
107192     sqlite3AuthCheck(pParse, SQLITE_CREATE_VTABLE, pTable->zName, 
107193             pTable->azModuleArg[0], pParse->db->aDb[iDb].zName);
107194   }
107195 #endif
107196 }
107197 
107198 /*
107199 ** This routine takes the module argument that has been accumulating
107200 ** in pParse->zArg[] and appends it to the list of arguments on the
107201 ** virtual table currently under construction in pParse->pTable.
107202 */
107203 static void addArgumentToVtab(Parse *pParse){
107204   if( pParse->sArg.z && pParse->pNewTable ){
107205     const char *z = (const char*)pParse->sArg.z;
107206     int n = pParse->sArg.n;
107207     sqlite3 *db = pParse->db;
107208     addModuleArgument(db, pParse->pNewTable, sqlite3DbStrNDup(db, z, n));
107209   }
107210 }
107211 
107212 /*
107213 ** The parser calls this routine after the CREATE VIRTUAL TABLE statement
107214 ** has been completely parsed.
107215 */
107216 SQLITE_PRIVATE void sqlite3VtabFinishParse(Parse *pParse, Token *pEnd){
107217   Table *pTab = pParse->pNewTable;  /* The table being constructed */
107218   sqlite3 *db = pParse->db;         /* The database connection */
107219 
107220   if( pTab==0 ) return;
107221   addArgumentToVtab(pParse);
107222   pParse->sArg.z = 0;
107223   if( pTab->nModuleArg<1 ) return;
107224   
107225   /* If the CREATE VIRTUAL TABLE statement is being entered for the
107226   ** first time (in other words if the virtual table is actually being
107227   ** created now instead of just being read out of sqlite_master) then
107228   ** do additional initialization work and store the statement text
107229   ** in the sqlite_master table.
107230   */
107231   if( !db->init.busy ){
107232     char *zStmt;
107233     char *zWhere;
107234     int iDb;
107235     Vdbe *v;
107236 
107237     /* Compute the complete text of the CREATE VIRTUAL TABLE statement */
107238     if( pEnd ){
107239       pParse->sNameToken.n = (int)(pEnd->z - pParse->sNameToken.z) + pEnd->n;
107240     }
107241     zStmt = sqlite3MPrintf(db, "CREATE VIRTUAL TABLE %T", &pParse->sNameToken);
107242 
107243     /* A slot for the record has already been allocated in the 
107244     ** SQLITE_MASTER table.  We just need to update that slot with all
107245     ** the information we've collected.  
107246     **
107247     ** The VM register number pParse->regRowid holds the rowid of an
107248     ** entry in the sqlite_master table tht was created for this vtab
107249     ** by sqlite3StartTable().
107250     */
107251     iDb = sqlite3SchemaToIndex(db, pTab->pSchema);
107252     sqlite3NestedParse(pParse,
107253       "UPDATE %Q.%s "
107254          "SET type='table', name=%Q, tbl_name=%Q, rootpage=0, sql=%Q "
107255        "WHERE rowid=#%d",
107256       db->aDb[iDb].zName, SCHEMA_TABLE(iDb),
107257       pTab->zName,
107258       pTab->zName,
107259       zStmt,
107260       pParse->regRowid
107261     );
107262     sqlite3DbFree(db, zStmt);
107263     v = sqlite3GetVdbe(pParse);
107264     sqlite3ChangeCookie(pParse, iDb);
107265 
107266     sqlite3VdbeAddOp2(v, OP_Expire, 0, 0);
107267     zWhere = sqlite3MPrintf(db, "name='%q' AND type='table'", pTab->zName);
107268     sqlite3VdbeAddParseSchemaOp(v, iDb, zWhere);
107269     sqlite3VdbeAddOp4(v, OP_VCreate, iDb, 0, 0, 
107270                          pTab->zName, sqlite3Strlen30(pTab->zName) + 1);
107271   }
107272 
107273   /* If we are rereading the sqlite_master table create the in-memory
107274   ** record of the table. The xConnect() method is not called until
107275   ** the first time the virtual table is used in an SQL statement. This
107276   ** allows a schema that contains virtual tables to be loaded before
107277   ** the required virtual table implementations are registered.  */
107278   else {
107279     Table *pOld;
107280     Schema *pSchema = pTab->pSchema;
107281     const char *zName = pTab->zName;
107282     int nName = sqlite3Strlen30(zName);
107283     assert( sqlite3SchemaMutexHeld(db, 0, pSchema) );
107284     pOld = sqlite3HashInsert(&pSchema->tblHash, zName, nName, pTab);
107285     if( pOld ){
107286       db->mallocFailed = 1;
107287       assert( pTab==pOld );  /* Malloc must have failed inside HashInsert() */
107288       return;
107289     }
107290     pParse->pNewTable = 0;
107291   }
107292 }
107293 
107294 /*
107295 ** The parser calls this routine when it sees the first token
107296 ** of an argument to the module name in a CREATE VIRTUAL TABLE statement.
107297 */
107298 SQLITE_PRIVATE void sqlite3VtabArgInit(Parse *pParse){
107299   addArgumentToVtab(pParse);
107300   pParse->sArg.z = 0;
107301   pParse->sArg.n = 0;
107302 }
107303 
107304 /*
107305 ** The parser calls this routine for each token after the first token
107306 ** in an argument to the module name in a CREATE VIRTUAL TABLE statement.
107307 */
107308 SQLITE_PRIVATE void sqlite3VtabArgExtend(Parse *pParse, Token *p){
107309   Token *pArg = &pParse->sArg;
107310   if( pArg->z==0 ){
107311     pArg->z = p->z;
107312     pArg->n = p->n;
107313   }else{
107314     assert(pArg->z < p->z);
107315     pArg->n = (int)(&p->z[p->n] - pArg->z);
107316   }
107317 }
107318 
107319 /*
107320 ** Invoke a virtual table constructor (either xCreate or xConnect). The
107321 ** pointer to the function to invoke is passed as the fourth parameter
107322 ** to this procedure.
107323 */
107324 static int vtabCallConstructor(
107325   sqlite3 *db, 
107326   Table *pTab,
107327   Module *pMod,
107328   int (*xConstruct)(sqlite3*,void*,int,const char*const*,sqlite3_vtab**,char**),
107329   char **pzErr
107330 ){
107331   VtabCtx sCtx, *pPriorCtx;
107332   VTable *pVTable;
107333   int rc;
107334   const char *const*azArg = (const char *const*)pTab->azModuleArg;
107335   int nArg = pTab->nModuleArg;
107336   char *zErr = 0;
107337   char *zModuleName = sqlite3MPrintf(db, "%s", pTab->zName);
107338   int iDb;
107339 
107340   if( !zModuleName ){
107341     return SQLITE_NOMEM;
107342   }
107343 
107344   pVTable = sqlite3DbMallocZero(db, sizeof(VTable));
107345   if( !pVTable ){
107346     sqlite3DbFree(db, zModuleName);
107347     return SQLITE_NOMEM;
107348   }
107349   pVTable->db = db;
107350   pVTable->pMod = pMod;
107351 
107352   iDb = sqlite3SchemaToIndex(db, pTab->pSchema);
107353   pTab->azModuleArg[1] = db->aDb[iDb].zName;
107354 
107355   /* Invoke the virtual table constructor */
107356   assert( &db->pVtabCtx );
107357   assert( xConstruct );
107358   sCtx.pTab = pTab;
107359   sCtx.pVTable = pVTable;
107360   pPriorCtx = db->pVtabCtx;
107361   db->pVtabCtx = &sCtx;
107362   rc = xConstruct(db, pMod->pAux, nArg, azArg, &pVTable->pVtab, &zErr);
107363   db->pVtabCtx = pPriorCtx;
107364   if( rc==SQLITE_NOMEM ) db->mallocFailed = 1;
107365 
107366   if( SQLITE_OK!=rc ){
107367     if( zErr==0 ){
107368       *pzErr = sqlite3MPrintf(db, "vtable constructor failed: %s", zModuleName);
107369     }else {
107370       *pzErr = sqlite3MPrintf(db, "%s", zErr);
107371       sqlite3_free(zErr);
107372     }
107373     sqlite3DbFree(db, pVTable);
107374   }else if( ALWAYS(pVTable->pVtab) ){
107375     /* Justification of ALWAYS():  A correct vtab constructor must allocate
107376     ** the sqlite3_vtab object if successful.  */
107377     pVTable->pVtab->pModule = pMod->pModule;
107378     pVTable->nRef = 1;
107379     if( sCtx.pTab ){
107380       const char *zFormat = "vtable constructor did not declare schema: %s";
107381       *pzErr = sqlite3MPrintf(db, zFormat, pTab->zName);
107382       sqlite3VtabUnlock(pVTable);
107383       rc = SQLITE_ERROR;
107384     }else{
107385       int iCol;
107386       /* If everything went according to plan, link the new VTable structure
107387       ** into the linked list headed by pTab->pVTable. Then loop through the 
107388       ** columns of the table to see if any of them contain the token "hidden".
107389       ** If so, set the Column COLFLAG_HIDDEN flag and remove the token from
107390       ** the type string.  */
107391       pVTable->pNext = pTab->pVTable;
107392       pTab->pVTable = pVTable;
107393 
107394       for(iCol=0; iCol<pTab->nCol; iCol++){
107395         char *zType = pTab->aCol[iCol].zType;
107396         int nType;
107397         int i = 0;
107398         if( !zType ) continue;
107399         nType = sqlite3Strlen30(zType);
107400         if( sqlite3StrNICmp("hidden", zType, 6)||(zType[6] && zType[6]!=' ') ){
107401           for(i=0; i<nType; i++){
107402             if( (0==sqlite3StrNICmp(" hidden", &zType[i], 7))
107403              && (zType[i+7]=='\0' || zType[i+7]==' ')
107404             ){
107405               i++;
107406               break;
107407             }
107408           }
107409         }
107410         if( i<nType ){
107411           int j;
107412           int nDel = 6 + (zType[i+6] ? 1 : 0);
107413           for(j=i; (j+nDel)<=nType; j++){
107414             zType[j] = zType[j+nDel];
107415           }
107416           if( zType[i]=='\0' && i>0 ){
107417             assert(zType[i-1]==' ');
107418             zType[i-1] = '\0';
107419           }
107420           pTab->aCol[iCol].colFlags |= COLFLAG_HIDDEN;
107421         }
107422       }
107423     }
107424   }
107425 
107426   sqlite3DbFree(db, zModuleName);
107427   return rc;
107428 }
107429 
107430 /*
107431 ** This function is invoked by the parser to call the xConnect() method
107432 ** of the virtual table pTab. If an error occurs, an error code is returned 
107433 ** and an error left in pParse.
107434 **
107435 ** This call is a no-op if table pTab is not a virtual table.
107436 */
107437 SQLITE_PRIVATE int sqlite3VtabCallConnect(Parse *pParse, Table *pTab){
107438   sqlite3 *db = pParse->db;
107439   const char *zMod;
107440   Module *pMod;
107441   int rc;
107442 
107443   assert( pTab );
107444   if( (pTab->tabFlags & TF_Virtual)==0 || sqlite3GetVTable(db, pTab) ){
107445     return SQLITE_OK;
107446   }
107447 
107448   /* Locate the required virtual table module */
107449   zMod = pTab->azModuleArg[0];
107450   pMod = (Module*)sqlite3HashFind(&db->aModule, zMod, sqlite3Strlen30(zMod));
107451 
107452   if( !pMod ){
107453     const char *zModule = pTab->azModuleArg[0];
107454     sqlite3ErrorMsg(pParse, "no such module: %s", zModule);
107455     rc = SQLITE_ERROR;
107456   }else{
107457     char *zErr = 0;
107458     rc = vtabCallConstructor(db, pTab, pMod, pMod->pModule->xConnect, &zErr);
107459     if( rc!=SQLITE_OK ){
107460       sqlite3ErrorMsg(pParse, "%s", zErr);
107461     }
107462     sqlite3DbFree(db, zErr);
107463   }
107464 
107465   return rc;
107466 }
107467 /*
107468 ** Grow the db->aVTrans[] array so that there is room for at least one
107469 ** more v-table. Return SQLITE_NOMEM if a malloc fails, or SQLITE_OK otherwise.
107470 */
107471 static int growVTrans(sqlite3 *db){
107472   const int ARRAY_INCR = 5;
107473 
107474   /* Grow the sqlite3.aVTrans array if required */
107475   if( (db->nVTrans%ARRAY_INCR)==0 ){
107476     VTable **aVTrans;
107477     int nBytes = sizeof(sqlite3_vtab *) * (db->nVTrans + ARRAY_INCR);
107478     aVTrans = sqlite3DbRealloc(db, (void *)db->aVTrans, nBytes);
107479     if( !aVTrans ){
107480       return SQLITE_NOMEM;
107481     }
107482     memset(&aVTrans[db->nVTrans], 0, sizeof(sqlite3_vtab *)*ARRAY_INCR);
107483     db->aVTrans = aVTrans;
107484   }
107485 
107486   return SQLITE_OK;
107487 }
107488 
107489 /*
107490 ** Add the virtual table pVTab to the array sqlite3.aVTrans[]. Space should
107491 ** have already been reserved using growVTrans().
107492 */
107493 static void addToVTrans(sqlite3 *db, VTable *pVTab){
107494   /* Add pVtab to the end of sqlite3.aVTrans */
107495   db->aVTrans[db->nVTrans++] = pVTab;
107496   sqlite3VtabLock(pVTab);
107497 }
107498 
107499 /*
107500 ** This function is invoked by the vdbe to call the xCreate method
107501 ** of the virtual table named zTab in database iDb. 
107502 **
107503 ** If an error occurs, *pzErr is set to point an an English language
107504 ** description of the error and an SQLITE_XXX error code is returned.
107505 ** In this case the caller must call sqlite3DbFree(db, ) on *pzErr.
107506 */
107507 SQLITE_PRIVATE int sqlite3VtabCallCreate(sqlite3 *db, int iDb, const char *zTab, char **pzErr){
107508   int rc = SQLITE_OK;
107509   Table *pTab;
107510   Module *pMod;
107511   const char *zMod;
107512 
107513   pTab = sqlite3FindTable(db, zTab, db->aDb[iDb].zName);
107514   assert( pTab && (pTab->tabFlags & TF_Virtual)!=0 && !pTab->pVTable );
107515 
107516   /* Locate the required virtual table module */
107517   zMod = pTab->azModuleArg[0];
107518   pMod = (Module*)sqlite3HashFind(&db->aModule, zMod, sqlite3Strlen30(zMod));
107519 
107520   /* If the module has been registered and includes a Create method, 
107521   ** invoke it now. If the module has not been registered, return an 
107522   ** error. Otherwise, do nothing.
107523   */
107524   if( !pMod ){
107525     *pzErr = sqlite3MPrintf(db, "no such module: %s", zMod);
107526     rc = SQLITE_ERROR;
107527   }else{
107528     rc = vtabCallConstructor(db, pTab, pMod, pMod->pModule->xCreate, pzErr);
107529   }
107530 
107531   /* Justification of ALWAYS():  The xConstructor method is required to
107532   ** create a valid sqlite3_vtab if it returns SQLITE_OK. */
107533   if( rc==SQLITE_OK && ALWAYS(sqlite3GetVTable(db, pTab)) ){
107534     rc = growVTrans(db);
107535     if( rc==SQLITE_OK ){
107536       addToVTrans(db, sqlite3GetVTable(db, pTab));
107537     }
107538   }
107539 
107540   return rc;
107541 }
107542 
107543 /*
107544 ** This function is used to set the schema of a virtual table.  It is only
107545 ** valid to call this function from within the xCreate() or xConnect() of a
107546 ** virtual table module.
107547 */
107548 SQLITE_API int sqlite3_declare_vtab(sqlite3 *db, const char *zCreateTable){
107549   Parse *pParse;
107550 
107551   int rc = SQLITE_OK;
107552   Table *pTab;
107553   char *zErr = 0;
107554 
107555   sqlite3_mutex_enter(db->mutex);
107556   if( !db->pVtabCtx || !(pTab = db->pVtabCtx->pTab) ){
107557     sqlite3Error(db, SQLITE_MISUSE, 0);
107558     sqlite3_mutex_leave(db->mutex);
107559     return SQLITE_MISUSE_BKPT;
107560   }
107561   assert( (pTab->tabFlags & TF_Virtual)!=0 );
107562 
107563   pParse = sqlite3StackAllocZero(db, sizeof(*pParse));
107564   if( pParse==0 ){
107565     rc = SQLITE_NOMEM;
107566   }else{
107567     pParse->declareVtab = 1;
107568     pParse->db = db;
107569     pParse->nQueryLoop = 1;
107570   
107571     if( SQLITE_OK==sqlite3RunParser(pParse, zCreateTable, &zErr) 
107572      && pParse->pNewTable
107573      && !db->mallocFailed
107574      && !pParse->pNewTable->pSelect
107575      && (pParse->pNewTable->tabFlags & TF_Virtual)==0
107576     ){
107577       if( !pTab->aCol ){
107578         pTab->aCol = pParse->pNewTable->aCol;
107579         pTab->nCol = pParse->pNewTable->nCol;
107580         pParse->pNewTable->nCol = 0;
107581         pParse->pNewTable->aCol = 0;
107582       }
107583       db->pVtabCtx->pTab = 0;
107584     }else{
107585       sqlite3Error(db, SQLITE_ERROR, (zErr ? "%s" : 0), zErr);
107586       sqlite3DbFree(db, zErr);
107587       rc = SQLITE_ERROR;
107588     }
107589     pParse->declareVtab = 0;
107590   
107591     if( pParse->pVdbe ){
107592       sqlite3VdbeFinalize(pParse->pVdbe);
107593     }
107594     sqlite3DeleteTable(db, pParse->pNewTable);
107595     sqlite3ParserReset(pParse);
107596     sqlite3StackFree(db, pParse);
107597   }
107598 
107599   assert( (rc&0xff)==rc );
107600   rc = sqlite3ApiExit(db, rc);
107601   sqlite3_mutex_leave(db->mutex);
107602   return rc;
107603 }
107604 
107605 /*
107606 ** This function is invoked by the vdbe to call the xDestroy method
107607 ** of the virtual table named zTab in database iDb. This occurs
107608 ** when a DROP TABLE is mentioned.
107609 **
107610 ** This call is a no-op if zTab is not a virtual table.
107611 */
107612 SQLITE_PRIVATE int sqlite3VtabCallDestroy(sqlite3 *db, int iDb, const char *zTab){
107613   int rc = SQLITE_OK;
107614   Table *pTab;
107615 
107616   pTab = sqlite3FindTable(db, zTab, db->aDb[iDb].zName);
107617   if( ALWAYS(pTab!=0 && pTab->pVTable!=0) ){
107618     VTable *p = vtabDisconnectAll(db, pTab);
107619 
107620     assert( rc==SQLITE_OK );
107621     rc = p->pMod->pModule->xDestroy(p->pVtab);
107622 
107623     /* Remove the sqlite3_vtab* from the aVTrans[] array, if applicable */
107624     if( rc==SQLITE_OK ){
107625       assert( pTab->pVTable==p && p->pNext==0 );
107626       p->pVtab = 0;
107627       pTab->pVTable = 0;
107628       sqlite3VtabUnlock(p);
107629     }
107630   }
107631 
107632   return rc;
107633 }
107634 
107635 /*
107636 ** This function invokes either the xRollback or xCommit method
107637 ** of each of the virtual tables in the sqlite3.aVTrans array. The method
107638 ** called is identified by the second argument, "offset", which is
107639 ** the offset of the method to call in the sqlite3_module structure.
107640 **
107641 ** The array is cleared after invoking the callbacks. 
107642 */
107643 static void callFinaliser(sqlite3 *db, int offset){
107644   int i;
107645   if( db->aVTrans ){
107646     for(i=0; i<db->nVTrans; i++){
107647       VTable *pVTab = db->aVTrans[i];
107648       sqlite3_vtab *p = pVTab->pVtab;
107649       if( p ){
107650         int (*x)(sqlite3_vtab *);
107651         x = *(int (**)(sqlite3_vtab *))((char *)p->pModule + offset);
107652         if( x ) x(p);
107653       }
107654       pVTab->iSavepoint = 0;
107655       sqlite3VtabUnlock(pVTab);
107656     }
107657     sqlite3DbFree(db, db->aVTrans);
107658     db->nVTrans = 0;
107659     db->aVTrans = 0;
107660   }
107661 }
107662 
107663 /*
107664 ** Invoke the xSync method of all virtual tables in the sqlite3.aVTrans
107665 ** array. Return the error code for the first error that occurs, or
107666 ** SQLITE_OK if all xSync operations are successful.
107667 **
107668 ** If an error message is available, leave it in p->zErrMsg.
107669 */
107670 SQLITE_PRIVATE int sqlite3VtabSync(sqlite3 *db, Vdbe *p){
107671   int i;
107672   int rc = SQLITE_OK;
107673   VTable **aVTrans = db->aVTrans;
107674 
107675   db->aVTrans = 0;
107676   for(i=0; rc==SQLITE_OK && i<db->nVTrans; i++){
107677     int (*x)(sqlite3_vtab *);
107678     sqlite3_vtab *pVtab = aVTrans[i]->pVtab;
107679     if( pVtab && (x = pVtab->pModule->xSync)!=0 ){
107680       rc = x(pVtab);
107681       sqlite3VtabImportErrmsg(p, pVtab);
107682     }
107683   }
107684   db->aVTrans = aVTrans;
107685   return rc;
107686 }
107687 
107688 /*
107689 ** Invoke the xRollback method of all virtual tables in the 
107690 ** sqlite3.aVTrans array. Then clear the array itself.
107691 */
107692 SQLITE_PRIVATE int sqlite3VtabRollback(sqlite3 *db){
107693   callFinaliser(db, offsetof(sqlite3_module,xRollback));
107694   return SQLITE_OK;
107695 }
107696 
107697 /*
107698 ** Invoke the xCommit method of all virtual tables in the 
107699 ** sqlite3.aVTrans array. Then clear the array itself.
107700 */
107701 SQLITE_PRIVATE int sqlite3VtabCommit(sqlite3 *db){
107702   callFinaliser(db, offsetof(sqlite3_module,xCommit));
107703   return SQLITE_OK;
107704 }
107705 
107706 /*
107707 ** If the virtual table pVtab supports the transaction interface
107708 ** (xBegin/xRollback/xCommit and optionally xSync) and a transaction is
107709 ** not currently open, invoke the xBegin method now.
107710 **
107711 ** If the xBegin call is successful, place the sqlite3_vtab pointer
107712 ** in the sqlite3.aVTrans array.
107713 */
107714 SQLITE_PRIVATE int sqlite3VtabBegin(sqlite3 *db, VTable *pVTab){
107715   int rc = SQLITE_OK;
107716   const sqlite3_module *pModule;
107717 
107718   /* Special case: If db->aVTrans is NULL and db->nVTrans is greater
107719   ** than zero, then this function is being called from within a
107720   ** virtual module xSync() callback. It is illegal to write to 
107721   ** virtual module tables in this case, so return SQLITE_LOCKED.
107722   */
107723   if( sqlite3VtabInSync(db) ){
107724     return SQLITE_LOCKED;
107725   }
107726   if( !pVTab ){
107727     return SQLITE_OK;
107728   } 
107729   pModule = pVTab->pVtab->pModule;
107730 
107731   if( pModule->xBegin ){
107732     int i;
107733 
107734     /* If pVtab is already in the aVTrans array, return early */
107735     for(i=0; i<db->nVTrans; i++){
107736       if( db->aVTrans[i]==pVTab ){
107737         return SQLITE_OK;
107738       }
107739     }
107740 
107741     /* Invoke the xBegin method. If successful, add the vtab to the 
107742     ** sqlite3.aVTrans[] array. */
107743     rc = growVTrans(db);
107744     if( rc==SQLITE_OK ){
107745       rc = pModule->xBegin(pVTab->pVtab);
107746       if( rc==SQLITE_OK ){
107747         addToVTrans(db, pVTab);
107748       }
107749     }
107750   }
107751   return rc;
107752 }
107753 
107754 /*
107755 ** Invoke either the xSavepoint, xRollbackTo or xRelease method of all
107756 ** virtual tables that currently have an open transaction. Pass iSavepoint
107757 ** as the second argument to the virtual table method invoked.
107758 **
107759 ** If op is SAVEPOINT_BEGIN, the xSavepoint method is invoked. If it is
107760 ** SAVEPOINT_ROLLBACK, the xRollbackTo method. Otherwise, if op is 
107761 ** SAVEPOINT_RELEASE, then the xRelease method of each virtual table with
107762 ** an open transaction is invoked.
107763 **
107764 ** If any virtual table method returns an error code other than SQLITE_OK, 
107765 ** processing is abandoned and the error returned to the caller of this
107766 ** function immediately. If all calls to virtual table methods are successful,
107767 ** SQLITE_OK is returned.
107768 */
107769 SQLITE_PRIVATE int sqlite3VtabSavepoint(sqlite3 *db, int op, int iSavepoint){
107770   int rc = SQLITE_OK;
107771 
107772   assert( op==SAVEPOINT_RELEASE||op==SAVEPOINT_ROLLBACK||op==SAVEPOINT_BEGIN );
107773   assert( iSavepoint>=0 );
107774   if( db->aVTrans ){
107775     int i;
107776     for(i=0; rc==SQLITE_OK && i<db->nVTrans; i++){
107777       VTable *pVTab = db->aVTrans[i];
107778       const sqlite3_module *pMod = pVTab->pMod->pModule;
107779       if( pVTab->pVtab && pMod->iVersion>=2 ){
107780         int (*xMethod)(sqlite3_vtab *, int);
107781         switch( op ){
107782           case SAVEPOINT_BEGIN:
107783             xMethod = pMod->xSavepoint;
107784             pVTab->iSavepoint = iSavepoint+1;
107785             break;
107786           case SAVEPOINT_ROLLBACK:
107787             xMethod = pMod->xRollbackTo;
107788             break;
107789           default:
107790             xMethod = pMod->xRelease;
107791             break;
107792         }
107793         if( xMethod && pVTab->iSavepoint>iSavepoint ){
107794           rc = xMethod(pVTab->pVtab, iSavepoint);
107795         }
107796       }
107797     }
107798   }
107799   return rc;
107800 }
107801 
107802 /*
107803 ** The first parameter (pDef) is a function implementation.  The
107804 ** second parameter (pExpr) is the first argument to this function.
107805 ** If pExpr is a column in a virtual table, then let the virtual
107806 ** table implementation have an opportunity to overload the function.
107807 **
107808 ** This routine is used to allow virtual table implementations to
107809 ** overload MATCH, LIKE, GLOB, and REGEXP operators.
107810 **
107811 ** Return either the pDef argument (indicating no change) or a 
107812 ** new FuncDef structure that is marked as ephemeral using the
107813 ** SQLITE_FUNC_EPHEM flag.
107814 */
107815 SQLITE_PRIVATE FuncDef *sqlite3VtabOverloadFunction(
107816   sqlite3 *db,    /* Database connection for reporting malloc problems */
107817   FuncDef *pDef,  /* Function to possibly overload */
107818   int nArg,       /* Number of arguments to the function */
107819   Expr *pExpr     /* First argument to the function */
107820 ){
107821   Table *pTab;
107822   sqlite3_vtab *pVtab;
107823   sqlite3_module *pMod;
107824   void (*xFunc)(sqlite3_context*,int,sqlite3_value**) = 0;
107825   void *pArg = 0;
107826   FuncDef *pNew;
107827   int rc = 0;
107828   char *zLowerName;
107829   unsigned char *z;
107830 
107831 
107832   /* Check to see the left operand is a column in a virtual table */
107833   if( NEVER(pExpr==0) ) return pDef;
107834   if( pExpr->op!=TK_COLUMN ) return pDef;
107835   pTab = pExpr->pTab;
107836   if( NEVER(pTab==0) ) return pDef;
107837   if( (pTab->tabFlags & TF_Virtual)==0 ) return pDef;
107838   pVtab = sqlite3GetVTable(db, pTab)->pVtab;
107839   assert( pVtab!=0 );
107840   assert( pVtab->pModule!=0 );
107841   pMod = (sqlite3_module *)pVtab->pModule;
107842   if( pMod->xFindFunction==0 ) return pDef;
107843  
107844   /* Call the xFindFunction method on the virtual table implementation
107845   ** to see if the implementation wants to overload this function 
107846   */
107847   zLowerName = sqlite3DbStrDup(db, pDef->zName);
107848   if( zLowerName ){
107849     for(z=(unsigned char*)zLowerName; *z; z++){
107850       *z = sqlite3UpperToLower[*z];
107851     }
107852     rc = pMod->xFindFunction(pVtab, nArg, zLowerName, &xFunc, &pArg);
107853     sqlite3DbFree(db, zLowerName);
107854   }
107855   if( rc==0 ){
107856     return pDef;
107857   }
107858 
107859   /* Create a new ephemeral function definition for the overloaded
107860   ** function */
107861   pNew = sqlite3DbMallocZero(db, sizeof(*pNew)
107862                              + sqlite3Strlen30(pDef->zName) + 1);
107863   if( pNew==0 ){
107864     return pDef;
107865   }
107866   *pNew = *pDef;
107867   pNew->zName = (char *)&pNew[1];
107868   memcpy(pNew->zName, pDef->zName, sqlite3Strlen30(pDef->zName)+1);
107869   pNew->xFunc = xFunc;
107870   pNew->pUserData = pArg;
107871   pNew->funcFlags |= SQLITE_FUNC_EPHEM;
107872   return pNew;
107873 }
107874 
107875 /*
107876 ** Make sure virtual table pTab is contained in the pParse->apVirtualLock[]
107877 ** array so that an OP_VBegin will get generated for it.  Add pTab to the
107878 ** array if it is missing.  If pTab is already in the array, this routine
107879 ** is a no-op.
107880 */
107881 SQLITE_PRIVATE void sqlite3VtabMakeWritable(Parse *pParse, Table *pTab){
107882   Parse *pToplevel = sqlite3ParseToplevel(pParse);
107883   int i, n;
107884   Table **apVtabLock;
107885 
107886   assert( IsVirtual(pTab) );
107887   for(i=0; i<pToplevel->nVtabLock; i++){
107888     if( pTab==pToplevel->apVtabLock[i] ) return;
107889   }
107890   n = (pToplevel->nVtabLock+1)*sizeof(pToplevel->apVtabLock[0]);
107891   apVtabLock = sqlite3_realloc(pToplevel->apVtabLock, n);
107892   if( apVtabLock ){
107893     pToplevel->apVtabLock = apVtabLock;
107894     pToplevel->apVtabLock[pToplevel->nVtabLock++] = pTab;
107895   }else{
107896     pToplevel->db->mallocFailed = 1;
107897   }
107898 }
107899 
107900 /*
107901 ** Return the ON CONFLICT resolution mode in effect for the virtual
107902 ** table update operation currently in progress.
107903 **
107904 ** The results of this routine are undefined unless it is called from
107905 ** within an xUpdate method.
107906 */
107907 SQLITE_API int sqlite3_vtab_on_conflict(sqlite3 *db){
107908   static const unsigned char aMap[] = { 
107909     SQLITE_ROLLBACK, SQLITE_ABORT, SQLITE_FAIL, SQLITE_IGNORE, SQLITE_REPLACE 
107910   };
107911   assert( OE_Rollback==1 && OE_Abort==2 && OE_Fail==3 );
107912   assert( OE_Ignore==4 && OE_Replace==5 );
107913   assert( db->vtabOnConflict>=1 && db->vtabOnConflict<=5 );
107914   return (int)aMap[db->vtabOnConflict-1];
107915 }
107916 
107917 /*
107918 ** Call from within the xCreate() or xConnect() methods to provide 
107919 ** the SQLite core with additional information about the behavior
107920 ** of the virtual table being implemented.
107921 */
107922 SQLITE_API int sqlite3_vtab_config(sqlite3 *db, int op, ...){
107923   va_list ap;
107924   int rc = SQLITE_OK;
107925 
107926   sqlite3_mutex_enter(db->mutex);
107927 
107928   va_start(ap, op);
107929   switch( op ){
107930     case SQLITE_VTAB_CONSTRAINT_SUPPORT: {
107931       VtabCtx *p = db->pVtabCtx;
107932       if( !p ){
107933         rc = SQLITE_MISUSE_BKPT;
107934       }else{
107935         assert( p->pTab==0 || (p->pTab->tabFlags & TF_Virtual)!=0 );
107936         p->pVTable->bConstraint = (u8)va_arg(ap, int);
107937       }
107938       break;
107939     }
107940     default:
107941       rc = SQLITE_MISUSE_BKPT;
107942       break;
107943   }
107944   va_end(ap);
107945 
107946   if( rc!=SQLITE_OK ) sqlite3Error(db, rc, 0);
107947   sqlite3_mutex_leave(db->mutex);
107948   return rc;
107949 }
107950 
107951 #endif /* SQLITE_OMIT_VIRTUALTABLE */
107952 
107953 /************** End of vtab.c ************************************************/
107954 /************** Begin file where.c *******************************************/
107955 /*
107956 ** 2001 September 15
107957 **
107958 ** The author disclaims copyright to this source code.  In place of
107959 ** a legal notice, here is a blessing:
107960 **
107961 **    May you do good and not evil.
107962 **    May you find forgiveness for yourself and forgive others.
107963 **    May you share freely, never taking more than you give.
107964 **
107965 *************************************************************************
107966 ** This module contains C code that generates VDBE code used to process
107967 ** the WHERE clause of SQL statements.  This module is responsible for
107968 ** generating the code that loops through a table looking for applicable
107969 ** rows.  Indices are selected and used to speed the search when doing
107970 ** so is applicable.  Because this module is responsible for selecting
107971 ** indices, you might also think of this module as the "query optimizer".
107972 */
107973 /************** Include whereInt.h in the middle of where.c ******************/
107974 /************** Begin file whereInt.h ****************************************/
107975 /*
107976 ** 2013-11-12
107977 **
107978 ** The author disclaims copyright to this source code.  In place of
107979 ** a legal notice, here is a blessing:
107980 **
107981 **    May you do good and not evil.
107982 **    May you find forgiveness for yourself and forgive others.
107983 **    May you share freely, never taking more than you give.
107984 **
107985 *************************************************************************
107986 **
107987 ** This file contains structure and macro definitions for the query
107988 ** planner logic in "where.c".  These definitions are broken out into
107989 ** a separate source file for easier editing.
107990 */
107991 
107992 /*
107993 ** Trace output macros
107994 */
107995 #if defined(SQLITE_TEST) || defined(SQLITE_DEBUG)
107996 /***/ int sqlite3WhereTrace = 0;
107997 #endif
107998 #if defined(SQLITE_DEBUG) \
107999     && (defined(SQLITE_TEST) || defined(SQLITE_ENABLE_WHERETRACE))
108000 # define WHERETRACE(K,X)  if(sqlite3WhereTrace&(K)) sqlite3DebugPrintf X
108001 # define WHERETRACE_ENABLED 1
108002 #else
108003 # define WHERETRACE(K,X)
108004 #endif
108005 
108006 /* Forward references
108007 */
108008 typedef struct WhereClause WhereClause;
108009 typedef struct WhereMaskSet WhereMaskSet;
108010 typedef struct WhereOrInfo WhereOrInfo;
108011 typedef struct WhereAndInfo WhereAndInfo;
108012 typedef struct WhereLevel WhereLevel;
108013 typedef struct WhereLoop WhereLoop;
108014 typedef struct WherePath WherePath;
108015 typedef struct WhereTerm WhereTerm;
108016 typedef struct WhereLoopBuilder WhereLoopBuilder;
108017 typedef struct WhereScan WhereScan;
108018 typedef struct WhereOrCost WhereOrCost;
108019 typedef struct WhereOrSet WhereOrSet;
108020 
108021 /*
108022 ** This object contains information needed to implement a single nested
108023 ** loop in WHERE clause.
108024 **
108025 ** Contrast this object with WhereLoop.  This object describes the
108026 ** implementation of the loop.  WhereLoop describes the algorithm.
108027 ** This object contains a pointer to the WhereLoop algorithm as one of
108028 ** its elements.
108029 **
108030 ** The WhereInfo object contains a single instance of this object for
108031 ** each term in the FROM clause (which is to say, for each of the
108032 ** nested loops as implemented).  The order of WhereLevel objects determines
108033 ** the loop nested order, with WhereInfo.a[0] being the outer loop and
108034 ** WhereInfo.a[WhereInfo.nLevel-1] being the inner loop.
108035 */
108036 struct WhereLevel {
108037   int iLeftJoin;        /* Memory cell used to implement LEFT OUTER JOIN */
108038   int iTabCur;          /* The VDBE cursor used to access the table */
108039   int iIdxCur;          /* The VDBE cursor used to access pIdx */
108040   int addrBrk;          /* Jump here to break out of the loop */
108041   int addrNxt;          /* Jump here to start the next IN combination */
108042   int addrSkip;         /* Jump here for next iteration of skip-scan */
108043   int addrCont;         /* Jump here to continue with the next loop cycle */
108044   int addrFirst;        /* First instruction of interior of the loop */
108045   int addrBody;         /* Beginning of the body of this loop */
108046   u8 iFrom;             /* Which entry in the FROM clause */
108047   u8 op, p5;            /* Opcode and P5 of the opcode that ends the loop */
108048   int p1, p2;           /* Operands of the opcode used to ends the loop */
108049   union {               /* Information that depends on pWLoop->wsFlags */
108050     struct {
108051       int nIn;              /* Number of entries in aInLoop[] */
108052       struct InLoop {
108053         int iCur;              /* The VDBE cursor used by this IN operator */
108054         int addrInTop;         /* Top of the IN loop */
108055         u8 eEndLoopOp;         /* IN Loop terminator. OP_Next or OP_Prev */
108056       } *aInLoop;           /* Information about each nested IN operator */
108057     } in;                 /* Used when pWLoop->wsFlags&WHERE_IN_ABLE */
108058     Index *pCovidx;       /* Possible covering index for WHERE_MULTI_OR */
108059   } u;
108060   struct WhereLoop *pWLoop;  /* The selected WhereLoop object */
108061   Bitmask notReady;          /* FROM entries not usable at this level */
108062 };
108063 
108064 /*
108065 ** Each instance of this object represents an algorithm for evaluating one
108066 ** term of a join.  Every term of the FROM clause will have at least
108067 ** one corresponding WhereLoop object (unless INDEXED BY constraints
108068 ** prevent a query solution - which is an error) and many terms of the
108069 ** FROM clause will have multiple WhereLoop objects, each describing a
108070 ** potential way of implementing that FROM-clause term, together with
108071 ** dependencies and cost estimates for using the chosen algorithm.
108072 **
108073 ** Query planning consists of building up a collection of these WhereLoop
108074 ** objects, then computing a particular sequence of WhereLoop objects, with
108075 ** one WhereLoop object per FROM clause term, that satisfy all dependencies
108076 ** and that minimize the overall cost.
108077 */
108078 struct WhereLoop {
108079   Bitmask prereq;       /* Bitmask of other loops that must run first */
108080   Bitmask maskSelf;     /* Bitmask identifying table iTab */
108081 #ifdef SQLITE_DEBUG
108082   char cId;             /* Symbolic ID of this loop for debugging use */
108083 #endif
108084   u8 iTab;              /* Position in FROM clause of table for this loop */
108085   u8 iSortIdx;          /* Sorting index number.  0==None */
108086   LogEst rSetup;        /* One-time setup cost (ex: create transient index) */
108087   LogEst rRun;          /* Cost of running each loop */
108088   LogEst nOut;          /* Estimated number of output rows */
108089   union {
108090     struct {               /* Information for internal btree tables */
108091       u16 nEq;               /* Number of equality constraints */
108092       u16 nSkip;             /* Number of initial index columns to skip */
108093       Index *pIndex;         /* Index used, or NULL */
108094     } btree;
108095     struct {               /* Information for virtual tables */
108096       int idxNum;            /* Index number */
108097       u8 needFree;           /* True if sqlite3_free(idxStr) is needed */
108098       u8 isOrdered;          /* True if satisfies ORDER BY */
108099       u16 omitMask;          /* Terms that may be omitted */
108100       char *idxStr;          /* Index identifier string */
108101     } vtab;
108102   } u;
108103   u32 wsFlags;          /* WHERE_* flags describing the plan */
108104   u16 nLTerm;           /* Number of entries in aLTerm[] */
108105   /**** whereLoopXfer() copies fields above ***********************/
108106 # define WHERE_LOOP_XFER_SZ offsetof(WhereLoop,nLSlot)
108107   u16 nLSlot;           /* Number of slots allocated for aLTerm[] */
108108   WhereTerm **aLTerm;   /* WhereTerms used */
108109   WhereLoop *pNextLoop; /* Next WhereLoop object in the WhereClause */
108110   WhereTerm *aLTermSpace[4];  /* Initial aLTerm[] space */
108111 };
108112 
108113 /* This object holds the prerequisites and the cost of running a
108114 ** subquery on one operand of an OR operator in the WHERE clause.
108115 ** See WhereOrSet for additional information 
108116 */
108117 struct WhereOrCost {
108118   Bitmask prereq;     /* Prerequisites */
108119   LogEst rRun;        /* Cost of running this subquery */
108120   LogEst nOut;        /* Number of outputs for this subquery */
108121 };
108122 
108123 /* The WhereOrSet object holds a set of possible WhereOrCosts that
108124 ** correspond to the subquery(s) of OR-clause processing.  Only the
108125 ** best N_OR_COST elements are retained.
108126 */
108127 #define N_OR_COST 3
108128 struct WhereOrSet {
108129   u16 n;                      /* Number of valid a[] entries */
108130   WhereOrCost a[N_OR_COST];   /* Set of best costs */
108131 };
108132 
108133 
108134 /* Forward declaration of methods */
108135 static int whereLoopResize(sqlite3*, WhereLoop*, int);
108136 
108137 /*
108138 ** Each instance of this object holds a sequence of WhereLoop objects
108139 ** that implement some or all of a query plan.
108140 **
108141 ** Think of each WhereLoop object as a node in a graph with arcs
108142 ** showing dependencies and costs for travelling between nodes.  (That is
108143 ** not a completely accurate description because WhereLoop costs are a
108144 ** vector, not a scalar, and because dependencies are many-to-one, not
108145 ** one-to-one as are graph nodes.  But it is a useful visualization aid.)
108146 ** Then a WherePath object is a path through the graph that visits some
108147 ** or all of the WhereLoop objects once.
108148 **
108149 ** The "solver" works by creating the N best WherePath objects of length
108150 ** 1.  Then using those as a basis to compute the N best WherePath objects
108151 ** of length 2.  And so forth until the length of WherePaths equals the
108152 ** number of nodes in the FROM clause.  The best (lowest cost) WherePath
108153 ** at the end is the choosen query plan.
108154 */
108155 struct WherePath {
108156   Bitmask maskLoop;     /* Bitmask of all WhereLoop objects in this path */
108157   Bitmask revLoop;      /* aLoop[]s that should be reversed for ORDER BY */
108158   LogEst nRow;          /* Estimated number of rows generated by this path */
108159   LogEst rCost;         /* Total cost of this path */
108160   u8 isOrdered;         /* True if this path satisfies ORDER BY */
108161   u8 isOrderedValid;    /* True if the isOrdered field is valid */
108162   WhereLoop **aLoop;    /* Array of WhereLoop objects implementing this path */
108163 };
108164 
108165 /*
108166 ** The query generator uses an array of instances of this structure to
108167 ** help it analyze the subexpressions of the WHERE clause.  Each WHERE
108168 ** clause subexpression is separated from the others by AND operators,
108169 ** usually, or sometimes subexpressions separated by OR.
108170 **
108171 ** All WhereTerms are collected into a single WhereClause structure.  
108172 ** The following identity holds:
108173 **
108174 **        WhereTerm.pWC->a[WhereTerm.idx] == WhereTerm
108175 **
108176 ** When a term is of the form:
108177 **
108178 **              X <op> <expr>
108179 **
108180 ** where X is a column name and <op> is one of certain operators,
108181 ** then WhereTerm.leftCursor and WhereTerm.u.leftColumn record the
108182 ** cursor number and column number for X.  WhereTerm.eOperator records
108183 ** the <op> using a bitmask encoding defined by WO_xxx below.  The
108184 ** use of a bitmask encoding for the operator allows us to search
108185 ** quickly for terms that match any of several different operators.
108186 **
108187 ** A WhereTerm might also be two or more subterms connected by OR:
108188 **
108189 **         (t1.X <op> <expr>) OR (t1.Y <op> <expr>) OR ....
108190 **
108191 ** In this second case, wtFlag has the TERM_ORINFO bit set and eOperator==WO_OR
108192 ** and the WhereTerm.u.pOrInfo field points to auxiliary information that
108193 ** is collected about the OR clause.
108194 **
108195 ** If a term in the WHERE clause does not match either of the two previous
108196 ** categories, then eOperator==0.  The WhereTerm.pExpr field is still set
108197 ** to the original subexpression content and wtFlags is set up appropriately
108198 ** but no other fields in the WhereTerm object are meaningful.
108199 **
108200 ** When eOperator!=0, prereqRight and prereqAll record sets of cursor numbers,
108201 ** but they do so indirectly.  A single WhereMaskSet structure translates
108202 ** cursor number into bits and the translated bit is stored in the prereq
108203 ** fields.  The translation is used in order to maximize the number of
108204 ** bits that will fit in a Bitmask.  The VDBE cursor numbers might be
108205 ** spread out over the non-negative integers.  For example, the cursor
108206 ** numbers might be 3, 8, 9, 10, 20, 23, 41, and 45.  The WhereMaskSet
108207 ** translates these sparse cursor numbers into consecutive integers
108208 ** beginning with 0 in order to make the best possible use of the available
108209 ** bits in the Bitmask.  So, in the example above, the cursor numbers
108210 ** would be mapped into integers 0 through 7.
108211 **
108212 ** The number of terms in a join is limited by the number of bits
108213 ** in prereqRight and prereqAll.  The default is 64 bits, hence SQLite
108214 ** is only able to process joins with 64 or fewer tables.
108215 */
108216 struct WhereTerm {
108217   Expr *pExpr;            /* Pointer to the subexpression that is this term */
108218   int iParent;            /* Disable pWC->a[iParent] when this term disabled */
108219   int leftCursor;         /* Cursor number of X in "X <op> <expr>" */
108220   union {
108221     int leftColumn;         /* Column number of X in "X <op> <expr>" */
108222     WhereOrInfo *pOrInfo;   /* Extra information if (eOperator & WO_OR)!=0 */
108223     WhereAndInfo *pAndInfo; /* Extra information if (eOperator& WO_AND)!=0 */
108224   } u;
108225   LogEst truthProb;       /* Probability of truth for this expression */
108226   u16 eOperator;          /* A WO_xx value describing <op> */
108227   u8 wtFlags;             /* TERM_xxx bit flags.  See below */
108228   u8 nChild;              /* Number of children that must disable us */
108229   WhereClause *pWC;       /* The clause this term is part of */
108230   Bitmask prereqRight;    /* Bitmask of tables used by pExpr->pRight */
108231   Bitmask prereqAll;      /* Bitmask of tables referenced by pExpr */
108232 };
108233 
108234 /*
108235 ** Allowed values of WhereTerm.wtFlags
108236 */
108237 #define TERM_DYNAMIC    0x01   /* Need to call sqlite3ExprDelete(db, pExpr) */
108238 #define TERM_VIRTUAL    0x02   /* Added by the optimizer.  Do not code */
108239 #define TERM_CODED      0x04   /* This term is already coded */
108240 #define TERM_COPIED     0x08   /* Has a child */
108241 #define TERM_ORINFO     0x10   /* Need to free the WhereTerm.u.pOrInfo object */
108242 #define TERM_ANDINFO    0x20   /* Need to free the WhereTerm.u.pAndInfo obj */
108243 #define TERM_OR_OK      0x40   /* Used during OR-clause processing */
108244 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
108245 #  define TERM_VNULL    0x80   /* Manufactured x>NULL or x<=NULL term */
108246 #else
108247 #  define TERM_VNULL    0x00   /* Disabled if not using stat3 */
108248 #endif
108249 
108250 /*
108251 ** An instance of the WhereScan object is used as an iterator for locating
108252 ** terms in the WHERE clause that are useful to the query planner.
108253 */
108254 struct WhereScan {
108255   WhereClause *pOrigWC;      /* Original, innermost WhereClause */
108256   WhereClause *pWC;          /* WhereClause currently being scanned */
108257   char *zCollName;           /* Required collating sequence, if not NULL */
108258   char idxaff;               /* Must match this affinity, if zCollName!=NULL */
108259   unsigned char nEquiv;      /* Number of entries in aEquiv[] */
108260   unsigned char iEquiv;      /* Next unused slot in aEquiv[] */
108261   u32 opMask;                /* Acceptable operators */
108262   int k;                     /* Resume scanning at this->pWC->a[this->k] */
108263   int aEquiv[22];            /* Cursor,Column pairs for equivalence classes */
108264 };
108265 
108266 /*
108267 ** An instance of the following structure holds all information about a
108268 ** WHERE clause.  Mostly this is a container for one or more WhereTerms.
108269 **
108270 ** Explanation of pOuter:  For a WHERE clause of the form
108271 **
108272 **           a AND ((b AND c) OR (d AND e)) AND f
108273 **
108274 ** There are separate WhereClause objects for the whole clause and for
108275 ** the subclauses "(b AND c)" and "(d AND e)".  The pOuter field of the
108276 ** subclauses points to the WhereClause object for the whole clause.
108277 */
108278 struct WhereClause {
108279   WhereInfo *pWInfo;       /* WHERE clause processing context */
108280   WhereClause *pOuter;     /* Outer conjunction */
108281   u8 op;                   /* Split operator.  TK_AND or TK_OR */
108282   int nTerm;               /* Number of terms */
108283   int nSlot;               /* Number of entries in a[] */
108284   WhereTerm *a;            /* Each a[] describes a term of the WHERE cluase */
108285 #if defined(SQLITE_SMALL_STACK)
108286   WhereTerm aStatic[1];    /* Initial static space for a[] */
108287 #else
108288   WhereTerm aStatic[8];    /* Initial static space for a[] */
108289 #endif
108290 };
108291 
108292 /*
108293 ** A WhereTerm with eOperator==WO_OR has its u.pOrInfo pointer set to
108294 ** a dynamically allocated instance of the following structure.
108295 */
108296 struct WhereOrInfo {
108297   WhereClause wc;          /* Decomposition into subterms */
108298   Bitmask indexable;       /* Bitmask of all indexable tables in the clause */
108299 };
108300 
108301 /*
108302 ** A WhereTerm with eOperator==WO_AND has its u.pAndInfo pointer set to
108303 ** a dynamically allocated instance of the following structure.
108304 */
108305 struct WhereAndInfo {
108306   WhereClause wc;          /* The subexpression broken out */
108307 };
108308 
108309 /*
108310 ** An instance of the following structure keeps track of a mapping
108311 ** between VDBE cursor numbers and bits of the bitmasks in WhereTerm.
108312 **
108313 ** The VDBE cursor numbers are small integers contained in 
108314 ** SrcList_item.iCursor and Expr.iTable fields.  For any given WHERE 
108315 ** clause, the cursor numbers might not begin with 0 and they might
108316 ** contain gaps in the numbering sequence.  But we want to make maximum
108317 ** use of the bits in our bitmasks.  This structure provides a mapping
108318 ** from the sparse cursor numbers into consecutive integers beginning
108319 ** with 0.
108320 **
108321 ** If WhereMaskSet.ix[A]==B it means that The A-th bit of a Bitmask
108322 ** corresponds VDBE cursor number B.  The A-th bit of a bitmask is 1<<A.
108323 **
108324 ** For example, if the WHERE clause expression used these VDBE
108325 ** cursors:  4, 5, 8, 29, 57, 73.  Then the  WhereMaskSet structure
108326 ** would map those cursor numbers into bits 0 through 5.
108327 **
108328 ** Note that the mapping is not necessarily ordered.  In the example
108329 ** above, the mapping might go like this:  4->3, 5->1, 8->2, 29->0,
108330 ** 57->5, 73->4.  Or one of 719 other combinations might be used. It
108331 ** does not really matter.  What is important is that sparse cursor
108332 ** numbers all get mapped into bit numbers that begin with 0 and contain
108333 ** no gaps.
108334 */
108335 struct WhereMaskSet {
108336   int n;                        /* Number of assigned cursor values */
108337   int ix[BMS];                  /* Cursor assigned to each bit */
108338 };
108339 
108340 /*
108341 ** This object is a convenience wrapper holding all information needed
108342 ** to construct WhereLoop objects for a particular query.
108343 */
108344 struct WhereLoopBuilder {
108345   WhereInfo *pWInfo;        /* Information about this WHERE */
108346   WhereClause *pWC;         /* WHERE clause terms */
108347   ExprList *pOrderBy;       /* ORDER BY clause */
108348   WhereLoop *pNew;          /* Template WhereLoop */
108349   WhereOrSet *pOrSet;       /* Record best loops here, if not NULL */
108350 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
108351   UnpackedRecord *pRec;     /* Probe for stat4 (if required) */
108352   int nRecValid;            /* Number of valid fields currently in pRec */
108353 #endif
108354 };
108355 
108356 /*
108357 ** The WHERE clause processing routine has two halves.  The
108358 ** first part does the start of the WHERE loop and the second
108359 ** half does the tail of the WHERE loop.  An instance of
108360 ** this structure is returned by the first half and passed
108361 ** into the second half to give some continuity.
108362 **
108363 ** An instance of this object holds the complete state of the query
108364 ** planner.
108365 */
108366 struct WhereInfo {
108367   Parse *pParse;            /* Parsing and code generating context */
108368   SrcList *pTabList;        /* List of tables in the join */
108369   ExprList *pOrderBy;       /* The ORDER BY clause or NULL */
108370   ExprList *pResultSet;     /* Result set. DISTINCT operates on these */
108371   WhereLoop *pLoops;        /* List of all WhereLoop objects */
108372   Bitmask revMask;          /* Mask of ORDER BY terms that need reversing */
108373   LogEst nRowOut;           /* Estimated number of output rows */
108374   u16 wctrlFlags;           /* Flags originally passed to sqlite3WhereBegin() */
108375   u8 bOBSat;                /* ORDER BY satisfied by indices */
108376   u8 okOnePass;             /* Ok to use one-pass algorithm for UPDATE/DELETE */
108377   u8 untestedTerms;         /* Not all WHERE terms resolved by outer loop */
108378   u8 eDistinct;             /* One of the WHERE_DISTINCT_* values below */
108379   u8 nLevel;                /* Number of nested loop */
108380   int iTop;                 /* The very beginning of the WHERE loop */
108381   int iContinue;            /* Jump here to continue with next record */
108382   int iBreak;               /* Jump here to break out of the loop */
108383   int savedNQueryLoop;      /* pParse->nQueryLoop outside the WHERE loop */
108384   int aiCurOnePass[2];      /* OP_OpenWrite cursors for the ONEPASS opt */
108385   WhereMaskSet sMaskSet;    /* Map cursor numbers to bitmasks */
108386   WhereClause sWC;          /* Decomposition of the WHERE clause */
108387   WhereLevel a[1];          /* Information about each nest loop in WHERE */
108388 };
108389 
108390 /*
108391 ** Bitmasks for the operators on WhereTerm objects.  These are all
108392 ** operators that are of interest to the query planner.  An
108393 ** OR-ed combination of these values can be used when searching for
108394 ** particular WhereTerms within a WhereClause.
108395 */
108396 #define WO_IN     0x001
108397 #define WO_EQ     0x002
108398 #define WO_LT     (WO_EQ<<(TK_LT-TK_EQ))
108399 #define WO_LE     (WO_EQ<<(TK_LE-TK_EQ))
108400 #define WO_GT     (WO_EQ<<(TK_GT-TK_EQ))
108401 #define WO_GE     (WO_EQ<<(TK_GE-TK_EQ))
108402 #define WO_MATCH  0x040
108403 #define WO_ISNULL 0x080
108404 #define WO_OR     0x100       /* Two or more OR-connected terms */
108405 #define WO_AND    0x200       /* Two or more AND-connected terms */
108406 #define WO_EQUIV  0x400       /* Of the form A==B, both columns */
108407 #define WO_NOOP   0x800       /* This term does not restrict search space */
108408 
108409 #define WO_ALL    0xfff       /* Mask of all possible WO_* values */
108410 #define WO_SINGLE 0x0ff       /* Mask of all non-compound WO_* values */
108411 
108412 /*
108413 ** These are definitions of bits in the WhereLoop.wsFlags field.
108414 ** The particular combination of bits in each WhereLoop help to
108415 ** determine the algorithm that WhereLoop represents.
108416 */
108417 #define WHERE_COLUMN_EQ    0x00000001  /* x=EXPR */
108418 #define WHERE_COLUMN_RANGE 0x00000002  /* x<EXPR and/or x>EXPR */
108419 #define WHERE_COLUMN_IN    0x00000004  /* x IN (...) */
108420 #define WHERE_COLUMN_NULL  0x00000008  /* x IS NULL */
108421 #define WHERE_CONSTRAINT   0x0000000f  /* Any of the WHERE_COLUMN_xxx values */
108422 #define WHERE_TOP_LIMIT    0x00000010  /* x<EXPR or x<=EXPR constraint */
108423 #define WHERE_BTM_LIMIT    0x00000020  /* x>EXPR or x>=EXPR constraint */
108424 #define WHERE_BOTH_LIMIT   0x00000030  /* Both x>EXPR and x<EXPR */
108425 #define WHERE_IDX_ONLY     0x00000040  /* Use index only - omit table */
108426 #define WHERE_IPK          0x00000100  /* x is the INTEGER PRIMARY KEY */
108427 #define WHERE_INDEXED      0x00000200  /* WhereLoop.u.btree.pIndex is valid */
108428 #define WHERE_VIRTUALTABLE 0x00000400  /* WhereLoop.u.vtab is valid */
108429 #define WHERE_IN_ABLE      0x00000800  /* Able to support an IN operator */
108430 #define WHERE_ONEROW       0x00001000  /* Selects no more than one row */
108431 #define WHERE_MULTI_OR     0x00002000  /* OR using multiple indices */
108432 #define WHERE_AUTO_INDEX   0x00004000  /* Uses an ephemeral index */
108433 #define WHERE_SKIPSCAN     0x00008000  /* Uses the skip-scan algorithm */
108434 
108435 /************** End of whereInt.h ********************************************/
108436 /************** Continuing where we left off in where.c **********************/
108437 
108438 /*
108439 ** Return the estimated number of output rows from a WHERE clause
108440 */
108441 SQLITE_PRIVATE u64 sqlite3WhereOutputRowCount(WhereInfo *pWInfo){
108442   return sqlite3LogEstToInt(pWInfo->nRowOut);
108443 }
108444 
108445 /*
108446 ** Return one of the WHERE_DISTINCT_xxxxx values to indicate how this
108447 ** WHERE clause returns outputs for DISTINCT processing.
108448 */
108449 SQLITE_PRIVATE int sqlite3WhereIsDistinct(WhereInfo *pWInfo){
108450   return pWInfo->eDistinct;
108451 }
108452 
108453 /*
108454 ** Return TRUE if the WHERE clause returns rows in ORDER BY order.
108455 ** Return FALSE if the output needs to be sorted.
108456 */
108457 SQLITE_PRIVATE int sqlite3WhereIsOrdered(WhereInfo *pWInfo){
108458   return pWInfo->bOBSat!=0;
108459 }
108460 
108461 /*
108462 ** Return the VDBE address or label to jump to in order to continue
108463 ** immediately with the next row of a WHERE clause.
108464 */
108465 SQLITE_PRIVATE int sqlite3WhereContinueLabel(WhereInfo *pWInfo){
108466   return pWInfo->iContinue;
108467 }
108468 
108469 /*
108470 ** Return the VDBE address or label to jump to in order to break
108471 ** out of a WHERE loop.
108472 */
108473 SQLITE_PRIVATE int sqlite3WhereBreakLabel(WhereInfo *pWInfo){
108474   return pWInfo->iBreak;
108475 }
108476 
108477 /*
108478 ** Return TRUE if an UPDATE or DELETE statement can operate directly on
108479 ** the rowids returned by a WHERE clause.  Return FALSE if doing an
108480 ** UPDATE or DELETE might change subsequent WHERE clause results.
108481 **
108482 ** If the ONEPASS optimization is used (if this routine returns true)
108483 ** then also write the indices of open cursors used by ONEPASS
108484 ** into aiCur[0] and aiCur[1].  iaCur[0] gets the cursor of the data
108485 ** table and iaCur[1] gets the cursor used by an auxiliary index.
108486 ** Either value may be -1, indicating that cursor is not used.
108487 ** Any cursors returned will have been opened for writing.
108488 **
108489 ** aiCur[0] and aiCur[1] both get -1 if the where-clause logic is
108490 ** unable to use the ONEPASS optimization.
108491 */
108492 SQLITE_PRIVATE int sqlite3WhereOkOnePass(WhereInfo *pWInfo, int *aiCur){
108493   memcpy(aiCur, pWInfo->aiCurOnePass, sizeof(int)*2);
108494   return pWInfo->okOnePass;
108495 }
108496 
108497 /*
108498 ** Move the content of pSrc into pDest
108499 */
108500 static void whereOrMove(WhereOrSet *pDest, WhereOrSet *pSrc){
108501   pDest->n = pSrc->n;
108502   memcpy(pDest->a, pSrc->a, pDest->n*sizeof(pDest->a[0]));
108503 }
108504 
108505 /*
108506 ** Try to insert a new prerequisite/cost entry into the WhereOrSet pSet.
108507 **
108508 ** The new entry might overwrite an existing entry, or it might be
108509 ** appended, or it might be discarded.  Do whatever is the right thing
108510 ** so that pSet keeps the N_OR_COST best entries seen so far.
108511 */
108512 static int whereOrInsert(
108513   WhereOrSet *pSet,      /* The WhereOrSet to be updated */
108514   Bitmask prereq,        /* Prerequisites of the new entry */
108515   LogEst rRun,           /* Run-cost of the new entry */
108516   LogEst nOut            /* Number of outputs for the new entry */
108517 ){
108518   u16 i;
108519   WhereOrCost *p;
108520   for(i=pSet->n, p=pSet->a; i>0; i--, p++){
108521     if( rRun<=p->rRun && (prereq & p->prereq)==prereq ){
108522       goto whereOrInsert_done;
108523     }
108524     if( p->rRun<=rRun && (p->prereq & prereq)==p->prereq ){
108525       return 0;
108526     }
108527   }
108528   if( pSet->n<N_OR_COST ){
108529     p = &pSet->a[pSet->n++];
108530     p->nOut = nOut;
108531   }else{
108532     p = pSet->a;
108533     for(i=1; i<pSet->n; i++){
108534       if( p->rRun>pSet->a[i].rRun ) p = pSet->a + i;
108535     }
108536     if( p->rRun<=rRun ) return 0;
108537   }
108538 whereOrInsert_done:
108539   p->prereq = prereq;
108540   p->rRun = rRun;
108541   if( p->nOut>nOut ) p->nOut = nOut;
108542   return 1;
108543 }
108544 
108545 /*
108546 ** Initialize a preallocated WhereClause structure.
108547 */
108548 static void whereClauseInit(
108549   WhereClause *pWC,        /* The WhereClause to be initialized */
108550   WhereInfo *pWInfo        /* The WHERE processing context */
108551 ){
108552   pWC->pWInfo = pWInfo;
108553   pWC->pOuter = 0;
108554   pWC->nTerm = 0;
108555   pWC->nSlot = ArraySize(pWC->aStatic);
108556   pWC->a = pWC->aStatic;
108557 }
108558 
108559 /* Forward reference */
108560 static void whereClauseClear(WhereClause*);
108561 
108562 /*
108563 ** Deallocate all memory associated with a WhereOrInfo object.
108564 */
108565 static void whereOrInfoDelete(sqlite3 *db, WhereOrInfo *p){
108566   whereClauseClear(&p->wc);
108567   sqlite3DbFree(db, p);
108568 }
108569 
108570 /*
108571 ** Deallocate all memory associated with a WhereAndInfo object.
108572 */
108573 static void whereAndInfoDelete(sqlite3 *db, WhereAndInfo *p){
108574   whereClauseClear(&p->wc);
108575   sqlite3DbFree(db, p);
108576 }
108577 
108578 /*
108579 ** Deallocate a WhereClause structure.  The WhereClause structure
108580 ** itself is not freed.  This routine is the inverse of whereClauseInit().
108581 */
108582 static void whereClauseClear(WhereClause *pWC){
108583   int i;
108584   WhereTerm *a;
108585   sqlite3 *db = pWC->pWInfo->pParse->db;
108586   for(i=pWC->nTerm-1, a=pWC->a; i>=0; i--, a++){
108587     if( a->wtFlags & TERM_DYNAMIC ){
108588       sqlite3ExprDelete(db, a->pExpr);
108589     }
108590     if( a->wtFlags & TERM_ORINFO ){
108591       whereOrInfoDelete(db, a->u.pOrInfo);
108592     }else if( a->wtFlags & TERM_ANDINFO ){
108593       whereAndInfoDelete(db, a->u.pAndInfo);
108594     }
108595   }
108596   if( pWC->a!=pWC->aStatic ){
108597     sqlite3DbFree(db, pWC->a);
108598   }
108599 }
108600 
108601 /*
108602 ** Add a single new WhereTerm entry to the WhereClause object pWC.
108603 ** The new WhereTerm object is constructed from Expr p and with wtFlags.
108604 ** The index in pWC->a[] of the new WhereTerm is returned on success.
108605 ** 0 is returned if the new WhereTerm could not be added due to a memory
108606 ** allocation error.  The memory allocation failure will be recorded in
108607 ** the db->mallocFailed flag so that higher-level functions can detect it.
108608 **
108609 ** This routine will increase the size of the pWC->a[] array as necessary.
108610 **
108611 ** If the wtFlags argument includes TERM_DYNAMIC, then responsibility
108612 ** for freeing the expression p is assumed by the WhereClause object pWC.
108613 ** This is true even if this routine fails to allocate a new WhereTerm.
108614 **
108615 ** WARNING:  This routine might reallocate the space used to store
108616 ** WhereTerms.  All pointers to WhereTerms should be invalidated after
108617 ** calling this routine.  Such pointers may be reinitialized by referencing
108618 ** the pWC->a[] array.
108619 */
108620 static int whereClauseInsert(WhereClause *pWC, Expr *p, u8 wtFlags){
108621   WhereTerm *pTerm;
108622   int idx;
108623   testcase( wtFlags & TERM_VIRTUAL );
108624   if( pWC->nTerm>=pWC->nSlot ){
108625     WhereTerm *pOld = pWC->a;
108626     sqlite3 *db = pWC->pWInfo->pParse->db;
108627     pWC->a = sqlite3DbMallocRaw(db, sizeof(pWC->a[0])*pWC->nSlot*2 );
108628     if( pWC->a==0 ){
108629       if( wtFlags & TERM_DYNAMIC ){
108630         sqlite3ExprDelete(db, p);
108631       }
108632       pWC->a = pOld;
108633       return 0;
108634     }
108635     memcpy(pWC->a, pOld, sizeof(pWC->a[0])*pWC->nTerm);
108636     if( pOld!=pWC->aStatic ){
108637       sqlite3DbFree(db, pOld);
108638     }
108639     pWC->nSlot = sqlite3DbMallocSize(db, pWC->a)/sizeof(pWC->a[0]);
108640   }
108641   pTerm = &pWC->a[idx = pWC->nTerm++];
108642   if( p && ExprHasProperty(p, EP_Unlikely) ){
108643     pTerm->truthProb = sqlite3LogEst(p->iTable) - 99;
108644   }else{
108645     pTerm->truthProb = -1;
108646   }
108647   pTerm->pExpr = sqlite3ExprSkipCollate(p);
108648   pTerm->wtFlags = wtFlags;
108649   pTerm->pWC = pWC;
108650   pTerm->iParent = -1;
108651   return idx;
108652 }
108653 
108654 /*
108655 ** This routine identifies subexpressions in the WHERE clause where
108656 ** each subexpression is separated by the AND operator or some other
108657 ** operator specified in the op parameter.  The WhereClause structure
108658 ** is filled with pointers to subexpressions.  For example:
108659 **
108660 **    WHERE  a=='hello' AND coalesce(b,11)<10 AND (c+12!=d OR c==22)
108661 **           \________/     \_______________/     \________________/
108662 **            slot[0]            slot[1]               slot[2]
108663 **
108664 ** The original WHERE clause in pExpr is unaltered.  All this routine
108665 ** does is make slot[] entries point to substructure within pExpr.
108666 **
108667 ** In the previous sentence and in the diagram, "slot[]" refers to
108668 ** the WhereClause.a[] array.  The slot[] array grows as needed to contain
108669 ** all terms of the WHERE clause.
108670 */
108671 static void whereSplit(WhereClause *pWC, Expr *pExpr, u8 op){
108672   pWC->op = op;
108673   if( pExpr==0 ) return;
108674   if( pExpr->op!=op ){
108675     whereClauseInsert(pWC, pExpr, 0);
108676   }else{
108677     whereSplit(pWC, pExpr->pLeft, op);
108678     whereSplit(pWC, pExpr->pRight, op);
108679   }
108680 }
108681 
108682 /*
108683 ** Initialize a WhereMaskSet object
108684 */
108685 #define initMaskSet(P)  (P)->n=0
108686 
108687 /*
108688 ** Return the bitmask for the given cursor number.  Return 0 if
108689 ** iCursor is not in the set.
108690 */
108691 static Bitmask getMask(WhereMaskSet *pMaskSet, int iCursor){
108692   int i;
108693   assert( pMaskSet->n<=(int)sizeof(Bitmask)*8 );
108694   for(i=0; i<pMaskSet->n; i++){
108695     if( pMaskSet->ix[i]==iCursor ){
108696       return MASKBIT(i);
108697     }
108698   }
108699   return 0;
108700 }
108701 
108702 /*
108703 ** Create a new mask for cursor iCursor.
108704 **
108705 ** There is one cursor per table in the FROM clause.  The number of
108706 ** tables in the FROM clause is limited by a test early in the
108707 ** sqlite3WhereBegin() routine.  So we know that the pMaskSet->ix[]
108708 ** array will never overflow.
108709 */
108710 static void createMask(WhereMaskSet *pMaskSet, int iCursor){
108711   assert( pMaskSet->n < ArraySize(pMaskSet->ix) );
108712   pMaskSet->ix[pMaskSet->n++] = iCursor;
108713 }
108714 
108715 /*
108716 ** These routines walk (recursively) an expression tree and generate
108717 ** a bitmask indicating which tables are used in that expression
108718 ** tree.
108719 */
108720 static Bitmask exprListTableUsage(WhereMaskSet*, ExprList*);
108721 static Bitmask exprSelectTableUsage(WhereMaskSet*, Select*);
108722 static Bitmask exprTableUsage(WhereMaskSet *pMaskSet, Expr *p){
108723   Bitmask mask = 0;
108724   if( p==0 ) return 0;
108725   if( p->op==TK_COLUMN ){
108726     mask = getMask(pMaskSet, p->iTable);
108727     return mask;
108728   }
108729   mask = exprTableUsage(pMaskSet, p->pRight);
108730   mask |= exprTableUsage(pMaskSet, p->pLeft);
108731   if( ExprHasProperty(p, EP_xIsSelect) ){
108732     mask |= exprSelectTableUsage(pMaskSet, p->x.pSelect);
108733   }else{
108734     mask |= exprListTableUsage(pMaskSet, p->x.pList);
108735   }
108736   return mask;
108737 }
108738 static Bitmask exprListTableUsage(WhereMaskSet *pMaskSet, ExprList *pList){
108739   int i;
108740   Bitmask mask = 0;
108741   if( pList ){
108742     for(i=0; i<pList->nExpr; i++){
108743       mask |= exprTableUsage(pMaskSet, pList->a[i].pExpr);
108744     }
108745   }
108746   return mask;
108747 }
108748 static Bitmask exprSelectTableUsage(WhereMaskSet *pMaskSet, Select *pS){
108749   Bitmask mask = 0;
108750   while( pS ){
108751     SrcList *pSrc = pS->pSrc;
108752     mask |= exprListTableUsage(pMaskSet, pS->pEList);
108753     mask |= exprListTableUsage(pMaskSet, pS->pGroupBy);
108754     mask |= exprListTableUsage(pMaskSet, pS->pOrderBy);
108755     mask |= exprTableUsage(pMaskSet, pS->pWhere);
108756     mask |= exprTableUsage(pMaskSet, pS->pHaving);
108757     if( ALWAYS(pSrc!=0) ){
108758       int i;
108759       for(i=0; i<pSrc->nSrc; i++){
108760         mask |= exprSelectTableUsage(pMaskSet, pSrc->a[i].pSelect);
108761         mask |= exprTableUsage(pMaskSet, pSrc->a[i].pOn);
108762       }
108763     }
108764     pS = pS->pPrior;
108765   }
108766   return mask;
108767 }
108768 
108769 /*
108770 ** Return TRUE if the given operator is one of the operators that is
108771 ** allowed for an indexable WHERE clause term.  The allowed operators are
108772 ** "=", "<", ">", "<=", ">=", "IN", and "IS NULL"
108773 */
108774 static int allowedOp(int op){
108775   assert( TK_GT>TK_EQ && TK_GT<TK_GE );
108776   assert( TK_LT>TK_EQ && TK_LT<TK_GE );
108777   assert( TK_LE>TK_EQ && TK_LE<TK_GE );
108778   assert( TK_GE==TK_EQ+4 );
108779   return op==TK_IN || (op>=TK_EQ && op<=TK_GE) || op==TK_ISNULL;
108780 }
108781 
108782 /*
108783 ** Swap two objects of type TYPE.
108784 */
108785 #define SWAP(TYPE,A,B) {TYPE t=A; A=B; B=t;}
108786 
108787 /*
108788 ** Commute a comparison operator.  Expressions of the form "X op Y"
108789 ** are converted into "Y op X".
108790 **
108791 ** If left/right precedence rules come into play when determining the
108792 ** collating sequence, then COLLATE operators are adjusted to ensure
108793 ** that the collating sequence does not change.  For example:
108794 ** "Y collate NOCASE op X" becomes "X op Y" because any collation sequence on
108795 ** the left hand side of a comparison overrides any collation sequence 
108796 ** attached to the right. For the same reason the EP_Collate flag
108797 ** is not commuted.
108798 */
108799 static void exprCommute(Parse *pParse, Expr *pExpr){
108800   u16 expRight = (pExpr->pRight->flags & EP_Collate);
108801   u16 expLeft = (pExpr->pLeft->flags & EP_Collate);
108802   assert( allowedOp(pExpr->op) && pExpr->op!=TK_IN );
108803   if( expRight==expLeft ){
108804     /* Either X and Y both have COLLATE operator or neither do */
108805     if( expRight ){
108806       /* Both X and Y have COLLATE operators.  Make sure X is always
108807       ** used by clearing the EP_Collate flag from Y. */
108808       pExpr->pRight->flags &= ~EP_Collate;
108809     }else if( sqlite3ExprCollSeq(pParse, pExpr->pLeft)!=0 ){
108810       /* Neither X nor Y have COLLATE operators, but X has a non-default
108811       ** collating sequence.  So add the EP_Collate marker on X to cause
108812       ** it to be searched first. */
108813       pExpr->pLeft->flags |= EP_Collate;
108814     }
108815   }
108816   SWAP(Expr*,pExpr->pRight,pExpr->pLeft);
108817   if( pExpr->op>=TK_GT ){
108818     assert( TK_LT==TK_GT+2 );
108819     assert( TK_GE==TK_LE+2 );
108820     assert( TK_GT>TK_EQ );
108821     assert( TK_GT<TK_LE );
108822     assert( pExpr->op>=TK_GT && pExpr->op<=TK_GE );
108823     pExpr->op = ((pExpr->op-TK_GT)^2)+TK_GT;
108824   }
108825 }
108826 
108827 /*
108828 ** Translate from TK_xx operator to WO_xx bitmask.
108829 */
108830 static u16 operatorMask(int op){
108831   u16 c;
108832   assert( allowedOp(op) );
108833   if( op==TK_IN ){
108834     c = WO_IN;
108835   }else if( op==TK_ISNULL ){
108836     c = WO_ISNULL;
108837   }else{
108838     assert( (WO_EQ<<(op-TK_EQ)) < 0x7fff );
108839     c = (u16)(WO_EQ<<(op-TK_EQ));
108840   }
108841   assert( op!=TK_ISNULL || c==WO_ISNULL );
108842   assert( op!=TK_IN || c==WO_IN );
108843   assert( op!=TK_EQ || c==WO_EQ );
108844   assert( op!=TK_LT || c==WO_LT );
108845   assert( op!=TK_LE || c==WO_LE );
108846   assert( op!=TK_GT || c==WO_GT );
108847   assert( op!=TK_GE || c==WO_GE );
108848   return c;
108849 }
108850 
108851 /*
108852 ** Advance to the next WhereTerm that matches according to the criteria
108853 ** established when the pScan object was initialized by whereScanInit().
108854 ** Return NULL if there are no more matching WhereTerms.
108855 */
108856 static WhereTerm *whereScanNext(WhereScan *pScan){
108857   int iCur;            /* The cursor on the LHS of the term */
108858   int iColumn;         /* The column on the LHS of the term.  -1 for IPK */
108859   Expr *pX;            /* An expression being tested */
108860   WhereClause *pWC;    /* Shorthand for pScan->pWC */
108861   WhereTerm *pTerm;    /* The term being tested */
108862   int k = pScan->k;    /* Where to start scanning */
108863 
108864   while( pScan->iEquiv<=pScan->nEquiv ){
108865     iCur = pScan->aEquiv[pScan->iEquiv-2];
108866     iColumn = pScan->aEquiv[pScan->iEquiv-1];
108867     while( (pWC = pScan->pWC)!=0 ){
108868       for(pTerm=pWC->a+k; k<pWC->nTerm; k++, pTerm++){
108869         if( pTerm->leftCursor==iCur
108870          && pTerm->u.leftColumn==iColumn
108871          && (pScan->iEquiv<=2 || !ExprHasProperty(pTerm->pExpr, EP_FromJoin))
108872         ){
108873           if( (pTerm->eOperator & WO_EQUIV)!=0
108874            && pScan->nEquiv<ArraySize(pScan->aEquiv)
108875           ){
108876             int j;
108877             pX = sqlite3ExprSkipCollate(pTerm->pExpr->pRight);
108878             assert( pX->op==TK_COLUMN );
108879             for(j=0; j<pScan->nEquiv; j+=2){
108880               if( pScan->aEquiv[j]==pX->iTable
108881                && pScan->aEquiv[j+1]==pX->iColumn ){
108882                   break;
108883               }
108884             }
108885             if( j==pScan->nEquiv ){
108886               pScan->aEquiv[j] = pX->iTable;
108887               pScan->aEquiv[j+1] = pX->iColumn;
108888               pScan->nEquiv += 2;
108889             }
108890           }
108891           if( (pTerm->eOperator & pScan->opMask)!=0 ){
108892             /* Verify the affinity and collating sequence match */
108893             if( pScan->zCollName && (pTerm->eOperator & WO_ISNULL)==0 ){
108894               CollSeq *pColl;
108895               Parse *pParse = pWC->pWInfo->pParse;
108896               pX = pTerm->pExpr;
108897               if( !sqlite3IndexAffinityOk(pX, pScan->idxaff) ){
108898                 continue;
108899               }
108900               assert(pX->pLeft);
108901               pColl = sqlite3BinaryCompareCollSeq(pParse,
108902                                                   pX->pLeft, pX->pRight);
108903               if( pColl==0 ) pColl = pParse->db->pDfltColl;
108904               if( sqlite3StrICmp(pColl->zName, pScan->zCollName) ){
108905                 continue;
108906               }
108907             }
108908             if( (pTerm->eOperator & WO_EQ)!=0
108909              && (pX = pTerm->pExpr->pRight)->op==TK_COLUMN
108910              && pX->iTable==pScan->aEquiv[0]
108911              && pX->iColumn==pScan->aEquiv[1]
108912             ){
108913               continue;
108914             }
108915             pScan->k = k+1;
108916             return pTerm;
108917           }
108918         }
108919       }
108920       pScan->pWC = pScan->pWC->pOuter;
108921       k = 0;
108922     }
108923     pScan->pWC = pScan->pOrigWC;
108924     k = 0;
108925     pScan->iEquiv += 2;
108926   }
108927   return 0;
108928 }
108929 
108930 /*
108931 ** Initialize a WHERE clause scanner object.  Return a pointer to the
108932 ** first match.  Return NULL if there are no matches.
108933 **
108934 ** The scanner will be searching the WHERE clause pWC.  It will look
108935 ** for terms of the form "X <op> <expr>" where X is column iColumn of table
108936 ** iCur.  The <op> must be one of the operators described by opMask.
108937 **
108938 ** If the search is for X and the WHERE clause contains terms of the
108939 ** form X=Y then this routine might also return terms of the form
108940 ** "Y <op> <expr>".  The number of levels of transitivity is limited,
108941 ** but is enough to handle most commonly occurring SQL statements.
108942 **
108943 ** If X is not the INTEGER PRIMARY KEY then X must be compatible with
108944 ** index pIdx.
108945 */
108946 static WhereTerm *whereScanInit(
108947   WhereScan *pScan,       /* The WhereScan object being initialized */
108948   WhereClause *pWC,       /* The WHERE clause to be scanned */
108949   int iCur,               /* Cursor to scan for */
108950   int iColumn,            /* Column to scan for */
108951   u32 opMask,             /* Operator(s) to scan for */
108952   Index *pIdx             /* Must be compatible with this index */
108953 ){
108954   int j;
108955 
108956   /* memset(pScan, 0, sizeof(*pScan)); */
108957   pScan->pOrigWC = pWC;
108958   pScan->pWC = pWC;
108959   if( pIdx && iColumn>=0 ){
108960     pScan->idxaff = pIdx->pTable->aCol[iColumn].affinity;
108961     for(j=0; pIdx->aiColumn[j]!=iColumn; j++){
108962       if( NEVER(j>=pIdx->nKeyCol) ) return 0;
108963     }
108964     pScan->zCollName = pIdx->azColl[j];
108965   }else{
108966     pScan->idxaff = 0;
108967     pScan->zCollName = 0;
108968   }
108969   pScan->opMask = opMask;
108970   pScan->k = 0;
108971   pScan->aEquiv[0] = iCur;
108972   pScan->aEquiv[1] = iColumn;
108973   pScan->nEquiv = 2;
108974   pScan->iEquiv = 2;
108975   return whereScanNext(pScan);
108976 }
108977 
108978 /*
108979 ** Search for a term in the WHERE clause that is of the form "X <op> <expr>"
108980 ** where X is a reference to the iColumn of table iCur and <op> is one of
108981 ** the WO_xx operator codes specified by the op parameter.
108982 ** Return a pointer to the term.  Return 0 if not found.
108983 **
108984 ** The term returned might by Y=<expr> if there is another constraint in
108985 ** the WHERE clause that specifies that X=Y.  Any such constraints will be
108986 ** identified by the WO_EQUIV bit in the pTerm->eOperator field.  The
108987 ** aEquiv[] array holds X and all its equivalents, with each SQL variable
108988 ** taking up two slots in aEquiv[].  The first slot is for the cursor number
108989 ** and the second is for the column number.  There are 22 slots in aEquiv[]
108990 ** so that means we can look for X plus up to 10 other equivalent values.
108991 ** Hence a search for X will return <expr> if X=A1 and A1=A2 and A2=A3
108992 ** and ... and A9=A10 and A10=<expr>.
108993 **
108994 ** If there are multiple terms in the WHERE clause of the form "X <op> <expr>"
108995 ** then try for the one with no dependencies on <expr> - in other words where
108996 ** <expr> is a constant expression of some kind.  Only return entries of
108997 ** the form "X <op> Y" where Y is a column in another table if no terms of
108998 ** the form "X <op> <const-expr>" exist.   If no terms with a constant RHS
108999 ** exist, try to return a term that does not use WO_EQUIV.
109000 */
109001 static WhereTerm *findTerm(
109002   WhereClause *pWC,     /* The WHERE clause to be searched */
109003   int iCur,             /* Cursor number of LHS */
109004   int iColumn,          /* Column number of LHS */
109005   Bitmask notReady,     /* RHS must not overlap with this mask */
109006   u32 op,               /* Mask of WO_xx values describing operator */
109007   Index *pIdx           /* Must be compatible with this index, if not NULL */
109008 ){
109009   WhereTerm *pResult = 0;
109010   WhereTerm *p;
109011   WhereScan scan;
109012 
109013   p = whereScanInit(&scan, pWC, iCur, iColumn, op, pIdx);
109014   while( p ){
109015     if( (p->prereqRight & notReady)==0 ){
109016       if( p->prereqRight==0 && (p->eOperator&WO_EQ)!=0 ){
109017         return p;
109018       }
109019       if( pResult==0 ) pResult = p;
109020     }
109021     p = whereScanNext(&scan);
109022   }
109023   return pResult;
109024 }
109025 
109026 /* Forward reference */
109027 static void exprAnalyze(SrcList*, WhereClause*, int);
109028 
109029 /*
109030 ** Call exprAnalyze on all terms in a WHERE clause.  
109031 */
109032 static void exprAnalyzeAll(
109033   SrcList *pTabList,       /* the FROM clause */
109034   WhereClause *pWC         /* the WHERE clause to be analyzed */
109035 ){
109036   int i;
109037   for(i=pWC->nTerm-1; i>=0; i--){
109038     exprAnalyze(pTabList, pWC, i);
109039   }
109040 }
109041 
109042 #ifndef SQLITE_OMIT_LIKE_OPTIMIZATION
109043 /*
109044 ** Check to see if the given expression is a LIKE or GLOB operator that
109045 ** can be optimized using inequality constraints.  Return TRUE if it is
109046 ** so and false if not.
109047 **
109048 ** In order for the operator to be optimizible, the RHS must be a string
109049 ** literal that does not begin with a wildcard.  
109050 */
109051 static int isLikeOrGlob(
109052   Parse *pParse,    /* Parsing and code generating context */
109053   Expr *pExpr,      /* Test this expression */
109054   Expr **ppPrefix,  /* Pointer to TK_STRING expression with pattern prefix */
109055   int *pisComplete, /* True if the only wildcard is % in the last character */
109056   int *pnoCase      /* True if uppercase is equivalent to lowercase */
109057 ){
109058   const char *z = 0;         /* String on RHS of LIKE operator */
109059   Expr *pRight, *pLeft;      /* Right and left size of LIKE operator */
109060   ExprList *pList;           /* List of operands to the LIKE operator */
109061   int c;                     /* One character in z[] */
109062   int cnt;                   /* Number of non-wildcard prefix characters */
109063   char wc[3];                /* Wildcard characters */
109064   sqlite3 *db = pParse->db;  /* Database connection */
109065   sqlite3_value *pVal = 0;
109066   int op;                    /* Opcode of pRight */
109067 
109068   if( !sqlite3IsLikeFunction(db, pExpr, pnoCase, wc) ){
109069     return 0;
109070   }
109071 #ifdef SQLITE_EBCDIC
109072   if( *pnoCase ) return 0;
109073 #endif
109074   pList = pExpr->x.pList;
109075   pLeft = pList->a[1].pExpr;
109076   if( pLeft->op!=TK_COLUMN 
109077    || sqlite3ExprAffinity(pLeft)!=SQLITE_AFF_TEXT 
109078    || IsVirtual(pLeft->pTab)
109079   ){
109080     /* IMP: R-02065-49465 The left-hand side of the LIKE or GLOB operator must
109081     ** be the name of an indexed column with TEXT affinity. */
109082     return 0;
109083   }
109084   assert( pLeft->iColumn!=(-1) ); /* Because IPK never has AFF_TEXT */
109085 
109086   pRight = pList->a[0].pExpr;
109087   op = pRight->op;
109088   if( op==TK_VARIABLE ){
109089     Vdbe *pReprepare = pParse->pReprepare;
109090     int iCol = pRight->iColumn;
109091     pVal = sqlite3VdbeGetBoundValue(pReprepare, iCol, SQLITE_AFF_NONE);
109092     if( pVal && sqlite3_value_type(pVal)==SQLITE_TEXT ){
109093       z = (char *)sqlite3_value_text(pVal);
109094     }
109095     sqlite3VdbeSetVarmask(pParse->pVdbe, iCol);
109096     assert( pRight->op==TK_VARIABLE || pRight->op==TK_REGISTER );
109097   }else if( op==TK_STRING ){
109098     z = pRight->u.zToken;
109099   }
109100   if( z ){
109101     cnt = 0;
109102     while( (c=z[cnt])!=0 && c!=wc[0] && c!=wc[1] && c!=wc[2] ){
109103       cnt++;
109104     }
109105     if( cnt!=0 && 255!=(u8)z[cnt-1] ){
109106       Expr *pPrefix;
109107       *pisComplete = c==wc[0] && z[cnt+1]==0;
109108       pPrefix = sqlite3Expr(db, TK_STRING, z);
109109       if( pPrefix ) pPrefix->u.zToken[cnt] = 0;
109110       *ppPrefix = pPrefix;
109111       if( op==TK_VARIABLE ){
109112         Vdbe *v = pParse->pVdbe;
109113         sqlite3VdbeSetVarmask(v, pRight->iColumn);
109114         if( *pisComplete && pRight->u.zToken[1] ){
109115           /* If the rhs of the LIKE expression is a variable, and the current
109116           ** value of the variable means there is no need to invoke the LIKE
109117           ** function, then no OP_Variable will be added to the program.
109118           ** This causes problems for the sqlite3_bind_parameter_name()
109119           ** API. To workaround them, add a dummy OP_Variable here.
109120           */ 
109121           int r1 = sqlite3GetTempReg(pParse);
109122           sqlite3ExprCodeTarget(pParse, pRight, r1);
109123           sqlite3VdbeChangeP3(v, sqlite3VdbeCurrentAddr(v)-1, 0);
109124           sqlite3ReleaseTempReg(pParse, r1);
109125         }
109126       }
109127     }else{
109128       z = 0;
109129     }
109130   }
109131 
109132   sqlite3ValueFree(pVal);
109133   return (z!=0);
109134 }
109135 #endif /* SQLITE_OMIT_LIKE_OPTIMIZATION */
109136 
109137 
109138 #ifndef SQLITE_OMIT_VIRTUALTABLE
109139 /*
109140 ** Check to see if the given expression is of the form
109141 **
109142 **         column MATCH expr
109143 **
109144 ** If it is then return TRUE.  If not, return FALSE.
109145 */
109146 static int isMatchOfColumn(
109147   Expr *pExpr      /* Test this expression */
109148 ){
109149   ExprList *pList;
109150 
109151   if( pExpr->op!=TK_FUNCTION ){
109152     return 0;
109153   }
109154   if( sqlite3StrICmp(pExpr->u.zToken,"match")!=0 ){
109155     return 0;
109156   }
109157   pList = pExpr->x.pList;
109158   if( pList->nExpr!=2 ){
109159     return 0;
109160   }
109161   if( pList->a[1].pExpr->op != TK_COLUMN ){
109162     return 0;
109163   }
109164   return 1;
109165 }
109166 #endif /* SQLITE_OMIT_VIRTUALTABLE */
109167 
109168 /*
109169 ** If the pBase expression originated in the ON or USING clause of
109170 ** a join, then transfer the appropriate markings over to derived.
109171 */
109172 static void transferJoinMarkings(Expr *pDerived, Expr *pBase){
109173   if( pDerived ){
109174     pDerived->flags |= pBase->flags & EP_FromJoin;
109175     pDerived->iRightJoinTable = pBase->iRightJoinTable;
109176   }
109177 }
109178 
109179 #if !defined(SQLITE_OMIT_OR_OPTIMIZATION) && !defined(SQLITE_OMIT_SUBQUERY)
109180 /*
109181 ** Analyze a term that consists of two or more OR-connected
109182 ** subterms.  So in:
109183 **
109184 **     ... WHERE  (a=5) AND (b=7 OR c=9 OR d=13) AND (d=13)
109185 **                          ^^^^^^^^^^^^^^^^^^^^
109186 **
109187 ** This routine analyzes terms such as the middle term in the above example.
109188 ** A WhereOrTerm object is computed and attached to the term under
109189 ** analysis, regardless of the outcome of the analysis.  Hence:
109190 **
109191 **     WhereTerm.wtFlags   |=  TERM_ORINFO
109192 **     WhereTerm.u.pOrInfo  =  a dynamically allocated WhereOrTerm object
109193 **
109194 ** The term being analyzed must have two or more of OR-connected subterms.
109195 ** A single subterm might be a set of AND-connected sub-subterms.
109196 ** Examples of terms under analysis:
109197 **
109198 **     (A)     t1.x=t2.y OR t1.x=t2.z OR t1.y=15 OR t1.z=t3.a+5
109199 **     (B)     x=expr1 OR expr2=x OR x=expr3
109200 **     (C)     t1.x=t2.y OR (t1.x=t2.z AND t1.y=15)
109201 **     (D)     x=expr1 OR (y>11 AND y<22 AND z LIKE '*hello*')
109202 **     (E)     (p.a=1 AND q.b=2 AND r.c=3) OR (p.x=4 AND q.y=5 AND r.z=6)
109203 **
109204 ** CASE 1:
109205 **
109206 ** If all subterms are of the form T.C=expr for some single column of C and
109207 ** a single table T (as shown in example B above) then create a new virtual
109208 ** term that is an equivalent IN expression.  In other words, if the term
109209 ** being analyzed is:
109210 **
109211 **      x = expr1  OR  expr2 = x  OR  x = expr3
109212 **
109213 ** then create a new virtual term like this:
109214 **
109215 **      x IN (expr1,expr2,expr3)
109216 **
109217 ** CASE 2:
109218 **
109219 ** If all subterms are indexable by a single table T, then set
109220 **
109221 **     WhereTerm.eOperator              =  WO_OR
109222 **     WhereTerm.u.pOrInfo->indexable  |=  the cursor number for table T
109223 **
109224 ** A subterm is "indexable" if it is of the form
109225 ** "T.C <op> <expr>" where C is any column of table T and 
109226 ** <op> is one of "=", "<", "<=", ">", ">=", "IS NULL", or "IN".
109227 ** A subterm is also indexable if it is an AND of two or more
109228 ** subsubterms at least one of which is indexable.  Indexable AND 
109229 ** subterms have their eOperator set to WO_AND and they have
109230 ** u.pAndInfo set to a dynamically allocated WhereAndTerm object.
109231 **
109232 ** From another point of view, "indexable" means that the subterm could
109233 ** potentially be used with an index if an appropriate index exists.
109234 ** This analysis does not consider whether or not the index exists; that
109235 ** is decided elsewhere.  This analysis only looks at whether subterms
109236 ** appropriate for indexing exist.
109237 **
109238 ** All examples A through E above satisfy case 2.  But if a term
109239 ** also statisfies case 1 (such as B) we know that the optimizer will
109240 ** always prefer case 1, so in that case we pretend that case 2 is not
109241 ** satisfied.
109242 **
109243 ** It might be the case that multiple tables are indexable.  For example,
109244 ** (E) above is indexable on tables P, Q, and R.
109245 **
109246 ** Terms that satisfy case 2 are candidates for lookup by using
109247 ** separate indices to find rowids for each subterm and composing
109248 ** the union of all rowids using a RowSet object.  This is similar
109249 ** to "bitmap indices" in other database engines.
109250 **
109251 ** OTHERWISE:
109252 **
109253 ** If neither case 1 nor case 2 apply, then leave the eOperator set to
109254 ** zero.  This term is not useful for search.
109255 */
109256 static void exprAnalyzeOrTerm(
109257   SrcList *pSrc,            /* the FROM clause */
109258   WhereClause *pWC,         /* the complete WHERE clause */
109259   int idxTerm               /* Index of the OR-term to be analyzed */
109260 ){
109261   WhereInfo *pWInfo = pWC->pWInfo;        /* WHERE clause processing context */
109262   Parse *pParse = pWInfo->pParse;         /* Parser context */
109263   sqlite3 *db = pParse->db;               /* Database connection */
109264   WhereTerm *pTerm = &pWC->a[idxTerm];    /* The term to be analyzed */
109265   Expr *pExpr = pTerm->pExpr;             /* The expression of the term */
109266   int i;                                  /* Loop counters */
109267   WhereClause *pOrWc;       /* Breakup of pTerm into subterms */
109268   WhereTerm *pOrTerm;       /* A Sub-term within the pOrWc */
109269   WhereOrInfo *pOrInfo;     /* Additional information associated with pTerm */
109270   Bitmask chngToIN;         /* Tables that might satisfy case 1 */
109271   Bitmask indexable;        /* Tables that are indexable, satisfying case 2 */
109272 
109273   /*
109274   ** Break the OR clause into its separate subterms.  The subterms are
109275   ** stored in a WhereClause structure containing within the WhereOrInfo
109276   ** object that is attached to the original OR clause term.
109277   */
109278   assert( (pTerm->wtFlags & (TERM_DYNAMIC|TERM_ORINFO|TERM_ANDINFO))==0 );
109279   assert( pExpr->op==TK_OR );
109280   pTerm->u.pOrInfo = pOrInfo = sqlite3DbMallocZero(db, sizeof(*pOrInfo));
109281   if( pOrInfo==0 ) return;
109282   pTerm->wtFlags |= TERM_ORINFO;
109283   pOrWc = &pOrInfo->wc;
109284   whereClauseInit(pOrWc, pWInfo);
109285   whereSplit(pOrWc, pExpr, TK_OR);
109286   exprAnalyzeAll(pSrc, pOrWc);
109287   if( db->mallocFailed ) return;
109288   assert( pOrWc->nTerm>=2 );
109289 
109290   /*
109291   ** Compute the set of tables that might satisfy cases 1 or 2.
109292   */
109293   indexable = ~(Bitmask)0;
109294   chngToIN = ~(Bitmask)0;
109295   for(i=pOrWc->nTerm-1, pOrTerm=pOrWc->a; i>=0 && indexable; i--, pOrTerm++){
109296     if( (pOrTerm->eOperator & WO_SINGLE)==0 ){
109297       WhereAndInfo *pAndInfo;
109298       assert( (pOrTerm->wtFlags & (TERM_ANDINFO|TERM_ORINFO))==0 );
109299       chngToIN = 0;
109300       pAndInfo = sqlite3DbMallocRaw(db, sizeof(*pAndInfo));
109301       if( pAndInfo ){
109302         WhereClause *pAndWC;
109303         WhereTerm *pAndTerm;
109304         int j;
109305         Bitmask b = 0;
109306         pOrTerm->u.pAndInfo = pAndInfo;
109307         pOrTerm->wtFlags |= TERM_ANDINFO;
109308         pOrTerm->eOperator = WO_AND;
109309         pAndWC = &pAndInfo->wc;
109310         whereClauseInit(pAndWC, pWC->pWInfo);
109311         whereSplit(pAndWC, pOrTerm->pExpr, TK_AND);
109312         exprAnalyzeAll(pSrc, pAndWC);
109313         pAndWC->pOuter = pWC;
109314         testcase( db->mallocFailed );
109315         if( !db->mallocFailed ){
109316           for(j=0, pAndTerm=pAndWC->a; j<pAndWC->nTerm; j++, pAndTerm++){
109317             assert( pAndTerm->pExpr );
109318             if( allowedOp(pAndTerm->pExpr->op) ){
109319               b |= getMask(&pWInfo->sMaskSet, pAndTerm->leftCursor);
109320             }
109321           }
109322         }
109323         indexable &= b;
109324       }
109325     }else if( pOrTerm->wtFlags & TERM_COPIED ){
109326       /* Skip this term for now.  We revisit it when we process the
109327       ** corresponding TERM_VIRTUAL term */
109328     }else{
109329       Bitmask b;
109330       b = getMask(&pWInfo->sMaskSet, pOrTerm->leftCursor);
109331       if( pOrTerm->wtFlags & TERM_VIRTUAL ){
109332         WhereTerm *pOther = &pOrWc->a[pOrTerm->iParent];
109333         b |= getMask(&pWInfo->sMaskSet, pOther->leftCursor);
109334       }
109335       indexable &= b;
109336       if( (pOrTerm->eOperator & WO_EQ)==0 ){
109337         chngToIN = 0;
109338       }else{
109339         chngToIN &= b;
109340       }
109341     }
109342   }
109343 
109344   /*
109345   ** Record the set of tables that satisfy case 2.  The set might be
109346   ** empty.
109347   */
109348   pOrInfo->indexable = indexable;
109349   pTerm->eOperator = indexable==0 ? 0 : WO_OR;
109350 
109351   /*
109352   ** chngToIN holds a set of tables that *might* satisfy case 1.  But
109353   ** we have to do some additional checking to see if case 1 really
109354   ** is satisfied.
109355   **
109356   ** chngToIN will hold either 0, 1, or 2 bits.  The 0-bit case means
109357   ** that there is no possibility of transforming the OR clause into an
109358   ** IN operator because one or more terms in the OR clause contain
109359   ** something other than == on a column in the single table.  The 1-bit
109360   ** case means that every term of the OR clause is of the form
109361   ** "table.column=expr" for some single table.  The one bit that is set
109362   ** will correspond to the common table.  We still need to check to make
109363   ** sure the same column is used on all terms.  The 2-bit case is when
109364   ** the all terms are of the form "table1.column=table2.column".  It
109365   ** might be possible to form an IN operator with either table1.column
109366   ** or table2.column as the LHS if either is common to every term of
109367   ** the OR clause.
109368   **
109369   ** Note that terms of the form "table.column1=table.column2" (the
109370   ** same table on both sizes of the ==) cannot be optimized.
109371   */
109372   if( chngToIN ){
109373     int okToChngToIN = 0;     /* True if the conversion to IN is valid */
109374     int iColumn = -1;         /* Column index on lhs of IN operator */
109375     int iCursor = -1;         /* Table cursor common to all terms */
109376     int j = 0;                /* Loop counter */
109377 
109378     /* Search for a table and column that appears on one side or the
109379     ** other of the == operator in every subterm.  That table and column
109380     ** will be recorded in iCursor and iColumn.  There might not be any
109381     ** such table and column.  Set okToChngToIN if an appropriate table
109382     ** and column is found but leave okToChngToIN false if not found.
109383     */
109384     for(j=0; j<2 && !okToChngToIN; j++){
109385       pOrTerm = pOrWc->a;
109386       for(i=pOrWc->nTerm-1; i>=0; i--, pOrTerm++){
109387         assert( pOrTerm->eOperator & WO_EQ );
109388         pOrTerm->wtFlags &= ~TERM_OR_OK;
109389         if( pOrTerm->leftCursor==iCursor ){
109390           /* This is the 2-bit case and we are on the second iteration and
109391           ** current term is from the first iteration.  So skip this term. */
109392           assert( j==1 );
109393           continue;
109394         }
109395         if( (chngToIN & getMask(&pWInfo->sMaskSet, pOrTerm->leftCursor))==0 ){
109396           /* This term must be of the form t1.a==t2.b where t2 is in the
109397           ** chngToIN set but t1 is not.  This term will be either preceeded
109398           ** or follwed by an inverted copy (t2.b==t1.a).  Skip this term 
109399           ** and use its inversion. */
109400           testcase( pOrTerm->wtFlags & TERM_COPIED );
109401           testcase( pOrTerm->wtFlags & TERM_VIRTUAL );
109402           assert( pOrTerm->wtFlags & (TERM_COPIED|TERM_VIRTUAL) );
109403           continue;
109404         }
109405         iColumn = pOrTerm->u.leftColumn;
109406         iCursor = pOrTerm->leftCursor;
109407         break;
109408       }
109409       if( i<0 ){
109410         /* No candidate table+column was found.  This can only occur
109411         ** on the second iteration */
109412         assert( j==1 );
109413         assert( IsPowerOfTwo(chngToIN) );
109414         assert( chngToIN==getMask(&pWInfo->sMaskSet, iCursor) );
109415         break;
109416       }
109417       testcase( j==1 );
109418 
109419       /* We have found a candidate table and column.  Check to see if that
109420       ** table and column is common to every term in the OR clause */
109421       okToChngToIN = 1;
109422       for(; i>=0 && okToChngToIN; i--, pOrTerm++){
109423         assert( pOrTerm->eOperator & WO_EQ );
109424         if( pOrTerm->leftCursor!=iCursor ){
109425           pOrTerm->wtFlags &= ~TERM_OR_OK;
109426         }else if( pOrTerm->u.leftColumn!=iColumn ){
109427           okToChngToIN = 0;
109428         }else{
109429           int affLeft, affRight;
109430           /* If the right-hand side is also a column, then the affinities
109431           ** of both right and left sides must be such that no type
109432           ** conversions are required on the right.  (Ticket #2249)
109433           */
109434           affRight = sqlite3ExprAffinity(pOrTerm->pExpr->pRight);
109435           affLeft = sqlite3ExprAffinity(pOrTerm->pExpr->pLeft);
109436           if( affRight!=0 && affRight!=affLeft ){
109437             okToChngToIN = 0;
109438           }else{
109439             pOrTerm->wtFlags |= TERM_OR_OK;
109440           }
109441         }
109442       }
109443     }
109444 
109445     /* At this point, okToChngToIN is true if original pTerm satisfies
109446     ** case 1.  In that case, construct a new virtual term that is 
109447     ** pTerm converted into an IN operator.
109448     */
109449     if( okToChngToIN ){
109450       Expr *pDup;            /* A transient duplicate expression */
109451       ExprList *pList = 0;   /* The RHS of the IN operator */
109452       Expr *pLeft = 0;       /* The LHS of the IN operator */
109453       Expr *pNew;            /* The complete IN operator */
109454 
109455       for(i=pOrWc->nTerm-1, pOrTerm=pOrWc->a; i>=0; i--, pOrTerm++){
109456         if( (pOrTerm->wtFlags & TERM_OR_OK)==0 ) continue;
109457         assert( pOrTerm->eOperator & WO_EQ );
109458         assert( pOrTerm->leftCursor==iCursor );
109459         assert( pOrTerm->u.leftColumn==iColumn );
109460         pDup = sqlite3ExprDup(db, pOrTerm->pExpr->pRight, 0);
109461         pList = sqlite3ExprListAppend(pWInfo->pParse, pList, pDup);
109462         pLeft = pOrTerm->pExpr->pLeft;
109463       }
109464       assert( pLeft!=0 );
109465       pDup = sqlite3ExprDup(db, pLeft, 0);
109466       pNew = sqlite3PExpr(pParse, TK_IN, pDup, 0, 0);
109467       if( pNew ){
109468         int idxNew;
109469         transferJoinMarkings(pNew, pExpr);
109470         assert( !ExprHasProperty(pNew, EP_xIsSelect) );
109471         pNew->x.pList = pList;
109472         idxNew = whereClauseInsert(pWC, pNew, TERM_VIRTUAL|TERM_DYNAMIC);
109473         testcase( idxNew==0 );
109474         exprAnalyze(pSrc, pWC, idxNew);
109475         pTerm = &pWC->a[idxTerm];
109476         pWC->a[idxNew].iParent = idxTerm;
109477         pTerm->nChild = 1;
109478       }else{
109479         sqlite3ExprListDelete(db, pList);
109480       }
109481       pTerm->eOperator = WO_NOOP;  /* case 1 trumps case 2 */
109482     }
109483   }
109484 }
109485 #endif /* !SQLITE_OMIT_OR_OPTIMIZATION && !SQLITE_OMIT_SUBQUERY */
109486 
109487 /*
109488 ** The input to this routine is an WhereTerm structure with only the
109489 ** "pExpr" field filled in.  The job of this routine is to analyze the
109490 ** subexpression and populate all the other fields of the WhereTerm
109491 ** structure.
109492 **
109493 ** If the expression is of the form "<expr> <op> X" it gets commuted
109494 ** to the standard form of "X <op> <expr>".
109495 **
109496 ** If the expression is of the form "X <op> Y" where both X and Y are
109497 ** columns, then the original expression is unchanged and a new virtual
109498 ** term of the form "Y <op> X" is added to the WHERE clause and
109499 ** analyzed separately.  The original term is marked with TERM_COPIED
109500 ** and the new term is marked with TERM_DYNAMIC (because it's pExpr
109501 ** needs to be freed with the WhereClause) and TERM_VIRTUAL (because it
109502 ** is a commuted copy of a prior term.)  The original term has nChild=1
109503 ** and the copy has idxParent set to the index of the original term.
109504 */
109505 static void exprAnalyze(
109506   SrcList *pSrc,            /* the FROM clause */
109507   WhereClause *pWC,         /* the WHERE clause */
109508   int idxTerm               /* Index of the term to be analyzed */
109509 ){
109510   WhereInfo *pWInfo = pWC->pWInfo; /* WHERE clause processing context */
109511   WhereTerm *pTerm;                /* The term to be analyzed */
109512   WhereMaskSet *pMaskSet;          /* Set of table index masks */
109513   Expr *pExpr;                     /* The expression to be analyzed */
109514   Bitmask prereqLeft;              /* Prerequesites of the pExpr->pLeft */
109515   Bitmask prereqAll;               /* Prerequesites of pExpr */
109516   Bitmask extraRight = 0;          /* Extra dependencies on LEFT JOIN */
109517   Expr *pStr1 = 0;                 /* RHS of LIKE/GLOB operator */
109518   int isComplete = 0;              /* RHS of LIKE/GLOB ends with wildcard */
109519   int noCase = 0;                  /* LIKE/GLOB distinguishes case */
109520   int op;                          /* Top-level operator.  pExpr->op */
109521   Parse *pParse = pWInfo->pParse;  /* Parsing context */
109522   sqlite3 *db = pParse->db;        /* Database connection */
109523 
109524   if( db->mallocFailed ){
109525     return;
109526   }
109527   pTerm = &pWC->a[idxTerm];
109528   pMaskSet = &pWInfo->sMaskSet;
109529   pExpr = pTerm->pExpr;
109530   assert( pExpr->op!=TK_AS && pExpr->op!=TK_COLLATE );
109531   prereqLeft = exprTableUsage(pMaskSet, pExpr->pLeft);
109532   op = pExpr->op;
109533   if( op==TK_IN ){
109534     assert( pExpr->pRight==0 );
109535     if( ExprHasProperty(pExpr, EP_xIsSelect) ){
109536       pTerm->prereqRight = exprSelectTableUsage(pMaskSet, pExpr->x.pSelect);
109537     }else{
109538       pTerm->prereqRight = exprListTableUsage(pMaskSet, pExpr->x.pList);
109539     }
109540   }else if( op==TK_ISNULL ){
109541     pTerm->prereqRight = 0;
109542   }else{
109543     pTerm->prereqRight = exprTableUsage(pMaskSet, pExpr->pRight);
109544   }
109545   prereqAll = exprTableUsage(pMaskSet, pExpr);
109546   if( ExprHasProperty(pExpr, EP_FromJoin) ){
109547     Bitmask x = getMask(pMaskSet, pExpr->iRightJoinTable);
109548     prereqAll |= x;
109549     extraRight = x-1;  /* ON clause terms may not be used with an index
109550                        ** on left table of a LEFT JOIN.  Ticket #3015 */
109551   }
109552   pTerm->prereqAll = prereqAll;
109553   pTerm->leftCursor = -1;
109554   pTerm->iParent = -1;
109555   pTerm->eOperator = 0;
109556   if( allowedOp(op) ){
109557     Expr *pLeft = sqlite3ExprSkipCollate(pExpr->pLeft);
109558     Expr *pRight = sqlite3ExprSkipCollate(pExpr->pRight);
109559     u16 opMask = (pTerm->prereqRight & prereqLeft)==0 ? WO_ALL : WO_EQUIV;
109560     if( pLeft->op==TK_COLUMN ){
109561       pTerm->leftCursor = pLeft->iTable;
109562       pTerm->u.leftColumn = pLeft->iColumn;
109563       pTerm->eOperator = operatorMask(op) & opMask;
109564     }
109565     if( pRight && pRight->op==TK_COLUMN ){
109566       WhereTerm *pNew;
109567       Expr *pDup;
109568       u16 eExtraOp = 0;        /* Extra bits for pNew->eOperator */
109569       if( pTerm->leftCursor>=0 ){
109570         int idxNew;
109571         pDup = sqlite3ExprDup(db, pExpr, 0);
109572         if( db->mallocFailed ){
109573           sqlite3ExprDelete(db, pDup);
109574           return;
109575         }
109576         idxNew = whereClauseInsert(pWC, pDup, TERM_VIRTUAL|TERM_DYNAMIC);
109577         if( idxNew==0 ) return;
109578         pNew = &pWC->a[idxNew];
109579         pNew->iParent = idxTerm;
109580         pTerm = &pWC->a[idxTerm];
109581         pTerm->nChild = 1;
109582         pTerm->wtFlags |= TERM_COPIED;
109583         if( pExpr->op==TK_EQ
109584          && !ExprHasProperty(pExpr, EP_FromJoin)
109585          && OptimizationEnabled(db, SQLITE_Transitive)
109586         ){
109587           pTerm->eOperator |= WO_EQUIV;
109588           eExtraOp = WO_EQUIV;
109589         }
109590       }else{
109591         pDup = pExpr;
109592         pNew = pTerm;
109593       }
109594       exprCommute(pParse, pDup);
109595       pLeft = sqlite3ExprSkipCollate(pDup->pLeft);
109596       pNew->leftCursor = pLeft->iTable;
109597       pNew->u.leftColumn = pLeft->iColumn;
109598       testcase( (prereqLeft | extraRight) != prereqLeft );
109599       pNew->prereqRight = prereqLeft | extraRight;
109600       pNew->prereqAll = prereqAll;
109601       pNew->eOperator = (operatorMask(pDup->op) + eExtraOp) & opMask;
109602     }
109603   }
109604 
109605 #ifndef SQLITE_OMIT_BETWEEN_OPTIMIZATION
109606   /* If a term is the BETWEEN operator, create two new virtual terms
109607   ** that define the range that the BETWEEN implements.  For example:
109608   **
109609   **      a BETWEEN b AND c
109610   **
109611   ** is converted into:
109612   **
109613   **      (a BETWEEN b AND c) AND (a>=b) AND (a<=c)
109614   **
109615   ** The two new terms are added onto the end of the WhereClause object.
109616   ** The new terms are "dynamic" and are children of the original BETWEEN
109617   ** term.  That means that if the BETWEEN term is coded, the children are
109618   ** skipped.  Or, if the children are satisfied by an index, the original
109619   ** BETWEEN term is skipped.
109620   */
109621   else if( pExpr->op==TK_BETWEEN && pWC->op==TK_AND ){
109622     ExprList *pList = pExpr->x.pList;
109623     int i;
109624     static const u8 ops[] = {TK_GE, TK_LE};
109625     assert( pList!=0 );
109626     assert( pList->nExpr==2 );
109627     for(i=0; i<2; i++){
109628       Expr *pNewExpr;
109629       int idxNew;
109630       pNewExpr = sqlite3PExpr(pParse, ops[i], 
109631                              sqlite3ExprDup(db, pExpr->pLeft, 0),
109632                              sqlite3ExprDup(db, pList->a[i].pExpr, 0), 0);
109633       transferJoinMarkings(pNewExpr, pExpr);
109634       idxNew = whereClauseInsert(pWC, pNewExpr, TERM_VIRTUAL|TERM_DYNAMIC);
109635       testcase( idxNew==0 );
109636       exprAnalyze(pSrc, pWC, idxNew);
109637       pTerm = &pWC->a[idxTerm];
109638       pWC->a[idxNew].iParent = idxTerm;
109639     }
109640     pTerm->nChild = 2;
109641   }
109642 #endif /* SQLITE_OMIT_BETWEEN_OPTIMIZATION */
109643 
109644 #if !defined(SQLITE_OMIT_OR_OPTIMIZATION) && !defined(SQLITE_OMIT_SUBQUERY)
109645   /* Analyze a term that is composed of two or more subterms connected by
109646   ** an OR operator.
109647   */
109648   else if( pExpr->op==TK_OR ){
109649     assert( pWC->op==TK_AND );
109650     exprAnalyzeOrTerm(pSrc, pWC, idxTerm);
109651     pTerm = &pWC->a[idxTerm];
109652   }
109653 #endif /* SQLITE_OMIT_OR_OPTIMIZATION */
109654 
109655 #ifndef SQLITE_OMIT_LIKE_OPTIMIZATION
109656   /* Add constraints to reduce the search space on a LIKE or GLOB
109657   ** operator.
109658   **
109659   ** A like pattern of the form "x LIKE 'abc%'" is changed into constraints
109660   **
109661   **          x>='abc' AND x<'abd' AND x LIKE 'abc%'
109662   **
109663   ** The last character of the prefix "abc" is incremented to form the
109664   ** termination condition "abd".
109665   */
109666   if( pWC->op==TK_AND 
109667    && isLikeOrGlob(pParse, pExpr, &pStr1, &isComplete, &noCase)
109668   ){
109669     Expr *pLeft;       /* LHS of LIKE/GLOB operator */
109670     Expr *pStr2;       /* Copy of pStr1 - RHS of LIKE/GLOB operator */
109671     Expr *pNewExpr1;
109672     Expr *pNewExpr2;
109673     int idxNew1;
109674     int idxNew2;
109675     Token sCollSeqName;  /* Name of collating sequence */
109676 
109677     pLeft = pExpr->x.pList->a[1].pExpr;
109678     pStr2 = sqlite3ExprDup(db, pStr1, 0);
109679     if( !db->mallocFailed ){
109680       u8 c, *pC;       /* Last character before the first wildcard */
109681       pC = (u8*)&pStr2->u.zToken[sqlite3Strlen30(pStr2->u.zToken)-1];
109682       c = *pC;
109683       if( noCase ){
109684         /* The point is to increment the last character before the first
109685         ** wildcard.  But if we increment '@', that will push it into the
109686         ** alphabetic range where case conversions will mess up the 
109687         ** inequality.  To avoid this, make sure to also run the full
109688         ** LIKE on all candidate expressions by clearing the isComplete flag
109689         */
109690         if( c=='A'-1 ) isComplete = 0;
109691         c = sqlite3UpperToLower[c];
109692       }
109693       *pC = c + 1;
109694     }
109695     sCollSeqName.z = noCase ? "NOCASE" : "BINARY";
109696     sCollSeqName.n = 6;
109697     pNewExpr1 = sqlite3ExprDup(db, pLeft, 0);
109698     pNewExpr1 = sqlite3PExpr(pParse, TK_GE, 
109699            sqlite3ExprAddCollateToken(pParse,pNewExpr1,&sCollSeqName),
109700            pStr1, 0);
109701     transferJoinMarkings(pNewExpr1, pExpr);
109702     idxNew1 = whereClauseInsert(pWC, pNewExpr1, TERM_VIRTUAL|TERM_DYNAMIC);
109703     testcase( idxNew1==0 );
109704     exprAnalyze(pSrc, pWC, idxNew1);
109705     pNewExpr2 = sqlite3ExprDup(db, pLeft, 0);
109706     pNewExpr2 = sqlite3PExpr(pParse, TK_LT,
109707            sqlite3ExprAddCollateToken(pParse,pNewExpr2,&sCollSeqName),
109708            pStr2, 0);
109709     transferJoinMarkings(pNewExpr2, pExpr);
109710     idxNew2 = whereClauseInsert(pWC, pNewExpr2, TERM_VIRTUAL|TERM_DYNAMIC);
109711     testcase( idxNew2==0 );
109712     exprAnalyze(pSrc, pWC, idxNew2);
109713     pTerm = &pWC->a[idxTerm];
109714     if( isComplete ){
109715       pWC->a[idxNew1].iParent = idxTerm;
109716       pWC->a[idxNew2].iParent = idxTerm;
109717       pTerm->nChild = 2;
109718     }
109719   }
109720 #endif /* SQLITE_OMIT_LIKE_OPTIMIZATION */
109721 
109722 #ifndef SQLITE_OMIT_VIRTUALTABLE
109723   /* Add a WO_MATCH auxiliary term to the constraint set if the
109724   ** current expression is of the form:  column MATCH expr.
109725   ** This information is used by the xBestIndex methods of
109726   ** virtual tables.  The native query optimizer does not attempt
109727   ** to do anything with MATCH functions.
109728   */
109729   if( isMatchOfColumn(pExpr) ){
109730     int idxNew;
109731     Expr *pRight, *pLeft;
109732     WhereTerm *pNewTerm;
109733     Bitmask prereqColumn, prereqExpr;
109734 
109735     pRight = pExpr->x.pList->a[0].pExpr;
109736     pLeft = pExpr->x.pList->a[1].pExpr;
109737     prereqExpr = exprTableUsage(pMaskSet, pRight);
109738     prereqColumn = exprTableUsage(pMaskSet, pLeft);
109739     if( (prereqExpr & prereqColumn)==0 ){
109740       Expr *pNewExpr;
109741       pNewExpr = sqlite3PExpr(pParse, TK_MATCH, 
109742                               0, sqlite3ExprDup(db, pRight, 0), 0);
109743       idxNew = whereClauseInsert(pWC, pNewExpr, TERM_VIRTUAL|TERM_DYNAMIC);
109744       testcase( idxNew==0 );
109745       pNewTerm = &pWC->a[idxNew];
109746       pNewTerm->prereqRight = prereqExpr;
109747       pNewTerm->leftCursor = pLeft->iTable;
109748       pNewTerm->u.leftColumn = pLeft->iColumn;
109749       pNewTerm->eOperator = WO_MATCH;
109750       pNewTerm->iParent = idxTerm;
109751       pTerm = &pWC->a[idxTerm];
109752       pTerm->nChild = 1;
109753       pTerm->wtFlags |= TERM_COPIED;
109754       pNewTerm->prereqAll = pTerm->prereqAll;
109755     }
109756   }
109757 #endif /* SQLITE_OMIT_VIRTUALTABLE */
109758 
109759 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
109760   /* When sqlite_stat3 histogram data is available an operator of the
109761   ** form "x IS NOT NULL" can sometimes be evaluated more efficiently
109762   ** as "x>NULL" if x is not an INTEGER PRIMARY KEY.  So construct a
109763   ** virtual term of that form.
109764   **
109765   ** Note that the virtual term must be tagged with TERM_VNULL.  This
109766   ** TERM_VNULL tag will suppress the not-null check at the beginning
109767   ** of the loop.  Without the TERM_VNULL flag, the not-null check at
109768   ** the start of the loop will prevent any results from being returned.
109769   */
109770   if( pExpr->op==TK_NOTNULL
109771    && pExpr->pLeft->op==TK_COLUMN
109772    && pExpr->pLeft->iColumn>=0
109773    && OptimizationEnabled(db, SQLITE_Stat3)
109774   ){
109775     Expr *pNewExpr;
109776     Expr *pLeft = pExpr->pLeft;
109777     int idxNew;
109778     WhereTerm *pNewTerm;
109779 
109780     pNewExpr = sqlite3PExpr(pParse, TK_GT,
109781                             sqlite3ExprDup(db, pLeft, 0),
109782                             sqlite3PExpr(pParse, TK_NULL, 0, 0, 0), 0);
109783 
109784     idxNew = whereClauseInsert(pWC, pNewExpr,
109785                               TERM_VIRTUAL|TERM_DYNAMIC|TERM_VNULL);
109786     if( idxNew ){
109787       pNewTerm = &pWC->a[idxNew];
109788       pNewTerm->prereqRight = 0;
109789       pNewTerm->leftCursor = pLeft->iTable;
109790       pNewTerm->u.leftColumn = pLeft->iColumn;
109791       pNewTerm->eOperator = WO_GT;
109792       pNewTerm->iParent = idxTerm;
109793       pTerm = &pWC->a[idxTerm];
109794       pTerm->nChild = 1;
109795       pTerm->wtFlags |= TERM_COPIED;
109796       pNewTerm->prereqAll = pTerm->prereqAll;
109797     }
109798   }
109799 #endif /* SQLITE_ENABLE_STAT3_OR_STAT4 */
109800 
109801   /* Prevent ON clause terms of a LEFT JOIN from being used to drive
109802   ** an index for tables to the left of the join.
109803   */
109804   pTerm->prereqRight |= extraRight;
109805 }
109806 
109807 /*
109808 ** This function searches pList for a entry that matches the iCol-th column
109809 ** of index pIdx.
109810 **
109811 ** If such an expression is found, its index in pList->a[] is returned. If
109812 ** no expression is found, -1 is returned.
109813 */
109814 static int findIndexCol(
109815   Parse *pParse,                  /* Parse context */
109816   ExprList *pList,                /* Expression list to search */
109817   int iBase,                      /* Cursor for table associated with pIdx */
109818   Index *pIdx,                    /* Index to match column of */
109819   int iCol                        /* Column of index to match */
109820 ){
109821   int i;
109822   const char *zColl = pIdx->azColl[iCol];
109823 
109824   for(i=0; i<pList->nExpr; i++){
109825     Expr *p = sqlite3ExprSkipCollate(pList->a[i].pExpr);
109826     if( p->op==TK_COLUMN
109827      && p->iColumn==pIdx->aiColumn[iCol]
109828      && p->iTable==iBase
109829     ){
109830       CollSeq *pColl = sqlite3ExprCollSeq(pParse, pList->a[i].pExpr);
109831       if( ALWAYS(pColl) && 0==sqlite3StrICmp(pColl->zName, zColl) ){
109832         return i;
109833       }
109834     }
109835   }
109836 
109837   return -1;
109838 }
109839 
109840 /*
109841 ** Return true if the DISTINCT expression-list passed as the third argument
109842 ** is redundant.
109843 **
109844 ** A DISTINCT list is redundant if the database contains some subset of
109845 ** columns that are unique and non-null.
109846 */
109847 static int isDistinctRedundant(
109848   Parse *pParse,            /* Parsing context */
109849   SrcList *pTabList,        /* The FROM clause */
109850   WhereClause *pWC,         /* The WHERE clause */
109851   ExprList *pDistinct       /* The result set that needs to be DISTINCT */
109852 ){
109853   Table *pTab;
109854   Index *pIdx;
109855   int i;                          
109856   int iBase;
109857 
109858   /* If there is more than one table or sub-select in the FROM clause of
109859   ** this query, then it will not be possible to show that the DISTINCT 
109860   ** clause is redundant. */
109861   if( pTabList->nSrc!=1 ) return 0;
109862   iBase = pTabList->a[0].iCursor;
109863   pTab = pTabList->a[0].pTab;
109864 
109865   /* If any of the expressions is an IPK column on table iBase, then return 
109866   ** true. Note: The (p->iTable==iBase) part of this test may be false if the
109867   ** current SELECT is a correlated sub-query.
109868   */
109869   for(i=0; i<pDistinct->nExpr; i++){
109870     Expr *p = sqlite3ExprSkipCollate(pDistinct->a[i].pExpr);
109871     if( p->op==TK_COLUMN && p->iTable==iBase && p->iColumn<0 ) return 1;
109872   }
109873 
109874   /* Loop through all indices on the table, checking each to see if it makes
109875   ** the DISTINCT qualifier redundant. It does so if:
109876   **
109877   **   1. The index is itself UNIQUE, and
109878   **
109879   **   2. All of the columns in the index are either part of the pDistinct
109880   **      list, or else the WHERE clause contains a term of the form "col=X",
109881   **      where X is a constant value. The collation sequences of the
109882   **      comparison and select-list expressions must match those of the index.
109883   **
109884   **   3. All of those index columns for which the WHERE clause does not
109885   **      contain a "col=X" term are subject to a NOT NULL constraint.
109886   */
109887   for(pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext){
109888     if( pIdx->onError==OE_None ) continue;
109889     for(i=0; i<pIdx->nKeyCol; i++){
109890       i16 iCol = pIdx->aiColumn[i];
109891       if( 0==findTerm(pWC, iBase, iCol, ~(Bitmask)0, WO_EQ, pIdx) ){
109892         int iIdxCol = findIndexCol(pParse, pDistinct, iBase, pIdx, i);
109893         if( iIdxCol<0 || pTab->aCol[iCol].notNull==0 ){
109894           break;
109895         }
109896       }
109897     }
109898     if( i==pIdx->nKeyCol ){
109899       /* This index implies that the DISTINCT qualifier is redundant. */
109900       return 1;
109901     }
109902   }
109903 
109904   return 0;
109905 }
109906 
109907 
109908 /*
109909 ** Estimate the logarithm of the input value to base 2.
109910 */
109911 static LogEst estLog(LogEst N){
109912   LogEst x = sqlite3LogEst(N);
109913   return x>33 ? x - 33 : 0;
109914 }
109915 
109916 /*
109917 ** Two routines for printing the content of an sqlite3_index_info
109918 ** structure.  Used for testing and debugging only.  If neither
109919 ** SQLITE_TEST or SQLITE_DEBUG are defined, then these routines
109920 ** are no-ops.
109921 */
109922 #if !defined(SQLITE_OMIT_VIRTUALTABLE) && defined(WHERETRACE_ENABLED)
109923 static void TRACE_IDX_INPUTS(sqlite3_index_info *p){
109924   int i;
109925   if( !sqlite3WhereTrace ) return;
109926   for(i=0; i<p->nConstraint; i++){
109927     sqlite3DebugPrintf("  constraint[%d]: col=%d termid=%d op=%d usabled=%d\n",
109928        i,
109929        p->aConstraint[i].iColumn,
109930        p->aConstraint[i].iTermOffset,
109931        p->aConstraint[i].op,
109932        p->aConstraint[i].usable);
109933   }
109934   for(i=0; i<p->nOrderBy; i++){
109935     sqlite3DebugPrintf("  orderby[%d]: col=%d desc=%d\n",
109936        i,
109937        p->aOrderBy[i].iColumn,
109938        p->aOrderBy[i].desc);
109939   }
109940 }
109941 static void TRACE_IDX_OUTPUTS(sqlite3_index_info *p){
109942   int i;
109943   if( !sqlite3WhereTrace ) return;
109944   for(i=0; i<p->nConstraint; i++){
109945     sqlite3DebugPrintf("  usage[%d]: argvIdx=%d omit=%d\n",
109946        i,
109947        p->aConstraintUsage[i].argvIndex,
109948        p->aConstraintUsage[i].omit);
109949   }
109950   sqlite3DebugPrintf("  idxNum=%d\n", p->idxNum);
109951   sqlite3DebugPrintf("  idxStr=%s\n", p->idxStr);
109952   sqlite3DebugPrintf("  orderByConsumed=%d\n", p->orderByConsumed);
109953   sqlite3DebugPrintf("  estimatedCost=%g\n", p->estimatedCost);
109954   sqlite3DebugPrintf("  estimatedRows=%lld\n", p->estimatedRows);
109955 }
109956 #else
109957 #define TRACE_IDX_INPUTS(A)
109958 #define TRACE_IDX_OUTPUTS(A)
109959 #endif
109960 
109961 #ifndef SQLITE_OMIT_AUTOMATIC_INDEX
109962 /*
109963 ** Return TRUE if the WHERE clause term pTerm is of a form where it
109964 ** could be used with an index to access pSrc, assuming an appropriate
109965 ** index existed.
109966 */
109967 static int termCanDriveIndex(
109968   WhereTerm *pTerm,              /* WHERE clause term to check */
109969   struct SrcList_item *pSrc,     /* Table we are trying to access */
109970   Bitmask notReady               /* Tables in outer loops of the join */
109971 ){
109972   char aff;
109973   if( pTerm->leftCursor!=pSrc->iCursor ) return 0;
109974   if( (pTerm->eOperator & WO_EQ)==0 ) return 0;
109975   if( (pTerm->prereqRight & notReady)!=0 ) return 0;
109976   if( pTerm->u.leftColumn<0 ) return 0;
109977   aff = pSrc->pTab->aCol[pTerm->u.leftColumn].affinity;
109978   if( !sqlite3IndexAffinityOk(pTerm->pExpr, aff) ) return 0;
109979   return 1;
109980 }
109981 #endif
109982 
109983 
109984 #ifndef SQLITE_OMIT_AUTOMATIC_INDEX
109985 /*
109986 ** Generate code to construct the Index object for an automatic index
109987 ** and to set up the WhereLevel object pLevel so that the code generator
109988 ** makes use of the automatic index.
109989 */
109990 static void constructAutomaticIndex(
109991   Parse *pParse,              /* The parsing context */
109992   WhereClause *pWC,           /* The WHERE clause */
109993   struct SrcList_item *pSrc,  /* The FROM clause term to get the next index */
109994   Bitmask notReady,           /* Mask of cursors that are not available */
109995   WhereLevel *pLevel          /* Write new index here */
109996 ){
109997   int nKeyCol;                /* Number of columns in the constructed index */
109998   WhereTerm *pTerm;           /* A single term of the WHERE clause */
109999   WhereTerm *pWCEnd;          /* End of pWC->a[] */
110000   Index *pIdx;                /* Object describing the transient index */
110001   Vdbe *v;                    /* Prepared statement under construction */
110002   int addrInit;               /* Address of the initialization bypass jump */
110003   Table *pTable;              /* The table being indexed */
110004   int addrTop;                /* Top of the index fill loop */
110005   int regRecord;              /* Register holding an index record */
110006   int n;                      /* Column counter */
110007   int i;                      /* Loop counter */
110008   int mxBitCol;               /* Maximum column in pSrc->colUsed */
110009   CollSeq *pColl;             /* Collating sequence to on a column */
110010   WhereLoop *pLoop;           /* The Loop object */
110011   char *zNotUsed;             /* Extra space on the end of pIdx */
110012   Bitmask idxCols;            /* Bitmap of columns used for indexing */
110013   Bitmask extraCols;          /* Bitmap of additional columns */
110014   u8 sentWarning = 0;         /* True if a warnning has been issued */
110015 
110016   /* Generate code to skip over the creation and initialization of the
110017   ** transient index on 2nd and subsequent iterations of the loop. */
110018   v = pParse->pVdbe;
110019   assert( v!=0 );
110020   addrInit = sqlite3CodeOnce(pParse);
110021 
110022   /* Count the number of columns that will be added to the index
110023   ** and used to match WHERE clause constraints */
110024   nKeyCol = 0;
110025   pTable = pSrc->pTab;
110026   pWCEnd = &pWC->a[pWC->nTerm];
110027   pLoop = pLevel->pWLoop;
110028   idxCols = 0;
110029   for(pTerm=pWC->a; pTerm<pWCEnd; pTerm++){
110030     if( termCanDriveIndex(pTerm, pSrc, notReady) ){
110031       int iCol = pTerm->u.leftColumn;
110032       Bitmask cMask = iCol>=BMS ? MASKBIT(BMS-1) : MASKBIT(iCol);
110033       testcase( iCol==BMS );
110034       testcase( iCol==BMS-1 );
110035       if( !sentWarning ){
110036         sqlite3_log(SQLITE_WARNING_AUTOINDEX,
110037             "automatic index on %s(%s)", pTable->zName,
110038             pTable->aCol[iCol].zName);
110039         sentWarning = 1;
110040       }
110041       if( (idxCols & cMask)==0 ){
110042         if( whereLoopResize(pParse->db, pLoop, nKeyCol+1) ) return;
110043         pLoop->aLTerm[nKeyCol++] = pTerm;
110044         idxCols |= cMask;
110045       }
110046     }
110047   }
110048   assert( nKeyCol>0 );
110049   pLoop->u.btree.nEq = pLoop->nLTerm = nKeyCol;
110050   pLoop->wsFlags = WHERE_COLUMN_EQ | WHERE_IDX_ONLY | WHERE_INDEXED
110051                      | WHERE_AUTO_INDEX;
110052 
110053   /* Count the number of additional columns needed to create a
110054   ** covering index.  A "covering index" is an index that contains all
110055   ** columns that are needed by the query.  With a covering index, the
110056   ** original table never needs to be accessed.  Automatic indices must
110057   ** be a covering index because the index will not be updated if the
110058   ** original table changes and the index and table cannot both be used
110059   ** if they go out of sync.
110060   */
110061   extraCols = pSrc->colUsed & (~idxCols | MASKBIT(BMS-1));
110062   mxBitCol = (pTable->nCol >= BMS-1) ? BMS-1 : pTable->nCol;
110063   testcase( pTable->nCol==BMS-1 );
110064   testcase( pTable->nCol==BMS-2 );
110065   for(i=0; i<mxBitCol; i++){
110066     if( extraCols & MASKBIT(i) ) nKeyCol++;
110067   }
110068   if( pSrc->colUsed & MASKBIT(BMS-1) ){
110069     nKeyCol += pTable->nCol - BMS + 1;
110070   }
110071   pLoop->wsFlags |= WHERE_COLUMN_EQ | WHERE_IDX_ONLY;
110072 
110073   /* Construct the Index object to describe this index */
110074   pIdx = sqlite3AllocateIndexObject(pParse->db, nKeyCol+1, 0, &zNotUsed);
110075   if( pIdx==0 ) return;
110076   pLoop->u.btree.pIndex = pIdx;
110077   pIdx->zName = "auto-index";
110078   pIdx->pTable = pTable;
110079   n = 0;
110080   idxCols = 0;
110081   for(pTerm=pWC->a; pTerm<pWCEnd; pTerm++){
110082     if( termCanDriveIndex(pTerm, pSrc, notReady) ){
110083       int iCol = pTerm->u.leftColumn;
110084       Bitmask cMask = iCol>=BMS ? MASKBIT(BMS-1) : MASKBIT(iCol);
110085       testcase( iCol==BMS-1 );
110086       testcase( iCol==BMS );
110087       if( (idxCols & cMask)==0 ){
110088         Expr *pX = pTerm->pExpr;
110089         idxCols |= cMask;
110090         pIdx->aiColumn[n] = pTerm->u.leftColumn;
110091         pColl = sqlite3BinaryCompareCollSeq(pParse, pX->pLeft, pX->pRight);
110092         pIdx->azColl[n] = ALWAYS(pColl) ? pColl->zName : "BINARY";
110093         n++;
110094       }
110095     }
110096   }
110097   assert( (u32)n==pLoop->u.btree.nEq );
110098 
110099   /* Add additional columns needed to make the automatic index into
110100   ** a covering index */
110101   for(i=0; i<mxBitCol; i++){
110102     if( extraCols & MASKBIT(i) ){
110103       pIdx->aiColumn[n] = i;
110104       pIdx->azColl[n] = "BINARY";
110105       n++;
110106     }
110107   }
110108   if( pSrc->colUsed & MASKBIT(BMS-1) ){
110109     for(i=BMS-1; i<pTable->nCol; i++){
110110       pIdx->aiColumn[n] = i;
110111       pIdx->azColl[n] = "BINARY";
110112       n++;
110113     }
110114   }
110115   assert( n==nKeyCol );
110116   pIdx->aiColumn[n] = -1;
110117   pIdx->azColl[n] = "BINARY";
110118 
110119   /* Create the automatic index */
110120   assert( pLevel->iIdxCur>=0 );
110121   pLevel->iIdxCur = pParse->nTab++;
110122   sqlite3VdbeAddOp2(v, OP_OpenAutoindex, pLevel->iIdxCur, nKeyCol+1);
110123   sqlite3VdbeSetP4KeyInfo(pParse, pIdx);
110124   VdbeComment((v, "for %s", pTable->zName));
110125 
110126   /* Fill the automatic index with content */
110127   addrTop = sqlite3VdbeAddOp1(v, OP_Rewind, pLevel->iTabCur);
110128   regRecord = sqlite3GetTempReg(pParse);
110129   sqlite3GenerateIndexKey(pParse, pIdx, pLevel->iTabCur, regRecord, 0, 0);
110130   sqlite3VdbeAddOp2(v, OP_IdxInsert, pLevel->iIdxCur, regRecord);
110131   sqlite3VdbeChangeP5(v, OPFLAG_USESEEKRESULT);
110132   sqlite3VdbeAddOp2(v, OP_Next, pLevel->iTabCur, addrTop+1);
110133   sqlite3VdbeChangeP5(v, SQLITE_STMTSTATUS_AUTOINDEX);
110134   sqlite3VdbeJumpHere(v, addrTop);
110135   sqlite3ReleaseTempReg(pParse, regRecord);
110136   
110137   /* Jump here when skipping the initialization */
110138   sqlite3VdbeJumpHere(v, addrInit);
110139 }
110140 #endif /* SQLITE_OMIT_AUTOMATIC_INDEX */
110141 
110142 #ifndef SQLITE_OMIT_VIRTUALTABLE
110143 /*
110144 ** Allocate and populate an sqlite3_index_info structure. It is the 
110145 ** responsibility of the caller to eventually release the structure
110146 ** by passing the pointer returned by this function to sqlite3_free().
110147 */
110148 static sqlite3_index_info *allocateIndexInfo(
110149   Parse *pParse,
110150   WhereClause *pWC,
110151   struct SrcList_item *pSrc,
110152   ExprList *pOrderBy
110153 ){
110154   int i, j;
110155   int nTerm;
110156   struct sqlite3_index_constraint *pIdxCons;
110157   struct sqlite3_index_orderby *pIdxOrderBy;
110158   struct sqlite3_index_constraint_usage *pUsage;
110159   WhereTerm *pTerm;
110160   int nOrderBy;
110161   sqlite3_index_info *pIdxInfo;
110162 
110163   /* Count the number of possible WHERE clause constraints referring
110164   ** to this virtual table */
110165   for(i=nTerm=0, pTerm=pWC->a; i<pWC->nTerm; i++, pTerm++){
110166     if( pTerm->leftCursor != pSrc->iCursor ) continue;
110167     assert( IsPowerOfTwo(pTerm->eOperator & ~WO_EQUIV) );
110168     testcase( pTerm->eOperator & WO_IN );
110169     testcase( pTerm->eOperator & WO_ISNULL );
110170     if( pTerm->eOperator & (WO_ISNULL) ) continue;
110171     if( pTerm->wtFlags & TERM_VNULL ) continue;
110172     nTerm++;
110173   }
110174 
110175   /* If the ORDER BY clause contains only columns in the current 
110176   ** virtual table then allocate space for the aOrderBy part of
110177   ** the sqlite3_index_info structure.
110178   */
110179   nOrderBy = 0;
110180   if( pOrderBy ){
110181     int n = pOrderBy->nExpr;
110182     for(i=0; i<n; i++){
110183       Expr *pExpr = pOrderBy->a[i].pExpr;
110184       if( pExpr->op!=TK_COLUMN || pExpr->iTable!=pSrc->iCursor ) break;
110185     }
110186     if( i==n){
110187       nOrderBy = n;
110188     }
110189   }
110190 
110191   /* Allocate the sqlite3_index_info structure
110192   */
110193   pIdxInfo = sqlite3DbMallocZero(pParse->db, sizeof(*pIdxInfo)
110194                            + (sizeof(*pIdxCons) + sizeof(*pUsage))*nTerm
110195                            + sizeof(*pIdxOrderBy)*nOrderBy );
110196   if( pIdxInfo==0 ){
110197     sqlite3ErrorMsg(pParse, "out of memory");
110198     return 0;
110199   }
110200 
110201   /* Initialize the structure.  The sqlite3_index_info structure contains
110202   ** many fields that are declared "const" to prevent xBestIndex from
110203   ** changing them.  We have to do some funky casting in order to
110204   ** initialize those fields.
110205   */
110206   pIdxCons = (struct sqlite3_index_constraint*)&pIdxInfo[1];
110207   pIdxOrderBy = (struct sqlite3_index_orderby*)&pIdxCons[nTerm];
110208   pUsage = (struct sqlite3_index_constraint_usage*)&pIdxOrderBy[nOrderBy];
110209   *(int*)&pIdxInfo->nConstraint = nTerm;
110210   *(int*)&pIdxInfo->nOrderBy = nOrderBy;
110211   *(struct sqlite3_index_constraint**)&pIdxInfo->aConstraint = pIdxCons;
110212   *(struct sqlite3_index_orderby**)&pIdxInfo->aOrderBy = pIdxOrderBy;
110213   *(struct sqlite3_index_constraint_usage**)&pIdxInfo->aConstraintUsage =
110214                                                                    pUsage;
110215 
110216   for(i=j=0, pTerm=pWC->a; i<pWC->nTerm; i++, pTerm++){
110217     u8 op;
110218     if( pTerm->leftCursor != pSrc->iCursor ) continue;
110219     assert( IsPowerOfTwo(pTerm->eOperator & ~WO_EQUIV) );
110220     testcase( pTerm->eOperator & WO_IN );
110221     testcase( pTerm->eOperator & WO_ISNULL );
110222     if( pTerm->eOperator & (WO_ISNULL) ) continue;
110223     if( pTerm->wtFlags & TERM_VNULL ) continue;
110224     pIdxCons[j].iColumn = pTerm->u.leftColumn;
110225     pIdxCons[j].iTermOffset = i;
110226     op = (u8)pTerm->eOperator & WO_ALL;
110227     if( op==WO_IN ) op = WO_EQ;
110228     pIdxCons[j].op = op;
110229     /* The direct assignment in the previous line is possible only because
110230     ** the WO_ and SQLITE_INDEX_CONSTRAINT_ codes are identical.  The
110231     ** following asserts verify this fact. */
110232     assert( WO_EQ==SQLITE_INDEX_CONSTRAINT_EQ );
110233     assert( WO_LT==SQLITE_INDEX_CONSTRAINT_LT );
110234     assert( WO_LE==SQLITE_INDEX_CONSTRAINT_LE );
110235     assert( WO_GT==SQLITE_INDEX_CONSTRAINT_GT );
110236     assert( WO_GE==SQLITE_INDEX_CONSTRAINT_GE );
110237     assert( WO_MATCH==SQLITE_INDEX_CONSTRAINT_MATCH );
110238     assert( pTerm->eOperator & (WO_IN|WO_EQ|WO_LT|WO_LE|WO_GT|WO_GE|WO_MATCH) );
110239     j++;
110240   }
110241   for(i=0; i<nOrderBy; i++){
110242     Expr *pExpr = pOrderBy->a[i].pExpr;
110243     pIdxOrderBy[i].iColumn = pExpr->iColumn;
110244     pIdxOrderBy[i].desc = pOrderBy->a[i].sortOrder;
110245   }
110246 
110247   return pIdxInfo;
110248 }
110249 
110250 /*
110251 ** The table object reference passed as the second argument to this function
110252 ** must represent a virtual table. This function invokes the xBestIndex()
110253 ** method of the virtual table with the sqlite3_index_info object that
110254 ** comes in as the 3rd argument to this function.
110255 **
110256 ** If an error occurs, pParse is populated with an error message and a
110257 ** non-zero value is returned. Otherwise, 0 is returned and the output
110258 ** part of the sqlite3_index_info structure is left populated.
110259 **
110260 ** Whether or not an error is returned, it is the responsibility of the
110261 ** caller to eventually free p->idxStr if p->needToFreeIdxStr indicates
110262 ** that this is required.
110263 */
110264 static int vtabBestIndex(Parse *pParse, Table *pTab, sqlite3_index_info *p){
110265   sqlite3_vtab *pVtab = sqlite3GetVTable(pParse->db, pTab)->pVtab;
110266   int i;
110267   int rc;
110268 
110269   TRACE_IDX_INPUTS(p);
110270   rc = pVtab->pModule->xBestIndex(pVtab, p);
110271   TRACE_IDX_OUTPUTS(p);
110272 
110273   if( rc!=SQLITE_OK ){
110274     if( rc==SQLITE_NOMEM ){
110275       pParse->db->mallocFailed = 1;
110276     }else if( !pVtab->zErrMsg ){
110277       sqlite3ErrorMsg(pParse, "%s", sqlite3ErrStr(rc));
110278     }else{
110279       sqlite3ErrorMsg(pParse, "%s", pVtab->zErrMsg);
110280     }
110281   }
110282   sqlite3_free(pVtab->zErrMsg);
110283   pVtab->zErrMsg = 0;
110284 
110285   for(i=0; i<p->nConstraint; i++){
110286     if( !p->aConstraint[i].usable && p->aConstraintUsage[i].argvIndex>0 ){
110287       sqlite3ErrorMsg(pParse, 
110288           "table %s: xBestIndex returned an invalid plan", pTab->zName);
110289     }
110290   }
110291 
110292   return pParse->nErr;
110293 }
110294 #endif /* !defined(SQLITE_OMIT_VIRTUALTABLE) */
110295 
110296 
110297 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
110298 /*
110299 ** Estimate the location of a particular key among all keys in an
110300 ** index.  Store the results in aStat as follows:
110301 **
110302 **    aStat[0]      Est. number of rows less than pVal
110303 **    aStat[1]      Est. number of rows equal to pVal
110304 **
110305 ** Return SQLITE_OK on success.
110306 */
110307 static void whereKeyStats(
110308   Parse *pParse,              /* Database connection */
110309   Index *pIdx,                /* Index to consider domain of */
110310   UnpackedRecord *pRec,       /* Vector of values to consider */
110311   int roundUp,                /* Round up if true.  Round down if false */
110312   tRowcnt *aStat              /* OUT: stats written here */
110313 ){
110314   IndexSample *aSample = pIdx->aSample;
110315   int iCol;                   /* Index of required stats in anEq[] etc. */
110316   int iMin = 0;               /* Smallest sample not yet tested */
110317   int i = pIdx->nSample;      /* Smallest sample larger than or equal to pRec */
110318   int iTest;                  /* Next sample to test */
110319   int res;                    /* Result of comparison operation */
110320 
110321 #ifndef SQLITE_DEBUG
110322   UNUSED_PARAMETER( pParse );
110323 #endif
110324   assert( pRec!=0 );
110325   iCol = pRec->nField - 1;
110326   assert( pIdx->nSample>0 );
110327   assert( pRec->nField>0 && iCol<pIdx->nSampleCol );
110328   do{
110329     iTest = (iMin+i)/2;
110330     res = sqlite3VdbeRecordCompare(aSample[iTest].n, aSample[iTest].p, pRec);
110331     if( res<0 ){
110332       iMin = iTest+1;
110333     }else{
110334       i = iTest;
110335     }
110336   }while( res && iMin<i );
110337 
110338 #ifdef SQLITE_DEBUG
110339   /* The following assert statements check that the binary search code
110340   ** above found the right answer. This block serves no purpose other
110341   ** than to invoke the asserts.  */
110342   if( res==0 ){
110343     /* If (res==0) is true, then sample $i must be equal to pRec */
110344     assert( i<pIdx->nSample );
110345     assert( 0==sqlite3VdbeRecordCompare(aSample[i].n, aSample[i].p, pRec)
110346          || pParse->db->mallocFailed );
110347   }else{
110348     /* Otherwise, pRec must be smaller than sample $i and larger than
110349     ** sample ($i-1).  */
110350     assert( i==pIdx->nSample 
110351          || sqlite3VdbeRecordCompare(aSample[i].n, aSample[i].p, pRec)>0
110352          || pParse->db->mallocFailed );
110353     assert( i==0
110354          || sqlite3VdbeRecordCompare(aSample[i-1].n, aSample[i-1].p, pRec)<0
110355          || pParse->db->mallocFailed );
110356   }
110357 #endif /* ifdef SQLITE_DEBUG */
110358 
110359   /* At this point, aSample[i] is the first sample that is greater than
110360   ** or equal to pVal.  Or if i==pIdx->nSample, then all samples are less
110361   ** than pVal.  If aSample[i]==pVal, then res==0.
110362   */
110363   if( res==0 ){
110364     aStat[0] = aSample[i].anLt[iCol];
110365     aStat[1] = aSample[i].anEq[iCol];
110366   }else{
110367     tRowcnt iLower, iUpper, iGap;
110368     if( i==0 ){
110369       iLower = 0;
110370       iUpper = aSample[0].anLt[iCol];
110371     }else{
110372       iUpper = i>=pIdx->nSample ? pIdx->aiRowEst[0] : aSample[i].anLt[iCol];
110373       iLower = aSample[i-1].anEq[iCol] + aSample[i-1].anLt[iCol];
110374     }
110375     aStat[1] = (pIdx->nKeyCol>iCol ? pIdx->aAvgEq[iCol] : 1);
110376     if( iLower>=iUpper ){
110377       iGap = 0;
110378     }else{
110379       iGap = iUpper - iLower;
110380     }
110381     if( roundUp ){
110382       iGap = (iGap*2)/3;
110383     }else{
110384       iGap = iGap/3;
110385     }
110386     aStat[0] = iLower + iGap;
110387   }
110388 }
110389 #endif /* SQLITE_ENABLE_STAT3_OR_STAT4 */
110390 
110391 /*
110392 ** This function is used to estimate the number of rows that will be visited
110393 ** by scanning an index for a range of values. The range may have an upper
110394 ** bound, a lower bound, or both. The WHERE clause terms that set the upper
110395 ** and lower bounds are represented by pLower and pUpper respectively. For
110396 ** example, assuming that index p is on t1(a):
110397 **
110398 **   ... FROM t1 WHERE a > ? AND a < ? ...
110399 **                    |_____|   |_____|
110400 **                       |         |
110401 **                     pLower    pUpper
110402 **
110403 ** If either of the upper or lower bound is not present, then NULL is passed in
110404 ** place of the corresponding WhereTerm.
110405 **
110406 ** The value in (pBuilder->pNew->u.btree.nEq) is the index of the index
110407 ** column subject to the range constraint. Or, equivalently, the number of
110408 ** equality constraints optimized by the proposed index scan. For example,
110409 ** assuming index p is on t1(a, b), and the SQL query is:
110410 **
110411 **   ... FROM t1 WHERE a = ? AND b > ? AND b < ? ...
110412 **
110413 ** then nEq is set to 1 (as the range restricted column, b, is the second 
110414 ** left-most column of the index). Or, if the query is:
110415 **
110416 **   ... FROM t1 WHERE a > ? AND a < ? ...
110417 **
110418 ** then nEq is set to 0.
110419 **
110420 ** When this function is called, *pnOut is set to the sqlite3LogEst() of the
110421 ** number of rows that the index scan is expected to visit without 
110422 ** considering the range constraints. If nEq is 0, this is the number of 
110423 ** rows in the index. Assuming no error occurs, *pnOut is adjusted (reduced)
110424 ** to account for the range contraints pLower and pUpper.
110425 ** 
110426 ** In the absence of sqlite_stat4 ANALYZE data, or if such data cannot be
110427 ** used, each range inequality reduces the search space by a factor of 4. 
110428 ** Hence a pair of constraints (x>? AND x<?) reduces the expected number of
110429 ** rows visited by a factor of 16.
110430 */
110431 static int whereRangeScanEst(
110432   Parse *pParse,       /* Parsing & code generating context */
110433   WhereLoopBuilder *pBuilder,
110434   WhereTerm *pLower,   /* Lower bound on the range. ex: "x>123" Might be NULL */
110435   WhereTerm *pUpper,   /* Upper bound on the range. ex: "x<455" Might be NULL */
110436   WhereLoop *pLoop     /* Modify the .nOut and maybe .rRun fields */
110437 ){
110438   int rc = SQLITE_OK;
110439   int nOut = pLoop->nOut;
110440   LogEst nNew;
110441 
110442 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
110443   Index *p = pLoop->u.btree.pIndex;
110444   int nEq = pLoop->u.btree.nEq;
110445 
110446   if( p->nSample>0
110447    && nEq==pBuilder->nRecValid
110448    && nEq<p->nSampleCol
110449    && OptimizationEnabled(pParse->db, SQLITE_Stat3) 
110450   ){
110451     UnpackedRecord *pRec = pBuilder->pRec;
110452     tRowcnt a[2];
110453     u8 aff;
110454 
110455     /* Variable iLower will be set to the estimate of the number of rows in 
110456     ** the index that are less than the lower bound of the range query. The
110457     ** lower bound being the concatenation of $P and $L, where $P is the
110458     ** key-prefix formed by the nEq values matched against the nEq left-most
110459     ** columns of the index, and $L is the value in pLower.
110460     **
110461     ** Or, if pLower is NULL or $L cannot be extracted from it (because it
110462     ** is not a simple variable or literal value), the lower bound of the
110463     ** range is $P. Due to a quirk in the way whereKeyStats() works, even
110464     ** if $L is available, whereKeyStats() is called for both ($P) and 
110465     ** ($P:$L) and the larger of the two returned values used.
110466     **
110467     ** Similarly, iUpper is to be set to the estimate of the number of rows
110468     ** less than the upper bound of the range query. Where the upper bound
110469     ** is either ($P) or ($P:$U). Again, even if $U is available, both values
110470     ** of iUpper are requested of whereKeyStats() and the smaller used.
110471     */
110472     tRowcnt iLower;
110473     tRowcnt iUpper;
110474 
110475     if( nEq==p->nKeyCol ){
110476       aff = SQLITE_AFF_INTEGER;
110477     }else{
110478       aff = p->pTable->aCol[p->aiColumn[nEq]].affinity;
110479     }
110480     /* Determine iLower and iUpper using ($P) only. */
110481     if( nEq==0 ){
110482       iLower = 0;
110483       iUpper = p->aiRowEst[0];
110484     }else{
110485       /* Note: this call could be optimized away - since the same values must 
110486       ** have been requested when testing key $P in whereEqualScanEst().  */
110487       whereKeyStats(pParse, p, pRec, 0, a);
110488       iLower = a[0];
110489       iUpper = a[0] + a[1];
110490     }
110491 
110492     /* If possible, improve on the iLower estimate using ($P:$L). */
110493     if( pLower ){
110494       int bOk;                    /* True if value is extracted from pExpr */
110495       Expr *pExpr = pLower->pExpr->pRight;
110496       assert( (pLower->eOperator & (WO_GT|WO_GE))!=0 );
110497       rc = sqlite3Stat4ProbeSetValue(pParse, p, &pRec, pExpr, aff, nEq, &bOk);
110498       if( rc==SQLITE_OK && bOk ){
110499         tRowcnt iNew;
110500         whereKeyStats(pParse, p, pRec, 0, a);
110501         iNew = a[0] + ((pLower->eOperator & WO_GT) ? a[1] : 0);
110502         if( iNew>iLower ) iLower = iNew;
110503         nOut--;
110504       }
110505     }
110506 
110507     /* If possible, improve on the iUpper estimate using ($P:$U). */
110508     if( pUpper ){
110509       int bOk;                    /* True if value is extracted from pExpr */
110510       Expr *pExpr = pUpper->pExpr->pRight;
110511       assert( (pUpper->eOperator & (WO_LT|WO_LE))!=0 );
110512       rc = sqlite3Stat4ProbeSetValue(pParse, p, &pRec, pExpr, aff, nEq, &bOk);
110513       if( rc==SQLITE_OK && bOk ){
110514         tRowcnt iNew;
110515         whereKeyStats(pParse, p, pRec, 1, a);
110516         iNew = a[0] + ((pUpper->eOperator & WO_LE) ? a[1] : 0);
110517         if( iNew<iUpper ) iUpper = iNew;
110518         nOut--;
110519       }
110520     }
110521 
110522     pBuilder->pRec = pRec;
110523     if( rc==SQLITE_OK ){
110524       if( iUpper>iLower ){
110525         nNew = sqlite3LogEst(iUpper - iLower);
110526       }else{
110527         nNew = 10;        assert( 10==sqlite3LogEst(2) );
110528       }
110529       if( nNew<nOut ){
110530         nOut = nNew;
110531       }
110532       pLoop->nOut = (LogEst)nOut;
110533       WHERETRACE(0x10, ("range scan regions: %u..%u  est=%d\n",
110534                          (u32)iLower, (u32)iUpper, nOut));
110535       return SQLITE_OK;
110536     }
110537   }
110538 #else
110539   UNUSED_PARAMETER(pParse);
110540   UNUSED_PARAMETER(pBuilder);
110541 #endif
110542   assert( pLower || pUpper );
110543   /* TUNING:  Each inequality constraint reduces the search space 4-fold.
110544   ** A BETWEEN operator, therefore, reduces the search space 16-fold */
110545   nNew = nOut;
110546   if( pLower && (pLower->wtFlags & TERM_VNULL)==0 ){
110547     nNew -= 20;        assert( 20==sqlite3LogEst(4) );
110548     nOut--;
110549   }
110550   if( pUpper ){
110551     nNew -= 20;        assert( 20==sqlite3LogEst(4) );
110552     nOut--;
110553   }
110554   if( nNew<10 ) nNew = 10;
110555   if( nNew<nOut ) nOut = nNew;
110556   pLoop->nOut = (LogEst)nOut;
110557   return rc;
110558 }
110559 
110560 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
110561 /*
110562 ** Estimate the number of rows that will be returned based on
110563 ** an equality constraint x=VALUE and where that VALUE occurs in
110564 ** the histogram data.  This only works when x is the left-most
110565 ** column of an index and sqlite_stat3 histogram data is available
110566 ** for that index.  When pExpr==NULL that means the constraint is
110567 ** "x IS NULL" instead of "x=VALUE".
110568 **
110569 ** Write the estimated row count into *pnRow and return SQLITE_OK. 
110570 ** If unable to make an estimate, leave *pnRow unchanged and return
110571 ** non-zero.
110572 **
110573 ** This routine can fail if it is unable to load a collating sequence
110574 ** required for string comparison, or if unable to allocate memory
110575 ** for a UTF conversion required for comparison.  The error is stored
110576 ** in the pParse structure.
110577 */
110578 static int whereEqualScanEst(
110579   Parse *pParse,       /* Parsing & code generating context */
110580   WhereLoopBuilder *pBuilder,
110581   Expr *pExpr,         /* Expression for VALUE in the x=VALUE constraint */
110582   tRowcnt *pnRow       /* Write the revised row estimate here */
110583 ){
110584   Index *p = pBuilder->pNew->u.btree.pIndex;
110585   int nEq = pBuilder->pNew->u.btree.nEq;
110586   UnpackedRecord *pRec = pBuilder->pRec;
110587   u8 aff;                   /* Column affinity */
110588   int rc;                   /* Subfunction return code */
110589   tRowcnt a[2];             /* Statistics */
110590   int bOk;
110591 
110592   assert( nEq>=1 );
110593   assert( nEq<=(p->nKeyCol+1) );
110594   assert( p->aSample!=0 );
110595   assert( p->nSample>0 );
110596   assert( pBuilder->nRecValid<nEq );
110597 
110598   /* If values are not available for all fields of the index to the left
110599   ** of this one, no estimate can be made. Return SQLITE_NOTFOUND. */
110600   if( pBuilder->nRecValid<(nEq-1) ){
110601     return SQLITE_NOTFOUND;
110602   }
110603 
110604   /* This is an optimization only. The call to sqlite3Stat4ProbeSetValue()
110605   ** below would return the same value.  */
110606   if( nEq>p->nKeyCol ){
110607     *pnRow = 1;
110608     return SQLITE_OK;
110609   }
110610 
110611   aff = p->pTable->aCol[p->aiColumn[nEq-1]].affinity;
110612   rc = sqlite3Stat4ProbeSetValue(pParse, p, &pRec, pExpr, aff, nEq-1, &bOk);
110613   pBuilder->pRec = pRec;
110614   if( rc!=SQLITE_OK ) return rc;
110615   if( bOk==0 ) return SQLITE_NOTFOUND;
110616   pBuilder->nRecValid = nEq;
110617 
110618   whereKeyStats(pParse, p, pRec, 0, a);
110619   WHERETRACE(0x10,("equality scan regions: %d\n", (int)a[1]));
110620   *pnRow = a[1];
110621   
110622   return rc;
110623 }
110624 #endif /* SQLITE_ENABLE_STAT3_OR_STAT4 */
110625 
110626 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
110627 /*
110628 ** Estimate the number of rows that will be returned based on
110629 ** an IN constraint where the right-hand side of the IN operator
110630 ** is a list of values.  Example:
110631 **
110632 **        WHERE x IN (1,2,3,4)
110633 **
110634 ** Write the estimated row count into *pnRow and return SQLITE_OK. 
110635 ** If unable to make an estimate, leave *pnRow unchanged and return
110636 ** non-zero.
110637 **
110638 ** This routine can fail if it is unable to load a collating sequence
110639 ** required for string comparison, or if unable to allocate memory
110640 ** for a UTF conversion required for comparison.  The error is stored
110641 ** in the pParse structure.
110642 */
110643 static int whereInScanEst(
110644   Parse *pParse,       /* Parsing & code generating context */
110645   WhereLoopBuilder *pBuilder,
110646   ExprList *pList,     /* The value list on the RHS of "x IN (v1,v2,v3,...)" */
110647   tRowcnt *pnRow       /* Write the revised row estimate here */
110648 ){
110649   Index *p = pBuilder->pNew->u.btree.pIndex;
110650   int nRecValid = pBuilder->nRecValid;
110651   int rc = SQLITE_OK;     /* Subfunction return code */
110652   tRowcnt nEst;           /* Number of rows for a single term */
110653   tRowcnt nRowEst = 0;    /* New estimate of the number of rows */
110654   int i;                  /* Loop counter */
110655 
110656   assert( p->aSample!=0 );
110657   for(i=0; rc==SQLITE_OK && i<pList->nExpr; i++){
110658     nEst = p->aiRowEst[0];
110659     rc = whereEqualScanEst(pParse, pBuilder, pList->a[i].pExpr, &nEst);
110660     nRowEst += nEst;
110661     pBuilder->nRecValid = nRecValid;
110662   }
110663 
110664   if( rc==SQLITE_OK ){
110665     if( nRowEst > p->aiRowEst[0] ) nRowEst = p->aiRowEst[0];
110666     *pnRow = nRowEst;
110667     WHERETRACE(0x10,("IN row estimate: est=%g\n", nRowEst));
110668   }
110669   assert( pBuilder->nRecValid==nRecValid );
110670   return rc;
110671 }
110672 #endif /* SQLITE_ENABLE_STAT3_OR_STAT4 */
110673 
110674 /*
110675 ** Disable a term in the WHERE clause.  Except, do not disable the term
110676 ** if it controls a LEFT OUTER JOIN and it did not originate in the ON
110677 ** or USING clause of that join.
110678 **
110679 ** Consider the term t2.z='ok' in the following queries:
110680 **
110681 **   (1)  SELECT * FROM t1 LEFT JOIN t2 ON t1.a=t2.x WHERE t2.z='ok'
110682 **   (2)  SELECT * FROM t1 LEFT JOIN t2 ON t1.a=t2.x AND t2.z='ok'
110683 **   (3)  SELECT * FROM t1, t2 WHERE t1.a=t2.x AND t2.z='ok'
110684 **
110685 ** The t2.z='ok' is disabled in the in (2) because it originates
110686 ** in the ON clause.  The term is disabled in (3) because it is not part
110687 ** of a LEFT OUTER JOIN.  In (1), the term is not disabled.
110688 **
110689 ** Disabling a term causes that term to not be tested in the inner loop
110690 ** of the join.  Disabling is an optimization.  When terms are satisfied
110691 ** by indices, we disable them to prevent redundant tests in the inner
110692 ** loop.  We would get the correct results if nothing were ever disabled,
110693 ** but joins might run a little slower.  The trick is to disable as much
110694 ** as we can without disabling too much.  If we disabled in (1), we'd get
110695 ** the wrong answer.  See ticket #813.
110696 */
110697 static void disableTerm(WhereLevel *pLevel, WhereTerm *pTerm){
110698   if( pTerm
110699       && (pTerm->wtFlags & TERM_CODED)==0
110700       && (pLevel->iLeftJoin==0 || ExprHasProperty(pTerm->pExpr, EP_FromJoin))
110701       && (pLevel->notReady & pTerm->prereqAll)==0
110702   ){
110703     pTerm->wtFlags |= TERM_CODED;
110704     if( pTerm->iParent>=0 ){
110705       WhereTerm *pOther = &pTerm->pWC->a[pTerm->iParent];
110706       if( (--pOther->nChild)==0 ){
110707         disableTerm(pLevel, pOther);
110708       }
110709     }
110710   }
110711 }
110712 
110713 /*
110714 ** Code an OP_Affinity opcode to apply the column affinity string zAff
110715 ** to the n registers starting at base. 
110716 **
110717 ** As an optimization, SQLITE_AFF_NONE entries (which are no-ops) at the
110718 ** beginning and end of zAff are ignored.  If all entries in zAff are
110719 ** SQLITE_AFF_NONE, then no code gets generated.
110720 **
110721 ** This routine makes its own copy of zAff so that the caller is free
110722 ** to modify zAff after this routine returns.
110723 */
110724 static void codeApplyAffinity(Parse *pParse, int base, int n, char *zAff){
110725   Vdbe *v = pParse->pVdbe;
110726   if( zAff==0 ){
110727     assert( pParse->db->mallocFailed );
110728     return;
110729   }
110730   assert( v!=0 );
110731 
110732   /* Adjust base and n to skip over SQLITE_AFF_NONE entries at the beginning
110733   ** and end of the affinity string.
110734   */
110735   while( n>0 && zAff[0]==SQLITE_AFF_NONE ){
110736     n--;
110737     base++;
110738     zAff++;
110739   }
110740   while( n>1 && zAff[n-1]==SQLITE_AFF_NONE ){
110741     n--;
110742   }
110743 
110744   /* Code the OP_Affinity opcode if there is anything left to do. */
110745   if( n>0 ){
110746     sqlite3VdbeAddOp2(v, OP_Affinity, base, n);
110747     sqlite3VdbeChangeP4(v, -1, zAff, n);
110748     sqlite3ExprCacheAffinityChange(pParse, base, n);
110749   }
110750 }
110751 
110752 
110753 /*
110754 ** Generate code for a single equality term of the WHERE clause.  An equality
110755 ** term can be either X=expr or X IN (...).   pTerm is the term to be 
110756 ** coded.
110757 **
110758 ** The current value for the constraint is left in register iReg.
110759 **
110760 ** For a constraint of the form X=expr, the expression is evaluated and its
110761 ** result is left on the stack.  For constraints of the form X IN (...)
110762 ** this routine sets up a loop that will iterate over all values of X.
110763 */
110764 static int codeEqualityTerm(
110765   Parse *pParse,      /* The parsing context */
110766   WhereTerm *pTerm,   /* The term of the WHERE clause to be coded */
110767   WhereLevel *pLevel, /* The level of the FROM clause we are working on */
110768   int iEq,            /* Index of the equality term within this level */
110769   int bRev,           /* True for reverse-order IN operations */
110770   int iTarget         /* Attempt to leave results in this register */
110771 ){
110772   Expr *pX = pTerm->pExpr;
110773   Vdbe *v = pParse->pVdbe;
110774   int iReg;                  /* Register holding results */
110775 
110776   assert( iTarget>0 );
110777   if( pX->op==TK_EQ ){
110778     iReg = sqlite3ExprCodeTarget(pParse, pX->pRight, iTarget);
110779   }else if( pX->op==TK_ISNULL ){
110780     iReg = iTarget;
110781     sqlite3VdbeAddOp2(v, OP_Null, 0, iReg);
110782 #ifndef SQLITE_OMIT_SUBQUERY
110783   }else{
110784     int eType;
110785     int iTab;
110786     struct InLoop *pIn;
110787     WhereLoop *pLoop = pLevel->pWLoop;
110788 
110789     if( (pLoop->wsFlags & WHERE_VIRTUALTABLE)==0
110790       && pLoop->u.btree.pIndex!=0
110791       && pLoop->u.btree.pIndex->aSortOrder[iEq]
110792     ){
110793       testcase( iEq==0 );
110794       testcase( bRev );
110795       bRev = !bRev;
110796     }
110797     assert( pX->op==TK_IN );
110798     iReg = iTarget;
110799     eType = sqlite3FindInIndex(pParse, pX, 0);
110800     if( eType==IN_INDEX_INDEX_DESC ){
110801       testcase( bRev );
110802       bRev = !bRev;
110803     }
110804     iTab = pX->iTable;
110805     sqlite3VdbeAddOp2(v, bRev ? OP_Last : OP_Rewind, iTab, 0);
110806     assert( (pLoop->wsFlags & WHERE_MULTI_OR)==0 );
110807     pLoop->wsFlags |= WHERE_IN_ABLE;
110808     if( pLevel->u.in.nIn==0 ){
110809       pLevel->addrNxt = sqlite3VdbeMakeLabel(v);
110810     }
110811     pLevel->u.in.nIn++;
110812     pLevel->u.in.aInLoop =
110813        sqlite3DbReallocOrFree(pParse->db, pLevel->u.in.aInLoop,
110814                               sizeof(pLevel->u.in.aInLoop[0])*pLevel->u.in.nIn);
110815     pIn = pLevel->u.in.aInLoop;
110816     if( pIn ){
110817       pIn += pLevel->u.in.nIn - 1;
110818       pIn->iCur = iTab;
110819       if( eType==IN_INDEX_ROWID ){
110820         pIn->addrInTop = sqlite3VdbeAddOp2(v, OP_Rowid, iTab, iReg);
110821       }else{
110822         pIn->addrInTop = sqlite3VdbeAddOp3(v, OP_Column, iTab, 0, iReg);
110823       }
110824       pIn->eEndLoopOp = bRev ? OP_PrevIfOpen : OP_NextIfOpen;
110825       sqlite3VdbeAddOp1(v, OP_IsNull, iReg);
110826     }else{
110827       pLevel->u.in.nIn = 0;
110828     }
110829 #endif
110830   }
110831   disableTerm(pLevel, pTerm);
110832   return iReg;
110833 }
110834 
110835 /*
110836 ** Generate code that will evaluate all == and IN constraints for an
110837 ** index scan.
110838 **
110839 ** For example, consider table t1(a,b,c,d,e,f) with index i1(a,b,c).
110840 ** Suppose the WHERE clause is this:  a==5 AND b IN (1,2,3) AND c>5 AND c<10
110841 ** The index has as many as three equality constraints, but in this
110842 ** example, the third "c" value is an inequality.  So only two 
110843 ** constraints are coded.  This routine will generate code to evaluate
110844 ** a==5 and b IN (1,2,3).  The current values for a and b will be stored
110845 ** in consecutive registers and the index of the first register is returned.
110846 **
110847 ** In the example above nEq==2.  But this subroutine works for any value
110848 ** of nEq including 0.  If nEq==0, this routine is nearly a no-op.
110849 ** The only thing it does is allocate the pLevel->iMem memory cell and
110850 ** compute the affinity string.
110851 **
110852 ** The nExtraReg parameter is 0 or 1.  It is 0 if all WHERE clause constraints
110853 ** are == or IN and are covered by the nEq.  nExtraReg is 1 if there is
110854 ** an inequality constraint (such as the "c>=5 AND c<10" in the example) that
110855 ** occurs after the nEq quality constraints.
110856 **
110857 ** This routine allocates a range of nEq+nExtraReg memory cells and returns
110858 ** the index of the first memory cell in that range. The code that
110859 ** calls this routine will use that memory range to store keys for
110860 ** start and termination conditions of the loop.
110861 ** key value of the loop.  If one or more IN operators appear, then
110862 ** this routine allocates an additional nEq memory cells for internal
110863 ** use.
110864 **
110865 ** Before returning, *pzAff is set to point to a buffer containing a
110866 ** copy of the column affinity string of the index allocated using
110867 ** sqlite3DbMalloc(). Except, entries in the copy of the string associated
110868 ** with equality constraints that use NONE affinity are set to
110869 ** SQLITE_AFF_NONE. This is to deal with SQL such as the following:
110870 **
110871 **   CREATE TABLE t1(a TEXT PRIMARY KEY, b);
110872 **   SELECT ... FROM t1 AS t2, t1 WHERE t1.a = t2.b;
110873 **
110874 ** In the example above, the index on t1(a) has TEXT affinity. But since
110875 ** the right hand side of the equality constraint (t2.b) has NONE affinity,
110876 ** no conversion should be attempted before using a t2.b value as part of
110877 ** a key to search the index. Hence the first byte in the returned affinity
110878 ** string in this example would be set to SQLITE_AFF_NONE.
110879 */
110880 static int codeAllEqualityTerms(
110881   Parse *pParse,        /* Parsing context */
110882   WhereLevel *pLevel,   /* Which nested loop of the FROM we are coding */
110883   int bRev,             /* Reverse the order of IN operators */
110884   int nExtraReg,        /* Number of extra registers to allocate */
110885   char **pzAff          /* OUT: Set to point to affinity string */
110886 ){
110887   u16 nEq;                      /* The number of == or IN constraints to code */
110888   u16 nSkip;                    /* Number of left-most columns to skip */
110889   Vdbe *v = pParse->pVdbe;      /* The vm under construction */
110890   Index *pIdx;                  /* The index being used for this loop */
110891   WhereTerm *pTerm;             /* A single constraint term */
110892   WhereLoop *pLoop;             /* The WhereLoop object */
110893   int j;                        /* Loop counter */
110894   int regBase;                  /* Base register */
110895   int nReg;                     /* Number of registers to allocate */
110896   char *zAff;                   /* Affinity string to return */
110897 
110898   /* This module is only called on query plans that use an index. */
110899   pLoop = pLevel->pWLoop;
110900   assert( (pLoop->wsFlags & WHERE_VIRTUALTABLE)==0 );
110901   nEq = pLoop->u.btree.nEq;
110902   nSkip = pLoop->u.btree.nSkip;
110903   pIdx = pLoop->u.btree.pIndex;
110904   assert( pIdx!=0 );
110905 
110906   /* Figure out how many memory cells we will need then allocate them.
110907   */
110908   regBase = pParse->nMem + 1;
110909   nReg = pLoop->u.btree.nEq + nExtraReg;
110910   pParse->nMem += nReg;
110911 
110912   zAff = sqlite3DbStrDup(pParse->db, sqlite3IndexAffinityStr(v, pIdx));
110913   if( !zAff ){
110914     pParse->db->mallocFailed = 1;
110915   }
110916 
110917   if( nSkip ){
110918     int iIdxCur = pLevel->iIdxCur;
110919     sqlite3VdbeAddOp1(v, (bRev?OP_Last:OP_Rewind), iIdxCur);
110920     VdbeComment((v, "begin skip-scan on %s", pIdx->zName));
110921     j = sqlite3VdbeAddOp0(v, OP_Goto);
110922     pLevel->addrSkip = sqlite3VdbeAddOp4Int(v, (bRev?OP_SeekLt:OP_SeekGt),
110923                             iIdxCur, 0, regBase, nSkip);
110924     sqlite3VdbeJumpHere(v, j);
110925     for(j=0; j<nSkip; j++){
110926       sqlite3VdbeAddOp3(v, OP_Column, iIdxCur, j, regBase+j);
110927       assert( pIdx->aiColumn[j]>=0 );
110928       VdbeComment((v, "%s", pIdx->pTable->aCol[pIdx->aiColumn[j]].zName));
110929     }
110930   }    
110931 
110932   /* Evaluate the equality constraints
110933   */
110934   assert( zAff==0 || (int)strlen(zAff)>=nEq );
110935   for(j=nSkip; j<nEq; j++){
110936     int r1;
110937     pTerm = pLoop->aLTerm[j];
110938     assert( pTerm!=0 );
110939     /* The following testcase is true for indices with redundant columns. 
110940     ** Ex: CREATE INDEX i1 ON t1(a,b,a); SELECT * FROM t1 WHERE a=0 AND b=0; */
110941     testcase( (pTerm->wtFlags & TERM_CODED)!=0 );
110942     testcase( pTerm->wtFlags & TERM_VIRTUAL );
110943     r1 = codeEqualityTerm(pParse, pTerm, pLevel, j, bRev, regBase+j);
110944     if( r1!=regBase+j ){
110945       if( nReg==1 ){
110946         sqlite3ReleaseTempReg(pParse, regBase);
110947         regBase = r1;
110948       }else{
110949         sqlite3VdbeAddOp2(v, OP_SCopy, r1, regBase+j);
110950       }
110951     }
110952     testcase( pTerm->eOperator & WO_ISNULL );
110953     testcase( pTerm->eOperator & WO_IN );
110954     if( (pTerm->eOperator & (WO_ISNULL|WO_IN))==0 ){
110955       Expr *pRight = pTerm->pExpr->pRight;
110956       sqlite3ExprCodeIsNullJump(v, pRight, regBase+j, pLevel->addrBrk);
110957       if( zAff ){
110958         if( sqlite3CompareAffinity(pRight, zAff[j])==SQLITE_AFF_NONE ){
110959           zAff[j] = SQLITE_AFF_NONE;
110960         }
110961         if( sqlite3ExprNeedsNoAffinityChange(pRight, zAff[j]) ){
110962           zAff[j] = SQLITE_AFF_NONE;
110963         }
110964       }
110965     }
110966   }
110967   *pzAff = zAff;
110968   return regBase;
110969 }
110970 
110971 #ifndef SQLITE_OMIT_EXPLAIN
110972 /*
110973 ** This routine is a helper for explainIndexRange() below
110974 **
110975 ** pStr holds the text of an expression that we are building up one term
110976 ** at a time.  This routine adds a new term to the end of the expression.
110977 ** Terms are separated by AND so add the "AND" text for second and subsequent
110978 ** terms only.
110979 */
110980 static void explainAppendTerm(
110981   StrAccum *pStr,             /* The text expression being built */
110982   int iTerm,                  /* Index of this term.  First is zero */
110983   const char *zColumn,        /* Name of the column */
110984   const char *zOp             /* Name of the operator */
110985 ){
110986   if( iTerm ) sqlite3StrAccumAppend(pStr, " AND ", 5);
110987   sqlite3StrAccumAppend(pStr, zColumn, -1);
110988   sqlite3StrAccumAppend(pStr, zOp, 1);
110989   sqlite3StrAccumAppend(pStr, "?", 1);
110990 }
110991 
110992 /*
110993 ** Argument pLevel describes a strategy for scanning table pTab. This 
110994 ** function returns a pointer to a string buffer containing a description
110995 ** of the subset of table rows scanned by the strategy in the form of an
110996 ** SQL expression. Or, if all rows are scanned, NULL is returned.
110997 **
110998 ** For example, if the query:
110999 **
111000 **   SELECT * FROM t1 WHERE a=1 AND b>2;
111001 **
111002 ** is run and there is an index on (a, b), then this function returns a
111003 ** string similar to:
111004 **
111005 **   "a=? AND b>?"
111006 **
111007 ** The returned pointer points to memory obtained from sqlite3DbMalloc().
111008 ** It is the responsibility of the caller to free the buffer when it is
111009 ** no longer required.
111010 */
111011 static char *explainIndexRange(sqlite3 *db, WhereLoop *pLoop, Table *pTab){
111012   Index *pIndex = pLoop->u.btree.pIndex;
111013   u16 nEq = pLoop->u.btree.nEq;
111014   u16 nSkip = pLoop->u.btree.nSkip;
111015   int i, j;
111016   Column *aCol = pTab->aCol;
111017   i16 *aiColumn = pIndex->aiColumn;
111018   StrAccum txt;
111019 
111020   if( nEq==0 && (pLoop->wsFlags & (WHERE_BTM_LIMIT|WHERE_TOP_LIMIT))==0 ){
111021     return 0;
111022   }
111023   sqlite3StrAccumInit(&txt, 0, 0, SQLITE_MAX_LENGTH);
111024   txt.db = db;
111025   sqlite3StrAccumAppend(&txt, " (", 2);
111026   for(i=0; i<nEq; i++){
111027     char *z = (i==pIndex->nKeyCol ) ? "rowid" : aCol[aiColumn[i]].zName;
111028     if( i>=nSkip ){
111029       explainAppendTerm(&txt, i, z, "=");
111030     }else{
111031       if( i ) sqlite3StrAccumAppend(&txt, " AND ", 5);
111032       sqlite3StrAccumAppend(&txt, "ANY(", 4);
111033       sqlite3StrAccumAppend(&txt, z, -1);
111034       sqlite3StrAccumAppend(&txt, ")", 1);
111035     }
111036   }
111037 
111038   j = i;
111039   if( pLoop->wsFlags&WHERE_BTM_LIMIT ){
111040     char *z = (j==pIndex->nKeyCol ) ? "rowid" : aCol[aiColumn[j]].zName;
111041     explainAppendTerm(&txt, i++, z, ">");
111042   }
111043   if( pLoop->wsFlags&WHERE_TOP_LIMIT ){
111044     char *z = (j==pIndex->nKeyCol ) ? "rowid" : aCol[aiColumn[j]].zName;
111045     explainAppendTerm(&txt, i, z, "<");
111046   }
111047   sqlite3StrAccumAppend(&txt, ")", 1);
111048   return sqlite3StrAccumFinish(&txt);
111049 }
111050 
111051 /*
111052 ** This function is a no-op unless currently processing an EXPLAIN QUERY PLAN
111053 ** command. If the query being compiled is an EXPLAIN QUERY PLAN, a single
111054 ** record is added to the output to describe the table scan strategy in 
111055 ** pLevel.
111056 */
111057 static void explainOneScan(
111058   Parse *pParse,                  /* Parse context */
111059   SrcList *pTabList,              /* Table list this loop refers to */
111060   WhereLevel *pLevel,             /* Scan to write OP_Explain opcode for */
111061   int iLevel,                     /* Value for "level" column of output */
111062   int iFrom,                      /* Value for "from" column of output */
111063   u16 wctrlFlags                  /* Flags passed to sqlite3WhereBegin() */
111064 ){
111065 #ifndef SQLITE_DEBUG
111066   if( pParse->explain==2 )
111067 #endif
111068   {
111069     struct SrcList_item *pItem = &pTabList->a[pLevel->iFrom];
111070     Vdbe *v = pParse->pVdbe;      /* VM being constructed */
111071     sqlite3 *db = pParse->db;     /* Database handle */
111072     char *zMsg;                   /* Text to add to EQP output */
111073     int iId = pParse->iSelectId;  /* Select id (left-most output column) */
111074     int isSearch;                 /* True for a SEARCH. False for SCAN. */
111075     WhereLoop *pLoop;             /* The controlling WhereLoop object */
111076     u32 flags;                    /* Flags that describe this loop */
111077 
111078     pLoop = pLevel->pWLoop;
111079     flags = pLoop->wsFlags;
111080     if( (flags&WHERE_MULTI_OR) || (wctrlFlags&WHERE_ONETABLE_ONLY) ) return;
111081 
111082     isSearch = (flags&(WHERE_BTM_LIMIT|WHERE_TOP_LIMIT))!=0
111083             || ((flags&WHERE_VIRTUALTABLE)==0 && (pLoop->u.btree.nEq>0))
111084             || (wctrlFlags&(WHERE_ORDERBY_MIN|WHERE_ORDERBY_MAX));
111085 
111086     zMsg = sqlite3MPrintf(db, "%s", isSearch?"SEARCH":"SCAN");
111087     if( pItem->pSelect ){
111088       zMsg = sqlite3MAppendf(db, zMsg, "%s SUBQUERY %d", zMsg,pItem->iSelectId);
111089     }else{
111090       zMsg = sqlite3MAppendf(db, zMsg, "%s TABLE %s", zMsg, pItem->zName);
111091     }
111092 
111093     if( pItem->zAlias ){
111094       zMsg = sqlite3MAppendf(db, zMsg, "%s AS %s", zMsg, pItem->zAlias);
111095     }
111096     if( (flags & (WHERE_IPK|WHERE_VIRTUALTABLE))==0
111097      && ALWAYS(pLoop->u.btree.pIndex!=0)
111098     ){
111099       char *zWhere = explainIndexRange(db, pLoop, pItem->pTab);
111100       zMsg = sqlite3MAppendf(db, zMsg,
111101                ((flags & WHERE_AUTO_INDEX) ? 
111102                    "%s USING AUTOMATIC %sINDEX%.0s%s" :
111103                    "%s USING %sINDEX %s%s"), 
111104                zMsg, ((flags & WHERE_IDX_ONLY) ? "COVERING " : ""),
111105                pLoop->u.btree.pIndex->zName, zWhere);
111106       sqlite3DbFree(db, zWhere);
111107     }else if( (flags & WHERE_IPK)!=0 && (flags & WHERE_CONSTRAINT)!=0 ){
111108       zMsg = sqlite3MAppendf(db, zMsg, "%s USING INTEGER PRIMARY KEY", zMsg);
111109 
111110       if( flags&(WHERE_COLUMN_EQ|WHERE_COLUMN_IN) ){
111111         zMsg = sqlite3MAppendf(db, zMsg, "%s (rowid=?)", zMsg);
111112       }else if( (flags&WHERE_BOTH_LIMIT)==WHERE_BOTH_LIMIT ){
111113         zMsg = sqlite3MAppendf(db, zMsg, "%s (rowid>? AND rowid<?)", zMsg);
111114       }else if( flags&WHERE_BTM_LIMIT ){
111115         zMsg = sqlite3MAppendf(db, zMsg, "%s (rowid>?)", zMsg);
111116       }else if( ALWAYS(flags&WHERE_TOP_LIMIT) ){
111117         zMsg = sqlite3MAppendf(db, zMsg, "%s (rowid<?)", zMsg);
111118       }
111119     }
111120 #ifndef SQLITE_OMIT_VIRTUALTABLE
111121     else if( (flags & WHERE_VIRTUALTABLE)!=0 ){
111122       zMsg = sqlite3MAppendf(db, zMsg, "%s VIRTUAL TABLE INDEX %d:%s", zMsg,
111123                   pLoop->u.vtab.idxNum, pLoop->u.vtab.idxStr);
111124     }
111125 #endif
111126     zMsg = sqlite3MAppendf(db, zMsg, "%s", zMsg);
111127     sqlite3VdbeAddOp4(v, OP_Explain, iId, iLevel, iFrom, zMsg, P4_DYNAMIC);
111128   }
111129 }
111130 #else
111131 # define explainOneScan(u,v,w,x,y,z)
111132 #endif /* SQLITE_OMIT_EXPLAIN */
111133 
111134 
111135 /*
111136 ** Generate code for the start of the iLevel-th loop in the WHERE clause
111137 ** implementation described by pWInfo.
111138 */
111139 static Bitmask codeOneLoopStart(
111140   WhereInfo *pWInfo,   /* Complete information about the WHERE clause */
111141   int iLevel,          /* Which level of pWInfo->a[] should be coded */
111142   Bitmask notReady     /* Which tables are currently available */
111143 ){
111144   int j, k;            /* Loop counters */
111145   int iCur;            /* The VDBE cursor for the table */
111146   int addrNxt;         /* Where to jump to continue with the next IN case */
111147   int omitTable;       /* True if we use the index only */
111148   int bRev;            /* True if we need to scan in reverse order */
111149   WhereLevel *pLevel;  /* The where level to be coded */
111150   WhereLoop *pLoop;    /* The WhereLoop object being coded */
111151   WhereClause *pWC;    /* Decomposition of the entire WHERE clause */
111152   WhereTerm *pTerm;               /* A WHERE clause term */
111153   Parse *pParse;                  /* Parsing context */
111154   sqlite3 *db;                    /* Database connection */
111155   Vdbe *v;                        /* The prepared stmt under constructions */
111156   struct SrcList_item *pTabItem;  /* FROM clause term being coded */
111157   int addrBrk;                    /* Jump here to break out of the loop */
111158   int addrCont;                   /* Jump here to continue with next cycle */
111159   int iRowidReg = 0;        /* Rowid is stored in this register, if not zero */
111160   int iReleaseReg = 0;      /* Temp register to free before returning */
111161 
111162   pParse = pWInfo->pParse;
111163   v = pParse->pVdbe;
111164   pWC = &pWInfo->sWC;
111165   db = pParse->db;
111166   pLevel = &pWInfo->a[iLevel];
111167   pLoop = pLevel->pWLoop;
111168   pTabItem = &pWInfo->pTabList->a[pLevel->iFrom];
111169   iCur = pTabItem->iCursor;
111170   pLevel->notReady = notReady & ~getMask(&pWInfo->sMaskSet, iCur);
111171   bRev = (pWInfo->revMask>>iLevel)&1;
111172   omitTable = (pLoop->wsFlags & WHERE_IDX_ONLY)!=0 
111173            && (pWInfo->wctrlFlags & WHERE_FORCE_TABLE)==0;
111174   VdbeModuleComment((v, "Begin WHERE-loop%d: %s",iLevel,pTabItem->pTab->zName));
111175 
111176   /* Create labels for the "break" and "continue" instructions
111177   ** for the current loop.  Jump to addrBrk to break out of a loop.
111178   ** Jump to cont to go immediately to the next iteration of the
111179   ** loop.
111180   **
111181   ** When there is an IN operator, we also have a "addrNxt" label that
111182   ** means to continue with the next IN value combination.  When
111183   ** there are no IN operators in the constraints, the "addrNxt" label
111184   ** is the same as "addrBrk".
111185   */
111186   addrBrk = pLevel->addrBrk = pLevel->addrNxt = sqlite3VdbeMakeLabel(v);
111187   addrCont = pLevel->addrCont = sqlite3VdbeMakeLabel(v);
111188 
111189   /* If this is the right table of a LEFT OUTER JOIN, allocate and
111190   ** initialize a memory cell that records if this table matches any
111191   ** row of the left table of the join.
111192   */
111193   if( pLevel->iFrom>0 && (pTabItem[0].jointype & JT_LEFT)!=0 ){
111194     pLevel->iLeftJoin = ++pParse->nMem;
111195     sqlite3VdbeAddOp2(v, OP_Integer, 0, pLevel->iLeftJoin);
111196     VdbeComment((v, "init LEFT JOIN no-match flag"));
111197   }
111198 
111199   /* Special case of a FROM clause subquery implemented as a co-routine */
111200   if( pTabItem->viaCoroutine ){
111201     int regYield = pTabItem->regReturn;
111202     sqlite3VdbeAddOp2(v, OP_Integer, pTabItem->addrFillSub-1, regYield);
111203     pLevel->p2 =  sqlite3VdbeAddOp1(v, OP_Yield, regYield);
111204     VdbeComment((v, "next row of co-routine %s", pTabItem->pTab->zName));
111205     sqlite3VdbeAddOp2(v, OP_If, regYield+1, addrBrk);
111206     pLevel->op = OP_Goto;
111207   }else
111208 
111209 #ifndef SQLITE_OMIT_VIRTUALTABLE
111210   if(  (pLoop->wsFlags & WHERE_VIRTUALTABLE)!=0 ){
111211     /* Case 1:  The table is a virtual-table.  Use the VFilter and VNext
111212     **          to access the data.
111213     */
111214     int iReg;   /* P3 Value for OP_VFilter */
111215     int addrNotFound;
111216     int nConstraint = pLoop->nLTerm;
111217 
111218     sqlite3ExprCachePush(pParse);
111219     iReg = sqlite3GetTempRange(pParse, nConstraint+2);
111220     addrNotFound = pLevel->addrBrk;
111221     for(j=0; j<nConstraint; j++){
111222       int iTarget = iReg+j+2;
111223       pTerm = pLoop->aLTerm[j];
111224       if( pTerm==0 ) continue;
111225       if( pTerm->eOperator & WO_IN ){
111226         codeEqualityTerm(pParse, pTerm, pLevel, j, bRev, iTarget);
111227         addrNotFound = pLevel->addrNxt;
111228       }else{
111229         sqlite3ExprCode(pParse, pTerm->pExpr->pRight, iTarget);
111230       }
111231     }
111232     sqlite3VdbeAddOp2(v, OP_Integer, pLoop->u.vtab.idxNum, iReg);
111233     sqlite3VdbeAddOp2(v, OP_Integer, nConstraint, iReg+1);
111234     sqlite3VdbeAddOp4(v, OP_VFilter, iCur, addrNotFound, iReg,
111235                       pLoop->u.vtab.idxStr,
111236                       pLoop->u.vtab.needFree ? P4_MPRINTF : P4_STATIC);
111237     pLoop->u.vtab.needFree = 0;
111238     for(j=0; j<nConstraint && j<16; j++){
111239       if( (pLoop->u.vtab.omitMask>>j)&1 ){
111240         disableTerm(pLevel, pLoop->aLTerm[j]);
111241       }
111242     }
111243     pLevel->op = OP_VNext;
111244     pLevel->p1 = iCur;
111245     pLevel->p2 = sqlite3VdbeCurrentAddr(v);
111246     sqlite3ReleaseTempRange(pParse, iReg, nConstraint+2);
111247     sqlite3ExprCachePop(pParse, 1);
111248   }else
111249 #endif /* SQLITE_OMIT_VIRTUALTABLE */
111250 
111251   if( (pLoop->wsFlags & WHERE_IPK)!=0
111252    && (pLoop->wsFlags & (WHERE_COLUMN_IN|WHERE_COLUMN_EQ))!=0
111253   ){
111254     /* Case 2:  We can directly reference a single row using an
111255     **          equality comparison against the ROWID field.  Or
111256     **          we reference multiple rows using a "rowid IN (...)"
111257     **          construct.
111258     */
111259     assert( pLoop->u.btree.nEq==1 );
111260     iReleaseReg = sqlite3GetTempReg(pParse);
111261     pTerm = pLoop->aLTerm[0];
111262     assert( pTerm!=0 );
111263     assert( pTerm->pExpr!=0 );
111264     assert( omitTable==0 );
111265     testcase( pTerm->wtFlags & TERM_VIRTUAL );
111266     iRowidReg = codeEqualityTerm(pParse, pTerm, pLevel, 0, bRev, iReleaseReg);
111267     addrNxt = pLevel->addrNxt;
111268     sqlite3VdbeAddOp2(v, OP_MustBeInt, iRowidReg, addrNxt);
111269     sqlite3VdbeAddOp3(v, OP_NotExists, iCur, addrNxt, iRowidReg);
111270     sqlite3ExprCacheAffinityChange(pParse, iRowidReg, 1);
111271     sqlite3ExprCacheStore(pParse, iCur, -1, iRowidReg);
111272     VdbeComment((v, "pk"));
111273     pLevel->op = OP_Noop;
111274   }else if( (pLoop->wsFlags & WHERE_IPK)!=0
111275          && (pLoop->wsFlags & WHERE_COLUMN_RANGE)!=0
111276   ){
111277     /* Case 3:  We have an inequality comparison against the ROWID field.
111278     */
111279     int testOp = OP_Noop;
111280     int start;
111281     int memEndValue = 0;
111282     WhereTerm *pStart, *pEnd;
111283 
111284     assert( omitTable==0 );
111285     j = 0;
111286     pStart = pEnd = 0;
111287     if( pLoop->wsFlags & WHERE_BTM_LIMIT ) pStart = pLoop->aLTerm[j++];
111288     if( pLoop->wsFlags & WHERE_TOP_LIMIT ) pEnd = pLoop->aLTerm[j++];
111289     assert( pStart!=0 || pEnd!=0 );
111290     if( bRev ){
111291       pTerm = pStart;
111292       pStart = pEnd;
111293       pEnd = pTerm;
111294     }
111295     if( pStart ){
111296       Expr *pX;             /* The expression that defines the start bound */
111297       int r1, rTemp;        /* Registers for holding the start boundary */
111298 
111299       /* The following constant maps TK_xx codes into corresponding 
111300       ** seek opcodes.  It depends on a particular ordering of TK_xx
111301       */
111302       const u8 aMoveOp[] = {
111303            /* TK_GT */  OP_SeekGt,
111304            /* TK_LE */  OP_SeekLe,
111305            /* TK_LT */  OP_SeekLt,
111306            /* TK_GE */  OP_SeekGe
111307       };
111308       assert( TK_LE==TK_GT+1 );      /* Make sure the ordering.. */
111309       assert( TK_LT==TK_GT+2 );      /*  ... of the TK_xx values... */
111310       assert( TK_GE==TK_GT+3 );      /*  ... is correcct. */
111311 
111312       assert( (pStart->wtFlags & TERM_VNULL)==0 );
111313       testcase( pStart->wtFlags & TERM_VIRTUAL );
111314       pX = pStart->pExpr;
111315       assert( pX!=0 );
111316       testcase( pStart->leftCursor!=iCur ); /* transitive constraints */
111317       r1 = sqlite3ExprCodeTemp(pParse, pX->pRight, &rTemp);
111318       sqlite3VdbeAddOp3(v, aMoveOp[pX->op-TK_GT], iCur, addrBrk, r1);
111319       VdbeComment((v, "pk"));
111320       sqlite3ExprCacheAffinityChange(pParse, r1, 1);
111321       sqlite3ReleaseTempReg(pParse, rTemp);
111322       disableTerm(pLevel, pStart);
111323     }else{
111324       sqlite3VdbeAddOp2(v, bRev ? OP_Last : OP_Rewind, iCur, addrBrk);
111325     }
111326     if( pEnd ){
111327       Expr *pX;
111328       pX = pEnd->pExpr;
111329       assert( pX!=0 );
111330       assert( (pEnd->wtFlags & TERM_VNULL)==0 );
111331       testcase( pEnd->leftCursor!=iCur ); /* Transitive constraints */
111332       testcase( pEnd->wtFlags & TERM_VIRTUAL );
111333       memEndValue = ++pParse->nMem;
111334       sqlite3ExprCode(pParse, pX->pRight, memEndValue);
111335       if( pX->op==TK_LT || pX->op==TK_GT ){
111336         testOp = bRev ? OP_Le : OP_Ge;
111337       }else{
111338         testOp = bRev ? OP_Lt : OP_Gt;
111339       }
111340       disableTerm(pLevel, pEnd);
111341     }
111342     start = sqlite3VdbeCurrentAddr(v);
111343     pLevel->op = bRev ? OP_Prev : OP_Next;
111344     pLevel->p1 = iCur;
111345     pLevel->p2 = start;
111346     assert( pLevel->p5==0 );
111347     if( testOp!=OP_Noop ){
111348       iRowidReg = iReleaseReg = sqlite3GetTempReg(pParse);
111349       sqlite3VdbeAddOp2(v, OP_Rowid, iCur, iRowidReg);
111350       sqlite3ExprCacheStore(pParse, iCur, -1, iRowidReg);
111351       sqlite3VdbeAddOp3(v, testOp, memEndValue, addrBrk, iRowidReg);
111352       sqlite3VdbeChangeP5(v, SQLITE_AFF_NUMERIC | SQLITE_JUMPIFNULL);
111353     }
111354   }else if( pLoop->wsFlags & WHERE_INDEXED ){
111355     /* Case 4: A scan using an index.
111356     **
111357     **         The WHERE clause may contain zero or more equality 
111358     **         terms ("==" or "IN" operators) that refer to the N
111359     **         left-most columns of the index. It may also contain
111360     **         inequality constraints (>, <, >= or <=) on the indexed
111361     **         column that immediately follows the N equalities. Only 
111362     **         the right-most column can be an inequality - the rest must
111363     **         use the "==" and "IN" operators. For example, if the 
111364     **         index is on (x,y,z), then the following clauses are all 
111365     **         optimized:
111366     **
111367     **            x=5
111368     **            x=5 AND y=10
111369     **            x=5 AND y<10
111370     **            x=5 AND y>5 AND y<10
111371     **            x=5 AND y=5 AND z<=10
111372     **
111373     **         The z<10 term of the following cannot be used, only
111374     **         the x=5 term:
111375     **
111376     **            x=5 AND z<10
111377     **
111378     **         N may be zero if there are inequality constraints.
111379     **         If there are no inequality constraints, then N is at
111380     **         least one.
111381     **
111382     **         This case is also used when there are no WHERE clause
111383     **         constraints but an index is selected anyway, in order
111384     **         to force the output order to conform to an ORDER BY.
111385     */  
111386     static const u8 aStartOp[] = {
111387       0,
111388       0,
111389       OP_Rewind,           /* 2: (!start_constraints && startEq &&  !bRev) */
111390       OP_Last,             /* 3: (!start_constraints && startEq &&   bRev) */
111391       OP_SeekGt,           /* 4: (start_constraints  && !startEq && !bRev) */
111392       OP_SeekLt,           /* 5: (start_constraints  && !startEq &&  bRev) */
111393       OP_SeekGe,           /* 6: (start_constraints  &&  startEq && !bRev) */
111394       OP_SeekLe            /* 7: (start_constraints  &&  startEq &&  bRev) */
111395     };
111396     static const u8 aEndOp[] = {
111397       OP_Noop,             /* 0: (!end_constraints) */
111398       OP_IdxGE,            /* 1: (end_constraints && !bRev) */
111399       OP_IdxLT             /* 2: (end_constraints && bRev) */
111400     };
111401     u16 nEq = pLoop->u.btree.nEq;     /* Number of == or IN terms */
111402     int isMinQuery = 0;          /* If this is an optimized SELECT min(x).. */
111403     int regBase;                 /* Base register holding constraint values */
111404     int r1;                      /* Temp register */
111405     WhereTerm *pRangeStart = 0;  /* Inequality constraint at range start */
111406     WhereTerm *pRangeEnd = 0;    /* Inequality constraint at range end */
111407     int startEq;                 /* True if range start uses ==, >= or <= */
111408     int endEq;                   /* True if range end uses ==, >= or <= */
111409     int start_constraints;       /* Start of range is constrained */
111410     int nConstraint;             /* Number of constraint terms */
111411     Index *pIdx;                 /* The index we will be using */
111412     int iIdxCur;                 /* The VDBE cursor for the index */
111413     int nExtraReg = 0;           /* Number of extra registers needed */
111414     int op;                      /* Instruction opcode */
111415     char *zStartAff;             /* Affinity for start of range constraint */
111416     char cEndAff = 0;            /* Affinity for end of range constraint */
111417 
111418     pIdx = pLoop->u.btree.pIndex;
111419     iIdxCur = pLevel->iIdxCur;
111420     assert( nEq>=pLoop->u.btree.nSkip );
111421 
111422     /* If this loop satisfies a sort order (pOrderBy) request that 
111423     ** was passed to this function to implement a "SELECT min(x) ..." 
111424     ** query, then the caller will only allow the loop to run for
111425     ** a single iteration. This means that the first row returned
111426     ** should not have a NULL value stored in 'x'. If column 'x' is
111427     ** the first one after the nEq equality constraints in the index,
111428     ** this requires some special handling.
111429     */
111430     if( (pWInfo->wctrlFlags&WHERE_ORDERBY_MIN)!=0
111431      && (pWInfo->bOBSat!=0)
111432      && (pIdx->nKeyCol>nEq)
111433     ){
111434       assert( pLoop->u.btree.nSkip==0 );
111435       isMinQuery = 1;
111436       nExtraReg = 1;
111437     }
111438 
111439     /* Find any inequality constraint terms for the start and end 
111440     ** of the range. 
111441     */
111442     j = nEq;
111443     if( pLoop->wsFlags & WHERE_BTM_LIMIT ){
111444       pRangeStart = pLoop->aLTerm[j++];
111445       nExtraReg = 1;
111446     }
111447     if( pLoop->wsFlags & WHERE_TOP_LIMIT ){
111448       pRangeEnd = pLoop->aLTerm[j++];
111449       nExtraReg = 1;
111450     }
111451 
111452     /* Generate code to evaluate all constraint terms using == or IN
111453     ** and store the values of those terms in an array of registers
111454     ** starting at regBase.
111455     */
111456     regBase = codeAllEqualityTerms(pParse,pLevel,bRev,nExtraReg,&zStartAff);
111457     assert( zStartAff==0 || sqlite3Strlen30(zStartAff)>=nEq );
111458     if( zStartAff ) cEndAff = zStartAff[nEq];
111459     addrNxt = pLevel->addrNxt;
111460 
111461     /* If we are doing a reverse order scan on an ascending index, or
111462     ** a forward order scan on a descending index, interchange the 
111463     ** start and end terms (pRangeStart and pRangeEnd).
111464     */
111465     if( (nEq<pIdx->nKeyCol && bRev==(pIdx->aSortOrder[nEq]==SQLITE_SO_ASC))
111466      || (bRev && pIdx->nKeyCol==nEq)
111467     ){
111468       SWAP(WhereTerm *, pRangeEnd, pRangeStart);
111469     }
111470 
111471     testcase( pRangeStart && (pRangeStart->eOperator & WO_LE)!=0 );
111472     testcase( pRangeStart && (pRangeStart->eOperator & WO_GE)!=0 );
111473     testcase( pRangeEnd && (pRangeEnd->eOperator & WO_LE)!=0 );
111474     testcase( pRangeEnd && (pRangeEnd->eOperator & WO_GE)!=0 );
111475     startEq = !pRangeStart || pRangeStart->eOperator & (WO_LE|WO_GE);
111476     endEq =   !pRangeEnd || pRangeEnd->eOperator & (WO_LE|WO_GE);
111477     start_constraints = pRangeStart || nEq>0;
111478 
111479     /* Seek the index cursor to the start of the range. */
111480     nConstraint = nEq;
111481     if( pRangeStart ){
111482       Expr *pRight = pRangeStart->pExpr->pRight;
111483       sqlite3ExprCode(pParse, pRight, regBase+nEq);
111484       if( (pRangeStart->wtFlags & TERM_VNULL)==0 ){
111485         sqlite3ExprCodeIsNullJump(v, pRight, regBase+nEq, addrNxt);
111486       }
111487       if( zStartAff ){
111488         if( sqlite3CompareAffinity(pRight, zStartAff[nEq])==SQLITE_AFF_NONE){
111489           /* Since the comparison is to be performed with no conversions
111490           ** applied to the operands, set the affinity to apply to pRight to 
111491           ** SQLITE_AFF_NONE.  */
111492           zStartAff[nEq] = SQLITE_AFF_NONE;
111493         }
111494         if( sqlite3ExprNeedsNoAffinityChange(pRight, zStartAff[nEq]) ){
111495           zStartAff[nEq] = SQLITE_AFF_NONE;
111496         }
111497       }  
111498       nConstraint++;
111499       testcase( pRangeStart->wtFlags & TERM_VIRTUAL );
111500     }else if( isMinQuery ){
111501       sqlite3VdbeAddOp2(v, OP_Null, 0, regBase+nEq);
111502       nConstraint++;
111503       startEq = 0;
111504       start_constraints = 1;
111505     }
111506     codeApplyAffinity(pParse, regBase, nConstraint, zStartAff);
111507     op = aStartOp[(start_constraints<<2) + (startEq<<1) + bRev];
111508     assert( op!=0 );
111509     testcase( op==OP_Rewind );
111510     testcase( op==OP_Last );
111511     testcase( op==OP_SeekGt );
111512     testcase( op==OP_SeekGe );
111513     testcase( op==OP_SeekLe );
111514     testcase( op==OP_SeekLt );
111515     sqlite3VdbeAddOp4Int(v, op, iIdxCur, addrNxt, regBase, nConstraint);
111516 
111517     /* Load the value for the inequality constraint at the end of the
111518     ** range (if any).
111519     */
111520     nConstraint = nEq;
111521     if( pRangeEnd ){
111522       Expr *pRight = pRangeEnd->pExpr->pRight;
111523       sqlite3ExprCacheRemove(pParse, regBase+nEq, 1);
111524       sqlite3ExprCode(pParse, pRight, regBase+nEq);
111525       if( (pRangeEnd->wtFlags & TERM_VNULL)==0 ){
111526         sqlite3ExprCodeIsNullJump(v, pRight, regBase+nEq, addrNxt);
111527       }
111528       if( sqlite3CompareAffinity(pRight, cEndAff)!=SQLITE_AFF_NONE
111529        && !sqlite3ExprNeedsNoAffinityChange(pRight, cEndAff)
111530       ){
111531         codeApplyAffinity(pParse, regBase+nEq, 1, &cEndAff);
111532       }
111533       nConstraint++;
111534       testcase( pRangeEnd->wtFlags & TERM_VIRTUAL );
111535     }
111536     sqlite3DbFree(db, zStartAff);
111537 
111538     /* Top of the loop body */
111539     pLevel->p2 = sqlite3VdbeCurrentAddr(v);
111540 
111541     /* Check if the index cursor is past the end of the range. */
111542     op = aEndOp[(pRangeEnd || nEq) * (1 + bRev)];
111543     testcase( op==OP_Noop );
111544     testcase( op==OP_IdxGE );
111545     testcase( op==OP_IdxLT );
111546     if( op!=OP_Noop ){
111547       sqlite3VdbeAddOp4Int(v, op, iIdxCur, addrNxt, regBase, nConstraint);
111548       sqlite3VdbeChangeP5(v, endEq!=bRev ?1:0);
111549     }
111550 
111551     /* If there are inequality constraints, check that the value
111552     ** of the table column that the inequality contrains is not NULL.
111553     ** If it is, jump to the next iteration of the loop.
111554     */
111555     r1 = sqlite3GetTempReg(pParse);
111556     testcase( pLoop->wsFlags & WHERE_BTM_LIMIT );
111557     testcase( pLoop->wsFlags & WHERE_TOP_LIMIT );
111558     if( (pLoop->wsFlags & (WHERE_BTM_LIMIT|WHERE_TOP_LIMIT))!=0 
111559      && (j = pIdx->aiColumn[nEq])>=0 
111560      && pIdx->pTable->aCol[j].notNull==0 
111561      && (nEq || (pLoop->wsFlags & WHERE_BTM_LIMIT)==0)
111562     ){
111563       sqlite3VdbeAddOp3(v, OP_Column, iIdxCur, nEq, r1);
111564       VdbeComment((v, "%s", pIdx->pTable->aCol[j].zName));
111565       sqlite3VdbeAddOp2(v, OP_IsNull, r1, addrCont);
111566     }
111567     sqlite3ReleaseTempReg(pParse, r1);
111568 
111569     /* Seek the table cursor, if required */
111570     disableTerm(pLevel, pRangeStart);
111571     disableTerm(pLevel, pRangeEnd);
111572     if( omitTable ){
111573       /* pIdx is a covering index.  No need to access the main table. */
111574     }else if( HasRowid(pIdx->pTable) ){
111575       iRowidReg = iReleaseReg = sqlite3GetTempReg(pParse);
111576       sqlite3VdbeAddOp2(v, OP_IdxRowid, iIdxCur, iRowidReg);
111577       sqlite3ExprCacheStore(pParse, iCur, -1, iRowidReg);
111578       sqlite3VdbeAddOp2(v, OP_Seek, iCur, iRowidReg);  /* Deferred seek */
111579     }else{
111580       Index *pPk = sqlite3PrimaryKeyIndex(pIdx->pTable);
111581       iRowidReg = sqlite3GetTempRange(pParse, pPk->nKeyCol);
111582       for(j=0; j<pPk->nKeyCol; j++){
111583         k = sqlite3ColumnOfIndex(pIdx, pPk->aiColumn[j]);
111584         sqlite3VdbeAddOp3(v, OP_Column, iIdxCur, k, iRowidReg+j);
111585       }
111586       sqlite3VdbeAddOp4Int(v, OP_NotFound, iCur, addrCont,
111587                            iRowidReg, pPk->nKeyCol);
111588     }
111589 
111590     /* Record the instruction used to terminate the loop. Disable 
111591     ** WHERE clause terms made redundant by the index range scan.
111592     */
111593     if( pLoop->wsFlags & WHERE_ONEROW ){
111594       pLevel->op = OP_Noop;
111595     }else if( bRev ){
111596       pLevel->op = OP_Prev;
111597     }else{
111598       pLevel->op = OP_Next;
111599     }
111600     pLevel->p1 = iIdxCur;
111601     if( (pLoop->wsFlags & WHERE_CONSTRAINT)==0 ){
111602       pLevel->p5 = SQLITE_STMTSTATUS_FULLSCAN_STEP;
111603     }else{
111604       assert( pLevel->p5==0 );
111605     }
111606   }else
111607 
111608 #ifndef SQLITE_OMIT_OR_OPTIMIZATION
111609   if( pLoop->wsFlags & WHERE_MULTI_OR ){
111610     /* Case 5:  Two or more separately indexed terms connected by OR
111611     **
111612     ** Example:
111613     **
111614     **   CREATE TABLE t1(a,b,c,d);
111615     **   CREATE INDEX i1 ON t1(a);
111616     **   CREATE INDEX i2 ON t1(b);
111617     **   CREATE INDEX i3 ON t1(c);
111618     **
111619     **   SELECT * FROM t1 WHERE a=5 OR b=7 OR (c=11 AND d=13)
111620     **
111621     ** In the example, there are three indexed terms connected by OR.
111622     ** The top of the loop looks like this:
111623     **
111624     **          Null       1                # Zero the rowset in reg 1
111625     **
111626     ** Then, for each indexed term, the following. The arguments to
111627     ** RowSetTest are such that the rowid of the current row is inserted
111628     ** into the RowSet. If it is already present, control skips the
111629     ** Gosub opcode and jumps straight to the code generated by WhereEnd().
111630     **
111631     **        sqlite3WhereBegin(<term>)
111632     **          RowSetTest                  # Insert rowid into rowset
111633     **          Gosub      2 A
111634     **        sqlite3WhereEnd()
111635     **
111636     ** Following the above, code to terminate the loop. Label A, the target
111637     ** of the Gosub above, jumps to the instruction right after the Goto.
111638     **
111639     **          Null       1                # Zero the rowset in reg 1
111640     **          Goto       B                # The loop is finished.
111641     **
111642     **       A: <loop body>                 # Return data, whatever.
111643     **
111644     **          Return     2                # Jump back to the Gosub
111645     **
111646     **       B: <after the loop>
111647     **
111648     */
111649     WhereClause *pOrWc;    /* The OR-clause broken out into subterms */
111650     SrcList *pOrTab;       /* Shortened table list or OR-clause generation */
111651     Index *pCov = 0;             /* Potential covering index (or NULL) */
111652     int iCovCur = pParse->nTab++;  /* Cursor used for index scans (if any) */
111653 
111654     int regReturn = ++pParse->nMem;           /* Register used with OP_Gosub */
111655     int regRowset = 0;                        /* Register for RowSet object */
111656     int regRowid = 0;                         /* Register holding rowid */
111657     int iLoopBody = sqlite3VdbeMakeLabel(v);  /* Start of loop body */
111658     int iRetInit;                             /* Address of regReturn init */
111659     int untestedTerms = 0;             /* Some terms not completely tested */
111660     int ii;                            /* Loop counter */
111661     Expr *pAndExpr = 0;                /* An ".. AND (...)" expression */
111662    
111663     pTerm = pLoop->aLTerm[0];
111664     assert( pTerm!=0 );
111665     assert( pTerm->eOperator & WO_OR );
111666     assert( (pTerm->wtFlags & TERM_ORINFO)!=0 );
111667     pOrWc = &pTerm->u.pOrInfo->wc;
111668     pLevel->op = OP_Return;
111669     pLevel->p1 = regReturn;
111670 
111671     /* Set up a new SrcList in pOrTab containing the table being scanned
111672     ** by this loop in the a[0] slot and all notReady tables in a[1..] slots.
111673     ** This becomes the SrcList in the recursive call to sqlite3WhereBegin().
111674     */
111675     if( pWInfo->nLevel>1 ){
111676       int nNotReady;                 /* The number of notReady tables */
111677       struct SrcList_item *origSrc;     /* Original list of tables */
111678       nNotReady = pWInfo->nLevel - iLevel - 1;
111679       pOrTab = sqlite3StackAllocRaw(db,
111680                             sizeof(*pOrTab)+ nNotReady*sizeof(pOrTab->a[0]));
111681       if( pOrTab==0 ) return notReady;
111682       pOrTab->nAlloc = (u8)(nNotReady + 1);
111683       pOrTab->nSrc = pOrTab->nAlloc;
111684       memcpy(pOrTab->a, pTabItem, sizeof(*pTabItem));
111685       origSrc = pWInfo->pTabList->a;
111686       for(k=1; k<=nNotReady; k++){
111687         memcpy(&pOrTab->a[k], &origSrc[pLevel[k].iFrom], sizeof(pOrTab->a[k]));
111688       }
111689     }else{
111690       pOrTab = pWInfo->pTabList;
111691     }
111692 
111693     /* Initialize the rowset register to contain NULL. An SQL NULL is 
111694     ** equivalent to an empty rowset.
111695     **
111696     ** Also initialize regReturn to contain the address of the instruction 
111697     ** immediately following the OP_Return at the bottom of the loop. This
111698     ** is required in a few obscure LEFT JOIN cases where control jumps
111699     ** over the top of the loop into the body of it. In this case the 
111700     ** correct response for the end-of-loop code (the OP_Return) is to 
111701     ** fall through to the next instruction, just as an OP_Next does if
111702     ** called on an uninitialized cursor.
111703     */
111704     if( (pWInfo->wctrlFlags & WHERE_DUPLICATES_OK)==0 ){
111705       regRowset = ++pParse->nMem;
111706       regRowid = ++pParse->nMem;
111707       sqlite3VdbeAddOp2(v, OP_Null, 0, regRowset);
111708     }
111709     iRetInit = sqlite3VdbeAddOp2(v, OP_Integer, 0, regReturn);
111710 
111711     /* If the original WHERE clause is z of the form:  (x1 OR x2 OR ...) AND y
111712     ** Then for every term xN, evaluate as the subexpression: xN AND z
111713     ** That way, terms in y that are factored into the disjunction will
111714     ** be picked up by the recursive calls to sqlite3WhereBegin() below.
111715     **
111716     ** Actually, each subexpression is converted to "xN AND w" where w is
111717     ** the "interesting" terms of z - terms that did not originate in the
111718     ** ON or USING clause of a LEFT JOIN, and terms that are usable as 
111719     ** indices.
111720     **
111721     ** This optimization also only applies if the (x1 OR x2 OR ...) term
111722     ** is not contained in the ON clause of a LEFT JOIN.
111723     ** See ticket http://www.sqlite.org/src/info/f2369304e4
111724     */
111725     if( pWC->nTerm>1 ){
111726       int iTerm;
111727       for(iTerm=0; iTerm<pWC->nTerm; iTerm++){
111728         Expr *pExpr = pWC->a[iTerm].pExpr;
111729         if( &pWC->a[iTerm] == pTerm ) continue;
111730         if( ExprHasProperty(pExpr, EP_FromJoin) ) continue;
111731         if( pWC->a[iTerm].wtFlags & (TERM_ORINFO) ) continue;
111732         if( (pWC->a[iTerm].eOperator & WO_ALL)==0 ) continue;
111733         pExpr = sqlite3ExprDup(db, pExpr, 0);
111734         pAndExpr = sqlite3ExprAnd(db, pAndExpr, pExpr);
111735       }
111736       if( pAndExpr ){
111737         pAndExpr = sqlite3PExpr(pParse, TK_AND, 0, pAndExpr, 0);
111738       }
111739     }
111740 
111741     for(ii=0; ii<pOrWc->nTerm; ii++){
111742       WhereTerm *pOrTerm = &pOrWc->a[ii];
111743       if( pOrTerm->leftCursor==iCur || (pOrTerm->eOperator & WO_AND)!=0 ){
111744         WhereInfo *pSubWInfo;          /* Info for single OR-term scan */
111745         Expr *pOrExpr = pOrTerm->pExpr;
111746         if( pAndExpr && !ExprHasProperty(pOrExpr, EP_FromJoin) ){
111747           pAndExpr->pLeft = pOrExpr;
111748           pOrExpr = pAndExpr;
111749         }
111750         /* Loop through table entries that match term pOrTerm. */
111751         pSubWInfo = sqlite3WhereBegin(pParse, pOrTab, pOrExpr, 0, 0,
111752                         WHERE_OMIT_OPEN_CLOSE | WHERE_AND_ONLY |
111753                         WHERE_FORCE_TABLE | WHERE_ONETABLE_ONLY, iCovCur);
111754         assert( pSubWInfo || pParse->nErr || db->mallocFailed );
111755         if( pSubWInfo ){
111756           WhereLoop *pSubLoop;
111757           explainOneScan(
111758               pParse, pOrTab, &pSubWInfo->a[0], iLevel, pLevel->iFrom, 0
111759           );
111760           if( (pWInfo->wctrlFlags & WHERE_DUPLICATES_OK)==0 ){
111761             int iSet = ((ii==pOrWc->nTerm-1)?-1:ii);
111762             int r;
111763             r = sqlite3ExprCodeGetColumn(pParse, pTabItem->pTab, -1, iCur, 
111764                                          regRowid, 0);
111765             sqlite3VdbeAddOp4Int(v, OP_RowSetTest, regRowset,
111766                                  sqlite3VdbeCurrentAddr(v)+2, r, iSet);
111767           }
111768           sqlite3VdbeAddOp2(v, OP_Gosub, regReturn, iLoopBody);
111769 
111770           /* The pSubWInfo->untestedTerms flag means that this OR term
111771           ** contained one or more AND term from a notReady table.  The
111772           ** terms from the notReady table could not be tested and will
111773           ** need to be tested later.
111774           */
111775           if( pSubWInfo->untestedTerms ) untestedTerms = 1;
111776 
111777           /* If all of the OR-connected terms are optimized using the same
111778           ** index, and the index is opened using the same cursor number
111779           ** by each call to sqlite3WhereBegin() made by this loop, it may
111780           ** be possible to use that index as a covering index.
111781           **
111782           ** If the call to sqlite3WhereBegin() above resulted in a scan that
111783           ** uses an index, and this is either the first OR-connected term
111784           ** processed or the index is the same as that used by all previous
111785           ** terms, set pCov to the candidate covering index. Otherwise, set 
111786           ** pCov to NULL to indicate that no candidate covering index will 
111787           ** be available.
111788           */
111789           pSubLoop = pSubWInfo->a[0].pWLoop;
111790           assert( (pSubLoop->wsFlags & WHERE_AUTO_INDEX)==0 );
111791           if( (pSubLoop->wsFlags & WHERE_INDEXED)!=0
111792            && (ii==0 || pSubLoop->u.btree.pIndex==pCov)
111793           ){
111794             assert( pSubWInfo->a[0].iIdxCur==iCovCur );
111795             pCov = pSubLoop->u.btree.pIndex;
111796           }else{
111797             pCov = 0;
111798           }
111799 
111800           /* Finish the loop through table entries that match term pOrTerm. */
111801           sqlite3WhereEnd(pSubWInfo);
111802         }
111803       }
111804     }
111805     pLevel->u.pCovidx = pCov;
111806     if( pCov ) pLevel->iIdxCur = iCovCur;
111807     if( pAndExpr ){
111808       pAndExpr->pLeft = 0;
111809       sqlite3ExprDelete(db, pAndExpr);
111810     }
111811     sqlite3VdbeChangeP1(v, iRetInit, sqlite3VdbeCurrentAddr(v));
111812     sqlite3VdbeAddOp2(v, OP_Goto, 0, pLevel->addrBrk);
111813     sqlite3VdbeResolveLabel(v, iLoopBody);
111814 
111815     if( pWInfo->nLevel>1 ) sqlite3StackFree(db, pOrTab);
111816     if( !untestedTerms ) disableTerm(pLevel, pTerm);
111817   }else
111818 #endif /* SQLITE_OMIT_OR_OPTIMIZATION */
111819 
111820   {
111821     /* Case 6:  There is no usable index.  We must do a complete
111822     **          scan of the entire table.
111823     */
111824     static const u8 aStep[] = { OP_Next, OP_Prev };
111825     static const u8 aStart[] = { OP_Rewind, OP_Last };
111826     assert( bRev==0 || bRev==1 );
111827     pLevel->op = aStep[bRev];
111828     pLevel->p1 = iCur;
111829     pLevel->p2 = 1 + sqlite3VdbeAddOp2(v, aStart[bRev], iCur, addrBrk);
111830     pLevel->p5 = SQLITE_STMTSTATUS_FULLSCAN_STEP;
111831   }
111832 
111833   /* Insert code to test every subexpression that can be completely
111834   ** computed using the current set of tables.
111835   */
111836   for(pTerm=pWC->a, j=pWC->nTerm; j>0; j--, pTerm++){
111837     Expr *pE;
111838     testcase( pTerm->wtFlags & TERM_VIRTUAL );
111839     testcase( pTerm->wtFlags & TERM_CODED );
111840     if( pTerm->wtFlags & (TERM_VIRTUAL|TERM_CODED) ) continue;
111841     if( (pTerm->prereqAll & pLevel->notReady)!=0 ){
111842       testcase( pWInfo->untestedTerms==0
111843                && (pWInfo->wctrlFlags & WHERE_ONETABLE_ONLY)!=0 );
111844       pWInfo->untestedTerms = 1;
111845       continue;
111846     }
111847     pE = pTerm->pExpr;
111848     assert( pE!=0 );
111849     if( pLevel->iLeftJoin && !ExprHasProperty(pE, EP_FromJoin) ){
111850       continue;
111851     }
111852     sqlite3ExprIfFalse(pParse, pE, addrCont, SQLITE_JUMPIFNULL);
111853     pTerm->wtFlags |= TERM_CODED;
111854   }
111855 
111856   /* Insert code to test for implied constraints based on transitivity
111857   ** of the "==" operator.
111858   **
111859   ** Example: If the WHERE clause contains "t1.a=t2.b" and "t2.b=123"
111860   ** and we are coding the t1 loop and the t2 loop has not yet coded,
111861   ** then we cannot use the "t1.a=t2.b" constraint, but we can code
111862   ** the implied "t1.a=123" constraint.
111863   */
111864   for(pTerm=pWC->a, j=pWC->nTerm; j>0; j--, pTerm++){
111865     Expr *pE, *pEAlt;
111866     WhereTerm *pAlt;
111867     if( pTerm->wtFlags & (TERM_VIRTUAL|TERM_CODED) ) continue;
111868     if( pTerm->eOperator!=(WO_EQUIV|WO_EQ) ) continue;
111869     if( pTerm->leftCursor!=iCur ) continue;
111870     if( pLevel->iLeftJoin ) continue;
111871     pE = pTerm->pExpr;
111872     assert( !ExprHasProperty(pE, EP_FromJoin) );
111873     assert( (pTerm->prereqRight & pLevel->notReady)!=0 );
111874     pAlt = findTerm(pWC, iCur, pTerm->u.leftColumn, notReady, WO_EQ|WO_IN, 0);
111875     if( pAlt==0 ) continue;
111876     if( pAlt->wtFlags & (TERM_CODED) ) continue;
111877     testcase( pAlt->eOperator & WO_EQ );
111878     testcase( pAlt->eOperator & WO_IN );
111879     VdbeModuleComment((v, "begin transitive constraint"));
111880     pEAlt = sqlite3StackAllocRaw(db, sizeof(*pEAlt));
111881     if( pEAlt ){
111882       *pEAlt = *pAlt->pExpr;
111883       pEAlt->pLeft = pE->pLeft;
111884       sqlite3ExprIfFalse(pParse, pEAlt, addrCont, SQLITE_JUMPIFNULL);
111885       sqlite3StackFree(db, pEAlt);
111886     }
111887   }
111888 
111889   /* For a LEFT OUTER JOIN, generate code that will record the fact that
111890   ** at least one row of the right table has matched the left table.  
111891   */
111892   if( pLevel->iLeftJoin ){
111893     pLevel->addrFirst = sqlite3VdbeCurrentAddr(v);
111894     sqlite3VdbeAddOp2(v, OP_Integer, 1, pLevel->iLeftJoin);
111895     VdbeComment((v, "record LEFT JOIN hit"));
111896     sqlite3ExprCacheClear(pParse);
111897     for(pTerm=pWC->a, j=0; j<pWC->nTerm; j++, pTerm++){
111898       testcase( pTerm->wtFlags & TERM_VIRTUAL );
111899       testcase( pTerm->wtFlags & TERM_CODED );
111900       if( pTerm->wtFlags & (TERM_VIRTUAL|TERM_CODED) ) continue;
111901       if( (pTerm->prereqAll & pLevel->notReady)!=0 ){
111902         assert( pWInfo->untestedTerms );
111903         continue;
111904       }
111905       assert( pTerm->pExpr );
111906       sqlite3ExprIfFalse(pParse, pTerm->pExpr, addrCont, SQLITE_JUMPIFNULL);
111907       pTerm->wtFlags |= TERM_CODED;
111908     }
111909   }
111910   sqlite3ReleaseTempReg(pParse, iReleaseReg);
111911 
111912   return pLevel->notReady;
111913 }
111914 
111915 #if defined(WHERETRACE_ENABLED) && defined(SQLITE_ENABLE_TREE_EXPLAIN)
111916 /*
111917 ** Generate "Explanation" text for a WhereTerm.
111918 */
111919 static void whereExplainTerm(Vdbe *v, WhereTerm *pTerm){
111920   char zType[4];
111921   memcpy(zType, "...", 4);
111922   if( pTerm->wtFlags & TERM_VIRTUAL ) zType[0] = 'V';
111923   if( pTerm->eOperator & WO_EQUIV  ) zType[1] = 'E';
111924   if( ExprHasProperty(pTerm->pExpr, EP_FromJoin) ) zType[2] = 'L';
111925   sqlite3ExplainPrintf(v, "%s ", zType);
111926   sqlite3ExplainExpr(v, pTerm->pExpr);
111927 }
111928 #endif /* WHERETRACE_ENABLED && SQLITE_ENABLE_TREE_EXPLAIN */
111929 
111930 
111931 #ifdef WHERETRACE_ENABLED
111932 /*
111933 ** Print a WhereLoop object for debugging purposes
111934 */
111935 static void whereLoopPrint(WhereLoop *p, WhereClause *pWC){
111936   WhereInfo *pWInfo = pWC->pWInfo;
111937   int nb = 1+(pWInfo->pTabList->nSrc+7)/8;
111938   struct SrcList_item *pItem = pWInfo->pTabList->a + p->iTab;
111939   Table *pTab = pItem->pTab;
111940   sqlite3DebugPrintf("%c%2d.%0*llx.%0*llx", p->cId,
111941                      p->iTab, nb, p->maskSelf, nb, p->prereq);
111942   sqlite3DebugPrintf(" %12s",
111943                      pItem->zAlias ? pItem->zAlias : pTab->zName);
111944   if( (p->wsFlags & WHERE_VIRTUALTABLE)==0 ){
111945      const char *zName;
111946      if( p->u.btree.pIndex && (zName = p->u.btree.pIndex->zName)!=0 ){
111947       if( strncmp(zName, "sqlite_autoindex_", 17)==0 ){
111948         int i = sqlite3Strlen30(zName) - 1;
111949         while( zName[i]!='_' ) i--;
111950         zName += i;
111951       }
111952       sqlite3DebugPrintf(".%-16s %2d", zName, p->u.btree.nEq);
111953     }else{
111954       sqlite3DebugPrintf("%20s","");
111955     }
111956   }else{
111957     char *z;
111958     if( p->u.vtab.idxStr ){
111959       z = sqlite3_mprintf("(%d,\"%s\",%x)",
111960                 p->u.vtab.idxNum, p->u.vtab.idxStr, p->u.vtab.omitMask);
111961     }else{
111962       z = sqlite3_mprintf("(%d,%x)", p->u.vtab.idxNum, p->u.vtab.omitMask);
111963     }
111964     sqlite3DebugPrintf(" %-19s", z);
111965     sqlite3_free(z);
111966   }
111967   sqlite3DebugPrintf(" f %04x N %d", p->wsFlags, p->nLTerm);
111968   sqlite3DebugPrintf(" cost %d,%d,%d\n", p->rSetup, p->rRun, p->nOut);
111969 #ifdef SQLITE_ENABLE_TREE_EXPLAIN
111970   /* If the 0x100 bit of wheretracing is set, then show all of the constraint
111971   ** expressions in the WhereLoop.aLTerm[] array.
111972   */
111973   if( p->nLTerm && (sqlite3WhereTrace & 0x100)!=0 ){  /* WHERETRACE 0x100 */
111974     int i;
111975     Vdbe *v = pWInfo->pParse->pVdbe;
111976     sqlite3ExplainBegin(v);
111977     for(i=0; i<p->nLTerm; i++){
111978       WhereTerm *pTerm = p->aLTerm[i];
111979       if( pTerm==0 ) continue;
111980       sqlite3ExplainPrintf(v, "  (%d) #%-2d ", i+1, (int)(pTerm-pWC->a));
111981       sqlite3ExplainPush(v);
111982       whereExplainTerm(v, pTerm);
111983       sqlite3ExplainPop(v);
111984       sqlite3ExplainNL(v);
111985     }
111986     sqlite3ExplainFinish(v);
111987     sqlite3DebugPrintf("%s", sqlite3VdbeExplanation(v));
111988   }
111989 #endif
111990 }
111991 #endif
111992 
111993 /*
111994 ** Convert bulk memory into a valid WhereLoop that can be passed
111995 ** to whereLoopClear harmlessly.
111996 */
111997 static void whereLoopInit(WhereLoop *p){
111998   p->aLTerm = p->aLTermSpace;
111999   p->nLTerm = 0;
112000   p->nLSlot = ArraySize(p->aLTermSpace);
112001   p->wsFlags = 0;
112002 }
112003 
112004 /*
112005 ** Clear the WhereLoop.u union.  Leave WhereLoop.pLTerm intact.
112006 */
112007 static void whereLoopClearUnion(sqlite3 *db, WhereLoop *p){
112008   if( p->wsFlags & (WHERE_VIRTUALTABLE|WHERE_AUTO_INDEX) ){
112009     if( (p->wsFlags & WHERE_VIRTUALTABLE)!=0 && p->u.vtab.needFree ){
112010       sqlite3_free(p->u.vtab.idxStr);
112011       p->u.vtab.needFree = 0;
112012       p->u.vtab.idxStr = 0;
112013     }else if( (p->wsFlags & WHERE_AUTO_INDEX)!=0 && p->u.btree.pIndex!=0 ){
112014       sqlite3DbFree(db, p->u.btree.pIndex->zColAff);
112015       sqlite3KeyInfoUnref(p->u.btree.pIndex->pKeyInfo);
112016       sqlite3DbFree(db, p->u.btree.pIndex);
112017       p->u.btree.pIndex = 0;
112018     }
112019   }
112020 }
112021 
112022 /*
112023 ** Deallocate internal memory used by a WhereLoop object
112024 */
112025 static void whereLoopClear(sqlite3 *db, WhereLoop *p){
112026   if( p->aLTerm!=p->aLTermSpace ) sqlite3DbFree(db, p->aLTerm);
112027   whereLoopClearUnion(db, p);
112028   whereLoopInit(p);
112029 }
112030 
112031 /*
112032 ** Increase the memory allocation for pLoop->aLTerm[] to be at least n.
112033 */
112034 static int whereLoopResize(sqlite3 *db, WhereLoop *p, int n){
112035   WhereTerm **paNew;
112036   if( p->nLSlot>=n ) return SQLITE_OK;
112037   n = (n+7)&~7;
112038   paNew = sqlite3DbMallocRaw(db, sizeof(p->aLTerm[0])*n);
112039   if( paNew==0 ) return SQLITE_NOMEM;
112040   memcpy(paNew, p->aLTerm, sizeof(p->aLTerm[0])*p->nLSlot);
112041   if( p->aLTerm!=p->aLTermSpace ) sqlite3DbFree(db, p->aLTerm);
112042   p->aLTerm = paNew;
112043   p->nLSlot = n;
112044   return SQLITE_OK;
112045 }
112046 
112047 /*
112048 ** Transfer content from the second pLoop into the first.
112049 */
112050 static int whereLoopXfer(sqlite3 *db, WhereLoop *pTo, WhereLoop *pFrom){
112051   whereLoopClearUnion(db, pTo);
112052   if( whereLoopResize(db, pTo, pFrom->nLTerm) ){
112053     memset(&pTo->u, 0, sizeof(pTo->u));
112054     return SQLITE_NOMEM;
112055   }
112056   memcpy(pTo, pFrom, WHERE_LOOP_XFER_SZ);
112057   memcpy(pTo->aLTerm, pFrom->aLTerm, pTo->nLTerm*sizeof(pTo->aLTerm[0]));
112058   if( pFrom->wsFlags & WHERE_VIRTUALTABLE ){
112059     pFrom->u.vtab.needFree = 0;
112060   }else if( (pFrom->wsFlags & WHERE_AUTO_INDEX)!=0 ){
112061     pFrom->u.btree.pIndex = 0;
112062   }
112063   return SQLITE_OK;
112064 }
112065 
112066 /*
112067 ** Delete a WhereLoop object
112068 */
112069 static void whereLoopDelete(sqlite3 *db, WhereLoop *p){
112070   whereLoopClear(db, p);
112071   sqlite3DbFree(db, p);
112072 }
112073 
112074 /*
112075 ** Free a WhereInfo structure
112076 */
112077 static void whereInfoFree(sqlite3 *db, WhereInfo *pWInfo){
112078   if( ALWAYS(pWInfo) ){
112079     whereClauseClear(&pWInfo->sWC);
112080     while( pWInfo->pLoops ){
112081       WhereLoop *p = pWInfo->pLoops;
112082       pWInfo->pLoops = p->pNextLoop;
112083       whereLoopDelete(db, p);
112084     }
112085     sqlite3DbFree(db, pWInfo);
112086   }
112087 }
112088 
112089 /*
112090 ** Insert or replace a WhereLoop entry using the template supplied.
112091 **
112092 ** An existing WhereLoop entry might be overwritten if the new template
112093 ** is better and has fewer dependencies.  Or the template will be ignored
112094 ** and no insert will occur if an existing WhereLoop is faster and has
112095 ** fewer dependencies than the template.  Otherwise a new WhereLoop is
112096 ** added based on the template.
112097 **
112098 ** If pBuilder->pOrSet is not NULL then we only care about only the
112099 ** prerequisites and rRun and nOut costs of the N best loops.  That
112100 ** information is gathered in the pBuilder->pOrSet object.  This special
112101 ** processing mode is used only for OR clause processing.
112102 **
112103 ** When accumulating multiple loops (when pBuilder->pOrSet is NULL) we
112104 ** still might overwrite similar loops with the new template if the
112105 ** template is better.  Loops may be overwritten if the following 
112106 ** conditions are met:
112107 **
112108 **    (1)  They have the same iTab.
112109 **    (2)  They have the same iSortIdx.
112110 **    (3)  The template has same or fewer dependencies than the current loop
112111 **    (4)  The template has the same or lower cost than the current loop
112112 **    (5)  The template uses more terms of the same index but has no additional
112113 **         dependencies          
112114 */
112115 static int whereLoopInsert(WhereLoopBuilder *pBuilder, WhereLoop *pTemplate){
112116   WhereLoop **ppPrev, *p, *pNext = 0;
112117   WhereInfo *pWInfo = pBuilder->pWInfo;
112118   sqlite3 *db = pWInfo->pParse->db;
112119 
112120   /* If pBuilder->pOrSet is defined, then only keep track of the costs
112121   ** and prereqs.
112122   */
112123   if( pBuilder->pOrSet!=0 ){
112124 #if WHERETRACE_ENABLED
112125     u16 n = pBuilder->pOrSet->n;
112126     int x =
112127 #endif
112128     whereOrInsert(pBuilder->pOrSet, pTemplate->prereq, pTemplate->rRun,
112129                                     pTemplate->nOut);
112130 #if WHERETRACE_ENABLED /* 0x8 */
112131     if( sqlite3WhereTrace & 0x8 ){
112132       sqlite3DebugPrintf(x?"   or-%d:  ":"   or-X:  ", n);
112133       whereLoopPrint(pTemplate, pBuilder->pWC);
112134     }
112135 #endif
112136     return SQLITE_OK;
112137   }
112138 
112139   /* Search for an existing WhereLoop to overwrite, or which takes
112140   ** priority over pTemplate.
112141   */
112142   for(ppPrev=&pWInfo->pLoops, p=*ppPrev; p; ppPrev=&p->pNextLoop, p=*ppPrev){
112143     if( p->iTab!=pTemplate->iTab || p->iSortIdx!=pTemplate->iSortIdx ){
112144       /* If either the iTab or iSortIdx values for two WhereLoop are different
112145       ** then those WhereLoops need to be considered separately.  Neither is
112146       ** a candidate to replace the other. */
112147       continue;
112148     }
112149     /* In the current implementation, the rSetup value is either zero
112150     ** or the cost of building an automatic index (NlogN) and the NlogN
112151     ** is the same for compatible WhereLoops. */
112152     assert( p->rSetup==0 || pTemplate->rSetup==0 
112153                  || p->rSetup==pTemplate->rSetup );
112154 
112155     /* whereLoopAddBtree() always generates and inserts the automatic index
112156     ** case first.  Hence compatible candidate WhereLoops never have a larger
112157     ** rSetup. Call this SETUP-INVARIANT */
112158     assert( p->rSetup>=pTemplate->rSetup );
112159 
112160     if( (p->prereq & pTemplate->prereq)==p->prereq
112161      && p->rSetup<=pTemplate->rSetup
112162      && p->rRun<=pTemplate->rRun
112163      && p->nOut<=pTemplate->nOut
112164     ){
112165       /* This branch taken when p is equal or better than pTemplate in 
112166       ** all of (1) dependencies (2) setup-cost, (3) run-cost, and
112167       ** (4) number of output rows. */
112168       assert( p->rSetup==pTemplate->rSetup );
112169       if( p->prereq==pTemplate->prereq
112170        && p->nLTerm<pTemplate->nLTerm
112171        && (p->wsFlags & pTemplate->wsFlags & WHERE_INDEXED)!=0
112172        && (p->u.btree.pIndex==pTemplate->u.btree.pIndex
112173           || pTemplate->rRun+p->nLTerm<=p->rRun+pTemplate->nLTerm)
112174       ){
112175         /* Overwrite an existing WhereLoop with an similar one that uses
112176         ** more terms of the index */
112177         pNext = p->pNextLoop;
112178         break;
112179       }else{
112180         /* pTemplate is not helpful.
112181         ** Return without changing or adding anything */
112182         goto whereLoopInsert_noop;
112183       }
112184     }
112185     if( (p->prereq & pTemplate->prereq)==pTemplate->prereq
112186      && p->rRun>=pTemplate->rRun
112187      && p->nOut>=pTemplate->nOut
112188     ){
112189       /* Overwrite an existing WhereLoop with a better one: one that is
112190       ** better at one of (1) dependencies, (2) setup-cost, (3) run-cost
112191       ** or (4) number of output rows, and is no worse in any of those
112192       ** categories. */
112193       assert( p->rSetup>=pTemplate->rSetup ); /* SETUP-INVARIANT above */
112194       pNext = p->pNextLoop;
112195       break;
112196     }
112197   }
112198 
112199   /* If we reach this point it means that either p[] should be overwritten
112200   ** with pTemplate[] if p[] exists, or if p==NULL then allocate a new
112201   ** WhereLoop and insert it.
112202   */
112203 #if WHERETRACE_ENABLED /* 0x8 */
112204   if( sqlite3WhereTrace & 0x8 ){
112205     if( p!=0 ){
112206       sqlite3DebugPrintf("ins-del:  ");
112207       whereLoopPrint(p, pBuilder->pWC);
112208     }
112209     sqlite3DebugPrintf("ins-new:  ");
112210     whereLoopPrint(pTemplate, pBuilder->pWC);
112211   }
112212 #endif
112213   if( p==0 ){
112214     p = sqlite3DbMallocRaw(db, sizeof(WhereLoop));
112215     if( p==0 ) return SQLITE_NOMEM;
112216     whereLoopInit(p);
112217   }
112218   whereLoopXfer(db, p, pTemplate);
112219   p->pNextLoop = pNext;
112220   *ppPrev = p;
112221   if( (p->wsFlags & WHERE_VIRTUALTABLE)==0 ){
112222     Index *pIndex = p->u.btree.pIndex;
112223     if( pIndex && pIndex->tnum==0 ){
112224       p->u.btree.pIndex = 0;
112225     }
112226   }
112227   return SQLITE_OK;
112228 
112229   /* Jump here if the insert is a no-op */
112230 whereLoopInsert_noop:
112231 #if WHERETRACE_ENABLED /* 0x8 */
112232   if( sqlite3WhereTrace & 0x8 ){
112233     sqlite3DebugPrintf("ins-noop: ");
112234     whereLoopPrint(pTemplate, pBuilder->pWC);
112235   }
112236 #endif
112237   return SQLITE_OK;  
112238 }
112239 
112240 /*
112241 ** Adjust the WhereLoop.nOut value downward to account for terms of the
112242 ** WHERE clause that reference the loop but which are not used by an
112243 ** index.
112244 **
112245 ** In the current implementation, the first extra WHERE clause term reduces
112246 ** the number of output rows by a factor of 10 and each additional term
112247 ** reduces the number of output rows by sqrt(2).
112248 */
112249 static void whereLoopOutputAdjust(WhereClause *pWC, WhereLoop *pLoop){
112250   WhereTerm *pTerm, *pX;
112251   Bitmask notAllowed = ~(pLoop->prereq|pLoop->maskSelf);
112252   int i, j;
112253 
112254   if( !OptimizationEnabled(pWC->pWInfo->pParse->db, SQLITE_AdjustOutEst) ){
112255     return;
112256   }
112257   for(i=pWC->nTerm, pTerm=pWC->a; i>0; i--, pTerm++){
112258     if( (pTerm->wtFlags & TERM_VIRTUAL)!=0 ) break;
112259     if( (pTerm->prereqAll & pLoop->maskSelf)==0 ) continue;
112260     if( (pTerm->prereqAll & notAllowed)!=0 ) continue;
112261     for(j=pLoop->nLTerm-1; j>=0; j--){
112262       pX = pLoop->aLTerm[j];
112263       if( pX==0 ) continue;
112264       if( pX==pTerm ) break;
112265       if( pX->iParent>=0 && (&pWC->a[pX->iParent])==pTerm ) break;
112266     }
112267     if( j<0 ) pLoop->nOut += pTerm->truthProb;
112268   }
112269 }
112270 
112271 /*
112272 ** We have so far matched pBuilder->pNew->u.btree.nEq terms of the index pIndex.
112273 ** Try to match one more.
112274 **
112275 ** If pProbe->tnum==0, that means pIndex is a fake index used for the
112276 ** INTEGER PRIMARY KEY.
112277 */
112278 static int whereLoopAddBtreeIndex(
112279   WhereLoopBuilder *pBuilder,     /* The WhereLoop factory */
112280   struct SrcList_item *pSrc,      /* FROM clause term being analyzed */
112281   Index *pProbe,                  /* An index on pSrc */
112282   LogEst nInMul                   /* log(Number of iterations due to IN) */
112283 ){
112284   WhereInfo *pWInfo = pBuilder->pWInfo;  /* WHERE analyse context */
112285   Parse *pParse = pWInfo->pParse;        /* Parsing context */
112286   sqlite3 *db = pParse->db;       /* Database connection malloc context */
112287   WhereLoop *pNew;                /* Template WhereLoop under construction */
112288   WhereTerm *pTerm;               /* A WhereTerm under consideration */
112289   int opMask;                     /* Valid operators for constraints */
112290   WhereScan scan;                 /* Iterator for WHERE terms */
112291   Bitmask saved_prereq;           /* Original value of pNew->prereq */
112292   u16 saved_nLTerm;               /* Original value of pNew->nLTerm */
112293   u16 saved_nEq;                  /* Original value of pNew->u.btree.nEq */
112294   u16 saved_nSkip;                /* Original value of pNew->u.btree.nSkip */
112295   u32 saved_wsFlags;              /* Original value of pNew->wsFlags */
112296   LogEst saved_nOut;              /* Original value of pNew->nOut */
112297   int iCol;                       /* Index of the column in the table */
112298   int rc = SQLITE_OK;             /* Return code */
112299   LogEst nRowEst;                 /* Estimated index selectivity */
112300   LogEst rLogSize;                /* Logarithm of table size */
112301   WhereTerm *pTop = 0, *pBtm = 0; /* Top and bottom range constraints */
112302 
112303   pNew = pBuilder->pNew;
112304   if( db->mallocFailed ) return SQLITE_NOMEM;
112305 
112306   assert( (pNew->wsFlags & WHERE_VIRTUALTABLE)==0 );
112307   assert( (pNew->wsFlags & WHERE_TOP_LIMIT)==0 );
112308   if( pNew->wsFlags & WHERE_BTM_LIMIT ){
112309     opMask = WO_LT|WO_LE;
112310   }else if( pProbe->tnum<=0 || (pSrc->jointype & JT_LEFT)!=0 ){
112311     opMask = WO_EQ|WO_IN|WO_GT|WO_GE|WO_LT|WO_LE;
112312   }else{
112313     opMask = WO_EQ|WO_IN|WO_ISNULL|WO_GT|WO_GE|WO_LT|WO_LE;
112314   }
112315   if( pProbe->bUnordered ) opMask &= ~(WO_GT|WO_GE|WO_LT|WO_LE);
112316 
112317   assert( pNew->u.btree.nEq<=pProbe->nKeyCol );
112318   if( pNew->u.btree.nEq < pProbe->nKeyCol ){
112319     iCol = pProbe->aiColumn[pNew->u.btree.nEq];
112320     nRowEst = sqlite3LogEst(pProbe->aiRowEst[pNew->u.btree.nEq+1]);
112321     if( nRowEst==0 && pProbe->onError==OE_None ) nRowEst = 1;
112322   }else{
112323     iCol = -1;
112324     nRowEst = 0;
112325   }
112326   pTerm = whereScanInit(&scan, pBuilder->pWC, pSrc->iCursor, iCol,
112327                         opMask, pProbe);
112328   saved_nEq = pNew->u.btree.nEq;
112329   saved_nSkip = pNew->u.btree.nSkip;
112330   saved_nLTerm = pNew->nLTerm;
112331   saved_wsFlags = pNew->wsFlags;
112332   saved_prereq = pNew->prereq;
112333   saved_nOut = pNew->nOut;
112334   pNew->rSetup = 0;
112335   rLogSize = estLog(sqlite3LogEst(pProbe->aiRowEst[0]));
112336 
112337   /* Consider using a skip-scan if there are no WHERE clause constraints
112338   ** available for the left-most terms of the index, and if the average
112339   ** number of repeats in the left-most terms is at least 18.  The magic
112340   ** number 18 was found by experimentation to be the payoff point where
112341   ** skip-scan become faster than a full-scan.
112342   */
112343   if( pTerm==0
112344    && saved_nEq==saved_nSkip
112345    && saved_nEq+1<pProbe->nKeyCol
112346    && pProbe->aiRowEst[saved_nEq+1]>=18  /* TUNING: Minimum for skip-scan */
112347   ){
112348     LogEst nIter;
112349     pNew->u.btree.nEq++;
112350     pNew->u.btree.nSkip++;
112351     pNew->aLTerm[pNew->nLTerm++] = 0;
112352     pNew->wsFlags |= WHERE_SKIPSCAN;
112353     nIter = sqlite3LogEst(pProbe->aiRowEst[0]/pProbe->aiRowEst[saved_nEq+1]);
112354     whereLoopAddBtreeIndex(pBuilder, pSrc, pProbe, nIter);
112355   }
112356   for(; rc==SQLITE_OK && pTerm!=0; pTerm = whereScanNext(&scan)){
112357     int nIn = 0;
112358 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
112359     int nRecValid = pBuilder->nRecValid;
112360 #endif
112361     if( (pTerm->eOperator==WO_ISNULL || (pTerm->wtFlags&TERM_VNULL)!=0)
112362      && (iCol<0 || pSrc->pTab->aCol[iCol].notNull)
112363     ){
112364       continue; /* ignore IS [NOT] NULL constraints on NOT NULL columns */
112365     }
112366     if( pTerm->prereqRight & pNew->maskSelf ) continue;
112367 
112368     assert( pNew->nOut==saved_nOut );
112369 
112370     pNew->wsFlags = saved_wsFlags;
112371     pNew->u.btree.nEq = saved_nEq;
112372     pNew->nLTerm = saved_nLTerm;
112373     if( whereLoopResize(db, pNew, pNew->nLTerm+1) ) break; /* OOM */
112374     pNew->aLTerm[pNew->nLTerm++] = pTerm;
112375     pNew->prereq = (saved_prereq | pTerm->prereqRight) & ~pNew->maskSelf;
112376     pNew->rRun = rLogSize; /* Baseline cost is log2(N).  Adjustments below */
112377     if( pTerm->eOperator & WO_IN ){
112378       Expr *pExpr = pTerm->pExpr;
112379       pNew->wsFlags |= WHERE_COLUMN_IN;
112380       if( ExprHasProperty(pExpr, EP_xIsSelect) ){
112381         /* "x IN (SELECT ...)":  TUNING: the SELECT returns 25 rows */
112382         nIn = 46;  assert( 46==sqlite3LogEst(25) );
112383       }else if( ALWAYS(pExpr->x.pList && pExpr->x.pList->nExpr) ){
112384         /* "x IN (value, value, ...)" */
112385         nIn = sqlite3LogEst(pExpr->x.pList->nExpr);
112386       }
112387       pNew->rRun += nIn;
112388       pNew->u.btree.nEq++;
112389       pNew->nOut = nRowEst + nInMul + nIn;
112390     }else if( pTerm->eOperator & (WO_EQ) ){
112391       assert(
112392         (pNew->wsFlags & (WHERE_COLUMN_NULL|WHERE_COLUMN_IN|WHERE_SKIPSCAN))!=0
112393         || nInMul==0
112394       );
112395       pNew->wsFlags |= WHERE_COLUMN_EQ;
112396       if( iCol<0  
112397        || (pProbe->onError!=OE_None && nInMul==0
112398            && pNew->u.btree.nEq==pProbe->nKeyCol-1)
112399       ){
112400         assert( (pNew->wsFlags & WHERE_COLUMN_IN)==0 || iCol<0 );
112401         pNew->wsFlags |= WHERE_ONEROW;
112402       }
112403       pNew->u.btree.nEq++;
112404       pNew->nOut = nRowEst + nInMul;
112405     }else if( pTerm->eOperator & (WO_ISNULL) ){
112406       pNew->wsFlags |= WHERE_COLUMN_NULL;
112407       pNew->u.btree.nEq++;
112408       /* TUNING: IS NULL selects 2 rows */
112409       nIn = 10;  assert( 10==sqlite3LogEst(2) );
112410       pNew->nOut = nRowEst + nInMul + nIn;
112411     }else if( pTerm->eOperator & (WO_GT|WO_GE) ){
112412       testcase( pTerm->eOperator & WO_GT );
112413       testcase( pTerm->eOperator & WO_GE );
112414       pNew->wsFlags |= WHERE_COLUMN_RANGE|WHERE_BTM_LIMIT;
112415       pBtm = pTerm;
112416       pTop = 0;
112417     }else{
112418       assert( pTerm->eOperator & (WO_LT|WO_LE) );
112419       testcase( pTerm->eOperator & WO_LT );
112420       testcase( pTerm->eOperator & WO_LE );
112421       pNew->wsFlags |= WHERE_COLUMN_RANGE|WHERE_TOP_LIMIT;
112422       pTop = pTerm;
112423       pBtm = (pNew->wsFlags & WHERE_BTM_LIMIT)!=0 ?
112424                      pNew->aLTerm[pNew->nLTerm-2] : 0;
112425     }
112426     if( pNew->wsFlags & WHERE_COLUMN_RANGE ){
112427       /* Adjust nOut and rRun for STAT3 range values */
112428       assert( pNew->nOut==saved_nOut );
112429       whereRangeScanEst(pParse, pBuilder, pBtm, pTop, pNew);
112430     }
112431 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
112432     if( nInMul==0 
112433      && pProbe->nSample 
112434      && pNew->u.btree.nEq<=pProbe->nSampleCol
112435      && OptimizationEnabled(db, SQLITE_Stat3) 
112436     ){
112437       Expr *pExpr = pTerm->pExpr;
112438       tRowcnt nOut = 0;
112439       if( (pTerm->eOperator & (WO_EQ|WO_ISNULL))!=0 ){
112440         testcase( pTerm->eOperator & WO_EQ );
112441         testcase( pTerm->eOperator & WO_ISNULL );
112442         rc = whereEqualScanEst(pParse, pBuilder, pExpr->pRight, &nOut);
112443       }else if( (pTerm->eOperator & WO_IN)
112444              &&  !ExprHasProperty(pExpr, EP_xIsSelect)  ){
112445         rc = whereInScanEst(pParse, pBuilder, pExpr->x.pList, &nOut);
112446       }
112447       assert( nOut==0 || rc==SQLITE_OK );
112448       if( nOut ){
112449         pNew->nOut = sqlite3LogEst(nOut);
112450         if( pNew->nOut>saved_nOut ) pNew->nOut = saved_nOut;
112451       }
112452     }
112453 #endif
112454     if( (pNew->wsFlags & (WHERE_IDX_ONLY|WHERE_IPK))==0 ){
112455       /* Each row involves a step of the index, then a binary search of
112456       ** the main table */
112457       pNew->rRun =  sqlite3LogEstAdd(pNew->rRun,rLogSize>27 ? rLogSize-17 : 10);
112458     }
112459     /* Step cost for each output row */
112460     pNew->rRun = sqlite3LogEstAdd(pNew->rRun, pNew->nOut);
112461     whereLoopOutputAdjust(pBuilder->pWC, pNew);
112462     rc = whereLoopInsert(pBuilder, pNew);
112463     if( (pNew->wsFlags & WHERE_TOP_LIMIT)==0
112464      && pNew->u.btree.nEq<(pProbe->nKeyCol + (pProbe->zName!=0))
112465     ){
112466       whereLoopAddBtreeIndex(pBuilder, pSrc, pProbe, nInMul+nIn);
112467     }
112468     pNew->nOut = saved_nOut;
112469 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
112470     pBuilder->nRecValid = nRecValid;
112471 #endif
112472   }
112473   pNew->prereq = saved_prereq;
112474   pNew->u.btree.nEq = saved_nEq;
112475   pNew->u.btree.nSkip = saved_nSkip;
112476   pNew->wsFlags = saved_wsFlags;
112477   pNew->nOut = saved_nOut;
112478   pNew->nLTerm = saved_nLTerm;
112479   return rc;
112480 }
112481 
112482 /*
112483 ** Return True if it is possible that pIndex might be useful in
112484 ** implementing the ORDER BY clause in pBuilder.
112485 **
112486 ** Return False if pBuilder does not contain an ORDER BY clause or
112487 ** if there is no way for pIndex to be useful in implementing that
112488 ** ORDER BY clause.
112489 */
112490 static int indexMightHelpWithOrderBy(
112491   WhereLoopBuilder *pBuilder,
112492   Index *pIndex,
112493   int iCursor
112494 ){
112495   ExprList *pOB;
112496   int ii, jj;
112497 
112498   if( pIndex->bUnordered ) return 0;
112499   if( (pOB = pBuilder->pWInfo->pOrderBy)==0 ) return 0;
112500   for(ii=0; ii<pOB->nExpr; ii++){
112501     Expr *pExpr = sqlite3ExprSkipCollate(pOB->a[ii].pExpr);
112502     if( pExpr->op!=TK_COLUMN ) return 0;
112503     if( pExpr->iTable==iCursor ){
112504       for(jj=0; jj<pIndex->nKeyCol; jj++){
112505         if( pExpr->iColumn==pIndex->aiColumn[jj] ) return 1;
112506       }
112507     }
112508   }
112509   return 0;
112510 }
112511 
112512 /*
112513 ** Return a bitmask where 1s indicate that the corresponding column of
112514 ** the table is used by an index.  Only the first 63 columns are considered.
112515 */
112516 static Bitmask columnsInIndex(Index *pIdx){
112517   Bitmask m = 0;
112518   int j;
112519   for(j=pIdx->nColumn-1; j>=0; j--){
112520     int x = pIdx->aiColumn[j];
112521     if( x>=0 ){
112522       testcase( x==BMS-1 );
112523       testcase( x==BMS-2 );
112524       if( x<BMS-1 ) m |= MASKBIT(x);
112525     }
112526   }
112527   return m;
112528 }
112529 
112530 /* Check to see if a partial index with pPartIndexWhere can be used
112531 ** in the current query.  Return true if it can be and false if not.
112532 */
112533 static int whereUsablePartialIndex(int iTab, WhereClause *pWC, Expr *pWhere){
112534   int i;
112535   WhereTerm *pTerm;
112536   for(i=0, pTerm=pWC->a; i<pWC->nTerm; i++, pTerm++){
112537     if( sqlite3ExprImpliesExpr(pTerm->pExpr, pWhere, iTab) ) return 1;
112538   }
112539   return 0;
112540 }
112541 
112542 /*
112543 ** Add all WhereLoop objects for a single table of the join where the table
112544 ** is idenfied by pBuilder->pNew->iTab.  That table is guaranteed to be
112545 ** a b-tree table, not a virtual table.
112546 */
112547 static int whereLoopAddBtree(
112548   WhereLoopBuilder *pBuilder, /* WHERE clause information */
112549   Bitmask mExtra              /* Extra prerequesites for using this table */
112550 ){
112551   WhereInfo *pWInfo;          /* WHERE analysis context */
112552   Index *pProbe;              /* An index we are evaluating */
112553   Index sPk;                  /* A fake index object for the primary key */
112554   tRowcnt aiRowEstPk[2];      /* The aiRowEst[] value for the sPk index */
112555   i16 aiColumnPk = -1;        /* The aColumn[] value for the sPk index */
112556   SrcList *pTabList;          /* The FROM clause */
112557   struct SrcList_item *pSrc;  /* The FROM clause btree term to add */
112558   WhereLoop *pNew;            /* Template WhereLoop object */
112559   int rc = SQLITE_OK;         /* Return code */
112560   int iSortIdx = 1;           /* Index number */
112561   int b;                      /* A boolean value */
112562   LogEst rSize;               /* number of rows in the table */
112563   LogEst rLogSize;            /* Logarithm of the number of rows in the table */
112564   WhereClause *pWC;           /* The parsed WHERE clause */
112565   Table *pTab;                /* Table being queried */
112566   
112567   pNew = pBuilder->pNew;
112568   pWInfo = pBuilder->pWInfo;
112569   pTabList = pWInfo->pTabList;
112570   pSrc = pTabList->a + pNew->iTab;
112571   pTab = pSrc->pTab;
112572   pWC = pBuilder->pWC;
112573   assert( !IsVirtual(pSrc->pTab) );
112574 
112575   if( pSrc->pIndex ){
112576     /* An INDEXED BY clause specifies a particular index to use */
112577     pProbe = pSrc->pIndex;
112578   }else if( !HasRowid(pTab) ){
112579     pProbe = pTab->pIndex;
112580   }else{
112581     /* There is no INDEXED BY clause.  Create a fake Index object in local
112582     ** variable sPk to represent the rowid primary key index.  Make this
112583     ** fake index the first in a chain of Index objects with all of the real
112584     ** indices to follow */
112585     Index *pFirst;                  /* First of real indices on the table */
112586     memset(&sPk, 0, sizeof(Index));
112587     sPk.nKeyCol = 1;
112588     sPk.aiColumn = &aiColumnPk;
112589     sPk.aiRowEst = aiRowEstPk;
112590     sPk.onError = OE_Replace;
112591     sPk.pTable = pTab;
112592     aiRowEstPk[0] = pTab->nRowEst;
112593     aiRowEstPk[1] = 1;
112594     pFirst = pSrc->pTab->pIndex;
112595     if( pSrc->notIndexed==0 ){
112596       /* The real indices of the table are only considered if the
112597       ** NOT INDEXED qualifier is omitted from the FROM clause */
112598       sPk.pNext = pFirst;
112599     }
112600     pProbe = &sPk;
112601   }
112602   rSize = sqlite3LogEst(pTab->nRowEst);
112603   rLogSize = estLog(rSize);
112604 
112605 #ifndef SQLITE_OMIT_AUTOMATIC_INDEX
112606   /* Automatic indexes */
112607   if( !pBuilder->pOrSet
112608    && (pWInfo->pParse->db->flags & SQLITE_AutoIndex)!=0
112609    && pSrc->pIndex==0
112610    && !pSrc->viaCoroutine
112611    && !pSrc->notIndexed
112612    && HasRowid(pTab)
112613    && !pSrc->isCorrelated
112614   ){
112615     /* Generate auto-index WhereLoops */
112616     WhereTerm *pTerm;
112617     WhereTerm *pWCEnd = pWC->a + pWC->nTerm;
112618     for(pTerm=pWC->a; rc==SQLITE_OK && pTerm<pWCEnd; pTerm++){
112619       if( pTerm->prereqRight & pNew->maskSelf ) continue;
112620       if( termCanDriveIndex(pTerm, pSrc, 0) ){
112621         pNew->u.btree.nEq = 1;
112622         pNew->u.btree.nSkip = 0;
112623         pNew->u.btree.pIndex = 0;
112624         pNew->nLTerm = 1;
112625         pNew->aLTerm[0] = pTerm;
112626         /* TUNING: One-time cost for computing the automatic index is
112627         ** approximately 7*N*log2(N) where N is the number of rows in
112628         ** the table being indexed. */
112629         pNew->rSetup = rLogSize + rSize + 28;  assert( 28==sqlite3LogEst(7) );
112630         /* TUNING: Each index lookup yields 20 rows in the table.  This
112631         ** is more than the usual guess of 10 rows, since we have no way
112632         ** of knowning how selective the index will ultimately be.  It would
112633         ** not be unreasonable to make this value much larger. */
112634         pNew->nOut = 43;  assert( 43==sqlite3LogEst(20) );
112635         pNew->rRun = sqlite3LogEstAdd(rLogSize,pNew->nOut);
112636         pNew->wsFlags = WHERE_AUTO_INDEX;
112637         pNew->prereq = mExtra | pTerm->prereqRight;
112638         rc = whereLoopInsert(pBuilder, pNew);
112639       }
112640     }
112641   }
112642 #endif /* SQLITE_OMIT_AUTOMATIC_INDEX */
112643 
112644   /* Loop over all indices
112645   */
112646   for(; rc==SQLITE_OK && pProbe; pProbe=pProbe->pNext, iSortIdx++){
112647     if( pProbe->pPartIdxWhere!=0
112648      && !whereUsablePartialIndex(pNew->iTab, pWC, pProbe->pPartIdxWhere) ){
112649       continue;  /* Partial index inappropriate for this query */
112650     }
112651     pNew->u.btree.nEq = 0;
112652     pNew->u.btree.nSkip = 0;
112653     pNew->nLTerm = 0;
112654     pNew->iSortIdx = 0;
112655     pNew->rSetup = 0;
112656     pNew->prereq = mExtra;
112657     pNew->nOut = rSize;
112658     pNew->u.btree.pIndex = pProbe;
112659     b = indexMightHelpWithOrderBy(pBuilder, pProbe, pSrc->iCursor);
112660     /* The ONEPASS_DESIRED flags never occurs together with ORDER BY */
112661     assert( (pWInfo->wctrlFlags & WHERE_ONEPASS_DESIRED)==0 || b==0 );
112662     if( pProbe->tnum<=0 ){
112663       /* Integer primary key index */
112664       pNew->wsFlags = WHERE_IPK;
112665 
112666       /* Full table scan */
112667       pNew->iSortIdx = b ? iSortIdx : 0;
112668       /* TUNING: Cost of full table scan is 3*(N + log2(N)).
112669       **  +  The extra 3 factor is to encourage the use of indexed lookups
112670       **     over full scans.  FIXME */
112671       pNew->rRun = sqlite3LogEstAdd(rSize,rLogSize) + 16;
112672       whereLoopOutputAdjust(pWC, pNew);
112673       rc = whereLoopInsert(pBuilder, pNew);
112674       pNew->nOut = rSize;
112675       if( rc ) break;
112676     }else{
112677       Bitmask m;
112678       if( pProbe->isCovering ){
112679         pNew->wsFlags = WHERE_IDX_ONLY | WHERE_INDEXED;
112680         m = 0;
112681       }else{
112682         m = pSrc->colUsed & ~columnsInIndex(pProbe);
112683         pNew->wsFlags = (m==0) ? (WHERE_IDX_ONLY|WHERE_INDEXED) : WHERE_INDEXED;
112684       }
112685 
112686       /* Full scan via index */
112687       if( b
112688        || !HasRowid(pTab)
112689        || ( m==0
112690          && pProbe->bUnordered==0
112691          && (pProbe->szIdxRow<pTab->szTabRow)
112692          && (pWInfo->wctrlFlags & WHERE_ONEPASS_DESIRED)==0
112693          && sqlite3GlobalConfig.bUseCis
112694          && OptimizationEnabled(pWInfo->pParse->db, SQLITE_CoverIdxScan)
112695           )
112696       ){
112697         pNew->iSortIdx = b ? iSortIdx : 0;
112698         if( m==0 ){
112699           /* TUNING: Cost of a covering index scan is K*(N + log2(N)).
112700           **  +  The extra factor K of between 1.1 and 3.0 that depends
112701           **     on the relative sizes of the table and the index.  K
112702           **     is smaller for smaller indices, thus favoring them.
112703           */
112704           pNew->rRun = sqlite3LogEstAdd(rSize,rLogSize) + 1 +
112705                         (15*pProbe->szIdxRow)/pTab->szTabRow;
112706         }else{
112707           /* TUNING: Cost of scanning a non-covering index is (N+1)*log2(N)
112708           ** which we will simplify to just N*log2(N) */
112709           pNew->rRun = rSize + rLogSize;
112710         }
112711         whereLoopOutputAdjust(pWC, pNew);
112712         rc = whereLoopInsert(pBuilder, pNew);
112713         pNew->nOut = rSize;
112714         if( rc ) break;
112715       }
112716     }
112717 
112718     rc = whereLoopAddBtreeIndex(pBuilder, pSrc, pProbe, 0);
112719 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
112720     sqlite3Stat4ProbeFree(pBuilder->pRec);
112721     pBuilder->nRecValid = 0;
112722     pBuilder->pRec = 0;
112723 #endif
112724 
112725     /* If there was an INDEXED BY clause, then only that one index is
112726     ** considered. */
112727     if( pSrc->pIndex ) break;
112728   }
112729   return rc;
112730 }
112731 
112732 #ifndef SQLITE_OMIT_VIRTUALTABLE
112733 /*
112734 ** Add all WhereLoop objects for a table of the join identified by
112735 ** pBuilder->pNew->iTab.  That table is guaranteed to be a virtual table.
112736 */
112737 static int whereLoopAddVirtual(
112738   WhereLoopBuilder *pBuilder,  /* WHERE clause information */
112739   Bitmask mExtra
112740 ){
112741   WhereInfo *pWInfo;           /* WHERE analysis context */
112742   Parse *pParse;               /* The parsing context */
112743   WhereClause *pWC;            /* The WHERE clause */
112744   struct SrcList_item *pSrc;   /* The FROM clause term to search */
112745   Table *pTab;
112746   sqlite3 *db;
112747   sqlite3_index_info *pIdxInfo;
112748   struct sqlite3_index_constraint *pIdxCons;
112749   struct sqlite3_index_constraint_usage *pUsage;
112750   WhereTerm *pTerm;
112751   int i, j;
112752   int iTerm, mxTerm;
112753   int nConstraint;
112754   int seenIn = 0;              /* True if an IN operator is seen */
112755   int seenVar = 0;             /* True if a non-constant constraint is seen */
112756   int iPhase;                  /* 0: const w/o IN, 1: const, 2: no IN,  2: IN */
112757   WhereLoop *pNew;
112758   int rc = SQLITE_OK;
112759 
112760   pWInfo = pBuilder->pWInfo;
112761   pParse = pWInfo->pParse;
112762   db = pParse->db;
112763   pWC = pBuilder->pWC;
112764   pNew = pBuilder->pNew;
112765   pSrc = &pWInfo->pTabList->a[pNew->iTab];
112766   pTab = pSrc->pTab;
112767   assert( IsVirtual(pTab) );
112768   pIdxInfo = allocateIndexInfo(pParse, pWC, pSrc, pBuilder->pOrderBy);
112769   if( pIdxInfo==0 ) return SQLITE_NOMEM;
112770   pNew->prereq = 0;
112771   pNew->rSetup = 0;
112772   pNew->wsFlags = WHERE_VIRTUALTABLE;
112773   pNew->nLTerm = 0;
112774   pNew->u.vtab.needFree = 0;
112775   pUsage = pIdxInfo->aConstraintUsage;
112776   nConstraint = pIdxInfo->nConstraint;
112777   if( whereLoopResize(db, pNew, nConstraint) ){
112778     sqlite3DbFree(db, pIdxInfo);
112779     return SQLITE_NOMEM;
112780   }
112781 
112782   for(iPhase=0; iPhase<=3; iPhase++){
112783     if( !seenIn && (iPhase&1)!=0 ){
112784       iPhase++;
112785       if( iPhase>3 ) break;
112786     }
112787     if( !seenVar && iPhase>1 ) break;
112788     pIdxCons = *(struct sqlite3_index_constraint**)&pIdxInfo->aConstraint;
112789     for(i=0; i<pIdxInfo->nConstraint; i++, pIdxCons++){
112790       j = pIdxCons->iTermOffset;
112791       pTerm = &pWC->a[j];
112792       switch( iPhase ){
112793         case 0:    /* Constants without IN operator */
112794           pIdxCons->usable = 0;
112795           if( (pTerm->eOperator & WO_IN)!=0 ){
112796             seenIn = 1;
112797           }
112798           if( pTerm->prereqRight!=0 ){
112799             seenVar = 1;
112800           }else if( (pTerm->eOperator & WO_IN)==0 ){
112801             pIdxCons->usable = 1;
112802           }
112803           break;
112804         case 1:    /* Constants with IN operators */
112805           assert( seenIn );
112806           pIdxCons->usable = (pTerm->prereqRight==0);
112807           break;
112808         case 2:    /* Variables without IN */
112809           assert( seenVar );
112810           pIdxCons->usable = (pTerm->eOperator & WO_IN)==0;
112811           break;
112812         default:   /* Variables with IN */
112813           assert( seenVar && seenIn );
112814           pIdxCons->usable = 1;
112815           break;
112816       }
112817     }
112818     memset(pUsage, 0, sizeof(pUsage[0])*pIdxInfo->nConstraint);
112819     if( pIdxInfo->needToFreeIdxStr ) sqlite3_free(pIdxInfo->idxStr);
112820     pIdxInfo->idxStr = 0;
112821     pIdxInfo->idxNum = 0;
112822     pIdxInfo->needToFreeIdxStr = 0;
112823     pIdxInfo->orderByConsumed = 0;
112824     pIdxInfo->estimatedCost = SQLITE_BIG_DBL / (double)2;
112825     pIdxInfo->estimatedRows = 25;
112826     rc = vtabBestIndex(pParse, pTab, pIdxInfo);
112827     if( rc ) goto whereLoopAddVtab_exit;
112828     pIdxCons = *(struct sqlite3_index_constraint**)&pIdxInfo->aConstraint;
112829     pNew->prereq = mExtra;
112830     mxTerm = -1;
112831     assert( pNew->nLSlot>=nConstraint );
112832     for(i=0; i<nConstraint; i++) pNew->aLTerm[i] = 0;
112833     pNew->u.vtab.omitMask = 0;
112834     for(i=0; i<nConstraint; i++, pIdxCons++){
112835       if( (iTerm = pUsage[i].argvIndex - 1)>=0 ){
112836         j = pIdxCons->iTermOffset;
112837         if( iTerm>=nConstraint
112838          || j<0
112839          || j>=pWC->nTerm
112840          || pNew->aLTerm[iTerm]!=0
112841         ){
112842           rc = SQLITE_ERROR;
112843           sqlite3ErrorMsg(pParse, "%s.xBestIndex() malfunction", pTab->zName);
112844           goto whereLoopAddVtab_exit;
112845         }
112846         testcase( iTerm==nConstraint-1 );
112847         testcase( j==0 );
112848         testcase( j==pWC->nTerm-1 );
112849         pTerm = &pWC->a[j];
112850         pNew->prereq |= pTerm->prereqRight;
112851         assert( iTerm<pNew->nLSlot );
112852         pNew->aLTerm[iTerm] = pTerm;
112853         if( iTerm>mxTerm ) mxTerm = iTerm;
112854         testcase( iTerm==15 );
112855         testcase( iTerm==16 );
112856         if( iTerm<16 && pUsage[i].omit ) pNew->u.vtab.omitMask |= 1<<iTerm;
112857         if( (pTerm->eOperator & WO_IN)!=0 ){
112858           if( pUsage[i].omit==0 ){
112859             /* Do not attempt to use an IN constraint if the virtual table
112860             ** says that the equivalent EQ constraint cannot be safely omitted.
112861             ** If we do attempt to use such a constraint, some rows might be
112862             ** repeated in the output. */
112863             break;
112864           }
112865           /* A virtual table that is constrained by an IN clause may not
112866           ** consume the ORDER BY clause because (1) the order of IN terms
112867           ** is not necessarily related to the order of output terms and
112868           ** (2) Multiple outputs from a single IN value will not merge
112869           ** together.  */
112870           pIdxInfo->orderByConsumed = 0;
112871         }
112872       }
112873     }
112874     if( i>=nConstraint ){
112875       pNew->nLTerm = mxTerm+1;
112876       assert( pNew->nLTerm<=pNew->nLSlot );
112877       pNew->u.vtab.idxNum = pIdxInfo->idxNum;
112878       pNew->u.vtab.needFree = pIdxInfo->needToFreeIdxStr;
112879       pIdxInfo->needToFreeIdxStr = 0;
112880       pNew->u.vtab.idxStr = pIdxInfo->idxStr;
112881       pNew->u.vtab.isOrdered = (u8)((pIdxInfo->nOrderBy!=0)
112882                                      && pIdxInfo->orderByConsumed);
112883       pNew->rSetup = 0;
112884       pNew->rRun = sqlite3LogEstFromDouble(pIdxInfo->estimatedCost);
112885       pNew->nOut = sqlite3LogEst(pIdxInfo->estimatedRows);
112886       whereLoopInsert(pBuilder, pNew);
112887       if( pNew->u.vtab.needFree ){
112888         sqlite3_free(pNew->u.vtab.idxStr);
112889         pNew->u.vtab.needFree = 0;
112890       }
112891     }
112892   }  
112893 
112894 whereLoopAddVtab_exit:
112895   if( pIdxInfo->needToFreeIdxStr ) sqlite3_free(pIdxInfo->idxStr);
112896   sqlite3DbFree(db, pIdxInfo);
112897   return rc;
112898 }
112899 #endif /* SQLITE_OMIT_VIRTUALTABLE */
112900 
112901 /*
112902 ** Add WhereLoop entries to handle OR terms.  This works for either
112903 ** btrees or virtual tables.
112904 */
112905 static int whereLoopAddOr(WhereLoopBuilder *pBuilder, Bitmask mExtra){
112906   WhereInfo *pWInfo = pBuilder->pWInfo;
112907   WhereClause *pWC;
112908   WhereLoop *pNew;
112909   WhereTerm *pTerm, *pWCEnd;
112910   int rc = SQLITE_OK;
112911   int iCur;
112912   WhereClause tempWC;
112913   WhereLoopBuilder sSubBuild;
112914   WhereOrSet sSum, sCur, sPrev;
112915   struct SrcList_item *pItem;
112916   
112917   pWC = pBuilder->pWC;
112918   if( pWInfo->wctrlFlags & WHERE_AND_ONLY ) return SQLITE_OK;
112919   pWCEnd = pWC->a + pWC->nTerm;
112920   pNew = pBuilder->pNew;
112921   memset(&sSum, 0, sizeof(sSum));
112922   pItem = pWInfo->pTabList->a + pNew->iTab;
112923   if( !HasRowid(pItem->pTab) ) return SQLITE_OK;
112924   iCur = pItem->iCursor;
112925 
112926   for(pTerm=pWC->a; pTerm<pWCEnd && rc==SQLITE_OK; pTerm++){
112927     if( (pTerm->eOperator & WO_OR)!=0
112928      && (pTerm->u.pOrInfo->indexable & pNew->maskSelf)!=0 
112929     ){
112930       WhereClause * const pOrWC = &pTerm->u.pOrInfo->wc;
112931       WhereTerm * const pOrWCEnd = &pOrWC->a[pOrWC->nTerm];
112932       WhereTerm *pOrTerm;
112933       int once = 1;
112934       int i, j;
112935     
112936       sSubBuild = *pBuilder;
112937       sSubBuild.pOrderBy = 0;
112938       sSubBuild.pOrSet = &sCur;
112939 
112940       for(pOrTerm=pOrWC->a; pOrTerm<pOrWCEnd; pOrTerm++){
112941         if( (pOrTerm->eOperator & WO_AND)!=0 ){
112942           sSubBuild.pWC = &pOrTerm->u.pAndInfo->wc;
112943         }else if( pOrTerm->leftCursor==iCur ){
112944           tempWC.pWInfo = pWC->pWInfo;
112945           tempWC.pOuter = pWC;
112946           tempWC.op = TK_AND;
112947           tempWC.nTerm = 1;
112948           tempWC.a = pOrTerm;
112949           sSubBuild.pWC = &tempWC;
112950         }else{
112951           continue;
112952         }
112953         sCur.n = 0;
112954 #ifndef SQLITE_OMIT_VIRTUALTABLE
112955         if( IsVirtual(pItem->pTab) ){
112956           rc = whereLoopAddVirtual(&sSubBuild, mExtra);
112957         }else
112958 #endif
112959         {
112960           rc = whereLoopAddBtree(&sSubBuild, mExtra);
112961         }
112962         assert( rc==SQLITE_OK || sCur.n==0 );
112963         if( sCur.n==0 ){
112964           sSum.n = 0;
112965           break;
112966         }else if( once ){
112967           whereOrMove(&sSum, &sCur);
112968           once = 0;
112969         }else{
112970           whereOrMove(&sPrev, &sSum);
112971           sSum.n = 0;
112972           for(i=0; i<sPrev.n; i++){
112973             for(j=0; j<sCur.n; j++){
112974               whereOrInsert(&sSum, sPrev.a[i].prereq | sCur.a[j].prereq,
112975                             sqlite3LogEstAdd(sPrev.a[i].rRun, sCur.a[j].rRun),
112976                             sqlite3LogEstAdd(sPrev.a[i].nOut, sCur.a[j].nOut));
112977             }
112978           }
112979         }
112980       }
112981       pNew->nLTerm = 1;
112982       pNew->aLTerm[0] = pTerm;
112983       pNew->wsFlags = WHERE_MULTI_OR;
112984       pNew->rSetup = 0;
112985       pNew->iSortIdx = 0;
112986       memset(&pNew->u, 0, sizeof(pNew->u));
112987       for(i=0; rc==SQLITE_OK && i<sSum.n; i++){
112988         /* TUNING: Multiple by 3.5 for the secondary table lookup */
112989         pNew->rRun = sSum.a[i].rRun + 18;
112990         pNew->nOut = sSum.a[i].nOut;
112991         pNew->prereq = sSum.a[i].prereq;
112992         rc = whereLoopInsert(pBuilder, pNew);
112993       }
112994     }
112995   }
112996   return rc;
112997 }
112998 
112999 /*
113000 ** Add all WhereLoop objects for all tables 
113001 */
113002 static int whereLoopAddAll(WhereLoopBuilder *pBuilder){
113003   WhereInfo *pWInfo = pBuilder->pWInfo;
113004   Bitmask mExtra = 0;
113005   Bitmask mPrior = 0;
113006   int iTab;
113007   SrcList *pTabList = pWInfo->pTabList;
113008   struct SrcList_item *pItem;
113009   sqlite3 *db = pWInfo->pParse->db;
113010   int nTabList = pWInfo->nLevel;
113011   int rc = SQLITE_OK;
113012   u8 priorJoinType = 0;
113013   WhereLoop *pNew;
113014 
113015   /* Loop over the tables in the join, from left to right */
113016   pNew = pBuilder->pNew;
113017   whereLoopInit(pNew);
113018   for(iTab=0, pItem=pTabList->a; iTab<nTabList; iTab++, pItem++){
113019     pNew->iTab = iTab;
113020     pNew->maskSelf = getMask(&pWInfo->sMaskSet, pItem->iCursor);
113021     if( ((pItem->jointype|priorJoinType) & (JT_LEFT|JT_CROSS))!=0 ){
113022       mExtra = mPrior;
113023     }
113024     priorJoinType = pItem->jointype;
113025     if( IsVirtual(pItem->pTab) ){
113026       rc = whereLoopAddVirtual(pBuilder, mExtra);
113027     }else{
113028       rc = whereLoopAddBtree(pBuilder, mExtra);
113029     }
113030     if( rc==SQLITE_OK ){
113031       rc = whereLoopAddOr(pBuilder, mExtra);
113032     }
113033     mPrior |= pNew->maskSelf;
113034     if( rc || db->mallocFailed ) break;
113035   }
113036   whereLoopClear(db, pNew);
113037   return rc;
113038 }
113039 
113040 /*
113041 ** Examine a WherePath (with the addition of the extra WhereLoop of the 5th
113042 ** parameters) to see if it outputs rows in the requested ORDER BY
113043 ** (or GROUP BY) without requiring a separate sort operation.  Return:
113044 ** 
113045 **    0:  ORDER BY is not satisfied.  Sorting required
113046 **    1:  ORDER BY is satisfied.      Omit sorting
113047 **   -1:  Unknown at this time
113048 **
113049 ** Note that processing for WHERE_GROUPBY and WHERE_DISTINCTBY is not as
113050 ** strict.  With GROUP BY and DISTINCT the only requirement is that
113051 ** equivalent rows appear immediately adjacent to one another.  GROUP BY
113052 ** and DISTINT do not require rows to appear in any particular order as long
113053 ** as equivelent rows are grouped together.  Thus for GROUP BY and DISTINCT
113054 ** the pOrderBy terms can be matched in any order.  With ORDER BY, the 
113055 ** pOrderBy terms must be matched in strict left-to-right order.
113056 */
113057 static int wherePathSatisfiesOrderBy(
113058   WhereInfo *pWInfo,    /* The WHERE clause */
113059   ExprList *pOrderBy,   /* ORDER BY or GROUP BY or DISTINCT clause to check */
113060   WherePath *pPath,     /* The WherePath to check */
113061   u16 wctrlFlags,       /* Might contain WHERE_GROUPBY or WHERE_DISTINCTBY */
113062   u16 nLoop,            /* Number of entries in pPath->aLoop[] */
113063   WhereLoop *pLast,     /* Add this WhereLoop to the end of pPath->aLoop[] */
113064   Bitmask *pRevMask     /* OUT: Mask of WhereLoops to run in reverse order */
113065 ){
113066   u8 revSet;            /* True if rev is known */
113067   u8 rev;               /* Composite sort order */
113068   u8 revIdx;            /* Index sort order */
113069   u8 isOrderDistinct;   /* All prior WhereLoops are order-distinct */
113070   u8 distinctColumns;   /* True if the loop has UNIQUE NOT NULL columns */
113071   u8 isMatch;           /* iColumn matches a term of the ORDER BY clause */
113072   u16 nKeyCol;          /* Number of key columns in pIndex */
113073   u16 nColumn;          /* Total number of ordered columns in the index */
113074   u16 nOrderBy;         /* Number terms in the ORDER BY clause */
113075   int iLoop;            /* Index of WhereLoop in pPath being processed */
113076   int i, j;             /* Loop counters */
113077   int iCur;             /* Cursor number for current WhereLoop */
113078   int iColumn;          /* A column number within table iCur */
113079   WhereLoop *pLoop = 0; /* Current WhereLoop being processed. */
113080   WhereTerm *pTerm;     /* A single term of the WHERE clause */
113081   Expr *pOBExpr;        /* An expression from the ORDER BY clause */
113082   CollSeq *pColl;       /* COLLATE function from an ORDER BY clause term */
113083   Index *pIndex;        /* The index associated with pLoop */
113084   sqlite3 *db = pWInfo->pParse->db;  /* Database connection */
113085   Bitmask obSat = 0;    /* Mask of ORDER BY terms satisfied so far */
113086   Bitmask obDone;       /* Mask of all ORDER BY terms */
113087   Bitmask orderDistinctMask;  /* Mask of all well-ordered loops */
113088   Bitmask ready;              /* Mask of inner loops */
113089 
113090   /*
113091   ** We say the WhereLoop is "one-row" if it generates no more than one
113092   ** row of output.  A WhereLoop is one-row if all of the following are true:
113093   **  (a) All index columns match with WHERE_COLUMN_EQ.
113094   **  (b) The index is unique
113095   ** Any WhereLoop with an WHERE_COLUMN_EQ constraint on the rowid is one-row.
113096   ** Every one-row WhereLoop will have the WHERE_ONEROW bit set in wsFlags.
113097   **
113098   ** We say the WhereLoop is "order-distinct" if the set of columns from
113099   ** that WhereLoop that are in the ORDER BY clause are different for every
113100   ** row of the WhereLoop.  Every one-row WhereLoop is automatically
113101   ** order-distinct.   A WhereLoop that has no columns in the ORDER BY clause
113102   ** is not order-distinct. To be order-distinct is not quite the same as being
113103   ** UNIQUE since a UNIQUE column or index can have multiple rows that 
113104   ** are NULL and NULL values are equivalent for the purpose of order-distinct.
113105   ** To be order-distinct, the columns must be UNIQUE and NOT NULL.
113106   **
113107   ** The rowid for a table is always UNIQUE and NOT NULL so whenever the
113108   ** rowid appears in the ORDER BY clause, the corresponding WhereLoop is
113109   ** automatically order-distinct.
113110   */
113111 
113112   assert( pOrderBy!=0 );
113113 
113114   /* Sortability of virtual tables is determined by the xBestIndex method
113115   ** of the virtual table itself */
113116   if( pLast->wsFlags & WHERE_VIRTUALTABLE ){
113117     testcase( nLoop>0 );  /* True when outer loops are one-row and match 
113118                           ** no ORDER BY terms */
113119     return pLast->u.vtab.isOrdered;
113120   }
113121   if( nLoop && OptimizationDisabled(db, SQLITE_OrderByIdxJoin) ) return 0;
113122 
113123   nOrderBy = pOrderBy->nExpr;
113124   testcase( nOrderBy==BMS-1 );
113125   if( nOrderBy>BMS-1 ) return 0;  /* Cannot optimize overly large ORDER BYs */
113126   isOrderDistinct = 1;
113127   obDone = MASKBIT(nOrderBy)-1;
113128   orderDistinctMask = 0;
113129   ready = 0;
113130   for(iLoop=0; isOrderDistinct && obSat<obDone && iLoop<=nLoop; iLoop++){
113131     if( iLoop>0 ) ready |= pLoop->maskSelf;
113132     pLoop = iLoop<nLoop ? pPath->aLoop[iLoop] : pLast;
113133     assert( (pLoop->wsFlags & WHERE_VIRTUALTABLE)==0 );
113134     iCur = pWInfo->pTabList->a[pLoop->iTab].iCursor;
113135 
113136     /* Mark off any ORDER BY term X that is a column in the table of
113137     ** the current loop for which there is term in the WHERE
113138     ** clause of the form X IS NULL or X=? that reference only outer
113139     ** loops.
113140     */
113141     for(i=0; i<nOrderBy; i++){
113142       if( MASKBIT(i) & obSat ) continue;
113143       pOBExpr = sqlite3ExprSkipCollate(pOrderBy->a[i].pExpr);
113144       if( pOBExpr->op!=TK_COLUMN ) continue;
113145       if( pOBExpr->iTable!=iCur ) continue;
113146       pTerm = findTerm(&pWInfo->sWC, iCur, pOBExpr->iColumn,
113147                        ~ready, WO_EQ|WO_ISNULL, 0);
113148       if( pTerm==0 ) continue;
113149       if( (pTerm->eOperator&WO_EQ)!=0 && pOBExpr->iColumn>=0 ){
113150         const char *z1, *z2;
113151         pColl = sqlite3ExprCollSeq(pWInfo->pParse, pOrderBy->a[i].pExpr);
113152         if( !pColl ) pColl = db->pDfltColl;
113153         z1 = pColl->zName;
113154         pColl = sqlite3ExprCollSeq(pWInfo->pParse, pTerm->pExpr);
113155         if( !pColl ) pColl = db->pDfltColl;
113156         z2 = pColl->zName;
113157         if( sqlite3StrICmp(z1, z2)!=0 ) continue;
113158       }
113159       obSat |= MASKBIT(i);
113160     }
113161 
113162     if( (pLoop->wsFlags & WHERE_ONEROW)==0 ){
113163       if( pLoop->wsFlags & WHERE_IPK ){
113164         pIndex = 0;
113165         nKeyCol = 0;
113166         nColumn = 1;
113167       }else if( (pIndex = pLoop->u.btree.pIndex)==0 || pIndex->bUnordered ){
113168         return 0;
113169       }else{
113170         nKeyCol = pIndex->nKeyCol;
113171         nColumn = pIndex->nColumn;
113172         assert( nColumn==nKeyCol+1 || !HasRowid(pIndex->pTable) );
113173         assert( pIndex->aiColumn[nColumn-1]==(-1) || !HasRowid(pIndex->pTable));
113174         isOrderDistinct = pIndex->onError!=OE_None;
113175       }
113176 
113177       /* Loop through all columns of the index and deal with the ones
113178       ** that are not constrained by == or IN.
113179       */
113180       rev = revSet = 0;
113181       distinctColumns = 0;
113182       for(j=0; j<nColumn; j++){
113183         u8 bOnce;   /* True to run the ORDER BY search loop */
113184 
113185         /* Skip over == and IS NULL terms */
113186         if( j<pLoop->u.btree.nEq
113187          && pLoop->u.btree.nSkip==0
113188          && ((i = pLoop->aLTerm[j]->eOperator) & (WO_EQ|WO_ISNULL))!=0
113189         ){
113190           if( i & WO_ISNULL ){
113191             testcase( isOrderDistinct );
113192             isOrderDistinct = 0;
113193           }
113194           continue;  
113195         }
113196 
113197         /* Get the column number in the table (iColumn) and sort order
113198         ** (revIdx) for the j-th column of the index.
113199         */
113200         if( pIndex ){
113201           iColumn = pIndex->aiColumn[j];
113202           revIdx = pIndex->aSortOrder[j];
113203           if( iColumn==pIndex->pTable->iPKey ) iColumn = -1;
113204         }else{
113205           iColumn = -1;
113206           revIdx = 0;
113207         }
113208 
113209         /* An unconstrained column that might be NULL means that this
113210         ** WhereLoop is not well-ordered
113211         */
113212         if( isOrderDistinct
113213          && iColumn>=0
113214          && j>=pLoop->u.btree.nEq
113215          && pIndex->pTable->aCol[iColumn].notNull==0
113216         ){
113217           isOrderDistinct = 0;
113218         }
113219 
113220         /* Find the ORDER BY term that corresponds to the j-th column
113221         ** of the index and and mark that ORDER BY term off 
113222         */
113223         bOnce = 1;
113224         isMatch = 0;
113225         for(i=0; bOnce && i<nOrderBy; i++){
113226           if( MASKBIT(i) & obSat ) continue;
113227           pOBExpr = sqlite3ExprSkipCollate(pOrderBy->a[i].pExpr);
113228           testcase( wctrlFlags & WHERE_GROUPBY );
113229           testcase( wctrlFlags & WHERE_DISTINCTBY );
113230           if( (wctrlFlags & (WHERE_GROUPBY|WHERE_DISTINCTBY))==0 ) bOnce = 0;
113231           if( pOBExpr->op!=TK_COLUMN ) continue;
113232           if( pOBExpr->iTable!=iCur ) continue;
113233           if( pOBExpr->iColumn!=iColumn ) continue;
113234           if( iColumn>=0 ){
113235             pColl = sqlite3ExprCollSeq(pWInfo->pParse, pOrderBy->a[i].pExpr);
113236             if( !pColl ) pColl = db->pDfltColl;
113237             if( sqlite3StrICmp(pColl->zName, pIndex->azColl[j])!=0 ) continue;
113238           }
113239           isMatch = 1;
113240           break;
113241         }
113242         if( isMatch ){
113243           if( iColumn<0 ){
113244             testcase( distinctColumns==0 );
113245             distinctColumns = 1;
113246           }
113247           obSat |= MASKBIT(i);
113248           if( (pWInfo->wctrlFlags & WHERE_GROUPBY)==0 ){
113249             /* Make sure the sort order is compatible in an ORDER BY clause.
113250             ** Sort order is irrelevant for a GROUP BY clause. */
113251             if( revSet ){
113252               if( (rev ^ revIdx)!=pOrderBy->a[i].sortOrder ) return 0;
113253             }else{
113254               rev = revIdx ^ pOrderBy->a[i].sortOrder;
113255               if( rev ) *pRevMask |= MASKBIT(iLoop);
113256               revSet = 1;
113257             }
113258           }
113259         }else{
113260           /* No match found */
113261           if( j==0 || j<nKeyCol ){
113262             testcase( isOrderDistinct!=0 );
113263             isOrderDistinct = 0;
113264           }
113265           break;
113266         }
113267       } /* end Loop over all index columns */
113268       if( distinctColumns ){
113269         testcase( isOrderDistinct==0 );
113270         isOrderDistinct = 1;
113271       }
113272     } /* end-if not one-row */
113273 
113274     /* Mark off any other ORDER BY terms that reference pLoop */
113275     if( isOrderDistinct ){
113276       orderDistinctMask |= pLoop->maskSelf;
113277       for(i=0; i<nOrderBy; i++){
113278         Expr *p;
113279         if( MASKBIT(i) & obSat ) continue;
113280         p = pOrderBy->a[i].pExpr;
113281         if( (exprTableUsage(&pWInfo->sMaskSet, p)&~orderDistinctMask)==0 ){
113282           obSat |= MASKBIT(i);
113283         }
113284       }
113285     }
113286   } /* End the loop over all WhereLoops from outer-most down to inner-most */
113287   if( obSat==obDone ) return 1;
113288   if( !isOrderDistinct ) return 0;
113289   return -1;
113290 }
113291 
113292 #ifdef WHERETRACE_ENABLED
113293 /* For debugging use only: */
113294 static const char *wherePathName(WherePath *pPath, int nLoop, WhereLoop *pLast){
113295   static char zName[65];
113296   int i;
113297   for(i=0; i<nLoop; i++){ zName[i] = pPath->aLoop[i]->cId; }
113298   if( pLast ) zName[i++] = pLast->cId;
113299   zName[i] = 0;
113300   return zName;
113301 }
113302 #endif
113303 
113304 
113305 /*
113306 ** Given the list of WhereLoop objects at pWInfo->pLoops, this routine
113307 ** attempts to find the lowest cost path that visits each WhereLoop
113308 ** once.  This path is then loaded into the pWInfo->a[].pWLoop fields.
113309 **
113310 ** Assume that the total number of output rows that will need to be sorted
113311 ** will be nRowEst (in the 10*log2 representation).  Or, ignore sorting
113312 ** costs if nRowEst==0.
113313 **
113314 ** Return SQLITE_OK on success or SQLITE_NOMEM of a memory allocation
113315 ** error occurs.
113316 */
113317 static int wherePathSolver(WhereInfo *pWInfo, LogEst nRowEst){
113318   int mxChoice;             /* Maximum number of simultaneous paths tracked */
113319   int nLoop;                /* Number of terms in the join */
113320   Parse *pParse;            /* Parsing context */
113321   sqlite3 *db;              /* The database connection */
113322   int iLoop;                /* Loop counter over the terms of the join */
113323   int ii, jj;               /* Loop counters */
113324   int mxI = 0;              /* Index of next entry to replace */
113325   LogEst rCost;             /* Cost of a path */
113326   LogEst nOut;              /* Number of outputs */
113327   LogEst mxCost = 0;        /* Maximum cost of a set of paths */
113328   LogEst mxOut = 0;         /* Maximum nOut value on the set of paths */
113329   LogEst rSortCost;         /* Cost to do a sort */
113330   int nTo, nFrom;           /* Number of valid entries in aTo[] and aFrom[] */
113331   WherePath *aFrom;         /* All nFrom paths at the previous level */
113332   WherePath *aTo;           /* The nTo best paths at the current level */
113333   WherePath *pFrom;         /* An element of aFrom[] that we are working on */
113334   WherePath *pTo;           /* An element of aTo[] that we are working on */
113335   WhereLoop *pWLoop;        /* One of the WhereLoop objects */
113336   WhereLoop **pX;           /* Used to divy up the pSpace memory */
113337   char *pSpace;             /* Temporary memory used by this routine */
113338 
113339   pParse = pWInfo->pParse;
113340   db = pParse->db;
113341   nLoop = pWInfo->nLevel;
113342   /* TUNING: For simple queries, only the best path is tracked.
113343   ** For 2-way joins, the 5 best paths are followed.
113344   ** For joins of 3 or more tables, track the 10 best paths */
113345   mxChoice = (nLoop==1) ? 1 : (nLoop==2 ? 5 : 10);
113346   assert( nLoop<=pWInfo->pTabList->nSrc );
113347   WHERETRACE(0x002, ("---- begin solver\n"));
113348 
113349   /* Allocate and initialize space for aTo and aFrom */
113350   ii = (sizeof(WherePath)+sizeof(WhereLoop*)*nLoop)*mxChoice*2;
113351   pSpace = sqlite3DbMallocRaw(db, ii);
113352   if( pSpace==0 ) return SQLITE_NOMEM;
113353   aTo = (WherePath*)pSpace;
113354   aFrom = aTo+mxChoice;
113355   memset(aFrom, 0, sizeof(aFrom[0]));
113356   pX = (WhereLoop**)(aFrom+mxChoice);
113357   for(ii=mxChoice*2, pFrom=aTo; ii>0; ii--, pFrom++, pX += nLoop){
113358     pFrom->aLoop = pX;
113359   }
113360 
113361   /* Seed the search with a single WherePath containing zero WhereLoops.
113362   **
113363   ** TUNING: Do not let the number of iterations go above 25.  If the cost
113364   ** of computing an automatic index is not paid back within the first 25
113365   ** rows, then do not use the automatic index. */
113366   aFrom[0].nRow = MIN(pParse->nQueryLoop, 46);  assert( 46==sqlite3LogEst(25) );
113367   nFrom = 1;
113368 
113369   /* Precompute the cost of sorting the final result set, if the caller
113370   ** to sqlite3WhereBegin() was concerned about sorting */
113371   rSortCost = 0;
113372   if( pWInfo->pOrderBy==0 || nRowEst==0 ){
113373     aFrom[0].isOrderedValid = 1;
113374   }else{
113375     /* TUNING: Estimated cost of sorting is 48*N*log2(N) where N is the
113376     ** number of output rows. The 48 is the expected size of a row to sort. 
113377     ** FIXME:  compute a better estimate of the 48 multiplier based on the
113378     ** result set expressions. */
113379     rSortCost = nRowEst + estLog(nRowEst);
113380     WHERETRACE(0x002,("---- sort cost=%-3d\n", rSortCost));
113381   }
113382 
113383   /* Compute successively longer WherePaths using the previous generation
113384   ** of WherePaths as the basis for the next.  Keep track of the mxChoice
113385   ** best paths at each generation */
113386   for(iLoop=0; iLoop<nLoop; iLoop++){
113387     nTo = 0;
113388     for(ii=0, pFrom=aFrom; ii<nFrom; ii++, pFrom++){
113389       for(pWLoop=pWInfo->pLoops; pWLoop; pWLoop=pWLoop->pNextLoop){
113390         Bitmask maskNew;
113391         Bitmask revMask = 0;
113392         u8 isOrderedValid = pFrom->isOrderedValid;
113393         u8 isOrdered = pFrom->isOrdered;
113394         if( (pWLoop->prereq & ~pFrom->maskLoop)!=0 ) continue;
113395         if( (pWLoop->maskSelf & pFrom->maskLoop)!=0 ) continue;
113396         /* At this point, pWLoop is a candidate to be the next loop. 
113397         ** Compute its cost */
113398         rCost = sqlite3LogEstAdd(pWLoop->rSetup,pWLoop->rRun + pFrom->nRow);
113399         rCost = sqlite3LogEstAdd(rCost, pFrom->rCost);
113400         nOut = pFrom->nRow + pWLoop->nOut;
113401         maskNew = pFrom->maskLoop | pWLoop->maskSelf;
113402         if( !isOrderedValid ){
113403           switch( wherePathSatisfiesOrderBy(pWInfo,
113404                        pWInfo->pOrderBy, pFrom, pWInfo->wctrlFlags,
113405                        iLoop, pWLoop, &revMask) ){
113406             case 1:  /* Yes.  pFrom+pWLoop does satisfy the ORDER BY clause */
113407               isOrdered = 1;
113408               isOrderedValid = 1;
113409               break;
113410             case 0:  /* No.  pFrom+pWLoop will require a separate sort */
113411               isOrdered = 0;
113412               isOrderedValid = 1;
113413               rCost = sqlite3LogEstAdd(rCost, rSortCost);
113414               break;
113415             default: /* Cannot tell yet.  Try again on the next iteration */
113416               break;
113417           }
113418         }else{
113419           revMask = pFrom->revLoop;
113420         }
113421         /* Check to see if pWLoop should be added to the mxChoice best so far */
113422         for(jj=0, pTo=aTo; jj<nTo; jj++, pTo++){
113423           if( pTo->maskLoop==maskNew
113424            && pTo->isOrderedValid==isOrderedValid
113425            && ((pTo->rCost<=rCost && pTo->nRow<=nOut) ||
113426                 (pTo->rCost>=rCost && pTo->nRow>=nOut))
113427           ){
113428             testcase( jj==nTo-1 );
113429             break;
113430           }
113431         }
113432         if( jj>=nTo ){
113433           if( nTo>=mxChoice && rCost>=mxCost ){
113434 #ifdef WHERETRACE_ENABLED /* 0x4 */
113435             if( sqlite3WhereTrace&0x4 ){
113436               sqlite3DebugPrintf("Skip   %s cost=%-3d,%3d order=%c\n",
113437                   wherePathName(pFrom, iLoop, pWLoop), rCost, nOut,
113438                   isOrderedValid ? (isOrdered ? 'Y' : 'N') : '?');
113439             }
113440 #endif
113441             continue;
113442           }
113443           /* Add a new Path to the aTo[] set */
113444           if( nTo<mxChoice ){
113445             /* Increase the size of the aTo set by one */
113446             jj = nTo++;
113447           }else{
113448             /* New path replaces the prior worst to keep count below mxChoice */
113449             jj = mxI;
113450           }
113451           pTo = &aTo[jj];
113452 #ifdef WHERETRACE_ENABLED /* 0x4 */
113453           if( sqlite3WhereTrace&0x4 ){
113454             sqlite3DebugPrintf("New    %s cost=%-3d,%3d order=%c\n",
113455                 wherePathName(pFrom, iLoop, pWLoop), rCost, nOut,
113456                 isOrderedValid ? (isOrdered ? 'Y' : 'N') : '?');
113457           }
113458 #endif
113459         }else{
113460           if( pTo->rCost<=rCost && pTo->nRow<=nOut ){
113461 #ifdef WHERETRACE_ENABLED /* 0x4 */
113462             if( sqlite3WhereTrace&0x4 ){
113463               sqlite3DebugPrintf(
113464                   "Skip   %s cost=%-3d,%3d order=%c",
113465                   wherePathName(pFrom, iLoop, pWLoop), rCost, nOut,
113466                   isOrderedValid ? (isOrdered ? 'Y' : 'N') : '?');
113467               sqlite3DebugPrintf("   vs %s cost=%-3d,%d order=%c\n",
113468                   wherePathName(pTo, iLoop+1, 0), pTo->rCost, pTo->nRow,
113469                   pTo->isOrderedValid ? (pTo->isOrdered ? 'Y' : 'N') : '?');
113470             }
113471 #endif
113472             testcase( pTo->rCost==rCost );
113473             continue;
113474           }
113475           testcase( pTo->rCost==rCost+1 );
113476           /* A new and better score for a previously created equivalent path */
113477 #ifdef WHERETRACE_ENABLED /* 0x4 */
113478           if( sqlite3WhereTrace&0x4 ){
113479             sqlite3DebugPrintf(
113480                 "Update %s cost=%-3d,%3d order=%c",
113481                 wherePathName(pFrom, iLoop, pWLoop), rCost, nOut,
113482                 isOrderedValid ? (isOrdered ? 'Y' : 'N') : '?');
113483             sqlite3DebugPrintf("  was %s cost=%-3d,%3d order=%c\n",
113484                 wherePathName(pTo, iLoop+1, 0), pTo->rCost, pTo->nRow,
113485                 pTo->isOrderedValid ? (pTo->isOrdered ? 'Y' : 'N') : '?');
113486           }
113487 #endif
113488         }
113489         /* pWLoop is a winner.  Add it to the set of best so far */
113490         pTo->maskLoop = pFrom->maskLoop | pWLoop->maskSelf;
113491         pTo->revLoop = revMask;
113492         pTo->nRow = nOut;
113493         pTo->rCost = rCost;
113494         pTo->isOrderedValid = isOrderedValid;
113495         pTo->isOrdered = isOrdered;
113496         memcpy(pTo->aLoop, pFrom->aLoop, sizeof(WhereLoop*)*iLoop);
113497         pTo->aLoop[iLoop] = pWLoop;
113498         if( nTo>=mxChoice ){
113499           mxI = 0;
113500           mxCost = aTo[0].rCost;
113501           mxOut = aTo[0].nRow;
113502           for(jj=1, pTo=&aTo[1]; jj<mxChoice; jj++, pTo++){
113503             if( pTo->rCost>mxCost || (pTo->rCost==mxCost && pTo->nRow>mxOut) ){
113504               mxCost = pTo->rCost;
113505               mxOut = pTo->nRow;
113506               mxI = jj;
113507             }
113508           }
113509         }
113510       }
113511     }
113512 
113513 #ifdef WHERETRACE_ENABLED  /* >=2 */
113514     if( sqlite3WhereTrace>=2 ){
113515       sqlite3DebugPrintf("---- after round %d ----\n", iLoop);
113516       for(ii=0, pTo=aTo; ii<nTo; ii++, pTo++){
113517         sqlite3DebugPrintf(" %s cost=%-3d nrow=%-3d order=%c",
113518            wherePathName(pTo, iLoop+1, 0), pTo->rCost, pTo->nRow,
113519            pTo->isOrderedValid ? (pTo->isOrdered ? 'Y' : 'N') : '?');
113520         if( pTo->isOrderedValid && pTo->isOrdered ){
113521           sqlite3DebugPrintf(" rev=0x%llx\n", pTo->revLoop);
113522         }else{
113523           sqlite3DebugPrintf("\n");
113524         }
113525       }
113526     }
113527 #endif
113528 
113529     /* Swap the roles of aFrom and aTo for the next generation */
113530     pFrom = aTo;
113531     aTo = aFrom;
113532     aFrom = pFrom;
113533     nFrom = nTo;
113534   }
113535 
113536   if( nFrom==0 ){
113537     sqlite3ErrorMsg(pParse, "no query solution");
113538     sqlite3DbFree(db, pSpace);
113539     return SQLITE_ERROR;
113540   }
113541   
113542   /* Find the lowest cost path.  pFrom will be left pointing to that path */
113543   pFrom = aFrom;
113544   for(ii=1; ii<nFrom; ii++){
113545     if( pFrom->rCost>aFrom[ii].rCost ) pFrom = &aFrom[ii];
113546   }
113547   assert( pWInfo->nLevel==nLoop );
113548   /* Load the lowest cost path into pWInfo */
113549   for(iLoop=0; iLoop<nLoop; iLoop++){
113550     WhereLevel *pLevel = pWInfo->a + iLoop;
113551     pLevel->pWLoop = pWLoop = pFrom->aLoop[iLoop];
113552     pLevel->iFrom = pWLoop->iTab;
113553     pLevel->iTabCur = pWInfo->pTabList->a[pLevel->iFrom].iCursor;
113554   }
113555   if( (pWInfo->wctrlFlags & WHERE_WANT_DISTINCT)!=0
113556    && (pWInfo->wctrlFlags & WHERE_DISTINCTBY)==0
113557    && pWInfo->eDistinct==WHERE_DISTINCT_NOOP
113558    && nRowEst
113559   ){
113560     Bitmask notUsed;
113561     int rc = wherePathSatisfiesOrderBy(pWInfo, pWInfo->pResultSet, pFrom,
113562                  WHERE_DISTINCTBY, nLoop-1, pFrom->aLoop[nLoop-1], &notUsed);
113563     if( rc==1 ) pWInfo->eDistinct = WHERE_DISTINCT_ORDERED;
113564   }
113565   if( pFrom->isOrdered ){
113566     if( pWInfo->wctrlFlags & WHERE_DISTINCTBY ){
113567       pWInfo->eDistinct = WHERE_DISTINCT_ORDERED;
113568     }else{
113569       pWInfo->bOBSat = 1;
113570       pWInfo->revMask = pFrom->revLoop;
113571     }
113572   }
113573   pWInfo->nRowOut = pFrom->nRow;
113574 
113575   /* Free temporary memory and return success */
113576   sqlite3DbFree(db, pSpace);
113577   return SQLITE_OK;
113578 }
113579 
113580 /*
113581 ** Most queries use only a single table (they are not joins) and have
113582 ** simple == constraints against indexed fields.  This routine attempts
113583 ** to plan those simple cases using much less ceremony than the
113584 ** general-purpose query planner, and thereby yield faster sqlite3_prepare()
113585 ** times for the common case.
113586 **
113587 ** Return non-zero on success, if this query can be handled by this
113588 ** no-frills query planner.  Return zero if this query needs the 
113589 ** general-purpose query planner.
113590 */
113591 static int whereShortCut(WhereLoopBuilder *pBuilder){
113592   WhereInfo *pWInfo;
113593   struct SrcList_item *pItem;
113594   WhereClause *pWC;
113595   WhereTerm *pTerm;
113596   WhereLoop *pLoop;
113597   int iCur;
113598   int j;
113599   Table *pTab;
113600   Index *pIdx;
113601   
113602   pWInfo = pBuilder->pWInfo;
113603   if( pWInfo->wctrlFlags & WHERE_FORCE_TABLE ) return 0;
113604   assert( pWInfo->pTabList->nSrc>=1 );
113605   pItem = pWInfo->pTabList->a;
113606   pTab = pItem->pTab;
113607   if( IsVirtual(pTab) ) return 0;
113608   if( pItem->zIndex ) return 0;
113609   iCur = pItem->iCursor;
113610   pWC = &pWInfo->sWC;
113611   pLoop = pBuilder->pNew;
113612   pLoop->wsFlags = 0;
113613   pLoop->u.btree.nSkip = 0;
113614   pTerm = findTerm(pWC, iCur, -1, 0, WO_EQ, 0);
113615   if( pTerm ){
113616     pLoop->wsFlags = WHERE_COLUMN_EQ|WHERE_IPK|WHERE_ONEROW;
113617     pLoop->aLTerm[0] = pTerm;
113618     pLoop->nLTerm = 1;
113619     pLoop->u.btree.nEq = 1;
113620     /* TUNING: Cost of a rowid lookup is 10 */
113621     pLoop->rRun = 33;  /* 33==sqlite3LogEst(10) */
113622   }else{
113623     for(pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext){
113624       assert( pLoop->aLTermSpace==pLoop->aLTerm );
113625       assert( ArraySize(pLoop->aLTermSpace)==4 );
113626       if( pIdx->onError==OE_None 
113627        || pIdx->pPartIdxWhere!=0 
113628        || pIdx->nKeyCol>ArraySize(pLoop->aLTermSpace) 
113629       ) continue;
113630       for(j=0; j<pIdx->nKeyCol; j++){
113631         pTerm = findTerm(pWC, iCur, pIdx->aiColumn[j], 0, WO_EQ, pIdx);
113632         if( pTerm==0 ) break;
113633         pLoop->aLTerm[j] = pTerm;
113634       }
113635       if( j!=pIdx->nKeyCol ) continue;
113636       pLoop->wsFlags = WHERE_COLUMN_EQ|WHERE_ONEROW|WHERE_INDEXED;
113637       if( pIdx->isCovering || (pItem->colUsed & ~columnsInIndex(pIdx))==0 ){
113638         pLoop->wsFlags |= WHERE_IDX_ONLY;
113639       }
113640       pLoop->nLTerm = j;
113641       pLoop->u.btree.nEq = j;
113642       pLoop->u.btree.pIndex = pIdx;
113643       /* TUNING: Cost of a unique index lookup is 15 */
113644       pLoop->rRun = 39;  /* 39==sqlite3LogEst(15) */
113645       break;
113646     }
113647   }
113648   if( pLoop->wsFlags ){
113649     pLoop->nOut = (LogEst)1;
113650     pWInfo->a[0].pWLoop = pLoop;
113651     pLoop->maskSelf = getMask(&pWInfo->sMaskSet, iCur);
113652     pWInfo->a[0].iTabCur = iCur;
113653     pWInfo->nRowOut = 1;
113654     if( pWInfo->pOrderBy ) pWInfo->bOBSat =  1;
113655     if( pWInfo->wctrlFlags & WHERE_WANT_DISTINCT ){
113656       pWInfo->eDistinct = WHERE_DISTINCT_UNIQUE;
113657     }
113658 #ifdef SQLITE_DEBUG
113659     pLoop->cId = '0';
113660 #endif
113661     return 1;
113662   }
113663   return 0;
113664 }
113665 
113666 /*
113667 ** Generate the beginning of the loop used for WHERE clause processing.
113668 ** The return value is a pointer to an opaque structure that contains
113669 ** information needed to terminate the loop.  Later, the calling routine
113670 ** should invoke sqlite3WhereEnd() with the return value of this function
113671 ** in order to complete the WHERE clause processing.
113672 **
113673 ** If an error occurs, this routine returns NULL.
113674 **
113675 ** The basic idea is to do a nested loop, one loop for each table in
113676 ** the FROM clause of a select.  (INSERT and UPDATE statements are the
113677 ** same as a SELECT with only a single table in the FROM clause.)  For
113678 ** example, if the SQL is this:
113679 **
113680 **       SELECT * FROM t1, t2, t3 WHERE ...;
113681 **
113682 ** Then the code generated is conceptually like the following:
113683 **
113684 **      foreach row1 in t1 do       \    Code generated
113685 **        foreach row2 in t2 do      |-- by sqlite3WhereBegin()
113686 **          foreach row3 in t3 do   /
113687 **            ...
113688 **          end                     \    Code generated
113689 **        end                        |-- by sqlite3WhereEnd()
113690 **      end                         /
113691 **
113692 ** Note that the loops might not be nested in the order in which they
113693 ** appear in the FROM clause if a different order is better able to make
113694 ** use of indices.  Note also that when the IN operator appears in
113695 ** the WHERE clause, it might result in additional nested loops for
113696 ** scanning through all values on the right-hand side of the IN.
113697 **
113698 ** There are Btree cursors associated with each table.  t1 uses cursor
113699 ** number pTabList->a[0].iCursor.  t2 uses the cursor pTabList->a[1].iCursor.
113700 ** And so forth.  This routine generates code to open those VDBE cursors
113701 ** and sqlite3WhereEnd() generates the code to close them.
113702 **
113703 ** The code that sqlite3WhereBegin() generates leaves the cursors named
113704 ** in pTabList pointing at their appropriate entries.  The [...] code
113705 ** can use OP_Column and OP_Rowid opcodes on these cursors to extract
113706 ** data from the various tables of the loop.
113707 **
113708 ** If the WHERE clause is empty, the foreach loops must each scan their
113709 ** entire tables.  Thus a three-way join is an O(N^3) operation.  But if
113710 ** the tables have indices and there are terms in the WHERE clause that
113711 ** refer to those indices, a complete table scan can be avoided and the
113712 ** code will run much faster.  Most of the work of this routine is checking
113713 ** to see if there are indices that can be used to speed up the loop.
113714 **
113715 ** Terms of the WHERE clause are also used to limit which rows actually
113716 ** make it to the "..." in the middle of the loop.  After each "foreach",
113717 ** terms of the WHERE clause that use only terms in that loop and outer
113718 ** loops are evaluated and if false a jump is made around all subsequent
113719 ** inner loops (or around the "..." if the test occurs within the inner-
113720 ** most loop)
113721 **
113722 ** OUTER JOINS
113723 **
113724 ** An outer join of tables t1 and t2 is conceptally coded as follows:
113725 **
113726 **    foreach row1 in t1 do
113727 **      flag = 0
113728 **      foreach row2 in t2 do
113729 **        start:
113730 **          ...
113731 **          flag = 1
113732 **      end
113733 **      if flag==0 then
113734 **        move the row2 cursor to a null row
113735 **        goto start
113736 **      fi
113737 **    end
113738 **
113739 ** ORDER BY CLAUSE PROCESSING
113740 **
113741 ** pOrderBy is a pointer to the ORDER BY clause (or the GROUP BY clause
113742 ** if the WHERE_GROUPBY flag is set in wctrlFlags) of a SELECT statement
113743 ** if there is one.  If there is no ORDER BY clause or if this routine
113744 ** is called from an UPDATE or DELETE statement, then pOrderBy is NULL.
113745 **
113746 ** The iIdxCur parameter is the cursor number of an index.  If 
113747 ** WHERE_ONETABLE_ONLY is set, iIdxCur is the cursor number of an index
113748 ** to use for OR clause processing.  The WHERE clause should use this
113749 ** specific cursor.  If WHERE_ONEPASS_DESIRED is set, then iIdxCur is
113750 ** the first cursor in an array of cursors for all indices.  iIdxCur should
113751 ** be used to compute the appropriate cursor depending on which index is
113752 ** used.
113753 */
113754 SQLITE_PRIVATE WhereInfo *sqlite3WhereBegin(
113755   Parse *pParse,        /* The parser context */
113756   SrcList *pTabList,    /* FROM clause: A list of all tables to be scanned */
113757   Expr *pWhere,         /* The WHERE clause */
113758   ExprList *pOrderBy,   /* An ORDER BY clause, or NULL */
113759   ExprList *pResultSet, /* Result set of the query */
113760   u16 wctrlFlags,       /* One of the WHERE_* flags defined in sqliteInt.h */
113761   int iIdxCur           /* If WHERE_ONETABLE_ONLY is set, index cursor number */
113762 ){
113763   int nByteWInfo;            /* Num. bytes allocated for WhereInfo struct */
113764   int nTabList;              /* Number of elements in pTabList */
113765   WhereInfo *pWInfo;         /* Will become the return value of this function */
113766   Vdbe *v = pParse->pVdbe;   /* The virtual database engine */
113767   Bitmask notReady;          /* Cursors that are not yet positioned */
113768   WhereLoopBuilder sWLB;     /* The WhereLoop builder */
113769   WhereMaskSet *pMaskSet;    /* The expression mask set */
113770   WhereLevel *pLevel;        /* A single level in pWInfo->a[] */
113771   WhereLoop *pLoop;          /* Pointer to a single WhereLoop object */
113772   int ii;                    /* Loop counter */
113773   sqlite3 *db;               /* Database connection */
113774   int rc;                    /* Return code */
113775 
113776 
113777   /* Variable initialization */
113778   db = pParse->db;
113779   memset(&sWLB, 0, sizeof(sWLB));
113780   sWLB.pOrderBy = pOrderBy;
113781 
113782   /* Disable the DISTINCT optimization if SQLITE_DistinctOpt is set via
113783   ** sqlite3_test_ctrl(SQLITE_TESTCTRL_OPTIMIZATIONS,...) */
113784   if( OptimizationDisabled(db, SQLITE_DistinctOpt) ){
113785     wctrlFlags &= ~WHERE_WANT_DISTINCT;
113786   }
113787 
113788   /* The number of tables in the FROM clause is limited by the number of
113789   ** bits in a Bitmask 
113790   */
113791   testcase( pTabList->nSrc==BMS );
113792   if( pTabList->nSrc>BMS ){
113793     sqlite3ErrorMsg(pParse, "at most %d tables in a join", BMS);
113794     return 0;
113795   }
113796 
113797   /* This function normally generates a nested loop for all tables in 
113798   ** pTabList.  But if the WHERE_ONETABLE_ONLY flag is set, then we should
113799   ** only generate code for the first table in pTabList and assume that
113800   ** any cursors associated with subsequent tables are uninitialized.
113801   */
113802   nTabList = (wctrlFlags & WHERE_ONETABLE_ONLY) ? 1 : pTabList->nSrc;
113803 
113804   /* Allocate and initialize the WhereInfo structure that will become the
113805   ** return value. A single allocation is used to store the WhereInfo
113806   ** struct, the contents of WhereInfo.a[], the WhereClause structure
113807   ** and the WhereMaskSet structure. Since WhereClause contains an 8-byte
113808   ** field (type Bitmask) it must be aligned on an 8-byte boundary on
113809   ** some architectures. Hence the ROUND8() below.
113810   */
113811   nByteWInfo = ROUND8(sizeof(WhereInfo)+(nTabList-1)*sizeof(WhereLevel));
113812   pWInfo = sqlite3DbMallocZero(db, nByteWInfo + sizeof(WhereLoop));
113813   if( db->mallocFailed ){
113814     sqlite3DbFree(db, pWInfo);
113815     pWInfo = 0;
113816     goto whereBeginError;
113817   }
113818   pWInfo->aiCurOnePass[0] = pWInfo->aiCurOnePass[1] = -1;
113819   pWInfo->nLevel = nTabList;
113820   pWInfo->pParse = pParse;
113821   pWInfo->pTabList = pTabList;
113822   pWInfo->pOrderBy = pOrderBy;
113823   pWInfo->pResultSet = pResultSet;
113824   pWInfo->iBreak = sqlite3VdbeMakeLabel(v);
113825   pWInfo->wctrlFlags = wctrlFlags;
113826   pWInfo->savedNQueryLoop = pParse->nQueryLoop;
113827   pMaskSet = &pWInfo->sMaskSet;
113828   sWLB.pWInfo = pWInfo;
113829   sWLB.pWC = &pWInfo->sWC;
113830   sWLB.pNew = (WhereLoop*)(((char*)pWInfo)+nByteWInfo);
113831   assert( EIGHT_BYTE_ALIGNMENT(sWLB.pNew) );
113832   whereLoopInit(sWLB.pNew);
113833 #ifdef SQLITE_DEBUG
113834   sWLB.pNew->cId = '*';
113835 #endif
113836 
113837   /* Split the WHERE clause into separate subexpressions where each
113838   ** subexpression is separated by an AND operator.
113839   */
113840   initMaskSet(pMaskSet);
113841   whereClauseInit(&pWInfo->sWC, pWInfo);
113842   whereSplit(&pWInfo->sWC, pWhere, TK_AND);
113843   sqlite3CodeVerifySchema(pParse, -1); /* Insert the cookie verifier Goto */
113844     
113845   /* Special case: a WHERE clause that is constant.  Evaluate the
113846   ** expression and either jump over all of the code or fall thru.
113847   */
113848   if( pWhere && (nTabList==0 || sqlite3ExprIsConstantNotJoin(pWhere)) ){
113849     sqlite3ExprIfFalse(pParse, pWhere, pWInfo->iBreak, SQLITE_JUMPIFNULL);
113850     pWhere = 0;
113851   }
113852 
113853   /* Special case: No FROM clause
113854   */
113855   if( nTabList==0 ){
113856     if( pOrderBy ) pWInfo->bOBSat = 1;
113857     if( wctrlFlags & WHERE_WANT_DISTINCT ){
113858       pWInfo->eDistinct = WHERE_DISTINCT_UNIQUE;
113859     }
113860   }
113861 
113862   /* Assign a bit from the bitmask to every term in the FROM clause.
113863   **
113864   ** When assigning bitmask values to FROM clause cursors, it must be
113865   ** the case that if X is the bitmask for the N-th FROM clause term then
113866   ** the bitmask for all FROM clause terms to the left of the N-th term
113867   ** is (X-1).   An expression from the ON clause of a LEFT JOIN can use
113868   ** its Expr.iRightJoinTable value to find the bitmask of the right table
113869   ** of the join.  Subtracting one from the right table bitmask gives a
113870   ** bitmask for all tables to the left of the join.  Knowing the bitmask
113871   ** for all tables to the left of a left join is important.  Ticket #3015.
113872   **
113873   ** Note that bitmasks are created for all pTabList->nSrc tables in
113874   ** pTabList, not just the first nTabList tables.  nTabList is normally
113875   ** equal to pTabList->nSrc but might be shortened to 1 if the
113876   ** WHERE_ONETABLE_ONLY flag is set.
113877   */
113878   for(ii=0; ii<pTabList->nSrc; ii++){
113879     createMask(pMaskSet, pTabList->a[ii].iCursor);
113880   }
113881 #ifndef NDEBUG
113882   {
113883     Bitmask toTheLeft = 0;
113884     for(ii=0; ii<pTabList->nSrc; ii++){
113885       Bitmask m = getMask(pMaskSet, pTabList->a[ii].iCursor);
113886       assert( (m-1)==toTheLeft );
113887       toTheLeft |= m;
113888     }
113889   }
113890 #endif
113891 
113892   /* Analyze all of the subexpressions.  Note that exprAnalyze() might
113893   ** add new virtual terms onto the end of the WHERE clause.  We do not
113894   ** want to analyze these virtual terms, so start analyzing at the end
113895   ** and work forward so that the added virtual terms are never processed.
113896   */
113897   exprAnalyzeAll(pTabList, &pWInfo->sWC);
113898   if( db->mallocFailed ){
113899     goto whereBeginError;
113900   }
113901 
113902   /* If the ORDER BY (or GROUP BY) clause contains references to general
113903   ** expressions, then we won't be able to satisfy it using indices, so
113904   ** go ahead and disable it now.
113905   */
113906   if( pOrderBy && (wctrlFlags & WHERE_WANT_DISTINCT)!=0 ){
113907     for(ii=0; ii<pOrderBy->nExpr; ii++){
113908       Expr *pExpr = sqlite3ExprSkipCollate(pOrderBy->a[ii].pExpr);
113909       if( pExpr->op!=TK_COLUMN ){
113910         pWInfo->pOrderBy = pOrderBy = 0;
113911         break;
113912       }else if( pExpr->iColumn<0 ){
113913         break;
113914       }
113915     }
113916   }
113917 
113918   if( wctrlFlags & WHERE_WANT_DISTINCT ){
113919     if( isDistinctRedundant(pParse, pTabList, &pWInfo->sWC, pResultSet) ){
113920       /* The DISTINCT marking is pointless.  Ignore it. */
113921       pWInfo->eDistinct = WHERE_DISTINCT_UNIQUE;
113922     }else if( pOrderBy==0 ){
113923       /* Try to ORDER BY the result set to make distinct processing easier */
113924       pWInfo->wctrlFlags |= WHERE_DISTINCTBY;
113925       pWInfo->pOrderBy = pResultSet;
113926     }
113927   }
113928 
113929   /* Construct the WhereLoop objects */
113930   WHERETRACE(0xffff,("*** Optimizer Start ***\n"));
113931   /* Display all terms of the WHERE clause */
113932 #if defined(WHERETRACE_ENABLED) && defined(SQLITE_ENABLE_TREE_EXPLAIN)
113933   if( sqlite3WhereTrace & 0x100 ){
113934     int i;
113935     Vdbe *v = pParse->pVdbe;
113936     sqlite3ExplainBegin(v);
113937     for(i=0; i<sWLB.pWC->nTerm; i++){
113938       sqlite3ExplainPrintf(v, "#%-2d ", i);
113939       sqlite3ExplainPush(v);
113940       whereExplainTerm(v, &sWLB.pWC->a[i]);
113941       sqlite3ExplainPop(v);
113942       sqlite3ExplainNL(v);
113943     }
113944     sqlite3ExplainFinish(v);
113945     sqlite3DebugPrintf("%s", sqlite3VdbeExplanation(v));
113946   }
113947 #endif
113948   if( nTabList!=1 || whereShortCut(&sWLB)==0 ){
113949     rc = whereLoopAddAll(&sWLB);
113950     if( rc ) goto whereBeginError;
113951   
113952     /* Display all of the WhereLoop objects if wheretrace is enabled */
113953 #ifdef WHERETRACE_ENABLED /* !=0 */
113954     if( sqlite3WhereTrace ){
113955       WhereLoop *p;
113956       int i;
113957       static char zLabel[] = "0123456789abcdefghijklmnopqrstuvwyxz"
113958                                        "ABCDEFGHIJKLMNOPQRSTUVWYXZ";
113959       for(p=pWInfo->pLoops, i=0; p; p=p->pNextLoop, i++){
113960         p->cId = zLabel[i%sizeof(zLabel)];
113961         whereLoopPrint(p, sWLB.pWC);
113962       }
113963     }
113964 #endif
113965   
113966     wherePathSolver(pWInfo, 0);
113967     if( db->mallocFailed ) goto whereBeginError;
113968     if( pWInfo->pOrderBy ){
113969        wherePathSolver(pWInfo, pWInfo->nRowOut+1);
113970        if( db->mallocFailed ) goto whereBeginError;
113971     }
113972   }
113973   if( pWInfo->pOrderBy==0 && (db->flags & SQLITE_ReverseOrder)!=0 ){
113974      pWInfo->revMask = (Bitmask)(-1);
113975   }
113976   if( pParse->nErr || NEVER(db->mallocFailed) ){
113977     goto whereBeginError;
113978   }
113979 #ifdef WHERETRACE_ENABLED /* !=0 */
113980   if( sqlite3WhereTrace ){
113981     int ii;
113982     sqlite3DebugPrintf("---- Solution nRow=%d", pWInfo->nRowOut);
113983     if( pWInfo->bOBSat ){
113984       sqlite3DebugPrintf(" ORDERBY=0x%llx", pWInfo->revMask);
113985     }
113986     switch( pWInfo->eDistinct ){
113987       case WHERE_DISTINCT_UNIQUE: {
113988         sqlite3DebugPrintf("  DISTINCT=unique");
113989         break;
113990       }
113991       case WHERE_DISTINCT_ORDERED: {
113992         sqlite3DebugPrintf("  DISTINCT=ordered");
113993         break;
113994       }
113995       case WHERE_DISTINCT_UNORDERED: {
113996         sqlite3DebugPrintf("  DISTINCT=unordered");
113997         break;
113998       }
113999     }
114000     sqlite3DebugPrintf("\n");
114001     for(ii=0; ii<pWInfo->nLevel; ii++){
114002       whereLoopPrint(pWInfo->a[ii].pWLoop, sWLB.pWC);
114003     }
114004   }
114005 #endif
114006   /* Attempt to omit tables from the join that do not effect the result */
114007   if( pWInfo->nLevel>=2
114008    && pResultSet!=0
114009    && OptimizationEnabled(db, SQLITE_OmitNoopJoin)
114010   ){
114011     Bitmask tabUsed = exprListTableUsage(pMaskSet, pResultSet);
114012     if( sWLB.pOrderBy ) tabUsed |= exprListTableUsage(pMaskSet, sWLB.pOrderBy);
114013     while( pWInfo->nLevel>=2 ){
114014       WhereTerm *pTerm, *pEnd;
114015       pLoop = pWInfo->a[pWInfo->nLevel-1].pWLoop;
114016       if( (pWInfo->pTabList->a[pLoop->iTab].jointype & JT_LEFT)==0 ) break;
114017       if( (wctrlFlags & WHERE_WANT_DISTINCT)==0
114018        && (pLoop->wsFlags & WHERE_ONEROW)==0
114019       ){
114020         break;
114021       }
114022       if( (tabUsed & pLoop->maskSelf)!=0 ) break;
114023       pEnd = sWLB.pWC->a + sWLB.pWC->nTerm;
114024       for(pTerm=sWLB.pWC->a; pTerm<pEnd; pTerm++){
114025         if( (pTerm->prereqAll & pLoop->maskSelf)!=0
114026          && !ExprHasProperty(pTerm->pExpr, EP_FromJoin)
114027         ){
114028           break;
114029         }
114030       }
114031       if( pTerm<pEnd ) break;
114032       WHERETRACE(0xffff, ("-> drop loop %c not used\n", pLoop->cId));
114033       pWInfo->nLevel--;
114034       nTabList--;
114035     }
114036   }
114037   WHERETRACE(0xffff,("*** Optimizer Finished ***\n"));
114038   pWInfo->pParse->nQueryLoop += pWInfo->nRowOut;
114039 
114040   /* If the caller is an UPDATE or DELETE statement that is requesting
114041   ** to use a one-pass algorithm, determine if this is appropriate.
114042   ** The one-pass algorithm only works if the WHERE clause constrains
114043   ** the statement to update a single row.
114044   */
114045   assert( (wctrlFlags & WHERE_ONEPASS_DESIRED)==0 || pWInfo->nLevel==1 );
114046   if( (wctrlFlags & WHERE_ONEPASS_DESIRED)!=0 
114047    && (pWInfo->a[0].pWLoop->wsFlags & WHERE_ONEROW)!=0 ){
114048     pWInfo->okOnePass = 1;
114049     if( HasRowid(pTabList->a[0].pTab) ){
114050       pWInfo->a[0].pWLoop->wsFlags &= ~WHERE_IDX_ONLY;
114051     }
114052   }
114053 
114054   /* Open all tables in the pTabList and any indices selected for
114055   ** searching those tables.
114056   */
114057   notReady = ~(Bitmask)0;
114058   for(ii=0, pLevel=pWInfo->a; ii<nTabList; ii++, pLevel++){
114059     Table *pTab;     /* Table to open */
114060     int iDb;         /* Index of database containing table/index */
114061     struct SrcList_item *pTabItem;
114062 
114063     pTabItem = &pTabList->a[pLevel->iFrom];
114064     pTab = pTabItem->pTab;
114065     iDb = sqlite3SchemaToIndex(db, pTab->pSchema);
114066     pLoop = pLevel->pWLoop;
114067     if( (pTab->tabFlags & TF_Ephemeral)!=0 || pTab->pSelect ){
114068       /* Do nothing */
114069     }else
114070 #ifndef SQLITE_OMIT_VIRTUALTABLE
114071     if( (pLoop->wsFlags & WHERE_VIRTUALTABLE)!=0 ){
114072       const char *pVTab = (const char *)sqlite3GetVTable(db, pTab);
114073       int iCur = pTabItem->iCursor;
114074       sqlite3VdbeAddOp4(v, OP_VOpen, iCur, 0, 0, pVTab, P4_VTAB);
114075     }else if( IsVirtual(pTab) ){
114076       /* noop */
114077     }else
114078 #endif
114079     if( (pLoop->wsFlags & WHERE_IDX_ONLY)==0
114080          && (wctrlFlags & WHERE_OMIT_OPEN_CLOSE)==0 ){
114081       int op = OP_OpenRead;
114082       if( pWInfo->okOnePass ){
114083         op = OP_OpenWrite;
114084         pWInfo->aiCurOnePass[0] = pTabItem->iCursor;
114085       };
114086       sqlite3OpenTable(pParse, pTabItem->iCursor, iDb, pTab, op);
114087       assert( pTabItem->iCursor==pLevel->iTabCur );
114088       testcase( !pWInfo->okOnePass && pTab->nCol==BMS-1 );
114089       testcase( !pWInfo->okOnePass && pTab->nCol==BMS );
114090       if( !pWInfo->okOnePass && pTab->nCol<BMS && HasRowid(pTab) ){
114091         Bitmask b = pTabItem->colUsed;
114092         int n = 0;
114093         for(; b; b=b>>1, n++){}
114094         sqlite3VdbeChangeP4(v, sqlite3VdbeCurrentAddr(v)-1, 
114095                             SQLITE_INT_TO_PTR(n), P4_INT32);
114096         assert( n<=pTab->nCol );
114097       }
114098     }else{
114099       sqlite3TableLock(pParse, iDb, pTab->tnum, 0, pTab->zName);
114100     }
114101     if( pLoop->wsFlags & WHERE_INDEXED ){
114102       Index *pIx = pLoop->u.btree.pIndex;
114103       int iIndexCur;
114104       int op = OP_OpenRead;
114105       /* iIdxCur is always set if to a positive value if ONEPASS is possible */
114106       assert( iIdxCur!=0 || (pWInfo->wctrlFlags & WHERE_ONEPASS_DESIRED)==0 );
114107       if( pWInfo->okOnePass ){
114108         Index *pJ = pTabItem->pTab->pIndex;
114109         iIndexCur = iIdxCur;
114110         assert( wctrlFlags & WHERE_ONEPASS_DESIRED );
114111         while( ALWAYS(pJ) && pJ!=pIx ){
114112           iIndexCur++;
114113           pJ = pJ->pNext;
114114         }
114115         op = OP_OpenWrite;
114116         pWInfo->aiCurOnePass[1] = iIndexCur;
114117       }else if( iIdxCur && (wctrlFlags & WHERE_ONETABLE_ONLY)!=0 ){
114118         iIndexCur = iIdxCur;
114119       }else{
114120         iIndexCur = pParse->nTab++;
114121       }
114122       pLevel->iIdxCur = iIndexCur;
114123       assert( pIx->pSchema==pTab->pSchema );
114124       assert( iIndexCur>=0 );
114125       sqlite3VdbeAddOp3(v, op, iIndexCur, pIx->tnum, iDb);
114126       sqlite3VdbeSetP4KeyInfo(pParse, pIx);
114127       VdbeComment((v, "%s", pIx->zName));
114128     }
114129     sqlite3CodeVerifySchema(pParse, iDb);
114130     notReady &= ~getMask(&pWInfo->sMaskSet, pTabItem->iCursor);
114131   }
114132   pWInfo->iTop = sqlite3VdbeCurrentAddr(v);
114133   if( db->mallocFailed ) goto whereBeginError;
114134 
114135   /* Generate the code to do the search.  Each iteration of the for
114136   ** loop below generates code for a single nested loop of the VM
114137   ** program.
114138   */
114139   notReady = ~(Bitmask)0;
114140   for(ii=0; ii<nTabList; ii++){
114141     pLevel = &pWInfo->a[ii];
114142 #ifndef SQLITE_OMIT_AUTOMATIC_INDEX
114143     if( (pLevel->pWLoop->wsFlags & WHERE_AUTO_INDEX)!=0 ){
114144       constructAutomaticIndex(pParse, &pWInfo->sWC,
114145                 &pTabList->a[pLevel->iFrom], notReady, pLevel);
114146       if( db->mallocFailed ) goto whereBeginError;
114147     }
114148 #endif
114149     explainOneScan(pParse, pTabList, pLevel, ii, pLevel->iFrom, wctrlFlags);
114150     pLevel->addrBody = sqlite3VdbeCurrentAddr(v);
114151     notReady = codeOneLoopStart(pWInfo, ii, notReady);
114152     pWInfo->iContinue = pLevel->addrCont;
114153   }
114154 
114155   /* Done. */
114156   VdbeModuleComment((v, "Begin WHERE-core"));
114157   return pWInfo;
114158 
114159   /* Jump here if malloc fails */
114160 whereBeginError:
114161   if( pWInfo ){
114162     pParse->nQueryLoop = pWInfo->savedNQueryLoop;
114163     whereInfoFree(db, pWInfo);
114164   }
114165   return 0;
114166 }
114167 
114168 /*
114169 ** Generate the end of the WHERE loop.  See comments on 
114170 ** sqlite3WhereBegin() for additional information.
114171 */
114172 SQLITE_PRIVATE void sqlite3WhereEnd(WhereInfo *pWInfo){
114173   Parse *pParse = pWInfo->pParse;
114174   Vdbe *v = pParse->pVdbe;
114175   int i;
114176   WhereLevel *pLevel;
114177   WhereLoop *pLoop;
114178   SrcList *pTabList = pWInfo->pTabList;
114179   sqlite3 *db = pParse->db;
114180 
114181   /* Generate loop termination code.
114182   */
114183   VdbeModuleComment((v, "End WHERE-core"));
114184   sqlite3ExprCacheClear(pParse);
114185   for(i=pWInfo->nLevel-1; i>=0; i--){
114186     int addr;
114187     pLevel = &pWInfo->a[i];
114188     pLoop = pLevel->pWLoop;
114189     sqlite3VdbeResolveLabel(v, pLevel->addrCont);
114190     if( pLevel->op!=OP_Noop ){
114191       sqlite3VdbeAddOp2(v, pLevel->op, pLevel->p1, pLevel->p2);
114192       sqlite3VdbeChangeP5(v, pLevel->p5);
114193     }
114194     if( pLoop->wsFlags & WHERE_IN_ABLE && pLevel->u.in.nIn>0 ){
114195       struct InLoop *pIn;
114196       int j;
114197       sqlite3VdbeResolveLabel(v, pLevel->addrNxt);
114198       for(j=pLevel->u.in.nIn, pIn=&pLevel->u.in.aInLoop[j-1]; j>0; j--, pIn--){
114199         sqlite3VdbeJumpHere(v, pIn->addrInTop+1);
114200         sqlite3VdbeAddOp2(v, pIn->eEndLoopOp, pIn->iCur, pIn->addrInTop);
114201         sqlite3VdbeJumpHere(v, pIn->addrInTop-1);
114202       }
114203       sqlite3DbFree(db, pLevel->u.in.aInLoop);
114204     }
114205     sqlite3VdbeResolveLabel(v, pLevel->addrBrk);
114206     if( pLevel->addrSkip ){
114207       sqlite3VdbeAddOp2(v, OP_Goto, 0, pLevel->addrSkip);
114208       VdbeComment((v, "next skip-scan on %s", pLoop->u.btree.pIndex->zName));
114209       sqlite3VdbeJumpHere(v, pLevel->addrSkip);
114210       sqlite3VdbeJumpHere(v, pLevel->addrSkip-2);
114211     }
114212     if( pLevel->iLeftJoin ){
114213       addr = sqlite3VdbeAddOp1(v, OP_IfPos, pLevel->iLeftJoin);
114214       assert( (pLoop->wsFlags & WHERE_IDX_ONLY)==0
114215            || (pLoop->wsFlags & WHERE_INDEXED)!=0 );
114216       if( (pLoop->wsFlags & WHERE_IDX_ONLY)==0 ){
114217         sqlite3VdbeAddOp1(v, OP_NullRow, pTabList->a[i].iCursor);
114218       }
114219       if( pLoop->wsFlags & WHERE_INDEXED ){
114220         sqlite3VdbeAddOp1(v, OP_NullRow, pLevel->iIdxCur);
114221       }
114222       if( pLevel->op==OP_Return ){
114223         sqlite3VdbeAddOp2(v, OP_Gosub, pLevel->p1, pLevel->addrFirst);
114224       }else{
114225         sqlite3VdbeAddOp2(v, OP_Goto, 0, pLevel->addrFirst);
114226       }
114227       sqlite3VdbeJumpHere(v, addr);
114228     }
114229     VdbeModuleComment((v, "End WHERE-loop%d: %s", i,
114230                      pWInfo->pTabList->a[pLevel->iFrom].pTab->zName));
114231   }
114232 
114233   /* The "break" point is here, just past the end of the outer loop.
114234   ** Set it.
114235   */
114236   sqlite3VdbeResolveLabel(v, pWInfo->iBreak);
114237 
114238   assert( pWInfo->nLevel<=pTabList->nSrc );
114239   for(i=0, pLevel=pWInfo->a; i<pWInfo->nLevel; i++, pLevel++){
114240     Index *pIdx = 0;
114241     struct SrcList_item *pTabItem = &pTabList->a[pLevel->iFrom];
114242     Table *pTab = pTabItem->pTab;
114243     assert( pTab!=0 );
114244     pLoop = pLevel->pWLoop;
114245 
114246     /* Close all of the cursors that were opened by sqlite3WhereBegin.
114247     ** Except, do not close cursors that will be reused by the OR optimization
114248     ** (WHERE_OMIT_OPEN_CLOSE).  And do not close the OP_OpenWrite cursors
114249     ** created for the ONEPASS optimization.
114250     */
114251     if( (pTab->tabFlags & TF_Ephemeral)==0
114252      && pTab->pSelect==0
114253      && (pWInfo->wctrlFlags & WHERE_OMIT_OPEN_CLOSE)==0
114254     ){
114255       int ws = pLoop->wsFlags;
114256       if( !pWInfo->okOnePass && (ws & WHERE_IDX_ONLY)==0 ){
114257         sqlite3VdbeAddOp1(v, OP_Close, pTabItem->iCursor);
114258       }
114259       if( (ws & WHERE_INDEXED)!=0
114260        && (ws & (WHERE_IPK|WHERE_AUTO_INDEX))==0 
114261        && pLevel->iIdxCur!=pWInfo->aiCurOnePass[1]
114262       ){
114263         sqlite3VdbeAddOp1(v, OP_Close, pLevel->iIdxCur);
114264       }
114265     }
114266 
114267     /* If this scan uses an index, make VDBE code substitutions to read data
114268     ** from the index instead of from the table where possible.  In some cases
114269     ** this optimization prevents the table from ever being read, which can
114270     ** yield a significant performance boost.
114271     ** 
114272     ** Calls to the code generator in between sqlite3WhereBegin and
114273     ** sqlite3WhereEnd will have created code that references the table
114274     ** directly.  This loop scans all that code looking for opcodes
114275     ** that reference the table and converts them into opcodes that
114276     ** reference the index.
114277     */
114278     if( pLoop->wsFlags & (WHERE_INDEXED|WHERE_IDX_ONLY) ){
114279       pIdx = pLoop->u.btree.pIndex;
114280     }else if( pLoop->wsFlags & WHERE_MULTI_OR ){
114281       pIdx = pLevel->u.pCovidx;
114282     }
114283     if( pIdx && !db->mallocFailed ){
114284       int k, last;
114285       VdbeOp *pOp;
114286 
114287       last = sqlite3VdbeCurrentAddr(v);
114288       k = pLevel->addrBody;
114289       pOp = sqlite3VdbeGetOp(v, k);
114290       for(; k<last; k++, pOp++){
114291         if( pOp->p1!=pLevel->iTabCur ) continue;
114292         if( pOp->opcode==OP_Column ){
114293           int x = pOp->p2;
114294           assert( pIdx->pTable==pTab );
114295           if( !HasRowid(pTab) ){
114296             Index *pPk = sqlite3PrimaryKeyIndex(pTab);
114297             x = pPk->aiColumn[x];
114298           }
114299           x = sqlite3ColumnOfIndex(pIdx, x);
114300           if( x>=0 ){
114301             pOp->p2 = x;
114302             pOp->p1 = pLevel->iIdxCur;
114303           }
114304           assert( (pLoop->wsFlags & WHERE_IDX_ONLY)==0 || x>=0 );
114305         }else if( pOp->opcode==OP_Rowid ){
114306           pOp->p1 = pLevel->iIdxCur;
114307           pOp->opcode = OP_IdxRowid;
114308         }
114309       }
114310     }
114311   }
114312 
114313   /* Final cleanup
114314   */
114315   pParse->nQueryLoop = pWInfo->savedNQueryLoop;
114316   whereInfoFree(db, pWInfo);
114317   return;
114318 }
114319 
114320 /************** End of where.c ***********************************************/
114321 /************** Begin file parse.c *******************************************/
114322 /* Driver template for the LEMON parser generator.
114323 ** The author disclaims copyright to this source code.
114324 **
114325 ** This version of "lempar.c" is modified, slightly, for use by SQLite.
114326 ** The only modifications are the addition of a couple of NEVER()
114327 ** macros to disable tests that are needed in the case of a general
114328 ** LALR(1) grammar but which are always false in the
114329 ** specific grammar used by SQLite.
114330 */
114331 /* First off, code is included that follows the "include" declaration
114332 ** in the input grammar file. */
114333 /* #include <stdio.h> */
114334 
114335 
114336 /*
114337 ** Disable all error recovery processing in the parser push-down
114338 ** automaton.
114339 */
114340 #define YYNOERRORRECOVERY 1
114341 
114342 /*
114343 ** Make yytestcase() the same as testcase()
114344 */
114345 #define yytestcase(X) testcase(X)
114346 
114347 /*
114348 ** An instance of this structure holds information about the
114349 ** LIMIT clause of a SELECT statement.
114350 */
114351 struct LimitVal {
114352   Expr *pLimit;    /* The LIMIT expression.  NULL if there is no limit */
114353   Expr *pOffset;   /* The OFFSET expression.  NULL if there is none */
114354 };
114355 
114356 /*
114357 ** An instance of this structure is used to store the LIKE,
114358 ** GLOB, NOT LIKE, and NOT GLOB operators.
114359 */
114360 struct LikeOp {
114361   Token eOperator;  /* "like" or "glob" or "regexp" */
114362   int bNot;         /* True if the NOT keyword is present */
114363 };
114364 
114365 /*
114366 ** An instance of the following structure describes the event of a
114367 ** TRIGGER.  "a" is the event type, one of TK_UPDATE, TK_INSERT,
114368 ** TK_DELETE, or TK_INSTEAD.  If the event is of the form
114369 **
114370 **      UPDATE ON (a,b,c)
114371 **
114372 ** Then the "b" IdList records the list "a,b,c".
114373 */
114374 struct TrigEvent { int a; IdList * b; };
114375 
114376 /*
114377 ** An instance of this structure holds the ATTACH key and the key type.
114378 */
114379 struct AttachKey { int type;  Token key; };
114380 
114381 /*
114382 ** One or more VALUES claues
114383 */
114384 struct ValueList {
114385   ExprList *pList;
114386   Select *pSelect;
114387 };
114388 
114389 
114390   /* This is a utility routine used to set the ExprSpan.zStart and
114391   ** ExprSpan.zEnd values of pOut so that the span covers the complete
114392   ** range of text beginning with pStart and going to the end of pEnd.
114393   */
114394   static void spanSet(ExprSpan *pOut, Token *pStart, Token *pEnd){
114395     pOut->zStart = pStart->z;
114396     pOut->zEnd = &pEnd->z[pEnd->n];
114397   }
114398 
114399   /* Construct a new Expr object from a single identifier.  Use the
114400   ** new Expr to populate pOut.  Set the span of pOut to be the identifier
114401   ** that created the expression.
114402   */
114403   static void spanExpr(ExprSpan *pOut, Parse *pParse, int op, Token *pValue){
114404     pOut->pExpr = sqlite3PExpr(pParse, op, 0, 0, pValue);
114405     pOut->zStart = pValue->z;
114406     pOut->zEnd = &pValue->z[pValue->n];
114407   }
114408 
114409   /* This routine constructs a binary expression node out of two ExprSpan
114410   ** objects and uses the result to populate a new ExprSpan object.
114411   */
114412   static void spanBinaryExpr(
114413     ExprSpan *pOut,     /* Write the result here */
114414     Parse *pParse,      /* The parsing context.  Errors accumulate here */
114415     int op,             /* The binary operation */
114416     ExprSpan *pLeft,    /* The left operand */
114417     ExprSpan *pRight    /* The right operand */
114418   ){
114419     pOut->pExpr = sqlite3PExpr(pParse, op, pLeft->pExpr, pRight->pExpr, 0);
114420     pOut->zStart = pLeft->zStart;
114421     pOut->zEnd = pRight->zEnd;
114422   }
114423 
114424   /* Construct an expression node for a unary postfix operator
114425   */
114426   static void spanUnaryPostfix(
114427     ExprSpan *pOut,        /* Write the new expression node here */
114428     Parse *pParse,         /* Parsing context to record errors */
114429     int op,                /* The operator */
114430     ExprSpan *pOperand,    /* The operand */
114431     Token *pPostOp         /* The operand token for setting the span */
114432   ){
114433     pOut->pExpr = sqlite3PExpr(pParse, op, pOperand->pExpr, 0, 0);
114434     pOut->zStart = pOperand->zStart;
114435     pOut->zEnd = &pPostOp->z[pPostOp->n];
114436   }                           
114437 
114438   /* A routine to convert a binary TK_IS or TK_ISNOT expression into a
114439   ** unary TK_ISNULL or TK_NOTNULL expression. */
114440   static void binaryToUnaryIfNull(Parse *pParse, Expr *pY, Expr *pA, int op){
114441     sqlite3 *db = pParse->db;
114442     if( db->mallocFailed==0 && pY->op==TK_NULL ){
114443       pA->op = (u8)op;
114444       sqlite3ExprDelete(db, pA->pRight);
114445       pA->pRight = 0;
114446     }
114447   }
114448 
114449   /* Construct an expression node for a unary prefix operator
114450   */
114451   static void spanUnaryPrefix(
114452     ExprSpan *pOut,        /* Write the new expression node here */
114453     Parse *pParse,         /* Parsing context to record errors */
114454     int op,                /* The operator */
114455     ExprSpan *pOperand,    /* The operand */
114456     Token *pPreOp         /* The operand token for setting the span */
114457   ){
114458     pOut->pExpr = sqlite3PExpr(pParse, op, pOperand->pExpr, 0, 0);
114459     pOut->zStart = pPreOp->z;
114460     pOut->zEnd = pOperand->zEnd;
114461   }
114462 /* Next is all token values, in a form suitable for use by makeheaders.
114463 ** This section will be null unless lemon is run with the -m switch.
114464 */
114465 /* 
114466 ** These constants (all generated automatically by the parser generator)
114467 ** specify the various kinds of tokens (terminals) that the parser
114468 ** understands. 
114469 **
114470 ** Each symbol here is a terminal symbol in the grammar.
114471 */
114472 /* Make sure the INTERFACE macro is defined.
114473 */
114474 #ifndef INTERFACE
114475 # define INTERFACE 1
114476 #endif
114477 /* The next thing included is series of defines which control
114478 ** various aspects of the generated parser.
114479 **    YYCODETYPE         is the data type used for storing terminal
114480 **                       and nonterminal numbers.  "unsigned char" is
114481 **                       used if there are fewer than 250 terminals
114482 **                       and nonterminals.  "int" is used otherwise.
114483 **    YYNOCODE           is a number of type YYCODETYPE which corresponds
114484 **                       to no legal terminal or nonterminal number.  This
114485 **                       number is used to fill in empty slots of the hash 
114486 **                       table.
114487 **    YYFALLBACK         If defined, this indicates that one or more tokens
114488 **                       have fall-back values which should be used if the
114489 **                       original value of the token will not parse.
114490 **    YYACTIONTYPE       is the data type used for storing terminal
114491 **                       and nonterminal numbers.  "unsigned char" is
114492 **                       used if there are fewer than 250 rules and
114493 **                       states combined.  "int" is used otherwise.
114494 **    sqlite3ParserTOKENTYPE     is the data type used for minor tokens given 
114495 **                       directly to the parser from the tokenizer.
114496 **    YYMINORTYPE        is the data type used for all minor tokens.
114497 **                       This is typically a union of many types, one of
114498 **                       which is sqlite3ParserTOKENTYPE.  The entry in the union
114499 **                       for base tokens is called "yy0".
114500 **    YYSTACKDEPTH       is the maximum depth of the parser's stack.  If
114501 **                       zero the stack is dynamically sized using realloc()
114502 **    sqlite3ParserARG_SDECL     A static variable declaration for the %extra_argument
114503 **    sqlite3ParserARG_PDECL     A parameter declaration for the %extra_argument
114504 **    sqlite3ParserARG_STORE     Code to store %extra_argument into yypParser
114505 **    sqlite3ParserARG_FETCH     Code to extract %extra_argument from yypParser
114506 **    YYNSTATE           the combined number of states.
114507 **    YYNRULE            the number of rules in the grammar
114508 **    YYERRORSYMBOL      is the code number of the error symbol.  If not
114509 **                       defined, then do no error processing.
114510 */
114511 #define YYCODETYPE unsigned char
114512 #define YYNOCODE 253
114513 #define YYACTIONTYPE unsigned short int
114514 #define YYWILDCARD 68
114515 #define sqlite3ParserTOKENTYPE Token
114516 typedef union {
114517   int yyinit;
114518   sqlite3ParserTOKENTYPE yy0;
114519   int yy4;
114520   struct TrigEvent yy90;
114521   ExprSpan yy118;
114522   u16 yy177;
114523   TriggerStep* yy203;
114524   u8 yy210;
114525   struct {int value; int mask;} yy215;
114526   SrcList* yy259;
114527   struct ValueList yy260;
114528   struct LimitVal yy292;
114529   Expr* yy314;
114530   ExprList* yy322;
114531   struct LikeOp yy342;
114532   IdList* yy384;
114533   Select* yy387;
114534 } YYMINORTYPE;
114535 #ifndef YYSTACKDEPTH
114536 #define YYSTACKDEPTH 100
114537 #endif
114538 #define sqlite3ParserARG_SDECL Parse *pParse;
114539 #define sqlite3ParserARG_PDECL ,Parse *pParse
114540 #define sqlite3ParserARG_FETCH Parse *pParse = yypParser->pParse
114541 #define sqlite3ParserARG_STORE yypParser->pParse = pParse
114542 #define YYNSTATE 631
114543 #define YYNRULE 329
114544 #define YYFALLBACK 1
114545 #define YY_NO_ACTION      (YYNSTATE+YYNRULE+2)
114546 #define YY_ACCEPT_ACTION  (YYNSTATE+YYNRULE+1)
114547 #define YY_ERROR_ACTION   (YYNSTATE+YYNRULE)
114548 
114549 /* The yyzerominor constant is used to initialize instances of
114550 ** YYMINORTYPE objects to zero. */
114551 static const YYMINORTYPE yyzerominor = { 0 };
114552 
114553 /* Define the yytestcase() macro to be a no-op if is not already defined
114554 ** otherwise.
114555 **
114556 ** Applications can choose to define yytestcase() in the %include section
114557 ** to a macro that can assist in verifying code coverage.  For production
114558 ** code the yytestcase() macro should be turned off.  But it is useful
114559 ** for testing.
114560 */
114561 #ifndef yytestcase
114562 # define yytestcase(X)
114563 #endif
114564 
114565 
114566 /* Next are the tables used to determine what action to take based on the
114567 ** current state and lookahead token.  These tables are used to implement
114568 ** functions that take a state number and lookahead value and return an
114569 ** action integer.  
114570 **
114571 ** Suppose the action integer is N.  Then the action is determined as
114572 ** follows
114573 **
114574 **   0 <= N < YYNSTATE                  Shift N.  That is, push the lookahead
114575 **                                      token onto the stack and goto state N.
114576 **
114577 **   YYNSTATE <= N < YYNSTATE+YYNRULE   Reduce by rule N-YYNSTATE.
114578 **
114579 **   N == YYNSTATE+YYNRULE              A syntax error has occurred.
114580 **
114581 **   N == YYNSTATE+YYNRULE+1            The parser accepts its input.
114582 **
114583 **   N == YYNSTATE+YYNRULE+2            No such action.  Denotes unused
114584 **                                      slots in the yy_action[] table.
114585 **
114586 ** The action table is constructed as a single large table named yy_action[].
114587 ** Given state S and lookahead X, the action is computed as
114588 **
114589 **      yy_action[ yy_shift_ofst[S] + X ]
114590 **
114591 ** If the index value yy_shift_ofst[S]+X is out of range or if the value
114592 ** yy_lookahead[yy_shift_ofst[S]+X] is not equal to X or if yy_shift_ofst[S]
114593 ** is equal to YY_SHIFT_USE_DFLT, it means that the action is not in the table
114594 ** and that yy_default[S] should be used instead.  
114595 **
114596 ** The formula above is for computing the action when the lookahead is
114597 ** a terminal symbol.  If the lookahead is a non-terminal (as occurs after
114598 ** a reduce action) then the yy_reduce_ofst[] array is used in place of
114599 ** the yy_shift_ofst[] array and YY_REDUCE_USE_DFLT is used in place of
114600 ** YY_SHIFT_USE_DFLT.
114601 **
114602 ** The following are the tables generated in this section:
114603 **
114604 **  yy_action[]        A single table containing all actions.
114605 **  yy_lookahead[]     A table containing the lookahead for each entry in
114606 **                     yy_action.  Used to detect hash collisions.
114607 **  yy_shift_ofst[]    For each state, the offset into yy_action for
114608 **                     shifting terminals.
114609 **  yy_reduce_ofst[]   For each state, the offset into yy_action for
114610 **                     shifting non-terminals after a reduce.
114611 **  yy_default[]       Default action for each state.
114612 */
114613 #define YY_ACTTAB_COUNT (1582)
114614 static const YYACTIONTYPE yy_action[] = {
114615  /*     0 */   312,  961,  185,  420,    2,  171,  516,  515,  597,   56,
114616  /*    10 */    56,   56,   56,   49,   54,   54,   54,   54,   53,   53,
114617  /*    20 */    52,   52,   52,   51,  234,  197,  196,  195,  624,  623,
114618  /*    30 */   301,  590,  584,   56,   56,   56,   56,  156,   54,   54,
114619  /*    40 */    54,   54,   53,   53,   52,   52,   52,   51,  234,  628,
114620  /*    50 */    57,   58,   48,  582,  581,  583,  583,   55,   55,   56,
114621  /*    60 */    56,   56,   56,  466,   54,   54,   54,   54,   53,   53,
114622  /*    70 */    52,   52,   52,   51,  234,  312,  597,   52,   52,   52,
114623  /*    80 */    51,  234,   33,   54,   54,   54,   54,   53,   53,   52,
114624  /*    90 */    52,   52,   51,  234,  624,  623,  621,  620,  165,  624,
114625  /*   100 */   623,  383,  380,  379,  214,  328,  590,  584,  624,  623,
114626  /*   110 */   467,   59,  378,  619,  618,  617,   53,   53,   52,   52,
114627  /*   120 */    52,   51,  234,  506,  507,   57,   58,   48,  582,  581,
114628  /*   130 */   583,  583,   55,   55,   56,   56,   56,   56,   30,   54,
114629  /*   140 */    54,   54,   54,   53,   53,   52,   52,   52,   51,  234,
114630  /*   150 */   312,   50,   47,  146,  233,  232,  207,  474,  256,  349,
114631  /*   160 */   255,  475,  621,  620,  554,  438,  298,  621,  620,  236,
114632  /*   170 */   674,  435,  440,  553,  439,  366,  621,  620,  540,  224,
114633  /*   180 */   551,  590,  584,  176,  138,  282,  386,  277,  385,  168,
114634  /*   190 */   600,  422,  951,  548,  622,  951,  273,  572,  572,  566,
114635  /*   200 */    57,   58,   48,  582,  581,  583,  583,   55,   55,   56,
114636  /*   210 */    56,   56,   56,  354,   54,   54,   54,   54,   53,   53,
114637  /*   220 */    52,   52,   52,   51,  234,  312,  561,  526,   62,  675,
114638  /*   230 */   132,  595,  410,  348,  579,  579,  492,  426,  577,  419,
114639  /*   240 */   627,   65,  329,  560,  441,  237,  676,  123,  607,   67,
114640  /*   250 */   542,  532,  622,  170,  205,  500,  590,  584,  166,  559,
114641  /*   260 */   622,  403,  593,  593,  593,  442,  443,  271,  422,  950,
114642  /*   270 */   166,  223,  950,  483,  190,   57,   58,   48,  582,  581,
114643  /*   280 */   583,  583,   55,   55,   56,   56,   56,   56,  600,   54,
114644  /*   290 */    54,   54,   54,   53,   53,   52,   52,   52,   51,  234,
114645  /*   300 */   312,  441,  412,  376,  175,  165,  166,  391,  383,  380,
114646  /*   310 */   379,  342,  412,  203,  426,   66,  392,  622,  415,  378,
114647  /*   320 */   597,  166,  442,  338,  444,  571,  601,   74,  415,  624,
114648  /*   330 */   623,  590,  584,  624,  623,  174,  601,   92,  333,  171,
114649  /*   340 */     1,  410,  597,  579,  579,  624,  623,  600,  306,  425,
114650  /*   350 */    57,   58,   48,  582,  581,  583,  583,   55,   55,   56,
114651  /*   360 */    56,   56,   56,  580,   54,   54,   54,   54,   53,   53,
114652  /*   370 */    52,   52,   52,   51,  234,  312,  472,  262,  399,   68,
114653  /*   380 */   412,  339,  571,  389,  624,  623,  578,  602,  597,  589,
114654  /*   390 */   588,  603,  412,  622,  423,  533,  415,  621,  620,  513,
114655  /*   400 */   257,  621,  620,  166,  601,   91,  590,  584,  415,   45,
114656  /*   410 */   597,  586,  585,  621,  620,  250,  601,   92,   39,  347,
114657  /*   420 */   576,  336,  597,  547,  567,   57,   58,   48,  582,  581,
114658  /*   430 */   583,  583,   55,   55,   56,   56,   56,   56,  587,   54,
114659  /*   440 */    54,   54,   54,   53,   53,   52,   52,   52,   51,  234,
114660  /*   450 */   312,  561,  621,  620,  531,  291,  470,  188,  399,  375,
114661  /*   460 */   247,  492,  249,  350,  412,  476,  476,  368,  560,  299,
114662  /*   470 */   334,  412,  281,  482,   67,  565,  410,  622,  579,  579,
114663  /*   480 */   415,  590,  584,  280,  559,  467,  520,  415,  601,   92,
114664  /*   490 */   597,  167,  544,   36,  877,  601,   16,  519,  564,    6,
114665  /*   500 */    57,   58,   48,  582,  581,  583,  583,   55,   55,   56,
114666  /*   510 */    56,   56,   56,  200,   54,   54,   54,   54,   53,   53,
114667  /*   520 */    52,   52,   52,   51,  234,  312,  183,  412,  236,  528,
114668  /*   530 */   395,  535,  358,  256,  349,  255,  397,  412,  248,  182,
114669  /*   540 */   353,  359,  549,  415,  236,  317,  563,   50,   47,  146,
114670  /*   550 */   273,  601,   73,  415,    7,  311,  590,  584,  568,  493,
114671  /*   560 */   213,  601,   92,  233,  232,  410,  173,  579,  579,  330,
114672  /*   570 */   575,  574,  631,  629,  332,   57,   58,   48,  582,  581,
114673  /*   580 */   583,  583,   55,   55,   56,   56,   56,   56,  199,   54,
114674  /*   590 */    54,   54,   54,   53,   53,   52,   52,   52,   51,  234,
114675  /*   600 */   312,  492,  340,  320,  511,  505,  572,  572,  460,  562,
114676  /*   610 */   549,  170,  145,  430,   67,  558,  410,  622,  579,  579,
114677  /*   620 */   384,  236,  600,  412,  408,  575,  574,  504,  572,  572,
114678  /*   630 */   571,  590,  584,  353,  198,  143,  268,  549,  316,  415,
114679  /*   640 */   306,  424,  207,   50,   47,  146,  167,  601,   69,  546,
114680  /*   650 */    57,   58,   48,  582,  581,  583,  583,   55,   55,   56,
114681  /*   660 */    56,   56,   56,  555,   54,   54,   54,   54,   53,   53,
114682  /*   670 */    52,   52,   52,   51,  234,  312,  600,  326,  412,  270,
114683  /*   680 */   145,  264,  274,  266,  459,  571,  423,   35,  412,  568,
114684  /*   690 */   407,  213,  428,  388,  415,  308,  212,  143,  622,  354,
114685  /*   700 */   317,   12,  601,   94,  415,  549,  590,  584,   50,   47,
114686  /*   710 */   146,  365,  601,   97,  552,  362,  318,  147,  602,  361,
114687  /*   720 */   325,   15,  603,  187,  206,   57,   58,   48,  582,  581,
114688  /*   730 */   583,  583,   55,   55,   56,   56,   56,   56,  412,   54,
114689  /*   740 */    54,   54,   54,   53,   53,   52,   52,   52,   51,  234,
114690  /*   750 */   312,  412,   35,  412,  415,   22,  630,    2,  600,   50,
114691  /*   760 */    47,  146,  601,   95,  412,  485,  510,  415,  412,  415,
114692  /*   770 */   412,   11,  235,  486,  412,  601,  104,  601,  103,   19,
114693  /*   780 */   415,  590,  584,  352,  415,   40,  415,   38,  601,  105,
114694  /*   790 */   415,   32,  601,  106,  601,  133,  544,  169,  601,  134,
114695  /*   800 */    57,   58,   48,  582,  581,  583,  583,   55,   55,   56,
114696  /*   810 */    56,   56,   56,  412,   54,   54,   54,   54,   53,   53,
114697  /*   820 */    52,   52,   52,   51,  234,  312,  412,  274,  412,  415,
114698  /*   830 */   412,  274,  274,  274,  201,  230,  721,  601,   98,  484,
114699  /*   840 */   427,  307,  415,  622,  415,  540,  415,  622,  622,  622,
114700  /*   850 */   601,  102,  601,  101,  601,   93,  590,  584,  262,   21,
114701  /*   860 */   129,  622,  522,  521,  554,  222,  469,  521,  600,  324,
114702  /*   870 */   323,  322,  211,  553,  622,   57,   58,   48,  582,  581,
114703  /*   880 */   583,  583,   55,   55,   56,   56,   56,   56,  412,   54,
114704  /*   890 */    54,   54,   54,   53,   53,   52,   52,   52,   51,  234,
114705  /*   900 */   312,  412,  261,  412,  415,  412,  600,  210,  625,  367,
114706  /*   910 */    51,  234,  601,  100,  538,  606,  142,  415,  355,  415,
114707  /*   920 */   412,  415,  412,  496,  622,  601,   77,  601,   96,  601,
114708  /*   930 */   137,  590,  584,  530,  622,  529,  415,  141,  415,   28,
114709  /*   940 */   524,  600,  229,  544,  601,  136,  601,  135,  604,  204,
114710  /*   950 */    57,   58,   48,  582,  581,  583,  583,   55,   55,   56,
114711  /*   960 */    56,   56,   56,  412,   54,   54,   54,   54,   53,   53,
114712  /*   970 */    52,   52,   52,   51,  234,  312,  412,  360,  412,  415,
114713  /*   980 */   412,  360,  286,  600,  503,  220,  127,  601,   76,  629,
114714  /*   990 */   332,  382,  415,  622,  415,  540,  415,  622,  412,  613,
114715  /*  1000 */   601,   90,  601,   89,  601,   75,  590,  584,  341,  272,
114716  /*  1010 */   377,  622,  126,   27,  415,  622,  164,  544,  125,  280,
114717  /*  1020 */   373,  122,  601,   88,  480,   57,   46,   48,  582,  581,
114718  /*  1030 */   583,  583,   55,   55,   56,   56,   56,   56,  412,   54,
114719  /*  1040 */    54,   54,   54,   53,   53,   52,   52,   52,   51,  234,
114720  /*  1050 */   312,  412,  360,  412,  415,  412,  284,  186,  369,  321,
114721  /*  1060 */   477,  170,  601,   87,  121,  473,  221,  415,  622,  415,
114722  /*  1070 */   254,  415,  412,  355,  412,  601,   99,  601,   86,  601,
114723  /*  1080 */    17,  590,  584,  259,  612,  120,  159,  158,  415,  622,
114724  /*  1090 */   415,   14,  465,  157,  462,   25,  601,   85,  601,   84,
114725  /*  1100 */   622,   58,   48,  582,  581,  583,  583,   55,   55,   56,
114726  /*  1110 */    56,   56,   56,  412,   54,   54,   54,   54,   53,   53,
114727  /*  1120 */    52,   52,   52,   51,  234,  312,  412,  262,  412,  415,
114728  /*  1130 */   412,  262,  118,  611,  117,   24,   10,  601,   83,  351,
114729  /*  1140 */   216,  219,  415,  622,  415,  608,  415,  622,  412,  622,
114730  /*  1150 */   601,   72,  601,   71,  601,   82,  590,  584,  262,    4,
114731  /*  1160 */   605,  622,  458,  115,  415,  456,  252,  154,  452,  110,
114732  /*  1170 */   108,  453,  601,   81,  622,  451,  622,   48,  582,  581,
114733  /*  1180 */   583,  583,   55,   55,   56,   56,   56,   56,  412,   54,
114734  /*  1190 */    54,   54,   54,   53,   53,   52,   52,   52,   51,  234,
114735  /*  1200 */    44,  406,  450,    3,  415,  412,  262,  107,  416,  623,
114736  /*  1210 */   446,  437,  601,   80,  436,  335,  238,  189,  411,  409,
114737  /*  1220 */   594,  415,  622,   44,  406,  401,    3,  412,  557,  601,
114738  /*  1230 */    70,  416,  623,  412,  622,  149,  622,  421,  404,   64,
114739  /*  1240 */   412,  622,  409,  415,  622,  331,  139,  148,  566,  415,
114740  /*  1250 */   449,  601,   18,  228,  124,  626,  415,  601,   79,  315,
114741  /*  1260 */   181,  404,  412,  545,  601,   78,  262,  541,   41,   42,
114742  /*  1270 */   534,  566,  390,  202,  262,   43,  414,  413,  415,  622,
114743  /*  1280 */   595,  314,  622,  622,  180,  539,  601,   92,  415,  276,
114744  /*  1290 */   622,   41,   42,  509,  616,  615,  601,    9,   43,  414,
114745  /*  1300 */   413,  622,  418,  595,  262,  622,  275,  600,  614,  622,
114746  /*  1310 */   218,  593,  593,  593,  592,  591,   13,  178,  217,  417,
114747  /*  1320 */   622,  236,  622,   44,  406,  490,    3,  269,  399,  267,
114748  /*  1330 */   609,  416,  623,  400,  593,  593,  593,  592,  591,   13,
114749  /*  1340 */   265,  622,  409,  622,  263,  622,   34,  406,  244,    3,
114750  /*  1350 */   258,  363,  464,  463,  416,  623,  622,  356,  251,    8,
114751  /*  1360 */   622,  404,  177,  599,  455,  409,  622,  622,  622,  622,
114752  /*  1370 */   445,  566,  243,  622,  622,  236,  295,  240,   31,  239,
114753  /*  1380 */   622,  431,   30,  396,  404,  290,  622,  294,  622,  293,
114754  /*  1390 */   144,   41,   42,  622,  566,  622,  394,  622,   43,  414,
114755  /*  1400 */   413,  622,  289,  595,  398,   60,  622,  292,   37,  231,
114756  /*  1410 */   598,  172,  622,   29,   41,   42,  393,  523,  622,  556,
114757  /*  1420 */   184,   43,  414,  413,  287,  387,  595,  543,  285,  518,
114758  /*  1430 */   537,  536,  517,  327,  593,  593,  593,  592,  591,   13,
114759  /*  1440 */   215,  283,  278,  514,  513,  304,  303,  302,  179,  300,
114760  /*  1450 */   512,  310,  454,  128,  227,  226,  309,  593,  593,  593,
114761  /*  1460 */   592,  591,   13,  494,  489,  225,  488,  150,  487,  242,
114762  /*  1470 */   163,   61,  374,  481,  162,  161,  624,  623,  241,  372,
114763  /*  1480 */   209,  479,  370,  260,   26,  160,  478,  364,  468,  471,
114764  /*  1490 */   140,  152,  119,  467,  131,  116,  155,  153,  345,  457,
114765  /*  1500 */   151,  346,  130,  114,  113,  112,  111,  448,  319,   23,
114766  /*  1510 */   109,  434,   20,  433,  432,  429,  566,  610,  573,  596,
114767  /*  1520 */    63,  405,  191,  279,  510,  296,  498,  288,  570,  495,
114768  /*  1530 */   499,  497,  461,  194,    5,  305,  193,  192,  381,  569,
114769  /*  1540 */   357,  256,  344,  245,  526,  246,  253,  313,  595,  343,
114770  /*  1550 */   447,  297,  236,  402,  550,  491,  508,  502,  501,  527,
114771  /*  1560 */   234,  208,  525,  962,  962,  962,  371,  962,  962,  962,
114772  /*  1570 */   962,  962,  962,  962,  962,  337,  962,  962,  962,  593,
114773  /*  1580 */   593,  593,
114774 };
114775 static const YYCODETYPE yy_lookahead[] = {
114776  /*     0 */    19,  143,  144,  145,  146,   24,    7,    8,   27,   78,
114777  /*    10 */    79,   80,   81,   82,   83,   84,   85,   86,   87,   88,
114778  /*    20 */    89,   90,   91,   92,   93,  106,  107,  108,   27,   28,
114779  /*    30 */    15,   50,   51,   78,   79,   80,   81,   26,   83,   84,
114780  /*    40 */    85,   86,   87,   88,   89,   90,   91,   92,   93,    1,
114781  /*    50 */    69,   70,   71,   72,   73,   74,   75,   76,   77,   78,
114782  /*    60 */    79,   80,   81,   11,   83,   84,   85,   86,   87,   88,
114783  /*    70 */    89,   90,   91,   92,   93,   19,   95,   89,   90,   91,
114784  /*    80 */    92,   93,   26,   83,   84,   85,   86,   87,   88,   89,
114785  /*    90 */    90,   91,   92,   93,   27,   28,   95,   96,   97,   27,
114786  /*   100 */    28,  100,  101,  102,   22,   19,   50,   51,   27,   28,
114787  /*   110 */    58,   55,  111,    7,    8,    9,   87,   88,   89,   90,
114788  /*   120 */    91,   92,   93,   98,   99,   69,   70,   71,   72,   73,
114789  /*   130 */    74,   75,   76,   77,   78,   79,   80,   81,  127,   83,
114790  /*   140 */    84,   85,   86,   87,   88,   89,   90,   91,   92,   93,
114791  /*   150 */    19,  223,  224,  225,   87,   88,  162,   31,  106,  107,
114792  /*   160 */   108,   35,   95,   96,   33,   98,   23,   95,   96,  117,
114793  /*   170 */   119,  243,  105,   42,  107,   49,   95,   96,  151,   93,
114794  /*   180 */    26,   50,   51,   97,   98,   99,  100,  101,  102,  103,
114795  /*   190 */   196,   22,   23,  121,  167,   26,  110,  130,  131,   67,
114796  /*   200 */    69,   70,   71,   72,   73,   74,   75,   76,   77,   78,
114797  /*   210 */    79,   80,   81,  219,   83,   84,   85,   86,   87,   88,
114798  /*   220 */    89,   90,   91,   92,   93,   19,   12,   95,  234,  119,
114799  /*   230 */    24,   99,  113,  239,  115,  116,  151,   68,   23,  147,
114800  /*   240 */   148,   26,  215,   29,  151,  153,  119,  155,  163,  164,
114801  /*   250 */    23,   23,  167,   26,  162,   23,   50,   51,   26,   45,
114802  /*   260 */   167,   47,  130,  131,  132,  172,  173,   23,   22,   23,
114803  /*   270 */    26,  186,   26,  188,  120,   69,   70,   71,   72,   73,
114804  /*   280 */    74,   75,   76,   77,   78,   79,   80,   81,  196,   83,
114805  /*   290 */    84,   85,   86,   87,   88,   89,   90,   91,   92,   93,
114806  /*   300 */    19,  151,  151,   23,  119,   97,   26,   19,  100,  101,
114807  /*   310 */   102,  219,  151,  162,   68,   22,   28,  167,  167,  111,
114808  /*   320 */    27,   26,  172,  173,  231,  232,  175,  176,  167,   27,
114809  /*   330 */    28,   50,   51,   27,   28,  119,  175,  176,  246,   24,
114810  /*   340 */    22,  113,   27,  115,  116,   27,   28,  196,   22,   23,
114811  /*   350 */    69,   70,   71,   72,   73,   74,   75,   76,   77,   78,
114812  /*   360 */    79,   80,   81,  114,   83,   84,   85,   86,   87,   88,
114813  /*   370 */    89,   90,   91,   92,   93,   19,   21,  151,  217,   22,
114814  /*   380 */   151,  231,  232,  222,   27,   28,   23,  114,   95,   50,
114815  /*   390 */    51,  118,  151,  167,   68,   89,  167,   95,   96,  104,
114816  /*   400 */    23,   95,   96,   26,  175,  176,   50,   51,  167,   22,
114817  /*   410 */    95,   72,   73,   95,   96,   16,  175,  176,  137,   64,
114818  /*   420 */    23,  195,   27,  121,   23,   69,   70,   71,   72,   73,
114819  /*   430 */    74,   75,   76,   77,   78,   79,   80,   81,   99,   83,
114820  /*   440 */    84,   85,   86,   87,   88,   89,   90,   91,   92,   93,
114821  /*   450 */    19,   12,   95,   96,   23,  226,  101,   22,  217,   19,
114822  /*   460 */    61,  151,   63,  222,  151,  106,  107,  108,   29,  159,
114823  /*   470 */   244,  151,   99,  163,  164,   23,  113,  167,  115,  116,
114824  /*   480 */   167,   50,   51,  110,   45,   58,   47,  167,  175,  176,
114825  /*   490 */    95,   51,  168,  137,  139,  175,  176,   58,   11,   22,
114826  /*   500 */    69,   70,   71,   72,   73,   74,   75,   76,   77,   78,
114827  /*   510 */    79,   80,   81,   22,   83,   84,   85,   86,   87,   88,
114828  /*   520 */    89,   90,   91,   92,   93,   19,   23,  151,  117,   23,
114829  /*   530 */   217,  207,   19,  106,  107,  108,  216,  151,  139,   23,
114830  /*   540 */   129,   28,   26,  167,  117,  105,   23,  223,  224,  225,
114831  /*   550 */   110,  175,  176,  167,   77,  165,   50,   51,  168,  169,
114832  /*   560 */   170,  175,  176,   87,   88,  113,   26,  115,  116,  171,
114833  /*   570 */   172,  173,    0,    1,    2,   69,   70,   71,   72,   73,
114834  /*   580 */    74,   75,   76,   77,   78,   79,   80,   81,  162,   83,
114835  /*   590 */    84,   85,   86,   87,   88,   89,   90,   91,   92,   93,
114836  /*   600 */    19,  151,   98,  217,   23,   37,  130,  131,   23,   23,
114837  /*   610 */    26,   26,   96,  163,  164,   23,  113,  167,  115,  116,
114838  /*   620 */    52,  117,  196,  151,  171,  172,  173,   59,  130,  131,
114839  /*   630 */   232,   50,   51,  129,  208,  209,   16,  121,  156,  167,
114840  /*   640 */    22,   23,  162,  223,  224,  225,   51,  175,  176,  121,
114841  /*   650 */    69,   70,   71,   72,   73,   74,   75,   76,   77,   78,
114842  /*   660 */    79,   80,   81,  178,   83,   84,   85,   86,   87,   88,
114843  /*   670 */    89,   90,   91,   92,   93,   19,  196,  109,  151,   23,
114844  /*   680 */    96,   61,  151,   63,   23,  232,   68,   26,  151,  168,
114845  /*   690 */   169,  170,   23,   89,  167,   26,  208,  209,  167,  219,
114846  /*   700 */   105,   36,  175,  176,  167,  121,   50,   51,  223,  224,
114847  /*   710 */   225,  229,  175,  176,  178,  233,  247,  248,  114,  239,
114848  /*   720 */   189,   22,  118,   24,  162,   69,   70,   71,   72,   73,
114849  /*   730 */    74,   75,   76,   77,   78,   79,   80,   81,  151,   83,
114850  /*   740 */    84,   85,   86,   87,   88,   89,   90,   91,   92,   93,
114851  /*   750 */    19,  151,   26,  151,  167,   24,  145,  146,  196,  223,
114852  /*   760 */   224,  225,  175,  176,  151,  182,  183,  167,  151,  167,
114853  /*   770 */   151,   36,  199,  190,  151,  175,  176,  175,  176,  206,
114854  /*   780 */   167,   50,   51,  221,  167,  136,  167,  138,  175,  176,
114855  /*   790 */   167,   26,  175,  176,  175,  176,  168,   36,  175,  176,
114856  /*   800 */    69,   70,   71,   72,   73,   74,   75,   76,   77,   78,
114857  /*   810 */    79,   80,   81,  151,   83,   84,   85,   86,   87,   88,
114858  /*   820 */    89,   90,   91,   92,   93,   19,  151,  151,  151,  167,
114859  /*   830 */   151,  151,  151,  151,  162,  207,   23,  175,  176,   26,
114860  /*   840 */   249,  250,  167,  167,  167,  151,  167,  167,  167,  167,
114861  /*   850 */   175,  176,  175,  176,  175,  176,   50,   51,  151,   53,
114862  /*   860 */    22,  167,  192,  193,   33,  189,  192,  193,  196,  189,
114863  /*   870 */   189,  189,  162,   42,  167,   69,   70,   71,   72,   73,
114864  /*   880 */    74,   75,   76,   77,   78,   79,   80,   81,  151,   83,
114865  /*   890 */    84,   85,   86,   87,   88,   89,   90,   91,   92,   93,
114866  /*   900 */    19,  151,  195,  151,  167,  151,  196,  162,  151,  215,
114867  /*   910 */    92,   93,  175,  176,   28,  174,  119,  167,  151,  167,
114868  /*   920 */   151,  167,  151,  182,  167,  175,  176,  175,  176,  175,
114869  /*   930 */   176,   50,   51,   23,  167,   23,  167,   40,  167,   22,
114870  /*   940 */   167,  196,   53,  168,  175,  176,  175,  176,  175,  162,
114871  /*   950 */    69,   70,   71,   72,   73,   74,   75,   76,   77,   78,
114872  /*   960 */    79,   80,   81,  151,   83,   84,   85,   86,   87,   88,
114873  /*   970 */    89,   90,   91,   92,   93,   19,  151,  151,  151,  167,
114874  /*   980 */   151,  151,  207,  196,   30,  218,   22,  175,  176,    1,
114875  /*   990 */     2,   53,  167,  167,  167,  151,  167,  167,  151,  151,
114876  /*  1000 */   175,  176,  175,  176,  175,  176,   50,   51,  221,   23,
114877  /*  1010 */    53,  167,   22,   22,  167,  167,  103,  168,   22,  110,
114878  /*  1020 */    19,  105,  175,  176,   20,   69,   70,   71,   72,   73,
114879  /*  1030 */    74,   75,   76,   77,   78,   79,   80,   81,  151,   83,
114880  /*  1040 */    84,   85,   86,   87,   88,   89,   90,   91,   92,   93,
114881  /*  1050 */    19,  151,  151,  151,  167,  151,  207,   24,   44,  215,
114882  /*  1060 */    60,   26,  175,  176,   54,   54,  240,  167,  167,  167,
114883  /*  1070 */   240,  167,  151,  151,  151,  175,  176,  175,  176,  175,
114884  /*  1080 */   176,   50,   51,  139,  151,   22,  105,  119,  167,  167,
114885  /*  1090 */   167,    5,    1,   36,   28,   77,  175,  176,  175,  176,
114886  /*  1100 */   167,   70,   71,   72,   73,   74,   75,   76,   77,   78,
114887  /*  1110 */    79,   80,   81,  151,   83,   84,   85,   86,   87,   88,
114888  /*  1120 */    89,   90,   91,   92,   93,   19,  151,  151,  151,  167,
114889  /*  1130 */   151,  151,  109,  151,  128,   77,   22,  175,  176,   26,
114890  /*  1140 */   218,  240,  167,  167,  167,  151,  167,  167,  151,  167,
114891  /*  1150 */   175,  176,  175,  176,  175,  176,   50,   51,  151,   22,
114892  /*  1160 */   151,  167,   23,  120,  167,    1,   16,  122,   20,  120,
114893  /*  1170 */   109,  195,  175,  176,  167,  195,  167,   71,   72,   73,
114894  /*  1180 */    74,   75,   76,   77,   78,   79,   80,   81,  151,   83,
114895  /*  1190 */    84,   85,   86,   87,   88,   89,   90,   91,   92,   93,
114896  /*  1200 */    19,   20,  195,   22,  167,  151,  151,  128,   27,   28,
114897  /*  1210 */   129,   23,  175,  176,   23,   66,  141,   22,  151,   38,
114898  /*  1220 */   151,  167,  167,   19,   20,  151,   22,  151,  151,  175,
114899  /*  1230 */   176,   27,   28,  151,  167,   15,  167,    4,   57,   16,
114900  /*  1240 */   151,  167,   38,  167,  167,    3,  166,  248,   67,  167,
114901  /*  1250 */   195,  175,  176,  181,  181,  150,  167,  175,  176,  251,
114902  /*  1260 */     6,   57,  151,  151,  175,  176,  151,  151,   87,   88,
114903  /*  1270 */    89,   67,  151,  162,  151,   94,   95,   96,  167,  167,
114904  /*  1280 */    99,  251,  167,  167,  152,  151,  175,  176,  167,  151,
114905  /*  1290 */   167,   87,   88,  151,  150,  150,  175,  176,   94,   95,
114906  /*  1300 */    96,  167,  150,   99,  151,  167,  151,  196,   13,  167,
114907  /*  1310 */   195,  130,  131,  132,  133,  134,  135,  152,  195,  160,
114908  /*  1320 */   167,  117,  167,   19,   20,  151,   22,  151,  217,  151,
114909  /*  1330 */   161,   27,   28,  222,  130,  131,  132,  133,  134,  135,
114910  /*  1340 */   151,  167,   38,  167,  151,  167,   19,   20,  195,   22,
114911  /*  1350 */   151,  151,  151,  151,   27,   28,  167,  151,  151,   26,
114912  /*  1360 */   167,   57,   25,  196,  151,   38,  167,  167,  167,  167,
114913  /*  1370 */   151,   67,  151,  167,  167,  117,  201,  151,  125,  151,
114914  /*  1380 */   167,  151,  127,  124,   57,  151,  167,  202,  167,  203,
114915  /*  1390 */   151,   87,   88,  167,   67,  167,  151,  167,   94,   95,
114916  /*  1400 */    96,  167,  151,   99,  123,  126,  167,  204,  136,  227,
114917  /*  1410 */   205,  119,  167,  105,   87,   88,  122,  177,  167,  158,
114918  /*  1420 */   158,   94,   95,   96,  212,  105,   99,  213,  212,  177,
114919  /*  1430 */   213,  213,  185,   48,  130,  131,  132,  133,  134,  135,
114920  /*  1440 */     5,  212,  177,  179,  104,   10,   11,   12,   13,   14,
114921  /*  1450 */   177,  180,   17,   22,  230,   93,  180,  130,  131,  132,
114922  /*  1460 */   133,  134,  135,  185,  177,  230,  177,   32,  177,   34,
114923  /*  1470 */   157,   22,   18,  158,  157,  157,   27,   28,   43,  158,
114924  /*  1480 */   158,  158,   46,  237,  136,  157,  238,  158,  191,  201,
114925  /*  1490 */    69,   56,  191,   58,  220,   22,  157,   62,   18,  201,
114926  /*  1500 */    65,  158,  220,  194,  194,  194,  194,  201,  158,  242,
114927  /*  1510 */   191,   41,  242,  158,  158,   39,   67,  154,  232,  168,
114928  /*  1520 */   245,  228,  198,  178,  183,  200,  168,  211,  232,  168,
114929  /*  1530 */   178,  178,  201,  187,  198,  149,   87,   88,  179,  168,
114930  /*  1540 */   241,  106,  107,  108,   95,  211,  241,  112,   99,  211,
114931  /*  1550 */   201,  197,  117,  193,  210,  188,  184,  184,  184,  175,
114932  /*  1560 */    93,  235,  175,  252,  252,  252,  236,  252,  252,  252,
114933  /*  1570 */   252,  252,  252,  252,  252,  140,  252,  252,  252,  130,
114934  /*  1580 */   131,  132,
114935 };
114936 #define YY_SHIFT_USE_DFLT (-82)
114937 #define YY_SHIFT_COUNT (419)
114938 #define YY_SHIFT_MIN   (-81)
114939 #define YY_SHIFT_MAX   (1480)
114940 static const short yy_shift_ofst[] = {
114941  /*     0 */   988, 1204, 1435, 1204, 1304, 1304,   67,   67,    1,  -19,
114942  /*    10 */  1304, 1304, 1304, 1304,  427,   81,  131,  131,  806, 1181,
114943  /*    20 */  1304, 1304, 1304, 1304, 1304, 1304, 1304, 1304, 1304, 1304,
114944  /*    30 */  1304, 1304, 1304, 1304, 1304, 1304, 1304, 1304, 1304, 1304,
114945  /*    40 */  1304, 1304, 1304, 1304, 1304, 1304, 1304, 1304, 1327, 1304,
114946  /*    50 */  1304, 1304, 1304, 1304, 1304, 1304, 1304, 1304, 1304, 1304,
114947  /*    60 */  1304, 1304,   52,   81,   81,  476,  476,  395, 1258,   56,
114948  /*    70 */   731,  656,  581,  506,  431,  356,  281,  206,  881,  881,
114949  /*    80 */   881,  881,  881,  881,  881,  881,  881,  881,  881,  881,
114950  /*    90 */   881,  881,  881,  956,  881, 1031, 1106, 1106,  -69,  -45,
114951  /*   100 */   -45,  -45,  -45,  -45,    0,   29,  -12,   81,   81,   81,
114952  /*   110 */    81,   81,   81,   81,   81,   81,   81,   81,   81,   81,
114953  /*   120 */    81,   81,   81,  355,  440,   81,   81,   81,   81,   81,
114954  /*   130 */   504,  411,  395,  818, 1467,  -82,  -82,  -82, 1449,   86,
114955  /*   140 */   439,  439,  306,  357,  302,   72,  318,  246,  169,   81,
114956  /*   150 */    81,   81,   81,   81,   81,   81,   81,   81,   81,   81,
114957  /*   160 */    81,   81,   81,   81,   81,   81,   81,   81,   81,   81,
114958  /*   170 */    81,   81,   81,   81,   81,   81,   81,   81,   81,   81,
114959  /*   180 */    81,   81,  315,  315,  315,  572, 1258, 1258, 1258,  -82,
114960  /*   190 */   -82,  -82,  132,  132,  208,  568,  568,  568,  516,  503,
114961  /*   200 */   214,  452,  363,  228,  119,  119,  119,  119,  359,  126,
114962  /*   210 */   119,  119,  584,  293,  604,  106,   11,  288,  288,  513,
114963  /*   220 */    11,  513,  295,  813,  395,  831,  395,  831,  595,  831,
114964  /*   230 */   288,  649,  498,  498,  395,  154,  273,  699, 1476, 1292,
114965  /*   240 */  1292, 1470, 1470, 1292, 1473, 1421, 1255, 1480, 1480, 1480,
114966  /*   250 */  1480, 1292, 1454, 1255, 1473, 1421, 1421, 1255, 1292, 1454,
114967  /*   260 */  1348, 1436, 1292, 1292, 1454, 1292, 1454, 1292, 1454, 1431,
114968  /*   270 */  1320, 1320, 1320, 1385, 1362, 1362, 1431, 1320, 1340, 1320,
114969  /*   280 */  1385, 1320, 1320, 1294, 1308, 1294, 1308, 1294, 1308, 1292,
114970  /*   290 */  1292, 1272, 1279, 1281, 1253, 1259, 1255, 1258, 1337, 1333,
114971  /*   300 */  1295, 1295, 1254, 1254, 1254, 1254,  -82,  -82,  -82,  -82,
114972  /*   310 */   -82,  -82,  339,  399,  618,  326,  620,  -81,  669,  477,
114973  /*   320 */   661,  585,  377,  280,  244,  232,   25,   -1,  373,  227,
114974  /*   330 */   215, 1233, 1242, 1195, 1075, 1220, 1149, 1223, 1191, 1188,
114975  /*   340 */  1081, 1113, 1079, 1061, 1049, 1148, 1045, 1150, 1164, 1043,
114976  /*   350 */  1139, 1137, 1113, 1114, 1006, 1058, 1018, 1023, 1066, 1057,
114977  /*   360 */   968, 1091, 1086, 1063,  981,  944, 1011, 1035, 1010, 1000,
114978  /*   370 */  1014,  916, 1033, 1004, 1001,  909,  913,  996,  957,  991,
114979  /*   380 */   990,  986,  964,  938,  954,  917,  889,  897,  912,  910,
114980  /*   390 */   797,  886,  761,  838,  528,  726,  735,  765,  665,  726,
114981  /*   400 */   592,  586,  540,  523,  491,  487,  435,  401,  397,  387,
114982  /*   410 */   249,  216,  185,  127,  110,   51,   82,  143,   15,   48,
114983 };
114984 #define YY_REDUCE_USE_DFLT (-143)
114985 #define YY_REDUCE_COUNT (311)
114986 #define YY_REDUCE_MIN   (-142)
114987 #define YY_REDUCE_MAX   (1387)
114988 static const short yy_reduce_ofst[] = {
114989  /*     0 */  -142, 1111,   92,  151,  241,  161,  150,   93,   85,  324,
114990  /*    10 */   386,  313,  320,  229,   -6,  310,  536,  485,  -72, 1121,
114991  /*    20 */  1089, 1082, 1076, 1054, 1037,  997,  979,  977,  975,  962,
114992  /*    30 */   923,  921,  904,  902,  900,  887,  847,  829,  827,  825,
114993  /*    40 */   812,  771,  769,  754,  752,  750,  737,  679,  677,  675,
114994  /*    50 */   662,  623,  619,  617,  613,  602,  600,  587,  537,  527,
114995  /*    60 */   472,  376,  480,  450,  226,  453,  398,  390,  426,  420,
114996  /*    70 */   420,  420,  420,  420,  420,  420,  420,  420,  420,  420,
114997  /*    80 */   420,  420,  420,  420,  420,  420,  420,  420,  420,  420,
114998  /*    90 */   420,  420,  420,  420,  420,  420,  420,  420,  420,  420,
114999  /*   100 */   420,  420,  420,  420,  420,  420,  420, 1153,  922, 1123,
115000  /*   110 */  1115, 1055, 1007,  980,  976,  901,  844,  830,  767,  826,
115001  /*   120 */   682,  694,  707,  482,  583,  681,  680,  676,  531,   27,
115002  /*   130 */   787,  562,  521,  420,  420,  420,  420,  420,  773,  741,
115003  /*   140 */   674,  670, 1067, 1251, 1245, 1239, 1234,  591,  591, 1230,
115004  /*   150 */  1228, 1226, 1221, 1219, 1213, 1207, 1206, 1202, 1201, 1200,
115005  /*   160 */  1199, 1193, 1189, 1178, 1176, 1174, 1155, 1142, 1138, 1134,
115006  /*   170 */  1116, 1112, 1077, 1074, 1069, 1067, 1009,  994,  982,  933,
115007  /*   180 */   848,  757,  849,  775,  628,  611,  745,  710,  672,  469,
115008  /*   190 */   488,  573, 1387, 1384, 1367, 1374, 1373, 1372, 1344, 1354,
115009  /*   200 */  1360, 1354, 1354, 1354, 1354, 1354, 1354, 1354, 1330, 1326,
115010  /*   210 */  1354, 1354, 1344, 1371, 1336, 1386, 1349, 1338, 1334, 1305,
115011  /*   220 */  1331, 1299, 1359, 1346, 1361, 1353, 1358, 1352, 1341, 1345,
115012  /*   230 */  1316, 1293, 1296, 1286, 1351, 1325, 1324, 1363, 1275, 1356,
115013  /*   240 */  1355, 1270, 1267, 1350, 1282, 1319, 1306, 1312, 1311, 1310,
115014  /*   250 */  1309, 1343, 1339, 1298, 1274, 1301, 1297, 1288, 1329, 1328,
115015  /*   260 */  1248, 1246, 1323, 1322, 1318, 1321, 1317, 1315, 1313, 1276,
115016  /*   270 */  1291, 1289, 1287, 1278, 1235, 1224, 1271, 1273, 1264, 1265,
115017  /*   280 */  1247, 1252, 1240, 1218, 1229, 1217, 1216, 1214, 1212, 1262,
115018  /*   290 */  1261, 1182, 1205, 1203, 1186, 1185, 1175, 1167, 1169, 1159,
115019  /*   300 */  1165, 1132, 1152, 1145, 1144, 1105, 1030, 1008,  999, 1073,
115020  /*   310 */  1072, 1080,
115021 };
115022 static const YYACTIONTYPE yy_default[] = {
115023  /*     0 */   636,  872,  960,  960,  872,  872,  960,  960,  960,  762,
115024  /*    10 */   960,  960,  960,  870,  960,  960,  790,  790,  934,  960,
115025  /*    20 */   960,  960,  960,  960,  960,  960,  960,  960,  960,  960,
115026  /*    30 */   960,  960,  960,  960,  960,  960,  960,  960,  960,  960,
115027  /*    40 */   960,  960,  960,  960,  960,  960,  960,  960,  960,  960,
115028  /*    50 */   960,  960,  960,  960,  960,  960,  960,  960,  960,  960,
115029  /*    60 */   960,  960,  960,  960,  960,  960,  960,  677,  766,  796,
115030  /*    70 */   960,  960,  960,  960,  960,  960,  960,  960,  933,  935,
115031  /*    80 */   804,  803,  913,  777,  801,  794,  798,  873,  866,  867,
115032  /*    90 */   865,  869,  874,  960,  797,  833,  850,  832,  844,  849,
115033  /*   100 */   856,  848,  845,  835,  834,  836,  837,  960,  960,  960,
115034  /*   110 */   960,  960,  960,  960,  960,  960,  960,  960,  960,  960,
115035  /*   120 */   960,  960,  960,  662,  731,  960,  960,  960,  960,  960,
115036  /*   130 */   960,  960,  960,  838,  839,  853,  852,  851,  960,  669,
115037  /*   140 */   960,  960,  960,  960,  960,  960,  960,  960,  960,  960,
115038  /*   150 */   940,  938,  960,  885,  960,  960,  960,  960,  960,  960,
115039  /*   160 */   960,  960,  960,  960,  960,  960,  960,  960,  960,  960,
115040  /*   170 */   960,  960,  960,  960,  960,  960,  960,  960,  960,  960,
115041  /*   180 */   960,  642,  762,  762,  762,  636,  960,  960,  960,  952,
115042  /*   190 */   766,  756,  960,  960,  960,  960,  960,  960,  960,  960,
115043  /*   200 */   960,  960,  960,  960,  806,  745,  923,  925,  960,  906,
115044  /*   210 */   743,  664,  764,  679,  754,  644,  800,  779,  779,  918,
115045  /*   220 */   800,  918,  702,  725,  960,  790,  960,  790,  699,  790,
115046  /*   230 */   779,  868,  960,  960,  960,  763,  754,  960,  945,  770,
115047  /*   240 */   770,  937,  937,  770,  812,  735,  800,  742,  742,  742,
115048  /*   250 */   742,  770,  659,  800,  812,  735,  735,  800,  770,  659,
115049  /*   260 */   912,  910,  770,  770,  659,  770,  659,  770,  659,  878,
115050  /*   270 */   733,  733,  733,  717,  882,  882,  878,  733,  702,  733,
115051  /*   280 */   717,  733,  733,  783,  778,  783,  778,  783,  778,  770,
115052  /*   290 */   770,  960,  795,  784,  793,  791,  800,  960,  665,  720,
115053  /*   300 */   652,  652,  641,  641,  641,  641,  957,  957,  952,  704,
115054  /*   310 */   704,  687,  960,  960,  960,  960,  960,  960,  960,  887,
115055  /*   320 */   960,  960,  960,  960,  960,  960,  960,  960,  960,  960,
115056  /*   330 */   960,  960,  637,  947,  960,  960,  944,  960,  960,  960,
115057  /*   340 */   960,  805,  960,  960,  960,  960,  960,  960,  960,  960,
115058  /*   350 */   960,  960,  922,  960,  960,  960,  960,  960,  960,  960,
115059  /*   360 */   916,  960,  960,  960,  960,  960,  960,  909,  908,  960,
115060  /*   370 */   960,  960,  960,  960,  960,  960,  960,  960,  960,  960,
115061  /*   380 */   960,  960,  960,  960,  960,  960,  960,  960,  960,  960,
115062  /*   390 */   960,  960,  960,  960,  960,  792,  960,  785,  960,  871,
115063  /*   400 */   960,  960,  960,  960,  960,  960,  960,  960,  960,  960,
115064  /*   410 */   748,  821,  960,  820,  824,  819,  671,  960,  650,  960,
115065  /*   420 */   633,  638,  956,  959,  958,  955,  954,  953,  948,  946,
115066  /*   430 */   943,  942,  941,  939,  936,  932,  891,  889,  896,  895,
115067  /*   440 */   894,  893,  892,  890,  888,  886,  807,  802,  799,  931,
115068  /*   450 */   884,  744,  741,  740,  658,  949,  915,  924,  811,  810,
115069  /*   460 */   813,  921,  920,  919,  917,  914,  901,  809,  808,  736,
115070  /*   470 */   876,  875,  661,  905,  904,  903,  907,  911,  902,  772,
115071  /*   480 */   660,  657,  668,  723,  724,  732,  730,  729,  728,  727,
115072  /*   490 */   726,  722,  670,  678,  716,  701,  700,  881,  883,  880,
115073  /*   500 */   879,  709,  708,  714,  713,  712,  711,  710,  707,  706,
115074  /*   510 */   705,  698,  697,  703,  696,  719,  718,  715,  695,  739,
115075  /*   520 */   738,  737,  734,  694,  693,  692,  824,  691,  690,  830,
115076  /*   530 */   829,  817,  860,  759,  758,  757,  769,  768,  781,  780,
115077  /*   540 */   815,  814,  782,  767,  761,  760,  776,  775,  774,  773,
115078  /*   550 */   765,  755,  787,  789,  788,  786,  862,  771,  859,  930,
115079  /*   560 */   929,  928,  927,  926,  864,  863,  831,  828,  682,  683,
115080  /*   570 */   899,  898,  900,  897,  685,  684,  681,  680,  861,  750,
115081  /*   580 */   749,  857,  854,  846,  842,  858,  855,  847,  843,  841,
115082  /*   590 */   840,  826,  825,  823,  822,  818,  827,  673,  751,  747,
115083  /*   600 */   746,  816,  753,  752,  689,  688,  686,  667,  666,  663,
115084  /*   610 */   656,  654,  653,  655,  651,  649,  648,  647,  646,  645,
115085  /*   620 */   676,  675,  674,  672,  671,  643,  640,  639,  635,  634,
115086  /*   630 */   632,
115087 };
115088 
115089 /* The next table maps tokens into fallback tokens.  If a construct
115090 ** like the following:
115091 ** 
115092 **      %fallback ID X Y Z.
115093 **
115094 ** appears in the grammar, then ID becomes a fallback token for X, Y,
115095 ** and Z.  Whenever one of the tokens X, Y, or Z is input to the parser
115096 ** but it does not parse, the type of the token is changed to ID and
115097 ** the parse is retried before an error is thrown.
115098 */
115099 #ifdef YYFALLBACK
115100 static const YYCODETYPE yyFallback[] = {
115101     0,  /*          $ => nothing */
115102     0,  /*       SEMI => nothing */
115103    27,  /*    EXPLAIN => ID */
115104    27,  /*      QUERY => ID */
115105    27,  /*       PLAN => ID */
115106    27,  /*      BEGIN => ID */
115107     0,  /* TRANSACTION => nothing */
115108    27,  /*   DEFERRED => ID */
115109    27,  /*  IMMEDIATE => ID */
115110    27,  /*  EXCLUSIVE => ID */
115111     0,  /*     COMMIT => nothing */
115112    27,  /*        END => ID */
115113    27,  /*   ROLLBACK => ID */
115114    27,  /*  SAVEPOINT => ID */
115115    27,  /*    RELEASE => ID */
115116     0,  /*         TO => nothing */
115117     0,  /*      TABLE => nothing */
115118     0,  /*     CREATE => nothing */
115119    27,  /*         IF => ID */
115120     0,  /*        NOT => nothing */
115121     0,  /*     EXISTS => nothing */
115122    27,  /*       TEMP => ID */
115123     0,  /*         LP => nothing */
115124     0,  /*         RP => nothing */
115125     0,  /*         AS => nothing */
115126    27,  /*    WITHOUT => ID */
115127     0,  /*      COMMA => nothing */
115128     0,  /*         ID => nothing */
115129     0,  /*    INDEXED => nothing */
115130    27,  /*      ABORT => ID */
115131    27,  /*     ACTION => ID */
115132    27,  /*      AFTER => ID */
115133    27,  /*    ANALYZE => ID */
115134    27,  /*        ASC => ID */
115135    27,  /*     ATTACH => ID */
115136    27,  /*     BEFORE => ID */
115137    27,  /*         BY => ID */
115138    27,  /*    CASCADE => ID */
115139    27,  /*       CAST => ID */
115140    27,  /*   COLUMNKW => ID */
115141    27,  /*   CONFLICT => ID */
115142    27,  /*   DATABASE => ID */
115143    27,  /*       DESC => ID */
115144    27,  /*     DETACH => ID */
115145    27,  /*       EACH => ID */
115146    27,  /*       FAIL => ID */
115147    27,  /*        FOR => ID */
115148    27,  /*     IGNORE => ID */
115149    27,  /*  INITIALLY => ID */
115150    27,  /*    INSTEAD => ID */
115151    27,  /*    LIKE_KW => ID */
115152    27,  /*      MATCH => ID */
115153    27,  /*         NO => ID */
115154    27,  /*        KEY => ID */
115155    27,  /*         OF => ID */
115156    27,  /*     OFFSET => ID */
115157    27,  /*     PRAGMA => ID */
115158    27,  /*      RAISE => ID */
115159    27,  /*    REPLACE => ID */
115160    27,  /*   RESTRICT => ID */
115161    27,  /*        ROW => ID */
115162    27,  /*    TRIGGER => ID */
115163    27,  /*     VACUUM => ID */
115164    27,  /*       VIEW => ID */
115165    27,  /*    VIRTUAL => ID */
115166    27,  /*    REINDEX => ID */
115167    27,  /*     RENAME => ID */
115168    27,  /*   CTIME_KW => ID */
115169 };
115170 #endif /* YYFALLBACK */
115171 
115172 /* The following structure represents a single element of the
115173 ** parser's stack.  Information stored includes:
115174 **
115175 **   +  The state number for the parser at this level of the stack.
115176 **
115177 **   +  The value of the token stored at this level of the stack.
115178 **      (In other words, the "major" token.)
115179 **
115180 **   +  The semantic value stored at this level of the stack.  This is
115181 **      the information used by the action routines in the grammar.
115182 **      It is sometimes called the "minor" token.
115183 */
115184 struct yyStackEntry {
115185   YYACTIONTYPE stateno;  /* The state-number */
115186   YYCODETYPE major;      /* The major token value.  This is the code
115187                          ** number for the token at this stack level */
115188   YYMINORTYPE minor;     /* The user-supplied minor token value.  This
115189                          ** is the value of the token  */
115190 };
115191 typedef struct yyStackEntry yyStackEntry;
115192 
115193 /* The state of the parser is completely contained in an instance of
115194 ** the following structure */
115195 struct yyParser {
115196   int yyidx;                    /* Index of top element in stack */
115197 #ifdef YYTRACKMAXSTACKDEPTH
115198   int yyidxMax;                 /* Maximum value of yyidx */
115199 #endif
115200   int yyerrcnt;                 /* Shifts left before out of the error */
115201   sqlite3ParserARG_SDECL                /* A place to hold %extra_argument */
115202 #if YYSTACKDEPTH<=0
115203   int yystksz;                  /* Current side of the stack */
115204   yyStackEntry *yystack;        /* The parser's stack */
115205 #else
115206   yyStackEntry yystack[YYSTACKDEPTH];  /* The parser's stack */
115207 #endif
115208 };
115209 typedef struct yyParser yyParser;
115210 
115211 #ifndef NDEBUG
115212 /* #include <stdio.h> */
115213 static FILE *yyTraceFILE = 0;
115214 static char *yyTracePrompt = 0;
115215 #endif /* NDEBUG */
115216 
115217 #ifndef NDEBUG
115218 /* 
115219 ** Turn parser tracing on by giving a stream to which to write the trace
115220 ** and a prompt to preface each trace message.  Tracing is turned off
115221 ** by making either argument NULL 
115222 **
115223 ** Inputs:
115224 ** <ul>
115225 ** <li> A FILE* to which trace output should be written.
115226 **      If NULL, then tracing is turned off.
115227 ** <li> A prefix string written at the beginning of every
115228 **      line of trace output.  If NULL, then tracing is
115229 **      turned off.
115230 ** </ul>
115231 **
115232 ** Outputs:
115233 ** None.
115234 */
115235 SQLITE_PRIVATE void sqlite3ParserTrace(FILE *TraceFILE, char *zTracePrompt){
115236   yyTraceFILE = TraceFILE;
115237   yyTracePrompt = zTracePrompt;
115238   if( yyTraceFILE==0 ) yyTracePrompt = 0;
115239   else if( yyTracePrompt==0 ) yyTraceFILE = 0;
115240 }
115241 #endif /* NDEBUG */
115242 
115243 #ifndef NDEBUG
115244 /* For tracing shifts, the names of all terminals and nonterminals
115245 ** are required.  The following table supplies these names */
115246 static const char *const yyTokenName[] = { 
115247   "$",             "SEMI",          "EXPLAIN",       "QUERY",       
115248   "PLAN",          "BEGIN",         "TRANSACTION",   "DEFERRED",    
115249   "IMMEDIATE",     "EXCLUSIVE",     "COMMIT",        "END",         
115250   "ROLLBACK",      "SAVEPOINT",     "RELEASE",       "TO",          
115251   "TABLE",         "CREATE",        "IF",            "NOT",         
115252   "EXISTS",        "TEMP",          "LP",            "RP",          
115253   "AS",            "WITHOUT",       "COMMA",         "ID",          
115254   "INDEXED",       "ABORT",         "ACTION",        "AFTER",       
115255   "ANALYZE",       "ASC",           "ATTACH",        "BEFORE",      
115256   "BY",            "CASCADE",       "CAST",          "COLUMNKW",    
115257   "CONFLICT",      "DATABASE",      "DESC",          "DETACH",      
115258   "EACH",          "FAIL",          "FOR",           "IGNORE",      
115259   "INITIALLY",     "INSTEAD",       "LIKE_KW",       "MATCH",       
115260   "NO",            "KEY",           "OF",            "OFFSET",      
115261   "PRAGMA",        "RAISE",         "REPLACE",       "RESTRICT",    
115262   "ROW",           "TRIGGER",       "VACUUM",        "VIEW",        
115263   "VIRTUAL",       "REINDEX",       "RENAME",        "CTIME_KW",    
115264   "ANY",           "OR",            "AND",           "IS",          
115265   "BETWEEN",       "IN",            "ISNULL",        "NOTNULL",     
115266   "NE",            "EQ",            "GT",            "LE",          
115267   "LT",            "GE",            "ESCAPE",        "BITAND",      
115268   "BITOR",         "LSHIFT",        "RSHIFT",        "PLUS",        
115269   "MINUS",         "STAR",          "SLASH",         "REM",         
115270   "CONCAT",        "COLLATE",       "BITNOT",        "STRING",      
115271   "JOIN_KW",       "CONSTRAINT",    "DEFAULT",       "NULL",        
115272   "PRIMARY",       "UNIQUE",        "CHECK",         "REFERENCES",  
115273   "AUTOINCR",      "ON",            "INSERT",        "DELETE",      
115274   "UPDATE",        "SET",           "DEFERRABLE",    "FOREIGN",     
115275   "DROP",          "UNION",         "ALL",           "EXCEPT",      
115276   "INTERSECT",     "SELECT",        "DISTINCT",      "DOT",         
115277   "FROM",          "JOIN",          "USING",         "ORDER",       
115278   "GROUP",         "HAVING",        "LIMIT",         "WHERE",       
115279   "INTO",          "VALUES",        "INTEGER",       "FLOAT",       
115280   "BLOB",          "REGISTER",      "VARIABLE",      "CASE",        
115281   "WHEN",          "THEN",          "ELSE",          "INDEX",       
115282   "ALTER",         "ADD",           "error",         "input",       
115283   "cmdlist",       "ecmd",          "explain",       "cmdx",        
115284   "cmd",           "transtype",     "trans_opt",     "nm",          
115285   "savepoint_opt",  "create_table",  "create_table_args",  "createkw",    
115286   "temp",          "ifnotexists",   "dbnm",          "columnlist",  
115287   "conslist_opt",  "table_options",  "select",        "column",      
115288   "columnid",      "type",          "carglist",      "id",          
115289   "ids",           "typetoken",     "typename",      "signed",      
115290   "plus_num",      "minus_num",     "ccons",         "term",        
115291   "expr",          "onconf",        "sortorder",     "autoinc",     
115292   "idxlist_opt",   "refargs",       "defer_subclause",  "refarg",      
115293   "refact",        "init_deferred_pred_opt",  "conslist",      "tconscomma",  
115294   "tcons",         "idxlist",       "defer_subclause_opt",  "orconf",      
115295   "resolvetype",   "raisetype",     "ifexists",      "fullname",    
115296   "oneselect",     "multiselect_op",  "distinct",      "selcollist",  
115297   "from",          "where_opt",     "groupby_opt",   "having_opt",  
115298   "orderby_opt",   "limit_opt",     "sclp",          "as",          
115299   "seltablist",    "stl_prefix",    "joinop",        "indexed_opt", 
115300   "on_opt",        "using_opt",     "joinop2",       "idlist",      
115301   "sortlist",      "nexprlist",     "setlist",       "insert_cmd",  
115302   "inscollist_opt",  "valuelist",     "exprlist",      "likeop",      
115303   "between_op",    "in_op",         "case_operand",  "case_exprlist",
115304   "case_else",     "uniqueflag",    "collate",       "nmnum",       
115305   "number",        "trigger_decl",  "trigger_cmd_list",  "trigger_time",
115306   "trigger_event",  "foreach_clause",  "when_clause",   "trigger_cmd", 
115307   "trnm",          "tridxby",       "database_kw_opt",  "key_opt",     
115308   "add_column_fullname",  "kwcolumn_opt",  "create_vtab",   "vtabarglist", 
115309   "vtabarg",       "vtabargtoken",  "lp",            "anylist",     
115310 };
115311 #endif /* NDEBUG */
115312 
115313 #ifndef NDEBUG
115314 /* For tracing reduce actions, the names of all rules are required.
115315 */
115316 static const char *const yyRuleName[] = {
115317  /*   0 */ "input ::= cmdlist",
115318  /*   1 */ "cmdlist ::= cmdlist ecmd",
115319  /*   2 */ "cmdlist ::= ecmd",
115320  /*   3 */ "ecmd ::= SEMI",
115321  /*   4 */ "ecmd ::= explain cmdx SEMI",
115322  /*   5 */ "explain ::=",
115323  /*   6 */ "explain ::= EXPLAIN",
115324  /*   7 */ "explain ::= EXPLAIN QUERY PLAN",
115325  /*   8 */ "cmdx ::= cmd",
115326  /*   9 */ "cmd ::= BEGIN transtype trans_opt",
115327  /*  10 */ "trans_opt ::=",
115328  /*  11 */ "trans_opt ::= TRANSACTION",
115329  /*  12 */ "trans_opt ::= TRANSACTION nm",
115330  /*  13 */ "transtype ::=",
115331  /*  14 */ "transtype ::= DEFERRED",
115332  /*  15 */ "transtype ::= IMMEDIATE",
115333  /*  16 */ "transtype ::= EXCLUSIVE",
115334  /*  17 */ "cmd ::= COMMIT trans_opt",
115335  /*  18 */ "cmd ::= END trans_opt",
115336  /*  19 */ "cmd ::= ROLLBACK trans_opt",
115337  /*  20 */ "savepoint_opt ::= SAVEPOINT",
115338  /*  21 */ "savepoint_opt ::=",
115339  /*  22 */ "cmd ::= SAVEPOINT nm",
115340  /*  23 */ "cmd ::= RELEASE savepoint_opt nm",
115341  /*  24 */ "cmd ::= ROLLBACK trans_opt TO savepoint_opt nm",
115342  /*  25 */ "cmd ::= create_table create_table_args",
115343  /*  26 */ "create_table ::= createkw temp TABLE ifnotexists nm dbnm",
115344  /*  27 */ "createkw ::= CREATE",
115345  /*  28 */ "ifnotexists ::=",
115346  /*  29 */ "ifnotexists ::= IF NOT EXISTS",
115347  /*  30 */ "temp ::= TEMP",
115348  /*  31 */ "temp ::=",
115349  /*  32 */ "create_table_args ::= LP columnlist conslist_opt RP table_options",
115350  /*  33 */ "create_table_args ::= AS select",
115351  /*  34 */ "table_options ::=",
115352  /*  35 */ "table_options ::= WITHOUT nm",
115353  /*  36 */ "columnlist ::= columnlist COMMA column",
115354  /*  37 */ "columnlist ::= column",
115355  /*  38 */ "column ::= columnid type carglist",
115356  /*  39 */ "columnid ::= nm",
115357  /*  40 */ "id ::= ID",
115358  /*  41 */ "id ::= INDEXED",
115359  /*  42 */ "ids ::= ID|STRING",
115360  /*  43 */ "nm ::= id",
115361  /*  44 */ "nm ::= STRING",
115362  /*  45 */ "nm ::= JOIN_KW",
115363  /*  46 */ "type ::=",
115364  /*  47 */ "type ::= typetoken",
115365  /*  48 */ "typetoken ::= typename",
115366  /*  49 */ "typetoken ::= typename LP signed RP",
115367  /*  50 */ "typetoken ::= typename LP signed COMMA signed RP",
115368  /*  51 */ "typename ::= ids",
115369  /*  52 */ "typename ::= typename ids",
115370  /*  53 */ "signed ::= plus_num",
115371  /*  54 */ "signed ::= minus_num",
115372  /*  55 */ "carglist ::= carglist ccons",
115373  /*  56 */ "carglist ::=",
115374  /*  57 */ "ccons ::= CONSTRAINT nm",
115375  /*  58 */ "ccons ::= DEFAULT term",
115376  /*  59 */ "ccons ::= DEFAULT LP expr RP",
115377  /*  60 */ "ccons ::= DEFAULT PLUS term",
115378  /*  61 */ "ccons ::= DEFAULT MINUS term",
115379  /*  62 */ "ccons ::= DEFAULT id",
115380  /*  63 */ "ccons ::= NULL onconf",
115381  /*  64 */ "ccons ::= NOT NULL onconf",
115382  /*  65 */ "ccons ::= PRIMARY KEY sortorder onconf autoinc",
115383  /*  66 */ "ccons ::= UNIQUE onconf",
115384  /*  67 */ "ccons ::= CHECK LP expr RP",
115385  /*  68 */ "ccons ::= REFERENCES nm idxlist_opt refargs",
115386  /*  69 */ "ccons ::= defer_subclause",
115387  /*  70 */ "ccons ::= COLLATE ids",
115388  /*  71 */ "autoinc ::=",
115389  /*  72 */ "autoinc ::= AUTOINCR",
115390  /*  73 */ "refargs ::=",
115391  /*  74 */ "refargs ::= refargs refarg",
115392  /*  75 */ "refarg ::= MATCH nm",
115393  /*  76 */ "refarg ::= ON INSERT refact",
115394  /*  77 */ "refarg ::= ON DELETE refact",
115395  /*  78 */ "refarg ::= ON UPDATE refact",
115396  /*  79 */ "refact ::= SET NULL",
115397  /*  80 */ "refact ::= SET DEFAULT",
115398  /*  81 */ "refact ::= CASCADE",
115399  /*  82 */ "refact ::= RESTRICT",
115400  /*  83 */ "refact ::= NO ACTION",
115401  /*  84 */ "defer_subclause ::= NOT DEFERRABLE init_deferred_pred_opt",
115402  /*  85 */ "defer_subclause ::= DEFERRABLE init_deferred_pred_opt",
115403  /*  86 */ "init_deferred_pred_opt ::=",
115404  /*  87 */ "init_deferred_pred_opt ::= INITIALLY DEFERRED",
115405  /*  88 */ "init_deferred_pred_opt ::= INITIALLY IMMEDIATE",
115406  /*  89 */ "conslist_opt ::=",
115407  /*  90 */ "conslist_opt ::= COMMA conslist",
115408  /*  91 */ "conslist ::= conslist tconscomma tcons",
115409  /*  92 */ "conslist ::= tcons",
115410  /*  93 */ "tconscomma ::= COMMA",
115411  /*  94 */ "tconscomma ::=",
115412  /*  95 */ "tcons ::= CONSTRAINT nm",
115413  /*  96 */ "tcons ::= PRIMARY KEY LP idxlist autoinc RP onconf",
115414  /*  97 */ "tcons ::= UNIQUE LP idxlist RP onconf",
115415  /*  98 */ "tcons ::= CHECK LP expr RP onconf",
115416  /*  99 */ "tcons ::= FOREIGN KEY LP idxlist RP REFERENCES nm idxlist_opt refargs defer_subclause_opt",
115417  /* 100 */ "defer_subclause_opt ::=",
115418  /* 101 */ "defer_subclause_opt ::= defer_subclause",
115419  /* 102 */ "onconf ::=",
115420  /* 103 */ "onconf ::= ON CONFLICT resolvetype",
115421  /* 104 */ "orconf ::=",
115422  /* 105 */ "orconf ::= OR resolvetype",
115423  /* 106 */ "resolvetype ::= raisetype",
115424  /* 107 */ "resolvetype ::= IGNORE",
115425  /* 108 */ "resolvetype ::= REPLACE",
115426  /* 109 */ "cmd ::= DROP TABLE ifexists fullname",
115427  /* 110 */ "ifexists ::= IF EXISTS",
115428  /* 111 */ "ifexists ::=",
115429  /* 112 */ "cmd ::= createkw temp VIEW ifnotexists nm dbnm AS select",
115430  /* 113 */ "cmd ::= DROP VIEW ifexists fullname",
115431  /* 114 */ "cmd ::= select",
115432  /* 115 */ "select ::= oneselect",
115433  /* 116 */ "select ::= select multiselect_op oneselect",
115434  /* 117 */ "multiselect_op ::= UNION",
115435  /* 118 */ "multiselect_op ::= UNION ALL",
115436  /* 119 */ "multiselect_op ::= EXCEPT|INTERSECT",
115437  /* 120 */ "oneselect ::= SELECT distinct selcollist from where_opt groupby_opt having_opt orderby_opt limit_opt",
115438  /* 121 */ "distinct ::= DISTINCT",
115439  /* 122 */ "distinct ::= ALL",
115440  /* 123 */ "distinct ::=",
115441  /* 124 */ "sclp ::= selcollist COMMA",
115442  /* 125 */ "sclp ::=",
115443  /* 126 */ "selcollist ::= sclp expr as",
115444  /* 127 */ "selcollist ::= sclp STAR",
115445  /* 128 */ "selcollist ::= sclp nm DOT STAR",
115446  /* 129 */ "as ::= AS nm",
115447  /* 130 */ "as ::= ids",
115448  /* 131 */ "as ::=",
115449  /* 132 */ "from ::=",
115450  /* 133 */ "from ::= FROM seltablist",
115451  /* 134 */ "stl_prefix ::= seltablist joinop",
115452  /* 135 */ "stl_prefix ::=",
115453  /* 136 */ "seltablist ::= stl_prefix nm dbnm as indexed_opt on_opt using_opt",
115454  /* 137 */ "seltablist ::= stl_prefix LP select RP as on_opt using_opt",
115455  /* 138 */ "seltablist ::= stl_prefix LP seltablist RP as on_opt using_opt",
115456  /* 139 */ "dbnm ::=",
115457  /* 140 */ "dbnm ::= DOT nm",
115458  /* 141 */ "fullname ::= nm dbnm",
115459  /* 142 */ "joinop ::= COMMA|JOIN",
115460  /* 143 */ "joinop ::= JOIN_KW JOIN",
115461  /* 144 */ "joinop ::= JOIN_KW nm JOIN",
115462  /* 145 */ "joinop ::= JOIN_KW nm nm JOIN",
115463  /* 146 */ "on_opt ::= ON expr",
115464  /* 147 */ "on_opt ::=",
115465  /* 148 */ "indexed_opt ::=",
115466  /* 149 */ "indexed_opt ::= INDEXED BY nm",
115467  /* 150 */ "indexed_opt ::= NOT INDEXED",
115468  /* 151 */ "using_opt ::= USING LP idlist RP",
115469  /* 152 */ "using_opt ::=",
115470  /* 153 */ "orderby_opt ::=",
115471  /* 154 */ "orderby_opt ::= ORDER BY sortlist",
115472  /* 155 */ "sortlist ::= sortlist COMMA expr sortorder",
115473  /* 156 */ "sortlist ::= expr sortorder",
115474  /* 157 */ "sortorder ::= ASC",
115475  /* 158 */ "sortorder ::= DESC",
115476  /* 159 */ "sortorder ::=",
115477  /* 160 */ "groupby_opt ::=",
115478  /* 161 */ "groupby_opt ::= GROUP BY nexprlist",
115479  /* 162 */ "having_opt ::=",
115480  /* 163 */ "having_opt ::= HAVING expr",
115481  /* 164 */ "limit_opt ::=",
115482  /* 165 */ "limit_opt ::= LIMIT expr",
115483  /* 166 */ "limit_opt ::= LIMIT expr OFFSET expr",
115484  /* 167 */ "limit_opt ::= LIMIT expr COMMA expr",
115485  /* 168 */ "cmd ::= DELETE FROM fullname indexed_opt where_opt",
115486  /* 169 */ "where_opt ::=",
115487  /* 170 */ "where_opt ::= WHERE expr",
115488  /* 171 */ "cmd ::= UPDATE orconf fullname indexed_opt SET setlist where_opt",
115489  /* 172 */ "setlist ::= setlist COMMA nm EQ expr",
115490  /* 173 */ "setlist ::= nm EQ expr",
115491  /* 174 */ "cmd ::= insert_cmd INTO fullname inscollist_opt valuelist",
115492  /* 175 */ "cmd ::= insert_cmd INTO fullname inscollist_opt select",
115493  /* 176 */ "cmd ::= insert_cmd INTO fullname inscollist_opt DEFAULT VALUES",
115494  /* 177 */ "insert_cmd ::= INSERT orconf",
115495  /* 178 */ "insert_cmd ::= REPLACE",
115496  /* 179 */ "valuelist ::= VALUES LP nexprlist RP",
115497  /* 180 */ "valuelist ::= valuelist COMMA LP exprlist RP",
115498  /* 181 */ "inscollist_opt ::=",
115499  /* 182 */ "inscollist_opt ::= LP idlist RP",
115500  /* 183 */ "idlist ::= idlist COMMA nm",
115501  /* 184 */ "idlist ::= nm",
115502  /* 185 */ "expr ::= term",
115503  /* 186 */ "expr ::= LP expr RP",
115504  /* 187 */ "term ::= NULL",
115505  /* 188 */ "expr ::= id",
115506  /* 189 */ "expr ::= JOIN_KW",
115507  /* 190 */ "expr ::= nm DOT nm",
115508  /* 191 */ "expr ::= nm DOT nm DOT nm",
115509  /* 192 */ "term ::= INTEGER|FLOAT|BLOB",
115510  /* 193 */ "term ::= STRING",
115511  /* 194 */ "expr ::= REGISTER",
115512  /* 195 */ "expr ::= VARIABLE",
115513  /* 196 */ "expr ::= expr COLLATE ids",
115514  /* 197 */ "expr ::= CAST LP expr AS typetoken RP",
115515  /* 198 */ "expr ::= ID LP distinct exprlist RP",
115516  /* 199 */ "expr ::= ID LP STAR RP",
115517  /* 200 */ "term ::= CTIME_KW",
115518  /* 201 */ "expr ::= expr AND expr",
115519  /* 202 */ "expr ::= expr OR expr",
115520  /* 203 */ "expr ::= expr LT|GT|GE|LE expr",
115521  /* 204 */ "expr ::= expr EQ|NE expr",
115522  /* 205 */ "expr ::= expr BITAND|BITOR|LSHIFT|RSHIFT expr",
115523  /* 206 */ "expr ::= expr PLUS|MINUS expr",
115524  /* 207 */ "expr ::= expr STAR|SLASH|REM expr",
115525  /* 208 */ "expr ::= expr CONCAT expr",
115526  /* 209 */ "likeop ::= LIKE_KW",
115527  /* 210 */ "likeop ::= NOT LIKE_KW",
115528  /* 211 */ "likeop ::= MATCH",
115529  /* 212 */ "likeop ::= NOT MATCH",
115530  /* 213 */ "expr ::= expr likeop expr",
115531  /* 214 */ "expr ::= expr likeop expr ESCAPE expr",
115532  /* 215 */ "expr ::= expr ISNULL|NOTNULL",
115533  /* 216 */ "expr ::= expr NOT NULL",
115534  /* 217 */ "expr ::= expr IS expr",
115535  /* 218 */ "expr ::= expr IS NOT expr",
115536  /* 219 */ "expr ::= NOT expr",
115537  /* 220 */ "expr ::= BITNOT expr",
115538  /* 221 */ "expr ::= MINUS expr",
115539  /* 222 */ "expr ::= PLUS expr",
115540  /* 223 */ "between_op ::= BETWEEN",
115541  /* 224 */ "between_op ::= NOT BETWEEN",
115542  /* 225 */ "expr ::= expr between_op expr AND expr",
115543  /* 226 */ "in_op ::= IN",
115544  /* 227 */ "in_op ::= NOT IN",
115545  /* 228 */ "expr ::= expr in_op LP exprlist RP",
115546  /* 229 */ "expr ::= LP select RP",
115547  /* 230 */ "expr ::= expr in_op LP select RP",
115548  /* 231 */ "expr ::= expr in_op nm dbnm",
115549  /* 232 */ "expr ::= EXISTS LP select RP",
115550  /* 233 */ "expr ::= CASE case_operand case_exprlist case_else END",
115551  /* 234 */ "case_exprlist ::= case_exprlist WHEN expr THEN expr",
115552  /* 235 */ "case_exprlist ::= WHEN expr THEN expr",
115553  /* 236 */ "case_else ::= ELSE expr",
115554  /* 237 */ "case_else ::=",
115555  /* 238 */ "case_operand ::= expr",
115556  /* 239 */ "case_operand ::=",
115557  /* 240 */ "exprlist ::= nexprlist",
115558  /* 241 */ "exprlist ::=",
115559  /* 242 */ "nexprlist ::= nexprlist COMMA expr",
115560  /* 243 */ "nexprlist ::= expr",
115561  /* 244 */ "cmd ::= createkw uniqueflag INDEX ifnotexists nm dbnm ON nm LP idxlist RP where_opt",
115562  /* 245 */ "uniqueflag ::= UNIQUE",
115563  /* 246 */ "uniqueflag ::=",
115564  /* 247 */ "idxlist_opt ::=",
115565  /* 248 */ "idxlist_opt ::= LP idxlist RP",
115566  /* 249 */ "idxlist ::= idxlist COMMA nm collate sortorder",
115567  /* 250 */ "idxlist ::= nm collate sortorder",
115568  /* 251 */ "collate ::=",
115569  /* 252 */ "collate ::= COLLATE ids",
115570  /* 253 */ "cmd ::= DROP INDEX ifexists fullname",
115571  /* 254 */ "cmd ::= VACUUM",
115572  /* 255 */ "cmd ::= VACUUM nm",
115573  /* 256 */ "cmd ::= PRAGMA nm dbnm",
115574  /* 257 */ "cmd ::= PRAGMA nm dbnm EQ nmnum",
115575  /* 258 */ "cmd ::= PRAGMA nm dbnm LP nmnum RP",
115576  /* 259 */ "cmd ::= PRAGMA nm dbnm EQ minus_num",
115577  /* 260 */ "cmd ::= PRAGMA nm dbnm LP minus_num RP",
115578  /* 261 */ "nmnum ::= plus_num",
115579  /* 262 */ "nmnum ::= nm",
115580  /* 263 */ "nmnum ::= ON",
115581  /* 264 */ "nmnum ::= DELETE",
115582  /* 265 */ "nmnum ::= DEFAULT",
115583  /* 266 */ "plus_num ::= PLUS number",
115584  /* 267 */ "plus_num ::= number",
115585  /* 268 */ "minus_num ::= MINUS number",
115586  /* 269 */ "number ::= INTEGER|FLOAT",
115587  /* 270 */ "cmd ::= createkw trigger_decl BEGIN trigger_cmd_list END",
115588  /* 271 */ "trigger_decl ::= temp TRIGGER ifnotexists nm dbnm trigger_time trigger_event ON fullname foreach_clause when_clause",
115589  /* 272 */ "trigger_time ::= BEFORE",
115590  /* 273 */ "trigger_time ::= AFTER",
115591  /* 274 */ "trigger_time ::= INSTEAD OF",
115592  /* 275 */ "trigger_time ::=",
115593  /* 276 */ "trigger_event ::= DELETE|INSERT",
115594  /* 277 */ "trigger_event ::= UPDATE",
115595  /* 278 */ "trigger_event ::= UPDATE OF idlist",
115596  /* 279 */ "foreach_clause ::=",
115597  /* 280 */ "foreach_clause ::= FOR EACH ROW",
115598  /* 281 */ "when_clause ::=",
115599  /* 282 */ "when_clause ::= WHEN expr",
115600  /* 283 */ "trigger_cmd_list ::= trigger_cmd_list trigger_cmd SEMI",
115601  /* 284 */ "trigger_cmd_list ::= trigger_cmd SEMI",
115602  /* 285 */ "trnm ::= nm",
115603  /* 286 */ "trnm ::= nm DOT nm",
115604  /* 287 */ "tridxby ::=",
115605  /* 288 */ "tridxby ::= INDEXED BY nm",
115606  /* 289 */ "tridxby ::= NOT INDEXED",
115607  /* 290 */ "trigger_cmd ::= UPDATE orconf trnm tridxby SET setlist where_opt",
115608  /* 291 */ "trigger_cmd ::= insert_cmd INTO trnm inscollist_opt valuelist",
115609  /* 292 */ "trigger_cmd ::= insert_cmd INTO trnm inscollist_opt select",
115610  /* 293 */ "trigger_cmd ::= DELETE FROM trnm tridxby where_opt",
115611  /* 294 */ "trigger_cmd ::= select",
115612  /* 295 */ "expr ::= RAISE LP IGNORE RP",
115613  /* 296 */ "expr ::= RAISE LP raisetype COMMA nm RP",
115614  /* 297 */ "raisetype ::= ROLLBACK",
115615  /* 298 */ "raisetype ::= ABORT",
115616  /* 299 */ "raisetype ::= FAIL",
115617  /* 300 */ "cmd ::= DROP TRIGGER ifexists fullname",
115618  /* 301 */ "cmd ::= ATTACH database_kw_opt expr AS expr key_opt",
115619  /* 302 */ "cmd ::= DETACH database_kw_opt expr",
115620  /* 303 */ "key_opt ::=",
115621  /* 304 */ "key_opt ::= KEY expr",
115622  /* 305 */ "database_kw_opt ::= DATABASE",
115623  /* 306 */ "database_kw_opt ::=",
115624  /* 307 */ "cmd ::= REINDEX",
115625  /* 308 */ "cmd ::= REINDEX nm dbnm",
115626  /* 309 */ "cmd ::= ANALYZE",
115627  /* 310 */ "cmd ::= ANALYZE nm dbnm",
115628  /* 311 */ "cmd ::= ALTER TABLE fullname RENAME TO nm",
115629  /* 312 */ "cmd ::= ALTER TABLE add_column_fullname ADD kwcolumn_opt column",
115630  /* 313 */ "add_column_fullname ::= fullname",
115631  /* 314 */ "kwcolumn_opt ::=",
115632  /* 315 */ "kwcolumn_opt ::= COLUMNKW",
115633  /* 316 */ "cmd ::= create_vtab",
115634  /* 317 */ "cmd ::= create_vtab LP vtabarglist RP",
115635  /* 318 */ "create_vtab ::= createkw VIRTUAL TABLE ifnotexists nm dbnm USING nm",
115636  /* 319 */ "vtabarglist ::= vtabarg",
115637  /* 320 */ "vtabarglist ::= vtabarglist COMMA vtabarg",
115638  /* 321 */ "vtabarg ::=",
115639  /* 322 */ "vtabarg ::= vtabarg vtabargtoken",
115640  /* 323 */ "vtabargtoken ::= ANY",
115641  /* 324 */ "vtabargtoken ::= lp anylist RP",
115642  /* 325 */ "lp ::= LP",
115643  /* 326 */ "anylist ::=",
115644  /* 327 */ "anylist ::= anylist LP anylist RP",
115645  /* 328 */ "anylist ::= anylist ANY",
115646 };
115647 #endif /* NDEBUG */
115648 
115649 
115650 #if YYSTACKDEPTH<=0
115651 /*
115652 ** Try to increase the size of the parser stack.
115653 */
115654 static void yyGrowStack(yyParser *p){
115655   int newSize;
115656   yyStackEntry *pNew;
115657 
115658   newSize = p->yystksz*2 + 100;
115659   pNew = realloc(p->yystack, newSize*sizeof(pNew[0]));
115660   if( pNew ){
115661     p->yystack = pNew;
115662     p->yystksz = newSize;
115663 #ifndef NDEBUG
115664     if( yyTraceFILE ){
115665       fprintf(yyTraceFILE,"%sStack grows to %d entries!\n",
115666               yyTracePrompt, p->yystksz);
115667     }
115668 #endif
115669   }
115670 }
115671 #endif
115672 
115673 /* 
115674 ** This function allocates a new parser.
115675 ** The only argument is a pointer to a function which works like
115676 ** malloc.
115677 **
115678 ** Inputs:
115679 ** A pointer to the function used to allocate memory.
115680 **
115681 ** Outputs:
115682 ** A pointer to a parser.  This pointer is used in subsequent calls
115683 ** to sqlite3Parser and sqlite3ParserFree.
115684 */
115685 SQLITE_PRIVATE void *sqlite3ParserAlloc(void *(*mallocProc)(size_t)){
115686   yyParser *pParser;
115687   pParser = (yyParser*)(*mallocProc)( (size_t)sizeof(yyParser) );
115688   if( pParser ){
115689     pParser->yyidx = -1;
115690 #ifdef YYTRACKMAXSTACKDEPTH
115691     pParser->yyidxMax = 0;
115692 #endif
115693 #if YYSTACKDEPTH<=0
115694     pParser->yystack = NULL;
115695     pParser->yystksz = 0;
115696     yyGrowStack(pParser);
115697 #endif
115698   }
115699   return pParser;
115700 }
115701 
115702 /* The following function deletes the value associated with a
115703 ** symbol.  The symbol can be either a terminal or nonterminal.
115704 ** "yymajor" is the symbol code, and "yypminor" is a pointer to
115705 ** the value.
115706 */
115707 static void yy_destructor(
115708   yyParser *yypParser,    /* The parser */
115709   YYCODETYPE yymajor,     /* Type code for object to destroy */
115710   YYMINORTYPE *yypminor   /* The object to be destroyed */
115711 ){
115712   sqlite3ParserARG_FETCH;
115713   switch( yymajor ){
115714     /* Here is inserted the actions which take place when a
115715     ** terminal or non-terminal is destroyed.  This can happen
115716     ** when the symbol is popped from the stack during a
115717     ** reduce or during error processing or when a parser is 
115718     ** being destroyed before it is finished parsing.
115719     **
115720     ** Note: during a reduce, the only symbols destroyed are those
115721     ** which appear on the RHS of the rule, but which are not used
115722     ** inside the C code.
115723     */
115724     case 162: /* select */
115725     case 196: /* oneselect */
115726 {
115727 sqlite3SelectDelete(pParse->db, (yypminor->yy387));
115728 }
115729       break;
115730     case 175: /* term */
115731     case 176: /* expr */
115732 {
115733 sqlite3ExprDelete(pParse->db, (yypminor->yy118).pExpr);
115734 }
115735       break;
115736     case 180: /* idxlist_opt */
115737     case 189: /* idxlist */
115738     case 199: /* selcollist */
115739     case 202: /* groupby_opt */
115740     case 204: /* orderby_opt */
115741     case 206: /* sclp */
115742     case 216: /* sortlist */
115743     case 217: /* nexprlist */
115744     case 218: /* setlist */
115745     case 222: /* exprlist */
115746     case 227: /* case_exprlist */
115747 {
115748 sqlite3ExprListDelete(pParse->db, (yypminor->yy322));
115749 }
115750       break;
115751     case 195: /* fullname */
115752     case 200: /* from */
115753     case 208: /* seltablist */
115754     case 209: /* stl_prefix */
115755 {
115756 sqlite3SrcListDelete(pParse->db, (yypminor->yy259));
115757 }
115758       break;
115759     case 201: /* where_opt */
115760     case 203: /* having_opt */
115761     case 212: /* on_opt */
115762     case 226: /* case_operand */
115763     case 228: /* case_else */
115764     case 238: /* when_clause */
115765     case 243: /* key_opt */
115766 {
115767 sqlite3ExprDelete(pParse->db, (yypminor->yy314));
115768 }
115769       break;
115770     case 213: /* using_opt */
115771     case 215: /* idlist */
115772     case 220: /* inscollist_opt */
115773 {
115774 sqlite3IdListDelete(pParse->db, (yypminor->yy384));
115775 }
115776       break;
115777     case 221: /* valuelist */
115778 {
115779 
115780   sqlite3ExprListDelete(pParse->db, (yypminor->yy260).pList);
115781   sqlite3SelectDelete(pParse->db, (yypminor->yy260).pSelect);
115782 
115783 }
115784       break;
115785     case 234: /* trigger_cmd_list */
115786     case 239: /* trigger_cmd */
115787 {
115788 sqlite3DeleteTriggerStep(pParse->db, (yypminor->yy203));
115789 }
115790       break;
115791     case 236: /* trigger_event */
115792 {
115793 sqlite3IdListDelete(pParse->db, (yypminor->yy90).b);
115794 }
115795       break;
115796     default:  break;   /* If no destructor action specified: do nothing */
115797   }
115798 }
115799 
115800 /*
115801 ** Pop the parser's stack once.
115802 **
115803 ** If there is a destructor routine associated with the token which
115804 ** is popped from the stack, then call it.
115805 **
115806 ** Return the major token number for the symbol popped.
115807 */
115808 static int yy_pop_parser_stack(yyParser *pParser){
115809   YYCODETYPE yymajor;
115810   yyStackEntry *yytos = &pParser->yystack[pParser->yyidx];
115811 
115812   /* There is no mechanism by which the parser stack can be popped below
115813   ** empty in SQLite.  */
115814   if( NEVER(pParser->yyidx<0) ) return 0;
115815 #ifndef NDEBUG
115816   if( yyTraceFILE && pParser->yyidx>=0 ){
115817     fprintf(yyTraceFILE,"%sPopping %s\n",
115818       yyTracePrompt,
115819       yyTokenName[yytos->major]);
115820   }
115821 #endif
115822   yymajor = yytos->major;
115823   yy_destructor(pParser, yymajor, &yytos->minor);
115824   pParser->yyidx--;
115825   return yymajor;
115826 }
115827 
115828 /* 
115829 ** Deallocate and destroy a parser.  Destructors are all called for
115830 ** all stack elements before shutting the parser down.
115831 **
115832 ** Inputs:
115833 ** <ul>
115834 ** <li>  A pointer to the parser.  This should be a pointer
115835 **       obtained from sqlite3ParserAlloc.
115836 ** <li>  A pointer to a function used to reclaim memory obtained
115837 **       from malloc.
115838 ** </ul>
115839 */
115840 SQLITE_PRIVATE void sqlite3ParserFree(
115841   void *p,                    /* The parser to be deleted */
115842   void (*freeProc)(void*)     /* Function used to reclaim memory */
115843 ){
115844   yyParser *pParser = (yyParser*)p;
115845   /* In SQLite, we never try to destroy a parser that was not successfully
115846   ** created in the first place. */
115847   if( NEVER(pParser==0) ) return;
115848   while( pParser->yyidx>=0 ) yy_pop_parser_stack(pParser);
115849 #if YYSTACKDEPTH<=0
115850   free(pParser->yystack);
115851 #endif
115852   (*freeProc)((void*)pParser);
115853 }
115854 
115855 /*
115856 ** Return the peak depth of the stack for a parser.
115857 */
115858 #ifdef YYTRACKMAXSTACKDEPTH
115859 SQLITE_PRIVATE int sqlite3ParserStackPeak(void *p){
115860   yyParser *pParser = (yyParser*)p;
115861   return pParser->yyidxMax;
115862 }
115863 #endif
115864 
115865 /*
115866 ** Find the appropriate action for a parser given the terminal
115867 ** look-ahead token iLookAhead.
115868 **
115869 ** If the look-ahead token is YYNOCODE, then check to see if the action is
115870 ** independent of the look-ahead.  If it is, return the action, otherwise
115871 ** return YY_NO_ACTION.
115872 */
115873 static int yy_find_shift_action(
115874   yyParser *pParser,        /* The parser */
115875   YYCODETYPE iLookAhead     /* The look-ahead token */
115876 ){
115877   int i;
115878   int stateno = pParser->yystack[pParser->yyidx].stateno;
115879  
115880   if( stateno>YY_SHIFT_COUNT
115881    || (i = yy_shift_ofst[stateno])==YY_SHIFT_USE_DFLT ){
115882     return yy_default[stateno];
115883   }
115884   assert( iLookAhead!=YYNOCODE );
115885   i += iLookAhead;
115886   if( i<0 || i>=YY_ACTTAB_COUNT || yy_lookahead[i]!=iLookAhead ){
115887     if( iLookAhead>0 ){
115888 #ifdef YYFALLBACK
115889       YYCODETYPE iFallback;            /* Fallback token */
115890       if( iLookAhead<sizeof(yyFallback)/sizeof(yyFallback[0])
115891              && (iFallback = yyFallback[iLookAhead])!=0 ){
115892 #ifndef NDEBUG
115893         if( yyTraceFILE ){
115894           fprintf(yyTraceFILE, "%sFALLBACK %s => %s\n",
115895              yyTracePrompt, yyTokenName[iLookAhead], yyTokenName[iFallback]);
115896         }
115897 #endif
115898         return yy_find_shift_action(pParser, iFallback);
115899       }
115900 #endif
115901 #ifdef YYWILDCARD
115902       {
115903         int j = i - iLookAhead + YYWILDCARD;
115904         if( 
115905 #if YY_SHIFT_MIN+YYWILDCARD<0
115906           j>=0 &&
115907 #endif
115908 #if YY_SHIFT_MAX+YYWILDCARD>=YY_ACTTAB_COUNT
115909           j<YY_ACTTAB_COUNT &&
115910 #endif
115911           yy_lookahead[j]==YYWILDCARD
115912         ){
115913 #ifndef NDEBUG
115914           if( yyTraceFILE ){
115915             fprintf(yyTraceFILE, "%sWILDCARD %s => %s\n",
115916                yyTracePrompt, yyTokenName[iLookAhead], yyTokenName[YYWILDCARD]);
115917           }
115918 #endif /* NDEBUG */
115919           return yy_action[j];
115920         }
115921       }
115922 #endif /* YYWILDCARD */
115923     }
115924     return yy_default[stateno];
115925   }else{
115926     return yy_action[i];
115927   }
115928 }
115929 
115930 /*
115931 ** Find the appropriate action for a parser given the non-terminal
115932 ** look-ahead token iLookAhead.
115933 **
115934 ** If the look-ahead token is YYNOCODE, then check to see if the action is
115935 ** independent of the look-ahead.  If it is, return the action, otherwise
115936 ** return YY_NO_ACTION.
115937 */
115938 static int yy_find_reduce_action(
115939   int stateno,              /* Current state number */
115940   YYCODETYPE iLookAhead     /* The look-ahead token */
115941 ){
115942   int i;
115943 #ifdef YYERRORSYMBOL
115944   if( stateno>YY_REDUCE_COUNT ){
115945     return yy_default[stateno];
115946   }
115947 #else
115948   assert( stateno<=YY_REDUCE_COUNT );
115949 #endif
115950   i = yy_reduce_ofst[stateno];
115951   assert( i!=YY_REDUCE_USE_DFLT );
115952   assert( iLookAhead!=YYNOCODE );
115953   i += iLookAhead;
115954 #ifdef YYERRORSYMBOL
115955   if( i<0 || i>=YY_ACTTAB_COUNT || yy_lookahead[i]!=iLookAhead ){
115956     return yy_default[stateno];
115957   }
115958 #else
115959   assert( i>=0 && i<YY_ACTTAB_COUNT );
115960   assert( yy_lookahead[i]==iLookAhead );
115961 #endif
115962   return yy_action[i];
115963 }
115964 
115965 /*
115966 ** The following routine is called if the stack overflows.
115967 */
115968 static void yyStackOverflow(yyParser *yypParser, YYMINORTYPE *yypMinor){
115969    sqlite3ParserARG_FETCH;
115970    yypParser->yyidx--;
115971 #ifndef NDEBUG
115972    if( yyTraceFILE ){
115973      fprintf(yyTraceFILE,"%sStack Overflow!\n",yyTracePrompt);
115974    }
115975 #endif
115976    while( yypParser->yyidx>=0 ) yy_pop_parser_stack(yypParser);
115977    /* Here code is inserted which will execute if the parser
115978    ** stack every overflows */
115979 
115980   UNUSED_PARAMETER(yypMinor); /* Silence some compiler warnings */
115981   sqlite3ErrorMsg(pParse, "parser stack overflow");
115982    sqlite3ParserARG_STORE; /* Suppress warning about unused %extra_argument var */
115983 }
115984 
115985 /*
115986 ** Perform a shift action.
115987 */
115988 static void yy_shift(
115989   yyParser *yypParser,          /* The parser to be shifted */
115990   int yyNewState,               /* The new state to shift in */
115991   int yyMajor,                  /* The major token to shift in */
115992   YYMINORTYPE *yypMinor         /* Pointer to the minor token to shift in */
115993 ){
115994   yyStackEntry *yytos;
115995   yypParser->yyidx++;
115996 #ifdef YYTRACKMAXSTACKDEPTH
115997   if( yypParser->yyidx>yypParser->yyidxMax ){
115998     yypParser->yyidxMax = yypParser->yyidx;
115999   }
116000 #endif
116001 #if YYSTACKDEPTH>0 
116002   if( yypParser->yyidx>=YYSTACKDEPTH ){
116003     yyStackOverflow(yypParser, yypMinor);
116004     return;
116005   }
116006 #else
116007   if( yypParser->yyidx>=yypParser->yystksz ){
116008     yyGrowStack(yypParser);
116009     if( yypParser->yyidx>=yypParser->yystksz ){
116010       yyStackOverflow(yypParser, yypMinor);
116011       return;
116012     }
116013   }
116014 #endif
116015   yytos = &yypParser->yystack[yypParser->yyidx];
116016   yytos->stateno = (YYACTIONTYPE)yyNewState;
116017   yytos->major = (YYCODETYPE)yyMajor;
116018   yytos->minor = *yypMinor;
116019 #ifndef NDEBUG
116020   if( yyTraceFILE && yypParser->yyidx>0 ){
116021     int i;
116022     fprintf(yyTraceFILE,"%sShift %d\n",yyTracePrompt,yyNewState);
116023     fprintf(yyTraceFILE,"%sStack:",yyTracePrompt);
116024     for(i=1; i<=yypParser->yyidx; i++)
116025       fprintf(yyTraceFILE," %s",yyTokenName[yypParser->yystack[i].major]);
116026     fprintf(yyTraceFILE,"\n");
116027   }
116028 #endif
116029 }
116030 
116031 /* The following table contains information about every rule that
116032 ** is used during the reduce.
116033 */
116034 static const struct {
116035   YYCODETYPE lhs;         /* Symbol on the left-hand side of the rule */
116036   unsigned char nrhs;     /* Number of right-hand side symbols in the rule */
116037 } yyRuleInfo[] = {
116038   { 143, 1 },
116039   { 144, 2 },
116040   { 144, 1 },
116041   { 145, 1 },
116042   { 145, 3 },
116043   { 146, 0 },
116044   { 146, 1 },
116045   { 146, 3 },
116046   { 147, 1 },
116047   { 148, 3 },
116048   { 150, 0 },
116049   { 150, 1 },
116050   { 150, 2 },
116051   { 149, 0 },
116052   { 149, 1 },
116053   { 149, 1 },
116054   { 149, 1 },
116055   { 148, 2 },
116056   { 148, 2 },
116057   { 148, 2 },
116058   { 152, 1 },
116059   { 152, 0 },
116060   { 148, 2 },
116061   { 148, 3 },
116062   { 148, 5 },
116063   { 148, 2 },
116064   { 153, 6 },
116065   { 155, 1 },
116066   { 157, 0 },
116067   { 157, 3 },
116068   { 156, 1 },
116069   { 156, 0 },
116070   { 154, 5 },
116071   { 154, 2 },
116072   { 161, 0 },
116073   { 161, 2 },
116074   { 159, 3 },
116075   { 159, 1 },
116076   { 163, 3 },
116077   { 164, 1 },
116078   { 167, 1 },
116079   { 167, 1 },
116080   { 168, 1 },
116081   { 151, 1 },
116082   { 151, 1 },
116083   { 151, 1 },
116084   { 165, 0 },
116085   { 165, 1 },
116086   { 169, 1 },
116087   { 169, 4 },
116088   { 169, 6 },
116089   { 170, 1 },
116090   { 170, 2 },
116091   { 171, 1 },
116092   { 171, 1 },
116093   { 166, 2 },
116094   { 166, 0 },
116095   { 174, 2 },
116096   { 174, 2 },
116097   { 174, 4 },
116098   { 174, 3 },
116099   { 174, 3 },
116100   { 174, 2 },
116101   { 174, 2 },
116102   { 174, 3 },
116103   { 174, 5 },
116104   { 174, 2 },
116105   { 174, 4 },
116106   { 174, 4 },
116107   { 174, 1 },
116108   { 174, 2 },
116109   { 179, 0 },
116110   { 179, 1 },
116111   { 181, 0 },
116112   { 181, 2 },
116113   { 183, 2 },
116114   { 183, 3 },
116115   { 183, 3 },
116116   { 183, 3 },
116117   { 184, 2 },
116118   { 184, 2 },
116119   { 184, 1 },
116120   { 184, 1 },
116121   { 184, 2 },
116122   { 182, 3 },
116123   { 182, 2 },
116124   { 185, 0 },
116125   { 185, 2 },
116126   { 185, 2 },
116127   { 160, 0 },
116128   { 160, 2 },
116129   { 186, 3 },
116130   { 186, 1 },
116131   { 187, 1 },
116132   { 187, 0 },
116133   { 188, 2 },
116134   { 188, 7 },
116135   { 188, 5 },
116136   { 188, 5 },
116137   { 188, 10 },
116138   { 190, 0 },
116139   { 190, 1 },
116140   { 177, 0 },
116141   { 177, 3 },
116142   { 191, 0 },
116143   { 191, 2 },
116144   { 192, 1 },
116145   { 192, 1 },
116146   { 192, 1 },
116147   { 148, 4 },
116148   { 194, 2 },
116149   { 194, 0 },
116150   { 148, 8 },
116151   { 148, 4 },
116152   { 148, 1 },
116153   { 162, 1 },
116154   { 162, 3 },
116155   { 197, 1 },
116156   { 197, 2 },
116157   { 197, 1 },
116158   { 196, 9 },
116159   { 198, 1 },
116160   { 198, 1 },
116161   { 198, 0 },
116162   { 206, 2 },
116163   { 206, 0 },
116164   { 199, 3 },
116165   { 199, 2 },
116166   { 199, 4 },
116167   { 207, 2 },
116168   { 207, 1 },
116169   { 207, 0 },
116170   { 200, 0 },
116171   { 200, 2 },
116172   { 209, 2 },
116173   { 209, 0 },
116174   { 208, 7 },
116175   { 208, 7 },
116176   { 208, 7 },
116177   { 158, 0 },
116178   { 158, 2 },
116179   { 195, 2 },
116180   { 210, 1 },
116181   { 210, 2 },
116182   { 210, 3 },
116183   { 210, 4 },
116184   { 212, 2 },
116185   { 212, 0 },
116186   { 211, 0 },
116187   { 211, 3 },
116188   { 211, 2 },
116189   { 213, 4 },
116190   { 213, 0 },
116191   { 204, 0 },
116192   { 204, 3 },
116193   { 216, 4 },
116194   { 216, 2 },
116195   { 178, 1 },
116196   { 178, 1 },
116197   { 178, 0 },
116198   { 202, 0 },
116199   { 202, 3 },
116200   { 203, 0 },
116201   { 203, 2 },
116202   { 205, 0 },
116203   { 205, 2 },
116204   { 205, 4 },
116205   { 205, 4 },
116206   { 148, 5 },
116207   { 201, 0 },
116208   { 201, 2 },
116209   { 148, 7 },
116210   { 218, 5 },
116211   { 218, 3 },
116212   { 148, 5 },
116213   { 148, 5 },
116214   { 148, 6 },
116215   { 219, 2 },
116216   { 219, 1 },
116217   { 221, 4 },
116218   { 221, 5 },
116219   { 220, 0 },
116220   { 220, 3 },
116221   { 215, 3 },
116222   { 215, 1 },
116223   { 176, 1 },
116224   { 176, 3 },
116225   { 175, 1 },
116226   { 176, 1 },
116227   { 176, 1 },
116228   { 176, 3 },
116229   { 176, 5 },
116230   { 175, 1 },
116231   { 175, 1 },
116232   { 176, 1 },
116233   { 176, 1 },
116234   { 176, 3 },
116235   { 176, 6 },
116236   { 176, 5 },
116237   { 176, 4 },
116238   { 175, 1 },
116239   { 176, 3 },
116240   { 176, 3 },
116241   { 176, 3 },
116242   { 176, 3 },
116243   { 176, 3 },
116244   { 176, 3 },
116245   { 176, 3 },
116246   { 176, 3 },
116247   { 223, 1 },
116248   { 223, 2 },
116249   { 223, 1 },
116250   { 223, 2 },
116251   { 176, 3 },
116252   { 176, 5 },
116253   { 176, 2 },
116254   { 176, 3 },
116255   { 176, 3 },
116256   { 176, 4 },
116257   { 176, 2 },
116258   { 176, 2 },
116259   { 176, 2 },
116260   { 176, 2 },
116261   { 224, 1 },
116262   { 224, 2 },
116263   { 176, 5 },
116264   { 225, 1 },
116265   { 225, 2 },
116266   { 176, 5 },
116267   { 176, 3 },
116268   { 176, 5 },
116269   { 176, 4 },
116270   { 176, 4 },
116271   { 176, 5 },
116272   { 227, 5 },
116273   { 227, 4 },
116274   { 228, 2 },
116275   { 228, 0 },
116276   { 226, 1 },
116277   { 226, 0 },
116278   { 222, 1 },
116279   { 222, 0 },
116280   { 217, 3 },
116281   { 217, 1 },
116282   { 148, 12 },
116283   { 229, 1 },
116284   { 229, 0 },
116285   { 180, 0 },
116286   { 180, 3 },
116287   { 189, 5 },
116288   { 189, 3 },
116289   { 230, 0 },
116290   { 230, 2 },
116291   { 148, 4 },
116292   { 148, 1 },
116293   { 148, 2 },
116294   { 148, 3 },
116295   { 148, 5 },
116296   { 148, 6 },
116297   { 148, 5 },
116298   { 148, 6 },
116299   { 231, 1 },
116300   { 231, 1 },
116301   { 231, 1 },
116302   { 231, 1 },
116303   { 231, 1 },
116304   { 172, 2 },
116305   { 172, 1 },
116306   { 173, 2 },
116307   { 232, 1 },
116308   { 148, 5 },
116309   { 233, 11 },
116310   { 235, 1 },
116311   { 235, 1 },
116312   { 235, 2 },
116313   { 235, 0 },
116314   { 236, 1 },
116315   { 236, 1 },
116316   { 236, 3 },
116317   { 237, 0 },
116318   { 237, 3 },
116319   { 238, 0 },
116320   { 238, 2 },
116321   { 234, 3 },
116322   { 234, 2 },
116323   { 240, 1 },
116324   { 240, 3 },
116325   { 241, 0 },
116326   { 241, 3 },
116327   { 241, 2 },
116328   { 239, 7 },
116329   { 239, 5 },
116330   { 239, 5 },
116331   { 239, 5 },
116332   { 239, 1 },
116333   { 176, 4 },
116334   { 176, 6 },
116335   { 193, 1 },
116336   { 193, 1 },
116337   { 193, 1 },
116338   { 148, 4 },
116339   { 148, 6 },
116340   { 148, 3 },
116341   { 243, 0 },
116342   { 243, 2 },
116343   { 242, 1 },
116344   { 242, 0 },
116345   { 148, 1 },
116346   { 148, 3 },
116347   { 148, 1 },
116348   { 148, 3 },
116349   { 148, 6 },
116350   { 148, 6 },
116351   { 244, 1 },
116352   { 245, 0 },
116353   { 245, 1 },
116354   { 148, 1 },
116355   { 148, 4 },
116356   { 246, 8 },
116357   { 247, 1 },
116358   { 247, 3 },
116359   { 248, 0 },
116360   { 248, 2 },
116361   { 249, 1 },
116362   { 249, 3 },
116363   { 250, 1 },
116364   { 251, 0 },
116365   { 251, 4 },
116366   { 251, 2 },
116367 };
116368 
116369 static void yy_accept(yyParser*);  /* Forward Declaration */
116370 
116371 /*
116372 ** Perform a reduce action and the shift that must immediately
116373 ** follow the reduce.
116374 */
116375 static void yy_reduce(
116376   yyParser *yypParser,         /* The parser */
116377   int yyruleno                 /* Number of the rule by which to reduce */
116378 ){
116379   int yygoto;                     /* The next state */
116380   int yyact;                      /* The next action */
116381   YYMINORTYPE yygotominor;        /* The LHS of the rule reduced */
116382   yyStackEntry *yymsp;            /* The top of the parser's stack */
116383   int yysize;                     /* Amount to pop the stack */
116384   sqlite3ParserARG_FETCH;
116385   yymsp = &yypParser->yystack[yypParser->yyidx];
116386 #ifndef NDEBUG
116387   if( yyTraceFILE && yyruleno>=0 
116388         && yyruleno<(int)(sizeof(yyRuleName)/sizeof(yyRuleName[0])) ){
116389     fprintf(yyTraceFILE, "%sReduce [%s].\n", yyTracePrompt,
116390       yyRuleName[yyruleno]);
116391   }
116392 #endif /* NDEBUG */
116393 
116394   /* Silence complaints from purify about yygotominor being uninitialized
116395   ** in some cases when it is copied into the stack after the following
116396   ** switch.  yygotominor is uninitialized when a rule reduces that does
116397   ** not set the value of its left-hand side nonterminal.  Leaving the
116398   ** value of the nonterminal uninitialized is utterly harmless as long
116399   ** as the value is never used.  So really the only thing this code
116400   ** accomplishes is to quieten purify.  
116401   **
116402   ** 2007-01-16:  The wireshark project (www.wireshark.org) reports that
116403   ** without this code, their parser segfaults.  I'm not sure what there
116404   ** parser is doing to make this happen.  This is the second bug report
116405   ** from wireshark this week.  Clearly they are stressing Lemon in ways
116406   ** that it has not been previously stressed...  (SQLite ticket #2172)
116407   */
116408   /*memset(&yygotominor, 0, sizeof(yygotominor));*/
116409   yygotominor = yyzerominor;
116410 
116411 
116412   switch( yyruleno ){
116413   /* Beginning here are the reduction cases.  A typical example
116414   ** follows:
116415   **   case 0:
116416   **  #line <lineno> <grammarfile>
116417   **     { ... }           // User supplied code
116418   **  #line <lineno> <thisfile>
116419   **     break;
116420   */
116421       case 5: /* explain ::= */
116422 { sqlite3BeginParse(pParse, 0); }
116423         break;
116424       case 6: /* explain ::= EXPLAIN */
116425 { sqlite3BeginParse(pParse, 1); }
116426         break;
116427       case 7: /* explain ::= EXPLAIN QUERY PLAN */
116428 { sqlite3BeginParse(pParse, 2); }
116429         break;
116430       case 8: /* cmdx ::= cmd */
116431 { sqlite3FinishCoding(pParse); }
116432         break;
116433       case 9: /* cmd ::= BEGIN transtype trans_opt */
116434 {sqlite3BeginTransaction(pParse, yymsp[-1].minor.yy4);}
116435         break;
116436       case 13: /* transtype ::= */
116437 {yygotominor.yy4 = TK_DEFERRED;}
116438         break;
116439       case 14: /* transtype ::= DEFERRED */
116440       case 15: /* transtype ::= IMMEDIATE */ yytestcase(yyruleno==15);
116441       case 16: /* transtype ::= EXCLUSIVE */ yytestcase(yyruleno==16);
116442       case 117: /* multiselect_op ::= UNION */ yytestcase(yyruleno==117);
116443       case 119: /* multiselect_op ::= EXCEPT|INTERSECT */ yytestcase(yyruleno==119);
116444 {yygotominor.yy4 = yymsp[0].major;}
116445         break;
116446       case 17: /* cmd ::= COMMIT trans_opt */
116447       case 18: /* cmd ::= END trans_opt */ yytestcase(yyruleno==18);
116448 {sqlite3CommitTransaction(pParse);}
116449         break;
116450       case 19: /* cmd ::= ROLLBACK trans_opt */
116451 {sqlite3RollbackTransaction(pParse);}
116452         break;
116453       case 22: /* cmd ::= SAVEPOINT nm */
116454 {
116455   sqlite3Savepoint(pParse, SAVEPOINT_BEGIN, &yymsp[0].minor.yy0);
116456 }
116457         break;
116458       case 23: /* cmd ::= RELEASE savepoint_opt nm */
116459 {
116460   sqlite3Savepoint(pParse, SAVEPOINT_RELEASE, &yymsp[0].minor.yy0);
116461 }
116462         break;
116463       case 24: /* cmd ::= ROLLBACK trans_opt TO savepoint_opt nm */
116464 {
116465   sqlite3Savepoint(pParse, SAVEPOINT_ROLLBACK, &yymsp[0].minor.yy0);
116466 }
116467         break;
116468       case 26: /* create_table ::= createkw temp TABLE ifnotexists nm dbnm */
116469 {
116470    sqlite3StartTable(pParse,&yymsp[-1].minor.yy0,&yymsp[0].minor.yy0,yymsp[-4].minor.yy4,0,0,yymsp[-2].minor.yy4);
116471 }
116472         break;
116473       case 27: /* createkw ::= CREATE */
116474 {
116475   pParse->db->lookaside.bEnabled = 0;
116476   yygotominor.yy0 = yymsp[0].minor.yy0;
116477 }
116478         break;
116479       case 28: /* ifnotexists ::= */
116480       case 31: /* temp ::= */ yytestcase(yyruleno==31);
116481       case 71: /* autoinc ::= */ yytestcase(yyruleno==71);
116482       case 84: /* defer_subclause ::= NOT DEFERRABLE init_deferred_pred_opt */ yytestcase(yyruleno==84);
116483       case 86: /* init_deferred_pred_opt ::= */ yytestcase(yyruleno==86);
116484       case 88: /* init_deferred_pred_opt ::= INITIALLY IMMEDIATE */ yytestcase(yyruleno==88);
116485       case 100: /* defer_subclause_opt ::= */ yytestcase(yyruleno==100);
116486       case 111: /* ifexists ::= */ yytestcase(yyruleno==111);
116487       case 223: /* between_op ::= BETWEEN */ yytestcase(yyruleno==223);
116488       case 226: /* in_op ::= IN */ yytestcase(yyruleno==226);
116489 {yygotominor.yy4 = 0;}
116490         break;
116491       case 29: /* ifnotexists ::= IF NOT EXISTS */
116492       case 30: /* temp ::= TEMP */ yytestcase(yyruleno==30);
116493       case 72: /* autoinc ::= AUTOINCR */ yytestcase(yyruleno==72);
116494       case 87: /* init_deferred_pred_opt ::= INITIALLY DEFERRED */ yytestcase(yyruleno==87);
116495       case 110: /* ifexists ::= IF EXISTS */ yytestcase(yyruleno==110);
116496       case 224: /* between_op ::= NOT BETWEEN */ yytestcase(yyruleno==224);
116497       case 227: /* in_op ::= NOT IN */ yytestcase(yyruleno==227);
116498 {yygotominor.yy4 = 1;}
116499         break;
116500       case 32: /* create_table_args ::= LP columnlist conslist_opt RP table_options */
116501 {
116502   sqlite3EndTable(pParse,&yymsp[-2].minor.yy0,&yymsp[-1].minor.yy0,yymsp[0].minor.yy210,0);
116503 }
116504         break;
116505       case 33: /* create_table_args ::= AS select */
116506 {
116507   sqlite3EndTable(pParse,0,0,0,yymsp[0].minor.yy387);
116508   sqlite3SelectDelete(pParse->db, yymsp[0].minor.yy387);
116509 }
116510         break;
116511       case 34: /* table_options ::= */
116512 {yygotominor.yy210 = 0;}
116513         break;
116514       case 35: /* table_options ::= WITHOUT nm */
116515 {
116516   if( yymsp[0].minor.yy0.n==5 && sqlite3_strnicmp(yymsp[0].minor.yy0.z,"rowid",5)==0 ){
116517     yygotominor.yy210 = TF_WithoutRowid;
116518   }else{
116519     yygotominor.yy210 = 0;
116520     sqlite3ErrorMsg(pParse, "unknown table option: %.*s", yymsp[0].minor.yy0.n, yymsp[0].minor.yy0.z);
116521   }
116522 }
116523         break;
116524       case 38: /* column ::= columnid type carglist */
116525 {
116526   yygotominor.yy0.z = yymsp[-2].minor.yy0.z;
116527   yygotominor.yy0.n = (int)(pParse->sLastToken.z-yymsp[-2].minor.yy0.z) + pParse->sLastToken.n;
116528 }
116529         break;
116530       case 39: /* columnid ::= nm */
116531 {
116532   sqlite3AddColumn(pParse,&yymsp[0].minor.yy0);
116533   yygotominor.yy0 = yymsp[0].minor.yy0;
116534   pParse->constraintName.n = 0;
116535 }
116536         break;
116537       case 40: /* id ::= ID */
116538       case 41: /* id ::= INDEXED */ yytestcase(yyruleno==41);
116539       case 42: /* ids ::= ID|STRING */ yytestcase(yyruleno==42);
116540       case 43: /* nm ::= id */ yytestcase(yyruleno==43);
116541       case 44: /* nm ::= STRING */ yytestcase(yyruleno==44);
116542       case 45: /* nm ::= JOIN_KW */ yytestcase(yyruleno==45);
116543       case 48: /* typetoken ::= typename */ yytestcase(yyruleno==48);
116544       case 51: /* typename ::= ids */ yytestcase(yyruleno==51);
116545       case 129: /* as ::= AS nm */ yytestcase(yyruleno==129);
116546       case 130: /* as ::= ids */ yytestcase(yyruleno==130);
116547       case 140: /* dbnm ::= DOT nm */ yytestcase(yyruleno==140);
116548       case 149: /* indexed_opt ::= INDEXED BY nm */ yytestcase(yyruleno==149);
116549       case 252: /* collate ::= COLLATE ids */ yytestcase(yyruleno==252);
116550       case 261: /* nmnum ::= plus_num */ yytestcase(yyruleno==261);
116551       case 262: /* nmnum ::= nm */ yytestcase(yyruleno==262);
116552       case 263: /* nmnum ::= ON */ yytestcase(yyruleno==263);
116553       case 264: /* nmnum ::= DELETE */ yytestcase(yyruleno==264);
116554       case 265: /* nmnum ::= DEFAULT */ yytestcase(yyruleno==265);
116555       case 266: /* plus_num ::= PLUS number */ yytestcase(yyruleno==266);
116556       case 267: /* plus_num ::= number */ yytestcase(yyruleno==267);
116557       case 268: /* minus_num ::= MINUS number */ yytestcase(yyruleno==268);
116558       case 269: /* number ::= INTEGER|FLOAT */ yytestcase(yyruleno==269);
116559       case 285: /* trnm ::= nm */ yytestcase(yyruleno==285);
116560 {yygotominor.yy0 = yymsp[0].minor.yy0;}
116561         break;
116562       case 47: /* type ::= typetoken */
116563 {sqlite3AddColumnType(pParse,&yymsp[0].minor.yy0);}
116564         break;
116565       case 49: /* typetoken ::= typename LP signed RP */
116566 {
116567   yygotominor.yy0.z = yymsp[-3].minor.yy0.z;
116568   yygotominor.yy0.n = (int)(&yymsp[0].minor.yy0.z[yymsp[0].minor.yy0.n] - yymsp[-3].minor.yy0.z);
116569 }
116570         break;
116571       case 50: /* typetoken ::= typename LP signed COMMA signed RP */
116572 {
116573   yygotominor.yy0.z = yymsp[-5].minor.yy0.z;
116574   yygotominor.yy0.n = (int)(&yymsp[0].minor.yy0.z[yymsp[0].minor.yy0.n] - yymsp[-5].minor.yy0.z);
116575 }
116576         break;
116577       case 52: /* typename ::= typename ids */
116578 {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);}
116579         break;
116580       case 57: /* ccons ::= CONSTRAINT nm */
116581       case 95: /* tcons ::= CONSTRAINT nm */ yytestcase(yyruleno==95);
116582 {pParse->constraintName = yymsp[0].minor.yy0;}
116583         break;
116584       case 58: /* ccons ::= DEFAULT term */
116585       case 60: /* ccons ::= DEFAULT PLUS term */ yytestcase(yyruleno==60);
116586 {sqlite3AddDefaultValue(pParse,&yymsp[0].minor.yy118);}
116587         break;
116588       case 59: /* ccons ::= DEFAULT LP expr RP */
116589 {sqlite3AddDefaultValue(pParse,&yymsp[-1].minor.yy118);}
116590         break;
116591       case 61: /* ccons ::= DEFAULT MINUS term */
116592 {
116593   ExprSpan v;
116594   v.pExpr = sqlite3PExpr(pParse, TK_UMINUS, yymsp[0].minor.yy118.pExpr, 0, 0);
116595   v.zStart = yymsp[-1].minor.yy0.z;
116596   v.zEnd = yymsp[0].minor.yy118.zEnd;
116597   sqlite3AddDefaultValue(pParse,&v);
116598 }
116599         break;
116600       case 62: /* ccons ::= DEFAULT id */
116601 {
116602   ExprSpan v;
116603   spanExpr(&v, pParse, TK_STRING, &yymsp[0].minor.yy0);
116604   sqlite3AddDefaultValue(pParse,&v);
116605 }
116606         break;
116607       case 64: /* ccons ::= NOT NULL onconf */
116608 {sqlite3AddNotNull(pParse, yymsp[0].minor.yy4);}
116609         break;
116610       case 65: /* ccons ::= PRIMARY KEY sortorder onconf autoinc */
116611 {sqlite3AddPrimaryKey(pParse,0,yymsp[-1].minor.yy4,yymsp[0].minor.yy4,yymsp[-2].minor.yy4);}
116612         break;
116613       case 66: /* ccons ::= UNIQUE onconf */
116614 {sqlite3CreateIndex(pParse,0,0,0,0,yymsp[0].minor.yy4,0,0,0,0);}
116615         break;
116616       case 67: /* ccons ::= CHECK LP expr RP */
116617 {sqlite3AddCheckConstraint(pParse,yymsp[-1].minor.yy118.pExpr);}
116618         break;
116619       case 68: /* ccons ::= REFERENCES nm idxlist_opt refargs */
116620 {sqlite3CreateForeignKey(pParse,0,&yymsp[-2].minor.yy0,yymsp[-1].minor.yy322,yymsp[0].minor.yy4);}
116621         break;
116622       case 69: /* ccons ::= defer_subclause */
116623 {sqlite3DeferForeignKey(pParse,yymsp[0].minor.yy4);}
116624         break;
116625       case 70: /* ccons ::= COLLATE ids */
116626 {sqlite3AddCollateType(pParse, &yymsp[0].minor.yy0);}
116627         break;
116628       case 73: /* refargs ::= */
116629 { yygotominor.yy4 = OE_None*0x0101; /* EV: R-19803-45884 */}
116630         break;
116631       case 74: /* refargs ::= refargs refarg */
116632 { yygotominor.yy4 = (yymsp[-1].minor.yy4 & ~yymsp[0].minor.yy215.mask) | yymsp[0].minor.yy215.value; }
116633         break;
116634       case 75: /* refarg ::= MATCH nm */
116635       case 76: /* refarg ::= ON INSERT refact */ yytestcase(yyruleno==76);
116636 { yygotominor.yy215.value = 0;     yygotominor.yy215.mask = 0x000000; }
116637         break;
116638       case 77: /* refarg ::= ON DELETE refact */
116639 { yygotominor.yy215.value = yymsp[0].minor.yy4;     yygotominor.yy215.mask = 0x0000ff; }
116640         break;
116641       case 78: /* refarg ::= ON UPDATE refact */
116642 { yygotominor.yy215.value = yymsp[0].minor.yy4<<8;  yygotominor.yy215.mask = 0x00ff00; }
116643         break;
116644       case 79: /* refact ::= SET NULL */
116645 { yygotominor.yy4 = OE_SetNull;  /* EV: R-33326-45252 */}
116646         break;
116647       case 80: /* refact ::= SET DEFAULT */
116648 { yygotominor.yy4 = OE_SetDflt;  /* EV: R-33326-45252 */}
116649         break;
116650       case 81: /* refact ::= CASCADE */
116651 { yygotominor.yy4 = OE_Cascade;  /* EV: R-33326-45252 */}
116652         break;
116653       case 82: /* refact ::= RESTRICT */
116654 { yygotominor.yy4 = OE_Restrict; /* EV: R-33326-45252 */}
116655         break;
116656       case 83: /* refact ::= NO ACTION */
116657 { yygotominor.yy4 = OE_None;     /* EV: R-33326-45252 */}
116658         break;
116659       case 85: /* defer_subclause ::= DEFERRABLE init_deferred_pred_opt */
116660       case 101: /* defer_subclause_opt ::= defer_subclause */ yytestcase(yyruleno==101);
116661       case 103: /* onconf ::= ON CONFLICT resolvetype */ yytestcase(yyruleno==103);
116662       case 106: /* resolvetype ::= raisetype */ yytestcase(yyruleno==106);
116663 {yygotominor.yy4 = yymsp[0].minor.yy4;}
116664         break;
116665       case 89: /* conslist_opt ::= */
116666 {yygotominor.yy0.n = 0; yygotominor.yy0.z = 0;}
116667         break;
116668       case 90: /* conslist_opt ::= COMMA conslist */
116669 {yygotominor.yy0 = yymsp[-1].minor.yy0;}
116670         break;
116671       case 93: /* tconscomma ::= COMMA */
116672 {pParse->constraintName.n = 0;}
116673         break;
116674       case 96: /* tcons ::= PRIMARY KEY LP idxlist autoinc RP onconf */
116675 {sqlite3AddPrimaryKey(pParse,yymsp[-3].minor.yy322,yymsp[0].minor.yy4,yymsp[-2].minor.yy4,0);}
116676         break;
116677       case 97: /* tcons ::= UNIQUE LP idxlist RP onconf */
116678 {sqlite3CreateIndex(pParse,0,0,0,yymsp[-2].minor.yy322,yymsp[0].minor.yy4,0,0,0,0);}
116679         break;
116680       case 98: /* tcons ::= CHECK LP expr RP onconf */
116681 {sqlite3AddCheckConstraint(pParse,yymsp[-2].minor.yy118.pExpr);}
116682         break;
116683       case 99: /* tcons ::= FOREIGN KEY LP idxlist RP REFERENCES nm idxlist_opt refargs defer_subclause_opt */
116684 {
116685     sqlite3CreateForeignKey(pParse, yymsp[-6].minor.yy322, &yymsp[-3].minor.yy0, yymsp[-2].minor.yy322, yymsp[-1].minor.yy4);
116686     sqlite3DeferForeignKey(pParse, yymsp[0].minor.yy4);
116687 }
116688         break;
116689       case 102: /* onconf ::= */
116690 {yygotominor.yy4 = OE_Default;}
116691         break;
116692       case 104: /* orconf ::= */
116693 {yygotominor.yy210 = OE_Default;}
116694         break;
116695       case 105: /* orconf ::= OR resolvetype */
116696 {yygotominor.yy210 = (u8)yymsp[0].minor.yy4;}
116697         break;
116698       case 107: /* resolvetype ::= IGNORE */
116699 {yygotominor.yy4 = OE_Ignore;}
116700         break;
116701       case 108: /* resolvetype ::= REPLACE */
116702 {yygotominor.yy4 = OE_Replace;}
116703         break;
116704       case 109: /* cmd ::= DROP TABLE ifexists fullname */
116705 {
116706   sqlite3DropTable(pParse, yymsp[0].minor.yy259, 0, yymsp[-1].minor.yy4);
116707 }
116708         break;
116709       case 112: /* cmd ::= createkw temp VIEW ifnotexists nm dbnm AS select */
116710 {
116711   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);
116712 }
116713         break;
116714       case 113: /* cmd ::= DROP VIEW ifexists fullname */
116715 {
116716   sqlite3DropTable(pParse, yymsp[0].minor.yy259, 1, yymsp[-1].minor.yy4);
116717 }
116718         break;
116719       case 114: /* cmd ::= select */
116720 {
116721   SelectDest dest = {SRT_Output, 0, 0, 0, 0};
116722   sqlite3Select(pParse, yymsp[0].minor.yy387, &dest);
116723   sqlite3ExplainBegin(pParse->pVdbe);
116724   sqlite3ExplainSelect(pParse->pVdbe, yymsp[0].minor.yy387);
116725   sqlite3ExplainFinish(pParse->pVdbe);
116726   sqlite3SelectDelete(pParse->db, yymsp[0].minor.yy387);
116727 }
116728         break;
116729       case 115: /* select ::= oneselect */
116730 {yygotominor.yy387 = yymsp[0].minor.yy387;}
116731         break;
116732       case 116: /* select ::= select multiselect_op oneselect */
116733 {
116734   if( yymsp[0].minor.yy387 ){
116735     yymsp[0].minor.yy387->op = (u8)yymsp[-1].minor.yy4;
116736     yymsp[0].minor.yy387->pPrior = yymsp[-2].minor.yy387;
116737     if( yymsp[-1].minor.yy4!=TK_ALL ) pParse->hasCompound = 1;
116738   }else{
116739     sqlite3SelectDelete(pParse->db, yymsp[-2].minor.yy387);
116740   }
116741   yygotominor.yy387 = yymsp[0].minor.yy387;
116742 }
116743         break;
116744       case 118: /* multiselect_op ::= UNION ALL */
116745 {yygotominor.yy4 = TK_ALL;}
116746         break;
116747       case 120: /* oneselect ::= SELECT distinct selcollist from where_opt groupby_opt having_opt orderby_opt limit_opt */
116748 {
116749   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);
116750 }
116751         break;
116752       case 121: /* distinct ::= DISTINCT */
116753 {yygotominor.yy177 = SF_Distinct;}
116754         break;
116755       case 122: /* distinct ::= ALL */
116756       case 123: /* distinct ::= */ yytestcase(yyruleno==123);
116757 {yygotominor.yy177 = 0;}
116758         break;
116759       case 124: /* sclp ::= selcollist COMMA */
116760       case 248: /* idxlist_opt ::= LP idxlist RP */ yytestcase(yyruleno==248);
116761 {yygotominor.yy322 = yymsp[-1].minor.yy322;}
116762         break;
116763       case 125: /* sclp ::= */
116764       case 153: /* orderby_opt ::= */ yytestcase(yyruleno==153);
116765       case 160: /* groupby_opt ::= */ yytestcase(yyruleno==160);
116766       case 241: /* exprlist ::= */ yytestcase(yyruleno==241);
116767       case 247: /* idxlist_opt ::= */ yytestcase(yyruleno==247);
116768 {yygotominor.yy322 = 0;}
116769         break;
116770       case 126: /* selcollist ::= sclp expr as */
116771 {
116772    yygotominor.yy322 = sqlite3ExprListAppend(pParse, yymsp[-2].minor.yy322, yymsp[-1].minor.yy118.pExpr);
116773    if( yymsp[0].minor.yy0.n>0 ) sqlite3ExprListSetName(pParse, yygotominor.yy322, &yymsp[0].minor.yy0, 1);
116774    sqlite3ExprListSetSpan(pParse,yygotominor.yy322,&yymsp[-1].minor.yy118);
116775 }
116776         break;
116777       case 127: /* selcollist ::= sclp STAR */
116778 {
116779   Expr *p = sqlite3Expr(pParse->db, TK_ALL, 0);
116780   yygotominor.yy322 = sqlite3ExprListAppend(pParse, yymsp[-1].minor.yy322, p);
116781 }
116782         break;
116783       case 128: /* selcollist ::= sclp nm DOT STAR */
116784 {
116785   Expr *pRight = sqlite3PExpr(pParse, TK_ALL, 0, 0, &yymsp[0].minor.yy0);
116786   Expr *pLeft = sqlite3PExpr(pParse, TK_ID, 0, 0, &yymsp[-2].minor.yy0);
116787   Expr *pDot = sqlite3PExpr(pParse, TK_DOT, pLeft, pRight, 0);
116788   yygotominor.yy322 = sqlite3ExprListAppend(pParse,yymsp[-3].minor.yy322, pDot);
116789 }
116790         break;
116791       case 131: /* as ::= */
116792 {yygotominor.yy0.n = 0;}
116793         break;
116794       case 132: /* from ::= */
116795 {yygotominor.yy259 = sqlite3DbMallocZero(pParse->db, sizeof(*yygotominor.yy259));}
116796         break;
116797       case 133: /* from ::= FROM seltablist */
116798 {
116799   yygotominor.yy259 = yymsp[0].minor.yy259;
116800   sqlite3SrcListShiftJoinType(yygotominor.yy259);
116801 }
116802         break;
116803       case 134: /* stl_prefix ::= seltablist joinop */
116804 {
116805    yygotominor.yy259 = yymsp[-1].minor.yy259;
116806    if( ALWAYS(yygotominor.yy259 && yygotominor.yy259->nSrc>0) ) yygotominor.yy259->a[yygotominor.yy259->nSrc-1].jointype = (u8)yymsp[0].minor.yy4;
116807 }
116808         break;
116809       case 135: /* stl_prefix ::= */
116810 {yygotominor.yy259 = 0;}
116811         break;
116812       case 136: /* seltablist ::= stl_prefix nm dbnm as indexed_opt on_opt using_opt */
116813 {
116814   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);
116815   sqlite3SrcListIndexedBy(pParse, yygotominor.yy259, &yymsp[-2].minor.yy0);
116816 }
116817         break;
116818       case 137: /* seltablist ::= stl_prefix LP select RP as on_opt using_opt */
116819 {
116820     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);
116821   }
116822         break;
116823       case 138: /* seltablist ::= stl_prefix LP seltablist RP as on_opt using_opt */
116824 {
116825     if( yymsp[-6].minor.yy259==0 && yymsp[-2].minor.yy0.n==0 && yymsp[-1].minor.yy314==0 && yymsp[0].minor.yy384==0 ){
116826       yygotominor.yy259 = yymsp[-4].minor.yy259;
116827     }else if( yymsp[-4].minor.yy259->nSrc==1 ){
116828       yygotominor.yy259 = sqlite3SrcListAppendFromTerm(pParse,yymsp[-6].minor.yy259,0,0,&yymsp[-2].minor.yy0,0,yymsp[-1].minor.yy314,yymsp[0].minor.yy384);
116829       if( yygotominor.yy259 ){
116830         struct SrcList_item *pNew = &yygotominor.yy259->a[yygotominor.yy259->nSrc-1];
116831         struct SrcList_item *pOld = yymsp[-4].minor.yy259->a;
116832         pNew->zName = pOld->zName;
116833         pNew->zDatabase = pOld->zDatabase;
116834         pNew->pSelect = pOld->pSelect;
116835         pOld->zName = pOld->zDatabase = 0;
116836         pOld->pSelect = 0;
116837       }
116838       sqlite3SrcListDelete(pParse->db, yymsp[-4].minor.yy259);
116839     }else{
116840       Select *pSubquery;
116841       sqlite3SrcListShiftJoinType(yymsp[-4].minor.yy259);
116842       pSubquery = sqlite3SelectNew(pParse,0,yymsp[-4].minor.yy259,0,0,0,0,SF_NestedFrom,0,0);
116843       yygotominor.yy259 = sqlite3SrcListAppendFromTerm(pParse,yymsp[-6].minor.yy259,0,0,&yymsp[-2].minor.yy0,pSubquery,yymsp[-1].minor.yy314,yymsp[0].minor.yy384);
116844     }
116845   }
116846         break;
116847       case 139: /* dbnm ::= */
116848       case 148: /* indexed_opt ::= */ yytestcase(yyruleno==148);
116849 {yygotominor.yy0.z=0; yygotominor.yy0.n=0;}
116850         break;
116851       case 141: /* fullname ::= nm dbnm */
116852 {yygotominor.yy259 = sqlite3SrcListAppend(pParse->db,0,&yymsp[-1].minor.yy0,&yymsp[0].minor.yy0);}
116853         break;
116854       case 142: /* joinop ::= COMMA|JOIN */
116855 { yygotominor.yy4 = JT_INNER; }
116856         break;
116857       case 143: /* joinop ::= JOIN_KW JOIN */
116858 { yygotominor.yy4 = sqlite3JoinType(pParse,&yymsp[-1].minor.yy0,0,0); }
116859         break;
116860       case 144: /* joinop ::= JOIN_KW nm JOIN */
116861 { yygotominor.yy4 = sqlite3JoinType(pParse,&yymsp[-2].minor.yy0,&yymsp[-1].minor.yy0,0); }
116862         break;
116863       case 145: /* joinop ::= JOIN_KW nm nm JOIN */
116864 { yygotominor.yy4 = sqlite3JoinType(pParse,&yymsp[-3].minor.yy0,&yymsp[-2].minor.yy0,&yymsp[-1].minor.yy0); }
116865         break;
116866       case 146: /* on_opt ::= ON expr */
116867       case 163: /* having_opt ::= HAVING expr */ yytestcase(yyruleno==163);
116868       case 170: /* where_opt ::= WHERE expr */ yytestcase(yyruleno==170);
116869       case 236: /* case_else ::= ELSE expr */ yytestcase(yyruleno==236);
116870       case 238: /* case_operand ::= expr */ yytestcase(yyruleno==238);
116871 {yygotominor.yy314 = yymsp[0].minor.yy118.pExpr;}
116872         break;
116873       case 147: /* on_opt ::= */
116874       case 162: /* having_opt ::= */ yytestcase(yyruleno==162);
116875       case 169: /* where_opt ::= */ yytestcase(yyruleno==169);
116876       case 237: /* case_else ::= */ yytestcase(yyruleno==237);
116877       case 239: /* case_operand ::= */ yytestcase(yyruleno==239);
116878 {yygotominor.yy314 = 0;}
116879         break;
116880       case 150: /* indexed_opt ::= NOT INDEXED */
116881 {yygotominor.yy0.z=0; yygotominor.yy0.n=1;}
116882         break;
116883       case 151: /* using_opt ::= USING LP idlist RP */
116884       case 182: /* inscollist_opt ::= LP idlist RP */ yytestcase(yyruleno==182);
116885 {yygotominor.yy384 = yymsp[-1].minor.yy384;}
116886         break;
116887       case 152: /* using_opt ::= */
116888       case 181: /* inscollist_opt ::= */ yytestcase(yyruleno==181);
116889 {yygotominor.yy384 = 0;}
116890         break;
116891       case 154: /* orderby_opt ::= ORDER BY sortlist */
116892       case 161: /* groupby_opt ::= GROUP BY nexprlist */ yytestcase(yyruleno==161);
116893       case 240: /* exprlist ::= nexprlist */ yytestcase(yyruleno==240);
116894 {yygotominor.yy322 = yymsp[0].minor.yy322;}
116895         break;
116896       case 155: /* sortlist ::= sortlist COMMA expr sortorder */
116897 {
116898   yygotominor.yy322 = sqlite3ExprListAppend(pParse,yymsp[-3].minor.yy322,yymsp[-1].minor.yy118.pExpr);
116899   if( yygotominor.yy322 ) yygotominor.yy322->a[yygotominor.yy322->nExpr-1].sortOrder = (u8)yymsp[0].minor.yy4;
116900 }
116901         break;
116902       case 156: /* sortlist ::= expr sortorder */
116903 {
116904   yygotominor.yy322 = sqlite3ExprListAppend(pParse,0,yymsp[-1].minor.yy118.pExpr);
116905   if( yygotominor.yy322 && ALWAYS(yygotominor.yy322->a) ) yygotominor.yy322->a[0].sortOrder = (u8)yymsp[0].minor.yy4;
116906 }
116907         break;
116908       case 157: /* sortorder ::= ASC */
116909       case 159: /* sortorder ::= */ yytestcase(yyruleno==159);
116910 {yygotominor.yy4 = SQLITE_SO_ASC;}
116911         break;
116912       case 158: /* sortorder ::= DESC */
116913 {yygotominor.yy4 = SQLITE_SO_DESC;}
116914         break;
116915       case 164: /* limit_opt ::= */
116916 {yygotominor.yy292.pLimit = 0; yygotominor.yy292.pOffset = 0;}
116917         break;
116918       case 165: /* limit_opt ::= LIMIT expr */
116919 {yygotominor.yy292.pLimit = yymsp[0].minor.yy118.pExpr; yygotominor.yy292.pOffset = 0;}
116920         break;
116921       case 166: /* limit_opt ::= LIMIT expr OFFSET expr */
116922 {yygotominor.yy292.pLimit = yymsp[-2].minor.yy118.pExpr; yygotominor.yy292.pOffset = yymsp[0].minor.yy118.pExpr;}
116923         break;
116924       case 167: /* limit_opt ::= LIMIT expr COMMA expr */
116925 {yygotominor.yy292.pOffset = yymsp[-2].minor.yy118.pExpr; yygotominor.yy292.pLimit = yymsp[0].minor.yy118.pExpr;}
116926         break;
116927       case 168: /* cmd ::= DELETE FROM fullname indexed_opt where_opt */
116928 {
116929   sqlite3SrcListIndexedBy(pParse, yymsp[-2].minor.yy259, &yymsp[-1].minor.yy0);
116930   sqlite3DeleteFrom(pParse,yymsp[-2].minor.yy259,yymsp[0].minor.yy314);
116931 }
116932         break;
116933       case 171: /* cmd ::= UPDATE orconf fullname indexed_opt SET setlist where_opt */
116934 {
116935   sqlite3SrcListIndexedBy(pParse, yymsp[-4].minor.yy259, &yymsp[-3].minor.yy0);
116936   sqlite3ExprListCheckLength(pParse,yymsp[-1].minor.yy322,"set list"); 
116937   sqlite3Update(pParse,yymsp[-4].minor.yy259,yymsp[-1].minor.yy322,yymsp[0].minor.yy314,yymsp[-5].minor.yy210);
116938 }
116939         break;
116940       case 172: /* setlist ::= setlist COMMA nm EQ expr */
116941 {
116942   yygotominor.yy322 = sqlite3ExprListAppend(pParse, yymsp[-4].minor.yy322, yymsp[0].minor.yy118.pExpr);
116943   sqlite3ExprListSetName(pParse, yygotominor.yy322, &yymsp[-2].minor.yy0, 1);
116944 }
116945         break;
116946       case 173: /* setlist ::= nm EQ expr */
116947 {
116948   yygotominor.yy322 = sqlite3ExprListAppend(pParse, 0, yymsp[0].minor.yy118.pExpr);
116949   sqlite3ExprListSetName(pParse, yygotominor.yy322, &yymsp[-2].minor.yy0, 1);
116950 }
116951         break;
116952       case 174: /* cmd ::= insert_cmd INTO fullname inscollist_opt valuelist */
116953 {sqlite3Insert(pParse, yymsp[-2].minor.yy259, yymsp[0].minor.yy260.pList, yymsp[0].minor.yy260.pSelect, yymsp[-1].minor.yy384, yymsp[-4].minor.yy210);}
116954         break;
116955       case 175: /* cmd ::= insert_cmd INTO fullname inscollist_opt select */
116956 {sqlite3Insert(pParse, yymsp[-2].minor.yy259, 0, yymsp[0].minor.yy387, yymsp[-1].minor.yy384, yymsp[-4].minor.yy210);}
116957         break;
116958       case 176: /* cmd ::= insert_cmd INTO fullname inscollist_opt DEFAULT VALUES */
116959 {sqlite3Insert(pParse, yymsp[-3].minor.yy259, 0, 0, yymsp[-2].minor.yy384, yymsp[-5].minor.yy210);}
116960         break;
116961       case 177: /* insert_cmd ::= INSERT orconf */
116962 {yygotominor.yy210 = yymsp[0].minor.yy210;}
116963         break;
116964       case 178: /* insert_cmd ::= REPLACE */
116965 {yygotominor.yy210 = OE_Replace;}
116966         break;
116967       case 179: /* valuelist ::= VALUES LP nexprlist RP */
116968 {
116969   yygotominor.yy260.pList = yymsp[-1].minor.yy322;
116970   yygotominor.yy260.pSelect = 0;
116971 }
116972         break;
116973       case 180: /* valuelist ::= valuelist COMMA LP exprlist RP */
116974 {
116975   Select *pRight = sqlite3SelectNew(pParse, yymsp[-1].minor.yy322, 0, 0, 0, 0, 0, 0, 0, 0);
116976   if( yymsp[-4].minor.yy260.pList ){
116977     yymsp[-4].minor.yy260.pSelect = sqlite3SelectNew(pParse, yymsp[-4].minor.yy260.pList, 0, 0, 0, 0, 0, 0, 0, 0);
116978     yymsp[-4].minor.yy260.pList = 0;
116979   }
116980   yygotominor.yy260.pList = 0;
116981   if( yymsp[-4].minor.yy260.pSelect==0 || pRight==0 ){
116982     sqlite3SelectDelete(pParse->db, pRight);
116983     sqlite3SelectDelete(pParse->db, yymsp[-4].minor.yy260.pSelect);
116984     yygotominor.yy260.pSelect = 0;
116985   }else{
116986     pRight->op = TK_ALL;
116987     pRight->pPrior = yymsp[-4].minor.yy260.pSelect;
116988     pRight->selFlags |= SF_Values;
116989     pRight->pPrior->selFlags |= SF_Values;
116990     yygotominor.yy260.pSelect = pRight;
116991   }
116992 }
116993         break;
116994       case 183: /* idlist ::= idlist COMMA nm */
116995 {yygotominor.yy384 = sqlite3IdListAppend(pParse->db,yymsp[-2].minor.yy384,&yymsp[0].minor.yy0);}
116996         break;
116997       case 184: /* idlist ::= nm */
116998 {yygotominor.yy384 = sqlite3IdListAppend(pParse->db,0,&yymsp[0].minor.yy0);}
116999         break;
117000       case 185: /* expr ::= term */
117001 {yygotominor.yy118 = yymsp[0].minor.yy118;}
117002         break;
117003       case 186: /* expr ::= LP expr RP */
117004 {yygotominor.yy118.pExpr = yymsp[-1].minor.yy118.pExpr; spanSet(&yygotominor.yy118,&yymsp[-2].minor.yy0,&yymsp[0].minor.yy0);}
117005         break;
117006       case 187: /* term ::= NULL */
117007       case 192: /* term ::= INTEGER|FLOAT|BLOB */ yytestcase(yyruleno==192);
117008       case 193: /* term ::= STRING */ yytestcase(yyruleno==193);
117009 {spanExpr(&yygotominor.yy118, pParse, yymsp[0].major, &yymsp[0].minor.yy0);}
117010         break;
117011       case 188: /* expr ::= id */
117012       case 189: /* expr ::= JOIN_KW */ yytestcase(yyruleno==189);
117013 {spanExpr(&yygotominor.yy118, pParse, TK_ID, &yymsp[0].minor.yy0);}
117014         break;
117015       case 190: /* expr ::= nm DOT nm */
117016 {
117017   Expr *temp1 = sqlite3PExpr(pParse, TK_ID, 0, 0, &yymsp[-2].minor.yy0);
117018   Expr *temp2 = sqlite3PExpr(pParse, TK_ID, 0, 0, &yymsp[0].minor.yy0);
117019   yygotominor.yy118.pExpr = sqlite3PExpr(pParse, TK_DOT, temp1, temp2, 0);
117020   spanSet(&yygotominor.yy118,&yymsp[-2].minor.yy0,&yymsp[0].minor.yy0);
117021 }
117022         break;
117023       case 191: /* expr ::= nm DOT nm DOT nm */
117024 {
117025   Expr *temp1 = sqlite3PExpr(pParse, TK_ID, 0, 0, &yymsp[-4].minor.yy0);
117026   Expr *temp2 = sqlite3PExpr(pParse, TK_ID, 0, 0, &yymsp[-2].minor.yy0);
117027   Expr *temp3 = sqlite3PExpr(pParse, TK_ID, 0, 0, &yymsp[0].minor.yy0);
117028   Expr *temp4 = sqlite3PExpr(pParse, TK_DOT, temp2, temp3, 0);
117029   yygotominor.yy118.pExpr = sqlite3PExpr(pParse, TK_DOT, temp1, temp4, 0);
117030   spanSet(&yygotominor.yy118,&yymsp[-4].minor.yy0,&yymsp[0].minor.yy0);
117031 }
117032         break;
117033       case 194: /* expr ::= REGISTER */
117034 {
117035   /* When doing a nested parse, one can include terms in an expression
117036   ** that look like this:   #1 #2 ...  These terms refer to registers
117037   ** in the virtual machine.  #N is the N-th register. */
117038   if( pParse->nested==0 ){
117039     sqlite3ErrorMsg(pParse, "near \"%T\": syntax error", &yymsp[0].minor.yy0);
117040     yygotominor.yy118.pExpr = 0;
117041   }else{
117042     yygotominor.yy118.pExpr = sqlite3PExpr(pParse, TK_REGISTER, 0, 0, &yymsp[0].minor.yy0);
117043     if( yygotominor.yy118.pExpr ) sqlite3GetInt32(&yymsp[0].minor.yy0.z[1], &yygotominor.yy118.pExpr->iTable);
117044   }
117045   spanSet(&yygotominor.yy118, &yymsp[0].minor.yy0, &yymsp[0].minor.yy0);
117046 }
117047         break;
117048       case 195: /* expr ::= VARIABLE */
117049 {
117050   spanExpr(&yygotominor.yy118, pParse, TK_VARIABLE, &yymsp[0].minor.yy0);
117051   sqlite3ExprAssignVarNumber(pParse, yygotominor.yy118.pExpr);
117052   spanSet(&yygotominor.yy118, &yymsp[0].minor.yy0, &yymsp[0].minor.yy0);
117053 }
117054         break;
117055       case 196: /* expr ::= expr COLLATE ids */
117056 {
117057   yygotominor.yy118.pExpr = sqlite3ExprAddCollateToken(pParse, yymsp[-2].minor.yy118.pExpr, &yymsp[0].minor.yy0);
117058   yygotominor.yy118.zStart = yymsp[-2].minor.yy118.zStart;
117059   yygotominor.yy118.zEnd = &yymsp[0].minor.yy0.z[yymsp[0].minor.yy0.n];
117060 }
117061         break;
117062       case 197: /* expr ::= CAST LP expr AS typetoken RP */
117063 {
117064   yygotominor.yy118.pExpr = sqlite3PExpr(pParse, TK_CAST, yymsp[-3].minor.yy118.pExpr, 0, &yymsp[-1].minor.yy0);
117065   spanSet(&yygotominor.yy118,&yymsp[-5].minor.yy0,&yymsp[0].minor.yy0);
117066 }
117067         break;
117068       case 198: /* expr ::= ID LP distinct exprlist RP */
117069 {
117070   if( yymsp[-1].minor.yy322 && yymsp[-1].minor.yy322->nExpr>pParse->db->aLimit[SQLITE_LIMIT_FUNCTION_ARG] ){
117071     sqlite3ErrorMsg(pParse, "too many arguments on function %T", &yymsp[-4].minor.yy0);
117072   }
117073   yygotominor.yy118.pExpr = sqlite3ExprFunction(pParse, yymsp[-1].minor.yy322, &yymsp[-4].minor.yy0);
117074   spanSet(&yygotominor.yy118,&yymsp[-4].minor.yy0,&yymsp[0].minor.yy0);
117075   if( yymsp[-2].minor.yy177 && yygotominor.yy118.pExpr ){
117076     yygotominor.yy118.pExpr->flags |= EP_Distinct;
117077   }
117078 }
117079         break;
117080       case 199: /* expr ::= ID LP STAR RP */
117081 {
117082   yygotominor.yy118.pExpr = sqlite3ExprFunction(pParse, 0, &yymsp[-3].minor.yy0);
117083   spanSet(&yygotominor.yy118,&yymsp[-3].minor.yy0,&yymsp[0].minor.yy0);
117084 }
117085         break;
117086       case 200: /* term ::= CTIME_KW */
117087 {
117088   yygotominor.yy118.pExpr = sqlite3ExprFunction(pParse, 0, &yymsp[0].minor.yy0);
117089   spanSet(&yygotominor.yy118, &yymsp[0].minor.yy0, &yymsp[0].minor.yy0);
117090 }
117091         break;
117092       case 201: /* expr ::= expr AND expr */
117093       case 202: /* expr ::= expr OR expr */ yytestcase(yyruleno==202);
117094       case 203: /* expr ::= expr LT|GT|GE|LE expr */ yytestcase(yyruleno==203);
117095       case 204: /* expr ::= expr EQ|NE expr */ yytestcase(yyruleno==204);
117096       case 205: /* expr ::= expr BITAND|BITOR|LSHIFT|RSHIFT expr */ yytestcase(yyruleno==205);
117097       case 206: /* expr ::= expr PLUS|MINUS expr */ yytestcase(yyruleno==206);
117098       case 207: /* expr ::= expr STAR|SLASH|REM expr */ yytestcase(yyruleno==207);
117099       case 208: /* expr ::= expr CONCAT expr */ yytestcase(yyruleno==208);
117100 {spanBinaryExpr(&yygotominor.yy118,pParse,yymsp[-1].major,&yymsp[-2].minor.yy118,&yymsp[0].minor.yy118);}
117101         break;
117102       case 209: /* likeop ::= LIKE_KW */
117103       case 211: /* likeop ::= MATCH */ yytestcase(yyruleno==211);
117104 {yygotominor.yy342.eOperator = yymsp[0].minor.yy0; yygotominor.yy342.bNot = 0;}
117105         break;
117106       case 210: /* likeop ::= NOT LIKE_KW */
117107       case 212: /* likeop ::= NOT MATCH */ yytestcase(yyruleno==212);
117108 {yygotominor.yy342.eOperator = yymsp[0].minor.yy0; yygotominor.yy342.bNot = 1;}
117109         break;
117110       case 213: /* expr ::= expr likeop expr */
117111 {
117112   ExprList *pList;
117113   pList = sqlite3ExprListAppend(pParse,0, yymsp[0].minor.yy118.pExpr);
117114   pList = sqlite3ExprListAppend(pParse,pList, yymsp[-2].minor.yy118.pExpr);
117115   yygotominor.yy118.pExpr = sqlite3ExprFunction(pParse, pList, &yymsp[-1].minor.yy342.eOperator);
117116   if( yymsp[-1].minor.yy342.bNot ) yygotominor.yy118.pExpr = sqlite3PExpr(pParse, TK_NOT, yygotominor.yy118.pExpr, 0, 0);
117117   yygotominor.yy118.zStart = yymsp[-2].minor.yy118.zStart;
117118   yygotominor.yy118.zEnd = yymsp[0].minor.yy118.zEnd;
117119   if( yygotominor.yy118.pExpr ) yygotominor.yy118.pExpr->flags |= EP_InfixFunc;
117120 }
117121         break;
117122       case 214: /* expr ::= expr likeop expr ESCAPE expr */
117123 {
117124   ExprList *pList;
117125   pList = sqlite3ExprListAppend(pParse,0, yymsp[-2].minor.yy118.pExpr);
117126   pList = sqlite3ExprListAppend(pParse,pList, yymsp[-4].minor.yy118.pExpr);
117127   pList = sqlite3ExprListAppend(pParse,pList, yymsp[0].minor.yy118.pExpr);
117128   yygotominor.yy118.pExpr = sqlite3ExprFunction(pParse, pList, &yymsp[-3].minor.yy342.eOperator);
117129   if( yymsp[-3].minor.yy342.bNot ) yygotominor.yy118.pExpr = sqlite3PExpr(pParse, TK_NOT, yygotominor.yy118.pExpr, 0, 0);
117130   yygotominor.yy118.zStart = yymsp[-4].minor.yy118.zStart;
117131   yygotominor.yy118.zEnd = yymsp[0].minor.yy118.zEnd;
117132   if( yygotominor.yy118.pExpr ) yygotominor.yy118.pExpr->flags |= EP_InfixFunc;
117133 }
117134         break;
117135       case 215: /* expr ::= expr ISNULL|NOTNULL */
117136 {spanUnaryPostfix(&yygotominor.yy118,pParse,yymsp[0].major,&yymsp[-1].minor.yy118,&yymsp[0].minor.yy0);}
117137         break;
117138       case 216: /* expr ::= expr NOT NULL */
117139 {spanUnaryPostfix(&yygotominor.yy118,pParse,TK_NOTNULL,&yymsp[-2].minor.yy118,&yymsp[0].minor.yy0);}
117140         break;
117141       case 217: /* expr ::= expr IS expr */
117142 {
117143   spanBinaryExpr(&yygotominor.yy118,pParse,TK_IS,&yymsp[-2].minor.yy118,&yymsp[0].minor.yy118);
117144   binaryToUnaryIfNull(pParse, yymsp[0].minor.yy118.pExpr, yygotominor.yy118.pExpr, TK_ISNULL);
117145 }
117146         break;
117147       case 218: /* expr ::= expr IS NOT expr */
117148 {
117149   spanBinaryExpr(&yygotominor.yy118,pParse,TK_ISNOT,&yymsp[-3].minor.yy118,&yymsp[0].minor.yy118);
117150   binaryToUnaryIfNull(pParse, yymsp[0].minor.yy118.pExpr, yygotominor.yy118.pExpr, TK_NOTNULL);
117151 }
117152         break;
117153       case 219: /* expr ::= NOT expr */
117154       case 220: /* expr ::= BITNOT expr */ yytestcase(yyruleno==220);
117155 {spanUnaryPrefix(&yygotominor.yy118,pParse,yymsp[-1].major,&yymsp[0].minor.yy118,&yymsp[-1].minor.yy0);}
117156         break;
117157       case 221: /* expr ::= MINUS expr */
117158 {spanUnaryPrefix(&yygotominor.yy118,pParse,TK_UMINUS,&yymsp[0].minor.yy118,&yymsp[-1].minor.yy0);}
117159         break;
117160       case 222: /* expr ::= PLUS expr */
117161 {spanUnaryPrefix(&yygotominor.yy118,pParse,TK_UPLUS,&yymsp[0].minor.yy118,&yymsp[-1].minor.yy0);}
117162         break;
117163       case 225: /* expr ::= expr between_op expr AND expr */
117164 {
117165   ExprList *pList = sqlite3ExprListAppend(pParse,0, yymsp[-2].minor.yy118.pExpr);
117166   pList = sqlite3ExprListAppend(pParse,pList, yymsp[0].minor.yy118.pExpr);
117167   yygotominor.yy118.pExpr = sqlite3PExpr(pParse, TK_BETWEEN, yymsp[-4].minor.yy118.pExpr, 0, 0);
117168   if( yygotominor.yy118.pExpr ){
117169     yygotominor.yy118.pExpr->x.pList = pList;
117170   }else{
117171     sqlite3ExprListDelete(pParse->db, pList);
117172   } 
117173   if( yymsp[-3].minor.yy4 ) yygotominor.yy118.pExpr = sqlite3PExpr(pParse, TK_NOT, yygotominor.yy118.pExpr, 0, 0);
117174   yygotominor.yy118.zStart = yymsp[-4].minor.yy118.zStart;
117175   yygotominor.yy118.zEnd = yymsp[0].minor.yy118.zEnd;
117176 }
117177         break;
117178       case 228: /* expr ::= expr in_op LP exprlist RP */
117179 {
117180     if( yymsp[-1].minor.yy322==0 ){
117181       /* Expressions of the form
117182       **
117183       **      expr1 IN ()
117184       **      expr1 NOT IN ()
117185       **
117186       ** simplify to constants 0 (false) and 1 (true), respectively,
117187       ** regardless of the value of expr1.
117188       */
117189       yygotominor.yy118.pExpr = sqlite3PExpr(pParse, TK_INTEGER, 0, 0, &sqlite3IntTokens[yymsp[-3].minor.yy4]);
117190       sqlite3ExprDelete(pParse->db, yymsp[-4].minor.yy118.pExpr);
117191     }else{
117192       yygotominor.yy118.pExpr = sqlite3PExpr(pParse, TK_IN, yymsp[-4].minor.yy118.pExpr, 0, 0);
117193       if( yygotominor.yy118.pExpr ){
117194         yygotominor.yy118.pExpr->x.pList = yymsp[-1].minor.yy322;
117195         sqlite3ExprSetHeight(pParse, yygotominor.yy118.pExpr);
117196       }else{
117197         sqlite3ExprListDelete(pParse->db, yymsp[-1].minor.yy322);
117198       }
117199       if( yymsp[-3].minor.yy4 ) yygotominor.yy118.pExpr = sqlite3PExpr(pParse, TK_NOT, yygotominor.yy118.pExpr, 0, 0);
117200     }
117201     yygotominor.yy118.zStart = yymsp[-4].minor.yy118.zStart;
117202     yygotominor.yy118.zEnd = &yymsp[0].minor.yy0.z[yymsp[0].minor.yy0.n];
117203   }
117204         break;
117205       case 229: /* expr ::= LP select RP */
117206 {
117207     yygotominor.yy118.pExpr = sqlite3PExpr(pParse, TK_SELECT, 0, 0, 0);
117208     if( yygotominor.yy118.pExpr ){
117209       yygotominor.yy118.pExpr->x.pSelect = yymsp[-1].minor.yy387;
117210       ExprSetProperty(yygotominor.yy118.pExpr, EP_xIsSelect);
117211       sqlite3ExprSetHeight(pParse, yygotominor.yy118.pExpr);
117212     }else{
117213       sqlite3SelectDelete(pParse->db, yymsp[-1].minor.yy387);
117214     }
117215     yygotominor.yy118.zStart = yymsp[-2].minor.yy0.z;
117216     yygotominor.yy118.zEnd = &yymsp[0].minor.yy0.z[yymsp[0].minor.yy0.n];
117217   }
117218         break;
117219       case 230: /* expr ::= expr in_op LP select RP */
117220 {
117221     yygotominor.yy118.pExpr = sqlite3PExpr(pParse, TK_IN, yymsp[-4].minor.yy118.pExpr, 0, 0);
117222     if( yygotominor.yy118.pExpr ){
117223       yygotominor.yy118.pExpr->x.pSelect = yymsp[-1].minor.yy387;
117224       ExprSetProperty(yygotominor.yy118.pExpr, EP_xIsSelect);
117225       sqlite3ExprSetHeight(pParse, yygotominor.yy118.pExpr);
117226     }else{
117227       sqlite3SelectDelete(pParse->db, yymsp[-1].minor.yy387);
117228     }
117229     if( yymsp[-3].minor.yy4 ) yygotominor.yy118.pExpr = sqlite3PExpr(pParse, TK_NOT, yygotominor.yy118.pExpr, 0, 0);
117230     yygotominor.yy118.zStart = yymsp[-4].minor.yy118.zStart;
117231     yygotominor.yy118.zEnd = &yymsp[0].minor.yy0.z[yymsp[0].minor.yy0.n];
117232   }
117233         break;
117234       case 231: /* expr ::= expr in_op nm dbnm */
117235 {
117236     SrcList *pSrc = sqlite3SrcListAppend(pParse->db, 0,&yymsp[-1].minor.yy0,&yymsp[0].minor.yy0);
117237     yygotominor.yy118.pExpr = sqlite3PExpr(pParse, TK_IN, yymsp[-3].minor.yy118.pExpr, 0, 0);
117238     if( yygotominor.yy118.pExpr ){
117239       yygotominor.yy118.pExpr->x.pSelect = sqlite3SelectNew(pParse, 0,pSrc,0,0,0,0,0,0,0);
117240       ExprSetProperty(yygotominor.yy118.pExpr, EP_xIsSelect);
117241       sqlite3ExprSetHeight(pParse, yygotominor.yy118.pExpr);
117242     }else{
117243       sqlite3SrcListDelete(pParse->db, pSrc);
117244     }
117245     if( yymsp[-2].minor.yy4 ) yygotominor.yy118.pExpr = sqlite3PExpr(pParse, TK_NOT, yygotominor.yy118.pExpr, 0, 0);
117246     yygotominor.yy118.zStart = yymsp[-3].minor.yy118.zStart;
117247     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];
117248   }
117249         break;
117250       case 232: /* expr ::= EXISTS LP select RP */
117251 {
117252     Expr *p = yygotominor.yy118.pExpr = sqlite3PExpr(pParse, TK_EXISTS, 0, 0, 0);
117253     if( p ){
117254       p->x.pSelect = yymsp[-1].minor.yy387;
117255       ExprSetProperty(p, EP_xIsSelect);
117256       sqlite3ExprSetHeight(pParse, p);
117257     }else{
117258       sqlite3SelectDelete(pParse->db, yymsp[-1].minor.yy387);
117259     }
117260     yygotominor.yy118.zStart = yymsp[-3].minor.yy0.z;
117261     yygotominor.yy118.zEnd = &yymsp[0].minor.yy0.z[yymsp[0].minor.yy0.n];
117262   }
117263         break;
117264       case 233: /* expr ::= CASE case_operand case_exprlist case_else END */
117265 {
117266   yygotominor.yy118.pExpr = sqlite3PExpr(pParse, TK_CASE, yymsp[-3].minor.yy314, 0, 0);
117267   if( yygotominor.yy118.pExpr ){
117268     yygotominor.yy118.pExpr->x.pList = yymsp[-1].minor.yy314 ? sqlite3ExprListAppend(pParse,yymsp[-2].minor.yy322,yymsp[-1].minor.yy314) : yymsp[-2].minor.yy322;
117269     sqlite3ExprSetHeight(pParse, yygotominor.yy118.pExpr);
117270   }else{
117271     sqlite3ExprListDelete(pParse->db, yymsp[-2].minor.yy322);
117272     sqlite3ExprDelete(pParse->db, yymsp[-1].minor.yy314);
117273   }
117274   yygotominor.yy118.zStart = yymsp[-4].minor.yy0.z;
117275   yygotominor.yy118.zEnd = &yymsp[0].minor.yy0.z[yymsp[0].minor.yy0.n];
117276 }
117277         break;
117278       case 234: /* case_exprlist ::= case_exprlist WHEN expr THEN expr */
117279 {
117280   yygotominor.yy322 = sqlite3ExprListAppend(pParse,yymsp[-4].minor.yy322, yymsp[-2].minor.yy118.pExpr);
117281   yygotominor.yy322 = sqlite3ExprListAppend(pParse,yygotominor.yy322, yymsp[0].minor.yy118.pExpr);
117282 }
117283         break;
117284       case 235: /* case_exprlist ::= WHEN expr THEN expr */
117285 {
117286   yygotominor.yy322 = sqlite3ExprListAppend(pParse,0, yymsp[-2].minor.yy118.pExpr);
117287   yygotominor.yy322 = sqlite3ExprListAppend(pParse,yygotominor.yy322, yymsp[0].minor.yy118.pExpr);
117288 }
117289         break;
117290       case 242: /* nexprlist ::= nexprlist COMMA expr */
117291 {yygotominor.yy322 = sqlite3ExprListAppend(pParse,yymsp[-2].minor.yy322,yymsp[0].minor.yy118.pExpr);}
117292         break;
117293       case 243: /* nexprlist ::= expr */
117294 {yygotominor.yy322 = sqlite3ExprListAppend(pParse,0,yymsp[0].minor.yy118.pExpr);}
117295         break;
117296       case 244: /* cmd ::= createkw uniqueflag INDEX ifnotexists nm dbnm ON nm LP idxlist RP where_opt */
117297 {
117298   sqlite3CreateIndex(pParse, &yymsp[-7].minor.yy0, &yymsp[-6].minor.yy0, 
117299                      sqlite3SrcListAppend(pParse->db,0,&yymsp[-4].minor.yy0,0), yymsp[-2].minor.yy322, yymsp[-10].minor.yy4,
117300                       &yymsp[-11].minor.yy0, yymsp[0].minor.yy314, SQLITE_SO_ASC, yymsp[-8].minor.yy4);
117301 }
117302         break;
117303       case 245: /* uniqueflag ::= UNIQUE */
117304       case 298: /* raisetype ::= ABORT */ yytestcase(yyruleno==298);
117305 {yygotominor.yy4 = OE_Abort;}
117306         break;
117307       case 246: /* uniqueflag ::= */
117308 {yygotominor.yy4 = OE_None;}
117309         break;
117310       case 249: /* idxlist ::= idxlist COMMA nm collate sortorder */
117311 {
117312   Expr *p = sqlite3ExprAddCollateToken(pParse, 0, &yymsp[-1].minor.yy0);
117313   yygotominor.yy322 = sqlite3ExprListAppend(pParse,yymsp[-4].minor.yy322, p);
117314   sqlite3ExprListSetName(pParse,yygotominor.yy322,&yymsp[-2].minor.yy0,1);
117315   sqlite3ExprListCheckLength(pParse, yygotominor.yy322, "index");
117316   if( yygotominor.yy322 ) yygotominor.yy322->a[yygotominor.yy322->nExpr-1].sortOrder = (u8)yymsp[0].minor.yy4;
117317 }
117318         break;
117319       case 250: /* idxlist ::= nm collate sortorder */
117320 {
117321   Expr *p = sqlite3ExprAddCollateToken(pParse, 0, &yymsp[-1].minor.yy0);
117322   yygotominor.yy322 = sqlite3ExprListAppend(pParse,0, p);
117323   sqlite3ExprListSetName(pParse, yygotominor.yy322, &yymsp[-2].minor.yy0, 1);
117324   sqlite3ExprListCheckLength(pParse, yygotominor.yy322, "index");
117325   if( yygotominor.yy322 ) yygotominor.yy322->a[yygotominor.yy322->nExpr-1].sortOrder = (u8)yymsp[0].minor.yy4;
117326 }
117327         break;
117328       case 251: /* collate ::= */
117329 {yygotominor.yy0.z = 0; yygotominor.yy0.n = 0;}
117330         break;
117331       case 253: /* cmd ::= DROP INDEX ifexists fullname */
117332 {sqlite3DropIndex(pParse, yymsp[0].minor.yy259, yymsp[-1].minor.yy4);}
117333         break;
117334       case 254: /* cmd ::= VACUUM */
117335       case 255: /* cmd ::= VACUUM nm */ yytestcase(yyruleno==255);
117336 {sqlite3Vacuum(pParse);}
117337         break;
117338       case 256: /* cmd ::= PRAGMA nm dbnm */
117339 {sqlite3Pragma(pParse,&yymsp[-1].minor.yy0,&yymsp[0].minor.yy0,0,0);}
117340         break;
117341       case 257: /* cmd ::= PRAGMA nm dbnm EQ nmnum */
117342 {sqlite3Pragma(pParse,&yymsp[-3].minor.yy0,&yymsp[-2].minor.yy0,&yymsp[0].minor.yy0,0);}
117343         break;
117344       case 258: /* cmd ::= PRAGMA nm dbnm LP nmnum RP */
117345 {sqlite3Pragma(pParse,&yymsp[-4].minor.yy0,&yymsp[-3].minor.yy0,&yymsp[-1].minor.yy0,0);}
117346         break;
117347       case 259: /* cmd ::= PRAGMA nm dbnm EQ minus_num */
117348 {sqlite3Pragma(pParse,&yymsp[-3].minor.yy0,&yymsp[-2].minor.yy0,&yymsp[0].minor.yy0,1);}
117349         break;
117350       case 260: /* cmd ::= PRAGMA nm dbnm LP minus_num RP */
117351 {sqlite3Pragma(pParse,&yymsp[-4].minor.yy0,&yymsp[-3].minor.yy0,&yymsp[-1].minor.yy0,1);}
117352         break;
117353       case 270: /* cmd ::= createkw trigger_decl BEGIN trigger_cmd_list END */
117354 {
117355   Token all;
117356   all.z = yymsp[-3].minor.yy0.z;
117357   all.n = (int)(yymsp[0].minor.yy0.z - yymsp[-3].minor.yy0.z) + yymsp[0].minor.yy0.n;
117358   sqlite3FinishTrigger(pParse, yymsp[-1].minor.yy203, &all);
117359 }
117360         break;
117361       case 271: /* trigger_decl ::= temp TRIGGER ifnotexists nm dbnm trigger_time trigger_event ON fullname foreach_clause when_clause */
117362 {
117363   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);
117364   yygotominor.yy0 = (yymsp[-6].minor.yy0.n==0?yymsp[-7].minor.yy0:yymsp[-6].minor.yy0);
117365 }
117366         break;
117367       case 272: /* trigger_time ::= BEFORE */
117368       case 275: /* trigger_time ::= */ yytestcase(yyruleno==275);
117369 { yygotominor.yy4 = TK_BEFORE; }
117370         break;
117371       case 273: /* trigger_time ::= AFTER */
117372 { yygotominor.yy4 = TK_AFTER;  }
117373         break;
117374       case 274: /* trigger_time ::= INSTEAD OF */
117375 { yygotominor.yy4 = TK_INSTEAD;}
117376         break;
117377       case 276: /* trigger_event ::= DELETE|INSERT */
117378       case 277: /* trigger_event ::= UPDATE */ yytestcase(yyruleno==277);
117379 {yygotominor.yy90.a = yymsp[0].major; yygotominor.yy90.b = 0;}
117380         break;
117381       case 278: /* trigger_event ::= UPDATE OF idlist */
117382 {yygotominor.yy90.a = TK_UPDATE; yygotominor.yy90.b = yymsp[0].minor.yy384;}
117383         break;
117384       case 281: /* when_clause ::= */
117385       case 303: /* key_opt ::= */ yytestcase(yyruleno==303);
117386 { yygotominor.yy314 = 0; }
117387         break;
117388       case 282: /* when_clause ::= WHEN expr */
117389       case 304: /* key_opt ::= KEY expr */ yytestcase(yyruleno==304);
117390 { yygotominor.yy314 = yymsp[0].minor.yy118.pExpr; }
117391         break;
117392       case 283: /* trigger_cmd_list ::= trigger_cmd_list trigger_cmd SEMI */
117393 {
117394   assert( yymsp[-2].minor.yy203!=0 );
117395   yymsp[-2].minor.yy203->pLast->pNext = yymsp[-1].minor.yy203;
117396   yymsp[-2].minor.yy203->pLast = yymsp[-1].minor.yy203;
117397   yygotominor.yy203 = yymsp[-2].minor.yy203;
117398 }
117399         break;
117400       case 284: /* trigger_cmd_list ::= trigger_cmd SEMI */
117401 { 
117402   assert( yymsp[-1].minor.yy203!=0 );
117403   yymsp[-1].minor.yy203->pLast = yymsp[-1].minor.yy203;
117404   yygotominor.yy203 = yymsp[-1].minor.yy203;
117405 }
117406         break;
117407       case 286: /* trnm ::= nm DOT nm */
117408 {
117409   yygotominor.yy0 = yymsp[0].minor.yy0;
117410   sqlite3ErrorMsg(pParse, 
117411         "qualified table names are not allowed on INSERT, UPDATE, and DELETE "
117412         "statements within triggers");
117413 }
117414         break;
117415       case 288: /* tridxby ::= INDEXED BY nm */
117416 {
117417   sqlite3ErrorMsg(pParse,
117418         "the INDEXED BY clause is not allowed on UPDATE or DELETE statements "
117419         "within triggers");
117420 }
117421         break;
117422       case 289: /* tridxby ::= NOT INDEXED */
117423 {
117424   sqlite3ErrorMsg(pParse,
117425         "the NOT INDEXED clause is not allowed on UPDATE or DELETE statements "
117426         "within triggers");
117427 }
117428         break;
117429       case 290: /* trigger_cmd ::= UPDATE orconf trnm tridxby SET setlist where_opt */
117430 { yygotominor.yy203 = sqlite3TriggerUpdateStep(pParse->db, &yymsp[-4].minor.yy0, yymsp[-1].minor.yy322, yymsp[0].minor.yy314, yymsp[-5].minor.yy210); }
117431         break;
117432       case 291: /* trigger_cmd ::= insert_cmd INTO trnm inscollist_opt valuelist */
117433 {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);}
117434         break;
117435       case 292: /* trigger_cmd ::= insert_cmd INTO trnm inscollist_opt select */
117436 {yygotominor.yy203 = sqlite3TriggerInsertStep(pParse->db, &yymsp[-2].minor.yy0, yymsp[-1].minor.yy384, 0, yymsp[0].minor.yy387, yymsp[-4].minor.yy210);}
117437         break;
117438       case 293: /* trigger_cmd ::= DELETE FROM trnm tridxby where_opt */
117439 {yygotominor.yy203 = sqlite3TriggerDeleteStep(pParse->db, &yymsp[-2].minor.yy0, yymsp[0].minor.yy314);}
117440         break;
117441       case 294: /* trigger_cmd ::= select */
117442 {yygotominor.yy203 = sqlite3TriggerSelectStep(pParse->db, yymsp[0].minor.yy387); }
117443         break;
117444       case 295: /* expr ::= RAISE LP IGNORE RP */
117445 {
117446   yygotominor.yy118.pExpr = sqlite3PExpr(pParse, TK_RAISE, 0, 0, 0); 
117447   if( yygotominor.yy118.pExpr ){
117448     yygotominor.yy118.pExpr->affinity = OE_Ignore;
117449   }
117450   yygotominor.yy118.zStart = yymsp[-3].minor.yy0.z;
117451   yygotominor.yy118.zEnd = &yymsp[0].minor.yy0.z[yymsp[0].minor.yy0.n];
117452 }
117453         break;
117454       case 296: /* expr ::= RAISE LP raisetype COMMA nm RP */
117455 {
117456   yygotominor.yy118.pExpr = sqlite3PExpr(pParse, TK_RAISE, 0, 0, &yymsp[-1].minor.yy0); 
117457   if( yygotominor.yy118.pExpr ) {
117458     yygotominor.yy118.pExpr->affinity = (char)yymsp[-3].minor.yy4;
117459   }
117460   yygotominor.yy118.zStart = yymsp[-5].minor.yy0.z;
117461   yygotominor.yy118.zEnd = &yymsp[0].minor.yy0.z[yymsp[0].minor.yy0.n];
117462 }
117463         break;
117464       case 297: /* raisetype ::= ROLLBACK */
117465 {yygotominor.yy4 = OE_Rollback;}
117466         break;
117467       case 299: /* raisetype ::= FAIL */
117468 {yygotominor.yy4 = OE_Fail;}
117469         break;
117470       case 300: /* cmd ::= DROP TRIGGER ifexists fullname */
117471 {
117472   sqlite3DropTrigger(pParse,yymsp[0].minor.yy259,yymsp[-1].minor.yy4);
117473 }
117474         break;
117475       case 301: /* cmd ::= ATTACH database_kw_opt expr AS expr key_opt */
117476 {
117477   sqlite3Attach(pParse, yymsp[-3].minor.yy118.pExpr, yymsp[-1].minor.yy118.pExpr, yymsp[0].minor.yy314);
117478 }
117479         break;
117480       case 302: /* cmd ::= DETACH database_kw_opt expr */
117481 {
117482   sqlite3Detach(pParse, yymsp[0].minor.yy118.pExpr);
117483 }
117484         break;
117485       case 307: /* cmd ::= REINDEX */
117486 {sqlite3Reindex(pParse, 0, 0);}
117487         break;
117488       case 308: /* cmd ::= REINDEX nm dbnm */
117489 {sqlite3Reindex(pParse, &yymsp[-1].minor.yy0, &yymsp[0].minor.yy0);}
117490         break;
117491       case 309: /* cmd ::= ANALYZE */
117492 {sqlite3Analyze(pParse, 0, 0);}
117493         break;
117494       case 310: /* cmd ::= ANALYZE nm dbnm */
117495 {sqlite3Analyze(pParse, &yymsp[-1].minor.yy0, &yymsp[0].minor.yy0);}
117496         break;
117497       case 311: /* cmd ::= ALTER TABLE fullname RENAME TO nm */
117498 {
117499   sqlite3AlterRenameTable(pParse,yymsp[-3].minor.yy259,&yymsp[0].minor.yy0);
117500 }
117501         break;
117502       case 312: /* cmd ::= ALTER TABLE add_column_fullname ADD kwcolumn_opt column */
117503 {
117504   sqlite3AlterFinishAddColumn(pParse, &yymsp[0].minor.yy0);
117505 }
117506         break;
117507       case 313: /* add_column_fullname ::= fullname */
117508 {
117509   pParse->db->lookaside.bEnabled = 0;
117510   sqlite3AlterBeginAddColumn(pParse, yymsp[0].minor.yy259);
117511 }
117512         break;
117513       case 316: /* cmd ::= create_vtab */
117514 {sqlite3VtabFinishParse(pParse,0);}
117515         break;
117516       case 317: /* cmd ::= create_vtab LP vtabarglist RP */
117517 {sqlite3VtabFinishParse(pParse,&yymsp[0].minor.yy0);}
117518         break;
117519       case 318: /* create_vtab ::= createkw VIRTUAL TABLE ifnotexists nm dbnm USING nm */
117520 {
117521     sqlite3VtabBeginParse(pParse, &yymsp[-3].minor.yy0, &yymsp[-2].minor.yy0, &yymsp[0].minor.yy0, yymsp[-4].minor.yy4);
117522 }
117523         break;
117524       case 321: /* vtabarg ::= */
117525 {sqlite3VtabArgInit(pParse);}
117526         break;
117527       case 323: /* vtabargtoken ::= ANY */
117528       case 324: /* vtabargtoken ::= lp anylist RP */ yytestcase(yyruleno==324);
117529       case 325: /* lp ::= LP */ yytestcase(yyruleno==325);
117530 {sqlite3VtabArgExtend(pParse,&yymsp[0].minor.yy0);}
117531         break;
117532       default:
117533       /* (0) input ::= cmdlist */ yytestcase(yyruleno==0);
117534       /* (1) cmdlist ::= cmdlist ecmd */ yytestcase(yyruleno==1);
117535       /* (2) cmdlist ::= ecmd */ yytestcase(yyruleno==2);
117536       /* (3) ecmd ::= SEMI */ yytestcase(yyruleno==3);
117537       /* (4) ecmd ::= explain cmdx SEMI */ yytestcase(yyruleno==4);
117538       /* (10) trans_opt ::= */ yytestcase(yyruleno==10);
117539       /* (11) trans_opt ::= TRANSACTION */ yytestcase(yyruleno==11);
117540       /* (12) trans_opt ::= TRANSACTION nm */ yytestcase(yyruleno==12);
117541       /* (20) savepoint_opt ::= SAVEPOINT */ yytestcase(yyruleno==20);
117542       /* (21) savepoint_opt ::= */ yytestcase(yyruleno==21);
117543       /* (25) cmd ::= create_table create_table_args */ yytestcase(yyruleno==25);
117544       /* (36) columnlist ::= columnlist COMMA column */ yytestcase(yyruleno==36);
117545       /* (37) columnlist ::= column */ yytestcase(yyruleno==37);
117546       /* (46) type ::= */ yytestcase(yyruleno==46);
117547       /* (53) signed ::= plus_num */ yytestcase(yyruleno==53);
117548       /* (54) signed ::= minus_num */ yytestcase(yyruleno==54);
117549       /* (55) carglist ::= carglist ccons */ yytestcase(yyruleno==55);
117550       /* (56) carglist ::= */ yytestcase(yyruleno==56);
117551       /* (63) ccons ::= NULL onconf */ yytestcase(yyruleno==63);
117552       /* (91) conslist ::= conslist tconscomma tcons */ yytestcase(yyruleno==91);
117553       /* (92) conslist ::= tcons */ yytestcase(yyruleno==92);
117554       /* (94) tconscomma ::= */ yytestcase(yyruleno==94);
117555       /* (279) foreach_clause ::= */ yytestcase(yyruleno==279);
117556       /* (280) foreach_clause ::= FOR EACH ROW */ yytestcase(yyruleno==280);
117557       /* (287) tridxby ::= */ yytestcase(yyruleno==287);
117558       /* (305) database_kw_opt ::= DATABASE */ yytestcase(yyruleno==305);
117559       /* (306) database_kw_opt ::= */ yytestcase(yyruleno==306);
117560       /* (314) kwcolumn_opt ::= */ yytestcase(yyruleno==314);
117561       /* (315) kwcolumn_opt ::= COLUMNKW */ yytestcase(yyruleno==315);
117562       /* (319) vtabarglist ::= vtabarg */ yytestcase(yyruleno==319);
117563       /* (320) vtabarglist ::= vtabarglist COMMA vtabarg */ yytestcase(yyruleno==320);
117564       /* (322) vtabarg ::= vtabarg vtabargtoken */ yytestcase(yyruleno==322);
117565       /* (326) anylist ::= */ yytestcase(yyruleno==326);
117566       /* (327) anylist ::= anylist LP anylist RP */ yytestcase(yyruleno==327);
117567       /* (328) anylist ::= anylist ANY */ yytestcase(yyruleno==328);
117568         break;
117569   };
117570   assert( yyruleno>=0 && yyruleno<sizeof(yyRuleInfo)/sizeof(yyRuleInfo[0]) );
117571   yygoto = yyRuleInfo[yyruleno].lhs;
117572   yysize = yyRuleInfo[yyruleno].nrhs;
117573   yypParser->yyidx -= yysize;
117574   yyact = yy_find_reduce_action(yymsp[-yysize].stateno,(YYCODETYPE)yygoto);
117575   if( yyact < YYNSTATE ){
117576 #ifdef NDEBUG
117577     /* If we are not debugging and the reduce action popped at least
117578     ** one element off the stack, then we can push the new element back
117579     ** onto the stack here, and skip the stack overflow test in yy_shift().
117580     ** That gives a significant speed improvement. */
117581     if( yysize ){
117582       yypParser->yyidx++;
117583       yymsp -= yysize-1;
117584       yymsp->stateno = (YYACTIONTYPE)yyact;
117585       yymsp->major = (YYCODETYPE)yygoto;
117586       yymsp->minor = yygotominor;
117587     }else
117588 #endif
117589     {
117590       yy_shift(yypParser,yyact,yygoto,&yygotominor);
117591     }
117592   }else{
117593     assert( yyact == YYNSTATE + YYNRULE + 1 );
117594     yy_accept(yypParser);
117595   }
117596 }
117597 
117598 /*
117599 ** The following code executes when the parse fails
117600 */
117601 #ifndef YYNOERRORRECOVERY
117602 static void yy_parse_failed(
117603   yyParser *yypParser           /* The parser */
117604 ){
117605   sqlite3ParserARG_FETCH;
117606 #ifndef NDEBUG
117607   if( yyTraceFILE ){
117608     fprintf(yyTraceFILE,"%sFail!\n",yyTracePrompt);
117609   }
117610 #endif
117611   while( yypParser->yyidx>=0 ) yy_pop_parser_stack(yypParser);
117612   /* Here code is inserted which will be executed whenever the
117613   ** parser fails */
117614   sqlite3ParserARG_STORE; /* Suppress warning about unused %extra_argument variable */
117615 }
117616 #endif /* YYNOERRORRECOVERY */
117617 
117618 /*
117619 ** The following code executes when a syntax error first occurs.
117620 */
117621 static void yy_syntax_error(
117622   yyParser *yypParser,           /* The parser */
117623   int yymajor,                   /* The major type of the error token */
117624   YYMINORTYPE yyminor            /* The minor type of the error token */
117625 ){
117626   sqlite3ParserARG_FETCH;
117627 #define TOKEN (yyminor.yy0)
117628 
117629   UNUSED_PARAMETER(yymajor);  /* Silence some compiler warnings */
117630   assert( TOKEN.z[0] );  /* The tokenizer always gives us a token */
117631   sqlite3ErrorMsg(pParse, "near \"%T\": syntax error", &TOKEN);
117632   sqlite3ParserARG_STORE; /* Suppress warning about unused %extra_argument variable */
117633 }
117634 
117635 /*
117636 ** The following is executed when the parser accepts
117637 */
117638 static void yy_accept(
117639   yyParser *yypParser           /* The parser */
117640 ){
117641   sqlite3ParserARG_FETCH;
117642 #ifndef NDEBUG
117643   if( yyTraceFILE ){
117644     fprintf(yyTraceFILE,"%sAccept!\n",yyTracePrompt);
117645   }
117646 #endif
117647   while( yypParser->yyidx>=0 ) yy_pop_parser_stack(yypParser);
117648   /* Here code is inserted which will be executed whenever the
117649   ** parser accepts */
117650   sqlite3ParserARG_STORE; /* Suppress warning about unused %extra_argument variable */
117651 }
117652 
117653 /* The main parser program.
117654 ** The first argument is a pointer to a structure obtained from
117655 ** "sqlite3ParserAlloc" which describes the current state of the parser.
117656 ** The second argument is the major token number.  The third is
117657 ** the minor token.  The fourth optional argument is whatever the
117658 ** user wants (and specified in the grammar) and is available for
117659 ** use by the action routines.
117660 **
117661 ** Inputs:
117662 ** <ul>
117663 ** <li> A pointer to the parser (an opaque structure.)
117664 ** <li> The major token number.
117665 ** <li> The minor token number.
117666 ** <li> An option argument of a grammar-specified type.
117667 ** </ul>
117668 **
117669 ** Outputs:
117670 ** None.
117671 */
117672 SQLITE_PRIVATE void sqlite3Parser(
117673   void *yyp,                   /* The parser */
117674   int yymajor,                 /* The major token code number */
117675   sqlite3ParserTOKENTYPE yyminor       /* The value for the token */
117676   sqlite3ParserARG_PDECL               /* Optional %extra_argument parameter */
117677 ){
117678   YYMINORTYPE yyminorunion;
117679   int yyact;            /* The parser action. */
117680 #if !defined(YYERRORSYMBOL) && !defined(YYNOERRORRECOVERY)
117681   int yyendofinput;     /* True if we are at the end of input */
117682 #endif
117683 #ifdef YYERRORSYMBOL
117684   int yyerrorhit = 0;   /* True if yymajor has invoked an error */
117685 #endif
117686   yyParser *yypParser;  /* The parser */
117687 
117688   /* (re)initialize the parser, if necessary */
117689   yypParser = (yyParser*)yyp;
117690   if( yypParser->yyidx<0 ){
117691 #if YYSTACKDEPTH<=0
117692     if( yypParser->yystksz <=0 ){
117693       /*memset(&yyminorunion, 0, sizeof(yyminorunion));*/
117694       yyminorunion = yyzerominor;
117695       yyStackOverflow(yypParser, &yyminorunion);
117696       return;
117697     }
117698 #endif
117699     yypParser->yyidx = 0;
117700     yypParser->yyerrcnt = -1;
117701     yypParser->yystack[0].stateno = 0;
117702     yypParser->yystack[0].major = 0;
117703   }
117704   yyminorunion.yy0 = yyminor;
117705 #if !defined(YYERRORSYMBOL) && !defined(YYNOERRORRECOVERY)
117706   yyendofinput = (yymajor==0);
117707 #endif
117708   sqlite3ParserARG_STORE;
117709 
117710 #ifndef NDEBUG
117711   if( yyTraceFILE ){
117712     fprintf(yyTraceFILE,"%sInput %s\n",yyTracePrompt,yyTokenName[yymajor]);
117713   }
117714 #endif
117715 
117716   do{
117717     yyact = yy_find_shift_action(yypParser,(YYCODETYPE)yymajor);
117718     if( yyact<YYNSTATE ){
117719       yy_shift(yypParser,yyact,yymajor,&yyminorunion);
117720       yypParser->yyerrcnt--;
117721       yymajor = YYNOCODE;
117722     }else if( yyact < YYNSTATE + YYNRULE ){
117723       yy_reduce(yypParser,yyact-YYNSTATE);
117724     }else{
117725       assert( yyact == YY_ERROR_ACTION );
117726 #ifdef YYERRORSYMBOL
117727       int yymx;
117728 #endif
117729 #ifndef NDEBUG
117730       if( yyTraceFILE ){
117731         fprintf(yyTraceFILE,"%sSyntax Error!\n",yyTracePrompt);
117732       }
117733 #endif
117734 #ifdef YYERRORSYMBOL
117735       /* A syntax error has occurred.
117736       ** The response to an error depends upon whether or not the
117737       ** grammar defines an error token "ERROR".  
117738       **
117739       ** This is what we do if the grammar does define ERROR:
117740       **
117741       **  * Call the %syntax_error function.
117742       **
117743       **  * Begin popping the stack until we enter a state where
117744       **    it is legal to shift the error symbol, then shift
117745       **    the error symbol.
117746       **
117747       **  * Set the error count to three.
117748       **
117749       **  * Begin accepting and shifting new tokens.  No new error
117750       **    processing will occur until three tokens have been
117751       **    shifted successfully.
117752       **
117753       */
117754       if( yypParser->yyerrcnt<0 ){
117755         yy_syntax_error(yypParser,yymajor,yyminorunion);
117756       }
117757       yymx = yypParser->yystack[yypParser->yyidx].major;
117758       if( yymx==YYERRORSYMBOL || yyerrorhit ){
117759 #ifndef NDEBUG
117760         if( yyTraceFILE ){
117761           fprintf(yyTraceFILE,"%sDiscard input token %s\n",
117762              yyTracePrompt,yyTokenName[yymajor]);
117763         }
117764 #endif
117765         yy_destructor(yypParser, (YYCODETYPE)yymajor,&yyminorunion);
117766         yymajor = YYNOCODE;
117767       }else{
117768          while(
117769           yypParser->yyidx >= 0 &&
117770           yymx != YYERRORSYMBOL &&
117771           (yyact = yy_find_reduce_action(
117772                         yypParser->yystack[yypParser->yyidx].stateno,
117773                         YYERRORSYMBOL)) >= YYNSTATE
117774         ){
117775           yy_pop_parser_stack(yypParser);
117776         }
117777         if( yypParser->yyidx < 0 || yymajor==0 ){
117778           yy_destructor(yypParser,(YYCODETYPE)yymajor,&yyminorunion);
117779           yy_parse_failed(yypParser);
117780           yymajor = YYNOCODE;
117781         }else if( yymx!=YYERRORSYMBOL ){
117782           YYMINORTYPE u2;
117783           u2.YYERRSYMDT = 0;
117784           yy_shift(yypParser,yyact,YYERRORSYMBOL,&u2);
117785         }
117786       }
117787       yypParser->yyerrcnt = 3;
117788       yyerrorhit = 1;
117789 #elif defined(YYNOERRORRECOVERY)
117790       /* If the YYNOERRORRECOVERY macro is defined, then do not attempt to
117791       ** do any kind of error recovery.  Instead, simply invoke the syntax
117792       ** error routine and continue going as if nothing had happened.
117793       **
117794       ** Applications can set this macro (for example inside %include) if
117795       ** they intend to abandon the parse upon the first syntax error seen.
117796       */
117797       yy_syntax_error(yypParser,yymajor,yyminorunion);
117798       yy_destructor(yypParser,(YYCODETYPE)yymajor,&yyminorunion);
117799       yymajor = YYNOCODE;
117800       
117801 #else  /* YYERRORSYMBOL is not defined */
117802       /* This is what we do if the grammar does not define ERROR:
117803       **
117804       **  * Report an error message, and throw away the input token.
117805       **
117806       **  * If the input token is $, then fail the parse.
117807       **
117808       ** As before, subsequent error messages are suppressed until
117809       ** three input tokens have been successfully shifted.
117810       */
117811       if( yypParser->yyerrcnt<=0 ){
117812         yy_syntax_error(yypParser,yymajor,yyminorunion);
117813       }
117814       yypParser->yyerrcnt = 3;
117815       yy_destructor(yypParser,(YYCODETYPE)yymajor,&yyminorunion);
117816       if( yyendofinput ){
117817         yy_parse_failed(yypParser);
117818       }
117819       yymajor = YYNOCODE;
117820 #endif
117821     }
117822   }while( yymajor!=YYNOCODE && yypParser->yyidx>=0 );
117823   return;
117824 }
117825 
117826 /************** End of parse.c ***********************************************/
117827 /************** Begin file tokenize.c ****************************************/
117828 /*
117829 ** 2001 September 15
117830 **
117831 ** The author disclaims copyright to this source code.  In place of
117832 ** a legal notice, here is a blessing:
117833 **
117834 **    May you do good and not evil.
117835 **    May you find forgiveness for yourself and forgive others.
117836 **    May you share freely, never taking more than you give.
117837 **
117838 *************************************************************************
117839 ** An tokenizer for SQL
117840 **
117841 ** This file contains C code that splits an SQL input string up into
117842 ** individual tokens and sends those tokens one-by-one over to the
117843 ** parser for analysis.
117844 */
117845 /* #include <stdlib.h> */
117846 
117847 /*
117848 ** The charMap() macro maps alphabetic characters into their
117849 ** lower-case ASCII equivalent.  On ASCII machines, this is just
117850 ** an upper-to-lower case map.  On EBCDIC machines we also need
117851 ** to adjust the encoding.  Only alphabetic characters and underscores
117852 ** need to be translated.
117853 */
117854 #ifdef SQLITE_ASCII
117855 # define charMap(X) sqlite3UpperToLower[(unsigned char)X]
117856 #endif
117857 #ifdef SQLITE_EBCDIC
117858 # define charMap(X) ebcdicToAscii[(unsigned char)X]
117859 const unsigned char ebcdicToAscii[] = {
117860 /* 0   1   2   3   4   5   6   7   8   9   A   B   C   D   E   F */
117861    0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  /* 0x */
117862    0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  /* 1x */
117863    0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  /* 2x */
117864    0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  /* 3x */
117865    0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  /* 4x */
117866    0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  /* 5x */
117867    0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0, 95,  0,  0,  /* 6x */
117868    0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  /* 7x */
117869    0, 97, 98, 99,100,101,102,103,104,105,  0,  0,  0,  0,  0,  0,  /* 8x */
117870    0,106,107,108,109,110,111,112,113,114,  0,  0,  0,  0,  0,  0,  /* 9x */
117871    0,  0,115,116,117,118,119,120,121,122,  0,  0,  0,  0,  0,  0,  /* Ax */
117872    0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  /* Bx */
117873    0, 97, 98, 99,100,101,102,103,104,105,  0,  0,  0,  0,  0,  0,  /* Cx */
117874    0,106,107,108,109,110,111,112,113,114,  0,  0,  0,  0,  0,  0,  /* Dx */
117875    0,  0,115,116,117,118,119,120,121,122,  0,  0,  0,  0,  0,  0,  /* Ex */
117876    0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  /* Fx */
117877 };
117878 #endif
117879 
117880 /*
117881 ** The sqlite3KeywordCode function looks up an identifier to determine if
117882 ** it is a keyword.  If it is a keyword, the token code of that keyword is 
117883 ** returned.  If the input is not a keyword, TK_ID is returned.
117884 **
117885 ** The implementation of this routine was generated by a program,
117886 ** mkkeywordhash.h, located in the tool subdirectory of the distribution.
117887 ** The output of the mkkeywordhash.c program is written into a file
117888 ** named keywordhash.h and then included into this source file by
117889 ** the #include below.
117890 */
117891 /************** Include keywordhash.h in the middle of tokenize.c ************/
117892 /************** Begin file keywordhash.h *************************************/
117893 /***** This file contains automatically generated code ******
117894 **
117895 ** The code in this file has been automatically generated by
117896 **
117897 **   sqlite/tool/mkkeywordhash.c
117898 **
117899 ** The code in this file implements a function that determines whether
117900 ** or not a given identifier is really an SQL keyword.  The same thing
117901 ** might be implemented more directly using a hand-written hash table.
117902 ** But by using this automatically generated code, the size of the code
117903 ** is substantially reduced.  This is important for embedded applications
117904 ** on platforms with limited memory.
117905 */
117906 /* Hash score: 177 */
117907 static int keywordCode(const char *z, int n){
117908   /* zText[] encodes 819 bytes of keywords in 545 bytes */
117909   /*   REINDEXEDESCAPEACHECKEYBEFOREIGNOREGEXPLAINSTEADDATABASELECT       */
117910   /*   ABLEFTHENDEFERRABLELSEXCEPTRANSACTIONATURALTERAISEXCLUSIVE         */
117911   /*   XISTSAVEPOINTERSECTRIGGEREFERENCESCONSTRAINTOFFSETEMPORARY         */
117912   /*   UNIQUERYWITHOUTERELEASEATTACHAVINGROUPDATEBEGINNERENAMEBETWEEN     */
117913   /*   OTNULLIKECASCADELETECASECOLLATECREATECURRENT_DATEDETACH            */
117914   /*   IMMEDIATEJOINSERTMATCHPLANALYZEPRAGMABORTVALUESVIRTUALIMITWHEN     */
117915   /*   WHEREPLACEAFTERESTRICTANDEFAULTAUTOINCREMENTCASTCOLUMNCOMMIT       */
117916   /*   CONFLICTCROSSCURRENT_TIMESTAMPRIMARYDEFERREDISTINCTDROPFAIL        */
117917   /*   FROMFULLGLOBYIFISNULLORDERIGHTROLLBACKROWUNIONUSINGVACUUMVIEW      */
117918   /*   INITIALLY                                                          */
117919   static const char zText[544] = {
117920     'R','E','I','N','D','E','X','E','D','E','S','C','A','P','E','A','C','H',
117921     'E','C','K','E','Y','B','E','F','O','R','E','I','G','N','O','R','E','G',
117922     'E','X','P','L','A','I','N','S','T','E','A','D','D','A','T','A','B','A',
117923     'S','E','L','E','C','T','A','B','L','E','F','T','H','E','N','D','E','F',
117924     'E','R','R','A','B','L','E','L','S','E','X','C','E','P','T','R','A','N',
117925     'S','A','C','T','I','O','N','A','T','U','R','A','L','T','E','R','A','I',
117926     'S','E','X','C','L','U','S','I','V','E','X','I','S','T','S','A','V','E',
117927     'P','O','I','N','T','E','R','S','E','C','T','R','I','G','G','E','R','E',
117928     'F','E','R','E','N','C','E','S','C','O','N','S','T','R','A','I','N','T',
117929     'O','F','F','S','E','T','E','M','P','O','R','A','R','Y','U','N','I','Q',
117930     'U','E','R','Y','W','I','T','H','O','U','T','E','R','E','L','E','A','S',
117931     'E','A','T','T','A','C','H','A','V','I','N','G','R','O','U','P','D','A',
117932     'T','E','B','E','G','I','N','N','E','R','E','N','A','M','E','B','E','T',
117933     'W','E','E','N','O','T','N','U','L','L','I','K','E','C','A','S','C','A',
117934     'D','E','L','E','T','E','C','A','S','E','C','O','L','L','A','T','E','C',
117935     'R','E','A','T','E','C','U','R','R','E','N','T','_','D','A','T','E','D',
117936     'E','T','A','C','H','I','M','M','E','D','I','A','T','E','J','O','I','N',
117937     'S','E','R','T','M','A','T','C','H','P','L','A','N','A','L','Y','Z','E',
117938     'P','R','A','G','M','A','B','O','R','T','V','A','L','U','E','S','V','I',
117939     'R','T','U','A','L','I','M','I','T','W','H','E','N','W','H','E','R','E',
117940     'P','L','A','C','E','A','F','T','E','R','E','S','T','R','I','C','T','A',
117941     'N','D','E','F','A','U','L','T','A','U','T','O','I','N','C','R','E','M',
117942     'E','N','T','C','A','S','T','C','O','L','U','M','N','C','O','M','M','I',
117943     'T','C','O','N','F','L','I','C','T','C','R','O','S','S','C','U','R','R',
117944     'E','N','T','_','T','I','M','E','S','T','A','M','P','R','I','M','A','R',
117945     'Y','D','E','F','E','R','R','E','D','I','S','T','I','N','C','T','D','R',
117946     'O','P','F','A','I','L','F','R','O','M','F','U','L','L','G','L','O','B',
117947     'Y','I','F','I','S','N','U','L','L','O','R','D','E','R','I','G','H','T',
117948     'R','O','L','L','B','A','C','K','R','O','W','U','N','I','O','N','U','S',
117949     'I','N','G','V','A','C','U','U','M','V','I','E','W','I','N','I','T','I',
117950     'A','L','L','Y',
117951   };
117952   static const unsigned char aHash[127] = {
117953       75, 104, 115,  73,   0,  45,   0,   0,  81,   0,  76,   0,   0,
117954       42,  12,  77,  15,   0, 114,  84,  53, 111,   0,  19,   0,   0,
117955      119,   0, 117,  88,   0,  22,  92,   0,   9,   0,   0,  69,  70,
117956        0,  68,   6,   0,  48,  89, 101,   0, 116, 100,   0,   0,  44,
117957        0, 102,  24,   0,  17,   0, 120,  52,  23,   0,   5, 109,  25,
117958       95,   0,   0, 122, 105,  59, 121,  56,  28,  54,   0,  90,   0,
117959       99,  26,   0,  98,   0,   0,   0,  94,  91,  96,  87, 108,  14,
117960       39, 107,   0,  80,   0,  18,  86, 110,  32,   0, 118,  79, 112,
117961       61,  46,  83,   0,   0,  93,  40,   0, 113,   0,  36,   0,   0,
117962       29,   0,  85,  62,  63,   0,  20,  60,   0,  55,
117963   };
117964   static const unsigned char aNext[122] = {
117965        0,   0,   0,   0,   4,   0,   0,   0,   0,   0,   0,   0,   0,
117966        0,   2,   0,   0,   0,   0,   0,   0,  13,   0,   0,   0,   0,
117967        0,   7,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,   0,
117968        0,   0,   0,   0,  33,   0,  21,   0,   0,   0,   0,   0,   0,
117969       43,   3,  47,   0,   0,   0,   0,  30,   0,  57,   0,  38,   0,
117970        0,   0,   1,  65,   0,   0,  66,   0,  41,   0,   0,   0,   0,
117971        0,   0,  49,  64,   0,   0,   0,  51,  31,   0,  16,  34,  10,
117972        0,   0,   0,   0,   0,   0,   0,  11,  71,  78,   0,   8,   0,
117973      103,  97,   0, 106,   0,  58,   0,  74,  50,  27,  37,  72,  82,
117974        0,  35,  67,   0,   0,
117975   };
117976   static const unsigned char aLen[122] = {
117977        7,   7,   5,   4,   6,   4,   5,   3,   6,   7,   3,   6,   6,
117978        7,   7,   3,   8,   2,   6,   5,   4,   4,   3,  10,   4,   6,
117979       11,   6,   2,   7,   5,   5,   9,   6,   9,   9,   7,  10,  10,
117980        4,   6,   2,   3,   9,   4,   2,   6,   5,   7,   5,   7,   6,
117981        6,   5,   6,   5,   5,   6,   7,   7,   3,   2,   4,   4,   7,
117982        3,   6,   4,   7,   6,  12,   6,   9,   4,   6,   5,   4,   7,
117983        6,   5,   6,   7,   5,   4,   5,   7,   5,   8,   3,   7,  13,
117984        2,   2,   4,   6,   6,   8,   5,  17,  12,   7,   8,   8,   2,
117985        4,   4,   4,   4,   4,   2,   2,   6,   5,   5,   8,   3,   5,
117986        5,   6,   4,   9,   3,
117987   };
117988   static const unsigned short int aOffset[122] = {
117989        0,   2,   2,   8,   9,  14,  16,  20,  23,  25,  25,  29,  33,
117990       36,  41,  46,  48,  53,  54,  59,  62,  65,  67,  69,  78,  81,
117991       86,  91,  95,  96, 101, 105, 109, 117, 122, 128, 136, 142, 152,
117992      159, 162, 162, 165, 167, 167, 171, 176, 179, 184, 188, 192, 199,
117993      204, 209, 212, 218, 221, 225, 231, 237, 237, 237, 240, 243, 247,
117994      248, 252, 258, 262, 269, 275, 287, 293, 302, 304, 310, 315, 317,
117995      324, 329, 334, 340, 346, 351, 355, 358, 365, 369, 377, 379, 386,
117996      388, 390, 399, 403, 409, 415, 423, 428, 428, 444, 451, 458, 459,
117997      466, 470, 474, 478, 482, 485, 487, 489, 495, 499, 504, 512, 515,
117998      520, 525, 531, 535, 540,
117999   };
118000   static const unsigned char aCode[122] = {
118001     TK_REINDEX,    TK_INDEXED,    TK_INDEX,      TK_DESC,       TK_ESCAPE,     
118002     TK_EACH,       TK_CHECK,      TK_KEY,        TK_BEFORE,     TK_FOREIGN,    
118003     TK_FOR,        TK_IGNORE,     TK_LIKE_KW,    TK_EXPLAIN,    TK_INSTEAD,    
118004     TK_ADD,        TK_DATABASE,   TK_AS,         TK_SELECT,     TK_TABLE,      
118005     TK_JOIN_KW,    TK_THEN,       TK_END,        TK_DEFERRABLE, TK_ELSE,       
118006     TK_EXCEPT,     TK_TRANSACTION,TK_ACTION,     TK_ON,         TK_JOIN_KW,    
118007     TK_ALTER,      TK_RAISE,      TK_EXCLUSIVE,  TK_EXISTS,     TK_SAVEPOINT,  
118008     TK_INTERSECT,  TK_TRIGGER,    TK_REFERENCES, TK_CONSTRAINT, TK_INTO,       
118009     TK_OFFSET,     TK_OF,         TK_SET,        TK_TEMP,       TK_TEMP,       
118010     TK_OR,         TK_UNIQUE,     TK_QUERY,      TK_WITHOUT,    TK_JOIN_KW,    
118011     TK_RELEASE,    TK_ATTACH,     TK_HAVING,     TK_GROUP,      TK_UPDATE,     
118012     TK_BEGIN,      TK_JOIN_KW,    TK_RENAME,     TK_BETWEEN,    TK_NOTNULL,    
118013     TK_NOT,        TK_NO,         TK_NULL,       TK_LIKE_KW,    TK_CASCADE,    
118014     TK_ASC,        TK_DELETE,     TK_CASE,       TK_COLLATE,    TK_CREATE,     
118015     TK_CTIME_KW,   TK_DETACH,     TK_IMMEDIATE,  TK_JOIN,       TK_INSERT,     
118016     TK_MATCH,      TK_PLAN,       TK_ANALYZE,    TK_PRAGMA,     TK_ABORT,      
118017     TK_VALUES,     TK_VIRTUAL,    TK_LIMIT,      TK_WHEN,       TK_WHERE,      
118018     TK_REPLACE,    TK_AFTER,      TK_RESTRICT,   TK_AND,        TK_DEFAULT,    
118019     TK_AUTOINCR,   TK_TO,         TK_IN,         TK_CAST,       TK_COLUMNKW,   
118020     TK_COMMIT,     TK_CONFLICT,   TK_JOIN_KW,    TK_CTIME_KW,   TK_CTIME_KW,   
118021     TK_PRIMARY,    TK_DEFERRED,   TK_DISTINCT,   TK_IS,         TK_DROP,       
118022     TK_FAIL,       TK_FROM,       TK_JOIN_KW,    TK_LIKE_KW,    TK_BY,         
118023     TK_IF,         TK_ISNULL,     TK_ORDER,      TK_JOIN_KW,    TK_ROLLBACK,   
118024     TK_ROW,        TK_UNION,      TK_USING,      TK_VACUUM,     TK_VIEW,       
118025     TK_INITIALLY,  TK_ALL,        
118026   };
118027   int h, i;
118028   if( n<2 ) return TK_ID;
118029   h = ((charMap(z[0])*4) ^
118030       (charMap(z[n-1])*3) ^
118031       n) % 127;
118032   for(i=((int)aHash[h])-1; i>=0; i=((int)aNext[i])-1){
118033     if( aLen[i]==n && sqlite3StrNICmp(&zText[aOffset[i]],z,n)==0 ){
118034       testcase( i==0 ); /* REINDEX */
118035       testcase( i==1 ); /* INDEXED */
118036       testcase( i==2 ); /* INDEX */
118037       testcase( i==3 ); /* DESC */
118038       testcase( i==4 ); /* ESCAPE */
118039       testcase( i==5 ); /* EACH */
118040       testcase( i==6 ); /* CHECK */
118041       testcase( i==7 ); /* KEY */
118042       testcase( i==8 ); /* BEFORE */
118043       testcase( i==9 ); /* FOREIGN */
118044       testcase( i==10 ); /* FOR */
118045       testcase( i==11 ); /* IGNORE */
118046       testcase( i==12 ); /* REGEXP */
118047       testcase( i==13 ); /* EXPLAIN */
118048       testcase( i==14 ); /* INSTEAD */
118049       testcase( i==15 ); /* ADD */
118050       testcase( i==16 ); /* DATABASE */
118051       testcase( i==17 ); /* AS */
118052       testcase( i==18 ); /* SELECT */
118053       testcase( i==19 ); /* TABLE */
118054       testcase( i==20 ); /* LEFT */
118055       testcase( i==21 ); /* THEN */
118056       testcase( i==22 ); /* END */
118057       testcase( i==23 ); /* DEFERRABLE */
118058       testcase( i==24 ); /* ELSE */
118059       testcase( i==25 ); /* EXCEPT */
118060       testcase( i==26 ); /* TRANSACTION */
118061       testcase( i==27 ); /* ACTION */
118062       testcase( i==28 ); /* ON */
118063       testcase( i==29 ); /* NATURAL */
118064       testcase( i==30 ); /* ALTER */
118065       testcase( i==31 ); /* RAISE */
118066       testcase( i==32 ); /* EXCLUSIVE */
118067       testcase( i==33 ); /* EXISTS */
118068       testcase( i==34 ); /* SAVEPOINT */
118069       testcase( i==35 ); /* INTERSECT */
118070       testcase( i==36 ); /* TRIGGER */
118071       testcase( i==37 ); /* REFERENCES */
118072       testcase( i==38 ); /* CONSTRAINT */
118073       testcase( i==39 ); /* INTO */
118074       testcase( i==40 ); /* OFFSET */
118075       testcase( i==41 ); /* OF */
118076       testcase( i==42 ); /* SET */
118077       testcase( i==43 ); /* TEMPORARY */
118078       testcase( i==44 ); /* TEMP */
118079       testcase( i==45 ); /* OR */
118080       testcase( i==46 ); /* UNIQUE */
118081       testcase( i==47 ); /* QUERY */
118082       testcase( i==48 ); /* WITHOUT */
118083       testcase( i==49 ); /* OUTER */
118084       testcase( i==50 ); /* RELEASE */
118085       testcase( i==51 ); /* ATTACH */
118086       testcase( i==52 ); /* HAVING */
118087       testcase( i==53 ); /* GROUP */
118088       testcase( i==54 ); /* UPDATE */
118089       testcase( i==55 ); /* BEGIN */
118090       testcase( i==56 ); /* INNER */
118091       testcase( i==57 ); /* RENAME */
118092       testcase( i==58 ); /* BETWEEN */
118093       testcase( i==59 ); /* NOTNULL */
118094       testcase( i==60 ); /* NOT */
118095       testcase( i==61 ); /* NO */
118096       testcase( i==62 ); /* NULL */
118097       testcase( i==63 ); /* LIKE */
118098       testcase( i==64 ); /* CASCADE */
118099       testcase( i==65 ); /* ASC */
118100       testcase( i==66 ); /* DELETE */
118101       testcase( i==67 ); /* CASE */
118102       testcase( i==68 ); /* COLLATE */
118103       testcase( i==69 ); /* CREATE */
118104       testcase( i==70 ); /* CURRENT_DATE */
118105       testcase( i==71 ); /* DETACH */
118106       testcase( i==72 ); /* IMMEDIATE */
118107       testcase( i==73 ); /* JOIN */
118108       testcase( i==74 ); /* INSERT */
118109       testcase( i==75 ); /* MATCH */
118110       testcase( i==76 ); /* PLAN */
118111       testcase( i==77 ); /* ANALYZE */
118112       testcase( i==78 ); /* PRAGMA */
118113       testcase( i==79 ); /* ABORT */
118114       testcase( i==80 ); /* VALUES */
118115       testcase( i==81 ); /* VIRTUAL */
118116       testcase( i==82 ); /* LIMIT */
118117       testcase( i==83 ); /* WHEN */
118118       testcase( i==84 ); /* WHERE */
118119       testcase( i==85 ); /* REPLACE */
118120       testcase( i==86 ); /* AFTER */
118121       testcase( i==87 ); /* RESTRICT */
118122       testcase( i==88 ); /* AND */
118123       testcase( i==89 ); /* DEFAULT */
118124       testcase( i==90 ); /* AUTOINCREMENT */
118125       testcase( i==91 ); /* TO */
118126       testcase( i==92 ); /* IN */
118127       testcase( i==93 ); /* CAST */
118128       testcase( i==94 ); /* COLUMN */
118129       testcase( i==95 ); /* COMMIT */
118130       testcase( i==96 ); /* CONFLICT */
118131       testcase( i==97 ); /* CROSS */
118132       testcase( i==98 ); /* CURRENT_TIMESTAMP */
118133       testcase( i==99 ); /* CURRENT_TIME */
118134       testcase( i==100 ); /* PRIMARY */
118135       testcase( i==101 ); /* DEFERRED */
118136       testcase( i==102 ); /* DISTINCT */
118137       testcase( i==103 ); /* IS */
118138       testcase( i==104 ); /* DROP */
118139       testcase( i==105 ); /* FAIL */
118140       testcase( i==106 ); /* FROM */
118141       testcase( i==107 ); /* FULL */
118142       testcase( i==108 ); /* GLOB */
118143       testcase( i==109 ); /* BY */
118144       testcase( i==110 ); /* IF */
118145       testcase( i==111 ); /* ISNULL */
118146       testcase( i==112 ); /* ORDER */
118147       testcase( i==113 ); /* RIGHT */
118148       testcase( i==114 ); /* ROLLBACK */
118149       testcase( i==115 ); /* ROW */
118150       testcase( i==116 ); /* UNION */
118151       testcase( i==117 ); /* USING */
118152       testcase( i==118 ); /* VACUUM */
118153       testcase( i==119 ); /* VIEW */
118154       testcase( i==120 ); /* INITIALLY */
118155       testcase( i==121 ); /* ALL */
118156       return aCode[i];
118157     }
118158   }
118159   return TK_ID;
118160 }
118161 SQLITE_PRIVATE int sqlite3KeywordCode(const unsigned char *z, int n){
118162   return keywordCode((char*)z, n);
118163 }
118164 #define SQLITE_N_KEYWORD 122
118165 
118166 /************** End of keywordhash.h *****************************************/
118167 /************** Continuing where we left off in tokenize.c *******************/
118168 
118169 
118170 /*
118171 ** If X is a character that can be used in an identifier then
118172 ** IdChar(X) will be true.  Otherwise it is false.
118173 **
118174 ** For ASCII, any character with the high-order bit set is
118175 ** allowed in an identifier.  For 7-bit characters, 
118176 ** sqlite3IsIdChar[X] must be 1.
118177 **
118178 ** For EBCDIC, the rules are more complex but have the same
118179 ** end result.
118180 **
118181 ** Ticket #1066.  the SQL standard does not allow '$' in the
118182 ** middle of identfiers.  But many SQL implementations do. 
118183 ** SQLite will allow '$' in identifiers for compatibility.
118184 ** But the feature is undocumented.
118185 */
118186 #ifdef SQLITE_ASCII
118187 #define IdChar(C)  ((sqlite3CtypeMap[(unsigned char)C]&0x46)!=0)
118188 #endif
118189 #ifdef SQLITE_EBCDIC
118190 SQLITE_PRIVATE const char sqlite3IsEbcdicIdChar[] = {
118191 /* x0 x1 x2 x3 x4 x5 x6 x7 x8 x9 xA xB xC xD xE xF */
118192     0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0,  /* 4x */
118193     0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 1, 0, 0, 0, 0,  /* 5x */
118194     0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 1, 0, 0,  /* 6x */
118195     0, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0,  /* 7x */
118196     0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 1, 1, 1, 0,  /* 8x */
118197     0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 1, 0, 1, 0,  /* 9x */
118198     1, 0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 1, 1, 1, 0,  /* Ax */
118199     0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,  /* Bx */
118200     0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 1, 1, 1, 1, 1,  /* Cx */
118201     0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 1, 1, 1, 1, 1,  /* Dx */
118202     0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 0, 1, 1, 1, 1, 1,  /* Ex */
118203     1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 1, 1, 1, 1, 0,  /* Fx */
118204 };
118205 #define IdChar(C)  (((c=C)>=0x42 && sqlite3IsEbcdicIdChar[c-0x40]))
118206 #endif
118207 
118208 
118209 /*
118210 ** Return the length of the token that begins at z[0]. 
118211 ** Store the token type in *tokenType before returning.
118212 */
118213 SQLITE_PRIVATE int sqlite3GetToken(const unsigned char *z, int *tokenType){
118214   int i, c;
118215   switch( *z ){
118216     case ' ': case '\t': case '\n': case '\f': case '\r': {
118217       testcase( z[0]==' ' );
118218       testcase( z[0]=='\t' );
118219       testcase( z[0]=='\n' );
118220       testcase( z[0]=='\f' );
118221       testcase( z[0]=='\r' );
118222       for(i=1; sqlite3Isspace(z[i]); i++){}
118223       *tokenType = TK_SPACE;
118224       return i;
118225     }
118226     case '-': {
118227       if( z[1]=='-' ){
118228         for(i=2; (c=z[i])!=0 && c!='\n'; i++){}
118229         *tokenType = TK_SPACE;   /* IMP: R-22934-25134 */
118230         return i;
118231       }
118232       *tokenType = TK_MINUS;
118233       return 1;
118234     }
118235     case '(': {
118236       *tokenType = TK_LP;
118237       return 1;
118238     }
118239     case ')': {
118240       *tokenType = TK_RP;
118241       return 1;
118242     }
118243     case ';': {
118244       *tokenType = TK_SEMI;
118245       return 1;
118246     }
118247     case '+': {
118248       *tokenType = TK_PLUS;
118249       return 1;
118250     }
118251     case '*': {
118252       *tokenType = TK_STAR;
118253       return 1;
118254     }
118255     case '/': {
118256       if( z[1]!='*' || z[2]==0 ){
118257         *tokenType = TK_SLASH;
118258         return 1;
118259       }
118260       for(i=3, c=z[2]; (c!='*' || z[i]!='/') && (c=z[i])!=0; i++){}
118261       if( c ) i++;
118262       *tokenType = TK_SPACE;   /* IMP: R-22934-25134 */
118263       return i;
118264     }
118265     case '%': {
118266       *tokenType = TK_REM;
118267       return 1;
118268     }
118269     case '=': {
118270       *tokenType = TK_EQ;
118271       return 1 + (z[1]=='=');
118272     }
118273     case '<': {
118274       if( (c=z[1])=='=' ){
118275         *tokenType = TK_LE;
118276         return 2;
118277       }else if( c=='>' ){
118278         *tokenType = TK_NE;
118279         return 2;
118280       }else if( c=='<' ){
118281         *tokenType = TK_LSHIFT;
118282         return 2;
118283       }else{
118284         *tokenType = TK_LT;
118285         return 1;
118286       }
118287     }
118288     case '>': {
118289       if( (c=z[1])=='=' ){
118290         *tokenType = TK_GE;
118291         return 2;
118292       }else if( c=='>' ){
118293         *tokenType = TK_RSHIFT;
118294         return 2;
118295       }else{
118296         *tokenType = TK_GT;
118297         return 1;
118298       }
118299     }
118300     case '!': {
118301       if( z[1]!='=' ){
118302         *tokenType = TK_ILLEGAL;
118303         return 2;
118304       }else{
118305         *tokenType = TK_NE;
118306         return 2;
118307       }
118308     }
118309     case '|': {
118310       if( z[1]!='|' ){
118311         *tokenType = TK_BITOR;
118312         return 1;
118313       }else{
118314         *tokenType = TK_CONCAT;
118315         return 2;
118316       }
118317     }
118318     case ',': {
118319       *tokenType = TK_COMMA;
118320       return 1;
118321     }
118322     case '&': {
118323       *tokenType = TK_BITAND;
118324       return 1;
118325     }
118326     case '~': {
118327       *tokenType = TK_BITNOT;
118328       return 1;
118329     }
118330     case '`':
118331     case '\'':
118332     case '"': {
118333       int delim = z[0];
118334       testcase( delim=='`' );
118335       testcase( delim=='\'' );
118336       testcase( delim=='"' );
118337       for(i=1; (c=z[i])!=0; i++){
118338         if( c==delim ){
118339           if( z[i+1]==delim ){
118340             i++;
118341           }else{
118342             break;
118343           }
118344         }
118345       }
118346       if( c=='\'' ){
118347         *tokenType = TK_STRING;
118348         return i+1;
118349       }else if( c!=0 ){
118350         *tokenType = TK_ID;
118351         return i+1;
118352       }else{
118353         *tokenType = TK_ILLEGAL;
118354         return i;
118355       }
118356     }
118357     case '.': {
118358 #ifndef SQLITE_OMIT_FLOATING_POINT
118359       if( !sqlite3Isdigit(z[1]) )
118360 #endif
118361       {
118362         *tokenType = TK_DOT;
118363         return 1;
118364       }
118365       /* If the next character is a digit, this is a floating point
118366       ** number that begins with ".".  Fall thru into the next case */
118367     }
118368     case '0': case '1': case '2': case '3': case '4':
118369     case '5': case '6': case '7': case '8': case '9': {
118370       testcase( z[0]=='0' );  testcase( z[0]=='1' );  testcase( z[0]=='2' );
118371       testcase( z[0]=='3' );  testcase( z[0]=='4' );  testcase( z[0]=='5' );
118372       testcase( z[0]=='6' );  testcase( z[0]=='7' );  testcase( z[0]=='8' );
118373       testcase( z[0]=='9' );
118374       *tokenType = TK_INTEGER;
118375       for(i=0; sqlite3Isdigit(z[i]); i++){}
118376 #ifndef SQLITE_OMIT_FLOATING_POINT
118377       if( z[i]=='.' ){
118378         i++;
118379         while( sqlite3Isdigit(z[i]) ){ i++; }
118380         *tokenType = TK_FLOAT;
118381       }
118382       if( (z[i]=='e' || z[i]=='E') &&
118383            ( sqlite3Isdigit(z[i+1]) 
118384             || ((z[i+1]=='+' || z[i+1]=='-') && sqlite3Isdigit(z[i+2]))
118385            )
118386       ){
118387         i += 2;
118388         while( sqlite3Isdigit(z[i]) ){ i++; }
118389         *tokenType = TK_FLOAT;
118390       }
118391 #endif
118392       while( IdChar(z[i]) ){
118393         *tokenType = TK_ILLEGAL;
118394         i++;
118395       }
118396       return i;
118397     }
118398     case '[': {
118399       for(i=1, c=z[0]; c!=']' && (c=z[i])!=0; i++){}
118400       *tokenType = c==']' ? TK_ID : TK_ILLEGAL;
118401       return i;
118402     }
118403     case '?': {
118404       *tokenType = TK_VARIABLE;
118405       for(i=1; sqlite3Isdigit(z[i]); i++){}
118406       return i;
118407     }
118408     case '#': {
118409       for(i=1; sqlite3Isdigit(z[i]); i++){}
118410       if( i>1 ){
118411         /* Parameters of the form #NNN (where NNN is a number) are used
118412         ** internally by sqlite3NestedParse.  */
118413         *tokenType = TK_REGISTER;
118414         return i;
118415       }
118416       /* Fall through into the next case if the '#' is not followed by
118417       ** a digit. Try to match #AAAA where AAAA is a parameter name. */
118418     }
118419 #ifndef SQLITE_OMIT_TCL_VARIABLE
118420     case '$':
118421 #endif
118422     case '@':  /* For compatibility with MS SQL Server */
118423     case ':': {
118424       int n = 0;
118425       testcase( z[0]=='$' );  testcase( z[0]=='@' );  testcase( z[0]==':' );
118426       *tokenType = TK_VARIABLE;
118427       for(i=1; (c=z[i])!=0; i++){
118428         if( IdChar(c) ){
118429           n++;
118430 #ifndef SQLITE_OMIT_TCL_VARIABLE
118431         }else if( c=='(' && n>0 ){
118432           do{
118433             i++;
118434           }while( (c=z[i])!=0 && !sqlite3Isspace(c) && c!=')' );
118435           if( c==')' ){
118436             i++;
118437           }else{
118438             *tokenType = TK_ILLEGAL;
118439           }
118440           break;
118441         }else if( c==':' && z[i+1]==':' ){
118442           i++;
118443 #endif
118444         }else{
118445           break;
118446         }
118447       }
118448       if( n==0 ) *tokenType = TK_ILLEGAL;
118449       return i;
118450     }
118451 #ifndef SQLITE_OMIT_BLOB_LITERAL
118452     case 'x': case 'X': {
118453       testcase( z[0]=='x' ); testcase( z[0]=='X' );
118454       if( z[1]=='\'' ){
118455         *tokenType = TK_BLOB;
118456         for(i=2; sqlite3Isxdigit(z[i]); i++){}
118457         if( z[i]!='\'' || i%2 ){
118458           *tokenType = TK_ILLEGAL;
118459           while( z[i] && z[i]!='\'' ){ i++; }
118460         }
118461         if( z[i] ) i++;
118462         return i;
118463       }
118464       /* Otherwise fall through to the next case */
118465     }
118466 #endif
118467     default: {
118468       if( !IdChar(*z) ){
118469         break;
118470       }
118471       for(i=1; IdChar(z[i]); i++){}
118472       *tokenType = keywordCode((char*)z, i);
118473       return i;
118474     }
118475   }
118476   *tokenType = TK_ILLEGAL;
118477   return 1;
118478 }
118479 
118480 /*
118481 ** Run the parser on the given SQL string.  The parser structure is
118482 ** passed in.  An SQLITE_ status code is returned.  If an error occurs
118483 ** then an and attempt is made to write an error message into 
118484 ** memory obtained from sqlite3_malloc() and to make *pzErrMsg point to that
118485 ** error message.
118486 */
118487 SQLITE_PRIVATE int sqlite3RunParser(Parse *pParse, const char *zSql, char **pzErrMsg){
118488   int nErr = 0;                   /* Number of errors encountered */
118489   int i;                          /* Loop counter */
118490   void *pEngine;                  /* The LEMON-generated LALR(1) parser */
118491   int tokenType;                  /* type of the next token */
118492   int lastTokenParsed = -1;       /* type of the previous token */
118493   u8 enableLookaside;             /* Saved value of db->lookaside.bEnabled */
118494   sqlite3 *db = pParse->db;       /* The database connection */
118495   int mxSqlLen;                   /* Max length of an SQL string */
118496 
118497 
118498   mxSqlLen = db->aLimit[SQLITE_LIMIT_SQL_LENGTH];
118499   if( db->nVdbeActive==0 ){
118500     db->u1.isInterrupted = 0;
118501   }
118502   pParse->rc = SQLITE_OK;
118503   pParse->zTail = zSql;
118504   i = 0;
118505   assert( pzErrMsg!=0 );
118506   pEngine = sqlite3ParserAlloc((void*(*)(size_t))sqlite3Malloc);
118507   if( pEngine==0 ){
118508     db->mallocFailed = 1;
118509     return SQLITE_NOMEM;
118510   }
118511   assert( pParse->pNewTable==0 );
118512   assert( pParse->pNewTrigger==0 );
118513   assert( pParse->nVar==0 );
118514   assert( pParse->nzVar==0 );
118515   assert( pParse->azVar==0 );
118516   enableLookaside = db->lookaside.bEnabled;
118517   if( db->lookaside.pStart ) db->lookaside.bEnabled = 1;
118518   while( !db->mallocFailed && zSql[i]!=0 ){
118519     assert( i>=0 );
118520     pParse->sLastToken.z = &zSql[i];
118521     pParse->sLastToken.n = sqlite3GetToken((unsigned char*)&zSql[i],&tokenType);
118522     i += pParse->sLastToken.n;
118523     if( i>mxSqlLen ){
118524       pParse->rc = SQLITE_TOOBIG;
118525       break;
118526     }
118527     switch( tokenType ){
118528       case TK_SPACE: {
118529         if( db->u1.isInterrupted ){
118530           sqlite3ErrorMsg(pParse, "interrupt");
118531           pParse->rc = SQLITE_INTERRUPT;
118532           goto abort_parse;
118533         }
118534         break;
118535       }
118536       case TK_ILLEGAL: {
118537         sqlite3DbFree(db, *pzErrMsg);
118538         *pzErrMsg = sqlite3MPrintf(db, "unrecognized token: \"%T\"",
118539                         &pParse->sLastToken);
118540         nErr++;
118541         goto abort_parse;
118542       }
118543       case TK_SEMI: {
118544         pParse->zTail = &zSql[i];
118545         /* Fall thru into the default case */
118546       }
118547       default: {
118548         sqlite3Parser(pEngine, tokenType, pParse->sLastToken, pParse);
118549         lastTokenParsed = tokenType;
118550         if( pParse->rc!=SQLITE_OK ){
118551           goto abort_parse;
118552         }
118553         break;
118554       }
118555     }
118556   }
118557 abort_parse:
118558   if( zSql[i]==0 && nErr==0 && pParse->rc==SQLITE_OK ){
118559     if( lastTokenParsed!=TK_SEMI ){
118560       sqlite3Parser(pEngine, TK_SEMI, pParse->sLastToken, pParse);
118561       pParse->zTail = &zSql[i];
118562     }
118563     sqlite3Parser(pEngine, 0, pParse->sLastToken, pParse);
118564   }
118565 #ifdef YYTRACKMAXSTACKDEPTH
118566   sqlite3StatusSet(SQLITE_STATUS_PARSER_STACK,
118567       sqlite3ParserStackPeak(pEngine)
118568   );
118569 #endif /* YYDEBUG */
118570   sqlite3ParserFree(pEngine, sqlite3_free);
118571   db->lookaside.bEnabled = enableLookaside;
118572   if( db->mallocFailed ){
118573     pParse->rc = SQLITE_NOMEM;
118574   }
118575   if( pParse->rc!=SQLITE_OK && pParse->rc!=SQLITE_DONE && pParse->zErrMsg==0 ){
118576     sqlite3SetString(&pParse->zErrMsg, db, "%s", sqlite3ErrStr(pParse->rc));
118577   }
118578   assert( pzErrMsg!=0 );
118579   if( pParse->zErrMsg ){
118580     *pzErrMsg = pParse->zErrMsg;
118581     sqlite3_log(pParse->rc, "%s", *pzErrMsg);
118582     pParse->zErrMsg = 0;
118583     nErr++;
118584   }
118585   if( pParse->pVdbe && pParse->nErr>0 && pParse->nested==0 ){
118586     sqlite3VdbeDelete(pParse->pVdbe);
118587     pParse->pVdbe = 0;
118588   }
118589 #ifndef SQLITE_OMIT_SHARED_CACHE
118590   if( pParse->nested==0 ){
118591     sqlite3DbFree(db, pParse->aTableLock);
118592     pParse->aTableLock = 0;
118593     pParse->nTableLock = 0;
118594   }
118595 #endif
118596 #ifndef SQLITE_OMIT_VIRTUALTABLE
118597   sqlite3_free(pParse->apVtabLock);
118598 #endif
118599 
118600   if( !IN_DECLARE_VTAB ){
118601     /* If the pParse->declareVtab flag is set, do not delete any table 
118602     ** structure built up in pParse->pNewTable. The calling code (see vtab.c)
118603     ** will take responsibility for freeing the Table structure.
118604     */
118605     sqlite3DeleteTable(db, pParse->pNewTable);
118606   }
118607 
118608   sqlite3DeleteTrigger(db, pParse->pNewTrigger);
118609   for(i=pParse->nzVar-1; i>=0; i--) sqlite3DbFree(db, pParse->azVar[i]);
118610   sqlite3DbFree(db, pParse->azVar);
118611   while( pParse->pAinc ){
118612     AutoincInfo *p = pParse->pAinc;
118613     pParse->pAinc = p->pNext;
118614     sqlite3DbFree(db, p);
118615   }
118616   while( pParse->pZombieTab ){
118617     Table *p = pParse->pZombieTab;
118618     pParse->pZombieTab = p->pNextZombie;
118619     sqlite3DeleteTable(db, p);
118620   }
118621   if( nErr>0 && pParse->rc==SQLITE_OK ){
118622     pParse->rc = SQLITE_ERROR;
118623   }
118624   return nErr;
118625 }
118626 
118627 /************** End of tokenize.c ********************************************/
118628 /************** Begin file complete.c ****************************************/
118629 /*
118630 ** 2001 September 15
118631 **
118632 ** The author disclaims copyright to this source code.  In place of
118633 ** a legal notice, here is a blessing:
118634 **
118635 **    May you do good and not evil.
118636 **    May you find forgiveness for yourself and forgive others.
118637 **    May you share freely, never taking more than you give.
118638 **
118639 *************************************************************************
118640 ** An tokenizer for SQL
118641 **
118642 ** This file contains C code that implements the sqlite3_complete() API.
118643 ** This code used to be part of the tokenizer.c source file.  But by
118644 ** separating it out, the code will be automatically omitted from
118645 ** static links that do not use it.
118646 */
118647 #ifndef SQLITE_OMIT_COMPLETE
118648 
118649 /*
118650 ** This is defined in tokenize.c.  We just have to import the definition.
118651 */
118652 #ifndef SQLITE_AMALGAMATION
118653 #ifdef SQLITE_ASCII
118654 #define IdChar(C)  ((sqlite3CtypeMap[(unsigned char)C]&0x46)!=0)
118655 #endif
118656 #ifdef SQLITE_EBCDIC
118657 SQLITE_PRIVATE const char sqlite3IsEbcdicIdChar[];
118658 #define IdChar(C)  (((c=C)>=0x42 && sqlite3IsEbcdicIdChar[c-0x40]))
118659 #endif
118660 #endif /* SQLITE_AMALGAMATION */
118661 
118662 
118663 /*
118664 ** Token types used by the sqlite3_complete() routine.  See the header
118665 ** comments on that procedure for additional information.
118666 */
118667 #define tkSEMI    0
118668 #define tkWS      1
118669 #define tkOTHER   2
118670 #ifndef SQLITE_OMIT_TRIGGER
118671 #define tkEXPLAIN 3
118672 #define tkCREATE  4
118673 #define tkTEMP    5
118674 #define tkTRIGGER 6
118675 #define tkEND     7
118676 #endif
118677 
118678 /*
118679 ** Return TRUE if the given SQL string ends in a semicolon.
118680 **
118681 ** Special handling is require for CREATE TRIGGER statements.
118682 ** Whenever the CREATE TRIGGER keywords are seen, the statement
118683 ** must end with ";END;".
118684 **
118685 ** This implementation uses a state machine with 8 states:
118686 **
118687 **   (0) INVALID   We have not yet seen a non-whitespace character.
118688 **
118689 **   (1) START     At the beginning or end of an SQL statement.  This routine
118690 **                 returns 1 if it ends in the START state and 0 if it ends
118691 **                 in any other state.
118692 **
118693 **   (2) NORMAL    We are in the middle of statement which ends with a single
118694 **                 semicolon.
118695 **
118696 **   (3) EXPLAIN   The keyword EXPLAIN has been seen at the beginning of 
118697 **                 a statement.
118698 **
118699 **   (4) CREATE    The keyword CREATE has been seen at the beginning of a
118700 **                 statement, possibly preceeded by EXPLAIN and/or followed by
118701 **                 TEMP or TEMPORARY
118702 **
118703 **   (5) TRIGGER   We are in the middle of a trigger definition that must be
118704 **                 ended by a semicolon, the keyword END, and another semicolon.
118705 **
118706 **   (6) SEMI      We've seen the first semicolon in the ";END;" that occurs at
118707 **                 the end of a trigger definition.
118708 **
118709 **   (7) END       We've seen the ";END" of the ";END;" that occurs at the end
118710 **                 of a trigger difinition.
118711 **
118712 ** Transitions between states above are determined by tokens extracted
118713 ** from the input.  The following tokens are significant:
118714 **
118715 **   (0) tkSEMI      A semicolon.
118716 **   (1) tkWS        Whitespace.
118717 **   (2) tkOTHER     Any other SQL token.
118718 **   (3) tkEXPLAIN   The "explain" keyword.
118719 **   (4) tkCREATE    The "create" keyword.
118720 **   (5) tkTEMP      The "temp" or "temporary" keyword.
118721 **   (6) tkTRIGGER   The "trigger" keyword.
118722 **   (7) tkEND       The "end" keyword.
118723 **
118724 ** Whitespace never causes a state transition and is always ignored.
118725 ** This means that a SQL string of all whitespace is invalid.
118726 **
118727 ** If we compile with SQLITE_OMIT_TRIGGER, all of the computation needed
118728 ** to recognize the end of a trigger can be omitted.  All we have to do
118729 ** is look for a semicolon that is not part of an string or comment.
118730 */
118731 SQLITE_API int sqlite3_complete(const char *zSql){
118732   u8 state = 0;   /* Current state, using numbers defined in header comment */
118733   u8 token;       /* Value of the next token */
118734 
118735 #ifndef SQLITE_OMIT_TRIGGER
118736   /* A complex statement machine used to detect the end of a CREATE TRIGGER
118737   ** statement.  This is the normal case.
118738   */
118739   static const u8 trans[8][8] = {
118740                      /* Token:                                                */
118741      /* State:       **  SEMI  WS  OTHER  EXPLAIN  CREATE  TEMP  TRIGGER  END */
118742      /* 0 INVALID: */ {    1,  0,     2,       3,      4,    2,       2,   2, },
118743      /* 1   START: */ {    1,  1,     2,       3,      4,    2,       2,   2, },
118744      /* 2  NORMAL: */ {    1,  2,     2,       2,      2,    2,       2,   2, },
118745      /* 3 EXPLAIN: */ {    1,  3,     3,       2,      4,    2,       2,   2, },
118746      /* 4  CREATE: */ {    1,  4,     2,       2,      2,    4,       5,   2, },
118747      /* 5 TRIGGER: */ {    6,  5,     5,       5,      5,    5,       5,   5, },
118748      /* 6    SEMI: */ {    6,  6,     5,       5,      5,    5,       5,   7, },
118749      /* 7     END: */ {    1,  7,     5,       5,      5,    5,       5,   5, },
118750   };
118751 #else
118752   /* If triggers are not supported by this compile then the statement machine
118753   ** used to detect the end of a statement is much simplier
118754   */
118755   static const u8 trans[3][3] = {
118756                      /* Token:           */
118757      /* State:       **  SEMI  WS  OTHER */
118758      /* 0 INVALID: */ {    1,  0,     2, },
118759      /* 1   START: */ {    1,  1,     2, },
118760      /* 2  NORMAL: */ {    1,  2,     2, },
118761   };
118762 #endif /* SQLITE_OMIT_TRIGGER */
118763 
118764   while( *zSql ){
118765     switch( *zSql ){
118766       case ';': {  /* A semicolon */
118767         token = tkSEMI;
118768         break;
118769       }
118770       case ' ':
118771       case '\r':
118772       case '\t':
118773       case '\n':
118774       case '\f': {  /* White space is ignored */
118775         token = tkWS;
118776         break;
118777       }
118778       case '/': {   /* C-style comments */
118779         if( zSql[1]!='*' ){
118780           token = tkOTHER;
118781           break;
118782         }
118783         zSql += 2;
118784         while( zSql[0] && (zSql[0]!='*' || zSql[1]!='/') ){ zSql++; }
118785         if( zSql[0]==0 ) return 0;
118786         zSql++;
118787         token = tkWS;
118788         break;
118789       }
118790       case '-': {   /* SQL-style comments from "--" to end of line */
118791         if( zSql[1]!='-' ){
118792           token = tkOTHER;
118793           break;
118794         }
118795         while( *zSql && *zSql!='\n' ){ zSql++; }
118796         if( *zSql==0 ) return state==1;
118797         token = tkWS;
118798         break;
118799       }
118800       case '[': {   /* Microsoft-style identifiers in [...] */
118801         zSql++;
118802         while( *zSql && *zSql!=']' ){ zSql++; }
118803         if( *zSql==0 ) return 0;
118804         token = tkOTHER;
118805         break;
118806       }
118807       case '`':     /* Grave-accent quoted symbols used by MySQL */
118808       case '"':     /* single- and double-quoted strings */
118809       case '\'': {
118810         int c = *zSql;
118811         zSql++;
118812         while( *zSql && *zSql!=c ){ zSql++; }
118813         if( *zSql==0 ) return 0;
118814         token = tkOTHER;
118815         break;
118816       }
118817       default: {
118818 #ifdef SQLITE_EBCDIC
118819         unsigned char c;
118820 #endif
118821         if( IdChar((u8)*zSql) ){
118822           /* Keywords and unquoted identifiers */
118823           int nId;
118824           for(nId=1; IdChar(zSql[nId]); nId++){}
118825 #ifdef SQLITE_OMIT_TRIGGER
118826           token = tkOTHER;
118827 #else
118828           switch( *zSql ){
118829             case 'c': case 'C': {
118830               if( nId==6 && sqlite3StrNICmp(zSql, "create", 6)==0 ){
118831                 token = tkCREATE;
118832               }else{
118833                 token = tkOTHER;
118834               }
118835               break;
118836             }
118837             case 't': case 'T': {
118838               if( nId==7 && sqlite3StrNICmp(zSql, "trigger", 7)==0 ){
118839                 token = tkTRIGGER;
118840               }else if( nId==4 && sqlite3StrNICmp(zSql, "temp", 4)==0 ){
118841                 token = tkTEMP;
118842               }else if( nId==9 && sqlite3StrNICmp(zSql, "temporary", 9)==0 ){
118843                 token = tkTEMP;
118844               }else{
118845                 token = tkOTHER;
118846               }
118847               break;
118848             }
118849             case 'e':  case 'E': {
118850               if( nId==3 && sqlite3StrNICmp(zSql, "end", 3)==0 ){
118851                 token = tkEND;
118852               }else
118853 #ifndef SQLITE_OMIT_EXPLAIN
118854               if( nId==7 && sqlite3StrNICmp(zSql, "explain", 7)==0 ){
118855                 token = tkEXPLAIN;
118856               }else
118857 #endif
118858               {
118859                 token = tkOTHER;
118860               }
118861               break;
118862             }
118863             default: {
118864               token = tkOTHER;
118865               break;
118866             }
118867           }
118868 #endif /* SQLITE_OMIT_TRIGGER */
118869           zSql += nId-1;
118870         }else{
118871           /* Operators and special symbols */
118872           token = tkOTHER;
118873         }
118874         break;
118875       }
118876     }
118877     state = trans[state][token];
118878     zSql++;
118879   }
118880   return state==1;
118881 }
118882 
118883 #ifndef SQLITE_OMIT_UTF16
118884 /*
118885 ** This routine is the same as the sqlite3_complete() routine described
118886 ** above, except that the parameter is required to be UTF-16 encoded, not
118887 ** UTF-8.
118888 */
118889 SQLITE_API int sqlite3_complete16(const void *zSql){
118890   sqlite3_value *pVal;
118891   char const *zSql8;
118892   int rc = SQLITE_NOMEM;
118893 
118894 #ifndef SQLITE_OMIT_AUTOINIT
118895   rc = sqlite3_initialize();
118896   if( rc ) return rc;
118897 #endif
118898   pVal = sqlite3ValueNew(0);
118899   sqlite3ValueSetStr(pVal, -1, zSql, SQLITE_UTF16NATIVE, SQLITE_STATIC);
118900   zSql8 = sqlite3ValueText(pVal, SQLITE_UTF8);
118901   if( zSql8 ){
118902     rc = sqlite3_complete(zSql8);
118903   }else{
118904     rc = SQLITE_NOMEM;
118905   }
118906   sqlite3ValueFree(pVal);
118907   return sqlite3ApiExit(0, rc);
118908 }
118909 #endif /* SQLITE_OMIT_UTF16 */
118910 #endif /* SQLITE_OMIT_COMPLETE */
118911 
118912 /************** End of complete.c ********************************************/
118913 /************** Begin file main.c ********************************************/
118914 /*
118915 ** 2001 September 15
118916 **
118917 ** The author disclaims copyright to this source code.  In place of
118918 ** a legal notice, here is a blessing:
118919 **
118920 **    May you do good and not evil.
118921 **    May you find forgiveness for yourself and forgive others.
118922 **    May you share freely, never taking more than you give.
118923 **
118924 *************************************************************************
118925 ** Main file for the SQLite library.  The routines in this file
118926 ** implement the programmer interface to the library.  Routines in
118927 ** other files are for internal use by SQLite and should not be
118928 ** accessed by users of the library.
118929 */
118930 
118931 #ifdef SQLITE_ENABLE_FTS3
118932 /************** Include fts3.h in the middle of main.c ***********************/
118933 /************** Begin file fts3.h ********************************************/
118934 /*
118935 ** 2006 Oct 10
118936 **
118937 ** The author disclaims copyright to this source code.  In place of
118938 ** a legal notice, here is a blessing:
118939 **
118940 **    May you do good and not evil.
118941 **    May you find forgiveness for yourself and forgive others.
118942 **    May you share freely, never taking more than you give.
118943 **
118944 ******************************************************************************
118945 **
118946 ** This header file is used by programs that want to link against the
118947 ** FTS3 library.  All it does is declare the sqlite3Fts3Init() interface.
118948 */
118949 
118950 #if 0
118951 extern "C" {
118952 #endif  /* __cplusplus */
118953 
118954 SQLITE_PRIVATE int sqlite3Fts3Init(sqlite3 *db);
118955 
118956 #if 0
118957 }  /* extern "C" */
118958 #endif  /* __cplusplus */
118959 
118960 /************** End of fts3.h ************************************************/
118961 /************** Continuing where we left off in main.c ***********************/
118962 #endif
118963 #ifdef SQLITE_ENABLE_RTREE
118964 /************** Include rtree.h in the middle of main.c **********************/
118965 /************** Begin file rtree.h *******************************************/
118966 /*
118967 ** 2008 May 26
118968 **
118969 ** The author disclaims copyright to this source code.  In place of
118970 ** a legal notice, here is a blessing:
118971 **
118972 **    May you do good and not evil.
118973 **    May you find forgiveness for yourself and forgive others.
118974 **    May you share freely, never taking more than you give.
118975 **
118976 ******************************************************************************
118977 **
118978 ** This header file is used by programs that want to link against the
118979 ** RTREE library.  All it does is declare the sqlite3RtreeInit() interface.
118980 */
118981 
118982 #if 0
118983 extern "C" {
118984 #endif  /* __cplusplus */
118985 
118986 SQLITE_PRIVATE int sqlite3RtreeInit(sqlite3 *db);
118987 
118988 #if 0
118989 }  /* extern "C" */
118990 #endif  /* __cplusplus */
118991 
118992 /************** End of rtree.h ***********************************************/
118993 /************** Continuing where we left off in main.c ***********************/
118994 #endif
118995 #ifdef SQLITE_ENABLE_ICU
118996 /************** Include sqliteicu.h in the middle of main.c ******************/
118997 /************** Begin file sqliteicu.h ***************************************/
118998 /*
118999 ** 2008 May 26
119000 **
119001 ** The author disclaims copyright to this source code.  In place of
119002 ** a legal notice, here is a blessing:
119003 **
119004 **    May you do good and not evil.
119005 **    May you find forgiveness for yourself and forgive others.
119006 **    May you share freely, never taking more than you give.
119007 **
119008 ******************************************************************************
119009 **
119010 ** This header file is used by programs that want to link against the
119011 ** ICU extension.  All it does is declare the sqlite3IcuInit() interface.
119012 */
119013 
119014 #if 0
119015 extern "C" {
119016 #endif  /* __cplusplus */
119017 
119018 SQLITE_PRIVATE int sqlite3IcuInit(sqlite3 *db);
119019 
119020 #if 0
119021 }  /* extern "C" */
119022 #endif  /* __cplusplus */
119023 
119024 
119025 /************** End of sqliteicu.h *******************************************/
119026 /************** Continuing where we left off in main.c ***********************/
119027 #endif
119028 
119029 #ifndef SQLITE_AMALGAMATION
119030 /* IMPLEMENTATION-OF: R-46656-45156 The sqlite3_version[] string constant
119031 ** contains the text of SQLITE_VERSION macro. 
119032 */
119033 SQLITE_API const char sqlite3_version[] = SQLITE_VERSION;
119034 #endif
119035 
119036 /* IMPLEMENTATION-OF: R-53536-42575 The sqlite3_libversion() function returns
119037 ** a pointer to the to the sqlite3_version[] string constant. 
119038 */
119039 SQLITE_API const char *sqlite3_libversion(void){ return sqlite3_version; }
119040 
119041 /* IMPLEMENTATION-OF: R-63124-39300 The sqlite3_sourceid() function returns a
119042 ** pointer to a string constant whose value is the same as the
119043 ** SQLITE_SOURCE_ID C preprocessor macro. 
119044 */
119045 SQLITE_API const char *sqlite3_sourceid(void){ return SQLITE_SOURCE_ID; }
119046 
119047 /* IMPLEMENTATION-OF: R-35210-63508 The sqlite3_libversion_number() function
119048 ** returns an integer equal to SQLITE_VERSION_NUMBER.
119049 */
119050 SQLITE_API int sqlite3_libversion_number(void){ return SQLITE_VERSION_NUMBER; }
119051 
119052 /* IMPLEMENTATION-OF: R-20790-14025 The sqlite3_threadsafe() function returns
119053 ** zero if and only if SQLite was compiled with mutexing code omitted due to
119054 ** the SQLITE_THREADSAFE compile-time option being set to 0.
119055 */
119056 SQLITE_API int sqlite3_threadsafe(void){ return SQLITE_THREADSAFE; }
119057 
119058 #if !defined(SQLITE_OMIT_TRACE) && defined(SQLITE_ENABLE_IOTRACE)
119059 /*
119060 ** If the following function pointer is not NULL and if
119061 ** SQLITE_ENABLE_IOTRACE is enabled, then messages describing
119062 ** I/O active are written using this function.  These messages
119063 ** are intended for debugging activity only.
119064 */
119065 SQLITE_PRIVATE void (*sqlite3IoTrace)(const char*, ...) = 0;
119066 #endif
119067 
119068 /*
119069 ** If the following global variable points to a string which is the
119070 ** name of a directory, then that directory will be used to store
119071 ** temporary files.
119072 **
119073 ** See also the "PRAGMA temp_store_directory" SQL command.
119074 */
119075 SQLITE_API char *sqlite3_temp_directory = 0;
119076 
119077 /*
119078 ** If the following global variable points to a string which is the
119079 ** name of a directory, then that directory will be used to store
119080 ** all database files specified with a relative pathname.
119081 **
119082 ** See also the "PRAGMA data_store_directory" SQL command.
119083 */
119084 SQLITE_API char *sqlite3_data_directory = 0;
119085 
119086 /*
119087 ** Initialize SQLite.  
119088 **
119089 ** This routine must be called to initialize the memory allocation,
119090 ** VFS, and mutex subsystems prior to doing any serious work with
119091 ** SQLite.  But as long as you do not compile with SQLITE_OMIT_AUTOINIT
119092 ** this routine will be called automatically by key routines such as
119093 ** sqlite3_open().  
119094 **
119095 ** This routine is a no-op except on its very first call for the process,
119096 ** or for the first call after a call to sqlite3_shutdown.
119097 **
119098 ** The first thread to call this routine runs the initialization to
119099 ** completion.  If subsequent threads call this routine before the first
119100 ** thread has finished the initialization process, then the subsequent
119101 ** threads must block until the first thread finishes with the initialization.
119102 **
119103 ** The first thread might call this routine recursively.  Recursive
119104 ** calls to this routine should not block, of course.  Otherwise the
119105 ** initialization process would never complete.
119106 **
119107 ** Let X be the first thread to enter this routine.  Let Y be some other
119108 ** thread.  Then while the initial invocation of this routine by X is
119109 ** incomplete, it is required that:
119110 **
119111 **    *  Calls to this routine from Y must block until the outer-most
119112 **       call by X completes.
119113 **
119114 **    *  Recursive calls to this routine from thread X return immediately
119115 **       without blocking.
119116 */
119117 SQLITE_API int sqlite3_initialize(void){
119118   MUTEX_LOGIC( sqlite3_mutex *pMaster; )       /* The main static mutex */
119119   int rc;                                      /* Result code */
119120 #ifdef SQLITE_EXTRA_INIT
119121   int bRunExtraInit = 0;                       /* Extra initialization needed */
119122 #endif
119123 
119124 #ifdef SQLITE_OMIT_WSD
119125   rc = sqlite3_wsd_init(4096, 24);
119126   if( rc!=SQLITE_OK ){
119127     return rc;
119128   }
119129 #endif
119130 
119131   /* If SQLite is already completely initialized, then this call
119132   ** to sqlite3_initialize() should be a no-op.  But the initialization
119133   ** must be complete.  So isInit must not be set until the very end
119134   ** of this routine.
119135   */
119136   if( sqlite3GlobalConfig.isInit ) return SQLITE_OK;
119137 
119138 #ifdef SQLITE_ENABLE_SQLLOG
119139   {
119140     extern void sqlite3_init_sqllog(void);
119141     sqlite3_init_sqllog();
119142   }
119143 #endif
119144 
119145   /* Make sure the mutex subsystem is initialized.  If unable to 
119146   ** initialize the mutex subsystem, return early with the error.
119147   ** If the system is so sick that we are unable to allocate a mutex,
119148   ** there is not much SQLite is going to be able to do.
119149   **
119150   ** The mutex subsystem must take care of serializing its own
119151   ** initialization.
119152   */
119153   rc = sqlite3MutexInit();
119154   if( rc ) return rc;
119155 
119156   /* Initialize the malloc() system and the recursive pInitMutex mutex.
119157   ** This operation is protected by the STATIC_MASTER mutex.  Note that
119158   ** MutexAlloc() is called for a static mutex prior to initializing the
119159   ** malloc subsystem - this implies that the allocation of a static
119160   ** mutex must not require support from the malloc subsystem.
119161   */
119162   MUTEX_LOGIC( pMaster = sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER); )
119163   sqlite3_mutex_enter(pMaster);
119164   sqlite3GlobalConfig.isMutexInit = 1;
119165   if( !sqlite3GlobalConfig.isMallocInit ){
119166     rc = sqlite3MallocInit();
119167   }
119168   if( rc==SQLITE_OK ){
119169     sqlite3GlobalConfig.isMallocInit = 1;
119170     if( !sqlite3GlobalConfig.pInitMutex ){
119171       sqlite3GlobalConfig.pInitMutex =
119172            sqlite3MutexAlloc(SQLITE_MUTEX_RECURSIVE);
119173       if( sqlite3GlobalConfig.bCoreMutex && !sqlite3GlobalConfig.pInitMutex ){
119174         rc = SQLITE_NOMEM;
119175       }
119176     }
119177   }
119178   if( rc==SQLITE_OK ){
119179     sqlite3GlobalConfig.nRefInitMutex++;
119180   }
119181   sqlite3_mutex_leave(pMaster);
119182 
119183   /* If rc is not SQLITE_OK at this point, then either the malloc
119184   ** subsystem could not be initialized or the system failed to allocate
119185   ** the pInitMutex mutex. Return an error in either case.  */
119186   if( rc!=SQLITE_OK ){
119187     return rc;
119188   }
119189 
119190   /* Do the rest of the initialization under the recursive mutex so
119191   ** that we will be able to handle recursive calls into
119192   ** sqlite3_initialize().  The recursive calls normally come through
119193   ** sqlite3_os_init() when it invokes sqlite3_vfs_register(), but other
119194   ** recursive calls might also be possible.
119195   **
119196   ** IMPLEMENTATION-OF: R-00140-37445 SQLite automatically serializes calls
119197   ** to the xInit method, so the xInit method need not be threadsafe.
119198   **
119199   ** The following mutex is what serializes access to the appdef pcache xInit
119200   ** methods.  The sqlite3_pcache_methods.xInit() all is embedded in the
119201   ** call to sqlite3PcacheInitialize().
119202   */
119203   sqlite3_mutex_enter(sqlite3GlobalConfig.pInitMutex);
119204   if( sqlite3GlobalConfig.isInit==0 && sqlite3GlobalConfig.inProgress==0 ){
119205     FuncDefHash *pHash = &GLOBAL(FuncDefHash, sqlite3GlobalFunctions);
119206     sqlite3GlobalConfig.inProgress = 1;
119207     memset(pHash, 0, sizeof(sqlite3GlobalFunctions));
119208     sqlite3RegisterGlobalFunctions();
119209     if( sqlite3GlobalConfig.isPCacheInit==0 ){
119210       rc = sqlite3PcacheInitialize();
119211     }
119212     if( rc==SQLITE_OK ){
119213       sqlite3GlobalConfig.isPCacheInit = 1;
119214       rc = sqlite3OsInit();
119215     }
119216     if( rc==SQLITE_OK ){
119217       sqlite3PCacheBufferSetup( sqlite3GlobalConfig.pPage, 
119218           sqlite3GlobalConfig.szPage, sqlite3GlobalConfig.nPage);
119219       sqlite3GlobalConfig.isInit = 1;
119220 #ifdef SQLITE_EXTRA_INIT
119221       bRunExtraInit = 1;
119222 #endif
119223     }
119224     sqlite3GlobalConfig.inProgress = 0;
119225   }
119226   sqlite3_mutex_leave(sqlite3GlobalConfig.pInitMutex);
119227 
119228   /* Go back under the static mutex and clean up the recursive
119229   ** mutex to prevent a resource leak.
119230   */
119231   sqlite3_mutex_enter(pMaster);
119232   sqlite3GlobalConfig.nRefInitMutex--;
119233   if( sqlite3GlobalConfig.nRefInitMutex<=0 ){
119234     assert( sqlite3GlobalConfig.nRefInitMutex==0 );
119235     sqlite3_mutex_free(sqlite3GlobalConfig.pInitMutex);
119236     sqlite3GlobalConfig.pInitMutex = 0;
119237   }
119238   sqlite3_mutex_leave(pMaster);
119239 
119240   /* The following is just a sanity check to make sure SQLite has
119241   ** been compiled correctly.  It is important to run this code, but
119242   ** we don't want to run it too often and soak up CPU cycles for no
119243   ** reason.  So we run it once during initialization.
119244   */
119245 #ifndef NDEBUG
119246 #ifndef SQLITE_OMIT_FLOATING_POINT
119247   /* This section of code's only "output" is via assert() statements. */
119248   if ( rc==SQLITE_OK ){
119249     u64 x = (((u64)1)<<63)-1;
119250     double y;
119251     assert(sizeof(x)==8);
119252     assert(sizeof(x)==sizeof(y));
119253     memcpy(&y, &x, 8);
119254     assert( sqlite3IsNaN(y) );
119255   }
119256 #endif
119257 #endif
119258 
119259   /* Do extra initialization steps requested by the SQLITE_EXTRA_INIT
119260   ** compile-time option.
119261   */
119262 #ifdef SQLITE_EXTRA_INIT
119263   if( bRunExtraInit ){
119264     int SQLITE_EXTRA_INIT(const char*);
119265     rc = SQLITE_EXTRA_INIT(0);
119266   }
119267 #endif
119268 
119269   return rc;
119270 }
119271 
119272 /*
119273 ** Undo the effects of sqlite3_initialize().  Must not be called while
119274 ** there are outstanding database connections or memory allocations or
119275 ** while any part of SQLite is otherwise in use in any thread.  This
119276 ** routine is not threadsafe.  But it is safe to invoke this routine
119277 ** on when SQLite is already shut down.  If SQLite is already shut down
119278 ** when this routine is invoked, then this routine is a harmless no-op.
119279 */
119280 SQLITE_API int sqlite3_shutdown(void){
119281   if( sqlite3GlobalConfig.isInit ){
119282 #ifdef SQLITE_EXTRA_SHUTDOWN
119283     void SQLITE_EXTRA_SHUTDOWN(void);
119284     SQLITE_EXTRA_SHUTDOWN();
119285 #endif
119286     sqlite3_os_end();
119287     sqlite3_reset_auto_extension();
119288     sqlite3GlobalConfig.isInit = 0;
119289   }
119290   if( sqlite3GlobalConfig.isPCacheInit ){
119291     sqlite3PcacheShutdown();
119292     sqlite3GlobalConfig.isPCacheInit = 0;
119293   }
119294   if( sqlite3GlobalConfig.isMallocInit ){
119295     sqlite3MallocEnd();
119296     sqlite3GlobalConfig.isMallocInit = 0;
119297 
119298 #ifndef SQLITE_OMIT_SHUTDOWN_DIRECTORIES
119299     /* The heap subsystem has now been shutdown and these values are supposed
119300     ** to be NULL or point to memory that was obtained from sqlite3_malloc(),
119301     ** which would rely on that heap subsystem; therefore, make sure these
119302     ** values cannot refer to heap memory that was just invalidated when the
119303     ** heap subsystem was shutdown.  This is only done if the current call to
119304     ** this function resulted in the heap subsystem actually being shutdown.
119305     */
119306     sqlite3_data_directory = 0;
119307     sqlite3_temp_directory = 0;
119308 #endif
119309   }
119310   if( sqlite3GlobalConfig.isMutexInit ){
119311     sqlite3MutexEnd();
119312     sqlite3GlobalConfig.isMutexInit = 0;
119313   }
119314 
119315   return SQLITE_OK;
119316 }
119317 
119318 /*
119319 ** This API allows applications to modify the global configuration of
119320 ** the SQLite library at run-time.
119321 **
119322 ** This routine should only be called when there are no outstanding
119323 ** database connections or memory allocations.  This routine is not
119324 ** threadsafe.  Failure to heed these warnings can lead to unpredictable
119325 ** behavior.
119326 */
119327 SQLITE_API int sqlite3_config(int op, ...){
119328   va_list ap;
119329   int rc = SQLITE_OK;
119330 
119331   /* sqlite3_config() shall return SQLITE_MISUSE if it is invoked while
119332   ** the SQLite library is in use. */
119333   if( sqlite3GlobalConfig.isInit ) return SQLITE_MISUSE_BKPT;
119334 
119335   va_start(ap, op);
119336   switch( op ){
119337 
119338     /* Mutex configuration options are only available in a threadsafe
119339     ** compile. 
119340     */
119341 #if defined(SQLITE_THREADSAFE) && SQLITE_THREADSAFE>0
119342     case SQLITE_CONFIG_SINGLETHREAD: {
119343       /* Disable all mutexing */
119344       sqlite3GlobalConfig.bCoreMutex = 0;
119345       sqlite3GlobalConfig.bFullMutex = 0;
119346       break;
119347     }
119348     case SQLITE_CONFIG_MULTITHREAD: {
119349       /* Disable mutexing of database connections */
119350       /* Enable mutexing of core data structures */
119351       sqlite3GlobalConfig.bCoreMutex = 1;
119352       sqlite3GlobalConfig.bFullMutex = 0;
119353       break;
119354     }
119355     case SQLITE_CONFIG_SERIALIZED: {
119356       /* Enable all mutexing */
119357       sqlite3GlobalConfig.bCoreMutex = 1;
119358       sqlite3GlobalConfig.bFullMutex = 1;
119359       break;
119360     }
119361     case SQLITE_CONFIG_MUTEX: {
119362       /* Specify an alternative mutex implementation */
119363       sqlite3GlobalConfig.mutex = *va_arg(ap, sqlite3_mutex_methods*);
119364       break;
119365     }
119366     case SQLITE_CONFIG_GETMUTEX: {
119367       /* Retrieve the current mutex implementation */
119368       *va_arg(ap, sqlite3_mutex_methods*) = sqlite3GlobalConfig.mutex;
119369       break;
119370     }
119371 #endif
119372 
119373 
119374     case SQLITE_CONFIG_MALLOC: {
119375       /* Specify an alternative malloc implementation */
119376       sqlite3GlobalConfig.m = *va_arg(ap, sqlite3_mem_methods*);
119377       break;
119378     }
119379     case SQLITE_CONFIG_GETMALLOC: {
119380       /* Retrieve the current malloc() implementation */
119381       if( sqlite3GlobalConfig.m.xMalloc==0 ) sqlite3MemSetDefault();
119382       *va_arg(ap, sqlite3_mem_methods*) = sqlite3GlobalConfig.m;
119383       break;
119384     }
119385     case SQLITE_CONFIG_MEMSTATUS: {
119386       /* Enable or disable the malloc status collection */
119387       sqlite3GlobalConfig.bMemstat = va_arg(ap, int);
119388       break;
119389     }
119390     case SQLITE_CONFIG_SCRATCH: {
119391       /* Designate a buffer for scratch memory space */
119392       sqlite3GlobalConfig.pScratch = va_arg(ap, void*);
119393       sqlite3GlobalConfig.szScratch = va_arg(ap, int);
119394       sqlite3GlobalConfig.nScratch = va_arg(ap, int);
119395       break;
119396     }
119397     case SQLITE_CONFIG_PAGECACHE: {
119398       /* Designate a buffer for page cache memory space */
119399       sqlite3GlobalConfig.pPage = va_arg(ap, void*);
119400       sqlite3GlobalConfig.szPage = va_arg(ap, int);
119401       sqlite3GlobalConfig.nPage = va_arg(ap, int);
119402       break;
119403     }
119404 
119405     case SQLITE_CONFIG_PCACHE: {
119406       /* no-op */
119407       break;
119408     }
119409     case SQLITE_CONFIG_GETPCACHE: {
119410       /* now an error */
119411       rc = SQLITE_ERROR;
119412       break;
119413     }
119414 
119415     case SQLITE_CONFIG_PCACHE2: {
119416       /* Specify an alternative page cache implementation */
119417       sqlite3GlobalConfig.pcache2 = *va_arg(ap, sqlite3_pcache_methods2*);
119418       break;
119419     }
119420     case SQLITE_CONFIG_GETPCACHE2: {
119421       if( sqlite3GlobalConfig.pcache2.xInit==0 ){
119422         sqlite3PCacheSetDefault();
119423       }
119424       *va_arg(ap, sqlite3_pcache_methods2*) = sqlite3GlobalConfig.pcache2;
119425       break;
119426     }
119427 
119428 #if defined(SQLITE_ENABLE_MEMSYS3) || defined(SQLITE_ENABLE_MEMSYS5)
119429     case SQLITE_CONFIG_HEAP: {
119430       /* Designate a buffer for heap memory space */
119431       sqlite3GlobalConfig.pHeap = va_arg(ap, void*);
119432       sqlite3GlobalConfig.nHeap = va_arg(ap, int);
119433       sqlite3GlobalConfig.mnReq = va_arg(ap, int);
119434 
119435       if( sqlite3GlobalConfig.mnReq<1 ){
119436         sqlite3GlobalConfig.mnReq = 1;
119437       }else if( sqlite3GlobalConfig.mnReq>(1<<12) ){
119438         /* cap min request size at 2^12 */
119439         sqlite3GlobalConfig.mnReq = (1<<12);
119440       }
119441 
119442       if( sqlite3GlobalConfig.pHeap==0 ){
119443         /* If the heap pointer is NULL, then restore the malloc implementation
119444         ** back to NULL pointers too.  This will cause the malloc to go
119445         ** back to its default implementation when sqlite3_initialize() is
119446         ** run.
119447         */
119448         memset(&sqlite3GlobalConfig.m, 0, sizeof(sqlite3GlobalConfig.m));
119449       }else{
119450         /* The heap pointer is not NULL, then install one of the
119451         ** mem5.c/mem3.c methods.  The enclosing #if guarantees at
119452         ** least one of these methods is currently enabled.
119453         */
119454 #ifdef SQLITE_ENABLE_MEMSYS3
119455         sqlite3GlobalConfig.m = *sqlite3MemGetMemsys3();
119456 #endif
119457 #ifdef SQLITE_ENABLE_MEMSYS5
119458         sqlite3GlobalConfig.m = *sqlite3MemGetMemsys5();
119459 #endif
119460       }
119461       break;
119462     }
119463 #endif
119464 
119465     case SQLITE_CONFIG_LOOKASIDE: {
119466       sqlite3GlobalConfig.szLookaside = va_arg(ap, int);
119467       sqlite3GlobalConfig.nLookaside = va_arg(ap, int);
119468       break;
119469     }
119470     
119471     /* Record a pointer to the logger function and its first argument.
119472     ** The default is NULL.  Logging is disabled if the function pointer is
119473     ** NULL.
119474     */
119475     case SQLITE_CONFIG_LOG: {
119476       /* MSVC is picky about pulling func ptrs from va lists.
119477       ** http://support.microsoft.com/kb/47961
119478       ** sqlite3GlobalConfig.xLog = va_arg(ap, void(*)(void*,int,const char*));
119479       */
119480       typedef void(*LOGFUNC_t)(void*,int,const char*);
119481       sqlite3GlobalConfig.xLog = va_arg(ap, LOGFUNC_t);
119482       sqlite3GlobalConfig.pLogArg = va_arg(ap, void*);
119483       break;
119484     }
119485 
119486     case SQLITE_CONFIG_URI: {
119487       sqlite3GlobalConfig.bOpenUri = va_arg(ap, int);
119488       break;
119489     }
119490 
119491     case SQLITE_CONFIG_COVERING_INDEX_SCAN: {
119492       sqlite3GlobalConfig.bUseCis = va_arg(ap, int);
119493       break;
119494     }
119495 
119496 #ifdef SQLITE_ENABLE_SQLLOG
119497     case SQLITE_CONFIG_SQLLOG: {
119498       typedef void(*SQLLOGFUNC_t)(void*, sqlite3*, const char*, int);
119499       sqlite3GlobalConfig.xSqllog = va_arg(ap, SQLLOGFUNC_t);
119500       sqlite3GlobalConfig.pSqllogArg = va_arg(ap, void *);
119501       break;
119502     }
119503 #endif
119504 
119505     case SQLITE_CONFIG_MMAP_SIZE: {
119506       sqlite3_int64 szMmap = va_arg(ap, sqlite3_int64);
119507       sqlite3_int64 mxMmap = va_arg(ap, sqlite3_int64);
119508       if( mxMmap<0 || mxMmap>SQLITE_MAX_MMAP_SIZE ){
119509         mxMmap = SQLITE_MAX_MMAP_SIZE;
119510       }
119511       sqlite3GlobalConfig.mxMmap = mxMmap;
119512       if( szMmap<0 ) szMmap = SQLITE_DEFAULT_MMAP_SIZE;
119513       if( szMmap>mxMmap) szMmap = mxMmap;
119514       sqlite3GlobalConfig.szMmap = szMmap;
119515       break;
119516     }
119517 
119518 #if SQLITE_OS_WIN && defined(SQLITE_WIN32_MALLOC)
119519     case SQLITE_CONFIG_WIN32_HEAPSIZE: {
119520       sqlite3GlobalConfig.nHeap = va_arg(ap, int);
119521       break;
119522     }
119523 #endif
119524 
119525     default: {
119526       rc = SQLITE_ERROR;
119527       break;
119528     }
119529   }
119530   va_end(ap);
119531   return rc;
119532 }
119533 
119534 /*
119535 ** Set up the lookaside buffers for a database connection.
119536 ** Return SQLITE_OK on success.  
119537 ** If lookaside is already active, return SQLITE_BUSY.
119538 **
119539 ** The sz parameter is the number of bytes in each lookaside slot.
119540 ** The cnt parameter is the number of slots.  If pStart is NULL the
119541 ** space for the lookaside memory is obtained from sqlite3_malloc().
119542 ** If pStart is not NULL then it is sz*cnt bytes of memory to use for
119543 ** the lookaside memory.
119544 */
119545 static int setupLookaside(sqlite3 *db, void *pBuf, int sz, int cnt){
119546   void *pStart;
119547   if( db->lookaside.nOut ){
119548     return SQLITE_BUSY;
119549   }
119550   /* Free any existing lookaside buffer for this handle before
119551   ** allocating a new one so we don't have to have space for 
119552   ** both at the same time.
119553   */
119554   if( db->lookaside.bMalloced ){
119555     sqlite3_free(db->lookaside.pStart);
119556   }
119557   /* The size of a lookaside slot after ROUNDDOWN8 needs to be larger
119558   ** than a pointer to be useful.
119559   */
119560   sz = ROUNDDOWN8(sz);  /* IMP: R-33038-09382 */
119561   if( sz<=(int)sizeof(LookasideSlot*) ) sz = 0;
119562   if( cnt<0 ) cnt = 0;
119563   if( sz==0 || cnt==0 ){
119564     sz = 0;
119565     pStart = 0;
119566   }else if( pBuf==0 ){
119567     sqlite3BeginBenignMalloc();
119568     pStart = sqlite3Malloc( sz*cnt );  /* IMP: R-61949-35727 */
119569     sqlite3EndBenignMalloc();
119570     if( pStart ) cnt = sqlite3MallocSize(pStart)/sz;
119571   }else{
119572     pStart = pBuf;
119573   }
119574   db->lookaside.pStart = pStart;
119575   db->lookaside.pFree = 0;
119576   db->lookaside.sz = (u16)sz;
119577   if( pStart ){
119578     int i;
119579     LookasideSlot *p;
119580     assert( sz > (int)sizeof(LookasideSlot*) );
119581     p = (LookasideSlot*)pStart;
119582     for(i=cnt-1; i>=0; i--){
119583       p->pNext = db->lookaside.pFree;
119584       db->lookaside.pFree = p;
119585       p = (LookasideSlot*)&((u8*)p)[sz];
119586     }
119587     db->lookaside.pEnd = p;
119588     db->lookaside.bEnabled = 1;
119589     db->lookaside.bMalloced = pBuf==0 ?1:0;
119590   }else{
119591     db->lookaside.pEnd = 0;
119592     db->lookaside.bEnabled = 0;
119593     db->lookaside.bMalloced = 0;
119594   }
119595   return SQLITE_OK;
119596 }
119597 
119598 /*
119599 ** Return the mutex associated with a database connection.
119600 */
119601 SQLITE_API sqlite3_mutex *sqlite3_db_mutex(sqlite3 *db){
119602   return db->mutex;
119603 }
119604 
119605 /*
119606 ** Free up as much memory as we can from the given database
119607 ** connection.
119608 */
119609 SQLITE_API int sqlite3_db_release_memory(sqlite3 *db){
119610   int i;
119611   sqlite3_mutex_enter(db->mutex);
119612   sqlite3BtreeEnterAll(db);
119613   for(i=0; i<db->nDb; i++){
119614     Btree *pBt = db->aDb[i].pBt;
119615     if( pBt ){
119616       Pager *pPager = sqlite3BtreePager(pBt);
119617       sqlite3PagerShrink(pPager);
119618     }
119619   }
119620   sqlite3BtreeLeaveAll(db);
119621   sqlite3_mutex_leave(db->mutex);
119622   return SQLITE_OK;
119623 }
119624 
119625 /*
119626 ** Configuration settings for an individual database connection
119627 */
119628 SQLITE_API int sqlite3_db_config(sqlite3 *db, int op, ...){
119629   va_list ap;
119630   int rc;
119631   va_start(ap, op);
119632   switch( op ){
119633     case SQLITE_DBCONFIG_LOOKASIDE: {
119634       void *pBuf = va_arg(ap, void*); /* IMP: R-26835-10964 */
119635       int sz = va_arg(ap, int);       /* IMP: R-47871-25994 */
119636       int cnt = va_arg(ap, int);      /* IMP: R-04460-53386 */
119637       rc = setupLookaside(db, pBuf, sz, cnt);
119638       break;
119639     }
119640     default: {
119641       static const struct {
119642         int op;      /* The opcode */
119643         u32 mask;    /* Mask of the bit in sqlite3.flags to set/clear */
119644       } aFlagOp[] = {
119645         { SQLITE_DBCONFIG_ENABLE_FKEY,    SQLITE_ForeignKeys    },
119646         { SQLITE_DBCONFIG_ENABLE_TRIGGER, SQLITE_EnableTrigger  },
119647       };
119648       unsigned int i;
119649       rc = SQLITE_ERROR; /* IMP: R-42790-23372 */
119650       for(i=0; i<ArraySize(aFlagOp); i++){
119651         if( aFlagOp[i].op==op ){
119652           int onoff = va_arg(ap, int);
119653           int *pRes = va_arg(ap, int*);
119654           int oldFlags = db->flags;
119655           if( onoff>0 ){
119656             db->flags |= aFlagOp[i].mask;
119657           }else if( onoff==0 ){
119658             db->flags &= ~aFlagOp[i].mask;
119659           }
119660           if( oldFlags!=db->flags ){
119661             sqlite3ExpirePreparedStatements(db);
119662           }
119663           if( pRes ){
119664             *pRes = (db->flags & aFlagOp[i].mask)!=0;
119665           }
119666           rc = SQLITE_OK;
119667           break;
119668         }
119669       }
119670       break;
119671     }
119672   }
119673   va_end(ap);
119674   return rc;
119675 }
119676 
119677 
119678 /*
119679 ** Return true if the buffer z[0..n-1] contains all spaces.
119680 */
119681 static int allSpaces(const char *z, int n){
119682   while( n>0 && z[n-1]==' ' ){ n--; }
119683   return n==0;
119684 }
119685 
119686 /*
119687 ** This is the default collating function named "BINARY" which is always
119688 ** available.
119689 **
119690 ** If the padFlag argument is not NULL then space padding at the end
119691 ** of strings is ignored.  This implements the RTRIM collation.
119692 */
119693 static int binCollFunc(
119694   void *padFlag,
119695   int nKey1, const void *pKey1,
119696   int nKey2, const void *pKey2
119697 ){
119698   int rc, n;
119699   n = nKey1<nKey2 ? nKey1 : nKey2;
119700   rc = memcmp(pKey1, pKey2, n);
119701   if( rc==0 ){
119702     if( padFlag
119703      && allSpaces(((char*)pKey1)+n, nKey1-n)
119704      && allSpaces(((char*)pKey2)+n, nKey2-n)
119705     ){
119706       /* Leave rc unchanged at 0 */
119707     }else{
119708       rc = nKey1 - nKey2;
119709     }
119710   }
119711   return rc;
119712 }
119713 
119714 /*
119715 ** Another built-in collating sequence: NOCASE. 
119716 **
119717 ** This collating sequence is intended to be used for "case independent
119718 ** comparison". SQLite's knowledge of upper and lower case equivalents
119719 ** extends only to the 26 characters used in the English language.
119720 **
119721 ** At the moment there is only a UTF-8 implementation.
119722 */
119723 static int nocaseCollatingFunc(
119724   void *NotUsed,
119725   int nKey1, const void *pKey1,
119726   int nKey2, const void *pKey2
119727 ){
119728   int r = sqlite3StrNICmp(
119729       (const char *)pKey1, (const char *)pKey2, (nKey1<nKey2)?nKey1:nKey2);
119730   UNUSED_PARAMETER(NotUsed);
119731   if( 0==r ){
119732     r = nKey1-nKey2;
119733   }
119734   return r;
119735 }
119736 
119737 /*
119738 ** Return the ROWID of the most recent insert
119739 */
119740 SQLITE_API sqlite_int64 sqlite3_last_insert_rowid(sqlite3 *db){
119741   return db->lastRowid;
119742 }
119743 
119744 /*
119745 ** Return the number of changes in the most recent call to sqlite3_exec().
119746 */
119747 SQLITE_API int sqlite3_changes(sqlite3 *db){
119748   return db->nChange;
119749 }
119750 
119751 /*
119752 ** Return the number of changes since the database handle was opened.
119753 */
119754 SQLITE_API int sqlite3_total_changes(sqlite3 *db){
119755   return db->nTotalChange;
119756 }
119757 
119758 /*
119759 ** Close all open savepoints. This function only manipulates fields of the
119760 ** database handle object, it does not close any savepoints that may be open
119761 ** at the b-tree/pager level.
119762 */
119763 SQLITE_PRIVATE void sqlite3CloseSavepoints(sqlite3 *db){
119764   while( db->pSavepoint ){
119765     Savepoint *pTmp = db->pSavepoint;
119766     db->pSavepoint = pTmp->pNext;
119767     sqlite3DbFree(db, pTmp);
119768   }
119769   db->nSavepoint = 0;
119770   db->nStatement = 0;
119771   db->isTransactionSavepoint = 0;
119772 }
119773 
119774 /*
119775 ** Invoke the destructor function associated with FuncDef p, if any. Except,
119776 ** if this is not the last copy of the function, do not invoke it. Multiple
119777 ** copies of a single function are created when create_function() is called
119778 ** with SQLITE_ANY as the encoding.
119779 */
119780 static void functionDestroy(sqlite3 *db, FuncDef *p){
119781   FuncDestructor *pDestructor = p->pDestructor;
119782   if( pDestructor ){
119783     pDestructor->nRef--;
119784     if( pDestructor->nRef==0 ){
119785       pDestructor->xDestroy(pDestructor->pUserData);
119786       sqlite3DbFree(db, pDestructor);
119787     }
119788   }
119789 }
119790 
119791 /*
119792 ** Disconnect all sqlite3_vtab objects that belong to database connection
119793 ** db. This is called when db is being closed.
119794 */
119795 static void disconnectAllVtab(sqlite3 *db){
119796 #ifndef SQLITE_OMIT_VIRTUALTABLE
119797   int i;
119798   sqlite3BtreeEnterAll(db);
119799   for(i=0; i<db->nDb; i++){
119800     Schema *pSchema = db->aDb[i].pSchema;
119801     if( db->aDb[i].pSchema ){
119802       HashElem *p;
119803       for(p=sqliteHashFirst(&pSchema->tblHash); p; p=sqliteHashNext(p)){
119804         Table *pTab = (Table *)sqliteHashData(p);
119805         if( IsVirtual(pTab) ) sqlite3VtabDisconnect(db, pTab);
119806       }
119807     }
119808   }
119809   sqlite3BtreeLeaveAll(db);
119810 #else
119811   UNUSED_PARAMETER(db);
119812 #endif
119813 }
119814 
119815 /*
119816 ** Return TRUE if database connection db has unfinalized prepared
119817 ** statements or unfinished sqlite3_backup objects.  
119818 */
119819 static int connectionIsBusy(sqlite3 *db){
119820   int j;
119821   assert( sqlite3_mutex_held(db->mutex) );
119822   if( db->pVdbe ) return 1;
119823   for(j=0; j<db->nDb; j++){
119824     Btree *pBt = db->aDb[j].pBt;
119825     if( pBt && sqlite3BtreeIsInBackup(pBt) ) return 1;
119826   }
119827   return 0;
119828 }
119829 
119830 /*
119831 ** Close an existing SQLite database
119832 */
119833 static int sqlite3Close(sqlite3 *db, int forceZombie){
119834   if( !db ){
119835     return SQLITE_OK;
119836   }
119837   if( !sqlite3SafetyCheckSickOrOk(db) ){
119838     return SQLITE_MISUSE_BKPT;
119839   }
119840   sqlite3_mutex_enter(db->mutex);
119841 
119842   /* Force xDisconnect calls on all virtual tables */
119843   disconnectAllVtab(db);
119844 
119845   /* If a transaction is open, the disconnectAllVtab() call above
119846   ** will not have called the xDisconnect() method on any virtual
119847   ** tables in the db->aVTrans[] array. The following sqlite3VtabRollback()
119848   ** call will do so. We need to do this before the check for active
119849   ** SQL statements below, as the v-table implementation may be storing
119850   ** some prepared statements internally.
119851   */
119852   sqlite3VtabRollback(db);
119853 
119854   /* Legacy behavior (sqlite3_close() behavior) is to return
119855   ** SQLITE_BUSY if the connection can not be closed immediately.
119856   */
119857   if( !forceZombie && connectionIsBusy(db) ){
119858     sqlite3Error(db, SQLITE_BUSY, "unable to close due to unfinalized "
119859        "statements or unfinished backups");
119860     sqlite3_mutex_leave(db->mutex);
119861     return SQLITE_BUSY;
119862   }
119863 
119864 #ifdef SQLITE_ENABLE_SQLLOG
119865   if( sqlite3GlobalConfig.xSqllog ){
119866     /* Closing the handle. Fourth parameter is passed the value 2. */
119867     sqlite3GlobalConfig.xSqllog(sqlite3GlobalConfig.pSqllogArg, db, 0, 2);
119868   }
119869 #endif
119870 
119871   /* Convert the connection into a zombie and then close it.
119872   */
119873   db->magic = SQLITE_MAGIC_ZOMBIE;
119874   sqlite3LeaveMutexAndCloseZombie(db);
119875   return SQLITE_OK;
119876 }
119877 
119878 /*
119879 ** Two variations on the public interface for closing a database
119880 ** connection. The sqlite3_close() version returns SQLITE_BUSY and
119881 ** leaves the connection option if there are unfinalized prepared
119882 ** statements or unfinished sqlite3_backups.  The sqlite3_close_v2()
119883 ** version forces the connection to become a zombie if there are
119884 ** unclosed resources, and arranges for deallocation when the last
119885 ** prepare statement or sqlite3_backup closes.
119886 */
119887 SQLITE_API int sqlite3_close(sqlite3 *db){ return sqlite3Close(db,0); }
119888 SQLITE_API int sqlite3_close_v2(sqlite3 *db){ return sqlite3Close(db,1); }
119889 
119890 
119891 /*
119892 ** Close the mutex on database connection db.
119893 **
119894 ** Furthermore, if database connection db is a zombie (meaning that there
119895 ** has been a prior call to sqlite3_close(db) or sqlite3_close_v2(db)) and
119896 ** every sqlite3_stmt has now been finalized and every sqlite3_backup has
119897 ** finished, then free all resources.
119898 */
119899 SQLITE_PRIVATE void sqlite3LeaveMutexAndCloseZombie(sqlite3 *db){
119900   HashElem *i;                    /* Hash table iterator */
119901   int j;
119902 
119903   /* If there are outstanding sqlite3_stmt or sqlite3_backup objects
119904   ** or if the connection has not yet been closed by sqlite3_close_v2(),
119905   ** then just leave the mutex and return.
119906   */
119907   if( db->magic!=SQLITE_MAGIC_ZOMBIE || connectionIsBusy(db) ){
119908     sqlite3_mutex_leave(db->mutex);
119909     return;
119910   }
119911 
119912   /* If we reach this point, it means that the database connection has
119913   ** closed all sqlite3_stmt and sqlite3_backup objects and has been
119914   ** passed to sqlite3_close (meaning that it is a zombie).  Therefore,
119915   ** go ahead and free all resources.
119916   */
119917 
119918   /* If a transaction is open, roll it back. This also ensures that if
119919   ** any database schemas have been modified by an uncommitted transaction
119920   ** they are reset. And that the required b-tree mutex is held to make
119921   ** the pager rollback and schema reset an atomic operation. */
119922   sqlite3RollbackAll(db, SQLITE_OK);
119923 
119924   /* Free any outstanding Savepoint structures. */
119925   sqlite3CloseSavepoints(db);
119926 
119927   /* Close all database connections */
119928   for(j=0; j<db->nDb; j++){
119929     struct Db *pDb = &db->aDb[j];
119930     if( pDb->pBt ){
119931       sqlite3BtreeClose(pDb->pBt);
119932       pDb->pBt = 0;
119933       if( j!=1 ){
119934         pDb->pSchema = 0;
119935       }
119936     }
119937   }
119938   /* Clear the TEMP schema separately and last */
119939   if( db->aDb[1].pSchema ){
119940     sqlite3SchemaClear(db->aDb[1].pSchema);
119941   }
119942   sqlite3VtabUnlockList(db);
119943 
119944   /* Free up the array of auxiliary databases */
119945   sqlite3CollapseDatabaseArray(db);
119946   assert( db->nDb<=2 );
119947   assert( db->aDb==db->aDbStatic );
119948 
119949   /* Tell the code in notify.c that the connection no longer holds any
119950   ** locks and does not require any further unlock-notify callbacks.
119951   */
119952   sqlite3ConnectionClosed(db);
119953 
119954   for(j=0; j<ArraySize(db->aFunc.a); j++){
119955     FuncDef *pNext, *pHash, *p;
119956     for(p=db->aFunc.a[j]; p; p=pHash){
119957       pHash = p->pHash;
119958       while( p ){
119959         functionDestroy(db, p);
119960         pNext = p->pNext;
119961         sqlite3DbFree(db, p);
119962         p = pNext;
119963       }
119964     }
119965   }
119966   for(i=sqliteHashFirst(&db->aCollSeq); i; i=sqliteHashNext(i)){
119967     CollSeq *pColl = (CollSeq *)sqliteHashData(i);
119968     /* Invoke any destructors registered for collation sequence user data. */
119969     for(j=0; j<3; j++){
119970       if( pColl[j].xDel ){
119971         pColl[j].xDel(pColl[j].pUser);
119972       }
119973     }
119974     sqlite3DbFree(db, pColl);
119975   }
119976   sqlite3HashClear(&db->aCollSeq);
119977 #ifndef SQLITE_OMIT_VIRTUALTABLE
119978   for(i=sqliteHashFirst(&db->aModule); i; i=sqliteHashNext(i)){
119979     Module *pMod = (Module *)sqliteHashData(i);
119980     if( pMod->xDestroy ){
119981       pMod->xDestroy(pMod->pAux);
119982     }
119983     sqlite3DbFree(db, pMod);
119984   }
119985   sqlite3HashClear(&db->aModule);
119986 #endif
119987 
119988   sqlite3Error(db, SQLITE_OK, 0); /* Deallocates any cached error strings. */
119989   if( db->pErr ){
119990     sqlite3ValueFree(db->pErr);
119991   }
119992   sqlite3CloseExtensions(db);
119993 
119994   db->magic = SQLITE_MAGIC_ERROR;
119995 
119996   /* The temp-database schema is allocated differently from the other schema
119997   ** objects (using sqliteMalloc() directly, instead of sqlite3BtreeSchema()).
119998   ** So it needs to be freed here. Todo: Why not roll the temp schema into
119999   ** the same sqliteMalloc() as the one that allocates the database 
120000   ** structure?
120001   */
120002   sqlite3DbFree(db, db->aDb[1].pSchema);
120003   sqlite3_mutex_leave(db->mutex);
120004   db->magic = SQLITE_MAGIC_CLOSED;
120005   sqlite3_mutex_free(db->mutex);
120006   assert( db->lookaside.nOut==0 );  /* Fails on a lookaside memory leak */
120007   if( db->lookaside.bMalloced ){
120008     sqlite3_free(db->lookaside.pStart);
120009   }
120010   sqlite3_free(db);
120011 }
120012 
120013 /*
120014 ** Rollback all database files.  If tripCode is not SQLITE_OK, then
120015 ** any open cursors are invalidated ("tripped" - as in "tripping a circuit
120016 ** breaker") and made to return tripCode if there are any further
120017 ** attempts to use that cursor.
120018 */
120019 SQLITE_PRIVATE void sqlite3RollbackAll(sqlite3 *db, int tripCode){
120020   int i;
120021   int inTrans = 0;
120022   assert( sqlite3_mutex_held(db->mutex) );
120023   sqlite3BeginBenignMalloc();
120024 
120025   /* Obtain all b-tree mutexes before making any calls to BtreeRollback(). 
120026   ** This is important in case the transaction being rolled back has
120027   ** modified the database schema. If the b-tree mutexes are not taken
120028   ** here, then another shared-cache connection might sneak in between
120029   ** the database rollback and schema reset, which can cause false
120030   ** corruption reports in some cases.  */
120031   sqlite3BtreeEnterAll(db);
120032 
120033   for(i=0; i<db->nDb; i++){
120034     Btree *p = db->aDb[i].pBt;
120035     if( p ){
120036       if( sqlite3BtreeIsInTrans(p) ){
120037         inTrans = 1;
120038       }
120039       sqlite3BtreeRollback(p, tripCode);
120040     }
120041   }
120042   sqlite3VtabRollback(db);
120043   sqlite3EndBenignMalloc();
120044 
120045   if( (db->flags&SQLITE_InternChanges)!=0 && db->init.busy==0 ){
120046     sqlite3ExpirePreparedStatements(db);
120047     sqlite3ResetAllSchemasOfConnection(db);
120048   }
120049   sqlite3BtreeLeaveAll(db);
120050 
120051   /* Any deferred constraint violations have now been resolved. */
120052   db->nDeferredCons = 0;
120053   db->nDeferredImmCons = 0;
120054   db->flags &= ~SQLITE_DeferFKs;
120055 
120056   /* If one has been configured, invoke the rollback-hook callback */
120057   if( db->xRollbackCallback && (inTrans || !db->autoCommit) ){
120058     db->xRollbackCallback(db->pRollbackArg);
120059   }
120060 }
120061 
120062 /*
120063 ** Return a static string containing the name corresponding to the error code
120064 ** specified in the argument.
120065 */
120066 #if defined(SQLITE_DEBUG) || defined(SQLITE_TEST) || \
120067     defined(SQLITE_DEBUG_OS_TRACE)
120068 SQLITE_PRIVATE const char *sqlite3ErrName(int rc){
120069   const char *zName = 0;
120070   int i, origRc = rc;
120071   for(i=0; i<2 && zName==0; i++, rc &= 0xff){
120072     switch( rc ){
120073       case SQLITE_OK:                 zName = "SQLITE_OK";                break;
120074       case SQLITE_ERROR:              zName = "SQLITE_ERROR";             break;
120075       case SQLITE_INTERNAL:           zName = "SQLITE_INTERNAL";          break;
120076       case SQLITE_PERM:               zName = "SQLITE_PERM";              break;
120077       case SQLITE_ABORT:              zName = "SQLITE_ABORT";             break;
120078       case SQLITE_ABORT_ROLLBACK:     zName = "SQLITE_ABORT_ROLLBACK";    break;
120079       case SQLITE_BUSY:               zName = "SQLITE_BUSY";              break;
120080       case SQLITE_BUSY_RECOVERY:      zName = "SQLITE_BUSY_RECOVERY";     break;
120081       case SQLITE_BUSY_SNAPSHOT:      zName = "SQLITE_BUSY_SNAPSHOT";     break;
120082       case SQLITE_LOCKED:             zName = "SQLITE_LOCKED";            break;
120083       case SQLITE_LOCKED_SHAREDCACHE: zName = "SQLITE_LOCKED_SHAREDCACHE";break;
120084       case SQLITE_NOMEM:              zName = "SQLITE_NOMEM";             break;
120085       case SQLITE_READONLY:           zName = "SQLITE_READONLY";          break;
120086       case SQLITE_READONLY_RECOVERY:  zName = "SQLITE_READONLY_RECOVERY"; break;
120087       case SQLITE_READONLY_CANTLOCK:  zName = "SQLITE_READONLY_CANTLOCK"; break;
120088       case SQLITE_READONLY_ROLLBACK:  zName = "SQLITE_READONLY_ROLLBACK"; break;
120089       case SQLITE_INTERRUPT:          zName = "SQLITE_INTERRUPT";         break;
120090       case SQLITE_IOERR:              zName = "SQLITE_IOERR";             break;
120091       case SQLITE_IOERR_READ:         zName = "SQLITE_IOERR_READ";        break;
120092       case SQLITE_IOERR_SHORT_READ:   zName = "SQLITE_IOERR_SHORT_READ";  break;
120093       case SQLITE_IOERR_WRITE:        zName = "SQLITE_IOERR_WRITE";       break;
120094       case SQLITE_IOERR_FSYNC:        zName = "SQLITE_IOERR_FSYNC";       break;
120095       case SQLITE_IOERR_DIR_FSYNC:    zName = "SQLITE_IOERR_DIR_FSYNC";   break;
120096       case SQLITE_IOERR_TRUNCATE:     zName = "SQLITE_IOERR_TRUNCATE";    break;
120097       case SQLITE_IOERR_FSTAT:        zName = "SQLITE_IOERR_FSTAT";       break;
120098       case SQLITE_IOERR_UNLOCK:       zName = "SQLITE_IOERR_UNLOCK";      break;
120099       case SQLITE_IOERR_RDLOCK:       zName = "SQLITE_IOERR_RDLOCK";      break;
120100       case SQLITE_IOERR_DELETE:       zName = "SQLITE_IOERR_DELETE";      break;
120101       case SQLITE_IOERR_BLOCKED:      zName = "SQLITE_IOERR_BLOCKED";     break;
120102       case SQLITE_IOERR_NOMEM:        zName = "SQLITE_IOERR_NOMEM";       break;
120103       case SQLITE_IOERR_ACCESS:       zName = "SQLITE_IOERR_ACCESS";      break;
120104       case SQLITE_IOERR_CHECKRESERVEDLOCK:
120105                                 zName = "SQLITE_IOERR_CHECKRESERVEDLOCK"; break;
120106       case SQLITE_IOERR_LOCK:         zName = "SQLITE_IOERR_LOCK";        break;
120107       case SQLITE_IOERR_CLOSE:        zName = "SQLITE_IOERR_CLOSE";       break;
120108       case SQLITE_IOERR_DIR_CLOSE:    zName = "SQLITE_IOERR_DIR_CLOSE";   break;
120109       case SQLITE_IOERR_SHMOPEN:      zName = "SQLITE_IOERR_SHMOPEN";     break;
120110       case SQLITE_IOERR_SHMSIZE:      zName = "SQLITE_IOERR_SHMSIZE";     break;
120111       case SQLITE_IOERR_SHMLOCK:      zName = "SQLITE_IOERR_SHMLOCK";     break;
120112       case SQLITE_IOERR_SHMMAP:       zName = "SQLITE_IOERR_SHMMAP";      break;
120113       case SQLITE_IOERR_SEEK:         zName = "SQLITE_IOERR_SEEK";        break;
120114       case SQLITE_IOERR_DELETE_NOENT: zName = "SQLITE_IOERR_DELETE_NOENT";break;
120115       case SQLITE_IOERR_MMAP:         zName = "SQLITE_IOERR_MMAP";        break;
120116       case SQLITE_IOERR_GETTEMPPATH:  zName = "SQLITE_IOERR_GETTEMPPATH"; break;
120117       case SQLITE_IOERR_CONVPATH:     zName = "SQLITE_IOERR_CONVPATH";    break;
120118       case SQLITE_CORRUPT:            zName = "SQLITE_CORRUPT";           break;
120119       case SQLITE_CORRUPT_VTAB:       zName = "SQLITE_CORRUPT_VTAB";      break;
120120       case SQLITE_NOTFOUND:           zName = "SQLITE_NOTFOUND";          break;
120121       case SQLITE_FULL:               zName = "SQLITE_FULL";              break;
120122       case SQLITE_CANTOPEN:           zName = "SQLITE_CANTOPEN";          break;
120123       case SQLITE_CANTOPEN_NOTEMPDIR: zName = "SQLITE_CANTOPEN_NOTEMPDIR";break;
120124       case SQLITE_CANTOPEN_ISDIR:     zName = "SQLITE_CANTOPEN_ISDIR";    break;
120125       case SQLITE_CANTOPEN_FULLPATH:  zName = "SQLITE_CANTOPEN_FULLPATH"; break;
120126       case SQLITE_CANTOPEN_CONVPATH:  zName = "SQLITE_CANTOPEN_CONVPATH"; break;
120127       case SQLITE_PROTOCOL:           zName = "SQLITE_PROTOCOL";          break;
120128       case SQLITE_EMPTY:              zName = "SQLITE_EMPTY";             break;
120129       case SQLITE_SCHEMA:             zName = "SQLITE_SCHEMA";            break;
120130       case SQLITE_TOOBIG:             zName = "SQLITE_TOOBIG";            break;
120131       case SQLITE_CONSTRAINT:         zName = "SQLITE_CONSTRAINT";        break;
120132       case SQLITE_CONSTRAINT_UNIQUE:  zName = "SQLITE_CONSTRAINT_UNIQUE"; break;
120133       case SQLITE_CONSTRAINT_TRIGGER: zName = "SQLITE_CONSTRAINT_TRIGGER";break;
120134       case SQLITE_CONSTRAINT_FOREIGNKEY:
120135                                 zName = "SQLITE_CONSTRAINT_FOREIGNKEY";   break;
120136       case SQLITE_CONSTRAINT_CHECK:   zName = "SQLITE_CONSTRAINT_CHECK";  break;
120137       case SQLITE_CONSTRAINT_PRIMARYKEY:
120138                                 zName = "SQLITE_CONSTRAINT_PRIMARYKEY";   break;
120139       case SQLITE_CONSTRAINT_NOTNULL: zName = "SQLITE_CONSTRAINT_NOTNULL";break;
120140       case SQLITE_CONSTRAINT_COMMITHOOK:
120141                                 zName = "SQLITE_CONSTRAINT_COMMITHOOK";   break;
120142       case SQLITE_CONSTRAINT_VTAB:    zName = "SQLITE_CONSTRAINT_VTAB";   break;
120143       case SQLITE_CONSTRAINT_FUNCTION:
120144                                 zName = "SQLITE_CONSTRAINT_FUNCTION";     break;
120145       case SQLITE_CONSTRAINT_ROWID:   zName = "SQLITE_CONSTRAINT_ROWID";  break;
120146       case SQLITE_MISMATCH:           zName = "SQLITE_MISMATCH";          break;
120147       case SQLITE_MISUSE:             zName = "SQLITE_MISUSE";            break;
120148       case SQLITE_NOLFS:              zName = "SQLITE_NOLFS";             break;
120149       case SQLITE_AUTH:               zName = "SQLITE_AUTH";              break;
120150       case SQLITE_FORMAT:             zName = "SQLITE_FORMAT";            break;
120151       case SQLITE_RANGE:              zName = "SQLITE_RANGE";             break;
120152       case SQLITE_NOTADB:             zName = "SQLITE_NOTADB";            break;
120153       case SQLITE_ROW:                zName = "SQLITE_ROW";               break;
120154       case SQLITE_NOTICE:             zName = "SQLITE_NOTICE";            break;
120155       case SQLITE_NOTICE_RECOVER_WAL: zName = "SQLITE_NOTICE_RECOVER_WAL";break;
120156       case SQLITE_NOTICE_RECOVER_ROLLBACK:
120157                                 zName = "SQLITE_NOTICE_RECOVER_ROLLBACK"; break;
120158       case SQLITE_WARNING:            zName = "SQLITE_WARNING";           break;
120159       case SQLITE_WARNING_AUTOINDEX:  zName = "SQLITE_WARNING_AUTOINDEX"; break;
120160       case SQLITE_DONE:               zName = "SQLITE_DONE";              break;
120161     }
120162   }
120163   if( zName==0 ){
120164     static char zBuf[50];
120165     sqlite3_snprintf(sizeof(zBuf), zBuf, "SQLITE_UNKNOWN(%d)", origRc);
120166     zName = zBuf;
120167   }
120168   return zName;
120169 }
120170 #endif
120171 
120172 /*
120173 ** Return a static string that describes the kind of error specified in the
120174 ** argument.
120175 */
120176 SQLITE_PRIVATE const char *sqlite3ErrStr(int rc){
120177   static const char* const aMsg[] = {
120178     /* SQLITE_OK          */ "not an error",
120179     /* SQLITE_ERROR       */ "SQL logic error or missing database",
120180     /* SQLITE_INTERNAL    */ 0,
120181     /* SQLITE_PERM        */ "access permission denied",
120182     /* SQLITE_ABORT       */ "callback requested query abort",
120183     /* SQLITE_BUSY        */ "database is locked",
120184     /* SQLITE_LOCKED      */ "database table is locked",
120185     /* SQLITE_NOMEM       */ "out of memory",
120186     /* SQLITE_READONLY    */ "attempt to write a readonly database",
120187     /* SQLITE_INTERRUPT   */ "interrupted",
120188     /* SQLITE_IOERR       */ "disk I/O error",
120189     /* SQLITE_CORRUPT     */ "database disk image is malformed",
120190     /* SQLITE_NOTFOUND    */ "unknown operation",
120191     /* SQLITE_FULL        */ "database or disk is full",
120192     /* SQLITE_CANTOPEN    */ "unable to open database file",
120193     /* SQLITE_PROTOCOL    */ "locking protocol",
120194     /* SQLITE_EMPTY       */ "table contains no data",
120195     /* SQLITE_SCHEMA      */ "database schema has changed",
120196     /* SQLITE_TOOBIG      */ "string or blob too big",
120197     /* SQLITE_CONSTRAINT  */ "constraint failed",
120198     /* SQLITE_MISMATCH    */ "datatype mismatch",
120199     /* SQLITE_MISUSE      */ "library routine called out of sequence",
120200     /* SQLITE_NOLFS       */ "large file support is disabled",
120201     /* SQLITE_AUTH        */ "authorization denied",
120202     /* SQLITE_FORMAT      */ "auxiliary database format error",
120203     /* SQLITE_RANGE       */ "bind or column index out of range",
120204     /* SQLITE_NOTADB      */ "file is encrypted or is not a database",
120205   };
120206   const char *zErr = "unknown error";
120207   switch( rc ){
120208     case SQLITE_ABORT_ROLLBACK: {
120209       zErr = "abort due to ROLLBACK";
120210       break;
120211     }
120212     default: {
120213       rc &= 0xff;
120214       if( ALWAYS(rc>=0) && rc<ArraySize(aMsg) && aMsg[rc]!=0 ){
120215         zErr = aMsg[rc];
120216       }
120217       break;
120218     }
120219   }
120220   return zErr;
120221 }
120222 
120223 /*
120224 ** This routine implements a busy callback that sleeps and tries
120225 ** again until a timeout value is reached.  The timeout value is
120226 ** an integer number of milliseconds passed in as the first
120227 ** argument.
120228 */
120229 static int sqliteDefaultBusyCallback(
120230  void *ptr,               /* Database connection */
120231  int count                /* Number of times table has been busy */
120232 ){
120233 #if SQLITE_OS_WIN || (defined(HAVE_USLEEP) && HAVE_USLEEP)
120234   static const u8 delays[] =
120235      { 1, 2, 5, 10, 15, 20, 25, 25,  25,  50,  50, 100 };
120236   static const u8 totals[] =
120237      { 0, 1, 3,  8, 18, 33, 53, 78, 103, 128, 178, 228 };
120238 # define NDELAY ArraySize(delays)
120239   sqlite3 *db = (sqlite3 *)ptr;
120240   int timeout = db->busyTimeout;
120241   int delay, prior;
120242 
120243   assert( count>=0 );
120244   if( count < NDELAY ){
120245     delay = delays[count];
120246     prior = totals[count];
120247   }else{
120248     delay = delays[NDELAY-1];
120249     prior = totals[NDELAY-1] + delay*(count-(NDELAY-1));
120250   }
120251   if( prior + delay > timeout ){
120252     delay = timeout - prior;
120253     if( delay<=0 ) return 0;
120254   }
120255   sqlite3OsSleep(db->pVfs, delay*1000);
120256   return 1;
120257 #else
120258   sqlite3 *db = (sqlite3 *)ptr;
120259   int timeout = ((sqlite3 *)ptr)->busyTimeout;
120260   if( (count+1)*1000 > timeout ){
120261     return 0;
120262   }
120263   sqlite3OsSleep(db->pVfs, 1000000);
120264   return 1;
120265 #endif
120266 }
120267 
120268 /*
120269 ** Invoke the given busy handler.
120270 **
120271 ** This routine is called when an operation failed with a lock.
120272 ** If this routine returns non-zero, the lock is retried.  If it
120273 ** returns 0, the operation aborts with an SQLITE_BUSY error.
120274 */
120275 SQLITE_PRIVATE int sqlite3InvokeBusyHandler(BusyHandler *p){
120276   int rc;
120277   if( NEVER(p==0) || p->xFunc==0 || p->nBusy<0 ) return 0;
120278   rc = p->xFunc(p->pArg, p->nBusy);
120279   if( rc==0 ){
120280     p->nBusy = -1;
120281   }else{
120282     p->nBusy++;
120283   }
120284   return rc; 
120285 }
120286 
120287 /*
120288 ** This routine sets the busy callback for an Sqlite database to the
120289 ** given callback function with the given argument.
120290 */
120291 SQLITE_API int sqlite3_busy_handler(
120292   sqlite3 *db,
120293   int (*xBusy)(void*,int),
120294   void *pArg
120295 ){
120296   sqlite3_mutex_enter(db->mutex);
120297   db->busyHandler.xFunc = xBusy;
120298   db->busyHandler.pArg = pArg;
120299   db->busyHandler.nBusy = 0;
120300   db->busyTimeout = 0;
120301   sqlite3_mutex_leave(db->mutex);
120302   return SQLITE_OK;
120303 }
120304 
120305 #ifndef SQLITE_OMIT_PROGRESS_CALLBACK
120306 /*
120307 ** This routine sets the progress callback for an Sqlite database to the
120308 ** given callback function with the given argument. The progress callback will
120309 ** be invoked every nOps opcodes.
120310 */
120311 SQLITE_API void sqlite3_progress_handler(
120312   sqlite3 *db, 
120313   int nOps,
120314   int (*xProgress)(void*), 
120315   void *pArg
120316 ){
120317   sqlite3_mutex_enter(db->mutex);
120318   if( nOps>0 ){
120319     db->xProgress = xProgress;
120320     db->nProgressOps = (unsigned)nOps;
120321     db->pProgressArg = pArg;
120322   }else{
120323     db->xProgress = 0;
120324     db->nProgressOps = 0;
120325     db->pProgressArg = 0;
120326   }
120327   sqlite3_mutex_leave(db->mutex);
120328 }
120329 #endif
120330 
120331 
120332 /*
120333 ** This routine installs a default busy handler that waits for the
120334 ** specified number of milliseconds before returning 0.
120335 */
120336 SQLITE_API int sqlite3_busy_timeout(sqlite3 *db, int ms){
120337   if( ms>0 ){
120338     sqlite3_busy_handler(db, sqliteDefaultBusyCallback, (void*)db);
120339     db->busyTimeout = ms;
120340   }else{
120341     sqlite3_busy_handler(db, 0, 0);
120342   }
120343   return SQLITE_OK;
120344 }
120345 
120346 /*
120347 ** Cause any pending operation to stop at its earliest opportunity.
120348 */
120349 SQLITE_API void sqlite3_interrupt(sqlite3 *db){
120350   db->u1.isInterrupted = 1;
120351 }
120352 
120353 
120354 /*
120355 ** This function is exactly the same as sqlite3_create_function(), except
120356 ** that it is designed to be called by internal code. The difference is
120357 ** that if a malloc() fails in sqlite3_create_function(), an error code
120358 ** is returned and the mallocFailed flag cleared. 
120359 */
120360 SQLITE_PRIVATE int sqlite3CreateFunc(
120361   sqlite3 *db,
120362   const char *zFunctionName,
120363   int nArg,
120364   int enc,
120365   void *pUserData,
120366   void (*xFunc)(sqlite3_context*,int,sqlite3_value **),
120367   void (*xStep)(sqlite3_context*,int,sqlite3_value **),
120368   void (*xFinal)(sqlite3_context*),
120369   FuncDestructor *pDestructor
120370 ){
120371   FuncDef *p;
120372   int nName;
120373 
120374   assert( sqlite3_mutex_held(db->mutex) );
120375   if( zFunctionName==0 ||
120376       (xFunc && (xFinal || xStep)) || 
120377       (!xFunc && (xFinal && !xStep)) ||
120378       (!xFunc && (!xFinal && xStep)) ||
120379       (nArg<-1 || nArg>SQLITE_MAX_FUNCTION_ARG) ||
120380       (255<(nName = sqlite3Strlen30( zFunctionName))) ){
120381     return SQLITE_MISUSE_BKPT;
120382   }
120383   
120384 #ifndef SQLITE_OMIT_UTF16
120385   /* If SQLITE_UTF16 is specified as the encoding type, transform this
120386   ** to one of SQLITE_UTF16LE or SQLITE_UTF16BE using the
120387   ** SQLITE_UTF16NATIVE macro. SQLITE_UTF16 is not used internally.
120388   **
120389   ** If SQLITE_ANY is specified, add three versions of the function
120390   ** to the hash table.
120391   */
120392   if( enc==SQLITE_UTF16 ){
120393     enc = SQLITE_UTF16NATIVE;
120394   }else if( enc==SQLITE_ANY ){
120395     int rc;
120396     rc = sqlite3CreateFunc(db, zFunctionName, nArg, SQLITE_UTF8,
120397          pUserData, xFunc, xStep, xFinal, pDestructor);
120398     if( rc==SQLITE_OK ){
120399       rc = sqlite3CreateFunc(db, zFunctionName, nArg, SQLITE_UTF16LE,
120400           pUserData, xFunc, xStep, xFinal, pDestructor);
120401     }
120402     if( rc!=SQLITE_OK ){
120403       return rc;
120404     }
120405     enc = SQLITE_UTF16BE;
120406   }
120407 #else
120408   enc = SQLITE_UTF8;
120409 #endif
120410   
120411   /* Check if an existing function is being overridden or deleted. If so,
120412   ** and there are active VMs, then return SQLITE_BUSY. If a function
120413   ** is being overridden/deleted but there are no active VMs, allow the
120414   ** operation to continue but invalidate all precompiled statements.
120415   */
120416   p = sqlite3FindFunction(db, zFunctionName, nName, nArg, (u8)enc, 0);
120417   if( p && (p->funcFlags & SQLITE_FUNC_ENCMASK)==enc && p->nArg==nArg ){
120418     if( db->nVdbeActive ){
120419       sqlite3Error(db, SQLITE_BUSY, 
120420         "unable to delete/modify user-function due to active statements");
120421       assert( !db->mallocFailed );
120422       return SQLITE_BUSY;
120423     }else{
120424       sqlite3ExpirePreparedStatements(db);
120425     }
120426   }
120427 
120428   p = sqlite3FindFunction(db, zFunctionName, nName, nArg, (u8)enc, 1);
120429   assert(p || db->mallocFailed);
120430   if( !p ){
120431     return SQLITE_NOMEM;
120432   }
120433 
120434   /* If an older version of the function with a configured destructor is
120435   ** being replaced invoke the destructor function here. */
120436   functionDestroy(db, p);
120437 
120438   if( pDestructor ){
120439     pDestructor->nRef++;
120440   }
120441   p->pDestructor = pDestructor;
120442   p->funcFlags &= SQLITE_FUNC_ENCMASK;
120443   p->xFunc = xFunc;
120444   p->xStep = xStep;
120445   p->xFinalize = xFinal;
120446   p->pUserData = pUserData;
120447   p->nArg = (u16)nArg;
120448   return SQLITE_OK;
120449 }
120450 
120451 /*
120452 ** Create new user functions.
120453 */
120454 SQLITE_API int sqlite3_create_function(
120455   sqlite3 *db,
120456   const char *zFunc,
120457   int nArg,
120458   int enc,
120459   void *p,
120460   void (*xFunc)(sqlite3_context*,int,sqlite3_value **),
120461   void (*xStep)(sqlite3_context*,int,sqlite3_value **),
120462   void (*xFinal)(sqlite3_context*)
120463 ){
120464   return sqlite3_create_function_v2(db, zFunc, nArg, enc, p, xFunc, xStep,
120465                                     xFinal, 0);
120466 }
120467 
120468 SQLITE_API int sqlite3_create_function_v2(
120469   sqlite3 *db,
120470   const char *zFunc,
120471   int nArg,
120472   int enc,
120473   void *p,
120474   void (*xFunc)(sqlite3_context*,int,sqlite3_value **),
120475   void (*xStep)(sqlite3_context*,int,sqlite3_value **),
120476   void (*xFinal)(sqlite3_context*),
120477   void (*xDestroy)(void *)
120478 ){
120479   int rc = SQLITE_ERROR;
120480   FuncDestructor *pArg = 0;
120481   sqlite3_mutex_enter(db->mutex);
120482   if( xDestroy ){
120483     pArg = (FuncDestructor *)sqlite3DbMallocZero(db, sizeof(FuncDestructor));
120484     if( !pArg ){
120485       xDestroy(p);
120486       goto out;
120487     }
120488     pArg->xDestroy = xDestroy;
120489     pArg->pUserData = p;
120490   }
120491   rc = sqlite3CreateFunc(db, zFunc, nArg, enc, p, xFunc, xStep, xFinal, pArg);
120492   if( pArg && pArg->nRef==0 ){
120493     assert( rc!=SQLITE_OK );
120494     xDestroy(p);
120495     sqlite3DbFree(db, pArg);
120496   }
120497 
120498  out:
120499   rc = sqlite3ApiExit(db, rc);
120500   sqlite3_mutex_leave(db->mutex);
120501   return rc;
120502 }
120503 
120504 #ifndef SQLITE_OMIT_UTF16
120505 SQLITE_API int sqlite3_create_function16(
120506   sqlite3 *db,
120507   const void *zFunctionName,
120508   int nArg,
120509   int eTextRep,
120510   void *p,
120511   void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
120512   void (*xStep)(sqlite3_context*,int,sqlite3_value**),
120513   void (*xFinal)(sqlite3_context*)
120514 ){
120515   int rc;
120516   char *zFunc8;
120517   sqlite3_mutex_enter(db->mutex);
120518   assert( !db->mallocFailed );
120519   zFunc8 = sqlite3Utf16to8(db, zFunctionName, -1, SQLITE_UTF16NATIVE);
120520   rc = sqlite3CreateFunc(db, zFunc8, nArg, eTextRep, p, xFunc, xStep, xFinal,0);
120521   sqlite3DbFree(db, zFunc8);
120522   rc = sqlite3ApiExit(db, rc);
120523   sqlite3_mutex_leave(db->mutex);
120524   return rc;
120525 }
120526 #endif
120527 
120528 
120529 /*
120530 ** Declare that a function has been overloaded by a virtual table.
120531 **
120532 ** If the function already exists as a regular global function, then
120533 ** this routine is a no-op.  If the function does not exist, then create
120534 ** a new one that always throws a run-time error.  
120535 **
120536 ** When virtual tables intend to provide an overloaded function, they
120537 ** should call this routine to make sure the global function exists.
120538 ** A global function must exist in order for name resolution to work
120539 ** properly.
120540 */
120541 SQLITE_API int sqlite3_overload_function(
120542   sqlite3 *db,
120543   const char *zName,
120544   int nArg
120545 ){
120546   int nName = sqlite3Strlen30(zName);
120547   int rc = SQLITE_OK;
120548   sqlite3_mutex_enter(db->mutex);
120549   if( sqlite3FindFunction(db, zName, nName, nArg, SQLITE_UTF8, 0)==0 ){
120550     rc = sqlite3CreateFunc(db, zName, nArg, SQLITE_UTF8,
120551                            0, sqlite3InvalidFunction, 0, 0, 0);
120552   }
120553   rc = sqlite3ApiExit(db, rc);
120554   sqlite3_mutex_leave(db->mutex);
120555   return rc;
120556 }
120557 
120558 #ifndef SQLITE_OMIT_TRACE
120559 /*
120560 ** Register a trace function.  The pArg from the previously registered trace
120561 ** is returned.  
120562 **
120563 ** A NULL trace function means that no tracing is executes.  A non-NULL
120564 ** trace is a pointer to a function that is invoked at the start of each
120565 ** SQL statement.
120566 */
120567 SQLITE_API void *sqlite3_trace(sqlite3 *db, void (*xTrace)(void*,const char*), void *pArg){
120568   void *pOld;
120569   sqlite3_mutex_enter(db->mutex);
120570   pOld = db->pTraceArg;
120571   db->xTrace = xTrace;
120572   db->pTraceArg = pArg;
120573   sqlite3_mutex_leave(db->mutex);
120574   return pOld;
120575 }
120576 /*
120577 ** Register a profile function.  The pArg from the previously registered 
120578 ** profile function is returned.  
120579 **
120580 ** A NULL profile function means that no profiling is executes.  A non-NULL
120581 ** profile is a pointer to a function that is invoked at the conclusion of
120582 ** each SQL statement that is run.
120583 */
120584 SQLITE_API void *sqlite3_profile(
120585   sqlite3 *db,
120586   void (*xProfile)(void*,const char*,sqlite_uint64),
120587   void *pArg
120588 ){
120589   void *pOld;
120590   sqlite3_mutex_enter(db->mutex);
120591   pOld = db->pProfileArg;
120592   db->xProfile = xProfile;
120593   db->pProfileArg = pArg;
120594   sqlite3_mutex_leave(db->mutex);
120595   return pOld;
120596 }
120597 #endif /* SQLITE_OMIT_TRACE */
120598 
120599 /*
120600 ** Register a function to be invoked when a transaction commits.
120601 ** If the invoked function returns non-zero, then the commit becomes a
120602 ** rollback.
120603 */
120604 SQLITE_API void *sqlite3_commit_hook(
120605   sqlite3 *db,              /* Attach the hook to this database */
120606   int (*xCallback)(void*),  /* Function to invoke on each commit */
120607   void *pArg                /* Argument to the function */
120608 ){
120609   void *pOld;
120610   sqlite3_mutex_enter(db->mutex);
120611   pOld = db->pCommitArg;
120612   db->xCommitCallback = xCallback;
120613   db->pCommitArg = pArg;
120614   sqlite3_mutex_leave(db->mutex);
120615   return pOld;
120616 }
120617 
120618 /*
120619 ** Register a callback to be invoked each time a row is updated,
120620 ** inserted or deleted using this database connection.
120621 */
120622 SQLITE_API void *sqlite3_update_hook(
120623   sqlite3 *db,              /* Attach the hook to this database */
120624   void (*xCallback)(void*,int,char const *,char const *,sqlite_int64),
120625   void *pArg                /* Argument to the function */
120626 ){
120627   void *pRet;
120628   sqlite3_mutex_enter(db->mutex);
120629   pRet = db->pUpdateArg;
120630   db->xUpdateCallback = xCallback;
120631   db->pUpdateArg = pArg;
120632   sqlite3_mutex_leave(db->mutex);
120633   return pRet;
120634 }
120635 
120636 /*
120637 ** Register a callback to be invoked each time a transaction is rolled
120638 ** back by this database connection.
120639 */
120640 SQLITE_API void *sqlite3_rollback_hook(
120641   sqlite3 *db,              /* Attach the hook to this database */
120642   void (*xCallback)(void*), /* Callback function */
120643   void *pArg                /* Argument to the function */
120644 ){
120645   void *pRet;
120646   sqlite3_mutex_enter(db->mutex);
120647   pRet = db->pRollbackArg;
120648   db->xRollbackCallback = xCallback;
120649   db->pRollbackArg = pArg;
120650   sqlite3_mutex_leave(db->mutex);
120651   return pRet;
120652 }
120653 
120654 #ifndef SQLITE_OMIT_WAL
120655 /*
120656 ** The sqlite3_wal_hook() callback registered by sqlite3_wal_autocheckpoint().
120657 ** Invoke sqlite3_wal_checkpoint if the number of frames in the log file
120658 ** is greater than sqlite3.pWalArg cast to an integer (the value configured by
120659 ** wal_autocheckpoint()).
120660 */ 
120661 SQLITE_PRIVATE int sqlite3WalDefaultHook(
120662   void *pClientData,     /* Argument */
120663   sqlite3 *db,           /* Connection */
120664   const char *zDb,       /* Database */
120665   int nFrame             /* Size of WAL */
120666 ){
120667   if( nFrame>=SQLITE_PTR_TO_INT(pClientData) ){
120668     sqlite3BeginBenignMalloc();
120669     sqlite3_wal_checkpoint(db, zDb);
120670     sqlite3EndBenignMalloc();
120671   }
120672   return SQLITE_OK;
120673 }
120674 #endif /* SQLITE_OMIT_WAL */
120675 
120676 /*
120677 ** Configure an sqlite3_wal_hook() callback to automatically checkpoint
120678 ** a database after committing a transaction if there are nFrame or
120679 ** more frames in the log file. Passing zero or a negative value as the
120680 ** nFrame parameter disables automatic checkpoints entirely.
120681 **
120682 ** The callback registered by this function replaces any existing callback
120683 ** registered using sqlite3_wal_hook(). Likewise, registering a callback
120684 ** using sqlite3_wal_hook() disables the automatic checkpoint mechanism
120685 ** configured by this function.
120686 */
120687 SQLITE_API int sqlite3_wal_autocheckpoint(sqlite3 *db, int nFrame){
120688 #ifdef SQLITE_OMIT_WAL
120689   UNUSED_PARAMETER(db);
120690   UNUSED_PARAMETER(nFrame);
120691 #else
120692   if( nFrame>0 ){
120693     sqlite3_wal_hook(db, sqlite3WalDefaultHook, SQLITE_INT_TO_PTR(nFrame));
120694   }else{
120695     sqlite3_wal_hook(db, 0, 0);
120696   }
120697 #endif
120698   return SQLITE_OK;
120699 }
120700 
120701 /*
120702 ** Register a callback to be invoked each time a transaction is written
120703 ** into the write-ahead-log by this database connection.
120704 */
120705 SQLITE_API void *sqlite3_wal_hook(
120706   sqlite3 *db,                    /* Attach the hook to this db handle */
120707   int(*xCallback)(void *, sqlite3*, const char*, int),
120708   void *pArg                      /* First argument passed to xCallback() */
120709 ){
120710 #ifndef SQLITE_OMIT_WAL
120711   void *pRet;
120712   sqlite3_mutex_enter(db->mutex);
120713   pRet = db->pWalArg;
120714   db->xWalCallback = xCallback;
120715   db->pWalArg = pArg;
120716   sqlite3_mutex_leave(db->mutex);
120717   return pRet;
120718 #else
120719   return 0;
120720 #endif
120721 }
120722 
120723 /*
120724 ** Checkpoint database zDb.
120725 */
120726 SQLITE_API int sqlite3_wal_checkpoint_v2(
120727   sqlite3 *db,                    /* Database handle */
120728   const char *zDb,                /* Name of attached database (or NULL) */
120729   int eMode,                      /* SQLITE_CHECKPOINT_* value */
120730   int *pnLog,                     /* OUT: Size of WAL log in frames */
120731   int *pnCkpt                     /* OUT: Total number of frames checkpointed */
120732 ){
120733 #ifdef SQLITE_OMIT_WAL
120734   return SQLITE_OK;
120735 #else
120736   int rc;                         /* Return code */
120737   int iDb = SQLITE_MAX_ATTACHED;  /* sqlite3.aDb[] index of db to checkpoint */
120738 
120739   /* Initialize the output variables to -1 in case an error occurs. */
120740   if( pnLog ) *pnLog = -1;
120741   if( pnCkpt ) *pnCkpt = -1;
120742 
120743   assert( SQLITE_CHECKPOINT_FULL>SQLITE_CHECKPOINT_PASSIVE );
120744   assert( SQLITE_CHECKPOINT_FULL<SQLITE_CHECKPOINT_RESTART );
120745   assert( SQLITE_CHECKPOINT_PASSIVE+2==SQLITE_CHECKPOINT_RESTART );
120746   if( eMode<SQLITE_CHECKPOINT_PASSIVE || eMode>SQLITE_CHECKPOINT_RESTART ){
120747     return SQLITE_MISUSE;
120748   }
120749 
120750   sqlite3_mutex_enter(db->mutex);
120751   if( zDb && zDb[0] ){
120752     iDb = sqlite3FindDbName(db, zDb);
120753   }
120754   if( iDb<0 ){
120755     rc = SQLITE_ERROR;
120756     sqlite3Error(db, SQLITE_ERROR, "unknown database: %s", zDb);
120757   }else{
120758     rc = sqlite3Checkpoint(db, iDb, eMode, pnLog, pnCkpt);
120759     sqlite3Error(db, rc, 0);
120760   }
120761   rc = sqlite3ApiExit(db, rc);
120762   sqlite3_mutex_leave(db->mutex);
120763   return rc;
120764 #endif
120765 }
120766 
120767 
120768 /*
120769 ** Checkpoint database zDb. If zDb is NULL, or if the buffer zDb points
120770 ** to contains a zero-length string, all attached databases are 
120771 ** checkpointed.
120772 */
120773 SQLITE_API int sqlite3_wal_checkpoint(sqlite3 *db, const char *zDb){
120774   return sqlite3_wal_checkpoint_v2(db, zDb, SQLITE_CHECKPOINT_PASSIVE, 0, 0);
120775 }
120776 
120777 #ifndef SQLITE_OMIT_WAL
120778 /*
120779 ** Run a checkpoint on database iDb. This is a no-op if database iDb is
120780 ** not currently open in WAL mode.
120781 **
120782 ** If a transaction is open on the database being checkpointed, this 
120783 ** function returns SQLITE_LOCKED and a checkpoint is not attempted. If 
120784 ** an error occurs while running the checkpoint, an SQLite error code is 
120785 ** returned (i.e. SQLITE_IOERR). Otherwise, SQLITE_OK.
120786 **
120787 ** The mutex on database handle db should be held by the caller. The mutex
120788 ** associated with the specific b-tree being checkpointed is taken by
120789 ** this function while the checkpoint is running.
120790 **
120791 ** If iDb is passed SQLITE_MAX_ATTACHED, then all attached databases are
120792 ** checkpointed. If an error is encountered it is returned immediately -
120793 ** no attempt is made to checkpoint any remaining databases.
120794 **
120795 ** Parameter eMode is one of SQLITE_CHECKPOINT_PASSIVE, FULL or RESTART.
120796 */
120797 SQLITE_PRIVATE int sqlite3Checkpoint(sqlite3 *db, int iDb, int eMode, int *pnLog, int *pnCkpt){
120798   int rc = SQLITE_OK;             /* Return code */
120799   int i;                          /* Used to iterate through attached dbs */
120800   int bBusy = 0;                  /* True if SQLITE_BUSY has been encountered */
120801 
120802   assert( sqlite3_mutex_held(db->mutex) );
120803   assert( !pnLog || *pnLog==-1 );
120804   assert( !pnCkpt || *pnCkpt==-1 );
120805 
120806   for(i=0; i<db->nDb && rc==SQLITE_OK; i++){
120807     if( i==iDb || iDb==SQLITE_MAX_ATTACHED ){
120808       rc = sqlite3BtreeCheckpoint(db->aDb[i].pBt, eMode, pnLog, pnCkpt);
120809       pnLog = 0;
120810       pnCkpt = 0;
120811       if( rc==SQLITE_BUSY ){
120812         bBusy = 1;
120813         rc = SQLITE_OK;
120814       }
120815     }
120816   }
120817 
120818   return (rc==SQLITE_OK && bBusy) ? SQLITE_BUSY : rc;
120819 }
120820 #endif /* SQLITE_OMIT_WAL */
120821 
120822 /*
120823 ** This function returns true if main-memory should be used instead of
120824 ** a temporary file for transient pager files and statement journals.
120825 ** The value returned depends on the value of db->temp_store (runtime
120826 ** parameter) and the compile time value of SQLITE_TEMP_STORE. The
120827 ** following table describes the relationship between these two values
120828 ** and this functions return value.
120829 **
120830 **   SQLITE_TEMP_STORE     db->temp_store     Location of temporary database
120831 **   -----------------     --------------     ------------------------------
120832 **   0                     any                file      (return 0)
120833 **   1                     1                  file      (return 0)
120834 **   1                     2                  memory    (return 1)
120835 **   1                     0                  file      (return 0)
120836 **   2                     1                  file      (return 0)
120837 **   2                     2                  memory    (return 1)
120838 **   2                     0                  memory    (return 1)
120839 **   3                     any                memory    (return 1)
120840 */
120841 SQLITE_PRIVATE int sqlite3TempInMemory(const sqlite3 *db){
120842 #if SQLITE_TEMP_STORE==1
120843   return ( db->temp_store==2 );
120844 #endif
120845 #if SQLITE_TEMP_STORE==2
120846   return ( db->temp_store!=1 );
120847 #endif
120848 #if SQLITE_TEMP_STORE==3
120849   return 1;
120850 #endif
120851 #if SQLITE_TEMP_STORE<1 || SQLITE_TEMP_STORE>3
120852   return 0;
120853 #endif
120854 }
120855 
120856 /*
120857 ** Return UTF-8 encoded English language explanation of the most recent
120858 ** error.
120859 */
120860 SQLITE_API const char *sqlite3_errmsg(sqlite3 *db){
120861   const char *z;
120862   if( !db ){
120863     return sqlite3ErrStr(SQLITE_NOMEM);
120864   }
120865   if( !sqlite3SafetyCheckSickOrOk(db) ){
120866     return sqlite3ErrStr(SQLITE_MISUSE_BKPT);
120867   }
120868   sqlite3_mutex_enter(db->mutex);
120869   if( db->mallocFailed ){
120870     z = sqlite3ErrStr(SQLITE_NOMEM);
120871   }else{
120872     z = (char*)sqlite3_value_text(db->pErr);
120873     assert( !db->mallocFailed );
120874     if( z==0 ){
120875       z = sqlite3ErrStr(db->errCode);
120876     }
120877   }
120878   sqlite3_mutex_leave(db->mutex);
120879   return z;
120880 }
120881 
120882 #ifndef SQLITE_OMIT_UTF16
120883 /*
120884 ** Return UTF-16 encoded English language explanation of the most recent
120885 ** error.
120886 */
120887 SQLITE_API const void *sqlite3_errmsg16(sqlite3 *db){
120888   static const u16 outOfMem[] = {
120889     'o', 'u', 't', ' ', 'o', 'f', ' ', 'm', 'e', 'm', 'o', 'r', 'y', 0
120890   };
120891   static const u16 misuse[] = {
120892     'l', 'i', 'b', 'r', 'a', 'r', 'y', ' ', 
120893     'r', 'o', 'u', 't', 'i', 'n', 'e', ' ', 
120894     'c', 'a', 'l', 'l', 'e', 'd', ' ', 
120895     'o', 'u', 't', ' ', 
120896     'o', 'f', ' ', 
120897     's', 'e', 'q', 'u', 'e', 'n', 'c', 'e', 0
120898   };
120899 
120900   const void *z;
120901   if( !db ){
120902     return (void *)outOfMem;
120903   }
120904   if( !sqlite3SafetyCheckSickOrOk(db) ){
120905     return (void *)misuse;
120906   }
120907   sqlite3_mutex_enter(db->mutex);
120908   if( db->mallocFailed ){
120909     z = (void *)outOfMem;
120910   }else{
120911     z = sqlite3_value_text16(db->pErr);
120912     if( z==0 ){
120913       sqlite3ValueSetStr(db->pErr, -1, sqlite3ErrStr(db->errCode),
120914            SQLITE_UTF8, SQLITE_STATIC);
120915       z = sqlite3_value_text16(db->pErr);
120916     }
120917     /* A malloc() may have failed within the call to sqlite3_value_text16()
120918     ** above. If this is the case, then the db->mallocFailed flag needs to
120919     ** be cleared before returning. Do this directly, instead of via
120920     ** sqlite3ApiExit(), to avoid setting the database handle error message.
120921     */
120922     db->mallocFailed = 0;
120923   }
120924   sqlite3_mutex_leave(db->mutex);
120925   return z;
120926 }
120927 #endif /* SQLITE_OMIT_UTF16 */
120928 
120929 /*
120930 ** Return the most recent error code generated by an SQLite routine. If NULL is
120931 ** passed to this function, we assume a malloc() failed during sqlite3_open().
120932 */
120933 SQLITE_API int sqlite3_errcode(sqlite3 *db){
120934   if( db && !sqlite3SafetyCheckSickOrOk(db) ){
120935     return SQLITE_MISUSE_BKPT;
120936   }
120937   if( !db || db->mallocFailed ){
120938     return SQLITE_NOMEM;
120939   }
120940   return db->errCode & db->errMask;
120941 }
120942 SQLITE_API int sqlite3_extended_errcode(sqlite3 *db){
120943   if( db && !sqlite3SafetyCheckSickOrOk(db) ){
120944     return SQLITE_MISUSE_BKPT;
120945   }
120946   if( !db || db->mallocFailed ){
120947     return SQLITE_NOMEM;
120948   }
120949   return db->errCode;
120950 }
120951 
120952 /*
120953 ** Return a string that describes the kind of error specified in the
120954 ** argument.  For now, this simply calls the internal sqlite3ErrStr()
120955 ** function.
120956 */
120957 SQLITE_API const char *sqlite3_errstr(int rc){
120958   return sqlite3ErrStr(rc);
120959 }
120960 
120961 /*
120962 ** Invalidate all cached KeyInfo objects for database connection "db"
120963 */
120964 static void invalidateCachedKeyInfo(sqlite3 *db){
120965   Db *pDb;                    /* A single database */
120966   int iDb;                    /* The database index number */
120967   HashElem *k;                /* For looping over tables in pDb */
120968   Table *pTab;                /* A table in the database */
120969   Index *pIdx;                /* Each index */
120970 
120971   for(iDb=0, pDb=db->aDb; iDb<db->nDb; iDb++, pDb++){
120972     if( pDb->pBt==0 ) continue;
120973     sqlite3BtreeEnter(pDb->pBt);
120974     for(k=sqliteHashFirst(&pDb->pSchema->tblHash);  k; k=sqliteHashNext(k)){
120975       pTab = (Table*)sqliteHashData(k);
120976       for(pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext){
120977         if( pIdx->pKeyInfo && pIdx->pKeyInfo->db==db ){
120978           sqlite3KeyInfoUnref(pIdx->pKeyInfo);
120979           pIdx->pKeyInfo = 0;
120980         }
120981       }
120982     }
120983     sqlite3BtreeLeave(pDb->pBt);
120984   }
120985 }
120986 
120987 /*
120988 ** Create a new collating function for database "db".  The name is zName
120989 ** and the encoding is enc.
120990 */
120991 static int createCollation(
120992   sqlite3* db,
120993   const char *zName, 
120994   u8 enc,
120995   void* pCtx,
120996   int(*xCompare)(void*,int,const void*,int,const void*),
120997   void(*xDel)(void*)
120998 ){
120999   CollSeq *pColl;
121000   int enc2;
121001   int nName = sqlite3Strlen30(zName);
121002   
121003   assert( sqlite3_mutex_held(db->mutex) );
121004 
121005   /* If SQLITE_UTF16 is specified as the encoding type, transform this
121006   ** to one of SQLITE_UTF16LE or SQLITE_UTF16BE using the
121007   ** SQLITE_UTF16NATIVE macro. SQLITE_UTF16 is not used internally.
121008   */
121009   enc2 = enc;
121010   testcase( enc2==SQLITE_UTF16 );
121011   testcase( enc2==SQLITE_UTF16_ALIGNED );
121012   if( enc2==SQLITE_UTF16 || enc2==SQLITE_UTF16_ALIGNED ){
121013     enc2 = SQLITE_UTF16NATIVE;
121014   }
121015   if( enc2<SQLITE_UTF8 || enc2>SQLITE_UTF16BE ){
121016     return SQLITE_MISUSE_BKPT;
121017   }
121018 
121019   /* Check if this call is removing or replacing an existing collation 
121020   ** sequence. If so, and there are active VMs, return busy. If there
121021   ** are no active VMs, invalidate any pre-compiled statements.
121022   */
121023   pColl = sqlite3FindCollSeq(db, (u8)enc2, zName, 0);
121024   if( pColl && pColl->xCmp ){
121025     if( db->nVdbeActive ){
121026       sqlite3Error(db, SQLITE_BUSY, 
121027         "unable to delete/modify collation sequence due to active statements");
121028       return SQLITE_BUSY;
121029     }
121030     sqlite3ExpirePreparedStatements(db);
121031     invalidateCachedKeyInfo(db);
121032 
121033     /* If collation sequence pColl was created directly by a call to
121034     ** sqlite3_create_collation, and not generated by synthCollSeq(),
121035     ** then any copies made by synthCollSeq() need to be invalidated.
121036     ** Also, collation destructor - CollSeq.xDel() - function may need
121037     ** to be called.
121038     */ 
121039     if( (pColl->enc & ~SQLITE_UTF16_ALIGNED)==enc2 ){
121040       CollSeq *aColl = sqlite3HashFind(&db->aCollSeq, zName, nName);
121041       int j;
121042       for(j=0; j<3; j++){
121043         CollSeq *p = &aColl[j];
121044         if( p->enc==pColl->enc ){
121045           if( p->xDel ){
121046             p->xDel(p->pUser);
121047           }
121048           p->xCmp = 0;
121049         }
121050       }
121051     }
121052   }
121053 
121054   pColl = sqlite3FindCollSeq(db, (u8)enc2, zName, 1);
121055   if( pColl==0 ) return SQLITE_NOMEM;
121056   pColl->xCmp = xCompare;
121057   pColl->pUser = pCtx;
121058   pColl->xDel = xDel;
121059   pColl->enc = (u8)(enc2 | (enc & SQLITE_UTF16_ALIGNED));
121060   sqlite3Error(db, SQLITE_OK, 0);
121061   return SQLITE_OK;
121062 }
121063 
121064 
121065 /*
121066 ** This array defines hard upper bounds on limit values.  The
121067 ** initializer must be kept in sync with the SQLITE_LIMIT_*
121068 ** #defines in sqlite3.h.
121069 */
121070 static const int aHardLimit[] = {
121071   SQLITE_MAX_LENGTH,
121072   SQLITE_MAX_SQL_LENGTH,
121073   SQLITE_MAX_COLUMN,
121074   SQLITE_MAX_EXPR_DEPTH,
121075   SQLITE_MAX_COMPOUND_SELECT,
121076   SQLITE_MAX_VDBE_OP,
121077   SQLITE_MAX_FUNCTION_ARG,
121078   SQLITE_MAX_ATTACHED,
121079   SQLITE_MAX_LIKE_PATTERN_LENGTH,
121080   SQLITE_MAX_VARIABLE_NUMBER,
121081   SQLITE_MAX_TRIGGER_DEPTH,
121082 };
121083 
121084 /*
121085 ** Make sure the hard limits are set to reasonable values
121086 */
121087 #if SQLITE_MAX_LENGTH<100
121088 # error SQLITE_MAX_LENGTH must be at least 100
121089 #endif
121090 #if SQLITE_MAX_SQL_LENGTH<100
121091 # error SQLITE_MAX_SQL_LENGTH must be at least 100
121092 #endif
121093 #if SQLITE_MAX_SQL_LENGTH>SQLITE_MAX_LENGTH
121094 # error SQLITE_MAX_SQL_LENGTH must not be greater than SQLITE_MAX_LENGTH
121095 #endif
121096 #if SQLITE_MAX_COMPOUND_SELECT<2
121097 # error SQLITE_MAX_COMPOUND_SELECT must be at least 2
121098 #endif
121099 #if SQLITE_MAX_VDBE_OP<40
121100 # error SQLITE_MAX_VDBE_OP must be at least 40
121101 #endif
121102 #if SQLITE_MAX_FUNCTION_ARG<0 || SQLITE_MAX_FUNCTION_ARG>1000
121103 # error SQLITE_MAX_FUNCTION_ARG must be between 0 and 1000
121104 #endif
121105 #if SQLITE_MAX_ATTACHED<0 || SQLITE_MAX_ATTACHED>62
121106 # error SQLITE_MAX_ATTACHED must be between 0 and 62
121107 #endif
121108 #if SQLITE_MAX_LIKE_PATTERN_LENGTH<1
121109 # error SQLITE_MAX_LIKE_PATTERN_LENGTH must be at least 1
121110 #endif
121111 #if SQLITE_MAX_COLUMN>32767
121112 # error SQLITE_MAX_COLUMN must not exceed 32767
121113 #endif
121114 #if SQLITE_MAX_TRIGGER_DEPTH<1
121115 # error SQLITE_MAX_TRIGGER_DEPTH must be at least 1
121116 #endif
121117 
121118 
121119 /*
121120 ** Change the value of a limit.  Report the old value.
121121 ** If an invalid limit index is supplied, report -1.
121122 ** Make no changes but still report the old value if the
121123 ** new limit is negative.
121124 **
121125 ** A new lower limit does not shrink existing constructs.
121126 ** It merely prevents new constructs that exceed the limit
121127 ** from forming.
121128 */
121129 SQLITE_API int sqlite3_limit(sqlite3 *db, int limitId, int newLimit){
121130   int oldLimit;
121131 
121132 
121133   /* EVIDENCE-OF: R-30189-54097 For each limit category SQLITE_LIMIT_NAME
121134   ** there is a hard upper bound set at compile-time by a C preprocessor
121135   ** macro called SQLITE_MAX_NAME. (The "_LIMIT_" in the name is changed to
121136   ** "_MAX_".)
121137   */
121138   assert( aHardLimit[SQLITE_LIMIT_LENGTH]==SQLITE_MAX_LENGTH );
121139   assert( aHardLimit[SQLITE_LIMIT_SQL_LENGTH]==SQLITE_MAX_SQL_LENGTH );
121140   assert( aHardLimit[SQLITE_LIMIT_COLUMN]==SQLITE_MAX_COLUMN );
121141   assert( aHardLimit[SQLITE_LIMIT_EXPR_DEPTH]==SQLITE_MAX_EXPR_DEPTH );
121142   assert( aHardLimit[SQLITE_LIMIT_COMPOUND_SELECT]==SQLITE_MAX_COMPOUND_SELECT);
121143   assert( aHardLimit[SQLITE_LIMIT_VDBE_OP]==SQLITE_MAX_VDBE_OP );
121144   assert( aHardLimit[SQLITE_LIMIT_FUNCTION_ARG]==SQLITE_MAX_FUNCTION_ARG );
121145   assert( aHardLimit[SQLITE_LIMIT_ATTACHED]==SQLITE_MAX_ATTACHED );
121146   assert( aHardLimit[SQLITE_LIMIT_LIKE_PATTERN_LENGTH]==
121147                                                SQLITE_MAX_LIKE_PATTERN_LENGTH );
121148   assert( aHardLimit[SQLITE_LIMIT_VARIABLE_NUMBER]==SQLITE_MAX_VARIABLE_NUMBER);
121149   assert( aHardLimit[SQLITE_LIMIT_TRIGGER_DEPTH]==SQLITE_MAX_TRIGGER_DEPTH );
121150   assert( SQLITE_LIMIT_TRIGGER_DEPTH==(SQLITE_N_LIMIT-1) );
121151 
121152 
121153   if( limitId<0 || limitId>=SQLITE_N_LIMIT ){
121154     return -1;
121155   }
121156   oldLimit = db->aLimit[limitId];
121157   if( newLimit>=0 ){                   /* IMP: R-52476-28732 */
121158     if( newLimit>aHardLimit[limitId] ){
121159       newLimit = aHardLimit[limitId];  /* IMP: R-51463-25634 */
121160     }
121161     db->aLimit[limitId] = newLimit;
121162   }
121163   return oldLimit;                     /* IMP: R-53341-35419 */
121164 }
121165 
121166 /*
121167 ** This function is used to parse both URIs and non-URI filenames passed by the
121168 ** user to API functions sqlite3_open() or sqlite3_open_v2(), and for database
121169 ** URIs specified as part of ATTACH statements.
121170 **
121171 ** The first argument to this function is the name of the VFS to use (or
121172 ** a NULL to signify the default VFS) if the URI does not contain a "vfs=xxx"
121173 ** query parameter. The second argument contains the URI (or non-URI filename)
121174 ** itself. When this function is called the *pFlags variable should contain
121175 ** the default flags to open the database handle with. The value stored in
121176 ** *pFlags may be updated before returning if the URI filename contains 
121177 ** "cache=xxx" or "mode=xxx" query parameters.
121178 **
121179 ** If successful, SQLITE_OK is returned. In this case *ppVfs is set to point to
121180 ** the VFS that should be used to open the database file. *pzFile is set to
121181 ** point to a buffer containing the name of the file to open. It is the 
121182 ** responsibility of the caller to eventually call sqlite3_free() to release
121183 ** this buffer.
121184 **
121185 ** If an error occurs, then an SQLite error code is returned and *pzErrMsg
121186 ** may be set to point to a buffer containing an English language error 
121187 ** message. It is the responsibility of the caller to eventually release
121188 ** this buffer by calling sqlite3_free().
121189 */
121190 SQLITE_PRIVATE int sqlite3ParseUri(
121191   const char *zDefaultVfs,        /* VFS to use if no "vfs=xxx" query option */
121192   const char *zUri,               /* Nul-terminated URI to parse */
121193   unsigned int *pFlags,           /* IN/OUT: SQLITE_OPEN_XXX flags */
121194   sqlite3_vfs **ppVfs,            /* OUT: VFS to use */ 
121195   char **pzFile,                  /* OUT: Filename component of URI */
121196   char **pzErrMsg                 /* OUT: Error message (if rc!=SQLITE_OK) */
121197 ){
121198   int rc = SQLITE_OK;
121199   unsigned int flags = *pFlags;
121200   const char *zVfs = zDefaultVfs;
121201   char *zFile;
121202   char c;
121203   int nUri = sqlite3Strlen30(zUri);
121204 
121205   assert( *pzErrMsg==0 );
121206 
121207   if( ((flags & SQLITE_OPEN_URI) || sqlite3GlobalConfig.bOpenUri) 
121208    && nUri>=5 && memcmp(zUri, "file:", 5)==0 
121209   ){
121210     char *zOpt;
121211     int eState;                   /* Parser state when parsing URI */
121212     int iIn;                      /* Input character index */
121213     int iOut = 0;                 /* Output character index */
121214     int nByte = nUri+2;           /* Bytes of space to allocate */
121215 
121216     /* Make sure the SQLITE_OPEN_URI flag is set to indicate to the VFS xOpen 
121217     ** method that there may be extra parameters following the file-name.  */
121218     flags |= SQLITE_OPEN_URI;
121219 
121220     for(iIn=0; iIn<nUri; iIn++) nByte += (zUri[iIn]=='&');
121221     zFile = sqlite3_malloc(nByte);
121222     if( !zFile ) return SQLITE_NOMEM;
121223 
121224     iIn = 5;
121225 #ifndef SQLITE_ALLOW_URI_AUTHORITY
121226     /* Discard the scheme and authority segments of the URI. */
121227     if( zUri[5]=='/' && zUri[6]=='/' ){
121228       iIn = 7;
121229       while( zUri[iIn] && zUri[iIn]!='/' ) iIn++;
121230       if( iIn!=7 && (iIn!=16 || memcmp("localhost", &zUri[7], 9)) ){
121231         *pzErrMsg = sqlite3_mprintf("invalid uri authority: %.*s", 
121232             iIn-7, &zUri[7]);
121233         rc = SQLITE_ERROR;
121234         goto parse_uri_out;
121235       }
121236     }
121237 #endif
121238 
121239     /* Copy the filename and any query parameters into the zFile buffer. 
121240     ** Decode %HH escape codes along the way. 
121241     **
121242     ** Within this loop, variable eState may be set to 0, 1 or 2, depending
121243     ** on the parsing context. As follows:
121244     **
121245     **   0: Parsing file-name.
121246     **   1: Parsing name section of a name=value query parameter.
121247     **   2: Parsing value section of a name=value query parameter.
121248     */
121249     eState = 0;
121250     while( (c = zUri[iIn])!=0 && c!='#' ){
121251       iIn++;
121252       if( c=='%' 
121253        && sqlite3Isxdigit(zUri[iIn]) 
121254        && sqlite3Isxdigit(zUri[iIn+1]) 
121255       ){
121256         int octet = (sqlite3HexToInt(zUri[iIn++]) << 4);
121257         octet += sqlite3HexToInt(zUri[iIn++]);
121258 
121259         assert( octet>=0 && octet<256 );
121260         if( octet==0 ){
121261           /* This branch is taken when "%00" appears within the URI. In this
121262           ** case we ignore all text in the remainder of the path, name or
121263           ** value currently being parsed. So ignore the current character
121264           ** and skip to the next "?", "=" or "&", as appropriate. */
121265           while( (c = zUri[iIn])!=0 && c!='#' 
121266               && (eState!=0 || c!='?')
121267               && (eState!=1 || (c!='=' && c!='&'))
121268               && (eState!=2 || c!='&')
121269           ){
121270             iIn++;
121271           }
121272           continue;
121273         }
121274         c = octet;
121275       }else if( eState==1 && (c=='&' || c=='=') ){
121276         if( zFile[iOut-1]==0 ){
121277           /* An empty option name. Ignore this option altogether. */
121278           while( zUri[iIn] && zUri[iIn]!='#' && zUri[iIn-1]!='&' ) iIn++;
121279           continue;
121280         }
121281         if( c=='&' ){
121282           zFile[iOut++] = '\0';
121283         }else{
121284           eState = 2;
121285         }
121286         c = 0;
121287       }else if( (eState==0 && c=='?') || (eState==2 && c=='&') ){
121288         c = 0;
121289         eState = 1;
121290       }
121291       zFile[iOut++] = c;
121292     }
121293     if( eState==1 ) zFile[iOut++] = '\0';
121294     zFile[iOut++] = '\0';
121295     zFile[iOut++] = '\0';
121296 
121297     /* Check if there were any options specified that should be interpreted 
121298     ** here. Options that are interpreted here include "vfs" and those that
121299     ** correspond to flags that may be passed to the sqlite3_open_v2()
121300     ** method. */
121301     zOpt = &zFile[sqlite3Strlen30(zFile)+1];
121302     while( zOpt[0] ){
121303       int nOpt = sqlite3Strlen30(zOpt);
121304       char *zVal = &zOpt[nOpt+1];
121305       int nVal = sqlite3Strlen30(zVal);
121306 
121307       if( nOpt==3 && memcmp("vfs", zOpt, 3)==0 ){
121308         zVfs = zVal;
121309       }else{
121310         struct OpenMode {
121311           const char *z;
121312           int mode;
121313         } *aMode = 0;
121314         char *zModeType = 0;
121315         int mask = 0;
121316         int limit = 0;
121317 
121318         if( nOpt==5 && memcmp("cache", zOpt, 5)==0 ){
121319           static struct OpenMode aCacheMode[] = {
121320             { "shared",  SQLITE_OPEN_SHAREDCACHE },
121321             { "private", SQLITE_OPEN_PRIVATECACHE },
121322             { 0, 0 }
121323           };
121324 
121325           mask = SQLITE_OPEN_SHAREDCACHE|SQLITE_OPEN_PRIVATECACHE;
121326           aMode = aCacheMode;
121327           limit = mask;
121328           zModeType = "cache";
121329         }
121330         if( nOpt==4 && memcmp("mode", zOpt, 4)==0 ){
121331           static struct OpenMode aOpenMode[] = {
121332             { "ro",  SQLITE_OPEN_READONLY },
121333             { "rw",  SQLITE_OPEN_READWRITE }, 
121334             { "rwc", SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE },
121335             { "memory", SQLITE_OPEN_MEMORY },
121336             { 0, 0 }
121337           };
121338 
121339           mask = SQLITE_OPEN_READONLY | SQLITE_OPEN_READWRITE
121340                    | SQLITE_OPEN_CREATE | SQLITE_OPEN_MEMORY;
121341           aMode = aOpenMode;
121342           limit = mask & flags;
121343           zModeType = "access";
121344         }
121345 
121346         if( aMode ){
121347           int i;
121348           int mode = 0;
121349           for(i=0; aMode[i].z; i++){
121350             const char *z = aMode[i].z;
121351             if( nVal==sqlite3Strlen30(z) && 0==memcmp(zVal, z, nVal) ){
121352               mode = aMode[i].mode;
121353               break;
121354             }
121355           }
121356           if( mode==0 ){
121357             *pzErrMsg = sqlite3_mprintf("no such %s mode: %s", zModeType, zVal);
121358             rc = SQLITE_ERROR;
121359             goto parse_uri_out;
121360           }
121361           if( (mode & ~SQLITE_OPEN_MEMORY)>limit ){
121362             *pzErrMsg = sqlite3_mprintf("%s mode not allowed: %s",
121363                                         zModeType, zVal);
121364             rc = SQLITE_PERM;
121365             goto parse_uri_out;
121366           }
121367           flags = (flags & ~mask) | mode;
121368         }
121369       }
121370 
121371       zOpt = &zVal[nVal+1];
121372     }
121373 
121374   }else{
121375     zFile = sqlite3_malloc(nUri+2);
121376     if( !zFile ) return SQLITE_NOMEM;
121377     memcpy(zFile, zUri, nUri);
121378     zFile[nUri] = '\0';
121379     zFile[nUri+1] = '\0';
121380     flags &= ~SQLITE_OPEN_URI;
121381   }
121382 
121383   *ppVfs = sqlite3_vfs_find(zVfs);
121384   if( *ppVfs==0 ){
121385     *pzErrMsg = sqlite3_mprintf("no such vfs: %s", zVfs);
121386     rc = SQLITE_ERROR;
121387   }
121388  parse_uri_out:
121389   if( rc!=SQLITE_OK ){
121390     sqlite3_free(zFile);
121391     zFile = 0;
121392   }
121393   *pFlags = flags;
121394   *pzFile = zFile;
121395   return rc;
121396 }
121397 
121398 
121399 /*
121400 ** This routine does the work of opening a database on behalf of
121401 ** sqlite3_open() and sqlite3_open16(). The database filename "zFilename"  
121402 ** is UTF-8 encoded.
121403 */
121404 static int openDatabase(
121405   const char *zFilename, /* Database filename UTF-8 encoded */
121406   sqlite3 **ppDb,        /* OUT: Returned database handle */
121407   unsigned int flags,    /* Operational flags */
121408   const char *zVfs       /* Name of the VFS to use */
121409 ){
121410   sqlite3 *db;                    /* Store allocated handle here */
121411   int rc;                         /* Return code */
121412   int isThreadsafe;               /* True for threadsafe connections */
121413   char *zOpen = 0;                /* Filename argument to pass to BtreeOpen() */
121414   char *zErrMsg = 0;              /* Error message from sqlite3ParseUri() */
121415 
121416   *ppDb = 0;
121417 #ifndef SQLITE_OMIT_AUTOINIT
121418   rc = sqlite3_initialize();
121419   if( rc ) return rc;
121420 #endif
121421 
121422   /* Only allow sensible combinations of bits in the flags argument.  
121423   ** Throw an error if any non-sense combination is used.  If we
121424   ** do not block illegal combinations here, it could trigger
121425   ** assert() statements in deeper layers.  Sensible combinations
121426   ** are:
121427   **
121428   **  1:  SQLITE_OPEN_READONLY
121429   **  2:  SQLITE_OPEN_READWRITE
121430   **  6:  SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE
121431   */
121432   assert( SQLITE_OPEN_READONLY  == 0x01 );
121433   assert( SQLITE_OPEN_READWRITE == 0x02 );
121434   assert( SQLITE_OPEN_CREATE    == 0x04 );
121435   testcase( (1<<(flags&7))==0x02 ); /* READONLY */
121436   testcase( (1<<(flags&7))==0x04 ); /* READWRITE */
121437   testcase( (1<<(flags&7))==0x40 ); /* READWRITE | CREATE */
121438   if( ((1<<(flags&7)) & 0x46)==0 ) return SQLITE_MISUSE_BKPT;
121439 
121440   if( sqlite3GlobalConfig.bCoreMutex==0 ){
121441     isThreadsafe = 0;
121442   }else if( flags & SQLITE_OPEN_NOMUTEX ){
121443     isThreadsafe = 0;
121444   }else if( flags & SQLITE_OPEN_FULLMUTEX ){
121445     isThreadsafe = 1;
121446   }else{
121447     isThreadsafe = sqlite3GlobalConfig.bFullMutex;
121448   }
121449   if( flags & SQLITE_OPEN_PRIVATECACHE ){
121450     flags &= ~SQLITE_OPEN_SHAREDCACHE;
121451   }else if( sqlite3GlobalConfig.sharedCacheEnabled ){
121452     flags |= SQLITE_OPEN_SHAREDCACHE;
121453   }
121454 
121455   /* Remove harmful bits from the flags parameter
121456   **
121457   ** The SQLITE_OPEN_NOMUTEX and SQLITE_OPEN_FULLMUTEX flags were
121458   ** dealt with in the previous code block.  Besides these, the only
121459   ** valid input flags for sqlite3_open_v2() are SQLITE_OPEN_READONLY,
121460   ** SQLITE_OPEN_READWRITE, SQLITE_OPEN_CREATE, SQLITE_OPEN_SHAREDCACHE,
121461   ** SQLITE_OPEN_PRIVATECACHE, and some reserved bits.  Silently mask
121462   ** off all other flags.
121463   */
121464   flags &=  ~( SQLITE_OPEN_DELETEONCLOSE |
121465                SQLITE_OPEN_EXCLUSIVE |
121466                SQLITE_OPEN_MAIN_DB |
121467                SQLITE_OPEN_TEMP_DB | 
121468                SQLITE_OPEN_TRANSIENT_DB | 
121469                SQLITE_OPEN_MAIN_JOURNAL | 
121470                SQLITE_OPEN_TEMP_JOURNAL | 
121471                SQLITE_OPEN_SUBJOURNAL | 
121472                SQLITE_OPEN_MASTER_JOURNAL |
121473                SQLITE_OPEN_NOMUTEX |
121474                SQLITE_OPEN_FULLMUTEX |
121475                SQLITE_OPEN_WAL
121476              );
121477 
121478   /* Allocate the sqlite data structure */
121479   db = sqlite3MallocZero( sizeof(sqlite3) );
121480   if( db==0 ) goto opendb_out;
121481   if( isThreadsafe ){
121482     db->mutex = sqlite3MutexAlloc(SQLITE_MUTEX_RECURSIVE);
121483     if( db->mutex==0 ){
121484       sqlite3_free(db);
121485       db = 0;
121486       goto opendb_out;
121487     }
121488   }
121489   sqlite3_mutex_enter(db->mutex);
121490   db->errMask = 0xff;
121491   db->nDb = 2;
121492   db->magic = SQLITE_MAGIC_BUSY;
121493   db->aDb = db->aDbStatic;
121494 
121495   assert( sizeof(db->aLimit)==sizeof(aHardLimit) );
121496   memcpy(db->aLimit, aHardLimit, sizeof(db->aLimit));
121497   db->autoCommit = 1;
121498   db->nextAutovac = -1;
121499   db->szMmap = sqlite3GlobalConfig.szMmap;
121500   db->nextPagesize = 0;
121501   db->flags |= SQLITE_ShortColNames | SQLITE_EnableTrigger | SQLITE_CacheSpill
121502 #if !defined(SQLITE_DEFAULT_AUTOMATIC_INDEX) || SQLITE_DEFAULT_AUTOMATIC_INDEX
121503                  | SQLITE_AutoIndex
121504 #endif
121505 #if SQLITE_DEFAULT_FILE_FORMAT<4
121506                  | SQLITE_LegacyFileFmt
121507 #endif
121508 #ifdef SQLITE_ENABLE_LOAD_EXTENSION
121509                  | SQLITE_LoadExtension
121510 #endif
121511 #if SQLITE_DEFAULT_RECURSIVE_TRIGGERS
121512                  | SQLITE_RecTriggers
121513 #endif
121514 #if defined(SQLITE_DEFAULT_FOREIGN_KEYS) && SQLITE_DEFAULT_FOREIGN_KEYS
121515                  | SQLITE_ForeignKeys
121516 #endif
121517       ;
121518   sqlite3HashInit(&db->aCollSeq);
121519 #ifndef SQLITE_OMIT_VIRTUALTABLE
121520   sqlite3HashInit(&db->aModule);
121521 #endif
121522 
121523   /* Add the default collation sequence BINARY. BINARY works for both UTF-8
121524   ** and UTF-16, so add a version for each to avoid any unnecessary
121525   ** conversions. The only error that can occur here is a malloc() failure.
121526   */
121527   createCollation(db, "BINARY", SQLITE_UTF8, 0, binCollFunc, 0);
121528   createCollation(db, "BINARY", SQLITE_UTF16BE, 0, binCollFunc, 0);
121529   createCollation(db, "BINARY", SQLITE_UTF16LE, 0, binCollFunc, 0);
121530   createCollation(db, "RTRIM", SQLITE_UTF8, (void*)1, binCollFunc, 0);
121531   if( db->mallocFailed ){
121532     goto opendb_out;
121533   }
121534   db->pDfltColl = sqlite3FindCollSeq(db, SQLITE_UTF8, "BINARY", 0);
121535   assert( db->pDfltColl!=0 );
121536 
121537   /* Also add a UTF-8 case-insensitive collation sequence. */
121538   createCollation(db, "NOCASE", SQLITE_UTF8, 0, nocaseCollatingFunc, 0);
121539 
121540   /* Parse the filename/URI argument. */
121541   db->openFlags = flags;
121542   rc = sqlite3ParseUri(zVfs, zFilename, &flags, &db->pVfs, &zOpen, &zErrMsg);
121543   if( rc!=SQLITE_OK ){
121544     if( rc==SQLITE_NOMEM ) db->mallocFailed = 1;
121545     sqlite3Error(db, rc, zErrMsg ? "%s" : 0, zErrMsg);
121546     sqlite3_free(zErrMsg);
121547     goto opendb_out;
121548   }
121549 
121550   /* Open the backend database driver */
121551   rc = sqlite3BtreeOpen(db->pVfs, zOpen, db, &db->aDb[0].pBt, 0,
121552                         flags | SQLITE_OPEN_MAIN_DB);
121553   if( rc!=SQLITE_OK ){
121554     if( rc==SQLITE_IOERR_NOMEM ){
121555       rc = SQLITE_NOMEM;
121556     }
121557     sqlite3Error(db, rc, 0);
121558     goto opendb_out;
121559   }
121560   db->aDb[0].pSchema = sqlite3SchemaGet(db, db->aDb[0].pBt);
121561   db->aDb[1].pSchema = sqlite3SchemaGet(db, 0);
121562 
121563 
121564   /* The default safety_level for the main database is 'full'; for the temp
121565   ** database it is 'NONE'. This matches the pager layer defaults.  
121566   */
121567   db->aDb[0].zName = "main";
121568   db->aDb[0].safety_level = 3;
121569   db->aDb[1].zName = "temp";
121570   db->aDb[1].safety_level = 1;
121571 
121572   db->magic = SQLITE_MAGIC_OPEN;
121573   if( db->mallocFailed ){
121574     goto opendb_out;
121575   }
121576 
121577   /* Register all built-in functions, but do not attempt to read the
121578   ** database schema yet. This is delayed until the first time the database
121579   ** is accessed.
121580   */
121581   sqlite3Error(db, SQLITE_OK, 0);
121582   sqlite3RegisterBuiltinFunctions(db);
121583 
121584   /* Load automatic extensions - extensions that have been registered
121585   ** using the sqlite3_automatic_extension() API.
121586   */
121587   rc = sqlite3_errcode(db);
121588   if( rc==SQLITE_OK ){
121589     sqlite3AutoLoadExtensions(db);
121590     rc = sqlite3_errcode(db);
121591     if( rc!=SQLITE_OK ){
121592       goto opendb_out;
121593     }
121594   }
121595 
121596 #ifdef SQLITE_ENABLE_FTS1
121597   if( !db->mallocFailed ){
121598     extern int sqlite3Fts1Init(sqlite3*);
121599     rc = sqlite3Fts1Init(db);
121600   }
121601 #endif
121602 
121603 #ifdef SQLITE_ENABLE_FTS2
121604   if( !db->mallocFailed && rc==SQLITE_OK ){
121605     extern int sqlite3Fts2Init(sqlite3*);
121606     rc = sqlite3Fts2Init(db);
121607   }
121608 #endif
121609 
121610 #ifdef SQLITE_ENABLE_FTS3
121611   if( !db->mallocFailed && rc==SQLITE_OK ){
121612     rc = sqlite3Fts3Init(db);
121613   }
121614 #endif
121615 
121616 #ifdef SQLITE_ENABLE_ICU
121617   if( !db->mallocFailed && rc==SQLITE_OK ){
121618     rc = sqlite3IcuInit(db);
121619   }
121620 #endif
121621 
121622 #ifdef SQLITE_ENABLE_RTREE
121623   if( !db->mallocFailed && rc==SQLITE_OK){
121624     rc = sqlite3RtreeInit(db);
121625   }
121626 #endif
121627 
121628   sqlite3Error(db, rc, 0);
121629 
121630   /* -DSQLITE_DEFAULT_LOCKING_MODE=1 makes EXCLUSIVE the default locking
121631   ** mode.  -DSQLITE_DEFAULT_LOCKING_MODE=0 make NORMAL the default locking
121632   ** mode.  Doing nothing at all also makes NORMAL the default.
121633   */
121634 #ifdef SQLITE_DEFAULT_LOCKING_MODE
121635   db->dfltLockMode = SQLITE_DEFAULT_LOCKING_MODE;
121636   sqlite3PagerLockingMode(sqlite3BtreePager(db->aDb[0].pBt),
121637                           SQLITE_DEFAULT_LOCKING_MODE);
121638 #endif
121639 
121640   /* Enable the lookaside-malloc subsystem */
121641   setupLookaside(db, 0, sqlite3GlobalConfig.szLookaside,
121642                         sqlite3GlobalConfig.nLookaside);
121643 
121644   sqlite3_wal_autocheckpoint(db, SQLITE_DEFAULT_WAL_AUTOCHECKPOINT);
121645 
121646 opendb_out:
121647   sqlite3_free(zOpen);
121648   if( db ){
121649     assert( db->mutex!=0 || isThreadsafe==0 || sqlite3GlobalConfig.bFullMutex==0 );
121650     sqlite3_mutex_leave(db->mutex);
121651   }
121652   rc = sqlite3_errcode(db);
121653   assert( db!=0 || rc==SQLITE_NOMEM );
121654   if( rc==SQLITE_NOMEM ){
121655     sqlite3_close(db);
121656     db = 0;
121657   }else if( rc!=SQLITE_OK ){
121658     db->magic = SQLITE_MAGIC_SICK;
121659   }
121660   *ppDb = db;
121661 #ifdef SQLITE_ENABLE_SQLLOG
121662   if( sqlite3GlobalConfig.xSqllog ){
121663     /* Opening a db handle. Fourth parameter is passed 0. */
121664     void *pArg = sqlite3GlobalConfig.pSqllogArg;
121665     sqlite3GlobalConfig.xSqllog(pArg, db, zFilename, 0);
121666   }
121667 #endif
121668   return sqlite3ApiExit(0, rc);
121669 }
121670 
121671 /*
121672 ** Open a new database handle.
121673 */
121674 SQLITE_API int sqlite3_open(
121675   const char *zFilename, 
121676   sqlite3 **ppDb 
121677 ){
121678   return openDatabase(zFilename, ppDb,
121679                       SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE, 0);
121680 }
121681 SQLITE_API int sqlite3_open_v2(
121682   const char *filename,   /* Database filename (UTF-8) */
121683   sqlite3 **ppDb,         /* OUT: SQLite db handle */
121684   int flags,              /* Flags */
121685   const char *zVfs        /* Name of VFS module to use */
121686 ){
121687   return openDatabase(filename, ppDb, (unsigned int)flags, zVfs);
121688 }
121689 
121690 #ifndef SQLITE_OMIT_UTF16
121691 /*
121692 ** Open a new database handle.
121693 */
121694 SQLITE_API int sqlite3_open16(
121695   const void *zFilename, 
121696   sqlite3 **ppDb
121697 ){
121698   char const *zFilename8;   /* zFilename encoded in UTF-8 instead of UTF-16 */
121699   sqlite3_value *pVal;
121700   int rc;
121701 
121702   assert( zFilename );
121703   assert( ppDb );
121704   *ppDb = 0;
121705 #ifndef SQLITE_OMIT_AUTOINIT
121706   rc = sqlite3_initialize();
121707   if( rc ) return rc;
121708 #endif
121709   pVal = sqlite3ValueNew(0);
121710   sqlite3ValueSetStr(pVal, -1, zFilename, SQLITE_UTF16NATIVE, SQLITE_STATIC);
121711   zFilename8 = sqlite3ValueText(pVal, SQLITE_UTF8);
121712   if( zFilename8 ){
121713     rc = openDatabase(zFilename8, ppDb,
121714                       SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE, 0);
121715     assert( *ppDb || rc==SQLITE_NOMEM );
121716     if( rc==SQLITE_OK && !DbHasProperty(*ppDb, 0, DB_SchemaLoaded) ){
121717       ENC(*ppDb) = SQLITE_UTF16NATIVE;
121718     }
121719   }else{
121720     rc = SQLITE_NOMEM;
121721   }
121722   sqlite3ValueFree(pVal);
121723 
121724   return sqlite3ApiExit(0, rc);
121725 }
121726 #endif /* SQLITE_OMIT_UTF16 */
121727 
121728 /*
121729 ** Register a new collation sequence with the database handle db.
121730 */
121731 SQLITE_API int sqlite3_create_collation(
121732   sqlite3* db, 
121733   const char *zName, 
121734   int enc, 
121735   void* pCtx,
121736   int(*xCompare)(void*,int,const void*,int,const void*)
121737 ){
121738   int rc;
121739   sqlite3_mutex_enter(db->mutex);
121740   assert( !db->mallocFailed );
121741   rc = createCollation(db, zName, (u8)enc, pCtx, xCompare, 0);
121742   rc = sqlite3ApiExit(db, rc);
121743   sqlite3_mutex_leave(db->mutex);
121744   return rc;
121745 }
121746 
121747 /*
121748 ** Register a new collation sequence with the database handle db.
121749 */
121750 SQLITE_API int sqlite3_create_collation_v2(
121751   sqlite3* db, 
121752   const char *zName, 
121753   int enc, 
121754   void* pCtx,
121755   int(*xCompare)(void*,int,const void*,int,const void*),
121756   void(*xDel)(void*)
121757 ){
121758   int rc;
121759   sqlite3_mutex_enter(db->mutex);
121760   assert( !db->mallocFailed );
121761   rc = createCollation(db, zName, (u8)enc, pCtx, xCompare, xDel);
121762   rc = sqlite3ApiExit(db, rc);
121763   sqlite3_mutex_leave(db->mutex);
121764   return rc;
121765 }
121766 
121767 #ifndef SQLITE_OMIT_UTF16
121768 /*
121769 ** Register a new collation sequence with the database handle db.
121770 */
121771 SQLITE_API int sqlite3_create_collation16(
121772   sqlite3* db, 
121773   const void *zName,
121774   int enc, 
121775   void* pCtx,
121776   int(*xCompare)(void*,int,const void*,int,const void*)
121777 ){
121778   int rc = SQLITE_OK;
121779   char *zName8;
121780   sqlite3_mutex_enter(db->mutex);
121781   assert( !db->mallocFailed );
121782   zName8 = sqlite3Utf16to8(db, zName, -1, SQLITE_UTF16NATIVE);
121783   if( zName8 ){
121784     rc = createCollation(db, zName8, (u8)enc, pCtx, xCompare, 0);
121785     sqlite3DbFree(db, zName8);
121786   }
121787   rc = sqlite3ApiExit(db, rc);
121788   sqlite3_mutex_leave(db->mutex);
121789   return rc;
121790 }
121791 #endif /* SQLITE_OMIT_UTF16 */
121792 
121793 /*
121794 ** Register a collation sequence factory callback with the database handle
121795 ** db. Replace any previously installed collation sequence factory.
121796 */
121797 SQLITE_API int sqlite3_collation_needed(
121798   sqlite3 *db, 
121799   void *pCollNeededArg, 
121800   void(*xCollNeeded)(void*,sqlite3*,int eTextRep,const char*)
121801 ){
121802   sqlite3_mutex_enter(db->mutex);
121803   db->xCollNeeded = xCollNeeded;
121804   db->xCollNeeded16 = 0;
121805   db->pCollNeededArg = pCollNeededArg;
121806   sqlite3_mutex_leave(db->mutex);
121807   return SQLITE_OK;
121808 }
121809 
121810 #ifndef SQLITE_OMIT_UTF16
121811 /*
121812 ** Register a collation sequence factory callback with the database handle
121813 ** db. Replace any previously installed collation sequence factory.
121814 */
121815 SQLITE_API int sqlite3_collation_needed16(
121816   sqlite3 *db, 
121817   void *pCollNeededArg, 
121818   void(*xCollNeeded16)(void*,sqlite3*,int eTextRep,const void*)
121819 ){
121820   sqlite3_mutex_enter(db->mutex);
121821   db->xCollNeeded = 0;
121822   db->xCollNeeded16 = xCollNeeded16;
121823   db->pCollNeededArg = pCollNeededArg;
121824   sqlite3_mutex_leave(db->mutex);
121825   return SQLITE_OK;
121826 }
121827 #endif /* SQLITE_OMIT_UTF16 */
121828 
121829 #ifndef SQLITE_OMIT_DEPRECATED
121830 /*
121831 ** This function is now an anachronism. It used to be used to recover from a
121832 ** malloc() failure, but SQLite now does this automatically.
121833 */
121834 SQLITE_API int sqlite3_global_recover(void){
121835   return SQLITE_OK;
121836 }
121837 #endif
121838 
121839 /*
121840 ** Test to see whether or not the database connection is in autocommit
121841 ** mode.  Return TRUE if it is and FALSE if not.  Autocommit mode is on
121842 ** by default.  Autocommit is disabled by a BEGIN statement and reenabled
121843 ** by the next COMMIT or ROLLBACK.
121844 */
121845 SQLITE_API int sqlite3_get_autocommit(sqlite3 *db){
121846   return db->autoCommit;
121847 }
121848 
121849 /*
121850 ** The following routines are subtitutes for constants SQLITE_CORRUPT,
121851 ** SQLITE_MISUSE, SQLITE_CANTOPEN, SQLITE_IOERR and possibly other error
121852 ** constants.  They server two purposes:
121853 **
121854 **   1.  Serve as a convenient place to set a breakpoint in a debugger
121855 **       to detect when version error conditions occurs.
121856 **
121857 **   2.  Invoke sqlite3_log() to provide the source code location where
121858 **       a low-level error is first detected.
121859 */
121860 SQLITE_PRIVATE int sqlite3CorruptError(int lineno){
121861   testcase( sqlite3GlobalConfig.xLog!=0 );
121862   sqlite3_log(SQLITE_CORRUPT,
121863               "database corruption at line %d of [%.10s]",
121864               lineno, 20+sqlite3_sourceid());
121865   return SQLITE_CORRUPT;
121866 }
121867 SQLITE_PRIVATE int sqlite3MisuseError(int lineno){
121868   testcase( sqlite3GlobalConfig.xLog!=0 );
121869   sqlite3_log(SQLITE_MISUSE, 
121870               "misuse at line %d of [%.10s]",
121871               lineno, 20+sqlite3_sourceid());
121872   return SQLITE_MISUSE;
121873 }
121874 SQLITE_PRIVATE int sqlite3CantopenError(int lineno){
121875   testcase( sqlite3GlobalConfig.xLog!=0 );
121876   sqlite3_log(SQLITE_CANTOPEN, 
121877               "cannot open file at line %d of [%.10s]",
121878               lineno, 20+sqlite3_sourceid());
121879   return SQLITE_CANTOPEN;
121880 }
121881 
121882 
121883 #ifndef SQLITE_OMIT_DEPRECATED
121884 /*
121885 ** This is a convenience routine that makes sure that all thread-specific
121886 ** data for this thread has been deallocated.
121887 **
121888 ** SQLite no longer uses thread-specific data so this routine is now a
121889 ** no-op.  It is retained for historical compatibility.
121890 */
121891 SQLITE_API void sqlite3_thread_cleanup(void){
121892 }
121893 #endif
121894 
121895 /*
121896 ** Return meta information about a specific column of a database table.
121897 ** See comment in sqlite3.h (sqlite.h.in) for details.
121898 */
121899 #ifdef SQLITE_ENABLE_COLUMN_METADATA
121900 SQLITE_API int sqlite3_table_column_metadata(
121901   sqlite3 *db,                /* Connection handle */
121902   const char *zDbName,        /* Database name or NULL */
121903   const char *zTableName,     /* Table name */
121904   const char *zColumnName,    /* Column name */
121905   char const **pzDataType,    /* OUTPUT: Declared data type */
121906   char const **pzCollSeq,     /* OUTPUT: Collation sequence name */
121907   int *pNotNull,              /* OUTPUT: True if NOT NULL constraint exists */
121908   int *pPrimaryKey,           /* OUTPUT: True if column part of PK */
121909   int *pAutoinc               /* OUTPUT: True if column is auto-increment */
121910 ){
121911   int rc;
121912   char *zErrMsg = 0;
121913   Table *pTab = 0;
121914   Column *pCol = 0;
121915   int iCol;
121916 
121917   char const *zDataType = 0;
121918   char const *zCollSeq = 0;
121919   int notnull = 0;
121920   int primarykey = 0;
121921   int autoinc = 0;
121922 
121923   /* Ensure the database schema has been loaded */
121924   sqlite3_mutex_enter(db->mutex);
121925   sqlite3BtreeEnterAll(db);
121926   rc = sqlite3Init(db, &zErrMsg);
121927   if( SQLITE_OK!=rc ){
121928     goto error_out;
121929   }
121930 
121931   /* Locate the table in question */
121932   pTab = sqlite3FindTable(db, zTableName, zDbName);
121933   if( !pTab || pTab->pSelect ){
121934     pTab = 0;
121935     goto error_out;
121936   }
121937 
121938   /* Find the column for which info is requested */
121939   if( sqlite3IsRowid(zColumnName) ){
121940     iCol = pTab->iPKey;
121941     if( iCol>=0 ){
121942       pCol = &pTab->aCol[iCol];
121943     }
121944   }else{
121945     for(iCol=0; iCol<pTab->nCol; iCol++){
121946       pCol = &pTab->aCol[iCol];
121947       if( 0==sqlite3StrICmp(pCol->zName, zColumnName) ){
121948         break;
121949       }
121950     }
121951     if( iCol==pTab->nCol ){
121952       pTab = 0;
121953       goto error_out;
121954     }
121955   }
121956 
121957   /* The following block stores the meta information that will be returned
121958   ** to the caller in local variables zDataType, zCollSeq, notnull, primarykey
121959   ** and autoinc. At this point there are two possibilities:
121960   ** 
121961   **     1. The specified column name was rowid", "oid" or "_rowid_" 
121962   **        and there is no explicitly declared IPK column. 
121963   **
121964   **     2. The table is not a view and the column name identified an 
121965   **        explicitly declared column. Copy meta information from *pCol.
121966   */ 
121967   if( pCol ){
121968     zDataType = pCol->zType;
121969     zCollSeq = pCol->zColl;
121970     notnull = pCol->notNull!=0;
121971     primarykey  = (pCol->colFlags & COLFLAG_PRIMKEY)!=0;
121972     autoinc = pTab->iPKey==iCol && (pTab->tabFlags & TF_Autoincrement)!=0;
121973   }else{
121974     zDataType = "INTEGER";
121975     primarykey = 1;
121976   }
121977   if( !zCollSeq ){
121978     zCollSeq = "BINARY";
121979   }
121980 
121981 error_out:
121982   sqlite3BtreeLeaveAll(db);
121983 
121984   /* Whether the function call succeeded or failed, set the output parameters
121985   ** to whatever their local counterparts contain. If an error did occur,
121986   ** this has the effect of zeroing all output parameters.
121987   */
121988   if( pzDataType ) *pzDataType = zDataType;
121989   if( pzCollSeq ) *pzCollSeq = zCollSeq;
121990   if( pNotNull ) *pNotNull = notnull;
121991   if( pPrimaryKey ) *pPrimaryKey = primarykey;
121992   if( pAutoinc ) *pAutoinc = autoinc;
121993 
121994   if( SQLITE_OK==rc && !pTab ){
121995     sqlite3DbFree(db, zErrMsg);
121996     zErrMsg = sqlite3MPrintf(db, "no such table column: %s.%s", zTableName,
121997         zColumnName);
121998     rc = SQLITE_ERROR;
121999   }
122000   sqlite3Error(db, rc, (zErrMsg?"%s":0), zErrMsg);
122001   sqlite3DbFree(db, zErrMsg);
122002   rc = sqlite3ApiExit(db, rc);
122003   sqlite3_mutex_leave(db->mutex);
122004   return rc;
122005 }
122006 #endif
122007 
122008 /*
122009 ** Sleep for a little while.  Return the amount of time slept.
122010 */
122011 SQLITE_API int sqlite3_sleep(int ms){
122012   sqlite3_vfs *pVfs;
122013   int rc;
122014   pVfs = sqlite3_vfs_find(0);
122015   if( pVfs==0 ) return 0;
122016 
122017   /* This function works in milliseconds, but the underlying OsSleep() 
122018   ** API uses microseconds. Hence the 1000's.
122019   */
122020   rc = (sqlite3OsSleep(pVfs, 1000*ms)/1000);
122021   return rc;
122022 }
122023 
122024 /*
122025 ** Enable or disable the extended result codes.
122026 */
122027 SQLITE_API int sqlite3_extended_result_codes(sqlite3 *db, int onoff){
122028   sqlite3_mutex_enter(db->mutex);
122029   db->errMask = onoff ? 0xffffffff : 0xff;
122030   sqlite3_mutex_leave(db->mutex);
122031   return SQLITE_OK;
122032 }
122033 
122034 /*
122035 ** Invoke the xFileControl method on a particular database.
122036 */
122037 SQLITE_API int sqlite3_file_control(sqlite3 *db, const char *zDbName, int op, void *pArg){
122038   int rc = SQLITE_ERROR;
122039   Btree *pBtree;
122040 
122041   sqlite3_mutex_enter(db->mutex);
122042   pBtree = sqlite3DbNameToBtree(db, zDbName);
122043   if( pBtree ){
122044     Pager *pPager;
122045     sqlite3_file *fd;
122046     sqlite3BtreeEnter(pBtree);
122047     pPager = sqlite3BtreePager(pBtree);
122048     assert( pPager!=0 );
122049     fd = sqlite3PagerFile(pPager);
122050     assert( fd!=0 );
122051     if( op==SQLITE_FCNTL_FILE_POINTER ){
122052       *(sqlite3_file**)pArg = fd;
122053       rc = SQLITE_OK;
122054     }else if( fd->pMethods ){
122055       rc = sqlite3OsFileControl(fd, op, pArg);
122056     }else{
122057       rc = SQLITE_NOTFOUND;
122058     }
122059     sqlite3BtreeLeave(pBtree);
122060   }
122061   sqlite3_mutex_leave(db->mutex);
122062   return rc;   
122063 }
122064 
122065 /*
122066 ** Interface to the testing logic.
122067 */
122068 SQLITE_API int sqlite3_test_control(int op, ...){
122069   int rc = 0;
122070 #ifndef SQLITE_OMIT_BUILTIN_TEST
122071   va_list ap;
122072   va_start(ap, op);
122073   switch( op ){
122074 
122075     /*
122076     ** Save the current state of the PRNG.
122077     */
122078     case SQLITE_TESTCTRL_PRNG_SAVE: {
122079       sqlite3PrngSaveState();
122080       break;
122081     }
122082 
122083     /*
122084     ** Restore the state of the PRNG to the last state saved using
122085     ** PRNG_SAVE.  If PRNG_SAVE has never before been called, then
122086     ** this verb acts like PRNG_RESET.
122087     */
122088     case SQLITE_TESTCTRL_PRNG_RESTORE: {
122089       sqlite3PrngRestoreState();
122090       break;
122091     }
122092 
122093     /*
122094     ** Reset the PRNG back to its uninitialized state.  The next call
122095     ** to sqlite3_randomness() will reseed the PRNG using a single call
122096     ** to the xRandomness method of the default VFS.
122097     */
122098     case SQLITE_TESTCTRL_PRNG_RESET: {
122099       sqlite3PrngResetState();
122100       break;
122101     }
122102 
122103     /*
122104     **  sqlite3_test_control(BITVEC_TEST, size, program)
122105     **
122106     ** Run a test against a Bitvec object of size.  The program argument
122107     ** is an array of integers that defines the test.  Return -1 on a
122108     ** memory allocation error, 0 on success, or non-zero for an error.
122109     ** See the sqlite3BitvecBuiltinTest() for additional information.
122110     */
122111     case SQLITE_TESTCTRL_BITVEC_TEST: {
122112       int sz = va_arg(ap, int);
122113       int *aProg = va_arg(ap, int*);
122114       rc = sqlite3BitvecBuiltinTest(sz, aProg);
122115       break;
122116     }
122117 
122118     /*
122119     **  sqlite3_test_control(BENIGN_MALLOC_HOOKS, xBegin, xEnd)
122120     **
122121     ** Register hooks to call to indicate which malloc() failures 
122122     ** are benign.
122123     */
122124     case SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS: {
122125       typedef void (*void_function)(void);
122126       void_function xBenignBegin;
122127       void_function xBenignEnd;
122128       xBenignBegin = va_arg(ap, void_function);
122129       xBenignEnd = va_arg(ap, void_function);
122130       sqlite3BenignMallocHooks(xBenignBegin, xBenignEnd);
122131       break;
122132     }
122133 
122134     /*
122135     **  sqlite3_test_control(SQLITE_TESTCTRL_PENDING_BYTE, unsigned int X)
122136     **
122137     ** Set the PENDING byte to the value in the argument, if X>0.
122138     ** Make no changes if X==0.  Return the value of the pending byte
122139     ** as it existing before this routine was called.
122140     **
122141     ** IMPORTANT:  Changing the PENDING byte from 0x40000000 results in
122142     ** an incompatible database file format.  Changing the PENDING byte
122143     ** while any database connection is open results in undefined and
122144     ** dileterious behavior.
122145     */
122146     case SQLITE_TESTCTRL_PENDING_BYTE: {
122147       rc = PENDING_BYTE;
122148 #ifndef SQLITE_OMIT_WSD
122149       {
122150         unsigned int newVal = va_arg(ap, unsigned int);
122151         if( newVal ) sqlite3PendingByte = newVal;
122152       }
122153 #endif
122154       break;
122155     }
122156 
122157     /*
122158     **  sqlite3_test_control(SQLITE_TESTCTRL_ASSERT, int X)
122159     **
122160     ** This action provides a run-time test to see whether or not
122161     ** assert() was enabled at compile-time.  If X is true and assert()
122162     ** is enabled, then the return value is true.  If X is true and
122163     ** assert() is disabled, then the return value is zero.  If X is
122164     ** false and assert() is enabled, then the assertion fires and the
122165     ** process aborts.  If X is false and assert() is disabled, then the
122166     ** return value is zero.
122167     */
122168     case SQLITE_TESTCTRL_ASSERT: {
122169       volatile int x = 0;
122170       assert( (x = va_arg(ap,int))!=0 );
122171       rc = x;
122172       break;
122173     }
122174 
122175 
122176     /*
122177     **  sqlite3_test_control(SQLITE_TESTCTRL_ALWAYS, int X)
122178     **
122179     ** This action provides a run-time test to see how the ALWAYS and
122180     ** NEVER macros were defined at compile-time.
122181     **
122182     ** The return value is ALWAYS(X).  
122183     **
122184     ** The recommended test is X==2.  If the return value is 2, that means
122185     ** ALWAYS() and NEVER() are both no-op pass-through macros, which is the
122186     ** default setting.  If the return value is 1, then ALWAYS() is either
122187     ** hard-coded to true or else it asserts if its argument is false.
122188     ** The first behavior (hard-coded to true) is the case if
122189     ** SQLITE_TESTCTRL_ASSERT shows that assert() is disabled and the second
122190     ** behavior (assert if the argument to ALWAYS() is false) is the case if
122191     ** SQLITE_TESTCTRL_ASSERT shows that assert() is enabled.
122192     **
122193     ** The run-time test procedure might look something like this:
122194     **
122195     **    if( sqlite3_test_control(SQLITE_TESTCTRL_ALWAYS, 2)==2 ){
122196     **      // ALWAYS() and NEVER() are no-op pass-through macros
122197     **    }else if( sqlite3_test_control(SQLITE_TESTCTRL_ASSERT, 1) ){
122198     **      // ALWAYS(x) asserts that x is true. NEVER(x) asserts x is false.
122199     **    }else{
122200     **      // ALWAYS(x) is a constant 1.  NEVER(x) is a constant 0.
122201     **    }
122202     */
122203     case SQLITE_TESTCTRL_ALWAYS: {
122204       int x = va_arg(ap,int);
122205       rc = ALWAYS(x);
122206       break;
122207     }
122208 
122209     /*   sqlite3_test_control(SQLITE_TESTCTRL_RESERVE, sqlite3 *db, int N)
122210     **
122211     ** Set the nReserve size to N for the main database on the database
122212     ** connection db.
122213     */
122214     case SQLITE_TESTCTRL_RESERVE: {
122215       sqlite3 *db = va_arg(ap, sqlite3*);
122216       int x = va_arg(ap,int);
122217       sqlite3_mutex_enter(db->mutex);
122218       sqlite3BtreeSetPageSize(db->aDb[0].pBt, 0, x, 0);
122219       sqlite3_mutex_leave(db->mutex);
122220       break;
122221     }
122222 
122223     /*  sqlite3_test_control(SQLITE_TESTCTRL_OPTIMIZATIONS, sqlite3 *db, int N)
122224     **
122225     ** Enable or disable various optimizations for testing purposes.  The 
122226     ** argument N is a bitmask of optimizations to be disabled.  For normal
122227     ** operation N should be 0.  The idea is that a test program (like the
122228     ** SQL Logic Test or SLT test module) can run the same SQL multiple times
122229     ** with various optimizations disabled to verify that the same answer
122230     ** is obtained in every case.
122231     */
122232     case SQLITE_TESTCTRL_OPTIMIZATIONS: {
122233       sqlite3 *db = va_arg(ap, sqlite3*);
122234       db->dbOptFlags = (u16)(va_arg(ap, int) & 0xffff);
122235       break;
122236     }
122237 
122238 #ifdef SQLITE_N_KEYWORD
122239     /* sqlite3_test_control(SQLITE_TESTCTRL_ISKEYWORD, const char *zWord)
122240     **
122241     ** If zWord is a keyword recognized by the parser, then return the
122242     ** number of keywords.  Or if zWord is not a keyword, return 0.
122243     ** 
122244     ** This test feature is only available in the amalgamation since
122245     ** the SQLITE_N_KEYWORD macro is not defined in this file if SQLite
122246     ** is built using separate source files.
122247     */
122248     case SQLITE_TESTCTRL_ISKEYWORD: {
122249       const char *zWord = va_arg(ap, const char*);
122250       int n = sqlite3Strlen30(zWord);
122251       rc = (sqlite3KeywordCode((u8*)zWord, n)!=TK_ID) ? SQLITE_N_KEYWORD : 0;
122252       break;
122253     }
122254 #endif 
122255 
122256     /* sqlite3_test_control(SQLITE_TESTCTRL_SCRATCHMALLOC, sz, &pNew, pFree);
122257     **
122258     ** Pass pFree into sqlite3ScratchFree(). 
122259     ** If sz>0 then allocate a scratch buffer into pNew.  
122260     */
122261     case SQLITE_TESTCTRL_SCRATCHMALLOC: {
122262       void *pFree, **ppNew;
122263       int sz;
122264       sz = va_arg(ap, int);
122265       ppNew = va_arg(ap, void**);
122266       pFree = va_arg(ap, void*);
122267       if( sz ) *ppNew = sqlite3ScratchMalloc(sz);
122268       sqlite3ScratchFree(pFree);
122269       break;
122270     }
122271 
122272     /*   sqlite3_test_control(SQLITE_TESTCTRL_LOCALTIME_FAULT, int onoff);
122273     **
122274     ** If parameter onoff is non-zero, configure the wrappers so that all
122275     ** subsequent calls to localtime() and variants fail. If onoff is zero,
122276     ** undo this setting.
122277     */
122278     case SQLITE_TESTCTRL_LOCALTIME_FAULT: {
122279       sqlite3GlobalConfig.bLocaltimeFault = va_arg(ap, int);
122280       break;
122281     }
122282 
122283 #if defined(SQLITE_ENABLE_TREE_EXPLAIN)
122284     /*   sqlite3_test_control(SQLITE_TESTCTRL_EXPLAIN_STMT,
122285     **                        sqlite3_stmt*,const char**);
122286     **
122287     ** If compiled with SQLITE_ENABLE_TREE_EXPLAIN, each sqlite3_stmt holds
122288     ** a string that describes the optimized parse tree.  This test-control
122289     ** returns a pointer to that string.
122290     */
122291     case SQLITE_TESTCTRL_EXPLAIN_STMT: {
122292       sqlite3_stmt *pStmt = va_arg(ap, sqlite3_stmt*);
122293       const char **pzRet = va_arg(ap, const char**);
122294       *pzRet = sqlite3VdbeExplanation((Vdbe*)pStmt);
122295       break;
122296     }
122297 #endif
122298 
122299     /*   sqlite3_test_control(SQLITE_TESTCTRL_NEVER_CORRUPT, int);
122300     **
122301     ** Set or clear a flag that indicates that the database file is always well-
122302     ** formed and never corrupt.  This flag is clear by default, indicating that
122303     ** database files might have arbitrary corruption.  Setting the flag during
122304     ** testing causes certain assert() statements in the code to be activated
122305     ** that demonstrat invariants on well-formed database files.
122306     */
122307     case SQLITE_TESTCTRL_NEVER_CORRUPT: {
122308       sqlite3Config.neverCorrupt = va_arg(ap, int);
122309       break;
122310     }
122311 
122312   }
122313   va_end(ap);
122314 #endif /* SQLITE_OMIT_BUILTIN_TEST */
122315   return rc;
122316 }
122317 
122318 /*
122319 ** This is a utility routine, useful to VFS implementations, that checks
122320 ** to see if a database file was a URI that contained a specific query 
122321 ** parameter, and if so obtains the value of the query parameter.
122322 **
122323 ** The zFilename argument is the filename pointer passed into the xOpen()
122324 ** method of a VFS implementation.  The zParam argument is the name of the
122325 ** query parameter we seek.  This routine returns the value of the zParam
122326 ** parameter if it exists.  If the parameter does not exist, this routine
122327 ** returns a NULL pointer.
122328 */
122329 SQLITE_API const char *sqlite3_uri_parameter(const char *zFilename, const char *zParam){
122330   if( zFilename==0 ) return 0;
122331   zFilename += sqlite3Strlen30(zFilename) + 1;
122332   while( zFilename[0] ){
122333     int x = strcmp(zFilename, zParam);
122334     zFilename += sqlite3Strlen30(zFilename) + 1;
122335     if( x==0 ) return zFilename;
122336     zFilename += sqlite3Strlen30(zFilename) + 1;
122337   }
122338   return 0;
122339 }
122340 
122341 /*
122342 ** Return a boolean value for a query parameter.
122343 */
122344 SQLITE_API int sqlite3_uri_boolean(const char *zFilename, const char *zParam, int bDflt){
122345   const char *z = sqlite3_uri_parameter(zFilename, zParam);
122346   bDflt = bDflt!=0;
122347   return z ? sqlite3GetBoolean(z, bDflt) : bDflt;
122348 }
122349 
122350 /*
122351 ** Return a 64-bit integer value for a query parameter.
122352 */
122353 SQLITE_API sqlite3_int64 sqlite3_uri_int64(
122354   const char *zFilename,    /* Filename as passed to xOpen */
122355   const char *zParam,       /* URI parameter sought */
122356   sqlite3_int64 bDflt       /* return if parameter is missing */
122357 ){
122358   const char *z = sqlite3_uri_parameter(zFilename, zParam);
122359   sqlite3_int64 v;
122360   if( z && sqlite3Atoi64(z, &v, sqlite3Strlen30(z), SQLITE_UTF8)==SQLITE_OK ){
122361     bDflt = v;
122362   }
122363   return bDflt;
122364 }
122365 
122366 /*
122367 ** Return the Btree pointer identified by zDbName.  Return NULL if not found.
122368 */
122369 SQLITE_PRIVATE Btree *sqlite3DbNameToBtree(sqlite3 *db, const char *zDbName){
122370   int i;
122371   for(i=0; i<db->nDb; i++){
122372     if( db->aDb[i].pBt
122373      && (zDbName==0 || sqlite3StrICmp(zDbName, db->aDb[i].zName)==0)
122374     ){
122375       return db->aDb[i].pBt;
122376     }
122377   }
122378   return 0;
122379 }
122380 
122381 /*
122382 ** Return the filename of the database associated with a database
122383 ** connection.
122384 */
122385 SQLITE_API const char *sqlite3_db_filename(sqlite3 *db, const char *zDbName){
122386   Btree *pBt = sqlite3DbNameToBtree(db, zDbName);
122387   return pBt ? sqlite3BtreeGetFilename(pBt) : 0;
122388 }
122389 
122390 /*
122391 ** Return 1 if database is read-only or 0 if read/write.  Return -1 if
122392 ** no such database exists.
122393 */
122394 SQLITE_API int sqlite3_db_readonly(sqlite3 *db, const char *zDbName){
122395   Btree *pBt = sqlite3DbNameToBtree(db, zDbName);
122396   return pBt ? sqlite3PagerIsreadonly(sqlite3BtreePager(pBt)) : -1;
122397 }
122398 
122399 /************** End of main.c ************************************************/
122400 /************** Begin file notify.c ******************************************/
122401 /*
122402 ** 2009 March 3
122403 **
122404 ** The author disclaims copyright to this source code.  In place of
122405 ** a legal notice, here is a blessing:
122406 **
122407 **    May you do good and not evil.
122408 **    May you find forgiveness for yourself and forgive others.
122409 **    May you share freely, never taking more than you give.
122410 **
122411 *************************************************************************
122412 **
122413 ** This file contains the implementation of the sqlite3_unlock_notify()
122414 ** API method and its associated functionality.
122415 */
122416 
122417 /* Omit this entire file if SQLITE_ENABLE_UNLOCK_NOTIFY is not defined. */
122418 #ifdef SQLITE_ENABLE_UNLOCK_NOTIFY
122419 
122420 /*
122421 ** Public interfaces:
122422 **
122423 **   sqlite3ConnectionBlocked()
122424 **   sqlite3ConnectionUnlocked()
122425 **   sqlite3ConnectionClosed()
122426 **   sqlite3_unlock_notify()
122427 */
122428 
122429 #define assertMutexHeld() \
122430   assert( sqlite3_mutex_held(sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER)) )
122431 
122432 /*
122433 ** Head of a linked list of all sqlite3 objects created by this process
122434 ** for which either sqlite3.pBlockingConnection or sqlite3.pUnlockConnection
122435 ** is not NULL. This variable may only accessed while the STATIC_MASTER
122436 ** mutex is held.
122437 */
122438 static sqlite3 *SQLITE_WSD sqlite3BlockedList = 0;
122439 
122440 #ifndef NDEBUG
122441 /*
122442 ** This function is a complex assert() that verifies the following 
122443 ** properties of the blocked connections list:
122444 **
122445 **   1) Each entry in the list has a non-NULL value for either 
122446 **      pUnlockConnection or pBlockingConnection, or both.
122447 **
122448 **   2) All entries in the list that share a common value for 
122449 **      xUnlockNotify are grouped together.
122450 **
122451 **   3) If the argument db is not NULL, then none of the entries in the
122452 **      blocked connections list have pUnlockConnection or pBlockingConnection
122453 **      set to db. This is used when closing connection db.
122454 */
122455 static void checkListProperties(sqlite3 *db){
122456   sqlite3 *p;
122457   for(p=sqlite3BlockedList; p; p=p->pNextBlocked){
122458     int seen = 0;
122459     sqlite3 *p2;
122460 
122461     /* Verify property (1) */
122462     assert( p->pUnlockConnection || p->pBlockingConnection );
122463 
122464     /* Verify property (2) */
122465     for(p2=sqlite3BlockedList; p2!=p; p2=p2->pNextBlocked){
122466       if( p2->xUnlockNotify==p->xUnlockNotify ) seen = 1;
122467       assert( p2->xUnlockNotify==p->xUnlockNotify || !seen );
122468       assert( db==0 || p->pUnlockConnection!=db );
122469       assert( db==0 || p->pBlockingConnection!=db );
122470     }
122471   }
122472 }
122473 #else
122474 # define checkListProperties(x)
122475 #endif
122476 
122477 /*
122478 ** Remove connection db from the blocked connections list. If connection
122479 ** db is not currently a part of the list, this function is a no-op.
122480 */
122481 static void removeFromBlockedList(sqlite3 *db){
122482   sqlite3 **pp;
122483   assertMutexHeld();
122484   for(pp=&sqlite3BlockedList; *pp; pp = &(*pp)->pNextBlocked){
122485     if( *pp==db ){
122486       *pp = (*pp)->pNextBlocked;
122487       break;
122488     }
122489   }
122490 }
122491 
122492 /*
122493 ** Add connection db to the blocked connections list. It is assumed
122494 ** that it is not already a part of the list.
122495 */
122496 static void addToBlockedList(sqlite3 *db){
122497   sqlite3 **pp;
122498   assertMutexHeld();
122499   for(
122500     pp=&sqlite3BlockedList; 
122501     *pp && (*pp)->xUnlockNotify!=db->xUnlockNotify; 
122502     pp=&(*pp)->pNextBlocked
122503   );
122504   db->pNextBlocked = *pp;
122505   *pp = db;
122506 }
122507 
122508 /*
122509 ** Obtain the STATIC_MASTER mutex.
122510 */
122511 static void enterMutex(void){
122512   sqlite3_mutex_enter(sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER));
122513   checkListProperties(0);
122514 }
122515 
122516 /*
122517 ** Release the STATIC_MASTER mutex.
122518 */
122519 static void leaveMutex(void){
122520   assertMutexHeld();
122521   checkListProperties(0);
122522   sqlite3_mutex_leave(sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER));
122523 }
122524 
122525 /*
122526 ** Register an unlock-notify callback.
122527 **
122528 ** This is called after connection "db" has attempted some operation
122529 ** but has received an SQLITE_LOCKED error because another connection
122530 ** (call it pOther) in the same process was busy using the same shared
122531 ** cache.  pOther is found by looking at db->pBlockingConnection.
122532 **
122533 ** If there is no blocking connection, the callback is invoked immediately,
122534 ** before this routine returns.
122535 **
122536 ** If pOther is already blocked on db, then report SQLITE_LOCKED, to indicate
122537 ** a deadlock.
122538 **
122539 ** Otherwise, make arrangements to invoke xNotify when pOther drops
122540 ** its locks.
122541 **
122542 ** Each call to this routine overrides any prior callbacks registered
122543 ** on the same "db".  If xNotify==0 then any prior callbacks are immediately
122544 ** cancelled.
122545 */
122546 SQLITE_API int sqlite3_unlock_notify(
122547   sqlite3 *db,
122548   void (*xNotify)(void **, int),
122549   void *pArg
122550 ){
122551   int rc = SQLITE_OK;
122552 
122553   sqlite3_mutex_enter(db->mutex);
122554   enterMutex();
122555 
122556   if( xNotify==0 ){
122557     removeFromBlockedList(db);
122558     db->pBlockingConnection = 0;
122559     db->pUnlockConnection = 0;
122560     db->xUnlockNotify = 0;
122561     db->pUnlockArg = 0;
122562   }else if( 0==db->pBlockingConnection ){
122563     /* The blocking transaction has been concluded. Or there never was a 
122564     ** blocking transaction. In either case, invoke the notify callback
122565     ** immediately. 
122566     */
122567     xNotify(&pArg, 1);
122568   }else{
122569     sqlite3 *p;
122570 
122571     for(p=db->pBlockingConnection; p && p!=db; p=p->pUnlockConnection){}
122572     if( p ){
122573       rc = SQLITE_LOCKED;              /* Deadlock detected. */
122574     }else{
122575       db->pUnlockConnection = db->pBlockingConnection;
122576       db->xUnlockNotify = xNotify;
122577       db->pUnlockArg = pArg;
122578       removeFromBlockedList(db);
122579       addToBlockedList(db);
122580     }
122581   }
122582 
122583   leaveMutex();
122584   assert( !db->mallocFailed );
122585   sqlite3Error(db, rc, (rc?"database is deadlocked":0));
122586   sqlite3_mutex_leave(db->mutex);
122587   return rc;
122588 }
122589 
122590 /*
122591 ** This function is called while stepping or preparing a statement 
122592 ** associated with connection db. The operation will return SQLITE_LOCKED
122593 ** to the user because it requires a lock that will not be available
122594 ** until connection pBlocker concludes its current transaction.
122595 */
122596 SQLITE_PRIVATE void sqlite3ConnectionBlocked(sqlite3 *db, sqlite3 *pBlocker){
122597   enterMutex();
122598   if( db->pBlockingConnection==0 && db->pUnlockConnection==0 ){
122599     addToBlockedList(db);
122600   }
122601   db->pBlockingConnection = pBlocker;
122602   leaveMutex();
122603 }
122604 
122605 /*
122606 ** This function is called when
122607 ** the transaction opened by database db has just finished. Locks held 
122608 ** by database connection db have been released.
122609 **
122610 ** This function loops through each entry in the blocked connections
122611 ** list and does the following:
122612 **
122613 **   1) If the sqlite3.pBlockingConnection member of a list entry is
122614 **      set to db, then set pBlockingConnection=0.
122615 **
122616 **   2) If the sqlite3.pUnlockConnection member of a list entry is
122617 **      set to db, then invoke the configured unlock-notify callback and
122618 **      set pUnlockConnection=0.
122619 **
122620 **   3) If the two steps above mean that pBlockingConnection==0 and
122621 **      pUnlockConnection==0, remove the entry from the blocked connections
122622 **      list.
122623 */
122624 SQLITE_PRIVATE void sqlite3ConnectionUnlocked(sqlite3 *db){
122625   void (*xUnlockNotify)(void **, int) = 0; /* Unlock-notify cb to invoke */
122626   int nArg = 0;                            /* Number of entries in aArg[] */
122627   sqlite3 **pp;                            /* Iterator variable */
122628   void **aArg;               /* Arguments to the unlock callback */
122629   void **aDyn = 0;           /* Dynamically allocated space for aArg[] */
122630   void *aStatic[16];         /* Starter space for aArg[].  No malloc required */
122631 
122632   aArg = aStatic;
122633   enterMutex();         /* Enter STATIC_MASTER mutex */
122634 
122635   /* This loop runs once for each entry in the blocked-connections list. */
122636   for(pp=&sqlite3BlockedList; *pp; /* no-op */ ){
122637     sqlite3 *p = *pp;
122638 
122639     /* Step 1. */
122640     if( p->pBlockingConnection==db ){
122641       p->pBlockingConnection = 0;
122642     }
122643 
122644     /* Step 2. */
122645     if( p->pUnlockConnection==db ){
122646       assert( p->xUnlockNotify );
122647       if( p->xUnlockNotify!=xUnlockNotify && nArg!=0 ){
122648         xUnlockNotify(aArg, nArg);
122649         nArg = 0;
122650       }
122651 
122652       sqlite3BeginBenignMalloc();
122653       assert( aArg==aDyn || (aDyn==0 && aArg==aStatic) );
122654       assert( nArg<=(int)ArraySize(aStatic) || aArg==aDyn );
122655       if( (!aDyn && nArg==(int)ArraySize(aStatic))
122656        || (aDyn && nArg==(int)(sqlite3MallocSize(aDyn)/sizeof(void*)))
122657       ){
122658         /* The aArg[] array needs to grow. */
122659         void **pNew = (void **)sqlite3Malloc(nArg*sizeof(void *)*2);
122660         if( pNew ){
122661           memcpy(pNew, aArg, nArg*sizeof(void *));
122662           sqlite3_free(aDyn);
122663           aDyn = aArg = pNew;
122664         }else{
122665           /* This occurs when the array of context pointers that need to
122666           ** be passed to the unlock-notify callback is larger than the
122667           ** aStatic[] array allocated on the stack and the attempt to 
122668           ** allocate a larger array from the heap has failed.
122669           **
122670           ** This is a difficult situation to handle. Returning an error
122671           ** code to the caller is insufficient, as even if an error code
122672           ** is returned the transaction on connection db will still be
122673           ** closed and the unlock-notify callbacks on blocked connections
122674           ** will go unissued. This might cause the application to wait
122675           ** indefinitely for an unlock-notify callback that will never 
122676           ** arrive.
122677           **
122678           ** Instead, invoke the unlock-notify callback with the context
122679           ** array already accumulated. We can then clear the array and
122680           ** begin accumulating any further context pointers without 
122681           ** requiring any dynamic allocation. This is sub-optimal because
122682           ** it means that instead of one callback with a large array of
122683           ** context pointers the application will receive two or more
122684           ** callbacks with smaller arrays of context pointers, which will
122685           ** reduce the applications ability to prioritize multiple 
122686           ** connections. But it is the best that can be done under the
122687           ** circumstances.
122688           */
122689           xUnlockNotify(aArg, nArg);
122690           nArg = 0;
122691         }
122692       }
122693       sqlite3EndBenignMalloc();
122694 
122695       aArg[nArg++] = p->pUnlockArg;
122696       xUnlockNotify = p->xUnlockNotify;
122697       p->pUnlockConnection = 0;
122698       p->xUnlockNotify = 0;
122699       p->pUnlockArg = 0;
122700     }
122701 
122702     /* Step 3. */
122703     if( p->pBlockingConnection==0 && p->pUnlockConnection==0 ){
122704       /* Remove connection p from the blocked connections list. */
122705       *pp = p->pNextBlocked;
122706       p->pNextBlocked = 0;
122707     }else{
122708       pp = &p->pNextBlocked;
122709     }
122710   }
122711 
122712   if( nArg!=0 ){
122713     xUnlockNotify(aArg, nArg);
122714   }
122715   sqlite3_free(aDyn);
122716   leaveMutex();         /* Leave STATIC_MASTER mutex */
122717 }
122718 
122719 /*
122720 ** This is called when the database connection passed as an argument is 
122721 ** being closed. The connection is removed from the blocked list.
122722 */
122723 SQLITE_PRIVATE void sqlite3ConnectionClosed(sqlite3 *db){
122724   sqlite3ConnectionUnlocked(db);
122725   enterMutex();
122726   removeFromBlockedList(db);
122727   checkListProperties(db);
122728   leaveMutex();
122729 }
122730 #endif
122731 
122732 /************** End of notify.c **********************************************/
122733 /************** Begin file fts3.c ********************************************/
122734 /*
122735 ** 2006 Oct 10
122736 **
122737 ** The author disclaims copyright to this source code.  In place of
122738 ** a legal notice, here is a blessing:
122739 **
122740 **    May you do good and not evil.
122741 **    May you find forgiveness for yourself and forgive others.
122742 **    May you share freely, never taking more than you give.
122743 **
122744 ******************************************************************************
122745 **
122746 ** This is an SQLite module implementing full-text search.
122747 */
122748 
122749 /*
122750 ** The code in this file is only compiled if:
122751 **
122752 **     * The FTS3 module is being built as an extension
122753 **       (in which case SQLITE_CORE is not defined), or
122754 **
122755 **     * The FTS3 module is being built into the core of
122756 **       SQLite (in which case SQLITE_ENABLE_FTS3 is defined).
122757 */
122758 
122759 /* The full-text index is stored in a series of b+tree (-like)
122760 ** structures called segments which map terms to doclists.  The
122761 ** structures are like b+trees in layout, but are constructed from the
122762 ** bottom up in optimal fashion and are not updatable.  Since trees
122763 ** are built from the bottom up, things will be described from the
122764 ** bottom up.
122765 **
122766 **
122767 **** Varints ****
122768 ** The basic unit of encoding is a variable-length integer called a
122769 ** varint.  We encode variable-length integers in little-endian order
122770 ** using seven bits * per byte as follows:
122771 **
122772 ** KEY:
122773 **         A = 0xxxxxxx    7 bits of data and one flag bit
122774 **         B = 1xxxxxxx    7 bits of data and one flag bit
122775 **
122776 **  7 bits - A
122777 ** 14 bits - BA
122778 ** 21 bits - BBA
122779 ** and so on.
122780 **
122781 ** This is similar in concept to how sqlite encodes "varints" but
122782 ** the encoding is not the same.  SQLite varints are big-endian
122783 ** are are limited to 9 bytes in length whereas FTS3 varints are
122784 ** little-endian and can be up to 10 bytes in length (in theory).
122785 **
122786 ** Example encodings:
122787 **
122788 **     1:    0x01
122789 **   127:    0x7f
122790 **   128:    0x81 0x00
122791 **
122792 **
122793 **** Document lists ****
122794 ** A doclist (document list) holds a docid-sorted list of hits for a
122795 ** given term.  Doclists hold docids and associated token positions.
122796 ** A docid is the unique integer identifier for a single document.
122797 ** A position is the index of a word within the document.  The first 
122798 ** word of the document has a position of 0.
122799 **
122800 ** FTS3 used to optionally store character offsets using a compile-time
122801 ** option.  But that functionality is no longer supported.
122802 **
122803 ** A doclist is stored like this:
122804 **
122805 ** array {
122806 **   varint docid;          (delta from previous doclist)
122807 **   array {                (position list for column 0)
122808 **     varint position;     (2 more than the delta from previous position)
122809 **   }
122810 **   array {
122811 **     varint POS_COLUMN;   (marks start of position list for new column)
122812 **     varint column;       (index of new column)
122813 **     array {
122814 **       varint position;   (2 more than the delta from previous position)
122815 **     }
122816 **   }
122817 **   varint POS_END;        (marks end of positions for this document.
122818 ** }
122819 **
122820 ** Here, array { X } means zero or more occurrences of X, adjacent in
122821 ** memory.  A "position" is an index of a token in the token stream
122822 ** generated by the tokenizer. Note that POS_END and POS_COLUMN occur 
122823 ** in the same logical place as the position element, and act as sentinals
122824 ** ending a position list array.  POS_END is 0.  POS_COLUMN is 1.
122825 ** The positions numbers are not stored literally but rather as two more
122826 ** than the difference from the prior position, or the just the position plus
122827 ** 2 for the first position.  Example:
122828 **
122829 **   label:       A B C D E  F  G H   I  J K
122830 **   value:     123 5 9 1 1 14 35 0 234 72 0
122831 **
122832 ** The 123 value is the first docid.  For column zero in this document
122833 ** there are two matches at positions 3 and 10 (5-2 and 9-2+3).  The 1
122834 ** at D signals the start of a new column; the 1 at E indicates that the
122835 ** new column is column number 1.  There are two positions at 12 and 45
122836 ** (14-2 and 35-2+12).  The 0 at H indicate the end-of-document.  The
122837 ** 234 at I is the delta to next docid (357).  It has one position 70
122838 ** (72-2) and then terminates with the 0 at K.
122839 **
122840 ** A "position-list" is the list of positions for multiple columns for
122841 ** a single docid.  A "column-list" is the set of positions for a single
122842 ** column.  Hence, a position-list consists of one or more column-lists,
122843 ** a document record consists of a docid followed by a position-list and
122844 ** a doclist consists of one or more document records.
122845 **
122846 ** A bare doclist omits the position information, becoming an 
122847 ** array of varint-encoded docids.
122848 **
122849 **** Segment leaf nodes ****
122850 ** Segment leaf nodes store terms and doclists, ordered by term.  Leaf
122851 ** nodes are written using LeafWriter, and read using LeafReader (to
122852 ** iterate through a single leaf node's data) and LeavesReader (to
122853 ** iterate through a segment's entire leaf layer).  Leaf nodes have
122854 ** the format:
122855 **
122856 ** varint iHeight;             (height from leaf level, always 0)
122857 ** varint nTerm;               (length of first term)
122858 ** char pTerm[nTerm];          (content of first term)
122859 ** varint nDoclist;            (length of term's associated doclist)
122860 ** char pDoclist[nDoclist];    (content of doclist)
122861 ** array {
122862 **                             (further terms are delta-encoded)
122863 **   varint nPrefix;           (length of prefix shared with previous term)
122864 **   varint nSuffix;           (length of unshared suffix)
122865 **   char pTermSuffix[nSuffix];(unshared suffix of next term)
122866 **   varint nDoclist;          (length of term's associated doclist)
122867 **   char pDoclist[nDoclist];  (content of doclist)
122868 ** }
122869 **
122870 ** Here, array { X } means zero or more occurrences of X, adjacent in
122871 ** memory.
122872 **
122873 ** Leaf nodes are broken into blocks which are stored contiguously in
122874 ** the %_segments table in sorted order.  This means that when the end
122875 ** of a node is reached, the next term is in the node with the next
122876 ** greater node id.
122877 **
122878 ** New data is spilled to a new leaf node when the current node
122879 ** exceeds LEAF_MAX bytes (default 2048).  New data which itself is
122880 ** larger than STANDALONE_MIN (default 1024) is placed in a standalone
122881 ** node (a leaf node with a single term and doclist).  The goal of
122882 ** these settings is to pack together groups of small doclists while
122883 ** making it efficient to directly access large doclists.  The
122884 ** assumption is that large doclists represent terms which are more
122885 ** likely to be query targets.
122886 **
122887 ** TODO(shess) It may be useful for blocking decisions to be more
122888 ** dynamic.  For instance, it may make more sense to have a 2.5k leaf
122889 ** node rather than splitting into 2k and .5k nodes.  My intuition is
122890 ** that this might extend through 2x or 4x the pagesize.
122891 **
122892 **
122893 **** Segment interior nodes ****
122894 ** Segment interior nodes store blockids for subtree nodes and terms
122895 ** to describe what data is stored by the each subtree.  Interior
122896 ** nodes are written using InteriorWriter, and read using
122897 ** InteriorReader.  InteriorWriters are created as needed when
122898 ** SegmentWriter creates new leaf nodes, or when an interior node
122899 ** itself grows too big and must be split.  The format of interior
122900 ** nodes:
122901 **
122902 ** varint iHeight;           (height from leaf level, always >0)
122903 ** varint iBlockid;          (block id of node's leftmost subtree)
122904 ** optional {
122905 **   varint nTerm;           (length of first term)
122906 **   char pTerm[nTerm];      (content of first term)
122907 **   array {
122908 **                                (further terms are delta-encoded)
122909 **     varint nPrefix;            (length of shared prefix with previous term)
122910 **     varint nSuffix;            (length of unshared suffix)
122911 **     char pTermSuffix[nSuffix]; (unshared suffix of next term)
122912 **   }
122913 ** }
122914 **
122915 ** Here, optional { X } means an optional element, while array { X }
122916 ** means zero or more occurrences of X, adjacent in memory.
122917 **
122918 ** An interior node encodes n terms separating n+1 subtrees.  The
122919 ** subtree blocks are contiguous, so only the first subtree's blockid
122920 ** is encoded.  The subtree at iBlockid will contain all terms less
122921 ** than the first term encoded (or all terms if no term is encoded).
122922 ** Otherwise, for terms greater than or equal to pTerm[i] but less
122923 ** than pTerm[i+1], the subtree for that term will be rooted at
122924 ** iBlockid+i.  Interior nodes only store enough term data to
122925 ** distinguish adjacent children (if the rightmost term of the left
122926 ** child is "something", and the leftmost term of the right child is
122927 ** "wicked", only "w" is stored).
122928 **
122929 ** New data is spilled to a new interior node at the same height when
122930 ** the current node exceeds INTERIOR_MAX bytes (default 2048).
122931 ** INTERIOR_MIN_TERMS (default 7) keeps large terms from monopolizing
122932 ** interior nodes and making the tree too skinny.  The interior nodes
122933 ** at a given height are naturally tracked by interior nodes at
122934 ** height+1, and so on.
122935 **
122936 **
122937 **** Segment directory ****
122938 ** The segment directory in table %_segdir stores meta-information for
122939 ** merging and deleting segments, and also the root node of the
122940 ** segment's tree.
122941 **
122942 ** The root node is the top node of the segment's tree after encoding
122943 ** the entire segment, restricted to ROOT_MAX bytes (default 1024).
122944 ** This could be either a leaf node or an interior node.  If the top
122945 ** node requires more than ROOT_MAX bytes, it is flushed to %_segments
122946 ** and a new root interior node is generated (which should always fit
122947 ** within ROOT_MAX because it only needs space for 2 varints, the
122948 ** height and the blockid of the previous root).
122949 **
122950 ** The meta-information in the segment directory is:
122951 **   level               - segment level (see below)
122952 **   idx                 - index within level
122953 **                       - (level,idx uniquely identify a segment)
122954 **   start_block         - first leaf node
122955 **   leaves_end_block    - last leaf node
122956 **   end_block           - last block (including interior nodes)
122957 **   root                - contents of root node
122958 **
122959 ** If the root node is a leaf node, then start_block,
122960 ** leaves_end_block, and end_block are all 0.
122961 **
122962 **
122963 **** Segment merging ****
122964 ** To amortize update costs, segments are grouped into levels and
122965 ** merged in batches.  Each increase in level represents exponentially
122966 ** more documents.
122967 **
122968 ** New documents (actually, document updates) are tokenized and
122969 ** written individually (using LeafWriter) to a level 0 segment, with
122970 ** incrementing idx.  When idx reaches MERGE_COUNT (default 16), all
122971 ** level 0 segments are merged into a single level 1 segment.  Level 1
122972 ** is populated like level 0, and eventually MERGE_COUNT level 1
122973 ** segments are merged to a single level 2 segment (representing
122974 ** MERGE_COUNT^2 updates), and so on.
122975 **
122976 ** A segment merge traverses all segments at a given level in
122977 ** parallel, performing a straightforward sorted merge.  Since segment
122978 ** leaf nodes are written in to the %_segments table in order, this
122979 ** merge traverses the underlying sqlite disk structures efficiently.
122980 ** After the merge, all segment blocks from the merged level are
122981 ** deleted.
122982 **
122983 ** MERGE_COUNT controls how often we merge segments.  16 seems to be
122984 ** somewhat of a sweet spot for insertion performance.  32 and 64 show
122985 ** very similar performance numbers to 16 on insertion, though they're
122986 ** a tiny bit slower (perhaps due to more overhead in merge-time
122987 ** sorting).  8 is about 20% slower than 16, 4 about 50% slower than
122988 ** 16, 2 about 66% slower than 16.
122989 **
122990 ** At query time, high MERGE_COUNT increases the number of segments
122991 ** which need to be scanned and merged.  For instance, with 100k docs
122992 ** inserted:
122993 **
122994 **    MERGE_COUNT   segments
122995 **       16           25
122996 **        8           12
122997 **        4           10
122998 **        2            6
122999 **
123000 ** This appears to have only a moderate impact on queries for very
123001 ** frequent terms (which are somewhat dominated by segment merge
123002 ** costs), and infrequent and non-existent terms still seem to be fast
123003 ** even with many segments.
123004 **
123005 ** TODO(shess) That said, it would be nice to have a better query-side
123006 ** argument for MERGE_COUNT of 16.  Also, it is possible/likely that
123007 ** optimizations to things like doclist merging will swing the sweet
123008 ** spot around.
123009 **
123010 **
123011 **
123012 **** Handling of deletions and updates ****
123013 ** Since we're using a segmented structure, with no docid-oriented
123014 ** index into the term index, we clearly cannot simply update the term
123015 ** index when a document is deleted or updated.  For deletions, we
123016 ** write an empty doclist (varint(docid) varint(POS_END)), for updates
123017 ** we simply write the new doclist.  Segment merges overwrite older
123018 ** data for a particular docid with newer data, so deletes or updates
123019 ** will eventually overtake the earlier data and knock it out.  The
123020 ** query logic likewise merges doclists so that newer data knocks out
123021 ** older data.
123022 */
123023 
123024 /************** Include fts3Int.h in the middle of fts3.c ********************/
123025 /************** Begin file fts3Int.h *****************************************/
123026 /*
123027 ** 2009 Nov 12
123028 **
123029 ** The author disclaims copyright to this source code.  In place of
123030 ** a legal notice, here is a blessing:
123031 **
123032 **    May you do good and not evil.
123033 **    May you find forgiveness for yourself and forgive others.
123034 **    May you share freely, never taking more than you give.
123035 **
123036 ******************************************************************************
123037 **
123038 */
123039 #ifndef _FTSINT_H
123040 #define _FTSINT_H
123041 
123042 #if !defined(NDEBUG) && !defined(SQLITE_DEBUG) 
123043 # define NDEBUG 1
123044 #endif
123045 
123046 /*
123047 ** FTS4 is really an extension for FTS3.  It is enabled using the
123048 ** SQLITE_ENABLE_FTS3 macro.  But to avoid confusion we also all
123049 ** the SQLITE_ENABLE_FTS4 macro to serve as an alisse for SQLITE_ENABLE_FTS3.
123050 */
123051 #if defined(SQLITE_ENABLE_FTS4) && !defined(SQLITE_ENABLE_FTS3)
123052 # define SQLITE_ENABLE_FTS3
123053 #endif
123054 
123055 #if !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_FTS3)
123056 
123057 /* If not building as part of the core, include sqlite3ext.h. */
123058 #ifndef SQLITE_CORE
123059 SQLITE_EXTENSION_INIT3
123060 #endif
123061 
123062 /************** Include fts3_tokenizer.h in the middle of fts3Int.h **********/
123063 /************** Begin file fts3_tokenizer.h **********************************/
123064 /*
123065 ** 2006 July 10
123066 **
123067 ** The author disclaims copyright to this source code.
123068 **
123069 *************************************************************************
123070 ** Defines the interface to tokenizers used by fulltext-search.  There
123071 ** are three basic components:
123072 **
123073 ** sqlite3_tokenizer_module is a singleton defining the tokenizer
123074 ** interface functions.  This is essentially the class structure for
123075 ** tokenizers.
123076 **
123077 ** sqlite3_tokenizer is used to define a particular tokenizer, perhaps
123078 ** including customization information defined at creation time.
123079 **
123080 ** sqlite3_tokenizer_cursor is generated by a tokenizer to generate
123081 ** tokens from a particular input.
123082 */
123083 #ifndef _FTS3_TOKENIZER_H_
123084 #define _FTS3_TOKENIZER_H_
123085 
123086 /* TODO(shess) Only used for SQLITE_OK and SQLITE_DONE at this time.
123087 ** If tokenizers are to be allowed to call sqlite3_*() functions, then
123088 ** we will need a way to register the API consistently.
123089 */
123090 
123091 /*
123092 ** Structures used by the tokenizer interface. When a new tokenizer
123093 ** implementation is registered, the caller provides a pointer to
123094 ** an sqlite3_tokenizer_module containing pointers to the callback
123095 ** functions that make up an implementation.
123096 **
123097 ** When an fts3 table is created, it passes any arguments passed to
123098 ** the tokenizer clause of the CREATE VIRTUAL TABLE statement to the
123099 ** sqlite3_tokenizer_module.xCreate() function of the requested tokenizer
123100 ** implementation. The xCreate() function in turn returns an 
123101 ** sqlite3_tokenizer structure representing the specific tokenizer to
123102 ** be used for the fts3 table (customized by the tokenizer clause arguments).
123103 **
123104 ** To tokenize an input buffer, the sqlite3_tokenizer_module.xOpen()
123105 ** method is called. It returns an sqlite3_tokenizer_cursor object
123106 ** that may be used to tokenize a specific input buffer based on
123107 ** the tokenization rules supplied by a specific sqlite3_tokenizer
123108 ** object.
123109 */
123110 typedef struct sqlite3_tokenizer_module sqlite3_tokenizer_module;
123111 typedef struct sqlite3_tokenizer sqlite3_tokenizer;
123112 typedef struct sqlite3_tokenizer_cursor sqlite3_tokenizer_cursor;
123113 
123114 struct sqlite3_tokenizer_module {
123115 
123116   /*
123117   ** Structure version. Should always be set to 0 or 1.
123118   */
123119   int iVersion;
123120 
123121   /*
123122   ** Create a new tokenizer. The values in the argv[] array are the
123123   ** arguments passed to the "tokenizer" clause of the CREATE VIRTUAL
123124   ** TABLE statement that created the fts3 table. For example, if
123125   ** the following SQL is executed:
123126   **
123127   **   CREATE .. USING fts3( ... , tokenizer <tokenizer-name> arg1 arg2)
123128   **
123129   ** then argc is set to 2, and the argv[] array contains pointers
123130   ** to the strings "arg1" and "arg2".
123131   **
123132   ** This method should return either SQLITE_OK (0), or an SQLite error 
123133   ** code. If SQLITE_OK is returned, then *ppTokenizer should be set
123134   ** to point at the newly created tokenizer structure. The generic
123135   ** sqlite3_tokenizer.pModule variable should not be initialized by
123136   ** this callback. The caller will do so.
123137   */
123138   int (*xCreate)(
123139     int argc,                           /* Size of argv array */
123140     const char *const*argv,             /* Tokenizer argument strings */
123141     sqlite3_tokenizer **ppTokenizer     /* OUT: Created tokenizer */
123142   );
123143 
123144   /*
123145   ** Destroy an existing tokenizer. The fts3 module calls this method
123146   ** exactly once for each successful call to xCreate().
123147   */
123148   int (*xDestroy)(sqlite3_tokenizer *pTokenizer);
123149 
123150   /*
123151   ** Create a tokenizer cursor to tokenize an input buffer. The caller
123152   ** is responsible for ensuring that the input buffer remains valid
123153   ** until the cursor is closed (using the xClose() method). 
123154   */
123155   int (*xOpen)(
123156     sqlite3_tokenizer *pTokenizer,       /* Tokenizer object */
123157     const char *pInput, int nBytes,      /* Input buffer */
123158     sqlite3_tokenizer_cursor **ppCursor  /* OUT: Created tokenizer cursor */
123159   );
123160 
123161   /*
123162   ** Destroy an existing tokenizer cursor. The fts3 module calls this 
123163   ** method exactly once for each successful call to xOpen().
123164   */
123165   int (*xClose)(sqlite3_tokenizer_cursor *pCursor);
123166 
123167   /*
123168   ** Retrieve the next token from the tokenizer cursor pCursor. This
123169   ** method should either return SQLITE_OK and set the values of the
123170   ** "OUT" variables identified below, or SQLITE_DONE to indicate that
123171   ** the end of the buffer has been reached, or an SQLite error code.
123172   **
123173   ** *ppToken should be set to point at a buffer containing the 
123174   ** normalized version of the token (i.e. after any case-folding and/or
123175   ** stemming has been performed). *pnBytes should be set to the length
123176   ** of this buffer in bytes. The input text that generated the token is
123177   ** identified by the byte offsets returned in *piStartOffset and
123178   ** *piEndOffset. *piStartOffset should be set to the index of the first
123179   ** byte of the token in the input buffer. *piEndOffset should be set
123180   ** to the index of the first byte just past the end of the token in
123181   ** the input buffer.
123182   **
123183   ** The buffer *ppToken is set to point at is managed by the tokenizer
123184   ** implementation. It is only required to be valid until the next call
123185   ** to xNext() or xClose(). 
123186   */
123187   /* TODO(shess) current implementation requires pInput to be
123188   ** nul-terminated.  This should either be fixed, or pInput/nBytes
123189   ** should be converted to zInput.
123190   */
123191   int (*xNext)(
123192     sqlite3_tokenizer_cursor *pCursor,   /* Tokenizer cursor */
123193     const char **ppToken, int *pnBytes,  /* OUT: Normalized text for token */
123194     int *piStartOffset,  /* OUT: Byte offset of token in input buffer */
123195     int *piEndOffset,    /* OUT: Byte offset of end of token in input buffer */
123196     int *piPosition      /* OUT: Number of tokens returned before this one */
123197   );
123198 
123199   /***********************************************************************
123200   ** Methods below this point are only available if iVersion>=1.
123201   */
123202 
123203   /* 
123204   ** Configure the language id of a tokenizer cursor.
123205   */
123206   int (*xLanguageid)(sqlite3_tokenizer_cursor *pCsr, int iLangid);
123207 };
123208 
123209 struct sqlite3_tokenizer {
123210   const sqlite3_tokenizer_module *pModule;  /* The module for this tokenizer */
123211   /* Tokenizer implementations will typically add additional fields */
123212 };
123213 
123214 struct sqlite3_tokenizer_cursor {
123215   sqlite3_tokenizer *pTokenizer;       /* Tokenizer for this cursor. */
123216   /* Tokenizer implementations will typically add additional fields */
123217 };
123218 
123219 int fts3_global_term_cnt(int iTerm, int iCol);
123220 int fts3_term_cnt(int iTerm, int iCol);
123221 
123222 
123223 #endif /* _FTS3_TOKENIZER_H_ */
123224 
123225 /************** End of fts3_tokenizer.h **************************************/
123226 /************** Continuing where we left off in fts3Int.h ********************/
123227 /************** Include fts3_hash.h in the middle of fts3Int.h ***************/
123228 /************** Begin file fts3_hash.h ***************************************/
123229 /*
123230 ** 2001 September 22
123231 **
123232 ** The author disclaims copyright to this source code.  In place of
123233 ** a legal notice, here is a blessing:
123234 **
123235 **    May you do good and not evil.
123236 **    May you find forgiveness for yourself and forgive others.
123237 **    May you share freely, never taking more than you give.
123238 **
123239 *************************************************************************
123240 ** This is the header file for the generic hash-table implementation
123241 ** used in SQLite.  We've modified it slightly to serve as a standalone
123242 ** hash table implementation for the full-text indexing module.
123243 **
123244 */
123245 #ifndef _FTS3_HASH_H_
123246 #define _FTS3_HASH_H_
123247 
123248 /* Forward declarations of structures. */
123249 typedef struct Fts3Hash Fts3Hash;
123250 typedef struct Fts3HashElem Fts3HashElem;
123251 
123252 /* A complete hash table is an instance of the following structure.
123253 ** The internals of this structure are intended to be opaque -- client
123254 ** code should not attempt to access or modify the fields of this structure
123255 ** directly.  Change this structure only by using the routines below.
123256 ** However, many of the "procedures" and "functions" for modifying and
123257 ** accessing this structure are really macros, so we can't really make
123258 ** this structure opaque.
123259 */
123260 struct Fts3Hash {
123261   char keyClass;          /* HASH_INT, _POINTER, _STRING, _BINARY */
123262   char copyKey;           /* True if copy of key made on insert */
123263   int count;              /* Number of entries in this table */
123264   Fts3HashElem *first;    /* The first element of the array */
123265   int htsize;             /* Number of buckets in the hash table */
123266   struct _fts3ht {        /* the hash table */
123267     int count;               /* Number of entries with this hash */
123268     Fts3HashElem *chain;     /* Pointer to first entry with this hash */
123269   } *ht;
123270 };
123271 
123272 /* Each element in the hash table is an instance of the following 
123273 ** structure.  All elements are stored on a single doubly-linked list.
123274 **
123275 ** Again, this structure is intended to be opaque, but it can't really
123276 ** be opaque because it is used by macros.
123277 */
123278 struct Fts3HashElem {
123279   Fts3HashElem *next, *prev; /* Next and previous elements in the table */
123280   void *data;                /* Data associated with this element */
123281   void *pKey; int nKey;      /* Key associated with this element */
123282 };
123283 
123284 /*
123285 ** There are 2 different modes of operation for a hash table:
123286 **
123287 **   FTS3_HASH_STRING        pKey points to a string that is nKey bytes long
123288 **                           (including the null-terminator, if any).  Case
123289 **                           is respected in comparisons.
123290 **
123291 **   FTS3_HASH_BINARY        pKey points to binary data nKey bytes long. 
123292 **                           memcmp() is used to compare keys.
123293 **
123294 ** A copy of the key is made if the copyKey parameter to fts3HashInit is 1.  
123295 */
123296 #define FTS3_HASH_STRING    1
123297 #define FTS3_HASH_BINARY    2
123298 
123299 /*
123300 ** Access routines.  To delete, insert a NULL pointer.
123301 */
123302 SQLITE_PRIVATE void sqlite3Fts3HashInit(Fts3Hash *pNew, char keyClass, char copyKey);
123303 SQLITE_PRIVATE void *sqlite3Fts3HashInsert(Fts3Hash*, const void *pKey, int nKey, void *pData);
123304 SQLITE_PRIVATE void *sqlite3Fts3HashFind(const Fts3Hash*, const void *pKey, int nKey);
123305 SQLITE_PRIVATE void sqlite3Fts3HashClear(Fts3Hash*);
123306 SQLITE_PRIVATE Fts3HashElem *sqlite3Fts3HashFindElem(const Fts3Hash *, const void *, int);
123307 
123308 /*
123309 ** Shorthand for the functions above
123310 */
123311 #define fts3HashInit     sqlite3Fts3HashInit
123312 #define fts3HashInsert   sqlite3Fts3HashInsert
123313 #define fts3HashFind     sqlite3Fts3HashFind
123314 #define fts3HashClear    sqlite3Fts3HashClear
123315 #define fts3HashFindElem sqlite3Fts3HashFindElem
123316 
123317 /*
123318 ** Macros for looping over all elements of a hash table.  The idiom is
123319 ** like this:
123320 **
123321 **   Fts3Hash h;
123322 **   Fts3HashElem *p;
123323 **   ...
123324 **   for(p=fts3HashFirst(&h); p; p=fts3HashNext(p)){
123325 **     SomeStructure *pData = fts3HashData(p);
123326 **     // do something with pData
123327 **   }
123328 */
123329 #define fts3HashFirst(H)  ((H)->first)
123330 #define fts3HashNext(E)   ((E)->next)
123331 #define fts3HashData(E)   ((E)->data)
123332 #define fts3HashKey(E)    ((E)->pKey)
123333 #define fts3HashKeysize(E) ((E)->nKey)
123334 
123335 /*
123336 ** Number of entries in a hash table
123337 */
123338 #define fts3HashCount(H)  ((H)->count)
123339 
123340 #endif /* _FTS3_HASH_H_ */
123341 
123342 /************** End of fts3_hash.h *******************************************/
123343 /************** Continuing where we left off in fts3Int.h ********************/
123344 
123345 /*
123346 ** This constant determines the maximum depth of an FTS expression tree
123347 ** that the library will create and use. FTS uses recursion to perform 
123348 ** various operations on the query tree, so the disadvantage of a large
123349 ** limit is that it may allow very large queries to use large amounts
123350 ** of stack space (perhaps causing a stack overflow).
123351 */
123352 #ifndef SQLITE_FTS3_MAX_EXPR_DEPTH
123353 # define SQLITE_FTS3_MAX_EXPR_DEPTH 12
123354 #endif
123355 
123356 
123357 /*
123358 ** This constant controls how often segments are merged. Once there are
123359 ** FTS3_MERGE_COUNT segments of level N, they are merged into a single
123360 ** segment of level N+1.
123361 */
123362 #define FTS3_MERGE_COUNT 16
123363 
123364 /*
123365 ** This is the maximum amount of data (in bytes) to store in the 
123366 ** Fts3Table.pendingTerms hash table. Normally, the hash table is
123367 ** populated as documents are inserted/updated/deleted in a transaction
123368 ** and used to create a new segment when the transaction is committed.
123369 ** However if this limit is reached midway through a transaction, a new 
123370 ** segment is created and the hash table cleared immediately.
123371 */
123372 #define FTS3_MAX_PENDING_DATA (1*1024*1024)
123373 
123374 /*
123375 ** Macro to return the number of elements in an array. SQLite has a
123376 ** similar macro called ArraySize(). Use a different name to avoid
123377 ** a collision when building an amalgamation with built-in FTS3.
123378 */
123379 #define SizeofArray(X) ((int)(sizeof(X)/sizeof(X[0])))
123380 
123381 
123382 #ifndef MIN
123383 # define MIN(x,y) ((x)<(y)?(x):(y))
123384 #endif
123385 #ifndef MAX
123386 # define MAX(x,y) ((x)>(y)?(x):(y))
123387 #endif
123388 
123389 /*
123390 ** Maximum length of a varint encoded integer. The varint format is different
123391 ** from that used by SQLite, so the maximum length is 10, not 9.
123392 */
123393 #define FTS3_VARINT_MAX 10
123394 
123395 /*
123396 ** FTS4 virtual tables may maintain multiple indexes - one index of all terms
123397 ** in the document set and zero or more prefix indexes. All indexes are stored
123398 ** as one or more b+-trees in the %_segments and %_segdir tables. 
123399 **
123400 ** It is possible to determine which index a b+-tree belongs to based on the
123401 ** value stored in the "%_segdir.level" column. Given this value L, the index
123402 ** that the b+-tree belongs to is (L<<10). In other words, all b+-trees with
123403 ** level values between 0 and 1023 (inclusive) belong to index 0, all levels
123404 ** between 1024 and 2047 to index 1, and so on.
123405 **
123406 ** It is considered impossible for an index to use more than 1024 levels. In 
123407 ** theory though this may happen, but only after at least 
123408 ** (FTS3_MERGE_COUNT^1024) separate flushes of the pending-terms tables.
123409 */
123410 #define FTS3_SEGDIR_MAXLEVEL      1024
123411 #define FTS3_SEGDIR_MAXLEVEL_STR "1024"
123412 
123413 /*
123414 ** The testcase() macro is only used by the amalgamation.  If undefined,
123415 ** make it a no-op.
123416 */
123417 #ifndef testcase
123418 # define testcase(X)
123419 #endif
123420 
123421 /*
123422 ** Terminator values for position-lists and column-lists.
123423 */
123424 #define POS_COLUMN  (1)     /* Column-list terminator */
123425 #define POS_END     (0)     /* Position-list terminator */ 
123426 
123427 /*
123428 ** This section provides definitions to allow the
123429 ** FTS3 extension to be compiled outside of the 
123430 ** amalgamation.
123431 */
123432 #ifndef SQLITE_AMALGAMATION
123433 /*
123434 ** Macros indicating that conditional expressions are always true or
123435 ** false.
123436 */
123437 #ifdef SQLITE_COVERAGE_TEST
123438 # define ALWAYS(x) (1)
123439 # define NEVER(X)  (0)
123440 #else
123441 # define ALWAYS(x) (x)
123442 # define NEVER(x)  (x)
123443 #endif
123444 
123445 /*
123446 ** Internal types used by SQLite.
123447 */
123448 typedef unsigned char u8;         /* 1-byte (or larger) unsigned integer */
123449 typedef short int i16;            /* 2-byte (or larger) signed integer */
123450 typedef unsigned int u32;         /* 4-byte unsigned integer */
123451 typedef sqlite3_uint64 u64;       /* 8-byte unsigned integer */
123452 typedef sqlite3_int64 i64;        /* 8-byte signed integer */
123453 
123454 /*
123455 ** Macro used to suppress compiler warnings for unused parameters.
123456 */
123457 #define UNUSED_PARAMETER(x) (void)(x)
123458 
123459 /*
123460 ** Activate assert() only if SQLITE_TEST is enabled.
123461 */
123462 #if !defined(NDEBUG) && !defined(SQLITE_DEBUG) 
123463 # define NDEBUG 1
123464 #endif
123465 
123466 /*
123467 ** The TESTONLY macro is used to enclose variable declarations or
123468 ** other bits of code that are needed to support the arguments
123469 ** within testcase() and assert() macros.
123470 */
123471 #if defined(SQLITE_DEBUG) || defined(SQLITE_COVERAGE_TEST)
123472 # define TESTONLY(X)  X
123473 #else
123474 # define TESTONLY(X)
123475 #endif
123476 
123477 #endif /* SQLITE_AMALGAMATION */
123478 
123479 #ifdef SQLITE_DEBUG
123480 SQLITE_PRIVATE int sqlite3Fts3Corrupt(void);
123481 # define FTS_CORRUPT_VTAB sqlite3Fts3Corrupt()
123482 #else
123483 # define FTS_CORRUPT_VTAB SQLITE_CORRUPT_VTAB
123484 #endif
123485 
123486 typedef struct Fts3Table Fts3Table;
123487 typedef struct Fts3Cursor Fts3Cursor;
123488 typedef struct Fts3Expr Fts3Expr;
123489 typedef struct Fts3Phrase Fts3Phrase;
123490 typedef struct Fts3PhraseToken Fts3PhraseToken;
123491 
123492 typedef struct Fts3Doclist Fts3Doclist;
123493 typedef struct Fts3SegFilter Fts3SegFilter;
123494 typedef struct Fts3DeferredToken Fts3DeferredToken;
123495 typedef struct Fts3SegReader Fts3SegReader;
123496 typedef struct Fts3MultiSegReader Fts3MultiSegReader;
123497 
123498 /*
123499 ** A connection to a fulltext index is an instance of the following
123500 ** structure. The xCreate and xConnect methods create an instance
123501 ** of this structure and xDestroy and xDisconnect free that instance.
123502 ** All other methods receive a pointer to the structure as one of their
123503 ** arguments.
123504 */
123505 struct Fts3Table {
123506   sqlite3_vtab base;              /* Base class used by SQLite core */
123507   sqlite3 *db;                    /* The database connection */
123508   const char *zDb;                /* logical database name */
123509   const char *zName;              /* virtual table name */
123510   int nColumn;                    /* number of named columns in virtual table */
123511   char **azColumn;                /* column names.  malloced */
123512   u8 *abNotindexed;               /* True for 'notindexed' columns */
123513   sqlite3_tokenizer *pTokenizer;  /* tokenizer for inserts and queries */
123514   char *zContentTbl;              /* content=xxx option, or NULL */
123515   char *zLanguageid;              /* languageid=xxx option, or NULL */
123516   u8 bAutoincrmerge;              /* True if automerge=1 */
123517   u32 nLeafAdd;                   /* Number of leaf blocks added this trans */
123518 
123519   /* Precompiled statements used by the implementation. Each of these 
123520   ** statements is run and reset within a single virtual table API call. 
123521   */
123522   sqlite3_stmt *aStmt[37];
123523 
123524   char *zReadExprlist;
123525   char *zWriteExprlist;
123526 
123527   int nNodeSize;                  /* Soft limit for node size */
123528   u8 bFts4;                       /* True for FTS4, false for FTS3 */
123529   u8 bHasStat;                    /* True if %_stat table exists */
123530   u8 bHasDocsize;                 /* True if %_docsize table exists */
123531   u8 bDescIdx;                    /* True if doclists are in reverse order */
123532   u8 bIgnoreSavepoint;            /* True to ignore xSavepoint invocations */
123533   int nPgsz;                      /* Page size for host database */
123534   char *zSegmentsTbl;             /* Name of %_segments table */
123535   sqlite3_blob *pSegments;        /* Blob handle open on %_segments table */
123536 
123537   /* 
123538   ** The following array of hash tables is used to buffer pending index 
123539   ** updates during transactions. All pending updates buffered at any one
123540   ** time must share a common language-id (see the FTS4 langid= feature).
123541   ** The current language id is stored in variable iPrevLangid.
123542   **
123543   ** A single FTS4 table may have multiple full-text indexes. For each index
123544   ** there is an entry in the aIndex[] array. Index 0 is an index of all the
123545   ** terms that appear in the document set. Each subsequent index in aIndex[]
123546   ** is an index of prefixes of a specific length.
123547   **
123548   ** Variable nPendingData contains an estimate the memory consumed by the 
123549   ** pending data structures, including hash table overhead, but not including
123550   ** malloc overhead.  When nPendingData exceeds nMaxPendingData, all hash
123551   ** tables are flushed to disk. Variable iPrevDocid is the docid of the most 
123552   ** recently inserted record.
123553   */
123554   int nIndex;                     /* Size of aIndex[] */
123555   struct Fts3Index {
123556     int nPrefix;                  /* Prefix length (0 for main terms index) */
123557     Fts3Hash hPending;            /* Pending terms table for this index */
123558   } *aIndex;
123559   int nMaxPendingData;            /* Max pending data before flush to disk */
123560   int nPendingData;               /* Current bytes of pending data */
123561   sqlite_int64 iPrevDocid;        /* Docid of most recently inserted document */
123562   int iPrevLangid;                /* Langid of recently inserted document */
123563 
123564 #if defined(SQLITE_DEBUG) || defined(SQLITE_COVERAGE_TEST)
123565   /* State variables used for validating that the transaction control
123566   ** methods of the virtual table are called at appropriate times.  These
123567   ** values do not contribute to FTS functionality; they are used for
123568   ** verifying the operation of the SQLite core.
123569   */
123570   int inTransaction;     /* True after xBegin but before xCommit/xRollback */
123571   int mxSavepoint;       /* Largest valid xSavepoint integer */
123572 #endif
123573 
123574 #ifdef SQLITE_TEST
123575   /* True to disable the incremental doclist optimization. This is controled
123576   ** by special insert command 'test-no-incr-doclist'.  */
123577   int bNoIncrDoclist;
123578 #endif
123579 };
123580 
123581 /*
123582 ** When the core wants to read from the virtual table, it creates a
123583 ** virtual table cursor (an instance of the following structure) using
123584 ** the xOpen method. Cursors are destroyed using the xClose method.
123585 */
123586 struct Fts3Cursor {
123587   sqlite3_vtab_cursor base;       /* Base class used by SQLite core */
123588   i16 eSearch;                    /* Search strategy (see below) */
123589   u8 isEof;                       /* True if at End Of Results */
123590   u8 isRequireSeek;               /* True if must seek pStmt to %_content row */
123591   sqlite3_stmt *pStmt;            /* Prepared statement in use by the cursor */
123592   Fts3Expr *pExpr;                /* Parsed MATCH query string */
123593   int iLangid;                    /* Language being queried for */
123594   int nPhrase;                    /* Number of matchable phrases in query */
123595   Fts3DeferredToken *pDeferred;   /* Deferred search tokens, if any */
123596   sqlite3_int64 iPrevId;          /* Previous id read from aDoclist */
123597   char *pNextId;                  /* Pointer into the body of aDoclist */
123598   char *aDoclist;                 /* List of docids for full-text queries */
123599   int nDoclist;                   /* Size of buffer at aDoclist */
123600   u8 bDesc;                       /* True to sort in descending order */
123601   int eEvalmode;                  /* An FTS3_EVAL_XX constant */
123602   int nRowAvg;                    /* Average size of database rows, in pages */
123603   sqlite3_int64 nDoc;             /* Documents in table */
123604   i64 iMinDocid;                  /* Minimum docid to return */
123605   i64 iMaxDocid;                  /* Maximum docid to return */
123606   int isMatchinfoNeeded;          /* True when aMatchinfo[] needs filling in */
123607   u32 *aMatchinfo;                /* Information about most recent match */
123608   int nMatchinfo;                 /* Number of elements in aMatchinfo[] */
123609   char *zMatchinfo;               /* Matchinfo specification */
123610 };
123611 
123612 #define FTS3_EVAL_FILTER    0
123613 #define FTS3_EVAL_NEXT      1
123614 #define FTS3_EVAL_MATCHINFO 2
123615 
123616 /*
123617 ** The Fts3Cursor.eSearch member is always set to one of the following.
123618 ** Actualy, Fts3Cursor.eSearch can be greater than or equal to
123619 ** FTS3_FULLTEXT_SEARCH.  If so, then Fts3Cursor.eSearch - 2 is the index
123620 ** of the column to be searched.  For example, in
123621 **
123622 **     CREATE VIRTUAL TABLE ex1 USING fts3(a,b,c,d);
123623 **     SELECT docid FROM ex1 WHERE b MATCH 'one two three';
123624 ** 
123625 ** Because the LHS of the MATCH operator is 2nd column "b",
123626 ** Fts3Cursor.eSearch will be set to FTS3_FULLTEXT_SEARCH+1.  (+0 for a,
123627 ** +1 for b, +2 for c, +3 for d.)  If the LHS of MATCH were "ex1" 
123628 ** indicating that all columns should be searched,
123629 ** then eSearch would be set to FTS3_FULLTEXT_SEARCH+4.
123630 */
123631 #define FTS3_FULLSCAN_SEARCH 0    /* Linear scan of %_content table */
123632 #define FTS3_DOCID_SEARCH    1    /* Lookup by rowid on %_content table */
123633 #define FTS3_FULLTEXT_SEARCH 2    /* Full-text index search */
123634 
123635 /*
123636 ** The lower 16-bits of the sqlite3_index_info.idxNum value set by
123637 ** the xBestIndex() method contains the Fts3Cursor.eSearch value described
123638 ** above. The upper 16-bits contain a combination of the following
123639 ** bits, used to describe extra constraints on full-text searches.
123640 */
123641 #define FTS3_HAVE_LANGID    0x00010000      /* languageid=? */
123642 #define FTS3_HAVE_DOCID_GE  0x00020000      /* docid>=? */
123643 #define FTS3_HAVE_DOCID_LE  0x00040000      /* docid<=? */
123644 
123645 struct Fts3Doclist {
123646   char *aAll;                    /* Array containing doclist (or NULL) */
123647   int nAll;                      /* Size of a[] in bytes */
123648   char *pNextDocid;              /* Pointer to next docid */
123649 
123650   sqlite3_int64 iDocid;          /* Current docid (if pList!=0) */
123651   int bFreeList;                 /* True if pList should be sqlite3_free()d */
123652   char *pList;                   /* Pointer to position list following iDocid */
123653   int nList;                     /* Length of position list */
123654 };
123655 
123656 /*
123657 ** A "phrase" is a sequence of one or more tokens that must match in
123658 ** sequence.  A single token is the base case and the most common case.
123659 ** For a sequence of tokens contained in double-quotes (i.e. "one two three")
123660 ** nToken will be the number of tokens in the string.
123661 */
123662 struct Fts3PhraseToken {
123663   char *z;                        /* Text of the token */
123664   int n;                          /* Number of bytes in buffer z */
123665   int isPrefix;                   /* True if token ends with a "*" character */
123666   int bFirst;                     /* True if token must appear at position 0 */
123667 
123668   /* Variables above this point are populated when the expression is
123669   ** parsed (by code in fts3_expr.c). Below this point the variables are
123670   ** used when evaluating the expression. */
123671   Fts3DeferredToken *pDeferred;   /* Deferred token object for this token */
123672   Fts3MultiSegReader *pSegcsr;    /* Segment-reader for this token */
123673 };
123674 
123675 struct Fts3Phrase {
123676   /* Cache of doclist for this phrase. */
123677   Fts3Doclist doclist;
123678   int bIncr;                 /* True if doclist is loaded incrementally */
123679   int iDoclistToken;
123680 
123681   /* Variables below this point are populated by fts3_expr.c when parsing 
123682   ** a MATCH expression. Everything above is part of the evaluation phase. 
123683   */
123684   int nToken;                /* Number of tokens in the phrase */
123685   int iColumn;               /* Index of column this phrase must match */
123686   Fts3PhraseToken aToken[1]; /* One entry for each token in the phrase */
123687 };
123688 
123689 /*
123690 ** A tree of these objects forms the RHS of a MATCH operator.
123691 **
123692 ** If Fts3Expr.eType is FTSQUERY_PHRASE and isLoaded is true, then aDoclist 
123693 ** points to a malloced buffer, size nDoclist bytes, containing the results 
123694 ** of this phrase query in FTS3 doclist format. As usual, the initial 
123695 ** "Length" field found in doclists stored on disk is omitted from this 
123696 ** buffer.
123697 **
123698 ** Variable aMI is used only for FTSQUERY_NEAR nodes to store the global
123699 ** matchinfo data. If it is not NULL, it points to an array of size nCol*3,
123700 ** where nCol is the number of columns in the queried FTS table. The array
123701 ** is populated as follows:
123702 **
123703 **   aMI[iCol*3 + 0] = Undefined
123704 **   aMI[iCol*3 + 1] = Number of occurrences
123705 **   aMI[iCol*3 + 2] = Number of rows containing at least one instance
123706 **
123707 ** The aMI array is allocated using sqlite3_malloc(). It should be freed 
123708 ** when the expression node is.
123709 */
123710 struct Fts3Expr {
123711   int eType;                 /* One of the FTSQUERY_XXX values defined below */
123712   int nNear;                 /* Valid if eType==FTSQUERY_NEAR */
123713   Fts3Expr *pParent;         /* pParent->pLeft==this or pParent->pRight==this */
123714   Fts3Expr *pLeft;           /* Left operand */
123715   Fts3Expr *pRight;          /* Right operand */
123716   Fts3Phrase *pPhrase;       /* Valid if eType==FTSQUERY_PHRASE */
123717 
123718   /* The following are used by the fts3_eval.c module. */
123719   sqlite3_int64 iDocid;      /* Current docid */
123720   u8 bEof;                   /* True this expression is at EOF already */
123721   u8 bStart;                 /* True if iDocid is valid */
123722   u8 bDeferred;              /* True if this expression is entirely deferred */
123723 
123724   u32 *aMI;
123725 };
123726 
123727 /*
123728 ** Candidate values for Fts3Query.eType. Note that the order of the first
123729 ** four values is in order of precedence when parsing expressions. For 
123730 ** example, the following:
123731 **
123732 **   "a OR b AND c NOT d NEAR e"
123733 **
123734 ** is equivalent to:
123735 **
123736 **   "a OR (b AND (c NOT (d NEAR e)))"
123737 */
123738 #define FTSQUERY_NEAR   1
123739 #define FTSQUERY_NOT    2
123740 #define FTSQUERY_AND    3
123741 #define FTSQUERY_OR     4
123742 #define FTSQUERY_PHRASE 5
123743 
123744 
123745 /* fts3_write.c */
123746 SQLITE_PRIVATE int sqlite3Fts3UpdateMethod(sqlite3_vtab*,int,sqlite3_value**,sqlite3_int64*);
123747 SQLITE_PRIVATE int sqlite3Fts3PendingTermsFlush(Fts3Table *);
123748 SQLITE_PRIVATE void sqlite3Fts3PendingTermsClear(Fts3Table *);
123749 SQLITE_PRIVATE int sqlite3Fts3Optimize(Fts3Table *);
123750 SQLITE_PRIVATE int sqlite3Fts3SegReaderNew(int, int, sqlite3_int64,
123751   sqlite3_int64, sqlite3_int64, const char *, int, Fts3SegReader**);
123752 SQLITE_PRIVATE int sqlite3Fts3SegReaderPending(
123753   Fts3Table*,int,const char*,int,int,Fts3SegReader**);
123754 SQLITE_PRIVATE void sqlite3Fts3SegReaderFree(Fts3SegReader *);
123755 SQLITE_PRIVATE int sqlite3Fts3AllSegdirs(Fts3Table*, int, int, int, sqlite3_stmt **);
123756 SQLITE_PRIVATE int sqlite3Fts3ReadBlock(Fts3Table*, sqlite3_int64, char **, int*, int*);
123757 
123758 SQLITE_PRIVATE int sqlite3Fts3SelectDoctotal(Fts3Table *, sqlite3_stmt **);
123759 SQLITE_PRIVATE int sqlite3Fts3SelectDocsize(Fts3Table *, sqlite3_int64, sqlite3_stmt **);
123760 
123761 #ifndef SQLITE_DISABLE_FTS4_DEFERRED
123762 SQLITE_PRIVATE void sqlite3Fts3FreeDeferredTokens(Fts3Cursor *);
123763 SQLITE_PRIVATE int sqlite3Fts3DeferToken(Fts3Cursor *, Fts3PhraseToken *, int);
123764 SQLITE_PRIVATE int sqlite3Fts3CacheDeferredDoclists(Fts3Cursor *);
123765 SQLITE_PRIVATE void sqlite3Fts3FreeDeferredDoclists(Fts3Cursor *);
123766 SQLITE_PRIVATE int sqlite3Fts3DeferredTokenList(Fts3DeferredToken *, char **, int *);
123767 #else
123768 # define sqlite3Fts3FreeDeferredTokens(x)
123769 # define sqlite3Fts3DeferToken(x,y,z) SQLITE_OK
123770 # define sqlite3Fts3CacheDeferredDoclists(x) SQLITE_OK
123771 # define sqlite3Fts3FreeDeferredDoclists(x)
123772 # define sqlite3Fts3DeferredTokenList(x,y,z) SQLITE_OK
123773 #endif
123774 
123775 SQLITE_PRIVATE void sqlite3Fts3SegmentsClose(Fts3Table *);
123776 SQLITE_PRIVATE int sqlite3Fts3MaxLevel(Fts3Table *, int *);
123777 
123778 /* Special values interpreted by sqlite3SegReaderCursor() */
123779 #define FTS3_SEGCURSOR_PENDING        -1
123780 #define FTS3_SEGCURSOR_ALL            -2
123781 
123782 SQLITE_PRIVATE int sqlite3Fts3SegReaderStart(Fts3Table*, Fts3MultiSegReader*, Fts3SegFilter*);
123783 SQLITE_PRIVATE int sqlite3Fts3SegReaderStep(Fts3Table *, Fts3MultiSegReader *);
123784 SQLITE_PRIVATE void sqlite3Fts3SegReaderFinish(Fts3MultiSegReader *);
123785 
123786 SQLITE_PRIVATE int sqlite3Fts3SegReaderCursor(Fts3Table *, 
123787     int, int, int, const char *, int, int, int, Fts3MultiSegReader *);
123788 
123789 /* Flags allowed as part of the 4th argument to SegmentReaderIterate() */
123790 #define FTS3_SEGMENT_REQUIRE_POS   0x00000001
123791 #define FTS3_SEGMENT_IGNORE_EMPTY  0x00000002
123792 #define FTS3_SEGMENT_COLUMN_FILTER 0x00000004
123793 #define FTS3_SEGMENT_PREFIX        0x00000008
123794 #define FTS3_SEGMENT_SCAN          0x00000010
123795 #define FTS3_SEGMENT_FIRST         0x00000020
123796 
123797 /* Type passed as 4th argument to SegmentReaderIterate() */
123798 struct Fts3SegFilter {
123799   const char *zTerm;
123800   int nTerm;
123801   int iCol;
123802   int flags;
123803 };
123804 
123805 struct Fts3MultiSegReader {
123806   /* Used internally by sqlite3Fts3SegReaderXXX() calls */
123807   Fts3SegReader **apSegment;      /* Array of Fts3SegReader objects */
123808   int nSegment;                   /* Size of apSegment array */
123809   int nAdvance;                   /* How many seg-readers to advance */
123810   Fts3SegFilter *pFilter;         /* Pointer to filter object */
123811   char *aBuffer;                  /* Buffer to merge doclists in */
123812   int nBuffer;                    /* Allocated size of aBuffer[] in bytes */
123813 
123814   int iColFilter;                 /* If >=0, filter for this column */
123815   int bRestart;
123816 
123817   /* Used by fts3.c only. */
123818   int nCost;                      /* Cost of running iterator */
123819   int bLookup;                    /* True if a lookup of a single entry. */
123820 
123821   /* Output values. Valid only after Fts3SegReaderStep() returns SQLITE_ROW. */
123822   char *zTerm;                    /* Pointer to term buffer */
123823   int nTerm;                      /* Size of zTerm in bytes */
123824   char *aDoclist;                 /* Pointer to doclist buffer */
123825   int nDoclist;                   /* Size of aDoclist[] in bytes */
123826 };
123827 
123828 SQLITE_PRIVATE int sqlite3Fts3Incrmerge(Fts3Table*,int,int);
123829 
123830 #define fts3GetVarint32(p, piVal) (                                           \
123831   (*(u8*)(p)&0x80) ? sqlite3Fts3GetVarint32(p, piVal) : (*piVal=*(u8*)(p), 1) \
123832 )
123833 
123834 /* fts3.c */
123835 SQLITE_PRIVATE int sqlite3Fts3PutVarint(char *, sqlite3_int64);
123836 SQLITE_PRIVATE int sqlite3Fts3GetVarint(const char *, sqlite_int64 *);
123837 SQLITE_PRIVATE int sqlite3Fts3GetVarint32(const char *, int *);
123838 SQLITE_PRIVATE int sqlite3Fts3VarintLen(sqlite3_uint64);
123839 SQLITE_PRIVATE void sqlite3Fts3Dequote(char *);
123840 SQLITE_PRIVATE void sqlite3Fts3DoclistPrev(int,char*,int,char**,sqlite3_int64*,int*,u8*);
123841 SQLITE_PRIVATE int sqlite3Fts3EvalPhraseStats(Fts3Cursor *, Fts3Expr *, u32 *);
123842 SQLITE_PRIVATE int sqlite3Fts3FirstFilter(sqlite3_int64, char *, int, char *);
123843 SQLITE_PRIVATE void sqlite3Fts3CreateStatTable(int*, Fts3Table*);
123844 
123845 /* fts3_tokenizer.c */
123846 SQLITE_PRIVATE const char *sqlite3Fts3NextToken(const char *, int *);
123847 SQLITE_PRIVATE int sqlite3Fts3InitHashTable(sqlite3 *, Fts3Hash *, const char *);
123848 SQLITE_PRIVATE int sqlite3Fts3InitTokenizer(Fts3Hash *pHash, const char *, 
123849     sqlite3_tokenizer **, char **
123850 );
123851 SQLITE_PRIVATE int sqlite3Fts3IsIdChar(char);
123852 
123853 /* fts3_snippet.c */
123854 SQLITE_PRIVATE void sqlite3Fts3Offsets(sqlite3_context*, Fts3Cursor*);
123855 SQLITE_PRIVATE void sqlite3Fts3Snippet(sqlite3_context *, Fts3Cursor *, const char *,
123856   const char *, const char *, int, int
123857 );
123858 SQLITE_PRIVATE void sqlite3Fts3Matchinfo(sqlite3_context *, Fts3Cursor *, const char *);
123859 
123860 /* fts3_expr.c */
123861 SQLITE_PRIVATE int sqlite3Fts3ExprParse(sqlite3_tokenizer *, int,
123862   char **, int, int, int, const char *, int, Fts3Expr **, char **
123863 );
123864 SQLITE_PRIVATE void sqlite3Fts3ExprFree(Fts3Expr *);
123865 #ifdef SQLITE_TEST
123866 SQLITE_PRIVATE int sqlite3Fts3ExprInitTestInterface(sqlite3 *db);
123867 SQLITE_PRIVATE int sqlite3Fts3InitTerm(sqlite3 *db);
123868 #endif
123869 
123870 SQLITE_PRIVATE int sqlite3Fts3OpenTokenizer(sqlite3_tokenizer *, int, const char *, int,
123871   sqlite3_tokenizer_cursor **
123872 );
123873 
123874 /* fts3_aux.c */
123875 SQLITE_PRIVATE int sqlite3Fts3InitAux(sqlite3 *db);
123876 
123877 SQLITE_PRIVATE void sqlite3Fts3EvalPhraseCleanup(Fts3Phrase *);
123878 
123879 SQLITE_PRIVATE int sqlite3Fts3MsrIncrStart(
123880     Fts3Table*, Fts3MultiSegReader*, int, const char*, int);
123881 SQLITE_PRIVATE int sqlite3Fts3MsrIncrNext(
123882     Fts3Table *, Fts3MultiSegReader *, sqlite3_int64 *, char **, int *);
123883 SQLITE_PRIVATE int sqlite3Fts3EvalPhrasePoslist(Fts3Cursor *, Fts3Expr *, int iCol, char **); 
123884 SQLITE_PRIVATE int sqlite3Fts3MsrOvfl(Fts3Cursor *, Fts3MultiSegReader *, int *);
123885 SQLITE_PRIVATE int sqlite3Fts3MsrIncrRestart(Fts3MultiSegReader *pCsr);
123886 
123887 /* fts3_tokenize_vtab.c */
123888 SQLITE_PRIVATE int sqlite3Fts3InitTok(sqlite3*, Fts3Hash *);
123889 
123890 /* fts3_unicode2.c (functions generated by parsing unicode text files) */
123891 #ifdef SQLITE_ENABLE_FTS4_UNICODE61
123892 SQLITE_PRIVATE int sqlite3FtsUnicodeFold(int, int);
123893 SQLITE_PRIVATE int sqlite3FtsUnicodeIsalnum(int);
123894 SQLITE_PRIVATE int sqlite3FtsUnicodeIsdiacritic(int);
123895 #endif
123896 
123897 #endif /* !SQLITE_CORE || SQLITE_ENABLE_FTS3 */
123898 #endif /* _FTSINT_H */
123899 
123900 /************** End of fts3Int.h *********************************************/
123901 /************** Continuing where we left off in fts3.c ***********************/
123902 #if !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_FTS3)
123903 
123904 #if defined(SQLITE_ENABLE_FTS3) && !defined(SQLITE_CORE)
123905 # define SQLITE_CORE 1
123906 #endif
123907 
123908 /* #include <assert.h> */
123909 /* #include <stdlib.h> */
123910 /* #include <stddef.h> */
123911 /* #include <stdio.h> */
123912 /* #include <string.h> */
123913 /* #include <stdarg.h> */
123914 
123915 #ifndef SQLITE_CORE 
123916   SQLITE_EXTENSION_INIT1
123917 #endif
123918 
123919 static int fts3EvalNext(Fts3Cursor *pCsr);
123920 static int fts3EvalStart(Fts3Cursor *pCsr);
123921 static int fts3TermSegReaderCursor(
123922     Fts3Cursor *, const char *, int, int, Fts3MultiSegReader **);
123923 
123924 /* 
123925 ** Write a 64-bit variable-length integer to memory starting at p[0].
123926 ** The length of data written will be between 1 and FTS3_VARINT_MAX bytes.
123927 ** The number of bytes written is returned.
123928 */
123929 SQLITE_PRIVATE int sqlite3Fts3PutVarint(char *p, sqlite_int64 v){
123930   unsigned char *q = (unsigned char *) p;
123931   sqlite_uint64 vu = v;
123932   do{
123933     *q++ = (unsigned char) ((vu & 0x7f) | 0x80);
123934     vu >>= 7;
123935   }while( vu!=0 );
123936   q[-1] &= 0x7f;  /* turn off high bit in final byte */
123937   assert( q - (unsigned char *)p <= FTS3_VARINT_MAX );
123938   return (int) (q - (unsigned char *)p);
123939 }
123940 
123941 #define GETVARINT_STEP(v, ptr, shift, mask1, mask2, var, ret) \
123942   v = (v & mask1) | ( (*ptr++) << shift );                    \
123943   if( (v & mask2)==0 ){ var = v; return ret; }
123944 #define GETVARINT_INIT(v, ptr, shift, mask1, mask2, var, ret) \
123945   v = (*ptr++);                                               \
123946   if( (v & mask2)==0 ){ var = v; return ret; }
123947 
123948 /* 
123949 ** Read a 64-bit variable-length integer from memory starting at p[0].
123950 ** Return the number of bytes read, or 0 on error.
123951 ** The value is stored in *v.
123952 */
123953 SQLITE_PRIVATE int sqlite3Fts3GetVarint(const char *p, sqlite_int64 *v){
123954   const char *pStart = p;
123955   u32 a;
123956   u64 b;
123957   int shift;
123958 
123959   GETVARINT_INIT(a, p, 0,  0x00,     0x80, *v, 1);
123960   GETVARINT_STEP(a, p, 7,  0x7F,     0x4000, *v, 2);
123961   GETVARINT_STEP(a, p, 14, 0x3FFF,   0x200000, *v, 3);
123962   GETVARINT_STEP(a, p, 21, 0x1FFFFF, 0x10000000, *v, 4);
123963   b = (a & 0x0FFFFFFF );
123964 
123965   for(shift=28; shift<=63; shift+=7){
123966     u64 c = *p++;
123967     b += (c&0x7F) << shift;
123968     if( (c & 0x80)==0 ) break;
123969   }
123970   *v = b;
123971   return (int)(p - pStart);
123972 }
123973 
123974 /*
123975 ** Similar to sqlite3Fts3GetVarint(), except that the output is truncated to a
123976 ** 32-bit integer before it is returned.
123977 */
123978 SQLITE_PRIVATE int sqlite3Fts3GetVarint32(const char *p, int *pi){
123979   u32 a;
123980 
123981 #ifndef fts3GetVarint32
123982   GETVARINT_INIT(a, p, 0,  0x00,     0x80, *pi, 1);
123983 #else
123984   a = (*p++);
123985   assert( a & 0x80 );
123986 #endif
123987 
123988   GETVARINT_STEP(a, p, 7,  0x7F,     0x4000, *pi, 2);
123989   GETVARINT_STEP(a, p, 14, 0x3FFF,   0x200000, *pi, 3);
123990   GETVARINT_STEP(a, p, 21, 0x1FFFFF, 0x10000000, *pi, 4);
123991   a = (a & 0x0FFFFFFF );
123992   *pi = (int)(a | ((u32)(*p & 0x0F) << 28));
123993   return 5;
123994 }
123995 
123996 /*
123997 ** Return the number of bytes required to encode v as a varint
123998 */
123999 SQLITE_PRIVATE int sqlite3Fts3VarintLen(sqlite3_uint64 v){
124000   int i = 0;
124001   do{
124002     i++;
124003     v >>= 7;
124004   }while( v!=0 );
124005   return i;
124006 }
124007 
124008 /*
124009 ** Convert an SQL-style quoted string into a normal string by removing
124010 ** the quote characters.  The conversion is done in-place.  If the
124011 ** input does not begin with a quote character, then this routine
124012 ** is a no-op.
124013 **
124014 ** Examples:
124015 **
124016 **     "abc"   becomes   abc
124017 **     'xyz'   becomes   xyz
124018 **     [pqr]   becomes   pqr
124019 **     `mno`   becomes   mno
124020 **
124021 */
124022 SQLITE_PRIVATE void sqlite3Fts3Dequote(char *z){
124023   char quote;                     /* Quote character (if any ) */
124024 
124025   quote = z[0];
124026   if( quote=='[' || quote=='\'' || quote=='"' || quote=='`' ){
124027     int iIn = 1;                  /* Index of next byte to read from input */
124028     int iOut = 0;                 /* Index of next byte to write to output */
124029 
124030     /* If the first byte was a '[', then the close-quote character is a ']' */
124031     if( quote=='[' ) quote = ']';  
124032 
124033     while( ALWAYS(z[iIn]) ){
124034       if( z[iIn]==quote ){
124035         if( z[iIn+1]!=quote ) break;
124036         z[iOut++] = quote;
124037         iIn += 2;
124038       }else{
124039         z[iOut++] = z[iIn++];
124040       }
124041     }
124042     z[iOut] = '\0';
124043   }
124044 }
124045 
124046 /*
124047 ** Read a single varint from the doclist at *pp and advance *pp to point
124048 ** to the first byte past the end of the varint.  Add the value of the varint
124049 ** to *pVal.
124050 */
124051 static void fts3GetDeltaVarint(char **pp, sqlite3_int64 *pVal){
124052   sqlite3_int64 iVal;
124053   *pp += sqlite3Fts3GetVarint(*pp, &iVal);
124054   *pVal += iVal;
124055 }
124056 
124057 /*
124058 ** When this function is called, *pp points to the first byte following a
124059 ** varint that is part of a doclist (or position-list, or any other list
124060 ** of varints). This function moves *pp to point to the start of that varint,
124061 ** and sets *pVal by the varint value.
124062 **
124063 ** Argument pStart points to the first byte of the doclist that the
124064 ** varint is part of.
124065 */
124066 static void fts3GetReverseVarint(
124067   char **pp, 
124068   char *pStart, 
124069   sqlite3_int64 *pVal
124070 ){
124071   sqlite3_int64 iVal;
124072   char *p;
124073 
124074   /* Pointer p now points at the first byte past the varint we are 
124075   ** interested in. So, unless the doclist is corrupt, the 0x80 bit is
124076   ** clear on character p[-1]. */
124077   for(p = (*pp)-2; p>=pStart && *p&0x80; p--);
124078   p++;
124079   *pp = p;
124080 
124081   sqlite3Fts3GetVarint(p, &iVal);
124082   *pVal = iVal;
124083 }
124084 
124085 /*
124086 ** The xDisconnect() virtual table method.
124087 */
124088 static int fts3DisconnectMethod(sqlite3_vtab *pVtab){
124089   Fts3Table *p = (Fts3Table *)pVtab;
124090   int i;
124091 
124092   assert( p->nPendingData==0 );
124093   assert( p->pSegments==0 );
124094 
124095   /* Free any prepared statements held */
124096   for(i=0; i<SizeofArray(p->aStmt); i++){
124097     sqlite3_finalize(p->aStmt[i]);
124098   }
124099   sqlite3_free(p->zSegmentsTbl);
124100   sqlite3_free(p->zReadExprlist);
124101   sqlite3_free(p->zWriteExprlist);
124102   sqlite3_free(p->zContentTbl);
124103   sqlite3_free(p->zLanguageid);
124104 
124105   /* Invoke the tokenizer destructor to free the tokenizer. */
124106   p->pTokenizer->pModule->xDestroy(p->pTokenizer);
124107 
124108   sqlite3_free(p);
124109   return SQLITE_OK;
124110 }
124111 
124112 /*
124113 ** Construct one or more SQL statements from the format string given
124114 ** and then evaluate those statements. The success code is written
124115 ** into *pRc.
124116 **
124117 ** If *pRc is initially non-zero then this routine is a no-op.
124118 */
124119 static void fts3DbExec(
124120   int *pRc,              /* Success code */
124121   sqlite3 *db,           /* Database in which to run SQL */
124122   const char *zFormat,   /* Format string for SQL */
124123   ...                    /* Arguments to the format string */
124124 ){
124125   va_list ap;
124126   char *zSql;
124127   if( *pRc ) return;
124128   va_start(ap, zFormat);
124129   zSql = sqlite3_vmprintf(zFormat, ap);
124130   va_end(ap);
124131   if( zSql==0 ){
124132     *pRc = SQLITE_NOMEM;
124133   }else{
124134     *pRc = sqlite3_exec(db, zSql, 0, 0, 0);
124135     sqlite3_free(zSql);
124136   }
124137 }
124138 
124139 /*
124140 ** The xDestroy() virtual table method.
124141 */
124142 static int fts3DestroyMethod(sqlite3_vtab *pVtab){
124143   Fts3Table *p = (Fts3Table *)pVtab;
124144   int rc = SQLITE_OK;              /* Return code */
124145   const char *zDb = p->zDb;        /* Name of database (e.g. "main", "temp") */
124146   sqlite3 *db = p->db;             /* Database handle */
124147 
124148   /* Drop the shadow tables */
124149   if( p->zContentTbl==0 ){
124150     fts3DbExec(&rc, db, "DROP TABLE IF EXISTS %Q.'%q_content'", zDb, p->zName);
124151   }
124152   fts3DbExec(&rc, db, "DROP TABLE IF EXISTS %Q.'%q_segments'", zDb,p->zName);
124153   fts3DbExec(&rc, db, "DROP TABLE IF EXISTS %Q.'%q_segdir'", zDb, p->zName);
124154   fts3DbExec(&rc, db, "DROP TABLE IF EXISTS %Q.'%q_docsize'", zDb, p->zName);
124155   fts3DbExec(&rc, db, "DROP TABLE IF EXISTS %Q.'%q_stat'", zDb, p->zName);
124156 
124157   /* If everything has worked, invoke fts3DisconnectMethod() to free the
124158   ** memory associated with the Fts3Table structure and return SQLITE_OK.
124159   ** Otherwise, return an SQLite error code.
124160   */
124161   return (rc==SQLITE_OK ? fts3DisconnectMethod(pVtab) : rc);
124162 }
124163 
124164 
124165 /*
124166 ** Invoke sqlite3_declare_vtab() to declare the schema for the FTS3 table
124167 ** passed as the first argument. This is done as part of the xConnect()
124168 ** and xCreate() methods.
124169 **
124170 ** If *pRc is non-zero when this function is called, it is a no-op. 
124171 ** Otherwise, if an error occurs, an SQLite error code is stored in *pRc
124172 ** before returning.
124173 */
124174 static void fts3DeclareVtab(int *pRc, Fts3Table *p){
124175   if( *pRc==SQLITE_OK ){
124176     int i;                        /* Iterator variable */
124177     int rc;                       /* Return code */
124178     char *zSql;                   /* SQL statement passed to declare_vtab() */
124179     char *zCols;                  /* List of user defined columns */
124180     const char *zLanguageid;
124181 
124182     zLanguageid = (p->zLanguageid ? p->zLanguageid : "__langid");
124183     sqlite3_vtab_config(p->db, SQLITE_VTAB_CONSTRAINT_SUPPORT, 1);
124184 
124185     /* Create a list of user columns for the virtual table */
124186     zCols = sqlite3_mprintf("%Q, ", p->azColumn[0]);
124187     for(i=1; zCols && i<p->nColumn; i++){
124188       zCols = sqlite3_mprintf("%z%Q, ", zCols, p->azColumn[i]);
124189     }
124190 
124191     /* Create the whole "CREATE TABLE" statement to pass to SQLite */
124192     zSql = sqlite3_mprintf(
124193         "CREATE TABLE x(%s %Q HIDDEN, docid HIDDEN, %Q HIDDEN)", 
124194         zCols, p->zName, zLanguageid
124195     );
124196     if( !zCols || !zSql ){
124197       rc = SQLITE_NOMEM;
124198     }else{
124199       rc = sqlite3_declare_vtab(p->db, zSql);
124200     }
124201 
124202     sqlite3_free(zSql);
124203     sqlite3_free(zCols);
124204     *pRc = rc;
124205   }
124206 }
124207 
124208 /*
124209 ** Create the %_stat table if it does not already exist.
124210 */
124211 SQLITE_PRIVATE void sqlite3Fts3CreateStatTable(int *pRc, Fts3Table *p){
124212   fts3DbExec(pRc, p->db, 
124213       "CREATE TABLE IF NOT EXISTS %Q.'%q_stat'"
124214           "(id INTEGER PRIMARY KEY, value BLOB);",
124215       p->zDb, p->zName
124216   );
124217   if( (*pRc)==SQLITE_OK ) p->bHasStat = 1;
124218 }
124219 
124220 /*
124221 ** Create the backing store tables (%_content, %_segments and %_segdir)
124222 ** required by the FTS3 table passed as the only argument. This is done
124223 ** as part of the vtab xCreate() method.
124224 **
124225 ** If the p->bHasDocsize boolean is true (indicating that this is an
124226 ** FTS4 table, not an FTS3 table) then also create the %_docsize and
124227 ** %_stat tables required by FTS4.
124228 */
124229 static int fts3CreateTables(Fts3Table *p){
124230   int rc = SQLITE_OK;             /* Return code */
124231   int i;                          /* Iterator variable */
124232   sqlite3 *db = p->db;            /* The database connection */
124233 
124234   if( p->zContentTbl==0 ){
124235     const char *zLanguageid = p->zLanguageid;
124236     char *zContentCols;           /* Columns of %_content table */
124237 
124238     /* Create a list of user columns for the content table */
124239     zContentCols = sqlite3_mprintf("docid INTEGER PRIMARY KEY");
124240     for(i=0; zContentCols && i<p->nColumn; i++){
124241       char *z = p->azColumn[i];
124242       zContentCols = sqlite3_mprintf("%z, 'c%d%q'", zContentCols, i, z);
124243     }
124244     if( zLanguageid && zContentCols ){
124245       zContentCols = sqlite3_mprintf("%z, langid", zContentCols, zLanguageid);
124246     }
124247     if( zContentCols==0 ) rc = SQLITE_NOMEM;
124248   
124249     /* Create the content table */
124250     fts3DbExec(&rc, db, 
124251        "CREATE TABLE %Q.'%q_content'(%s)",
124252        p->zDb, p->zName, zContentCols
124253     );
124254     sqlite3_free(zContentCols);
124255   }
124256 
124257   /* Create other tables */
124258   fts3DbExec(&rc, db, 
124259       "CREATE TABLE %Q.'%q_segments'(blockid INTEGER PRIMARY KEY, block BLOB);",
124260       p->zDb, p->zName
124261   );
124262   fts3DbExec(&rc, db, 
124263       "CREATE TABLE %Q.'%q_segdir'("
124264         "level INTEGER,"
124265         "idx INTEGER,"
124266         "start_block INTEGER,"
124267         "leaves_end_block INTEGER,"
124268         "end_block INTEGER,"
124269         "root BLOB,"
124270         "PRIMARY KEY(level, idx)"
124271       ");",
124272       p->zDb, p->zName
124273   );
124274   if( p->bHasDocsize ){
124275     fts3DbExec(&rc, db, 
124276         "CREATE TABLE %Q.'%q_docsize'(docid INTEGER PRIMARY KEY, size BLOB);",
124277         p->zDb, p->zName
124278     );
124279   }
124280   assert( p->bHasStat==p->bFts4 );
124281   if( p->bHasStat ){
124282     sqlite3Fts3CreateStatTable(&rc, p);
124283   }
124284   return rc;
124285 }
124286 
124287 /*
124288 ** Store the current database page-size in bytes in p->nPgsz.
124289 **
124290 ** If *pRc is non-zero when this function is called, it is a no-op. 
124291 ** Otherwise, if an error occurs, an SQLite error code is stored in *pRc
124292 ** before returning.
124293 */
124294 static void fts3DatabasePageSize(int *pRc, Fts3Table *p){
124295   if( *pRc==SQLITE_OK ){
124296     int rc;                       /* Return code */
124297     char *zSql;                   /* SQL text "PRAGMA %Q.page_size" */
124298     sqlite3_stmt *pStmt;          /* Compiled "PRAGMA %Q.page_size" statement */
124299   
124300     zSql = sqlite3_mprintf("PRAGMA %Q.page_size", p->zDb);
124301     if( !zSql ){
124302       rc = SQLITE_NOMEM;
124303     }else{
124304       rc = sqlite3_prepare(p->db, zSql, -1, &pStmt, 0);
124305       if( rc==SQLITE_OK ){
124306         sqlite3_step(pStmt);
124307         p->nPgsz = sqlite3_column_int(pStmt, 0);
124308         rc = sqlite3_finalize(pStmt);
124309       }else if( rc==SQLITE_AUTH ){
124310         p->nPgsz = 1024;
124311         rc = SQLITE_OK;
124312       }
124313     }
124314     assert( p->nPgsz>0 || rc!=SQLITE_OK );
124315     sqlite3_free(zSql);
124316     *pRc = rc;
124317   }
124318 }
124319 
124320 /*
124321 ** "Special" FTS4 arguments are column specifications of the following form:
124322 **
124323 **   <key> = <value>
124324 **
124325 ** There may not be whitespace surrounding the "=" character. The <value> 
124326 ** term may be quoted, but the <key> may not.
124327 */
124328 static int fts3IsSpecialColumn(
124329   const char *z, 
124330   int *pnKey,
124331   char **pzValue
124332 ){
124333   char *zValue;
124334   const char *zCsr = z;
124335 
124336   while( *zCsr!='=' ){
124337     if( *zCsr=='\0' ) return 0;
124338     zCsr++;
124339   }
124340 
124341   *pnKey = (int)(zCsr-z);
124342   zValue = sqlite3_mprintf("%s", &zCsr[1]);
124343   if( zValue ){
124344     sqlite3Fts3Dequote(zValue);
124345   }
124346   *pzValue = zValue;
124347   return 1;
124348 }
124349 
124350 /*
124351 ** Append the output of a printf() style formatting to an existing string.
124352 */
124353 static void fts3Appendf(
124354   int *pRc,                       /* IN/OUT: Error code */
124355   char **pz,                      /* IN/OUT: Pointer to string buffer */
124356   const char *zFormat,            /* Printf format string to append */
124357   ...                             /* Arguments for printf format string */
124358 ){
124359   if( *pRc==SQLITE_OK ){
124360     va_list ap;
124361     char *z;
124362     va_start(ap, zFormat);
124363     z = sqlite3_vmprintf(zFormat, ap);
124364     va_end(ap);
124365     if( z && *pz ){
124366       char *z2 = sqlite3_mprintf("%s%s", *pz, z);
124367       sqlite3_free(z);
124368       z = z2;
124369     }
124370     if( z==0 ) *pRc = SQLITE_NOMEM;
124371     sqlite3_free(*pz);
124372     *pz = z;
124373   }
124374 }
124375 
124376 /*
124377 ** Return a copy of input string zInput enclosed in double-quotes (") and
124378 ** with all double quote characters escaped. For example:
124379 **
124380 **     fts3QuoteId("un \"zip\"")   ->    "un \"\"zip\"\""
124381 **
124382 ** The pointer returned points to memory obtained from sqlite3_malloc(). It
124383 ** is the callers responsibility to call sqlite3_free() to release this
124384 ** memory.
124385 */
124386 static char *fts3QuoteId(char const *zInput){
124387   int nRet;
124388   char *zRet;
124389   nRet = 2 + (int)strlen(zInput)*2 + 1;
124390   zRet = sqlite3_malloc(nRet);
124391   if( zRet ){
124392     int i;
124393     char *z = zRet;
124394     *(z++) = '"';
124395     for(i=0; zInput[i]; i++){
124396       if( zInput[i]=='"' ) *(z++) = '"';
124397       *(z++) = zInput[i];
124398     }
124399     *(z++) = '"';
124400     *(z++) = '\0';
124401   }
124402   return zRet;
124403 }
124404 
124405 /*
124406 ** Return a list of comma separated SQL expressions and a FROM clause that 
124407 ** could be used in a SELECT statement such as the following:
124408 **
124409 **     SELECT <list of expressions> FROM %_content AS x ...
124410 **
124411 ** to return the docid, followed by each column of text data in order
124412 ** from left to write. If parameter zFunc is not NULL, then instead of
124413 ** being returned directly each column of text data is passed to an SQL
124414 ** function named zFunc first. For example, if zFunc is "unzip" and the
124415 ** table has the three user-defined columns "a", "b", and "c", the following
124416 ** string is returned:
124417 **
124418 **     "docid, unzip(x.'a'), unzip(x.'b'), unzip(x.'c') FROM %_content AS x"
124419 **
124420 ** The pointer returned points to a buffer allocated by sqlite3_malloc(). It
124421 ** is the responsibility of the caller to eventually free it.
124422 **
124423 ** If *pRc is not SQLITE_OK when this function is called, it is a no-op (and
124424 ** a NULL pointer is returned). Otherwise, if an OOM error is encountered
124425 ** by this function, NULL is returned and *pRc is set to SQLITE_NOMEM. If
124426 ** no error occurs, *pRc is left unmodified.
124427 */
124428 static char *fts3ReadExprList(Fts3Table *p, const char *zFunc, int *pRc){
124429   char *zRet = 0;
124430   char *zFree = 0;
124431   char *zFunction;
124432   int i;
124433 
124434   if( p->zContentTbl==0 ){
124435     if( !zFunc ){
124436       zFunction = "";
124437     }else{
124438       zFree = zFunction = fts3QuoteId(zFunc);
124439     }
124440     fts3Appendf(pRc, &zRet, "docid");
124441     for(i=0; i<p->nColumn; i++){
124442       fts3Appendf(pRc, &zRet, ",%s(x.'c%d%q')", zFunction, i, p->azColumn[i]);
124443     }
124444     if( p->zLanguageid ){
124445       fts3Appendf(pRc, &zRet, ", x.%Q", "langid");
124446     }
124447     sqlite3_free(zFree);
124448   }else{
124449     fts3Appendf(pRc, &zRet, "rowid");
124450     for(i=0; i<p->nColumn; i++){
124451       fts3Appendf(pRc, &zRet, ", x.'%q'", p->azColumn[i]);
124452     }
124453     if( p->zLanguageid ){
124454       fts3Appendf(pRc, &zRet, ", x.%Q", p->zLanguageid);
124455     }
124456   }
124457   fts3Appendf(pRc, &zRet, " FROM '%q'.'%q%s' AS x", 
124458       p->zDb,
124459       (p->zContentTbl ? p->zContentTbl : p->zName),
124460       (p->zContentTbl ? "" : "_content")
124461   );
124462   return zRet;
124463 }
124464 
124465 /*
124466 ** Return a list of N comma separated question marks, where N is the number
124467 ** of columns in the %_content table (one for the docid plus one for each
124468 ** user-defined text column).
124469 **
124470 ** If argument zFunc is not NULL, then all but the first question mark
124471 ** is preceded by zFunc and an open bracket, and followed by a closed
124472 ** bracket. For example, if zFunc is "zip" and the FTS3 table has three 
124473 ** user-defined text columns, the following string is returned:
124474 **
124475 **     "?, zip(?), zip(?), zip(?)"
124476 **
124477 ** The pointer returned points to a buffer allocated by sqlite3_malloc(). It
124478 ** is the responsibility of the caller to eventually free it.
124479 **
124480 ** If *pRc is not SQLITE_OK when this function is called, it is a no-op (and
124481 ** a NULL pointer is returned). Otherwise, if an OOM error is encountered
124482 ** by this function, NULL is returned and *pRc is set to SQLITE_NOMEM. If
124483 ** no error occurs, *pRc is left unmodified.
124484 */
124485 static char *fts3WriteExprList(Fts3Table *p, const char *zFunc, int *pRc){
124486   char *zRet = 0;
124487   char *zFree = 0;
124488   char *zFunction;
124489   int i;
124490 
124491   if( !zFunc ){
124492     zFunction = "";
124493   }else{
124494     zFree = zFunction = fts3QuoteId(zFunc);
124495   }
124496   fts3Appendf(pRc, &zRet, "?");
124497   for(i=0; i<p->nColumn; i++){
124498     fts3Appendf(pRc, &zRet, ",%s(?)", zFunction);
124499   }
124500   if( p->zLanguageid ){
124501     fts3Appendf(pRc, &zRet, ", ?");
124502   }
124503   sqlite3_free(zFree);
124504   return zRet;
124505 }
124506 
124507 /*
124508 ** This function interprets the string at (*pp) as a non-negative integer
124509 ** value. It reads the integer and sets *pnOut to the value read, then 
124510 ** sets *pp to point to the byte immediately following the last byte of
124511 ** the integer value.
124512 **
124513 ** Only decimal digits ('0'..'9') may be part of an integer value. 
124514 **
124515 ** If *pp does not being with a decimal digit SQLITE_ERROR is returned and
124516 ** the output value undefined. Otherwise SQLITE_OK is returned.
124517 **
124518 ** This function is used when parsing the "prefix=" FTS4 parameter.
124519 */
124520 static int fts3GobbleInt(const char **pp, int *pnOut){
124521   const char *p;                  /* Iterator pointer */
124522   int nInt = 0;                   /* Output value */
124523 
124524   for(p=*pp; p[0]>='0' && p[0]<='9'; p++){
124525     nInt = nInt * 10 + (p[0] - '0');
124526   }
124527   if( p==*pp ) return SQLITE_ERROR;
124528   *pnOut = nInt;
124529   *pp = p;
124530   return SQLITE_OK;
124531 }
124532 
124533 /*
124534 ** This function is called to allocate an array of Fts3Index structures
124535 ** representing the indexes maintained by the current FTS table. FTS tables
124536 ** always maintain the main "terms" index, but may also maintain one or
124537 ** more "prefix" indexes, depending on the value of the "prefix=" parameter
124538 ** (if any) specified as part of the CREATE VIRTUAL TABLE statement.
124539 **
124540 ** Argument zParam is passed the value of the "prefix=" option if one was
124541 ** specified, or NULL otherwise.
124542 **
124543 ** If no error occurs, SQLITE_OK is returned and *apIndex set to point to
124544 ** the allocated array. *pnIndex is set to the number of elements in the
124545 ** array. If an error does occur, an SQLite error code is returned.
124546 **
124547 ** Regardless of whether or not an error is returned, it is the responsibility
124548 ** of the caller to call sqlite3_free() on the output array to free it.
124549 */
124550 static int fts3PrefixParameter(
124551   const char *zParam,             /* ABC in prefix=ABC parameter to parse */
124552   int *pnIndex,                   /* OUT: size of *apIndex[] array */
124553   struct Fts3Index **apIndex      /* OUT: Array of indexes for this table */
124554 ){
124555   struct Fts3Index *aIndex;       /* Allocated array */
124556   int nIndex = 1;                 /* Number of entries in array */
124557 
124558   if( zParam && zParam[0] ){
124559     const char *p;
124560     nIndex++;
124561     for(p=zParam; *p; p++){
124562       if( *p==',' ) nIndex++;
124563     }
124564   }
124565 
124566   aIndex = sqlite3_malloc(sizeof(struct Fts3Index) * nIndex);
124567   *apIndex = aIndex;
124568   *pnIndex = nIndex;
124569   if( !aIndex ){
124570     return SQLITE_NOMEM;
124571   }
124572 
124573   memset(aIndex, 0, sizeof(struct Fts3Index) * nIndex);
124574   if( zParam ){
124575     const char *p = zParam;
124576     int i;
124577     for(i=1; i<nIndex; i++){
124578       int nPrefix;
124579       if( fts3GobbleInt(&p, &nPrefix) ) return SQLITE_ERROR;
124580       aIndex[i].nPrefix = nPrefix;
124581       p++;
124582     }
124583   }
124584 
124585   return SQLITE_OK;
124586 }
124587 
124588 /*
124589 ** This function is called when initializing an FTS4 table that uses the
124590 ** content=xxx option. It determines the number of and names of the columns
124591 ** of the new FTS4 table.
124592 **
124593 ** The third argument passed to this function is the value passed to the
124594 ** config=xxx option (i.e. "xxx"). This function queries the database for
124595 ** a table of that name. If found, the output variables are populated
124596 ** as follows:
124597 **
124598 **   *pnCol:   Set to the number of columns table xxx has,
124599 **
124600 **   *pnStr:   Set to the total amount of space required to store a copy
124601 **             of each columns name, including the nul-terminator.
124602 **
124603 **   *pazCol:  Set to point to an array of *pnCol strings. Each string is
124604 **             the name of the corresponding column in table xxx. The array
124605 **             and its contents are allocated using a single allocation. It
124606 **             is the responsibility of the caller to free this allocation
124607 **             by eventually passing the *pazCol value to sqlite3_free().
124608 **
124609 ** If the table cannot be found, an error code is returned and the output
124610 ** variables are undefined. Or, if an OOM is encountered, SQLITE_NOMEM is
124611 ** returned (and the output variables are undefined).
124612 */
124613 static int fts3ContentColumns(
124614   sqlite3 *db,                    /* Database handle */
124615   const char *zDb,                /* Name of db (i.e. "main", "temp" etc.) */
124616   const char *zTbl,               /* Name of content table */
124617   const char ***pazCol,           /* OUT: Malloc'd array of column names */
124618   int *pnCol,                     /* OUT: Size of array *pazCol */
124619   int *pnStr                      /* OUT: Bytes of string content */
124620 ){
124621   int rc = SQLITE_OK;             /* Return code */
124622   char *zSql;                     /* "SELECT *" statement on zTbl */  
124623   sqlite3_stmt *pStmt = 0;        /* Compiled version of zSql */
124624 
124625   zSql = sqlite3_mprintf("SELECT * FROM %Q.%Q", zDb, zTbl);
124626   if( !zSql ){
124627     rc = SQLITE_NOMEM;
124628   }else{
124629     rc = sqlite3_prepare(db, zSql, -1, &pStmt, 0);
124630   }
124631   sqlite3_free(zSql);
124632 
124633   if( rc==SQLITE_OK ){
124634     const char **azCol;           /* Output array */
124635     int nStr = 0;                 /* Size of all column names (incl. 0x00) */
124636     int nCol;                     /* Number of table columns */
124637     int i;                        /* Used to iterate through columns */
124638 
124639     /* Loop through the returned columns. Set nStr to the number of bytes of
124640     ** space required to store a copy of each column name, including the
124641     ** nul-terminator byte.  */
124642     nCol = sqlite3_column_count(pStmt);
124643     for(i=0; i<nCol; i++){
124644       const char *zCol = sqlite3_column_name(pStmt, i);
124645       nStr += (int)strlen(zCol) + 1;
124646     }
124647 
124648     /* Allocate and populate the array to return. */
124649     azCol = (const char **)sqlite3_malloc(sizeof(char *) * nCol + nStr);
124650     if( azCol==0 ){
124651       rc = SQLITE_NOMEM;
124652     }else{
124653       char *p = (char *)&azCol[nCol];
124654       for(i=0; i<nCol; i++){
124655         const char *zCol = sqlite3_column_name(pStmt, i);
124656         int n = (int)strlen(zCol)+1;
124657         memcpy(p, zCol, n);
124658         azCol[i] = p;
124659         p += n;
124660       }
124661     }
124662     sqlite3_finalize(pStmt);
124663 
124664     /* Set the output variables. */
124665     *pnCol = nCol;
124666     *pnStr = nStr;
124667     *pazCol = azCol;
124668   }
124669 
124670   return rc;
124671 }
124672 
124673 /*
124674 ** This function is the implementation of both the xConnect and xCreate
124675 ** methods of the FTS3 virtual table.
124676 **
124677 ** The argv[] array contains the following:
124678 **
124679 **   argv[0]   -> module name  ("fts3" or "fts4")
124680 **   argv[1]   -> database name
124681 **   argv[2]   -> table name
124682 **   argv[...] -> "column name" and other module argument fields.
124683 */
124684 static int fts3InitVtab(
124685   int isCreate,                   /* True for xCreate, false for xConnect */
124686   sqlite3 *db,                    /* The SQLite database connection */
124687   void *pAux,                     /* Hash table containing tokenizers */
124688   int argc,                       /* Number of elements in argv array */
124689   const char * const *argv,       /* xCreate/xConnect argument array */
124690   sqlite3_vtab **ppVTab,          /* Write the resulting vtab structure here */
124691   char **pzErr                    /* Write any error message here */
124692 ){
124693   Fts3Hash *pHash = (Fts3Hash *)pAux;
124694   Fts3Table *p = 0;               /* Pointer to allocated vtab */
124695   int rc = SQLITE_OK;             /* Return code */
124696   int i;                          /* Iterator variable */
124697   int nByte;                      /* Size of allocation used for *p */
124698   int iCol;                       /* Column index */
124699   int nString = 0;                /* Bytes required to hold all column names */
124700   int nCol = 0;                   /* Number of columns in the FTS table */
124701   char *zCsr;                     /* Space for holding column names */
124702   int nDb;                        /* Bytes required to hold database name */
124703   int nName;                      /* Bytes required to hold table name */
124704   int isFts4 = (argv[0][3]=='4'); /* True for FTS4, false for FTS3 */
124705   const char **aCol;              /* Array of column names */
124706   sqlite3_tokenizer *pTokenizer = 0;        /* Tokenizer for this table */
124707 
124708   int nIndex;                     /* Size of aIndex[] array */
124709   struct Fts3Index *aIndex = 0;   /* Array of indexes for this table */
124710 
124711   /* The results of parsing supported FTS4 key=value options: */
124712   int bNoDocsize = 0;             /* True to omit %_docsize table */
124713   int bDescIdx = 0;               /* True to store descending indexes */
124714   char *zPrefix = 0;              /* Prefix parameter value (or NULL) */
124715   char *zCompress = 0;            /* compress=? parameter (or NULL) */
124716   char *zUncompress = 0;          /* uncompress=? parameter (or NULL) */
124717   char *zContent = 0;             /* content=? parameter (or NULL) */
124718   char *zLanguageid = 0;          /* languageid=? parameter (or NULL) */
124719   char **azNotindexed = 0;        /* The set of notindexed= columns */
124720   int nNotindexed = 0;            /* Size of azNotindexed[] array */
124721 
124722   assert( strlen(argv[0])==4 );
124723   assert( (sqlite3_strnicmp(argv[0], "fts4", 4)==0 && isFts4)
124724        || (sqlite3_strnicmp(argv[0], "fts3", 4)==0 && !isFts4)
124725   );
124726 
124727   nDb = (int)strlen(argv[1]) + 1;
124728   nName = (int)strlen(argv[2]) + 1;
124729 
124730   nByte = sizeof(const char *) * (argc-2);
124731   aCol = (const char **)sqlite3_malloc(nByte);
124732   if( aCol ){
124733     memset((void*)aCol, 0, nByte);
124734     azNotindexed = (char **)sqlite3_malloc(nByte);
124735   }
124736   if( azNotindexed ){
124737     memset(azNotindexed, 0, nByte);
124738   }
124739   if( !aCol || !azNotindexed ){
124740     rc = SQLITE_NOMEM;
124741     goto fts3_init_out;
124742   }
124743 
124744   /* Loop through all of the arguments passed by the user to the FTS3/4
124745   ** module (i.e. all the column names and special arguments). This loop
124746   ** does the following:
124747   **
124748   **   + Figures out the number of columns the FTSX table will have, and
124749   **     the number of bytes of space that must be allocated to store copies
124750   **     of the column names.
124751   **
124752   **   + If there is a tokenizer specification included in the arguments,
124753   **     initializes the tokenizer pTokenizer.
124754   */
124755   for(i=3; rc==SQLITE_OK && i<argc; i++){
124756     char const *z = argv[i];
124757     int nKey;
124758     char *zVal;
124759 
124760     /* Check if this is a tokenizer specification */
124761     if( !pTokenizer 
124762      && strlen(z)>8
124763      && 0==sqlite3_strnicmp(z, "tokenize", 8) 
124764      && 0==sqlite3Fts3IsIdChar(z[8])
124765     ){
124766       rc = sqlite3Fts3InitTokenizer(pHash, &z[9], &pTokenizer, pzErr);
124767     }
124768 
124769     /* Check if it is an FTS4 special argument. */
124770     else if( isFts4 && fts3IsSpecialColumn(z, &nKey, &zVal) ){
124771       struct Fts4Option {
124772         const char *zOpt;
124773         int nOpt;
124774       } aFts4Opt[] = {
124775         { "matchinfo",   9 },     /* 0 -> MATCHINFO */
124776         { "prefix",      6 },     /* 1 -> PREFIX */
124777         { "compress",    8 },     /* 2 -> COMPRESS */
124778         { "uncompress", 10 },     /* 3 -> UNCOMPRESS */
124779         { "order",       5 },     /* 4 -> ORDER */
124780         { "content",     7 },     /* 5 -> CONTENT */
124781         { "languageid", 10 },     /* 6 -> LANGUAGEID */
124782         { "notindexed", 10 }      /* 7 -> NOTINDEXED */
124783       };
124784 
124785       int iOpt;
124786       if( !zVal ){
124787         rc = SQLITE_NOMEM;
124788       }else{
124789         for(iOpt=0; iOpt<SizeofArray(aFts4Opt); iOpt++){
124790           struct Fts4Option *pOp = &aFts4Opt[iOpt];
124791           if( nKey==pOp->nOpt && !sqlite3_strnicmp(z, pOp->zOpt, pOp->nOpt) ){
124792             break;
124793           }
124794         }
124795         if( iOpt==SizeofArray(aFts4Opt) ){
124796           *pzErr = sqlite3_mprintf("unrecognized parameter: %s", z);
124797           rc = SQLITE_ERROR;
124798         }else{
124799           switch( iOpt ){
124800             case 0:               /* MATCHINFO */
124801               if( strlen(zVal)!=4 || sqlite3_strnicmp(zVal, "fts3", 4) ){
124802                 *pzErr = sqlite3_mprintf("unrecognized matchinfo: %s", zVal);
124803                 rc = SQLITE_ERROR;
124804               }
124805               bNoDocsize = 1;
124806               break;
124807 
124808             case 1:               /* PREFIX */
124809               sqlite3_free(zPrefix);
124810               zPrefix = zVal;
124811               zVal = 0;
124812               break;
124813 
124814             case 2:               /* COMPRESS */
124815               sqlite3_free(zCompress);
124816               zCompress = zVal;
124817               zVal = 0;
124818               break;
124819 
124820             case 3:               /* UNCOMPRESS */
124821               sqlite3_free(zUncompress);
124822               zUncompress = zVal;
124823               zVal = 0;
124824               break;
124825 
124826             case 4:               /* ORDER */
124827               if( (strlen(zVal)!=3 || sqlite3_strnicmp(zVal, "asc", 3)) 
124828                && (strlen(zVal)!=4 || sqlite3_strnicmp(zVal, "desc", 4)) 
124829               ){
124830                 *pzErr = sqlite3_mprintf("unrecognized order: %s", zVal);
124831                 rc = SQLITE_ERROR;
124832               }
124833               bDescIdx = (zVal[0]=='d' || zVal[0]=='D');
124834               break;
124835 
124836             case 5:              /* CONTENT */
124837               sqlite3_free(zContent);
124838               zContent = zVal;
124839               zVal = 0;
124840               break;
124841 
124842             case 6:              /* LANGUAGEID */
124843               assert( iOpt==6 );
124844               sqlite3_free(zLanguageid);
124845               zLanguageid = zVal;
124846               zVal = 0;
124847               break;
124848 
124849             case 7:              /* NOTINDEXED */
124850               azNotindexed[nNotindexed++] = zVal;
124851               zVal = 0;
124852               break;
124853           }
124854         }
124855         sqlite3_free(zVal);
124856       }
124857     }
124858 
124859     /* Otherwise, the argument is a column name. */
124860     else {
124861       nString += (int)(strlen(z) + 1);
124862       aCol[nCol++] = z;
124863     }
124864   }
124865 
124866   /* If a content=xxx option was specified, the following:
124867   **
124868   **   1. Ignore any compress= and uncompress= options.
124869   **
124870   **   2. If no column names were specified as part of the CREATE VIRTUAL
124871   **      TABLE statement, use all columns from the content table.
124872   */
124873   if( rc==SQLITE_OK && zContent ){
124874     sqlite3_free(zCompress); 
124875     sqlite3_free(zUncompress); 
124876     zCompress = 0;
124877     zUncompress = 0;
124878     if( nCol==0 ){
124879       sqlite3_free((void*)aCol); 
124880       aCol = 0;
124881       rc = fts3ContentColumns(db, argv[1], zContent, &aCol, &nCol, &nString);
124882 
124883       /* If a languageid= option was specified, remove the language id
124884       ** column from the aCol[] array. */ 
124885       if( rc==SQLITE_OK && zLanguageid ){
124886         int j;
124887         for(j=0; j<nCol; j++){
124888           if( sqlite3_stricmp(zLanguageid, aCol[j])==0 ){
124889             int k;
124890             for(k=j; k<nCol; k++) aCol[k] = aCol[k+1];
124891             nCol--;
124892             break;
124893           }
124894         }
124895       }
124896     }
124897   }
124898   if( rc!=SQLITE_OK ) goto fts3_init_out;
124899 
124900   if( nCol==0 ){
124901     assert( nString==0 );
124902     aCol[0] = "content";
124903     nString = 8;
124904     nCol = 1;
124905   }
124906 
124907   if( pTokenizer==0 ){
124908     rc = sqlite3Fts3InitTokenizer(pHash, "simple", &pTokenizer, pzErr);
124909     if( rc!=SQLITE_OK ) goto fts3_init_out;
124910   }
124911   assert( pTokenizer );
124912 
124913   rc = fts3PrefixParameter(zPrefix, &nIndex, &aIndex);
124914   if( rc==SQLITE_ERROR ){
124915     assert( zPrefix );
124916     *pzErr = sqlite3_mprintf("error parsing prefix parameter: %s", zPrefix);
124917   }
124918   if( rc!=SQLITE_OK ) goto fts3_init_out;
124919 
124920   /* Allocate and populate the Fts3Table structure. */
124921   nByte = sizeof(Fts3Table) +                  /* Fts3Table */
124922           nCol * sizeof(char *) +              /* azColumn */
124923           nIndex * sizeof(struct Fts3Index) +  /* aIndex */
124924           nCol * sizeof(u8) +                  /* abNotindexed */
124925           nName +                              /* zName */
124926           nDb +                                /* zDb */
124927           nString;                             /* Space for azColumn strings */
124928   p = (Fts3Table*)sqlite3_malloc(nByte);
124929   if( p==0 ){
124930     rc = SQLITE_NOMEM;
124931     goto fts3_init_out;
124932   }
124933   memset(p, 0, nByte);
124934   p->db = db;
124935   p->nColumn = nCol;
124936   p->nPendingData = 0;
124937   p->azColumn = (char **)&p[1];
124938   p->pTokenizer = pTokenizer;
124939   p->nMaxPendingData = FTS3_MAX_PENDING_DATA;
124940   p->bHasDocsize = (isFts4 && bNoDocsize==0);
124941   p->bHasStat = isFts4;
124942   p->bFts4 = isFts4;
124943   p->bDescIdx = bDescIdx;
124944   p->bAutoincrmerge = 0xff;   /* 0xff means setting unknown */
124945   p->zContentTbl = zContent;
124946   p->zLanguageid = zLanguageid;
124947   zContent = 0;
124948   zLanguageid = 0;
124949   TESTONLY( p->inTransaction = -1 );
124950   TESTONLY( p->mxSavepoint = -1 );
124951 
124952   p->aIndex = (struct Fts3Index *)&p->azColumn[nCol];
124953   memcpy(p->aIndex, aIndex, sizeof(struct Fts3Index) * nIndex);
124954   p->nIndex = nIndex;
124955   for(i=0; i<nIndex; i++){
124956     fts3HashInit(&p->aIndex[i].hPending, FTS3_HASH_STRING, 1);
124957   }
124958   p->abNotindexed = (u8 *)&p->aIndex[nIndex];
124959 
124960   /* Fill in the zName and zDb fields of the vtab structure. */
124961   zCsr = (char *)&p->abNotindexed[nCol];
124962   p->zName = zCsr;
124963   memcpy(zCsr, argv[2], nName);
124964   zCsr += nName;
124965   p->zDb = zCsr;
124966   memcpy(zCsr, argv[1], nDb);
124967   zCsr += nDb;
124968 
124969   /* Fill in the azColumn array */
124970   for(iCol=0; iCol<nCol; iCol++){
124971     char *z; 
124972     int n = 0;
124973     z = (char *)sqlite3Fts3NextToken(aCol[iCol], &n);
124974     memcpy(zCsr, z, n);
124975     zCsr[n] = '\0';
124976     sqlite3Fts3Dequote(zCsr);
124977     p->azColumn[iCol] = zCsr;
124978     zCsr += n+1;
124979     assert( zCsr <= &((char *)p)[nByte] );
124980   }
124981 
124982   /* Fill in the abNotindexed array */
124983   for(iCol=0; iCol<nCol; iCol++){
124984     int n = (int)strlen(p->azColumn[iCol]);
124985     for(i=0; i<nNotindexed; i++){
124986       char *zNot = azNotindexed[i];
124987       if( zNot && 0==sqlite3_strnicmp(p->azColumn[iCol], zNot, n) ){
124988         p->abNotindexed[iCol] = 1;
124989         sqlite3_free(zNot);
124990         azNotindexed[i] = 0;
124991       }
124992     }
124993   }
124994   for(i=0; i<nNotindexed; i++){
124995     if( azNotindexed[i] ){
124996       *pzErr = sqlite3_mprintf("no such column: %s", azNotindexed[i]);
124997       rc = SQLITE_ERROR;
124998     }
124999   }
125000 
125001   if( rc==SQLITE_OK && (zCompress==0)!=(zUncompress==0) ){
125002     char const *zMiss = (zCompress==0 ? "compress" : "uncompress");
125003     rc = SQLITE_ERROR;
125004     *pzErr = sqlite3_mprintf("missing %s parameter in fts4 constructor", zMiss);
125005   }
125006   p->zReadExprlist = fts3ReadExprList(p, zUncompress, &rc);
125007   p->zWriteExprlist = fts3WriteExprList(p, zCompress, &rc);
125008   if( rc!=SQLITE_OK ) goto fts3_init_out;
125009 
125010   /* If this is an xCreate call, create the underlying tables in the 
125011   ** database. TODO: For xConnect(), it could verify that said tables exist.
125012   */
125013   if( isCreate ){
125014     rc = fts3CreateTables(p);
125015   }
125016 
125017   /* Check to see if a legacy fts3 table has been "upgraded" by the
125018   ** addition of a %_stat table so that it can use incremental merge.
125019   */
125020   if( !isFts4 && !isCreate ){
125021     int rc2 = SQLITE_OK;
125022     fts3DbExec(&rc2, db, "SELECT 1 FROM %Q.'%q_stat' WHERE id=2",
125023                p->zDb, p->zName);
125024     if( rc2==SQLITE_OK ) p->bHasStat = 1;
125025   }
125026 
125027   /* Figure out the page-size for the database. This is required in order to
125028   ** estimate the cost of loading large doclists from the database.  */
125029   fts3DatabasePageSize(&rc, p);
125030   p->nNodeSize = p->nPgsz-35;
125031 
125032   /* Declare the table schema to SQLite. */
125033   fts3DeclareVtab(&rc, p);
125034 
125035 fts3_init_out:
125036   sqlite3_free(zPrefix);
125037   sqlite3_free(aIndex);
125038   sqlite3_free(zCompress);
125039   sqlite3_free(zUncompress);
125040   sqlite3_free(zContent);
125041   sqlite3_free(zLanguageid);
125042   for(i=0; i<nNotindexed; i++) sqlite3_free(azNotindexed[i]);
125043   sqlite3_free((void *)aCol);
125044   sqlite3_free((void *)azNotindexed);
125045   if( rc!=SQLITE_OK ){
125046     if( p ){
125047       fts3DisconnectMethod((sqlite3_vtab *)p);
125048     }else if( pTokenizer ){
125049       pTokenizer->pModule->xDestroy(pTokenizer);
125050     }
125051   }else{
125052     assert( p->pSegments==0 );
125053     *ppVTab = &p->base;
125054   }
125055   return rc;
125056 }
125057 
125058 /*
125059 ** The xConnect() and xCreate() methods for the virtual table. All the
125060 ** work is done in function fts3InitVtab().
125061 */
125062 static int fts3ConnectMethod(
125063   sqlite3 *db,                    /* Database connection */
125064   void *pAux,                     /* Pointer to tokenizer hash table */
125065   int argc,                       /* Number of elements in argv array */
125066   const char * const *argv,       /* xCreate/xConnect argument array */
125067   sqlite3_vtab **ppVtab,          /* OUT: New sqlite3_vtab object */
125068   char **pzErr                    /* OUT: sqlite3_malloc'd error message */
125069 ){
125070   return fts3InitVtab(0, db, pAux, argc, argv, ppVtab, pzErr);
125071 }
125072 static int fts3CreateMethod(
125073   sqlite3 *db,                    /* Database connection */
125074   void *pAux,                     /* Pointer to tokenizer hash table */
125075   int argc,                       /* Number of elements in argv array */
125076   const char * const *argv,       /* xCreate/xConnect argument array */
125077   sqlite3_vtab **ppVtab,          /* OUT: New sqlite3_vtab object */
125078   char **pzErr                    /* OUT: sqlite3_malloc'd error message */
125079 ){
125080   return fts3InitVtab(1, db, pAux, argc, argv, ppVtab, pzErr);
125081 }
125082 
125083 /* 
125084 ** Implementation of the xBestIndex method for FTS3 tables. There
125085 ** are three possible strategies, in order of preference:
125086 **
125087 **   1. Direct lookup by rowid or docid. 
125088 **   2. Full-text search using a MATCH operator on a non-docid column.
125089 **   3. Linear scan of %_content table.
125090 */
125091 static int fts3BestIndexMethod(sqlite3_vtab *pVTab, sqlite3_index_info *pInfo){
125092   Fts3Table *p = (Fts3Table *)pVTab;
125093   int i;                          /* Iterator variable */
125094   int iCons = -1;                 /* Index of constraint to use */
125095 
125096   int iLangidCons = -1;           /* Index of langid=x constraint, if present */
125097   int iDocidGe = -1;              /* Index of docid>=x constraint, if present */
125098   int iDocidLe = -1;              /* Index of docid<=x constraint, if present */
125099   int iIdx;
125100 
125101   /* By default use a full table scan. This is an expensive option,
125102   ** so search through the constraints to see if a more efficient 
125103   ** strategy is possible.
125104   */
125105   pInfo->idxNum = FTS3_FULLSCAN_SEARCH;
125106   pInfo->estimatedCost = 5000000;
125107   for(i=0; i<pInfo->nConstraint; i++){
125108     int bDocid;                 /* True if this constraint is on docid */
125109     struct sqlite3_index_constraint *pCons = &pInfo->aConstraint[i];
125110     if( pCons->usable==0 ) continue;
125111 
125112     bDocid = (pCons->iColumn<0 || pCons->iColumn==p->nColumn+1);
125113 
125114     /* A direct lookup on the rowid or docid column. Assign a cost of 1.0. */
125115     if( iCons<0 && pCons->op==SQLITE_INDEX_CONSTRAINT_EQ && bDocid ){
125116       pInfo->idxNum = FTS3_DOCID_SEARCH;
125117       pInfo->estimatedCost = 1.0;
125118       iCons = i;
125119     }
125120 
125121     /* A MATCH constraint. Use a full-text search.
125122     **
125123     ** If there is more than one MATCH constraint available, use the first
125124     ** one encountered. If there is both a MATCH constraint and a direct
125125     ** rowid/docid lookup, prefer the MATCH strategy. This is done even 
125126     ** though the rowid/docid lookup is faster than a MATCH query, selecting
125127     ** it would lead to an "unable to use function MATCH in the requested 
125128     ** context" error.
125129     */
125130     if( pCons->op==SQLITE_INDEX_CONSTRAINT_MATCH 
125131      && pCons->iColumn>=0 && pCons->iColumn<=p->nColumn
125132     ){
125133       pInfo->idxNum = FTS3_FULLTEXT_SEARCH + pCons->iColumn;
125134       pInfo->estimatedCost = 2.0;
125135       iCons = i;
125136     }
125137 
125138     /* Equality constraint on the langid column */
125139     if( pCons->op==SQLITE_INDEX_CONSTRAINT_EQ 
125140      && pCons->iColumn==p->nColumn + 2
125141     ){
125142       iLangidCons = i;
125143     }
125144 
125145     if( bDocid ){
125146       switch( pCons->op ){
125147         case SQLITE_INDEX_CONSTRAINT_GE:
125148         case SQLITE_INDEX_CONSTRAINT_GT:
125149           iDocidGe = i;
125150           break;
125151 
125152         case SQLITE_INDEX_CONSTRAINT_LE:
125153         case SQLITE_INDEX_CONSTRAINT_LT:
125154           iDocidLe = i;
125155           break;
125156       }
125157     }
125158   }
125159 
125160   iIdx = 1;
125161   if( iCons>=0 ){
125162     pInfo->aConstraintUsage[iCons].argvIndex = iIdx++;
125163     pInfo->aConstraintUsage[iCons].omit = 1;
125164   } 
125165   if( iLangidCons>=0 ){
125166     pInfo->idxNum |= FTS3_HAVE_LANGID;
125167     pInfo->aConstraintUsage[iLangidCons].argvIndex = iIdx++;
125168   } 
125169   if( iDocidGe>=0 ){
125170     pInfo->idxNum |= FTS3_HAVE_DOCID_GE;
125171     pInfo->aConstraintUsage[iDocidGe].argvIndex = iIdx++;
125172   } 
125173   if( iDocidLe>=0 ){
125174     pInfo->idxNum |= FTS3_HAVE_DOCID_LE;
125175     pInfo->aConstraintUsage[iDocidLe].argvIndex = iIdx++;
125176   } 
125177 
125178   /* Regardless of the strategy selected, FTS can deliver rows in rowid (or
125179   ** docid) order. Both ascending and descending are possible. 
125180   */
125181   if( pInfo->nOrderBy==1 ){
125182     struct sqlite3_index_orderby *pOrder = &pInfo->aOrderBy[0];
125183     if( pOrder->iColumn<0 || pOrder->iColumn==p->nColumn+1 ){
125184       if( pOrder->desc ){
125185         pInfo->idxStr = "DESC";
125186       }else{
125187         pInfo->idxStr = "ASC";
125188       }
125189       pInfo->orderByConsumed = 1;
125190     }
125191   }
125192 
125193   assert( p->pSegments==0 );
125194   return SQLITE_OK;
125195 }
125196 
125197 /*
125198 ** Implementation of xOpen method.
125199 */
125200 static int fts3OpenMethod(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCsr){
125201   sqlite3_vtab_cursor *pCsr;               /* Allocated cursor */
125202 
125203   UNUSED_PARAMETER(pVTab);
125204 
125205   /* Allocate a buffer large enough for an Fts3Cursor structure. If the
125206   ** allocation succeeds, zero it and return SQLITE_OK. Otherwise, 
125207   ** if the allocation fails, return SQLITE_NOMEM.
125208   */
125209   *ppCsr = pCsr = (sqlite3_vtab_cursor *)sqlite3_malloc(sizeof(Fts3Cursor));
125210   if( !pCsr ){
125211     return SQLITE_NOMEM;
125212   }
125213   memset(pCsr, 0, sizeof(Fts3Cursor));
125214   return SQLITE_OK;
125215 }
125216 
125217 /*
125218 ** Close the cursor.  For additional information see the documentation
125219 ** on the xClose method of the virtual table interface.
125220 */
125221 static int fts3CloseMethod(sqlite3_vtab_cursor *pCursor){
125222   Fts3Cursor *pCsr = (Fts3Cursor *)pCursor;
125223   assert( ((Fts3Table *)pCsr->base.pVtab)->pSegments==0 );
125224   sqlite3_finalize(pCsr->pStmt);
125225   sqlite3Fts3ExprFree(pCsr->pExpr);
125226   sqlite3Fts3FreeDeferredTokens(pCsr);
125227   sqlite3_free(pCsr->aDoclist);
125228   sqlite3_free(pCsr->aMatchinfo);
125229   assert( ((Fts3Table *)pCsr->base.pVtab)->pSegments==0 );
125230   sqlite3_free(pCsr);
125231   return SQLITE_OK;
125232 }
125233 
125234 /*
125235 ** If pCsr->pStmt has not been prepared (i.e. if pCsr->pStmt==0), then
125236 ** compose and prepare an SQL statement of the form:
125237 **
125238 **    "SELECT <columns> FROM %_content WHERE rowid = ?"
125239 **
125240 ** (or the equivalent for a content=xxx table) and set pCsr->pStmt to
125241 ** it. If an error occurs, return an SQLite error code.
125242 **
125243 ** Otherwise, set *ppStmt to point to pCsr->pStmt and return SQLITE_OK.
125244 */
125245 static int fts3CursorSeekStmt(Fts3Cursor *pCsr, sqlite3_stmt **ppStmt){
125246   int rc = SQLITE_OK;
125247   if( pCsr->pStmt==0 ){
125248     Fts3Table *p = (Fts3Table *)pCsr->base.pVtab;
125249     char *zSql;
125250     zSql = sqlite3_mprintf("SELECT %s WHERE rowid = ?", p->zReadExprlist);
125251     if( !zSql ) return SQLITE_NOMEM;
125252     rc = sqlite3_prepare_v2(p->db, zSql, -1, &pCsr->pStmt, 0);
125253     sqlite3_free(zSql);
125254   }
125255   *ppStmt = pCsr->pStmt;
125256   return rc;
125257 }
125258 
125259 /*
125260 ** Position the pCsr->pStmt statement so that it is on the row
125261 ** of the %_content table that contains the last match.  Return
125262 ** SQLITE_OK on success.  
125263 */
125264 static int fts3CursorSeek(sqlite3_context *pContext, Fts3Cursor *pCsr){
125265   int rc = SQLITE_OK;
125266   if( pCsr->isRequireSeek ){
125267     sqlite3_stmt *pStmt = 0;
125268 
125269     rc = fts3CursorSeekStmt(pCsr, &pStmt);
125270     if( rc==SQLITE_OK ){
125271       sqlite3_bind_int64(pCsr->pStmt, 1, pCsr->iPrevId);
125272       pCsr->isRequireSeek = 0;
125273       if( SQLITE_ROW==sqlite3_step(pCsr->pStmt) ){
125274         return SQLITE_OK;
125275       }else{
125276         rc = sqlite3_reset(pCsr->pStmt);
125277         if( rc==SQLITE_OK && ((Fts3Table *)pCsr->base.pVtab)->zContentTbl==0 ){
125278           /* If no row was found and no error has occurred, then the %_content
125279           ** table is missing a row that is present in the full-text index.
125280           ** The data structures are corrupt.  */
125281           rc = FTS_CORRUPT_VTAB;
125282           pCsr->isEof = 1;
125283         }
125284       }
125285     }
125286   }
125287 
125288   if( rc!=SQLITE_OK && pContext ){
125289     sqlite3_result_error_code(pContext, rc);
125290   }
125291   return rc;
125292 }
125293 
125294 /*
125295 ** This function is used to process a single interior node when searching
125296 ** a b-tree for a term or term prefix. The node data is passed to this 
125297 ** function via the zNode/nNode parameters. The term to search for is
125298 ** passed in zTerm/nTerm.
125299 **
125300 ** If piFirst is not NULL, then this function sets *piFirst to the blockid
125301 ** of the child node that heads the sub-tree that may contain the term.
125302 **
125303 ** If piLast is not NULL, then *piLast is set to the right-most child node
125304 ** that heads a sub-tree that may contain a term for which zTerm/nTerm is
125305 ** a prefix.
125306 **
125307 ** If an OOM error occurs, SQLITE_NOMEM is returned. Otherwise, SQLITE_OK.
125308 */
125309 static int fts3ScanInteriorNode(
125310   const char *zTerm,              /* Term to select leaves for */
125311   int nTerm,                      /* Size of term zTerm in bytes */
125312   const char *zNode,              /* Buffer containing segment interior node */
125313   int nNode,                      /* Size of buffer at zNode */
125314   sqlite3_int64 *piFirst,         /* OUT: Selected child node */
125315   sqlite3_int64 *piLast           /* OUT: Selected child node */
125316 ){
125317   int rc = SQLITE_OK;             /* Return code */
125318   const char *zCsr = zNode;       /* Cursor to iterate through node */
125319   const char *zEnd = &zCsr[nNode];/* End of interior node buffer */
125320   char *zBuffer = 0;              /* Buffer to load terms into */
125321   int nAlloc = 0;                 /* Size of allocated buffer */
125322   int isFirstTerm = 1;            /* True when processing first term on page */
125323   sqlite3_int64 iChild;           /* Block id of child node to descend to */
125324 
125325   /* Skip over the 'height' varint that occurs at the start of every 
125326   ** interior node. Then load the blockid of the left-child of the b-tree
125327   ** node into variable iChild.  
125328   **
125329   ** Even if the data structure on disk is corrupted, this (reading two
125330   ** varints from the buffer) does not risk an overread. If zNode is a
125331   ** root node, then the buffer comes from a SELECT statement. SQLite does
125332   ** not make this guarantee explicitly, but in practice there are always
125333   ** either more than 20 bytes of allocated space following the nNode bytes of
125334   ** contents, or two zero bytes. Or, if the node is read from the %_segments
125335   ** table, then there are always 20 bytes of zeroed padding following the
125336   ** nNode bytes of content (see sqlite3Fts3ReadBlock() for details).
125337   */
125338   zCsr += sqlite3Fts3GetVarint(zCsr, &iChild);
125339   zCsr += sqlite3Fts3GetVarint(zCsr, &iChild);
125340   if( zCsr>zEnd ){
125341     return FTS_CORRUPT_VTAB;
125342   }
125343   
125344   while( zCsr<zEnd && (piFirst || piLast) ){
125345     int cmp;                      /* memcmp() result */
125346     int nSuffix;                  /* Size of term suffix */
125347     int nPrefix = 0;              /* Size of term prefix */
125348     int nBuffer;                  /* Total term size */
125349   
125350     /* Load the next term on the node into zBuffer. Use realloc() to expand
125351     ** the size of zBuffer if required.  */
125352     if( !isFirstTerm ){
125353       zCsr += fts3GetVarint32(zCsr, &nPrefix);
125354     }
125355     isFirstTerm = 0;
125356     zCsr += fts3GetVarint32(zCsr, &nSuffix);
125357     
125358     if( nPrefix<0 || nSuffix<0 || &zCsr[nSuffix]>zEnd ){
125359       rc = FTS_CORRUPT_VTAB;
125360       goto finish_scan;
125361     }
125362     if( nPrefix+nSuffix>nAlloc ){
125363       char *zNew;
125364       nAlloc = (nPrefix+nSuffix) * 2;
125365       zNew = (char *)sqlite3_realloc(zBuffer, nAlloc);
125366       if( !zNew ){
125367         rc = SQLITE_NOMEM;
125368         goto finish_scan;
125369       }
125370       zBuffer = zNew;
125371     }
125372     assert( zBuffer );
125373     memcpy(&zBuffer[nPrefix], zCsr, nSuffix);
125374     nBuffer = nPrefix + nSuffix;
125375     zCsr += nSuffix;
125376 
125377     /* Compare the term we are searching for with the term just loaded from
125378     ** the interior node. If the specified term is greater than or equal
125379     ** to the term from the interior node, then all terms on the sub-tree 
125380     ** headed by node iChild are smaller than zTerm. No need to search 
125381     ** iChild.
125382     **
125383     ** If the interior node term is larger than the specified term, then
125384     ** the tree headed by iChild may contain the specified term.
125385     */
125386     cmp = memcmp(zTerm, zBuffer, (nBuffer>nTerm ? nTerm : nBuffer));
125387     if( piFirst && (cmp<0 || (cmp==0 && nBuffer>nTerm)) ){
125388       *piFirst = iChild;
125389       piFirst = 0;
125390     }
125391 
125392     if( piLast && cmp<0 ){
125393       *piLast = iChild;
125394       piLast = 0;
125395     }
125396 
125397     iChild++;
125398   };
125399 
125400   if( piFirst ) *piFirst = iChild;
125401   if( piLast ) *piLast = iChild;
125402 
125403  finish_scan:
125404   sqlite3_free(zBuffer);
125405   return rc;
125406 }
125407 
125408 
125409 /*
125410 ** The buffer pointed to by argument zNode (size nNode bytes) contains an
125411 ** interior node of a b-tree segment. The zTerm buffer (size nTerm bytes)
125412 ** contains a term. This function searches the sub-tree headed by the zNode
125413 ** node for the range of leaf nodes that may contain the specified term
125414 ** or terms for which the specified term is a prefix.
125415 **
125416 ** If piLeaf is not NULL, then *piLeaf is set to the blockid of the 
125417 ** left-most leaf node in the tree that may contain the specified term.
125418 ** If piLeaf2 is not NULL, then *piLeaf2 is set to the blockid of the
125419 ** right-most leaf node that may contain a term for which the specified
125420 ** term is a prefix.
125421 **
125422 ** It is possible that the range of returned leaf nodes does not contain 
125423 ** the specified term or any terms for which it is a prefix. However, if the 
125424 ** segment does contain any such terms, they are stored within the identified
125425 ** range. Because this function only inspects interior segment nodes (and
125426 ** never loads leaf nodes into memory), it is not possible to be sure.
125427 **
125428 ** If an error occurs, an error code other than SQLITE_OK is returned.
125429 */ 
125430 static int fts3SelectLeaf(
125431   Fts3Table *p,                   /* Virtual table handle */
125432   const char *zTerm,              /* Term to select leaves for */
125433   int nTerm,                      /* Size of term zTerm in bytes */
125434   const char *zNode,              /* Buffer containing segment interior node */
125435   int nNode,                      /* Size of buffer at zNode */
125436   sqlite3_int64 *piLeaf,          /* Selected leaf node */
125437   sqlite3_int64 *piLeaf2          /* Selected leaf node */
125438 ){
125439   int rc;                         /* Return code */
125440   int iHeight;                    /* Height of this node in tree */
125441 
125442   assert( piLeaf || piLeaf2 );
125443 
125444   fts3GetVarint32(zNode, &iHeight);
125445   rc = fts3ScanInteriorNode(zTerm, nTerm, zNode, nNode, piLeaf, piLeaf2);
125446   assert( !piLeaf2 || !piLeaf || rc!=SQLITE_OK || (*piLeaf<=*piLeaf2) );
125447 
125448   if( rc==SQLITE_OK && iHeight>1 ){
125449     char *zBlob = 0;              /* Blob read from %_segments table */
125450     int nBlob;                    /* Size of zBlob in bytes */
125451 
125452     if( piLeaf && piLeaf2 && (*piLeaf!=*piLeaf2) ){
125453       rc = sqlite3Fts3ReadBlock(p, *piLeaf, &zBlob, &nBlob, 0);
125454       if( rc==SQLITE_OK ){
125455         rc = fts3SelectLeaf(p, zTerm, nTerm, zBlob, nBlob, piLeaf, 0);
125456       }
125457       sqlite3_free(zBlob);
125458       piLeaf = 0;
125459       zBlob = 0;
125460     }
125461 
125462     if( rc==SQLITE_OK ){
125463       rc = sqlite3Fts3ReadBlock(p, piLeaf?*piLeaf:*piLeaf2, &zBlob, &nBlob, 0);
125464     }
125465     if( rc==SQLITE_OK ){
125466       rc = fts3SelectLeaf(p, zTerm, nTerm, zBlob, nBlob, piLeaf, piLeaf2);
125467     }
125468     sqlite3_free(zBlob);
125469   }
125470 
125471   return rc;
125472 }
125473 
125474 /*
125475 ** This function is used to create delta-encoded serialized lists of FTS3 
125476 ** varints. Each call to this function appends a single varint to a list.
125477 */
125478 static void fts3PutDeltaVarint(
125479   char **pp,                      /* IN/OUT: Output pointer */
125480   sqlite3_int64 *piPrev,          /* IN/OUT: Previous value written to list */
125481   sqlite3_int64 iVal              /* Write this value to the list */
125482 ){
125483   assert( iVal-*piPrev > 0 || (*piPrev==0 && iVal==0) );
125484   *pp += sqlite3Fts3PutVarint(*pp, iVal-*piPrev);
125485   *piPrev = iVal;
125486 }
125487 
125488 /*
125489 ** When this function is called, *ppPoslist is assumed to point to the 
125490 ** start of a position-list. After it returns, *ppPoslist points to the
125491 ** first byte after the position-list.
125492 **
125493 ** A position list is list of positions (delta encoded) and columns for 
125494 ** a single document record of a doclist.  So, in other words, this
125495 ** routine advances *ppPoslist so that it points to the next docid in
125496 ** the doclist, or to the first byte past the end of the doclist.
125497 **
125498 ** If pp is not NULL, then the contents of the position list are copied
125499 ** to *pp. *pp is set to point to the first byte past the last byte copied
125500 ** before this function returns.
125501 */
125502 static void fts3PoslistCopy(char **pp, char **ppPoslist){
125503   char *pEnd = *ppPoslist;
125504   char c = 0;
125505 
125506   /* The end of a position list is marked by a zero encoded as an FTS3 
125507   ** varint. A single POS_END (0) byte. Except, if the 0 byte is preceded by
125508   ** a byte with the 0x80 bit set, then it is not a varint 0, but the tail
125509   ** of some other, multi-byte, value.
125510   **
125511   ** The following while-loop moves pEnd to point to the first byte that is not 
125512   ** immediately preceded by a byte with the 0x80 bit set. Then increments
125513   ** pEnd once more so that it points to the byte immediately following the
125514   ** last byte in the position-list.
125515   */
125516   while( *pEnd | c ){
125517     c = *pEnd++ & 0x80;
125518     testcase( c!=0 && (*pEnd)==0 );
125519   }
125520   pEnd++;  /* Advance past the POS_END terminator byte */
125521 
125522   if( pp ){
125523     int n = (int)(pEnd - *ppPoslist);
125524     char *p = *pp;
125525     memcpy(p, *ppPoslist, n);
125526     p += n;
125527     *pp = p;
125528   }
125529   *ppPoslist = pEnd;
125530 }
125531 
125532 /*
125533 ** When this function is called, *ppPoslist is assumed to point to the 
125534 ** start of a column-list. After it returns, *ppPoslist points to the
125535 ** to the terminator (POS_COLUMN or POS_END) byte of the column-list.
125536 **
125537 ** A column-list is list of delta-encoded positions for a single column
125538 ** within a single document within a doclist.
125539 **
125540 ** The column-list is terminated either by a POS_COLUMN varint (1) or
125541 ** a POS_END varint (0).  This routine leaves *ppPoslist pointing to
125542 ** the POS_COLUMN or POS_END that terminates the column-list.
125543 **
125544 ** If pp is not NULL, then the contents of the column-list are copied
125545 ** to *pp. *pp is set to point to the first byte past the last byte copied
125546 ** before this function returns.  The POS_COLUMN or POS_END terminator
125547 ** is not copied into *pp.
125548 */
125549 static void fts3ColumnlistCopy(char **pp, char **ppPoslist){
125550   char *pEnd = *ppPoslist;
125551   char c = 0;
125552 
125553   /* A column-list is terminated by either a 0x01 or 0x00 byte that is
125554   ** not part of a multi-byte varint.
125555   */
125556   while( 0xFE & (*pEnd | c) ){
125557     c = *pEnd++ & 0x80;
125558     testcase( c!=0 && ((*pEnd)&0xfe)==0 );
125559   }
125560   if( pp ){
125561     int n = (int)(pEnd - *ppPoslist);
125562     char *p = *pp;
125563     memcpy(p, *ppPoslist, n);
125564     p += n;
125565     *pp = p;
125566   }
125567   *ppPoslist = pEnd;
125568 }
125569 
125570 /*
125571 ** Value used to signify the end of an position-list. This is safe because
125572 ** it is not possible to have a document with 2^31 terms.
125573 */
125574 #define POSITION_LIST_END 0x7fffffff
125575 
125576 /*
125577 ** This function is used to help parse position-lists. When this function is
125578 ** called, *pp may point to the start of the next varint in the position-list
125579 ** being parsed, or it may point to 1 byte past the end of the position-list
125580 ** (in which case **pp will be a terminator bytes POS_END (0) or
125581 ** (1)).
125582 **
125583 ** If *pp points past the end of the current position-list, set *pi to 
125584 ** POSITION_LIST_END and return. Otherwise, read the next varint from *pp,
125585 ** increment the current value of *pi by the value read, and set *pp to
125586 ** point to the next value before returning.
125587 **
125588 ** Before calling this routine *pi must be initialized to the value of
125589 ** the previous position, or zero if we are reading the first position
125590 ** in the position-list.  Because positions are delta-encoded, the value
125591 ** of the previous position is needed in order to compute the value of
125592 ** the next position.
125593 */
125594 static void fts3ReadNextPos(
125595   char **pp,                    /* IN/OUT: Pointer into position-list buffer */
125596   sqlite3_int64 *pi             /* IN/OUT: Value read from position-list */
125597 ){
125598   if( (**pp)&0xFE ){
125599     fts3GetDeltaVarint(pp, pi);
125600     *pi -= 2;
125601   }else{
125602     *pi = POSITION_LIST_END;
125603   }
125604 }
125605 
125606 /*
125607 ** If parameter iCol is not 0, write an POS_COLUMN (1) byte followed by
125608 ** the value of iCol encoded as a varint to *pp.   This will start a new
125609 ** column list.
125610 **
125611 ** Set *pp to point to the byte just after the last byte written before 
125612 ** returning (do not modify it if iCol==0). Return the total number of bytes
125613 ** written (0 if iCol==0).
125614 */
125615 static int fts3PutColNumber(char **pp, int iCol){
125616   int n = 0;                      /* Number of bytes written */
125617   if( iCol ){
125618     char *p = *pp;                /* Output pointer */
125619     n = 1 + sqlite3Fts3PutVarint(&p[1], iCol);
125620     *p = 0x01;
125621     *pp = &p[n];
125622   }
125623   return n;
125624 }
125625 
125626 /*
125627 ** Compute the union of two position lists.  The output written
125628 ** into *pp contains all positions of both *pp1 and *pp2 in sorted
125629 ** order and with any duplicates removed.  All pointers are
125630 ** updated appropriately.   The caller is responsible for insuring
125631 ** that there is enough space in *pp to hold the complete output.
125632 */
125633 static void fts3PoslistMerge(
125634   char **pp,                      /* Output buffer */
125635   char **pp1,                     /* Left input list */
125636   char **pp2                      /* Right input list */
125637 ){
125638   char *p = *pp;
125639   char *p1 = *pp1;
125640   char *p2 = *pp2;
125641 
125642   while( *p1 || *p2 ){
125643     int iCol1;         /* The current column index in pp1 */
125644     int iCol2;         /* The current column index in pp2 */
125645 
125646     if( *p1==POS_COLUMN ) fts3GetVarint32(&p1[1], &iCol1);
125647     else if( *p1==POS_END ) iCol1 = POSITION_LIST_END;
125648     else iCol1 = 0;
125649 
125650     if( *p2==POS_COLUMN ) fts3GetVarint32(&p2[1], &iCol2);
125651     else if( *p2==POS_END ) iCol2 = POSITION_LIST_END;
125652     else iCol2 = 0;
125653 
125654     if( iCol1==iCol2 ){
125655       sqlite3_int64 i1 = 0;       /* Last position from pp1 */
125656       sqlite3_int64 i2 = 0;       /* Last position from pp2 */
125657       sqlite3_int64 iPrev = 0;
125658       int n = fts3PutColNumber(&p, iCol1);
125659       p1 += n;
125660       p2 += n;
125661 
125662       /* At this point, both p1 and p2 point to the start of column-lists
125663       ** for the same column (the column with index iCol1 and iCol2).
125664       ** A column-list is a list of non-negative delta-encoded varints, each 
125665       ** incremented by 2 before being stored. Each list is terminated by a
125666       ** POS_END (0) or POS_COLUMN (1). The following block merges the two lists
125667       ** and writes the results to buffer p. p is left pointing to the byte
125668       ** after the list written. No terminator (POS_END or POS_COLUMN) is
125669       ** written to the output.
125670       */
125671       fts3GetDeltaVarint(&p1, &i1);
125672       fts3GetDeltaVarint(&p2, &i2);
125673       do {
125674         fts3PutDeltaVarint(&p, &iPrev, (i1<i2) ? i1 : i2); 
125675         iPrev -= 2;
125676         if( i1==i2 ){
125677           fts3ReadNextPos(&p1, &i1);
125678           fts3ReadNextPos(&p2, &i2);
125679         }else if( i1<i2 ){
125680           fts3ReadNextPos(&p1, &i1);
125681         }else{
125682           fts3ReadNextPos(&p2, &i2);
125683         }
125684       }while( i1!=POSITION_LIST_END || i2!=POSITION_LIST_END );
125685     }else if( iCol1<iCol2 ){
125686       p1 += fts3PutColNumber(&p, iCol1);
125687       fts3ColumnlistCopy(&p, &p1);
125688     }else{
125689       p2 += fts3PutColNumber(&p, iCol2);
125690       fts3ColumnlistCopy(&p, &p2);
125691     }
125692   }
125693 
125694   *p++ = POS_END;
125695   *pp = p;
125696   *pp1 = p1 + 1;
125697   *pp2 = p2 + 1;
125698 }
125699 
125700 /*
125701 ** This function is used to merge two position lists into one. When it is
125702 ** called, *pp1 and *pp2 must both point to position lists. A position-list is
125703 ** the part of a doclist that follows each document id. For example, if a row
125704 ** contains:
125705 **
125706 **     'a b c'|'x y z'|'a b b a'
125707 **
125708 ** Then the position list for this row for token 'b' would consist of:
125709 **
125710 **     0x02 0x01 0x02 0x03 0x03 0x00
125711 **
125712 ** When this function returns, both *pp1 and *pp2 are left pointing to the
125713 ** byte following the 0x00 terminator of their respective position lists.
125714 **
125715 ** If isSaveLeft is 0, an entry is added to the output position list for 
125716 ** each position in *pp2 for which there exists one or more positions in
125717 ** *pp1 so that (pos(*pp2)>pos(*pp1) && pos(*pp2)-pos(*pp1)<=nToken). i.e.
125718 ** when the *pp1 token appears before the *pp2 token, but not more than nToken
125719 ** slots before it.
125720 **
125721 ** e.g. nToken==1 searches for adjacent positions.
125722 */
125723 static int fts3PoslistPhraseMerge(
125724   char **pp,                      /* IN/OUT: Preallocated output buffer */
125725   int nToken,                     /* Maximum difference in token positions */
125726   int isSaveLeft,                 /* Save the left position */
125727   int isExact,                    /* If *pp1 is exactly nTokens before *pp2 */
125728   char **pp1,                     /* IN/OUT: Left input list */
125729   char **pp2                      /* IN/OUT: Right input list */
125730 ){
125731   char *p = *pp;
125732   char *p1 = *pp1;
125733   char *p2 = *pp2;
125734   int iCol1 = 0;
125735   int iCol2 = 0;
125736 
125737   /* Never set both isSaveLeft and isExact for the same invocation. */
125738   assert( isSaveLeft==0 || isExact==0 );
125739 
125740   assert( p!=0 && *p1!=0 && *p2!=0 );
125741   if( *p1==POS_COLUMN ){ 
125742     p1++;
125743     p1 += fts3GetVarint32(p1, &iCol1);
125744   }
125745   if( *p2==POS_COLUMN ){ 
125746     p2++;
125747     p2 += fts3GetVarint32(p2, &iCol2);
125748   }
125749 
125750   while( 1 ){
125751     if( iCol1==iCol2 ){
125752       char *pSave = p;
125753       sqlite3_int64 iPrev = 0;
125754       sqlite3_int64 iPos1 = 0;
125755       sqlite3_int64 iPos2 = 0;
125756 
125757       if( iCol1 ){
125758         *p++ = POS_COLUMN;
125759         p += sqlite3Fts3PutVarint(p, iCol1);
125760       }
125761 
125762       assert( *p1!=POS_END && *p1!=POS_COLUMN );
125763       assert( *p2!=POS_END && *p2!=POS_COLUMN );
125764       fts3GetDeltaVarint(&p1, &iPos1); iPos1 -= 2;
125765       fts3GetDeltaVarint(&p2, &iPos2); iPos2 -= 2;
125766 
125767       while( 1 ){
125768         if( iPos2==iPos1+nToken 
125769          || (isExact==0 && iPos2>iPos1 && iPos2<=iPos1+nToken) 
125770         ){
125771           sqlite3_int64 iSave;
125772           iSave = isSaveLeft ? iPos1 : iPos2;
125773           fts3PutDeltaVarint(&p, &iPrev, iSave+2); iPrev -= 2;
125774           pSave = 0;
125775           assert( p );
125776         }
125777         if( (!isSaveLeft && iPos2<=(iPos1+nToken)) || iPos2<=iPos1 ){
125778           if( (*p2&0xFE)==0 ) break;
125779           fts3GetDeltaVarint(&p2, &iPos2); iPos2 -= 2;
125780         }else{
125781           if( (*p1&0xFE)==0 ) break;
125782           fts3GetDeltaVarint(&p1, &iPos1); iPos1 -= 2;
125783         }
125784       }
125785 
125786       if( pSave ){
125787         assert( pp && p );
125788         p = pSave;
125789       }
125790 
125791       fts3ColumnlistCopy(0, &p1);
125792       fts3ColumnlistCopy(0, &p2);
125793       assert( (*p1&0xFE)==0 && (*p2&0xFE)==0 );
125794       if( 0==*p1 || 0==*p2 ) break;
125795 
125796       p1++;
125797       p1 += fts3GetVarint32(p1, &iCol1);
125798       p2++;
125799       p2 += fts3GetVarint32(p2, &iCol2);
125800     }
125801 
125802     /* Advance pointer p1 or p2 (whichever corresponds to the smaller of
125803     ** iCol1 and iCol2) so that it points to either the 0x00 that marks the
125804     ** end of the position list, or the 0x01 that precedes the next 
125805     ** column-number in the position list. 
125806     */
125807     else if( iCol1<iCol2 ){
125808       fts3ColumnlistCopy(0, &p1);
125809       if( 0==*p1 ) break;
125810       p1++;
125811       p1 += fts3GetVarint32(p1, &iCol1);
125812     }else{
125813       fts3ColumnlistCopy(0, &p2);
125814       if( 0==*p2 ) break;
125815       p2++;
125816       p2 += fts3GetVarint32(p2, &iCol2);
125817     }
125818   }
125819 
125820   fts3PoslistCopy(0, &p2);
125821   fts3PoslistCopy(0, &p1);
125822   *pp1 = p1;
125823   *pp2 = p2;
125824   if( *pp==p ){
125825     return 0;
125826   }
125827   *p++ = 0x00;
125828   *pp = p;
125829   return 1;
125830 }
125831 
125832 /*
125833 ** Merge two position-lists as required by the NEAR operator. The argument
125834 ** position lists correspond to the left and right phrases of an expression 
125835 ** like:
125836 **
125837 **     "phrase 1" NEAR "phrase number 2"
125838 **
125839 ** Position list *pp1 corresponds to the left-hand side of the NEAR 
125840 ** expression and *pp2 to the right. As usual, the indexes in the position 
125841 ** lists are the offsets of the last token in each phrase (tokens "1" and "2" 
125842 ** in the example above).
125843 **
125844 ** The output position list - written to *pp - is a copy of *pp2 with those
125845 ** entries that are not sufficiently NEAR entries in *pp1 removed.
125846 */
125847 static int fts3PoslistNearMerge(
125848   char **pp,                      /* Output buffer */
125849   char *aTmp,                     /* Temporary buffer space */
125850   int nRight,                     /* Maximum difference in token positions */
125851   int nLeft,                      /* Maximum difference in token positions */
125852   char **pp1,                     /* IN/OUT: Left input list */
125853   char **pp2                      /* IN/OUT: Right input list */
125854 ){
125855   char *p1 = *pp1;
125856   char *p2 = *pp2;
125857 
125858   char *pTmp1 = aTmp;
125859   char *pTmp2;
125860   char *aTmp2;
125861   int res = 1;
125862 
125863   fts3PoslistPhraseMerge(&pTmp1, nRight, 0, 0, pp1, pp2);
125864   aTmp2 = pTmp2 = pTmp1;
125865   *pp1 = p1;
125866   *pp2 = p2;
125867   fts3PoslistPhraseMerge(&pTmp2, nLeft, 1, 0, pp2, pp1);
125868   if( pTmp1!=aTmp && pTmp2!=aTmp2 ){
125869     fts3PoslistMerge(pp, &aTmp, &aTmp2);
125870   }else if( pTmp1!=aTmp ){
125871     fts3PoslistCopy(pp, &aTmp);
125872   }else if( pTmp2!=aTmp2 ){
125873     fts3PoslistCopy(pp, &aTmp2);
125874   }else{
125875     res = 0;
125876   }
125877 
125878   return res;
125879 }
125880 
125881 /* 
125882 ** An instance of this function is used to merge together the (potentially
125883 ** large number of) doclists for each term that matches a prefix query.
125884 ** See function fts3TermSelectMerge() for details.
125885 */
125886 typedef struct TermSelect TermSelect;
125887 struct TermSelect {
125888   char *aaOutput[16];             /* Malloc'd output buffers */
125889   int anOutput[16];               /* Size each output buffer in bytes */
125890 };
125891 
125892 /*
125893 ** This function is used to read a single varint from a buffer. Parameter
125894 ** pEnd points 1 byte past the end of the buffer. When this function is
125895 ** called, if *pp points to pEnd or greater, then the end of the buffer
125896 ** has been reached. In this case *pp is set to 0 and the function returns.
125897 **
125898 ** If *pp does not point to or past pEnd, then a single varint is read
125899 ** from *pp. *pp is then set to point 1 byte past the end of the read varint.
125900 **
125901 ** If bDescIdx is false, the value read is added to *pVal before returning.
125902 ** If it is true, the value read is subtracted from *pVal before this 
125903 ** function returns.
125904 */
125905 static void fts3GetDeltaVarint3(
125906   char **pp,                      /* IN/OUT: Point to read varint from */
125907   char *pEnd,                     /* End of buffer */
125908   int bDescIdx,                   /* True if docids are descending */
125909   sqlite3_int64 *pVal             /* IN/OUT: Integer value */
125910 ){
125911   if( *pp>=pEnd ){
125912     *pp = 0;
125913   }else{
125914     sqlite3_int64 iVal;
125915     *pp += sqlite3Fts3GetVarint(*pp, &iVal);
125916     if( bDescIdx ){
125917       *pVal -= iVal;
125918     }else{
125919       *pVal += iVal;
125920     }
125921   }
125922 }
125923 
125924 /*
125925 ** This function is used to write a single varint to a buffer. The varint
125926 ** is written to *pp. Before returning, *pp is set to point 1 byte past the
125927 ** end of the value written.
125928 **
125929 ** If *pbFirst is zero when this function is called, the value written to
125930 ** the buffer is that of parameter iVal. 
125931 **
125932 ** If *pbFirst is non-zero when this function is called, then the value 
125933 ** written is either (iVal-*piPrev) (if bDescIdx is zero) or (*piPrev-iVal)
125934 ** (if bDescIdx is non-zero).
125935 **
125936 ** Before returning, this function always sets *pbFirst to 1 and *piPrev
125937 ** to the value of parameter iVal.
125938 */
125939 static void fts3PutDeltaVarint3(
125940   char **pp,                      /* IN/OUT: Output pointer */
125941   int bDescIdx,                   /* True for descending docids */
125942   sqlite3_int64 *piPrev,          /* IN/OUT: Previous value written to list */
125943   int *pbFirst,                   /* IN/OUT: True after first int written */
125944   sqlite3_int64 iVal              /* Write this value to the list */
125945 ){
125946   sqlite3_int64 iWrite;
125947   if( bDescIdx==0 || *pbFirst==0 ){
125948     iWrite = iVal - *piPrev;
125949   }else{
125950     iWrite = *piPrev - iVal;
125951   }
125952   assert( *pbFirst || *piPrev==0 );
125953   assert( *pbFirst==0 || iWrite>0 );
125954   *pp += sqlite3Fts3PutVarint(*pp, iWrite);
125955   *piPrev = iVal;
125956   *pbFirst = 1;
125957 }
125958 
125959 
125960 /*
125961 ** This macro is used by various functions that merge doclists. The two
125962 ** arguments are 64-bit docid values. If the value of the stack variable
125963 ** bDescDoclist is 0 when this macro is invoked, then it returns (i1-i2). 
125964 ** Otherwise, (i2-i1).
125965 **
125966 ** Using this makes it easier to write code that can merge doclists that are
125967 ** sorted in either ascending or descending order.
125968 */
125969 #define DOCID_CMP(i1, i2) ((bDescDoclist?-1:1) * (i1-i2))
125970 
125971 /*
125972 ** This function does an "OR" merge of two doclists (output contains all
125973 ** positions contained in either argument doclist). If the docids in the 
125974 ** input doclists are sorted in ascending order, parameter bDescDoclist
125975 ** should be false. If they are sorted in ascending order, it should be
125976 ** passed a non-zero value.
125977 **
125978 ** If no error occurs, *paOut is set to point at an sqlite3_malloc'd buffer
125979 ** containing the output doclist and SQLITE_OK is returned. In this case
125980 ** *pnOut is set to the number of bytes in the output doclist.
125981 **
125982 ** If an error occurs, an SQLite error code is returned. The output values
125983 ** are undefined in this case.
125984 */
125985 static int fts3DoclistOrMerge(
125986   int bDescDoclist,               /* True if arguments are desc */
125987   char *a1, int n1,               /* First doclist */
125988   char *a2, int n2,               /* Second doclist */
125989   char **paOut, int *pnOut        /* OUT: Malloc'd doclist */
125990 ){
125991   sqlite3_int64 i1 = 0;
125992   sqlite3_int64 i2 = 0;
125993   sqlite3_int64 iPrev = 0;
125994   char *pEnd1 = &a1[n1];
125995   char *pEnd2 = &a2[n2];
125996   char *p1 = a1;
125997   char *p2 = a2;
125998   char *p;
125999   char *aOut;
126000   int bFirstOut = 0;
126001 
126002   *paOut = 0;
126003   *pnOut = 0;
126004 
126005   /* Allocate space for the output. Both the input and output doclists
126006   ** are delta encoded. If they are in ascending order (bDescDoclist==0),
126007   ** then the first docid in each list is simply encoded as a varint. For
126008   ** each subsequent docid, the varint stored is the difference between the
126009   ** current and previous docid (a positive number - since the list is in
126010   ** ascending order).
126011   **
126012   ** The first docid written to the output is therefore encoded using the 
126013   ** same number of bytes as it is in whichever of the input lists it is
126014   ** read from. And each subsequent docid read from the same input list 
126015   ** consumes either the same or less bytes as it did in the input (since
126016   ** the difference between it and the previous value in the output must
126017   ** be a positive value less than or equal to the delta value read from 
126018   ** the input list). The same argument applies to all but the first docid
126019   ** read from the 'other' list. And to the contents of all position lists
126020   ** that will be copied and merged from the input to the output.
126021   **
126022   ** However, if the first docid copied to the output is a negative number,
126023   ** then the encoding of the first docid from the 'other' input list may
126024   ** be larger in the output than it was in the input (since the delta value
126025   ** may be a larger positive integer than the actual docid).
126026   **
126027   ** The space required to store the output is therefore the sum of the
126028   ** sizes of the two inputs, plus enough space for exactly one of the input
126029   ** docids to grow. 
126030   **
126031   ** A symetric argument may be made if the doclists are in descending 
126032   ** order.
126033   */
126034   aOut = sqlite3_malloc(n1+n2+FTS3_VARINT_MAX-1);
126035   if( !aOut ) return SQLITE_NOMEM;
126036 
126037   p = aOut;
126038   fts3GetDeltaVarint3(&p1, pEnd1, 0, &i1);
126039   fts3GetDeltaVarint3(&p2, pEnd2, 0, &i2);
126040   while( p1 || p2 ){
126041     sqlite3_int64 iDiff = DOCID_CMP(i1, i2);
126042 
126043     if( p2 && p1 && iDiff==0 ){
126044       fts3PutDeltaVarint3(&p, bDescDoclist, &iPrev, &bFirstOut, i1);
126045       fts3PoslistMerge(&p, &p1, &p2);
126046       fts3GetDeltaVarint3(&p1, pEnd1, bDescDoclist, &i1);
126047       fts3GetDeltaVarint3(&p2, pEnd2, bDescDoclist, &i2);
126048     }else if( !p2 || (p1 && iDiff<0) ){
126049       fts3PutDeltaVarint3(&p, bDescDoclist, &iPrev, &bFirstOut, i1);
126050       fts3PoslistCopy(&p, &p1);
126051       fts3GetDeltaVarint3(&p1, pEnd1, bDescDoclist, &i1);
126052     }else{
126053       fts3PutDeltaVarint3(&p, bDescDoclist, &iPrev, &bFirstOut, i2);
126054       fts3PoslistCopy(&p, &p2);
126055       fts3GetDeltaVarint3(&p2, pEnd2, bDescDoclist, &i2);
126056     }
126057   }
126058 
126059   *paOut = aOut;
126060   *pnOut = (int)(p-aOut);
126061   assert( *pnOut<=n1+n2+FTS3_VARINT_MAX-1 );
126062   return SQLITE_OK;
126063 }
126064 
126065 /*
126066 ** This function does a "phrase" merge of two doclists. In a phrase merge,
126067 ** the output contains a copy of each position from the right-hand input
126068 ** doclist for which there is a position in the left-hand input doclist
126069 ** exactly nDist tokens before it.
126070 **
126071 ** If the docids in the input doclists are sorted in ascending order,
126072 ** parameter bDescDoclist should be false. If they are sorted in ascending 
126073 ** order, it should be passed a non-zero value.
126074 **
126075 ** The right-hand input doclist is overwritten by this function.
126076 */
126077 static void fts3DoclistPhraseMerge(
126078   int bDescDoclist,               /* True if arguments are desc */
126079   int nDist,                      /* Distance from left to right (1=adjacent) */
126080   char *aLeft, int nLeft,         /* Left doclist */
126081   char *aRight, int *pnRight      /* IN/OUT: Right/output doclist */
126082 ){
126083   sqlite3_int64 i1 = 0;
126084   sqlite3_int64 i2 = 0;
126085   sqlite3_int64 iPrev = 0;
126086   char *pEnd1 = &aLeft[nLeft];
126087   char *pEnd2 = &aRight[*pnRight];
126088   char *p1 = aLeft;
126089   char *p2 = aRight;
126090   char *p;
126091   int bFirstOut = 0;
126092   char *aOut = aRight;
126093 
126094   assert( nDist>0 );
126095 
126096   p = aOut;
126097   fts3GetDeltaVarint3(&p1, pEnd1, 0, &i1);
126098   fts3GetDeltaVarint3(&p2, pEnd2, 0, &i2);
126099 
126100   while( p1 && p2 ){
126101     sqlite3_int64 iDiff = DOCID_CMP(i1, i2);
126102     if( iDiff==0 ){
126103       char *pSave = p;
126104       sqlite3_int64 iPrevSave = iPrev;
126105       int bFirstOutSave = bFirstOut;
126106 
126107       fts3PutDeltaVarint3(&p, bDescDoclist, &iPrev, &bFirstOut, i1);
126108       if( 0==fts3PoslistPhraseMerge(&p, nDist, 0, 1, &p1, &p2) ){
126109         p = pSave;
126110         iPrev = iPrevSave;
126111         bFirstOut = bFirstOutSave;
126112       }
126113       fts3GetDeltaVarint3(&p1, pEnd1, bDescDoclist, &i1);
126114       fts3GetDeltaVarint3(&p2, pEnd2, bDescDoclist, &i2);
126115     }else if( iDiff<0 ){
126116       fts3PoslistCopy(0, &p1);
126117       fts3GetDeltaVarint3(&p1, pEnd1, bDescDoclist, &i1);
126118     }else{
126119       fts3PoslistCopy(0, &p2);
126120       fts3GetDeltaVarint3(&p2, pEnd2, bDescDoclist, &i2);
126121     }
126122   }
126123 
126124   *pnRight = (int)(p - aOut);
126125 }
126126 
126127 /*
126128 ** Argument pList points to a position list nList bytes in size. This
126129 ** function checks to see if the position list contains any entries for
126130 ** a token in position 0 (of any column). If so, it writes argument iDelta
126131 ** to the output buffer pOut, followed by a position list consisting only
126132 ** of the entries from pList at position 0, and terminated by an 0x00 byte.
126133 ** The value returned is the number of bytes written to pOut (if any).
126134 */
126135 SQLITE_PRIVATE int sqlite3Fts3FirstFilter(
126136   sqlite3_int64 iDelta,           /* Varint that may be written to pOut */
126137   char *pList,                    /* Position list (no 0x00 term) */
126138   int nList,                      /* Size of pList in bytes */
126139   char *pOut                      /* Write output here */
126140 ){
126141   int nOut = 0;
126142   int bWritten = 0;               /* True once iDelta has been written */
126143   char *p = pList;
126144   char *pEnd = &pList[nList];
126145 
126146   if( *p!=0x01 ){
126147     if( *p==0x02 ){
126148       nOut += sqlite3Fts3PutVarint(&pOut[nOut], iDelta);
126149       pOut[nOut++] = 0x02;
126150       bWritten = 1;
126151     }
126152     fts3ColumnlistCopy(0, &p);
126153   }
126154 
126155   while( p<pEnd && *p==0x01 ){
126156     sqlite3_int64 iCol;
126157     p++;
126158     p += sqlite3Fts3GetVarint(p, &iCol);
126159     if( *p==0x02 ){
126160       if( bWritten==0 ){
126161         nOut += sqlite3Fts3PutVarint(&pOut[nOut], iDelta);
126162         bWritten = 1;
126163       }
126164       pOut[nOut++] = 0x01;
126165       nOut += sqlite3Fts3PutVarint(&pOut[nOut], iCol);
126166       pOut[nOut++] = 0x02;
126167     }
126168     fts3ColumnlistCopy(0, &p);
126169   }
126170   if( bWritten ){
126171     pOut[nOut++] = 0x00;
126172   }
126173 
126174   return nOut;
126175 }
126176 
126177 
126178 /*
126179 ** Merge all doclists in the TermSelect.aaOutput[] array into a single
126180 ** doclist stored in TermSelect.aaOutput[0]. If successful, delete all
126181 ** other doclists (except the aaOutput[0] one) and return SQLITE_OK.
126182 **
126183 ** If an OOM error occurs, return SQLITE_NOMEM. In this case it is
126184 ** the responsibility of the caller to free any doclists left in the
126185 ** TermSelect.aaOutput[] array.
126186 */
126187 static int fts3TermSelectFinishMerge(Fts3Table *p, TermSelect *pTS){
126188   char *aOut = 0;
126189   int nOut = 0;
126190   int i;
126191 
126192   /* Loop through the doclists in the aaOutput[] array. Merge them all
126193   ** into a single doclist.
126194   */
126195   for(i=0; i<SizeofArray(pTS->aaOutput); i++){
126196     if( pTS->aaOutput[i] ){
126197       if( !aOut ){
126198         aOut = pTS->aaOutput[i];
126199         nOut = pTS->anOutput[i];
126200         pTS->aaOutput[i] = 0;
126201       }else{
126202         int nNew;
126203         char *aNew;
126204 
126205         int rc = fts3DoclistOrMerge(p->bDescIdx, 
126206             pTS->aaOutput[i], pTS->anOutput[i], aOut, nOut, &aNew, &nNew
126207         );
126208         if( rc!=SQLITE_OK ){
126209           sqlite3_free(aOut);
126210           return rc;
126211         }
126212 
126213         sqlite3_free(pTS->aaOutput[i]);
126214         sqlite3_free(aOut);
126215         pTS->aaOutput[i] = 0;
126216         aOut = aNew;
126217         nOut = nNew;
126218       }
126219     }
126220   }
126221 
126222   pTS->aaOutput[0] = aOut;
126223   pTS->anOutput[0] = nOut;
126224   return SQLITE_OK;
126225 }
126226 
126227 /*
126228 ** Merge the doclist aDoclist/nDoclist into the TermSelect object passed
126229 ** as the first argument. The merge is an "OR" merge (see function
126230 ** fts3DoclistOrMerge() for details).
126231 **
126232 ** This function is called with the doclist for each term that matches
126233 ** a queried prefix. It merges all these doclists into one, the doclist
126234 ** for the specified prefix. Since there can be a very large number of
126235 ** doclists to merge, the merging is done pair-wise using the TermSelect
126236 ** object.
126237 **
126238 ** This function returns SQLITE_OK if the merge is successful, or an
126239 ** SQLite error code (SQLITE_NOMEM) if an error occurs.
126240 */
126241 static int fts3TermSelectMerge(
126242   Fts3Table *p,                   /* FTS table handle */
126243   TermSelect *pTS,                /* TermSelect object to merge into */
126244   char *aDoclist,                 /* Pointer to doclist */
126245   int nDoclist                    /* Size of aDoclist in bytes */
126246 ){
126247   if( pTS->aaOutput[0]==0 ){
126248     /* If this is the first term selected, copy the doclist to the output
126249     ** buffer using memcpy(). */
126250     pTS->aaOutput[0] = sqlite3_malloc(nDoclist);
126251     pTS->anOutput[0] = nDoclist;
126252     if( pTS->aaOutput[0] ){
126253       memcpy(pTS->aaOutput[0], aDoclist, nDoclist);
126254     }else{
126255       return SQLITE_NOMEM;
126256     }
126257   }else{
126258     char *aMerge = aDoclist;
126259     int nMerge = nDoclist;
126260     int iOut;
126261 
126262     for(iOut=0; iOut<SizeofArray(pTS->aaOutput); iOut++){
126263       if( pTS->aaOutput[iOut]==0 ){
126264         assert( iOut>0 );
126265         pTS->aaOutput[iOut] = aMerge;
126266         pTS->anOutput[iOut] = nMerge;
126267         break;
126268       }else{
126269         char *aNew;
126270         int nNew;
126271 
126272         int rc = fts3DoclistOrMerge(p->bDescIdx, aMerge, nMerge, 
126273             pTS->aaOutput[iOut], pTS->anOutput[iOut], &aNew, &nNew
126274         );
126275         if( rc!=SQLITE_OK ){
126276           if( aMerge!=aDoclist ) sqlite3_free(aMerge);
126277           return rc;
126278         }
126279 
126280         if( aMerge!=aDoclist ) sqlite3_free(aMerge);
126281         sqlite3_free(pTS->aaOutput[iOut]);
126282         pTS->aaOutput[iOut] = 0;
126283   
126284         aMerge = aNew;
126285         nMerge = nNew;
126286         if( (iOut+1)==SizeofArray(pTS->aaOutput) ){
126287           pTS->aaOutput[iOut] = aMerge;
126288           pTS->anOutput[iOut] = nMerge;
126289         }
126290       }
126291     }
126292   }
126293   return SQLITE_OK;
126294 }
126295 
126296 /*
126297 ** Append SegReader object pNew to the end of the pCsr->apSegment[] array.
126298 */
126299 static int fts3SegReaderCursorAppend(
126300   Fts3MultiSegReader *pCsr, 
126301   Fts3SegReader *pNew
126302 ){
126303   if( (pCsr->nSegment%16)==0 ){
126304     Fts3SegReader **apNew;
126305     int nByte = (pCsr->nSegment + 16)*sizeof(Fts3SegReader*);
126306     apNew = (Fts3SegReader **)sqlite3_realloc(pCsr->apSegment, nByte);
126307     if( !apNew ){
126308       sqlite3Fts3SegReaderFree(pNew);
126309       return SQLITE_NOMEM;
126310     }
126311     pCsr->apSegment = apNew;
126312   }
126313   pCsr->apSegment[pCsr->nSegment++] = pNew;
126314   return SQLITE_OK;
126315 }
126316 
126317 /*
126318 ** Add seg-reader objects to the Fts3MultiSegReader object passed as the
126319 ** 8th argument.
126320 **
126321 ** This function returns SQLITE_OK if successful, or an SQLite error code
126322 ** otherwise.
126323 */
126324 static int fts3SegReaderCursor(
126325   Fts3Table *p,                   /* FTS3 table handle */
126326   int iLangid,                    /* Language id */
126327   int iIndex,                     /* Index to search (from 0 to p->nIndex-1) */
126328   int iLevel,                     /* Level of segments to scan */
126329   const char *zTerm,              /* Term to query for */
126330   int nTerm,                      /* Size of zTerm in bytes */
126331   int isPrefix,                   /* True for a prefix search */
126332   int isScan,                     /* True to scan from zTerm to EOF */
126333   Fts3MultiSegReader *pCsr        /* Cursor object to populate */
126334 ){
126335   int rc = SQLITE_OK;             /* Error code */
126336   sqlite3_stmt *pStmt = 0;        /* Statement to iterate through segments */
126337   int rc2;                        /* Result of sqlite3_reset() */
126338 
126339   /* If iLevel is less than 0 and this is not a scan, include a seg-reader 
126340   ** for the pending-terms. If this is a scan, then this call must be being
126341   ** made by an fts4aux module, not an FTS table. In this case calling
126342   ** Fts3SegReaderPending might segfault, as the data structures used by 
126343   ** fts4aux are not completely populated. So it's easiest to filter these
126344   ** calls out here.  */
126345   if( iLevel<0 && p->aIndex ){
126346     Fts3SegReader *pSeg = 0;
126347     rc = sqlite3Fts3SegReaderPending(p, iIndex, zTerm, nTerm, isPrefix, &pSeg);
126348     if( rc==SQLITE_OK && pSeg ){
126349       rc = fts3SegReaderCursorAppend(pCsr, pSeg);
126350     }
126351   }
126352 
126353   if( iLevel!=FTS3_SEGCURSOR_PENDING ){
126354     if( rc==SQLITE_OK ){
126355       rc = sqlite3Fts3AllSegdirs(p, iLangid, iIndex, iLevel, &pStmt);
126356     }
126357 
126358     while( rc==SQLITE_OK && SQLITE_ROW==(rc = sqlite3_step(pStmt)) ){
126359       Fts3SegReader *pSeg = 0;
126360 
126361       /* Read the values returned by the SELECT into local variables. */
126362       sqlite3_int64 iStartBlock = sqlite3_column_int64(pStmt, 1);
126363       sqlite3_int64 iLeavesEndBlock = sqlite3_column_int64(pStmt, 2);
126364       sqlite3_int64 iEndBlock = sqlite3_column_int64(pStmt, 3);
126365       int nRoot = sqlite3_column_bytes(pStmt, 4);
126366       char const *zRoot = sqlite3_column_blob(pStmt, 4);
126367 
126368       /* If zTerm is not NULL, and this segment is not stored entirely on its
126369       ** root node, the range of leaves scanned can be reduced. Do this. */
126370       if( iStartBlock && zTerm ){
126371         sqlite3_int64 *pi = (isPrefix ? &iLeavesEndBlock : 0);
126372         rc = fts3SelectLeaf(p, zTerm, nTerm, zRoot, nRoot, &iStartBlock, pi);
126373         if( rc!=SQLITE_OK ) goto finished;
126374         if( isPrefix==0 && isScan==0 ) iLeavesEndBlock = iStartBlock;
126375       }
126376  
126377       rc = sqlite3Fts3SegReaderNew(pCsr->nSegment+1, 
126378           (isPrefix==0 && isScan==0),
126379           iStartBlock, iLeavesEndBlock, 
126380           iEndBlock, zRoot, nRoot, &pSeg
126381       );
126382       if( rc!=SQLITE_OK ) goto finished;
126383       rc = fts3SegReaderCursorAppend(pCsr, pSeg);
126384     }
126385   }
126386 
126387  finished:
126388   rc2 = sqlite3_reset(pStmt);
126389   if( rc==SQLITE_DONE ) rc = rc2;
126390 
126391   return rc;
126392 }
126393 
126394 /*
126395 ** Set up a cursor object for iterating through a full-text index or a 
126396 ** single level therein.
126397 */
126398 SQLITE_PRIVATE int sqlite3Fts3SegReaderCursor(
126399   Fts3Table *p,                   /* FTS3 table handle */
126400   int iLangid,                    /* Language-id to search */
126401   int iIndex,                     /* Index to search (from 0 to p->nIndex-1) */
126402   int iLevel,                     /* Level of segments to scan */
126403   const char *zTerm,              /* Term to query for */
126404   int nTerm,                      /* Size of zTerm in bytes */
126405   int isPrefix,                   /* True for a prefix search */
126406   int isScan,                     /* True to scan from zTerm to EOF */
126407   Fts3MultiSegReader *pCsr       /* Cursor object to populate */
126408 ){
126409   assert( iIndex>=0 && iIndex<p->nIndex );
126410   assert( iLevel==FTS3_SEGCURSOR_ALL
126411       ||  iLevel==FTS3_SEGCURSOR_PENDING 
126412       ||  iLevel>=0
126413   );
126414   assert( iLevel<FTS3_SEGDIR_MAXLEVEL );
126415   assert( FTS3_SEGCURSOR_ALL<0 && FTS3_SEGCURSOR_PENDING<0 );
126416   assert( isPrefix==0 || isScan==0 );
126417 
126418   memset(pCsr, 0, sizeof(Fts3MultiSegReader));
126419   return fts3SegReaderCursor(
126420       p, iLangid, iIndex, iLevel, zTerm, nTerm, isPrefix, isScan, pCsr
126421   );
126422 }
126423 
126424 /*
126425 ** In addition to its current configuration, have the Fts3MultiSegReader
126426 ** passed as the 4th argument also scan the doclist for term zTerm/nTerm.
126427 **
126428 ** SQLITE_OK is returned if no error occurs, otherwise an SQLite error code.
126429 */
126430 static int fts3SegReaderCursorAddZero(
126431   Fts3Table *p,                   /* FTS virtual table handle */
126432   int iLangid,
126433   const char *zTerm,              /* Term to scan doclist of */
126434   int nTerm,                      /* Number of bytes in zTerm */
126435   Fts3MultiSegReader *pCsr        /* Fts3MultiSegReader to modify */
126436 ){
126437   return fts3SegReaderCursor(p, 
126438       iLangid, 0, FTS3_SEGCURSOR_ALL, zTerm, nTerm, 0, 0,pCsr
126439   );
126440 }
126441 
126442 /*
126443 ** Open an Fts3MultiSegReader to scan the doclist for term zTerm/nTerm. Or,
126444 ** if isPrefix is true, to scan the doclist for all terms for which 
126445 ** zTerm/nTerm is a prefix. If successful, return SQLITE_OK and write
126446 ** a pointer to the new Fts3MultiSegReader to *ppSegcsr. Otherwise, return
126447 ** an SQLite error code.
126448 **
126449 ** It is the responsibility of the caller to free this object by eventually
126450 ** passing it to fts3SegReaderCursorFree() 
126451 **
126452 ** SQLITE_OK is returned if no error occurs, otherwise an SQLite error code.
126453 ** Output parameter *ppSegcsr is set to 0 if an error occurs.
126454 */
126455 static int fts3TermSegReaderCursor(
126456   Fts3Cursor *pCsr,               /* Virtual table cursor handle */
126457   const char *zTerm,              /* Term to query for */
126458   int nTerm,                      /* Size of zTerm in bytes */
126459   int isPrefix,                   /* True for a prefix search */
126460   Fts3MultiSegReader **ppSegcsr   /* OUT: Allocated seg-reader cursor */
126461 ){
126462   Fts3MultiSegReader *pSegcsr;    /* Object to allocate and return */
126463   int rc = SQLITE_NOMEM;          /* Return code */
126464 
126465   pSegcsr = sqlite3_malloc(sizeof(Fts3MultiSegReader));
126466   if( pSegcsr ){
126467     int i;
126468     int bFound = 0;               /* True once an index has been found */
126469     Fts3Table *p = (Fts3Table *)pCsr->base.pVtab;
126470 
126471     if( isPrefix ){
126472       for(i=1; bFound==0 && i<p->nIndex; i++){
126473         if( p->aIndex[i].nPrefix==nTerm ){
126474           bFound = 1;
126475           rc = sqlite3Fts3SegReaderCursor(p, pCsr->iLangid, 
126476               i, FTS3_SEGCURSOR_ALL, zTerm, nTerm, 0, 0, pSegcsr
126477           );
126478           pSegcsr->bLookup = 1;
126479         }
126480       }
126481 
126482       for(i=1; bFound==0 && i<p->nIndex; i++){
126483         if( p->aIndex[i].nPrefix==nTerm+1 ){
126484           bFound = 1;
126485           rc = sqlite3Fts3SegReaderCursor(p, pCsr->iLangid, 
126486               i, FTS3_SEGCURSOR_ALL, zTerm, nTerm, 1, 0, pSegcsr
126487           );
126488           if( rc==SQLITE_OK ){
126489             rc = fts3SegReaderCursorAddZero(
126490                 p, pCsr->iLangid, zTerm, nTerm, pSegcsr
126491             );
126492           }
126493         }
126494       }
126495     }
126496 
126497     if( bFound==0 ){
126498       rc = sqlite3Fts3SegReaderCursor(p, pCsr->iLangid, 
126499           0, FTS3_SEGCURSOR_ALL, zTerm, nTerm, isPrefix, 0, pSegcsr
126500       );
126501       pSegcsr->bLookup = !isPrefix;
126502     }
126503   }
126504 
126505   *ppSegcsr = pSegcsr;
126506   return rc;
126507 }
126508 
126509 /*
126510 ** Free an Fts3MultiSegReader allocated by fts3TermSegReaderCursor().
126511 */
126512 static void fts3SegReaderCursorFree(Fts3MultiSegReader *pSegcsr){
126513   sqlite3Fts3SegReaderFinish(pSegcsr);
126514   sqlite3_free(pSegcsr);
126515 }
126516 
126517 /*
126518 ** This function retrieves the doclist for the specified term (or term
126519 ** prefix) from the database.
126520 */
126521 static int fts3TermSelect(
126522   Fts3Table *p,                   /* Virtual table handle */
126523   Fts3PhraseToken *pTok,          /* Token to query for */
126524   int iColumn,                    /* Column to query (or -ve for all columns) */
126525   int *pnOut,                     /* OUT: Size of buffer at *ppOut */
126526   char **ppOut                    /* OUT: Malloced result buffer */
126527 ){
126528   int rc;                         /* Return code */
126529   Fts3MultiSegReader *pSegcsr;    /* Seg-reader cursor for this term */
126530   TermSelect tsc;                 /* Object for pair-wise doclist merging */
126531   Fts3SegFilter filter;           /* Segment term filter configuration */
126532 
126533   pSegcsr = pTok->pSegcsr;
126534   memset(&tsc, 0, sizeof(TermSelect));
126535 
126536   filter.flags = FTS3_SEGMENT_IGNORE_EMPTY | FTS3_SEGMENT_REQUIRE_POS
126537         | (pTok->isPrefix ? FTS3_SEGMENT_PREFIX : 0)
126538         | (pTok->bFirst ? FTS3_SEGMENT_FIRST : 0)
126539         | (iColumn<p->nColumn ? FTS3_SEGMENT_COLUMN_FILTER : 0);
126540   filter.iCol = iColumn;
126541   filter.zTerm = pTok->z;
126542   filter.nTerm = pTok->n;
126543 
126544   rc = sqlite3Fts3SegReaderStart(p, pSegcsr, &filter);
126545   while( SQLITE_OK==rc
126546       && SQLITE_ROW==(rc = sqlite3Fts3SegReaderStep(p, pSegcsr)) 
126547   ){
126548     rc = fts3TermSelectMerge(p, &tsc, pSegcsr->aDoclist, pSegcsr->nDoclist);
126549   }
126550 
126551   if( rc==SQLITE_OK ){
126552     rc = fts3TermSelectFinishMerge(p, &tsc);
126553   }
126554   if( rc==SQLITE_OK ){
126555     *ppOut = tsc.aaOutput[0];
126556     *pnOut = tsc.anOutput[0];
126557   }else{
126558     int i;
126559     for(i=0; i<SizeofArray(tsc.aaOutput); i++){
126560       sqlite3_free(tsc.aaOutput[i]);
126561     }
126562   }
126563 
126564   fts3SegReaderCursorFree(pSegcsr);
126565   pTok->pSegcsr = 0;
126566   return rc;
126567 }
126568 
126569 /*
126570 ** This function counts the total number of docids in the doclist stored
126571 ** in buffer aList[], size nList bytes.
126572 **
126573 ** If the isPoslist argument is true, then it is assumed that the doclist
126574 ** contains a position-list following each docid. Otherwise, it is assumed
126575 ** that the doclist is simply a list of docids stored as delta encoded 
126576 ** varints.
126577 */
126578 static int fts3DoclistCountDocids(char *aList, int nList){
126579   int nDoc = 0;                   /* Return value */
126580   if( aList ){
126581     char *aEnd = &aList[nList];   /* Pointer to one byte after EOF */
126582     char *p = aList;              /* Cursor */
126583     while( p<aEnd ){
126584       nDoc++;
126585       while( (*p++)&0x80 );     /* Skip docid varint */
126586       fts3PoslistCopy(0, &p);   /* Skip over position list */
126587     }
126588   }
126589 
126590   return nDoc;
126591 }
126592 
126593 /*
126594 ** Advance the cursor to the next row in the %_content table that
126595 ** matches the search criteria.  For a MATCH search, this will be
126596 ** the next row that matches. For a full-table scan, this will be
126597 ** simply the next row in the %_content table.  For a docid lookup,
126598 ** this routine simply sets the EOF flag.
126599 **
126600 ** Return SQLITE_OK if nothing goes wrong.  SQLITE_OK is returned
126601 ** even if we reach end-of-file.  The fts3EofMethod() will be called
126602 ** subsequently to determine whether or not an EOF was hit.
126603 */
126604 static int fts3NextMethod(sqlite3_vtab_cursor *pCursor){
126605   int rc;
126606   Fts3Cursor *pCsr = (Fts3Cursor *)pCursor;
126607   if( pCsr->eSearch==FTS3_DOCID_SEARCH || pCsr->eSearch==FTS3_FULLSCAN_SEARCH ){
126608     if( SQLITE_ROW!=sqlite3_step(pCsr->pStmt) ){
126609       pCsr->isEof = 1;
126610       rc = sqlite3_reset(pCsr->pStmt);
126611     }else{
126612       pCsr->iPrevId = sqlite3_column_int64(pCsr->pStmt, 0);
126613       rc = SQLITE_OK;
126614     }
126615   }else{
126616     rc = fts3EvalNext((Fts3Cursor *)pCursor);
126617   }
126618   assert( ((Fts3Table *)pCsr->base.pVtab)->pSegments==0 );
126619   return rc;
126620 }
126621 
126622 /*
126623 ** The following are copied from sqliteInt.h.
126624 **
126625 ** Constants for the largest and smallest possible 64-bit signed integers.
126626 ** These macros are designed to work correctly on both 32-bit and 64-bit
126627 ** compilers.
126628 */
126629 #ifndef SQLITE_AMALGAMATION
126630 # define LARGEST_INT64  (0xffffffff|(((sqlite3_int64)0x7fffffff)<<32))
126631 # define SMALLEST_INT64 (((sqlite3_int64)-1) - LARGEST_INT64)
126632 #endif
126633 
126634 /*
126635 ** If the numeric type of argument pVal is "integer", then return it
126636 ** converted to a 64-bit signed integer. Otherwise, return a copy of
126637 ** the second parameter, iDefault.
126638 */
126639 static sqlite3_int64 fts3DocidRange(sqlite3_value *pVal, i64 iDefault){
126640   if( pVal ){
126641     int eType = sqlite3_value_numeric_type(pVal);
126642     if( eType==SQLITE_INTEGER ){
126643       return sqlite3_value_int64(pVal);
126644     }
126645   }
126646   return iDefault;
126647 }
126648 
126649 /*
126650 ** This is the xFilter interface for the virtual table.  See
126651 ** the virtual table xFilter method documentation for additional
126652 ** information.
126653 **
126654 ** If idxNum==FTS3_FULLSCAN_SEARCH then do a full table scan against
126655 ** the %_content table.
126656 **
126657 ** If idxNum==FTS3_DOCID_SEARCH then do a docid lookup for a single entry
126658 ** in the %_content table.
126659 **
126660 ** If idxNum>=FTS3_FULLTEXT_SEARCH then use the full text index.  The
126661 ** column on the left-hand side of the MATCH operator is column
126662 ** number idxNum-FTS3_FULLTEXT_SEARCH, 0 indexed.  argv[0] is the right-hand
126663 ** side of the MATCH operator.
126664 */
126665 static int fts3FilterMethod(
126666   sqlite3_vtab_cursor *pCursor,   /* The cursor used for this query */
126667   int idxNum,                     /* Strategy index */
126668   const char *idxStr,             /* Unused */
126669   int nVal,                       /* Number of elements in apVal */
126670   sqlite3_value **apVal           /* Arguments for the indexing scheme */
126671 ){
126672   int rc;
126673   char *zSql;                     /* SQL statement used to access %_content */
126674   int eSearch;
126675   Fts3Table *p = (Fts3Table *)pCursor->pVtab;
126676   Fts3Cursor *pCsr = (Fts3Cursor *)pCursor;
126677 
126678   sqlite3_value *pCons = 0;       /* The MATCH or rowid constraint, if any */
126679   sqlite3_value *pLangid = 0;     /* The "langid = ?" constraint, if any */
126680   sqlite3_value *pDocidGe = 0;    /* The "docid >= ?" constraint, if any */
126681   sqlite3_value *pDocidLe = 0;    /* The "docid <= ?" constraint, if any */
126682   int iIdx;
126683 
126684   UNUSED_PARAMETER(idxStr);
126685   UNUSED_PARAMETER(nVal);
126686 
126687   eSearch = (idxNum & 0x0000FFFF);
126688   assert( eSearch>=0 && eSearch<=(FTS3_FULLTEXT_SEARCH+p->nColumn) );
126689   assert( p->pSegments==0 );
126690 
126691   /* Collect arguments into local variables */
126692   iIdx = 0;
126693   if( eSearch!=FTS3_FULLSCAN_SEARCH ) pCons = apVal[iIdx++];
126694   if( idxNum & FTS3_HAVE_LANGID ) pLangid = apVal[iIdx++];
126695   if( idxNum & FTS3_HAVE_DOCID_GE ) pDocidGe = apVal[iIdx++];
126696   if( idxNum & FTS3_HAVE_DOCID_LE ) pDocidLe = apVal[iIdx++];
126697   assert( iIdx==nVal );
126698 
126699   /* In case the cursor has been used before, clear it now. */
126700   sqlite3_finalize(pCsr->pStmt);
126701   sqlite3_free(pCsr->aDoclist);
126702   sqlite3Fts3ExprFree(pCsr->pExpr);
126703   memset(&pCursor[1], 0, sizeof(Fts3Cursor)-sizeof(sqlite3_vtab_cursor));
126704 
126705   /* Set the lower and upper bounds on docids to return */
126706   pCsr->iMinDocid = fts3DocidRange(pDocidGe, SMALLEST_INT64);
126707   pCsr->iMaxDocid = fts3DocidRange(pDocidLe, LARGEST_INT64);
126708 
126709   if( idxStr ){
126710     pCsr->bDesc = (idxStr[0]=='D');
126711   }else{
126712     pCsr->bDesc = p->bDescIdx;
126713   }
126714   pCsr->eSearch = (i16)eSearch;
126715 
126716   if( eSearch!=FTS3_DOCID_SEARCH && eSearch!=FTS3_FULLSCAN_SEARCH ){
126717     int iCol = eSearch-FTS3_FULLTEXT_SEARCH;
126718     const char *zQuery = (const char *)sqlite3_value_text(pCons);
126719 
126720     if( zQuery==0 && sqlite3_value_type(pCons)!=SQLITE_NULL ){
126721       return SQLITE_NOMEM;
126722     }
126723 
126724     pCsr->iLangid = 0;
126725     if( pLangid ) pCsr->iLangid = sqlite3_value_int(pLangid);
126726 
126727     assert( p->base.zErrMsg==0 );
126728     rc = sqlite3Fts3ExprParse(p->pTokenizer, pCsr->iLangid,
126729         p->azColumn, p->bFts4, p->nColumn, iCol, zQuery, -1, &pCsr->pExpr, 
126730         &p->base.zErrMsg
126731     );
126732     if( rc!=SQLITE_OK ){
126733       return rc;
126734     }
126735 
126736     rc = fts3EvalStart(pCsr);
126737     sqlite3Fts3SegmentsClose(p);
126738     if( rc!=SQLITE_OK ) return rc;
126739     pCsr->pNextId = pCsr->aDoclist;
126740     pCsr->iPrevId = 0;
126741   }
126742 
126743   /* Compile a SELECT statement for this cursor. For a full-table-scan, the
126744   ** statement loops through all rows of the %_content table. For a
126745   ** full-text query or docid lookup, the statement retrieves a single
126746   ** row by docid.
126747   */
126748   if( eSearch==FTS3_FULLSCAN_SEARCH ){
126749     zSql = sqlite3_mprintf(
126750         "SELECT %s ORDER BY rowid %s",
126751         p->zReadExprlist, (pCsr->bDesc ? "DESC" : "ASC")
126752     );
126753     if( zSql ){
126754       rc = sqlite3_prepare_v2(p->db, zSql, -1, &pCsr->pStmt, 0);
126755       sqlite3_free(zSql);
126756     }else{
126757       rc = SQLITE_NOMEM;
126758     }
126759   }else if( eSearch==FTS3_DOCID_SEARCH ){
126760     rc = fts3CursorSeekStmt(pCsr, &pCsr->pStmt);
126761     if( rc==SQLITE_OK ){
126762       rc = sqlite3_bind_value(pCsr->pStmt, 1, pCons);
126763     }
126764   }
126765   if( rc!=SQLITE_OK ) return rc;
126766 
126767   return fts3NextMethod(pCursor);
126768 }
126769 
126770 /* 
126771 ** This is the xEof method of the virtual table. SQLite calls this 
126772 ** routine to find out if it has reached the end of a result set.
126773 */
126774 static int fts3EofMethod(sqlite3_vtab_cursor *pCursor){
126775   return ((Fts3Cursor *)pCursor)->isEof;
126776 }
126777 
126778 /* 
126779 ** This is the xRowid method. The SQLite core calls this routine to
126780 ** retrieve the rowid for the current row of the result set. fts3
126781 ** exposes %_content.docid as the rowid for the virtual table. The
126782 ** rowid should be written to *pRowid.
126783 */
126784 static int fts3RowidMethod(sqlite3_vtab_cursor *pCursor, sqlite_int64 *pRowid){
126785   Fts3Cursor *pCsr = (Fts3Cursor *) pCursor;
126786   *pRowid = pCsr->iPrevId;
126787   return SQLITE_OK;
126788 }
126789 
126790 /* 
126791 ** This is the xColumn method, called by SQLite to request a value from
126792 ** the row that the supplied cursor currently points to.
126793 **
126794 ** If:
126795 **
126796 **   (iCol <  p->nColumn)   -> The value of the iCol'th user column.
126797 **   (iCol == p->nColumn)   -> Magic column with the same name as the table.
126798 **   (iCol == p->nColumn+1) -> Docid column
126799 **   (iCol == p->nColumn+2) -> Langid column
126800 */
126801 static int fts3ColumnMethod(
126802   sqlite3_vtab_cursor *pCursor,   /* Cursor to retrieve value from */
126803   sqlite3_context *pCtx,          /* Context for sqlite3_result_xxx() calls */
126804   int iCol                        /* Index of column to read value from */
126805 ){
126806   int rc = SQLITE_OK;             /* Return Code */
126807   Fts3Cursor *pCsr = (Fts3Cursor *) pCursor;
126808   Fts3Table *p = (Fts3Table *)pCursor->pVtab;
126809 
126810   /* The column value supplied by SQLite must be in range. */
126811   assert( iCol>=0 && iCol<=p->nColumn+2 );
126812 
126813   if( iCol==p->nColumn+1 ){
126814     /* This call is a request for the "docid" column. Since "docid" is an 
126815     ** alias for "rowid", use the xRowid() method to obtain the value.
126816     */
126817     sqlite3_result_int64(pCtx, pCsr->iPrevId);
126818   }else if( iCol==p->nColumn ){
126819     /* The extra column whose name is the same as the table.
126820     ** Return a blob which is a pointer to the cursor.  */
126821     sqlite3_result_blob(pCtx, &pCsr, sizeof(pCsr), SQLITE_TRANSIENT);
126822   }else if( iCol==p->nColumn+2 && pCsr->pExpr ){
126823     sqlite3_result_int64(pCtx, pCsr->iLangid);
126824   }else{
126825     /* The requested column is either a user column (one that contains 
126826     ** indexed data), or the language-id column.  */
126827     rc = fts3CursorSeek(0, pCsr);
126828 
126829     if( rc==SQLITE_OK ){
126830       if( iCol==p->nColumn+2 ){
126831         int iLangid = 0;
126832         if( p->zLanguageid ){
126833           iLangid = sqlite3_column_int(pCsr->pStmt, p->nColumn+1);
126834         }
126835         sqlite3_result_int(pCtx, iLangid);
126836       }else if( sqlite3_data_count(pCsr->pStmt)>(iCol+1) ){
126837         sqlite3_result_value(pCtx, sqlite3_column_value(pCsr->pStmt, iCol+1));
126838       }
126839     }
126840   }
126841 
126842   assert( ((Fts3Table *)pCsr->base.pVtab)->pSegments==0 );
126843   return rc;
126844 }
126845 
126846 /* 
126847 ** This function is the implementation of the xUpdate callback used by 
126848 ** FTS3 virtual tables. It is invoked by SQLite each time a row is to be
126849 ** inserted, updated or deleted.
126850 */
126851 static int fts3UpdateMethod(
126852   sqlite3_vtab *pVtab,            /* Virtual table handle */
126853   int nArg,                       /* Size of argument array */
126854   sqlite3_value **apVal,          /* Array of arguments */
126855   sqlite_int64 *pRowid            /* OUT: The affected (or effected) rowid */
126856 ){
126857   return sqlite3Fts3UpdateMethod(pVtab, nArg, apVal, pRowid);
126858 }
126859 
126860 /*
126861 ** Implementation of xSync() method. Flush the contents of the pending-terms
126862 ** hash-table to the database.
126863 */
126864 static int fts3SyncMethod(sqlite3_vtab *pVtab){
126865 
126866   /* Following an incremental-merge operation, assuming that the input
126867   ** segments are not completely consumed (the usual case), they are updated
126868   ** in place to remove the entries that have already been merged. This
126869   ** involves updating the leaf block that contains the smallest unmerged
126870   ** entry and each block (if any) between the leaf and the root node. So
126871   ** if the height of the input segment b-trees is N, and input segments
126872   ** are merged eight at a time, updating the input segments at the end
126873   ** of an incremental-merge requires writing (8*(1+N)) blocks. N is usually
126874   ** small - often between 0 and 2. So the overhead of the incremental
126875   ** merge is somewhere between 8 and 24 blocks. To avoid this overhead
126876   ** dwarfing the actual productive work accomplished, the incremental merge
126877   ** is only attempted if it will write at least 64 leaf blocks. Hence
126878   ** nMinMerge.
126879   **
126880   ** Of course, updating the input segments also involves deleting a bunch
126881   ** of blocks from the segments table. But this is not considered overhead
126882   ** as it would also be required by a crisis-merge that used the same input 
126883   ** segments.
126884   */
126885   const u32 nMinMerge = 64;       /* Minimum amount of incr-merge work to do */
126886 
126887   Fts3Table *p = (Fts3Table*)pVtab;
126888   int rc = sqlite3Fts3PendingTermsFlush(p);
126889 
126890   if( rc==SQLITE_OK && p->bAutoincrmerge==1 && p->nLeafAdd>(nMinMerge/16) ){
126891     int mxLevel = 0;              /* Maximum relative level value in db */
126892     int A;                        /* Incr-merge parameter A */
126893 
126894     rc = sqlite3Fts3MaxLevel(p, &mxLevel);
126895     assert( rc==SQLITE_OK || mxLevel==0 );
126896     A = p->nLeafAdd * mxLevel;
126897     A += (A/2);
126898     if( A>(int)nMinMerge ) rc = sqlite3Fts3Incrmerge(p, A, 8);
126899   }
126900   sqlite3Fts3SegmentsClose(p);
126901   return rc;
126902 }
126903 
126904 /*
126905 ** Implementation of xBegin() method. This is a no-op.
126906 */
126907 static int fts3BeginMethod(sqlite3_vtab *pVtab){
126908   Fts3Table *p = (Fts3Table*)pVtab;
126909   UNUSED_PARAMETER(pVtab);
126910   assert( p->pSegments==0 );
126911   assert( p->nPendingData==0 );
126912   assert( p->inTransaction!=1 );
126913   TESTONLY( p->inTransaction = 1 );
126914   TESTONLY( p->mxSavepoint = -1; );
126915   p->nLeafAdd = 0;
126916   return SQLITE_OK;
126917 }
126918 
126919 /*
126920 ** Implementation of xCommit() method. This is a no-op. The contents of
126921 ** the pending-terms hash-table have already been flushed into the database
126922 ** by fts3SyncMethod().
126923 */
126924 static int fts3CommitMethod(sqlite3_vtab *pVtab){
126925   TESTONLY( Fts3Table *p = (Fts3Table*)pVtab );
126926   UNUSED_PARAMETER(pVtab);
126927   assert( p->nPendingData==0 );
126928   assert( p->inTransaction!=0 );
126929   assert( p->pSegments==0 );
126930   TESTONLY( p->inTransaction = 0 );
126931   TESTONLY( p->mxSavepoint = -1; );
126932   return SQLITE_OK;
126933 }
126934 
126935 /*
126936 ** Implementation of xRollback(). Discard the contents of the pending-terms
126937 ** hash-table. Any changes made to the database are reverted by SQLite.
126938 */
126939 static int fts3RollbackMethod(sqlite3_vtab *pVtab){
126940   Fts3Table *p = (Fts3Table*)pVtab;
126941   sqlite3Fts3PendingTermsClear(p);
126942   assert( p->inTransaction!=0 );
126943   TESTONLY( p->inTransaction = 0 );
126944   TESTONLY( p->mxSavepoint = -1; );
126945   return SQLITE_OK;
126946 }
126947 
126948 /*
126949 ** When called, *ppPoslist must point to the byte immediately following the
126950 ** end of a position-list. i.e. ( (*ppPoslist)[-1]==POS_END ). This function
126951 ** moves *ppPoslist so that it instead points to the first byte of the
126952 ** same position list.
126953 */
126954 static void fts3ReversePoslist(char *pStart, char **ppPoslist){
126955   char *p = &(*ppPoslist)[-2];
126956   char c = 0;
126957 
126958   while( p>pStart && (c=*p--)==0 );
126959   while( p>pStart && (*p & 0x80) | c ){ 
126960     c = *p--; 
126961   }
126962   if( p>pStart ){ p = &p[2]; }
126963   while( *p++&0x80 );
126964   *ppPoslist = p;
126965 }
126966 
126967 /*
126968 ** Helper function used by the implementation of the overloaded snippet(),
126969 ** offsets() and optimize() SQL functions.
126970 **
126971 ** If the value passed as the third argument is a blob of size
126972 ** sizeof(Fts3Cursor*), then the blob contents are copied to the 
126973 ** output variable *ppCsr and SQLITE_OK is returned. Otherwise, an error
126974 ** message is written to context pContext and SQLITE_ERROR returned. The
126975 ** string passed via zFunc is used as part of the error message.
126976 */
126977 static int fts3FunctionArg(
126978   sqlite3_context *pContext,      /* SQL function call context */
126979   const char *zFunc,              /* Function name */
126980   sqlite3_value *pVal,            /* argv[0] passed to function */
126981   Fts3Cursor **ppCsr              /* OUT: Store cursor handle here */
126982 ){
126983   Fts3Cursor *pRet;
126984   if( sqlite3_value_type(pVal)!=SQLITE_BLOB 
126985    || sqlite3_value_bytes(pVal)!=sizeof(Fts3Cursor *)
126986   ){
126987     char *zErr = sqlite3_mprintf("illegal first argument to %s", zFunc);
126988     sqlite3_result_error(pContext, zErr, -1);
126989     sqlite3_free(zErr);
126990     return SQLITE_ERROR;
126991   }
126992   memcpy(&pRet, sqlite3_value_blob(pVal), sizeof(Fts3Cursor *));
126993   *ppCsr = pRet;
126994   return SQLITE_OK;
126995 }
126996 
126997 /*
126998 ** Implementation of the snippet() function for FTS3
126999 */
127000 static void fts3SnippetFunc(
127001   sqlite3_context *pContext,      /* SQLite function call context */
127002   int nVal,                       /* Size of apVal[] array */
127003   sqlite3_value **apVal           /* Array of arguments */
127004 ){
127005   Fts3Cursor *pCsr;               /* Cursor handle passed through apVal[0] */
127006   const char *zStart = "<b>";
127007   const char *zEnd = "</b>";
127008   const char *zEllipsis = "<b>...</b>";
127009   int iCol = -1;
127010   int nToken = 15;                /* Default number of tokens in snippet */
127011 
127012   /* There must be at least one argument passed to this function (otherwise
127013   ** the non-overloaded version would have been called instead of this one).
127014   */
127015   assert( nVal>=1 );
127016 
127017   if( nVal>6 ){
127018     sqlite3_result_error(pContext, 
127019         "wrong number of arguments to function snippet()", -1);
127020     return;
127021   }
127022   if( fts3FunctionArg(pContext, "snippet", apVal[0], &pCsr) ) return;
127023 
127024   switch( nVal ){
127025     case 6: nToken = sqlite3_value_int(apVal[5]);
127026     case 5: iCol = sqlite3_value_int(apVal[4]);
127027     case 4: zEllipsis = (const char*)sqlite3_value_text(apVal[3]);
127028     case 3: zEnd = (const char*)sqlite3_value_text(apVal[2]);
127029     case 2: zStart = (const char*)sqlite3_value_text(apVal[1]);
127030   }
127031   if( !zEllipsis || !zEnd || !zStart ){
127032     sqlite3_result_error_nomem(pContext);
127033   }else if( SQLITE_OK==fts3CursorSeek(pContext, pCsr) ){
127034     sqlite3Fts3Snippet(pContext, pCsr, zStart, zEnd, zEllipsis, iCol, nToken);
127035   }
127036 }
127037 
127038 /*
127039 ** Implementation of the offsets() function for FTS3
127040 */
127041 static void fts3OffsetsFunc(
127042   sqlite3_context *pContext,      /* SQLite function call context */
127043   int nVal,                       /* Size of argument array */
127044   sqlite3_value **apVal           /* Array of arguments */
127045 ){
127046   Fts3Cursor *pCsr;               /* Cursor handle passed through apVal[0] */
127047 
127048   UNUSED_PARAMETER(nVal);
127049 
127050   assert( nVal==1 );
127051   if( fts3FunctionArg(pContext, "offsets", apVal[0], &pCsr) ) return;
127052   assert( pCsr );
127053   if( SQLITE_OK==fts3CursorSeek(pContext, pCsr) ){
127054     sqlite3Fts3Offsets(pContext, pCsr);
127055   }
127056 }
127057 
127058 /* 
127059 ** Implementation of the special optimize() function for FTS3. This 
127060 ** function merges all segments in the database to a single segment.
127061 ** Example usage is:
127062 **
127063 **   SELECT optimize(t) FROM t LIMIT 1;
127064 **
127065 ** where 't' is the name of an FTS3 table.
127066 */
127067 static void fts3OptimizeFunc(
127068   sqlite3_context *pContext,      /* SQLite function call context */
127069   int nVal,                       /* Size of argument array */
127070   sqlite3_value **apVal           /* Array of arguments */
127071 ){
127072   int rc;                         /* Return code */
127073   Fts3Table *p;                   /* Virtual table handle */
127074   Fts3Cursor *pCursor;            /* Cursor handle passed through apVal[0] */
127075 
127076   UNUSED_PARAMETER(nVal);
127077 
127078   assert( nVal==1 );
127079   if( fts3FunctionArg(pContext, "optimize", apVal[0], &pCursor) ) return;
127080   p = (Fts3Table *)pCursor->base.pVtab;
127081   assert( p );
127082 
127083   rc = sqlite3Fts3Optimize(p);
127084 
127085   switch( rc ){
127086     case SQLITE_OK:
127087       sqlite3_result_text(pContext, "Index optimized", -1, SQLITE_STATIC);
127088       break;
127089     case SQLITE_DONE:
127090       sqlite3_result_text(pContext, "Index already optimal", -1, SQLITE_STATIC);
127091       break;
127092     default:
127093       sqlite3_result_error_code(pContext, rc);
127094       break;
127095   }
127096 }
127097 
127098 /*
127099 ** Implementation of the matchinfo() function for FTS3
127100 */
127101 static void fts3MatchinfoFunc(
127102   sqlite3_context *pContext,      /* SQLite function call context */
127103   int nVal,                       /* Size of argument array */
127104   sqlite3_value **apVal           /* Array of arguments */
127105 ){
127106   Fts3Cursor *pCsr;               /* Cursor handle passed through apVal[0] */
127107   assert( nVal==1 || nVal==2 );
127108   if( SQLITE_OK==fts3FunctionArg(pContext, "matchinfo", apVal[0], &pCsr) ){
127109     const char *zArg = 0;
127110     if( nVal>1 ){
127111       zArg = (const char *)sqlite3_value_text(apVal[1]);
127112     }
127113     sqlite3Fts3Matchinfo(pContext, pCsr, zArg);
127114   }
127115 }
127116 
127117 /*
127118 ** This routine implements the xFindFunction method for the FTS3
127119 ** virtual table.
127120 */
127121 static int fts3FindFunctionMethod(
127122   sqlite3_vtab *pVtab,            /* Virtual table handle */
127123   int nArg,                       /* Number of SQL function arguments */
127124   const char *zName,              /* Name of SQL function */
127125   void (**pxFunc)(sqlite3_context*,int,sqlite3_value**), /* OUT: Result */
127126   void **ppArg                    /* Unused */
127127 ){
127128   struct Overloaded {
127129     const char *zName;
127130     void (*xFunc)(sqlite3_context*,int,sqlite3_value**);
127131   } aOverload[] = {
127132     { "snippet", fts3SnippetFunc },
127133     { "offsets", fts3OffsetsFunc },
127134     { "optimize", fts3OptimizeFunc },
127135     { "matchinfo", fts3MatchinfoFunc },
127136   };
127137   int i;                          /* Iterator variable */
127138 
127139   UNUSED_PARAMETER(pVtab);
127140   UNUSED_PARAMETER(nArg);
127141   UNUSED_PARAMETER(ppArg);
127142 
127143   for(i=0; i<SizeofArray(aOverload); i++){
127144     if( strcmp(zName, aOverload[i].zName)==0 ){
127145       *pxFunc = aOverload[i].xFunc;
127146       return 1;
127147     }
127148   }
127149 
127150   /* No function of the specified name was found. Return 0. */
127151   return 0;
127152 }
127153 
127154 /*
127155 ** Implementation of FTS3 xRename method. Rename an fts3 table.
127156 */
127157 static int fts3RenameMethod(
127158   sqlite3_vtab *pVtab,            /* Virtual table handle */
127159   const char *zName               /* New name of table */
127160 ){
127161   Fts3Table *p = (Fts3Table *)pVtab;
127162   sqlite3 *db = p->db;            /* Database connection */
127163   int rc;                         /* Return Code */
127164 
127165   /* As it happens, the pending terms table is always empty here. This is
127166   ** because an "ALTER TABLE RENAME TABLE" statement inside a transaction 
127167   ** always opens a savepoint transaction. And the xSavepoint() method 
127168   ** flushes the pending terms table. But leave the (no-op) call to
127169   ** PendingTermsFlush() in in case that changes.
127170   */
127171   assert( p->nPendingData==0 );
127172   rc = sqlite3Fts3PendingTermsFlush(p);
127173 
127174   if( p->zContentTbl==0 ){
127175     fts3DbExec(&rc, db,
127176       "ALTER TABLE %Q.'%q_content'  RENAME TO '%q_content';",
127177       p->zDb, p->zName, zName
127178     );
127179   }
127180 
127181   if( p->bHasDocsize ){
127182     fts3DbExec(&rc, db,
127183       "ALTER TABLE %Q.'%q_docsize'  RENAME TO '%q_docsize';",
127184       p->zDb, p->zName, zName
127185     );
127186   }
127187   if( p->bHasStat ){
127188     fts3DbExec(&rc, db,
127189       "ALTER TABLE %Q.'%q_stat'  RENAME TO '%q_stat';",
127190       p->zDb, p->zName, zName
127191     );
127192   }
127193   fts3DbExec(&rc, db,
127194     "ALTER TABLE %Q.'%q_segments' RENAME TO '%q_segments';",
127195     p->zDb, p->zName, zName
127196   );
127197   fts3DbExec(&rc, db,
127198     "ALTER TABLE %Q.'%q_segdir'   RENAME TO '%q_segdir';",
127199     p->zDb, p->zName, zName
127200   );
127201   return rc;
127202 }
127203 
127204 /*
127205 ** The xSavepoint() method.
127206 **
127207 ** Flush the contents of the pending-terms table to disk.
127208 */
127209 static int fts3SavepointMethod(sqlite3_vtab *pVtab, int iSavepoint){
127210   int rc = SQLITE_OK;
127211   UNUSED_PARAMETER(iSavepoint);
127212   assert( ((Fts3Table *)pVtab)->inTransaction );
127213   assert( ((Fts3Table *)pVtab)->mxSavepoint < iSavepoint );
127214   TESTONLY( ((Fts3Table *)pVtab)->mxSavepoint = iSavepoint );
127215   if( ((Fts3Table *)pVtab)->bIgnoreSavepoint==0 ){
127216     rc = fts3SyncMethod(pVtab);
127217   }
127218   return rc;
127219 }
127220 
127221 /*
127222 ** The xRelease() method.
127223 **
127224 ** This is a no-op.
127225 */
127226 static int fts3ReleaseMethod(sqlite3_vtab *pVtab, int iSavepoint){
127227   TESTONLY( Fts3Table *p = (Fts3Table*)pVtab );
127228   UNUSED_PARAMETER(iSavepoint);
127229   UNUSED_PARAMETER(pVtab);
127230   assert( p->inTransaction );
127231   assert( p->mxSavepoint >= iSavepoint );
127232   TESTONLY( p->mxSavepoint = iSavepoint-1 );
127233   return SQLITE_OK;
127234 }
127235 
127236 /*
127237 ** The xRollbackTo() method.
127238 **
127239 ** Discard the contents of the pending terms table.
127240 */
127241 static int fts3RollbackToMethod(sqlite3_vtab *pVtab, int iSavepoint){
127242   Fts3Table *p = (Fts3Table*)pVtab;
127243   UNUSED_PARAMETER(iSavepoint);
127244   assert( p->inTransaction );
127245   assert( p->mxSavepoint >= iSavepoint );
127246   TESTONLY( p->mxSavepoint = iSavepoint );
127247   sqlite3Fts3PendingTermsClear(p);
127248   return SQLITE_OK;
127249 }
127250 
127251 static const sqlite3_module fts3Module = {
127252   /* iVersion      */ 2,
127253   /* xCreate       */ fts3CreateMethod,
127254   /* xConnect      */ fts3ConnectMethod,
127255   /* xBestIndex    */ fts3BestIndexMethod,
127256   /* xDisconnect   */ fts3DisconnectMethod,
127257   /* xDestroy      */ fts3DestroyMethod,
127258   /* xOpen         */ fts3OpenMethod,
127259   /* xClose        */ fts3CloseMethod,
127260   /* xFilter       */ fts3FilterMethod,
127261   /* xNext         */ fts3NextMethod,
127262   /* xEof          */ fts3EofMethod,
127263   /* xColumn       */ fts3ColumnMethod,
127264   /* xRowid        */ fts3RowidMethod,
127265   /* xUpdate       */ fts3UpdateMethod,
127266   /* xBegin        */ fts3BeginMethod,
127267   /* xSync         */ fts3SyncMethod,
127268   /* xCommit       */ fts3CommitMethod,
127269   /* xRollback     */ fts3RollbackMethod,
127270   /* xFindFunction */ fts3FindFunctionMethod,
127271   /* xRename */       fts3RenameMethod,
127272   /* xSavepoint    */ fts3SavepointMethod,
127273   /* xRelease      */ fts3ReleaseMethod,
127274   /* xRollbackTo   */ fts3RollbackToMethod,
127275 };
127276 
127277 /*
127278 ** This function is registered as the module destructor (called when an
127279 ** FTS3 enabled database connection is closed). It frees the memory
127280 ** allocated for the tokenizer hash table.
127281 */
127282 static void hashDestroy(void *p){
127283   Fts3Hash *pHash = (Fts3Hash *)p;
127284   sqlite3Fts3HashClear(pHash);
127285   sqlite3_free(pHash);
127286 }
127287 
127288 /*
127289 ** The fts3 built-in tokenizers - "simple", "porter" and "icu"- are 
127290 ** implemented in files fts3_tokenizer1.c, fts3_porter.c and fts3_icu.c
127291 ** respectively. The following three forward declarations are for functions
127292 ** declared in these files used to retrieve the respective implementations.
127293 **
127294 ** Calling sqlite3Fts3SimpleTokenizerModule() sets the value pointed
127295 ** to by the argument to point to the "simple" tokenizer implementation.
127296 ** And so on.
127297 */
127298 SQLITE_PRIVATE void sqlite3Fts3SimpleTokenizerModule(sqlite3_tokenizer_module const**ppModule);
127299 SQLITE_PRIVATE void sqlite3Fts3PorterTokenizerModule(sqlite3_tokenizer_module const**ppModule);
127300 #ifdef SQLITE_ENABLE_FTS4_UNICODE61
127301 SQLITE_PRIVATE void sqlite3Fts3UnicodeTokenizer(sqlite3_tokenizer_module const**ppModule);
127302 #endif
127303 #ifdef SQLITE_ENABLE_ICU
127304 SQLITE_PRIVATE void sqlite3Fts3IcuTokenizerModule(sqlite3_tokenizer_module const**ppModule);
127305 #endif
127306 
127307 /*
127308 ** Initialize the fts3 extension. If this extension is built as part
127309 ** of the sqlite library, then this function is called directly by
127310 ** SQLite. If fts3 is built as a dynamically loadable extension, this
127311 ** function is called by the sqlite3_extension_init() entry point.
127312 */
127313 SQLITE_PRIVATE int sqlite3Fts3Init(sqlite3 *db){
127314   int rc = SQLITE_OK;
127315   Fts3Hash *pHash = 0;
127316   const sqlite3_tokenizer_module *pSimple = 0;
127317   const sqlite3_tokenizer_module *pPorter = 0;
127318 #ifdef SQLITE_ENABLE_FTS4_UNICODE61
127319   const sqlite3_tokenizer_module *pUnicode = 0;
127320 #endif
127321 
127322 #ifdef SQLITE_ENABLE_ICU
127323   const sqlite3_tokenizer_module *pIcu = 0;
127324   sqlite3Fts3IcuTokenizerModule(&pIcu);
127325 #endif
127326 
127327 #ifdef SQLITE_ENABLE_FTS4_UNICODE61
127328   sqlite3Fts3UnicodeTokenizer(&pUnicode);
127329 #endif
127330 
127331 #ifdef SQLITE_TEST
127332   rc = sqlite3Fts3InitTerm(db);
127333   if( rc!=SQLITE_OK ) return rc;
127334 #endif
127335 
127336   rc = sqlite3Fts3InitAux(db);
127337   if( rc!=SQLITE_OK ) return rc;
127338 
127339   sqlite3Fts3SimpleTokenizerModule(&pSimple);
127340   sqlite3Fts3PorterTokenizerModule(&pPorter);
127341 
127342   /* Allocate and initialize the hash-table used to store tokenizers. */
127343   pHash = sqlite3_malloc(sizeof(Fts3Hash));
127344   if( !pHash ){
127345     rc = SQLITE_NOMEM;
127346   }else{
127347     sqlite3Fts3HashInit(pHash, FTS3_HASH_STRING, 1);
127348   }
127349 
127350   /* Load the built-in tokenizers into the hash table */
127351   if( rc==SQLITE_OK ){
127352     if( sqlite3Fts3HashInsert(pHash, "simple", 7, (void *)pSimple)
127353      || sqlite3Fts3HashInsert(pHash, "porter", 7, (void *)pPorter) 
127354 
127355 #ifdef SQLITE_ENABLE_FTS4_UNICODE61
127356      || sqlite3Fts3HashInsert(pHash, "unicode61", 10, (void *)pUnicode) 
127357 #endif
127358 #ifdef SQLITE_ENABLE_ICU
127359      || (pIcu && sqlite3Fts3HashInsert(pHash, "icu", 4, (void *)pIcu))
127360 #endif
127361     ){
127362       rc = SQLITE_NOMEM;
127363     }
127364   }
127365 
127366 #ifdef SQLITE_TEST
127367   if( rc==SQLITE_OK ){
127368     rc = sqlite3Fts3ExprInitTestInterface(db);
127369   }
127370 #endif
127371 
127372   /* Create the virtual table wrapper around the hash-table and overload 
127373   ** the two scalar functions. If this is successful, register the
127374   ** module with sqlite.
127375   */
127376   if( SQLITE_OK==rc 
127377    && SQLITE_OK==(rc = sqlite3Fts3InitHashTable(db, pHash, "fts3_tokenizer"))
127378    && SQLITE_OK==(rc = sqlite3_overload_function(db, "snippet", -1))
127379    && SQLITE_OK==(rc = sqlite3_overload_function(db, "offsets", 1))
127380    && SQLITE_OK==(rc = sqlite3_overload_function(db, "matchinfo", 1))
127381    && SQLITE_OK==(rc = sqlite3_overload_function(db, "matchinfo", 2))
127382    && SQLITE_OK==(rc = sqlite3_overload_function(db, "optimize", 1))
127383   ){
127384     rc = sqlite3_create_module_v2(
127385         db, "fts3", &fts3Module, (void *)pHash, hashDestroy
127386     );
127387     if( rc==SQLITE_OK ){
127388       rc = sqlite3_create_module_v2(
127389           db, "fts4", &fts3Module, (void *)pHash, 0
127390       );
127391     }
127392     if( rc==SQLITE_OK ){
127393       rc = sqlite3Fts3InitTok(db, (void *)pHash);
127394     }
127395     return rc;
127396   }
127397 
127398 
127399   /* An error has occurred. Delete the hash table and return the error code. */
127400   assert( rc!=SQLITE_OK );
127401   if( pHash ){
127402     sqlite3Fts3HashClear(pHash);
127403     sqlite3_free(pHash);
127404   }
127405   return rc;
127406 }
127407 
127408 /*
127409 ** Allocate an Fts3MultiSegReader for each token in the expression headed
127410 ** by pExpr. 
127411 **
127412 ** An Fts3SegReader object is a cursor that can seek or scan a range of
127413 ** entries within a single segment b-tree. An Fts3MultiSegReader uses multiple
127414 ** Fts3SegReader objects internally to provide an interface to seek or scan
127415 ** within the union of all segments of a b-tree. Hence the name.
127416 **
127417 ** If the allocated Fts3MultiSegReader just seeks to a single entry in a
127418 ** segment b-tree (if the term is not a prefix or it is a prefix for which
127419 ** there exists prefix b-tree of the right length) then it may be traversed
127420 ** and merged incrementally. Otherwise, it has to be merged into an in-memory 
127421 ** doclist and then traversed.
127422 */
127423 static void fts3EvalAllocateReaders(
127424   Fts3Cursor *pCsr,               /* FTS cursor handle */
127425   Fts3Expr *pExpr,                /* Allocate readers for this expression */
127426   int *pnToken,                   /* OUT: Total number of tokens in phrase. */
127427   int *pnOr,                      /* OUT: Total number of OR nodes in expr. */
127428   int *pRc                        /* IN/OUT: Error code */
127429 ){
127430   if( pExpr && SQLITE_OK==*pRc ){
127431     if( pExpr->eType==FTSQUERY_PHRASE ){
127432       int i;
127433       int nToken = pExpr->pPhrase->nToken;
127434       *pnToken += nToken;
127435       for(i=0; i<nToken; i++){
127436         Fts3PhraseToken *pToken = &pExpr->pPhrase->aToken[i];
127437         int rc = fts3TermSegReaderCursor(pCsr, 
127438             pToken->z, pToken->n, pToken->isPrefix, &pToken->pSegcsr
127439         );
127440         if( rc!=SQLITE_OK ){
127441           *pRc = rc;
127442           return;
127443         }
127444       }
127445       assert( pExpr->pPhrase->iDoclistToken==0 );
127446       pExpr->pPhrase->iDoclistToken = -1;
127447     }else{
127448       *pnOr += (pExpr->eType==FTSQUERY_OR);
127449       fts3EvalAllocateReaders(pCsr, pExpr->pLeft, pnToken, pnOr, pRc);
127450       fts3EvalAllocateReaders(pCsr, pExpr->pRight, pnToken, pnOr, pRc);
127451     }
127452   }
127453 }
127454 
127455 /*
127456 ** Arguments pList/nList contain the doclist for token iToken of phrase p.
127457 ** It is merged into the main doclist stored in p->doclist.aAll/nAll.
127458 **
127459 ** This function assumes that pList points to a buffer allocated using
127460 ** sqlite3_malloc(). This function takes responsibility for eventually
127461 ** freeing the buffer.
127462 */
127463 static void fts3EvalPhraseMergeToken(
127464   Fts3Table *pTab,                /* FTS Table pointer */
127465   Fts3Phrase *p,                  /* Phrase to merge pList/nList into */
127466   int iToken,                     /* Token pList/nList corresponds to */
127467   char *pList,                    /* Pointer to doclist */
127468   int nList                       /* Number of bytes in pList */
127469 ){
127470   assert( iToken!=p->iDoclistToken );
127471 
127472   if( pList==0 ){
127473     sqlite3_free(p->doclist.aAll);
127474     p->doclist.aAll = 0;
127475     p->doclist.nAll = 0;
127476   }
127477 
127478   else if( p->iDoclistToken<0 ){
127479     p->doclist.aAll = pList;
127480     p->doclist.nAll = nList;
127481   }
127482 
127483   else if( p->doclist.aAll==0 ){
127484     sqlite3_free(pList);
127485   }
127486 
127487   else {
127488     char *pLeft;
127489     char *pRight;
127490     int nLeft;
127491     int nRight;
127492     int nDiff;
127493 
127494     if( p->iDoclistToken<iToken ){
127495       pLeft = p->doclist.aAll;
127496       nLeft = p->doclist.nAll;
127497       pRight = pList;
127498       nRight = nList;
127499       nDiff = iToken - p->iDoclistToken;
127500     }else{
127501       pRight = p->doclist.aAll;
127502       nRight = p->doclist.nAll;
127503       pLeft = pList;
127504       nLeft = nList;
127505       nDiff = p->iDoclistToken - iToken;
127506     }
127507 
127508     fts3DoclistPhraseMerge(pTab->bDescIdx, nDiff, pLeft, nLeft, pRight,&nRight);
127509     sqlite3_free(pLeft);
127510     p->doclist.aAll = pRight;
127511     p->doclist.nAll = nRight;
127512   }
127513 
127514   if( iToken>p->iDoclistToken ) p->iDoclistToken = iToken;
127515 }
127516 
127517 /*
127518 ** Load the doclist for phrase p into p->doclist.aAll/nAll. The loaded doclist
127519 ** does not take deferred tokens into account.
127520 **
127521 ** SQLITE_OK is returned if no error occurs, otherwise an SQLite error code.
127522 */
127523 static int fts3EvalPhraseLoad(
127524   Fts3Cursor *pCsr,               /* FTS Cursor handle */
127525   Fts3Phrase *p                   /* Phrase object */
127526 ){
127527   Fts3Table *pTab = (Fts3Table *)pCsr->base.pVtab;
127528   int iToken;
127529   int rc = SQLITE_OK;
127530 
127531   for(iToken=0; rc==SQLITE_OK && iToken<p->nToken; iToken++){
127532     Fts3PhraseToken *pToken = &p->aToken[iToken];
127533     assert( pToken->pDeferred==0 || pToken->pSegcsr==0 );
127534 
127535     if( pToken->pSegcsr ){
127536       int nThis = 0;
127537       char *pThis = 0;
127538       rc = fts3TermSelect(pTab, pToken, p->iColumn, &nThis, &pThis);
127539       if( rc==SQLITE_OK ){
127540         fts3EvalPhraseMergeToken(pTab, p, iToken, pThis, nThis);
127541       }
127542     }
127543     assert( pToken->pSegcsr==0 );
127544   }
127545 
127546   return rc;
127547 }
127548 
127549 /*
127550 ** This function is called on each phrase after the position lists for
127551 ** any deferred tokens have been loaded into memory. It updates the phrases
127552 ** current position list to include only those positions that are really
127553 ** instances of the phrase (after considering deferred tokens). If this
127554 ** means that the phrase does not appear in the current row, doclist.pList
127555 ** and doclist.nList are both zeroed.
127556 **
127557 ** SQLITE_OK is returned if no error occurs, otherwise an SQLite error code.
127558 */
127559 static int fts3EvalDeferredPhrase(Fts3Cursor *pCsr, Fts3Phrase *pPhrase){
127560   int iToken;                     /* Used to iterate through phrase tokens */
127561   char *aPoslist = 0;             /* Position list for deferred tokens */
127562   int nPoslist = 0;               /* Number of bytes in aPoslist */
127563   int iPrev = -1;                 /* Token number of previous deferred token */
127564 
127565   assert( pPhrase->doclist.bFreeList==0 );
127566 
127567   for(iToken=0; iToken<pPhrase->nToken; iToken++){
127568     Fts3PhraseToken *pToken = &pPhrase->aToken[iToken];
127569     Fts3DeferredToken *pDeferred = pToken->pDeferred;
127570 
127571     if( pDeferred ){
127572       char *pList;
127573       int nList;
127574       int rc = sqlite3Fts3DeferredTokenList(pDeferred, &pList, &nList);
127575       if( rc!=SQLITE_OK ) return rc;
127576 
127577       if( pList==0 ){
127578         sqlite3_free(aPoslist);
127579         pPhrase->doclist.pList = 0;
127580         pPhrase->doclist.nList = 0;
127581         return SQLITE_OK;
127582 
127583       }else if( aPoslist==0 ){
127584         aPoslist = pList;
127585         nPoslist = nList;
127586 
127587       }else{
127588         char *aOut = pList;
127589         char *p1 = aPoslist;
127590         char *p2 = aOut;
127591 
127592         assert( iPrev>=0 );
127593         fts3PoslistPhraseMerge(&aOut, iToken-iPrev, 0, 1, &p1, &p2);
127594         sqlite3_free(aPoslist);
127595         aPoslist = pList;
127596         nPoslist = (int)(aOut - aPoslist);
127597         if( nPoslist==0 ){
127598           sqlite3_free(aPoslist);
127599           pPhrase->doclist.pList = 0;
127600           pPhrase->doclist.nList = 0;
127601           return SQLITE_OK;
127602         }
127603       }
127604       iPrev = iToken;
127605     }
127606   }
127607 
127608   if( iPrev>=0 ){
127609     int nMaxUndeferred = pPhrase->iDoclistToken;
127610     if( nMaxUndeferred<0 ){
127611       pPhrase->doclist.pList = aPoslist;
127612       pPhrase->doclist.nList = nPoslist;
127613       pPhrase->doclist.iDocid = pCsr->iPrevId;
127614       pPhrase->doclist.bFreeList = 1;
127615     }else{
127616       int nDistance;
127617       char *p1;
127618       char *p2;
127619       char *aOut;
127620 
127621       if( nMaxUndeferred>iPrev ){
127622         p1 = aPoslist;
127623         p2 = pPhrase->doclist.pList;
127624         nDistance = nMaxUndeferred - iPrev;
127625       }else{
127626         p1 = pPhrase->doclist.pList;
127627         p2 = aPoslist;
127628         nDistance = iPrev - nMaxUndeferred;
127629       }
127630 
127631       aOut = (char *)sqlite3_malloc(nPoslist+8);
127632       if( !aOut ){
127633         sqlite3_free(aPoslist);
127634         return SQLITE_NOMEM;
127635       }
127636       
127637       pPhrase->doclist.pList = aOut;
127638       if( fts3PoslistPhraseMerge(&aOut, nDistance, 0, 1, &p1, &p2) ){
127639         pPhrase->doclist.bFreeList = 1;
127640         pPhrase->doclist.nList = (int)(aOut - pPhrase->doclist.pList);
127641       }else{
127642         sqlite3_free(aOut);
127643         pPhrase->doclist.pList = 0;
127644         pPhrase->doclist.nList = 0;
127645       }
127646       sqlite3_free(aPoslist);
127647     }
127648   }
127649 
127650   return SQLITE_OK;
127651 }
127652 
127653 /*
127654 ** Maximum number of tokens a phrase may have to be considered for the
127655 ** incremental doclists strategy.
127656 */
127657 #define MAX_INCR_PHRASE_TOKENS 4
127658 
127659 /*
127660 ** This function is called for each Fts3Phrase in a full-text query 
127661 ** expression to initialize the mechanism for returning rows. Once this
127662 ** function has been called successfully on an Fts3Phrase, it may be
127663 ** used with fts3EvalPhraseNext() to iterate through the matching docids.
127664 **
127665 ** If parameter bOptOk is true, then the phrase may (or may not) use the
127666 ** incremental loading strategy. Otherwise, the entire doclist is loaded into
127667 ** memory within this call.
127668 **
127669 ** SQLITE_OK is returned if no error occurs, otherwise an SQLite error code.
127670 */
127671 static int fts3EvalPhraseStart(Fts3Cursor *pCsr, int bOptOk, Fts3Phrase *p){
127672   Fts3Table *pTab = (Fts3Table *)pCsr->base.pVtab;
127673   int rc = SQLITE_OK;             /* Error code */
127674   int i;
127675 
127676   /* Determine if doclists may be loaded from disk incrementally. This is
127677   ** possible if the bOptOk argument is true, the FTS doclists will be
127678   ** scanned in forward order, and the phrase consists of 
127679   ** MAX_INCR_PHRASE_TOKENS or fewer tokens, none of which are are "^first"
127680   ** tokens or prefix tokens that cannot use a prefix-index.  */
127681   int bHaveIncr = 0;
127682   int bIncrOk = (bOptOk 
127683    && pCsr->bDesc==pTab->bDescIdx 
127684    && p->nToken<=MAX_INCR_PHRASE_TOKENS && p->nToken>0
127685    && p->nToken<=MAX_INCR_PHRASE_TOKENS && p->nToken>0
127686 #ifdef SQLITE_TEST
127687    && pTab->bNoIncrDoclist==0
127688 #endif
127689   );
127690   for(i=0; bIncrOk==1 && i<p->nToken; i++){
127691     Fts3PhraseToken *pToken = &p->aToken[i];
127692     if( pToken->bFirst || (pToken->pSegcsr!=0 && !pToken->pSegcsr->bLookup) ){
127693       bIncrOk = 0;
127694     }
127695     if( pToken->pSegcsr ) bHaveIncr = 1;
127696   }
127697 
127698   if( bIncrOk && bHaveIncr ){
127699     /* Use the incremental approach. */
127700     int iCol = (p->iColumn >= pTab->nColumn ? -1 : p->iColumn);
127701     for(i=0; rc==SQLITE_OK && i<p->nToken; i++){
127702       Fts3PhraseToken *pToken = &p->aToken[i];
127703       Fts3MultiSegReader *pSegcsr = pToken->pSegcsr;
127704       if( pSegcsr ){
127705         rc = sqlite3Fts3MsrIncrStart(pTab, pSegcsr, iCol, pToken->z, pToken->n);
127706       }
127707     }
127708     p->bIncr = 1;
127709   }else{
127710     /* Load the full doclist for the phrase into memory. */
127711     rc = fts3EvalPhraseLoad(pCsr, p);
127712     p->bIncr = 0;
127713   }
127714 
127715   assert( rc!=SQLITE_OK || p->nToken<1 || p->aToken[0].pSegcsr==0 || p->bIncr );
127716   return rc;
127717 }
127718 
127719 /*
127720 ** This function is used to iterate backwards (from the end to start) 
127721 ** through doclists. It is used by this module to iterate through phrase
127722 ** doclists in reverse and by the fts3_write.c module to iterate through
127723 ** pending-terms lists when writing to databases with "order=desc".
127724 **
127725 ** The doclist may be sorted in ascending (parameter bDescIdx==0) or 
127726 ** descending (parameter bDescIdx==1) order of docid. Regardless, this
127727 ** function iterates from the end of the doclist to the beginning.
127728 */
127729 SQLITE_PRIVATE void sqlite3Fts3DoclistPrev(
127730   int bDescIdx,                   /* True if the doclist is desc */
127731   char *aDoclist,                 /* Pointer to entire doclist */
127732   int nDoclist,                   /* Length of aDoclist in bytes */
127733   char **ppIter,                  /* IN/OUT: Iterator pointer */
127734   sqlite3_int64 *piDocid,         /* IN/OUT: Docid pointer */
127735   int *pnList,                    /* OUT: List length pointer */
127736   u8 *pbEof                       /* OUT: End-of-file flag */
127737 ){
127738   char *p = *ppIter;
127739 
127740   assert( nDoclist>0 );
127741   assert( *pbEof==0 );
127742   assert( p || *piDocid==0 );
127743   assert( !p || (p>aDoclist && p<&aDoclist[nDoclist]) );
127744 
127745   if( p==0 ){
127746     sqlite3_int64 iDocid = 0;
127747     char *pNext = 0;
127748     char *pDocid = aDoclist;
127749     char *pEnd = &aDoclist[nDoclist];
127750     int iMul = 1;
127751 
127752     while( pDocid<pEnd ){
127753       sqlite3_int64 iDelta;
127754       pDocid += sqlite3Fts3GetVarint(pDocid, &iDelta);
127755       iDocid += (iMul * iDelta);
127756       pNext = pDocid;
127757       fts3PoslistCopy(0, &pDocid);
127758       while( pDocid<pEnd && *pDocid==0 ) pDocid++;
127759       iMul = (bDescIdx ? -1 : 1);
127760     }
127761 
127762     *pnList = (int)(pEnd - pNext);
127763     *ppIter = pNext;
127764     *piDocid = iDocid;
127765   }else{
127766     int iMul = (bDescIdx ? -1 : 1);
127767     sqlite3_int64 iDelta;
127768     fts3GetReverseVarint(&p, aDoclist, &iDelta);
127769     *piDocid -= (iMul * iDelta);
127770 
127771     if( p==aDoclist ){
127772       *pbEof = 1;
127773     }else{
127774       char *pSave = p;
127775       fts3ReversePoslist(aDoclist, &p);
127776       *pnList = (int)(pSave - p);
127777     }
127778     *ppIter = p;
127779   }
127780 }
127781 
127782 /*
127783 ** Iterate forwards through a doclist.
127784 */
127785 SQLITE_PRIVATE void sqlite3Fts3DoclistNext(
127786   int bDescIdx,                   /* True if the doclist is desc */
127787   char *aDoclist,                 /* Pointer to entire doclist */
127788   int nDoclist,                   /* Length of aDoclist in bytes */
127789   char **ppIter,                  /* IN/OUT: Iterator pointer */
127790   sqlite3_int64 *piDocid,         /* IN/OUT: Docid pointer */
127791   u8 *pbEof                       /* OUT: End-of-file flag */
127792 ){
127793   char *p = *ppIter;
127794 
127795   assert( nDoclist>0 );
127796   assert( *pbEof==0 );
127797   assert( p || *piDocid==0 );
127798   assert( !p || (p>=aDoclist && p<=&aDoclist[nDoclist]) );
127799 
127800   if( p==0 ){
127801     p = aDoclist;
127802     p += sqlite3Fts3GetVarint(p, piDocid);
127803   }else{
127804     fts3PoslistCopy(0, &p);
127805     if( p>=&aDoclist[nDoclist] ){
127806       *pbEof = 1;
127807     }else{
127808       sqlite3_int64 iVar;
127809       p += sqlite3Fts3GetVarint(p, &iVar);
127810       *piDocid += ((bDescIdx ? -1 : 1) * iVar);
127811     }
127812   }
127813 
127814   *ppIter = p;
127815 }
127816 
127817 /*
127818 ** Advance the iterator pDL to the next entry in pDL->aAll/nAll. Set *pbEof
127819 ** to true if EOF is reached.
127820 */
127821 static void fts3EvalDlPhraseNext(
127822   Fts3Table *pTab,
127823   Fts3Doclist *pDL,
127824   u8 *pbEof
127825 ){
127826   char *pIter;                            /* Used to iterate through aAll */
127827   char *pEnd = &pDL->aAll[pDL->nAll];     /* 1 byte past end of aAll */
127828  
127829   if( pDL->pNextDocid ){
127830     pIter = pDL->pNextDocid;
127831   }else{
127832     pIter = pDL->aAll;
127833   }
127834 
127835   if( pIter>=pEnd ){
127836     /* We have already reached the end of this doclist. EOF. */
127837     *pbEof = 1;
127838   }else{
127839     sqlite3_int64 iDelta;
127840     pIter += sqlite3Fts3GetVarint(pIter, &iDelta);
127841     if( pTab->bDescIdx==0 || pDL->pNextDocid==0 ){
127842       pDL->iDocid += iDelta;
127843     }else{
127844       pDL->iDocid -= iDelta;
127845     }
127846     pDL->pList = pIter;
127847     fts3PoslistCopy(0, &pIter);
127848     pDL->nList = (int)(pIter - pDL->pList);
127849 
127850     /* pIter now points just past the 0x00 that terminates the position-
127851     ** list for document pDL->iDocid. However, if this position-list was
127852     ** edited in place by fts3EvalNearTrim(), then pIter may not actually
127853     ** point to the start of the next docid value. The following line deals
127854     ** with this case by advancing pIter past the zero-padding added by
127855     ** fts3EvalNearTrim().  */
127856     while( pIter<pEnd && *pIter==0 ) pIter++;
127857 
127858     pDL->pNextDocid = pIter;
127859     assert( pIter>=&pDL->aAll[pDL->nAll] || *pIter );
127860     *pbEof = 0;
127861   }
127862 }
127863 
127864 /*
127865 ** Helper type used by fts3EvalIncrPhraseNext() and incrPhraseTokenNext().
127866 */
127867 typedef struct TokenDoclist TokenDoclist;
127868 struct TokenDoclist {
127869   int bIgnore;
127870   sqlite3_int64 iDocid;
127871   char *pList;
127872   int nList;
127873 };
127874 
127875 /*
127876 ** Token pToken is an incrementally loaded token that is part of a 
127877 ** multi-token phrase. Advance it to the next matching document in the
127878 ** database and populate output variable *p with the details of the new
127879 ** entry. Or, if the iterator has reached EOF, set *pbEof to true.
127880 **
127881 ** If an error occurs, return an SQLite error code. Otherwise, return 
127882 ** SQLITE_OK.
127883 */
127884 static int incrPhraseTokenNext(
127885   Fts3Table *pTab,                /* Virtual table handle */
127886   Fts3Phrase *pPhrase,            /* Phrase to advance token of */
127887   int iToken,                     /* Specific token to advance */
127888   TokenDoclist *p,                /* OUT: Docid and doclist for new entry */
127889   u8 *pbEof                       /* OUT: True if iterator is at EOF */
127890 ){
127891   int rc = SQLITE_OK;
127892 
127893   if( pPhrase->iDoclistToken==iToken ){
127894     assert( p->bIgnore==0 );
127895     assert( pPhrase->aToken[iToken].pSegcsr==0 );
127896     fts3EvalDlPhraseNext(pTab, &pPhrase->doclist, pbEof);
127897     p->pList = pPhrase->doclist.pList;
127898     p->nList = pPhrase->doclist.nList;
127899     p->iDocid = pPhrase->doclist.iDocid;
127900   }else{
127901     Fts3PhraseToken *pToken = &pPhrase->aToken[iToken];
127902     assert( pToken->pDeferred==0 );
127903     assert( pToken->pSegcsr || pPhrase->iDoclistToken>=0 );
127904     if( pToken->pSegcsr ){
127905       assert( p->bIgnore==0 );
127906       rc = sqlite3Fts3MsrIncrNext(
127907           pTab, pToken->pSegcsr, &p->iDocid, &p->pList, &p->nList
127908       );
127909       if( p->pList==0 ) *pbEof = 1;
127910     }else{
127911       p->bIgnore = 1;
127912     }
127913   }
127914 
127915   return rc;
127916 }
127917 
127918 
127919 /*
127920 ** The phrase iterator passed as the second argument:
127921 **
127922 **   * features at least one token that uses an incremental doclist, and 
127923 **
127924 **   * does not contain any deferred tokens.
127925 **
127926 ** Advance it to the next matching documnent in the database and populate
127927 ** the Fts3Doclist.pList and nList fields. 
127928 **
127929 ** If there is no "next" entry and no error occurs, then *pbEof is set to
127930 ** 1 before returning. Otherwise, if no error occurs and the iterator is
127931 ** successfully advanced, *pbEof is set to 0.
127932 **
127933 ** If an error occurs, return an SQLite error code. Otherwise, return 
127934 ** SQLITE_OK.
127935 */
127936 static int fts3EvalIncrPhraseNext(
127937   Fts3Cursor *pCsr,               /* FTS Cursor handle */
127938   Fts3Phrase *p,                  /* Phrase object to advance to next docid */
127939   u8 *pbEof                       /* OUT: Set to 1 if EOF */
127940 ){
127941   int rc = SQLITE_OK;
127942   Fts3Doclist *pDL = &p->doclist;
127943   Fts3Table *pTab = (Fts3Table *)pCsr->base.pVtab;
127944   u8 bEof = 0;
127945 
127946   /* This is only called if it is guaranteed that the phrase has at least
127947   ** one incremental token. In which case the bIncr flag is set. */
127948   assert( p->bIncr==1 );
127949 
127950   if( p->nToken==1 && p->bIncr ){
127951     rc = sqlite3Fts3MsrIncrNext(pTab, p->aToken[0].pSegcsr, 
127952         &pDL->iDocid, &pDL->pList, &pDL->nList
127953     );
127954     if( pDL->pList==0 ) bEof = 1;
127955   }else{
127956     int bDescDoclist = pCsr->bDesc;
127957     struct TokenDoclist a[MAX_INCR_PHRASE_TOKENS];
127958 
127959     memset(a, 0, sizeof(a));
127960     assert( p->nToken<=MAX_INCR_PHRASE_TOKENS );
127961     assert( p->iDoclistToken<MAX_INCR_PHRASE_TOKENS );
127962 
127963     while( bEof==0 ){
127964       int bMaxSet = 0;
127965       sqlite3_int64 iMax = 0;     /* Largest docid for all iterators */
127966       int i;                      /* Used to iterate through tokens */
127967 
127968       /* Advance the iterator for each token in the phrase once. */
127969       for(i=0; rc==SQLITE_OK && i<p->nToken && bEof==0; i++){
127970         rc = incrPhraseTokenNext(pTab, p, i, &a[i], &bEof);
127971         if( a[i].bIgnore==0 && (bMaxSet==0 || DOCID_CMP(iMax, a[i].iDocid)<0) ){
127972           iMax = a[i].iDocid;
127973           bMaxSet = 1;
127974         }
127975       }
127976       assert( rc!=SQLITE_OK || a[p->nToken-1].bIgnore==0 );
127977       assert( rc!=SQLITE_OK || bMaxSet );
127978 
127979       /* Keep advancing iterators until they all point to the same document */
127980       for(i=0; i<p->nToken; i++){
127981         while( rc==SQLITE_OK && bEof==0 
127982             && a[i].bIgnore==0 && DOCID_CMP(a[i].iDocid, iMax)<0 
127983         ){
127984           rc = incrPhraseTokenNext(pTab, p, i, &a[i], &bEof);
127985           if( DOCID_CMP(a[i].iDocid, iMax)>0 ){
127986             iMax = a[i].iDocid;
127987             i = 0;
127988           }
127989         }
127990       }
127991 
127992       /* Check if the current entries really are a phrase match */
127993       if( bEof==0 ){
127994         int nList = 0;
127995         int nByte = a[p->nToken-1].nList;
127996         char *aDoclist = sqlite3_malloc(nByte+1);
127997         if( !aDoclist ) return SQLITE_NOMEM;
127998         memcpy(aDoclist, a[p->nToken-1].pList, nByte+1);
127999 
128000         for(i=0; i<(p->nToken-1); i++){
128001           if( a[i].bIgnore==0 ){
128002             char *pL = a[i].pList;
128003             char *pR = aDoclist;
128004             char *pOut = aDoclist;
128005             int nDist = p->nToken-1-i;
128006             int res = fts3PoslistPhraseMerge(&pOut, nDist, 0, 1, &pL, &pR);
128007             if( res==0 ) break;
128008             nList = (int)(pOut - aDoclist);
128009           }
128010         }
128011         if( i==(p->nToken-1) ){
128012           pDL->iDocid = iMax;
128013           pDL->pList = aDoclist;
128014           pDL->nList = nList;
128015           pDL->bFreeList = 1;
128016           break;
128017         }
128018         sqlite3_free(aDoclist);
128019       }
128020     }
128021   }
128022 
128023   *pbEof = bEof;
128024   return rc;
128025 }
128026 
128027 /*
128028 ** Attempt to move the phrase iterator to point to the next matching docid. 
128029 ** If an error occurs, return an SQLite error code. Otherwise, return 
128030 ** SQLITE_OK.
128031 **
128032 ** If there is no "next" entry and no error occurs, then *pbEof is set to
128033 ** 1 before returning. Otherwise, if no error occurs and the iterator is
128034 ** successfully advanced, *pbEof is set to 0.
128035 */
128036 static int fts3EvalPhraseNext(
128037   Fts3Cursor *pCsr,               /* FTS Cursor handle */
128038   Fts3Phrase *p,                  /* Phrase object to advance to next docid */
128039   u8 *pbEof                       /* OUT: Set to 1 if EOF */
128040 ){
128041   int rc = SQLITE_OK;
128042   Fts3Doclist *pDL = &p->doclist;
128043   Fts3Table *pTab = (Fts3Table *)pCsr->base.pVtab;
128044 
128045   if( p->bIncr ){
128046     rc = fts3EvalIncrPhraseNext(pCsr, p, pbEof);
128047   }else if( pCsr->bDesc!=pTab->bDescIdx && pDL->nAll ){
128048     sqlite3Fts3DoclistPrev(pTab->bDescIdx, pDL->aAll, pDL->nAll, 
128049         &pDL->pNextDocid, &pDL->iDocid, &pDL->nList, pbEof
128050     );
128051     pDL->pList = pDL->pNextDocid;
128052   }else{
128053     fts3EvalDlPhraseNext(pTab, pDL, pbEof);
128054   }
128055 
128056   return rc;
128057 }
128058 
128059 /*
128060 **
128061 ** If *pRc is not SQLITE_OK when this function is called, it is a no-op.
128062 ** Otherwise, fts3EvalPhraseStart() is called on all phrases within the
128063 ** expression. Also the Fts3Expr.bDeferred variable is set to true for any
128064 ** expressions for which all descendent tokens are deferred.
128065 **
128066 ** If parameter bOptOk is zero, then it is guaranteed that the
128067 ** Fts3Phrase.doclist.aAll/nAll variables contain the entire doclist for
128068 ** each phrase in the expression (subject to deferred token processing).
128069 ** Or, if bOptOk is non-zero, then one or more tokens within the expression
128070 ** may be loaded incrementally, meaning doclist.aAll/nAll is not available.
128071 **
128072 ** If an error occurs within this function, *pRc is set to an SQLite error
128073 ** code before returning.
128074 */
128075 static void fts3EvalStartReaders(
128076   Fts3Cursor *pCsr,               /* FTS Cursor handle */
128077   Fts3Expr *pExpr,                /* Expression to initialize phrases in */
128078   int *pRc                        /* IN/OUT: Error code */
128079 ){
128080   if( pExpr && SQLITE_OK==*pRc ){
128081     if( pExpr->eType==FTSQUERY_PHRASE ){
128082       int i;
128083       int nToken = pExpr->pPhrase->nToken;
128084       for(i=0; i<nToken; i++){
128085         if( pExpr->pPhrase->aToken[i].pDeferred==0 ) break;
128086       }
128087       pExpr->bDeferred = (i==nToken);
128088       *pRc = fts3EvalPhraseStart(pCsr, 1, pExpr->pPhrase);
128089     }else{
128090       fts3EvalStartReaders(pCsr, pExpr->pLeft, pRc);
128091       fts3EvalStartReaders(pCsr, pExpr->pRight, pRc);
128092       pExpr->bDeferred = (pExpr->pLeft->bDeferred && pExpr->pRight->bDeferred);
128093     }
128094   }
128095 }
128096 
128097 /*
128098 ** An array of the following structures is assembled as part of the process
128099 ** of selecting tokens to defer before the query starts executing (as part
128100 ** of the xFilter() method). There is one element in the array for each
128101 ** token in the FTS expression.
128102 **
128103 ** Tokens are divided into AND/NEAR clusters. All tokens in a cluster belong
128104 ** to phrases that are connected only by AND and NEAR operators (not OR or
128105 ** NOT). When determining tokens to defer, each AND/NEAR cluster is considered
128106 ** separately. The root of a tokens AND/NEAR cluster is stored in 
128107 ** Fts3TokenAndCost.pRoot.
128108 */
128109 typedef struct Fts3TokenAndCost Fts3TokenAndCost;
128110 struct Fts3TokenAndCost {
128111   Fts3Phrase *pPhrase;            /* The phrase the token belongs to */
128112   int iToken;                     /* Position of token in phrase */
128113   Fts3PhraseToken *pToken;        /* The token itself */
128114   Fts3Expr *pRoot;                /* Root of NEAR/AND cluster */
128115   int nOvfl;                      /* Number of overflow pages to load doclist */
128116   int iCol;                       /* The column the token must match */
128117 };
128118 
128119 /*
128120 ** This function is used to populate an allocated Fts3TokenAndCost array.
128121 **
128122 ** If *pRc is not SQLITE_OK when this function is called, it is a no-op.
128123 ** Otherwise, if an error occurs during execution, *pRc is set to an
128124 ** SQLite error code.
128125 */
128126 static void fts3EvalTokenCosts(
128127   Fts3Cursor *pCsr,               /* FTS Cursor handle */
128128   Fts3Expr *pRoot,                /* Root of current AND/NEAR cluster */
128129   Fts3Expr *pExpr,                /* Expression to consider */
128130   Fts3TokenAndCost **ppTC,        /* Write new entries to *(*ppTC)++ */
128131   Fts3Expr ***ppOr,               /* Write new OR root to *(*ppOr)++ */
128132   int *pRc                        /* IN/OUT: Error code */
128133 ){
128134   if( *pRc==SQLITE_OK ){
128135     if( pExpr->eType==FTSQUERY_PHRASE ){
128136       Fts3Phrase *pPhrase = pExpr->pPhrase;
128137       int i;
128138       for(i=0; *pRc==SQLITE_OK && i<pPhrase->nToken; i++){
128139         Fts3TokenAndCost *pTC = (*ppTC)++;
128140         pTC->pPhrase = pPhrase;
128141         pTC->iToken = i;
128142         pTC->pRoot = pRoot;
128143         pTC->pToken = &pPhrase->aToken[i];
128144         pTC->iCol = pPhrase->iColumn;
128145         *pRc = sqlite3Fts3MsrOvfl(pCsr, pTC->pToken->pSegcsr, &pTC->nOvfl);
128146       }
128147     }else if( pExpr->eType!=FTSQUERY_NOT ){
128148       assert( pExpr->eType==FTSQUERY_OR
128149            || pExpr->eType==FTSQUERY_AND
128150            || pExpr->eType==FTSQUERY_NEAR
128151       );
128152       assert( pExpr->pLeft && pExpr->pRight );
128153       if( pExpr->eType==FTSQUERY_OR ){
128154         pRoot = pExpr->pLeft;
128155         **ppOr = pRoot;
128156         (*ppOr)++;
128157       }
128158       fts3EvalTokenCosts(pCsr, pRoot, pExpr->pLeft, ppTC, ppOr, pRc);
128159       if( pExpr->eType==FTSQUERY_OR ){
128160         pRoot = pExpr->pRight;
128161         **ppOr = pRoot;
128162         (*ppOr)++;
128163       }
128164       fts3EvalTokenCosts(pCsr, pRoot, pExpr->pRight, ppTC, ppOr, pRc);
128165     }
128166   }
128167 }
128168 
128169 /*
128170 ** Determine the average document (row) size in pages. If successful,
128171 ** write this value to *pnPage and return SQLITE_OK. Otherwise, return
128172 ** an SQLite error code.
128173 **
128174 ** The average document size in pages is calculated by first calculating 
128175 ** determining the average size in bytes, B. If B is less than the amount
128176 ** of data that will fit on a single leaf page of an intkey table in
128177 ** this database, then the average docsize is 1. Otherwise, it is 1 plus
128178 ** the number of overflow pages consumed by a record B bytes in size.
128179 */
128180 static int fts3EvalAverageDocsize(Fts3Cursor *pCsr, int *pnPage){
128181   if( pCsr->nRowAvg==0 ){
128182     /* The average document size, which is required to calculate the cost
128183     ** of each doclist, has not yet been determined. Read the required 
128184     ** data from the %_stat table to calculate it.
128185     **
128186     ** Entry 0 of the %_stat table is a blob containing (nCol+1) FTS3 
128187     ** varints, where nCol is the number of columns in the FTS3 table.
128188     ** The first varint is the number of documents currently stored in
128189     ** the table. The following nCol varints contain the total amount of
128190     ** data stored in all rows of each column of the table, from left
128191     ** to right.
128192     */
128193     int rc;
128194     Fts3Table *p = (Fts3Table*)pCsr->base.pVtab;
128195     sqlite3_stmt *pStmt;
128196     sqlite3_int64 nDoc = 0;
128197     sqlite3_int64 nByte = 0;
128198     const char *pEnd;
128199     const char *a;
128200 
128201     rc = sqlite3Fts3SelectDoctotal(p, &pStmt);
128202     if( rc!=SQLITE_OK ) return rc;
128203     a = sqlite3_column_blob(pStmt, 0);
128204     assert( a );
128205 
128206     pEnd = &a[sqlite3_column_bytes(pStmt, 0)];
128207     a += sqlite3Fts3GetVarint(a, &nDoc);
128208     while( a<pEnd ){
128209       a += sqlite3Fts3GetVarint(a, &nByte);
128210     }
128211     if( nDoc==0 || nByte==0 ){
128212       sqlite3_reset(pStmt);
128213       return FTS_CORRUPT_VTAB;
128214     }
128215 
128216     pCsr->nDoc = nDoc;
128217     pCsr->nRowAvg = (int)(((nByte / nDoc) + p->nPgsz) / p->nPgsz);
128218     assert( pCsr->nRowAvg>0 ); 
128219     rc = sqlite3_reset(pStmt);
128220     if( rc!=SQLITE_OK ) return rc;
128221   }
128222 
128223   *pnPage = pCsr->nRowAvg;
128224   return SQLITE_OK;
128225 }
128226 
128227 /*
128228 ** This function is called to select the tokens (if any) that will be 
128229 ** deferred. The array aTC[] has already been populated when this is
128230 ** called.
128231 **
128232 ** This function is called once for each AND/NEAR cluster in the 
128233 ** expression. Each invocation determines which tokens to defer within
128234 ** the cluster with root node pRoot. See comments above the definition
128235 ** of struct Fts3TokenAndCost for more details.
128236 **
128237 ** If no error occurs, SQLITE_OK is returned and sqlite3Fts3DeferToken()
128238 ** called on each token to defer. Otherwise, an SQLite error code is
128239 ** returned.
128240 */
128241 static int fts3EvalSelectDeferred(
128242   Fts3Cursor *pCsr,               /* FTS Cursor handle */
128243   Fts3Expr *pRoot,                /* Consider tokens with this root node */
128244   Fts3TokenAndCost *aTC,          /* Array of expression tokens and costs */
128245   int nTC                         /* Number of entries in aTC[] */
128246 ){
128247   Fts3Table *pTab = (Fts3Table *)pCsr->base.pVtab;
128248   int nDocSize = 0;               /* Number of pages per doc loaded */
128249   int rc = SQLITE_OK;             /* Return code */
128250   int ii;                         /* Iterator variable for various purposes */
128251   int nOvfl = 0;                  /* Total overflow pages used by doclists */
128252   int nToken = 0;                 /* Total number of tokens in cluster */
128253 
128254   int nMinEst = 0;                /* The minimum count for any phrase so far. */
128255   int nLoad4 = 1;                 /* (Phrases that will be loaded)^4. */
128256 
128257   /* Tokens are never deferred for FTS tables created using the content=xxx
128258   ** option. The reason being that it is not guaranteed that the content
128259   ** table actually contains the same data as the index. To prevent this from
128260   ** causing any problems, the deferred token optimization is completely
128261   ** disabled for content=xxx tables. */
128262   if( pTab->zContentTbl ){
128263     return SQLITE_OK;
128264   }
128265 
128266   /* Count the tokens in this AND/NEAR cluster. If none of the doclists
128267   ** associated with the tokens spill onto overflow pages, or if there is
128268   ** only 1 token, exit early. No tokens to defer in this case. */
128269   for(ii=0; ii<nTC; ii++){
128270     if( aTC[ii].pRoot==pRoot ){
128271       nOvfl += aTC[ii].nOvfl;
128272       nToken++;
128273     }
128274   }
128275   if( nOvfl==0 || nToken<2 ) return SQLITE_OK;
128276 
128277   /* Obtain the average docsize (in pages). */
128278   rc = fts3EvalAverageDocsize(pCsr, &nDocSize);
128279   assert( rc!=SQLITE_OK || nDocSize>0 );
128280 
128281 
128282   /* Iterate through all tokens in this AND/NEAR cluster, in ascending order 
128283   ** of the number of overflow pages that will be loaded by the pager layer 
128284   ** to retrieve the entire doclist for the token from the full-text index.
128285   ** Load the doclists for tokens that are either:
128286   **
128287   **   a. The cheapest token in the entire query (i.e. the one visited by the
128288   **      first iteration of this loop), or
128289   **
128290   **   b. Part of a multi-token phrase.
128291   **
128292   ** After each token doclist is loaded, merge it with the others from the
128293   ** same phrase and count the number of documents that the merged doclist
128294   ** contains. Set variable "nMinEst" to the smallest number of documents in 
128295   ** any phrase doclist for which 1 or more token doclists have been loaded.
128296   ** Let nOther be the number of other phrases for which it is certain that
128297   ** one or more tokens will not be deferred.
128298   **
128299   ** Then, for each token, defer it if loading the doclist would result in
128300   ** loading N or more overflow pages into memory, where N is computed as:
128301   **
128302   **    (nMinEst + 4^nOther - 1) / (4^nOther)
128303   */
128304   for(ii=0; ii<nToken && rc==SQLITE_OK; ii++){
128305     int iTC;                      /* Used to iterate through aTC[] array. */
128306     Fts3TokenAndCost *pTC = 0;    /* Set to cheapest remaining token. */
128307 
128308     /* Set pTC to point to the cheapest remaining token. */
128309     for(iTC=0; iTC<nTC; iTC++){
128310       if( aTC[iTC].pToken && aTC[iTC].pRoot==pRoot 
128311        && (!pTC || aTC[iTC].nOvfl<pTC->nOvfl) 
128312       ){
128313         pTC = &aTC[iTC];
128314       }
128315     }
128316     assert( pTC );
128317 
128318     if( ii && pTC->nOvfl>=((nMinEst+(nLoad4/4)-1)/(nLoad4/4))*nDocSize ){
128319       /* The number of overflow pages to load for this (and therefore all
128320       ** subsequent) tokens is greater than the estimated number of pages 
128321       ** that will be loaded if all subsequent tokens are deferred.
128322       */
128323       Fts3PhraseToken *pToken = pTC->pToken;
128324       rc = sqlite3Fts3DeferToken(pCsr, pToken, pTC->iCol);
128325       fts3SegReaderCursorFree(pToken->pSegcsr);
128326       pToken->pSegcsr = 0;
128327     }else{
128328       /* Set nLoad4 to the value of (4^nOther) for the next iteration of the
128329       ** for-loop. Except, limit the value to 2^24 to prevent it from 
128330       ** overflowing the 32-bit integer it is stored in. */
128331       if( ii<12 ) nLoad4 = nLoad4*4;
128332 
128333       if( ii==0 || (pTC->pPhrase->nToken>1 && ii!=nToken-1) ){
128334         /* Either this is the cheapest token in the entire query, or it is
128335         ** part of a multi-token phrase. Either way, the entire doclist will
128336         ** (eventually) be loaded into memory. It may as well be now. */
128337         Fts3PhraseToken *pToken = pTC->pToken;
128338         int nList = 0;
128339         char *pList = 0;
128340         rc = fts3TermSelect(pTab, pToken, pTC->iCol, &nList, &pList);
128341         assert( rc==SQLITE_OK || pList==0 );
128342         if( rc==SQLITE_OK ){
128343           int nCount;
128344           fts3EvalPhraseMergeToken(pTab, pTC->pPhrase, pTC->iToken,pList,nList);
128345           nCount = fts3DoclistCountDocids(
128346               pTC->pPhrase->doclist.aAll, pTC->pPhrase->doclist.nAll
128347           );
128348           if( ii==0 || nCount<nMinEst ) nMinEst = nCount;
128349         }
128350       }
128351     }
128352     pTC->pToken = 0;
128353   }
128354 
128355   return rc;
128356 }
128357 
128358 /*
128359 ** This function is called from within the xFilter method. It initializes
128360 ** the full-text query currently stored in pCsr->pExpr. To iterate through
128361 ** the results of a query, the caller does:
128362 **
128363 **    fts3EvalStart(pCsr);
128364 **    while( 1 ){
128365 **      fts3EvalNext(pCsr);
128366 **      if( pCsr->bEof ) break;
128367 **      ... return row pCsr->iPrevId to the caller ...
128368 **    }
128369 */
128370 static int fts3EvalStart(Fts3Cursor *pCsr){
128371   Fts3Table *pTab = (Fts3Table *)pCsr->base.pVtab;
128372   int rc = SQLITE_OK;
128373   int nToken = 0;
128374   int nOr = 0;
128375 
128376   /* Allocate a MultiSegReader for each token in the expression. */
128377   fts3EvalAllocateReaders(pCsr, pCsr->pExpr, &nToken, &nOr, &rc);
128378 
128379   /* Determine which, if any, tokens in the expression should be deferred. */
128380 #ifndef SQLITE_DISABLE_FTS4_DEFERRED
128381   if( rc==SQLITE_OK && nToken>1 && pTab->bFts4 ){
128382     Fts3TokenAndCost *aTC;
128383     Fts3Expr **apOr;
128384     aTC = (Fts3TokenAndCost *)sqlite3_malloc(
128385         sizeof(Fts3TokenAndCost) * nToken
128386       + sizeof(Fts3Expr *) * nOr * 2
128387     );
128388     apOr = (Fts3Expr **)&aTC[nToken];
128389 
128390     if( !aTC ){
128391       rc = SQLITE_NOMEM;
128392     }else{
128393       int ii;
128394       Fts3TokenAndCost *pTC = aTC;
128395       Fts3Expr **ppOr = apOr;
128396 
128397       fts3EvalTokenCosts(pCsr, 0, pCsr->pExpr, &pTC, &ppOr, &rc);
128398       nToken = (int)(pTC-aTC);
128399       nOr = (int)(ppOr-apOr);
128400 
128401       if( rc==SQLITE_OK ){
128402         rc = fts3EvalSelectDeferred(pCsr, 0, aTC, nToken);
128403         for(ii=0; rc==SQLITE_OK && ii<nOr; ii++){
128404           rc = fts3EvalSelectDeferred(pCsr, apOr[ii], aTC, nToken);
128405         }
128406       }
128407 
128408       sqlite3_free(aTC);
128409     }
128410   }
128411 #endif
128412 
128413   fts3EvalStartReaders(pCsr, pCsr->pExpr, &rc);
128414   return rc;
128415 }
128416 
128417 /*
128418 ** Invalidate the current position list for phrase pPhrase.
128419 */
128420 static void fts3EvalInvalidatePoslist(Fts3Phrase *pPhrase){
128421   if( pPhrase->doclist.bFreeList ){
128422     sqlite3_free(pPhrase->doclist.pList);
128423   }
128424   pPhrase->doclist.pList = 0;
128425   pPhrase->doclist.nList = 0;
128426   pPhrase->doclist.bFreeList = 0;
128427 }
128428 
128429 /*
128430 ** This function is called to edit the position list associated with
128431 ** the phrase object passed as the fifth argument according to a NEAR
128432 ** condition. For example:
128433 **
128434 **     abc NEAR/5 "def ghi"
128435 **
128436 ** Parameter nNear is passed the NEAR distance of the expression (5 in
128437 ** the example above). When this function is called, *paPoslist points to
128438 ** the position list, and *pnToken is the number of phrase tokens in, the
128439 ** phrase on the other side of the NEAR operator to pPhrase. For example,
128440 ** if pPhrase refers to the "def ghi" phrase, then *paPoslist points to
128441 ** the position list associated with phrase "abc".
128442 **
128443 ** All positions in the pPhrase position list that are not sufficiently
128444 ** close to a position in the *paPoslist position list are removed. If this
128445 ** leaves 0 positions, zero is returned. Otherwise, non-zero.
128446 **
128447 ** Before returning, *paPoslist is set to point to the position lsit 
128448 ** associated with pPhrase. And *pnToken is set to the number of tokens in
128449 ** pPhrase.
128450 */
128451 static int fts3EvalNearTrim(
128452   int nNear,                      /* NEAR distance. As in "NEAR/nNear". */
128453   char *aTmp,                     /* Temporary space to use */
128454   char **paPoslist,               /* IN/OUT: Position list */
128455   int *pnToken,                   /* IN/OUT: Tokens in phrase of *paPoslist */
128456   Fts3Phrase *pPhrase             /* The phrase object to trim the doclist of */
128457 ){
128458   int nParam1 = nNear + pPhrase->nToken;
128459   int nParam2 = nNear + *pnToken;
128460   int nNew;
128461   char *p2; 
128462   char *pOut; 
128463   int res;
128464 
128465   assert( pPhrase->doclist.pList );
128466 
128467   p2 = pOut = pPhrase->doclist.pList;
128468   res = fts3PoslistNearMerge(
128469     &pOut, aTmp, nParam1, nParam2, paPoslist, &p2
128470   );
128471   if( res ){
128472     nNew = (int)(pOut - pPhrase->doclist.pList) - 1;
128473     assert( pPhrase->doclist.pList[nNew]=='\0' );
128474     assert( nNew<=pPhrase->doclist.nList && nNew>0 );
128475     memset(&pPhrase->doclist.pList[nNew], 0, pPhrase->doclist.nList - nNew);
128476     pPhrase->doclist.nList = nNew;
128477     *paPoslist = pPhrase->doclist.pList;
128478     *pnToken = pPhrase->nToken;
128479   }
128480 
128481   return res;
128482 }
128483 
128484 /*
128485 ** This function is a no-op if *pRc is other than SQLITE_OK when it is called.
128486 ** Otherwise, it advances the expression passed as the second argument to
128487 ** point to the next matching row in the database. Expressions iterate through
128488 ** matching rows in docid order. Ascending order if Fts3Cursor.bDesc is zero,
128489 ** or descending if it is non-zero.
128490 **
128491 ** If an error occurs, *pRc is set to an SQLite error code. Otherwise, if
128492 ** successful, the following variables in pExpr are set:
128493 **
128494 **   Fts3Expr.bEof                (non-zero if EOF - there is no next row)
128495 **   Fts3Expr.iDocid              (valid if bEof==0. The docid of the next row)
128496 **
128497 ** If the expression is of type FTSQUERY_PHRASE, and the expression is not
128498 ** at EOF, then the following variables are populated with the position list
128499 ** for the phrase for the visited row:
128500 **
128501 **   FTs3Expr.pPhrase->doclist.nList        (length of pList in bytes)
128502 **   FTs3Expr.pPhrase->doclist.pList        (pointer to position list)
128503 **
128504 ** It says above that this function advances the expression to the next
128505 ** matching row. This is usually true, but there are the following exceptions:
128506 **
128507 **   1. Deferred tokens are not taken into account. If a phrase consists
128508 **      entirely of deferred tokens, it is assumed to match every row in
128509 **      the db. In this case the position-list is not populated at all. 
128510 **
128511 **      Or, if a phrase contains one or more deferred tokens and one or
128512 **      more non-deferred tokens, then the expression is advanced to the 
128513 **      next possible match, considering only non-deferred tokens. In other
128514 **      words, if the phrase is "A B C", and "B" is deferred, the expression
128515 **      is advanced to the next row that contains an instance of "A * C", 
128516 **      where "*" may match any single token. The position list in this case
128517 **      is populated as for "A * C" before returning.
128518 **
128519 **   2. NEAR is treated as AND. If the expression is "x NEAR y", it is 
128520 **      advanced to point to the next row that matches "x AND y".
128521 ** 
128522 ** See fts3EvalTestDeferredAndNear() for details on testing if a row is
128523 ** really a match, taking into account deferred tokens and NEAR operators.
128524 */
128525 static void fts3EvalNextRow(
128526   Fts3Cursor *pCsr,               /* FTS Cursor handle */
128527   Fts3Expr *pExpr,                /* Expr. to advance to next matching row */
128528   int *pRc                        /* IN/OUT: Error code */
128529 ){
128530   if( *pRc==SQLITE_OK ){
128531     int bDescDoclist = pCsr->bDesc;         /* Used by DOCID_CMP() macro */
128532     assert( pExpr->bEof==0 );
128533     pExpr->bStart = 1;
128534 
128535     switch( pExpr->eType ){
128536       case FTSQUERY_NEAR:
128537       case FTSQUERY_AND: {
128538         Fts3Expr *pLeft = pExpr->pLeft;
128539         Fts3Expr *pRight = pExpr->pRight;
128540         assert( !pLeft->bDeferred || !pRight->bDeferred );
128541 
128542         if( pLeft->bDeferred ){
128543           /* LHS is entirely deferred. So we assume it matches every row.
128544           ** Advance the RHS iterator to find the next row visited. */
128545           fts3EvalNextRow(pCsr, pRight, pRc);
128546           pExpr->iDocid = pRight->iDocid;
128547           pExpr->bEof = pRight->bEof;
128548         }else if( pRight->bDeferred ){
128549           /* RHS is entirely deferred. So we assume it matches every row.
128550           ** Advance the LHS iterator to find the next row visited. */
128551           fts3EvalNextRow(pCsr, pLeft, pRc);
128552           pExpr->iDocid = pLeft->iDocid;
128553           pExpr->bEof = pLeft->bEof;
128554         }else{
128555           /* Neither the RHS or LHS are deferred. */
128556           fts3EvalNextRow(pCsr, pLeft, pRc);
128557           fts3EvalNextRow(pCsr, pRight, pRc);
128558           while( !pLeft->bEof && !pRight->bEof && *pRc==SQLITE_OK ){
128559             sqlite3_int64 iDiff = DOCID_CMP(pLeft->iDocid, pRight->iDocid);
128560             if( iDiff==0 ) break;
128561             if( iDiff<0 ){
128562               fts3EvalNextRow(pCsr, pLeft, pRc);
128563             }else{
128564               fts3EvalNextRow(pCsr, pRight, pRc);
128565             }
128566           }
128567           pExpr->iDocid = pLeft->iDocid;
128568           pExpr->bEof = (pLeft->bEof || pRight->bEof);
128569         }
128570         break;
128571       }
128572   
128573       case FTSQUERY_OR: {
128574         Fts3Expr *pLeft = pExpr->pLeft;
128575         Fts3Expr *pRight = pExpr->pRight;
128576         sqlite3_int64 iCmp = DOCID_CMP(pLeft->iDocid, pRight->iDocid);
128577 
128578         assert( pLeft->bStart || pLeft->iDocid==pRight->iDocid );
128579         assert( pRight->bStart || pLeft->iDocid==pRight->iDocid );
128580 
128581         if( pRight->bEof || (pLeft->bEof==0 && iCmp<0) ){
128582           fts3EvalNextRow(pCsr, pLeft, pRc);
128583         }else if( pLeft->bEof || (pRight->bEof==0 && iCmp>0) ){
128584           fts3EvalNextRow(pCsr, pRight, pRc);
128585         }else{
128586           fts3EvalNextRow(pCsr, pLeft, pRc);
128587           fts3EvalNextRow(pCsr, pRight, pRc);
128588         }
128589 
128590         pExpr->bEof = (pLeft->bEof && pRight->bEof);
128591         iCmp = DOCID_CMP(pLeft->iDocid, pRight->iDocid);
128592         if( pRight->bEof || (pLeft->bEof==0 &&  iCmp<0) ){
128593           pExpr->iDocid = pLeft->iDocid;
128594         }else{
128595           pExpr->iDocid = pRight->iDocid;
128596         }
128597 
128598         break;
128599       }
128600 
128601       case FTSQUERY_NOT: {
128602         Fts3Expr *pLeft = pExpr->pLeft;
128603         Fts3Expr *pRight = pExpr->pRight;
128604 
128605         if( pRight->bStart==0 ){
128606           fts3EvalNextRow(pCsr, pRight, pRc);
128607           assert( *pRc!=SQLITE_OK || pRight->bStart );
128608         }
128609 
128610         fts3EvalNextRow(pCsr, pLeft, pRc);
128611         if( pLeft->bEof==0 ){
128612           while( !*pRc 
128613               && !pRight->bEof 
128614               && DOCID_CMP(pLeft->iDocid, pRight->iDocid)>0 
128615           ){
128616             fts3EvalNextRow(pCsr, pRight, pRc);
128617           }
128618         }
128619         pExpr->iDocid = pLeft->iDocid;
128620         pExpr->bEof = pLeft->bEof;
128621         break;
128622       }
128623 
128624       default: {
128625         Fts3Phrase *pPhrase = pExpr->pPhrase;
128626         fts3EvalInvalidatePoslist(pPhrase);
128627         *pRc = fts3EvalPhraseNext(pCsr, pPhrase, &pExpr->bEof);
128628         pExpr->iDocid = pPhrase->doclist.iDocid;
128629         break;
128630       }
128631     }
128632   }
128633 }
128634 
128635 /*
128636 ** If *pRc is not SQLITE_OK, or if pExpr is not the root node of a NEAR
128637 ** cluster, then this function returns 1 immediately.
128638 **
128639 ** Otherwise, it checks if the current row really does match the NEAR 
128640 ** expression, using the data currently stored in the position lists 
128641 ** (Fts3Expr->pPhrase.doclist.pList/nList) for each phrase in the expression. 
128642 **
128643 ** If the current row is a match, the position list associated with each
128644 ** phrase in the NEAR expression is edited in place to contain only those
128645 ** phrase instances sufficiently close to their peers to satisfy all NEAR
128646 ** constraints. In this case it returns 1. If the NEAR expression does not 
128647 ** match the current row, 0 is returned. The position lists may or may not
128648 ** be edited if 0 is returned.
128649 */
128650 static int fts3EvalNearTest(Fts3Expr *pExpr, int *pRc){
128651   int res = 1;
128652 
128653   /* The following block runs if pExpr is the root of a NEAR query.
128654   ** For example, the query:
128655   **
128656   **         "w" NEAR "x" NEAR "y" NEAR "z"
128657   **
128658   ** which is represented in tree form as:
128659   **
128660   **                               |
128661   **                          +--NEAR--+      <-- root of NEAR query
128662   **                          |        |
128663   **                     +--NEAR--+   "z"
128664   **                     |        |
128665   **                +--NEAR--+   "y"
128666   **                |        |
128667   **               "w"      "x"
128668   **
128669   ** The right-hand child of a NEAR node is always a phrase. The 
128670   ** left-hand child may be either a phrase or a NEAR node. There are
128671   ** no exceptions to this - it's the way the parser in fts3_expr.c works.
128672   */
128673   if( *pRc==SQLITE_OK 
128674    && pExpr->eType==FTSQUERY_NEAR 
128675    && pExpr->bEof==0
128676    && (pExpr->pParent==0 || pExpr->pParent->eType!=FTSQUERY_NEAR)
128677   ){
128678     Fts3Expr *p; 
128679     int nTmp = 0;                 /* Bytes of temp space */
128680     char *aTmp;                   /* Temp space for PoslistNearMerge() */
128681 
128682     /* Allocate temporary working space. */
128683     for(p=pExpr; p->pLeft; p=p->pLeft){
128684       nTmp += p->pRight->pPhrase->doclist.nList;
128685     }
128686     nTmp += p->pPhrase->doclist.nList;
128687     if( nTmp==0 ){
128688       res = 0;
128689     }else{
128690       aTmp = sqlite3_malloc(nTmp*2);
128691       if( !aTmp ){
128692         *pRc = SQLITE_NOMEM;
128693         res = 0;
128694       }else{
128695         char *aPoslist = p->pPhrase->doclist.pList;
128696         int nToken = p->pPhrase->nToken;
128697 
128698         for(p=p->pParent;res && p && p->eType==FTSQUERY_NEAR; p=p->pParent){
128699           Fts3Phrase *pPhrase = p->pRight->pPhrase;
128700           int nNear = p->nNear;
128701           res = fts3EvalNearTrim(nNear, aTmp, &aPoslist, &nToken, pPhrase);
128702         }
128703 
128704         aPoslist = pExpr->pRight->pPhrase->doclist.pList;
128705         nToken = pExpr->pRight->pPhrase->nToken;
128706         for(p=pExpr->pLeft; p && res; p=p->pLeft){
128707           int nNear;
128708           Fts3Phrase *pPhrase;
128709           assert( p->pParent && p->pParent->pLeft==p );
128710           nNear = p->pParent->nNear;
128711           pPhrase = (
128712               p->eType==FTSQUERY_NEAR ? p->pRight->pPhrase : p->pPhrase
128713               );
128714           res = fts3EvalNearTrim(nNear, aTmp, &aPoslist, &nToken, pPhrase);
128715         }
128716       }
128717 
128718       sqlite3_free(aTmp);
128719     }
128720   }
128721 
128722   return res;
128723 }
128724 
128725 /*
128726 ** This function is a helper function for fts3EvalTestDeferredAndNear().
128727 ** Assuming no error occurs or has occurred, It returns non-zero if the
128728 ** expression passed as the second argument matches the row that pCsr 
128729 ** currently points to, or zero if it does not.
128730 **
128731 ** If *pRc is not SQLITE_OK when this function is called, it is a no-op.
128732 ** If an error occurs during execution of this function, *pRc is set to 
128733 ** the appropriate SQLite error code. In this case the returned value is 
128734 ** undefined.
128735 */
128736 static int fts3EvalTestExpr(
128737   Fts3Cursor *pCsr,               /* FTS cursor handle */
128738   Fts3Expr *pExpr,                /* Expr to test. May or may not be root. */
128739   int *pRc                        /* IN/OUT: Error code */
128740 ){
128741   int bHit = 1;                   /* Return value */
128742   if( *pRc==SQLITE_OK ){
128743     switch( pExpr->eType ){
128744       case FTSQUERY_NEAR:
128745       case FTSQUERY_AND:
128746         bHit = (
128747             fts3EvalTestExpr(pCsr, pExpr->pLeft, pRc)
128748          && fts3EvalTestExpr(pCsr, pExpr->pRight, pRc)
128749          && fts3EvalNearTest(pExpr, pRc)
128750         );
128751 
128752         /* If the NEAR expression does not match any rows, zero the doclist for 
128753         ** all phrases involved in the NEAR. This is because the snippet(),
128754         ** offsets() and matchinfo() functions are not supposed to recognize 
128755         ** any instances of phrases that are part of unmatched NEAR queries. 
128756         ** For example if this expression:
128757         **
128758         **    ... MATCH 'a OR (b NEAR c)'
128759         **
128760         ** is matched against a row containing:
128761         **
128762         **        'a b d e'
128763         **
128764         ** then any snippet() should ony highlight the "a" term, not the "b"
128765         ** (as "b" is part of a non-matching NEAR clause).
128766         */
128767         if( bHit==0 
128768          && pExpr->eType==FTSQUERY_NEAR 
128769          && (pExpr->pParent==0 || pExpr->pParent->eType!=FTSQUERY_NEAR)
128770         ){
128771           Fts3Expr *p;
128772           for(p=pExpr; p->pPhrase==0; p=p->pLeft){
128773             if( p->pRight->iDocid==pCsr->iPrevId ){
128774               fts3EvalInvalidatePoslist(p->pRight->pPhrase);
128775             }
128776           }
128777           if( p->iDocid==pCsr->iPrevId ){
128778             fts3EvalInvalidatePoslist(p->pPhrase);
128779           }
128780         }
128781 
128782         break;
128783 
128784       case FTSQUERY_OR: {
128785         int bHit1 = fts3EvalTestExpr(pCsr, pExpr->pLeft, pRc);
128786         int bHit2 = fts3EvalTestExpr(pCsr, pExpr->pRight, pRc);
128787         bHit = bHit1 || bHit2;
128788         break;
128789       }
128790 
128791       case FTSQUERY_NOT:
128792         bHit = (
128793             fts3EvalTestExpr(pCsr, pExpr->pLeft, pRc)
128794          && !fts3EvalTestExpr(pCsr, pExpr->pRight, pRc)
128795         );
128796         break;
128797 
128798       default: {
128799 #ifndef SQLITE_DISABLE_FTS4_DEFERRED
128800         if( pCsr->pDeferred 
128801          && (pExpr->iDocid==pCsr->iPrevId || pExpr->bDeferred)
128802         ){
128803           Fts3Phrase *pPhrase = pExpr->pPhrase;
128804           assert( pExpr->bDeferred || pPhrase->doclist.bFreeList==0 );
128805           if( pExpr->bDeferred ){
128806             fts3EvalInvalidatePoslist(pPhrase);
128807           }
128808           *pRc = fts3EvalDeferredPhrase(pCsr, pPhrase);
128809           bHit = (pPhrase->doclist.pList!=0);
128810           pExpr->iDocid = pCsr->iPrevId;
128811         }else
128812 #endif
128813         {
128814           bHit = (pExpr->bEof==0 && pExpr->iDocid==pCsr->iPrevId);
128815         }
128816         break;
128817       }
128818     }
128819   }
128820   return bHit;
128821 }
128822 
128823 /*
128824 ** This function is called as the second part of each xNext operation when
128825 ** iterating through the results of a full-text query. At this point the
128826 ** cursor points to a row that matches the query expression, with the
128827 ** following caveats:
128828 **
128829 **   * Up until this point, "NEAR" operators in the expression have been
128830 **     treated as "AND".
128831 **
128832 **   * Deferred tokens have not yet been considered.
128833 **
128834 ** If *pRc is not SQLITE_OK when this function is called, it immediately
128835 ** returns 0. Otherwise, it tests whether or not after considering NEAR
128836 ** operators and deferred tokens the current row is still a match for the
128837 ** expression. It returns 1 if both of the following are true:
128838 **
128839 **   1. *pRc is SQLITE_OK when this function returns, and
128840 **
128841 **   2. After scanning the current FTS table row for the deferred tokens,
128842 **      it is determined that the row does *not* match the query.
128843 **
128844 ** Or, if no error occurs and it seems the current row does match the FTS
128845 ** query, return 0.
128846 */
128847 static int fts3EvalTestDeferredAndNear(Fts3Cursor *pCsr, int *pRc){
128848   int rc = *pRc;
128849   int bMiss = 0;
128850   if( rc==SQLITE_OK ){
128851 
128852     /* If there are one or more deferred tokens, load the current row into
128853     ** memory and scan it to determine the position list for each deferred
128854     ** token. Then, see if this row is really a match, considering deferred
128855     ** tokens and NEAR operators (neither of which were taken into account
128856     ** earlier, by fts3EvalNextRow()). 
128857     */
128858     if( pCsr->pDeferred ){
128859       rc = fts3CursorSeek(0, pCsr);
128860       if( rc==SQLITE_OK ){
128861         rc = sqlite3Fts3CacheDeferredDoclists(pCsr);
128862       }
128863     }
128864     bMiss = (0==fts3EvalTestExpr(pCsr, pCsr->pExpr, &rc));
128865 
128866     /* Free the position-lists accumulated for each deferred token above. */
128867     sqlite3Fts3FreeDeferredDoclists(pCsr);
128868     *pRc = rc;
128869   }
128870   return (rc==SQLITE_OK && bMiss);
128871 }
128872 
128873 /*
128874 ** Advance to the next document that matches the FTS expression in
128875 ** Fts3Cursor.pExpr.
128876 */
128877 static int fts3EvalNext(Fts3Cursor *pCsr){
128878   int rc = SQLITE_OK;             /* Return Code */
128879   Fts3Expr *pExpr = pCsr->pExpr;
128880   assert( pCsr->isEof==0 );
128881   if( pExpr==0 ){
128882     pCsr->isEof = 1;
128883   }else{
128884     do {
128885       if( pCsr->isRequireSeek==0 ){
128886         sqlite3_reset(pCsr->pStmt);
128887       }
128888       assert( sqlite3_data_count(pCsr->pStmt)==0 );
128889       fts3EvalNextRow(pCsr, pExpr, &rc);
128890       pCsr->isEof = pExpr->bEof;
128891       pCsr->isRequireSeek = 1;
128892       pCsr->isMatchinfoNeeded = 1;
128893       pCsr->iPrevId = pExpr->iDocid;
128894     }while( pCsr->isEof==0 && fts3EvalTestDeferredAndNear(pCsr, &rc) );
128895   }
128896 
128897   /* Check if the cursor is past the end of the docid range specified
128898   ** by Fts3Cursor.iMinDocid/iMaxDocid. If so, set the EOF flag.  */
128899   if( rc==SQLITE_OK && (
128900         (pCsr->bDesc==0 && pCsr->iPrevId>pCsr->iMaxDocid)
128901      || (pCsr->bDesc!=0 && pCsr->iPrevId<pCsr->iMinDocid)
128902   )){
128903     pCsr->isEof = 1;
128904   }
128905 
128906   return rc;
128907 }
128908 
128909 /*
128910 ** Restart interation for expression pExpr so that the next call to
128911 ** fts3EvalNext() visits the first row. Do not allow incremental 
128912 ** loading or merging of phrase doclists for this iteration.
128913 **
128914 ** If *pRc is other than SQLITE_OK when this function is called, it is
128915 ** a no-op. If an error occurs within this function, *pRc is set to an
128916 ** SQLite error code before returning.
128917 */
128918 static void fts3EvalRestart(
128919   Fts3Cursor *pCsr,
128920   Fts3Expr *pExpr,
128921   int *pRc
128922 ){
128923   if( pExpr && *pRc==SQLITE_OK ){
128924     Fts3Phrase *pPhrase = pExpr->pPhrase;
128925 
128926     if( pPhrase ){
128927       fts3EvalInvalidatePoslist(pPhrase);
128928       if( pPhrase->bIncr ){
128929         int i;
128930         for(i=0; i<pPhrase->nToken; i++){
128931           Fts3PhraseToken *pToken = &pPhrase->aToken[i];
128932           assert( pToken->pDeferred==0 );
128933           if( pToken->pSegcsr ){
128934             sqlite3Fts3MsrIncrRestart(pToken->pSegcsr);
128935           }
128936         }
128937         *pRc = fts3EvalPhraseStart(pCsr, 0, pPhrase);
128938       }
128939       pPhrase->doclist.pNextDocid = 0;
128940       pPhrase->doclist.iDocid = 0;
128941     }
128942 
128943     pExpr->iDocid = 0;
128944     pExpr->bEof = 0;
128945     pExpr->bStart = 0;
128946 
128947     fts3EvalRestart(pCsr, pExpr->pLeft, pRc);
128948     fts3EvalRestart(pCsr, pExpr->pRight, pRc);
128949   }
128950 }
128951 
128952 /*
128953 ** After allocating the Fts3Expr.aMI[] array for each phrase in the 
128954 ** expression rooted at pExpr, the cursor iterates through all rows matched
128955 ** by pExpr, calling this function for each row. This function increments
128956 ** the values in Fts3Expr.aMI[] according to the position-list currently
128957 ** found in Fts3Expr.pPhrase->doclist.pList for each of the phrase 
128958 ** expression nodes.
128959 */
128960 static void fts3EvalUpdateCounts(Fts3Expr *pExpr){
128961   if( pExpr ){
128962     Fts3Phrase *pPhrase = pExpr->pPhrase;
128963     if( pPhrase && pPhrase->doclist.pList ){
128964       int iCol = 0;
128965       char *p = pPhrase->doclist.pList;
128966 
128967       assert( *p );
128968       while( 1 ){
128969         u8 c = 0;
128970         int iCnt = 0;
128971         while( 0xFE & (*p | c) ){
128972           if( (c&0x80)==0 ) iCnt++;
128973           c = *p++ & 0x80;
128974         }
128975 
128976         /* aMI[iCol*3 + 1] = Number of occurrences
128977         ** aMI[iCol*3 + 2] = Number of rows containing at least one instance
128978         */
128979         pExpr->aMI[iCol*3 + 1] += iCnt;
128980         pExpr->aMI[iCol*3 + 2] += (iCnt>0);
128981         if( *p==0x00 ) break;
128982         p++;
128983         p += fts3GetVarint32(p, &iCol);
128984       }
128985     }
128986 
128987     fts3EvalUpdateCounts(pExpr->pLeft);
128988     fts3EvalUpdateCounts(pExpr->pRight);
128989   }
128990 }
128991 
128992 /*
128993 ** Expression pExpr must be of type FTSQUERY_PHRASE.
128994 **
128995 ** If it is not already allocated and populated, this function allocates and
128996 ** populates the Fts3Expr.aMI[] array for expression pExpr. If pExpr is part
128997 ** of a NEAR expression, then it also allocates and populates the same array
128998 ** for all other phrases that are part of the NEAR expression.
128999 **
129000 ** SQLITE_OK is returned if the aMI[] array is successfully allocated and
129001 ** populated. Otherwise, if an error occurs, an SQLite error code is returned.
129002 */
129003 static int fts3EvalGatherStats(
129004   Fts3Cursor *pCsr,               /* Cursor object */
129005   Fts3Expr *pExpr                 /* FTSQUERY_PHRASE expression */
129006 ){
129007   int rc = SQLITE_OK;             /* Return code */
129008 
129009   assert( pExpr->eType==FTSQUERY_PHRASE );
129010   if( pExpr->aMI==0 ){
129011     Fts3Table *pTab = (Fts3Table *)pCsr->base.pVtab;
129012     Fts3Expr *pRoot;                /* Root of NEAR expression */
129013     Fts3Expr *p;                    /* Iterator used for several purposes */
129014 
129015     sqlite3_int64 iPrevId = pCsr->iPrevId;
129016     sqlite3_int64 iDocid;
129017     u8 bEof;
129018 
129019     /* Find the root of the NEAR expression */
129020     pRoot = pExpr;
129021     while( pRoot->pParent && pRoot->pParent->eType==FTSQUERY_NEAR ){
129022       pRoot = pRoot->pParent;
129023     }
129024     iDocid = pRoot->iDocid;
129025     bEof = pRoot->bEof;
129026     assert( pRoot->bStart );
129027 
129028     /* Allocate space for the aMSI[] array of each FTSQUERY_PHRASE node */
129029     for(p=pRoot; p; p=p->pLeft){
129030       Fts3Expr *pE = (p->eType==FTSQUERY_PHRASE?p:p->pRight);
129031       assert( pE->aMI==0 );
129032       pE->aMI = (u32 *)sqlite3_malloc(pTab->nColumn * 3 * sizeof(u32));
129033       if( !pE->aMI ) return SQLITE_NOMEM;
129034       memset(pE->aMI, 0, pTab->nColumn * 3 * sizeof(u32));
129035     }
129036 
129037     fts3EvalRestart(pCsr, pRoot, &rc);
129038 
129039     while( pCsr->isEof==0 && rc==SQLITE_OK ){
129040 
129041       do {
129042         /* Ensure the %_content statement is reset. */
129043         if( pCsr->isRequireSeek==0 ) sqlite3_reset(pCsr->pStmt);
129044         assert( sqlite3_data_count(pCsr->pStmt)==0 );
129045 
129046         /* Advance to the next document */
129047         fts3EvalNextRow(pCsr, pRoot, &rc);
129048         pCsr->isEof = pRoot->bEof;
129049         pCsr->isRequireSeek = 1;
129050         pCsr->isMatchinfoNeeded = 1;
129051         pCsr->iPrevId = pRoot->iDocid;
129052       }while( pCsr->isEof==0 
129053            && pRoot->eType==FTSQUERY_NEAR 
129054            && fts3EvalTestDeferredAndNear(pCsr, &rc) 
129055       );
129056 
129057       if( rc==SQLITE_OK && pCsr->isEof==0 ){
129058         fts3EvalUpdateCounts(pRoot);
129059       }
129060     }
129061 
129062     pCsr->isEof = 0;
129063     pCsr->iPrevId = iPrevId;
129064 
129065     if( bEof ){
129066       pRoot->bEof = bEof;
129067     }else{
129068       /* Caution: pRoot may iterate through docids in ascending or descending
129069       ** order. For this reason, even though it seems more defensive, the 
129070       ** do loop can not be written:
129071       **
129072       **   do {...} while( pRoot->iDocid<iDocid && rc==SQLITE_OK );
129073       */
129074       fts3EvalRestart(pCsr, pRoot, &rc);
129075       do {
129076         fts3EvalNextRow(pCsr, pRoot, &rc);
129077         assert( pRoot->bEof==0 );
129078       }while( pRoot->iDocid!=iDocid && rc==SQLITE_OK );
129079       fts3EvalTestDeferredAndNear(pCsr, &rc);
129080     }
129081   }
129082   return rc;
129083 }
129084 
129085 /*
129086 ** This function is used by the matchinfo() module to query a phrase 
129087 ** expression node for the following information:
129088 **
129089 **   1. The total number of occurrences of the phrase in each column of 
129090 **      the FTS table (considering all rows), and
129091 **
129092 **   2. For each column, the number of rows in the table for which the
129093 **      column contains at least one instance of the phrase.
129094 **
129095 ** If no error occurs, SQLITE_OK is returned and the values for each column
129096 ** written into the array aiOut as follows:
129097 **
129098 **   aiOut[iCol*3 + 1] = Number of occurrences
129099 **   aiOut[iCol*3 + 2] = Number of rows containing at least one instance
129100 **
129101 ** Caveats:
129102 **
129103 **   * If a phrase consists entirely of deferred tokens, then all output 
129104 **     values are set to the number of documents in the table. In other
129105 **     words we assume that very common tokens occur exactly once in each 
129106 **     column of each row of the table.
129107 **
129108 **   * If a phrase contains some deferred tokens (and some non-deferred 
129109 **     tokens), count the potential occurrence identified by considering
129110 **     the non-deferred tokens instead of actual phrase occurrences.
129111 **
129112 **   * If the phrase is part of a NEAR expression, then only phrase instances
129113 **     that meet the NEAR constraint are included in the counts.
129114 */
129115 SQLITE_PRIVATE int sqlite3Fts3EvalPhraseStats(
129116   Fts3Cursor *pCsr,               /* FTS cursor handle */
129117   Fts3Expr *pExpr,                /* Phrase expression */
129118   u32 *aiOut                      /* Array to write results into (see above) */
129119 ){
129120   Fts3Table *pTab = (Fts3Table *)pCsr->base.pVtab;
129121   int rc = SQLITE_OK;
129122   int iCol;
129123 
129124   if( pExpr->bDeferred && pExpr->pParent->eType!=FTSQUERY_NEAR ){
129125     assert( pCsr->nDoc>0 );
129126     for(iCol=0; iCol<pTab->nColumn; iCol++){
129127       aiOut[iCol*3 + 1] = (u32)pCsr->nDoc;
129128       aiOut[iCol*3 + 2] = (u32)pCsr->nDoc;
129129     }
129130   }else{
129131     rc = fts3EvalGatherStats(pCsr, pExpr);
129132     if( rc==SQLITE_OK ){
129133       assert( pExpr->aMI );
129134       for(iCol=0; iCol<pTab->nColumn; iCol++){
129135         aiOut[iCol*3 + 1] = pExpr->aMI[iCol*3 + 1];
129136         aiOut[iCol*3 + 2] = pExpr->aMI[iCol*3 + 2];
129137       }
129138     }
129139   }
129140 
129141   return rc;
129142 }
129143 
129144 /*
129145 ** The expression pExpr passed as the second argument to this function
129146 ** must be of type FTSQUERY_PHRASE. 
129147 **
129148 ** The returned value is either NULL or a pointer to a buffer containing
129149 ** a position-list indicating the occurrences of the phrase in column iCol
129150 ** of the current row. 
129151 **
129152 ** More specifically, the returned buffer contains 1 varint for each 
129153 ** occurrence of the phrase in the column, stored using the normal (delta+2) 
129154 ** compression and is terminated by either an 0x01 or 0x00 byte. For example,
129155 ** if the requested column contains "a b X c d X X" and the position-list
129156 ** for 'X' is requested, the buffer returned may contain:
129157 **
129158 **     0x04 0x05 0x03 0x01   or   0x04 0x05 0x03 0x00
129159 **
129160 ** This function works regardless of whether or not the phrase is deferred,
129161 ** incremental, or neither.
129162 */
129163 SQLITE_PRIVATE int sqlite3Fts3EvalPhrasePoslist(
129164   Fts3Cursor *pCsr,               /* FTS3 cursor object */
129165   Fts3Expr *pExpr,                /* Phrase to return doclist for */
129166   int iCol,                       /* Column to return position list for */
129167   char **ppOut                    /* OUT: Pointer to position list */
129168 ){
129169   Fts3Phrase *pPhrase = pExpr->pPhrase;
129170   Fts3Table *pTab = (Fts3Table *)pCsr->base.pVtab;
129171   char *pIter;
129172   int iThis;
129173   sqlite3_int64 iDocid;
129174 
129175   /* If this phrase is applies specifically to some column other than 
129176   ** column iCol, return a NULL pointer.  */
129177   *ppOut = 0;
129178   assert( iCol>=0 && iCol<pTab->nColumn );
129179   if( (pPhrase->iColumn<pTab->nColumn && pPhrase->iColumn!=iCol) ){
129180     return SQLITE_OK;
129181   }
129182 
129183   iDocid = pExpr->iDocid;
129184   pIter = pPhrase->doclist.pList;
129185   if( iDocid!=pCsr->iPrevId || pExpr->bEof ){
129186     int bDescDoclist = pTab->bDescIdx;      /* For DOCID_CMP macro */
129187     int iMul;                     /* +1 if csr dir matches index dir, else -1 */
129188     int bOr = 0;
129189     u8 bEof = 0;
129190     u8 bTreeEof = 0;
129191     Fts3Expr *p;                  /* Used to iterate from pExpr to root */
129192     Fts3Expr *pNear;              /* Most senior NEAR ancestor (or pExpr) */
129193 
129194     /* Check if this phrase descends from an OR expression node. If not, 
129195     ** return NULL. Otherwise, the entry that corresponds to docid 
129196     ** pCsr->iPrevId may lie earlier in the doclist buffer. Or, if the
129197     ** tree that the node is part of has been marked as EOF, but the node
129198     ** itself is not EOF, then it may point to an earlier entry. */
129199     pNear = pExpr;
129200     for(p=pExpr->pParent; p; p=p->pParent){
129201       if( p->eType==FTSQUERY_OR ) bOr = 1;
129202       if( p->eType==FTSQUERY_NEAR ) pNear = p;
129203       if( p->bEof ) bTreeEof = 1;
129204     }
129205     if( bOr==0 ) return SQLITE_OK;
129206 
129207     /* This is the descendent of an OR node. In this case we cannot use
129208     ** an incremental phrase. Load the entire doclist for the phrase
129209     ** into memory in this case.  */
129210     if( pPhrase->bIncr ){
129211       int rc = SQLITE_OK;
129212       int bEofSave = pExpr->bEof;
129213       fts3EvalRestart(pCsr, pExpr, &rc);
129214       while( rc==SQLITE_OK && !pExpr->bEof ){
129215         fts3EvalNextRow(pCsr, pExpr, &rc);
129216         if( bEofSave==0 && pExpr->iDocid==iDocid ) break;
129217       }
129218       pIter = pPhrase->doclist.pList;
129219       assert( rc!=SQLITE_OK || pPhrase->bIncr==0 );
129220       if( rc!=SQLITE_OK ) return rc;
129221     }
129222     
129223     iMul = ((pCsr->bDesc==bDescDoclist) ? 1 : -1);
129224     while( bTreeEof==1 
129225         && pNear->bEof==0
129226         && (DOCID_CMP(pNear->iDocid, pCsr->iPrevId) * iMul)<0
129227     ){
129228       int rc = SQLITE_OK;
129229       fts3EvalNextRow(pCsr, pExpr, &rc);
129230       if( rc!=SQLITE_OK ) return rc;
129231       iDocid = pExpr->iDocid;
129232       pIter = pPhrase->doclist.pList;
129233     }
129234 
129235     bEof = (pPhrase->doclist.nAll==0);
129236     assert( bDescDoclist==0 || bDescDoclist==1 );
129237     assert( pCsr->bDesc==0 || pCsr->bDesc==1 );
129238 
129239     if( bEof==0 ){
129240       if( pCsr->bDesc==bDescDoclist ){
129241         int dummy;
129242         if( pNear->bEof ){
129243           /* This expression is already at EOF. So position it to point to the
129244           ** last entry in the doclist at pPhrase->doclist.aAll[]. Variable
129245           ** iDocid is already set for this entry, so all that is required is
129246           ** to set pIter to point to the first byte of the last position-list
129247           ** in the doclist. 
129248           **
129249           ** It would also be correct to set pIter and iDocid to zero. In
129250           ** this case, the first call to sqltie3Fts4DoclistPrev() below
129251           ** would also move the iterator to point to the last entry in the 
129252           ** doclist. However, this is expensive, as to do so it has to 
129253           ** iterate through the entire doclist from start to finish (since
129254           ** it does not know the docid for the last entry).  */
129255           pIter = &pPhrase->doclist.aAll[pPhrase->doclist.nAll-1];
129256           fts3ReversePoslist(pPhrase->doclist.aAll, &pIter);
129257         }
129258         while( (pIter==0 || DOCID_CMP(iDocid, pCsr->iPrevId)>0 ) && bEof==0 ){
129259           sqlite3Fts3DoclistPrev(
129260               bDescDoclist, pPhrase->doclist.aAll, pPhrase->doclist.nAll, 
129261               &pIter, &iDocid, &dummy, &bEof
129262           );
129263         }
129264       }else{
129265         if( pNear->bEof ){
129266           pIter = 0;
129267           iDocid = 0;
129268         }
129269         while( (pIter==0 || DOCID_CMP(iDocid, pCsr->iPrevId)<0 ) && bEof==0 ){
129270           sqlite3Fts3DoclistNext(
129271               bDescDoclist, pPhrase->doclist.aAll, pPhrase->doclist.nAll, 
129272               &pIter, &iDocid, &bEof
129273           );
129274         }
129275       }
129276     }
129277 
129278     if( bEof || iDocid!=pCsr->iPrevId ) pIter = 0;
129279   }
129280   if( pIter==0 ) return SQLITE_OK;
129281 
129282   if( *pIter==0x01 ){
129283     pIter++;
129284     pIter += fts3GetVarint32(pIter, &iThis);
129285   }else{
129286     iThis = 0;
129287   }
129288   while( iThis<iCol ){
129289     fts3ColumnlistCopy(0, &pIter);
129290     if( *pIter==0x00 ) return 0;
129291     pIter++;
129292     pIter += fts3GetVarint32(pIter, &iThis);
129293   }
129294 
129295   *ppOut = ((iCol==iThis)?pIter:0);
129296   return SQLITE_OK;
129297 }
129298 
129299 /*
129300 ** Free all components of the Fts3Phrase structure that were allocated by
129301 ** the eval module. Specifically, this means to free:
129302 **
129303 **   * the contents of pPhrase->doclist, and
129304 **   * any Fts3MultiSegReader objects held by phrase tokens.
129305 */
129306 SQLITE_PRIVATE void sqlite3Fts3EvalPhraseCleanup(Fts3Phrase *pPhrase){
129307   if( pPhrase ){
129308     int i;
129309     sqlite3_free(pPhrase->doclist.aAll);
129310     fts3EvalInvalidatePoslist(pPhrase);
129311     memset(&pPhrase->doclist, 0, sizeof(Fts3Doclist));
129312     for(i=0; i<pPhrase->nToken; i++){
129313       fts3SegReaderCursorFree(pPhrase->aToken[i].pSegcsr);
129314       pPhrase->aToken[i].pSegcsr = 0;
129315     }
129316   }
129317 }
129318 
129319 
129320 /*
129321 ** Return SQLITE_CORRUPT_VTAB.
129322 */
129323 #ifdef SQLITE_DEBUG
129324 SQLITE_PRIVATE int sqlite3Fts3Corrupt(){
129325   return SQLITE_CORRUPT_VTAB;
129326 }
129327 #endif
129328 
129329 #if !SQLITE_CORE
129330 /*
129331 ** Initialize API pointer table, if required.
129332 */
129333 #ifdef _WIN32
129334 __declspec(dllexport)
129335 #endif
129336 SQLITE_API int sqlite3_fts3_init(
129337   sqlite3 *db, 
129338   char **pzErrMsg,
129339   const sqlite3_api_routines *pApi
129340 ){
129341   SQLITE_EXTENSION_INIT2(pApi)
129342   return sqlite3Fts3Init(db);
129343 }
129344 #endif
129345 
129346 #endif
129347 
129348 /************** End of fts3.c ************************************************/
129349 /************** Begin file fts3_aux.c ****************************************/
129350 /*
129351 ** 2011 Jan 27
129352 **
129353 ** The author disclaims copyright to this source code.  In place of
129354 ** a legal notice, here is a blessing:
129355 **
129356 **    May you do good and not evil.
129357 **    May you find forgiveness for yourself and forgive others.
129358 **    May you share freely, never taking more than you give.
129359 **
129360 ******************************************************************************
129361 **
129362 */
129363 #if !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_FTS3)
129364 
129365 /* #include <string.h> */
129366 /* #include <assert.h> */
129367 
129368 typedef struct Fts3auxTable Fts3auxTable;
129369 typedef struct Fts3auxCursor Fts3auxCursor;
129370 
129371 struct Fts3auxTable {
129372   sqlite3_vtab base;              /* Base class used by SQLite core */
129373   Fts3Table *pFts3Tab;
129374 };
129375 
129376 struct Fts3auxCursor {
129377   sqlite3_vtab_cursor base;       /* Base class used by SQLite core */
129378   Fts3MultiSegReader csr;        /* Must be right after "base" */
129379   Fts3SegFilter filter;
129380   char *zStop;
129381   int nStop;                      /* Byte-length of string zStop */
129382   int iLangid;                    /* Language id to query */
129383   int isEof;                      /* True if cursor is at EOF */
129384   sqlite3_int64 iRowid;           /* Current rowid */
129385 
129386   int iCol;                       /* Current value of 'col' column */
129387   int nStat;                      /* Size of aStat[] array */
129388   struct Fts3auxColstats {
129389     sqlite3_int64 nDoc;           /* 'documents' values for current csr row */
129390     sqlite3_int64 nOcc;           /* 'occurrences' values for current csr row */
129391   } *aStat;
129392 };
129393 
129394 /*
129395 ** Schema of the terms table.
129396 */
129397 #define FTS3_AUX_SCHEMA \
129398   "CREATE TABLE x(term, col, documents, occurrences, languageid HIDDEN)"
129399 
129400 /*
129401 ** This function does all the work for both the xConnect and xCreate methods.
129402 ** These tables have no persistent representation of their own, so xConnect
129403 ** and xCreate are identical operations.
129404 */
129405 static int fts3auxConnectMethod(
129406   sqlite3 *db,                    /* Database connection */
129407   void *pUnused,                  /* Unused */
129408   int argc,                       /* Number of elements in argv array */
129409   const char * const *argv,       /* xCreate/xConnect argument array */
129410   sqlite3_vtab **ppVtab,          /* OUT: New sqlite3_vtab object */
129411   char **pzErr                    /* OUT: sqlite3_malloc'd error message */
129412 ){
129413   char const *zDb;                /* Name of database (e.g. "main") */
129414   char const *zFts3;              /* Name of fts3 table */
129415   int nDb;                        /* Result of strlen(zDb) */
129416   int nFts3;                      /* Result of strlen(zFts3) */
129417   int nByte;                      /* Bytes of space to allocate here */
129418   int rc;                         /* value returned by declare_vtab() */
129419   Fts3auxTable *p;                /* Virtual table object to return */
129420 
129421   UNUSED_PARAMETER(pUnused);
129422 
129423   /* The user should invoke this in one of two forms:
129424   **
129425   **     CREATE VIRTUAL TABLE xxx USING fts4aux(fts4-table);
129426   **     CREATE VIRTUAL TABLE xxx USING fts4aux(fts4-table-db, fts4-table);
129427   */
129428   if( argc!=4 && argc!=5 ) goto bad_args;
129429 
129430   zDb = argv[1]; 
129431   nDb = (int)strlen(zDb);
129432   if( argc==5 ){
129433     if( nDb==4 && 0==sqlite3_strnicmp("temp", zDb, 4) ){
129434       zDb = argv[3]; 
129435       nDb = (int)strlen(zDb);
129436       zFts3 = argv[4];
129437     }else{
129438       goto bad_args;
129439     }
129440   }else{
129441     zFts3 = argv[3];
129442   }
129443   nFts3 = (int)strlen(zFts3);
129444 
129445   rc = sqlite3_declare_vtab(db, FTS3_AUX_SCHEMA);
129446   if( rc!=SQLITE_OK ) return rc;
129447 
129448   nByte = sizeof(Fts3auxTable) + sizeof(Fts3Table) + nDb + nFts3 + 2;
129449   p = (Fts3auxTable *)sqlite3_malloc(nByte);
129450   if( !p ) return SQLITE_NOMEM;
129451   memset(p, 0, nByte);
129452 
129453   p->pFts3Tab = (Fts3Table *)&p[1];
129454   p->pFts3Tab->zDb = (char *)&p->pFts3Tab[1];
129455   p->pFts3Tab->zName = &p->pFts3Tab->zDb[nDb+1];
129456   p->pFts3Tab->db = db;
129457   p->pFts3Tab->nIndex = 1;
129458 
129459   memcpy((char *)p->pFts3Tab->zDb, zDb, nDb);
129460   memcpy((char *)p->pFts3Tab->zName, zFts3, nFts3);
129461   sqlite3Fts3Dequote((char *)p->pFts3Tab->zName);
129462 
129463   *ppVtab = (sqlite3_vtab *)p;
129464   return SQLITE_OK;
129465 
129466  bad_args:
129467   *pzErr = sqlite3_mprintf("invalid arguments to fts4aux constructor");
129468   return SQLITE_ERROR;
129469 }
129470 
129471 /*
129472 ** This function does the work for both the xDisconnect and xDestroy methods.
129473 ** These tables have no persistent representation of their own, so xDisconnect
129474 ** and xDestroy are identical operations.
129475 */
129476 static int fts3auxDisconnectMethod(sqlite3_vtab *pVtab){
129477   Fts3auxTable *p = (Fts3auxTable *)pVtab;
129478   Fts3Table *pFts3 = p->pFts3Tab;
129479   int i;
129480 
129481   /* Free any prepared statements held */
129482   for(i=0; i<SizeofArray(pFts3->aStmt); i++){
129483     sqlite3_finalize(pFts3->aStmt[i]);
129484   }
129485   sqlite3_free(pFts3->zSegmentsTbl);
129486   sqlite3_free(p);
129487   return SQLITE_OK;
129488 }
129489 
129490 #define FTS4AUX_EQ_CONSTRAINT 1
129491 #define FTS4AUX_GE_CONSTRAINT 2
129492 #define FTS4AUX_LE_CONSTRAINT 4
129493 
129494 /*
129495 ** xBestIndex - Analyze a WHERE and ORDER BY clause.
129496 */
129497 static int fts3auxBestIndexMethod(
129498   sqlite3_vtab *pVTab, 
129499   sqlite3_index_info *pInfo
129500 ){
129501   int i;
129502   int iEq = -1;
129503   int iGe = -1;
129504   int iLe = -1;
129505   int iLangid = -1;
129506   int iNext = 1;                  /* Next free argvIndex value */
129507 
129508   UNUSED_PARAMETER(pVTab);
129509 
129510   /* This vtab delivers always results in "ORDER BY term ASC" order. */
129511   if( pInfo->nOrderBy==1 
129512    && pInfo->aOrderBy[0].iColumn==0 
129513    && pInfo->aOrderBy[0].desc==0
129514   ){
129515     pInfo->orderByConsumed = 1;
129516   }
129517 
129518   /* Search for equality and range constraints on the "term" column. 
129519   ** And equality constraints on the hidden "languageid" column. */
129520   for(i=0; i<pInfo->nConstraint; i++){
129521     if( pInfo->aConstraint[i].usable ){
129522       int op = pInfo->aConstraint[i].op;
129523       int iCol = pInfo->aConstraint[i].iColumn;
129524 
129525       if( iCol==0 ){
129526         if( op==SQLITE_INDEX_CONSTRAINT_EQ ) iEq = i;
129527         if( op==SQLITE_INDEX_CONSTRAINT_LT ) iLe = i;
129528         if( op==SQLITE_INDEX_CONSTRAINT_LE ) iLe = i;
129529         if( op==SQLITE_INDEX_CONSTRAINT_GT ) iGe = i;
129530         if( op==SQLITE_INDEX_CONSTRAINT_GE ) iGe = i;
129531       }
129532       if( iCol==4 ){
129533         if( op==SQLITE_INDEX_CONSTRAINT_EQ ) iLangid = i;
129534       }
129535     }
129536   }
129537 
129538   if( iEq>=0 ){
129539     pInfo->idxNum = FTS4AUX_EQ_CONSTRAINT;
129540     pInfo->aConstraintUsage[iEq].argvIndex = iNext++;
129541     pInfo->estimatedCost = 5;
129542   }else{
129543     pInfo->idxNum = 0;
129544     pInfo->estimatedCost = 20000;
129545     if( iGe>=0 ){
129546       pInfo->idxNum += FTS4AUX_GE_CONSTRAINT;
129547       pInfo->aConstraintUsage[iGe].argvIndex = iNext++;
129548       pInfo->estimatedCost /= 2;
129549     }
129550     if( iLe>=0 ){
129551       pInfo->idxNum += FTS4AUX_LE_CONSTRAINT;
129552       pInfo->aConstraintUsage[iLe].argvIndex = iNext++;
129553       pInfo->estimatedCost /= 2;
129554     }
129555   }
129556   if( iLangid>=0 ){
129557     pInfo->aConstraintUsage[iLangid].argvIndex = iNext++;
129558     pInfo->estimatedCost--;
129559   }
129560 
129561   return SQLITE_OK;
129562 }
129563 
129564 /*
129565 ** xOpen - Open a cursor.
129566 */
129567 static int fts3auxOpenMethod(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCsr){
129568   Fts3auxCursor *pCsr;            /* Pointer to cursor object to return */
129569 
129570   UNUSED_PARAMETER(pVTab);
129571 
129572   pCsr = (Fts3auxCursor *)sqlite3_malloc(sizeof(Fts3auxCursor));
129573   if( !pCsr ) return SQLITE_NOMEM;
129574   memset(pCsr, 0, sizeof(Fts3auxCursor));
129575 
129576   *ppCsr = (sqlite3_vtab_cursor *)pCsr;
129577   return SQLITE_OK;
129578 }
129579 
129580 /*
129581 ** xClose - Close a cursor.
129582 */
129583 static int fts3auxCloseMethod(sqlite3_vtab_cursor *pCursor){
129584   Fts3Table *pFts3 = ((Fts3auxTable *)pCursor->pVtab)->pFts3Tab;
129585   Fts3auxCursor *pCsr = (Fts3auxCursor *)pCursor;
129586 
129587   sqlite3Fts3SegmentsClose(pFts3);
129588   sqlite3Fts3SegReaderFinish(&pCsr->csr);
129589   sqlite3_free((void *)pCsr->filter.zTerm);
129590   sqlite3_free(pCsr->zStop);
129591   sqlite3_free(pCsr->aStat);
129592   sqlite3_free(pCsr);
129593   return SQLITE_OK;
129594 }
129595 
129596 static int fts3auxGrowStatArray(Fts3auxCursor *pCsr, int nSize){
129597   if( nSize>pCsr->nStat ){
129598     struct Fts3auxColstats *aNew;
129599     aNew = (struct Fts3auxColstats *)sqlite3_realloc(pCsr->aStat, 
129600         sizeof(struct Fts3auxColstats) * nSize
129601     );
129602     if( aNew==0 ) return SQLITE_NOMEM;
129603     memset(&aNew[pCsr->nStat], 0, 
129604         sizeof(struct Fts3auxColstats) * (nSize - pCsr->nStat)
129605     );
129606     pCsr->aStat = aNew;
129607     pCsr->nStat = nSize;
129608   }
129609   return SQLITE_OK;
129610 }
129611 
129612 /*
129613 ** xNext - Advance the cursor to the next row, if any.
129614 */
129615 static int fts3auxNextMethod(sqlite3_vtab_cursor *pCursor){
129616   Fts3auxCursor *pCsr = (Fts3auxCursor *)pCursor;
129617   Fts3Table *pFts3 = ((Fts3auxTable *)pCursor->pVtab)->pFts3Tab;
129618   int rc;
129619 
129620   /* Increment our pretend rowid value. */
129621   pCsr->iRowid++;
129622 
129623   for(pCsr->iCol++; pCsr->iCol<pCsr->nStat; pCsr->iCol++){
129624     if( pCsr->aStat[pCsr->iCol].nDoc>0 ) return SQLITE_OK;
129625   }
129626 
129627   rc = sqlite3Fts3SegReaderStep(pFts3, &pCsr->csr);
129628   if( rc==SQLITE_ROW ){
129629     int i = 0;
129630     int nDoclist = pCsr->csr.nDoclist;
129631     char *aDoclist = pCsr->csr.aDoclist;
129632     int iCol;
129633 
129634     int eState = 0;
129635 
129636     if( pCsr->zStop ){
129637       int n = (pCsr->nStop<pCsr->csr.nTerm) ? pCsr->nStop : pCsr->csr.nTerm;
129638       int mc = memcmp(pCsr->zStop, pCsr->csr.zTerm, n);
129639       if( mc<0 || (mc==0 && pCsr->csr.nTerm>pCsr->nStop) ){
129640         pCsr->isEof = 1;
129641         return SQLITE_OK;
129642       }
129643     }
129644 
129645     if( fts3auxGrowStatArray(pCsr, 2) ) return SQLITE_NOMEM;
129646     memset(pCsr->aStat, 0, sizeof(struct Fts3auxColstats) * pCsr->nStat);
129647     iCol = 0;
129648 
129649     while( i<nDoclist ){
129650       sqlite3_int64 v = 0;
129651 
129652       i += sqlite3Fts3GetVarint(&aDoclist[i], &v);
129653       switch( eState ){
129654         /* State 0. In this state the integer just read was a docid. */
129655         case 0:
129656           pCsr->aStat[0].nDoc++;
129657           eState = 1;
129658           iCol = 0;
129659           break;
129660 
129661         /* State 1. In this state we are expecting either a 1, indicating
129662         ** that the following integer will be a column number, or the
129663         ** start of a position list for column 0.  
129664         ** 
129665         ** The only difference between state 1 and state 2 is that if the
129666         ** integer encountered in state 1 is not 0 or 1, then we need to
129667         ** increment the column 0 "nDoc" count for this term.
129668         */
129669         case 1:
129670           assert( iCol==0 );
129671           if( v>1 ){
129672             pCsr->aStat[1].nDoc++;
129673           }
129674           eState = 2;
129675           /* fall through */
129676 
129677         case 2:
129678           if( v==0 ){       /* 0x00. Next integer will be a docid. */
129679             eState = 0;
129680           }else if( v==1 ){ /* 0x01. Next integer will be a column number. */
129681             eState = 3;
129682           }else{            /* 2 or greater. A position. */
129683             pCsr->aStat[iCol+1].nOcc++;
129684             pCsr->aStat[0].nOcc++;
129685           }
129686           break;
129687 
129688         /* State 3. The integer just read is a column number. */
129689         default: assert( eState==3 );
129690           iCol = (int)v;
129691           if( fts3auxGrowStatArray(pCsr, iCol+2) ) return SQLITE_NOMEM;
129692           pCsr->aStat[iCol+1].nDoc++;
129693           eState = 2;
129694           break;
129695       }
129696     }
129697 
129698     pCsr->iCol = 0;
129699     rc = SQLITE_OK;
129700   }else{
129701     pCsr->isEof = 1;
129702   }
129703   return rc;
129704 }
129705 
129706 /*
129707 ** xFilter - Initialize a cursor to point at the start of its data.
129708 */
129709 static int fts3auxFilterMethod(
129710   sqlite3_vtab_cursor *pCursor,   /* The cursor used for this query */
129711   int idxNum,                     /* Strategy index */
129712   const char *idxStr,             /* Unused */
129713   int nVal,                       /* Number of elements in apVal */
129714   sqlite3_value **apVal           /* Arguments for the indexing scheme */
129715 ){
129716   Fts3auxCursor *pCsr = (Fts3auxCursor *)pCursor;
129717   Fts3Table *pFts3 = ((Fts3auxTable *)pCursor->pVtab)->pFts3Tab;
129718   int rc;
129719   int isScan = 0;
129720   int iLangVal = 0;               /* Language id to query */
129721 
129722   int iEq = -1;                   /* Index of term=? value in apVal */
129723   int iGe = -1;                   /* Index of term>=? value in apVal */
129724   int iLe = -1;                   /* Index of term<=? value in apVal */
129725   int iLangid = -1;               /* Index of languageid=? value in apVal */
129726   int iNext = 0;
129727 
129728   UNUSED_PARAMETER(nVal);
129729   UNUSED_PARAMETER(idxStr);
129730 
129731   assert( idxStr==0 );
129732   assert( idxNum==FTS4AUX_EQ_CONSTRAINT || idxNum==0
129733        || idxNum==FTS4AUX_LE_CONSTRAINT || idxNum==FTS4AUX_GE_CONSTRAINT
129734        || idxNum==(FTS4AUX_LE_CONSTRAINT|FTS4AUX_GE_CONSTRAINT)
129735   );
129736 
129737   if( idxNum==FTS4AUX_EQ_CONSTRAINT ){
129738     iEq = iNext++;
129739   }else{
129740     isScan = 1;
129741     if( idxNum & FTS4AUX_GE_CONSTRAINT ){
129742       iGe = iNext++;
129743     }
129744     if( idxNum & FTS4AUX_LE_CONSTRAINT ){
129745       iLe = iNext++;
129746     }
129747   }
129748   if( iNext<nVal ){
129749     iLangid = iNext++;
129750   }
129751 
129752   /* In case this cursor is being reused, close and zero it. */
129753   testcase(pCsr->filter.zTerm);
129754   sqlite3Fts3SegReaderFinish(&pCsr->csr);
129755   sqlite3_free((void *)pCsr->filter.zTerm);
129756   sqlite3_free(pCsr->aStat);
129757   memset(&pCsr->csr, 0, ((u8*)&pCsr[1]) - (u8*)&pCsr->csr);
129758 
129759   pCsr->filter.flags = FTS3_SEGMENT_REQUIRE_POS|FTS3_SEGMENT_IGNORE_EMPTY;
129760   if( isScan ) pCsr->filter.flags |= FTS3_SEGMENT_SCAN;
129761 
129762   if( iEq>=0 || iGe>=0 ){
129763     const unsigned char *zStr = sqlite3_value_text(apVal[0]);
129764     assert( (iEq==0 && iGe==-1) || (iEq==-1 && iGe==0) );
129765     if( zStr ){
129766       pCsr->filter.zTerm = sqlite3_mprintf("%s", zStr);
129767       pCsr->filter.nTerm = sqlite3_value_bytes(apVal[0]);
129768       if( pCsr->filter.zTerm==0 ) return SQLITE_NOMEM;
129769     }
129770   }
129771 
129772   if( iLe>=0 ){
129773     pCsr->zStop = sqlite3_mprintf("%s", sqlite3_value_text(apVal[iLe]));
129774     pCsr->nStop = sqlite3_value_bytes(apVal[iLe]);
129775     if( pCsr->zStop==0 ) return SQLITE_NOMEM;
129776   }
129777   
129778   if( iLangid>=0 ){
129779     iLangVal = sqlite3_value_int(apVal[iLangid]);
129780 
129781     /* If the user specified a negative value for the languageid, use zero
129782     ** instead. This works, as the "languageid=?" constraint will also
129783     ** be tested by the VDBE layer. The test will always be false (since
129784     ** this module will not return a row with a negative languageid), and
129785     ** so the overall query will return zero rows.  */
129786     if( iLangVal<0 ) iLangVal = 0;
129787   }
129788   pCsr->iLangid = iLangVal;
129789 
129790   rc = sqlite3Fts3SegReaderCursor(pFts3, iLangVal, 0, FTS3_SEGCURSOR_ALL,
129791       pCsr->filter.zTerm, pCsr->filter.nTerm, 0, isScan, &pCsr->csr
129792   );
129793   if( rc==SQLITE_OK ){
129794     rc = sqlite3Fts3SegReaderStart(pFts3, &pCsr->csr, &pCsr->filter);
129795   }
129796 
129797   if( rc==SQLITE_OK ) rc = fts3auxNextMethod(pCursor);
129798   return rc;
129799 }
129800 
129801 /*
129802 ** xEof - Return true if the cursor is at EOF, or false otherwise.
129803 */
129804 static int fts3auxEofMethod(sqlite3_vtab_cursor *pCursor){
129805   Fts3auxCursor *pCsr = (Fts3auxCursor *)pCursor;
129806   return pCsr->isEof;
129807 }
129808 
129809 /*
129810 ** xColumn - Return a column value.
129811 */
129812 static int fts3auxColumnMethod(
129813   sqlite3_vtab_cursor *pCursor,   /* Cursor to retrieve value from */
129814   sqlite3_context *pCtx,          /* Context for sqlite3_result_xxx() calls */
129815   int iCol                        /* Index of column to read value from */
129816 ){
129817   Fts3auxCursor *p = (Fts3auxCursor *)pCursor;
129818 
129819   assert( p->isEof==0 );
129820   switch( iCol ){
129821     case 0: /* term */
129822       sqlite3_result_text(pCtx, p->csr.zTerm, p->csr.nTerm, SQLITE_TRANSIENT);
129823       break;
129824 
129825     case 1: /* col */
129826       if( p->iCol ){
129827         sqlite3_result_int(pCtx, p->iCol-1);
129828       }else{
129829         sqlite3_result_text(pCtx, "*", -1, SQLITE_STATIC);
129830       }
129831       break;
129832 
129833     case 2: /* documents */
129834       sqlite3_result_int64(pCtx, p->aStat[p->iCol].nDoc);
129835       break;
129836 
129837     case 3: /* occurrences */
129838       sqlite3_result_int64(pCtx, p->aStat[p->iCol].nOcc);
129839       break;
129840 
129841     default: /* languageid */
129842       assert( iCol==4 );
129843       sqlite3_result_int(pCtx, p->iLangid);
129844       break;
129845   }
129846 
129847   return SQLITE_OK;
129848 }
129849 
129850 /*
129851 ** xRowid - Return the current rowid for the cursor.
129852 */
129853 static int fts3auxRowidMethod(
129854   sqlite3_vtab_cursor *pCursor,   /* Cursor to retrieve value from */
129855   sqlite_int64 *pRowid            /* OUT: Rowid value */
129856 ){
129857   Fts3auxCursor *pCsr = (Fts3auxCursor *)pCursor;
129858   *pRowid = pCsr->iRowid;
129859   return SQLITE_OK;
129860 }
129861 
129862 /*
129863 ** Register the fts3aux module with database connection db. Return SQLITE_OK
129864 ** if successful or an error code if sqlite3_create_module() fails.
129865 */
129866 SQLITE_PRIVATE int sqlite3Fts3InitAux(sqlite3 *db){
129867   static const sqlite3_module fts3aux_module = {
129868      0,                           /* iVersion      */
129869      fts3auxConnectMethod,        /* xCreate       */
129870      fts3auxConnectMethod,        /* xConnect      */
129871      fts3auxBestIndexMethod,      /* xBestIndex    */
129872      fts3auxDisconnectMethod,     /* xDisconnect   */
129873      fts3auxDisconnectMethod,     /* xDestroy      */
129874      fts3auxOpenMethod,           /* xOpen         */
129875      fts3auxCloseMethod,          /* xClose        */
129876      fts3auxFilterMethod,         /* xFilter       */
129877      fts3auxNextMethod,           /* xNext         */
129878      fts3auxEofMethod,            /* xEof          */
129879      fts3auxColumnMethod,         /* xColumn       */
129880      fts3auxRowidMethod,          /* xRowid        */
129881      0,                           /* xUpdate       */
129882      0,                           /* xBegin        */
129883      0,                           /* xSync         */
129884      0,                           /* xCommit       */
129885      0,                           /* xRollback     */
129886      0,                           /* xFindFunction */
129887      0,                           /* xRename       */
129888      0,                           /* xSavepoint    */
129889      0,                           /* xRelease      */
129890      0                            /* xRollbackTo   */
129891   };
129892   int rc;                         /* Return code */
129893 
129894   rc = sqlite3_create_module(db, "fts4aux", &fts3aux_module, 0);
129895   return rc;
129896 }
129897 
129898 #endif /* !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_FTS3) */
129899 
129900 /************** End of fts3_aux.c ********************************************/
129901 /************** Begin file fts3_expr.c ***************************************/
129902 /*
129903 ** 2008 Nov 28
129904 **
129905 ** The author disclaims copyright to this source code.  In place of
129906 ** a legal notice, here is a blessing:
129907 **
129908 **    May you do good and not evil.
129909 **    May you find forgiveness for yourself and forgive others.
129910 **    May you share freely, never taking more than you give.
129911 **
129912 ******************************************************************************
129913 **
129914 ** This module contains code that implements a parser for fts3 query strings
129915 ** (the right-hand argument to the MATCH operator). Because the supported 
129916 ** syntax is relatively simple, the whole tokenizer/parser system is
129917 ** hand-coded. 
129918 */
129919 #if !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_FTS3)
129920 
129921 /*
129922 ** By default, this module parses the legacy syntax that has been 
129923 ** traditionally used by fts3. Or, if SQLITE_ENABLE_FTS3_PARENTHESIS
129924 ** is defined, then it uses the new syntax. The differences between
129925 ** the new and the old syntaxes are:
129926 **
129927 **  a) The new syntax supports parenthesis. The old does not.
129928 **
129929 **  b) The new syntax supports the AND and NOT operators. The old does not.
129930 **
129931 **  c) The old syntax supports the "-" token qualifier. This is not 
129932 **     supported by the new syntax (it is replaced by the NOT operator).
129933 **
129934 **  d) When using the old syntax, the OR operator has a greater precedence
129935 **     than an implicit AND. When using the new, both implicity and explicit
129936 **     AND operators have a higher precedence than OR.
129937 **
129938 ** If compiled with SQLITE_TEST defined, then this module exports the
129939 ** symbol "int sqlite3_fts3_enable_parentheses". Setting this variable
129940 ** to zero causes the module to use the old syntax. If it is set to 
129941 ** non-zero the new syntax is activated. This is so both syntaxes can
129942 ** be tested using a single build of testfixture.
129943 **
129944 ** The following describes the syntax supported by the fts3 MATCH
129945 ** operator in a similar format to that used by the lemon parser
129946 ** generator. This module does not use actually lemon, it uses a
129947 ** custom parser.
129948 **
129949 **   query ::= andexpr (OR andexpr)*.
129950 **
129951 **   andexpr ::= notexpr (AND? notexpr)*.
129952 **
129953 **   notexpr ::= nearexpr (NOT nearexpr|-TOKEN)*.
129954 **   notexpr ::= LP query RP.
129955 **
129956 **   nearexpr ::= phrase (NEAR distance_opt nearexpr)*.
129957 **
129958 **   distance_opt ::= .
129959 **   distance_opt ::= / INTEGER.
129960 **
129961 **   phrase ::= TOKEN.
129962 **   phrase ::= COLUMN:TOKEN.
129963 **   phrase ::= "TOKEN TOKEN TOKEN...".
129964 */
129965 
129966 #ifdef SQLITE_TEST
129967 SQLITE_API int sqlite3_fts3_enable_parentheses = 0;
129968 #else
129969 # ifdef SQLITE_ENABLE_FTS3_PARENTHESIS 
129970 #  define sqlite3_fts3_enable_parentheses 1
129971 # else
129972 #  define sqlite3_fts3_enable_parentheses 0
129973 # endif
129974 #endif
129975 
129976 /*
129977 ** Default span for NEAR operators.
129978 */
129979 #define SQLITE_FTS3_DEFAULT_NEAR_PARAM 10
129980 
129981 /* #include <string.h> */
129982 /* #include <assert.h> */
129983 
129984 /*
129985 ** isNot:
129986 **   This variable is used by function getNextNode(). When getNextNode() is
129987 **   called, it sets ParseContext.isNot to true if the 'next node' is a 
129988 **   FTSQUERY_PHRASE with a unary "-" attached to it. i.e. "mysql" in the
129989 **   FTS3 query "sqlite -mysql". Otherwise, ParseContext.isNot is set to
129990 **   zero.
129991 */
129992 typedef struct ParseContext ParseContext;
129993 struct ParseContext {
129994   sqlite3_tokenizer *pTokenizer;      /* Tokenizer module */
129995   int iLangid;                        /* Language id used with tokenizer */
129996   const char **azCol;                 /* Array of column names for fts3 table */
129997   int bFts4;                          /* True to allow FTS4-only syntax */
129998   int nCol;                           /* Number of entries in azCol[] */
129999   int iDefaultCol;                    /* Default column to query */
130000   int isNot;                          /* True if getNextNode() sees a unary - */
130001   sqlite3_context *pCtx;              /* Write error message here */
130002   int nNest;                          /* Number of nested brackets */
130003 };
130004 
130005 /*
130006 ** This function is equivalent to the standard isspace() function. 
130007 **
130008 ** The standard isspace() can be awkward to use safely, because although it
130009 ** is defined to accept an argument of type int, its behavior when passed
130010 ** an integer that falls outside of the range of the unsigned char type
130011 ** is undefined (and sometimes, "undefined" means segfault). This wrapper
130012 ** is defined to accept an argument of type char, and always returns 0 for
130013 ** any values that fall outside of the range of the unsigned char type (i.e.
130014 ** negative values).
130015 */
130016 static int fts3isspace(char c){
130017   return c==' ' || c=='\t' || c=='\n' || c=='\r' || c=='\v' || c=='\f';
130018 }
130019 
130020 /*
130021 ** Allocate nByte bytes of memory using sqlite3_malloc(). If successful,
130022 ** zero the memory before returning a pointer to it. If unsuccessful, 
130023 ** return NULL.
130024 */
130025 static void *fts3MallocZero(int nByte){
130026   void *pRet = sqlite3_malloc(nByte);
130027   if( pRet ) memset(pRet, 0, nByte);
130028   return pRet;
130029 }
130030 
130031 SQLITE_PRIVATE int sqlite3Fts3OpenTokenizer(
130032   sqlite3_tokenizer *pTokenizer,
130033   int iLangid,
130034   const char *z,
130035   int n,
130036   sqlite3_tokenizer_cursor **ppCsr
130037 ){
130038   sqlite3_tokenizer_module const *pModule = pTokenizer->pModule;
130039   sqlite3_tokenizer_cursor *pCsr = 0;
130040   int rc;
130041 
130042   rc = pModule->xOpen(pTokenizer, z, n, &pCsr);
130043   assert( rc==SQLITE_OK || pCsr==0 );
130044   if( rc==SQLITE_OK ){
130045     pCsr->pTokenizer = pTokenizer;
130046     if( pModule->iVersion>=1 ){
130047       rc = pModule->xLanguageid(pCsr, iLangid);
130048       if( rc!=SQLITE_OK ){
130049         pModule->xClose(pCsr);
130050         pCsr = 0;
130051       }
130052     }
130053   }
130054   *ppCsr = pCsr;
130055   return rc;
130056 }
130057 
130058 /*
130059 ** Function getNextNode(), which is called by fts3ExprParse(), may itself
130060 ** call fts3ExprParse(). So this forward declaration is required.
130061 */
130062 static int fts3ExprParse(ParseContext *, const char *, int, Fts3Expr **, int *);
130063 
130064 /*
130065 ** Extract the next token from buffer z (length n) using the tokenizer
130066 ** and other information (column names etc.) in pParse. Create an Fts3Expr
130067 ** structure of type FTSQUERY_PHRASE containing a phrase consisting of this
130068 ** single token and set *ppExpr to point to it. If the end of the buffer is
130069 ** reached before a token is found, set *ppExpr to zero. It is the
130070 ** responsibility of the caller to eventually deallocate the allocated 
130071 ** Fts3Expr structure (if any) by passing it to sqlite3_free().
130072 **
130073 ** Return SQLITE_OK if successful, or SQLITE_NOMEM if a memory allocation
130074 ** fails.
130075 */
130076 static int getNextToken(
130077   ParseContext *pParse,                   /* fts3 query parse context */
130078   int iCol,                               /* Value for Fts3Phrase.iColumn */
130079   const char *z, int n,                   /* Input string */
130080   Fts3Expr **ppExpr,                      /* OUT: expression */
130081   int *pnConsumed                         /* OUT: Number of bytes consumed */
130082 ){
130083   sqlite3_tokenizer *pTokenizer = pParse->pTokenizer;
130084   sqlite3_tokenizer_module const *pModule = pTokenizer->pModule;
130085   int rc;
130086   sqlite3_tokenizer_cursor *pCursor;
130087   Fts3Expr *pRet = 0;
130088   int nConsumed = 0;
130089 
130090   rc = sqlite3Fts3OpenTokenizer(pTokenizer, pParse->iLangid, z, n, &pCursor);
130091   if( rc==SQLITE_OK ){
130092     const char *zToken;
130093     int nToken = 0, iStart = 0, iEnd = 0, iPosition = 0;
130094     int nByte;                               /* total space to allocate */
130095 
130096     rc = pModule->xNext(pCursor, &zToken, &nToken, &iStart, &iEnd, &iPosition);
130097 
130098     if( (rc==SQLITE_OK || rc==SQLITE_DONE) && sqlite3_fts3_enable_parentheses ){
130099       int i;
130100       if( rc==SQLITE_DONE ) iStart = n;
130101       for(i=0; i<iStart; i++){
130102         if( z[i]=='(' ){
130103           pParse->nNest++;
130104           rc = fts3ExprParse(pParse, &z[i+1], n-i-1, &pRet, &nConsumed);
130105           if( rc==SQLITE_OK && !pRet ){
130106             rc = SQLITE_DONE;
130107           }
130108           nConsumed = (int)(i + 1 + nConsumed);
130109           break;
130110         }
130111 
130112         if( z[i]==')' ){
130113           rc = SQLITE_DONE;
130114           pParse->nNest--;
130115           nConsumed = i+1;
130116           break;
130117         }
130118       }
130119     }
130120 
130121     if( nConsumed==0 && rc==SQLITE_OK ){
130122       nByte = sizeof(Fts3Expr) + sizeof(Fts3Phrase) + nToken;
130123       pRet = (Fts3Expr *)fts3MallocZero(nByte);
130124       if( !pRet ){
130125         rc = SQLITE_NOMEM;
130126       }else{
130127         pRet->eType = FTSQUERY_PHRASE;
130128         pRet->pPhrase = (Fts3Phrase *)&pRet[1];
130129         pRet->pPhrase->nToken = 1;
130130         pRet->pPhrase->iColumn = iCol;
130131         pRet->pPhrase->aToken[0].n = nToken;
130132         pRet->pPhrase->aToken[0].z = (char *)&pRet->pPhrase[1];
130133         memcpy(pRet->pPhrase->aToken[0].z, zToken, nToken);
130134 
130135         if( iEnd<n && z[iEnd]=='*' ){
130136           pRet->pPhrase->aToken[0].isPrefix = 1;
130137           iEnd++;
130138         }
130139 
130140         while( 1 ){
130141           if( !sqlite3_fts3_enable_parentheses 
130142            && iStart>0 && z[iStart-1]=='-' 
130143           ){
130144             pParse->isNot = 1;
130145             iStart--;
130146           }else if( pParse->bFts4 && iStart>0 && z[iStart-1]=='^' ){
130147             pRet->pPhrase->aToken[0].bFirst = 1;
130148             iStart--;
130149           }else{
130150             break;
130151           }
130152         }
130153 
130154       }
130155       nConsumed = iEnd;
130156     }
130157 
130158     pModule->xClose(pCursor);
130159   }
130160   
130161   *pnConsumed = nConsumed;
130162   *ppExpr = pRet;
130163   return rc;
130164 }
130165 
130166 
130167 /*
130168 ** Enlarge a memory allocation.  If an out-of-memory allocation occurs,
130169 ** then free the old allocation.
130170 */
130171 static void *fts3ReallocOrFree(void *pOrig, int nNew){
130172   void *pRet = sqlite3_realloc(pOrig, nNew);
130173   if( !pRet ){
130174     sqlite3_free(pOrig);
130175   }
130176   return pRet;
130177 }
130178 
130179 /*
130180 ** Buffer zInput, length nInput, contains the contents of a quoted string
130181 ** that appeared as part of an fts3 query expression. Neither quote character
130182 ** is included in the buffer. This function attempts to tokenize the entire
130183 ** input buffer and create an Fts3Expr structure of type FTSQUERY_PHRASE 
130184 ** containing the results.
130185 **
130186 ** If successful, SQLITE_OK is returned and *ppExpr set to point at the
130187 ** allocated Fts3Expr structure. Otherwise, either SQLITE_NOMEM (out of memory
130188 ** error) or SQLITE_ERROR (tokenization error) is returned and *ppExpr set
130189 ** to 0.
130190 */
130191 static int getNextString(
130192   ParseContext *pParse,                   /* fts3 query parse context */
130193   const char *zInput, int nInput,         /* Input string */
130194   Fts3Expr **ppExpr                       /* OUT: expression */
130195 ){
130196   sqlite3_tokenizer *pTokenizer = pParse->pTokenizer;
130197   sqlite3_tokenizer_module const *pModule = pTokenizer->pModule;
130198   int rc;
130199   Fts3Expr *p = 0;
130200   sqlite3_tokenizer_cursor *pCursor = 0;
130201   char *zTemp = 0;
130202   int nTemp = 0;
130203 
130204   const int nSpace = sizeof(Fts3Expr) + sizeof(Fts3Phrase);
130205   int nToken = 0;
130206 
130207   /* The final Fts3Expr data structure, including the Fts3Phrase,
130208   ** Fts3PhraseToken structures token buffers are all stored as a single 
130209   ** allocation so that the expression can be freed with a single call to
130210   ** sqlite3_free(). Setting this up requires a two pass approach.
130211   **
130212   ** The first pass, in the block below, uses a tokenizer cursor to iterate
130213   ** through the tokens in the expression. This pass uses fts3ReallocOrFree()
130214   ** to assemble data in two dynamic buffers:
130215   **
130216   **   Buffer p: Points to the Fts3Expr structure, followed by the Fts3Phrase
130217   **             structure, followed by the array of Fts3PhraseToken 
130218   **             structures. This pass only populates the Fts3PhraseToken array.
130219   **
130220   **   Buffer zTemp: Contains copies of all tokens.
130221   **
130222   ** The second pass, in the block that begins "if( rc==SQLITE_DONE )" below,
130223   ** appends buffer zTemp to buffer p, and fills in the Fts3Expr and Fts3Phrase
130224   ** structures.
130225   */
130226   rc = sqlite3Fts3OpenTokenizer(
130227       pTokenizer, pParse->iLangid, zInput, nInput, &pCursor);
130228   if( rc==SQLITE_OK ){
130229     int ii;
130230     for(ii=0; rc==SQLITE_OK; ii++){
130231       const char *zByte;
130232       int nByte = 0, iBegin = 0, iEnd = 0, iPos = 0;
130233       rc = pModule->xNext(pCursor, &zByte, &nByte, &iBegin, &iEnd, &iPos);
130234       if( rc==SQLITE_OK ){
130235         Fts3PhraseToken *pToken;
130236 
130237         p = fts3ReallocOrFree(p, nSpace + ii*sizeof(Fts3PhraseToken));
130238         if( !p ) goto no_mem;
130239 
130240         zTemp = fts3ReallocOrFree(zTemp, nTemp + nByte);
130241         if( !zTemp ) goto no_mem;
130242 
130243         assert( nToken==ii );
130244         pToken = &((Fts3Phrase *)(&p[1]))->aToken[ii];
130245         memset(pToken, 0, sizeof(Fts3PhraseToken));
130246 
130247         memcpy(&zTemp[nTemp], zByte, nByte);
130248         nTemp += nByte;
130249 
130250         pToken->n = nByte;
130251         pToken->isPrefix = (iEnd<nInput && zInput[iEnd]=='*');
130252         pToken->bFirst = (iBegin>0 && zInput[iBegin-1]=='^');
130253         nToken = ii+1;
130254       }
130255     }
130256 
130257     pModule->xClose(pCursor);
130258     pCursor = 0;
130259   }
130260 
130261   if( rc==SQLITE_DONE ){
130262     int jj;
130263     char *zBuf = 0;
130264 
130265     p = fts3ReallocOrFree(p, nSpace + nToken*sizeof(Fts3PhraseToken) + nTemp);
130266     if( !p ) goto no_mem;
130267     memset(p, 0, (char *)&(((Fts3Phrase *)&p[1])->aToken[0])-(char *)p);
130268     p->eType = FTSQUERY_PHRASE;
130269     p->pPhrase = (Fts3Phrase *)&p[1];
130270     p->pPhrase->iColumn = pParse->iDefaultCol;
130271     p->pPhrase->nToken = nToken;
130272 
130273     zBuf = (char *)&p->pPhrase->aToken[nToken];
130274     if( zTemp ){
130275       memcpy(zBuf, zTemp, nTemp);
130276       sqlite3_free(zTemp);
130277     }else{
130278       assert( nTemp==0 );
130279     }
130280 
130281     for(jj=0; jj<p->pPhrase->nToken; jj++){
130282       p->pPhrase->aToken[jj].z = zBuf;
130283       zBuf += p->pPhrase->aToken[jj].n;
130284     }
130285     rc = SQLITE_OK;
130286   }
130287 
130288   *ppExpr = p;
130289   return rc;
130290 no_mem:
130291 
130292   if( pCursor ){
130293     pModule->xClose(pCursor);
130294   }
130295   sqlite3_free(zTemp);
130296   sqlite3_free(p);
130297   *ppExpr = 0;
130298   return SQLITE_NOMEM;
130299 }
130300 
130301 /*
130302 ** The output variable *ppExpr is populated with an allocated Fts3Expr 
130303 ** structure, or set to 0 if the end of the input buffer is reached.
130304 **
130305 ** Returns an SQLite error code. SQLITE_OK if everything works, SQLITE_NOMEM
130306 ** if a malloc failure occurs, or SQLITE_ERROR if a parse error is encountered.
130307 ** If SQLITE_ERROR is returned, pContext is populated with an error message.
130308 */
130309 static int getNextNode(
130310   ParseContext *pParse,                   /* fts3 query parse context */
130311   const char *z, int n,                   /* Input string */
130312   Fts3Expr **ppExpr,                      /* OUT: expression */
130313   int *pnConsumed                         /* OUT: Number of bytes consumed */
130314 ){
130315   static const struct Fts3Keyword {
130316     char *z;                              /* Keyword text */
130317     unsigned char n;                      /* Length of the keyword */
130318     unsigned char parenOnly;              /* Only valid in paren mode */
130319     unsigned char eType;                  /* Keyword code */
130320   } aKeyword[] = {
130321     { "OR" ,  2, 0, FTSQUERY_OR   },
130322     { "AND",  3, 1, FTSQUERY_AND  },
130323     { "NOT",  3, 1, FTSQUERY_NOT  },
130324     { "NEAR", 4, 0, FTSQUERY_NEAR }
130325   };
130326   int ii;
130327   int iCol;
130328   int iColLen;
130329   int rc;
130330   Fts3Expr *pRet = 0;
130331 
130332   const char *zInput = z;
130333   int nInput = n;
130334 
130335   pParse->isNot = 0;
130336 
130337   /* Skip over any whitespace before checking for a keyword, an open or
130338   ** close bracket, or a quoted string. 
130339   */
130340   while( nInput>0 && fts3isspace(*zInput) ){
130341     nInput--;
130342     zInput++;
130343   }
130344   if( nInput==0 ){
130345     return SQLITE_DONE;
130346   }
130347 
130348   /* See if we are dealing with a keyword. */
130349   for(ii=0; ii<(int)(sizeof(aKeyword)/sizeof(struct Fts3Keyword)); ii++){
130350     const struct Fts3Keyword *pKey = &aKeyword[ii];
130351 
130352     if( (pKey->parenOnly & ~sqlite3_fts3_enable_parentheses)!=0 ){
130353       continue;
130354     }
130355 
130356     if( nInput>=pKey->n && 0==memcmp(zInput, pKey->z, pKey->n) ){
130357       int nNear = SQLITE_FTS3_DEFAULT_NEAR_PARAM;
130358       int nKey = pKey->n;
130359       char cNext;
130360 
130361       /* If this is a "NEAR" keyword, check for an explicit nearness. */
130362       if( pKey->eType==FTSQUERY_NEAR ){
130363         assert( nKey==4 );
130364         if( zInput[4]=='/' && zInput[5]>='0' && zInput[5]<='9' ){
130365           nNear = 0;
130366           for(nKey=5; zInput[nKey]>='0' && zInput[nKey]<='9'; nKey++){
130367             nNear = nNear * 10 + (zInput[nKey] - '0');
130368           }
130369         }
130370       }
130371 
130372       /* At this point this is probably a keyword. But for that to be true,
130373       ** the next byte must contain either whitespace, an open or close
130374       ** parenthesis, a quote character, or EOF. 
130375       */
130376       cNext = zInput[nKey];
130377       if( fts3isspace(cNext) 
130378        || cNext=='"' || cNext=='(' || cNext==')' || cNext==0
130379       ){
130380         pRet = (Fts3Expr *)fts3MallocZero(sizeof(Fts3Expr));
130381         if( !pRet ){
130382           return SQLITE_NOMEM;
130383         }
130384         pRet->eType = pKey->eType;
130385         pRet->nNear = nNear;
130386         *ppExpr = pRet;
130387         *pnConsumed = (int)((zInput - z) + nKey);
130388         return SQLITE_OK;
130389       }
130390 
130391       /* Turns out that wasn't a keyword after all. This happens if the
130392       ** user has supplied a token such as "ORacle". Continue.
130393       */
130394     }
130395   }
130396 
130397   /* See if we are dealing with a quoted phrase. If this is the case, then
130398   ** search for the closing quote and pass the whole string to getNextString()
130399   ** for processing. This is easy to do, as fts3 has no syntax for escaping
130400   ** a quote character embedded in a string.
130401   */
130402   if( *zInput=='"' ){
130403     for(ii=1; ii<nInput && zInput[ii]!='"'; ii++);
130404     *pnConsumed = (int)((zInput - z) + ii + 1);
130405     if( ii==nInput ){
130406       return SQLITE_ERROR;
130407     }
130408     return getNextString(pParse, &zInput[1], ii-1, ppExpr);
130409   }
130410 
130411 
130412   /* If control flows to this point, this must be a regular token, or 
130413   ** the end of the input. Read a regular token using the sqlite3_tokenizer
130414   ** interface. Before doing so, figure out if there is an explicit
130415   ** column specifier for the token. 
130416   **
130417   ** TODO: Strangely, it is not possible to associate a column specifier
130418   ** with a quoted phrase, only with a single token. Not sure if this was
130419   ** an implementation artifact or an intentional decision when fts3 was
130420   ** first implemented. Whichever it was, this module duplicates the 
130421   ** limitation.
130422   */
130423   iCol = pParse->iDefaultCol;
130424   iColLen = 0;
130425   for(ii=0; ii<pParse->nCol; ii++){
130426     const char *zStr = pParse->azCol[ii];
130427     int nStr = (int)strlen(zStr);
130428     if( nInput>nStr && zInput[nStr]==':' 
130429      && sqlite3_strnicmp(zStr, zInput, nStr)==0 
130430     ){
130431       iCol = ii;
130432       iColLen = (int)((zInput - z) + nStr + 1);
130433       break;
130434     }
130435   }
130436   rc = getNextToken(pParse, iCol, &z[iColLen], n-iColLen, ppExpr, pnConsumed);
130437   *pnConsumed += iColLen;
130438   return rc;
130439 }
130440 
130441 /*
130442 ** The argument is an Fts3Expr structure for a binary operator (any type
130443 ** except an FTSQUERY_PHRASE). Return an integer value representing the
130444 ** precedence of the operator. Lower values have a higher precedence (i.e.
130445 ** group more tightly). For example, in the C language, the == operator
130446 ** groups more tightly than ||, and would therefore have a higher precedence.
130447 **
130448 ** When using the new fts3 query syntax (when SQLITE_ENABLE_FTS3_PARENTHESIS
130449 ** is defined), the order of the operators in precedence from highest to
130450 ** lowest is:
130451 **
130452 **   NEAR
130453 **   NOT
130454 **   AND (including implicit ANDs)
130455 **   OR
130456 **
130457 ** Note that when using the old query syntax, the OR operator has a higher
130458 ** precedence than the AND operator.
130459 */
130460 static int opPrecedence(Fts3Expr *p){
130461   assert( p->eType!=FTSQUERY_PHRASE );
130462   if( sqlite3_fts3_enable_parentheses ){
130463     return p->eType;
130464   }else if( p->eType==FTSQUERY_NEAR ){
130465     return 1;
130466   }else if( p->eType==FTSQUERY_OR ){
130467     return 2;
130468   }
130469   assert( p->eType==FTSQUERY_AND );
130470   return 3;
130471 }
130472 
130473 /*
130474 ** Argument ppHead contains a pointer to the current head of a query 
130475 ** expression tree being parsed. pPrev is the expression node most recently
130476 ** inserted into the tree. This function adds pNew, which is always a binary
130477 ** operator node, into the expression tree based on the relative precedence
130478 ** of pNew and the existing nodes of the tree. This may result in the head
130479 ** of the tree changing, in which case *ppHead is set to the new root node.
130480 */
130481 static void insertBinaryOperator(
130482   Fts3Expr **ppHead,       /* Pointer to the root node of a tree */
130483   Fts3Expr *pPrev,         /* Node most recently inserted into the tree */
130484   Fts3Expr *pNew           /* New binary node to insert into expression tree */
130485 ){
130486   Fts3Expr *pSplit = pPrev;
130487   while( pSplit->pParent && opPrecedence(pSplit->pParent)<=opPrecedence(pNew) ){
130488     pSplit = pSplit->pParent;
130489   }
130490 
130491   if( pSplit->pParent ){
130492     assert( pSplit->pParent->pRight==pSplit );
130493     pSplit->pParent->pRight = pNew;
130494     pNew->pParent = pSplit->pParent;
130495   }else{
130496     *ppHead = pNew;
130497   }
130498   pNew->pLeft = pSplit;
130499   pSplit->pParent = pNew;
130500 }
130501 
130502 /*
130503 ** Parse the fts3 query expression found in buffer z, length n. This function
130504 ** returns either when the end of the buffer is reached or an unmatched 
130505 ** closing bracket - ')' - is encountered.
130506 **
130507 ** If successful, SQLITE_OK is returned, *ppExpr is set to point to the
130508 ** parsed form of the expression and *pnConsumed is set to the number of
130509 ** bytes read from buffer z. Otherwise, *ppExpr is set to 0 and SQLITE_NOMEM
130510 ** (out of memory error) or SQLITE_ERROR (parse error) is returned.
130511 */
130512 static int fts3ExprParse(
130513   ParseContext *pParse,                   /* fts3 query parse context */
130514   const char *z, int n,                   /* Text of MATCH query */
130515   Fts3Expr **ppExpr,                      /* OUT: Parsed query structure */
130516   int *pnConsumed                         /* OUT: Number of bytes consumed */
130517 ){
130518   Fts3Expr *pRet = 0;
130519   Fts3Expr *pPrev = 0;
130520   Fts3Expr *pNotBranch = 0;               /* Only used in legacy parse mode */
130521   int nIn = n;
130522   const char *zIn = z;
130523   int rc = SQLITE_OK;
130524   int isRequirePhrase = 1;
130525 
130526   while( rc==SQLITE_OK ){
130527     Fts3Expr *p = 0;
130528     int nByte = 0;
130529     rc = getNextNode(pParse, zIn, nIn, &p, &nByte);
130530     if( rc==SQLITE_OK ){
130531       int isPhrase;
130532 
130533       if( !sqlite3_fts3_enable_parentheses 
130534        && p->eType==FTSQUERY_PHRASE && pParse->isNot 
130535       ){
130536         /* Create an implicit NOT operator. */
130537         Fts3Expr *pNot = fts3MallocZero(sizeof(Fts3Expr));
130538         if( !pNot ){
130539           sqlite3Fts3ExprFree(p);
130540           rc = SQLITE_NOMEM;
130541           goto exprparse_out;
130542         }
130543         pNot->eType = FTSQUERY_NOT;
130544         pNot->pRight = p;
130545         p->pParent = pNot;
130546         if( pNotBranch ){
130547           pNot->pLeft = pNotBranch;
130548           pNotBranch->pParent = pNot;
130549         }
130550         pNotBranch = pNot;
130551         p = pPrev;
130552       }else{
130553         int eType = p->eType;
130554         isPhrase = (eType==FTSQUERY_PHRASE || p->pLeft);
130555 
130556         /* The isRequirePhrase variable is set to true if a phrase or
130557         ** an expression contained in parenthesis is required. If a
130558         ** binary operator (AND, OR, NOT or NEAR) is encounted when
130559         ** isRequirePhrase is set, this is a syntax error.
130560         */
130561         if( !isPhrase && isRequirePhrase ){
130562           sqlite3Fts3ExprFree(p);
130563           rc = SQLITE_ERROR;
130564           goto exprparse_out;
130565         }
130566   
130567         if( isPhrase && !isRequirePhrase ){
130568           /* Insert an implicit AND operator. */
130569           Fts3Expr *pAnd;
130570           assert( pRet && pPrev );
130571           pAnd = fts3MallocZero(sizeof(Fts3Expr));
130572           if( !pAnd ){
130573             sqlite3Fts3ExprFree(p);
130574             rc = SQLITE_NOMEM;
130575             goto exprparse_out;
130576           }
130577           pAnd->eType = FTSQUERY_AND;
130578           insertBinaryOperator(&pRet, pPrev, pAnd);
130579           pPrev = pAnd;
130580         }
130581 
130582         /* This test catches attempts to make either operand of a NEAR
130583         ** operator something other than a phrase. For example, either of
130584         ** the following:
130585         **
130586         **    (bracketed expression) NEAR phrase
130587         **    phrase NEAR (bracketed expression)
130588         **
130589         ** Return an error in either case.
130590         */
130591         if( pPrev && (
130592             (eType==FTSQUERY_NEAR && !isPhrase && pPrev->eType!=FTSQUERY_PHRASE)
130593          || (eType!=FTSQUERY_PHRASE && isPhrase && pPrev->eType==FTSQUERY_NEAR)
130594         )){
130595           sqlite3Fts3ExprFree(p);
130596           rc = SQLITE_ERROR;
130597           goto exprparse_out;
130598         }
130599   
130600         if( isPhrase ){
130601           if( pRet ){
130602             assert( pPrev && pPrev->pLeft && pPrev->pRight==0 );
130603             pPrev->pRight = p;
130604             p->pParent = pPrev;
130605           }else{
130606             pRet = p;
130607           }
130608         }else{
130609           insertBinaryOperator(&pRet, pPrev, p);
130610         }
130611         isRequirePhrase = !isPhrase;
130612       }
130613       assert( nByte>0 );
130614     }
130615     assert( rc!=SQLITE_OK || (nByte>0 && nByte<=nIn) );
130616     nIn -= nByte;
130617     zIn += nByte;
130618     pPrev = p;
130619   }
130620 
130621   if( rc==SQLITE_DONE && pRet && isRequirePhrase ){
130622     rc = SQLITE_ERROR;
130623   }
130624 
130625   if( rc==SQLITE_DONE ){
130626     rc = SQLITE_OK;
130627     if( !sqlite3_fts3_enable_parentheses && pNotBranch ){
130628       if( !pRet ){
130629         rc = SQLITE_ERROR;
130630       }else{
130631         Fts3Expr *pIter = pNotBranch;
130632         while( pIter->pLeft ){
130633           pIter = pIter->pLeft;
130634         }
130635         pIter->pLeft = pRet;
130636         pRet->pParent = pIter;
130637         pRet = pNotBranch;
130638       }
130639     }
130640   }
130641   *pnConsumed = n - nIn;
130642 
130643 exprparse_out:
130644   if( rc!=SQLITE_OK ){
130645     sqlite3Fts3ExprFree(pRet);
130646     sqlite3Fts3ExprFree(pNotBranch);
130647     pRet = 0;
130648   }
130649   *ppExpr = pRet;
130650   return rc;
130651 }
130652 
130653 /*
130654 ** Return SQLITE_ERROR if the maximum depth of the expression tree passed 
130655 ** as the only argument is more than nMaxDepth.
130656 */
130657 static int fts3ExprCheckDepth(Fts3Expr *p, int nMaxDepth){
130658   int rc = SQLITE_OK;
130659   if( p ){
130660     if( nMaxDepth<0 ){ 
130661       rc = SQLITE_TOOBIG;
130662     }else{
130663       rc = fts3ExprCheckDepth(p->pLeft, nMaxDepth-1);
130664       if( rc==SQLITE_OK ){
130665         rc = fts3ExprCheckDepth(p->pRight, nMaxDepth-1);
130666       }
130667     }
130668   }
130669   return rc;
130670 }
130671 
130672 /*
130673 ** This function attempts to transform the expression tree at (*pp) to
130674 ** an equivalent but more balanced form. The tree is modified in place.
130675 ** If successful, SQLITE_OK is returned and (*pp) set to point to the 
130676 ** new root expression node. 
130677 **
130678 ** nMaxDepth is the maximum allowable depth of the balanced sub-tree.
130679 **
130680 ** Otherwise, if an error occurs, an SQLite error code is returned and 
130681 ** expression (*pp) freed.
130682 */
130683 static int fts3ExprBalance(Fts3Expr **pp, int nMaxDepth){
130684   int rc = SQLITE_OK;             /* Return code */
130685   Fts3Expr *pRoot = *pp;          /* Initial root node */
130686   Fts3Expr *pFree = 0;            /* List of free nodes. Linked by pParent. */
130687   int eType = pRoot->eType;       /* Type of node in this tree */
130688 
130689   if( nMaxDepth==0 ){
130690     rc = SQLITE_ERROR;
130691   }
130692 
130693   if( rc==SQLITE_OK && (eType==FTSQUERY_AND || eType==FTSQUERY_OR) ){
130694     Fts3Expr **apLeaf;
130695     apLeaf = (Fts3Expr **)sqlite3_malloc(sizeof(Fts3Expr *) * nMaxDepth);
130696     if( 0==apLeaf ){
130697       rc = SQLITE_NOMEM;
130698     }else{
130699       memset(apLeaf, 0, sizeof(Fts3Expr *) * nMaxDepth);
130700     }
130701 
130702     if( rc==SQLITE_OK ){
130703       int i;
130704       Fts3Expr *p;
130705 
130706       /* Set $p to point to the left-most leaf in the tree of eType nodes. */
130707       for(p=pRoot; p->eType==eType; p=p->pLeft){
130708         assert( p->pParent==0 || p->pParent->pLeft==p );
130709         assert( p->pLeft && p->pRight );
130710       }
130711 
130712       /* This loop runs once for each leaf in the tree of eType nodes. */
130713       while( 1 ){
130714         int iLvl;
130715         Fts3Expr *pParent = p->pParent;     /* Current parent of p */
130716 
130717         assert( pParent==0 || pParent->pLeft==p );
130718         p->pParent = 0;
130719         if( pParent ){
130720           pParent->pLeft = 0;
130721         }else{
130722           pRoot = 0;
130723         }
130724         rc = fts3ExprBalance(&p, nMaxDepth-1);
130725         if( rc!=SQLITE_OK ) break;
130726 
130727         for(iLvl=0; p && iLvl<nMaxDepth; iLvl++){
130728           if( apLeaf[iLvl]==0 ){
130729             apLeaf[iLvl] = p;
130730             p = 0;
130731           }else{
130732             assert( pFree );
130733             pFree->pLeft = apLeaf[iLvl];
130734             pFree->pRight = p;
130735             pFree->pLeft->pParent = pFree;
130736             pFree->pRight->pParent = pFree;
130737 
130738             p = pFree;
130739             pFree = pFree->pParent;
130740             p->pParent = 0;
130741             apLeaf[iLvl] = 0;
130742           }
130743         }
130744         if( p ){
130745           sqlite3Fts3ExprFree(p);
130746           rc = SQLITE_TOOBIG;
130747           break;
130748         }
130749 
130750         /* If that was the last leaf node, break out of the loop */
130751         if( pParent==0 ) break;
130752 
130753         /* Set $p to point to the next leaf in the tree of eType nodes */
130754         for(p=pParent->pRight; p->eType==eType; p=p->pLeft);
130755 
130756         /* Remove pParent from the original tree. */
130757         assert( pParent->pParent==0 || pParent->pParent->pLeft==pParent );
130758         pParent->pRight->pParent = pParent->pParent;
130759         if( pParent->pParent ){
130760           pParent->pParent->pLeft = pParent->pRight;
130761         }else{
130762           assert( pParent==pRoot );
130763           pRoot = pParent->pRight;
130764         }
130765 
130766         /* Link pParent into the free node list. It will be used as an
130767         ** internal node of the new tree.  */
130768         pParent->pParent = pFree;
130769         pFree = pParent;
130770       }
130771 
130772       if( rc==SQLITE_OK ){
130773         p = 0;
130774         for(i=0; i<nMaxDepth; i++){
130775           if( apLeaf[i] ){
130776             if( p==0 ){
130777               p = apLeaf[i];
130778               p->pParent = 0;
130779             }else{
130780               assert( pFree!=0 );
130781               pFree->pRight = p;
130782               pFree->pLeft = apLeaf[i];
130783               pFree->pLeft->pParent = pFree;
130784               pFree->pRight->pParent = pFree;
130785 
130786               p = pFree;
130787               pFree = pFree->pParent;
130788               p->pParent = 0;
130789             }
130790           }
130791         }
130792         pRoot = p;
130793       }else{
130794         /* An error occurred. Delete the contents of the apLeaf[] array 
130795         ** and pFree list. Everything else is cleaned up by the call to
130796         ** sqlite3Fts3ExprFree(pRoot) below.  */
130797         Fts3Expr *pDel;
130798         for(i=0; i<nMaxDepth; i++){
130799           sqlite3Fts3ExprFree(apLeaf[i]);
130800         }
130801         while( (pDel=pFree)!=0 ){
130802           pFree = pDel->pParent;
130803           sqlite3_free(pDel);
130804         }
130805       }
130806 
130807       assert( pFree==0 );
130808       sqlite3_free( apLeaf );
130809     }
130810   }
130811 
130812   if( rc!=SQLITE_OK ){
130813     sqlite3Fts3ExprFree(pRoot);
130814     pRoot = 0;
130815   }
130816   *pp = pRoot;
130817   return rc;
130818 }
130819 
130820 /*
130821 ** This function is similar to sqlite3Fts3ExprParse(), with the following
130822 ** differences:
130823 **
130824 **   1. It does not do expression rebalancing.
130825 **   2. It does not check that the expression does not exceed the 
130826 **      maximum allowable depth.
130827 **   3. Even if it fails, *ppExpr may still be set to point to an 
130828 **      expression tree. It should be deleted using sqlite3Fts3ExprFree()
130829 **      in this case.
130830 */
130831 static int fts3ExprParseUnbalanced(
130832   sqlite3_tokenizer *pTokenizer,      /* Tokenizer module */
130833   int iLangid,                        /* Language id for tokenizer */
130834   char **azCol,                       /* Array of column names for fts3 table */
130835   int bFts4,                          /* True to allow FTS4-only syntax */
130836   int nCol,                           /* Number of entries in azCol[] */
130837   int iDefaultCol,                    /* Default column to query */
130838   const char *z, int n,               /* Text of MATCH query */
130839   Fts3Expr **ppExpr                   /* OUT: Parsed query structure */
130840 ){
130841   int nParsed;
130842   int rc;
130843   ParseContext sParse;
130844 
130845   memset(&sParse, 0, sizeof(ParseContext));
130846   sParse.pTokenizer = pTokenizer;
130847   sParse.iLangid = iLangid;
130848   sParse.azCol = (const char **)azCol;
130849   sParse.nCol = nCol;
130850   sParse.iDefaultCol = iDefaultCol;
130851   sParse.bFts4 = bFts4;
130852   if( z==0 ){
130853     *ppExpr = 0;
130854     return SQLITE_OK;
130855   }
130856   if( n<0 ){
130857     n = (int)strlen(z);
130858   }
130859   rc = fts3ExprParse(&sParse, z, n, ppExpr, &nParsed);
130860   assert( rc==SQLITE_OK || *ppExpr==0 );
130861 
130862   /* Check for mismatched parenthesis */
130863   if( rc==SQLITE_OK && sParse.nNest ){
130864     rc = SQLITE_ERROR;
130865   }
130866   
130867   return rc;
130868 }
130869 
130870 /*
130871 ** Parameters z and n contain a pointer to and length of a buffer containing
130872 ** an fts3 query expression, respectively. This function attempts to parse the
130873 ** query expression and create a tree of Fts3Expr structures representing the
130874 ** parsed expression. If successful, *ppExpr is set to point to the head
130875 ** of the parsed expression tree and SQLITE_OK is returned. If an error
130876 ** occurs, either SQLITE_NOMEM (out-of-memory error) or SQLITE_ERROR (parse
130877 ** error) is returned and *ppExpr is set to 0.
130878 **
130879 ** If parameter n is a negative number, then z is assumed to point to a
130880 ** nul-terminated string and the length is determined using strlen().
130881 **
130882 ** The first parameter, pTokenizer, is passed the fts3 tokenizer module to
130883 ** use to normalize query tokens while parsing the expression. The azCol[]
130884 ** array, which is assumed to contain nCol entries, should contain the names
130885 ** of each column in the target fts3 table, in order from left to right. 
130886 ** Column names must be nul-terminated strings.
130887 **
130888 ** The iDefaultCol parameter should be passed the index of the table column
130889 ** that appears on the left-hand-side of the MATCH operator (the default
130890 ** column to match against for tokens for which a column name is not explicitly
130891 ** specified as part of the query string), or -1 if tokens may by default
130892 ** match any table column.
130893 */
130894 SQLITE_PRIVATE int sqlite3Fts3ExprParse(
130895   sqlite3_tokenizer *pTokenizer,      /* Tokenizer module */
130896   int iLangid,                        /* Language id for tokenizer */
130897   char **azCol,                       /* Array of column names for fts3 table */
130898   int bFts4,                          /* True to allow FTS4-only syntax */
130899   int nCol,                           /* Number of entries in azCol[] */
130900   int iDefaultCol,                    /* Default column to query */
130901   const char *z, int n,               /* Text of MATCH query */
130902   Fts3Expr **ppExpr,                  /* OUT: Parsed query structure */
130903   char **pzErr                        /* OUT: Error message (sqlite3_malloc) */
130904 ){
130905   int rc = fts3ExprParseUnbalanced(
130906       pTokenizer, iLangid, azCol, bFts4, nCol, iDefaultCol, z, n, ppExpr
130907   );
130908   
130909   /* Rebalance the expression. And check that its depth does not exceed
130910   ** SQLITE_FTS3_MAX_EXPR_DEPTH.  */
130911   if( rc==SQLITE_OK && *ppExpr ){
130912     rc = fts3ExprBalance(ppExpr, SQLITE_FTS3_MAX_EXPR_DEPTH);
130913     if( rc==SQLITE_OK ){
130914       rc = fts3ExprCheckDepth(*ppExpr, SQLITE_FTS3_MAX_EXPR_DEPTH);
130915     }
130916   }
130917 
130918   if( rc!=SQLITE_OK ){
130919     sqlite3Fts3ExprFree(*ppExpr);
130920     *ppExpr = 0;
130921     if( rc==SQLITE_TOOBIG ){
130922       *pzErr = sqlite3_mprintf(
130923           "FTS expression tree is too large (maximum depth %d)", 
130924           SQLITE_FTS3_MAX_EXPR_DEPTH
130925       );
130926       rc = SQLITE_ERROR;
130927     }else if( rc==SQLITE_ERROR ){
130928       *pzErr = sqlite3_mprintf("malformed MATCH expression: [%s]", z);
130929     }
130930   }
130931 
130932   return rc;
130933 }
130934 
130935 /*
130936 ** Free a single node of an expression tree.
130937 */
130938 static void fts3FreeExprNode(Fts3Expr *p){
130939   assert( p->eType==FTSQUERY_PHRASE || p->pPhrase==0 );
130940   sqlite3Fts3EvalPhraseCleanup(p->pPhrase);
130941   sqlite3_free(p->aMI);
130942   sqlite3_free(p);
130943 }
130944 
130945 /*
130946 ** Free a parsed fts3 query expression allocated by sqlite3Fts3ExprParse().
130947 **
130948 ** This function would be simpler if it recursively called itself. But
130949 ** that would mean passing a sufficiently large expression to ExprParse()
130950 ** could cause a stack overflow.
130951 */
130952 SQLITE_PRIVATE void sqlite3Fts3ExprFree(Fts3Expr *pDel){
130953   Fts3Expr *p;
130954   assert( pDel==0 || pDel->pParent==0 );
130955   for(p=pDel; p && (p->pLeft||p->pRight); p=(p->pLeft ? p->pLeft : p->pRight)){
130956     assert( p->pParent==0 || p==p->pParent->pRight || p==p->pParent->pLeft );
130957   }
130958   while( p ){
130959     Fts3Expr *pParent = p->pParent;
130960     fts3FreeExprNode(p);
130961     if( pParent && p==pParent->pLeft && pParent->pRight ){
130962       p = pParent->pRight;
130963       while( p && (p->pLeft || p->pRight) ){
130964         assert( p==p->pParent->pRight || p==p->pParent->pLeft );
130965         p = (p->pLeft ? p->pLeft : p->pRight);
130966       }
130967     }else{
130968       p = pParent;
130969     }
130970   }
130971 }
130972 
130973 /****************************************************************************
130974 *****************************************************************************
130975 ** Everything after this point is just test code.
130976 */
130977 
130978 #ifdef SQLITE_TEST
130979 
130980 /* #include <stdio.h> */
130981 
130982 /*
130983 ** Function to query the hash-table of tokenizers (see README.tokenizers).
130984 */
130985 static int queryTestTokenizer(
130986   sqlite3 *db, 
130987   const char *zName,  
130988   const sqlite3_tokenizer_module **pp
130989 ){
130990   int rc;
130991   sqlite3_stmt *pStmt;
130992   const char zSql[] = "SELECT fts3_tokenizer(?)";
130993 
130994   *pp = 0;
130995   rc = sqlite3_prepare_v2(db, zSql, -1, &pStmt, 0);
130996   if( rc!=SQLITE_OK ){
130997     return rc;
130998   }
130999 
131000   sqlite3_bind_text(pStmt, 1, zName, -1, SQLITE_STATIC);
131001   if( SQLITE_ROW==sqlite3_step(pStmt) ){
131002     if( sqlite3_column_type(pStmt, 0)==SQLITE_BLOB ){
131003       memcpy((void *)pp, sqlite3_column_blob(pStmt, 0), sizeof(*pp));
131004     }
131005   }
131006 
131007   return sqlite3_finalize(pStmt);
131008 }
131009 
131010 /*
131011 ** Return a pointer to a buffer containing a text representation of the
131012 ** expression passed as the first argument. The buffer is obtained from
131013 ** sqlite3_malloc(). It is the responsibility of the caller to use 
131014 ** sqlite3_free() to release the memory. If an OOM condition is encountered,
131015 ** NULL is returned.
131016 **
131017 ** If the second argument is not NULL, then its contents are prepended to 
131018 ** the returned expression text and then freed using sqlite3_free().
131019 */
131020 static char *exprToString(Fts3Expr *pExpr, char *zBuf){
131021   if( pExpr==0 ){
131022     return sqlite3_mprintf("");
131023   }
131024   switch( pExpr->eType ){
131025     case FTSQUERY_PHRASE: {
131026       Fts3Phrase *pPhrase = pExpr->pPhrase;
131027       int i;
131028       zBuf = sqlite3_mprintf(
131029           "%zPHRASE %d 0", zBuf, pPhrase->iColumn);
131030       for(i=0; zBuf && i<pPhrase->nToken; i++){
131031         zBuf = sqlite3_mprintf("%z %.*s%s", zBuf, 
131032             pPhrase->aToken[i].n, pPhrase->aToken[i].z,
131033             (pPhrase->aToken[i].isPrefix?"+":"")
131034         );
131035       }
131036       return zBuf;
131037     }
131038 
131039     case FTSQUERY_NEAR:
131040       zBuf = sqlite3_mprintf("%zNEAR/%d ", zBuf, pExpr->nNear);
131041       break;
131042     case FTSQUERY_NOT:
131043       zBuf = sqlite3_mprintf("%zNOT ", zBuf);
131044       break;
131045     case FTSQUERY_AND:
131046       zBuf = sqlite3_mprintf("%zAND ", zBuf);
131047       break;
131048     case FTSQUERY_OR:
131049       zBuf = sqlite3_mprintf("%zOR ", zBuf);
131050       break;
131051   }
131052 
131053   if( zBuf ) zBuf = sqlite3_mprintf("%z{", zBuf);
131054   if( zBuf ) zBuf = exprToString(pExpr->pLeft, zBuf);
131055   if( zBuf ) zBuf = sqlite3_mprintf("%z} {", zBuf);
131056 
131057   if( zBuf ) zBuf = exprToString(pExpr->pRight, zBuf);
131058   if( zBuf ) zBuf = sqlite3_mprintf("%z}", zBuf);
131059 
131060   return zBuf;
131061 }
131062 
131063 /*
131064 ** This is the implementation of a scalar SQL function used to test the 
131065 ** expression parser. It should be called as follows:
131066 **
131067 **   fts3_exprtest(<tokenizer>, <expr>, <column 1>, ...);
131068 **
131069 ** The first argument, <tokenizer>, is the name of the fts3 tokenizer used
131070 ** to parse the query expression (see README.tokenizers). The second argument
131071 ** is the query expression to parse. Each subsequent argument is the name
131072 ** of a column of the fts3 table that the query expression may refer to.
131073 ** For example:
131074 **
131075 **   SELECT fts3_exprtest('simple', 'Bill col2:Bloggs', 'col1', 'col2');
131076 */
131077 static void fts3ExprTest(
131078   sqlite3_context *context,
131079   int argc,
131080   sqlite3_value **argv
131081 ){
131082   sqlite3_tokenizer_module const *pModule = 0;
131083   sqlite3_tokenizer *pTokenizer = 0;
131084   int rc;
131085   char **azCol = 0;
131086   const char *zExpr;
131087   int nExpr;
131088   int nCol;
131089   int ii;
131090   Fts3Expr *pExpr;
131091   char *zBuf = 0;
131092   sqlite3 *db = sqlite3_context_db_handle(context);
131093 
131094   if( argc<3 ){
131095     sqlite3_result_error(context, 
131096         "Usage: fts3_exprtest(tokenizer, expr, col1, ...", -1
131097     );
131098     return;
131099   }
131100 
131101   rc = queryTestTokenizer(db,
131102                           (const char *)sqlite3_value_text(argv[0]), &pModule);
131103   if( rc==SQLITE_NOMEM ){
131104     sqlite3_result_error_nomem(context);
131105     goto exprtest_out;
131106   }else if( !pModule ){
131107     sqlite3_result_error(context, "No such tokenizer module", -1);
131108     goto exprtest_out;
131109   }
131110 
131111   rc = pModule->xCreate(0, 0, &pTokenizer);
131112   assert( rc==SQLITE_NOMEM || rc==SQLITE_OK );
131113   if( rc==SQLITE_NOMEM ){
131114     sqlite3_result_error_nomem(context);
131115     goto exprtest_out;
131116   }
131117   pTokenizer->pModule = pModule;
131118 
131119   zExpr = (const char *)sqlite3_value_text(argv[1]);
131120   nExpr = sqlite3_value_bytes(argv[1]);
131121   nCol = argc-2;
131122   azCol = (char **)sqlite3_malloc(nCol*sizeof(char *));
131123   if( !azCol ){
131124     sqlite3_result_error_nomem(context);
131125     goto exprtest_out;
131126   }
131127   for(ii=0; ii<nCol; ii++){
131128     azCol[ii] = (char *)sqlite3_value_text(argv[ii+2]);
131129   }
131130 
131131   if( sqlite3_user_data(context) ){
131132     char *zDummy = 0;
131133     rc = sqlite3Fts3ExprParse(
131134         pTokenizer, 0, azCol, 0, nCol, nCol, zExpr, nExpr, &pExpr, &zDummy
131135     );
131136     assert( rc==SQLITE_OK || pExpr==0 );
131137     sqlite3_free(zDummy);
131138   }else{
131139     rc = fts3ExprParseUnbalanced(
131140         pTokenizer, 0, azCol, 0, nCol, nCol, zExpr, nExpr, &pExpr
131141     );
131142   }
131143 
131144   if( rc!=SQLITE_OK && rc!=SQLITE_NOMEM ){
131145     sqlite3Fts3ExprFree(pExpr);
131146     sqlite3_result_error(context, "Error parsing expression", -1);
131147   }else if( rc==SQLITE_NOMEM || !(zBuf = exprToString(pExpr, 0)) ){
131148     sqlite3_result_error_nomem(context);
131149   }else{
131150     sqlite3_result_text(context, zBuf, -1, SQLITE_TRANSIENT);
131151     sqlite3_free(zBuf);
131152   }
131153 
131154   sqlite3Fts3ExprFree(pExpr);
131155 
131156 exprtest_out:
131157   if( pModule && pTokenizer ){
131158     rc = pModule->xDestroy(pTokenizer);
131159   }
131160   sqlite3_free(azCol);
131161 }
131162 
131163 /*
131164 ** Register the query expression parser test function fts3_exprtest() 
131165 ** with database connection db. 
131166 */
131167 SQLITE_PRIVATE int sqlite3Fts3ExprInitTestInterface(sqlite3* db){
131168   int rc = sqlite3_create_function(
131169       db, "fts3_exprtest", -1, SQLITE_UTF8, 0, fts3ExprTest, 0, 0
131170   );
131171   if( rc==SQLITE_OK ){
131172     rc = sqlite3_create_function(db, "fts3_exprtest_rebalance", 
131173         -1, SQLITE_UTF8, (void *)1, fts3ExprTest, 0, 0
131174     );
131175   }
131176   return rc;
131177 }
131178 
131179 #endif
131180 #endif /* !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_FTS3) */
131181 
131182 /************** End of fts3_expr.c *******************************************/
131183 /************** Begin file fts3_hash.c ***************************************/
131184 /*
131185 ** 2001 September 22
131186 **
131187 ** The author disclaims copyright to this source code.  In place of
131188 ** a legal notice, here is a blessing:
131189 **
131190 **    May you do good and not evil.
131191 **    May you find forgiveness for yourself and forgive others.
131192 **    May you share freely, never taking more than you give.
131193 **
131194 *************************************************************************
131195 ** This is the implementation of generic hash-tables used in SQLite.
131196 ** We've modified it slightly to serve as a standalone hash table
131197 ** implementation for the full-text indexing module.
131198 */
131199 
131200 /*
131201 ** The code in this file is only compiled if:
131202 **
131203 **     * The FTS3 module is being built as an extension
131204 **       (in which case SQLITE_CORE is not defined), or
131205 **
131206 **     * The FTS3 module is being built into the core of
131207 **       SQLite (in which case SQLITE_ENABLE_FTS3 is defined).
131208 */
131209 #if !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_FTS3)
131210 
131211 /* #include <assert.h> */
131212 /* #include <stdlib.h> */
131213 /* #include <string.h> */
131214 
131215 
131216 /*
131217 ** Malloc and Free functions
131218 */
131219 static void *fts3HashMalloc(int n){
131220   void *p = sqlite3_malloc(n);
131221   if( p ){
131222     memset(p, 0, n);
131223   }
131224   return p;
131225 }
131226 static void fts3HashFree(void *p){
131227   sqlite3_free(p);
131228 }
131229 
131230 /* Turn bulk memory into a hash table object by initializing the
131231 ** fields of the Hash structure.
131232 **
131233 ** "pNew" is a pointer to the hash table that is to be initialized.
131234 ** keyClass is one of the constants 
131235 ** FTS3_HASH_BINARY or FTS3_HASH_STRING.  The value of keyClass 
131236 ** determines what kind of key the hash table will use.  "copyKey" is
131237 ** true if the hash table should make its own private copy of keys and
131238 ** false if it should just use the supplied pointer.
131239 */
131240 SQLITE_PRIVATE void sqlite3Fts3HashInit(Fts3Hash *pNew, char keyClass, char copyKey){
131241   assert( pNew!=0 );
131242   assert( keyClass>=FTS3_HASH_STRING && keyClass<=FTS3_HASH_BINARY );
131243   pNew->keyClass = keyClass;
131244   pNew->copyKey = copyKey;
131245   pNew->first = 0;
131246   pNew->count = 0;
131247   pNew->htsize = 0;
131248   pNew->ht = 0;
131249 }
131250 
131251 /* Remove all entries from a hash table.  Reclaim all memory.
131252 ** Call this routine to delete a hash table or to reset a hash table
131253 ** to the empty state.
131254 */
131255 SQLITE_PRIVATE void sqlite3Fts3HashClear(Fts3Hash *pH){
131256   Fts3HashElem *elem;         /* For looping over all elements of the table */
131257 
131258   assert( pH!=0 );
131259   elem = pH->first;
131260   pH->first = 0;
131261   fts3HashFree(pH->ht);
131262   pH->ht = 0;
131263   pH->htsize = 0;
131264   while( elem ){
131265     Fts3HashElem *next_elem = elem->next;
131266     if( pH->copyKey && elem->pKey ){
131267       fts3HashFree(elem->pKey);
131268     }
131269     fts3HashFree(elem);
131270     elem = next_elem;
131271   }
131272   pH->count = 0;
131273 }
131274 
131275 /*
131276 ** Hash and comparison functions when the mode is FTS3_HASH_STRING
131277 */
131278 static int fts3StrHash(const void *pKey, int nKey){
131279   const char *z = (const char *)pKey;
131280   int h = 0;
131281   if( nKey<=0 ) nKey = (int) strlen(z);
131282   while( nKey > 0  ){
131283     h = (h<<3) ^ h ^ *z++;
131284     nKey--;
131285   }
131286   return h & 0x7fffffff;
131287 }
131288 static int fts3StrCompare(const void *pKey1, int n1, const void *pKey2, int n2){
131289   if( n1!=n2 ) return 1;
131290   return strncmp((const char*)pKey1,(const char*)pKey2,n1);
131291 }
131292 
131293 /*
131294 ** Hash and comparison functions when the mode is FTS3_HASH_BINARY
131295 */
131296 static int fts3BinHash(const void *pKey, int nKey){
131297   int h = 0;
131298   const char *z = (const char *)pKey;
131299   while( nKey-- > 0 ){
131300     h = (h<<3) ^ h ^ *(z++);
131301   }
131302   return h & 0x7fffffff;
131303 }
131304 static int fts3BinCompare(const void *pKey1, int n1, const void *pKey2, int n2){
131305   if( n1!=n2 ) return 1;
131306   return memcmp(pKey1,pKey2,n1);
131307 }
131308 
131309 /*
131310 ** Return a pointer to the appropriate hash function given the key class.
131311 **
131312 ** The C syntax in this function definition may be unfamilar to some 
131313 ** programmers, so we provide the following additional explanation:
131314 **
131315 ** The name of the function is "ftsHashFunction".  The function takes a
131316 ** single parameter "keyClass".  The return value of ftsHashFunction()
131317 ** is a pointer to another function.  Specifically, the return value
131318 ** of ftsHashFunction() is a pointer to a function that takes two parameters
131319 ** with types "const void*" and "int" and returns an "int".
131320 */
131321 static int (*ftsHashFunction(int keyClass))(const void*,int){
131322   if( keyClass==FTS3_HASH_STRING ){
131323     return &fts3StrHash;
131324   }else{
131325     assert( keyClass==FTS3_HASH_BINARY );
131326     return &fts3BinHash;
131327   }
131328 }
131329 
131330 /*
131331 ** Return a pointer to the appropriate hash function given the key class.
131332 **
131333 ** For help in interpreted the obscure C code in the function definition,
131334 ** see the header comment on the previous function.
131335 */
131336 static int (*ftsCompareFunction(int keyClass))(const void*,int,const void*,int){
131337   if( keyClass==FTS3_HASH_STRING ){
131338     return &fts3StrCompare;
131339   }else{
131340     assert( keyClass==FTS3_HASH_BINARY );
131341     return &fts3BinCompare;
131342   }
131343 }
131344 
131345 /* Link an element into the hash table
131346 */
131347 static void fts3HashInsertElement(
131348   Fts3Hash *pH,            /* The complete hash table */
131349   struct _fts3ht *pEntry,  /* The entry into which pNew is inserted */
131350   Fts3HashElem *pNew       /* The element to be inserted */
131351 ){
131352   Fts3HashElem *pHead;     /* First element already in pEntry */
131353   pHead = pEntry->chain;
131354   if( pHead ){
131355     pNew->next = pHead;
131356     pNew->prev = pHead->prev;
131357     if( pHead->prev ){ pHead->prev->next = pNew; }
131358     else             { pH->first = pNew; }
131359     pHead->prev = pNew;
131360   }else{
131361     pNew->next = pH->first;
131362     if( pH->first ){ pH->first->prev = pNew; }
131363     pNew->prev = 0;
131364     pH->first = pNew;
131365   }
131366   pEntry->count++;
131367   pEntry->chain = pNew;
131368 }
131369 
131370 
131371 /* Resize the hash table so that it cantains "new_size" buckets.
131372 ** "new_size" must be a power of 2.  The hash table might fail 
131373 ** to resize if sqliteMalloc() fails.
131374 **
131375 ** Return non-zero if a memory allocation error occurs.
131376 */
131377 static int fts3Rehash(Fts3Hash *pH, int new_size){
131378   struct _fts3ht *new_ht;          /* The new hash table */
131379   Fts3HashElem *elem, *next_elem;  /* For looping over existing elements */
131380   int (*xHash)(const void*,int);   /* The hash function */
131381 
131382   assert( (new_size & (new_size-1))==0 );
131383   new_ht = (struct _fts3ht *)fts3HashMalloc( new_size*sizeof(struct _fts3ht) );
131384   if( new_ht==0 ) return 1;
131385   fts3HashFree(pH->ht);
131386   pH->ht = new_ht;
131387   pH->htsize = new_size;
131388   xHash = ftsHashFunction(pH->keyClass);
131389   for(elem=pH->first, pH->first=0; elem; elem = next_elem){
131390     int h = (*xHash)(elem->pKey, elem->nKey) & (new_size-1);
131391     next_elem = elem->next;
131392     fts3HashInsertElement(pH, &new_ht[h], elem);
131393   }
131394   return 0;
131395 }
131396 
131397 /* This function (for internal use only) locates an element in an
131398 ** hash table that matches the given key.  The hash for this key has
131399 ** already been computed and is passed as the 4th parameter.
131400 */
131401 static Fts3HashElem *fts3FindElementByHash(
131402   const Fts3Hash *pH, /* The pH to be searched */
131403   const void *pKey,   /* The key we are searching for */
131404   int nKey,
131405   int h               /* The hash for this key. */
131406 ){
131407   Fts3HashElem *elem;            /* Used to loop thru the element list */
131408   int count;                     /* Number of elements left to test */
131409   int (*xCompare)(const void*,int,const void*,int);  /* comparison function */
131410 
131411   if( pH->ht ){
131412     struct _fts3ht *pEntry = &pH->ht[h];
131413     elem = pEntry->chain;
131414     count = pEntry->count;
131415     xCompare = ftsCompareFunction(pH->keyClass);
131416     while( count-- && elem ){
131417       if( (*xCompare)(elem->pKey,elem->nKey,pKey,nKey)==0 ){ 
131418         return elem;
131419       }
131420       elem = elem->next;
131421     }
131422   }
131423   return 0;
131424 }
131425 
131426 /* Remove a single entry from the hash table given a pointer to that
131427 ** element and a hash on the element's key.
131428 */
131429 static void fts3RemoveElementByHash(
131430   Fts3Hash *pH,         /* The pH containing "elem" */
131431   Fts3HashElem* elem,   /* The element to be removed from the pH */
131432   int h                 /* Hash value for the element */
131433 ){
131434   struct _fts3ht *pEntry;
131435   if( elem->prev ){
131436     elem->prev->next = elem->next; 
131437   }else{
131438     pH->first = elem->next;
131439   }
131440   if( elem->next ){
131441     elem->next->prev = elem->prev;
131442   }
131443   pEntry = &pH->ht[h];
131444   if( pEntry->chain==elem ){
131445     pEntry->chain = elem->next;
131446   }
131447   pEntry->count--;
131448   if( pEntry->count<=0 ){
131449     pEntry->chain = 0;
131450   }
131451   if( pH->copyKey && elem->pKey ){
131452     fts3HashFree(elem->pKey);
131453   }
131454   fts3HashFree( elem );
131455   pH->count--;
131456   if( pH->count<=0 ){
131457     assert( pH->first==0 );
131458     assert( pH->count==0 );
131459     fts3HashClear(pH);
131460   }
131461 }
131462 
131463 SQLITE_PRIVATE Fts3HashElem *sqlite3Fts3HashFindElem(
131464   const Fts3Hash *pH, 
131465   const void *pKey, 
131466   int nKey
131467 ){
131468   int h;                          /* A hash on key */
131469   int (*xHash)(const void*,int);  /* The hash function */
131470 
131471   if( pH==0 || pH->ht==0 ) return 0;
131472   xHash = ftsHashFunction(pH->keyClass);
131473   assert( xHash!=0 );
131474   h = (*xHash)(pKey,nKey);
131475   assert( (pH->htsize & (pH->htsize-1))==0 );
131476   return fts3FindElementByHash(pH,pKey,nKey, h & (pH->htsize-1));
131477 }
131478 
131479 /* 
131480 ** Attempt to locate an element of the hash table pH with a key
131481 ** that matches pKey,nKey.  Return the data for this element if it is
131482 ** found, or NULL if there is no match.
131483 */
131484 SQLITE_PRIVATE void *sqlite3Fts3HashFind(const Fts3Hash *pH, const void *pKey, int nKey){
131485   Fts3HashElem *pElem;            /* The element that matches key (if any) */
131486 
131487   pElem = sqlite3Fts3HashFindElem(pH, pKey, nKey);
131488   return pElem ? pElem->data : 0;
131489 }
131490 
131491 /* Insert an element into the hash table pH.  The key is pKey,nKey
131492 ** and the data is "data".
131493 **
131494 ** If no element exists with a matching key, then a new
131495 ** element is created.  A copy of the key is made if the copyKey
131496 ** flag is set.  NULL is returned.
131497 **
131498 ** If another element already exists with the same key, then the
131499 ** new data replaces the old data and the old data is returned.
131500 ** The key is not copied in this instance.  If a malloc fails, then
131501 ** the new data is returned and the hash table is unchanged.
131502 **
131503 ** If the "data" parameter to this function is NULL, then the
131504 ** element corresponding to "key" is removed from the hash table.
131505 */
131506 SQLITE_PRIVATE void *sqlite3Fts3HashInsert(
131507   Fts3Hash *pH,        /* The hash table to insert into */
131508   const void *pKey,    /* The key */
131509   int nKey,            /* Number of bytes in the key */
131510   void *data           /* The data */
131511 ){
131512   int hraw;                 /* Raw hash value of the key */
131513   int h;                    /* the hash of the key modulo hash table size */
131514   Fts3HashElem *elem;       /* Used to loop thru the element list */
131515   Fts3HashElem *new_elem;   /* New element added to the pH */
131516   int (*xHash)(const void*,int);  /* The hash function */
131517 
131518   assert( pH!=0 );
131519   xHash = ftsHashFunction(pH->keyClass);
131520   assert( xHash!=0 );
131521   hraw = (*xHash)(pKey, nKey);
131522   assert( (pH->htsize & (pH->htsize-1))==0 );
131523   h = hraw & (pH->htsize-1);
131524   elem = fts3FindElementByHash(pH,pKey,nKey,h);
131525   if( elem ){
131526     void *old_data = elem->data;
131527     if( data==0 ){
131528       fts3RemoveElementByHash(pH,elem,h);
131529     }else{
131530       elem->data = data;
131531     }
131532     return old_data;
131533   }
131534   if( data==0 ) return 0;
131535   if( (pH->htsize==0 && fts3Rehash(pH,8))
131536    || (pH->count>=pH->htsize && fts3Rehash(pH, pH->htsize*2))
131537   ){
131538     pH->count = 0;
131539     return data;
131540   }
131541   assert( pH->htsize>0 );
131542   new_elem = (Fts3HashElem*)fts3HashMalloc( sizeof(Fts3HashElem) );
131543   if( new_elem==0 ) return data;
131544   if( pH->copyKey && pKey!=0 ){
131545     new_elem->pKey = fts3HashMalloc( nKey );
131546     if( new_elem->pKey==0 ){
131547       fts3HashFree(new_elem);
131548       return data;
131549     }
131550     memcpy((void*)new_elem->pKey, pKey, nKey);
131551   }else{
131552     new_elem->pKey = (void*)pKey;
131553   }
131554   new_elem->nKey = nKey;
131555   pH->count++;
131556   assert( pH->htsize>0 );
131557   assert( (pH->htsize & (pH->htsize-1))==0 );
131558   h = hraw & (pH->htsize-1);
131559   fts3HashInsertElement(pH, &pH->ht[h], new_elem);
131560   new_elem->data = data;
131561   return 0;
131562 }
131563 
131564 #endif /* !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_FTS3) */
131565 
131566 /************** End of fts3_hash.c *******************************************/
131567 /************** Begin file fts3_porter.c *************************************/
131568 /*
131569 ** 2006 September 30
131570 **
131571 ** The author disclaims copyright to this source code.  In place of
131572 ** a legal notice, here is a blessing:
131573 **
131574 **    May you do good and not evil.
131575 **    May you find forgiveness for yourself and forgive others.
131576 **    May you share freely, never taking more than you give.
131577 **
131578 *************************************************************************
131579 ** Implementation of the full-text-search tokenizer that implements
131580 ** a Porter stemmer.
131581 */
131582 
131583 /*
131584 ** The code in this file is only compiled if:
131585 **
131586 **     * The FTS3 module is being built as an extension
131587 **       (in which case SQLITE_CORE is not defined), or
131588 **
131589 **     * The FTS3 module is being built into the core of
131590 **       SQLite (in which case SQLITE_ENABLE_FTS3 is defined).
131591 */
131592 #if !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_FTS3)
131593 
131594 /* #include <assert.h> */
131595 /* #include <stdlib.h> */
131596 /* #include <stdio.h> */
131597 /* #include <string.h> */
131598 
131599 
131600 /*
131601 ** Class derived from sqlite3_tokenizer
131602 */
131603 typedef struct porter_tokenizer {
131604   sqlite3_tokenizer base;      /* Base class */
131605 } porter_tokenizer;
131606 
131607 /*
131608 ** Class derived from sqlite3_tokenizer_cursor
131609 */
131610 typedef struct porter_tokenizer_cursor {
131611   sqlite3_tokenizer_cursor base;
131612   const char *zInput;          /* input we are tokenizing */
131613   int nInput;                  /* size of the input */
131614   int iOffset;                 /* current position in zInput */
131615   int iToken;                  /* index of next token to be returned */
131616   char *zToken;                /* storage for current token */
131617   int nAllocated;              /* space allocated to zToken buffer */
131618 } porter_tokenizer_cursor;
131619 
131620 
131621 /*
131622 ** Create a new tokenizer instance.
131623 */
131624 static int porterCreate(
131625   int argc, const char * const *argv,
131626   sqlite3_tokenizer **ppTokenizer
131627 ){
131628   porter_tokenizer *t;
131629 
131630   UNUSED_PARAMETER(argc);
131631   UNUSED_PARAMETER(argv);
131632 
131633   t = (porter_tokenizer *) sqlite3_malloc(sizeof(*t));
131634   if( t==NULL ) return SQLITE_NOMEM;
131635   memset(t, 0, sizeof(*t));
131636   *ppTokenizer = &t->base;
131637   return SQLITE_OK;
131638 }
131639 
131640 /*
131641 ** Destroy a tokenizer
131642 */
131643 static int porterDestroy(sqlite3_tokenizer *pTokenizer){
131644   sqlite3_free(pTokenizer);
131645   return SQLITE_OK;
131646 }
131647 
131648 /*
131649 ** Prepare to begin tokenizing a particular string.  The input
131650 ** string to be tokenized is zInput[0..nInput-1].  A cursor
131651 ** used to incrementally tokenize this string is returned in 
131652 ** *ppCursor.
131653 */
131654 static int porterOpen(
131655   sqlite3_tokenizer *pTokenizer,         /* The tokenizer */
131656   const char *zInput, int nInput,        /* String to be tokenized */
131657   sqlite3_tokenizer_cursor **ppCursor    /* OUT: Tokenization cursor */
131658 ){
131659   porter_tokenizer_cursor *c;
131660 
131661   UNUSED_PARAMETER(pTokenizer);
131662 
131663   c = (porter_tokenizer_cursor *) sqlite3_malloc(sizeof(*c));
131664   if( c==NULL ) return SQLITE_NOMEM;
131665 
131666   c->zInput = zInput;
131667   if( zInput==0 ){
131668     c->nInput = 0;
131669   }else if( nInput<0 ){
131670     c->nInput = (int)strlen(zInput);
131671   }else{
131672     c->nInput = nInput;
131673   }
131674   c->iOffset = 0;                 /* start tokenizing at the beginning */
131675   c->iToken = 0;
131676   c->zToken = NULL;               /* no space allocated, yet. */
131677   c->nAllocated = 0;
131678 
131679   *ppCursor = &c->base;
131680   return SQLITE_OK;
131681 }
131682 
131683 /*
131684 ** Close a tokenization cursor previously opened by a call to
131685 ** porterOpen() above.
131686 */
131687 static int porterClose(sqlite3_tokenizer_cursor *pCursor){
131688   porter_tokenizer_cursor *c = (porter_tokenizer_cursor *) pCursor;
131689   sqlite3_free(c->zToken);
131690   sqlite3_free(c);
131691   return SQLITE_OK;
131692 }
131693 /*
131694 ** Vowel or consonant
131695 */
131696 static const char cType[] = {
131697    0, 1, 1, 1, 0, 1, 1, 1, 0, 1, 1, 1, 1, 1, 0, 1, 1, 1, 1, 1, 0,
131698    1, 1, 1, 2, 1
131699 };
131700 
131701 /*
131702 ** isConsonant() and isVowel() determine if their first character in
131703 ** the string they point to is a consonant or a vowel, according
131704 ** to Porter ruls.  
131705 **
131706 ** A consonate is any letter other than 'a', 'e', 'i', 'o', or 'u'.
131707 ** 'Y' is a consonant unless it follows another consonant,
131708 ** in which case it is a vowel.
131709 **
131710 ** In these routine, the letters are in reverse order.  So the 'y' rule
131711 ** is that 'y' is a consonant unless it is followed by another
131712 ** consonent.
131713 */
131714 static int isVowel(const char*);
131715 static int isConsonant(const char *z){
131716   int j;
131717   char x = *z;
131718   if( x==0 ) return 0;
131719   assert( x>='a' && x<='z' );
131720   j = cType[x-'a'];
131721   if( j<2 ) return j;
131722   return z[1]==0 || isVowel(z + 1);
131723 }
131724 static int isVowel(const char *z){
131725   int j;
131726   char x = *z;
131727   if( x==0 ) return 0;
131728   assert( x>='a' && x<='z' );
131729   j = cType[x-'a'];
131730   if( j<2 ) return 1-j;
131731   return isConsonant(z + 1);
131732 }
131733 
131734 /*
131735 ** Let any sequence of one or more vowels be represented by V and let
131736 ** C be sequence of one or more consonants.  Then every word can be
131737 ** represented as:
131738 **
131739 **           [C] (VC){m} [V]
131740 **
131741 ** In prose:  A word is an optional consonant followed by zero or
131742 ** vowel-consonant pairs followed by an optional vowel.  "m" is the
131743 ** number of vowel consonant pairs.  This routine computes the value
131744 ** of m for the first i bytes of a word.
131745 **
131746 ** Return true if the m-value for z is 1 or more.  In other words,
131747 ** return true if z contains at least one vowel that is followed
131748 ** by a consonant.
131749 **
131750 ** In this routine z[] is in reverse order.  So we are really looking
131751 ** for an instance of of a consonant followed by a vowel.
131752 */
131753 static int m_gt_0(const char *z){
131754   while( isVowel(z) ){ z++; }
131755   if( *z==0 ) return 0;
131756   while( isConsonant(z) ){ z++; }
131757   return *z!=0;
131758 }
131759 
131760 /* Like mgt0 above except we are looking for a value of m which is
131761 ** exactly 1
131762 */
131763 static int m_eq_1(const char *z){
131764   while( isVowel(z) ){ z++; }
131765   if( *z==0 ) return 0;
131766   while( isConsonant(z) ){ z++; }
131767   if( *z==0 ) return 0;
131768   while( isVowel(z) ){ z++; }
131769   if( *z==0 ) return 1;
131770   while( isConsonant(z) ){ z++; }
131771   return *z==0;
131772 }
131773 
131774 /* Like mgt0 above except we are looking for a value of m>1 instead
131775 ** or m>0
131776 */
131777 static int m_gt_1(const char *z){
131778   while( isVowel(z) ){ z++; }
131779   if( *z==0 ) return 0;
131780   while( isConsonant(z) ){ z++; }
131781   if( *z==0 ) return 0;
131782   while( isVowel(z) ){ z++; }
131783   if( *z==0 ) return 0;
131784   while( isConsonant(z) ){ z++; }
131785   return *z!=0;
131786 }
131787 
131788 /*
131789 ** Return TRUE if there is a vowel anywhere within z[0..n-1]
131790 */
131791 static int hasVowel(const char *z){
131792   while( isConsonant(z) ){ z++; }
131793   return *z!=0;
131794 }
131795 
131796 /*
131797 ** Return TRUE if the word ends in a double consonant.
131798 **
131799 ** The text is reversed here. So we are really looking at
131800 ** the first two characters of z[].
131801 */
131802 static int doubleConsonant(const char *z){
131803   return isConsonant(z) && z[0]==z[1];
131804 }
131805 
131806 /*
131807 ** Return TRUE if the word ends with three letters which
131808 ** are consonant-vowel-consonent and where the final consonant
131809 ** is not 'w', 'x', or 'y'.
131810 **
131811 ** The word is reversed here.  So we are really checking the
131812 ** first three letters and the first one cannot be in [wxy].
131813 */
131814 static int star_oh(const char *z){
131815   return
131816     isConsonant(z) &&
131817     z[0]!='w' && z[0]!='x' && z[0]!='y' &&
131818     isVowel(z+1) &&
131819     isConsonant(z+2);
131820 }
131821 
131822 /*
131823 ** If the word ends with zFrom and xCond() is true for the stem
131824 ** of the word that preceeds the zFrom ending, then change the 
131825 ** ending to zTo.
131826 **
131827 ** The input word *pz and zFrom are both in reverse order.  zTo
131828 ** is in normal order. 
131829 **
131830 ** Return TRUE if zFrom matches.  Return FALSE if zFrom does not
131831 ** match.  Not that TRUE is returned even if xCond() fails and
131832 ** no substitution occurs.
131833 */
131834 static int stem(
131835   char **pz,             /* The word being stemmed (Reversed) */
131836   const char *zFrom,     /* If the ending matches this... (Reversed) */
131837   const char *zTo,       /* ... change the ending to this (not reversed) */
131838   int (*xCond)(const char*)   /* Condition that must be true */
131839 ){
131840   char *z = *pz;
131841   while( *zFrom && *zFrom==*z ){ z++; zFrom++; }
131842   if( *zFrom!=0 ) return 0;
131843   if( xCond && !xCond(z) ) return 1;
131844   while( *zTo ){
131845     *(--z) = *(zTo++);
131846   }
131847   *pz = z;
131848   return 1;
131849 }
131850 
131851 /*
131852 ** This is the fallback stemmer used when the porter stemmer is
131853 ** inappropriate.  The input word is copied into the output with
131854 ** US-ASCII case folding.  If the input word is too long (more
131855 ** than 20 bytes if it contains no digits or more than 6 bytes if
131856 ** it contains digits) then word is truncated to 20 or 6 bytes
131857 ** by taking 10 or 3 bytes from the beginning and end.
131858 */
131859 static void copy_stemmer(const char *zIn, int nIn, char *zOut, int *pnOut){
131860   int i, mx, j;
131861   int hasDigit = 0;
131862   for(i=0; i<nIn; i++){
131863     char c = zIn[i];
131864     if( c>='A' && c<='Z' ){
131865       zOut[i] = c - 'A' + 'a';
131866     }else{
131867       if( c>='0' && c<='9' ) hasDigit = 1;
131868       zOut[i] = c;
131869     }
131870   }
131871   mx = hasDigit ? 3 : 10;
131872   if( nIn>mx*2 ){
131873     for(j=mx, i=nIn-mx; i<nIn; i++, j++){
131874       zOut[j] = zOut[i];
131875     }
131876     i = j;
131877   }
131878   zOut[i] = 0;
131879   *pnOut = i;
131880 }
131881 
131882 
131883 /*
131884 ** Stem the input word zIn[0..nIn-1].  Store the output in zOut.
131885 ** zOut is at least big enough to hold nIn bytes.  Write the actual
131886 ** size of the output word (exclusive of the '\0' terminator) into *pnOut.
131887 **
131888 ** Any upper-case characters in the US-ASCII character set ([A-Z])
131889 ** are converted to lower case.  Upper-case UTF characters are
131890 ** unchanged.
131891 **
131892 ** Words that are longer than about 20 bytes are stemmed by retaining
131893 ** a few bytes from the beginning and the end of the word.  If the
131894 ** word contains digits, 3 bytes are taken from the beginning and
131895 ** 3 bytes from the end.  For long words without digits, 10 bytes
131896 ** are taken from each end.  US-ASCII case folding still applies.
131897 ** 
131898 ** If the input word contains not digits but does characters not 
131899 ** in [a-zA-Z] then no stemming is attempted and this routine just 
131900 ** copies the input into the input into the output with US-ASCII
131901 ** case folding.
131902 **
131903 ** Stemming never increases the length of the word.  So there is
131904 ** no chance of overflowing the zOut buffer.
131905 */
131906 static void porter_stemmer(const char *zIn, int nIn, char *zOut, int *pnOut){
131907   int i, j;
131908   char zReverse[28];
131909   char *z, *z2;
131910   if( nIn<3 || nIn>=(int)sizeof(zReverse)-7 ){
131911     /* The word is too big or too small for the porter stemmer.
131912     ** Fallback to the copy stemmer */
131913     copy_stemmer(zIn, nIn, zOut, pnOut);
131914     return;
131915   }
131916   for(i=0, j=sizeof(zReverse)-6; i<nIn; i++, j--){
131917     char c = zIn[i];
131918     if( c>='A' && c<='Z' ){
131919       zReverse[j] = c + 'a' - 'A';
131920     }else if( c>='a' && c<='z' ){
131921       zReverse[j] = c;
131922     }else{
131923       /* The use of a character not in [a-zA-Z] means that we fallback
131924       ** to the copy stemmer */
131925       copy_stemmer(zIn, nIn, zOut, pnOut);
131926       return;
131927     }
131928   }
131929   memset(&zReverse[sizeof(zReverse)-5], 0, 5);
131930   z = &zReverse[j+1];
131931 
131932 
131933   /* Step 1a */
131934   if( z[0]=='s' ){
131935     if(
131936      !stem(&z, "sess", "ss", 0) &&
131937      !stem(&z, "sei", "i", 0)  &&
131938      !stem(&z, "ss", "ss", 0)
131939     ){
131940       z++;
131941     }
131942   }
131943 
131944   /* Step 1b */  
131945   z2 = z;
131946   if( stem(&z, "dee", "ee", m_gt_0) ){
131947     /* Do nothing.  The work was all in the test */
131948   }else if( 
131949      (stem(&z, "gni", "", hasVowel) || stem(&z, "de", "", hasVowel))
131950       && z!=z2
131951   ){
131952      if( stem(&z, "ta", "ate", 0) ||
131953          stem(&z, "lb", "ble", 0) ||
131954          stem(&z, "zi", "ize", 0) ){
131955        /* Do nothing.  The work was all in the test */
131956      }else if( doubleConsonant(z) && (*z!='l' && *z!='s' && *z!='z') ){
131957        z++;
131958      }else if( m_eq_1(z) && star_oh(z) ){
131959        *(--z) = 'e';
131960      }
131961   }
131962 
131963   /* Step 1c */
131964   if( z[0]=='y' && hasVowel(z+1) ){
131965     z[0] = 'i';
131966   }
131967 
131968   /* Step 2 */
131969   switch( z[1] ){
131970    case 'a':
131971      stem(&z, "lanoita", "ate", m_gt_0) ||
131972      stem(&z, "lanoit", "tion", m_gt_0);
131973      break;
131974    case 'c':
131975      stem(&z, "icne", "ence", m_gt_0) ||
131976      stem(&z, "icna", "ance", m_gt_0);
131977      break;
131978    case 'e':
131979      stem(&z, "rezi", "ize", m_gt_0);
131980      break;
131981    case 'g':
131982      stem(&z, "igol", "log", m_gt_0);
131983      break;
131984    case 'l':
131985      stem(&z, "ilb", "ble", m_gt_0) ||
131986      stem(&z, "illa", "al", m_gt_0) ||
131987      stem(&z, "iltne", "ent", m_gt_0) ||
131988      stem(&z, "ile", "e", m_gt_0) ||
131989      stem(&z, "ilsuo", "ous", m_gt_0);
131990      break;
131991    case 'o':
131992      stem(&z, "noitazi", "ize", m_gt_0) ||
131993      stem(&z, "noita", "ate", m_gt_0) ||
131994      stem(&z, "rota", "ate", m_gt_0);
131995      break;
131996    case 's':
131997      stem(&z, "msila", "al", m_gt_0) ||
131998      stem(&z, "ssenevi", "ive", m_gt_0) ||
131999      stem(&z, "ssenluf", "ful", m_gt_0) ||
132000      stem(&z, "ssensuo", "ous", m_gt_0);
132001      break;
132002    case 't':
132003      stem(&z, "itila", "al", m_gt_0) ||
132004      stem(&z, "itivi", "ive", m_gt_0) ||
132005      stem(&z, "itilib", "ble", m_gt_0);
132006      break;
132007   }
132008 
132009   /* Step 3 */
132010   switch( z[0] ){
132011    case 'e':
132012      stem(&z, "etaci", "ic", m_gt_0) ||
132013      stem(&z, "evita", "", m_gt_0)   ||
132014      stem(&z, "ezila", "al", m_gt_0);
132015      break;
132016    case 'i':
132017      stem(&z, "itici", "ic", m_gt_0);
132018      break;
132019    case 'l':
132020      stem(&z, "laci", "ic", m_gt_0) ||
132021      stem(&z, "luf", "", m_gt_0);
132022      break;
132023    case 's':
132024      stem(&z, "ssen", "", m_gt_0);
132025      break;
132026   }
132027 
132028   /* Step 4 */
132029   switch( z[1] ){
132030    case 'a':
132031      if( z[0]=='l' && m_gt_1(z+2) ){
132032        z += 2;
132033      }
132034      break;
132035    case 'c':
132036      if( z[0]=='e' && z[2]=='n' && (z[3]=='a' || z[3]=='e')  && m_gt_1(z+4)  ){
132037        z += 4;
132038      }
132039      break;
132040    case 'e':
132041      if( z[0]=='r' && m_gt_1(z+2) ){
132042        z += 2;
132043      }
132044      break;
132045    case 'i':
132046      if( z[0]=='c' && m_gt_1(z+2) ){
132047        z += 2;
132048      }
132049      break;
132050    case 'l':
132051      if( z[0]=='e' && z[2]=='b' && (z[3]=='a' || z[3]=='i') && m_gt_1(z+4) ){
132052        z += 4;
132053      }
132054      break;
132055    case 'n':
132056      if( z[0]=='t' ){
132057        if( z[2]=='a' ){
132058          if( m_gt_1(z+3) ){
132059            z += 3;
132060          }
132061        }else if( z[2]=='e' ){
132062          stem(&z, "tneme", "", m_gt_1) ||
132063          stem(&z, "tnem", "", m_gt_1) ||
132064          stem(&z, "tne", "", m_gt_1);
132065        }
132066      }
132067      break;
132068    case 'o':
132069      if( z[0]=='u' ){
132070        if( m_gt_1(z+2) ){
132071          z += 2;
132072        }
132073      }else if( z[3]=='s' || z[3]=='t' ){
132074        stem(&z, "noi", "", m_gt_1);
132075      }
132076      break;
132077    case 's':
132078      if( z[0]=='m' && z[2]=='i' && m_gt_1(z+3) ){
132079        z += 3;
132080      }
132081      break;
132082    case 't':
132083      stem(&z, "eta", "", m_gt_1) ||
132084      stem(&z, "iti", "", m_gt_1);
132085      break;
132086    case 'u':
132087      if( z[0]=='s' && z[2]=='o' && m_gt_1(z+3) ){
132088        z += 3;
132089      }
132090      break;
132091    case 'v':
132092    case 'z':
132093      if( z[0]=='e' && z[2]=='i' && m_gt_1(z+3) ){
132094        z += 3;
132095      }
132096      break;
132097   }
132098 
132099   /* Step 5a */
132100   if( z[0]=='e' ){
132101     if( m_gt_1(z+1) ){
132102       z++;
132103     }else if( m_eq_1(z+1) && !star_oh(z+1) ){
132104       z++;
132105     }
132106   }
132107 
132108   /* Step 5b */
132109   if( m_gt_1(z) && z[0]=='l' && z[1]=='l' ){
132110     z++;
132111   }
132112 
132113   /* z[] is now the stemmed word in reverse order.  Flip it back
132114   ** around into forward order and return.
132115   */
132116   *pnOut = i = (int)strlen(z);
132117   zOut[i] = 0;
132118   while( *z ){
132119     zOut[--i] = *(z++);
132120   }
132121 }
132122 
132123 /*
132124 ** Characters that can be part of a token.  We assume any character
132125 ** whose value is greater than 0x80 (any UTF character) can be
132126 ** part of a token.  In other words, delimiters all must have
132127 ** values of 0x7f or lower.
132128 */
132129 static const char porterIdChar[] = {
132130 /* x0 x1 x2 x3 x4 x5 x6 x7 x8 x9 xA xB xC xD xE xF */
132131     1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0,  /* 3x */
132132     0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,  /* 4x */
132133     1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 1,  /* 5x */
132134     0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,  /* 6x */
132135     1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0,  /* 7x */
132136 };
132137 #define isDelim(C) (((ch=C)&0x80)==0 && (ch<0x30 || !porterIdChar[ch-0x30]))
132138 
132139 /*
132140 ** Extract the next token from a tokenization cursor.  The cursor must
132141 ** have been opened by a prior call to porterOpen().
132142 */
132143 static int porterNext(
132144   sqlite3_tokenizer_cursor *pCursor,  /* Cursor returned by porterOpen */
132145   const char **pzToken,               /* OUT: *pzToken is the token text */
132146   int *pnBytes,                       /* OUT: Number of bytes in token */
132147   int *piStartOffset,                 /* OUT: Starting offset of token */
132148   int *piEndOffset,                   /* OUT: Ending offset of token */
132149   int *piPosition                     /* OUT: Position integer of token */
132150 ){
132151   porter_tokenizer_cursor *c = (porter_tokenizer_cursor *) pCursor;
132152   const char *z = c->zInput;
132153 
132154   while( c->iOffset<c->nInput ){
132155     int iStartOffset, ch;
132156 
132157     /* Scan past delimiter characters */
132158     while( c->iOffset<c->nInput && isDelim(z[c->iOffset]) ){
132159       c->iOffset++;
132160     }
132161 
132162     /* Count non-delimiter characters. */
132163     iStartOffset = c->iOffset;
132164     while( c->iOffset<c->nInput && !isDelim(z[c->iOffset]) ){
132165       c->iOffset++;
132166     }
132167 
132168     if( c->iOffset>iStartOffset ){
132169       int n = c->iOffset-iStartOffset;
132170       if( n>c->nAllocated ){
132171         char *pNew;
132172         c->nAllocated = n+20;
132173         pNew = sqlite3_realloc(c->zToken, c->nAllocated);
132174         if( !pNew ) return SQLITE_NOMEM;
132175         c->zToken = pNew;
132176       }
132177       porter_stemmer(&z[iStartOffset], n, c->zToken, pnBytes);
132178       *pzToken = c->zToken;
132179       *piStartOffset = iStartOffset;
132180       *piEndOffset = c->iOffset;
132181       *piPosition = c->iToken++;
132182       return SQLITE_OK;
132183     }
132184   }
132185   return SQLITE_DONE;
132186 }
132187 
132188 /*
132189 ** The set of routines that implement the porter-stemmer tokenizer
132190 */
132191 static const sqlite3_tokenizer_module porterTokenizerModule = {
132192   0,
132193   porterCreate,
132194   porterDestroy,
132195   porterOpen,
132196   porterClose,
132197   porterNext,
132198   0
132199 };
132200 
132201 /*
132202 ** Allocate a new porter tokenizer.  Return a pointer to the new
132203 ** tokenizer in *ppModule
132204 */
132205 SQLITE_PRIVATE void sqlite3Fts3PorterTokenizerModule(
132206   sqlite3_tokenizer_module const**ppModule
132207 ){
132208   *ppModule = &porterTokenizerModule;
132209 }
132210 
132211 #endif /* !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_FTS3) */
132212 
132213 /************** End of fts3_porter.c *****************************************/
132214 /************** Begin file fts3_tokenizer.c **********************************/
132215 /*
132216 ** 2007 June 22
132217 **
132218 ** The author disclaims copyright to this source code.  In place of
132219 ** a legal notice, here is a blessing:
132220 **
132221 **    May you do good and not evil.
132222 **    May you find forgiveness for yourself and forgive others.
132223 **    May you share freely, never taking more than you give.
132224 **
132225 ******************************************************************************
132226 **
132227 ** This is part of an SQLite module implementing full-text search.
132228 ** This particular file implements the generic tokenizer interface.
132229 */
132230 
132231 /*
132232 ** The code in this file is only compiled if:
132233 **
132234 **     * The FTS3 module is being built as an extension
132235 **       (in which case SQLITE_CORE is not defined), or
132236 **
132237 **     * The FTS3 module is being built into the core of
132238 **       SQLite (in which case SQLITE_ENABLE_FTS3 is defined).
132239 */
132240 #if !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_FTS3)
132241 
132242 /* #include <assert.h> */
132243 /* #include <string.h> */
132244 
132245 /*
132246 ** Implementation of the SQL scalar function for accessing the underlying 
132247 ** hash table. This function may be called as follows:
132248 **
132249 **   SELECT <function-name>(<key-name>);
132250 **   SELECT <function-name>(<key-name>, <pointer>);
132251 **
132252 ** where <function-name> is the name passed as the second argument
132253 ** to the sqlite3Fts3InitHashTable() function (e.g. 'fts3_tokenizer').
132254 **
132255 ** If the <pointer> argument is specified, it must be a blob value
132256 ** containing a pointer to be stored as the hash data corresponding
132257 ** to the string <key-name>. If <pointer> is not specified, then
132258 ** the string <key-name> must already exist in the has table. Otherwise,
132259 ** an error is returned.
132260 **
132261 ** Whether or not the <pointer> argument is specified, the value returned
132262 ** is a blob containing the pointer stored as the hash data corresponding
132263 ** to string <key-name> (after the hash-table is updated, if applicable).
132264 */
132265 static void scalarFunc(
132266   sqlite3_context *context,
132267   int argc,
132268   sqlite3_value **argv
132269 ){
132270   Fts3Hash *pHash;
132271   void *pPtr = 0;
132272   const unsigned char *zName;
132273   int nName;
132274 
132275   assert( argc==1 || argc==2 );
132276 
132277   pHash = (Fts3Hash *)sqlite3_user_data(context);
132278 
132279   zName = sqlite3_value_text(argv[0]);
132280   nName = sqlite3_value_bytes(argv[0])+1;
132281 
132282   if( argc==2 ){
132283     void *pOld;
132284     int n = sqlite3_value_bytes(argv[1]);
132285     if( n!=sizeof(pPtr) ){
132286       sqlite3_result_error(context, "argument type mismatch", -1);
132287       return;
132288     }
132289     pPtr = *(void **)sqlite3_value_blob(argv[1]);
132290     pOld = sqlite3Fts3HashInsert(pHash, (void *)zName, nName, pPtr);
132291     if( pOld==pPtr ){
132292       sqlite3_result_error(context, "out of memory", -1);
132293       return;
132294     }
132295   }else{
132296     pPtr = sqlite3Fts3HashFind(pHash, zName, nName);
132297     if( !pPtr ){
132298       char *zErr = sqlite3_mprintf("unknown tokenizer: %s", zName);
132299       sqlite3_result_error(context, zErr, -1);
132300       sqlite3_free(zErr);
132301       return;
132302     }
132303   }
132304 
132305   sqlite3_result_blob(context, (void *)&pPtr, sizeof(pPtr), SQLITE_TRANSIENT);
132306 }
132307 
132308 SQLITE_PRIVATE int sqlite3Fts3IsIdChar(char c){
132309   static const char isFtsIdChar[] = {
132310       0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,  /* 0x */
132311       0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,  /* 1x */
132312       0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,  /* 2x */
132313       1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0,  /* 3x */
132314       0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,  /* 4x */
132315       1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 1,  /* 5x */
132316       0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,  /* 6x */
132317       1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0,  /* 7x */
132318   };
132319   return (c&0x80 || isFtsIdChar[(int)(c)]);
132320 }
132321 
132322 SQLITE_PRIVATE const char *sqlite3Fts3NextToken(const char *zStr, int *pn){
132323   const char *z1;
132324   const char *z2 = 0;
132325 
132326   /* Find the start of the next token. */
132327   z1 = zStr;
132328   while( z2==0 ){
132329     char c = *z1;
132330     switch( c ){
132331       case '\0': return 0;        /* No more tokens here */
132332       case '\'':
132333       case '"':
132334       case '`': {
132335         z2 = z1;
132336         while( *++z2 && (*z2!=c || *++z2==c) );
132337         break;
132338       }
132339       case '[':
132340         z2 = &z1[1];
132341         while( *z2 && z2[0]!=']' ) z2++;
132342         if( *z2 ) z2++;
132343         break;
132344 
132345       default:
132346         if( sqlite3Fts3IsIdChar(*z1) ){
132347           z2 = &z1[1];
132348           while( sqlite3Fts3IsIdChar(*z2) ) z2++;
132349         }else{
132350           z1++;
132351         }
132352     }
132353   }
132354 
132355   *pn = (int)(z2-z1);
132356   return z1;
132357 }
132358 
132359 SQLITE_PRIVATE int sqlite3Fts3InitTokenizer(
132360   Fts3Hash *pHash,                /* Tokenizer hash table */
132361   const char *zArg,               /* Tokenizer name */
132362   sqlite3_tokenizer **ppTok,      /* OUT: Tokenizer (if applicable) */
132363   char **pzErr                    /* OUT: Set to malloced error message */
132364 ){
132365   int rc;
132366   char *z = (char *)zArg;
132367   int n = 0;
132368   char *zCopy;
132369   char *zEnd;                     /* Pointer to nul-term of zCopy */
132370   sqlite3_tokenizer_module *m;
132371 
132372   zCopy = sqlite3_mprintf("%s", zArg);
132373   if( !zCopy ) return SQLITE_NOMEM;
132374   zEnd = &zCopy[strlen(zCopy)];
132375 
132376   z = (char *)sqlite3Fts3NextToken(zCopy, &n);
132377   z[n] = '\0';
132378   sqlite3Fts3Dequote(z);
132379 
132380   m = (sqlite3_tokenizer_module *)sqlite3Fts3HashFind(pHash,z,(int)strlen(z)+1);
132381   if( !m ){
132382     *pzErr = sqlite3_mprintf("unknown tokenizer: %s", z);
132383     rc = SQLITE_ERROR;
132384   }else{
132385     char const **aArg = 0;
132386     int iArg = 0;
132387     z = &z[n+1];
132388     while( z<zEnd && (NULL!=(z = (char *)sqlite3Fts3NextToken(z, &n))) ){
132389       int nNew = sizeof(char *)*(iArg+1);
132390       char const **aNew = (const char **)sqlite3_realloc((void *)aArg, nNew);
132391       if( !aNew ){
132392         sqlite3_free(zCopy);
132393         sqlite3_free((void *)aArg);
132394         return SQLITE_NOMEM;
132395       }
132396       aArg = aNew;
132397       aArg[iArg++] = z;
132398       z[n] = '\0';
132399       sqlite3Fts3Dequote(z);
132400       z = &z[n+1];
132401     }
132402     rc = m->xCreate(iArg, aArg, ppTok);
132403     assert( rc!=SQLITE_OK || *ppTok );
132404     if( rc!=SQLITE_OK ){
132405       *pzErr = sqlite3_mprintf("unknown tokenizer");
132406     }else{
132407       (*ppTok)->pModule = m; 
132408     }
132409     sqlite3_free((void *)aArg);
132410   }
132411 
132412   sqlite3_free(zCopy);
132413   return rc;
132414 }
132415 
132416 
132417 #ifdef SQLITE_TEST
132418 
132419 #include <tcl.h>
132420 /* #include <string.h> */
132421 
132422 /*
132423 ** Implementation of a special SQL scalar function for testing tokenizers 
132424 ** designed to be used in concert with the Tcl testing framework. This
132425 ** function must be called with two or more arguments:
132426 **
132427 **   SELECT <function-name>(<key-name>, ..., <input-string>);
132428 **
132429 ** where <function-name> is the name passed as the second argument
132430 ** to the sqlite3Fts3InitHashTable() function (e.g. 'fts3_tokenizer')
132431 ** concatenated with the string '_test' (e.g. 'fts3_tokenizer_test').
132432 **
132433 ** The return value is a string that may be interpreted as a Tcl
132434 ** list. For each token in the <input-string>, three elements are
132435 ** added to the returned list. The first is the token position, the 
132436 ** second is the token text (folded, stemmed, etc.) and the third is the
132437 ** substring of <input-string> associated with the token. For example, 
132438 ** using the built-in "simple" tokenizer:
132439 **
132440 **   SELECT fts_tokenizer_test('simple', 'I don't see how');
132441 **
132442 ** will return the string:
132443 **
132444 **   "{0 i I 1 dont don't 2 see see 3 how how}"
132445 **   
132446 */
132447 static void testFunc(
132448   sqlite3_context *context,
132449   int argc,
132450   sqlite3_value **argv
132451 ){
132452   Fts3Hash *pHash;
132453   sqlite3_tokenizer_module *p;
132454   sqlite3_tokenizer *pTokenizer = 0;
132455   sqlite3_tokenizer_cursor *pCsr = 0;
132456 
132457   const char *zErr = 0;
132458 
132459   const char *zName;
132460   int nName;
132461   const char *zInput;
132462   int nInput;
132463 
132464   const char *azArg[64];
132465 
132466   const char *zToken;
132467   int nToken = 0;
132468   int iStart = 0;
132469   int iEnd = 0;
132470   int iPos = 0;
132471   int i;
132472 
132473   Tcl_Obj *pRet;
132474 
132475   if( argc<2 ){
132476     sqlite3_result_error(context, "insufficient arguments", -1);
132477     return;
132478   }
132479 
132480   nName = sqlite3_value_bytes(argv[0]);
132481   zName = (const char *)sqlite3_value_text(argv[0]);
132482   nInput = sqlite3_value_bytes(argv[argc-1]);
132483   zInput = (const char *)sqlite3_value_text(argv[argc-1]);
132484 
132485   pHash = (Fts3Hash *)sqlite3_user_data(context);
132486   p = (sqlite3_tokenizer_module *)sqlite3Fts3HashFind(pHash, zName, nName+1);
132487 
132488   if( !p ){
132489     char *zErr = sqlite3_mprintf("unknown tokenizer: %s", zName);
132490     sqlite3_result_error(context, zErr, -1);
132491     sqlite3_free(zErr);
132492     return;
132493   }
132494 
132495   pRet = Tcl_NewObj();
132496   Tcl_IncrRefCount(pRet);
132497 
132498   for(i=1; i<argc-1; i++){
132499     azArg[i-1] = (const char *)sqlite3_value_text(argv[i]);
132500   }
132501 
132502   if( SQLITE_OK!=p->xCreate(argc-2, azArg, &pTokenizer) ){
132503     zErr = "error in xCreate()";
132504     goto finish;
132505   }
132506   pTokenizer->pModule = p;
132507   if( sqlite3Fts3OpenTokenizer(pTokenizer, 0, zInput, nInput, &pCsr) ){
132508     zErr = "error in xOpen()";
132509     goto finish;
132510   }
132511 
132512   while( SQLITE_OK==p->xNext(pCsr, &zToken, &nToken, &iStart, &iEnd, &iPos) ){
132513     Tcl_ListObjAppendElement(0, pRet, Tcl_NewIntObj(iPos));
132514     Tcl_ListObjAppendElement(0, pRet, Tcl_NewStringObj(zToken, nToken));
132515     zToken = &zInput[iStart];
132516     nToken = iEnd-iStart;
132517     Tcl_ListObjAppendElement(0, pRet, Tcl_NewStringObj(zToken, nToken));
132518   }
132519 
132520   if( SQLITE_OK!=p->xClose(pCsr) ){
132521     zErr = "error in xClose()";
132522     goto finish;
132523   }
132524   if( SQLITE_OK!=p->xDestroy(pTokenizer) ){
132525     zErr = "error in xDestroy()";
132526     goto finish;
132527   }
132528 
132529 finish:
132530   if( zErr ){
132531     sqlite3_result_error(context, zErr, -1);
132532   }else{
132533     sqlite3_result_text(context, Tcl_GetString(pRet), -1, SQLITE_TRANSIENT);
132534   }
132535   Tcl_DecrRefCount(pRet);
132536 }
132537 
132538 static
132539 int registerTokenizer(
132540   sqlite3 *db, 
132541   char *zName, 
132542   const sqlite3_tokenizer_module *p
132543 ){
132544   int rc;
132545   sqlite3_stmt *pStmt;
132546   const char zSql[] = "SELECT fts3_tokenizer(?, ?)";
132547 
132548   rc = sqlite3_prepare_v2(db, zSql, -1, &pStmt, 0);
132549   if( rc!=SQLITE_OK ){
132550     return rc;
132551   }
132552 
132553   sqlite3_bind_text(pStmt, 1, zName, -1, SQLITE_STATIC);
132554   sqlite3_bind_blob(pStmt, 2, &p, sizeof(p), SQLITE_STATIC);
132555   sqlite3_step(pStmt);
132556 
132557   return sqlite3_finalize(pStmt);
132558 }
132559 
132560 static
132561 int queryTokenizer(
132562   sqlite3 *db, 
132563   char *zName,  
132564   const sqlite3_tokenizer_module **pp
132565 ){
132566   int rc;
132567   sqlite3_stmt *pStmt;
132568   const char zSql[] = "SELECT fts3_tokenizer(?)";
132569 
132570   *pp = 0;
132571   rc = sqlite3_prepare_v2(db, zSql, -1, &pStmt, 0);
132572   if( rc!=SQLITE_OK ){
132573     return rc;
132574   }
132575 
132576   sqlite3_bind_text(pStmt, 1, zName, -1, SQLITE_STATIC);
132577   if( SQLITE_ROW==sqlite3_step(pStmt) ){
132578     if( sqlite3_column_type(pStmt, 0)==SQLITE_BLOB ){
132579       memcpy((void *)pp, sqlite3_column_blob(pStmt, 0), sizeof(*pp));
132580     }
132581   }
132582 
132583   return sqlite3_finalize(pStmt);
132584 }
132585 
132586 SQLITE_PRIVATE void sqlite3Fts3SimpleTokenizerModule(sqlite3_tokenizer_module const**ppModule);
132587 
132588 /*
132589 ** Implementation of the scalar function fts3_tokenizer_internal_test().
132590 ** This function is used for testing only, it is not included in the
132591 ** build unless SQLITE_TEST is defined.
132592 **
132593 ** The purpose of this is to test that the fts3_tokenizer() function
132594 ** can be used as designed by the C-code in the queryTokenizer and
132595 ** registerTokenizer() functions above. These two functions are repeated
132596 ** in the README.tokenizer file as an example, so it is important to
132597 ** test them.
132598 **
132599 ** To run the tests, evaluate the fts3_tokenizer_internal_test() scalar
132600 ** function with no arguments. An assert() will fail if a problem is
132601 ** detected. i.e.:
132602 **
132603 **     SELECT fts3_tokenizer_internal_test();
132604 **
132605 */
132606 static void intTestFunc(
132607   sqlite3_context *context,
132608   int argc,
132609   sqlite3_value **argv
132610 ){
132611   int rc;
132612   const sqlite3_tokenizer_module *p1;
132613   const sqlite3_tokenizer_module *p2;
132614   sqlite3 *db = (sqlite3 *)sqlite3_user_data(context);
132615 
132616   UNUSED_PARAMETER(argc);
132617   UNUSED_PARAMETER(argv);
132618 
132619   /* Test the query function */
132620   sqlite3Fts3SimpleTokenizerModule(&p1);
132621   rc = queryTokenizer(db, "simple", &p2);
132622   assert( rc==SQLITE_OK );
132623   assert( p1==p2 );
132624   rc = queryTokenizer(db, "nosuchtokenizer", &p2);
132625   assert( rc==SQLITE_ERROR );
132626   assert( p2==0 );
132627   assert( 0==strcmp(sqlite3_errmsg(db), "unknown tokenizer: nosuchtokenizer") );
132628 
132629   /* Test the storage function */
132630   rc = registerTokenizer(db, "nosuchtokenizer", p1);
132631   assert( rc==SQLITE_OK );
132632   rc = queryTokenizer(db, "nosuchtokenizer", &p2);
132633   assert( rc==SQLITE_OK );
132634   assert( p2==p1 );
132635 
132636   sqlite3_result_text(context, "ok", -1, SQLITE_STATIC);
132637 }
132638 
132639 #endif
132640 
132641 /*
132642 ** Set up SQL objects in database db used to access the contents of
132643 ** the hash table pointed to by argument pHash. The hash table must
132644 ** been initialized to use string keys, and to take a private copy 
132645 ** of the key when a value is inserted. i.e. by a call similar to:
132646 **
132647 **    sqlite3Fts3HashInit(pHash, FTS3_HASH_STRING, 1);
132648 **
132649 ** This function adds a scalar function (see header comment above
132650 ** scalarFunc() in this file for details) and, if ENABLE_TABLE is
132651 ** defined at compilation time, a temporary virtual table (see header 
132652 ** comment above struct HashTableVtab) to the database schema. Both 
132653 ** provide read/write access to the contents of *pHash.
132654 **
132655 ** The third argument to this function, zName, is used as the name
132656 ** of both the scalar and, if created, the virtual table.
132657 */
132658 SQLITE_PRIVATE int sqlite3Fts3InitHashTable(
132659   sqlite3 *db, 
132660   Fts3Hash *pHash, 
132661   const char *zName
132662 ){
132663   int rc = SQLITE_OK;
132664   void *p = (void *)pHash;
132665   const int any = SQLITE_ANY;
132666 
132667 #ifdef SQLITE_TEST
132668   char *zTest = 0;
132669   char *zTest2 = 0;
132670   void *pdb = (void *)db;
132671   zTest = sqlite3_mprintf("%s_test", zName);
132672   zTest2 = sqlite3_mprintf("%s_internal_test", zName);
132673   if( !zTest || !zTest2 ){
132674     rc = SQLITE_NOMEM;
132675   }
132676 #endif
132677 
132678   if( SQLITE_OK==rc ){
132679     rc = sqlite3_create_function(db, zName, 1, any, p, scalarFunc, 0, 0);
132680   }
132681   if( SQLITE_OK==rc ){
132682     rc = sqlite3_create_function(db, zName, 2, any, p, scalarFunc, 0, 0);
132683   }
132684 #ifdef SQLITE_TEST
132685   if( SQLITE_OK==rc ){
132686     rc = sqlite3_create_function(db, zTest, -1, any, p, testFunc, 0, 0);
132687   }
132688   if( SQLITE_OK==rc ){
132689     rc = sqlite3_create_function(db, zTest2, 0, any, pdb, intTestFunc, 0, 0);
132690   }
132691 #endif
132692 
132693 #ifdef SQLITE_TEST
132694   sqlite3_free(zTest);
132695   sqlite3_free(zTest2);
132696 #endif
132697 
132698   return rc;
132699 }
132700 
132701 #endif /* !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_FTS3) */
132702 
132703 /************** End of fts3_tokenizer.c **************************************/
132704 /************** Begin file fts3_tokenizer1.c *********************************/
132705 /*
132706 ** 2006 Oct 10
132707 **
132708 ** The author disclaims copyright to this source code.  In place of
132709 ** a legal notice, here is a blessing:
132710 **
132711 **    May you do good and not evil.
132712 **    May you find forgiveness for yourself and forgive others.
132713 **    May you share freely, never taking more than you give.
132714 **
132715 ******************************************************************************
132716 **
132717 ** Implementation of the "simple" full-text-search tokenizer.
132718 */
132719 
132720 /*
132721 ** The code in this file is only compiled if:
132722 **
132723 **     * The FTS3 module is being built as an extension
132724 **       (in which case SQLITE_CORE is not defined), or
132725 **
132726 **     * The FTS3 module is being built into the core of
132727 **       SQLite (in which case SQLITE_ENABLE_FTS3 is defined).
132728 */
132729 #if !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_FTS3)
132730 
132731 /* #include <assert.h> */
132732 /* #include <stdlib.h> */
132733 /* #include <stdio.h> */
132734 /* #include <string.h> */
132735 
132736 
132737 typedef struct simple_tokenizer {
132738   sqlite3_tokenizer base;
132739   char delim[128];             /* flag ASCII delimiters */
132740 } simple_tokenizer;
132741 
132742 typedef struct simple_tokenizer_cursor {
132743   sqlite3_tokenizer_cursor base;
132744   const char *pInput;          /* input we are tokenizing */
132745   int nBytes;                  /* size of the input */
132746   int iOffset;                 /* current position in pInput */
132747   int iToken;                  /* index of next token to be returned */
132748   char *pToken;                /* storage for current token */
132749   int nTokenAllocated;         /* space allocated to zToken buffer */
132750 } simple_tokenizer_cursor;
132751 
132752 
132753 static int simpleDelim(simple_tokenizer *t, unsigned char c){
132754   return c<0x80 && t->delim[c];
132755 }
132756 static int fts3_isalnum(int x){
132757   return (x>='0' && x<='9') || (x>='A' && x<='Z') || (x>='a' && x<='z');
132758 }
132759 
132760 /*
132761 ** Create a new tokenizer instance.
132762 */
132763 static int simpleCreate(
132764   int argc, const char * const *argv,
132765   sqlite3_tokenizer **ppTokenizer
132766 ){
132767   simple_tokenizer *t;
132768 
132769   t = (simple_tokenizer *) sqlite3_malloc(sizeof(*t));
132770   if( t==NULL ) return SQLITE_NOMEM;
132771   memset(t, 0, sizeof(*t));
132772 
132773   /* TODO(shess) Delimiters need to remain the same from run to run,
132774   ** else we need to reindex.  One solution would be a meta-table to
132775   ** track such information in the database, then we'd only want this
132776   ** information on the initial create.
132777   */
132778   if( argc>1 ){
132779     int i, n = (int)strlen(argv[1]);
132780     for(i=0; i<n; i++){
132781       unsigned char ch = argv[1][i];
132782       /* We explicitly don't support UTF-8 delimiters for now. */
132783       if( ch>=0x80 ){
132784         sqlite3_free(t);
132785         return SQLITE_ERROR;
132786       }
132787       t->delim[ch] = 1;
132788     }
132789   } else {
132790     /* Mark non-alphanumeric ASCII characters as delimiters */
132791     int i;
132792     for(i=1; i<0x80; i++){
132793       t->delim[i] = !fts3_isalnum(i) ? -1 : 0;
132794     }
132795   }
132796 
132797   *ppTokenizer = &t->base;
132798   return SQLITE_OK;
132799 }
132800 
132801 /*
132802 ** Destroy a tokenizer
132803 */
132804 static int simpleDestroy(sqlite3_tokenizer *pTokenizer){
132805   sqlite3_free(pTokenizer);
132806   return SQLITE_OK;
132807 }
132808 
132809 /*
132810 ** Prepare to begin tokenizing a particular string.  The input
132811 ** string to be tokenized is pInput[0..nBytes-1].  A cursor
132812 ** used to incrementally tokenize this string is returned in 
132813 ** *ppCursor.
132814 */
132815 static int simpleOpen(
132816   sqlite3_tokenizer *pTokenizer,         /* The tokenizer */
132817   const char *pInput, int nBytes,        /* String to be tokenized */
132818   sqlite3_tokenizer_cursor **ppCursor    /* OUT: Tokenization cursor */
132819 ){
132820   simple_tokenizer_cursor *c;
132821 
132822   UNUSED_PARAMETER(pTokenizer);
132823 
132824   c = (simple_tokenizer_cursor *) sqlite3_malloc(sizeof(*c));
132825   if( c==NULL ) return SQLITE_NOMEM;
132826 
132827   c->pInput = pInput;
132828   if( pInput==0 ){
132829     c->nBytes = 0;
132830   }else if( nBytes<0 ){
132831     c->nBytes = (int)strlen(pInput);
132832   }else{
132833     c->nBytes = nBytes;
132834   }
132835   c->iOffset = 0;                 /* start tokenizing at the beginning */
132836   c->iToken = 0;
132837   c->pToken = NULL;               /* no space allocated, yet. */
132838   c->nTokenAllocated = 0;
132839 
132840   *ppCursor = &c->base;
132841   return SQLITE_OK;
132842 }
132843 
132844 /*
132845 ** Close a tokenization cursor previously opened by a call to
132846 ** simpleOpen() above.
132847 */
132848 static int simpleClose(sqlite3_tokenizer_cursor *pCursor){
132849   simple_tokenizer_cursor *c = (simple_tokenizer_cursor *) pCursor;
132850   sqlite3_free(c->pToken);
132851   sqlite3_free(c);
132852   return SQLITE_OK;
132853 }
132854 
132855 /*
132856 ** Extract the next token from a tokenization cursor.  The cursor must
132857 ** have been opened by a prior call to simpleOpen().
132858 */
132859 static int simpleNext(
132860   sqlite3_tokenizer_cursor *pCursor,  /* Cursor returned by simpleOpen */
132861   const char **ppToken,               /* OUT: *ppToken is the token text */
132862   int *pnBytes,                       /* OUT: Number of bytes in token */
132863   int *piStartOffset,                 /* OUT: Starting offset of token */
132864   int *piEndOffset,                   /* OUT: Ending offset of token */
132865   int *piPosition                     /* OUT: Position integer of token */
132866 ){
132867   simple_tokenizer_cursor *c = (simple_tokenizer_cursor *) pCursor;
132868   simple_tokenizer *t = (simple_tokenizer *) pCursor->pTokenizer;
132869   unsigned char *p = (unsigned char *)c->pInput;
132870 
132871   while( c->iOffset<c->nBytes ){
132872     int iStartOffset;
132873 
132874     /* Scan past delimiter characters */
132875     while( c->iOffset<c->nBytes && simpleDelim(t, p[c->iOffset]) ){
132876       c->iOffset++;
132877     }
132878 
132879     /* Count non-delimiter characters. */
132880     iStartOffset = c->iOffset;
132881     while( c->iOffset<c->nBytes && !simpleDelim(t, p[c->iOffset]) ){
132882       c->iOffset++;
132883     }
132884 
132885     if( c->iOffset>iStartOffset ){
132886       int i, n = c->iOffset-iStartOffset;
132887       if( n>c->nTokenAllocated ){
132888         char *pNew;
132889         c->nTokenAllocated = n+20;
132890         pNew = sqlite3_realloc(c->pToken, c->nTokenAllocated);
132891         if( !pNew ) return SQLITE_NOMEM;
132892         c->pToken = pNew;
132893       }
132894       for(i=0; i<n; i++){
132895         /* TODO(shess) This needs expansion to handle UTF-8
132896         ** case-insensitivity.
132897         */
132898         unsigned char ch = p[iStartOffset+i];
132899         c->pToken[i] = (char)((ch>='A' && ch<='Z') ? ch-'A'+'a' : ch);
132900       }
132901       *ppToken = c->pToken;
132902       *pnBytes = n;
132903       *piStartOffset = iStartOffset;
132904       *piEndOffset = c->iOffset;
132905       *piPosition = c->iToken++;
132906 
132907       return SQLITE_OK;
132908     }
132909   }
132910   return SQLITE_DONE;
132911 }
132912 
132913 /*
132914 ** The set of routines that implement the simple tokenizer
132915 */
132916 static const sqlite3_tokenizer_module simpleTokenizerModule = {
132917   0,
132918   simpleCreate,
132919   simpleDestroy,
132920   simpleOpen,
132921   simpleClose,
132922   simpleNext,
132923   0,
132924 };
132925 
132926 /*
132927 ** Allocate a new simple tokenizer.  Return a pointer to the new
132928 ** tokenizer in *ppModule
132929 */
132930 SQLITE_PRIVATE void sqlite3Fts3SimpleTokenizerModule(
132931   sqlite3_tokenizer_module const**ppModule
132932 ){
132933   *ppModule = &simpleTokenizerModule;
132934 }
132935 
132936 #endif /* !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_FTS3) */
132937 
132938 /************** End of fts3_tokenizer1.c *************************************/
132939 /************** Begin file fts3_tokenize_vtab.c ******************************/
132940 /*
132941 ** 2013 Apr 22
132942 **
132943 ** The author disclaims copyright to this source code.  In place of
132944 ** a legal notice, here is a blessing:
132945 **
132946 **    May you do good and not evil.
132947 **    May you find forgiveness for yourself and forgive others.
132948 **    May you share freely, never taking more than you give.
132949 **
132950 ******************************************************************************
132951 **
132952 ** This file contains code for the "fts3tokenize" virtual table module.
132953 ** An fts3tokenize virtual table is created as follows:
132954 **
132955 **   CREATE VIRTUAL TABLE <tbl> USING fts3tokenize(
132956 **       <tokenizer-name>, <arg-1>, ...
132957 **   );
132958 **
132959 ** The table created has the following schema:
132960 **
132961 **   CREATE TABLE <tbl>(input, token, start, end, position)
132962 **
132963 ** When queried, the query must include a WHERE clause of type:
132964 **
132965 **   input = <string>
132966 **
132967 ** The virtual table module tokenizes this <string>, using the FTS3 
132968 ** tokenizer specified by the arguments to the CREATE VIRTUAL TABLE 
132969 ** statement and returns one row for each token in the result. With
132970 ** fields set as follows:
132971 **
132972 **   input:   Always set to a copy of <string>
132973 **   token:   A token from the input.
132974 **   start:   Byte offset of the token within the input <string>.
132975 **   end:     Byte offset of the byte immediately following the end of the
132976 **            token within the input string.
132977 **   pos:     Token offset of token within input.
132978 **
132979 */
132980 #if !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_FTS3)
132981 
132982 /* #include <string.h> */
132983 /* #include <assert.h> */
132984 
132985 typedef struct Fts3tokTable Fts3tokTable;
132986 typedef struct Fts3tokCursor Fts3tokCursor;
132987 
132988 /*
132989 ** Virtual table structure.
132990 */
132991 struct Fts3tokTable {
132992   sqlite3_vtab base;              /* Base class used by SQLite core */
132993   const sqlite3_tokenizer_module *pMod;
132994   sqlite3_tokenizer *pTok;
132995 };
132996 
132997 /*
132998 ** Virtual table cursor structure.
132999 */
133000 struct Fts3tokCursor {
133001   sqlite3_vtab_cursor base;       /* Base class used by SQLite core */
133002   char *zInput;                   /* Input string */
133003   sqlite3_tokenizer_cursor *pCsr; /* Cursor to iterate through zInput */
133004   int iRowid;                     /* Current 'rowid' value */
133005   const char *zToken;             /* Current 'token' value */
133006   int nToken;                     /* Size of zToken in bytes */
133007   int iStart;                     /* Current 'start' value */
133008   int iEnd;                       /* Current 'end' value */
133009   int iPos;                       /* Current 'pos' value */
133010 };
133011 
133012 /*
133013 ** Query FTS for the tokenizer implementation named zName.
133014 */
133015 static int fts3tokQueryTokenizer(
133016   Fts3Hash *pHash,
133017   const char *zName,
133018   const sqlite3_tokenizer_module **pp,
133019   char **pzErr
133020 ){
133021   sqlite3_tokenizer_module *p;
133022   int nName = (int)strlen(zName);
133023 
133024   p = (sqlite3_tokenizer_module *)sqlite3Fts3HashFind(pHash, zName, nName+1);
133025   if( !p ){
133026     *pzErr = sqlite3_mprintf("unknown tokenizer: %s", zName);
133027     return SQLITE_ERROR;
133028   }
133029 
133030   *pp = p;
133031   return SQLITE_OK;
133032 }
133033 
133034 /*
133035 ** The second argument, argv[], is an array of pointers to nul-terminated
133036 ** strings. This function makes a copy of the array and strings into a 
133037 ** single block of memory. It then dequotes any of the strings that appear
133038 ** to be quoted.
133039 **
133040 ** If successful, output parameter *pazDequote is set to point at the
133041 ** array of dequoted strings and SQLITE_OK is returned. The caller is
133042 ** responsible for eventually calling sqlite3_free() to free the array
133043 ** in this case. Or, if an error occurs, an SQLite error code is returned.
133044 ** The final value of *pazDequote is undefined in this case.
133045 */
133046 static int fts3tokDequoteArray(
133047   int argc,                       /* Number of elements in argv[] */
133048   const char * const *argv,       /* Input array */
133049   char ***pazDequote              /* Output array */
133050 ){
133051   int rc = SQLITE_OK;             /* Return code */
133052   if( argc==0 ){
133053     *pazDequote = 0;
133054   }else{
133055     int i;
133056     int nByte = 0;
133057     char **azDequote;
133058 
133059     for(i=0; i<argc; i++){
133060       nByte += (int)(strlen(argv[i]) + 1);
133061     }
133062 
133063     *pazDequote = azDequote = sqlite3_malloc(sizeof(char *)*argc + nByte);
133064     if( azDequote==0 ){
133065       rc = SQLITE_NOMEM;
133066     }else{
133067       char *pSpace = (char *)&azDequote[argc];
133068       for(i=0; i<argc; i++){
133069         int n = (int)strlen(argv[i]);
133070         azDequote[i] = pSpace;
133071         memcpy(pSpace, argv[i], n+1);
133072         sqlite3Fts3Dequote(pSpace);
133073         pSpace += (n+1);
133074       }
133075     }
133076   }
133077 
133078   return rc;
133079 }
133080 
133081 /*
133082 ** Schema of the tokenizer table.
133083 */
133084 #define FTS3_TOK_SCHEMA "CREATE TABLE x(input, token, start, end, position)"
133085 
133086 /*
133087 ** This function does all the work for both the xConnect and xCreate methods.
133088 ** These tables have no persistent representation of their own, so xConnect
133089 ** and xCreate are identical operations.
133090 **
133091 **   argv[0]: module name
133092 **   argv[1]: database name 
133093 **   argv[2]: table name
133094 **   argv[3]: first argument (tokenizer name)
133095 */
133096 static int fts3tokConnectMethod(
133097   sqlite3 *db,                    /* Database connection */
133098   void *pHash,                    /* Hash table of tokenizers */
133099   int argc,                       /* Number of elements in argv array */
133100   const char * const *argv,       /* xCreate/xConnect argument array */
133101   sqlite3_vtab **ppVtab,          /* OUT: New sqlite3_vtab object */
133102   char **pzErr                    /* OUT: sqlite3_malloc'd error message */
133103 ){
133104   Fts3tokTable *pTab;
133105   const sqlite3_tokenizer_module *pMod = 0;
133106   sqlite3_tokenizer *pTok = 0;
133107   int rc;
133108   char **azDequote = 0;
133109   int nDequote;
133110 
133111   rc = sqlite3_declare_vtab(db, FTS3_TOK_SCHEMA);
133112   if( rc!=SQLITE_OK ) return rc;
133113 
133114   nDequote = argc-3;
133115   rc = fts3tokDequoteArray(nDequote, &argv[3], &azDequote);
133116 
133117   if( rc==SQLITE_OK ){
133118     const char *zModule;
133119     if( nDequote<1 ){
133120       zModule = "simple";
133121     }else{
133122       zModule = azDequote[0];
133123     }
133124     rc = fts3tokQueryTokenizer((Fts3Hash*)pHash, zModule, &pMod, pzErr);
133125   }
133126 
133127   assert( (rc==SQLITE_OK)==(pMod!=0) );
133128   if( rc==SQLITE_OK ){
133129     const char * const *azArg = (const char * const *)&azDequote[1];
133130     rc = pMod->xCreate((nDequote>1 ? nDequote-1 : 0), azArg, &pTok);
133131   }
133132 
133133   if( rc==SQLITE_OK ){
133134     pTab = (Fts3tokTable *)sqlite3_malloc(sizeof(Fts3tokTable));
133135     if( pTab==0 ){
133136       rc = SQLITE_NOMEM;
133137     }
133138   }
133139 
133140   if( rc==SQLITE_OK ){
133141     memset(pTab, 0, sizeof(Fts3tokTable));
133142     pTab->pMod = pMod;
133143     pTab->pTok = pTok;
133144     *ppVtab = &pTab->base;
133145   }else{
133146     if( pTok ){
133147       pMod->xDestroy(pTok);
133148     }
133149   }
133150 
133151   sqlite3_free(azDequote);
133152   return rc;
133153 }
133154 
133155 /*
133156 ** This function does the work for both the xDisconnect and xDestroy methods.
133157 ** These tables have no persistent representation of their own, so xDisconnect
133158 ** and xDestroy are identical operations.
133159 */
133160 static int fts3tokDisconnectMethod(sqlite3_vtab *pVtab){
133161   Fts3tokTable *pTab = (Fts3tokTable *)pVtab;
133162 
133163   pTab->pMod->xDestroy(pTab->pTok);
133164   sqlite3_free(pTab);
133165   return SQLITE_OK;
133166 }
133167 
133168 /*
133169 ** xBestIndex - Analyze a WHERE and ORDER BY clause.
133170 */
133171 static int fts3tokBestIndexMethod(
133172   sqlite3_vtab *pVTab, 
133173   sqlite3_index_info *pInfo
133174 ){
133175   int i;
133176   UNUSED_PARAMETER(pVTab);
133177 
133178   for(i=0; i<pInfo->nConstraint; i++){
133179     if( pInfo->aConstraint[i].usable 
133180      && pInfo->aConstraint[i].iColumn==0 
133181      && pInfo->aConstraint[i].op==SQLITE_INDEX_CONSTRAINT_EQ 
133182     ){
133183       pInfo->idxNum = 1;
133184       pInfo->aConstraintUsage[i].argvIndex = 1;
133185       pInfo->aConstraintUsage[i].omit = 1;
133186       pInfo->estimatedCost = 1;
133187       return SQLITE_OK;
133188     }
133189   }
133190 
133191   pInfo->idxNum = 0;
133192   assert( pInfo->estimatedCost>1000000.0 );
133193 
133194   return SQLITE_OK;
133195 }
133196 
133197 /*
133198 ** xOpen - Open a cursor.
133199 */
133200 static int fts3tokOpenMethod(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCsr){
133201   Fts3tokCursor *pCsr;
133202   UNUSED_PARAMETER(pVTab);
133203 
133204   pCsr = (Fts3tokCursor *)sqlite3_malloc(sizeof(Fts3tokCursor));
133205   if( pCsr==0 ){
133206     return SQLITE_NOMEM;
133207   }
133208   memset(pCsr, 0, sizeof(Fts3tokCursor));
133209 
133210   *ppCsr = (sqlite3_vtab_cursor *)pCsr;
133211   return SQLITE_OK;
133212 }
133213 
133214 /*
133215 ** Reset the tokenizer cursor passed as the only argument. As if it had
133216 ** just been returned by fts3tokOpenMethod().
133217 */
133218 static void fts3tokResetCursor(Fts3tokCursor *pCsr){
133219   if( pCsr->pCsr ){
133220     Fts3tokTable *pTab = (Fts3tokTable *)(pCsr->base.pVtab);
133221     pTab->pMod->xClose(pCsr->pCsr);
133222     pCsr->pCsr = 0;
133223   }
133224   sqlite3_free(pCsr->zInput);
133225   pCsr->zInput = 0;
133226   pCsr->zToken = 0;
133227   pCsr->nToken = 0;
133228   pCsr->iStart = 0;
133229   pCsr->iEnd = 0;
133230   pCsr->iPos = 0;
133231   pCsr->iRowid = 0;
133232 }
133233 
133234 /*
133235 ** xClose - Close a cursor.
133236 */
133237 static int fts3tokCloseMethod(sqlite3_vtab_cursor *pCursor){
133238   Fts3tokCursor *pCsr = (Fts3tokCursor *)pCursor;
133239 
133240   fts3tokResetCursor(pCsr);
133241   sqlite3_free(pCsr);
133242   return SQLITE_OK;
133243 }
133244 
133245 /*
133246 ** xNext - Advance the cursor to the next row, if any.
133247 */
133248 static int fts3tokNextMethod(sqlite3_vtab_cursor *pCursor){
133249   Fts3tokCursor *pCsr = (Fts3tokCursor *)pCursor;
133250   Fts3tokTable *pTab = (Fts3tokTable *)(pCursor->pVtab);
133251   int rc;                         /* Return code */
133252 
133253   pCsr->iRowid++;
133254   rc = pTab->pMod->xNext(pCsr->pCsr,
133255       &pCsr->zToken, &pCsr->nToken,
133256       &pCsr->iStart, &pCsr->iEnd, &pCsr->iPos
133257   );
133258 
133259   if( rc!=SQLITE_OK ){
133260     fts3tokResetCursor(pCsr);
133261     if( rc==SQLITE_DONE ) rc = SQLITE_OK;
133262   }
133263 
133264   return rc;
133265 }
133266 
133267 /*
133268 ** xFilter - Initialize a cursor to point at the start of its data.
133269 */
133270 static int fts3tokFilterMethod(
133271   sqlite3_vtab_cursor *pCursor,   /* The cursor used for this query */
133272   int idxNum,                     /* Strategy index */
133273   const char *idxStr,             /* Unused */
133274   int nVal,                       /* Number of elements in apVal */
133275   sqlite3_value **apVal           /* Arguments for the indexing scheme */
133276 ){
133277   int rc = SQLITE_ERROR;
133278   Fts3tokCursor *pCsr = (Fts3tokCursor *)pCursor;
133279   Fts3tokTable *pTab = (Fts3tokTable *)(pCursor->pVtab);
133280   UNUSED_PARAMETER(idxStr);
133281   UNUSED_PARAMETER(nVal);
133282 
133283   fts3tokResetCursor(pCsr);
133284   if( idxNum==1 ){
133285     const char *zByte = (const char *)sqlite3_value_text(apVal[0]);
133286     int nByte = sqlite3_value_bytes(apVal[0]);
133287     pCsr->zInput = sqlite3_malloc(nByte+1);
133288     if( pCsr->zInput==0 ){
133289       rc = SQLITE_NOMEM;
133290     }else{
133291       memcpy(pCsr->zInput, zByte, nByte);
133292       pCsr->zInput[nByte] = 0;
133293       rc = pTab->pMod->xOpen(pTab->pTok, pCsr->zInput, nByte, &pCsr->pCsr);
133294       if( rc==SQLITE_OK ){
133295         pCsr->pCsr->pTokenizer = pTab->pTok;
133296       }
133297     }
133298   }
133299 
133300   if( rc!=SQLITE_OK ) return rc;
133301   return fts3tokNextMethod(pCursor);
133302 }
133303 
133304 /*
133305 ** xEof - Return true if the cursor is at EOF, or false otherwise.
133306 */
133307 static int fts3tokEofMethod(sqlite3_vtab_cursor *pCursor){
133308   Fts3tokCursor *pCsr = (Fts3tokCursor *)pCursor;
133309   return (pCsr->zToken==0);
133310 }
133311 
133312 /*
133313 ** xColumn - Return a column value.
133314 */
133315 static int fts3tokColumnMethod(
133316   sqlite3_vtab_cursor *pCursor,   /* Cursor to retrieve value from */
133317   sqlite3_context *pCtx,          /* Context for sqlite3_result_xxx() calls */
133318   int iCol                        /* Index of column to read value from */
133319 ){
133320   Fts3tokCursor *pCsr = (Fts3tokCursor *)pCursor;
133321 
133322   /* CREATE TABLE x(input, token, start, end, position) */
133323   switch( iCol ){
133324     case 0:
133325       sqlite3_result_text(pCtx, pCsr->zInput, -1, SQLITE_TRANSIENT);
133326       break;
133327     case 1:
133328       sqlite3_result_text(pCtx, pCsr->zToken, pCsr->nToken, SQLITE_TRANSIENT);
133329       break;
133330     case 2:
133331       sqlite3_result_int(pCtx, pCsr->iStart);
133332       break;
133333     case 3:
133334       sqlite3_result_int(pCtx, pCsr->iEnd);
133335       break;
133336     default:
133337       assert( iCol==4 );
133338       sqlite3_result_int(pCtx, pCsr->iPos);
133339       break;
133340   }
133341   return SQLITE_OK;
133342 }
133343 
133344 /*
133345 ** xRowid - Return the current rowid for the cursor.
133346 */
133347 static int fts3tokRowidMethod(
133348   sqlite3_vtab_cursor *pCursor,   /* Cursor to retrieve value from */
133349   sqlite_int64 *pRowid            /* OUT: Rowid value */
133350 ){
133351   Fts3tokCursor *pCsr = (Fts3tokCursor *)pCursor;
133352   *pRowid = (sqlite3_int64)pCsr->iRowid;
133353   return SQLITE_OK;
133354 }
133355 
133356 /*
133357 ** Register the fts3tok module with database connection db. Return SQLITE_OK
133358 ** if successful or an error code if sqlite3_create_module() fails.
133359 */
133360 SQLITE_PRIVATE int sqlite3Fts3InitTok(sqlite3 *db, Fts3Hash *pHash){
133361   static const sqlite3_module fts3tok_module = {
133362      0,                           /* iVersion      */
133363      fts3tokConnectMethod,        /* xCreate       */
133364      fts3tokConnectMethod,        /* xConnect      */
133365      fts3tokBestIndexMethod,      /* xBestIndex    */
133366      fts3tokDisconnectMethod,     /* xDisconnect   */
133367      fts3tokDisconnectMethod,     /* xDestroy      */
133368      fts3tokOpenMethod,           /* xOpen         */
133369      fts3tokCloseMethod,          /* xClose        */
133370      fts3tokFilterMethod,         /* xFilter       */
133371      fts3tokNextMethod,           /* xNext         */
133372      fts3tokEofMethod,            /* xEof          */
133373      fts3tokColumnMethod,         /* xColumn       */
133374      fts3tokRowidMethod,          /* xRowid        */
133375      0,                           /* xUpdate       */
133376      0,                           /* xBegin        */
133377      0,                           /* xSync         */
133378      0,                           /* xCommit       */
133379      0,                           /* xRollback     */
133380      0,                           /* xFindFunction */
133381      0,                           /* xRename       */
133382      0,                           /* xSavepoint    */
133383      0,                           /* xRelease      */
133384      0                            /* xRollbackTo   */
133385   };
133386   int rc;                         /* Return code */
133387 
133388   rc = sqlite3_create_module(db, "fts3tokenize", &fts3tok_module, (void*)pHash);
133389   return rc;
133390 }
133391 
133392 #endif /* !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_FTS3) */
133393 
133394 /************** End of fts3_tokenize_vtab.c **********************************/
133395 /************** Begin file fts3_write.c **************************************/
133396 /*
133397 ** 2009 Oct 23
133398 **
133399 ** The author disclaims copyright to this source code.  In place of
133400 ** a legal notice, here is a blessing:
133401 **
133402 **    May you do good and not evil.
133403 **    May you find forgiveness for yourself and forgive others.
133404 **    May you share freely, never taking more than you give.
133405 **
133406 ******************************************************************************
133407 **
133408 ** This file is part of the SQLite FTS3 extension module. Specifically,
133409 ** this file contains code to insert, update and delete rows from FTS3
133410 ** tables. It also contains code to merge FTS3 b-tree segments. Some
133411 ** of the sub-routines used to merge segments are also used by the query 
133412 ** code in fts3.c.
133413 */
133414 
133415 #if !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_FTS3)
133416 
133417 /* #include <string.h> */
133418 /* #include <assert.h> */
133419 /* #include <stdlib.h> */
133420 
133421 
133422 #define FTS_MAX_APPENDABLE_HEIGHT 16
133423 
133424 /*
133425 ** When full-text index nodes are loaded from disk, the buffer that they
133426 ** are loaded into has the following number of bytes of padding at the end 
133427 ** of it. i.e. if a full-text index node is 900 bytes in size, then a buffer
133428 ** of 920 bytes is allocated for it.
133429 **
133430 ** This means that if we have a pointer into a buffer containing node data,
133431 ** it is always safe to read up to two varints from it without risking an
133432 ** overread, even if the node data is corrupted.
133433 */
133434 #define FTS3_NODE_PADDING (FTS3_VARINT_MAX*2)
133435 
133436 /*
133437 ** Under certain circumstances, b-tree nodes (doclists) can be loaded into
133438 ** memory incrementally instead of all at once. This can be a big performance
133439 ** win (reduced IO and CPU) if SQLite stops calling the virtual table xNext()
133440 ** method before retrieving all query results (as may happen, for example,
133441 ** if a query has a LIMIT clause).
133442 **
133443 ** Incremental loading is used for b-tree nodes FTS3_NODE_CHUNK_THRESHOLD 
133444 ** bytes and larger. Nodes are loaded in chunks of FTS3_NODE_CHUNKSIZE bytes.
133445 ** The code is written so that the hard lower-limit for each of these values 
133446 ** is 1. Clearly such small values would be inefficient, but can be useful 
133447 ** for testing purposes.
133448 **
133449 ** If this module is built with SQLITE_TEST defined, these constants may
133450 ** be overridden at runtime for testing purposes. File fts3_test.c contains
133451 ** a Tcl interface to read and write the values.
133452 */
133453 #ifdef SQLITE_TEST
133454 int test_fts3_node_chunksize = (4*1024);
133455 int test_fts3_node_chunk_threshold = (4*1024)*4;
133456 # define FTS3_NODE_CHUNKSIZE       test_fts3_node_chunksize
133457 # define FTS3_NODE_CHUNK_THRESHOLD test_fts3_node_chunk_threshold
133458 #else
133459 # define FTS3_NODE_CHUNKSIZE (4*1024) 
133460 # define FTS3_NODE_CHUNK_THRESHOLD (FTS3_NODE_CHUNKSIZE*4)
133461 #endif
133462 
133463 /*
133464 ** The two values that may be meaningfully bound to the :1 parameter in
133465 ** statements SQL_REPLACE_STAT and SQL_SELECT_STAT.
133466 */
133467 #define FTS_STAT_DOCTOTAL      0
133468 #define FTS_STAT_INCRMERGEHINT 1
133469 #define FTS_STAT_AUTOINCRMERGE 2
133470 
133471 /*
133472 ** If FTS_LOG_MERGES is defined, call sqlite3_log() to report each automatic
133473 ** and incremental merge operation that takes place. This is used for 
133474 ** debugging FTS only, it should not usually be turned on in production
133475 ** systems.
133476 */
133477 #ifdef FTS3_LOG_MERGES
133478 static void fts3LogMerge(int nMerge, sqlite3_int64 iAbsLevel){
133479   sqlite3_log(SQLITE_OK, "%d-way merge from level %d", nMerge, (int)iAbsLevel);
133480 }
133481 #else
133482 #define fts3LogMerge(x, y)
133483 #endif
133484 
133485 
133486 typedef struct PendingList PendingList;
133487 typedef struct SegmentNode SegmentNode;
133488 typedef struct SegmentWriter SegmentWriter;
133489 
133490 /*
133491 ** An instance of the following data structure is used to build doclists
133492 ** incrementally. See function fts3PendingListAppend() for details.
133493 */
133494 struct PendingList {
133495   int nData;
133496   char *aData;
133497   int nSpace;
133498   sqlite3_int64 iLastDocid;
133499   sqlite3_int64 iLastCol;
133500   sqlite3_int64 iLastPos;
133501 };
133502 
133503 
133504 /*
133505 ** Each cursor has a (possibly empty) linked list of the following objects.
133506 */
133507 struct Fts3DeferredToken {
133508   Fts3PhraseToken *pToken;        /* Pointer to corresponding expr token */
133509   int iCol;                       /* Column token must occur in */
133510   Fts3DeferredToken *pNext;       /* Next in list of deferred tokens */
133511   PendingList *pList;             /* Doclist is assembled here */
133512 };
133513 
133514 /*
133515 ** An instance of this structure is used to iterate through the terms on
133516 ** a contiguous set of segment b-tree leaf nodes. Although the details of
133517 ** this structure are only manipulated by code in this file, opaque handles
133518 ** of type Fts3SegReader* are also used by code in fts3.c to iterate through
133519 ** terms when querying the full-text index. See functions:
133520 **
133521 **   sqlite3Fts3SegReaderNew()
133522 **   sqlite3Fts3SegReaderFree()
133523 **   sqlite3Fts3SegReaderIterate()
133524 **
133525 ** Methods used to manipulate Fts3SegReader structures:
133526 **
133527 **   fts3SegReaderNext()
133528 **   fts3SegReaderFirstDocid()
133529 **   fts3SegReaderNextDocid()
133530 */
133531 struct Fts3SegReader {
133532   int iIdx;                       /* Index within level, or 0x7FFFFFFF for PT */
133533   u8 bLookup;                     /* True for a lookup only */
133534   u8 rootOnly;                    /* True for a root-only reader */
133535 
133536   sqlite3_int64 iStartBlock;      /* Rowid of first leaf block to traverse */
133537   sqlite3_int64 iLeafEndBlock;    /* Rowid of final leaf block to traverse */
133538   sqlite3_int64 iEndBlock;        /* Rowid of final block in segment (or 0) */
133539   sqlite3_int64 iCurrentBlock;    /* Current leaf block (or 0) */
133540 
133541   char *aNode;                    /* Pointer to node data (or NULL) */
133542   int nNode;                      /* Size of buffer at aNode (or 0) */
133543   int nPopulate;                  /* If >0, bytes of buffer aNode[] loaded */
133544   sqlite3_blob *pBlob;            /* If not NULL, blob handle to read node */
133545 
133546   Fts3HashElem **ppNextElem;
133547 
133548   /* Variables set by fts3SegReaderNext(). These may be read directly
133549   ** by the caller. They are valid from the time SegmentReaderNew() returns
133550   ** until SegmentReaderNext() returns something other than SQLITE_OK
133551   ** (i.e. SQLITE_DONE).
133552   */
133553   int nTerm;                      /* Number of bytes in current term */
133554   char *zTerm;                    /* Pointer to current term */
133555   int nTermAlloc;                 /* Allocated size of zTerm buffer */
133556   char *aDoclist;                 /* Pointer to doclist of current entry */
133557   int nDoclist;                   /* Size of doclist in current entry */
133558 
133559   /* The following variables are used by fts3SegReaderNextDocid() to iterate 
133560   ** through the current doclist (aDoclist/nDoclist).
133561   */
133562   char *pOffsetList;
133563   int nOffsetList;                /* For descending pending seg-readers only */
133564   sqlite3_int64 iDocid;
133565 };
133566 
133567 #define fts3SegReaderIsPending(p) ((p)->ppNextElem!=0)
133568 #define fts3SegReaderIsRootOnly(p) ((p)->rootOnly!=0)
133569 
133570 /*
133571 ** An instance of this structure is used to create a segment b-tree in the
133572 ** database. The internal details of this type are only accessed by the
133573 ** following functions:
133574 **
133575 **   fts3SegWriterAdd()
133576 **   fts3SegWriterFlush()
133577 **   fts3SegWriterFree()
133578 */
133579 struct SegmentWriter {
133580   SegmentNode *pTree;             /* Pointer to interior tree structure */
133581   sqlite3_int64 iFirst;           /* First slot in %_segments written */
133582   sqlite3_int64 iFree;            /* Next free slot in %_segments */
133583   char *zTerm;                    /* Pointer to previous term buffer */
133584   int nTerm;                      /* Number of bytes in zTerm */
133585   int nMalloc;                    /* Size of malloc'd buffer at zMalloc */
133586   char *zMalloc;                  /* Malloc'd space (possibly) used for zTerm */
133587   int nSize;                      /* Size of allocation at aData */
133588   int nData;                      /* Bytes of data in aData */
133589   char *aData;                    /* Pointer to block from malloc() */
133590 };
133591 
133592 /*
133593 ** Type SegmentNode is used by the following three functions to create
133594 ** the interior part of the segment b+-tree structures (everything except
133595 ** the leaf nodes). These functions and type are only ever used by code
133596 ** within the fts3SegWriterXXX() family of functions described above.
133597 **
133598 **   fts3NodeAddTerm()
133599 **   fts3NodeWrite()
133600 **   fts3NodeFree()
133601 **
133602 ** When a b+tree is written to the database (either as a result of a merge
133603 ** or the pending-terms table being flushed), leaves are written into the 
133604 ** database file as soon as they are completely populated. The interior of
133605 ** the tree is assembled in memory and written out only once all leaves have
133606 ** been populated and stored. This is Ok, as the b+-tree fanout is usually
133607 ** very large, meaning that the interior of the tree consumes relatively 
133608 ** little memory.
133609 */
133610 struct SegmentNode {
133611   SegmentNode *pParent;           /* Parent node (or NULL for root node) */
133612   SegmentNode *pRight;            /* Pointer to right-sibling */
133613   SegmentNode *pLeftmost;         /* Pointer to left-most node of this depth */
133614   int nEntry;                     /* Number of terms written to node so far */
133615   char *zTerm;                    /* Pointer to previous term buffer */
133616   int nTerm;                      /* Number of bytes in zTerm */
133617   int nMalloc;                    /* Size of malloc'd buffer at zMalloc */
133618   char *zMalloc;                  /* Malloc'd space (possibly) used for zTerm */
133619   int nData;                      /* Bytes of valid data so far */
133620   char *aData;                    /* Node data */
133621 };
133622 
133623 /*
133624 ** Valid values for the second argument to fts3SqlStmt().
133625 */
133626 #define SQL_DELETE_CONTENT             0
133627 #define SQL_IS_EMPTY                   1
133628 #define SQL_DELETE_ALL_CONTENT         2 
133629 #define SQL_DELETE_ALL_SEGMENTS        3
133630 #define SQL_DELETE_ALL_SEGDIR          4
133631 #define SQL_DELETE_ALL_DOCSIZE         5
133632 #define SQL_DELETE_ALL_STAT            6
133633 #define SQL_SELECT_CONTENT_BY_ROWID    7
133634 #define SQL_NEXT_SEGMENT_INDEX         8
133635 #define SQL_INSERT_SEGMENTS            9
133636 #define SQL_NEXT_SEGMENTS_ID          10
133637 #define SQL_INSERT_SEGDIR             11
133638 #define SQL_SELECT_LEVEL              12
133639 #define SQL_SELECT_LEVEL_RANGE        13
133640 #define SQL_SELECT_LEVEL_COUNT        14
133641 #define SQL_SELECT_SEGDIR_MAX_LEVEL   15
133642 #define SQL_DELETE_SEGDIR_LEVEL       16
133643 #define SQL_DELETE_SEGMENTS_RANGE     17
133644 #define SQL_CONTENT_INSERT            18
133645 #define SQL_DELETE_DOCSIZE            19
133646 #define SQL_REPLACE_DOCSIZE           20
133647 #define SQL_SELECT_DOCSIZE            21
133648 #define SQL_SELECT_STAT               22
133649 #define SQL_REPLACE_STAT              23
133650 
133651 #define SQL_SELECT_ALL_PREFIX_LEVEL   24
133652 #define SQL_DELETE_ALL_TERMS_SEGDIR   25
133653 #define SQL_DELETE_SEGDIR_RANGE       26
133654 #define SQL_SELECT_ALL_LANGID         27
133655 #define SQL_FIND_MERGE_LEVEL          28
133656 #define SQL_MAX_LEAF_NODE_ESTIMATE    29
133657 #define SQL_DELETE_SEGDIR_ENTRY       30
133658 #define SQL_SHIFT_SEGDIR_ENTRY        31
133659 #define SQL_SELECT_SEGDIR             32
133660 #define SQL_CHOMP_SEGDIR              33
133661 #define SQL_SEGMENT_IS_APPENDABLE     34
133662 #define SQL_SELECT_INDEXES            35
133663 #define SQL_SELECT_MXLEVEL            36
133664 
133665 /*
133666 ** This function is used to obtain an SQLite prepared statement handle
133667 ** for the statement identified by the second argument. If successful,
133668 ** *pp is set to the requested statement handle and SQLITE_OK returned.
133669 ** Otherwise, an SQLite error code is returned and *pp is set to 0.
133670 **
133671 ** If argument apVal is not NULL, then it must point to an array with
133672 ** at least as many entries as the requested statement has bound 
133673 ** parameters. The values are bound to the statements parameters before
133674 ** returning.
133675 */
133676 static int fts3SqlStmt(
133677   Fts3Table *p,                   /* Virtual table handle */
133678   int eStmt,                      /* One of the SQL_XXX constants above */
133679   sqlite3_stmt **pp,              /* OUT: Statement handle */
133680   sqlite3_value **apVal           /* Values to bind to statement */
133681 ){
133682   const char *azSql[] = {
133683 /* 0  */  "DELETE FROM %Q.'%q_content' WHERE rowid = ?",
133684 /* 1  */  "SELECT NOT EXISTS(SELECT docid FROM %Q.'%q_content' WHERE rowid!=?)",
133685 /* 2  */  "DELETE FROM %Q.'%q_content'",
133686 /* 3  */  "DELETE FROM %Q.'%q_segments'",
133687 /* 4  */  "DELETE FROM %Q.'%q_segdir'",
133688 /* 5  */  "DELETE FROM %Q.'%q_docsize'",
133689 /* 6  */  "DELETE FROM %Q.'%q_stat'",
133690 /* 7  */  "SELECT %s WHERE rowid=?",
133691 /* 8  */  "SELECT (SELECT max(idx) FROM %Q.'%q_segdir' WHERE level = ?) + 1",
133692 /* 9  */  "REPLACE INTO %Q.'%q_segments'(blockid, block) VALUES(?, ?)",
133693 /* 10 */  "SELECT coalesce((SELECT max(blockid) FROM %Q.'%q_segments') + 1, 1)",
133694 /* 11 */  "REPLACE INTO %Q.'%q_segdir' VALUES(?,?,?,?,?,?)",
133695 
133696           /* Return segments in order from oldest to newest.*/ 
133697 /* 12 */  "SELECT idx, start_block, leaves_end_block, end_block, root "
133698             "FROM %Q.'%q_segdir' WHERE level = ? ORDER BY idx ASC",
133699 /* 13 */  "SELECT idx, start_block, leaves_end_block, end_block, root "
133700             "FROM %Q.'%q_segdir' WHERE level BETWEEN ? AND ?"
133701             "ORDER BY level DESC, idx ASC",
133702 
133703 /* 14 */  "SELECT count(*) FROM %Q.'%q_segdir' WHERE level = ?",
133704 /* 15 */  "SELECT max(level) FROM %Q.'%q_segdir' WHERE level BETWEEN ? AND ?",
133705 
133706 /* 16 */  "DELETE FROM %Q.'%q_segdir' WHERE level = ?",
133707 /* 17 */  "DELETE FROM %Q.'%q_segments' WHERE blockid BETWEEN ? AND ?",
133708 /* 18 */  "INSERT INTO %Q.'%q_content' VALUES(%s)",
133709 /* 19 */  "DELETE FROM %Q.'%q_docsize' WHERE docid = ?",
133710 /* 20 */  "REPLACE INTO %Q.'%q_docsize' VALUES(?,?)",
133711 /* 21 */  "SELECT size FROM %Q.'%q_docsize' WHERE docid=?",
133712 /* 22 */  "SELECT value FROM %Q.'%q_stat' WHERE id=?",
133713 /* 23 */  "REPLACE INTO %Q.'%q_stat' VALUES(?,?)",
133714 /* 24 */  "",
133715 /* 25 */  "",
133716 
133717 /* 26 */ "DELETE FROM %Q.'%q_segdir' WHERE level BETWEEN ? AND ?",
133718 /* 27 */ "SELECT DISTINCT level / (1024 * ?) FROM %Q.'%q_segdir'",
133719 
133720 /* This statement is used to determine which level to read the input from
133721 ** when performing an incremental merge. It returns the absolute level number
133722 ** of the oldest level in the db that contains at least ? segments. Or,
133723 ** if no level in the FTS index contains more than ? segments, the statement
133724 ** returns zero rows.  */
133725 /* 28 */ "SELECT level FROM %Q.'%q_segdir' GROUP BY level HAVING count(*)>=?"
133726          "  ORDER BY (level %% 1024) ASC LIMIT 1",
133727 
133728 /* Estimate the upper limit on the number of leaf nodes in a new segment
133729 ** created by merging the oldest :2 segments from absolute level :1. See 
133730 ** function sqlite3Fts3Incrmerge() for details.  */
133731 /* 29 */ "SELECT 2 * total(1 + leaves_end_block - start_block) "
133732          "  FROM %Q.'%q_segdir' WHERE level = ? AND idx < ?",
133733 
133734 /* SQL_DELETE_SEGDIR_ENTRY
133735 **   Delete the %_segdir entry on absolute level :1 with index :2.  */
133736 /* 30 */ "DELETE FROM %Q.'%q_segdir' WHERE level = ? AND idx = ?",
133737 
133738 /* SQL_SHIFT_SEGDIR_ENTRY
133739 **   Modify the idx value for the segment with idx=:3 on absolute level :2
133740 **   to :1.  */
133741 /* 31 */ "UPDATE %Q.'%q_segdir' SET idx = ? WHERE level=? AND idx=?",
133742 
133743 /* SQL_SELECT_SEGDIR
133744 **   Read a single entry from the %_segdir table. The entry from absolute 
133745 **   level :1 with index value :2.  */
133746 /* 32 */  "SELECT idx, start_block, leaves_end_block, end_block, root "
133747             "FROM %Q.'%q_segdir' WHERE level = ? AND idx = ?",
133748 
133749 /* SQL_CHOMP_SEGDIR
133750 **   Update the start_block (:1) and root (:2) fields of the %_segdir
133751 **   entry located on absolute level :3 with index :4.  */
133752 /* 33 */  "UPDATE %Q.'%q_segdir' SET start_block = ?, root = ?"
133753             "WHERE level = ? AND idx = ?",
133754 
133755 /* SQL_SEGMENT_IS_APPENDABLE
133756 **   Return a single row if the segment with end_block=? is appendable. Or
133757 **   no rows otherwise.  */
133758 /* 34 */  "SELECT 1 FROM %Q.'%q_segments' WHERE blockid=? AND block IS NULL",
133759 
133760 /* SQL_SELECT_INDEXES
133761 **   Return the list of valid segment indexes for absolute level ?  */
133762 /* 35 */  "SELECT idx FROM %Q.'%q_segdir' WHERE level=? ORDER BY 1 ASC",
133763 
133764 /* SQL_SELECT_MXLEVEL
133765 **   Return the largest relative level in the FTS index or indexes.  */
133766 /* 36 */  "SELECT max( level %% 1024 ) FROM %Q.'%q_segdir'"
133767   };
133768   int rc = SQLITE_OK;
133769   sqlite3_stmt *pStmt;
133770 
133771   assert( SizeofArray(azSql)==SizeofArray(p->aStmt) );
133772   assert( eStmt<SizeofArray(azSql) && eStmt>=0 );
133773   
133774   pStmt = p->aStmt[eStmt];
133775   if( !pStmt ){
133776     char *zSql;
133777     if( eStmt==SQL_CONTENT_INSERT ){
133778       zSql = sqlite3_mprintf(azSql[eStmt], p->zDb, p->zName, p->zWriteExprlist);
133779     }else if( eStmt==SQL_SELECT_CONTENT_BY_ROWID ){
133780       zSql = sqlite3_mprintf(azSql[eStmt], p->zReadExprlist);
133781     }else{
133782       zSql = sqlite3_mprintf(azSql[eStmt], p->zDb, p->zName);
133783     }
133784     if( !zSql ){
133785       rc = SQLITE_NOMEM;
133786     }else{
133787       rc = sqlite3_prepare_v2(p->db, zSql, -1, &pStmt, NULL);
133788       sqlite3_free(zSql);
133789       assert( rc==SQLITE_OK || pStmt==0 );
133790       p->aStmt[eStmt] = pStmt;
133791     }
133792   }
133793   if( apVal ){
133794     int i;
133795     int nParam = sqlite3_bind_parameter_count(pStmt);
133796     for(i=0; rc==SQLITE_OK && i<nParam; i++){
133797       rc = sqlite3_bind_value(pStmt, i+1, apVal[i]);
133798     }
133799   }
133800   *pp = pStmt;
133801   return rc;
133802 }
133803 
133804 
133805 static int fts3SelectDocsize(
133806   Fts3Table *pTab,                /* FTS3 table handle */
133807   sqlite3_int64 iDocid,           /* Docid to bind for SQL_SELECT_DOCSIZE */
133808   sqlite3_stmt **ppStmt           /* OUT: Statement handle */
133809 ){
133810   sqlite3_stmt *pStmt = 0;        /* Statement requested from fts3SqlStmt() */
133811   int rc;                         /* Return code */
133812 
133813   rc = fts3SqlStmt(pTab, SQL_SELECT_DOCSIZE, &pStmt, 0);
133814   if( rc==SQLITE_OK ){
133815     sqlite3_bind_int64(pStmt, 1, iDocid);
133816     rc = sqlite3_step(pStmt);
133817     if( rc!=SQLITE_ROW || sqlite3_column_type(pStmt, 0)!=SQLITE_BLOB ){
133818       rc = sqlite3_reset(pStmt);
133819       if( rc==SQLITE_OK ) rc = FTS_CORRUPT_VTAB;
133820       pStmt = 0;
133821     }else{
133822       rc = SQLITE_OK;
133823     }
133824   }
133825 
133826   *ppStmt = pStmt;
133827   return rc;
133828 }
133829 
133830 SQLITE_PRIVATE int sqlite3Fts3SelectDoctotal(
133831   Fts3Table *pTab,                /* Fts3 table handle */
133832   sqlite3_stmt **ppStmt           /* OUT: Statement handle */
133833 ){
133834   sqlite3_stmt *pStmt = 0;
133835   int rc;
133836   rc = fts3SqlStmt(pTab, SQL_SELECT_STAT, &pStmt, 0);
133837   if( rc==SQLITE_OK ){
133838     sqlite3_bind_int(pStmt, 1, FTS_STAT_DOCTOTAL);
133839     if( sqlite3_step(pStmt)!=SQLITE_ROW
133840      || sqlite3_column_type(pStmt, 0)!=SQLITE_BLOB
133841     ){
133842       rc = sqlite3_reset(pStmt);
133843       if( rc==SQLITE_OK ) rc = FTS_CORRUPT_VTAB;
133844       pStmt = 0;
133845     }
133846   }
133847   *ppStmt = pStmt;
133848   return rc;
133849 }
133850 
133851 SQLITE_PRIVATE int sqlite3Fts3SelectDocsize(
133852   Fts3Table *pTab,                /* Fts3 table handle */
133853   sqlite3_int64 iDocid,           /* Docid to read size data for */
133854   sqlite3_stmt **ppStmt           /* OUT: Statement handle */
133855 ){
133856   return fts3SelectDocsize(pTab, iDocid, ppStmt);
133857 }
133858 
133859 /*
133860 ** Similar to fts3SqlStmt(). Except, after binding the parameters in
133861 ** array apVal[] to the SQL statement identified by eStmt, the statement
133862 ** is executed.
133863 **
133864 ** Returns SQLITE_OK if the statement is successfully executed, or an
133865 ** SQLite error code otherwise.
133866 */
133867 static void fts3SqlExec(
133868   int *pRC,                /* Result code */
133869   Fts3Table *p,            /* The FTS3 table */
133870   int eStmt,               /* Index of statement to evaluate */
133871   sqlite3_value **apVal    /* Parameters to bind */
133872 ){
133873   sqlite3_stmt *pStmt;
133874   int rc;
133875   if( *pRC ) return;
133876   rc = fts3SqlStmt(p, eStmt, &pStmt, apVal); 
133877   if( rc==SQLITE_OK ){
133878     sqlite3_step(pStmt);
133879     rc = sqlite3_reset(pStmt);
133880   }
133881   *pRC = rc;
133882 }
133883 
133884 
133885 /*
133886 ** This function ensures that the caller has obtained an exclusive 
133887 ** shared-cache table-lock on the %_segdir table. This is required before 
133888 ** writing data to the fts3 table. If this lock is not acquired first, then
133889 ** the caller may end up attempting to take this lock as part of committing
133890 ** a transaction, causing SQLite to return SQLITE_LOCKED or 
133891 ** LOCKED_SHAREDCACHEto a COMMIT command.
133892 **
133893 ** It is best to avoid this because if FTS3 returns any error when 
133894 ** committing a transaction, the whole transaction will be rolled back. 
133895 ** And this is not what users expect when they get SQLITE_LOCKED_SHAREDCACHE. 
133896 ** It can still happen if the user locks the underlying tables directly 
133897 ** instead of accessing them via FTS.
133898 */
133899 static int fts3Writelock(Fts3Table *p){
133900   int rc = SQLITE_OK;
133901   
133902   if( p->nPendingData==0 ){
133903     sqlite3_stmt *pStmt;
133904     rc = fts3SqlStmt(p, SQL_DELETE_SEGDIR_LEVEL, &pStmt, 0);
133905     if( rc==SQLITE_OK ){
133906       sqlite3_bind_null(pStmt, 1);
133907       sqlite3_step(pStmt);
133908       rc = sqlite3_reset(pStmt);
133909     }
133910   }
133911 
133912   return rc;
133913 }
133914 
133915 /*
133916 ** FTS maintains a separate indexes for each language-id (a 32-bit integer).
133917 ** Within each language id, a separate index is maintained to store the
133918 ** document terms, and each configured prefix size (configured the FTS 
133919 ** "prefix=" option). And each index consists of multiple levels ("relative
133920 ** levels").
133921 **
133922 ** All three of these values (the language id, the specific index and the
133923 ** level within the index) are encoded in 64-bit integer values stored
133924 ** in the %_segdir table on disk. This function is used to convert three
133925 ** separate component values into the single 64-bit integer value that
133926 ** can be used to query the %_segdir table.
133927 **
133928 ** Specifically, each language-id/index combination is allocated 1024 
133929 ** 64-bit integer level values ("absolute levels"). The main terms index
133930 ** for language-id 0 is allocate values 0-1023. The first prefix index
133931 ** (if any) for language-id 0 is allocated values 1024-2047. And so on.
133932 ** Language 1 indexes are allocated immediately following language 0.
133933 **
133934 ** So, for a system with nPrefix prefix indexes configured, the block of
133935 ** absolute levels that corresponds to language-id iLangid and index 
133936 ** iIndex starts at absolute level ((iLangid * (nPrefix+1) + iIndex) * 1024).
133937 */
133938 static sqlite3_int64 getAbsoluteLevel(
133939   Fts3Table *p,                   /* FTS3 table handle */
133940   int iLangid,                    /* Language id */
133941   int iIndex,                     /* Index in p->aIndex[] */
133942   int iLevel                      /* Level of segments */
133943 ){
133944   sqlite3_int64 iBase;            /* First absolute level for iLangid/iIndex */
133945   assert( iLangid>=0 );
133946   assert( p->nIndex>0 );
133947   assert( iIndex>=0 && iIndex<p->nIndex );
133948 
133949   iBase = ((sqlite3_int64)iLangid * p->nIndex + iIndex) * FTS3_SEGDIR_MAXLEVEL;
133950   return iBase + iLevel;
133951 }
133952 
133953 /*
133954 ** Set *ppStmt to a statement handle that may be used to iterate through
133955 ** all rows in the %_segdir table, from oldest to newest. If successful,
133956 ** return SQLITE_OK. If an error occurs while preparing the statement, 
133957 ** return an SQLite error code.
133958 **
133959 ** There is only ever one instance of this SQL statement compiled for
133960 ** each FTS3 table.
133961 **
133962 ** The statement returns the following columns from the %_segdir table:
133963 **
133964 **   0: idx
133965 **   1: start_block
133966 **   2: leaves_end_block
133967 **   3: end_block
133968 **   4: root
133969 */
133970 SQLITE_PRIVATE int sqlite3Fts3AllSegdirs(
133971   Fts3Table *p,                   /* FTS3 table */
133972   int iLangid,                    /* Language being queried */
133973   int iIndex,                     /* Index for p->aIndex[] */
133974   int iLevel,                     /* Level to select (relative level) */
133975   sqlite3_stmt **ppStmt           /* OUT: Compiled statement */
133976 ){
133977   int rc;
133978   sqlite3_stmt *pStmt = 0;
133979 
133980   assert( iLevel==FTS3_SEGCURSOR_ALL || iLevel>=0 );
133981   assert( iLevel<FTS3_SEGDIR_MAXLEVEL );
133982   assert( iIndex>=0 && iIndex<p->nIndex );
133983 
133984   if( iLevel<0 ){
133985     /* "SELECT * FROM %_segdir WHERE level BETWEEN ? AND ? ORDER BY ..." */
133986     rc = fts3SqlStmt(p, SQL_SELECT_LEVEL_RANGE, &pStmt, 0);
133987     if( rc==SQLITE_OK ){ 
133988       sqlite3_bind_int64(pStmt, 1, getAbsoluteLevel(p, iLangid, iIndex, 0));
133989       sqlite3_bind_int64(pStmt, 2, 
133990           getAbsoluteLevel(p, iLangid, iIndex, FTS3_SEGDIR_MAXLEVEL-1)
133991       );
133992     }
133993   }else{
133994     /* "SELECT * FROM %_segdir WHERE level = ? ORDER BY ..." */
133995     rc = fts3SqlStmt(p, SQL_SELECT_LEVEL, &pStmt, 0);
133996     if( rc==SQLITE_OK ){ 
133997       sqlite3_bind_int64(pStmt, 1, getAbsoluteLevel(p, iLangid, iIndex,iLevel));
133998     }
133999   }
134000   *ppStmt = pStmt;
134001   return rc;
134002 }
134003 
134004 
134005 /*
134006 ** Append a single varint to a PendingList buffer. SQLITE_OK is returned
134007 ** if successful, or an SQLite error code otherwise.
134008 **
134009 ** This function also serves to allocate the PendingList structure itself.
134010 ** For example, to create a new PendingList structure containing two
134011 ** varints:
134012 **
134013 **   PendingList *p = 0;
134014 **   fts3PendingListAppendVarint(&p, 1);
134015 **   fts3PendingListAppendVarint(&p, 2);
134016 */
134017 static int fts3PendingListAppendVarint(
134018   PendingList **pp,               /* IN/OUT: Pointer to PendingList struct */
134019   sqlite3_int64 i                 /* Value to append to data */
134020 ){
134021   PendingList *p = *pp;
134022 
134023   /* Allocate or grow the PendingList as required. */
134024   if( !p ){
134025     p = sqlite3_malloc(sizeof(*p) + 100);
134026     if( !p ){
134027       return SQLITE_NOMEM;
134028     }
134029     p->nSpace = 100;
134030     p->aData = (char *)&p[1];
134031     p->nData = 0;
134032   }
134033   else if( p->nData+FTS3_VARINT_MAX+1>p->nSpace ){
134034     int nNew = p->nSpace * 2;
134035     p = sqlite3_realloc(p, sizeof(*p) + nNew);
134036     if( !p ){
134037       sqlite3_free(*pp);
134038       *pp = 0;
134039       return SQLITE_NOMEM;
134040     }
134041     p->nSpace = nNew;
134042     p->aData = (char *)&p[1];
134043   }
134044 
134045   /* Append the new serialized varint to the end of the list. */
134046   p->nData += sqlite3Fts3PutVarint(&p->aData[p->nData], i);
134047   p->aData[p->nData] = '\0';
134048   *pp = p;
134049   return SQLITE_OK;
134050 }
134051 
134052 /*
134053 ** Add a docid/column/position entry to a PendingList structure. Non-zero
134054 ** is returned if the structure is sqlite3_realloced as part of adding
134055 ** the entry. Otherwise, zero.
134056 **
134057 ** If an OOM error occurs, *pRc is set to SQLITE_NOMEM before returning.
134058 ** Zero is always returned in this case. Otherwise, if no OOM error occurs,
134059 ** it is set to SQLITE_OK.
134060 */
134061 static int fts3PendingListAppend(
134062   PendingList **pp,               /* IN/OUT: PendingList structure */
134063   sqlite3_int64 iDocid,           /* Docid for entry to add */
134064   sqlite3_int64 iCol,             /* Column for entry to add */
134065   sqlite3_int64 iPos,             /* Position of term for entry to add */
134066   int *pRc                        /* OUT: Return code */
134067 ){
134068   PendingList *p = *pp;
134069   int rc = SQLITE_OK;
134070 
134071   assert( !p || p->iLastDocid<=iDocid );
134072 
134073   if( !p || p->iLastDocid!=iDocid ){
134074     sqlite3_int64 iDelta = iDocid - (p ? p->iLastDocid : 0);
134075     if( p ){
134076       assert( p->nData<p->nSpace );
134077       assert( p->aData[p->nData]==0 );
134078       p->nData++;
134079     }
134080     if( SQLITE_OK!=(rc = fts3PendingListAppendVarint(&p, iDelta)) ){
134081       goto pendinglistappend_out;
134082     }
134083     p->iLastCol = -1;
134084     p->iLastPos = 0;
134085     p->iLastDocid = iDocid;
134086   }
134087   if( iCol>0 && p->iLastCol!=iCol ){
134088     if( SQLITE_OK!=(rc = fts3PendingListAppendVarint(&p, 1))
134089      || SQLITE_OK!=(rc = fts3PendingListAppendVarint(&p, iCol))
134090     ){
134091       goto pendinglistappend_out;
134092     }
134093     p->iLastCol = iCol;
134094     p->iLastPos = 0;
134095   }
134096   if( iCol>=0 ){
134097     assert( iPos>p->iLastPos || (iPos==0 && p->iLastPos==0) );
134098     rc = fts3PendingListAppendVarint(&p, 2+iPos-p->iLastPos);
134099     if( rc==SQLITE_OK ){
134100       p->iLastPos = iPos;
134101     }
134102   }
134103 
134104  pendinglistappend_out:
134105   *pRc = rc;
134106   if( p!=*pp ){
134107     *pp = p;
134108     return 1;
134109   }
134110   return 0;
134111 }
134112 
134113 /*
134114 ** Free a PendingList object allocated by fts3PendingListAppend().
134115 */
134116 static void fts3PendingListDelete(PendingList *pList){
134117   sqlite3_free(pList);
134118 }
134119 
134120 /*
134121 ** Add an entry to one of the pending-terms hash tables.
134122 */
134123 static int fts3PendingTermsAddOne(
134124   Fts3Table *p,
134125   int iCol,
134126   int iPos,
134127   Fts3Hash *pHash,                /* Pending terms hash table to add entry to */
134128   const char *zToken,
134129   int nToken
134130 ){
134131   PendingList *pList;
134132   int rc = SQLITE_OK;
134133 
134134   pList = (PendingList *)fts3HashFind(pHash, zToken, nToken);
134135   if( pList ){
134136     p->nPendingData -= (pList->nData + nToken + sizeof(Fts3HashElem));
134137   }
134138   if( fts3PendingListAppend(&pList, p->iPrevDocid, iCol, iPos, &rc) ){
134139     if( pList==fts3HashInsert(pHash, zToken, nToken, pList) ){
134140       /* Malloc failed while inserting the new entry. This can only 
134141       ** happen if there was no previous entry for this token.
134142       */
134143       assert( 0==fts3HashFind(pHash, zToken, nToken) );
134144       sqlite3_free(pList);
134145       rc = SQLITE_NOMEM;
134146     }
134147   }
134148   if( rc==SQLITE_OK ){
134149     p->nPendingData += (pList->nData + nToken + sizeof(Fts3HashElem));
134150   }
134151   return rc;
134152 }
134153 
134154 /*
134155 ** Tokenize the nul-terminated string zText and add all tokens to the
134156 ** pending-terms hash-table. The docid used is that currently stored in
134157 ** p->iPrevDocid, and the column is specified by argument iCol.
134158 **
134159 ** If successful, SQLITE_OK is returned. Otherwise, an SQLite error code.
134160 */
134161 static int fts3PendingTermsAdd(
134162   Fts3Table *p,                   /* Table into which text will be inserted */
134163   int iLangid,                    /* Language id to use */
134164   const char *zText,              /* Text of document to be inserted */
134165   int iCol,                       /* Column into which text is being inserted */
134166   u32 *pnWord                     /* IN/OUT: Incr. by number tokens inserted */
134167 ){
134168   int rc;
134169   int iStart = 0;
134170   int iEnd = 0;
134171   int iPos = 0;
134172   int nWord = 0;
134173 
134174   char const *zToken;
134175   int nToken = 0;
134176 
134177   sqlite3_tokenizer *pTokenizer = p->pTokenizer;
134178   sqlite3_tokenizer_module const *pModule = pTokenizer->pModule;
134179   sqlite3_tokenizer_cursor *pCsr;
134180   int (*xNext)(sqlite3_tokenizer_cursor *pCursor,
134181       const char**,int*,int*,int*,int*);
134182 
134183   assert( pTokenizer && pModule );
134184 
134185   /* If the user has inserted a NULL value, this function may be called with
134186   ** zText==0. In this case, add zero token entries to the hash table and 
134187   ** return early. */
134188   if( zText==0 ){
134189     *pnWord = 0;
134190     return SQLITE_OK;
134191   }
134192 
134193   rc = sqlite3Fts3OpenTokenizer(pTokenizer, iLangid, zText, -1, &pCsr);
134194   if( rc!=SQLITE_OK ){
134195     return rc;
134196   }
134197 
134198   xNext = pModule->xNext;
134199   while( SQLITE_OK==rc
134200       && SQLITE_OK==(rc = xNext(pCsr, &zToken, &nToken, &iStart, &iEnd, &iPos))
134201   ){
134202     int i;
134203     if( iPos>=nWord ) nWord = iPos+1;
134204 
134205     /* Positions cannot be negative; we use -1 as a terminator internally.
134206     ** Tokens must have a non-zero length.
134207     */
134208     if( iPos<0 || !zToken || nToken<=0 ){
134209       rc = SQLITE_ERROR;
134210       break;
134211     }
134212 
134213     /* Add the term to the terms index */
134214     rc = fts3PendingTermsAddOne(
134215         p, iCol, iPos, &p->aIndex[0].hPending, zToken, nToken
134216     );
134217     
134218     /* Add the term to each of the prefix indexes that it is not too 
134219     ** short for. */
134220     for(i=1; rc==SQLITE_OK && i<p->nIndex; i++){
134221       struct Fts3Index *pIndex = &p->aIndex[i];
134222       if( nToken<pIndex->nPrefix ) continue;
134223       rc = fts3PendingTermsAddOne(
134224           p, iCol, iPos, &pIndex->hPending, zToken, pIndex->nPrefix
134225       );
134226     }
134227   }
134228 
134229   pModule->xClose(pCsr);
134230   *pnWord += nWord;
134231   return (rc==SQLITE_DONE ? SQLITE_OK : rc);
134232 }
134233 
134234 /* 
134235 ** Calling this function indicates that subsequent calls to 
134236 ** fts3PendingTermsAdd() are to add term/position-list pairs for the
134237 ** contents of the document with docid iDocid.
134238 */
134239 static int fts3PendingTermsDocid(
134240   Fts3Table *p,                   /* Full-text table handle */
134241   int iLangid,                    /* Language id of row being written */
134242   sqlite_int64 iDocid             /* Docid of row being written */
134243 ){
134244   assert( iLangid>=0 );
134245 
134246   /* TODO(shess) Explore whether partially flushing the buffer on
134247   ** forced-flush would provide better performance.  I suspect that if
134248   ** we ordered the doclists by size and flushed the largest until the
134249   ** buffer was half empty, that would let the less frequent terms
134250   ** generate longer doclists.
134251   */
134252   if( iDocid<=p->iPrevDocid 
134253    || p->iPrevLangid!=iLangid
134254    || p->nPendingData>p->nMaxPendingData 
134255   ){
134256     int rc = sqlite3Fts3PendingTermsFlush(p);
134257     if( rc!=SQLITE_OK ) return rc;
134258   }
134259   p->iPrevDocid = iDocid;
134260   p->iPrevLangid = iLangid;
134261   return SQLITE_OK;
134262 }
134263 
134264 /*
134265 ** Discard the contents of the pending-terms hash tables. 
134266 */
134267 SQLITE_PRIVATE void sqlite3Fts3PendingTermsClear(Fts3Table *p){
134268   int i;
134269   for(i=0; i<p->nIndex; i++){
134270     Fts3HashElem *pElem;
134271     Fts3Hash *pHash = &p->aIndex[i].hPending;
134272     for(pElem=fts3HashFirst(pHash); pElem; pElem=fts3HashNext(pElem)){
134273       PendingList *pList = (PendingList *)fts3HashData(pElem);
134274       fts3PendingListDelete(pList);
134275     }
134276     fts3HashClear(pHash);
134277   }
134278   p->nPendingData = 0;
134279 }
134280 
134281 /*
134282 ** This function is called by the xUpdate() method as part of an INSERT
134283 ** operation. It adds entries for each term in the new record to the
134284 ** pendingTerms hash table.
134285 **
134286 ** Argument apVal is the same as the similarly named argument passed to
134287 ** fts3InsertData(). Parameter iDocid is the docid of the new row.
134288 */
134289 static int fts3InsertTerms(
134290   Fts3Table *p, 
134291   int iLangid, 
134292   sqlite3_value **apVal, 
134293   u32 *aSz
134294 ){
134295   int i;                          /* Iterator variable */
134296   for(i=2; i<p->nColumn+2; i++){
134297     int iCol = i-2;
134298     if( p->abNotindexed[iCol]==0 ){
134299       const char *zText = (const char *)sqlite3_value_text(apVal[i]);
134300       int rc = fts3PendingTermsAdd(p, iLangid, zText, iCol, &aSz[iCol]);
134301       if( rc!=SQLITE_OK ){
134302         return rc;
134303       }
134304       aSz[p->nColumn] += sqlite3_value_bytes(apVal[i]);
134305     }
134306   }
134307   return SQLITE_OK;
134308 }
134309 
134310 /*
134311 ** This function is called by the xUpdate() method for an INSERT operation.
134312 ** The apVal parameter is passed a copy of the apVal argument passed by
134313 ** SQLite to the xUpdate() method. i.e:
134314 **
134315 **   apVal[0]                Not used for INSERT.
134316 **   apVal[1]                rowid
134317 **   apVal[2]                Left-most user-defined column
134318 **   ...
134319 **   apVal[p->nColumn+1]     Right-most user-defined column
134320 **   apVal[p->nColumn+2]     Hidden column with same name as table
134321 **   apVal[p->nColumn+3]     Hidden "docid" column (alias for rowid)
134322 **   apVal[p->nColumn+4]     Hidden languageid column
134323 */
134324 static int fts3InsertData(
134325   Fts3Table *p,                   /* Full-text table */
134326   sqlite3_value **apVal,          /* Array of values to insert */
134327   sqlite3_int64 *piDocid          /* OUT: Docid for row just inserted */
134328 ){
134329   int rc;                         /* Return code */
134330   sqlite3_stmt *pContentInsert;   /* INSERT INTO %_content VALUES(...) */
134331 
134332   if( p->zContentTbl ){
134333     sqlite3_value *pRowid = apVal[p->nColumn+3];
134334     if( sqlite3_value_type(pRowid)==SQLITE_NULL ){
134335       pRowid = apVal[1];
134336     }
134337     if( sqlite3_value_type(pRowid)!=SQLITE_INTEGER ){
134338       return SQLITE_CONSTRAINT;
134339     }
134340     *piDocid = sqlite3_value_int64(pRowid);
134341     return SQLITE_OK;
134342   }
134343 
134344   /* Locate the statement handle used to insert data into the %_content
134345   ** table. The SQL for this statement is:
134346   **
134347   **   INSERT INTO %_content VALUES(?, ?, ?, ...)
134348   **
134349   ** The statement features N '?' variables, where N is the number of user
134350   ** defined columns in the FTS3 table, plus one for the docid field.
134351   */
134352   rc = fts3SqlStmt(p, SQL_CONTENT_INSERT, &pContentInsert, &apVal[1]);
134353   if( rc==SQLITE_OK && p->zLanguageid ){
134354     rc = sqlite3_bind_int(
134355         pContentInsert, p->nColumn+2, 
134356         sqlite3_value_int(apVal[p->nColumn+4])
134357     );
134358   }
134359   if( rc!=SQLITE_OK ) return rc;
134360 
134361   /* There is a quirk here. The users INSERT statement may have specified
134362   ** a value for the "rowid" field, for the "docid" field, or for both.
134363   ** Which is a problem, since "rowid" and "docid" are aliases for the
134364   ** same value. For example:
134365   **
134366   **   INSERT INTO fts3tbl(rowid, docid) VALUES(1, 2);
134367   **
134368   ** In FTS3, this is an error. It is an error to specify non-NULL values
134369   ** for both docid and some other rowid alias.
134370   */
134371   if( SQLITE_NULL!=sqlite3_value_type(apVal[3+p->nColumn]) ){
134372     if( SQLITE_NULL==sqlite3_value_type(apVal[0])
134373      && SQLITE_NULL!=sqlite3_value_type(apVal[1])
134374     ){
134375       /* A rowid/docid conflict. */
134376       return SQLITE_ERROR;
134377     }
134378     rc = sqlite3_bind_value(pContentInsert, 1, apVal[3+p->nColumn]);
134379     if( rc!=SQLITE_OK ) return rc;
134380   }
134381 
134382   /* Execute the statement to insert the record. Set *piDocid to the 
134383   ** new docid value. 
134384   */
134385   sqlite3_step(pContentInsert);
134386   rc = sqlite3_reset(pContentInsert);
134387 
134388   *piDocid = sqlite3_last_insert_rowid(p->db);
134389   return rc;
134390 }
134391 
134392 
134393 
134394 /*
134395 ** Remove all data from the FTS3 table. Clear the hash table containing
134396 ** pending terms.
134397 */
134398 static int fts3DeleteAll(Fts3Table *p, int bContent){
134399   int rc = SQLITE_OK;             /* Return code */
134400 
134401   /* Discard the contents of the pending-terms hash table. */
134402   sqlite3Fts3PendingTermsClear(p);
134403 
134404   /* Delete everything from the shadow tables. Except, leave %_content as
134405   ** is if bContent is false.  */
134406   assert( p->zContentTbl==0 || bContent==0 );
134407   if( bContent ) fts3SqlExec(&rc, p, SQL_DELETE_ALL_CONTENT, 0);
134408   fts3SqlExec(&rc, p, SQL_DELETE_ALL_SEGMENTS, 0);
134409   fts3SqlExec(&rc, p, SQL_DELETE_ALL_SEGDIR, 0);
134410   if( p->bHasDocsize ){
134411     fts3SqlExec(&rc, p, SQL_DELETE_ALL_DOCSIZE, 0);
134412   }
134413   if( p->bHasStat ){
134414     fts3SqlExec(&rc, p, SQL_DELETE_ALL_STAT, 0);
134415   }
134416   return rc;
134417 }
134418 
134419 /*
134420 **
134421 */
134422 static int langidFromSelect(Fts3Table *p, sqlite3_stmt *pSelect){
134423   int iLangid = 0;
134424   if( p->zLanguageid ) iLangid = sqlite3_column_int(pSelect, p->nColumn+1);
134425   return iLangid;
134426 }
134427 
134428 /*
134429 ** The first element in the apVal[] array is assumed to contain the docid
134430 ** (an integer) of a row about to be deleted. Remove all terms from the
134431 ** full-text index.
134432 */
134433 static void fts3DeleteTerms( 
134434   int *pRC,               /* Result code */
134435   Fts3Table *p,           /* The FTS table to delete from */
134436   sqlite3_value *pRowid,  /* The docid to be deleted */
134437   u32 *aSz,               /* Sizes of deleted document written here */
134438   int *pbFound            /* OUT: Set to true if row really does exist */
134439 ){
134440   int rc;
134441   sqlite3_stmt *pSelect;
134442 
134443   assert( *pbFound==0 );
134444   if( *pRC ) return;
134445   rc = fts3SqlStmt(p, SQL_SELECT_CONTENT_BY_ROWID, &pSelect, &pRowid);
134446   if( rc==SQLITE_OK ){
134447     if( SQLITE_ROW==sqlite3_step(pSelect) ){
134448       int i;
134449       int iLangid = langidFromSelect(p, pSelect);
134450       rc = fts3PendingTermsDocid(p, iLangid, sqlite3_column_int64(pSelect, 0));
134451       for(i=1; rc==SQLITE_OK && i<=p->nColumn; i++){
134452         int iCol = i-1;
134453         if( p->abNotindexed[iCol]==0 ){
134454           const char *zText = (const char *)sqlite3_column_text(pSelect, i);
134455           rc = fts3PendingTermsAdd(p, iLangid, zText, -1, &aSz[iCol]);
134456           aSz[p->nColumn] += sqlite3_column_bytes(pSelect, i);
134457         }
134458       }
134459       if( rc!=SQLITE_OK ){
134460         sqlite3_reset(pSelect);
134461         *pRC = rc;
134462         return;
134463       }
134464       *pbFound = 1;
134465     }
134466     rc = sqlite3_reset(pSelect);
134467   }else{
134468     sqlite3_reset(pSelect);
134469   }
134470   *pRC = rc;
134471 }
134472 
134473 /*
134474 ** Forward declaration to account for the circular dependency between
134475 ** functions fts3SegmentMerge() and fts3AllocateSegdirIdx().
134476 */
134477 static int fts3SegmentMerge(Fts3Table *, int, int, int);
134478 
134479 /* 
134480 ** This function allocates a new level iLevel index in the segdir table.
134481 ** Usually, indexes are allocated within a level sequentially starting
134482 ** with 0, so the allocated index is one greater than the value returned
134483 ** by:
134484 **
134485 **   SELECT max(idx) FROM %_segdir WHERE level = :iLevel
134486 **
134487 ** However, if there are already FTS3_MERGE_COUNT indexes at the requested
134488 ** level, they are merged into a single level (iLevel+1) segment and the 
134489 ** allocated index is 0.
134490 **
134491 ** If successful, *piIdx is set to the allocated index slot and SQLITE_OK
134492 ** returned. Otherwise, an SQLite error code is returned.
134493 */
134494 static int fts3AllocateSegdirIdx(
134495   Fts3Table *p, 
134496   int iLangid,                    /* Language id */
134497   int iIndex,                     /* Index for p->aIndex */
134498   int iLevel, 
134499   int *piIdx
134500 ){
134501   int rc;                         /* Return Code */
134502   sqlite3_stmt *pNextIdx;         /* Query for next idx at level iLevel */
134503   int iNext = 0;                  /* Result of query pNextIdx */
134504 
134505   assert( iLangid>=0 );
134506   assert( p->nIndex>=1 );
134507 
134508   /* Set variable iNext to the next available segdir index at level iLevel. */
134509   rc = fts3SqlStmt(p, SQL_NEXT_SEGMENT_INDEX, &pNextIdx, 0);
134510   if( rc==SQLITE_OK ){
134511     sqlite3_bind_int64(
134512         pNextIdx, 1, getAbsoluteLevel(p, iLangid, iIndex, iLevel)
134513     );
134514     if( SQLITE_ROW==sqlite3_step(pNextIdx) ){
134515       iNext = sqlite3_column_int(pNextIdx, 0);
134516     }
134517     rc = sqlite3_reset(pNextIdx);
134518   }
134519 
134520   if( rc==SQLITE_OK ){
134521     /* If iNext is FTS3_MERGE_COUNT, indicating that level iLevel is already
134522     ** full, merge all segments in level iLevel into a single iLevel+1
134523     ** segment and allocate (newly freed) index 0 at level iLevel. Otherwise,
134524     ** if iNext is less than FTS3_MERGE_COUNT, allocate index iNext.
134525     */
134526     if( iNext>=FTS3_MERGE_COUNT ){
134527       fts3LogMerge(16, getAbsoluteLevel(p, iLangid, iIndex, iLevel));
134528       rc = fts3SegmentMerge(p, iLangid, iIndex, iLevel);
134529       *piIdx = 0;
134530     }else{
134531       *piIdx = iNext;
134532     }
134533   }
134534 
134535   return rc;
134536 }
134537 
134538 /*
134539 ** The %_segments table is declared as follows:
134540 **
134541 **   CREATE TABLE %_segments(blockid INTEGER PRIMARY KEY, block BLOB)
134542 **
134543 ** This function reads data from a single row of the %_segments table. The
134544 ** specific row is identified by the iBlockid parameter. If paBlob is not
134545 ** NULL, then a buffer is allocated using sqlite3_malloc() and populated
134546 ** with the contents of the blob stored in the "block" column of the 
134547 ** identified table row is. Whether or not paBlob is NULL, *pnBlob is set
134548 ** to the size of the blob in bytes before returning.
134549 **
134550 ** If an error occurs, or the table does not contain the specified row,
134551 ** an SQLite error code is returned. Otherwise, SQLITE_OK is returned. If
134552 ** paBlob is non-NULL, then it is the responsibility of the caller to
134553 ** eventually free the returned buffer.
134554 **
134555 ** This function may leave an open sqlite3_blob* handle in the
134556 ** Fts3Table.pSegments variable. This handle is reused by subsequent calls
134557 ** to this function. The handle may be closed by calling the
134558 ** sqlite3Fts3SegmentsClose() function. Reusing a blob handle is a handy
134559 ** performance improvement, but the blob handle should always be closed
134560 ** before control is returned to the user (to prevent a lock being held
134561 ** on the database file for longer than necessary). Thus, any virtual table
134562 ** method (xFilter etc.) that may directly or indirectly call this function
134563 ** must call sqlite3Fts3SegmentsClose() before returning.
134564 */
134565 SQLITE_PRIVATE int sqlite3Fts3ReadBlock(
134566   Fts3Table *p,                   /* FTS3 table handle */
134567   sqlite3_int64 iBlockid,         /* Access the row with blockid=$iBlockid */
134568   char **paBlob,                  /* OUT: Blob data in malloc'd buffer */
134569   int *pnBlob,                    /* OUT: Size of blob data */
134570   int *pnLoad                     /* OUT: Bytes actually loaded */
134571 ){
134572   int rc;                         /* Return code */
134573 
134574   /* pnBlob must be non-NULL. paBlob may be NULL or non-NULL. */
134575   assert( pnBlob );
134576 
134577   if( p->pSegments ){
134578     rc = sqlite3_blob_reopen(p->pSegments, iBlockid);
134579   }else{
134580     if( 0==p->zSegmentsTbl ){
134581       p->zSegmentsTbl = sqlite3_mprintf("%s_segments", p->zName);
134582       if( 0==p->zSegmentsTbl ) return SQLITE_NOMEM;
134583     }
134584     rc = sqlite3_blob_open(
134585        p->db, p->zDb, p->zSegmentsTbl, "block", iBlockid, 0, &p->pSegments
134586     );
134587   }
134588 
134589   if( rc==SQLITE_OK ){
134590     int nByte = sqlite3_blob_bytes(p->pSegments);
134591     *pnBlob = nByte;
134592     if( paBlob ){
134593       char *aByte = sqlite3_malloc(nByte + FTS3_NODE_PADDING);
134594       if( !aByte ){
134595         rc = SQLITE_NOMEM;
134596       }else{
134597         if( pnLoad && nByte>(FTS3_NODE_CHUNK_THRESHOLD) ){
134598           nByte = FTS3_NODE_CHUNKSIZE;
134599           *pnLoad = nByte;
134600         }
134601         rc = sqlite3_blob_read(p->pSegments, aByte, nByte, 0);
134602         memset(&aByte[nByte], 0, FTS3_NODE_PADDING);
134603         if( rc!=SQLITE_OK ){
134604           sqlite3_free(aByte);
134605           aByte = 0;
134606         }
134607       }
134608       *paBlob = aByte;
134609     }
134610   }
134611 
134612   return rc;
134613 }
134614 
134615 /*
134616 ** Close the blob handle at p->pSegments, if it is open. See comments above
134617 ** the sqlite3Fts3ReadBlock() function for details.
134618 */
134619 SQLITE_PRIVATE void sqlite3Fts3SegmentsClose(Fts3Table *p){
134620   sqlite3_blob_close(p->pSegments);
134621   p->pSegments = 0;
134622 }
134623     
134624 static int fts3SegReaderIncrRead(Fts3SegReader *pReader){
134625   int nRead;                      /* Number of bytes to read */
134626   int rc;                         /* Return code */
134627 
134628   nRead = MIN(pReader->nNode - pReader->nPopulate, FTS3_NODE_CHUNKSIZE);
134629   rc = sqlite3_blob_read(
134630       pReader->pBlob, 
134631       &pReader->aNode[pReader->nPopulate],
134632       nRead,
134633       pReader->nPopulate
134634   );
134635 
134636   if( rc==SQLITE_OK ){
134637     pReader->nPopulate += nRead;
134638     memset(&pReader->aNode[pReader->nPopulate], 0, FTS3_NODE_PADDING);
134639     if( pReader->nPopulate==pReader->nNode ){
134640       sqlite3_blob_close(pReader->pBlob);
134641       pReader->pBlob = 0;
134642       pReader->nPopulate = 0;
134643     }
134644   }
134645   return rc;
134646 }
134647 
134648 static int fts3SegReaderRequire(Fts3SegReader *pReader, char *pFrom, int nByte){
134649   int rc = SQLITE_OK;
134650   assert( !pReader->pBlob 
134651        || (pFrom>=pReader->aNode && pFrom<&pReader->aNode[pReader->nNode])
134652   );
134653   while( pReader->pBlob && rc==SQLITE_OK 
134654      &&  (pFrom - pReader->aNode + nByte)>pReader->nPopulate
134655   ){
134656     rc = fts3SegReaderIncrRead(pReader);
134657   }
134658   return rc;
134659 }
134660 
134661 /*
134662 ** Set an Fts3SegReader cursor to point at EOF.
134663 */
134664 static void fts3SegReaderSetEof(Fts3SegReader *pSeg){
134665   if( !fts3SegReaderIsRootOnly(pSeg) ){
134666     sqlite3_free(pSeg->aNode);
134667     sqlite3_blob_close(pSeg->pBlob);
134668     pSeg->pBlob = 0;
134669   }
134670   pSeg->aNode = 0;
134671 }
134672 
134673 /*
134674 ** Move the iterator passed as the first argument to the next term in the
134675 ** segment. If successful, SQLITE_OK is returned. If there is no next term,
134676 ** SQLITE_DONE. Otherwise, an SQLite error code.
134677 */
134678 static int fts3SegReaderNext(
134679   Fts3Table *p, 
134680   Fts3SegReader *pReader,
134681   int bIncr
134682 ){
134683   int rc;                         /* Return code of various sub-routines */
134684   char *pNext;                    /* Cursor variable */
134685   int nPrefix;                    /* Number of bytes in term prefix */
134686   int nSuffix;                    /* Number of bytes in term suffix */
134687 
134688   if( !pReader->aDoclist ){
134689     pNext = pReader->aNode;
134690   }else{
134691     pNext = &pReader->aDoclist[pReader->nDoclist];
134692   }
134693 
134694   if( !pNext || pNext>=&pReader->aNode[pReader->nNode] ){
134695 
134696     if( fts3SegReaderIsPending(pReader) ){
134697       Fts3HashElem *pElem = *(pReader->ppNextElem);
134698       if( pElem==0 ){
134699         pReader->aNode = 0;
134700       }else{
134701         PendingList *pList = (PendingList *)fts3HashData(pElem);
134702         pReader->zTerm = (char *)fts3HashKey(pElem);
134703         pReader->nTerm = fts3HashKeysize(pElem);
134704         pReader->nNode = pReader->nDoclist = pList->nData + 1;
134705         pReader->aNode = pReader->aDoclist = pList->aData;
134706         pReader->ppNextElem++;
134707         assert( pReader->aNode );
134708       }
134709       return SQLITE_OK;
134710     }
134711 
134712     fts3SegReaderSetEof(pReader);
134713 
134714     /* If iCurrentBlock>=iLeafEndBlock, this is an EOF condition. All leaf 
134715     ** blocks have already been traversed.  */
134716     assert( pReader->iCurrentBlock<=pReader->iLeafEndBlock );
134717     if( pReader->iCurrentBlock>=pReader->iLeafEndBlock ){
134718       return SQLITE_OK;
134719     }
134720 
134721     rc = sqlite3Fts3ReadBlock(
134722         p, ++pReader->iCurrentBlock, &pReader->aNode, &pReader->nNode, 
134723         (bIncr ? &pReader->nPopulate : 0)
134724     );
134725     if( rc!=SQLITE_OK ) return rc;
134726     assert( pReader->pBlob==0 );
134727     if( bIncr && pReader->nPopulate<pReader->nNode ){
134728       pReader->pBlob = p->pSegments;
134729       p->pSegments = 0;
134730     }
134731     pNext = pReader->aNode;
134732   }
134733 
134734   assert( !fts3SegReaderIsPending(pReader) );
134735 
134736   rc = fts3SegReaderRequire(pReader, pNext, FTS3_VARINT_MAX*2);
134737   if( rc!=SQLITE_OK ) return rc;
134738   
134739   /* Because of the FTS3_NODE_PADDING bytes of padding, the following is 
134740   ** safe (no risk of overread) even if the node data is corrupted. */
134741   pNext += fts3GetVarint32(pNext, &nPrefix);
134742   pNext += fts3GetVarint32(pNext, &nSuffix);
134743   if( nPrefix<0 || nSuffix<=0 
134744    || &pNext[nSuffix]>&pReader->aNode[pReader->nNode] 
134745   ){
134746     return FTS_CORRUPT_VTAB;
134747   }
134748 
134749   if( nPrefix+nSuffix>pReader->nTermAlloc ){
134750     int nNew = (nPrefix+nSuffix)*2;
134751     char *zNew = sqlite3_realloc(pReader->zTerm, nNew);
134752     if( !zNew ){
134753       return SQLITE_NOMEM;
134754     }
134755     pReader->zTerm = zNew;
134756     pReader->nTermAlloc = nNew;
134757   }
134758 
134759   rc = fts3SegReaderRequire(pReader, pNext, nSuffix+FTS3_VARINT_MAX);
134760   if( rc!=SQLITE_OK ) return rc;
134761 
134762   memcpy(&pReader->zTerm[nPrefix], pNext, nSuffix);
134763   pReader->nTerm = nPrefix+nSuffix;
134764   pNext += nSuffix;
134765   pNext += fts3GetVarint32(pNext, &pReader->nDoclist);
134766   pReader->aDoclist = pNext;
134767   pReader->pOffsetList = 0;
134768 
134769   /* Check that the doclist does not appear to extend past the end of the
134770   ** b-tree node. And that the final byte of the doclist is 0x00. If either 
134771   ** of these statements is untrue, then the data structure is corrupt.
134772   */
134773   if( &pReader->aDoclist[pReader->nDoclist]>&pReader->aNode[pReader->nNode] 
134774    || (pReader->nPopulate==0 && pReader->aDoclist[pReader->nDoclist-1])
134775   ){
134776     return FTS_CORRUPT_VTAB;
134777   }
134778   return SQLITE_OK;
134779 }
134780 
134781 /*
134782 ** Set the SegReader to point to the first docid in the doclist associated
134783 ** with the current term.
134784 */
134785 static int fts3SegReaderFirstDocid(Fts3Table *pTab, Fts3SegReader *pReader){
134786   int rc = SQLITE_OK;
134787   assert( pReader->aDoclist );
134788   assert( !pReader->pOffsetList );
134789   if( pTab->bDescIdx && fts3SegReaderIsPending(pReader) ){
134790     u8 bEof = 0;
134791     pReader->iDocid = 0;
134792     pReader->nOffsetList = 0;
134793     sqlite3Fts3DoclistPrev(0,
134794         pReader->aDoclist, pReader->nDoclist, &pReader->pOffsetList, 
134795         &pReader->iDocid, &pReader->nOffsetList, &bEof
134796     );
134797   }else{
134798     rc = fts3SegReaderRequire(pReader, pReader->aDoclist, FTS3_VARINT_MAX);
134799     if( rc==SQLITE_OK ){
134800       int n = sqlite3Fts3GetVarint(pReader->aDoclist, &pReader->iDocid);
134801       pReader->pOffsetList = &pReader->aDoclist[n];
134802     }
134803   }
134804   return rc;
134805 }
134806 
134807 /*
134808 ** Advance the SegReader to point to the next docid in the doclist
134809 ** associated with the current term.
134810 ** 
134811 ** If arguments ppOffsetList and pnOffsetList are not NULL, then 
134812 ** *ppOffsetList is set to point to the first column-offset list
134813 ** in the doclist entry (i.e. immediately past the docid varint).
134814 ** *pnOffsetList is set to the length of the set of column-offset
134815 ** lists, not including the nul-terminator byte. For example:
134816 */
134817 static int fts3SegReaderNextDocid(
134818   Fts3Table *pTab,
134819   Fts3SegReader *pReader,         /* Reader to advance to next docid */
134820   char **ppOffsetList,            /* OUT: Pointer to current position-list */
134821   int *pnOffsetList               /* OUT: Length of *ppOffsetList in bytes */
134822 ){
134823   int rc = SQLITE_OK;
134824   char *p = pReader->pOffsetList;
134825   char c = 0;
134826 
134827   assert( p );
134828 
134829   if( pTab->bDescIdx && fts3SegReaderIsPending(pReader) ){
134830     /* A pending-terms seg-reader for an FTS4 table that uses order=desc.
134831     ** Pending-terms doclists are always built up in ascending order, so
134832     ** we have to iterate through them backwards here. */
134833     u8 bEof = 0;
134834     if( ppOffsetList ){
134835       *ppOffsetList = pReader->pOffsetList;
134836       *pnOffsetList = pReader->nOffsetList - 1;
134837     }
134838     sqlite3Fts3DoclistPrev(0,
134839         pReader->aDoclist, pReader->nDoclist, &p, &pReader->iDocid,
134840         &pReader->nOffsetList, &bEof
134841     );
134842     if( bEof ){
134843       pReader->pOffsetList = 0;
134844     }else{
134845       pReader->pOffsetList = p;
134846     }
134847   }else{
134848     char *pEnd = &pReader->aDoclist[pReader->nDoclist];
134849 
134850     /* Pointer p currently points at the first byte of an offset list. The
134851     ** following block advances it to point one byte past the end of
134852     ** the same offset list. */
134853     while( 1 ){
134854   
134855       /* The following line of code (and the "p++" below the while() loop) is
134856       ** normally all that is required to move pointer p to the desired 
134857       ** position. The exception is if this node is being loaded from disk
134858       ** incrementally and pointer "p" now points to the first byte past
134859       ** the populated part of pReader->aNode[].
134860       */
134861       while( *p | c ) c = *p++ & 0x80;
134862       assert( *p==0 );
134863   
134864       if( pReader->pBlob==0 || p<&pReader->aNode[pReader->nPopulate] ) break;
134865       rc = fts3SegReaderIncrRead(pReader);
134866       if( rc!=SQLITE_OK ) return rc;
134867     }
134868     p++;
134869   
134870     /* If required, populate the output variables with a pointer to and the
134871     ** size of the previous offset-list.
134872     */
134873     if( ppOffsetList ){
134874       *ppOffsetList = pReader->pOffsetList;
134875       *pnOffsetList = (int)(p - pReader->pOffsetList - 1);
134876     }
134877 
134878     /* List may have been edited in place by fts3EvalNearTrim() */
134879     while( p<pEnd && *p==0 ) p++;
134880   
134881     /* If there are no more entries in the doclist, set pOffsetList to
134882     ** NULL. Otherwise, set Fts3SegReader.iDocid to the next docid and
134883     ** Fts3SegReader.pOffsetList to point to the next offset list before
134884     ** returning.
134885     */
134886     if( p>=pEnd ){
134887       pReader->pOffsetList = 0;
134888     }else{
134889       rc = fts3SegReaderRequire(pReader, p, FTS3_VARINT_MAX);
134890       if( rc==SQLITE_OK ){
134891         sqlite3_int64 iDelta;
134892         pReader->pOffsetList = p + sqlite3Fts3GetVarint(p, &iDelta);
134893         if( pTab->bDescIdx ){
134894           pReader->iDocid -= iDelta;
134895         }else{
134896           pReader->iDocid += iDelta;
134897         }
134898       }
134899     }
134900   }
134901 
134902   return SQLITE_OK;
134903 }
134904 
134905 
134906 SQLITE_PRIVATE int sqlite3Fts3MsrOvfl(
134907   Fts3Cursor *pCsr, 
134908   Fts3MultiSegReader *pMsr,
134909   int *pnOvfl
134910 ){
134911   Fts3Table *p = (Fts3Table*)pCsr->base.pVtab;
134912   int nOvfl = 0;
134913   int ii;
134914   int rc = SQLITE_OK;
134915   int pgsz = p->nPgsz;
134916 
134917   assert( p->bFts4 );
134918   assert( pgsz>0 );
134919 
134920   for(ii=0; rc==SQLITE_OK && ii<pMsr->nSegment; ii++){
134921     Fts3SegReader *pReader = pMsr->apSegment[ii];
134922     if( !fts3SegReaderIsPending(pReader) 
134923      && !fts3SegReaderIsRootOnly(pReader) 
134924     ){
134925       sqlite3_int64 jj;
134926       for(jj=pReader->iStartBlock; jj<=pReader->iLeafEndBlock; jj++){
134927         int nBlob;
134928         rc = sqlite3Fts3ReadBlock(p, jj, 0, &nBlob, 0);
134929         if( rc!=SQLITE_OK ) break;
134930         if( (nBlob+35)>pgsz ){
134931           nOvfl += (nBlob + 34)/pgsz;
134932         }
134933       }
134934     }
134935   }
134936   *pnOvfl = nOvfl;
134937   return rc;
134938 }
134939 
134940 /*
134941 ** Free all allocations associated with the iterator passed as the 
134942 ** second argument.
134943 */
134944 SQLITE_PRIVATE void sqlite3Fts3SegReaderFree(Fts3SegReader *pReader){
134945   if( pReader && !fts3SegReaderIsPending(pReader) ){
134946     sqlite3_free(pReader->zTerm);
134947     if( !fts3SegReaderIsRootOnly(pReader) ){
134948       sqlite3_free(pReader->aNode);
134949       sqlite3_blob_close(pReader->pBlob);
134950     }
134951   }
134952   sqlite3_free(pReader);
134953 }
134954 
134955 /*
134956 ** Allocate a new SegReader object.
134957 */
134958 SQLITE_PRIVATE int sqlite3Fts3SegReaderNew(
134959   int iAge,                       /* Segment "age". */
134960   int bLookup,                    /* True for a lookup only */
134961   sqlite3_int64 iStartLeaf,       /* First leaf to traverse */
134962   sqlite3_int64 iEndLeaf,         /* Final leaf to traverse */
134963   sqlite3_int64 iEndBlock,        /* Final block of segment */
134964   const char *zRoot,              /* Buffer containing root node */
134965   int nRoot,                      /* Size of buffer containing root node */
134966   Fts3SegReader **ppReader        /* OUT: Allocated Fts3SegReader */
134967 ){
134968   Fts3SegReader *pReader;         /* Newly allocated SegReader object */
134969   int nExtra = 0;                 /* Bytes to allocate segment root node */
134970 
134971   assert( iStartLeaf<=iEndLeaf );
134972   if( iStartLeaf==0 ){
134973     nExtra = nRoot + FTS3_NODE_PADDING;
134974   }
134975 
134976   pReader = (Fts3SegReader *)sqlite3_malloc(sizeof(Fts3SegReader) + nExtra);
134977   if( !pReader ){
134978     return SQLITE_NOMEM;
134979   }
134980   memset(pReader, 0, sizeof(Fts3SegReader));
134981   pReader->iIdx = iAge;
134982   pReader->bLookup = bLookup!=0;
134983   pReader->iStartBlock = iStartLeaf;
134984   pReader->iLeafEndBlock = iEndLeaf;
134985   pReader->iEndBlock = iEndBlock;
134986 
134987   if( nExtra ){
134988     /* The entire segment is stored in the root node. */
134989     pReader->aNode = (char *)&pReader[1];
134990     pReader->rootOnly = 1;
134991     pReader->nNode = nRoot;
134992     memcpy(pReader->aNode, zRoot, nRoot);
134993     memset(&pReader->aNode[nRoot], 0, FTS3_NODE_PADDING);
134994   }else{
134995     pReader->iCurrentBlock = iStartLeaf-1;
134996   }
134997   *ppReader = pReader;
134998   return SQLITE_OK;
134999 }
135000 
135001 /*
135002 ** This is a comparison function used as a qsort() callback when sorting
135003 ** an array of pending terms by term. This occurs as part of flushing
135004 ** the contents of the pending-terms hash table to the database.
135005 */
135006 static int fts3CompareElemByTerm(const void *lhs, const void *rhs){
135007   char *z1 = fts3HashKey(*(Fts3HashElem **)lhs);
135008   char *z2 = fts3HashKey(*(Fts3HashElem **)rhs);
135009   int n1 = fts3HashKeysize(*(Fts3HashElem **)lhs);
135010   int n2 = fts3HashKeysize(*(Fts3HashElem **)rhs);
135011 
135012   int n = (n1<n2 ? n1 : n2);
135013   int c = memcmp(z1, z2, n);
135014   if( c==0 ){
135015     c = n1 - n2;
135016   }
135017   return c;
135018 }
135019 
135020 /*
135021 ** This function is used to allocate an Fts3SegReader that iterates through
135022 ** a subset of the terms stored in the Fts3Table.pendingTerms array.
135023 **
135024 ** If the isPrefixIter parameter is zero, then the returned SegReader iterates
135025 ** through each term in the pending-terms table. Or, if isPrefixIter is
135026 ** non-zero, it iterates through each term and its prefixes. For example, if
135027 ** the pending terms hash table contains the terms "sqlite", "mysql" and
135028 ** "firebird", then the iterator visits the following 'terms' (in the order
135029 ** shown):
135030 **
135031 **   f fi fir fire fireb firebi firebir firebird
135032 **   m my mys mysq mysql
135033 **   s sq sql sqli sqlit sqlite
135034 **
135035 ** Whereas if isPrefixIter is zero, the terms visited are:
135036 **
135037 **   firebird mysql sqlite
135038 */
135039 SQLITE_PRIVATE int sqlite3Fts3SegReaderPending(
135040   Fts3Table *p,                   /* Virtual table handle */
135041   int iIndex,                     /* Index for p->aIndex */
135042   const char *zTerm,              /* Term to search for */
135043   int nTerm,                      /* Size of buffer zTerm */
135044   int bPrefix,                    /* True for a prefix iterator */
135045   Fts3SegReader **ppReader        /* OUT: SegReader for pending-terms */
135046 ){
135047   Fts3SegReader *pReader = 0;     /* Fts3SegReader object to return */
135048   Fts3HashElem *pE;               /* Iterator variable */
135049   Fts3HashElem **aElem = 0;       /* Array of term hash entries to scan */
135050   int nElem = 0;                  /* Size of array at aElem */
135051   int rc = SQLITE_OK;             /* Return Code */
135052   Fts3Hash *pHash;
135053 
135054   pHash = &p->aIndex[iIndex].hPending;
135055   if( bPrefix ){
135056     int nAlloc = 0;               /* Size of allocated array at aElem */
135057 
135058     for(pE=fts3HashFirst(pHash); pE; pE=fts3HashNext(pE)){
135059       char *zKey = (char *)fts3HashKey(pE);
135060       int nKey = fts3HashKeysize(pE);
135061       if( nTerm==0 || (nKey>=nTerm && 0==memcmp(zKey, zTerm, nTerm)) ){
135062         if( nElem==nAlloc ){
135063           Fts3HashElem **aElem2;
135064           nAlloc += 16;
135065           aElem2 = (Fts3HashElem **)sqlite3_realloc(
135066               aElem, nAlloc*sizeof(Fts3HashElem *)
135067           );
135068           if( !aElem2 ){
135069             rc = SQLITE_NOMEM;
135070             nElem = 0;
135071             break;
135072           }
135073           aElem = aElem2;
135074         }
135075 
135076         aElem[nElem++] = pE;
135077       }
135078     }
135079 
135080     /* If more than one term matches the prefix, sort the Fts3HashElem
135081     ** objects in term order using qsort(). This uses the same comparison
135082     ** callback as is used when flushing terms to disk.
135083     */
135084     if( nElem>1 ){
135085       qsort(aElem, nElem, sizeof(Fts3HashElem *), fts3CompareElemByTerm);
135086     }
135087 
135088   }else{
135089     /* The query is a simple term lookup that matches at most one term in
135090     ** the index. All that is required is a straight hash-lookup. 
135091     **
135092     ** Because the stack address of pE may be accessed via the aElem pointer
135093     ** below, the "Fts3HashElem *pE" must be declared so that it is valid
135094     ** within this entire function, not just this "else{...}" block.
135095     */
135096     pE = fts3HashFindElem(pHash, zTerm, nTerm);
135097     if( pE ){
135098       aElem = &pE;
135099       nElem = 1;
135100     }
135101   }
135102 
135103   if( nElem>0 ){
135104     int nByte = sizeof(Fts3SegReader) + (nElem+1)*sizeof(Fts3HashElem *);
135105     pReader = (Fts3SegReader *)sqlite3_malloc(nByte);
135106     if( !pReader ){
135107       rc = SQLITE_NOMEM;
135108     }else{
135109       memset(pReader, 0, nByte);
135110       pReader->iIdx = 0x7FFFFFFF;
135111       pReader->ppNextElem = (Fts3HashElem **)&pReader[1];
135112       memcpy(pReader->ppNextElem, aElem, nElem*sizeof(Fts3HashElem *));
135113     }
135114   }
135115 
135116   if( bPrefix ){
135117     sqlite3_free(aElem);
135118   }
135119   *ppReader = pReader;
135120   return rc;
135121 }
135122 
135123 /*
135124 ** Compare the entries pointed to by two Fts3SegReader structures. 
135125 ** Comparison is as follows:
135126 **
135127 **   1) EOF is greater than not EOF.
135128 **
135129 **   2) The current terms (if any) are compared using memcmp(). If one
135130 **      term is a prefix of another, the longer term is considered the
135131 **      larger.
135132 **
135133 **   3) By segment age. An older segment is considered larger.
135134 */
135135 static int fts3SegReaderCmp(Fts3SegReader *pLhs, Fts3SegReader *pRhs){
135136   int rc;
135137   if( pLhs->aNode && pRhs->aNode ){
135138     int rc2 = pLhs->nTerm - pRhs->nTerm;
135139     if( rc2<0 ){
135140       rc = memcmp(pLhs->zTerm, pRhs->zTerm, pLhs->nTerm);
135141     }else{
135142       rc = memcmp(pLhs->zTerm, pRhs->zTerm, pRhs->nTerm);
135143     }
135144     if( rc==0 ){
135145       rc = rc2;
135146     }
135147   }else{
135148     rc = (pLhs->aNode==0) - (pRhs->aNode==0);
135149   }
135150   if( rc==0 ){
135151     rc = pRhs->iIdx - pLhs->iIdx;
135152   }
135153   assert( rc!=0 );
135154   return rc;
135155 }
135156 
135157 /*
135158 ** A different comparison function for SegReader structures. In this
135159 ** version, it is assumed that each SegReader points to an entry in
135160 ** a doclist for identical terms. Comparison is made as follows:
135161 **
135162 **   1) EOF (end of doclist in this case) is greater than not EOF.
135163 **
135164 **   2) By current docid.
135165 **
135166 **   3) By segment age. An older segment is considered larger.
135167 */
135168 static int fts3SegReaderDoclistCmp(Fts3SegReader *pLhs, Fts3SegReader *pRhs){
135169   int rc = (pLhs->pOffsetList==0)-(pRhs->pOffsetList==0);
135170   if( rc==0 ){
135171     if( pLhs->iDocid==pRhs->iDocid ){
135172       rc = pRhs->iIdx - pLhs->iIdx;
135173     }else{
135174       rc = (pLhs->iDocid > pRhs->iDocid) ? 1 : -1;
135175     }
135176   }
135177   assert( pLhs->aNode && pRhs->aNode );
135178   return rc;
135179 }
135180 static int fts3SegReaderDoclistCmpRev(Fts3SegReader *pLhs, Fts3SegReader *pRhs){
135181   int rc = (pLhs->pOffsetList==0)-(pRhs->pOffsetList==0);
135182   if( rc==0 ){
135183     if( pLhs->iDocid==pRhs->iDocid ){
135184       rc = pRhs->iIdx - pLhs->iIdx;
135185     }else{
135186       rc = (pLhs->iDocid < pRhs->iDocid) ? 1 : -1;
135187     }
135188   }
135189   assert( pLhs->aNode && pRhs->aNode );
135190   return rc;
135191 }
135192 
135193 /*
135194 ** Compare the term that the Fts3SegReader object passed as the first argument
135195 ** points to with the term specified by arguments zTerm and nTerm. 
135196 **
135197 ** If the pSeg iterator is already at EOF, return 0. Otherwise, return
135198 ** -ve if the pSeg term is less than zTerm/nTerm, 0 if the two terms are
135199 ** equal, or +ve if the pSeg term is greater than zTerm/nTerm.
135200 */
135201 static int fts3SegReaderTermCmp(
135202   Fts3SegReader *pSeg,            /* Segment reader object */
135203   const char *zTerm,              /* Term to compare to */
135204   int nTerm                       /* Size of term zTerm in bytes */
135205 ){
135206   int res = 0;
135207   if( pSeg->aNode ){
135208     if( pSeg->nTerm>nTerm ){
135209       res = memcmp(pSeg->zTerm, zTerm, nTerm);
135210     }else{
135211       res = memcmp(pSeg->zTerm, zTerm, pSeg->nTerm);
135212     }
135213     if( res==0 ){
135214       res = pSeg->nTerm-nTerm;
135215     }
135216   }
135217   return res;
135218 }
135219 
135220 /*
135221 ** Argument apSegment is an array of nSegment elements. It is known that
135222 ** the final (nSegment-nSuspect) members are already in sorted order
135223 ** (according to the comparison function provided). This function shuffles
135224 ** the array around until all entries are in sorted order.
135225 */
135226 static void fts3SegReaderSort(
135227   Fts3SegReader **apSegment,                     /* Array to sort entries of */
135228   int nSegment,                                  /* Size of apSegment array */
135229   int nSuspect,                                  /* Unsorted entry count */
135230   int (*xCmp)(Fts3SegReader *, Fts3SegReader *)  /* Comparison function */
135231 ){
135232   int i;                          /* Iterator variable */
135233 
135234   assert( nSuspect<=nSegment );
135235 
135236   if( nSuspect==nSegment ) nSuspect--;
135237   for(i=nSuspect-1; i>=0; i--){
135238     int j;
135239     for(j=i; j<(nSegment-1); j++){
135240       Fts3SegReader *pTmp;
135241       if( xCmp(apSegment[j], apSegment[j+1])<0 ) break;
135242       pTmp = apSegment[j+1];
135243       apSegment[j+1] = apSegment[j];
135244       apSegment[j] = pTmp;
135245     }
135246   }
135247 
135248 #ifndef NDEBUG
135249   /* Check that the list really is sorted now. */
135250   for(i=0; i<(nSuspect-1); i++){
135251     assert( xCmp(apSegment[i], apSegment[i+1])<0 );
135252   }
135253 #endif
135254 }
135255 
135256 /* 
135257 ** Insert a record into the %_segments table.
135258 */
135259 static int fts3WriteSegment(
135260   Fts3Table *p,                   /* Virtual table handle */
135261   sqlite3_int64 iBlock,           /* Block id for new block */
135262   char *z,                        /* Pointer to buffer containing block data */
135263   int n                           /* Size of buffer z in bytes */
135264 ){
135265   sqlite3_stmt *pStmt;
135266   int rc = fts3SqlStmt(p, SQL_INSERT_SEGMENTS, &pStmt, 0);
135267   if( rc==SQLITE_OK ){
135268     sqlite3_bind_int64(pStmt, 1, iBlock);
135269     sqlite3_bind_blob(pStmt, 2, z, n, SQLITE_STATIC);
135270     sqlite3_step(pStmt);
135271     rc = sqlite3_reset(pStmt);
135272   }
135273   return rc;
135274 }
135275 
135276 /*
135277 ** Find the largest relative level number in the table. If successful, set
135278 ** *pnMax to this value and return SQLITE_OK. Otherwise, if an error occurs,
135279 ** set *pnMax to zero and return an SQLite error code.
135280 */
135281 SQLITE_PRIVATE int sqlite3Fts3MaxLevel(Fts3Table *p, int *pnMax){
135282   int rc;
135283   int mxLevel = 0;
135284   sqlite3_stmt *pStmt = 0;
135285 
135286   rc = fts3SqlStmt(p, SQL_SELECT_MXLEVEL, &pStmt, 0);
135287   if( rc==SQLITE_OK ){
135288     if( SQLITE_ROW==sqlite3_step(pStmt) ){
135289       mxLevel = sqlite3_column_int(pStmt, 0);
135290     }
135291     rc = sqlite3_reset(pStmt);
135292   }
135293   *pnMax = mxLevel;
135294   return rc;
135295 }
135296 
135297 /* 
135298 ** Insert a record into the %_segdir table.
135299 */
135300 static int fts3WriteSegdir(
135301   Fts3Table *p,                   /* Virtual table handle */
135302   sqlite3_int64 iLevel,           /* Value for "level" field (absolute level) */
135303   int iIdx,                       /* Value for "idx" field */
135304   sqlite3_int64 iStartBlock,      /* Value for "start_block" field */
135305   sqlite3_int64 iLeafEndBlock,    /* Value for "leaves_end_block" field */
135306   sqlite3_int64 iEndBlock,        /* Value for "end_block" field */
135307   char *zRoot,                    /* Blob value for "root" field */
135308   int nRoot                       /* Number of bytes in buffer zRoot */
135309 ){
135310   sqlite3_stmt *pStmt;
135311   int rc = fts3SqlStmt(p, SQL_INSERT_SEGDIR, &pStmt, 0);
135312   if( rc==SQLITE_OK ){
135313     sqlite3_bind_int64(pStmt, 1, iLevel);
135314     sqlite3_bind_int(pStmt, 2, iIdx);
135315     sqlite3_bind_int64(pStmt, 3, iStartBlock);
135316     sqlite3_bind_int64(pStmt, 4, iLeafEndBlock);
135317     sqlite3_bind_int64(pStmt, 5, iEndBlock);
135318     sqlite3_bind_blob(pStmt, 6, zRoot, nRoot, SQLITE_STATIC);
135319     sqlite3_step(pStmt);
135320     rc = sqlite3_reset(pStmt);
135321   }
135322   return rc;
135323 }
135324 
135325 /*
135326 ** Return the size of the common prefix (if any) shared by zPrev and
135327 ** zNext, in bytes. For example, 
135328 **
135329 **   fts3PrefixCompress("abc", 3, "abcdef", 6)   // returns 3
135330 **   fts3PrefixCompress("abX", 3, "abcdef", 6)   // returns 2
135331 **   fts3PrefixCompress("abX", 3, "Xbcdef", 6)   // returns 0
135332 */
135333 static int fts3PrefixCompress(
135334   const char *zPrev,              /* Buffer containing previous term */
135335   int nPrev,                      /* Size of buffer zPrev in bytes */
135336   const char *zNext,              /* Buffer containing next term */
135337   int nNext                       /* Size of buffer zNext in bytes */
135338 ){
135339   int n;
135340   UNUSED_PARAMETER(nNext);
135341   for(n=0; n<nPrev && zPrev[n]==zNext[n]; n++);
135342   return n;
135343 }
135344 
135345 /*
135346 ** Add term zTerm to the SegmentNode. It is guaranteed that zTerm is larger
135347 ** (according to memcmp) than the previous term.
135348 */
135349 static int fts3NodeAddTerm(
135350   Fts3Table *p,                   /* Virtual table handle */
135351   SegmentNode **ppTree,           /* IN/OUT: SegmentNode handle */ 
135352   int isCopyTerm,                 /* True if zTerm/nTerm is transient */
135353   const char *zTerm,              /* Pointer to buffer containing term */
135354   int nTerm                       /* Size of term in bytes */
135355 ){
135356   SegmentNode *pTree = *ppTree;
135357   int rc;
135358   SegmentNode *pNew;
135359 
135360   /* First try to append the term to the current node. Return early if 
135361   ** this is possible.
135362   */
135363   if( pTree ){
135364     int nData = pTree->nData;     /* Current size of node in bytes */
135365     int nReq = nData;             /* Required space after adding zTerm */
135366     int nPrefix;                  /* Number of bytes of prefix compression */
135367     int nSuffix;                  /* Suffix length */
135368 
135369     nPrefix = fts3PrefixCompress(pTree->zTerm, pTree->nTerm, zTerm, nTerm);
135370     nSuffix = nTerm-nPrefix;
135371 
135372     nReq += sqlite3Fts3VarintLen(nPrefix)+sqlite3Fts3VarintLen(nSuffix)+nSuffix;
135373     if( nReq<=p->nNodeSize || !pTree->zTerm ){
135374 
135375       if( nReq>p->nNodeSize ){
135376         /* An unusual case: this is the first term to be added to the node
135377         ** and the static node buffer (p->nNodeSize bytes) is not large
135378         ** enough. Use a separately malloced buffer instead This wastes
135379         ** p->nNodeSize bytes, but since this scenario only comes about when
135380         ** the database contain two terms that share a prefix of almost 2KB, 
135381         ** this is not expected to be a serious problem. 
135382         */
135383         assert( pTree->aData==(char *)&pTree[1] );
135384         pTree->aData = (char *)sqlite3_malloc(nReq);
135385         if( !pTree->aData ){
135386           return SQLITE_NOMEM;
135387         }
135388       }
135389 
135390       if( pTree->zTerm ){
135391         /* There is no prefix-length field for first term in a node */
135392         nData += sqlite3Fts3PutVarint(&pTree->aData[nData], nPrefix);
135393       }
135394 
135395       nData += sqlite3Fts3PutVarint(&pTree->aData[nData], nSuffix);
135396       memcpy(&pTree->aData[nData], &zTerm[nPrefix], nSuffix);
135397       pTree->nData = nData + nSuffix;
135398       pTree->nEntry++;
135399 
135400       if( isCopyTerm ){
135401         if( pTree->nMalloc<nTerm ){
135402           char *zNew = sqlite3_realloc(pTree->zMalloc, nTerm*2);
135403           if( !zNew ){
135404             return SQLITE_NOMEM;
135405           }
135406           pTree->nMalloc = nTerm*2;
135407           pTree->zMalloc = zNew;
135408         }
135409         pTree->zTerm = pTree->zMalloc;
135410         memcpy(pTree->zTerm, zTerm, nTerm);
135411         pTree->nTerm = nTerm;
135412       }else{
135413         pTree->zTerm = (char *)zTerm;
135414         pTree->nTerm = nTerm;
135415       }
135416       return SQLITE_OK;
135417     }
135418   }
135419 
135420   /* If control flows to here, it was not possible to append zTerm to the
135421   ** current node. Create a new node (a right-sibling of the current node).
135422   ** If this is the first node in the tree, the term is added to it.
135423   **
135424   ** Otherwise, the term is not added to the new node, it is left empty for
135425   ** now. Instead, the term is inserted into the parent of pTree. If pTree 
135426   ** has no parent, one is created here.
135427   */
135428   pNew = (SegmentNode *)sqlite3_malloc(sizeof(SegmentNode) + p->nNodeSize);
135429   if( !pNew ){
135430     return SQLITE_NOMEM;
135431   }
135432   memset(pNew, 0, sizeof(SegmentNode));
135433   pNew->nData = 1 + FTS3_VARINT_MAX;
135434   pNew->aData = (char *)&pNew[1];
135435 
135436   if( pTree ){
135437     SegmentNode *pParent = pTree->pParent;
135438     rc = fts3NodeAddTerm(p, &pParent, isCopyTerm, zTerm, nTerm);
135439     if( pTree->pParent==0 ){
135440       pTree->pParent = pParent;
135441     }
135442     pTree->pRight = pNew;
135443     pNew->pLeftmost = pTree->pLeftmost;
135444     pNew->pParent = pParent;
135445     pNew->zMalloc = pTree->zMalloc;
135446     pNew->nMalloc = pTree->nMalloc;
135447     pTree->zMalloc = 0;
135448   }else{
135449     pNew->pLeftmost = pNew;
135450     rc = fts3NodeAddTerm(p, &pNew, isCopyTerm, zTerm, nTerm); 
135451   }
135452 
135453   *ppTree = pNew;
135454   return rc;
135455 }
135456 
135457 /*
135458 ** Helper function for fts3NodeWrite().
135459 */
135460 static int fts3TreeFinishNode(
135461   SegmentNode *pTree, 
135462   int iHeight, 
135463   sqlite3_int64 iLeftChild
135464 ){
135465   int nStart;
135466   assert( iHeight>=1 && iHeight<128 );
135467   nStart = FTS3_VARINT_MAX - sqlite3Fts3VarintLen(iLeftChild);
135468   pTree->aData[nStart] = (char)iHeight;
135469   sqlite3Fts3PutVarint(&pTree->aData[nStart+1], iLeftChild);
135470   return nStart;
135471 }
135472 
135473 /*
135474 ** Write the buffer for the segment node pTree and all of its peers to the
135475 ** database. Then call this function recursively to write the parent of 
135476 ** pTree and its peers to the database. 
135477 **
135478 ** Except, if pTree is a root node, do not write it to the database. Instead,
135479 ** set output variables *paRoot and *pnRoot to contain the root node.
135480 **
135481 ** If successful, SQLITE_OK is returned and output variable *piLast is
135482 ** set to the largest blockid written to the database (or zero if no
135483 ** blocks were written to the db). Otherwise, an SQLite error code is 
135484 ** returned.
135485 */
135486 static int fts3NodeWrite(
135487   Fts3Table *p,                   /* Virtual table handle */
135488   SegmentNode *pTree,             /* SegmentNode handle */
135489   int iHeight,                    /* Height of this node in tree */
135490   sqlite3_int64 iLeaf,            /* Block id of first leaf node */
135491   sqlite3_int64 iFree,            /* Block id of next free slot in %_segments */
135492   sqlite3_int64 *piLast,          /* OUT: Block id of last entry written */
135493   char **paRoot,                  /* OUT: Data for root node */
135494   int *pnRoot                     /* OUT: Size of root node in bytes */
135495 ){
135496   int rc = SQLITE_OK;
135497 
135498   if( !pTree->pParent ){
135499     /* Root node of the tree. */
135500     int nStart = fts3TreeFinishNode(pTree, iHeight, iLeaf);
135501     *piLast = iFree-1;
135502     *pnRoot = pTree->nData - nStart;
135503     *paRoot = &pTree->aData[nStart];
135504   }else{
135505     SegmentNode *pIter;
135506     sqlite3_int64 iNextFree = iFree;
135507     sqlite3_int64 iNextLeaf = iLeaf;
135508     for(pIter=pTree->pLeftmost; pIter && rc==SQLITE_OK; pIter=pIter->pRight){
135509       int nStart = fts3TreeFinishNode(pIter, iHeight, iNextLeaf);
135510       int nWrite = pIter->nData - nStart;
135511   
135512       rc = fts3WriteSegment(p, iNextFree, &pIter->aData[nStart], nWrite);
135513       iNextFree++;
135514       iNextLeaf += (pIter->nEntry+1);
135515     }
135516     if( rc==SQLITE_OK ){
135517       assert( iNextLeaf==iFree );
135518       rc = fts3NodeWrite(
135519           p, pTree->pParent, iHeight+1, iFree, iNextFree, piLast, paRoot, pnRoot
135520       );
135521     }
135522   }
135523 
135524   return rc;
135525 }
135526 
135527 /*
135528 ** Free all memory allocations associated with the tree pTree.
135529 */
135530 static void fts3NodeFree(SegmentNode *pTree){
135531   if( pTree ){
135532     SegmentNode *p = pTree->pLeftmost;
135533     fts3NodeFree(p->pParent);
135534     while( p ){
135535       SegmentNode *pRight = p->pRight;
135536       if( p->aData!=(char *)&p[1] ){
135537         sqlite3_free(p->aData);
135538       }
135539       assert( pRight==0 || p->zMalloc==0 );
135540       sqlite3_free(p->zMalloc);
135541       sqlite3_free(p);
135542       p = pRight;
135543     }
135544   }
135545 }
135546 
135547 /*
135548 ** Add a term to the segment being constructed by the SegmentWriter object
135549 ** *ppWriter. When adding the first term to a segment, *ppWriter should
135550 ** be passed NULL. This function will allocate a new SegmentWriter object
135551 ** and return it via the input/output variable *ppWriter in this case.
135552 **
135553 ** If successful, SQLITE_OK is returned. Otherwise, an SQLite error code.
135554 */
135555 static int fts3SegWriterAdd(
135556   Fts3Table *p,                   /* Virtual table handle */
135557   SegmentWriter **ppWriter,       /* IN/OUT: SegmentWriter handle */ 
135558   int isCopyTerm,                 /* True if buffer zTerm must be copied */
135559   const char *zTerm,              /* Pointer to buffer containing term */
135560   int nTerm,                      /* Size of term in bytes */
135561   const char *aDoclist,           /* Pointer to buffer containing doclist */
135562   int nDoclist                    /* Size of doclist in bytes */
135563 ){
135564   int nPrefix;                    /* Size of term prefix in bytes */
135565   int nSuffix;                    /* Size of term suffix in bytes */
135566   int nReq;                       /* Number of bytes required on leaf page */
135567   int nData;
135568   SegmentWriter *pWriter = *ppWriter;
135569 
135570   if( !pWriter ){
135571     int rc;
135572     sqlite3_stmt *pStmt;
135573 
135574     /* Allocate the SegmentWriter structure */
135575     pWriter = (SegmentWriter *)sqlite3_malloc(sizeof(SegmentWriter));
135576     if( !pWriter ) return SQLITE_NOMEM;
135577     memset(pWriter, 0, sizeof(SegmentWriter));
135578     *ppWriter = pWriter;
135579 
135580     /* Allocate a buffer in which to accumulate data */
135581     pWriter->aData = (char *)sqlite3_malloc(p->nNodeSize);
135582     if( !pWriter->aData ) return SQLITE_NOMEM;
135583     pWriter->nSize = p->nNodeSize;
135584 
135585     /* Find the next free blockid in the %_segments table */
135586     rc = fts3SqlStmt(p, SQL_NEXT_SEGMENTS_ID, &pStmt, 0);
135587     if( rc!=SQLITE_OK ) return rc;
135588     if( SQLITE_ROW==sqlite3_step(pStmt) ){
135589       pWriter->iFree = sqlite3_column_int64(pStmt, 0);
135590       pWriter->iFirst = pWriter->iFree;
135591     }
135592     rc = sqlite3_reset(pStmt);
135593     if( rc!=SQLITE_OK ) return rc;
135594   }
135595   nData = pWriter->nData;
135596 
135597   nPrefix = fts3PrefixCompress(pWriter->zTerm, pWriter->nTerm, zTerm, nTerm);
135598   nSuffix = nTerm-nPrefix;
135599 
135600   /* Figure out how many bytes are required by this new entry */
135601   nReq = sqlite3Fts3VarintLen(nPrefix) +    /* varint containing prefix size */
135602     sqlite3Fts3VarintLen(nSuffix) +         /* varint containing suffix size */
135603     nSuffix +                               /* Term suffix */
135604     sqlite3Fts3VarintLen(nDoclist) +        /* Size of doclist */
135605     nDoclist;                               /* Doclist data */
135606 
135607   if( nData>0 && nData+nReq>p->nNodeSize ){
135608     int rc;
135609 
135610     /* The current leaf node is full. Write it out to the database. */
135611     rc = fts3WriteSegment(p, pWriter->iFree++, pWriter->aData, nData);
135612     if( rc!=SQLITE_OK ) return rc;
135613     p->nLeafAdd++;
135614 
135615     /* Add the current term to the interior node tree. The term added to
135616     ** the interior tree must:
135617     **
135618     **   a) be greater than the largest term on the leaf node just written
135619     **      to the database (still available in pWriter->zTerm), and
135620     **
135621     **   b) be less than or equal to the term about to be added to the new
135622     **      leaf node (zTerm/nTerm).
135623     **
135624     ** In other words, it must be the prefix of zTerm 1 byte longer than
135625     ** the common prefix (if any) of zTerm and pWriter->zTerm.
135626     */
135627     assert( nPrefix<nTerm );
135628     rc = fts3NodeAddTerm(p, &pWriter->pTree, isCopyTerm, zTerm, nPrefix+1);
135629     if( rc!=SQLITE_OK ) return rc;
135630 
135631     nData = 0;
135632     pWriter->nTerm = 0;
135633 
135634     nPrefix = 0;
135635     nSuffix = nTerm;
135636     nReq = 1 +                              /* varint containing prefix size */
135637       sqlite3Fts3VarintLen(nTerm) +         /* varint containing suffix size */
135638       nTerm +                               /* Term suffix */
135639       sqlite3Fts3VarintLen(nDoclist) +      /* Size of doclist */
135640       nDoclist;                             /* Doclist data */
135641   }
135642 
135643   /* If the buffer currently allocated is too small for this entry, realloc
135644   ** the buffer to make it large enough.
135645   */
135646   if( nReq>pWriter->nSize ){
135647     char *aNew = sqlite3_realloc(pWriter->aData, nReq);
135648     if( !aNew ) return SQLITE_NOMEM;
135649     pWriter->aData = aNew;
135650     pWriter->nSize = nReq;
135651   }
135652   assert( nData+nReq<=pWriter->nSize );
135653 
135654   /* Append the prefix-compressed term and doclist to the buffer. */
135655   nData += sqlite3Fts3PutVarint(&pWriter->aData[nData], nPrefix);
135656   nData += sqlite3Fts3PutVarint(&pWriter->aData[nData], nSuffix);
135657   memcpy(&pWriter->aData[nData], &zTerm[nPrefix], nSuffix);
135658   nData += nSuffix;
135659   nData += sqlite3Fts3PutVarint(&pWriter->aData[nData], nDoclist);
135660   memcpy(&pWriter->aData[nData], aDoclist, nDoclist);
135661   pWriter->nData = nData + nDoclist;
135662 
135663   /* Save the current term so that it can be used to prefix-compress the next.
135664   ** If the isCopyTerm parameter is true, then the buffer pointed to by
135665   ** zTerm is transient, so take a copy of the term data. Otherwise, just
135666   ** store a copy of the pointer.
135667   */
135668   if( isCopyTerm ){
135669     if( nTerm>pWriter->nMalloc ){
135670       char *zNew = sqlite3_realloc(pWriter->zMalloc, nTerm*2);
135671       if( !zNew ){
135672         return SQLITE_NOMEM;
135673       }
135674       pWriter->nMalloc = nTerm*2;
135675       pWriter->zMalloc = zNew;
135676       pWriter->zTerm = zNew;
135677     }
135678     assert( pWriter->zTerm==pWriter->zMalloc );
135679     memcpy(pWriter->zTerm, zTerm, nTerm);
135680   }else{
135681     pWriter->zTerm = (char *)zTerm;
135682   }
135683   pWriter->nTerm = nTerm;
135684 
135685   return SQLITE_OK;
135686 }
135687 
135688 /*
135689 ** Flush all data associated with the SegmentWriter object pWriter to the
135690 ** database. This function must be called after all terms have been added
135691 ** to the segment using fts3SegWriterAdd(). If successful, SQLITE_OK is
135692 ** returned. Otherwise, an SQLite error code.
135693 */
135694 static int fts3SegWriterFlush(
135695   Fts3Table *p,                   /* Virtual table handle */
135696   SegmentWriter *pWriter,         /* SegmentWriter to flush to the db */
135697   sqlite3_int64 iLevel,           /* Value for 'level' column of %_segdir */
135698   int iIdx                        /* Value for 'idx' column of %_segdir */
135699 ){
135700   int rc;                         /* Return code */
135701   if( pWriter->pTree ){
135702     sqlite3_int64 iLast = 0;      /* Largest block id written to database */
135703     sqlite3_int64 iLastLeaf;      /* Largest leaf block id written to db */
135704     char *zRoot = NULL;           /* Pointer to buffer containing root node */
135705     int nRoot = 0;                /* Size of buffer zRoot */
135706 
135707     iLastLeaf = pWriter->iFree;
135708     rc = fts3WriteSegment(p, pWriter->iFree++, pWriter->aData, pWriter->nData);
135709     if( rc==SQLITE_OK ){
135710       rc = fts3NodeWrite(p, pWriter->pTree, 1,
135711           pWriter->iFirst, pWriter->iFree, &iLast, &zRoot, &nRoot);
135712     }
135713     if( rc==SQLITE_OK ){
135714       rc = fts3WriteSegdir(
135715           p, iLevel, iIdx, pWriter->iFirst, iLastLeaf, iLast, zRoot, nRoot);
135716     }
135717   }else{
135718     /* The entire tree fits on the root node. Write it to the segdir table. */
135719     rc = fts3WriteSegdir(
135720         p, iLevel, iIdx, 0, 0, 0, pWriter->aData, pWriter->nData);
135721   }
135722   p->nLeafAdd++;
135723   return rc;
135724 }
135725 
135726 /*
135727 ** Release all memory held by the SegmentWriter object passed as the 
135728 ** first argument.
135729 */
135730 static void fts3SegWriterFree(SegmentWriter *pWriter){
135731   if( pWriter ){
135732     sqlite3_free(pWriter->aData);
135733     sqlite3_free(pWriter->zMalloc);
135734     fts3NodeFree(pWriter->pTree);
135735     sqlite3_free(pWriter);
135736   }
135737 }
135738 
135739 /*
135740 ** The first value in the apVal[] array is assumed to contain an integer.
135741 ** This function tests if there exist any documents with docid values that
135742 ** are different from that integer. i.e. if deleting the document with docid
135743 ** pRowid would mean the FTS3 table were empty.
135744 **
135745 ** If successful, *pisEmpty is set to true if the table is empty except for
135746 ** document pRowid, or false otherwise, and SQLITE_OK is returned. If an
135747 ** error occurs, an SQLite error code is returned.
135748 */
135749 static int fts3IsEmpty(Fts3Table *p, sqlite3_value *pRowid, int *pisEmpty){
135750   sqlite3_stmt *pStmt;
135751   int rc;
135752   if( p->zContentTbl ){
135753     /* If using the content=xxx option, assume the table is never empty */
135754     *pisEmpty = 0;
135755     rc = SQLITE_OK;
135756   }else{
135757     rc = fts3SqlStmt(p, SQL_IS_EMPTY, &pStmt, &pRowid);
135758     if( rc==SQLITE_OK ){
135759       if( SQLITE_ROW==sqlite3_step(pStmt) ){
135760         *pisEmpty = sqlite3_column_int(pStmt, 0);
135761       }
135762       rc = sqlite3_reset(pStmt);
135763     }
135764   }
135765   return rc;
135766 }
135767 
135768 /*
135769 ** Set *pnMax to the largest segment level in the database for the index
135770 ** iIndex.
135771 **
135772 ** Segment levels are stored in the 'level' column of the %_segdir table.
135773 **
135774 ** Return SQLITE_OK if successful, or an SQLite error code if not.
135775 */
135776 static int fts3SegmentMaxLevel(
135777   Fts3Table *p, 
135778   int iLangid,
135779   int iIndex, 
135780   sqlite3_int64 *pnMax
135781 ){
135782   sqlite3_stmt *pStmt;
135783   int rc;
135784   assert( iIndex>=0 && iIndex<p->nIndex );
135785 
135786   /* Set pStmt to the compiled version of:
135787   **
135788   **   SELECT max(level) FROM %Q.'%q_segdir' WHERE level BETWEEN ? AND ?
135789   **
135790   ** (1024 is actually the value of macro FTS3_SEGDIR_PREFIXLEVEL_STR).
135791   */
135792   rc = fts3SqlStmt(p, SQL_SELECT_SEGDIR_MAX_LEVEL, &pStmt, 0);
135793   if( rc!=SQLITE_OK ) return rc;
135794   sqlite3_bind_int64(pStmt, 1, getAbsoluteLevel(p, iLangid, iIndex, 0));
135795   sqlite3_bind_int64(pStmt, 2, 
135796       getAbsoluteLevel(p, iLangid, iIndex, FTS3_SEGDIR_MAXLEVEL-1)
135797   );
135798   if( SQLITE_ROW==sqlite3_step(pStmt) ){
135799     *pnMax = sqlite3_column_int64(pStmt, 0);
135800   }
135801   return sqlite3_reset(pStmt);
135802 }
135803 
135804 /*
135805 ** Delete all entries in the %_segments table associated with the segment
135806 ** opened with seg-reader pSeg. This function does not affect the contents
135807 ** of the %_segdir table.
135808 */
135809 static int fts3DeleteSegment(
135810   Fts3Table *p,                   /* FTS table handle */
135811   Fts3SegReader *pSeg             /* Segment to delete */
135812 ){
135813   int rc = SQLITE_OK;             /* Return code */
135814   if( pSeg->iStartBlock ){
135815     sqlite3_stmt *pDelete;        /* SQL statement to delete rows */
135816     rc = fts3SqlStmt(p, SQL_DELETE_SEGMENTS_RANGE, &pDelete, 0);
135817     if( rc==SQLITE_OK ){
135818       sqlite3_bind_int64(pDelete, 1, pSeg->iStartBlock);
135819       sqlite3_bind_int64(pDelete, 2, pSeg->iEndBlock);
135820       sqlite3_step(pDelete);
135821       rc = sqlite3_reset(pDelete);
135822     }
135823   }
135824   return rc;
135825 }
135826 
135827 /*
135828 ** This function is used after merging multiple segments into a single large
135829 ** segment to delete the old, now redundant, segment b-trees. Specifically,
135830 ** it:
135831 ** 
135832 **   1) Deletes all %_segments entries for the segments associated with 
135833 **      each of the SegReader objects in the array passed as the third 
135834 **      argument, and
135835 **
135836 **   2) deletes all %_segdir entries with level iLevel, or all %_segdir
135837 **      entries regardless of level if (iLevel<0).
135838 **
135839 ** SQLITE_OK is returned if successful, otherwise an SQLite error code.
135840 */
135841 static int fts3DeleteSegdir(
135842   Fts3Table *p,                   /* Virtual table handle */
135843   int iLangid,                    /* Language id */
135844   int iIndex,                     /* Index for p->aIndex */
135845   int iLevel,                     /* Level of %_segdir entries to delete */
135846   Fts3SegReader **apSegment,      /* Array of SegReader objects */
135847   int nReader                     /* Size of array apSegment */
135848 ){
135849   int rc = SQLITE_OK;             /* Return Code */
135850   int i;                          /* Iterator variable */
135851   sqlite3_stmt *pDelete = 0;      /* SQL statement to delete rows */
135852 
135853   for(i=0; rc==SQLITE_OK && i<nReader; i++){
135854     rc = fts3DeleteSegment(p, apSegment[i]);
135855   }
135856   if( rc!=SQLITE_OK ){
135857     return rc;
135858   }
135859 
135860   assert( iLevel>=0 || iLevel==FTS3_SEGCURSOR_ALL );
135861   if( iLevel==FTS3_SEGCURSOR_ALL ){
135862     rc = fts3SqlStmt(p, SQL_DELETE_SEGDIR_RANGE, &pDelete, 0);
135863     if( rc==SQLITE_OK ){
135864       sqlite3_bind_int64(pDelete, 1, getAbsoluteLevel(p, iLangid, iIndex, 0));
135865       sqlite3_bind_int64(pDelete, 2, 
135866           getAbsoluteLevel(p, iLangid, iIndex, FTS3_SEGDIR_MAXLEVEL-1)
135867       );
135868     }
135869   }else{
135870     rc = fts3SqlStmt(p, SQL_DELETE_SEGDIR_LEVEL, &pDelete, 0);
135871     if( rc==SQLITE_OK ){
135872       sqlite3_bind_int64(
135873           pDelete, 1, getAbsoluteLevel(p, iLangid, iIndex, iLevel)
135874       );
135875     }
135876   }
135877 
135878   if( rc==SQLITE_OK ){
135879     sqlite3_step(pDelete);
135880     rc = sqlite3_reset(pDelete);
135881   }
135882 
135883   return rc;
135884 }
135885 
135886 /*
135887 ** When this function is called, buffer *ppList (size *pnList bytes) contains 
135888 ** a position list that may (or may not) feature multiple columns. This
135889 ** function adjusts the pointer *ppList and the length *pnList so that they
135890 ** identify the subset of the position list that corresponds to column iCol.
135891 **
135892 ** If there are no entries in the input position list for column iCol, then
135893 ** *pnList is set to zero before returning.
135894 **
135895 ** If parameter bZero is non-zero, then any part of the input list following
135896 ** the end of the output list is zeroed before returning.
135897 */
135898 static void fts3ColumnFilter(
135899   int iCol,                       /* Column to filter on */
135900   int bZero,                      /* Zero out anything following *ppList */
135901   char **ppList,                  /* IN/OUT: Pointer to position list */
135902   int *pnList                     /* IN/OUT: Size of buffer *ppList in bytes */
135903 ){
135904   char *pList = *ppList;
135905   int nList = *pnList;
135906   char *pEnd = &pList[nList];
135907   int iCurrent = 0;
135908   char *p = pList;
135909 
135910   assert( iCol>=0 );
135911   while( 1 ){
135912     char c = 0;
135913     while( p<pEnd && (c | *p)&0xFE ) c = *p++ & 0x80;
135914   
135915     if( iCol==iCurrent ){
135916       nList = (int)(p - pList);
135917       break;
135918     }
135919 
135920     nList -= (int)(p - pList);
135921     pList = p;
135922     if( nList==0 ){
135923       break;
135924     }
135925     p = &pList[1];
135926     p += fts3GetVarint32(p, &iCurrent);
135927   }
135928 
135929   if( bZero && &pList[nList]!=pEnd ){
135930     memset(&pList[nList], 0, pEnd - &pList[nList]);
135931   }
135932   *ppList = pList;
135933   *pnList = nList;
135934 }
135935 
135936 /*
135937 ** Cache data in the Fts3MultiSegReader.aBuffer[] buffer (overwriting any
135938 ** existing data). Grow the buffer if required.
135939 **
135940 ** If successful, return SQLITE_OK. Otherwise, if an OOM error is encountered
135941 ** trying to resize the buffer, return SQLITE_NOMEM.
135942 */
135943 static int fts3MsrBufferData(
135944   Fts3MultiSegReader *pMsr,       /* Multi-segment-reader handle */
135945   char *pList,
135946   int nList
135947 ){
135948   if( nList>pMsr->nBuffer ){
135949     char *pNew;
135950     pMsr->nBuffer = nList*2;
135951     pNew = (char *)sqlite3_realloc(pMsr->aBuffer, pMsr->nBuffer);
135952     if( !pNew ) return SQLITE_NOMEM;
135953     pMsr->aBuffer = pNew;
135954   }
135955 
135956   memcpy(pMsr->aBuffer, pList, nList);
135957   return SQLITE_OK;
135958 }
135959 
135960 SQLITE_PRIVATE int sqlite3Fts3MsrIncrNext(
135961   Fts3Table *p,                   /* Virtual table handle */
135962   Fts3MultiSegReader *pMsr,       /* Multi-segment-reader handle */
135963   sqlite3_int64 *piDocid,         /* OUT: Docid value */
135964   char **paPoslist,               /* OUT: Pointer to position list */
135965   int *pnPoslist                  /* OUT: Size of position list in bytes */
135966 ){
135967   int nMerge = pMsr->nAdvance;
135968   Fts3SegReader **apSegment = pMsr->apSegment;
135969   int (*xCmp)(Fts3SegReader *, Fts3SegReader *) = (
135970     p->bDescIdx ? fts3SegReaderDoclistCmpRev : fts3SegReaderDoclistCmp
135971   );
135972 
135973   if( nMerge==0 ){
135974     *paPoslist = 0;
135975     return SQLITE_OK;
135976   }
135977 
135978   while( 1 ){
135979     Fts3SegReader *pSeg;
135980     pSeg = pMsr->apSegment[0];
135981 
135982     if( pSeg->pOffsetList==0 ){
135983       *paPoslist = 0;
135984       break;
135985     }else{
135986       int rc;
135987       char *pList;
135988       int nList;
135989       int j;
135990       sqlite3_int64 iDocid = apSegment[0]->iDocid;
135991 
135992       rc = fts3SegReaderNextDocid(p, apSegment[0], &pList, &nList);
135993       j = 1;
135994       while( rc==SQLITE_OK 
135995         && j<nMerge
135996         && apSegment[j]->pOffsetList
135997         && apSegment[j]->iDocid==iDocid
135998       ){
135999         rc = fts3SegReaderNextDocid(p, apSegment[j], 0, 0);
136000         j++;
136001       }
136002       if( rc!=SQLITE_OK ) return rc;
136003       fts3SegReaderSort(pMsr->apSegment, nMerge, j, xCmp);
136004 
136005       if( nList>0 && fts3SegReaderIsPending(apSegment[0]) ){
136006         rc = fts3MsrBufferData(pMsr, pList, nList+1);
136007         if( rc!=SQLITE_OK ) return rc;
136008         assert( (pMsr->aBuffer[nList] & 0xFE)==0x00 );
136009         pList = pMsr->aBuffer;
136010       }
136011 
136012       if( pMsr->iColFilter>=0 ){
136013         fts3ColumnFilter(pMsr->iColFilter, 1, &pList, &nList);
136014       }
136015 
136016       if( nList>0 ){
136017         *paPoslist = pList;
136018         *piDocid = iDocid;
136019         *pnPoslist = nList;
136020         break;
136021       }
136022     }
136023   }
136024 
136025   return SQLITE_OK;
136026 }
136027 
136028 static int fts3SegReaderStart(
136029   Fts3Table *p,                   /* Virtual table handle */
136030   Fts3MultiSegReader *pCsr,       /* Cursor object */
136031   const char *zTerm,              /* Term searched for (or NULL) */
136032   int nTerm                       /* Length of zTerm in bytes */
136033 ){
136034   int i;
136035   int nSeg = pCsr->nSegment;
136036 
136037   /* If the Fts3SegFilter defines a specific term (or term prefix) to search 
136038   ** for, then advance each segment iterator until it points to a term of
136039   ** equal or greater value than the specified term. This prevents many
136040   ** unnecessary merge/sort operations for the case where single segment
136041   ** b-tree leaf nodes contain more than one term.
136042   */
136043   for(i=0; pCsr->bRestart==0 && i<pCsr->nSegment; i++){
136044     int res = 0;
136045     Fts3SegReader *pSeg = pCsr->apSegment[i];
136046     do {
136047       int rc = fts3SegReaderNext(p, pSeg, 0);
136048       if( rc!=SQLITE_OK ) return rc;
136049     }while( zTerm && (res = fts3SegReaderTermCmp(pSeg, zTerm, nTerm))<0 );
136050 
136051     if( pSeg->bLookup && res!=0 ){
136052       fts3SegReaderSetEof(pSeg);
136053     }
136054   }
136055   fts3SegReaderSort(pCsr->apSegment, nSeg, nSeg, fts3SegReaderCmp);
136056 
136057   return SQLITE_OK;
136058 }
136059 
136060 SQLITE_PRIVATE int sqlite3Fts3SegReaderStart(
136061   Fts3Table *p,                   /* Virtual table handle */
136062   Fts3MultiSegReader *pCsr,       /* Cursor object */
136063   Fts3SegFilter *pFilter          /* Restrictions on range of iteration */
136064 ){
136065   pCsr->pFilter = pFilter;
136066   return fts3SegReaderStart(p, pCsr, pFilter->zTerm, pFilter->nTerm);
136067 }
136068 
136069 SQLITE_PRIVATE int sqlite3Fts3MsrIncrStart(
136070   Fts3Table *p,                   /* Virtual table handle */
136071   Fts3MultiSegReader *pCsr,       /* Cursor object */
136072   int iCol,                       /* Column to match on. */
136073   const char *zTerm,              /* Term to iterate through a doclist for */
136074   int nTerm                       /* Number of bytes in zTerm */
136075 ){
136076   int i;
136077   int rc;
136078   int nSegment = pCsr->nSegment;
136079   int (*xCmp)(Fts3SegReader *, Fts3SegReader *) = (
136080     p->bDescIdx ? fts3SegReaderDoclistCmpRev : fts3SegReaderDoclistCmp
136081   );
136082 
136083   assert( pCsr->pFilter==0 );
136084   assert( zTerm && nTerm>0 );
136085 
136086   /* Advance each segment iterator until it points to the term zTerm/nTerm. */
136087   rc = fts3SegReaderStart(p, pCsr, zTerm, nTerm);
136088   if( rc!=SQLITE_OK ) return rc;
136089 
136090   /* Determine how many of the segments actually point to zTerm/nTerm. */
136091   for(i=0; i<nSegment; i++){
136092     Fts3SegReader *pSeg = pCsr->apSegment[i];
136093     if( !pSeg->aNode || fts3SegReaderTermCmp(pSeg, zTerm, nTerm) ){
136094       break;
136095     }
136096   }
136097   pCsr->nAdvance = i;
136098 
136099   /* Advance each of the segments to point to the first docid. */
136100   for(i=0; i<pCsr->nAdvance; i++){
136101     rc = fts3SegReaderFirstDocid(p, pCsr->apSegment[i]);
136102     if( rc!=SQLITE_OK ) return rc;
136103   }
136104   fts3SegReaderSort(pCsr->apSegment, i, i, xCmp);
136105 
136106   assert( iCol<0 || iCol<p->nColumn );
136107   pCsr->iColFilter = iCol;
136108 
136109   return SQLITE_OK;
136110 }
136111 
136112 /*
136113 ** This function is called on a MultiSegReader that has been started using
136114 ** sqlite3Fts3MsrIncrStart(). One or more calls to MsrIncrNext() may also
136115 ** have been made. Calling this function puts the MultiSegReader in such
136116 ** a state that if the next two calls are:
136117 **
136118 **   sqlite3Fts3SegReaderStart()
136119 **   sqlite3Fts3SegReaderStep()
136120 **
136121 ** then the entire doclist for the term is available in 
136122 ** MultiSegReader.aDoclist/nDoclist.
136123 */
136124 SQLITE_PRIVATE int sqlite3Fts3MsrIncrRestart(Fts3MultiSegReader *pCsr){
136125   int i;                          /* Used to iterate through segment-readers */
136126 
136127   assert( pCsr->zTerm==0 );
136128   assert( pCsr->nTerm==0 );
136129   assert( pCsr->aDoclist==0 );
136130   assert( pCsr->nDoclist==0 );
136131 
136132   pCsr->nAdvance = 0;
136133   pCsr->bRestart = 1;
136134   for(i=0; i<pCsr->nSegment; i++){
136135     pCsr->apSegment[i]->pOffsetList = 0;
136136     pCsr->apSegment[i]->nOffsetList = 0;
136137     pCsr->apSegment[i]->iDocid = 0;
136138   }
136139 
136140   return SQLITE_OK;
136141 }
136142 
136143 
136144 SQLITE_PRIVATE int sqlite3Fts3SegReaderStep(
136145   Fts3Table *p,                   /* Virtual table handle */
136146   Fts3MultiSegReader *pCsr        /* Cursor object */
136147 ){
136148   int rc = SQLITE_OK;
136149 
136150   int isIgnoreEmpty =  (pCsr->pFilter->flags & FTS3_SEGMENT_IGNORE_EMPTY);
136151   int isRequirePos =   (pCsr->pFilter->flags & FTS3_SEGMENT_REQUIRE_POS);
136152   int isColFilter =    (pCsr->pFilter->flags & FTS3_SEGMENT_COLUMN_FILTER);
136153   int isPrefix =       (pCsr->pFilter->flags & FTS3_SEGMENT_PREFIX);
136154   int isScan =         (pCsr->pFilter->flags & FTS3_SEGMENT_SCAN);
136155   int isFirst =        (pCsr->pFilter->flags & FTS3_SEGMENT_FIRST);
136156 
136157   Fts3SegReader **apSegment = pCsr->apSegment;
136158   int nSegment = pCsr->nSegment;
136159   Fts3SegFilter *pFilter = pCsr->pFilter;
136160   int (*xCmp)(Fts3SegReader *, Fts3SegReader *) = (
136161     p->bDescIdx ? fts3SegReaderDoclistCmpRev : fts3SegReaderDoclistCmp
136162   );
136163 
136164   if( pCsr->nSegment==0 ) return SQLITE_OK;
136165 
136166   do {
136167     int nMerge;
136168     int i;
136169   
136170     /* Advance the first pCsr->nAdvance entries in the apSegment[] array
136171     ** forward. Then sort the list in order of current term again.  
136172     */
136173     for(i=0; i<pCsr->nAdvance; i++){
136174       Fts3SegReader *pSeg = apSegment[i];
136175       if( pSeg->bLookup ){
136176         fts3SegReaderSetEof(pSeg);
136177       }else{
136178         rc = fts3SegReaderNext(p, pSeg, 0);
136179       }
136180       if( rc!=SQLITE_OK ) return rc;
136181     }
136182     fts3SegReaderSort(apSegment, nSegment, pCsr->nAdvance, fts3SegReaderCmp);
136183     pCsr->nAdvance = 0;
136184 
136185     /* If all the seg-readers are at EOF, we're finished. return SQLITE_OK. */
136186     assert( rc==SQLITE_OK );
136187     if( apSegment[0]->aNode==0 ) break;
136188 
136189     pCsr->nTerm = apSegment[0]->nTerm;
136190     pCsr->zTerm = apSegment[0]->zTerm;
136191 
136192     /* If this is a prefix-search, and if the term that apSegment[0] points
136193     ** to does not share a suffix with pFilter->zTerm/nTerm, then all 
136194     ** required callbacks have been made. In this case exit early.
136195     **
136196     ** Similarly, if this is a search for an exact match, and the first term
136197     ** of segment apSegment[0] is not a match, exit early.
136198     */
136199     if( pFilter->zTerm && !isScan ){
136200       if( pCsr->nTerm<pFilter->nTerm 
136201        || (!isPrefix && pCsr->nTerm>pFilter->nTerm)
136202        || memcmp(pCsr->zTerm, pFilter->zTerm, pFilter->nTerm) 
136203       ){
136204         break;
136205       }
136206     }
136207 
136208     nMerge = 1;
136209     while( nMerge<nSegment 
136210         && apSegment[nMerge]->aNode
136211         && apSegment[nMerge]->nTerm==pCsr->nTerm 
136212         && 0==memcmp(pCsr->zTerm, apSegment[nMerge]->zTerm, pCsr->nTerm)
136213     ){
136214       nMerge++;
136215     }
136216 
136217     assert( isIgnoreEmpty || (isRequirePos && !isColFilter) );
136218     if( nMerge==1 
136219      && !isIgnoreEmpty 
136220      && !isFirst 
136221      && (p->bDescIdx==0 || fts3SegReaderIsPending(apSegment[0])==0)
136222     ){
136223       pCsr->nDoclist = apSegment[0]->nDoclist;
136224       if( fts3SegReaderIsPending(apSegment[0]) ){
136225         rc = fts3MsrBufferData(pCsr, apSegment[0]->aDoclist, pCsr->nDoclist);
136226         pCsr->aDoclist = pCsr->aBuffer;
136227       }else{
136228         pCsr->aDoclist = apSegment[0]->aDoclist;
136229       }
136230       if( rc==SQLITE_OK ) rc = SQLITE_ROW;
136231     }else{
136232       int nDoclist = 0;           /* Size of doclist */
136233       sqlite3_int64 iPrev = 0;    /* Previous docid stored in doclist */
136234 
136235       /* The current term of the first nMerge entries in the array
136236       ** of Fts3SegReader objects is the same. The doclists must be merged
136237       ** and a single term returned with the merged doclist.
136238       */
136239       for(i=0; i<nMerge; i++){
136240         fts3SegReaderFirstDocid(p, apSegment[i]);
136241       }
136242       fts3SegReaderSort(apSegment, nMerge, nMerge, xCmp);
136243       while( apSegment[0]->pOffsetList ){
136244         int j;                    /* Number of segments that share a docid */
136245         char *pList = 0;
136246         int nList = 0;
136247         int nByte;
136248         sqlite3_int64 iDocid = apSegment[0]->iDocid;
136249         fts3SegReaderNextDocid(p, apSegment[0], &pList, &nList);
136250         j = 1;
136251         while( j<nMerge
136252             && apSegment[j]->pOffsetList
136253             && apSegment[j]->iDocid==iDocid
136254         ){
136255           fts3SegReaderNextDocid(p, apSegment[j], 0, 0);
136256           j++;
136257         }
136258 
136259         if( isColFilter ){
136260           fts3ColumnFilter(pFilter->iCol, 0, &pList, &nList);
136261         }
136262 
136263         if( !isIgnoreEmpty || nList>0 ){
136264 
136265           /* Calculate the 'docid' delta value to write into the merged 
136266           ** doclist. */
136267           sqlite3_int64 iDelta;
136268           if( p->bDescIdx && nDoclist>0 ){
136269             iDelta = iPrev - iDocid;
136270           }else{
136271             iDelta = iDocid - iPrev;
136272           }
136273           assert( iDelta>0 || (nDoclist==0 && iDelta==iDocid) );
136274           assert( nDoclist>0 || iDelta==iDocid );
136275 
136276           nByte = sqlite3Fts3VarintLen(iDelta) + (isRequirePos?nList+1:0);
136277           if( nDoclist+nByte>pCsr->nBuffer ){
136278             char *aNew;
136279             pCsr->nBuffer = (nDoclist+nByte)*2;
136280             aNew = sqlite3_realloc(pCsr->aBuffer, pCsr->nBuffer);
136281             if( !aNew ){
136282               return SQLITE_NOMEM;
136283             }
136284             pCsr->aBuffer = aNew;
136285           }
136286 
136287           if( isFirst ){
136288             char *a = &pCsr->aBuffer[nDoclist];
136289             int nWrite;
136290            
136291             nWrite = sqlite3Fts3FirstFilter(iDelta, pList, nList, a);
136292             if( nWrite ){
136293               iPrev = iDocid;
136294               nDoclist += nWrite;
136295             }
136296           }else{
136297             nDoclist += sqlite3Fts3PutVarint(&pCsr->aBuffer[nDoclist], iDelta);
136298             iPrev = iDocid;
136299             if( isRequirePos ){
136300               memcpy(&pCsr->aBuffer[nDoclist], pList, nList);
136301               nDoclist += nList;
136302               pCsr->aBuffer[nDoclist++] = '\0';
136303             }
136304           }
136305         }
136306 
136307         fts3SegReaderSort(apSegment, nMerge, j, xCmp);
136308       }
136309       if( nDoclist>0 ){
136310         pCsr->aDoclist = pCsr->aBuffer;
136311         pCsr->nDoclist = nDoclist;
136312         rc = SQLITE_ROW;
136313       }
136314     }
136315     pCsr->nAdvance = nMerge;
136316   }while( rc==SQLITE_OK );
136317 
136318   return rc;
136319 }
136320 
136321 
136322 SQLITE_PRIVATE void sqlite3Fts3SegReaderFinish(
136323   Fts3MultiSegReader *pCsr       /* Cursor object */
136324 ){
136325   if( pCsr ){
136326     int i;
136327     for(i=0; i<pCsr->nSegment; i++){
136328       sqlite3Fts3SegReaderFree(pCsr->apSegment[i]);
136329     }
136330     sqlite3_free(pCsr->apSegment);
136331     sqlite3_free(pCsr->aBuffer);
136332 
136333     pCsr->nSegment = 0;
136334     pCsr->apSegment = 0;
136335     pCsr->aBuffer = 0;
136336   }
136337 }
136338 
136339 /*
136340 ** Merge all level iLevel segments in the database into a single 
136341 ** iLevel+1 segment. Or, if iLevel<0, merge all segments into a
136342 ** single segment with a level equal to the numerically largest level 
136343 ** currently present in the database.
136344 **
136345 ** If this function is called with iLevel<0, but there is only one
136346 ** segment in the database, SQLITE_DONE is returned immediately. 
136347 ** Otherwise, if successful, SQLITE_OK is returned. If an error occurs, 
136348 ** an SQLite error code is returned.
136349 */
136350 static int fts3SegmentMerge(
136351   Fts3Table *p, 
136352   int iLangid,                    /* Language id to merge */
136353   int iIndex,                     /* Index in p->aIndex[] to merge */
136354   int iLevel                      /* Level to merge */
136355 ){
136356   int rc;                         /* Return code */
136357   int iIdx = 0;                   /* Index of new segment */
136358   sqlite3_int64 iNewLevel = 0;    /* Level/index to create new segment at */
136359   SegmentWriter *pWriter = 0;     /* Used to write the new, merged, segment */
136360   Fts3SegFilter filter;           /* Segment term filter condition */
136361   Fts3MultiSegReader csr;         /* Cursor to iterate through level(s) */
136362   int bIgnoreEmpty = 0;           /* True to ignore empty segments */
136363 
136364   assert( iLevel==FTS3_SEGCURSOR_ALL
136365        || iLevel==FTS3_SEGCURSOR_PENDING
136366        || iLevel>=0
136367   );
136368   assert( iLevel<FTS3_SEGDIR_MAXLEVEL );
136369   assert( iIndex>=0 && iIndex<p->nIndex );
136370 
136371   rc = sqlite3Fts3SegReaderCursor(p, iLangid, iIndex, iLevel, 0, 0, 1, 0, &csr);
136372   if( rc!=SQLITE_OK || csr.nSegment==0 ) goto finished;
136373 
136374   if( iLevel==FTS3_SEGCURSOR_ALL ){
136375     /* This call is to merge all segments in the database to a single
136376     ** segment. The level of the new segment is equal to the numerically
136377     ** greatest segment level currently present in the database for this
136378     ** index. The idx of the new segment is always 0.  */
136379     if( csr.nSegment==1 ){
136380       rc = SQLITE_DONE;
136381       goto finished;
136382     }
136383     rc = fts3SegmentMaxLevel(p, iLangid, iIndex, &iNewLevel);
136384     bIgnoreEmpty = 1;
136385 
136386   }else if( iLevel==FTS3_SEGCURSOR_PENDING ){
136387     iNewLevel = getAbsoluteLevel(p, iLangid, iIndex, 0);
136388     rc = fts3AllocateSegdirIdx(p, iLangid, iIndex, 0, &iIdx);
136389   }else{
136390     /* This call is to merge all segments at level iLevel. find the next
136391     ** available segment index at level iLevel+1. The call to
136392     ** fts3AllocateSegdirIdx() will merge the segments at level iLevel+1 to 
136393     ** a single iLevel+2 segment if necessary.  */
136394     rc = fts3AllocateSegdirIdx(p, iLangid, iIndex, iLevel+1, &iIdx);
136395     iNewLevel = getAbsoluteLevel(p, iLangid, iIndex, iLevel+1);
136396   }
136397   if( rc!=SQLITE_OK ) goto finished;
136398   assert( csr.nSegment>0 );
136399   assert( iNewLevel>=getAbsoluteLevel(p, iLangid, iIndex, 0) );
136400   assert( iNewLevel<getAbsoluteLevel(p, iLangid, iIndex,FTS3_SEGDIR_MAXLEVEL) );
136401 
136402   memset(&filter, 0, sizeof(Fts3SegFilter));
136403   filter.flags = FTS3_SEGMENT_REQUIRE_POS;
136404   filter.flags |= (bIgnoreEmpty ? FTS3_SEGMENT_IGNORE_EMPTY : 0);
136405 
136406   rc = sqlite3Fts3SegReaderStart(p, &csr, &filter);
136407   while( SQLITE_OK==rc ){
136408     rc = sqlite3Fts3SegReaderStep(p, &csr);
136409     if( rc!=SQLITE_ROW ) break;
136410     rc = fts3SegWriterAdd(p, &pWriter, 1, 
136411         csr.zTerm, csr.nTerm, csr.aDoclist, csr.nDoclist);
136412   }
136413   if( rc!=SQLITE_OK ) goto finished;
136414   assert( pWriter );
136415 
136416   if( iLevel!=FTS3_SEGCURSOR_PENDING ){
136417     rc = fts3DeleteSegdir(
136418         p, iLangid, iIndex, iLevel, csr.apSegment, csr.nSegment
136419     );
136420     if( rc!=SQLITE_OK ) goto finished;
136421   }
136422   rc = fts3SegWriterFlush(p, pWriter, iNewLevel, iIdx);
136423 
136424  finished:
136425   fts3SegWriterFree(pWriter);
136426   sqlite3Fts3SegReaderFinish(&csr);
136427   return rc;
136428 }
136429 
136430 
136431 /* 
136432 ** Flush the contents of pendingTerms to level 0 segments.
136433 */
136434 SQLITE_PRIVATE int sqlite3Fts3PendingTermsFlush(Fts3Table *p){
136435   int rc = SQLITE_OK;
136436   int i;
136437         
136438   for(i=0; rc==SQLITE_OK && i<p->nIndex; i++){
136439     rc = fts3SegmentMerge(p, p->iPrevLangid, i, FTS3_SEGCURSOR_PENDING);
136440     if( rc==SQLITE_DONE ) rc = SQLITE_OK;
136441   }
136442   sqlite3Fts3PendingTermsClear(p);
136443 
136444   /* Determine the auto-incr-merge setting if unknown.  If enabled,
136445   ** estimate the number of leaf blocks of content to be written
136446   */
136447   if( rc==SQLITE_OK && p->bHasStat
136448    && p->bAutoincrmerge==0xff && p->nLeafAdd>0
136449   ){
136450     sqlite3_stmt *pStmt = 0;
136451     rc = fts3SqlStmt(p, SQL_SELECT_STAT, &pStmt, 0);
136452     if( rc==SQLITE_OK ){
136453       sqlite3_bind_int(pStmt, 1, FTS_STAT_AUTOINCRMERGE);
136454       rc = sqlite3_step(pStmt);
136455       p->bAutoincrmerge = (rc==SQLITE_ROW && sqlite3_column_int(pStmt, 0));
136456       rc = sqlite3_reset(pStmt);
136457     }
136458   }
136459   return rc;
136460 }
136461 
136462 /*
136463 ** Encode N integers as varints into a blob.
136464 */
136465 static void fts3EncodeIntArray(
136466   int N,             /* The number of integers to encode */
136467   u32 *a,            /* The integer values */
136468   char *zBuf,        /* Write the BLOB here */
136469   int *pNBuf         /* Write number of bytes if zBuf[] used here */
136470 ){
136471   int i, j;
136472   for(i=j=0; i<N; i++){
136473     j += sqlite3Fts3PutVarint(&zBuf[j], (sqlite3_int64)a[i]);
136474   }
136475   *pNBuf = j;
136476 }
136477 
136478 /*
136479 ** Decode a blob of varints into N integers
136480 */
136481 static void fts3DecodeIntArray(
136482   int N,             /* The number of integers to decode */
136483   u32 *a,            /* Write the integer values */
136484   const char *zBuf,  /* The BLOB containing the varints */
136485   int nBuf           /* size of the BLOB */
136486 ){
136487   int i, j;
136488   UNUSED_PARAMETER(nBuf);
136489   for(i=j=0; i<N; i++){
136490     sqlite3_int64 x;
136491     j += sqlite3Fts3GetVarint(&zBuf[j], &x);
136492     assert(j<=nBuf);
136493     a[i] = (u32)(x & 0xffffffff);
136494   }
136495 }
136496 
136497 /*
136498 ** Insert the sizes (in tokens) for each column of the document
136499 ** with docid equal to p->iPrevDocid.  The sizes are encoded as
136500 ** a blob of varints.
136501 */
136502 static void fts3InsertDocsize(
136503   int *pRC,                       /* Result code */
136504   Fts3Table *p,                   /* Table into which to insert */
136505   u32 *aSz                        /* Sizes of each column, in tokens */
136506 ){
136507   char *pBlob;             /* The BLOB encoding of the document size */
136508   int nBlob;               /* Number of bytes in the BLOB */
136509   sqlite3_stmt *pStmt;     /* Statement used to insert the encoding */
136510   int rc;                  /* Result code from subfunctions */
136511 
136512   if( *pRC ) return;
136513   pBlob = sqlite3_malloc( 10*p->nColumn );
136514   if( pBlob==0 ){
136515     *pRC = SQLITE_NOMEM;
136516     return;
136517   }
136518   fts3EncodeIntArray(p->nColumn, aSz, pBlob, &nBlob);
136519   rc = fts3SqlStmt(p, SQL_REPLACE_DOCSIZE, &pStmt, 0);
136520   if( rc ){
136521     sqlite3_free(pBlob);
136522     *pRC = rc;
136523     return;
136524   }
136525   sqlite3_bind_int64(pStmt, 1, p->iPrevDocid);
136526   sqlite3_bind_blob(pStmt, 2, pBlob, nBlob, sqlite3_free);
136527   sqlite3_step(pStmt);
136528   *pRC = sqlite3_reset(pStmt);
136529 }
136530 
136531 /*
136532 ** Record 0 of the %_stat table contains a blob consisting of N varints,
136533 ** where N is the number of user defined columns in the fts3 table plus
136534 ** two. If nCol is the number of user defined columns, then values of the 
136535 ** varints are set as follows:
136536 **
136537 **   Varint 0:       Total number of rows in the table.
136538 **
136539 **   Varint 1..nCol: For each column, the total number of tokens stored in
136540 **                   the column for all rows of the table.
136541 **
136542 **   Varint 1+nCol:  The total size, in bytes, of all text values in all
136543 **                   columns of all rows of the table.
136544 **
136545 */
136546 static void fts3UpdateDocTotals(
136547   int *pRC,                       /* The result code */
136548   Fts3Table *p,                   /* Table being updated */
136549   u32 *aSzIns,                    /* Size increases */
136550   u32 *aSzDel,                    /* Size decreases */
136551   int nChng                       /* Change in the number of documents */
136552 ){
136553   char *pBlob;             /* Storage for BLOB written into %_stat */
136554   int nBlob;               /* Size of BLOB written into %_stat */
136555   u32 *a;                  /* Array of integers that becomes the BLOB */
136556   sqlite3_stmt *pStmt;     /* Statement for reading and writing */
136557   int i;                   /* Loop counter */
136558   int rc;                  /* Result code from subfunctions */
136559 
136560   const int nStat = p->nColumn+2;
136561 
136562   if( *pRC ) return;
136563   a = sqlite3_malloc( (sizeof(u32)+10)*nStat );
136564   if( a==0 ){
136565     *pRC = SQLITE_NOMEM;
136566     return;
136567   }
136568   pBlob = (char*)&a[nStat];
136569   rc = fts3SqlStmt(p, SQL_SELECT_STAT, &pStmt, 0);
136570   if( rc ){
136571     sqlite3_free(a);
136572     *pRC = rc;
136573     return;
136574   }
136575   sqlite3_bind_int(pStmt, 1, FTS_STAT_DOCTOTAL);
136576   if( sqlite3_step(pStmt)==SQLITE_ROW ){
136577     fts3DecodeIntArray(nStat, a,
136578          sqlite3_column_blob(pStmt, 0),
136579          sqlite3_column_bytes(pStmt, 0));
136580   }else{
136581     memset(a, 0, sizeof(u32)*(nStat) );
136582   }
136583   rc = sqlite3_reset(pStmt);
136584   if( rc!=SQLITE_OK ){
136585     sqlite3_free(a);
136586     *pRC = rc;
136587     return;
136588   }
136589   if( nChng<0 && a[0]<(u32)(-nChng) ){
136590     a[0] = 0;
136591   }else{
136592     a[0] += nChng;
136593   }
136594   for(i=0; i<p->nColumn+1; i++){
136595     u32 x = a[i+1];
136596     if( x+aSzIns[i] < aSzDel[i] ){
136597       x = 0;
136598     }else{
136599       x = x + aSzIns[i] - aSzDel[i];
136600     }
136601     a[i+1] = x;
136602   }
136603   fts3EncodeIntArray(nStat, a, pBlob, &nBlob);
136604   rc = fts3SqlStmt(p, SQL_REPLACE_STAT, &pStmt, 0);
136605   if( rc ){
136606     sqlite3_free(a);
136607     *pRC = rc;
136608     return;
136609   }
136610   sqlite3_bind_int(pStmt, 1, FTS_STAT_DOCTOTAL);
136611   sqlite3_bind_blob(pStmt, 2, pBlob, nBlob, SQLITE_STATIC);
136612   sqlite3_step(pStmt);
136613   *pRC = sqlite3_reset(pStmt);
136614   sqlite3_free(a);
136615 }
136616 
136617 /*
136618 ** Merge the entire database so that there is one segment for each 
136619 ** iIndex/iLangid combination.
136620 */
136621 static int fts3DoOptimize(Fts3Table *p, int bReturnDone){
136622   int bSeenDone = 0;
136623   int rc;
136624   sqlite3_stmt *pAllLangid = 0;
136625 
136626   rc = fts3SqlStmt(p, SQL_SELECT_ALL_LANGID, &pAllLangid, 0);
136627   if( rc==SQLITE_OK ){
136628     int rc2;
136629     sqlite3_bind_int(pAllLangid, 1, p->nIndex);
136630     while( sqlite3_step(pAllLangid)==SQLITE_ROW ){
136631       int i;
136632       int iLangid = sqlite3_column_int(pAllLangid, 0);
136633       for(i=0; rc==SQLITE_OK && i<p->nIndex; i++){
136634         rc = fts3SegmentMerge(p, iLangid, i, FTS3_SEGCURSOR_ALL);
136635         if( rc==SQLITE_DONE ){
136636           bSeenDone = 1;
136637           rc = SQLITE_OK;
136638         }
136639       }
136640     }
136641     rc2 = sqlite3_reset(pAllLangid);
136642     if( rc==SQLITE_OK ) rc = rc2;
136643   }
136644 
136645   sqlite3Fts3SegmentsClose(p);
136646   sqlite3Fts3PendingTermsClear(p);
136647 
136648   return (rc==SQLITE_OK && bReturnDone && bSeenDone) ? SQLITE_DONE : rc;
136649 }
136650 
136651 /*
136652 ** This function is called when the user executes the following statement:
136653 **
136654 **     INSERT INTO <tbl>(<tbl>) VALUES('rebuild');
136655 **
136656 ** The entire FTS index is discarded and rebuilt. If the table is one 
136657 ** created using the content=xxx option, then the new index is based on
136658 ** the current contents of the xxx table. Otherwise, it is rebuilt based
136659 ** on the contents of the %_content table.
136660 */
136661 static int fts3DoRebuild(Fts3Table *p){
136662   int rc;                         /* Return Code */
136663 
136664   rc = fts3DeleteAll(p, 0);
136665   if( rc==SQLITE_OK ){
136666     u32 *aSz = 0;
136667     u32 *aSzIns = 0;
136668     u32 *aSzDel = 0;
136669     sqlite3_stmt *pStmt = 0;
136670     int nEntry = 0;
136671 
136672     /* Compose and prepare an SQL statement to loop through the content table */
136673     char *zSql = sqlite3_mprintf("SELECT %s" , p->zReadExprlist);
136674     if( !zSql ){
136675       rc = SQLITE_NOMEM;
136676     }else{
136677       rc = sqlite3_prepare_v2(p->db, zSql, -1, &pStmt, 0);
136678       sqlite3_free(zSql);
136679     }
136680 
136681     if( rc==SQLITE_OK ){
136682       int nByte = sizeof(u32) * (p->nColumn+1)*3;
136683       aSz = (u32 *)sqlite3_malloc(nByte);
136684       if( aSz==0 ){
136685         rc = SQLITE_NOMEM;
136686       }else{
136687         memset(aSz, 0, nByte);
136688         aSzIns = &aSz[p->nColumn+1];
136689         aSzDel = &aSzIns[p->nColumn+1];
136690       }
136691     }
136692 
136693     while( rc==SQLITE_OK && SQLITE_ROW==sqlite3_step(pStmt) ){
136694       int iCol;
136695       int iLangid = langidFromSelect(p, pStmt);
136696       rc = fts3PendingTermsDocid(p, iLangid, sqlite3_column_int64(pStmt, 0));
136697       memset(aSz, 0, sizeof(aSz[0]) * (p->nColumn+1));
136698       for(iCol=0; rc==SQLITE_OK && iCol<p->nColumn; iCol++){
136699         if( p->abNotindexed[iCol]==0 ){
136700           const char *z = (const char *) sqlite3_column_text(pStmt, iCol+1);
136701           rc = fts3PendingTermsAdd(p, iLangid, z, iCol, &aSz[iCol]);
136702           aSz[p->nColumn] += sqlite3_column_bytes(pStmt, iCol+1);
136703         }
136704       }
136705       if( p->bHasDocsize ){
136706         fts3InsertDocsize(&rc, p, aSz);
136707       }
136708       if( rc!=SQLITE_OK ){
136709         sqlite3_finalize(pStmt);
136710         pStmt = 0;
136711       }else{
136712         nEntry++;
136713         for(iCol=0; iCol<=p->nColumn; iCol++){
136714           aSzIns[iCol] += aSz[iCol];
136715         }
136716       }
136717     }
136718     if( p->bFts4 ){
136719       fts3UpdateDocTotals(&rc, p, aSzIns, aSzDel, nEntry);
136720     }
136721     sqlite3_free(aSz);
136722 
136723     if( pStmt ){
136724       int rc2 = sqlite3_finalize(pStmt);
136725       if( rc==SQLITE_OK ){
136726         rc = rc2;
136727       }
136728     }
136729   }
136730 
136731   return rc;
136732 }
136733 
136734 
136735 /*
136736 ** This function opens a cursor used to read the input data for an 
136737 ** incremental merge operation. Specifically, it opens a cursor to scan
136738 ** the oldest nSeg segments (idx=0 through idx=(nSeg-1)) in absolute 
136739 ** level iAbsLevel.
136740 */
136741 static int fts3IncrmergeCsr(
136742   Fts3Table *p,                   /* FTS3 table handle */
136743   sqlite3_int64 iAbsLevel,        /* Absolute level to open */
136744   int nSeg,                       /* Number of segments to merge */
136745   Fts3MultiSegReader *pCsr        /* Cursor object to populate */
136746 ){
136747   int rc;                         /* Return Code */
136748   sqlite3_stmt *pStmt = 0;        /* Statement used to read %_segdir entry */  
136749   int nByte;                      /* Bytes allocated at pCsr->apSegment[] */
136750 
136751   /* Allocate space for the Fts3MultiSegReader.aCsr[] array */
136752   memset(pCsr, 0, sizeof(*pCsr));
136753   nByte = sizeof(Fts3SegReader *) * nSeg;
136754   pCsr->apSegment = (Fts3SegReader **)sqlite3_malloc(nByte);
136755 
136756   if( pCsr->apSegment==0 ){
136757     rc = SQLITE_NOMEM;
136758   }else{
136759     memset(pCsr->apSegment, 0, nByte);
136760     rc = fts3SqlStmt(p, SQL_SELECT_LEVEL, &pStmt, 0);
136761   }
136762   if( rc==SQLITE_OK ){
136763     int i;
136764     int rc2;
136765     sqlite3_bind_int64(pStmt, 1, iAbsLevel);
136766     assert( pCsr->nSegment==0 );
136767     for(i=0; rc==SQLITE_OK && sqlite3_step(pStmt)==SQLITE_ROW && i<nSeg; i++){
136768       rc = sqlite3Fts3SegReaderNew(i, 0,
136769           sqlite3_column_int64(pStmt, 1),        /* segdir.start_block */
136770           sqlite3_column_int64(pStmt, 2),        /* segdir.leaves_end_block */
136771           sqlite3_column_int64(pStmt, 3),        /* segdir.end_block */
136772           sqlite3_column_blob(pStmt, 4),         /* segdir.root */
136773           sqlite3_column_bytes(pStmt, 4),        /* segdir.root */
136774           &pCsr->apSegment[i]
136775       );
136776       pCsr->nSegment++;
136777     }
136778     rc2 = sqlite3_reset(pStmt);
136779     if( rc==SQLITE_OK ) rc = rc2;
136780   }
136781 
136782   return rc;
136783 }
136784 
136785 typedef struct IncrmergeWriter IncrmergeWriter;
136786 typedef struct NodeWriter NodeWriter;
136787 typedef struct Blob Blob;
136788 typedef struct NodeReader NodeReader;
136789 
136790 /*
136791 ** An instance of the following structure is used as a dynamic buffer
136792 ** to build up nodes or other blobs of data in.
136793 **
136794 ** The function blobGrowBuffer() is used to extend the allocation.
136795 */
136796 struct Blob {
136797   char *a;                        /* Pointer to allocation */
136798   int n;                          /* Number of valid bytes of data in a[] */
136799   int nAlloc;                     /* Allocated size of a[] (nAlloc>=n) */
136800 };
136801 
136802 /*
136803 ** This structure is used to build up buffers containing segment b-tree 
136804 ** nodes (blocks).
136805 */
136806 struct NodeWriter {
136807   sqlite3_int64 iBlock;           /* Current block id */
136808   Blob key;                       /* Last key written to the current block */
136809   Blob block;                     /* Current block image */
136810 };
136811 
136812 /*
136813 ** An object of this type contains the state required to create or append
136814 ** to an appendable b-tree segment.
136815 */
136816 struct IncrmergeWriter {
136817   int nLeafEst;                   /* Space allocated for leaf blocks */
136818   int nWork;                      /* Number of leaf pages flushed */
136819   sqlite3_int64 iAbsLevel;        /* Absolute level of input segments */
136820   int iIdx;                       /* Index of *output* segment in iAbsLevel+1 */
136821   sqlite3_int64 iStart;           /* Block number of first allocated block */
136822   sqlite3_int64 iEnd;             /* Block number of last allocated block */
136823   NodeWriter aNodeWriter[FTS_MAX_APPENDABLE_HEIGHT];
136824 };
136825 
136826 /*
136827 ** An object of the following type is used to read data from a single
136828 ** FTS segment node. See the following functions:
136829 **
136830 **     nodeReaderInit()
136831 **     nodeReaderNext()
136832 **     nodeReaderRelease()
136833 */
136834 struct NodeReader {
136835   const char *aNode;
136836   int nNode;
136837   int iOff;                       /* Current offset within aNode[] */
136838 
136839   /* Output variables. Containing the current node entry. */
136840   sqlite3_int64 iChild;           /* Pointer to child node */
136841   Blob term;                      /* Current term */
136842   const char *aDoclist;           /* Pointer to doclist */
136843   int nDoclist;                   /* Size of doclist in bytes */
136844 };
136845 
136846 /*
136847 ** If *pRc is not SQLITE_OK when this function is called, it is a no-op.
136848 ** Otherwise, if the allocation at pBlob->a is not already at least nMin
136849 ** bytes in size, extend (realloc) it to be so.
136850 **
136851 ** If an OOM error occurs, set *pRc to SQLITE_NOMEM and leave pBlob->a
136852 ** unmodified. Otherwise, if the allocation succeeds, update pBlob->nAlloc
136853 ** to reflect the new size of the pBlob->a[] buffer.
136854 */
136855 static void blobGrowBuffer(Blob *pBlob, int nMin, int *pRc){
136856   if( *pRc==SQLITE_OK && nMin>pBlob->nAlloc ){
136857     int nAlloc = nMin;
136858     char *a = (char *)sqlite3_realloc(pBlob->a, nAlloc);
136859     if( a ){
136860       pBlob->nAlloc = nAlloc;
136861       pBlob->a = a;
136862     }else{
136863       *pRc = SQLITE_NOMEM;
136864     }
136865   }
136866 }
136867 
136868 /*
136869 ** Attempt to advance the node-reader object passed as the first argument to
136870 ** the next entry on the node. 
136871 **
136872 ** Return an error code if an error occurs (SQLITE_NOMEM is possible). 
136873 ** Otherwise return SQLITE_OK. If there is no next entry on the node
136874 ** (e.g. because the current entry is the last) set NodeReader->aNode to
136875 ** NULL to indicate EOF. Otherwise, populate the NodeReader structure output 
136876 ** variables for the new entry.
136877 */
136878 static int nodeReaderNext(NodeReader *p){
136879   int bFirst = (p->term.n==0);    /* True for first term on the node */
136880   int nPrefix = 0;                /* Bytes to copy from previous term */
136881   int nSuffix = 0;                /* Bytes to append to the prefix */
136882   int rc = SQLITE_OK;             /* Return code */
136883 
136884   assert( p->aNode );
136885   if( p->iChild && bFirst==0 ) p->iChild++;
136886   if( p->iOff>=p->nNode ){
136887     /* EOF */
136888     p->aNode = 0;
136889   }else{
136890     if( bFirst==0 ){
136891       p->iOff += fts3GetVarint32(&p->aNode[p->iOff], &nPrefix);
136892     }
136893     p->iOff += fts3GetVarint32(&p->aNode[p->iOff], &nSuffix);
136894 
136895     blobGrowBuffer(&p->term, nPrefix+nSuffix, &rc);
136896     if( rc==SQLITE_OK ){
136897       memcpy(&p->term.a[nPrefix], &p->aNode[p->iOff], nSuffix);
136898       p->term.n = nPrefix+nSuffix;
136899       p->iOff += nSuffix;
136900       if( p->iChild==0 ){
136901         p->iOff += fts3GetVarint32(&p->aNode[p->iOff], &p->nDoclist);
136902         p->aDoclist = &p->aNode[p->iOff];
136903         p->iOff += p->nDoclist;
136904       }
136905     }
136906   }
136907 
136908   assert( p->iOff<=p->nNode );
136909 
136910   return rc;
136911 }
136912 
136913 /*
136914 ** Release all dynamic resources held by node-reader object *p.
136915 */
136916 static void nodeReaderRelease(NodeReader *p){
136917   sqlite3_free(p->term.a);
136918 }
136919 
136920 /*
136921 ** Initialize a node-reader object to read the node in buffer aNode/nNode.
136922 **
136923 ** If successful, SQLITE_OK is returned and the NodeReader object set to 
136924 ** point to the first entry on the node (if any). Otherwise, an SQLite
136925 ** error code is returned.
136926 */
136927 static int nodeReaderInit(NodeReader *p, const char *aNode, int nNode){
136928   memset(p, 0, sizeof(NodeReader));
136929   p->aNode = aNode;
136930   p->nNode = nNode;
136931 
136932   /* Figure out if this is a leaf or an internal node. */
136933   if( p->aNode[0] ){
136934     /* An internal node. */
136935     p->iOff = 1 + sqlite3Fts3GetVarint(&p->aNode[1], &p->iChild);
136936   }else{
136937     p->iOff = 1;
136938   }
136939 
136940   return nodeReaderNext(p);
136941 }
136942 
136943 /*
136944 ** This function is called while writing an FTS segment each time a leaf o
136945 ** node is finished and written to disk. The key (zTerm/nTerm) is guaranteed
136946 ** to be greater than the largest key on the node just written, but smaller
136947 ** than or equal to the first key that will be written to the next leaf
136948 ** node.
136949 **
136950 ** The block id of the leaf node just written to disk may be found in
136951 ** (pWriter->aNodeWriter[0].iBlock) when this function is called.
136952 */
136953 static int fts3IncrmergePush(
136954   Fts3Table *p,                   /* Fts3 table handle */
136955   IncrmergeWriter *pWriter,       /* Writer object */
136956   const char *zTerm,              /* Term to write to internal node */
136957   int nTerm                       /* Bytes at zTerm */
136958 ){
136959   sqlite3_int64 iPtr = pWriter->aNodeWriter[0].iBlock;
136960   int iLayer;
136961 
136962   assert( nTerm>0 );
136963   for(iLayer=1; ALWAYS(iLayer<FTS_MAX_APPENDABLE_HEIGHT); iLayer++){
136964     sqlite3_int64 iNextPtr = 0;
136965     NodeWriter *pNode = &pWriter->aNodeWriter[iLayer];
136966     int rc = SQLITE_OK;
136967     int nPrefix;
136968     int nSuffix;
136969     int nSpace;
136970 
136971     /* Figure out how much space the key will consume if it is written to
136972     ** the current node of layer iLayer. Due to the prefix compression, 
136973     ** the space required changes depending on which node the key is to
136974     ** be added to.  */
136975     nPrefix = fts3PrefixCompress(pNode->key.a, pNode->key.n, zTerm, nTerm);
136976     nSuffix = nTerm - nPrefix;
136977     nSpace  = sqlite3Fts3VarintLen(nPrefix);
136978     nSpace += sqlite3Fts3VarintLen(nSuffix) + nSuffix;
136979 
136980     if( pNode->key.n==0 || (pNode->block.n + nSpace)<=p->nNodeSize ){ 
136981       /* If the current node of layer iLayer contains zero keys, or if adding
136982       ** the key to it will not cause it to grow to larger than nNodeSize 
136983       ** bytes in size, write the key here.  */
136984 
136985       Blob *pBlk = &pNode->block;
136986       if( pBlk->n==0 ){
136987         blobGrowBuffer(pBlk, p->nNodeSize, &rc);
136988         if( rc==SQLITE_OK ){
136989           pBlk->a[0] = (char)iLayer;
136990           pBlk->n = 1 + sqlite3Fts3PutVarint(&pBlk->a[1], iPtr);
136991         }
136992       }
136993       blobGrowBuffer(pBlk, pBlk->n + nSpace, &rc);
136994       blobGrowBuffer(&pNode->key, nTerm, &rc);
136995 
136996       if( rc==SQLITE_OK ){
136997         if( pNode->key.n ){
136998           pBlk->n += sqlite3Fts3PutVarint(&pBlk->a[pBlk->n], nPrefix);
136999         }
137000         pBlk->n += sqlite3Fts3PutVarint(&pBlk->a[pBlk->n], nSuffix);
137001         memcpy(&pBlk->a[pBlk->n], &zTerm[nPrefix], nSuffix);
137002         pBlk->n += nSuffix;
137003 
137004         memcpy(pNode->key.a, zTerm, nTerm);
137005         pNode->key.n = nTerm;
137006       }
137007     }else{
137008       /* Otherwise, flush the current node of layer iLayer to disk.
137009       ** Then allocate a new, empty sibling node. The key will be written
137010       ** into the parent of this node. */
137011       rc = fts3WriteSegment(p, pNode->iBlock, pNode->block.a, pNode->block.n);
137012 
137013       assert( pNode->block.nAlloc>=p->nNodeSize );
137014       pNode->block.a[0] = (char)iLayer;
137015       pNode->block.n = 1 + sqlite3Fts3PutVarint(&pNode->block.a[1], iPtr+1);
137016 
137017       iNextPtr = pNode->iBlock;
137018       pNode->iBlock++;
137019       pNode->key.n = 0;
137020     }
137021 
137022     if( rc!=SQLITE_OK || iNextPtr==0 ) return rc;
137023     iPtr = iNextPtr;
137024   }
137025 
137026   assert( 0 );
137027   return 0;
137028 }
137029 
137030 /*
137031 ** Append a term and (optionally) doclist to the FTS segment node currently
137032 ** stored in blob *pNode. The node need not contain any terms, but the
137033 ** header must be written before this function is called.
137034 **
137035 ** A node header is a single 0x00 byte for a leaf node, or a height varint
137036 ** followed by the left-hand-child varint for an internal node.
137037 **
137038 ** The term to be appended is passed via arguments zTerm/nTerm. For a 
137039 ** leaf node, the doclist is passed as aDoclist/nDoclist. For an internal
137040 ** node, both aDoclist and nDoclist must be passed 0.
137041 **
137042 ** If the size of the value in blob pPrev is zero, then this is the first
137043 ** term written to the node. Otherwise, pPrev contains a copy of the 
137044 ** previous term. Before this function returns, it is updated to contain a
137045 ** copy of zTerm/nTerm.
137046 **
137047 ** It is assumed that the buffer associated with pNode is already large
137048 ** enough to accommodate the new entry. The buffer associated with pPrev
137049 ** is extended by this function if requrired.
137050 **
137051 ** If an error (i.e. OOM condition) occurs, an SQLite error code is
137052 ** returned. Otherwise, SQLITE_OK.
137053 */
137054 static int fts3AppendToNode(
137055   Blob *pNode,                    /* Current node image to append to */
137056   Blob *pPrev,                    /* Buffer containing previous term written */
137057   const char *zTerm,              /* New term to write */
137058   int nTerm,                      /* Size of zTerm in bytes */
137059   const char *aDoclist,           /* Doclist (or NULL) to write */
137060   int nDoclist                    /* Size of aDoclist in bytes */ 
137061 ){
137062   int rc = SQLITE_OK;             /* Return code */
137063   int bFirst = (pPrev->n==0);     /* True if this is the first term written */
137064   int nPrefix;                    /* Size of term prefix in bytes */
137065   int nSuffix;                    /* Size of term suffix in bytes */
137066 
137067   /* Node must have already been started. There must be a doclist for a
137068   ** leaf node, and there must not be a doclist for an internal node.  */
137069   assert( pNode->n>0 );
137070   assert( (pNode->a[0]=='\0')==(aDoclist!=0) );
137071 
137072   blobGrowBuffer(pPrev, nTerm, &rc);
137073   if( rc!=SQLITE_OK ) return rc;
137074 
137075   nPrefix = fts3PrefixCompress(pPrev->a, pPrev->n, zTerm, nTerm);
137076   nSuffix = nTerm - nPrefix;
137077   memcpy(pPrev->a, zTerm, nTerm);
137078   pPrev->n = nTerm;
137079 
137080   if( bFirst==0 ){
137081     pNode->n += sqlite3Fts3PutVarint(&pNode->a[pNode->n], nPrefix);
137082   }
137083   pNode->n += sqlite3Fts3PutVarint(&pNode->a[pNode->n], nSuffix);
137084   memcpy(&pNode->a[pNode->n], &zTerm[nPrefix], nSuffix);
137085   pNode->n += nSuffix;
137086 
137087   if( aDoclist ){
137088     pNode->n += sqlite3Fts3PutVarint(&pNode->a[pNode->n], nDoclist);
137089     memcpy(&pNode->a[pNode->n], aDoclist, nDoclist);
137090     pNode->n += nDoclist;
137091   }
137092 
137093   assert( pNode->n<=pNode->nAlloc );
137094 
137095   return SQLITE_OK;
137096 }
137097 
137098 /*
137099 ** Append the current term and doclist pointed to by cursor pCsr to the
137100 ** appendable b-tree segment opened for writing by pWriter.
137101 **
137102 ** Return SQLITE_OK if successful, or an SQLite error code otherwise.
137103 */
137104 static int fts3IncrmergeAppend(
137105   Fts3Table *p,                   /* Fts3 table handle */
137106   IncrmergeWriter *pWriter,       /* Writer object */
137107   Fts3MultiSegReader *pCsr        /* Cursor containing term and doclist */
137108 ){
137109   const char *zTerm = pCsr->zTerm;
137110   int nTerm = pCsr->nTerm;
137111   const char *aDoclist = pCsr->aDoclist;
137112   int nDoclist = pCsr->nDoclist;
137113   int rc = SQLITE_OK;           /* Return code */
137114   int nSpace;                   /* Total space in bytes required on leaf */
137115   int nPrefix;                  /* Size of prefix shared with previous term */
137116   int nSuffix;                  /* Size of suffix (nTerm - nPrefix) */
137117   NodeWriter *pLeaf;            /* Object used to write leaf nodes */
137118 
137119   pLeaf = &pWriter->aNodeWriter[0];
137120   nPrefix = fts3PrefixCompress(pLeaf->key.a, pLeaf->key.n, zTerm, nTerm);
137121   nSuffix = nTerm - nPrefix;
137122 
137123   nSpace  = sqlite3Fts3VarintLen(nPrefix);
137124   nSpace += sqlite3Fts3VarintLen(nSuffix) + nSuffix;
137125   nSpace += sqlite3Fts3VarintLen(nDoclist) + nDoclist;
137126 
137127   /* If the current block is not empty, and if adding this term/doclist
137128   ** to the current block would make it larger than Fts3Table.nNodeSize
137129   ** bytes, write this block out to the database. */
137130   if( pLeaf->block.n>0 && (pLeaf->block.n + nSpace)>p->nNodeSize ){
137131     rc = fts3WriteSegment(p, pLeaf->iBlock, pLeaf->block.a, pLeaf->block.n);
137132     pWriter->nWork++;
137133 
137134     /* Add the current term to the parent node. The term added to the 
137135     ** parent must:
137136     **
137137     **   a) be greater than the largest term on the leaf node just written
137138     **      to the database (still available in pLeaf->key), and
137139     **
137140     **   b) be less than or equal to the term about to be added to the new
137141     **      leaf node (zTerm/nTerm).
137142     **
137143     ** In other words, it must be the prefix of zTerm 1 byte longer than
137144     ** the common prefix (if any) of zTerm and pWriter->zTerm.
137145     */
137146     if( rc==SQLITE_OK ){
137147       rc = fts3IncrmergePush(p, pWriter, zTerm, nPrefix+1);
137148     }
137149 
137150     /* Advance to the next output block */
137151     pLeaf->iBlock++;
137152     pLeaf->key.n = 0;
137153     pLeaf->block.n = 0;
137154 
137155     nSuffix = nTerm;
137156     nSpace  = 1;
137157     nSpace += sqlite3Fts3VarintLen(nSuffix) + nSuffix;
137158     nSpace += sqlite3Fts3VarintLen(nDoclist) + nDoclist;
137159   }
137160 
137161   blobGrowBuffer(&pLeaf->block, pLeaf->block.n + nSpace, &rc);
137162 
137163   if( rc==SQLITE_OK ){
137164     if( pLeaf->block.n==0 ){
137165       pLeaf->block.n = 1;
137166       pLeaf->block.a[0] = '\0';
137167     }
137168     rc = fts3AppendToNode(
137169         &pLeaf->block, &pLeaf->key, zTerm, nTerm, aDoclist, nDoclist
137170     );
137171   }
137172 
137173   return rc;
137174 }
137175 
137176 /*
137177 ** This function is called to release all dynamic resources held by the
137178 ** merge-writer object pWriter, and if no error has occurred, to flush
137179 ** all outstanding node buffers held by pWriter to disk.
137180 **
137181 ** If *pRc is not SQLITE_OK when this function is called, then no attempt
137182 ** is made to write any data to disk. Instead, this function serves only
137183 ** to release outstanding resources.
137184 **
137185 ** Otherwise, if *pRc is initially SQLITE_OK and an error occurs while
137186 ** flushing buffers to disk, *pRc is set to an SQLite error code before
137187 ** returning.
137188 */
137189 static void fts3IncrmergeRelease(
137190   Fts3Table *p,                   /* FTS3 table handle */
137191   IncrmergeWriter *pWriter,       /* Merge-writer object */
137192   int *pRc                        /* IN/OUT: Error code */
137193 ){
137194   int i;                          /* Used to iterate through non-root layers */
137195   int iRoot;                      /* Index of root in pWriter->aNodeWriter */
137196   NodeWriter *pRoot;              /* NodeWriter for root node */
137197   int rc = *pRc;                  /* Error code */
137198 
137199   /* Set iRoot to the index in pWriter->aNodeWriter[] of the output segment 
137200   ** root node. If the segment fits entirely on a single leaf node, iRoot
137201   ** will be set to 0. If the root node is the parent of the leaves, iRoot
137202   ** will be 1. And so on.  */
137203   for(iRoot=FTS_MAX_APPENDABLE_HEIGHT-1; iRoot>=0; iRoot--){
137204     NodeWriter *pNode = &pWriter->aNodeWriter[iRoot];
137205     if( pNode->block.n>0 ) break;
137206     assert( *pRc || pNode->block.nAlloc==0 );
137207     assert( *pRc || pNode->key.nAlloc==0 );
137208     sqlite3_free(pNode->block.a);
137209     sqlite3_free(pNode->key.a);
137210   }
137211 
137212   /* Empty output segment. This is a no-op. */
137213   if( iRoot<0 ) return;
137214 
137215   /* The entire output segment fits on a single node. Normally, this means
137216   ** the node would be stored as a blob in the "root" column of the %_segdir
137217   ** table. However, this is not permitted in this case. The problem is that 
137218   ** space has already been reserved in the %_segments table, and so the 
137219   ** start_block and end_block fields of the %_segdir table must be populated. 
137220   ** And, by design or by accident, released versions of FTS cannot handle 
137221   ** segments that fit entirely on the root node with start_block!=0.
137222   **
137223   ** Instead, create a synthetic root node that contains nothing but a 
137224   ** pointer to the single content node. So that the segment consists of a
137225   ** single leaf and a single interior (root) node.
137226   **
137227   ** Todo: Better might be to defer allocating space in the %_segments 
137228   ** table until we are sure it is needed.
137229   */
137230   if( iRoot==0 ){
137231     Blob *pBlock = &pWriter->aNodeWriter[1].block;
137232     blobGrowBuffer(pBlock, 1 + FTS3_VARINT_MAX, &rc);
137233     if( rc==SQLITE_OK ){
137234       pBlock->a[0] = 0x01;
137235       pBlock->n = 1 + sqlite3Fts3PutVarint(
137236           &pBlock->a[1], pWriter->aNodeWriter[0].iBlock
137237       );
137238     }
137239     iRoot = 1;
137240   }
137241   pRoot = &pWriter->aNodeWriter[iRoot];
137242 
137243   /* Flush all currently outstanding nodes to disk. */
137244   for(i=0; i<iRoot; i++){
137245     NodeWriter *pNode = &pWriter->aNodeWriter[i];
137246     if( pNode->block.n>0 && rc==SQLITE_OK ){
137247       rc = fts3WriteSegment(p, pNode->iBlock, pNode->block.a, pNode->block.n);
137248     }
137249     sqlite3_free(pNode->block.a);
137250     sqlite3_free(pNode->key.a);
137251   }
137252 
137253   /* Write the %_segdir record. */
137254   if( rc==SQLITE_OK ){
137255     rc = fts3WriteSegdir(p, 
137256         pWriter->iAbsLevel+1,               /* level */
137257         pWriter->iIdx,                      /* idx */
137258         pWriter->iStart,                    /* start_block */
137259         pWriter->aNodeWriter[0].iBlock,     /* leaves_end_block */
137260         pWriter->iEnd,                      /* end_block */
137261         pRoot->block.a, pRoot->block.n      /* root */
137262     );
137263   }
137264   sqlite3_free(pRoot->block.a);
137265   sqlite3_free(pRoot->key.a);
137266 
137267   *pRc = rc;
137268 }
137269 
137270 /*
137271 ** Compare the term in buffer zLhs (size in bytes nLhs) with that in
137272 ** zRhs (size in bytes nRhs) using memcmp. If one term is a prefix of
137273 ** the other, it is considered to be smaller than the other.
137274 **
137275 ** Return -ve if zLhs is smaller than zRhs, 0 if it is equal, or +ve
137276 ** if it is greater.
137277 */
137278 static int fts3TermCmp(
137279   const char *zLhs, int nLhs,     /* LHS of comparison */
137280   const char *zRhs, int nRhs      /* RHS of comparison */
137281 ){
137282   int nCmp = MIN(nLhs, nRhs);
137283   int res;
137284 
137285   res = memcmp(zLhs, zRhs, nCmp);
137286   if( res==0 ) res = nLhs - nRhs;
137287 
137288   return res;
137289 }
137290 
137291 
137292 /*
137293 ** Query to see if the entry in the %_segments table with blockid iEnd is 
137294 ** NULL. If no error occurs and the entry is NULL, set *pbRes 1 before
137295 ** returning. Otherwise, set *pbRes to 0. 
137296 **
137297 ** Or, if an error occurs while querying the database, return an SQLite 
137298 ** error code. The final value of *pbRes is undefined in this case.
137299 **
137300 ** This is used to test if a segment is an "appendable" segment. If it
137301 ** is, then a NULL entry has been inserted into the %_segments table
137302 ** with blockid %_segdir.end_block.
137303 */
137304 static int fts3IsAppendable(Fts3Table *p, sqlite3_int64 iEnd, int *pbRes){
137305   int bRes = 0;                   /* Result to set *pbRes to */
137306   sqlite3_stmt *pCheck = 0;       /* Statement to query database with */
137307   int rc;                         /* Return code */
137308 
137309   rc = fts3SqlStmt(p, SQL_SEGMENT_IS_APPENDABLE, &pCheck, 0);
137310   if( rc==SQLITE_OK ){
137311     sqlite3_bind_int64(pCheck, 1, iEnd);
137312     if( SQLITE_ROW==sqlite3_step(pCheck) ) bRes = 1;
137313     rc = sqlite3_reset(pCheck);
137314   }
137315   
137316   *pbRes = bRes;
137317   return rc;
137318 }
137319 
137320 /*
137321 ** This function is called when initializing an incremental-merge operation.
137322 ** It checks if the existing segment with index value iIdx at absolute level 
137323 ** (iAbsLevel+1) can be appended to by the incremental merge. If it can, the
137324 ** merge-writer object *pWriter is initialized to write to it.
137325 **
137326 ** An existing segment can be appended to by an incremental merge if:
137327 **
137328 **   * It was initially created as an appendable segment (with all required
137329 **     space pre-allocated), and
137330 **
137331 **   * The first key read from the input (arguments zKey and nKey) is 
137332 **     greater than the largest key currently stored in the potential
137333 **     output segment.
137334 */
137335 static int fts3IncrmergeLoad(
137336   Fts3Table *p,                   /* Fts3 table handle */
137337   sqlite3_int64 iAbsLevel,        /* Absolute level of input segments */
137338   int iIdx,                       /* Index of candidate output segment */
137339   const char *zKey,               /* First key to write */
137340   int nKey,                       /* Number of bytes in nKey */
137341   IncrmergeWriter *pWriter        /* Populate this object */
137342 ){
137343   int rc;                         /* Return code */
137344   sqlite3_stmt *pSelect = 0;      /* SELECT to read %_segdir entry */
137345 
137346   rc = fts3SqlStmt(p, SQL_SELECT_SEGDIR, &pSelect, 0);
137347   if( rc==SQLITE_OK ){
137348     sqlite3_int64 iStart = 0;     /* Value of %_segdir.start_block */
137349     sqlite3_int64 iLeafEnd = 0;   /* Value of %_segdir.leaves_end_block */
137350     sqlite3_int64 iEnd = 0;       /* Value of %_segdir.end_block */
137351     const char *aRoot = 0;        /* Pointer to %_segdir.root buffer */
137352     int nRoot = 0;                /* Size of aRoot[] in bytes */
137353     int rc2;                      /* Return code from sqlite3_reset() */
137354     int bAppendable = 0;          /* Set to true if segment is appendable */
137355 
137356     /* Read the %_segdir entry for index iIdx absolute level (iAbsLevel+1) */
137357     sqlite3_bind_int64(pSelect, 1, iAbsLevel+1);
137358     sqlite3_bind_int(pSelect, 2, iIdx);
137359     if( sqlite3_step(pSelect)==SQLITE_ROW ){
137360       iStart = sqlite3_column_int64(pSelect, 1);
137361       iLeafEnd = sqlite3_column_int64(pSelect, 2);
137362       iEnd = sqlite3_column_int64(pSelect, 3);
137363       nRoot = sqlite3_column_bytes(pSelect, 4);
137364       aRoot = sqlite3_column_blob(pSelect, 4);
137365     }else{
137366       return sqlite3_reset(pSelect);
137367     }
137368 
137369     /* Check for the zero-length marker in the %_segments table */
137370     rc = fts3IsAppendable(p, iEnd, &bAppendable);
137371 
137372     /* Check that zKey/nKey is larger than the largest key the candidate */
137373     if( rc==SQLITE_OK && bAppendable ){
137374       char *aLeaf = 0;
137375       int nLeaf = 0;
137376 
137377       rc = sqlite3Fts3ReadBlock(p, iLeafEnd, &aLeaf, &nLeaf, 0);
137378       if( rc==SQLITE_OK ){
137379         NodeReader reader;
137380         for(rc = nodeReaderInit(&reader, aLeaf, nLeaf);
137381             rc==SQLITE_OK && reader.aNode;
137382             rc = nodeReaderNext(&reader)
137383         ){
137384           assert( reader.aNode );
137385         }
137386         if( fts3TermCmp(zKey, nKey, reader.term.a, reader.term.n)<=0 ){
137387           bAppendable = 0;
137388         }
137389         nodeReaderRelease(&reader);
137390       }
137391       sqlite3_free(aLeaf);
137392     }
137393 
137394     if( rc==SQLITE_OK && bAppendable ){
137395       /* It is possible to append to this segment. Set up the IncrmergeWriter
137396       ** object to do so.  */
137397       int i;
137398       int nHeight = (int)aRoot[0];
137399       NodeWriter *pNode;
137400 
137401       pWriter->nLeafEst = (int)((iEnd - iStart) + 1)/FTS_MAX_APPENDABLE_HEIGHT;
137402       pWriter->iStart = iStart;
137403       pWriter->iEnd = iEnd;
137404       pWriter->iAbsLevel = iAbsLevel;
137405       pWriter->iIdx = iIdx;
137406 
137407       for(i=nHeight+1; i<FTS_MAX_APPENDABLE_HEIGHT; i++){
137408         pWriter->aNodeWriter[i].iBlock = pWriter->iStart + i*pWriter->nLeafEst;
137409       }
137410 
137411       pNode = &pWriter->aNodeWriter[nHeight];
137412       pNode->iBlock = pWriter->iStart + pWriter->nLeafEst*nHeight;
137413       blobGrowBuffer(&pNode->block, MAX(nRoot, p->nNodeSize), &rc);
137414       if( rc==SQLITE_OK ){
137415         memcpy(pNode->block.a, aRoot, nRoot);
137416         pNode->block.n = nRoot;
137417       }
137418 
137419       for(i=nHeight; i>=0 && rc==SQLITE_OK; i--){
137420         NodeReader reader;
137421         pNode = &pWriter->aNodeWriter[i];
137422 
137423         rc = nodeReaderInit(&reader, pNode->block.a, pNode->block.n);
137424         while( reader.aNode && rc==SQLITE_OK ) rc = nodeReaderNext(&reader);
137425         blobGrowBuffer(&pNode->key, reader.term.n, &rc);
137426         if( rc==SQLITE_OK ){
137427           memcpy(pNode->key.a, reader.term.a, reader.term.n);
137428           pNode->key.n = reader.term.n;
137429           if( i>0 ){
137430             char *aBlock = 0;
137431             int nBlock = 0;
137432             pNode = &pWriter->aNodeWriter[i-1];
137433             pNode->iBlock = reader.iChild;
137434             rc = sqlite3Fts3ReadBlock(p, reader.iChild, &aBlock, &nBlock, 0);
137435             blobGrowBuffer(&pNode->block, MAX(nBlock, p->nNodeSize), &rc);
137436             if( rc==SQLITE_OK ){
137437               memcpy(pNode->block.a, aBlock, nBlock);
137438               pNode->block.n = nBlock;
137439             }
137440             sqlite3_free(aBlock);
137441           }
137442         }
137443         nodeReaderRelease(&reader);
137444       }
137445     }
137446 
137447     rc2 = sqlite3_reset(pSelect);
137448     if( rc==SQLITE_OK ) rc = rc2;
137449   }
137450 
137451   return rc;
137452 }
137453 
137454 /*
137455 ** Determine the largest segment index value that exists within absolute
137456 ** level iAbsLevel+1. If no error occurs, set *piIdx to this value plus
137457 ** one before returning SQLITE_OK. Or, if there are no segments at all 
137458 ** within level iAbsLevel, set *piIdx to zero.
137459 **
137460 ** If an error occurs, return an SQLite error code. The final value of
137461 ** *piIdx is undefined in this case.
137462 */
137463 static int fts3IncrmergeOutputIdx( 
137464   Fts3Table *p,                   /* FTS Table handle */
137465   sqlite3_int64 iAbsLevel,        /* Absolute index of input segments */
137466   int *piIdx                      /* OUT: Next free index at iAbsLevel+1 */
137467 ){
137468   int rc;
137469   sqlite3_stmt *pOutputIdx = 0;   /* SQL used to find output index */
137470 
137471   rc = fts3SqlStmt(p, SQL_NEXT_SEGMENT_INDEX, &pOutputIdx, 0);
137472   if( rc==SQLITE_OK ){
137473     sqlite3_bind_int64(pOutputIdx, 1, iAbsLevel+1);
137474     sqlite3_step(pOutputIdx);
137475     *piIdx = sqlite3_column_int(pOutputIdx, 0);
137476     rc = sqlite3_reset(pOutputIdx);
137477   }
137478 
137479   return rc;
137480 }
137481 
137482 /* 
137483 ** Allocate an appendable output segment on absolute level iAbsLevel+1
137484 ** with idx value iIdx.
137485 **
137486 ** In the %_segdir table, a segment is defined by the values in three
137487 ** columns:
137488 **
137489 **     start_block
137490 **     leaves_end_block
137491 **     end_block
137492 **
137493 ** When an appendable segment is allocated, it is estimated that the
137494 ** maximum number of leaf blocks that may be required is the sum of the
137495 ** number of leaf blocks consumed by the input segments, plus the number
137496 ** of input segments, multiplied by two. This value is stored in stack 
137497 ** variable nLeafEst.
137498 **
137499 ** A total of 16*nLeafEst blocks are allocated when an appendable segment
137500 ** is created ((1 + end_block - start_block)==16*nLeafEst). The contiguous
137501 ** array of leaf nodes starts at the first block allocated. The array
137502 ** of interior nodes that are parents of the leaf nodes start at block
137503 ** (start_block + (1 + end_block - start_block) / 16). And so on.
137504 **
137505 ** In the actual code below, the value "16" is replaced with the 
137506 ** pre-processor macro FTS_MAX_APPENDABLE_HEIGHT.
137507 */
137508 static int fts3IncrmergeWriter( 
137509   Fts3Table *p,                   /* Fts3 table handle */
137510   sqlite3_int64 iAbsLevel,        /* Absolute level of input segments */
137511   int iIdx,                       /* Index of new output segment */
137512   Fts3MultiSegReader *pCsr,       /* Cursor that data will be read from */
137513   IncrmergeWriter *pWriter        /* Populate this object */
137514 ){
137515   int rc;                         /* Return Code */
137516   int i;                          /* Iterator variable */
137517   int nLeafEst = 0;               /* Blocks allocated for leaf nodes */
137518   sqlite3_stmt *pLeafEst = 0;     /* SQL used to determine nLeafEst */
137519   sqlite3_stmt *pFirstBlock = 0;  /* SQL used to determine first block */
137520 
137521   /* Calculate nLeafEst. */
137522   rc = fts3SqlStmt(p, SQL_MAX_LEAF_NODE_ESTIMATE, &pLeafEst, 0);
137523   if( rc==SQLITE_OK ){
137524     sqlite3_bind_int64(pLeafEst, 1, iAbsLevel);
137525     sqlite3_bind_int64(pLeafEst, 2, pCsr->nSegment);
137526     if( SQLITE_ROW==sqlite3_step(pLeafEst) ){
137527       nLeafEst = sqlite3_column_int(pLeafEst, 0);
137528     }
137529     rc = sqlite3_reset(pLeafEst);
137530   }
137531   if( rc!=SQLITE_OK ) return rc;
137532 
137533   /* Calculate the first block to use in the output segment */
137534   rc = fts3SqlStmt(p, SQL_NEXT_SEGMENTS_ID, &pFirstBlock, 0);
137535   if( rc==SQLITE_OK ){
137536     if( SQLITE_ROW==sqlite3_step(pFirstBlock) ){
137537       pWriter->iStart = sqlite3_column_int64(pFirstBlock, 0);
137538       pWriter->iEnd = pWriter->iStart - 1;
137539       pWriter->iEnd += nLeafEst * FTS_MAX_APPENDABLE_HEIGHT;
137540     }
137541     rc = sqlite3_reset(pFirstBlock);
137542   }
137543   if( rc!=SQLITE_OK ) return rc;
137544 
137545   /* Insert the marker in the %_segments table to make sure nobody tries
137546   ** to steal the space just allocated. This is also used to identify 
137547   ** appendable segments.  */
137548   rc = fts3WriteSegment(p, pWriter->iEnd, 0, 0);
137549   if( rc!=SQLITE_OK ) return rc;
137550 
137551   pWriter->iAbsLevel = iAbsLevel;
137552   pWriter->nLeafEst = nLeafEst;
137553   pWriter->iIdx = iIdx;
137554 
137555   /* Set up the array of NodeWriter objects */
137556   for(i=0; i<FTS_MAX_APPENDABLE_HEIGHT; i++){
137557     pWriter->aNodeWriter[i].iBlock = pWriter->iStart + i*pWriter->nLeafEst;
137558   }
137559   return SQLITE_OK;
137560 }
137561 
137562 /*
137563 ** Remove an entry from the %_segdir table. This involves running the 
137564 ** following two statements:
137565 **
137566 **   DELETE FROM %_segdir WHERE level = :iAbsLevel AND idx = :iIdx
137567 **   UPDATE %_segdir SET idx = idx - 1 WHERE level = :iAbsLevel AND idx > :iIdx
137568 **
137569 ** The DELETE statement removes the specific %_segdir level. The UPDATE 
137570 ** statement ensures that the remaining segments have contiguously allocated
137571 ** idx values.
137572 */
137573 static int fts3RemoveSegdirEntry(
137574   Fts3Table *p,                   /* FTS3 table handle */
137575   sqlite3_int64 iAbsLevel,        /* Absolute level to delete from */
137576   int iIdx                        /* Index of %_segdir entry to delete */
137577 ){
137578   int rc;                         /* Return code */
137579   sqlite3_stmt *pDelete = 0;      /* DELETE statement */
137580 
137581   rc = fts3SqlStmt(p, SQL_DELETE_SEGDIR_ENTRY, &pDelete, 0);
137582   if( rc==SQLITE_OK ){
137583     sqlite3_bind_int64(pDelete, 1, iAbsLevel);
137584     sqlite3_bind_int(pDelete, 2, iIdx);
137585     sqlite3_step(pDelete);
137586     rc = sqlite3_reset(pDelete);
137587   }
137588 
137589   return rc;
137590 }
137591 
137592 /*
137593 ** One or more segments have just been removed from absolute level iAbsLevel.
137594 ** Update the 'idx' values of the remaining segments in the level so that
137595 ** the idx values are a contiguous sequence starting from 0.
137596 */
137597 static int fts3RepackSegdirLevel(
137598   Fts3Table *p,                   /* FTS3 table handle */
137599   sqlite3_int64 iAbsLevel         /* Absolute level to repack */
137600 ){
137601   int rc;                         /* Return code */
137602   int *aIdx = 0;                  /* Array of remaining idx values */
137603   int nIdx = 0;                   /* Valid entries in aIdx[] */
137604   int nAlloc = 0;                 /* Allocated size of aIdx[] */
137605   int i;                          /* Iterator variable */
137606   sqlite3_stmt *pSelect = 0;      /* Select statement to read idx values */
137607   sqlite3_stmt *pUpdate = 0;      /* Update statement to modify idx values */
137608 
137609   rc = fts3SqlStmt(p, SQL_SELECT_INDEXES, &pSelect, 0);
137610   if( rc==SQLITE_OK ){
137611     int rc2;
137612     sqlite3_bind_int64(pSelect, 1, iAbsLevel);
137613     while( SQLITE_ROW==sqlite3_step(pSelect) ){
137614       if( nIdx>=nAlloc ){
137615         int *aNew;
137616         nAlloc += 16;
137617         aNew = sqlite3_realloc(aIdx, nAlloc*sizeof(int));
137618         if( !aNew ){
137619           rc = SQLITE_NOMEM;
137620           break;
137621         }
137622         aIdx = aNew;
137623       }
137624       aIdx[nIdx++] = sqlite3_column_int(pSelect, 0);
137625     }
137626     rc2 = sqlite3_reset(pSelect);
137627     if( rc==SQLITE_OK ) rc = rc2;
137628   }
137629 
137630   if( rc==SQLITE_OK ){
137631     rc = fts3SqlStmt(p, SQL_SHIFT_SEGDIR_ENTRY, &pUpdate, 0);
137632   }
137633   if( rc==SQLITE_OK ){
137634     sqlite3_bind_int64(pUpdate, 2, iAbsLevel);
137635   }
137636 
137637   assert( p->bIgnoreSavepoint==0 );
137638   p->bIgnoreSavepoint = 1;
137639   for(i=0; rc==SQLITE_OK && i<nIdx; i++){
137640     if( aIdx[i]!=i ){
137641       sqlite3_bind_int(pUpdate, 3, aIdx[i]);
137642       sqlite3_bind_int(pUpdate, 1, i);
137643       sqlite3_step(pUpdate);
137644       rc = sqlite3_reset(pUpdate);
137645     }
137646   }
137647   p->bIgnoreSavepoint = 0;
137648 
137649   sqlite3_free(aIdx);
137650   return rc;
137651 }
137652 
137653 static void fts3StartNode(Blob *pNode, int iHeight, sqlite3_int64 iChild){
137654   pNode->a[0] = (char)iHeight;
137655   if( iChild ){
137656     assert( pNode->nAlloc>=1+sqlite3Fts3VarintLen(iChild) );
137657     pNode->n = 1 + sqlite3Fts3PutVarint(&pNode->a[1], iChild);
137658   }else{
137659     assert( pNode->nAlloc>=1 );
137660     pNode->n = 1;
137661   }
137662 }
137663 
137664 /*
137665 ** The first two arguments are a pointer to and the size of a segment b-tree
137666 ** node. The node may be a leaf or an internal node.
137667 **
137668 ** This function creates a new node image in blob object *pNew by copying
137669 ** all terms that are greater than or equal to zTerm/nTerm (for leaf nodes)
137670 ** or greater than zTerm/nTerm (for internal nodes) from aNode/nNode.
137671 */
137672 static int fts3TruncateNode(
137673   const char *aNode,              /* Current node image */
137674   int nNode,                      /* Size of aNode in bytes */
137675   Blob *pNew,                     /* OUT: Write new node image here */
137676   const char *zTerm,              /* Omit all terms smaller than this */
137677   int nTerm,                      /* Size of zTerm in bytes */
137678   sqlite3_int64 *piBlock          /* OUT: Block number in next layer down */
137679 ){
137680   NodeReader reader;              /* Reader object */
137681   Blob prev = {0, 0, 0};          /* Previous term written to new node */
137682   int rc = SQLITE_OK;             /* Return code */
137683   int bLeaf = aNode[0]=='\0';     /* True for a leaf node */
137684 
137685   /* Allocate required output space */
137686   blobGrowBuffer(pNew, nNode, &rc);
137687   if( rc!=SQLITE_OK ) return rc;
137688   pNew->n = 0;
137689 
137690   /* Populate new node buffer */
137691   for(rc = nodeReaderInit(&reader, aNode, nNode); 
137692       rc==SQLITE_OK && reader.aNode; 
137693       rc = nodeReaderNext(&reader)
137694   ){
137695     if( pNew->n==0 ){
137696       int res = fts3TermCmp(reader.term.a, reader.term.n, zTerm, nTerm);
137697       if( res<0 || (bLeaf==0 && res==0) ) continue;
137698       fts3StartNode(pNew, (int)aNode[0], reader.iChild);
137699       *piBlock = reader.iChild;
137700     }
137701     rc = fts3AppendToNode(
137702         pNew, &prev, reader.term.a, reader.term.n,
137703         reader.aDoclist, reader.nDoclist
137704     );
137705     if( rc!=SQLITE_OK ) break;
137706   }
137707   if( pNew->n==0 ){
137708     fts3StartNode(pNew, (int)aNode[0], reader.iChild);
137709     *piBlock = reader.iChild;
137710   }
137711   assert( pNew->n<=pNew->nAlloc );
137712 
137713   nodeReaderRelease(&reader);
137714   sqlite3_free(prev.a);
137715   return rc;
137716 }
137717 
137718 /*
137719 ** Remove all terms smaller than zTerm/nTerm from segment iIdx in absolute 
137720 ** level iAbsLevel. This may involve deleting entries from the %_segments
137721 ** table, and modifying existing entries in both the %_segments and %_segdir
137722 ** tables.
137723 **
137724 ** SQLITE_OK is returned if the segment is updated successfully. Or an
137725 ** SQLite error code otherwise.
137726 */
137727 static int fts3TruncateSegment(
137728   Fts3Table *p,                   /* FTS3 table handle */
137729   sqlite3_int64 iAbsLevel,        /* Absolute level of segment to modify */
137730   int iIdx,                       /* Index within level of segment to modify */
137731   const char *zTerm,              /* Remove terms smaller than this */
137732   int nTerm                      /* Number of bytes in buffer zTerm */
137733 ){
137734   int rc = SQLITE_OK;             /* Return code */
137735   Blob root = {0,0,0};            /* New root page image */
137736   Blob block = {0,0,0};           /* Buffer used for any other block */
137737   sqlite3_int64 iBlock = 0;       /* Block id */
137738   sqlite3_int64 iNewStart = 0;    /* New value for iStartBlock */
137739   sqlite3_int64 iOldStart = 0;    /* Old value for iStartBlock */
137740   sqlite3_stmt *pFetch = 0;       /* Statement used to fetch segdir */
137741 
137742   rc = fts3SqlStmt(p, SQL_SELECT_SEGDIR, &pFetch, 0);
137743   if( rc==SQLITE_OK ){
137744     int rc2;                      /* sqlite3_reset() return code */
137745     sqlite3_bind_int64(pFetch, 1, iAbsLevel);
137746     sqlite3_bind_int(pFetch, 2, iIdx);
137747     if( SQLITE_ROW==sqlite3_step(pFetch) ){
137748       const char *aRoot = sqlite3_column_blob(pFetch, 4);
137749       int nRoot = sqlite3_column_bytes(pFetch, 4);
137750       iOldStart = sqlite3_column_int64(pFetch, 1);
137751       rc = fts3TruncateNode(aRoot, nRoot, &root, zTerm, nTerm, &iBlock);
137752     }
137753     rc2 = sqlite3_reset(pFetch);
137754     if( rc==SQLITE_OK ) rc = rc2;
137755   }
137756 
137757   while( rc==SQLITE_OK && iBlock ){
137758     char *aBlock = 0;
137759     int nBlock = 0;
137760     iNewStart = iBlock;
137761 
137762     rc = sqlite3Fts3ReadBlock(p, iBlock, &aBlock, &nBlock, 0);
137763     if( rc==SQLITE_OK ){
137764       rc = fts3TruncateNode(aBlock, nBlock, &block, zTerm, nTerm, &iBlock);
137765     }
137766     if( rc==SQLITE_OK ){
137767       rc = fts3WriteSegment(p, iNewStart, block.a, block.n);
137768     }
137769     sqlite3_free(aBlock);
137770   }
137771 
137772   /* Variable iNewStart now contains the first valid leaf node. */
137773   if( rc==SQLITE_OK && iNewStart ){
137774     sqlite3_stmt *pDel = 0;
137775     rc = fts3SqlStmt(p, SQL_DELETE_SEGMENTS_RANGE, &pDel, 0);
137776     if( rc==SQLITE_OK ){
137777       sqlite3_bind_int64(pDel, 1, iOldStart);
137778       sqlite3_bind_int64(pDel, 2, iNewStart-1);
137779       sqlite3_step(pDel);
137780       rc = sqlite3_reset(pDel);
137781     }
137782   }
137783 
137784   if( rc==SQLITE_OK ){
137785     sqlite3_stmt *pChomp = 0;
137786     rc = fts3SqlStmt(p, SQL_CHOMP_SEGDIR, &pChomp, 0);
137787     if( rc==SQLITE_OK ){
137788       sqlite3_bind_int64(pChomp, 1, iNewStart);
137789       sqlite3_bind_blob(pChomp, 2, root.a, root.n, SQLITE_STATIC);
137790       sqlite3_bind_int64(pChomp, 3, iAbsLevel);
137791       sqlite3_bind_int(pChomp, 4, iIdx);
137792       sqlite3_step(pChomp);
137793       rc = sqlite3_reset(pChomp);
137794     }
137795   }
137796 
137797   sqlite3_free(root.a);
137798   sqlite3_free(block.a);
137799   return rc;
137800 }
137801 
137802 /*
137803 ** This function is called after an incrmental-merge operation has run to
137804 ** merge (or partially merge) two or more segments from absolute level
137805 ** iAbsLevel.
137806 **
137807 ** Each input segment is either removed from the db completely (if all of
137808 ** its data was copied to the output segment by the incrmerge operation)
137809 ** or modified in place so that it no longer contains those entries that
137810 ** have been duplicated in the output segment.
137811 */
137812 static int fts3IncrmergeChomp(
137813   Fts3Table *p,                   /* FTS table handle */
137814   sqlite3_int64 iAbsLevel,        /* Absolute level containing segments */
137815   Fts3MultiSegReader *pCsr,       /* Chomp all segments opened by this cursor */
137816   int *pnRem                      /* Number of segments not deleted */
137817 ){
137818   int i;
137819   int nRem = 0;
137820   int rc = SQLITE_OK;
137821 
137822   for(i=pCsr->nSegment-1; i>=0 && rc==SQLITE_OK; i--){
137823     Fts3SegReader *pSeg = 0;
137824     int j;
137825 
137826     /* Find the Fts3SegReader object with Fts3SegReader.iIdx==i. It is hiding
137827     ** somewhere in the pCsr->apSegment[] array.  */
137828     for(j=0; ALWAYS(j<pCsr->nSegment); j++){
137829       pSeg = pCsr->apSegment[j];
137830       if( pSeg->iIdx==i ) break;
137831     }
137832     assert( j<pCsr->nSegment && pSeg->iIdx==i );
137833 
137834     if( pSeg->aNode==0 ){
137835       /* Seg-reader is at EOF. Remove the entire input segment. */
137836       rc = fts3DeleteSegment(p, pSeg);
137837       if( rc==SQLITE_OK ){
137838         rc = fts3RemoveSegdirEntry(p, iAbsLevel, pSeg->iIdx);
137839       }
137840       *pnRem = 0;
137841     }else{
137842       /* The incremental merge did not copy all the data from this 
137843       ** segment to the upper level. The segment is modified in place
137844       ** so that it contains no keys smaller than zTerm/nTerm. */ 
137845       const char *zTerm = pSeg->zTerm;
137846       int nTerm = pSeg->nTerm;
137847       rc = fts3TruncateSegment(p, iAbsLevel, pSeg->iIdx, zTerm, nTerm);
137848       nRem++;
137849     }
137850   }
137851 
137852   if( rc==SQLITE_OK && nRem!=pCsr->nSegment ){
137853     rc = fts3RepackSegdirLevel(p, iAbsLevel);
137854   }
137855 
137856   *pnRem = nRem;
137857   return rc;
137858 }
137859 
137860 /*
137861 ** Store an incr-merge hint in the database.
137862 */
137863 static int fts3IncrmergeHintStore(Fts3Table *p, Blob *pHint){
137864   sqlite3_stmt *pReplace = 0;
137865   int rc;                         /* Return code */
137866 
137867   rc = fts3SqlStmt(p, SQL_REPLACE_STAT, &pReplace, 0);
137868   if( rc==SQLITE_OK ){
137869     sqlite3_bind_int(pReplace, 1, FTS_STAT_INCRMERGEHINT);
137870     sqlite3_bind_blob(pReplace, 2, pHint->a, pHint->n, SQLITE_STATIC);
137871     sqlite3_step(pReplace);
137872     rc = sqlite3_reset(pReplace);
137873   }
137874 
137875   return rc;
137876 }
137877 
137878 /*
137879 ** Load an incr-merge hint from the database. The incr-merge hint, if one 
137880 ** exists, is stored in the rowid==1 row of the %_stat table.
137881 **
137882 ** If successful, populate blob *pHint with the value read from the %_stat
137883 ** table and return SQLITE_OK. Otherwise, if an error occurs, return an
137884 ** SQLite error code.
137885 */
137886 static int fts3IncrmergeHintLoad(Fts3Table *p, Blob *pHint){
137887   sqlite3_stmt *pSelect = 0;
137888   int rc;
137889 
137890   pHint->n = 0;
137891   rc = fts3SqlStmt(p, SQL_SELECT_STAT, &pSelect, 0);
137892   if( rc==SQLITE_OK ){
137893     int rc2;
137894     sqlite3_bind_int(pSelect, 1, FTS_STAT_INCRMERGEHINT);
137895     if( SQLITE_ROW==sqlite3_step(pSelect) ){
137896       const char *aHint = sqlite3_column_blob(pSelect, 0);
137897       int nHint = sqlite3_column_bytes(pSelect, 0);
137898       if( aHint ){
137899         blobGrowBuffer(pHint, nHint, &rc);
137900         if( rc==SQLITE_OK ){
137901           memcpy(pHint->a, aHint, nHint);
137902           pHint->n = nHint;
137903         }
137904       }
137905     }
137906     rc2 = sqlite3_reset(pSelect);
137907     if( rc==SQLITE_OK ) rc = rc2;
137908   }
137909 
137910   return rc;
137911 }
137912 
137913 /*
137914 ** If *pRc is not SQLITE_OK when this function is called, it is a no-op.
137915 ** Otherwise, append an entry to the hint stored in blob *pHint. Each entry
137916 ** consists of two varints, the absolute level number of the input segments 
137917 ** and the number of input segments.
137918 **
137919 ** If successful, leave *pRc set to SQLITE_OK and return. If an error occurs,
137920 ** set *pRc to an SQLite error code before returning.
137921 */
137922 static void fts3IncrmergeHintPush(
137923   Blob *pHint,                    /* Hint blob to append to */
137924   i64 iAbsLevel,                  /* First varint to store in hint */
137925   int nInput,                     /* Second varint to store in hint */
137926   int *pRc                        /* IN/OUT: Error code */
137927 ){
137928   blobGrowBuffer(pHint, pHint->n + 2*FTS3_VARINT_MAX, pRc);
137929   if( *pRc==SQLITE_OK ){
137930     pHint->n += sqlite3Fts3PutVarint(&pHint->a[pHint->n], iAbsLevel);
137931     pHint->n += sqlite3Fts3PutVarint(&pHint->a[pHint->n], (i64)nInput);
137932   }
137933 }
137934 
137935 /*
137936 ** Read the last entry (most recently pushed) from the hint blob *pHint
137937 ** and then remove the entry. Write the two values read to *piAbsLevel and 
137938 ** *pnInput before returning.
137939 **
137940 ** If no error occurs, return SQLITE_OK. If the hint blob in *pHint does
137941 ** not contain at least two valid varints, return SQLITE_CORRUPT_VTAB.
137942 */
137943 static int fts3IncrmergeHintPop(Blob *pHint, i64 *piAbsLevel, int *pnInput){
137944   const int nHint = pHint->n;
137945   int i;
137946 
137947   i = pHint->n-2;
137948   while( i>0 && (pHint->a[i-1] & 0x80) ) i--;
137949   while( i>0 && (pHint->a[i-1] & 0x80) ) i--;
137950 
137951   pHint->n = i;
137952   i += sqlite3Fts3GetVarint(&pHint->a[i], piAbsLevel);
137953   i += fts3GetVarint32(&pHint->a[i], pnInput);
137954   if( i!=nHint ) return SQLITE_CORRUPT_VTAB;
137955 
137956   return SQLITE_OK;
137957 }
137958 
137959 
137960 /*
137961 ** Attempt an incremental merge that writes nMerge leaf blocks.
137962 **
137963 ** Incremental merges happen nMin segments at a time. The two
137964 ** segments to be merged are the nMin oldest segments (the ones with
137965 ** the smallest indexes) in the highest level that contains at least
137966 ** nMin segments. Multiple merges might occur in an attempt to write the 
137967 ** quota of nMerge leaf blocks.
137968 */
137969 SQLITE_PRIVATE int sqlite3Fts3Incrmerge(Fts3Table *p, int nMerge, int nMin){
137970   int rc;                         /* Return code */
137971   int nRem = nMerge;              /* Number of leaf pages yet to  be written */
137972   Fts3MultiSegReader *pCsr;       /* Cursor used to read input data */
137973   Fts3SegFilter *pFilter;         /* Filter used with cursor pCsr */
137974   IncrmergeWriter *pWriter;       /* Writer object */
137975   int nSeg = 0;                   /* Number of input segments */
137976   sqlite3_int64 iAbsLevel = 0;    /* Absolute level number to work on */
137977   Blob hint = {0, 0, 0};          /* Hint read from %_stat table */
137978   int bDirtyHint = 0;             /* True if blob 'hint' has been modified */
137979 
137980   /* Allocate space for the cursor, filter and writer objects */
137981   const int nAlloc = sizeof(*pCsr) + sizeof(*pFilter) + sizeof(*pWriter);
137982   pWriter = (IncrmergeWriter *)sqlite3_malloc(nAlloc);
137983   if( !pWriter ) return SQLITE_NOMEM;
137984   pFilter = (Fts3SegFilter *)&pWriter[1];
137985   pCsr = (Fts3MultiSegReader *)&pFilter[1];
137986 
137987   rc = fts3IncrmergeHintLoad(p, &hint);
137988   while( rc==SQLITE_OK && nRem>0 ){
137989     const i64 nMod = FTS3_SEGDIR_MAXLEVEL * p->nIndex;
137990     sqlite3_stmt *pFindLevel = 0; /* SQL used to determine iAbsLevel */
137991     int bUseHint = 0;             /* True if attempting to append */
137992 
137993     /* Search the %_segdir table for the absolute level with the smallest
137994     ** relative level number that contains at least nMin segments, if any.
137995     ** If one is found, set iAbsLevel to the absolute level number and
137996     ** nSeg to nMin. If no level with at least nMin segments can be found, 
137997     ** set nSeg to -1.
137998     */
137999     rc = fts3SqlStmt(p, SQL_FIND_MERGE_LEVEL, &pFindLevel, 0);
138000     sqlite3_bind_int(pFindLevel, 1, nMin);
138001     if( sqlite3_step(pFindLevel)==SQLITE_ROW ){
138002       iAbsLevel = sqlite3_column_int64(pFindLevel, 0);
138003       nSeg = nMin;
138004     }else{
138005       nSeg = -1;
138006     }
138007     rc = sqlite3_reset(pFindLevel);
138008 
138009     /* If the hint read from the %_stat table is not empty, check if the
138010     ** last entry in it specifies a relative level smaller than or equal
138011     ** to the level identified by the block above (if any). If so, this 
138012     ** iteration of the loop will work on merging at the hinted level.
138013     */
138014     if( rc==SQLITE_OK && hint.n ){
138015       int nHint = hint.n;
138016       sqlite3_int64 iHintAbsLevel = 0;      /* Hint level */
138017       int nHintSeg = 0;                     /* Hint number of segments */
138018 
138019       rc = fts3IncrmergeHintPop(&hint, &iHintAbsLevel, &nHintSeg);
138020       if( nSeg<0 || (iAbsLevel % nMod) >= (iHintAbsLevel % nMod) ){
138021         iAbsLevel = iHintAbsLevel;
138022         nSeg = nHintSeg;
138023         bUseHint = 1;
138024         bDirtyHint = 1;
138025       }else{
138026         /* This undoes the effect of the HintPop() above - so that no entry
138027         ** is removed from the hint blob.  */
138028         hint.n = nHint;
138029       }
138030     }
138031 
138032     /* If nSeg is less that zero, then there is no level with at least
138033     ** nMin segments and no hint in the %_stat table. No work to do.
138034     ** Exit early in this case.  */
138035     if( nSeg<0 ) break;
138036 
138037     /* Open a cursor to iterate through the contents of the oldest nSeg 
138038     ** indexes of absolute level iAbsLevel. If this cursor is opened using 
138039     ** the 'hint' parameters, it is possible that there are less than nSeg
138040     ** segments available in level iAbsLevel. In this case, no work is
138041     ** done on iAbsLevel - fall through to the next iteration of the loop 
138042     ** to start work on some other level.  */
138043     memset(pWriter, 0, nAlloc);
138044     pFilter->flags = FTS3_SEGMENT_REQUIRE_POS;
138045     if( rc==SQLITE_OK ){
138046       rc = fts3IncrmergeCsr(p, iAbsLevel, nSeg, pCsr);
138047     }
138048     if( SQLITE_OK==rc && pCsr->nSegment==nSeg
138049      && SQLITE_OK==(rc = sqlite3Fts3SegReaderStart(p, pCsr, pFilter))
138050      && SQLITE_ROW==(rc = sqlite3Fts3SegReaderStep(p, pCsr))
138051     ){
138052       int iIdx = 0;               /* Largest idx in level (iAbsLevel+1) */
138053       rc = fts3IncrmergeOutputIdx(p, iAbsLevel, &iIdx);
138054       if( rc==SQLITE_OK ){
138055         if( bUseHint && iIdx>0 ){
138056           const char *zKey = pCsr->zTerm;
138057           int nKey = pCsr->nTerm;
138058           rc = fts3IncrmergeLoad(p, iAbsLevel, iIdx-1, zKey, nKey, pWriter);
138059         }else{
138060           rc = fts3IncrmergeWriter(p, iAbsLevel, iIdx, pCsr, pWriter);
138061         }
138062       }
138063 
138064       if( rc==SQLITE_OK && pWriter->nLeafEst ){
138065         fts3LogMerge(nSeg, iAbsLevel);
138066         do {
138067           rc = fts3IncrmergeAppend(p, pWriter, pCsr);
138068           if( rc==SQLITE_OK ) rc = sqlite3Fts3SegReaderStep(p, pCsr);
138069           if( pWriter->nWork>=nRem && rc==SQLITE_ROW ) rc = SQLITE_OK;
138070         }while( rc==SQLITE_ROW );
138071 
138072         /* Update or delete the input segments */
138073         if( rc==SQLITE_OK ){
138074           nRem -= (1 + pWriter->nWork);
138075           rc = fts3IncrmergeChomp(p, iAbsLevel, pCsr, &nSeg);
138076           if( nSeg!=0 ){
138077             bDirtyHint = 1;
138078             fts3IncrmergeHintPush(&hint, iAbsLevel, nSeg, &rc);
138079           }
138080         }
138081       }
138082 
138083       fts3IncrmergeRelease(p, pWriter, &rc);
138084     }
138085 
138086     sqlite3Fts3SegReaderFinish(pCsr);
138087   }
138088 
138089   /* Write the hint values into the %_stat table for the next incr-merger */
138090   if( bDirtyHint && rc==SQLITE_OK ){
138091     rc = fts3IncrmergeHintStore(p, &hint);
138092   }
138093 
138094   sqlite3_free(pWriter);
138095   sqlite3_free(hint.a);
138096   return rc;
138097 }
138098 
138099 /*
138100 ** Convert the text beginning at *pz into an integer and return
138101 ** its value.  Advance *pz to point to the first character past
138102 ** the integer.
138103 */
138104 static int fts3Getint(const char **pz){
138105   const char *z = *pz;
138106   int i = 0;
138107   while( (*z)>='0' && (*z)<='9' ) i = 10*i + *(z++) - '0';
138108   *pz = z;
138109   return i;
138110 }
138111 
138112 /*
138113 ** Process statements of the form:
138114 **
138115 **    INSERT INTO table(table) VALUES('merge=A,B');
138116 **
138117 ** A and B are integers that decode to be the number of leaf pages
138118 ** written for the merge, and the minimum number of segments on a level
138119 ** before it will be selected for a merge, respectively.
138120 */
138121 static int fts3DoIncrmerge(
138122   Fts3Table *p,                   /* FTS3 table handle */
138123   const char *zParam              /* Nul-terminated string containing "A,B" */
138124 ){
138125   int rc;
138126   int nMin = (FTS3_MERGE_COUNT / 2);
138127   int nMerge = 0;
138128   const char *z = zParam;
138129 
138130   /* Read the first integer value */
138131   nMerge = fts3Getint(&z);
138132 
138133   /* If the first integer value is followed by a ',',  read the second
138134   ** integer value. */
138135   if( z[0]==',' && z[1]!='\0' ){
138136     z++;
138137     nMin = fts3Getint(&z);
138138   }
138139 
138140   if( z[0]!='\0' || nMin<2 ){
138141     rc = SQLITE_ERROR;
138142   }else{
138143     rc = SQLITE_OK;
138144     if( !p->bHasStat ){
138145       assert( p->bFts4==0 );
138146       sqlite3Fts3CreateStatTable(&rc, p);
138147     }
138148     if( rc==SQLITE_OK ){
138149       rc = sqlite3Fts3Incrmerge(p, nMerge, nMin);
138150     }
138151     sqlite3Fts3SegmentsClose(p);
138152   }
138153   return rc;
138154 }
138155 
138156 /*
138157 ** Process statements of the form:
138158 **
138159 **    INSERT INTO table(table) VALUES('automerge=X');
138160 **
138161 ** where X is an integer.  X==0 means to turn automerge off.  X!=0 means
138162 ** turn it on.  The setting is persistent.
138163 */
138164 static int fts3DoAutoincrmerge(
138165   Fts3Table *p,                   /* FTS3 table handle */
138166   const char *zParam              /* Nul-terminated string containing boolean */
138167 ){
138168   int rc = SQLITE_OK;
138169   sqlite3_stmt *pStmt = 0;
138170   p->bAutoincrmerge = fts3Getint(&zParam)!=0;
138171   if( !p->bHasStat ){
138172     assert( p->bFts4==0 );
138173     sqlite3Fts3CreateStatTable(&rc, p);
138174     if( rc ) return rc;
138175   }
138176   rc = fts3SqlStmt(p, SQL_REPLACE_STAT, &pStmt, 0);
138177   if( rc ) return rc;
138178   sqlite3_bind_int(pStmt, 1, FTS_STAT_AUTOINCRMERGE);
138179   sqlite3_bind_int(pStmt, 2, p->bAutoincrmerge);
138180   sqlite3_step(pStmt);
138181   rc = sqlite3_reset(pStmt);
138182   return rc;
138183 }
138184 
138185 /*
138186 ** Return a 64-bit checksum for the FTS index entry specified by the
138187 ** arguments to this function.
138188 */
138189 static u64 fts3ChecksumEntry(
138190   const char *zTerm,              /* Pointer to buffer containing term */
138191   int nTerm,                      /* Size of zTerm in bytes */
138192   int iLangid,                    /* Language id for current row */
138193   int iIndex,                     /* Index (0..Fts3Table.nIndex-1) */
138194   i64 iDocid,                     /* Docid for current row. */
138195   int iCol,                       /* Column number */
138196   int iPos                        /* Position */
138197 ){
138198   int i;
138199   u64 ret = (u64)iDocid;
138200 
138201   ret += (ret<<3) + iLangid;
138202   ret += (ret<<3) + iIndex;
138203   ret += (ret<<3) + iCol;
138204   ret += (ret<<3) + iPos;
138205   for(i=0; i<nTerm; i++) ret += (ret<<3) + zTerm[i];
138206 
138207   return ret;
138208 }
138209 
138210 /*
138211 ** Return a checksum of all entries in the FTS index that correspond to
138212 ** language id iLangid. The checksum is calculated by XORing the checksums
138213 ** of each individual entry (see fts3ChecksumEntry()) together.
138214 **
138215 ** If successful, the checksum value is returned and *pRc set to SQLITE_OK.
138216 ** Otherwise, if an error occurs, *pRc is set to an SQLite error code. The
138217 ** return value is undefined in this case.
138218 */
138219 static u64 fts3ChecksumIndex(
138220   Fts3Table *p,                   /* FTS3 table handle */
138221   int iLangid,                    /* Language id to return cksum for */
138222   int iIndex,                     /* Index to cksum (0..p->nIndex-1) */
138223   int *pRc                        /* OUT: Return code */
138224 ){
138225   Fts3SegFilter filter;
138226   Fts3MultiSegReader csr;
138227   int rc;
138228   u64 cksum = 0;
138229 
138230   assert( *pRc==SQLITE_OK );
138231 
138232   memset(&filter, 0, sizeof(filter));
138233   memset(&csr, 0, sizeof(csr));
138234   filter.flags =  FTS3_SEGMENT_REQUIRE_POS|FTS3_SEGMENT_IGNORE_EMPTY;
138235   filter.flags |= FTS3_SEGMENT_SCAN;
138236 
138237   rc = sqlite3Fts3SegReaderCursor(
138238       p, iLangid, iIndex, FTS3_SEGCURSOR_ALL, 0, 0, 0, 1,&csr
138239   );
138240   if( rc==SQLITE_OK ){
138241     rc = sqlite3Fts3SegReaderStart(p, &csr, &filter);
138242   }
138243 
138244   if( rc==SQLITE_OK ){
138245     while( SQLITE_ROW==(rc = sqlite3Fts3SegReaderStep(p, &csr)) ){
138246       char *pCsr = csr.aDoclist;
138247       char *pEnd = &pCsr[csr.nDoclist];
138248 
138249       i64 iDocid = 0;
138250       i64 iCol = 0;
138251       i64 iPos = 0;
138252 
138253       pCsr += sqlite3Fts3GetVarint(pCsr, &iDocid);
138254       while( pCsr<pEnd ){
138255         i64 iVal = 0;
138256         pCsr += sqlite3Fts3GetVarint(pCsr, &iVal);
138257         if( pCsr<pEnd ){
138258           if( iVal==0 || iVal==1 ){
138259             iCol = 0;
138260             iPos = 0;
138261             if( iVal ){
138262               pCsr += sqlite3Fts3GetVarint(pCsr, &iCol);
138263             }else{
138264               pCsr += sqlite3Fts3GetVarint(pCsr, &iVal);
138265               iDocid += iVal;
138266             }
138267           }else{
138268             iPos += (iVal - 2);
138269             cksum = cksum ^ fts3ChecksumEntry(
138270                 csr.zTerm, csr.nTerm, iLangid, iIndex, iDocid,
138271                 (int)iCol, (int)iPos
138272             );
138273           }
138274         }
138275       }
138276     }
138277   }
138278   sqlite3Fts3SegReaderFinish(&csr);
138279 
138280   *pRc = rc;
138281   return cksum;
138282 }
138283 
138284 /*
138285 ** Check if the contents of the FTS index match the current contents of the
138286 ** content table. If no error occurs and the contents do match, set *pbOk
138287 ** to true and return SQLITE_OK. Or if the contents do not match, set *pbOk
138288 ** to false before returning.
138289 **
138290 ** If an error occurs (e.g. an OOM or IO error), return an SQLite error 
138291 ** code. The final value of *pbOk is undefined in this case.
138292 */
138293 static int fts3IntegrityCheck(Fts3Table *p, int *pbOk){
138294   int rc = SQLITE_OK;             /* Return code */
138295   u64 cksum1 = 0;                 /* Checksum based on FTS index contents */
138296   u64 cksum2 = 0;                 /* Checksum based on %_content contents */
138297   sqlite3_stmt *pAllLangid = 0;   /* Statement to return all language-ids */
138298 
138299   /* This block calculates the checksum according to the FTS index. */
138300   rc = fts3SqlStmt(p, SQL_SELECT_ALL_LANGID, &pAllLangid, 0);
138301   if( rc==SQLITE_OK ){
138302     int rc2;
138303     sqlite3_bind_int(pAllLangid, 1, p->nIndex);
138304     while( rc==SQLITE_OK && sqlite3_step(pAllLangid)==SQLITE_ROW ){
138305       int iLangid = sqlite3_column_int(pAllLangid, 0);
138306       int i;
138307       for(i=0; i<p->nIndex; i++){
138308         cksum1 = cksum1 ^ fts3ChecksumIndex(p, iLangid, i, &rc);
138309       }
138310     }
138311     rc2 = sqlite3_reset(pAllLangid);
138312     if( rc==SQLITE_OK ) rc = rc2;
138313   }
138314 
138315   /* This block calculates the checksum according to the %_content table */
138316   rc = fts3SqlStmt(p, SQL_SELECT_ALL_LANGID, &pAllLangid, 0);
138317   if( rc==SQLITE_OK ){
138318     sqlite3_tokenizer_module const *pModule = p->pTokenizer->pModule;
138319     sqlite3_stmt *pStmt = 0;
138320     char *zSql;
138321    
138322     zSql = sqlite3_mprintf("SELECT %s" , p->zReadExprlist);
138323     if( !zSql ){
138324       rc = SQLITE_NOMEM;
138325     }else{
138326       rc = sqlite3_prepare_v2(p->db, zSql, -1, &pStmt, 0);
138327       sqlite3_free(zSql);
138328     }
138329 
138330     while( rc==SQLITE_OK && SQLITE_ROW==sqlite3_step(pStmt) ){
138331       i64 iDocid = sqlite3_column_int64(pStmt, 0);
138332       int iLang = langidFromSelect(p, pStmt);
138333       int iCol;
138334 
138335       for(iCol=0; rc==SQLITE_OK && iCol<p->nColumn; iCol++){
138336         const char *zText = (const char *)sqlite3_column_text(pStmt, iCol+1);
138337         int nText = sqlite3_column_bytes(pStmt, iCol+1);
138338         sqlite3_tokenizer_cursor *pT = 0;
138339 
138340         rc = sqlite3Fts3OpenTokenizer(p->pTokenizer, iLang, zText, nText, &pT);
138341         while( rc==SQLITE_OK ){
138342           char const *zToken;       /* Buffer containing token */
138343           int nToken = 0;           /* Number of bytes in token */
138344           int iDum1 = 0, iDum2 = 0; /* Dummy variables */
138345           int iPos = 0;             /* Position of token in zText */
138346 
138347           rc = pModule->xNext(pT, &zToken, &nToken, &iDum1, &iDum2, &iPos);
138348           if( rc==SQLITE_OK ){
138349             int i;
138350             cksum2 = cksum2 ^ fts3ChecksumEntry(
138351                 zToken, nToken, iLang, 0, iDocid, iCol, iPos
138352             );
138353             for(i=1; i<p->nIndex; i++){
138354               if( p->aIndex[i].nPrefix<=nToken ){
138355                 cksum2 = cksum2 ^ fts3ChecksumEntry(
138356                   zToken, p->aIndex[i].nPrefix, iLang, i, iDocid, iCol, iPos
138357                 );
138358               }
138359             }
138360           }
138361         }
138362         if( pT ) pModule->xClose(pT);
138363         if( rc==SQLITE_DONE ) rc = SQLITE_OK;
138364       }
138365     }
138366 
138367     sqlite3_finalize(pStmt);
138368   }
138369 
138370   *pbOk = (cksum1==cksum2);
138371   return rc;
138372 }
138373 
138374 /*
138375 ** Run the integrity-check. If no error occurs and the current contents of
138376 ** the FTS index are correct, return SQLITE_OK. Or, if the contents of the
138377 ** FTS index are incorrect, return SQLITE_CORRUPT_VTAB.
138378 **
138379 ** Or, if an error (e.g. an OOM or IO error) occurs, return an SQLite 
138380 ** error code.
138381 **
138382 ** The integrity-check works as follows. For each token and indexed token
138383 ** prefix in the document set, a 64-bit checksum is calculated (by code
138384 ** in fts3ChecksumEntry()) based on the following:
138385 **
138386 **     + The index number (0 for the main index, 1 for the first prefix
138387 **       index etc.),
138388 **     + The token (or token prefix) text itself, 
138389 **     + The language-id of the row it appears in,
138390 **     + The docid of the row it appears in,
138391 **     + The column it appears in, and
138392 **     + The tokens position within that column.
138393 **
138394 ** The checksums for all entries in the index are XORed together to create
138395 ** a single checksum for the entire index.
138396 **
138397 ** The integrity-check code calculates the same checksum in two ways:
138398 **
138399 **     1. By scanning the contents of the FTS index, and 
138400 **     2. By scanning and tokenizing the content table.
138401 **
138402 ** If the two checksums are identical, the integrity-check is deemed to have
138403 ** passed.
138404 */
138405 static int fts3DoIntegrityCheck(
138406   Fts3Table *p                    /* FTS3 table handle */
138407 ){
138408   int rc;
138409   int bOk = 0;
138410   rc = fts3IntegrityCheck(p, &bOk);
138411   if( rc==SQLITE_OK && bOk==0 ) rc = SQLITE_CORRUPT_VTAB;
138412   return rc;
138413 }
138414 
138415 /*
138416 ** Handle a 'special' INSERT of the form:
138417 **
138418 **   "INSERT INTO tbl(tbl) VALUES(<expr>)"
138419 **
138420 ** Argument pVal contains the result of <expr>. Currently the only 
138421 ** meaningful value to insert is the text 'optimize'.
138422 */
138423 static int fts3SpecialInsert(Fts3Table *p, sqlite3_value *pVal){
138424   int rc;                         /* Return Code */
138425   const char *zVal = (const char *)sqlite3_value_text(pVal);
138426   int nVal = sqlite3_value_bytes(pVal);
138427 
138428   if( !zVal ){
138429     return SQLITE_NOMEM;
138430   }else if( nVal==8 && 0==sqlite3_strnicmp(zVal, "optimize", 8) ){
138431     rc = fts3DoOptimize(p, 0);
138432   }else if( nVal==7 && 0==sqlite3_strnicmp(zVal, "rebuild", 7) ){
138433     rc = fts3DoRebuild(p);
138434   }else if( nVal==15 && 0==sqlite3_strnicmp(zVal, "integrity-check", 15) ){
138435     rc = fts3DoIntegrityCheck(p);
138436   }else if( nVal>6 && 0==sqlite3_strnicmp(zVal, "merge=", 6) ){
138437     rc = fts3DoIncrmerge(p, &zVal[6]);
138438   }else if( nVal>10 && 0==sqlite3_strnicmp(zVal, "automerge=", 10) ){
138439     rc = fts3DoAutoincrmerge(p, &zVal[10]);
138440 #ifdef SQLITE_TEST
138441   }else if( nVal>9 && 0==sqlite3_strnicmp(zVal, "nodesize=", 9) ){
138442     p->nNodeSize = atoi(&zVal[9]);
138443     rc = SQLITE_OK;
138444   }else if( nVal>11 && 0==sqlite3_strnicmp(zVal, "maxpending=", 9) ){
138445     p->nMaxPendingData = atoi(&zVal[11]);
138446     rc = SQLITE_OK;
138447   }else if( nVal>21 && 0==sqlite3_strnicmp(zVal, "test-no-incr-doclist=", 21) ){
138448     p->bNoIncrDoclist = atoi(&zVal[21]);
138449     rc = SQLITE_OK;
138450 #endif
138451   }else{
138452     rc = SQLITE_ERROR;
138453   }
138454 
138455   return rc;
138456 }
138457 
138458 #ifndef SQLITE_DISABLE_FTS4_DEFERRED
138459 /*
138460 ** Delete all cached deferred doclists. Deferred doclists are cached
138461 ** (allocated) by the sqlite3Fts3CacheDeferredDoclists() function.
138462 */
138463 SQLITE_PRIVATE void sqlite3Fts3FreeDeferredDoclists(Fts3Cursor *pCsr){
138464   Fts3DeferredToken *pDef;
138465   for(pDef=pCsr->pDeferred; pDef; pDef=pDef->pNext){
138466     fts3PendingListDelete(pDef->pList);
138467     pDef->pList = 0;
138468   }
138469 }
138470 
138471 /*
138472 ** Free all entries in the pCsr->pDeffered list. Entries are added to 
138473 ** this list using sqlite3Fts3DeferToken().
138474 */
138475 SQLITE_PRIVATE void sqlite3Fts3FreeDeferredTokens(Fts3Cursor *pCsr){
138476   Fts3DeferredToken *pDef;
138477   Fts3DeferredToken *pNext;
138478   for(pDef=pCsr->pDeferred; pDef; pDef=pNext){
138479     pNext = pDef->pNext;
138480     fts3PendingListDelete(pDef->pList);
138481     sqlite3_free(pDef);
138482   }
138483   pCsr->pDeferred = 0;
138484 }
138485 
138486 /*
138487 ** Generate deferred-doclists for all tokens in the pCsr->pDeferred list
138488 ** based on the row that pCsr currently points to.
138489 **
138490 ** A deferred-doclist is like any other doclist with position information
138491 ** included, except that it only contains entries for a single row of the
138492 ** table, not for all rows.
138493 */
138494 SQLITE_PRIVATE int sqlite3Fts3CacheDeferredDoclists(Fts3Cursor *pCsr){
138495   int rc = SQLITE_OK;             /* Return code */
138496   if( pCsr->pDeferred ){
138497     int i;                        /* Used to iterate through table columns */
138498     sqlite3_int64 iDocid;         /* Docid of the row pCsr points to */
138499     Fts3DeferredToken *pDef;      /* Used to iterate through deferred tokens */
138500   
138501     Fts3Table *p = (Fts3Table *)pCsr->base.pVtab;
138502     sqlite3_tokenizer *pT = p->pTokenizer;
138503     sqlite3_tokenizer_module const *pModule = pT->pModule;
138504    
138505     assert( pCsr->isRequireSeek==0 );
138506     iDocid = sqlite3_column_int64(pCsr->pStmt, 0);
138507   
138508     for(i=0; i<p->nColumn && rc==SQLITE_OK; i++){
138509       if( p->abNotindexed[i]==0 ){
138510         const char *zText = (const char *)sqlite3_column_text(pCsr->pStmt, i+1);
138511         sqlite3_tokenizer_cursor *pTC = 0;
138512 
138513         rc = sqlite3Fts3OpenTokenizer(pT, pCsr->iLangid, zText, -1, &pTC);
138514         while( rc==SQLITE_OK ){
138515           char const *zToken;       /* Buffer containing token */
138516           int nToken = 0;           /* Number of bytes in token */
138517           int iDum1 = 0, iDum2 = 0; /* Dummy variables */
138518           int iPos = 0;             /* Position of token in zText */
138519 
138520           rc = pModule->xNext(pTC, &zToken, &nToken, &iDum1, &iDum2, &iPos);
138521           for(pDef=pCsr->pDeferred; pDef && rc==SQLITE_OK; pDef=pDef->pNext){
138522             Fts3PhraseToken *pPT = pDef->pToken;
138523             if( (pDef->iCol>=p->nColumn || pDef->iCol==i)
138524                 && (pPT->bFirst==0 || iPos==0)
138525                 && (pPT->n==nToken || (pPT->isPrefix && pPT->n<nToken))
138526                 && (0==memcmp(zToken, pPT->z, pPT->n))
138527               ){
138528               fts3PendingListAppend(&pDef->pList, iDocid, i, iPos, &rc);
138529             }
138530           }
138531         }
138532         if( pTC ) pModule->xClose(pTC);
138533         if( rc==SQLITE_DONE ) rc = SQLITE_OK;
138534       }
138535     }
138536 
138537     for(pDef=pCsr->pDeferred; pDef && rc==SQLITE_OK; pDef=pDef->pNext){
138538       if( pDef->pList ){
138539         rc = fts3PendingListAppendVarint(&pDef->pList, 0);
138540       }
138541     }
138542   }
138543 
138544   return rc;
138545 }
138546 
138547 SQLITE_PRIVATE int sqlite3Fts3DeferredTokenList(
138548   Fts3DeferredToken *p, 
138549   char **ppData, 
138550   int *pnData
138551 ){
138552   char *pRet;
138553   int nSkip;
138554   sqlite3_int64 dummy;
138555 
138556   *ppData = 0;
138557   *pnData = 0;
138558 
138559   if( p->pList==0 ){
138560     return SQLITE_OK;
138561   }
138562 
138563   pRet = (char *)sqlite3_malloc(p->pList->nData);
138564   if( !pRet ) return SQLITE_NOMEM;
138565 
138566   nSkip = sqlite3Fts3GetVarint(p->pList->aData, &dummy);
138567   *pnData = p->pList->nData - nSkip;
138568   *ppData = pRet;
138569   
138570   memcpy(pRet, &p->pList->aData[nSkip], *pnData);
138571   return SQLITE_OK;
138572 }
138573 
138574 /*
138575 ** Add an entry for token pToken to the pCsr->pDeferred list.
138576 */
138577 SQLITE_PRIVATE int sqlite3Fts3DeferToken(
138578   Fts3Cursor *pCsr,               /* Fts3 table cursor */
138579   Fts3PhraseToken *pToken,        /* Token to defer */
138580   int iCol                        /* Column that token must appear in (or -1) */
138581 ){
138582   Fts3DeferredToken *pDeferred;
138583   pDeferred = sqlite3_malloc(sizeof(*pDeferred));
138584   if( !pDeferred ){
138585     return SQLITE_NOMEM;
138586   }
138587   memset(pDeferred, 0, sizeof(*pDeferred));
138588   pDeferred->pToken = pToken;
138589   pDeferred->pNext = pCsr->pDeferred; 
138590   pDeferred->iCol = iCol;
138591   pCsr->pDeferred = pDeferred;
138592 
138593   assert( pToken->pDeferred==0 );
138594   pToken->pDeferred = pDeferred;
138595 
138596   return SQLITE_OK;
138597 }
138598 #endif
138599 
138600 /*
138601 ** SQLite value pRowid contains the rowid of a row that may or may not be
138602 ** present in the FTS3 table. If it is, delete it and adjust the contents
138603 ** of subsiduary data structures accordingly.
138604 */
138605 static int fts3DeleteByRowid(
138606   Fts3Table *p, 
138607   sqlite3_value *pRowid, 
138608   int *pnChng,                    /* IN/OUT: Decrement if row is deleted */
138609   u32 *aSzDel
138610 ){
138611   int rc = SQLITE_OK;             /* Return code */
138612   int bFound = 0;                 /* True if *pRowid really is in the table */
138613 
138614   fts3DeleteTerms(&rc, p, pRowid, aSzDel, &bFound);
138615   if( bFound && rc==SQLITE_OK ){
138616     int isEmpty = 0;              /* Deleting *pRowid leaves the table empty */
138617     rc = fts3IsEmpty(p, pRowid, &isEmpty);
138618     if( rc==SQLITE_OK ){
138619       if( isEmpty ){
138620         /* Deleting this row means the whole table is empty. In this case
138621         ** delete the contents of all three tables and throw away any
138622         ** data in the pendingTerms hash table.  */
138623         rc = fts3DeleteAll(p, 1);
138624         *pnChng = 0;
138625         memset(aSzDel, 0, sizeof(u32) * (p->nColumn+1) * 2);
138626       }else{
138627         *pnChng = *pnChng - 1;
138628         if( p->zContentTbl==0 ){
138629           fts3SqlExec(&rc, p, SQL_DELETE_CONTENT, &pRowid);
138630         }
138631         if( p->bHasDocsize ){
138632           fts3SqlExec(&rc, p, SQL_DELETE_DOCSIZE, &pRowid);
138633         }
138634       }
138635     }
138636   }
138637 
138638   return rc;
138639 }
138640 
138641 /*
138642 ** This function does the work for the xUpdate method of FTS3 virtual
138643 ** tables. The schema of the virtual table being:
138644 **
138645 **     CREATE TABLE <table name>( 
138646 **       <user columns>,
138647 **       <table name> HIDDEN, 
138648 **       docid HIDDEN, 
138649 **       <langid> HIDDEN
138650 **     );
138651 **
138652 ** 
138653 */
138654 SQLITE_PRIVATE int sqlite3Fts3UpdateMethod(
138655   sqlite3_vtab *pVtab,            /* FTS3 vtab object */
138656   int nArg,                       /* Size of argument array */
138657   sqlite3_value **apVal,          /* Array of arguments */
138658   sqlite_int64 *pRowid            /* OUT: The affected (or effected) rowid */
138659 ){
138660   Fts3Table *p = (Fts3Table *)pVtab;
138661   int rc = SQLITE_OK;             /* Return Code */
138662   int isRemove = 0;               /* True for an UPDATE or DELETE */
138663   u32 *aSzIns = 0;                /* Sizes of inserted documents */
138664   u32 *aSzDel = 0;                /* Sizes of deleted documents */
138665   int nChng = 0;                  /* Net change in number of documents */
138666   int bInsertDone = 0;
138667 
138668   assert( p->pSegments==0 );
138669   assert( 
138670       nArg==1                     /* DELETE operations */
138671    || nArg==(2 + p->nColumn + 3)  /* INSERT or UPDATE operations */
138672   );
138673 
138674   /* Check for a "special" INSERT operation. One of the form:
138675   **
138676   **   INSERT INTO xyz(xyz) VALUES('command');
138677   */
138678   if( nArg>1 
138679    && sqlite3_value_type(apVal[0])==SQLITE_NULL 
138680    && sqlite3_value_type(apVal[p->nColumn+2])!=SQLITE_NULL 
138681   ){
138682     rc = fts3SpecialInsert(p, apVal[p->nColumn+2]);
138683     goto update_out;
138684   }
138685 
138686   if( nArg>1 && sqlite3_value_int(apVal[2 + p->nColumn + 2])<0 ){
138687     rc = SQLITE_CONSTRAINT;
138688     goto update_out;
138689   }
138690 
138691   /* Allocate space to hold the change in document sizes */
138692   aSzDel = sqlite3_malloc( sizeof(aSzDel[0])*(p->nColumn+1)*2 );
138693   if( aSzDel==0 ){
138694     rc = SQLITE_NOMEM;
138695     goto update_out;
138696   }
138697   aSzIns = &aSzDel[p->nColumn+1];
138698   memset(aSzDel, 0, sizeof(aSzDel[0])*(p->nColumn+1)*2);
138699 
138700   rc = fts3Writelock(p);
138701   if( rc!=SQLITE_OK ) goto update_out;
138702 
138703   /* If this is an INSERT operation, or an UPDATE that modifies the rowid
138704   ** value, then this operation requires constraint handling.
138705   **
138706   ** If the on-conflict mode is REPLACE, this means that the existing row
138707   ** should be deleted from the database before inserting the new row. Or,
138708   ** if the on-conflict mode is other than REPLACE, then this method must
138709   ** detect the conflict and return SQLITE_CONSTRAINT before beginning to
138710   ** modify the database file.
138711   */
138712   if( nArg>1 && p->zContentTbl==0 ){
138713     /* Find the value object that holds the new rowid value. */
138714     sqlite3_value *pNewRowid = apVal[3+p->nColumn];
138715     if( sqlite3_value_type(pNewRowid)==SQLITE_NULL ){
138716       pNewRowid = apVal[1];
138717     }
138718 
138719     if( sqlite3_value_type(pNewRowid)!=SQLITE_NULL && ( 
138720         sqlite3_value_type(apVal[0])==SQLITE_NULL
138721      || sqlite3_value_int64(apVal[0])!=sqlite3_value_int64(pNewRowid)
138722     )){
138723       /* The new rowid is not NULL (in this case the rowid will be
138724       ** automatically assigned and there is no chance of a conflict), and 
138725       ** the statement is either an INSERT or an UPDATE that modifies the
138726       ** rowid column. So if the conflict mode is REPLACE, then delete any
138727       ** existing row with rowid=pNewRowid. 
138728       **
138729       ** Or, if the conflict mode is not REPLACE, insert the new record into 
138730       ** the %_content table. If we hit the duplicate rowid constraint (or any
138731       ** other error) while doing so, return immediately.
138732       **
138733       ** This branch may also run if pNewRowid contains a value that cannot
138734       ** be losslessly converted to an integer. In this case, the eventual 
138735       ** call to fts3InsertData() (either just below or further on in this
138736       ** function) will return SQLITE_MISMATCH. If fts3DeleteByRowid is 
138737       ** invoked, it will delete zero rows (since no row will have
138738       ** docid=$pNewRowid if $pNewRowid is not an integer value).
138739       */
138740       if( sqlite3_vtab_on_conflict(p->db)==SQLITE_REPLACE ){
138741         rc = fts3DeleteByRowid(p, pNewRowid, &nChng, aSzDel);
138742       }else{
138743         rc = fts3InsertData(p, apVal, pRowid);
138744         bInsertDone = 1;
138745       }
138746     }
138747   }
138748   if( rc!=SQLITE_OK ){
138749     goto update_out;
138750   }
138751 
138752   /* If this is a DELETE or UPDATE operation, remove the old record. */
138753   if( sqlite3_value_type(apVal[0])!=SQLITE_NULL ){
138754     assert( sqlite3_value_type(apVal[0])==SQLITE_INTEGER );
138755     rc = fts3DeleteByRowid(p, apVal[0], &nChng, aSzDel);
138756     isRemove = 1;
138757   }
138758   
138759   /* If this is an INSERT or UPDATE operation, insert the new record. */
138760   if( nArg>1 && rc==SQLITE_OK ){
138761     int iLangid = sqlite3_value_int(apVal[2 + p->nColumn + 2]);
138762     if( bInsertDone==0 ){
138763       rc = fts3InsertData(p, apVal, pRowid);
138764       if( rc==SQLITE_CONSTRAINT && p->zContentTbl==0 ){
138765         rc = FTS_CORRUPT_VTAB;
138766       }
138767     }
138768     if( rc==SQLITE_OK && (!isRemove || *pRowid!=p->iPrevDocid ) ){
138769       rc = fts3PendingTermsDocid(p, iLangid, *pRowid);
138770     }
138771     if( rc==SQLITE_OK ){
138772       assert( p->iPrevDocid==*pRowid );
138773       rc = fts3InsertTerms(p, iLangid, apVal, aSzIns);
138774     }
138775     if( p->bHasDocsize ){
138776       fts3InsertDocsize(&rc, p, aSzIns);
138777     }
138778     nChng++;
138779   }
138780 
138781   if( p->bFts4 ){
138782     fts3UpdateDocTotals(&rc, p, aSzIns, aSzDel, nChng);
138783   }
138784 
138785  update_out:
138786   sqlite3_free(aSzDel);
138787   sqlite3Fts3SegmentsClose(p);
138788   return rc;
138789 }
138790 
138791 /* 
138792 ** Flush any data in the pending-terms hash table to disk. If successful,
138793 ** merge all segments in the database (including the new segment, if 
138794 ** there was any data to flush) into a single segment. 
138795 */
138796 SQLITE_PRIVATE int sqlite3Fts3Optimize(Fts3Table *p){
138797   int rc;
138798   rc = sqlite3_exec(p->db, "SAVEPOINT fts3", 0, 0, 0);
138799   if( rc==SQLITE_OK ){
138800     rc = fts3DoOptimize(p, 1);
138801     if( rc==SQLITE_OK || rc==SQLITE_DONE ){
138802       int rc2 = sqlite3_exec(p->db, "RELEASE fts3", 0, 0, 0);
138803       if( rc2!=SQLITE_OK ) rc = rc2;
138804     }else{
138805       sqlite3_exec(p->db, "ROLLBACK TO fts3", 0, 0, 0);
138806       sqlite3_exec(p->db, "RELEASE fts3", 0, 0, 0);
138807     }
138808   }
138809   sqlite3Fts3SegmentsClose(p);
138810   return rc;
138811 }
138812 
138813 #endif
138814 
138815 /************** End of fts3_write.c ******************************************/
138816 /************** Begin file fts3_snippet.c ************************************/
138817 /*
138818 ** 2009 Oct 23
138819 **
138820 ** The author disclaims copyright to this source code.  In place of
138821 ** a legal notice, here is a blessing:
138822 **
138823 **    May you do good and not evil.
138824 **    May you find forgiveness for yourself and forgive others.
138825 **    May you share freely, never taking more than you give.
138826 **
138827 ******************************************************************************
138828 */
138829 
138830 #if !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_FTS3)
138831 
138832 /* #include <string.h> */
138833 /* #include <assert.h> */
138834 
138835 /*
138836 ** Characters that may appear in the second argument to matchinfo().
138837 */
138838 #define FTS3_MATCHINFO_NPHRASE   'p'        /* 1 value */
138839 #define FTS3_MATCHINFO_NCOL      'c'        /* 1 value */
138840 #define FTS3_MATCHINFO_NDOC      'n'        /* 1 value */
138841 #define FTS3_MATCHINFO_AVGLENGTH 'a'        /* nCol values */
138842 #define FTS3_MATCHINFO_LENGTH    'l'        /* nCol values */
138843 #define FTS3_MATCHINFO_LCS       's'        /* nCol values */
138844 #define FTS3_MATCHINFO_HITS      'x'        /* 3*nCol*nPhrase values */
138845 
138846 /*
138847 ** The default value for the second argument to matchinfo(). 
138848 */
138849 #define FTS3_MATCHINFO_DEFAULT   "pcx"
138850 
138851 
138852 /*
138853 ** Used as an fts3ExprIterate() context when loading phrase doclists to
138854 ** Fts3Expr.aDoclist[]/nDoclist.
138855 */
138856 typedef struct LoadDoclistCtx LoadDoclistCtx;
138857 struct LoadDoclistCtx {
138858   Fts3Cursor *pCsr;               /* FTS3 Cursor */
138859   int nPhrase;                    /* Number of phrases seen so far */
138860   int nToken;                     /* Number of tokens seen so far */
138861 };
138862 
138863 /*
138864 ** The following types are used as part of the implementation of the 
138865 ** fts3BestSnippet() routine.
138866 */
138867 typedef struct SnippetIter SnippetIter;
138868 typedef struct SnippetPhrase SnippetPhrase;
138869 typedef struct SnippetFragment SnippetFragment;
138870 
138871 struct SnippetIter {
138872   Fts3Cursor *pCsr;               /* Cursor snippet is being generated from */
138873   int iCol;                       /* Extract snippet from this column */
138874   int nSnippet;                   /* Requested snippet length (in tokens) */
138875   int nPhrase;                    /* Number of phrases in query */
138876   SnippetPhrase *aPhrase;         /* Array of size nPhrase */
138877   int iCurrent;                   /* First token of current snippet */
138878 };
138879 
138880 struct SnippetPhrase {
138881   int nToken;                     /* Number of tokens in phrase */
138882   char *pList;                    /* Pointer to start of phrase position list */
138883   int iHead;                      /* Next value in position list */
138884   char *pHead;                    /* Position list data following iHead */
138885   int iTail;                      /* Next value in trailing position list */
138886   char *pTail;                    /* Position list data following iTail */
138887 };
138888 
138889 struct SnippetFragment {
138890   int iCol;                       /* Column snippet is extracted from */
138891   int iPos;                       /* Index of first token in snippet */
138892   u64 covered;                    /* Mask of query phrases covered */
138893   u64 hlmask;                     /* Mask of snippet terms to highlight */
138894 };
138895 
138896 /*
138897 ** This type is used as an fts3ExprIterate() context object while 
138898 ** accumulating the data returned by the matchinfo() function.
138899 */
138900 typedef struct MatchInfo MatchInfo;
138901 struct MatchInfo {
138902   Fts3Cursor *pCursor;            /* FTS3 Cursor */
138903   int nCol;                       /* Number of columns in table */
138904   int nPhrase;                    /* Number of matchable phrases in query */
138905   sqlite3_int64 nDoc;             /* Number of docs in database */
138906   u32 *aMatchinfo;                /* Pre-allocated buffer */
138907 };
138908 
138909 
138910 
138911 /*
138912 ** The snippet() and offsets() functions both return text values. An instance
138913 ** of the following structure is used to accumulate those values while the
138914 ** functions are running. See fts3StringAppend() for details.
138915 */
138916 typedef struct StrBuffer StrBuffer;
138917 struct StrBuffer {
138918   char *z;                        /* Pointer to buffer containing string */
138919   int n;                          /* Length of z in bytes (excl. nul-term) */
138920   int nAlloc;                     /* Allocated size of buffer z in bytes */
138921 };
138922 
138923 
138924 /*
138925 ** This function is used to help iterate through a position-list. A position
138926 ** list is a list of unique integers, sorted from smallest to largest. Each
138927 ** element of the list is represented by an FTS3 varint that takes the value
138928 ** of the difference between the current element and the previous one plus
138929 ** two. For example, to store the position-list:
138930 **
138931 **     4 9 113
138932 **
138933 ** the three varints:
138934 **
138935 **     6 7 106
138936 **
138937 ** are encoded.
138938 **
138939 ** When this function is called, *pp points to the start of an element of
138940 ** the list. *piPos contains the value of the previous entry in the list.
138941 ** After it returns, *piPos contains the value of the next element of the
138942 ** list and *pp is advanced to the following varint.
138943 */
138944 static void fts3GetDeltaPosition(char **pp, int *piPos){
138945   int iVal;
138946   *pp += fts3GetVarint32(*pp, &iVal);
138947   *piPos += (iVal-2);
138948 }
138949 
138950 /*
138951 ** Helper function for fts3ExprIterate() (see below).
138952 */
138953 static int fts3ExprIterate2(
138954   Fts3Expr *pExpr,                /* Expression to iterate phrases of */
138955   int *piPhrase,                  /* Pointer to phrase counter */
138956   int (*x)(Fts3Expr*,int,void*),  /* Callback function to invoke for phrases */
138957   void *pCtx                      /* Second argument to pass to callback */
138958 ){
138959   int rc;                         /* Return code */
138960   int eType = pExpr->eType;       /* Type of expression node pExpr */
138961 
138962   if( eType!=FTSQUERY_PHRASE ){
138963     assert( pExpr->pLeft && pExpr->pRight );
138964     rc = fts3ExprIterate2(pExpr->pLeft, piPhrase, x, pCtx);
138965     if( rc==SQLITE_OK && eType!=FTSQUERY_NOT ){
138966       rc = fts3ExprIterate2(pExpr->pRight, piPhrase, x, pCtx);
138967     }
138968   }else{
138969     rc = x(pExpr, *piPhrase, pCtx);
138970     (*piPhrase)++;
138971   }
138972   return rc;
138973 }
138974 
138975 /*
138976 ** Iterate through all phrase nodes in an FTS3 query, except those that
138977 ** are part of a sub-tree that is the right-hand-side of a NOT operator.
138978 ** For each phrase node found, the supplied callback function is invoked.
138979 **
138980 ** If the callback function returns anything other than SQLITE_OK, 
138981 ** the iteration is abandoned and the error code returned immediately.
138982 ** Otherwise, SQLITE_OK is returned after a callback has been made for
138983 ** all eligible phrase nodes.
138984 */
138985 static int fts3ExprIterate(
138986   Fts3Expr *pExpr,                /* Expression to iterate phrases of */
138987   int (*x)(Fts3Expr*,int,void*),  /* Callback function to invoke for phrases */
138988   void *pCtx                      /* Second argument to pass to callback */
138989 ){
138990   int iPhrase = 0;                /* Variable used as the phrase counter */
138991   return fts3ExprIterate2(pExpr, &iPhrase, x, pCtx);
138992 }
138993 
138994 /*
138995 ** This is an fts3ExprIterate() callback used while loading the doclists
138996 ** for each phrase into Fts3Expr.aDoclist[]/nDoclist. See also
138997 ** fts3ExprLoadDoclists().
138998 */
138999 static int fts3ExprLoadDoclistsCb(Fts3Expr *pExpr, int iPhrase, void *ctx){
139000   int rc = SQLITE_OK;
139001   Fts3Phrase *pPhrase = pExpr->pPhrase;
139002   LoadDoclistCtx *p = (LoadDoclistCtx *)ctx;
139003 
139004   UNUSED_PARAMETER(iPhrase);
139005 
139006   p->nPhrase++;
139007   p->nToken += pPhrase->nToken;
139008 
139009   return rc;
139010 }
139011 
139012 /*
139013 ** Load the doclists for each phrase in the query associated with FTS3 cursor
139014 ** pCsr. 
139015 **
139016 ** If pnPhrase is not NULL, then *pnPhrase is set to the number of matchable 
139017 ** phrases in the expression (all phrases except those directly or 
139018 ** indirectly descended from the right-hand-side of a NOT operator). If 
139019 ** pnToken is not NULL, then it is set to the number of tokens in all
139020 ** matchable phrases of the expression.
139021 */
139022 static int fts3ExprLoadDoclists(
139023   Fts3Cursor *pCsr,               /* Fts3 cursor for current query */
139024   int *pnPhrase,                  /* OUT: Number of phrases in query */
139025   int *pnToken                    /* OUT: Number of tokens in query */
139026 ){
139027   int rc;                         /* Return Code */
139028   LoadDoclistCtx sCtx = {0,0,0};  /* Context for fts3ExprIterate() */
139029   sCtx.pCsr = pCsr;
139030   rc = fts3ExprIterate(pCsr->pExpr, fts3ExprLoadDoclistsCb, (void *)&sCtx);
139031   if( pnPhrase ) *pnPhrase = sCtx.nPhrase;
139032   if( pnToken ) *pnToken = sCtx.nToken;
139033   return rc;
139034 }
139035 
139036 static int fts3ExprPhraseCountCb(Fts3Expr *pExpr, int iPhrase, void *ctx){
139037   (*(int *)ctx)++;
139038   UNUSED_PARAMETER(pExpr);
139039   UNUSED_PARAMETER(iPhrase);
139040   return SQLITE_OK;
139041 }
139042 static int fts3ExprPhraseCount(Fts3Expr *pExpr){
139043   int nPhrase = 0;
139044   (void)fts3ExprIterate(pExpr, fts3ExprPhraseCountCb, (void *)&nPhrase);
139045   return nPhrase;
139046 }
139047 
139048 /*
139049 ** Advance the position list iterator specified by the first two 
139050 ** arguments so that it points to the first element with a value greater
139051 ** than or equal to parameter iNext.
139052 */
139053 static void fts3SnippetAdvance(char **ppIter, int *piIter, int iNext){
139054   char *pIter = *ppIter;
139055   if( pIter ){
139056     int iIter = *piIter;
139057 
139058     while( iIter<iNext ){
139059       if( 0==(*pIter & 0xFE) ){
139060         iIter = -1;
139061         pIter = 0;
139062         break;
139063       }
139064       fts3GetDeltaPosition(&pIter, &iIter);
139065     }
139066 
139067     *piIter = iIter;
139068     *ppIter = pIter;
139069   }
139070 }
139071 
139072 /*
139073 ** Advance the snippet iterator to the next candidate snippet.
139074 */
139075 static int fts3SnippetNextCandidate(SnippetIter *pIter){
139076   int i;                          /* Loop counter */
139077 
139078   if( pIter->iCurrent<0 ){
139079     /* The SnippetIter object has just been initialized. The first snippet
139080     ** candidate always starts at offset 0 (even if this candidate has a
139081     ** score of 0.0).
139082     */
139083     pIter->iCurrent = 0;
139084 
139085     /* Advance the 'head' iterator of each phrase to the first offset that
139086     ** is greater than or equal to (iNext+nSnippet).
139087     */
139088     for(i=0; i<pIter->nPhrase; i++){
139089       SnippetPhrase *pPhrase = &pIter->aPhrase[i];
139090       fts3SnippetAdvance(&pPhrase->pHead, &pPhrase->iHead, pIter->nSnippet);
139091     }
139092   }else{
139093     int iStart;
139094     int iEnd = 0x7FFFFFFF;
139095 
139096     for(i=0; i<pIter->nPhrase; i++){
139097       SnippetPhrase *pPhrase = &pIter->aPhrase[i];
139098       if( pPhrase->pHead && pPhrase->iHead<iEnd ){
139099         iEnd = pPhrase->iHead;
139100       }
139101     }
139102     if( iEnd==0x7FFFFFFF ){
139103       return 1;
139104     }
139105 
139106     pIter->iCurrent = iStart = iEnd - pIter->nSnippet + 1;
139107     for(i=0; i<pIter->nPhrase; i++){
139108       SnippetPhrase *pPhrase = &pIter->aPhrase[i];
139109       fts3SnippetAdvance(&pPhrase->pHead, &pPhrase->iHead, iEnd+1);
139110       fts3SnippetAdvance(&pPhrase->pTail, &pPhrase->iTail, iStart);
139111     }
139112   }
139113 
139114   return 0;
139115 }
139116 
139117 /*
139118 ** Retrieve information about the current candidate snippet of snippet 
139119 ** iterator pIter.
139120 */
139121 static void fts3SnippetDetails(
139122   SnippetIter *pIter,             /* Snippet iterator */
139123   u64 mCovered,                   /* Bitmask of phrases already covered */
139124   int *piToken,                   /* OUT: First token of proposed snippet */
139125   int *piScore,                   /* OUT: "Score" for this snippet */
139126   u64 *pmCover,                   /* OUT: Bitmask of phrases covered */
139127   u64 *pmHighlight                /* OUT: Bitmask of terms to highlight */
139128 ){
139129   int iStart = pIter->iCurrent;   /* First token of snippet */
139130   int iScore = 0;                 /* Score of this snippet */
139131   int i;                          /* Loop counter */
139132   u64 mCover = 0;                 /* Mask of phrases covered by this snippet */
139133   u64 mHighlight = 0;             /* Mask of tokens to highlight in snippet */
139134 
139135   for(i=0; i<pIter->nPhrase; i++){
139136     SnippetPhrase *pPhrase = &pIter->aPhrase[i];
139137     if( pPhrase->pTail ){
139138       char *pCsr = pPhrase->pTail;
139139       int iCsr = pPhrase->iTail;
139140 
139141       while( iCsr<(iStart+pIter->nSnippet) ){
139142         int j;
139143         u64 mPhrase = (u64)1 << i;
139144         u64 mPos = (u64)1 << (iCsr - iStart);
139145         assert( iCsr>=iStart );
139146         if( (mCover|mCovered)&mPhrase ){
139147           iScore++;
139148         }else{
139149           iScore += 1000;
139150         }
139151         mCover |= mPhrase;
139152 
139153         for(j=0; j<pPhrase->nToken; j++){
139154           mHighlight |= (mPos>>j);
139155         }
139156 
139157         if( 0==(*pCsr & 0x0FE) ) break;
139158         fts3GetDeltaPosition(&pCsr, &iCsr);
139159       }
139160     }
139161   }
139162 
139163   /* Set the output variables before returning. */
139164   *piToken = iStart;
139165   *piScore = iScore;
139166   *pmCover = mCover;
139167   *pmHighlight = mHighlight;
139168 }
139169 
139170 /*
139171 ** This function is an fts3ExprIterate() callback used by fts3BestSnippet().
139172 ** Each invocation populates an element of the SnippetIter.aPhrase[] array.
139173 */
139174 static int fts3SnippetFindPositions(Fts3Expr *pExpr, int iPhrase, void *ctx){
139175   SnippetIter *p = (SnippetIter *)ctx;
139176   SnippetPhrase *pPhrase = &p->aPhrase[iPhrase];
139177   char *pCsr;
139178   int rc;
139179 
139180   pPhrase->nToken = pExpr->pPhrase->nToken;
139181   rc = sqlite3Fts3EvalPhrasePoslist(p->pCsr, pExpr, p->iCol, &pCsr);
139182   assert( rc==SQLITE_OK || pCsr==0 );
139183   if( pCsr ){
139184     int iFirst = 0;
139185     pPhrase->pList = pCsr;
139186     fts3GetDeltaPosition(&pCsr, &iFirst);
139187     assert( iFirst>=0 );
139188     pPhrase->pHead = pCsr;
139189     pPhrase->pTail = pCsr;
139190     pPhrase->iHead = iFirst;
139191     pPhrase->iTail = iFirst;
139192   }else{
139193     assert( rc!=SQLITE_OK || (
139194        pPhrase->pList==0 && pPhrase->pHead==0 && pPhrase->pTail==0 
139195     ));
139196   }
139197 
139198   return rc;
139199 }
139200 
139201 /*
139202 ** Select the fragment of text consisting of nFragment contiguous tokens 
139203 ** from column iCol that represent the "best" snippet. The best snippet
139204 ** is the snippet with the highest score, where scores are calculated
139205 ** by adding:
139206 **
139207 **   (a) +1 point for each occurrence of a matchable phrase in the snippet.
139208 **
139209 **   (b) +1000 points for the first occurrence of each matchable phrase in 
139210 **       the snippet for which the corresponding mCovered bit is not set.
139211 **
139212 ** The selected snippet parameters are stored in structure *pFragment before
139213 ** returning. The score of the selected snippet is stored in *piScore
139214 ** before returning.
139215 */
139216 static int fts3BestSnippet(
139217   int nSnippet,                   /* Desired snippet length */
139218   Fts3Cursor *pCsr,               /* Cursor to create snippet for */
139219   int iCol,                       /* Index of column to create snippet from */
139220   u64 mCovered,                   /* Mask of phrases already covered */
139221   u64 *pmSeen,                    /* IN/OUT: Mask of phrases seen */
139222   SnippetFragment *pFragment,     /* OUT: Best snippet found */
139223   int *piScore                    /* OUT: Score of snippet pFragment */
139224 ){
139225   int rc;                         /* Return Code */
139226   int nList;                      /* Number of phrases in expression */
139227   SnippetIter sIter;              /* Iterates through snippet candidates */
139228   int nByte;                      /* Number of bytes of space to allocate */
139229   int iBestScore = -1;            /* Best snippet score found so far */
139230   int i;                          /* Loop counter */
139231 
139232   memset(&sIter, 0, sizeof(sIter));
139233 
139234   /* Iterate through the phrases in the expression to count them. The same
139235   ** callback makes sure the doclists are loaded for each phrase.
139236   */
139237   rc = fts3ExprLoadDoclists(pCsr, &nList, 0);
139238   if( rc!=SQLITE_OK ){
139239     return rc;
139240   }
139241 
139242   /* Now that it is known how many phrases there are, allocate and zero
139243   ** the required space using malloc().
139244   */
139245   nByte = sizeof(SnippetPhrase) * nList;
139246   sIter.aPhrase = (SnippetPhrase *)sqlite3_malloc(nByte);
139247   if( !sIter.aPhrase ){
139248     return SQLITE_NOMEM;
139249   }
139250   memset(sIter.aPhrase, 0, nByte);
139251 
139252   /* Initialize the contents of the SnippetIter object. Then iterate through
139253   ** the set of phrases in the expression to populate the aPhrase[] array.
139254   */
139255   sIter.pCsr = pCsr;
139256   sIter.iCol = iCol;
139257   sIter.nSnippet = nSnippet;
139258   sIter.nPhrase = nList;
139259   sIter.iCurrent = -1;
139260   (void)fts3ExprIterate(pCsr->pExpr, fts3SnippetFindPositions, (void *)&sIter);
139261 
139262   /* Set the *pmSeen output variable. */
139263   for(i=0; i<nList; i++){
139264     if( sIter.aPhrase[i].pHead ){
139265       *pmSeen |= (u64)1 << i;
139266     }
139267   }
139268 
139269   /* Loop through all candidate snippets. Store the best snippet in 
139270   ** *pFragment. Store its associated 'score' in iBestScore.
139271   */
139272   pFragment->iCol = iCol;
139273   while( !fts3SnippetNextCandidate(&sIter) ){
139274     int iPos;
139275     int iScore;
139276     u64 mCover;
139277     u64 mHighlight;
139278     fts3SnippetDetails(&sIter, mCovered, &iPos, &iScore, &mCover, &mHighlight);
139279     assert( iScore>=0 );
139280     if( iScore>iBestScore ){
139281       pFragment->iPos = iPos;
139282       pFragment->hlmask = mHighlight;
139283       pFragment->covered = mCover;
139284       iBestScore = iScore;
139285     }
139286   }
139287 
139288   sqlite3_free(sIter.aPhrase);
139289   *piScore = iBestScore;
139290   return SQLITE_OK;
139291 }
139292 
139293 
139294 /*
139295 ** Append a string to the string-buffer passed as the first argument.
139296 **
139297 ** If nAppend is negative, then the length of the string zAppend is
139298 ** determined using strlen().
139299 */
139300 static int fts3StringAppend(
139301   StrBuffer *pStr,                /* Buffer to append to */
139302   const char *zAppend,            /* Pointer to data to append to buffer */
139303   int nAppend                     /* Size of zAppend in bytes (or -1) */
139304 ){
139305   if( nAppend<0 ){
139306     nAppend = (int)strlen(zAppend);
139307   }
139308 
139309   /* If there is insufficient space allocated at StrBuffer.z, use realloc()
139310   ** to grow the buffer until so that it is big enough to accomadate the
139311   ** appended data.
139312   */
139313   if( pStr->n+nAppend+1>=pStr->nAlloc ){
139314     int nAlloc = pStr->nAlloc+nAppend+100;
139315     char *zNew = sqlite3_realloc(pStr->z, nAlloc);
139316     if( !zNew ){
139317       return SQLITE_NOMEM;
139318     }
139319     pStr->z = zNew;
139320     pStr->nAlloc = nAlloc;
139321   }
139322   assert( pStr->z!=0 && (pStr->nAlloc >= pStr->n+nAppend+1) );
139323 
139324   /* Append the data to the string buffer. */
139325   memcpy(&pStr->z[pStr->n], zAppend, nAppend);
139326   pStr->n += nAppend;
139327   pStr->z[pStr->n] = '\0';
139328 
139329   return SQLITE_OK;
139330 }
139331 
139332 /*
139333 ** The fts3BestSnippet() function often selects snippets that end with a
139334 ** query term. That is, the final term of the snippet is always a term
139335 ** that requires highlighting. For example, if 'X' is a highlighted term
139336 ** and '.' is a non-highlighted term, BestSnippet() may select:
139337 **
139338 **     ........X.....X
139339 **
139340 ** This function "shifts" the beginning of the snippet forward in the 
139341 ** document so that there are approximately the same number of 
139342 ** non-highlighted terms to the right of the final highlighted term as there
139343 ** are to the left of the first highlighted term. For example, to this:
139344 **
139345 **     ....X.....X....
139346 **
139347 ** This is done as part of extracting the snippet text, not when selecting
139348 ** the snippet. Snippet selection is done based on doclists only, so there
139349 ** is no way for fts3BestSnippet() to know whether or not the document 
139350 ** actually contains terms that follow the final highlighted term. 
139351 */
139352 static int fts3SnippetShift(
139353   Fts3Table *pTab,                /* FTS3 table snippet comes from */
139354   int iLangid,                    /* Language id to use in tokenizing */
139355   int nSnippet,                   /* Number of tokens desired for snippet */
139356   const char *zDoc,               /* Document text to extract snippet from */
139357   int nDoc,                       /* Size of buffer zDoc in bytes */
139358   int *piPos,                     /* IN/OUT: First token of snippet */
139359   u64 *pHlmask                    /* IN/OUT: Mask of tokens to highlight */
139360 ){
139361   u64 hlmask = *pHlmask;          /* Local copy of initial highlight-mask */
139362 
139363   if( hlmask ){
139364     int nLeft;                    /* Tokens to the left of first highlight */
139365     int nRight;                   /* Tokens to the right of last highlight */
139366     int nDesired;                 /* Ideal number of tokens to shift forward */
139367 
139368     for(nLeft=0; !(hlmask & ((u64)1 << nLeft)); nLeft++);
139369     for(nRight=0; !(hlmask & ((u64)1 << (nSnippet-1-nRight))); nRight++);
139370     nDesired = (nLeft-nRight)/2;
139371 
139372     /* Ideally, the start of the snippet should be pushed forward in the
139373     ** document nDesired tokens. This block checks if there are actually
139374     ** nDesired tokens to the right of the snippet. If so, *piPos and
139375     ** *pHlMask are updated to shift the snippet nDesired tokens to the
139376     ** right. Otherwise, the snippet is shifted by the number of tokens
139377     ** available.
139378     */
139379     if( nDesired>0 ){
139380       int nShift;                 /* Number of tokens to shift snippet by */
139381       int iCurrent = 0;           /* Token counter */
139382       int rc;                     /* Return Code */
139383       sqlite3_tokenizer_module *pMod;
139384       sqlite3_tokenizer_cursor *pC;
139385       pMod = (sqlite3_tokenizer_module *)pTab->pTokenizer->pModule;
139386 
139387       /* Open a cursor on zDoc/nDoc. Check if there are (nSnippet+nDesired)
139388       ** or more tokens in zDoc/nDoc.
139389       */
139390       rc = sqlite3Fts3OpenTokenizer(pTab->pTokenizer, iLangid, zDoc, nDoc, &pC);
139391       if( rc!=SQLITE_OK ){
139392         return rc;
139393       }
139394       while( rc==SQLITE_OK && iCurrent<(nSnippet+nDesired) ){
139395         const char *ZDUMMY; int DUMMY1 = 0, DUMMY2 = 0, DUMMY3 = 0;
139396         rc = pMod->xNext(pC, &ZDUMMY, &DUMMY1, &DUMMY2, &DUMMY3, &iCurrent);
139397       }
139398       pMod->xClose(pC);
139399       if( rc!=SQLITE_OK && rc!=SQLITE_DONE ){ return rc; }
139400 
139401       nShift = (rc==SQLITE_DONE)+iCurrent-nSnippet;
139402       assert( nShift<=nDesired );
139403       if( nShift>0 ){
139404         *piPos += nShift;
139405         *pHlmask = hlmask >> nShift;
139406       }
139407     }
139408   }
139409   return SQLITE_OK;
139410 }
139411 
139412 /*
139413 ** Extract the snippet text for fragment pFragment from cursor pCsr and
139414 ** append it to string buffer pOut.
139415 */
139416 static int fts3SnippetText(
139417   Fts3Cursor *pCsr,               /* FTS3 Cursor */
139418   SnippetFragment *pFragment,     /* Snippet to extract */
139419   int iFragment,                  /* Fragment number */
139420   int isLast,                     /* True for final fragment in snippet */
139421   int nSnippet,                   /* Number of tokens in extracted snippet */
139422   const char *zOpen,              /* String inserted before highlighted term */
139423   const char *zClose,             /* String inserted after highlighted term */
139424   const char *zEllipsis,          /* String inserted between snippets */
139425   StrBuffer *pOut                 /* Write output here */
139426 ){
139427   Fts3Table *pTab = (Fts3Table *)pCsr->base.pVtab;
139428   int rc;                         /* Return code */
139429   const char *zDoc;               /* Document text to extract snippet from */
139430   int nDoc;                       /* Size of zDoc in bytes */
139431   int iCurrent = 0;               /* Current token number of document */
139432   int iEnd = 0;                   /* Byte offset of end of current token */
139433   int isShiftDone = 0;            /* True after snippet is shifted */
139434   int iPos = pFragment->iPos;     /* First token of snippet */
139435   u64 hlmask = pFragment->hlmask; /* Highlight-mask for snippet */
139436   int iCol = pFragment->iCol+1;   /* Query column to extract text from */
139437   sqlite3_tokenizer_module *pMod; /* Tokenizer module methods object */
139438   sqlite3_tokenizer_cursor *pC;   /* Tokenizer cursor open on zDoc/nDoc */
139439   
139440   zDoc = (const char *)sqlite3_column_text(pCsr->pStmt, iCol);
139441   if( zDoc==0 ){
139442     if( sqlite3_column_type(pCsr->pStmt, iCol)!=SQLITE_NULL ){
139443       return SQLITE_NOMEM;
139444     }
139445     return SQLITE_OK;
139446   }
139447   nDoc = sqlite3_column_bytes(pCsr->pStmt, iCol);
139448 
139449   /* Open a token cursor on the document. */
139450   pMod = (sqlite3_tokenizer_module *)pTab->pTokenizer->pModule;
139451   rc = sqlite3Fts3OpenTokenizer(pTab->pTokenizer, pCsr->iLangid, zDoc,nDoc,&pC);
139452   if( rc!=SQLITE_OK ){
139453     return rc;
139454   }
139455 
139456   while( rc==SQLITE_OK ){
139457     const char *ZDUMMY;           /* Dummy argument used with tokenizer */
139458     int DUMMY1 = -1;              /* Dummy argument used with tokenizer */
139459     int iBegin = 0;               /* Offset in zDoc of start of token */
139460     int iFin = 0;                 /* Offset in zDoc of end of token */
139461     int isHighlight = 0;          /* True for highlighted terms */
139462 
139463     /* Variable DUMMY1 is initialized to a negative value above. Elsewhere
139464     ** in the FTS code the variable that the third argument to xNext points to
139465     ** is initialized to zero before the first (*but not necessarily
139466     ** subsequent*) call to xNext(). This is done for a particular application
139467     ** that needs to know whether or not the tokenizer is being used for
139468     ** snippet generation or for some other purpose.
139469     **
139470     ** Extreme care is required when writing code to depend on this
139471     ** initialization. It is not a documented part of the tokenizer interface.
139472     ** If a tokenizer is used directly by any code outside of FTS, this
139473     ** convention might not be respected.  */
139474     rc = pMod->xNext(pC, &ZDUMMY, &DUMMY1, &iBegin, &iFin, &iCurrent);
139475     if( rc!=SQLITE_OK ){
139476       if( rc==SQLITE_DONE ){
139477         /* Special case - the last token of the snippet is also the last token
139478         ** of the column. Append any punctuation that occurred between the end
139479         ** of the previous token and the end of the document to the output. 
139480         ** Then break out of the loop. */
139481         rc = fts3StringAppend(pOut, &zDoc[iEnd], -1);
139482       }
139483       break;
139484     }
139485     if( iCurrent<iPos ){ continue; }
139486 
139487     if( !isShiftDone ){
139488       int n = nDoc - iBegin;
139489       rc = fts3SnippetShift(
139490           pTab, pCsr->iLangid, nSnippet, &zDoc[iBegin], n, &iPos, &hlmask
139491       );
139492       isShiftDone = 1;
139493 
139494       /* Now that the shift has been done, check if the initial "..." are
139495       ** required. They are required if (a) this is not the first fragment,
139496       ** or (b) this fragment does not begin at position 0 of its column. 
139497       */
139498       if( rc==SQLITE_OK && (iPos>0 || iFragment>0) ){
139499         rc = fts3StringAppend(pOut, zEllipsis, -1);
139500       }
139501       if( rc!=SQLITE_OK || iCurrent<iPos ) continue;
139502     }
139503 
139504     if( iCurrent>=(iPos+nSnippet) ){
139505       if( isLast ){
139506         rc = fts3StringAppend(pOut, zEllipsis, -1);
139507       }
139508       break;
139509     }
139510 
139511     /* Set isHighlight to true if this term should be highlighted. */
139512     isHighlight = (hlmask & ((u64)1 << (iCurrent-iPos)))!=0;
139513 
139514     if( iCurrent>iPos ) rc = fts3StringAppend(pOut, &zDoc[iEnd], iBegin-iEnd);
139515     if( rc==SQLITE_OK && isHighlight ) rc = fts3StringAppend(pOut, zOpen, -1);
139516     if( rc==SQLITE_OK ) rc = fts3StringAppend(pOut, &zDoc[iBegin], iFin-iBegin);
139517     if( rc==SQLITE_OK && isHighlight ) rc = fts3StringAppend(pOut, zClose, -1);
139518 
139519     iEnd = iFin;
139520   }
139521 
139522   pMod->xClose(pC);
139523   return rc;
139524 }
139525 
139526 
139527 /*
139528 ** This function is used to count the entries in a column-list (a 
139529 ** delta-encoded list of term offsets within a single column of a single 
139530 ** row). When this function is called, *ppCollist should point to the
139531 ** beginning of the first varint in the column-list (the varint that
139532 ** contains the position of the first matching term in the column data).
139533 ** Before returning, *ppCollist is set to point to the first byte after
139534 ** the last varint in the column-list (either the 0x00 signifying the end
139535 ** of the position-list, or the 0x01 that precedes the column number of
139536 ** the next column in the position-list).
139537 **
139538 ** The number of elements in the column-list is returned.
139539 */
139540 static int fts3ColumnlistCount(char **ppCollist){
139541   char *pEnd = *ppCollist;
139542   char c = 0;
139543   int nEntry = 0;
139544 
139545   /* A column-list is terminated by either a 0x01 or 0x00. */
139546   while( 0xFE & (*pEnd | c) ){
139547     c = *pEnd++ & 0x80;
139548     if( !c ) nEntry++;
139549   }
139550 
139551   *ppCollist = pEnd;
139552   return nEntry;
139553 }
139554 
139555 /*
139556 ** fts3ExprIterate() callback used to collect the "global" matchinfo stats
139557 ** for a single query. 
139558 **
139559 ** fts3ExprIterate() callback to load the 'global' elements of a
139560 ** FTS3_MATCHINFO_HITS matchinfo array. The global stats are those elements 
139561 ** of the matchinfo array that are constant for all rows returned by the 
139562 ** current query.
139563 **
139564 ** Argument pCtx is actually a pointer to a struct of type MatchInfo. This
139565 ** function populates Matchinfo.aMatchinfo[] as follows:
139566 **
139567 **   for(iCol=0; iCol<nCol; iCol++){
139568 **     aMatchinfo[3*iPhrase*nCol + 3*iCol + 1] = X;
139569 **     aMatchinfo[3*iPhrase*nCol + 3*iCol + 2] = Y;
139570 **   }
139571 **
139572 ** where X is the number of matches for phrase iPhrase is column iCol of all
139573 ** rows of the table. Y is the number of rows for which column iCol contains
139574 ** at least one instance of phrase iPhrase.
139575 **
139576 ** If the phrase pExpr consists entirely of deferred tokens, then all X and
139577 ** Y values are set to nDoc, where nDoc is the number of documents in the 
139578 ** file system. This is done because the full-text index doclist is required
139579 ** to calculate these values properly, and the full-text index doclist is
139580 ** not available for deferred tokens.
139581 */
139582 static int fts3ExprGlobalHitsCb(
139583   Fts3Expr *pExpr,                /* Phrase expression node */
139584   int iPhrase,                    /* Phrase number (numbered from zero) */
139585   void *pCtx                      /* Pointer to MatchInfo structure */
139586 ){
139587   MatchInfo *p = (MatchInfo *)pCtx;
139588   return sqlite3Fts3EvalPhraseStats(
139589       p->pCursor, pExpr, &p->aMatchinfo[3*iPhrase*p->nCol]
139590   );
139591 }
139592 
139593 /*
139594 ** fts3ExprIterate() callback used to collect the "local" part of the
139595 ** FTS3_MATCHINFO_HITS array. The local stats are those elements of the 
139596 ** array that are different for each row returned by the query.
139597 */
139598 static int fts3ExprLocalHitsCb(
139599   Fts3Expr *pExpr,                /* Phrase expression node */
139600   int iPhrase,                    /* Phrase number */
139601   void *pCtx                      /* Pointer to MatchInfo structure */
139602 ){
139603   int rc = SQLITE_OK;
139604   MatchInfo *p = (MatchInfo *)pCtx;
139605   int iStart = iPhrase * p->nCol * 3;
139606   int i;
139607 
139608   for(i=0; i<p->nCol && rc==SQLITE_OK; i++){
139609     char *pCsr;
139610     rc = sqlite3Fts3EvalPhrasePoslist(p->pCursor, pExpr, i, &pCsr);
139611     if( pCsr ){
139612       p->aMatchinfo[iStart+i*3] = fts3ColumnlistCount(&pCsr);
139613     }else{
139614       p->aMatchinfo[iStart+i*3] = 0;
139615     }
139616   }
139617 
139618   return rc;
139619 }
139620 
139621 static int fts3MatchinfoCheck(
139622   Fts3Table *pTab, 
139623   char cArg,
139624   char **pzErr
139625 ){
139626   if( (cArg==FTS3_MATCHINFO_NPHRASE)
139627    || (cArg==FTS3_MATCHINFO_NCOL)
139628    || (cArg==FTS3_MATCHINFO_NDOC && pTab->bFts4)
139629    || (cArg==FTS3_MATCHINFO_AVGLENGTH && pTab->bFts4)
139630    || (cArg==FTS3_MATCHINFO_LENGTH && pTab->bHasDocsize)
139631    || (cArg==FTS3_MATCHINFO_LCS)
139632    || (cArg==FTS3_MATCHINFO_HITS)
139633   ){
139634     return SQLITE_OK;
139635   }
139636   *pzErr = sqlite3_mprintf("unrecognized matchinfo request: %c", cArg);
139637   return SQLITE_ERROR;
139638 }
139639 
139640 static int fts3MatchinfoSize(MatchInfo *pInfo, char cArg){
139641   int nVal;                       /* Number of integers output by cArg */
139642 
139643   switch( cArg ){
139644     case FTS3_MATCHINFO_NDOC:
139645     case FTS3_MATCHINFO_NPHRASE: 
139646     case FTS3_MATCHINFO_NCOL: 
139647       nVal = 1;
139648       break;
139649 
139650     case FTS3_MATCHINFO_AVGLENGTH:
139651     case FTS3_MATCHINFO_LENGTH:
139652     case FTS3_MATCHINFO_LCS:
139653       nVal = pInfo->nCol;
139654       break;
139655 
139656     default:
139657       assert( cArg==FTS3_MATCHINFO_HITS );
139658       nVal = pInfo->nCol * pInfo->nPhrase * 3;
139659       break;
139660   }
139661 
139662   return nVal;
139663 }
139664 
139665 static int fts3MatchinfoSelectDoctotal(
139666   Fts3Table *pTab,
139667   sqlite3_stmt **ppStmt,
139668   sqlite3_int64 *pnDoc,
139669   const char **paLen
139670 ){
139671   sqlite3_stmt *pStmt;
139672   const char *a;
139673   sqlite3_int64 nDoc;
139674 
139675   if( !*ppStmt ){
139676     int rc = sqlite3Fts3SelectDoctotal(pTab, ppStmt);
139677     if( rc!=SQLITE_OK ) return rc;
139678   }
139679   pStmt = *ppStmt;
139680   assert( sqlite3_data_count(pStmt)==1 );
139681 
139682   a = sqlite3_column_blob(pStmt, 0);
139683   a += sqlite3Fts3GetVarint(a, &nDoc);
139684   if( nDoc==0 ) return FTS_CORRUPT_VTAB;
139685   *pnDoc = (u32)nDoc;
139686 
139687   if( paLen ) *paLen = a;
139688   return SQLITE_OK;
139689 }
139690 
139691 /*
139692 ** An instance of the following structure is used to store state while 
139693 ** iterating through a multi-column position-list corresponding to the
139694 ** hits for a single phrase on a single row in order to calculate the
139695 ** values for a matchinfo() FTS3_MATCHINFO_LCS request.
139696 */
139697 typedef struct LcsIterator LcsIterator;
139698 struct LcsIterator {
139699   Fts3Expr *pExpr;                /* Pointer to phrase expression */
139700   int iPosOffset;                 /* Tokens count up to end of this phrase */
139701   char *pRead;                    /* Cursor used to iterate through aDoclist */
139702   int iPos;                       /* Current position */
139703 };
139704 
139705 /* 
139706 ** If LcsIterator.iCol is set to the following value, the iterator has
139707 ** finished iterating through all offsets for all columns.
139708 */
139709 #define LCS_ITERATOR_FINISHED 0x7FFFFFFF;
139710 
139711 static int fts3MatchinfoLcsCb(
139712   Fts3Expr *pExpr,                /* Phrase expression node */
139713   int iPhrase,                    /* Phrase number (numbered from zero) */
139714   void *pCtx                      /* Pointer to MatchInfo structure */
139715 ){
139716   LcsIterator *aIter = (LcsIterator *)pCtx;
139717   aIter[iPhrase].pExpr = pExpr;
139718   return SQLITE_OK;
139719 }
139720 
139721 /*
139722 ** Advance the iterator passed as an argument to the next position. Return
139723 ** 1 if the iterator is at EOF or if it now points to the start of the
139724 ** position list for the next column.
139725 */
139726 static int fts3LcsIteratorAdvance(LcsIterator *pIter){
139727   char *pRead = pIter->pRead;
139728   sqlite3_int64 iRead;
139729   int rc = 0;
139730 
139731   pRead += sqlite3Fts3GetVarint(pRead, &iRead);
139732   if( iRead==0 || iRead==1 ){
139733     pRead = 0;
139734     rc = 1;
139735   }else{
139736     pIter->iPos += (int)(iRead-2);
139737   }
139738 
139739   pIter->pRead = pRead;
139740   return rc;
139741 }
139742   
139743 /*
139744 ** This function implements the FTS3_MATCHINFO_LCS matchinfo() flag. 
139745 **
139746 ** If the call is successful, the longest-common-substring lengths for each
139747 ** column are written into the first nCol elements of the pInfo->aMatchinfo[] 
139748 ** array before returning. SQLITE_OK is returned in this case.
139749 **
139750 ** Otherwise, if an error occurs, an SQLite error code is returned and the
139751 ** data written to the first nCol elements of pInfo->aMatchinfo[] is 
139752 ** undefined.
139753 */
139754 static int fts3MatchinfoLcs(Fts3Cursor *pCsr, MatchInfo *pInfo){
139755   LcsIterator *aIter;
139756   int i;
139757   int iCol;
139758   int nToken = 0;
139759 
139760   /* Allocate and populate the array of LcsIterator objects. The array
139761   ** contains one element for each matchable phrase in the query.
139762   **/
139763   aIter = sqlite3_malloc(sizeof(LcsIterator) * pCsr->nPhrase);
139764   if( !aIter ) return SQLITE_NOMEM;
139765   memset(aIter, 0, sizeof(LcsIterator) * pCsr->nPhrase);
139766   (void)fts3ExprIterate(pCsr->pExpr, fts3MatchinfoLcsCb, (void*)aIter);
139767 
139768   for(i=0; i<pInfo->nPhrase; i++){
139769     LcsIterator *pIter = &aIter[i];
139770     nToken -= pIter->pExpr->pPhrase->nToken;
139771     pIter->iPosOffset = nToken;
139772   }
139773 
139774   for(iCol=0; iCol<pInfo->nCol; iCol++){
139775     int nLcs = 0;                 /* LCS value for this column */
139776     int nLive = 0;                /* Number of iterators in aIter not at EOF */
139777 
139778     for(i=0; i<pInfo->nPhrase; i++){
139779       int rc;
139780       LcsIterator *pIt = &aIter[i];
139781       rc = sqlite3Fts3EvalPhrasePoslist(pCsr, pIt->pExpr, iCol, &pIt->pRead);
139782       if( rc!=SQLITE_OK ) return rc;
139783       if( pIt->pRead ){
139784         pIt->iPos = pIt->iPosOffset;
139785         fts3LcsIteratorAdvance(&aIter[i]);
139786         nLive++;
139787       }
139788     }
139789 
139790     while( nLive>0 ){
139791       LcsIterator *pAdv = 0;      /* The iterator to advance by one position */
139792       int nThisLcs = 0;           /* LCS for the current iterator positions */
139793 
139794       for(i=0; i<pInfo->nPhrase; i++){
139795         LcsIterator *pIter = &aIter[i];
139796         if( pIter->pRead==0 ){
139797           /* This iterator is already at EOF for this column. */
139798           nThisLcs = 0;
139799         }else{
139800           if( pAdv==0 || pIter->iPos<pAdv->iPos ){
139801             pAdv = pIter;
139802           }
139803           if( nThisLcs==0 || pIter->iPos==pIter[-1].iPos ){
139804             nThisLcs++;
139805           }else{
139806             nThisLcs = 1;
139807           }
139808           if( nThisLcs>nLcs ) nLcs = nThisLcs;
139809         }
139810       }
139811       if( fts3LcsIteratorAdvance(pAdv) ) nLive--;
139812     }
139813 
139814     pInfo->aMatchinfo[iCol] = nLcs;
139815   }
139816 
139817   sqlite3_free(aIter);
139818   return SQLITE_OK;
139819 }
139820 
139821 /*
139822 ** Populate the buffer pInfo->aMatchinfo[] with an array of integers to
139823 ** be returned by the matchinfo() function. Argument zArg contains the 
139824 ** format string passed as the second argument to matchinfo (or the
139825 ** default value "pcx" if no second argument was specified). The format
139826 ** string has already been validated and the pInfo->aMatchinfo[] array
139827 ** is guaranteed to be large enough for the output.
139828 **
139829 ** If bGlobal is true, then populate all fields of the matchinfo() output.
139830 ** If it is false, then assume that those fields that do not change between
139831 ** rows (i.e. FTS3_MATCHINFO_NPHRASE, NCOL, NDOC, AVGLENGTH and part of HITS)
139832 ** have already been populated.
139833 **
139834 ** Return SQLITE_OK if successful, or an SQLite error code if an error 
139835 ** occurs. If a value other than SQLITE_OK is returned, the state the
139836 ** pInfo->aMatchinfo[] buffer is left in is undefined.
139837 */
139838 static int fts3MatchinfoValues(
139839   Fts3Cursor *pCsr,               /* FTS3 cursor object */
139840   int bGlobal,                    /* True to grab the global stats */
139841   MatchInfo *pInfo,               /* Matchinfo context object */
139842   const char *zArg                /* Matchinfo format string */
139843 ){
139844   int rc = SQLITE_OK;
139845   int i;
139846   Fts3Table *pTab = (Fts3Table *)pCsr->base.pVtab;
139847   sqlite3_stmt *pSelect = 0;
139848 
139849   for(i=0; rc==SQLITE_OK && zArg[i]; i++){
139850 
139851     switch( zArg[i] ){
139852       case FTS3_MATCHINFO_NPHRASE:
139853         if( bGlobal ) pInfo->aMatchinfo[0] = pInfo->nPhrase;
139854         break;
139855 
139856       case FTS3_MATCHINFO_NCOL:
139857         if( bGlobal ) pInfo->aMatchinfo[0] = pInfo->nCol;
139858         break;
139859         
139860       case FTS3_MATCHINFO_NDOC:
139861         if( bGlobal ){
139862           sqlite3_int64 nDoc = 0;
139863           rc = fts3MatchinfoSelectDoctotal(pTab, &pSelect, &nDoc, 0);
139864           pInfo->aMatchinfo[0] = (u32)nDoc;
139865         }
139866         break;
139867 
139868       case FTS3_MATCHINFO_AVGLENGTH: 
139869         if( bGlobal ){
139870           sqlite3_int64 nDoc;     /* Number of rows in table */
139871           const char *a;          /* Aggregate column length array */
139872 
139873           rc = fts3MatchinfoSelectDoctotal(pTab, &pSelect, &nDoc, &a);
139874           if( rc==SQLITE_OK ){
139875             int iCol;
139876             for(iCol=0; iCol<pInfo->nCol; iCol++){
139877               u32 iVal;
139878               sqlite3_int64 nToken;
139879               a += sqlite3Fts3GetVarint(a, &nToken);
139880               iVal = (u32)(((u32)(nToken&0xffffffff)+nDoc/2)/nDoc);
139881               pInfo->aMatchinfo[iCol] = iVal;
139882             }
139883           }
139884         }
139885         break;
139886 
139887       case FTS3_MATCHINFO_LENGTH: {
139888         sqlite3_stmt *pSelectDocsize = 0;
139889         rc = sqlite3Fts3SelectDocsize(pTab, pCsr->iPrevId, &pSelectDocsize);
139890         if( rc==SQLITE_OK ){
139891           int iCol;
139892           const char *a = sqlite3_column_blob(pSelectDocsize, 0);
139893           for(iCol=0; iCol<pInfo->nCol; iCol++){
139894             sqlite3_int64 nToken;
139895             a += sqlite3Fts3GetVarint(a, &nToken);
139896             pInfo->aMatchinfo[iCol] = (u32)nToken;
139897           }
139898         }
139899         sqlite3_reset(pSelectDocsize);
139900         break;
139901       }
139902 
139903       case FTS3_MATCHINFO_LCS:
139904         rc = fts3ExprLoadDoclists(pCsr, 0, 0);
139905         if( rc==SQLITE_OK ){
139906           rc = fts3MatchinfoLcs(pCsr, pInfo);
139907         }
139908         break;
139909 
139910       default: {
139911         Fts3Expr *pExpr;
139912         assert( zArg[i]==FTS3_MATCHINFO_HITS );
139913         pExpr = pCsr->pExpr;
139914         rc = fts3ExprLoadDoclists(pCsr, 0, 0);
139915         if( rc!=SQLITE_OK ) break;
139916         if( bGlobal ){
139917           if( pCsr->pDeferred ){
139918             rc = fts3MatchinfoSelectDoctotal(pTab, &pSelect, &pInfo->nDoc, 0);
139919             if( rc!=SQLITE_OK ) break;
139920           }
139921           rc = fts3ExprIterate(pExpr, fts3ExprGlobalHitsCb,(void*)pInfo);
139922           if( rc!=SQLITE_OK ) break;
139923         }
139924         (void)fts3ExprIterate(pExpr, fts3ExprLocalHitsCb,(void*)pInfo);
139925         break;
139926       }
139927     }
139928 
139929     pInfo->aMatchinfo += fts3MatchinfoSize(pInfo, zArg[i]);
139930   }
139931 
139932   sqlite3_reset(pSelect);
139933   return rc;
139934 }
139935 
139936 
139937 /*
139938 ** Populate pCsr->aMatchinfo[] with data for the current row. The 
139939 ** 'matchinfo' data is an array of 32-bit unsigned integers (C type u32).
139940 */
139941 static int fts3GetMatchinfo(
139942   Fts3Cursor *pCsr,               /* FTS3 Cursor object */
139943   const char *zArg                /* Second argument to matchinfo() function */
139944 ){
139945   MatchInfo sInfo;
139946   Fts3Table *pTab = (Fts3Table *)pCsr->base.pVtab;
139947   int rc = SQLITE_OK;
139948   int bGlobal = 0;                /* Collect 'global' stats as well as local */
139949 
139950   memset(&sInfo, 0, sizeof(MatchInfo));
139951   sInfo.pCursor = pCsr;
139952   sInfo.nCol = pTab->nColumn;
139953 
139954   /* If there is cached matchinfo() data, but the format string for the 
139955   ** cache does not match the format string for this request, discard 
139956   ** the cached data. */
139957   if( pCsr->zMatchinfo && strcmp(pCsr->zMatchinfo, zArg) ){
139958     assert( pCsr->aMatchinfo );
139959     sqlite3_free(pCsr->aMatchinfo);
139960     pCsr->zMatchinfo = 0;
139961     pCsr->aMatchinfo = 0;
139962   }
139963 
139964   /* If Fts3Cursor.aMatchinfo[] is NULL, then this is the first time the
139965   ** matchinfo function has been called for this query. In this case 
139966   ** allocate the array used to accumulate the matchinfo data and
139967   ** initialize those elements that are constant for every row.
139968   */
139969   if( pCsr->aMatchinfo==0 ){
139970     int nMatchinfo = 0;           /* Number of u32 elements in match-info */
139971     int nArg;                     /* Bytes in zArg */
139972     int i;                        /* Used to iterate through zArg */
139973 
139974     /* Determine the number of phrases in the query */
139975     pCsr->nPhrase = fts3ExprPhraseCount(pCsr->pExpr);
139976     sInfo.nPhrase = pCsr->nPhrase;
139977 
139978     /* Determine the number of integers in the buffer returned by this call. */
139979     for(i=0; zArg[i]; i++){
139980       nMatchinfo += fts3MatchinfoSize(&sInfo, zArg[i]);
139981     }
139982 
139983     /* Allocate space for Fts3Cursor.aMatchinfo[] and Fts3Cursor.zMatchinfo. */
139984     nArg = (int)strlen(zArg);
139985     pCsr->aMatchinfo = (u32 *)sqlite3_malloc(sizeof(u32)*nMatchinfo + nArg + 1);
139986     if( !pCsr->aMatchinfo ) return SQLITE_NOMEM;
139987 
139988     pCsr->zMatchinfo = (char *)&pCsr->aMatchinfo[nMatchinfo];
139989     pCsr->nMatchinfo = nMatchinfo;
139990     memcpy(pCsr->zMatchinfo, zArg, nArg+1);
139991     memset(pCsr->aMatchinfo, 0, sizeof(u32)*nMatchinfo);
139992     pCsr->isMatchinfoNeeded = 1;
139993     bGlobal = 1;
139994   }
139995 
139996   sInfo.aMatchinfo = pCsr->aMatchinfo;
139997   sInfo.nPhrase = pCsr->nPhrase;
139998   if( pCsr->isMatchinfoNeeded ){
139999     rc = fts3MatchinfoValues(pCsr, bGlobal, &sInfo, zArg);
140000     pCsr->isMatchinfoNeeded = 0;
140001   }
140002 
140003   return rc;
140004 }
140005 
140006 /*
140007 ** Implementation of snippet() function.
140008 */
140009 SQLITE_PRIVATE void sqlite3Fts3Snippet(
140010   sqlite3_context *pCtx,          /* SQLite function call context */
140011   Fts3Cursor *pCsr,               /* Cursor object */
140012   const char *zStart,             /* Snippet start text - "<b>" */
140013   const char *zEnd,               /* Snippet end text - "</b>" */
140014   const char *zEllipsis,          /* Snippet ellipsis text - "<b>...</b>" */
140015   int iCol,                       /* Extract snippet from this column */
140016   int nToken                      /* Approximate number of tokens in snippet */
140017 ){
140018   Fts3Table *pTab = (Fts3Table *)pCsr->base.pVtab;
140019   int rc = SQLITE_OK;
140020   int i;
140021   StrBuffer res = {0, 0, 0};
140022 
140023   /* The returned text includes up to four fragments of text extracted from
140024   ** the data in the current row. The first iteration of the for(...) loop
140025   ** below attempts to locate a single fragment of text nToken tokens in 
140026   ** size that contains at least one instance of all phrases in the query
140027   ** expression that appear in the current row. If such a fragment of text
140028   ** cannot be found, the second iteration of the loop attempts to locate
140029   ** a pair of fragments, and so on.
140030   */
140031   int nSnippet = 0;               /* Number of fragments in this snippet */
140032   SnippetFragment aSnippet[4];    /* Maximum of 4 fragments per snippet */
140033   int nFToken = -1;               /* Number of tokens in each fragment */
140034 
140035   if( !pCsr->pExpr ){
140036     sqlite3_result_text(pCtx, "", 0, SQLITE_STATIC);
140037     return;
140038   }
140039 
140040   for(nSnippet=1; 1; nSnippet++){
140041 
140042     int iSnip;                    /* Loop counter 0..nSnippet-1 */
140043     u64 mCovered = 0;             /* Bitmask of phrases covered by snippet */
140044     u64 mSeen = 0;                /* Bitmask of phrases seen by BestSnippet() */
140045 
140046     if( nToken>=0 ){
140047       nFToken = (nToken+nSnippet-1) / nSnippet;
140048     }else{
140049       nFToken = -1 * nToken;
140050     }
140051 
140052     for(iSnip=0; iSnip<nSnippet; iSnip++){
140053       int iBestScore = -1;        /* Best score of columns checked so far */
140054       int iRead;                  /* Used to iterate through columns */
140055       SnippetFragment *pFragment = &aSnippet[iSnip];
140056 
140057       memset(pFragment, 0, sizeof(*pFragment));
140058 
140059       /* Loop through all columns of the table being considered for snippets.
140060       ** If the iCol argument to this function was negative, this means all
140061       ** columns of the FTS3 table. Otherwise, only column iCol is considered.
140062       */
140063       for(iRead=0; iRead<pTab->nColumn; iRead++){
140064         SnippetFragment sF = {0, 0, 0, 0};
140065         int iS;
140066         if( iCol>=0 && iRead!=iCol ) continue;
140067 
140068         /* Find the best snippet of nFToken tokens in column iRead. */
140069         rc = fts3BestSnippet(nFToken, pCsr, iRead, mCovered, &mSeen, &sF, &iS);
140070         if( rc!=SQLITE_OK ){
140071           goto snippet_out;
140072         }
140073         if( iS>iBestScore ){
140074           *pFragment = sF;
140075           iBestScore = iS;
140076         }
140077       }
140078 
140079       mCovered |= pFragment->covered;
140080     }
140081 
140082     /* If all query phrases seen by fts3BestSnippet() are present in at least
140083     ** one of the nSnippet snippet fragments, break out of the loop.
140084     */
140085     assert( (mCovered&mSeen)==mCovered );
140086     if( mSeen==mCovered || nSnippet==SizeofArray(aSnippet) ) break;
140087   }
140088 
140089   assert( nFToken>0 );
140090 
140091   for(i=0; i<nSnippet && rc==SQLITE_OK; i++){
140092     rc = fts3SnippetText(pCsr, &aSnippet[i], 
140093         i, (i==nSnippet-1), nFToken, zStart, zEnd, zEllipsis, &res
140094     );
140095   }
140096 
140097  snippet_out:
140098   sqlite3Fts3SegmentsClose(pTab);
140099   if( rc!=SQLITE_OK ){
140100     sqlite3_result_error_code(pCtx, rc);
140101     sqlite3_free(res.z);
140102   }else{
140103     sqlite3_result_text(pCtx, res.z, -1, sqlite3_free);
140104   }
140105 }
140106 
140107 
140108 typedef struct TermOffset TermOffset;
140109 typedef struct TermOffsetCtx TermOffsetCtx;
140110 
140111 struct TermOffset {
140112   char *pList;                    /* Position-list */
140113   int iPos;                       /* Position just read from pList */
140114   int iOff;                       /* Offset of this term from read positions */
140115 };
140116 
140117 struct TermOffsetCtx {
140118   Fts3Cursor *pCsr;
140119   int iCol;                       /* Column of table to populate aTerm for */
140120   int iTerm;
140121   sqlite3_int64 iDocid;
140122   TermOffset *aTerm;
140123 };
140124 
140125 /*
140126 ** This function is an fts3ExprIterate() callback used by sqlite3Fts3Offsets().
140127 */
140128 static int fts3ExprTermOffsetInit(Fts3Expr *pExpr, int iPhrase, void *ctx){
140129   TermOffsetCtx *p = (TermOffsetCtx *)ctx;
140130   int nTerm;                      /* Number of tokens in phrase */
140131   int iTerm;                      /* For looping through nTerm phrase terms */
140132   char *pList;                    /* Pointer to position list for phrase */
140133   int iPos = 0;                   /* First position in position-list */
140134   int rc;
140135 
140136   UNUSED_PARAMETER(iPhrase);
140137   rc = sqlite3Fts3EvalPhrasePoslist(p->pCsr, pExpr, p->iCol, &pList);
140138   nTerm = pExpr->pPhrase->nToken;
140139   if( pList ){
140140     fts3GetDeltaPosition(&pList, &iPos);
140141     assert( iPos>=0 );
140142   }
140143 
140144   for(iTerm=0; iTerm<nTerm; iTerm++){
140145     TermOffset *pT = &p->aTerm[p->iTerm++];
140146     pT->iOff = nTerm-iTerm-1;
140147     pT->pList = pList;
140148     pT->iPos = iPos;
140149   }
140150 
140151   return rc;
140152 }
140153 
140154 /*
140155 ** Implementation of offsets() function.
140156 */
140157 SQLITE_PRIVATE void sqlite3Fts3Offsets(
140158   sqlite3_context *pCtx,          /* SQLite function call context */
140159   Fts3Cursor *pCsr                /* Cursor object */
140160 ){
140161   Fts3Table *pTab = (Fts3Table *)pCsr->base.pVtab;
140162   sqlite3_tokenizer_module const *pMod = pTab->pTokenizer->pModule;
140163   int rc;                         /* Return Code */
140164   int nToken;                     /* Number of tokens in query */
140165   int iCol;                       /* Column currently being processed */
140166   StrBuffer res = {0, 0, 0};      /* Result string */
140167   TermOffsetCtx sCtx;             /* Context for fts3ExprTermOffsetInit() */
140168 
140169   if( !pCsr->pExpr ){
140170     sqlite3_result_text(pCtx, "", 0, SQLITE_STATIC);
140171     return;
140172   }
140173 
140174   memset(&sCtx, 0, sizeof(sCtx));
140175   assert( pCsr->isRequireSeek==0 );
140176 
140177   /* Count the number of terms in the query */
140178   rc = fts3ExprLoadDoclists(pCsr, 0, &nToken);
140179   if( rc!=SQLITE_OK ) goto offsets_out;
140180 
140181   /* Allocate the array of TermOffset iterators. */
140182   sCtx.aTerm = (TermOffset *)sqlite3_malloc(sizeof(TermOffset)*nToken);
140183   if( 0==sCtx.aTerm ){
140184     rc = SQLITE_NOMEM;
140185     goto offsets_out;
140186   }
140187   sCtx.iDocid = pCsr->iPrevId;
140188   sCtx.pCsr = pCsr;
140189 
140190   /* Loop through the table columns, appending offset information to 
140191   ** string-buffer res for each column.
140192   */
140193   for(iCol=0; iCol<pTab->nColumn; iCol++){
140194     sqlite3_tokenizer_cursor *pC; /* Tokenizer cursor */
140195     const char *ZDUMMY;           /* Dummy argument used with xNext() */
140196     int NDUMMY = 0;               /* Dummy argument used with xNext() */
140197     int iStart = 0;
140198     int iEnd = 0;
140199     int iCurrent = 0;
140200     const char *zDoc;
140201     int nDoc;
140202 
140203     /* Initialize the contents of sCtx.aTerm[] for column iCol. There is 
140204     ** no way that this operation can fail, so the return code from
140205     ** fts3ExprIterate() can be discarded.
140206     */
140207     sCtx.iCol = iCol;
140208     sCtx.iTerm = 0;
140209     (void)fts3ExprIterate(pCsr->pExpr, fts3ExprTermOffsetInit, (void *)&sCtx);
140210 
140211     /* Retreive the text stored in column iCol. If an SQL NULL is stored 
140212     ** in column iCol, jump immediately to the next iteration of the loop.
140213     ** If an OOM occurs while retrieving the data (this can happen if SQLite
140214     ** needs to transform the data from utf-16 to utf-8), return SQLITE_NOMEM 
140215     ** to the caller. 
140216     */
140217     zDoc = (const char *)sqlite3_column_text(pCsr->pStmt, iCol+1);
140218     nDoc = sqlite3_column_bytes(pCsr->pStmt, iCol+1);
140219     if( zDoc==0 ){
140220       if( sqlite3_column_type(pCsr->pStmt, iCol+1)==SQLITE_NULL ){
140221         continue;
140222       }
140223       rc = SQLITE_NOMEM;
140224       goto offsets_out;
140225     }
140226 
140227     /* Initialize a tokenizer iterator to iterate through column iCol. */
140228     rc = sqlite3Fts3OpenTokenizer(pTab->pTokenizer, pCsr->iLangid,
140229         zDoc, nDoc, &pC
140230     );
140231     if( rc!=SQLITE_OK ) goto offsets_out;
140232 
140233     rc = pMod->xNext(pC, &ZDUMMY, &NDUMMY, &iStart, &iEnd, &iCurrent);
140234     while( rc==SQLITE_OK ){
140235       int i;                      /* Used to loop through terms */
140236       int iMinPos = 0x7FFFFFFF;   /* Position of next token */
140237       TermOffset *pTerm = 0;      /* TermOffset associated with next token */
140238 
140239       for(i=0; i<nToken; i++){
140240         TermOffset *pT = &sCtx.aTerm[i];
140241         if( pT->pList && (pT->iPos-pT->iOff)<iMinPos ){
140242           iMinPos = pT->iPos-pT->iOff;
140243           pTerm = pT;
140244         }
140245       }
140246 
140247       if( !pTerm ){
140248         /* All offsets for this column have been gathered. */
140249         rc = SQLITE_DONE;
140250       }else{
140251         assert( iCurrent<=iMinPos );
140252         if( 0==(0xFE&*pTerm->pList) ){
140253           pTerm->pList = 0;
140254         }else{
140255           fts3GetDeltaPosition(&pTerm->pList, &pTerm->iPos);
140256         }
140257         while( rc==SQLITE_OK && iCurrent<iMinPos ){
140258           rc = pMod->xNext(pC, &ZDUMMY, &NDUMMY, &iStart, &iEnd, &iCurrent);
140259         }
140260         if( rc==SQLITE_OK ){
140261           char aBuffer[64];
140262           sqlite3_snprintf(sizeof(aBuffer), aBuffer, 
140263               "%d %d %d %d ", iCol, pTerm-sCtx.aTerm, iStart, iEnd-iStart
140264           );
140265           rc = fts3StringAppend(&res, aBuffer, -1);
140266         }else if( rc==SQLITE_DONE && pTab->zContentTbl==0 ){
140267           rc = FTS_CORRUPT_VTAB;
140268         }
140269       }
140270     }
140271     if( rc==SQLITE_DONE ){
140272       rc = SQLITE_OK;
140273     }
140274 
140275     pMod->xClose(pC);
140276     if( rc!=SQLITE_OK ) goto offsets_out;
140277   }
140278 
140279  offsets_out:
140280   sqlite3_free(sCtx.aTerm);
140281   assert( rc!=SQLITE_DONE );
140282   sqlite3Fts3SegmentsClose(pTab);
140283   if( rc!=SQLITE_OK ){
140284     sqlite3_result_error_code(pCtx,  rc);
140285     sqlite3_free(res.z);
140286   }else{
140287     sqlite3_result_text(pCtx, res.z, res.n-1, sqlite3_free);
140288   }
140289   return;
140290 }
140291 
140292 /*
140293 ** Implementation of matchinfo() function.
140294 */
140295 SQLITE_PRIVATE void sqlite3Fts3Matchinfo(
140296   sqlite3_context *pContext,      /* Function call context */
140297   Fts3Cursor *pCsr,               /* FTS3 table cursor */
140298   const char *zArg                /* Second arg to matchinfo() function */
140299 ){
140300   Fts3Table *pTab = (Fts3Table *)pCsr->base.pVtab;
140301   int rc;
140302   int i;
140303   const char *zFormat;
140304 
140305   if( zArg ){
140306     for(i=0; zArg[i]; i++){
140307       char *zErr = 0;
140308       if( fts3MatchinfoCheck(pTab, zArg[i], &zErr) ){
140309         sqlite3_result_error(pContext, zErr, -1);
140310         sqlite3_free(zErr);
140311         return;
140312       }
140313     }
140314     zFormat = zArg;
140315   }else{
140316     zFormat = FTS3_MATCHINFO_DEFAULT;
140317   }
140318 
140319   if( !pCsr->pExpr ){
140320     sqlite3_result_blob(pContext, "", 0, SQLITE_STATIC);
140321     return;
140322   }
140323 
140324   /* Retrieve matchinfo() data. */
140325   rc = fts3GetMatchinfo(pCsr, zFormat);
140326   sqlite3Fts3SegmentsClose(pTab);
140327 
140328   if( rc!=SQLITE_OK ){
140329     sqlite3_result_error_code(pContext, rc);
140330   }else{
140331     int n = pCsr->nMatchinfo * sizeof(u32);
140332     sqlite3_result_blob(pContext, pCsr->aMatchinfo, n, SQLITE_TRANSIENT);
140333   }
140334 }
140335 
140336 #endif
140337 
140338 /************** End of fts3_snippet.c ****************************************/
140339 /************** Begin file fts3_unicode.c ************************************/
140340 /*
140341 ** 2012 May 24
140342 **
140343 ** The author disclaims copyright to this source code.  In place of
140344 ** a legal notice, here is a blessing:
140345 **
140346 **    May you do good and not evil.
140347 **    May you find forgiveness for yourself and forgive others.
140348 **    May you share freely, never taking more than you give.
140349 **
140350 ******************************************************************************
140351 **
140352 ** Implementation of the "unicode" full-text-search tokenizer.
140353 */
140354 
140355 #ifdef SQLITE_ENABLE_FTS4_UNICODE61
140356 
140357 #if !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_FTS3)
140358 
140359 /* #include <assert.h> */
140360 /* #include <stdlib.h> */
140361 /* #include <stdio.h> */
140362 /* #include <string.h> */
140363 
140364 
140365 /*
140366 ** The following two macros - READ_UTF8 and WRITE_UTF8 - have been copied
140367 ** from the sqlite3 source file utf.c. If this file is compiled as part
140368 ** of the amalgamation, they are not required.
140369 */
140370 #ifndef SQLITE_AMALGAMATION
140371 
140372 static const unsigned char sqlite3Utf8Trans1[] = {
140373   0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
140374   0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
140375   0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
140376   0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
140377   0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
140378   0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
140379   0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
140380   0x00, 0x01, 0x02, 0x03, 0x00, 0x01, 0x00, 0x00,
140381 };
140382 
140383 #define READ_UTF8(zIn, zTerm, c)                           \
140384   c = *(zIn++);                                            \
140385   if( c>=0xc0 ){                                           \
140386     c = sqlite3Utf8Trans1[c-0xc0];                         \
140387     while( zIn!=zTerm && (*zIn & 0xc0)==0x80 ){            \
140388       c = (c<<6) + (0x3f & *(zIn++));                      \
140389     }                                                      \
140390     if( c<0x80                                             \
140391         || (c&0xFFFFF800)==0xD800                          \
140392         || (c&0xFFFFFFFE)==0xFFFE ){  c = 0xFFFD; }        \
140393   }
140394 
140395 #define WRITE_UTF8(zOut, c) {                          \
140396   if( c<0x00080 ){                                     \
140397     *zOut++ = (u8)(c&0xFF);                            \
140398   }                                                    \
140399   else if( c<0x00800 ){                                \
140400     *zOut++ = 0xC0 + (u8)((c>>6)&0x1F);                \
140401     *zOut++ = 0x80 + (u8)(c & 0x3F);                   \
140402   }                                                    \
140403   else if( c<0x10000 ){                                \
140404     *zOut++ = 0xE0 + (u8)((c>>12)&0x0F);               \
140405     *zOut++ = 0x80 + (u8)((c>>6) & 0x3F);              \
140406     *zOut++ = 0x80 + (u8)(c & 0x3F);                   \
140407   }else{                                               \
140408     *zOut++ = 0xF0 + (u8)((c>>18) & 0x07);             \
140409     *zOut++ = 0x80 + (u8)((c>>12) & 0x3F);             \
140410     *zOut++ = 0x80 + (u8)((c>>6) & 0x3F);              \
140411     *zOut++ = 0x80 + (u8)(c & 0x3F);                   \
140412   }                                                    \
140413 }
140414 
140415 #endif /* ifndef SQLITE_AMALGAMATION */
140416 
140417 typedef struct unicode_tokenizer unicode_tokenizer;
140418 typedef struct unicode_cursor unicode_cursor;
140419 
140420 struct unicode_tokenizer {
140421   sqlite3_tokenizer base;
140422   int bRemoveDiacritic;
140423   int nException;
140424   int *aiException;
140425 };
140426 
140427 struct unicode_cursor {
140428   sqlite3_tokenizer_cursor base;
140429   const unsigned char *aInput;    /* Input text being tokenized */
140430   int nInput;                     /* Size of aInput[] in bytes */
140431   int iOff;                       /* Current offset within aInput[] */
140432   int iToken;                     /* Index of next token to be returned */
140433   char *zToken;                   /* storage for current token */
140434   int nAlloc;                     /* space allocated at zToken */
140435 };
140436 
140437 
140438 /*
140439 ** Destroy a tokenizer allocated by unicodeCreate().
140440 */
140441 static int unicodeDestroy(sqlite3_tokenizer *pTokenizer){
140442   if( pTokenizer ){
140443     unicode_tokenizer *p = (unicode_tokenizer *)pTokenizer;
140444     sqlite3_free(p->aiException);
140445     sqlite3_free(p);
140446   }
140447   return SQLITE_OK;
140448 }
140449 
140450 /*
140451 ** As part of a tokenchars= or separators= option, the CREATE VIRTUAL TABLE
140452 ** statement has specified that the tokenizer for this table shall consider
140453 ** all characters in string zIn/nIn to be separators (if bAlnum==0) or
140454 ** token characters (if bAlnum==1).
140455 **
140456 ** For each codepoint in the zIn/nIn string, this function checks if the
140457 ** sqlite3FtsUnicodeIsalnum() function already returns the desired result.
140458 ** If so, no action is taken. Otherwise, the codepoint is added to the 
140459 ** unicode_tokenizer.aiException[] array. For the purposes of tokenization,
140460 ** the return value of sqlite3FtsUnicodeIsalnum() is inverted for all
140461 ** codepoints in the aiException[] array.
140462 **
140463 ** If a standalone diacritic mark (one that sqlite3FtsUnicodeIsdiacritic()
140464 ** identifies as a diacritic) occurs in the zIn/nIn string it is ignored.
140465 ** It is not possible to change the behavior of the tokenizer with respect
140466 ** to these codepoints.
140467 */
140468 static int unicodeAddExceptions(
140469   unicode_tokenizer *p,           /* Tokenizer to add exceptions to */
140470   int bAlnum,                     /* Replace Isalnum() return value with this */
140471   const char *zIn,                /* Array of characters to make exceptions */
140472   int nIn                         /* Length of z in bytes */
140473 ){
140474   const unsigned char *z = (const unsigned char *)zIn;
140475   const unsigned char *zTerm = &z[nIn];
140476   int iCode;
140477   int nEntry = 0;
140478 
140479   assert( bAlnum==0 || bAlnum==1 );
140480 
140481   while( z<zTerm ){
140482     READ_UTF8(z, zTerm, iCode);
140483     assert( (sqlite3FtsUnicodeIsalnum(iCode) & 0xFFFFFFFE)==0 );
140484     if( sqlite3FtsUnicodeIsalnum(iCode)!=bAlnum 
140485      && sqlite3FtsUnicodeIsdiacritic(iCode)==0 
140486     ){
140487       nEntry++;
140488     }
140489   }
140490 
140491   if( nEntry ){
140492     int *aNew;                    /* New aiException[] array */
140493     int nNew;                     /* Number of valid entries in array aNew[] */
140494 
140495     aNew = sqlite3_realloc(p->aiException, (p->nException+nEntry)*sizeof(int));
140496     if( aNew==0 ) return SQLITE_NOMEM;
140497     nNew = p->nException;
140498 
140499     z = (const unsigned char *)zIn;
140500     while( z<zTerm ){
140501       READ_UTF8(z, zTerm, iCode);
140502       if( sqlite3FtsUnicodeIsalnum(iCode)!=bAlnum 
140503        && sqlite3FtsUnicodeIsdiacritic(iCode)==0
140504       ){
140505         int i, j;
140506         for(i=0; i<nNew && aNew[i]<iCode; i++);
140507         for(j=nNew; j>i; j--) aNew[j] = aNew[j-1];
140508         aNew[i] = iCode;
140509         nNew++;
140510       }
140511     }
140512     p->aiException = aNew;
140513     p->nException = nNew;
140514   }
140515 
140516   return SQLITE_OK;
140517 }
140518 
140519 /*
140520 ** Return true if the p->aiException[] array contains the value iCode.
140521 */
140522 static int unicodeIsException(unicode_tokenizer *p, int iCode){
140523   if( p->nException>0 ){
140524     int *a = p->aiException;
140525     int iLo = 0;
140526     int iHi = p->nException-1;
140527 
140528     while( iHi>=iLo ){
140529       int iTest = (iHi + iLo) / 2;
140530       if( iCode==a[iTest] ){
140531         return 1;
140532       }else if( iCode>a[iTest] ){
140533         iLo = iTest+1;
140534       }else{
140535         iHi = iTest-1;
140536       }
140537     }
140538   }
140539 
140540   return 0;
140541 }
140542 
140543 /*
140544 ** Return true if, for the purposes of tokenization, codepoint iCode is
140545 ** considered a token character (not a separator).
140546 */
140547 static int unicodeIsAlnum(unicode_tokenizer *p, int iCode){
140548   assert( (sqlite3FtsUnicodeIsalnum(iCode) & 0xFFFFFFFE)==0 );
140549   return sqlite3FtsUnicodeIsalnum(iCode) ^ unicodeIsException(p, iCode);
140550 }
140551 
140552 /*
140553 ** Create a new tokenizer instance.
140554 */
140555 static int unicodeCreate(
140556   int nArg,                       /* Size of array argv[] */
140557   const char * const *azArg,      /* Tokenizer creation arguments */
140558   sqlite3_tokenizer **pp          /* OUT: New tokenizer handle */
140559 ){
140560   unicode_tokenizer *pNew;        /* New tokenizer object */
140561   int i;
140562   int rc = SQLITE_OK;
140563 
140564   pNew = (unicode_tokenizer *) sqlite3_malloc(sizeof(unicode_tokenizer));
140565   if( pNew==NULL ) return SQLITE_NOMEM;
140566   memset(pNew, 0, sizeof(unicode_tokenizer));
140567   pNew->bRemoveDiacritic = 1;
140568 
140569   for(i=0; rc==SQLITE_OK && i<nArg; i++){
140570     const char *z = azArg[i];
140571     int n = strlen(z);
140572 
140573     if( n==19 && memcmp("remove_diacritics=1", z, 19)==0 ){
140574       pNew->bRemoveDiacritic = 1;
140575     }
140576     else if( n==19 && memcmp("remove_diacritics=0", z, 19)==0 ){
140577       pNew->bRemoveDiacritic = 0;
140578     }
140579     else if( n>=11 && memcmp("tokenchars=", z, 11)==0 ){
140580       rc = unicodeAddExceptions(pNew, 1, &z[11], n-11);
140581     }
140582     else if( n>=11 && memcmp("separators=", z, 11)==0 ){
140583       rc = unicodeAddExceptions(pNew, 0, &z[11], n-11);
140584     }
140585     else{
140586       /* Unrecognized argument */
140587       rc  = SQLITE_ERROR;
140588     }
140589   }
140590 
140591   if( rc!=SQLITE_OK ){
140592     unicodeDestroy((sqlite3_tokenizer *)pNew);
140593     pNew = 0;
140594   }
140595   *pp = (sqlite3_tokenizer *)pNew;
140596   return rc;
140597 }
140598 
140599 /*
140600 ** Prepare to begin tokenizing a particular string.  The input
140601 ** string to be tokenized is pInput[0..nBytes-1].  A cursor
140602 ** used to incrementally tokenize this string is returned in 
140603 ** *ppCursor.
140604 */
140605 static int unicodeOpen(
140606   sqlite3_tokenizer *p,           /* The tokenizer */
140607   const char *aInput,             /* Input string */
140608   int nInput,                     /* Size of string aInput in bytes */
140609   sqlite3_tokenizer_cursor **pp   /* OUT: New cursor object */
140610 ){
140611   unicode_cursor *pCsr;
140612 
140613   pCsr = (unicode_cursor *)sqlite3_malloc(sizeof(unicode_cursor));
140614   if( pCsr==0 ){
140615     return SQLITE_NOMEM;
140616   }
140617   memset(pCsr, 0, sizeof(unicode_cursor));
140618 
140619   pCsr->aInput = (const unsigned char *)aInput;
140620   if( aInput==0 ){
140621     pCsr->nInput = 0;
140622   }else if( nInput<0 ){
140623     pCsr->nInput = (int)strlen(aInput);
140624   }else{
140625     pCsr->nInput = nInput;
140626   }
140627 
140628   *pp = &pCsr->base;
140629   UNUSED_PARAMETER(p);
140630   return SQLITE_OK;
140631 }
140632 
140633 /*
140634 ** Close a tokenization cursor previously opened by a call to
140635 ** simpleOpen() above.
140636 */
140637 static int unicodeClose(sqlite3_tokenizer_cursor *pCursor){
140638   unicode_cursor *pCsr = (unicode_cursor *) pCursor;
140639   sqlite3_free(pCsr->zToken);
140640   sqlite3_free(pCsr);
140641   return SQLITE_OK;
140642 }
140643 
140644 /*
140645 ** Extract the next token from a tokenization cursor.  The cursor must
140646 ** have been opened by a prior call to simpleOpen().
140647 */
140648 static int unicodeNext(
140649   sqlite3_tokenizer_cursor *pC,   /* Cursor returned by simpleOpen */
140650   const char **paToken,           /* OUT: Token text */
140651   int *pnToken,                   /* OUT: Number of bytes at *paToken */
140652   int *piStart,                   /* OUT: Starting offset of token */
140653   int *piEnd,                     /* OUT: Ending offset of token */
140654   int *piPos                      /* OUT: Position integer of token */
140655 ){
140656   unicode_cursor *pCsr = (unicode_cursor *)pC;
140657   unicode_tokenizer *p = ((unicode_tokenizer *)pCsr->base.pTokenizer);
140658   int iCode;
140659   char *zOut;
140660   const unsigned char *z = &pCsr->aInput[pCsr->iOff];
140661   const unsigned char *zStart = z;
140662   const unsigned char *zEnd;
140663   const unsigned char *zTerm = &pCsr->aInput[pCsr->nInput];
140664 
140665   /* Scan past any delimiter characters before the start of the next token.
140666   ** Return SQLITE_DONE early if this takes us all the way to the end of 
140667   ** the input.  */
140668   while( z<zTerm ){
140669     READ_UTF8(z, zTerm, iCode);
140670     if( unicodeIsAlnum(p, iCode) ) break;
140671     zStart = z;
140672   }
140673   if( zStart>=zTerm ) return SQLITE_DONE;
140674 
140675   zOut = pCsr->zToken;
140676   do {
140677     int iOut;
140678 
140679     /* Grow the output buffer if required. */
140680     if( (zOut-pCsr->zToken)>=(pCsr->nAlloc-4) ){
140681       char *zNew = sqlite3_realloc(pCsr->zToken, pCsr->nAlloc+64);
140682       if( !zNew ) return SQLITE_NOMEM;
140683       zOut = &zNew[zOut - pCsr->zToken];
140684       pCsr->zToken = zNew;
140685       pCsr->nAlloc += 64;
140686     }
140687 
140688     /* Write the folded case of the last character read to the output */
140689     zEnd = z;
140690     iOut = sqlite3FtsUnicodeFold(iCode, p->bRemoveDiacritic);
140691     if( iOut ){
140692       WRITE_UTF8(zOut, iOut);
140693     }
140694 
140695     /* If the cursor is not at EOF, read the next character */
140696     if( z>=zTerm ) break;
140697     READ_UTF8(z, zTerm, iCode);
140698   }while( unicodeIsAlnum(p, iCode) 
140699        || sqlite3FtsUnicodeIsdiacritic(iCode)
140700   );
140701 
140702   /* Set the output variables and return. */
140703   pCsr->iOff = (z - pCsr->aInput);
140704   *paToken = pCsr->zToken;
140705   *pnToken = zOut - pCsr->zToken;
140706   *piStart = (zStart - pCsr->aInput);
140707   *piEnd = (zEnd - pCsr->aInput);
140708   *piPos = pCsr->iToken++;
140709   return SQLITE_OK;
140710 }
140711 
140712 /*
140713 ** Set *ppModule to a pointer to the sqlite3_tokenizer_module 
140714 ** structure for the unicode tokenizer.
140715 */
140716 SQLITE_PRIVATE void sqlite3Fts3UnicodeTokenizer(sqlite3_tokenizer_module const **ppModule){
140717   static const sqlite3_tokenizer_module module = {
140718     0,
140719     unicodeCreate,
140720     unicodeDestroy,
140721     unicodeOpen,
140722     unicodeClose,
140723     unicodeNext,
140724     0,
140725   };
140726   *ppModule = &module;
140727 }
140728 
140729 #endif /* !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_FTS3) */
140730 #endif /* ifndef SQLITE_ENABLE_FTS4_UNICODE61 */
140731 
140732 /************** End of fts3_unicode.c ****************************************/
140733 /************** Begin file fts3_unicode2.c ***********************************/
140734 /*
140735 ** 2012 May 25
140736 **
140737 ** The author disclaims copyright to this source code.  In place of
140738 ** a legal notice, here is a blessing:
140739 **
140740 **    May you do good and not evil.
140741 **    May you find forgiveness for yourself and forgive others.
140742 **    May you share freely, never taking more than you give.
140743 **
140744 ******************************************************************************
140745 */
140746 
140747 /*
140748 ** DO NOT EDIT THIS MACHINE GENERATED FILE.
140749 */
140750 
140751 #if defined(SQLITE_ENABLE_FTS4_UNICODE61)
140752 #if defined(SQLITE_ENABLE_FTS3) || defined(SQLITE_ENABLE_FTS4)
140753 
140754 /* #include <assert.h> */
140755 
140756 /*
140757 ** Return true if the argument corresponds to a unicode codepoint
140758 ** classified as either a letter or a number. Otherwise false.
140759 **
140760 ** The results are undefined if the value passed to this function
140761 ** is less than zero.
140762 */
140763 SQLITE_PRIVATE int sqlite3FtsUnicodeIsalnum(int c){
140764   /* Each unsigned integer in the following array corresponds to a contiguous
140765   ** range of unicode codepoints that are not either letters or numbers (i.e.
140766   ** codepoints for which this function should return 0).
140767   **
140768   ** The most significant 22 bits in each 32-bit value contain the first 
140769   ** codepoint in the range. The least significant 10 bits are used to store
140770   ** the size of the range (always at least 1). In other words, the value 
140771   ** ((C<<22) + N) represents a range of N codepoints starting with codepoint 
140772   ** C. It is not possible to represent a range larger than 1023 codepoints 
140773   ** using this format.
140774   */
140775   const static unsigned int aEntry[] = {
140776     0x00000030, 0x0000E807, 0x00016C06, 0x0001EC2F, 0x0002AC07,
140777     0x0002D001, 0x0002D803, 0x0002EC01, 0x0002FC01, 0x00035C01,
140778     0x0003DC01, 0x000B0804, 0x000B480E, 0x000B9407, 0x000BB401,
140779     0x000BBC81, 0x000DD401, 0x000DF801, 0x000E1002, 0x000E1C01,
140780     0x000FD801, 0x00120808, 0x00156806, 0x00162402, 0x00163C01,
140781     0x00164437, 0x0017CC02, 0x00180005, 0x00181816, 0x00187802,
140782     0x00192C15, 0x0019A804, 0x0019C001, 0x001B5001, 0x001B580F,
140783     0x001B9C07, 0x001BF402, 0x001C000E, 0x001C3C01, 0x001C4401,
140784     0x001CC01B, 0x001E980B, 0x001FAC09, 0x001FD804, 0x00205804,
140785     0x00206C09, 0x00209403, 0x0020A405, 0x0020C00F, 0x00216403,
140786     0x00217801, 0x0023901B, 0x00240004, 0x0024E803, 0x0024F812,
140787     0x00254407, 0x00258804, 0x0025C001, 0x00260403, 0x0026F001,
140788     0x0026F807, 0x00271C02, 0x00272C03, 0x00275C01, 0x00278802,
140789     0x0027C802, 0x0027E802, 0x00280403, 0x0028F001, 0x0028F805,
140790     0x00291C02, 0x00292C03, 0x00294401, 0x0029C002, 0x0029D401,
140791     0x002A0403, 0x002AF001, 0x002AF808, 0x002B1C03, 0x002B2C03,
140792     0x002B8802, 0x002BC002, 0x002C0403, 0x002CF001, 0x002CF807,
140793     0x002D1C02, 0x002D2C03, 0x002D5802, 0x002D8802, 0x002DC001,
140794     0x002E0801, 0x002EF805, 0x002F1803, 0x002F2804, 0x002F5C01,
140795     0x002FCC08, 0x00300403, 0x0030F807, 0x00311803, 0x00312804,
140796     0x00315402, 0x00318802, 0x0031FC01, 0x00320802, 0x0032F001,
140797     0x0032F807, 0x00331803, 0x00332804, 0x00335402, 0x00338802,
140798     0x00340802, 0x0034F807, 0x00351803, 0x00352804, 0x00355C01,
140799     0x00358802, 0x0035E401, 0x00360802, 0x00372801, 0x00373C06,
140800     0x00375801, 0x00376008, 0x0037C803, 0x0038C401, 0x0038D007,
140801     0x0038FC01, 0x00391C09, 0x00396802, 0x003AC401, 0x003AD006,
140802     0x003AEC02, 0x003B2006, 0x003C041F, 0x003CD00C, 0x003DC417,
140803     0x003E340B, 0x003E6424, 0x003EF80F, 0x003F380D, 0x0040AC14,
140804     0x00412806, 0x00415804, 0x00417803, 0x00418803, 0x00419C07,
140805     0x0041C404, 0x0042080C, 0x00423C01, 0x00426806, 0x0043EC01,
140806     0x004D740C, 0x004E400A, 0x00500001, 0x0059B402, 0x005A0001,
140807     0x005A6C02, 0x005BAC03, 0x005C4803, 0x005CC805, 0x005D4802,
140808     0x005DC802, 0x005ED023, 0x005F6004, 0x005F7401, 0x0060000F,
140809     0x0062A401, 0x0064800C, 0x0064C00C, 0x00650001, 0x00651002,
140810     0x0066C011, 0x00672002, 0x00677822, 0x00685C05, 0x00687802,
140811     0x0069540A, 0x0069801D, 0x0069FC01, 0x006A8007, 0x006AA006,
140812     0x006C0005, 0x006CD011, 0x006D6823, 0x006E0003, 0x006E840D,
140813     0x006F980E, 0x006FF004, 0x00709014, 0x0070EC05, 0x0071F802,
140814     0x00730008, 0x00734019, 0x0073B401, 0x0073C803, 0x00770027,
140815     0x0077F004, 0x007EF401, 0x007EFC03, 0x007F3403, 0x007F7403,
140816     0x007FB403, 0x007FF402, 0x00800065, 0x0081A806, 0x0081E805,
140817     0x00822805, 0x0082801A, 0x00834021, 0x00840002, 0x00840C04,
140818     0x00842002, 0x00845001, 0x00845803, 0x00847806, 0x00849401,
140819     0x00849C01, 0x0084A401, 0x0084B801, 0x0084E802, 0x00850005,
140820     0x00852804, 0x00853C01, 0x00864264, 0x00900027, 0x0091000B,
140821     0x0092704E, 0x00940200, 0x009C0475, 0x009E53B9, 0x00AD400A,
140822     0x00B39406, 0x00B3BC03, 0x00B3E404, 0x00B3F802, 0x00B5C001,
140823     0x00B5FC01, 0x00B7804F, 0x00B8C00C, 0x00BA001A, 0x00BA6C59,
140824     0x00BC00D6, 0x00BFC00C, 0x00C00005, 0x00C02019, 0x00C0A807,
140825     0x00C0D802, 0x00C0F403, 0x00C26404, 0x00C28001, 0x00C3EC01,
140826     0x00C64002, 0x00C6580A, 0x00C70024, 0x00C8001F, 0x00C8A81E,
140827     0x00C94001, 0x00C98020, 0x00CA2827, 0x00CB003F, 0x00CC0100,
140828     0x01370040, 0x02924037, 0x0293F802, 0x02983403, 0x0299BC10,
140829     0x029A7C01, 0x029BC008, 0x029C0017, 0x029C8002, 0x029E2402,
140830     0x02A00801, 0x02A01801, 0x02A02C01, 0x02A08C09, 0x02A0D804,
140831     0x02A1D004, 0x02A20002, 0x02A2D011, 0x02A33802, 0x02A38012,
140832     0x02A3E003, 0x02A4980A, 0x02A51C0D, 0x02A57C01, 0x02A60004,
140833     0x02A6CC1B, 0x02A77802, 0x02A8A40E, 0x02A90C01, 0x02A93002,
140834     0x02A97004, 0x02A9DC03, 0x02A9EC01, 0x02AAC001, 0x02AAC803,
140835     0x02AADC02, 0x02AAF802, 0x02AB0401, 0x02AB7802, 0x02ABAC07,
140836     0x02ABD402, 0x02AF8C0B, 0x03600001, 0x036DFC02, 0x036FFC02,
140837     0x037FFC01, 0x03EC7801, 0x03ECA401, 0x03EEC810, 0x03F4F802,
140838     0x03F7F002, 0x03F8001A, 0x03F88007, 0x03F8C023, 0x03F95013,
140839     0x03F9A004, 0x03FBFC01, 0x03FC040F, 0x03FC6807, 0x03FCEC06,
140840     0x03FD6C0B, 0x03FF8007, 0x03FFA007, 0x03FFE405, 0x04040003,
140841     0x0404DC09, 0x0405E411, 0x0406400C, 0x0407402E, 0x040E7C01,
140842     0x040F4001, 0x04215C01, 0x04247C01, 0x0424FC01, 0x04280403,
140843     0x04281402, 0x04283004, 0x0428E003, 0x0428FC01, 0x04294009,
140844     0x0429FC01, 0x042CE407, 0x04400003, 0x0440E016, 0x04420003,
140845     0x0442C012, 0x04440003, 0x04449C0E, 0x04450004, 0x04460003,
140846     0x0446CC0E, 0x04471404, 0x045AAC0D, 0x0491C004, 0x05BD442E,
140847     0x05BE3C04, 0x074000F6, 0x07440027, 0x0744A4B5, 0x07480046,
140848     0x074C0057, 0x075B0401, 0x075B6C01, 0x075BEC01, 0x075C5401,
140849     0x075CD401, 0x075D3C01, 0x075DBC01, 0x075E2401, 0x075EA401,
140850     0x075F0C01, 0x07BBC002, 0x07C0002C, 0x07C0C064, 0x07C2800F,
140851     0x07C2C40E, 0x07C3040F, 0x07C3440F, 0x07C4401F, 0x07C4C03C,
140852     0x07C5C02B, 0x07C7981D, 0x07C8402B, 0x07C90009, 0x07C94002,
140853     0x07CC0021, 0x07CCC006, 0x07CCDC46, 0x07CE0014, 0x07CE8025,
140854     0x07CF1805, 0x07CF8011, 0x07D0003F, 0x07D10001, 0x07D108B6,
140855     0x07D3E404, 0x07D4003E, 0x07D50004, 0x07D54018, 0x07D7EC46,
140856     0x07D9140B, 0x07DA0046, 0x07DC0074, 0x38000401, 0x38008060,
140857     0x380400F0,
140858   };
140859   static const unsigned int aAscii[4] = {
140860     0xFFFFFFFF, 0xFC00FFFF, 0xF8000001, 0xF8000001,
140861   };
140862 
140863   if( c<128 ){
140864     return ( (aAscii[c >> 5] & (1 << (c & 0x001F)))==0 );
140865   }else if( c<(1<<22) ){
140866     unsigned int key = (((unsigned int)c)<<10) | 0x000003FF;
140867     int iRes;
140868     int iHi = sizeof(aEntry)/sizeof(aEntry[0]) - 1;
140869     int iLo = 0;
140870     while( iHi>=iLo ){
140871       int iTest = (iHi + iLo) / 2;
140872       if( key >= aEntry[iTest] ){
140873         iRes = iTest;
140874         iLo = iTest+1;
140875       }else{
140876         iHi = iTest-1;
140877       }
140878     }
140879     assert( aEntry[0]<key );
140880     assert( key>=aEntry[iRes] );
140881     return (((unsigned int)c) >= ((aEntry[iRes]>>10) + (aEntry[iRes]&0x3FF)));
140882   }
140883   return 1;
140884 }
140885 
140886 
140887 /*
140888 ** If the argument is a codepoint corresponding to a lowercase letter
140889 ** in the ASCII range with a diacritic added, return the codepoint
140890 ** of the ASCII letter only. For example, if passed 235 - "LATIN
140891 ** SMALL LETTER E WITH DIAERESIS" - return 65 ("LATIN SMALL LETTER
140892 ** E"). The resuls of passing a codepoint that corresponds to an
140893 ** uppercase letter are undefined.
140894 */
140895 static int remove_diacritic(int c){
140896   unsigned short aDia[] = {
140897         0,  1797,  1848,  1859,  1891,  1928,  1940,  1995, 
140898      2024,  2040,  2060,  2110,  2168,  2206,  2264,  2286, 
140899      2344,  2383,  2472,  2488,  2516,  2596,  2668,  2732, 
140900      2782,  2842,  2894,  2954,  2984,  3000,  3028,  3336, 
140901      3456,  3696,  3712,  3728,  3744,  3896,  3912,  3928, 
140902      3968,  4008,  4040,  4106,  4138,  4170,  4202,  4234, 
140903      4266,  4296,  4312,  4344,  4408,  4424,  4472,  4504, 
140904      6148,  6198,  6264,  6280,  6360,  6429,  6505,  6529, 
140905     61448, 61468, 61534, 61592, 61642, 61688, 61704, 61726, 
140906     61784, 61800, 61836, 61880, 61914, 61948, 61998, 62122, 
140907     62154, 62200, 62218, 62302, 62364, 62442, 62478, 62536, 
140908     62554, 62584, 62604, 62640, 62648, 62656, 62664, 62730, 
140909     62924, 63050, 63082, 63274, 63390, 
140910   };
140911   char aChar[] = {
140912     '\0', 'a',  'c',  'e',  'i',  'n',  'o',  'u',  'y',  'y',  'a',  'c',  
140913     'd',  'e',  'e',  'g',  'h',  'i',  'j',  'k',  'l',  'n',  'o',  'r',  
140914     's',  't',  'u',  'u',  'w',  'y',  'z',  'o',  'u',  'a',  'i',  'o',  
140915     'u',  'g',  'k',  'o',  'j',  'g',  'n',  'a',  'e',  'i',  'o',  'r',  
140916     'u',  's',  't',  'h',  'a',  'e',  'o',  'y',  '\0', '\0', '\0', '\0', 
140917     '\0', '\0', '\0', '\0', 'a',  'b',  'd',  'd',  'e',  'f',  'g',  'h',  
140918     'h',  'i',  'k',  'l',  'l',  'm',  'n',  'p',  'r',  'r',  's',  't',  
140919     'u',  'v',  'w',  'w',  'x',  'y',  'z',  'h',  't',  'w',  'y',  'a',  
140920     'e',  'i',  'o',  'u',  'y',  
140921   };
140922 
140923   unsigned int key = (((unsigned int)c)<<3) | 0x00000007;
140924   int iRes = 0;
140925   int iHi = sizeof(aDia)/sizeof(aDia[0]) - 1;
140926   int iLo = 0;
140927   while( iHi>=iLo ){
140928     int iTest = (iHi + iLo) / 2;
140929     if( key >= aDia[iTest] ){
140930       iRes = iTest;
140931       iLo = iTest+1;
140932     }else{
140933       iHi = iTest-1;
140934     }
140935   }
140936   assert( key>=aDia[iRes] );
140937   return ((c > (aDia[iRes]>>3) + (aDia[iRes]&0x07)) ? c : (int)aChar[iRes]);
140938 };
140939 
140940 
140941 /*
140942 ** Return true if the argument interpreted as a unicode codepoint
140943 ** is a diacritical modifier character.
140944 */
140945 SQLITE_PRIVATE int sqlite3FtsUnicodeIsdiacritic(int c){
140946   unsigned int mask0 = 0x08029FDF;
140947   unsigned int mask1 = 0x000361F8;
140948   if( c<768 || c>817 ) return 0;
140949   return (c < 768+32) ?
140950       (mask0 & (1 << (c-768))) :
140951       (mask1 & (1 << (c-768-32)));
140952 }
140953 
140954 
140955 /*
140956 ** Interpret the argument as a unicode codepoint. If the codepoint
140957 ** is an upper case character that has a lower case equivalent,
140958 ** return the codepoint corresponding to the lower case version.
140959 ** Otherwise, return a copy of the argument.
140960 **
140961 ** The results are undefined if the value passed to this function
140962 ** is less than zero.
140963 */
140964 SQLITE_PRIVATE int sqlite3FtsUnicodeFold(int c, int bRemoveDiacritic){
140965   /* Each entry in the following array defines a rule for folding a range
140966   ** of codepoints to lower case. The rule applies to a range of nRange
140967   ** codepoints starting at codepoint iCode.
140968   **
140969   ** If the least significant bit in flags is clear, then the rule applies
140970   ** to all nRange codepoints (i.e. all nRange codepoints are upper case and
140971   ** need to be folded). Or, if it is set, then the rule only applies to
140972   ** every second codepoint in the range, starting with codepoint C.
140973   **
140974   ** The 7 most significant bits in flags are an index into the aiOff[]
140975   ** array. If a specific codepoint C does require folding, then its lower
140976   ** case equivalent is ((C + aiOff[flags>>1]) & 0xFFFF).
140977   **
140978   ** The contents of this array are generated by parsing the CaseFolding.txt
140979   ** file distributed as part of the "Unicode Character Database". See
140980   ** http://www.unicode.org for details.
140981   */
140982   static const struct TableEntry {
140983     unsigned short iCode;
140984     unsigned char flags;
140985     unsigned char nRange;
140986   } aEntry[] = {
140987     {65, 14, 26},          {181, 64, 1},          {192, 14, 23},
140988     {216, 14, 7},          {256, 1, 48},          {306, 1, 6},
140989     {313, 1, 16},          {330, 1, 46},          {376, 116, 1},
140990     {377, 1, 6},           {383, 104, 1},         {385, 50, 1},
140991     {386, 1, 4},           {390, 44, 1},          {391, 0, 1},
140992     {393, 42, 2},          {395, 0, 1},           {398, 32, 1},
140993     {399, 38, 1},          {400, 40, 1},          {401, 0, 1},
140994     {403, 42, 1},          {404, 46, 1},          {406, 52, 1},
140995     {407, 48, 1},          {408, 0, 1},           {412, 52, 1},
140996     {413, 54, 1},          {415, 56, 1},          {416, 1, 6},
140997     {422, 60, 1},          {423, 0, 1},           {425, 60, 1},
140998     {428, 0, 1},           {430, 60, 1},          {431, 0, 1},
140999     {433, 58, 2},          {435, 1, 4},           {439, 62, 1},
141000     {440, 0, 1},           {444, 0, 1},           {452, 2, 1},
141001     {453, 0, 1},           {455, 2, 1},           {456, 0, 1},
141002     {458, 2, 1},           {459, 1, 18},          {478, 1, 18},
141003     {497, 2, 1},           {498, 1, 4},           {502, 122, 1},
141004     {503, 134, 1},         {504, 1, 40},          {544, 110, 1},
141005     {546, 1, 18},          {570, 70, 1},          {571, 0, 1},
141006     {573, 108, 1},         {574, 68, 1},          {577, 0, 1},
141007     {579, 106, 1},         {580, 28, 1},          {581, 30, 1},
141008     {582, 1, 10},          {837, 36, 1},          {880, 1, 4},
141009     {886, 0, 1},           {902, 18, 1},          {904, 16, 3},
141010     {908, 26, 1},          {910, 24, 2},          {913, 14, 17},
141011     {931, 14, 9},          {962, 0, 1},           {975, 4, 1},
141012     {976, 140, 1},         {977, 142, 1},         {981, 146, 1},
141013     {982, 144, 1},         {984, 1, 24},          {1008, 136, 1},
141014     {1009, 138, 1},        {1012, 130, 1},        {1013, 128, 1},
141015     {1015, 0, 1},          {1017, 152, 1},        {1018, 0, 1},
141016     {1021, 110, 3},        {1024, 34, 16},        {1040, 14, 32},
141017     {1120, 1, 34},         {1162, 1, 54},         {1216, 6, 1},
141018     {1217, 1, 14},         {1232, 1, 88},         {1329, 22, 38},
141019     {4256, 66, 38},        {4295, 66, 1},         {4301, 66, 1},
141020     {7680, 1, 150},        {7835, 132, 1},        {7838, 96, 1},
141021     {7840, 1, 96},         {7944, 150, 8},        {7960, 150, 6},
141022     {7976, 150, 8},        {7992, 150, 8},        {8008, 150, 6},
141023     {8025, 151, 8},        {8040, 150, 8},        {8072, 150, 8},
141024     {8088, 150, 8},        {8104, 150, 8},        {8120, 150, 2},
141025     {8122, 126, 2},        {8124, 148, 1},        {8126, 100, 1},
141026     {8136, 124, 4},        {8140, 148, 1},        {8152, 150, 2},
141027     {8154, 120, 2},        {8168, 150, 2},        {8170, 118, 2},
141028     {8172, 152, 1},        {8184, 112, 2},        {8186, 114, 2},
141029     {8188, 148, 1},        {8486, 98, 1},         {8490, 92, 1},
141030     {8491, 94, 1},         {8498, 12, 1},         {8544, 8, 16},
141031     {8579, 0, 1},          {9398, 10, 26},        {11264, 22, 47},
141032     {11360, 0, 1},         {11362, 88, 1},        {11363, 102, 1},
141033     {11364, 90, 1},        {11367, 1, 6},         {11373, 84, 1},
141034     {11374, 86, 1},        {11375, 80, 1},        {11376, 82, 1},
141035     {11378, 0, 1},         {11381, 0, 1},         {11390, 78, 2},
141036     {11392, 1, 100},       {11499, 1, 4},         {11506, 0, 1},
141037     {42560, 1, 46},        {42624, 1, 24},        {42786, 1, 14},
141038     {42802, 1, 62},        {42873, 1, 4},         {42877, 76, 1},
141039     {42878, 1, 10},        {42891, 0, 1},         {42893, 74, 1},
141040     {42896, 1, 4},         {42912, 1, 10},        {42922, 72, 1},
141041     {65313, 14, 26},       
141042   };
141043   static const unsigned short aiOff[] = {
141044    1,     2,     8,     15,    16,    26,    28,    32,    
141045    37,    38,    40,    48,    63,    64,    69,    71,    
141046    79,    80,    116,   202,   203,   205,   206,   207,   
141047    209,   210,   211,   213,   214,   217,   218,   219,   
141048    775,   7264,  10792, 10795, 23228, 23256, 30204, 54721, 
141049    54753, 54754, 54756, 54787, 54793, 54809, 57153, 57274, 
141050    57921, 58019, 58363, 61722, 65268, 65341, 65373, 65406, 
141051    65408, 65410, 65415, 65424, 65436, 65439, 65450, 65462, 
141052    65472, 65476, 65478, 65480, 65482, 65488, 65506, 65511, 
141053    65514, 65521, 65527, 65528, 65529, 
141054   };
141055 
141056   int ret = c;
141057 
141058   assert( c>=0 );
141059   assert( sizeof(unsigned short)==2 && sizeof(unsigned char)==1 );
141060 
141061   if( c<128 ){
141062     if( c>='A' && c<='Z' ) ret = c + ('a' - 'A');
141063   }else if( c<65536 ){
141064     int iHi = sizeof(aEntry)/sizeof(aEntry[0]) - 1;
141065     int iLo = 0;
141066     int iRes = -1;
141067 
141068     while( iHi>=iLo ){
141069       int iTest = (iHi + iLo) / 2;
141070       int cmp = (c - aEntry[iTest].iCode);
141071       if( cmp>=0 ){
141072         iRes = iTest;
141073         iLo = iTest+1;
141074       }else{
141075         iHi = iTest-1;
141076       }
141077     }
141078     assert( iRes<0 || c>=aEntry[iRes].iCode );
141079 
141080     if( iRes>=0 ){
141081       const struct TableEntry *p = &aEntry[iRes];
141082       if( c<(p->iCode + p->nRange) && 0==(0x01 & p->flags & (p->iCode ^ c)) ){
141083         ret = (c + (aiOff[p->flags>>1])) & 0x0000FFFF;
141084         assert( ret>0 );
141085       }
141086     }
141087 
141088     if( bRemoveDiacritic ) ret = remove_diacritic(ret);
141089   }
141090   
141091   else if( c>=66560 && c<66600 ){
141092     ret = c + 40;
141093   }
141094 
141095   return ret;
141096 }
141097 #endif /* defined(SQLITE_ENABLE_FTS3) || defined(SQLITE_ENABLE_FTS4) */
141098 #endif /* !defined(SQLITE_ENABLE_FTS4_UNICODE61) */
141099 
141100 /************** End of fts3_unicode2.c ***************************************/
141101 /************** Begin file rtree.c *******************************************/
141102 /*
141103 ** 2001 September 15
141104 **
141105 ** The author disclaims copyright to this source code.  In place of
141106 ** a legal notice, here is a blessing:
141107 **
141108 **    May you do good and not evil.
141109 **    May you find forgiveness for yourself and forgive others.
141110 **    May you share freely, never taking more than you give.
141111 **
141112 *************************************************************************
141113 ** This file contains code for implementations of the r-tree and r*-tree
141114 ** algorithms packaged as an SQLite virtual table module.
141115 */
141116 
141117 /*
141118 ** Database Format of R-Tree Tables
141119 ** --------------------------------
141120 **
141121 ** The data structure for a single virtual r-tree table is stored in three 
141122 ** native SQLite tables declared as follows. In each case, the '%' character
141123 ** in the table name is replaced with the user-supplied name of the r-tree
141124 ** table.
141125 **
141126 **   CREATE TABLE %_node(nodeno INTEGER PRIMARY KEY, data BLOB)
141127 **   CREATE TABLE %_parent(nodeno INTEGER PRIMARY KEY, parentnode INTEGER)
141128 **   CREATE TABLE %_rowid(rowid INTEGER PRIMARY KEY, nodeno INTEGER)
141129 **
141130 ** The data for each node of the r-tree structure is stored in the %_node
141131 ** table. For each node that is not the root node of the r-tree, there is
141132 ** an entry in the %_parent table associating the node with its parent.
141133 ** And for each row of data in the table, there is an entry in the %_rowid
141134 ** table that maps from the entries rowid to the id of the node that it
141135 ** is stored on.
141136 **
141137 ** The root node of an r-tree always exists, even if the r-tree table is
141138 ** empty. The nodeno of the root node is always 1. All other nodes in the
141139 ** table must be the same size as the root node. The content of each node
141140 ** is formatted as follows:
141141 **
141142 **   1. If the node is the root node (node 1), then the first 2 bytes
141143 **      of the node contain the tree depth as a big-endian integer.
141144 **      For non-root nodes, the first 2 bytes are left unused.
141145 **
141146 **   2. The next 2 bytes contain the number of entries currently 
141147 **      stored in the node.
141148 **
141149 **   3. The remainder of the node contains the node entries. Each entry
141150 **      consists of a single 8-byte integer followed by an even number
141151 **      of 4-byte coordinates. For leaf nodes the integer is the rowid
141152 **      of a record. For internal nodes it is the node number of a
141153 **      child page.
141154 */
141155 
141156 #if !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_RTREE)
141157 
141158 /*
141159 ** This file contains an implementation of a couple of different variants
141160 ** of the r-tree algorithm. See the README file for further details. The 
141161 ** same data-structure is used for all, but the algorithms for insert and
141162 ** delete operations vary. The variants used are selected at compile time 
141163 ** by defining the following symbols:
141164 */
141165 
141166 /* Either, both or none of the following may be set to activate 
141167 ** r*tree variant algorithms.
141168 */
141169 #define VARIANT_RSTARTREE_CHOOSESUBTREE 0
141170 #define VARIANT_RSTARTREE_REINSERT      1
141171 
141172 /* 
141173 ** Exactly one of the following must be set to 1.
141174 */
141175 #define VARIANT_GUTTMAN_QUADRATIC_SPLIT 0
141176 #define VARIANT_GUTTMAN_LINEAR_SPLIT    0
141177 #define VARIANT_RSTARTREE_SPLIT         1
141178 
141179 #define VARIANT_GUTTMAN_SPLIT \
141180         (VARIANT_GUTTMAN_LINEAR_SPLIT||VARIANT_GUTTMAN_QUADRATIC_SPLIT)
141181 
141182 #if VARIANT_GUTTMAN_QUADRATIC_SPLIT
141183   #define PickNext QuadraticPickNext
141184   #define PickSeeds QuadraticPickSeeds
141185   #define AssignCells splitNodeGuttman
141186 #endif
141187 #if VARIANT_GUTTMAN_LINEAR_SPLIT
141188   #define PickNext LinearPickNext
141189   #define PickSeeds LinearPickSeeds
141190   #define AssignCells splitNodeGuttman
141191 #endif
141192 #if VARIANT_RSTARTREE_SPLIT
141193   #define AssignCells splitNodeStartree
141194 #endif
141195 
141196 #if !defined(NDEBUG) && !defined(SQLITE_DEBUG) 
141197 # define NDEBUG 1
141198 #endif
141199 
141200 #ifndef SQLITE_CORE
141201   SQLITE_EXTENSION_INIT1
141202 #else
141203 #endif
141204 
141205 /* #include <string.h> */
141206 /* #include <assert.h> */
141207 
141208 #ifndef SQLITE_AMALGAMATION
141209 #include "sqlite3rtree.h"
141210 typedef sqlite3_int64 i64;
141211 typedef unsigned char u8;
141212 typedef unsigned int u32;
141213 #endif
141214 
141215 /*  The following macro is used to suppress compiler warnings.
141216 */
141217 #ifndef UNUSED_PARAMETER
141218 # define UNUSED_PARAMETER(x) (void)(x)
141219 #endif
141220 
141221 typedef struct Rtree Rtree;
141222 typedef struct RtreeCursor RtreeCursor;
141223 typedef struct RtreeNode RtreeNode;
141224 typedef struct RtreeCell RtreeCell;
141225 typedef struct RtreeConstraint RtreeConstraint;
141226 typedef struct RtreeMatchArg RtreeMatchArg;
141227 typedef struct RtreeGeomCallback RtreeGeomCallback;
141228 typedef union RtreeCoord RtreeCoord;
141229 
141230 /* The rtree may have between 1 and RTREE_MAX_DIMENSIONS dimensions. */
141231 #define RTREE_MAX_DIMENSIONS 5
141232 
141233 /* Size of hash table Rtree.aHash. This hash table is not expected to
141234 ** ever contain very many entries, so a fixed number of buckets is 
141235 ** used.
141236 */
141237 #define HASHSIZE 128
141238 
141239 /* The xBestIndex method of this virtual table requires an estimate of
141240 ** the number of rows in the virtual table to calculate the costs of
141241 ** various strategies. If possible, this estimate is loaded from the
141242 ** sqlite_stat1 table (with RTREE_MIN_ROWEST as a hard-coded minimum).
141243 ** Otherwise, if no sqlite_stat1 entry is available, use 
141244 ** RTREE_DEFAULT_ROWEST.
141245 */
141246 #define RTREE_DEFAULT_ROWEST 1048576
141247 #define RTREE_MIN_ROWEST         100
141248 
141249 /* 
141250 ** An rtree virtual-table object.
141251 */
141252 struct Rtree {
141253   sqlite3_vtab base;
141254   sqlite3 *db;                /* Host database connection */
141255   int iNodeSize;              /* Size in bytes of each node in the node table */
141256   int nDim;                   /* Number of dimensions */
141257   int nBytesPerCell;          /* Bytes consumed per cell */
141258   int iDepth;                 /* Current depth of the r-tree structure */
141259   char *zDb;                  /* Name of database containing r-tree table */
141260   char *zName;                /* Name of r-tree table */ 
141261   RtreeNode *aHash[HASHSIZE]; /* Hash table of in-memory nodes. */ 
141262   int nBusy;                  /* Current number of users of this structure */
141263   i64 nRowEst;                /* Estimated number of rows in this table */
141264 
141265   /* List of nodes removed during a CondenseTree operation. List is
141266   ** linked together via the pointer normally used for hash chains -
141267   ** RtreeNode.pNext. RtreeNode.iNode stores the depth of the sub-tree 
141268   ** headed by the node (leaf nodes have RtreeNode.iNode==0).
141269   */
141270   RtreeNode *pDeleted;
141271   int iReinsertHeight;        /* Height of sub-trees Reinsert() has run on */
141272 
141273   /* Statements to read/write/delete a record from xxx_node */
141274   sqlite3_stmt *pReadNode;
141275   sqlite3_stmt *pWriteNode;
141276   sqlite3_stmt *pDeleteNode;
141277 
141278   /* Statements to read/write/delete a record from xxx_rowid */
141279   sqlite3_stmt *pReadRowid;
141280   sqlite3_stmt *pWriteRowid;
141281   sqlite3_stmt *pDeleteRowid;
141282 
141283   /* Statements to read/write/delete a record from xxx_parent */
141284   sqlite3_stmt *pReadParent;
141285   sqlite3_stmt *pWriteParent;
141286   sqlite3_stmt *pDeleteParent;
141287 
141288   int eCoordType;
141289 };
141290 
141291 /* Possible values for eCoordType: */
141292 #define RTREE_COORD_REAL32 0
141293 #define RTREE_COORD_INT32  1
141294 
141295 /*
141296 ** If SQLITE_RTREE_INT_ONLY is defined, then this virtual table will
141297 ** only deal with integer coordinates.  No floating point operations
141298 ** will be done.
141299 */
141300 #ifdef SQLITE_RTREE_INT_ONLY
141301   typedef sqlite3_int64 RtreeDValue;       /* High accuracy coordinate */
141302   typedef int RtreeValue;                  /* Low accuracy coordinate */
141303 #else
141304   typedef double RtreeDValue;              /* High accuracy coordinate */
141305   typedef float RtreeValue;                /* Low accuracy coordinate */
141306 #endif
141307 
141308 /*
141309 ** The minimum number of cells allowed for a node is a third of the 
141310 ** maximum. In Gutman's notation:
141311 **
141312 **     m = M/3
141313 **
141314 ** If an R*-tree "Reinsert" operation is required, the same number of
141315 ** cells are removed from the overfull node and reinserted into the tree.
141316 */
141317 #define RTREE_MINCELLS(p) ((((p)->iNodeSize-4)/(p)->nBytesPerCell)/3)
141318 #define RTREE_REINSERT(p) RTREE_MINCELLS(p)
141319 #define RTREE_MAXCELLS 51
141320 
141321 /*
141322 ** The smallest possible node-size is (512-64)==448 bytes. And the largest
141323 ** supported cell size is 48 bytes (8 byte rowid + ten 4 byte coordinates).
141324 ** Therefore all non-root nodes must contain at least 3 entries. Since 
141325 ** 2^40 is greater than 2^64, an r-tree structure always has a depth of
141326 ** 40 or less.
141327 */
141328 #define RTREE_MAX_DEPTH 40
141329 
141330 /* 
141331 ** An rtree cursor object.
141332 */
141333 struct RtreeCursor {
141334   sqlite3_vtab_cursor base;
141335   RtreeNode *pNode;                 /* Node cursor is currently pointing at */
141336   int iCell;                        /* Index of current cell in pNode */
141337   int iStrategy;                    /* Copy of idxNum search parameter */
141338   int nConstraint;                  /* Number of entries in aConstraint */
141339   RtreeConstraint *aConstraint;     /* Search constraints. */
141340 };
141341 
141342 union RtreeCoord {
141343   RtreeValue f;
141344   int i;
141345 };
141346 
141347 /*
141348 ** The argument is an RtreeCoord. Return the value stored within the RtreeCoord
141349 ** formatted as a RtreeDValue (double or int64). This macro assumes that local
141350 ** variable pRtree points to the Rtree structure associated with the
141351 ** RtreeCoord.
141352 */
141353 #ifdef SQLITE_RTREE_INT_ONLY
141354 # define DCOORD(coord) ((RtreeDValue)coord.i)
141355 #else
141356 # define DCOORD(coord) (                           \
141357     (pRtree->eCoordType==RTREE_COORD_REAL32) ?      \
141358       ((double)coord.f) :                           \
141359       ((double)coord.i)                             \
141360   )
141361 #endif
141362 
141363 /*
141364 ** A search constraint.
141365 */
141366 struct RtreeConstraint {
141367   int iCoord;                     /* Index of constrained coordinate */
141368   int op;                         /* Constraining operation */
141369   RtreeDValue rValue;             /* Constraint value. */
141370   int (*xGeom)(sqlite3_rtree_geometry*, int, RtreeDValue*, int*);
141371   sqlite3_rtree_geometry *pGeom;  /* Constraint callback argument for a MATCH */
141372 };
141373 
141374 /* Possible values for RtreeConstraint.op */
141375 #define RTREE_EQ    0x41
141376 #define RTREE_LE    0x42
141377 #define RTREE_LT    0x43
141378 #define RTREE_GE    0x44
141379 #define RTREE_GT    0x45
141380 #define RTREE_MATCH 0x46
141381 
141382 /* 
141383 ** An rtree structure node.
141384 */
141385 struct RtreeNode {
141386   RtreeNode *pParent;               /* Parent node */
141387   i64 iNode;
141388   int nRef;
141389   int isDirty;
141390   u8 *zData;
141391   RtreeNode *pNext;                 /* Next node in this hash chain */
141392 };
141393 #define NCELL(pNode) readInt16(&(pNode)->zData[2])
141394 
141395 /* 
141396 ** Structure to store a deserialized rtree record.
141397 */
141398 struct RtreeCell {
141399   i64 iRowid;
141400   RtreeCoord aCoord[RTREE_MAX_DIMENSIONS*2];
141401 };
141402 
141403 
141404 /*
141405 ** Value for the first field of every RtreeMatchArg object. The MATCH
141406 ** operator tests that the first field of a blob operand matches this
141407 ** value to avoid operating on invalid blobs (which could cause a segfault).
141408 */
141409 #define RTREE_GEOMETRY_MAGIC 0x891245AB
141410 
141411 /*
141412 ** An instance of this structure must be supplied as a blob argument to
141413 ** the right-hand-side of an SQL MATCH operator used to constrain an
141414 ** r-tree query.
141415 */
141416 struct RtreeMatchArg {
141417   u32 magic;                      /* Always RTREE_GEOMETRY_MAGIC */
141418   int (*xGeom)(sqlite3_rtree_geometry *, int, RtreeDValue*, int *);
141419   void *pContext;
141420   int nParam;
141421   RtreeDValue aParam[1];
141422 };
141423 
141424 /*
141425 ** When a geometry callback is created (see sqlite3_rtree_geometry_callback),
141426 ** a single instance of the following structure is allocated. It is used
141427 ** as the context for the user-function created by by s_r_g_c(). The object
141428 ** is eventually deleted by the destructor mechanism provided by
141429 ** sqlite3_create_function_v2() (which is called by s_r_g_c() to create
141430 ** the geometry callback function).
141431 */
141432 struct RtreeGeomCallback {
141433   int (*xGeom)(sqlite3_rtree_geometry*, int, RtreeDValue*, int*);
141434   void *pContext;
141435 };
141436 
141437 #ifndef MAX
141438 # define MAX(x,y) ((x) < (y) ? (y) : (x))
141439 #endif
141440 #ifndef MIN
141441 # define MIN(x,y) ((x) > (y) ? (y) : (x))
141442 #endif
141443 
141444 /*
141445 ** Functions to deserialize a 16 bit integer, 32 bit real number and
141446 ** 64 bit integer. The deserialized value is returned.
141447 */
141448 static int readInt16(u8 *p){
141449   return (p[0]<<8) + p[1];
141450 }
141451 static void readCoord(u8 *p, RtreeCoord *pCoord){
141452   u32 i = (
141453     (((u32)p[0]) << 24) + 
141454     (((u32)p[1]) << 16) + 
141455     (((u32)p[2]) <<  8) + 
141456     (((u32)p[3]) <<  0)
141457   );
141458   *(u32 *)pCoord = i;
141459 }
141460 static i64 readInt64(u8 *p){
141461   return (
141462     (((i64)p[0]) << 56) + 
141463     (((i64)p[1]) << 48) + 
141464     (((i64)p[2]) << 40) + 
141465     (((i64)p[3]) << 32) + 
141466     (((i64)p[4]) << 24) + 
141467     (((i64)p[5]) << 16) + 
141468     (((i64)p[6]) <<  8) + 
141469     (((i64)p[7]) <<  0)
141470   );
141471 }
141472 
141473 /*
141474 ** Functions to serialize a 16 bit integer, 32 bit real number and
141475 ** 64 bit integer. The value returned is the number of bytes written
141476 ** to the argument buffer (always 2, 4 and 8 respectively).
141477 */
141478 static int writeInt16(u8 *p, int i){
141479   p[0] = (i>> 8)&0xFF;
141480   p[1] = (i>> 0)&0xFF;
141481   return 2;
141482 }
141483 static int writeCoord(u8 *p, RtreeCoord *pCoord){
141484   u32 i;
141485   assert( sizeof(RtreeCoord)==4 );
141486   assert( sizeof(u32)==4 );
141487   i = *(u32 *)pCoord;
141488   p[0] = (i>>24)&0xFF;
141489   p[1] = (i>>16)&0xFF;
141490   p[2] = (i>> 8)&0xFF;
141491   p[3] = (i>> 0)&0xFF;
141492   return 4;
141493 }
141494 static int writeInt64(u8 *p, i64 i){
141495   p[0] = (i>>56)&0xFF;
141496   p[1] = (i>>48)&0xFF;
141497   p[2] = (i>>40)&0xFF;
141498   p[3] = (i>>32)&0xFF;
141499   p[4] = (i>>24)&0xFF;
141500   p[5] = (i>>16)&0xFF;
141501   p[6] = (i>> 8)&0xFF;
141502   p[7] = (i>> 0)&0xFF;
141503   return 8;
141504 }
141505 
141506 /*
141507 ** Increment the reference count of node p.
141508 */
141509 static void nodeReference(RtreeNode *p){
141510   if( p ){
141511     p->nRef++;
141512   }
141513 }
141514 
141515 /*
141516 ** Clear the content of node p (set all bytes to 0x00).
141517 */
141518 static void nodeZero(Rtree *pRtree, RtreeNode *p){
141519   memset(&p->zData[2], 0, pRtree->iNodeSize-2);
141520   p->isDirty = 1;
141521 }
141522 
141523 /*
141524 ** Given a node number iNode, return the corresponding key to use
141525 ** in the Rtree.aHash table.
141526 */
141527 static int nodeHash(i64 iNode){
141528   return (
141529     (iNode>>56) ^ (iNode>>48) ^ (iNode>>40) ^ (iNode>>32) ^ 
141530     (iNode>>24) ^ (iNode>>16) ^ (iNode>> 8) ^ (iNode>> 0)
141531   ) % HASHSIZE;
141532 }
141533 
141534 /*
141535 ** Search the node hash table for node iNode. If found, return a pointer
141536 ** to it. Otherwise, return 0.
141537 */
141538 static RtreeNode *nodeHashLookup(Rtree *pRtree, i64 iNode){
141539   RtreeNode *p;
141540   for(p=pRtree->aHash[nodeHash(iNode)]; p && p->iNode!=iNode; p=p->pNext);
141541   return p;
141542 }
141543 
141544 /*
141545 ** Add node pNode to the node hash table.
141546 */
141547 static void nodeHashInsert(Rtree *pRtree, RtreeNode *pNode){
141548   int iHash;
141549   assert( pNode->pNext==0 );
141550   iHash = nodeHash(pNode->iNode);
141551   pNode->pNext = pRtree->aHash[iHash];
141552   pRtree->aHash[iHash] = pNode;
141553 }
141554 
141555 /*
141556 ** Remove node pNode from the node hash table.
141557 */
141558 static void nodeHashDelete(Rtree *pRtree, RtreeNode *pNode){
141559   RtreeNode **pp;
141560   if( pNode->iNode!=0 ){
141561     pp = &pRtree->aHash[nodeHash(pNode->iNode)];
141562     for( ; (*pp)!=pNode; pp = &(*pp)->pNext){ assert(*pp); }
141563     *pp = pNode->pNext;
141564     pNode->pNext = 0;
141565   }
141566 }
141567 
141568 /*
141569 ** Allocate and return new r-tree node. Initially, (RtreeNode.iNode==0),
141570 ** indicating that node has not yet been assigned a node number. It is
141571 ** assigned a node number when nodeWrite() is called to write the
141572 ** node contents out to the database.
141573 */
141574 static RtreeNode *nodeNew(Rtree *pRtree, RtreeNode *pParent){
141575   RtreeNode *pNode;
141576   pNode = (RtreeNode *)sqlite3_malloc(sizeof(RtreeNode) + pRtree->iNodeSize);
141577   if( pNode ){
141578     memset(pNode, 0, sizeof(RtreeNode) + pRtree->iNodeSize);
141579     pNode->zData = (u8 *)&pNode[1];
141580     pNode->nRef = 1;
141581     pNode->pParent = pParent;
141582     pNode->isDirty = 1;
141583     nodeReference(pParent);
141584   }
141585   return pNode;
141586 }
141587 
141588 /*
141589 ** Obtain a reference to an r-tree node.
141590 */
141591 static int
141592 nodeAcquire(
141593   Rtree *pRtree,             /* R-tree structure */
141594   i64 iNode,                 /* Node number to load */
141595   RtreeNode *pParent,        /* Either the parent node or NULL */
141596   RtreeNode **ppNode         /* OUT: Acquired node */
141597 ){
141598   int rc;
141599   int rc2 = SQLITE_OK;
141600   RtreeNode *pNode;
141601 
141602   /* Check if the requested node is already in the hash table. If so,
141603   ** increase its reference count and return it.
141604   */
141605   if( (pNode = nodeHashLookup(pRtree, iNode)) ){
141606     assert( !pParent || !pNode->pParent || pNode->pParent==pParent );
141607     if( pParent && !pNode->pParent ){
141608       nodeReference(pParent);
141609       pNode->pParent = pParent;
141610     }
141611     pNode->nRef++;
141612     *ppNode = pNode;
141613     return SQLITE_OK;
141614   }
141615 
141616   sqlite3_bind_int64(pRtree->pReadNode, 1, iNode);
141617   rc = sqlite3_step(pRtree->pReadNode);
141618   if( rc==SQLITE_ROW ){
141619     const u8 *zBlob = sqlite3_column_blob(pRtree->pReadNode, 0);
141620     if( pRtree->iNodeSize==sqlite3_column_bytes(pRtree->pReadNode, 0) ){
141621       pNode = (RtreeNode *)sqlite3_malloc(sizeof(RtreeNode)+pRtree->iNodeSize);
141622       if( !pNode ){
141623         rc2 = SQLITE_NOMEM;
141624       }else{
141625         pNode->pParent = pParent;
141626         pNode->zData = (u8 *)&pNode[1];
141627         pNode->nRef = 1;
141628         pNode->iNode = iNode;
141629         pNode->isDirty = 0;
141630         pNode->pNext = 0;
141631         memcpy(pNode->zData, zBlob, pRtree->iNodeSize);
141632         nodeReference(pParent);
141633       }
141634     }
141635   }
141636   rc = sqlite3_reset(pRtree->pReadNode);
141637   if( rc==SQLITE_OK ) rc = rc2;
141638 
141639   /* If the root node was just loaded, set pRtree->iDepth to the height
141640   ** of the r-tree structure. A height of zero means all data is stored on
141641   ** the root node. A height of one means the children of the root node
141642   ** are the leaves, and so on. If the depth as specified on the root node
141643   ** is greater than RTREE_MAX_DEPTH, the r-tree structure must be corrupt.
141644   */
141645   if( pNode && iNode==1 ){
141646     pRtree->iDepth = readInt16(pNode->zData);
141647     if( pRtree->iDepth>RTREE_MAX_DEPTH ){
141648       rc = SQLITE_CORRUPT_VTAB;
141649     }
141650   }
141651 
141652   /* If no error has occurred so far, check if the "number of entries"
141653   ** field on the node is too large. If so, set the return code to 
141654   ** SQLITE_CORRUPT_VTAB.
141655   */
141656   if( pNode && rc==SQLITE_OK ){
141657     if( NCELL(pNode)>((pRtree->iNodeSize-4)/pRtree->nBytesPerCell) ){
141658       rc = SQLITE_CORRUPT_VTAB;
141659     }
141660   }
141661 
141662   if( rc==SQLITE_OK ){
141663     if( pNode!=0 ){
141664       nodeHashInsert(pRtree, pNode);
141665     }else{
141666       rc = SQLITE_CORRUPT_VTAB;
141667     }
141668     *ppNode = pNode;
141669   }else{
141670     sqlite3_free(pNode);
141671     *ppNode = 0;
141672   }
141673 
141674   return rc;
141675 }
141676 
141677 /*
141678 ** Overwrite cell iCell of node pNode with the contents of pCell.
141679 */
141680 static void nodeOverwriteCell(
141681   Rtree *pRtree, 
141682   RtreeNode *pNode,  
141683   RtreeCell *pCell, 
141684   int iCell
141685 ){
141686   int ii;
141687   u8 *p = &pNode->zData[4 + pRtree->nBytesPerCell*iCell];
141688   p += writeInt64(p, pCell->iRowid);
141689   for(ii=0; ii<(pRtree->nDim*2); ii++){
141690     p += writeCoord(p, &pCell->aCoord[ii]);
141691   }
141692   pNode->isDirty = 1;
141693 }
141694 
141695 /*
141696 ** Remove cell the cell with index iCell from node pNode.
141697 */
141698 static void nodeDeleteCell(Rtree *pRtree, RtreeNode *pNode, int iCell){
141699   u8 *pDst = &pNode->zData[4 + pRtree->nBytesPerCell*iCell];
141700   u8 *pSrc = &pDst[pRtree->nBytesPerCell];
141701   int nByte = (NCELL(pNode) - iCell - 1) * pRtree->nBytesPerCell;
141702   memmove(pDst, pSrc, nByte);
141703   writeInt16(&pNode->zData[2], NCELL(pNode)-1);
141704   pNode->isDirty = 1;
141705 }
141706 
141707 /*
141708 ** Insert the contents of cell pCell into node pNode. If the insert
141709 ** is successful, return SQLITE_OK.
141710 **
141711 ** If there is not enough free space in pNode, return SQLITE_FULL.
141712 */
141713 static int
141714 nodeInsertCell(
141715   Rtree *pRtree, 
141716   RtreeNode *pNode, 
141717   RtreeCell *pCell 
141718 ){
141719   int nCell;                    /* Current number of cells in pNode */
141720   int nMaxCell;                 /* Maximum number of cells for pNode */
141721 
141722   nMaxCell = (pRtree->iNodeSize-4)/pRtree->nBytesPerCell;
141723   nCell = NCELL(pNode);
141724 
141725   assert( nCell<=nMaxCell );
141726   if( nCell<nMaxCell ){
141727     nodeOverwriteCell(pRtree, pNode, pCell, nCell);
141728     writeInt16(&pNode->zData[2], nCell+1);
141729     pNode->isDirty = 1;
141730   }
141731 
141732   return (nCell==nMaxCell);
141733 }
141734 
141735 /*
141736 ** If the node is dirty, write it out to the database.
141737 */
141738 static int
141739 nodeWrite(Rtree *pRtree, RtreeNode *pNode){
141740   int rc = SQLITE_OK;
141741   if( pNode->isDirty ){
141742     sqlite3_stmt *p = pRtree->pWriteNode;
141743     if( pNode->iNode ){
141744       sqlite3_bind_int64(p, 1, pNode->iNode);
141745     }else{
141746       sqlite3_bind_null(p, 1);
141747     }
141748     sqlite3_bind_blob(p, 2, pNode->zData, pRtree->iNodeSize, SQLITE_STATIC);
141749     sqlite3_step(p);
141750     pNode->isDirty = 0;
141751     rc = sqlite3_reset(p);
141752     if( pNode->iNode==0 && rc==SQLITE_OK ){
141753       pNode->iNode = sqlite3_last_insert_rowid(pRtree->db);
141754       nodeHashInsert(pRtree, pNode);
141755     }
141756   }
141757   return rc;
141758 }
141759 
141760 /*
141761 ** Release a reference to a node. If the node is dirty and the reference
141762 ** count drops to zero, the node data is written to the database.
141763 */
141764 static int
141765 nodeRelease(Rtree *pRtree, RtreeNode *pNode){
141766   int rc = SQLITE_OK;
141767   if( pNode ){
141768     assert( pNode->nRef>0 );
141769     pNode->nRef--;
141770     if( pNode->nRef==0 ){
141771       if( pNode->iNode==1 ){
141772         pRtree->iDepth = -1;
141773       }
141774       if( pNode->pParent ){
141775         rc = nodeRelease(pRtree, pNode->pParent);
141776       }
141777       if( rc==SQLITE_OK ){
141778         rc = nodeWrite(pRtree, pNode);
141779       }
141780       nodeHashDelete(pRtree, pNode);
141781       sqlite3_free(pNode);
141782     }
141783   }
141784   return rc;
141785 }
141786 
141787 /*
141788 ** Return the 64-bit integer value associated with cell iCell of
141789 ** node pNode. If pNode is a leaf node, this is a rowid. If it is
141790 ** an internal node, then the 64-bit integer is a child page number.
141791 */
141792 static i64 nodeGetRowid(
141793   Rtree *pRtree, 
141794   RtreeNode *pNode, 
141795   int iCell
141796 ){
141797   assert( iCell<NCELL(pNode) );
141798   return readInt64(&pNode->zData[4 + pRtree->nBytesPerCell*iCell]);
141799 }
141800 
141801 /*
141802 ** Return coordinate iCoord from cell iCell in node pNode.
141803 */
141804 static void nodeGetCoord(
141805   Rtree *pRtree, 
141806   RtreeNode *pNode, 
141807   int iCell,
141808   int iCoord,
141809   RtreeCoord *pCoord           /* Space to write result to */
141810 ){
141811   readCoord(&pNode->zData[12 + pRtree->nBytesPerCell*iCell + 4*iCoord], pCoord);
141812 }
141813 
141814 /*
141815 ** Deserialize cell iCell of node pNode. Populate the structure pointed
141816 ** to by pCell with the results.
141817 */
141818 static void nodeGetCell(
141819   Rtree *pRtree, 
141820   RtreeNode *pNode, 
141821   int iCell,
141822   RtreeCell *pCell
141823 ){
141824   int ii;
141825   pCell->iRowid = nodeGetRowid(pRtree, pNode, iCell);
141826   for(ii=0; ii<pRtree->nDim*2; ii++){
141827     nodeGetCoord(pRtree, pNode, iCell, ii, &pCell->aCoord[ii]);
141828   }
141829 }
141830 
141831 
141832 /* Forward declaration for the function that does the work of
141833 ** the virtual table module xCreate() and xConnect() methods.
141834 */
141835 static int rtreeInit(
141836   sqlite3 *, void *, int, const char *const*, sqlite3_vtab **, char **, int
141837 );
141838 
141839 /* 
141840 ** Rtree virtual table module xCreate method.
141841 */
141842 static int rtreeCreate(
141843   sqlite3 *db,
141844   void *pAux,
141845   int argc, const char *const*argv,
141846   sqlite3_vtab **ppVtab,
141847   char **pzErr
141848 ){
141849   return rtreeInit(db, pAux, argc, argv, ppVtab, pzErr, 1);
141850 }
141851 
141852 /* 
141853 ** Rtree virtual table module xConnect method.
141854 */
141855 static int rtreeConnect(
141856   sqlite3 *db,
141857   void *pAux,
141858   int argc, const char *const*argv,
141859   sqlite3_vtab **ppVtab,
141860   char **pzErr
141861 ){
141862   return rtreeInit(db, pAux, argc, argv, ppVtab, pzErr, 0);
141863 }
141864 
141865 /*
141866 ** Increment the r-tree reference count.
141867 */
141868 static void rtreeReference(Rtree *pRtree){
141869   pRtree->nBusy++;
141870 }
141871 
141872 /*
141873 ** Decrement the r-tree reference count. When the reference count reaches
141874 ** zero the structure is deleted.
141875 */
141876 static void rtreeRelease(Rtree *pRtree){
141877   pRtree->nBusy--;
141878   if( pRtree->nBusy==0 ){
141879     sqlite3_finalize(pRtree->pReadNode);
141880     sqlite3_finalize(pRtree->pWriteNode);
141881     sqlite3_finalize(pRtree->pDeleteNode);
141882     sqlite3_finalize(pRtree->pReadRowid);
141883     sqlite3_finalize(pRtree->pWriteRowid);
141884     sqlite3_finalize(pRtree->pDeleteRowid);
141885     sqlite3_finalize(pRtree->pReadParent);
141886     sqlite3_finalize(pRtree->pWriteParent);
141887     sqlite3_finalize(pRtree->pDeleteParent);
141888     sqlite3_free(pRtree);
141889   }
141890 }
141891 
141892 /* 
141893 ** Rtree virtual table module xDisconnect method.
141894 */
141895 static int rtreeDisconnect(sqlite3_vtab *pVtab){
141896   rtreeRelease((Rtree *)pVtab);
141897   return SQLITE_OK;
141898 }
141899 
141900 /* 
141901 ** Rtree virtual table module xDestroy method.
141902 */
141903 static int rtreeDestroy(sqlite3_vtab *pVtab){
141904   Rtree *pRtree = (Rtree *)pVtab;
141905   int rc;
141906   char *zCreate = sqlite3_mprintf(
141907     "DROP TABLE '%q'.'%q_node';"
141908     "DROP TABLE '%q'.'%q_rowid';"
141909     "DROP TABLE '%q'.'%q_parent';",
141910     pRtree->zDb, pRtree->zName, 
141911     pRtree->zDb, pRtree->zName,
141912     pRtree->zDb, pRtree->zName
141913   );
141914   if( !zCreate ){
141915     rc = SQLITE_NOMEM;
141916   }else{
141917     rc = sqlite3_exec(pRtree->db, zCreate, 0, 0, 0);
141918     sqlite3_free(zCreate);
141919   }
141920   if( rc==SQLITE_OK ){
141921     rtreeRelease(pRtree);
141922   }
141923 
141924   return rc;
141925 }
141926 
141927 /* 
141928 ** Rtree virtual table module xOpen method.
141929 */
141930 static int rtreeOpen(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor){
141931   int rc = SQLITE_NOMEM;
141932   RtreeCursor *pCsr;
141933 
141934   pCsr = (RtreeCursor *)sqlite3_malloc(sizeof(RtreeCursor));
141935   if( pCsr ){
141936     memset(pCsr, 0, sizeof(RtreeCursor));
141937     pCsr->base.pVtab = pVTab;
141938     rc = SQLITE_OK;
141939   }
141940   *ppCursor = (sqlite3_vtab_cursor *)pCsr;
141941 
141942   return rc;
141943 }
141944 
141945 
141946 /*
141947 ** Free the RtreeCursor.aConstraint[] array and its contents.
141948 */
141949 static void freeCursorConstraints(RtreeCursor *pCsr){
141950   if( pCsr->aConstraint ){
141951     int i;                        /* Used to iterate through constraint array */
141952     for(i=0; i<pCsr->nConstraint; i++){
141953       sqlite3_rtree_geometry *pGeom = pCsr->aConstraint[i].pGeom;
141954       if( pGeom ){
141955         if( pGeom->xDelUser ) pGeom->xDelUser(pGeom->pUser);
141956         sqlite3_free(pGeom);
141957       }
141958     }
141959     sqlite3_free(pCsr->aConstraint);
141960     pCsr->aConstraint = 0;
141961   }
141962 }
141963 
141964 /* 
141965 ** Rtree virtual table module xClose method.
141966 */
141967 static int rtreeClose(sqlite3_vtab_cursor *cur){
141968   Rtree *pRtree = (Rtree *)(cur->pVtab);
141969   int rc;
141970   RtreeCursor *pCsr = (RtreeCursor *)cur;
141971   freeCursorConstraints(pCsr);
141972   rc = nodeRelease(pRtree, pCsr->pNode);
141973   sqlite3_free(pCsr);
141974   return rc;
141975 }
141976 
141977 /*
141978 ** Rtree virtual table module xEof method.
141979 **
141980 ** Return non-zero if the cursor does not currently point to a valid 
141981 ** record (i.e if the scan has finished), or zero otherwise.
141982 */
141983 static int rtreeEof(sqlite3_vtab_cursor *cur){
141984   RtreeCursor *pCsr = (RtreeCursor *)cur;
141985   return (pCsr->pNode==0);
141986 }
141987 
141988 /*
141989 ** The r-tree constraint passed as the second argument to this function is
141990 ** guaranteed to be a MATCH constraint.
141991 */
141992 static int testRtreeGeom(
141993   Rtree *pRtree,                  /* R-Tree object */
141994   RtreeConstraint *pConstraint,   /* MATCH constraint to test */
141995   RtreeCell *pCell,               /* Cell to test */
141996   int *pbRes                      /* OUT: Test result */
141997 ){
141998   int i;
141999   RtreeDValue aCoord[RTREE_MAX_DIMENSIONS*2];
142000   int nCoord = pRtree->nDim*2;
142001 
142002   assert( pConstraint->op==RTREE_MATCH );
142003   assert( pConstraint->pGeom );
142004 
142005   for(i=0; i<nCoord; i++){
142006     aCoord[i] = DCOORD(pCell->aCoord[i]);
142007   }
142008   return pConstraint->xGeom(pConstraint->pGeom, nCoord, aCoord, pbRes);
142009 }
142010 
142011 /* 
142012 ** Cursor pCursor currently points to a cell in a non-leaf page.
142013 ** Set *pbEof to true if the sub-tree headed by the cell is filtered
142014 ** (excluded) by the constraints in the pCursor->aConstraint[] 
142015 ** array, or false otherwise.
142016 **
142017 ** Return SQLITE_OK if successful or an SQLite error code if an error
142018 ** occurs within a geometry callback.
142019 */
142020 static int testRtreeCell(Rtree *pRtree, RtreeCursor *pCursor, int *pbEof){
142021   RtreeCell cell;
142022   int ii;
142023   int bRes = 0;
142024   int rc = SQLITE_OK;
142025 
142026   nodeGetCell(pRtree, pCursor->pNode, pCursor->iCell, &cell);
142027   for(ii=0; bRes==0 && ii<pCursor->nConstraint; ii++){
142028     RtreeConstraint *p = &pCursor->aConstraint[ii];
142029     RtreeDValue cell_min = DCOORD(cell.aCoord[(p->iCoord>>1)*2]);
142030     RtreeDValue cell_max = DCOORD(cell.aCoord[(p->iCoord>>1)*2+1]);
142031 
142032     assert(p->op==RTREE_LE || p->op==RTREE_LT || p->op==RTREE_GE 
142033         || p->op==RTREE_GT || p->op==RTREE_EQ || p->op==RTREE_MATCH
142034     );
142035 
142036     switch( p->op ){
142037       case RTREE_LE: case RTREE_LT: 
142038         bRes = p->rValue<cell_min; 
142039         break;
142040 
142041       case RTREE_GE: case RTREE_GT: 
142042         bRes = p->rValue>cell_max; 
142043         break;
142044 
142045       case RTREE_EQ:
142046         bRes = (p->rValue>cell_max || p->rValue<cell_min);
142047         break;
142048 
142049       default: {
142050         assert( p->op==RTREE_MATCH );
142051         rc = testRtreeGeom(pRtree, p, &cell, &bRes);
142052         bRes = !bRes;
142053         break;
142054       }
142055     }
142056   }
142057 
142058   *pbEof = bRes;
142059   return rc;
142060 }
142061 
142062 /* 
142063 ** Test if the cell that cursor pCursor currently points to
142064 ** would be filtered (excluded) by the constraints in the 
142065 ** pCursor->aConstraint[] array. If so, set *pbEof to true before
142066 ** returning. If the cell is not filtered (excluded) by the constraints,
142067 ** set pbEof to zero.
142068 **
142069 ** Return SQLITE_OK if successful or an SQLite error code if an error
142070 ** occurs within a geometry callback.
142071 **
142072 ** This function assumes that the cell is part of a leaf node.
142073 */
142074 static int testRtreeEntry(Rtree *pRtree, RtreeCursor *pCursor, int *pbEof){
142075   RtreeCell cell;
142076   int ii;
142077   *pbEof = 0;
142078 
142079   nodeGetCell(pRtree, pCursor->pNode, pCursor->iCell, &cell);
142080   for(ii=0; ii<pCursor->nConstraint; ii++){
142081     RtreeConstraint *p = &pCursor->aConstraint[ii];
142082     RtreeDValue coord = DCOORD(cell.aCoord[p->iCoord]);
142083     int res;
142084     assert(p->op==RTREE_LE || p->op==RTREE_LT || p->op==RTREE_GE 
142085         || p->op==RTREE_GT || p->op==RTREE_EQ || p->op==RTREE_MATCH
142086     );
142087     switch( p->op ){
142088       case RTREE_LE: res = (coord<=p->rValue); break;
142089       case RTREE_LT: res = (coord<p->rValue);  break;
142090       case RTREE_GE: res = (coord>=p->rValue); break;
142091       case RTREE_GT: res = (coord>p->rValue);  break;
142092       case RTREE_EQ: res = (coord==p->rValue); break;
142093       default: {
142094         int rc;
142095         assert( p->op==RTREE_MATCH );
142096         rc = testRtreeGeom(pRtree, p, &cell, &res);
142097         if( rc!=SQLITE_OK ){
142098           return rc;
142099         }
142100         break;
142101       }
142102     }
142103 
142104     if( !res ){
142105       *pbEof = 1;
142106       return SQLITE_OK;
142107     }
142108   }
142109 
142110   return SQLITE_OK;
142111 }
142112 
142113 /*
142114 ** Cursor pCursor currently points at a node that heads a sub-tree of
142115 ** height iHeight (if iHeight==0, then the node is a leaf). Descend
142116 ** to point to the left-most cell of the sub-tree that matches the 
142117 ** configured constraints.
142118 */
142119 static int descendToCell(
142120   Rtree *pRtree, 
142121   RtreeCursor *pCursor, 
142122   int iHeight,
142123   int *pEof                 /* OUT: Set to true if cannot descend */
142124 ){
142125   int isEof;
142126   int rc;
142127   int ii;
142128   RtreeNode *pChild;
142129   sqlite3_int64 iRowid;
142130 
142131   RtreeNode *pSavedNode = pCursor->pNode;
142132   int iSavedCell = pCursor->iCell;
142133 
142134   assert( iHeight>=0 );
142135 
142136   if( iHeight==0 ){
142137     rc = testRtreeEntry(pRtree, pCursor, &isEof);
142138   }else{
142139     rc = testRtreeCell(pRtree, pCursor, &isEof);
142140   }
142141   if( rc!=SQLITE_OK || isEof || iHeight==0 ){
142142     goto descend_to_cell_out;
142143   }
142144 
142145   iRowid = nodeGetRowid(pRtree, pCursor->pNode, pCursor->iCell);
142146   rc = nodeAcquire(pRtree, iRowid, pCursor->pNode, &pChild);
142147   if( rc!=SQLITE_OK ){
142148     goto descend_to_cell_out;
142149   }
142150 
142151   nodeRelease(pRtree, pCursor->pNode);
142152   pCursor->pNode = pChild;
142153   isEof = 1;
142154   for(ii=0; isEof && ii<NCELL(pChild); ii++){
142155     pCursor->iCell = ii;
142156     rc = descendToCell(pRtree, pCursor, iHeight-1, &isEof);
142157     if( rc!=SQLITE_OK ){
142158       goto descend_to_cell_out;
142159     }
142160   }
142161 
142162   if( isEof ){
142163     assert( pCursor->pNode==pChild );
142164     nodeReference(pSavedNode);
142165     nodeRelease(pRtree, pChild);
142166     pCursor->pNode = pSavedNode;
142167     pCursor->iCell = iSavedCell;
142168   }
142169 
142170 descend_to_cell_out:
142171   *pEof = isEof;
142172   return rc;
142173 }
142174 
142175 /*
142176 ** One of the cells in node pNode is guaranteed to have a 64-bit 
142177 ** integer value equal to iRowid. Return the index of this cell.
142178 */
142179 static int nodeRowidIndex(
142180   Rtree *pRtree, 
142181   RtreeNode *pNode, 
142182   i64 iRowid,
142183   int *piIndex
142184 ){
142185   int ii;
142186   int nCell = NCELL(pNode);
142187   for(ii=0; ii<nCell; ii++){
142188     if( nodeGetRowid(pRtree, pNode, ii)==iRowid ){
142189       *piIndex = ii;
142190       return SQLITE_OK;
142191     }
142192   }
142193   return SQLITE_CORRUPT_VTAB;
142194 }
142195 
142196 /*
142197 ** Return the index of the cell containing a pointer to node pNode
142198 ** in its parent. If pNode is the root node, return -1.
142199 */
142200 static int nodeParentIndex(Rtree *pRtree, RtreeNode *pNode, int *piIndex){
142201   RtreeNode *pParent = pNode->pParent;
142202   if( pParent ){
142203     return nodeRowidIndex(pRtree, pParent, pNode->iNode, piIndex);
142204   }
142205   *piIndex = -1;
142206   return SQLITE_OK;
142207 }
142208 
142209 /* 
142210 ** Rtree virtual table module xNext method.
142211 */
142212 static int rtreeNext(sqlite3_vtab_cursor *pVtabCursor){
142213   Rtree *pRtree = (Rtree *)(pVtabCursor->pVtab);
142214   RtreeCursor *pCsr = (RtreeCursor *)pVtabCursor;
142215   int rc = SQLITE_OK;
142216 
142217   /* RtreeCursor.pNode must not be NULL. If is is NULL, then this cursor is
142218   ** already at EOF. It is against the rules to call the xNext() method of
142219   ** a cursor that has already reached EOF.
142220   */
142221   assert( pCsr->pNode );
142222 
142223   if( pCsr->iStrategy==1 ){
142224     /* This "scan" is a direct lookup by rowid. There is no next entry. */
142225     nodeRelease(pRtree, pCsr->pNode);
142226     pCsr->pNode = 0;
142227   }else{
142228     /* Move to the next entry that matches the configured constraints. */
142229     int iHeight = 0;
142230     while( pCsr->pNode ){
142231       RtreeNode *pNode = pCsr->pNode;
142232       int nCell = NCELL(pNode);
142233       for(pCsr->iCell++; pCsr->iCell<nCell; pCsr->iCell++){
142234         int isEof;
142235         rc = descendToCell(pRtree, pCsr, iHeight, &isEof);
142236         if( rc!=SQLITE_OK || !isEof ){
142237           return rc;
142238         }
142239       }
142240       pCsr->pNode = pNode->pParent;
142241       rc = nodeParentIndex(pRtree, pNode, &pCsr->iCell);
142242       if( rc!=SQLITE_OK ){
142243         return rc;
142244       }
142245       nodeReference(pCsr->pNode);
142246       nodeRelease(pRtree, pNode);
142247       iHeight++;
142248     }
142249   }
142250 
142251   return rc;
142252 }
142253 
142254 /* 
142255 ** Rtree virtual table module xRowid method.
142256 */
142257 static int rtreeRowid(sqlite3_vtab_cursor *pVtabCursor, sqlite_int64 *pRowid){
142258   Rtree *pRtree = (Rtree *)pVtabCursor->pVtab;
142259   RtreeCursor *pCsr = (RtreeCursor *)pVtabCursor;
142260 
142261   assert(pCsr->pNode);
142262   *pRowid = nodeGetRowid(pRtree, pCsr->pNode, pCsr->iCell);
142263 
142264   return SQLITE_OK;
142265 }
142266 
142267 /* 
142268 ** Rtree virtual table module xColumn method.
142269 */
142270 static int rtreeColumn(sqlite3_vtab_cursor *cur, sqlite3_context *ctx, int i){
142271   Rtree *pRtree = (Rtree *)cur->pVtab;
142272   RtreeCursor *pCsr = (RtreeCursor *)cur;
142273 
142274   if( i==0 ){
142275     i64 iRowid = nodeGetRowid(pRtree, pCsr->pNode, pCsr->iCell);
142276     sqlite3_result_int64(ctx, iRowid);
142277   }else{
142278     RtreeCoord c;
142279     nodeGetCoord(pRtree, pCsr->pNode, pCsr->iCell, i-1, &c);
142280 #ifndef SQLITE_RTREE_INT_ONLY
142281     if( pRtree->eCoordType==RTREE_COORD_REAL32 ){
142282       sqlite3_result_double(ctx, c.f);
142283     }else
142284 #endif
142285     {
142286       assert( pRtree->eCoordType==RTREE_COORD_INT32 );
142287       sqlite3_result_int(ctx, c.i);
142288     }
142289   }
142290 
142291   return SQLITE_OK;
142292 }
142293 
142294 /* 
142295 ** Use nodeAcquire() to obtain the leaf node containing the record with 
142296 ** rowid iRowid. If successful, set *ppLeaf to point to the node and
142297 ** return SQLITE_OK. If there is no such record in the table, set
142298 ** *ppLeaf to 0 and return SQLITE_OK. If an error occurs, set *ppLeaf
142299 ** to zero and return an SQLite error code.
142300 */
142301 static int findLeafNode(Rtree *pRtree, i64 iRowid, RtreeNode **ppLeaf){
142302   int rc;
142303   *ppLeaf = 0;
142304   sqlite3_bind_int64(pRtree->pReadRowid, 1, iRowid);
142305   if( sqlite3_step(pRtree->pReadRowid)==SQLITE_ROW ){
142306     i64 iNode = sqlite3_column_int64(pRtree->pReadRowid, 0);
142307     rc = nodeAcquire(pRtree, iNode, 0, ppLeaf);
142308     sqlite3_reset(pRtree->pReadRowid);
142309   }else{
142310     rc = sqlite3_reset(pRtree->pReadRowid);
142311   }
142312   return rc;
142313 }
142314 
142315 /*
142316 ** This function is called to configure the RtreeConstraint object passed
142317 ** as the second argument for a MATCH constraint. The value passed as the
142318 ** first argument to this function is the right-hand operand to the MATCH
142319 ** operator.
142320 */
142321 static int deserializeGeometry(sqlite3_value *pValue, RtreeConstraint *pCons){
142322   RtreeMatchArg *p;
142323   sqlite3_rtree_geometry *pGeom;
142324   int nBlob;
142325 
142326   /* Check that value is actually a blob. */
142327   if( sqlite3_value_type(pValue)!=SQLITE_BLOB ) return SQLITE_ERROR;
142328 
142329   /* Check that the blob is roughly the right size. */
142330   nBlob = sqlite3_value_bytes(pValue);
142331   if( nBlob<(int)sizeof(RtreeMatchArg) 
142332    || ((nBlob-sizeof(RtreeMatchArg))%sizeof(RtreeDValue))!=0
142333   ){
142334     return SQLITE_ERROR;
142335   }
142336 
142337   pGeom = (sqlite3_rtree_geometry *)sqlite3_malloc(
142338       sizeof(sqlite3_rtree_geometry) + nBlob
142339   );
142340   if( !pGeom ) return SQLITE_NOMEM;
142341   memset(pGeom, 0, sizeof(sqlite3_rtree_geometry));
142342   p = (RtreeMatchArg *)&pGeom[1];
142343 
142344   memcpy(p, sqlite3_value_blob(pValue), nBlob);
142345   if( p->magic!=RTREE_GEOMETRY_MAGIC 
142346    || nBlob!=(int)(sizeof(RtreeMatchArg) + (p->nParam-1)*sizeof(RtreeDValue))
142347   ){
142348     sqlite3_free(pGeom);
142349     return SQLITE_ERROR;
142350   }
142351 
142352   pGeom->pContext = p->pContext;
142353   pGeom->nParam = p->nParam;
142354   pGeom->aParam = p->aParam;
142355 
142356   pCons->xGeom = p->xGeom;
142357   pCons->pGeom = pGeom;
142358   return SQLITE_OK;
142359 }
142360 
142361 /* 
142362 ** Rtree virtual table module xFilter method.
142363 */
142364 static int rtreeFilter(
142365   sqlite3_vtab_cursor *pVtabCursor, 
142366   int idxNum, const char *idxStr,
142367   int argc, sqlite3_value **argv
142368 ){
142369   Rtree *pRtree = (Rtree *)pVtabCursor->pVtab;
142370   RtreeCursor *pCsr = (RtreeCursor *)pVtabCursor;
142371 
142372   RtreeNode *pRoot = 0;
142373   int ii;
142374   int rc = SQLITE_OK;
142375 
142376   rtreeReference(pRtree);
142377 
142378   freeCursorConstraints(pCsr);
142379   pCsr->iStrategy = idxNum;
142380 
142381   if( idxNum==1 ){
142382     /* Special case - lookup by rowid. */
142383     RtreeNode *pLeaf;        /* Leaf on which the required cell resides */
142384     i64 iRowid = sqlite3_value_int64(argv[0]);
142385     rc = findLeafNode(pRtree, iRowid, &pLeaf);
142386     pCsr->pNode = pLeaf; 
142387     if( pLeaf ){
142388       assert( rc==SQLITE_OK );
142389       rc = nodeRowidIndex(pRtree, pLeaf, iRowid, &pCsr->iCell);
142390     }
142391   }else{
142392     /* Normal case - r-tree scan. Set up the RtreeCursor.aConstraint array 
142393     ** with the configured constraints. 
142394     */
142395     if( argc>0 ){
142396       pCsr->aConstraint = sqlite3_malloc(sizeof(RtreeConstraint)*argc);
142397       pCsr->nConstraint = argc;
142398       if( !pCsr->aConstraint ){
142399         rc = SQLITE_NOMEM;
142400       }else{
142401         memset(pCsr->aConstraint, 0, sizeof(RtreeConstraint)*argc);
142402         assert( (idxStr==0 && argc==0)
142403                 || (idxStr && (int)strlen(idxStr)==argc*2) );
142404         for(ii=0; ii<argc; ii++){
142405           RtreeConstraint *p = &pCsr->aConstraint[ii];
142406           p->op = idxStr[ii*2];
142407           p->iCoord = idxStr[ii*2+1]-'a';
142408           if( p->op==RTREE_MATCH ){
142409             /* A MATCH operator. The right-hand-side must be a blob that
142410             ** can be cast into an RtreeMatchArg object. One created using
142411             ** an sqlite3_rtree_geometry_callback() SQL user function.
142412             */
142413             rc = deserializeGeometry(argv[ii], p);
142414             if( rc!=SQLITE_OK ){
142415               break;
142416             }
142417           }else{
142418 #ifdef SQLITE_RTREE_INT_ONLY
142419             p->rValue = sqlite3_value_int64(argv[ii]);
142420 #else
142421             p->rValue = sqlite3_value_double(argv[ii]);
142422 #endif
142423           }
142424         }
142425       }
142426     }
142427   
142428     if( rc==SQLITE_OK ){
142429       pCsr->pNode = 0;
142430       rc = nodeAcquire(pRtree, 1, 0, &pRoot);
142431     }
142432     if( rc==SQLITE_OK ){
142433       int isEof = 1;
142434       int nCell = NCELL(pRoot);
142435       pCsr->pNode = pRoot;
142436       for(pCsr->iCell=0; rc==SQLITE_OK && pCsr->iCell<nCell; pCsr->iCell++){
142437         assert( pCsr->pNode==pRoot );
142438         rc = descendToCell(pRtree, pCsr, pRtree->iDepth, &isEof);
142439         if( !isEof ){
142440           break;
142441         }
142442       }
142443       if( rc==SQLITE_OK && isEof ){
142444         assert( pCsr->pNode==pRoot );
142445         nodeRelease(pRtree, pRoot);
142446         pCsr->pNode = 0;
142447       }
142448       assert( rc!=SQLITE_OK || !pCsr->pNode || pCsr->iCell<NCELL(pCsr->pNode) );
142449     }
142450   }
142451 
142452   rtreeRelease(pRtree);
142453   return rc;
142454 }
142455 
142456 /*
142457 ** Set the pIdxInfo->estimatedRows variable to nRow. Unless this
142458 ** extension is currently being used by a version of SQLite too old to
142459 ** support estimatedRows. In that case this function is a no-op.
142460 */
142461 static void setEstimatedRows(sqlite3_index_info *pIdxInfo, i64 nRow){
142462 #if SQLITE_VERSION_NUMBER>=3008002
142463   if( sqlite3_libversion_number()>=3008002 ){
142464     pIdxInfo->estimatedRows = nRow;
142465   }
142466 #endif
142467 }
142468 
142469 /*
142470 ** Rtree virtual table module xBestIndex method. There are three
142471 ** table scan strategies to choose from (in order from most to 
142472 ** least desirable):
142473 **
142474 **   idxNum     idxStr        Strategy
142475 **   ------------------------------------------------
142476 **     1        Unused        Direct lookup by rowid.
142477 **     2        See below     R-tree query or full-table scan.
142478 **   ------------------------------------------------
142479 **
142480 ** If strategy 1 is used, then idxStr is not meaningful. If strategy
142481 ** 2 is used, idxStr is formatted to contain 2 bytes for each 
142482 ** constraint used. The first two bytes of idxStr correspond to 
142483 ** the constraint in sqlite3_index_info.aConstraintUsage[] with
142484 ** (argvIndex==1) etc.
142485 **
142486 ** The first of each pair of bytes in idxStr identifies the constraint
142487 ** operator as follows:
142488 **
142489 **   Operator    Byte Value
142490 **   ----------------------
142491 **      =        0x41 ('A')
142492 **     <=        0x42 ('B')
142493 **      <        0x43 ('C')
142494 **     >=        0x44 ('D')
142495 **      >        0x45 ('E')
142496 **   MATCH       0x46 ('F')
142497 **   ----------------------
142498 **
142499 ** The second of each pair of bytes identifies the coordinate column
142500 ** to which the constraint applies. The leftmost coordinate column
142501 ** is 'a', the second from the left 'b' etc.
142502 */
142503 static int rtreeBestIndex(sqlite3_vtab *tab, sqlite3_index_info *pIdxInfo){
142504   Rtree *pRtree = (Rtree*)tab;
142505   int rc = SQLITE_OK;
142506   int ii;
142507   i64 nRow;                       /* Estimated rows returned by this scan */
142508 
142509   int iIdx = 0;
142510   char zIdxStr[RTREE_MAX_DIMENSIONS*8+1];
142511   memset(zIdxStr, 0, sizeof(zIdxStr));
142512 
142513   assert( pIdxInfo->idxStr==0 );
142514   for(ii=0; ii<pIdxInfo->nConstraint && iIdx<(int)(sizeof(zIdxStr)-1); ii++){
142515     struct sqlite3_index_constraint *p = &pIdxInfo->aConstraint[ii];
142516 
142517     if( p->usable && p->iColumn==0 && p->op==SQLITE_INDEX_CONSTRAINT_EQ ){
142518       /* We have an equality constraint on the rowid. Use strategy 1. */
142519       int jj;
142520       for(jj=0; jj<ii; jj++){
142521         pIdxInfo->aConstraintUsage[jj].argvIndex = 0;
142522         pIdxInfo->aConstraintUsage[jj].omit = 0;
142523       }
142524       pIdxInfo->idxNum = 1;
142525       pIdxInfo->aConstraintUsage[ii].argvIndex = 1;
142526       pIdxInfo->aConstraintUsage[jj].omit = 1;
142527 
142528       /* This strategy involves a two rowid lookups on an B-Tree structures
142529       ** and then a linear search of an R-Tree node. This should be 
142530       ** considered almost as quick as a direct rowid lookup (for which 
142531       ** sqlite uses an internal cost of 0.0). It is expected to return
142532       ** a single row.
142533       */ 
142534       pIdxInfo->estimatedCost = 30.0;
142535       setEstimatedRows(pIdxInfo, 1);
142536       return SQLITE_OK;
142537     }
142538 
142539     if( p->usable && (p->iColumn>0 || p->op==SQLITE_INDEX_CONSTRAINT_MATCH) ){
142540       u8 op;
142541       switch( p->op ){
142542         case SQLITE_INDEX_CONSTRAINT_EQ: op = RTREE_EQ; break;
142543         case SQLITE_INDEX_CONSTRAINT_GT: op = RTREE_GT; break;
142544         case SQLITE_INDEX_CONSTRAINT_LE: op = RTREE_LE; break;
142545         case SQLITE_INDEX_CONSTRAINT_LT: op = RTREE_LT; break;
142546         case SQLITE_INDEX_CONSTRAINT_GE: op = RTREE_GE; break;
142547         default:
142548           assert( p->op==SQLITE_INDEX_CONSTRAINT_MATCH );
142549           op = RTREE_MATCH; 
142550           break;
142551       }
142552       zIdxStr[iIdx++] = op;
142553       zIdxStr[iIdx++] = p->iColumn - 1 + 'a';
142554       pIdxInfo->aConstraintUsage[ii].argvIndex = (iIdx/2);
142555       pIdxInfo->aConstraintUsage[ii].omit = 1;
142556     }
142557   }
142558 
142559   pIdxInfo->idxNum = 2;
142560   pIdxInfo->needToFreeIdxStr = 1;
142561   if( iIdx>0 && 0==(pIdxInfo->idxStr = sqlite3_mprintf("%s", zIdxStr)) ){
142562     return SQLITE_NOMEM;
142563   }
142564 
142565   nRow = pRtree->nRowEst / (iIdx + 1);
142566   pIdxInfo->estimatedCost = (double)6.0 * (double)nRow;
142567   setEstimatedRows(pIdxInfo, nRow);
142568 
142569   return rc;
142570 }
142571 
142572 /*
142573 ** Return the N-dimensional volumn of the cell stored in *p.
142574 */
142575 static RtreeDValue cellArea(Rtree *pRtree, RtreeCell *p){
142576   RtreeDValue area = (RtreeDValue)1;
142577   int ii;
142578   for(ii=0; ii<(pRtree->nDim*2); ii+=2){
142579     area = (area * (DCOORD(p->aCoord[ii+1]) - DCOORD(p->aCoord[ii])));
142580   }
142581   return area;
142582 }
142583 
142584 /*
142585 ** Return the margin length of cell p. The margin length is the sum
142586 ** of the objects size in each dimension.
142587 */
142588 static RtreeDValue cellMargin(Rtree *pRtree, RtreeCell *p){
142589   RtreeDValue margin = (RtreeDValue)0;
142590   int ii;
142591   for(ii=0; ii<(pRtree->nDim*2); ii+=2){
142592     margin += (DCOORD(p->aCoord[ii+1]) - DCOORD(p->aCoord[ii]));
142593   }
142594   return margin;
142595 }
142596 
142597 /*
142598 ** Store the union of cells p1 and p2 in p1.
142599 */
142600 static void cellUnion(Rtree *pRtree, RtreeCell *p1, RtreeCell *p2){
142601   int ii;
142602   if( pRtree->eCoordType==RTREE_COORD_REAL32 ){
142603     for(ii=0; ii<(pRtree->nDim*2); ii+=2){
142604       p1->aCoord[ii].f = MIN(p1->aCoord[ii].f, p2->aCoord[ii].f);
142605       p1->aCoord[ii+1].f = MAX(p1->aCoord[ii+1].f, p2->aCoord[ii+1].f);
142606     }
142607   }else{
142608     for(ii=0; ii<(pRtree->nDim*2); ii+=2){
142609       p1->aCoord[ii].i = MIN(p1->aCoord[ii].i, p2->aCoord[ii].i);
142610       p1->aCoord[ii+1].i = MAX(p1->aCoord[ii+1].i, p2->aCoord[ii+1].i);
142611     }
142612   }
142613 }
142614 
142615 /*
142616 ** Return true if the area covered by p2 is a subset of the area covered
142617 ** by p1. False otherwise.
142618 */
142619 static int cellContains(Rtree *pRtree, RtreeCell *p1, RtreeCell *p2){
142620   int ii;
142621   int isInt = (pRtree->eCoordType==RTREE_COORD_INT32);
142622   for(ii=0; ii<(pRtree->nDim*2); ii+=2){
142623     RtreeCoord *a1 = &p1->aCoord[ii];
142624     RtreeCoord *a2 = &p2->aCoord[ii];
142625     if( (!isInt && (a2[0].f<a1[0].f || a2[1].f>a1[1].f)) 
142626      || ( isInt && (a2[0].i<a1[0].i || a2[1].i>a1[1].i)) 
142627     ){
142628       return 0;
142629     }
142630   }
142631   return 1;
142632 }
142633 
142634 /*
142635 ** Return the amount cell p would grow by if it were unioned with pCell.
142636 */
142637 static RtreeDValue cellGrowth(Rtree *pRtree, RtreeCell *p, RtreeCell *pCell){
142638   RtreeDValue area;
142639   RtreeCell cell;
142640   memcpy(&cell, p, sizeof(RtreeCell));
142641   area = cellArea(pRtree, &cell);
142642   cellUnion(pRtree, &cell, pCell);
142643   return (cellArea(pRtree, &cell)-area);
142644 }
142645 
142646 #if VARIANT_RSTARTREE_CHOOSESUBTREE || VARIANT_RSTARTREE_SPLIT
142647 static RtreeDValue cellOverlap(
142648   Rtree *pRtree, 
142649   RtreeCell *p, 
142650   RtreeCell *aCell, 
142651   int nCell, 
142652   int iExclude
142653 ){
142654   int ii;
142655   RtreeDValue overlap = 0.0;
142656   for(ii=0; ii<nCell; ii++){
142657 #if VARIANT_RSTARTREE_CHOOSESUBTREE
142658     if( ii!=iExclude )
142659 #else
142660     assert( iExclude==-1 );
142661     UNUSED_PARAMETER(iExclude);
142662 #endif
142663     {
142664       int jj;
142665       RtreeDValue o = (RtreeDValue)1;
142666       for(jj=0; jj<(pRtree->nDim*2); jj+=2){
142667         RtreeDValue x1, x2;
142668 
142669         x1 = MAX(DCOORD(p->aCoord[jj]), DCOORD(aCell[ii].aCoord[jj]));
142670         x2 = MIN(DCOORD(p->aCoord[jj+1]), DCOORD(aCell[ii].aCoord[jj+1]));
142671 
142672         if( x2<x1 ){
142673           o = 0.0;
142674           break;
142675         }else{
142676           o = o * (x2-x1);
142677         }
142678       }
142679       overlap += o;
142680     }
142681   }
142682   return overlap;
142683 }
142684 #endif
142685 
142686 #if VARIANT_RSTARTREE_CHOOSESUBTREE
142687 static RtreeDValue cellOverlapEnlargement(
142688   Rtree *pRtree, 
142689   RtreeCell *p, 
142690   RtreeCell *pInsert, 
142691   RtreeCell *aCell, 
142692   int nCell, 
142693   int iExclude
142694 ){
142695   RtreeDValue before, after;
142696   before = cellOverlap(pRtree, p, aCell, nCell, iExclude);
142697   cellUnion(pRtree, p, pInsert);
142698   after = cellOverlap(pRtree, p, aCell, nCell, iExclude);
142699   return (after-before);
142700 }
142701 #endif
142702 
142703 
142704 /*
142705 ** This function implements the ChooseLeaf algorithm from Gutman[84].
142706 ** ChooseSubTree in r*tree terminology.
142707 */
142708 static int ChooseLeaf(
142709   Rtree *pRtree,               /* Rtree table */
142710   RtreeCell *pCell,            /* Cell to insert into rtree */
142711   int iHeight,                 /* Height of sub-tree rooted at pCell */
142712   RtreeNode **ppLeaf           /* OUT: Selected leaf page */
142713 ){
142714   int rc;
142715   int ii;
142716   RtreeNode *pNode;
142717   rc = nodeAcquire(pRtree, 1, 0, &pNode);
142718 
142719   for(ii=0; rc==SQLITE_OK && ii<(pRtree->iDepth-iHeight); ii++){
142720     int iCell;
142721     sqlite3_int64 iBest = 0;
142722 
142723     RtreeDValue fMinGrowth = 0.0;
142724     RtreeDValue fMinArea = 0.0;
142725 #if VARIANT_RSTARTREE_CHOOSESUBTREE
142726     RtreeDValue fMinOverlap = 0.0;
142727     RtreeDValue overlap;
142728 #endif
142729 
142730     int nCell = NCELL(pNode);
142731     RtreeCell cell;
142732     RtreeNode *pChild;
142733 
142734     RtreeCell *aCell = 0;
142735 
142736 #if VARIANT_RSTARTREE_CHOOSESUBTREE
142737     if( ii==(pRtree->iDepth-1) ){
142738       int jj;
142739       aCell = sqlite3_malloc(sizeof(RtreeCell)*nCell);
142740       if( !aCell ){
142741         rc = SQLITE_NOMEM;
142742         nodeRelease(pRtree, pNode);
142743         pNode = 0;
142744         continue;
142745       }
142746       for(jj=0; jj<nCell; jj++){
142747         nodeGetCell(pRtree, pNode, jj, &aCell[jj]);
142748       }
142749     }
142750 #endif
142751 
142752     /* Select the child node which will be enlarged the least if pCell
142753     ** is inserted into it. Resolve ties by choosing the entry with
142754     ** the smallest area.
142755     */
142756     for(iCell=0; iCell<nCell; iCell++){
142757       int bBest = 0;
142758       RtreeDValue growth;
142759       RtreeDValue area;
142760       nodeGetCell(pRtree, pNode, iCell, &cell);
142761       growth = cellGrowth(pRtree, &cell, pCell);
142762       area = cellArea(pRtree, &cell);
142763 
142764 #if VARIANT_RSTARTREE_CHOOSESUBTREE
142765       if( ii==(pRtree->iDepth-1) ){
142766         overlap = cellOverlapEnlargement(pRtree,&cell,pCell,aCell,nCell,iCell);
142767       }else{
142768         overlap = 0.0;
142769       }
142770       if( (iCell==0) 
142771        || (overlap<fMinOverlap) 
142772        || (overlap==fMinOverlap && growth<fMinGrowth)
142773        || (overlap==fMinOverlap && growth==fMinGrowth && area<fMinArea)
142774       ){
142775         bBest = 1;
142776         fMinOverlap = overlap;
142777       }
142778 #else
142779       if( iCell==0||growth<fMinGrowth||(growth==fMinGrowth && area<fMinArea) ){
142780         bBest = 1;
142781       }
142782 #endif
142783       if( bBest ){
142784         fMinGrowth = growth;
142785         fMinArea = area;
142786         iBest = cell.iRowid;
142787       }
142788     }
142789 
142790     sqlite3_free(aCell);
142791     rc = nodeAcquire(pRtree, iBest, pNode, &pChild);
142792     nodeRelease(pRtree, pNode);
142793     pNode = pChild;
142794   }
142795 
142796   *ppLeaf = pNode;
142797   return rc;
142798 }
142799 
142800 /*
142801 ** A cell with the same content as pCell has just been inserted into
142802 ** the node pNode. This function updates the bounding box cells in
142803 ** all ancestor elements.
142804 */
142805 static int AdjustTree(
142806   Rtree *pRtree,                    /* Rtree table */
142807   RtreeNode *pNode,                 /* Adjust ancestry of this node. */
142808   RtreeCell *pCell                  /* This cell was just inserted */
142809 ){
142810   RtreeNode *p = pNode;
142811   while( p->pParent ){
142812     RtreeNode *pParent = p->pParent;
142813     RtreeCell cell;
142814     int iCell;
142815 
142816     if( nodeParentIndex(pRtree, p, &iCell) ){
142817       return SQLITE_CORRUPT_VTAB;
142818     }
142819 
142820     nodeGetCell(pRtree, pParent, iCell, &cell);
142821     if( !cellContains(pRtree, &cell, pCell) ){
142822       cellUnion(pRtree, &cell, pCell);
142823       nodeOverwriteCell(pRtree, pParent, &cell, iCell);
142824     }
142825  
142826     p = pParent;
142827   }
142828   return SQLITE_OK;
142829 }
142830 
142831 /*
142832 ** Write mapping (iRowid->iNode) to the <rtree>_rowid table.
142833 */
142834 static int rowidWrite(Rtree *pRtree, sqlite3_int64 iRowid, sqlite3_int64 iNode){
142835   sqlite3_bind_int64(pRtree->pWriteRowid, 1, iRowid);
142836   sqlite3_bind_int64(pRtree->pWriteRowid, 2, iNode);
142837   sqlite3_step(pRtree->pWriteRowid);
142838   return sqlite3_reset(pRtree->pWriteRowid);
142839 }
142840 
142841 /*
142842 ** Write mapping (iNode->iPar) to the <rtree>_parent table.
142843 */
142844 static int parentWrite(Rtree *pRtree, sqlite3_int64 iNode, sqlite3_int64 iPar){
142845   sqlite3_bind_int64(pRtree->pWriteParent, 1, iNode);
142846   sqlite3_bind_int64(pRtree->pWriteParent, 2, iPar);
142847   sqlite3_step(pRtree->pWriteParent);
142848   return sqlite3_reset(pRtree->pWriteParent);
142849 }
142850 
142851 static int rtreeInsertCell(Rtree *, RtreeNode *, RtreeCell *, int);
142852 
142853 #if VARIANT_GUTTMAN_LINEAR_SPLIT
142854 /*
142855 ** Implementation of the linear variant of the PickNext() function from
142856 ** Guttman[84].
142857 */
142858 static RtreeCell *LinearPickNext(
142859   Rtree *pRtree,
142860   RtreeCell *aCell, 
142861   int nCell, 
142862   RtreeCell *pLeftBox, 
142863   RtreeCell *pRightBox,
142864   int *aiUsed
142865 ){
142866   int ii;
142867   for(ii=0; aiUsed[ii]; ii++);
142868   aiUsed[ii] = 1;
142869   return &aCell[ii];
142870 }
142871 
142872 /*
142873 ** Implementation of the linear variant of the PickSeeds() function from
142874 ** Guttman[84].
142875 */
142876 static void LinearPickSeeds(
142877   Rtree *pRtree,
142878   RtreeCell *aCell, 
142879   int nCell, 
142880   int *piLeftSeed, 
142881   int *piRightSeed
142882 ){
142883   int i;
142884   int iLeftSeed = 0;
142885   int iRightSeed = 1;
142886   RtreeDValue maxNormalInnerWidth = (RtreeDValue)0;
142887 
142888   /* Pick two "seed" cells from the array of cells. The algorithm used
142889   ** here is the LinearPickSeeds algorithm from Gutman[1984]. The 
142890   ** indices of the two seed cells in the array are stored in local
142891   ** variables iLeftSeek and iRightSeed.
142892   */
142893   for(i=0; i<pRtree->nDim; i++){
142894     RtreeDValue x1 = DCOORD(aCell[0].aCoord[i*2]);
142895     RtreeDValue x2 = DCOORD(aCell[0].aCoord[i*2+1]);
142896     RtreeDValue x3 = x1;
142897     RtreeDValue x4 = x2;
142898     int jj;
142899 
142900     int iCellLeft = 0;
142901     int iCellRight = 0;
142902 
142903     for(jj=1; jj<nCell; jj++){
142904       RtreeDValue left = DCOORD(aCell[jj].aCoord[i*2]);
142905       RtreeDValue right = DCOORD(aCell[jj].aCoord[i*2+1]);
142906 
142907       if( left<x1 ) x1 = left;
142908       if( right>x4 ) x4 = right;
142909       if( left>x3 ){
142910         x3 = left;
142911         iCellRight = jj;
142912       }
142913       if( right<x2 ){
142914         x2 = right;
142915         iCellLeft = jj;
142916       }
142917     }
142918 
142919     if( x4!=x1 ){
142920       RtreeDValue normalwidth = (x3 - x2) / (x4 - x1);
142921       if( normalwidth>maxNormalInnerWidth ){
142922         iLeftSeed = iCellLeft;
142923         iRightSeed = iCellRight;
142924       }
142925     }
142926   }
142927 
142928   *piLeftSeed = iLeftSeed;
142929   *piRightSeed = iRightSeed;
142930 }
142931 #endif /* VARIANT_GUTTMAN_LINEAR_SPLIT */
142932 
142933 #if VARIANT_GUTTMAN_QUADRATIC_SPLIT
142934 /*
142935 ** Implementation of the quadratic variant of the PickNext() function from
142936 ** Guttman[84].
142937 */
142938 static RtreeCell *QuadraticPickNext(
142939   Rtree *pRtree,
142940   RtreeCell *aCell, 
142941   int nCell, 
142942   RtreeCell *pLeftBox, 
142943   RtreeCell *pRightBox,
142944   int *aiUsed
142945 ){
142946   #define FABS(a) ((a)<0.0?-1.0*(a):(a))
142947 
142948   int iSelect = -1;
142949   RtreeDValue fDiff;
142950   int ii;
142951   for(ii=0; ii<nCell; ii++){
142952     if( aiUsed[ii]==0 ){
142953       RtreeDValue left = cellGrowth(pRtree, pLeftBox, &aCell[ii]);
142954       RtreeDValue right = cellGrowth(pRtree, pLeftBox, &aCell[ii]);
142955       RtreeDValue diff = FABS(right-left);
142956       if( iSelect<0 || diff>fDiff ){
142957         fDiff = diff;
142958         iSelect = ii;
142959       }
142960     }
142961   }
142962   aiUsed[iSelect] = 1;
142963   return &aCell[iSelect];
142964 }
142965 
142966 /*
142967 ** Implementation of the quadratic variant of the PickSeeds() function from
142968 ** Guttman[84].
142969 */
142970 static void QuadraticPickSeeds(
142971   Rtree *pRtree,
142972   RtreeCell *aCell, 
142973   int nCell, 
142974   int *piLeftSeed, 
142975   int *piRightSeed
142976 ){
142977   int ii;
142978   int jj;
142979 
142980   int iLeftSeed = 0;
142981   int iRightSeed = 1;
142982   RtreeDValue fWaste = 0.0;
142983 
142984   for(ii=0; ii<nCell; ii++){
142985     for(jj=ii+1; jj<nCell; jj++){
142986       RtreeDValue right = cellArea(pRtree, &aCell[jj]);
142987       RtreeDValue growth = cellGrowth(pRtree, &aCell[ii], &aCell[jj]);
142988       RtreeDValue waste = growth - right;
142989 
142990       if( waste>fWaste ){
142991         iLeftSeed = ii;
142992         iRightSeed = jj;
142993         fWaste = waste;
142994       }
142995     }
142996   }
142997 
142998   *piLeftSeed = iLeftSeed;
142999   *piRightSeed = iRightSeed;
143000 }
143001 #endif /* VARIANT_GUTTMAN_QUADRATIC_SPLIT */
143002 
143003 /*
143004 ** Arguments aIdx, aDistance and aSpare all point to arrays of size
143005 ** nIdx. The aIdx array contains the set of integers from 0 to 
143006 ** (nIdx-1) in no particular order. This function sorts the values
143007 ** in aIdx according to the indexed values in aDistance. For
143008 ** example, assuming the inputs:
143009 **
143010 **   aIdx      = { 0,   1,   2,   3 }
143011 **   aDistance = { 5.0, 2.0, 7.0, 6.0 }
143012 **
143013 ** this function sets the aIdx array to contain:
143014 **
143015 **   aIdx      = { 0,   1,   2,   3 }
143016 **
143017 ** The aSpare array is used as temporary working space by the
143018 ** sorting algorithm.
143019 */
143020 static void SortByDistance(
143021   int *aIdx, 
143022   int nIdx, 
143023   RtreeDValue *aDistance, 
143024   int *aSpare
143025 ){
143026   if( nIdx>1 ){
143027     int iLeft = 0;
143028     int iRight = 0;
143029 
143030     int nLeft = nIdx/2;
143031     int nRight = nIdx-nLeft;
143032     int *aLeft = aIdx;
143033     int *aRight = &aIdx[nLeft];
143034 
143035     SortByDistance(aLeft, nLeft, aDistance, aSpare);
143036     SortByDistance(aRight, nRight, aDistance, aSpare);
143037 
143038     memcpy(aSpare, aLeft, sizeof(int)*nLeft);
143039     aLeft = aSpare;
143040 
143041     while( iLeft<nLeft || iRight<nRight ){
143042       if( iLeft==nLeft ){
143043         aIdx[iLeft+iRight] = aRight[iRight];
143044         iRight++;
143045       }else if( iRight==nRight ){
143046         aIdx[iLeft+iRight] = aLeft[iLeft];
143047         iLeft++;
143048       }else{
143049         RtreeDValue fLeft = aDistance[aLeft[iLeft]];
143050         RtreeDValue fRight = aDistance[aRight[iRight]];
143051         if( fLeft<fRight ){
143052           aIdx[iLeft+iRight] = aLeft[iLeft];
143053           iLeft++;
143054         }else{
143055           aIdx[iLeft+iRight] = aRight[iRight];
143056           iRight++;
143057         }
143058       }
143059     }
143060 
143061 #if 0
143062     /* Check that the sort worked */
143063     {
143064       int jj;
143065       for(jj=1; jj<nIdx; jj++){
143066         RtreeDValue left = aDistance[aIdx[jj-1]];
143067         RtreeDValue right = aDistance[aIdx[jj]];
143068         assert( left<=right );
143069       }
143070     }
143071 #endif
143072   }
143073 }
143074 
143075 /*
143076 ** Arguments aIdx, aCell and aSpare all point to arrays of size
143077 ** nIdx. The aIdx array contains the set of integers from 0 to 
143078 ** (nIdx-1) in no particular order. This function sorts the values
143079 ** in aIdx according to dimension iDim of the cells in aCell. The
143080 ** minimum value of dimension iDim is considered first, the
143081 ** maximum used to break ties.
143082 **
143083 ** The aSpare array is used as temporary working space by the
143084 ** sorting algorithm.
143085 */
143086 static void SortByDimension(
143087   Rtree *pRtree,
143088   int *aIdx, 
143089   int nIdx, 
143090   int iDim, 
143091   RtreeCell *aCell, 
143092   int *aSpare
143093 ){
143094   if( nIdx>1 ){
143095 
143096     int iLeft = 0;
143097     int iRight = 0;
143098 
143099     int nLeft = nIdx/2;
143100     int nRight = nIdx-nLeft;
143101     int *aLeft = aIdx;
143102     int *aRight = &aIdx[nLeft];
143103 
143104     SortByDimension(pRtree, aLeft, nLeft, iDim, aCell, aSpare);
143105     SortByDimension(pRtree, aRight, nRight, iDim, aCell, aSpare);
143106 
143107     memcpy(aSpare, aLeft, sizeof(int)*nLeft);
143108     aLeft = aSpare;
143109     while( iLeft<nLeft || iRight<nRight ){
143110       RtreeDValue xleft1 = DCOORD(aCell[aLeft[iLeft]].aCoord[iDim*2]);
143111       RtreeDValue xleft2 = DCOORD(aCell[aLeft[iLeft]].aCoord[iDim*2+1]);
143112       RtreeDValue xright1 = DCOORD(aCell[aRight[iRight]].aCoord[iDim*2]);
143113       RtreeDValue xright2 = DCOORD(aCell[aRight[iRight]].aCoord[iDim*2+1]);
143114       if( (iLeft!=nLeft) && ((iRight==nRight)
143115        || (xleft1<xright1)
143116        || (xleft1==xright1 && xleft2<xright2)
143117       )){
143118         aIdx[iLeft+iRight] = aLeft[iLeft];
143119         iLeft++;
143120       }else{
143121         aIdx[iLeft+iRight] = aRight[iRight];
143122         iRight++;
143123       }
143124     }
143125 
143126 #if 0
143127     /* Check that the sort worked */
143128     {
143129       int jj;
143130       for(jj=1; jj<nIdx; jj++){
143131         RtreeDValue xleft1 = aCell[aIdx[jj-1]].aCoord[iDim*2];
143132         RtreeDValue xleft2 = aCell[aIdx[jj-1]].aCoord[iDim*2+1];
143133         RtreeDValue xright1 = aCell[aIdx[jj]].aCoord[iDim*2];
143134         RtreeDValue xright2 = aCell[aIdx[jj]].aCoord[iDim*2+1];
143135         assert( xleft1<=xright1 && (xleft1<xright1 || xleft2<=xright2) );
143136       }
143137     }
143138 #endif
143139   }
143140 }
143141 
143142 #if VARIANT_RSTARTREE_SPLIT
143143 /*
143144 ** Implementation of the R*-tree variant of SplitNode from Beckman[1990].
143145 */
143146 static int splitNodeStartree(
143147   Rtree *pRtree,
143148   RtreeCell *aCell,
143149   int nCell,
143150   RtreeNode *pLeft,
143151   RtreeNode *pRight,
143152   RtreeCell *pBboxLeft,
143153   RtreeCell *pBboxRight
143154 ){
143155   int **aaSorted;
143156   int *aSpare;
143157   int ii;
143158 
143159   int iBestDim = 0;
143160   int iBestSplit = 0;
143161   RtreeDValue fBestMargin = 0.0;
143162 
143163   int nByte = (pRtree->nDim+1)*(sizeof(int*)+nCell*sizeof(int));
143164 
143165   aaSorted = (int **)sqlite3_malloc(nByte);
143166   if( !aaSorted ){
143167     return SQLITE_NOMEM;
143168   }
143169 
143170   aSpare = &((int *)&aaSorted[pRtree->nDim])[pRtree->nDim*nCell];
143171   memset(aaSorted, 0, nByte);
143172   for(ii=0; ii<pRtree->nDim; ii++){
143173     int jj;
143174     aaSorted[ii] = &((int *)&aaSorted[pRtree->nDim])[ii*nCell];
143175     for(jj=0; jj<nCell; jj++){
143176       aaSorted[ii][jj] = jj;
143177     }
143178     SortByDimension(pRtree, aaSorted[ii], nCell, ii, aCell, aSpare);
143179   }
143180 
143181   for(ii=0; ii<pRtree->nDim; ii++){
143182     RtreeDValue margin = 0.0;
143183     RtreeDValue fBestOverlap = 0.0;
143184     RtreeDValue fBestArea = 0.0;
143185     int iBestLeft = 0;
143186     int nLeft;
143187 
143188     for(
143189       nLeft=RTREE_MINCELLS(pRtree); 
143190       nLeft<=(nCell-RTREE_MINCELLS(pRtree)); 
143191       nLeft++
143192     ){
143193       RtreeCell left;
143194       RtreeCell right;
143195       int kk;
143196       RtreeDValue overlap;
143197       RtreeDValue area;
143198 
143199       memcpy(&left, &aCell[aaSorted[ii][0]], sizeof(RtreeCell));
143200       memcpy(&right, &aCell[aaSorted[ii][nCell-1]], sizeof(RtreeCell));
143201       for(kk=1; kk<(nCell-1); kk++){
143202         if( kk<nLeft ){
143203           cellUnion(pRtree, &left, &aCell[aaSorted[ii][kk]]);
143204         }else{
143205           cellUnion(pRtree, &right, &aCell[aaSorted[ii][kk]]);
143206         }
143207       }
143208       margin += cellMargin(pRtree, &left);
143209       margin += cellMargin(pRtree, &right);
143210       overlap = cellOverlap(pRtree, &left, &right, 1, -1);
143211       area = cellArea(pRtree, &left) + cellArea(pRtree, &right);
143212       if( (nLeft==RTREE_MINCELLS(pRtree))
143213        || (overlap<fBestOverlap)
143214        || (overlap==fBestOverlap && area<fBestArea)
143215       ){
143216         iBestLeft = nLeft;
143217         fBestOverlap = overlap;
143218         fBestArea = area;
143219       }
143220     }
143221 
143222     if( ii==0 || margin<fBestMargin ){
143223       iBestDim = ii;
143224       fBestMargin = margin;
143225       iBestSplit = iBestLeft;
143226     }
143227   }
143228 
143229   memcpy(pBboxLeft, &aCell[aaSorted[iBestDim][0]], sizeof(RtreeCell));
143230   memcpy(pBboxRight, &aCell[aaSorted[iBestDim][iBestSplit]], sizeof(RtreeCell));
143231   for(ii=0; ii<nCell; ii++){
143232     RtreeNode *pTarget = (ii<iBestSplit)?pLeft:pRight;
143233     RtreeCell *pBbox = (ii<iBestSplit)?pBboxLeft:pBboxRight;
143234     RtreeCell *pCell = &aCell[aaSorted[iBestDim][ii]];
143235     nodeInsertCell(pRtree, pTarget, pCell);
143236     cellUnion(pRtree, pBbox, pCell);
143237   }
143238 
143239   sqlite3_free(aaSorted);
143240   return SQLITE_OK;
143241 }
143242 #endif
143243 
143244 #if VARIANT_GUTTMAN_SPLIT
143245 /*
143246 ** Implementation of the regular R-tree SplitNode from Guttman[1984].
143247 */
143248 static int splitNodeGuttman(
143249   Rtree *pRtree,
143250   RtreeCell *aCell,
143251   int nCell,
143252   RtreeNode *pLeft,
143253   RtreeNode *pRight,
143254   RtreeCell *pBboxLeft,
143255   RtreeCell *pBboxRight
143256 ){
143257   int iLeftSeed = 0;
143258   int iRightSeed = 1;
143259   int *aiUsed;
143260   int i;
143261 
143262   aiUsed = sqlite3_malloc(sizeof(int)*nCell);
143263   if( !aiUsed ){
143264     return SQLITE_NOMEM;
143265   }
143266   memset(aiUsed, 0, sizeof(int)*nCell);
143267 
143268   PickSeeds(pRtree, aCell, nCell, &iLeftSeed, &iRightSeed);
143269 
143270   memcpy(pBboxLeft, &aCell[iLeftSeed], sizeof(RtreeCell));
143271   memcpy(pBboxRight, &aCell[iRightSeed], sizeof(RtreeCell));
143272   nodeInsertCell(pRtree, pLeft, &aCell[iLeftSeed]);
143273   nodeInsertCell(pRtree, pRight, &aCell[iRightSeed]);
143274   aiUsed[iLeftSeed] = 1;
143275   aiUsed[iRightSeed] = 1;
143276 
143277   for(i=nCell-2; i>0; i--){
143278     RtreeCell *pNext;
143279     pNext = PickNext(pRtree, aCell, nCell, pBboxLeft, pBboxRight, aiUsed);
143280     RtreeDValue diff =  
143281       cellGrowth(pRtree, pBboxLeft, pNext) - 
143282       cellGrowth(pRtree, pBboxRight, pNext)
143283     ;
143284     if( (RTREE_MINCELLS(pRtree)-NCELL(pRight)==i)
143285      || (diff>0.0 && (RTREE_MINCELLS(pRtree)-NCELL(pLeft)!=i))
143286     ){
143287       nodeInsertCell(pRtree, pRight, pNext);
143288       cellUnion(pRtree, pBboxRight, pNext);
143289     }else{
143290       nodeInsertCell(pRtree, pLeft, pNext);
143291       cellUnion(pRtree, pBboxLeft, pNext);
143292     }
143293   }
143294 
143295   sqlite3_free(aiUsed);
143296   return SQLITE_OK;
143297 }
143298 #endif
143299 
143300 static int updateMapping(
143301   Rtree *pRtree, 
143302   i64 iRowid, 
143303   RtreeNode *pNode, 
143304   int iHeight
143305 ){
143306   int (*xSetMapping)(Rtree *, sqlite3_int64, sqlite3_int64);
143307   xSetMapping = ((iHeight==0)?rowidWrite:parentWrite);
143308   if( iHeight>0 ){
143309     RtreeNode *pChild = nodeHashLookup(pRtree, iRowid);
143310     if( pChild ){
143311       nodeRelease(pRtree, pChild->pParent);
143312       nodeReference(pNode);
143313       pChild->pParent = pNode;
143314     }
143315   }
143316   return xSetMapping(pRtree, iRowid, pNode->iNode);
143317 }
143318 
143319 static int SplitNode(
143320   Rtree *pRtree,
143321   RtreeNode *pNode,
143322   RtreeCell *pCell,
143323   int iHeight
143324 ){
143325   int i;
143326   int newCellIsRight = 0;
143327 
143328   int rc = SQLITE_OK;
143329   int nCell = NCELL(pNode);
143330   RtreeCell *aCell;
143331   int *aiUsed;
143332 
143333   RtreeNode *pLeft = 0;
143334   RtreeNode *pRight = 0;
143335 
143336   RtreeCell leftbbox;
143337   RtreeCell rightbbox;
143338 
143339   /* Allocate an array and populate it with a copy of pCell and 
143340   ** all cells from node pLeft. Then zero the original node.
143341   */
143342   aCell = sqlite3_malloc((sizeof(RtreeCell)+sizeof(int))*(nCell+1));
143343   if( !aCell ){
143344     rc = SQLITE_NOMEM;
143345     goto splitnode_out;
143346   }
143347   aiUsed = (int *)&aCell[nCell+1];
143348   memset(aiUsed, 0, sizeof(int)*(nCell+1));
143349   for(i=0; i<nCell; i++){
143350     nodeGetCell(pRtree, pNode, i, &aCell[i]);
143351   }
143352   nodeZero(pRtree, pNode);
143353   memcpy(&aCell[nCell], pCell, sizeof(RtreeCell));
143354   nCell++;
143355 
143356   if( pNode->iNode==1 ){
143357     pRight = nodeNew(pRtree, pNode);
143358     pLeft = nodeNew(pRtree, pNode);
143359     pRtree->iDepth++;
143360     pNode->isDirty = 1;
143361     writeInt16(pNode->zData, pRtree->iDepth);
143362   }else{
143363     pLeft = pNode;
143364     pRight = nodeNew(pRtree, pLeft->pParent);
143365     nodeReference(pLeft);
143366   }
143367 
143368   if( !pLeft || !pRight ){
143369     rc = SQLITE_NOMEM;
143370     goto splitnode_out;
143371   }
143372 
143373   memset(pLeft->zData, 0, pRtree->iNodeSize);
143374   memset(pRight->zData, 0, pRtree->iNodeSize);
143375 
143376   rc = AssignCells(pRtree, aCell, nCell, pLeft, pRight, &leftbbox, &rightbbox);
143377   if( rc!=SQLITE_OK ){
143378     goto splitnode_out;
143379   }
143380 
143381   /* Ensure both child nodes have node numbers assigned to them by calling
143382   ** nodeWrite(). Node pRight always needs a node number, as it was created
143383   ** by nodeNew() above. But node pLeft sometimes already has a node number.
143384   ** In this case avoid the all to nodeWrite().
143385   */
143386   if( SQLITE_OK!=(rc = nodeWrite(pRtree, pRight))
143387    || (0==pLeft->iNode && SQLITE_OK!=(rc = nodeWrite(pRtree, pLeft)))
143388   ){
143389     goto splitnode_out;
143390   }
143391 
143392   rightbbox.iRowid = pRight->iNode;
143393   leftbbox.iRowid = pLeft->iNode;
143394 
143395   if( pNode->iNode==1 ){
143396     rc = rtreeInsertCell(pRtree, pLeft->pParent, &leftbbox, iHeight+1);
143397     if( rc!=SQLITE_OK ){
143398       goto splitnode_out;
143399     }
143400   }else{
143401     RtreeNode *pParent = pLeft->pParent;
143402     int iCell;
143403     rc = nodeParentIndex(pRtree, pLeft, &iCell);
143404     if( rc==SQLITE_OK ){
143405       nodeOverwriteCell(pRtree, pParent, &leftbbox, iCell);
143406       rc = AdjustTree(pRtree, pParent, &leftbbox);
143407     }
143408     if( rc!=SQLITE_OK ){
143409       goto splitnode_out;
143410     }
143411   }
143412   if( (rc = rtreeInsertCell(pRtree, pRight->pParent, &rightbbox, iHeight+1)) ){
143413     goto splitnode_out;
143414   }
143415 
143416   for(i=0; i<NCELL(pRight); i++){
143417     i64 iRowid = nodeGetRowid(pRtree, pRight, i);
143418     rc = updateMapping(pRtree, iRowid, pRight, iHeight);
143419     if( iRowid==pCell->iRowid ){
143420       newCellIsRight = 1;
143421     }
143422     if( rc!=SQLITE_OK ){
143423       goto splitnode_out;
143424     }
143425   }
143426   if( pNode->iNode==1 ){
143427     for(i=0; i<NCELL(pLeft); i++){
143428       i64 iRowid = nodeGetRowid(pRtree, pLeft, i);
143429       rc = updateMapping(pRtree, iRowid, pLeft, iHeight);
143430       if( rc!=SQLITE_OK ){
143431         goto splitnode_out;
143432       }
143433     }
143434   }else if( newCellIsRight==0 ){
143435     rc = updateMapping(pRtree, pCell->iRowid, pLeft, iHeight);
143436   }
143437 
143438   if( rc==SQLITE_OK ){
143439     rc = nodeRelease(pRtree, pRight);
143440     pRight = 0;
143441   }
143442   if( rc==SQLITE_OK ){
143443     rc = nodeRelease(pRtree, pLeft);
143444     pLeft = 0;
143445   }
143446 
143447 splitnode_out:
143448   nodeRelease(pRtree, pRight);
143449   nodeRelease(pRtree, pLeft);
143450   sqlite3_free(aCell);
143451   return rc;
143452 }
143453 
143454 /*
143455 ** If node pLeaf is not the root of the r-tree and its pParent pointer is 
143456 ** still NULL, load all ancestor nodes of pLeaf into memory and populate
143457 ** the pLeaf->pParent chain all the way up to the root node.
143458 **
143459 ** This operation is required when a row is deleted (or updated - an update
143460 ** is implemented as a delete followed by an insert). SQLite provides the
143461 ** rowid of the row to delete, which can be used to find the leaf on which
143462 ** the entry resides (argument pLeaf). Once the leaf is located, this 
143463 ** function is called to determine its ancestry.
143464 */
143465 static int fixLeafParent(Rtree *pRtree, RtreeNode *pLeaf){
143466   int rc = SQLITE_OK;
143467   RtreeNode *pChild = pLeaf;
143468   while( rc==SQLITE_OK && pChild->iNode!=1 && pChild->pParent==0 ){
143469     int rc2 = SQLITE_OK;          /* sqlite3_reset() return code */
143470     sqlite3_bind_int64(pRtree->pReadParent, 1, pChild->iNode);
143471     rc = sqlite3_step(pRtree->pReadParent);
143472     if( rc==SQLITE_ROW ){
143473       RtreeNode *pTest;           /* Used to test for reference loops */
143474       i64 iNode;                  /* Node number of parent node */
143475 
143476       /* Before setting pChild->pParent, test that we are not creating a
143477       ** loop of references (as we would if, say, pChild==pParent). We don't
143478       ** want to do this as it leads to a memory leak when trying to delete
143479       ** the referenced counted node structures.
143480       */
143481       iNode = sqlite3_column_int64(pRtree->pReadParent, 0);
143482       for(pTest=pLeaf; pTest && pTest->iNode!=iNode; pTest=pTest->pParent);
143483       if( !pTest ){
143484         rc2 = nodeAcquire(pRtree, iNode, 0, &pChild->pParent);
143485       }
143486     }
143487     rc = sqlite3_reset(pRtree->pReadParent);
143488     if( rc==SQLITE_OK ) rc = rc2;
143489     if( rc==SQLITE_OK && !pChild->pParent ) rc = SQLITE_CORRUPT_VTAB;
143490     pChild = pChild->pParent;
143491   }
143492   return rc;
143493 }
143494 
143495 static int deleteCell(Rtree *, RtreeNode *, int, int);
143496 
143497 static int removeNode(Rtree *pRtree, RtreeNode *pNode, int iHeight){
143498   int rc;
143499   int rc2;
143500   RtreeNode *pParent = 0;
143501   int iCell;
143502 
143503   assert( pNode->nRef==1 );
143504 
143505   /* Remove the entry in the parent cell. */
143506   rc = nodeParentIndex(pRtree, pNode, &iCell);
143507   if( rc==SQLITE_OK ){
143508     pParent = pNode->pParent;
143509     pNode->pParent = 0;
143510     rc = deleteCell(pRtree, pParent, iCell, iHeight+1);
143511   }
143512   rc2 = nodeRelease(pRtree, pParent);
143513   if( rc==SQLITE_OK ){
143514     rc = rc2;
143515   }
143516   if( rc!=SQLITE_OK ){
143517     return rc;
143518   }
143519 
143520   /* Remove the xxx_node entry. */
143521   sqlite3_bind_int64(pRtree->pDeleteNode, 1, pNode->iNode);
143522   sqlite3_step(pRtree->pDeleteNode);
143523   if( SQLITE_OK!=(rc = sqlite3_reset(pRtree->pDeleteNode)) ){
143524     return rc;
143525   }
143526 
143527   /* Remove the xxx_parent entry. */
143528   sqlite3_bind_int64(pRtree->pDeleteParent, 1, pNode->iNode);
143529   sqlite3_step(pRtree->pDeleteParent);
143530   if( SQLITE_OK!=(rc = sqlite3_reset(pRtree->pDeleteParent)) ){
143531     return rc;
143532   }
143533   
143534   /* Remove the node from the in-memory hash table and link it into
143535   ** the Rtree.pDeleted list. Its contents will be re-inserted later on.
143536   */
143537   nodeHashDelete(pRtree, pNode);
143538   pNode->iNode = iHeight;
143539   pNode->pNext = pRtree->pDeleted;
143540   pNode->nRef++;
143541   pRtree->pDeleted = pNode;
143542 
143543   return SQLITE_OK;
143544 }
143545 
143546 static int fixBoundingBox(Rtree *pRtree, RtreeNode *pNode){
143547   RtreeNode *pParent = pNode->pParent;
143548   int rc = SQLITE_OK; 
143549   if( pParent ){
143550     int ii; 
143551     int nCell = NCELL(pNode);
143552     RtreeCell box;                            /* Bounding box for pNode */
143553     nodeGetCell(pRtree, pNode, 0, &box);
143554     for(ii=1; ii<nCell; ii++){
143555       RtreeCell cell;
143556       nodeGetCell(pRtree, pNode, ii, &cell);
143557       cellUnion(pRtree, &box, &cell);
143558     }
143559     box.iRowid = pNode->iNode;
143560     rc = nodeParentIndex(pRtree, pNode, &ii);
143561     if( rc==SQLITE_OK ){
143562       nodeOverwriteCell(pRtree, pParent, &box, ii);
143563       rc = fixBoundingBox(pRtree, pParent);
143564     }
143565   }
143566   return rc;
143567 }
143568 
143569 /*
143570 ** Delete the cell at index iCell of node pNode. After removing the
143571 ** cell, adjust the r-tree data structure if required.
143572 */
143573 static int deleteCell(Rtree *pRtree, RtreeNode *pNode, int iCell, int iHeight){
143574   RtreeNode *pParent;
143575   int rc;
143576 
143577   if( SQLITE_OK!=(rc = fixLeafParent(pRtree, pNode)) ){
143578     return rc;
143579   }
143580 
143581   /* Remove the cell from the node. This call just moves bytes around
143582   ** the in-memory node image, so it cannot fail.
143583   */
143584   nodeDeleteCell(pRtree, pNode, iCell);
143585 
143586   /* If the node is not the tree root and now has less than the minimum
143587   ** number of cells, remove it from the tree. Otherwise, update the
143588   ** cell in the parent node so that it tightly contains the updated
143589   ** node.
143590   */
143591   pParent = pNode->pParent;
143592   assert( pParent || pNode->iNode==1 );
143593   if( pParent ){
143594     if( NCELL(pNode)<RTREE_MINCELLS(pRtree) ){
143595       rc = removeNode(pRtree, pNode, iHeight);
143596     }else{
143597       rc = fixBoundingBox(pRtree, pNode);
143598     }
143599   }
143600 
143601   return rc;
143602 }
143603 
143604 static int Reinsert(
143605   Rtree *pRtree, 
143606   RtreeNode *pNode, 
143607   RtreeCell *pCell, 
143608   int iHeight
143609 ){
143610   int *aOrder;
143611   int *aSpare;
143612   RtreeCell *aCell;
143613   RtreeDValue *aDistance;
143614   int nCell;
143615   RtreeDValue aCenterCoord[RTREE_MAX_DIMENSIONS];
143616   int iDim;
143617   int ii;
143618   int rc = SQLITE_OK;
143619   int n;
143620 
143621   memset(aCenterCoord, 0, sizeof(RtreeDValue)*RTREE_MAX_DIMENSIONS);
143622 
143623   nCell = NCELL(pNode)+1;
143624   n = (nCell+1)&(~1);
143625 
143626   /* Allocate the buffers used by this operation. The allocation is
143627   ** relinquished before this function returns.
143628   */
143629   aCell = (RtreeCell *)sqlite3_malloc(n * (
143630     sizeof(RtreeCell)     +         /* aCell array */
143631     sizeof(int)           +         /* aOrder array */
143632     sizeof(int)           +         /* aSpare array */
143633     sizeof(RtreeDValue)             /* aDistance array */
143634   ));
143635   if( !aCell ){
143636     return SQLITE_NOMEM;
143637   }
143638   aOrder    = (int *)&aCell[n];
143639   aSpare    = (int *)&aOrder[n];
143640   aDistance = (RtreeDValue *)&aSpare[n];
143641 
143642   for(ii=0; ii<nCell; ii++){
143643     if( ii==(nCell-1) ){
143644       memcpy(&aCell[ii], pCell, sizeof(RtreeCell));
143645     }else{
143646       nodeGetCell(pRtree, pNode, ii, &aCell[ii]);
143647     }
143648     aOrder[ii] = ii;
143649     for(iDim=0; iDim<pRtree->nDim; iDim++){
143650       aCenterCoord[iDim] += DCOORD(aCell[ii].aCoord[iDim*2]);
143651       aCenterCoord[iDim] += DCOORD(aCell[ii].aCoord[iDim*2+1]);
143652     }
143653   }
143654   for(iDim=0; iDim<pRtree->nDim; iDim++){
143655     aCenterCoord[iDim] = (aCenterCoord[iDim]/(nCell*(RtreeDValue)2));
143656   }
143657 
143658   for(ii=0; ii<nCell; ii++){
143659     aDistance[ii] = 0.0;
143660     for(iDim=0; iDim<pRtree->nDim; iDim++){
143661       RtreeDValue coord = (DCOORD(aCell[ii].aCoord[iDim*2+1]) - 
143662                                DCOORD(aCell[ii].aCoord[iDim*2]));
143663       aDistance[ii] += (coord-aCenterCoord[iDim])*(coord-aCenterCoord[iDim]);
143664     }
143665   }
143666 
143667   SortByDistance(aOrder, nCell, aDistance, aSpare);
143668   nodeZero(pRtree, pNode);
143669 
143670   for(ii=0; rc==SQLITE_OK && ii<(nCell-(RTREE_MINCELLS(pRtree)+1)); ii++){
143671     RtreeCell *p = &aCell[aOrder[ii]];
143672     nodeInsertCell(pRtree, pNode, p);
143673     if( p->iRowid==pCell->iRowid ){
143674       if( iHeight==0 ){
143675         rc = rowidWrite(pRtree, p->iRowid, pNode->iNode);
143676       }else{
143677         rc = parentWrite(pRtree, p->iRowid, pNode->iNode);
143678       }
143679     }
143680   }
143681   if( rc==SQLITE_OK ){
143682     rc = fixBoundingBox(pRtree, pNode);
143683   }
143684   for(; rc==SQLITE_OK && ii<nCell; ii++){
143685     /* Find a node to store this cell in. pNode->iNode currently contains
143686     ** the height of the sub-tree headed by the cell.
143687     */
143688     RtreeNode *pInsert;
143689     RtreeCell *p = &aCell[aOrder[ii]];
143690     rc = ChooseLeaf(pRtree, p, iHeight, &pInsert);
143691     if( rc==SQLITE_OK ){
143692       int rc2;
143693       rc = rtreeInsertCell(pRtree, pInsert, p, iHeight);
143694       rc2 = nodeRelease(pRtree, pInsert);
143695       if( rc==SQLITE_OK ){
143696         rc = rc2;
143697       }
143698     }
143699   }
143700 
143701   sqlite3_free(aCell);
143702   return rc;
143703 }
143704 
143705 /*
143706 ** Insert cell pCell into node pNode. Node pNode is the head of a 
143707 ** subtree iHeight high (leaf nodes have iHeight==0).
143708 */
143709 static int rtreeInsertCell(
143710   Rtree *pRtree,
143711   RtreeNode *pNode,
143712   RtreeCell *pCell,
143713   int iHeight
143714 ){
143715   int rc = SQLITE_OK;
143716   if( iHeight>0 ){
143717     RtreeNode *pChild = nodeHashLookup(pRtree, pCell->iRowid);
143718     if( pChild ){
143719       nodeRelease(pRtree, pChild->pParent);
143720       nodeReference(pNode);
143721       pChild->pParent = pNode;
143722     }
143723   }
143724   if( nodeInsertCell(pRtree, pNode, pCell) ){
143725 #if VARIANT_RSTARTREE_REINSERT
143726     if( iHeight<=pRtree->iReinsertHeight || pNode->iNode==1){
143727       rc = SplitNode(pRtree, pNode, pCell, iHeight);
143728     }else{
143729       pRtree->iReinsertHeight = iHeight;
143730       rc = Reinsert(pRtree, pNode, pCell, iHeight);
143731     }
143732 #else
143733     rc = SplitNode(pRtree, pNode, pCell, iHeight);
143734 #endif
143735   }else{
143736     rc = AdjustTree(pRtree, pNode, pCell);
143737     if( rc==SQLITE_OK ){
143738       if( iHeight==0 ){
143739         rc = rowidWrite(pRtree, pCell->iRowid, pNode->iNode);
143740       }else{
143741         rc = parentWrite(pRtree, pCell->iRowid, pNode->iNode);
143742       }
143743     }
143744   }
143745   return rc;
143746 }
143747 
143748 static int reinsertNodeContent(Rtree *pRtree, RtreeNode *pNode){
143749   int ii;
143750   int rc = SQLITE_OK;
143751   int nCell = NCELL(pNode);
143752 
143753   for(ii=0; rc==SQLITE_OK && ii<nCell; ii++){
143754     RtreeNode *pInsert;
143755     RtreeCell cell;
143756     nodeGetCell(pRtree, pNode, ii, &cell);
143757 
143758     /* Find a node to store this cell in. pNode->iNode currently contains
143759     ** the height of the sub-tree headed by the cell.
143760     */
143761     rc = ChooseLeaf(pRtree, &cell, (int)pNode->iNode, &pInsert);
143762     if( rc==SQLITE_OK ){
143763       int rc2;
143764       rc = rtreeInsertCell(pRtree, pInsert, &cell, (int)pNode->iNode);
143765       rc2 = nodeRelease(pRtree, pInsert);
143766       if( rc==SQLITE_OK ){
143767         rc = rc2;
143768       }
143769     }
143770   }
143771   return rc;
143772 }
143773 
143774 /*
143775 ** Select a currently unused rowid for a new r-tree record.
143776 */
143777 static int newRowid(Rtree *pRtree, i64 *piRowid){
143778   int rc;
143779   sqlite3_bind_null(pRtree->pWriteRowid, 1);
143780   sqlite3_bind_null(pRtree->pWriteRowid, 2);
143781   sqlite3_step(pRtree->pWriteRowid);
143782   rc = sqlite3_reset(pRtree->pWriteRowid);
143783   *piRowid = sqlite3_last_insert_rowid(pRtree->db);
143784   return rc;
143785 }
143786 
143787 /*
143788 ** Remove the entry with rowid=iDelete from the r-tree structure.
143789 */
143790 static int rtreeDeleteRowid(Rtree *pRtree, sqlite3_int64 iDelete){
143791   int rc;                         /* Return code */
143792   RtreeNode *pLeaf = 0;           /* Leaf node containing record iDelete */
143793   int iCell;                      /* Index of iDelete cell in pLeaf */
143794   RtreeNode *pRoot;               /* Root node of rtree structure */
143795 
143796 
143797   /* Obtain a reference to the root node to initialize Rtree.iDepth */
143798   rc = nodeAcquire(pRtree, 1, 0, &pRoot);
143799 
143800   /* Obtain a reference to the leaf node that contains the entry 
143801   ** about to be deleted. 
143802   */
143803   if( rc==SQLITE_OK ){
143804     rc = findLeafNode(pRtree, iDelete, &pLeaf);
143805   }
143806 
143807   /* Delete the cell in question from the leaf node. */
143808   if( rc==SQLITE_OK ){
143809     int rc2;
143810     rc = nodeRowidIndex(pRtree, pLeaf, iDelete, &iCell);
143811     if( rc==SQLITE_OK ){
143812       rc = deleteCell(pRtree, pLeaf, iCell, 0);
143813     }
143814     rc2 = nodeRelease(pRtree, pLeaf);
143815     if( rc==SQLITE_OK ){
143816       rc = rc2;
143817     }
143818   }
143819 
143820   /* Delete the corresponding entry in the <rtree>_rowid table. */
143821   if( rc==SQLITE_OK ){
143822     sqlite3_bind_int64(pRtree->pDeleteRowid, 1, iDelete);
143823     sqlite3_step(pRtree->pDeleteRowid);
143824     rc = sqlite3_reset(pRtree->pDeleteRowid);
143825   }
143826 
143827   /* Check if the root node now has exactly one child. If so, remove
143828   ** it, schedule the contents of the child for reinsertion and 
143829   ** reduce the tree height by one.
143830   **
143831   ** This is equivalent to copying the contents of the child into
143832   ** the root node (the operation that Gutman's paper says to perform 
143833   ** in this scenario).
143834   */
143835   if( rc==SQLITE_OK && pRtree->iDepth>0 && NCELL(pRoot)==1 ){
143836     int rc2;
143837     RtreeNode *pChild;
143838     i64 iChild = nodeGetRowid(pRtree, pRoot, 0);
143839     rc = nodeAcquire(pRtree, iChild, pRoot, &pChild);
143840     if( rc==SQLITE_OK ){
143841       rc = removeNode(pRtree, pChild, pRtree->iDepth-1);
143842     }
143843     rc2 = nodeRelease(pRtree, pChild);
143844     if( rc==SQLITE_OK ) rc = rc2;
143845     if( rc==SQLITE_OK ){
143846       pRtree->iDepth--;
143847       writeInt16(pRoot->zData, pRtree->iDepth);
143848       pRoot->isDirty = 1;
143849     }
143850   }
143851 
143852   /* Re-insert the contents of any underfull nodes removed from the tree. */
143853   for(pLeaf=pRtree->pDeleted; pLeaf; pLeaf=pRtree->pDeleted){
143854     if( rc==SQLITE_OK ){
143855       rc = reinsertNodeContent(pRtree, pLeaf);
143856     }
143857     pRtree->pDeleted = pLeaf->pNext;
143858     sqlite3_free(pLeaf);
143859   }
143860 
143861   /* Release the reference to the root node. */
143862   if( rc==SQLITE_OK ){
143863     rc = nodeRelease(pRtree, pRoot);
143864   }else{
143865     nodeRelease(pRtree, pRoot);
143866   }
143867 
143868   return rc;
143869 }
143870 
143871 /*
143872 ** Rounding constants for float->double conversion.
143873 */
143874 #define RNDTOWARDS  (1.0 - 1.0/8388608.0)  /* Round towards zero */
143875 #define RNDAWAY     (1.0 + 1.0/8388608.0)  /* Round away from zero */
143876 
143877 #if !defined(SQLITE_RTREE_INT_ONLY)
143878 /*
143879 ** Convert an sqlite3_value into an RtreeValue (presumably a float)
143880 ** while taking care to round toward negative or positive, respectively.
143881 */
143882 static RtreeValue rtreeValueDown(sqlite3_value *v){
143883   double d = sqlite3_value_double(v);
143884   float f = (float)d;
143885   if( f>d ){
143886     f = (float)(d*(d<0 ? RNDAWAY : RNDTOWARDS));
143887   }
143888   return f;
143889 }
143890 static RtreeValue rtreeValueUp(sqlite3_value *v){
143891   double d = sqlite3_value_double(v);
143892   float f = (float)d;
143893   if( f<d ){
143894     f = (float)(d*(d<0 ? RNDTOWARDS : RNDAWAY));
143895   }
143896   return f;
143897 }
143898 #endif /* !defined(SQLITE_RTREE_INT_ONLY) */
143899 
143900 
143901 /*
143902 ** The xUpdate method for rtree module virtual tables.
143903 */
143904 static int rtreeUpdate(
143905   sqlite3_vtab *pVtab, 
143906   int nData, 
143907   sqlite3_value **azData, 
143908   sqlite_int64 *pRowid
143909 ){
143910   Rtree *pRtree = (Rtree *)pVtab;
143911   int rc = SQLITE_OK;
143912   RtreeCell cell;                 /* New cell to insert if nData>1 */
143913   int bHaveRowid = 0;             /* Set to 1 after new rowid is determined */
143914 
143915   rtreeReference(pRtree);
143916   assert(nData>=1);
143917 
143918   /* Constraint handling. A write operation on an r-tree table may return
143919   ** SQLITE_CONSTRAINT for two reasons:
143920   **
143921   **   1. A duplicate rowid value, or
143922   **   2. The supplied data violates the "x2>=x1" constraint.
143923   **
143924   ** In the first case, if the conflict-handling mode is REPLACE, then
143925   ** the conflicting row can be removed before proceeding. In the second
143926   ** case, SQLITE_CONSTRAINT must be returned regardless of the
143927   ** conflict-handling mode specified by the user.
143928   */
143929   if( nData>1 ){
143930     int ii;
143931 
143932     /* Populate the cell.aCoord[] array. The first coordinate is azData[3]. */
143933     assert( nData==(pRtree->nDim*2 + 3) );
143934 #ifndef SQLITE_RTREE_INT_ONLY
143935     if( pRtree->eCoordType==RTREE_COORD_REAL32 ){
143936       for(ii=0; ii<(pRtree->nDim*2); ii+=2){
143937         cell.aCoord[ii].f = rtreeValueDown(azData[ii+3]);
143938         cell.aCoord[ii+1].f = rtreeValueUp(azData[ii+4]);
143939         if( cell.aCoord[ii].f>cell.aCoord[ii+1].f ){
143940           rc = SQLITE_CONSTRAINT;
143941           goto constraint;
143942         }
143943       }
143944     }else
143945 #endif
143946     {
143947       for(ii=0; ii<(pRtree->nDim*2); ii+=2){
143948         cell.aCoord[ii].i = sqlite3_value_int(azData[ii+3]);
143949         cell.aCoord[ii+1].i = sqlite3_value_int(azData[ii+4]);
143950         if( cell.aCoord[ii].i>cell.aCoord[ii+1].i ){
143951           rc = SQLITE_CONSTRAINT;
143952           goto constraint;
143953         }
143954       }
143955     }
143956 
143957     /* If a rowid value was supplied, check if it is already present in 
143958     ** the table. If so, the constraint has failed. */
143959     if( sqlite3_value_type(azData[2])!=SQLITE_NULL ){
143960       cell.iRowid = sqlite3_value_int64(azData[2]);
143961       if( sqlite3_value_type(azData[0])==SQLITE_NULL
143962        || sqlite3_value_int64(azData[0])!=cell.iRowid
143963       ){
143964         int steprc;
143965         sqlite3_bind_int64(pRtree->pReadRowid, 1, cell.iRowid);
143966         steprc = sqlite3_step(pRtree->pReadRowid);
143967         rc = sqlite3_reset(pRtree->pReadRowid);
143968         if( SQLITE_ROW==steprc ){
143969           if( sqlite3_vtab_on_conflict(pRtree->db)==SQLITE_REPLACE ){
143970             rc = rtreeDeleteRowid(pRtree, cell.iRowid);
143971           }else{
143972             rc = SQLITE_CONSTRAINT;
143973             goto constraint;
143974           }
143975         }
143976       }
143977       bHaveRowid = 1;
143978     }
143979   }
143980 
143981   /* If azData[0] is not an SQL NULL value, it is the rowid of a
143982   ** record to delete from the r-tree table. The following block does
143983   ** just that.
143984   */
143985   if( sqlite3_value_type(azData[0])!=SQLITE_NULL ){
143986     rc = rtreeDeleteRowid(pRtree, sqlite3_value_int64(azData[0]));
143987   }
143988 
143989   /* If the azData[] array contains more than one element, elements
143990   ** (azData[2]..azData[argc-1]) contain a new record to insert into
143991   ** the r-tree structure.
143992   */
143993   if( rc==SQLITE_OK && nData>1 ){
143994     /* Insert the new record into the r-tree */
143995     RtreeNode *pLeaf = 0;
143996 
143997     /* Figure out the rowid of the new row. */
143998     if( bHaveRowid==0 ){
143999       rc = newRowid(pRtree, &cell.iRowid);
144000     }
144001     *pRowid = cell.iRowid;
144002 
144003     if( rc==SQLITE_OK ){
144004       rc = ChooseLeaf(pRtree, &cell, 0, &pLeaf);
144005     }
144006     if( rc==SQLITE_OK ){
144007       int rc2;
144008       pRtree->iReinsertHeight = -1;
144009       rc = rtreeInsertCell(pRtree, pLeaf, &cell, 0);
144010       rc2 = nodeRelease(pRtree, pLeaf);
144011       if( rc==SQLITE_OK ){
144012         rc = rc2;
144013       }
144014     }
144015   }
144016 
144017 constraint:
144018   rtreeRelease(pRtree);
144019   return rc;
144020 }
144021 
144022 /*
144023 ** The xRename method for rtree module virtual tables.
144024 */
144025 static int rtreeRename(sqlite3_vtab *pVtab, const char *zNewName){
144026   Rtree *pRtree = (Rtree *)pVtab;
144027   int rc = SQLITE_NOMEM;
144028   char *zSql = sqlite3_mprintf(
144029     "ALTER TABLE %Q.'%q_node'   RENAME TO \"%w_node\";"
144030     "ALTER TABLE %Q.'%q_parent' RENAME TO \"%w_parent\";"
144031     "ALTER TABLE %Q.'%q_rowid'  RENAME TO \"%w_rowid\";"
144032     , pRtree->zDb, pRtree->zName, zNewName 
144033     , pRtree->zDb, pRtree->zName, zNewName 
144034     , pRtree->zDb, pRtree->zName, zNewName
144035   );
144036   if( zSql ){
144037     rc = sqlite3_exec(pRtree->db, zSql, 0, 0, 0);
144038     sqlite3_free(zSql);
144039   }
144040   return rc;
144041 }
144042 
144043 /*
144044 ** This function populates the pRtree->nRowEst variable with an estimate
144045 ** of the number of rows in the virtual table. If possible, this is based
144046 ** on sqlite_stat1 data. Otherwise, use RTREE_DEFAULT_ROWEST.
144047 */
144048 static int rtreeQueryStat1(sqlite3 *db, Rtree *pRtree){
144049   const char *zSql = "SELECT stat FROM sqlite_stat1 WHERE tbl= ? || '_rowid'";
144050   sqlite3_stmt *p;
144051   int rc;
144052   i64 nRow = 0;
144053 
144054   rc = sqlite3_prepare_v2(db, zSql, -1, &p, 0);
144055   if( rc==SQLITE_OK ){
144056     sqlite3_bind_text(p, 1, pRtree->zName, -1, SQLITE_STATIC);
144057     if( sqlite3_step(p)==SQLITE_ROW ) nRow = sqlite3_column_int64(p, 0);
144058     rc = sqlite3_finalize(p);
144059   }else if( rc!=SQLITE_NOMEM ){
144060     rc = SQLITE_OK;
144061   }
144062 
144063   if( rc==SQLITE_OK ){
144064     if( nRow==0 ){
144065       pRtree->nRowEst = RTREE_DEFAULT_ROWEST;
144066     }else{
144067       pRtree->nRowEst = MAX(nRow, RTREE_MIN_ROWEST);
144068     }
144069   }
144070 
144071   return rc;
144072 }
144073 
144074 static sqlite3_module rtreeModule = {
144075   0,                          /* iVersion */
144076   rtreeCreate,                /* xCreate - create a table */
144077   rtreeConnect,               /* xConnect - connect to an existing table */
144078   rtreeBestIndex,             /* xBestIndex - Determine search strategy */
144079   rtreeDisconnect,            /* xDisconnect - Disconnect from a table */
144080   rtreeDestroy,               /* xDestroy - Drop a table */
144081   rtreeOpen,                  /* xOpen - open a cursor */
144082   rtreeClose,                 /* xClose - close a cursor */
144083   rtreeFilter,                /* xFilter - configure scan constraints */
144084   rtreeNext,                  /* xNext - advance a cursor */
144085   rtreeEof,                   /* xEof */
144086   rtreeColumn,                /* xColumn - read data */
144087   rtreeRowid,                 /* xRowid - read data */
144088   rtreeUpdate,                /* xUpdate - write data */
144089   0,                          /* xBegin - begin transaction */
144090   0,                          /* xSync - sync transaction */
144091   0,                          /* xCommit - commit transaction */
144092   0,                          /* xRollback - rollback transaction */
144093   0,                          /* xFindFunction - function overloading */
144094   rtreeRename,                /* xRename - rename the table */
144095   0,                          /* xSavepoint */
144096   0,                          /* xRelease */
144097   0                           /* xRollbackTo */
144098 };
144099 
144100 static int rtreeSqlInit(
144101   Rtree *pRtree, 
144102   sqlite3 *db, 
144103   const char *zDb, 
144104   const char *zPrefix, 
144105   int isCreate
144106 ){
144107   int rc = SQLITE_OK;
144108 
144109   #define N_STATEMENT 9
144110   static const char *azSql[N_STATEMENT] = {
144111     /* Read and write the xxx_node table */
144112     "SELECT data FROM '%q'.'%q_node' WHERE nodeno = :1",
144113     "INSERT OR REPLACE INTO '%q'.'%q_node' VALUES(:1, :2)",
144114     "DELETE FROM '%q'.'%q_node' WHERE nodeno = :1",
144115 
144116     /* Read and write the xxx_rowid table */
144117     "SELECT nodeno FROM '%q'.'%q_rowid' WHERE rowid = :1",
144118     "INSERT OR REPLACE INTO '%q'.'%q_rowid' VALUES(:1, :2)",
144119     "DELETE FROM '%q'.'%q_rowid' WHERE rowid = :1",
144120 
144121     /* Read and write the xxx_parent table */
144122     "SELECT parentnode FROM '%q'.'%q_parent' WHERE nodeno = :1",
144123     "INSERT OR REPLACE INTO '%q'.'%q_parent' VALUES(:1, :2)",
144124     "DELETE FROM '%q'.'%q_parent' WHERE nodeno = :1"
144125   };
144126   sqlite3_stmt **appStmt[N_STATEMENT];
144127   int i;
144128 
144129   pRtree->db = db;
144130 
144131   if( isCreate ){
144132     char *zCreate = sqlite3_mprintf(
144133 "CREATE TABLE \"%w\".\"%w_node\"(nodeno INTEGER PRIMARY KEY, data BLOB);"
144134 "CREATE TABLE \"%w\".\"%w_rowid\"(rowid INTEGER PRIMARY KEY, nodeno INTEGER);"
144135 "CREATE TABLE \"%w\".\"%w_parent\"(nodeno INTEGER PRIMARY KEY, parentnode INTEGER);"
144136 "INSERT INTO '%q'.'%q_node' VALUES(1, zeroblob(%d))",
144137       zDb, zPrefix, zDb, zPrefix, zDb, zPrefix, zDb, zPrefix, pRtree->iNodeSize
144138     );
144139     if( !zCreate ){
144140       return SQLITE_NOMEM;
144141     }
144142     rc = sqlite3_exec(db, zCreate, 0, 0, 0);
144143     sqlite3_free(zCreate);
144144     if( rc!=SQLITE_OK ){
144145       return rc;
144146     }
144147   }
144148 
144149   appStmt[0] = &pRtree->pReadNode;
144150   appStmt[1] = &pRtree->pWriteNode;
144151   appStmt[2] = &pRtree->pDeleteNode;
144152   appStmt[3] = &pRtree->pReadRowid;
144153   appStmt[4] = &pRtree->pWriteRowid;
144154   appStmt[5] = &pRtree->pDeleteRowid;
144155   appStmt[6] = &pRtree->pReadParent;
144156   appStmt[7] = &pRtree->pWriteParent;
144157   appStmt[8] = &pRtree->pDeleteParent;
144158 
144159   rc = rtreeQueryStat1(db, pRtree);
144160   for(i=0; i<N_STATEMENT && rc==SQLITE_OK; i++){
144161     char *zSql = sqlite3_mprintf(azSql[i], zDb, zPrefix);
144162     if( zSql ){
144163       rc = sqlite3_prepare_v2(db, zSql, -1, appStmt[i], 0); 
144164     }else{
144165       rc = SQLITE_NOMEM;
144166     }
144167     sqlite3_free(zSql);
144168   }
144169 
144170   return rc;
144171 }
144172 
144173 /*
144174 ** The second argument to this function contains the text of an SQL statement
144175 ** that returns a single integer value. The statement is compiled and executed
144176 ** using database connection db. If successful, the integer value returned
144177 ** is written to *piVal and SQLITE_OK returned. Otherwise, an SQLite error
144178 ** code is returned and the value of *piVal after returning is not defined.
144179 */
144180 static int getIntFromStmt(sqlite3 *db, const char *zSql, int *piVal){
144181   int rc = SQLITE_NOMEM;
144182   if( zSql ){
144183     sqlite3_stmt *pStmt = 0;
144184     rc = sqlite3_prepare_v2(db, zSql, -1, &pStmt, 0);
144185     if( rc==SQLITE_OK ){
144186       if( SQLITE_ROW==sqlite3_step(pStmt) ){
144187         *piVal = sqlite3_column_int(pStmt, 0);
144188       }
144189       rc = sqlite3_finalize(pStmt);
144190     }
144191   }
144192   return rc;
144193 }
144194 
144195 /*
144196 ** This function is called from within the xConnect() or xCreate() method to
144197 ** determine the node-size used by the rtree table being created or connected
144198 ** to. If successful, pRtree->iNodeSize is populated and SQLITE_OK returned.
144199 ** Otherwise, an SQLite error code is returned.
144200 **
144201 ** If this function is being called as part of an xConnect(), then the rtree
144202 ** table already exists. In this case the node-size is determined by inspecting
144203 ** the root node of the tree.
144204 **
144205 ** Otherwise, for an xCreate(), use 64 bytes less than the database page-size. 
144206 ** This ensures that each node is stored on a single database page. If the 
144207 ** database page-size is so large that more than RTREE_MAXCELLS entries 
144208 ** would fit in a single node, use a smaller node-size.
144209 */
144210 static int getNodeSize(
144211   sqlite3 *db,                    /* Database handle */
144212   Rtree *pRtree,                  /* Rtree handle */
144213   int isCreate,                   /* True for xCreate, false for xConnect */
144214   char **pzErr                    /* OUT: Error message, if any */
144215 ){
144216   int rc;
144217   char *zSql;
144218   if( isCreate ){
144219     int iPageSize = 0;
144220     zSql = sqlite3_mprintf("PRAGMA %Q.page_size", pRtree->zDb);
144221     rc = getIntFromStmt(db, zSql, &iPageSize);
144222     if( rc==SQLITE_OK ){
144223       pRtree->iNodeSize = iPageSize-64;
144224       if( (4+pRtree->nBytesPerCell*RTREE_MAXCELLS)<pRtree->iNodeSize ){
144225         pRtree->iNodeSize = 4+pRtree->nBytesPerCell*RTREE_MAXCELLS;
144226       }
144227     }else{
144228       *pzErr = sqlite3_mprintf("%s", sqlite3_errmsg(db));
144229     }
144230   }else{
144231     zSql = sqlite3_mprintf(
144232         "SELECT length(data) FROM '%q'.'%q_node' WHERE nodeno = 1",
144233         pRtree->zDb, pRtree->zName
144234     );
144235     rc = getIntFromStmt(db, zSql, &pRtree->iNodeSize);
144236     if( rc!=SQLITE_OK ){
144237       *pzErr = sqlite3_mprintf("%s", sqlite3_errmsg(db));
144238     }
144239   }
144240 
144241   sqlite3_free(zSql);
144242   return rc;
144243 }
144244 
144245 /* 
144246 ** This function is the implementation of both the xConnect and xCreate
144247 ** methods of the r-tree virtual table.
144248 **
144249 **   argv[0]   -> module name
144250 **   argv[1]   -> database name
144251 **   argv[2]   -> table name
144252 **   argv[...] -> column names...
144253 */
144254 static int rtreeInit(
144255   sqlite3 *db,                        /* Database connection */
144256   void *pAux,                         /* One of the RTREE_COORD_* constants */
144257   int argc, const char *const*argv,   /* Parameters to CREATE TABLE statement */
144258   sqlite3_vtab **ppVtab,              /* OUT: New virtual table */
144259   char **pzErr,                       /* OUT: Error message, if any */
144260   int isCreate                        /* True for xCreate, false for xConnect */
144261 ){
144262   int rc = SQLITE_OK;
144263   Rtree *pRtree;
144264   int nDb;              /* Length of string argv[1] */
144265   int nName;            /* Length of string argv[2] */
144266   int eCoordType = (pAux ? RTREE_COORD_INT32 : RTREE_COORD_REAL32);
144267 
144268   const char *aErrMsg[] = {
144269     0,                                                    /* 0 */
144270     "Wrong number of columns for an rtree table",         /* 1 */
144271     "Too few columns for an rtree table",                 /* 2 */
144272     "Too many columns for an rtree table"                 /* 3 */
144273   };
144274 
144275   int iErr = (argc<6) ? 2 : argc>(RTREE_MAX_DIMENSIONS*2+4) ? 3 : argc%2;
144276   if( aErrMsg[iErr] ){
144277     *pzErr = sqlite3_mprintf("%s", aErrMsg[iErr]);
144278     return SQLITE_ERROR;
144279   }
144280 
144281   sqlite3_vtab_config(db, SQLITE_VTAB_CONSTRAINT_SUPPORT, 1);
144282 
144283   /* Allocate the sqlite3_vtab structure */
144284   nDb = (int)strlen(argv[1]);
144285   nName = (int)strlen(argv[2]);
144286   pRtree = (Rtree *)sqlite3_malloc(sizeof(Rtree)+nDb+nName+2);
144287   if( !pRtree ){
144288     return SQLITE_NOMEM;
144289   }
144290   memset(pRtree, 0, sizeof(Rtree)+nDb+nName+2);
144291   pRtree->nBusy = 1;
144292   pRtree->base.pModule = &rtreeModule;
144293   pRtree->zDb = (char *)&pRtree[1];
144294   pRtree->zName = &pRtree->zDb[nDb+1];
144295   pRtree->nDim = (argc-4)/2;
144296   pRtree->nBytesPerCell = 8 + pRtree->nDim*4*2;
144297   pRtree->eCoordType = eCoordType;
144298   memcpy(pRtree->zDb, argv[1], nDb);
144299   memcpy(pRtree->zName, argv[2], nName);
144300 
144301   /* Figure out the node size to use. */
144302   rc = getNodeSize(db, pRtree, isCreate, pzErr);
144303 
144304   /* Create/Connect to the underlying relational database schema. If
144305   ** that is successful, call sqlite3_declare_vtab() to configure
144306   ** the r-tree table schema.
144307   */
144308   if( rc==SQLITE_OK ){
144309     if( (rc = rtreeSqlInit(pRtree, db, argv[1], argv[2], isCreate)) ){
144310       *pzErr = sqlite3_mprintf("%s", sqlite3_errmsg(db));
144311     }else{
144312       char *zSql = sqlite3_mprintf("CREATE TABLE x(%s", argv[3]);
144313       char *zTmp;
144314       int ii;
144315       for(ii=4; zSql && ii<argc; ii++){
144316         zTmp = zSql;
144317         zSql = sqlite3_mprintf("%s, %s", zTmp, argv[ii]);
144318         sqlite3_free(zTmp);
144319       }
144320       if( zSql ){
144321         zTmp = zSql;
144322         zSql = sqlite3_mprintf("%s);", zTmp);
144323         sqlite3_free(zTmp);
144324       }
144325       if( !zSql ){
144326         rc = SQLITE_NOMEM;
144327       }else if( SQLITE_OK!=(rc = sqlite3_declare_vtab(db, zSql)) ){
144328         *pzErr = sqlite3_mprintf("%s", sqlite3_errmsg(db));
144329       }
144330       sqlite3_free(zSql);
144331     }
144332   }
144333 
144334   if( rc==SQLITE_OK ){
144335     *ppVtab = (sqlite3_vtab *)pRtree;
144336   }else{
144337     rtreeRelease(pRtree);
144338   }
144339   return rc;
144340 }
144341 
144342 
144343 /*
144344 ** Implementation of a scalar function that decodes r-tree nodes to
144345 ** human readable strings. This can be used for debugging and analysis.
144346 **
144347 ** The scalar function takes two arguments, a blob of data containing
144348 ** an r-tree node, and the number of dimensions the r-tree indexes.
144349 ** For a two-dimensional r-tree structure called "rt", to deserialize
144350 ** all nodes, a statement like:
144351 **
144352 **   SELECT rtreenode(2, data) FROM rt_node;
144353 **
144354 ** The human readable string takes the form of a Tcl list with one
144355 ** entry for each cell in the r-tree node. Each entry is itself a
144356 ** list, containing the 8-byte rowid/pageno followed by the 
144357 ** <num-dimension>*2 coordinates.
144358 */
144359 static void rtreenode(sqlite3_context *ctx, int nArg, sqlite3_value **apArg){
144360   char *zText = 0;
144361   RtreeNode node;
144362   Rtree tree;
144363   int ii;
144364 
144365   UNUSED_PARAMETER(nArg);
144366   memset(&node, 0, sizeof(RtreeNode));
144367   memset(&tree, 0, sizeof(Rtree));
144368   tree.nDim = sqlite3_value_int(apArg[0]);
144369   tree.nBytesPerCell = 8 + 8 * tree.nDim;
144370   node.zData = (u8 *)sqlite3_value_blob(apArg[1]);
144371 
144372   for(ii=0; ii<NCELL(&node); ii++){
144373     char zCell[512];
144374     int nCell = 0;
144375     RtreeCell cell;
144376     int jj;
144377 
144378     nodeGetCell(&tree, &node, ii, &cell);
144379     sqlite3_snprintf(512-nCell,&zCell[nCell],"%lld", cell.iRowid);
144380     nCell = (int)strlen(zCell);
144381     for(jj=0; jj<tree.nDim*2; jj++){
144382 #ifndef SQLITE_RTREE_INT_ONLY
144383       sqlite3_snprintf(512-nCell,&zCell[nCell], " %f",
144384                        (double)cell.aCoord[jj].f);
144385 #else
144386       sqlite3_snprintf(512-nCell,&zCell[nCell], " %d",
144387                        cell.aCoord[jj].i);
144388 #endif
144389       nCell = (int)strlen(zCell);
144390     }
144391 
144392     if( zText ){
144393       char *zTextNew = sqlite3_mprintf("%s {%s}", zText, zCell);
144394       sqlite3_free(zText);
144395       zText = zTextNew;
144396     }else{
144397       zText = sqlite3_mprintf("{%s}", zCell);
144398     }
144399   }
144400   
144401   sqlite3_result_text(ctx, zText, -1, sqlite3_free);
144402 }
144403 
144404 static void rtreedepth(sqlite3_context *ctx, int nArg, sqlite3_value **apArg){
144405   UNUSED_PARAMETER(nArg);
144406   if( sqlite3_value_type(apArg[0])!=SQLITE_BLOB 
144407    || sqlite3_value_bytes(apArg[0])<2
144408   ){
144409     sqlite3_result_error(ctx, "Invalid argument to rtreedepth()", -1); 
144410   }else{
144411     u8 *zBlob = (u8 *)sqlite3_value_blob(apArg[0]);
144412     sqlite3_result_int(ctx, readInt16(zBlob));
144413   }
144414 }
144415 
144416 /*
144417 ** Register the r-tree module with database handle db. This creates the
144418 ** virtual table module "rtree" and the debugging/analysis scalar 
144419 ** function "rtreenode".
144420 */
144421 SQLITE_PRIVATE int sqlite3RtreeInit(sqlite3 *db){
144422   const int utf8 = SQLITE_UTF8;
144423   int rc;
144424 
144425   rc = sqlite3_create_function(db, "rtreenode", 2, utf8, 0, rtreenode, 0, 0);
144426   if( rc==SQLITE_OK ){
144427     rc = sqlite3_create_function(db, "rtreedepth", 1, utf8, 0,rtreedepth, 0, 0);
144428   }
144429   if( rc==SQLITE_OK ){
144430 #ifdef SQLITE_RTREE_INT_ONLY
144431     void *c = (void *)RTREE_COORD_INT32;
144432 #else
144433     void *c = (void *)RTREE_COORD_REAL32;
144434 #endif
144435     rc = sqlite3_create_module_v2(db, "rtree", &rtreeModule, c, 0);
144436   }
144437   if( rc==SQLITE_OK ){
144438     void *c = (void *)RTREE_COORD_INT32;
144439     rc = sqlite3_create_module_v2(db, "rtree_i32", &rtreeModule, c, 0);
144440   }
144441 
144442   return rc;
144443 }
144444 
144445 /*
144446 ** A version of sqlite3_free() that can be used as a callback. This is used
144447 ** in two places - as the destructor for the blob value returned by the
144448 ** invocation of a geometry function, and as the destructor for the geometry
144449 ** functions themselves.
144450 */
144451 static void doSqlite3Free(void *p){
144452   sqlite3_free(p);
144453 }
144454 
144455 /*
144456 ** Each call to sqlite3_rtree_geometry_callback() creates an ordinary SQLite
144457 ** scalar user function. This C function is the callback used for all such
144458 ** registered SQL functions.
144459 **
144460 ** The scalar user functions return a blob that is interpreted by r-tree
144461 ** table MATCH operators.
144462 */
144463 static void geomCallback(sqlite3_context *ctx, int nArg, sqlite3_value **aArg){
144464   RtreeGeomCallback *pGeomCtx = (RtreeGeomCallback *)sqlite3_user_data(ctx);
144465   RtreeMatchArg *pBlob;
144466   int nBlob;
144467 
144468   nBlob = sizeof(RtreeMatchArg) + (nArg-1)*sizeof(RtreeDValue);
144469   pBlob = (RtreeMatchArg *)sqlite3_malloc(nBlob);
144470   if( !pBlob ){
144471     sqlite3_result_error_nomem(ctx);
144472   }else{
144473     int i;
144474     pBlob->magic = RTREE_GEOMETRY_MAGIC;
144475     pBlob->xGeom = pGeomCtx->xGeom;
144476     pBlob->pContext = pGeomCtx->pContext;
144477     pBlob->nParam = nArg;
144478     for(i=0; i<nArg; i++){
144479 #ifdef SQLITE_RTREE_INT_ONLY
144480       pBlob->aParam[i] = sqlite3_value_int64(aArg[i]);
144481 #else
144482       pBlob->aParam[i] = sqlite3_value_double(aArg[i]);
144483 #endif
144484     }
144485     sqlite3_result_blob(ctx, pBlob, nBlob, doSqlite3Free);
144486   }
144487 }
144488 
144489 /*
144490 ** Register a new geometry function for use with the r-tree MATCH operator.
144491 */
144492 SQLITE_API int sqlite3_rtree_geometry_callback(
144493   sqlite3 *db,
144494   const char *zGeom,
144495   int (*xGeom)(sqlite3_rtree_geometry *, int, RtreeDValue *, int *),
144496   void *pContext
144497 ){
144498   RtreeGeomCallback *pGeomCtx;      /* Context object for new user-function */
144499 
144500   /* Allocate and populate the context object. */
144501   pGeomCtx = (RtreeGeomCallback *)sqlite3_malloc(sizeof(RtreeGeomCallback));
144502   if( !pGeomCtx ) return SQLITE_NOMEM;
144503   pGeomCtx->xGeom = xGeom;
144504   pGeomCtx->pContext = pContext;
144505 
144506   /* Create the new user-function. Register a destructor function to delete
144507   ** the context object when it is no longer required.  */
144508   return sqlite3_create_function_v2(db, zGeom, -1, SQLITE_ANY, 
144509       (void *)pGeomCtx, geomCallback, 0, 0, doSqlite3Free
144510   );
144511 }
144512 
144513 #if !SQLITE_CORE
144514 #ifdef _WIN32
144515 __declspec(dllexport)
144516 #endif
144517 SQLITE_API int sqlite3_rtree_init(
144518   sqlite3 *db,
144519   char **pzErrMsg,
144520   const sqlite3_api_routines *pApi
144521 ){
144522   SQLITE_EXTENSION_INIT2(pApi)
144523   return sqlite3RtreeInit(db);
144524 }
144525 #endif
144526 
144527 #endif
144528 
144529 /************** End of rtree.c ***********************************************/
144530 /************** Begin file icu.c *********************************************/
144531 /*
144532 ** 2007 May 6
144533 **
144534 ** The author disclaims copyright to this source code.  In place of
144535 ** a legal notice, here is a blessing:
144536 **
144537 **    May you do good and not evil.
144538 **    May you find forgiveness for yourself and forgive others.
144539 **    May you share freely, never taking more than you give.
144540 **
144541 *************************************************************************
144542 ** $Id: icu.c,v 1.7 2007/12/13 21:54:11 drh Exp $
144543 **
144544 ** This file implements an integration between the ICU library 
144545 ** ("International Components for Unicode", an open-source library 
144546 ** for handling unicode data) and SQLite. The integration uses 
144547 ** ICU to provide the following to SQLite:
144548 **
144549 **   * An implementation of the SQL regexp() function (and hence REGEXP
144550 **     operator) using the ICU uregex_XX() APIs.
144551 **
144552 **   * Implementations of the SQL scalar upper() and lower() functions
144553 **     for case mapping.
144554 **
144555 **   * Integration of ICU and SQLite collation sequences.
144556 **
144557 **   * An implementation of the LIKE operator that uses ICU to 
144558 **     provide case-independent matching.
144559 */
144560 
144561 #if !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_ICU)
144562 
144563 /* Include ICU headers */
144564 #include <unicode/utypes.h>
144565 #include <unicode/uregex.h>
144566 #include <unicode/ustring.h>
144567 #include <unicode/ucol.h>
144568 
144569 /* #include <assert.h> */
144570 
144571 #ifndef SQLITE_CORE
144572   SQLITE_EXTENSION_INIT1
144573 #else
144574 #endif
144575 
144576 /*
144577 ** Maximum length (in bytes) of the pattern in a LIKE or GLOB
144578 ** operator.
144579 */
144580 #ifndef SQLITE_MAX_LIKE_PATTERN_LENGTH
144581 # define SQLITE_MAX_LIKE_PATTERN_LENGTH 50000
144582 #endif
144583 
144584 /*
144585 ** Version of sqlite3_free() that is always a function, never a macro.
144586 */
144587 static void xFree(void *p){
144588   sqlite3_free(p);
144589 }
144590 
144591 /*
144592 ** Compare two UTF-8 strings for equality where the first string is
144593 ** a "LIKE" expression. Return true (1) if they are the same and 
144594 ** false (0) if they are different.
144595 */
144596 static int icuLikeCompare(
144597   const uint8_t *zPattern,   /* LIKE pattern */
144598   const uint8_t *zString,    /* The UTF-8 string to compare against */
144599   const UChar32 uEsc         /* The escape character */
144600 ){
144601   static const int MATCH_ONE = (UChar32)'_';
144602   static const int MATCH_ALL = (UChar32)'%';
144603 
144604   int iPattern = 0;       /* Current byte index in zPattern */
144605   int iString = 0;        /* Current byte index in zString */
144606 
144607   int prevEscape = 0;     /* True if the previous character was uEsc */
144608 
144609   while( zPattern[iPattern]!=0 ){
144610 
144611     /* Read (and consume) the next character from the input pattern. */
144612     UChar32 uPattern;
144613     U8_NEXT_UNSAFE(zPattern, iPattern, uPattern);
144614     assert(uPattern!=0);
144615 
144616     /* There are now 4 possibilities:
144617     **
144618     **     1. uPattern is an unescaped match-all character "%",
144619     **     2. uPattern is an unescaped match-one character "_",
144620     **     3. uPattern is an unescaped escape character, or
144621     **     4. uPattern is to be handled as an ordinary character
144622     */
144623     if( !prevEscape && uPattern==MATCH_ALL ){
144624       /* Case 1. */
144625       uint8_t c;
144626 
144627       /* Skip any MATCH_ALL or MATCH_ONE characters that follow a
144628       ** MATCH_ALL. For each MATCH_ONE, skip one character in the 
144629       ** test string.
144630       */
144631       while( (c=zPattern[iPattern]) == MATCH_ALL || c == MATCH_ONE ){
144632         if( c==MATCH_ONE ){
144633           if( zString[iString]==0 ) return 0;
144634           U8_FWD_1_UNSAFE(zString, iString);
144635         }
144636         iPattern++;
144637       }
144638 
144639       if( zPattern[iPattern]==0 ) return 1;
144640 
144641       while( zString[iString] ){
144642         if( icuLikeCompare(&zPattern[iPattern], &zString[iString], uEsc) ){
144643           return 1;
144644         }
144645         U8_FWD_1_UNSAFE(zString, iString);
144646       }
144647       return 0;
144648 
144649     }else if( !prevEscape && uPattern==MATCH_ONE ){
144650       /* Case 2. */
144651       if( zString[iString]==0 ) return 0;
144652       U8_FWD_1_UNSAFE(zString, iString);
144653 
144654     }else if( !prevEscape && uPattern==uEsc){
144655       /* Case 3. */
144656       prevEscape = 1;
144657 
144658     }else{
144659       /* Case 4. */
144660       UChar32 uString;
144661       U8_NEXT_UNSAFE(zString, iString, uString);
144662       uString = u_foldCase(uString, U_FOLD_CASE_DEFAULT);
144663       uPattern = u_foldCase(uPattern, U_FOLD_CASE_DEFAULT);
144664       if( uString!=uPattern ){
144665         return 0;
144666       }
144667       prevEscape = 0;
144668     }
144669   }
144670 
144671   return zString[iString]==0;
144672 }
144673 
144674 /*
144675 ** Implementation of the like() SQL function.  This function implements
144676 ** the build-in LIKE operator.  The first argument to the function is the
144677 ** pattern and the second argument is the string.  So, the SQL statements:
144678 **
144679 **       A LIKE B
144680 **
144681 ** is implemented as like(B, A). If there is an escape character E, 
144682 **
144683 **       A LIKE B ESCAPE E
144684 **
144685 ** is mapped to like(B, A, E).
144686 */
144687 static void icuLikeFunc(
144688   sqlite3_context *context, 
144689   int argc, 
144690   sqlite3_value **argv
144691 ){
144692   const unsigned char *zA = sqlite3_value_text(argv[0]);
144693   const unsigned char *zB = sqlite3_value_text(argv[1]);
144694   UChar32 uEsc = 0;
144695 
144696   /* Limit the length of the LIKE or GLOB pattern to avoid problems
144697   ** of deep recursion and N*N behavior in patternCompare().
144698   */
144699   if( sqlite3_value_bytes(argv[0])>SQLITE_MAX_LIKE_PATTERN_LENGTH ){
144700     sqlite3_result_error(context, "LIKE or GLOB pattern too complex", -1);
144701     return;
144702   }
144703 
144704 
144705   if( argc==3 ){
144706     /* The escape character string must consist of a single UTF-8 character.
144707     ** Otherwise, return an error.
144708     */
144709     int nE= sqlite3_value_bytes(argv[2]);
144710     const unsigned char *zE = sqlite3_value_text(argv[2]);
144711     int i = 0;
144712     if( zE==0 ) return;
144713     U8_NEXT(zE, i, nE, uEsc);
144714     if( i!=nE){
144715       sqlite3_result_error(context, 
144716           "ESCAPE expression must be a single character", -1);
144717       return;
144718     }
144719   }
144720 
144721   if( zA && zB ){
144722     sqlite3_result_int(context, icuLikeCompare(zA, zB, uEsc));
144723   }
144724 }
144725 
144726 /*
144727 ** This function is called when an ICU function called from within
144728 ** the implementation of an SQL scalar function returns an error.
144729 **
144730 ** The scalar function context passed as the first argument is 
144731 ** loaded with an error message based on the following two args.
144732 */
144733 static void icuFunctionError(
144734   sqlite3_context *pCtx,       /* SQLite scalar function context */
144735   const char *zName,           /* Name of ICU function that failed */
144736   UErrorCode e                 /* Error code returned by ICU function */
144737 ){
144738   char zBuf[128];
144739   sqlite3_snprintf(128, zBuf, "ICU error: %s(): %s", zName, u_errorName(e));
144740   zBuf[127] = '\0';
144741   sqlite3_result_error(pCtx, zBuf, -1);
144742 }
144743 
144744 /*
144745 ** Function to delete compiled regexp objects. Registered as
144746 ** a destructor function with sqlite3_set_auxdata().
144747 */
144748 static void icuRegexpDelete(void *p){
144749   URegularExpression *pExpr = (URegularExpression *)p;
144750   uregex_close(pExpr);
144751 }
144752 
144753 /*
144754 ** Implementation of SQLite REGEXP operator. This scalar function takes
144755 ** two arguments. The first is a regular expression pattern to compile
144756 ** the second is a string to match against that pattern. If either 
144757 ** argument is an SQL NULL, then NULL Is returned. Otherwise, the result
144758 ** is 1 if the string matches the pattern, or 0 otherwise.
144759 **
144760 ** SQLite maps the regexp() function to the regexp() operator such
144761 ** that the following two are equivalent:
144762 **
144763 **     zString REGEXP zPattern
144764 **     regexp(zPattern, zString)
144765 **
144766 ** Uses the following ICU regexp APIs:
144767 **
144768 **     uregex_open()
144769 **     uregex_matches()
144770 **     uregex_close()
144771 */
144772 static void icuRegexpFunc(sqlite3_context *p, int nArg, sqlite3_value **apArg){
144773   UErrorCode status = U_ZERO_ERROR;
144774   URegularExpression *pExpr;
144775   UBool res;
144776   const UChar *zString = sqlite3_value_text16(apArg[1]);
144777 
144778   (void)nArg;  /* Unused parameter */
144779 
144780   /* If the left hand side of the regexp operator is NULL, 
144781   ** then the result is also NULL. 
144782   */
144783   if( !zString ){
144784     return;
144785   }
144786 
144787   pExpr = sqlite3_get_auxdata(p, 0);
144788   if( !pExpr ){
144789     const UChar *zPattern = sqlite3_value_text16(apArg[0]);
144790     if( !zPattern ){
144791       return;
144792     }
144793     pExpr = uregex_open(zPattern, -1, 0, 0, &status);
144794 
144795     if( U_SUCCESS(status) ){
144796       sqlite3_set_auxdata(p, 0, pExpr, icuRegexpDelete);
144797     }else{
144798       assert(!pExpr);
144799       icuFunctionError(p, "uregex_open", status);
144800       return;
144801     }
144802   }
144803 
144804   /* Configure the text that the regular expression operates on. */
144805   uregex_setText(pExpr, zString, -1, &status);
144806   if( !U_SUCCESS(status) ){
144807     icuFunctionError(p, "uregex_setText", status);
144808     return;
144809   }
144810 
144811   /* Attempt the match */
144812   res = uregex_matches(pExpr, 0, &status);
144813   if( !U_SUCCESS(status) ){
144814     icuFunctionError(p, "uregex_matches", status);
144815     return;
144816   }
144817 
144818   /* Set the text that the regular expression operates on to a NULL
144819   ** pointer. This is not really necessary, but it is tidier than 
144820   ** leaving the regular expression object configured with an invalid
144821   ** pointer after this function returns.
144822   */
144823   uregex_setText(pExpr, 0, 0, &status);
144824 
144825   /* Return 1 or 0. */
144826   sqlite3_result_int(p, res ? 1 : 0);
144827 }
144828 
144829 /*
144830 ** Implementations of scalar functions for case mapping - upper() and 
144831 ** lower(). Function upper() converts its input to upper-case (ABC).
144832 ** Function lower() converts to lower-case (abc).
144833 **
144834 ** ICU provides two types of case mapping, "general" case mapping and
144835 ** "language specific". Refer to ICU documentation for the differences
144836 ** between the two.
144837 **
144838 ** To utilise "general" case mapping, the upper() or lower() scalar 
144839 ** functions are invoked with one argument:
144840 **
144841 **     upper('ABC') -> 'abc'
144842 **     lower('abc') -> 'ABC'
144843 **
144844 ** To access ICU "language specific" case mapping, upper() or lower()
144845 ** should be invoked with two arguments. The second argument is the name
144846 ** of the locale to use. Passing an empty string ("") or SQL NULL value
144847 ** as the second argument is the same as invoking the 1 argument version
144848 ** of upper() or lower().
144849 **
144850 **     lower('I', 'en_us') -> 'i'
144851 **     lower('I', 'tr_tr') -> 'ı' (small dotless i)
144852 **
144853 ** http://www.icu-project.org/userguide/posix.html#case_mappings
144854 */
144855 static void icuCaseFunc16(sqlite3_context *p, int nArg, sqlite3_value **apArg){
144856   const UChar *zInput;
144857   UChar *zOutput;
144858   int nInput;
144859   int nOutput;
144860 
144861   UErrorCode status = U_ZERO_ERROR;
144862   const char *zLocale = 0;
144863 
144864   assert(nArg==1 || nArg==2);
144865   if( nArg==2 ){
144866     zLocale = (const char *)sqlite3_value_text(apArg[1]);
144867   }
144868 
144869   zInput = sqlite3_value_text16(apArg[0]);
144870   if( !zInput ){
144871     return;
144872   }
144873   nInput = sqlite3_value_bytes16(apArg[0]);
144874 
144875   nOutput = nInput * 2 + 2;
144876   zOutput = sqlite3_malloc(nOutput);
144877   if( !zOutput ){
144878     return;
144879   }
144880 
144881   if( sqlite3_user_data(p) ){
144882     u_strToUpper(zOutput, nOutput/2, zInput, nInput/2, zLocale, &status);
144883   }else{
144884     u_strToLower(zOutput, nOutput/2, zInput, nInput/2, zLocale, &status);
144885   }
144886 
144887   if( !U_SUCCESS(status) ){
144888     icuFunctionError(p, "u_strToLower()/u_strToUpper", status);
144889     return;
144890   }
144891 
144892   sqlite3_result_text16(p, zOutput, -1, xFree);
144893 }
144894 
144895 /*
144896 ** Collation sequence destructor function. The pCtx argument points to
144897 ** a UCollator structure previously allocated using ucol_open().
144898 */
144899 static void icuCollationDel(void *pCtx){
144900   UCollator *p = (UCollator *)pCtx;
144901   ucol_close(p);
144902 }
144903 
144904 /*
144905 ** Collation sequence comparison function. The pCtx argument points to
144906 ** a UCollator structure previously allocated using ucol_open().
144907 */
144908 static int icuCollationColl(
144909   void *pCtx,
144910   int nLeft,
144911   const void *zLeft,
144912   int nRight,
144913   const void *zRight
144914 ){
144915   UCollationResult res;
144916   UCollator *p = (UCollator *)pCtx;
144917   res = ucol_strcoll(p, (UChar *)zLeft, nLeft/2, (UChar *)zRight, nRight/2);
144918   switch( res ){
144919     case UCOL_LESS:    return -1;
144920     case UCOL_GREATER: return +1;
144921     case UCOL_EQUAL:   return 0;
144922   }
144923   assert(!"Unexpected return value from ucol_strcoll()");
144924   return 0;
144925 }
144926 
144927 /*
144928 ** Implementation of the scalar function icu_load_collation().
144929 **
144930 ** This scalar function is used to add ICU collation based collation 
144931 ** types to an SQLite database connection. It is intended to be called
144932 ** as follows:
144933 **
144934 **     SELECT icu_load_collation(<locale>, <collation-name>);
144935 **
144936 ** Where <locale> is a string containing an ICU locale identifier (i.e.
144937 ** "en_AU", "tr_TR" etc.) and <collation-name> is the name of the
144938 ** collation sequence to create.
144939 */
144940 static void icuLoadCollation(
144941   sqlite3_context *p, 
144942   int nArg, 
144943   sqlite3_value **apArg
144944 ){
144945   sqlite3 *db = (sqlite3 *)sqlite3_user_data(p);
144946   UErrorCode status = U_ZERO_ERROR;
144947   const char *zLocale;      /* Locale identifier - (eg. "jp_JP") */
144948   const char *zName;        /* SQL Collation sequence name (eg. "japanese") */
144949   UCollator *pUCollator;    /* ICU library collation object */
144950   int rc;                   /* Return code from sqlite3_create_collation_x() */
144951 
144952   assert(nArg==2);
144953   zLocale = (const char *)sqlite3_value_text(apArg[0]);
144954   zName = (const char *)sqlite3_value_text(apArg[1]);
144955 
144956   if( !zLocale || !zName ){
144957     return;
144958   }
144959 
144960   pUCollator = ucol_open(zLocale, &status);
144961   if( !U_SUCCESS(status) ){
144962     icuFunctionError(p, "ucol_open", status);
144963     return;
144964   }
144965   assert(p);
144966 
144967   rc = sqlite3_create_collation_v2(db, zName, SQLITE_UTF16, (void *)pUCollator, 
144968       icuCollationColl, icuCollationDel
144969   );
144970   if( rc!=SQLITE_OK ){
144971     ucol_close(pUCollator);
144972     sqlite3_result_error(p, "Error registering collation function", -1);
144973   }
144974 }
144975 
144976 /*
144977 ** Register the ICU extension functions with database db.
144978 */
144979 SQLITE_PRIVATE int sqlite3IcuInit(sqlite3 *db){
144980   struct IcuScalar {
144981     const char *zName;                        /* Function name */
144982     int nArg;                                 /* Number of arguments */
144983     int enc;                                  /* Optimal text encoding */
144984     void *pContext;                           /* sqlite3_user_data() context */
144985     void (*xFunc)(sqlite3_context*,int,sqlite3_value**);
144986   } scalars[] = {
144987     {"regexp", 2, SQLITE_ANY,          0, icuRegexpFunc},
144988 
144989     {"lower",  1, SQLITE_UTF16,        0, icuCaseFunc16},
144990     {"lower",  2, SQLITE_UTF16,        0, icuCaseFunc16},
144991     {"upper",  1, SQLITE_UTF16, (void*)1, icuCaseFunc16},
144992     {"upper",  2, SQLITE_UTF16, (void*)1, icuCaseFunc16},
144993 
144994     {"lower",  1, SQLITE_UTF8,         0, icuCaseFunc16},
144995     {"lower",  2, SQLITE_UTF8,         0, icuCaseFunc16},
144996     {"upper",  1, SQLITE_UTF8,  (void*)1, icuCaseFunc16},
144997     {"upper",  2, SQLITE_UTF8,  (void*)1, icuCaseFunc16},
144998 
144999     {"like",   2, SQLITE_UTF8,         0, icuLikeFunc},
145000     {"like",   3, SQLITE_UTF8,         0, icuLikeFunc},
145001 
145002     {"icu_load_collation",  2, SQLITE_UTF8, (void*)db, icuLoadCollation},
145003   };
145004 
145005   int rc = SQLITE_OK;
145006   int i;
145007 
145008   for(i=0; rc==SQLITE_OK && i<(int)(sizeof(scalars)/sizeof(scalars[0])); i++){
145009     struct IcuScalar *p = &scalars[i];
145010     rc = sqlite3_create_function(
145011         db, p->zName, p->nArg, p->enc, p->pContext, p->xFunc, 0, 0
145012     );
145013   }
145014 
145015   return rc;
145016 }
145017 
145018 #if !SQLITE_CORE
145019 #ifdef _WIN32
145020 __declspec(dllexport)
145021 #endif
145022 SQLITE_API int sqlite3_icu_init(
145023   sqlite3 *db, 
145024   char **pzErrMsg,
145025   const sqlite3_api_routines *pApi
145026 ){
145027   SQLITE_EXTENSION_INIT2(pApi)
145028   return sqlite3IcuInit(db);
145029 }
145030 #endif
145031 
145032 #endif
145033 
145034 /************** End of icu.c *************************************************/
145035 /************** Begin file fts3_icu.c ****************************************/
145036 /*
145037 ** 2007 June 22
145038 **
145039 ** The author disclaims copyright to this source code.  In place of
145040 ** a legal notice, here is a blessing:
145041 **
145042 **    May you do good and not evil.
145043 **    May you find forgiveness for yourself and forgive others.
145044 **    May you share freely, never taking more than you give.
145045 **
145046 *************************************************************************
145047 ** This file implements a tokenizer for fts3 based on the ICU library.
145048 */
145049 #if !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_FTS3)
145050 #ifdef SQLITE_ENABLE_ICU
145051 
145052 /* #include <assert.h> */
145053 /* #include <string.h> */
145054 
145055 #include <unicode/ubrk.h>
145056 /* #include <unicode/ucol.h> */
145057 /* #include <unicode/ustring.h> */
145058 #include <unicode/utf16.h>
145059 
145060 typedef struct IcuTokenizer IcuTokenizer;
145061 typedef struct IcuCursor IcuCursor;
145062 
145063 struct IcuTokenizer {
145064   sqlite3_tokenizer base;
145065   char *zLocale;
145066 };
145067 
145068 struct IcuCursor {
145069   sqlite3_tokenizer_cursor base;
145070 
145071   UBreakIterator *pIter;      /* ICU break-iterator object */
145072   int nChar;                  /* Number of UChar elements in pInput */
145073   UChar *aChar;               /* Copy of input using utf-16 encoding */
145074   int *aOffset;               /* Offsets of each character in utf-8 input */
145075 
145076   int nBuffer;
145077   char *zBuffer;
145078 
145079   int iToken;
145080 };
145081 
145082 /*
145083 ** Create a new tokenizer instance.
145084 */
145085 static int icuCreate(
145086   int argc,                            /* Number of entries in argv[] */
145087   const char * const *argv,            /* Tokenizer creation arguments */
145088   sqlite3_tokenizer **ppTokenizer      /* OUT: Created tokenizer */
145089 ){
145090   IcuTokenizer *p;
145091   int n = 0;
145092 
145093   if( argc>0 ){
145094     n = strlen(argv[0])+1;
145095   }
145096   p = (IcuTokenizer *)sqlite3_malloc(sizeof(IcuTokenizer)+n);
145097   if( !p ){
145098     return SQLITE_NOMEM;
145099   }
145100   memset(p, 0, sizeof(IcuTokenizer));
145101 
145102   if( n ){
145103     p->zLocale = (char *)&p[1];
145104     memcpy(p->zLocale, argv[0], n);
145105   }
145106 
145107   *ppTokenizer = (sqlite3_tokenizer *)p;
145108 
145109   return SQLITE_OK;
145110 }
145111 
145112 /*
145113 ** Destroy a tokenizer
145114 */
145115 static int icuDestroy(sqlite3_tokenizer *pTokenizer){
145116   IcuTokenizer *p = (IcuTokenizer *)pTokenizer;
145117   sqlite3_free(p);
145118   return SQLITE_OK;
145119 }
145120 
145121 /*
145122 ** Prepare to begin tokenizing a particular string.  The input
145123 ** string to be tokenized is pInput[0..nBytes-1].  A cursor
145124 ** used to incrementally tokenize this string is returned in 
145125 ** *ppCursor.
145126 */
145127 static int icuOpen(
145128   sqlite3_tokenizer *pTokenizer,         /* The tokenizer */
145129   const char *zInput,                    /* Input string */
145130   int nInput,                            /* Length of zInput in bytes */
145131   sqlite3_tokenizer_cursor **ppCursor    /* OUT: Tokenization cursor */
145132 ){
145133   IcuTokenizer *p = (IcuTokenizer *)pTokenizer;
145134   IcuCursor *pCsr;
145135 
145136   const int32_t opt = U_FOLD_CASE_DEFAULT;
145137   UErrorCode status = U_ZERO_ERROR;
145138   int nChar;
145139 
145140   UChar32 c;
145141   int iInput = 0;
145142   int iOut = 0;
145143 
145144   *ppCursor = 0;
145145 
145146   if( zInput==0 ){
145147     nInput = 0;
145148     zInput = "";
145149   }else if( nInput<0 ){
145150     nInput = strlen(zInput);
145151   }
145152   nChar = nInput+1;
145153   pCsr = (IcuCursor *)sqlite3_malloc(
145154       sizeof(IcuCursor) +                /* IcuCursor */
145155       ((nChar+3)&~3) * sizeof(UChar) +   /* IcuCursor.aChar[] */
145156       (nChar+1) * sizeof(int)            /* IcuCursor.aOffset[] */
145157   );
145158   if( !pCsr ){
145159     return SQLITE_NOMEM;
145160   }
145161   memset(pCsr, 0, sizeof(IcuCursor));
145162   pCsr->aChar = (UChar *)&pCsr[1];
145163   pCsr->aOffset = (int *)&pCsr->aChar[(nChar+3)&~3];
145164 
145165   pCsr->aOffset[iOut] = iInput;
145166   U8_NEXT(zInput, iInput, nInput, c); 
145167   while( c>0 ){
145168     int isError = 0;
145169     c = u_foldCase(c, opt);
145170     U16_APPEND(pCsr->aChar, iOut, nChar, c, isError);
145171     if( isError ){
145172       sqlite3_free(pCsr);
145173       return SQLITE_ERROR;
145174     }
145175     pCsr->aOffset[iOut] = iInput;
145176 
145177     if( iInput<nInput ){
145178       U8_NEXT(zInput, iInput, nInput, c);
145179     }else{
145180       c = 0;
145181     }
145182   }
145183 
145184   pCsr->pIter = ubrk_open(UBRK_WORD, p->zLocale, pCsr->aChar, iOut, &status);
145185   if( !U_SUCCESS(status) ){
145186     sqlite3_free(pCsr);
145187     return SQLITE_ERROR;
145188   }
145189   pCsr->nChar = iOut;
145190 
145191   ubrk_first(pCsr->pIter);
145192   *ppCursor = (sqlite3_tokenizer_cursor *)pCsr;
145193   return SQLITE_OK;
145194 }
145195 
145196 /*
145197 ** Close a tokenization cursor previously opened by a call to icuOpen().
145198 */
145199 static int icuClose(sqlite3_tokenizer_cursor *pCursor){
145200   IcuCursor *pCsr = (IcuCursor *)pCursor;
145201   ubrk_close(pCsr->pIter);
145202   sqlite3_free(pCsr->zBuffer);
145203   sqlite3_free(pCsr);
145204   return SQLITE_OK;
145205 }
145206 
145207 /*
145208 ** Extract the next token from a tokenization cursor.
145209 */
145210 static int icuNext(
145211   sqlite3_tokenizer_cursor *pCursor,  /* Cursor returned by simpleOpen */
145212   const char **ppToken,               /* OUT: *ppToken is the token text */
145213   int *pnBytes,                       /* OUT: Number of bytes in token */
145214   int *piStartOffset,                 /* OUT: Starting offset of token */
145215   int *piEndOffset,                   /* OUT: Ending offset of token */
145216   int *piPosition                     /* OUT: Position integer of token */
145217 ){
145218   IcuCursor *pCsr = (IcuCursor *)pCursor;
145219 
145220   int iStart = 0;
145221   int iEnd = 0;
145222   int nByte = 0;
145223 
145224   while( iStart==iEnd ){
145225     UChar32 c;
145226 
145227     iStart = ubrk_current(pCsr->pIter);
145228     iEnd = ubrk_next(pCsr->pIter);
145229     if( iEnd==UBRK_DONE ){
145230       return SQLITE_DONE;
145231     }
145232 
145233     while( iStart<iEnd ){
145234       int iWhite = iStart;
145235       U16_NEXT(pCsr->aChar, iWhite, pCsr->nChar, c);
145236       if( u_isspace(c) ){
145237         iStart = iWhite;
145238       }else{
145239         break;
145240       }
145241     }
145242     assert(iStart<=iEnd);
145243   }
145244 
145245   do {
145246     UErrorCode status = U_ZERO_ERROR;
145247     if( nByte ){
145248       char *zNew = sqlite3_realloc(pCsr->zBuffer, nByte);
145249       if( !zNew ){
145250         return SQLITE_NOMEM;
145251       }
145252       pCsr->zBuffer = zNew;
145253       pCsr->nBuffer = nByte;
145254     }
145255 
145256     u_strToUTF8(
145257         pCsr->zBuffer, pCsr->nBuffer, &nByte,    /* Output vars */
145258         &pCsr->aChar[iStart], iEnd-iStart,       /* Input vars */
145259         &status                                  /* Output success/failure */
145260     );
145261   } while( nByte>pCsr->nBuffer );
145262 
145263   *ppToken = pCsr->zBuffer;
145264   *pnBytes = nByte;
145265   *piStartOffset = pCsr->aOffset[iStart];
145266   *piEndOffset = pCsr->aOffset[iEnd];
145267   *piPosition = pCsr->iToken++;
145268 
145269   return SQLITE_OK;
145270 }
145271 
145272 /*
145273 ** The set of routines that implement the simple tokenizer
145274 */
145275 static const sqlite3_tokenizer_module icuTokenizerModule = {
145276   0,                           /* iVersion */
145277   icuCreate,                   /* xCreate  */
145278   icuDestroy,                  /* xCreate  */
145279   icuOpen,                     /* xOpen    */
145280   icuClose,                    /* xClose   */
145281   icuNext,                     /* xNext    */
145282 };
145283 
145284 /*
145285 ** Set *ppModule to point at the implementation of the ICU tokenizer.
145286 */
145287 SQLITE_PRIVATE void sqlite3Fts3IcuTokenizerModule(
145288   sqlite3_tokenizer_module const**ppModule
145289 ){
145290   *ppModule = &icuTokenizerModule;
145291 }
145292 
145293 #endif /* defined(SQLITE_ENABLE_ICU) */
145294 #endif /* !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_FTS3) */
145295 
145296 /************** End of fts3_icu.c ********************************************/