Back to index

php5  5.3.10
vdbeInt.h
Go to the documentation of this file.
00001 /*
00002 ** 2003 September 6
00003 **
00004 ** The author disclaims copyright to this source code.  In place of
00005 ** a legal notice, here is a blessing:
00006 **
00007 **    May you do good and not evil.
00008 **    May you find forgiveness for yourself and forgive others.
00009 **    May you share freely, never taking more than you give.
00010 **
00011 *************************************************************************
00012 ** This is the header file for information that is private to the
00013 ** VDBE.  This information used to all be at the top of the single
00014 ** source code file "vdbe.c".  When that file became too big (over
00015 ** 6000 lines long) it was split up into several smaller files and
00016 ** this header information was factored out.
00017 */
00018 
00019 /*
00020 ** When converting from the native format to the key format and back
00021 ** again, in addition to changing the byte order we invert the high-order
00022 ** bit of the most significant byte.  This causes negative numbers to
00023 ** sort before positive numbers in the memcmp() function.
00024 */
00025 #define keyToInt(X)   (sqliteVdbeByteSwap(X) ^ 0x80000000)
00026 #define intToKey(X)   (sqliteVdbeByteSwap((X) ^ 0x80000000))
00027 
00028 /*
00029 ** The makefile scans this source file and creates the following
00030 ** array of string constants which are the names of all VDBE opcodes.
00031 ** This array is defined in a separate source code file named opcode.c
00032 ** which is automatically generated by the makefile.
00033 */
00034 extern char *sqliteOpcodeNames[];
00035 
00036 /*
00037 ** SQL is translated into a sequence of instructions to be
00038 ** executed by a virtual machine.  Each instruction is an instance
00039 ** of the following structure.
00040 */
00041 typedef struct VdbeOp Op;
00042 
00043 /*
00044 ** Boolean values
00045 */
00046 typedef unsigned char Bool;
00047 
00048 /*
00049 ** A cursor is a pointer into a single BTree within a database file.
00050 ** The cursor can seek to a BTree entry with a particular key, or
00051 ** loop over all entries of the Btree.  You can also insert new BTree
00052 ** entries or retrieve the key or data from the entry that the cursor
00053 ** is currently pointing to.
00054 ** 
00055 ** Every cursor that the virtual machine has open is represented by an
00056 ** instance of the following structure.
00057 **
00058 ** If the Cursor.isTriggerRow flag is set it means that this cursor is
00059 ** really a single row that represents the NEW or OLD pseudo-table of
00060 ** a row trigger.  The data for the row is stored in Cursor.pData and
00061 ** the rowid is in Cursor.iKey.
00062 */
00063 struct Cursor {
00064   BtCursor *pCursor;    /* The cursor structure of the backend */
00065   int lastRecno;        /* Last recno from a Next or NextIdx operation */
00066   int nextRowid;        /* Next rowid returned by OP_NewRowid */
00067   Bool recnoIsValid;    /* True if lastRecno is valid */
00068   Bool keyAsData;       /* The OP_Column command works on key instead of data */
00069   Bool atFirst;         /* True if pointing to first entry */
00070   Bool useRandomRowid;  /* Generate new record numbers semi-randomly */
00071   Bool nullRow;         /* True if pointing to a row with no data */
00072   Bool nextRowidValid;  /* True if the nextRowid field is valid */
00073   Bool pseudoTable;     /* This is a NEW or OLD pseudo-tables of a trigger */
00074   Bool deferredMoveto;  /* A call to sqliteBtreeMoveto() is needed */
00075   int movetoTarget;     /* Argument to the deferred sqliteBtreeMoveto() */
00076   Btree *pBt;           /* Separate file holding temporary table */
00077   int nData;            /* Number of bytes in pData */
00078   char *pData;          /* Data for a NEW or OLD pseudo-table */
00079   int iKey;             /* Key for the NEW or OLD pseudo-table row */
00080 };
00081 typedef struct Cursor Cursor;
00082 
00083 /*
00084 ** A sorter builds a list of elements to be sorted.  Each element of
00085 ** the list is an instance of the following structure.
00086 */
00087 typedef struct Sorter Sorter;
00088 struct Sorter {
00089   int nKey;           /* Number of bytes in the key */
00090   char *zKey;         /* The key by which we will sort */
00091   int nData;          /* Number of bytes in the data */
00092   char *pData;        /* The data associated with this key */
00093   Sorter *pNext;      /* Next in the list */
00094 };
00095 
00096 /* 
00097 ** Number of buckets used for merge-sort.  
00098 */
00099 #define NSORT 30
00100 
00101 /*
00102 ** Number of bytes of string storage space available to each stack
00103 ** layer without having to malloc.  NBFS is short for Number of Bytes
00104 ** For Strings.
00105 */
00106 #define NBFS 32
00107 
00108 /*
00109 ** A single level of the stack or a single memory cell
00110 ** is an instance of the following structure. 
00111 */
00112 struct Mem {
00113   int i;              /* Integer value */
00114   int n;              /* Number of characters in string value, including '\0' */
00115   int flags;          /* Some combination of MEM_Null, MEM_Str, MEM_Dyn, etc. */
00116   double r;           /* Real value */
00117   char *z;            /* String value */
00118   char zShort[NBFS];  /* Space for short strings */
00119 };
00120 typedef struct Mem Mem;
00121 
00122 /*
00123 ** Allowed values for Mem.flags
00124 */
00125 #define MEM_Null      0x0001   /* Value is NULL */
00126 #define MEM_Str       0x0002   /* Value is a string */
00127 #define MEM_Int       0x0004   /* Value is an integer */
00128 #define MEM_Real      0x0008   /* Value is a real number */
00129 #define MEM_Dyn       0x0010   /* Need to call sqliteFree() on Mem.z */
00130 #define MEM_Static    0x0020   /* Mem.z points to a static string */
00131 #define MEM_Ephem     0x0040   /* Mem.z points to an ephemeral string */
00132 #define MEM_Short     0x0080   /* Mem.z points to Mem.zShort */
00133 
00134 /* The following MEM_ value appears only in AggElem.aMem.s.flag fields.
00135 ** It indicates that the corresponding AggElem.aMem.z points to a
00136 ** aggregate function context that needs to be finalized.
00137 */
00138 #define MEM_AggCtx    0x0100   /* Mem.z points to an agg function context */
00139 
00140 /*
00141 ** The "context" argument for a installable function.  A pointer to an
00142 ** instance of this structure is the first argument to the routines used
00143 ** implement the SQL functions.
00144 **
00145 ** There is a typedef for this structure in sqlite.h.  So all routines,
00146 ** even the public interface to SQLite, can use a pointer to this structure.
00147 ** But this file is the only place where the internal details of this
00148 ** structure are known.
00149 **
00150 ** This structure is defined inside of vdbe.c because it uses substructures
00151 ** (Mem) which are only defined there.
00152 */
00153 struct sqlite_func {
00154   FuncDef *pFunc;   /* Pointer to function information.  MUST BE FIRST */
00155   Mem s;            /* The return value is stored here */
00156   void *pAgg;       /* Aggregate context */
00157   u8 isError;       /* Set to true for an error */
00158   u8 isStep;        /* Current in the step function */
00159   int cnt;          /* Number of times that the step function has been called */
00160 };
00161 
00162 /*
00163 ** An Agg structure describes an Aggregator.  Each Agg consists of
00164 ** zero or more Aggregator elements (AggElem).  Each AggElem contains
00165 ** a key and one or more values.  The values are used in processing
00166 ** aggregate functions in a SELECT.  The key is used to implement
00167 ** the GROUP BY clause of a select.
00168 */
00169 typedef struct Agg Agg;
00170 typedef struct AggElem AggElem;
00171 struct Agg {
00172   int nMem;            /* Number of values stored in each AggElem */
00173   AggElem *pCurrent;   /* The AggElem currently in focus */
00174   HashElem *pSearch;   /* The hash element for pCurrent */
00175   Hash hash;           /* Hash table of all aggregate elements */
00176   FuncDef **apFunc;    /* Information about aggregate functions */
00177 };
00178 struct AggElem {
00179   char *zKey;          /* The key to this AggElem */
00180   int nKey;            /* Number of bytes in the key, including '\0' at end */
00181   Mem aMem[1];         /* The values for this AggElem */
00182 };
00183 
00184 /*
00185 ** A Set structure is used for quick testing to see if a value
00186 ** is part of a small set.  Sets are used to implement code like
00187 ** this:
00188 **            x.y IN ('hi','hoo','hum')
00189 */
00190 typedef struct Set Set;
00191 struct Set {
00192   Hash hash;             /* A set is just a hash table */
00193   HashElem *prev;        /* Previously accessed hash elemen */
00194 };
00195 
00196 /*
00197 ** A Keylist is a bunch of keys into a table.  The keylist can
00198 ** grow without bound.  The keylist stores the ROWIDs of database
00199 ** records that need to be deleted or updated.
00200 */
00201 typedef struct Keylist Keylist;
00202 struct Keylist {
00203   int nKey;         /* Number of slots in aKey[] */
00204   int nUsed;        /* Next unwritten slot in aKey[] */
00205   int nRead;        /* Next unread slot in aKey[] */
00206   Keylist *pNext;   /* Next block of keys */
00207   int aKey[1];      /* One or more keys.  Extra space allocated as needed */
00208 };
00209 
00210 /*
00211 ** A Context stores the last insert rowid, the last statement change count,
00212 ** and the current statement change count (i.e. changes since last statement).
00213 ** Elements of Context structure type make up the ContextStack, which is
00214 ** updated by the ContextPush and ContextPop opcodes (used by triggers)
00215 */
00216 typedef struct Context Context;
00217 struct Context {
00218   int lastRowid;    /* Last insert rowid (from db->lastRowid) */
00219   int lsChange;     /* Last statement change count (from db->lsChange) */
00220   int csChange;     /* Current statement change count (from db->csChange) */
00221 };
00222 
00223 /*
00224 ** An instance of the virtual machine.  This structure contains the complete
00225 ** state of the virtual machine.
00226 **
00227 ** The "sqlite_vm" structure pointer that is returned by sqlite_compile()
00228 ** is really a pointer to an instance of this structure.
00229 */
00230 struct Vdbe {
00231   sqlite *db;         /* The whole database */
00232   Vdbe *pPrev,*pNext; /* Linked list of VDBEs with the same Vdbe.db */
00233   FILE *trace;        /* Write an execution trace here, if not NULL */
00234   int nOp;            /* Number of instructions in the program */
00235   int nOpAlloc;       /* Number of slots allocated for aOp[] */
00236   Op *aOp;            /* Space to hold the virtual machine's program */
00237   int nLabel;         /* Number of labels used */
00238   int nLabelAlloc;    /* Number of slots allocated in aLabel[] */
00239   int *aLabel;        /* Space to hold the labels */
00240   Mem *aStack;        /* The operand stack, except string values */
00241   Mem *pTos;          /* Top entry in the operand stack */
00242   char **zArgv;       /* Text values used by the callback */
00243   char **azColName;   /* Becomes the 4th parameter to callbacks */
00244   int nCursor;        /* Number of slots in aCsr[] */
00245   Cursor *aCsr;       /* One element of this array for each open cursor */
00246   Sorter *pSort;      /* A linked list of objects to be sorted */
00247   FILE *pFile;        /* At most one open file handler */
00248   int nField;         /* Number of file fields */
00249   char **azField;     /* Data for each file field */
00250   int nVar;           /* Number of entries in azVariable[] */
00251   char **azVar;       /* Values for the OP_Variable opcode */
00252   int *anVar;         /* Length of each value in azVariable[] */
00253   u8 *abVar;          /* TRUE if azVariable[i] needs to be sqliteFree()ed */
00254   char *zLine;            /* A single line from the input file */
00255   int nLineAlloc;         /* Number of spaces allocated for zLine */
00256   int magic;              /* Magic number for sanity checking */
00257   int nMem;               /* Number of memory locations currently allocated */
00258   Mem *aMem;              /* The memory locations */
00259   Agg agg;                /* Aggregate information */
00260   int nSet;               /* Number of sets allocated */
00261   Set *aSet;              /* An array of sets */
00262   int nCallback;          /* Number of callbacks invoked so far */
00263   Keylist *pList;         /* A list of ROWIDs */
00264   int keylistStackDepth;  /* The size of the "keylist" stack */
00265   Keylist **keylistStack; /* The stack used by opcodes ListPush & ListPop */
00266   int contextStackDepth;  /* The size of the "context" stack */
00267   Context *contextStack;  /* Stack used by opcodes ContextPush & ContextPop*/
00268   int pc;                 /* The program counter */
00269   int rc;                 /* Value to return */
00270   unsigned uniqueCnt;     /* Used by OP_MakeRecord when P2!=0 */
00271   int errorAction;        /* Recovery action to do in case of an error */
00272   int undoTransOnError;   /* If error, either ROLLBACK or COMMIT */
00273   int inTempTrans;        /* True if temp database is transactioned */
00274   int returnStack[100];   /* Return address stack for OP_Gosub & OP_Return */
00275   int returnDepth;        /* Next unused element in returnStack[] */
00276   int nResColumn;         /* Number of columns in one row of the result set */
00277   char **azResColumn;     /* Values for one row of result */ 
00278   int popStack;           /* Pop the stack this much on entry to VdbeExec() */
00279   char *zErrMsg;          /* Error message written here */
00280   u8 explain;             /* True if EXPLAIN present on SQL command */
00281 };
00282 
00283 /*
00284 ** The following are allowed values for Vdbe.magic
00285 */
00286 #define VDBE_MAGIC_INIT     0x26bceaa5    /* Building a VDBE program */
00287 #define VDBE_MAGIC_RUN      0xbdf20da3    /* VDBE is ready to execute */
00288 #define VDBE_MAGIC_HALT     0x519c2973    /* VDBE has completed execution */
00289 #define VDBE_MAGIC_DEAD     0xb606c3c8    /* The VDBE has been deallocated */
00290 
00291 /*
00292 ** Function prototypes
00293 */
00294 void sqliteVdbeCleanupCursor(Cursor*);
00295 void sqliteVdbeSorterReset(Vdbe*);
00296 void sqliteVdbeAggReset(Agg*);
00297 void sqliteVdbeKeylistFree(Keylist*);
00298 void sqliteVdbePopStack(Vdbe*,int);
00299 int sqliteVdbeCursorMoveto(Cursor*);
00300 int sqliteVdbeByteSwap(int);
00301 #if !defined(NDEBUG) || defined(VDBE_PROFILE)
00302 void sqliteVdbePrintOp(FILE*, int, Op*);
00303 #endif