SQLite

Check-in [508248e783]
Login

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

Overview
Comment:Improvements to the documentation of the return codes for sqlite3_step(). Tickets #1633, #1366, #1178, #906, and probably others too. (CVS 3395)
Downloads: Tarball | ZIP archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 508248e783dc1e3da3695b28467ca3b79629e582
User & Date: drh 2006-09-08 11:56:30.000
Context
2006-09-08
12:27
Bug fix in date/time computations. Ticket #1964. Some unrelated comment typos are also fixed and got accidently checked in at the same time. (CVS 3396) (check-in: c81eaa0dc9 user: drh tags: trunk)
11:56
Improvements to the documentation of the return codes for sqlite3_step(). Tickets #1633, #1366, #1178, #906, and probably others too. (CVS 3395) (check-in: 508248e783 user: drh tags: trunk)
2006-09-06
21:39
Include io.h on Windows to quell a build warning about access() having no prototype. (CVS 3394) (check-in: b3eb1732bd user: adamd tags: trunk)
Changes
Unified Diff Ignore Whitespace Patch
Changes to www/capi3ref.tcl.
1
2
3
4
5
6
7
8
set rcsid {$Id: capi3ref.tcl,v 1.43 2006/08/24 15:18:25 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}} {
|







1
2
3
4
5
6
7
8
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}} {
1275
1276
1277
1278
1279
1280
1281



1282
1283
1284
1285
1286
1287































1288
1289
1290
1291
1292
1293
1294
 for processing by the caller. The values may be accessed using
 the sqlite3_column_*() functions. sqlite3_step()
 is called again to retrieve the next row of data.
 
 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().




 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.































}

api {} {
void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);
} {
 Register a function that is called each time an SQL statement is evaluated.
 The callback function is invoked on the first call to sqlite3_step() after







>
>
>






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







1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
 for processing by the caller. The values may be accessed using
 the sqlite3_column_*() functions. sqlite3_step()
 is called again to retrieve the next row of data.
 
 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 {} {
void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);
} {
 Register a function that is called each time an SQL statement is evaluated.
 The callback function is invoked on the first call to sqlite3_step() after