src/vdbeapi.c

   1 /*
   2 ** 2004 May 26
   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 **
  13 ** This file contains code use to implement APIs that are part of the
  14 ** VDBE.
  15 */
  16 #include "sqliteInt.h"
  17 #include "vdbeInt.h"
  18
  19 #ifndef SQLITE_OMIT_DEPRECATED
  20 /*
  21 ** Return TRUE (non-zero) of the statement supplied as an argument needs
  22 ** to be recompiled.  A statement needs to be recompiled whenever the
  23 ** execution environment changes in a way that would alter the program
  24 ** that sqlite3_prepare() generates.  For example, if new functions or
  25 ** collating sequences are registered or if an authorizer function is
  26 ** added or changed.
  27 */
  28 int sqlite3_expired(sqlite3_stmt *pStmt){
  29   Vdbe *p = (Vdbe*)pStmt;
  30   return p==0 || p->expired;
  31 }
  32 #endif
  33
  34 /*
  35 ** Check on a Vdbe to make sure it has not been finalized.  Log
  36 ** an error and return true if it has been finalized (or is otherwise
  37 ** invalid).  Return false if it is ok.
  38 */
  39 static int vdbeSafety(Vdbe *p){
  40   if( p->db==0 ){
  41     sqlite3_log(SQLITE_MISUSE, "API called with finalized prepared statement");
  42     return 1;
  43   }else{
  44     return 0;
  45   }
  46 }
  47 static int vdbeSafetyNotNull(Vdbe *p){
  48   if( p==0 ){
  49     sqlite3_log(SQLITE_MISUSE, "API called with NULL prepared statement");
  50     return 1;
  51   }else{
  52     return vdbeSafety(p);
  53   }
  54 }
  55
  56 #ifndef SQLITE_OMIT_TRACE
  57 /*
  58 ** Invoke the profile callback.  This routine is only called if we already
  59 ** know that the profile callback is defined and needs to be invoked.
  60 */
  61 static SQLITE_NOINLINE void invokeProfileCallback(sqlite3 *db, Vdbe *p){
  62   sqlite3_int64 iNow;
  63   sqlite3_int64 iElapse;
  64   assert( p->startTime>0 );
  65   assert( db->xProfile!=0 || (db->mTrace & SQLITE_TRACE_PROFILE)!=0 );
  66   assert( db->init.busy==0 );
  67   assert( p->zSql!=0 );
  68   sqlite3OsCurrentTimeInt64(db->pVfs, &iNow);
  69   iElapse = (iNow - p->startTime)*1000000;
  70   if( db->xProfile ){
  71     db->xProfile(db->pProfileArg, p->zSql, iElapse);
  72   }
  73   if( db->mTrace & SQLITE_TRACE_PROFILE ){
  74     db->xTrace(SQLITE_TRACE_PROFILE, db->pTraceArg, p, (void*)&iElapse);
  75   }
  76   p->startTime = 0;
  77 }
  78 /*
  79 ** The checkProfileCallback(DB,P) macro checks to see if a profile callback
  80 ** is needed, and it invokes the callback if it is needed.
  81 */
  82 # define checkProfileCallback(DB,P) \
  83    if( ((P)->startTime)>0 ){ invokeProfileCallback(DB,P); }
  84 #else
  85 # define checkProfileCallback(DB,P)  /*no-op*/
  86 #endif
  87
  88 /*
  89 ** The following routine destroys a virtual machine that is created by
  90 ** the sqlite3_compile() routine. The integer returned is an SQLITE_
  91 ** success/failure code that describes the result of executing the virtual
  92 ** machine.
  93 **
  94 ** This routine sets the error code and string returned by
  95 ** sqlite3_errcode(), sqlite3_errmsg() and sqlite3_errmsg16().
  96 */
  97 int sqlite3_finalize(sqlite3_stmt *pStmt){
  98   int rc;
  99   if( pStmt==0 ){
 100     /* IMPLEMENTATION-OF: R-57228-12904 Invoking sqlite3_finalize() on a NULL
 101     ** pointer is a harmless no-op. */
 102     rc = SQLITE_OK;
 103   }else{
 104     Vdbe *v = (Vdbe*)pStmt;
 105     sqlite3 *db = v->db;
 106     if( vdbeSafety(v) ) return SQLITE_MISUSE_BKPT;
 107     sqlite3_mutex_enter(db->mutex);
 108     checkProfileCallback(db, v);
 109     rc = sqlite3VdbeFinalize(v);
 110     rc = sqlite3ApiExit(db, rc);
 111     sqlite3LeaveMutexAndCloseZombie(db);
 112   }
 113   return rc;
 114 }
 115
 116 /*
 117 ** Terminate the current execution of an SQL statement and reset it
 118 ** back to its starting state so that it can be reused. A success code from
 119 ** the prior execution is returned.
 120 **
 121 ** This routine sets the error code and string returned by
 122 ** sqlite3_errcode(), sqlite3_errmsg() and sqlite3_errmsg16().
 123 */
 124 int sqlite3_reset(sqlite3_stmt *pStmt){
 125   int rc;
 126   if( pStmt==0 ){
 127     rc = SQLITE_OK;
 128   }else{
 129     Vdbe *v = (Vdbe*)pStmt;
 130     sqlite3 *db = v->db;
 131     sqlite3_mutex_enter(db->mutex);
 132     checkProfileCallback(db, v);
 133     rc = sqlite3VdbeReset(v);
 134     sqlite3VdbeRewind(v);
 135     assert( (rc & (db->errMask))==rc );
 136     rc = sqlite3ApiExit(db, rc);
 137     sqlite3_mutex_leave(db->mutex);
 138   }
 139   return rc;
 140 }
 141
 142 /*
 143 ** Set all the parameters in the compiled SQL statement to NULL.
 144 */
 145 int sqlite3_clear_bindings(sqlite3_stmt *pStmt){
 146   int i;
 147   int rc = SQLITE_OK;
 148   Vdbe *p = (Vdbe*)pStmt;
 149 #if SQLITE_THREADSAFE
 150   sqlite3_mutex *mutex = ((Vdbe*)pStmt)->db->mutex;
 151 #endif
 152   sqlite3_mutex_enter(mutex);
 153   for(i=0; i<p->nVar; i++){
 154     sqlite3VdbeMemRelease(&p->aVar[i]);
 155     p->aVar[i].flags = MEM_Null;
 156   }
 157   assert( (p->prepFlags & SQLITE_PREPARE_SAVESQL)!=0 || p->expmask==0 );
 158   if( p->expmask ){
 159     p->expired = 1;
 160   }
 161   sqlite3_mutex_leave(mutex);
 162   return rc;
 163 }
 164
 165
 166 /**************************** sqlite3_value_  *******************************
 167 ** The following routines extract information from a Mem or sqlite3_value
 168 ** structure.
 169 */
 170 const void *sqlite3_value_blob(sqlite3_value *pVal){
 171   Mem *p = (Mem*)pVal;
 172   if( p->flags & (MEM_Blob|MEM_Str) ){
 173     if( ExpandBlob(p)!=SQLITE_OK ){
 174       assert( p->flags==MEM_Null && p->z==0 );
 175       return 0;
 176     }
 177     p->flags |= MEM_Blob;
 178     return p->n ? p->z : 0;
 179   }else{
 180     return sqlite3_value_text(pVal);
 181   }
 182 }
 183 int sqlite3_value_bytes(sqlite3_value *pVal){
 184   return sqlite3ValueBytes(pVal, SQLITE_UTF8);
 185 }
 186 int sqlite3_value_bytes16(sqlite3_value *pVal){
 187   return sqlite3ValueBytes(pVal, SQLITE_UTF16NATIVE);
 188 }
 189 double sqlite3_value_double(sqlite3_value *pVal){
 190   return sqlite3VdbeRealValue((Mem*)pVal);
 191 }
 192 int sqlite3_value_int(sqlite3_value *pVal){
 193   return (int)sqlite3VdbeIntValue((Mem*)pVal);
 194 }
 195 sqlite_int64 sqlite3_value_int64(sqlite3_value *pVal){
 196   return sqlite3VdbeIntValue((Mem*)pVal);
 197 }
 198 unsigned int sqlite3_value_subtype(sqlite3_value *pVal){
 199   Mem *pMem = (Mem*)pVal;
 200   return ((pMem->flags & MEM_Subtype) ? pMem->eSubtype : 0);
 201 }
 202 void *sqlite3_value_pointer(sqlite3_value *pVal, const char *zPType){
 203   Mem *p = (Mem*)pVal;
 204   if( (p->flags&(MEM_TypeMask|MEM_Term|MEM_Subtype)) ==
 205                  (MEM_Null|MEM_Term|MEM_Subtype)
 206    && zPType!=0
 207    && p->eSubtype=='p'
 208    && strcmp(p->u.zPType, zPType)==0
 209   ){
 210     return (void*)p->z;
 211   }else{
 212     return 0;
 213   }
 214 }
 215 const unsigned char *sqlite3_value_text(sqlite3_value *pVal){
 216   return (const unsigned char *)sqlite3ValueText(pVal, SQLITE_UTF8);
 217 }
 218 #ifndef SQLITE_OMIT_UTF16
 219 const void *sqlite3_value_text16(sqlite3_value* pVal){
 220   return sqlite3ValueText(pVal, SQLITE_UTF16NATIVE);
 221 }
 222 const void *sqlite3_value_text16be(sqlite3_value *pVal){
 223   return sqlite3ValueText(pVal, SQLITE_UTF16BE);
 224 }
 225 const void *sqlite3_value_text16le(sqlite3_value *pVal){
 226   return sqlite3ValueText(pVal, SQLITE_UTF16LE);
 227 }
 228 #endif /* SQLITE_OMIT_UTF16 */
 229 /* EVIDENCE-OF: R-12793-43283 Every value in SQLite has one of five
 230 ** fundamental datatypes: 64-bit signed integer 64-bit IEEE floating
 231 ** point number string BLOB NULL
 232 */
 233 int sqlite3_value_type(sqlite3_value* pVal){
 234   static const u8 aType[] = {
 235      SQLITE_BLOB,     /* 0x00 */
 236      SQLITE_NULL,     /* 0x01 */
 237      SQLITE_TEXT,     /* 0x02 */
 238      SQLITE_NULL,     /* 0x03 */
 239      SQLITE_INTEGER,  /* 0x04 */
 240      SQLITE_NULL,     /* 0x05 */
 241      SQLITE_INTEGER,  /* 0x06 */
 242      SQLITE_NULL,     /* 0x07 */
 243      SQLITE_FLOAT,    /* 0x08 */
 244      SQLITE_NULL,     /* 0x09 */
 245      SQLITE_FLOAT,    /* 0x0a */
 246      SQLITE_NULL,     /* 0x0b */
 247      SQLITE_INTEGER,  /* 0x0c */
 248      SQLITE_NULL,     /* 0x0d */
 249      SQLITE_INTEGER,  /* 0x0e */
 250      SQLITE_NULL,     /* 0x0f */
 251      SQLITE_BLOB,     /* 0x10 */
 252      SQLITE_NULL,     /* 0x11 */
 253      SQLITE_TEXT,     /* 0x12 */
 254      SQLITE_NULL,     /* 0x13 */
 255      SQLITE_INTEGER,  /* 0x14 */
 256      SQLITE_NULL,     /* 0x15 */
 257      SQLITE_INTEGER,  /* 0x16 */
 258      SQLITE_NULL,     /* 0x17 */
 259      SQLITE_FLOAT,    /* 0x18 */
 260      SQLITE_NULL,     /* 0x19 */
 261      SQLITE_FLOAT,    /* 0x1a */
 262      SQLITE_NULL,     /* 0x1b */
 263      SQLITE_INTEGER,  /* 0x1c */
 264      SQLITE_NULL,     /* 0x1d */
 265      SQLITE_INTEGER,  /* 0x1e */
 266      SQLITE_NULL,     /* 0x1f */
 267   };
 268   return aType[pVal->flags&MEM_AffMask];
 269 }
 270
 271 /* Make a copy of an sqlite3_value object
 272 */
 273 sqlite3_value *sqlite3_value_dup(const sqlite3_value *pOrig){
 274   sqlite3_value *pNew;
 275   if( pOrig==0 ) return 0;
 276   pNew = sqlite3_malloc( sizeof(*pNew) );
 277   if( pNew==0 ) return 0;
 278   memset(pNew, 0, sizeof(*pNew));
 279   memcpy(pNew, pOrig, MEMCELLSIZE);
 280   pNew->flags &= ~MEM_Dyn;
 281   pNew->db = 0;
 282   if( pNew->flags&(MEM_Str|MEM_Blob) ){
 283     pNew->flags &= ~(MEM_Static|MEM_Dyn);
 284     pNew->flags |= MEM_Ephem;
 285     if( sqlite3VdbeMemMakeWriteable(pNew)!=SQLITE_OK ){
 286       sqlite3ValueFree(pNew);
 287       pNew = 0;
 288     }
 289   }
 290   return pNew;
 291 }
 292
 293 /* Destroy an sqlite3_value object previously obtained from
 294 ** sqlite3_value_dup().
 295 */
 296 void sqlite3_value_free(sqlite3_value *pOld){
 297   sqlite3ValueFree(pOld);
 298 }
 299
 300
 301 /**************************** sqlite3_result_  *******************************
 302 ** The following routines are used by user-defined functions to specify
 303 ** the function result.
 304 **
 305 ** The setStrOrError() function calls sqlite3VdbeMemSetStr() to store the
 306 ** result as a string or blob but if the string or blob is too large, it
 307 ** then sets the error code to SQLITE_TOOBIG
 308 **
 309 ** The invokeValueDestructor(P,X) routine invokes destructor function X()
 310 ** on value P is not going to be used and need to be destroyed.
 311 */
 312 static void setResultStrOrError(
 313   sqlite3_context *pCtx,  /* Function context */
 314   const char *z,          /* String pointer */
 315   int n,                  /* Bytes in string, or negative */
 316   u8 enc,                 /* Encoding of z.  0 for BLOBs */
 317   void (*xDel)(void*)     /* Destructor function */
 318 ){
 319   if( sqlite3VdbeMemSetStr(pCtx->pOut, z, n, enc, xDel)==SQLITE_TOOBIG ){
 320     sqlite3_result_error_toobig(pCtx);
 321   }
 322 }
 323 static int invokeValueDestructor(
 324   const void *p,             /* Value to destroy */
 325   void (*xDel)(void*),       /* The destructor */
 326   sqlite3_context *pCtx      /* Set a SQLITE_TOOBIG error if no NULL */
 327 ){
 328   assert( xDel!=SQLITE_DYNAMIC );
 329   if( xDel==0 ){
 330     /* noop */
 331   }else if( xDel==SQLITE_TRANSIENT ){
 332     /* noop */
 333   }else{
 334     xDel((void*)p);
 335   }
 336   if( pCtx ) sqlite3_result_error_toobig(pCtx);
 337   return SQLITE_TOOBIG;
 338 }
 339 void sqlite3_result_blob(
 340   sqlite3_context *pCtx,
 341   const void *z,
 342   int n,
 343   void (*xDel)(void *)
 344 ){
 345   assert( n>=0 );
 346   assert( sqlite3_mutex_held(pCtx->pOut->db->mutex) );
 347   setResultStrOrError(pCtx, z, n, 0, xDel);
 348 }
 349 void sqlite3_result_blob64(
 350   sqlite3_context *pCtx,
 351   const void *z,
 352   sqlite3_uint64 n,
 353   void (*xDel)(void *)
 354 ){
 355   assert( sqlite3_mutex_held(pCtx->pOut->db->mutex) );
 356   assert( xDel!=SQLITE_DYNAMIC );
 357   if( n>0x7fffffff ){
 358     (void)invokeValueDestructor(z, xDel, pCtx);
 359   }else{
 360     setResultStrOrError(pCtx, z, (int)n, 0, xDel);
 361   }
 362 }
 363 void sqlite3_result_double(sqlite3_context *pCtx, double rVal){
 364   assert( sqlite3_mutex_held(pCtx->pOut->db->mutex) );
 365   sqlite3VdbeMemSetDouble(pCtx->pOut, rVal);
 366 }
 367 void sqlite3_result_error(sqlite3_context *pCtx, const char *z, int n){
 368   assert( sqlite3_mutex_held(pCtx->pOut->db->mutex) );
 369   pCtx->isError = SQLITE_ERROR;
 370   pCtx->fErrorOrAux = 1;
 371   sqlite3VdbeMemSetStr(pCtx->pOut, z, n, SQLITE_UTF8, SQLITE_TRANSIENT);
 372 }
 373 #ifndef SQLITE_OMIT_UTF16
 374 void sqlite3_result_error16(sqlite3_context *pCtx, const void *z, int n){
 375   assert( sqlite3_mutex_held(pCtx->pOut->db->mutex) );
 376   pCtx->isError = SQLITE_ERROR;
 377   pCtx->fErrorOrAux = 1;
 378   sqlite3VdbeMemSetStr(pCtx->pOut, z, n, SQLITE_UTF16NATIVE, SQLITE_TRANSIENT);
 379 }
 380 #endif
 381 void sqlite3_result_int(sqlite3_context *pCtx, int iVal){
 382   assert( sqlite3_mutex_held(pCtx->pOut->db->mutex) );
 383   sqlite3VdbeMemSetInt64(pCtx->pOut, (i64)iVal);
 384 }
 385 void sqlite3_result_int64(sqlite3_context *pCtx, i64 iVal){
 386   assert( sqlite3_mutex_held(pCtx->pOut->db->mutex) );
 387   sqlite3VdbeMemSetInt64(pCtx->pOut, iVal);
 388 }
 389 void sqlite3_result_null(sqlite3_context *pCtx){
 390   assert( sqlite3_mutex_held(pCtx->pOut->db->mutex) );
 391   sqlite3VdbeMemSetNull(pCtx->pOut);
 392 }
 393 void sqlite3_result_pointer(
 394   sqlite3_context *pCtx,
 395   void *pPtr,
 396   const char *zPType,
 397   void (*xDestructor)(void*)
 398 ){
 399   Mem *pOut = pCtx->pOut;
 400   assert( sqlite3_mutex_held(pOut->db->mutex) );
 401   sqlite3VdbeMemSetNull(pOut);
 402   sqlite3VdbeMemSetPointer(pOut, pPtr, zPType, xDestructor);
 403 }
 404 void sqlite3_result_subtype(sqlite3_context *pCtx, unsigned int eSubtype){
 405   Mem *pOut = pCtx->pOut;
 406   assert( sqlite3_mutex_held(pOut->db->mutex) );
 407   pOut->eSubtype = eSubtype & 0xff;
 408   pOut->flags |= MEM_Subtype;
 409 }
 410 void sqlite3_result_text(
 411   sqlite3_context *pCtx,
 412   const char *z,
 413   int n,
 414   void (*xDel)(void *)
 415 ){
 416   assert( sqlite3_mutex_held(pCtx->pOut->db->mutex) );
 417   setResultStrOrError(pCtx, z, n, SQLITE_UTF8, xDel);
 418 }
 419 void sqlite3_result_text64(
 420   sqlite3_context *pCtx,
 421   const char *z,
 422   sqlite3_uint64 n,
 423   void (*xDel)(void *),
 424   unsigned char enc
 425 ){
 426   assert( sqlite3_mutex_held(pCtx->pOut->db->mutex) );
 427   assert( xDel!=SQLITE_DYNAMIC );
 428   if( enc==SQLITE_UTF16 ) enc = SQLITE_UTF16NATIVE;
 429   if( n>0x7fffffff ){
 430     (void)invokeValueDestructor(z, xDel, pCtx);
 431   }else{
 432     setResultStrOrError(pCtx, z, (int)n, enc, xDel);
 433   }
 434 }
 435 #ifndef SQLITE_OMIT_UTF16
 436 void sqlite3_result_text16(
 437   sqlite3_context *pCtx,
 438   const void *z,
 439   int n,
 440   void (*xDel)(void *)
 441 ){
 442   assert( sqlite3_mutex_held(pCtx->pOut->db->mutex) );
 443   setResultStrOrError(pCtx, z, n, SQLITE_UTF16NATIVE, xDel);
 444 }
 445 void sqlite3_result_text16be(
 446   sqlite3_context *pCtx,
 447   const void *z,
 448   int n,
 449   void (*xDel)(void *)
 450 ){
 451   assert( sqlite3_mutex_held(pCtx->pOut->db->mutex) );
 452   setResultStrOrError(pCtx, z, n, SQLITE_UTF16BE, xDel);
 453 }
 454 void sqlite3_result_text16le(
 455   sqlite3_context *pCtx,
 456   const void *z,
 457   int n,
 458   void (*xDel)(void *)
 459 ){
 460   assert( sqlite3_mutex_held(pCtx->pOut->db->mutex) );
 461   setResultStrOrError(pCtx, z, n, SQLITE_UTF16LE, xDel);
 462 }
 463 #endif /* SQLITE_OMIT_UTF16 */
 464 void sqlite3_result_value(sqlite3_context *pCtx, sqlite3_value *pValue){
 465   assert( sqlite3_mutex_held(pCtx->pOut->db->mutex) );
 466   sqlite3VdbeMemCopy(pCtx->pOut, pValue);
 467 }
 468 void sqlite3_result_zeroblob(sqlite3_context *pCtx, int n){
 469   assert( sqlite3_mutex_held(pCtx->pOut->db->mutex) );
 470   sqlite3VdbeMemSetZeroBlob(pCtx->pOut, n);
 471 }
 472 int sqlite3_result_zeroblob64(sqlite3_context *pCtx, u64 n){
 473   Mem *pOut = pCtx->pOut;
 474   assert( sqlite3_mutex_held(pOut->db->mutex) );
 475   if( n>(u64)pOut->db->aLimit[SQLITE_LIMIT_LENGTH] ){
 476     return SQLITE_TOOBIG;
 477   }
 478   sqlite3VdbeMemSetZeroBlob(pCtx->pOut, (int)n);
 479   return SQLITE_OK;
 480 }
 481 void sqlite3_result_error_code(sqlite3_context *pCtx, int errCode){
 482   pCtx->isError = errCode;
 483   pCtx->fErrorOrAux = 1;
 484 #ifdef SQLITE_DEBUG
 485   if( pCtx->pVdbe ) pCtx->pVdbe->rcApp = errCode;
 486 #endif
 487   if( pCtx->pOut->flags & MEM_Null ){
 488     sqlite3VdbeMemSetStr(pCtx->pOut, sqlite3ErrStr(errCode), -1,
 489                          SQLITE_UTF8, SQLITE_STATIC);
 490   }
 491 }
 492
 493 /* Force an SQLITE_TOOBIG error. */
 494 void sqlite3_result_error_toobig(sqlite3_context *pCtx){
 495   assert( sqlite3_mutex_held(pCtx->pOut->db->mutex) );
 496   pCtx->isError = SQLITE_TOOBIG;
 497   pCtx->fErrorOrAux = 1;
 498   sqlite3VdbeMemSetStr(pCtx->pOut, "string or blob too big", -1,
 499                        SQLITE_UTF8, SQLITE_STATIC);
 500 }
 501
 502 /* An SQLITE_NOMEM error. */
 503 void sqlite3_result_error_nomem(sqlite3_context *pCtx){
 504   assert( sqlite3_mutex_held(pCtx->pOut->db->mutex) );
 505   sqlite3VdbeMemSetNull(pCtx->pOut);
 506   pCtx->isError = SQLITE_NOMEM_BKPT;
 507   pCtx->fErrorOrAux = 1;
 508   sqlite3OomFault(pCtx->pOut->db);
 509 }
 510
 511 /*
 512 ** This function is called after a transaction has been committed. It
 513 ** invokes callbacks registered with sqlite3_wal_hook() as required.
 514 */
 515 static int doWalCallbacks(sqlite3 *db){
 516   int rc = SQLITE_OK;
 517 #ifndef SQLITE_OMIT_WAL
 518   int i;
 519   for(i=0; i<db->nDb; i++){
 520     Btree *pBt = db->aDb[i].pBt;
 521     if( pBt ){
 522       int nEntry;
 523       sqlite3BtreeEnter(pBt);
 524       nEntry = sqlite3PagerWalCallback(sqlite3BtreePager(pBt));
 525       sqlite3BtreeLeave(pBt);
 526       if( db->xWalCallback && nEntry>0 && rc==SQLITE_OK ){
 527         rc = db->xWalCallback(db->pWalArg, db, db->aDb[i].zDbSName, nEntry);
 528       }
 529     }
 530   }
 531 #endif
 532   return rc;
 533 }
 534
 535
 536 /*
 537 ** Execute the statement pStmt, either until a row of data is ready, the
 538 ** statement is completely executed or an error occurs.
 539 **
 540 ** This routine implements the bulk of the logic behind the sqlite_step()
 541 ** API.  The only thing omitted is the automatic recompile if a
 542 ** schema change has occurred.  That detail is handled by the
 543 ** outer sqlite3_step() wrapper procedure.
 544 */
 545 static int sqlite3Step(Vdbe *p){
 546   sqlite3 *db;
 547   int rc;
 548
 549   assert(p);
 550   if( p->magic!=VDBE_MAGIC_RUN ){
 551     /* We used to require that sqlite3_reset() be called before retrying
 552     ** sqlite3_step() after any error or after SQLITE_DONE.  But beginning
 553     ** with version 3.7.0, we changed this so that sqlite3_reset() would
 554     ** be called automatically instead of throwing the SQLITE_MISUSE error.
 555     ** This "automatic-reset" change is not technically an incompatibility,
 556     ** since any application that receives an SQLITE_MISUSE is broken by
 557     ** definition.
 558     **
 559     ** Nevertheless, some published applications that were originally written
 560     ** for version 3.6.23 or earlier do in fact depend on SQLITE_MISUSE
 561     ** returns, and those were broken by the automatic-reset change.  As a
 562     ** a work-around, the SQLITE_OMIT_AUTORESET compile-time restores the
 563     ** legacy behavior of returning SQLITE_MISUSE for cases where the
 564     ** previous sqlite3_step() returned something other than a SQLITE_LOCKED
 565     ** or SQLITE_BUSY error.
 566     */
 567 #ifdef SQLITE_OMIT_AUTORESET
 568     if( (rc = p->rc&0xff)==SQLITE_BUSY || rc==SQLITE_LOCKED ){
 569       sqlite3_reset((sqlite3_stmt*)p);
 570     }else{
 571       return SQLITE_MISUSE_BKPT;
 572     }
 573 #else
 574     sqlite3_reset((sqlite3_stmt*)p);
 575 #endif
 576   }
 577
 578   /* Check that malloc() has not failed. If it has, return early. */
 579   db = p->db;
 580   if( db->mallocFailed ){
 581     p->rc = SQLITE_NOMEM;
 582     return SQLITE_NOMEM_BKPT;
 583   }
 584
 585   if( p->pc<=0 && p->expired ){
 586     p->rc = SQLITE_SCHEMA;
 587     rc = SQLITE_ERROR;
 588     goto end_of_step;
 589   }
 590   if( p->pc<0 ){
 591     /* If there are no other statements currently running, then
 592     ** reset the interrupt flag.  This prevents a call to sqlite3_interrupt
 593     ** from interrupting a statement that has not yet started.
 594     */
 595     if( db->nVdbeActive==0 ){
 596       db->u1.isInterrupted = 0;
 597     }
 598
 599     assert( db->nVdbeWrite>0 || db->autoCommit==0
 600         || (db->nDeferredCons==0 && db->nDeferredImmCons==0)
 601     );
 602
 603 #ifndef SQLITE_OMIT_TRACE
 604     if( (db->xProfile || (db->mTrace & SQLITE_TRACE_PROFILE)!=0)
 605         && !db->init.busy && p->zSql ){
 606       sqlite3OsCurrentTimeInt64(db->pVfs, &p->startTime);
 607     }else{
 608       assert( p->startTime==0 );
 609     }
 610 #endif
 611
 612     db->nVdbeActive++;
 613     if( p->readOnly==0 ) db->nVdbeWrite++;
 614     if( p->bIsReader ) db->nVdbeRead++;
 615     p->pc = 0;
 616   }
 617 #ifdef SQLITE_DEBUG
 618   p->rcApp = SQLITE_OK;
 619 #endif
 620 #ifndef SQLITE_OMIT_EXPLAIN
 621   if( p->explain ){
 622     rc = sqlite3VdbeList(p);
 623   }else
 624 #endif /* SQLITE_OMIT_EXPLAIN */
 625   {
 626     db->nVdbeExec++;
 627     rc = sqlite3VdbeExec(p);
 628     db->nVdbeExec--;
 629   }
 630
 631 #ifndef SQLITE_OMIT_TRACE
 632   /* If the statement completed successfully, invoke the profile callback */
 633   if( rc!=SQLITE_ROW ) checkProfileCallback(db, p);
 634 #endif
 635
 636   if( rc==SQLITE_DONE ){
 637     assert( p->rc==SQLITE_OK );
 638     p->rc = doWalCallbacks(db);
 639     if( p->rc!=SQLITE_OK ){
 640       rc = SQLITE_ERROR;
 641     }
 642   }
 643
 644   db->errCode = rc;
 645   if( SQLITE_NOMEM==sqlite3ApiExit(p->db, p->rc) ){
 646     p->rc = SQLITE_NOMEM_BKPT;
 647   }
 648 end_of_step:
 649   /* At this point local variable rc holds the value that should be
 650   ** returned if this statement was compiled using the legacy
 651   ** sqlite3_prepare() interface. According to the docs, this can only
 652   ** be one of the values in the first assert() below. Variable p->rc
 653   ** contains the value that would be returned if sqlite3_finalize()
 654   ** were called on statement p.
 655   */
 656   assert( rc==SQLITE_ROW  || rc==SQLITE_DONE   || rc==SQLITE_ERROR
 657        || (rc&0xff)==SQLITE_BUSY || rc==SQLITE_MISUSE
 658   );
 659   assert( (p->rc!=SQLITE_ROW && p->rc!=SQLITE_DONE) || p->rc==p->rcApp );
 660   if( (p->prepFlags & SQLITE_PREPARE_SAVESQL)!=0
 661    && rc!=SQLITE_ROW
 662    && rc!=SQLITE_DONE
 663   ){
 664     /* If this statement was prepared using saved SQL and an
 665     ** error has occurred, then return the error code in p->rc to the
 666     ** caller. Set the error code in the database handle to the same value.
 667     */
 668     rc = sqlite3VdbeTransferError(p);
 669   }
 670   return (rc&db->errMask);
 671 }
 672
 673 /*
 674 ** This is the top-level implementation of sqlite3_step().  Call
 675 ** sqlite3Step() to do most of the work.  If a schema error occurs,
 676 ** call sqlite3Reprepare() and try again.
 677 */
 678 int sqlite3_step(sqlite3_stmt *pStmt){
 679   int rc = SQLITE_OK;      /* Result from sqlite3Step() */
 680   int rc2 = SQLITE_OK;     /* Result from sqlite3Reprepare() */
 681   Vdbe *v = (Vdbe*)pStmt;  /* the prepared statement */
 682   int cnt = 0;             /* Counter to prevent infinite loop of reprepares */
 683   sqlite3 *db;             /* The database connection */
 684
 685   if( vdbeSafetyNotNull(v) ){
 686     return SQLITE_MISUSE_BKPT;
 687   }
 688   db = v->db;
 689   sqlite3_mutex_enter(db->mutex);
 690   v->doingRerun = 0;
 691   while( (rc = sqlite3Step(v))==SQLITE_SCHEMA
 692          && cnt++ < SQLITE_MAX_SCHEMA_RETRY ){
 693     int savedPc = v->pc;
 694     rc2 = rc = sqlite3Reprepare(v);
 695     if( rc!=SQLITE_OK) break;
 696     sqlite3_reset(pStmt);
 697     if( savedPc>=0 ) v->doingRerun = 1;
 698     assert( v->expired==0 );
 699   }
 700   if( rc2!=SQLITE_OK ){
 701     /* This case occurs after failing to recompile an sql statement.
 702     ** The error message from the SQL compiler has already been loaded
 703     ** into the database handle. This block copies the error message
 704     ** from the database handle into the statement and sets the statement
 705     ** program counter to 0 to ensure that when the statement is
 706     ** finalized or reset the parser error message is available via
 707     ** sqlite3_errmsg() and sqlite3_errcode().
 708     */
 709     const char *zErr = (const char *)sqlite3_value_text(db->pErr);
 710     sqlite3DbFree(db, v->zErrMsg);
 711     if( !db->mallocFailed ){
 712       v->zErrMsg = sqlite3DbStrDup(db, zErr);
 713       v->rc = rc2;
 714     } else {
 715       v->zErrMsg = 0;
 716       v->rc = rc = SQLITE_NOMEM_BKPT;
 717     }
 718   }
 719   rc = sqlite3ApiExit(db, rc);
 720   sqlite3_mutex_leave(db->mutex);
 721   return rc;
 722 }
 723
 724
 725 /*
 726 ** Extract the user data from a sqlite3_context structure and return a
 727 ** pointer to it.
 728 */
 729 void *sqlite3_user_data(sqlite3_context *p){
 730   assert( p && p->pFunc );
 731   return p->pFunc->pUserData;
 732 }
 733
 734 /*
 735 ** Extract the user data from a sqlite3_context structure and return a
 736 ** pointer to it.
 737 **
 738 ** IMPLEMENTATION-OF: R-46798-50301 The sqlite3_context_db_handle() interface
 739 ** returns a copy of the pointer to the database connection (the 1st
 740 ** parameter) of the sqlite3_create_function() and
 741 ** sqlite3_create_function16() routines that originally registered the
 742 ** application defined function.
 743 */
 744 sqlite3 *sqlite3_context_db_handle(sqlite3_context *p){
 745   assert( p && p->pOut );
 746   return p->pOut->db;
 747 }
 748
 749 /*
 750 ** Return the current time for a statement.  If the current time
 751 ** is requested more than once within the same run of a single prepared
 752 ** statement, the exact same time is returned for each invocation regardless
 753 ** of the amount of time that elapses between invocations.  In other words,
 754 ** the time returned is always the time of the first call.
 755 */
 756 sqlite3_int64 sqlite3StmtCurrentTime(sqlite3_context *p){
 757   int rc;
 758 #ifndef SQLITE_ENABLE_STAT3_OR_STAT4
 759   sqlite3_int64 *piTime = &p->pVdbe->iCurrentTime;
 760   assert( p->pVdbe!=0 );
 761 #else
 762   sqlite3_int64 iTime = 0;
 763   sqlite3_int64 *piTime = p->pVdbe!=0 ? &p->pVdbe->iCurrentTime : &iTime;
 764 #endif
 765   if( *piTime==0 ){
 766     rc = sqlite3OsCurrentTimeInt64(p->pOut->db->pVfs, piTime);
 767     if( rc ) *piTime = 0;
 768   }
 769   return *piTime;
 770 }
 771
 772 /*
 773 ** The following is the implementation of an SQL function that always
 774 ** fails with an error message stating that the function is used in the
 775 ** wrong context.  The sqlite3_overload_function() API might construct
 776 ** SQL function that use this routine so that the functions will exist
 777 ** for name resolution but are actually overloaded by the xFindFunction
 778 ** method of virtual tables.
 779 */
 780 void sqlite3InvalidFunction(
 781   sqlite3_context *context,  /* The function calling context */
 782   int NotUsed,               /* Number of arguments to the function */
 783   sqlite3_value **NotUsed2   /* Value of each argument */
 784 ){
 785   const char *zName = context->pFunc->zName;
 786   char *zErr;
 787   UNUSED_PARAMETER2(NotUsed, NotUsed2);
 788   zErr = sqlite3_mprintf(
 789       "unable to use function %s in the requested context", zName);
 790   sqlite3_result_error(context, zErr, -1);
 791   sqlite3_free(zErr);
 792 }
 793
 794 /*
 795 ** Create a new aggregate context for p and return a pointer to
 796 ** its pMem->z element.
 797 */
 798 static SQLITE_NOINLINE void *createAggContext(sqlite3_context *p, int nByte){
 799   Mem *pMem = p->pMem;
 800   assert( (pMem->flags & MEM_Agg)==0 );
 801   if( nByte<=0 ){
 802     sqlite3VdbeMemSetNull(pMem);
 803     pMem->z = 0;
 804   }else{
 805     sqlite3VdbeMemClearAndResize(pMem, nByte);
 806     pMem->flags = MEM_Agg;
 807     pMem->u.pDef = p->pFunc;
 808     if( pMem->z ){
 809       memset(pMem->z, 0, nByte);
 810     }
 811   }
 812   return (void*)pMem->z;
 813 }
 814
 815 /*
 816 ** Allocate or return the aggregate context for a user function.  A new
 817 ** context is allocated on the first call.  Subsequent calls return the
 818 ** same context that was returned on prior calls.
 819 */
 820 void *sqlite3_aggregate_context(sqlite3_context *p, int nByte){
 821   assert( p && p->pFunc && p->pFunc->xFinalize );
 822   assert( sqlite3_mutex_held(p->pOut->db->mutex) );
 823   testcase( nByte<0 );
 824   if( (p->pMem->flags & MEM_Agg)==0 ){
 825     return createAggContext(p, nByte);
 826   }else{
 827     return (void*)p->pMem->z;
 828   }
 829 }
 830
 831 /*
 832 ** Return the auxiliary data pointer, if any, for the iArg'th argument to
 833 ** the user-function defined by pCtx.
 834 **
 835 ** The left-most argument is 0.
 836 **
 837 ** Undocumented behavior:  If iArg is negative then access a cache of
 838 ** auxiliary data pointers that is available to all functions within a
 839 ** single prepared statement.  The iArg values must match.
 840 */
 841 void *sqlite3_get_auxdata(sqlite3_context *pCtx, int iArg){
 842   AuxData *pAuxData;
 843
 844   assert( sqlite3_mutex_held(pCtx->pOut->db->mutex) );
 845 #if SQLITE_ENABLE_STAT3_OR_STAT4
 846   if( pCtx->pVdbe==0 ) return 0;
 847 #else
 848   assert( pCtx->pVdbe!=0 );
 849 #endif
 850   for(pAuxData=pCtx->pVdbe->pAuxData; pAuxData; pAuxData=pAuxData->pNextAux){
 851     if(  pAuxData->iAuxArg==iArg && (pAuxData->iAuxOp==pCtx->iOp || iArg<0) ){
 852       return pAuxData->pAux;
 853     }
 854   }
 855   return 0;
 856 }
 857
 858 /*
 859 ** Set the auxiliary data pointer and delete function, for the iArg'th
 860 ** argument to the user-function defined by pCtx. Any previous value is
 861 ** deleted by calling the delete function specified when it was set.
 862 **
 863 ** The left-most argument is 0.
 864 **
 865 ** Undocumented behavior:  If iArg is negative then make the data available
 866 ** to all functions within the current prepared statement using iArg as an
 867 ** access code.
 868 */
 869 void sqlite3_set_auxdata(
 870   sqlite3_context *pCtx,
 871   int iArg,
 872   void *pAux,
 873   void (*xDelete)(void*)
 874 ){
 875   AuxData *pAuxData;
 876   Vdbe *pVdbe = pCtx->pVdbe;
 877
 878   assert( sqlite3_mutex_held(pCtx->pOut->db->mutex) );
 879 #ifdef SQLITE_ENABLE_STAT3_OR_STAT4
 880   if( pVdbe==0 ) goto failed;
 881 #else
 882   assert( pVdbe!=0 );
 883 #endif
 884
 885   for(pAuxData=pVdbe->pAuxData; pAuxData; pAuxData=pAuxData->pNextAux){
 886     if( pAuxData->iAuxArg==iArg && (pAuxData->iAuxOp==pCtx->iOp || iArg<0) ){
 887       break;
 888     }
 889   }
 890   if( pAuxData==0 ){
 891     pAuxData = sqlite3DbMallocZero(pVdbe->db, sizeof(AuxData));
 892     if( !pAuxData ) goto failed;
 893     pAuxData->iAuxOp = pCtx->iOp;
 894     pAuxData->iAuxArg = iArg;
 895     pAuxData->pNextAux = pVdbe->pAuxData;
 896     pVdbe->pAuxData = pAuxData;
 897     if( pCtx->fErrorOrAux==0 ){
 898       pCtx->isError = 0;
 899       pCtx->fErrorOrAux = 1;
 900     }
 901   }else if( pAuxData->xDeleteAux ){
 902     pAuxData->xDeleteAux(pAuxData->pAux);
 903   }
 904
 905   pAuxData->pAux = pAux;
 906   pAuxData->xDeleteAux = xDelete;
 907   return;
 908
 909 failed:
 910   if( xDelete ){
 911     xDelete(pAux);
 912   }
 913 }
 914
 915 #ifndef SQLITE_OMIT_DEPRECATED
 916 /*
 917 ** Return the number of times the Step function of an aggregate has been
 918 ** called.
 919 **
 920 ** This function is deprecated.  Do not use it for new code.  It is
 921 ** provide only to avoid breaking legacy code.  New aggregate function
 922 ** implementations should keep their own counts within their aggregate
 923 ** context.
 924 */
 925 int sqlite3_aggregate_count(sqlite3_context *p){
 926   assert( p && p->pMem && p->pFunc && p->pFunc->xFinalize );
 927   return p->pMem->n;
 928 }
 929 #endif
 930
 931 /*
 932 ** Return the number of columns in the result set for the statement pStmt.
 933 */
 934 int sqlite3_column_count(sqlite3_stmt *pStmt){
 935   Vdbe *pVm = (Vdbe *)pStmt;
 936   return pVm ? pVm->nResColumn : 0;
 937 }
 938
 939 /*
 940 ** Return the number of values available from the current row of the
 941 ** currently executing statement pStmt.
 942 */
 943 int sqlite3_data_count(sqlite3_stmt *pStmt){
 944   Vdbe *pVm = (Vdbe *)pStmt;
 945   if( pVm==0 || pVm->pResultSet==0 ) return 0;
 946   return pVm->nResColumn;
 947 }
 948
 949 /*
 950 ** Return a pointer to static memory containing an SQL NULL value.
 951 */
 952 static const Mem *columnNullValue(void){
 953   /* Even though the Mem structure contains an element
 954   ** of type i64, on certain architectures (x86) with certain compiler
 955   ** switches (-Os), gcc may align this Mem object on a 4-byte boundary
 956   ** instead of an 8-byte one. This all works fine, except that when
 957   ** running with SQLITE_DEBUG defined the SQLite code sometimes assert()s
 958   ** that a Mem structure is located on an 8-byte boundary. To prevent
 959   ** these assert()s from failing, when building with SQLITE_DEBUG defined
 960   ** using gcc, we force nullMem to be 8-byte aligned using the magical
 961   ** __attribute__((aligned(8))) macro.  */
 962   static const Mem nullMem
 963 #if defined(SQLITE_DEBUG) && defined(__GNUC__)
 964     __attribute__((aligned(8)))
 965 #endif
 966     = {
 967         /* .u          = */ {0},
 968         /* .flags      = */ (u16)MEM_Null,
 969         /* .enc        = */ (u8)0,
 970         /* .eSubtype   = */ (u8)0,
 971         /* .n          = */ (int)0,
 972         /* .z          = */ (char*)0,
 973         /* .zMalloc    = */ (char*)0,
 974         /* .szMalloc   = */ (int)0,
 975         /* .uTemp      = */ (u32)0,
 976         /* .db         = */ (sqlite3*)0,
 977         /* .xDel       = */ (void(*)(void*))0,
 978 #ifdef SQLITE_DEBUG
 979         /* .pScopyFrom = */ (Mem*)0,
 980         /* .pFiller    = */ (void*)0,
 981 #endif
 982       };
 983   return &nullMem;
 984 }
 985
 986 /*
 987 ** Check to see if column iCol of the given statement is valid.  If
 988 ** it is, return a pointer to the Mem for the value of that column.
 989 ** If iCol is not valid, return a pointer to a Mem which has a value
 990 ** of NULL.
 991 */
 992 static Mem *columnMem(sqlite3_stmt *pStmt, int i){
 993   Vdbe *pVm;
 994   Mem *pOut;
 995
 996   pVm = (Vdbe *)pStmt;
 997   if( pVm==0 ) return (Mem*)columnNullValue();
 998   assert( pVm->db );
 999   sqlite3_mutex_enter(pVm->db->mutex);
1000   if( pVm->pResultSet!=0 && i<pVm->nResColumn && i>=0 ){
1001     pOut = &pVm->pResultSet[i];
1002   }else{
1003     sqlite3Error(pVm->db, SQLITE_RANGE);
1004     pOut = (Mem*)columnNullValue();
1005   }
1006   return pOut;
1007 }
1008
1009 /*
1010 ** This function is called after invoking an sqlite3_value_XXX function on a
1011 ** column value (i.e. a value returned by evaluating an SQL expression in the
1012 ** select list of a SELECT statement) that may cause a malloc() failure. If
1013 ** malloc() has failed, the threads mallocFailed flag is cleared and the result
1014 ** code of statement pStmt set to SQLITE_NOMEM.
1015 **
1016 ** Specifically, this is called from within:
1017 **
1018 **     sqlite3_column_int()
1019 **     sqlite3_column_int64()
1020 **     sqlite3_column_text()
1021 **     sqlite3_column_text16()
1022 **     sqlite3_column_real()
1023 **     sqlite3_column_bytes()
1024 **     sqlite3_column_bytes16()
1025 **     sqiite3_column_blob()
1026 */
1027 static void columnMallocFailure(sqlite3_stmt *pStmt)
1028 {
1029   /* If malloc() failed during an encoding conversion within an
1030   ** sqlite3_column_XXX API, then set the return code of the statement to
1031   ** SQLITE_NOMEM. The next call to _step() (if any) will return SQLITE_ERROR
1032   ** and _finalize() will return NOMEM.
1033   */
1034   Vdbe *p = (Vdbe *)pStmt;
1035   if( p ){
1036     assert( p->db!=0 );
1037     assert( sqlite3_mutex_held(p->db->mutex) );
1038     p->rc = sqlite3ApiExit(p->db, p->rc);
1039     sqlite3_mutex_leave(p->db->mutex);
1040   }
1041 }
1042
1043 /**************************** sqlite3_column_  *******************************
1044 ** The following routines are used to access elements of the current row
1045 ** in the result set.
1046 */
1047 const void *sqlite3_column_blob(sqlite3_stmt *pStmt, int i){
1048   const void *val;
1049   val = sqlite3_value_blob( columnMem(pStmt,i) );
1050   /* Even though there is no encoding conversion, value_blob() might
1051   ** need to call malloc() to expand the result of a zeroblob()
1052   ** expression.
1053   */
1054   columnMallocFailure(pStmt);
1055   return val;
1056 }
1057 int sqlite3_column_bytes(sqlite3_stmt *pStmt, int i){
1058   int val = sqlite3_value_bytes( columnMem(pStmt,i) );
1059   columnMallocFailure(pStmt);
1060   return val;
1061 }
1062 int sqlite3_column_bytes16(sqlite3_stmt *pStmt, int i){
1063   int val = sqlite3_value_bytes16( columnMem(pStmt,i) );
1064   columnMallocFailure(pStmt);
1065   return val;
1066 }
1067 double sqlite3_column_double(sqlite3_stmt *pStmt, int i){
1068   double val = sqlite3_value_double( columnMem(pStmt,i) );
1069   columnMallocFailure(pStmt);
1070   return val;
1071 }
1072 int sqlite3_column_int(sqlite3_stmt *pStmt, int i){
1073   int val = sqlite3_value_int( columnMem(pStmt,i) );
1074   columnMallocFailure(pStmt);
1075   return val;
1076 }
1077 sqlite_int64 sqlite3_column_int64(sqlite3_stmt *pStmt, int i){
1078   sqlite_int64 val = sqlite3_value_int64( columnMem(pStmt,i) );
1079   columnMallocFailure(pStmt);
1080   return val;
1081 }
1082 const unsigned char *sqlite3_column_text(sqlite3_stmt *pStmt, int i){
1083   const unsigned char *val = sqlite3_value_text( columnMem(pStmt,i) );
1084   columnMallocFailure(pStmt);
1085   return val;
1086 }
1087 sqlite3_value *sqlite3_column_value(sqlite3_stmt *pStmt, int i){
1088   Mem *pOut = columnMem(pStmt, i);
1089   if( pOut->flags&MEM_Static ){
1090     pOut->flags &= ~MEM_Static;
1091     pOut->flags |= MEM_Ephem;
1092   }
1093   columnMallocFailure(pStmt);
1094   return (sqlite3_value *)pOut;
1095 }
1096 #ifndef SQLITE_OMIT_UTF16
1097 const void *sqlite3_column_text16(sqlite3_stmt *pStmt, int i){
1098   const void *val = sqlite3_value_text16( columnMem(pStmt,i) );
1099   columnMallocFailure(pStmt);
1100   return val;
1101 }
1102 #endif /* SQLITE_OMIT_UTF16 */
1103 int sqlite3_column_type(sqlite3_stmt *pStmt, int i){
1104   int iType = sqlite3_value_type( columnMem(pStmt,i) );
1105   columnMallocFailure(pStmt);
1106   return iType;
1107 }
1108
1109 /*
1110 ** Convert the N-th element of pStmt->pColName[] into a string using
1111 ** xFunc() then return that string.  If N is out of range, return 0.
1112 **
1113 ** There are up to 5 names for each column.  useType determines which
1114 ** name is returned.  Here are the names:
1115 **
1116 **    0      The column name as it should be displayed for output
1117 **    1      The datatype name for the column
1118 **    2      The name of the database that the column derives from
1119 **    3      The name of the table that the column derives from
1120 **    4      The name of the table column that the result column derives from
1121 **
1122 ** If the result is not a simple column reference (if it is an expression
1123 ** or a constant) then useTypes 2, 3, and 4 return NULL.
1124 */
1125 static const void *columnName(
1126   sqlite3_stmt *pStmt,
1127   int N,
1128   const void *(*xFunc)(Mem*),
1129   int useType
1130 ){
1131   const void *ret;
1132   Vdbe *p;
1133   int n;
1134   sqlite3 *db;
1135 #ifdef SQLITE_ENABLE_API_ARMOR
1136   if( pStmt==0 ){
1137     (void)SQLITE_MISUSE_BKPT;
1138     return 0;
1139   }
1140 #endif
1141   ret = 0;
1142   p = (Vdbe *)pStmt;
1143   db = p->db;
1144   assert( db!=0 );
1145   n = sqlite3_column_count(pStmt);
1146   if( N<n && N>=0 ){
1147     N += useType*n;
1148     sqlite3_mutex_enter(db->mutex);
1149     assert( db->mallocFailed==0 );
1150     ret = xFunc(&p->aColName[N]);
1151      /* A malloc may have failed inside of the xFunc() call. If this
1152     ** is the case, clear the mallocFailed flag and return NULL.
1153     */
1154     if( db->mallocFailed ){
1155       sqlite3OomClear(db);
1156       ret = 0;
1157     }
1158     sqlite3_mutex_leave(db->mutex);
1159   }
1160   return ret;
1161 }
1162
1163 /*
1164 ** Return the name of the Nth column of the result set returned by SQL
1165 ** statement pStmt.
1166 */
1167 const char *sqlite3_column_name(sqlite3_stmt *pStmt, int N){
1168   return columnName(
1169       pStmt, N, (const void*(*)(Mem*))sqlite3_value_text, COLNAME_NAME);
1170 }
1171 #ifndef SQLITE_OMIT_UTF16
1172 const void *sqlite3_column_name16(sqlite3_stmt *pStmt, int N){
1173   return columnName(
1174       pStmt, N, (const void*(*)(Mem*))sqlite3_value_text16, COLNAME_NAME);
1175 }
1176 #endif
1177
1178 /*
1179 ** Constraint:  If you have ENABLE_COLUMN_METADATA then you must
1180 ** not define OMIT_DECLTYPE.
1181 */
1182 #if defined(SQLITE_OMIT_DECLTYPE) && defined(SQLITE_ENABLE_COLUMN_METADATA)
1183 # error "Must not define both SQLITE_OMIT_DECLTYPE \
1184          and SQLITE_ENABLE_COLUMN_METADATA"
1185 #endif
1186
1187 #ifndef SQLITE_OMIT_DECLTYPE
1188 /*
1189 ** Return the column declaration type (if applicable) of the 'i'th column
1190 ** of the result set of SQL statement pStmt.
1191 */
1192 const char *sqlite3_column_decltype(sqlite3_stmt *pStmt, int N){
1193   return columnName(
1194       pStmt, N, (const void*(*)(Mem*))sqlite3_value_text, COLNAME_DECLTYPE);
1195 }
1196 #ifndef SQLITE_OMIT_UTF16
1197 const void *sqlite3_column_decltype16(sqlite3_stmt *pStmt, int N){
1198   return columnName(
1199       pStmt, N, (const void*(*)(Mem*))sqlite3_value_text16, COLNAME_DECLTYPE);
1200 }
1201 #endif /* SQLITE_OMIT_UTF16 */
1202 #endif /* SQLITE_OMIT_DECLTYPE */
1203
1204 #ifdef SQLITE_ENABLE_COLUMN_METADATA
1205 /*
1206 ** Return the name of the database from which a result column derives.
1207 ** NULL is returned if the result column is an expression or constant or
1208 ** anything else which is not an unambiguous reference to a database column.
1209 */
1210 const char *sqlite3_column_database_name(sqlite3_stmt *pStmt, int N){
1211   return columnName(
1212       pStmt, N, (const void*(*)(Mem*))sqlite3_value_text, COLNAME_DATABASE);
1213 }
1214 #ifndef SQLITE_OMIT_UTF16
1215 const void *sqlite3_column_database_name16(sqlite3_stmt *pStmt, int N){
1216   return columnName(
1217       pStmt, N, (const void*(*)(Mem*))sqlite3_value_text16, COLNAME_DATABASE);
1218 }
1219 #endif /* SQLITE_OMIT_UTF16 */
1220
1221 /*
1222 ** Return the name of the table from which a result column derives.
1223 ** NULL is returned if the result column is an expression or constant or
1224 ** anything else which is not an unambiguous reference to a database column.
1225 */
1226 const char *sqlite3_column_table_name(sqlite3_stmt *pStmt, int N){
1227   return columnName(
1228       pStmt, N, (const void*(*)(Mem*))sqlite3_value_text, COLNAME_TABLE);
1229 }
1230 #ifndef SQLITE_OMIT_UTF16
1231 const void *sqlite3_column_table_name16(sqlite3_stmt *pStmt, int N){
1232   return columnName(
1233       pStmt, N, (const void*(*)(Mem*))sqlite3_value_text16, COLNAME_TABLE);
1234 }
1235 #endif /* SQLITE_OMIT_UTF16 */
1236
1237 /*
1238 ** Return the name of the table column from which a result column derives.
1239 ** NULL is returned if the result column is an expression or constant or
1240 ** anything else which is not an unambiguous reference to a database column.
1241 */
1242 const char *sqlite3_column_origin_name(sqlite3_stmt *pStmt, int N){
1243   return columnName(
1244       pStmt, N, (const void*(*)(Mem*))sqlite3_value_text, COLNAME_COLUMN);
1245 }
1246 #ifndef SQLITE_OMIT_UTF16
1247 const void *sqlite3_column_origin_name16(sqlite3_stmt *pStmt, int N){
1248   return columnName(
1249       pStmt, N, (const void*(*)(Mem*))sqlite3_value_text16, COLNAME_COLUMN);
1250 }
1251 #endif /* SQLITE_OMIT_UTF16 */
1252 #endif /* SQLITE_ENABLE_COLUMN_METADATA */
1253
1254
1255 /******************************* sqlite3_bind_  ***************************
1256 **
1257 ** Routines used to attach values to wildcards in a compiled SQL statement.
1258 */
1259 /*
1260 ** Unbind the value bound to variable i in virtual machine p. This is the
1261 ** the same as binding a NULL value to the column. If the "i" parameter is
1262 ** out of range, then SQLITE_RANGE is returned. Othewise SQLITE_OK.
1263 **
1264 ** A successful evaluation of this routine acquires the mutex on p.
1265 ** the mutex is released if any kind of error occurs.
1266 **
1267 ** The error code stored in database p->db is overwritten with the return
1268 ** value in any case.
1269 */
1270 static int vdbeUnbind(Vdbe *p, int i){
1271   Mem *pVar;
1272   if( vdbeSafetyNotNull(p) ){
1273     return SQLITE_MISUSE_BKPT;
1274   }
1275   sqlite3_mutex_enter(p->db->mutex);
1276   if( p->magic!=VDBE_MAGIC_RUN || p->pc>=0 ){
1277     sqlite3Error(p->db, SQLITE_MISUSE);
1278     sqlite3_mutex_leave(p->db->mutex);
1279     sqlite3_log(SQLITE_MISUSE,
1280         "bind on a busy prepared statement: [%s]", p->zSql);
1281     return SQLITE_MISUSE_BKPT;
1282   }
1283   if( i<1 || i>p->nVar ){
1284     sqlite3Error(p->db, SQLITE_RANGE);
1285     sqlite3_mutex_leave(p->db->mutex);
1286     return SQLITE_RANGE;
1287   }
1288   i--;
1289   pVar = &p->aVar[i];
1290   sqlite3VdbeMemRelease(pVar);
1291   pVar->flags = MEM_Null;
1292   sqlite3Error(p->db, SQLITE_OK);
1293
1294   /* If the bit corresponding to this variable in Vdbe.expmask is set, then
1295   ** binding a new value to this variable invalidates the current query plan.
1296   **
1297   ** IMPLEMENTATION-OF: R-48440-37595 If the specific value bound to host
1298   ** parameter in the WHERE clause might influence the choice of query plan
1299   ** for a statement, then the statement will be automatically recompiled,
1300   ** as if there had been a schema change, on the first sqlite3_step() call
1301   ** following any change to the bindings of that parameter.
1302   */
1303   assert( (p->prepFlags & SQLITE_PREPARE_SAVESQL)!=0 || p->expmask==0 );
1304   if( p->expmask!=0 && (p->expmask & (i>=31 ? 0x80000000 : (u32)1<<i))!=0 ){
1305     p->expired = 1;
1306   }
1307   return SQLITE_OK;
1308 }
1309
1310 /*
1311 ** Bind a text or BLOB value.
1312 */
1313 static int bindText(
1314   sqlite3_stmt *pStmt,   /* The statement to bind against */
1315   int i,                 /* Index of the parameter to bind */
1316   const void *zData,     /* Pointer to the data to be bound */
1317   int nData,             /* Number of bytes of data to be bound */
1318   void (*xDel)(void*),   /* Destructor for the data */
1319   u8 encoding            /* Encoding for the data */
1320 ){
1321   Vdbe *p = (Vdbe *)pStmt;
1322   Mem *pVar;
1323   int rc;
1324
1325   rc = vdbeUnbind(p, i);
1326   if( rc==SQLITE_OK ){
1327     if( zData!=0 ){
1328       pVar = &p->aVar[i-1];
1329       rc = sqlite3VdbeMemSetStr(pVar, zData, nData, encoding, xDel);
1330       if( rc==SQLITE_OK && encoding!=0 ){
1331         rc = sqlite3VdbeChangeEncoding(pVar, ENC(p->db));
1332       }
1333       if( rc ){
1334         sqlite3Error(p->db, rc);
1335         rc = sqlite3ApiExit(p->db, rc);
1336       }
1337     }
1338     sqlite3_mutex_leave(p->db->mutex);
1339   }else if( xDel!=SQLITE_STATIC && xDel!=SQLITE_TRANSIENT ){
1340     xDel((void*)zData);
1341   }
1342   return rc;
1343 }
1344
1345
1346 /*
1347 ** Bind a blob value to an SQL statement variable.
1348 */
1349 int sqlite3_bind_blob(
1350   sqlite3_stmt *pStmt,
1351   int i,
1352   const void *zData,
1353   int nData,
1354   void (*xDel)(void*)
1355 ){
1356 #ifdef SQLITE_ENABLE_API_ARMOR
1357   if( nData<0 ) return SQLITE_MISUSE_BKPT;
1358 #endif
1359   return bindText(pStmt, i, zData, nData, xDel, 0);
1360 }
1361 int sqlite3_bind_blob64(
1362   sqlite3_stmt *pStmt,
1363   int i,
1364   const void *zData,
1365   sqlite3_uint64 nData,
1366   void (*xDel)(void*)
1367 ){
1368   assert( xDel!=SQLITE_DYNAMIC );
1369   if( nData>0x7fffffff ){
1370     return invokeValueDestructor(zData, xDel, 0);
1371   }else{
1372     return bindText(pStmt, i, zData, (int)nData, xDel, 0);
1373   }
1374 }
1375 int sqlite3_bind_double(sqlite3_stmt *pStmt, int i, double rValue){
1376   int rc;
1377   Vdbe *p = (Vdbe *)pStmt;
1378   rc = vdbeUnbind(p, i);
1379   if( rc==SQLITE_OK ){
1380     sqlite3VdbeMemSetDouble(&p->aVar[i-1], rValue);
1381     sqlite3_mutex_leave(p->db->mutex);
1382   }
1383   return rc;
1384 }
1385 int sqlite3_bind_int(sqlite3_stmt *p, int i, int iValue){
1386   return sqlite3_bind_int64(p, i, (i64)iValue);
1387 }
1388 int sqlite3_bind_int64(sqlite3_stmt *pStmt, int i, sqlite_int64 iValue){
1389   int rc;
1390   Vdbe *p = (Vdbe *)pStmt;
1391   rc = vdbeUnbind(p, i);
1392   if( rc==SQLITE_OK ){
1393     sqlite3VdbeMemSetInt64(&p->aVar[i-1], iValue);
1394     sqlite3_mutex_leave(p->db->mutex);
1395   }
1396   return rc;
1397 }
1398 int sqlite3_bind_null(sqlite3_stmt *pStmt, int i){
1399   int rc;
1400   Vdbe *p = (Vdbe*)pStmt;
1401   rc = vdbeUnbind(p, i);
1402   if( rc==SQLITE_OK ){
1403     sqlite3_mutex_leave(p->db->mutex);
1404   }
1405   return rc;
1406 }
1407 int sqlite3_bind_pointer(
1408   sqlite3_stmt *pStmt,
1409   int i,
1410   void *pPtr,
1411   const char *zPTtype,
1412   void (*xDestructor)(void*)
1413 ){
1414   int rc;
1415   Vdbe *p = (Vdbe*)pStmt;
1416   rc = vdbeUnbind(p, i);
1417   if( rc==SQLITE_OK ){
1418     sqlite3VdbeMemSetPointer(&p->aVar[i-1], pPtr, zPTtype, xDestructor);
1419     sqlite3_mutex_leave(p->db->mutex);
1420   }else if( xDestructor ){
1421     xDestructor(pPtr);
1422   }
1423   return rc;
1424 }
1425 int sqlite3_bind_text(
1426   sqlite3_stmt *pStmt,
1427   int i,
1428   const char *zData,
1429   int nData,
1430   void (*xDel)(void*)
1431 ){
1432   return bindText(pStmt, i, zData, nData, xDel, SQLITE_UTF8);
1433 }
1434 int sqlite3_bind_text64(
1435   sqlite3_stmt *pStmt,
1436   int i,
1437   const char *zData,
1438   sqlite3_uint64 nData,
1439   void (*xDel)(void*),
1440   unsigned char enc
1441 ){
1442   assert( xDel!=SQLITE_DYNAMIC );
1443   if( nData>0x7fffffff ){
1444     return invokeValueDestructor(zData, xDel, 0);
1445   }else{
1446     if( enc==SQLITE_UTF16 ) enc = SQLITE_UTF16NATIVE;
1447     return bindText(pStmt, i, zData, (int)nData, xDel, enc);
1448   }
1449 }
1450 #ifndef SQLITE_OMIT_UTF16
1451 int sqlite3_bind_text16(
1452   sqlite3_stmt *pStmt,
1453   int i,
1454   const void *zData,
1455   int nData,
1456   void (*xDel)(void*)
1457 ){
1458   return bindText(pStmt, i, zData, nData, xDel, SQLITE_UTF16NATIVE);
1459 }
1460 #endif /* SQLITE_OMIT_UTF16 */
1461 int sqlite3_bind_value(sqlite3_stmt *pStmt, int i, const sqlite3_value *pValue){
1462   int rc;
1463   switch( sqlite3_value_type((sqlite3_value*)pValue) ){
1464     case SQLITE_INTEGER: {
1465       rc = sqlite3_bind_int64(pStmt, i, pValue->u.i);
1466       break;
1467     }
1468     case SQLITE_FLOAT: {
1469       rc = sqlite3_bind_double(pStmt, i, pValue->u.r);
1470       break;
1471     }
1472     case SQLITE_BLOB: {
1473       if( pValue->flags & MEM_Zero ){
1474         rc = sqlite3_bind_zeroblob(pStmt, i, pValue->u.nZero);
1475       }else{
1476         rc = sqlite3_bind_blob(pStmt, i, pValue->z, pValue->n,SQLITE_TRANSIENT);
1477       }
1478       break;
1479     }
1480     case SQLITE_TEXT: {
1481       rc = bindText(pStmt,i,  pValue->z, pValue->n, SQLITE_TRANSIENT,
1482                               pValue->enc);
1483       break;
1484     }
1485     default: {
1486       rc = sqlite3_bind_null(pStmt, i);
1487       break;
1488     }
1489   }
1490   return rc;
1491 }
1492 int sqlite3_bind_zeroblob(sqlite3_stmt *pStmt, int i, int n){
1493   int rc;
1494   Vdbe *p = (Vdbe *)pStmt;
1495   rc = vdbeUnbind(p, i);
1496   if( rc==SQLITE_OK ){
1497     sqlite3VdbeMemSetZeroBlob(&p->aVar[i-1], n);
1498     sqlite3_mutex_leave(p->db->mutex);
1499   }
1500   return rc;
1501 }
1502 int sqlite3_bind_zeroblob64(sqlite3_stmt *pStmt, int i, sqlite3_uint64 n){
1503   int rc;
1504   Vdbe *p = (Vdbe *)pStmt;
1505   sqlite3_mutex_enter(p->db->mutex);
1506   if( n>(u64)p->db->aLimit[SQLITE_LIMIT_LENGTH] ){
1507     rc = SQLITE_TOOBIG;
1508   }else{
1509     assert( (n & 0x7FFFFFFF)==n );
1510     rc = sqlite3_bind_zeroblob(pStmt, i, n);
1511   }
1512   rc = sqlite3ApiExit(p->db, rc);
1513   sqlite3_mutex_leave(p->db->mutex);
1514   return rc;
1515 }
1516
1517 /*
1518 ** Return the number of wildcards that can be potentially bound to.
1519 ** This routine is added to support DBD::SQLite.
1520 */
1521 int sqlite3_bind_parameter_count(sqlite3_stmt *pStmt){
1522   Vdbe *p = (Vdbe*)pStmt;
1523   return p ? p->nVar : 0;
1524 }
1525
1526 /*
1527 ** Return the name of a wildcard parameter.  Return NULL if the index
1528 ** is out of range or if the wildcard is unnamed.
1529 **
1530 ** The result is always UTF-8.
1531 */
1532 const char *sqlite3_bind_parameter_name(sqlite3_stmt *pStmt, int i){
1533   Vdbe *p = (Vdbe*)pStmt;
1534   if( p==0 ) return 0;
1535   return sqlite3VListNumToName(p->pVList, i);
1536 }
1537
1538 /*
1539 ** Given a wildcard parameter name, return the index of the variable
1540 ** with that name.  If there is no variable with the given name,
1541 ** return 0.
1542 */
1543 int sqlite3VdbeParameterIndex(Vdbe *p, const char *zName, int nName){
1544   if( p==0 || zName==0 ) return 0;
1545   return sqlite3VListNameToNum(p->pVList, zName, nName);
1546 }
1547 int sqlite3_bind_parameter_index(sqlite3_stmt *pStmt, const char *zName){
1548   return sqlite3VdbeParameterIndex((Vdbe*)pStmt, zName, sqlite3Strlen30(zName));
1549 }
1550
1551 /*
1552 ** Transfer all bindings from the first statement over to the second.
1553 */
1554 int sqlite3TransferBindings(sqlite3_stmt *pFromStmt, sqlite3_stmt *pToStmt){
1555   Vdbe *pFrom = (Vdbe*)pFromStmt;
1556   Vdbe *pTo = (Vdbe*)pToStmt;
1557   int i;
1558   assert( pTo->db==pFrom->db );
1559   assert( pTo->nVar==pFrom->nVar );
1560   sqlite3_mutex_enter(pTo->db->mutex);
1561   for(i=0; i<pFrom->nVar; i++){
1562     sqlite3VdbeMemMove(&pTo->aVar[i], &pFrom->aVar[i]);
1563   }
1564   sqlite3_mutex_leave(pTo->db->mutex);
1565   return SQLITE_OK;
1566 }
1567
1568 #ifndef SQLITE_OMIT_DEPRECATED
1569 /*
1570 ** Deprecated external interface.  Internal/core SQLite code
1571 ** should call sqlite3TransferBindings.
1572 **
1573 ** It is misuse to call this routine with statements from different
1574 ** database connections.  But as this is a deprecated interface, we
1575 ** will not bother to check for that condition.
1576 **
1577 ** If the two statements contain a different number of bindings, then
1578 ** an SQLITE_ERROR is returned.  Nothing else can go wrong, so otherwise
1579 ** SQLITE_OK is returned.
1580 */
1581 int sqlite3_transfer_bindings(sqlite3_stmt *pFromStmt, sqlite3_stmt *pToStmt){
1582   Vdbe *pFrom = (Vdbe*)pFromStmt;
1583   Vdbe *pTo = (Vdbe*)pToStmt;
1584   if( pFrom->nVar!=pTo->nVar ){
1585     return SQLITE_ERROR;
1586   }
1587   assert( (pTo->prepFlags & SQLITE_PREPARE_SAVESQL)!=0 || pTo->expmask==0 );
1588   if( pTo->expmask ){
1589     pTo->expired = 1;
1590   }
1591   assert( (pFrom->prepFlags & SQLITE_PREPARE_SAVESQL)!=0 || pFrom->expmask==0 );
1592   if( pFrom->expmask ){
1593     pFrom->expired = 1;
1594   }
1595   return sqlite3TransferBindings(pFromStmt, pToStmt);
1596 }
1597 #endif
1598
1599 /*
1600 ** Return the sqlite3* database handle to which the prepared statement given
1601 ** in the argument belongs.  This is the same database handle that was
1602 ** the first argument to the sqlite3_prepare() that was used to create
1603 ** the statement in the first place.
1604 */
1605 sqlite3 *sqlite3_db_handle(sqlite3_stmt *pStmt){
1606   return pStmt ? ((Vdbe*)pStmt)->db : 0;
1607 }
1608
1609 /*
1610 ** Return true if the prepared statement is guaranteed to not modify the
1611 ** database.
1612 */
1613 int sqlite3_stmt_readonly(sqlite3_stmt *pStmt){
1614   return pStmt ? ((Vdbe*)pStmt)->readOnly : 1;
1615 }
1616
1617 /*
1618 ** Return true if the prepared statement is in need of being reset.
1619 */
1620 int sqlite3_stmt_busy(sqlite3_stmt *pStmt){
1621   Vdbe *v = (Vdbe*)pStmt;
1622   return v!=0 && v->magic==VDBE_MAGIC_RUN && v->pc>=0;
1623 }
1624
1625 /*
1626 ** Return a pointer to the next prepared statement after pStmt associated
1627 ** with database connection pDb.  If pStmt is NULL, return the first
1628 ** prepared statement for the database connection.  Return NULL if there
1629 ** are no more.
1630 */
1631 sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt){
1632   sqlite3_stmt *pNext;
1633 #ifdef SQLITE_ENABLE_API_ARMOR
1634   if( !sqlite3SafetyCheckOk(pDb) ){
1635     (void)SQLITE_MISUSE_BKPT;
1636     return 0;
1637   }
1638 #endif
1639   sqlite3_mutex_enter(pDb->mutex);
1640   if( pStmt==0 ){
1641     pNext = (sqlite3_stmt*)pDb->pVdbe;
1642   }else{
1643     pNext = (sqlite3_stmt*)((Vdbe*)pStmt)->pNext;
1644   }
1645   sqlite3_mutex_leave(pDb->mutex);
1646   return pNext;
1647 }
1648
1649 /*
1650 ** Return the value of a status counter for a prepared statement
1651 */
1652 int sqlite3_stmt_status(sqlite3_stmt *pStmt, int op, int resetFlag){
1653   Vdbe *pVdbe = (Vdbe*)pStmt;
1654   u32 v;
1655 #ifdef SQLITE_ENABLE_API_ARMOR
1656   if( !pStmt ){
1657     (void)SQLITE_MISUSE_BKPT;
1658     return 0;
1659   }
1660 #endif
1661   if( op==SQLITE_STMTSTATUS_MEMUSED ){
1662     sqlite3 *db = pVdbe->db;
1663     sqlite3_mutex_enter(db->mutex);
1664     v = 0;
1665     db->pnBytesFreed = (int*)&v;
1666     sqlite3VdbeClearObject(db, pVdbe);
1667     sqlite3DbFree(db, pVdbe);
1668     db->pnBytesFreed = 0;
1669     sqlite3_mutex_leave(db->mutex);
1670   }else{
1671     v = pVdbe->aCounter[op];
1672     if( resetFlag ) pVdbe->aCounter[op] = 0;
1673   }
1674   return (int)v;
1675 }
1676
1677 /*
1678 ** Return the SQL associated with a prepared statement
1679 */
1680 const char *sqlite3_sql(sqlite3_stmt *pStmt){
1681   Vdbe *p = (Vdbe *)pStmt;
1682   return p ? p->zSql : 0;
1683 }
1684
1685 /*
1686 ** Return the SQL associated with a prepared statement with
1687 ** bound parameters expanded.  Space to hold the returned string is
1688 ** obtained from sqlite3_malloc().  The caller is responsible for
1689 ** freeing the returned string by passing it to sqlite3_free().
1690 **
1691 ** The SQLITE_TRACE_SIZE_LIMIT puts an upper bound on the size of
1692 ** expanded bound parameters.
1693 */
1694 char *sqlite3_expanded_sql(sqlite3_stmt *pStmt){
1695 #ifdef SQLITE_OMIT_TRACE
1696   return 0;
1697 #else
1698   char *z = 0;
1699   const char *zSql = sqlite3_sql(pStmt);
1700   if( zSql ){
1701     Vdbe *p = (Vdbe *)pStmt;
1702     sqlite3_mutex_enter(p->db->mutex);
1703     z = sqlite3VdbeExpandSql(p, zSql);
1704     sqlite3_mutex_leave(p->db->mutex);
1705   }
1706   return z;
1707 #endif
1708 }
1709
1710 #ifdef SQLITE_ENABLE_PREUPDATE_HOOK
1711 /*
1712 ** Allocate and populate an UnpackedRecord structure based on the serialized
1713 ** record in nKey/pKey. Return a pointer to the new UnpackedRecord structure
1714 ** if successful, or a NULL pointer if an OOM error is encountered.
1715 */
1716 static UnpackedRecord *vdbeUnpackRecord(
1717   KeyInfo *pKeyInfo,
1718   int nKey,
1719   const void *pKey
1720 ){
1721   UnpackedRecord *pRet;           /* Return value */
1722
1723   pRet = sqlite3VdbeAllocUnpackedRecord(pKeyInfo);
1724   if( pRet ){
1725     memset(pRet->aMem, 0, sizeof(Mem)*(pKeyInfo->nField+1));
1726     sqlite3VdbeRecordUnpack(pKeyInfo, nKey, pKey, pRet);
1727   }
1728   return pRet;
1729 }
1730
1731 /*
1732 ** This function is called from within a pre-update callback to retrieve
1733 ** a field of the row currently being updated or deleted.
1734 */
1735 int sqlite3_preupdate_old(sqlite3 *db, int iIdx, sqlite3_value **ppValue){
1736   PreUpdate *p = db->pPreUpdate;
1737   Mem *pMem;
1738   int rc = SQLITE_OK;
1739
1740   /* Test that this call is being made from within an SQLITE_DELETE or
1741   ** SQLITE_UPDATE pre-update callback, and that iIdx is within range. */
1742   if( !p || p->op==SQLITE_INSERT ){
1743     rc = SQLITE_MISUSE_BKPT;
1744     goto preupdate_old_out;
1745   }
1746   if( p->pPk ){
1747     iIdx = sqlite3ColumnOfIndex(p->pPk, iIdx);
1748   }
1749   if( iIdx>=p->pCsr->nField || iIdx<0 ){
1750     rc = SQLITE_RANGE;
1751     goto preupdate_old_out;
1752   }
1753
1754   /* If the old.* record has not yet been loaded into memory, do so now. */
1755   if( p->pUnpacked==0 ){
1756     u32 nRec;
1757     u8 *aRec;
1758
1759     nRec = sqlite3BtreePayloadSize(p->pCsr->uc.pCursor);
1760     aRec = sqlite3DbMallocRaw(db, nRec);
1761     if( !aRec ) goto preupdate_old_out;
1762     rc = sqlite3BtreePayload(p->pCsr->uc.pCursor, 0, nRec, aRec);
1763     if( rc==SQLITE_OK ){
1764       p->pUnpacked = vdbeUnpackRecord(&p->keyinfo, nRec, aRec);
1765       if( !p->pUnpacked ) rc = SQLITE_NOMEM;
1766     }
1767     if( rc!=SQLITE_OK ){
1768       sqlite3DbFree(db, aRec);
1769       goto preupdate_old_out;
1770     }
1771     p->aRecord = aRec;
1772   }
1773
1774   pMem = *ppValue = &p->pUnpacked->aMem[iIdx];
1775   if( iIdx==p->pTab->iPKey ){
1776     sqlite3VdbeMemSetInt64(pMem, p->iKey1);
1777   }else if( iIdx>=p->pUnpacked->nField ){
1778     *ppValue = (sqlite3_value *)columnNullValue();
1779   }else if( p->pTab->aCol[iIdx].affinity==SQLITE_AFF_REAL ){
1780     if( pMem->flags & MEM_Int ){
1781       sqlite3VdbeMemRealify(pMem);
1782     }
1783   }
1784
1785  preupdate_old_out:
1786   sqlite3Error(db, rc);
1787   return sqlite3ApiExit(db, rc);
1788 }
1789 #endif /* SQLITE_ENABLE_PREUPDATE_HOOK */
1790
1791 #ifdef SQLITE_ENABLE_PREUPDATE_HOOK
1792 /*
1793 ** This function is called from within a pre-update callback to retrieve
1794 ** the number of columns in the row being updated, deleted or inserted.
1795 */
1796 int sqlite3_preupdate_count(sqlite3 *db){
1797   PreUpdate *p = db->pPreUpdate;
1798   return (p ? p->keyinfo.nField : 0);
1799 }
1800 #endif /* SQLITE_ENABLE_PREUPDATE_HOOK */
1801
1802 #ifdef SQLITE_ENABLE_PREUPDATE_HOOK
1803 /*
1804 ** This function is designed to be called from within a pre-update callback
1805 ** only. It returns zero if the change that caused the callback was made
1806 ** immediately by a user SQL statement. Or, if the change was made by a
1807 ** trigger program, it returns the number of trigger programs currently
1808 ** on the stack (1 for a top-level trigger, 2 for a trigger fired by a
1809 ** top-level trigger etc.).
1810 **
1811 ** For the purposes of the previous paragraph, a foreign key CASCADE, SET NULL
1812 ** or SET DEFAULT action is considered a trigger.
1813 */
1814 int sqlite3_preupdate_depth(sqlite3 *db){
1815   PreUpdate *p = db->pPreUpdate;
1816   return (p ? p->v->nFrame : 0);
1817 }
1818 #endif /* SQLITE_ENABLE_PREUPDATE_HOOK */
1819
1820 #ifdef SQLITE_ENABLE_PREUPDATE_HOOK
1821 /*
1822 ** This function is called from within a pre-update callback to retrieve
1823 ** a field of the row currently being updated or inserted.
1824 */
1825 int sqlite3_preupdate_new(sqlite3 *db, int iIdx, sqlite3_value **ppValue){
1826   PreUpdate *p = db->pPreUpdate;
1827   int rc = SQLITE_OK;
1828   Mem *pMem;
1829
1830   if( !p || p->op==SQLITE_DELETE ){
1831     rc = SQLITE_MISUSE_BKPT;
1832     goto preupdate_new_out;
1833   }
1834   if( p->pPk && p->op!=SQLITE_UPDATE ){
1835     iIdx = sqlite3ColumnOfIndex(p->pPk, iIdx);
1836   }
1837   if( iIdx>=p->pCsr->nField || iIdx<0 ){
1838     rc = SQLITE_RANGE;
1839     goto preupdate_new_out;
1840   }
1841
1842   if( p->op==SQLITE_INSERT ){
1843     /* For an INSERT, memory cell p->iNewReg contains the serialized record
1844     ** that is being inserted. Deserialize it. */
1845     UnpackedRecord *pUnpack = p->pNewUnpacked;
1846     if( !pUnpack ){
1847       Mem *pData = &p->v->aMem[p->iNewReg];
1848       rc = ExpandBlob(pData);
1849       if( rc!=SQLITE_OK ) goto preupdate_new_out;
1850       pUnpack = vdbeUnpackRecord(&p->keyinfo, pData->n, pData->z);
1851       if( !pUnpack ){
1852         rc = SQLITE_NOMEM;
1853         goto preupdate_new_out;
1854       }
1855       p->pNewUnpacked = pUnpack;
1856     }
1857     pMem = &pUnpack->aMem[iIdx];
1858     if( iIdx==p->pTab->iPKey ){
1859       sqlite3VdbeMemSetInt64(pMem, p->iKey2);
1860     }else if( iIdx>=pUnpack->nField ){
1861       pMem = (sqlite3_value *)columnNullValue();
1862     }
1863   }else{
1864     /* For an UPDATE, memory cell (p->iNewReg+1+iIdx) contains the required
1865     ** value. Make a copy of the cell contents and return a pointer to it.
1866     ** It is not safe to return a pointer to the memory cell itself as the
1867     ** caller may modify the value text encoding.
1868     */
1869     assert( p->op==SQLITE_UPDATE );
1870     if( !p->aNew ){
1871       p->aNew = (Mem *)sqlite3DbMallocZero(db, sizeof(Mem) * p->pCsr->nField);
1872       if( !p->aNew ){
1873         rc = SQLITE_NOMEM;
1874         goto preupdate_new_out;
1875       }
1876     }
1877     assert( iIdx>=0 && iIdx<p->pCsr->nField );
1878     pMem = &p->aNew[iIdx];
1879     if( pMem->flags==0 ){
1880       if( iIdx==p->pTab->iPKey ){
1881         sqlite3VdbeMemSetInt64(pMem, p->iKey2);
1882       }else{
1883         rc = sqlite3VdbeMemCopy(pMem, &p->v->aMem[p->iNewReg+1+iIdx]);
1884         if( rc!=SQLITE_OK ) goto preupdate_new_out;
1885       }
1886     }
1887   }
1888   *ppValue = pMem;
1889
1890  preupdate_new_out:
1891   sqlite3Error(db, rc);
1892   return sqlite3ApiExit(db, rc);
1893 }
1894 #endif /* SQLITE_ENABLE_PREUPDATE_HOOK */
1895
1896 #ifdef SQLITE_ENABLE_STMT_SCANSTATUS
1897 /*
1898 ** Return status data for a single loop within query pStmt.
1899 */
1900 int sqlite3_stmt_scanstatus(
1901   sqlite3_stmt *pStmt,            /* Prepared statement being queried */
1902   int idx,                        /* Index of loop to report on */
1903   int iScanStatusOp,              /* Which metric to return */
1904   void *pOut                      /* OUT: Write the answer here */
1905 ){
1906   Vdbe *p = (Vdbe*)pStmt;
1907   ScanStatus *pScan;
1908   if( idx<0 || idx>=p->nScan ) return 1;
1909   pScan = &p->aScan[idx];
1910   switch( iScanStatusOp ){
1911     case SQLITE_SCANSTAT_NLOOP: {
1912       *(sqlite3_int64*)pOut = p->anExec[pScan->addrLoop];
1913       break;
1914     }
1915     case SQLITE_SCANSTAT_NVISIT: {
1916       *(sqlite3_int64*)pOut = p->anExec[pScan->addrVisit];
1917       break;
1918     }
1919     case SQLITE_SCANSTAT_EST: {
1920       double r = 1.0;
1921       LogEst x = pScan->nEst;
1922       while( x<100 ){
1923         x += 10;
1924         r *= 0.5;
1925       }
1926       *(double*)pOut = r*sqlite3LogEstToInt(x);
1927       break;
1928     }
1929     case SQLITE_SCANSTAT_NAME: {
1930       *(const char**)pOut = pScan->zName;
1931       break;
1932     }
1933     case SQLITE_SCANSTAT_EXPLAIN: {
1934       if( pScan->addrExplain ){
1935         *(const char**)pOut = p->aOp[ pScan->addrExplain ].p4.z;
1936       }else{
1937         *(const char**)pOut = 0;
1938       }
1939       break;
1940     }
1941     case SQLITE_SCANSTAT_SELECTID: {
1942       if( pScan->addrExplain ){
1943         *(int*)pOut = p->aOp[ pScan->addrExplain ].p1;
1944       }else{
1945         *(int*)pOut = -1;
1946       }
1947       break;
1948     }
1949     default: {
1950       return 1;
1951     }
1952   }
1953   return 0;
1954 }
1955
1956 /*
1957 ** Zero all counters associated with the sqlite3_stmt_scanstatus() data.
1958 */
1959 void sqlite3_stmt_scanstatus_reset(sqlite3_stmt *pStmt){
1960   Vdbe *p = (Vdbe*)pStmt;
1961   memset(p->anExec, 0, p->nOp * sizeof(i64));
1962 }
1963 #endif /* SQLITE_ENABLE_STMT_SCANSTATUS */