192 lines
8.2 KiB
HTML
192 lines
8.2 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>Open A BLOB For Incremental I/O</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_blob_open -->
|
|
<div class=nosearch>
|
|
<a href="intro.html"><h2>SQLite C Interface</h2></a>
|
|
<h2>Open A BLOB For Incremental I/O</h2>
|
|
</div>
|
|
<blockquote><pre>
|
|
int sqlite3_blob_open(
|
|
sqlite3*,
|
|
const char *zDb,
|
|
const char *zTable,
|
|
const char *zColumn,
|
|
sqlite3_int64 iRow,
|
|
int flags,
|
|
sqlite3_blob **ppBlob
|
|
);
|
|
</pre></blockquote>
|
|
<p>
|
|
This interfaces opens a <a href="../c3ref/blob.html">handle</a> to the BLOB located
|
|
in row iRow, column zColumn, table zTable in database zDb;
|
|
in other words, the same BLOB that would be selected by:</p>
|
|
|
|
<p><pre>
|
|
SELECT zColumn FROM zDb.zTable WHERE <a href="../lang_createtable.html#rowid">rowid</a> = iRow;
|
|
</pre></p>
|
|
|
|
<p>Parameter zDb is not the filename that contains the database, but
|
|
rather the symbolic name of the database. For attached databases, this is
|
|
the name that appears after the AS keyword in the <a href="../lang_attach.html">ATTACH</a> statement.
|
|
For the main database file, the database name is "main". For TEMP
|
|
tables, the database name is "temp".</p>
|
|
|
|
<p>If the flags parameter is non-zero, then the BLOB is opened for read
|
|
and write access. If the flags parameter is zero, the BLOB is opened for
|
|
read-only access.</p>
|
|
|
|
<p>On success, <a href="../rescode.html#ok">SQLITE_OK</a> is returned and the new <a href="../c3ref/blob.html">BLOB handle</a> is stored
|
|
in *ppBlob. Otherwise an <a href="../rescode.html">error code</a> is returned and, unless the error
|
|
code is SQLITE_MISUSE, *ppBlob is set to NULL. This means that, provided
|
|
the API is not misused, it is always safe to call <a href="../c3ref/blob_close.html">sqlite3_blob_close()</a>
|
|
on *ppBlob after this function it returns.</p>
|
|
|
|
<p>This function fails with SQLITE_ERROR if any of the following are true:
|
|
<ul>
|
|
<li> Database zDb does not exist,
|
|
<li> Table zTable does not exist within database zDb,
|
|
<li> Table zTable is a WITHOUT ROWID table,
|
|
<li> Column zColumn does not exist,
|
|
<li> Row iRow is not present in the table,
|
|
<li> The specified column of row iRow contains a value that is not
|
|
a TEXT or BLOB value,
|
|
<li> Column zColumn is part of an index, PRIMARY KEY or UNIQUE
|
|
constraint and the blob is being opened for read/write access,
|
|
<li> <a href="../foreignkeys.html">Foreign key constraints</a> are enabled,
|
|
column zColumn is part of a <a href="../foreignkeys.html#parentchild">child key</a> definition and the blob is
|
|
being opened for read/write access.
|
|
</ul></p>
|
|
|
|
<p>Unless it returns SQLITE_MISUSE, this function sets the
|
|
<a href="../c3ref/sqlite3.html">database connection</a> error code and message accessible via
|
|
<a href="../c3ref/errcode.html">sqlite3_errcode()</a> and <a href="../c3ref/errcode.html">sqlite3_errmsg()</a> and related functions.</p>
|
|
|
|
<p>A BLOB referenced by sqlite3_blob_open() may be read using the
|
|
<a href="../c3ref/blob_read.html">sqlite3_blob_read()</a> interface and modified by using
|
|
<a href="../c3ref/blob_write.html">sqlite3_blob_write()</a>. The <a href="../c3ref/blob.html">BLOB handle</a> can be moved to a
|
|
different row of the same table using the <a href="../c3ref/blob_reopen.html">sqlite3_blob_reopen()</a>
|
|
interface. However, the column, table, or database of a <a href="../c3ref/blob.html">BLOB handle</a>
|
|
cannot be changed after the <a href="../c3ref/blob.html">BLOB handle</a> is opened.</p>
|
|
|
|
<p>If the row that a BLOB handle points to is modified by an
|
|
<a href="../lang_update.html">UPDATE</a>, <a href="../lang_delete.html">DELETE</a>, or by <a href="../lang_conflict.html">ON CONFLICT</a> side-effects
|
|
then the BLOB handle is marked as "expired".
|
|
This is true if any column of the row is changed, even a column
|
|
other than the one the BLOB handle is open on.
|
|
Calls to <a href="../c3ref/blob_read.html">sqlite3_blob_read()</a> and <a href="../c3ref/blob_write.html">sqlite3_blob_write()</a> for
|
|
an expired BLOB handle fail with a return code of <a href="../rescode.html#abort">SQLITE_ABORT</a>.
|
|
Changes written into a BLOB prior to the BLOB expiring are not
|
|
rolled back by the expiration of the BLOB. Such changes will eventually
|
|
commit if the transaction continues to completion.</p>
|
|
|
|
<p>Use the <a href="../c3ref/blob_bytes.html">sqlite3_blob_bytes()</a> interface to determine the size of
|
|
the opened blob. The size of a blob may not be changed by this
|
|
interface. Use the <a href="../lang_update.html">UPDATE</a> SQL command to change the size of a
|
|
blob.</p>
|
|
|
|
<p>The <a href="../c3ref/bind_blob.html">sqlite3_bind_zeroblob()</a> and <a href="../c3ref/result_blob.html">sqlite3_result_zeroblob()</a> interfaces
|
|
and the built-in <a href="../lang_corefunc.html#zeroblob">zeroblob</a> SQL function may be used to create a
|
|
zero-filled blob to read or write using the incremental-blob interface.</p>
|
|
|
|
<p>To avoid a resource leak, every open <a href="../c3ref/blob.html">BLOB handle</a> should eventually
|
|
be released by a call to <a href="../c3ref/blob_close.html">sqlite3_blob_close()</a>.</p>
|
|
|
|
<p>See also: <a href="../c3ref/blob_close.html">sqlite3_blob_close()</a>,
|
|
<a href="../c3ref/blob_reopen.html">sqlite3_blob_reopen()</a>, <a href="../c3ref/blob_read.html">sqlite3_blob_read()</a>,
|
|
<a href="../c3ref/blob_bytes.html">sqlite3_blob_bytes()</a>, <a href="../c3ref/blob_write.html">sqlite3_blob_write()</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>
|