Documentation Source Text

Check-in [275febef8f]
Login

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

Overview
Comment:Complete reorganization of the documentation sources.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 275febef8faf17827a432ef6e1ed1d0154c29da0
User & Date: drh 2007-11-12 15:32:09
Context
2007-11-12
20:38
Generate C interface reference document both as the single big file and also as lots of individual small files. check-in: ae0c38c662 user: drh tags: trunk
15:32
Complete reorganization of the documentation sources. check-in: 275febef8f user: drh tags: trunk
03:45
Initial check-in of documentation sources. check-in: 6dc1e6a1f3 user: drh tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Deleted 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 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 arch.gif.

cannot compute difference between binary files

Deleted arch.png.

cannot compute difference between binary files

Deleted 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 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 arch2.gif.

cannot compute difference between binary files

Deleted 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

Added art/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

Added art/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

Added art/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 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 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 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 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 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 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 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 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 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 copyright-release.pdf.

cannot compute difference between binary files

Deleted 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 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 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 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}
     4         -puts {
     5         -<p>
     6         -This page highlights some of the characteristics of SQLite that are
     7         -unusual and which make SQLite different from many other SQL
     8         -database engines.
     9         -</p>
    10         -}
    11         -proc feature {tag name text} {
    12         -  puts "<a name=\"$tag\" />"
    13         -  puts "<p><b>$name</b></p>\n"
    14         -  puts "<blockquote>$text</blockquote>\n"
    15         -}
    16         -
    17         -feature zeroconfig {Zero-Configuration} {
    18         -  SQLite does not need to be "installed" before it is used. 
    19         -  There is no "setup" procedure.  There is no
    20         -  server process that needs to be started, stopped, or configured.
    21         -  There is
    22         -  no need for an administrator to create a new database instance or assign
    23         -  access permissions to users.
    24         -  SQLite uses no configuration files.
    25         -  Nothing needs to be done to tell the system that SQLite is running.
    26         -  No actions are required to recover after a system crash or power failure.
    27         -  There is nothing to troubleshoot.
    28         -  <p>
    29         -  SQLite just works.
    30         -  <p>
    31         -  Other more familiar database engines run great once you get them going.
    32         -  But doing the initial installation and configuration can be
    33         -  intimidatingly complex.
    34         -}
    35         -
    36         -feature serverless {Serverless} {
    37         -  Most SQL database engines are implemented as a separate server
    38         -  process.  Programs that want to access the database communicate
    39         -  with the server using some kind of interprocess communcation
    40         -  (typically TCP/IP) to send requests to the server and to receive
    41         -  back results.  SQLite does not work this way.  With SQLite, the
    42         -  process that wants to access the database reads and writes
    43         -  directly from the database files on disk.  There is no intermediary
    44         -  server process.
    45         -  <p>
    46         -  There are advantages and disadvantages to being serverless.  The
    47         -  main advantage is that there is no separate server process
    48         -  to install, setup, configure, initialize, manage, and troubleshoot.
    49         -  This is one reason why SQLite is a "zero-configuration" database
    50         -  engine.  Programs that use SQLite require no administrative support
    51         -  for setting up the database engine before they are run.  Any program
    52         -  that is able to access the disk is able to use an SQLite database.
    53         -  <p>
    54         -  On the other hand, a database engine that uses a server can provide
    55         -  better protection from bugs in the client application - stray pointers
    56         -  in a client cannot corrupt memory on the server.  And because a server
    57         -  is a single persistent process, it is able control database access with
    58         -  more precision, allowing for finer grain locking and better concurrancy.
    59         -  <p>
    60         -  Most SQL database engines are client/server based.  Of those that are
    61         -  serverless, SQLite is the only one that this author knows of that
    62         -  allows multiple applications to access the same database at the same time.
    63         -}
    64         -
    65         -feature onefile {Single Database File} {
    66         -  An SQLite database is a single ordinary disk file that can be located
    67         -  anywhere in the directory hierarchy.  If SQLite can read
    68         -  the disk file then it can read anything in the database.  If the disk
    69         -  file and its directory are writable, then SQLite can change anything
    70         -  in the database.   Database files can easily be copied onto a USB
    71         -  memory stick or emailed for sharing.
    72         -  <p>
    73         -  Other SQL database engines tend to store data as a large collection of
    74         -  files.  Often these files are in a standard location that only the
    75         -  database engine itself can access.  This makes the data more secure,
    76         -  but also makes it harder to access.  Some SQL database engines provide
    77         -  the option of writing directly to disk and bypassing the filesystem
    78         -  all together.  This provides added performance, but at the cost of
    79         -  considerable setup and maintenance complexity.
    80         -}
    81         -
    82         -feature small {Compact} {
    83         -  When optimized for size, the whole SQLite library with everything enabled
    84         -  is less than 225KiB in size (as measured on an ix86 using the "size"
    85         -  utility from the GNU compiler suite.)  Unneeded features can be disabled
    86         -  at compile-time to further reduce the size of the library to under
    87         -  170KiB if desired.
    88         -  <p>
    89         -  Most other SQL database engines are much larger than this.  IBM boasts
    90         -  that it's recently released CloudScape database engine is "only" a 2MiB
    91         -  jar file - 10 times larger than SQLite even after it is compressed!
    92         -  Firebird boasts that it's client-side library is only 350KiB.  That's
    93         -  50% larger than SQLite and does not even contain the database engine.
    94         -  The Berkeley DB library from Sleepycat is 450KiB and it omits SQL
    95         -  support, providing the programmer with only simple key/value pairs.
    96         -}
    97         -
    98         -feature typing {Manifest typing} {
    99         -  Most SQL database engines use static typing.  A datatype is associated
   100         -  with each column in a table and only values of that particular datatype
   101         -  are allowed to be stored in that column.  SQLite relaxes this restriction
   102         -  by using manifest typing.
   103         -  In manifest typing, the datatype is a property of the value itself, not 
   104         -  of the column in which the value is stored.
   105         -  SQLite thus allows the user to store
   106         -  any value of any datatype into any column regardless of the declared type
   107         -  of that column.  (There are some exceptions to this rule: An INTEGER
   108         -  PRIMARY KEY column may only store integers.  And SQLite attempts to coerce
   109         -  values into the declared datatype of the column when it can.)
   110         -  <p>
   111         -  As far as we can tell, the SQL language specification allows the use
   112         -  of manifest typing.   Nevertheless, most other SQL database engines are
   113         -  statically typed and so some people
   114         -  feel that the use of manifest typing is a bug in SQLite.  But the authors
   115         -  of SQLite feel very strongly that this is a feature.  The use of manifest
   116         -  typing in SQLite is a deliberate design decision which has proven in practice
   117         -  to make SQLite more reliable and easier to use, especially when used in
   118         -  combination with dynamically typed programming languages such as Tcl and
   119         -  Python.
   120         -}
   121         -
   122         -feature flex {Variable-length records} {
   123         -  Most other SQL database engines allocated a fixed amount of disk space
   124         -  for each row in most tables.  They play special tricks for handling
   125         -  BLOBs and CLOBs which can be of wildly varying length.  But for most
   126         -  tables, if you declare a column to be a VARCHAR(100) then the database
   127         -  engine will allocate
   128         -  100 bytes of disk space regardless of how much information you actually
   129         -  store in that column.
   130         -  <p>
   131         -  SQLite, in contrast, use only the amount of disk space actually
   132         -  needed to store the information in a row.  If you store a single
   133         -  character in a VARCHAR(100) column, then only a single byte of disk
   134         -  space is consumed.  (Actually two bytes - there is some overhead at
   135         -  the beginning of each column to record its datatype and length.)
   136         -  <p>
   137         -  The use of variable-length records by SQLite has a number of advantages.
   138         -  It results in smaller database files, obviously.  It also makes the
   139         -  database run faster, since there is less information to move to and from
   140         -  disk.  And, the use of variable-length records makes it possible for
   141         -  SQLite to employ manifest typing instead of static typing.
   142         -}
   143         -
   144         -feature readable {Readable source code} {
   145         -  The source code to SQLite is designed to be readable and accessible to
   146         -  the average programmer.  All procedures and data structures and many
   147         -  automatic variables are carefully commented with useful information about
   148         -  what they do.  Boilerplate commenting is omitted.
   149         -}
   150         -
   151         -feature vdbe {SQL statements compile into virtual machine code} {
   152         -  Every SQL database engine compiles each SQL statement into some kind of
   153         -  internal data structure which is then used to carry out the work of the
   154         -  statement.  But in most SQL engines that internal data structure is a
   155         -  complex web of interlinked structures and objects.  In SQLite, the compiled
   156         -  form of statements is a short program in a machine-language like
   157         -  representation.  Users of the database can view this 
   158         -  <a href="opcode.html">virtual machine language</a>
   159         -  by prepending the <a href="lang_explain.html">EXPLAIN</a> keyword
   160         -  to a query.
   161         -  <p>
   162         -  The use of a virtual machine in SQLite has been a great benefit to
   163         -  library's development.  The virtual machine provides a crisp, well-defined
   164         -  junction between the front-end of SQLite (the part that parses SQL
   165         -  statements and generates virtual machine code) and the back-end (the
   166         -  part that executes the virtual machine code and computes a result.)
   167         -  The virtual machine allows the developers to see clearly and in an
   168         -  easily readable form what SQLite is trying to do with each statement
   169         -  it compiles, which is a tremendous help in debugging.
   170         -  Depending on how it is compiled, SQLite also has the capability of
   171         -  tracing the execution of the virtual machine - printing each
   172         -  virtual machine instruction and its result as it executes.
   173         -}
   174         -
   175         -#feature binding {Tight bindings to dynamic languages} {
   176         -#  Because it is embedded, SQLite can have a much tighter and more natural
   177         -#  binding to high-level dynamic languages such as Tcl, Perl, Python,
   178         -#  PHP, and Ruby.
   179         -#  For example, 
   180         -#}
   181         -
   182         -feature license {Public domain} {
   183         -  The source code for SQLite is in the public domain.  No claim of copyright
   184         -  is made on any part of the core source code.  (The documentation and test
   185         -  code is a different matter - some sections of documentation and test logic
   186         -  are governed by open-sources licenses.)  All contributors to the
   187         -  SQLite core software have signed affidavits specifically disavowing any
   188         -  copyright interest in the code.  This means that anybody is able to legally
   189         -  do anything they want with the SQLite source code.
   190         -  <p>
   191         -  There are other SQL database engines with liberal licenses that allow
   192         -  the code to be broadly and freely used.  But those other engines are
   193         -  still governed by copyright law.  SQLite is different in that copyright
   194         -  law simply does not apply.  
   195         -  <p>
   196         -  The source code files for other SQL database engines typically begin
   197         -  with a comment describing your license rights to view and copy that file.
   198         -  The SQLite source code contains no license since it is not governed by
   199         -  copyright.  Instead of a license, the SQLite source code offers a blessing:
   200         -  <blockquote>
   201         -  <i>May you do good and not evil<br>
   202         -  May you find forgiveness for yourself and forgive others<br>
   203         -  May you share freely, never taking more than you give.</i>
   204         -  </blockquote>
   205         -}
   206         -
   207         -feature extensions {SQL language extensions} {
   208         -  SQLite provides a number of enhancements to the SQL language 
   209         -  not normally found in other database engines.
   210         -  The EXPLAIN keyword and manifest typing have already been mentioned
   211         -  above.  SQLite also provides statements such as 
   212         -  <a href="lang_replace.html">REPLACE</a> and the
   213         -  <a href="lang_conflict.html">ON CONFLICT</a> clause that allow for
   214         -  added control over the resolution of constraint conflicts.
   215         -  SQLite supports <a href="lang_attach.html">ATTACH</a> and
   216         -  <a href="lang_detach.html">DETACH</a> commands that allow multiple
   217         -  independent databases to be used together in the same query.
   218         -  And SQLite defines APIs that allows the user to add new
   219         -  <a href="capi3ref.html#sqlite3_create_function">SQL functions</a>
   220         -  and <a href="capi3ref.html#sqlite3_create_collation">collating sequences</a>.
   221         -}
   222         -
   223         -
   224         -footer $rcsid

