sqlite3_bind_blob

Navigation

API > API/Plugins > API/Plugins/SQLiteCore > API/Plugins/SQLiteCore/sqlite

References

int sqlite3_bind_blob  
(  
    sqlite3_stmt *,  
    int,  
    const void *,  
    int n,  
    void(*)(void *)  
)  
Copy full snippet

int sqlite3_bind_blob (     sqlite3_stmt *,     int,     const void *,     int n,     void(*)(void *) )

Remarks

CAPI3REF: Binding Values To Prepared Statements KEYWORDS: {host parameter} {host parameters} {host parameter name} KEYWORDS: {SQL parameter} {SQL parameters} {parameter binding} METHOD: sqlite3_stmt

^(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:

• ?
• ?NNN
• :VVV
• @VVV
• $VVV

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 sqlite3bind*() routines defined here.

^The first argument to the sqlite3bind*() 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 bytes 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 the bind API fails, except the destructor is not called if the third parameter is a NULL pointer or the fourth parameter is negative. ^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 sqlite3bind*() 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 [sqlite3_blob_open | incremental BLOB I/O] routines. ^A negative value for the zeroblob results in a zero-length BLOB.

^The sqlite3_bind_pointer(S,I,P,T,D) routine causes the I-th parameter in [prepared statement] S to have an SQL value of NULL, but to also be associated with the pointer P of type T. ^D is either a NULL pointer or a pointer to a destructor function for P. ^SQLite will invoke the destructor D with a single argument of P when it is finished using P. The T parameter should be a static string, preferably a string literal. The sqlite3_bind_pointer() routine is part of the [pointer passing interface] added for SQLite 3.20.0.

^If any of the sqlite3bind*() routines are called with a NULL pointer for the [prepared statement] or with a prepared statement for which [[sqlite3step()](API\Plugins\SQLiteCore\sqlite\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 sqlite3bind* 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 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_bind_parameter_count()], [sqlite3_bind_parameter_name()], and [sqlite3_bind_parameter_index()].