From: drh Date: Fri, 15 Sep 2006 16:58:48 +0000 (+0000) Subject: Add documentation for the sqlite3_extended_result_codes() API. (CVS 3425) X-Git-Tag: version-3.6.10~2742 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=572d11dc8f235a07f51f437ade813957b11f7bbb;p=thirdparty%2Fsqlite.git Add documentation for the sqlite3_extended_result_codes() API. (CVS 3425) FossilOrigin-Name: a6b3f6bed209dc27d36cd4e159159f73266e9911 --- diff --git a/manifest b/manifest index 61253a5093..0f884772a7 100644 --- 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 db03962864..e6133445b8 100644 --- 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 cb6ae67492..727efa0718 100644 --- 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 "" 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] "

\n\n

" d3 puts "

$d3

" }