000001  /*
000002  ** 2004 May 26
000003  **
000004  ** The author disclaims copyright to this source code.  In place of
000005  ** a legal notice, here is a blessing:
000006  **
000007  **    May you do good and not evil.
000008  **    May you find forgiveness for yourself and forgive others.
000009  **    May you share freely, never taking more than you give.
000010  **
000011  *************************************************************************
000012  **
000013  ** This file contains code use to implement APIs that are part of the
000014  ** VDBE.
000015  */
000016  #include "sqliteInt.h"
000017  #include "vdbeInt.h"
000018  
000019  #ifndef SQLITE_OMIT_DEPRECATED
000020  /*
000021  ** Return TRUE (non-zero) of the statement supplied as an argument needs
000022  ** to be recompiled.  A statement needs to be recompiled whenever the
000023  ** execution environment changes in a way that would alter the program
000024  ** that sqlite3_prepare() generates.  For example, if new functions or
000025  ** collating sequences are registered or if an authorizer function is
000026  ** added or changed.
000027  */
000028  int sqlite3_expired(sqlite3_stmt *pStmt){
000029    Vdbe *p = (Vdbe*)pStmt;
000030    return p==0 || p->expired;
000031  }
000032  #endif
000033  
000034  /*
000035  ** Check on a Vdbe to make sure it has not been finalized.  Log
000036  ** an error and return true if it has been finalized (or is otherwise
000037  ** invalid).  Return false if it is ok.
000038  */
000039  static int vdbeSafety(Vdbe *p){
000040    if( p->db==0 ){
000041      sqlite3_log(SQLITE_MISUSE, "API called with finalized prepared statement");
000042      return 1;
000043    }else{
000044      return 0;
000045    }
000046  }
000047  static int vdbeSafetyNotNull(Vdbe *p){
000048    if( p==0 ){
000049      sqlite3_log(SQLITE_MISUSE, "API called with NULL prepared statement");
000050      return 1;
000051    }else{
000052      return vdbeSafety(p);
000053    }
000054  }
000055  
000056  #ifndef SQLITE_OMIT_TRACE
000057  /*
000058  ** Invoke the profile callback.  This routine is only called if we already
000059  ** know that the profile callback is defined and needs to be invoked.
000060  */
000061  static SQLITE_NOINLINE void invokeProfileCallback(sqlite3 *db, Vdbe *p){
000062    sqlite3_int64 iNow;
000063    sqlite3_int64 iElapse;
000064    assert( p->startTime>0 );
000065    assert( (db->mTrace & (SQLITE_TRACE_PROFILE|SQLITE_TRACE_XPROFILE))!=0 );
000066    assert( db->init.busy==0 );
000067    assert( p->zSql!=0 );
000068    sqlite3OsCurrentTimeInt64(db->pVfs, &iNow);
000069    iElapse = (iNow - p->startTime)*1000000;
000070  #ifndef SQLITE_OMIT_DEPRECATED
000071    if( db->xProfile ){
000072      db->xProfile(db->pProfileArg, p->zSql, iElapse);
000073    }
000074  #endif
000075    if( db->mTrace & SQLITE_TRACE_PROFILE ){
000076      db->xTrace(SQLITE_TRACE_PROFILE, db->pTraceArg, p, (void*)&iElapse);
000077    }
000078    p->startTime = 0;
000079  }
000080  /*
000081  ** The checkProfileCallback(DB,P) macro checks to see if a profile callback
000082  ** is needed, and it invokes the callback if it is needed.
000083  */
000084  # define checkProfileCallback(DB,P) \
000085     if( ((P)->startTime)>0 ){ invokeProfileCallback(DB,P); }
000086  #else
000087  # define checkProfileCallback(DB,P)  /*no-op*/
000088  #endif
000089  
000090  /*
000091  ** The following routine destroys a virtual machine that is created by
000092  ** the sqlite3_compile() routine. The integer returned is an SQLITE_
000093  ** success/failure code that describes the result of executing the virtual
000094  ** machine.
000095  **
000096  ** This routine sets the error code and string returned by
000097  ** sqlite3_errcode(), sqlite3_errmsg() and sqlite3_errmsg16().
000098  */
000099  int sqlite3_finalize(sqlite3_stmt *pStmt){
000100    int rc;
000101    if( pStmt==0 ){
000102      /* IMPLEMENTATION-OF: R-57228-12904 Invoking sqlite3_finalize() on a NULL
000103      ** pointer is a harmless no-op. */
000104      rc = SQLITE_OK;
000105    }else{
000106      Vdbe *v = (Vdbe*)pStmt;
000107      sqlite3 *db = v->db;
000108      if( vdbeSafety(v) ) return SQLITE_MISUSE_BKPT;
000109      sqlite3_mutex_enter(db->mutex);
000110      checkProfileCallback(db, v);
000111      rc = sqlite3VdbeFinalize(v);
000112      rc = sqlite3ApiExit(db, rc);
000113      sqlite3LeaveMutexAndCloseZombie(db);
000114    }
000115    return rc;
000116  }
000117  
000118  /*
000119  ** Terminate the current execution of an SQL statement and reset it
000120  ** back to its starting state so that it can be reused. A success code from
000121  ** the prior execution is returned.
000122  **
000123  ** This routine sets the error code and string returned by
000124  ** sqlite3_errcode(), sqlite3_errmsg() and sqlite3_errmsg16().
000125  */
000126  int sqlite3_reset(sqlite3_stmt *pStmt){
000127    int rc;
000128    if( pStmt==0 ){
000129      rc = SQLITE_OK;
000130    }else{
000131      Vdbe *v = (Vdbe*)pStmt;
000132      sqlite3 *db = v->db;
000133      sqlite3_mutex_enter(db->mutex);
000134      checkProfileCallback(db, v);
000135      rc = sqlite3VdbeReset(v);
000136      sqlite3VdbeRewind(v);
000137      assert( (rc & (db->errMask))==rc );
000138      rc = sqlite3ApiExit(db, rc);
000139      sqlite3_mutex_leave(db->mutex);
000140    }
000141    return rc;
000142  }
000143  
000144  /*
000145  ** Set all the parameters in the compiled SQL statement to NULL.
000146  */
000147  int sqlite3_clear_bindings(sqlite3_stmt *pStmt){
000148    int i;
000149    int rc = SQLITE_OK;
000150    Vdbe *p = (Vdbe*)pStmt;
000151  #if SQLITE_THREADSAFE
000152    sqlite3_mutex *mutex = ((Vdbe*)pStmt)->db->mutex;
000153  #endif
000154    sqlite3_mutex_enter(mutex);
000155    for(i=0; i<p->nVar; i++){
000156      sqlite3VdbeMemRelease(&p->aVar[i]);
000157      p->aVar[i].flags = MEM_Null;
000158    }
000159    assert( (p->prepFlags & SQLITE_PREPARE_SAVESQL)!=0 || p->expmask==0 );
000160    if( p->expmask ){
000161      p->expired = 1;
000162    }
000163    sqlite3_mutex_leave(mutex);
000164    return rc;
000165  }
000166  
000167  
000168  /**************************** sqlite3_value_  *******************************
000169  ** The following routines extract information from a Mem or sqlite3_value
000170  ** structure.
000171  */
000172  const void *sqlite3_value_blob(sqlite3_value *pVal){
000173    Mem *p = (Mem*)pVal;
000174    if( p->flags & (MEM_Blob|MEM_Str) ){
000175      if( ExpandBlob(p)!=SQLITE_OK ){
000176        assert( p->flags==MEM_Null && p->z==0 );
000177        return 0;
000178      }
000179      p->flags |= MEM_Blob;
000180      return p->n ? p->z : 0;
000181    }else{
000182      return sqlite3_value_text(pVal);
000183    }
000184  }
000185  int sqlite3_value_bytes(sqlite3_value *pVal){
000186    return sqlite3ValueBytes(pVal, SQLITE_UTF8);
000187  }
000188  int sqlite3_value_bytes16(sqlite3_value *pVal){
000189    return sqlite3ValueBytes(pVal, SQLITE_UTF16NATIVE);
000190  }
000191  double sqlite3_value_double(sqlite3_value *pVal){
000192    return sqlite3VdbeRealValue((Mem*)pVal);
000193  }
000194  int sqlite3_value_int(sqlite3_value *pVal){
000195    return (int)sqlite3VdbeIntValue((Mem*)pVal);
000196  }
000197  sqlite_int64 sqlite3_value_int64(sqlite3_value *pVal){
000198    return sqlite3VdbeIntValue((Mem*)pVal);
000199  }
000200  unsigned int sqlite3_value_subtype(sqlite3_value *pVal){
000201    Mem *pMem = (Mem*)pVal;
000202    return ((pMem->flags & MEM_Subtype) ? pMem->eSubtype : 0);
000203  }
000204  void *sqlite3_value_pointer(sqlite3_value *pVal, const char *zPType){
000205    Mem *p = (Mem*)pVal;
000206    if( (p->flags&(MEM_TypeMask|MEM_Term|MEM_Subtype)) ==
000207                   (MEM_Null|MEM_Term|MEM_Subtype)
000208     && zPType!=0
000209     && p->eSubtype=='p'
000210     && strcmp(p->u.zPType, zPType)==0
000211    ){
000212      return (void*)p->z;
000213    }else{
000214      return 0;
000215    }
000216  }
000217  const unsigned char *sqlite3_value_text(sqlite3_value *pVal){
000218    return (const unsigned char *)sqlite3ValueText(pVal, SQLITE_UTF8);
000219  }
000220  #ifndef SQLITE_OMIT_UTF16
000221  const void *sqlite3_value_text16(sqlite3_value* pVal){
000222    return sqlite3ValueText(pVal, SQLITE_UTF16NATIVE);
000223  }
000224  const void *sqlite3_value_text16be(sqlite3_value *pVal){
000225    return sqlite3ValueText(pVal, SQLITE_UTF16BE);
000226  }
000227  const void *sqlite3_value_text16le(sqlite3_value *pVal){
000228    return sqlite3ValueText(pVal, SQLITE_UTF16LE);
000229  }
000230  #endif /* SQLITE_OMIT_UTF16 */
000231  /* EVIDENCE-OF: R-12793-43283 Every value in SQLite has one of five
000232  ** fundamental datatypes: 64-bit signed integer 64-bit IEEE floating
000233  ** point number string BLOB NULL
000234  */
000235  int sqlite3_value_type(sqlite3_value* pVal){
000236    static const u8 aType[] = {
000237       SQLITE_BLOB,     /* 0x00 (not possible) */
000238       SQLITE_NULL,     /* 0x01 NULL */
000239       SQLITE_TEXT,     /* 0x02 TEXT */
000240       SQLITE_NULL,     /* 0x03 (not possible) */
000241       SQLITE_INTEGER,  /* 0x04 INTEGER */
000242       SQLITE_NULL,     /* 0x05 (not possible) */
000243       SQLITE_INTEGER,  /* 0x06 INTEGER + TEXT */
000244       SQLITE_NULL,     /* 0x07 (not possible) */
000245       SQLITE_FLOAT,    /* 0x08 FLOAT */
000246       SQLITE_NULL,     /* 0x09 (not possible) */
000247       SQLITE_FLOAT,    /* 0x0a FLOAT + TEXT */
000248       SQLITE_NULL,     /* 0x0b (not possible) */
000249       SQLITE_INTEGER,  /* 0x0c (not possible) */
000250       SQLITE_NULL,     /* 0x0d (not possible) */
000251       SQLITE_INTEGER,  /* 0x0e (not possible) */
000252       SQLITE_NULL,     /* 0x0f (not possible) */
000253       SQLITE_BLOB,     /* 0x10 BLOB */
000254       SQLITE_NULL,     /* 0x11 (not possible) */
000255       SQLITE_TEXT,     /* 0x12 (not possible) */
000256       SQLITE_NULL,     /* 0x13 (not possible) */
000257       SQLITE_INTEGER,  /* 0x14 INTEGER + BLOB */
000258       SQLITE_NULL,     /* 0x15 (not possible) */
000259       SQLITE_INTEGER,  /* 0x16 (not possible) */
000260       SQLITE_NULL,     /* 0x17 (not possible) */
000261       SQLITE_FLOAT,    /* 0x18 FLOAT + BLOB */
000262       SQLITE_NULL,     /* 0x19 (not possible) */
000263       SQLITE_FLOAT,    /* 0x1a (not possible) */
000264       SQLITE_NULL,     /* 0x1b (not possible) */
000265       SQLITE_INTEGER,  /* 0x1c (not possible) */
000266       SQLITE_NULL,     /* 0x1d (not possible) */
000267       SQLITE_INTEGER,  /* 0x1e (not possible) */
000268       SQLITE_NULL,     /* 0x1f (not possible) */
000269       SQLITE_FLOAT,    /* 0x20 INTREAL */
000270       SQLITE_NULL,     /* 0x21 (not possible) */
000271       SQLITE_TEXT,     /* 0x22 INTREAL + TEXT */
000272       SQLITE_NULL,     /* 0x23 (not possible) */
000273       SQLITE_FLOAT,    /* 0x24 (not possible) */
000274       SQLITE_NULL,     /* 0x25 (not possible) */
000275       SQLITE_FLOAT,    /* 0x26 (not possible) */
000276       SQLITE_NULL,     /* 0x27 (not possible) */
000277       SQLITE_FLOAT,    /* 0x28 (not possible) */
000278       SQLITE_NULL,     /* 0x29 (not possible) */
000279       SQLITE_FLOAT,    /* 0x2a (not possible) */
000280       SQLITE_NULL,     /* 0x2b (not possible) */
000281       SQLITE_FLOAT,    /* 0x2c (not possible) */
000282       SQLITE_NULL,     /* 0x2d (not possible) */
000283       SQLITE_FLOAT,    /* 0x2e (not possible) */
000284       SQLITE_NULL,     /* 0x2f (not possible) */
000285       SQLITE_BLOB,     /* 0x30 (not possible) */
000286       SQLITE_NULL,     /* 0x31 (not possible) */
000287       SQLITE_TEXT,     /* 0x32 (not possible) */
000288       SQLITE_NULL,     /* 0x33 (not possible) */
000289       SQLITE_FLOAT,    /* 0x34 (not possible) */
000290       SQLITE_NULL,     /* 0x35 (not possible) */
000291       SQLITE_FLOAT,    /* 0x36 (not possible) */
000292       SQLITE_NULL,     /* 0x37 (not possible) */
000293       SQLITE_FLOAT,    /* 0x38 (not possible) */
000294       SQLITE_NULL,     /* 0x39 (not possible) */
000295       SQLITE_FLOAT,    /* 0x3a (not possible) */
000296       SQLITE_NULL,     /* 0x3b (not possible) */
000297       SQLITE_FLOAT,    /* 0x3c (not possible) */
000298       SQLITE_NULL,     /* 0x3d (not possible) */
000299       SQLITE_FLOAT,    /* 0x3e (not possible) */
000300       SQLITE_NULL,     /* 0x3f (not possible) */
000301    };
000302  #ifdef SQLITE_DEBUG
000303    {
000304      int eType = SQLITE_BLOB;
000305      if( pVal->flags & MEM_Null ){
000306        eType = SQLITE_NULL;
000307      }else if( pVal->flags & (MEM_Real|MEM_IntReal) ){
000308        eType = SQLITE_FLOAT;
000309      }else if( pVal->flags & MEM_Int ){
000310        eType = SQLITE_INTEGER;
000311      }else if( pVal->flags & MEM_Str ){
000312        eType = SQLITE_TEXT;
000313      }
000314      assert( eType == aType[pVal->flags&MEM_AffMask] );
000315    }
000316  #endif
000317    return aType[pVal->flags&MEM_AffMask];
000318  }
000319  
000320  /* Return true if a parameter to xUpdate represents an unchanged column */
000321  int sqlite3_value_nochange(sqlite3_value *pVal){
000322    return (pVal->flags&(MEM_Null|MEM_Zero))==(MEM_Null|MEM_Zero);
000323  }
000324  
000325  /* Return true if a parameter value originated from an sqlite3_bind() */
000326  int sqlite3_value_frombind(sqlite3_value *pVal){
000327    return (pVal->flags&MEM_FromBind)!=0;
000328  }
000329  
000330  /* Make a copy of an sqlite3_value object
000331  */
000332  sqlite3_value *sqlite3_value_dup(const sqlite3_value *pOrig){
000333    sqlite3_value *pNew;
000334    if( pOrig==0 ) return 0;
000335    pNew = sqlite3_malloc( sizeof(*pNew) );
000336    if( pNew==0 ) return 0;
000337    memset(pNew, 0, sizeof(*pNew));
000338    memcpy(pNew, pOrig, MEMCELLSIZE);
000339    pNew->flags &= ~MEM_Dyn;
000340    pNew->db = 0;
000341    if( pNew->flags&(MEM_Str|MEM_Blob) ){
000342      pNew->flags &= ~(MEM_Static|MEM_Dyn);
000343      pNew->flags |= MEM_Ephem;
000344      if( sqlite3VdbeMemMakeWriteable(pNew)!=SQLITE_OK ){
000345        sqlite3ValueFree(pNew);
000346        pNew = 0;
000347      }
000348    }
000349    return pNew;
000350  }
000351  
000352  /* Destroy an sqlite3_value object previously obtained from
000353  ** sqlite3_value_dup().
000354  */
000355  void sqlite3_value_free(sqlite3_value *pOld){
000356    sqlite3ValueFree(pOld);
000357  }
000358    
000359  
000360  /**************************** sqlite3_result_  *******************************
000361  ** The following routines are used by user-defined functions to specify
000362  ** the function result.
000363  **
000364  ** The setStrOrError() function calls sqlite3VdbeMemSetStr() to store the
000365  ** result as a string or blob but if the string or blob is too large, it
000366  ** then sets the error code to SQLITE_TOOBIG
000367  **
000368  ** The invokeValueDestructor(P,X) routine invokes destructor function X()
000369  ** on value P is not going to be used and need to be destroyed.
000370  */
000371  static void setResultStrOrError(
000372    sqlite3_context *pCtx,  /* Function context */
000373    const char *z,          /* String pointer */
000374    int n,                  /* Bytes in string, or negative */
000375    u8 enc,                 /* Encoding of z.  0 for BLOBs */
000376    void (*xDel)(void*)     /* Destructor function */
000377  ){
000378    if( sqlite3VdbeMemSetStr(pCtx->pOut, z, n, enc, xDel)==SQLITE_TOOBIG ){
000379      sqlite3_result_error_toobig(pCtx);
000380    }
000381  }
000382  static int invokeValueDestructor(
000383    const void *p,             /* Value to destroy */
000384    void (*xDel)(void*),       /* The destructor */
000385    sqlite3_context *pCtx      /* Set a SQLITE_TOOBIG error if no NULL */
000386  ){
000387    assert( xDel!=SQLITE_DYNAMIC );
000388    if( xDel==0 ){
000389      /* noop */
000390    }else if( xDel==SQLITE_TRANSIENT ){
000391      /* noop */
000392    }else{
000393      xDel((void*)p);
000394    }
000395    if( pCtx ) sqlite3_result_error_toobig(pCtx);
000396    return SQLITE_TOOBIG;
000397  }
000398  void sqlite3_result_blob(
000399    sqlite3_context *pCtx, 
000400    const void *z, 
000401    int n, 
000402    void (*xDel)(void *)
000403  ){
000404    assert( n>=0 );
000405    assert( sqlite3_mutex_held(pCtx->pOut->db->mutex) );
000406    setResultStrOrError(pCtx, z, n, 0, xDel);
000407  }
000408  void sqlite3_result_blob64(
000409    sqlite3_context *pCtx, 
000410    const void *z, 
000411    sqlite3_uint64 n,
000412    void (*xDel)(void *)
000413  ){
000414    assert( sqlite3_mutex_held(pCtx->pOut->db->mutex) );
000415    assert( xDel!=SQLITE_DYNAMIC );
000416    if( n>0x7fffffff ){
000417      (void)invokeValueDestructor(z, xDel, pCtx);
000418    }else{
000419      setResultStrOrError(pCtx, z, (int)n, 0, xDel);
000420    }
000421  }
000422  void sqlite3_result_double(sqlite3_context *pCtx, double rVal){
000423    assert( sqlite3_mutex_held(pCtx->pOut->db->mutex) );
000424    sqlite3VdbeMemSetDouble(pCtx->pOut, rVal);
000425  }
000426  void sqlite3_result_error(sqlite3_context *pCtx, const char *z, int n){
000427    assert( sqlite3_mutex_held(pCtx->pOut->db->mutex) );
000428    pCtx->isError = SQLITE_ERROR;
000429    sqlite3VdbeMemSetStr(pCtx->pOut, z, n, SQLITE_UTF8, SQLITE_TRANSIENT);
000430  }
000431  #ifndef SQLITE_OMIT_UTF16
000432  void sqlite3_result_error16(sqlite3_context *pCtx, const void *z, int n){
000433    assert( sqlite3_mutex_held(pCtx->pOut->db->mutex) );
000434    pCtx->isError = SQLITE_ERROR;
000435    sqlite3VdbeMemSetStr(pCtx->pOut, z, n, SQLITE_UTF16NATIVE, SQLITE_TRANSIENT);
000436  }
000437  #endif
000438  void sqlite3_result_int(sqlite3_context *pCtx, int iVal){
000439    assert( sqlite3_mutex_held(pCtx->pOut->db->mutex) );
000440    sqlite3VdbeMemSetInt64(pCtx->pOut, (i64)iVal);
000441  }
000442  void sqlite3_result_int64(sqlite3_context *pCtx, i64 iVal){
000443    assert( sqlite3_mutex_held(pCtx->pOut->db->mutex) );
000444    sqlite3VdbeMemSetInt64(pCtx->pOut, iVal);
000445  }
000446  void sqlite3_result_null(sqlite3_context *pCtx){
000447    assert( sqlite3_mutex_held(pCtx->pOut->db->mutex) );
000448    sqlite3VdbeMemSetNull(pCtx->pOut);
000449  }
000450  void sqlite3_result_pointer(
000451    sqlite3_context *pCtx,
000452    void *pPtr,
000453    const char *zPType,
000454    void (*xDestructor)(void*)
000455  ){
000456    Mem *pOut = pCtx->pOut;
000457    assert( sqlite3_mutex_held(pOut->db->mutex) );
000458    sqlite3VdbeMemRelease(pOut);
000459    pOut->flags = MEM_Null;
000460    sqlite3VdbeMemSetPointer(pOut, pPtr, zPType, xDestructor);
000461  }
000462  void sqlite3_result_subtype(sqlite3_context *pCtx, unsigned int eSubtype){
000463    Mem *pOut = pCtx->pOut;
000464    assert( sqlite3_mutex_held(pOut->db->mutex) );
000465    pOut->eSubtype = eSubtype & 0xff;
000466    pOut->flags |= MEM_Subtype;
000467  }
000468  void sqlite3_result_text(
000469    sqlite3_context *pCtx, 
000470    const char *z, 
000471    int n,
000472    void (*xDel)(void *)
000473  ){
000474    assert( sqlite3_mutex_held(pCtx->pOut->db->mutex) );
000475    setResultStrOrError(pCtx, z, n, SQLITE_UTF8, xDel);
000476  }
000477  void sqlite3_result_text64(
000478    sqlite3_context *pCtx, 
000479    const char *z, 
000480    sqlite3_uint64 n,
000481    void (*xDel)(void *),
000482    unsigned char enc
000483  ){
000484    assert( sqlite3_mutex_held(pCtx->pOut->db->mutex) );
000485    assert( xDel!=SQLITE_DYNAMIC );
000486    if( enc==SQLITE_UTF16 ) enc = SQLITE_UTF16NATIVE;
000487    if( n>0x7fffffff ){
000488      (void)invokeValueDestructor(z, xDel, pCtx);
000489    }else{
000490      setResultStrOrError(pCtx, z, (int)n, enc, xDel);
000491    }
000492  }
000493  #ifndef SQLITE_OMIT_UTF16
000494  void sqlite3_result_text16(
000495    sqlite3_context *pCtx, 
000496    const void *z, 
000497    int n, 
000498    void (*xDel)(void *)
000499  ){
000500    assert( sqlite3_mutex_held(pCtx->pOut->db->mutex) );
000501    setResultStrOrError(pCtx, z, n, SQLITE_UTF16NATIVE, xDel);
000502  }
000503  void sqlite3_result_text16be(
000504    sqlite3_context *pCtx, 
000505    const void *z, 
000506    int n, 
000507    void (*xDel)(void *)
000508  ){
000509    assert( sqlite3_mutex_held(pCtx->pOut->db->mutex) );
000510    setResultStrOrError(pCtx, z, n, SQLITE_UTF16BE, xDel);
000511  }
000512  void sqlite3_result_text16le(
000513    sqlite3_context *pCtx, 
000514    const void *z, 
000515    int n, 
000516    void (*xDel)(void *)
000517  ){
000518    assert( sqlite3_mutex_held(pCtx->pOut->db->mutex) );
000519    setResultStrOrError(pCtx, z, n, SQLITE_UTF16LE, xDel);
000520  }
000521  #endif /* SQLITE_OMIT_UTF16 */
000522  void sqlite3_result_value(sqlite3_context *pCtx, sqlite3_value *pValue){
000523    assert( sqlite3_mutex_held(pCtx->pOut->db->mutex) );
000524    sqlite3VdbeMemCopy(pCtx->pOut, pValue);
000525  }
000526  void sqlite3_result_zeroblob(sqlite3_context *pCtx, int n){
000527    assert( sqlite3_mutex_held(pCtx->pOut->db->mutex) );
000528    sqlite3VdbeMemSetZeroBlob(pCtx->pOut, n);
000529  }
000530  int sqlite3_result_zeroblob64(sqlite3_context *pCtx, u64 n){
000531    Mem *pOut = pCtx->pOut;
000532    assert( sqlite3_mutex_held(pOut->db->mutex) );
000533    if( n>(u64)pOut->db->aLimit[SQLITE_LIMIT_LENGTH] ){
000534      return SQLITE_TOOBIG;
000535    }
000536    sqlite3VdbeMemSetZeroBlob(pCtx->pOut, (int)n);
000537    return SQLITE_OK;
000538  }
000539  void sqlite3_result_error_code(sqlite3_context *pCtx, int errCode){
000540    pCtx->isError = errCode ? errCode : -1;
000541  #ifdef SQLITE_DEBUG
000542    if( pCtx->pVdbe ) pCtx->pVdbe->rcApp = errCode;
000543  #endif
000544    if( pCtx->pOut->flags & MEM_Null ){
000545      sqlite3VdbeMemSetStr(pCtx->pOut, sqlite3ErrStr(errCode), -1, 
000546                           SQLITE_UTF8, SQLITE_STATIC);
000547    }
000548  }
000549  
000550  /* Force an SQLITE_TOOBIG error. */
000551  void sqlite3_result_error_toobig(sqlite3_context *pCtx){
000552    assert( sqlite3_mutex_held(pCtx->pOut->db->mutex) );
000553    pCtx->isError = SQLITE_TOOBIG;
000554    sqlite3VdbeMemSetStr(pCtx->pOut, "string or blob too big", -1, 
000555                         SQLITE_UTF8, SQLITE_STATIC);
000556  }
000557  
000558  /* An SQLITE_NOMEM error. */
000559  void sqlite3_result_error_nomem(sqlite3_context *pCtx){
000560    assert( sqlite3_mutex_held(pCtx->pOut->db->mutex) );
000561    sqlite3VdbeMemSetNull(pCtx->pOut);
000562    pCtx->isError = SQLITE_NOMEM_BKPT;
000563    sqlite3OomFault(pCtx->pOut->db);
000564  }
000565  
000566  #ifndef SQLITE_UNTESTABLE
000567  /* Force the INT64 value currently stored as the result to be
000568  ** a MEM_IntReal value.  See the SQLITE_TESTCTRL_RESULT_INTREAL
000569  ** test-control.
000570  */
000571  void sqlite3ResultIntReal(sqlite3_context *pCtx){ 
000572    assert( sqlite3_mutex_held(pCtx->pOut->db->mutex) );
000573    if( pCtx->pOut->flags & MEM_Int ){
000574      pCtx->pOut->flags &= ~MEM_Int;
000575      pCtx->pOut->flags |= MEM_IntReal;
000576    }
000577  }
000578  #endif
000579  
000580  
000581  /*
000582  ** This function is called after a transaction has been committed. It 
000583  ** invokes callbacks registered with sqlite3_wal_hook() as required.
000584  */
000585  static int doWalCallbacks(sqlite3 *db){
000586    int rc = SQLITE_OK;
000587  #ifndef SQLITE_OMIT_WAL
000588    int i;
000589    for(i=0; i<db->nDb; i++){
000590      Btree *pBt = db->aDb[i].pBt;
000591      if( pBt ){
000592        int nEntry;
000593        sqlite3BtreeEnter(pBt);
000594        nEntry = sqlite3PagerWalCallback(sqlite3BtreePager(pBt));
000595        sqlite3BtreeLeave(pBt);
000596        if( nEntry>0 && db->xWalCallback && rc==SQLITE_OK ){
000597          rc = db->xWalCallback(db->pWalArg, db, db->aDb[i].zDbSName, nEntry);
000598        }
000599      }
000600    }
000601  #endif
000602    return rc;
000603  }
000604  
000605  
000606  /*
000607  ** Execute the statement pStmt, either until a row of data is ready, the
000608  ** statement is completely executed or an error occurs.
000609  **
000610  ** This routine implements the bulk of the logic behind the sqlite_step()
000611  ** API.  The only thing omitted is the automatic recompile if a 
000612  ** schema change has occurred.  That detail is handled by the
000613  ** outer sqlite3_step() wrapper procedure.
000614  */
000615  static int sqlite3Step(Vdbe *p){
000616    sqlite3 *db;
000617    int rc;
000618  
000619    assert(p);
000620    if( p->magic!=VDBE_MAGIC_RUN ){
000621      /* We used to require that sqlite3_reset() be called before retrying
000622      ** sqlite3_step() after any error or after SQLITE_DONE.  But beginning
000623      ** with version 3.7.0, we changed this so that sqlite3_reset() would
000624      ** be called automatically instead of throwing the SQLITE_MISUSE error.
000625      ** This "automatic-reset" change is not technically an incompatibility, 
000626      ** since any application that receives an SQLITE_MISUSE is broken by
000627      ** definition.
000628      **
000629      ** Nevertheless, some published applications that were originally written
000630      ** for version 3.6.23 or earlier do in fact depend on SQLITE_MISUSE 
000631      ** returns, and those were broken by the automatic-reset change.  As a
000632      ** a work-around, the SQLITE_OMIT_AUTORESET compile-time restores the
000633      ** legacy behavior of returning SQLITE_MISUSE for cases where the 
000634      ** previous sqlite3_step() returned something other than a SQLITE_LOCKED
000635      ** or SQLITE_BUSY error.
000636      */
000637  #ifdef SQLITE_OMIT_AUTORESET
000638      if( (rc = p->rc&0xff)==SQLITE_BUSY || rc==SQLITE_LOCKED ){
000639        sqlite3_reset((sqlite3_stmt*)p);
000640      }else{
000641        return SQLITE_MISUSE_BKPT;
000642      }
000643  #else
000644      sqlite3_reset((sqlite3_stmt*)p);
000645  #endif
000646    }
000647  
000648    /* Check that malloc() has not failed. If it has, return early. */
000649    db = p->db;
000650    if( db->mallocFailed ){
000651      p->rc = SQLITE_NOMEM;
000652      return SQLITE_NOMEM_BKPT;
000653    }
000654  
000655    if( p->pc<0 && p->expired ){
000656      p->rc = SQLITE_SCHEMA;
000657      rc = SQLITE_ERROR;
000658      goto end_of_step;
000659    }
000660    if( p->pc<0 ){
000661      /* If there are no other statements currently running, then
000662      ** reset the interrupt flag.  This prevents a call to sqlite3_interrupt
000663      ** from interrupting a statement that has not yet started.
000664      */
000665      if( db->nVdbeActive==0 ){
000666        db->u1.isInterrupted = 0;
000667      }
000668  
000669      assert( db->nVdbeWrite>0 || db->autoCommit==0 
000670          || (db->nDeferredCons==0 && db->nDeferredImmCons==0)
000671      );
000672  
000673  #ifndef SQLITE_OMIT_TRACE
000674      if( (db->mTrace & (SQLITE_TRACE_PROFILE|SQLITE_TRACE_XPROFILE))!=0
000675          && !db->init.busy && p->zSql ){
000676        sqlite3OsCurrentTimeInt64(db->pVfs, &p->startTime);
000677      }else{
000678        assert( p->startTime==0 );
000679      }
000680  #endif
000681  
000682      db->nVdbeActive++;
000683      if( p->readOnly==0 ) db->nVdbeWrite++;
000684      if( p->bIsReader ) db->nVdbeRead++;
000685      p->pc = 0;
000686    }
000687  #ifdef SQLITE_DEBUG
000688    p->rcApp = SQLITE_OK;
000689  #endif
000690  #ifndef SQLITE_OMIT_EXPLAIN
000691    if( p->explain ){
000692      rc = sqlite3VdbeList(p);
000693    }else
000694  #endif /* SQLITE_OMIT_EXPLAIN */
000695    {
000696      db->nVdbeExec++;
000697      rc = sqlite3VdbeExec(p);
000698      db->nVdbeExec--;
000699    }
000700  
000701    if( rc!=SQLITE_ROW ){
000702  #ifndef SQLITE_OMIT_TRACE
000703      /* If the statement completed successfully, invoke the profile callback */
000704      checkProfileCallback(db, p);
000705  #endif
000706  
000707      if( rc==SQLITE_DONE && db->autoCommit ){
000708        assert( p->rc==SQLITE_OK );
000709        p->rc = doWalCallbacks(db);
000710        if( p->rc!=SQLITE_OK ){
000711          rc = SQLITE_ERROR;
000712        }
000713      }
000714    }
000715  
000716    db->errCode = rc;
000717    if( SQLITE_NOMEM==sqlite3ApiExit(p->db, p->rc) ){
000718      p->rc = SQLITE_NOMEM_BKPT;
000719    }
000720  end_of_step:
000721    /* At this point local variable rc holds the value that should be 
000722    ** returned if this statement was compiled using the legacy 
000723    ** sqlite3_prepare() interface. According to the docs, this can only
000724    ** be one of the values in the first assert() below. Variable p->rc 
000725    ** contains the value that would be returned if sqlite3_finalize() 
000726    ** were called on statement p.
000727    */
000728    assert( rc==SQLITE_ROW  || rc==SQLITE_DONE   || rc==SQLITE_ERROR 
000729         || (rc&0xff)==SQLITE_BUSY || rc==SQLITE_MISUSE
000730    );
000731    assert( (p->rc!=SQLITE_ROW && p->rc!=SQLITE_DONE) || p->rc==p->rcApp );
000732    if( rc!=SQLITE_ROW 
000733     && rc!=SQLITE_DONE
000734     && (p->prepFlags & SQLITE_PREPARE_SAVESQL)!=0
000735    ){
000736      /* If this statement was prepared using saved SQL and an 
000737      ** error has occurred, then return the error code in p->rc to the
000738      ** caller. Set the error code in the database handle to the same value.
000739      */ 
000740      rc = sqlite3VdbeTransferError(p);
000741    }
000742    return (rc&db->errMask);
000743  }
000744  
000745  /*
000746  ** This is the top-level implementation of sqlite3_step().  Call
000747  ** sqlite3Step() to do most of the work.  If a schema error occurs,
000748  ** call sqlite3Reprepare() and try again.
000749  */
000750  int sqlite3_step(sqlite3_stmt *pStmt){
000751    int rc = SQLITE_OK;      /* Result from sqlite3Step() */
000752    Vdbe *v = (Vdbe*)pStmt;  /* the prepared statement */
000753    int cnt = 0;             /* Counter to prevent infinite loop of reprepares */
000754    sqlite3 *db;             /* The database connection */
000755  
000756    if( vdbeSafetyNotNull(v) ){
000757      return SQLITE_MISUSE_BKPT;
000758    }
000759    db = v->db;
000760    sqlite3_mutex_enter(db->mutex);
000761    v->doingRerun = 0;
000762    while( (rc = sqlite3Step(v))==SQLITE_SCHEMA
000763           && cnt++ < SQLITE_MAX_SCHEMA_RETRY ){
000764      int savedPc = v->pc;
000765      rc = sqlite3Reprepare(v);
000766      if( rc!=SQLITE_OK ){
000767        /* This case occurs after failing to recompile an sql statement. 
000768        ** The error message from the SQL compiler has already been loaded 
000769        ** into the database handle. This block copies the error message 
000770        ** from the database handle into the statement and sets the statement
000771        ** program counter to 0 to ensure that when the statement is 
000772        ** finalized or reset the parser error message is available via
000773        ** sqlite3_errmsg() and sqlite3_errcode().
000774        */
000775        const char *zErr = (const char *)sqlite3_value_text(db->pErr); 
000776        sqlite3DbFree(db, v->zErrMsg);
000777        if( !db->mallocFailed ){
000778          v->zErrMsg = sqlite3DbStrDup(db, zErr);
000779          v->rc = rc = sqlite3ApiExit(db, rc);
000780        } else {
000781          v->zErrMsg = 0;
000782          v->rc = rc = SQLITE_NOMEM_BKPT;
000783        }
000784        break;
000785      }
000786      sqlite3_reset(pStmt);
000787      if( savedPc>=0 ) v->doingRerun = 1;
000788      assert( v->expired==0 );
000789    }
000790    sqlite3_mutex_leave(db->mutex);
000791    return rc;
000792  }
000793  
000794  
000795  /*
000796  ** Extract the user data from a sqlite3_context structure and return a
000797  ** pointer to it.
000798  */
000799  void *sqlite3_user_data(sqlite3_context *p){
000800    assert( p && p->pFunc );
000801    return p->pFunc->pUserData;
000802  }
000803  
000804  /*
000805  ** Extract the user data from a sqlite3_context structure and return a
000806  ** pointer to it.
000807  **
000808  ** IMPLEMENTATION-OF: R-46798-50301 The sqlite3_context_db_handle() interface
000809  ** returns a copy of the pointer to the database connection (the 1st
000810  ** parameter) of the sqlite3_create_function() and
000811  ** sqlite3_create_function16() routines that originally registered the
000812  ** application defined function.
000813  */
000814  sqlite3 *sqlite3_context_db_handle(sqlite3_context *p){
000815    assert( p && p->pOut );
000816    return p->pOut->db;
000817  }
000818  
000819  /*
000820  ** If this routine is invoked from within an xColumn method of a virtual
000821  ** table, then it returns true if and only if the the call is during an
000822  ** UPDATE operation and the value of the column will not be modified
000823  ** by the UPDATE.
000824  **
000825  ** If this routine is called from any context other than within the
000826  ** xColumn method of a virtual table, then the return value is meaningless
000827  ** and arbitrary.
000828  **
000829  ** Virtual table implements might use this routine to optimize their
000830  ** performance by substituting a NULL result, or some other light-weight
000831  ** value, as a signal to the xUpdate routine that the column is unchanged.
000832  */
000833  int sqlite3_vtab_nochange(sqlite3_context *p){
000834    assert( p );
000835    return sqlite3_value_nochange(p->pOut);
000836  }
000837  
000838  /*
000839  ** Return the current time for a statement.  If the current time
000840  ** is requested more than once within the same run of a single prepared
000841  ** statement, the exact same time is returned for each invocation regardless
000842  ** of the amount of time that elapses between invocations.  In other words,
000843  ** the time returned is always the time of the first call.
000844  */
000845  sqlite3_int64 sqlite3StmtCurrentTime(sqlite3_context *p){
000846    int rc;
000847  #ifndef SQLITE_ENABLE_STAT4
000848    sqlite3_int64 *piTime = &p->pVdbe->iCurrentTime;
000849    assert( p->pVdbe!=0 );
000850  #else
000851    sqlite3_int64 iTime = 0;
000852    sqlite3_int64 *piTime = p->pVdbe!=0 ? &p->pVdbe->iCurrentTime : &iTime;
000853  #endif
000854    if( *piTime==0 ){
000855      rc = sqlite3OsCurrentTimeInt64(p->pOut->db->pVfs, piTime);
000856      if( rc ) *piTime = 0;
000857    }
000858    return *piTime;
000859  }
000860  
000861  /*
000862  ** Create a new aggregate context for p and return a pointer to
000863  ** its pMem->z element.
000864  */
000865  static SQLITE_NOINLINE void *createAggContext(sqlite3_context *p, int nByte){
000866    Mem *pMem = p->pMem;
000867    assert( (pMem->flags & MEM_Agg)==0 );
000868    if( nByte<=0 ){
000869      sqlite3VdbeMemSetNull(pMem);
000870      pMem->z = 0;
000871    }else{
000872      sqlite3VdbeMemClearAndResize(pMem, nByte);
000873      pMem->flags = MEM_Agg;
000874      pMem->u.pDef = p->pFunc;
000875      if( pMem->z ){
000876        memset(pMem->z, 0, nByte);
000877      }
000878    }
000879    return (void*)pMem->z;
000880  }
000881  
000882  /*
000883  ** Allocate or return the aggregate context for a user function.  A new
000884  ** context is allocated on the first call.  Subsequent calls return the
000885  ** same context that was returned on prior calls.
000886  */
000887  void *sqlite3_aggregate_context(sqlite3_context *p, int nByte){
000888    assert( p && p->pFunc && p->pFunc->xFinalize );
000889    assert( sqlite3_mutex_held(p->pOut->db->mutex) );
000890    testcase( nByte<0 );
000891    if( (p->pMem->flags & MEM_Agg)==0 ){
000892      return createAggContext(p, nByte);
000893    }else{
000894      return (void*)p->pMem->z;
000895    }
000896  }
000897  
000898  /*
000899  ** Return the auxiliary data pointer, if any, for the iArg'th argument to
000900  ** the user-function defined by pCtx.
000901  **
000902  ** The left-most argument is 0.
000903  **
000904  ** Undocumented behavior:  If iArg is negative then access a cache of
000905  ** auxiliary data pointers that is available to all functions within a
000906  ** single prepared statement.  The iArg values must match.
000907  */
000908  void *sqlite3_get_auxdata(sqlite3_context *pCtx, int iArg){
000909    AuxData *pAuxData;
000910  
000911    assert( sqlite3_mutex_held(pCtx->pOut->db->mutex) );
000912  #if SQLITE_ENABLE_STAT4
000913    if( pCtx->pVdbe==0 ) return 0;
000914  #else
000915    assert( pCtx->pVdbe!=0 );
000916  #endif
000917    for(pAuxData=pCtx->pVdbe->pAuxData; pAuxData; pAuxData=pAuxData->pNextAux){
000918      if(  pAuxData->iAuxArg==iArg && (pAuxData->iAuxOp==pCtx->iOp || iArg<0) ){
000919        return pAuxData->pAux;
000920      }
000921    }
000922    return 0;
000923  }
000924  
000925  /*
000926  ** Set the auxiliary data pointer and delete function, for the iArg'th
000927  ** argument to the user-function defined by pCtx. Any previous value is
000928  ** deleted by calling the delete function specified when it was set.
000929  **
000930  ** The left-most argument is 0.
000931  **
000932  ** Undocumented behavior:  If iArg is negative then make the data available
000933  ** to all functions within the current prepared statement using iArg as an
000934  ** access code.
000935  */
000936  void sqlite3_set_auxdata(
000937    sqlite3_context *pCtx, 
000938    int iArg, 
000939    void *pAux, 
000940    void (*xDelete)(void*)
000941  ){
000942    AuxData *pAuxData;
000943    Vdbe *pVdbe = pCtx->pVdbe;
000944  
000945    assert( sqlite3_mutex_held(pCtx->pOut->db->mutex) );
000946  #ifdef SQLITE_ENABLE_STAT4
000947    if( pVdbe==0 ) goto failed;
000948  #else
000949    assert( pVdbe!=0 );
000950  #endif
000951  
000952    for(pAuxData=pVdbe->pAuxData; pAuxData; pAuxData=pAuxData->pNextAux){
000953      if( pAuxData->iAuxArg==iArg && (pAuxData->iAuxOp==pCtx->iOp || iArg<0) ){
000954        break;
000955      }
000956    }
000957    if( pAuxData==0 ){
000958      pAuxData = sqlite3DbMallocZero(pVdbe->db, sizeof(AuxData));
000959      if( !pAuxData ) goto failed;
000960      pAuxData->iAuxOp = pCtx->iOp;
000961      pAuxData->iAuxArg = iArg;
000962      pAuxData->pNextAux = pVdbe->pAuxData;
000963      pVdbe->pAuxData = pAuxData;
000964      if( pCtx->isError==0 ) pCtx->isError = -1;
000965    }else if( pAuxData->xDeleteAux ){
000966      pAuxData->xDeleteAux(pAuxData->pAux);
000967    }
000968  
000969    pAuxData->pAux = pAux;
000970    pAuxData->xDeleteAux = xDelete;
000971    return;
000972  
000973  failed:
000974    if( xDelete ){
000975      xDelete(pAux);
000976    }
000977  }
000978  
000979  #ifndef SQLITE_OMIT_DEPRECATED
000980  /*
000981  ** Return the number of times the Step function of an aggregate has been 
000982  ** called.
000983  **
000984  ** This function is deprecated.  Do not use it for new code.  It is
000985  ** provide only to avoid breaking legacy code.  New aggregate function
000986  ** implementations should keep their own counts within their aggregate
000987  ** context.
000988  */
000989  int sqlite3_aggregate_count(sqlite3_context *p){
000990    assert( p && p->pMem && p->pFunc && p->pFunc->xFinalize );
000991    return p->pMem->n;
000992  }
000993  #endif
000994  
000995  /*
000996  ** Return the number of columns in the result set for the statement pStmt.
000997  */
000998  int sqlite3_column_count(sqlite3_stmt *pStmt){
000999    Vdbe *pVm = (Vdbe *)pStmt;
001000    return pVm ? pVm->nResColumn : 0;
001001  }
001002  
001003  /*
001004  ** Return the number of values available from the current row of the
001005  ** currently executing statement pStmt.
001006  */
001007  int sqlite3_data_count(sqlite3_stmt *pStmt){
001008    Vdbe *pVm = (Vdbe *)pStmt;
001009    if( pVm==0 || pVm->pResultSet==0 ) return 0;
001010    return pVm->nResColumn;
001011  }
001012  
001013  /*
001014  ** Return a pointer to static memory containing an SQL NULL value.
001015  */
001016  static const Mem *columnNullValue(void){
001017    /* Even though the Mem structure contains an element
001018    ** of type i64, on certain architectures (x86) with certain compiler
001019    ** switches (-Os), gcc may align this Mem object on a 4-byte boundary
001020    ** instead of an 8-byte one. This all works fine, except that when
001021    ** running with SQLITE_DEBUG defined the SQLite code sometimes assert()s
001022    ** that a Mem structure is located on an 8-byte boundary. To prevent
001023    ** these assert()s from failing, when building with SQLITE_DEBUG defined
001024    ** using gcc, we force nullMem to be 8-byte aligned using the magical
001025    ** __attribute__((aligned(8))) macro.  */
001026    static const Mem nullMem 
001027  #if defined(SQLITE_DEBUG) && defined(__GNUC__)
001028      __attribute__((aligned(8))) 
001029  #endif
001030      = {
001031          /* .u          = */ {0},
001032          /* .flags      = */ (u16)MEM_Null,
001033          /* .enc        = */ (u8)0,
001034          /* .eSubtype   = */ (u8)0,
001035          /* .n          = */ (int)0,
001036          /* .z          = */ (char*)0,
001037          /* .zMalloc    = */ (char*)0,
001038          /* .szMalloc   = */ (int)0,
001039          /* .uTemp      = */ (u32)0,
001040          /* .db         = */ (sqlite3*)0,
001041          /* .xDel       = */ (void(*)(void*))0,
001042  #ifdef SQLITE_DEBUG
001043          /* .pScopyFrom = */ (Mem*)0,
001044          /* .mScopyFlags= */ 0,
001045  #endif
001046        };
001047    return &nullMem;
001048  }
001049  
001050  /*
001051  ** Check to see if column iCol of the given statement is valid.  If
001052  ** it is, return a pointer to the Mem for the value of that column.
001053  ** If iCol is not valid, return a pointer to a Mem which has a value
001054  ** of NULL.
001055  */
001056  static Mem *columnMem(sqlite3_stmt *pStmt, int i){
001057    Vdbe *pVm;
001058    Mem *pOut;
001059  
001060    pVm = (Vdbe *)pStmt;
001061    if( pVm==0 ) return (Mem*)columnNullValue();
001062    assert( pVm->db );
001063    sqlite3_mutex_enter(pVm->db->mutex);
001064    if( pVm->pResultSet!=0 && i<pVm->nResColumn && i>=0 ){
001065      pOut = &pVm->pResultSet[i];
001066    }else{
001067      sqlite3Error(pVm->db, SQLITE_RANGE);
001068      pOut = (Mem*)columnNullValue();
001069    }
001070    return pOut;
001071  }
001072  
001073  /*
001074  ** This function is called after invoking an sqlite3_value_XXX function on a 
001075  ** column value (i.e. a value returned by evaluating an SQL expression in the
001076  ** select list of a SELECT statement) that may cause a malloc() failure. If 
001077  ** malloc() has failed, the threads mallocFailed flag is cleared and the result
001078  ** code of statement pStmt set to SQLITE_NOMEM.
001079  **
001080  ** Specifically, this is called from within:
001081  **
001082  **     sqlite3_column_int()
001083  **     sqlite3_column_int64()
001084  **     sqlite3_column_text()
001085  **     sqlite3_column_text16()
001086  **     sqlite3_column_real()
001087  **     sqlite3_column_bytes()
001088  **     sqlite3_column_bytes16()
001089  **     sqiite3_column_blob()
001090  */
001091  static void columnMallocFailure(sqlite3_stmt *pStmt)
001092  {
001093    /* If malloc() failed during an encoding conversion within an
001094    ** sqlite3_column_XXX API, then set the return code of the statement to
001095    ** SQLITE_NOMEM. The next call to _step() (if any) will return SQLITE_ERROR
001096    ** and _finalize() will return NOMEM.
001097    */
001098    Vdbe *p = (Vdbe *)pStmt;
001099    if( p ){
001100      assert( p->db!=0 );
001101      assert( sqlite3_mutex_held(p->db->mutex) );
001102      p->rc = sqlite3ApiExit(p->db, p->rc);
001103      sqlite3_mutex_leave(p->db->mutex);
001104    }
001105  }
001106  
001107  /**************************** sqlite3_column_  *******************************
001108  ** The following routines are used to access elements of the current row
001109  ** in the result set.
001110  */
001111  const void *sqlite3_column_blob(sqlite3_stmt *pStmt, int i){
001112    const void *val;
001113    val = sqlite3_value_blob( columnMem(pStmt,i) );
001114    /* Even though there is no encoding conversion, value_blob() might
001115    ** need to call malloc() to expand the result of a zeroblob() 
001116    ** expression. 
001117    */
001118    columnMallocFailure(pStmt);
001119    return val;
001120  }
001121  int sqlite3_column_bytes(sqlite3_stmt *pStmt, int i){
001122    int val = sqlite3_value_bytes( columnMem(pStmt,i) );
001123    columnMallocFailure(pStmt);
001124    return val;
001125  }
001126  int sqlite3_column_bytes16(sqlite3_stmt *pStmt, int i){
001127    int val = sqlite3_value_bytes16( columnMem(pStmt,i) );
001128    columnMallocFailure(pStmt);
001129    return val;
001130  }
001131  double sqlite3_column_double(sqlite3_stmt *pStmt, int i){
001132    double val = sqlite3_value_double( columnMem(pStmt,i) );
001133    columnMallocFailure(pStmt);
001134    return val;
001135  }
001136  int sqlite3_column_int(sqlite3_stmt *pStmt, int i){
001137    int val = sqlite3_value_int( columnMem(pStmt,i) );
001138    columnMallocFailure(pStmt);
001139    return val;
001140  }
001141  sqlite_int64 sqlite3_column_int64(sqlite3_stmt *pStmt, int i){
001142    sqlite_int64 val = sqlite3_value_int64( columnMem(pStmt,i) );
001143    columnMallocFailure(pStmt);
001144    return val;
001145  }
001146  const unsigned char *sqlite3_column_text(sqlite3_stmt *pStmt, int i){
001147    const unsigned char *val = sqlite3_value_text( columnMem(pStmt,i) );
001148    columnMallocFailure(pStmt);
001149    return val;
001150  }
001151  sqlite3_value *sqlite3_column_value(sqlite3_stmt *pStmt, int i){
001152    Mem *pOut = columnMem(pStmt, i);
001153    if( pOut->flags&MEM_Static ){
001154      pOut->flags &= ~MEM_Static;
001155      pOut->flags |= MEM_Ephem;
001156    }
001157    columnMallocFailure(pStmt);
001158    return (sqlite3_value *)pOut;
001159  }
001160  #ifndef SQLITE_OMIT_UTF16
001161  const void *sqlite3_column_text16(sqlite3_stmt *pStmt, int i){
001162    const void *val = sqlite3_value_text16( columnMem(pStmt,i) );
001163    columnMallocFailure(pStmt);
001164    return val;
001165  }
001166  #endif /* SQLITE_OMIT_UTF16 */
001167  int sqlite3_column_type(sqlite3_stmt *pStmt, int i){
001168    int iType = sqlite3_value_type( columnMem(pStmt,i) );
001169    columnMallocFailure(pStmt);
001170    return iType;
001171  }
001172  
001173  /*
001174  ** Convert the N-th element of pStmt->pColName[] into a string using
001175  ** xFunc() then return that string.  If N is out of range, return 0.
001176  **
001177  ** There are up to 5 names for each column.  useType determines which
001178  ** name is returned.  Here are the names:
001179  **
001180  **    0      The column name as it should be displayed for output
001181  **    1      The datatype name for the column
001182  **    2      The name of the database that the column derives from
001183  **    3      The name of the table that the column derives from
001184  **    4      The name of the table column that the result column derives from
001185  **
001186  ** If the result is not a simple column reference (if it is an expression
001187  ** or a constant) then useTypes 2, 3, and 4 return NULL.
001188  */
001189  static const void *columnName(
001190    sqlite3_stmt *pStmt,     /* The statement */
001191    int N,                   /* Which column to get the name for */
001192    int useUtf16,            /* True to return the name as UTF16 */
001193    int useType              /* What type of name */
001194  ){
001195    const void *ret;
001196    Vdbe *p;
001197    int n;
001198    sqlite3 *db;
001199  #ifdef SQLITE_ENABLE_API_ARMOR
001200    if( pStmt==0 ){
001201      (void)SQLITE_MISUSE_BKPT;
001202      return 0;
001203    }
001204  #endif
001205    ret = 0;
001206    p = (Vdbe *)pStmt;
001207    db = p->db;
001208    assert( db!=0 );
001209    n = sqlite3_column_count(pStmt);
001210    if( N<n && N>=0 ){
001211      N += useType*n;
001212      sqlite3_mutex_enter(db->mutex);
001213      assert( db->mallocFailed==0 );
001214  #ifndef SQLITE_OMIT_UTF16
001215      if( useUtf16 ){
001216        ret = sqlite3_value_text16((sqlite3_value*)&p->aColName[N]);
001217      }else
001218  #endif
001219      {
001220        ret = sqlite3_value_text((sqlite3_value*)&p->aColName[N]);
001221      }
001222      /* A malloc may have failed inside of the _text() call. If this
001223      ** is the case, clear the mallocFailed flag and return NULL.
001224      */
001225      if( db->mallocFailed ){
001226        sqlite3OomClear(db);
001227        ret = 0;
001228      }
001229      sqlite3_mutex_leave(db->mutex);
001230    }
001231    return ret;
001232  }
001233  
001234  /*
001235  ** Return the name of the Nth column of the result set returned by SQL
001236  ** statement pStmt.
001237  */
001238  const char *sqlite3_column_name(sqlite3_stmt *pStmt, int N){
001239    return columnName(pStmt, N, 0, COLNAME_NAME);
001240  }
001241  #ifndef SQLITE_OMIT_UTF16
001242  const void *sqlite3_column_name16(sqlite3_stmt *pStmt, int N){
001243    return columnName(pStmt, N, 1, COLNAME_NAME);
001244  }
001245  #endif
001246  
001247  /*
001248  ** Constraint:  If you have ENABLE_COLUMN_METADATA then you must
001249  ** not define OMIT_DECLTYPE.
001250  */
001251  #if defined(SQLITE_OMIT_DECLTYPE) && defined(SQLITE_ENABLE_COLUMN_METADATA)
001252  # error "Must not define both SQLITE_OMIT_DECLTYPE \
001253           and SQLITE_ENABLE_COLUMN_METADATA"
001254  #endif
001255  
001256  #ifndef SQLITE_OMIT_DECLTYPE
001257  /*
001258  ** Return the column declaration type (if applicable) of the 'i'th column
001259  ** of the result set of SQL statement pStmt.
001260  */
001261  const char *sqlite3_column_decltype(sqlite3_stmt *pStmt, int N){
001262    return columnName(pStmt, N, 0, COLNAME_DECLTYPE);
001263  }
001264  #ifndef SQLITE_OMIT_UTF16
001265  const void *sqlite3_column_decltype16(sqlite3_stmt *pStmt, int N){
001266    return columnName(pStmt, N, 1, COLNAME_DECLTYPE);
001267  }
001268  #endif /* SQLITE_OMIT_UTF16 */
001269  #endif /* SQLITE_OMIT_DECLTYPE */
001270  
001271  #ifdef SQLITE_ENABLE_COLUMN_METADATA
001272  /*
001273  ** Return the name of the database from which a result column derives.
001274  ** NULL is returned if the result column is an expression or constant or
001275  ** anything else which is not an unambiguous reference to a database column.
001276  */
001277  const char *sqlite3_column_database_name(sqlite3_stmt *pStmt, int N){
001278    return columnName(pStmt, N, 0, COLNAME_DATABASE);
001279  }
001280  #ifndef SQLITE_OMIT_UTF16
001281  const void *sqlite3_column_database_name16(sqlite3_stmt *pStmt, int N){
001282    return columnName(pStmt, N, 1, COLNAME_DATABASE);
001283  }
001284  #endif /* SQLITE_OMIT_UTF16 */
001285  
001286  /*
001287  ** Return the name of the table from which a result column derives.
001288  ** NULL is returned if the result column is an expression or constant or
001289  ** anything else which is not an unambiguous reference to a database column.
001290  */
001291  const char *sqlite3_column_table_name(sqlite3_stmt *pStmt, int N){
001292    return columnName(pStmt, N, 0, COLNAME_TABLE);
001293  }
001294  #ifndef SQLITE_OMIT_UTF16
001295  const void *sqlite3_column_table_name16(sqlite3_stmt *pStmt, int N){
001296    return columnName(pStmt, N, 1, COLNAME_TABLE);
001297  }
001298  #endif /* SQLITE_OMIT_UTF16 */
001299  
001300  /*
001301  ** Return the name of the table column from which a result column derives.
001302  ** NULL is returned if the result column is an expression or constant or
001303  ** anything else which is not an unambiguous reference to a database column.
001304  */
001305  const char *sqlite3_column_origin_name(sqlite3_stmt *pStmt, int N){
001306    return columnName(pStmt, N, 0, COLNAME_COLUMN);
001307  }
001308  #ifndef SQLITE_OMIT_UTF16
001309  const void *sqlite3_column_origin_name16(sqlite3_stmt *pStmt, int N){
001310    return columnName(pStmt, N, 1, COLNAME_COLUMN);
001311  }
001312  #endif /* SQLITE_OMIT_UTF16 */
001313  #endif /* SQLITE_ENABLE_COLUMN_METADATA */
001314  
001315  
001316  /******************************* sqlite3_bind_  ***************************
001317  ** 
001318  ** Routines used to attach values to wildcards in a compiled SQL statement.
001319  */
001320  /*
001321  ** Unbind the value bound to variable i in virtual machine p. This is the 
001322  ** the same as binding a NULL value to the column. If the "i" parameter is
001323  ** out of range, then SQLITE_RANGE is returned. Othewise SQLITE_OK.
001324  **
001325  ** A successful evaluation of this routine acquires the mutex on p.
001326  ** the mutex is released if any kind of error occurs.
001327  **
001328  ** The error code stored in database p->db is overwritten with the return
001329  ** value in any case.
001330  */
001331  static int vdbeUnbind(Vdbe *p, int i){
001332    Mem *pVar;
001333    if( vdbeSafetyNotNull(p) ){
001334      return SQLITE_MISUSE_BKPT;
001335    }
001336    sqlite3_mutex_enter(p->db->mutex);
001337    if( p->magic!=VDBE_MAGIC_RUN || p->pc>=0 ){
001338      sqlite3Error(p->db, SQLITE_MISUSE);
001339      sqlite3_mutex_leave(p->db->mutex);
001340      sqlite3_log(SQLITE_MISUSE, 
001341          "bind on a busy prepared statement: [%s]", p->zSql);
001342      return SQLITE_MISUSE_BKPT;
001343    }
001344    if( i<1 || i>p->nVar ){
001345      sqlite3Error(p->db, SQLITE_RANGE);
001346      sqlite3_mutex_leave(p->db->mutex);
001347      return SQLITE_RANGE;
001348    }
001349    i--;
001350    pVar = &p->aVar[i];
001351    sqlite3VdbeMemRelease(pVar);
001352    pVar->flags = MEM_Null;
001353    p->db->errCode = SQLITE_OK;
001354  
001355    /* If the bit corresponding to this variable in Vdbe.expmask is set, then 
001356    ** binding a new value to this variable invalidates the current query plan.
001357    **
001358    ** IMPLEMENTATION-OF: R-48440-37595 If the specific value bound to host
001359    ** parameter in the WHERE clause might influence the choice of query plan
001360    ** for a statement, then the statement will be automatically recompiled,
001361    ** as if there had been a schema change, on the first sqlite3_step() call
001362    ** following any change to the bindings of that parameter.
001363    */
001364    assert( (p->prepFlags & SQLITE_PREPARE_SAVESQL)!=0 || p->expmask==0 );
001365    if( p->expmask!=0 && (p->expmask & (i>=31 ? 0x80000000 : (u32)1<<i))!=0 ){
001366      p->expired = 1;
001367    }
001368    return SQLITE_OK;
001369  }
001370  
001371  /*
001372  ** Bind a text or BLOB value.
001373  */
001374  static int bindText(
001375    sqlite3_stmt *pStmt,   /* The statement to bind against */
001376    int i,                 /* Index of the parameter to bind */
001377    const void *zData,     /* Pointer to the data to be bound */
001378    int nData,             /* Number of bytes of data to be bound */
001379    void (*xDel)(void*),   /* Destructor for the data */
001380    u8 encoding            /* Encoding for the data */
001381  ){
001382    Vdbe *p = (Vdbe *)pStmt;
001383    Mem *pVar;
001384    int rc;
001385  
001386    rc = vdbeUnbind(p, i);
001387    if( rc==SQLITE_OK ){
001388      if( zData!=0 ){
001389        pVar = &p->aVar[i-1];
001390        rc = sqlite3VdbeMemSetStr(pVar, zData, nData, encoding, xDel);
001391        if( rc==SQLITE_OK && encoding!=0 ){
001392          rc = sqlite3VdbeChangeEncoding(pVar, ENC(p->db));
001393        }
001394        if( rc ){
001395          sqlite3Error(p->db, rc);
001396          rc = sqlite3ApiExit(p->db, rc);
001397        }
001398      }
001399      sqlite3_mutex_leave(p->db->mutex);
001400    }else if( xDel!=SQLITE_STATIC && xDel!=SQLITE_TRANSIENT ){
001401      xDel((void*)zData);
001402    }
001403    return rc;
001404  }
001405  
001406  
001407  /*
001408  ** Bind a blob value to an SQL statement variable.
001409  */
001410  int sqlite3_bind_blob(
001411    sqlite3_stmt *pStmt, 
001412    int i, 
001413    const void *zData, 
001414    int nData, 
001415    void (*xDel)(void*)
001416  ){
001417  #ifdef SQLITE_ENABLE_API_ARMOR
001418    if( nData<0 ) return SQLITE_MISUSE_BKPT;
001419  #endif
001420    return bindText(pStmt, i, zData, nData, xDel, 0);
001421  }
001422  int sqlite3_bind_blob64(
001423    sqlite3_stmt *pStmt, 
001424    int i, 
001425    const void *zData, 
001426    sqlite3_uint64 nData, 
001427    void (*xDel)(void*)
001428  ){
001429    assert( xDel!=SQLITE_DYNAMIC );
001430    if( nData>0x7fffffff ){
001431      return invokeValueDestructor(zData, xDel, 0);
001432    }else{
001433      return bindText(pStmt, i, zData, (int)nData, xDel, 0);
001434    }
001435  }
001436  int sqlite3_bind_double(sqlite3_stmt *pStmt, int i, double rValue){
001437    int rc;
001438    Vdbe *p = (Vdbe *)pStmt;
001439    rc = vdbeUnbind(p, i);
001440    if( rc==SQLITE_OK ){
001441      sqlite3VdbeMemSetDouble(&p->aVar[i-1], rValue);
001442      sqlite3_mutex_leave(p->db->mutex);
001443    }
001444    return rc;
001445  }
001446  int sqlite3_bind_int(sqlite3_stmt *p, int i, int iValue){
001447    return sqlite3_bind_int64(p, i, (i64)iValue);
001448  }
001449  int sqlite3_bind_int64(sqlite3_stmt *pStmt, int i, sqlite_int64 iValue){
001450    int rc;
001451    Vdbe *p = (Vdbe *)pStmt;
001452    rc = vdbeUnbind(p, i);
001453    if( rc==SQLITE_OK ){
001454      sqlite3VdbeMemSetInt64(&p->aVar[i-1], iValue);
001455      sqlite3_mutex_leave(p->db->mutex);
001456    }
001457    return rc;
001458  }
001459  int sqlite3_bind_null(sqlite3_stmt *pStmt, int i){
001460    int rc;
001461    Vdbe *p = (Vdbe*)pStmt;
001462    rc = vdbeUnbind(p, i);
001463    if( rc==SQLITE_OK ){
001464      sqlite3_mutex_leave(p->db->mutex);
001465    }
001466    return rc;
001467  }
001468  int sqlite3_bind_pointer(
001469    sqlite3_stmt *pStmt,
001470    int i,
001471    void *pPtr,
001472    const char *zPTtype,
001473    void (*xDestructor)(void*)
001474  ){
001475    int rc;
001476    Vdbe *p = (Vdbe*)pStmt;
001477    rc = vdbeUnbind(p, i);
001478    if( rc==SQLITE_OK ){
001479      sqlite3VdbeMemSetPointer(&p->aVar[i-1], pPtr, zPTtype, xDestructor);
001480      sqlite3_mutex_leave(p->db->mutex);
001481    }else if( xDestructor ){
001482      xDestructor(pPtr);
001483    }
001484    return rc;
001485  }
001486  int sqlite3_bind_text( 
001487    sqlite3_stmt *pStmt, 
001488    int i, 
001489    const char *zData, 
001490    int nData, 
001491    void (*xDel)(void*)
001492  ){
001493    return bindText(pStmt, i, zData, nData, xDel, SQLITE_UTF8);
001494  }
001495  int sqlite3_bind_text64( 
001496    sqlite3_stmt *pStmt, 
001497    int i, 
001498    const char *zData, 
001499    sqlite3_uint64 nData, 
001500    void (*xDel)(void*),
001501    unsigned char enc
001502  ){
001503    assert( xDel!=SQLITE_DYNAMIC );
001504    if( nData>0x7fffffff ){
001505      return invokeValueDestructor(zData, xDel, 0);
001506    }else{
001507      if( enc==SQLITE_UTF16 ) enc = SQLITE_UTF16NATIVE;
001508      return bindText(pStmt, i, zData, (int)nData, xDel, enc);
001509    }
001510  }
001511  #ifndef SQLITE_OMIT_UTF16
001512  int sqlite3_bind_text16(
001513    sqlite3_stmt *pStmt, 
001514    int i, 
001515    const void *zData, 
001516    int nData, 
001517    void (*xDel)(void*)
001518  ){
001519    return bindText(pStmt, i, zData, nData, xDel, SQLITE_UTF16NATIVE);
001520  }
001521  #endif /* SQLITE_OMIT_UTF16 */
001522  int sqlite3_bind_value(sqlite3_stmt *pStmt, int i, const sqlite3_value *pValue){
001523    int rc;
001524    switch( sqlite3_value_type((sqlite3_value*)pValue) ){
001525      case SQLITE_INTEGER: {
001526        rc = sqlite3_bind_int64(pStmt, i, pValue->u.i);
001527        break;
001528      }
001529      case SQLITE_FLOAT: {
001530        rc = sqlite3_bind_double(pStmt, i, pValue->u.r);
001531        break;
001532      }
001533      case SQLITE_BLOB: {
001534        if( pValue->flags & MEM_Zero ){
001535          rc = sqlite3_bind_zeroblob(pStmt, i, pValue->u.nZero);
001536        }else{
001537          rc = sqlite3_bind_blob(pStmt, i, pValue->z, pValue->n,SQLITE_TRANSIENT);
001538        }
001539        break;
001540      }
001541      case SQLITE_TEXT: {
001542        rc = bindText(pStmt,i,  pValue->z, pValue->n, SQLITE_TRANSIENT,
001543                                pValue->enc);
001544        break;
001545      }
001546      default: {
001547        rc = sqlite3_bind_null(pStmt, i);
001548        break;
001549      }
001550    }
001551    return rc;
001552  }
001553  int sqlite3_bind_zeroblob(sqlite3_stmt *pStmt, int i, int n){
001554    int rc;
001555    Vdbe *p = (Vdbe *)pStmt;
001556    rc = vdbeUnbind(p, i);
001557    if( rc==SQLITE_OK ){
001558      sqlite3VdbeMemSetZeroBlob(&p->aVar[i-1], n);
001559      sqlite3_mutex_leave(p->db->mutex);
001560    }
001561    return rc;
001562  }
001563  int sqlite3_bind_zeroblob64(sqlite3_stmt *pStmt, int i, sqlite3_uint64 n){
001564    int rc;
001565    Vdbe *p = (Vdbe *)pStmt;
001566    sqlite3_mutex_enter(p->db->mutex);
001567    if( n>(u64)p->db->aLimit[SQLITE_LIMIT_LENGTH] ){
001568      rc = SQLITE_TOOBIG;
001569    }else{
001570      assert( (n & 0x7FFFFFFF)==n );
001571      rc = sqlite3_bind_zeroblob(pStmt, i, n);
001572    }
001573    rc = sqlite3ApiExit(p->db, rc);
001574    sqlite3_mutex_leave(p->db->mutex);
001575    return rc;
001576  }
001577  
001578  /*
001579  ** Return the number of wildcards that can be potentially bound to.
001580  ** This routine is added to support DBD::SQLite.  
001581  */
001582  int sqlite3_bind_parameter_count(sqlite3_stmt *pStmt){
001583    Vdbe *p = (Vdbe*)pStmt;
001584    return p ? p->nVar : 0;
001585  }
001586  
001587  /*
001588  ** Return the name of a wildcard parameter.  Return NULL if the index
001589  ** is out of range or if the wildcard is unnamed.
001590  **
001591  ** The result is always UTF-8.
001592  */
001593  const char *sqlite3_bind_parameter_name(sqlite3_stmt *pStmt, int i){
001594    Vdbe *p = (Vdbe*)pStmt;
001595    if( p==0 ) return 0;
001596    return sqlite3VListNumToName(p->pVList, i);
001597  }
001598  
001599  /*
001600  ** Given a wildcard parameter name, return the index of the variable
001601  ** with that name.  If there is no variable with the given name,
001602  ** return 0.
001603  */
001604  int sqlite3VdbeParameterIndex(Vdbe *p, const char *zName, int nName){
001605    if( p==0 || zName==0 ) return 0;
001606    return sqlite3VListNameToNum(p->pVList, zName, nName);
001607  }
001608  int sqlite3_bind_parameter_index(sqlite3_stmt *pStmt, const char *zName){
001609    return sqlite3VdbeParameterIndex((Vdbe*)pStmt, zName, sqlite3Strlen30(zName));
001610  }
001611  
001612  /*
001613  ** Transfer all bindings from the first statement over to the second.
001614  */
001615  int sqlite3TransferBindings(sqlite3_stmt *pFromStmt, sqlite3_stmt *pToStmt){
001616    Vdbe *pFrom = (Vdbe*)pFromStmt;
001617    Vdbe *pTo = (Vdbe*)pToStmt;
001618    int i;
001619    assert( pTo->db==pFrom->db );
001620    assert( pTo->nVar==pFrom->nVar );
001621    sqlite3_mutex_enter(pTo->db->mutex);
001622    for(i=0; i<pFrom->nVar; i++){
001623      sqlite3VdbeMemMove(&pTo->aVar[i], &pFrom->aVar[i]);
001624    }
001625    sqlite3_mutex_leave(pTo->db->mutex);
001626    return SQLITE_OK;
001627  }
001628  
001629  #ifndef SQLITE_OMIT_DEPRECATED
001630  /*
001631  ** Deprecated external interface.  Internal/core SQLite code
001632  ** should call sqlite3TransferBindings.
001633  **
001634  ** It is misuse to call this routine with statements from different
001635  ** database connections.  But as this is a deprecated interface, we
001636  ** will not bother to check for that condition.
001637  **
001638  ** If the two statements contain a different number of bindings, then
001639  ** an SQLITE_ERROR is returned.  Nothing else can go wrong, so otherwise
001640  ** SQLITE_OK is returned.
001641  */
001642  int sqlite3_transfer_bindings(sqlite3_stmt *pFromStmt, sqlite3_stmt *pToStmt){
001643    Vdbe *pFrom = (Vdbe*)pFromStmt;
001644    Vdbe *pTo = (Vdbe*)pToStmt;
001645    if( pFrom->nVar!=pTo->nVar ){
001646      return SQLITE_ERROR;
001647    }
001648    assert( (pTo->prepFlags & SQLITE_PREPARE_SAVESQL)!=0 || pTo->expmask==0 );
001649    if( pTo->expmask ){
001650      pTo->expired = 1;
001651    }
001652    assert( (pFrom->prepFlags & SQLITE_PREPARE_SAVESQL)!=0 || pFrom->expmask==0 );
001653    if( pFrom->expmask ){
001654      pFrom->expired = 1;
001655    }
001656    return sqlite3TransferBindings(pFromStmt, pToStmt);
001657  }
001658  #endif
001659  
001660  /*
001661  ** Return the sqlite3* database handle to which the prepared statement given
001662  ** in the argument belongs.  This is the same database handle that was
001663  ** the first argument to the sqlite3_prepare() that was used to create
001664  ** the statement in the first place.
001665  */
001666  sqlite3 *sqlite3_db_handle(sqlite3_stmt *pStmt){
001667    return pStmt ? ((Vdbe*)pStmt)->db : 0;
001668  }
001669  
001670  /*
001671  ** Return true if the prepared statement is guaranteed to not modify the
001672  ** database.
001673  */
001674  int sqlite3_stmt_readonly(sqlite3_stmt *pStmt){
001675    return pStmt ? ((Vdbe*)pStmt)->readOnly : 1;
001676  }
001677  
001678  /*
001679  ** Return 1 if the statement is an EXPLAIN and return 2 if the
001680  ** statement is an EXPLAIN QUERY PLAN
001681  */
001682  int sqlite3_stmt_isexplain(sqlite3_stmt *pStmt){
001683    return pStmt ? ((Vdbe*)pStmt)->explain : 0;
001684  }
001685  
001686  /*
001687  ** Return true if the prepared statement is in need of being reset.
001688  */
001689  int sqlite3_stmt_busy(sqlite3_stmt *pStmt){
001690    Vdbe *v = (Vdbe*)pStmt;
001691    return v!=0 && v->magic==VDBE_MAGIC_RUN && v->pc>=0;
001692  }
001693  
001694  /*
001695  ** Return a pointer to the next prepared statement after pStmt associated
001696  ** with database connection pDb.  If pStmt is NULL, return the first
001697  ** prepared statement for the database connection.  Return NULL if there
001698  ** are no more.
001699  */
001700  sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt){
001701    sqlite3_stmt *pNext;
001702  #ifdef SQLITE_ENABLE_API_ARMOR
001703    if( !sqlite3SafetyCheckOk(pDb) ){
001704      (void)SQLITE_MISUSE_BKPT;
001705      return 0;
001706    }
001707  #endif
001708    sqlite3_mutex_enter(pDb->mutex);
001709    if( pStmt==0 ){
001710      pNext = (sqlite3_stmt*)pDb->pVdbe;
001711    }else{
001712      pNext = (sqlite3_stmt*)((Vdbe*)pStmt)->pNext;
001713    }
001714    sqlite3_mutex_leave(pDb->mutex);
001715    return pNext;
001716  }
001717  
001718  /*
001719  ** Return the value of a status counter for a prepared statement
001720  */
001721  int sqlite3_stmt_status(sqlite3_stmt *pStmt, int op, int resetFlag){
001722    Vdbe *pVdbe = (Vdbe*)pStmt;
001723    u32 v;
001724  #ifdef SQLITE_ENABLE_API_ARMOR
001725    if( !pStmt 
001726     || (op!=SQLITE_STMTSTATUS_MEMUSED && (op<0||op>=ArraySize(pVdbe->aCounter)))
001727    ){
001728      (void)SQLITE_MISUSE_BKPT;
001729      return 0;
001730    }
001731  #endif
001732    if( op==SQLITE_STMTSTATUS_MEMUSED ){
001733      sqlite3 *db = pVdbe->db;
001734      sqlite3_mutex_enter(db->mutex);
001735      v = 0;
001736      db->pnBytesFreed = (int*)&v;
001737      sqlite3VdbeClearObject(db, pVdbe);
001738      sqlite3DbFree(db, pVdbe);
001739      db->pnBytesFreed = 0;
001740      sqlite3_mutex_leave(db->mutex);
001741    }else{
001742      v = pVdbe->aCounter[op];
001743      if( resetFlag ) pVdbe->aCounter[op] = 0;
001744    }
001745    return (int)v;
001746  }
001747  
001748  /*
001749  ** Return the SQL associated with a prepared statement
001750  */
001751  const char *sqlite3_sql(sqlite3_stmt *pStmt){
001752    Vdbe *p = (Vdbe *)pStmt;
001753    return p ? p->zSql : 0;
001754  }
001755  
001756  /*
001757  ** Return the SQL associated with a prepared statement with
001758  ** bound parameters expanded.  Space to hold the returned string is
001759  ** obtained from sqlite3_malloc().  The caller is responsible for
001760  ** freeing the returned string by passing it to sqlite3_free().
001761  **
001762  ** The SQLITE_TRACE_SIZE_LIMIT puts an upper bound on the size of
001763  ** expanded bound parameters.
001764  */
001765  char *sqlite3_expanded_sql(sqlite3_stmt *pStmt){
001766  #ifdef SQLITE_OMIT_TRACE
001767    return 0;
001768  #else
001769    char *z = 0;
001770    const char *zSql = sqlite3_sql(pStmt);
001771    if( zSql ){
001772      Vdbe *p = (Vdbe *)pStmt;
001773      sqlite3_mutex_enter(p->db->mutex);
001774      z = sqlite3VdbeExpandSql(p, zSql);
001775      sqlite3_mutex_leave(p->db->mutex);
001776    }
001777    return z;
001778  #endif
001779  }
001780  
001781  #ifdef SQLITE_ENABLE_NORMALIZE
001782  /*
001783  ** Return the normalized SQL associated with a prepared statement.
001784  */
001785  const char *sqlite3_normalized_sql(sqlite3_stmt *pStmt){
001786    Vdbe *p = (Vdbe *)pStmt;
001787    if( p==0 ) return 0;
001788    if( p->zNormSql==0 && ALWAYS(p->zSql!=0) ){
001789      sqlite3_mutex_enter(p->db->mutex);
001790      p->zNormSql = sqlite3Normalize(p, p->zSql);
001791      sqlite3_mutex_leave(p->db->mutex);
001792    }
001793    return p->zNormSql;
001794  }
001795  #endif /* SQLITE_ENABLE_NORMALIZE */
001796  
001797  #ifdef SQLITE_ENABLE_PREUPDATE_HOOK
001798  /*
001799  ** Allocate and populate an UnpackedRecord structure based on the serialized
001800  ** record in nKey/pKey. Return a pointer to the new UnpackedRecord structure
001801  ** if successful, or a NULL pointer if an OOM error is encountered.
001802  */
001803  static UnpackedRecord *vdbeUnpackRecord(
001804    KeyInfo *pKeyInfo, 
001805    int nKey, 
001806    const void *pKey
001807  ){
001808    UnpackedRecord *pRet;           /* Return value */
001809  
001810    pRet = sqlite3VdbeAllocUnpackedRecord(pKeyInfo);
001811    if( pRet ){
001812      memset(pRet->aMem, 0, sizeof(Mem)*(pKeyInfo->nKeyField+1));
001813      sqlite3VdbeRecordUnpack(pKeyInfo, nKey, pKey, pRet);
001814    }
001815    return pRet;
001816  }
001817  
001818  /*
001819  ** This function is called from within a pre-update callback to retrieve
001820  ** a field of the row currently being updated or deleted.
001821  */
001822  int sqlite3_preupdate_old(sqlite3 *db, int iIdx, sqlite3_value **ppValue){
001823    PreUpdate *p = db->pPreUpdate;
001824    Mem *pMem;
001825    int rc = SQLITE_OK;
001826  
001827    /* Test that this call is being made from within an SQLITE_DELETE or
001828    ** SQLITE_UPDATE pre-update callback, and that iIdx is within range. */
001829    if( !p || p->op==SQLITE_INSERT ){
001830      rc = SQLITE_MISUSE_BKPT;
001831      goto preupdate_old_out;
001832    }
001833    if( p->pPk ){
001834      iIdx = sqlite3TableColumnToIndex(p->pPk, iIdx);
001835    }
001836    if( iIdx>=p->pCsr->nField || iIdx<0 ){
001837      rc = SQLITE_RANGE;
001838      goto preupdate_old_out;
001839    }
001840  
001841    /* If the old.* record has not yet been loaded into memory, do so now. */
001842    if( p->pUnpacked==0 ){
001843      u32 nRec;
001844      u8 *aRec;
001845  
001846      nRec = sqlite3BtreePayloadSize(p->pCsr->uc.pCursor);
001847      aRec = sqlite3DbMallocRaw(db, nRec);
001848      if( !aRec ) goto preupdate_old_out;
001849      rc = sqlite3BtreePayload(p->pCsr->uc.pCursor, 0, nRec, aRec);
001850      if( rc==SQLITE_OK ){
001851        p->pUnpacked = vdbeUnpackRecord(&p->keyinfo, nRec, aRec);
001852        if( !p->pUnpacked ) rc = SQLITE_NOMEM;
001853      }
001854      if( rc!=SQLITE_OK ){
001855        sqlite3DbFree(db, aRec);
001856        goto preupdate_old_out;
001857      }
001858      p->aRecord = aRec;
001859    }
001860  
001861    pMem = *ppValue = &p->pUnpacked->aMem[iIdx];
001862    if( iIdx==p->pTab->iPKey ){
001863      sqlite3VdbeMemSetInt64(pMem, p->iKey1);
001864    }else if( iIdx>=p->pUnpacked->nField ){
001865      *ppValue = (sqlite3_value *)columnNullValue();
001866    }else if( p->pTab->aCol[iIdx].affinity==SQLITE_AFF_REAL ){
001867      if( pMem->flags & (MEM_Int|MEM_IntReal) ){
001868        testcase( pMem->flags & MEM_Int );
001869        testcase( pMem->flags & MEM_IntReal );
001870        sqlite3VdbeMemRealify(pMem);
001871      }
001872    }
001873  
001874   preupdate_old_out:
001875    sqlite3Error(db, rc);
001876    return sqlite3ApiExit(db, rc);
001877  }
001878  #endif /* SQLITE_ENABLE_PREUPDATE_HOOK */
001879  
001880  #ifdef SQLITE_ENABLE_PREUPDATE_HOOK
001881  /*
001882  ** This function is called from within a pre-update callback to retrieve
001883  ** the number of columns in the row being updated, deleted or inserted.
001884  */
001885  int sqlite3_preupdate_count(sqlite3 *db){
001886    PreUpdate *p = db->pPreUpdate;
001887    return (p ? p->keyinfo.nKeyField : 0);
001888  }
001889  #endif /* SQLITE_ENABLE_PREUPDATE_HOOK */
001890  
001891  #ifdef SQLITE_ENABLE_PREUPDATE_HOOK
001892  /*
001893  ** This function is designed to be called from within a pre-update callback
001894  ** only. It returns zero if the change that caused the callback was made
001895  ** immediately by a user SQL statement. Or, if the change was made by a
001896  ** trigger program, it returns the number of trigger programs currently
001897  ** on the stack (1 for a top-level trigger, 2 for a trigger fired by a 
001898  ** top-level trigger etc.).
001899  **
001900  ** For the purposes of the previous paragraph, a foreign key CASCADE, SET NULL
001901  ** or SET DEFAULT action is considered a trigger.
001902  */
001903  int sqlite3_preupdate_depth(sqlite3 *db){
001904    PreUpdate *p = db->pPreUpdate;
001905    return (p ? p->v->nFrame : 0);
001906  }
001907  #endif /* SQLITE_ENABLE_PREUPDATE_HOOK */
001908  
001909  #ifdef SQLITE_ENABLE_PREUPDATE_HOOK
001910  /*
001911  ** This function is called from within a pre-update callback to retrieve
001912  ** a field of the row currently being updated or inserted.
001913  */
001914  int sqlite3_preupdate_new(sqlite3 *db, int iIdx, sqlite3_value **ppValue){
001915    PreUpdate *p = db->pPreUpdate;
001916    int rc = SQLITE_OK;
001917    Mem *pMem;
001918  
001919    if( !p || p->op==SQLITE_DELETE ){
001920      rc = SQLITE_MISUSE_BKPT;
001921      goto preupdate_new_out;
001922    }
001923    if( p->pPk && p->op!=SQLITE_UPDATE ){
001924      iIdx = sqlite3TableColumnToIndex(p->pPk, iIdx);
001925    }
001926    if( iIdx>=p->pCsr->nField || iIdx<0 ){
001927      rc = SQLITE_RANGE;
001928      goto preupdate_new_out;
001929    }
001930  
001931    if( p->op==SQLITE_INSERT ){
001932      /* For an INSERT, memory cell p->iNewReg contains the serialized record
001933      ** that is being inserted. Deserialize it. */
001934      UnpackedRecord *pUnpack = p->pNewUnpacked;
001935      if( !pUnpack ){
001936        Mem *pData = &p->v->aMem[p->iNewReg];
001937        rc = ExpandBlob(pData);
001938        if( rc!=SQLITE_OK ) goto preupdate_new_out;
001939        pUnpack = vdbeUnpackRecord(&p->keyinfo, pData->n, pData->z);
001940        if( !pUnpack ){
001941          rc = SQLITE_NOMEM;
001942          goto preupdate_new_out;
001943        }
001944        p->pNewUnpacked = pUnpack;
001945      }
001946      pMem = &pUnpack->aMem[iIdx];
001947      if( iIdx==p->pTab->iPKey ){
001948        sqlite3VdbeMemSetInt64(pMem, p->iKey2);
001949      }else if( iIdx>=pUnpack->nField ){
001950        pMem = (sqlite3_value *)columnNullValue();
001951      }
001952    }else{
001953      /* For an UPDATE, memory cell (p->iNewReg+1+iIdx) contains the required
001954      ** value. Make a copy of the cell contents and return a pointer to it.
001955      ** It is not safe to return a pointer to the memory cell itself as the
001956      ** caller may modify the value text encoding.
001957      */
001958      assert( p->op==SQLITE_UPDATE );
001959      if( !p->aNew ){
001960        p->aNew = (Mem *)sqlite3DbMallocZero(db, sizeof(Mem) * p->pCsr->nField);
001961        if( !p->aNew ){
001962          rc = SQLITE_NOMEM;
001963          goto preupdate_new_out;
001964        }
001965      }
001966      assert( iIdx>=0 && iIdx<p->pCsr->nField );
001967      pMem = &p->aNew[iIdx];
001968      if( pMem->flags==0 ){
001969        if( iIdx==p->pTab->iPKey ){
001970          sqlite3VdbeMemSetInt64(pMem, p->iKey2);
001971        }else{
001972          rc = sqlite3VdbeMemCopy(pMem, &p->v->aMem[p->iNewReg+1+iIdx]);
001973          if( rc!=SQLITE_OK ) goto preupdate_new_out;
001974        }
001975      }
001976    }
001977    *ppValue = pMem;
001978  
001979   preupdate_new_out:
001980    sqlite3Error(db, rc);
001981    return sqlite3ApiExit(db, rc);
001982  }
001983  #endif /* SQLITE_ENABLE_PREUPDATE_HOOK */
001984  
001985  #ifdef SQLITE_ENABLE_STMT_SCANSTATUS
001986  /*
001987  ** Return status data for a single loop within query pStmt.
001988  */
001989  int sqlite3_stmt_scanstatus(
001990    sqlite3_stmt *pStmt,            /* Prepared statement being queried */
001991    int idx,                        /* Index of loop to report on */
001992    int iScanStatusOp,              /* Which metric to return */
001993    void *pOut                      /* OUT: Write the answer here */
001994  ){
001995    Vdbe *p = (Vdbe*)pStmt;
001996    ScanStatus *pScan;
001997    if( idx<0 || idx>=p->nScan ) return 1;
001998    pScan = &p->aScan[idx];
001999    switch( iScanStatusOp ){
002000      case SQLITE_SCANSTAT_NLOOP: {
002001        *(sqlite3_int64*)pOut = p->anExec[pScan->addrLoop];
002002        break;
002003      }
002004      case SQLITE_SCANSTAT_NVISIT: {
002005        *(sqlite3_int64*)pOut = p->anExec[pScan->addrVisit];
002006        break;
002007      }
002008      case SQLITE_SCANSTAT_EST: {
002009        double r = 1.0;
002010        LogEst x = pScan->nEst;
002011        while( x<100 ){
002012          x += 10;
002013          r *= 0.5;
002014        }
002015        *(double*)pOut = r*sqlite3LogEstToInt(x);
002016        break;
002017      }
002018      case SQLITE_SCANSTAT_NAME: {
002019        *(const char**)pOut = pScan->zName;
002020        break;
002021      }
002022      case SQLITE_SCANSTAT_EXPLAIN: {
002023        if( pScan->addrExplain ){
002024          *(const char**)pOut = p->aOp[ pScan->addrExplain ].p4.z;
002025        }else{
002026          *(const char**)pOut = 0;
002027        }
002028        break;
002029      }
002030      case SQLITE_SCANSTAT_SELECTID: {
002031        if( pScan->addrExplain ){
002032          *(int*)pOut = p->aOp[ pScan->addrExplain ].p1;
002033        }else{
002034          *(int*)pOut = -1;
002035        }
002036        break;
002037      }
002038      default: {
002039        return 1;
002040      }
002041    }
002042    return 0;
002043  }
002044  
002045  /*
002046  ** Zero all counters associated with the sqlite3_stmt_scanstatus() data.
002047  */
002048  void sqlite3_stmt_scanstatus_reset(sqlite3_stmt *pStmt){
002049    Vdbe *p = (Vdbe*)pStmt;
002050    memset(p->anExec, 0, p->nOp * sizeof(i64));
002051  }
002052  #endif /* SQLITE_ENABLE_STMT_SCANSTATUS */