C Programming Interface of SQlite database (6) Return Value and Error code (Result Codes and Error Codes) -- Reading Notes of Using SQlite

C Programming Interface of SQlite database (6) Return Value and error code (Result Codes)
And Error Codes) by Drizzle QQ: 253786989

Standard Code (Standard Codes)

The following are Definitions of standard return values and error codes:

#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 constants are returned only by a specific function. For example, SQLITE_RANGE is returned only by the sqlite3_bind_xxx function. There are also some constants. For example, SQLITE_ERROR can only indicate that the function has encountered an error during execution, but cannot know the cause of the error.

SQLITE_MISUSE indicates that the API is misused. For example, after a sqlite3_step function is executed and is not reset, bind a parameter to it again. Then, the bind function returns SQLITE_MISUSE.

Extended code (Extended Codes)

The standard error code provides less information about the cause of the error. So sometimes, we use an extended error code. Extended error codes are based on standard error codes. Their low-level bytes are the original standard error codes, and then they are appended with information to describe the error details.

int sqlite3_extended_result_codes(sqlite3*, int onoff);

Because of the compatibility of the customer's old program, the error codes of these extensions are not enabled by default. Programmers can use the sqlite3_extended_result_codes function to enable or disable extended error codes.

The following are all the extended error codes (most of which are used to 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-related functions (Error Functions)

int sqlite3_extended_result_codes(sqlite3*, int onoff);

Enable or disable the use of extended error codes for a database connection. Enable the extended error code by passing a non-zero value to the 2nd parameters of the sqlite3_extended_result_codes function. This function always returns SQLITE_ OK. There is no way to obtain whether the extended error code is enabled or disabled.

int sqlite3_errcode(sqlite3 *db);

If SQLITE_ OK is not returned for a database function operation, you can call this function to obtain the error code. By default, it returns a standard error code. If the current database connection has enabled an extended error code, this function may also return an extended error code.

int sqlite3_extended_errcode(sqlite3 *db);

Similar to the sqlite3_errcode function, this function only returns the extended error code.

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

Returns an error code string encoded using a UTF-8 or UTF-16. The programmer should call these two functions and use them immediately after obtaining the error code information, or make a copy. The next database operation may invalidate the returned string pointer.

SQlite error handling cannot process multiple errors at the same time. For example, if an API function call has an error, the programmer does not check and process the error, the next API function call may return SQLITE_MISUSE, indicating that the program tries to use an invalid data structure. Therefore, programmers should check and handle any possible errors after each API function call.

In addition, if multiple threads share the same database connection, it is best to encapsulate the code of the core API call and error handling in the critical section. Programmers can use the sqlite3_db_mutex function to obtain the mutex pointer for database connections (a pointer to the sqlite3_mutex object ).

Prepare function (Prepare v2)

The following table compares the prepare functions of the original version with the prepare functions of the v2 version:

The prepare function of V2 is more concise in error handling, as well as the schema advantages listed in the table above. Therefore, we recommend that you use the prepare function of v2.

Transactions and errors (Transactions and Errors)

Generally, SQlite operations are in the automatic submission mode. SQlite automatically encapsulates every SQL command into a transaction. If each statement is encapsulated in its own transaction, the error recovery is simple. At any time, as long as SQLite finds itself in an error state, it can simply roll back the current transaction. In this way, the current SQL command can be effectively canceled and the database will return to the status before an error occurs.

However, onceBegin transactionCommand Execution, SQlite is not in the automatic submission mode. A transaction is opened and will remain openEnd transactionOrCommit transactionCommand execution. This allows multiple SQL commands to be encapsulated into a transaction, so that a series of discrete commands are either executed in full or not executed (atomic operation ), however, this also limits the recovery of SQLite errors.

When an explicit transaction encounters an error, SQLite tries to cancel the statement just executed. Unfortunately, this is not always possible. If the transaction is bad, SQLite can only roll back the current transaction at times, and there is no other choice.

Sqlite_full (full database or disk space), sqlite_ioerr (Disk Io error or file locked), sqlite_busy (Database locked ), sqlite_nomem (insufficient memory), sqlite_interrupt (interrupted ). If the program is executing a display transaction and receives one of these errors, it is necessary to prepare for processing the transaction rollback that may occur.

int sqlite3_get_autocommit(sqlite3*);

This function can be used to obtain the current submission status. If a non-zero value is returned, the database is in the atutoconmit mode. If 0 is returned, the database is in a display transaction (the database is currently inside an explicit transaction ).

If the SQLite database is forced to perform a full transaction rollback operation, the database will change to the automatic transaction commit mode again. If the database is not in the automatic commit mode, it must be in a transaction, indicating that rollback is not required.

C Programming Interface of SQlite database (6) Return Value and error code (Result Codes)
And Error Codes) by Drizzle QQ: 253786989