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,/* OUT: Statement handle */
  const char **pzTail     /* OUT: Pointer to unused portion of zsql */
);
int sqlite3_prepare16(
  sqlite3 *db,/* Database handle */
  const void *zsql,UTF-16 encoded */
  int nByte,/* OUT: Statement handle */
  const void **pzTail     /* OUT: Pointer to unused portion of zsql */
);
int sqlite3_prepare16_v2(
  sqlite3 *db,/* 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.

The first argument,"db",is adatabase connectionobtained from a prior successful call tosqlite3_open(),sqlite3_open_v2()orsqlite3_open16(). The database connection must not have been 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.

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 stringincludingthe nul-terminator bytes as this saves sqlite from having to make a copy of the input string.

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.

*ppStmt is left pointing to a compiledprepared statementthat can be executed usingsqlite3_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 usingsqlite3_finalize()after it has finished with it. ppStmt may not be NULL.

On success,the sqlite3_prepare() family of routines returnSQLITE_OK; otherwise anerror codeis 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 (thesqlite3_stmtobject) contains a copy of the original sql text. This causes thesqlite3_step()interface to behave differently in three ways:

1. If the database schema changes,instead of returningSQLITE_SCHEMAas it always used to do,sqlite3_step()will automatically recompile the sql statement and try to run it again.
2. When an error occurs,100)" rel="nofollow" target="_blank">sqlite3_step()will return one of the detailederror codesorextended error codes. The legacy behavior was thatsqlite3_step()would only return a genericSQLITE_ERRORresult code and the application would have to make a second call tosqlite3_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.
3. If the specific value bound tohost parameterin the WHERE clause might influence the choice of query plan for a statement,then the statement will be automatically recompiled,as if there had been a schema change,on the firstsqlite3_step()call following any change to thebindingsof thatparameter. The specific value of WHERE-clauseparametermight influence the choice of query plan if the parameter is the left-hand side of aLIKEorGLOBoperator or if the parameter is compared to an indexed column and theSQLITE_ENABLE_STAT3compile-time option is enabled. the

See also lists ofObjects,Constants,andFunctions.