SQLite

3.3.9

set rcsid {$Id: capi3ref.tcl,v 1.47 2007/01/04 16:37:41 drh Exp $}
source common.tcl
header {C/C++ Interface For SQLite Version 3}
puts {
<h2>C/C++ Interface For SQLite Version 3</h2>
}

proc api {name prototype desc {notused x}} {

int sqlite3_prepare16_v2(
  sqlite3 *db,            /* Database handle */
  const void *zSql,       /* SQL statement, UTF-16 encoded */
  int nBytes,             /* Length of zSql in bytes. */
  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  const void **pzTail     /* OUT: Pointer to unused portion of zSql */
);

/* Legacy Interfaces */
int sqlite3_prepare(
  sqlite3 *db,            /* Database handle */
  const char *zSql,       /* SQL statement, UTF-8 encoded */
  int nBytes,             /* Length of zSql in bytes. */
  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  const char **pzTail     /* OUT: Pointer to unused portion of zSql */
);
int sqlite3_prepare16(
  sqlite3 *db,            /* Database handle */
  const void *zSql,       /* SQL statement, UTF-16 encoded */
  int nBytes,             /* Length of zSql in bytes. */
  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  const void **pzTail     /* OUT: Pointer to unused portion of zSql */
);
} {
 To execute an SQL query, it must first be compiled into a byte-code
 program using one of these routines. 

 The first argument "db" is an SQLite database handle. The second
 argument "zSql" is the statement to be compiled, encoded as either
 UTF-8 or UTF-16.  The sqlite3_prepare_v2()
 interfaces uses UTF-8 and sqlite3_prepare16_v2()
 use UTF-16. If the next argument, "nBytes", is less
 than zero, then zSql is read up to the first nul terminator.  If
 "nBytes" is not less than zero, then it is the length of the string zSql
 in bytes (not characters).

 *pzTail is made to point to the first byte past the end of the first
 SQL statement in zSql.  This routine only compiles the first statement
 in zSql, so *pzTail is left pointing to what remains uncompiled.

 *ppStmt is left pointing to a compiled SQL statement that can be
 executed using sqlite3_step().  Or if there is an error, *ppStmt may be
 set to NULL.  If the input text contained no SQL (if the input is and
 empty string or a comment) then *ppStmt is set to NULL.  The calling
 procedure is responsible for deleting this compiled SQL statement
 using sqlite3_finalize() after it has finished with it.

 On success, SQLITE_OK is returned.  Otherwise an error code is returned.

 The sqlite3_prepare_v2() and sqlite3_prepare16_v2() interfaces are
 recommended for all new programs. The other two older interfaces are retained
 for backwards compatibility. In the "v2" interfaces, the prepared statement
 that is returned (the sqlite3_stmt object) contains a copy of the original
 SQL. This causes the sqlite3_step() interface to behave a little differently.
 If the database schema changes, instead of returning SQLITE_SCHEMA as it
 always used to do, sqlite3_step() will automatically recompile the SQL
 statement and try to run it again. Only after 5 consecutive failures will
 an SQLITE_SCHEMA failure be reported back. The other change is that

}

api {} {
int sqlite3_reset(sqlite3_stmt *pStmt);
} {
 The sqlite3_reset() function is called to reset a prepared SQL
 statement obtained by a previous call to 
 sqlite3_prepare_v2() or
 sqlite3_prepare16_v2() back to it's initial state, ready to be re-executed.
 Any SQL statement variables that had values bound to them using
 the sqlite3_bind_*() API retain their values.
}

api {} {
void sqlite3_result_blob(sqlite3_context*, const void*, int n, void(*)(void*));

 or to deny access to certain tables or columns within the database.
}

api {} {
int sqlite3_step(sqlite3_stmt*);
} {
 After an SQL query has been prepared with a call to either
 sqlite3_prepare_v2() or sqlite3_prepare16_v2() or to one of
 the legacy interfaces sqlite3_prepare() or sqlite3_prepare16(),
 then this function must be
 called one or more times to execute the statement.

 The details of the behavior of this sqlite3_step() interface depend
 on whether the statement was prepared using the newer "v2" interface
 sqlite3_prepare_v2() and sqlite3_prepare16_v2() or the older legacy
 interface sqlite3_prepare() and sqlite3_prepare16().  The use of the
 new "v2" interface is recommended for new applications but the legacy

 successfully.  sqlite3_step() should not be called again on this virtual
 machine without first calling sqlite3_reset() to reset the virtual
 machine back to its initial state.

 If the SQL statement being executed returns any data, then 
 SQLITE_ROW is returned each time a new row of data is ready
 for processing by the caller. The values may be accessed using
 the sqlite3_column_int(), sqlite3_column_text(), and similar functions.
 sqlite3_step() is called again to retrieve the next row of data.
 
 SQLITE_ERROR means that a run-time error (such as a constraint
 violation) has occurred.  sqlite3_step() should not be called again on
 the VM. More information may be found by calling sqlite3_errmsg().
 A more specific error code (example: SQLITE_INTERRUPT, SQLITE_SCHEMA,
 SQLITE_CORRUPT, and so forth) can be obtained by calling
 sqlite3_reset() on the prepared statement.  In the "v2" interface,

  if {[regexp {\(([0-9.]+)\)} $date all vers]} {
    set label [string map {. _} $vers]
    puts "<A NAME=\"version_$label\">"
  }
  puts "<DT><B>$date</B></DT>"
  puts "<DD><P><UL>$desc</UL></P></DD>"
}

