1 /* 2 ** 2003 September 6 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 ** This is the header file for information that is private to the 13 ** VDBE. This information used to all be at the top of the single 14 ** source code file "vdbe.c". When that file became too big (over 15 ** 6000 lines long) it was split up into several smaller files and 16 ** this header information was factored out. 17 */ 18 19 /* 20 ** When converting from the native format to the key format and back 21 ** again, in addition to changing the byte order we invert the high-order 22 ** bit of the most significant byte. This causes negative numbers to 23 ** sort before positive numbers in the memcmp() function. 24 */ 25 #define keyToInt(X) (sqliteVdbeByteSwap(X) ^ 0x80000000) 26 #define intToKey(X) (sqliteVdbeByteSwap((X) ^ 0x80000000)) 27 28 /* 29 ** The makefile scans this source file and creates the following 30 ** array of string constants which are the names of all VDBE opcodes. 31 ** This array is defined in a separate source code file named opcode.c 32 ** which is automatically generated by the makefile. 33 */ 34 extern char *sqliteOpcodeNames[]; 35 36 /* 37 ** SQL is translated into a sequence of instructions to be 38 ** executed by a virtual machine. Each instruction is an instance 39 ** of the following structure. 40 */ 41 typedef struct VdbeOp Op; 42 43 /* 44 ** Boolean values 45 */ 46 typedef unsigned char Bool; 47 48 /* 49 ** A cursor is a pointer into a single BTree within a database file. 50 ** The cursor can seek to a BTree entry with a particular key, or 51 ** loop over all entries of the Btree. You can also insert new BTree 52 ** entries or retrieve the key or data from the entry that the cursor 53 ** is currently pointing to. 54 ** 55 ** Every cursor that the virtual machine has open is represented by an 56 ** instance of the following structure. 57 ** 58 ** If the Cursor.isTriggerRow flag is set it means that this cursor is 59 ** really a single row that represents the NEW or OLD pseudo-table of 60 ** a row trigger. The data for the row is stored in Cursor.pData and 61 ** the rowid is in Cursor.iKey. 62 */ 63 struct Cursor { 64 BtCursor *pCursor; /* The cursor structure of the backend */ 65 int lastRecno; /* Last recno from a Next or NextIdx operation */ 66 int nextRowid; /* Next rowid returned by OP_NewRowid */ 67 Bool recnoIsValid; /* True if lastRecno is valid */ 68 Bool keyAsData; /* The OP_Column command works on key instead of data */ 69 Bool atFirst; /* True if pointing to first entry */ 70 Bool useRandomRowid; /* Generate new record numbers semi-randomly */ 71 Bool nullRow; /* True if pointing to a row with no data */ 72 Bool nextRowidValid; /* True if the nextRowid field is valid */ 73 Bool pseudoTable; /* This is a NEW or OLD pseudo-tables of a trigger */ 74 Bool deferredMoveto; /* A call to sqliteBtreeMoveto() is needed */ 75 int movetoTarget; /* Argument to the deferred sqliteBtreeMoveto() */ 76 Btree *pBt; /* Separate file holding temporary table */ 77 int nData; /* Number of bytes in pData */ 78 char *pData; /* Data for a NEW or OLD pseudo-table */ 79 int iKey; /* Key for the NEW or OLD pseudo-table row */ 80 }; 81 typedef struct Cursor Cursor; 82 83 /* 84 ** A sorter builds a list of elements to be sorted. Each element of 85 ** the list is an instance of the following structure. 86 */ 87 typedef struct Sorter Sorter; 88 struct Sorter { 89 int nKey; /* Number of bytes in the key */ 90 char *zKey; /* The key by which we will sort */ 91 int nData; /* Number of bytes in the data */ 92 char *pData; /* The data associated with this key */ 93 Sorter *pNext; /* Next in the list */ 94 }; 95 96 /* 97 ** Number of buckets used for merge-sort. 98 */ 99 #define NSORT 30 100 101 /* 102 ** Number of bytes of string storage space available to each stack 103 ** layer without having to malloc. NBFS is short for Number of Bytes 104 ** For Strings. 105 */ 106 #define NBFS 32 107 108 /* 109 ** A single level of the stack or a single memory cell 110 ** is an instance of the following structure. 111 */ 112 struct Mem { 113 int i; /* Integer value */ 114 int n; /* Number of characters in string value, including '\0' */ 115 int flags; /* Some combination of MEM_Null, MEM_Str, MEM_Dyn, etc. */ 116 double r; /* Real value */ 117 char *z; /* String value */ 118 char zShort[NBFS]; /* Space for short strings */ 119 }; 120 typedef struct Mem Mem; 121 122 /* 123 ** Allowed values for Mem.flags 124 */ 125 #define MEM_Null 0x0001 /* Value is NULL */ 126 #define MEM_Str 0x0002 /* Value is a string */ 127 #define MEM_Int 0x0004 /* Value is an integer */ 128 #define MEM_Real 0x0008 /* Value is a real number */ 129 #define MEM_Dyn 0x0010 /* Need to call sqliteFree() on Mem.z */ 130 #define MEM_Static 0x0020 /* Mem.z points to a static string */ 131 #define MEM_Ephem 0x0040 /* Mem.z points to an ephemeral string */ 132 #define MEM_Short 0x0080 /* Mem.z points to Mem.zShort */ 133 134 /* The following MEM_ value appears only in AggElem.aMem.s.flag fields. 135 ** It indicates that the corresponding AggElem.aMem.z points to a 136 ** aggregate function context that needs to be finalized. 137 */ 138 #define MEM_AggCtx 0x0100 /* Mem.z points to an agg function context */ 139 140 /* 141 ** The "context" argument for a installable function. A pointer to an 142 ** instance of this structure is the first argument to the routines used 143 ** implement the SQL functions. 144 ** 145 ** There is a typedef for this structure in sqlite.h. So all routines, 146 ** even the public interface to SQLite, can use a pointer to this structure. 147 ** But this file is the only place where the internal details of this 148 ** structure are known. 149 ** 150 ** This structure is defined inside of vdbe.c because it uses substructures 151 ** (Mem) which are only defined there. 152 */ 153 struct sqlite_func { 154 FuncDef *pFunc; /* Pointer to function information. MUST BE FIRST */ 155 Mem s; /* The return value is stored here */ 156 void *pAgg; /* Aggregate context */ 157 u8 isError; /* Set to true for an error */ 158 u8 isStep; /* Current in the step function */ 159 int cnt; /* Number of times that the step function has been called */ 160 }; 161 162 /* 163 ** An Agg structure describes an Aggregator. Each Agg consists of 164 ** zero or more Aggregator elements (AggElem). Each AggElem contains 165 ** a key and one or more values. The values are used in processing 166 ** aggregate functions in a SELECT. The key is used to implement 167 ** the GROUP BY clause of a select. 168 */ 169 typedef struct Agg Agg; 170 typedef struct AggElem AggElem; 171 struct Agg { 172 int nMem; /* Number of values stored in each AggElem */ 173 AggElem *pCurrent; /* The AggElem currently in focus */ 174 HashElem *pSearch; /* The hash element for pCurrent */ 175 Hash hash; /* Hash table of all aggregate elements */ 176 FuncDef **apFunc; /* Information about aggregate functions */ 177 }; 178 struct AggElem { 179 char *zKey; /* The key to this AggElem */ 180 int nKey; /* Number of bytes in the key, including '\0' at end */ 181 Mem aMem[1]; /* The values for this AggElem */ 182 }; 183 184 /* 185 ** A Set structure is used for quick testing to see if a value 186 ** is part of a small set. Sets are used to implement code like 187 ** this: 188 ** x.y IN ('hi','hoo','hum') 189 */ 190 typedef struct Set Set; 191 struct Set { 192 Hash hash; /* A set is just a hash table */ 193 HashElem *prev; /* Previously accessed hash elemen */ 194 }; 195 196 /* 197 ** A Keylist is a bunch of keys into a table. The keylist can 198 ** grow without bound. The keylist stores the ROWIDs of database 199 ** records that need to be deleted or updated. 200 */ 201 typedef struct Keylist Keylist; 202 struct Keylist { 203 int nKey; /* Number of slots in aKey[] */ 204 int nUsed; /* Next unwritten slot in aKey[] */ 205 int nRead; /* Next unread slot in aKey[] */ 206 Keylist *pNext; /* Next block of keys */ 207 int aKey[1]; /* One or more keys. Extra space allocated as needed */ 208 }; 209 210 /* 211 ** A Context stores the last insert rowid, the last statement change count, 212 ** and the current statement change count (i.e. changes since last statement). 213 ** Elements of Context structure type make up the ContextStack, which is 214 ** updated by the ContextPush and ContextPop opcodes (used by triggers) 215 */ 216 typedef struct Context Context; 217 struct Context { 218 int lastRowid; /* Last insert rowid (from db->lastRowid) */ 219 int lsChange; /* Last statement change count (from db->lsChange) */ 220 int csChange; /* Current statement change count (from db->csChange) */ 221 }; 222 223 /* 224 ** An instance of the virtual machine. This structure contains the complete 225 ** state of the virtual machine. 226 ** 227 ** The "sqlite_vm" structure pointer that is returned by sqlite_compile() 228 ** is really a pointer to an instance of this structure. 229 */ 230 struct Vdbe { 231 sqlite *db; /* The whole database */ 232 Vdbe *pPrev,*pNext; /* Linked list of VDBEs with the same Vdbe.db */ 233 FILE *trace; /* Write an execution trace here, if not NULL */ 234 int nOp; /* Number of instructions in the program */ 235 int nOpAlloc; /* Number of slots allocated for aOp[] */ 236 Op *aOp; /* Space to hold the virtual machine's program */ 237 int nLabel; /* Number of labels used */ 238 int nLabelAlloc; /* Number of slots allocated in aLabel[] */ 239 int *aLabel; /* Space to hold the labels */ 240 Mem *aStack; /* The operand stack, except string values */ 241 Mem *pTos; /* Top entry in the operand stack */ 242 char **zArgv; /* Text values used by the callback */ 243 char **azColName; /* Becomes the 4th parameter to callbacks */ 244 int nCursor; /* Number of slots in aCsr[] */ 245 Cursor *aCsr; /* One element of this array for each open cursor */ 246 Sorter *pSort; /* A linked list of objects to be sorted */ 247 FILE *pFile; /* At most one open file handler */ 248 int nField; /* Number of file fields */ 249 char **azField; /* Data for each file field */ 250 int nVar; /* Number of entries in azVariable[] */ 251 char **azVar; /* Values for the OP_Variable opcode */ 252 int *anVar; /* Length of each value in azVariable[] */ 253 u8 *abVar; /* TRUE if azVariable[i] needs to be sqliteFree()ed */ 254 char *zLine; /* A single line from the input file */ 255 int nLineAlloc; /* Number of spaces allocated for zLine */ 256 int magic; /* Magic number for sanity checking */ 257 int nMem; /* Number of memory locations currently allocated */ 258 Mem *aMem; /* The memory locations */ 259 Agg agg; /* Aggregate information */ 260 int nSet; /* Number of sets allocated */ 261 Set *aSet; /* An array of sets */ 262 int nCallback; /* Number of callbacks invoked so far */ 263 Keylist *pList; /* A list of ROWIDs */ 264 int keylistStackDepth; /* The size of the "keylist" stack */ 265 Keylist **keylistStack; /* The stack used by opcodes ListPush & ListPop */ 266 int contextStackDepth; /* The size of the "context" stack */ 267 Context *contextStack; /* Stack used by opcodes ContextPush & ContextPop*/ 268 int pc; /* The program counter */ 269 int rc; /* Value to return */ 270 unsigned uniqueCnt; /* Used by OP_MakeRecord when P2!=0 */ 271 int errorAction; /* Recovery action to do in case of an error */ 272 int undoTransOnError; /* If error, either ROLLBACK or COMMIT */ 273 int inTempTrans; /* True if temp database is transactioned */ 274 int returnStack[100]; /* Return address stack for OP_Gosub & OP_Return */ 275 int returnDepth; /* Next unused element in returnStack[] */ 276 int nResColumn; /* Number of columns in one row of the result set */ 277 char **azResColumn; /* Values for one row of result */ 278 int popStack; /* Pop the stack this much on entry to VdbeExec() */ 279 char *zErrMsg; /* Error message written here */ 280 u8 explain; /* True if EXPLAIN present on SQL command */ 281 }; 282 283 /* 284 ** The following are allowed values for Vdbe.magic 285 */ 286 #define VDBE_MAGIC_INIT 0x26bceaa5 /* Building a VDBE program */ 287 #define VDBE_MAGIC_RUN 0xbdf20da3 /* VDBE is ready to execute */ 288 #define VDBE_MAGIC_HALT 0x519c2973 /* VDBE has completed execution */ 289 #define VDBE_MAGIC_DEAD 0xb606c3c8 /* The VDBE has been deallocated */ 290 291 /* 292 ** Function prototypes 293 */ 294 void sqliteVdbeCleanupCursor(Cursor*); 295 void sqliteVdbeSorterReset(Vdbe*); 296 void sqliteVdbeAggReset(Agg*); 297 void sqliteVdbeKeylistFree(Keylist*); 298 void sqliteVdbePopStack(Vdbe*,int); 299 int sqliteVdbeCursorMoveto(Cursor*); 300 int sqliteVdbeByteSwap(int); 301 #if !defined(NDEBUG) || defined(VDBE_PROFILE) 302 void sqliteVdbePrintOp(FILE*, int, Op*); 303 #endif 304