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
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
|
<!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>Result Values From A Query</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: {column access functions} sqlite3_column_blob sqlite3_column_bytes sqlite3_column_bytes16 sqlite3_column_double sqlite3_column_int sqlite3_column_int64 sqlite3_column_text sqlite3_column_text16 sqlite3_column_type sqlite3_column_value -->
<div class=nosearch>
<a href="intro.html"><h2>SQLite C Interface</h2></a>
<h2>Result Values From A Query</h2>
</div>
<blockquote><pre>
const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
double sqlite3_column_double(sqlite3_stmt*, int iCol);
int sqlite3_column_int(sqlite3_stmt*, int iCol);
sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);
const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);
int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
int sqlite3_column_type(sqlite3_stmt*, int iCol);
</pre></blockquote>
<p>
<b>Summary:</b>
<blockquote><table border=0 cellpadding=0 cellspacing=0>
<tr><td><b>sqlite3_column_blob</b><td>→<td>BLOB result
<tr><td><b>sqlite3_column_double</b><td>→<td>REAL result
<tr><td><b>sqlite3_column_int</b><td>→<td>32-bit INTEGER result
<tr><td><b>sqlite3_column_int64</b><td>→<td>64-bit INTEGER result
<tr><td><b>sqlite3_column_text</b><td>→<td>UTF-8 TEXT result
<tr><td><b>sqlite3_column_text16</b><td>→<td>UTF-16 TEXT result
<tr><td><b>sqlite3_column_value</b><td>→<td>The result as an
<a href="../c3ref/value.html">unprotected sqlite3_value</a> object.
<tr><td> <td> <td>
<tr><td><b>sqlite3_column_bytes</b><td>→<td>Size of a BLOB
or a UTF-8 TEXT result in bytes
<tr><td><b>sqlite3_column_bytes16 </b>
<td>→ <td>Size of UTF-16
TEXT in bytes
<tr><td><b>sqlite3_column_type</b><td>→<td>Default
datatype of the result
</table></blockquote></p>
<p><b>Details:</b></p>
<p>These routines return information about a single column of the current
result row of a query. In every case the first argument is a pointer
to the <a href="../c3ref/stmt.html">prepared statement</a> that is being evaluated (the <a href="../c3ref/stmt.html">sqlite3_stmt*</a>
that was returned from <a href="../c3ref/prepare.html">sqlite3_prepare_v2()</a> or one of its variants)
and the second argument is the index of the column for which information
should be returned. The leftmost column of the result set has the index 0.
The number of columns in the result can be determined using
<a href="../c3ref/column_count.html">sqlite3_column_count()</a>.</p>
<p>If the SQL statement does not currently point to a valid row, or if the
column index is out of range, the result is undefined.
These routines may only be called when the most recent call to
<a href="../c3ref/step.html">sqlite3_step()</a> has returned <a href="../rescode.html#row">SQLITE_ROW</a> and neither
<a href="../c3ref/reset.html">sqlite3_reset()</a> nor <a href="../c3ref/finalize.html">sqlite3_finalize()</a> have been called subsequently.
If any of these routines are called after <a href="../c3ref/reset.html">sqlite3_reset()</a> or
<a href="../c3ref/finalize.html">sqlite3_finalize()</a> or after <a href="../c3ref/step.html">sqlite3_step()</a> has returned
something other than <a href="../rescode.html#row">SQLITE_ROW</a>, the results are undefined.
If <a href="../c3ref/step.html">sqlite3_step()</a> or <a href="../c3ref/reset.html">sqlite3_reset()</a> or <a href="../c3ref/finalize.html">sqlite3_finalize()</a>
are called from a different thread while any of these routines
are pending, then the results are undefined.</p>
<p>The first six interfaces (_blob, _double, _int, _int64, _text, and _text16)
each return the value of a result column in a specific data format. If
the result column is not initially in the requested format (for example,
if the query returns an integer but the sqlite3_column_text() interface
is used to extract the value) then an automatic type conversion is performed.</p>
<p>The sqlite3_column_type() routine returns the
<a href="../c3ref/c_blob.html">datatype code</a> for the initial data type
of the result column. 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>.
The return value of sqlite3_column_type() can be used to decide which
of the first six interface should be used to extract the column value.
The value returned by sqlite3_column_type() is only meaningful if no
automatic type conversions have occurred for the value in question.
After a type conversion, the result of calling sqlite3_column_type()
is undefined, though harmless. Future
versions of SQLite may change the behavior of sqlite3_column_type()
following a type conversion.</p>
<p>If the result is a BLOB or a TEXT string, then the sqlite3_column_bytes()
or sqlite3_column_bytes16() interfaces can be used to determine the size
of that BLOB or string.</p>
<p>If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes()
routine returns the number of bytes in that BLOB or string.
If the result is a UTF-16 string, then sqlite3_column_bytes() converts
the string to UTF-8 and then returns the number of bytes.
If the result is a numeric value then sqlite3_column_bytes() uses
<a href="../c3ref/mprintf.html">sqlite3_snprintf()</a> to convert that value to a UTF-8 string and returns
the number of bytes in that string.
If the result is NULL, then sqlite3_column_bytes() returns zero.</p>
<p>If the result is a BLOB or UTF-16 string then the sqlite3_column_bytes16()
routine returns the number of bytes in that BLOB or string.
If the result is a UTF-8 string, then sqlite3_column_bytes16() converts
the string to UTF-16 and then returns the number of bytes.
If the result is a numeric value then sqlite3_column_bytes16() uses
<a href="../c3ref/mprintf.html">sqlite3_snprintf()</a> to convert that value to a UTF-16 string and returns
the number of bytes in that string.
If the result is NULL, then sqlite3_column_bytes16() returns zero.</p>
<p>The values returned by <a href="../c3ref/column_blob.html">sqlite3_column_bytes()</a> and
<a href="../c3ref/column_blob.html">sqlite3_column_bytes16()</a> do not include the zero terminators at the end
of the string. For clarity: the values returned by
<a href="../c3ref/column_blob.html">sqlite3_column_bytes()</a> and <a href="../c3ref/column_blob.html">sqlite3_column_bytes16()</a> are the number of
bytes in the string, not the number of characters.</p>
<p>Strings returned by sqlite3_column_text() and sqlite3_column_text16(),
even empty strings, are always zero-terminated. The return
value from sqlite3_column_blob() for a zero-length BLOB is a NULL pointer.</p>
<p>Strings returned by sqlite3_column_text16() always have the endianness
which is native to the platform, regardless of the text encoding set
for the database.</p>
<p><b>Warning:</b> The object returned by <a href="../c3ref/column_blob.html">sqlite3_column_value()</a> is an
<a href="../c3ref/value.html">unprotected sqlite3_value</a> object. In a multithreaded environment,
an unprotected sqlite3_value object may only be used safely with
<a href="../c3ref/bind_blob.html">sqlite3_bind_value()</a> and <a href="../c3ref/result_blob.html">sqlite3_result_value()</a>.
If the <a href="../c3ref/value.html">unprotected sqlite3_value</a> object returned by
<a href="../c3ref/column_blob.html">sqlite3_column_value()</a> is used in any other way, including calls
to routines like <a href="../c3ref/value_blob.html">sqlite3_value_int()</a>, <a href="../c3ref/value_blob.html">sqlite3_value_text()</a>,
or <a href="../c3ref/value_blob.html">sqlite3_value_bytes()</a>, the behavior is not threadsafe.
Hence, the sqlite3_column_value() interface
is normally only useful within the implementation of
<a href="../appfunc.html">application-defined SQL functions</a> or <a href="../vtab.html">virtual tables</a>, not within
top-level application code.</p>
<p>These routines may attempt to convert the datatype of the result.
For example, if the internal representation is FLOAT and a text result
is requested, <a href="../c3ref/mprintf.html">sqlite3_snprintf()</a> is used internally to perform the
conversion automatically. The following table details the conversions
that are applied:</p>
<p><blockquote>
<table border="1">
<tr><th> Internal<br>Type <th> Requested<br>Type <th> Conversion</p>
<p><tr><td> NULL <td> INTEGER <td> Result is 0
<tr><td> NULL <td> FLOAT <td> Result is 0.0
<tr><td> NULL <td> TEXT <td> Result is a NULL pointer
<tr><td> NULL <td> BLOB <td> Result is a NULL pointer
<tr><td> INTEGER <td> FLOAT <td> Convert from integer to float
<tr><td> INTEGER <td> TEXT <td> ASCII rendering of the integer
<tr><td> INTEGER <td> BLOB <td> Same as INTEGER->TEXT
<tr><td> FLOAT <td> INTEGER <td> <a href="../lang_expr.html#castexpr">CAST</a> to INTEGER
<tr><td> FLOAT <td> TEXT <td> ASCII rendering of the float
<tr><td> FLOAT <td> BLOB <td> <a href="../lang_expr.html#castexpr">CAST</a> to BLOB
<tr><td> TEXT <td> INTEGER <td> <a href="../lang_expr.html#castexpr">CAST</a> to INTEGER
<tr><td> TEXT <td> FLOAT <td> <a href="../lang_expr.html#castexpr">CAST</a> to REAL
<tr><td> TEXT <td> BLOB <td> No change
<tr><td> BLOB <td> INTEGER <td> <a href="../lang_expr.html#castexpr">CAST</a> to INTEGER
<tr><td> BLOB <td> FLOAT <td> <a href="../lang_expr.html#castexpr">CAST</a> to REAL
<tr><td> BLOB <td> TEXT <td> <a href="../lang_expr.html#castexpr">CAST</a> to TEXT, ensure zero terminator
</table>
</blockquote></p>
<p>Note that when type conversions occur, pointers returned by prior
calls to sqlite3_column_blob(), sqlite3_column_text(), and/or
sqlite3_column_text16() may be invalidated.
Type conversions and pointer invalidations might occur
in the following cases:</p>
<p><ul>
<li> The initial content is a BLOB and sqlite3_column_text() or
sqlite3_column_text16() is called. A zero-terminator might
need to be added to the string.</li>
<li> The initial content is UTF-8 text and sqlite3_column_bytes16() or
sqlite3_column_text16() is called. The content must be converted
to UTF-16.</li>
<li> The initial content is UTF-16 text and sqlite3_column_bytes() or
sqlite3_column_text() is called. The content must be converted
to UTF-8.</li>
</ul></p>
<p>Conversions between UTF-16be and UTF-16le are always done in place and do
not invalidate a prior pointer, though of course the content of the buffer
that the prior pointer references will have been modified. Other kinds
of conversion are done in place when it is possible, but sometimes they
are not possible and in those cases prior pointers are invalidated.</p>
<p>The safest policy is to invoke these routines
in one of the following ways:</p>
<p><ul>
<li>sqlite3_column_text() followed by sqlite3_column_bytes()</li>
<li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li>
<li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li>
</ul></p>
<p>In other words, you should call sqlite3_column_text(),
sqlite3_column_blob(), or sqlite3_column_text16() first to force the result
into the desired format, then invoke sqlite3_column_bytes() or
sqlite3_column_bytes16() to find the size of the result. Do not mix calls
to sqlite3_column_text() or sqlite3_column_blob() with calls to
sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16()
with calls to sqlite3_column_bytes().</p>
<p>The pointers returned are valid until a type conversion occurs as
described above, or until <a href="../c3ref/step.html">sqlite3_step()</a> or <a href="../c3ref/reset.html">sqlite3_reset()</a> or
<a href="../c3ref/finalize.html">sqlite3_finalize()</a> is called. The memory space used to hold strings
and BLOBs is freed automatically. Do not pass the pointers returned
from <a href="../c3ref/column_blob.html">sqlite3_column_blob()</a>, <a href="../c3ref/column_blob.html">sqlite3_column_text()</a>, etc. into
<a href="../c3ref/free.html">sqlite3_free()</a>.</p>
<p>As long as the input parameters are correct, these routines will 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_column_blob()
<li> sqlite3_column_text()
<li> sqlite3_column_text16()
<li> sqlite3_column_bytes()
<li> sqlite3_column_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>
|
