TSqlBlob Class Reference

Detailed Description

Utility class that provides methods for reading and writing the entire content of a blob in a single call.

The target blob is identified using the relevant database connection, table name, column name and ROWID of the record to which the blob belongs (also the attached database name if the blob is contained in an attached database).

The behaviour of the RSqlBlobReadStream class and the recommendations for using it exist for the Get() and GetLC() methods of this class. Similarly, the behaviour of the RSqlBlobWriteStream class and the recommendations for using it exist for the SetL() method of this class.

In particular, it is strongly recommended to use this class or the RSqlBlobReadStream and RSqlBlobWriteStream classes for reading and writing the content of large blobs because it significantly reduces the amount of RAM that is used when compared to using the legacy streaming and RSqlStatement APIs.

Specifically, it is recommended to use this class for blobs over 2Mb in size. Indeed, in some circumstances where very large blobs are in use it may be impossible to read or write to a blob using the legacy APIs (due to the server's finite RAM capacity), and this class or the RSqlBlobReadStream and RSqlBlobWriteStream classes may provide the only way to achieve this.

It is strongly recommended to execute calls to the SetL() method within a transaction. If a leave occurs during a call to SetL() then the current state of the blob object is undefined and a ROLLBACK should be executed to return the blob object to its previous state. Note that in order for a ROLLBACK to execute successfully all open RSqlBlobReadStream and RSqlBlobWriteStream handles and all open RSqlStatement objects must be closed before the ROLLBACK is executed.

When using SetL() to update the content of a zeroblob it is recommended, where possible, to create the zeroblob and then call SetL() within the same transaction. Otherwise the zeroblob will have to be journalled before being written to.

The following code illustrates typical use cases of this class:

CASE 1 - retrieving the entire content of a large blob.

RSqlDatabase db;
CleanupClosePushL(db);
<open/create "db" object>;
HBufC8* wholeBlob = TSqlBlob::GetLC(db, <table_name>, <column_name>, <rowid>);
<do something with the blob data>
CleanupStack::PopAndDestroy(2); // wholeBlob, db

CASE 2 - creating a 4Mb blob.

RSqlDatabase db;
CleanupClosePushL(db);
<open/create "db" object>;
CleanupStack::PushL(TCleanupItem(&DoRollback, &db)); // rollback function
TInt err = db.Exec(_L("BEGIN"));
<check err>
err = db.Exec(_L("INSERT INTO table1 VALUES(99, zeroblob(4194304))"));
<check err>
<fill a buffer 'buf' with 4Mb of blob data>
TSqlBlob::SetL(db, <table_name>, <column_name>, buf);
CleanupStack::Pop(); // TCleanupItem
err = db.Exec(_L("COMMIT")); // blob data committed to disk
<check err>
CleanupStack::PopAndDestroy(&db);

See also: RSqlBlobReadStream RSqlBlobWriteStream RSqlDatabase::LastInsertedRowId() RSqlStatement::BindZeroBlob()