SQlite database C programming interface (VI) Result Codes and Error Codes by QQ: 253786989 2012-02-07

Standard Codes
Here are the standard return values and error code definitions:

#define SQLITE_OK           0   /* Successful result */
/* beginning-of-error-codes */
#define SQLITE_ERROR        1   /* SQL error or missing database */
#define SQLITE_INTERNAL     2   /* Internal logic error in SQLite */
#define SQLITE_PERM         3   /* Access permission denied */
#define SQLITE_ABORT        4   /* Callback routine requested an abort */
#define SQLITE_BUSY         5   /* The database file is locked */
#define SQLITE_LOCKED       6   /* A table in the database is locked */
#define SQLITE_NOMEM        7   /* A malloc() failed */
#define SQLITE_READONLY     8   /* Attempt to write a readonly database */
#define SQLITE_INTERRUPT    9   /* Operation terminated by sqlite3_interrupt()*/
#define SQLITE_IOERR       10   /* Some kind of disk I/O error occurred */
#define SQLITE_CORRUPT     11   /* The database disk image is malformed */
#define SQLITE_NOTFOUND    12   /* Unknown opcode in sqlite3_file_control() */
#define SQLITE_FULL        13   /* Insertion failed because database is full */
#define SQLITE_CANTOPEN    14   /* Unable to open the database file */
#define SQLITE_PROTOCOL    15   /* Database lock protocol error */
#define SQLITE_EMPTY       16   /* Database is empty */
#define SQLITE_SCHEMA      17   /* The database schema changed */
#define SQLITE_TOOBIG      18   /* String or BLOB exceeds size limit */
#define SQLITE_CONSTRAINT  19   /* Abort due to constraint violation */
#define SQLITE_MISMATCH    20   /* Data type mismatch */
#define SQLITE_MISUSE      21   /* Library used incorrectly */
#define SQLITE_NOLFS       22   /* Uses OS features not supported on host */
#define SQLITE_AUTH        23   /* Authorization denied */
#define SQLITE_FORMAT      24   /* Auxiliary database format error */
#define SQLITE_RANGE       25   /* 2nd parameter to sqlite3_bind out of range */
#define SQLITE_NOTADB      26   /* File opened that is not a database file */
#define SQLITE_ROW         100  /* sqlite3_step() has another row ready */
#define SQLITE_DONE        101  /* sqlite3_step() has finished executing */
/* end-of-error-codes */

Some of these constants are returned only by a specific function, such as the SQLITE_RANGE, which is returned only by the SQlite3_bind_xxx function. Some constants, such as SQLITE_ERROR, only indicate that an error occurred during the execution of the function, but there is no way to know why the error occurred.
Sqlite_false stands for MISUSE of apis. For example, a bind function returns SQlite_ern when a statement is given another parameter after the sqlite3_step function has executed without being reset.
Extended Codes
Standard error codes provide less information about the cause of the error. So sometimes we use extended error codes. The extended error code is based on the standard error code, whose lower order byte is the original standard error code, and then attaches information to its higher order byte “or” to describe the details of the error.

int sqlite3_extended_result_codes(sqlite3*, int onoff);

The error codes for these extensions are not enabled by default due to compatibility issues with the client’s legacy programs. Programmers can enable or disable extended error codes by using the SQlite3_extended_result_CODES function.
Here are all the extended error codes (most of which describe SQLITE_IOERR) :

#define SQLITE_IOERR_READ              (SQLITE_IOERR | (1<<8))
#define SQLITE_IOERR_SHORT_READ        (SQLITE_IOERR | (2<<8))
#define SQLITE_IOERR_WRITE             (SQLITE_IOERR | (3<<8))
#define SQLITE_IOERR_FSYNC             (SQLITE_IOERR | (4<<8))
#define SQLITE_IOERR_DIR_FSYNC         (SQLITE_IOERR | (5<<8))
#define SQLITE_IOERR_TRUNCATE          (SQLITE_IOERR | (6<<8))
#define SQLITE_IOERR_FSTAT             (SQLITE_IOERR | (7<<8))
#define SQLITE_IOERR_UNLOCK            (SQLITE_IOERR | (8<<8))
#define SQLITE_IOERR_RDLOCK            (SQLITE_IOERR | (9<<8))
#define SQLITE_IOERR_DELETE            (SQLITE_IOERR | (10<<8))
#define SQLITE_IOERR_BLOCKED           (SQLITE_IOERR | (11<<8))
#define SQLITE_IOERR_NOMEM             (SQLITE_IOERR | (12<<8))
#define SQLITE_IOERR_ACCESS            (SQLITE_IOERR | (13<<8))
#define SQLITE_IOERR_CHECKRESERVEDLOCK (SQLITE_IOERR | (14<<8))
#define SQLITE_IOERR_LOCK              (SQLITE_IOERR | (15<<8))
#define SQLITE_IOERR_CLOSE             (SQLITE_IOERR | (16<<8))
#define SQLITE_IOERR_DIR_CLOSE         (SQLITE_IOERR | (17<<8))
#define SQLITE_IOERR_SHMOPEN           (SQLITE_IOERR | (18<<8))
#define SQLITE_IOERR_SHMSIZE           (SQLITE_IOERR | (19<<8))
#define SQLITE_IOERR_SHMLOCK           (SQLITE_IOERR | (20<<8))
#define SQLITE_IOERR_SHMMAP            (SQLITE_IOERR | (21<<8))
#define SQLITE_IOERR_SEEK              (SQLITE_IOERR | (22<<8))
#define SQLITE_LOCKED_SHAREDCACHE      (SQLITE_LOCKED |  (1<<8))
#define SQLITE_BUSY_RECOVERY           (SQLITE_BUSY   |  (1<<8))
#define SQLITE_CANTOPEN_NOTEMPDIR      (SQLITE_CANTOPEN | (1<<8))
#define SQLITE_CORRUPT_VTAB            (SQLITE_CORRUPT | (1<<8))
#define SQLITE_READONLY_RECOVERY       (SQLITE_READONLY | (1<<8))
#define SQLITE_READONLY_CANTLOCK       (SQLITE_READONLY | (2<<8))

