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#ifndef _VDBEINT_H_
19#define _VDBEINT_H_
20
21/*
22** SQL is translated into a sequence of instructions to be
23** executed by a virtual machine.  Each instruction is an instance
24** of the following structure.
25*/
26typedef struct VdbeOp Op;
27
28/*
29** Boolean values
30*/
31typedef unsigned char Bool;
32
33/*
34** A cursor is a pointer into a single BTree within a database file.
35** The cursor can seek to a BTree entry with a particular key, or
36** loop over all entries of the Btree.  You can also insert new BTree
37** entries or retrieve the key or data from the entry that the cursor
38** is currently pointing to.
39**
40** Every cursor that the virtual machine has open is represented by an
41** instance of the following structure.
42*/
43struct VdbeCursor {
44  BtCursor *pCursor;    /* The cursor structure of the backend */
45  Btree *pBt;           /* Separate file holding temporary table */
46  KeyInfo *pKeyInfo;    /* Info about index keys needed by index cursors */
47  int iDb;              /* Index of cursor database in db->aDb[] (or -1) */
48  int pseudoTableReg;   /* Register holding pseudotable content. */
49  int nField;           /* Number of fields in the header */
50  Bool zeroed;          /* True if zeroed out and ready for reuse */
51  Bool rowidIsValid;    /* True if lastRowid is valid */
52  Bool atFirst;         /* True if pointing to first entry */
53  Bool useRandomRowid;  /* Generate new record numbers semi-randomly */
54  Bool nullRow;         /* True if pointing to a row with no data */
55  Bool deferredMoveto;  /* A call to sqlite3BtreeMoveto() is needed */
56  Bool isTable;         /* True if a table requiring integer keys */
57  Bool isIndex;         /* True if an index containing keys only - no data */
58  Bool isOrdered;       /* True if the underlying table is BTREE_UNORDERED */
59  sqlite3_vtab_cursor *pVtabCursor;  /* The cursor for a virtual table */
60  const sqlite3_module *pModule;     /* Module for cursor pVtabCursor */
61  i64 seqCount;         /* Sequence counter */
62  i64 movetoTarget;     /* Argument to the deferred sqlite3BtreeMoveto() */
63  i64 lastRowid;        /* Last rowid from a Next or NextIdx operation */
64
65  /* Result of last sqlite3BtreeMoveto() done by an OP_NotExists or
66  ** OP_IsUnique opcode on this cursor. */
67  int seekResult;
68
69  /* Cached information about the header for the data record that the
70  ** cursor is currently pointing to.  Only valid if cacheStatus matches
71  ** Vdbe.cacheCtr.  Vdbe.cacheCtr will never take on the value of
72  ** CACHE_STALE and so setting cacheStatus=CACHE_STALE guarantees that
73  ** the cache is out of date.
74  **
75  ** aRow might point to (ephemeral) data for the current row, or it might
76  ** be NULL.
77  */
78  u32 cacheStatus;      /* Cache is valid if this matches Vdbe.cacheCtr */
79  int payloadSize;      /* Total number of bytes in the record */
80  u32 *aType;           /* Type values for all entries in the record */
81  u32 *aOffset;         /* Cached offsets to the start of each columns data */
82  u8 *aRow;             /* Data for the current row, if all on one page */
83};
84typedef struct VdbeCursor VdbeCursor;
85
86/*
87** When a sub-program is executed (OP_Program), a structure of this type
88** is allocated to store the current value of the program counter, as
89** well as the current memory cell array and various other frame specific
90** values stored in the Vdbe struct. When the sub-program is finished,
91** these values are copied back to the Vdbe from the VdbeFrame structure,
92** restoring the state of the VM to as it was before the sub-program
93** began executing.
94**
95** The memory for a VdbeFrame object is allocated and managed by a memory
96** cell in the parent (calling) frame. When the memory cell is deleted or
97** overwritten, the VdbeFrame object is not freed immediately. Instead, it
98** is linked into the Vdbe.pDelFrame list. The contents of the Vdbe.pDelFrame
99** list is deleted when the VM is reset in VdbeHalt(). The reason for doing
100** this instead of deleting the VdbeFrame immediately is to avoid recursive
101** calls to sqlite3VdbeMemRelease() when the memory cells belonging to the
102** child frame are released.
103**
104** The currently executing frame is stored in Vdbe.pFrame. Vdbe.pFrame is
105** set to NULL if the currently executing frame is the main program.
106*/
107typedef struct VdbeFrame VdbeFrame;
108struct VdbeFrame {
109  Vdbe *v;                /* VM this frame belongs to */
110  int pc;                 /* Program Counter in parent (calling) frame */
111  Op *aOp;                /* Program instructions for parent frame */
112  int nOp;                /* Size of aOp array */
113  Mem *aMem;              /* Array of memory cells for parent frame */
114  int nMem;               /* Number of entries in aMem */
115  VdbeCursor **apCsr;     /* Array of Vdbe cursors for parent frame */
116  u16 nCursor;            /* Number of entries in apCsr */
117  void *token;            /* Copy of SubProgram.token */
118  int nChildMem;          /* Number of memory cells for child frame */
119  int nChildCsr;          /* Number of cursors for child frame */
120  i64 lastRowid;          /* Last insert rowid (sqlite3.lastRowid) */
121  int nChange;            /* Statement changes (Vdbe.nChanges)     */
122  VdbeFrame *pParent;     /* Parent of this frame, or NULL if parent is main */
123};
124
125#define VdbeFrameMem(p) ((Mem *)&((u8 *)p)[ROUND8(sizeof(VdbeFrame))])
126
127/*
128** A value for VdbeCursor.cacheValid that means the cache is always invalid.
129*/
130#define CACHE_STALE 0
131
132/*
133** Internally, the vdbe manipulates nearly all SQL values as Mem
134** structures. Each Mem struct may cache multiple representations (string,
135** integer etc.) of the same value.
136*/
137struct Mem {
138  sqlite3 *db;        /* The associated database connection */
139  char *z;            /* String or BLOB value */
140  double r;           /* Real value */
141  union {
142    i64 i;              /* Integer value used when MEM_Int is set in flags */
143    int nZero;          /* Used when bit MEM_Zero is set in flags */
144    FuncDef *pDef;      /* Used only when flags==MEM_Agg */
145    RowSet *pRowSet;    /* Used only when flags==MEM_RowSet */
146    VdbeFrame *pFrame;  /* Used when flags==MEM_Frame */
147  } u;
148  int n;              /* Number of characters in string value, excluding '\0' */
149  u16 flags;          /* Some combination of MEM_Null, MEM_Str, MEM_Dyn, etc. */
150  u8  type;           /* One of SQLITE_NULL, SQLITE_TEXT, SQLITE_INTEGER, etc */
151  u8  enc;            /* SQLITE_UTF8, SQLITE_UTF16BE, SQLITE_UTF16LE */
152#ifdef SQLITE_DEBUG
153  Mem *pScopyFrom;    /* This Mem is a shallow copy of pScopyFrom */
154  void *pFiller;      /* So that sizeof(Mem) is a multiple of 8 */
155#endif
156  void (*xDel)(void *);  /* If not null, call this function to delete Mem.z */
157  char *zMalloc;      /* Dynamic buffer allocated by sqlite3_malloc() */
158};
159
160/* One or more of the following flags are set to indicate the validOK
161** representations of the value stored in the Mem struct.
162**
163** If the MEM_Null flag is set, then the value is an SQL NULL value.
164** No other flags may be set in this case.
165**
166** If the MEM_Str flag is set then Mem.z points at a string representation.
167** Usually this is encoded in the same unicode encoding as the main
168** database (see below for exceptions). If the MEM_Term flag is also
169** set, then the string is nul terminated. The MEM_Int and MEM_Real
170** flags may coexist with the MEM_Str flag.
171*/
172#define MEM_Null      0x0001   /* Value is NULL */
173#define MEM_Str       0x0002   /* Value is a string */
174#define MEM_Int       0x0004   /* Value is an integer */
175#define MEM_Real      0x0008   /* Value is a real number */
176#define MEM_Blob      0x0010   /* Value is a BLOB */
177#define MEM_RowSet    0x0020   /* Value is a RowSet object */
178#define MEM_Frame     0x0040   /* Value is a VdbeFrame object */
179#define MEM_Invalid   0x0080   /* Value is undefined */
180#define MEM_TypeMask  0x00ff   /* Mask of type bits */
181
182/* Whenever Mem contains a valid string or blob representation, one of
183** the following flags must be set to determine the memory management
184** policy for Mem.z.  The MEM_Term flag tells us whether or not the
185** string is \000 or \u0000 terminated
186*/
187#define MEM_Term      0x0200   /* String rep is nul terminated */
188#define MEM_Dyn       0x0400   /* Need to call sqliteFree() on Mem.z */
189#define MEM_Static    0x0800   /* Mem.z points to a static string */
190#define MEM_Ephem     0x1000   /* Mem.z points to an ephemeral string */
191#define MEM_Agg       0x2000   /* Mem.z points to an agg function context */
192#define MEM_Zero      0x4000   /* Mem.i contains count of 0s appended to blob */
193#ifdef SQLITE_OMIT_INCRBLOB
194  #undef MEM_Zero
195  #define MEM_Zero 0x0000
196#endif
197
198/*
199** Clear any existing type flags from a Mem and replace them with f
200*/
201#define MemSetTypeFlag(p, f) \
202   ((p)->flags = ((p)->flags&~(MEM_TypeMask|MEM_Zero))|f)
203
204/*
205** Return true if a memory cell is not marked as invalid.  This macro
206** is for use inside assert() statements only.
207*/
208#ifdef SQLITE_DEBUG
209#define memIsValid(M)  ((M)->flags & MEM_Invalid)==0
210#endif
211
212
213/* A VdbeFunc is just a FuncDef (defined in sqliteInt.h) that contains
214** additional information about auxiliary information bound to arguments
215** of the function.  This is used to implement the sqlite3_get_auxdata()
216** and sqlite3_set_auxdata() APIs.  The "auxdata" is some auxiliary data
217** that can be associated with a constant argument to a function.  This
218** allows functions such as "regexp" to compile their constant regular
219** expression argument once and reused the compiled code for multiple
220** invocations.
221*/
222struct VdbeFunc {
223  FuncDef *pFunc;               /* The definition of the function */
224  int nAux;                     /* Number of entries allocated for apAux[] */
225  struct AuxData {
226    void *pAux;                   /* Aux data for the i-th argument */
227    void (*xDelete)(void *);      /* Destructor for the aux data */
228  } apAux[1];                   /* One slot for each function argument */
229};
230
231/*
232** The "context" argument for a installable function.  A pointer to an
233** instance of this structure is the first argument to the routines used
234** implement the SQL functions.
235**
236** There is a typedef for this structure in sqlite.h.  So all routines,
237** even the public interface to SQLite, can use a pointer to this structure.
238** But this file is the only place where the internal details of this
239** structure are known.
240**
241** This structure is defined inside of vdbeInt.h because it uses substructures
242** (Mem) which are only defined there.
243*/
244struct sqlite3_context {
245  FuncDef *pFunc;       /* Pointer to function information.  MUST BE FIRST */
246  VdbeFunc *pVdbeFunc;  /* Auxilary data, if created. */
247  Mem s;                /* The return value is stored here */
248  Mem *pMem;            /* Memory cell used to store aggregate context */
249  int isError;          /* Error code returned by the function. */
250  CollSeq *pColl;       /* Collating sequence */
251};
252
253/*
254** An instance of the virtual machine.  This structure contains the complete
255** state of the virtual machine.
256**
257** The "sqlite3_stmt" structure pointer that is returned by sqlite3_prepare()
258** is really a pointer to an instance of this structure.
259**
260** The Vdbe.inVtabMethod variable is set to non-zero for the duration of
261** any virtual table method invocations made by the vdbe program. It is
262** set to 2 for xDestroy method calls and 1 for all other methods. This
263** variable is used for two purposes: to allow xDestroy methods to execute
264** "DROP TABLE" statements and to prevent some nasty side effects of
265** malloc failure when SQLite is invoked recursively by a virtual table
266** method function.
267*/
268struct Vdbe {
269  sqlite3 *db;            /* The database connection that owns this statement */
270  Op *aOp;                /* Space to hold the virtual machine's program */
271  Mem *aMem;              /* The memory locations */
272  Mem **apArg;            /* Arguments to currently executing user function */
273  Mem *aColName;          /* Column names to return */
274  Mem *pResultSet;        /* Pointer to an array of results */
275  int nMem;               /* Number of memory locations currently allocated */
276  int nOp;                /* Number of instructions in the program */
277  int nOpAlloc;           /* Number of slots allocated for aOp[] */
278  int nLabel;             /* Number of labels used */
279  int nLabelAlloc;        /* Number of slots allocated in aLabel[] */
280  int *aLabel;            /* Space to hold the labels */
281  u16 nResColumn;         /* Number of columns in one row of the result set */
282  u16 nCursor;            /* Number of slots in apCsr[] */
283  u32 magic;              /* Magic number for sanity checking */
284  char *zErrMsg;          /* Error message written here */
285  Vdbe *pPrev,*pNext;     /* Linked list of VDBEs with the same Vdbe.db */
286  VdbeCursor **apCsr;     /* One element of this array for each open cursor */
287  Mem *aVar;              /* Values for the OP_Variable opcode. */
288  char **azVar;           /* Name of variables */
289  ynVar nVar;             /* Number of entries in aVar[] */
290  u32 cacheCtr;           /* VdbeCursor row cache generation counter */
291  int pc;                 /* The program counter */
292  int rc;                 /* Value to return */
293  u8 errorAction;         /* Recovery action to do in case of an error */
294  u8 okVar;               /* True if azVar[] has been initialized */
295  u8 explain;             /* True if EXPLAIN present on SQL command */
296  u8 changeCntOn;         /* True to update the change-counter */
297  u8 expired;             /* True if the VM needs to be recompiled */
298  u8 runOnlyOnce;         /* Automatically expire on reset */
299  u8 minWriteFileFormat;  /* Minimum file format for writable database files */
300  u8 inVtabMethod;        /* See comments above */
301  u8 usesStmtJournal;     /* True if uses a statement journal */
302  u8 readOnly;            /* True for read-only statements */
303  u8 isPrepareV2;         /* True if prepared with prepare_v2() */
304  int nChange;            /* Number of db changes made since last reset */
305  yDbMask btreeMask;      /* Bitmask of db->aDb[] entries referenced */
306  yDbMask lockMask;       /* Subset of btreeMask that requires a lock */
307  int iStatement;         /* Statement number (or 0 if has not opened stmt) */
308  int aCounter[3];        /* Counters used by sqlite3_stmt_status() */
309#ifndef SQLITE_OMIT_TRACE
310  i64 startTime;          /* Time when query started - used for profiling */
311#endif
312  i64 nFkConstraint;      /* Number of imm. FK constraints this VM */
313  i64 nStmtDefCons;       /* Number of def. constraints when stmt started */
314  char *zSql;             /* Text of the SQL statement that generated this */
315  void *pFree;            /* Free this when deleting the vdbe */
316#ifdef SQLITE_DEBUG
317  FILE *trace;            /* Write an execution trace here, if not NULL */
318#endif
319  VdbeFrame *pFrame;      /* Parent frame */
320  VdbeFrame *pDelFrame;   /* List of frame objects to free on VM reset */
321  int nFrame;             /* Number of frames in pFrame list */
322  u32 expmask;            /* Binding to these vars invalidates VM */
323  SubProgram *pProgram;   /* Linked list of all sub-programs used by VM */
324};
325
326/*
327** The following are allowed values for Vdbe.magic
328*/
329#define VDBE_MAGIC_INIT     0x26bceaa5    /* Building a VDBE program */
330#define VDBE_MAGIC_RUN      0xbdf20da3    /* VDBE is ready to execute */
331#define VDBE_MAGIC_HALT     0x519c2973    /* VDBE has completed execution */
332#define VDBE_MAGIC_DEAD     0xb606c3c8    /* The VDBE has been deallocated */
333
334/*
335** Function prototypes
336*/
337void sqlite3VdbeFreeCursor(Vdbe *, VdbeCursor*);
338void sqliteVdbePopStack(Vdbe*,int);
339int sqlite3VdbeCursorMoveto(VdbeCursor*);
340#if defined(SQLITE_DEBUG) || defined(VDBE_PROFILE)
341void sqlite3VdbePrintOp(FILE*, int, Op*);
342#endif
343u32 sqlite3VdbeSerialTypeLen(u32);
344u32 sqlite3VdbeSerialType(Mem*, int);
345u32 sqlite3VdbeSerialPut(unsigned char*, int, Mem*, int);
346u32 sqlite3VdbeSerialGet(const unsigned char*, u32, Mem*);
347void sqlite3VdbeDeleteAuxData(VdbeFunc*, int);
348
349int sqlite2BtreeKeyCompare(BtCursor *, const void *, int, int, int *);
350int sqlite3VdbeIdxKeyCompare(VdbeCursor*,UnpackedRecord*,int*);
351int sqlite3VdbeIdxRowid(sqlite3*, BtCursor *, i64 *);
352int sqlite3MemCompare(const Mem*, const Mem*, const CollSeq*);
353int sqlite3VdbeExec(Vdbe*);
354int sqlite3VdbeList(Vdbe*);
355int sqlite3VdbeHalt(Vdbe*);
356int sqlite3VdbeChangeEncoding(Mem *, int);
357int sqlite3VdbeMemTooBig(Mem*);
358int sqlite3VdbeMemCopy(Mem*, const Mem*);
359void sqlite3VdbeMemShallowCopy(Mem*, const Mem*, int);
360void sqlite3VdbeMemMove(Mem*, Mem*);
361int sqlite3VdbeMemNulTerminate(Mem*);
362int sqlite3VdbeMemSetStr(Mem*, const char*, int, u8, void(*)(void*));
363void sqlite3VdbeMemSetInt64(Mem*, i64);
364#ifdef SQLITE_OMIT_FLOATING_POINT
365# define sqlite3VdbeMemSetDouble sqlite3VdbeMemSetInt64
366#else
367  void sqlite3VdbeMemSetDouble(Mem*, double);
368#endif
369void sqlite3VdbeMemSetNull(Mem*);
370void sqlite3VdbeMemSetZeroBlob(Mem*,int);
371void sqlite3VdbeMemSetRowSet(Mem*);
372int sqlite3VdbeMemMakeWriteable(Mem*);
373int sqlite3VdbeMemStringify(Mem*, int);
374i64 sqlite3VdbeIntValue(Mem*);
375int sqlite3VdbeMemIntegerify(Mem*);
376double sqlite3VdbeRealValue(Mem*);
377void sqlite3VdbeIntegerAffinity(Mem*);
378int sqlite3VdbeMemRealify(Mem*);
379int sqlite3VdbeMemNumerify(Mem*);
380int sqlite3VdbeMemFromBtree(BtCursor*,int,int,int,Mem*);
381void sqlite3VdbeMemRelease(Mem *p);
382void sqlite3VdbeMemReleaseExternal(Mem *p);
383int sqlite3VdbeMemFinalize(Mem*, FuncDef*);
384const char *sqlite3OpcodeName(int);
385int sqlite3VdbeMemGrow(Mem *pMem, int n, int preserve);
386int sqlite3VdbeCloseStatement(Vdbe *, int);
387void sqlite3VdbeFrameDelete(VdbeFrame*);
388int sqlite3VdbeFrameRestore(VdbeFrame *);
389void sqlite3VdbeMemStoreType(Mem *pMem);
390
391#if !defined(SQLITE_OMIT_SHARED_CACHE) && SQLITE_THREADSAFE>0
392  void sqlite3VdbeEnter(Vdbe*);
393  void sqlite3VdbeLeave(Vdbe*);
394#else
395# define sqlite3VdbeEnter(X)
396# define sqlite3VdbeLeave(X)
397#endif
398
399#ifdef SQLITE_DEBUG
400void sqlite3VdbeMemPrepareToChange(Vdbe*,Mem*);
401#endif
402
403#ifndef SQLITE_OMIT_FOREIGN_KEY
404int sqlite3VdbeCheckFk(Vdbe *, int);
405#else
406# define sqlite3VdbeCheckFk(p,i) 0
407#endif
408
409int sqlite3VdbeMemTranslate(Mem*, u8);
410#ifdef SQLITE_DEBUG
411  void sqlite3VdbePrintSql(Vdbe*);
412  void sqlite3VdbeMemPrettyPrint(Mem *pMem, char *zBuf);
413#endif
414int sqlite3VdbeMemHandleBom(Mem *pMem);
415
416#ifndef SQLITE_OMIT_INCRBLOB
417  int sqlite3VdbeMemExpandBlob(Mem *);
418#else
419  #define sqlite3VdbeMemExpandBlob(x) SQLITE_OK
420#endif
421
422#endif /* !defined(_VDBEINT_H_) */
423