chng {2007 January 4 (3.3.9)} {
<li>Fix bugs in pager.c that could lead to database corruption if two
processes both try to recover a hot journal at the same instant</li>
<li>Added the <a href="capi3ref.html#sqlite3_prepare_v2>sqlite3_prepare_v2()</a>
API.</li>
<li>Fixed the ".dump" command in the command-line shell to show
triggers and views again.</li>
<li>Change the table_info pragma so that it returns NULL for the default
value if there is no default value</li>
<li>Support for non-ASCII characters in win95 filenames</li>
<li>Query optimizer enhancements:
<ul>
<li>Optimizer does a better job of using indices to satisfy ORDER BY
clauses that sort on the integer primary key</li>
<li>Use an index to satisfy an IS NULL operator in the WHERE clause</li>
<li>Fix a bug that was causing the optimizer to miss an OR optimization
opportunity</li>
<li>The optimizer has more freedom to reorder tables in the FROM clause
even in there are LEFT joins.</li>
</ul>
<li>Extension loading supported added to winCE</li>
<li>Allow constrain names on the DEFAULT clause in a table definition</li>
<li>Added the ".bail" command to the command-line shell</li>
<li>Make CVS (comma separate value) output from the command-line shell
more closely aligned to accepted practice</li>
<li>Experimental FTS2 module added</li>
<li>Use sqlite3_mprintf() instead of strdup() to avoid libc dependencies</li>
<li>VACUUM uses a temporary file in the official TEMP folder, not in the
same directory as the original database</li>
<li>The prefix on temporary filenames on windows is changed from "sqlite"
to "etilqs".</li>
}

chng {2006 October 9 (3.3.8)} {
<li>Support for full text search using the
<a href="http://www.sqlite.org/cvstrac/wiki?p=FullTextIndex">FTS1 module</a>
(beta)</li>
<li>Added OS-X locking patches (beta - disabled by default)</li>
<li>Introduce extended error codes and add error codes for various

    even after system crashes and power failures.
<li>Zero-configuration - no setup or administration needed.</li>
<li>Implements most of SQL92.
    (<a href="omitted.html">Features not supported</a>)</li>
<li>A complete database is stored in a single disk file.</li>
<li>Database files can be freely shared between machines with
    different byte orders.</li>
<li>Supports databases up to 2 tebibytes
    (2<sup><small>41</small></sup> bytes) in size.</li>
<li>Strings and BLOBs up to 2 gibibytes (2<sup><small>31</small></sup> bytes)
    in size.</li>
<li>Small code footprint: less than 250KiB fully configured or less
    than 150KiB with optional features omitted.</li>
<li><a href="speed.html">Faster</a> than popular client/server database
    engines for most common operations.</li>
<li>Simple, easy to use <a href="capi3.html">API</a>.</li>
<li><a href="tclsqlite.html">TCL bindings</a> included.
    Bindings for many other languages 

proc newsitem {date title text} {
  puts "<h3>$date - $title</h3>"
  regsub -all "\n( *\n)+" $text "</p>\n\n<p>" txt
  puts "<p>$txt</p>"
  puts "<hr width=\"50%\">"
}

newsitem {2007-Jan-4} {Version 3.3.9} {
  Version 3.3.9 fixes bugs that can lead to database corruption under
  obsure and difficult to reproduce circumstances.  See
  <a href="http://www.sqlite.org/cvstrac/wiki?p=DatabaseCorruption">
  DatabaseCorruption</a> in the
  <a href="http://www.sqlite.org/cvstrac/wiki">wiki</a> for details.
  This release also add the new
  <a href="capi3ref.html#sqlite3_prepare_v2">sqlite3_prepare_v2()</a>
  API and includes important bug fixes in the command-line
  shell and enhancements to the query optimizer.  Upgrading is
  recommended.
}

newsitem {2006-Oct-9} {Version 3.3.8} {
  Version 3.3.8 adds support for full-text search using the 
  <a href="http://www.sqlite.org/cvstrac/wiki?p=FtsOne">FTS1
  module.</a>  There are also minor bug fixes.  Upgrade only if
  you want to try out the new full-text search capabilities or if
  you are having problems with 3.3.7.

  <a href="http://www.mikesclutter.com">Mike Owens</a>.
  is now available from <a href="http://www.apress.com">Apress</a>.
  The books covers the latest SQLite internals as well as
  the native C interface and bindings for PHP, Python,
  Perl, Ruby, Tcl, and Java.  Recommended.
}














puts {
<p align="right"><a href="oldnews.html">Old news...</a></p>
</td></tr></table>
}
footer {$Id: index.tcl,v 1.144 2007/01/04 16:37:41 drh Exp $}

#!/usr/bin/tclsh
source common.tcl
header {SQLite Older News}

proc newsitem {date title text} {
  puts "<h3>$date - $title</h3>"
  regsub -all "\n( *\n)+" $text "</p>\n\n<p>" txt
  puts "<p>$txt</p>"
  puts "<hr width=\"50%\">"
}


newsitem {2006-Jun-6} {Version 3.3.6} {
  Changes include improved tolerance for windows virus scanners
  and faster :memory: databases.  There are also fixes for several
  obscure bugs.  Upgrade if you are having problems.
}

newsitem {2006-Apr-5} {Version 3.3.5} {
  This release fixes many minor bugs and documentation typos and
  provides some minor new features and performance enhancements.
  Upgrade only if you are having problems or need one of the new features.
}

newsitem {2006-Feb-11} {Version 3.3.4} {
  This release fixes several bugs, including a 
  a blunder that might cause a deadlock on multithreaded systems.
  Anyone using SQLite in a multithreaded environment should probably upgrade.
}

  changes to both the C-language API and the underlying file format
  that will enable SQLite to better support internationalization.
  The first beta is schedule for release on 2004-July-01.

  Plans are to continue to support SQLite version 2.8 with
  bug fixes.  But all new development will occur in version 3.0.
}
footer {$Id: oldnews.tcl,v 1.17 2007/01/04 16:37:41 drh Exp $}