I've been using the sqlite Tcl API for about 3 million years, with much delight. I'm venturing now into the C API -- hoping to put sqlite into a large monolithic "always on" C++ daemon. I would like to use the API in a way perfectly in line with how the authors intended.
But it's sort of hard to figure out exactly what the authors intended in some cases. Consider the man page for sqlite3_step() (http://sqlite.org/c3ref/step.html ): "With the "v2" interface, any of the other result codes <http://sqlite.org/c3ref/c_abort.html> or extended result codes <http://sqlite.org/c3ref/c_abort_rollback.html> might be returned as well.... SQLITE_ERROR <http://sqlite.org/c3ref/c_abort.html> 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() <http://sqlite.org/c3ref/errcode.html>. With the legacy interface, a more specific error code (for example, SQLITE_INTERRUPT <http://sqlite.org/c3ref/c_abort.html>, SQLITE_SCHEMA <http://sqlite.org/c3ref/c_abort.html>, SQLITE_CORRUPT <http://sqlite.org/c3ref/c_abort.html>, and so forth) can be obtained by calling sqlite3_reset() <http://sqlite.org/c3ref/reset.html> on the prepared statement <http://sqlite.org/c3ref/stmt.html>. In the "v2" interface, the more specific error code is returned directly by sqlite3_step()." I am a big fan generally of the clarity of the sqlite docs. But this page could use another section detailing all the possible result codes' specific semantics under sqlite3_step(), and in particular what the client should do in those circumstances. Similar to how your normal linux system call man page details such things. The page bites a bit of that off, as you see above. But consider e.g. (from http://sqlite.org/c3ref/c_abort.html): #define SQLITE_NOTICE 27 /* Notifications from sqlite3_log() */ Am I supposed to look for that? What am I supposed to do with it if I get it? How about SQLITE_CANTOPEN? Seems like that shouldn't be a possibility by the time we hit sqlite3_step(), but the docs are silent on the matter. So what am I to do? If I get SQLITE_IOERR, is that always permanent, or do I need to look for things like SQLITE_IOERR_LOCK and if that bit is set then rollback and retry? sqlite3_exec() has the same issue: it's hard to say from reading the docs exactly which of the error codes might be returned, and what the caller should do in those cases. sqlite3_prepare_v2() again has the same issue: "On success, the sqlite3_prepare() family of routines return SQLITE_OK <http://sqlite.org/c3ref/c_abort.html>; otherwise an error code <http://sqlite.org/c3ref/c_abort.html> is returned." Again, can *any* of those error codes be returned? Which of them is permanent and which are temporary in the case of prepare_v2()? And so on. Apologies if I have missed some of the docs. Any pointers, or especially example C code that the SQLite devs consider perfectly robust and complete API usage, are much appreciated. Eric _______________________________________________ sqlite-users mailing list sqlite-users@sqlite.org http://sqlite.org:8080/cgi-bin/mailman/listinfo/sqlite-users
