1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
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>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;
}
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: sqlite3_value_blob sqlite3_value_bytes sqlite3_value_bytes16 sqlite3_value_double sqlite3_value_encoding 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*);
int sqlite3_value_encoding(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>The sqlite3_value_encoding(X) interface returns one of <a href="../c3ref/c_any.html">SQLITE_UTF8</a>,
<a href="../c3ref/c_any.html">SQLITE_UTF16BE</a>, or <a href="../c3ref/c_any.html">SQLITE_UTF16LE</a> according to the current encoding
of the value X, assuming that X has type TEXT. If sqlite3_value_type(X)
returns something other than SQLITE_TEXT, then the return value from
sqlite3_value_encoding(X) is meaningless. Calls to
sqlite3_value_text(X), sqlite3_value_text16(X), sqlite3_value_text16be(X),
sqlite3_value_text16le(X), sqlite3_value_bytes(X), or
sqlite3_value_bytes16(X) might change the encoding of the value X and
thus change the return from subsequent calls to sqlite3_value_encoding(X).</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>
|
