4 ** The author disclaims copyright to this source code. In place of
5 ** a legal notice, here is a blessing:
7 ** May you do good and not evil.
8 ** May you find forgiveness for yourself and forgive others.
9 ** May you share freely, never taking more than you give.
11 *************************************************************************
13 ** This file contains code used to implement incremental BLOB I/O.
16 #include "sqliteInt.h"
19 #ifndef SQLITE_OMIT_INCRBLOB
22 ** Valid sqlite3_blob* handles point to Incrblob structures.
24 typedef struct Incrblob Incrblob
;
26 int flags
; /* Copy of "flags" passed to sqlite3_blob_open() */
27 int nByte
; /* Size of open blob, in bytes */
28 int iOffset
; /* Byte offset of blob in cursor data */
29 int iCol
; /* Table column this handle is open on */
30 BtCursor
*pCsr
; /* Cursor pointing at blob row */
31 sqlite3_stmt
*pStmt
; /* Statement holding cursor open */
32 sqlite3
*db
; /* The associated database */
37 ** This function is used by both blob_open() and blob_reopen(). It seeks
38 ** the b-tree cursor associated with blob handle p to point to row iRow.
39 ** If successful, SQLITE_OK is returned and subsequent calls to
40 ** sqlite3_blob_read() or sqlite3_blob_write() access the specified row.
42 ** If an error occurs, or if the specified row does not exist or does not
43 ** contain a value of type TEXT or BLOB in the column nominated when the
44 ** blob handle was opened, then an error code is returned and *pzErr may
45 ** be set to point to a buffer containing an error message. It is the
46 ** responsibility of the caller to free the error message buffer using
49 ** If an error does occur, then the b-tree cursor is closed. All subsequent
50 ** calls to sqlite3_blob_read(), blob_write() or blob_reopen() will
51 ** immediately return SQLITE_ABORT.
53 static int blobSeekToRow(Incrblob
*p
, sqlite3_int64 iRow
, char **pzErr
){
54 int rc
; /* Error code */
55 char *zErr
= 0; /* Error message */
56 Vdbe
*v
= (Vdbe
*)p
->pStmt
;
58 /* Set the value of the SQL statements only variable to integer iRow.
59 ** This is done directly instead of using sqlite3_bind_int64() to avoid
60 ** triggering asserts related to mutexes.
62 assert( v
->aVar
[0].flags
&MEM_Int
);
63 v
->aVar
[0].u
.i
= iRow
;
65 rc
= sqlite3_step(p
->pStmt
);
67 VdbeCursor
*pC
= v
->apCsr
[0];
68 u32 type
= pC
->aType
[p
->iCol
];
70 zErr
= sqlite3MPrintf(p
->db
, "cannot open value of type %s",
71 type
==0?"null": type
==7?"real": "integer"
74 sqlite3_finalize(p
->pStmt
);
77 p
->iOffset
= pC
->aType
[p
->iCol
+ pC
->nField
];
78 p
->nByte
= sqlite3VdbeSerialTypeLen(type
);
79 p
->pCsr
= pC
->pCursor
;
80 sqlite3BtreeEnterCursor(p
->pCsr
);
81 sqlite3BtreeCacheOverflow(p
->pCsr
);
82 sqlite3BtreeLeaveCursor(p
->pCsr
);
89 rc
= sqlite3_finalize(p
->pStmt
);
92 zErr
= sqlite3MPrintf(p
->db
, "no such rowid: %lld", iRow
);
95 zErr
= sqlite3MPrintf(p
->db
, "%s", sqlite3_errmsg(p
->db
));
99 assert( rc
!=SQLITE_OK
|| zErr
==0 );
100 assert( rc
!=SQLITE_ROW
&& rc
!=SQLITE_DONE
);
107 ** Open a blob handle.
109 int sqlite3_blob_open(
110 sqlite3
* db
, /* The database connection */
111 const char *zDb
, /* The attached database containing the blob */
112 const char *zTable
, /* The table containing the blob */
113 const char *zColumn
, /* The column containing the blob */
114 sqlite_int64 iRow
, /* The row containing the glob */
115 int flags
, /* True -> read/write access, false -> read-only */
116 sqlite3_blob
**ppBlob
/* Handle for accessing the blob returned here */
119 int iCol
; /* Index of zColumn in row-record */
121 /* This VDBE program seeks a btree cursor to the identified
122 ** db/table/row entry. The reason for using a vdbe program instead
123 ** of writing code to use the b-tree layer directly is that the
124 ** vdbe program will take advantage of the various transaction,
125 ** locking and error handling infrastructure built into the vdbe.
127 ** After seeking the cursor, the vdbe executes an OP_ResultRow.
128 ** Code external to the Vdbe then "borrows" the b-tree cursor and
129 ** uses it to implement the blob_read(), blob_write() and
130 ** blob_bytes() functions.
132 ** The sqlite3_blob_close() function finalizes the vdbe program,
133 ** which closes the b-tree cursor and (possibly) commits the
136 static const int iLn
= VDBE_OFFSET_LINENO(4);
137 static const VdbeOpList openBlob
[] = {
138 /* {OP_Transaction, 0, 0, 0}, // 0: Inserted separately */
139 {OP_TableLock
, 0, 0, 0}, /* 1: Acquire a read or write lock */
140 /* One of the following two instructions is replaced by an OP_Noop. */
141 {OP_OpenRead
, 0, 0, 0}, /* 2: Open cursor 0 for reading */
142 {OP_OpenWrite
, 0, 0, 0}, /* 3: Open cursor 0 for read/write */
143 {OP_Variable
, 1, 1, 1}, /* 4: Push the rowid to the stack */
144 {OP_NotExists
, 0, 10, 1}, /* 5: Seek the cursor */
145 {OP_Column
, 0, 0, 1}, /* 6 */
146 {OP_ResultRow
, 1, 0, 0}, /* 7 */
147 {OP_Goto
, 0, 4, 0}, /* 8 */
148 {OP_Close
, 0, 0, 0}, /* 9 */
149 {OP_Halt
, 0, 0, 0}, /* 10 */
158 flags
= !!flags
; /* flags = (flags ? 1 : 0); */
161 sqlite3_mutex_enter(db
->mutex
);
163 pBlob
= (Incrblob
*)sqlite3DbMallocZero(db
, sizeof(Incrblob
));
164 if( !pBlob
) goto blob_open_out
;
165 pParse
= sqlite3StackAllocRaw(db
, sizeof(*pParse
));
166 if( !pParse
) goto blob_open_out
;
169 memset(pParse
, 0, sizeof(Parse
));
171 sqlite3DbFree(db
, zErr
);
174 sqlite3BtreeEnterAll(db
);
175 pTab
= sqlite3LocateTable(pParse
, 0, zTable
, zDb
);
176 if( pTab
&& IsVirtual(pTab
) ){
178 sqlite3ErrorMsg(pParse
, "cannot open virtual table: %s", zTable
);
180 if( pTab
&& !HasRowid(pTab
) ){
182 sqlite3ErrorMsg(pParse
, "cannot open table without rowid: %s", zTable
);
184 #ifndef SQLITE_OMIT_VIEW
185 if( pTab
&& pTab
->pSelect
){
187 sqlite3ErrorMsg(pParse
, "cannot open view: %s", zTable
);
191 if( pParse
->zErrMsg
){
192 sqlite3DbFree(db
, zErr
);
193 zErr
= pParse
->zErrMsg
;
197 sqlite3BtreeLeaveAll(db
);
201 /* Now search pTab for the exact column. */
202 for(iCol
=0; iCol
<pTab
->nCol
; iCol
++) {
203 if( sqlite3StrICmp(pTab
->aCol
[iCol
].zName
, zColumn
)==0 ){
207 if( iCol
==pTab
->nCol
){
208 sqlite3DbFree(db
, zErr
);
209 zErr
= sqlite3MPrintf(db
, "no such column: \"%s\"", zColumn
);
211 sqlite3BtreeLeaveAll(db
);
215 /* If the value is being opened for writing, check that the
216 ** column is not indexed, and that it is not part of a foreign key.
217 ** It is against the rules to open a column to which either of these
218 ** descriptions applies for writing. */
220 const char *zFault
= 0;
222 #ifndef SQLITE_OMIT_FOREIGN_KEY
223 if( db
->flags
&SQLITE_ForeignKeys
){
224 /* Check that the column is not part of an FK child key definition. It
225 ** is not necessary to check if it is part of a parent key, as parent
226 ** key columns must be indexed. The check below will pick up this
229 for(pFKey
=pTab
->pFKey
; pFKey
; pFKey
=pFKey
->pNextFrom
){
231 for(j
=0; j
<pFKey
->nCol
; j
++){
232 if( pFKey
->aCol
[j
].iFrom
==iCol
){
233 zFault
= "foreign key";
239 for(pIdx
=pTab
->pIndex
; pIdx
; pIdx
=pIdx
->pNext
){
241 for(j
=0; j
<pIdx
->nKeyCol
; j
++){
242 if( pIdx
->aiColumn
[j
]==iCol
){
248 sqlite3DbFree(db
, zErr
);
249 zErr
= sqlite3MPrintf(db
, "cannot open %s column for writing", zFault
);
251 sqlite3BtreeLeaveAll(db
);
256 pBlob
->pStmt
= (sqlite3_stmt
*)sqlite3VdbeCreate(pParse
);
257 assert( pBlob
->pStmt
|| db
->mallocFailed
);
259 Vdbe
*v
= (Vdbe
*)pBlob
->pStmt
;
260 int iDb
= sqlite3SchemaToIndex(db
, pTab
->pSchema
);
263 sqlite3VdbeAddOp4Int(v
, OP_Transaction
, iDb
, flags
,
264 pTab
->pSchema
->schema_cookie
,
265 pTab
->pSchema
->iGeneration
);
266 sqlite3VdbeChangeP5(v
, 1);
267 sqlite3VdbeAddOpList(v
, ArraySize(openBlob
), openBlob
, iLn
);
269 /* Make sure a mutex is held on the table to be accessed */
270 sqlite3VdbeUsesBtree(v
, iDb
);
272 /* Configure the OP_TableLock instruction */
273 #ifdef SQLITE_OMIT_SHARED_CACHE
274 sqlite3VdbeChangeToNoop(v
, 1);
276 sqlite3VdbeChangeP1(v
, 1, iDb
);
277 sqlite3VdbeChangeP2(v
, 1, pTab
->tnum
);
278 sqlite3VdbeChangeP3(v
, 1, flags
);
279 sqlite3VdbeChangeP4(v
, 1, pTab
->zName
, P4_TRANSIENT
);
282 /* Remove either the OP_OpenWrite or OpenRead. Set the P2
283 ** parameter of the other to pTab->tnum. */
284 sqlite3VdbeChangeToNoop(v
, 3 - flags
);
285 sqlite3VdbeChangeP2(v
, 2 + flags
, pTab
->tnum
);
286 sqlite3VdbeChangeP3(v
, 2 + flags
, iDb
);
288 /* Configure the number of columns. Configure the cursor to
289 ** think that the table has one more column than it really
290 ** does. An OP_Column to retrieve this imaginary column will
291 ** always return an SQL NULL. This is useful because it means
292 ** we can invoke OP_Column to fill in the vdbe cursors type
293 ** and offset cache without causing any IO.
295 sqlite3VdbeChangeP4(v
, 2+flags
, SQLITE_INT_TO_PTR(pTab
->nCol
+1),P4_INT32
);
296 sqlite3VdbeChangeP2(v
, 6, pTab
->nCol
);
297 if( !db
->mallocFailed
){
301 sqlite3VdbeMakeReady(v
, pParse
);
305 pBlob
->flags
= flags
;
308 sqlite3BtreeLeaveAll(db
);
309 if( db
->mallocFailed
){
312 sqlite3_bind_int64(pBlob
->pStmt
, 1, iRow
);
313 rc
= blobSeekToRow(pBlob
, iRow
, &zErr
);
314 } while( (++nAttempt
)<SQLITE_MAX_SCHEMA_RETRY
&& rc
==SQLITE_SCHEMA
);
317 if( rc
==SQLITE_OK
&& db
->mallocFailed
==0 ){
318 *ppBlob
= (sqlite3_blob
*)pBlob
;
320 if( pBlob
&& pBlob
->pStmt
) sqlite3VdbeFinalize((Vdbe
*)pBlob
->pStmt
);
321 sqlite3DbFree(db
, pBlob
);
323 sqlite3Error(db
, rc
, (zErr
? "%s" : 0), zErr
);
324 sqlite3DbFree(db
, zErr
);
325 sqlite3ParserReset(pParse
);
326 sqlite3StackFree(db
, pParse
);
327 rc
= sqlite3ApiExit(db
, rc
);
328 sqlite3_mutex_leave(db
->mutex
);
333 ** Close a blob handle that was previously created using
334 ** sqlite3_blob_open().
336 int sqlite3_blob_close(sqlite3_blob
*pBlob
){
337 Incrblob
*p
= (Incrblob
*)pBlob
;
343 sqlite3_mutex_enter(db
->mutex
);
344 rc
= sqlite3_finalize(p
->pStmt
);
345 sqlite3DbFree(db
, p
);
346 sqlite3_mutex_leave(db
->mutex
);
354 ** Perform a read or write operation on a blob
356 static int blobReadWrite(
361 int (*xCall
)(BtCursor
*, u32
, u32
, void*)
364 Incrblob
*p
= (Incrblob
*)pBlob
;
368 if( p
==0 ) return SQLITE_MISUSE_BKPT
;
370 sqlite3_mutex_enter(db
->mutex
);
373 if( n
<0 || iOffset
<0 || (iOffset
+n
)>p
->nByte
){
374 /* Request is out of range. Return a transient error. */
376 sqlite3Error(db
, SQLITE_ERROR
, 0);
378 /* If there is no statement handle, then the blob-handle has
379 ** already been invalidated. Return SQLITE_ABORT in this case.
383 /* Call either BtreeData() or BtreePutData(). If SQLITE_ABORT is
384 ** returned, clean-up the statement handle.
386 assert( db
== v
->db
);
387 sqlite3BtreeEnterCursor(p
->pCsr
);
388 rc
= xCall(p
->pCsr
, iOffset
+p
->iOffset
, n
, z
);
389 sqlite3BtreeLeaveCursor(p
->pCsr
);
390 if( rc
==SQLITE_ABORT
){
391 sqlite3VdbeFinalize(v
);
398 rc
= sqlite3ApiExit(db
, rc
);
399 sqlite3_mutex_leave(db
->mutex
);
404 ** Read data from a blob handle.
406 int sqlite3_blob_read(sqlite3_blob
*pBlob
, void *z
, int n
, int iOffset
){
407 return blobReadWrite(pBlob
, z
, n
, iOffset
, sqlite3BtreeData
);
411 ** Write data to a blob handle.
413 int sqlite3_blob_write(sqlite3_blob
*pBlob
, const void *z
, int n
, int iOffset
){
414 return blobReadWrite(pBlob
, (void *)z
, n
, iOffset
, sqlite3BtreePutData
);
418 ** Query a blob handle for the size of the data.
420 ** The Incrblob.nByte field is fixed for the lifetime of the Incrblob
421 ** so no mutex is required for access.
423 int sqlite3_blob_bytes(sqlite3_blob
*pBlob
){
424 Incrblob
*p
= (Incrblob
*)pBlob
;
425 return (p
&& p
->pStmt
) ? p
->nByte
: 0;
429 ** Move an existing blob handle to point to a different row of the same
432 ** If an error occurs, or if the specified row does not exist or does not
433 ** contain a blob or text value, then an error code is returned and the
434 ** database handle error code and message set. If this happens, then all
435 ** subsequent calls to sqlite3_blob_xxx() functions (except blob_close())
436 ** immediately return SQLITE_ABORT.
438 int sqlite3_blob_reopen(sqlite3_blob
*pBlob
, sqlite3_int64 iRow
){
440 Incrblob
*p
= (Incrblob
*)pBlob
;
443 if( p
==0 ) return SQLITE_MISUSE_BKPT
;
445 sqlite3_mutex_enter(db
->mutex
);
448 /* If there is no statement handle, then the blob-handle has
449 ** already been invalidated. Return SQLITE_ABORT in this case.
454 rc
= blobSeekToRow(p
, iRow
, &zErr
);
456 sqlite3Error(db
, rc
, (zErr
? "%s" : 0), zErr
);
457 sqlite3DbFree(db
, zErr
);
459 assert( rc
!=SQLITE_SCHEMA
);
462 rc
= sqlite3ApiExit(db
, rc
);
463 assert( rc
==SQLITE_OK
|| p
->pStmt
==0 );
464 sqlite3_mutex_leave(db
->mutex
);
468 #endif /* #ifndef SQLITE_OMIT_INCRBLOB */