1 /*

     2 ** 2001 September 15

     3 **

     4 ** The author disclaims copyright to this source code.  In place of

     5 ** a legal notice, here is a blessing:

     6 **

     7 **    May you do good and not evil.

     8 **    May you find forgiveness for yourself and forgive others.

     9 **    May you share freely, never taking more than you give.

    10 **

    11 *************************************************************************

    12 ** Internal interface definitions for SQLite.

    13 **

    14 ** @(#) $Id: sqliteInt.h,v 1.752 2008/08/04 20:13:27 drh Exp $

    15 */

    16 #ifndef _SQLITEINT_H_

    17 #define _SQLITEINT_H_

    18 

    19 /*

    20 ** Include the configuration header output by 'configure' if we're using the

    21 ** autoconf-based build

    22 */

    23 #ifdef _HAVE_SQLITE_CONFIG_H

    24 #include "config.h"

    25 #endif

    26 

    27 #include "sqliteLimit.h"

    28 

    29 /* Disable nuisance warnings on Borland compilers */

    30 #if defined(__BORLANDC__)

    31 #pragma warn -rch /* unreachable code */

    32 #pragma warn -ccc /* Condition is always true or false */

    33 #pragma warn -aus /* Assigned value is never used */

    34 #pragma warn -csu /* Comparing signed and unsigned */

    35 #pragma warn -spa /* Suspicous pointer arithmetic */

    36 #endif

    37 

    38 /* Needed for various definitions... */

    39 #ifndef _GNU_SOURCE

    40 # define _GNU_SOURCE

    41 #endif

    42 

    43 /*

    44 ** Include standard header files as necessary

    45 */

    46 #ifdef HAVE_STDINT_H

    47 #include <stdint.h>

    48 #endif

    49 #ifdef HAVE_INTTYPES_H

    50 #include <inttypes.h>

    51 #endif

    52 

    53 /*

    54 ** A macro used to aid in coverage testing.  When doing coverage

    55 ** testing, the condition inside the argument must be evaluated 

    56 ** both true and false in order to get full branch coverage.

    57 ** This macro can be inserted to ensure adequate test coverage

    58 ** in places where simple condition/decision coverage is inadequate.

    59 */

    60 #ifdef SQLITE_COVERAGE_TEST

    61   void sqlite3Coverage(int);

    62 # define testcase(X)  if( X ){ sqlite3Coverage(__LINE__); }

    63 #else

    64 # define testcase(X)

    65 #endif

    66 

    67 /*

    68 ** The ALWAYS and NEVER macros surround boolean expressions which 

    69 ** are intended to always be true or false, respectively.  Such

    70 ** expressions could be omitted from the code completely.  But they

    71 ** are included in a few cases in order to enhance the resilience

    72 ** of SQLite to unexpected behavior - to make the code "self-healing"

    73 ** or "ductile" rather than being "brittle" and crashing at the first

    74 ** hint of unplanned behavior.

    75 **

    76 ** When doing coverage testing ALWAYS and NEVER are hard-coded to

    77 ** be true and false so that the unreachable code then specify will

    78 ** not be counted as untested code.

    79 */

    80 #ifdef SQLITE_COVERAGE_TEST

    81 # define ALWAYS(X)      (1)

    82 # define NEVER(X)       (0)

    83 #else

    84 # define ALWAYS(X)      (X)

    85 # define NEVER(X)       (X)

    86 #endif

    87 

    88 /*

    89 ** The macro unlikely() is a hint that surrounds a boolean

    90 ** expression that is usually false.  Macro likely() surrounds

    91 ** a boolean expression that is usually true.  GCC is able to

    92 ** use these hints to generate better code, sometimes.

    93 */

    94 #if defined(__GNUC__) && 0

    95 # define likely(X)    __builtin_expect((X),1)

    96 # define unlikely(X)  __builtin_expect((X),0)

    97 #else

    98 # define likely(X)    !!(X)

    99 # define unlikely(X)  !!(X)

   100 #endif

   101 

   102 /*

   103  * This macro is used to "hide" some ugliness in casting an int

   104  * value to a ptr value under the MSVC 64-bit compiler.   Casting

   105  * non 64-bit values to ptr types results in a "hard" error with 

   106  * the MSVC 64-bit compiler which this attempts to avoid.  

   107  *

   108  * A simple compiler pragma or casting sequence could not be found

   109  * to correct this in all situations, so this macro was introduced.

   110  *

   111  * It could be argued that the intptr_t type could be used in this

   112  * case, but that type is not available on all compilers, or 

   113  * requires the #include of specific headers which differs between

   114  * platforms.

   115  */

   116 #define SQLITE_INT_TO_PTR(X)   ((void*)&((char*)0)[X])

   117 #define SQLITE_PTR_TO_INT(X)   ((int)(((char*)X)-(char*)0))

   118 

   119 /*

   120 ** These #defines should enable >2GB file support on Posix if the

   121 ** underlying operating system supports it.  If the OS lacks

   122 ** large file support, or if the OS is windows, these should be no-ops.

   123 **

   124 ** Ticket #2739:  The _LARGEFILE_SOURCE macro must appear before any

   125 ** system #includes.  Hence, this block of code must be the very first

   126 ** code in all source files.

   127 **

   128 ** Large file support can be disabled using the -DSQLITE_DISABLE_LFS switch

   129 ** on the compiler command line.  This is necessary if you are compiling

   130 ** on a recent machine (ex: RedHat 7.2) but you want your code to work

   131 ** on an older machine (ex: RedHat 6.0).  If you compile on RedHat 7.2

   132 ** without this option, LFS is enable.  But LFS does not exist in the kernel

   133 ** in RedHat 6.0, so the code won't work.  Hence, for maximum binary

   134 ** portability you should omit LFS.

   135 **

   136 ** Similar is true for MacOS.  LFS is only supported on MacOS 9 and later.

   137 */

   138 #ifndef SQLITE_DISABLE_LFS

   139 # define _LARGE_FILE       1

   140 # ifndef _FILE_OFFSET_BITS

   141 #   define _FILE_OFFSET_BITS 64

   142 # endif

   143 # define _LARGEFILE_SOURCE 1

   144 #endif

   145 

   146 

   147 /*

   148 ** The SQLITE_THREADSAFE macro must be defined as either 0 or 1.

   149 ** Older versions of SQLite used an optional THREADSAFE macro.

   150 ** We support that for legacy

   151 */

   152 #if !defined(SQLITE_THREADSAFE)

   153 #if defined(THREADSAFE)

   154 # define SQLITE_THREADSAFE THREADSAFE

   155 #else

   156 # define SQLITE_THREADSAFE 1

   157 #endif

   158 #endif

   159 

   160 /*

   161 ** Exactly one of the following macros must be defined in order to

   162 ** specify which memory allocation subsystem to use.

   163 **

   164 **     SQLITE_SYSTEM_MALLOC          // Use normal system malloc()

   165 **     SQLITE_MEMDEBUG               // Debugging version of system malloc()

   166 **     SQLITE_MEMORY_SIZE            // internal allocator #1

   167 **     SQLITE_MMAP_HEAP_SIZE         // internal mmap() allocator

   168 **     SQLITE_POW2_MEMORY_SIZE       // internal power-of-two allocator

   169 **

   170 ** If none of the above are defined, then set SQLITE_SYSTEM_MALLOC as

   171 ** the default.

   172 */

   173 #if defined(SQLITE_SYSTEM_MALLOC)+defined(SQLITE_MEMDEBUG)+\

   174     defined(SQLITE_MEMORY_SIZE)+defined(SQLITE_MMAP_HEAP_SIZE)+\

   175     defined(SQLITE_POW2_MEMORY_SIZE)>1

   176 # error "At most one of the following compile-time configuration options\

   177  is allows: SQLITE_SYSTEM_MALLOC, SQLITE_MEMDEBUG, SQLITE_MEMORY_SIZE,\

   178  SQLITE_MMAP_HEAP_SIZE, SQLITE_POW2_MEMORY_SIZE"

   179 #endif

   180 #if defined(SQLITE_SYSTEM_MALLOC)+defined(SQLITE_MEMDEBUG)+\

   181     defined(SQLITE_MEMORY_SIZE)+defined(SQLITE_MMAP_HEAP_SIZE)+\

   182     defined(SQLITE_POW2_MEMORY_SIZE)==0

   183 # define SQLITE_SYSTEM_MALLOC 1

   184 #endif

   185 

   186 /*

   187 ** If SQLITE_MALLOC_SOFT_LIMIT is defined, then try to keep the

   188 ** sizes of memory allocations below this value where possible.

   189 */

   190 #if defined(SQLITE_POW2_MEMORY_SIZE) && !defined(SQLITE_MALLOC_SOFT_LIMIT)

   191 # define SQLITE_MALLOC_SOFT_LIMIT 1024

   192 #endif

   193 

   194 /*

   195 ** We need to define _XOPEN_SOURCE as follows in order to enable

   196 ** recursive mutexes on most unix systems.  But Mac OS X is different.

   197 ** The _XOPEN_SOURCE define causes problems for Mac OS X we are told,

   198 ** so it is omitted there.  See ticket #2673.

   199 **

   200 ** Later we learn that _XOPEN_SOURCE is poorly or incorrectly

   201 ** implemented on some systems.  So we avoid defining it at all

   202 ** if it is already defined or if it is unneeded because we are

   203 ** not doing a threadsafe build.  Ticket #2681.

   204 **

   205 ** See also ticket #2741.

   206 */

   207 #if !defined(_XOPEN_SOURCE) && !defined(__DARWIN__) && !defined(__APPLE__) && SQLITE_THREADSAFE

   208 #  define _XOPEN_SOURCE 500  /* Needed to enable pthread recursive mutexes */

   209 #endif

   210 

   211 #if defined(SQLITE_TCL) || defined(TCLSH)

   212 # include <tcl.h>

   213 #endif

   214 

   215 /*

   216 ** Many people are failing to set -DNDEBUG=1 when compiling SQLite.

   217 ** Setting NDEBUG makes the code smaller and run faster.  So the following

   218 ** lines are added to automatically set NDEBUG unless the -DSQLITE_DEBUG=1

   219 ** option is set.  Thus NDEBUG becomes an opt-in rather than an opt-out

   220 ** feature.

   221 */

   222 #if !defined(NDEBUG) && !defined(SQLITE_DEBUG) 

   223 # define NDEBUG 1

   224 #endif

   225 

   226 #include "sqlite3.h"

   227 #include "hash.h"

   228 #include "parse.h"

   229 #include <stdio.h>

   230 #include <stdlib.h>

   231 #include <string.h>

   232 #include <assert.h>

   233 #include <stddef.h>

   234 

   235 /*

   236 ** If compiling for a processor that lacks floating point support,

   237 ** substitute integer for floating-point

   238 */

   239 #ifdef SQLITE_OMIT_FLOATING_POINT

   240 # define double sqlite_int64

   241 # define LONGDOUBLE_TYPE sqlite_int64

   242 # ifndef SQLITE_BIG_DBL

   243 #   define SQLITE_BIG_DBL (0x7fffffffffffffff)

   244 # endif

   245 # define SQLITE_OMIT_DATETIME_FUNCS 1

   246 # define SQLITE_OMIT_TRACE 1

   247 # undef SQLITE_MIXED_ENDIAN_64BIT_FLOAT

   248 #endif

   249 #ifndef SQLITE_BIG_DBL

   250 # define SQLITE_BIG_DBL (1e99)

   251 #endif

   252 

   253 /*

   254 ** OMIT_TEMPDB is set to 1 if SQLITE_OMIT_TEMPDB is defined, or 0

   255 ** afterward. Having this macro allows us to cause the C compiler 

   256 ** to omit code used by TEMP tables without messy #ifndef statements.

   257 */

   258 #ifdef SQLITE_OMIT_TEMPDB

   259 #define OMIT_TEMPDB 1

   260 #else

   261 #define OMIT_TEMPDB 0

   262 #endif

   263 

   264 /*

   265 ** If the following macro is set to 1, then NULL values are considered

   266 ** distinct when determining whether or not two entries are the same

   267 ** in a UNIQUE index.  This is the way PostgreSQL, Oracle, DB2, MySQL,

   268 ** OCELOT, and Firebird all work.  The SQL92 spec explicitly says this

   269 ** is the way things are suppose to work.

   270 **

   271 ** If the following macro is set to 0, the NULLs are indistinct for

   272 ** a UNIQUE index.  In this mode, you can only have a single NULL entry

   273 ** for a column declared UNIQUE.  This is the way Informix and SQL Server

   274 ** work.

   275 */

   276 #define NULL_DISTINCT_FOR_UNIQUE 1

   277 

   278 /*

   279 ** The "file format" number is an integer that is incremented whenever

   280 ** the VDBE-level file format changes.  The following macros define the

   281 ** the default file format for new databases and the maximum file format

   282 ** that the library can read.

   283 */

   284 #define SQLITE_MAX_FILE_FORMAT 4

   285 #ifndef SQLITE_DEFAULT_FILE_FORMAT

   286 # define SQLITE_DEFAULT_FILE_FORMAT 1

   287 #endif

   288 

   289 /*

   290 ** Provide a default value for SQLITE_TEMP_STORE in case it is not specified

   291 ** on the command-line

   292 */

   293 #ifndef SQLITE_TEMP_STORE

   294 # define SQLITE_TEMP_STORE 1

   295 #endif

   296 

   297 /*

   298 ** GCC does not define the offsetof() macro so we'll have to do it

   299 ** ourselves.

   300 */

   301 #ifndef offsetof

   302 #define offsetof(STRUCTURE,FIELD) ((int)((char*)&((STRUCTURE*)0)->FIELD))

   303 #endif

   304 

   305 /*

   306 ** Check to see if this machine uses EBCDIC.  (Yes, believe it or

   307 ** not, there are still machines out there that use EBCDIC.)

   308 */

   309 #if 'A' == '\301'

   310 # define SQLITE_EBCDIC 1

   311 #else

   312 # define SQLITE_ASCII 1

   313 #endif

   314 

   315 /*

   316 ** Integers of known sizes.  These typedefs might change for architectures

   317 ** where the sizes very.  Preprocessor macros are available so that the

   318 ** types can be conveniently redefined at compile-type.  Like this:

   319 **

   320 **         cc '-DUINTPTR_TYPE=long long int' ...

   321 */

   322 #ifndef UINT32_TYPE

   323 # ifdef HAVE_UINT32_T

   324 #  define UINT32_TYPE uint32_t

   325 # else

   326 #  define UINT32_TYPE unsigned int

   327 # endif

   328 #endif

   329 #ifndef UINT16_TYPE

   330 # ifdef HAVE_UINT16_T

   331 #  define UINT16_TYPE uint16_t

   332 # else

   333 #  define UINT16_TYPE unsigned short int

   334 # endif

   335 #endif

   336 #ifndef INT16_TYPE

   337 # ifdef HAVE_INT16_T

   338 #  define INT16_TYPE int16_t

   339 # else

   340 #  define INT16_TYPE short int

   341 # endif

   342 #endif

   343 #ifndef UINT8_TYPE

   344 # ifdef HAVE_UINT8_T

   345 #  define UINT8_TYPE uint8_t

   346 # else

   347 #  define UINT8_TYPE unsigned char

   348 # endif

   349 #endif

   350 #ifndef INT8_TYPE

   351 # ifdef HAVE_INT8_T

   352 #  define INT8_TYPE int8_t

   353 # else

   354 #  define INT8_TYPE signed char

   355 # endif

   356 #endif

   357 #ifndef LONGDOUBLE_TYPE

   358 # define LONGDOUBLE_TYPE long double

   359 #endif

   360 typedef sqlite_int64 i64;          /* 8-byte signed integer */

   361 typedef sqlite_uint64 u64;         /* 8-byte unsigned integer */

   362 typedef UINT32_TYPE u32;           /* 4-byte unsigned integer */

   363 typedef UINT16_TYPE u16;           /* 2-byte unsigned integer */

   364 typedef INT16_TYPE i16;            /* 2-byte signed integer */

   365 typedef UINT8_TYPE u8;             /* 1-byte unsigned integer */

   366 typedef UINT8_TYPE i8;             /* 1-byte signed integer */

   367 

   368 /*

   369 ** Macros to determine whether the machine is big or little endian,

   370 ** evaluated at runtime.

   371 */

   372 #ifdef SQLITE_AMALGAMATION

   373 const int sqlite3one;

   374 #else

   375 extern const int sqlite3one;

   376 #endif

   377 #if defined(i386) || defined(__i386__) || defined(_M_IX86)

   378 # define SQLITE_BIGENDIAN    0

   379 # define SQLITE_LITTLEENDIAN 1

   380 # define SQLITE_UTF16NATIVE  SQLITE_UTF16LE

   381 #else

   382 # define SQLITE_BIGENDIAN    (*(char *)(&sqlite3one)==0)

   383 # define SQLITE_LITTLEENDIAN (*(char *)(&sqlite3one)==1)

   384 # define SQLITE_UTF16NATIVE (SQLITE_BIGENDIAN?SQLITE_UTF16BE:SQLITE_UTF16LE)

   385 #endif

   386 

   387 /*

   388 ** Constants for the largest and smallest possible 64-bit signed integers.

   389 ** These macros are designed to work correctly on both 32-bit and 64-bit

   390 ** compilers.

   391 */

   392 #define LARGEST_INT64  (0xffffffff|(((i64)0x7fffffff)<<32))

   393 #define SMALLEST_INT64 (((i64)-1) - LARGEST_INT64)

   394 

   395 /*

   396 ** An instance of the following structure is used to store the busy-handler

   397 ** callback for a given sqlite handle. 

   398 **

   399 ** The sqlite.busyHandler member of the sqlite struct contains the busy

   400 ** callback for the database handle. Each pager opened via the sqlite

   401 ** handle is passed a pointer to sqlite.busyHandler. The busy-handler

   402 ** callback is currently invoked only from within pager.c.

   403 */

   404 typedef struct BusyHandler BusyHandler;

   405 struct BusyHandler {

   406   int (*xFunc)(void *,int);  /* The busy callback */

   407   void *pArg;                /* First arg to busy callback */

   408   int nBusy;                 /* Incremented with each busy call */

   409 };

   410 

   411 /*

   412 ** Name of the master database table.  The master database table

   413 ** is a special table that holds the names and attributes of all

   414 ** user tables and indices.

   415 */

   416 #define MASTER_NAME       "sqlite_master"

   417 #define TEMP_MASTER_NAME  "sqlite_temp_master"

   418 

   419 /*

   420 ** The root-page of the master database table.

   421 */

   422 #define MASTER_ROOT       1

   423 

   424 /*

   425 ** The name of the schema table.

   426 */

   427 #define SCHEMA_TABLE(x)  ((!OMIT_TEMPDB)&&(x==1)?TEMP_MASTER_NAME:MASTER_NAME)

   428 

   429 /*

   430 ** A convenience macro that returns the number of elements in

   431 ** an array.

   432 */

   433 #define ArraySize(X)    (sizeof(X)/sizeof(X[0]))

   434 

   435 /*

   436 ** The following value as a destructor means to use sqlite3DbFree().

   437 ** This is an internal extension to SQLITE_STATIC and SQLITE_TRANSIENT.

   438 */

   439 #define SQLITE_DYNAMIC   ((sqlite3_destructor_type)sqlite3DbFree)

   440 

   441 /*

   442 ** Forward references to structures

   443 */

   444 typedef struct AggInfo AggInfo;

   445 typedef struct AuthContext AuthContext;

   446 typedef struct Bitvec Bitvec;

   447 typedef struct CollSeq CollSeq;

   448 typedef struct Column Column;

   449 typedef struct Db Db;

   450 typedef struct Schema Schema;

   451 typedef struct Expr Expr;

   452 typedef struct ExprList ExprList;

   453 typedef struct FKey FKey;

   454 typedef struct FuncDef FuncDef;

   455 typedef struct IdList IdList;

   456 typedef struct Index Index;

   457 typedef struct KeyClass KeyClass;

   458 typedef struct KeyInfo KeyInfo;

   459 typedef struct Lookaside Lookaside;

   460 typedef struct LookasideSlot LookasideSlot;

   461 typedef struct Module Module;

   462 typedef struct NameContext NameContext;

   463 typedef struct Parse Parse;

   464 typedef struct Select Select;

   465 typedef struct SrcList SrcList;

   466 typedef struct StrAccum StrAccum;

   467 typedef struct Table Table;

   468 typedef struct TableLock TableLock;

   469 typedef struct Token Token;

   470 typedef struct TriggerStack TriggerStack;

   471 typedef struct TriggerStep TriggerStep;

   472 typedef struct Trigger Trigger;

   473 typedef struct WhereInfo WhereInfo;

   474 typedef struct WhereLevel WhereLevel;

   475 

   476 /*

   477 ** Defer sourcing vdbe.h and btree.h until after the "u8" and 

   478 ** "BusyHandler" typedefs. vdbe.h also requires a few of the opaque

   479 ** pointer types (i.e. FuncDef) defined above.

   480 */

   481 #include "btree.h"

   482 #include "vdbe.h"

   483 #include "pager.h"

   484 

   485 #include "os.h"

   486 #include "mutex.h"

   487 

   488 

   489 /*

   490 ** Each database file to be accessed by the system is an instance

   491 ** of the following structure.  There are normally two of these structures

   492 ** in the sqlite.aDb[] array.  aDb[0] is the main database file and

   493 ** aDb[1] is the database file used to hold temporary tables.  Additional

   494 ** databases may be attached.

   495 */

   496 struct Db {

   497   char *zName;         /* Name of this database */

   498   Btree *pBt;          /* The B*Tree structure for this database file */

   499   u8 inTrans;          /* 0: not writable.  1: Transaction.  2: Checkpoint */

   500   u8 safety_level;     /* How aggressive at synching data to disk */

   501   void *pAux;               /* Auxiliary data.  Usually NULL */

   502   void (*xFreeAux)(void*);  /* Routine to free pAux */

   503   Schema *pSchema;     /* Pointer to database schema (possibly shared) */

   504 };

   505 

   506 /*

   507 ** An instance of the following structure stores a database schema.

   508 **

   509 ** If there are no virtual tables configured in this schema, the

   510 ** Schema.db variable is set to NULL. After the first virtual table

   511 ** has been added, it is set to point to the database connection 

   512 ** used to create the connection. Once a virtual table has been

   513 ** added to the Schema structure and the Schema.db variable populated, 

   514 ** only that database connection may use the Schema to prepare 

   515 ** statements.

   516 */

   517 struct Schema {

   518   int schema_cookie;   /* Database schema version number for this file */

   519   Hash tblHash;        /* All tables indexed by name */

   520   Hash idxHash;        /* All (named) indices indexed by name */

   521   Hash trigHash;       /* All triggers indexed by name */

   522   Hash aFKey;          /* Foreign keys indexed by to-table */

   523   Table *pSeqTab;      /* The sqlite_sequence table used by AUTOINCREMENT */

   524   u8 file_format;      /* Schema format version for this file */

   525   u8 enc;              /* Text encoding used by this database */

   526   u16 flags;           /* Flags associated with this schema */

   527   int cache_size;      /* Number of pages to use in the cache */

   528 #ifndef SQLITE_OMIT_VIRTUALTABLE

   529   sqlite3 *db;         /* "Owner" connection. See comment above */

   530 #endif

   531 };

   532 

   533 /*

   534 ** These macros can be used to test, set, or clear bits in the 

   535 ** Db.flags field.

   536 */

   537 #define DbHasProperty(D,I,P)     (((D)->aDb[I].pSchema->flags&(P))==(P))

   538 #define DbHasAnyProperty(D,I,P)  (((D)->aDb[I].pSchema->flags&(P))!=0)

   539 #define DbSetProperty(D,I,P)     (D)->aDb[I].pSchema->flags|=(P)

   540 #define DbClearProperty(D,I,P)   (D)->aDb[I].pSchema->flags&=~(P)

   541 

   542 /*

   543 ** Allowed values for the DB.flags field.

   544 **

   545 ** The DB_SchemaLoaded flag is set after the database schema has been

   546 ** read into internal hash tables.

   547 **

   548 ** DB_UnresetViews means that one or more views have column names that

   549 ** have been filled out.  If the schema changes, these column names might

   550 ** changes and so the view will need to be reset.

   551 */

   552 #define DB_SchemaLoaded    0x0001  /* The schema has been loaded */

   553 #define DB_UnresetViews    0x0002  /* Some views have defined column names */

   554 #define DB_Empty           0x0004  /* The file is empty (length 0 bytes) */

   555 

   556 /*

   557 ** The number of different kinds of things that can be limited

   558 ** using the sqlite3_limit() interface.

   559 */

   560 #define SQLITE_N_LIMIT (SQLITE_LIMIT_VARIABLE_NUMBER+1)

   561 

   562 /*

   563 ** Lookaside malloc is a set of fixed-size buffers that can be used

   564 ** to satisify small transient memory allocation requests for objects

   565 ** associated with a particular database connection.  The use of

   566 ** lookaside malloc provides a significant performance enhancement

   567 ** (approx 10%) by avoiding numerous malloc/free requests while parsing

   568 ** SQL statements.

   569 **

   570 ** The Lookaside structure holds configuration information about the

   571 ** lookaside malloc subsystem.  Each available memory allocation in

   572 ** the lookaside subsystem is stored on a linked list of LookasideSlot

   573 ** objects.

   574 */

   575 struct Lookaside {

   576   u16 sz;                 /* Size of each buffer in bytes */

   577   u8 bEnabled;            /* True if use lookaside.  False to ignore it */

   578   u8 bMalloced;           /* True if pStart obtained from sqlite3_malloc() */

   579   int nOut;               /* Number of buffers currently checked out */

   580   int mxOut;              /* Highwater mark for nOut */

   581   LookasideSlot *pFree;   /* List if available buffers */

   582   void *pStart;           /* First byte of available memory space */

   583   void *pEnd;             /* First byte past end of available space */

   584 };

   585 struct LookasideSlot {

   586   LookasideSlot *pNext;    /* Next buffer in the list of free buffers */

   587 };

   588 

   589 /*

   590 ** Each database is an instance of the following structure.

   591 **

   592 ** The sqlite.lastRowid records the last insert rowid generated by an

   593 ** insert statement.  Inserts on views do not affect its value.  Each

   594 ** trigger has its own context, so that lastRowid can be updated inside

   595 ** triggers as usual.  The previous value will be restored once the trigger

   596 ** exits.  Upon entering a before or instead of trigger, lastRowid is no

   597 ** longer (since after version 2.8.12) reset to -1.

   598 **

   599 ** The sqlite.nChange does not count changes within triggers and keeps no

   600 ** context.  It is reset at start of sqlite3_exec.

   601 ** The sqlite.lsChange represents the number of changes made by the last

   602 ** insert, update, or delete statement.  It remains constant throughout the

   603 ** length of a statement and is then updated by OP_SetCounts.  It keeps a

   604 ** context stack just like lastRowid so that the count of changes

   605 ** within a trigger is not seen outside the trigger.  Changes to views do not

   606 ** affect the value of lsChange.

   607 ** The sqlite.csChange keeps track of the number of current changes (since

   608 ** the last statement) and is used to update sqlite_lsChange.

   609 **

   610 ** The member variables sqlite.errCode, sqlite.zErrMsg and sqlite.zErrMsg16

   611 ** store the most recent error code and, if applicable, string. The

   612 ** internal function sqlite3Error() is used to set these variables

   613 ** consistently.

   614 */

   615 struct sqlite3 {

   616   sqlite3_vfs *pVfs;            /* OS Interface */

   617   int nDb;                      /* Number of backends currently in use */

   618   Db *aDb;                      /* All backends */

   619   int flags;                    /* Miscellanous flags. See below */

   620   int openFlags;                /* Flags passed to sqlite3_vfs.xOpen() */

   621   int errCode;                  /* Most recent error code (SQLITE_*) */

   622   int errMask;                  /* & result codes with this before returning */

   623   u8 autoCommit;                /* The auto-commit flag. */

   624   u8 temp_store;                /* 1: file 2: memory 0: default */

   625   u8 mallocFailed;              /* True if we have seen a malloc failure */

   626   u8 dfltLockMode;              /* Default locking-mode for attached dbs */

   627   u8 dfltJournalMode;           /* Default journal mode for attached dbs */

   628   signed char nextAutovac;      /* Autovac setting after VACUUM if >=0 */

   629   int nextPagesize;             /* Pagesize after VACUUM if >0 */

   630   int nTable;                   /* Number of tables in the database */

   631   CollSeq *pDfltColl;           /* The default collating sequence (BINARY) */

   632   i64 lastRowid;                /* ROWID of most recent insert (see above) */

   633   i64 priorNewRowid;            /* Last randomly generated ROWID */

   634   int magic;                    /* Magic number for detect library misuse */

   635   int nChange;                  /* Value returned by sqlite3_changes() */

   636   int nTotalChange;             /* Value returned by sqlite3_total_changes() */

   637   sqlite3_mutex *mutex;         /* Connection mutex */

   638   int aLimit[SQLITE_N_LIMIT];   /* Limits */

   639   struct sqlite3InitInfo {      /* Information used during initialization */

   640     int iDb;                    /* When back is being initialized */

   641     int newTnum;                /* Rootpage of table being initialized */

   642     u8 busy;                    /* TRUE if currently initializing */

   643   } init;

   644   int nExtension;               /* Number of loaded extensions */

   645   void **aExtension;            /* Array of shared libraray handles */

   646   struct Vdbe *pVdbe;           /* List of active virtual machines */

   647   int activeVdbeCnt;            /* Number of vdbes currently executing */

   648   void (*xTrace)(void*,const char*);        /* Trace function */

   649   void *pTraceArg;                          /* Argument to the trace function */

   650   void (*xProfile)(void*,const char*,u64);  /* Profiling function */

   651   void *pProfileArg;                        /* Argument to profile function */

   652   void *pCommitArg;                 /* Argument to xCommitCallback() */   

   653   int (*xCommitCallback)(void*);    /* Invoked at every commit. */

   654   void *pRollbackArg;               /* Argument to xRollbackCallback() */   

   655   void (*xRollbackCallback)(void*); /* Invoked at every commit. */

   656   void *pUpdateArg;

   657   void (*xUpdateCallback)(void*,int, const char*,const char*,sqlite_int64);

   658   void(*xCollNeeded)(void*,sqlite3*,int eTextRep,const char*);

   659   void(*xCollNeeded16)(void*,sqlite3*,int eTextRep,const void*);

   660   void *pCollNeededArg;

   661   sqlite3_value *pErr;          /* Most recent error message */

   662   char *zErrMsg;                /* Most recent error message (UTF-8 encoded) */

   663   char *zErrMsg16;              /* Most recent error message (UTF-16 encoded) */

   664   union {

   665     int isInterrupted;          /* True if sqlite3_interrupt has been called */

   666     double notUsed1;            /* Spacer */

   667   } u1;

   668   Lookaside lookaside;          /* Lookaside malloc configuration */

   669 #ifndef SQLITE_OMIT_AUTHORIZATION

   670   int (*xAuth)(void*,int,const char*,const char*,const char*,const char*);

   671                                 /* Access authorization function */

   672   void *pAuthArg;               /* 1st argument to the access auth function */

   673 #endif

   674 #ifndef SQLITE_OMIT_PROGRESS_CALLBACK

   675   int (*xProgress)(void *);     /* The progress callback */

   676   void *pProgressArg;           /* Argument to the progress callback */

   677   int nProgressOps;             /* Number of opcodes for progress callback */

   678 #endif

   679 #ifndef SQLITE_OMIT_VIRTUALTABLE

   680   Hash aModule;                 /* populated by sqlite3_create_module() */

   681   Table *pVTab;                 /* vtab with active Connect/Create method */

   682   sqlite3_vtab **aVTrans;       /* Virtual tables with open transactions */

   683   int nVTrans;                  /* Allocated size of aVTrans */

   684 #endif

   685   Hash aFunc;                   /* All functions that can be in SQL exprs */

   686   Hash aCollSeq;                /* All collating sequences */

   687   BusyHandler busyHandler;      /* Busy callback */

   688   int busyTimeout;              /* Busy handler timeout, in msec */

   689   Db aDbStatic[2];              /* Static space for the 2 default backends */

   690 #ifdef SQLITE_SSE

   691   sqlite3_stmt *pFetch;         /* Used by SSE to fetch stored statements */

   692 #endif

   693 };

   694 

   695 /*

   696 ** A macro to discover the encoding of a database.

   697 */

   698 #define ENC(db) ((db)->aDb[0].pSchema->enc)

   699 

   700 /*

   701 ** Possible values for the sqlite.flags and or Db.flags fields.

   702 **

   703 ** On sqlite.flags, the SQLITE_InTrans value means that we have

   704 ** executed a BEGIN.  On Db.flags, SQLITE_InTrans means a statement

   705 ** transaction is active on that particular database file.

   706 */

   707 #define SQLITE_VdbeTrace      0x00000001  /* True to trace VDBE execution */

   708 #define SQLITE_InTrans        0x00000008  /* True if in a transaction */

   709 #define SQLITE_InternChanges  0x00000010  /* Uncommitted Hash table changes */

   710 #define SQLITE_FullColNames   0x00000020  /* Show full column names on SELECT */

   711 #define SQLITE_ShortColNames  0x00000040  /* Show short columns names */

   712 #define SQLITE_CountRows      0x00000080  /* Count rows changed by INSERT, */

   713                                           /*   DELETE, or UPDATE and return */

   714                                           /*   the count using a callback. */

   715 #define SQLITE_NullCallback   0x00000100  /* Invoke the callback once if the */

   716                                           /*   result set is empty */

   717 #define SQLITE_SqlTrace       0x00000200  /* Debug print SQL as it executes */

   718 #define SQLITE_VdbeListing    0x00000400  /* Debug listings of VDBE programs */

   719 #define SQLITE_WriteSchema    0x00000800  /* OK to update SQLITE_MASTER */

   720 #define SQLITE_NoReadlock     0x00001000  /* Readlocks are omitted when 

   721                                           ** accessing read-only databases */

   722 #define SQLITE_IgnoreChecks   0x00002000  /* Do not enforce check constraints */

   723 #define SQLITE_ReadUncommitted 0x00004000 /* For shared-cache mode */

   724 #define SQLITE_LegacyFileFmt  0x00008000  /* Create new databases in format 1 */

   725 #define SQLITE_FullFSync      0x00010000  /* Use full fsync on the backend */

   726 #define SQLITE_LoadExtension  0x00020000  /* Enable load_extension */

   727 

   728 #define SQLITE_RecoveryMode   0x00040000  /* Ignore schema errors */

   729 #define SQLITE_SharedCache    0x00080000  /* Cache sharing is enabled */

   730 #define SQLITE_Vtab           0x00100000  /* There exists a virtual table */

   731 

   732 /*

   733 ** Possible values for the sqlite.magic field.

   734 ** The numbers are obtained at random and have no special meaning, other

   735 ** than being distinct from one another.

   736 */

   737 #define SQLITE_MAGIC_OPEN     0xa029a697  /* Database is open */

   738 #define SQLITE_MAGIC_CLOSED   0x9f3c2d33  /* Database is closed */

   739 #define SQLITE_MAGIC_SICK     0x4b771290  /* Error and awaiting close */

   740 #define SQLITE_MAGIC_BUSY     0xf03b7906  /* Database currently in use */

   741 #define SQLITE_MAGIC_ERROR    0xb5357930  /* An SQLITE_MISUSE error occurred */

   742 

   743 /*

   744 ** Each SQL function is defined by an instance of the following

   745 ** structure.  A pointer to this structure is stored in the sqlite.aFunc

   746 ** hash table.  When multiple functions have the same name, the hash table

   747 ** points to a linked list of these structures.

   748 */

   749 struct FuncDef {

   750   i16 nArg;            /* Number of arguments.  -1 means unlimited */

   751   u8 iPrefEnc;         /* Preferred text encoding (SQLITE_UTF8, 16LE, 16BE) */

   752   u8 needCollSeq;      /* True if sqlite3GetFuncCollSeq() might be called */

   753   u8 flags;            /* Some combination of SQLITE_FUNC_* */

   754   void *pUserData;     /* User data parameter */

   755   FuncDef *pNext;      /* Next function with same name */

   756   void (*xFunc)(sqlite3_context*,int,sqlite3_value**); /* Regular function */

   757   void (*xStep)(sqlite3_context*,int,sqlite3_value**); /* Aggregate step */

   758   void (*xFinalize)(sqlite3_context*);                /* Aggregate finializer */

   759   char zName[1];       /* SQL name of the function.  MUST BE LAST */

   760 };

   761 

   762 /*

   763 ** Each SQLite module (virtual table definition) is defined by an

   764 ** instance of the following structure, stored in the sqlite3.aModule

   765 ** hash table.

   766 */

   767 struct Module {

   768   const sqlite3_module *pModule;       /* Callback pointers */

   769   const char *zName;                   /* Name passed to create_module() */

   770   void *pAux;                          /* pAux passed to create_module() */

   771   void (*xDestroy)(void *);            /* Module destructor function */

   772 };

   773 

   774 /*

   775 ** Possible values for FuncDef.flags

   776 */

   777 #define SQLITE_FUNC_LIKE   0x01  /* Candidate for the LIKE optimization */

   778 #define SQLITE_FUNC_CASE   0x02  /* Case-sensitive LIKE-type function */

   779 #define SQLITE_FUNC_EPHEM  0x04  /* Ephermeral.  Delete with VDBE */

   780 

   781 /*

   782 ** information about each column of an SQL table is held in an instance

   783 ** of this structure.

   784 */

   785 struct Column {

   786   char *zName;     /* Name of this column */

   787   Expr *pDflt;     /* Default value of this column */

   788   char *zType;     /* Data type for this column */

   789   char *zColl;     /* Collating sequence.  If NULL, use the default */

   790   u8 notNull;      /* True if there is a NOT NULL constraint */

   791   u8 isPrimKey;    /* True if this column is part of the PRIMARY KEY */

   792   char affinity;   /* One of the SQLITE_AFF_... values */

   793 #ifndef SQLITE_OMIT_VIRTUALTABLE

   794   u8 isHidden;     /* True if this column is 'hidden' */

   795 #endif

   796 };

   797 

   798 /*

   799 ** A "Collating Sequence" is defined by an instance of the following

   800 ** structure. Conceptually, a collating sequence consists of a name and

   801 ** a comparison routine that defines the order of that sequence.

   802 **

   803 ** There may two seperate implementations of the collation function, one

   804 ** that processes text in UTF-8 encoding (CollSeq.xCmp) and another that

   805 ** processes text encoded in UTF-16 (CollSeq.xCmp16), using the machine

   806 ** native byte order. When a collation sequence is invoked, SQLite selects

   807 ** the version that will require the least expensive encoding

   808 ** translations, if any.

   809 **

   810 ** The CollSeq.pUser member variable is an extra parameter that passed in

   811 ** as the first argument to the UTF-8 comparison function, xCmp.

   812 ** CollSeq.pUser16 is the equivalent for the UTF-16 comparison function,

   813 ** xCmp16.

   814 **

   815 ** If both CollSeq.xCmp and CollSeq.xCmp16 are NULL, it means that the

   816 ** collating sequence is undefined.  Indices built on an undefined

   817 ** collating sequence may not be read or written.

   818 */

   819 struct CollSeq {

   820   char *zName;          /* Name of the collating sequence, UTF-8 encoded */

   821   u8 enc;               /* Text encoding handled by xCmp() */

   822   u8 type;              /* One of the SQLITE_COLL_... values below */

   823   void *pUser;          /* First argument to xCmp() */

   824   int (*xCmp)(void*,int, const void*, int, const void*);

   825   void (*xDel)(void*);  /* Destructor for pUser */

   826 };

   827 

   828 /*

   829 ** Allowed values of CollSeq flags:

   830 */

   831 #define SQLITE_COLL_BINARY  1  /* The default memcmp() collating sequence */

   832 #define SQLITE_COLL_NOCASE  2  /* The built-in NOCASE collating sequence */

   833 #define SQLITE_COLL_REVERSE 3  /* The built-in REVERSE collating sequence */

   834 #define SQLITE_COLL_USER    0  /* Any other user-defined collating sequence */

   835 

   836 /*

   837 ** A sort order can be either ASC or DESC.

   838 */

   839 #define SQLITE_SO_ASC       0  /* Sort in ascending order */

   840 #define SQLITE_SO_DESC      1  /* Sort in ascending order */

   841 

   842 /*

   843 ** Column affinity types.

   844 **

   845 ** These used to have mnemonic name like 'i' for SQLITE_AFF_INTEGER and

   846 ** 't' for SQLITE_AFF_TEXT.  But we can save a little space and improve

   847 ** the speed a little by number the values consecutively.  

   848 **

   849 ** But rather than start with 0 or 1, we begin with 'a'.  That way,

   850 ** when multiple affinity types are concatenated into a string and

   851 ** used as the P4 operand, they will be more readable.

   852 **

   853 ** Note also that the numeric types are grouped together so that testing

   854 ** for a numeric type is a single comparison.

   855 */

   856 #define SQLITE_AFF_TEXT     'a'

   857 #define SQLITE_AFF_NONE     'b'

   858 #define SQLITE_AFF_NUMERIC  'c'

   859 #define SQLITE_AFF_INTEGER  'd'

   860 #define SQLITE_AFF_REAL     'e'

   861 

   862 #define sqlite3IsNumericAffinity(X)  ((X)>=SQLITE_AFF_NUMERIC)

   863 

   864 /*

   865 ** The SQLITE_AFF_MASK values masks off the significant bits of an

   866 ** affinity value. 

   867 */

   868 #define SQLITE_AFF_MASK     0x67

   869 

   870 /*

   871 ** Additional bit values that can be ORed with an affinity without

   872 ** changing the affinity.

   873 */

   874 #define SQLITE_JUMPIFNULL   0x08  /* jumps if either operand is NULL */

   875 #define SQLITE_STOREP2      0x10  /* Store result in reg[P2] rather than jump */

   876 

   877 /*

   878 ** Each SQL table is represented in memory by an instance of the

   879 ** following structure.

   880 **

   881 ** Table.zName is the name of the table.  The case of the original

   882 ** CREATE TABLE statement is stored, but case is not significant for

   883 ** comparisons.

   884 **

   885 ** Table.nCol is the number of columns in this table.  Table.aCol is a

   886 ** pointer to an array of Column structures, one for each column.

   887 **

   888 ** If the table has an INTEGER PRIMARY KEY, then Table.iPKey is the index of

   889 ** the column that is that key.   Otherwise Table.iPKey is negative.  Note

   890 ** that the datatype of the PRIMARY KEY must be INTEGER for this field to

   891 ** be set.  An INTEGER PRIMARY KEY is used as the rowid for each row of

   892 ** the table.  If a table has no INTEGER PRIMARY KEY, then a random rowid

   893 ** is generated for each row of the table.  Table.hasPrimKey is true if

   894 ** the table has any PRIMARY KEY, INTEGER or otherwise.

   895 **

   896 ** Table.tnum is the page number for the root BTree page of the table in the

   897 ** database file.  If Table.iDb is the index of the database table backend

   898 ** in sqlite.aDb[].  0 is for the main database and 1 is for the file that

   899 ** holds temporary tables and indices.  If Table.isEphem

   900 ** is true, then the table is stored in a file that is automatically deleted

   901 ** when the VDBE cursor to the table is closed.  In this case Table.tnum 

   902 ** refers VDBE cursor number that holds the table open, not to the root

   903 ** page number.  Transient tables are used to hold the results of a

   904 ** sub-query that appears instead of a real table name in the FROM clause 

   905 ** of a SELECT statement.

   906 */

   907 struct Table {

   908   sqlite3 *db;     /* Associated database connection.  Might be NULL. */

   909   char *zName;     /* Name of the table */

   910   int nCol;        /* Number of columns in this table */

   911   Column *aCol;    /* Information about each column */

   912   int iPKey;       /* If not less then 0, use aCol[iPKey] as the primary key */

   913   Index *pIndex;   /* List of SQL indexes on this table. */

   914   int tnum;        /* Root BTree node for this table (see note above) */

   915   Select *pSelect; /* NULL for tables.  Points to definition if a view. */

   916   int nRef;          /* Number of pointers to this Table */

   917   Trigger *pTrigger; /* List of SQL triggers on this table */

   918   FKey *pFKey;       /* Linked list of all foreign keys in this table */

   919   char *zColAff;     /* String defining the affinity of each column */

   920 #ifndef SQLITE_OMIT_CHECK

   921   Expr *pCheck;      /* The AND of all CHECK constraints */

   922 #endif

   923 #ifndef SQLITE_OMIT_ALTERTABLE

   924   int addColOffset;  /* Offset in CREATE TABLE statement to add a new column */

   925 #endif

   926   u8 readOnly;     /* True if this table should not be written by the user */

   927   u8 isEphem;      /* True if created using OP_OpenEphermeral */

   928   u8 hasPrimKey;   /* True if there exists a primary key */

   929   u8 keyConf;      /* What to do in case of uniqueness conflict on iPKey */

   930   u8 autoInc;      /* True if the integer primary key is autoincrement */

   931 #ifndef SQLITE_OMIT_VIRTUALTABLE

   932   u8 isVirtual;             /* True if this is a virtual table */

   933   u8 isCommit;              /* True once the CREATE TABLE has been committed */

   934   Module *pMod;             /* Pointer to the implementation of the module */

   935   sqlite3_vtab *pVtab;      /* Pointer to the module instance */

   936   int nModuleArg;           /* Number of arguments to the module */

   937   char **azModuleArg;       /* Text of all module args. [0] is module name */

   938 #endif

   939   Schema *pSchema;          /* Schema that contains this table */

   940 };

   941 

   942 /*

   943 ** Test to see whether or not a table is a virtual table.  This is

   944 ** done as a macro so that it will be optimized out when virtual

   945 ** table support is omitted from the build.

   946 */

   947 #ifndef SQLITE_OMIT_VIRTUALTABLE

   948 #  define IsVirtual(X)      ((X)->isVirtual)

   949 #  define IsHiddenColumn(X) ((X)->isHidden)

   950 #else

   951 #  define IsVirtual(X)      0

   952 #  define IsHiddenColumn(X) 0

   953 #endif

   954 

   955 /*

   956 ** Each foreign key constraint is an instance of the following structure.

   957 **

   958 ** A foreign key is associated with two tables.  The "from" table is

   959 ** the table that contains the REFERENCES clause that creates the foreign

   960 ** key.  The "to" table is the table that is named in the REFERENCES clause.

   961 ** Consider this example:

   962 **

   963 **     CREATE TABLE ex1(

   964 **       a INTEGER PRIMARY KEY,

   965 **       b INTEGER CONSTRAINT fk1 REFERENCES ex2(x)

   966 **     );

   967 **

   968 ** For foreign key "fk1", the from-table is "ex1" and the to-table is "ex2".

   969 **

   970 ** Each REFERENCES clause generates an instance of the following structure

   971 ** which is attached to the from-table.  The to-table need not exist when

   972 ** the from-table is created.  The existance of the to-table is not checked

   973 ** until an attempt is made to insert data into the from-table.

   974 **

   975 ** The sqlite.aFKey hash table stores pointers to this structure

   976 ** given the name of a to-table.  For each to-table, all foreign keys

   977 ** associated with that table are on a linked list using the FKey.pNextTo

   978 ** field.

   979 */

   980 struct FKey {

   981   Table *pFrom;     /* The table that constains the REFERENCES clause */

   982   FKey *pNextFrom;  /* Next foreign key in pFrom */

   983   char *zTo;        /* Name of table that the key points to */

   984   FKey *pNextTo;    /* Next foreign key that points to zTo */

   985   int nCol;         /* Number of columns in this key */

   986   struct sColMap {  /* Mapping of columns in pFrom to columns in zTo */

   987     int iFrom;         /* Index of column in pFrom */

   988     char *zCol;        /* Name of column in zTo.  If 0 use PRIMARY KEY */

   989   } *aCol;          /* One entry for each of nCol column s */

   990   u8 isDeferred;    /* True if constraint checking is deferred till COMMIT */

   991   u8 updateConf;    /* How to resolve conflicts that occur on UPDATE */

   992   u8 deleteConf;    /* How to resolve conflicts that occur on DELETE */

   993   u8 insertConf;    /* How to resolve conflicts that occur on INSERT */

   994 };

   995 

   996 /*

   997 ** SQLite supports many different ways to resolve a constraint

   998 ** error.  ROLLBACK processing means that a constraint violation

   999 ** causes the operation in process to fail and for the current transaction

  1000 ** to be rolled back.  ABORT processing means the operation in process

  1001 ** fails and any prior changes from that one operation are backed out,

  1002 ** but the transaction is not rolled back.  FAIL processing means that

  1003 ** the operation in progress stops and returns an error code.  But prior

  1004 ** changes due to the same operation are not backed out and no rollback

  1005 ** occurs.  IGNORE means that the particular row that caused the constraint

  1006 ** error is not inserted or updated.  Processing continues and no error

  1007 ** is returned.  REPLACE means that preexisting database rows that caused

  1008 ** a UNIQUE constraint violation are removed so that the new insert or

  1009 ** update can proceed.  Processing continues and no error is reported.

  1010 **

  1011 ** RESTRICT, SETNULL, and CASCADE actions apply only to foreign keys.

  1012 ** RESTRICT is the same as ABORT for IMMEDIATE foreign keys and the

  1013 ** same as ROLLBACK for DEFERRED keys.  SETNULL means that the foreign

  1014 ** key is set to NULL.  CASCADE means that a DELETE or UPDATE of the

  1015 ** referenced table row is propagated into the row that holds the

  1016 ** foreign key.

  1017 ** 

  1018 ** The following symbolic values are used to record which type

  1019 ** of action to take.

  1020 */

  1021 #define OE_None     0   /* There is no constraint to check */

  1022 #define OE_Rollback 1   /* Fail the operation and rollback the transaction */

  1023 #define OE_Abort    2   /* Back out changes but do no rollback transaction */

  1024 #define OE_Fail     3   /* Stop the operation but leave all prior changes */

  1025 #define OE_Ignore   4   /* Ignore the error. Do not do the INSERT or UPDATE */

  1026 #define OE_Replace  5   /* Delete existing record, then do INSERT or UPDATE */

  1027 

  1028 #define OE_Restrict 6   /* OE_Abort for IMMEDIATE, OE_Rollback for DEFERRED */

  1029 #define OE_SetNull  7   /* Set the foreign key value to NULL */

  1030 #define OE_SetDflt  8   /* Set the foreign key value to its default */

  1031 #define OE_Cascade  9   /* Cascade the changes */

  1032 

  1033 #define OE_Default  99  /* Do whatever the default action is */

  1034 

  1035 

  1036 /*

  1037 ** An instance of the following structure is passed as the first

  1038 ** argument to sqlite3VdbeKeyCompare and is used to control the 

  1039 ** comparison of the two index keys.

  1040 **

  1041 ** If the KeyInfo.incrKey value is true and the comparison would

  1042 ** otherwise be equal, then return a result as if the second key

  1043 ** were larger.

  1044 */

  1045 struct KeyInfo {

  1046   sqlite3 *db;        /* The database connection */

  1047   u8 enc;             /* Text encoding - one of the TEXT_Utf* values */

  1048   u8 incrKey;         /* Increase 2nd key by epsilon before comparison */

  1049   u8 prefixIsEqual;   /* Treat a prefix as equal */

  1050   int nField;         /* Number of entries in aColl[] */

  1051   u8 *aSortOrder;     /* If defined an aSortOrder[i] is true, sort DESC */

  1052   CollSeq *aColl[1];  /* Collating sequence for each term of the key */

  1053 };

  1054 

  1055 /*

  1056 ** Each SQL index is represented in memory by an

  1057 ** instance of the following structure.

  1058 **

  1059 ** The columns of the table that are to be indexed are described

  1060 ** by the aiColumn[] field of this structure.  For example, suppose

  1061 ** we have the following table and index:

  1062 **

  1063 **     CREATE TABLE Ex1(c1 int, c2 int, c3 text);

  1064 **     CREATE INDEX Ex2 ON Ex1(c3,c1);

  1065 **

  1066 ** In the Table structure describing Ex1, nCol==3 because there are

  1067 ** three columns in the table.  In the Index structure describing

  1068 ** Ex2, nColumn==2 since 2 of the 3 columns of Ex1 are indexed.

  1069 ** The value of aiColumn is {2, 0}.  aiColumn[0]==2 because the 

  1070 ** first column to be indexed (c3) has an index of 2 in Ex1.aCol[].

  1071 ** The second column to be indexed (c1) has an index of 0 in

  1072 ** Ex1.aCol[], hence Ex2.aiColumn[1]==0.

  1073 **

  1074 ** The Index.onError field determines whether or not the indexed columns

  1075 ** must be unique and what to do if they are not.  When Index.onError=OE_None,

  1076 ** it means this is not a unique index.  Otherwise it is a unique index

  1077 ** and the value of Index.onError indicate the which conflict resolution 

  1078 ** algorithm to employ whenever an attempt is made to insert a non-unique

  1079 ** element.

  1080 */

  1081 struct Index {

  1082   char *zName;     /* Name of this index */

  1083   int nColumn;     /* Number of columns in the table used by this index */

  1084   int *aiColumn;   /* Which columns are used by this index.  1st is 0 */

  1085   unsigned *aiRowEst; /* Result of ANALYZE: Est. rows selected by each column */

  1086   Table *pTable;   /* The SQL table being indexed */

  1087   int tnum;        /* Page containing root of this index in database file */

  1088   u8 onError;      /* OE_Abort, OE_Ignore, OE_Replace, or OE_None */

  1089   u8 autoIndex;    /* True if is automatically created (ex: by UNIQUE) */

  1090   char *zColAff;   /* String defining the affinity of each column */

  1091   Index *pNext;    /* The next index associated with the same table */

  1092   Schema *pSchema; /* Schema containing this index */

  1093   u8 *aSortOrder;  /* Array of size Index.nColumn. True==DESC, False==ASC */

  1094   char **azColl;   /* Array of collation sequence names for index */

  1095 };

  1096 

  1097 /*

  1098 ** Each token coming out of the lexer is an instance of

  1099 ** this structure.  Tokens are also used as part of an expression.

  1100 **

  1101 ** Note if Token.z==0 then Token.dyn and Token.n are undefined and

  1102 ** may contain random values.  Do not make any assuptions about Token.dyn

  1103 ** and Token.n when Token.z==0.

  1104 */

  1105 struct Token {

  1106   const unsigned char *z; /* Text of the token.  Not NULL-terminated! */

  1107   unsigned dyn  : 1;      /* True for malloced memory, false for static */

  1108   unsigned n    : 31;     /* Number of characters in this token */

  1109 };

  1110 

  1111 /*

  1112 ** An instance of this structure contains information needed to generate

  1113 ** code for a SELECT that contains aggregate functions.

  1114 **

  1115 ** If Expr.op==TK_AGG_COLUMN or TK_AGG_FUNCTION then Expr.pAggInfo is a

  1116 ** pointer to this structure.  The Expr.iColumn field is the index in

  1117 ** AggInfo.aCol[] or AggInfo.aFunc[] of information needed to generate

  1118 ** code for that node.

  1119 **

  1120 ** AggInfo.pGroupBy and AggInfo.aFunc.pExpr point to fields within the

  1121 ** original Select structure that describes the SELECT statement.  These

  1122 ** fields do not need to be freed when deallocating the AggInfo structure.

  1123 */

  1124 struct AggInfo {

  1125   u8 directMode;          /* Direct rendering mode means take data directly

  1126                           ** from source tables rather than from accumulators */

  1127   u8 useSortingIdx;       /* In direct mode, reference the sorting index rather

  1128                           ** than the source table */

  1129   int sortingIdx;         /* Cursor number of the sorting index */

  1130   ExprList *pGroupBy;     /* The group by clause */

  1131   int nSortingColumn;     /* Number of columns in the sorting index */

  1132   struct AggInfo_col {    /* For each column used in source tables */

  1133     Table *pTab;             /* Source table */

  1134     int iTable;              /* Cursor number of the source table */

  1135     int iColumn;             /* Column number within the source table */