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( ExpandBlob(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].zDbSName, 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==0 ) return (Mem*)columnNullValue();
 956   assert( pVm->db );
 957   sqlite3_mutex_enter(pVm->db->mutex);
 958   if( pVm->pResultSet!=0 && i<pVm->nResColumn && i>=0 ){
 959     pOut = &pVm->pResultSet[i];
 960   }else{
 961     sqlite3Error(pVm->db, SQLITE_RANGE);
 962     pOut = (Mem*)columnNullValue();
 963   }
 964   return pOut;
 965 }
 966
 967 /*
 968 ** This function is called after invoking an sqlite3_value_XXX function on a
 969 ** column value (i.e. a value returned by evaluating an SQL expression in the
 970 ** select list of a SELECT statement) that may cause a malloc() failure. If
 971 ** malloc() has failed, the threads mallocFailed flag is cleared and the result
 972 ** code of statement pStmt set to SQLITE_NOMEM.
 973 **
 974 ** Specifically, this is called from within:
 975 **
 976 **     sqlite3_column_int()
 977 **     sqlite3_column_int64()
 978 **     sqlite3_column_text()
 979 **     sqlite3_column_text16()
 980 **     sqlite3_column_real()
 981 **     sqlite3_column_bytes()
 982 **     sqlite3_column_bytes16()
 983 **     sqiite3_column_blob()
 984 */
 985 static void columnMallocFailure(sqlite3_stmt *pStmt)
 986 {
 987   /* If malloc() failed during an encoding conversion within an
 988   ** sqlite3_column_XXX API, then set the return code of the statement to
 989   ** SQLITE_NOMEM. The next call to _step() (if any) will return SQLITE_ERROR
 990   ** and _finalize() will return NOMEM.
 991   */
 992   Vdbe *p = (Vdbe *)pStmt;
 993   if( p ){
 994     assert( p->db!=0 );
 995     assert( sqlite3_mutex_held(p->db->mutex) );
 996     p->rc = sqlite3ApiExit(p->db, p->rc);
 997     sqlite3_mutex_leave(p->db->mutex);
 998   }
 999 }
