Small. Fast. Reliable.
Choose any three.

About Sitemap Documentation Download License News Developers Support

## 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.

The first argument "db" is an SQLite database handle obtained from a prior call to sqlite3_open(), sqlite3_open_v2() or sqlite3_open16(). 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 uses 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 until the nByte-th byte, whichever comes first.

*pzTail is made to point to the first byte past the end of the first SQL statement in zSql. These routines only compiles the first statement in zSql, so *pzTail is left pointing to what remains uncompiled.

*ppStmt is left pointing to a compiled SQL statement structure that can be executed using sqlite3_step(). Or if there is an error, *ppStmt may be set to NULL. If the input text contains no SQL (if the input is and 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.

On success, 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 result codes or extended result codes. The legacy behavior was that sqlite3_step() would only return a generic SQLITE_ERROR result code and you would 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.

See also lists of Objects, Constants, and Functions.

This page last modified 2007/12/14 14:37:57 UTC