/ Check-in [a6b3f6be]
Login
SQLite training in Houston TX on 2019-11-05 (details)
Part of the 2019 Tcl Conference

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Add documentation for the sqlite3_extended_result_codes() API. (CVS 3425)
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: a6b3f6bed209dc27d36cd4e159159f73266e9911
User & Date: drh 2006-09-15 16:58:49
Context
2006-09-16
21:45
Add the sqlite3_overload_function() API - part of the virtual table interface. (CVS 3426) check-in: aa7728f9 user: drh tags: trunk
2006-09-15
16:58
Add documentation for the sqlite3_extended_result_codes() API. (CVS 3425) check-in: a6b3f6be user: drh tags: trunk
16:09
Fix an initialization problem in FTS1. Ticket #1977. (CVS 3424) check-in: 5a18dd88 user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to www/capi3ref.tcl.

1
2
3
4
5
6
7
8
9
10
11
12
13


14
15
16










































17
18
19
20
21
22
23
..
41
42
43
44
45
46
47





















48
49
50
51
52
53
54
....
1646
1647
1648
1649
1650
1651
1652



1653
1654
1655
1656
1657
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 {
<h2>C/C++ Interface For SQLite Version 3</h2>
}

proc api {name prototype desc {notused x}} {
  global apilist
  if {$name==""} {
    regsub -all {sqlite3_[a-z0-9_]+\(} $prototype \
      {[lappend name [string trimright & (]]} x1
    subst $x1


  }
  lappend apilist [list $name $prototype $desc]
}











































api {result-codes} {
#define SQLITE_OK           0   /* Successful result */
#define SQLITE_ERROR        1   /* SQL error or missing database */
#define SQLITE_INTERNAL     2   /* An internal logic error in SQLite */
#define SQLITE_PERM         3   /* Access permission denied */
#define SQLITE_ABORT        4   /* Callback routine requested an abort */
................................................................................
#define SQLITE_NOLFS       22   /* Uses OS features not supported on host */
#define SQLITE_AUTH        23   /* Authorization denied */
#define SQLITE_ROW         100  /* sqlite_step() has another row ready */
#define SQLITE_DONE        101  /* sqlite_step() has finished executing */
} {
Many SQLite functions return an integer result code from the set shown
above in order to indicates success or failure.





















}

api {} {
  const char *sqlite3_libversion(void);
} {
  Return a pointer to a string which contains the version number of
  the library.  The same string is available in the global
................................................................................
  puts "<blockquote><pre>"
  regsub "^( *\n)+" $prototype {} p2
  regsub "(\n *)+\$" $p2 {} p3
  puts $p3
  puts "</pre></blockquote>"
  regsub -all {\[} $desc {\[} desc
  regsub -all {sqlite3_[a-z0-9_]+} $desc "\[resolve_name $name &\]" d2



  regsub -all "\n( *\n)+" [subst $d2] "</p>\n\n<p>" d3
  puts "<p>$d3</p>"
}

footer $rcsid
|







|




>
>



>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







 







>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







 







>
>
>





1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
..
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
....
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
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 {
<h2>C/C++ Interface For SQLite Version 3</h2>
}

proc api {name prototype desc {notused x}} {
  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 */
#define SQLITE_INTERNAL     2   /* An internal logic error in SQLite */
#define SQLITE_PERM         3   /* Access permission denied */
#define SQLITE_ABORT        4   /* Callback routine requested an abort */
................................................................................
#define SQLITE_NOLFS       22   /* Uses OS features not supported on host */
#define SQLITE_AUTH        23   /* Authorization denied */
#define SQLITE_ROW         100  /* sqlite_step() has another row ready */
#define SQLITE_DONE        101  /* sqlite_step() has finished executing */
} {
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 {} {
  const char *sqlite3_libversion(void);
} {
  Return a pointer to a string which contains the version number of
  the library.  The same string is available in the global
................................................................................
  puts "<blockquote><pre>"
  regsub "^( *\n)+" $prototype {} p2
  regsub "(\n *)+\$" $p2 {} p3
  puts $p3
  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>"
}

footer $rcsid