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.529 2006/09/23 20:36:02 drh Exp $

    15 */

    16 #ifndef _SQLITEINT_H_

    17 #define _SQLITEINT_H_

    18 

    19 #include <e32def.h>

    20 /*

    21 ** Extra interface definitions for those who need them

    22 */

    23 #ifdef SQLITE_EXTRA

    24 # include "sqliteExtra.h"

    25 #endif

    26 

    27 /*

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

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

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

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

    32 ** feature.

    33 */

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

    35 # define NDEBUG 1

    36 #endif

    37 

    38 /*

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

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

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

    42 **

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

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

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

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

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

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

    49 ** portability you should omit LFS.

    50 **

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

    52 */

    53 #ifndef SQLITE_DISABLE_LFS

    54 # define _LARGE_FILE       1

    55 # ifndef _FILE_OFFSET_BITS

    56 #   define _FILE_OFFSET_BITS 64

    57 # endif

    58 # define _LARGEFILE_SOURCE 1

    59 #endif

    60 

    61 #include "sqlite3.h"

    62 #include "hash.h"

    63 #include "parse.h"

    64 #include <stdio.h>

    65 #include <stdlib.h>

    66 #include <string.h>

    67 #include <assert.h>

    68 #include <libc/stddef.h>

    69 

    70 /*

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

    72 ** substitute integer for floating-point

    73 */

    74 #ifdef SQLITE_OMIT_FLOATING_POINT

    75 # define double sqlite_int64

    76 # define LONGDOUBLE_TYPE sqlite_int64

    77 # ifndef SQLITE_BIG_DBL

    78 #   define SQLITE_BIG_DBL (0x7fffffffffffffff)

    79 # endif

    80 # define SQLITE_OMIT_DATETIME_FUNCS 1

    81 # define SQLITE_OMIT_TRACE 1

    82 #endif

    83 #ifndef SQLITE_BIG_DBL

    84 # define SQLITE_BIG_DBL (1e99)

    85 #endif

    86 

    87 /*

    88 ** The maximum number of in-memory pages to use for the main database

    89 ** table and for temporary tables. Internally, the MAX_PAGES and 

    90 ** TEMP_PAGES macros are used. To override the default values at

    91 ** compilation time, the SQLITE_DEFAULT_CACHE_SIZE and 

    92 ** SQLITE_DEFAULT_TEMP_CACHE_SIZE macros should be set.

    93 */

    94 #ifdef SQLITE_DEFAULT_CACHE_SIZE

    95 # define MAX_PAGES SQLITE_DEFAULT_CACHE_SIZE

    96 #else

    97 # define MAX_PAGES   2000

    98 #endif

    99 #ifdef SQLITE_DEFAULT_TEMP_CACHE_SIZE

   100 # define TEMP_PAGES SQLITE_DEFAULT_TEMP_CACHE_SIZE

   101 #else

   102 # define TEMP_PAGES   500

   103 #endif

   104 

   105 /*

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

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

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

   109 */

   110 #ifdef SQLITE_OMIT_TEMPDB

   111 #define OMIT_TEMPDB 1

   112 #else

   113 #define OMIT_TEMPDB 0

   114 #endif

   115 

   116 /*

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

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

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

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

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

   122 **

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

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

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

   126 ** work.

   127 */

   128 #define NULL_DISTINCT_FOR_UNIQUE 1

   129 

   130 /*

   131 ** The maximum number of attached databases.  This must be at least 2

   132 ** in order to support the main database file (0) and the file used to

   133 ** hold temporary tables (1).  And it must be less than 32 because

   134 ** we use a bitmask of databases with a u32 in places (for example

   135 ** the Parse.cookieMask field).

   136 */

   137 #define MAX_ATTACHED 10

   138 

   139 /*

   140 ** The maximum value of a ?nnn wildcard that the parser will accept.

   141 */

   142 #define SQLITE_MAX_VARIABLE_NUMBER 999

   143 

   144 /*

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

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

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

   148 ** that the library can read.

   149 */

   150 #define SQLITE_MAX_FILE_FORMAT 4

   151 #ifndef SQLITE_DEFAULT_FILE_FORMAT

   152 # define SQLITE_DEFAULT_FILE_FORMAT 1

   153 #endif

   154 

   155 /*

   156 ** Provide a default value for TEMP_STORE in case it is not specified

   157 ** on the command-line

   158 */

   159 #ifndef TEMP_STORE

   160 # define TEMP_STORE 1

   161 #endif

   162 

   163 /*

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

   165 ** ourselves.

   166 */

   167 #ifndef offsetof

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

   169 #endif

   170 

   171 /*

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

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

   174 */

   175 #if 'A' == '\301'

   176 # define SQLITE_EBCDIC 1

   177 #else

   178 # define SQLITE_ASCII 1

   179 #endif

   180 

   181 /*

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

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

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

   185 **

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

   187 */

   188 #ifndef UINT32_TYPE

   189 # define UINT32_TYPE unsigned int

   190 #endif

   191 #ifndef UINT16_TYPE

   192 # define UINT16_TYPE unsigned short int

   193 #endif

   194 #ifndef INT16_TYPE

   195 # define INT16_TYPE short int

   196 #endif

   197 #ifndef UINT8_TYPE

   198 # define UINT8_TYPE unsigned char

   199 #endif

   200 #ifndef INT8_TYPE

   201 # define INT8_TYPE signed char

   202 #endif

   203 #ifndef LONGDOUBLE_TYPE

   204 # define LONGDOUBLE_TYPE long double

   205 #endif

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

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

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

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

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

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

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

   213 

   214 /*

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

   216 ** evaluated at runtime.

   217 */

   218 extern const int sqlite3one;

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

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

   221 

   222 /*

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

   224 ** callback for a given sqlite handle. 

   225 **

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

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

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

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

   230 */

   231 typedef struct BusyHandler BusyHandler;

   232 struct BusyHandler {

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

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

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

   236 };

   237 

   238 /*

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

   240 ** "BusyHandler typedefs.

   241 */

   242 #include "vdbe.h"

   243 #include "btree.h"

   244 #include "pager.h"

   245 

   246 #ifdef SQLITE_MEMDEBUG

   247 /*

   248 ** The following global variables are used for testing and debugging

   249 ** only.  They only work if SQLITE_MEMDEBUG is defined.

   250 */

   251 extern int sqlite3_nMalloc;      /* Number of sqliteMalloc() calls */

   252 extern int sqlite3_nFree;        /* Number of sqliteFree() calls */

   253 extern int sqlite3_iMallocFail;  /* Fail sqliteMalloc() after this many calls */

   254 extern int sqlite3_iMallocReset; /* Set iMallocFail to this when it reaches 0 */

   255 

   256 extern void *sqlite3_pFirst;         /* Pointer to linked list of allocations */

   257 extern int sqlite3_nMaxAlloc;        /* High water mark of ThreadData.nAlloc */

   258 extern int sqlite3_mallocDisallowed; /* assert() in sqlite3Malloc() if set */

   259 extern int sqlite3_isFail;           /* True if all malloc calls should fail */

   260 extern const char *sqlite3_zFile;    /* Filename to associate debug info with */

   261 extern int sqlite3_iLine;            /* Line number for debug info */

   262 

   263 #define ENTER_MALLOC (sqlite3_zFile = __FILE__, sqlite3_iLine = __LINE__)

   264 #define sqliteMalloc(x)          (ENTER_MALLOC, sqlite3Malloc(x,1))

   265 #define sqliteMallocRaw(x)       (ENTER_MALLOC, sqlite3MallocRaw(x,1))

   266 #define sqliteRealloc(x,y)       (ENTER_MALLOC, sqlite3Realloc(x,y))

   267 #define sqliteStrDup(x)          (ENTER_MALLOC, sqlite3StrDup(x))

   268 #define sqliteStrNDup(x,y)       (ENTER_MALLOC, sqlite3StrNDup(x,y))

   269 #define sqliteReallocOrFree(x,y) (ENTER_MALLOC, sqlite3ReallocOrFree(x,y))

   270 

   271 #else

   272 

   273 #define ENTER_MALLOC 0

   274 #define sqliteMalloc(x)          sqlite3Malloc(x,1)

   275 #define sqliteMallocRaw(x)       sqlite3MallocRaw(x,1)

   276 #define sqliteRealloc(x,y)       sqlite3Realloc(x,y)

   277 #define sqliteStrDup(x)          sqlite3StrDup(x)

   278 #define sqliteStrNDup(x,y)       sqlite3StrNDup(x,y)

   279 #define sqliteReallocOrFree(x,y) sqlite3ReallocOrFree(x,y)

   280 

   281 #endif

   282 

   283 #define sqliteFree(x)          sqlite3FreeX(x)

   284 #define sqliteAllocSize(x)     sqlite3AllocSize(x)

   285 

   286 

   287 /*

   288 ** An instance of this structure might be allocated to store information

   289 ** specific to a single thread.

   290 */

   291 struct ThreadData {

   292   int dummy;               /* So that this structure is never empty */

   293 

   294 #ifdef SQLITE_ENABLE_MEMORY_MANAGEMENT

   295   int nSoftHeapLimit;      /* Suggested max mem allocation.  No limit if <0 */

   296   int nAlloc;              /* Number of bytes currently allocated */

   297   Pager *pPager;           /* Linked list of all pagers in this thread */

   298 #endif

   299 

   300 #ifndef SQLITE_OMIT_SHARED_CACHE

   301   u8 useSharedData;        /* True if shared pagers and schemas are enabled */

   302   BtShared *pBtree;        /* Linked list of all currently open BTrees */

   303 #endif

   304 };

   305 

   306 /*

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

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

   309 ** user tables and indices.

   310 */

   311 #define MASTER_NAME       "sqlite_master"

   312 #define TEMP_MASTER_NAME  "sqlite_temp_master"

   313 

   314 /*

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

   316 */

   317 #define MASTER_ROOT       1

   318 

   319 /*

   320 ** The name of the schema table.

   321 */

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

   323 

   324 /*

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

   326 ** an array.

   327 */

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

   329 

   330 /*

   331 ** Forward references to structures

   332 */

   333 typedef struct AggInfo AggInfo;

   334 typedef struct AuthContext AuthContext;

   335 typedef struct CollSeq CollSeq;

   336 typedef struct Column Column;

   337 typedef struct Db Db;

   338 typedef struct Schema Schema;

   339 typedef struct Expr Expr;

   340 typedef struct ExprList ExprList;

   341 typedef struct FKey FKey;

   342 typedef struct FuncDef FuncDef;

   343 typedef struct IdList IdList;

   344 typedef struct Index Index;

   345 typedef struct KeyClass KeyClass;

   346 typedef struct KeyInfo KeyInfo;

   347 typedef struct Module Module;

   348 typedef struct NameContext NameContext;

   349 typedef struct Parse Parse;

   350 typedef struct Select Select;

   351 typedef struct SrcList SrcList;

   352 typedef struct ThreadData ThreadData;

   353 typedef struct Table Table;

   354 typedef struct TableLock TableLock;

   355 typedef struct Token Token;

   356 typedef struct TriggerStack TriggerStack;

   357 typedef struct TriggerStep TriggerStep;

   358 typedef struct Trigger Trigger;

   359 typedef struct WhereInfo WhereInfo;

   360 typedef struct WhereLevel WhereLevel;

   361 

   362 /*

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

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

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

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

   367 ** databases may be attached.

   368 */

   369 struct Db {

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

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

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

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

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

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

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

   377 };

   378 

   379 /*

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

   381 */

   382 struct Schema {

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

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

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

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

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

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

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

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

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

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

   393 };

   394 

   395 /*

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

   397 ** Db.flags field.

   398 */

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

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

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

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

   403 

   404 /*

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

   406 **

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

   408 ** read into internal hash tables.

   409 **

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

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

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

   413 */

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

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

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

   417 

   418 #define SQLITE_UTF16NATIVE (SQLITE_BIGENDIAN?SQLITE_UTF16BE:SQLITE_UTF16LE)

   419 

   420 /*

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

   422 **

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

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

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

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

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

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

   429 **

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

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

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

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

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

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

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

   437 ** affect the value of lsChange.

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

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

   440 **

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

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

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

   444 ** consistently.

   445 */

   446 struct sqlite3 {

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

   448   Db *aDb;                      /* All backends */

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   464   } init;

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

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

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

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

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

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

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

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

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

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

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

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

   477   void *pUpdateArg;

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

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

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

   481   void *pCollNeededArg;

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

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

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

   485   union {

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

   487     double notUsed1;            /* Spacer */

   488   } u1;

   489 #ifndef SQLITE_OMIT_AUTHORIZATION

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

   491                                 /* Access authorization function */

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

   493 #endif

   494 #ifndef SQLITE_OMIT_PROGRESS_CALLBACK

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

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

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

   498 #endif

   499 #ifndef SQLITE_OMIT_VIRTUALTABLE

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

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

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

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

   504 #endif

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

   506   Hash aCollSeq;                /* All collating sequences */

   507   BusyHandler busyHandler;      /* Busy callback */

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

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

   510 #ifdef SQLITE_SSE

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

   512 #endif

   513 };

   514 

   515 /*

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

   517 */

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

   519 

   520 /*

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

   522 **

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

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

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

   526 */

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

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

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

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

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

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

   533                                           /*   DELETE, or UPDATE and return */

   534                                           /*   the count using a callback. */

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

   536                                           /*   result set is empty */

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

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

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

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

   541                                           ** accessing read-only databases */

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

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

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

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

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

   547 

   548 /*

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

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

   551 ** than being distinct from one another.

   552 */

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

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

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

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

   557 

   558 /*

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

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

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

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

   563 */

   564 struct FuncDef {

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

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

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

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

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

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

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

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

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

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

   575 };

   576 

   577 /*

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

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

   580 ** hash table.

   581 */

   582 struct Module {

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

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

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

   586 };

   587 

   588 /*

   589 ** Possible values for FuncDef.flags

   590 */

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

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

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

   594 

   595 /*

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

   597 ** of this structure.

   598 */

   599 struct Column {

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

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

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

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

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

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

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

   607 };

   608 

   609 /*

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

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

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

   613 **

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

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

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

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

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

   619 ** translations, if any.

   620 **

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

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

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

   624 ** xCmp16.

   625 **

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

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

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

   629 */

   630 struct CollSeq {

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

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

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

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

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

   636 };

   637 

   638 /*

   639 ** Allowed values of CollSeq flags:

   640 */

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

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

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

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

   645 

   646 /*

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

   648 */

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

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

   651 

   652 /*

   653 ** Column affinity types.

   654 **

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

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

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

   658 **

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

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

   661 ** used as the P3 operand, they will be more readable.

   662 **

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

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

   665 */

   666 #define SQLITE_AFF_TEXT     'a'

   667 #define SQLITE_AFF_NONE     'b'

   668 #define SQLITE_AFF_NUMERIC  'c'

   669 #define SQLITE_AFF_INTEGER  'd'

   670 #define SQLITE_AFF_REAL     'e'

   671 

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

   673 

   674 /*

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

   676 ** following structure.

   677 **

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

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

   680 ** comparisons.

   681 **

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

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

   684 **

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

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

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

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

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

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

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

   692 **

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

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

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

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

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

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

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

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

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

   702 ** of a SELECT statement.

   703 */

   704 struct Table {

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

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

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

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

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

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

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

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

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

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

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

   716 #ifndef SQLITE_OMIT_CHECK

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

   718 #endif

   719 #ifndef SQLITE_OMIT_ALTERTABLE

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

   721 #endif

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

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

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

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

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

   727 #ifndef SQLITE_OMIT_VIRTUALTABLE

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

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

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

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

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

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

   734 #endif

   735   Schema *pSchema;

   736 };

   737 

   738 /*

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

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

   741 ** table support is omitted from the build.

   742 */

   743 #ifndef SQLITE_OMIT_VIRTUALTABLE

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

   745 #else

   746 #  define IsVirtual(X) 0

   747 #endif

   748 

   749 /*

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

   751 **

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

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

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

   755 ** Consider this example:

   756 **

   757 **     CREATE TABLE ex1(

   758 **       a INTEGER PRIMARY KEY,

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

   760 **     );

   761 **

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

   763 **

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

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

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

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

   768 **

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

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

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

   772 ** field.

   773 */

   774 struct FKey {

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

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

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

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

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

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

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

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

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

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

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

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

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

   788 };

   789 

   790 /*

   791 ** SQLite supports many different ways to resolve a contraint

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

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

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

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

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

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

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

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

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

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

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

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

   804 **

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

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

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

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

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

   810 ** foreign key.

   811 ** 

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

   813 ** of action to take.

   814 */

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

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

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

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

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

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

   821 

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

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

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

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

   826 

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

   828 

   829 

   830 /*

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

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

   833 ** comparison of the two index keys.

   834 **

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

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

   837 ** were larger.

   838 */

   839 struct KeyInfo {

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

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

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

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

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

   845 };

   846 

   847 /*

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

   849 ** instance of the following structure.

   850 **

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

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

   853 ** we have the following table and index:

   854 **

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

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

   857 **

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

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

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

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

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

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

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

   865 **

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

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

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

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

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

   871 ** element.

   872 */

   873 struct Index {

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

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

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

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

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

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

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

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

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

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

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

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

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

   887 };

   888 

   889 /*

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

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

   892 **

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

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

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

   896 */

   897 struct Token {

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

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

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

   901 };

   902 

   903 /*

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

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

   906 **

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

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

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

   910 ** code for that node.

   911 **

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

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

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

   915 */

   916 struct AggInfo {

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

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

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

   920                           ** than the source table */

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

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

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

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

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

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

   927     int iSorterColumn;       /* Column number in the sorting index */

   928     int iMem;                /* Memory location that acts as accumulator */

   929     Expr *pExpr;             /* The original expression */

   930   } *aCol;

   931   int nColumn;            /* Number of used entries in aCol[] */

   932   int nColumnAlloc;       /* Number of slots allocated for aCol[] */

   933   int nAccumulator;       /* Number of columns that show through to the output.

   934                           ** Additional columns are used only as parameters to

   935                           ** aggregate functions */

   936   struct AggInfo_func {   /* For each aggregate function */

   937     Expr *pExpr;             /* Expression encoding the function */

   938     FuncDef *pFunc;          /* The aggregate function implementation */

   939     int iMem;                /* Memory location that acts as accumulator */

   940     int iDistinct;           /* Ephermeral table used to enforce DISTINCT */

   941   } *aFunc;

   942   int nFunc;              /* Number of entries in aFunc[] */

   943   int nFuncAlloc;         /* Number of slots allocated for aFunc[] */

   944 };

   945 

   946 /*

   947 ** Each node of an expression in the parse tree is an instance

   948 ** of this structure.

   949 **

   950 ** Expr.op is the opcode.  The integer parser token codes are reused

   951 ** as opcodes here.  For example, the parser defines TK_GE to be an integer

   952 ** code representing the ">=" operator.  This same integer code is reused

   953 ** to represent the greater-than-or-equal-to operator in the expression

   954 ** tree.

   955 **

   956 ** Expr.pRight and Expr.pLeft are subexpressions.  Expr.pList is a list

   957 ** of argument if the expression is a function.

   958 **

   959 ** Expr.token is the operator token for this node.  For some expressions

   960 ** that have subexpressions, Expr.token can be the complete text that gave

   961 ** rise to the Expr.  In the latter case, the token is marked as being

   962 ** a compound token.

   963 **

   964 ** An expression of the form ID or ID.ID refers to a column in a table.

   965 ** For such expressions, Expr.op is set to TK_COLUMN and Expr.iTable is

   966 ** the integer cursor number of a VDBE cursor pointing to that table and

   967 ** Expr.iColumn is the column number for the specific column.  If the

   968 ** expression is used as a result in an aggregate SELECT, then the

   969 ** value is also stored in the Expr.iAgg column in the aggregate so that

   970 ** it can be accessed after all aggregates are computed.

   971 **

   972 ** If the expression is a function, the Expr.iTable is an integer code

   973 ** representing which function.  If the expression is an unbound variable

   974 ** marker (a question mark character '?' in the original SQL) then the

   975 ** Expr.iTable holds the index number for that variable.

   976 **

   977 ** If the expression is a subquery then Expr.iColumn holds an integer

   978 ** register number containing the result of the subquery.  If the

   979 ** subquery gives a constant result, then iTable is -1.  If the subquery

   980 ** gives a different answer at different times during statement processing

   981 ** then iTable is the address of a subroutine that computes the subquery.

   982 **

   983 ** The Expr.pSelect field points to a SELECT statement.  The SELECT might

   984 ** be the right operand of an IN operator.  Or, if a scalar SELECT appears

   985 ** in an expression the opcode is TK_SELECT and Expr.pSelect is the only

   986 ** operand.

   987 **

   988 ** If the Expr is of type OP_Column, and the table it is selecting from

   989 ** is a disk table or the "old.*" pseudo-table, then pTab points to the

   990 ** corresponding table definition.

   991 */

   992 struct Expr {

   993   u8 op;                 /* Operation performed by this node */

   994   char affinity;         /* The affinity of the column or 0 if not a column */

   995   u16 flags;             /* Various flags.  See below */

   996   CollSeq *pColl;        /* The collation type of the column or 0 */

   997   Expr *pLeft, *pRight;  /* Left and right subnodes */

   998   ExprList *pList;       /* A list of expressions used as function arguments

   999                          ** or in "<expr> IN (<expr-list)" */

  1000   Token token;           /* An operand token */

  1001   Token span;            /* Complete text of the expression */

  1002   int iTable, iColumn;   /* When op==TK_COLUMN, then this expr node means the

  1003                          ** iColumn-th field of the iTable-th table. */

  1004   AggInfo *pAggInfo;     /* Used by TK_AGG_COLUMN and TK_AGG_FUNCTION */

  1005   int iAgg;              /* Which entry in pAggInfo->aCol[] or ->aFunc[] */

  1006   int iRightJoinTable;   /* If EP_FromJoin, the right table of the join */

  1007   Select *pSelect;       /* When the expression is a sub-select.  Also the

  1008                          ** right side of "<expr> IN (<select>)" */

  1009   Table *pTab;           /* Table for OP_Column expressions. */

  1010   Schema *pSchema;

  1011 };

  1012 

  1013 /*

  1014 ** The following are the meanings of bits in the Expr.flags field.

  1015 */

  1016 #define EP_FromJoin     0x01  /* Originated in ON or USING clause of a join */

  1017 #define EP_Agg          0x02  /* Contains one or more aggregate functions */

  1018 #define EP_Resolved     0x04  /* IDs have been resolved to COLUMNs */

  1019 #define EP_Error        0x08  /* Expression contains one or more errors */

  1020 #define EP_Distinct     0x10  /* Aggregate function with DISTINCT keyword */

  1021 #define EP_VarSelect    0x20  /* pSelect is correlated, not constant */

  1022 #define EP_Dequoted     0x40  /* True if the string has been dequoted */

  1023 #define EP_InfixFunc    0x80  /* True for an infix function: LIKE, GLOB, etc */

  1024 

  1025 /*

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

  1027 ** Expr.flags field.

  1028 */

  1029 #define ExprHasProperty(E,P)     (((E)->flags&(P))==(P))

  1030 #define ExprHasAnyProperty(E,P)  (((E)->flags&(P))!=0)

  1031 #define ExprSetProperty(E,P)     (E)->flags|=(P)

  1032 #define ExprClearProperty(E,P)   (E)->flags&=~(P)

  1033 

  1034 /*

  1035 ** A list of expressions.  Each expression may optionally have a

  1036 ** name.  An expr/name combination can be used in several ways, such

  1037 ** as the list of "expr AS ID" fields following a "SELECT" or in the

  1038 ** list of "ID = expr" items in an UPDATE.  A list of expressions can

  1039 ** also be used as the argument to a function, in which case the a.zName

  1040 ** field is not used.

  1041 */

  1042 struct ExprList {

  1043   int nExpr;             /* Number of expressions on the list */

  1044   int nAlloc;            /* Number of entries allocated below */

  1045   int iECursor;          /* VDBE Cursor associated with this ExprList */

  1046   struct ExprList_item {

  1047     Expr *pExpr;           /* The list of expressions */

  1048     char *zName;           /* Token associated with this expression */

  1049     u8 sortOrder;          /* 1 for DESC or 0 for ASC */

  1050     u8 isAgg;              /* True if this is an aggregate like count(*) */

  1051     u8 done;               /* A flag to indicate when processing is finished */

  1052   } *a;                  /* One entry for each expression */

  1053 };

  1054 

  1055 /*

  1056 ** An instance of this structure can hold a simple list of identifiers,

  1057 ** such as the list "a,b,c" in the following statements:

  1058 **

  1059 **      INSERT INTO t(a,b,c) VALUES ...;

  1060 **      CREATE INDEX idx ON t(a,b,c);

  1061 **      CREATE TRIGGER trig BEFORE UPDATE ON t(a,b,c) ...;

  1062 **

  1063 ** The IdList.a.idx field is used when the IdList represents the list of

  1064 ** column names after a table name in an INSERT statement.  In the statement

  1065 **

  1066 **     INSERT INTO t(a,b,c) ...

  1067 **

  1068 ** If "a" is the k-th column of table "t", then IdList.a[0].idx==k.

  1069 */

  1070 struct IdList {

  1071   struct IdList_item {

  1072     char *zName;      /* Name of the identifier */

  1073     int idx;          /* Index in some Table.aCol[] of a column named zName */

  1074   } *a;

  1075   int nId;         /* Number of identifiers on the list */

  1076   int nAlloc;      /* Number of entries allocated for a[] below */

  1077 };

  1078 

  1079 /*

  1080 ** The bitmask datatype defined below is used for various optimizations.

  1081 */

  1082 typedef unsigned int Bitmask;

  1083 

  1084 /*

  1085 ** The following structure describes the FROM clause of a SELECT statement.

  1086 ** Each table or subquery in the FROM clause is a separate element of

  1087 ** the SrcList.a[] array.

  1088 **

  1089 ** With the addition of multiple database support, the following structure

  1090 ** can also be used to describe a particular table such as the table that

  1091 ** is modified by an INSERT, DELETE, or UPDATE statement.  In standard SQL,

  1092 ** such a table must be a simple name: ID.  But in SQLite, the table can

  1093 ** now be identified by a database name, a dot, then the table name: ID.ID.

  1094 */

  1095 struct SrcList {

  1096   i16 nSrc;        /* Number of tables or subqueries in the FROM clause */

  1097   i16 nAlloc;      /* Number of entries allocated in a[] below */

  1098   struct SrcList_item {

  1099     char *zDatabase;  /* Name of database holding this table */

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

  1101     char *zAlias;     /* The "B" part of a "A AS B" phrase.  zName is the "A" */

  1102     Table *pTab;      /* An SQL table corresponding to zName */

  1103     Select *pSelect;  /* A SELECT statement used in place of a table name */

  1104     u8 isPopulated;   /* Temporary table associated with SELECT is populated */

  1105     u8 jointype;      /* Type of join between this table and the next */

  1106     i16 iCursor;      /* The VDBE cursor number used to access this table */

  1107     Expr *pOn;        /* The ON clause of a join */

  1108     IdList *pUsing;   /* The USING clause of a join */

  1109     Bitmask colUsed;  /* Bit N (1<<N) set if column N or pTab is used */

  1110   } a[1];             /* One entry for each identifier on the list */

  1111 };

  1112 

  1113 /*

  1114 ** Permitted values of the SrcList.a.jointype field

  1115 */

  1116 #define JT_INNER     0x0001    /* Any kind of inner or cross join */

  1117 #define JT_CROSS     0x0002    /* Explicit use of the CROSS keyword */

  1118 #define JT_NATURAL   0x0004    /* True for a "natural" join */

  1119 #define JT_LEFT      0x0008    /* Left outer join */

  1120 #define JT_RIGHT     0x0010    /* Right outer join */

  1121 #define JT_OUTER     0x0020    /* The "OUTER" keyword is present */

  1122 #define JT_ERROR     0x0040    /* unknown or unsupported join type */

  1123 

  1124 /*

  1125 ** For each nested loop in a WHERE clause implementation, the WhereInfo

  1126 ** structure contains a single instance of this structure.  This structure

  1127 ** is intended to be private the the where.c module and should not be

  1128 ** access or modified by other modules.

  1129 **

  1130 ** The pIdxInfo and pBestIdx fields are used to help pick the best

  1131 ** index on a virtual table.  The pIdxInfo pointer contains indexing

  1132 ** information for the i-th table in the FROM clause before reordering.

  1133 ** All the pIdxInfo pointers are freed by whereInfoFree() in where.c.

  1134 ** The pBestIdx pointer is a copy of pIdxInfo for the i-th table after