Deleted direct1b.gif.

cannot compute difference between binary files

Deleted docs.tcl.

     1         -# This script generates the "docs.html" page that describes various
     2         -# sources of documentation available for SQLite.
     3         -#
     4         -set rcsid {$Id: docs.tcl,v 1.15 2007/10/04 00:29:29 drh Exp $}
     5         -source common.tcl
     6         -header {SQLite Documentation}
     7         -puts {
     8         -<h2>Available Documentation</h2>
     9         -<table width="100%" cellpadding="5">
    10         -}
    11         -
    12         -proc doc {name url desc} {
    13         -  puts {<tr><td valign="top" align="right">}
    14         -  regsub -all { +} $name {\&nbsp;} name
    15         -  puts "<a href=\"$url\">$name</a></td>"
    16         -  puts {<td width="10"></td>}
    17         -  puts {<td valign="top" align="left">}
    18         -  puts $desc
    19         -  puts {</td></tr>}
    20         -}
    21         -
    22         -doc {Appropriate Uses For SQLite} {whentouse.html} {
    23         -  This document describes situations where SQLite is an approriate
    24         -  database engine to use versus situations where a client/server
    25         -  database engine might be a better choice.
    26         -}
    27         -
    28         -doc {Distinctive Features} {different.html} {
    29         -  This document enumerates and describes some of the features of
    30         -  SQLite that make it different from other SQL database engines.
    31         -}
    32         -
    33         -doc {SQLite In 5 Minutes Or Less} {quickstart.html} {
    34         -  A very quick introduction to programming with SQLite.
    35         -}
    36         -
    37         -doc {SQL Syntax} {lang.html} {
    38         -  This document describes the SQL language that is understood by
    39         -  SQLite.  
    40         -}
    41         -doc {Version 3 C/C++ API<br>Reference} {capi3ref.html} {
    42         -  This document describes each API function separately.
    43         -}
    44         -doc {Sharing Cache Mode} {sharedcache.html} {
    45         -  Version 3.3.0 and later supports the ability for two or more
    46         -  database connections to share the same page and schema cache.
    47         -  This feature is useful for certain specialized applications.
    48         -}
    49         -doc {Tcl API} {tclsqlite.html} {
    50         -  A description of the TCL interface bindings for SQLite.
    51         -}
    52         -
    53         -doc {How SQLite Implements Atomic Commit} {ac/atomiccommit.html} {
    54         -  A description of the logic within SQLite that implements
    55         -  transactions with atomic commit, even in the face of power
    56         -  failures.
    57         -}
    58         -doc {Moving From SQLite 3.4 to 3.5} {34to35.html} {
    59         -  A document describing the differences between SQLite version 3.4.2
    60         -  and 3.5.0.
    61         -}
    62         -
    63         -doc {Pragma commands} {pragma.html} {
    64         -  This document describes SQLite performance tuning options and other 
    65         -  special purpose database commands.
    66         -}
    67         -doc {SQLite Version 3} {version3.html} {
    68         -  A summary of of the changes between SQLite version 2.8 and SQLite version 3.0.
    69         -}
    70         -doc {Version 3 C/C++ API} {capi3.html} {
    71         -  A description of the C/C++ interface bindings for SQLite version 3.0.0
    72         -  and following.
    73         -}
    74         -doc {Version 3 DataTypes } {datatype3.html} {
    75         -  SQLite version 3 introduces the concept of manifest typing, where the
    76         -  type of a value is associated with the value itself, not the column that
    77         -  it is stored in.
    78         -  This page describes data typing for SQLite version 3 in further detail.
    79         -}
    80         -
    81         -doc {Locking And Concurrency<br>In SQLite Version 3} {lockingv3.html} {
    82         -  A description of how the new locking code in version 3 increases
    83         -  concurrancy and decreases the problem of writer starvation.
    84         -}
    85         -
    86         -doc {Overview Of The Optimizer} {optoverview.html} {
    87         -  A quick overview of the various query optimizations that are
    88         -  attempted by the SQLite code generator.
    89         -}
    90         -
    91         -
    92         -doc {Null Handling} {nulls.html} {
    93         -  Different SQL database engines handle NULLs in different ways.  The
    94         -  SQL standards are ambiguous.  This document describes how SQLite handles
    95         -  NULLs in comparison with other SQL database engines.
    96         -}
    97         -
    98         -doc {Copyright} {copyright.html} {
    99         -  SQLite is in the public domain.  This document describes what that means
   100         -  and the implications for contributors.
   101         -}
   102         -
   103         -doc {Unsupported SQL} {omitted.html} {
   104         -  This page describes features of SQL that SQLite does not support.
   105         -}
   106         -
   107         -doc {Version 2 C/C++ API} {c_interface.html} {
   108         -  A description of the C/C++ interface bindings for SQLite through version 
   109         -  2.8
   110         -}
   111         -
   112         -
   113         -doc {Version 2 DataTypes } {datatypes.html} {
   114         -  A description of how SQLite version 2 handles SQL datatypes.
   115         -  Short summary:  Everything is a string.
   116         -}
   117         -
   118         -doc {Release History} {changes.html} {
   119         -  A chronology of SQLite releases going back to version 1.0.0
   120         -}
   121         -
   122         -
   123         -doc {Speed Comparison} {speed.html} {
   124         -  The speed of version 2.7.6 of SQLite is compared against PostgreSQL and
   125         -  MySQL.
   126         -}
   127         -
   128         -doc {Architecture} {arch.html} {
   129         -  An architectural overview of the SQLite library, useful for those who want
   130         -  to hack the code.
   131         -}
   132         -
   133         -doc {VDBE Tutorial} {vdbe.html} {
   134         -  The VDBE is the subsystem within SQLite that does the actual work of
   135         -  executing SQL statements.  This page describes the principles of operation
   136         -  for the VDBE in SQLite version 2.7.  This is essential reading for anyone
   137         -  who want to modify the SQLite sources.
   138         -}
   139         -
   140         -doc {VDBE Opcodes} {opcode.html} {
   141         -  This document is an automatically generated description of the various
   142         -  opcodes that the VDBE understands.  Programmers can use this document as
   143         -  a reference to better understand the output of EXPLAIN listings from
   144         -  SQLite.
   145         -}
   146         -
   147         -doc {Compilation Options} {compile.html} {
   148         -  This document describes the compile time options that may be set to 
   149         -  modify the default behaviour of the library or omit optional features
   150         -  in order to reduce binary size.
   151         -}
   152         -
   153         -doc {Backwards Compatibility} {formatchng.html} {
   154         -  This document details all of the incompatible changes to the SQLite
   155         -  file format that have occurred since version 1.0.0.
   156         -}
   157         -
   158         -puts {</table>}
   159         -footer $rcsid

