Debian Codegraph @

www/c3ref/blob_open.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>Open A BLOB For Incremental I/O</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: sqlite3_blob_open -->
119 <div class=nosearch>
120 <a href="../c3ref/intro.html"><h2>SQLite C Interface</h2></a>
121 <h2>Open A BLOB For Incremental I/O</h2>
122 </div>
123 <blockquote><pre>
124 int sqlite3_blob_open(
125 sqlite3*,
126 const char *zDb,
127 const char *zTable,
128 const char *zColumn,
129 sqlite3_int64 iRow,
130 int flags,
131 sqlite3_blob **ppBlob
132 );
133 </pre></blockquote>
134 <p>
135 This interfaces opens a <a href="../c3ref/blob.html">handle</a> to the BLOB located
136 in row iRow, column zColumn, table zTable in database zDb;
137 in other words, the same BLOB that would be selected by:</p>
138
139 <p><pre>
140 SELECT zColumn FROM zDb.zTable WHERE <a href="../lang_createtable.html#rowid">rowid</a> = iRow;
141 </pre></p>
142
143 <p>Parameter zDb is not the filename that contains the database, but
144 rather the symbolic name of the database. For attached databases, this is
145 the name that appears after the AS keyword in the <a href="../lang_attach.html">ATTACH</a> statement.
146 For the main database file, the database name is "main". For TEMP
147 tables, the database name is "temp".</p>
148
149 <p>If the flags parameter is non-zero, then the BLOB is opened for read
150 and write access. If the flags parameter is zero, the BLOB is opened for
151 read-only access.</p>
152
153 <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
154 in *ppBlob. Otherwise an <a href="../rescode.html">error code</a> is returned and, unless the error
155 code is SQLITE_MISUSE, *ppBlob is set to NULL. This means that, provided
156 the API is not misused, it is always safe to call <a href="../c3ref/blob_close.html">sqlite3_blob_close()</a>
157 on *ppBlob after this function returns.</p>
158
159 <p>This function fails with SQLITE_ERROR if any of the following are true:
160 <ul>
161 <li> Database zDb does not exist,
162 <li> Table zTable does not exist within database zDb,
163 <li> Table zTable is a WITHOUT ROWID table,
164 <li> Column zColumn does not exist,
165 <li> Row iRow is not present in the table,
166 <li> The specified column of row iRow contains a value that is not
167 a TEXT or BLOB value,
168 <li> Column zColumn is part of an index, PRIMARY KEY or UNIQUE
169 constraint and the blob is being opened for read/write access,
170 <li> <a href="../foreignkeys.html">Foreign key constraints</a> are enabled,
171 column zColumn is part of a <a href="../foreignkeys.html#parentchild">child key</a> definition and the blob is
172 being opened for read/write access.
173 </ul></p>
174
175 <p>Unless it returns SQLITE_MISUSE, this function sets the
176 <a href="../c3ref/sqlite3.html">database connection</a> error code and message accessible via
177 <a href="../c3ref/errcode.html">sqlite3_errcode()</a> and <a href="../c3ref/errcode.html">sqlite3_errmsg()</a> and related functions.</p>
178
179 <p>A BLOB referenced by sqlite3_blob_open() may be read using the
180 <a href="../c3ref/blob_read.html">sqlite3_blob_read()</a> interface and modified by using
181 <a href="../c3ref/blob_write.html">sqlite3_blob_write()</a>. The <a href="../c3ref/blob.html">BLOB handle</a> can be moved to a
182 different row of the same table using the <a href="../c3ref/blob_reopen.html">sqlite3_blob_reopen()</a>
183 interface. However, the column, table, or database of a <a href="../c3ref/blob.html">BLOB handle</a>
184 cannot be changed after the <a href="../c3ref/blob.html">BLOB handle</a> is opened.</p>
185
186 <p>If the row that a BLOB handle points to is modified by an
187 <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
188 then the BLOB handle is marked as "expired".
189 This is true if any column of the row is changed, even a column
190 other than the one the BLOB handle is open on.
191 Calls to <a href="../c3ref/blob_read.html">sqlite3_blob_read()</a> and <a href="../c3ref/blob_write.html">sqlite3_blob_write()</a> for
192 an expired BLOB handle fail with a return code of <a href="../rescode.html#abort">SQLITE_ABORT</a>.
193 Changes written into a BLOB prior to the BLOB expiring are not
194 rolled back by the expiration of the BLOB. Such changes will eventually
195 commit if the transaction continues to completion.</p>
196
197 <p>Use the <a href="../c3ref/blob_bytes.html">sqlite3_blob_bytes()</a> interface to determine the size of
198 the opened blob. The size of a blob may not be changed by this
199 interface. Use the <a href="../lang_update.html">UPDATE</a> SQL command to change the size of a
200 blob.</p>
201
202 <p>The <a href="../c3ref/bind_blob.html">sqlite3_bind_zeroblob()</a> and <a href="../c3ref/result_blob.html">sqlite3_result_zeroblob()</a> interfaces
203 and the built-in <a href="../lang_corefunc.html#zeroblob">zeroblob</a> SQL function may be used to create a
204 zero-filled blob to read or write using the incremental-blob interface.</p>
205
206 <p>To avoid a resource leak, every open <a href="../c3ref/blob.html">BLOB handle</a> should eventually
207 be released by a call to <a href="../c3ref/blob_close.html">sqlite3_blob_close()</a>.</p>
208
209 <p>See also: <a href="../c3ref/blob_close.html">sqlite3_blob_close()</a>,
210 <a href="../c3ref/blob_reopen.html">sqlite3_blob_reopen()</a>, <a href="../c3ref/blob_read.html">sqlite3_blob_read()</a>,
211 <a href="../c3ref/blob_bytes.html">sqlite3_blob_bytes()</a>, <a href="../c3ref/blob_write.html">sqlite3_blob_write()</a>.
212 </p><p>See also lists of
213 <a href="../c3ref/objlist.html">Objects</a>,
214 <a href="../c3ref/constlist.html">Constants</a>, and
215 <a href="../c3ref/funclist.html">Functions</a>.</p>
216