diff options
Diffstat (limited to 'www/c3ref/column_blob.html')
| -rw-r--r-- | www/c3ref/column_blob.html | 347 |
1 files changed, 347 insertions, 0 deletions
diff --git a/www/c3ref/column_blob.html b/www/c3ref/column_blob.html new file mode 100644 index 0000000..baf038f --- /dev/null +++ b/www/c3ref/column_blob.html @@ -0,0 +1,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="../c3ref/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="../c3ref/objlist.html">Objects</a>, + <a href="../c3ref/constlist.html">Constants</a>, and + <a href="../c3ref/funclist.html">Functions</a>.</p> + |