Debian Codegraph @

www/c3ref/column_blob.html

raw
1 <!DOCTYPE html>
2 <html><head>
3 <meta name="viewport" content="width=device-width, initial-scale=1.0">
4 <meta http-equiv="content-type" content="text/html; charset=UTF-8">
5 <link href="../sqlite.css" rel="stylesheet">
6 <title>Result Values From A Query</title>
7 <!-- path=../ -->
8 </head>
9 <body>
10 <div class=nosearch>
11 <a href="../index.html">
12 <img class="logo" src="../images/sqlite370_banner.svg" alt="SQLite" border="0">
13 </a>
14 <div><!-- IE hack to prevent disappearing logo --></div>
15 <div class="tagline desktoponly">
16 Small. Fast. Reliable.<br>Choose any three.
17 </div>
18 <div class="menu mainmenu">
19 <ul>
20 <li><a href="../index.html">Home</a>
21 <li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a>
22 <li class='wideonly'><a href='../about.html'>About</a>
23 <li class='desktoponly'><a href="../docs.html">Documentation</a>
24 <li class='desktoponly'><a href="../download.html">Download</a>
25 <li class='wideonly'><a href='../copyright.html'>License</a>
26 <li class='desktoponly'><a href="../support.html">Support</a>
27 <li class='desktoponly'><a href="../prosupport.html">Purchase</a>
28 <li class='search' id='search_menubutton'>
29 <a href="javascript:void(0)" onclick='toggle_search()'>Search</a>
30 </ul>
31 </div>
32 <div class="menu submenu" id="submenu">
33 <ul>
34 <li><a href='../about.html'>About</a>
35 <li><a href='../docs.html'>Documentation</a>
36 <li><a href='../download.html'>Download</a>
37 <li><a href='../support.html'>Support</a>
38 <li><a href='../prosupport.html'>Purchase</a>
39 </ul>
40 </div>
41 <div class="searchmenu" id="searchmenu">
42 <form method="GET" action="../search">
43 <select name="s" id="searchtype">
44 <option value="d">Search Documentation</option>
45 <option value="c">Search Changelog</option>
46 </select>
47 <input type="text" name="q" id="searchbox" value="">
48 <input type="submit" value="Go">
49 </form>
50 </div>
51 </div>
52 <script>
53 function toggle_div(nm) {
54 var w = document.getElementById(nm);
55 if( w.style.display=="block" ){
56 w.style.display = "none";
57 }else{
58 w.style.display = "block";
59 }
60 }
61 function toggle_search() {
62 var w = document.getElementById("searchmenu");
63 if( w.style.display=="block" ){
64 w.style.display = "none";
65 } else {
66 w.style.display = "block";
67 setTimeout(function(){
68 document.getElementById("searchbox").focus()
69 }, 30);
70 }
71 }
72 function div_off(nm){document.getElementById(nm).style.display="none";}
73 window.onbeforeunload = function(e){div_off("submenu");}
74 /* Disable the Search feature if we are not operating from CGI, since */
75 /* Search is accomplished using CGI and will not work without it. */
76 if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){
77 document.getElementById("search_menubutton").style.display = "none";
78 }
79 /* Used by the Hide/Show button beside syntax diagrams, to toggle the */
80 function hideorshow(btn,obj){
81 var x = document.getElementById(obj);
82 var b = document.getElementById(btn);
83 if( x.style.display!='none' ){
84 x.style.display = 'none';
85 b.innerHTML='show';
86 }else{
87 x.style.display = '';
88 b.innerHTML='hide';
89 }
90 return false;
91 }
92 var antiRobot = 0;
93 function antiRobotGo(){
94 if( antiRobot!=3 ) return;
95 antiRobot = 7;
96 var j = document.getElementById("mtimelink");
97 if(j && j.hasAttribute("data-href")) j.href=j.getAttribute("data-href");
98 }
99 function antiRobotDefense(){
100 document.body.onmousedown=function(){
101 antiRobot |= 2;
102 antiRobotGo();
103 document.body.onmousedown=null;
104 }
105 document.body.onmousemove=function(){
106 antiRobot |= 2;
107 antiRobotGo();
108 document.body.onmousemove=null;
109 }
110 setTimeout(function(){
111 antiRobot |= 1;
112 antiRobotGo();
113 }, 100)
114 antiRobotGo();
115 }
116 antiRobotDefense();
117 </script>
118 <!-- 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 -->
119 <div class=nosearch>
120 <a href="../c3ref/intro.html"><h2>SQLite C Interface</h2></a>
121 <h2>Result Values From A Query</h2>
122 </div>
123 <blockquote><pre>
124 const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
125 double sqlite3_column_double(sqlite3_stmt*, int iCol);
126 int sqlite3_column_int(sqlite3_stmt*, int iCol);
127 sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);
128 const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
129 const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
130 sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);
131 int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
132 int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
133 int sqlite3_column_type(sqlite3_stmt*, int iCol);
134 </pre></blockquote>
135 <p>
136 <b>Summary:</b>
137 <blockquote><table border=0 cellpadding=0 cellspacing=0>
138 <tr><td><b>sqlite3_column_blob</b><td>&rarr;<td>BLOB result
139 <tr><td><b>sqlite3_column_double</b><td>&rarr;<td>REAL result
140 <tr><td><b>sqlite3_column_int</b><td>&rarr;<td>32-bit INTEGER result
141 <tr><td><b>sqlite3_column_int64</b><td>&rarr;<td>64-bit INTEGER result
142 <tr><td><b>sqlite3_column_text</b><td>&rarr;<td>UTF-8 TEXT result
143 <tr><td><b>sqlite3_column_text16</b><td>&rarr;<td>UTF-16 TEXT result
144 <tr><td><b>sqlite3_column_value</b><td>&rarr;<td>The result as an
145 <a href="../c3ref/value.html">unprotected sqlite3_value</a> object.
146 <tr><td>&nbsp;<td>&nbsp;<td>&nbsp;
147 <tr><td><b>sqlite3_column_bytes</b><td>&rarr;<td>Size of a BLOB
148 or a UTF-8 TEXT result in bytes
149 <tr><td><b>sqlite3_column_bytes16&nbsp;&nbsp;</b>
150 <td>&rarr;&nbsp;&nbsp;<td>Size of UTF-16
151 TEXT in bytes
152 <tr><td><b>sqlite3_column_type</b><td>&rarr;<td>Default
153 datatype of the result
154 </table></blockquote></p>
155
156 <p><b>Details:</b></p>
157
158 <p>These routines return information about a single column of the current
159 result row of a query. In every case the first argument is a pointer
160 to the <a href="../c3ref/stmt.html">prepared statement</a> that is being evaluated (the <a href="../c3ref/stmt.html">sqlite3_stmt*</a>
161 that was returned from <a href="../c3ref/prepare.html">sqlite3_prepare_v2()</a> or one of its variants)
162 and the second argument is the index of the column for which information
163 should be returned. The leftmost column of the result set has the index 0.
164 The number of columns in the result can be determined using
165 <a href="../c3ref/column_count.html">sqlite3_column_count()</a>.</p>
166
167 <p>If the SQL statement does not currently point to a valid row, or if the
168 column index is out of range, the result is undefined.
169 These routines may only be called when the most recent call to
170 <a href="../c3ref/step.html">sqlite3_step()</a> has returned <a href="../rescode.html#row">SQLITE_ROW</a> and neither
171 <a href="../c3ref/reset.html">sqlite3_reset()</a> nor <a href="../c3ref/finalize.html">sqlite3_finalize()</a> have been called subsequently.
172 If any of these routines are called after <a href="../c3ref/reset.html">sqlite3_reset()</a> or
173 <a href="../c3ref/finalize.html">sqlite3_finalize()</a> or after <a href="../c3ref/step.html">sqlite3_step()</a> has returned
174 something other than <a href="../rescode.html#row">SQLITE_ROW</a>, the results are undefined.
175 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>
176 are called from a different thread while any of these routines
177 are pending, then the results are undefined.</p>
178
179 <p>The first six interfaces (_blob, _double, _int, _int64, _text, and _text16)
180 each return the value of a result column in a specific data format. If
181 the result column is not initially in the requested format (for example,
182 if the query returns an integer but the sqlite3_column_text() interface
183 is used to extract the value) then an automatic type conversion is performed.</p>
184
185 <p>The sqlite3_column_type() routine returns the
186 <a href="../c3ref/c_blob.html">datatype code</a> for the initial data type
187 of the result column. The returned value is one of <a href="../c3ref/c_blob.html">SQLITE_INTEGER</a>,
188 <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>.
189 The return value of sqlite3_column_type() can be used to decide which
190 of the first six interface should be used to extract the column value.
191 The value returned by sqlite3_column_type() is only meaningful if no
192 automatic type conversions have occurred for the value in question.
193 After a type conversion, the result of calling sqlite3_column_type()
194 is undefined, though harmless. Future
195 versions of SQLite may change the behavior of sqlite3_column_type()
196 following a type conversion.</p>
197
198 <p>If the result is a BLOB or a TEXT string, then the sqlite3_column_bytes()
199 or sqlite3_column_bytes16() interfaces can be used to determine the size
200 of that BLOB or string.</p>
201
202 <p>If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes()
203 routine returns the number of bytes in that BLOB or string.
204 If the result is a UTF-16 string, then sqlite3_column_bytes() converts
205 the string to UTF-8 and then returns the number of bytes.
206 If the result is a numeric value then sqlite3_column_bytes() uses
207 <a href="../c3ref/mprintf.html">sqlite3_snprintf()</a> to convert that value to a UTF-8 string and returns
208 the number of bytes in that string.
209 If the result is NULL, then sqlite3_column_bytes() returns zero.</p>
210
211 <p>If the result is a BLOB or UTF-16 string then the sqlite3_column_bytes16()
212 routine returns the number of bytes in that BLOB or string.
213 If the result is a UTF-8 string, then sqlite3_column_bytes16() converts
214 the string to UTF-16 and then returns the number of bytes.
215 If the result is a numeric value then sqlite3_column_bytes16() uses
216 <a href="../c3ref/mprintf.html">sqlite3_snprintf()</a> to convert that value to a UTF-16 string and returns
217 the number of bytes in that string.
218 If the result is NULL, then sqlite3_column_bytes16() returns zero.</p>
219
220 <p>The values returned by <a href="../c3ref/column_blob.html">sqlite3_column_bytes()</a> and
221 <a href="../c3ref/column_blob.html">sqlite3_column_bytes16()</a> do not include the zero terminators at the end
222 of the string. For clarity: the values returned by
223 <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
224 bytes in the string, not the number of characters.</p>
225
226 <p>Strings returned by sqlite3_column_text() and sqlite3_column_text16(),
227 even empty strings, are always zero-terminated. The return
228 value from sqlite3_column_blob() for a zero-length BLOB is a NULL pointer.</p>
229
230 <p>Strings returned by sqlite3_column_text16() always have the endianness
231 which is native to the platform, regardless of the text encoding set
232 for the database.</p>
233
234 <p><b>Warning:</b> The object returned by <a href="../c3ref/column_blob.html">sqlite3_column_value()</a> is an
235 <a href="../c3ref/value.html">unprotected sqlite3_value</a> object. In a multithreaded environment,
236 an unprotected sqlite3_value object may only be used safely with
237 <a href="../c3ref/bind_blob.html">sqlite3_bind_value()</a> and <a href="../c3ref/result_blob.html">sqlite3_result_value()</a>.
238 If the <a href="../c3ref/value.html">unprotected sqlite3_value</a> object returned by
239 <a href="../c3ref/column_blob.html">sqlite3_column_value()</a> is used in any other way, including calls
240 to routines like <a href="../c3ref/value_blob.html">sqlite3_value_int()</a>, <a href="../c3ref/value_blob.html">sqlite3_value_text()</a>,
241 or <a href="../c3ref/value_blob.html">sqlite3_value_bytes()</a>, the behavior is not threadsafe.
242 Hence, the sqlite3_column_value() interface
243 is normally only useful within the implementation of
244 <a href="../appfunc.html">application-defined SQL functions</a> or <a href="../vtab.html">virtual tables</a>, not within
245 top-level application code.</p>
246
247 <p>These routines may attempt to convert the datatype of the result.
248 For example, if the internal representation is FLOAT and a text result
249 is requested, <a href="../c3ref/mprintf.html">sqlite3_snprintf()</a> is used internally to perform the
250 conversion automatically. The following table details the conversions
251 that are applied:</p>
252
253 <p><blockquote>
254 <table border="1">
255 <tr><th> Internal<br>Type <th> Requested<br>Type <th> Conversion</p>
256
257 <p><tr><td> NULL <td> INTEGER <td> Result is 0
258 <tr><td> NULL <td> FLOAT <td> Result is 0.0
259 <tr><td> NULL <td> TEXT <td> Result is a NULL pointer
260 <tr><td> NULL <td> BLOB <td> Result is a NULL pointer
261 <tr><td> INTEGER <td> FLOAT <td> Convert from integer to float
262 <tr><td> INTEGER <td> TEXT <td> ASCII rendering of the integer
263 <tr><td> INTEGER <td> BLOB <td> Same as INTEGER->TEXT
264 <tr><td> FLOAT <td> INTEGER <td> <a href="../lang_expr.html#castexpr">CAST</a> to INTEGER
265 <tr><td> FLOAT <td> TEXT <td> ASCII rendering of the float
266 <tr><td> FLOAT <td> BLOB <td> <a href="../lang_expr.html#castexpr">CAST</a> to BLOB
267 <tr><td> TEXT <td> INTEGER <td> <a href="../lang_expr.html#castexpr">CAST</a> to INTEGER
268 <tr><td> TEXT <td> FLOAT <td> <a href="../lang_expr.html#castexpr">CAST</a> to REAL
269 <tr><td> TEXT <td> BLOB <td> No change
270 <tr><td> BLOB <td> INTEGER <td> <a href="../lang_expr.html#castexpr">CAST</a> to INTEGER
271 <tr><td> BLOB <td> FLOAT <td> <a href="../lang_expr.html#castexpr">CAST</a> to REAL
272 <tr><td> BLOB <td> TEXT <td> <a href="../lang_expr.html#castexpr">CAST</a> to TEXT, ensure zero terminator
273 </table>
274 </blockquote></p>
275
276 <p>Note that when type conversions occur, pointers returned by prior
277 calls to sqlite3_column_blob(), sqlite3_column_text(), and/or
278 sqlite3_column_text16() may be invalidated.
279 Type conversions and pointer invalidations might occur
280 in the following cases:</p>
281
282 <p><ul>
283 <li> The initial content is a BLOB and sqlite3_column_text() or
284 sqlite3_column_text16() is called. A zero-terminator might
285 need to be added to the string.</li>
286 <li> The initial content is UTF-8 text and sqlite3_column_bytes16() or
287 sqlite3_column_text16() is called. The content must be converted
288 to UTF-16.</li>
289 <li> The initial content is UTF-16 text and sqlite3_column_bytes() or
290 sqlite3_column_text() is called. The content must be converted
291 to UTF-8.</li>
292 </ul></p>
293
294 <p>Conversions between UTF-16be and UTF-16le are always done in place and do
295 not invalidate a prior pointer, though of course the content of the buffer
296 that the prior pointer references will have been modified. Other kinds
297 of conversion are done in place when it is possible, but sometimes they
298 are not possible and in those cases prior pointers are invalidated.</p>
299
300 <p>The safest policy is to invoke these routines
301 in one of the following ways:</p>
302
303 <p><ul>
304 <li>sqlite3_column_text() followed by sqlite3_column_bytes()</li>
305 <li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li>
306 <li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li>
307 </ul></p>
308
309 <p>In other words, you should call sqlite3_column_text(),
310 sqlite3_column_blob(), or sqlite3_column_text16() first to force the result
311 into the desired format, then invoke sqlite3_column_bytes() or
312 sqlite3_column_bytes16() to find the size of the result. Do not mix calls
313 to sqlite3_column_text() or sqlite3_column_blob() with calls to
314 sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16()
315 with calls to sqlite3_column_bytes().</p>
316
317 <p>The pointers returned are valid until a type conversion occurs as
318 described above, or until <a href="../c3ref/step.html">sqlite3_step()</a> or <a href="../c3ref/reset.html">sqlite3_reset()</a> or
319 <a href="../c3ref/finalize.html">sqlite3_finalize()</a> is called. The memory space used to hold strings
320 and BLOBs is freed automatically. Do not pass the pointers returned
321 from <a href="../c3ref/column_blob.html">sqlite3_column_blob()</a>, <a href="../c3ref/column_blob.html">sqlite3_column_text()</a>, etc. into
322 <a href="../c3ref/free.html">sqlite3_free()</a>.</p>
323
324 <p>As long as the input parameters are correct, these routines will only
325 fail if an out-of-memory error occurs during a format conversion.
326 Only the following subset of interfaces are subject to out-of-memory
327 errors:</p>
328
329 <p><ul>
330 <li> sqlite3_column_blob()
331 <li> sqlite3_column_text()
332 <li> sqlite3_column_text16()
333 <li> sqlite3_column_bytes()
334 <li> sqlite3_column_bytes16()
335 </ul></p>
336
337 <p>If an out-of-memory error occurs, then the return value from these
338 routines is the same as if the column had contained an SQL NULL value.
339 Valid SQL NULL returns can be distinguished from out-of-memory errors
340 by invoking the <a href="../c3ref/errcode.html">sqlite3_errcode()</a> immediately after the suspect
341 return value is obtained and before any
342 other SQLite interface is called on the same <a href="../c3ref/sqlite3.html">database connection</a>.
343 </p><p>See also lists of
344 <a href="../c3ref/objlist.html">Objects</a>,
345 <a href="../c3ref/constlist.html">Constants</a>, and
346 <a href="../c3ref/funclist.html">Functions</a>.</p>
347