Small. Fast. Reliable.
Choose any three.

About Sitemap Documentation Download License News Developers Support

## SQLite C Interface

## Binding Values To Prepared Statements

>     int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
>     int sqlite3_bind_double(sqlite3_stmt*, int, double);
>     int sqlite3_bind_int(sqlite3_stmt*, int, int);
>     int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);
>     int sqlite3_bind_null(sqlite3_stmt*, int);
>     int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*));
>     int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));
>     int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
>     int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);

In the SQL strings input to sqlite3_prepare_v2() and its variants, literals may be replaced by a parameter in one of these forms:

- ?
- ?NNN
- :VVV
- @VVV
- $VVV

In the parameter forms shown above NNN is an integer literal, and VVV is an alpha-numeric parameter name. The values of these parameters (also called "host parameter names" or "SQL parameters") can be set using the sqlite3_bind_*() routines defined here.

The first argument to the sqlite3_bind_*() routines is always a pointer to the sqlite3_stmt object returned from sqlite3_prepare_v2() or its variants.

The second argument is the index of the SQL parameter to be set. The leftmost SQL parameter has an index of 1. When the same named SQL parameter is used more than once, second and subsequent occurrences have the same index as the first occurrence. The index for named parameters can be looked up using the sqlite3_bind_parameter_index() API if desired. The index for "?NNN" parameters is the value of NNN. The NNN value must be between 1 and the sqlite3_limit() parameter SQLITE_LIMIT_VARIABLE_NUMBER (default value: 999).

The third argument is the value to bind to the parameter.

In those routines that have a fourth argument, its value is the number of bytes in the parameter. To be clear: the value is the number of bytes in the value, not the number of characters. If the fourth parameter is negative, the length of the string is the number of bytes up to the first zero terminator.

The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and sqlite3_bind_text16() is a destructor used to dispose of the BLOB or string after SQLite has finished with it. If the fifth argument is the special value SQLITE_STATIC, then SQLite assumes that the information is in static, unmanaged space and does not need to be freed. If the fifth argument has the value SQLITE_TRANSIENT, then SQLite makes its own private copy of the data immediately, before the sqlite3_bind_*() routine returns.

The sqlite3_bind_zeroblob() routine binds a BLOB of length N that is filled with zeroes. A zeroblob uses a fixed amount of memory (just an integer to hold its size) while it is being processed. Zeroblobs are intended to serve as placeholders for BLOBs whose content is later written using incremental BLOB I/O routines. A negative value for the zeroblob results in a zero-length BLOB.

The sqlite3_bind_*() routines must be called after sqlite3_prepare_v2() (and its variants) or sqlite3_reset() and before sqlite3_step(). Bindings are not cleared by the sqlite3_reset() routine. Unbound parameters are interpreted as NULL.

These routines return SQLITE_OK on success or an error code if anything goes wrong. SQLITE_RANGE is returned if the parameter index is out of range. SQLITE_NOMEM is returned if malloc() fails. SQLITE_MISUSE might be returned if these routines are called on a virtual machine that is the wrong state or which has already been finalized. Detection of misuse is unreliable. Applications should not depend on SQLITE_MISUSE returns. SQLITE_MISUSE is intended to indicate a a logic error in the application. Future versions of SQLite might panic rather than return SQLITE_MISUSE.

See also: sqlite3_bind_parameter_count(), sqlite3_bind_parameter_name(), and sqlite3_bind_parameter_index().

### Invariants:

H13506 | The SQL statement compiler recognizes tokens of the forms "?", "?NNN", "$VVV", ":VVV", and "@VVV" as SQL parameters, where NNN is any sequence of one or more digits and where VVV is any sequence of one or more alphanumeric characters or "::" optionally followed by a string containing no spaces and contained within parentheses.
H13509 | The initial value of an SQL parameter is NULL.
H13512 | The index of an "?" SQL parameter is one larger than the largest index of SQL parameter to the left, or 1 if the "?" is the leftmost SQL parameter.
H13515 | The index of an "?NNN" SQL parameter is the integer NNN.
H13518 | The index of an ":VVV", "$VVV", or "@VVV" SQL parameter is the same as the index of leftmost occurrences of the same parameter, or one more than the largest index over all parameters to the left if this is the first occurrence of this parameter, or 1 if this is the leftmost parameter.
H13521 | The SQL statement compiler fails with an SQLITE_RANGE error if the index of an SQL parameter is less than 1 or greater than the compile-time SQLITE_MAX_VARIABLE_NUMBER parameter.
H13524 | Calls to sqlite3_bind(S,N,V,...) associate the value V with all SQL parameters having an index of N in the prepared statement S.
H13527 | Calls to sqlite3_bind(S,N,...) override prior calls with the same values of S and N.
H13530 | Bindings established by sqlite3_bind(S,...) persist across calls to sqlite3_reset(S).
H13533 | In calls to sqlite3_bind_blob(S,N,V,L,D), sqlite3_bind_text(S,N,V,L,D), or sqlite3_bind_text16(S,N,V,L,D) SQLite binds the first L bytes of the BLOB or string pointed to by V, when L is non-negative.
H13536 | In calls to sqlite3_bind_text(S,N,V,L,D) or sqlite3_bind_text16(S,N,V,L,D) SQLite binds characters from V through the first zero character when L is negative.
H13539 | In calls to sqlite3_bind_blob(S,N,V,L,D), sqlite3_bind_text(S,N,V,L,D), or sqlite3_bind_text16(S,N,V,L,D) when D is the special constant SQLITE_STATIC, SQLite assumes that the value V is held in static unmanaged space that will not change during the lifetime of the binding.
H13542 | In calls to sqlite3_bind_blob(S,N,V,L,D), sqlite3_bind_text(S,N,V,L,D), or sqlite3_bind_text16(S,N,V,L,D) when D is the special constant SQLITE_TRANSIENT, the routine makes a private copy of the value V before it returns.
H13545 | In calls to sqlite3_bind_blob(S,N,V,L,D), sqlite3_bind_text(S,N,V,L,D), or sqlite3_bind_text16(S,N,V,L,D) when D is a pointer to a function, SQLite invokes that function to destroy the value V after it has finished using the value V.
H13548 | In calls to sqlite3_bind_zeroblob(S,N,V,L) the value bound is a BLOB of L bytes, or a zero-length BLOB if L is negative.
H13551 | In calls to sqlite3_bind_value(S,N,V) the V argument may be either a protected sqlite3_value object or an unprotected sqlite3_value object.

See also lists of Objects, Constants, and Functions.

This page last modified 2008/12/09 18:44:04 UTC