Deleted download.tcl.

     1         -#
     2         -# Run this TCL script to generate HTML for the download.html file.
     3         -#
     4         -set rcsid {$Id: download.tcl,v 1.27 2007/05/08 18:30:36 drh Exp $}
     5         -source common.tcl
     6         -header {SQLite Download Page}
     7         -
     8         -puts {
     9         -<h2>SQLite Download Page</h1>
    10         -<table width="100%" cellpadding="5">
    11         -}
    12         -
    13         -proc Product {pattern desc} {
    14         -  regsub {V[23]} $pattern {*} p3
    15         -  regsub V2 $pattern {(2[0-9a-z._]+)} pattern
    16         -  regsub V3 $pattern {(3[0-9a-z._]+)} pattern
    17         -  set p2 [string map {* .*} $pattern]
    18         -  set flist [glob -nocomplain $p3]
    19         -  foreach file [lsort -dict $flist] {
    20         -    if {![regexp ^$p2\$ $file all version]} continue
    21         -    regsub -all _ $version . version
    22         -    set size [file size $file]
    23         -    set units bytes
    24         -    if {$size>1024*1024} {
    25         -      set size [format %.2f [expr {$size/(1024.0*1024.0)}]]
    26         -      set units MiB
    27         -    } elseif {$size>1024} {
    28         -      set size [format %.2f [expr {$size/(1024.0)}]]
    29         -      set units KiB
    30         -    }
    31         -    puts "<tr><td width=\"10\"></td>"
    32         -    puts "<td valign=\"top\" align=\"right\">"
    33         -    puts "<a href=\"$file\">$file</a><br>($size $units)</td>"
    34         -    puts "<td width=\"5\"></td>"
    35         -    regsub -all VERSION $desc $version d2
    36         -    puts "<td valign=\"top\">[string trim $d2]</td></tr>"
    37         -  }
    38         -}
    39         -cd doc
    40         -
    41         -proc Heading {title} {
    42         -  puts "<tr><td colspan=4><big><b>$title</b></big></td></tr>"
    43         -}
    44         -
    45         -Heading {Precompiled Binaries for Linux}
    46         -
    47         -Product sqlite3-V3.bin.gz {
    48         -  A command-line program for accessing and modifying
    49         -  SQLite version 3.* databases.
    50         -  See <a href="sqlite.html">the documentation</a> for additional information.
    51         -}
    52         -
    53         -Product sqlite-V3.bin.gz {
    54         -  A command-line program for accessing and modifying
    55         -  SQLite databases.
    56         -  See <a href="sqlite.html">the documentation</a> for additional information.
    57         -}
    58         -
    59         -Product tclsqlite-V3.so.gz {
    60         -  Bindings for <a href="http://www.tcl.tk/">Tcl/Tk</a>.
    61         -  You can import this shared library into either
    62         -  tclsh or wish to get SQLite database access from Tcl/Tk.
    63         -  See <a href="tclsqlite.html">the documentation</a> for details.
    64         -}
    65         -
    66         -Product sqlite-V3.so.gz {
    67         -  A precompiled shared-library for Linux without the TCL bindings.
    68         -}
    69         -
    70         -Product fts1-V3.so.gz {
    71         -  A precompiled 
    72         -  <a href="http://www.sqlite.org/cvstrac/wiki?p=FtsOne">FTS1 Module</a> 
    73         -  for Linux.
    74         -}
    75         -
    76         -Product fts2-V3.so.gz {
    77         -  A precompiled 
    78         -  <a href="http://www.sqlite.org/cvstrac/wiki?p=FtsTwo">FTS2 Module</a> 
    79         -  for Linux.
    80         -}
    81         -
    82         -Product sqlite-devel-V3.i386.rpm {
    83         -  RPM containing documentation, header files, and static library for
    84         -  SQLite version VERSION.
    85         -}
    86         -Product sqlite-V3-1.i386.rpm {
    87         -  RPM containing shared libraries and the <b>sqlite</b> command-line
    88         -  program for SQLite version VERSION.
    89         -}
    90         -
    91         -Product sqlite*_analyzer-V3.bin.gz {
    92         -  An analysis program for database files compatible with SQLite 
    93         -  version VERSION and later.
    94         -}
    95         -
    96         -Heading {Precompiled Binaries For Windows}
    97         -
    98         -Product sqlite-V3.zip {
    99         -  A command-line program for accessing and modifing SQLite databases.
   100         -  See <a href="sqlite.html">the documentation</a> for additional information.
   101         -}
   102         -Product tclsqlite-V3.zip {
   103         -  Bindings for <a href="http://www.tcl.tk/">Tcl/Tk</a>.
   104         -  You can import this shared library into either
   105         -  tclsh or wish to get SQLite database access from Tcl/Tk.
   106         -  See <a href="tclsqlite.html">the documentation</a> for details.
   107         -}
   108         -Product sqlitedll-V3.zip {
   109         -  This is a DLL of the SQLite library without the TCL bindings.
   110         -  The only external dependency is MSVCRT.DLL.
   111         -}
   112         -
   113         -Product fts1dll-V3.zip {
   114         -  A precompiled 
   115         -  <a href="http://www.sqlite.org/cvstrac/wiki?p=FtsOne">FTS1 Module</a> 
   116         -  for win32.
   117         -}
   118         -
   119         -Product fts2dll-V3.zip {
   120         -  A precompiled 
   121         -  <a href="http://www.sqlite.org/cvstrac/wiki?p=FtsTwo">FTS2 Module</a> 
   122         -  for win32.
   123         -}
   124         -
   125         -Product sqlite*_analyzer-V3.zip {
   126         -  An analysis program for database files compatible with SQLite version
   127         -  VERSION and later.
   128         -}
   129         -
   130         -
   131         -Heading {Source Code}
   132         -
   133         -Product {sqlite-V3.tar.gz} {
   134         -  A tarball of the complete source tree for SQLite version VERSION
   135         -  including all of the documentation.
   136         -}
   137         -
   138         -Product {sqlite-source-V3.zip} {
   139         -  This ZIP archive contains preprocessed C code for the SQLite library as
   140         -  individual source files.
   141         -  Unlike the tarballs below, all of the preprocessing and automatic
   142         -  code generation has already been done on these C code files, so they
   143         -  can be converted to object code directly with any ordinary C compiler.
   144         -}
   145         -
   146         -Product {sqlite-amalgamation-V3.zip} {
   147         -  This ZIP archive contains all preprocessed C code combined into a
   148         -  single source file (the
   149         -  <a href="http://www.sqlite.org/cvstrac/wiki?p=TheAmalgamation">
   150         -  amalgamation</a>).
   151         -}
   152         -
   153         -Product {sqlite-V3-tea.tar.gz} {
   154         -  A tarball of proprocessed source code together with a
   155         -  <a href="http://www.tcl.tk/doc/tea/">Tcl Extension Architecture (TEA)</a>
   156         -  compatible configure script and makefile.
   157         -}
   158         -
   159         -Product {sqlite-V3.src.rpm} {
   160         -  An RPM containing complete source code for SQLite version VERSION
   161         -}
   162         -
   163         -Heading {Cross-Platform Binaries}
   164         -
   165         -Product {sqlite-V3.kit} {
   166         -  A <a href="http://www.equi4.com/starkit.html">starkit</a> containing
   167         -  precompiled SQLite binaries and Tcl bindings for Linux-x86, Windows,
   168         -  and Mac OS-X ppc and x86.
   169         -}
   170         -
   171         -Heading {Historical Binaries And Source Code}
   172         -
   173         -Product sqlite-V2.bin.gz {
   174         -  A command-line program for accessing and modifying
   175         -  SQLite version 2.* databases on Linux-x86.
   176         -}
   177         -Product sqlite-V2.zip {
   178         -  A command-line program for accessing and modifying 
   179         -  SQLite version 2.* databases on win32.
   180         -}
   181         -
   182         -Product sqlite*_analyzer-V2.bin.gz {
   183         -  An analysis program for version 2.* database files on Linux-x86
   184         -}
   185         -Product sqlite*_analyzer-V2.zip {
   186         -  An analysis program for version 2.* database files on win32.
   187         -}
   188         -Product {sqlite-source-V2.zip} {
   189         -  This ZIP archive contains C source code for the SQLite library
   190         -  version VERSION.
   191         -}
   192         -
   193         -
   194         -
   195         -
   196         -puts {
   197         -</table>
   198         -
   199         -<a name="cvs">
   200         -<h3>Direct Access To The Sources Via Anonymous CVS</h3>
   201         -
   202         -<p>
   203         -All SQLite source code is maintained in a 
   204         -<a href="http://www.cvshome.org/">CVS</a> repository that is
   205         -available for read-only access by anyone.  You can 
   206         -interactively view the
   207         -repository contents and download individual files
   208         -by visiting
   209         -<a href="http://www.sqlite.org/cvstrac/dir?d=sqlite">
   210         -http://www.sqlite.org/cvstrac/dir?d=sqlite</a>.
   211         -To access the repository directly, use the following
   212         -commands:
   213         -</p>
   214         -
   215         -<blockquote><pre>
   216         -cvs -d :pserver:anonymous@www.sqlite.org:/sqlite login
   217         -cvs -d :pserver:anonymous@www.sqlite.org:/sqlite checkout sqlite
   218         -</pre></blockquote>
   219         -
   220         -<p>
   221         -When the first command prompts you for a password, enter "anonymous".
   222         -</p>
   223         -
   224         -<p>
   225         -To access the SQLite version 2.8 sources, begin by getting the 3.0
   226         -tree as described above.  Then update to the "version_2" branch
   227         -as follows:
   228         -</p>
   229         -
   230         -<blockquote><pre>
   231         -cvs update -r version_2
   232         -</pre></blockquote>
   233         -
   234         -}
   235         -
   236         -footer $rcsid

Deleted dynload.tcl.

     1         -#
     2         -# Run this Tcl script to generate the dynload.html file.
     3         -#
     4         -set rcsid {$Id: dynload.tcl,v 1.1 2001/02/11 16:58:22 drh Exp $}
     5         -
     6         -puts {<html>
     7         -<head>
     8         -  <title>How to build a dynamically loaded Tcl extension for SQLite</title>
     9         -</head>
    10         -<body bgcolor=white>
    11         -<h1 align=center>
    12         -How To Build A Dynamically Loaded Tcl Extension
    13         -</h1>}
    14         -puts {<p>
    15         -<i>This note was contributed by 
    16         -<a href="bsaunder@tampabay.rr.com.nospam">Bill Saunders</a>.  Thanks, Bill!</i>
    17         -
    18         -<p>
    19         -To compile the SQLite Tcl extension into a dynamically loaded module 
    20         -I did the following:
    21         -</p>
    22         -
    23         -<ol>
    24         -<li><p>Do a standard compile
    25         -(I had a dir called bld at the same level as sqlite  ie
    26         -        /root/bld
    27         -        /root/sqlite
    28         -I followed the directions and did a standard build in the bld
    29         -directory)</p></li>
    30         -
    31         -<li><p>
    32         -Now do the following in the bld directory
    33         -<blockquote><pre>
    34         -gcc -shared -I. -lgdbm ../sqlite/src/tclsqlite.c libsqlite.a -o sqlite.so
    35         -</pre></blockquote></p></li>
    36         -
    37         -<li><p>
    38         -This should produce the file sqlite.so in the bld directory</p></li>
    39         -
    40         -<li><p>
    41         -Create a pkgIndex.tcl file that contains this line
    42         -
    43         -<blockquote><pre>
    44         -package ifneeded sqlite 1.0 [list load [file join $dir sqlite.so]]
    45         -</pre></blockquote></p></li>
    46         -
    47         -<li><p>
    48         -To use this put sqlite.so and pkgIndex.tcl in the same directory</p></li>
    49         -
    50         -<li><p>
    51         -From that directory start wish</p></li>
    52         -
    53         -<li><p>
    54         -Execute the following tcl command (tells tcl where to fine loadable
    55         -modules)
    56         -<blockquote><pre>
    57         -lappend auto_path [exec pwd]
    58         -</pre></blockquote></p></li>
    59         -
    60         -<li><p>
    61         -Load the package 
    62         -<blockquote><pre>
    63         -package require sqlite
    64         -</pre></blockquote></p></li>
    65         -
    66         -<li><p>
    67         -Have fun....</p></li>
    68         -</ul>
    69         -
    70         -</body></html>}

