244 lines
12 KiB
HTML
244 lines
12 KiB
HTML
<!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>Obtaining SQL Values</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;
|
|
}
|
|
</script>
|
|
</div>
|
|
<!-- keywords: sqlite3_value_blob sqlite3_value_bytes sqlite3_value_bytes16 sqlite3_value_double sqlite3_value_frombind sqlite3_value_int sqlite3_value_int64 sqlite3_value_nochange sqlite3_value_numeric_type sqlite3_value_pointer sqlite3_value_text sqlite3_value_text16 sqlite3_value_text16be sqlite3_value_text16le sqlite3_value_type -->
|
|
<div class=nosearch>
|
|
<a href="intro.html"><h2>SQLite C Interface</h2></a>
|
|
<h2>Obtaining SQL Values</h2>
|
|
</div>
|
|
<blockquote><pre>
|
|
const void *sqlite3_value_blob(sqlite3_value*);
|
|
double sqlite3_value_double(sqlite3_value*);
|
|
int sqlite3_value_int(sqlite3_value*);
|
|
sqlite3_int64 sqlite3_value_int64(sqlite3_value*);
|
|
void *sqlite3_value_pointer(sqlite3_value*, const char*);
|
|
const unsigned char *sqlite3_value_text(sqlite3_value*);
|
|
const void *sqlite3_value_text16(sqlite3_value*);
|
|
const void *sqlite3_value_text16le(sqlite3_value*);
|
|
const void *sqlite3_value_text16be(sqlite3_value*);
|
|
int sqlite3_value_bytes(sqlite3_value*);
|
|
int sqlite3_value_bytes16(sqlite3_value*);
|
|
int sqlite3_value_type(sqlite3_value*);
|
|
int sqlite3_value_numeric_type(sqlite3_value*);
|
|
int sqlite3_value_nochange(sqlite3_value*);
|
|
int sqlite3_value_frombind(sqlite3_value*);
|
|
</pre></blockquote>
|
|
<p>
|
|
<b>Summary:</b>
|
|
<blockquote><table border=0 cellpadding=0 cellspacing=0>
|
|
<tr><td><b>sqlite3_value_blob</b><td>→<td>BLOB value
|
|
<tr><td><b>sqlite3_value_double</b><td>→<td>REAL value
|
|
<tr><td><b>sqlite3_value_int</b><td>→<td>32-bit INTEGER value
|
|
<tr><td><b>sqlite3_value_int64</b><td>→<td>64-bit INTEGER value
|
|
<tr><td><b>sqlite3_value_pointer</b><td>→<td>Pointer value
|
|
<tr><td><b>sqlite3_value_text</b><td>→<td>UTF-8 TEXT value
|
|
<tr><td><b>sqlite3_value_text16</b><td>→<td>UTF-16 TEXT value in
|
|
the native byteorder
|
|
<tr><td><b>sqlite3_value_text16be</b><td>→<td>UTF-16be TEXT value
|
|
<tr><td><b>sqlite3_value_text16le</b><td>→<td>UTF-16le TEXT value
|
|
<tr><td> <td> <td>
|
|
<tr><td><b>sqlite3_value_bytes</b><td>→<td>Size of a BLOB
|
|
or a UTF-8 TEXT in bytes
|
|
<tr><td><b>sqlite3_value_bytes16 </b>
|
|
<td>→ <td>Size of UTF-16
|
|
TEXT in bytes
|
|
<tr><td><b>sqlite3_value_type</b><td>→<td>Default
|
|
datatype of the value
|
|
<tr><td><b>sqlite3_value_numeric_type </b>
|
|
<td>→ <td>Best numeric datatype of the value
|
|
<tr><td><b>sqlite3_value_nochange </b>
|
|
<td>→ <td>True if the column is unchanged in an UPDATE
|
|
against a virtual table.
|
|
<tr><td><b>sqlite3_value_frombind </b>
|
|
<td>→ <td>True if value originated from a <a href="../lang_expr.html#varparam">bound parameter</a>
|
|
</table></blockquote></p>
|
|
|
|
<p><b>Details:</b></p>
|
|
|
|
<p>These routines extract type, size, and content information from
|
|
<a href="../c3ref/value.html">protected sqlite3_value</a> objects. Protected sqlite3_value objects
|
|
are used to pass parameter information into the functions that
|
|
implement <a href="../appfunc.html">application-defined SQL functions</a> and <a href="../vtab.html">virtual tables</a>.</p>
|
|
|
|
<p>These routines work only with <a href="../c3ref/value.html">protected sqlite3_value</a> objects.
|
|
Any attempt to use these routines on an <a href="../c3ref/value.html">unprotected sqlite3_value</a>
|
|
is not threadsafe.</p>
|
|
|
|
<p>These routines work just like the corresponding <a href="../c3ref/column_blob.html">column access functions</a>
|
|
except that these routines take a single <a href="../c3ref/value.html">protected sqlite3_value</a> object
|
|
pointer instead of a <a href="../c3ref/stmt.html">sqlite3_stmt*</a> pointer and an integer column number.</p>
|
|
|
|
<p>The sqlite3_value_text16() interface extracts a UTF-16 string
|
|
in the native byte-order of the host machine. The
|
|
sqlite3_value_text16be() and sqlite3_value_text16le() interfaces
|
|
extract UTF-16 strings as big-endian and little-endian respectively.</p>
|
|
|
|
<p>If <a href="../c3ref/value.html">sqlite3_value</a> object V was initialized
|
|
using <a href="../c3ref/bind_blob.html">sqlite3_bind_pointer(S,I,P,X,D)</a> or <a href="../c3ref/result_blob.html">sqlite3_result_pointer(C,P,X,D)</a>
|
|
and if X and Y are strings that compare equal according to strcmp(X,Y),
|
|
then sqlite3_value_pointer(V,Y) will return the pointer P. Otherwise,
|
|
sqlite3_value_pointer(V,Y) returns a NULL. 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>The sqlite3_value_type(V) interface returns the
|
|
<a href="../c3ref/c_blob.html">datatype code</a> for the initial datatype of the
|
|
<a href="../c3ref/value.html">sqlite3_value</a> object V. The returned value is one of <a href="../c3ref/c_blob.html">SQLITE_INTEGER</a>,
|
|
<a href="../c3ref/c_blob.html">SQLITE_FLOAT</a>, <a href="../c3ref/c_blob.html">SQLITE_TEXT</a>, <a href="../c3ref/c_blob.html">SQLITE_BLOB</a>, or <a href="../c3ref/c_blob.html">SQLITE_NULL</a>.
|
|
Other interfaces might change the datatype for an sqlite3_value object.
|
|
For example, if the datatype is initially SQLITE_INTEGER and
|
|
sqlite3_value_text(V) is called to extract a text value for that
|
|
integer, then subsequent calls to sqlite3_value_type(V) might return
|
|
SQLITE_TEXT. Whether or not a persistent internal datatype conversion
|
|
occurs is undefined and may change from one release of SQLite to the next.</p>
|
|
|
|
<p>The sqlite3_value_numeric_type() interface attempts to apply
|
|
numeric affinity to the value. This means that an attempt is
|
|
made to convert the value to an integer or floating point. If
|
|
such a conversion is possible without loss of information (in other
|
|
words, if the value is a string that looks like a number)
|
|
then the conversion is performed. Otherwise no conversion occurs.
|
|
The <a href="../c3ref/c_blob.html">datatype</a> after conversion is returned.</p>
|
|
|
|
<p>Within the <a href="../vtab.html#xupdate">xUpdate</a> method of a <a href="../vtab.html">virtual table</a>, the
|
|
sqlite3_value_nochange(X) interface returns true if and only if
|
|
the column corresponding to X is unchanged by the UPDATE operation
|
|
that the xUpdate method call was invoked to implement and if
|
|
and the prior <a href="../vtab.html#xcolumn">xColumn</a> method call that was invoked to extracted
|
|
the value for that column returned without setting a result (probably
|
|
because it queried <a href="../c3ref/vtab_nochange.html">sqlite3_vtab_nochange()</a> and found that the column
|
|
was unchanging). Within an <a href="../vtab.html#xupdate">xUpdate</a> method, any value for which
|
|
sqlite3_value_nochange(X) is true will in all other respects appear
|
|
to be a NULL value. If sqlite3_value_nochange(X) is invoked anywhere other
|
|
than within an <a href="../vtab.html#xupdate">xUpdate</a> method call for an UPDATE statement, then
|
|
the return value is arbitrary and meaningless.</p>
|
|
|
|
<p>The sqlite3_value_frombind(X) interface returns non-zero if the
|
|
value X originated from one of the <a href="../c3ref/bind_blob.html">sqlite3_bind()</a>
|
|
interfaces. If X comes from an SQL literal value, or a table column,
|
|
or an expression, then sqlite3_value_frombind(X) returns zero.</p>
|
|
|
|
<p>Please pay particular attention to the fact that the pointer returned
|
|
from <a href="../c3ref/value_blob.html">sqlite3_value_blob()</a>, <a href="../c3ref/value_blob.html">sqlite3_value_text()</a>, or
|
|
<a href="../c3ref/value_blob.html">sqlite3_value_text16()</a> can be invalidated by a subsequent call to
|
|
<a href="../c3ref/value_blob.html">sqlite3_value_bytes()</a>, <a href="../c3ref/value_blob.html">sqlite3_value_bytes16()</a>, <a href="../c3ref/value_blob.html">sqlite3_value_text()</a>,
|
|
or <a href="../c3ref/value_blob.html">sqlite3_value_text16()</a>.</p>
|
|
|
|
<p>These routines must be called from the same thread as
|
|
the SQL function that supplied the <a href="../c3ref/value.html">sqlite3_value*</a> parameters.</p>
|
|
|
|
<p>As long as the input parameter is correct, these routines can only
|
|
fail if an out-of-memory error occurs during a format conversion.
|
|
Only the following subset of interfaces are subject to out-of-memory
|
|
errors:</p>
|
|
|
|
<p><ul>
|
|
<li> sqlite3_value_blob()
|
|
<li> sqlite3_value_text()
|
|
<li> sqlite3_value_text16()
|
|
<li> sqlite3_value_text16le()
|
|
<li> sqlite3_value_text16be()
|
|
<li> sqlite3_value_bytes()
|
|
<li> sqlite3_value_bytes16()
|
|
</ul></p>
|
|
|
|
<p>If an out-of-memory error occurs, then the return value from these
|
|
routines is the same as if the column had contained an SQL NULL value.
|
|
Valid SQL NULL returns can be distinguished from out-of-memory errors
|
|
by invoking the <a href="../c3ref/errcode.html">sqlite3_errcode()</a> immediately after the suspect
|
|
return value is obtained and before any
|
|
other SQLite interface is called on the same <a href="../c3ref/sqlite3.html">database connection</a>.
|
|
</p><p>See also lists of
|
|
<a href="objlist.html">Objects</a>,
|
|
<a href="constlist.html">Constants</a>, and
|
|
<a href="funclist.html">Functions</a>.</p>
|