xref: /illumos-gate/usr/src/lib/libsqlite/src/vdbeInt.h (revision 1da57d55)
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