4 ** The author disclaims copyright to this source code. In place of
5 ** a legal notice, here is a blessing:
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.
11 *************************************************************************
12 ** Header file for the Virtual DataBase Engine (VDBE)
14 ** This header defines the interface to the virtual database engine
15 ** or VDBE. The VDBE implements an abstract machine that runs a
16 ** simple program to access and modify the underlying database.
18 #ifndef _SQLITE_VDBE_H_
19 #define _SQLITE_VDBE_H_
23 ** A single VDBE is an opaque structure named "Vdbe". Only routines
24 ** in the source file sqliteVdbe.c are allowed to see the insides
27 typedef struct Vdbe Vdbe
;
30 ** The names of the following types declared in vdbeInt.h are required
31 ** for the VdbeOp definition.
33 typedef struct VdbeFunc VdbeFunc
;
34 typedef struct Mem Mem
;
35 typedef struct SubProgram SubProgram
;
38 ** A single instruction of the virtual machine has an opcode
39 ** and as many as three operands. The instruction is recorded
40 ** as an instance of the following structure:
43 u8 opcode
; /* What operation to perform */
44 signed char p4type
; /* One of the P4_xxx constants for p4 */
45 u8 opflags
; /* Mask of the OPFLG_* flags in opcodes.h */
46 u8 p5
; /* Fifth parameter is an unsigned character */
47 int p1
; /* First operand */
48 int p2
; /* Second parameter (often the jump destination) */
49 int p3
; /* The third parameter */
50 union { /* fourth parameter */
51 int i
; /* Integer value if p4type==P4_INT32 */
52 void *p
; /* Generic pointer */
53 char *z
; /* Pointer to data for string (char array) types */
54 i64
*pI64
; /* Used when p4type is P4_INT64 */
55 double *pReal
; /* Used when p4type is P4_REAL */
56 FuncDef
*pFunc
; /* Used when p4type is P4_FUNCDEF */
57 VdbeFunc
*pVdbeFunc
; /* Used when p4type is P4_VDBEFUNC */
58 CollSeq
*pColl
; /* Used when p4type is P4_COLLSEQ */
59 Mem
*pMem
; /* Used when p4type is P4_MEM */
60 VTable
*pVtab
; /* Used when p4type is P4_VTAB */
61 KeyInfo
*pKeyInfo
; /* Used when p4type is P4_KEYINFO */
62 int *ai
; /* Used when p4type is P4_INTARRAY */
63 SubProgram
*pProgram
; /* Used when p4type is P4_SUBPROGRAM */
64 int (*xAdvance
)(BtCursor
*, int *);
67 char *zComment
; /* Comment to improve readability */
70 int cnt
; /* Number of times this instruction was executed */
71 u64 cycles
; /* Total time spent executing this instruction */
74 typedef struct VdbeOp VdbeOp
;
78 ** A sub-routine used to implement a trigger program.
81 VdbeOp
*aOp
; /* Array of opcodes for sub-program */
82 int nOp
; /* Elements in aOp[] */
83 int nMem
; /* Number of memory cells required */
84 int nCsr
; /* Number of cursors required */
85 int nOnce
; /* Number of OP_Once instructions */
86 void *token
; /* id that may be used to recursive triggers */
87 SubProgram
*pNext
; /* Next sub-program already visited */
91 ** A smaller version of VdbeOp used for the VdbeAddOpList() function because
92 ** it takes up less space.
95 u8 opcode
; /* What operation to perform */
96 signed char p1
; /* First operand */
97 signed char p2
; /* Second parameter (often the jump destination) */
98 signed char p3
; /* Third parameter */
100 typedef struct VdbeOpList VdbeOpList
;
103 ** Allowed values of VdbeOp.p4type
105 #define P4_NOTUSED 0 /* The P4 parameter is not used */
106 #define P4_DYNAMIC (-1) /* Pointer to a string obtained from sqliteMalloc() */
107 #define P4_STATIC (-2) /* Pointer to a static string */
108 #define P4_COLLSEQ (-4) /* P4 is a pointer to a CollSeq structure */
109 #define P4_FUNCDEF (-5) /* P4 is a pointer to a FuncDef structure */
110 #define P4_KEYINFO (-6) /* P4 is a pointer to a KeyInfo structure */
111 #define P4_VDBEFUNC (-7) /* P4 is a pointer to a VdbeFunc structure */
112 #define P4_MEM (-8) /* P4 is a pointer to a Mem* structure */
113 #define P4_TRANSIENT 0 /* P4 is a pointer to a transient string */
114 #define P4_VTAB (-10) /* P4 is a pointer to an sqlite3_vtab structure */
115 #define P4_MPRINTF (-11) /* P4 is a string obtained from sqlite3_mprintf() */
116 #define P4_REAL (-12) /* P4 is a 64-bit floating point value */
117 #define P4_INT64 (-13) /* P4 is a 64-bit signed integer */
118 #define P4_INT32 (-14) /* P4 is a 32-bit signed integer */
119 #define P4_INTARRAY (-15) /* P4 is a vector of 32-bit integers */
120 #define P4_SUBPROGRAM (-18) /* P4 is a pointer to a SubProgram structure */
121 #define P4_ADVANCE (-19) /* P4 is a pointer to BtreeNext() or BtreePrev() */
123 /* When adding a P4 argument using P4_KEYINFO, a copy of the KeyInfo structure
124 ** is made. That copy is freed when the Vdbe is finalized. But if the
125 ** argument is P4_KEYINFO_HANDOFF, the passed in pointer is used. It still
126 ** gets freed when the Vdbe is finalized so it still should be obtained
127 ** from a single sqliteMalloc(). But no copy is made and the calling
128 ** function should *not* try to free the KeyInfo.
130 #define P4_KEYINFO_HANDOFF (-16)
131 #define P4_KEYINFO_STATIC (-17)
134 ** The Vdbe.aColName array contains 5n Mem structures, where n is the
135 ** number of columns of data returned by the statement.
137 #define COLNAME_NAME 0
138 #define COLNAME_DECLTYPE 1
139 #define COLNAME_DATABASE 2
140 #define COLNAME_TABLE 3
141 #define COLNAME_COLUMN 4
142 #ifdef SQLITE_ENABLE_COLUMN_METADATA
143 # define COLNAME_N 5 /* Number of COLNAME_xxx symbols */
145 # ifdef SQLITE_OMIT_DECLTYPE
146 # define COLNAME_N 1 /* Store only the name */
148 # define COLNAME_N 2 /* Store the name and decltype */
153 ** The following macro converts a relative address in the p2 field
154 ** of a VdbeOp structure into a negative number so that
155 ** sqlite3VdbeAddOpList() knows that the address is relative. Calling
156 ** the macro again restores the address.
158 #define ADDR(X) (-1-(X))
161 ** The makefile scans the vdbe.c source file and creates the "opcodes.h"
162 ** header file that defines a number for each opcode used by the VDBE.
167 ** Prototypes for the VDBE interface. See comments on the implementation
168 ** for a description of what each of these routines does.
170 Vdbe
*sqlite3VdbeCreate(sqlite3
*);
171 int sqlite3VdbeAddOp0(Vdbe
*,int);
172 int sqlite3VdbeAddOp1(Vdbe
*,int,int);
173 int sqlite3VdbeAddOp2(Vdbe
*,int,int,int);
174 int sqlite3VdbeAddOp3(Vdbe
*,int,int,int,int);
175 int sqlite3VdbeAddOp4(Vdbe
*,int,int,int,int,const char *zP4
,int);
176 int sqlite3VdbeAddOp4Int(Vdbe
*,int,int,int,int,int);
177 int sqlite3VdbeAddOpList(Vdbe
*, int nOp
, VdbeOpList
const *aOp
);
178 void sqlite3VdbeAddParseSchemaOp(Vdbe
*,int,char*);
179 void sqlite3VdbeChangeP1(Vdbe
*, u32 addr
, int P1
);
180 void sqlite3VdbeChangeP2(Vdbe
*, u32 addr
, int P2
);
181 void sqlite3VdbeChangeP3(Vdbe
*, u32 addr
, int P3
);
182 void sqlite3VdbeChangeP5(Vdbe
*, u8 P5
);
183 void sqlite3VdbeJumpHere(Vdbe
*, int addr
);
184 void sqlite3VdbeChangeToNoop(Vdbe
*, int addr
);
185 void sqlite3VdbeChangeP4(Vdbe
*, int addr
, const char *zP4
, int N
);
186 void sqlite3VdbeUsesBtree(Vdbe
*, int);
187 VdbeOp
*sqlite3VdbeGetOp(Vdbe
*, int);
188 int sqlite3VdbeMakeLabel(Vdbe
*);
189 void sqlite3VdbeRunOnlyOnce(Vdbe
*);
190 void sqlite3VdbeDelete(Vdbe
*);
191 void sqlite3VdbeClearObject(sqlite3
*,Vdbe
*);
192 void sqlite3VdbeMakeReady(Vdbe
*,Parse
*);
193 int sqlite3VdbeFinalize(Vdbe
*);
194 void sqlite3VdbeResolveLabel(Vdbe
*, int);
195 int sqlite3VdbeCurrentAddr(Vdbe
*);
197 int sqlite3VdbeAssertMayAbort(Vdbe
*, int);
198 void sqlite3VdbeTrace(Vdbe
*,FILE*);
200 void sqlite3VdbeResetStepResult(Vdbe
*);
201 void sqlite3VdbeRewind(Vdbe
*);
202 int sqlite3VdbeReset(Vdbe
*);
203 void sqlite3VdbeSetNumCols(Vdbe
*,int);
204 int sqlite3VdbeSetColName(Vdbe
*, int, int, const char *, void(*)(void*));
205 void sqlite3VdbeCountChanges(Vdbe
*);
206 sqlite3
*sqlite3VdbeDb(Vdbe
*);
207 void sqlite3VdbeSetSql(Vdbe
*, const char *z
, int n
, int);
208 void sqlite3VdbeSwap(Vdbe
*,Vdbe
*);
209 VdbeOp
*sqlite3VdbeTakeOpArray(Vdbe
*, int*, int*);
210 sqlite3_value
*sqlite3VdbeGetValue(Vdbe
*, int, u8
);
211 void sqlite3VdbeSetVarmask(Vdbe
*, int);
212 #ifndef SQLITE_OMIT_TRACE
213 char *sqlite3VdbeExpandSql(Vdbe
*, const char*);
216 void sqlite3VdbeRecordUnpack(KeyInfo
*,int,const void*,UnpackedRecord
*);
217 int sqlite3VdbeRecordCompare(int,const void*,UnpackedRecord
*);
218 UnpackedRecord
*sqlite3VdbeAllocUnpackedRecord(KeyInfo
*, char *, int, char **);
220 #ifndef SQLITE_OMIT_TRIGGER
221 void sqlite3VdbeLinkSubProgram(Vdbe
*, SubProgram
*);
226 void sqlite3VdbeComment(Vdbe
*, const char*, ...);
227 # define VdbeComment(X) sqlite3VdbeComment X
228 void sqlite3VdbeNoopComment(Vdbe
*, const char*, ...);
229 # define VdbeNoopComment(X) sqlite3VdbeNoopComment X
231 # define VdbeComment(X)
232 # define VdbeNoopComment(X)