SQLite

1.0.15

** inplicit conversion from one type to the other occurs as necessary.
** 
** Most of the code in this file is taken up by the sqliteVdbeExec()
** function which does the work of interpreting a VDBE program.
** But other routines are also provided to help in building up
** a program instruction by instruction.
**
** $Id: vdbe.c,v 1.47 2000/10/23 13:16:33 drh Exp $
*/
#include "sqliteInt.h"
#include <unistd.h>
#include <ctype.h>

/*
** SQL is translated into a sequence of instructions to be

  int (*xBusy)(void*,const char*,int)  /* Called when a file is busy */
){
  int pc;                    /* The program counter */
  Op *pOp;                   /* Current operation */
  int rc;                    /* Value to return */
  Dbbe *pBe = p->pBe;        /* The backend driver */
  sqlite *db = p->db;        /* The database */
  char **zStack;
  Stack *aStack;
  char zBuf[100];            /* Space to sprintf() and integer */


  /* No instruction ever pushes more than a single element onto the
  ** stack.  And the stack never grows on successive executions of the
  ** same loop.  So the total number of instructions is an upper bound
  ** on the maximum stack depth required.
  **
  ** Allocation all the stack space we will ever need.
  */
  NeedStack(p, p->nOp);
  zStack = p->zStack;
  aStack = p->aStack;
  p->tos = -1;

  rc = SQLITE_OK;
#ifdef MEMORY_DEBUG
  if( access("vdbe_trace",0)==0 ){
    p->trace = stderr;
  }

      /* Opcode: Integer P1 * *
      **
      ** The integer value P1 is pushed onto the stack.
      */
      case OP_Integer: {
        int i = ++p->tos;
        VERIFY( if( NeedStack(p, p->tos) ) goto no_mem; )
        aStack[i].i = pOp->p1;
        aStack[i].flags = STK_Int;
        break;
      }

      /* Opcode: String * * P3
      **
      ** The string value P3 is pushed onto the stack.
      */
      case OP_String: {
        int i = ++p->tos;
        char *z;
        VERIFY( if( NeedStack(p, p->tos) ) goto no_mem; )
        z = pOp->p3;
        if( z==0 ) z = "";
        zStack[i] = z;
        aStack[i].n = strlen(z) + 1;
        aStack[i].flags = STK_Str;
        break;
      }

      /* Opcode: Null * * *
      **
      ** Push a NULL value onto the stack.
      */
      case OP_Null: {
        int i = ++p->tos;
        VERIFY( if( NeedStack(p, p->tos) ) goto no_mem; )
        zStack[i] = 0;
        aStack[i].flags = STK_Null;
        break;
      }

      /* Opcode: Pop P1 * *
      **
      ** P1 elements are popped off of the top of stack and discarded.
      */

      ** top of the stack.
      */
      case OP_Dup: {
        int i = p->tos - pOp->p1;
        int j = ++p->tos;
        VERIFY( if( i<0 ) goto not_enough_stack; )
        VERIFY( if( NeedStack(p, p->tos) ) goto no_mem; )
        aStack[j] = aStack[i];
        if( aStack[i].flags & STK_Dyn ){
          zStack[j] = sqliteMalloc( aStack[j].n );
          if( zStack[j]==0 ) goto no_mem;
          memcpy(zStack[j], zStack[i], aStack[j].n);
        }else{
          zStack[j] = zStack[i];
        }
        break;
      }

      /* Opcode: Pull P1 * *
      **
      ** The P1-th element is removed from its current location on 
      ** the stack and pushed back on top of the stack.  The
      ** top of the stack is element 0, so "Pull 0 0 0" is
      ** a no-op.
      */
      case OP_Pull: {
        int from = p->tos - pOp->p1;
        int to = p->tos;
        int i;
        Stack ts;
        char *tz;
        VERIFY( if( from<0 ) goto not_enough_stack; )
        ts = aStack[from];
        tz = zStack[from];
        for(i=from; i<to; i++){
          aStack[i] = aStack[i+1];
          zStack[i] = zStack[i+1];
        }
        aStack[to] = ts;
        zStack[to] = tz;
        break;
      }

      /* Opcode: ColumnCount P1 * *
      **
      ** Specify the number of column values that will appear in the
      ** array passed as the 4th parameter to the callback.  No checking

      */
      case OP_Callback: {
        int i = p->tos - pOp->p1 + 1;
        int j;
        VERIFY( if( i<0 ) goto not_enough_stack; )
        VERIFY( if( NeedStack(p, p->tos+2) ) goto no_mem; )
        for(j=i; j<=p->tos; j++){
          if( (aStack[j].flags & STK_Null)==0 ){
            if( Stringify(p, j) ) goto no_mem;
          }
        }
        zStack[p->tos+1] = 0;
        if( xCallback!=0 ){
          if( xCallback(pArg, pOp->p1, &zStack[i], p->azColName)!=0 ){
            rc = SQLITE_ABORT;
          }
        }
        PopStack(p, pOp->p1);
        break;
      }

        nField = pOp->p1;
        zSep = pOp->p3;
        if( zSep==0 ) zSep = "";
        nSep = strlen(zSep);
        VERIFY( if( p->tos+1<nField ) goto not_enough_stack; )
        nByte = 1 - nSep;
        for(i=p->tos-nField+1; i<=p->tos; i++){
          if( aStack[i].flags & STK_Null ){
            nByte += nSep;
          }else{
            if( Stringify(p, i) ) goto no_mem;
            nByte += aStack[i].n - 1 + nSep;
          }
        }
        zNew = sqliteMalloc( nByte );
        if( zNew==0 ) goto no_mem;
        j = 0;
        for(i=p->tos-nField+1; i<=p->tos; i++){
          if( (aStack[i].flags & STK_Null)==0 ){
            memcpy(&zNew[j], zStack[i], aStack[i].n-1);
            j += aStack[i].n-1;
          }
          if( nSep>0 && i<p->tos ){
            memcpy(&zNew[j], zSep, nSep);
            j += nSep;
          }
        }
        zNew[j] = 0;
        if( pOp->p2==0 ) PopStack(p, nField);
        VERIFY( NeedStack(p, p->tos+1); )
        p->tos++;
        aStack[p->tos].n = nByte;
        aStack[p->tos].flags = STK_Str|STK_Dyn;
        zStack[p->tos] = zNew;
        break;
      }

      /* Opcode: Add * * *
      **
      ** Pop the top two elements from the stack, add them together,
      ** and push the result back onto the stack.  If either element

      case OP_Add:
      case OP_Subtract:
      case OP_Multiply:
      case OP_Divide: {
        int tos = p->tos;
        int nos = tos - 1;
        VERIFY( if( nos<0 ) goto not_enough_stack; )
        if( (aStack[tos].flags & aStack[nos].flags & STK_Int)==STK_Int ){
          int a, b;
          a = aStack[tos].i;
          b = aStack[nos].i;
          switch( pOp->opcode ){
            case OP_Add:         b += a;       break;
            case OP_Subtract:    b -= a;       break;
            case OP_Multiply:    b *= a;       break;
            default: {
              if( a==0 ) goto divide_by_zero;
              b /= a;
              break;
            }
          }
          PopStack(p, 2);
          p->tos = nos;
          aStack[nos].i = b;
          aStack[nos].flags = STK_Int;
        }else{
          double a, b;
          Realify(p, tos);
          Realify(p, nos);
          a = aStack[tos].r;
          b = aStack[nos].r;
          switch( pOp->opcode ){
            case OP_Add:         b += a;       break;
            case OP_Subtract:    b -= a;       break;
            case OP_Multiply:    b *= a;       break;
            default: {
              if( a==0.0 ) goto divide_by_zero;
              b /= a;
              break;
            }
          }
          PopStack(p, 1);
          Release(p, nos);
          aStack[nos].r = b;
          aStack[nos].flags = STK_Real;
        }
        break;

      divide_by_zero:
        PopStack(p, 2);
        p->tos = nos;
        aStack[nos].flags = STK_Null;
        break;
      }

      /* Opcode: Max * * *
      **
      ** Pop the top two elements from the stack then push back the
      ** largest of the two.
      */
      case OP_Max: {
        int tos = p->tos;
        int nos = tos - 1;
        int ft, fn;
        int copy = 0;
        VERIFY( if( nos<0 ) goto not_enough_stack; )
        ft = aStack[tos].flags;
        fn = aStack[nos].flags;
        if( fn & STK_Null ){
          copy = 1;
        }else if( (ft & fn & STK_Int)==STK_Int ){
          copy = aStack[nos].i<aStack[tos].i;
        }else if( ( (ft|fn) & (STK_Int|STK_Real) ) !=0 ){
          Realify(p, tos);
          Realify(p, nos);
          copy = aStack[tos].r>aStack[nos].r;
        }else{
          Stringify(p, tos);
          Stringify(p, nos);
          copy = sqliteCompare(zStack[tos],zStack[nos])>0;
        }
        if( copy ){
          Release(p, nos);
          aStack[nos] = aStack[tos];
          zStack[nos] = zStack[tos];
          zStack[tos] = 0;
          aStack[tos].flags = 0;
        }else{
          Release(p, tos);
        }
        p->tos = nos;
        break;
      }

      /* Opcode: Min * * *
      **
      ** Pop the top two elements from the stack then push back the
      ** smaller of the two. 
      */
      case OP_Min: {
        int tos = p->tos;
        int nos = tos - 1;
        int ft, fn;
        int copy = 0;
        VERIFY( if( nos<0 ) goto not_enough_stack; )
        ft = aStack[tos].flags;
        fn = aStack[nos].flags;
        if( fn & STK_Null ){
          copy = 1;
        }else if( ft & STK_Null ){
          copy = 0;
        }else if( (ft & fn & STK_Int)==STK_Int ){
          copy = aStack[nos].i>aStack[tos].i;
        }else if( ( (ft|fn) & (STK_Int|STK_Real) ) !=0 ){
          Realify(p, tos);
          Realify(p, nos);
          copy = aStack[tos].r<aStack[nos].r;
        }else{
          Stringify(p, tos);
          Stringify(p, nos);
          copy = sqliteCompare(zStack[tos],zStack[nos])<0;
        }
        if( copy ){
          Release(p, nos);
          aStack[nos] = aStack[tos];
          zStack[nos] = zStack[tos];
          zStack[tos] = 0;
          aStack[tos].flags = 0;
        }else{
          Release(p, tos);
        }
        p->tos = nos;
        break;
      }

      /* Opcode: AddImm  P1 * *
      ** 
      ** Add the value P1 to whatever is on top of the stack.
      */
      case OP_AddImm: {
        int tos = p->tos;
        VERIFY( if( tos<0 ) goto not_enough_stack; )
        Integerify(p, tos);
        aStack[tos].i += pOp->p1;
        break;
      }

      /* Opcode: Eq * P2 *
      **
      ** Pop the top two elements from the stack.  If they are equal, then
      ** jump to instruction P2.  Otherwise, continue to the next instruction.

      case OP_Gt:
      case OP_Ge: {
        int tos = p->tos;
        int nos = tos - 1;
        int c;
        int ft, fn;
        VERIFY( if( nos<0 ) goto not_enough_stack; )
        ft = aStack[tos].flags;
        fn = aStack[nos].flags;
        if( (ft & fn)==STK_Int ){
          c = aStack[nos].i - aStack[tos].i;
        }else{
          Stringify(p, tos);
          Stringify(p, nos);
          c = sqliteCompare(zStack[nos], zStack[tos]);
        }
        switch( pOp->opcode ){
          case OP_Eq:    c = c==0;     break;
          case OP_Ne:    c = c!=0;     break;
          case OP_Lt:    c = c<0;      break;
          case OP_Le:    c = c<=0;     break;
          case OP_Gt:    c = c>0;      break;

      case OP_Like: {
        int tos = p->tos;
        int nos = tos - 1;
        int c;
        VERIFY( if( nos<0 ) goto not_enough_stack; )
        Stringify(p, tos);
        Stringify(p, nos);
        c = sqliteLikeCompare(zStack[tos], zStack[nos]);
        PopStack(p, 2);
        if( pOp->p1 ) c = !c;
        if( c ) pc = pOp->p2-1;
        break;
      }

      /* Opcode: Glob P1 P2 *

      case OP_Glob: {
        int tos = p->tos;
        int nos = tos - 1;
        int c;
        VERIFY( if( nos<0 ) goto not_enough_stack; )
        Stringify(p, tos);
        Stringify(p, nos);
        c = sqliteGlobCompare(zStack[tos], zStack[nos]);
        PopStack(p, 2);
        if( pOp->p1 ) c = !c;
        if( c ) pc = pOp->p2-1;
        break;
      }

      /* Opcode: And * * *

        int tos = p->tos;
        int nos = tos - 1;
        int c;
        VERIFY( if( nos<0 ) goto not_enough_stack; )
        Integerify(p, tos);
        Integerify(p, nos);
        if( pOp->opcode==OP_And ){
          c = aStack[tos].i && aStack[nos].i;
        }else{
          c = aStack[tos].i || aStack[nos].i;
        }
        PopStack(p, 2);
        p->tos++;
        aStack[nos].i = c;
        aStack[nos].flags = STK_Int;
        break;
      }

      /* Opcode: Negative * * *
      **
      ** Treat the top of the stack as a numeric quantity.  Replace it
      ** with its additive inverse.
      */
      case OP_Negative: {
        int tos = p->tos;
        VERIFY( if( tos<0 ) goto not_enough_stack; )
        if( aStack[tos].flags & STK_Real ){
          Release(p, tos);
          aStack[tos].r = -aStack[tos].r;
          aStack[tos].flags = STK_Real;
        }else if( aStack[tos].flags & STK_Int ){
          Release(p, tos);
          aStack[tos].i = -aStack[tos].i;
          aStack[tos].flags = STK_Int;
        }else{
          Realify(p, tos);
          Release(p, tos);
          aStack[tos].r = -aStack[tos].r;
          aStack[tos].flags = STK_Real;
        }
        break;
      }

      /* Opcode: Not * * *
      **
      ** Interpret the top of the stack as a boolean value.  Replace it
      ** with its complement.
      */
      case OP_Not: {
        int tos = p->tos;
        VERIFY( if( p->tos<0 ) goto not_enough_stack; )
        Integerify(p, tos);
        Release(p, tos);
        aStack[tos].i = !aStack[tos].i;
        aStack[tos].flags = STK_Int;
        break;
      }

      /* Opcode: Noop * * *
      **
      ** Do nothing.  This instruction is often useful as a jump
      ** destination.

      ** An integer is false if zero and true otherwise.  A string is
      ** false if it has zero length and true otherwise.
      */
      case OP_If: {
        int c;
        VERIFY( if( p->tos<0 ) goto not_enough_stack; )
        Integerify(p, p->tos);
        c = aStack[p->tos].i;
        PopStack(p, 1);
        if( c ) pc = pOp->p2-1;
        break;
      }

      /* Opcode: IsNull * P2 *
      **
      ** Pop a single value from the stack.  If the value popped is NULL
      ** then jump to p2.  Otherwise continue to the next 
      ** instruction.
      */
      case OP_IsNull: {
        int c;
        VERIFY( if( p->tos<0 ) goto not_enough_stack; )
        c = (aStack[p->tos].flags & STK_Null)!=0;
        PopStack(p, 1);
        if( c ) pc = pOp->p2-1;
        break;
      }

      /* Opcode: NotNull * P2 *
      **
      ** Pop a single value from the stack.  If the value popped is not an
      ** empty string, then jump to p2.  Otherwise continue to the next 
      ** instruction.
      */
      case OP_NotNull: {
        int c;
        VERIFY( if( p->tos<0 ) goto not_enough_stack; )
        c = (aStack[p->tos].flags & STK_Null)==0;
        PopStack(p, 1);
        if( c ) pc = pOp->p2-1;
        break;
      }

      /* Opcode: MakeRecord P1 * *
      **

        int i, j;
        int addr;

        nField = pOp->p1;
        VERIFY( if( p->tos+1<nField ) goto not_enough_stack; )
        nByte = 0;
        for(i=p->tos-nField+1; i<=p->tos; i++){
          if( (aStack[i].flags & STK_Null)==0 ){
            if( Stringify(p, i) ) goto no_mem;
            nByte += aStack[i].n;
          }
        }
        nByte += sizeof(int)*nField;
        zNewRecord = sqliteMalloc( nByte );
        if( zNewRecord==0 ) goto no_mem;
        j = 0;
        addr = sizeof(int)*nField;
        for(i=p->tos-nField+1; i<=p->tos; i++){
          if( aStack[i].flags & STK_Null ){
            int zero = 0;
            memcpy(&zNewRecord[j], (char*)&zero, sizeof(int));
          }else{
            memcpy(&zNewRecord[j], (char*)&addr, sizeof(int));
            addr += aStack[i].n;
          }
          j += sizeof(int);
        }
        for(i=p->tos-nField+1; i<=p->tos; i++){
          if( (aStack[i].flags & STK_Null)==0 ){
            memcpy(&zNewRecord[j], zStack[i], aStack[i].n);
            j += aStack[i].n;
          }
        }
        PopStack(p, nField);
        VERIFY( NeedStack(p, p->tos+1); )
        p->tos++;
        aStack[p->tos].n = nByte;
        aStack[p->tos].flags = STK_Str | STK_Dyn;
        zStack[p->tos] = zNewRecord;
        break;
      }

      /* Opcode: MakeKey P1 P2 *
      **
      ** Convert the top P1 entries of the stack into a single entry suitable
      ** for use as the key in an index or a sort.  The top P1 records are

        int nField;
        int i, j;

        nField = pOp->p1;
        VERIFY( if( p->tos+1<nField ) goto not_enough_stack; )
        nByte = 0;
        for(i=p->tos-nField+1; i<=p->tos; i++){
          if( aStack[i].flags & STK_Null ){
            nByte++;
          }else{
            if( Stringify(p, i) ) goto no_mem;
            nByte += aStack[i].n;
          }
        }
        zNewKey = sqliteMalloc( nByte );
        if( zNewKey==0 ) goto no_mem;
        j = 0;
        for(i=p->tos-nField+1; i<=p->tos; i++){
          if( (aStack[i].flags & STK_Null)==0 ){
            memcpy(&zNewKey[j], zStack[i], aStack[i].n-1);
            j += aStack[i].n-1;
          }
          if( i<p->tos ) zNewKey[j++] = '\t';
        }
        zNewKey[j] = 0;
        if( pOp->p2==0 ) PopStack(p, nField);
        VERIFY( NeedStack(p, p->tos+1); )
        p->tos++;
        aStack[p->tos].n = nByte;
        aStack[p->tos].flags = STK_Str|STK_Dyn;
        zStack[p->tos] = zNewKey;
        break;
      }

      /* Opcode: Open P1 P2 P3
      **
      ** Open a new cursor for the database file named P3.  Give the
      ** cursor an identifier P1.  The P1 values need not be

      ** in the P1 cursor until needed.
      */
      case OP_Fetch: {
        int i = pOp->p1;
        int tos = p->tos;
        VERIFY( if( tos<0 ) goto not_enough_stack; )
        if( i>=0 && i<p->nCursor && p->aCsr[i].pCursor ){
          if( aStack[tos].flags & STK_Int ){
            pBe->Fetch(p->aCsr[i].pCursor, sizeof(int), 
                           (char*)&aStack[tos].i);
          }else{
            if( Stringify(p, tos) ) goto no_mem;
            pBe->Fetch(p->aCsr[i].pCursor, aStack[tos].n, 
                           zStack[tos]);
          }
          p->nFetch++;
        }
        PopStack(p, 1);
        break;
      }

      /* Opcode: Fcnt * * *
      **
      ** Push an integer onto the stack which is the total number of
      ** OP_Fetch opcodes that have been executed by this virtual machine.
      **
      ** This instruction is used to implement the special fcnt() function
      ** in the SQL dialect that SQLite understands.  fcnt() is used for
      ** testing purposes.
      */
      case OP_Fcnt: {
        int i = ++p->tos;
        VERIFY( if( NeedStack(p, p->tos) ) goto no_mem; )
        aStack[i].i = p->nFetch;
        aStack[i].flags = STK_Int;
        break;
      }

      /* Opcode: Distinct P1 P2 *
      **
      ** Use the top of the stack as a key.  If a record with that key
      ** does not exist in file P1, then jump to P2.  If the record

      case OP_NotFound:
      case OP_Found: {
        int i = pOp->p1;
        int tos = p->tos;
        int alreadyExists = 0;
        VERIFY( if( tos<0 ) goto not_enough_stack; )
        if( VERIFY( i>=0 && i<p->nCursor && ) p->aCsr[i].pCursor ){
          if( aStack[tos].flags & STK_Int ){
            alreadyExists = pBe->Test(p->aCsr[i].pCursor, sizeof(int), 
                                          (char*)&aStack[tos].i);
          }else{
            if( Stringify(p, tos) ) goto no_mem;
            alreadyExists = pBe->Test(p->aCsr[i].pCursor,aStack[tos].n, 
                                           zStack[tos]);
          }
        }
        if( pOp->opcode==OP_Found ){
          if( alreadyExists ) pc = pOp->p2 - 1;
        }else{
          if( !alreadyExists ) pc = pOp->p2 - 1;
        }

        if( VERIFY( i<0 || i>=p->nCursor || ) p->aCsr[i].pCursor==0 ){
          v = 0;
        }else{
          v = pBe->New(p->aCsr[i].pCursor);
        }
        VERIFY( NeedStack(p, p->tos+1); )
        p->tos++;
        aStack[p->tos].i = v;
        aStack[p->tos].flags = STK_Int;
        break;
      }

      /* Opcode: Put P1 * *
      **
      ** Write an entry into the database file P1.  A new entry is
      ** created if it doesn't already exist, or the data for an existing
      ** entry is overwritten.  The data is the value on the top of the
      ** stack.  The key is the next value down on the stack.  The stack
      ** is popped twice by this instruction.
      */
      case OP_Put: {
        int tos = p->tos;
        int nos = p->tos-1;
        int i = pOp->p1;
        VERIFY( if( nos<0 ) goto not_enough_stack; )
        if( VERIFY( i>=0 && i<p->nCursor && ) p->aCsr[i].pCursor!=0 ){
          char *zKey;
          int nKey;
          if( (aStack[nos].flags & STK_Int)==0 ){
            if( Stringify(p, nos) ) goto no_mem;
            nKey = aStack[nos].n;
            zKey = zStack[nos];
          }else{
            nKey = sizeof(int);
            zKey = (char*)&aStack[nos].i;
          }
          pBe->Put(p->aCsr[i].pCursor, nKey, zKey,
                        aStack[tos].n, zStack[tos]);
        }
        PopStack(p, 2);
        break;
      }

      /* Opcode: Delete P1 * *
      **
      ** The top of the stack is a key.  Remove this key and its data
      ** from database file P1.  Then pop the stack to discard the key.
      */
      case OP_Delete: {
        int tos = p->tos;
        int i = pOp->p1;
        VERIFY( if( tos<0 ) goto not_enough_stack; )
        if( VERIFY( i>=0 && i<p->nCursor && ) p->aCsr[i].pCursor!=0 ){
          char *zKey;
          int nKey;
          if( aStack[tos].flags & STK_Int ){
            nKey = sizeof(int);
            zKey = (char*)&aStack[tos].i;
          }else{
            if( Stringify(p, tos) ) goto no_mem;
            nKey = aStack[tos].n;
            zKey = zStack[tos];
          }
          pBe->Delete(p->aCsr[i].pCursor, nKey, zKey);
        }
        PopStack(p, 1);
        break;
      }

        char *z;

        VERIFY( if( NeedStack(p, tos) ) goto no_mem; )
        if( VERIFY( i>=0 && i<p->nCursor && ) (pCrsr = p->aCsr[i].pCursor)!=0 ){
          if( p->aCsr[i].keyAsData ){
            amt = pBe->KeyLength(pCrsr);
            if( amt<=sizeof(int)*(p2+1) ){
              aStack[tos].flags = STK_Null;
              break;
            }
            pAddr = (int*)pBe->ReadKey(pCrsr, sizeof(int)*p2);
            if( *pAddr==0 ){
              aStack[tos].flags = STK_Null;
              break;
            }
            z = pBe->ReadKey(pCrsr, *pAddr);
          }else{
            amt = pBe->DataLength(pCrsr);
            if( amt<=sizeof(int)*(p2+1) ){
              aStack[tos].flags = STK_Null;
              break;
            }
            pAddr = (int*)pBe->ReadData(pCrsr, sizeof(int)*p2);
            if( *pAddr==0 ){
              aStack[tos].flags = STK_Null;
              break;
            }
            z = pBe->ReadData(pCrsr, *pAddr);
          }
          zStack[tos] = z;
          aStack[tos].n = strlen(z) + 1;
          aStack[tos].flags = STK_Str;
        }
        break;
      }

      /* Opcode: Key P1 * *
      **
      ** Push onto the stack an integer which is the first 4 bytes of the
      ** the key to the current entry in a sequential scan of the database
      ** file P1.  The sequential scan should have been started using the 
      ** Next opcode.
      */
      case OP_Key: {
        int i = pOp->p1;
        int tos = ++p->tos;
        DbbeCursor *pCrsr;

        VERIFY( if( NeedStack(p, p->tos) ) goto no_mem; )
        if( VERIFY( i>=0 && i<p->nCursor && ) (pCrsr = p->aCsr[i].pCursor)!=0 ){
          char *z = pBe->ReadKey(pCrsr, 0);
          if( p->aCsr[i].keyAsData ){
            zStack[tos] = z;
            aStack[tos].flags = STK_Str;
            aStack[tos].n = pBe->KeyLength(pCrsr);
          }else{
            memcpy(&aStack[tos].i, z, sizeof(int));
            aStack[tos].flags = STK_Int;
          }
        }
        break;
      }

      /* Opcode: Rewind P1 * *
      **

      */
      case OP_NextIdx: {
        int i = pOp->p1;
        int tos = ++p->tos;
        DbbeCursor *pCrsr;

        VERIFY( if( NeedStack(p, p->tos) ) goto no_mem; )
        zStack[tos] = 0;
        if( VERIFY( i>=0 && i<p->nCursor && ) (pCrsr = p->aCsr[i].pCursor)!=0 ){
          int *aIdx;
          int nIdx;
          int j, k;
          nIdx = pBe->DataLength(pCrsr)/sizeof(int);
          aIdx = (int*)pBe->ReadData(pCrsr, 0);
          if( nIdx>1 ){
            k = *(aIdx++);
            if( k>nIdx-1 ) k = nIdx-1;
          }else{
            k = nIdx;
          }
          for(j=p->aCsr[i].index; j<k; j++){
            if( aIdx[j]!=0 ){
              aStack[tos].i = aIdx[j];
              aStack[tos].flags = STK_Int;
              break;
            }
          }
          if( j>=k ){
            j = -1;
            pc = pOp->p2 - 1;
            PopStack(p, 1);

        int nos = tos - 1;
        DbbeCursor *pCrsr;
        VERIFY( if( nos<0 ) goto not_enough_stack; )
        if( VERIFY( i>=0 && i<p->nCursor && ) (pCrsr = p->aCsr[i].pCursor)!=0 ){
          int r;
          int newVal;
          Integerify(p, nos);
          newVal = aStack[nos].i;
          if( Stringify(p, tos) ) goto no_mem;
          r = pBe->Fetch(pCrsr, aStack[tos].n, zStack[tos]);
          if( r==0 ){
            /* Create a new record for this index */
            pBe->Put(pCrsr, aStack[tos].n, zStack[tos],
                          sizeof(int), (char*)&newVal);
          }else{
            /* Extend the existing record */
            int nIdx;
            int *aIdx;
            int k;
            
            nIdx = pBe->DataLength(pCrsr)/sizeof(int);
            if( nIdx==1 ){
              aIdx = sqliteMalloc( sizeof(int)*4 );
              if( aIdx==0 ) goto no_mem;
              aIdx[0] = 2;
              pBe->CopyData(pCrsr, 0, sizeof(int), (char*)&aIdx[1]);
              aIdx[2] = newVal;
              pBe->Put(pCrsr, aStack[tos].n, zStack[tos],
                    sizeof(int)*4, (char*)aIdx);
              sqliteFree(aIdx);
            }else{
              aIdx = (int*)pBe->ReadData(pCrsr, 0);
              k = aIdx[0];
              if( k<nIdx-1 ){
                aIdx[k+1] = newVal;
                aIdx[0]++;
                pBe->Put(pCrsr, aStack[tos].n, zStack[tos],
                    sizeof(int)*nIdx, (char*)aIdx);
              }else{
                nIdx *= 2;
                aIdx = sqliteMalloc( sizeof(int)*nIdx );
                if( aIdx==0 ) goto no_mem;
                pBe->CopyData(pCrsr, 0, sizeof(int)*(k+1), (char*)aIdx);
                aIdx[k+1] = newVal;
                aIdx[0]++;
                pBe->Put(pCrsr, aStack[tos].n, zStack[tos],
                      sizeof(int)*nIdx, (char*)aIdx);
                sqliteFree(aIdx);
              }
            }              
          }
        }
        PopStack(p, 2);

        if( VERIFY( i>=0 && i<p->nCursor && ) (pCrsr = p->aCsr[i].pCursor)!=0 ){
          int *aIdx;
          int nIdx;
          int j, k;
          int r;
          int oldVal;
          Integerify(p, nos);
          oldVal = aStack[nos].i;
          if( Stringify(p, tos) ) goto no_mem;
          r = pBe->Fetch(pCrsr, aStack[tos].n, zStack[tos]);
          if( r==0 ) break;
          nIdx = pBe->DataLength(pCrsr)/sizeof(int);
          aIdx = (int*)pBe->ReadData(pCrsr, 0);
          if( (nIdx==1 && aIdx[0]==oldVal) || (aIdx[0]==1 && aIdx[1]==oldVal) ){
            pBe->Delete(pCrsr, aStack[tos].n, zStack[tos]);
          }else{
            k = aIdx[0];
            for(j=1; j<=k && aIdx[j]!=oldVal; j++){}
            if( j>k ) break;
            aIdx[j] = aIdx[k];
            aIdx[k] = 0;
            aIdx[0]--;
            if( aIdx[0]*3 + 1 < nIdx ){
              nIdx /= 2;
            }
            pBe->Put(pCrsr, aStack[tos].n, zStack[tos], 
                          sizeof(int)*nIdx, (char*)aIdx);
          }
        }
        PopStack(p, 2);
        break;
      }

      case OP_ListWrite: {
        int i = pOp->p1;
        VERIFY( if( i<0 ) goto bad_instruction; )
        VERIFY( if( p->tos<0 ) goto not_enough_stack; )
        if( VERIFY( i<p->nList && ) p->apList[i]!=0 ){
          int val;
          Integerify(p, p->tos);
          val = aStack[p->tos].i;
          PopStack(p, 1);
          fwrite(&val, sizeof(int), 1, p->apList[i]);
        }
        break;
      }

      /* Opcode: ListRewind P1 * *

        int i = pOp->p1;
        int val, amt;
        VERIFY(if( i<0 || i>=p->nList || p->apList[i]==0 )goto bad_instruction;)
        amt = fread(&val, sizeof(int), 1, p->apList[i]);
        if( amt==1 ){
          p->tos++;
          if( NeedStack(p, p->tos) ) goto no_mem;
          aStack[p->tos].i = val;
          aStack[p->tos].flags = STK_Int;
          zStack[p->tos] = 0;
        }else{
          pc = pOp->p2 - 1;
        }
        break;
      }

      /* Opcode: ListClose P1 * *

        VERIFY( if( i<0 || i>=p->nSort ) goto bad_instruction; )
        VERIFY( if( tos<1 ) goto not_enough_stack; )
        if( Stringify(p, tos) || Stringify(p, nos) ) goto no_mem;
        pSorter = sqliteMalloc( sizeof(Sorter) );
        if( pSorter==0 ) goto no_mem;
        pSorter->pNext = p->apSort[i];
        p->apSort[i] = pSorter;
        pSorter->nKey = aStack[tos].n;
        pSorter->zKey = zStack[tos];
        pSorter->nData = aStack[nos].n;
        pSorter->pData = zStack[nos];
        aStack[tos].flags = 0;
        aStack[nos].flags = 0;
        zStack[tos] = 0;
        zStack[nos] = 0;
        p->tos -= 2;
        break;
      }

      /* Opcode: SortMakeRec P1 * *
      **
      ** The top P1 elements are the arguments to a callback.  Form these

        int nField;
        int i, j;

        nField = pOp->p1;
        VERIFY( if( p->tos+1<nField ) goto not_enough_stack; )
        nByte = 0;
        for(i=p->tos-nField+1; i<=p->tos; i++){
          if( (aStack[i].flags & STK_Null)==0 ){
            if( Stringify(p, i) ) goto no_mem;
            nByte += aStack[i].n;
          }
        }
        nByte += sizeof(char*)*(nField+1);
        azArg = sqliteMalloc( nByte );
        if( azArg==0 ) goto no_mem;
        z = (char*)&azArg[nField+1];
        for(j=0, i=p->tos-nField+1; i<=p->tos; i++, j++){
          if( aStack[i].flags & STK_Null ){
            azArg[j] = 0;
          }else{
            azArg[j] = z;
            strcpy(z, zStack[i]);
            z += aStack[i].n;
          }
        }
        PopStack(p, nField);
        VERIFY( NeedStack(p, p->tos+1); )
        p->tos++;
        aStack[p->tos].n = nByte;
        zStack[p->tos] = (char*)azArg;
        aStack[p->tos].flags = STK_Str|STK_Dyn;
        break;
      }

      /* Opcode: SortMakeKey P1 * P3
      **
      ** Convert the top few entries of the stack into a sort key.  The
      ** number of stack entries consumed is the number of characters in 

        int i, j, k;

        nField = strlen(pOp->p3);
        VERIFY( if( p->tos+1<nField ) goto not_enough_stack; )
        nByte = 1;
        for(i=p->tos-nField+1; i<=p->tos; i++){
          if( Stringify(p, i) ) goto no_mem;
          nByte += aStack[i].n+2;
        }
        zNewKey = sqliteMalloc( nByte );
        if( zNewKey==0 ) goto no_mem;
        j = 0;
        k = 0;
        for(i=p->tos-nField+1; i<=p->tos; i++){
          zNewKey[j++] = pOp->p3[k++];
          memcpy(&zNewKey[j], zStack[i], aStack[i].n-1);
          j += aStack[i].n-1;
          zNewKey[j++] = 0;
        }
        zNewKey[j] = 0;
        PopStack(p, nField);
        VERIFY( NeedStack(p, p->tos+1); )
        p->tos++;
        aStack[p->tos].n = nByte;
        aStack[p->tos].flags = STK_Str|STK_Dyn;
        zStack[p->tos] = zNewKey;
        break;
      }

      /* Opcode: Sort P1 * *
      **
      ** Sort all elements on the given sorter.  The algorithm is a
      ** mergesort.

        int i = pOp->p1;
        VERIFY( if( i<0 ) goto bad_instruction; )
        if( VERIFY( i<p->nSort && ) p->apSort[i]!=0 ){
          Sorter *pSorter = p->apSort[i];
          p->apSort[i] = pSorter->pNext;
          p->tos++;
          VERIFY( NeedStack(p, p->tos); )
          zStack[p->tos] = pSorter->pData;
          aStack[p->tos].n = pSorter->nData;
          aStack[p->tos].flags = STK_Str|STK_Dyn;
          sqliteFree(pSorter->zKey);
          sqliteFree(pSorter);
        }else{
          pc = pOp->p2 - 1;
        }
        break;
      }

      /* Opcode: SortKey P1 * *
      **
      ** Push the key for the topmost element of the sorter onto the stack.
      ** But don't change the sorter an any other way.
      */
      case OP_SortKey: {
        int i = pOp->p1;
        VERIFY( if( i<0 ) goto bad_instruction; )
        if( i<p->nSort && p->apSort[i]!=0 ){
          Sorter *pSorter = p->apSort[i];
          p->tos++;
          VERIFY( NeedStack(p, p->tos); )
          sqliteSetString(&zStack[p->tos], pSorter->zKey, 0);
          aStack[p->tos].n = pSorter->nKey;
          aStack[p->tos].flags = STK_Str|STK_Dyn;
        }
        break;
      }

      /* Opcode: SortCallback P1 P2 *
      **
      ** The top of the stack contains a callback record built using
      ** the SortMakeRec operation with the same P1 value as this
      ** instruction.  Pop this record from the stack and invoke the
      ** callback on it.
      */
      case OP_SortCallback: {
        int i = p->tos;
        VERIFY( if( i<0 ) goto not_enough_stack; )
        if( xCallback!=0 ){
          if( xCallback(pArg, pOp->p1, (char**)zStack[i], p->azColName) ){
            rc = SQLITE_ABORT;
          }
        }
        PopStack(p, 1);
        break;
      }

        if( VERIFY( i>=0 && i<p->nField && ) p->azField ){
          z = p->azField[i];
        }else{
          z = 0;
        }
        if( z==0 ) z = "";
        p->tos++;
        aStack[p->tos].n = strlen(z) + 1;
        zStack[p->tos] = z;
        aStack[p->tos].flags = STK_Str;
        break;
      }

      /* Opcode: MemStore P1 * *
      **
      ** Pop a single value of the stack and store that value into memory
      ** location P1.  P1 should be a small integer since space is allocated

        }
        pMem = &p->aMem[i];
        if( pMem->s.flags & STK_Dyn ){
          zOld = pMem->z;
        }else{
          zOld = 0;
        }
        pMem->s = aStack[tos];
        if( pMem->s.flags & STK_Str ){
          pMem->z = sqliteStrNDup(zStack[tos], pMem->s.n);
          pMem->s.flags |= STK_Dyn;
        }
        if( zOld ) sqliteFree(zOld);
        PopStack(p, 1);
        break;
      }

      /* Opcode: MemLoad P1 * *
      **
      ** Push a copy of the value in memory location P1 onto the stack.
      */
      case OP_MemLoad: {
        int tos = ++p->tos;
        int i = pOp->p1;
        VERIFY( if( NeedStack(p, tos) ) goto no_mem; )
        if( i<0 || i>=p->nMem ){
          aStack[tos].flags = STK_Null;
          zStack[tos] = 0;
        }else{
          aStack[tos] = p->aMem[i].s;
          if( aStack[tos].flags & STK_Str ){
            char *z = sqliteMalloc(aStack[tos].n);
            if( z==0 ) goto no_mem;
            memcpy(z, p->aMem[i].z, aStack[tos].n);
            zStack[tos] = z;
            aStack[tos].flags |= STK_Dyn;
          }
        }
        break;
      }

      /* Opcode: AggReset * P2 *
      **

        int tos = p->tos;
        AggElem *pElem;
        char *zKey;
        int nKey;

        VERIFY( if( tos<0 ) goto not_enough_stack; )
        Stringify(p, tos);
        zKey = zStack[tos]; 
        nKey = aStack[tos].n;
        if( p->agg.nHash<=0 ){
          pElem = 0;
        }else{
          int h = sqliteHashNoCase(zKey, nKey-1) % p->agg.nHash;
          for(pElem=p->agg.apHash[h]; pElem; pElem=pElem->pHash){
            if( strcmp(pElem->zKey, zKey)==0 ) break;
          }

          Mem *pMem = &pFocus->aMem[i];
          char *zOld;
          if( pMem->s.flags & STK_Dyn ){
            zOld = pMem->z;
          }else{
            zOld = 0;
          }
          pMem->s = aStack[tos];
          if( pMem->s.flags & STK_Str ){
            pMem->z = sqliteMalloc( aStack[tos].n );
            if( pMem->z==0 ) goto no_mem;
            memcpy(pMem->z, zStack[tos], pMem->s.n);
            pMem->s.flags |= STK_Str|STK_Dyn;
          }
          if( zOld ) sqliteFree(zOld);
        }
        PopStack(p, 1);
        break;
      }

        AggElem *pFocus = AggInFocus(p->agg);
        int i = pOp->p2;
        int tos = ++p->tos;
        VERIFY( if( NeedStack(p, tos) ) goto no_mem; )
        if( pFocus==0 ) goto no_mem;
        if( VERIFY( i>=0 && ) i<p->agg.nMem ){
          Mem *pMem = &pFocus->aMem[i];
          aStack[tos] = pMem->s;
          zStack[tos] = pMem->z;
          aStack[tos].flags &= ~STK_Dyn;
        }
        break;
      }

      /* Opcode: AggNext * P2 *
      **
      ** Make the next aggregate value the current aggregate.  The prior

        }
        if( pOp->p3 ){
          SetInsert(&p->aSet[i], pOp->p3);
        }else{
          int tos = p->tos;
          if( tos<0 ) goto not_enough_stack;
          Stringify(p, tos);
          SetInsert(&p->aSet[i], zStack[tos]);
          PopStack(p, 1);
        }
        break;
      }

      /* Opcode: SetFound P1 P2 *
      **
      ** Pop the stack once and compare the value popped off with the
      ** contents of set P1.  If the element popped exists in set P1,
      ** then jump to P2.  Otherwise fall through.
      */
      case OP_SetFound: {
        int i = pOp->p1;
        int tos = p->tos;
        VERIFY( if( tos<0 ) goto not_enough_stack; )
        Stringify(p, tos);
        if( VERIFY( i>=0 && i<p->nSet &&) SetTest(&p->aSet[i], zStack[tos])){
          pc = pOp->p2 - 1;
        }
        PopStack(p, 1);
        break;
      }

      /* Opcode: SetNotFound P1 P2 *
      **
      ** Pop the stack once and compare the value popped off with the
      ** contents of set P1.  If the element popped does not exists in 
      ** set P1, then jump to P2.  Otherwise fall through.
      */
      case OP_SetNotFound: {
        int i = pOp->p1;
        int tos = p->tos;
        VERIFY( if( tos<0 ) goto not_enough_stack; )
        Stringify(p, tos);
        if(VERIFY( i>=0 && i<p->nSet &&) !SetTest(&p->aSet[i], zStack[tos])){
          pc = pOp->p2 - 1;
        }
        PopStack(p, 1);
        break;
      }

      /* Opcode: Length * * *
      **
      ** Interpret the top of the stack as a string.  Replace the top of
      ** stack with an integer which is the length of the string.
      */
      case OP_Strlen: {
        int tos = p->tos;
        int len;
        VERIFY( if( tos<0 ) goto not_enough_stack; )
        Stringify(p, tos);
        len = aStack[tos].n-1;
        PopStack(p, 1);
        p->tos++;
        aStack[tos].i = len;
        aStack[tos].flags = STK_Int;
        break;
      }

      /* Opcode: Substr P1 P2 *
      **
      ** This operation pops between 1 and 3 elements from the stack and
      ** pushes back a single element.  The bottom-most element popped from

        int start;
        int n;
        char *z;

        if( pOp->p2==0 ){
          VERIFY( if( p->tos<0 ) goto not_enough_stack; )
          Integerify(p, p->tos);
          cnt = aStack[p->tos].i;
          PopStack(p, 1);
        }else{
          cnt = pOp->p2;
        }
        if( pOp->p1==0 ){
          VERIFY( if( p->tos<0 ) goto not_enough_stack; )
          Integerify(p, p->tos);
          start = aStack[p->tos].i - 1;
          PopStack(p, 1);
        }else{
          start = pOp->p1 - 1;
        }
        VERIFY( if( p->tos<0 ) goto not_enough_stack; )
        Stringify(p, p->tos);
        n = aStack[p->tos].n - 1;
        if( start<0 ){
          start += n + 1;
          if( start<0 ){
            cnt += start;
            start = 0;
          }
        }
        if( start>n ){
          start = n;
        }
        if( cnt<0 ) cnt = 0;
        if( cnt > n ){
          cnt = n;
        }
        z = sqliteMalloc( cnt+1 );
        if( z==0 ) goto no_mem;
        strncpy(z, &zStack[p->tos][start], cnt);
        z[cnt] = 0;
        PopStack(p, 1);
        p->tos++;
        zStack[p->tos] = z;
        aStack[p->tos].n = cnt + 1;
        aStack[p->tos].flags = STK_Str|STK_Dyn;
        break;
      }

      /* An other opcode is illegal...
      */
      default: {
        sprintf(zBuf,"%d",pOp->opcode);

      sqliteSetString(pzErrMsg, "jump destination out of range", 0);
      rc = SQLITE_INTERNAL;
    }
    if( p->trace && p->tos>=0 ){
      int i;
      fprintf(p->trace, "Stack:");
      for(i=p->tos; i>=0 && i>p->tos-5; i--){
        if( aStack[i].flags & STK_Null ){
          fprintf(p->trace, " NULL");
        }else if( aStack[i].flags & STK_Int ){
          fprintf(p->trace, " i:%d", aStack[i].i);
        }else if( aStack[i].flags & STK_Real ){
          fprintf(p->trace, " r:%g", aStack[i].r);
        }else if( aStack[i].flags & STK_Str ){
          if( aStack[i].flags & STK_Dyn ){
            fprintf(p->trace, " z:[%.11s]", zStack[i]);
          }else{
            fprintf(p->trace, " s:[%.11s]", zStack[i]);
          }
        }else{
          fprintf(p->trace, " ???");
        }
      }
      fprintf(p->trace,"\n");
    }

#
# Run this Tcl script to generate the sqlite.html file.
#
set rcsid {$Id: c_interface.tcl,v 1.12 2000/10/23 13:16:33 drh Exp $}

puts {<html>
<head>
  <title>The C language interface to the SQLite library</title>
</head>
<body bgcolor=white>
<h1 align=center>

<p>The interface to the SQLite library consists of three core functions,
one opaque data structure, and some constants used as return values.
The core interface is as follows:</p>

<blockquote><pre>
typedef struct sqlite sqlite;

sqlite *sqlite_open(const char *dbname, int mode, char **errmsg);

void sqlite_close(sqlite*);

int sqlite_exec(
  sqlite*,
  char *sql,
  int (*)(void*,int,char**,char**),

database read only.  The third argument is a pointer to a string
pointer.  If the third argument is not NULL and an error occurs
while trying to open the database, then an error message will be
written to memory obtained from malloc() and *errmsg will be made
to point to this error message.  The calling function is responsible
for freeing the memory when it has finished with it.</p>

<p>The name of an SQLite database is normally the name of a directory
that contains a collection of GDBM files that comprise the database.
There is one GDBM file for each table and index in the
database.  All GDBM files end with the ".tbl" suffix.  Every SQLite
database also contains a special database table named <b>sqlite_master</b>
stored in its own GDBM file.  This special table records the database
schema.</p>

<p>To create a new SQLite database, all you have to do is call
<b>sqlite_open()</b> with the first parameter set to the name of
an empty directory and the second parameter set to 0666.  The
directory is created automatically if it does not already exist.</p>

<p>Beginning with SQLite version 1.0.14, SQLite supports database
backends other than GDBM.  The only backends currently supported 
are the default GDBM driver and an in-memory hash table database.
You may anticipate additional backends in future versions of SQLite.</p>

<p>An alternative database backend is specified by prepending the
backend name and a colon to the database name argument of the
<b>sqlite_open()</b> function.  For the GDBM backend, you can
prepend "<b>gdbm:</b>" to the directory name.  To select the in-memory
hash table backend, prepend "<b>memory:</b>" to the database name.
Future database drivers will be selected by a similar mechanism.</p>

<p>The return value of the <b>sqlite_open()</b> function is a
pointer to an opaque <b>sqlite</b> structure.  This pointer will
be the first argument to all subsequent SQLite function calls that
deal with the same database.  NULL is returned if the open fails
for any reason.</p>

}


proc chng {date desc} {
  puts "<DT><B>$date</B></DT>"
  puts "<DD><P><UL>$desc</UL></P></DD>"
}

chng {2000 Oct 23 (1.0.15)} {
<li>Documentation updates</li>
<li>Some sanity checking code was removed from the inner loop of vdbe.c
    to help the library to run a little faster.  The code is only
    removed if you compile with -DNDEBUG.</li>
}

chng {2000 Oct 19 (1.0.14)} {
<li>Added a "memory:" backend driver that stores its database in an
    in-memory hash table.</li>
}

chng {2000 Oct 18 (1.0.13)} {

#
# Run this Tcl script to generate the tclsqlite.html file.
#
set rcsid {$Id: tclsqlite.tcl,v 1.3 2000/10/23 13:16:33 drh Exp $}

puts {<html>
<head>
  <title>The Tcl interface to the SQLite library</title>
</head>
<body bgcolor=white>
<h1 align=center>

tcl command named <b>sqlite</b>.  Because there is only this
one interface command, the interface is not placed in a separate
namespace.</p>

<p>The <b>sqlite</b> command is used as follows:</p>

<blockquote>
<b>sqlite</b>&nbsp;&nbsp;<i>dbcmd&nbsp;&nbsp;database-name</i>
</blockquote>

<p>
The <b>sqlite</b> command opens the database named in the second
argument.  If the database does not already exist, it is
automatically created.
The <b>sqlite</b> command also creates a new Tcl
command to control the database.  The name of the new Tcl command
is given by the first argument.  This approach is similar to the
way widgets are created in Tk.
</p>

<p>
The name of the database is usually either the name of a directory
that will contain the GDBM files that comprise the database, or it is the
name of the directory prefaced by "<b>gdbm:</b>".  The second form
of the name is a new feature beginning in SQLite version 1.0.14 that
allows you to select alternative database backends.  The default
backend is GDBM.  But you can also select to store the database in
a hash table in memory by using the prefix "<b>memory:</b>". 
Other backends may be added in the future.
</p>

<p>
Every time you open an SQLite database with the <b>memory:</b> prefix
on the database name, you get a new in-memory database.  This is true
even if you open two databases with the same name.  Furthermore,
an in-memory database is automatically deleted when the database is
closed and so is not useful for persistant storage like a normal
database.  But the use of an in-memory SQL database does give Tcl/Tk
a powerful new data storage mechanism that can do things that are
difficult to do with only Tcl array variables.  In fact, the
hash-table backend for SQLite was created for the sole purpose of
providing better data structure support to the Tcl language.
</p>

<p>
Once an SQLite database is open, it can be controlled using 
methods of the <i>dbcmd</i>.  There are currently 5 methods
defined:</p>

<p>
<ul>

<h2>The "timeout" method</h2>

<p>The "timeout" method is used to control how long the SQLite library
will wait for locks to clear before giving up on a database transaction.
The default timeout is 0 millisecond.  (In other words, the default behavior
is not to wait at all.)</p>

<p>The GDBM backend allows multiple simultaneous
readers or a single writer but not both.  If any process is writing to
the database no other process is allows to read or write.  If any process
is reading the database other processes are allowed to read but not write.
Each GDBM file is locked separately.  Because each SQL table is stored as
a separate file, it is possible for different processes to write to different
database tables at the same time, just not the same table.</p>