NAME
sqlite3_bind_blob,
sqlite3_bind_blob64,
sqlite3_bind_double,
sqlite3_bind_int,
sqlite3_bind_int64,
sqlite3_bind_null,
sqlite3_bind_text,
sqlite3_bind_text16,
sqlite3_bind_text64,
sqlite3_bind_value,
sqlite3_bind_zeroblob,
sqlite3_bind_zeroblob64 —
Binding
Values To Prepared Statements
SYNOPSIS
int
sqlite3_bind_blob(
sqlite3_stmt*,
int,
const void*,
int n,
void(*)(void*));
int
sqlite3_bind_blob64(
sqlite3_stmt*,
int,
const void*,
sqlite3_uint64,
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,
void(*)(void*));
int
sqlite3_bind_text16(
sqlite3_stmt*,
int,
const void*,
int,
void(*)(void*));
int
sqlite3_bind_text64(
sqlite3_stmt*,
int,
const char*,
sqlite3_uint64,
void(*)(void*),
unsigned char encoding);
int
sqlite3_bind_value(
sqlite3_stmt*,
int,
const sqlite3_value*);
int
sqlite3_bind_zeroblob(
sqlite3_stmt*,
int,
int n);
int
sqlite3_bind_zeroblob64(
sqlite3_stmt*,
int,
sqlite3_uint64);
DESCRIPTION
In the SQL statement text input to sqlite3_prepare_v2() and its variants,
literals may be replaced by a parameter that matches one of following
templates:
In the templates above, NNN represents an integer literal, and VVV represents an
alphanumeric identifier. 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. If the third parameter
to sqlite3_bind_text() or sqlite3_bind_text16() or sqlite3_bind_blob() is a
NULL pointer then the fourth parameter is ignored and the end result is the
same as sqlite3_bind_null().
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
<u>bytes</u> in the value, not the number of characters. If the
fourth parameter to sqlite3_bind_text() or sqlite3_bind_text16() is negative,
then the length of the string is the number of bytes up to the first zero
terminator. If the fourth parameter to sqlite3_bind_blob() is negative, then
the behavior is undefined. If a non-negative fourth parameter is provided to
sqlite3_bind_text() or sqlite3_bind_text16() or sqlite3_bind_text64() then
that parameter must be the byte offset where the NUL terminator would occur
assuming the string were NUL terminated. If any NUL characters occur at byte
offsets less than the value of the fourth parameter then the resulting string
value will contain embedded NULs. The result of expressions involving strings
with embedded NULs is undefined.
The fifth argument to the BLOB and string binding interfaces is a destructor
used to dispose of the BLOB or string after SQLite has finished with it. The
destructor is called to dispose of the BLOB or string even if the call to bind
API fails. 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 sixth argument to sqlite3_bind_text64() must be one of SQLITE_UTF8,
SQLITE_UTF16, SQLITE_UTF16BE, or SQLITE_UTF16LE to specify the encoding of the
text in the third parameter. If the sixth argument to sqlite3_bind_text64() is
not one of the allowed values shown above, or if the text encoding is
different from the encoding specified by the sixth parameter, then the
behavior is undefined.
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.
If any of the sqlite3_bind_*() routines are called with a NULL pointer for the
prepared statement or with a prepared statement for which sqlite3_step() has
been called more recently than sqlite3_reset(), then the call will return
SQLITE_MISUSE. If any sqlite3_bind_() routine is passed a prepared statement
that has been finalized, the result is undefined and probably harmful.
Bindings are not cleared by the sqlite3_reset() routine. Unbound parameters are
interpreted as NULL.
The sqlite3_bind_* routines return SQLITE_OK on success or an error code if
anything goes wrong. SQLITE_TOOBIG might be returned if the size of a string
or BLOB exceeds limits imposed by sqlite3_limit(SQLITE_LIMIT_LENGTH) or
SQLITE_MAX_LENGTH. SQLITE_RANGE is returned if the parameter index is out of
range. SQLITE_NOMEM is returned if malloc() fails.
SEE ALSO
sqlite3_stmt(3),
sqlite3_bind_parameter_count(3),
sqlite3_bind_parameter_index(3),
sqlite3_bind_parameter_name(3),
sqlite3_blob_open(3),
sqlite3_limit(3),
sqlite3_prepare(3),
sqlite3_reset(3),
sqlite3_step(3),
sqlite3_stmt(3),
SQLITE_LIMIT_LENGTH(3),
SQLITE_OK(3),
sqlite3_destructor_type(3),
SQLITE_OK(3),
sqlite3_destructor_type(3),
SQLITE_UTF8(3)