diff options
Diffstat (limited to 'www/c3ref/bind_blob.html')
| -rw-r--r-- | www/c3ref/bind_blob.html | 279 |
1 files changed, 279 insertions, 0 deletions
diff --git a/www/c3ref/bind_blob.html b/www/c3ref/bind_blob.html new file mode 100644 index 0000000..ab264d7 --- /dev/null +++ b/www/c3ref/bind_blob.html @@ -0,0 +1,279 @@ +<!DOCTYPE html> +<html><head> +<meta name="viewport" content="width=device-width, initial-scale=1.0"> +<meta http-equiv="content-type" content="text/html; charset=UTF-8"> +<link href="../sqlite.css" rel="stylesheet"> +<title>Binding Values To Prepared Statements</title> +<!-- path=../ --> +</head> +<body> +<div class=nosearch> +<a href="../index.html"> +<img class="logo" src="../images/sqlite370_banner.gif" alt="SQLite" border="0"> +</a> +<div><!-- IE hack to prevent disappearing logo --></div> +<div class="tagline desktoponly"> +Small. Fast. Reliable.<br>Choose any three. +</div> +<div class="menu mainmenu"> +<ul> +<li><a href="../index.html">Home</a> +<li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a> +<li class='wideonly'><a href='../about.html'>About</a> +<li class='desktoponly'><a href="../docs.html">Documentation</a> +<li class='desktoponly'><a href="../download.html">Download</a> +<li class='wideonly'><a href='../copyright.html'>License</a> +<li class='desktoponly'><a href="../support.html">Support</a> +<li class='desktoponly'><a href="../prosupport.html">Purchase</a> +<li class='search' id='search_menubutton'> +<a href="javascript:void(0)" onclick='toggle_search()'>Search</a> +</ul> +</div> +<div class="menu submenu" id="submenu"> +<ul> +<li><a href='../about.html'>About</a> +<li><a href='../docs.html'>Documentation</a> +<li><a href='../download.html'>Download</a> +<li><a href='../support.html'>Support</a> +<li><a href='../prosupport.html'>Purchase</a> +</ul> +</div> +<div class="searchmenu" id="searchmenu"> +<form method="GET" action="../search"> +<select name="s" id="searchtype"> +<option value="d">Search Documentation</option> +<option value="c">Search Changelog</option> +</select> +<input type="text" name="q" id="searchbox" value=""> +<input type="submit" value="Go"> +</form> +</div> +</div> +<script> +function toggle_div(nm) { +var w = document.getElementById(nm); +if( w.style.display=="block" ){ +w.style.display = "none"; +}else{ +w.style.display = "block"; +} +} +function toggle_search() { +var w = document.getElementById("searchmenu"); +if( w.style.display=="block" ){ +w.style.display = "none"; +} else { +w.style.display = "block"; +setTimeout(function(){ +document.getElementById("searchbox").focus() +}, 30); +} +} +function div_off(nm){document.getElementById(nm).style.display="none";} +window.onbeforeunload = function(e){div_off("submenu");} +/* Disable the Search feature if we are not operating from CGI, since */ +/* Search is accomplished using CGI and will not work without it. */ +if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){ +document.getElementById("search_menubutton").style.display = "none"; +} +/* Used by the Hide/Show button beside syntax diagrams, to toggle the */ +function hideorshow(btn,obj){ +var x = document.getElementById(obj); +var b = document.getElementById(btn); +if( x.style.display!='none' ){ +x.style.display = 'none'; +b.innerHTML='show'; +}else{ +x.style.display = ''; +b.innerHTML='hide'; +} +return false; +} +var antiRobot = 0; +function antiRobotGo(){ +if( antiRobot!=3 ) return; +antiRobot = 7; +var j = document.getElementById("mtimelink"); +if(j && j.hasAttribute("data-href")) j.href=j.getAttribute("data-href"); +} +function antiRobotDefense(){ +document.body.onmousedown=function(){ +antiRobot |= 2; +antiRobotGo(); +document.body.onmousedown=null; +} +document.body.onmousemove=function(){ +antiRobot |= 2; +antiRobotGo(); +document.body.onmousemove=null; +} +setTimeout(function(){ +antiRobot |= 1; +antiRobotGo(); +}, 100) +antiRobotGo(); +} +antiRobotDefense(); +</script> +<!-- keywords: {SQL parameter} {SQL parameters} {host parameter} {host parameter name} {host parameters} {parameter binding} sqlite3_bind_blob sqlite3_bind_blob64 sqlite3_bind_double sqlite3_bind_int sqlite3_bind_int64 sqlite3_bind_null sqlite3_bind_pointer sqlite3_bind_text sqlite3_bind_text16 sqlite3_bind_text64 sqlite3_bind_value sqlite3_bind_zeroblob sqlite3_bind_zeroblob64 --> +<div class=nosearch> +<a href="../c3ref/intro.html"><h2>SQLite C Interface</h2></a> +<h2>Binding Values To Prepared Statements</h2> +</div> +<blockquote><pre> +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_pointer(sqlite3_stmt*, int, void*, const char*,void(*)(void*)); +int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n); +int sqlite3_bind_zeroblob64(sqlite3_stmt*, int, sqlite3_uint64); +</pre></blockquote> +<p> +In the SQL statement text input to <a href="../c3ref/prepare.html">sqlite3_prepare_v2()</a> and its variants, +literals may be replaced by a <a href="../lang_expr.html#varparam">parameter</a> that matches one of following +templates:</p> + +<p><ul> +<li> ? +<li> ?NNN +<li> :VVV +<li> @VVV +<li> $VVV +</ul></p> + +<p>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.</p> + +<p>The first argument to the sqlite3_bind_*() routines is always +a pointer to the <a href="../c3ref/stmt.html">sqlite3_stmt</a> object returned from +<a href="../c3ref/prepare.html">sqlite3_prepare_v2()</a> or its variants.</p> + +<p>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 +<a href="../c3ref/bind_parameter_index.html">sqlite3_bind_parameter_index()</a> API if desired. The index +for "?NNN" parameters is the value of NNN. +The NNN value must be between 1 and the <a href="../c3ref/limit.html">sqlite3_limit()</a> +parameter <a href="../c3ref/c_limit_attached.html#sqlitelimitvariablenumber">SQLITE_LIMIT_VARIABLE_NUMBER</a> (default value: 32766).</p> + +<p>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(). +If the third parameter to sqlite3_bind_text() is not NULL, then +it should be a pointer to well-formed UTF8 text. +If the third parameter to sqlite3_bind_text16() is not NULL, then +it should be a pointer to well-formed UTF16 text. +If the third parameter to sqlite3_bind_text64() is not NULL, then +it should be a pointer to a well-formed unicode string that is +either UTF8 if the sixth parameter is SQLITE_UTF8, or UTF16 +otherwise.</p> + +<p><a name="byteorderdeterminationrules"></a> + The byte-order of +UTF16 input text is determined by the byte-order mark (BOM, U+FEFF) +found in first character, which is removed, or in the absence of a BOM +the byte order is the native byte order of the host +machine for sqlite3_bind_text16() or the byte order specified in +the 6th parameter for sqlite3_bind_text64(). +If UTF16 input text contains invalid unicode +characters, then SQLite might change those invalid characters +into the unicode replacement character: U+FFFD.</p> + +<p>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 occurs 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.</p> + +<p>The fifth argument to the BLOB and string binding interfaces controls +or indicates the lifetime of the object referenced by the third parameter. +These three options exist: + (1) A destructor to dispose of the BLOB or string after SQLite has finished +with it may be passed. It 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. + (2) The special constant, <a href="../c3ref/c_static.html">SQLITE_STATIC</a>, may be passed to indicate that +the application remains responsible for disposing of the object. In this +case, the object and the provided pointer to it must remain valid until +either the prepared statement is finalized or the same SQL parameter is +bound to something else, whichever occurs sooner. + (3) The constant, <a href="../c3ref/c_static.html">SQLITE_TRANSIENT</a>, may be passed to indicate that the +object is to be copied prior to the return from sqlite3_bind_*(). The +object and pointer to it must remain valid until then. SQLite will then +manage the lifetime of its private copy.</p> + +<p>The sixth argument to sqlite3_bind_text64() must be one of +<a href="../c3ref/c_any.html">SQLITE_UTF8</a>, <a href="../c3ref/c_any.html">SQLITE_UTF16</a>, <a href="../c3ref/c_any.html">SQLITE_UTF16BE</a>, or <a href="../c3ref/c_any.html">SQLITE_UTF16LE</a> +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.</p> + +<p>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 +<a href="../c3ref/blob_open.html">incremental BLOB I/O</a> routines. +A negative value for the zeroblob results in a zero-length BLOB.</p> + +<p>The sqlite3_bind_pointer(S,I,P,T,D) routine causes the I-th parameter in +<a href="../c3ref/stmt.html">prepared statement</a> 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 +<a href="../bindptr.html">pointer passing interface</a> added for SQLite 3.20.0.</p> + +<p>If any of the sqlite3_bind_*() routines are called with a NULL pointer +for the <a href="../c3ref/stmt.html">prepared statement</a> or with a prepared statement for which +<a href="../c3ref/step.html">sqlite3_step()</a> has been called more recently than <a href="../c3ref/reset.html">sqlite3_reset()</a>, +then the call will return <a href="../rescode.html#misuse">SQLITE_MISUSE</a>. If any sqlite3_bind_() +routine is passed a <a href="../c3ref/stmt.html">prepared statement</a> that has been finalized, the +result is undefined and probably harmful.</p> + +<p>Bindings are not cleared by the <a href="../c3ref/reset.html">sqlite3_reset()</a> routine. +Unbound parameters are interpreted as NULL.</p> + +<p>The sqlite3_bind_* routines return <a href="../rescode.html#ok">SQLITE_OK</a> on success or an +<a href="../rescode.html">error code</a> if anything goes wrong. +<a href="../rescode.html#toobig">SQLITE_TOOBIG</a> might be returned if the size of a string or BLOB +exceeds limits imposed by <a href="../c3ref/limit.html">sqlite3_limit</a>(<a href="../c3ref/c_limit_attached.html#sqlitelimitlength">SQLITE_LIMIT_LENGTH</a>) or +<a href="../limits.html#max_length">SQLITE_MAX_LENGTH</a>. +<a href="../rescode.html#range">SQLITE_RANGE</a> is returned if the parameter +index is out of range. <a href="../rescode.html#nomem">SQLITE_NOMEM</a> is returned if malloc() fails.</p> + +<p>See also: <a href="../c3ref/bind_parameter_count.html">sqlite3_bind_parameter_count()</a>, +<a href="../c3ref/bind_parameter_name.html">sqlite3_bind_parameter_name()</a>, and <a href="../c3ref/bind_parameter_index.html">sqlite3_bind_parameter_index()</a>. +</p><p>See also lists of + <a href="../c3ref/objlist.html">Objects</a>, + <a href="../c3ref/constlist.html">Constants</a>, and + <a href="../c3ref/funclist.html">Functions</a>.</p> + |