/ Check-in [aa8eba33]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Update the amalgamation builder to incorporate the RTREE extension. (CVS 5160)
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: aa8eba3360c31182f5238e96b83a382374f40fab
User & Date: drh 2008-05-26 20:19:25
Context
2008-05-26
20:49
Use %w instead of %q when constructing shadow table names for rtree. (CVS 5161) check-in: 78f4ba97 user: drh tags: trunk
20:19
Update the amalgamation builder to incorporate the RTREE extension. (CVS 5160) check-in: aa8eba33 user: drh tags: trunk
18:41
Import 'rtree' extension. (CVS 5159) check-in: b104dcd6 user: danielk1977 tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to ext/rtree/README.

    76     76           the required type (64-bit integer or 32-bit real) as if they
    77     77           were part of an SQL CAST expression. Non-numeric strings are
    78     78           converted to zero.
    79     79   
    80     80     1.3 Queries.
    81     81   
    82     82       R-tree tables may be queried using all of the same SQL syntax supported
    83         -    by regular tables. However, some query patterns are more efficient faster
           83  +    by regular tables. However, some query patterns are more efficient
    84     84       than others.
    85     85   
    86     86       R-trees support fast lookup by primary key value (O(logN), like 
    87     87       regular tables).
    88     88   
    89     89       Any combination of equality and range (<, <=, >, >=) constraints
    90     90       on spatial data columns may be used to optimize other queries. This
................................................................................
    94     94     1.4 Introspection and Analysis.
    95     95   
    96     96       TODO: Describe rtreenode() and rtreedepth() functions.
    97     97   
    98     98   
    99     99   2. COMPILATION AND USAGE
   100    100   
   101         -  The easiest way to compile and use the ICU extension is to build
          101  +  The easiest way to compile and use the RTREE extension is to build
   102    102     and use it as a dynamically loadable SQLite extension. To do this
   103    103     using gcc on *nix:
   104    104   
   105    105       gcc -shared rtree.c -o libSqliteRtree.so
   106    106   
   107    107     You may need to add "-I" flags so that gcc can find sqlite3ext.h
   108         -  and sqlite3.h. The resulting shared lib, libSqliteIcu.so, may be
          108  +  and sqlite3.h. The resulting shared lib, libSqliteRtree.so, may be
   109    109     loaded into sqlite in the same way as any other dynamicly loadable
   110    110     extension.
   111    111   
   112    112   
   113    113   3. REFERENCES
   114    114   
   115    115     [1]  Atonin Guttman, "R-trees - A Dynamic Index Structure For Spatial 
   116    116          Searching", University of California Berkeley, 1984.
   117    117   
   118    118     [2]  Norbert Beckmann, Hans-Peter Kriegel, Ralf Schneider, Bernhard Seeger,
   119    119          "The R*-tree: An Efficient and Robust Access Method for Points and
   120    120          Rectangles", Universitaet Bremen, 1990.
   121         -
   122         -
   123         -

Changes to ext/rtree/rtree.c.

     8      8   **    May you find forgiveness for yourself and forgive others.
     9      9   **    May you share freely, never taking more than you give.
    10     10   **
    11     11   *************************************************************************
    12     12   ** This file contains code for implementations of the r-tree and r*-tree
    13     13   ** algorithms packaged as an SQLite virtual table module.
    14     14   **
    15         -** $Id: rtree.c,v 1.1 2008/05/26 18:41:54 danielk1977 Exp $
           15  +** $Id: rtree.c,v 1.2 2008/05/26 20:19:25 drh Exp $
    16     16   */
    17     17   
    18     18   #if !defined(SQLITE_CORE) || defined(SQLITE_ENABLE_RTREE)
    19     19   
    20     20   /*
    21     21   ** This file contains an implementation of a couple of different variants
    22     22   ** of the r-tree algorithm. See the README file for further details. The 
................................................................................
    62     62   #else
    63     63     #include "sqlite3.h"
    64     64   #endif
    65     65   
    66     66   #include <string.h>
    67     67   #include <assert.h>
    68     68   
    69         -typedef sqlite3_int64 i64;
    70         -typedef unsigned char u8;
    71         -typedef unsigned int u32;
           69  +#ifndef SQLITE_CORE
           70  +  typedef sqlite3_int64 i64;
           71  +  typedef unsigned char u8;
           72  +  typedef unsigned int u32;
           73  +#endif
    72     74   
    73     75   typedef struct Rtree Rtree;
    74     76   typedef struct RtreeCursor RtreeCursor;
    75     77   typedef struct RtreeNode RtreeNode;
    76     78   typedef struct RtreeCell RtreeCell;
    77     79   typedef struct RtreeConstraint RtreeConstraint;
    78     80   
................................................................................
  1352   1354   static int parentWrite(Rtree *pRtree, sqlite3_int64 iNode, sqlite3_int64 iPar){
  1353   1355     sqlite3_bind_int64(pRtree->pWriteParent, 1, iNode);
  1354   1356     sqlite3_bind_int64(pRtree->pWriteParent, 2, iPar);
  1355   1357     sqlite3_step(pRtree->pWriteParent);
  1356   1358     return sqlite3_reset(pRtree->pWriteParent);
  1357   1359   }
  1358   1360   
  1359         -static int insertCell(Rtree *, RtreeNode *, RtreeCell *, int);
         1361  +static int rtreeInsertCell(Rtree *, RtreeNode *, RtreeCell *, int);
  1360   1362   
  1361   1363   #if VARIANT_GUTTMAN_LINEAR_SPLIT
  1362   1364   /*
  1363   1365   ** Implementation of the linear variant of the PickNext() function from
  1364   1366   ** Guttman[84].
  1365   1367   */
  1366   1368   static RtreeCell *LinearPickNext(
................................................................................
  1890   1892       goto splitnode_out;
  1891   1893     }
  1892   1894   
  1893   1895     rightbbox.iRowid = pRight->iNode;
  1894   1896     leftbbox.iRowid = pLeft->iNode;
  1895   1897   
  1896   1898     if( pNode->iNode==1 ){
  1897         -    rc = insertCell(pRtree, pLeft->pParent, &leftbbox, iHeight+1);
         1899  +    rc = rtreeInsertCell(pRtree, pLeft->pParent, &leftbbox, iHeight+1);
  1898   1900       if( rc!=SQLITE_OK ){
  1899   1901         goto splitnode_out;
  1900   1902       }
  1901   1903     }else{
  1902   1904       RtreeNode *pParent = pLeft->pParent;
  1903   1905       int iCell = nodeParentIndex(pRtree, pLeft);
  1904   1906       nodeOverwriteCell(pRtree, pParent, &leftbbox, iCell);
  1905   1907       AdjustTree(pRtree, pParent, &leftbbox);
  1906   1908     }
  1907         -  if( (rc = insertCell(pRtree, pRight->pParent, &rightbbox, iHeight+1)) ){
         1909  +  if( (rc = rtreeInsertCell(pRtree, pRight->pParent, &rightbbox, iHeight+1)) ){
  1908   1910       goto splitnode_out;
  1909   1911     }
  1910   1912   
  1911   1913     for(i=0; i<NCELL(pRight); i++){
  1912   1914       i64 iRowid = nodeGetRowid(pRtree, pRight, i);
  1913   1915       rc = updateMapping(pRtree, iRowid, pRight, iHeight);
  1914   1916       if( iRowid==pCell->iRowid ){
................................................................................
  2145   2147       ** the height of the sub-tree headed by the cell.
  2146   2148       */
  2147   2149       RtreeNode *pInsert;
  2148   2150       RtreeCell *p = &aCell[aOrder[ii]];
  2149   2151       rc = ChooseLeaf(pRtree, p, iHeight, &pInsert);
  2150   2152       if( rc==SQLITE_OK ){
  2151   2153         int rc2;
  2152         -      rc = insertCell(pRtree, pInsert, p, iHeight);
         2154  +      rc = rtreeInsertCell(pRtree, pInsert, p, iHeight);
  2153   2155         rc2 = nodeRelease(pRtree, pInsert);
  2154   2156         if( rc==SQLITE_OK ){
  2155   2157           rc = rc2;
  2156   2158         }
  2157   2159       }
  2158   2160     }
  2159   2161   
................................................................................
  2161   2163     return rc;
  2162   2164   }
  2163   2165   
  2164   2166   /*
  2165   2167   ** Insert cell pCell into node pNode. Node pNode is the head of a 
  2166   2168   ** subtree iHeight high (leaf nodes have iHeight==0).
  2167   2169   */
  2168         -static int insertCell(
         2170  +static int rtreeInsertCell(
  2169   2171     Rtree *pRtree,
  2170   2172     RtreeNode *pNode,
  2171   2173     RtreeCell *pCell,
  2172   2174     int iHeight
  2173   2175   ){
  2174   2176     int rc = SQLITE_OK;
  2175   2177     if( iHeight>0 ){
................................................................................
  2214   2216   
  2215   2217       /* Find a node to store this cell in. pNode->iNode currently contains
  2216   2218       ** the height of the sub-tree headed by the cell.
  2217   2219       */
  2218   2220       rc = ChooseLeaf(pRtree, &cell, pNode->iNode, &pInsert);
  2219   2221       if( rc==SQLITE_OK ){
  2220   2222         int rc2;
  2221         -      rc = insertCell(pRtree, pInsert, &cell, pNode->iNode);
         2223  +      rc = rtreeInsertCell(pRtree, pInsert, &cell, pNode->iNode);
  2222   2224         rc2 = nodeRelease(pRtree, pInsert);
  2223   2225         if( rc==SQLITE_OK ){
  2224   2226           rc = rc2;
  2225   2227         }
  2226   2228       }
  2227   2229     }
  2228   2230     return rc;
................................................................................
  2385   2387   
  2386   2388       if( rc==SQLITE_OK ){
  2387   2389         rc = ChooseLeaf(pRtree, &cell, 0, &pLeaf);
  2388   2390       }
  2389   2391       if( rc==SQLITE_OK ){
  2390   2392         int rc2;
  2391   2393         pRtree->iReinsertHeight = -1;
  2392         -      rc = insertCell(pRtree, pLeaf, &cell, 0);
         2394  +      rc = rtreeInsertCell(pRtree, pLeaf, &cell, 0);
  2393   2395         rc2 = nodeRelease(pRtree, pLeaf);
  2394   2396         if( rc==SQLITE_OK ){
  2395   2397           rc = rc2;
  2396   2398         }
  2397   2399       }
  2398   2400     }
  2399   2401   

Added ext/rtree/rtree.h.

            1  +/*
            2  +** 2008 May 26
            3  +**
            4  +** The author disclaims copyright to this source code.  In place of
            5  +** a legal notice, here is a blessing:
            6  +**
            7  +**    May you do good and not evil.
            8  +**    May you find forgiveness for yourself and forgive others.
            9  +**    May you share freely, never taking more than you give.
           10  +**
           11  +******************************************************************************
           12  +**
           13  +** This header file is used by programs that want to link against the
           14  +** RTREE library.  All it does is declare the sqlite3RtreeInit() interface.
           15  +*/
           16  +#include "sqlite3.h"
           17  +
           18  +#ifdef __cplusplus
           19  +extern "C" {
           20  +#endif  /* __cplusplus */
           21  +
           22  +int sqlite3RtreeInit(sqlite3 *db);
           23  +
           24  +#ifdef __cplusplus
           25  +}  /* extern "C" */
           26  +#endif  /* __cplusplus */

Changes to main.mk.

    73     73   	  fts2_tokenizer1.o
    74     74   EXTOBJ += fts3.o \
    75     75   	  fts3_hash.o \
    76     76   	  fts3_icu.o \
    77     77   	  fts3_porter.o \
    78     78             fts3_tokenizer.o \
    79     79   	  fts3_tokenizer1.o
           80  +EXTOBJ += rtree.o
    80     81   
    81     82   # All of the source code files.
    82     83   #
    83     84   SRC = \
    84     85     $(TOP)/src/alter.c \
    85     86     $(TOP)/src/analyze.c \
    86     87     $(TOP)/src/attach.c \
................................................................................
   182    183     $(TOP)/ext/fts3/fts3_icu.c \
   183    184     $(TOP)/ext/fts3/fts3_porter.c \
   184    185     $(TOP)/ext/fts3/fts3_tokenizer.h \
   185    186     $(TOP)/ext/fts3/fts3_tokenizer.c \
   186    187     $(TOP)/ext/fts3/fts3_tokenizer1.c
   187    188   SRC += \
   188    189     $(TOP)/ext/icu/icu.c
          190  +SRC += \
          191  +  $(TOP)/ext/rtree/rtree.h \
          192  +  $(TOP)/ext/rtree/rtree.c
   189    193   
   190    194   
   191    195   # Generated source code files
   192    196   #
   193    197   SRC += \
   194    198     keywordhash.h \
   195    199     opcodes.c \
................................................................................
   270    274     $(TOP)/ext/fts2/fts2.h \
   271    275     $(TOP)/ext/fts2/fts2_hash.h \
   272    276     $(TOP)/ext/fts2/fts2_tokenizer.h
   273    277   EXTHDR += \
   274    278     $(TOP)/ext/fts3/fts3.h \
   275    279     $(TOP)/ext/fts3/fts3_hash.h \
   276    280     $(TOP)/ext/fts3/fts3_tokenizer.h
          281  +EXTHDR += \
          282  +  $(TOP)/ext/rtree/rtree.h
   277    283   
   278    284   # This is the default Makefile target.  The objects listed here
   279    285   # are what get build when you type just "make" with no arguments.
   280    286   #
   281    287   all:	sqlite3.h libsqlite3.a sqlite3$(EXE)
   282    288   
   283    289   libsqlite3.a:	$(LIBOBJ)

Changes to publish.sh.

    20     20   VERSW=`sed 's/\./_/g' $srcdir/VERSION`
    21     21   echo "VERSIONS: $VERS $VERSW"
    22     22   
    23     23   # Start by building an sqlite shell for linux.
    24     24   #
    25     25   make clean
    26     26   make sqlite3.c
    27         -CFLAGS="-Os -DSQLITE_ENABLE_FTS3=1 -DSQLITE_THREADSAFE=0"
           27  +CFLAGS="-Os -DSQLITE_ENABLE_FTS3=0 -DSQLITE_ENABLE_RTREE=0"
           28  +CFLAGS="$CFLAGS -DSQLITE_THREADSAFE=0"
    28     29   echo '***** '"COMPILING sqlite3-$VERS.bin..."
    29     30   gcc $CFLAGS -Itsrc sqlite3.c tsrc/shell.c -o sqlite3 -ldl
    30     31   strip sqlite3
    31     32   mv sqlite3 sqlite3-$VERS.bin
    32     33   gzip sqlite3-$VERS.bin
    33     34   chmod 644 sqlite3-$VERS.bin.gz
    34     35   mv sqlite3-$VERS.bin.gz doc
................................................................................
    47     48   zip doc/sqlite-amalgamation-$VERSW.zip sqlite3.c sqlite3.h sqlite3ext.h
    48     49   
    49     50   # Build the sqlite.so and tclsqlite.so shared libraries
    50     51   # under Linux
    51     52   #
    52     53   TCLDIR=/home/drh/tcltk/846/linux/846linux
    53     54   TCLSTUBLIB=$TCLDIR/libtclstub8.4g.a
    54         -CFLAGS="-Os -DSQLITE_ENABLE_FTS3=1 -DHAVE_LOCALTIME_R=1 -DHAVE_GMTIME_R=1"
           55  +CFLAGS="-Os -DSQLITE_ENABLE_FTS3=3 -DSQLITE_ENABLE_RTREE=1"
           56  +CFLAGS="$CFLAGS -DHAVE_LOCALTIME_R=1 -DHAVE_GMTIME_R=1"
    55     57   echo '***** BUILDING shared libraries for linux'
    56     58   gcc $CFLAGS -shared tclsqlite3.c $TCLSTUBLIB -o tclsqlite3.so -lpthread
    57     59   strip tclsqlite3.so
    58     60   chmod 644 tclsqlite3.so
    59     61   mv tclsqlite3.so tclsqlite-$VERS.so
    60     62   gzip tclsqlite-$VERS.so
    61     63   mv tclsqlite-$VERS.so.gz doc
................................................................................
    75     77   zip doc/tclsqlite-$VERSW.zip tclsqlite3.dll
    76     78   echo zip doc/sqlitedll-$VERSW.zip sqlite3.dll sqlite3.def
    77     79   zip doc/sqlitedll-$VERSW.zip sqlite3.dll sqlite3.def
    78     80   
    79     81   # Build the sqlite.exe executable for windows.
    80     82   #
    81     83   OPTS='-DSTATIC_BUILD=1 -DNDEBUG=1 -DSQLITE_THREADSAFE=0'
    82         -OPTS="$OPTS -DSQLITE_ENABLE_FTS3=1"
           84  +OPTS="$OPTS -DSQLITE_ENABLE_FTS3=1 -DSQLITE_ENABLE_RTREE=1"
    83     85   i386-mingw32msvc-gcc -Os $OPTS -Itsrc -I$TCLDIR sqlite3.c tsrc/shell.c \
    84     86         -o sqlite3.exe
    85     87   zip doc/sqlite-$VERSW.zip sqlite3.exe
    86     88   
    87     89   # Construct a tarball of the source tree
    88     90   #
    89     91   echo '***** BUILDING source archive'

Changes to src/main.c.

    10     10   **
    11     11   *************************************************************************
    12     12   ** Main file for the SQLite library.  The routines in this file
    13     13   ** implement the programmer interface to the library.  Routines in
    14     14   ** other files are for internal use by SQLite and should not be
    15     15   ** accessed by users of the library.
    16     16   **
    17         -** $Id: main.c,v 1.441 2008/05/26 18:41:54 danielk1977 Exp $
           17  +** $Id: main.c,v 1.442 2008/05/26 20:19:26 drh Exp $
    18     18   */
    19     19   #include "sqliteInt.h"
    20     20   #include <ctype.h>
           21  +
    21     22   #ifdef SQLITE_ENABLE_FTS3
    22     23   # include "fts3.h"
           24  +#endif
           25  +#ifdef SQLITE_ENABLE_RTREE
           26  +# include "rtree.h"
    23     27   #endif
    24     28   
    25     29   /*
    26     30   ** The version of the library
    27     31   */
    28     32   const char sqlite3_version[] = SQLITE_VERSION;
    29     33   const char *sqlite3_libversion(void){ return sqlite3_version; }
................................................................................
  1183   1187       extern int sqlite3IcuInit(sqlite3*);
  1184   1188       rc = sqlite3IcuInit(db);
  1185   1189     }
  1186   1190   #endif
  1187   1191   
  1188   1192   #ifdef SQLITE_ENABLE_RTREE
  1189   1193     if( !db->mallocFailed && rc==SQLITE_OK){
  1190         -    extern int sqlite3RtreeInit(sqlite3*);
  1191   1194       rc = sqlite3RtreeInit(db);
  1192   1195     }
  1193   1196   #endif
  1194   1197   
  1195   1198     sqlite3Error(db, rc, 0);
  1196   1199   
  1197   1200     /* -DSQLITE_DEFAULT_LOCKING_MODE=1 makes EXCLUSIVE the default locking

Changes to tool/mksqlite3c.tcl.

    96     96      mutex.h
    97     97      opcodes.h
    98     98      os_common.h
    99     99      os.h
   100    100      os_os2.h
   101    101      pager.h
   102    102      parse.h
          103  +   rtree.h
   103    104      sqlite3ext.h
   104    105      sqlite3.h
   105    106      sqliteInt.h
   106    107      sqliteLimit.h
   107    108      vdbe.h
   108    109      vdbeInt.h
   109    110   } {
................................................................................
   269    270      main.c
   270    271   
   271    272      fts3.c
   272    273      fts3_hash.c
   273    274      fts3_porter.c
   274    275      fts3_tokenizer.c
   275    276      fts3_tokenizer1.c
          277  +
          278  +   rtree.c
   276    279   } {
   277    280     copy_file tsrc/$file
   278    281   }
   279    282   
   280    283   close $out

Deleted www/34to35.tcl.

     1         -#
     2         -# Run this TCL script to generate HTML for the goals.html file.
     3         -#
     4         -set rcsid {$Id: 34to35.tcl,v 1.4 2007/10/01 13:54:11 drh Exp $}
     5         -source common.tcl
     6         -header {SQLite Changes From Version 3.4.2 To 3.5.0}
     7         -
     8         -proc CODE {text} {
     9         -  puts "<blockquote><pre>"
    10         -  puts $text
    11         -  puts "</pre></blockquote>"
    12         -}
    13         -proc SYNTAX {text} {
    14         -  puts "<blockquote><pre>"
    15         -  set t2 [string map {& &amp; < &lt; > &gt;} $text]
    16         -  regsub -all "/(\[^\n/\]+)/" $t2 {</b><i>\1</i><b>} t3
    17         -  puts "<b>$t3</b>"
    18         -  puts "</pre></blockquote>"
    19         -}
    20         -proc IMAGE {name {caption {}}} {
    21         -  puts "<center><img src=\"$name\">"
    22         -  if {$caption!=""} {
    23         -    puts "<br>$caption"
    24         -  }
    25         -  puts "</center>"
    26         -}
    27         -proc PARAGRAPH {text} {
    28         -  # regsub -all "/(\[a-zA-Z0-9\]+)/" $text {<i>\1</i>} t2
    29         -  #regsub -all "\\*(\[^\n*\]+)\\*" $text {<tt><b><big>\1</big></b></tt>} t3
    30         -  regsub -all {\[([^]\n]+)\]} $text {[resolve_link \1]} t3
    31         -  puts "<p>[subst -novar -noback $t3]</p>\n"
    32         -}
    33         -proc resolve_link {args} {
    34         -  set a2 [split $args |]
    35         -  set id [string trim [lindex $a2 0]]
    36         -  if {[lindex $a2 1]==""} {
    37         -    set display [string trim [lindex $a2 0]]
    38         -  } else {
    39         -    set display [string trim [lrange $a2 1 end]]
    40         -  }
    41         -  regsub -all {[^a-zA-Z0-9_]} $id {} id
    42         -  return "<a href=\"capi3ref.html#$id\">$display</a>"
    43         -}
    44         -set level(0) 0
    45         -set level(1) 0
    46         -proc HEADING {n name {tag {}}} {
    47         -  if {$tag!=""} {
    48         -    puts "<a name=\"$tag\">"
    49         -  }
    50         -  global level
    51         -  incr level($n)
    52         -  for {set i [expr {$n+1}]} {$i<10} {incr i} {
    53         -    set level($i) 0
    54         -  }
    55         -  if {$n==0} {
    56         -    set num {}
    57         -  } elseif {$n==1} {
    58         -    set num $level(1).0
    59         -  } else {
    60         -    set num $level(1)
    61         -    for {set i 2} {$i<=$n} {incr i} {
    62         -      append num .$level($i)
    63         -    }
    64         -  }
    65         -  incr n 1
    66         -  puts "<h$n>$num $name</h$n>"
    67         -}
    68         -
    69         -HEADING 0 {Moving From SQLite 3.4.2 to 3.5.0}
    70         -
    71         -PARAGRAPH {
    72         -  SQLite version 3.5.0 introduces a new OS interface layer that
    73         -  is incompatible with all prior versions of SQLite.  In addition,
    74         -  a few existing interfaces have been generalized to work across all
    75         -  database connections within a process rather than just all
    76         -  connections within a thread.  The purpose of this article
    77         -  is to describe the changes to 3.5.0 in detail so that users
    78         -  of prior versions of SQLite can judge what, if any, effort will
    79         -  be required to upgrade to newer versions.
    80         -}
    81         -
    82         -HEADING 1 {Overview Of Changes}
    83         -
    84         -PARAGRAPH {
    85         -  A quick enumeration of the changes in SQLite version 3.5.0
    86         -  is provide here.  Subsequent sections will describe these
    87         -  changes in more detail.
    88         -}
    89         -PARAGRAPH {
    90         -  <ol>
    91         -  <li>The OS interface layer has been completely reworked:
    92         -  <ol type="a">
    93         -  <li>The undocumented <b>sqlite3_os_switch()</b> interface has
    94         -      been removed.</li>
    95         -  <li>The <b>SQLITE_ENABLE_REDEF_IO</b> compile-time flag no longer functions.
    96         -      I/O procedures are now always redefinable.</li>
    97         -  <li>Three new objects are defined for specifying I/O procedures:
    98         -      [sqlite3_vfs], [sqlite3_file], and [sqlite3_io_methods].</li>
    99         -  <li>Three new interfaces are used to create alternative OS interfaces:
   100         -      [sqlite3_vfs_register()], [sqlite3_vfs_unregister()], and
   101         -      [sqlite3_vfs_find()].</li>
   102         -  <li>A new interface has been added to provided additional control over
   103         -      the creation of new database connections: [sqlite3_open_v2()].
   104         -      The legacy interfaces of [sqlite3_open()] and
   105         -      [sqlite3_open16()] continue to be fully supported.</li>
   106         -  </ol></li>
   107         -  <li>The optional shared cache and memory management features that
   108         -      were introduced in version 3.3.0 can now be used across multiple
   109         -      threads within the same process.  Formerly, these extensions only
   110         -      applied to database connections operating within a single thread.
   111         -   <ol type="a">
   112         -   <li>The [sqlite3_enable_shared_cache()] interface now applies to all
   113         -       threads within a process, not to just the one thread in which it
   114         -       was run.</li>
   115         -   <li>The [sqlite3_soft_heap_limit()] interface now applies to all threads
   116         -       within a process, not to just the one thread in which it was run.</li>
   117         -   <li>The [sqlite3_release_memory()] interface will now attempt to reduce
   118         -       the memory usages across all database connections in all threads, not
   119         -       just connections in the thread where the interface is called.</li>
   120         -   <li>The [sqlite3_thread_cleanup()] interface has become a no-op.</li>
   121         -   </ol></li>
   122         -  <li>Restrictions on the use of the same database connection by multiple
   123         -      threads have been dropped.  It is now safe for
   124         -      multiple threads to use the same database connection at the same
   125         -      time.</li>
   126         -  <li>There is now a compile-time option that allows an application to
   127         -      define alternative malloc()/free() implementations without having
   128         -      to modify any core SQLite code.</li>
   129         -  <li>There is now a compile-time option that allows an application to
   130         -      define alternative mutex implementations without having
   131         -      to modify any core SQLite code.</li>
   132         -  </ol>
   133         -}
   134         -PARAGRAPH {
   135         -  Of these changes, only 1a and 2a through 2c are incompatibilities
   136         -  in any formal sense.
   137         -  But users who have previously made custom modifications to the
   138         -  SQLite source (for example to add a custom OS layer for embedded
   139         -  hardware) might find that these changes have a larger impact.
   140         -  On the other hand, an important goal of these changes is to make
   141         -  it much easier to customize SQLite for use on different operating
   142         -  systems. 
   143         -}
   144         -
   145         -HEADING 1 {The OS Interface Layer}
   146         -
   147         -PARAGRAPH {
   148         -  If your system defines a custom OS interface for SQLite or if you
   149         -  were using the undocumented <b>sqlite3_os_switch()</b>
   150         -  interface, then you will need to make modifications in order to
   151         -  upgrade to SQLite version 3.5.0.  This may seem painful at first
   152         -  glance.  But as you look more closely, you will probably discover
   153         -  that your changes are made smaller and easier to understand and manage
   154         -  by the new SQLite interface.  It is likely that your changes will
   155         -  now also work seamlessly with the SQLite amalgamation.  You will
   156         -  no longer need to make any changes to the code SQLite source code.
   157         -  All of your changes can be effected by application code and you can
   158         -  link against a standard, unmodified version of the SQLite amalgamation.
   159         -  Furthermore, the OS interface layer, which was formerly undocumented,
   160         -  is now an officially support interface for SQLite.  So you have
   161         -  some assurance that this will be a one-time change and that your
   162         -  new backend will continue to work in future versions of SQLite.
   163         -}
   164         -
   165         -HEADING 2 {The Virtual File System Object}
   166         -
   167         -PARAGRAPH {
   168         -  The new OS interface for SQLite is built around an object named
   169         -  [sqlite3_vfs].  The "vfs" standard for "Virtual File System".
   170         -  The sqlite3_vfs object is basically a structure containing pointers
   171         -  to functions that implement the primitive disk I/O operations that
   172         -  SQLite needs to perform in order to read and write databases.  
   173         -  In this article, we will often refer a sqlite3_vfs objects as a "VFS".
   174         -}
   175         -
   176         -PARAGRAPH {
   177         -  SQLite is able to use multiple VFSes at the same time.  Each
   178         -  individual database connection is associated with just one VFS.
   179         -  But if you have multiple database connections, each connection
   180         -  can be associated with a different VFS.
   181         -}
   182         -
   183         -PARAGRAPH {
   184         -  There is always a default VFS.
   185         -  The legacy interfaces [sqlite3_open()] and [sqlite3_open16()] always
   186         -  use the default VFS.
   187         -  The new interface for creating database connections,
   188         -  [sqlite3_open_v2()], allows you to specify which VFS you want to
   189         -  use by name.
   190         -}
   191         -
   192         -HEADING 3 {Registering New VFS Objects}
   193         -
   194         -PARAGRAPH {
   195         -  Standard builds of SQLite for unix or windows come with a single
   196         -  VFS named "unix" or "win32", as appropriate.  This one VFS is also 
   197         -  the default.  So if you are using the legacy open functions, everything
   198         -  will continue to operate as it has before.  The change is that an application
   199         -  now has the flexibility of adding new VFS modules to implement a
   200         -  customized OS layer.  The [sqlite3_vfs_register()] API can be used
   201         -  to tell SQLite about one or more application-defined VFS modules:
   202         -}
   203         -
   204         -CODE {
   205         -int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt);
   206         -}
   207         -
   208         -PARAGRAPH {
   209         -  Applications can call sqlite3_vfs_register at any time, though of course
   210         -  a VFS needs to be registered before it can be used.  The first argument
   211         -  is a pointer to a customized VFS object that the application has prepared.
   212         -  The second argument is true to make the new VFS the default VFS so that
   213         -  it will be used by the legacy [sqlite3_open()] and [sqlite3_open16()] APIs.
   214         -  If the new VFS is not the default, then you will probably have to use
   215         -  the new [sqlite3_open_v2()] API to use it.  Note, however, that if
   216         -  a new VFS is the only VFS known to SQLite (if SQLite was compiled without
   217         -  its usual default VFS or if the pre-compiled default VFS was removed
   218         -  using [sqlite3_vfs_unregister()]) then the new VFS automatic becomes the
   219         -  default VFS regardless of the makeDflt argument to [sqlite3_vfs_register()].
   220         -}
   221         -
   222         -PARAGRAPH {
   223         -  Standard builds include the default "unix" or "win32" VFSes.
   224         -  But if you use the -DOS_OTHER=1 compile-time option, then SQLite is
   225         -  built without a default VFS.  In that case, the application must
   226         -  register at least one VFS prior to calling [sqlite3_open()].
   227         -  This is the approach that embedded applications should use.
   228         -  Rather than modifying the SQLite source to to insert an alternative
   229         -  OS layer as was done in prior releases of SQLite, instead compile
   230         -  an unmodified SQLite source file (preferably the amalgamation)
   231         -  with the -DOS_OTHER=1 option, then invoke [sqlite3_vfs_register()]
   232         -  to define the interface to the underlying filesystem prior to
   233         -  creating any database connections.
   234         -}
   235         -
   236         -HEADING 3 {Additional Control Over VFS Objects}
   237         -
   238         -PARAGRAPH {
   239         -  The [sqlite3_vfs_unregister()] API is used to remove an existing
   240         -  VFS from the system.
   241         -}
   242         -
   243         -CODE {
   244         -int sqlite3_vfs_unregister(sqlite3_vfs*);
   245         -}
   246         -
   247         -PARAGRAPH {
   248         -  The [sqlite3_vfs_find()] API is used to locate a particular VFS
   249         -  by name.  Its prototype is as follows:
   250         -}
   251         -
   252         -CODE {
   253         -sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName);
   254         -}
   255         -
   256         -PARAGRAPH {
   257         -  The argument is the symbolic name for the desired VFS.  If the
   258         -  argument is a NULL pointer, then the default VFS is returned.
   259         -  The function returns a pointer to the [sqlite3_vfs] object that
   260         -  implements the VFS.  Or it returns a NULL pointer if no object
   261         -  could be found that matched the search criteria.
   262         -}
   263         -
   264         -HEADING 3 {Modifications Of Existing VFSes}
   265         -
   266         -PARAGRAPH {
   267         -  Once a VFS has been registered, it should never be modified.  If
   268         -  a change in behavior is required, a new VFS should be registered.
   269         -  The application could, perhaps, use [sqlite3_vfs_find()] to locate
   270         -  the old VFS, make a copy of the old VFS into a new [sqlite3_vfs]
   271         -  object, make the desired modifications to the new VFS, unregister
   272         -  the old VFS, the register the new VFS in its place.  Existing
   273         -  database connections would continue to use the old VFS even after
   274         -  it is unregistered, but new database connections would use the
   275         -  new VFS.
   276         -}  
   277         -
   278         -HEADING 3 {The VFS Object}
   279         -
   280         -PARAGRAPH {
   281         -  A VFS object is an instance of the following structure:
   282         -}
   283         -
   284         -CODE {
   285         -typedef struct sqlite3_vfs sqlite3_vfs;
   286         -struct sqlite3_vfs {
   287         -  int iVersion;            /* Structure version number */
   288         -  int szOsFile;            /* Size of subclassed sqlite3_file */
   289         -  int mxPathname;          /* Maximum file pathname length */
   290         -  sqlite3_vfs *pNext;      /* Next registered VFS */
   291         -  const char *zName;       /* Name of this virtual file system */
   292         -  void *pAppData;          /* Pointer to application-specific data */
   293         -  int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*,
   294         -               int flags, int *pOutFlags);
   295         -  int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);
   296         -  int (*xAccess)(sqlite3_vfs*, const char *zName, int flags);
   297         -  int (*xGetTempName)(sqlite3_vfs*, char *zOut);
   298         -  int (*xFullPathname)(sqlite3_vfs*, const char *zName, char *zOut);
   299         -  void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename);
   300         -  void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg);
   301         -  void *(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol);
   302         -  void (*xDlClose)(sqlite3_vfs*, void*);
   303         -  int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
   304         -  int (*xSleep)(sqlite3_vfs*, int microseconds);
   305         -  int (*xCurrentTime)(sqlite3_vfs*, double*);
   306         -  /* New fields may be appended in figure versions.  The iVersion
   307         -  ** value will increment whenever this happens. */
   308         -};
   309         -}
   310         -
   311         -PARAGRAPH {
   312         -  To create a new VFS, an application fills in an instance of this
   313         -  structure with appropriate values and then calls [sqlite3_vfs_register()].
   314         -}
   315         -
   316         -PARAGRAPH {
   317         -  The iVersion field of [sqlite3_vfs] should be 1 for SQLite version 3.5.0.
   318         -  This number may increase in future versions of SQLite if we have to
   319         -  modify the VFS object in some way.  We hope that this never happens,
   320         -  but the provision is made in case it does.
   321         -}
   322         -
   323         -PARAGRAPH {
   324         -  The szOsFile field is the size in bytes of the structure that defines
   325         -  an open file: the [sqlite3_file] object.  This object will be described
   326         -  more fully below.  The point here is that each VFS implementation can
   327         -  define its own [sqlite3_file] object containing whatever information
   328         -  the VFS implementation needs to store about an open file.  SQLite needs
   329         -  to know how big this object is, however, in order to preallocate enough
   330         -  space to hold it.
   331         -}
   332         -
   333         -PARAGRAPH {
   334         -  The mxPathname field is the maximum length of a file pathname that
   335         -  this VFS can use.  SQLite sometimes has to preallocate buffers of
   336         -  this size, so it should be as small as reasonably possible.  Some
   337         -  filesystems permit huge pathnames, but in practice pathnames rarely
   338         -  extend beyond 100 bytes or so.  You do not have to put the longest
   339         -  pathname that the underlying filesystem can handle here.  You only
   340         -  have to put the longest pathname that you want SQLite to be able to
   341         -  handle.  A few hundred is a good value in most cases.
   342         -}
   343         -
   344         -PARAGRAPH {
   345         -  The pNext field is used internally by SQLite.  Specifically, SQLite
   346         -  uses this field to form a linked list of registered VFSes.
   347         -}
   348         -
   349         -PARAGRAPH {
   350         -  The zName field is the symbolic name of the VFS.  This is the name 
   351         -  that the [sqlite3_vfs_find()] compares against when it is looking for
   352         -  a VFS.
   353         -}
   354         -
   355         -PARAGRAPH {
   356         -  The pAppData pointer is unused by the SQLite core.  The pointer is
   357         -  available to store auxiliary information that a VFS information might
   358         -  want to carry around.
   359         -}
   360         -
   361         -PARAGRAPH {
   362         -  The remaining fields of the [sqlite3_vfs] object all store pointer
   363         -  to functions that implement primitive operations.  We call these
   364         -  "methods".  The first methods, xOpen, is used to open files on
   365         -  the underlying storage media.  The result is an [sqlite3_file]
   366         -  object.  There are additional methods, defined by the [sqlite3_file]
   367         -  object itself that are used to read and write and close the file.
   368         -  The additional methods are detailed below.  The filename is in UTF-8.
   369         -  SQLite will guarantee that the zFilename string passed to
   370         -  xOpen() is a full pathname as generated by xFullPathname() and
   371         -  that the string will be valid and unchanged until xClose() is
   372         -  called.  So the [sqlite3_file] can store a pointer to the
   373         -   filename if it needs to remember the filename for some reason.
   374         -   The flags argument to xOpen() is a copy of the flags argument
   375         -   to sqlite3_open_v2().  If sqlite3_open() or sqlite3_open16()
   376         -   is used, then flags is [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE].
   377         -   If xOpen() opens a file read-only then it sets *pOutFlags to
   378         -   include [SQLITE_OPEN_READONLY].  Other bits in *pOutFlags may be
   379         -   set.
   380         -   SQLite will also add one of the following flags to the xOpen()
   381         -   call, depending on the object being opened:
   382         -   <ul>
   383         -   <li>  [SQLITE_OPEN_MAIN_DB]
   384         -   <li>  [SQLITE_OPEN_MAIN_JOURNAL]
   385         -   <li>  [SQLITE_OPEN_TEMP_DB]
   386         -   <li>  [SQLITE_OPEN_TEMP_JOURNAL]
   387         -   <li>  [SQLITE_OPEN_TRANSIENT_DB]
   388         -   <li>  [SQLITE_OPEN_SUBJOURNAL]
   389         -   <li>  [SQLITE_OPEN_MASTER_JOURNAL]
   390         -   </ul>
   391         -   The file I/O implementation can use the object type flags to
   392         -   changes the way it deals with files.  For example, an application
   393         -   that does not care about crash recovery or rollback, might make
   394         -   the open of a journal file a no-op.  Writes to this journal are
   395         -   also a no-op.  Any attempt to read the journal returns [SQLITE_IOERR].
   396         -   Or the implementation might recognize the a database file will
   397         -   be doing page-aligned sector reads and writes in a random order
   398         -   and set up its I/O subsystem accordingly.
   399         -   SQLite might also add one of the following flags to the xOpen
   400         -   method:
   401         -   <ul>
   402         -   <li> [SQLITE_OPEN_DELETEONCLOSE]
   403         -   <li> [SQLITE_OPEN_EXCLUSIVE]
   404         -   </ul>
   405         -   The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be
   406         -   deleted when it is closed.  This will always be set for TEMP 
   407         -   databases and journals and for subjournals.  The 
   408         -   [SQLITE_OPEN_EXCLUSIVE] flag means the file should be opened
   409         -   for exclusive access.  This flag is set for all files except
   410         -   for the main database file.
   411         -   The [sqlite3_file] structure passed as the third argument to
   412         -   xOpen is allocated by the caller.  xOpen just fills it in.  The
   413         -   caller allocates a minimum of szOsFile bytes for the [sqlite3_file]
   414         -   structure.
   415         -}
   416         -
   417         -PARAGRAPH {
   418         -  The differences between an [SQLITE_OPEN_TEMP_DB] database and an
   419         -  [SQLITE_OPEN_TRANSIENT_DB] database is this:  The [SQLITE_OPEN_TEMP_DB]
   420         -  is used for explicitly declared and named TEMP tables (using the
   421         -  CREATE TEMP TABLE syntax) or for named tables in a temporary database
   422         -  that is created by opening a database with a filename that is an empty
   423         -  string.  An [SQLITE_OPEN_TRANSIENT_DB] holds an database table that
   424         -  SQLite creates automatically in order to evaluate a subquery or
   425         -  ORDER BY or GROUP BY clause.  Both TEMP_DB and TRANSIENT_DB databases
   426         -  are private and are deleted automatically.  TEMP_DB databases last
   427         -  for the duration of the database connection.  TRANSIENT_DB databases
   428         -  last only for the duration of a single SQL statement.
   429         -}
   430         -
   431         -PARAGRAPH {
   432         -  The xDelete method is used delete a file.  The name of the file is
   433         -  given in the second parameter.  The filename will be in UTF-8.
   434         -  The VFS must convert the filename into whatever character representation
   435         -  the underlying operating system expects.  If the syncDir parameter is
   436         -  true, then the xDelete method should not return until the change
   437         -  to the directory contents for the directory containing the
   438         -  deleted file have been synced to disk in order to insure that the
   439         -  file does not "reappear" if a power failure occurs soon after.
   440         -}
   441         -
   442         -PARAGRAPH {
   443         -  The xAccess method is used to check for access permissions on a file.
   444         -  The filename will be UTF-8 encoded.  The flags argument will be
   445         -  [SQLITE_ACCESS_EXISTS] to check for the existence of the file,
   446         -  [SQLITE_ACCESS_READWRITE] to check to see if the file is both readable
   447         -  and writable, or [SQLITE_ACCESS_READ] to check to see if the file is
   448         -  at least readable.  The "file" named by the second parameter might
   449         -  be a directory or folder name.
   450         -}
   451         -
   452         -PARAGRAPH {
   453         -  The xGetTempName method computes the name of a temporary file that
   454         -  SQLite can use.  The name should be written into the buffer given
   455         -  by the second parameter.  SQLite will size that buffer to hold
   456         -  at least mxPathname bytes.  The generated filename should be in UTF-8.
   457         -  To avoid security problems, the generated temporary filename should
   458         -  contain enough randomness to prevent an attacker from guessing the
   459         -  temporary filename in advance.
   460         -}
   461         -
   462         -PARAGRAPH {
   463         -  The xFullPathname method is used to convert a relative pathname
   464         -  into a full pathname.  The resulting full pathname is written into
   465         -  the buffer provided by the third parameter.  SQLite will size the
   466         -  output buffer to at least mxPathname bytes.  Both the input and
   467         -  output names should be in UTF-8.
   468         -}
   469         -
   470         -PARAGRAPH {
   471         -  The xDlOpen, xDlError, xDlSym, and xDlClose methods are all used for
   472         -  accessing shared libraries at run-time.  These methods may be omitted
   473         -  (and their pointers set to zero) if the library is compiled with
   474         -  SQLITE_OMIT_LOAD_EXTENSION or if the [sqlite3_enable_load_extension()]
   475         -  interface is never used to enable dynamic extension loading.  The
   476         -  xDlOpen method opens a shared library or DLL and returns a pointer to
   477         -  a handle.  NULL is returned if the open fails.  If the open fails,
   478         -  the xDlError method can be used to obtain a text error message.
   479         -  The message is written into the zErrMsg buffer of the third parameter
   480         -  which is at least nByte bytes in length.  The xDlSym returns a pointer
   481         -  to a symbol in the shared library.  The name of the symbol is given
   482         -  by the second parameter.  UTF-8 encoding is assumed.  If the symbol
   483         -  is not found a NULL pointer is returned.  The xDlClose routine closes
   484         -  the shared library.
   485         -}
   486         -
   487         -PARAGRAPH {
   488         -  The xRandomness method is used exactly once to initialize the 
   489         -  pseudo-random number generator (PRNG) inside of SQLite.  Only
   490         -  the xRandomness method on the default VFS is used.  The xRandomness
   491         -  methods on other VFSes are never accessed by SQLite.
   492         -  The xRandomness routine requests that nByte bytes of randomness
   493         -  be written into zOut.  The routine returns the actual number of
   494         -  bytes of randomness obtained.  The quality of the randomness so obtained
   495         -  will determine the quality of the randomness generated by built-in 
   496         -  SQLite functions such as random() and randomblob().  SQLite also
   497         -  uses its PRNG to generate temporary file names..  On some platforms
   498         -  (ex: windows) SQLite assumes that temporary file names are unique
   499         -  without actually testing for collisions, so it is important to have
   500         -  good-quality randomness even if the random() and randomblob() 
   501         -  functions are never used.
   502         -}
   503         -
   504         -PARAGRAPH {
   505         -  The xSleep method is used to suspend the calling thread for at
   506         -  least the number of microseconds given.  This method is used to
   507         -  implement the [sqlite3_sleep()] and [sqlite3_busy_timeout()] APIs.
   508         -  In the case of [sqlite3_sleep()] the xSleep method of the default
   509         -  VFS is always used.  If the underlying system does not have a
   510         -  microsecond resolution sleep capability, then the sleep time should
   511         -  be rounded up.  xSleep returns this rounded-up value.
   512         -}
   513         -
   514         -PARAGRAPH {
   515         -  The xCurrentTime method finds the current time and date and writes
   516         -  the result as double-precision floating point value into pointer
   517         -  provided by the second parameter.  The time and date is in
   518         -  coordinated universal time (UTC) and is a fractional julian day number.
   519         -}
   520         -
   521         -HEADING 3 {The Open File Object}
   522         -
   523         -PARAGRAPH {
   524         -  The result of opening a file is an instance of an [sqlite3_file] object.
   525         -  The [sqlite3_file] object is an abstract base class defined as follows:
   526         -}
   527         -
   528         -CODE {
   529         -typedef struct sqlite3_file sqlite3_file;
   530         -struct sqlite3_file {
   531         -  const struct sqlite3_io_methods *pMethods;
   532         -};
   533         -}
   534         -
   535         -PARAGRAPH {
   536         -  Each VFS implementation will subclass the [sqlite3_file] by adding
   537         -  additional fields at the end to hold whatever information the VFS
   538         -  needs to know about an open file.  It does not matter what information
   539         -  is stored as long as the total size of the structure does not exceed
   540         -  the szOsFile value recorded in the [sqlite3_vfs] object.
   541         -}
   542         -
   543         -PARAGRAPH {
   544         -  The [sqlite3_io_methods] object is a structure that contains pointers
   545         -  to methods for reading, writing, and otherwise dealing with files.
   546         -  This object is defined as follows:
   547         -}
   548         -
   549         -CODE {
   550         -typedef struct sqlite3_io_methods sqlite3_io_methods;
   551         -struct sqlite3_io_methods {
   552         -  int iVersion;
   553         -  int (*xClose)(sqlite3_file*);
   554         -  int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst);
   555         -  int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst);
   556         -  int (*xTruncate)(sqlite3_file*, sqlite3_int64 size);
   557         -  int (*xSync)(sqlite3_file*, int flags);
   558         -  int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize);
   559         -  int (*xLock)(sqlite3_file*, int);
   560         -  int (*xUnlock)(sqlite3_file*, int);
   561         -  int (*xCheckReservedLock)(sqlite3_file*);
   562         -  int (*xFileControl)(sqlite3_file*, int op, void *pArg);
   563         -  int (*xSectorSize)(sqlite3_file*);
   564         -  int (*xDeviceCharacteristics)(sqlite3_file*);
   565         -  /* Additional methods may be added in future releases */
   566         -};
   567         -}
   568         -
   569         -PARAGRAPH {
   570         -  The iVersion field of [sqlite3_io_methods] is provided as insurance
   571         -  against future enhancements.  The iVersion value should always be
   572         -  1 for SQLite version 3.5.
   573         -}
   574         -
   575         -PARAGRAPH {
   576         -  The xClose method closes the file.  The space for the [sqlite3_file]
   577         -  structure is deallocated by the caller.  But if the [sqlite3_file]
   578         -  contains pointers to other allocated memory or resources, those
   579         -  allocations should be released by the xClose method.
   580         -}
   581         -
   582         -PARAGRAPH {
   583         -  The xRead method reads iAmt bytes from the file beginning at a byte
   584         -  offset to iOfst.  The data read is stored in the pointer of the
   585         -  second parameter.  xRead returns the [SQLITE_OK] on success,
   586         -  [SQLITE_IOERR_SHORT_READ] if it was not able to read the full number
   587         -  of bytes because it reached end-of-file, or [SQLITE_IOERR_READ] for
   588         -  any other error.
   589         -}
   590         -
   591         -PARAGRAPH {
   592         -  The xWrite method writes iAmt bytes of data from the second parameter
   593         -  into the file beginning at an offset of iOfst bytes.  If the size of
   594         -  the file is less than iOfst bytes prior to the write, then xWrite should
   595         -  ensure that the file is extended with zeros up to iOfst bytes prior
   596         -  to beginning its write.  xWrite continues to extends the file as
   597         -  necessary so that the size of the file is at least iAmt+iOfst bytes 
   598         -  at the conclusion of the xWrite call.  The xWrite method returns
   599         -  [SQLITE_OK] on success.  If the write cannot complete because the
   600         -  underlying storage medium is full, then [SQLITE_FULL] is returned.
   601         -  [SQLITE_IOERR_WRITE] should be returned for any other error.
   602         -}
   603         -
   604         -PARAGRAPH {
   605         -  The xTruncate method truncates a file to be nByte bytes in length.
   606         -  If the file is already nByte bytes or less in length then this
   607         -  method is a no-op.  The xTruncate method returns [SQLITE_OK] on
   608         -  success and [SQLITE_IOERR_TRUNCATE] if anything goes wrong.
   609         -}
   610         -
   611         -PARAGRAPH {
   612         -  The xSync method is used to force previously written data out of
   613         -  operating system cache and into non-volatile memory.  The second
   614         -  parameter is usually [SQLITE_SYNC_NORMAL].  If the second parameter
   615         -  is [SQLITE_SYNC_FULL] then the xSync method should make sure that
   616         -  data has also been flushed through the disk controllers cache.
   617         -  The [SQLITE_SYNC_FULL] parameter is the equivalent of the F_FULLSYNC
   618         -  ioctl() on Mac OS X. The xSync method returns
   619         -  [SQLITE_OK] on success and [SQLITE_IOERR_FSYNC] if anything goes wrong.
   620         -}
   621         -
   622         -PARAGRAPH {
   623         -  The xFileSize() method determines the current size of the file
   624         -  in bytes and writes that value into *pSize.  It returns [SQLITE_OK]
   625         -  on success and [SQLITE_IOERR_FSTAT] if something goes wrong.
   626         -}
   627         -
   628         -PARAGRAPH {
   629         -  The xLock and xUnlock methods are used to set and clear file locks.
   630         -  SQLite supports five levels of file locks, in order:
   631         -  <ul>
   632         -  <li> [SQLITE_LOCK_NONE]
   633         -  <li> [SQLITE_LOCK_SHARED]
   634         -  <li> [SQLITE_LOCK_RESERVED]
   635         -  <li> [SQLITE_LOCK_PENDING]
   636         -  <li> [SQLITE_LOCK_EXCLUSIVE]
   637         -  </ul>
   638         -  The underlying implementation can support some subset of these locking
   639         -  levels as long as it meets the other requirements of this paragraph.
   640         -  The locking level is specified as the second argument to both xLock
   641         -  and xUnlock.  The xLock method increases the locking level to the
   642         -  specified locking level or higher.  The xUnlock method decreases the
   643         -  locking level to no lower than the level specified.  
   644         -  [SQLITE_LOCK_NONE] means that the file is unlocked.  [SQLITE_LOCK_SHARED]
   645         -  gives permission to read the file.  Multiple database connections can
   646         -  hold [SQLITE_LOCK_SHARED] at the same time.
   647         -  [SQLITE_LOCK_RESERVED] is like [SQLITE_LOCK_SHARED] in that its is permission
   648         -  to read the file.  But only a single connection can hold a reserved lock
   649         -  at any point in time.  The [SQLITE_LOCK_PENDING] is also permission to
   650         -  read the file.  Other connections can continue to read the file as well,
   651         -  but no other connection is allowed to escalate a lock from none to shared.
   652         -  [SQLITE_LOCK_EXCLUSIVE] is permission to write on the file.  Only a single
   653         -  connection can hold an exclusive lock and no other connection can hold
   654         -  any lock (other than "none") while one connection is hold an exclusive
   655         -  lock.  The xLock returns [SQLITE_OK] on success, [SQLITE_BUSY] if it
   656         -  is unable to obtain the lock, or [SQLITE_IOERR_RDLOCK] if something else
   657         -  goes wrong.  The xUnlock method returns [SQLITE_OK] on success and
   658         -  [SQLITE_IOERR_UNLOCK] for problems.
   659         -}
   660         -
   661         -PARAGRAPH {
   662         -  The xCheckReservedLock method checks to see if another connection or
   663         -  another process is currently holding a reserved, pending, or exclusive
   664         -  lock on the file.  It returns true or false.
   665         -}
   666         -
   667         -PARAGRAPH {
   668         -  The xFileControl() method is a generic interface that allows custom
   669         -  VFS implementations to directly control an open file using the
   670         -  (new and experimental)
   671         -  [sqlite3_file_control()] interface.  The second "op" argument
   672         -  is an integer opcode.   The third
   673         -  argument is a generic pointer which is intended to be a pointer
   674         -  to a structure that may contain arguments or space in which to
   675         -  write return values.  Potential uses for xFileControl() might be
   676         -  functions to enable blocking locks with timeouts, to change the
   677         -  locking strategy (for example to use dot-file locks), to inquire
   678         -  about the status of a lock, or to break stale locks.  The SQLite
   679         -  core reserves opcodes less than 100 for its own use. 
   680         -  A [SQLITE_FCNTL_LOCKSTATE | list of opcodes] less than 100 is available.
   681         -  Applications that define a custom xFileControl method should use opcodes 
   682         -  greater than 100 to avoid conflicts.
   683         -}
   684         -
   685         -PARAGRAPH {
   686         -  The xSectorSize returns the "sector size" of the underlying
   687         -  non-volatile media.  A "sector" is defined as the smallest unit of
   688         -  storage that can be written without disturbing adjacent storage.
   689         -  On a disk drive the "sector size" has until recently been 512 bytes,
   690         -  though there is a push to increase this value to 4KiB.  SQLite needs
   691         -  to know the sector size so that it can write a full sector at a
   692         -  time, and thus avoid corrupting adjacent storage space if a power
   693         -  lose occurs in the middle of a write.
   694         -}
   695         -
   696         -PARAGRAPH {
   697         -  The xDeviceCharacteristics method returns an integer bit vector that
   698         -  defines any special properties that the underlying storage medium might
   699         -  have that SQLite can use to increase performance.  The allowed return
   700         -  is the bit-wise OR of the following values:
   701         -  <ul>
   702         -  <li> [SQLITE_IOCAP_ATOMIC]
   703         -  <li> [SQLITE_IOCAP_ATOMIC512]
   704         -  <li> [SQLITE_IOCAP_ATOMIC1K]
   705         -  <li> [SQLITE_IOCAP_ATOMIC2K]
   706         -  <li> [SQLITE_IOCAP_ATOMIC4K]
   707         -  <li> [SQLITE_IOCAP_ATOMIC8K]
   708         -  <li> [SQLITE_IOCAP_ATOMIC16K]
   709         -  <li> [SQLITE_IOCAP_ATOMIC32K]
   710         -  <li> [SQLITE_IOCAP_ATOMIC64K]
   711         -  <li> [SQLITE_IOCAP_SAFE_APPEND]
   712         -  <li> [SQLITE_IOCAP_SEQUENTIAL]
   713         -  </ul>
   714         -  The [SQLITE_IOCAP_ATOMIC] bit means that all writes to this device are
   715         -  atomic in the sense that either the entire write occurs or none of it
   716         -  occurs.  The other 
   717         -  [SQLITE_IOCAP_ATOMIC | SQLITE_IOCAP_ATOMIC<i>nnn</i>] values indicate that
   718         -  writes of aligned blocks of the indicated size are atomic.
   719         -  [SQLITE_IOCAP_SAFE_APPEND] means that when extending a file with new
   720         -  data, the new data is written first and then the file size is updated.
   721         -  So if a power failure occurs, there is no chance that the file might have
   722         -  been extended with randomness.  The [SQLITE_IOCAP_SEQUENTIAL] bit means
   723         -  that all writes occur in the order that they are issued and are not
   724         -  reordered by the underlying file system.
   725         -}
   726         -
   727         -HEADING 3 {Checklist For Constructing A New VFS}
   728         -
   729         -PARAGRAPH {
   730         -  The preceding paragraphs contain a lot of information.
   731         -  To ease the task of constructing
   732         -  a new VFS for SQLite we offer the following implementation checklist:
   733         -}
   734         -
   735         -PARAGRAPH {
   736         -  <ol>
   737         -  <li> Define an appropriate subclass of the [sqlite3_file] object.
   738         -  <li> Implement the methods required by the [sqlite3_io_methods] object.
   739         -  <li> Create a static and 
   740         -       constant [sqlite3_io_methods] object containing pointers
   741         -       to the methods from the previous step.
   742         -  <li> Implement the xOpen method that opens a file and populates an
   743         -       [sqlite3_file] object, including setting pMethods to
   744         -       point to the [sqlite3_io_methods] object from the previous step.
   745         -  <li> Implement the other methods required by [sqlite3_vfs].
   746         -  <li> Define a static (but not constant) [sqlite3_vfs] structure that
   747         -       contains pointers to the xOpen method and the other methods and
   748         -       which contains the appropriate values for iVersion, szOsFile,
   749         -       mxPathname, zName, and pAppData.
   750         -  <li> Implement a procedure that calls [sqlite3_vfs_register()] and
   751         -       passes it a pointer to the [sqlite3_vfs] structure from the previous
   752         -       step.  This procedure is probably the only exported symbol in the
   753         -       source file that implements your VFS.
   754         -  </ol>
   755         -}
   756         -
   757         -PARAGRAPH {
   758         -  Within your application, call the procedure implemented in the last
   759         -  step above as part of your initialization process before any
   760         -  database connections are opened.  
   761         -}
   762         -
   763         -HEADING 1 {The Memory Allocation Subsystem}
   764         -
   765         -PARAGRAPH {
   766         -  Beginning with version 3.5, SQLite obtains all of the heap memory it
   767         -  needs using the routines [sqlite3_malloc()], [sqlite3_free()], and
   768         -  [sqlite3_realloc()].  These routines have existed in prior versions
   769         -  of SQLite, but SQLite has previously bypassed these routines and used
   770         -  its own memory allocator.  This all changes in version 3.5.0.
   771         -}
   772         -
   773         -PARAGRAPH {
   774         -  The SQLite source tree actually contains multiple versions of the
   775         -  memory allocator.  The default high-speed version found in the
   776         -  "mem1.c" source file is used for most builds.  But if the SQLITE_MEMDEBUG
   777         -  flag is enabled, a separate memory allocator the "mem2.c" source file
   778         -  is used instead.  The mem2.c allocator implements lots of hooks to
   779         -  do error checking and to simulate memory allocation failures for testing
   780         -  purposes.  Both of these allocators use the malloc()/free() implementation
   781         -  in the standard C library.
   782         -}
   783         -
   784         -PARAGRAPH {
   785         -  Applications are not required to use either of these standard memory
   786         -  allocators.  If SQLite is compiled with SQLITE_OMIT_MEMORY_ALLOCATION
   787         -  then no implementation for the [sqlite3_malloc()], [sqlite3_realloc()],
   788         -  and [sqlite3_free()] functions is provided.  Instead, the application
   789         -  that links against SQLite must provide its own implementation of these
   790         -  functions.  The application provided memory allocator is not required
   791         -  to use the malloc()/free() implementation in the standard C library.
   792         -  An embedded application might provide an alternative memory allocator
   793         -  that uses memory for a fixed memory pool set aside for the exclusive
   794         -  use of SQLite, for example.
   795         -}
   796         -
   797         -PARAGRAPH {
   798         -  Applications that implement their own memory allocator must provide
   799         -  implementation for the usual three allocation functions 
   800         -  [sqlite3_malloc()], [sqlite3_realloc()], and [sqlite3_free()].
   801         -  And they must also implement a fourth function:
   802         -}
   803         -
   804         -CODE {
   805         -int sqlite3_memory_alarm(
   806         -  void(*xCallback)(void *pArg, sqlite3_int64 used, int N),
   807         -  void *pArg,
   808         -  sqlite3_int64 iThreshold
   809         -);
   810         -}
   811         -
   812         -PARAGRAPH {
   813         - The [sqlite3_memory_alarm] routine is used to register
   814         - a callback on memory allocation events.
   815         - This routine registers or clears a callbacks that fires when
   816         - the amount of memory allocated exceeds iThreshold.  Only
   817         - a single callback can be registered at a time.  Each call
   818         - to [sqlite3_memory_alarm()] overwrites the previous callback.
   819         - The callback is disabled by setting xCallback to a NULL
   820         - pointer.
   821         -}
   822         -
   823         -PARAGRAPH {
   824         - The parameters to the callback are the pArg value, the 
   825         - amount of memory currently in use, and the size of the
   826         - allocation that provoked the callback.  The callback will
   827         - presumably invoke [sqlite3_free()] to free up memory space.
   828         - The callback may invoke [sqlite3_malloc()] or [sqlite3_realloc()]
   829         - but if it does, no additional callbacks will be invoked by
   830         - the recursive calls.
   831         -}
   832         -
   833         -PARAGRAPH {
   834         - The [sqlite3_soft_heap_limit()] interface works by registering
   835         - a memory alarm at the soft heap limit and invoking 
   836         - [sqlite3_release_memory()] in the alarm callback.  Application
   837         - programs should not attempt to use the [sqlite3_memory_alarm()]
   838         - interface because doing so will interfere with the
   839         - [sqlite3_soft_heap_limit()] module.  This interface is exposed
   840         - only so that applications can provide their own
   841         - alternative implementation when the SQLite core is
   842         - compiled with SQLITE_OMIT_MEMORY_ALLOCATION.
   843         -}
   844         -
   845         -PARAGRAPH {
   846         -  The built-in memory allocators in SQLite also provide the following
   847         -  additional interfaces:
   848         -}
   849         -
   850         -CODE {
   851         -sqlite3_int64 sqlite3_memory_used(void);
   852         -sqlite3_int64 sqlite3_memory_highwater(int resetFlag);
   853         -}
   854         -
   855         -PARAGRAPH {
   856         -  These interfaces can be used by an application to monitor how
   857         -  much memory SQLite is using.  The [sqlite3_memory_used()] routine
   858         -  returns the number of bytes of memory currently in use and the
   859         -  [sqlite3_memory_highwater()] returns the maximum instantaneous
   860         -  memory usage.  Neither routine includes the overhead associated
   861         -  with the memory allocator.  These routines are provided for use
   862         -  by the application.  SQLite never invokes them itself.  So if
   863         -  the application is providing its own memory allocation subsystem,
   864         -  it can omit these interfaces if desired.
   865         -}
   866         -
   867         -HEADING 1 {The Mutex Subsystem}
   868         -
   869         -PARAGRAPH {
   870         -  SQLite has always been threadsafe in the sense that it is safe to
   871         -  use different SQLite database connections in different threads at the
   872         -  same time.  The constraint was that the same database connection
   873         -  could not be used in two separate threads at once.  SQLite version 3.5.0
   874         -  relaxes this constraint. 
   875         -}
   876         -
   877         -PARAGRAPH {
   878         -  In order to allow multiple threads to use the same database connection
   879         -  at the same time, SQLite must make extensive use of mutexes.  And for
   880         -  this reason a new mutex subsystem as been added.  The mutex subsystem
   881         -  as the following interface:
   882         -}
   883         -
   884         -CODE {
   885         -sqlite3_mutex *sqlite3_mutex_alloc(int);
   886         -void sqlite3_mutex_free(sqlite3_mutex*);
   887         -void sqlite3_mutex_enter(sqlite3_mutex*);
   888         -int sqlite3_mutex_try(sqlite3_mutex*);
   889         -void sqlite3_mutex_leave(sqlite3_mutex*);
   890         -}
   891         -
   892         -PARAGRAPH {
   893         -  Though these routines exist for the use of the SQLite core, 
   894         -  application code is free to use these routines as well, if desired.
   895         -  A mutex is an [sqlite3_mutex] object.  The [sqlite3_mutex_alloc()]
   896         -  routine allocates a new mutex object and returns a pointer to it.
   897         -  The argument to [sqlite3_mutex_alloc()] should be 
   898         -  [SQLITE_MUTEX_FAST] or [SQLITE_MUTEX_RECURSIVE] for non-recursive
   899         -  and recursive mutexes, respectively.  If the underlying system does
   900         -  not provide non-recursive mutexes, then a recursive mutex can be
   901         -  substituted in that case.  The argument to [sqlite3_mutex_alloc()]
   902         -  can also be a constant designating one of several static mutexes:
   903         -  <ul>
   904         -  <li>  [SQLITE_MUTEX_STATIC_MASTER]
   905         -  <li>  [SQLITE_MUTEX_STATIC_MEM]
   906         -  <li>  [SQLITE_MUTEX_STATIC_MEM2]
   907         -  <li>  [SQLITE_MUTEX_STATIC_PRNG]
   908         -  <li>  [SQLITE_MUTEX_STATIC_LRU]
   909         -  </ul>
   910         -  These static mutexes are reserved for use internally by SQLite
   911         -  and should not be used by the application.  The static mutexes
   912         -  are all non-recursive.
   913         -}
   914         -
   915         -PARAGRAPH {
   916         -  The [sqlite3_mutex_free()] routine should be used to deallocate
   917         -  a non-static mutex.  If a static mutex is passed to this routine
   918         -  then the behavior is undefined.
   919         -}
   920         -
   921         -PARAGRAPH {
   922         -  The [sqlite3_mutex_enter()] attempts to enter the mutex and blocks
   923         -  if another threads is already there.  [sqlite3_mutex_try()] attempts
   924         -  to enter and returns [SQLITE_OK] on success or [SQLITE_BUSY] if another
   925         -  thread is already there.  [sqlite3_mutex_leave()] exits a mutex.
   926         -  The mutex is held until the number of exits matches the number of
   927         -  entrances.  If [sqlite3_mutex_leave()] is called on a mutex that 
   928         -  the thread is not currently holding, then the behavior is undefined.
   929         -  If any routine is called for a deallocated mutex, then the behavior
   930         -  is undefined.
   931         -}
   932         -
   933         -PARAGRAPH {
   934         -  The SQLite source code provides multiple implementations of these
   935         -  APIs, suitable for varying environments.  If SQLite is compiled with
   936         -  the SQLITE_THREADSAFE=0 flag then a no-op mutex implementation that 
   937         -  is fast but does no real mutual exclusion is provided.  That 
   938         -  implementation is suitable for use in single-threaded applications
   939         -  or applications that only use SQLite in a single thread.  Other
   940         -  real mutex implementations are provided based on the underlying
   941         -  operating system.
   942         -}
   943         -
   944         -PARAGRAPH {
   945         -  Embedded applications may wish to provide their own mutex implementation.
   946         -  If SQLite is compiled with the -DSQLITE_MUTEX_APPDEF=1 compile-time flag
   947         -  then the SQLite core provides no mutex subsystem and a mutex subsystem
   948         -  that matches the interface described above must be provided by the
   949         -  application that links against SQLite.
   950         -}
   951         -
   952         -HEADING 1 {Other Interface Changes}
   953         -
   954         -PARAGRAPH {
   955         -  Version 3.5.0 of SQLite changes the behavior of a few APIs in ways
   956         -  that are technically incompatible.  However, these APIs are seldom
   957         -  used and even when they are used it is difficult to imagine a
   958         -  scenario where the change might break something.  The changes
   959         -  actually makes these interface much more useful and powerful.
   960         -}
   961         -
   962         -PARAGRAPH {
   963         -  Prior to version 3.5.0, the [sqlite3_enable_shared_cache()] API
   964         -  would enable and disable the shared cache feature for all connections
   965         -  within a single thread - the same thread from which the 
   966         -  sqlite3_enable_shared_cache() routine was called.  Database connections
   967         -  that used the shared cache were restricted to running in the same
   968         -  thread in which they were opened.  Beginning with version 3.5.0,
   969         -  the sqlite3_enable_shared_cache() applies to all database connections
   970         -  in all threads within the process.  Now database connections running
   971         -  in separate threads can share a cache.  And database connections that
   972         -  use shared cache can migrate from one thread to another.
   973         -}
   974         -
   975         -PARAGRAPH {
   976         -  Prior to version 3.5.0 the [sqlite3_soft_heap_limit()] set an upper
   977         -  bound on heap memory usage for all database connections within a
   978         -  single thread.  Each thread could have its own heap limit.  Beginning
   979         -  in version 3.5.0, there is a single heap limit for the entire process.
   980         -  This seems more restrictive (one limit as opposed to many) but in
   981         -  practice it is what most users want.
   982         -}
   983         -
   984         -PARAGRAPH {
   985         -  Prior to version 3.5.0 the [sqlite3_release_memory()] function would
   986         -  try to reclaim memory from all database connections in the same thread
   987         -  as the sqlite3_release_memory() call.  Beginning with version 3.5.0,
   988         -  the sqlite3_release_memory() function will attempt to reclaim memory
   989         -  from all database connections in all threads.
   990         -}
   991         -
   992         -HEADING 1 {Summary}
   993         -
   994         -PARAGRAPH {
   995         -  The transition from SQLite version 3.4.2 to 3.5.0 is a major change.
   996         -  Every source code file in the SQLite core had to be modified, some
   997         -  extensively.  And the change introduced some minor incompatibilities
   998         -  in the C interface.  But we feel that the benefits of the transition
   999         -  from 3.4.2 to 3.5.0 far outweigh the pain of porting.  The new
  1000         -  VFS layer is now well-defined and stable and should simplify future
  1001         -  customizations.  The VFS layer, and the separable memory allocator
  1002         -  and mutex subsystems allow a standard SQLite source code amalgamation
  1003         -  to be used in an embedded project without change, greatly simplifying
  1004         -  configuration management.  And the resulting system is much more
  1005         -  tolerant of highly threaded designs.
  1006         -}

Deleted www/arch.fig.

     1         -#FIG 3.2
     2         -Portrait
     3         -Center
     4         -Inches
     5         -Letter  
     6         -100.00
     7         -Single
     8         --2
     9         -1200 2
    10         -2 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2
    11         -	1 1 3.00 75.00 135.00
    12         -	 3675 8550 3675 9075
    13         -2 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2
    14         -	1 1 3.00 75.00 135.00
    15         -	 3675 7200 3675 7725
    16         -2 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2
    17         -	1 1 3.00 75.00 135.00
    18         -	 3675 5775 3675 6300
    19         -2 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2
    20         -	1 1 3.00 75.00 135.00
    21         -	 3675 3975 3675 4500
    22         -2 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2
    23         -	1 1 3.00 75.00 135.00
    24         -	 3675 2625 3675 3150
    25         -2 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2
    26         -	1 1 3.00 75.00 135.00
    27         -	 3675 1275 3675 1800
    28         -2 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2
    29         -	1 1 3.00 75.00 135.00
    30         -	 3675 9900 3675 10425
    31         -2 2 0 1 0 11 100 0 20 0.000 0 0 7 0 0 5
    32         -	 2550 10425 4875 10425 4875 11250 2550 11250 2550 10425
    33         -2 2 0 1 0 11 100 0 20 0.000 0 0 7 0 0 5
    34         -	 2550 9075 4875 9075 4875 9900 2550 9900 2550 9075
    35         -2 2 0 1 0 11 100 0 20 0.000 0 0 7 0 0 5
    36         -	 2550 7725 4875 7725 4875 8550 2550 8550 2550 7725
    37         -2 2 0 1 0 11 100 0 20 0.000 0 0 7 0 0 5
    38         -	 2550 6300 4875 6300 4875 7200 2550 7200 2550 6300
    39         -2 2 0 1 0 11 100 0 20 0.000 0 0 7 0 0 5
    40         -	 2550 4500 4875 4500 4875 5775 2550 5775 2550 4500
    41         -2 2 0 1 0 11 100 0 20 0.000 0 0 7 0 0 5
    42         -	 2550 3150 4875 3150 4875 3975 2550 3975 2550 3150
    43         -2 2 0 1 0 11 100 0 20 0.000 0 0 7 0 0 5
    44         -	 2550 1800 4875 1800 4875 2625 2550 2625 2550 1800
    45         -2 2 0 1 0 11 100 0 20 0.000 0 0 7 0 0 5
    46         -	 2550 450 4875 450 4875 1275 2550 1275 2550 450
    47         -4 1 0 100 0 0 20 0.0000 4 195 1020 3675 750 Interface\001
    48         -4 1 0 100 0 0 14 0.0000 4 195 2040 3675 1125 main.c table.c tclsqlite.c\001
    49         -4 1 0 100 0 0 20 0.0000 4 195 1920 3675 6675 Virtual Machine\001
    50         -4 1 0 100 0 0 14 0.0000 4 150 570 3675 7050 vdbe.c\001
    51         -4 1 0 100 0 0 20 0.0000 4 195 1830 3675 4875 Code Generator\001
    52         -4 1 0 100 0 0 14 0.0000 4 195 1860 3675 5175 build.c delete.c expr.c\001
    53         -4 1 0 100 0 0 14 0.0000 4 195 2115 3675 5400 insert.c select.c update.c\001
    54         -4 1 0 100 0 0 14 0.0000 4 150 705 3675 5625 where.c\001
    55         -4 1 0 100 0 0 20 0.0000 4 195 735 3675 3450 Parser\001
    56         -4 1 0 100 0 0 20 0.0000 4 195 1140 3675 2100 Tokenizer\001
    57         -4 1 0 100 0 0 14 0.0000 4 150 870 3675 2475 tokenize.c\001
    58         -4 1 0 100 0 0 20 0.0000 4 255 1350 3675 9375 Page Cache\001
    59         -4 1 0 100 0 0 14 0.0000 4 150 630 3675 3825 parse.y\001
    60         -4 1 0 100 0 0 14 0.0000 4 150 600 3675 8400 btree.c\001
    61         -4 1 0 100 0 0 14 0.0000 4 150 645 3675 9750 pager.c\001
    62         -4 1 0 100 0 0 20 0.0000 4 195 1620 3675 8025 B-tree Driver\001
    63         -4 1 0 100 0 0 14 0.0000 4 105 345 3675 11100 os.c\001
    64         -4 1 0 100 0 0 20 0.0000 4 195 1470 3675 10725 OS Interface\001

Deleted www/arch.gif.

cannot compute difference between binary files

Deleted www/arch.png.

cannot compute difference between binary files

Deleted www/arch.tcl.

     1         -#
     2         -# Run this Tcl script to generate the sqlite.html file.
     3         -#
     4         -set rcsid {$Id: arch.tcl,v 1.16 2004/10/10 17:24:54 drh Exp $}
     5         -source common.tcl
     6         -header {Architecture of SQLite}
     7         -puts {
     8         -<h2>The Architecture Of SQLite</h2>
     9         -
    10         -<h3>Introduction</h3>
    11         -
    12         -<table align="right" border="1" cellpadding="15" cellspacing="1">
    13         -<tr><th>Block Diagram Of SQLite</th></tr>
    14         -<tr><td><img src="arch2.gif"></td></tr>
    15         -</table>
    16         -<p>This document describes the architecture of the SQLite library.
    17         -The information here is useful to those who want to understand or
    18         -modify the inner workings of SQLite.
    19         -</p>
    20         -
    21         -<p>
    22         -A block diagram showing the main components of SQLite
    23         -and how they interrelate is shown at the right.  The text that
    24         -follows will provide a quick overview of each of these components.
    25         -</p>
    26         -
    27         -
    28         -<p>
    29         -This document describes SQLite version 3.0.  Version 2.8 and
    30         -earlier are similar but the details differ.
    31         -</p>
    32         -
    33         -<h3>Interface</h3>
    34         -
    35         -<p>Much of the public interface to the SQLite library is implemented by
    36         -functions found in the <b>main.c</b>, <b>legacy.c</b>, and
    37         -<b>vdbeapi.c</b> source files
    38         -though some routines are
    39         -scattered about in other files where they can have access to data 
    40         -structures with file scope.  The
    41         -<b>sqlite3_get_table()</b> routine is implemented in <b>table.c</b>.
    42         -<b>sqlite3_mprintf()</b> is found in <b>printf.c</b>.
    43         -<b>sqlite3_complete()</b> is in <b>tokenize.c</b>.
    44         -The Tcl interface is implemented by <b>tclsqlite.c</b>.  More
    45         -information on the C interface to SQLite is
    46         -<a href="capi3ref.html">available separately</a>.<p>
    47         -
    48         -<p>To avoid name collisions with other software, all external
    49         -symbols in the SQLite library begin with the prefix <b>sqlite3</b>.
    50         -Those symbols that are intended for external use (in other words,
    51         -those symbols which form the API for SQLite) begin
    52         -with <b>sqlite3_</b>.</p>
    53         -
    54         -<h3>Tokenizer</h3>
    55         -
    56         -<p>When a string containing SQL statements is to be executed, the
    57         -interface passes that string to the tokenizer.  The job of the tokenizer
    58         -is to break the original string up into tokens and pass those tokens
    59         -one by one to the parser.  The tokenizer is hand-coded in C in 
    60         -the file <b>tokenize.c</b>.
    61         -
    62         -<p>Note that in this design, the tokenizer calls the parser.  People
    63         -who are familiar with YACC and BISON may be used to doing things the
    64         -other way around -- having the parser call the tokenizer.  The author
    65         -of SQLite 
    66         -has done it both ways and finds things generally work out nicer for
    67         -the tokenizer to call the parser.  YACC has it backwards.</p>
    68         -
    69         -<h3>Parser</h3>
    70         -
    71         -<p>The parser is the piece that assigns meaning to tokens based on
    72         -their context.  The parser for SQLite is generated using the
    73         -<a href="http://www.hwaci.com/sw/lemon/">Lemon</a> LALR(1) parser
    74         -generator.  Lemon does the same job as YACC/BISON, but it uses
    75         -a different input syntax which is less error-prone.
    76         -Lemon also generates a parser which is reentrant and thread-safe.
    77         -And lemon defines the concept of a non-terminal destructor so
    78         -that it does not leak memory when syntax errors are encountered.
    79         -The source file that drives Lemon is found in <b>parse.y</b>.</p>
    80         -
    81         -<p>Because
    82         -lemon is a program not normally found on development machines, the
    83         -complete source code to lemon (just one C file) is included in the
    84         -SQLite distribution in the "tool" subdirectory.  Documentation on
    85         -lemon is found in the "doc" subdirectory of the distribution.
    86         -</p>
    87         -
    88         -<h3>Code Generator</h3>
    89         -
    90         -<p>After the parser assembles tokens into complete SQL statements,
    91         -it calls the code generator to produce virtual machine code that
    92         -will do the work that the SQL statements request.  There are many
    93         -files in the code generator:
    94         -<b>attach.c</b>,
    95         -<b>auth.c</b>,
    96         -<b>build.c</b>,
    97         -<b>delete.c</b>,
    98         -<b>expr.c</b>,
    99         -<b>insert.c</b>,
   100         -<b>pragma.c</b>,
   101         -<b>select.c</b>,
   102         -<b>trigger.c</b>,
   103         -<b>update.c</b>,
   104         -<b>vacuum.c</b>
   105         -and <b>where.c</b>.
   106         -In these files is where most of the serious magic happens.
   107         -<b>expr.c</b> handles code generation for expressions.
   108         -<b>where.c</b> handles code generation for WHERE clauses on
   109         -SELECT, UPDATE and DELETE statements.  The files <b>attach.c</b>,
   110         -<b>delete.c</b>, <b>insert.c</b>, <b>select.c</b>, <b>trigger.c</b>
   111         -<b>update.c</b>, and <b>vacuum.c</b> handle the code generation
   112         -for SQL statements with the same names.  (Each of these files calls routines
   113         -in <b>expr.c</b> and <b>where.c</b> as necessary.)  All other
   114         -SQL statements are coded out of <b>build.c</b>.
   115         -The <b>auth.c</b> file implements the functionality of
   116         -<b>sqlite3_set_authorizer()</b>.</p>
   117         -
   118         -<h3>Virtual Machine</h3>
   119         -
   120         -<p>The program generated by the code generator is executed by
   121         -the virtual machine.  Additional information about the virtual
   122         -machine is <a href="opcode.html">available separately</a>.
   123         -To summarize, the virtual machine implements an abstract computing
   124         -engine specifically designed to manipulate database files.  The
   125         -machine has a stack which is used for intermediate storage.
   126         -Each instruction contains an opcode and
   127         -up to three additional operands.</p>
   128         -
   129         -<p>The virtual machine itself is entirely contained in a single
   130         -source file <b>vdbe.c</b>.  The virtual machine also has
   131         -its own header files: <b>vdbe.h</b> that defines an interface
   132         -between the virtual machine and the rest of the SQLite library and
   133         -<b>vdbeInt.h</b> which defines structure private the virtual machine.
   134         -The <b>vdbeaux.c</b> file contains utilities used by the virtual
   135         -machine and interface modules used by the rest of the library to
   136         -construct VM programs.  The <b>vdbeapi.c</b> file contains external
   137         -interfaces to the virtual machine such as the 
   138         -<b>sqlite3_bind_...</b> family of functions.  Individual values
   139         -(strings, integer, floating point numbers, and BLOBs) are stored
   140         -in an internal object named "Mem" which is implemented by
   141         -<b>vdbemem.c</b>.</p>
   142         -
   143         -<p>
   144         -SQLite implements SQL functions using callbacks to C-language routines.
   145         -Even the built-in SQL functions are implemented this way.  Most of
   146         -the built-in SQL functions (ex: <b>coalesce()</b>, <b>count()</b>,
   147         -<b>substr()</b>, and so forth) can be found in <b>func.c</b>.
   148         -Date and time conversion functions are found in <b>date.c</b>.
   149         -</p>
   150         -
   151         -<h3>B-Tree</h3>
   152         -
   153         -<p>An SQLite database is maintained on disk using a B-tree implementation
   154         -found in the <b>btree.c</b> source file.  A separate B-tree is used for
   155         -each table and index in the database.  All B-trees are stored in the
   156         -same disk file.  Details of the file format are recorded in a large
   157         -comment at the beginning of <b>btree.c</b>.</p>
   158         -
   159         -<p>The interface to the B-tree subsystem is defined by the header file
   160         -<b>btree.h</b>.
   161         -</p>
   162         -
   163         -<h3>Page Cache</h3>
   164         -
   165         -<p>The B-tree module requests information from the disk in fixed-size
   166         -chunks.  The default chunk size is 1024 bytes but can vary between 512
   167         -and 65536 bytes.
   168         -The page cache is responsible for reading, writing, and
   169         -caching these chunks.
   170         -The page cache also provides the rollback and atomic commit abstraction
   171         -and takes care of locking of the database file.  The
   172         -B-tree driver requests particular pages from the page cache and notifies
   173         -the page cache when it wants to modify pages or commit or rollback
   174         -changes and the page cache handles all the messy details of making sure
   175         -the requests are handled quickly, safely, and efficiently.</p>
   176         -
   177         -<p>The code to implement the page cache is contained in the single C
   178         -source file <b>pager.c</b>.  The interface to the page cache subsystem
   179         -is defined by the header file <b>pager.h</b>.
   180         -</p>
   181         -
   182         -<h3>OS Interface</h3>
   183         -
   184         -<p>
   185         -In order to provide portability between POSIX and Win32 operating systems,
   186         -SQLite uses an abstraction layer to interface with the operating system.
   187         -The interface to the OS abstraction layer is defined in
   188         -<b>os.h</b>.  Each supported operating system has its own implementation:
   189         -<b>os_unix.c</b> for Unix, <b>os_win.c</b> for windows, and so forth.
   190         -Each of these operating-specific implements typically has its own
   191         -header file: <b>os_unix.h</b>, <b>os_win.h</b>, etc.
   192         -</p>
   193         -
   194         -<h3>Utilities</h3>
   195         -
   196         -<p>
   197         -Memory allocation and caseless string comparison routines are located
   198         -in <b>util.c</b>.
   199         -Symbol tables used by the parser are maintained by hash tables found
   200         -in <b>hash.c</b>.  The <b>utf.c</b> source file contains Unicode
   201         -conversion subroutines.
   202         -SQLite has its own private implementation of <b>printf()</b> (with
   203         -some extensions) in <b>printf.c</b> and its own random number generator
   204         -in <b>random.c</b>.
   205         -</p>
   206         -
   207         -<h3>Test Code</h3>
   208         -
   209         -<p>
   210         -If you count regression test scripts,
   211         -more than half the total code base of SQLite is devoted to testing.
   212         -There are many <b>assert()</b> statements in the main code files.
   213         -In additional, the source files <b>test1.c</b> through <b>test5.c</b>
   214         -together with <b>md5.c</b> implement extensions used for testing
   215         -purposes only.  The <b>os_test.c</b> backend interface is used to
   216         -simulate power failures to verify the crash-recovery mechanism in
   217         -the pager.
   218         -</p>
   219         -
   220         -}
   221         -footer $rcsid

Deleted www/arch2.fig.

     1         -#FIG 3.2
     2         -Landscape
     3         -Center
     4         -Inches
     5         -Letter  
     6         -100.00
     7         -Single
     8         --2
     9         -1200 2
    10         -0 32 #000000
    11         -0 33 #868686
    12         -0 34 #dfefd7
    13         -0 35 #d7efef
    14         -0 36 #efdbef
    15         -0 37 #efdbd7
    16         -0 38 #e7efcf
    17         -0 39 #9e9e9e
    18         -6 3225 3900 4650 6000
    19         -2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
    20         -	 3225 5475 4575 5475 4575 5925 3225 5925 3225 5475
    21         -2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
    22         -	 3300 5550 4650 5550 4650 6000 3300 6000 3300 5550
    23         -2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
    24         -	 3225 4650 4575 4650 4575 5100 3225 5100 3225 4650
    25         -2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
    26         -	 3300 4725 4650 4725 4650 5175 3300 5175 3300 4725
    27         -2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
    28         -	 3225 3900 4575 3900 4575 4350 3225 4350 3225 3900
    29         -2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
    30         -	 3300 3975 4650 3975 4650 4425 3300 4425 3300 3975
    31         -2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
    32         -	1 1 1.00 60.00 120.00
    33         -	 3900 4350 3900 4650
    34         -2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
    35         -	1 1 1.00 60.00 120.00
    36         -	 3900 5100 3900 5475
    37         -4 1 0 50 0 2 12 0.0000 4 135 1050 3900 5775 OS Interface\001
    38         -4 1 0 50 0 2 12 0.0000 4 135 615 3900 4200 B-Tree\001
    39         -4 1 0 50 0 2 12 0.0000 4 180 495 3900 4950 Pager\001
    40         --6
    41         -6 5400 4725 6825 5250
    42         -2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
    43         -	 5400 4725 6750 4725 6750 5175 5400 5175 5400 4725
    44         -2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
    45         -	 5475 4800 6825 4800 6825 5250 5475 5250 5475 4800
    46         -4 1 0 50 0 2 12 0.0000 4 135 630 6000 5025 Utilities\001
    47         --6
    48         -6 5400 5550 6825 6075
    49         -2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
    50         -	 5400 5550 6750 5550 6750 6000 5400 6000 5400 5550
    51         -2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
    52         -	 5475 5625 6825 5625 6825 6075 5475 6075 5475 5625
    53         -4 1 0 50 0 2 12 0.0000 4 135 855 6000 5850 Test Code\001
    54         --6
    55         -6 5400 2775 6825 3750
    56         -2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
    57         -	 5475 2850 6825 2850 6825 3750 5475 3750 5475 2850
    58         -2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
    59         -	 5400 2775 6750 2775 6750 3675 5400 3675 5400 2775
    60         -4 1 0 50 0 2 12 0.0000 4 135 420 6075 3150 Code\001
    61         -4 1 0 50 0 2 12 0.0000 4 135 855 6075 3375 Generator\001
    62         --6
    63         -6 5400 1950 6825 2475
    64         -2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
    65         -	 5400 1950 6750 1950 6750 2400 5400 2400 5400 1950
    66         -2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
    67         -	 5475 2025 6825 2025 6825 2475 5475 2475 5475 2025
    68         -4 1 0 50 0 2 12 0.0000 4 135 570 6075 2250 Parser\001
    69         --6
    70         -2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
    71         -	 5400 1050 6750 1050 6750 1500 5400 1500 5400 1050
    72         -2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
    73         -	 5475 1125 6825 1125 6825 1575 5475 1575 5475 1125
    74         -2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
    75         -	 3225 1050 4575 1050 4575 1500 3225 1500 3225 1050
    76         -2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
    77         -	 3300 1125 4650 1125 4650 1575 3300 1575 3300 1125
    78         -2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
    79         -	 3225 1800 4575 1800 4575 2250 3225 2250 3225 1800
    80         -2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
    81         -	 3300 1875 4650 1875 4650 2325 3300 2325 3300 1875
    82         -2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
    83         -	 3225 2550 4575 2550 4575 3000 3225 3000 3225 2550
    84         -2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
    85         -	 3300 2625 4650 2625 4650 3075 3300 3075 3300 2625
    86         -2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
    87         -	1 1 1.00 60.00 120.00
    88         -	 3900 1500 3900 1800
    89         -2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
    90         -	1 1 1.00 60.00 120.00
    91         -	 3900 2250 3900 2550
    92         -2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
    93         -	1 1 1.00 60.00 120.00
    94         -	 3900 3000 3900 3900
    95         -2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
    96         -	1 1 1.00 60.00 120.00
    97         -	 4575 1950 5400 1350
    98         -2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
    99         -	1 1 1.00 60.00 120.00
   100         -	 5400 2925 4650 2325
   101         -2 2 0 1 0 34 55 0 20 0.000 0 0 -1 0 0 5
   102         -	 2850 750 4875 750 4875 3375 2850 3375 2850 750
   103         -2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
   104         -	1 1 1.00 60.00 120.00
   105         -	 6075 1500 6075 1950
   106         -2 3 0 1 0 35 55 0 20 0.000 0 0 -1 0 0 5
   107         -	 2850 3675 4875 3675 4875 6225 2850 6225 2850 3675
   108         -2 2 0 1 0 37 55 0 20 0.000 0 0 -1 0 0 5
   109         -	 5175 750 7200 750 7200 4050 5175 4050 5175 750
   110         -2 2 0 1 0 38 55 0 20 0.000 0 0 -1 0 0 5
   111         -	 5175 4425 7200 4425 7200 6225 5175 6225 5175 4425
   112         -2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
   113         -	1 1 1.00 60.00 120.00
   114         -	 6075 2475 6075 2775
   115         -4 1 0 50 0 2 12 0.0000 4 135 855 6075 1350 Tokenizer\001
   116         -4 1 0 50 0 1 12 1.5708 4 180 1020 7125 2250 SQL Compiler\001
   117         -4 1 0 50 0 1 12 1.5708 4 135 345 3075 2025 Core\001
   118         -4 1 0 50 0 2 12 0.0000 4 135 1290 3900 2850 Virtual Machine\001
   119         -4 1 0 50 0 2 12 0.0000 4 165 1185 3900 1995 SQL Command\001
   120         -4 1 0 50 0 2 12 0.0000 4 135 855 3900 2183 Processor\001
   121         -4 1 0 50 0 2 14 0.0000 4 150 870 3900 1350 Interface\001
   122         -4 1 0 50 0 1 12 1.5708 4 135 885 7125 5400 Accessories\001
   123         -4 1 0 50 0 1 12 1.5708 4 135 645 3075 4875 Backend\001

Deleted www/arch2.gif.

cannot compute difference between binary files

Deleted www/arch2b.fig.

     1         -#FIG 3.2
     2         -Landscape
     3         -Center
     4         -Inches
     5         -Letter  
     6         -100.00
     7         -Single
     8         --2
     9         -1200 2
    10         -0 32 #000000
    11         -0 33 #868686
    12         -0 34 #dfefd7
    13         -0 35 #d7efef
    14         -0 36 #efdbef
    15         -0 37 #efdbd7
    16         -0 38 #e7efcf
    17         -0 39 #9e9e9e
    18         -6 3225 3900 4650 6000
    19         -2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
    20         -	 3225 5475 4575 5475 4575 5925 3225 5925 3225 5475
    21         -2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
    22         -	 3300 5550 4650 5550 4650 6000 3300 6000 3300 5550
    23         -2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
    24         -	 3225 4650 4575 4650 4575 5100 3225 5100 3225 4650
    25         -2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
    26         -	 3300 4725 4650 4725 4650 5175 3300 5175 3300 4725
    27         -2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
    28         -	 3225 3900 4575 3900 4575 4350 3225 4350 3225 3900
    29         -2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
    30         -	 3300 3975 4650 3975 4650 4425 3300 4425 3300 3975
    31         -2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
    32         -	1 1 1.00 60.00 120.00
    33         -	 3900 4350 3900 4650
    34         -2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
    35         -	1 1 1.00 60.00 120.00
    36         -	 3900 5100 3900 5475
    37         -4 1 0 50 0 2 12 0.0000 4 135 1050 3900 5775 OS Interface\001
    38         -4 1 0 50 0 2 12 0.0000 4 135 615 3900 4200 B-Tree\001
    39         -4 1 0 50 0 2 12 0.0000 4 180 495 3900 4950 Pager\001
    40         --6
    41         -6 5175 4275 7200 6150
    42         -6 5400 4519 6825 5090
    43         -2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
    44         -	 5400 4519 6750 4519 6750 5009 5400 5009 5400 4519
    45         -2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
    46         -	 5475 4601 6825 4601 6825 5090 5475 5090 5475 4601
    47         -4 1 0 50 0 2 12 0.0000 4 135 630 6000 4845 Utilities\001
    48         --6
    49         -6 5400 5416 6825 5987
    50         -2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
    51         -	 5400 5416 6750 5416 6750 5906 5400 5906 5400 5416
    52         -2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
    53         -	 5475 5498 6825 5498 6825 5987 5475 5987 5475 5498
    54         -4 1 0 50 0 2 12 0.0000 4 135 855 6000 5742 Test Code\001
    55         --6
    56         -2 2 0 1 0 38 55 0 20 0.000 0 0 -1 0 0 5
    57         -	 5175 4275 7200 4275 7200 6150 5175 6150 5175 4275
    58         -4 1 0 50 0 1 12 1.5708 4 135 885 7125 5253 Accessories\001
    59         --6
    60         -6 5400 2700 6825 3675
    61         -2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
    62         -	 5475 2775 6825 2775 6825 3675 5475 3675 5475 2775
    63         -2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
    64         -	 5400 2700 6750 2700 6750 3600 5400 3600 5400 2700
    65         -4 1 0 50 0 2 12 0.0000 4 135 420 6075 3075 Code\001
    66         -4 1 0 50 0 2 12 0.0000 4 135 855 6075 3300 Generator\001
    67         --6
    68         -6 5400 1875 6825 2400
    69         -2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
    70         -	 5400 1875 6750 1875 6750 2325 5400 2325 5400 1875
    71         -2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
    72         -	 5475 1950 6825 1950 6825 2400 5475 2400 5475 1950
    73         -4 1 0 50 0 2 12 0.0000 4 135 570 6075 2175 Parser\001
    74         --6
    75         -2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
    76         -	 5400 1050 6750 1050 6750 1500 5400 1500 5400 1050
    77         -2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
    78         -	 5475 1125 6825 1125 6825 1575 5475 1575 5475 1125
    79         -2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
    80         -	 3225 1050 4575 1050 4575 1500 3225 1500 3225 1050
    81         -2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
    82         -	 3300 1125 4650 1125 4650 1575 3300 1575 3300 1125
    83         -2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
    84         -	 3225 1800 4575 1800 4575 2250 3225 2250 3225 1800
    85         -2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
    86         -	 3300 1875 4650 1875 4650 2325 3300 2325 3300 1875
    87         -2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5
    88         -	 3225 2550 4575 2550 4575 3000 3225 3000 3225 2550
    89         -2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5
    90         -	 3300 2625 4650 2625 4650 3075 3300 3075 3300 2625
    91         -2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
    92         -	1 1 1.00 60.00 120.00
    93         -	 3900 1500 3900 1800
    94         -2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
    95         -	1 1 1.00 60.00 120.00
    96         -	 3900 2250 3900 2550
    97         -2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
    98         -	1 1 1.00 60.00 120.00
    99         -	 3900 3000 3900 3900
   100         -2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
   101         -	1 1 1.00 60.00 120.00
   102         -	 4575 1950 5400 1350
   103         -2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
   104         -	1 1 1.00 60.00 120.00
   105         -	 5400 2925 4650 2175
   106         -2 2 0 1 0 34 55 0 20 0.000 0 0 -1 0 0 5
   107         -	 2850 750 4875 750 4875 3375 2850 3375 2850 750
   108         -2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
   109         -	1 1 1.00 60.00 120.00
   110         -	 6075 1500 6075 1800
   111         -2 3 0 1 0 35 55 0 20 0.000 0 0 -1 0 0 5
   112         -	 2850 3675 4875 3675 4875 6150 2850 6150 2850 3675
   113         -2 2 0 1 0 37 55 0 20 0.000 0 0 -1 0 0 5
   114         -	 5175 750 7200 750 7200 3975 5175 3975 5175 750
   115         -2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2
   116         -	1 1 1.00 60.00 120.00
   117         -	 6075 2400 6075 2700
   118         -4 1 0 50 0 2 12 0.0000 4 135 855 6075 1350 Tokenizer\001
   119         -4 1 0 50 0 1 12 1.5708 4 180 1020 7125 2250 SQL Compiler\001
   120         -4 1 0 50 0 1 12 1.5708 4 135 345 3075 2025 Core\001
   121         -4 1 0 50 0 2 12 0.0000 4 135 1290 3900 2850 Virtual Machine\001
   122         -4 1 0 50 0 2 12 0.0000 4 165 1185 3900 1995 SQL Command\001
   123         -4 1 0 50 0 2 12 0.0000 4 135 855 3900 2183 Processor\001
   124         -4 1 0 50 0 2 14 0.0000 4 150 870 3900 1350 Interface\001
   125         -4 1 0 50 0 1 12 1.5708 4 135 645 3075 4875 Backend\001

Deleted www/audit.tcl.

     1         -#
     2         -# Run this Tcl script to generate the audit.html file.
     3         -#
     4         -set rcsid {$Id: audit.tcl,v 1.1 2002/07/13 16:52:35 drh Exp $}
     5         -
     6         -puts {<html>
     7         -<head>
     8         -  <title>SQLite Security Audit Procedure</title>
     9         -</head>
    10         -<body bgcolor=white>
    11         -<h1 align=center>
    12         -SQLite Security Audit Procedure
    13         -</h1>}
    14         -puts "<p align=center>
    15         -(This page was last modified on [lrange $rcsid 3 4] UTC)
    16         -</p>"
    17         -
    18         -puts {
    19         -<p>
    20         -A security audit for SQLite consists of two components.  First, there is
    21         -a check for common errors that often lead to security problems.  Second,
    22         -an attempt is made to construct a proof that SQLite has certain desirable
    23         -security properties.
    24         -</p>
    25         -
    26         -<h2>Part I: Things to check</h2>
    27         -
    28         -<p>
    29         -Scan all source code and check for the following common errors:
    30         -</p>
    31         -
    32         -<ol>
    33         -<li><p>
    34         -Verify that the destination buffer is large enough to hold its result
    35         -in every call to the following routines:
    36         -<ul>
    37         -<li> <b>strcpy()</b> </li>
    38         -<li> <b>strncpy()</b> </li>
    39         -<li> <b>strcat()</b> </li>
    40         -<li> <b>memcpy()</b> </li>
    41         -<li> <b>memset()</b> </li>
    42         -<li> <b>memmove()</b> </li>
    43         -<li> <b>bcopy()</b> </li>
    44         -<li> <b>sprintf()</b> </li>
    45         -<li> <b>scanf()</b> </li>
    46         -</ul>
    47         -</p></li>
    48         -<li><p>
    49         -Verify that pointers returned by subroutines are not NULL before using
    50         -the pointers.  In particular, make sure the return values for the following
    51         -routines are checked before they are used:
    52         -<ul>
    53         -<li> <b>malloc()</b> </li>
    54         -<li> <b>realloc()</b> </li>
    55         -<li> <b>sqliteMalloc()</b> </li>
    56         -<li> <b>sqliteRealloc()</b> </li>
    57         -<li> <b>sqliteStrDup()</b> </li>
    58         -<li> <b>sqliteStrNDup()</b> </li>
    59         -<li> <b>sqliteExpr()</b> </li>
    60         -<li> <b>sqliteExprFunction()</b> </li>
    61         -<li> <b>sqliteExprListAppend()</b> </li>
    62         -<li> <b>sqliteResultSetOfSelect()</b> </li>
    63         -<li> <b>sqliteIdListAppend()</b> </li>
    64         -<li> <b>sqliteSrcListAppend()</b> </li>
    65         -<li> <b>sqliteSelectNew()</b> </li>
    66         -<li> <b>sqliteTableNameToTable()</b> </li>
    67         -<li> <b>sqliteTableTokenToSrcList()</b> </li>
    68         -<li> <b>sqliteWhereBegin()</b> </li>
    69         -<li> <b>sqliteFindTable()</b> </li>
    70         -<li> <b>sqliteFindIndex()</b> </li>
    71         -<li> <b>sqliteTableNameFromToken()</b> </li>
    72         -<li> <b>sqliteGetVdbe()</b> </li>
    73         -<li> <b>sqlite_mprintf()</b> </li>
    74         -<li> <b>sqliteExprDup()</b> </li>
    75         -<li> <b>sqliteExprListDup()</b> </li>
    76         -<li> <b>sqliteSrcListDup()</b> </li>
    77         -<li> <b>sqliteIdListDup()</b> </li>
    78         -<li> <b>sqliteSelectDup()</b> </li>
    79         -<li> <b>sqliteFindFunction()</b> </li>
    80         -<li> <b>sqliteTriggerSelectStep()</b> </li>
    81         -<li> <b>sqliteTriggerInsertStep()</b> </li>
    82         -<li> <b>sqliteTriggerUpdateStep()</b> </li>
    83         -<li> <b>sqliteTriggerDeleteStep()</b> </li>
    84         -</ul>
    85         -</p></li>
    86         -<li><p>
    87         -On all functions and procedures, verify that pointer parameters are not NULL
    88         -before dereferencing those parameters.
    89         -</p></li>
    90         -<li><p>
    91         -Check to make sure that temporary files are opened safely: that the process
    92         -will not overwrite an existing file when opening the temp file and that
    93         -another process is unable to substitute a file for the temp file being
    94         -opened.
    95         -</p></li>
    96         -</ol>
    97         -
    98         -
    99         -
   100         -<h2>Part II: Things to prove</h2>
   101         -
   102         -<p>
   103         -Prove that SQLite exhibits the characteristics outlined below:
   104         -</p>
   105         -
   106         -<ol>
   107         -<li><p>
   108         -The following are preconditions:</p>
   109         -<p><ul>
   110         -<li><b>Z</b> is an arbitrary-length NUL-terminated string.</li>
   111         -<li>An existing SQLite database has been opened.  The return value
   112         -    from the call to <b>sqlite_open()</b> is stored in the variable
   113         -    <b>db</b>.</li>
   114         -<li>The database contains at least one table of the form:
   115         -<blockquote><pre>
   116         -CREATE TABLE t1(a CLOB);
   117         -</pre></blockquote></li>
   118         -<li>There are no user-defined functions other than the standard
   119         -    build-in functions.</li>
   120         -</ul></p>
   121         -<p>The following statement of C code is executed:</p>
   122         -<blockquote><pre>
   123         -sqlite_exec_printf(
   124         -   db,
   125         -   "INSERT INTO t1(a) VALUES('%q');", 
   126         -   0, 0, 0, Z
   127         -);
   128         -</pre></blockquote>
   129         -<p>Prove the following are true for all possible values of string <b>Z</b>:</p>
   130         -<ol type="a">
   131         -<li><p>
   132         -The call to <b>sqlite_exec_printf()</b> will
   133         -return in a length of time that is a polynomial in <b>strlen(Z)</b>.
   134         -It might return an error code but it will not crash.
   135         -</p></li>
   136         -<li><p>
   137         -At most one new row will be inserted into table t1.
   138         -</p></li>
   139         -<li><p>
   140         -No preexisting rows of t1 will be deleted or modified.
   141         -</p></li>
   142         -<li><p>
   143         -No tables other than t1 will be altered in any way.
   144         -</p></li>
   145         -<li><p>
   146         -No preexisting files on the host computers filesystem, other than
   147         -the database file itself, will be deleted or modified.
   148         -</p></li>
   149         -<li><p>
   150         -For some constants <b>K1</b> and <b>K2</b>,
   151         -if at least <b>K1*strlen(Z) + K2</b> bytes of contiguous memory are
   152         -available to <b>malloc()</b>, then the call to <b>sqlite_exec_printf()</b>
   153         -will not return SQLITE_NOMEM.
   154         -</p></li>
   155         -</ol>
   156         -</p></li>
   157         -
   158         -
   159         -<li><p>
   160         -The following are preconditions:
   161         -<p><ul>
   162         -<li><b>Z</b> is an arbitrary-length NUL-terminated string.</li>
   163         -<li>An existing SQLite database has been opened.  The return value
   164         -    from the call to <b>sqlite_open()</b> is stored in the variable
   165         -    <b>db</b>.</li>
   166         -<li>There exists a callback function <b>cb()</b> that appends all
   167         -    information passed in through its parameters into a single
   168         -    data buffer called <b>Y</b>.</li>
   169         -<li>There are no user-defined functions other than the standard
   170         -    build-in functions.</li>
   171         -</ul></p>
   172         -<p>The following statement of C code is executed:</p>
   173         -<blockquote><pre>
   174         -sqlite_exec(db, Z, cb, 0, 0);
   175         -</pre></blockquote>
   176         -<p>Prove the following are true for all possible values of string <b>Z</b>:</p>
   177         -<ol type="a">
   178         -<li><p>
   179         -The call to <b>sqlite_exec()</b> will
   180         -return in a length of time which is a polynomial in <b>strlen(Z)</b>.
   181         -It might return an error code but it will not crash.
   182         -</p></li>
   183         -<li><p>
   184         -After <b>sqlite_exec()</b> returns, the buffer <b>Y</b> will not contain
   185         -any content from any preexisting file on the host computers file system,
   186         -except for the database file.
   187         -</p></li>
   188         -<li><p>
   189         -After the call to <b>sqlite_exec()</b> returns, the database file will
   190         -still be well-formed.  It might not contain the same data, but it will
   191         -still be a properly constructed SQLite database file.
   192         -</p></li>
   193         -<li><p>
   194         -No preexisting files on the host computers filesystem, other than
   195         -the database file itself, will be deleted or modified.
   196         -</p></li>
   197         -<li><p>
   198         -For some constants <b>K1</b> and <b>K2</b>,
   199         -if at least <b>K1*strlen(Z) + K2</b> bytes of contiguous memory are
   200         -available to <b>malloc()</b>, then the call to <b>sqlite_exec()</b>
   201         -will not return SQLITE_NOMEM.
   202         -</p></li>
   203         -</ol>
   204         -</p></li>
   205         -
   206         -</ol>
   207         -}
   208         -puts {
   209         -<p><hr /></p>
   210         -<p><a href="index.html"><img src="/goback.jpg" border=0 />
   211         -Back to the SQLite Home Page</a>
   212         -</p>
   213         -
   214         -</body></html>}

Deleted www/autoinc.tcl.

     1         -#
     2         -# Run this Tcl script to generate the autoinc.html file.
     3         -#
     4         -set rcsid {$Id: }
     5         -source common.tcl
     6         -
     7         -if {[llength $argv]>0} {
     8         -  set outputdir [lindex $argv 0]
     9         -} else {
    10         -  set outputdir ""
    11         -}
    12         -
    13         -header {SQLite Autoincrement}
    14         -puts {
    15         -<h1>SQLite Autoincrement</h1>
    16         -
    17         -<p>
    18         -In SQLite, every row of every table has an integer ROWID.
    19         -The ROWID for each row is unique among all rows in the same table.
    20         -In SQLite version 2.8 the ROWID is a 32-bit signed integer.
    21         -Version 3.0 of SQLite expanded the ROWID to be a 64-bit signed integer.
    22         -</p>
    23         -
    24         -<p>
    25         -You can access the ROWID of an SQLite table using one the special column
    26         -names ROWID, _ROWID_, or OID.
    27         -Except if you declare an ordinary table column to use one of those special
    28         -names, then the use of that name will refer to the declared column not
    29         -to the internal ROWID.
    30         -</p>
    31         -
    32         -<p>
    33         -If a table contains a column of type INTEGER PRIMARY KEY, then that
    34         -column becomes an alias for the ROWID.  You can then access the ROWID
    35         -using any of four different names, the original three names described above
    36         -or the name given to the INTEGER PRIMARY KEY column.  All these names are
    37         -aliases for one another and work equally well in any context.
    38         -</p>
    39         -
    40         -<p>
    41         -When a new row is inserted into an SQLite table, the ROWID can either
    42         -be specified as part of the INSERT statement or it can be assigned
    43         -automatically by the database engine.  To specify a ROWID manually,
    44         -just include it in the list of values to be inserted.  For example:
    45         -</p>
    46         -
    47         -<blockquote><pre>
    48         -CREATE TABLE test1(a INT, b TEXT);
    49         -INSERT INTO test1(rowid, a, b) VALUES(123, 5, 'hello');
    50         -</pre></blockquote>
    51         -
    52         -<p>
    53         -If no ROWID is specified on the insert, an appropriate ROWID is created
    54         -automatically.  The usual algorithm is to give the newly created row
    55         -a ROWID that is one larger than the largest ROWID in the table prior
    56         -to the insert.  If the table is initially empty, then a ROWID of 1 is
    57         -used.  If the largest ROWID is equal to the largest possible integer
    58         -(9223372036854775807 in SQLite version 3.0 and later) then the database
    59         -engine starts picking candidate ROWIDs at random until it finds one
    60         -that is not previously used.
    61         -</p>
    62         -
    63         -<p>
    64         -The normal ROWID selection algorithm described above
    65         -will generate monotonically increasing
    66         -unique ROWIDs as long as you never use the maximum ROWID value and you never
    67         -delete the entry in the table with the largest ROWID. 
    68         -If you ever delete rows or if you ever create a row with the maximum possible
    69         -ROWID, then ROWIDs from previously deleted rows might be reused when creating
    70         -new rows and newly created ROWIDs might not be in strictly accending order.
    71         -</p>
    72         -
    73         -
    74         -<h2>The AUTOINCREMENT Keyword</h2>
    75         -
    76         -<p>
    77         -If a column has the type INTEGER PRIMARY KEY AUTOINCREMENT then a slightly
    78         -different ROWID selection algorithm is used.  
    79         -The ROWID chosen for the new row is one larger than the largest ROWID
    80         -that has ever before existed in that same table.  If the table has never
    81         -before contained any data, then a ROWID of 1 is used.  If the table
    82         -has previously held a row with the largest possible ROWID, then new INSERTs
    83         -are not allowed and any attempt to insert a new row will fail with an
    84         -SQLITE_FULL error.
    85         -</p>
    86         -
    87         -<p>
    88         -SQLite keeps track of the largest ROWID that a table has ever held using
    89         -the special SQLITE_SEQUENCE table.  The SQLITE_SEQUENCE table is created
    90         -and initialized automatically whenever a normal table that contains an
    91         -AUTOINCREMENT column is created.  The content of the SQLITE_SEQUENCE table
    92         -can be modified using ordinary UPDATE, INSERT, and DELETE statements.
    93         -But making modifications to this table will likely perturb the AUTOINCREMENT
    94         -key generation algorithm.  Make sure you know what you are doing before
    95         -you undertake such changes.
    96         -</p>
    97         -
    98         -<p>
    99         -The behavior implemented by the AUTOINCREMENT keyword is subtly different
   100         -from the default behavior.  With AUTOINCREMENT, rows with automatically
   101         -selected ROWIDs are guaranteed to have ROWIDs that have never been used
   102         -before by the same table in the same database.  And the automatically generated
   103         -ROWIDs are guaranteed to be monotonically increasing.  These are important
   104         -properties in certain applications.  But if your application does not
   105         -need these properties, you should probably stay with the default behavior
   106         -since the use of AUTOINCREMENT requires additional work to be done
   107         -as each row is inserted and thus causes INSERTs to run a little slower.
   108         -}
   109         -footer $rcsid

Deleted www/c_interface.tcl.

     1         -#
     2         -# Run this Tcl script to generate the sqlite.html file.
     3         -#
     4         -set rcsid {$Id: c_interface.tcl,v 1.43 2004/11/19 11:59:24 danielk1977 Exp $}
     5         -source common.tcl
     6         -header {The C language interface to the SQLite library}
     7         -puts {
     8         -<h2>The C language interface to the SQLite library</h2>
     9         -
    10         -<p>The SQLite library is designed to be very easy to use from
    11         -a C or C++ program.  This document gives an overview of the C/C++
    12         -programming interface.</p>
    13         -
    14         -<h3>1.0 The Core API</h3>
    15         -
    16         -<p>The interface to the SQLite library consists of three core functions,
    17         -one opaque data structure, and some constants used as return values.
    18         -The core interface is as follows:</p>
    19         -
    20         -<blockquote><pre>
    21         -typedef struct sqlite sqlite;
    22         -#define SQLITE_OK           0   /* Successful result */
    23         -
    24         -sqlite *sqlite_open(const char *dbname, int mode, char **errmsg);
    25         -
    26         -void sqlite_close(sqlite *db);
    27         -
    28         -int sqlite_exec(
    29         -  sqlite *db,
    30         -  char *sql,
    31         -  int (*xCallback)(void*,int,char**,char**),
    32         -  void *pArg,
    33         -  char **errmsg
    34         -);
    35         -</pre></blockquote>
    36         -
    37         -<p>
    38         -The above is all you really need to know in order to use SQLite
    39         -in your C or C++ programs.  There are other interface functions
    40         -available (and described below) but we will begin by describing
    41         -the core functions shown above.
    42         -</p>
    43         -
    44         -<a name="sqlite_open">
    45         -<h4>1.1 Opening a database</h4>
    46         -
    47         -<p>Use the <b>sqlite_open</b> function to open an existing SQLite
    48         -database or to create a new SQLite database.  The first argument
    49         -is the database name.  The second argument is intended to signal
    50         -whether the database is going to be used for reading and writing
    51         -or just for reading.  But in the current implementation, the
    52         -second argument to <b>sqlite_open</b> is ignored.
    53         -The third argument is a pointer to a string pointer.
    54         -If the third argument is not NULL and an error occurs
    55         -while trying to open the database, then an error message will be
    56         -written to memory obtained from malloc() and *errmsg will be made
    57         -to point to this error message.  The calling function is responsible
    58         -for freeing the memory when it has finished with it.</p>
    59         -
    60         -<p>The name of an SQLite database is the name of a file that will
    61         -contain the database.  If the file does not exist, SQLite attempts
    62         -to create and initialize it.  If the file is read-only (due to
    63         -permission bits or because it is located on read-only media like
    64         -a CD-ROM) then SQLite opens the database for reading only.  The
    65         -entire SQL database is stored in a single file on the disk.  But
    66         -additional temporary files may be created during the execution of
    67         -an SQL command in order to store the database rollback journal or
    68         -temporary and intermediate results of a query.</p>
    69         -
    70         -<p>The return value of the <b>sqlite_open</b> function is a
    71         -pointer to an opaque <b>sqlite</b> structure.  This pointer will
    72         -be the first argument to all subsequent SQLite function calls that
    73         -deal with the same database.  NULL is returned if the open fails
    74         -for any reason.</p>
    75         -
    76         -<a name="sqlite_close">
    77         -<h4>1.2 Closing the database</h4>
    78         -
    79         -<p>To close an SQLite database, call the <b>sqlite_close</b>
    80         -function passing it the sqlite structure pointer that was obtained
    81         -from a prior call to <b>sqlite_open</b>.
    82         -If a transaction is active when the database is closed, the transaction
    83         -is rolled back.</p>
    84         -
    85         -<a name="sqlite_exec">
    86         -<h4>1.3 Executing SQL statements</h4>
    87         -
    88         -<p>The <b>sqlite_exec</b> function is used to process SQL statements
    89         -and queries.  This function requires 5 parameters as follows:</p>
    90         -
    91         -<ol>
    92         -<li><p>A pointer to the sqlite structure obtained from a prior call
    93         -       to <b>sqlite_open</b>.</p></li>
    94         -<li><p>A null-terminated string containing the text of one or more
    95         -       SQL statements and/or queries to be processed.</p></li>
    96         -<li><p>A pointer to a callback function which is invoked once for each
    97         -       row in the result of a query.  This argument may be NULL, in which
    98         -       case no callbacks will ever be invoked.</p></li>
    99         -<li><p>A pointer that is forwarded to become the first argument
   100         -       to the callback function.</p></li>
   101         -<li><p>A pointer to an error string.  Error messages are written to space
   102         -       obtained from malloc() and the error string is made to point to
   103         -       the malloced space.  The calling function is responsible for freeing
   104         -       this space when it has finished with it.
   105         -       This argument may be NULL, in which case error messages are not
   106         -       reported back to the calling function.</p></li>
   107         -</ol>
   108         -
   109         -<p>
   110         -The callback function is used to receive the results of a query.  A
   111         -prototype for the callback function is as follows:</p>
   112         -
   113         -<blockquote><pre>
   114         -int Callback(void *pArg, int argc, char **argv, char **columnNames){
   115         -  return 0;
   116         -}
   117         -</pre></blockquote>
   118         -
   119         -<a name="callback_row_data">
   120         -<p>The first argument to the callback is just a copy of the fourth argument
   121         -to <b>sqlite_exec</b>  This parameter can be used to pass arbitrary
   122         -information through to the callback function from client code.
   123         -The second argument is the number of columns in the query result.
   124         -The third argument is an array of pointers to strings where each string
   125         -is a single column of the result for that record.  Note that the
   126         -callback function reports a NULL value in the database as a NULL pointer,
   127         -which is very different from an empty string.  If the i-th parameter
   128         -is an empty string, we will get:</p>
   129         -<blockquote><pre>
   130         -argv[i][0] == 0
   131         -</pre></blockquote>
   132         -<p>But if the i-th parameter is NULL we will get:</p>
   133         -<blockquote><pre>
   134         -argv[i] == 0
   135         -</pre></blockquote>
   136         -
   137         -<p>The names of the columns are contained in first <i>argc</i>
   138         -entries of the fourth argument.
   139         -If the <a href="pragma.html#pragma_show_datatypes">SHOW_DATATYPES</a> pragma
   140         -is on (it is off by default) then
   141         -the second <i>argc</i> entries in the 4th argument are the datatypes
   142         -for the corresponding columns.
   143         -</p>
   144         -
   145         -<p>If the <a href="pragma.html#pragma_empty_result_callbacks">
   146         -EMPTY_RESULT_CALLBACKS</a> pragma is set to ON and the result of
   147         -a query is an empty set, then the callback is invoked once with the
   148         -third parameter (argv) set to 0.  In other words
   149         -<blockquote><pre>
   150         -argv == 0
   151         -</pre></blockquote>
   152         -The second parameter (argc)
   153         -and the fourth parameter (columnNames) are still valid
   154         -and can be used to determine the number and names of the result
   155         -columns if there had been a result.
   156         -The default behavior is not to invoke the callback at all if the
   157         -result set is empty.</p>
   158         -
   159         -<a name="callback_returns_nonzero">
   160         -<p>The callback function should normally return 0.  If the callback
   161         -function returns non-zero, the query is immediately aborted and 
   162         -<b>sqlite_exec</b> will return SQLITE_ABORT.</p>
   163         -
   164         -<h4>1.4 Error Codes</h4>
   165         -
   166         -<p>
   167         -The <b>sqlite_exec</b> function normally returns SQLITE_OK.  But
   168         -if something goes wrong it can return a different value to indicate
   169         -the type of error.  Here is a complete list of the return codes:
   170         -</p>
   171         -
   172         -<blockquote><pre>
   173         -#define SQLITE_OK           0   /* Successful result */
   174         -#define SQLITE_ERROR        1   /* SQL error or missing database */
   175         -#define SQLITE_INTERNAL     2   /* An internal logic error in SQLite */
   176         -#define SQLITE_PERM         3   /* Access permission denied */
   177         -#define SQLITE_ABORT        4   /* Callback routine requested an abort */
   178         -#define SQLITE_BUSY         5   /* The database file is locked */
   179         -#define SQLITE_LOCKED       6   /* A table in the database is locked */
   180         -#define SQLITE_NOMEM        7   /* A malloc() failed */
   181         -#define SQLITE_READONLY     8   /* Attempt to write a readonly database */
   182         -#define SQLITE_INTERRUPT    9   /* Operation terminated by sqlite_interrupt() */
   183         -#define SQLITE_IOERR       10   /* Some kind of disk I/O error occurred */
   184         -#define SQLITE_CORRUPT     11   /* The database disk image is malformed */
   185         -#define SQLITE_NOTFOUND    12   /* (Internal Only) Table or record not found */
   186         -#define SQLITE_FULL        13   /* Insertion failed because database is full */
   187         -#define SQLITE_CANTOPEN    14   /* Unable to open the database file */
   188         -#define SQLITE_PROTOCOL    15   /* Database lock protocol error */
   189         -#define SQLITE_EMPTY       16   /* (Internal Only) Database table is empty */
   190         -#define SQLITE_SCHEMA      17   /* The database schema changed */
   191         -#define SQLITE_TOOBIG      18   /* Too much data for one row of a table */
   192         -#define SQLITE_CONSTRAINT  19   /* Abort due to contraint violation */
   193         -#define SQLITE_MISMATCH    20   /* Data type mismatch */
   194         -#define SQLITE_MISUSE      21   /* Library used incorrectly */
   195         -#define SQLITE_NOLFS       22   /* Uses OS features not supported on host */
   196         -#define SQLITE_AUTH        23   /* Authorization denied */
   197         -#define SQLITE_ROW         100  /* sqlite_step() has another row ready */
   198         -#define SQLITE_DONE        101  /* sqlite_step() has finished executing */
   199         -</pre></blockquote>
   200         -
   201         -<p>
   202         -The meanings of these various return values are as follows:
   203         -</p>
   204         -
   205         -<blockquote>
   206         -<dl>
   207         -<dt>SQLITE_OK</dt>
   208         -<dd><p>This value is returned if everything worked and there were no errors.
   209         -</p></dd>
   210         -<dt>SQLITE_INTERNAL</dt>
   211         -<dd><p>This value indicates that an internal consistency check within
   212         -the SQLite library failed.  This can only happen if there is a bug in
   213         -the SQLite library.  If you ever get an SQLITE_INTERNAL reply from
   214         -an <b>sqlite_exec</b> call, please report the problem on the SQLite
   215         -mailing list.
   216         -</p></dd>
   217         -<dt>SQLITE_ERROR</dt>
   218         -<dd><p>This return value indicates that there was an error in the SQL
   219         -that was passed into the <b>sqlite_exec</b>.
   220         -</p></dd>
   221         -<dt>SQLITE_PERM</dt>
   222         -<dd><p>This return value says that the access permissions on the database
   223         -file are such that the file cannot be opened.
   224         -</p></dd>
   225         -<dt>SQLITE_ABORT</dt>
   226         -<dd><p>This value is returned if the callback function returns non-zero.
   227         -</p></dd>
   228         -<dt>SQLITE_BUSY</dt>
   229         -<dd><p>This return code indicates that another program or thread has
   230         -the database locked.  SQLite allows two or more threads to read the
   231         -database at the same time, but only one thread can have the database
   232         -open for writing at the same time.  Locking in SQLite is on the
   233         -entire database.</p>
   234         -</p></dd>
   235         -<dt>SQLITE_LOCKED</dt>
   236         -<dd><p>This return code is similar to SQLITE_BUSY in that it indicates
   237         -that the database is locked.  But the source of the lock is a recursive
   238         -call to <b>sqlite_exec</b>.  This return can only occur if you attempt
   239         -to invoke sqlite_exec from within a callback routine of a query
   240         -from a prior invocation of sqlite_exec.  Recursive calls to
   241         -sqlite_exec are allowed as long as they do
   242         -not attempt to write the same table.
   243         -</p></dd>
   244         -<dt>SQLITE_NOMEM</dt>
   245         -<dd><p>This value is returned if a call to <b>malloc</b> fails.
   246         -</p></dd>
   247         -<dt>SQLITE_READONLY</dt>
   248         -<dd><p>This return code indicates that an attempt was made to write to
   249         -a database file that is opened for reading only.
   250         -</p></dd>
   251         -<dt>SQLITE_INTERRUPT</dt>
   252         -<dd><p>This value is returned if a call to <b>sqlite_interrupt</b>
   253         -interrupts a database operation in progress.
   254         -</p></dd>
   255         -<dt>SQLITE_IOERR</dt>
   256         -<dd><p>This value is returned if the operating system informs SQLite
   257         -that it is unable to perform some disk I/O operation.  This could mean
   258         -that there is no more space left on the disk.
   259         -</p></dd>
   260         -<dt>SQLITE_CORRUPT</dt>
   261         -<dd><p>This value is returned if SQLite detects that the database it is
   262         -working on has become corrupted.  Corruption might occur due to a rogue
   263         -process writing to the database file or it might happen due to an 
   264         -perviously undetected logic error in of SQLite. This value is also
   265         -returned if a disk I/O error occurs in such a way that SQLite is forced
   266         -to leave the database file in a corrupted state.  The latter should only
   267         -happen due to a hardware or operating system malfunction.
   268         -</p></dd>
   269         -<dt>SQLITE_FULL</dt>
   270         -<dd><p>This value is returned if an insertion failed because there is
   271         -no space left on the disk, or the database is too big to hold any
   272         -more information.  The latter case should only occur for databases
   273         -that are larger than 2GB in size.
   274         -</p></dd>
   275         -<dt>SQLITE_CANTOPEN</dt>
   276         -<dd><p>This value is returned if the database file could not be opened
   277         -for some reason.
   278         -</p></dd>
   279         -<dt>SQLITE_PROTOCOL</dt>
   280         -<dd><p>This value is returned if some other process is messing with
   281         -file locks and has violated the file locking protocol that SQLite uses
   282         -on its rollback journal files.
   283         -</p></dd>
   284         -<dt>SQLITE_SCHEMA</dt>
   285         -<dd><p>When the database first opened, SQLite reads the database schema
   286         -into memory and uses that schema to parse new SQL statements.  If another
   287         -process changes the schema, the command currently being processed will
   288         -abort because the virtual machine code generated assumed the old
   289         -schema.  This is the return code for such cases.  Retrying the
   290         -command usually will clear the problem.
   291         -</p></dd>
   292         -<dt>SQLITE_TOOBIG</dt>
   293         -<dd><p>SQLite will not store more than about 1 megabyte of data in a single
   294         -row of a single table.  If you attempt to store more than 1 megabyte
   295         -in a single row, this is the return code you get.
   296         -</p></dd>
   297         -<dt>SQLITE_CONSTRAINT</dt>
   298         -<dd><p>This constant is returned if the SQL statement would have violated
   299         -a database constraint.
   300         -</p></dd>
   301         -<dt>SQLITE_MISMATCH</dt>
   302         -<dd><p>This error occurs when there is an attempt to insert non-integer
   303         -data into a column labeled INTEGER PRIMARY KEY.  For most columns, SQLite
   304         -ignores the data type and allows any kind of data to be stored.  But
   305         -an INTEGER PRIMARY KEY column is only allowed to store integer data.
   306         -</p></dd>
   307         -<dt>SQLITE_MISUSE</dt>
   308         -<dd><p>This error might occur if one or more of the SQLite API routines
   309         -is used incorrectly.  Examples of incorrect usage include calling
   310         -<b>sqlite_exec</b> after the database has been closed using
   311         -<b>sqlite_close</b> or 
   312         -calling <b>sqlite_exec</b> with the same
   313         -database pointer simultaneously from two separate threads.
   314         -</p></dd>
   315         -<dt>SQLITE_NOLFS</dt>
   316         -<dd><p>This error means that you have attempts to create or access a file
   317         -database file that is larger that 2GB on a legacy Unix machine that
   318         -lacks large file support.
   319         -</p></dd>
   320         -<dt>SQLITE_AUTH</dt>
   321         -<dd><p>This error indicates that the authorizer callback
   322         -has disallowed the SQL you are attempting to execute.
   323         -</p></dd>
   324         -<dt>SQLITE_ROW</dt>
   325         -<dd><p>This is one of the return codes from the
   326         -<b>sqlite_step</b> routine which is part of the non-callback API.
   327         -It indicates that another row of result data is available.
   328         -</p></dd>
   329         -<dt>SQLITE_DONE</dt>
   330         -<dd><p>This is one of the return codes from the
   331         -<b>sqlite_step</b> routine which is part of the non-callback API.
   332         -It indicates that the SQL statement has been completely executed and
   333         -the <b>sqlite_finalize</b> routine is ready to be called.
   334         -</p></dd>
   335         -</dl>
   336         -</blockquote>
   337         -
   338         -<h3>2.0 Accessing Data Without Using A Callback Function</h3>
   339         -
   340         -<p>
   341         -The <b>sqlite_exec</b> routine described above used to be the only
   342         -way to retrieve data from an SQLite database.  But many programmers found
   343         -it inconvenient to use a callback function to obtain results.  So beginning
   344         -with SQLite version 2.7.7, a second access interface is available that
   345         -does not use callbacks.
   346         -</p>
   347         -
   348         -<p>
   349         -The new interface uses three separate functions to replace the single
   350         -<b>sqlite_exec</b> function.
   351         -</p>
   352         -
   353         -<blockquote><pre>
   354         -typedef struct sqlite_vm sqlite_vm;
   355         -
   356         -int sqlite_compile(
   357         -  sqlite *db,              /* The open database */
   358         -  const char *zSql,        /* SQL statement to be compiled */
   359         -  const char **pzTail,     /* OUT: uncompiled tail of zSql */
   360         -  sqlite_vm **ppVm,        /* OUT: the virtual machine to execute zSql */
   361         -  char **pzErrmsg          /* OUT: Error message. */
   362         -);
   363         -
   364         -int sqlite_step(
   365         -  sqlite_vm *pVm,          /* The virtual machine to execute */
   366         -  int *pN,                 /* OUT: Number of columns in result */
   367         -  const char ***pazValue,  /* OUT: Column data */
   368         -  const char ***pazColName /* OUT: Column names and datatypes */
   369         -);
   370         -
   371         -int sqlite_finalize(
   372         -  sqlite_vm *pVm,          /* The virtual machine to be finalized */
   373         -  char **pzErrMsg          /* OUT: Error message */
   374         -);
   375         -</pre></blockquote>
   376         -
   377         -<p>
   378         -The strategy is to compile a single SQL statement using
   379         -<b>sqlite_compile</b> then invoke <b>sqlite_step</b> multiple times,
   380         -once for each row of output, and finally call <b>sqlite_finalize</b>
   381         -to clean up after the SQL has finished execution.
   382         -</p>
   383         -
   384         -<h4>2.1 Compiling An SQL Statement Into A Virtual Machine</h4>
   385         -
   386         -<p>
   387         -The <b>sqlite_compile</b> "compiles" a single SQL statement (specified
   388         -by the second parameter) and generates a virtual machine that is able
   389         -to execute that statement.  
   390         -As with must interface routines, the first parameter must be a pointer
   391         -to an sqlite structure that was obtained from a prior call to
   392         -<b>sqlite_open</b>.
   393         -
   394         -<p>
   395         -A pointer to the virtual machine is stored in a pointer which is passed
   396         -in as the 4th parameter.
   397         -Space to hold the virtual machine is dynamically allocated.  To avoid
   398         -a memory leak, the calling function must invoke
   399         -<b>sqlite_finalize</b> on the virtual machine after it has finished
   400         -with it.
   401         -The 4th parameter may be set to NULL if an error is encountered during
   402         -compilation.
   403         -</p>
   404         -
   405         -<p>
   406         -If any errors are encountered during compilation, an error message is
   407         -written into memory obtained from <b>malloc</b> and the 5th parameter
   408         -is made to point to that memory.  If the 5th parameter is NULL, then
   409         -no error message is generated.  If the 5th parameter is not NULL, then
   410         -the calling function should dispose of the memory containing the error
   411         -message by calling <b>sqlite_freemem</b>.
   412         -</p>
   413         -
   414         -<p>
   415         -If the 2nd parameter actually contains two or more statements of SQL,
   416         -only the first statement is compiled.  (This is different from the
   417         -behavior of <b>sqlite_exec</b> which executes all SQL statements
   418         -in its input string.)  The 3rd parameter to <b>sqlite_compile</b>
   419         -is made to point to the first character beyond the end of the first
   420         -statement of SQL in the input.  If the 2nd parameter contains only
   421         -a single SQL statement, then the 3rd parameter will be made to point
   422         -to the '\000' terminator at the end of the 2nd parameter.
   423         -</p>
   424         -
   425         -<p>
   426         -On success, <b>sqlite_compile</b> returns SQLITE_OK.
   427         -Otherwise and error code is returned.
   428         -</p>
   429         -
   430         -<h4>2.2 Step-By-Step Execution Of An SQL Statement</h4>
   431         -
   432         -<p>
   433         -After a virtual machine has been generated using <b>sqlite_compile</b>
   434         -it is executed by one or more calls to <b>sqlite_step</b>.  Each
   435         -invocation of <b>sqlite_step</b>, except the last one,
   436         -returns a single row of the result.
   437         -The number of columns in  the result is stored in the integer that
   438         -the 2nd parameter points to.
   439         -The pointer specified by the 3rd parameter is made to point
   440         -to an array of pointers to column values.
   441         -The pointer in the 4th parameter is made to point to an array
   442         -of pointers to column names and datatypes.
   443         -The 2nd through 4th parameters to <b>sqlite_step</b> convey the
   444         -same information as the 2nd through 4th parameters of the
   445         -<b>callback</b> routine when using
   446         -the <b>sqlite_exec</b> interface.  Except, with <b>sqlite_step</b>
   447         -the column datatype information is always included in the in the
   448         -4th parameter regardless of whether or not the
   449         -<a href="pragma.html#pragma_show_datatypes">SHOW_DATATYPES</a> pragma
   450         -is on or off.
   451         -</p>
   452         -
   453         -<p>
   454         -Each invocation of <b>sqlite_step</b> returns an integer code that
   455         -indicates what happened during that step.  This code may be
   456         -SQLITE_BUSY, SQLITE_ROW, SQLITE_DONE, SQLITE_ERROR, or
   457         -SQLITE_MISUSE.
   458         -</p>
   459         -
   460         -<p>
   461         -If the virtual machine is unable to open the database file because
   462         -it is locked by another thread or process, <b>sqlite_step</b>
   463         -will return SQLITE_BUSY.  The calling function should do some other
   464         -activity, or sleep, for a short amount of time to give the lock a
   465         -chance to clear, then invoke <b>sqlite_step</b> again.  This can
   466         -be repeated as many times as desired.
   467         -</p>
   468         -
   469         -<p>
   470         -Whenever another row of result data is available,
   471         -<b>sqlite_step</b> will return SQLITE_ROW.  The row data is
   472         -stored in an array of pointers to strings and the 2nd parameter
   473         -is made to point to this array.
   474         -</p>
   475         -
   476         -<p>
   477         -When all processing is complete, <b>sqlite_step</b> will return
   478         -either SQLITE_DONE or SQLITE_ERROR.  SQLITE_DONE indicates that the
   479         -statement completed successfully and SQLITE_ERROR indicates that there
   480         -was a run-time error.  (The details of the error are obtained from
   481         -<b>sqlite_finalize</b>.)  It is a misuse of the library to attempt
   482         -to call <b>sqlite_step</b> again after it has returned SQLITE_DONE
   483         -or SQLITE_ERROR.
   484         -</p>
   485         -
   486         -<p>
   487         -When <b>sqlite_step</b> returns SQLITE_DONE or SQLITE_ERROR,
   488         -the *pN and *pazColName values are set to the number of columns
   489         -in the result set and to the names of the columns, just as they
   490         -are for an SQLITE_ROW return.  This allows the calling code to
   491         -find the number of result columns and the column names and datatypes
   492         -even if the result set is empty.  The *pazValue parameter is always
   493         -set to NULL when the return codes is SQLITE_DONE or SQLITE_ERROR.
   494         -If the SQL being executed is a statement that does not
   495         -return a result (such as an INSERT or an UPDATE) then *pN will
   496         -be set to zero and *pazColName will be set to NULL.
   497         -</p>
   498         -
   499         -<p>
   500         -If you abuse the library by trying to call <b>sqlite_step</b>
   501         -inappropriately it will attempt return SQLITE_MISUSE.
   502         -This can happen if you call sqlite_step() on the same virtual machine
   503         -at the same
   504         -time from two or more threads or if you call sqlite_step()
   505         -again after it returned SQLITE_DONE or SQLITE_ERROR or if you
   506         -pass in an invalid virtual machine pointer to sqlite_step().
   507         -You should not depend on the SQLITE_MISUSE return code to indicate
   508         -an error.  It is possible that a misuse of the interface will go
   509         -undetected and result in a program crash.  The SQLITE_MISUSE is
   510         -intended as a debugging aid only - to help you detect incorrect
   511         -usage prior to a mishap.  The misuse detection logic is not guaranteed
   512         -to work in every case.
   513         -</p>
   514         -
   515         -<h4>2.3 Deleting A Virtual Machine</h4>
   516         -
   517         -<p>
   518         -Every virtual machine that <b>sqlite_compile</b> creates should
   519         -eventually be handed to <b>sqlite_finalize</b>.  The sqlite_finalize()
   520         -procedure deallocates the memory and other resources that the virtual
   521         -machine uses.  Failure to call sqlite_finalize() will result in 
   522         -resource leaks in your program.
   523         -</p>
   524         -
   525         -<p>
   526         -The <b>sqlite_finalize</b> routine also returns the result code
   527         -that indicates success or failure of the SQL operation that the
   528         -virtual machine carried out.
   529         -The value returned by sqlite_finalize() will be the same as would
   530         -have been returned had the same SQL been executed by <b>sqlite_exec</b>.
   531         -The error message returned will also be the same.
   532         -</p>
   533         -
   534         -<p>
   535         -It is acceptable to call <b>sqlite_finalize</b> on a virtual machine
   536         -before <b>sqlite_step</b> has returned SQLITE_DONE.  Doing so has
   537         -the effect of interrupting the operation in progress.  Partially completed
   538         -changes will be rolled back and the database will be restored to its
   539         -original state (unless an alternative recovery algorithm is selected using
   540         -an ON CONFLICT clause in the SQL being executed.)  The effect is the
   541         -same as if a callback function of <b>sqlite_exec</b> had returned
   542         -non-zero.
   543         -</p>
   544         -
   545         -<p>
   546         -It is also acceptable to call <b>sqlite_finalize</b> on a virtual machine
   547         -that has never been passed to <b>sqlite_step</b> even once.
   548         -</p>
   549         -
   550         -<h3>3.0 The Extended API</h3>
   551         -
   552         -<p>Only the three core routines described in section 1.0 are required to use
   553         -SQLite.  But there are many other functions that provide 
   554         -useful interfaces.  These extended routines are as follows:
   555         -</p>
   556         -
   557         -<blockquote><pre>
   558         -int sqlite_last_insert_rowid(sqlite*);
   559         -
   560         -int sqlite_changes(sqlite*);
   561         -
   562         -int sqlite_get_table(
   563         -  sqlite*,
   564         -  char *sql,
   565         -  char ***result,
   566         -  int *nrow,
   567         -  int *ncolumn,
   568         -  char **errmsg
   569         -);
   570         -
   571         -void sqlite_free_table(char**);
   572         -
   573         -void sqlite_interrupt(sqlite*);
   574         -
   575         -int sqlite_complete(const char *sql);
   576         -
   577         -void sqlite_busy_handler(sqlite*, int (*)(void*,const char*,int), void*);
   578         -
   579         -void sqlite_busy_timeout(sqlite*, int ms);
   580         -
   581         -const char sqlite_version[];
   582         -
   583         -const char sqlite_encoding[];
   584         -
   585         -int sqlite_exec_printf(
   586         -  sqlite*,
   587         -  char *sql,
   588         -  int (*)(void*,int,char**,char**),
   589         -  void*,
   590         -  char **errmsg,
   591         -  ...
   592         -);
   593         -
   594         -int sqlite_exec_vprintf(
   595         -  sqlite*,
   596         -  char *sql,
   597         -  int (*)(void*,int,char**,char**),
   598         -  void*,
   599         -  char **errmsg,
   600         -  va_list
   601         -);
   602         -
   603         -int sqlite_get_table_printf(
   604         -  sqlite*,
   605         -  char *sql,
   606         -  char ***result,
   607         -  int *nrow,
   608         -  int *ncolumn,
   609         -  char **errmsg,
   610         -  ...
   611         -);
   612         -
   613         -int sqlite_get_table_vprintf(
   614         -  sqlite*,
   615         -  char *sql,
   616         -  char ***result,
   617         -  int *nrow,
   618         -  int *ncolumn,
   619         -  char **errmsg,
   620         -  va_list
   621         -);
   622         -
   623         -char *sqlite_mprintf(const char *zFormat, ...);
   624         -
   625         -char *sqlite_vmprintf(const char *zFormat, va_list);
   626         -
   627         -void sqlite_freemem(char*);
   628         -
   629         -void sqlite_progress_handler(sqlite*, int, int (*)(void*), void*);
   630         -
   631         -</pre></blockquote>
   632         -
   633         -<p>All of the above definitions are included in the "sqlite.h"
   634         -header file that comes in the source tree.</p>
   635         -
   636         -<h4>3.1 The ROWID of the most recent insert</h4>
   637         -
   638         -<p>Every row of an SQLite table has a unique integer key.  If the
   639         -table has a column labeled INTEGER PRIMARY KEY, then that column
   640         -serves as the key.  If there is no INTEGER PRIMARY KEY column then
   641         -the key is a unique integer.  The key for a row can be accessed in
   642         -a SELECT statement or used in a WHERE or ORDER BY clause using any
   643         -of the names "ROWID", "OID", or "_ROWID_".</p>
   644         -
   645         -<p>When you do an insert into a table that does not have an INTEGER PRIMARY
   646         -KEY column, or if the table does have an INTEGER PRIMARY KEY but the value
   647         -for that column is not specified in the VALUES clause of the insert, then
   648         -the key is automatically generated.  You can find the value of the key
   649         -for the most recent INSERT statement using the
   650         -<b>sqlite_last_insert_rowid</b> API function.</p>
   651         -
   652         -<h4>3.2 The number of rows that changed</h4>
   653         -
   654         -<p>The <b>sqlite_changes</b> API function returns the number of rows
   655         -that have been inserted, deleted, or modified since the database was
   656         -last quiescent.  A "quiescent" database is one in which there are
   657         -no outstanding calls to <b>sqlite_exec</b> and no VMs created by
   658         -<b>sqlite_compile</b> that have not been finalized by <b>sqlite_finalize</b>.
   659         -In common usage, <b>sqlite_changes</b> returns the number
   660         -of rows inserted, deleted, or modified by the most recent <b>sqlite_exec</b>
   661         -call or since the most recent <b>sqlite_compile</b>.  But if you have
   662         -nested calls to <b>sqlite_exec</b> (that is, if the callback routine
   663         -of one <b>sqlite_exec</b> invokes another <b>sqlite_exec</b>) or if
   664         -you invoke <b>sqlite_compile</b> to create a new VM while there is
   665         -still another VM in existance, then
   666         -the meaning of the number returned by <b>sqlite_changes</b> is more
   667         -complex.
   668         -The number reported includes any changes
   669         -that were later undone by a ROLLBACK or ABORT.  But rows that are
   670         -deleted because of a DROP TABLE are <em>not</em> counted.</p>
   671         -
   672         -<p>SQLite implements the command "<b>DELETE FROM table</b>" (without
   673         -a WHERE clause) by dropping the table then recreating it.  
   674         -This is much faster than deleting the elements of the table individually.
   675         -But it also means that the value returned from <b>sqlite_changes</b>
   676         -will be zero regardless of the number of elements that were originally
   677         -in the table.  If an accurate count of the number of elements deleted
   678         -is necessary, use "<b>DELETE FROM table WHERE 1</b>" instead.</p>
   679         -
   680         -<h4>3.3 Querying into memory obtained from malloc()</h4>
   681         -
   682         -<p>The <b>sqlite_get_table</b> function is a wrapper around
   683         -<b>sqlite_exec</b> that collects all the information from successive
   684         -callbacks and writes it into memory obtained from malloc().  This
   685         -is a convenience function that allows the application to get the
   686         -entire result of a database query with a single function call.</p>
   687         -
   688         -<p>The main result from <b>sqlite_get_table</b> is an array of pointers
   689         -to strings.  There is one element in this array for each column of
   690         -each row in the result.  NULL results are represented by a NULL
   691         -pointer. In addition to the regular data, there is an added row at the 
   692         -beginning of the array that contains the name of each column of the
   693         -result.</p>
   694         -
   695         -<p>As an example, consider the following query:</p>
   696         -
   697         -<blockquote>
   698         -SELECT employee_name, login, host FROM users WHERE login LIKE 'd%';
   699         -</blockquote>
   700         -
   701         -<p>This query will return the name, login and host computer name
   702         -for every employee whose login begins with the letter "d".  If this
   703         -query is submitted to <b>sqlite_get_table</b> the result might
   704         -look like this:</p>
   705         -
   706         -<blockquote>
   707         -nrow = 2<br>
   708         -ncolumn = 3<br>
   709         -result[0] = "employee_name"<br>
   710         -result[1] = "login"<br>
   711         -result[2] = "host"<br>
   712         -result[3] = "dummy"<br>
   713         -result[4] = "No such user"<br>
   714         -result[5] = 0<br>
   715         -result[6] = "D. Richard Hipp"<br>
   716         -result[7] = "drh"<br>
   717         -result[8] = "zadok"
   718         -</blockquote>
   719         -
   720         -<p>Notice that the "host" value for the "dummy" record is NULL so
   721         -the result[] array contains a NULL pointer at that slot.</p>
   722         -
   723         -<p>If the result set of a query is empty, then by default
   724         -<b>sqlite_get_table</b> will set nrow to 0 and leave its
   725         -result parameter is set to NULL.  But if the EMPTY_RESULT_CALLBACKS
   726         -pragma is ON then the result parameter is initialized to the names
   727         -of the columns only.  For example, consider this query which has
   728         -an empty result set:</p>
   729         -
   730         -<blockquote>
   731         -SELECT employee_name, login, host FROM users WHERE employee_name IS NULL;
   732         -</blockquote>
   733         -
   734         -<p>
   735         -The default behavior gives this results:
   736         -</p>
   737         -
   738         -<blockquote>
   739         -nrow = 0<br>
   740         -ncolumn = 0<br>
   741         -result = 0<br>
   742         -</blockquote>
   743         -
   744         -<p>
   745         -But if the EMPTY_RESULT_CALLBACKS pragma is ON, then the following
   746         -is returned:
   747         -</p>
   748         -
   749         -<blockquote>
   750         -nrow = 0<br>
   751         -ncolumn = 3<br>
   752         -result[0] = "employee_name"<br>
   753         -result[1] = "login"<br>
   754         -result[2] = "host"<br>
   755         -</blockquote>
   756         -
   757         -<p>Memory to hold the information returned by <b>sqlite_get_table</b>
   758         -is obtained from malloc().  But the calling function should not try
   759         -to free this information directly.  Instead, pass the complete table
   760         -to <b>sqlite_free_table</b> when the table is no longer needed.
   761         -It is safe to call <b>sqlite_free_table</b> with a NULL pointer such
   762         -as would be returned if the result set is empty.</p>
   763         -
   764         -<p>The <b>sqlite_get_table</b> routine returns the same integer
   765         -result code as <b>sqlite_exec</b>.</p>
   766         -
   767         -<h4>3.4 Interrupting an SQLite operation</h4>
   768         -
   769         -<p>The <b>sqlite_interrupt</b> function can be called from a
   770         -different thread or from a signal handler to cause the current database
   771         -operation to exit at its first opportunity.  When this happens,
   772         -the <b>sqlite_exec</b> routine (or the equivalent) that started
   773         -the database operation will return SQLITE_INTERRUPT.</p>
   774         -
   775         -<h4>3.5 Testing for a complete SQL statement</h4>
   776         -
   777         -<p>The next interface routine to SQLite is a convenience function used
   778         -to test whether or not a string forms a complete SQL statement.
   779         -If the <b>sqlite_complete</b> function returns true when its input
   780         -is a string, then the argument forms a complete SQL statement.
   781         -There are no guarantees that the syntax of that statement is correct,
   782         -but we at least know the statement is complete.  If <b>sqlite_complete</b>
   783         -returns false, then more text is required to complete the SQL statement.</p>
   784         -
   785         -<p>For the purpose of the <b>sqlite_complete</b> function, an SQL
   786         -statement is complete if it ends in a semicolon.</p>
   787         -
   788         -<p>The <b>sqlite</b> command-line utility uses the <b>sqlite_complete</b>
   789         -function to know when it needs to call <b>sqlite_exec</b>.  After each
   790         -line of input is received, <b>sqlite</b> calls <b>sqlite_complete</b>
   791         -on all input in its buffer.  If <b>sqlite_complete</b> returns true, 
   792         -then <b>sqlite_exec</b> is called and the input buffer is reset.  If
   793         -<b>sqlite_complete</b> returns false, then the prompt is changed to
   794         -the continuation prompt and another line of text is read and added to
   795         -the input buffer.</p>
   796         -
   797         -<h4>3.6 Library version string</h4>
   798         -
   799         -<p>The SQLite library exports the string constant named
   800         -<b>sqlite_version</b> which contains the version number of the
   801         -library.  The header file contains a macro SQLITE_VERSION
   802         -with the same information.  If desired, a program can compare
   803         -the SQLITE_VERSION macro against the <b>sqlite_version</b>
   804         -string constant to verify that the version number of the
   805         -header file and the library match.</p> 
   806         -
   807         -<h4>3.7 Library character encoding</h4>
   808         -
   809         -<p>By default, SQLite assumes that all data uses a fixed-size
   810         -8-bit character (iso8859).  But if you give the --enable-utf8 option
   811         -to the configure script, then the library assumes UTF-8 variable
   812         -sized characters.  This makes a difference for the LIKE and GLOB
   813         -operators and the LENGTH() and SUBSTR() functions.  The static
   814         -string <b>sqlite_encoding</b> will be set to either "UTF-8" or
   815         -"iso8859" to indicate how the library was compiled.  In addition,
   816         -the <b>sqlite.h</b> header file will define one of the
   817         -macros <b>SQLITE_UTF8</b> or <b>SQLITE_ISO8859</b>, as appropriate.</p>
   818         -
   819         -<p>Note that the character encoding mechanism used by SQLite cannot
   820         -be changed at run-time.  This is a compile-time option only.  The
   821         -<b>sqlite_encoding</b> character string just tells you how the library
   822         -was compiled.</p>
   823         -
   824         -<h4>3.8 Changing the library's response to locked files</h4>
   825         -
   826         -<p>The <b>sqlite_busy_handler</b> procedure can be used to register
   827         -a busy callback with an open SQLite database.  The busy callback will
   828         -be invoked whenever SQLite tries to access a database that is locked.
   829         -The callback will typically do some other useful work, or perhaps sleep,
   830         -in order to give the lock a chance to clear.  If the callback returns
   831         -non-zero, then SQLite tries again to access the database and the cycle
   832         -repeats.  If the callback returns zero, then SQLite aborts the current
   833         -operation and returns SQLITE_BUSY.</p>
   834         -
   835         -<p>The arguments to <b>sqlite_busy_handler</b> are the opaque
   836         -structure returned from <b>sqlite_open</b>, a pointer to the busy
   837         -callback function, and a generic pointer that will be passed as
   838         -the first argument to the busy callback.  When SQLite invokes the
   839         -busy callback, it sends it three arguments:  the generic pointer
   840         -that was passed in as the third argument to <b>sqlite_busy_handler</b>,
   841         -the name of the database table or index that the library is trying
   842         -to access, and the number of times that the library has attempted to
   843         -access the database table or index.</p>
   844         -
   845         -<p>For the common case where we want the busy callback to sleep,
   846         -the SQLite library provides a convenience routine <b>sqlite_busy_timeout</b>.
   847         -The first argument to <b>sqlite_busy_timeout</b> is a pointer to
   848         -an open SQLite database and the second argument is a number of milliseconds.
   849         -After <b>sqlite_busy_timeout</b> has been executed, the SQLite library
   850         -will wait for the lock to clear for at least the number of milliseconds 
   851         -specified before it returns SQLITE_BUSY.  Specifying zero milliseconds for
   852         -the timeout restores the default behavior.</p>
   853         -
   854         -<h4>3.9 Using the <tt>_printf()</tt> wrapper functions</h4>
   855         -
   856         -<p>The four utility functions</p>
   857         -
   858         -<p>
   859         -<ul>
   860         -<li><b>sqlite_exec_printf()</b></li>
   861         -<li><b>sqlite_exec_vprintf()</b></li>
   862         -<li><b>sqlite_get_table_printf()</b></li>
   863         -<li><b>sqlite_get_table_vprintf()</b></li>
   864         -</ul>
   865         -</p>
   866         -
   867         -<p>implement the same query functionality as <b>sqlite_exec</b>
   868         -and <b>sqlite_get_table</b>.  But instead of taking a complete
   869         -SQL statement as their second argument, the four <b>_printf</b>
   870         -routines take a printf-style format string.  The SQL statement to
   871         -be executed is generated from this format string and from whatever
   872         -additional arguments are attached to the end of the function call.</p>
   873         -
   874         -<p>There are two advantages to using the SQLite printf
   875         -functions instead of <b>sprintf</b>.  First of all, with the
   876         -SQLite printf routines, there is never a danger of overflowing a
   877         -static buffer as there is with <b>sprintf</b>.  The SQLite
   878         -printf routines automatically allocate (and later frees)
   879         -as much memory as is 
   880         -necessary to hold the SQL statements generated.</p>
   881         -
   882         -<p>The second advantage the SQLite printf routines have over
   883         -<b>sprintf</b> are two new formatting options specifically designed
   884         -to support string literals in SQL.  Within the format string,
   885         -the %q formatting option works very much like %s in that it
   886         -reads a null-terminated string from the argument list and inserts
   887         -it into the result.  But %q translates the inserted string by
   888         -making two copies of every single-quote (') character in the
   889         -substituted string.  This has the effect of escaping the end-of-string
   890         -meaning of single-quote within a string literal. The %Q formatting
   891         -option works similar; it translates the single-quotes like %q and
   892         -additionally encloses the resulting string in single-quotes.
   893         -If the argument for the %Q formatting options is a NULL pointer,
   894         -the resulting string is NULL without single quotes.
   895         -</p>
   896         -
   897         -<p>Consider an example.  Suppose you are trying to insert a string
   898         -value into a database table where the string value was obtained from
   899         -user input.  Suppose the string to be inserted is stored in a variable
   900         -named zString.  The code to do the insertion might look like this:</p>
   901         -
   902         -<blockquote><pre>
   903         -sqlite_exec_printf(db,
   904         -  "INSERT INTO table1 VALUES('%s')",
   905         -  0, 0, 0, zString);
   906         -</pre></blockquote>
   907         -
   908         -<p>If the zString variable holds text like "Hello", then this statement
   909         -will work just fine.  But suppose the user enters a string like 
   910         -"Hi y'all!".  The SQL statement generated reads as follows:
   911         -
   912         -<blockquote><pre>
   913         -INSERT INTO table1 VALUES('Hi y'all')
   914         -</pre></blockquote>
   915         -
   916         -<p>This is not valid SQL because of the apostrophy in the word "y'all".
   917         -But if the %q formatting option is used instead of %s, like this:</p>
   918         -
   919         -<blockquote><pre>
   920         -sqlite_exec_printf(db,
   921         -  "INSERT INTO table1 VALUES('%q')",
   922         -  0, 0, 0, zString);
   923         -</pre></blockquote>
   924         -
   925         -<p>Then the generated SQL will look like the following:</p>
   926         -
   927         -<blockquote><pre>
   928         -INSERT INTO table1 VALUES('Hi y''all')
   929         -</pre></blockquote>
   930         -
   931         -<p>Here the apostrophy has been escaped and the SQL statement is well-formed.
   932         -When generating SQL on-the-fly from data that might contain a
   933         -single-quote character ('), it is always a good idea to use the
   934         -SQLite printf routines and the %q formatting option instead of <b>sprintf</b>.
   935         -</p>
   936         -
   937         -<p>If the %Q formatting option is used instead of %q, like this:</p>
   938         -
   939         -<blockquote><pre>
   940         -sqlite_exec_printf(db,
   941         -  "INSERT INTO table1 VALUES(%Q)",
   942         -  0, 0, 0, zString);
   943         -</pre></blockquote>
   944         -
   945         -<p>Then the generated SQL will look like the following:</p>
   946         -
   947         -<blockquote><pre>
   948         -INSERT INTO table1 VALUES('Hi y''all')
   949         -</pre></blockquote>
   950         -
   951         -<p>If the value of the zString variable is NULL, the generated SQL
   952         -will look like the following:</p>
   953         -
   954         -<blockquote><pre>
   955         -INSERT INTO table1 VALUES(NULL)
   956         -</pre></blockquote>
   957         -
   958         -<p>All of the _printf() routines above are built around the following
   959         -two functions:</p>
   960         -
   961         -<blockquote><pre>
   962         -char *sqlite_mprintf(const char *zFormat, ...);
   963         -char *sqlite_vmprintf(const char *zFormat, va_list);
   964         -</pre></blockquote>
   965         -
   966         -<p>The <b>sqlite_mprintf()</b> routine works like the the standard library
   967         -<b>sprintf()</b> except that it writes its results into memory obtained
   968         -from malloc() and returns a pointer to the malloced buffer.  
   969         -<b>sqlite_mprintf()</b> also understands the %q and %Q extensions described
   970         -above.  The <b>sqlite_vmprintf()</b> is a varargs version of the same
   971         -routine.  The string pointer that these routines return should be freed
   972         -by passing it to <b>sqlite_freemem()</b>.
   973         -</p>
   974         -
   975         -<h4>3.10 Performing background jobs during large queries</h3>
   976         -
   977         -<p>The <b>sqlite_progress_handler()</b> routine can be used to register a
   978         -callback routine with an SQLite database to be invoked periodically during long
   979         -running calls to <b>sqlite_exec()</b>, <b>sqlite_step()</b> and the various
   980         -wrapper functions.
   981         -</p>
   982         -
   983         -<p>The callback is invoked every N virtual machine operations, where N is
   984         -supplied as the second argument to <b>sqlite_progress_handler()</b>. The third
   985         -and fourth arguments to <b>sqlite_progress_handler()</b> are a pointer to the
   986         -routine to be invoked and a void pointer to be passed as the first argument to
   987         -it.
   988         -</p>
   989         -
   990         -<p>The time taken to execute each virtual machine operation can vary based on
   991         -many factors.  A typical value for a 1 GHz PC is between half and three million
   992         -per second but may be much higher or lower, depending on the query.  As such it
   993         -is difficult to schedule background operations based on virtual machine
   994         -operations. Instead, it is recommended that a callback be scheduled relatively
   995         -frequently (say every 1000 instructions) and external timer routines used to
   996         -determine whether or not background jobs need to be run.  
   997         -</p>
   998         -
   999         -<a name="cfunc">
  1000         -<h3>4.0 Adding New SQL Functions</h3>
  1001         -
  1002         -<p>Beginning with version 2.4.0, SQLite allows the SQL language to be
  1003         -extended with new functions implemented as C code.  The following interface
  1004         -is used:
  1005         -</p>
  1006         -
  1007         -<blockquote><pre>
  1008         -typedef struct sqlite_func sqlite_func;
  1009         -
  1010         -int sqlite_create_function(
  1011         -  sqlite *db,
  1012         -  const char *zName,
  1013         -  int nArg,
  1014         -  void (*xFunc)(sqlite_func*,int,const char**),
  1015         -  void *pUserData
  1016         -);
  1017         -int sqlite_create_aggregate(
  1018         -  sqlite *db,
  1019         -  const char *zName,
  1020         -  int nArg,
  1021         -  void (*xStep)(sqlite_func*,int,const char**),
  1022         -  void (*xFinalize)(sqlite_func*),
  1023         -  void *pUserData
  1024         -);
  1025         -
  1026         -char *sqlite_set_result_string(sqlite_func*,const char*,int);
  1027         -void sqlite_set_result_int(sqlite_func*,int);
  1028         -void sqlite_set_result_double(sqlite_func*,double);
  1029         -void sqlite_set_result_error(sqlite_func*,const char*,int);
  1030         -
  1031         -void *sqlite_user_data(sqlite_func*);
  1032         -void *sqlite_aggregate_context(sqlite_func*, int nBytes);
  1033         -int sqlite_aggregate_count(sqlite_func*);
  1034         -</pre></blockquote>
  1035         -
  1036         -<p>
  1037         -The <b>sqlite_create_function()</b> interface is used to create 
  1038         -regular functions and <b>sqlite_create_aggregate()</b> is used to
  1039         -create new aggregate functions.  In both cases, the <b>db</b>
  1040         -parameter is an open SQLite database on which the functions should
  1041         -be registered, <b>zName</b> is the name of the new function,
  1042         -<b>nArg</b> is the number of arguments, and <b>pUserData</b> is
  1043         -a pointer which is passed through unchanged to the C implementation
  1044         -of the function.  Both routines return 0 on success and non-zero
  1045         -if there are any errors.
  1046         -</p>
  1047         -
  1048         -<p>
  1049         -The length of a function name may not exceed 255 characters.
  1050         -Any attempt to create a function whose name exceeds 255 characters
  1051         -in length will result in an error.
  1052         -</p>
  1053         -
  1054         -<p>
  1055         -For regular functions, the <b>xFunc</b> callback is invoked once
  1056         -for each function call.  The implementation of xFunc should call
  1057         -one of the <b>sqlite_set_result_...</b> interfaces to return its
  1058         -result.  The <b>sqlite_user_data()</b> routine can be used to
  1059         -retrieve the <b>pUserData</b> pointer that was passed in when the
  1060         -function was registered.
  1061         -</p>
  1062         -
  1063         -<p>
  1064         -For aggregate functions, the <b>xStep</b> callback is invoked once
  1065         -for each row in the result and then <b>xFinalize</b> is invoked at the
  1066         -end to compute a final answer.  The xStep routine can use the
  1067         -<b>sqlite_aggregate_context()</b> interface to allocate memory that
  1068         -will be unique to that particular instance of the SQL function.
  1069         -This memory will be automatically deleted after xFinalize is called.
  1070         -The <b>sqlite_aggregate_count()</b> routine can be used to find out
  1071         -how many rows of data were passed to the aggregate.  The xFinalize
  1072         -callback should invoke one of the <b>sqlite_set_result_...</b>
  1073         -interfaces to set the final result of the aggregate.
  1074         -</p>
  1075         -
  1076         -<p>
  1077         -SQLite now implements all of its built-in functions using this
  1078         -interface.  For additional information and examples on how to create
  1079         -new SQL functions, review the SQLite source code in the file
  1080         -<b>func.c</b>.
  1081         -</p>
  1082         -
  1083         -<h3>5.0 Multi-Threading And SQLite</h3>
  1084         -
  1085         -<p>
  1086         -If SQLite is compiled with the THREADSAFE preprocessor macro set to 1,
  1087         -then it is safe to use SQLite from two or more threads of the same process
  1088         -at the same time.  But each thread should have its own <b>sqlite*</b>
  1089         -pointer returned from <b>sqlite_open</b>.  It is never safe for two
  1090         -or more threads to access the same <b>sqlite*</b> pointer at the same time.
  1091         -</p>
  1092         -
  1093         -<p>
  1094         -In precompiled SQLite libraries available on the website, the Unix
  1095         -versions are compiled with THREADSAFE turned off but the windows
  1096         -versions are compiled with THREADSAFE turned on.  If you need something
  1097         -different that this you will have to recompile.
  1098         -</p>
  1099         -
  1100         -<p>
  1101         -Under Unix, an <b>sqlite*</b> pointer should not be carried across a
  1102         -<b>fork()</b> system call into the child process.  The child process
  1103         -should open its own copy of the database after the <b>fork()</b>.
  1104         -</p>
  1105         -
  1106         -<h3>6.0 Usage Examples</h3>
  1107         -
  1108         -<p>For examples of how the SQLite C/C++ interface can be used,
  1109         -refer to the source code for the <b>sqlite</b> program in the
  1110         -file <b>src/shell.c</b> of the source tree.
  1111         -Additional information about sqlite is available at
  1112         -<a href="sqlite.html">sqlite.html</a>.
  1113         -See also the sources to the Tcl interface for SQLite in
  1114         -the source file <b>src/tclsqlite.c</b>.</p>
  1115         -}
  1116         -footer $rcsid

Deleted www/capi3.tcl.

     1         -set rcsid {$Id: capi3.tcl,v 1.10 2007/04/27 17:16:22 drh Exp $}
     2         -source common.tcl
     3         -header {C/C++ Interface For SQLite Version 3}
     4         -
     5         -proc AddHyperlinks {txt} {
     6         -  regsub -all {([^:alnum:>])(sqlite3_\w+)(\([^\)]*\))} $txt \
     7         -      {\1<a href="capi3ref.html#\2">\2</a>\3} t2
     8         -  puts $t2
     9         -}
    10         -
    11         -AddHyperlinks {
    12         -<h2>C/C++ Interface For SQLite Version 3</h2>
    13         -
    14         -<h3>1.0 Overview</h3>
    15         -
    16         -<p>
    17         -SQLite version 3.0 is a new version of SQLite, derived from
    18         -the SQLite 2.8.13 code base, but with an incompatible file format
    19         -and API.
    20         -SQLite version 3.0 was created to answer demand for the following features:
    21         -</p>
    22         -
    23         -<ul>
    24         -<li>Support for UTF-16.</li>
    25         -<li>User-definable text collating sequences.</li>
    26         -<li>The ability to store BLOBs in indexed columns.</li>
    27         -</ul>
    28         -
    29         -<p>
    30         -It was necessary to move to version 3.0 to implement these features because
    31         -each requires incompatible changes to the database file format.  Other
    32         -incompatible changes, such as a cleanup of the API, were introduced at the
    33         -same time under the theory that it is best to get your incompatible changes
    34         -out of the way all at once.  
    35         -</p>
    36         -
    37         -<p>
    38         -The API for version 3.0 is similar to the version 2.X API,
    39         -but with some important changes.  Most noticeably, the "<tt>sqlite_</tt>"
    40         -prefix that occurs on the beginning of all API functions and data
    41         -structures are changed to "<tt>sqlite3_</tt>".  
    42         -This avoids confusion between the two APIs and allows linking against both
    43         -SQLite 2.X and SQLite 3.0 at the same time.
    44         -</p>
    45         -
    46         -<p>
    47         -There is no agreement on what the C datatype for a UTF-16
    48         -string should be.  Therefore, SQLite uses a generic type of void*
    49         -to refer to UTF-16 strings.  Client software can cast the void* 
    50         -to whatever datatype is appropriate for their system.
    51         -</p>
    52         -
    53         -<h3>2.0 C/C++ Interface</h3>
    54         -
    55         -<p>
    56         -The API for SQLite 3.0 includes 83 separate functions in addition
    57         -to several data structures and #defines.  (A complete
    58         -<a href="capi3ref.html">API reference</a> is provided as a separate document.)
    59         -Fortunately, the interface is not nearly as complex as its size implies.
    60         -Simple programs can still make do with only 3 functions:
    61         -<a href="capi3ref.html#sqlite3_open">sqlite3_open()</a>,
    62         -<a href="capi3ref.html#sqlite3_exec">sqlite3_exec()</a>, and
    63         -<a href="capi3ref.html#sqlite3_close">sqlite3_close()</a>.
    64         -More control over the execution of the database engine is provided
    65         -using
    66         -<a href="capi3ref.html#sqlite3_prepare">sqlite3_prepare()</a>
    67         -to compile an SQLite statement into byte code and
    68         -<a href="capi3ref.html#sqlite3_prepare">sqlite3_step()</a>
    69         -to execute that bytecode.
    70         -A family of routines with names beginning with 
    71         -<a href="capi3ref.html#sqlite3_column_blob">sqlite3_column_</a>
    72         -is used to extract information about the result set of a query.
    73         -Many interface functions come in pairs, with both a UTF-8 and
    74         -UTF-16 version.  And there is a collection of routines
    75         -used to implement user-defined SQL functions and user-defined
    76         -text collating sequences.
    77         -</p>
    78         -
    79         -
    80         -<h4>2.1 Opening and closing a database</h4>
    81         -
    82         -<blockquote><pre>
    83         -   typedef struct sqlite3 sqlite3;
    84         -   int sqlite3_open(const char*, sqlite3**);
    85         -   int sqlite3_open16(const void*, sqlite3**);
    86         -   int sqlite3_close(sqlite3*);
    87         -   const char *sqlite3_errmsg(sqlite3*);
    88         -   const void *sqlite3_errmsg16(sqlite3*);
    89         -   int sqlite3_errcode(sqlite3*);
    90         -</pre></blockquote>
    91         -
    92         -<p>
    93         -The sqlite3_open() routine returns an integer error code rather than
    94         -a pointer to the sqlite3 structure as the version 2 interface did.
    95         -The difference between sqlite3_open()
    96         -and sqlite3_open16() is that sqlite3_open16() takes UTF-16 (in host native
    97         -byte order) for the name of the database file.  If a new database file
    98         -needs to be created, then sqlite3_open16() sets the internal text
    99         -representation to UTF-16 whereas sqlite3_open() sets the text
   100         -representation to UTF-8.
   101         -</p>
   102         -
   103         -<p>
   104         -The opening and/or creating of the database file is deferred until the
   105         -file is actually needed.  This allows options and parameters, such
   106         -as the native text representation and default page size, to be
   107         -set using PRAGMA statements.
   108         -</p>
   109         -
   110         -<p>
   111         -The sqlite3_errcode() routine returns a result code for the most
   112         -recent major API call.  sqlite3_errmsg() returns an English-language
   113         -text error message for the most recent error.  The error message is
   114         -represented in UTF-8 and will be ephemeral - it could disappear on
   115         -the next call to any SQLite API function.  sqlite3_errmsg16() works like
   116         -sqlite3_errmsg() except that it returns the error message represented
   117         -as UTF-16 in host native byte order.
   118         -</p>
   119         -
   120         -<p>
   121         -The error codes for SQLite version 3 are unchanged from version 2.
   122         -They are as follows:
   123         -</p>
   124         -
   125         -<blockquote><pre>
   126         -#define SQLITE_OK           0   /* Successful result */
   127         -#define SQLITE_ERROR        1   /* SQL error or missing database */
   128         -#define SQLITE_INTERNAL     2   /* An internal logic error in SQLite */
   129         -#define SQLITE_PERM         3   /* Access permission denied */
   130         -#define SQLITE_ABORT        4   /* Callback routine requested an abort */
   131         -#define SQLITE_BUSY         5   /* The database file is locked */
   132         -#define SQLITE_LOCKED       6   /* A table in the database is locked */
   133         -#define SQLITE_NOMEM        7   /* A malloc() failed */
   134         -#define SQLITE_READONLY     8   /* Attempt to write a readonly database */
   135         -#define SQLITE_INTERRUPT    9   /* Operation terminated by sqlite_interrupt() */
   136         -#define SQLITE_IOERR       10   /* Some kind of disk I/O error occurred */
   137         -#define SQLITE_CORRUPT     11   /* The database disk image is malformed */
   138         -#define SQLITE_NOTFOUND    12   /* (Internal Only) Table or record not found */
   139         -#define SQLITE_FULL        13   /* Insertion failed because database is full */
   140         -#define SQLITE_CANTOPEN    14   /* Unable to open the database file */
   141         -#define SQLITE_PROTOCOL    15   /* Database lock protocol error */
   142         -#define SQLITE_EMPTY       16   /* (Internal Only) Database table is empty */
   143         -#define SQLITE_SCHEMA      17   /* The database schema changed */
   144         -#define SQLITE_TOOBIG      18   /* Too much data for one row of a table */
   145         -#define SQLITE_CONSTRAINT  19   /* Abort due to contraint violation */
   146         -#define SQLITE_MISMATCH    20   /* Data type mismatch */
   147         -#define SQLITE_MISUSE      21   /* Library used incorrectly */
   148         -#define SQLITE_NOLFS       22   /* Uses OS features not supported on host */
   149         -#define SQLITE_AUTH        23   /* Authorization denied */
   150         -#define SQLITE_ROW         100  /* sqlite_step() has another row ready */
   151         -#define SQLITE_DONE        101  /* sqlite_step() has finished executing */
   152         -</pre></blockquote>
   153         -
   154         -<h4>2.2 Executing SQL statements</h4>
   155         -
   156         -<blockquote><pre>
   157         -   typedef int (*sqlite_callback)(void*,int,char**, char**);
   158         -   int sqlite3_exec(sqlite3*, const char *sql, sqlite_callback, void*, char**);
   159         -</pre></blockquote>
   160         -
   161         -<p>
   162         -The sqlite3_exec function works much as it did in SQLite version 2.
   163         -Zero or more SQL statements specified in the second parameter are compiled
   164         -and executed.  Query results are returned to a callback routine.
   165         -See the <a href="capi3ref.html#sqlite3_exec">API reference</a> for additional
   166         -information.
   167         -</p>
   168         -
   169         -<p>
   170         -In SQLite version 3, the sqlite3_exec routine is just a wrapper around
   171         -calls to the prepared statement interface.
   172         -</p>
   173         -
   174         -<blockquote><pre>
   175         -   typedef struct sqlite3_stmt sqlite3_stmt;
   176         -   int sqlite3_prepare(sqlite3*, const char*, int, sqlite3_stmt**, const char**);
   177         -   int sqlite3_prepare16(sqlite3*, const void*, int, sqlite3_stmt**, const void**);
   178         -   int sqlite3_finalize(sqlite3_stmt*);
   179         -   int sqlite3_reset(sqlite3_stmt*);
   180         -</pre></blockquote>
   181         -
   182         -<p>
   183         -The sqlite3_prepare interface compiles a single SQL statement into byte code
   184         -for later execution.  This interface is now the preferred way of accessing
   185         -the database.
   186         -</p>
   187         -
   188         -<p>
   189         -The SQL statement is a UTF-8 string for sqlite3_prepare().
   190         -The sqlite3_prepare16() works the same way except
   191         -that it expects a UTF-16 string as SQL input.
   192         -Only the first SQL statement in the input string is compiled.
   193         -The fourth parameter is filled in with a pointer to the next (uncompiled)
   194         -SQLite statement in the input string, if any.
   195         -The sqlite3_finalize() routine deallocates a prepared SQL statement.
   196         -All prepared statements must be finalized before the database can be
   197         -closed.
   198         -The sqlite3_reset() routine resets a prepared SQL statement so that it
   199         -can be executed again.
   200         -</p>
   201         -
   202         -<p>
   203         -The SQL statement may contain tokens of the form "?" or "?nnn" or ":aaa"
   204         -where "nnn" is an integer and "aaa" is an identifier.
   205         -Such tokens represent unspecified literal values (or "wildcards")
   206         -to be filled in later by the 
   207         -<a href="capi3ref.html#sqlite3_bind_blob">sqlite3_bind</a> interface.
   208         -Each wildcard has an associated number which is its sequence in the
   209         -statement or the "nnn" in the case of a "?nnn" form. 
   210         -It is allowed for the same wildcard
   211         -to occur more than once in the same SQL statement, in which case
   212         -all instance of that wildcard will be filled in with the same value.
   213         -Unbound wildcards have a value of NULL.
   214         -</p>
   215         -
   216         -<blockquote><pre>
   217         -   int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
   218         -   int sqlite3_bind_double(sqlite3_stmt*, int, double);
   219         -   int sqlite3_bind_int(sqlite3_stmt*, int, int);
   220         -   int sqlite3_bind_int64(sqlite3_stmt*, int, long long int);
   221         -   int sqlite3_bind_null(sqlite3_stmt*, int);
   222         -   int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*));
   223         -   int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
   224         -   int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
   225         -</pre></blockquote>
   226         -
   227         -<p>
   228         -There is an assortment of sqlite3_bind routines used to assign values
   229         -to wildcards in a prepared SQL statement.  Unbound wildcards
   230         -are interpreted as NULLs.  Bindings are not reset by sqlite3_reset().
   231         -But wildcards can be rebound to new values after an sqlite3_reset().
   232         -</p>
   233         -
   234         -<p>
   235         -After an SQL statement has been prepared (and optionally bound), it
   236         -is executed using:
   237         -</p>
   238         -
   239         -<blockquote><pre>
   240         -   int sqlite3_step(sqlite3_stmt*);
   241         -</pre></blockquote>
   242         -
   243         -<p>
   244         -The sqlite3_step() routine return SQLITE_ROW if it is returning a single
   245         -row of the result set, or SQLITE_DONE if execution has completed, either
   246         -normally or due to an error.  It might also return SQLITE_BUSY if it is
   247         -unable to open the database file.  If the return value is SQLITE_ROW, then
   248         -the following routines can be used to extract information about that row
   249         -of the result set:
   250         -</p>
   251         -
   252         -<blockquote><pre>
   253         -   const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
   254         -   int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
   255         -   int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
   256         -   int sqlite3_column_count(sqlite3_stmt*);
   257         -   const char *sqlite3_column_decltype(sqlite3_stmt *, int iCol);
   258         -   const void *sqlite3_column_decltype16(sqlite3_stmt *, int iCol);
   259         -   double sqlite3_column_double(sqlite3_stmt*, int iCol);
   260         -   int sqlite3_column_int(sqlite3_stmt*, int iCol);
   261         -   long long int sqlite3_column_int64(sqlite3_stmt*, int iCol);
   262         -   const char *sqlite3_column_name(sqlite3_stmt*, int iCol);
   263         -   const void *sqlite3_column_name16(sqlite3_stmt*, int iCol);
   264         -   const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
   265         -   const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
   266         -   int sqlite3_column_type(sqlite3_stmt*, int iCol);
   267         -</pre></blockquote>
   268         -
   269         -<p>
   270         -The 
   271         -<a href="capi3ref.html#sqlite3_column_count">sqlite3_column_count()</a>
   272         -function returns the number of columns in
   273         -the results set.  sqlite3_column_count() can be called at any time after
   274         -sqlite3_prepare().  
   275         -<a href="capi3ref.html#sqlite3_data_count">sqlite3_data_count()</a>
   276         -works similarly to
   277         -sqlite3_column_count() except that it only works following sqlite3_step().
   278         -If the previous call to sqlite3_step() returned SQLITE_DONE or an error code,
   279         -then sqlite3_data_count() will return 0 whereas sqlite3_column_count() will
   280         -continue to return the number of columns in the result set.
   281         -</p>
   282         -
   283         -<p>Returned data is examined using the other sqlite3_column_***() functions, 
   284         -all of which take a column number as their second parameter. Columns are
   285         -zero-indexed from left to right. Note that this is different to parameters,
   286         -which are indexed starting at one.
   287         -</p>
   288         -
   289         -<p>
   290         -The sqlite3_column_type() function returns the
   291         -datatype for the value in the Nth column.  The return value is one
   292         -of these:
   293         -</p>
   294         -
   295         -<blockquote><pre>
   296         -   #define SQLITE_INTEGER  1
   297         -   #define SQLITE_FLOAT    2
   298         -   #define SQLITE_TEXT     3
   299         -   #define SQLITE_BLOB     4
   300         -   #define SQLITE_NULL     5
   301         -</pre></blockquote>
   302         -
   303         -<p>
   304         -The sqlite3_column_decltype() routine returns text which is the
   305         -declared type of the column in the CREATE TABLE statement.  For an
   306         -expression, the return type is an empty string.  sqlite3_column_name()
   307         -returns the name of the Nth column.  sqlite3_column_bytes() returns
   308         -the number of bytes in a column that has type BLOB or the number of bytes
   309         -in a TEXT string with UTF-8 encoding.  sqlite3_column_bytes16() returns
   310         -the same value for BLOBs but for TEXT strings returns the number of bytes
   311         -in a UTF-16 encoding.
   312         -sqlite3_column_blob() return BLOB data.  
   313         -sqlite3_column_text() return TEXT data as UTF-8.
   314         -sqlite3_column_text16() return TEXT data as UTF-16.
   315         -sqlite3_column_int() return INTEGER data in the host machines native
   316         -integer format.
   317         -sqlite3_column_int64() returns 64-bit INTEGER data.
   318         -Finally, sqlite3_column_double() return floating point data.
   319         -</p>
   320         -
   321         -<p>
   322         -It is not necessary to retrieve data in the format specify by
   323         -sqlite3_column_type().  If a different format is requested, the data
   324         -is converted automatically.
   325         -</p>
   326         -
   327         -<p>
   328         -Data format conversions can invalidate the pointer returned by
   329         -prior calls to sqlite3_column_blob(), sqlite3_column_text(), and/or
   330         -sqlite3_column_text16().  Pointers might be invalided in the following
   331         -cases:
   332         -</p>
   333         -<ul>
   334         -<li><p>
   335         -The initial content is a BLOB and sqlite3_column_text() 
   336         -or sqlite3_column_text16()
   337         -is called.  A zero-terminator might need to be added to the string.
   338         -</p></li>
   339         -<li><p>
   340         -The initial content is UTF-8 text and sqlite3_column_bytes16() or
   341         -sqlite3_column_text16() is called.  The content must be converted to UTF-16.
   342         -</p></li>
   343         -<li><p>
   344         -The initial content is UTF-16 text and sqlite3_column_bytes() or
   345         -sqlite3_column_text() is called.  The content must be converted to UTF-8.
   346         -</p></li>
   347         -</ul>
   348         -<p>
   349         -Note that conversions between UTF-16be and UTF-16le 
   350         -are always done in place and do
   351         -not invalidate a prior pointer, though of course the content of the buffer
   352         -that the prior pointer points to will have been modified.  Other kinds
   353         -of conversion are done in place when it is possible, but sometime it is
   354         -not possible and in those cases prior pointers are invalidated.  
   355         -</p>
   356         -
   357         -<p>
   358         -The safest and easiest to remember policy is this: assume that any
   359         -result from
   360         -<ul>
   361         -<li>sqlite3_column_blob(),</li>
   362         -<li>sqlite3_column_text(), or</li>
   363         -<li>sqlite3_column_text16()</li>
   364         -</ul>
   365         -is invalided by subsequent calls to 
   366         -<ul>
   367         -<li>sqlite3_column_bytes(),</li>
   368         -<li>sqlite3_column_bytes16(),</li>
   369         -<li>sqlite3_column_text(), or</li>
   370         -<li>sqlite3_column_text16().</li>
   371         -</ul>
   372         -This means that you should always call sqlite3_column_bytes() or
   373         -sqlite3_column_bytes16() <u>before</u> calling sqlite3_column_blob(),
   374         -sqlite3_column_text(), or sqlite3_column_text16().
   375         -</p>
   376         -
   377         -<h4>2.3 User-defined functions</h4>
   378         -
   379         -<p>
   380         -User defined functions can be created using the following routine:
   381         -</p>
   382         -
   383         -<blockquote><pre>
   384         -   typedef struct sqlite3_value sqlite3_value;
   385         -   int sqlite3_create_function(
   386         -     sqlite3 *,
   387         -     const char *zFunctionName,
   388         -     int nArg,
   389         -     int eTextRep,
   390         -     void*,
   391         -     void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
   392         -     void (*xStep)(sqlite3_context*,int,sqlite3_value**),
   393         -     void (*xFinal)(sqlite3_context*)
   394         -   );
   395         -   int sqlite3_create_function16(
   396         -     sqlite3*,
   397         -     const void *zFunctionName,
   398         -     int nArg,
   399         -     int eTextRep,
   400         -     void*,
   401         -     void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
   402         -     void (*xStep)(sqlite3_context*,int,sqlite3_value**),
   403         -     void (*xFinal)(sqlite3_context*)
   404         -   );
   405         -   #define SQLITE_UTF8     1
   406         -   #define SQLITE_UTF16    2
   407         -   #define SQLITE_UTF16BE  3
   408         -   #define SQLITE_UTF16LE  4
   409         -   #define SQLITE_ANY      5
   410         -</pre></blockquote>
   411         -
   412         -<p>
   413         -The nArg parameter specifies the number of arguments to the function.
   414         -A value of 0 indicates that any number of arguments is allowed.  The
   415         -eTextRep parameter specifies what representation text values are expected
   416         -to be in for arguments to this function.  The value of this parameter should
   417         -be one of the parameters defined above.  SQLite version 3 allows multiple
   418         -implementations of the same function using different text representations.
   419         -The database engine chooses the function that minimization the number
   420         -of text conversions required.
   421         -</p>
   422         -
   423         -<p>
   424         -Normal functions specify only xFunc and leave xStep and xFinal set to NULL.
   425         -Aggregate functions specify xStep and xFinal and leave xFunc set to NULL.
   426         -There is no separate sqlite3_create_aggregate() API.
   427         -</p>
   428         -
   429         -<p>
   430         -The function name is specified in UTF-8.  A separate sqlite3_create_function16()
   431         -API works the same as sqlite_create_function()
   432         -except that the function name is specified in UTF-16 host byte order.
   433         -</p>
   434         -
   435         -<p>
   436         -Notice that the parameters to functions are now pointers to sqlite3_value
   437         -structures instead of pointers to strings as in SQLite version 2.X.
   438         -The following routines are used to extract useful information from these
   439         -"values":
   440         -</p>
   441         -
   442         -<blockquote><pre>
   443         -   const void *sqlite3_value_blob(sqlite3_value*);
   444         -   int sqlite3_value_bytes(sqlite3_value*);
   445         -   int sqlite3_value_bytes16(sqlite3_value*);
   446         -   double sqlite3_value_double(sqlite3_value*);
   447         -   int sqlite3_value_int(sqlite3_value*);
   448         -   long long int sqlite3_value_int64(sqlite3_value*);
   449         -   const unsigned char *sqlite3_value_text(sqlite3_value*);
   450         -   const void *sqlite3_value_text16(sqlite3_value*);
   451         -   int sqlite3_value_type(sqlite3_value*);
   452         -</pre></blockquote>
   453         -
   454         -<p>
   455         -Function implementations use the following APIs to acquire context and
   456         -to report results:
   457         -</p>
   458         -
   459         -<blockquote><pre>
   460         -   void *sqlite3_aggregate_context(sqlite3_context*, int nbyte);
   461         -   void *sqlite3_user_data(sqlite3_context*);
   462         -   void sqlite3_result_blob(sqlite3_context*, const void*, int n, void(*)(void*));
   463         -   void sqlite3_result_double(sqlite3_context*, double);
   464         -   void sqlite3_result_error(sqlite3_context*, const char*, int);
   465         -   void sqlite3_result_error16(sqlite3_context*, const void*, int);
   466         -   void sqlite3_result_int(sqlite3_context*, int);
   467         -   void sqlite3_result_int64(sqlite3_context*, long long int);
   468         -   void sqlite3_result_null(sqlite3_context*);
   469         -   void sqlite3_result_text(sqlite3_context*, const char*, int n, void(*)(void*));
   470         -   void sqlite3_result_text16(sqlite3_context*, const void*, int n, void(*)(void*));
   471         -   void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
   472         -   void *sqlite3_get_auxdata(sqlite3_context*, int);
   473         -   void sqlite3_set_auxdata(sqlite3_context*, int, void*, void (*)(void*));
   474         -</pre></blockquote>
   475         -
   476         -<h4>2.4 User-defined collating sequences</h4>
   477         -
   478         -<p>
   479         -The following routines are used to implement user-defined
   480         -collating sequences:
   481         -</p>
   482         -
   483         -<blockquote><pre>
   484         -   sqlite3_create_collation(sqlite3*, const char *zName, int eTextRep, void*,
   485         -      int(*xCompare)(void*,int,const void*,int,const void*));
   486         -   sqlite3_create_collation16(sqlite3*, const void *zName, int eTextRep, void*,
   487         -      int(*xCompare)(void*,int,const void*,int,const void*));
   488         -   sqlite3_collation_needed(sqlite3*, void*, 
   489         -      void(*)(void*,sqlite3*,int eTextRep,const char*));
   490         -   sqlite3_collation_needed16(sqlite3*, void*,
   491         -      void(*)(void*,sqlite3*,int eTextRep,const void*));
   492         -</pre></blockquote>
   493         -
   494         -<p>
   495         -The sqlite3_create_collation() function specifies a collating sequence name
   496         -and a comparison function to implement that collating sequence.  The
   497         -comparison function is only used for comparing text values.  The eTextRep
   498         -parameter is one of SQLITE_UTF8, SQLITE_UTF16LE, SQLITE_UTF16BE, or
   499         -SQLITE_ANY to specify which text representation the comparison function works
   500         -with.  Separate comparison functions can exist for the same collating
   501         -sequence for each of the UTF-8, UTF-16LE and UTF-16BE text representations.
   502         -The sqlite3_create_collation16() works like sqlite3_create_collation() except
   503         -that the collation name is specified in UTF-16 host byte order instead of
   504         -in UTF-8.
   505         -</p>
   506         -
   507         -<p>
   508         -The sqlite3_collation_needed() routine registers a callback which the
   509         -database engine will invoke if it encounters an unknown collating sequence.
   510         -The callback can lookup an appropriate comparison function and invoke
   511         -sqlite_3_create_collation() as needed.  The fourth parameter to the callback
   512         -is the name of the collating sequence in UTF-8.  For sqlite3_collation_need16()
   513         -the callback sends the collating sequence name in UTF-16 host byte order.
   514         -</p>
   515         -}
   516         -footer $rcsid

Deleted www/capi3ref.tcl.

     1         -set rcsid {$Id: capi3ref.tcl,v 1.60 2007/05/19 06:48:43 danielk1977 Exp $}
     2         -source common.tcl
     3         -header {C/C++ Interface For SQLite Version 3}
     4         -puts {
     5         -<h2 class=pdf_section>C/C++ Interface For SQLite Version 3</h2>
     6         -}
     7         -
     8         -proc api {name prototype desc {notused x}} {
     9         -  global apilist specialname
    10         -  if {$name==""} {
    11         -    regsub -all {sqlite3_[a-z0-9_]+\(} $prototype \
    12         -      {[lappend name [string trimright & (]]} x1
    13         -    subst $x1
    14         -  } else {
    15         -    lappend specialname $name
    16         -  }
    17         -  lappend apilist [list $name $prototype $desc]
    18         -}
    19         -
    20         -api {extended-result-codes} {
    21         -#define SQLITE_IOERR_READ       
    22         -#define SQLITE_IOERR_SHORT_READ 
    23         -#define SQLITE_IOERR_WRITE      
    24         -#define SQLITE_IOERR_FSYNC      
    25         -#define SQLITE_IOERR_DIR_FSYNC  
    26         -#define SQLITE_IOERR_TRUNCATE   
    27         -#define SQLITE_IOERR_FSTAT      
    28         -#define SQLITE_IOERR_UNLOCK     
    29         -#define SQLITE_IOERR_RDLOCK     
    30         -...
    31         -} {
    32         -In its default configuration, SQLite API routines return one of 26 integer
    33         -result codes described at result-codes.  However, experience has shown that
    34         -many of these result codes are too course-grained.  They do not provide as
    35         -much information about problems as users might like.  In an effort to
    36         -address this, newer versions of SQLite (version 3.3.8 and later) include
    37         -support for additional result codes that provide more detailed information
    38         -about errors.  The extended result codes are enabled (or disabled) for 
    39         -each database
    40         -connection using the sqlite3_extended_result_codes() API.
    41         -
    42         -Some of the available extended result codes are listed above.
    43         -We expect the number of extended result codes will be expand
    44         -over time.  Software that uses extended result codes should expect
    45         -to see new result codes in future releases of SQLite.
    46         -
    47         -The symbolic name for an extended result code always contains a related
    48         -primary result code as a prefix.  Primary result codes contain a single
    49         -"_" character.  Extended result codes contain two or more "_" characters.
    50         -The numeric value of an extended result code can be converted to its
    51         -corresponding primary result code by masking off the lower 8 bytes.
    52         -
    53         -A complete list of available extended result codes and
    54         -details about the meaning of the various extended result codes can be
    55         -found by consulting the C code, especially the sqlite3.h header
    56         -file and its antecedent sqlite.h.in.  Additional information
    57         -is also available at the SQLite wiki:
    58         -http://www.sqlite.org/cvstrac/wiki?p=ExtendedResultCodes
    59         -}
    60         -
    61         -
    62         -api {result-codes} {
    63         -#define SQLITE_OK           0   /* Successful result */
    64         -#define SQLITE_ERROR        1   /* SQL error or missing database */
    65         -#define SQLITE_INTERNAL     2   /* An internal logic error in SQLite */
    66         -#define SQLITE_PERM         3   /* Access permission denied */
    67         -#define SQLITE_ABORT        4   /* Callback routine requested an abort */
    68         -#define SQLITE_BUSY         5   /* The database file is locked */
    69         -#define SQLITE_LOCKED       6   /* A table in the database is locked */
    70         -#define SQLITE_NOMEM        7   /* A malloc() failed */
    71         -#define SQLITE_READONLY     8   /* Attempt to write a readonly database */
    72         -#define SQLITE_INTERRUPT    9   /* Operation terminated by sqlite_interrupt() */
    73         -#define SQLITE_IOERR       10   /* Some kind of disk I/O error occurred */
    74         -#define SQLITE_CORRUPT     11   /* The database disk image is malformed */
    75         -#define SQLITE_NOTFOUND    12   /* (Internal Only) Table or record not found */
    76         -#define SQLITE_FULL        13   /* Insertion failed because database is full */
    77         -#define SQLITE_CANTOPEN    14   /* Unable to open the database file */
    78         -#define SQLITE_PROTOCOL    15   /* Database lock protocol error */
    79         -#define SQLITE_EMPTY       16   /* (Internal Only) Database table is empty */
    80         -#define SQLITE_SCHEMA      17   /* The database schema changed */
    81         -#define SQLITE_TOOBIG      18   /* Too much data for one row of a table */
    82         -#define SQLITE_CONSTRAINT  19   /* Abort due to constraint violation */
    83         -#define SQLITE_MISMATCH    20   /* Data type mismatch */
    84         -#define SQLITE_MISUSE      21   /* Library used incorrectly */
    85         -#define SQLITE_NOLFS       22   /* Uses OS features not supported on host */
    86         -#define SQLITE_AUTH        23   /* Authorization denied */
    87         -#define SQLITE_ROW         100  /* sqlite_step() has another row ready */
    88         -#define SQLITE_DONE        101  /* sqlite_step() has finished executing */
    89         -} {
    90         -Many SQLite functions return an integer result code from the set shown
    91         -above in order to indicates success or failure.
    92         -
    93         -The result codes above are the only ones returned by SQLite in its
    94         -default configuration.  However, the sqlite3_extended_result_codes()
    95         -API can be used to set a database connectoin to return more detailed
    96         -result codes.  See the documentation on sqlite3_extended_result_codes()
    97         -or extended-result-codes for additional information.
    98         -}
    99         -
   100         -api {} {
   101         -  int sqlite3_extended_result_codes(sqlite3*, int onoff);
   102         -} {
   103         -This routine enables or disabled extended-result-codes feature.
   104         -By default, SQLite API routines return one of only 26 integer
   105         -result codes described at result-codes.  When extended result codes
   106         -are enabled by this routine, the repetoire of result codes can be
   107         -much larger and can (hopefully) provide more detailed information
   108         -about the cause of an error.
   109         -
   110         -The second argument is a boolean value that turns extended result
   111         -codes on and off.  Extended result codes are off by default for
   112         -backwards compatibility with older versions of SQLite.
   113         -}
   114         -
   115         -api {} {
   116         -  const char *sqlite3_libversion(void);
   117         -} {
   118         -  Return a pointer to a string which contains the version number of
   119         -  the library.  The same string is available in the global
   120         -  variable named "sqlite3_version".  This interface is provided since
   121         -  windows is unable to access global variables in DLLs.
   122         -}
   123         -
   124         -api {} {
   125         -  void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);
   126         -} {
   127         -  Aggregate functions use this routine to allocate
   128         -  a structure for storing their state.  The first time this routine
   129         -  is called for a particular aggregate, a new structure of size nBytes
   130         -  is allocated, zeroed, and returned.  On subsequent calls (for the
   131         -  same aggregate instance) the same buffer is returned.  The implementation
   132         -  of the aggregate can use the returned buffer to accumulate data.
   133         -
   134         -  The buffer is freed automatically by SQLite when the query that
   135         -  invoked the aggregate function terminates.
   136         -}
   137         -
   138         -api {} {
   139         -  int sqlite3_aggregate_count(sqlite3_context*);
   140         -} {
   141         -  This function is deprecated.   It continues to exist so as not to
   142         -  break any legacy code that might happen to use it.  But it should not
   143         -  be used in any new code.
   144         -
   145         -  In order to encourage people to not use this function, we are not going
   146         -  to tell you what it does.
   147         -}
   148         -
   149         -api {} {
   150         -  int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
   151         -  int sqlite3_bind_double(sqlite3_stmt*, int, double);
   152         -  int sqlite3_bind_int(sqlite3_stmt*, int, int);
   153         -  int sqlite3_bind_int64(sqlite3_stmt*, int, long long int);
   154         -  int sqlite3_bind_null(sqlite3_stmt*, int);
   155         -  int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*));
   156         -  int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
   157         -  #define SQLITE_STATIC      ((void(*)(void *))0)
   158         -  #define SQLITE_TRANSIENT   ((void(*)(void *))-1)
   159         -} {
   160         - In the SQL strings input to sqlite3_prepare_v2() and sqlite3_prepare16_v2(),
   161         - one or more literals can be replace by a parameter "?" or "?NNN"
   162         - or ":AAA" or "@AAA" or "\$VVV" where NNN is an integer literal,
   163         - AAA is an alphanumeric identifier and VVV is a variable name according
   164         - to the syntax rules of the TCL programming language.
   165         - The values of these parameters (also called "host parameter names")
   166         - can be set using the sqlite3_bind_*() routines.
   167         -
   168         - The first argument to the sqlite3_bind_*() routines always is a pointer
   169         - to the sqlite3_stmt structure returned from sqlite3_prepare_v2().  The second
   170         - argument is the index of the parameter to be set.  The first parameter has
   171         - an index of 1. When the same named parameter is used more than once, second
   172         - and subsequent
   173         - occurrences have the same index as the first occurrence.  The index for
   174         - named parameters can be looked up using the
   175         - sqlite3_bind_parameter_name() API if desired.  The index for "?NNN"
   176         - parametes is the value of NNN.  The NNN value must be between 1 and 999.
   177         -
   178         -
   179         - The third argument is the value to bind to the parameter.
   180         -
   181         - In those
   182         - routines that have a fourth argument, its value is the number of bytes
   183         - in the parameter.  To be clear: the value is the number of bytes in the
   184         - string, not the number of characters.  The number
   185         - of bytes does not include the zero-terminator at the end of strings.
   186         - If the fourth parameter is negative, the length of the string is
   187         - number of bytes up to the first zero terminator.
   188         -
   189         - The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and
   190         - sqlite3_bind_text16() is a destructor used to dispose of the BLOB or
   191         - text after SQLite has finished with it.  If the fifth argument is the
   192         - special value SQLITE_STATIC, then the library assumes that the information
   193         - is in static, unmanaged space and does not need to be freed.  If the
   194         - fifth argument has the value SQLITE_TRANSIENT, then SQLite makes its
   195         - own private copy of the data immediately, before the sqlite3_bind_*()
   196         - routine returns.
   197         -
   198         - The sqlite3_bind_*() routines must be called after
   199         - sqlite3_prepare_v2() or sqlite3_reset() and before sqlite3_step().
   200         - Bindings are not cleared by the sqlite3_reset() routine.
   201         - Unbound parameters are interpreted as NULL.
   202         -
   203         - These routines return SQLITE_OK on success or an error code if
   204         - anything goes wrong.  SQLITE_RANGE is returned if the parameter
   205         - index is out of range.  SQLITE_NOMEM is returned if malloc fails.
   206         - SQLITE_MISUSE is returned if these routines are called on a virtual
   207         - machine that is the wrong state or which has already been finalized.
   208         -}
   209         -
   210         -api {} {
   211         -  int sqlite3_bind_parameter_count(sqlite3_stmt*);
   212         -} {
   213         -  Return the number of parameters in the precompiled statement given as
   214         -  the argument.
   215         -}
   216         -
   217         -api {} {
   218         -  const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int n);
   219         -} {
   220         -  Return the name of the n-th parameter in the precompiled statement.
   221         -  Parameters of the form ":AAA" or "@AAA" or "\$VVV" have a name which is the
   222         -  string ":AAA" or "@AAA" or "\$VVV".  
   223         -  In other words, the initial ":" or "$" or "@"
   224         -  is included as part of the name.
   225         -  Parameters of the form "?" or "?NNN" have no name.
   226         -
   227         -  The first bound parameter has an index of 1, not 0.
   228         -
   229         -  If the value n is out of range or if the n-th parameter is nameless,
   230         -  then NULL is returned.  The returned string is always in the
   231         -  UTF-8 encoding even if the named parameter was originally specified
   232         -  as UTF-16 in sqlite3_prepare16_v2().
   233         -}
   234         -
   235         -api {} {
   236         -  int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);
   237         -} {
   238         -  Return the index of the parameter with the given name.
   239         -  The name must match exactly.
   240         -  If there is no parameter with the given name, return 0.
   241         -  The string zName is always in the UTF-8 encoding.
   242         -}
   243         -
   244         -api {} {
   245         -  int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);
   246         -} {
   247         - This routine identifies a callback function that might be invoked
   248         - whenever an attempt is made to open a database table 
   249         - that another thread or process has locked.
   250         - If the busy callback is NULL, then SQLITE_BUSY is returned immediately
   251         - upon encountering the lock.
   252         - If the busy callback is not NULL, then the
   253         - callback will be invoked with two arguments.  The
   254         - first argument to the handler is a copy of the void* pointer which
   255         - is the third argument to this routine.  The second argument to
   256         - the handler is the number of times that the busy handler has
   257         - been invoked for this locking event. If the
   258         - busy callback returns 0, then no additional attempts are made to
   259         - access the database and SQLITE_BUSY is returned.
   260         - If the callback returns non-zero, then another attempt is made to open the
   261         - database for reading and the cycle repeats.
   262         -
   263         - The presence of a busy handler does not guarantee that
   264         - it will be invoked when there is lock contention.
   265         - If SQLite determines that invoking the busy handler could result in
   266         - a deadlock, it will return SQLITE_BUSY instead.
   267         - Consider a scenario where one process is holding a read lock that
   268         - it is trying to promote to a reserved lock and
   269         - a second process is holding a reserved lock that it is trying
   270         - to promote to an exclusive lock.  The first process cannot proceed
   271         - because it is blocked by the second and the second process cannot
   272         - proceed because it is blocked by the first.  If both processes
   273         - invoke the busy handlers, neither will make any progress.  Therefore,
   274         - SQLite returns SQLITE_BUSY for the first process, hoping that this
   275         - will induce the first process to release its read lock and allow
   276         - the second process to proceed.
   277         -
   278         - The default busy callback is NULL.
   279         -
   280         - Sqlite is re-entrant, so the busy handler may start a new query. 
   281         - (It is not clear why anyone would every want to do this, but it
   282         - is allowed, in theory.)  But the busy handler may not close the
   283         - database.  Closing the database from a busy handler will delete 
   284         - data structures out from under the executing query and will 
   285         - probably result in a coredump.
   286         -
   287         - There can only be a single busy handler defined for each database
   288         - connection.  Setting a new busy handler clears any previous one.
   289         - Note that calling sqlite3_busy_timeout() will also set or clear
   290         - the busy handler.
   291         -}
   292         -
   293         -api {} {
   294         -  int sqlite3_busy_timeout(sqlite3*, int ms);
   295         -} {
   296         - This routine sets a busy handler that sleeps for a while when a
   297         - table is locked.  The handler will sleep multiple times until 
   298         - at least "ms" milliseconds of sleeping have been done.  After
   299         - "ms" milliseconds of sleeping, the handler returns 0 which
   300         - causes sqlite3_exec() to return SQLITE_BUSY.
   301         -
   302         - Calling this routine with an argument less than or equal to zero
   303         - turns off all busy handlers.
   304         -
   305         - There can only be a single busy handler for a particular database
   306         - connection.  If another busy handler was defined  
   307         - (using sqlite3_busy_handler()) prior to calling
   308         - this routine, that other busy handler is cleared.
   309         -}
   310         -
   311         -api {} {
   312         -  int sqlite3_changes(sqlite3*);
   313         -} {
   314         - This function returns the number of database rows that were changed
   315         - (or inserted or deleted) by the most recently completed
   316         - INSERT, UPDATE, or DELETE
   317         - statement.  Only changes that are directly specified by the INSERT,
   318         - UPDATE, or DELETE statement are counted.  Auxiliary changes caused by
   319         - triggers are not counted.  Use the sqlite3_total_changes() function
   320         - to find the total number of changes including changes caused by triggers.
   321         -
   322         - Within the body of a trigger, the sqlite3_changes() function does work
   323         - to report the number of rows that were changed for the most recently
   324         - completed INSERT, UPDATE, or DELETE statement within the trigger body.
   325         -
   326         - SQLite implements the command "DELETE FROM table" without a WHERE clause
   327         - by dropping and recreating the table.  (This is much faster than going
   328         - through and deleting individual elements from the table.)  Because of
   329         - this optimization, the change count for "DELETE FROM table" will be
   330         - zero regardless of the number of elements that were originally in the
   331         - table. To get an accurate count of the number of rows deleted, use
   332         - "DELETE FROM table WHERE 1" instead.
   333         -}
   334         -
   335         -api {} {
   336         -  int sqlite3_total_changes(sqlite3*);
   337         -} {
   338         -  This function returns the total number of database rows that have
   339         -  be modified, inserted, or deleted since the database connection was
   340         -  created using sqlite3_open().  All changes are counted, including
   341         -  changes by triggers and changes to TEMP and auxiliary databases.
   342         -  Except, changes to the SQLITE_MASTER table (caused by statements 
   343         -  such as CREATE TABLE) are not counted.  Nor are changes counted when
   344         -  an entire table is deleted using DROP TABLE.
   345         -
   346         -  See also the sqlite3_changes() API.
   347         -
   348         -  SQLite implements the command "DELETE FROM table" without a WHERE clause
   349         -  by dropping and recreating the table.  (This is much faster than going
   350         -  through and deleting individual elements form the table.)  Because of
   351         -  this optimization, the change count for "DELETE FROM table" will be
   352         -  zero regardless of the number of elements that were originally in the
   353         -  table. To get an accurate count of the number of rows deleted, use
   354         -  "DELETE FROM table WHERE 1" instead.
   355         -}
   356         -
   357         -api {} {
   358         -  int sqlite3_close(sqlite3*);
   359         -} {
   360         -  Call this function with a pointer to a structure that was previously
   361         -  returned from sqlite3_open() or sqlite3_open16()
   362         -  and the corresponding database will by closed.
   363         -
   364         -  SQLITE_OK is returned if the close is successful.  If there are
   365         -  prepared statements that have not been finalized, then SQLITE_BUSY
   366         -  is returned.  SQLITE_ERROR might be returned if the argument is not
   367         -  a valid connection pointer returned by sqlite3_open() or if the connection
   368         -  pointer has been closed previously.
   369         -}
   370         -
   371         -api {} {
   372         -const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
   373         -int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
   374         -int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
   375         -double sqlite3_column_double(sqlite3_stmt*, int iCol);
   376         -int sqlite3_column_int(sqlite3_stmt*, int iCol);
   377         -long long int sqlite3_column_int64(sqlite3_stmt*, int iCol);
   378         -const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
   379         -const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
   380         -int sqlite3_column_type(sqlite3_stmt*, int iCol);
   381         -#define SQLITE_INTEGER  1
   382         -#define SQLITE_FLOAT    2
   383         -#define SQLITE_TEXT     3
   384         -#define SQLITE_BLOB     4
   385         -#define SQLITE_NULL     5
   386         -} {
   387         - These routines return information about the information
   388         - in a single column of the current result row of a query.  In every
   389         - case the first argument is a pointer to the SQL statement that is being
   390         - executed (the sqlite_stmt* that was returned from sqlite3_prepare_v2()) and
   391         - the second argument is the index of the column for which information 
   392         - should be returned.  iCol is zero-indexed.  The left-most column has an
   393         - index of 0.
   394         -
   395         - If the SQL statement is not currently point to a valid row, or if the
   396         - the column index is out of range, the result is undefined.
   397         -
   398         - The sqlite3_column_type() routine returns the initial data type
   399         - of the result column.  The returned value is one of SQLITE_INTEGER,
   400         - SQLITE_FLOAT, SQLITE_TEXT, SQLITE_BLOB, or SQLITE_NULL.  The value
   401         - returned by sqlite3_column_type() is only meaningful if no type
   402         - conversions have occurred as described below.  After a type conversion,
   403         - the value returned by sqlite3_column_type() is undefined.  Future
   404         - versions of SQLite may change the behavior of sqlite3_column_type()
   405         - following a type conversion.
   406         -
   407         - If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes() 
   408         - routine returns the number of bytes in that BLOB or string.
   409         - If the result is a UTF-16 string, then sqlite3_column_bytes() converts
   410         - the string to UTF-8 and then returns the number of bytes.
   411         - If the result is a numeric value then sqlite3_column_bytes() uses
   412         - sqlite3_snprintf() to convert that value to a UTF-8 string and returns
   413         - the number of bytes in that string.
   414         - The value returned does
   415         - not include the \\000 terminator at the end of the string.  
   416         -
   417         - The sqlite3_column_bytes16() routine is similar to sqlite3_column_bytes()
   418         - but leaves the result in UTF-16 instead of UTF-8.  
   419         - The \\u0000 terminator is not included in this count.
   420         -
   421         - These routines attempt to convert the value where appropriate.  For
   422         - example, if the internal representation is FLOAT and a text result
   423         - is requested, sqlite3_snprintf() is used internally to do the conversion
   424         - automatically.  The following table details the conversions that
   425         - are applied:
   426         -
   427         -<blockquote>
   428         -<table border="1">
   429         -<tr><th>Internal Type</th><th>Requested Type</th><th>Conversion</th></tr>
   430         -<tr><td> NULL    </td><td> INTEGER</td><td>Result is 0</td></tr>
   431         -<tr><td> NULL </td><td>    FLOAT </td><td> Result is 0.0</td></tr>
   432         -<tr><td> NULL </td><td>    TEXT </td><td>  Result is NULL pointer</td></tr>
   433         -<tr><td> NULL </td><td>    BLOB </td><td>  Result is NULL pointer</td></tr>
   434         -<tr><td> INTEGER </td><td> FLOAT </td><td> Convert from integer to float</td></tr>
   435         -<tr><td> INTEGER </td><td> TEXT </td><td>  ASCII rendering of the integer</td></tr>
   436         -<tr><td> INTEGER </td><td> BLOB </td><td>  Same as for INTEGER->TEXT</td></tr>
   437         -<tr><td> FLOAT </td><td>   INTEGER</td><td>Convert from float to integer</td></tr>
   438         -<tr><td> FLOAT </td><td>   TEXT </td><td>  ASCII rendering of the float</td></tr>
   439         -<tr><td> FLOAT </td><td>   BLOB </td><td>  Same as FLOAT->TEXT</td></tr>
   440         -<tr><td> TEXT </td><td>    INTEGER</td><td>Use atoi()</td></tr>
   441         -<tr><td> TEXT </td><td>    FLOAT </td><td> Use atof()</td></tr>
   442         -<tr><td> TEXT </td><td>    BLOB </td><td>  No change</td></tr>
   443         -<tr><td> BLOB </td><td>    INTEGER</td><td>Convert to TEXT then use atoi()</td></tr>
   444         -<tr><td> BLOB </td><td>    FLOAT </td><td> Convert to TEXT then use atof()</td></tr>
   445         -<tr><td> BLOB </td><td>    TEXT </td><td>  Add a \\000 terminator if needed</td></tr>
   446         -</table>
   447         -</blockquote>
   448         -
   449         -  Note that when type conversions occur, pointers returned by prior
   450         -  calls to sqlite3_column_blob(), sqlite3_column_text(), and/or
   451         -  sqlite3_column_text16() may be invalidated. 
   452         -  Type conversions and pointer invalidations might occur
   453         -  in the following cases:
   454         -
   455         -  <ul>
   456         -  <li><p>
   457         -  The initial content is a BLOB and sqlite3_column_text() 
   458         -  or sqlite3_column_text16()
   459         -  is called.  A zero-terminator might need to be added to the string.
   460         -  </p></li>
   461         -  <li><p>
   462         -  The initial content is UTF-8 text and sqlite3_column_bytes16() or
   463         -  sqlite3_column_text16() is called.  The content must be converted to UTF-16.
   464         -  </p></li>
   465         -  <li><p>
   466         -  The initial content is UTF-16 text and sqlite3_column_bytes() or
   467         -  sqlite3_column_text() is called.  The content must be converted to UTF-8.
   468         -  </p></li>
   469         -  </ul>
   470         -
   471         -  Conversions between UTF-16be and UTF-16le 
   472         -  are always done in place and do
   473         -  not invalidate a prior pointer, though of course the content of the buffer
   474         -  that the prior pointer points to will have been modified.  Other kinds
   475         -  of conversion are done in place when it is possible, but sometime it is
   476         -  not possible and in those cases prior pointers are invalidated.  
   477         -
   478         -  The safest and easiest to remember policy is to invoke these routines
   479         -  in one of the following ways:
   480         -
   481         -  <ul>
   482         -  <li>sqlite3_column_text() followed by sqlite3_column_bytes()</li>
   483         -  <li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li>
   484         -  <li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li>
   485         -  </ul>
   486         -
   487         -  In other words, you should call sqlite3_column_text(), sqlite3_column_blob(),
   488         -  or sqlite3_column_text16() first to force the result into the desired
   489         -  format, then invoke sqlite3_column_bytes() or sqlite3_column_bytes16() to
   490         -  find the size of the result.  Do not mix call to sqlite3_column_text() or
   491         -  sqlite3_column_blob() with calls to sqlite3_column_bytes16().  And do not
   492         -  mix calls to sqlite3_column_text16() with calls to sqlite3_column_bytes().
   493         -}
   494         -
   495         -api {} {
   496         -int sqlite3_column_count(sqlite3_stmt *pStmt);
   497         -} {
   498         - Return the number of columns in the result set returned by the prepared
   499         - SQL statement. This routine returns 0 if pStmt is an SQL statement
   500         - that does not return data (for example an UPDATE).
   501         -
   502         - See also sqlite3_data_count().
   503         -}
   504         -
   505         -api {} {
   506         -const char *sqlite3_column_decltype(sqlite3_stmt *, int i);
   507         -const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
   508         -} {
   509         - The first argument is a prepared SQL statement. If this statement
   510         - is a SELECT statement, the Nth column of the returned result set 
   511         - of the SELECT is a table column then the declared type of the table
   512         - column is returned. If the Nth column of the result set is not a table
   513         - column, then a NULL pointer is returned. The returned string is 
   514         - UTF-8 encoded for sqlite3_column_decltype() and UTF-16 encoded
   515         - for sqlite3_column_decltype16(). For example, in the database schema:
   516         -
   517         - <blockquote><pre>
   518         - CREATE TABLE t1(c1 INTEGER);
   519         - </pre></blockquote>
   520         -
   521         - And the following statement compiled:
   522         -
   523         - <blockquote><pre>
   524         - SELECT c1 + 1, c1 FROM t1;
   525         - </pre></blockquote>
   526         -
   527         - Then this routine would return the string "INTEGER" for the second
   528         - result column (i==1), and a NULL pointer for the first result column
   529         - (i==0).
   530         -
   531         - If the following statements were compiled then this routine would
   532         - return "INTEGER" for the first (only) result column.
   533         -
   534         - <blockquote><pre>
   535         - SELECT (SELECT c1) FROM t1;
   536         - SELECT (SELECT c1 FROM t1);
   537         - SELECT c1 FROM (SELECT c1 FROM t1);
   538         - SELECT * FROM (SELECT c1 FROM t1);
   539         - SELECT * FROM (SELECT * FROM t1);
   540         - </pre></blockquote>
   541         -}
   542         -
   543         -api {} {
   544         -  int sqlite3_table_column_metadata(
   545         -    sqlite3 *db,                /* Connection handle */
   546         -    const char *zDbName,        /* Database name or NULL */
   547         -    const char *zTableName,     /* Table name */
   548         -    const char *zColumnName,    /* Column name */
   549         -    char const **pzDataType,    /* OUTPUT: Declared data type */
   550         -    char const **pzCollSeq,     /* OUTPUT: Collation sequence name */
   551         -    int *pNotNull,              /* OUTPUT: True if NOT NULL constraint exists */
   552         -    int *pPrimaryKey,           /* OUTPUT: True if column part of PK */
   553         -    int *pAutoinc               /* OUTPUT: True if colums is auto-increment */
   554         -  );
   555         -} {
   556         - This routine is used to obtain meta information about a specific column of a
   557         - specific database table accessible using the connection handle passed as the
   558         - first function argument.
   559         -
   560         - The column is identified by the second, third and fourth parameters to 
   561         - this function. The second parameter is either the name of the database
   562         - (i.e. "main", "temp" or an attached database) containing the specified
   563         - table or NULL. If it is NULL, then all attached databases are searched
   564         - for the table using the same algorithm as the database engine uses to 
   565         - resolve unqualified table references.
   566         -
   567         - The third and fourth parameters to this function are the table and column 
   568         - name of the desired column, respectively. Neither of these parameters 
   569         - may be NULL.
   570         -
   571         - Meta information is returned by writing to the memory locations passed as
   572         - the 5th and subsequent parameters to this function. Any of these 
   573         - arguments may be NULL, in which case the corresponding element of meta 
   574         - information is ommitted.
   575         -
   576         -<pre>
   577         - Parameter     Output Type      Description
   578         - -----------------------------------
   579         -   5th         const char*      Declared data type 
   580         -   6th         const char*      Name of the columns default collation sequence 
   581         -   7th         int              True if the column has a NOT NULL constraint
   582         -   8th         int              True if the column is part of the PRIMARY KEY
   583         -   9th         int              True if the column is AUTOINCREMENT
   584         -</pre>
   585         -
   586         - The memory pointed to by the character pointers returned for the 
   587         - declaration type and collation sequence is valid only until the next 
   588         - call to any sqlite API function.
   589         -
   590         - This function may load one or more schemas from database files. If an
   591         - error occurs during this process, or if the requested table or column
   592         - cannot be found, an SQLITE error code is returned and an error message
   593         - left in the database handle (to be retrieved using sqlite3_errmsg()).
   594         - Specifying an SQL view instead of a table as the third argument is also
   595         - considered an error.
   596         -
   597         - If the specified column is "rowid", "oid" or "_rowid_" and an 
   598         - INTEGER PRIMARY KEY column has been explicitly declared, then the output 
   599         - parameters are set for the explicitly declared column. If there is no
   600         - explicitly declared IPK column, then the data-type is "INTEGER", the
   601         - collation sequence "BINARY" and the primary-key flag is set. Both
   602         - the not-null and auto-increment flags are clear.
   603         -
   604         - This API is only available if the library was compiled with the
   605         - SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined.
   606         -}
   607         -
   608         -api {} {
   609         -const char *sqlite3_column_database_name(sqlite3_stmt *pStmt, int N);
   610         -const void *sqlite3_column_database_name16(sqlite3_stmt *pStmt, int N);
   611         -} {
   612         -If the Nth column returned by statement pStmt is a column reference,
   613         -these functions may be used to access the name of the database (either 
   614         -"main", "temp" or the name of an attached database) that contains
   615         -the column. If the Nth column is not a column reference, NULL is
   616         -returned.
   617         -
   618         -See the description of function sqlite3_column_decltype() for a
   619         -description of exactly which expressions are considered column references.
   620         -
   621         -Function sqlite3_column_database_name() returns a pointer to a UTF-8
   622         -encoded string. sqlite3_column_database_name16() returns a pointer
   623         -to a UTF-16 encoded string. 
   624         -}
   625         -
   626         -api {} {
   627         -const char *sqlite3_column_origin_name(sqlite3_stmt *pStmt, int N);
   628         -const void *sqlite3_column_origin_name16(sqlite3_stmt *pStmt, int N);
   629         -} {
   630         -If the Nth column returned by statement pStmt is a column reference,
   631         -these functions may be used to access the schema name of the referenced 
   632         -column in the database schema. If the Nth column is not a column 
   633         -reference, NULL is returned.
   634         -
   635         -See the description of function sqlite3_column_decltype() for a
   636         -description of exactly which expressions are considered column references.
   637         -
   638         -Function sqlite3_column_origin_name() returns a pointer to a UTF-8
   639         -encoded string. sqlite3_column_origin_name16() returns a pointer
   640         -to a UTF-16 encoded string. 
   641         -}
   642         -
   643         -api {} {
   644         -const char *sqlite3_column_table_name(sqlite3_stmt *pStmt, int N);
   645         -const void *sqlite3_column_table_name16(sqlite3_stmt *pStmt, int N);
   646         -} {
   647         -If the Nth column returned by statement pStmt is a column reference, 
   648         -these functions may be used to access the name of the table that 
   649         -contains the column.  If the Nth column is not a column reference, 
   650         -NULL is returned.
   651         -
   652         -See the description of function sqlite3_column_decltype() for a
   653         -description of exactly which expressions are considered column references.
   654         -
   655         -Function sqlite3_column_table_name() returns a pointer to a UTF-8
   656         -encoded string. sqlite3_column_table_name16() returns a pointer
   657         -to a UTF-16 encoded string. 
   658         -}
   659         -
   660         -api {} {
   661         -const char *sqlite3_column_name(sqlite3_stmt*,int);
   662         -const void *sqlite3_column_name16(sqlite3_stmt*,int);
   663         -} {
   664         - The first argument is a prepared SQL statement. This function returns
   665         - the column heading for the Nth column of that statement, where N is the
   666         - second function argument.  The string returned is UTF-8 for
   667         - sqlite3_column_name() and UTF-16 for sqlite3_column_name16().
   668         -}
   669         -
   670         -api {} {
   671         -void *sqlite3_commit_hook(sqlite3*, int(*xCallback)(void*), void *pArg);
   672         -} {
   673         - <i>Experimental</i>
   674         -
   675         - Register a callback function to be invoked whenever a new transaction
   676         - is committed.  The pArg argument is passed through to the callback.
   677         - callback.  If the callback function returns non-zero, then the commit
   678         - is converted into a rollback.
   679         -
   680         - If another function was previously registered, its pArg value is returned.
   681         - Otherwise NULL is returned.
   682         -
   683         - Registering a NULL function disables the callback.  Only a single commit
   684         - hook callback can be registered at a time.
   685         -}
   686         -
   687         -api {} {
   688         -int sqlite3_complete(const char *sql);
   689         -int sqlite3_complete16(const void *sql);
   690         -} {
   691         - These functions return true if the given input string comprises
   692         - one or more complete SQL statements.
   693         - The argument must be a nul-terminated UTF-8 string for sqlite3_complete()
   694         - and a nul-terminated UTF-16 string for sqlite3_complete16().
   695         -
   696         - These routines do not check to see if the SQL statement is well-formed.
   697         - They only check to see that the statement is terminated by a semicolon
   698         - that is not part of a string literal and is not inside
   699         - the body of a trigger.
   700         -} {}
   701         -
   702         -api {} {
   703         -int sqlite3_create_collation(
   704         -  sqlite3*, 
   705         -  const char *zName, 
   706         -  int pref16, 
   707         -  void*,
   708         -  int(*xCompare)(void*,int,const void*,int,const void*)
   709         -);
   710         -int sqlite3_create_collation16(
   711         -  sqlite3*, 
   712         -  const char *zName, 
   713         -  int pref16, 
   714         -  void*,
   715         -  int(*xCompare)(void*,int,const void*,int,const void*)
   716         -);
   717         -#define SQLITE_UTF8     1
   718         -#define SQLITE_UTF16BE  2
   719         -#define SQLITE_UTF16LE  3
   720         -#define SQLITE_UTF16    4
   721         -} {
   722         - These two functions are used to add new collation sequences to the
   723         - sqlite3 handle specified as the first argument. 
   724         -
   725         - The name of the new collation sequence is specified as a UTF-8 string
   726         - for sqlite3_create_collation() and a UTF-16 string for
   727         - sqlite3_create_collation16(). In both cases the name is passed as the
   728         - second function argument.
   729         -
   730         - The third argument must be one of the constants SQLITE_UTF8,
   731         - SQLITE_UTF16LE or SQLITE_UTF16BE, indicating that the user-supplied
   732         - routine expects to be passed pointers to strings encoded using UTF-8,
   733         - UTF-16 little-endian or UTF-16 big-endian respectively.  The
   734         - SQLITE_UTF16 constant indicates that text strings are expected in
   735         - UTF-16 in the native byte order of the host machine.
   736         -
   737         - A pointer to the user supplied routine must be passed as the fifth
   738         - argument. If it is NULL, this is the same as deleting the collation
   739         - sequence (so that SQLite cannot call it anymore). Each time the user
   740         - supplied function is invoked, it is passed a copy of the void* passed as
   741         - the fourth argument to sqlite3_create_collation() or
   742         - sqlite3_create_collation16() as its first argument.
   743         -
   744         - The remaining arguments to the user-supplied routine are two strings,
   745         - each represented by a [length, data] pair and encoded in the encoding
   746         - that was passed as the third argument when the collation sequence was
   747         - registered. The user routine should return negative, zero or positive if
   748         - the first string is less than, equal to, or greater than the second
   749         - string. i.e. (STRING1 - STRING2).
   750         -}
   751         -
   752         -api {} {
   753         -int sqlite3_collation_needed(
   754         -  sqlite3*, 
   755         -  void*, 
   756         -  void(*)(void*,sqlite3*,int eTextRep,const char*)
   757         -);
   758         -int sqlite3_collation_needed16(
   759         -  sqlite3*, 
   760         -  void*,
   761         -  void(*)(void*,sqlite3*,int eTextRep,const void*)
   762         -);
   763         -} {
   764         - To avoid having to register all collation sequences before a database
   765         - can be used, a single callback function may be registered with the
   766         - database handle to be called whenever an undefined collation sequence is
   767         - required.
   768         -
   769         - If the function is registered using the sqlite3_collation_needed() API,
   770         - then it is passed the names of undefined collation sequences as strings
   771         - encoded in UTF-8. If sqlite3_collation_needed16() is used, the names
   772         - are passed as UTF-16 in machine native byte order. A call to either
   773         - function replaces any existing callback.
   774         -
   775         - When the user-function is invoked, the first argument passed is a copy
   776         - of the second argument to sqlite3_collation_needed() or
   777         - sqlite3_collation_needed16(). The second argument is the database
   778         - handle. The third argument is one of SQLITE_UTF8, SQLITE_UTF16BE or
   779         - SQLITE_UTF16LE, indicating the most desirable form of the collation
   780         - sequence function required. The fourth argument is the name of the
   781         - required collation sequence.
   782         -
   783         - The collation sequence is returned to SQLite by a collation-needed
   784         - callback using the sqlite3_create_collation() or
   785         - sqlite3_create_collation16() APIs, described above.
   786         -}
   787         -
   788         -api {} {
   789         -int sqlite3_create_function(
   790         -  sqlite3 *,
   791         -  const char *zFunctionName,
   792         -  int nArg,
   793         -  int eTextRep,
   794         -  void *pUserData,
   795         -  void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
   796         -  void (*xStep)(sqlite3_context*,int,sqlite3_value**),
   797         -  void (*xFinal)(sqlite3_context*)
   798         -);
   799         -int sqlite3_create_function16(
   800         -  sqlite3*,
   801         -  const void *zFunctionName,
   802         -  int nArg,
   803         -  int eTextRep,
   804         -  void *pUserData,
   805         -  void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
   806         -  void (*xStep)(sqlite3_context*,int,sqlite3_value**),
   807         -  void (*xFinal)(sqlite3_context*)
   808         -);
   809         -#define SQLITE_UTF8     1
   810         -#define SQLITE_UTF16    2
   811         -#define SQLITE_UTF16BE  3
   812         -#define SQLITE_UTF16LE  4
   813         -#define SQLITE_ANY      5
   814         -} {
   815         - These two functions are used to add SQL functions or aggregates
   816         - implemented in C. The
   817         - only difference between these two routines is that the second argument, the
   818         - name of the (scalar) function or aggregate, is encoded in UTF-8 for
   819         - sqlite3_create_function() and UTF-16 for sqlite3_create_function16().
   820         - The length of the name is limited to 255 bytes, exclusive of the 
   821         - zero-terminator.  Note that the name length limit is in bytes, not
   822         - characters.  Any attempt to create a function with a longer name
   823         - will result in an SQLITE_ERROR error.
   824         - 
   825         - The first argument is the database handle that the new function or
   826         - aggregate is to be added to. If a single program uses more than one
   827         - database handle internally, then user functions or aggregates must 
   828         - be added individually to each database handle with which they will be
   829         - used.
   830         -
   831         - The third argument is the number of arguments that the function or
   832         - aggregate takes. If this argument is -1 then the function or
   833         - aggregate may take any number of arguments.  The maximum number
   834         - of arguments to a new SQL function is 127.  A number larger than
   835         - 127 for the third argument results in an SQLITE_ERROR error.
   836         -
   837         - The fourth argument, eTextRep, specifies what type of text arguments
   838         - this function prefers to receive.  Any function should be able to work
   839         - work with UTF-8, UTF-16le, or UTF-16be.  But some implementations may be
   840         - more efficient with one representation than another.  Users are allowed
   841         - to specify separate implementations for the same function which are called
   842         - depending on the text representation of the arguments.  The the implementation
   843         - which provides the best match is used.  If there is only a single
   844         - implementation which does not care what text representation is used,
   845         - then the fourth argument should be SQLITE_ANY.
   846         -
   847         - The fifth argument is an arbitrary pointer.  The function implementations
   848         - can gain access to this pointer using the sqlite_user_data() API.
   849         -
   850         - The sixth, seventh and  eighth argumens, xFunc, xStep and xFinal, are
   851         - pointers to user implemented C functions that implement the user
   852         - function or aggregate. A scalar function requires an implementation of
   853         - the xFunc callback only, NULL pointers should be passed as the xStep
   854         - and xFinal arguments. An aggregate function requires an implementation
   855         - of xStep and xFinal, and NULL should be passed for xFunc. To delete an
   856         - existing user function or aggregate, pass NULL for all three function
   857         - callbacks. Specifying an inconstant set of callback values, such as an
   858         - xFunc and an xFinal, or an xStep but no xFinal, results in an SQLITE_ERROR
   859         - return.
   860         -}
   861         -
   862         -api {} {
   863         -int sqlite3_data_count(sqlite3_stmt *pStmt);
   864         -} {
   865         - Return the number of values in the current row of the result set.
   866         -
   867         - After a call to sqlite3_step() that returns SQLITE_ROW, this routine
   868         - will return the same value as the sqlite3_column_count() function.
   869         - After sqlite3_step() has returned an SQLITE_DONE, SQLITE_BUSY or
   870         - error code, or before sqlite3_step() has been called on a 
   871         - prepared SQL statement, this routine returns zero.
   872         -}
   873         -
   874         -api {} {
   875         -int sqlite3_errcode(sqlite3 *db);
   876         -} {
   877         - Return the error code for the most recent failed sqlite3_* API call associated
   878         - with sqlite3 handle 'db'.  If a prior API call failed but the most recent
   879         - API call succeeded, the return value from this routine is undefined. 
   880         -
   881         - Calls to many sqlite3_* functions set the error code and string returned
   882         - by sqlite3_errcode(), sqlite3_errmsg() and sqlite3_errmsg16()
   883         - (overwriting the previous values). Note that calls to sqlite3_errcode(),
   884         - sqlite3_errmsg() and sqlite3_errmsg16() themselves do not affect the
   885         - results of future invocations.  Calls to API routines that do not return
   886         - an error code (examples: sqlite3_data_count() or sqlite3_mprintf()) do
   887         - not change the error code returned by this routine.
   888         -
   889         - Assuming no other intervening sqlite3_* API calls are made, the error
   890         - code returned by this function is associated with the same error as
   891         - the strings returned by sqlite3_errmsg() and sqlite3_errmsg16().
   892         -} {}
   893         -
   894         -api {} {
   895         -const char *sqlite3_errmsg(sqlite3*);
   896         -const void *sqlite3_errmsg16(sqlite3*);
   897         -} {
   898         - Return a pointer to a UTF-8 encoded string (sqlite3_errmsg)
   899         - or a UTF-16 encoded string (sqlite3_errmsg16) describing in English the
   900         - error condition for the most recent sqlite3_* API call. The returned
   901         - string is always terminated by an 0x00 byte.
   902         -
   903         - The string "not an error" is returned when the most recent API call was
   904         - successful.
   905         -}
   906         -
   907         -api {} {
   908         -int sqlite3_exec(
   909         -  sqlite3*,                     /* An open database */
   910         -  const char *sql,              /* SQL to be executed */
   911         -  sqlite_callback,              /* Callback function */
   912         -  void *,                       /* 1st argument to callback function */
   913         -  char **errmsg                 /* Error msg written here */
   914         -);
   915         -} {
   916         - A function to executes one or more statements of SQL.
   917         -
   918         - If one or more of the SQL statements are queries, then
   919         - the callback function specified by the 3rd argument is
   920         - invoked once for each row of the query result.  This callback
   921         - should normally return 0.  If the callback returns a non-zero
   922         - value then the query is aborted, all subsequent SQL statements
   923         - are skipped and the sqlite3_exec() function returns the SQLITE_ABORT.
   924         -
   925         - The 1st argument is an arbitrary pointer that is passed
   926         - to the callback function as its first argument.
   927         -
   928         - The 2nd argument to the callback function is the number of
   929         - columns in the query result.  The 3rd argument to the callback
   930         - is an array of strings holding the values for each column.
   931         - The 4th argument to the callback is an array of strings holding
   932         - the names of each column.
   933         -
   934         - The callback function may be NULL, even for queries.  A NULL
   935         - callback is not an error.  It just means that no callback
   936         - will be invoked.
   937         -
   938         - If an error occurs while parsing or evaluating the SQL (but
   939         - not while executing the callback) then an appropriate error
   940         - message is written into memory obtained from malloc() and
   941         - *errmsg is made to point to that message.  The calling function
   942         - is responsible for freeing the memory that holds the error
   943         - message.   Use sqlite3_free() for this.  If errmsg==NULL,
   944         - then no error message is ever written.
   945         -
   946         - The return value is is SQLITE_OK if there are no errors and
   947         - some other return code if there is an error.  The particular
   948         - return value depends on the type of error. 
   949         -
   950         - If the query could not be executed because a database file is
   951         - locked or busy, then this function returns SQLITE_BUSY.  (This
   952         - behavior can be modified somewhat using the sqlite3_busy_handler()
   953         - and sqlite3_busy_timeout() functions.)
   954         -} {}
   955         -
   956         -api {} {
   957         -int sqlite3_finalize(sqlite3_stmt *pStmt);
   958         -} {
   959         - The sqlite3_finalize() function is called to delete a prepared
   960         - SQL statement obtained by a previous call to sqlite3_prepare(),
   961         - sqlite3_prepare_v2(), sqlite3_prepare16(), or sqlite3_prepare16_v2().
   962         - If the statement was executed successfully, or
   963         - not executed at all, then SQLITE_OK is returned. If execution of the
   964         - statement failed then an error code is returned. 
   965         -
   966         - After sqlite_finalize() has been called, the statement handle is
   967         - invalidated. Passing it to any other SQLite function may cause a
   968         - crash.
   969         -
   970         - All prepared statements must finalized before sqlite3_close() is
   971         - called or else the close will fail with a return code of SQLITE_BUSY.
   972         -
   973         - This routine can be called at any point during the execution of the
   974         - virtual machine.  If the virtual machine has not completed execution
   975         - when this routine is called, that is like encountering an error or
   976         - an interrupt.  (See sqlite3_interrupt().)  Incomplete updates may be
   977         - rolled back and transactions canceled,  depending on the circumstances,
   978         - and the result code returned will be SQLITE_ABORT.
   979         -}
   980         -
   981         -api {} {
   982         -void *sqlite3_malloc(int);
   983         -void *sqlite3_realloc(void*, int);
   984         -void sqlite3_free(void*);
   985         -} {
   986         - These routines provide access to the memory allocator used by SQLite.
   987         - Depending on how SQLite has been compiled and the OS-layer backend,
   988         - the memory allocator used by SQLite might be the standard system
   989         - malloc()/realloc()/free(), or it might be something different.  With
   990         - certain compile-time flags, SQLite will add wrapper logic around the
   991         - memory allocator to add memory leak and buffer overrun detection.  The
   992         - OS layer might substitute a completely different memory allocator.
   993         - Use these APIs to be sure you are always using the correct memory
   994         - allocator.
   995         - 
   996         - The sqlite3_free() API, not the standard free() from the system library,
   997         - should always be used to free the memory buffer returned by
   998         - sqlite3_mprintf() or sqlite3_vmprintf() and to free the error message
   999         - string returned by sqlite3_exec().  Using free() instead of sqlite3_free()
  1000         - might accidentally work on some systems and build configurations but 
  1001         - will fail on others.
  1002         -
  1003         - Compatibility Note:  Prior to version 3.4.0, the sqlite3_free API
  1004         - was prototyped to take a <tt>char*</tt> parameter rather than 
  1005         - <tt>void*</tt>.  Like this:
  1006         -<blockquote><pre>
  1007         -void sqlite3_free(char*);
  1008         -</pre></blockquote>
  1009         - The change to using <tt>void*</tt> might cause warnings when 
  1010         - compiling older code against
  1011         - newer libraries, but everything should still work correctly.
  1012         -}
  1013         -
  1014         -api {} {
  1015         -int sqlite3_get_table(
  1016         -  sqlite3*,              /* An open database */
  1017         -  const char *sql,       /* SQL to be executed */
  1018         -  char ***resultp,       /* Result written to a char *[]  that this points to */
  1019         -  int *nrow,             /* Number of result rows written here */
  1020         -  int *ncolumn,          /* Number of result columns written here */
  1021         -  char **errmsg          /* Error msg written here */
  1022         -);
  1023         -void sqlite3_free_table(char **result);
  1024         -} {
  1025         - This next routine is really just a wrapper around sqlite3_exec().
  1026         - Instead of invoking a user-supplied callback for each row of the
  1027         - result, this routine remembers each row of the result in memory
  1028         - obtained from malloc(), then returns all of the result after the
  1029         - query has finished. 
  1030         -
  1031         - As an example, suppose the query result where this table:
  1032         -
  1033         - <pre>
  1034         -        Name        | Age
  1035         -        -----------------------
  1036         -        Alice       | 43
  1037         -        Bob         | 28
  1038         -        Cindy       | 21
  1039         - </pre>
  1040         -
  1041         - If the 3rd argument were &azResult then after the function returns
  1042         - azResult will contain the following data:
  1043         -
  1044         - <pre>
  1045         -        azResult[0] = "Name";
  1046         -        azResult[1] = "Age";
  1047         -        azResult[2] = "Alice";
  1048         -        azResult[3] = "43";
  1049         -        azResult[4] = "Bob";
  1050         -        azResult[5] = "28";
  1051         -        azResult[6] = "Cindy";
  1052         -        azResult[7] = "21";
  1053         - </pre>
  1054         -
  1055         - Notice that there is an extra row of data containing the column
  1056         - headers.  But the *nrow return value is still 3.  *ncolumn is
  1057         - set to 2.  In general, the number of values inserted into azResult
  1058         - will be ((*nrow) + 1)*(*ncolumn).
  1059         -
  1060         - After the calling function has finished using the result, it should 
  1061         - pass the result data pointer to sqlite3_free_table() in order to 
  1062         - release the memory that was malloc-ed.  Because of the way the 
  1063         - malloc() happens, the calling function must not try to call 
  1064         - malloc() directly.  Only sqlite3_free_table() is able to release 
  1065         - the memory properly and safely.
  1066         -
  1067         - The return value of this routine is the same as from sqlite3_exec().
  1068         -}
  1069         -
  1070         -api {sqlite3_interrupt} {
  1071         - void sqlite3_interrupt(sqlite3*);
  1072         -} {
  1073         - This function causes any pending database operation to abort and
  1074         - return at its earliest opportunity.  This routine is typically
  1075         - called in response to a user action such as pressing "Cancel"
  1076         - or Ctrl-C where the user wants a long query operation to halt
  1077         - immediately.
  1078         -} {}
  1079         -
  1080         -api {} {
  1081         -long long int sqlite3_last_insert_rowid(sqlite3*);
  1082         -} {
  1083         - Each entry in an SQLite table has a unique integer key called the "rowid".
  1084         - The rowid is always available as an undeclared column
  1085         - named ROWID, OID, or _ROWID_.
  1086         - If the table has a column of type INTEGER PRIMARY KEY then that column
  1087         - is another an alias for the rowid.
  1088         -
  1089         - This routine
  1090         - returns the rowid of the most recent INSERT into the database
  1091         - from the database connection given in the first argument.  If
  1092         - no inserts have ever occurred on this database connection, zero
  1093         - is returned.
  1094         -
  1095         - If an INSERT occurs within a trigger, then the rowid of the
  1096         - inserted row is returned by this routine as long as the trigger
  1097         - is running.  But once the trigger terminates, the value returned
  1098         - by this routine reverts to the last value inserted before the
  1099         - trigger fired.
  1100         -} {}
  1101         -
  1102         -api {} {
  1103         -char *sqlite3_mprintf(const char*,...);
  1104         -char *sqlite3_vmprintf(const char*, va_list);
  1105         -} {
  1106         - These routines are variants of the "sprintf()" from the
  1107         - standard C library.  The resulting string is written into memory
  1108         - obtained from malloc() so that there is never a possibility of buffer
  1109         - overflow.  These routines also implement some additional formatting
  1110         - options that are useful for constructing SQL statements.
  1111         -
  1112         - The strings returned by these routines should be freed by calling
  1113         - sqlite3_free().
  1114         -
  1115         - All of the usual printf formatting options apply.  In addition, there
  1116         - is a "%q" option.  %q works like %s in that it substitutes a null-terminated
  1117         - string from the argument list.  But %q also doubles every '\\'' character.
  1118         - %q is designed for use inside a string literal.  By doubling each '\\''
  1119         - character it escapes that character and allows it to be inserted into
  1120         - the string.
  1121         -
  1122         - For example, so some string variable contains text as follows:
  1123         -
  1124         - <blockquote><pre>
  1125         -  char *zText = "It's a happy day!";
  1126         - </pre></blockquote>
  1127         -
  1128         - One can use this text in an SQL statement as follows:
  1129         -
  1130         - <blockquote><pre>
  1131         -  sqlite3_exec_printf(db, "INSERT INTO table VALUES('%q')",
  1132         -       callback1, 0, 0, zText);
  1133         -  </pre></blockquote>
  1134         -
  1135         - Because the %q format string is used, the '\\'' character in zText
  1136         - is escaped and the SQL generated is as follows:
  1137         -
  1138         - <blockquote><pre>
  1139         -  INSERT INTO table1 VALUES('It''s a happy day!')
  1140         - </pre></blockquote>
  1141         -
  1142         - This is correct.  Had we used %s instead of %q, the generated SQL
  1143         - would have looked like this:
  1144         -
  1145         -  <blockquote><pre>
  1146         -  INSERT INTO table1 VALUES('It's a happy day!');
  1147         -  </pre></blockquote>
  1148         -
  1149         - This second example is an SQL syntax error.  As a general rule you
  1150         - should always use %q instead of %s when inserting text into a string 
  1151         - literal.
  1152         -} {}
  1153         -
  1154         -api {} {
  1155         -char *sqlite3_snprintf(int bufSize, char *buf, const char *zFormat, ...);
  1156         -} {
  1157         -  This routine works like "sprintf()", writing a formatted string into
  1158         -  the buf[].  However, no more than bufSize characters will be written
  1159         -  into buf[].  This routine returns a pointer to buf[].  If bufSize is
  1160         -  greater than zero, then buf[] is guaranteed to be zero-terminated.
  1161         -
  1162         -  This routine uses the same extended formatting options as
  1163         -  sqlite3_mprintf() and sqlite3_vmprintf().
  1164         -
  1165         -  Note these differences with the snprintf() function found in many
  1166         -  standard libraries:  (1)  sqlite3_snprintf() returns a pointer to the
  1167         -  buffer rather than the number of characters written.  (It would,
  1168         -  arguably, be more useful to return the number of characters written,
  1169         -  but we discovered that after the interface had been published and
  1170         -  are unwilling to break backwards compatibility.)  (2)  The order
  1171         -  of the bufSize and buf parameter is reversed from snprintf().  
  1172         -  And (3) sqlite3_snprintf() always writes a zero-terminator if bufSize
  1173         -  is positive.  
  1174         -
  1175         -  Please do not use the return value of this routine.  We may
  1176         -  decide to make the minor compatibility break and change this routine
  1177         -  to return the number of characters written rather than a pointer to
  1178         -  the buffer in a future minor version increment.
  1179         -}
  1180         -
  1181         -api {} {
  1182         -int sqlite3_open(
  1183         -  const char *filename,   /* Database filename (UTF-8) */
  1184         -  sqlite3 **ppDb          /* OUT: SQLite db handle */
  1185         -);
  1186         -int sqlite3_open16(
  1187         -  const void *filename,   /* Database filename (UTF-16) */
  1188         -  sqlite3 **ppDb          /* OUT: SQLite db handle */
  1189         -);
  1190         -} {
  1191         - Open the sqlite database file "filename".  The "filename" is UTF-8
  1192         - encoded for sqlite3_open() and UTF-16 encoded in the native byte order
  1193         - for sqlite3_open16().  An sqlite3* handle is returned in *ppDb, even
  1194         - if an error occurs. If the database is opened (or created) successfully,
  1195         - then SQLITE_OK is returned. Otherwise an error code is returned. The
  1196         - sqlite3_errmsg() or sqlite3_errmsg16()  routines can be used to obtain
  1197         - an English language description of the error.
  1198         -
  1199         - If the database file does not exist, then a new database will be created
  1200         - as needed.
  1201         - The encoding for the database will be UTF-8 if sqlite3_open() is called and
  1202         - UTF-16 if sqlite3_open16 is used.
  1203         -
  1204         - Whether or not an error occurs when it is opened, resources associated
  1205         - with the sqlite3* handle should be released by passing it to
  1206         - sqlite3_close() when it is no longer required.
  1207         -
  1208         - The returned sqlite3* can only be used in the same thread in which it
  1209         - was created.  It is an error to call sqlite3_open() in one thread then
  1210         - pass the resulting database handle off to another thread to use.  This
  1211         - restriction is due to goofy design decisions (bugs?) in the way some
  1212         - threading implementations interact with file locks.
  1213         -
  1214         - Note to windows users:  The encoding used for the filename argument
  1215         - of sqlite3_open() must be UTF-8, not whatever codepage is currently
  1216         - defined.  Filenames containing international characters must be converted
  1217         - to UTF-8 prior to passing them into sqlite3_open().
  1218         -}
  1219         -
  1220         -api {} {
  1221         -int sqlite3_prepare_v2(
  1222         -  sqlite3 *db,            /* Database handle */
  1223         -  const char *zSql,       /* SQL statement, UTF-8 encoded */
  1224         -  int nBytes,             /* Length of zSql in bytes. */
  1225         -  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  1226         -  const char **pzTail     /* OUT: Pointer to unused portion of zSql */
  1227         -);
  1228         -int sqlite3_prepare16_v2(
  1229         -  sqlite3 *db,            /* Database handle */
  1230         -  const void *zSql,       /* SQL statement, UTF-16 encoded */
  1231         -  int nBytes,             /* Length of zSql in bytes. */
  1232         -  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  1233         -  const void **pzTail     /* OUT: Pointer to unused portion of zSql */
  1234         -);
  1235         -
  1236         -/* Legacy Interfaces */
  1237         -int sqlite3_prepare(
  1238         -  sqlite3 *db,            /* Database handle */
  1239         -  const char *zSql,       /* SQL statement, UTF-8 encoded */
  1240         -  int nBytes,             /* Length of zSql in bytes. */
  1241         -  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  1242         -  const char **pzTail     /* OUT: Pointer to unused portion of zSql */
  1243         -);
  1244         -int sqlite3_prepare16(
  1245         -  sqlite3 *db,            /* Database handle */
  1246         -  const void *zSql,       /* SQL statement, UTF-16 encoded */
  1247         -  int nBytes,             /* Length of zSql in bytes. */
  1248         -  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  1249         -  const void **pzTail     /* OUT: Pointer to unused portion of zSql */
  1250         -);
  1251         -} {
  1252         - To execute an SQL query, it must first be compiled into a byte-code
  1253         - program using one of these routines. 
  1254         -
  1255         - The first argument "db" is an SQLite database handle. The second
  1256         - argument "zSql" is the statement to be compiled, encoded as either
  1257         - UTF-8 or UTF-16.  The sqlite3_prepare_v2()
  1258         - interfaces uses UTF-8 and sqlite3_prepare16_v2()
  1259         - use UTF-16. If the next argument, "nBytes", is less
  1260         - than zero, then zSql is read up to the first nul terminator.  If
  1261         - "nBytes" is not less than zero, then it is the length of the string zSql
  1262         - in bytes (not characters).
  1263         -
  1264         - *pzTail is made to point to the first byte past the end of the first
  1265         - SQL statement in zSql.  This routine only compiles the first statement
  1266         - in zSql, so *pzTail is left pointing to what remains uncompiled.
  1267         -
  1268         - *ppStmt is left pointing to a compiled SQL statement that can be
  1269         - executed using sqlite3_step().  Or if there is an error, *ppStmt may be
  1270         - set to NULL.  If the input text contained no SQL (if the input is and
  1271         - empty string or a comment) then *ppStmt is set to NULL.  The calling
  1272         - procedure is responsible for deleting this compiled SQL statement
  1273         - using sqlite3_finalize() after it has finished with it.
  1274         -
  1275         - On success, SQLITE_OK is returned.  Otherwise an error code is returned.
  1276         -
  1277         - The sqlite3_prepare_v2() and sqlite3_prepare16_v2() interfaces are
  1278         - recommended for all new programs. The two older interfaces are retained
  1279         - for backwards compatibility, but their use is discouraged.
  1280         - In the "v2" interfaces, the prepared statement
  1281         - that is returned (the sqlite3_stmt object) contains a copy of the original
  1282         - SQL. This causes the sqlite3_step() interface to behave a differently in
  1283         - two ways:
  1284         -
  1285         - <ol>
  1286         - <li>
  1287         - If the database schema changes, instead of returning SQLITE_SCHEMA as it
  1288         - always used to do, sqlite3_step() will automatically recompile the SQL
  1289         - statement and try to run it again.  If the schema has changed in a way
  1290         - that makes the statement no longer valid, sqlite3_step() will still
  1291         - return SQLITE_SCHEMA.  But unlike the legacy behavior, SQLITE_SCHEMA is
  1292         - now a fatal error.  Calling sqlite3_prepare_v2() again will not make the
  1293         - error go away.  Note: use sqlite3_errmsg() to find the text of the parsing
  1294         - error that results in an SQLITE_SCHEMA return.
  1295         - </li>
  1296         -
  1297         - <li>
  1298         - When an error occurs, 
  1299         - sqlite3_step() will return one of the detailed result-codes
  1300         - like SQLITE_IOERR or SQLITE_FULL or SQLITE_SCHEMA directly. The
  1301         - legacy behavior was that sqlite3_step() would only return a generic
  1302         - SQLITE_ERROR code and you would have to make a second call to
  1303         - sqlite3_reset() in order to find the underlying cause of the problem.
  1304         - With the "v2" prepare interfaces, the underlying reason for the error is
  1305         - returned directly.
  1306         - </li>
  1307         - </ol>
  1308         -}
  1309         -
  1310         -api {} {
  1311         -void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
  1312         -} {
  1313         - <i>Experimental</i>
  1314         -
  1315         - This routine configures a callback function - the progress callback - that
  1316         - is invoked periodically during long running calls to sqlite3_exec(),
  1317         - sqlite3_step() and sqlite3_get_table().
  1318         - An example use for this API is to keep
  1319         - a GUI updated during a large query.
  1320         -
  1321         - The progress callback is invoked once for every N virtual machine opcodes,
  1322         - where N is the second argument to this function. The progress callback
  1323         - itself is identified by the third argument to this function. The fourth
  1324         - argument to this function is a void pointer passed to the progress callback
  1325         - function each time it is invoked.
  1326         -
  1327         - If a call to sqlite3_exec(), sqlite3_step() or sqlite3_get_table() results 
  1328         - in less than N opcodes being executed, then the progress callback is not
  1329         - invoked.
  1330         - 
  1331         - To remove the progress callback altogether, pass NULL as the third
  1332         - argument to this function.
  1333         -
  1334         - If the progress callback returns a result other than 0, then the current 
  1335         - query is immediately terminated and any database changes rolled back. If the
  1336         - query was part of a larger transaction, then the transaction is not rolled
  1337         - back and remains active. The sqlite3_exec() call returns SQLITE_ABORT. 
  1338         -
  1339         -}
  1340         -
  1341         -api {} {
  1342         -int sqlite3_reset(sqlite3_stmt *pStmt);
  1343         -} {
  1344         - The sqlite3_reset() function is called to reset a prepared SQL
  1345         - statement obtained by a previous call to 
  1346         - sqlite3_prepare_v2() or
  1347         - sqlite3_prepare16_v2() back to it's initial state, ready to be re-executed.
  1348         - Any SQL statement variables that had values bound to them using
  1349         - the sqlite3_bind_*() API retain their values.
  1350         -}
  1351         -
  1352         -api {} {
  1353         -void sqlite3_result_blob(sqlite3_context*, const void*, int n, void(*)(void*));
  1354         -void sqlite3_result_double(sqlite3_context*, double);
  1355         -void sqlite3_result_error(sqlite3_context*, const char*, int);
  1356         -void sqlite3_result_error16(sqlite3_context*, const void*, int);
  1357         -void sqlite3_result_int(sqlite3_context*, int);
  1358         -void sqlite3_result_int64(sqlite3_context*, long long int);
  1359         -void sqlite3_result_null(sqlite3_context*);
  1360         -void sqlite3_result_text(sqlite3_context*, const char*, int n, void(*)(void*));
  1361         -void sqlite3_result_text16(sqlite3_context*, const void*, int n, void(*)(void*));
  1362         -void sqlite3_result_text16be(sqlite3_context*, const void*, int n, void(*)(void*));
  1363         -void sqlite3_result_text16le(sqlite3_context*, const void*, int n, void(*)(void*));
  1364         -void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
  1365         -} {
  1366         - User-defined functions invoke these routines in order to
  1367         - set their return value.  The sqlite3_result_value() routine is used
  1368         - to return an exact copy of one of the arguments to the function.
  1369         -
  1370         - The operation of these routines is very similar to the operation of
  1371         - sqlite3_bind_blob() and its cousins.  Refer to the documentation there
  1372         - for additional information.
  1373         -}
  1374         -
  1375         -api {} {
  1376         -int sqlite3_set_authorizer(
  1377         -  sqlite3*,
  1378         -  int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
  1379         -  void *pUserData
  1380         -);
  1381         -#define SQLITE_CREATE_INDEX          1   /* Index Name      Table Name      */
  1382         -#define SQLITE_CREATE_TABLE          2   /* Table Name      NULL            */
  1383         -#define SQLITE_CREATE_TEMP_INDEX     3   /* Index Name      Table Name      */
  1384         -#define SQLITE_CREATE_TEMP_TABLE     4   /* Table Name      NULL            */
  1385         -#define SQLITE_CREATE_TEMP_TRIGGER   5   /* Trigger Name    Table Name      */
  1386         -#define SQLITE_CREATE_TEMP_VIEW      6   /* View Name       NULL            */
  1387         -#define SQLITE_CREATE_TRIGGER        7   /* Trigger Name    Table Name      */
  1388         -#define SQLITE_CREATE_VIEW           8   /* View Name       NULL            */
  1389         -#define SQLITE_DELETE                9   /* Table Name      NULL            */
  1390         -#define SQLITE_DROP_INDEX           10   /* Index Name      Table Name      */
  1391         -#define SQLITE_DROP_TABLE           11   /* Table Name      NULL            */
  1392         -#define SQLITE_DROP_TEMP_INDEX      12   /* Index Name      Table Name      */
  1393         -#define SQLITE_DROP_TEMP_TABLE      13   /* Table Name      NULL            */
  1394         -#define SQLITE_DROP_TEMP_TRIGGER    14   /* Trigger Name    Table Name      */
  1395         -#define SQLITE_DROP_TEMP_VIEW       15   /* View Name       NULL            */
  1396         -#define SQLITE_DROP_TRIGGER         16   /* Trigger Name    Table Name      */
  1397         -#define SQLITE_DROP_VIEW            17   /* View Name       NULL            */
  1398         -#define SQLITE_INSERT               18   /* Table Name      NULL            */
  1399         -#define SQLITE_PRAGMA               19   /* Pragma Name     1st arg or NULL */
  1400         -#define SQLITE_READ                 20   /* Table Name      Column Name     */
  1401         -#define SQLITE_SELECT               21   /* NULL            NULL            */
  1402         -#define SQLITE_TRANSACTION          22   /* NULL            NULL            */
  1403         -#define SQLITE_UPDATE               23   /* Table Name      Column Name     */
  1404         -#define SQLITE_ATTACH               24   /* Filename        NULL            */
  1405         -#define SQLITE_DETACH               25   /* Database Name   NULL            */
  1406         -#define SQLITE_ALTER_TABLE          26   /* Database Name   Table Name      */
  1407         -#define SQLITE_REINDEX              27   /* Index Name      NULL            */
  1408         -#define SQLITE_ANALYZE              28   /* Table Name      NULL            */
  1409         -#define SQLITE_CREATE_VTABLE        29   /* Table Name      Module Name     */
  1410         -#define SQLITE_DROP_VTABLE          30   /* Table Name      Module Name     */
  1411         -#define SQLITE_FUNCTION             31   /* Function Name   NULL            */
  1412         -
  1413         -#define SQLITE_DENY   1   /* Abort the SQL statement with an error */
  1414         -#define SQLITE_IGNORE 2   /* Don't allow access, but don't generate an error */
  1415         -} {
  1416         - This routine registers a callback with the SQLite library.  The
  1417         - callback is invoked by sqlite3_prepare_v2() to authorize various
  1418         - operations against the database.  The callback should
  1419         - return SQLITE_OK if access is allowed, SQLITE_DENY if the entire
  1420         - SQL statement should be aborted with an error and SQLITE_IGNORE
  1421         - if the operation should be treated as a no-op.
  1422         -
  1423         - Each database connection have at most one authorizer registered
  1424         - at a time one time.  Each call
  1425         - to sqlite3_set_authorizer() overrides the previous authorizer.
  1426         - Setting the callback to NULL disables the authorizer.
  1427         -
  1428         - The second argument to the access authorization function will be one
  1429         - of the defined constants shown.  These values signify what kind of operation
  1430         - is to be authorized.  The 3rd and 4th arguments to the authorization
  1431         - function will be arguments or NULL depending on which of the 
  1432         - codes is used as the second argument.  For example, if the the
  1433         - 2nd argument code is SQLITE_READ then the 3rd argument will be the name
  1434         - of the table that is being read from and the 4th argument will be the
  1435         - name of the column that is being read from.  Or if the 2nd argument
  1436         - is SQLITE_FUNCTION then the 3rd argument will be the name of the
  1437         - function that is being invoked and the 4th argument will be NULL.
  1438         -
  1439         - The 5th argument is the name
  1440         - of the database ("main", "temp", etc.) where applicable.  The 6th argument
  1441         - is the name of the inner-most trigger or view that is responsible for
  1442         - the access attempt or NULL if this access attempt is directly from 
  1443         - input SQL code.
  1444         -
  1445         - The return value of the authorization callback function should be one of the
  1446         - constants SQLITE_OK, SQLITE_DENY, or SQLITE_IGNORE.  A return of
  1447         - SQLITE_OK means that the operation is permitted and that 
  1448         - sqlite3_prepare_v2() can proceed as normal.
  1449         - A return of SQLITE_DENY means that the sqlite3_prepare_v2()
  1450         - should fail with an error.  A return of SQLITE_IGNORE causes the 
  1451         - sqlite3_prepare_v2() to continue as normal but the requested 
  1452         - operation is silently converted into a no-op.  A return of SQLITE_IGNORE
  1453         - in response to an SQLITE_READ or SQLITE_FUNCTION causes the column
  1454         - being read or the function being invoked to return a NULL.
  1455         -
  1456         - The intent of this routine is to allow applications to safely execute
  1457         - user-entered SQL.  An appropriate callback can deny the user-entered
  1458         - SQL access certain operations (ex: anything that changes the database)
  1459         - or to deny access to certain tables or columns within the database.
  1460         -
  1461         - SQLite is not reentrant through the authorization callback function.
  1462         - The authorization callback function should not attempt to invoke
  1463         - any other SQLite APIs for the same database connection.  If the
  1464         - authorization callback function invokes some other SQLite API, an
  1465         - SQLITE_MISUSE error or a segmentation fault may result.
  1466         -}
  1467         -
  1468         -api {} {
  1469         -int sqlite3_step(sqlite3_stmt*);
  1470         -} {
  1471         - After an SQL query has been prepared with a call to either
  1472         - sqlite3_prepare_v2() or sqlite3_prepare16_v2() or to one of
  1473         - the legacy interfaces sqlite3_prepare() or sqlite3_prepare16(),
  1474         - then this function must be
  1475         - called one or more times to execute the statement.
  1476         -
  1477         - The details of the behavior of this sqlite3_step() interface depend
  1478         - on whether the statement was prepared using the newer "v2" interface
  1479         - sqlite3_prepare_v2() and sqlite3_prepare16_v2() or the older legacy
  1480         - interface sqlite3_prepare() and sqlite3_prepare16().  The use of the
  1481         - new "v2" interface is recommended for new applications but the legacy
  1482         - interface will continue to be supported.
  1483         -
  1484         - In the lagacy interface, the return value will be either SQLITE_BUSY, 
  1485         - SQLITE_DONE, SQLITE_ROW, SQLITE_ERROR, or SQLITE_MISUSE.  With the "v2"
  1486         - interface, any of the other SQLite result-codes might be returned as
  1487         - well.
  1488         -
  1489         - SQLITE_BUSY means that the database engine attempted to open
  1490         - a locked database and there is no busy callback registered.
  1491         - Call sqlite3_step() again to retry the open.
  1492         -
  1493         - SQLITE_DONE means that the statement has finished executing
  1494         - successfully.  sqlite3_step() should not be called again on this virtual
  1495         - machine without first calling sqlite3_reset() to reset the virtual
  1496         - machine back to its initial state.
  1497         -
  1498         - If the SQL statement being executed returns any data, then 
  1499         - SQLITE_ROW is returned each time a new row of data is ready
  1500         - for processing by the caller. The values may be accessed using
  1501         - the sqlite3_column_int(), sqlite3_column_text(), and similar functions.
  1502         - sqlite3_step() is called again to retrieve the next row of data.
  1503         - 
  1504         - SQLITE_ERROR means that a run-time error (such as a constraint
  1505         - violation) has occurred.  sqlite3_step() should not be called again on
  1506         - the VM. More information may be found by calling sqlite3_errmsg().
  1507         - A more specific error code (example: SQLITE_INTERRUPT, SQLITE_SCHEMA,
  1508         - SQLITE_CORRUPT, and so forth) can be obtained by calling
  1509         - sqlite3_reset() on the prepared statement.  In the "v2" interface,
  1510         - the more specific error code is returned directly by sqlite3_step().
  1511         -
  1512         - SQLITE_MISUSE means that the this routine was called inappropriately.
  1513         - Perhaps it was called on a virtual machine that had already been
  1514         - finalized or on one that had previously returned SQLITE_ERROR or
  1515         - SQLITE_DONE.  Or it could be the case that a database connection
  1516         - is being used by a different thread than the one it was created it.
  1517         -
  1518         - <b>Goofy Interface Alert:</b>
  1519         - In the legacy interface, 
  1520         - the sqlite3_step() API always returns a generic error code,
  1521         - SQLITE_ERROR, following any error other than SQLITE_BUSY and SQLITE_MISUSE.
  1522         - You must call sqlite3_reset() (or sqlite3_finalize()) in order to find
  1523         - one of the specific result-codes that better describes the error.
  1524         - We admit that this is a goofy design.  The problem has been fixed
  1525         - with the "v2" interface.  If you prepare all of your SQL statements
  1526         - using either sqlite3_prepare_v2() or sqlite3_prepare16_v2() instead
  1527         - of the legacy sqlite3_prepare() and sqlite3_prepare16(), then the 
  1528         - more specific result-codes are returned directly by sqlite3_step().
  1529         - The use of the "v2" interface is recommended.
  1530         -}
  1531         -
  1532         -api {} {
  1533         -void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);
  1534         -} {
  1535         - Register a function that is called each time an SQL statement is evaluated.
  1536         - The callback function is invoked on the first call to sqlite3_step() after
  1537         - calls to sqlite3_prepare_v2() or sqlite3_reset().
  1538         - This function can be used (for example) to generate
  1539         - a log file of all SQL executed against a database.  This can be
  1540         - useful when debugging an application that uses SQLite.
  1541         -}
  1542         -
  1543         -api {} {
  1544         -void *sqlite3_user_data(sqlite3_context*);
  1545         -} {
  1546         - The pUserData argument to the sqlite3_create_function() and
  1547         - sqlite3_create_function16() routines used to register user functions
  1548         - is available to the implementation of the function using this
  1549         - call.
  1550         -}
  1551         -
  1552         -api {} {
  1553         -const void *sqlite3_value_blob(sqlite3_value*);
  1554         -int sqlite3_value_bytes(sqlite3_value*);
  1555         -int sqlite3_value_bytes16(sqlite3_value*);
  1556         -double sqlite3_value_double(sqlite3_value*);
  1557         -int sqlite3_value_int(sqlite3_value*);
  1558         -long long int sqlite3_value_int64(sqlite3_value*);
  1559         -const unsigned char *sqlite3_value_text(sqlite3_value*);
  1560         -const void *sqlite3_value_text16(sqlite3_value*);
  1561         -const void *sqlite3_value_text16be(sqlite3_value*);
  1562         -const void *sqlite3_value_text16le(sqlite3_value*);
  1563         -int sqlite3_value_type(sqlite3_value*);
  1564         -} {
  1565         - This group of routines returns information about arguments to
  1566         - a user-defined function.  Function implementations use these routines
  1567         - to access their arguments.  These routines are the same as the
  1568         - sqlite3_column_... routines except that these routines take a single
  1569         - sqlite3_value* pointer instead of an sqlite3_stmt* and an integer
  1570         - column number.
  1571         -
  1572         - See the documentation under sqlite3_column_blob for additional
  1573         - information.
  1574         -
  1575         - Please pay particular attention to the fact that the pointer that
  1576         - is returned from sqlite3_value_blob(), sqlite3_value_text(), or
  1577         - sqlite3_value_text16() can be invalidated by a subsequent call to
  1578         - sqlite3_value_bytes(), sqlite3_value_bytes16(), sqlite_value_text(),
  1579         - or sqlite3_value_text16().  
  1580         -}
  1581         -
  1582         -api {} {
  1583         -  int sqlite3_sleep(int);
  1584         -} {
  1585         - Sleep for a little while. The second parameter is the number of
  1586         - miliseconds to sleep for. 
  1587         -
  1588         - If the operating system does not support sleep requests with 
  1589         - milisecond time resolution, then the time will be rounded up to 
  1590         - the nearest second. The number of miliseconds of sleep actually 
  1591         - requested from the operating system is returned.
  1592         -}
  1593         -
  1594         -api {} {
  1595         -  int sqlite3_expired(sqlite3_stmt*);
  1596         -} {
  1597         - Return TRUE (non-zero) if the statement supplied as an argument needs
  1598         - to be recompiled.  A statement needs to be recompiled whenever the
  1599         - execution environment changes in a way that would alter the program
  1600         - that sqlite3_prepare() generates.  For example, if new functions or
  1601         - collating sequences are registered or if an authorizer function is
  1602         - added or changed.
  1603         -}
  1604         -
  1605         -api {} {
  1606         -  int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*);
  1607         -} {
  1608         - Move all bindings from the first prepared statement over to the second.
  1609         - This routine is useful, for example, if the first prepared statement
  1610         - fails with an SQLITE_SCHEMA error.  The same SQL can be prepared into
  1611         - the second prepared statement then all of the bindings transfered over
  1612         - to the second statement before the first statement is finalized.
  1613         -}
  1614         -
  1615         -api {} {
  1616         -  int sqlite3_global_recover();
  1617         -} {
  1618         - This function used to be involved in recovering from out-of-memory
  1619         - errors.  But as of SQLite version 3.3.0, out-of-memory recovery is
  1620         - automatic and this routine now does nothing.  THe interface is retained
  1621         - to avoid link errors with legacy code.
  1622         -}
  1623         -
  1624         -api {} {
  1625         -  int sqlite3_get_autocommit(sqlite3*);
  1626         -} {
  1627         - Test to see whether or not the database connection is in autocommit
  1628         - mode.  Return TRUE if it is and FALSE if not.  Autocommit mode is on
  1629         - by default.  Autocommit is disabled by a BEGIN statement and reenabled
  1630         - by the next COMMIT or ROLLBACK.
  1631         -}
  1632         -
  1633         -api {} {
  1634         -  int sqlite3_clear_bindings(sqlite3_stmt*);
  1635         -} {
  1636         - Set all the parameters in the compiled SQL statement back to NULL.
  1637         -}
  1638         -
  1639         -api {} {
  1640         -  sqlite3 *sqlite3_db_handle(sqlite3_stmt*);
  1641         -} {
  1642         - Return the sqlite3* database handle to which the prepared statement given
  1643         - in the argument belongs.  This is the same database handle that was
  1644         - the first argument to the sqlite3_prepare() that was used to create
  1645         - the statement in the first place.
  1646         -}
  1647         -
  1648         -api {} {
  1649         -  void *sqlite3_update_hook(
  1650         -    sqlite3*, 
  1651         -    void(*)(void *,int ,char const *,char const *,sqlite_int64),
  1652         -    void*
  1653         -  );
  1654         -} {
  1655         - Register a callback function with the database connection identified by the 
  1656         - first argument to be invoked whenever a row is updated, inserted or deleted.
  1657         - Any callback set by a previous call to this function for the same 
  1658         - database connection is overridden.
  1659         -
  1660         - The second argument is a pointer to the function to invoke when a 
  1661         - row is updated, inserted or deleted. The first argument to the callback is
  1662         - a copy of the third argument to sqlite3_update_hook. The second callback 
  1663         - argument is one of SQLITE_INSERT, SQLITE_DELETE or SQLITE_UPDATE, depending
  1664         - on the operation that caused the callback to be invoked. The third and 
  1665         - fourth arguments to the callback contain pointers to the database and 
  1666         - table name containing the affected row. The final callback parameter is 
  1667         - the rowid of the row. In the case of an update, this is the rowid after 
  1668         - the update takes place.
  1669         -
  1670         - The update hook is not invoked when internal system tables are
  1671         - modified (i.e. sqlite_master and sqlite_sequence).
  1672         -
  1673         - If another function was previously registered, its pArg value is returned.
  1674         - Otherwise NULL is returned.
  1675         -
  1676         - See also: sqlite3_commit_hook(), sqlite3_rollback_hook()
  1677         -}
  1678         -
  1679         -api {} {
  1680         -  void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
  1681         -} {
  1682         - Register a callback to be invoked whenever a transaction is rolled
  1683         - back. 
  1684         -
  1685         - The new callback function overrides any existing rollback-hook
  1686         - callback. If there was an existing callback, then it's pArg value 
  1687         - (the third argument to sqlite3_rollback_hook() when it was registered) 
  1688         - is returned. Otherwise, NULL is returned.
  1689         -
  1690         - For the purposes of this API, a transaction is said to have been 
  1691         - rolled back if an explicit "ROLLBACK" statement is executed, or
  1692         - an error or constraint causes an implicit rollback to occur. The 
  1693         - callback is not invoked if a transaction is automatically rolled
  1694         - back because the database connection is closed.
  1695         -}
  1696         -
  1697         -api {} {
  1698         -  int sqlite3_enable_shared_cache(int);
  1699         -} {
  1700         -  This routine enables or disables the sharing of the database cache
  1701         -  and schema data structures between connections to the same database.
  1702         -  Sharing is enabled if the argument is true and disabled if the argument
  1703         -  is false.
  1704         -
  1705         -  Cache sharing is enabled and disabled on a thread-by-thread basis.
  1706         -  Each call to this routine enables or disables cache sharing only for
  1707         -  connections created in the same thread in which this routine is called.
  1708         -  There is no mechanism for sharing cache between database connections
  1709         -  running in different threads.
  1710         -
  1711         -  Sharing must be disabled prior to shutting down a thread or else
  1712         -  the thread will leak memory.  Call this routine with an argument of
  1713         -  0 to turn off sharing.  Or use the sqlite3_thread_cleanup() API.
  1714         -
  1715         -  This routine must not be called when any database connections
  1716         -  are active in the current thread.  Enabling or disabling shared
  1717         -  cache while there are active database connections will result
  1718         -  in memory corruption.
  1719         -
  1720         -  When the shared cache is enabled, the
  1721         -  following routines must always be called from the same thread:
  1722         -  sqlite3_open(), sqlite3_prepare_v2(), sqlite3_step(), sqlite3_reset(),
  1723         -  sqlite3_finalize(), and sqlite3_close().
  1724         -  This is due to the fact that the shared cache makes use of
  1725         -  thread-specific storage so that it will be available for sharing
  1726         -  with other connections.
  1727         -
  1728         -  Virtual tables cannot be used with a shared cache.  When shared
  1729         -  cache is enabled, the sqlite3_create_module() API used to register
  1730         -  virtual tables will always return an error.
  1731         -
  1732         -  This routine returns SQLITE_OK if shared cache was
  1733         -  enabled or disabled successfully.  An error code is returned
  1734         -  otherwise.
  1735         -
  1736         -  Shared cache is disabled by default for backward compatibility.
  1737         -}
  1738         -
  1739         -api {} {
  1740         -  void sqlite3_thread_cleanup(void);
  1741         -} {
  1742         -  This routine makes sure that all thread local storage used by SQLite
  1743         -  in the current thread has been deallocated.  A thread can call this
  1744         -  routine prior to terminating in order to make sure there are no memory
  1745         -  leaks.
  1746         -
  1747         -  This routine is not strictly necessary.  If cache sharing has been
  1748         -  disabled using sqlite3_enable_shared_cache() and if all database
  1749         -  connections have been closed and if SQLITE_ENABLE_MEMORY_MANAGMENT is
  1750         -  on and all memory has been freed, then the thread local storage will
  1751         -  already have been automatically deallocated.  This routine is provided
  1752         -  as a convenience to the program who just wants to make sure that there
  1753         -  are no leaks.
  1754         -}
  1755         -
  1756         -api {} {
  1757         -  int sqlite3_release_memory(int N);
  1758         -} {
  1759         -  This routine attempts to free at least N bytes of memory from the caches
  1760         -  of database connecions that were created in the same thread from which this
  1761         -  routine is called.  The value returned is the number of bytes actually
  1762         -  freed.  
  1763         -
  1764         -  This routine is only available if memory management has been enabled
  1765         -  by compiling with the SQLITE_ENABLE_MEMORY_MANAGMENT macro.
  1766         -}
  1767         -
  1768         -api {} {
  1769         -  void sqlite3_soft_heap_limit(int N);
  1770         -} {
  1771         -  This routine sets the soft heap limit for the current thread to N.
  1772         -  If the total heap usage by SQLite in the current thread exceeds N,
  1773         -  then sqlite3_release_memory() is called to try to reduce the memory usage
  1774         -  below the soft limit.
  1775         -
  1776         -  Prior to shutting down a thread sqlite3_soft_heap_limit() must be set to 
  1777         -  zero (the default) or else the thread will leak memory. Alternatively, use
  1778         -  the sqlite3_thread_cleanup() API.
  1779         -
  1780         -  A negative or zero value for N means that there is no soft heap limit and
  1781         -  sqlite3_release_memory() will only be called when memory is exhaused.
  1782         -  The default value for the soft heap limit is zero.
  1783         -
  1784         -  SQLite makes a best effort to honor the soft heap limit.  But if it
  1785         -  is unable to reduce memory usage below the soft limit, execution will
  1786         -  continue without error or notification.  This is why the limit is 
  1787         -  called a "soft" limit.  It is advisory only.
  1788         -
  1789         -  This routine is only available if memory management has been enabled
  1790         -  by compiling with the SQLITE_ENABLE_MEMORY_MANAGMENT macro.
  1791         -}
  1792         -
  1793         -api {} {
  1794         -  void sqlite3_thread_cleanup(void);
  1795         -} {
  1796         -  This routine ensures that a thread that has used SQLite in the past
  1797         -  has released any thread-local storage it might have allocated.  
  1798         -  When the rest of the API is used properly, the cleanup of 
  1799         -  thread-local storage should be completely automatic.  You should
  1800         -  never really need to invoke this API.  But it is provided to you
  1801         -  as a precaution and as a potential work-around for future
  1802         -  thread-releated memory-leaks.
  1803         -}
  1804         -
  1805         -set n 0
  1806         -set i 0
  1807         -foreach item $apilist {
  1808         -  set namelist [lindex $item 0]
  1809         -  foreach name $namelist {
  1810         -    set n_to_name($n) $name
  1811         -    set n_to_idx($n) $i
  1812         -    set name_to_idx($name) $i
  1813         -    incr n
  1814         -  }
  1815         -  incr i
  1816         -}
  1817         -set i 0
  1818         -foreach name [lsort [array names name_to_idx]] {
  1819         -  set sname($i) $name
  1820         -  incr i
  1821         -}
  1822         -#parray n_to_name
  1823         -#parray n_to_idx
  1824         -#parray name_to_idx
  1825         -#parray sname
  1826         -incr n -1
  1827         -puts "<DIV class=pdf_ignore>"
  1828         -puts {<table width="100%" cellpadding="5"><tr>}
  1829         -set nrow [expr {($n+2)/3}]
  1830         -set i 0
  1831         -for {set j 0} {$j<3} {incr j} {
  1832         -  if {$j>0} {puts {<td width="10"></td>}}
  1833         -  puts {<td valign="top">}
  1834         -  set limit [expr {$i+$nrow}]
  1835         -  puts {<ul>}
  1836         -  while {$i<$limit && $i<$n} {
  1837         -    set name $sname($i)
  1838         -    if {[regexp {^sqlite} $name]} {set display $name} {set display <i>$name</i>}
  1839         -    puts "<li><a href=\"#$name\">$display</a></li>"
  1840         -    incr i
  1841         -  }
  1842         -  puts {</ul></td>}
  1843         -}
  1844         -puts "</table>"
  1845         -puts "<!-- $n entries.  $nrow rows in 3 columns -->"
  1846         -puts "</DIV>"
  1847         -
  1848         -proc resolve_name {ignore_list name} {
  1849         -  global name_to_idx
  1850         -  if {![info exists name_to_idx($name)] || [lsearch $ignore_list $name]>=0} {
  1851         -    return $name
  1852         -  } else {
  1853         -    return "<a href=\"#$name\">$name</a>"
  1854         -  }
  1855         -}
  1856         -
  1857         -foreach name [lsort [array names name_to_idx]] {
  1858         -  set i $name_to_idx($name)
  1859         -  if {[info exists done($i)]} continue
  1860         -  set done($i) 1
  1861         -  foreach {namelist prototype desc} [lindex $apilist $i] break
  1862         -  foreach name $namelist {
  1863         -    puts "<a name=\"$name\"></a>"
  1864         -  }
  1865         -  puts "<p><hr></p>"
  1866         -  puts "<blockquote><pre>"
  1867         -  regsub "^( *\n)+" $prototype {} p2
  1868         -  regsub "(\n *)+\$" $p2 {} p3
  1869         -  puts $p3
  1870         -  puts "</pre></blockquote>"
  1871         -  regsub -all {\[} $desc {\[} desc
  1872         -  regsub -all {sqlite3_[a-z0-9_]+} $desc "\[resolve_name $name &\]" d2
  1873         -  foreach x $specialname {
  1874         -    regsub -all $x $d2 "\[resolve_name $name &\]" d2
  1875         -  }
  1876         -  regsub -all "\n( *\n)+" [subst $d2] "</p>\n\n<p>" d3
  1877         -  puts "<p>$d3</p>"
  1878         -}
  1879         -
  1880         -puts "<DIV class=pdf_ignore>"
  1881         -footer $rcsid
  1882         -puts "</DIV>"

Deleted www/changes.tcl.

     1         -#
     2         -# Run this script to generated a changes.html output file
     3         -#
     4         -source common.tcl
     5         -header {SQLite changes}
     6         -puts {
     7         -<p>
     8         -This page provides a high-level summary of changes to SQLite.
     9         -For more detail, refer the the checkin logs generated by
    10         -CVS at
    11         -<a href="http://www.sqlite.org/cvstrac/timeline">
    12         -http://www.sqlite.org/cvstrac/timeline</a>.
    13         -</p>
    14         -
    15         -<DL>
    16         -}
    17         -
    18         -
    19         -proc chng {date desc} {
    20         -  if {[regexp {\(([0-9.]+)\)} $date all vers]} {
    21         -    set label [string map {. _} $vers]
    22         -    puts "<A NAME=\"version_$label\">"
    23         -  }
    24         -  puts "<DT><B>$date</B></DT>"
    25         -  regsub -all {[Tt]icket #(\d+)} $desc \
    26         -      {<a href="http://www.sqlite.org/cvstrac/tktview?tn=\1">\0</a>} desc
    27         -  puts "<DD><P><UL>$desc</UL></P>"
    28         -  puts "</DD>"
    29         -}
    30         -
    31         -chng {2007 Nov 05 (3.5.2)} {
    32         -<li>Dropped support for the SQLITE_OMIT_MEMORY_ALLOCATION compile-time
    33         -option.
    34         -<li>Always open files using FILE_FLAG_RANDOM_ACCESS under windows.
    35         -<li>The 3rd parameter of the built-in SUBSTR() function is now optional.
    36         -<li>Bug fix: do not invoke the authorizer when reparsing the schema after
    37         -a schema change.
    38         -<li>Added the experimental malloc-free memory allocator in mem3.c.
    39         -<li>Virtual machine stores 64-bit integer and floating point constants
    40         -in binary instead of text for a performance boost.
    41         -<li>Fix a race condition in test_async.c.
    42         -<li>Added the ".timer" command to the CLI
    43         -}
    44         -
    45         -chng {2007 Oct 04 (3.5.1)} {
    46         -<li><i><b>Nota Bene:</b> We are not using terms "alpha" or "beta" on this
    47         -    release because the code is stable and because if we use those terms,
    48         -    nobody will upgrade.  However, we still reserve the right to make
    49         -    incompatible changes to the new VFS interface in future releases.</i></li>
    50         -
    51         -<li>Fix a bug in the handling of SQLITE_FULL errors that could lead
    52         -    to database corruption.  Ticket #2686.
    53         -<li>The test_async.c drive now does full file locking and works correctly
    54         -    when used simultaneously by multiple processes on the same database.
    55         -<li>The CLI ignores whitespace (including comments) at the end of lines
    56         -<li>Make sure the query optimizer checks dependences on all terms of
    57         -    a compound SELECT statement.  Ticket #2640.
    58         -<li>Add demonstration code showing how to build a VFS for a raw
    59         -    mass storage without a filesystem.
    60         -<li>Added an output buffer size parameter to the xGetTempname() method
    61         -    of the VFS layer.
    62         -<li>Sticky SQLITE_FULL or SQLITE_IOERR errors in the pager are reset
    63         -    when a new transaction is started.
    64         -}
    65         -
    66         -
    67         -chng {2007 Sep 04 (3.5.0) alpha} {
    68         -<li>Redesign the OS interface layer.  See
    69         -    <a href="34to35.html">34to35.html</a> for details.
    70         -    <font color="red">*** Potentially incompatible change ***</font>
    71         -<li>The <a href="capi3ref.html#sqlite3_release_memory">
    72         -    sqlite3_release_memory()</a>,
    73         -    <a href="capi3ref.html#sqlite3_soft_heap_limit">
    74         -    sqlite3_soft_heap_limit()</a>,
    75         -    and <a href="capi3ref.html#sqlite3_enable_shared_cache">
    76         -    sqlite3_enable_shared_cache()</a> interfaces now work cross all
    77         -    threads in the process, not just the single thread in which they
    78         -    are invoked.
    79         -    <font color="red">*** Potentially incompatible change ***</font>
    80         -<li>Added the 
    81         -    <a href="capi3ref.html#sqlite3_open_v2">sqlite3_open_v2()</a>
    82         -    interface.  
    83         -<li>Reimplemented the memory allocation subsystem and made it 
    84         -    replacable at compile-time.
    85         -<li>Created a new mutex subsystem and made it replacable at
    86         -    compile-time.
    87         -<li>The same database connection may now be used simultaneously by
    88         -    separate threads.
    89         -}
    90         -
    91         -
    92         -chng {2007 August 13 (3.4.2)} {
    93         -<li>Fix a database corruption bug that might occur if a ROLLBACK command
    94         -is executed in <a href="pragma.html#pragma_auto_vacuum">auto-vacuum mode</a>
    95         -and a very small <a href="capi3ref.html#sqlite3_soft_heap_limit">
    96         -soft_heap_limit</a> is set. 
    97         -<a href="http://www.sqlite.org/cvstrac/tktview?tn=2565">Ticket #2565</a>.
    98         -
    99         -<li>Add the ability to run a full regression test with a small
   100         -<a href="capi3ref.html#sqlite3_soft_heap_limit">soft_heap_limit</a>.
   101         -
   102         -<li>Fix other minor problems with using small soft heap limits.
   103         -
   104         -<li>Work-around for 
   105         -<a href="http://gcc.gnu.org/bugzilla/show_bug.cgi?id=32575">GCC bug 32575</a>.
   106         -
   107         -<li>Improved error detection of misused aggregate functions.
   108         -
   109         -<li>Improvements to the amalgamation generator script so that all symbols
   110         -are prefixed with either SQLITE_PRIVATE or SQLITE_API.
   111         -}
   112         -
   113         -chng {2007 July 20 (3.4.1)} {
   114         -<li>Fix a bug in <a href="lang_vacuum.html">VACUUM</a> that can lead to
   115         -    <a href="http://www.sqlite.org/cvstrac/wiki?p=DatabaseCorruption">
   116         -    database corruption</a> if two
   117         -    processes are connected to the database at the same time and one
   118         -    VACUUMs then the other then modifies the database.</li>
   119         -<li>The expression "+column" is now considered the same as "column"
   120         -    when computing the collating sequence to use on the expression.</li>
   121         -<li>In the <a href="tclsqlite.html">TCL language interface</a>,
   122         -   "@variable" instead of "$variable" always binds as a blob.</li>
   123         -<li>Added <a href="pragma.html#pragma_freelist_count">PRAGMA freelist_count</a>
   124         -    for determining the current size of the freelist.</li>
   125         -<li>The <a href="pragma.html#pragma_auto_vacuum">
   126         -    PRAGMA auto_vacuum=incremental</a> setting is now persistent.</li>
   127         -<li>Add FD_CLOEXEC to all open files under unix.</li>
   128         -<li>Fix a bug in the <a href="optoverview.html#minmax">
   129         -    min()/max() optimization</a> when applied to
   130         -    descending indices.</li>
   131         -<li>Make sure the TCL language interface works correctly with 64-bit
   132         -    integers on 64-bit machines.</li>
   133         -<li>Allow the value -9223372036854775808 as an integer literal in SQL
   134         -    statements.</li>
   135         -<li>Add the capability of "hidden" columns in virtual tables.</li>
   136         -<li>Use the macro SQLITE_PRIVATE (defaulting to "static") on all
   137         -    internal functions in the amalgamation.</li>
   138         -<li>Add pluggable tokenizers and <a href="http://www.icu-project.org/">ICU</a>
   139         -    tokenization support to FTS2</li>
   140         -<li>Other minor bug fixes and documentation enhancements</li>
   141         -}
   142         -
   143         -chng {2007 June 18 (3.4.0)} {
   144         -<li>Fix a bug that can lead to database corruption if an SQLITE_BUSY error
   145         -    occurs in the middle of an explicit transaction and that transaction
   146         -    is later committed.  
   147         -    <a href="http://www.sqlite.org/cvstrac/tktview?tn=2409">Ticket #2409.</a>
   148         -    See the
   149         -    <a href="http://www.sqlite.org/cvstrac/wiki?p=CorruptionFollowingBusyError">
   150         -    CorruptionFollowingBusyError</a> wiki page for details.</i>
   151         -<li>Fix a bug that can lead to database corruption if autovacuum mode is
   152         -    on and a malloc() failure follows a CREATE TABLE or CREATE INDEX statement
   153         -    which itself follows a cache overflow inside a transaction.  See
   154         -    <a href="http://www.sqlite.org/cvstrac/tktview?tn=2418">ticket #2418</a>. 
   155         -    </li>
   156         -<li>Added explicit <a href="limits.html">upper bounds</a> on the sizes and
   157         -    quantities of things SQLite can process.  This change might cause
   158         -    compatibility problems for
   159         -    applications that use SQLite in the extreme, which is why the current
   160         -    release is 3.4.0 instead of 3.3.18.</li>
   161         -<li>Added support for <a href="capi3ref.html#sqlite3_blob_open">
   162         -    Incremental BLOB I/O</a>.</li>
   163         -<li>Added the <a href="capi3ref.html#sqlite3_bind_zeroblob">zeroblob API</a>
   164         -    and the <a href="lang_expr.html#zeroblob">zeroblob()</a> SQL function.</li>
   165         -<li>Added support for <a href="pragma.html#pragma_incremental_vacuum">
   166         -    Incremental Vacuum</a>.</li>
   167         -<li>Added the SQLITE_MIXED_ENDIAN_64BIT_FLOAT compile-time option to suppport
   168         -    ARM7 processors with goofy endianness.</li>
   169         -<li>Removed all instances of sprintf() and strcpy() from the core library.</li>
   170         -<li>Added support for <a href="http://www.icu-project.org/">
   171         -    International Components for Unicode (ICU)</a> to the full-text search
   172         -    extensions.
   173         -</ul><p>
   174         -<ul type="circle">
   175         -<li>In the windows OS driver, reacquire a SHARED lock if an attempt to
   176         -    acquire an EXCLUSIVE lock fails.  Ticket #2354</li>
   177         -<li>Fix the REPLACE() function so that it returns NULL if the second argument
   178         -    is an empty string.  Ticket #2324.</li>
   179         -<li>Document the hazards of type coversions in
   180         -    <a href="capi3ref.html#sqlite3_column_blob">sqlite3_column_blob()</a>
   181         -    and related APIs.  Fix unnecessary type conversions.  Ticket #2321.</li>
   182         -<li>Internationalization of the TRIM() function.  Ticket #2323</li>
   183         -<li>Use memmove() instead of memcpy() when moving between memory regions
   184         -    that might overlap.  Ticket #2334</li>
   185         -<li>Fix an optimizer bug involving subqueries in a compound SELECT that has
   186         -    both an ORDER BY and a LIMIT clause.  Ticket #2339.</li>
   187         -<li>Make sure the <a href="capi3ref.html#sqlite3_snprintf">sqlite3_snprintf()
   188         -    </a> interface does not zero-terminate the buffer if the buffer size is
   189         -    less than 1.  Ticket #2341</li>
   190         -<li>Fix the built-in printf logic so that it prints "NaN" not "Inf" for
   191         -    floating-point NaNs.  Ticket #2345</li>
   192         -<li>When converting BLOB to TEXT, use the text encoding of the main database.
   193         -    Ticket #2349</li>
   194         -<li>Keep the full precision of integers (if possible) when casting to
   195         -    NUMERIC.  Ticket #2364</li>
   196         -<li>Fix a bug in the handling of UTF16 codepoint 0xE000</li>
   197         -<li>Consider explicit collate clauses when matching WHERE constraints
   198         -    to indices in the query optimizer.  Ticket #2391</li>
   199         -<li>Fix the query optimizer to correctly handle constant expressions in 
   200         -    the ON clause of a LEFT JOIN.  Ticket #2403</li>
   201         -<li>Fix the query optimizer to handle rowid comparisions to NULL
   202         -    correctly.  Ticket #2404</li>
   203         -<li>Fix many potental segfaults that could be caused by malicious SQL
   204         -    statements.</li>
   205         -}
   206         -
   207         -chng {2007 April 25 (3.3.17)} {
   208         -<li>When the "write_version" value of the database header is larger than
   209         -    what the library understands, make the database read-only instead of
   210         -    unreadable.</li>
   211         -<li>Other minor bug fixes</li>
   212         -}
   213         -
   214         -chng {2007 April 18 (3.3.16)} {
   215         -<li>Fix a bug that caused VACUUM to fail if NULLs appeared in a
   216         -    UNIQUE column.</li>
   217         -<li>Reinstate performance improvements that were added in 3.3.14
   218         -    but regressed in 3.3.15.</li>
   219         -<li>Fix problems with the handling of ORDER BY expressions on
   220         -    compound SELECT statements in subqueries.</li>
   221         -<li>Fix a potential segfault when destroying locks on WinCE in
   222         -    a multi-threaded environment.</li>
   223         -<li>Documentation updates.</li>
   224         -}
   225         -
   226         -chng {2007 April 9 (3.3.15)} {
   227         -<li>Fix a bug introduced in 3.3.14 that caused a rollback of
   228         -    CREATE TEMP TABLE to leave the database connection wedged.</li>
   229         -<li>Fix a bug that caused an extra NULL row to be returned when
   230         -    a descending query was interrupted by a change to the database.</li>
   231         -<li>The FOR EACH STATEMENT clause on a trigger now causes a syntax
   232         -    error.  It used to be silently ignored.</li>
   233         -<li>Fix an obscure and relatively harmless problem that might have caused
   234         -    a resource leak following an I/O error.</li>
   235         -<li>Many improvements to the test suite.  Test coverage now exceeded 98%</li>
   236         -}
   237         -
   238         -chng {2007 April 2 (3.3.14)} {
   239         -<li>Fix a <a href="http://www.sqlite.org/cvstrac/tktview?tn=2273">bug</a>
   240         -    in 3.3.13 that could cause a segfault when the IN operator
   241         -    is used one one term of a two-column index and the right-hand side of
   242         -    the IN operator contains a NULL.</li>
   243         -<li>Added a new OS interface method for determining the sector size
   244         -    of underlying media:  sqlite3OsSectorSize().</li>
   245         -<li>A new algorithm for statements of the form
   246         -    INSERT INTO <i>table1</i> SELECT * FROM <i>table2</i>
   247         -    is faster and reduces fragmentation.  VACUUM uses statements of
   248         -    this form and thus runs faster and defragments better.</li>
   249         -<li>Performance enhancements through reductions in disk I/O:
   250         -<ul>
   251         -<li>Do not read the last page of an overflow chain when
   252         -    deleting the row - just add that page to the freelist.</li>
   253         -<li>Do not store pages being deleted in the 
   254         -    rollback journal.</li>
   255         -<li>Do not read in the (meaningless) content of
   256         -    pages extracted from the freelist.</li>
   257         -<li>Do not flush the page cache (and thus avoiding
   258         -    a cache refill) unless another process changes the underlying
   259         -    database file.</li>
   260         -<li>Truncate rather than delete the rollback journal when committing
   261         -    a transaction in exclusive access mode, or when committing the TEMP
   262         -    database.</li>
   263         -</ul></li>
   264         -<li>Added support for exclusive access mode using
   265         -    <a href="pragma.html#pragma_locking_mode">
   266         -    "PRAGMA locking_mode=EXCLUSIVE"</a></li>
   267         -<li>Use heap space instead of stack space for large buffers in the
   268         -    pager - useful on embedded platforms with  stack-space
   269         -    limitations.</li>
   270         -<li>Add a makefile target "sqlite3.c" that builds an amalgamation containing
   271         -    the core SQLite library C code in a single file.</li>
   272         -<li>Get the library working correctly when compiled 
   273         -    with GCC option "-fstrict-aliasing".</li>
   274         -<li>Removed the vestigal SQLITE_PROTOCOL error.</li>
   275         -<li>Improvements to test coverage, other minor bugs fixed,
   276         -    memory leaks plugged,
   277         -    code refactored and/or recommented in places for easier reading.</li>
   278         -}
   279         -
   280         -chng {2007 February 13 (3.3.13)} {
   281         -<li>Add a "fragmentation" measurement in the output of sqlite3_analyzer.</li>
   282         -<li>Add the COLLATE operator used to explicitly set the collating sequence
   283         -used by an expression.  This feature is considered experimental pending
   284         -additional testing.</li>
   285         -<li>Allow up to 64 tables in a join - the old limit was 32.</li>
   286         -<li>Added two new experimental functions:
   287         -<a href="lang_expr.html#randomblobFunc">randomBlob()</a> and
   288         -<a href="lang_expr.html#hexFunc">hex()</a>.
   289         -Their intended use is to facilitate generating 
   290         -<a href="http://en.wikipedia.org/wiki/UUID">UUIDs</a>.
   291         -</li>
   292         -<li>Fix a problem where
   293         -<a href="pragma.html#pragma_count_changes">PRAGMA count_changes</a> was
   294         -causing incorrect results for updates on tables with triggers</li>
   295         -<li>Fix a bug in the ORDER BY clause optimizer for joins where the
   296         -left-most table in the join is constrained by a UNIQUE index.</li>
   297         -<li>Fixed a bug in the "copy" method of the TCL interface.</li>
   298         -<li>Bug fixes in fts1 and fts2 modules.</li>
   299         -}
   300         -
   301         -chng {2007 January 27 (3.3.12)} {
   302         -<li>Fix another bug in the IS NULL optimization that was added in
   303         -version 3.3.9.</li>
   304         -<li>Fix a assertion fault that occurred on deeply nested views.</li>
   305         -<li>Limit the amount of output that
   306         -<a href="pragma.html#pragma_integrity_check">PRAGMA integrity_check</a>
   307         -generates.</li>
   308         -<li>Minor syntactic changes to support a wider variety of compilers.</li>
   309         -}
   310         -
   311         -chng {2007 January 22 (3.3.11)} {
   312         -<li>Fix another bug in the implementation of the new 
   313         -<a href="capi3ref.html#sqlite3_prepare_v2">sqlite3_prepare_v2()</a> API.
   314         -We'll get it right eventually...</li>
   315         -<li>Fix a bug in the IS NULL optimization that was added in version 3.3.9 -
   316         -the bug was causing incorrect results on certain LEFT JOINs that included
   317         -in the WHERE clause an IS NULL constraint for the right table of the
   318         -LEFT JOIN.</li>
   319         -<li>Make AreFileApisANSI() a no-op macro in winCE since winCE does not
   320         -support this function.</li>
   321         -}
   322         -
   323         -chng {2007 January 9 (3.3.10)} {
   324         -<li>Fix bugs in the implementation of the new 
   325         -<a href="capi3ref.html#sqlite3_prepare_v2">sqlite3_prepare_v2()</a> API
   326         -that can lead to segfaults.</li>
   327         -<li>Fix 1-second round-off errors in the 
   328         -<a href="http://www.sqlite.org/cvstrac/wiki?p=DateAndTimeFunctions">
   329         -strftime()</a> function</li>
   330         -<li>Enhance the windows OS layer to provide detailed error codes</li>
   331         -<li>Work around a win2k problem so that SQLite can use single-character
   332         -database file names</li>
   333         -<li>The
   334         -<a href="pragma.html#pragma_user_version">user_version</a> and
   335         -<a href="pragma.html#pragma_schema_version">schema_version</a> pragmas 
   336         -correctly set their column names in the result set</li>
   337         -<li>Documentation updates</li>
   338         -}
   339         -
   340         -chng {2007 January 4 (3.3.9)} {
   341         -<li>Fix bugs in pager.c that could lead to database corruption if two
   342         -processes both try to recover a hot journal at the same instant</li>
   343         -<li>Added the <a href="capi3ref.html#sqlite3_prepare_v2">sqlite3_prepare_v2()</a>
   344         -API.</li>
   345         -<li>Fixed the ".dump" command in the command-line shell to show
   346         -indices, triggers and views again.</li>
   347         -<li>Change the table_info pragma so that it returns NULL for the default
   348         -value if there is no default value</li>
   349         -<li>Support for non-ASCII characters in win95 filenames</li>
   350         -<li>Query optimizer enhancements:
   351         -<ul>
   352         -<li>Optimizer does a better job of using indices to satisfy ORDER BY
   353         -clauses that sort on the integer primary key</li>
   354         -<li>Use an index to satisfy an IS NULL operator in the WHERE clause</li>
   355         -<li>Fix a bug that was causing the optimizer to miss an OR optimization
   356         -opportunity</li>
   357         -<li>The optimizer has more freedom to reorder tables in the FROM clause
   358         -even in there are LEFT joins.</li>
   359         -</ul>
   360         -<li>Extension loading supported added to winCE</li>
   361         -<li>Allow constraint names on the DEFAULT clause in a table definition</li>
   362         -<li>Added the ".bail" command to the command-line shell</li>
   363         -<li>Make CSV (comma separate value) output from the command-line shell
   364         -more closely aligned to accepted practice</li>
   365         -<li>Experimental FTS2 module added</li>
   366         -<li>Use sqlite3_mprintf() instead of strdup() to avoid libc dependencies</li>
   367         -<li>VACUUM uses a temporary file in the official TEMP folder, not in the
   368         -same directory as the original database</li>
   369         -<li>The prefix on temporary filenames on windows is changed from "sqlite"
   370         -to "etilqs".</li>
   371         -}
   372         -
   373         -chng {2006 October 9 (3.3.8)} {
   374         -<li>Support for full text search using the
   375         -<a href="http://www.sqlite.org/cvstrac/wiki?p=FullTextIndex">FTS1 module</a>
   376         -(beta)</li>
   377         -<li>Added OS-X locking patches (beta - disabled by default)</li>
   378         -<li>Introduce extended error codes and add error codes for various
   379         -kinds of I/O errors.</li>
   380         -<li>Added support for IF EXISTS on CREATE/DROP TRIGGER/VIEW</li>
   381         -<li>Fix the regression test suite so that it works with Tcl8.5</li>
   382         -<li>Enhance sqlite3_set_authorizer() to provide notification of calls to
   383         -    SQL functions.</li>
   384         -<li>Added experimental API:  sqlite3_auto_extension()</li>
   385         -<li>Various minor bug fixes</li>
   386         -}
   387         -
   388         -chng {2006 August 12 (3.3.7)} {
   389         -<li>Added support for
   390         -<a href="http://www.sqlite.org/cvstrac/wiki?p=VirtualTables">virtual tables</a>
   391         -(beta)</li>
   392         -<li>Added support for 
   393         -<a href="http://www.sqlite.org/cvstrac/wiki?p=LoadableExtensions">
   394         -dynamically loaded extensions</a> (beta)</li>
   395         -<li>The 
   396         -<a href="capi3ref.html#sqlite3_interrupt">sqlite3_interrupt()</a>
   397         -routine can be called for a different thread</li>
   398         -<li>Added the <a href="lang_expr.html#match">MATCH</a> operator.</li>
   399         -<li>The default file format is now 1.  
   400         -}
   401         -
   402         -chng {2006 June 6 (3.3.6)} {
   403         -<li>Plays better with virus scanners on windows</li>
   404         -<li>Faster :memory: databases</li>
   405         -<li>Fix an obscure segfault in UTF-8 to UTF-16 conversions</li>
   406         -<li>Added driver for OS/2</li>
   407         -<li>Correct column meta-information returned for aggregate queries</li>
   408         -<li>Enhanced output from EXPLAIN QUERY PLAN</li>
   409         -<li>LIMIT 0 now works on subqueries</li>
   410         -<li>Bug fixes and performance enhancements in the query optimizer</li>
   411         -<li>Correctly handle NULL filenames in ATTACH and DETACH</li>
   412         -<li>Inproved syntax error messages in the parser</li>
   413         -<li>Fix type coercion rules for the IN operator</li>
   414         -}
   415         -
   416         -chng {2006 April 5 (3.3.5)} {
   417         -<li>CHECK constraints use conflict resolution algorithms correctly.</li>
   418         -<li>The SUM() function throws an error on integer overflow.</li>
   419         -<li>Choose the column names in a compound query from the left-most SELECT
   420         -    instead of the right-most.</li>
   421         -<li>The sqlite3_create_collation() function
   422         -    honors the SQLITE_UTF16_ALIGNED flag.</li>
   423         -<li>SQLITE_SECURE_DELETE compile-time option causes deletes to overwrite
   424         -    old data with zeros.</li>
   425         -<li>Detect integer overflow in abs().</li>
   426         -<li>The random() function provides 64 bits of randomness instead of
   427         -    only 32 bits.</li>
   428         -<li>Parser detects and reports automaton stack overflow.</li>
   429         -<li>Change the round() function to return REAL instead of TEXT.</li>
   430         -<li>Allow WHERE clause terms on the left table of a LEFT OUTER JOIN to
   431         -    contain aggregate subqueries.</li>
   432         -<li>Skip over leading spaces in text to numeric conversions.</li>
   433         -<li>Various minor bug and documentation typo fixes and
   434         -    performance enhancements.</li>
   435         -}
   436         -
   437         -chng {2006 February 11 (3.3.4)} {
   438         -<li>Fix a blunder in the Unix mutex implementation that can lead to
   439         -deadlock on multithreaded systems.</li>
   440         -<li>Fix an alignment problem on 64-bit machines</li>
   441         -<li>Added the fullfsync pragma.</li>
   442         -<li>Fix an optimizer bug that could have caused some unusual LEFT OUTER JOINs
   443         -to give incorrect results.</li>
   444         -<li>The SUM function detects integer overflow and converts to accumulating
   445         -an approximate result using floating point numbers</li>
   446         -<li>Host parameter names can begin with '@' for compatibility with SQL Server.
   447         -</li>
   448         -<li>Other miscellaneous bug fixes</li>
   449         -}
   450         -
   451         -chng {2006 January 31 (3.3.3)} {
   452         -<li>Removed support for an ON CONFLICT clause on CREATE INDEX - it never
   453         -worked correctly so this should not present any backward compatibility
   454         -problems.</li>
   455         -<li>Authorizer callback now notified of ALTER TABLE ADD COLUMN commands</li>
   456         -<li>After any changes to the TEMP database schema, all prepared statements
   457         -are invalidated and must be recreated using a new call to
   458         -sqlite3_prepare()</li>
   459         -<li>Other minor bug fixes in preparation for the first stable release
   460         -of version 3.3</li>
   461         -}
   462         -
   463         -chng {2006 January 24 (3.3.2 beta)} {
   464         -<li>Bug fixes and speed improvements.  Improved test coverage.</li>
   465         -<li>Changes to the OS-layer interface: mutexes must now be recursive.</li>
   466         -<li>Discontinue the use of thread-specific data for out-of-memory
   467         -exception handling</li>
   468         -}
   469         -
   470         -chng {2006 January 16 (3.3.1 alpha)} {
   471         -<li>Countless bug fixes</li>
   472         -<li>Speed improvements</li>
   473         -<li>Database connections can now be used by multiple threads, not just
   474         -the thread in which they were created.</li>
   475         -}
   476         -
   477         -chng {2006 January 10 (3.3.0 alpha)} {
   478         -<li>CHECK constraints</li>
   479         -<li>IF EXISTS and IF NOT EXISTS clauses on CREATE/DROP TABLE/INDEX.</li>
   480         -<li>DESC indices</li>
   481         -<li>More efficient encoding of boolean values resulting in smaller database
   482         -files</li>
   483         -<li>More aggressive SQLITE_OMIT_FLOATING_POINT</li>
   484         -<li>Separate INTEGER and REAL affinity</li>
   485         -<li>Added a virtual function layer for the OS interface</li>
   486         -<li>"exists" method added to the TCL interface</li>
   487         -<li>Improved response to out-of-memory errors</li>
   488         -<li>Database cache can be optionally shared between connections
   489         -in the same thread</li>
   490         -<li>Optional READ UNCOMMITTED isolation (instead of the default
   491         -isolation level of SERIALIZABLE) and table level locking when
   492         -database connections share a common cache.</li>
   493         -}
   494         -
   495         -chng {2005 December 19 (3.2.8)} {
   496         -<li>Fix an obscure bug that can cause database corruption under the
   497         -following unusual circumstances: A large INSERT or UPDATE statement which 
   498         -is part of an even larger transaction fails due to a uniqueness contraint
   499         -but the containing transaction commits.</li>
   500         -}
   501         -
   502         -chng {2005 December 19 (2.8.17)} {
   503         -<li>Fix an obscure bug that can cause database corruption under the
   504         -following unusual circumstances: A large INSERT or UPDATE statement which 
   505         -is part of an even larger transaction fails due to a uniqueness contraint
   506         -but the containing transaction commits.</li>
   507         -}
   508         -
   509         -chng {2005 September 24 (3.2.7)} {
   510         -<li>GROUP BY now considers NULLs to be equal again, as it should
   511         -</li>
   512         -<li>Now compiles on Solaris and OpenBSD and other Unix variants
   513         -that lack the fdatasync() function</li>
   514         -<li>Now compiles on MSVC++6 again</li>
   515         -<li>Fix uninitialized variables causing malfunctions for various obscure
   516         -queries</li>
   517         -<li>Correctly compute a LEFT OUTER JOINs that is constrained on the
   518         -left table only</li>
   519         -}
   520         -
   521         -chng {2005 September 17 (3.2.6)} {
   522         -<li>Fix a bug that can cause database corruption if a VACUUM (or
   523         -    autovacuum) fails and is rolled back on a database that is
   524         -    larger than 1GiB</li>
   525         -<li>LIKE optiization now works for columns with COLLATE NOCASE</li>
   526         -<li>ORDER BY and GROUP BY now use bounded memory</li>
   527         -<li>Added support for COUNT(DISTINCT expr)</li>
   528         -<li>Change the way SUM() handles NULL values in order to comply with
   529         -    the SQL standard</li>
   530         -<li>Use fdatasync() instead of fsync() where possible in order to speed
   531         -    up commits slightly</li>
   532         -<li>Use of the CROSS keyword in a join turns off the table reordering
   533         -    optimization</li>
   534         -<li>Added the experimental and undocumented EXPLAIN QUERY PLAN capability</li>
   535         -<li>Use the unicode API in windows</li>
   536         -}
   537         -
   538         -chng {2005 August 27 (3.2.5)} {
   539         -<li>Fix a bug effecting DELETE and UPDATE statements that changed
   540         -more than 40960 rows.</li>
   541         -<li>Change the makefile so that it no longer requires GNUmake extensions</li>
   542         -<li>Fix the --enable-threadsafe option on the configure script</li>
   543         -<li>Fix a code generator bug that occurs when the left-hand side of an IN
   544         -operator is constant and the right-hand side is a SELECT statement</li>
   545         -<li>The PRAGMA synchronous=off statement now disables syncing of the
   546         -master journal file in addition to the normal rollback journals</li>
   547         -}
   548         -
   549         -chng {2005 August 24 (3.2.4)} {
   550         -<li>Fix a bug introduced in the previous release
   551         -that can cause a segfault while generating code
   552         -for complex WHERE clauses.</li>
   553         -<li>Allow floating point literals to begin or end with a decimal point.</li>
   554         -}
   555         -
   556         -chng {2005 August 21 (3.2.3)} {
   557         -<li>Added support for the CAST operator</li>
   558         -<li>Tcl interface allows BLOB values to be transferred to user-defined
   559         -functions</li>
   560         -<li>Added the "transaction" method to the Tcl interface</li>
   561         -<li>Allow the DEFAULT value of a column to call functions that have constant
   562         -operands</li>
   563         -<li>Added the ANALYZE command for gathering statistics on indices and
   564         -using those statistics when picking an index in the optimizer</li>
   565         -<li>Remove the limit (formerly 100) on the number of terms in the
   566         -WHERE clause</li>
   567         -<li>The right-hand side of the IN operator can now be a list of expressions
   568         -instead of just a list of constants</li>
   569         -<li>Rework the optimizer so that it is able to make better use of indices</li>
   570         -<li>The order of tables in a join is adjusted automatically to make
   571         -better use of indices</li>
   572         -<li>The IN operator is now a candidate for optimization even if the left-hand
   573         -side is not the left-most term of the index.  Multiple IN operators can be
   574         -used with the same index.</li>
   575         -<li>WHERE clause expressions using BETWEEN and OR are now candidates
   576         -for optimization</li>
   577         -<li>Added the "case_sensitive_like" pragma and the SQLITE_CASE_SENSITIVE_LIKE
   578         -compile-time option to set its default value to "on".</li>
   579         -<li>Use indices to help with GLOB expressions and LIKE expressions too
   580         -when the case_sensitive_like pragma is enabled</li>
   581         -<li>Added support for grave-accent quoting for compatibility with MySQL</li>
   582         -<li>Improved test coverage</li>
   583         -<li>Dozens of minor bug fixes</li>
   584         -}
   585         -
   586         -chng {2005 June 13 (3.2.2)} {
   587         -<li>Added the sqlite3_db_handle() API</li>
   588         -<li>Added the sqlite3_get_autocommit() API</li>
   589         -<li>Added a REGEXP operator to the parser.  There is no function to back
   590         -up this operator in the standard build but users can add their own using
   591         -sqlite3_create_function()</li>
   592         -<li>Speed improvements and library footprint reductions.</li>
   593         -<li>Fix byte alignment problems on 64-bit architectures.</li>
   594         -<li>Many, many minor bug fixes and documentation updates.</li>
   595         -}
   596         -
   597         -chng {2005 March 29 (3.2.1)} {
   598         -<li>Fix a memory allocation error in the new ADD COLUMN comment.</li>
   599         -<li>Documentation updates</li>
   600         -}
   601         -
   602         -chng {2005 March 21 (3.2.0)} {
   603         -<li>Added support for ALTER TABLE ADD COLUMN.</li>
   604         -<li>Added support for the "T" separator in ISO-8601 date/time strings.</li>
   605         -<li>Improved support for Cygwin.</li>
   606         -<li>Numerous bug fixes and documentation updates.</li>
   607         -}
   608         -
   609         -chng {2005 March 16 (3.1.6)} {
   610         -<li>Fix a bug that could cause database corruption when inserting
   611         -    record into tables with around 125 columns.</li>
   612         -<li>sqlite3_step() is now much more likely to invoke the busy handler
   613         -    and less likely to return SQLITE_BUSY.</li>
   614         -<li>Fix memory leaks that used to occur after a malloc() failure.</li>
   615         -}
   616         -
   617         -chng {2005 March 11 (3.1.5)} {
   618         -<li>The ioctl on OS-X to control syncing to disk is F_FULLFSYNC,
   619         -    not F_FULLSYNC.  The previous release had it wrong.</li>
   620         -}
   621         -
   622         -chng {2005 March 10 (3.1.4)} {
   623         -<li>Fix a bug in autovacuum that could cause database corruption if
   624         -a CREATE UNIQUE INDEX fails because of a constraint violation.
   625         -This problem only occurs if the new autovacuum feature introduced in
   626         -version 3.1 is turned on.</li>
   627         -<li>The F_FULLSYNC ioctl (currently only supported on OS-X) is disabled
   628         -if the synchronous pragma is set to something other than "full".</li>
   629         -<li>Add additional forward compatibility to the future version 3.2 database 
   630         -file format.</li>
   631         -<li>Fix a bug in WHERE clauses of the form (rowid<'2')</li>
   632         -<li>New SQLITE_OMIT_... compile-time options added</li>
   633         -<li>Updates to the man page</li>
   634         -<li>Remove the use of strcasecmp() from the shell</li>
   635         -<li>Windows DLL exports symbols Tclsqlite_Init and Sqlite_Init</li>
   636         -}
   637         -
   638         -chng {2005 February 19 (3.1.3)} {
   639         -<li>Fix a problem with VACUUM on databases from which tables containing
   640         -AUTOINCREMENT have been dropped.</li>
   641         -<li>Add forward compatibility to the future version 3.2 database file
   642         -format.</li>
   643         -<li>Documentation updates</li>
   644         -}
   645         -
   646         -chng {2005 February 15 (3.1.2)} {
   647         -<li>Fix a bug that can lead to database corruption if there are two
   648         -open connections to the same database and one connection does a VACUUM
   649         -and the second makes some change to the database.</li>
   650         -<li>Allow "?" parameters in the LIMIT clause.</li>
   651         -<li>Fix VACUUM so that it works with AUTOINCREMENT.</li>
   652         -<li>Fix a race condition in AUTOVACUUM that can lead to corrupt databases</li>
   653         -<li>Add a numeric version number to the sqlite3.h include file.</li>
   654         -<li>Other minor bug fixes and performance enhancements.</li>
   655         -}
   656         -
   657         -chng {2005 February 15 (2.8.16)} {
   658         -<li>Fix a bug that can lead to database corruption if there are two
   659         -open connections to the same database and one connection does a VACUUM
   660         -and the second makes some change to the database.</li>
   661         -<li>Correctly handle quoted names in CREATE INDEX statements.</li>
   662         -<li>Fix a naming conflict between sqlite.h and sqlite3.h.</li>
   663         -<li>Avoid excess heap usage when copying expressions.</li>
   664         -<li>Other minor bug fixes.</li>
   665         -}
   666         -
   667         -chng {2005 February 1 (3.1.1 BETA)} {
   668         -<li>Automatic caching of prepared statements in the TCL interface</li>
   669         -<li>ATTACH and DETACH as well as some other operations cause existing
   670         -    prepared statements to expire.</li>
   671         -<li>Numerious minor bug fixes</li>
   672         -}
   673         -
   674         -chng {2005 January 21 (3.1.0 ALPHA)} {
   675         -<li>Autovacuum support added</li>
   676         -<li>CURRENT_TIME, CURRENT_DATE, and CURRENT_TIMESTAMP added</li>
   677         -<li>Support for the EXISTS clause added.</li>
   678         -<li>Support for correlated subqueries added.</li>
   679         -<li>Added the ESCAPE clause on the LIKE operator.</li>
   680         -<li>Support for ALTER TABLE ... RENAME TABLE ... added</li>
   681         -<li>AUTOINCREMENT keyword supported on INTEGER PRIMARY KEY</li>
   682         -<li>Many SQLITE_OMIT_ macros inserts to omit features at compile-time
   683         -    and reduce the library footprint.</li>
   684         -<li>The REINDEX command was added.</li>
   685         -<li>The engine no longer consults the main table if it can get
   686         -    all the information it needs from an index.</li>
   687         -<li>Many nuisance bugs fixed.</li>
   688         -}
   689         -
   690         -chng {2004 October 11 (3.0.8)} {
   691         -<li>Add support for DEFERRED, IMMEDIATE, and EXCLUSIVE transactions.</li>
   692         -<li>Allow new user-defined functions to be created when there are
   693         -already one or more precompiled SQL statements.<li>
   694         -<li>Fix portability problems for Mingw/MSYS.</li>
   695         -<li>Fix a byte alignment problem on 64-bit Sparc machines.</li>
   696         -<li>Fix the ".import" command of the shell so that it ignores \r
   697         -characters at the end of lines.</li>
   698         -<li>The "csv" mode option in the shell puts strings inside double-quotes.</li>
   699         -<li>Fix typos in documentation.</li>
   700         -<li>Convert array constants in the code to have type "const".</li>
   701         -<li>Numerous code optimizations, specially optimizations designed to
   702         -make the code footprint smaller.</li>
   703         -}
   704         -
   705         -chng {2004 September 18 (3.0.7)} {
   706         -<li>The BTree module allocates large buffers using malloc() instead of
   707         -    off of the stack, in order to play better on machines with limited
   708         -    stack space.</li>
   709         -<li>Fixed naming conflicts so that versions 2.8 and 3.0 can be
   710         -    linked and used together in the same ANSI-C source file.</li>
   711         -<li>New interface: sqlite3_bind_parameter_index()</li>
   712         -<li>Add support for wildcard parameters of the form: "?nnn"</li>
   713         -<li>Fix problems found on 64-bit systems.</li>
   714         -<li>Removed encode.c file (containing unused routines) from the 
   715         -    version 3.0 source tree.</li>
   716         -<li>The sqlite3_trace() callbacks occur before each statement
   717         -    is executed, not when the statement is compiled.</li>
   718         -<li>Makefile updates and miscellaneous bug fixes.</li>
   719         -}
   720         -
   721         -chng {2004 September 02 (3.0.6 beta)} {
   722         -<li>Better detection and handling of corrupt database files.</li>
   723         -<li>The sqlite3_step() interface returns SQLITE_BUSY if it is unable
   724         -    to commit a change because of a lock</li>
   725         -<li>Combine the implementations of LIKE and GLOB into a single
   726         -    pattern-matching subroutine.</li>
   727         -<li>Miscellaneous code size optimizations and bug fixes</li>
   728         -}
   729         -
   730         -chng {2004 August 29 (3.0.5 beta)} {
   731         -<li>Support for ":AAA" style bind parameter names.</li>
   732         -<li>Added the new sqlite3_bind_parameter_name() interface.</li>
   733         -<li>Support for TCL variable names embedded in SQL statements in the
   734         -    TCL bindings.</li>
   735         -<li>The TCL bindings transfer data without necessarily doing a conversion
   736         -    to a string.</li>
   737         -<li>The database for TEMP tables is not created until it is needed.</li>
   738         -<li>Add the ability to specify an alternative temporary file directory
   739         -    using the "sqlite_temp_directory" global variable.</li>
   740         -<li>A compile-time option (SQLITE_BUSY_RESERVED_LOCK) causes the busy
   741         -    handler to be called when there is contention for a RESERVED lock.</li>
   742         -<li>Various bug fixes and optimizations</li>
   743         -}
   744         -
   745         -chng {2004 August 8 (3.0.4 beta)} {
   746         -<li>CREATE TABLE and DROP TABLE now work correctly as prepared statements.</li>
   747         -<li>Fix a bug in VACUUM and UNIQUE indices.</li>
   748         -<li>Add the ".import" command to the command-line shell.</li>
   749         -<li>Fix a bug that could cause index corruption when an attempt to
   750         -    delete rows of a table is blocked by a pending query.</li>
   751         -<li>Library size optimizations.</li>
   752         -<li>Other minor bug fixes.</li>
   753         -}
   754         -
   755         -chng {2004 July 22 (2.8.15)} {
   756         -<li>This is a maintenance release only.  Various minor bugs have been
   757         -fixed and some portability enhancements are added.</li>
   758         -}
   759         -
   760         -chng {2004 July 22 (3.0.3 beta)} {
   761         -<li>The second beta release for SQLite 3.0.</li>
   762         -<li>Add support for "PRAGMA page_size" to adjust the page size of
   763         -the database.</li>
   764         -<li>Various bug fixes and documentation updates.</li>
   765         -}
   766         -
   767         -chng {2004 June 30 (3.0.2 beta)} {
   768         -<li>The first beta release for SQLite 3.0.</li>
   769         -}
   770         -
   771         -chng {2004 June 22 (3.0.1 alpha)} {
   772         -<li><font color="red"><b>
   773         -    *** Alpha Release - Research And Testing Use Only ***</b></font>
   774         -<li>Lots of bug fixes.</li>
   775         -}
   776         -
   777         -chng {2004 June 18 (3.0.0 alpha)} {
   778         -<li><font color="red"><b>
   779         -    *** Alpha Release - Research And Testing Use Only ***</b></font>
   780         -<li>Support for internationalization including UTF-8, UTF-16, and
   781         -    user defined collating sequences.</li>
   782         -<li>New file format that is 25% to 35% smaller for typical use.</li>
   783         -<li>Improved concurrency.</li>
   784         -<li>Atomic commits for ATTACHed databases.</li>
   785         -<li>Remove cruft from the APIs.</li>
   786         -<li>BLOB support.</li>
   787         -<li>64-bit rowids.</li>
   788         -<li><a href="version3.html">More information</a>.
   789         -}
   790         -
   791         -chng {2004 June 9 (2.8.14)} {
   792         -<li>Fix the min() and max() optimizer so that it works when the FROM
   793         -    clause consists of a subquery.</li>
   794         -<li>Ignore extra whitespace at the end of of "." commands in the shell.</li>
   795         -<li>Bundle sqlite_encode_binary() and sqlite_decode_binary() with the 
   796         -    library.</li>
   797         -<li>The TEMP_STORE and DEFAULT_TEMP_STORE pragmas now work.</li>
   798         -<li>Code changes to compile cleanly using OpenWatcom.</li>
   799         -<li>Fix VDBE stack overflow problems with INSTEAD OF triggers and
   800         -    NULLs in IN operators.</li>
   801         -<li>Add the global variable sqlite_temp_directory which if set defines the
   802         -    directory in which temporary files are stored.</li>
   803         -<li>sqlite_interrupt() plays well with VACUUM.</li>
   804         -<li>Other minor bug fixes.</li>
   805         -}
   806         -
   807         -chng {2004 March 8 (2.8.13)} {
   808         -<li>Refactor parts of the code in order to make the code footprint
   809         -    smaller.  The code is now also a little bit faster.</li>
   810         -<li>sqlite_exec() is now implemented as a wrapper around sqlite_compile()
   811         -    and sqlite_step().</li>
   812         -<li>The built-in min() and max() functions now honor the difference between
   813         -    NUMERIC and TEXT datatypes.  Formerly, min() and max() always assumed
   814         -    their arguments were of type NUMERIC.</li>
   815         -<li>New HH:MM:SS modifier to the built-in date/time functions.</li>
   816         -<li>Experimental sqlite_last_statement_changes() API added.  Fixed the
   817         -    the last_insert_rowid() function so that it works correctly with
   818         -    triggers.</li>
   819         -<li>Add functions prototypes for the database encryption API.</li>
   820         -<li>Fix several nuisance bugs.</li>
   821         -}
   822         -
   823         -chng {2004 February 8 (2.8.12)} {
   824         -<li>Fix a bug that will might corrupt the rollback journal if a power failure
   825         -    or external program halt occurs in the middle of a COMMIT.  The corrupt
   826         -    journal can lead to database corruption when it is rolled back.</li>
   827         -<li>Reduce the size and increase the speed of various modules, especially
   828         -    the virtual machine.</li>
   829         -<li>Allow "&lt;expr&gt; IN &lt;table&gt;" as a shorthand for
   830         -    "&lt;expr&gt; IN (SELECT * FROM &lt;table&gt;".</li>
   831         -<li>Optimizations to the sqlite_mprintf() routine.</li>
   832         -<li>Make sure the MIN() and MAX() optimizations work within subqueries.</li>
   833         -}
   834         -
   835         -chng {2004 January 14 (2.8.11)} {
   836         -<li>Fix a bug in how the IN operator handles NULLs in subqueries.  The bug
   837         -    was introduced by the previous release.</li>
   838         -}
   839         -
   840         -chng {2004 January 13 (2.8.10)} {
   841         -<li>Fix a potential database corruption problem on Unix caused by the fact
   842         -    that all posix advisory locks are cleared whenever you close() a file.
   843         -    The work around it to embargo all close() calls while locks are 
   844         -    outstanding.</li>
   845         -<li>Performance enhancements on some corner cases of COUNT(*).</li>
   846         -<li>Make sure the in-memory backend response sanely if malloc() fails.</li>
   847         -<li>Allow sqlite_exec() to be called from within user-defined SQL
   848         -    functions.</li>
   849         -<li>Improved accuracy of floating-point conversions using "long double".</li>
   850         -<li>Bug fixes in the experimental date/time functions.</li>
   851         -}
   852         -
   853         -chng {2004 January 5 (2.8.9)} {
   854         -<li>Fix a 32-bit integer overflow problem that could result in corrupt
   855         -    indices in a database if large negative numbers (less than -2147483648)
   856         -    were inserted into a indexed numeric column.</li>
   857         -<li>Fix a locking problem on multi-threaded Linux implementations.</li>
   858         -<li>Always use "." instead of "," as the decimal point even if the locale
   859         -    requests ",".</li>
   860         -<li>Added UTC to localtime conversions to the experimental date/time
   861         -    functions.</li>
   862         -<li>Bug fixes to date/time functions.</li>
   863         -}
   864         -
   865         -chng {2003 December 17 (2.8.8)} {
   866         -<li>Fix a critical bug introduced into 2.8.0 which could cause
   867         -    database corruption.</li>
   868         -<li>Fix a problem with 3-way joins that do not use indices</li>
   869         -<li>The VACUUM command now works with the non-callback API</li>
   870         -<li>Improvements to the "PRAGMA integrity_check" command</li>
   871         -}
   872         -
   873         -chng {2003 December 4 (2.8.7)} {
   874         -<li>Added experimental sqlite_bind() and sqlite_reset() APIs.</li>
   875         -<li>If the name of the database is an empty string, open a new database
   876         -    in a temporary file that is automatically deleted when the database
   877         -    is closed.</li>
   878         -<li>Performance enhancements in the lemon-generated parser</li>
   879         -<li>Experimental date/time functions revised.</li>
   880         -<li>Disallow temporary indices on permanent tables.</li>
   881         -<li>Documentation updates and typo fixes</li>
   882         -<li>Added experimental sqlite_progress_handler() callback API</li>
   883         -<li>Removed support for the Oracle8 outer join syntax.</li>
   884         -<li>Allow GLOB and LIKE operators to work as functions.</li>
   885         -<li>Other minor documentation and makefile changes and bug fixes.</li>
   886         -}
   887         -
   888         -chng {2003 August 21 (2.8.6)} {
   889         -<li>Moved the CVS repository to www.sqlite.org</li>
   890         -<li>Update the NULL-handling documentation.</li>
   891         -<li>Experimental date/time functions added.</li>
   892         -<li>Bug fix: correctly evaluate a view of a view without segfaulting.</li>
   893         -<li>Bug fix: prevent database corruption if you dropped a
   894         -    trigger that had the same name as a table.</li>
   895         -<li>Bug fix: allow a VACUUM (without segfaulting) on an empty
   896         -    database after setting the EMPTY_RESULT_CALLBACKS pragma.</li>
   897         -<li>Bug fix: if an integer value will not fit in a 32-bit int, store it in
   898         -    a double instead.</li>
   899         -<li>Bug fix: Make sure the journal file directory entry is committed to disk
   900         -    before writing the database file.</li>
   901         -}
   902         -
   903         -chng {2003 July 22 (2.8.5)} {
   904         -<li>Make LIMIT work on a compound SELECT statement.</li>
   905         -<li>LIMIT 0 now shows no rows.  Use LIMIT -1 to see all rows.</li>
   906         -<li>Correctly handle comparisons between an INTEGER PRIMARY KEY and
   907         -    a floating point number.</li>
   908         -<li>Fix several important bugs in the new ATTACH and DETACH commands.</li>
   909         -<li>Updated the <a href="nulls.html">NULL-handling document</a>.</li> 
   910         -<li>Allow NULL arguments in sqlite_compile() and sqlite_step().</li>
   911         -<li>Many minor bug fixes</li>
   912         -}
   913         -
   914         -chng {2003 June 29 (2.8.4)} {
   915         -<li>Enhanced the "PRAGMA integrity_check" command to verify indices.</li>
   916         -<li>Added authorization hooks for the new ATTACH and DETACH commands.</li>
   917         -<li>Many documentation updates</li>
   918         -<li>Many minor bug fixes</li>
   919         -}
   920         -
   921         -chng {2003 June 4 (2.8.3)} {
   922         -<li>Fix a problem that will corrupt the indices on a table if you
   923         -    do an INSERT OR REPLACE or an UPDATE OR REPLACE on a table that
   924         -    contains an INTEGER PRIMARY KEY plus one or more indices.</li>
   925         -<li>Fix a bug in windows locking code so that locks work correctly
   926         -    when simultaneously accessed by Win95 and WinNT systems.</li>
   927         -<li>Add the ability for INSERT and UPDATE statements to refer to the
   928         -    "rowid" (or "_rowid_" or "oid") columns.</li>
   929         -<li>Other important bug fixes</li>
   930         -}
   931         -
   932         -chng {2003 May 17 (2.8.2)} {
   933         -<li>Fix a problem that will corrupt the database file if you drop a
   934         -    table from the main database that has a TEMP index.</li>
   935         -}
   936         -
   937         -chng {2003 May 16 (2.8.1)} {
   938         -<li>Reactivated the VACUUM command that reclaims unused disk space in 
   939         -    a database file.</li>
   940         -<li>Added the ATTACH and DETACH commands to allow interacting with multiple
   941         -    database files at the same time.</li>
   942         -<li>Added support for TEMP triggers and indices.</li>
   943         -<li>Added support for in-memory databases.</li>
   944         -<li>Removed the experimental sqlite_open_aux_file().  Its function is
   945         -    subsumed in the new ATTACH command.</li>
   946         -<li>The precedence order for ON CONFLICT clauses was changed so that
   947         -    ON CONFLICT clauses on BEGIN statements have a higher precedence than
   948         -    ON CONFLICT clauses on constraints.
   949         -<li>Many, many bug fixes and compatibility enhancements.</li>
   950         -}
   951         -
   952         -chng {2003 Feb 16 (2.8.0)} {
   953         -<li>Modified the journal file format to make it more resistant to corruption
   954         -    that can occur after an OS crash or power failure.</li>
   955         -<li>Added a new C/C++ API that does not use callback for returning data.</li>
   956         -}
   957         -
   958         -chng {2003 Jan 25 (2.7.6)} {
   959         -<li>Performance improvements.  The library is now much faster.</li>
   960         -<li>Added the <b>sqlite_set_authorizer()</b> API.  Formal documentation has
   961         -    not been written - see the source code comments for instructions on
   962         -    how to use this function.</li>
   963         -<li>Fix a bug in the GLOB operator that was preventing it from working
   964         -    with upper-case letters.</li>
   965         -<li>Various minor bug fixes.</li>
   966         -}
   967         -
   968         -chng {2002 Dec 27 (2.7.5)} {
   969         -<li>Fix an uninitialized variable in pager.c which could (with a probability
   970         -    of about 1 in 4 billion) result in a corrupted database.</li>
   971         -}
   972         -
   973         -chng {2002 Dec 17 (2.7.4)} {
   974         -<li>Database files can now grow to be up to 2^41 bytes.  The old limit
   975         -    was 2^31 bytes.</li>
   976         -<li>The optimizer will now scan tables in the reverse if doing so will
   977         -    satisfy an ORDER BY ... DESC clause.</li>
   978         -<li>The full pathname of the database file is now remembered even if
   979         -    a relative path is passed into sqlite_open().  This allows 
   980         -    the library to continue operating correctly after a chdir().</li>
   981         -<li>Speed improvements in the VDBE.</li>
   982         -<li>Lots of little bug fixes.</li>
   983         -}
   984         -
   985         -chng {2002 Oct 30 (2.7.3)} {
   986         -<li>Various compiler compatibility fixes.</li>
   987         -<li>Fix a bug in the "expr IN ()" operator.</li>
   988         -<li>Accept column names in parentheses.</li>
   989         -<li>Fix a problem with string memory management in the VDBE</li>
   990         -<li>Fix a bug in the "table_info" pragma"</li>
   991         -<li>Export the sqlite_function_type() API function in the Windows DLL</li>
   992         -<li>Fix locking behavior under windows</li>
   993         -<li>Fix a bug in LEFT OUTER JOIN</li>
   994         -}
   995         -
   996         -chng {2002 Sep 25 (2.7.2)} {
   997         -<li>Prevent journal file overflows on huge transactions.</li>
   998         -<li>Fix a memory leak that occurred when sqlite_open() failed.</li>
   999         -<li>Honor the ORDER BY and LIMIT clause of a SELECT even if the
  1000         -    result set is used for an INSERT.</li>
  1001         -<li>Do not put write locks on the file used to hold TEMP tables.</li>
  1002         -<li>Added documentation on SELECT DISTINCT and on how SQLite handles NULLs.</li>
  1003         -<li>Fix a problem that was causing poor performance when many thousands
  1004         -    of SQL statements were executed by a single sqlite_exec() call.</li>
  1005         -}
  1006         -
  1007         -chng {2002 Aug 31 (2.7.1)} {
  1008         -<li>Fix a bug in the ORDER BY logic that was introduced in version 2.7.0</li>
  1009         -<li>C-style comments are now accepted by the tokenizer.</li>
  1010         -<li>INSERT runs a little faster when the source is a SELECT statement.</li>
  1011         -}
  1012         -
  1013         -chng {2002 Aug 25 (2.7.0)} {
  1014         -<li>Make a distinction between numeric and text values when sorting.
  1015         -    Text values sort according to memcmp().  Numeric values sort in
  1016         -    numeric order.</li>
  1017         -<li>Allow multiple simultaneous readers under windows by simulating
  1018         -    the reader/writers locks that are missing from Win95/98/ME.</li>
  1019         -<li>An error is now returned when trying to start a transaction if
  1020         -    another transaction is already active.</li>
  1021         -}
  1022         -
  1023         -chng {2002 Aug 12 (2.6.3)} {
  1024         -<li>Add the ability to read both little-endian and big-endian databases.
  1025         -    So database created under SunOS or MacOSX can be read and written
  1026         -    under Linux or Windows and vice versa.</li>
  1027         -<li>Convert to the new website: http://www.sqlite.org/</li>
  1028         -<li>Allow transactions to span Linux Threads</li>
  1029         -<li>Bug fix in the processing of the ORDER BY clause for GROUP BY queries</li>
  1030         -}
  1031         -
  1032         -chng {2002 Jly 30 (2.6.2)} {
  1033         -<li>Text files read by the COPY command can now have line terminators
  1034         -    of LF,  CRLF, or CR.</li>
  1035         -<li>SQLITE_BUSY is handled correctly if encountered during database
  1036         -    initialization.</li>
  1037         -<li>Fix to UPDATE triggers on TEMP tables.</li>
  1038         -<li>Documentation updates.</li>
  1039         -}
  1040         -
  1041         -chng {2002 Jly 19 (2.6.1)} {
  1042         -<li>Include a static string in the library that responds to the RCS
  1043         -    "ident" command and which contains the library version number.</li>
  1044         -<li>Fix an assertion failure that occurred when deleting all rows of
  1045         -    a table with the "count_changes" pragma turned on.</li>
  1046         -<li>Better error reporting when problems occur during the automatic
  1047         -    2.5.6 to 2.6.0 database format upgrade.</li>
  1048         -}
  1049         -
  1050         -chng {2002 Jly 17 (2.6.0)} {
  1051         -<li>Change the format of indices to correct a design flaw the originated
  1052         -    with version 2.1.0.  <font color="red">*** This is an incompatible
  1053         -    file format change ***</font>  When version 2.6.0 or later of the
  1054         -    library attempts to open a database file created by version 2.5.6 or
  1055         -    earlier, it will automatically and irreversibly convert the file format.
  1056         -    <b>Make backup copies of older database files before opening them with
  1057         -    version 2.6.0 of the library.</b>
  1058         -    </li>
  1059         -}
  1060         -
  1061         -chng {2002 Jly 7 (2.5.6)} {
  1062         -<li>Fix more problems with rollback.  Enhance the test suite to exercise
  1063         -    the rollback logic extensively in order to prevent any future problems.
  1064         -    </li>
  1065         -}
  1066         -
  1067         -chng {2002 Jly 6 (2.5.5)} {
  1068         -<li>Fix a bug which could cause database corruption during a rollback.
  1069         -    This bugs was introduced in version 2.4.0 by the freelist
  1070         -    optimization of checking [410].</li>
  1071         -<li>Fix a bug in aggregate functions for VIEWs.</li>
  1072         -<li>Other minor changes and enhancements.</li>
  1073         -}
  1074         -
  1075         -chng {2002 Jly 1 (2.5.4)} {
  1076         -<li>Make the "AS" keyword optional again.</li>
  1077         -<li>The datatype of columns now appear in the 4th argument to the
  1078         -    callback.</li>
  1079         -<li>Added the <b>sqlite_open_aux_file()</b> API, though it is still
  1080         -    mostly undocumented and untested.</li>
  1081         -<li>Added additional test cases and fixed a few bugs that those
  1082         -    test cases found.</li>
  1083         -}
  1084         -
  1085         -chng {2002 Jun 24 (2.5.3)} {
  1086         -<li>Bug fix:  Database corruption can occur due to the optimization
  1087         -    that was introduced in version 2.4.0 (check-in [410]).  The problem
  1088         -    should now be fixed.  The use of versions 2.4.0 through 2.5.2 is
  1089         -    not recommended.</li>
  1090         -}
  1091         -
  1092         -chng {2002 Jun 24 (2.5.2)} {
  1093         -<li>Added the new <b>SQLITE_TEMP_MASTER</b> table which records the schema
  1094         -    for temporary tables in the same way that <b>SQLITE_MASTER</b> does for
  1095         -    persistent tables.</li>
  1096         -<li>Added an optimization to UNION ALL</li>
  1097         -<li>Fixed a bug in the processing of LEFT OUTER JOIN</li>
  1098         -<li>The LIMIT clause now works on subselects</li>
  1099         -<li>ORDER BY works on subselects</li>
  1100         -<li>There is a new TypeOf() function used to determine if an expression
  1101         -    is numeric or text.</li>
  1102         -<li>Autoincrement now works for INSERT from a SELECT.</li>
  1103         -}
  1104         -
  1105         -chng {2002 Jun 19 (2.5.1)} {
  1106         -<li>The query optimizer now attempts to implement the ORDER BY clause
  1107         -    using an index.  Sorting is still used if not suitable index is
  1108         -    available.</li>
  1109         -}
  1110         -
  1111         -chng {2002 Jun 17 (2.5.0)} {
  1112         -<li>Added support for row triggers.</li>
  1113         -<li>Added SQL-92 compliant handling of NULLs.</li>
  1114         -<li>Add support for the full SQL-92 join syntax and LEFT OUTER JOINs.</li>
  1115         -<li>Double-quoted strings interpreted as column names not text literals.</li>
  1116         -<li>Parse (but do not implement) foreign keys.</li>
  1117         -<li>Performance improvements in the parser, pager, and WHERE clause code
  1118         -    generator.</li>
  1119         -<li>Make the LIMIT clause work on subqueries.  (ORDER BY still does not
  1120         -    work, though.)</li>
  1121         -<li>Added the "%Q" expansion to sqlite_*_printf().</li>
  1122         -<li>Bug fixes too numerous to mention (see the change log).</li>
  1123         -}
  1124         -
  1125         -chng {2002 May 09 (2.4.12)} {
  1126         -<li>Added logic to detect when the library API routines are called out
  1127         -    of sequence.</li>
  1128         -}
  1129         -
  1130         -chng {2002 May 08 (2.4.11)} {
  1131         -<li>Bug fix: Column names in the result set were not being generated
  1132         -    correctly for some (rather complex) VIEWs.  This could cause a
  1133         -    segfault under certain circumstances.</li>
  1134         -}
  1135         -
  1136         -chng {2002 May 02 (2.4.10)} {
  1137         -<li>Bug fix: Generate correct column headers when a compound SELECT is used
  1138         -    as a subquery.</li>
  1139         -<li>Added the sqlite_encode_binary() and sqlite_decode_binary() functions to
  1140         -    the source tree.  But they are not yet linked into the library.</li>
  1141         -<li>Documentation updates.</li>
  1142         -<li>Export the sqlite_changes() function from windows DLLs.</li>
  1143         -<li>Bug fix: Do not attempt the subquery flattening optimization on queries
  1144         -    that lack a FROM clause.  To do so causes a segfault.</li>
  1145         -}
  1146         -
  1147         -chng {2002 Apr 21 (2.4.9)} {
  1148         -<li>Fix a bug that was causing the precompiled binary of SQLITE.EXE to
  1149         -    report "out of memory" under Windows 98.</li>
  1150         -}
  1151         -
  1152         -chng {2002 Apr 20 (2.4.8)} {
  1153         -<li>Make sure VIEWs are created after their corresponding TABLEs in the
  1154         -    output of the <b>.dump</b> command in the shell.</li>
  1155         -<li>Speed improvements: Do not do synchronous updates on TEMP tables.</li>
  1156         -<li>Many improvements and enhancements to the shell.</li>
  1157         -<li>Make the GLOB and LIKE operators functions that can be overridden
  1158         -    by a programmer.  This allows, for example, the LIKE operator to
  1159         -    be changed to be case sensitive.</li>
  1160         -}
  1161         -
  1162         -chng {2002 Apr 06 (2.4.7)} {
  1163         -<li>Add the ability to put TABLE.* in the column list of a
  1164         -    SELECT statement.</li>
  1165         -<li>Permit SELECT statements without a FROM clause.</li>
  1166         -<li>Added the <b>last_insert_rowid()</b> SQL function.</li>
  1167         -<li>Do not count rows where the IGNORE conflict resolution occurs in
  1168         -    the row count.</li>
  1169         -<li>Make sure functions expressions in the VALUES clause of an INSERT
  1170         -    are correct.</li>
  1171         -<li>Added the <b>sqlite_changes()</b> API function to return the number
  1172         -    of row that changed in the most recent operation.</li>
  1173         -}
  1174         -
  1175         -chng {2002 Apr 02 (2.4.6)} {
  1176         -<li>Bug fix: Correctly handle terms in the WHERE clause of a join that
  1177         -    do not contain a comparison operator.</li>
  1178         -}
  1179         -
  1180         -chng {2002 Apr 01 (2.4.5)} {
  1181         -<li>Bug fix: Correctly handle functions that appear in the WHERE clause
  1182         -    of a join.</li>
  1183         -<li>When the PRAGMA vdbe_trace=ON is set, correctly print the P3 operand
  1184         -    value when it is a pointer to a structure rather than a pointer to
  1185         -    a string.</li>
  1186         -<li>When inserting an explicit NULL into an INTEGER PRIMARY KEY, convert
  1187         -    the NULL value into a unique key automatically.</li>
  1188         -}
  1189         -
  1190         -chng {2002 Mar 24 (2.4.4)} {
  1191         -<li>Allow "VIEW" to be a column name</li>
  1192         -<li>Added support for CASE expressions (patch from Dan Kennedy)</li>
  1193         -<li>Added RPMS to the delivery (patches from Doug Henry)</li>
  1194         -<li>Fix typos in the documentation</li>
  1195         -<li>Cut over configuration management to a new CVS repository with
  1196         -    its own CVSTrac bug tracking system.</li>
  1197         -}
  1198         -
  1199         -chng {2002 Mar 22 (2.4.3)} {
  1200         -<li>Fix a bug in SELECT that occurs when a compound SELECT is used as a
  1201         -    subquery in the FROM of a SELECT.</li>
  1202         -<li>The <b>sqlite_get_table()</b> function now returns an error if you
  1203         -    give it two or more SELECTs that return different numbers of columns.</li>
  1204         -}
  1205         -
  1206         -chng {2002 Mar 14 (2.4.2)} {
  1207         -<li>Bug fix: Fix an assertion failure that occurred when ROWID was a column
  1208         -    in a SELECT statement on a view.</li>
  1209         -<li>Bug fix: Fix an uninitialized variable in the VDBE that would could an
  1210         -    assert failure.</li>
  1211         -<li>Make the os.h header file more robust in detecting when the compile is
  1212         -    for windows and when it is for unix.</li>
  1213         -}
  1214         -
  1215         -chng {2002 Mar 13 (2.4.1)} {
  1216         -<li>Using an unnamed subquery in a FROM clause would cause a segfault.</li>
  1217         -<li>The parser now insists on seeing a semicolon or the end of input before
  1218         -    executing a statement.  This avoids an accidental disaster if the
  1219         -    WHERE keyword is misspelled in an UPDATE or DELETE statement.</li>
  1220         -}
  1221         -
  1222         -
  1223         -chng {2002 Mar 10 (2.4.0)} {
  1224         -<li>Change the name of the sanity_check PRAGMA to <b>integrity_check</b>
  1225         -    and make it available in all compiles.</li>
  1226         -<li>SELECT min() or max() of an indexed column with no WHERE or GROUP BY
  1227         -    clause is handled as a special case which avoids a complete table scan.</li>
  1228         -<li>Automatically generated ROWIDs are now sequential.</li>
  1229         -<li>Do not allow dot-commands of the command-line shell to occur in the
  1230         -    middle of a real SQL command.</li>
  1231         -<li>Modifications to the "lemon" parser generator so that the parser tables
  1232         -    are 4 times smaller.</li>
  1233         -<li>Added support for user-defined functions implemented in C.</li>
  1234         -<li>Added support for new functions: <b>coalesce()</b>, <b>lower()</b>,
  1235         -    <b>upper()</b>, and <b>random()</b>
  1236         -<li>Added support for VIEWs.</li>
  1237         -<li>Added the subquery flattening optimizer.</li>
  1238         -<li>Modified the B-Tree and Pager modules so that disk pages that do not
  1239         -    contain real data (free pages) are not journaled and are not
  1240         -    written from memory back to the disk when they change.  This does not 
  1241         -    impact database integrity, since the
  1242         -    pages contain no real data, but it does make large INSERT operations
  1243         -    about 2.5 times faster and large DELETEs about 5 times faster.</li>
  1244         -<li>Made the CACHE_SIZE pragma persistent</li>
  1245         -<li>Added the SYNCHRONOUS pragma</li>
  1246         -<li>Fixed a bug that was causing updates to fail inside of transactions when
  1247         -    the database contained a temporary table.</li>
  1248         -}
  1249         -
  1250         -chng {2002 Feb 18 (2.3.3)} {
  1251         -<li>Allow identifiers to be quoted in square brackets, for compatibility
  1252         -    with MS-Access.</li>
  1253         -<li>Added support for sub-queries in the FROM clause of a SELECT.</li>
  1254         -<li>More efficient implementation of sqliteFileExists() under Windows.
  1255         -    (by Joel Luscy)</li>
  1256         -<li>The VALUES clause of an INSERT can now contain expressions, including
  1257         -    scalar SELECT clauses.</li>
  1258         -<li>Added support for CREATE TABLE AS SELECT</li>
  1259         -<li>Bug fix: Creating and dropping a table all within a single
  1260         -    transaction was not working.</li>
  1261         -}
  1262         -
  1263         -chng {2002 Feb 14 (2.3.2)} {
  1264         -<li>Bug fix: There was an incorrect assert() in pager.c.  The real code was
  1265         -    all correct (as far as is known) so everything should work OK if you
  1266         -    compile with -DNDEBUG=1.  When asserts are not disabled, there
  1267         -    could be a fault.</li>
  1268         -}
  1269         -
  1270         -chng {2002 Feb 13 (2.3.1)} {
  1271         -<li>Bug fix: An assertion was failing if "PRAGMA full_column_names=ON;" was
  1272         -    set and you did a query that used a rowid, like this:  
  1273         -    "SELECT rowid, * FROM ...".</li>
  1274         -}
  1275         -
  1276         -chng {2002 Jan 30 (2.3.0)} {
  1277         -<li>Fix a serious bug in the INSERT command which was causing data to go
  1278         -    into the wrong columns if the data source was a SELECT and the INSERT
  1279         -    clauses specified its columns in some order other than the default.</li>
  1280         -<li>Added the ability to resolve constraint conflicts is ways other than
  1281         -    an abort and rollback.  See the documentation on the "ON CONFLICT"
  1282         -    clause for details.</li>
  1283         -<li>Temporary files are now automatically deleted by the operating system
  1284         -    when closed.  There are no more dangling temporary files on a program
  1285         -    crash.  (If the OS crashes, fsck will delete the file after reboot 
  1286         -    under Unix.  I do not know what happens under Windows.)</li>
  1287         -<li>NOT NULL constraints are honored.</li>
  1288         -<li>The COPY command puts NULLs in columns whose data is '\N'.</li>
  1289         -<li>In the COPY command, backslash can now be used to escape a newline.</li>
  1290         -<li>Added the SANITY_CHECK pragma.</li>
  1291         -}
  1292         -
  1293         -chng {2002 Jan 28 (2.2.5)} {
  1294         -<li>Important bug fix: the IN operator was not working if either the
  1295         -    left-hand or right-hand side was derived from an INTEGER PRIMARY KEY.</li>
  1296         -<li>Do not escape the backslash '\' character in the output of the
  1297         -    <b>sqlite</b> command-line access program.</li>
  1298         -}
  1299         -
  1300         -chng {2002 Jan 22 (2.2.4)} {
  1301         -<li>The label to the right of an AS in the column list of a SELECT can now
  1302         -    be used as part of an expression in the WHERE, ORDER BY, GROUP BY, and/or
  1303         -    HAVING clauses.</li>
  1304         -<li>Fix a bug in the <b>-separator</b> command-line option to the <b>sqlite</b>
  1305         -    command.</li>
  1306         -<li>Fix a problem with the sort order when comparing upper-case strings against
  1307         -    characters greater than 'Z' but less than 'a'.</li>
  1308         -<li>Report an error if an ORDER BY or GROUP BY expression is constant.</li>
  1309         -}
  1310         -
  1311         -chng {2002 Jan 16 (2.2.3)} {
  1312         -<li>Fix warning messages in VC++ 7.0.  (Patches from nicolas352001)</li>
  1313         -<li>Make the library thread-safe.  (The code is there and appears to work
  1314         -    but has not been stressed.)</li>
  1315         -<li>Added the new <b>sqlite_last_insert_rowid()</b> API function.</li>
  1316         -}
  1317         -
  1318         -chng {2002 Jan 13 (2.2.2)} {
  1319         -<li>Bug fix: An assertion was failing when a temporary table with an index
  1320         -    had the same name as a permanent table created by a separate process.</li>
  1321         -<li>Bug fix: Updates to tables containing an INTEGER PRIMARY KEY and an
  1322         -    index could fail.</li>
  1323         -}
  1324         -
  1325         -chng {2002 Jan 9 (2.2.1)} {
  1326         -<li>Bug fix: An attempt to delete a single row of a table with a WHERE
  1327         -    clause of "ROWID=x" when no such rowid exists was causing an error.</li>
  1328         -<li>Bug fix: Passing in a NULL as the 3rd parameter to <b>sqlite_open()</b>
  1329         -    would sometimes cause a coredump.</li>
  1330         -<li>Bug fix: DROP TABLE followed by a CREATE TABLE with the same name all
  1331         -    within a single transaction was causing a coredump.</li>
  1332         -<li>Makefile updates from A. Rottmann</li>
  1333         -}
  1334         -
  1335         -chng {2001 Dec 22 (2.2.0)} {
  1336         -<li>Columns of type INTEGER PRIMARY KEY are actually used as the primary
  1337         -    key in underlying B-Tree representation of the table.</li>
  1338         -<li>Several obscure, unrelated bugs were found and fixed while 
  1339         -    implemented the integer primary key change of the previous bullet.</li>
  1340         -<li>Added the ability to specify "*" as part of a larger column list in
  1341         -    the result section of a SELECT statement.  For example:
  1342         -    <nobr>"<b>SELECT rowid, * FROM table1;</b>"</nobr>.</li>
  1343         -<li>Updates to comments and documentation.</li>
  1344         -}
  1345         -
  1346         -chng {2001 Dec 14 (2.1.7)} {
  1347         -<li>Fix a bug in <b>CREATE TEMPORARY TABLE</b> which was causing the
  1348         -    table to be initially allocated in the main database file instead
  1349         -    of in the separate temporary file.  This bug could cause the library
  1350         -    to suffer an assertion failure and it could cause "page leaks" in the
  1351         -    main database file.
  1352         -<li>Fix a bug in the b-tree subsystem that could sometimes cause the first
  1353         -    row of a table to be repeated during a database scan.</li>
  1354         -}
  1355         -
  1356         -chng {2001 Dec 14 (2.1.6)} {
  1357         -<li>Fix the locking mechanism yet again to prevent
  1358         -    <b>sqlite_exec()</b> from returning SQLITE_PROTOCOL
  1359         -    unnecessarily.  This time the bug was a race condition in
  1360         -    the locking code.  This change effects both POSIX and Windows users.</li>
  1361         -}
  1362         -
  1363         -chng {2001 Dec 6 (2.1.5)} {
  1364         -<li>Fix for another problem (unrelated to the one fixed in 2.1.4) 
  1365         -    that sometimes causes <b>sqlite_exec()</b> to return SQLITE_PROTOCOL
  1366         -    unnecessarily.  This time the bug was
  1367         -    in the POSIX locking code and should not effect windows users.</li>
  1368         -}
  1369         -
  1370         -chng {2001 Dec 4 (2.1.4)} {
  1371         -<li>Sometimes <b>sqlite_exec()</b> would return SQLITE_PROTOCOL when it
  1372         -    should have returned SQLITE_BUSY.</li>
  1373         -<li>The fix to the previous bug uncovered a deadlock which was also
  1374         -    fixed.</li>
  1375         -<li>Add the ability to put a single .command in the second argument
  1376         -    of the sqlite shell</li>
  1377         -<li>Updates to the FAQ</li>
  1378         -}
  1379         -
  1380         -chng {2001 Nov 23 (2.1.3)} {
  1381         -<li>Fix the behavior of comparison operators 
  1382         -    (ex: "<b>&lt</b>", "<b>==</b>", etc.)
  1383         -    so that they are consistent with the order of entries in an index.</li>
  1384         -<li>Correct handling of integers in SQL expressions that are larger than
  1385         -    what can be represented by the machine integer.</li>
  1386         -}
  1387         -
  1388         -chng {2001 Nov 22 (2.1.2)} {
  1389         -<li>Changes to support 64-bit architectures.</li>
  1390         -<li>Fix a bug in the locking protocol.</li>
  1391         -<li>Fix a bug that could (rarely) cause the database to become 
  1392         -    unreadable after a DROP TABLE due to corruption to the SQLITE_MASTER
  1393         -    table.</li>
  1394         -<li>Change the code so that version 2.1.1 databases that were rendered 
  1395         -    unreadable by the above bug can be read by this version of
  1396         -    the library even though the SQLITE_MASTER table is (slightly)
  1397         -    corrupted.</li>
  1398         -}
  1399         -
  1400         -chng {2001 Nov 13 (2.1.1)} {
  1401         -<li>Bug fix: Sometimes arbitrary strings were passed to the callback
  1402         -    function when the actual value of a column was NULL.</li>
  1403         -}
  1404         -
  1405         -chng {2001 Nov 12 (2.1.0)} {
  1406         -<li>Change the format of data records so that records up to 16MB in size
  1407         -    can be stored.</li>
  1408         -<li>Change the format of indices to allow for better query optimization.</li>
  1409         -<li>Implement the "LIMIT ... OFFSET ..." clause on SELECT statements.</li>
  1410         -}
  1411         -
  1412         -chng {2001 Nov 3 (2.0.8)} {
  1413         -<li>Made selected parameters in API functions <b>const</b>. This should
  1414         -    be fully backwards compatible.</li>
  1415         -<li>Documentation updates</li>
  1416         -<li>Simplify the design of the VDBE by restricting the number of sorters
  1417         -    and lists to 1.
  1418         -    In practice, no more than one sorter and one list was ever used anyhow.
  1419         -    </li>
  1420         -}
  1421         -
  1422         -chng {2001 Oct 21 (2.0.7)} {
  1423         -<li>Any UTF-8 character or ISO8859 character can be used as part of
  1424         -    an identifier.</li>
  1425         -<li>Patches from Christian Werner to improve ODBC compatibility and to
  1426         -    fix a bug in the round() function.</li>
  1427         -<li>Plug some memory leaks that use to occur if malloc() failed.
  1428         -    We have been and continue to be memory leak free as long as
  1429         -    malloc() works.</li>
  1430         -<li>Changes to some test scripts so that they work on Windows in
  1431         -    addition to Unix.</li>
  1432         -}
  1433         -
  1434         -chng {2001 Oct 19 (2.0.6)} {
  1435         -<li>Added the EMPTY_RESULT_CALLBACKS pragma</li>
  1436         -<li>Support for UTF-8 and ISO8859 characters in column and table names.</li>
  1437         -<li>Bug fix: Compute correct table names with the FULL_COLUMN_NAMES pragma
  1438         -    is turned on.</li>
  1439         -}
  1440         -
  1441         -chng {2001 Oct 14 (2.0.5)} {
  1442         -<li>Added the COUNT_CHANGES pragma.</li>
  1443         -<li>Changes to the FULL_COLUMN_NAMES pragma to help out the ODBC driver.</li>
  1444         -<li>Bug fix: "SELECT count(*)" was returning NULL for empty tables.
  1445         -    Now it returns 0.</li>
  1446         -}
  1447         -
  1448         -chng {2001 Oct 13 (2.0.4)} {
  1449         -<li>Bug fix: an obscure and relatively harmless bug was causing one of
  1450         -    the tests to fail when gcc optimizations are turned on.  This release
  1451         -    fixes the problem.</li>
  1452         -}
  1453         -
  1454         -chng {2001 Oct 13 (2.0.3)} {
  1455         -<li>Bug fix: the <b>sqlite_busy_timeout()</b> function was delaying 1000
  1456         -    times too long before failing.</li>
  1457         -<li>Bug fix: an assertion was failing if the disk holding the database
  1458         -    file became full or stopped accepting writes for some other reason.
  1459         -    New tests were added to detect similar problems in the future.</li>
  1460         -<li>Added new operators: <b>&amp;</b> (bitwise-and)
  1461         -    <b>|</b> (bitwise-or), <b>~</b> (ones-complement),
  1462         -    <b>&lt;&lt;</b> (shift left), <b>&gt;&gt;</b> (shift right).</li>
  1463         -<li>Added new functions: <b>round()</b> and <b>abs()</b>.</li>
  1464         -}
  1465         -
  1466         -chng {2001 Oct 9 (2.0.2)} {
  1467         -<li>Fix two bugs in the locking protocol.  (One was masking the other.)</li>
  1468         -<li>Removed some unused "#include <unistd.h>" that were causing problems
  1469         -    for VC++.</li>
  1470         -<li>Fixed <b>sqlite.h</b> so that it is usable from C++</li>
  1471         -<li>Added the FULL_COLUMN_NAMES pragma.  When set to "ON", the names of
  1472         -    columns are reported back as TABLE.COLUMN instead of just COLUMN.</li>
  1473         -<li>Added the TABLE_INFO() and INDEX_INFO() pragmas to help support the
  1474         -    ODBC interface.</li>
  1475         -<li>Added support for TEMPORARY tables and indices.</li>
  1476         -}
  1477         -
  1478         -chng {2001 Oct 2 (2.0.1)} {
  1479         -<li>Remove some C++ style comments from btree.c so that it will compile
  1480         -    using compilers other than gcc.</li>
  1481         -<li>The ".dump" output from the shell does not work if there are embedded
  1482         -    newlines anywhere in the data.  This is an old bug that was carried
  1483         -    forward from version 1.0.  To fix it, the ".dump" output no longer
  1484         -    uses the COPY command.  It instead generates INSERT statements.</li>
  1485         -<li>Extend the expression syntax to support "expr NOT NULL" (with a
  1486         -    space between the "NOT" and the "NULL") in addition to "expr NOTNULL"
  1487         -    (with no space).</li>
  1488         -}
  1489         -
  1490         -chng {2001 Sep 28 (2.0.0)} {
  1491         -<li>Automatically build binaries for Linux and Windows and put them on
  1492         -    the website.</li>
  1493         -}
  1494         -
  1495         -chng {2001 Sep 28 (2.0-alpha-4)} {
  1496         -<li>Incorporate makefile patches form A. Rottmann to use LIBTOOL</li>
  1497         -}
  1498         -
  1499         -chng {2001 Sep 27 (2.0-alpha-3)} {
  1500         -<li>SQLite now honors the UNIQUE keyword in CREATE UNIQUE INDEX.  Primary
  1501         -    keys are required to be unique.</li>
  1502         -<li>File format changed back to what it was for alpha-1</li>
  1503         -<li>Fixes to the rollback and locking behavior</li>
  1504         -}
  1505         -
  1506         -chng {2001 Sep 20 (2.0-alpha-2)} {
  1507         -<li>Initial release of version 2.0.  The idea of renaming the library
  1508         -    to "SQLus" was abandoned in favor of keeping the "SQLite" name and
  1509         -    bumping the major version number.</li>
  1510         -<li>The pager and btree subsystems added back. They are now the only
  1511         -    available backend.</li>
  1512         -<li>The Dbbe abstraction and the GDBM and memory drivers were removed.</li>
  1513         -<li>Copyright on all code was disclaimed.  The library is now in the
  1514         -    public domain.</li>
  1515         -}
  1516         -
  1517         -chng {2001 Jul 23 (1.0.32)} {
  1518         -<li>Pager and btree subsystems removed.  These will be used in a follow-on
  1519         -    SQL server library named "SQLus".</li>
  1520         -<li>Add the ability to use quoted strings as table and column names in
  1521         -    expressions.</li>
  1522         -}
  1523         -
  1524         -chng {2001 Apr 14 (1.0.31)} {
  1525         -<li>Pager subsystem added but not yet used.</li>
  1526         -<li>More robust handling of out-of-memory errors.</li>
  1527         -<li>New tests added to the test suite.</li>
  1528         -}
  1529         -
  1530         -chng {2001 Apr 6 (1.0.30)} {
  1531         -<li>Remove the <b>sqlite_encoding</b> TCL variable that was introduced
  1532         -    in the previous version.</li>
  1533         -<li>Add options <b>-encoding</b> and <b>-tcl-uses-utf</b> to the
  1534         -    <b>sqlite</b> TCL command.</li>
  1535         -<li>Add tests to make sure that tclsqlite was compiled using Tcl header
  1536         -    files and libraries that match.</li>
  1537         -}
  1538         -
  1539         -chng {2001 Apr 5 (1.0.29)} {
  1540         -<li>The library now assumes data is stored as UTF-8 if the --enable-utf8
  1541         -    option is given to configure.  The default behavior is to assume
  1542         -    iso8859-x, as it has always done.  This only makes a difference for
  1543         -    LIKE and GLOB operators and the LENGTH and SUBSTR functions.</li>
  1544         -<li>If the library is not configured for UTF-8 and the Tcl library
  1545         -    is one of the newer ones that uses UTF-8 internally,
  1546         -    then a conversion from UTF-8 to iso8859 and
  1547         -    back again is done inside the TCL interface.</li>
  1548         -}
  1549         -
  1550         -chng {2001 Apr 4 (1.0.28)} {
  1551         -<li>Added limited support for transactions.  At this point, transactions
  1552         -    will do table locking on the GDBM backend.  There is no support (yet)
  1553         -    for rollback or atomic commit.</li>
  1554         -<li>Added special column names ROWID, OID, and _ROWID_ that refer to the
  1555         -    unique random integer key associated with every row of every table.</li>
  1556         -<li>Additional tests added to the regression suite to cover the new ROWID
  1557         -    feature and the TCL interface bugs mentioned below.</li>
  1558         -<li>Changes to the "lemon" parser generator to help it work better when
  1559         -    compiled using MSVC.</li>
  1560         -<li>Bug fixes in the TCL interface identified by Oleg Oleinick.</li>
  1561         -}
  1562         -
  1563         -chng {2001 Mar 20 (1.0.27)} {
  1564         -<li>When doing DELETE and UPDATE, the library used to write the record
  1565         -    numbers of records to be deleted or updated into a temporary file.
  1566         -    This is changed so that the record numbers are held in memory.</li>
  1567         -<li>The DELETE command without a WHILE clause just removes the database
  1568         -    files from the disk, rather than going through and deleting record
  1569         -    by record.</li>
  1570         -}
  1571         -
  1572         -chng {2001 Mar 20 (1.0.26)} {
  1573         -<li>A serious bug fixed on Windows.  Windows users should upgrade.
  1574         -    No impact to Unix.</li>
  1575         -}
  1576         -
  1577         -chng {2001 Mar 15 (1.0.25)} {
  1578         -<li>Modify the test scripts to identify tests that depend on system
  1579         -    load and processor speed and
  1580         -    to warn the user that a failure of one of those (rare) tests does
  1581         -    not necessarily mean the library is malfunctioning.  No changes to
  1582         -    code.
  1583         -    </li>
  1584         -}
  1585         -
  1586         -chng {2001 Mar 14 (1.0.24)} {
  1587         -<li>Fix a bug which was causing
  1588         -    the UPDATE command to fail on systems where "malloc(0)" returns
  1589         -    NULL.  The problem does not appear Windows, Linux, or HPUX but does 
  1590         -    cause the library to fail on QNX.
  1591         -    </li>
  1592         -}
  1593         -
  1594         -chng {2001 Feb 19 (1.0.23)} {
  1595         -<li>An unrelated (and minor) bug from Mark Muranwski fixed.  The algorithm
  1596         -    for figuring out where to put temporary files for a "memory:" database
  1597         -    was not working quite right.
  1598         -    </li>
  1599         -}
  1600         -
  1601         -chng {2001 Feb 19 (1.0.22)} {
  1602         -<li>The previous fix was not quite right.  This one seems to work better.
  1603         -    </li>
  1604         -}
  1605         -
  1606         -chng {2001 Feb 19 (1.0.21)} {
  1607         -<li>The UPDATE statement was not working when the WHERE clause contained
  1608         -    some terms that could be satisfied using indices and other terms that
  1609         -    could not.  Fixed.</li>
  1610         -}
  1611         -
  1612         -chng {2001 Feb 11 (1.0.20)} {
  1613         -<li>Merge development changes into the main trunk.  Future work toward
  1614         -    using a BTree file structure will use a separate CVS source tree.  This
  1615         -    CVS tree will continue to support the GDBM version of SQLite only.</li>
  1616         -}
  1617         -
  1618         -chng {2001 Feb 6 (1.0.19)} {
  1619         -<li>Fix a strange (but valid) C declaration that was causing problems
  1620         -    for QNX.  No logical changes.</li>
  1621         -}
  1622         -
  1623         -chng {2001 Jan 4 (1.0.18)} {
  1624         -<li>Print the offending SQL statement when an error occurs.</li>
  1625         -<li>Do not require commas between constraints in CREATE TABLE statements.</li>
  1626         -<li>Added the "-echo" option to the shell.</li>
  1627         -<li>Changes to comments.</li>
  1628         -}
  1629         -
  1630         -chng {2000 Dec 10 (1.0.17)} {
  1631         -<li>Rewrote <b>sqlite_complete()</b> to make it faster.</li>
  1632         -<li>Minor tweaks to other code to make it run a little faster.</li>
  1633         -<li>Added new tests for <b>sqlite_complete()</b> and for memory leaks.</li>
  1634         -}
  1635         -
  1636         -chng {2000 Dec 4 (1.0.16)} {
  1637         -<li>Documentation updates.  Mostly fixing of typos and spelling errors.</li>
  1638         -}
  1639         -
  1640         -chng {2000 Oct 23 (1.0.15)} {
  1641         -<li>Documentation updates</li>
  1642         -<li>Some sanity checking code was removed from the inner loop of vdbe.c
  1643         -    to help the library to run a little faster.  The code is only
  1644         -    removed if you compile with -DNDEBUG.</li>
  1645         -}
  1646         -
  1647         -chng {2000 Oct 19 (1.0.14)} {
  1648         -<li>Added a "memory:" backend driver that stores its database in an
  1649         -    in-memory hash table.</li>
  1650         -}
  1651         -
  1652         -chng {2000 Oct 18 (1.0.13)} {
  1653         -<li>Break out the GDBM driver into a separate file in anticipation
  1654         -    to added new drivers.</li>
  1655         -<li>Allow the name of a database to be prefixed by the driver type.
  1656         -    For now, the only driver type is "gdbm:".</li>
  1657         -}
  1658         -
  1659         -chng {2000 Oct 16 (1.0.12)} {
  1660         -<li>Fixed an off-by-one error that was causing a coredump in 
  1661         -    the '%q' format directive of the new
  1662         -    <b>sqlite_..._printf()</b> routines.</li>
  1663         -<li>Added the <b>sqlite_interrupt()</b> interface.</li>
  1664         -<li>In the shell, <b>sqlite_interrupt()</b> is invoked when the
  1665         -    user presses Control-C</li>
  1666         -<li>Fixed some instances where <b>sqlite_exec()</b> was
  1667         -    returning the wrong error code.</li>
  1668         -}
  1669         -
  1670         -chng {2000 Oct 11 (1.0.10)} {
  1671         -<li>Added notes on how to compile for Windows95/98.</li>
  1672         -<li>Removed a few variables that were not being used.  Etc.</li>
  1673         -}
  1674         -
  1675         -chng {2000 Oct 8 (1.0.9)} {
  1676         -<li>Added the <b>sqlite_..._printf()</b> interface routines.</li>
  1677         -<li>Modified the <b>sqlite</b> shell program to use the new interface 
  1678         -    routines.</li>
  1679         -<li>Modified the <b>sqlite</b> shell program to print the schema for
  1680         -    the built-in SQLITE_MASTER table, if explicitly requested.</li>
  1681         -}
  1682         -
  1683         -chng {2000 Sep 30 (1.0.8)} {
  1684         -<li>Begin writing documentation on the TCL interface.</li>
  1685         -}
  1686         -
  1687         -chng {2000 Sep 29 (Not Released)} {
  1688         -<li>Added the <b>sqlite_get_table()</b> API</li>
  1689         -<li>Updated the documentation for due to the above change.</li>
  1690         -<li>Modified the <b>sqlite</b> shell to make use of the new
  1691         -    sqlite_get_table() API in order to print a list of tables
  1692         -    in multiple columns, similar to the way "ls" prints filenames.</li>
  1693         -<li>Modified the <b>sqlite</b> shell to print a semicolon at the
  1694         -    end of each CREATE statement in the output of the ".schema" command.</li>
  1695         -}
  1696         -
  1697         -chng {2000 Sep 21 (Not Released)} {
  1698         -<li>Change the tclsqlite "eval" method to return a list of results if
  1699         -    no callback script is specified.</li>
  1700         -<li>Change tclsqlite.c to use the Tcl_Obj interface</li>
  1701         -<li>Add tclsqlite.c to the libsqlite.a library</li>
  1702         -}
  1703         -
  1704         -chng {2000 Sep 13 (Version 1.0.5)} {
  1705         -<li>Changed the print format for floating point values from "%g" to "%.15g".
  1706         -    </li>
  1707         -<li>Changed the comparison function so that numbers in exponential notation
  1708         -    (ex: 1.234e+05) sort in numerical order.</li>
  1709         -}
  1710         -
  1711         -chng {2000 Aug 28 (Version 1.0.4)} {
  1712         -<li>Added functions <b>length()</b> and <b>substr()</b>.</li>
  1713         -<li>Fix a bug in the <b>sqlite</b> shell program that was causing
  1714         -    a coredump when the output mode was "column" and the first row
  1715         -    of data contained a NULL.</li>
  1716         -}
  1717         -
  1718         -chng {2000 Aug 22 (Version 1.0.3)} {
  1719         -<li>In the sqlite shell, print the "Database opened READ ONLY" message
  1720         -    to stderr instead of stdout.</li>
  1721         -<li>In the sqlite shell, now print the version number on initial startup.</li>
  1722         -<li>Add the <b>sqlite_version[]</b> string constant to the library</li>
  1723         -<li>Makefile updates</li>
  1724         -<li>Bug fix: incorrect VDBE code was being generated for the following
  1725         -    circumstance: a query on an indexed table containing a WHERE clause with
  1726         -    an IN operator that had a subquery on its right-hand side.</li>
  1727         -}
  1728         -
  1729         -chng {2000 Aug 18 (Version 1.0.1)} {
  1730         -<li>Fix a bug in the configure script.</li>
  1731         -<li>Minor revisions to the website.</li>
  1732         -}
  1733         -
  1734         -chng {2000 Aug 17 (Version 1.0)} {
  1735         -<li>Change the <b>sqlite</b> program so that it can read
  1736         -    databases for which it lacks write permission.  (It used to
  1737         -    refuse all access if it could not write.)</li>
  1738         -}
  1739         -
  1740         -chng {2000 Aug 9} {
  1741         -<li>Treat carriage returns as white space.</li>
  1742         -}
  1743         -
  1744         -chng {2000 Aug 8} {
  1745         -<li>Added pattern matching to the ".table" command in the "sqlite"
  1746         -command shell.</li>
  1747         -}
  1748         -
  1749         -chng {2000 Aug 4} {
  1750         -<li>Documentation updates</li>
  1751         -<li>Added "busy" and "timeout" methods to the Tcl interface</li>
  1752         -}
  1753         -
  1754         -chng {2000 Aug 3} {
  1755         -<li>File format version number was being stored in sqlite_master.tcl
  1756         -    multiple times. This was harmless, but unnecessary. It is now fixed.</li>
  1757         -}
  1758         -
  1759         -chng {2000 Aug 2} {
  1760         -<li>The file format for indices was changed slightly in order to work
  1761         -    around an inefficiency that can sometimes come up with GDBM when
  1762         -    there are large indices having many entries with the same key.
  1763         -    <font color="red">** Incompatible Change **</font></li>
  1764         -}
  1765         -
  1766         -chng {2000 Aug 1} {
  1767         -<li>The parser's stack was overflowing on a very long UPDATE statement.
  1768         -    This is now fixed.</li>
  1769         -}
  1770         -
  1771         -chng {2000 July 31} {
  1772         -<li>Finish the <a href="vdbe.html">VDBE tutorial</a>.</li>
  1773         -<li>Added documentation on compiling to WindowsNT.</li>
  1774         -<li>Fix a configuration program for WindowsNT.</li>
  1775         -<li>Fix a configuration problem for HPUX.</li>
  1776         -}
  1777         -
  1778         -chng {2000 July 29} {
  1779         -<li>Better labels on column names of the result.</li>
  1780         -}
  1781         -
  1782         -chng {2000 July 28} {
  1783         -<li>Added the <b>sqlite_busy_handler()</b> 
  1784         -    and <b>sqlite_busy_timeout()</b> interface.</li>
  1785         -}
  1786         -
  1787         -chng {2000 June 23} {
  1788         -<li>Begin writing the <a href="vdbe.html">VDBE tutorial</a>.</li>
  1789         -}
  1790         -
  1791         -chng {2000 June 21} {
  1792         -<li>Clean up comments and variable names.  Changes to documentation.
  1793         -    No functional changes to the code.</li>
  1794         -}
  1795         -
  1796         -chng {2000 June 19} {
  1797         -<li>Column names in UPDATE statements were case sensitive.
  1798         -    This mistake has now been fixed.</li>
  1799         -}
  1800         -
  1801         -chng {2000 June 16} {
  1802         -<li>Added the concatenate string operator (||)</li>
  1803         -}
  1804         -
  1805         -chng {2000 June 12} {
  1806         -<li>Added the fcnt() function to the SQL interpreter.  The fcnt() function
  1807         -    returns the number of database "Fetch" operations that have occurred.
  1808         -    This function is designed for use in test scripts to verify that
  1809         -    queries are efficient and appropriately optimized.  Fcnt() has no other
  1810         -    useful purpose, as far as I know.</li>
  1811         -<li>Added a bunch more tests that take advantage of the new fcnt() function.
  1812         -    The new tests did not uncover any new problems.</li>
  1813         -}
  1814         -
  1815         -chng {2000 June 8} {
  1816         -<li>Added lots of new test cases</li>
  1817         -<li>Fix a few bugs discovered while adding test cases</li>
  1818         -<li>Begin adding lots of new documentation</li>
  1819         -}
  1820         -
  1821         -chng {2000 June 6} {
  1822         -<li>Added compound select operators: <B>UNION</b>, <b>UNION ALL</B>,
  1823         -<b>INTERSECT</b>, and <b>EXCEPT</b></li>
  1824         -<li>Added support for using <b>(SELECT ...)</b> within expressions</li>
  1825         -<li>Added support for <b>IN</b> and <b>BETWEEN</b> operators</li>
  1826         -<li>Added support for <b>GROUP BY</b> and <b>HAVING</b></li>
  1827         -<li>NULL values are now reported to the callback as a NULL pointer
  1828         -    rather than an empty string.</li>
  1829         -}
  1830         -
  1831         -chng {2000 June 3} {
  1832         -<li>Added support for default values on columns of a table.</li>
  1833         -<li>Improved test coverage.  Fixed a few obscure bugs found by the
  1834         -improved tests.</li>
  1835         -}
  1836         -
  1837         -chng {2000 June 2} {
  1838         -<li>All database files to be modified by an UPDATE, INSERT or DELETE are 
  1839         -now locked before any changes are made to any files.  
  1840         -This makes it safe (I think) to access
  1841         -the same database simultaneously from multiple processes.</li>
  1842         -<li>The code appears stable so we are now calling it "beta".</li>
  1843         -}
  1844         -
  1845         -chng {2000 June 1} {
  1846         -<li>Better support for file locking so that two or more processes 
  1847         -(or threads)
  1848         -can access the same database simultaneously.  More work needed in
  1849         -this area, though.</li>
  1850         -}
  1851         -
  1852         -chng {2000 May 31} {
  1853         -<li>Added support for aggregate functions (Ex: <b>COUNT(*)</b>, <b>MIN(...)</b>)
  1854         -to the SELECT statement.</li>
  1855         -<li>Added support for <B>SELECT DISTINCT ...</B></li>
  1856         -}
  1857         -
  1858         -chng {2000 May 30} {
  1859         -<li>Added the <b>LIKE</b> operator.</li>
  1860         -<li>Added a <b>GLOB</b> operator: similar to <B>LIKE</B> 
  1861         -but it uses Unix shell globbing wildcards instead of the '%' 
  1862         -and '_' wildcards of SQL.</li>
  1863         -<li>Added the <B>COPY</b> command patterned after 
  1864         -<a href="http://www.postgresql.org/">PostgreSQL</a> so that SQLite
  1865         -can now read the output of the <b>pg_dump</b> database dump utility
  1866         -of PostgreSQL.</li>
  1867         -<li>Added a <B>VACUUM</B> command that that calls the 
  1868         -<b>gdbm_reorganize()</b> function on the underlying database
  1869         -files.</li>
  1870         -<li>And many, many bug fixes...</li>
  1871         -}
  1872         -
  1873         -chng {2000 May 29} {
  1874         -<li>Initial Public Release of Alpha code</li>
  1875         -}
  1876         -
  1877         -puts {
  1878         -</DL>
  1879         -}
  1880         -footer {$Id:}

Deleted www/common.tcl.

     1         -# This file contains TCL procedures used to generate standard parts of
     2         -# web pages.
     3         -#
     4         -
     5         -proc header {txt} {
     6         -  puts "<html><head><title>$txt</title></head>"
     7         -  puts {<DIV class="pdf_ignore">}
     8         -  puts \
     9         -{<body bgcolor="white" link="#50695f" vlink="#508896">
    10         -<table width="100%" border="0">
    11         -<tr><td valign="top">
    12         -<a href="index.html"><img src="sqlite.gif" border="none"></a></td>
    13         -<td width="100%"></td>
    14         -<td valign="bottom">
    15         -<ul>
    16         -<li><a href="http://www.sqlite.org/cvstrac/tktnew">bugs</a></li>
    17         -<li><a href="changes.html">changes</a></li>
    18         -<li><a href="contrib">contrib</a></li>
    19         -<li><a href="download.html#cvs">cvs&nbsp;repository</a></li>
    20         -<li><a href="docs.html">documentation</a></li>
    21         -</ul>
    22         -</td>
    23         -<td width="10"></td>
    24         -<td valign="bottom">
    25         -<ul>
    26         -<li><a href="download.html">download</a></li>
    27         -<li><a href="faq.html">faq</a></li>
    28         -<li><a href="index.html">home</a></li>
    29         -<li><a href="copyright.html">license</a></li>
    30         -<li><a href="index.html">news</a></li>
    31         -</ul>
    32         -</td>
    33         -<td width="10"></td>
    34         -<td valign="bottom">
    35         -<ul>
    36         -<li><a href="quickstart.html">quick&nbsp;start</a></li>
    37         -<li><a href="support.html">support</a></li>
    38         -<li><a href="lang.html">syntax</a></li>
    39         -<li><a href="http://www.sqlite.org/cvstrac/timeline">timeline</a></li>
    40         -<li><a href="http://www.sqlite.org/cvstrac/wiki">wiki</a></li>
    41         -</ul>
    42         -</td>
    43         -</tr></table>
    44         -<table width="100%">
    45         -<tr><td bgcolor="#80a796"></td></tr>
    46         -</table>}
    47         -  puts </DIV>
    48         -}
    49         -
    50         -proc footer {{rcsid {}}} {
    51         -  puts {
    52         -<table width="100%">
    53         -<tr><td bgcolor="#80a796"></td></tr>
    54         -</table>}
    55         -  set date [lrange $rcsid 3 4]
    56         -  if {$date!=""} {
    57         -    puts "<small><i>This page last modified on $date</i></small>"
    58         -  }
    59         -  puts {</body></html>}
    60         -}
    61         -
    62         -
    63         -# The following proc is used to ensure consistent formatting in the 
    64         -# HTML generated by lang.tcl and pragma.tcl.
    65         -#
    66         -proc Syntax {args} {
    67         -  puts {<table cellpadding="10" class=pdf_syntax>}
    68         -  foreach {rule body} $args {
    69         -    puts "<tr><td align=\"right\" valign=\"top\">"
    70         -    puts "<i><font color=\"#ff3434\">$rule</font></i>&nbsp;::=</td>"
    71         -    regsub -all < $body {%LT} body
    72         -    regsub -all > $body {%GT} body
    73         -    regsub -all %LT $body {</font></b><i><font color="#ff3434">} body
    74         -    regsub -all %GT $body {</font></i><b><font color="#2c2cf0">} body
    75         -    regsub -all {[]|[*?]} $body {</font></b>&<b><font color="#2c2cf0">} body
    76         -    regsub -all "\n" [string trim $body] "<br>\n" body
    77         -    regsub -all "\n  *" $body "\n\\&nbsp;\\&nbsp;\\&nbsp;\\&nbsp;" body
    78         -    regsub -all {[|,.*()]} $body {<big>&</big>} body
    79         -    regsub -all { = } $body { <big>=</big> } body
    80         -    regsub -all {STAR} $body {<big>*</big>} body
    81         -    ## These metacharacters must be handled to undo being
    82         -    ## treated as SQL punctuation characters above.
    83         -    regsub -all {RPPLUS} $body {</font></b>)+<b><font color="#2c2cf0">} body
    84         -    regsub -all {LP} $body {</font></b>(<b><font color="#2c2cf0">} body
    85         -    regsub -all {RP} $body {</font></b>)<b><font color="#2c2cf0">} body
    86         -    ## Place the left-hand side of the rule in the 2nd table column.
    87         -    puts "<td><b><font color=\"#2c2cf0\">$body</font></b></td></tr>"
    88         -  }
    89         -  puts {</table>}
    90         -}

Deleted www/compile.tcl.

     1         -#
     2         -# Run this Tcl script to generate the compile.html file.
     3         -#
     4         -set rcsid {$Id: compile.tcl,v 1.5 2005/03/19 15:10:45 drh Exp $ }
     5         -source common.tcl
     6         -header {Compilation Options For SQLite}
     7         -
     8         -puts {
     9         -<h1>Compilation Options For SQLite</h1>
    10         -
    11         -<p>
    12         -For most purposes, SQLite can be built just fine using the default
    13         -compilation options. However, if required, the compile-time options
    14         -documented below can be used to 
    15         -<a href="#omitfeatures">omit SQLite features</a> (resulting in
    16         -a smaller compiled library size) or to change the
    17         -<a href="#defaults">default values</a> of some parameters.
    18         -</p>
    19         -<p>
    20         -Every effort has been made to ensure that the various combinations
    21         -of compilation options work harmoniously and produce a working library.
    22         -Nevertheless, it is strongly recommended that the SQLite test-suite
    23         -be executed to check for errors before using an SQLite library built
    24         -with non-standard compilation options.
    25         -</p>
    26         -<a name="defaults"></a>
    27         -<h2>Options To Set Default Parameter Values</h2>
    28         -
    29         -<p><b>SQLITE_DEFAULT_AUTOVACUUM=<i>&lt;1 or 0&gt;</i></b><br>
    30         -This macro determines if SQLite creates databases with the 
    31         -<a href="pragma.html#pragma_auto_vacuum">auto-vacuum</a> 
    32         -flag set by default. The default value is 0 (do not create auto-vacuum
    33         -databases). In any case the compile-time default may be overridden by the 
    34         -"PRAGMA auto_vacuum" command.
    35         -</p>
    36         -
    37         -<p><b>SQLITE_DEFAULT_CACHE_SIZE=<i>&lt;pages&gt;</i></b><br>
    38         -This macro sets the default size of the page-cache for each attached
    39         -database, in pages. This can be overridden by the "PRAGMA cache_size"
    40         -comamnd. The default value is 2000.
    41         -</p>
    42         -
    43         -<p><b>SQLITE_DEFAULT_PAGE_SIZE=<i>&lt;bytes&gt;</i></b><br>
    44         -This macro is used to set the default page-size used when a
    45         -database is created. The value assigned must be a power of 2. The
    46         -default value is 1024. The compile-time default may be overridden at 
    47         -runtime by the "PRAGMA page_size" command.
    48         -</p>
    49         -
    50         -<p><b>SQLITE_DEFAULT_TEMP_CACHE_SIZE=<i>&lt;pages&gt;</i></b><br>
    51         -This macro sets the default size of the page-cache for temporary files
    52         -created by SQLite to store intermediate results, in pages. It does
    53         -not affect the page-cache for the temp database, where tables created
    54         -using "CREATE TEMP TABLE" are stored. The default value is 500.
    55         -</p>
    56         -
    57         -<p><b>SQLITE_MAX_PAGE_SIZE=<i>&lt;bytes&gt;</i></b><br>
    58         -This is used to set the maximum allowable page-size that can
    59         -be specified by the "PRAGMA page_size" command. The default value
    60         -is 8192.
    61         -</p>
    62         -
    63         -<a name="omitfeatures"></a>
    64         -<h2>Options To Omit Features</h2>
    65         -
    66         -<p>The following options are used to reduce the size of the compiled
    67         -library by omiting optional features. This is probably only useful
    68         -in embedded systems where space is especially tight, as even with all
    69         -features included the SQLite library is relatively small. Don't forget
    70         -to tell your compiler to optimize for binary size! (the -Os option if
    71         -using GCC).</p>
    72         -
    73         -<p>The macros in this section do not require values. The following 
    74         -compilation switches all have the same effect:<br>
    75         --DSQLITE_OMIT_ALTERTABLE<br>
    76         --DSQLITE_OMIT_ALTERTABLE=1<br>
    77         --DSQLITE_OMIT_ALTERTABLE=0
    78         -</p>
    79         -
    80         -<p>If any of these options are defined, then the same set of SQLITE_OMIT_XXX
    81         -options must also be defined when using the 'lemon' tool to generate a parse.c
    82         -file. Because of this, these options may only used when the library is built
    83         -from source, not from the collection of pre-packaged C files provided for
    84         -non-UNIX like platforms on the website.
    85         -</p>
    86         -
    87         -<p><b>SQLITE_OMIT_ALTERTABLE</b><br>
    88         -When this option is defined, the 
    89         -<a href="lang_altertable.html">ALTER TABLE</a> command is not included in the 
    90         -library. Executing an ALTER TABLE statement causes a parse error.
    91         -</p>
    92         -
    93         -<p><b>SQLITE_OMIT_AUTHORIZATION</b><br>
    94         -Defining this option omits the authorization callback feature from the
    95         -library. The <a href="capi3ref.html#sqlite3_set_authorizer">
    96         -sqlite3_set_authorizer()</a> API function is not present in the library.
    97         -</p>
    98         -
    99         -<p><b>SQLITE_OMIT_AUTOVACUUM</b><br>
   100         -If this option is defined, the library cannot create or write to 
   101         -databases that support 
   102         -<a href="pragma.html#pragma_auto_vacuum">auto-vacuum</a>. Executing a
   103         -"PRAGMA auto_vacuum" statement is not an error, but does not return a value
   104         -or modify the auto-vacuum flag in the database file. If a database that
   105         -supports auto-vacuum is opened by a library compiled with this option, it
   106         -is automatically opened in read-only mode.
   107         -</p>
   108         -
   109         -<p><b>SQLITE_OMIT_AUTOINCREMENT</b><br>
   110         -This option is used to omit the AUTOINCREMENT functionality. When this 
   111         -is macro is defined, columns declared as "INTEGER PRIMARY KEY AUTOINCREMENT"
   112         -behave in the same way as columns declared as "INTEGER PRIMARY KEY" when a 
   113         -NULL is inserted. The sqlite_sequence system table is neither created, nor
   114         -respected if it already exists.
   115         -</p>
   116         -<p><i>TODO: Need a link here - AUTOINCREMENT is not yet documented</i><p>
   117         -
   118         -<p><b>SQLITE_OMIT_BLOB_LITERAL</b><br>
   119         -When this option is defined, it is not possible to specify a blob in
   120         -an SQL statement using the X'ABCD' syntax.</p> 
   121         -}
   122         -#<p>WARNING: The VACUUM command depends on this syntax for vacuuming databases
   123         -#that contain blobs, so disabling this functionality may render a database
   124         -#unvacuumable.
   125         -#</p>
   126         -#<p><i>TODO: Need a link here - is that syntax documented anywhere?</i><p>
   127         -puts {
   128         -
   129         -<p><b>SQLITE_OMIT_COMPLETE</b><br>
   130         -This option causes the <a href="capi3ref.html#sqlite3_complete">
   131         -sqlite3_complete</a> API to be omitted.
   132         -</p>
   133         -
   134         -<p><b>SQLITE_OMIT_COMPOUND_SELECT</b><br>
   135         -This option is used to omit the compound SELECT functionality. 
   136         -<a href="lang_select.html">SELECT statements</a> that use the 
   137         -UNION, UNION ALL, INTERSECT or EXCEPT compound SELECT operators will 
   138         -cause a parse error.
   139         -</p>
   140         -
   141         -<p><b>SQLITE_OMIT_CONFLICT_CLAUSE</b><br>
   142         -In the future, this option will be used to omit the 
   143         -<a href="lang_conflict.html">ON CONFLICT</a> clause from the library.
   144         -</p>
   145         -
   146         -<p><b>SQLITE_OMIT_DATETIME_FUNCS</b><br>
   147         -If this option is defined, SQLite's built-in date and time manipulation
   148         -functions are omitted. Specifically, the SQL functions julianday(), date(),
   149         -time(), datetime() and strftime() are not available. The default column
   150         -values CURRENT_TIME, CURRENT_DATE and CURRENT_DATETIME are still available.
   151         -</p>
   152         -
   153         -<p><b>SQLITE_OMIT_EXPLAIN</b><br>
   154         -Defining this option causes the EXPLAIN command to be omitted from the
   155         -library. Attempting to execute an EXPLAIN statement will cause a parse
   156         -error.
   157         -</p>
   158         -
   159         -<p><b>SQLITE_OMIT_FLOATING_POINT</b><br>
   160         -This option is used to omit floating-point number support from the SQLite
   161         -library. When specified, specifying a floating point number as a literal 
   162         -(i.e. "1.01") results in a parse error.
   163         -</p>
   164         -<p>In the future, this option may also disable other floating point 
   165         -functionality, for example the sqlite3_result_double(), 
   166         -sqlite3_bind_double(), sqlite3_value_double() and sqlite3_column_double() 
   167         -API functions.
   168         -</p>
   169         -
   170         -<p><b>SQLITE_OMIT_FOREIGN_KEY</b><br>
   171         -If this option is defined, FOREIGN KEY clauses in column declarations are
   172         -ignored.
   173         -</p>
   174         -
   175         -<p><b>SQLITE_OMIT_INTEGRITY_CHECK</b><br>
   176         -This option may be used to omit the 
   177         -<a href="pragma.html#pragma_integrity_check">"PRAGMA integrity_check"</a> 
   178         -command from the compiled library.
   179         -</p>
   180         -
   181         -<p><b>SQLITE_OMIT_MEMORYDB</b><br>
   182         -When this is defined, the library does not respect the special database
   183         -name ":memory:" (normally used to create an in-memory database). If 
   184         -":memory:" is passed to sqlite3_open(), a file with this name will be 
   185         -opened or created.
   186         -</p>
   187         -
   188         -<p><b>SQLITE_OMIT_PAGER_PRAGMAS</b><br>
   189         -Defining this option omits pragmas related to the pager subsystem from 
   190         -the build. Currently, the 
   191         -<a href="pragma.html#pragma_default_cache_size">default_cache_size</a> and 
   192         -<a href="pragma.html#pragma_cache_size">cache_size</a> pragmas are omitted.
   193         -</p>
   194         -
   195         -<p><b>SQLITE_OMIT_PRAGMA</b><br>
   196         -This option is used to omit the <a href="pragma.html">PRAGMA command</a> 
   197         -from the library. Note that it is useful to define the macros that omit
   198         -specific pragmas in addition to this, as they may also remove supporting code
   199         -in other sub-systems. This macro removes the PRAGMA command only.
   200         -</p>
   201         -
   202         -<p><b>SQLITE_OMIT_PROGRESS_CALLBACK</b><br>
   203         -This option may be defined to omit the capability to issue "progress" 
   204         -callbacks during long-running SQL statements. The 
   205         -<a href="capi3ref.html#sqlite3_progress_handler">sqlite3_progress_handler()</a>
   206         -API function is not present in the library.
   207         -
   208         -<p><b>SQLITE_OMIT_REINDEX</b><br>
   209         -When this option is defined, the <a href="lang_reindex.html">REINDEX</a> 
   210         -command is not included in the library. Executing a REINDEX statement causes 
   211         -a parse error.
   212         -</p>
   213         -
   214         -<p><b>SQLITE_OMIT_SCHEMA_PRAGMAS</b><br>
   215         -Defining this option omits pragmas for querying the database schema from 
   216         -the build. Currently, the 
   217         -<a href="pragma.html#pragma_table_info">table_info</a>,
   218         -<a href="pragma.html#pragma_index_info">index_info</a>,
   219         -<a href="pragma.html#pragma_index_list">index_list</a> and
   220         -<a href="pragma.html#pragma_database_list">database_list</a>
   221         -pragmas are omitted.
   222         -</p>
   223         -
   224         -<p><b>SQLITE_OMIT_SCHEMA_VERSION_PRAGMAS</b><br>
   225         -Defining this option omits pragmas for querying and modifying the 
   226         -database schema version and user version from the build. Specifically, the 
   227         -<a href="pragma.html#pragma_schema_version">schema_version</a> and
   228         -<a href="pragma.html#pragma_user_version">user_version</a>
   229         -pragmas are omitted.
   230         -
   231         -<p><b>SQLITE_OMIT_SUBQUERY</b><br>
   232         -<p>If defined, support for sub-selects and the IN() operator are omitted.
   233         -</p>
   234         -
   235         -<p><b>SQLITE_OMIT_TCL_VARIABLE</b><br>
   236         -<p>If this macro is defined, then the special "$<variable-name>" syntax
   237         -used to automatically bind SQL variables to TCL variables is omitted.
   238         -</p>
   239         -
   240         -<p><b>SQLITE_OMIT_TRIGGER</b><br>
   241         -Defining this option omits support for VIEW objects. Neither the 
   242         -<a href="lang_createtrigger.html">CREATE TRIGGER</a> or 
   243         -<a href="lang_droptrigger.html">DROP TRIGGER</a> 
   244         -commands are available in this case, attempting to execute either will result
   245         -in a parse error.
   246         -</p>
   247         -<p>
   248         -WARNING: If this macro is defined, it will not be possible to open a database
   249         -for which the schema contains TRIGGER objects. 
   250         -</p>
   251         -
   252         -<p><b>SQLITE_OMIT_UTF16</b><br>
   253         -This macro is used to omit support for UTF16 text encoding. When this is
   254         -defined all API functions that return or accept UTF16 encoded text are
   255         -unavailable. These functions can be identified by the fact that they end
   256         -with '16', for example sqlite3_prepare16(), sqlite3_column_text16() and
   257         -sqlite3_bind_text16().
   258         -</p>
   259         -
   260         -<p><b>SQLITE_OMIT_VACUUM</b><br>
   261         -When this option is defined, the <a href="lang_vacuum.html">VACUUM</a> 
   262         -command is not included in the library. Executing a VACUUM statement causes 
   263         -a parse error.
   264         -</p>
   265         -
   266         -<p><b>SQLITE_OMIT_VIEW</b><br>
   267         -Defining this option omits support for VIEW objects. Neither the 
   268         -<a href="lang_createview.html">CREATE VIEW</a> or 
   269         -<a href="lang_dropview.html">DROP VIEW</a> 
   270         -commands are available in this case, attempting to execute either will result
   271         -in a parse error.
   272         -</p>
   273         -<p>
   274         -WARNING: If this macro is defined, it will not be possible to open a database
   275         -for which the schema contains VIEW objects. 
   276         -</p>
   277         -}
   278         -footer $rcsid

Deleted www/conflict.tcl.

     1         -#
     2         -# Run this Tcl script to generate the constraint.html file.
     3         -#
     4         -set rcsid {$Id: conflict.tcl,v 1.4 2004/10/10 17:24:55 drh Exp $ }
     5         -source common.tcl
     6         -header {Constraint Conflict Resolution in SQLite}
     7         -puts {
     8         -<h1>Constraint Conflict Resolution in SQLite</h1>
     9         -
    10         -<p>
    11         -In most SQL databases, if you have a UNIQUE constraint on
    12         -a table and you try to do an UPDATE or INSERT that violates
    13         -the constraint, the database will abort the operation in
    14         -progress, back out any prior changes associated with
    15         -UPDATE or INSERT command, and return an error.
    16         -This is the default behavior of SQLite.
    17         -Beginning with version 2.3.0, though, SQLite allows you to
    18         -define alternative ways for dealing with constraint violations.
    19         -This article describes those alternatives and how to use them.
    20         -</p>
    21         -
    22         -<h2>Conflict Resolution Algorithms</h2>
    23         -
    24         -<p>
    25         -SQLite defines five constraint conflict resolution algorithms
    26         -as follows:
    27         -</p>
    28         -
    29         -<dl>
    30         -<dt><b>ROLLBACK</b></dt>
    31         -<dd><p>When a constraint violation occurs, an immediate ROLLBACK
    32         -occurs, thus ending the current transaction, and the command aborts
    33         -with a return code of SQLITE_CONSTRAINT.  If no transaction is
    34         -active (other than the implied transaction that is created on every
    35         -command) then this algorithm works the same as ABORT.</p></dd>
    36         -
    37         -<dt><b>ABORT</b></dt>
    38         -<dd><p>When a constraint violation occurs, the command backs out
    39         -any prior changes it might have made and aborts with a return code
    40         -of SQLITE_CONSTRAINT.  But no ROLLBACK is executed so changes
    41         -from prior commands within the same transaction
    42         -are preserved.  This is the default behavior for SQLite.</p></dd>
    43         -
    44         -<dt><b>FAIL</b></dt>
    45         -<dd><p>When a constraint violation occurs, the command aborts with a
    46         -return code SQLITE_CONSTRAINT.  But any changes to the database that
    47         -the command made prior to encountering the constraint violation
    48         -are preserved and are not backed out.  For example, if an UPDATE
    49         -statement encountered a constraint violation on the 100th row that
    50         -it attempts to update, then the first 99 row changes are preserved
    51         -by change to rows 100 and beyond never occur.</p></dd>
    52         -
    53         -<dt><b>IGNORE</b></dt>
    54         -<dd><p>When a constraint violation occurs, the one row that contains
    55         -the constraint violation is not inserted or changed.  But the command
    56         -continues executing normally.  Other rows before and after the row that
    57         -contained the constraint violation continue to be inserted or updated
    58         -normally.  No error is returned.</p></dd>
    59         -
    60         -<dt><b>REPLACE</b></dt>
    61         -<dd><p>When a UNIQUE constraint violation occurs, the pre-existing row
    62         -that caused the constraint violation is removed prior to inserting
    63         -or updating the current row.  Thus the insert or update always occurs.
    64         -The command continues executing normally.  No error is returned.</p></dd>
    65         -</dl>
    66         -
    67         -<h2>Why So Many Choices?</h2>
    68         -
    69         -<p>SQLite provides multiple conflict resolution algorithms for a
    70         -couple of reasons.  First, SQLite tries to be roughly compatible with as
    71         -many other SQL databases as possible, but different SQL database
    72         -engines exhibit different conflict resolution strategies.  For
    73         -example, PostgreSQL always uses ROLLBACK, Oracle always uses ABORT, and
    74         -MySQL usually uses FAIL but can be instructed to use IGNORE or REPLACE.
    75         -By supporting all five alternatives, SQLite provides maximum
    76         -portability.</p>
    77         -
    78         -<p>Another reason for supporting multiple algorithms is that sometimes
    79         -it is useful to use an algorithm other than the default.
    80         -Suppose, for example, you are
    81         -inserting 1000 records into a database, all within a single
    82         -transaction, but one of those records is malformed and causes
    83         -a constraint error.  Under PostgreSQL or Oracle, none of the
    84         -1000 records would get inserted.  In MySQL, some subset of the
    85         -records that appeared before the malformed record would be inserted
    86         -but the rest would not.  Neither behavior is especially helpful.
    87         -What you really want is to use the IGNORE algorithm to insert
    88         -all but the malformed record.</p>
    89         -
    90         -}
    91         -footer $rcsid

Deleted www/copyright-release.html.

     1         -<html>
     2         -<body bgcolor="white">
     3         -<h1 align="center">
     4         -Copyright Release for<br>
     5         -Contributions To SQLite
     6         -</h1>
     7         -
     8         -<p>
     9         -SQLite is software that implements an embeddable SQL database engine.
    10         -SQLite is available for free download from http://www.sqlite.org/.
    11         -The principal author and maintainer of SQLite has disclaimed all
    12         -copyright interest in his contributions to SQLite
    13         -and thus released his contributions into the public domain.
    14         -In order to keep the SQLite software unencumbered by copyright
    15         -claims, the principal author asks others who may from time to
    16         -time contribute changes and enhancements to likewise disclaim
    17         -their own individual copyright interest.
    18         -</p>
    19         -
    20         -<p>
    21         -Because the SQLite software found at http://www.sqlite.org/ is in the
    22         -public domain, anyone is free to download the SQLite software
    23         -from that website, make changes to the software, use, distribute,
    24         -or sell the modified software, under either the original name or
    25         -under some new name, without any need to obtain permission, pay
    26         -royalties, acknowledge the original source of the software, or
    27         -in any other way compensate, identify, or notify the original authors.  
    28         -Nobody is in any way compelled to contribute their SQLite changes and 
    29         -enhancements back to the SQLite website.  This document concerns
    30         -only changes and enhancements to SQLite that are intentionally and
    31         -deliberately contributed back to the SQLite website.  
    32         -</p>
    33         -
    34         -<p>
    35         -For the purposes of this document, "SQLite software" shall mean any
    36         -computer source code, documentation, makefiles, test scripts, or
    37         -other information that is published on the SQLite website, 
    38         -http://www.sqlite.org/.  Precompiled binaries are excluded from
    39         -the definition of "SQLite software" in this document because the
    40         -process of compiling the software may introduce information from
    41         -outside sources which is not properly a part of SQLite.
    42         -</p>
    43         -
    44         -<p>
    45         -The header comments on the SQLite source files exhort the reader to
    46         -share freely and to never take more than one gives.
    47         -In the spirit of that exhortation I make the following declarations:
    48         -</p>
    49         -
    50         -<ol>
    51         -<li><p>
    52         -I dedicate to the public domain 
    53         -any and all copyright interest in the SQLite software that
    54         -was publicly available on the SQLite website (http://www.sqlite.org/) prior
    55         -to the date of the signature below and any changes or enhancements to
    56         -the SQLite software 
    57         -that I may cause to be published on that website in the future.
    58         -I make this dedication for the benefit of the public at large and
    59         -to the detriment of my heirs and successors.  I intend this
    60         -dedication to be an overt act of relinquishment in perpetuity of
    61         -all present and future rights to the SQLite software under copyright
    62         -law.
    63         -</p></li>
    64         -
    65         -<li><p>
    66         -To the best of my knowledge and belief, the changes and enhancements that
    67         -I have contributed to SQLite are either originally written by me
    68         -or are derived from prior works which I have verified are also
    69         -in the public domain and are not subject to claims of copyright
    70         -by other parties.
    71         -</p></li>
    72         -
    73         -<li><p>
    74         -To the best of my knowledge and belief, no individual, business, organization,
    75         -government, or other entity has any copyright interest
    76         -in the SQLite software as it existed on the
    77         -SQLite website as of the date on the signature line below.
    78         -</p></li>
    79         -
    80         -<li><p>
    81         -I agree never to publish any additional information
    82         -to the SQLite website (by CVS, email, scp, FTP, or any other means) unless
    83         -that information is an original work of authorship by me or is derived from 
    84         -prior published versions of SQLite.
    85         -I agree never to copy and paste code into the SQLite code base from
    86         -other sources.
    87         -I agree never to publish on the SQLite website any information that
    88         -would violate a law or breach a contract.
    89         -</p></li>
    90         -</ol>
    91         -
    92         -<p>
    93         -<table width="100%" cellpadding="0" cellspacing="0">
    94         -<tr>
    95         -<td width="60%" valign="top">
    96         -Signature:
    97         -<p>&nbsp;</p>
    98         -<p>&nbsp;</p>
    99         -<p>&nbsp;</p>
   100         -</td><td valign="top" align="left">
   101         -Date:
   102         -</td></tr>
   103         -<td colspan=2>
   104         -Name (printed):
   105         -</td>
   106         -</tr>
   107         -</table>
   108         -</body>
   109         -</html>

Deleted www/copyright-release.pdf.

cannot compute difference between binary files

Deleted www/copyright.tcl.

     1         -set rcsid {$Id: copyright.tcl,v 1.7 2007/05/06 21:20:43 drh Exp $}
     2         -source common.tcl
     3         -header {SQLite Copyright}
     4         -puts {
     5         -<h2>SQLite Copyright</h2>
     6         -
     7         -<table align="right" vspace="0" hspace="10" border="1" cellpadding="20">
     8         -<tr><td align="center">
     9         -<img src="nocopy.gif"><br>
    10         -SQLite is in the<br>
    11         -<a href="http://en.wikipedia.org/wiki/Public_Domain">Public Domain</a>
    12         -</td></tr>
    13         -</table>
    14         -
    15         -<p>
    16         -All of the deliverable code in SQLite has been dedicated to the
    17         -<a href="http://en.wikipedia.org/wiki/Public_Domain">public domain</a>
    18         -by the authors.
    19         -All code authors, and representatives of the companies they work for,
    20         -have signed affidavits dedicating their contributions to
    21         -the public domain and originals of
    22         -those signed affidavits are stored in a firesafe at the main offices
    23         -of <a href="http://www.hwaci.com">Hwaci</a>.
    24         -Anyone is free to copy, modify, publish, use, compile, sell, or distribute
    25         -the original SQLite code, either in source code form or as a compiled binary,
    26         -for any purpose, commercial or non-commercial, and by any means.
    27         -</p>
    28         -
    29         -<p>
    30         -The previous paragraph applies to the deliverable code in SQLite - 
    31         -those parts of the SQLite library that you actually bundle and
    32         -ship with a larger application.  Portions of the documentation and
    33         -some code used as part of the build process might fall under
    34         -other licenses.  The details here are unclear.  We do not worry
    35         -about the licensing of the documentation and build code so much
    36         -because none of these things are part of the core deliverable
    37         -SQLite library.
    38         -</p>
    39         -
    40         -<p>
    41         -All of the deliverable code in SQLite has been written from scratch.
    42         -No code has been taken from other projects or from the open
    43         -internet.  Every line of code can be traced back to its original
    44         -author, and all of those authors have public domain dedications
    45         -on file.  So the SQLite code base is clean and is
    46         -uncontaminated with licensed code from other projects.
    47         -</p>
    48         -
    49         -<h2>Obtaining An Explicit License To Use SQLite</h2>
    50         -
    51         -<p>
    52         -Even though SQLite is in the public domain and does not require
    53         -a license, some users want to obtain a license anyway.  Some reasons
    54         -for obtaining a license include:
    55         -</p>
    56         -
    57         -<ul>
    58         -<li> You are using SQLite in a jurisdiction that does not recognize
    59         -     the public domain.  </li>
    60         -<li> You are using SQLite in a jurisdiction that does not recognize
    61         -     the right of an author to dedicate their work to the public
    62         -     domain. </li>
    63         -<li> You want to hold a tangible legal document
    64         -     as evidence that you have the legal right to use and distribute
    65         -     SQLite. </li>
    66         -<li> Your legal department tells you that you have to purchase a license.
    67         -     </li>
    68         -</ul>
    69         -
    70         -<p>
    71         -If you feel like you really have to purchase a license for SQLite,
    72         -<a href="http://www.hwaci.com/">Hwaci</a>, the company that employs 
    73         -the architect and principal developers of SQLite, will sell you
    74         -one.
    75         -Please contact:
    76         -</p>
    77         -
    78         -<blockquote>
    79         -D. Richard Hipp <br />
    80         -Hwaci - Applied Software Research <br />
    81         -704.948.4565 <br />
    82         -<a href="mailto:drh@hwaci.com">drh@hwaci.com</a>
    83         -</blockquote>
    84         -
    85         -<h2>Contributed Code</h2>
    86         -
    87         -<p>
    88         -In order to keep SQLite completely free and unencumbered by copyright,
    89         -all new contributors to the SQLite code base are asked to dedicate
    90         -their contributions to the public domain.
    91         -If you want to send a patch or enhancement for possible inclusion in the
    92         -SQLite source tree, please accompany the patch with the following statement:
    93         -</p>
    94         -
    95         -<blockquote><i>
    96         -The author or authors of this code dedicate any and all copyright interest
    97         -in this code to the public domain.  We make this dedication for the benefit
    98         -of the public at large and to the detriment of our heirs and successors.
    99         -We intend this dedication to be an overt act of relinquishment in
   100         -perpetuity of all present and future rights to this code under copyright law.
   101         -</i></blockquote>
   102         -
   103         -<p>
   104         -We are not able to accept patches or changes to 
   105         -SQLite that are not accompanied by a statement such as the above.
   106         -In addition, if you make
   107         -changes or enhancements as an employee, then a simple statement such as the
   108         -above is insufficient.  You must also send by surface mail a copyright release
   109         -signed by a company officer.
   110         -A signed original of the copyright release should be mailed to:</p>
   111         -
   112         -<blockquote>
   113         -Hwaci<br>
   114         -6200 Maple Cove Lane<br>
   115         -Charlotte, NC 28269<br>
   116         -USA
   117         -</blockquote>
   118         -
   119         -<p>
   120         -A template copyright release is available
   121         -in <a href="copyright-release.pdf">PDF</a> or
   122         -<a href="copyright-release.html">HTML</a>.
   123         -You can use this release to make future changes. 
   124         -</p>
   125         -}
   126         -footer $rcsid

Deleted www/datatype3.tcl.

     1         -set rcsid {$Id: datatype3.tcl,v 1.17 2007/06/20 16:13:23 drh Exp $}
     2         -source common.tcl
     3         -header {Datatypes In SQLite Version 3}
     4         -puts {
     5         -<h2>Datatypes In SQLite Version 3</h2>
     6         -
     7         -<h3>1. Storage Classes</h3>
     8         -
     9         -<P>Version 2 of SQLite stores all column values as ASCII text.
    10         -Version 3 enhances this by providing the ability to store integer and
    11         -real numbers in a more compact format and the capability to store
    12         -BLOB data.</P>
    13         -
    14         -<P>Each value stored in an SQLite database (or manipulated by the
    15         -database engine) has one of the following storage classes:</P>
    16         -<UL>
    17         -	<LI><P><B>NULL</B>. The value is a NULL value.</P>
    18         -	<LI><P><B>INTEGER</B>. The value is a signed integer, stored in 1,
    19         -	2, 3, 4, 6, or 8 bytes depending on the magnitude of the value.</P>
    20         -	<LI><P><B>REAL</B>. The value is a floating point value, stored as
    21         -	an 8-byte IEEE floating point number.</P>
    22         -	<LI><P><B>TEXT</B>. The value is a text string, stored using the
    23         -	database encoding (UTF-8, UTF-16BE or UTF-16-LE).</P>
    24         -	<LI><P><B>BLOB</B>. The value is a blob of data, stored exactly as
    25         -	it was input.</P>
    26         -</UL>
    27         -
    28         -<P>As in SQLite version 2, any column in a version 3 database except an INTEGER
    29         -PRIMARY KEY may be used to store any type of value. The exception to
    30         -this rule is described below under 'Strict Affinity Mode'.</P>
    31         -
    32         -<P>All values supplied to SQLite, whether as literals embedded in SQL
    33         -statements or values bound to pre-compiled SQL statements
    34         -are assigned a storage class before the SQL statement is executed.
    35         -Under circumstances described below, the
    36         -database engine may convert values between numeric storage classes
    37         -(INTEGER and REAL) and TEXT during query execution. 
    38         -</P>
    39         -
    40         -<P>Storage classes are initially assigned as follows:</P>
    41         -<UL>
    42         -	<LI><P>Values specified as literals as part of SQL statements are
    43         -	assigned storage class TEXT if they are enclosed by single or double
    44         -	quotes, INTEGER if the literal is specified as an unquoted number
    45         -	with no decimal point or exponent, REAL if the literal is an
    46         -	unquoted number with a decimal point or exponent and NULL if the
    47         -	value is a NULL. Literals with storage class BLOB are specified
    48         -        using the X'ABCD' notation.</P>
    49         -	<LI><P>Values supplied using the sqlite3_bind_* APIs are assigned
    50         -	the storage class that most closely matches the native type bound
    51         -	(i.e. sqlite3_bind_blob() binds a value with storage class BLOB).</P>
    52         -</UL>
    53         -<P>The storage class of a value that is the result of an SQL scalar
    54         -operator depends on the outermost operator of the expression.
    55         -User-defined functions may return values with any storage class. It
    56         -is not generally possible to determine the storage class of the
    57         -result of an expression at compile time.</P>
    58         -
    59         -<a name="affinity">
    60         -<h3>2. Column Affinity</h3>
    61         -
    62         -<p>
    63         -In SQLite version 3, the type of a value is associated with the value
    64         -itself, not with the column or variable in which the value is stored.
    65         -(This is sometimes called
    66         -<a href="http://www.cliki.net/manifest%20type%20system">
    67         -manifest typing</a>.)
    68         -All other SQL databases engines that we are aware of use the more
    69         -restrictive system of static typing where the type is associated with
    70         -the container, not the value.
    71         -</p>
    72         -
    73         -<p>
    74         -In order to maximize compatibility between SQLite and other database
    75         -engines, SQLite support the concept of "type affinity" on columns.
    76         -The type affinity of a column is the recommended type for data stored
    77         -in that column.  The key here is that the type is recommended, not
    78         -required.  Any column can still store any type of data, in theory.
    79         -It is just that some columns, given the choice, will prefer to use
    80         -one storage class over another.  The preferred storage class for
    81         -a column is called its "affinity".
    82         -</p>
    83         -
    84         -<P>Each column in an SQLite 3 database is assigned one of the
    85         -following type affinities:</P>
    86         -<UL>
    87         -	<LI>TEXT</LI>
    88         -	<LI>NUMERIC</LI>
    89         -	<LI>INTEGER</LI>
    90         -        <LI>REAL</li>
    91         -	<LI>NONE</LI>
    92         -</UL>
    93         -
    94         -<P>A column with TEXT affinity stores all data using storage classes
    95         -NULL, TEXT or BLOB. If numerical data is inserted into a column with
    96         -TEXT affinity it is converted to text form before being stored.</P>
    97         -
    98         -<P>A column with NUMERIC affinity may contain values using all five
    99         -storage classes. When text data is inserted into a NUMERIC column, an
   100         -attempt is made to convert it to an integer or real number before it
   101         -is stored. If the conversion is successful, then the value is stored
   102         -using the INTEGER or REAL storage class. If the conversion cannot be
   103         -performed the value is stored using the TEXT storage class. No
   104         -attempt is made to convert NULL or blob values.</P>
   105         -
   106         -<P>A column that uses INTEGER affinity behaves in the same way as a
   107         -column with NUMERIC affinity, except that if a real value with no
   108         -floating point component (or text value that converts to such) is
   109         -inserted it is converted to an integer and stored using the INTEGER
   110         -storage class.</P>
   111         -
   112         -<P>A column with REAL affinity behaves like a column with NUMERIC
   113         -affinity except that it forces integer values into floating point
   114         -representation.  (As an optimization, integer values are stored on
   115         -disk as integers in order to take up less space and are only converted
   116         -to floating point as the value is read out of the table.)</P>
   117         -
   118         -<P>A column with affinity NONE does not prefer one storage class over
   119         -another.  It makes no attempt to coerce data before
   120         -it is inserted.</P>
   121         -
   122         -<h4>2.1 Determination Of Column Affinity</h4>
   123         -
   124         -<P>The type affinity of a column is determined by the declared type
   125         -of the column, according to the following rules:</P>
   126         -<OL>
   127         -	<LI><P>If the datatype contains the string &quot;INT&quot; then it
   128         -	is assigned INTEGER affinity.</P>
   129         -
   130         -	<LI><P>If the datatype of the column contains any of the strings
   131         -	&quot;CHAR&quot;, &quot;CLOB&quot;, or &quot;TEXT&quot; then that
   132         -	column has TEXT affinity. Notice that the type VARCHAR contains the
   133         -	string &quot;CHAR&quot; and is thus assigned TEXT affinity.</P>
   134         -
   135         -	<LI><P>If the datatype for a column
   136         -         contains the string &quot;BLOB&quot; or if
   137         -        no datatype is specified then the column has affinity NONE.</P>
   138         -
   139         -        <LI><P>If the datatype for a column
   140         -        contains any of the strings &quot;REAL&quot;, &quot;FLOA&quot;,
   141         -        or &quot;DOUB&quot; then the column has REAL affinity</P>
   142         -
   143         -	<LI><P>Otherwise, the affinity is NUMERIC.</P>
   144         -</OL>
   145         -
   146         -<P>If a table is created using a "CREATE TABLE &lt;table&gt; AS
   147         -SELECT..." statement, then all columns have no datatype specified
   148         -and they are given no affinity.</P>
   149         -
   150         -<h4>2.2 Column Affinity Example</h4>
   151         -
   152         -<blockquote>
   153         -<PRE>CREATE TABLE t1(
   154         -    t  TEXT,
   155         -    nu NUMERIC, 
   156         -    i  INTEGER,
   157         -    no BLOB
   158         -);
   159         -
   160         --- Storage classes for the following row:
   161         --- TEXT, REAL, INTEGER, TEXT
   162         -INSERT INTO t1 VALUES('500.0', '500.0', '500.0', '500.0');
   163         -
   164         --- Storage classes for the following row:
   165         --- TEXT, REAL, INTEGER, REAL
   166         -INSERT INTO t1 VALUES(500.0, 500.0, 500.0, 500.0);
   167         -</PRE>
   168         -</blockquote>
   169         -
   170         -<a name="comparisons">
   171         -<h3>3. Comparison Expressions</h3>
   172         -
   173         -<P>Like SQLite version 2, version 3
   174         -features the binary comparison operators '=',
   175         -'&lt;', '&lt;=', '&gt;=' and '!=', an operation to test for set
   176         -membership, 'IN', and the ternary comparison operator 'BETWEEN'.</P>
   177         -<P>The results of a comparison depend on the storage classes of the
   178         -two values being compared, according to the following rules:</P>
   179         -<UL>
   180         -	<LI><P>A value with storage class NULL is considered less than any
   181         -	other value (including another value with storage class NULL).</P>
   182         -
   183         -	<LI><P>An INTEGER or REAL value is less than any TEXT or BLOB value.
   184         -	When an INTEGER or REAL is compared to another INTEGER or REAL, a
   185         -	numerical comparison is performed.</P>
   186         -
   187         -	<LI><P>A TEXT value is less than a BLOB value. When two TEXT values
   188         -	are compared, the C library function memcmp() is usually used to
   189         -	determine the result. However this can be overridden, as described
   190         -	under 'User-defined collation Sequences' below.</P>
   191         -
   192         -	<LI><P>When two BLOB values are compared, the result is always
   193         -	determined using memcmp().</P>
   194         -</UL>
   195         -
   196         -<P>SQLite may attempt to convert values between the numeric storage
   197         -classes (INTEGER and REAL) and TEXT before performing a comparison.
   198         -For binary comparisons, this is done in the cases enumerated below.
   199         -The term "expression" used in the bullet points below means any
   200         -SQL scalar expression or literal other than a column value.  Note that
   201         -if X and Y.Z are a column names, then +X and +Y.Z are considered
   202         -expressions.</P>
   203         -<UL>
   204         -	<LI><P>When a column value is compared to the result of an
   205         -	expression, the affinity of the column is applied to the result of
   206         -	the expression before the comparison takes place.</P>
   207         -
   208         -	<LI><P>When two column values are compared, if one column has
   209         -	INTEGER or REAL or NUMERIC affinity and the other does not, 
   210         -        then NUMERIC affinity is applied to any values with storage
   211         -        class TEXT extracted from the non-NUMERIC column.</P>
   212         -
   213         -	<LI><P>When the results of two expressions are compared, no
   214         -        conversions occur.  The results are compared as is.  If a string
   215         -        is compared to a number, the number will always be less than the
   216         -        string.</P>
   217         -</UL>
   218         -
   219         -<P>
   220         -In SQLite, the expression "a BETWEEN b AND c" is equivalent to "a &gt;= b
   221         -AND a &lt;= c", even if this means that different affinities are applied to
   222         -'a' in each of the comparisons required to evaluate the expression.
   223         -</P>
   224         -
   225         -<P>Expressions of the type "a IN (SELECT b ....)" are handled by the three
   226         -rules enumerated above for binary comparisons (e.g. in a
   227         -similar manner to "a = b"). For example if 'b' is a column value
   228         -and 'a' is an expression, then the affinity of 'b' is applied to 'a'
   229         -before any comparisons take place.</P>
   230         -
   231         -<P>SQLite treats the expression "a IN (x, y, z)" as equivalent to "a = +x OR
   232         -a = +y OR a = +z".  The values to the right of the IN operator (the "x", "y",
   233         -and "z" values in this example) are considered to be expressions, even if they
   234         -happen to be column values.  If the value of the left of the IN operator is
   235         -a column, then the affinity of that column is used.  If the value is an
   236         -expression then no conversions occur.
   237         -</P>
   238         -
   239         -<h4>3.1 Comparison Example</h4>
   240         -
   241         -<blockquote>
   242         -<PRE>
   243         -CREATE TABLE t1(
   244         -    a TEXT,
   245         -    b NUMERIC,
   246         -    c BLOB
   247         -);
   248         -
   249         --- Storage classes for the following row:
   250         --- TEXT, REAL, TEXT
   251         -INSERT INTO t1 VALUES('500', '500', '500');
   252         -
   253         --- 60 and 40 are converted to '60' and '40' and values are compared as TEXT.
   254         -SELECT a &lt; 60, a &lt; 40 FROM t1;
   255         -1|0
   256         -
   257         --- Comparisons are numeric. No conversions are required.
   258         -SELECT b &lt; 60, b &lt; 600 FROM t1;
   259         -0|1
   260         -
   261         --- Both 60 and 600 (storage class NUMERIC) are less than '500'
   262         --- (storage class TEXT).
   263         -SELECT c &lt; 60, c &lt; 600 FROM t1;
   264         -0|0
   265         -</PRE>
   266         -</blockquote>
   267         -<h3>4. Operators</h3>
   268         -
   269         -<P>All mathematical operators (which is to say, all operators other
   270         -than the concatenation operator &quot;||&quot;) apply NUMERIC
   271         -affinity to all operands prior to being carried out. If one or both
   272         -operands cannot be converted to NUMERIC then the result of the
   273         -operation is NULL.</P>
   274         -
   275         -<P>For the concatenation operator, TEXT affinity is applied to both
   276         -operands. If either operand cannot be converted to TEXT (because it
   277         -is NULL or a BLOB) then the result of the concatenation is NULL.</P>
   278         -
   279         -<h3>5. Sorting, Grouping and Compound SELECTs</h3>
   280         -
   281         -<P>When values are sorted by an ORDER by clause, values with storage
   282         -class NULL come first, followed by INTEGER and REAL values
   283         -interspersed in numeric order, followed by TEXT values usually in
   284         -memcmp() order, and finally BLOB values in memcmp() order. No storage
   285         -class conversions occur before the sort.</P>
   286         -
   287         -<P>When grouping values with the GROUP BY clause values with
   288         -different storage classes are considered distinct, except for INTEGER
   289         -and REAL values which are considered equal if they are numerically
   290         -equal. No affinities are applied to any values as the result of a
   291         -GROUP by clause.</P>
   292         -
   293         -<P>The compound SELECT operators UNION,
   294         -INTERSECT and EXCEPT perform implicit comparisons between values.
   295         -Before these comparisons are performed an affinity may be applied to
   296         -each value. The same affinity, if any, is applied to all values that
   297         -may be returned in a single column of the compound SELECT result set.
   298         -The affinity applied is the affinity of the column returned by the
   299         -left most component SELECTs that has a column value (and not some
   300         -other kind of expression) in that position. If for a given compound
   301         -SELECT column none of the component SELECTs return a column value, no
   302         -affinity is applied to the values from that column before they are
   303         -compared.</P>
   304         -
   305         -<h3>6. Other Affinity Modes</h3>
   306         -
   307         -<P>The above sections describe the operation of the database engine
   308         -in 'normal' affinity mode. SQLite version 3 will feature two other affinity
   309         -modes, as follows:</P>
   310         -<UL>
   311         -	<LI><P><B>Strict affinity</B> mode. In this mode if a conversion
   312         -	between storage classes is ever required, the database engine
   313         -	returns an error and the current statement is rolled back.</P>
   314         -
   315         -	<LI><P><B>No affinity</B> mode. In this mode no conversions between
   316         -	storage classes are ever performed. Comparisons between values of
   317         -	different storage classes (except for INTEGER and REAL) are always
   318         -	false.</P>
   319         -</UL>
   320         -
   321         -<a name="collation"></a>
   322         -<h3>7. User-defined Collation Sequences</h3>
   323         -
   324         -<p>
   325         -By default, when SQLite compares two text values, the result of the
   326         -comparison is determined using memcmp(), regardless of the encoding of the
   327         -string. SQLite v3 provides the ability for users to supply arbitrary
   328         -comparison functions, known as user-defined collation sequences, to be used
   329         -instead of memcmp().
   330         -</p>  
   331         -<p>
   332         -Aside from the default collation sequence BINARY, implemented using
   333         -memcmp(), SQLite features one extra built-in collation sequences 
   334         -intended for testing purposes, the NOCASE collation:
   335         -</p>  
   336         -<UL>
   337         -	<LI><b>BINARY</b> - Compares string data using memcmp(), regardless
   338         -                            of text encoding.</LI>
   339         -	<LI><b>NOCASE</b> - The same as binary, except the 26 upper case
   340         -			    characters used by the English language are
   341         -			    folded to their lower case equivalents before
   342         -                            the comparison is performed.  </UL>
   343         -
   344         -
   345         -<h4>7.1 Assigning Collation Sequences from SQL</h4>
   346         -
   347         -<p>
   348         -Each column of each table has a default collation type. If a collation type
   349         -other than BINARY is required, a COLLATE clause is specified as part of the
   350         -<a href="lang_createtable.html">column definition</a> to define it. 
   351         -</p>  
   352         -
   353         -<p>
   354         -Whenever two text values are compared by SQLite, a collation sequence is
   355         -used to determine the results of the comparison according to the following
   356         -rules. Sections 3 and 5 of this document describe the circumstances under
   357         -which such a comparison takes place.
   358         -</p>  
   359         -
   360         -<p>
   361         -For binary comparison operators (=, <, >, <= and >=) if either operand is a
   362         -column, then the default collation type of the column determines the
   363         -collation sequence to use for the comparison. If both operands are columns,
   364         -then the collation type for the left operand determines the collation
   365         -sequence used. If neither operand is a column, then the BINARY collation
   366         -sequence is used.  For the purposes of this paragraph, a column name
   367         -preceded by one or more unary "+" operators is considered a column name.
   368         -</p>  
   369         -
   370         -<p>
   371         -The expression "x BETWEEN y and z" is equivalent to "x &gt;= y AND x &lt;=
   372         -z". The expression "x IN (SELECT y ...)" is handled in the same way as the
   373         -expression "x = y" for the purposes of determining the collation sequence
   374         -to use. The collation sequence used for expressions of the form "x IN (y, z
   375         -...)" is the default collation type of x if x is a column, or BINARY
   376         -otherwise.
   377         -</p>  
   378         -
   379         -<p>
   380         -An <a href="lang_select.html">ORDER BY</a> clause that is part of a SELECT
   381         -statement may be assigned a collation sequence to be used for the sort
   382         -operation explicitly. In this case the explicit collation sequence is
   383         -always used.  Otherwise, if the expression sorted by an ORDER BY clause is
   384         -a column, then the default collation type of the column is used to
   385         -determine sort order. If the expression is not a column, then the BINARY
   386         -collation sequence is used.
   387         -</p>  
   388         -
   389         -<h4>7.2 Collation Sequences Example</h4>
   390         -<p>
   391         -The examples below identify the collation sequences that would be used to
   392         -determine the results of text comparisons that may be performed by various
   393         -SQL statements. Note that a text comparison may not be required, and no
   394         -collation sequence used, in the case of numeric, blob or NULL values.
   395         -</p>
   396         -<blockquote>
   397         -<PRE>
   398         -CREATE TABLE t1(
   399         -    a,                 -- default collation type BINARY
   400         -    b COLLATE BINARY,  -- default collation type BINARY
   401         -    c COLLATE REVERSE, -- default collation type REVERSE
   402         -    d COLLATE NOCASE   -- default collation type NOCASE
   403         -);
   404         -
   405         --- Text comparison is performed using the BINARY collation sequence.
   406         -SELECT (a = b) FROM t1;
   407         -
   408         --- Text comparison is performed using the NOCASE collation sequence.
   409         -SELECT (d = a) FROM t1;
   410         -
   411         --- Text comparison is performed using the BINARY collation sequence.
   412         -SELECT (a = d) FROM t1;
   413         -
   414         --- Text comparison is performed using the REVERSE collation sequence.
   415         -SELECT ('abc' = c) FROM t1;
   416         -
   417         --- Text comparison is performed using the REVERSE collation sequence.
   418         -SELECT (c = 'abc') FROM t1;
   419         -
   420         --- Grouping is performed using the NOCASE collation sequence (i.e. values
   421         --- 'abc' and 'ABC' are placed in the same group).
   422         -SELECT count(*) GROUP BY d FROM t1;
   423         -
   424         --- Grouping is performed using the BINARY collation sequence.
   425         -SELECT count(*) GROUP BY (d || '') FROM t1;
   426         -
   427         --- Sorting is performed using the REVERSE collation sequence.
   428         -SELECT * FROM t1 ORDER BY c;
   429         -
   430         --- Sorting is performed using the BINARY collation sequence.
   431         -SELECT * FROM t1 ORDER BY (c || '');
   432         -
   433         --- Sorting is performed using the NOCASE collation sequence.
   434         -SELECT * FROM t1 ORDER BY c COLLATE NOCASE;
   435         -
   436         -</PRE>
   437         -</blockquote>
   438         -
   439         -}
   440         -footer $rcsid

Deleted www/datatypes.tcl.

     1         -#
     2         -# Run this script to generated a datatypes.html output file
     3         -#
     4         -set rcsid {$Id: datatypes.tcl,v 1.8 2004/10/10 17:24:55 drh Exp $}
     5         -source common.tcl
     6         -header {Datatypes In SQLite version 2}
     7         -puts {
     8         -<h2>Datatypes In SQLite Version 2</h2>
     9         -
    10         -<h3>1.0 &nbsp; Typelessness</h3>
    11         -<p>
    12         -SQLite is "typeless".  This means that you can store any
    13         -kind of data you want in any column of any table, regardless of the
    14         -declared datatype of that column.  
    15         -(See the one exception to this rule in section 2.0 below.)
    16         -This behavior is a feature, not
    17         -a bug.  A database is suppose to store and retrieve data and it 
    18         -should not matter to the database what format that data is in.
    19         -The strong typing system found in most other SQL engines and
    20         -codified in the SQL language spec is a misfeature -
    21         -it is an example of the implementation showing through into the
    22         -interface.  SQLite seeks to overcome this misfeature by allowing
    23         -you to store any kind of data into any kind of column and by
    24         -allowing flexibility in the specification of datatypes.
    25         -</p>
    26         -
    27         -<p>
    28         -A datatype to SQLite is any sequence of zero or more names
    29         -optionally followed by a parenthesized lists of one or two
    30         -signed integers.  Notice in particular that a datatype may
    31         -be <em>zero</em> or more names.  That means that an empty
    32         -string is a valid datatype as far as SQLite is concerned.
    33         -So you can declare tables where the datatype of each column
    34         -is left unspecified, like this:
    35         -</p>
    36         -
    37         -<blockquote><pre>
    38         -CREATE TABLE ex1(a,b,c);
    39         -</pre></blockquote>
    40         -
    41         -<p>
    42         -Even though SQLite allows the datatype to be omitted, it is
    43         -still a good idea to include it in your CREATE TABLE statements,
    44         -since the data type often serves as a good hint to other
    45         -programmers about what you intend to put in the column. And
    46         -if you ever port your code to another database engine, that
    47         -other engine will probably require a datatype of some kind.
    48         -SQLite accepts all the usual datatypes.  For example:
    49         -</p>
    50         -
    51         -<blockquote><pre>
    52         -CREATE TABLE ex2(
    53         -  a VARCHAR(10),
    54         -  b NVARCHAR(15),
    55         -  c TEXT,
    56         -  d INTEGER,
    57         -  e FLOAT,
    58         -  f BOOLEAN,
    59         -  g CLOB,
    60         -  h BLOB,
    61         -  i TIMESTAMP,
    62         -  j NUMERIC(10,5)
    63         -  k VARYING CHARACTER (24),
    64         -  l NATIONAL VARYING CHARACTER(16)
    65         -);
    66         -</pre></blockquote>
    67         -
    68         -<p>
    69         -And so forth.  Basically any sequence of names optionally followed by 
    70         -one or two signed integers in parentheses will do.
    71         -</p>
    72         -
    73         -<h3>2.0 &nbsp; The INTEGER PRIMARY KEY</h3>
    74         -
    75         -<p>
    76         -One exception to the typelessness of SQLite is a column whose type
    77         -is INTEGER PRIMARY KEY.  (And you must use "INTEGER" not "INT".
    78         -A column of type INT PRIMARY KEY is typeless just like any other.)
    79         -INTEGER PRIMARY KEY columns must contain a 32-bit signed integer.  Any
    80         -attempt to insert non-integer data will result in an error.
    81         -</p>
    82         -
    83         -<p>
    84         -INTEGER PRIMARY KEY columns can be used to implement the equivalent
    85         -of AUTOINCREMENT.  If you try to insert a NULL into an INTEGER PRIMARY
    86         -KEY column, the column will actually be filled with a integer that is
    87         -one greater than the largest key already in the table.  Or if the
    88         -largest key is 2147483647, then the column will be filled with a
    89         -random integer.  Either way, the INTEGER PRIMARY KEY column will be
    90         -assigned a unique integer.  You can retrieve this integer using
    91         -the <b>sqlite_last_insert_rowid()</b> API function or using the
    92         -<b>last_insert_rowid()</b> SQL function in a subsequent SELECT statement.
    93         -</p>
    94         -
    95         -<h3>3.0 &nbsp; Comparison and Sort Order</h3>
    96         -
    97         -<p>
    98         -SQLite is typeless for the purpose of deciding what data is allowed
    99         -to be stored in a column.  But some notion of type comes into play
   100         -when sorting and comparing data.  For these purposes, a column or
   101         -an expression can be one of two types: <b>numeric</b> and <b>text</b>.
   102         -The sort or comparison may give different results depending on which
   103         -type of data is being sorted or compared.
   104         -</p>
   105         -
   106         -<p>
   107         -If data is of type <b>text</b> then the comparison is determined by
   108         -the standard C data comparison functions <b>memcmp()</b> or
   109         -<b>strcmp()</b>.  The comparison looks at bytes from two inputs one
   110         -by one and returns the first non-zero difference.
   111         -Strings are '\000' terminated so shorter
   112         -strings sort before longer strings, as you would expect.
   113         -</p>
   114         -
   115         -<p>
   116         -For numeric data, this situation is more complex.  If both inputs
   117         -look like well-formed numbers, then they are converted
   118         -into floating point values using <b>atof()</b> and compared numerically.
   119         -If one input is not a well-formed number but the other is, then the
   120         -number is considered to be less than the non-number.  If neither inputs
   121         -is a well-formed number, then <b>strcmp()</b> is used to do the
   122         -comparison.
   123         -</p>
   124         -
   125         -<p>
   126         -Do not be confused by the fact that a column might have a "numeric"
   127         -datatype.  This does not mean that the column can contain only numbers.
   128         -It merely means that if the column does contain a number, that number
   129         -will sort in numerical order.
   130         -</p>
   131         -
   132         -<p>
   133         -For both text and numeric values, NULL sorts before any other value.
   134         -A comparison of any value against NULL using operators like "&lt;" or
   135         -"&gt;=" is always false.
   136         -</p>
   137         -
   138         -<h3>4.0 &nbsp; How SQLite Determines Datatypes</h3>
   139         -
   140         -<p>
   141         -For SQLite version 2.6.3 and earlier, all values used the numeric datatype.
   142         -The text datatype appears in version 2.7.0 and later.  In the sequel it
   143         -is assumed that you are using version 2.7.0 or later of SQLite.
   144         -</p>
   145         -
   146         -<p>
   147         -For an expression, the datatype of the result is often determined by
   148         -the outermost operator.  For example, arithmetic operators ("+", "*", "%")
   149         -always return a numeric results.  The string concatenation operator
   150         -("||") returns a text result.  And so forth.  If you are ever in doubt
   151         -about the datatype of an expression you can use the special <b>typeof()</b>
   152         -SQL function to determine what the datatype is.  For example:
   153         -</p>
   154         -
   155         -<blockquote><pre>
   156         -sqlite&gt; SELECT typeof('abc'+123);
   157         -numeric
   158         -sqlite&gt; SELECT typeof('abc'||123);
   159         -text
   160         -</pre></blockquote>
   161         -
   162         -<p>
   163         -For table columns, the datatype is determined by the type declaration
   164         -of the CREATE TABLE statement.  The datatype is text if and only if
   165         -the type declaration contains one or more of the following strings:
   166         -</p>
   167         -
   168         -<blockquote>
   169         -BLOB<br>
   170         -CHAR<br>
   171         -CLOB</br>
   172         -TEXT
   173         -</blockquote>
   174         -
   175         -<p>
   176         -The search for these strings in the type declaration is case insensitive,
   177         -of course.  If any of the above strings occur anywhere in the type
   178         -declaration, then the datatype of the column is text.  Notice that
   179         -the type "VARCHAR" contains "CHAR" as a substring so it is considered
   180         -text.</p>
   181         -
   182         -<p>If none of the strings above occur anywhere in the type declaration,
   183         -then the datatype is numeric.  Note in particular that the datatype for columns
   184         -with an empty type declaration is numeric.
   185         -</p>
   186         -
   187         -<h3>5.0 &nbsp; Examples</h3>
   188         -
   189         -<p>
   190         -Consider the following two command sequences:
   191         -</p>
   192         -
   193         -<blockquote><pre>
   194         -CREATE TABLE t1(a INTEGER UNIQUE);        CREATE TABLE t2(b TEXT UNIQUE);
   195         -INSERT INTO t1 VALUES('0');               INSERT INTO t2 VALUES(0);
   196         -INSERT INTO t1 VALUES('0.0');             INSERT INTO t2 VALUES(0.0);
   197         -</pre></blockquote>
   198         -
   199         -<p>In the sequence on the left, the second insert will fail.  In this case,
   200         -the strings '0' and '0.0' are treated as numbers since they are being 
   201         -inserted into a numeric column but 0==0.0 which violates the uniqueness
   202         -constraint.  However, the second insert in the right-hand sequence works.  In
   203         -this case, the constants 0 and 0.0 are treated a strings which means that
   204         -they are distinct.</p>
   205         -
   206         -<p>SQLite always converts numbers into double-precision (64-bit) floats
   207         -for comparison purposes.  This means that a long sequence of digits that
   208         -differ only in insignificant digits will compare equal if they
   209         -are in a numeric column but will compare unequal if they are in a text
   210         -column.  We have:</p>
   211         -
   212         -<blockquote><pre>
   213         -INSERT INTO t1                            INSERT INTO t2
   214         -   VALUES('12345678901234567890');           VALUES(12345678901234567890);
   215         -INSERT INTO t1                            INSERT INTO t2
   216         -   VALUES('12345678901234567891');           VALUES(12345678901234567891);
   217         -</pre></blockquote>
   218         -
   219         -<p>As before, the second insert on the left will fail because the comparison
   220         -will convert both strings into floating-point number first and the only
   221         -difference in the strings is in the 20-th digit which exceeds the resolution
   222         -of a 64-bit float.  In contrast, the second insert on the right will work
   223         -because in that case, the numbers being inserted are strings and are
   224         -compared using memcmp().</p>
   225         -
   226         -<p>
   227         -Numeric and text types make a difference for the DISTINCT keyword too:
   228         -</p>
   229         -
   230         -<blockquote><pre>
   231         -CREATE TABLE t3(a INTEGER);               CREATE TABLE t4(b TEXT);
   232         -INSERT INTO t3 VALUES('0');               INSERT INTO t4 VALUES(0);
   233         -INSERT INTO t3 VALUES('0.0');             INSERT INTO t4 VALUES(0.0);
   234         -SELECT DISTINCT * FROM t3;                SELECT DISTINCT * FROM t4;
   235         -</pre></blockquote>
   236         -
   237         -<p>
   238         -The SELECT statement on the left returns a single row since '0' and '0.0'
   239         -are treated as numbers and are therefore indistinct.  But the SELECT 
   240         -statement on the right returns two rows since 0 and 0.0 are treated
   241         -a strings which are different.</p>
   242         -}
   243         -footer $rcsid

Deleted www/different.tcl.

     1         -set rcsid {$Id: different.tcl,v 1.8 2006/12/18 14:12:21 drh Exp $}
     2         -source common.tcl
     3         -header {Distinctive Features Of SQLite}