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