Adding upstream version 3.45.1.upstream/3.45.1

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
author: Daniel Baumann <daniel.baumann@progress-linux.org> 2024-04-13 14:07:11 +0000
committer: Daniel Baumann <daniel.baumann@progress-linux.org> 2024-04-13 14:07:11 +0000
commit: 63847496f14c813a5d80efd5b7de0f1294ffe1e3 (patch)
tree: 01c7571c7c762ceee70638549a99834fdd7c411b /www/c3ref/bind_blob.html
parent: Initial commit. (diff)
download: sqlite3-63847496f14c813a5d80efd5b7de0f1294ffe1e3.tar.xz
sqlite3-63847496f14c813a5d80efd5b7de0f1294ffe1e3.zip
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>
+
author	Daniel Baumann <daniel.baumann@progress-linux.org>	2024-04-13 14:07:11 +0000
committer	Daniel Baumann <daniel.baumann@progress-linux.org>	2024-04-13 14:07:11 +0000
commit	63847496f14c813a5d80efd5b7de0f1294ffe1e3 (patch)
tree	01c7571c7c762ceee70638549a99834fdd7c411b /www/c3ref/bind_blob.html
parent	Initial commit. (diff)
download	sqlite3-63847496f14c813a5d80efd5b7de0f1294ffe1e3.tar.xz sqlite3-63847496f14c813a5d80efd5b7de0f1294ffe1e3.zip