Improvements to the documentation of the return codes for sqlite3_step().

Tickets #1633, #1366, #1178, #906, and probably others too. (CVS 3395)

FossilOrigin-Name: 508248e783dc1e3da3695b28467ca3b79629e582

diff --git a/manifest b/manifest
index 3dc55b8c2edf17188da47f647e48a83dbc016ebd..253e4df573cb54c8e2a8dae0893cf0db6f6436a0 100644 (file)
--- a/manifest
+++ b/manifest
@@ -1,5 +1,5 @@
-C Include\sio.h\son\sWindows\sto\squell\sa\sbuild\swarning\sabout\saccess()\shaving\sno\sprototype.\s(CVS\s3394)
-D 2006-09-06T21:39:40
+C Improvements\sto\sthe\sdocumentation\sof\sthe\sreturn\scodes\sfor\ssqlite3_step().\nTickets\s#1633,\s#1366,\s#1178,\s#906,\sand\sprobably\sothers\stoo.\s(CVS\s3395)
+D 2006-09-08T11:56:30
 F Makefile.in cabd42d34340f49260bc2a7668c38eba8d4cfd99
 F Makefile.linux-gcc 2d8574d1ba75f129aba2019f0b959db380a90935
 F README 9c4e2d6706bdcc3efdd773ce752a8cdab4f90028
@@ -352,7 +352,7 @@ F www/audit.tcl 90e09d580f79c7efec0c7d6f447b7ec5c2dce5c0
 F www/autoinc.tcl b357f5ba954b046ee35392ce0f884a2fcfcdea06
 F www/c_interface.tcl b51b08591554c16a0c3ef718364a508ac25abc7e
 F www/capi3.tcl 7a7cc225fe02eb7ab861a6019b08baa0014409e1
-F www/capi3ref.tcl 3df3e9703aca711dcdbe6de94bd93456abf75078
+F www/capi3ref.tcl 30511c41832e299cb598b9645b1a0ff5378d8b1d
 F www/changes.tcl 7bbcf947aa71d4760cbd286ba176466e729c974f
 F www/common.tcl 14d121c28532ad20c3e349caa4db708b0b822083
 F www/compile.tcl 276546d7eb445add5a867193bbd80f6919a6b084
@@ -396,7 +396,7 @@ F www/tclsqlite.tcl bb0d1357328a42b1993d78573e587c6dcbc964b9
 F www/vdbe.tcl 87a31ace769f20d3627a64fa1fade7fed47b90d0
 F www/version3.tcl 890248cf7b70e60c383b0e84d77d5132b3ead42b
 F www/whentouse.tcl 97e2b5cd296f7d8057e11f44427dea8a4c2db513
-P 55a03b96251515a4817a0eefb197219a460640e7
-R 6e16a3f89d647bcc85e29d207220a908
-U adamd
-Z 21a30daa992edd6252c2ee677fe7df56
+P b3eb1732bd529b14bef1872171a3c6429e209d31
+R e34c4ab5b751389f6c05ea187f495fb0
+U drh
+Z f62f8cbf6340cbbbc58aed5f40a05996

diff --git a/manifest.uuid b/manifest.uuid
index 7c8db8f73de582d6016baf1594f645d59b67d810..3e0f4446098c66f9e5d558bb37e3925062fd5b37 100644 (file)
--- a/manifest.uuid
+++ b/manifest.uuid
@@ -1 +1 @@
-b3eb1732bd529b14bef1872171a3c6429e209d31
\ No newline at end of file
+508248e783dc1e3da3695b28467ca3b79629e582
\ No newline at end of file

diff --git a/www/capi3ref.tcl b/www/capi3ref.tcl
index 2d6661f5672dce2262b4f22df3d07a5b308ecf62..cb6ae6749290038aaebfeb27d76d6fd1b53e6ee9 100644 (file)
--- a/www/capi3ref.tcl
+++ b/www/capi3ref.tcl
@@ -1,4 +1,4 @@
-set rcsid {$Id: capi3ref.tcl,v 1.43 2006/08/24 15:18:25 drh Exp $}
+set rcsid {$Id: capi3ref.tcl,v 1.44 2006/09/08 11:56:30 drh Exp $}
 source common.tcl
 header {C/C++ Interface For SQLite Version 3}
 puts {
@@ -1279,12 +1279,46 @@ int sqlite3_step(sqlite3_stmt*);
  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.
 
  SQLITE_MISUSE means that the this routine was called inappropriately.
  Perhaps it was called on a virtual machine that had already been
  finalized or on one that had previously returned SQLITE_ERROR or
  SQLITE_DONE.  Or it could be the case that a database connection
  is being used by a different thread than the one it was created it.
+
+ <b>Goofy Interface Alert:</b>
+ The sqlite3_step() API always returns a generic error code,
+ SQLITE_ERROR, following any error other than SQLITE_BUSY and SQLITE_MISUSE.
+ You must call sqlite3_reset() (or sqlite3_finalize()) in order to find
+ the specific error code that better describes the error.  We admit that
+ this is a goofy design.  Sqlite3_step() would be much easier to use if
+ it returned the specific error code directly.  But we cannot change that
+ now without breaking backwards compatibility.
+
+ Note that there is never any harm in calling sqlite3_reset() after
+ getting back an SQLITE_ERROR from sqlite3_step().  Any API that can
+ be used after an sqlite3_step() can also be used after sqlite3_reset().
+ You may want to create a simple wrapper around sqlite3_step() to make
+ this easier.  For example:
+
+ <blockquote><pre>
+    int less_goofy_sqlite3_step(sqlite3_stmt *pStatement){
+      int rc;
+      rc = sqlite3_step(pStatement);
+      if( rc==SQLITE_ERROR ){
+        rc = sqlite3_reset(pStatement);
+      }
+      return rc;
+    }
+ </pre></blockquote>
+
+ Simply substitute the less_goofy_sqlite3_step() call above for 
+ the normal sqlite3_step() everywhere in your code, and you will
+ always get back the specific error code rather than a generic
+ SQLITE_ERROR error code.
 }
 
 api {} {