Update documentation to talk about the response to errors

within an explicit transaction. (CVS 4460)

FossilOrigin-Name: 84616a13af633700635ad2f91e92c2f7271e96d1

diff --git a/manifest b/manifest
index 7207c50d5f9560fb0ffd56c41ae4db0cfaec7cb9..b8f184e4f76fc0a604f7d666900c7809a3c1a3e3 100644 (file)
--- a/manifest
+++ b/manifest
@@ -1,5 +1,5 @@
-C Simplify\sthe\svdbeHalt\slogic\sslightly.\s(CVS\s4459)
-D 2007-10-03T18:45:04
+C Update\sdocumentation\sto\stalk\sabout\sthe\sresponse\sto\serrors\nwithin\san\sexplicit\stransaction.\s(CVS\s4460)
+D 2007-10-03T20:15:28
 F Makefile.in cbfb898945536a8f9ea8b897e1586dd1fdbcc5db
 F Makefile.linux-gcc 65241babba6faf1152bf86574477baab19190499
 F README 9c4e2d6706bdcc3efdd773ce752a8cdab4f90028
@@ -130,7 +130,7 @@ F src/random.c 4a22746501bf36b0a088c66e38dde5daba6a35da
 F src/select.c 4706a6115da1bdc09a2be5991168a6cc2c0df267
 F src/server.c 087b92a39d883e3fa113cae259d64e4c7438bc96
 F src/shell.c 82089379833e361ba8a2ae65316a2173785300c0
-F src/sqlite.h.in 28746e34b4ada1cecc49768844064d3f1c7fd78e
+F src/sqlite.h.in 0b8875192b9cea40cf4a5d1dfda2d0172a0bd4c4
 F src/sqlite3ext.h a93f59cdee3638dc0c9c086f80df743a4e68c3cb
 F src/sqliteInt.h 9092213f1ff14cd7edee8d0649d8a193dbbad4b2
 F src/sqliteLimit.h 1bcbbdfa856f8b71b561abb31edb864b0eca1d12
@@ -557,7 +557,7 @@ F www/fullscanb.gif f7c94cb227f060511f8909e10f570157263e9a25
 F www/index-ex1-x-b.gif f9b1d85c3fa2435cf38b15970c7e3aa1edae23a3
 F www/index.tcl 087ec69ed7e28658e750a9ed38161c7f8344414c
 F www/indirect1b1.gif adfca361d2df59e34f9c5cac52a670c2bfc303a1
-F www/lang.tcl a2ee1ee272ed456a4c65220b8844c8075cffb9ed
+F www/lang.tcl 1c1e7573dc5f93971f1533393f06e79e68d7e5e1
 F www/limits.tcl 9035eb73e814ccb298595fd57670dec817533616
 F www/lockingv3.tcl e52345bd20323bef6146bfce18ae0829b2b7c87d
 F www/mingw.tcl d96b451568c5d28545fefe0c80bee3431c73f69c
@@ -581,7 +581,7 @@ F www/tclsqlite.tcl 8be95ee6dba05eabcd27a9d91331c803f2ce2130
 F www/vdbe.tcl 87a31ace769f20d3627a64fa1fade7fed47b90d0
 F www/version3.tcl 890248cf7b70e60c383b0e84d77d5132b3ead42b
 F www/whentouse.tcl fc46eae081251c3c181bd79c5faef8195d7991a5
-P 0fb6d5a5773c282882e7283e6f8f8c009e238ff4
-R 8078f77f6e7647e7ac36c0ae1aed3ae9
+P b59f7bcbabcccde9d2519e10e65e121343f2af7a
+R 4be517af398fae656e77e864bc26db9f
 U drh
-Z b6a4257494f5195bec3aaf8c352cc04d
+Z 4fe93e57aa934c2ed2008402ceee10f2

diff --git a/manifest.uuid b/manifest.uuid
index afae7f9a699c42b7b7c1a4962b46ea7a1c725a5e..9c17ada8f20b53a89ccbb5349792bcd8b3b712ab 100644 (file)
--- a/manifest.uuid
+++ b/manifest.uuid
@@ -1 +1 @@
-b59f7bcbabcccde9d2519e10e65e121343f2af7a
\ No newline at end of file
+84616a13af633700635ad2f91e92c2f7271e96d1
\ No newline at end of file

diff --git a/src/sqlite.h.in b/src/sqlite.h.in
index 798b0b2274d4ed5e0f778751ee836c3719c3ec0e..7e28a56c812aa0cc0b3ba0db7a009632e3058625 100644 (file)
--- a/src/sqlite.h.in
+++ b/src/sqlite.h.in
@@ -30,7 +30,7 @@
 ** the version number) and changes its name to "sqlite3.h" as
 ** part of the build process.
 **