Deleted faq.tcl.

     1         -#
     2         -# Run this script to generated a faq.html output file
     3         -#
     4         -set rcsid {$Id: faq.tcl,v 1.40 2007/09/04 01:58:27 drh Exp $}
     5         -source common.tcl
     6         -header {SQLite Frequently Asked Questions</title>}
     7         -
     8         -set cnt 1
     9         -proc faq {question answer} {
    10         -  set ::faq($::cnt) [list [string trim $question] [string trim $answer]]
    11         -  incr ::cnt
    12         -}
    13         -
    14         -#############
    15         -# Enter questions and answers here.
    16         -
    17         -faq {
    18         -  How do I create an AUTOINCREMENT field.
    19         -} {
    20         -  <p>Short answer: A column declared INTEGER PRIMARY KEY will
    21         -  autoincrement.</p>
    22         -
    23         -  <p>Here is the long answer:
    24         -  If you declare a column of a table to be INTEGER PRIMARY KEY, then
    25         -  whenever you insert a NULL
    26         -  into that column of the table, the NULL is automatically converted
    27         -  into an integer which is one greater than the largest value of that
    28         -  column over all other rows in the table, or 1 if the table is empty.
    29         -  (If the largest possible integer key, 9223372036854775807, then an
    30         -  unused key value is chosen at random.)
    31         -  For example, suppose you have a table like this:
    32         -<blockquote><pre>
    33         -CREATE TABLE t1(
    34         -  a INTEGER PRIMARY KEY,
    35         -  b INTEGER
    36         -);
    37         -</pre></blockquote>
    38         -  <p>With this table, the statement</p>
    39         -<blockquote><pre>
    40         -INSERT INTO t1 VALUES(NULL,123);
    41         -</pre></blockquote>
    42         -  <p>is logically equivalent to saying:</p>
    43         -<blockquote><pre>
    44         -INSERT INTO t1 VALUES((SELECT max(a) FROM t1)+1,123);
    45         -</pre></blockquote>
    46         -
    47         -  <p>There is a new API function named
    48         -  <a href="capi3ref.html#sqlite3_last_insert_rowid">
    49         -  sqlite3_last_insert_rowid()</a> which will return the integer key
    50         -  for the most recent insert operation.</p>
    51         -
    52         -  <p>Note that the integer key is one greater than the largest
    53         -  key that was in the table just prior to the insert.  The new key
    54         -  will be unique over all keys currently in the table, but it might
    55         -  overlap with keys that have been previously deleted from the
    56         -  table.  To create keys that are unique over the lifetime of the
    57         -  table, add the AUTOINCREMENT keyword to the INTEGER PRIMARY KEY
    58         -  declaration.  Then the key chosen will be one more than than the
    59         -  largest key that has ever existed in that table.  If the largest
    60         -  possible key has previously existed in that table, then the INSERT
    61         -  will fail with an SQLITE_FULL error code.</p>
    62         -}
    63         -
    64         -faq {
    65         -  What datatypes does SQLite support?
    66         -} {
    67         -  <p>See <a href="datatype3.html">http://www.sqlite.org/datatype3.html</a>.</p>
    68         -}
    69         -
    70         -faq {
    71         -  SQLite lets me insert a string into a database column of type integer!
    72         -} {
    73         -  <p>This is a feature, not a bug.  SQLite does not enforce data type
    74         -  constraints.  Any data can be
    75         -  inserted into any column.  You can put arbitrary length strings into
    76         -  integer columns, floating point numbers in boolean columns, or dates
    77         -  in character columns.  The datatype you assign to a column in the
    78         -  CREATE TABLE command does not restrict what data can be put into
    79         -  that column.  Every column is able to hold
    80         -  an arbitrary length string.  (There is one exception: Columns of
    81         -  type INTEGER PRIMARY KEY may only hold a 64-bit signed integer.
    82         -  An error will result
    83         -  if you try to put anything other than an integer into an
    84         -  INTEGER PRIMARY KEY column.)</p>
    85         -
    86         -  <p>But SQLite does use the declared type of a column as a hint
    87         -  that you prefer values in that format.  So, for example, if a
    88         -  column is of type INTEGER and you try to insert a string into
    89         -  that column, SQLite will attempt to convert the string into an
    90         -  integer.  If it can, it inserts the integer instead.  If not,
    91         -  it inserts the string.  This feature is sometimes
    92         -  call <a href="datatype3.html#affinity">type or column affinity</a>.
    93         -  </p>
    94         -}
    95         -
    96         -faq {
    97         -  Why doesn't SQLite allow me to use '0' and '0.0' as the primary
    98         -  key on two different rows of the same table?
    99         -} {
   100         -  <p>Your primary key must have a numeric type.  Change the datatype of
   101         -  your primary key to TEXT and it should work.</p>
   102         -
   103         -  <p>Every row must have a unique primary key.  For a column with a
   104         -  numeric type, SQLite thinks that <b>'0'</b> and <b>'0.0'</b> are the
   105         -  same value because they compare equal to one another numerically.
   106         -  (See the previous question.)  Hence the values are not unique.</p>
   107         -}
   108         -        
   109         -
   110         -faq {
   111         -  Can multiple applications or multiple instances of the same
   112         -  application access a single database file at the same time?
   113         -} {
   114         -  <p>Multiple processes can have the same database open at the same
   115         -  time.  Multiple processes can be doing a SELECT
   116         -  at the same time.  But only one process can be making changes to
   117         -  the database at any moment in time, however.</p>
   118         -
   119         -  <p>SQLite uses reader/writer locks to control access to the database.
   120         -  (Under Win95/98/ME which lacks support for reader/writer locks, a
   121         -  probabilistic simulation is used instead.)
   122         -  But use caution: this locking mechanism might
   123         -  not work correctly if the database file is kept on an NFS filesystem.
   124         -  This is because fcntl() file locking is broken on many NFS implementations.
   125         -  You should avoid putting SQLite database files on NFS if multiple
   126         -  processes might try to access the file at the same time.  On Windows,
   127         -  Microsoft's documentation says that locking may not work under FAT
   128         -  filesystems if you are not running the Share.exe daemon.  People who
   129         -  have a lot of experience with Windows tell me that file locking of
   130         -  network files is very buggy and is not dependable.  If what they
   131         -  say is true, sharing an SQLite database between two or more Windows
   132         -  machines might cause unexpected problems.</p>
   133         -
   134         -  <p>We are aware of no other <i>embedded</i> SQL database engine that
   135         -  supports as much concurrancy as SQLite.  SQLite allows multiple processes
   136         -  to have the database file open at once, and for multiple processes to
   137         -  read the database at once.  When any process wants to write, it must
   138         -  lock the entire database file for the duration of its update.  But that
   139         -  normally only takes a few milliseconds.  Other processes just wait on
   140         -  the writer to finish then continue about their business.  Other embedded
   141         -  SQL database engines typically only allow a single process to connect to
   142         -  the database at once.</p>
   143         -
   144         -  <p>However, client/server database engines (such as PostgreSQL, MySQL,
   145         -  or Oracle) usually support a higher level of concurrency and allow
   146         -  multiple processes to be writing to the same database at the same time.
   147         -  This is possible in a client/server database because there is always a
   148         -  single well-controlled server process available to coordinate access.
   149         -  If your application has a need for a lot of concurrency, then you should
   150         -  consider using a client/server database.  But experience suggests that
   151         -  most applications need much less concurrency than their designers imagine.
   152         -  </p>
   153         -
   154         -  <p>When SQLite tries to access a file that is locked by another
   155         -  process, the default behavior is to return SQLITE_BUSY.  You can
   156         -  adjust this behavior from C code using the 
   157         -  <a href="capi3ref.html#sqlite3_busy_handler">sqlite3_busy_handler()</a> or
   158         -  <a href="capi3ref.html#sqlite3_busy_timeout">sqlite3_busy_timeout()</a>
   159         -  API functions.</p>
   160         -}
   161         -
   162         -faq {
   163         -  Is SQLite threadsafe?
   164         -} {
   165         -  <p>Yes.  Sometimes.  In order to be thread-safe, SQLite must be compiled
   166         -  with the SQLITE_THREADSAFE preprocessor macro set to 1.  Both the windows
   167         -  and linux precompiled binaries in the distribution are compiled this way.
   168         -  If you are unsure if the SQLite library you are linking against is compiled
   169         -  to be threadsafe you can call the
   170         -  <a href="capi3ref.html#sqlite3_threadsafe">sqlite3_threadsafe()</a>
   171         -  interface to find out.
   172         -  </p>
   173         -
   174         -  <p>Prior to version 3.3.1,
   175         -  an <b>sqlite3</b> structure could only be used in the same thread
   176         -  that called <a href="capi3ref.html#sqlite3_open">sqlite3_open</a>
   177         -  to create it.
   178         -  You could not open a
   179         -  database in one thread then pass the handle off to another thread for
   180         -  it to use.  This was due to limitations (bugs?) in many common threading
   181         -  implementations such as on RedHat9.  Specifically, an fcntl() lock
   182         -  created by one thread cannot be removed or modified by a different
   183         -  thread on the troublesome systems.  And since SQLite uses fcntl()
   184         -  locks heavily for concurrency control, serious problems arose if you 
   185         -  start moving database connections across threads.</p>
   186         -
   187         -  <p>The restriction on moving database connections across threads
   188         -  was relaxed somewhat in version 3.3.1.  With that and subsequent
   189         -  versions, it is safe to move a connection handle across threads
   190         -  as long as the connection is not holding any fcntl() locks.  You
   191         -  can safely assume that no locks are being held if no
   192         -  transaction is pending and all statements have been finalized.</p>
   193         -
   194         -  <p>Under UNIX, you should not carry an open SQLite database across
   195         -  a fork() system call into the child process.  Problems will result
   196         -  if you do.</p>
   197         -}
   198         -
   199         -faq {
   200         -  How do I list all tables/indices contained in an SQLite database
   201         -} {
   202         -  <p>If you are running the <b>sqlite3</b> command-line access program
   203         -  you can type "<b>.tables</b>" to get a list of all tables.  Or you
   204         -  can type "<b>.schema</b>" to see the complete database schema including
   205         -  all tables and indices.  Either of these commands can be followed by
   206         -  a LIKE pattern that will restrict the tables that are displayed.</p>
   207         -
   208         -  <p>From within a C/C++ program (or a script using Tcl/Ruby/Perl/Python
   209         -  bindings) you can get access to table and index names by doing a SELECT
   210         -  on a special table named "<b>SQLITE_MASTER</b>".  Every SQLite database
   211         -  has an SQLITE_MASTER table that defines the schema for the database.
   212         -  The SQLITE_MASTER table looks like this:</p>
   213         -<blockquote><pre>
   214         -CREATE TABLE sqlite_master (
   215         -  type TEXT,
   216         -  name TEXT,
   217         -  tbl_name TEXT,
   218         -  rootpage INTEGER,
   219         -  sql TEXT
   220         -);
   221         -</pre></blockquote>
   222         -  <p>For tables, the <b>type</b> field will always be <b>'table'</b> and the
   223         -  <b>name</b> field will be the name of the table.  So to get a list of
   224         -  all tables in the database, use the following SELECT command:</p>
   225         -<blockquote><pre>
   226         -SELECT name FROM sqlite_master
   227         -WHERE type='table'
   228         -ORDER BY name;
   229         -</pre></blockquote>
   230         -  <p>For indices, <b>type</b> is equal to <b>'index'</b>, <b>name</b> is the
   231         -  name of the index and <b>tbl_name</b> is the name of the table to which
   232         -  the index belongs.  For both tables and indices, the <b>sql</b> field is
   233         -  the text of the original CREATE TABLE or CREATE INDEX statement that
   234         -  created the table or index.  For automatically created indices (used
   235         -  to implement the PRIMARY KEY or UNIQUE constraints) the <b>sql</b> field
   236         -  is NULL.</p>
   237         -
   238         -  <p>The SQLITE_MASTER table is read-only.  You cannot change this table
   239         -  using UPDATE, INSERT, or DELETE.  The table is automatically updated by
   240         -  CREATE TABLE, CREATE INDEX, DROP TABLE, and DROP INDEX commands.</p>
   241         -
   242         -  <p>Temporary tables do not appear in the SQLITE_MASTER table.  Temporary
   243         -  tables and their indices and triggers occur in another special table
   244         -  named SQLITE_TEMP_MASTER.  SQLITE_TEMP_MASTER works just like SQLITE_MASTER
   245         -  except that it is only visible to the application that created the 
   246         -  temporary tables.  To get a list of all tables, both permanent and
   247         -  temporary, one can use a command similar to the following:
   248         -<blockquote><pre>
   249         -SELECT name FROM 
   250         -   (SELECT * FROM sqlite_master UNION ALL
   251         -    SELECT * FROM sqlite_temp_master)
   252         -WHERE type='table'
   253         -ORDER BY name
   254         -</pre></blockquote>
   255         -}
   256         -
   257         -faq {
   258         -  Are there any known size limits to SQLite databases?
   259         -} {
   260         -  <p>See <a href="limits.html">limits.html</a> for a full discussion of
   261         -  the limits of SQLite.</p>
   262         -}
   263         -
   264         -faq {
   265         -  What is the maximum size of a VARCHAR in SQLite?
   266         -} {
   267         -  <p>SQLite does not enforce the length of a VARCHAR.  You can declare
   268         -  a VARCHAR(10) and SQLite will be happy to let you put 500 characters
   269         -  in it.  And it will keep all 500 characters intact - it never truncates.
   270         -  </p>
   271         -}
   272         -
   273         -faq {
   274         -  Does SQLite support a BLOB type?
   275         -} {
   276         -  <p>SQLite versions 3.0 and later allow you to store BLOB data in any 
   277         -  column, even columns that are declared to hold some other type.</p>
   278         -}
   279         -
   280         -faq {
   281         -  How do I add or delete columns from an existing table in SQLite.
   282         -} {
   283         -  <p>SQLite has limited 
   284         -  <a href="lang_altertable.html">ALTER TABLE</a> support that you can
   285         -  use to add a column to the end of a table or to change the name of
   286         -  a table.  
   287         -  If you what make more complex changes the structure of a table,
   288         -  you will have to recreate the
   289         -  table.  You can save existing data to a temporary table, drop the
   290         -  old table, create the new table, then copy the data back in from
   291         -  the temporary table.</p>
   292         -
   293         -  <p>For example, suppose you have a table named "t1" with columns
   294         -  names "a", "b", and "c" and that you want to delete column "c" from
   295         -  this table.  The following steps illustrate how this could be done:
   296         -  </p>
   297         -
   298         -  <blockquote><pre>
   299         -BEGIN TRANSACTION;
   300         -CREATE TEMPORARY TABLE t1_backup(a,b);
   301         -INSERT INTO t1_backup SELECT a,b FROM t1;
   302         -DROP TABLE t1;
   303         -CREATE TABLE t1(a,b);
   304         -INSERT INTO t1 SELECT a,b FROM t1_backup;
   305         -DROP TABLE t1_backup;
   306         -COMMIT;
   307         -</pre></blockquote>
   308         -}
   309         -
   310         -faq {
   311         -  I deleted a lot of data but the database file did not get any
   312         -  smaller.  Is this a bug?
   313         -} {
   314         -  <p>No.  When you delete information from an SQLite database, the
   315         -  unused disk space is added to an internal "free-list" and is reused
   316         -  the next time you insert data.  The disk space is not lost.  But
   317         -  neither is it returned to the operating system.</p>
   318         -
   319         -  <p>If you delete a lot of data and want to shrink the database file,
   320         -  run the <a href="lang_vacuum.html">VACUUM</a> command.
   321         -  VACUUM will reconstruct
   322         -  the database from scratch.  This will leave the database with an empty
   323         -  free-list and a file that is minimal in size.  Note, however, that the
   324         -  VACUUM can take some time to run (around a half second per megabyte
   325         -  on the Linux box where SQLite is developed) and it can use up to twice
   326         -  as much temporary disk space as the original file while it is running.
   327         -  </p>
   328         -
   329         -  <p>As of SQLite version 3.1, an alternative to using the VACUUM command
   330         -  is auto-vacuum mode, enabled using the 
   331         -  <a href="pragma.html#pragma_auto_vacuum">auto_vacuum pragma</a>.</p>
   332         -}
   333         -
   334         -faq {
   335         -  Can I use SQLite in my commercial product without paying royalties?
   336         -} {
   337         -  <p>Yes.  SQLite is in the 
   338         -  <a href="copyright.html">public domain</a>.  No claim of ownership is made
   339         -  to any part of the code.  You can do anything you want with it.</p>
   340         -}
   341         -
   342         -faq {
   343         -  How do I use a string literal that contains an embedded single-quote (')
   344         -  character?
   345         -} {
   346         -  <p>The SQL standard specifies that single-quotes in strings are escaped
   347         -  by putting two single quotes in a row.  SQL works like the Pascal programming
   348         -  language in the regard.  SQLite follows this standard.  Example:
   349         -  </p>
   350         -
   351         -  <blockquote><pre>
   352         -    INSERT INTO xyz VALUES('5 O''clock');
   353         -  </pre></blockquote>
   354         -}
   355         -
   356         -faq {What is an SQLITE_SCHEMA error, and why am I getting one?} {
   357         -  <p>An SQLITE_SCHEMA error is returned when a 
   358         -  prepared SQL statement is no longer valid and cannot be executed.
   359         -  When this occurs, the statement must be recompiled from SQL using 
   360         -  the 
   361         -  <a href="capi3ref.html#sqlite3_prepare">sqlite3_prepare()</a> API.
   362         -  In SQLite version 3, an SQLITE_SCHEMA error can
   363         -  only occur when using the 
   364         -  <a href="capi3ref.html#sqlite3_prepare">sqlite3_prepare()</a>/<a
   365         -  href="capi3ref.html#sqlite3_step">sqlite3_step()</a>/<a
   366         -  href="capi3ref.html#sqlite3_finalize">sqlite3_finalize()</a>
   367         -  API to execute SQL, not when using the
   368         -  <a href="capi3ref.html#sqlite3_exec">sqlite3_exec()</a>. This was not
   369         -  the case in version 2.</p>
   370         -
   371         -  <p>The most common reason for a prepared statement to become invalid
   372         -  is that the schema of the database was modified after the SQL was 
   373         -  prepared (possibly by another process).  The other reasons this can 
   374         -  happen are:</p> 
   375         -  <ul>
   376         -  <li>A database was <a href="lang_detach.html">DETACH</a>ed.
   377         -  <li>The database was <a href="lang_vacuum.html">VACUUM</a>ed
   378         -  <li>A user-function definition was deleted or changed.
   379         -  <li>A collation sequence definition was deleted or changed.
   380         -  <li>The authorization function was changed.
   381         -  </ul>
   382         -
   383         -  <p>In all cases, the solution is to recompile the statement from SQL
   384         -  and attempt to execute it again. Because a prepared statement can be
   385         -  invalidated by another process changing the database schema, all code
   386         -  that uses the
   387         -  <a href="capi3ref.html#sqlite3_prepare">sqlite3_prepare()</a>/<a
   388         -  href="capi3ref.html#sqlite3_step">sqlite3_step()</a>/<a
   389         -  href="capi3ref.html#sqlite3_finalize">sqlite3_finalize()</a>
   390         -  API should be prepared to handle SQLITE_SCHEMA errors. An example
   391         -  of one approach to this follows:</p>
   392         -
   393         -  <blockquote><pre>
   394         -
   395         -    int rc;
   396         -    sqlite3_stmt *pStmt;
   397         -    char zSql[] = "SELECT .....";
   398         -
   399         -    do {
   400         -      /* Compile the statement from SQL. Assume success. */
   401         -      sqlite3_prepare(pDb, zSql, -1, &pStmt, 0);
   402         -
   403         -      while( SQLITE_ROW==sqlite3_step(pStmt) ){
   404         -        /* Do something with the row of available data */
   405         -      }
   406         -
   407         -      /* Finalize the statement. If an SQLITE_SCHEMA error has
   408         -      ** occured, then the above call to sqlite3_step() will have
   409         -      ** returned SQLITE_ERROR. sqlite3_finalize() will return
   410         -      ** SQLITE_SCHEMA. In this case the loop will execute again.
   411         -      */
   412         -      rc = sqlite3_finalize(pStmt);
   413         -    } while( rc==SQLITE_SCHEMA );
   414         -    
   415         -  </pre></blockquote>
   416         -}
   417         -
   418         -faq {Why does ROUND(9.95,1)  return 9.9 instead of 10.0?
   419         -     Shouldn't 9.95 round up?} {
   420         -  <p>SQLite uses binary arithmetic and in binary, there is no
   421         -  way to write 9.95 in a finite number of bits.  The closest to
   422         -  you can get to 9.95 in a 64-bit IEEE float (which is what
   423         -  SQLite uses) is 9.949999999999999289457264239899814128875732421875.
   424         -  So when you type "9.95", SQLite really understands the number to be
   425         -  the much longer value shown above.  And that value rounds down.</p>
   426         -
   427         -  <p>This kind of problem comes up all the time when dealing with
   428         -  floating point binary numbers.  The general rule to remember is
   429         -  that most fractional numbers that have a finite representation in decimal
   430         -  (a.k.a "base-10")
   431         -  do not have a finite representation in binary (a.k.a "base-2").
   432         -  And so they are
   433         -  approximated using the closest binary number available.  That
   434         -  approximation is usually very close, but it will be slightly off
   435         -  and in some cases can cause your results to be a little different
   436         -  from what you might expect.</p>
   437         -}
   438         -
   439         -# End of questions and answers.
   440         -#############
   441         -
   442         -puts {<h2>Frequently Asked Questions</h2>}
   443         -
   444         -# puts {<DL COMPACT>}
   445         -# for {set i 1} {$i<$cnt} {incr i} {
   446         -#   puts "  <DT><A HREF=\"#q$i\">($i)</A></DT>"
   447         -#   puts "  <DD>[lindex $faq($i) 0]</DD>"
   448         -# }
   449         -# puts {</DL>}
   450         -puts {<OL>}
   451         -for {set i 1} {$i<$cnt} {incr i} {
   452         -  puts "<li><a href=\"#q$i\">[lindex $faq($i) 0]</a></li>"
   453         -}
   454         -puts {</OL>}
   455         -
   456         -for {set i 1} {$i<$cnt} {incr i} {
   457         -  puts "<A NAME=\"q$i\"><HR />"
   458         -  puts "<P><B>($i) [lindex $faq($i) 0]</B></P>\n"
   459         -  puts "<BLOCKQUOTE>[lindex $faq($i) 1]</BLOCKQUOTE></LI>\n"
   460         -}
   461         -
   462         -puts {</OL>}
   463         -footer $rcsid

Deleted fileformat.tcl.

     1         -#
     2         -# Run this script to generated a fileformat.html output file
     3         -#
     4         -set rcsid {$Id: fileformat.tcl,v 1.13 2004/10/10 17:24:55 drh Exp $}
     5         -source common.tcl
     6         -header {SQLite Database File Format (Version 2)}
     7         -puts {
     8         -<h2>SQLite 2.X Database File Format</h2>
     9         -
    10         -<p>
    11         -This document describes the disk file format for SQLite versions 2.1
    12         -through 2.8.  SQLite version 3.0 and following uses a very different
    13         -format which is described separately.
    14         -</p>
    15         -
    16         -<h3>1.0 &nbsp; Layers</h3>
    17         -
    18         -<p>
    19         -SQLite is implemented in layers.
    20         -(See the <a href="arch.html">architecture description</a>.)
    21         -The format of database files is determined by three different
    22         -layers in the architecture.
    23         -</p>
    24         -
    25         -<ul>
    26         -<li>The <b>schema</b> layer implemented by the VDBE.</li>
    27         -<li>The <b>b-tree</b> layer implemented by btree.c</li>
    28         -<li>The <b>pager</b> layer implemented by pager.c</li>
    29         -</ul>
    30         -
    31         -<p>
    32         -We will describe each layer beginning with the bottom (pager)
    33         -layer and working upwards.
    34         -</p>
    35         -
    36         -<h3>2.0 &nbsp; The Pager Layer</h3>
    37         -
    38         -<p>
    39         -An SQLite database consists of
    40         -"pages" of data.  Each page is 1024 bytes in size.
    41         -Pages are numbered beginning with 1.
    42         -A page number of 0 is used to indicate "no such page" in the
    43         -B-Tree and Schema layers.
    44         -</p>
    45         -
    46         -<p>
    47         -The pager layer is responsible for implementing transactions
    48         -with atomic commit and rollback.  It does this using a separate
    49         -journal file.  Whenever a new transaction is started, a journal
    50         -file is created that records the original state of the database.
    51         -If the program terminates before completing the transaction, the next
    52         -process to open the database can use the journal file to restore
    53         -the database to its original state.
    54         -</p>
    55         -
    56         -<p>
    57         -The journal file is located in the same directory as the database
    58         -file and has the same name as the database file but with the
    59         -characters "<tt>-journal</tt>" appended.
    60         -</p>
    61         -
    62         -<p>
    63         -The pager layer does not impose any content restrictions on the
    64         -main database file.  As far as the pager is concerned, each page
    65         -contains 1024 bytes of arbitrary data.  But there is structure to
    66         -the journal file.
    67         -</p>
    68         -
    69         -<p>
    70         -A journal file begins with 8 bytes as follows:
    71         -0xd9, 0xd5, 0x05, 0xf9, 0x20, 0xa1, 0x63, and 0xd6.
    72         -Processes that are attempting to rollback a journal use these 8 bytes
    73         -as a sanity check to make sure the file they think is a journal really
    74         -is a valid journal.  Prior version of SQLite used different journal
    75         -file formats.  The magic numbers for these prior formats are different
    76         -so that if a new version of the library attempts to rollback a journal
    77         -created by an earlier version, it can detect that the journal uses
    78         -an obsolete format and make the necessary adjustments.  This article
    79         -describes only the newest journal format - supported as of version
    80         -2.8.0.
    81         -</p>
    82         -
    83         -<p>
    84         -Following the 8 byte prefix is a three 4-byte integers that tell us
    85         -the number of pages that have been committed to the journal,
    86         -a magic number used for
    87         -sanity checking each page, and the
    88         -original size of the main database file before the transaction was
    89         -started.  The number of committed pages is used to limit how far
    90         -into the journal to read.  The use of the checksum magic number is
    91         -described below.
    92         -The original size of the database is used to restore the database
    93         -file back to its original size.
    94         -The size is expressed in pages (1024 bytes per page).
    95         -</p>
    96         -
    97         -<p>
    98         -All three integers in the journal header and all other multi-byte
    99         -numbers used in the journal file are big-endian.
   100         -That means that the most significant byte
   101         -occurs first.  That way, a journal file that is
   102         -originally created on one machine can be rolled back by another
   103         -machine that uses a different byte order.  So, for example, a
   104         -transaction that failed to complete on your big-endian SparcStation
   105         -can still be rolled back on your little-endian Linux box.
   106         -</p>
   107         -
   108         -<p>
   109         -After the 8-byte prefix and the three 4-byte integers, the
   110         -journal file consists of zero or more page records.  Each page
   111         -record is a 4-byte (big-endian) page number followed by 1024 bytes
   112         -of data and a 4-byte checksum.  
   113         -The data is the original content of the database page
   114         -before the transaction was started.  So to roll back the transaction,
   115         -the data is simply written into the corresponding page of the
   116         -main database file.  Pages can appear in the journal in any order,
   117         -but they are guaranteed to appear only once. All page numbers will be
   118         -between 1 and the maximum specified by the page size integer that
   119         -appeared at the beginning of the journal.
   120         -</p>
   121         -
   122         -<p>
   123         -The so-called checksum at the end of each record is not really a
   124         -checksum - it is the sum of the page number and the magic number which
   125         -was the second integer in the journal header.  The purpose of this
   126         -value is to try to detect journal corruption that might have occurred
   127         -because of a power loss or OS crash that occurred which the journal
   128         -file was being written to disk.  It could have been the case that the
   129         -meta-data for the journal file, specifically the size of the file, had
   130         -been written to the disk so that when the machine reboots it appears that
   131         -file is large enough to hold the current record.  But even though the
   132         -file size has changed, the data for the file might not have made it to
   133         -the disk surface at the time of the OS crash or power loss.  This means
   134         -that after reboot, the end of the journal file will contain quasi-random
   135         -garbage data.  The checksum is an attempt to detect such corruption.  If
   136         -the checksum does not match, that page of the journal is not rolled back.
   137         -</p>
   138         -
   139         -<p>
   140         -Here is a summary of the journal file format:
   141         -</p>
   142         -
   143         -<ul>
   144         -<li>8 byte prefix: 0xd9, 0xd5, 0x05, 0xf9, 0x20, 0xa1, 0x63, 0xd6</li>
   145         -<li>4 byte number of records in journal</li>
   146         -<li>4 byte magic number used for page checksums</li>
   147         -<li>4 byte initial database page count</li>
   148         -<li>Zero or more instances of the following:
   149         -   <ul>
   150         -   <li>4 byte page number</li>
   151         -   <li>1024 bytes of original data for the page</li>
   152         -   <li>4 byte checksum</li>
   153         -   </ul>
   154         -</li>
   155         -</ul>
   156         -
   157         -<h3>3.0 &nbsp; The B-Tree Layer</h3>
   158         -
   159         -<p>
   160         -The B-Tree layer builds on top of the pager layer to implement
   161         -one or more separate b-trees all in the same disk file.  The
   162         -algorithms used are taken from Knuth's <i>The Art Of Computer
   163         -Programming.</i></p>
   164         -
   165         -<p>
   166         -Page 1 of a database contains a header string used for sanity
   167         -checking, a few 32-bit words of configuration data, and a pointer
   168         -to the beginning of a list of unused pages in the database.
   169         -All other pages in the
   170         -database are either pages of a b-tree, overflow pages, or unused
   171         -pages on the freelist.
   172         -</p>
   173         -
   174         -<p>
   175         -Each b-tree page contains zero or more database entries.
   176         -Each entry has an unique key of one or more bytes and data of
   177         -zero or more bytes.
   178         -Both the key and data are arbitrary byte sequences.  The combination
   179         -of key and data are collectively known as "payload".  The current
   180         -implementation limits the amount of payload in a single entry to
   181         -1048576 bytes.  This limit can be raised to 16777216 by adjusting
   182         -a single #define in the source code and recompiling.  But most entries
   183         -contain less than a hundred bytes of payload so a megabyte limit seems
   184         -more than enough.
   185         -</p>
   186         -
   187         -<p>
   188         -Up to 238 bytes of payload for an entry can be held directly on
   189         -a b-tree page.  Any additional payload is contained on a linked list
   190         -of overflow pages.  This limit on the amount of payload held directly
   191         -on b-tree pages guarantees that each b-tree page can hold at least
   192         -4 entries.  In practice, most entries are smaller than 238 bytes and
   193         -thus most pages can hold more than 4 entries.
   194         -</p>
   195         -
   196         -<p>
   197         -A single database file can hold any number of separate, independent b-trees.
   198         -Each b-tree is identified by its root page, which never changes.
   199         -Child pages of the b-tree may change as entries are added and removed
   200         -and pages split and combine.  But the root page always stays the same.
   201         -The b-tree itself does not record which pages are root pages and which
   202         -are not.  That information is handled entirely at the schema layer.
   203         -</p>
   204         -
   205         -<h4>3.1 &nbsp; B-Tree Page 1 Details</h4>
   206         -
   207         -<p>
   208         -Page 1 begins with the following 48-byte string:
   209         -</p>
   210         -
   211         -<blockquote><pre>
   212         -** This file contains an SQLite 2.1 database **
   213         -</pre></blockquote>
   214         -
   215         -<p>
   216         -If you count the number of characters in the string above, you will
   217         -see that there are only 47.  A '\000' terminator byte is added to
   218         -bring the total to 48.
   219         -</p>
   220         -
   221         -<p>
   222         -A frequent question is why the string says version 2.1 when (as
   223         -of this writing) we are up to version 2.7.0 of SQLite and any
   224         -change to the second digit of the version is suppose to represent
   225         -a database format change.  The answer to this is that the B-tree
   226         -layer has not changed any since version 2.1.  There have been
   227         -database format changes since version 2.1 but those changes have
   228         -all been in the schema layer.  Because the format of the b-tree
   229         -layer is unchanged since version 2.1.0, the header string still
   230         -says version 2.1.
   231         -</p>
   232         -
   233         -<p>
   234         -After the format string is a 4-byte integer used to determine the
   235         -byte-order of the database.  The integer has a value of
   236         -0xdae37528.  If this number is expressed as 0xda, 0xe3, 0x75, 0x28, then
   237         -the database is in a big-endian format and all 16 and 32-bit integers
   238         -elsewhere in the b-tree layer are also big-endian.  If the number is
   239         -expressed as 0x28, 0x75, 0xe3, and 0xda, then the database is in a
   240         -little-endian format and all other multi-byte numbers in the b-tree 
   241         -layer are also little-endian.  
   242         -Prior to version 2.6.3, the SQLite engine was only able to read databases
   243         -that used the same byte order as the processor they were running on.
   244         -But beginning with 2.6.3, SQLite can read or write databases in any
   245         -byte order.
   246         -</p>
   247         -
   248         -<p>
   249         -After the byte-order code are six 4-byte integers.  Each integer is in the
   250         -byte order determined by the byte-order code.  The first integer is the
   251         -page number for the first page of the freelist.  If there are no unused
   252         -pages in the database, then this integer is 0.  The second integer is
   253         -the number of unused pages in the database.  The last 4 integers are
   254         -not used by the b-tree layer.  These are the so-called "meta" values that
   255         -are passed up to the schema layer
   256         -and used there for configuration and format version information.
   257         -All bytes of page 1 past beyond the meta-value integers are unused 
   258         -and are initialized to zero.
   259         -</p>
   260         -
   261         -<p>
   262         -Here is a summary of the information contained on page 1 in the b-tree layer:
   263         -</p>
   264         -
   265         -<ul>
   266         -<li>48 byte header string</li>
   267         -<li>4 byte integer used to determine the byte-order</li>
   268         -<li>4 byte integer which is the first page of the freelist</li>
   269         -<li>4 byte integer which is the number of pages on the freelist</li>
   270         -<li>36 bytes of meta-data arranged as nine 4-byte integers</li>
   271         -<li>928 bytes of unused space</li>
   272         -</ul>
   273         -
   274         -<h4>3.2 &nbsp; Structure Of A Single B-Tree Page</h4>
   275         -
   276         -<p>
   277         -Conceptually, a b-tree page contains N database entries and N+1 pointers
   278         -to other b-tree pages.
   279         -</p>
   280         -
   281         -<blockquote>
   282         -<table border=1 cellspacing=0 cellpadding=5>
   283         -<tr>
   284         -<td align="center">Ptr<br>0</td>
   285         -<td align="center">Entry<br>0</td>
   286         -<td align="center">Ptr<br>1</td>
   287         -<td align="center">Entry<br>1</td>
   288         -<td align="center"><b>...</b></td>
   289         -<td align="center">Ptr<br>N-1</td>
   290         -<td align="center">Entry<br>N-1</td>
   291         -<td align="center">Ptr<br>N</td>
   292         -</tr>
   293         -</table>
   294         -</blockquote>
   295         -
   296         -<p>
   297         -The entries are arranged in increasing order.  That is, the key to
   298         -Entry 0 is less than the key to Entry 1, and the key to Entry 1 is
   299         -less than the key of Entry 2, and so forth.  The pointers point to
   300         -pages containing additional entries that have keys in between the
   301         -entries on either side.  So Ptr 0 points to another b-tree page that
   302         -contains entries that all have keys less than Key 0, and Ptr 1
   303         -points to a b-tree pages where all entries have keys greater than Key 0
   304         -but less than Key 1, and so forth.
   305         -</p>
   306         -
   307         -<p>
   308         -Each b-tree page in SQLite consists of a header, zero or more "cells"
   309         -each holding a single entry and pointer, and zero or more "free blocks"
   310         -that represent unused space on the page.
   311         -</p>
   312         -
   313         -<p>
   314         -The header on a b-tree page is the first 8 bytes of the page.
   315         -The header contains the value
   316         -of the right-most pointer (Ptr N) and the byte offset into the page
   317         -of the first cell and the first free block.  The pointer is a 32-bit
   318         -value and the offsets are each 16-bit values.  We have:
   319         -</p>
   320         -
   321         -<blockquote>
   322         -<table border=1 cellspacing=0 cellpadding=5>
   323         -<tr>
   324         -<td align="center" width=30>0</td>
   325         -<td align="center" width=30>1</td>
   326         -<td align="center" width=30>2</td>
   327         -<td align="center" width=30>3</td>
   328         -<td align="center" width=30>4</td>
   329         -<td align="center" width=30>5</td>
   330         -<td align="center" width=30>6</td>
   331         -<td align="center" width=30>7</td>
   332         -</tr>
   333         -<tr>
   334         -<td align="center" colspan=4>Ptr N</td>
   335         -<td align="center" colspan=2>Cell 0</td>
   336         -<td align="center" colspan=2>Freeblock 0</td>
   337         -</tr>
   338         -</table>
   339         -</blockquote>
   340         -
   341         -<p>
   342         -The 1016 bytes of a b-tree page that come after the header contain
   343         -cells and freeblocks.  All 1016 bytes are covered by either a cell
   344         -or a freeblock.
   345         -</p>
   346         -
   347         -<p>
   348         -The cells are connected in a linked list.  Cell 0 contains Ptr 0 and
   349         -Entry 0.  Bytes 4 and 5 of the header point to Cell 0.  Cell 0 then
   350         -points to Cell 1 which contains Ptr 1 and Entry 1.  And so forth.
   351         -Cells vary in size.  Every cell has a 12-byte header and at least 4
   352         -bytes of payload space.  Space is allocated to payload in increments
   353         -of 4 bytes.  Thus the minimum size of a cell is 16 bytes and up to
   354         -63 cells can fit on a single page.  The size of a cell is always a multiple
   355         -of 4 bytes.
   356         -A cell can have up to 238 bytes of payload space.  If
   357         -the payload is more than 238 bytes, then an additional 4 byte page
   358         -number is appended to the cell which is the page number of the first
   359         -overflow page containing the additional payload.  The maximum size
   360         -of a cell is thus 254 bytes, meaning that a least 4 cells can fit into
   361         -the 1016 bytes of space available on a b-tree page.
   362         -An average cell is usually around 52 to 100 bytes in size with about
   363         -10 or 20 cells to a page.
   364         -</p>
   365         -
   366         -<p>
   367         -The data layout of a cell looks like this:
   368         -</p>
   369         -
   370         -<blockquote>
   371         -<table border=1 cellspacing=0 cellpadding=5>
   372         -<tr>
   373         -<td align="center" width=20>0</td>
   374         -<td align="center" width=20>1</td>
   375         -<td align="center" width=20>2</td>
   376         -<td align="center" width=20>3</td>
   377         -<td align="center" width=20>4</td>
   378         -<td align="center" width=20>5</td>
   379         -<td align="center" width=20>6</td>
   380         -<td align="center" width=20>7</td>
   381         -<td align="center" width=20>8</td>
   382         -<td align="center" width=20>9</td>
   383         -<td align="center" width=20>10</td>
   384         -<td align="center" width=20>11</td>
   385         -<td align="center" width=100>12 ... 249</td>
   386         -<td align="center" width=20>250</td>
   387         -<td align="center" width=20>251</td>
   388         -<td align="center" width=20>252</td>
   389         -<td align="center" width=20>253</td>
   390         -</tr>
   391         -<tr>
   392         -<td align="center" colspan=4>Ptr</td>
   393         -<td align="center" colspan=2>Keysize<br>(low)</td>
   394         -<td align="center" colspan=2>Next</td>
   395         -<td align="center" colspan=1>Ksz<br>(hi)</td>
   396         -<td align="center" colspan=1>Dsz<br>(hi)</td>
   397         -<td align="center" colspan=2>Datasize<br>(low)</td>
   398         -<td align="center" colspan=1>Payload</td>
   399         -<td align="center" colspan=4>Overflow<br>Pointer</td>
   400         -</tr>
   401         -</table>
   402         -</blockquote>
   403         -
   404         -<p>
   405         -The first four bytes are the pointer.  The size of the key is a 24-bit
   406         -where the upper 8 bits are taken from byte 8 and the lower 16 bits are
   407         -taken from bytes 4 and 5 (or bytes 5 and 4 on little-endian machines.)
   408         -The size of the data is another 24-bit value where the upper 8 bits
   409         -are taken from byte 9 and the lower 16 bits are taken from bytes 10 and
   410         -11 or 11 and 10, depending on the byte order.  Bytes 6 and 7 are the
   411         -offset to the next cell in the linked list of all cells on the current
   412         -page.  This offset is 0 for the last cell on the page.
   413         -</p>
   414         -
   415         -<p>
   416         -The payload itself can be any number of bytes between 1 and 1048576.
   417         -But space to hold the payload is allocated in 4-byte chunks up to
   418         -238 bytes.  If the entry contains more than 238 bytes of payload, then
   419         -additional payload data is stored on a linked list of overflow pages.
   420         -A 4 byte page number is appended to the cell that contains the first
   421         -page of this linked list.
   422         -</p>
   423         -
   424         -<p>
   425         -Each overflow page begins with a 4-byte value which is the
   426         -page number of the next overflow page in the list.   This value is
   427         -0 for the last page in the list.  The remaining
   428         -1020 bytes of the overflow page are available for storing payload.
   429         -Note that a full page is allocated regardless of the number of overflow
   430         -bytes stored.  Thus, if the total payload for an entry is 239 bytes,
   431         -the first 238 are stored in the cell and the overflow page stores just
   432         -one byte.
   433         -</p>
   434         -
   435         -<p>
   436         -The structure of an overflow page looks like this:
   437         -</p>
   438         -
   439         -<blockquote>
   440         -<table border=1 cellspacing=0 cellpadding=5>
   441         -<tr>
   442         -<td align="center" width=20>0</td>
   443         -<td align="center" width=20>1</td>
   444         -<td align="center" width=20>2</td>
   445         -<td align="center" width=20>3</td>
   446         -<td align="center" width=200>4 ... 1023</td>
   447         -</tr>
   448         -<tr>
   449         -<td align="center" colspan=4>Next Page</td>
   450         -<td align="center" colspan=1>Overflow Data</td>
   451         -</tr>
   452         -</table>
   453         -</blockquote>
   454         -
   455         -<p>
   456         -All space on a b-tree page which is not used by the header or by cells
   457         -is filled by freeblocks.  Freeblocks, like cells, are variable in size.
   458         -The size of a freeblock is at least 4 bytes and is always a multiple of
   459         -4 bytes.
   460         -The first 4 bytes contain a header and the remaining bytes
   461         -are unused.  The structure of the freeblock is as follows:
   462         -</p>
   463         -
   464         -<blockquote>
   465         -<table border=1 cellspacing=0 cellpadding=5>
   466         -<tr>
   467         -<td align="center" width=20>0</td>
   468         -<td align="center" width=20>1</td>
   469         -<td align="center" width=20>2</td>
   470         -<td align="center" width=20>3</td>
   471         -<td align="center" width=200>4 ... 1015</td>
   472         -</tr>
   473         -<tr>
   474         -<td align="center" colspan=2>Size</td>
   475         -<td align="center" colspan=2>Next</td>
   476         -<td align="center" colspan=1>Unused</td>
   477         -</tr>
   478         -</table>
   479         -</blockquote>
   480         -
   481         -<p>
   482         -Freeblocks are stored in a linked list in increasing order.  That is
   483         -to say, the first freeblock occurs at a lower index into the page than
   484         -the second free block, and so forth.  The first 2 bytes of the header
   485         -are an integer which is the total number of bytes in the freeblock.
   486         -The second 2 bytes are the index into the page of the next freeblock
   487         -in the list.  The last freeblock has a Next value of 0.
   488         -</p>
   489         -
   490         -<p>
   491         -When a new b-tree is created in a database, the root page of the b-tree
   492         -consist of a header and a single 1016 byte freeblock.  As entries are
   493         -added, space is carved off of that freeblock and used to make cells.
   494         -When b-tree entries are deleted, the space used by their cells is converted
   495         -into freeblocks.  Adjacent freeblocks are merged, but the page can still
   496         -become fragmented.  The b-tree code will occasionally try to defragment
   497         -the page by moving all cells to the beginning and constructing a single
   498         -freeblock at the end to take up all remaining space.
   499         -</p>
   500         -
   501         -<h4>3.3 &nbsp; The B-Tree Free Page List</h4>
   502         -
   503         -<p>
   504         -When information is removed from an SQLite database such that one or
   505         -more pages are no longer needed, those pages are added to a list of
   506         -free pages so that they can be reused later when new information is
   507         -added.  This subsection describes the structure of this freelist.
   508         -</p>
   509         -
   510         -<p>
   511         -The 32-bit integer beginning at byte-offset 52 in page 1 of the database
   512         -contains the address of the first page in a linked list of free pages.
   513         -If there are no free pages available, this integer has a value of 0.
   514         -The 32-bit integer at byte-offset 56 in page 1 contains the number of
   515         -free pages on the freelist.
   516         -</p>
   517         -
   518         -<p>
   519         -The freelist contains a trunk and many branches.  The trunk of
   520         -the freelist is composed of overflow pages.  That is to say, each page
   521         -contains a single 32-bit integer at byte offset 0 which
   522         -is the page number of the next page on the freelist trunk.
   523         -The payload area
   524         -of each trunk page is used to record pointers to branch pages. 
   525         -The first 32-bit integer in the payload area of a trunk page
   526         -is the number of branch pages to follow (between 0 and 254)
   527         -and each subsequent 32-bit integer is a page number for a branch page.
   528         -The following diagram shows the structure of a trunk freelist page:
   529         -</p>
   530         -
   531         -<blockquote>
   532         -<table border=1 cellspacing=0 cellpadding=5>
   533         -<tr>
   534         -<td align="center" width=20>0</td>
   535         -<td align="center" width=20>1</td>
   536         -<td align="center" width=20>2</td>
   537         -<td align="center" width=20>3</td>
   538         -<td align="center" width=20>4</td>
   539         -<td align="center" width=20>5</td>
   540         -<td align="center" width=20>6</td>
   541         -<td align="center" width=20>7</td>
   542         -<td align="center" width=200>8 ... 1023</td>
   543         -</tr>
   544         -<tr>
   545         -<td align="center" colspan=4>Next trunk page</td>
   546         -<td align="center" colspan=4># of branch pages</td>
   547         -<td align="center" colspan=1>Page numbers for branch pages</td>
   548         -</tr>
   549         -</table>
   550         -</blockquote>
   551         -
   552         -<p>
   553         -It is important to note that only the pages on the trunk of the freelist
   554         -contain pointers to other pages.  The branch pages contain no
   555         -data whatsoever.  The fact that the branch pages are completely
   556         -blank allows for an important optimization in the paging layer.  When
   557         -a branch page is removed from the freelist to be reused, it is not
   558         -necessary to write the original content of that page into the rollback
   559         -journal.  The branch page contained no data to begin with, so there is
   560         -no need to restore the page in the event of a rollback.  Similarly,
   561         -when a page is not longer needed and is added to the freelist as a branch
   562         -page, it is not necessary to write the content of that page
   563         -into the database file.
   564         -Again, the page contains no real data so it is not necessary to record the
   565         -content of that page.  By reducing the amount of disk I/O required,
   566         -these two optimizations allow some database operations
   567         -to go four to six times faster than they would otherwise.
   568         -</p>
   569         -
   570         -<h3>4.0 &nbsp; The Schema Layer</h3>
   571         -
   572         -<p>
   573         -The schema layer implements an SQL database on top of one or more
   574         -b-trees and keeps track of the root page numbers for all b-trees.
   575         -Where the b-tree layer provides only unformatted data storage with
   576         -a unique key, the schema layer allows each entry to contain multiple
   577         -columns.  The schema layer also allows indices and non-unique key values.
   578         -</p>
   579         -
   580         -<p>
   581         -The schema layer implements two separate data storage abstractions:
   582         -tables and indices.  Each table and each index uses its own b-tree
   583         -but they use the b-tree capabilities in different ways.  For a table,
   584         -the b-tree key is a unique 4-byte integer and the b-tree data is the
   585         -content of the table row, encoded so that columns can be separately
   586         -extracted.  For indices, the b-tree key varies in size depending on the
   587         -size of the fields being indexed and the b-tree data is empty.
   588         -</p>
   589         -
   590         -<h4>4.1 &nbsp; SQL Table Implementation Details</h4>
   591         -
   592         -<p>Each row of an SQL table is stored in a single b-tree entry.
   593         -The b-tree key is a 4-byte big-endian integer that is the ROWID
   594         -or INTEGER PRIMARY KEY for that table row.
   595         -The key is stored in a big-endian format so
   596         -that keys will sort in numerical order using memcmp() function.</p>
   597         -
   598         -<p>The content of a table row is stored in the data portion of
   599         -the corresponding b-tree table.  The content is encoded to allow
   600         -individual columns of the row to be extracted as necessary.  Assuming
   601         -that the table has N columns, the content is encoded as N+1 offsets
   602         -followed by N column values, as follows:
   603         -</p>
   604         -
   605         -<blockquote>
   606         -<table border=1 cellspacing=0 cellpadding=5>
   607         -<tr>
   608         -<td>offset 0</td>
   609         -<td>offset 1</td>
   610         -<td><b>...</b></td>
   611         -<td>offset N-1</td>
   612         -<td>offset N</td>
   613         -<td>value 0</td>
   614         -<td>value 1</td>
   615         -<td><b>...</b></td>
   616         -<td>value N-1</td>
   617         -</tr>
   618         -</table>
   619         -</blockquote>
   620         -
   621         -<p>
   622         -The offsets can be either 8-bit, 16-bit, or 24-bit integers depending
   623         -on how much data is to be stored.  If the total size of the content
   624         -is less than 256 bytes then 8-bit offsets are used.  If the total size
   625         -of the b-tree data is less than 65536 then 16-bit offsets are used.
   626         -24-bit offsets are used otherwise.  Offsets are always little-endian,
   627         -which means that the least significant byte occurs first.
   628         -</p>
   629         -
   630         -<p>
   631         -Data is stored as a nul-terminated string.  Any empty string consists
   632         -of just the nul terminator.  A NULL value is an empty string with no
   633         -nul-terminator.  Thus a NULL value occupies zero bytes and an empty string
   634         -occupies 1 byte.
   635         -</p>
   636         -
   637         -<p>
   638         -Column values are stored in the order that they appear in the CREATE TABLE
   639         -statement.  The offsets at the beginning of the record contain the
   640         -byte index of the corresponding column value.  Thus, Offset 0 contains
   641         -the byte index for Value 0, Offset 1 contains the byte offset
   642         -of Value 1, and so forth.  The number of bytes in a column value can
   643         -always be found by subtracting offsets.  This allows NULLs to be
   644         -recovered from the record unambiguously.
   645         -</p>
   646         -
   647         -<p>
   648         -Most columns are stored in the b-tree data as described above.
   649         -The one exception is column that has type INTEGER PRIMARY KEY.
   650         -INTEGER PRIMARY KEY columns correspond to the 4-byte b-tree key.
   651         -When an SQL statement attempts to read the INTEGER PRIMARY KEY,
   652         -the 4-byte b-tree key is read rather than information out of the
   653         -b-tree data.  But there is still an Offset associated with the
   654         -INTEGER PRIMARY KEY, just like any other column.  But the Value
   655         -associated with that offset is always NULL.
   656         -</p>
   657         -
   658         -<h4>4.2 &nbsp; SQL Index Implementation Details</h4>
   659         -
   660         -<p>
   661         -SQL indices are implement using a b-tree in which the key is used
   662         -but the data is always empty.  The purpose of an index is to map
   663         -one or more column values into the ROWID for the table entry that
   664         -contains those column values.
   665         -</p>
   666         -
   667         -<p>
   668         -Each b-tree in an index consists of one or more column values followed
   669         -by a 4-byte ROWID.  Each column value is nul-terminated (even NULL values)
   670         -and begins with a single character that indicates the datatype for that
   671         -column value.  Only three datatypes are supported: NULL, Number, and
   672         -Text.  NULL values are encoded as the character 'a' followed by the
   673         -nul terminator.  Numbers are encoded as the character 'b' followed by
   674         -a string that has been crafted so that sorting the string using memcmp()
   675         -will sort the corresponding numbers in numerical order.  (See the
   676         -sqliteRealToSortable() function in util.c of the SQLite sources for
   677         -additional information on this encoding.)  Numbers are also nul-terminated.
   678         -Text values consists of the character 'c' followed by a copy of the
   679         -text string and a nul-terminator.  These encoding rules result in
   680         -NULLs being sorted first, followed by numerical values in numerical
   681         -order, followed by text values in lexicographical order.
   682         -</p>
   683         -
   684         -<h4>4.4 &nbsp; SQL Schema Storage And Root B-Tree Page Numbers</h4>
   685         -
   686         -<p>
   687         -The database schema is stored in the database in a special tabled named
   688         -"sqlite_master" and which always has a root b-tree page number of 2.
   689         -This table contains the original CREATE TABLE,
   690         -CREATE INDEX, CREATE VIEW, and CREATE TRIGGER statements used to define
   691         -the database to begin with.  Whenever an SQLite database is opened,
   692         -the sqlite_master table is scanned from beginning to end and 
   693         -all the original CREATE statements are played back through the parser
   694         -in order to reconstruct an in-memory representation of the database
   695         -schema for use in subsequent command parsing.  For each CREATE TABLE
   696         -and CREATE INDEX statement, the root page number for the corresponding
   697         -b-tree is also recorded in the sqlite_master table so that SQLite will
   698         -know where to look for the appropriate b-tree.
   699         -</p>
   700         -
   701         -<p>
   702         -SQLite users can query the sqlite_master table just like any other table
   703         -in the database.  But the sqlite_master table cannot be directly written.
   704         -The sqlite_master table is automatically updated in response to CREATE
   705         -and DROP statements but it cannot be changed using INSERT, UPDATE, or
   706         -DELETE statements as that would risk corrupting the database.
   707         -</p>
   708         -
   709         -<p>
   710         -SQLite stores temporary tables and indices in a separate
   711         -file from the main database file.  The temporary table database file
   712         -is the same structure as the main database file.  The schema table
   713         -for the temporary tables is stored on page 2 just as in the main
   714         -database.  But the schema table for the temporary database named
   715         -"sqlite_temp_master" instead of "sqlite_master".  Other than the
   716         -name change, it works exactly the same.
   717         -</p>
   718         -
   719         -<h4>4.4 &nbsp; Schema Version Numbering And Other Meta-Information</h4>
   720         -
   721         -<p>
   722         -The nine 32-bit integers that are stored beginning at byte offset
   723         -60 of Page 1 in the b-tree layer are passed up into the schema layer
   724         -and used for versioning and configuration information.  The meaning
   725         -of the first four integers is shown below.  The other five are currently
   726         -unused.
   727         -</p>
   728         -
   729         -<ol>
   730         -<li>The schema version number</li>
   731         -<li>The format version number</li>
   732         -<li>The recommended pager cache size</li>
   733         -<li>The safety level</li>
   734         -</ol>
   735         -
   736         -<p>
   737         -The first meta-value, the schema version number, is used to detect when
   738         -the schema of the database is changed by a CREATE or DROP statement.
   739         -Recall that when a database is first opened the sqlite_master table is
   740         -scanned and an internal representation of the tables, indices, views,
   741         -and triggers for the database is built in memory.  This internal
   742         -representation is used for all subsequent SQL command parsing and
   743         -execution.  But what if another process were to change the schema
   744         -by adding or removing a table, index, view, or trigger?  If the original
   745         -process were to continue using the old schema, it could potentially
   746         -corrupt the database by writing to a table that no longer exists.
   747         -To avoid this problem, the schema version number is changed whenever
   748         -a CREATE or DROP statement is executed.  Before each command is
   749         -executed, the current schema version number for the database file
   750         -is compared against the schema version number from when the sqlite_master
   751         -table was last read.  If those numbers are different, the internal
   752         -schema representation is erased and the sqlite_master table is reread
   753         -to reconstruct the internal schema representation.
   754         -(Calls to sqlite_exec() generally return SQLITE_SCHEMA when this happens.)
   755         -</p>
   756         -
   757         -<p>
   758         -The second meta-value is the schema format version number.  This
   759         -