blob: 679a6c33d0fba00d5eed68e98fe9d89a43d1b5ce [file] [log] [blame]
drh9a324642003-09-06 20:12:01 +00001/*
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/*
drh4a1c3802004-05-12 15:15:47 +000020** intToKey() and keyToInt() used to transform the rowid. But with
21** the latest versions of the design they are no-ops.
drha11846b2004-01-07 18:52:56 +000022*/
drh4a1c3802004-05-12 15:15:47 +000023#define keyToInt(X) (X)
24#define intToKey(X) (X)
drha11846b2004-01-07 18:52:56 +000025
26/*
drh9a324642003-09-06 20:12:01 +000027** The makefile scans this source file and creates the following
28** array of string constants which are the names of all VDBE opcodes.
29** This array is defined in a separate source code file named opcode.c
30** which is automatically generated by the makefile.
31*/
danielk19774adee202004-05-08 08:23:19 +000032extern char *sqlite3OpcodeNames[];
drh9a324642003-09-06 20:12:01 +000033
34/*
35** SQL is translated into a sequence of instructions to be
36** executed by a virtual machine. Each instruction is an instance
37** of the following structure.
38*/
39typedef struct VdbeOp Op;
40
41/*
42** Boolean values
43*/
44typedef unsigned char Bool;
45
46/*
47** A cursor is a pointer into a single BTree within a database file.
48** The cursor can seek to a BTree entry with a particular key, or
49** loop over all entries of the Btree. You can also insert new BTree
50** entries or retrieve the key or data from the entry that the cursor
51** is currently pointing to.
52**
53** Every cursor that the virtual machine has open is represented by an
54** instance of the following structure.
55**
56** If the Cursor.isTriggerRow flag is set it means that this cursor is
57** really a single row that represents the NEW or OLD pseudo-table of
58** a row trigger. The data for the row is stored in Cursor.pData and
59** the rowid is in Cursor.iKey.
60*/
61struct Cursor {
62 BtCursor *pCursor; /* The cursor structure of the backend */
drhf328bc82004-05-10 23:29:49 +000063 i64 lastRecno; /* Last recno from a Next or NextIdx operation */
64 i64 nextRowid; /* Next rowid returned by OP_NewRowid */
drh9a324642003-09-06 20:12:01 +000065 Bool recnoIsValid; /* True if lastRecno is valid */
66 Bool keyAsData; /* The OP_Column command works on key instead of data */
67 Bool atFirst; /* True if pointing to first entry */
68 Bool useRandomRowid; /* Generate new record numbers semi-randomly */
69 Bool nullRow; /* True if pointing to a row with no data */
70 Bool nextRowidValid; /* True if the nextRowid field is valid */
71 Bool pseudoTable; /* This is a NEW or OLD pseudo-tables of a trigger */
danielk19774adee202004-05-08 08:23:19 +000072 Bool deferredMoveto; /* A call to sqlite3BtreeMoveto() is needed */
drhf328bc82004-05-10 23:29:49 +000073 Bool intKey; /* True if the table requires integer keys */
74 Bool zeroData; /* True if table contains keys only - no data */
drhd3d39e92004-05-20 22:16:29 +000075 u8 bogusIncrKey; /* Something for pIncrKey to point to if pKeyInfo==0 */
drhf328bc82004-05-10 23:29:49 +000076 i64 movetoTarget; /* Argument to the deferred sqlite3BtreeMoveto() */
drh9a324642003-09-06 20:12:01 +000077 Btree *pBt; /* Separate file holding temporary table */
78 int nData; /* Number of bytes in pData */
79 char *pData; /* Data for a NEW or OLD pseudo-table */
drhf328bc82004-05-10 23:29:49 +000080 i64 iKey; /* Key for the NEW or OLD pseudo-table row */
drhd3d39e92004-05-20 22:16:29 +000081 u8 *pIncrKey; /* Pointer to pKeyInfo->incrKey */
82 KeyInfo *pKeyInfo; /* Info about index keys needed by index cursors */
drh9188b382004-05-14 21:12:22 +000083
84 /* Cached information about the header for the data record that the
85 ** cursor is currently pointing to */
86 Bool cacheValid; /* True if the cache is valid */
87 int nField; /* Number of fields in the header */
88 int nHeader; /* Number of bytes in the entire header */
89 int payloadSize; /* Total number of bytes in the record */
90 u64 *aType; /* Type values for all entries in the record */
drh9a324642003-09-06 20:12:01 +000091};
92typedef struct Cursor Cursor;
93
94/*
95** A sorter builds a list of elements to be sorted. Each element of
96** the list is an instance of the following structure.
97*/
98typedef struct Sorter Sorter;
99struct Sorter {
100 int nKey; /* Number of bytes in the key */
101 char *zKey; /* The key by which we will sort */
102 int nData; /* Number of bytes in the data */
103 char *pData; /* The data associated with this key */
104 Sorter *pNext; /* Next in the list */
105};
106
107/*
108** Number of buckets used for merge-sort.
109*/
110#define NSORT 30
111
112/*
113** Number of bytes of string storage space available to each stack
114** layer without having to malloc. NBFS is short for Number of Bytes
115** For Strings.
116*/
117#define NBFS 32
118
119/*
drh00706be2004-01-30 14:49:16 +0000120** A single level of the stack or a single memory cell
121** is an instance of the following structure.
drh9a324642003-09-06 20:12:01 +0000122*/
123struct Mem {
drhf328bc82004-05-10 23:29:49 +0000124 i64 i; /* Integer value */
drh00706be2004-01-30 14:49:16 +0000125 int n; /* Number of characters in string value, including '\0' */
126 int flags; /* Some combination of MEM_Null, MEM_Str, MEM_Dyn, etc. */
127 double r; /* Real value */
drh3dc0b8e2004-05-10 12:07:10 +0000128 char *z; /* String or BLOB value */
drh00706be2004-01-30 14:49:16 +0000129 char zShort[NBFS]; /* Space for short strings */
drh9a324642003-09-06 20:12:01 +0000130};
131typedef struct Mem Mem;
132
133/*
drh3dc0b8e2004-05-10 12:07:10 +0000134** Allowed values for Mem.flags.
135**
136** The first 5 values determine the data type(s). Null and Blob must
137** occur alone. But Str, Int, and Real can occur together.
138**
139** The next 3 utf entries determine the text representation for strings.
140** These values are only meaningful if the type is Str.
141**
142** The last 4 values specify what kind of memory Mem.z points to.
143** These valus are only meaningful if the Str or Blob types are used.
drh9a324642003-09-06 20:12:01 +0000144*/
drh00706be2004-01-30 14:49:16 +0000145#define MEM_Null 0x0001 /* Value is NULL */
146#define MEM_Str 0x0002 /* Value is a string */
147#define MEM_Int 0x0004 /* Value is an integer */
148#define MEM_Real 0x0008 /* Value is a real number */
drh3dc0b8e2004-05-10 12:07:10 +0000149#define MEM_Blob 0x0010 /* Value is a BLOB */
danielk1977b1bc9532004-05-22 03:05:33 +0000150#define MEM_Struct 0x0020 /* Value is some kind of struct */
drh3dc0b8e2004-05-10 12:07:10 +0000151
danielk1977b1bc9532004-05-22 03:05:33 +0000152#define MEM_Term 0x0200 /* String has a nul terminator character */
danielk197751e3d8e2004-05-20 01:12:34 +0000153
danielk1977b1bc9532004-05-22 03:05:33 +0000154#define MEM_Dyn 0x0400 /* Need to call sqliteFree() on Mem.z */
155#define MEM_Static 0x0800 /* Mem.z points to a static string */
156#define MEM_Ephem 0x1000 /* Mem.z points to an ephemeral string */
157#define MEM_Short 0x2000 /* Mem.z points to Mem.zShort */
drh3dc0b8e2004-05-10 12:07:10 +0000158
danielk197793d46752004-05-23 13:30:58 +0000159/* Internally, all strings manipulated by the VDBE are encoded using the
160** native encoding for the main database. Therefore the following three
161** flags, which describe the text encoding of the string if the MEM_Str
162** flag is true, are not generally valid for Mem* objects handled by the
163** VDBE.
164**
165** When a user-defined function is called (see OP_Function), the Mem*
166** objects that store the argument values for the function call are
167** passed to the user-defined function routine cast to sqlite3_value*.
168** The user routine may then call sqlite3_value_data() or
169** sqlite3_value_data16() to request a UTF-8 or UTF-16 string. If the
170** string representation currently stored in Mem.z is not the requested
171** encoding, then a translation occurs. To keep track of things, the
172** MEM_Utf* flags are set correctly for the database encoding before a
173** user-routine is called, and kept up to date if any translations occur
174** thereafter.
175**
176** When sqlite3_step() returns SQLITE3_ROW, indicating that a row of data
177** is ready for processing by the caller, the data values are stored
178** internally as Mem* objects. Before sqlite3_step() returns, the MEM_Utf*
179** flags are set correctly for the database encoding. A translation may
180** take place if the user requests a non-native encoding via
181** sqlite3_column_data() or sqlite3_column_data16(). If this occurs, then
182** the MEM_Utf* flags are updated accordingly.
183*/
184#define MEM_Utf8 0x0040 /* String uses UTF-8 encoding */
185#define MEM_Utf16be 0x0080 /* String uses UTF-16 big-endian */
186#define MEM_Utf16le 0x0100 /* String uses UTF-16 little-endian */
drh9a324642003-09-06 20:12:01 +0000187
drh00706be2004-01-30 14:49:16 +0000188/* The following MEM_ value appears only in AggElem.aMem.s.flag fields.
drh9a324642003-09-06 20:12:01 +0000189** It indicates that the corresponding AggElem.aMem.z points to a
190** aggregate function context that needs to be finalized.
191*/
danielk1977b1bc9532004-05-22 03:05:33 +0000192#define MEM_AggCtx 0x4000 /* Mem.z points to an agg function context */
drh9a324642003-09-06 20:12:01 +0000193
194/*
195** The "context" argument for a installable function. A pointer to an
196** instance of this structure is the first argument to the routines used
197** implement the SQL functions.
198**
199** There is a typedef for this structure in sqlite.h. So all routines,
200** even the public interface to SQLite, can use a pointer to this structure.
201** But this file is the only place where the internal details of this
202** structure are known.
203**
204** This structure is defined inside of vdbe.c because it uses substructures
drh00706be2004-01-30 14:49:16 +0000205** (Mem) which are only defined there.
drh9a324642003-09-06 20:12:01 +0000206*/
207struct sqlite_func {
208 FuncDef *pFunc; /* Pointer to function information. MUST BE FIRST */
drh00706be2004-01-30 14:49:16 +0000209 Mem s; /* The return value is stored here */
drh9a324642003-09-06 20:12:01 +0000210 void *pAgg; /* Aggregate context */
211 u8 isError; /* Set to true for an error */
212 u8 isStep; /* Current in the step function */
213 int cnt; /* Number of times that the step function has been called */
214};
215
216/*
217** An Agg structure describes an Aggregator. Each Agg consists of
218** zero or more Aggregator elements (AggElem). Each AggElem contains
219** a key and one or more values. The values are used in processing
220** aggregate functions in a SELECT. The key is used to implement
221** the GROUP BY clause of a select.
222*/
223typedef struct Agg Agg;
224typedef struct AggElem AggElem;
225struct Agg {
226 int nMem; /* Number of values stored in each AggElem */
227 AggElem *pCurrent; /* The AggElem currently in focus */
228 HashElem *pSearch; /* The hash element for pCurrent */
229 Hash hash; /* Hash table of all aggregate elements */
230 FuncDef **apFunc; /* Information about aggregate functions */
231};
232struct AggElem {
233 char *zKey; /* The key to this AggElem */
234 int nKey; /* Number of bytes in the key, including '\0' at end */
235 Mem aMem[1]; /* The values for this AggElem */
236};
237
238/*
239** A Set structure is used for quick testing to see if a value
240** is part of a small set. Sets are used to implement code like
241** this:
242** x.y IN ('hi','hoo','hum')
243*/
244typedef struct Set Set;
245struct Set {
246 Hash hash; /* A set is just a hash table */
247 HashElem *prev; /* Previously accessed hash elemen */
248};
249
250/*
251** A Keylist is a bunch of keys into a table. The keylist can
252** grow without bound. The keylist stores the ROWIDs of database
253** records that need to be deleted or updated.
254*/
255typedef struct Keylist Keylist;
256struct Keylist {
257 int nKey; /* Number of slots in aKey[] */
258 int nUsed; /* Next unwritten slot in aKey[] */
259 int nRead; /* Next unread slot in aKey[] */
260 Keylist *pNext; /* Next block of keys */
danielk197750ce7502004-05-13 12:32:11 +0000261 i64 aKey[1]; /* One or more keys. Extra space allocated as needed */
drh9a324642003-09-06 20:12:01 +0000262};
263
264/*
rdcb0c374f2004-02-20 22:53:38 +0000265** A Context stores the last insert rowid, the last statement change count,
266** and the current statement change count (i.e. changes since last statement).
267** Elements of Context structure type make up the ContextStack, which is
268** updated by the ContextPush and ContextPop opcodes (used by triggers)
269*/
270typedef struct Context Context;
271struct Context {
272 int lastRowid; /* Last insert rowid (from db->lastRowid) */
273 int lsChange; /* Last statement change count (from db->lsChange) */
274 int csChange; /* Current statement change count (from db->csChange) */
275};
276
277/*
drh9a324642003-09-06 20:12:01 +0000278** An instance of the virtual machine. This structure contains the complete
279** state of the virtual machine.
280**
danielk1977132872b2004-05-10 10:37:18 +0000281** The "sqlite_vm" structure pointer that is returned by sqlite3_compile()
drh9a324642003-09-06 20:12:01 +0000282** is really a pointer to an instance of this structure.
283*/
284struct Vdbe {
285 sqlite *db; /* The whole database */
286 Vdbe *pPrev,*pNext; /* Linked list of VDBEs with the same Vdbe.db */
287 FILE *trace; /* Write an execution trace here, if not NULL */
288 int nOp; /* Number of instructions in the program */
289 int nOpAlloc; /* Number of slots allocated for aOp[] */
290 Op *aOp; /* Space to hold the virtual machine's program */
291 int nLabel; /* Number of labels used */
292 int nLabelAlloc; /* Number of slots allocated in aLabel[] */
293 int *aLabel; /* Space to hold the labels */
drh00706be2004-01-30 14:49:16 +0000294 Mem *aStack; /* The operand stack, except string values */
drh6810ce62004-01-31 19:22:56 +0000295 Mem *pTos; /* Top entry in the operand stack */
danielk19776ddcca52004-05-24 23:48:25 +0000296 Mem **apArg; /* Arguments to currently executing user function */
drh9a324642003-09-06 20:12:01 +0000297 char **azColName; /* Becomes the 4th parameter to callbacks */
danielk1977106bb232004-05-21 10:08:53 +0000298 void **azColName16; /* UTF-16 encoded equivalent of azColName */
drhd7556d22004-05-14 21:59:40 +0000299 int nCursor; /* Number of slots in apCsr[] */
300 Cursor **apCsr; /* One element of this array for each open cursor */
drh9a324642003-09-06 20:12:01 +0000301 Sorter *pSort; /* A linked list of objects to be sorted */
302 FILE *pFile; /* At most one open file handler */
303 int nField; /* Number of file fields */
304 char **azField; /* Data for each file field */
drh5a12e682004-05-19 11:24:25 +0000305 int nVar; /* Number of entries in apVar[] */
306 Mem *apVar; /* Values for the OP_Variable opcode. */
drh9a324642003-09-06 20:12:01 +0000307 char *zLine; /* A single line from the input file */
308 int nLineAlloc; /* Number of spaces allocated for zLine */
309 int magic; /* Magic number for sanity checking */
310 int nMem; /* Number of memory locations currently allocated */
311 Mem *aMem; /* The memory locations */
312 Agg agg; /* Aggregate information */
drh9a324642003-09-06 20:12:01 +0000313 int nCallback; /* Number of callbacks invoked so far */
314 Keylist *pList; /* A list of ROWIDs */
315 int keylistStackDepth; /* The size of the "keylist" stack */
316 Keylist **keylistStack; /* The stack used by opcodes ListPush & ListPop */
rdcb0c374f2004-02-20 22:53:38 +0000317 int contextStackDepth; /* The size of the "context" stack */
318 Context *contextStack; /* Stack used by opcodes ContextPush & ContextPop*/
drh9a324642003-09-06 20:12:01 +0000319 int pc; /* The program counter */
320 int rc; /* Value to return */
321 unsigned uniqueCnt; /* Used by OP_MakeRecord when P2!=0 */
322 int errorAction; /* Recovery action to do in case of an error */
323 int undoTransOnError; /* If error, either ROLLBACK or COMMIT */
324 int inTempTrans; /* True if temp database is transactioned */
325 int returnStack[100]; /* Return address stack for OP_Gosub & OP_Return */
326 int returnDepth; /* Next unused element in returnStack[] */
327 int nResColumn; /* Number of columns in one row of the result set */
drh826fb5a2004-02-14 23:59:57 +0000328 char **azResColumn; /* Values for one row of result */
danielk1977106bb232004-05-21 10:08:53 +0000329 u8 resOnStack; /* True if there are result values on the stack */
drh9a324642003-09-06 20:12:01 +0000330 int popStack; /* Pop the stack this much on entry to VdbeExec() */
331 char *zErrMsg; /* Error message written here */
332 u8 explain; /* True if EXPLAIN present on SQL command */
333};
334
335/*
336** The following are allowed values for Vdbe.magic
337*/
338#define VDBE_MAGIC_INIT 0x26bceaa5 /* Building a VDBE program */
339#define VDBE_MAGIC_RUN 0xbdf20da3 /* VDBE is ready to execute */
340#define VDBE_MAGIC_HALT 0x519c2973 /* VDBE has completed execution */
341#define VDBE_MAGIC_DEAD 0xb606c3c8 /* The VDBE has been deallocated */
342
343/*
drh9a324642003-09-06 20:12:01 +0000344** Function prototypes
345*/
danielk19774adee202004-05-08 08:23:19 +0000346void sqlite3VdbeCleanupCursor(Cursor*);
347void sqlite3VdbeSorterReset(Vdbe*);
348void sqlite3VdbeAggReset(Agg*);
349void sqlite3VdbeKeylistFree(Keylist*);
drh9a324642003-09-06 20:12:01 +0000350void sqliteVdbePopStack(Vdbe*,int);
danielk19774adee202004-05-08 08:23:19 +0000351int sqlite3VdbeCursorMoveto(Cursor*);
drh9a324642003-09-06 20:12:01 +0000352#if !defined(NDEBUG) || defined(VDBE_PROFILE)
danielk19774adee202004-05-08 08:23:19 +0000353void sqlite3VdbePrintOp(FILE*, int, Op*);
drh9a324642003-09-06 20:12:01 +0000354#endif
danielk1977cfcdaef2004-05-12 07:33:33 +0000355int sqlite3VdbeSerialTypeLen(u64);
danielk1977b1bc9532004-05-22 03:05:33 +0000356u64 sqlite3VdbeSerialType(Mem *);
357int sqlite3VdbeSerialPut(unsigned char *, Mem *);
358int sqlite3VdbeSerialGet(const unsigned char *, u64, Mem *, u8 enc);
danielk19774adee202004-05-08 08:23:19 +0000359
danielk1977189621d2004-05-09 23:23:56 +0000360int sqlite2BtreeKeyCompare(BtCursor *, const void *, int, int, int *);
drh7cf6e4d2004-05-19 14:56:55 +0000361int sqlite3VdbeIdxKeyCompare(Cursor*, int , const unsigned char*, int*);
danielk1977452c9892004-05-13 05:16:15 +0000362int sqlite3VdbeIdxRowid(BtCursor *, i64 *);
drh53db1452004-05-20 13:54:53 +0000363int sqlite3MemCompare(const Mem*, const Mem*, const CollSeq*);
danielk197788208052004-05-25 01:13:20 +0000364int sqlite3MemCopy(Mem*, const Mem*);
danielk1977bf3b7212004-05-18 10:06:24 +0000365int sqlite3VdbeKeyCompare(void*,int,const void*,int, const void*);
366int sqlite3VdbeRowCompare(void*,int,const void*,int, const void*);
danielk1977106bb232004-05-21 10:08:53 +0000367int sqlite3VdbeExec(Vdbe*);
368int sqlite3VdbeList(Vdbe*);
danielk1977b1bc9532004-05-22 03:05:33 +0000369int sqlite3VdbeSetEncoding(Mem *, u8);