-** @(#) $Id: sqlite.h.in,v 1.265 2007/10/03 08:46:45 danielk1977 Exp $
+** @(#) $Id: sqlite.h.in,v 1.266 2007/10/03 20:15:28 drh Exp $
 */
 #ifndef _SQLITE3_H_
 #define _SQLITE3_H_
@@ -2674,6 +2674,13 @@ SQLITE_EXTERN char *sqlite3_temp_directory;
 ** by default.  Autocommit is disabled by a BEGIN statement and reenabled
 ** by the next COMMIT or ROLLBACK.
 **
+** If certain kinds of errors occur on a statement within a multi-statement
+** transactions (errors including [SQLITE_FULL], [SQLITE_IOERR], 
+** [SQLITE_NOMEM], [SQLITE_BUSY], and [SQLITE_INTERRUPT]) then the
+** transaction might be rolled back automatically.  The only way to
+** find out if SQLite automatically rolled back the transaction after
+** an error is to use this function.
+**
 ** If another thread changes the autocommit status of the database
 ** connection while this routine is running, then the return value
 ** is undefined.

diff --git a/www/lang.tcl b/www/lang.tcl
index 8c471e71b2fd31ecba6f67b797ba201fab3002af..1c8b1e7b956f2ded857f04aa2f331c3b1b800ee4 100644 (file)
--- a/www/lang.tcl
+++ b/www/lang.tcl
@@ -1,7 +1,7 @@
 #
 # Run this Tcl script to generate the lang-*.html files.
 #
-set rcsid {$Id: lang.tcl,v 1.135 2007/10/01 17:45:40 drh Exp $}
+set rcsid {$Id: lang.tcl,v 1.136 2007/10/03 20:15:28 drh Exp $}
 source common.tcl
 
 if {[llength $argv]>0} {
@@ -288,11 +288,6 @@ ROLLBACK [TRANSACTION [<name>]]
 }
 
 puts {
-<p>Beginning in version 2.0, SQLite supports transactions with
-rollback and atomic commit.</p>
-
-<p>The optional transaction name is ignored. SQLite currently 
-does not allow nested transactions.</p>
 
 <p>
 No changes can be made to the database except within a transaction.
@@ -317,9 +312,17 @@ conflict resolution algorithm.
 END TRANSACTION is an alias for COMMIT.
 </p>
 
+<p>The optional transaction name is current ignored. SQLite 
+does not recognize nested transactions at this time.
+However, future versions of SQLite may be enhanced to support nested
+transactions and the transaction name would then become significant.
+Application are advised not to use the transaction name in order
+to avoid future compatibility problems.</p>
+
 <p>
-In SQLite version 3.0.8 and later, transactions can be deferred,
-immediate, or exclusive.  Deferred means that no locks are acquired
+Transactions can be deferred, immediate, or exclusive.  
+The default transaction behavior is deferred.
+Deferred means that no locks are acquired
 on the database until the database is first accessed.  Thus with a
 deferred transaction, the BEGIN statement itself does nothing.  Locks
 are not acquired until the first read or write operation.  The first read
@@ -346,13 +349,6 @@ A description of the meaning of SHARED, RESERVED, and EXCLUSIVE locks
 is available <a href="lockingv3.html">separately</a>.
 </p>
 
-<p>
-The default behavior for SQLite version 3.0.8 is a
-deferred transaction.  For SQLite version 3.0.0 through 3.0.7,
-deferred is the only kind of transaction available.  For SQLite
-version 2.8 and earlier, all transactions are exclusive.
-</p>
-
 <p>
 The COMMIT command does not actually perform a commit until all
 pending SQL commands finish.  Thus if two or more SELECT statements
@@ -367,6 +363,43 @@ that prevented the database from being updated.  When COMMIT fails in this
 way, the transaction remains active and the COMMIT can be retried later
 after the reader has had a chance to clear.
 </p>
+
+<h3>Response To Errors Within A Transaction</h3>
+
+<p>If certain kinds of errors occur within a transaction, the
+transaction may or may not be rolled back automatically.  The
+errors that cause the behavior include:</p>
+
+<ul>
+<li> SQLITE_FULL: database or disk full
+<li> SQLITE_IOERR: disk I/O error
+<li> SQLITE_BUSY: database in use by another process
+<li> SQLITE_NOMEM: out or memory
+<li> SQLITE_INTERRUPT: processing interrupted by user request
+</ul>
+
+<p>
+For all of these errors, SQLite attempts to undo just the one statement
+it was working on and leave changes from prior statements within the
+same transaction intact and continue with the transaction.  However, 
+depending on the statement being evaluated and the point at which the
+error occurs, it might be necessary for SQLite to rollback and
+cancel the transaction.  An application can tell which
+course of action SQLite took by using the
+<a href="capi3ref.html#sqlite3_get_autocommit">sqlite3_get_autocommit()</a>
+C-language interface.</p>
+
+<p>It is recommended that applications respond to the errors
+listed above by explicitly issuing a ROLLBACK command.  If the 
+transaction has already been rolled back automatically
+by the error response, then the ROLLBACK command will fail with an
+error, but no harm is caused by this.</p>
+
+<p>Future versions of SQLite may extend the list of errors which
+might cause automatic transaction rollback.  Future versions of
+SQLite might change the error response.  In particular, we may
+choose to simplify the interface in future versions of SQLite by
+causing the errors above to force an unconditional rollback.</p>
 }