1.Dd March 11, 2017 2.Dt SQLITE3_PREPARE 3 3.Os 4.Sh NAME 5.Nm sqlite3_prepare , 6.Nm sqlite3_prepare_v2 , 7.Nm sqlite3_prepare16 , 8.Nm sqlite3_prepare16_v2 9.Nd Compiling An SQL Statement 10.Sh SYNOPSIS 11.Ft int 12.Fo sqlite3_prepare 13.Fa "sqlite3 *db" 14.Fa "const char *zSql" 15.Fa "int nByte" 16.Fa "sqlite3_stmt **ppStmt" 17.Fa "const char **pzTail " 18.Fc 19.Ft int 20.Fo sqlite3_prepare_v2 21.Fa "sqlite3 *db" 22.Fa "const char *zSql" 23.Fa "int nByte" 24.Fa "sqlite3_stmt **ppStmt" 25.Fa "const char **pzTail " 26.Fc 27.Ft int 28.Fo sqlite3_prepare16 29.Fa "sqlite3 *db" 30.Fa "const void *zSql" 31.Fa "int nByte" 32.Fa "sqlite3_stmt **ppStmt" 33.Fa "const void **pzTail " 34.Fc 35.Ft int 36.Fo sqlite3_prepare16_v2 37.Fa "sqlite3 *db" 38.Fa "const void *zSql" 39.Fa "int nByte" 40.Fa "sqlite3_stmt **ppStmt" 41.Fa "const void **pzTail " 42.Fc 43.Sh DESCRIPTION 44To execute an SQL query, it must first be compiled into a byte-code 45program using one of these routines. 46.Pp 47The first argument, "db", is a database connection 48obtained from a prior successful call to sqlite3_open(), 49sqlite3_open_v2() or sqlite3_open16(). 50The database connection must not have been closed. 51.Pp 52The second argument, "zSql", is the statement to be compiled, encoded 53as either UTF-8 or UTF-16. 54The sqlite3_prepare() and sqlite3_prepare_v2() interfaces use UTF-8, 55and sqlite3_prepare16() and sqlite3_prepare16_v2() use UTF-16. 56.Pp 57If the nByte argument is negative, then zSql is read up to the first 58zero terminator. 59If nByte is positive, then it is the number of bytes read from zSql. 60If nByte is zero, then no prepared statement is generated. 61If the caller knows that the supplied string is nul-terminated, then 62there is a small performance advantage to passing an nByte parameter 63that is the number of bytes in the input string <i>including</i> the 64nul-terminator. 65.Pp 66If pzTail is not NULL then *pzTail is made to point to the first byte 67past the end of the first SQL statement in zSql. 68These routines only compile the first statement in zSql, so *pzTail 69is left pointing to what remains uncompiled. 70.Pp 71*ppStmt is left pointing to a compiled prepared statement 72that can be executed using sqlite3_step(). 73If there is an error, *ppStmt is set to NULL. 74If the input text contains no SQL (if the input is an empty string 75or a comment) then *ppStmt is set to NULL. 76The calling procedure is responsible for deleting the compiled SQL 77statement using sqlite3_finalize() after it has finished 78with it. 79ppStmt may not be NULL. 80.Pp 81On success, the sqlite3_prepare() family of routines return SQLITE_OK; 82otherwise an error code is returned. 83.Pp 84The sqlite3_prepare_v2() and sqlite3_prepare16_v2() interfaces are 85recommended for all new programs. 86The two older interfaces are retained for backwards compatibility, 87but their use is discouraged. 88In the "v2" interfaces, the prepared statement that is returned (the 89sqlite3_stmt object) contains a copy of the original SQL 90text. 91This causes the sqlite3_step() interface to behave differently 92in three ways: 93.Bl -enum 94.It 95If the database schema changes, instead of returning SQLITE_SCHEMA 96as it always used to do, sqlite3_step() will automatically 97recompile the SQL statement and try to run it again. 98As many as SQLITE_MAX_SCHEMA_RETRY retries will 99occur before sqlite3_step() gives up and returns an error. 100.It 101When an error occurs, sqlite3_step() will return one 102of the detailed error codes or extended error codes. 103The legacy behavior was that sqlite3_step() would only 104return a generic SQLITE_ERROR result code and the application 105would have to make a second call to sqlite3_reset() 106in order to find the underlying cause of the problem. 107With the "v2" prepare interfaces, the underlying reason for the error 108is returned immediately. 109.It 110If the specific value bound to host parameter in the 111WHERE clause might influence the choice of query plan for a statement, 112then the statement will be automatically recompiled, as if there had 113been a schema change, on the first sqlite3_step() call 114following any change to the bindings of that parameter. 115The specific value of WHERE-clause parameter might influence 116the choice of query plan if the parameter is the left-hand side of 117a LIKE or GLOB operator or if the parameter is compared to 118an indexed column and the SQLITE_ENABLE_STAT3 compile-time 119option is enabled. 120.El 121.Pp 122.Sh SEE ALSO 123.Xr sqlite3 3 , 124.Xr sqlite3_stmt 3 , 125.Xr sqlite3_bind_blob 3 , 126.Xr sqlite3_finalize 3 , 127.Xr sqlite3_open 3 , 128.Xr sqlite3_reset 3 , 129.Xr sqlite3_step 3 , 130.Xr sqlite3_stmt 3 , 131.Xr SQLITE_OK 3 132