Error Functions

int sqlite3_extended_result_codes(sqlite3*, int onoff);

Enable or disable the use of extended error codes for a database connection. Enable extended error codes by passing a non-zero value to the second parameter of the SQlite3_extended_result_CODES function. This function always returns SQLITE_OK, and there is no way to get an extension error code that is currently enabled or off.

int sqlite3_errcode(sqlite3 *db);

If a database function operation does not return SQLITE_OK, you can then call the function to get the error code. By default it returns the standard error code, and it may also return an extended error code if the current database connection is enabled.

int sqlite3_extended_errcode(sqlite3 *db);

Similar to the SQlite3_errcode function, except that it only returns the extended error code.

const char *sqlite3_errmsg(sqlite3*);
const void *sqlite3_errmsg16(sqlite3*);

Returns an error code string, encoded in UTF-8 or UTF-16. Programmers should either call these functions, get the error code information, or make a copy. The next database operation may invalidate the returned string pointer.
SQlite error handling cannot handle multiple errors simultaneously. For example, if an API function call goes awrong and the programmer fails to check for that error, the next API function call may well return SQlite_ern, indicating that the program is trying to use an invalid data structure. So programmers should check and handle any errors that might occur after each API function call.
In addition, if multiple threads share the same database connection, it is best to encapsulate the core API calls and error-handling code in the Critical section. Programmers can use the SQlite3_db_mutex function to get the mutex pointer to the database connection (a pointer to the SQlite3_mutex object).
Prepare for V2 Version
The following table compares the prepare function of the original version with that of v2 version:

The V2 version of prepare is more concise for error handling and has the schema advantages listed in the table above, so it is recommended to use the V2 version of prepare.
Transactions and Errors
Typically, SQlite operations are in auto-commit mode. SQlite automatically encapsulates each SQL command into a transaction. Error recovery is easy if each statement is encapsulated in its own transaction. Any time SQLite finds itself in the wrong state, it simply rolls back the current transaction. This effectively cancels the current SQL command and returns the database to the state it was in before the error occurred.
However, once the BEGIN TRANSACTION command is executed, SQlite is no longer in autocommit mode. A TRANSACTION is opened and will remain open until either the END TRANSACTION or the COMMIT TRANSACTION command is executed. This allows multiple SQL commands to be encapsulated into a single transaction, allowing a discrete set of commands to execute either all or none (atomic operations), but it also limits SQLite’s error recovery.
When a displayed (explicit) transaction encounters an error during execution, SQLite attempts to cancel the statement just executed. Unfortunately, this is not always possible. If things go badly, SOMETIMES SQlite can just roll back the entire current transaction, with no other option.
The most likely errors to cause a rollback are SQLITE_FULL (database or disk space is full), SQLITE_IOERR (disk IO error or file is locked), SQLITE_BUSY (database lock), SQLITE_NOMEM (out of memory), SQLITE_INTERRUPT (interrupt). If the program is executing a display transaction and receives one of these errors, be prepared to handle the possibility of a transaction being rolled back.

int sqlite3_get_autocommit(sqlite3*);

With this function, you can get the current commit status. If a non-zero value is returned, the database is in auto-commit (atutoconmit) mode. If 0 is returned, the database is currently inside an explicit transaction.
If the SQlite database is forced to do a full transaction rollback, the database will once again go into transaction autocommit mode. If the database is not in auto-commit mode, it must be in a transaction, indicating that no rollback is required.

SQlite database C programming interface (VI) Result Codes and Error Codes by QQ: 253786989 2012-02-07