AryaWu/sqlite
0
1/*2** 2001 September 153**4** The author disclaims copyright to this source code. In place of5** 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 engine15** or VDBE. The VDBE implements an abstract machine that runs a16** simple program to access and modify the underlying database.17*/18#ifndef SQLITE_VDBE_H19#define SQLITE_VDBE_H20#include <stdio.h>21 22/*23** A single VDBE is an opaque structure named "Vdbe". Only routines24** in the source file sqliteVdbe.c are allowed to see the insides25** of this structure.26*/27typedef struct Vdbe Vdbe;28 29/*30** The names of the following types declared in vdbeInt.h are required31** for the VdbeOp definition.32*/33typedef struct sqlite3_value Mem;34typedef struct SubProgram SubProgram;35typedef struct SubrtnSig SubrtnSig;36 37/*38** A signature for a reusable subroutine that materializes the RHS of39** an IN operator.40*/41struct SubrtnSig {42 int selId; /* SELECT-id for the SELECT statement on the RHS */43 u8 bComplete; /* True if fully coded and available for reusable */44 char *zAff; /* Affinity of the overall IN expression */45 int iTable; /* Ephemeral table generated by the subroutine */46 int iAddr; /* Subroutine entry address */47 int regReturn; /* Register used to hold return address */48};49 50/*51** A single instruction of the virtual machine has an opcode52** and as many as three operands. The instruction is recorded53** as an instance of the following structure:54*/55struct VdbeOp {56 u8 opcode; /* What operation to perform */57 signed char p4type; /* One of the P4_xxx constants for p4 */58 u16 p5; /* Fifth parameter is an unsigned 16-bit integer */59 int p1; /* First operand */60 int p2; /* Second parameter (often the jump destination) */61 int p3; /* The third parameter */62 union p4union { /* fourth parameter */63 int i; /* Integer value if p4type==P4_INT32 */64 void *p; /* Generic pointer */65 char *z; /* Pointer to data for string (char array) types */66 i64 *pI64; /* Used when p4type is P4_INT64 */67 double *pReal; /* Used when p4type is P4_REAL */68 FuncDef *pFunc; /* Used when p4type is P4_FUNCDEF */69 sqlite3_context *pCtx; /* Used when p4type is P4_FUNCCTX */70 CollSeq *pColl; /* Used when p4type is P4_COLLSEQ */71 Mem *pMem; /* Used when p4type is P4_MEM */72 VTable *pVtab; /* Used when p4type is P4_VTAB */73 KeyInfo *pKeyInfo; /* Used when p4type is P4_KEYINFO */74 u32 *ai; /* Used when p4type is P4_INTARRAY */75 SubProgram *pProgram; /* Used when p4type is P4_SUBPROGRAM */76 Table *pTab; /* Used when p4type is P4_TABLE */77 SubrtnSig *pSubrtnSig; /* Used when p4type is P4_SUBRTNSIG */78#ifdef SQLITE_ENABLE_CURSOR_HINTS79 Expr *pExpr; /* Used when p4type is P4_EXPR */80#endif81 } p4;82#ifdef SQLITE_ENABLE_EXPLAIN_COMMENTS83 char *zComment; /* Comment to improve readability */84#endif85#ifdef SQLITE_VDBE_COVERAGE86 u32 iSrcLine; /* Source-code line that generated this opcode87 ** with flags in the upper 8 bits */88#endif89#if defined(SQLITE_ENABLE_STMT_SCANSTATUS) || defined(VDBE_PROFILE)90 u64 nExec;91 u64 nCycle;92#endif93};94typedef struct VdbeOp VdbeOp;95 96 97/*98** A sub-routine used to implement a trigger program.99*/100struct SubProgram {101 VdbeOp *aOp; /* Array of opcodes for sub-program */102 int nOp; /* Elements in aOp[] */103 int nMem; /* Number of memory cells required */104 int nCsr; /* Number of cursors required */105 u8 *aOnce; /* Array of OP_Once flags */106 void *token; /* id that may be used to recursive triggers */107 SubProgram *pNext; /* Next sub-program already visited */108};109 110/*111** A smaller version of VdbeOp used for the VdbeAddOpList() function because112** it takes up less space.113*/114struct VdbeOpList {115 u8 opcode; /* What operation to perform */116 signed char p1; /* First operand */117 signed char p2; /* Second parameter (often the jump destination) */118 signed char p3; /* Third parameter */119};120typedef struct VdbeOpList VdbeOpList;121 122/*123** Allowed values of VdbeOp.p4type124*/125#define P4_NOTUSED 0 /* The P4 parameter is not used */126#define P4_TRANSIENT 0 /* P4 is a pointer to a transient string */127#define P4_STATIC (-1) /* Pointer to a static string */128#define P4_COLLSEQ (-2) /* P4 is a pointer to a CollSeq structure */129#define P4_INT32 (-3) /* P4 is a 32-bit signed integer */130#define P4_SUBPROGRAM (-4) /* P4 is a pointer to a SubProgram structure */131#define P4_TABLE (-5) /* P4 is a pointer to a Table structure */132/* Above do not own any resources. Must free those below */133#define P4_FREE_IF_LE (-6)134#define P4_DYNAMIC (-6) /* Pointer to memory from sqliteMalloc() */135#define P4_FUNCDEF (-7) /* P4 is a pointer to a FuncDef structure */136#define P4_KEYINFO (-8) /* P4 is a pointer to a KeyInfo structure */137#define P4_EXPR (-9) /* P4 is a pointer to an Expr tree */138#define P4_MEM (-10) /* P4 is a pointer to a Mem* structure */139#define P4_VTAB (-11) /* P4 is a pointer to an sqlite3_vtab structure */140#define P4_REAL (-12) /* P4 is a 64-bit floating point value */141#define P4_INT64 (-13) /* P4 is a 64-bit signed integer */142#define P4_INTARRAY (-14) /* P4 is a vector of 32-bit integers */143#define P4_FUNCCTX (-15) /* P4 is a pointer to an sqlite3_context object */144#define P4_TABLEREF (-16) /* Like P4_TABLE, but reference counted */145#define P4_SUBRTNSIG (-17) /* P4 is a SubrtnSig pointer */146 147/* Error message codes for OP_Halt */148#define P5_ConstraintNotNull 1149#define P5_ConstraintUnique 2150#define P5_ConstraintCheck 3151#define P5_ConstraintFK 4152 153/*154** The Vdbe.aColName array contains 5n Mem structures, where n is the 155** number of columns of data returned by the statement.156*/157#define COLNAME_NAME 0158#define COLNAME_DECLTYPE 1159#define COLNAME_DATABASE 2160#define COLNAME_TABLE 3161#define COLNAME_COLUMN 4162#ifdef SQLITE_ENABLE_COLUMN_METADATA163# define COLNAME_N 5 /* Number of COLNAME_xxx symbols */164#else165# ifdef SQLITE_OMIT_DECLTYPE166# define COLNAME_N 1 /* Store only the name */167# else168# define COLNAME_N 2 /* Store the name and decltype */169# endif170#endif171 172/*173** The following macro converts a label returned by sqlite3VdbeMakeLabel()174** into an index into the Parse.aLabel[] array that contains the resolved175** address of that label.176*/177#define ADDR(X) (~(X))178 179/*180** The makefile scans the vdbe.c source file and creates the "opcodes.h"181** header file that defines a number for each opcode used by the VDBE.182*/183#include "opcodes.h"184 185/*186** Additional non-public SQLITE_PREPARE_* flags187*/188#define SQLITE_PREPARE_SAVESQL 0x80 /* Preserve SQL text */189#define SQLITE_PREPARE_MASK 0x1f /* Mask of public flags */190 191/*192** Prototypes for the VDBE interface. See comments on the implementation193** for a description of what each of these routines does.194*/195Vdbe *sqlite3VdbeCreate(Parse*);196Parse *sqlite3VdbeParser(Vdbe*);197int sqlite3VdbeAddOp0(Vdbe*,int);198int sqlite3VdbeAddOp1(Vdbe*,int,int);199int sqlite3VdbeAddOp2(Vdbe*,int,int,int);200int sqlite3VdbeGoto(Vdbe*,int);201int sqlite3VdbeLoadString(Vdbe*,int,const char*);202void sqlite3VdbeMultiLoad(Vdbe*,int,const char*,...);203int sqlite3VdbeAddOp3(Vdbe*,int,int,int,int);204int sqlite3VdbeAddOp4(Vdbe*,int,int,int,int,const char *zP4,int);205int sqlite3VdbeAddOp4Dup8(Vdbe*,int,int,int,int,const u8*,int);206int sqlite3VdbeAddOp4Int(Vdbe*,int,int,int,int,int);207int sqlite3VdbeAddFunctionCall(Parse*,int,int,int,int,const FuncDef*,int);208void sqlite3VdbeEndCoroutine(Vdbe*,int);209#if defined(SQLITE_DEBUG) && !defined(SQLITE_TEST_REALLOC_STRESS)210 void sqlite3VdbeVerifyNoMallocRequired(Vdbe *p, int N);211 void sqlite3VdbeVerifyNoResultRow(Vdbe *p);212#else213# define sqlite3VdbeVerifyNoMallocRequired(A,B)214# define sqlite3VdbeVerifyNoResultRow(A)215#endif216#if defined(SQLITE_DEBUG)217 void sqlite3VdbeVerifyAbortable(Vdbe *p, int);218 void sqlite3VdbeNoJumpsOutsideSubrtn(Vdbe*,int,int,int);219#else220# define sqlite3VdbeVerifyAbortable(A,B)221# define sqlite3VdbeNoJumpsOutsideSubrtn(A,B,C,D)222#endif223VdbeOp *sqlite3VdbeAddOpList(Vdbe*, int nOp, VdbeOpList const *aOp,int iLineno);224#ifndef SQLITE_OMIT_EXPLAIN225 int sqlite3VdbeExplain(Parse*,u8,const char*,...);226 void sqlite3VdbeExplainPop(Parse*);227 int sqlite3VdbeExplainParent(Parse*);228# define ExplainQueryPlan(P) sqlite3VdbeExplain P229# ifdef SQLITE_ENABLE_STMT_SCANSTATUS230# define ExplainQueryPlan2(V,P) (V = sqlite3VdbeExplain P)231# else232# define ExplainQueryPlan2(V,P) ExplainQueryPlan(P)233# endif234# define ExplainQueryPlanPop(P) sqlite3VdbeExplainPop(P)235# define ExplainQueryPlanParent(P) sqlite3VdbeExplainParent(P)236#else237# define ExplainQueryPlan(P)238# define ExplainQueryPlan2(V,P)239# define ExplainQueryPlanPop(P)240# define ExplainQueryPlanParent(P) 0241# define sqlite3ExplainBreakpoint(A,B) /*no-op*/242#endif243#if defined(SQLITE_DEBUG) && !defined(SQLITE_OMIT_EXPLAIN)244 void sqlite3ExplainBreakpoint(const char*,const char*);245#else246# define sqlite3ExplainBreakpoint(A,B) /*no-op*/247#endif248void sqlite3VdbeAddParseSchemaOp(Vdbe*, int, char*, u16);249void sqlite3VdbeChangeOpcode(Vdbe*, int addr, u8);250void sqlite3VdbeChangeP1(Vdbe*, int addr, int P1);251void sqlite3VdbeChangeP2(Vdbe*, int addr, int P2);252void sqlite3VdbeChangeP3(Vdbe*, int addr, int P3);253void sqlite3VdbeChangeP5(Vdbe*, u16 P5);254void sqlite3VdbeTypeofColumn(Vdbe*, int);255void sqlite3VdbeJumpHere(Vdbe*, int addr);256void sqlite3VdbeJumpHereOrPopInst(Vdbe*, int addr);257int sqlite3VdbeChangeToNoop(Vdbe*, int addr);258int sqlite3VdbeDeletePriorOpcode(Vdbe*, u8 op);259#ifdef SQLITE_DEBUG260 void sqlite3VdbeReleaseRegisters(Parse*,int addr, int n, u32 mask, int);261#else262# define sqlite3VdbeReleaseRegisters(P,A,N,M,F)263#endif264void sqlite3VdbeChangeP4(Vdbe*, int addr, const char *zP4, int N);265void sqlite3VdbeAppendP4(Vdbe*, void *pP4, int p4type);266void sqlite3VdbeSetP4KeyInfo(Parse*, Index*);267void sqlite3VdbeUsesBtree(Vdbe*, int);268VdbeOp *sqlite3VdbeGetOp(Vdbe*, int);269VdbeOp *sqlite3VdbeGetLastOp(Vdbe*);270int sqlite3VdbeMakeLabel(Parse*);271void sqlite3VdbeRunOnlyOnce(Vdbe*);272void sqlite3VdbeReusable(Vdbe*);273void sqlite3VdbeDelete(Vdbe*);274void sqlite3VdbeMakeReady(Vdbe*,Parse*);275int sqlite3VdbeFinalize(Vdbe*);276void sqlite3VdbeResolveLabel(Vdbe*, int);277int sqlite3VdbeCurrentAddr(Vdbe*);278#ifdef SQLITE_DEBUG279 int sqlite3VdbeAssertMayAbort(Vdbe *, int);280#endif281void sqlite3VdbeResetStepResult(Vdbe*);282void sqlite3VdbeRewind(Vdbe*);283int sqlite3VdbeReset(Vdbe*);284void sqlite3VdbeSetNumCols(Vdbe*,int);285int sqlite3VdbeSetColName(Vdbe*, int, int, const char *, void(*)(void*));286void sqlite3VdbeCountChanges(Vdbe*);287sqlite3 *sqlite3VdbeDb(Vdbe*);288u8 sqlite3VdbePrepareFlags(Vdbe*);289void sqlite3VdbeSetSql(Vdbe*, const char *z, int n, u8);290#ifdef SQLITE_ENABLE_NORMALIZE291void sqlite3VdbeAddDblquoteStr(sqlite3*,Vdbe*,const char*);292int sqlite3VdbeUsesDoubleQuotedString(Vdbe*,const char*);293#endif294void sqlite3VdbeSwap(Vdbe*,Vdbe*);295VdbeOp *sqlite3VdbeTakeOpArray(Vdbe*, int*, int*);296sqlite3_value *sqlite3VdbeGetBoundValue(Vdbe*, int, u8);297void sqlite3VdbeSetVarmask(Vdbe*, int);298#ifndef SQLITE_OMIT_TRACE299 char *sqlite3VdbeExpandSql(Vdbe*, const char*);300#endif301int sqlite3MemCompare(const Mem*, const Mem*, const CollSeq*);302int sqlite3BlobCompare(const Mem*, const Mem*);303#ifdef SQLITE_ENABLE_PERCENTILE304 const char *sqlite3VdbeFuncName(const sqlite3_context*);305#endif306 307void sqlite3VdbeRecordUnpack(int,const void*,UnpackedRecord*);308int sqlite3VdbeRecordCompare(int,const void*,UnpackedRecord*);309int sqlite3VdbeRecordCompareWithSkip(int, const void *, UnpackedRecord *, int);310UnpackedRecord *sqlite3VdbeAllocUnpackedRecord(KeyInfo*);311 312typedef int (*RecordCompare)(int,const void*,UnpackedRecord*);313RecordCompare sqlite3VdbeFindCompare(UnpackedRecord*);314 315void sqlite3VdbeLinkSubProgram(Vdbe *, SubProgram *);316int sqlite3VdbeHasSubProgram(Vdbe*);317 318void sqlite3MemSetArrayInt64(sqlite3_value *aMem, int iIdx, i64 val);319 320#ifndef SQLITE_OMIT_DATETIME_FUNCS321int sqlite3NotPureFunc(sqlite3_context*);322#endif323#ifdef SQLITE_ENABLE_BYTECODE_VTAB324int sqlite3VdbeBytecodeVtabInit(sqlite3*);325#endif326 327/* Use SQLITE_ENABLE_EXPLAIN_COMMENTS to enable generation of extra328** comments on each VDBE opcode.329**330** Use the SQLITE_ENABLE_MODULE_COMMENTS macro to see some extra no-op331** comments in VDBE programs that show key decision points in the code332** generator.333*/334#ifdef SQLITE_ENABLE_EXPLAIN_COMMENTS335 void sqlite3VdbeComment(Vdbe*, const char*, ...);336# define VdbeComment(X) sqlite3VdbeComment X337 void sqlite3VdbeNoopComment(Vdbe*, const char*, ...);338# define VdbeNoopComment(X) sqlite3VdbeNoopComment X339# ifdef SQLITE_ENABLE_MODULE_COMMENTS340# define VdbeModuleComment(X) sqlite3VdbeNoopComment X341# else342# define VdbeModuleComment(X)343# endif344#else345# define VdbeComment(X)346# define VdbeNoopComment(X)347# define VdbeModuleComment(X)348#endif349 350/*351** The VdbeCoverage macros are used to set a coverage testing point352** for VDBE branch instructions. The coverage testing points are line353** numbers in the sqlite3.c source file. VDBE branch coverage testing354** only works with an amalgamation build. That's ok since a VDBE branch355** coverage build designed for testing the test suite only. No application356** should ever ship with VDBE branch coverage measuring turned on.357**358** VdbeCoverage(v) // Mark the previously coded instruction359** // as a branch360**361** VdbeCoverageIf(v, conditional) // Mark previous if conditional true362**363** VdbeCoverageAlwaysTaken(v) // Previous branch is always taken364**365** VdbeCoverageNeverTaken(v) // Previous branch is never taken366**367** VdbeCoverageNeverNull(v) // Previous three-way branch is only368** // taken on the first two ways. The369** // NULL option is not possible370**371** VdbeCoverageEqNe(v) // Previous OP_Jump is only interested372** // in distinguishing equal and not-equal.373**374** Every VDBE branch operation must be tagged with one of the macros above.375** If not, then when "make test" is run with -DSQLITE_VDBE_COVERAGE and376** -DSQLITE_DEBUG then an ALWAYS() will fail in the vdbeTakeBranch()377** routine in vdbe.c, alerting the developer to the missed tag.378**379** During testing, the test application will invoke380** sqlite3_test_control(SQLITE_TESTCTRL_VDBE_COVERAGE,...) to set a callback381** routine that is invoked as each bytecode branch is taken. The callback382** contains the sqlite3.c source line number of the VdbeCoverage macro and383** flags to indicate whether or not the branch was taken. The test application384** is responsible for keeping track of this and reporting byte-code branches385** that are never taken.386**387** See the VdbeBranchTaken() macro and vdbeTakeBranch() function in the388** vdbe.c source file for additional information.389*/390#ifdef SQLITE_VDBE_COVERAGE391 void sqlite3VdbeSetLineNumber(Vdbe*,int);392# define VdbeCoverage(v) sqlite3VdbeSetLineNumber(v,__LINE__)393# define VdbeCoverageIf(v,x) if(x)sqlite3VdbeSetLineNumber(v,__LINE__)394# define VdbeCoverageAlwaysTaken(v) \395 sqlite3VdbeSetLineNumber(v,__LINE__|0x5000000);396# define VdbeCoverageNeverTaken(v) \397 sqlite3VdbeSetLineNumber(v,__LINE__|0x6000000);398# define VdbeCoverageNeverNull(v) \399 sqlite3VdbeSetLineNumber(v,__LINE__|0x4000000);400# define VdbeCoverageNeverNullIf(v,x) \401 if(x)sqlite3VdbeSetLineNumber(v,__LINE__|0x4000000);402# define VdbeCoverageEqNe(v) \403 sqlite3VdbeSetLineNumber(v,__LINE__|0x8000000);404# define VDBE_OFFSET_LINENO(x) (__LINE__+x)405#else406# define VdbeCoverage(v)407# define VdbeCoverageIf(v,x)408# define VdbeCoverageAlwaysTaken(v)409# define VdbeCoverageNeverTaken(v)410# define VdbeCoverageNeverNull(v)411# define VdbeCoverageNeverNullIf(v,x)412# define VdbeCoverageEqNe(v)413# define VDBE_OFFSET_LINENO(x) 0414#endif415 416#ifdef SQLITE_ENABLE_STMT_SCANSTATUS417void sqlite3VdbeScanStatus(Vdbe*, int, int, int, LogEst, const char*);418void sqlite3VdbeScanStatusRange(Vdbe*, int, int, int);419void sqlite3VdbeScanStatusCounters(Vdbe*, int, int, int);420#else421# define sqlite3VdbeScanStatus(a,b,c,d,e,f)422# define sqlite3VdbeScanStatusRange(a,b,c,d)423# define sqlite3VdbeScanStatusCounters(a,b,c,d)424#endif425 426#if defined(SQLITE_DEBUG) || defined(VDBE_PROFILE)427void sqlite3VdbePrintOp(FILE*, int, VdbeOp*);428#endif429 430#if defined(SQLITE_ENABLE_CURSOR_HINTS) && defined(SQLITE_DEBUG)431int sqlite3CursorRangeHintExprCheck(Walker *pWalker, Expr *pExpr);432#endif433 434#endif /* SQLITE_VDBE_H */435