1000
1001 /**************************** sqlite3_column_  *******************************
1002 ** The following routines are used to access elements of the current row
1003 ** in the result set.
1004 */
1005 const void *sqlite3_column_blob(sqlite3_stmt *pStmt, int i){
1006   const void *val;
1007   val = sqlite3_value_blob( columnMem(pStmt,i) );
1008   /* Even though there is no encoding conversion, value_blob() might
1009   ** need to call malloc() to expand the result of a zeroblob()
1010   ** expression.
1011   */
1012   columnMallocFailure(pStmt);
1013   return val;
1014 }
1015 int sqlite3_column_bytes(sqlite3_stmt *pStmt, int i){
1016   int val = sqlite3_value_bytes( columnMem(pStmt,i) );
1017   columnMallocFailure(pStmt);
1018   return val;
1019 }
1020 int sqlite3_column_bytes16(sqlite3_stmt *pStmt, int i){
1021   int val = sqlite3_value_bytes16( columnMem(pStmt,i) );
1022   columnMallocFailure(pStmt);
1023   return val;
1024 }
1025 double sqlite3_column_double(sqlite3_stmt *pStmt, int i){
1026   double val = sqlite3_value_double( columnMem(pStmt,i) );
1027   columnMallocFailure(pStmt);
1028   return val;
1029 }
1030 int sqlite3_column_int(sqlite3_stmt *pStmt, int i){
1031   int val = sqlite3_value_int( columnMem(pStmt,i) );
1032   columnMallocFailure(pStmt);
1033   return val;
1034 }
1035 sqlite_int64 sqlite3_column_int64(sqlite3_stmt *pStmt, int i){
1036   sqlite_int64 val = sqlite3_value_int64( columnMem(pStmt,i) );
1037   columnMallocFailure(pStmt);
1038   return val;
1039 }
1040 const unsigned char *sqlite3_column_text(sqlite3_stmt *pStmt, int i){
1041   const unsigned char *val = sqlite3_value_text( columnMem(pStmt,i) );
1042   columnMallocFailure(pStmt);
1043   return val;
1044 }
1045 sqlite3_value *sqlite3_column_value(sqlite3_stmt *pStmt, int i){
1046   Mem *pOut = columnMem(pStmt, i);
1047   if( pOut->flags&MEM_Static ){
1048     pOut->flags &= ~MEM_Static;
1049     pOut->flags |= MEM_Ephem;
1050   }
1051   columnMallocFailure(pStmt);
1052   return (sqlite3_value *)pOut;
1053 }
1054 #ifndef SQLITE_OMIT_UTF16
1055 const void *sqlite3_column_text16(sqlite3_stmt *pStmt, int i){
1056   const void *val = sqlite3_value_text16( columnMem(pStmt,i) );
1057   columnMallocFailure(pStmt);
1058   return val;
1059 }
1060 #endif /* SQLITE_OMIT_UTF16 */
1061 int sqlite3_column_type(sqlite3_stmt *pStmt, int i){
1062   int iType = sqlite3_value_type( columnMem(pStmt,i) );
1063   columnMallocFailure(pStmt);
1064   return iType;
1065 }
1066
1067 /*
1068 ** Convert the N-th element of pStmt->pColName[] into a string using
1069 ** xFunc() then return that string.  If N is out of range, return 0.
1070 **
1071 ** There are up to 5 names for each column.  useType determines which
1072 ** name is returned.  Here are the names:
1073 **
1074 **    0      The column name as it should be displayed for output
1075 **    1      The datatype name for the column
1076 **    2      The name of the database that the column derives from
1077 **    3      The name of the table that the column derives from
1078 **    4      The name of the table column that the result column derives from
1079 **
1080 ** If the result is not a simple column reference (if it is an expression
1081 ** or a constant) then useTypes 2, 3, and 4 return NULL.
1082 */
1083 static const void *columnName(
1084   sqlite3_stmt *pStmt,
1085   int N,
1086   const void *(*xFunc)(Mem*),
1087   int useType
1088 ){
1089   const void *ret;
1090   Vdbe *p;
1091   int n;
1092   sqlite3 *db;
1093 #ifdef SQLITE_ENABLE_API_ARMOR
1094   if( pStmt==0 ){
1095     (void)SQLITE_MISUSE_BKPT;
1096     return 0;
1097   }
1098 #endif
1099   ret = 0;
1100   p = (Vdbe *)pStmt;
1101   db = p->db;
1102   assert( db!=0 );
1103   n = sqlite3_column_count(pStmt);
1104   if( N<n && N>=0 ){
1105     N += useType*n;
1106     sqlite3_mutex_enter(db->mutex);
1107     assert( db->mallocFailed==0 );
1108     ret = xFunc(&p->aColName[N]);
1109      /* A malloc may have failed inside of the xFunc() call. If this
1110     ** is the case, clear the mallocFailed flag and return NULL.
1111     */
1112     if( db->mallocFailed ){
1113       sqlite3OomClear(db);
1114       ret = 0;
1115     }
1116     sqlite3_mutex_leave(db->mutex);
1117   }
1118   return ret;
1119 }
1120
1121 /*
1122 ** Return the name of the Nth column of the result set returned by SQL
1123 ** statement pStmt.
1124 */
1125 const char *sqlite3_column_name(sqlite3_stmt *pStmt, int N){
1126   return columnName(
1127       pStmt, N, (const void*(*)(Mem*))sqlite3_value_text, COLNAME_NAME);
1128 }
1129 #ifndef SQLITE_OMIT_UTF16
1130 const void *sqlite3_column_name16(sqlite3_stmt *pStmt, int N){
1131   return columnName(
1132       pStmt, N, (const void*(*)(Mem*))sqlite3_value_text16, COLNAME_NAME);
1133 }
1134 #endif
1135
1136 /*
1137 ** Constraint:  If you have ENABLE_COLUMN_METADATA then you must
1138 ** not define OMIT_DECLTYPE.
1139 */
1140 #if defined(SQLITE_OMIT_DECLTYPE) && defined(SQLITE_ENABLE_COLUMN_METADATA)
1141 # error "Must not define both SQLITE_OMIT_DECLTYPE \
1142          and SQLITE_ENABLE_COLUMN_METADATA"
1143 #endif
1144
1145 #ifndef SQLITE_OMIT_DECLTYPE
1146 /*
1147 ** Return the column declaration type (if applicable) of the 'i'th column
1148 ** of the result set of SQL statement pStmt.
1149 */
1150 const char *sqlite3_column_decltype(sqlite3_stmt *pStmt, int N){
1151   return columnName(
1152       pStmt, N, (const void*(*)(Mem*))sqlite3_value_text, COLNAME_DECLTYPE);
1153 }
1154 #ifndef SQLITE_OMIT_UTF16
1155 const void *sqlite3_column_decltype16(sqlite3_stmt *pStmt, int N){
1156   return columnName(
1157       pStmt, N, (const void*(*)(Mem*))sqlite3_value_text16, COLNAME_DECLTYPE);
1158 }
1159 #endif /* SQLITE_OMIT_UTF16 */
1160 #endif /* SQLITE_OMIT_DECLTYPE */
1161
1162 #ifdef SQLITE_ENABLE_COLUMN_METADATA
1163 /*
1164 ** Return the name of the database from which a result column derives.
1165 ** NULL is returned if the result column is an expression or constant or
1166 ** anything else which is not an unambiguous reference to a database column.
1167 */
1168 const char *sqlite3_column_database_name(sqlite3_stmt *pStmt, int N){
1169   return columnName(
1170       pStmt, N, (const void*(*)(Mem*))sqlite3_value_text, COLNAME_DATABASE);
1171 }
1172 #ifndef SQLITE_OMIT_UTF16
1173 const void *sqlite3_column_database_name16(sqlite3_stmt *pStmt, int N){
1174   return columnName(
1175       pStmt, N, (const void*(*)(Mem*))sqlite3_value_text16, COLNAME_DATABASE);
1176 }
1177 #endif /* SQLITE_OMIT_UTF16 */
1178
1179 /*
1180 ** Return the name of the table from which a result column derives.
1181 ** NULL is returned if the result column is an expression or constant or
1182 ** anything else which is not an unambiguous reference to a database column.
1183 */
1184 const char *sqlite3_column_table_name(sqlite3_stmt *pStmt, int N){
1185   return columnName(
1186       pStmt, N, (const void*(*)(Mem*))sqlite3_value_text, COLNAME_TABLE);
1187 }
1188 #ifndef SQLITE_OMIT_UTF16
1189 const void *sqlite3_column_table_name16(sqlite3_stmt *pStmt, int N){
1190   return columnName(
1191       pStmt, N, (const void*(*)(Mem*))sqlite3_value_text16, COLNAME_TABLE);
1192 }
1193 #endif /* SQLITE_OMIT_UTF16 */
1194
1195 /*
1196 ** Return the name of the table column from which a result column derives.
1197 ** NULL is returned if the result column is an expression or constant or
1198 ** anything else which is not an unambiguous reference to a database column.
1199 */
1200 const char *sqlite3_column_origin_name(sqlite3_stmt *pStmt, int N){
1201   return columnName(
1202       pStmt, N, (const void*(*)(Mem*))sqlite3_value_text, COLNAME_COLUMN);
1203 }
1204 #ifndef SQLITE_OMIT_UTF16
1205 const void *sqlite3_column_origin_name16(sqlite3_stmt *pStmt, int N){
1206   return columnName(
1207       pStmt, N, (const void*(*)(Mem*))sqlite3_value_text16, COLNAME_COLUMN);
1208 }
1209 #endif /* SQLITE_OMIT_UTF16 */
1210 #endif /* SQLITE_ENABLE_COLUMN_METADATA */
1211
1212
1213 /******************************* sqlite3_bind_  ***************************
1214 **
1215 ** Routines used to attach values to wildcards in a compiled SQL statement.
1216 */
1217 /*
1218 ** Unbind the value bound to variable i in virtual machine p. This is the
1219 ** the same as binding a NULL value to the column. If the "i" parameter is
1220 ** out of range, then SQLITE_RANGE is returned. Othewise SQLITE_OK.
1221 **
1222 ** A successful evaluation of this routine acquires the mutex on p.
1223 ** the mutex is released if any kind of error occurs.
1224 **
1225 ** The error code stored in database p->db is overwritten with the return
1226 ** value in any case.
1227 */
1228 static int vdbeUnbind(Vdbe *p, int i){
1229   Mem *pVar;
1230   if( vdbeSafetyNotNull(p) ){
1231     return SQLITE_MISUSE_BKPT;
1232   }
1233   sqlite3_mutex_enter(p->db->mutex);
1234   if( p->magic!=VDBE_MAGIC_RUN || p->pc>=0 ){
1235     sqlite3Error(p->db, SQLITE_MISUSE);
1236     sqlite3_mutex_leave(p->db->mutex);
1237     sqlite3_log(SQLITE_MISUSE,
1238         "bind on a busy prepared statement: [%s]", p->zSql);
1239     return SQLITE_MISUSE_BKPT;
1240   }
1241   if( i<1 || i>p->nVar ){
1242     sqlite3Error(p->db, SQLITE_RANGE);
1243     sqlite3_mutex_leave(p->db->mutex);
1244     return SQLITE_RANGE;
1245   }
1246   i--;
1247   pVar = &p->aVar[i];
1248   sqlite3VdbeMemRelease(pVar);
1249   pVar->flags = MEM_Null;
1250   sqlite3Error(p->db, SQLITE_OK);
1251
1252   /* If the bit corresponding to this variable in Vdbe.expmask is set, then
1253   ** binding a new value to this variable invalidates the current query plan.
1254   **
1255   ** IMPLEMENTATION-OF: R-48440-37595 If the specific value bound to host
1256   ** parameter in the WHERE clause might influence the choice of query plan
1257   ** for a statement, then the statement will be automatically recompiled,
1258   ** as if there had been a schema change, on the first sqlite3_step() call
1259   ** following any change to the bindings of that parameter.
1260   */
1261   if( p->isPrepareV2 &&
1262      ((i<32 && p->expmask & ((u32)1 << i)) || p->expmask==0xffffffff)
1263   ){
1264     p->expired = 1;
1265   }
1266   return SQLITE_OK;
1267 }
1268
1269 /*
1270 ** Bind a text or BLOB value.
1271 */
1272 static int bindText(
1273   sqlite3_stmt *pStmt,   /* The statement to bind against */
1274   int i,                 /* Index of the parameter to bind */
1275   const void *zData,     /* Pointer to the data to be bound */
1276   int nData,             /* Number of bytes of data to be bound */
1277   void (*xDel)(void*),   /* Destructor for the data */
1278   u8 encoding            /* Encoding for the data */
1279 ){
1280   Vdbe *p = (Vdbe *)pStmt;
1281   Mem *pVar;
1282   int rc;
1283
1284   rc = vdbeUnbind(p, i);
1285   if( rc==SQLITE_OK ){
1286     if( zData!=0 ){
1287       pVar = &p->aVar[i-1];
1288       rc = sqlite3VdbeMemSetStr(pVar, zData, nData, encoding, xDel);
1289       if( rc==SQLITE_OK && encoding!=0 ){
1290         rc = sqlite3VdbeChangeEncoding(pVar, ENC(p->db));
1291       }
1292       sqlite3Error(p->db, rc);
1293       rc = sqlite3ApiExit(p->db, rc);
1294     }
1295     sqlite3_mutex_leave(p->db->mutex);
1296   }else if( xDel!=SQLITE_STATIC && xDel!=SQLITE_TRANSIENT ){
1297     xDel((void*)zData);
1298   }
1299   return rc;
1300 }
1301
1302
1303 /*
1304 ** Bind a blob value to an SQL statement variable.
1305 */
1306 int sqlite3_bind_blob(
1307   sqlite3_stmt *pStmt,
1308   int i,
1309   const void *zData,
1310   int nData,
1311   void (*xDel)(void*)
1312 ){
1313 #ifdef SQLITE_ENABLE_API_ARMOR
1314   if( nData<0 ) return SQLITE_MISUSE_BKPT;
1315 #endif
1316   return bindText(pStmt, i, zData, nData, xDel, 0);
1317 }
1318 int sqlite3_bind_blob64(
1319   sqlite3_stmt *pStmt,
1320   int i,
1321   const void *zData,
1322   sqlite3_uint64 nData,
1323   void (*xDel)(void*)
1324 ){
1325   assert( xDel!=SQLITE_DYNAMIC );
1326   if( nData>0x7fffffff ){
1327     return invokeValueDestructor(zData, xDel, 0);
1328   }else{
1329     return bindText(pStmt, i, zData, (int)nData, xDel, 0);
1330   }
1331 }
1332 int sqlite3_bind_double(sqlite3_stmt *pStmt, int i, double rValue){
1333   int rc;
1334   Vdbe *p = (Vdbe *)pStmt;
1335   rc = vdbeUnbind(p, i);
1336   if( rc==SQLITE_OK ){
1337     sqlite3VdbeMemSetDouble(&p->aVar[i-1], rValue);
1338     sqlite3_mutex_leave(p->db->mutex);
1339   }
1340   return rc;
1341 }
1342 int sqlite3_bind_int(sqlite3_stmt *p, int i, int iValue){
1343   return sqlite3_bind_int64(p, i, (i64)iValue);
1344 }
1345 int sqlite3_bind_int64(sqlite3_stmt *pStmt, int i, sqlite_int64 iValue){
1346   int rc;
1347   Vdbe *p = (Vdbe *)pStmt;
1348   rc = vdbeUnbind(p, i);
1349   if( rc==SQLITE_OK ){
1350     sqlite3VdbeMemSetInt64(&p->aVar[i-1], iValue);
1351     sqlite3_mutex_leave(p->db->mutex);
1352   }
1353   return rc;
1354 }
1355 int sqlite3_bind_null(sqlite3_stmt *pStmt, int i){
1356   int rc;
1357   Vdbe *p = (Vdbe*)pStmt;
1358   rc = vdbeUnbind(p, i);
1359   if( rc==SQLITE_OK ){
1360     sqlite3_mutex_leave(p->db->mutex);
1361   }
1362   return rc;
1363 }
1364 int sqlite3_bind_text(
1365   sqlite3_stmt *pStmt,
1366   int i,
1367   const char *zData,
1368   int nData,
1369   void (*xDel)(void*)
1370 ){
1371   return bindText(pStmt, i, zData, nData, xDel, SQLITE_UTF8);
1372 }
1373 int sqlite3_bind_text64(
1374   sqlite3_stmt *pStmt,
1375   int i,
1376   const char *zData,
1377   sqlite3_uint64 nData,
1378   void (*xDel)(void*),
1379   unsigned char enc
1380 ){
1381   assert( xDel!=SQLITE_DYNAMIC );
1382   if( nData>0x7fffffff ){
1383     return invokeValueDestructor(zData, xDel, 0);
1384   }else{
1385     if( enc==SQLITE_UTF16 ) enc = SQLITE_UTF16NATIVE;
1386     return bindText(pStmt, i, zData, (int)nData, xDel, enc);
1387   }
1388 }
1389 #ifndef SQLITE_OMIT_UTF16
1390 int sqlite3_bind_text16(
1391   sqlite3_stmt *pStmt,
1392   int i,
1393   const void *zData,
1394   int nData,
1395   void (*xDel)(void*)
1396 ){
1397   return bindText(pStmt, i, zData, nData, xDel, SQLITE_UTF16NATIVE);
1398 }
1399 #endif /* SQLITE_OMIT_UTF16 */
1400 int sqlite3_bind_value(sqlite3_stmt *pStmt, int i, const sqlite3_value *pValue){
1401   int rc;
1402   switch( sqlite3_value_type((sqlite3_value*)pValue) ){
1403     case SQLITE_INTEGER: {
1404       rc = sqlite3_bind_int64(pStmt, i, pValue->u.i);
1405       break;
1406     }
1407     case SQLITE_FLOAT: {
1408       rc = sqlite3_bind_double(pStmt, i, pValue->u.r);
1409       break;
1410     }
1411     case SQLITE_BLOB: {
1412       if( pValue->flags & MEM_Zero ){
1413         rc = sqlite3_bind_zeroblob(pStmt, i, pValue->u.nZero);
1414       }else{
1415         rc = sqlite3_bind_blob(pStmt, i, pValue->z, pValue->n,SQLITE_TRANSIENT);
1416       }
1417       break;
1418     }
1419     case SQLITE_TEXT: {
1420       rc = bindText(pStmt,i,  pValue->z, pValue->n, SQLITE_TRANSIENT,
1421                               pValue->enc);
1422       break;
1423     }
1424     default: {
1425       rc = sqlite3_bind_null(pStmt, i);
1426       break;
1427     }
1428   }
1429   return rc;
1430 }
1431 int sqlite3_bind_zeroblob(sqlite3_stmt *pStmt, int i, int n){
1432   int rc;
1433   Vdbe *p = (Vdbe *)pStmt;
1434   rc = vdbeUnbind(p, i);
1435   if( rc==SQLITE_OK ){
1436     sqlite3VdbeMemSetZeroBlob(&p->aVar[i-1], n);
1437     sqlite3_mutex_leave(p->db->mutex);
1438   }
1439   return rc;
1440 }
1441 int sqlite3_bind_zeroblob64(sqlite3_stmt *pStmt, int i, sqlite3_uint64 n){
1442   int rc;
1443   Vdbe *p = (Vdbe *)pStmt;
1444   sqlite3_mutex_enter(p->db->mutex);
1445   if( n>(u64)p->db->aLimit[SQLITE_LIMIT_LENGTH] ){
1446     rc = SQLITE_TOOBIG;
1447   }else{
1448     assert( (n & 0x7FFFFFFF)==n );
1449     rc = sqlite3_bind_zeroblob(pStmt, i, n);
1450   }
1451   rc = sqlite3ApiExit(p->db, rc);
1452   sqlite3_mutex_leave(p->db->mutex);
1453   return rc;
1454 }
1455
1456 /*
1457 ** Return the number of wildcards that can be potentially bound to.
1458 ** This routine is added to support DBD::SQLite.
1459 */
1460 int sqlite3_bind_parameter_count(sqlite3_stmt *pStmt){
1461   Vdbe *p = (Vdbe*)pStmt;
1462   return p ? p->nVar : 0;
1463 }
1464
1465 /*
1466 ** Return the name of a wildcard parameter.  Return NULL if the index
1467 ** is out of range or if the wildcard is unnamed.
1468 **
1469 ** The result is always UTF-8.
1470 */
1471 const char *sqlite3_bind_parameter_name(sqlite3_stmt *pStmt, int i){
1472   Vdbe *p = (Vdbe*)pStmt;
1473   if( p==0 ) return 0;
1474   return sqlite3VListNumToName(p->pVList, i);
1475 }
1476
1477 /*
1478 ** Given a wildcard parameter name, return the index of the variable
1479 ** with that name.  If there is no variable with the given name,
1480 ** return 0.
1481 */
1482 int sqlite3VdbeParameterIndex(Vdbe *p, const char *zName, int nName){
1483   if( p==0 || zName==0 ) return 0;
1484   return sqlite3VListNameToNum(p->pVList, zName, nName);
1485 }
1486 int sqlite3_bind_parameter_index(sqlite3_stmt *pStmt, const char *zName){
1487   return sqlite3VdbeParameterIndex((Vdbe*)pStmt, zName, sqlite3Strlen30(zName));
1488 }
1489
1490 /*
1491 ** Transfer all bindings from the first statement over to the second.
1492 */
1493 int sqlite3TransferBindings(sqlite3_stmt *pFromStmt, sqlite3_stmt *pToStmt){
1494   Vdbe *pFrom = (Vdbe*)pFromStmt;
1495   Vdbe *pTo = (Vdbe*)pToStmt;
1496   int i;
1497   assert( pTo->db==pFrom->db );
1498   assert( pTo->nVar==pFrom->nVar );
1499   sqlite3_mutex_enter(pTo->db->mutex);
1500   for(i=0; i<pFrom->nVar; i++){
1501     sqlite3VdbeMemMove(&pTo->aVar[i], &pFrom->aVar[i]);
1502   }
1503   sqlite3_mutex_leave(pTo->db->mutex);
1504   return SQLITE_OK;
1505 }
1506
1507 #ifndef SQLITE_OMIT_DEPRECATED
1508 /*
1509 ** Deprecated external interface.  Internal/core SQLite code
1510 ** should call sqlite3TransferBindings.
1511 **
1512 ** It is misuse to call this routine with statements from different
1513 ** database connections.  But as this is a deprecated interface, we
1514 ** will not bother to check for that condition.
1515 **
1516 ** If the two statements contain a different number of bindings, then
1517 ** an SQLITE_ERROR is returned.  Nothing else can go wrong, so otherwise
1518 ** SQLITE_OK is returned.
1519 */
1520 int sqlite3_transfer_bindings(sqlite3_stmt *pFromStmt, sqlite3_stmt *pToStmt){
1521   Vdbe *pFrom = (Vdbe*)pFromStmt;
1522   Vdbe *pTo = (Vdbe*)pToStmt;
1523   if( pFrom->nVar!=pTo->nVar ){
1524     return SQLITE_ERROR;
1525   }
1526   if( pTo->isPrepareV2 && pTo->expmask ){
1527     pTo->expired = 1;
1528   }
1529   if( pFrom->isPrepareV2 && pFrom->expmask ){
1530     pFrom->expired = 1;
1531   }
1532   return sqlite3TransferBindings(pFromStmt, pToStmt);
1533 }
1534 #endif
1535
1536 /*
1537 ** Return the sqlite3* database handle to which the prepared statement given
1538 ** in the argument belongs.  This is the same database handle that was
1539 ** the first argument to the sqlite3_prepare() that was used to create
1540 ** the statement in the first place.
1541 */
1542 sqlite3 *sqlite3_db_handle(sqlite3_stmt *pStmt){
1543   return pStmt ? ((Vdbe*)pStmt)->db : 0;
1544 }
1545
1546 /*
1547 ** Return true if the prepared statement is guaranteed to not modify the
1548 ** database.
1549 */
1550 int sqlite3_stmt_readonly(sqlite3_stmt *pStmt){
1551   return pStmt ? ((Vdbe*)pStmt)->readOnly : 1;
1552 }
1553
1554 /*
1555 ** Return true if the prepared statement is in need of being reset.
1556 */
1557 int sqlite3_stmt_busy(sqlite3_stmt *pStmt){
1558   Vdbe *v = (Vdbe*)pStmt;
1559   return v!=0 && v->magic==VDBE_MAGIC_RUN && v->pc>=0;
1560 }
1561
1562 /*
1563 ** Return a pointer to the next prepared statement after pStmt associated
1564 ** with database connection pDb.  If pStmt is NULL, return the first
1565 ** prepared statement for the database connection.  Return NULL if there
1566 ** are no more.
1567 */
1568 sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt){
1569   sqlite3_stmt *pNext;
1570 #ifdef SQLITE_ENABLE_API_ARMOR
1571   if( !sqlite3SafetyCheckOk(pDb) ){
1572     (void)SQLITE_MISUSE_BKPT;
1573     return 0;
1574   }
1575 #endif
1576   sqlite3_mutex_enter(pDb->mutex);
1577   if( pStmt==0 ){
1578     pNext = (sqlite3_stmt*)pDb->pVdbe;
1579   }else{
1580     pNext = (sqlite3_stmt*)((Vdbe*)pStmt)->pNext;
1581   }
1582   sqlite3_mutex_leave(pDb->mutex);
1583   return pNext;
1584 }
1585
1586 /*
1587 ** Return the value of a status counter for a prepared statement
1588 */
1589 int sqlite3_stmt_status(sqlite3_stmt *pStmt, int op, int resetFlag){
1590   Vdbe *pVdbe = (Vdbe*)pStmt;
1591   u32 v;
1592 #ifdef SQLITE_ENABLE_API_ARMOR
1593   if( !pStmt ){
1594     (void)SQLITE_MISUSE_BKPT;
1595     return 0;
1596   }
1597 #endif
1598   v = pVdbe->aCounter[op];
1599   if( resetFlag ) pVdbe->aCounter[op] = 0;
1600   return (int)v;
1601 }
1602
1603 /*
1604 ** Return the SQL associated with a prepared statement
1605 */
1606 const char *sqlite3_sql(sqlite3_stmt *pStmt){
1607   Vdbe *p = (Vdbe *)pStmt;
1608   return p ? p->zSql : 0;
1609 }
1610
1611 /*
1612 ** Return the SQL associated with a prepared statement with
1613 ** bound parameters expanded.  Space to hold the returned string is
1614 ** obtained from sqlite3_malloc().  The caller is responsible for
1615 ** freeing the returned string by passing it to sqlite3_free().
1616 **
1617 ** The SQLITE_TRACE_SIZE_LIMIT puts an upper bound on the size of
1618 ** expanded bound parameters.
1619 */
1620 char *sqlite3_expanded_sql(sqlite3_stmt *pStmt){
1621 #ifdef SQLITE_OMIT_TRACE
1622   return 0;
1623 #else
1624   char *z = 0;
1625   const char *zSql = sqlite3_sql(pStmt);
1626   if( zSql ){
1627     Vdbe *p = (Vdbe *)pStmt;
1628     sqlite3_mutex_enter(p->db->mutex);
1629     z = sqlite3VdbeExpandSql(p, zSql);
1630     sqlite3_mutex_leave(p->db->mutex);
1631   }
1632   return z;
1633 #endif
1634 }
1635
1636 #ifdef SQLITE_ENABLE_PREUPDATE_HOOK
1637 /*
1638 ** Allocate and populate an UnpackedRecord structure based on the serialized
1639 ** record in nKey/pKey. Return a pointer to the new UnpackedRecord structure
1640 ** if successful, or a NULL pointer if an OOM error is encountered.
1641 */
1642 static UnpackedRecord *vdbeUnpackRecord(
1643   KeyInfo *pKeyInfo,
1644   int nKey,
1645   const void *pKey
1646 ){
1647   UnpackedRecord *pRet;           /* Return value */
1648
1649   pRet = sqlite3VdbeAllocUnpackedRecord(pKeyInfo);
1650   if( pRet ){
1651     memset(pRet->aMem, 0, sizeof(Mem)*(pKeyInfo->nField+1));
1652     sqlite3VdbeRecordUnpack(pKeyInfo, nKey, pKey, pRet);
1653   }
1654   return pRet;
1655 }
1656
1657 /*
1658 ** This function is called from within a pre-update callback to retrieve
1659 ** a field of the row currently being updated or deleted.
1660 */
1661 int sqlite3_preupdate_old(sqlite3 *db, int iIdx, sqlite3_value **ppValue){
1662   PreUpdate *p = db->pPreUpdate;
1663   Mem *pMem;
1664   int rc = SQLITE_OK;
1665
1666   /* Test that this call is being made from within an SQLITE_DELETE or
1667   ** SQLITE_UPDATE pre-update callback, and that iIdx is within range. */
1668   if( !p || p->op==SQLITE_INSERT ){
1669     rc = SQLITE_MISUSE_BKPT;
1670     goto preupdate_old_out;
1671   }
1672   if( iIdx>=p->pCsr->nField || iIdx<0 ){
1673     rc = SQLITE_RANGE;
1674     goto preupdate_old_out;
1675   }
1676
1677   /* If the old.* record has not yet been loaded into memory, do so now. */
1678   if( p->pUnpacked==0 ){
1679     u32 nRec;
1680     u8 *aRec;
1681
1682     nRec = sqlite3BtreePayloadSize(p->pCsr->uc.pCursor);
1683     aRec = sqlite3DbMallocRaw(db, nRec);
1684     if( !aRec ) goto preupdate_old_out;
1685     rc = sqlite3BtreePayload(p->pCsr->uc.pCursor, 0, nRec, aRec);
1686     if( rc==SQLITE_OK ){
1687       p->pUnpacked = vdbeUnpackRecord(&p->keyinfo, nRec, aRec);
1688       if( !p->pUnpacked ) rc = SQLITE_NOMEM;
1689     }
1690     if( rc!=SQLITE_OK ){
1691       sqlite3DbFree(db, aRec);
1692       goto preupdate_old_out;
1693     }
1694     p->aRecord = aRec;
1695   }
1696
1697   pMem = *ppValue = &p->pUnpacked->aMem[iIdx];
1698   if( iIdx==p->pTab->iPKey ){
1699     sqlite3VdbeMemSetInt64(pMem, p->iKey1);
1700   }else if( iIdx>=p->pUnpacked->nField ){
1701     *ppValue = (sqlite3_value *)columnNullValue();
1702   }else if( p->pTab->aCol[iIdx].affinity==SQLITE_AFF_REAL ){
1703     if( pMem->flags & MEM_Int ){
1704       sqlite3VdbeMemRealify(pMem);
1705     }
1706   }
1707
1708  preupdate_old_out:
1709   sqlite3Error(db, rc);
1710   return sqlite3ApiExit(db, rc);
1711 }
1712 #endif /* SQLITE_ENABLE_PREUPDATE_HOOK */
1713
1714 #ifdef SQLITE_ENABLE_PREUPDATE_HOOK
1715 /*
1716 ** This function is called from within a pre-update callback to retrieve
1717 ** the number of columns in the row being updated, deleted or inserted.
1718 */
1719 int sqlite3_preupdate_count(sqlite3 *db){
1720   PreUpdate *p = db->pPreUpdate;
1721   return (p ? p->keyinfo.nField : 0);
1722 }
1723 #endif /* SQLITE_ENABLE_PREUPDATE_HOOK */
1724
1725 #ifdef SQLITE_ENABLE_PREUPDATE_HOOK
1726 /*
1727 ** This function is designed to be called from within a pre-update callback
1728 ** only. It returns zero if the change that caused the callback was made
1729 ** immediately by a user SQL statement. Or, if the change was made by a
1730 ** trigger program, it returns the number of trigger programs currently
1731 ** on the stack (1 for a top-level trigger, 2 for a trigger fired by a
1732 ** top-level trigger etc.).
1733 **
1734 ** For the purposes of the previous paragraph, a foreign key CASCADE, SET NULL
1735 ** or SET DEFAULT action is considered a trigger.
1736 */
1737 int sqlite3_preupdate_depth(sqlite3 *db){
1738   PreUpdate *p = db->pPreUpdate;
1739   return (p ? p->v->nFrame : 0);
1740 }
1741 #endif /* SQLITE_ENABLE_PREUPDATE_HOOK */
1742
1743 #ifdef SQLITE_ENABLE_PREUPDATE_HOOK
1744 /*
1745 ** This function is called from within a pre-update callback to retrieve
1746 ** a field of the row currently being updated or inserted.
1747 */
1748 int sqlite3_preupdate_new(sqlite3 *db, int iIdx, sqlite3_value **ppValue){
1749   PreUpdate *p = db->pPreUpdate;
1750   int rc = SQLITE_OK;
1751   Mem *pMem;
1752
1753   if( !p || p->op==SQLITE_DELETE ){
1754     rc = SQLITE_MISUSE_BKPT;
1755     goto preupdate_new_out;
1756   }
1757   if( iIdx>=p->pCsr->nField || iIdx<0 ){
1758     rc = SQLITE_RANGE;
1759     goto preupdate_new_out;
1760   }
1761
1762   if( p->op==SQLITE_INSERT ){
1763     /* For an INSERT, memory cell p->iNewReg contains the serialized record
1764     ** that is being inserted. Deserialize it. */
1765     UnpackedRecord *pUnpack = p->pNewUnpacked;
1766     if( !pUnpack ){
1767       Mem *pData = &p->v->aMem[p->iNewReg];
1768       rc = ExpandBlob(pData);
1769       if( rc!=SQLITE_OK ) goto preupdate_new_out;
1770       pUnpack = vdbeUnpackRecord(&p->keyinfo, pData->n, pData->z);
1771       if( !pUnpack ){
1772         rc = SQLITE_NOMEM;
1773         goto preupdate_new_out;
1774       }
1775       p->pNewUnpacked = pUnpack;
1776     }
1777     pMem = &pUnpack->aMem[iIdx];
1778     if( iIdx==p->pTab->iPKey ){
1779       sqlite3VdbeMemSetInt64(pMem, p->iKey2);
1780     }else if( iIdx>=pUnpack->nField ){
1781       pMem = (sqlite3_value *)columnNullValue();
1782     }
1783   }else{
1784     /* For an UPDATE, memory cell (p->iNewReg+1+iIdx) contains the required
1785     ** value. Make a copy of the cell contents and return a pointer to it.
1786     ** It is not safe to return a pointer to the memory cell itself as the
1787     ** caller may modify the value text encoding.
1788     */
1789     assert( p->op==SQLITE_UPDATE );
1790     if( !p->aNew ){
1791       p->aNew = (Mem *)sqlite3DbMallocZero(db, sizeof(Mem) * p->pCsr->nField);
1792       if( !p->aNew ){
1793         rc = SQLITE_NOMEM;
1794         goto preupdate_new_out;
1795       }
1796     }
1797     assert( iIdx>=0 && iIdx<p->pCsr->nField );
1798     pMem = &p->aNew[iIdx];
1799     if( pMem->flags==0 ){
1800       if( iIdx==p->pTab->iPKey ){
1801         sqlite3VdbeMemSetInt64(pMem, p->iKey2);
1802       }else{
1803         rc = sqlite3VdbeMemCopy(pMem, &p->v->aMem[p->iNewReg+1+iIdx]);
1804         if( rc!=SQLITE_OK ) goto preupdate_new_out;
1805       }
1806     }
1807   }
1808   *ppValue = pMem;
1809
1810  preupdate_new_out:
1811   sqlite3Error(db, rc);
1812   return sqlite3ApiExit(db, rc);
1813 }
1814 #endif /* SQLITE_ENABLE_PREUPDATE_HOOK */
1815
1816 #ifdef SQLITE_ENABLE_STMT_SCANSTATUS
1817 /*
1818 ** Return status data for a single loop within query pStmt.
1819 */
1820 int sqlite3_stmt_scanstatus(
1821   sqlite3_stmt *pStmt,            /* Prepared statement being queried */
1822   int idx,                        /* Index of loop to report on */
1823   int iScanStatusOp,              /* Which metric to return */
1824   void *pOut                      /* OUT: Write the answer here */
1825 ){
1826   Vdbe *p = (Vdbe*)pStmt;
1827   ScanStatus *pScan;
1828   if( idx<0 || idx>=p->nScan ) return 1;
1829   pScan = &p->aScan[idx];
1830   switch( iScanStatusOp ){
1831     case SQLITE_SCANSTAT_NLOOP: {
1832       *(sqlite3_int64*)pOut = p->anExec[pScan->addrLoop];
1833       break;
1834     }
1835     case SQLITE_SCANSTAT_NVISIT: {
1836       *(sqlite3_int64*)pOut = p->anExec[pScan->addrVisit];
1837       break;
1838     }
1839     case SQLITE_SCANSTAT_EST: {
1840       double r = 1.0;
1841       LogEst x = pScan->nEst;
1842       while( x<100 ){
1843         x += 10;
1844         r *= 0.5;
1845       }
1846       *(double*)pOut = r*sqlite3LogEstToInt(x);
1847       break;
1848     }
1849     case SQLITE_SCANSTAT_NAME: {
1850       *(const char**)pOut = pScan->zName;
1851       break;
1852     }
1853     case SQLITE_SCANSTAT_EXPLAIN: {
1854       if( pScan->addrExplain ){
1855         *(const char**)pOut = p->aOp[ pScan->addrExplain ].p4.z;
1856       }else{
1857         *(const char**)pOut = 0;
1858       }
1859       break;
1860     }
1861     case SQLITE_SCANSTAT_SELECTID: {
1862       if( pScan->addrExplain ){
1863         *(int*)pOut = p->aOp[ pScan->addrExplain ].p1;
1864       }else{
1865         *(int*)pOut = -1;
1866       }
1867       break;
1868     }
1869     default: {
1870       return 1;
1871     }
1872   }
1873   return 0;
1874 }
1875
1876 /*
1877 ** Zero all counters associated with the sqlite3_stmt_scanstatus() data.
1878 */
1879 void sqlite3_stmt_scanstatus_reset(sqlite3_stmt *pStmt){
1880   Vdbe *p = (Vdbe*)pStmt;
1881   memset(p->anExec, 0, p->nOp * sizeof(i64));
1882 }
1883 #endif /* SQLITE_ENABLE_STMT_SCANSTATUS */