1 | /* |
2 | ** 2001 September 15 |
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 | ** Header file for the Virtual DataBase Engine (VDBE) |
13 | ** |
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. |
17 | */ |
18 | #ifndef SQLITE_VDBE_H |
19 | #define SQLITE_VDBE_H |
20 | #include <stdio.h> |
21 | |
22 | /* |
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 |
25 | ** of this structure. |
26 | */ |
27 | typedef struct Vdbe Vdbe; |
28 | |
29 | /* |
30 | ** The names of the following types declared in vdbeInt.h are required |
31 | ** for the VdbeOp definition. |
32 | */ |
33 | typedef struct sqlite3_value Mem; |
34 | typedef struct SubProgram SubProgram; |
35 | |
36 | /* |
37 | ** A single instruction of the virtual machine has an opcode |
38 | ** and as many as three operands. The instruction is recorded |
39 | ** as an instance of the following structure: |
40 | */ |
41 | struct VdbeOp { |
42 | u8 opcode; /* What operation to perform */ |
43 | signed char p4type; /* One of the P4_xxx constants for p4 */ |
44 | u16 p5; /* Fifth parameter is an unsigned 16-bit integer */ |
45 | int p1; /* First operand */ |
46 | int p2; /* Second parameter (often the jump destination) */ |
47 | int p3; /* The third parameter */ |
48 | union p4union { /* fourth parameter */ |
49 | int i; /* Integer value if p4type==P4_INT32 */ |
50 | void *p; /* Generic pointer */ |
51 | char *z; /* Pointer to data for string (char array) types */ |
52 | i64 *pI64; /* Used when p4type is P4_INT64 */ |
53 | double *pReal; /* Used when p4type is P4_REAL */ |
54 | FuncDef *pFunc; /* Used when p4type is P4_FUNCDEF */ |
55 | sqlite3_context *pCtx; /* Used when p4type is P4_FUNCCTX */ |
56 | CollSeq *pColl; /* Used when p4type is P4_COLLSEQ */ |
57 | Mem *pMem; /* Used when p4type is P4_MEM */ |
58 | VTable *pVtab; /* Used when p4type is P4_VTAB */ |
59 | KeyInfo *pKeyInfo; /* Used when p4type is P4_KEYINFO */ |
60 | u32 *ai; /* Used when p4type is P4_INTARRAY */ |
61 | SubProgram *pProgram; /* Used when p4type is P4_SUBPROGRAM */ |
62 | Table *pTab; /* Used when p4type is P4_TABLE */ |
63 | #ifdef SQLITE_ENABLE_CURSOR_HINTS |
64 | Expr *pExpr; /* Used when p4type is P4_EXPR */ |
65 | #endif |
66 | } p4; |
67 | #ifdef SQLITE_ENABLE_EXPLAIN_COMMENTS |
68 | char *; /* Comment to improve readability */ |
69 | #endif |
70 | #ifdef VDBE_PROFILE |
71 | u32 cnt; /* Number of times this instruction was executed */ |
72 | u64 cycles; /* Total time spent executing this instruction */ |
73 | #endif |
74 | #ifdef SQLITE_VDBE_COVERAGE |
75 | u32 iSrcLine; /* Source-code line that generated this opcode |
76 | ** with flags in the upper 8 bits */ |
77 | #endif |
78 | }; |
79 | typedef struct VdbeOp VdbeOp; |
80 | |
81 | |
82 | /* |
83 | ** A sub-routine used to implement a trigger program. |
84 | */ |
85 | struct SubProgram { |
86 | VdbeOp *aOp; /* Array of opcodes for sub-program */ |
87 | int nOp; /* Elements in aOp[] */ |
88 | int nMem; /* Number of memory cells required */ |
89 | int nCsr; /* Number of cursors required */ |
90 | u8 *aOnce; /* Array of OP_Once flags */ |
91 | void *token; /* id that may be used to recursive triggers */ |
92 | SubProgram *pNext; /* Next sub-program already visited */ |
93 | }; |
94 | |
95 | /* |
96 | ** A smaller version of VdbeOp used for the VdbeAddOpList() function because |
97 | ** it takes up less space. |
98 | */ |
99 | struct VdbeOpList { |
100 | u8 opcode; /* What operation to perform */ |
101 | signed char p1; /* First operand */ |
102 | signed char p2; /* Second parameter (often the jump destination) */ |
103 | signed char p3; /* Third parameter */ |
104 | }; |
105 | typedef struct VdbeOpList VdbeOpList; |
106 | |
107 | /* |
108 | ** Allowed values of VdbeOp.p4type |
109 | */ |
110 | #define P4_NOTUSED 0 /* The P4 parameter is not used */ |
111 | #define P4_TRANSIENT 0 /* P4 is a pointer to a transient string */ |
112 | #define P4_STATIC (-1) /* Pointer to a static string */ |
113 | #define P4_COLLSEQ (-2) /* P4 is a pointer to a CollSeq structure */ |
114 | #define P4_INT32 (-3) /* P4 is a 32-bit signed integer */ |
115 | #define P4_SUBPROGRAM (-4) /* P4 is a pointer to a SubProgram structure */ |
116 | #define P4_TABLE (-5) /* P4 is a pointer to a Table structure */ |
117 | /* Above do not own any resources. Must free those below */ |
118 | #define P4_FREE_IF_LE (-6) |
119 | #define P4_DYNAMIC (-6) /* Pointer to memory from sqliteMalloc() */ |
120 | #define P4_FUNCDEF (-7) /* P4 is a pointer to a FuncDef structure */ |
121 | #define P4_KEYINFO (-8) /* P4 is a pointer to a KeyInfo structure */ |
122 | #define P4_EXPR (-9) /* P4 is a pointer to an Expr tree */ |
123 | #define P4_MEM (-10) /* P4 is a pointer to a Mem* structure */ |
124 | #define P4_VTAB (-11) /* P4 is a pointer to an sqlite3_vtab structure */ |
125 | #define P4_REAL (-12) /* P4 is a 64-bit floating point value */ |
126 | #define P4_INT64 (-13) /* P4 is a 64-bit signed integer */ |
127 | #define P4_INTARRAY (-14) /* P4 is a vector of 32-bit integers */ |
128 | #define P4_FUNCCTX (-15) /* P4 is a pointer to an sqlite3_context object */ |
129 | |
130 | /* Error message codes for OP_Halt */ |
131 | #define P5_ConstraintNotNull 1 |
132 | #define P5_ConstraintUnique 2 |
133 | #define P5_ConstraintCheck 3 |
134 | #define P5_ConstraintFK 4 |
135 | |
136 | /* |
137 | ** The Vdbe.aColName array contains 5n Mem structures, where n is the |
138 | ** number of columns of data returned by the statement. |
139 | */ |
140 | #define COLNAME_NAME 0 |
141 | #define COLNAME_DECLTYPE 1 |
142 | #define COLNAME_DATABASE 2 |
143 | #define COLNAME_TABLE 3 |
144 | #define COLNAME_COLUMN 4 |
145 | #ifdef SQLITE_ENABLE_COLUMN_METADATA |
146 | # define COLNAME_N 5 /* Number of COLNAME_xxx symbols */ |
147 | #else |
148 | # ifdef SQLITE_OMIT_DECLTYPE |
149 | # define COLNAME_N 1 /* Store only the name */ |
150 | # else |
151 | # define COLNAME_N 2 /* Store the name and decltype */ |
152 | # endif |
153 | #endif |
154 | |
155 | /* |
156 | ** The following macro converts a label returned by sqlite3VdbeMakeLabel() |
157 | ** into an index into the Parse.aLabel[] array that contains the resolved |
158 | ** address of that label. |
159 | */ |
160 | #define ADDR(X) (~(X)) |
161 | |
162 | /* |
163 | ** The makefile scans the vdbe.c source file and creates the "opcodes.h" |
164 | ** header file that defines a number for each opcode used by the VDBE. |
165 | */ |
166 | #include "opcodes.h" |
167 | |
168 | /* |
169 | ** Additional non-public SQLITE_PREPARE_* flags |
170 | */ |
171 | #define SQLITE_PREPARE_SAVESQL 0x80 /* Preserve SQL text */ |
172 | #define SQLITE_PREPARE_MASK 0x0f /* Mask of public flags */ |
173 | |
174 | /* |
175 | ** Prototypes for the VDBE interface. See comments on the implementation |
176 | ** for a description of what each of these routines does. |
177 | */ |
178 | Vdbe *sqlite3VdbeCreate(Parse*); |
179 | Parse *sqlite3VdbeParser(Vdbe*); |
180 | int sqlite3VdbeAddOp0(Vdbe*,int); |
181 | int sqlite3VdbeAddOp1(Vdbe*,int,int); |
182 | int sqlite3VdbeAddOp2(Vdbe*,int,int,int); |
183 | int sqlite3VdbeGoto(Vdbe*,int); |
184 | int sqlite3VdbeLoadString(Vdbe*,int,const char*); |
185 | void sqlite3VdbeMultiLoad(Vdbe*,int,const char*,...); |
186 | int sqlite3VdbeAddOp3(Vdbe*,int,int,int,int); |
187 | int sqlite3VdbeAddOp4(Vdbe*,int,int,int,int,const char *zP4,int); |
188 | int sqlite3VdbeAddOp4Dup8(Vdbe*,int,int,int,int,const u8*,int); |
189 | int sqlite3VdbeAddOp4Int(Vdbe*,int,int,int,int,int); |
190 | int sqlite3VdbeAddFunctionCall(Parse*,int,int,int,int,const FuncDef*,int); |
191 | void sqlite3VdbeEndCoroutine(Vdbe*,int); |
192 | #if defined(SQLITE_DEBUG) && !defined(SQLITE_TEST_REALLOC_STRESS) |
193 | void sqlite3VdbeVerifyNoMallocRequired(Vdbe *p, int N); |
194 | void sqlite3VdbeVerifyNoResultRow(Vdbe *p); |
195 | #else |
196 | # define sqlite3VdbeVerifyNoMallocRequired(A,B) |
197 | # define sqlite3VdbeVerifyNoResultRow(A) |
198 | #endif |
199 | #if defined(SQLITE_DEBUG) |
200 | void sqlite3VdbeVerifyAbortable(Vdbe *p, int); |
201 | void sqlite3VdbeNoJumpsOutsideSubrtn(Vdbe*,int,int,int); |
202 | #else |
203 | # define sqlite3VdbeVerifyAbortable(A,B) |
204 | # define sqlite3VdbeNoJumpsOutsideSubrtn(A,B,C,D) |
205 | #endif |
206 | VdbeOp *sqlite3VdbeAddOpList(Vdbe*, int nOp, VdbeOpList const *aOp,int iLineno); |
207 | #ifndef SQLITE_OMIT_EXPLAIN |
208 | void sqlite3VdbeExplain(Parse*,u8,const char*,...); |
209 | void sqlite3VdbeExplainPop(Parse*); |
210 | int sqlite3VdbeExplainParent(Parse*); |
211 | # define ExplainQueryPlan(P) sqlite3VdbeExplain P |
212 | # define ExplainQueryPlanPop(P) sqlite3VdbeExplainPop(P) |
213 | # define ExplainQueryPlanParent(P) sqlite3VdbeExplainParent(P) |
214 | #else |
215 | # define ExplainQueryPlan(P) |
216 | # define ExplainQueryPlanPop(P) |
217 | # define ExplainQueryPlanParent(P) 0 |
218 | # define sqlite3ExplainBreakpoint(A,B) /*no-op*/ |
219 | #endif |
220 | #if defined(SQLITE_DEBUG) && !defined(SQLITE_OMIT_EXPLAIN) |
221 | void sqlite3ExplainBreakpoint(const char*,const char*); |
222 | #else |
223 | # define sqlite3ExplainBreakpoint(A,B) /*no-op*/ |
224 | #endif |
225 | void sqlite3VdbeAddParseSchemaOp(Vdbe*, int, char*, u16); |
226 | void sqlite3VdbeChangeOpcode(Vdbe*, int addr, u8); |
227 | void sqlite3VdbeChangeP1(Vdbe*, int addr, int P1); |
228 | void sqlite3VdbeChangeP2(Vdbe*, int addr, int P2); |
229 | void sqlite3VdbeChangeP3(Vdbe*, int addr, int P3); |
230 | void sqlite3VdbeChangeP5(Vdbe*, u16 P5); |
231 | void sqlite3VdbeTypeofColumn(Vdbe*, int); |
232 | void sqlite3VdbeJumpHere(Vdbe*, int addr); |
233 | void sqlite3VdbeJumpHereOrPopInst(Vdbe*, int addr); |
234 | int sqlite3VdbeChangeToNoop(Vdbe*, int addr); |
235 | int sqlite3VdbeDeletePriorOpcode(Vdbe*, u8 op); |
236 | #ifdef SQLITE_DEBUG |
237 | void sqlite3VdbeReleaseRegisters(Parse*,int addr, int n, u32 mask, int); |
238 | #else |
239 | # define sqlite3VdbeReleaseRegisters(P,A,N,M,F) |
240 | #endif |
241 | void sqlite3VdbeChangeP4(Vdbe*, int addr, const char *zP4, int N); |
242 | void sqlite3VdbeAppendP4(Vdbe*, void *pP4, int p4type); |
243 | void sqlite3VdbeSetP4KeyInfo(Parse*, Index*); |
244 | void sqlite3VdbeUsesBtree(Vdbe*, int); |
245 | VdbeOp *sqlite3VdbeGetOp(Vdbe*, int); |
246 | VdbeOp *sqlite3VdbeGetLastOp(Vdbe*); |
247 | int sqlite3VdbeMakeLabel(Parse*); |
248 | void sqlite3VdbeRunOnlyOnce(Vdbe*); |
249 | void sqlite3VdbeReusable(Vdbe*); |
250 | void sqlite3VdbeDelete(Vdbe*); |
251 | void sqlite3VdbeMakeReady(Vdbe*,Parse*); |
252 | int sqlite3VdbeFinalize(Vdbe*); |
253 | void sqlite3VdbeResolveLabel(Vdbe*, int); |
254 | int sqlite3VdbeCurrentAddr(Vdbe*); |
255 | #ifdef SQLITE_DEBUG |
256 | int sqlite3VdbeAssertMayAbort(Vdbe *, int); |
257 | #endif |
258 | void sqlite3VdbeResetStepResult(Vdbe*); |
259 | void sqlite3VdbeRewind(Vdbe*); |
260 | int sqlite3VdbeReset(Vdbe*); |
261 | void sqlite3VdbeSetNumCols(Vdbe*,int); |
262 | int sqlite3VdbeSetColName(Vdbe*, int, int, const char *, void(*)(void*)); |
263 | void sqlite3VdbeCountChanges(Vdbe*); |
264 | sqlite3 *sqlite3VdbeDb(Vdbe*); |
265 | u8 sqlite3VdbePrepareFlags(Vdbe*); |
266 | void sqlite3VdbeSetSql(Vdbe*, const char *z, int n, u8); |
267 | #ifdef SQLITE_ENABLE_NORMALIZE |
268 | void sqlite3VdbeAddDblquoteStr(sqlite3*,Vdbe*,const char*); |
269 | int sqlite3VdbeUsesDoubleQuotedString(Vdbe*,const char*); |
270 | #endif |
271 | void sqlite3VdbeSwap(Vdbe*,Vdbe*); |
272 | VdbeOp *sqlite3VdbeTakeOpArray(Vdbe*, int*, int*); |
273 | sqlite3_value *sqlite3VdbeGetBoundValue(Vdbe*, int, u8); |
274 | void sqlite3VdbeSetVarmask(Vdbe*, int); |
275 | #ifndef SQLITE_OMIT_TRACE |
276 | char *sqlite3VdbeExpandSql(Vdbe*, const char*); |
277 | #endif |
278 | int sqlite3MemCompare(const Mem*, const Mem*, const CollSeq*); |
279 | int sqlite3BlobCompare(const Mem*, const Mem*); |
280 | |
281 | void sqlite3VdbeRecordUnpack(KeyInfo*,int,const void*,UnpackedRecord*); |
282 | int sqlite3VdbeRecordCompare(int,const void*,UnpackedRecord*); |
283 | int sqlite3VdbeRecordCompareWithSkip(int, const void *, UnpackedRecord *, int); |
284 | UnpackedRecord *sqlite3VdbeAllocUnpackedRecord(KeyInfo*); |
285 | |
286 | typedef int (*RecordCompare)(int,const void*,UnpackedRecord*); |
287 | RecordCompare sqlite3VdbeFindCompare(UnpackedRecord*); |
288 | |
289 | void sqlite3VdbeLinkSubProgram(Vdbe *, SubProgram *); |
290 | int sqlite3VdbeHasSubProgram(Vdbe*); |
291 | |
292 | int sqlite3NotPureFunc(sqlite3_context*); |
293 | #ifdef SQLITE_ENABLE_BYTECODE_VTAB |
294 | int sqlite3VdbeBytecodeVtabInit(sqlite3*); |
295 | #endif |
296 | |
297 | /* Use SQLITE_ENABLE_COMMENTS to enable generation of extra comments on |
298 | ** each VDBE opcode. |
299 | ** |
300 | ** Use the SQLITE_ENABLE_MODULE_COMMENTS macro to see some extra no-op |
301 | ** comments in VDBE programs that show key decision points in the code |
302 | ** generator. |
303 | */ |
304 | #ifdef SQLITE_ENABLE_EXPLAIN_COMMENTS |
305 | void (Vdbe*, const char*, ...); |
306 | # define (X) sqlite3VdbeComment X |
307 | void (Vdbe*, const char*, ...); |
308 | # define (X) sqlite3VdbeNoopComment X |
309 | # ifdef SQLITE_ENABLE_MODULE_COMMENTS |
310 | # define VdbeModuleComment(X) sqlite3VdbeNoopComment X |
311 | # else |
312 | # define (X) |
313 | # endif |
314 | #else |
315 | # define VdbeComment(X) |
316 | # define VdbeNoopComment(X) |
317 | # define VdbeModuleComment(X) |
318 | #endif |
319 | |
320 | /* |
321 | ** The VdbeCoverage macros are used to set a coverage testing point |
322 | ** for VDBE branch instructions. The coverage testing points are line |
323 | ** numbers in the sqlite3.c source file. VDBE branch coverage testing |
324 | ** only works with an amalagmation build. That's ok since a VDBE branch |
325 | ** coverage build designed for testing the test suite only. No application |
326 | ** should ever ship with VDBE branch coverage measuring turned on. |
327 | ** |
328 | ** VdbeCoverage(v) // Mark the previously coded instruction |
329 | ** // as a branch |
330 | ** |
331 | ** VdbeCoverageIf(v, conditional) // Mark previous if conditional true |
332 | ** |
333 | ** VdbeCoverageAlwaysTaken(v) // Previous branch is always taken |
334 | ** |
335 | ** VdbeCoverageNeverTaken(v) // Previous branch is never taken |
336 | ** |
337 | ** VdbeCoverageNeverNull(v) // Previous three-way branch is only |
338 | ** // taken on the first two ways. The |
339 | ** // NULL option is not possible |
340 | ** |
341 | ** VdbeCoverageEqNe(v) // Previous OP_Jump is only interested |
342 | ** // in distingishing equal and not-equal. |
343 | ** |
344 | ** Every VDBE branch operation must be tagged with one of the macros above. |
345 | ** If not, then when "make test" is run with -DSQLITE_VDBE_COVERAGE and |
346 | ** -DSQLITE_DEBUG then an ALWAYS() will fail in the vdbeTakeBranch() |
347 | ** routine in vdbe.c, alerting the developer to the missed tag. |
348 | ** |
349 | ** During testing, the test application will invoke |
350 | ** sqlite3_test_control(SQLITE_TESTCTRL_VDBE_COVERAGE,...) to set a callback |
351 | ** routine that is invoked as each bytecode branch is taken. The callback |
352 | ** contains the sqlite3.c source line number ov the VdbeCoverage macro and |
353 | ** flags to indicate whether or not the branch was taken. The test application |
354 | ** is responsible for keeping track of this and reporting byte-code branches |
355 | ** that are never taken. |
356 | ** |
357 | ** See the VdbeBranchTaken() macro and vdbeTakeBranch() function in the |
358 | ** vdbe.c source file for additional information. |
359 | */ |
360 | #ifdef SQLITE_VDBE_COVERAGE |
361 | void sqlite3VdbeSetLineNumber(Vdbe*,int); |
362 | # define VdbeCoverage(v) sqlite3VdbeSetLineNumber(v,__LINE__) |
363 | # define VdbeCoverageIf(v,x) if(x)sqlite3VdbeSetLineNumber(v,__LINE__) |
364 | # define VdbeCoverageAlwaysTaken(v) \ |
365 | sqlite3VdbeSetLineNumber(v,__LINE__|0x5000000); |
366 | # define VdbeCoverageNeverTaken(v) \ |
367 | sqlite3VdbeSetLineNumber(v,__LINE__|0x6000000); |
368 | # define VdbeCoverageNeverNull(v) \ |
369 | sqlite3VdbeSetLineNumber(v,__LINE__|0x4000000); |
370 | # define VdbeCoverageNeverNullIf(v,x) \ |
371 | if(x)sqlite3VdbeSetLineNumber(v,__LINE__|0x4000000); |
372 | # define VdbeCoverageEqNe(v) \ |
373 | sqlite3VdbeSetLineNumber(v,__LINE__|0x8000000); |
374 | # define VDBE_OFFSET_LINENO(x) (__LINE__+x) |
375 | #else |
376 | # define VdbeCoverage(v) |
377 | # define VdbeCoverageIf(v,x) |
378 | # define VdbeCoverageAlwaysTaken(v) |
379 | # define VdbeCoverageNeverTaken(v) |
380 | # define VdbeCoverageNeverNull(v) |
381 | # define VdbeCoverageNeverNullIf(v,x) |
382 | # define VdbeCoverageEqNe(v) |
383 | # define VDBE_OFFSET_LINENO(x) 0 |
384 | #endif |
385 | |
386 | #ifdef SQLITE_ENABLE_STMT_SCANSTATUS |
387 | void sqlite3VdbeScanStatus(Vdbe*, int, int, int, LogEst, const char*); |
388 | #else |
389 | # define sqlite3VdbeScanStatus(a,b,c,d,e) |
390 | #endif |
391 | |
392 | #if defined(SQLITE_DEBUG) || defined(VDBE_PROFILE) |
393 | void sqlite3VdbePrintOp(FILE*, int, VdbeOp*); |
394 | #endif |
395 | |
396 | #endif /* SQLITE_VDBE_H */ |
397 | |