SQLite C Interface-Compiling An SQL Statement

 

Int sqlite3_prepare (
Sqlite3 * db,/* Database handle */
Const char * zSql,/* SQL statement, UTF-8 encoded */
Int nByte,/* Maximum length of zSql in bytes .*/
Sqlite3_stmt ** ppStmt,/* OUT: Statement handle */
Const char ** pzTail/* OUT: Pointer to unused portion of zSql */
);
Int sqlite3_prepare_v2 (
Sqlite3 * db,/* Database handle */
Const char * zSql,/* SQL statement, UTF-8 encoded */
Int nByte,/* Maximum length of zSql in bytes .*/
Sqlite3_stmt ** ppStmt,/* OUT: Statement handle */
Const char ** pzTail/* OUT: Pointer to unused portion of zSql */
);
Int sqlite3_prepare16 (
Sqlite3 * db,/* Database handle */
Const void * zSql,/* SQL statement, UTF-16 encoded */
Int nByte,/* Maximum length of zSql in bytes .*/
Sqlite3_stmt ** ppStmt,/* OUT: Statement handle */
Const void ** pzTail/* OUT: Pointer to unused portion of zSql */
);
Int sqlite3_prepare16_v2 (
Sqlite3 * db,/* Database handle */
Const void * zSql,/* SQL statement, UTF-16 encoded */
Int nByte,/* Maximum length of zSql in bytes .*/
Sqlite3_stmt ** ppStmt,/* OUT: Statement handle */
Const void ** pzTail/* OUT: Pointer to unused portion of zSql */
);

 

To execute an SQL query, it must first be compiled into a byte-code program using one of these routines.

To execute an SQL query, you must first use one of these routines to compile it into bytecode.

 

The first argument, "db", is a database connection obtained from a prior successful call to sqlite3_open (), evaluate () or sqlite3_open16 (). The database connection must not have been closed.

1st parameters. "db" is the database connection obtained by successfully calling sqlite3_open (), sqlite3_open_v2 (), or sqlite3_open16. The database connection must not be closed.

 

The second argument, "zSql", is the statement to be compiled, encoded as either UTF-8 or UTF-16. the sqlite3_prepare () and sqlite3_prepare_v2 () interfaces use UTF-8, and sqlite3_prepare16 () and sqlite3_prepare16_v2 () use UTF-16.

The 2nd parameters, "zSql", are the statements to be compiled, UTF-8 or UTF-16 encoded. Sqlite3_prepare () and sqlite3_prepare_v2 () interfaces use UTF-8, while sqlite3_prepare16 () and sqlite3_prepare16_v2 () Use UTF-16.

 

If the nByte argument is less than zero, then zSql is read up to the first zero terminator. if nByte is non-negative, then it is the maximum number of bytes read from zSql. when nByte is non-negative, the zSql string ends at either the first '\ 000' or' \ u0000 'character or the nByte-th byte, whichever comes first. if the caller knows that the supplied string is nul-terminated, then there is a small performance advantage to be gained by passing an nByte parameter that is equal to the number of bytes in the input string including the nul-terminator bytes.

If the nByte parameter is less than 0, zSql is read until the first 0 Terminator. If nByte is not negative, this is the maximum number of bytes read from zSql. When the nByte is not negative, the zSql string ends with the first "\ 000", "\ u0000", or the first byte, no matter which one appears first. If the caller knows that the provided string ends with null, passing the number of bytes of the input string including the null terminator to the nByte parameter can improve the performance.

 

If pzTail is not NULL then * pzTail is made to point to the first byte past the end of the first SQL statement in zSql. these routines only compile the first statement in zSql, so * pzTail is left pointing to what remains uncompiled.

If pzTail is not NULL, Set * pzTail to point to the first byte after the first SQL statement in zSql. These routines compile only the first statement in zSql, so * pzSql points to the uncompiled part.

 

* PpStmt is left pointing to a compiled prepared statement that can be executed using sqlite3_step (). if there is an error, * ppStmt is set to NULL. if the input text contains no SQL (if the input is an empty string or a comment) then * ppStmt is set to NULL. the calling procedure is responsible for deleting the compiled SQL statement using sqlite3_finalize () after it has finished with it. ppStmt may not be NULL.

Let * ppStmt point to a compiled statement that can be executed using sqlite3_step. If an error occurs, * ppStmt is set to NULL. If no SQL (empty string or comment) is input, * ppStmt is set to NULL. The main debugging process is responsible for using sqlite3_finalize () to delete compiled SQL statements after use. PpStmt may not be NULL.

 

On success, SQLITE_ OK is returned, otherwise an error code is returned.

If the call succeeds, SQLITE_ OK is returned. Otherwise, an error code is returned.

 

The sqlite3_prepare_v2 () and sqlite3_prepare16_v2 () interfaces are recommended for all new programs. the two older interfaces are retained for backwards compatibility, but their use is discouraged. in the "v2" interfaces, the prepared statement that is returned (the sqlite3_stmt object) contains a copy of the original SQL text. this causes the sqlite3_step () interface to behave a differently in two ways:

1. If the database schema changes, instead of returning SQLITE_SCHEMA as it always used to do, sqlite3_step () will automatically recompile the SQL statement and try to run it again. if the schema has changed in a way that makes the statement no longer valid, sqlite3_step () will still return SQLITE_SCHEMA. but unlike the legacy behavior, SQLITE_SCHEMA is now a fatal error. calling sqlite3_prepare_v2 () again will not make the error go away. note: use sqlite3_errmsg () to find the text of the parsing error that results in an SQLITE_SCHEMA return.
2. When an error occurs, sqlite3_step () will return one of the detailed error codes or extended error codes. the legacy behavior was that sqlite3_step () wocould only return a generic SQLITE_ERROR result code and you wowould have to make a second call to sqlite3_reset () in order to find the underlying cause of the problem. with the "v2" prepare interfaces, the underlying reason for the error is returned immediately.

We recommend that all new programs use the sqlite3_prepare_v2 () and sqlite3_prepare16_v2 () interfaces. The two old interfaces are retained for backward compatibility, but their use is blocked. In the "v2" interface, the returned precompiled Statement (sqlite3_stmt object) contains a copy of the original SQL text. This makes the sqlite3_step () interface behave differently in two aspects:

1. If the database mode changes, SQLITE_SCHEMA is not returned as before. sqlite3_step () will automatically recompile the SQL statement and try to run it again. If the statement is no longer valid due to schema change, sqlite3_step () returns SQLITE_SCHEMA. But unlike the original behavior, SQLITE_SCHEMA is now a major error. Calling sqlite3_prepare_v2 () again will not eliminate the error. Note: Use sqlite3_errmsg () to obtain the parsing error text that causes SQLITE_SCHEMA to be returned.
2. When an error occurs, sqlite3_step () returns a detailed error code or an extended error code. The original behavior is that sqlite3_step () Only returns the General SQLITE_ERROR result code, and you will have to call sqlite3_reset () again to obtain the internal cause of the problem. When you use the precompiled API "v2", the internal cause of the error is returned immediately.