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