Add documentation for the sqlite3_extended_result_codes() API. (CVS 3425)

FossilOrigin-Name: a6b3f6bed209dc27d36cd4e159159f73266e9911

diff --git a/manifest b/manifest
index 61253a5093e56691aa43023d240560a435d75051..0f884772a770ccc4b30610f1308afa689f4fd060 100644 (file)
--- a/manifest
+++ b/manifest
@@ -1,5 +1,5 @@
-C Fix\san\sinitialization\sproblem\sin\sFTS1.\s\sTicket\s#1977.\s(CVS\s3424)
-D 2006-09-15T16:09:00
+C Add\sdocumentation\sfor\sthe\ssqlite3_extended_result_codes()\sAPI.\s(CVS\s3425)
+D 2006-09-15T16:58:49
 F Makefile.in cabd42d34340f49260bc2a7668c38eba8d4cfd99
 F Makefile.linux-gcc 2d8574d1ba75f129aba2019f0b959db380a90935
 F README 9c4e2d6706bdcc3efdd773ce752a8cdab4f90028
@@ -355,7 +355,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 30511c41832e299cb598b9645b1a0ff5378d8b1d
+F www/capi3ref.tcl 9a54c86c93b29e682417d6b2a038f0dc9e4f19fb
 F www/changes.tcl 7bbcf947aa71d4760cbd286ba176466e729c974f
 F www/common.tcl 14d121c28532ad20c3e349caa4db708b0b822083
 F www/compile.tcl 276546d7eb445add5a867193bbd80f6919a6b084
@@ -399,7 +399,7 @@ F www/tclsqlite.tcl bb0d1357328a42b1993d78573e587c6dcbc964b9
 F www/vdbe.tcl 87a31ace769f20d3627a64fa1fade7fed47b90d0
 F www/version3.tcl 890248cf7b70e60c383b0e84d77d5132b3ead42b
 F www/whentouse.tcl 97e2b5cd296f7d8057e11f44427dea8a4c2db513
-P 78ae74db1cbf605cd421e7ea321e879d3638968e
-R 0dedcde70866a12a23f0808cc8e8baad
+P 5a18dd88498ca35ca1333d88c4635868d0b61073
+R db2e22fec0c46956a77b6266569df6f6
 U drh
-Z 41df79c93a460e6fa69a8c835c60a380
+Z b17dc9813a2e708d175a29c8b1fb19be

diff --git a/manifest.uuid b/manifest.uuid
index db03962864951f7d56f4985e30c74e50598ee378..e6133445b8c1a5a51f88b3f799c27ceab79ebf78 100644 (file)
--- a/manifest.uuid
+++ b/manifest.uuid
@@ -1 +1 @@
-5a18dd88498ca35ca1333d88c4635868d0b61073
\ No newline at end of file
+a6b3f6bed209dc27d36cd4e159159f73266e9911
\ No newline at end of file

diff --git a/www/capi3ref.tcl b/www/capi3ref.tcl
index cb6ae6749290038aaebfeb27d76d6fd1b53e6ee9..727efa0718edc3f50aa60ebecd883833e02dc241 100644 (file)
--- a/www/capi3ref.tcl
+++ b/www/capi3ref.tcl
@@ -1,4 +1,4 @@
-set rcsid {$Id: capi3ref.tcl,v 1.44 2006/09/08 11:56:30 drh Exp $}
+set rcsid {$Id: capi3ref.tcl,v 1.45 2006/09/15 16:58:49 drh Exp $}
 source common.tcl
 header {C/C++ Interface For SQLite Version 3}
 puts {
@@ -6,15 +6,59 @@ puts {
 }
 
 proc api {name prototype desc {notused x}} {
-  global apilist
+  global apilist specialname
   if {$name==""} {
     regsub -all {sqlite3_[a-z0-9_]+\(} $prototype \
       {[lappend name [string trimright & (]]} x1
     subst $x1
+  } else {
+    lappend specialname $name
   }
   lappend apilist [list $name $prototype $desc]
 }
 
+api {extended-result-codes} {
+#define SQLITE_IOERR_READ       
+#define SQLITE_IOERR_SHORT_READ 
+#define SQLITE_IOERR_WRITE      
+#define SQLITE_IOERR_FSYNC      
+#define SQLITE_IOERR_DIR_FSYNC  
+#define SQLITE_IOERR_TRUNCATE   
+#define SQLITE_IOERR_FSTAT      
+#define SQLITE_IOERR_UNLOCK     
+#define SQLITE_IOERR_RDLOCK     
+...
+} {
+In its default configuration, SQLite API routines return one of 26 integer
+result codes described at result-codes.  However, experience has shown that
+many of these result codes are too course-grained.  They do not provide as
+much information about problems as users might like.  In an effort to
+address this, newer versions of SQLite (version 3.3.8 and later) include
+support for additional result codes that provide more detailed information
+about errors.  The extended result codes are enabled (or disabled) for 
+each database
+connection using the sqlite3_extended_result_codes() API.
+
+Some of the available extended result codes are listed above.
+We expect the number of extended result codes will be expand
+over time.  Software that uses extended result codes should expect
+to see new result codes in future releases of SQLite.
+
+The symbolic name for an extended result code always contains a related
+primary result code as a prefix.  Primary result codes contain a single
+"_" character.  Extended result codes contain two or more "_" characters.
+The numeric value of an extended result code can be converted to its
+corresponding primary result code by masking off the lower 8 bytes.
+
+A complete list of available extended result codes and
+details about the meaning of the various extended result codes can be
+found by consulting the C code, especially the sqlite3.h header
+file and its antecedent sqlite.h.in.  Additional information
+is also available at the SQLite wiki:
+http://www.sqlite.org/cvstrac/wiki?p=ExtendedResultCodes
+}
+
+
 api {result-codes} {
 #define SQLITE_OK           0   /* Successful result */
 #define SQLITE_ERROR        1   /* SQL error or missing database */
@@ -45,6 +89,27 @@ api {result-codes} {
 } {
 Many SQLite functions return an integer result code from the set shown
 above in order to indicates success or failure.
+
+The result codes above are the only ones returned by SQLite in its
+default configuration.  However, the sqlite3_extended_result_codes()
+API can be used to set a database connectoin to return more detailed
+result codes.  See the documentation on sqlite3_extended_result_codes()
+or extended-result-codes for additional information.
+}
+
+api {} {
+  int sqlite3_extended_result_codes(sqlite3*, int onoff);
+} {
+This routine enables or disabled extended-result-codes feature.
+By default, SQLite API routines return one of only 26 integer
+result codes described at result-codes.  When extended result codes
+are enabled by this routine, the repetoire of result codes can be
+much larger and can (hopefully) provide more detailed information
+about the cause of an error.
+
+The second argument is a boolean value that turns extended result
+codes on and off.  Extended result codes are off by default for
+backwards compatibility with older versions of SQLite.
 }
 
 api {} {
@@ -1650,6 +1715,9 @@ foreach name [lsort [array names name_to_idx]] {
   puts "</pre></blockquote>"
   regsub -all {\[} $desc {\[} desc
   regsub -all {sqlite3_[a-z0-9_]+} $desc "\[resolve_name $name &\]" d2
+  foreach x $specialname {
+    regsub -all $x $d2 "\[resolve_name $name &\]" d2
+  }
   regsub -all "\n( *\n)+" [subst $d2] "</p>\n\n<p>" d3
   puts "<p>$d3</p>"
 }