13.7 Blob Class
The Blob
class defines the common properties of objects of type BLOB
. A BLOB
is a large binary object stored as a column value in a row of a database table. A Blob
object contains a logical pointer to a BLOB
, not the BLOB
itself.
Methods of the Blob
class enable you to perform specific tasks related to Blob
objects.
Methods of the ResultSet
and Statement
classes, such as getBlob()
and setBlob()
, enable you to access an SQL BLOB
value.
The only methods valid on a NULL
Blob
object are setName(), isNull(), and operator=().
An uninitialized Blob
object can be initialized by:
-
The setEmpty() method. The
BLOB
can then be modified by inserting thisBLOB
into the table and then retrieving it usingSELECT...FOR UPDATE
. The write() method modifies theBLOB
; however, the modified data is flushed to the table only when the transaction is committed. Note that an update is not required. -
Assigning an initialized
Blob
object to it.
See Also:
-
In-depth discussion of LOBs in Oracle Database SecureFiles and Large Objects Developer's Guide
Table 13-8 Summary of Blob Methods
Method | Summary |
---|---|
|
|
Appends a specified |
|
Closes a previously opened |
|
Closes the |
|
Copies a specified portion of a |
|
Returns the smallest data size to perform efficient writes to the |
|
Returns the content type of the |
|
Returns the |
|
Returns data from the |
|
Tests whether the |
|
Tests whether the |
|
Tests whether the |
|
Returns the number of bytes in the |
|
Opens the |
|
Assigns a |
|
Tests whether two |
|
Tests whether two |
|
Reads a portion of the |
|
Sets the content type of the |
|
Sets the |
|
Sets the |
|
Specifies a |
|
Truncates the |
|
Writes a buffer into an unopened |
|
Writes a buffer into an open |
13.7.1 Blob()
Blob
class constructor.
Syntax | Description |
---|---|
Blob(); |
Creates a |
Blob( const Connection *connectionp); |
Creates an uninitialized |
Blob( const Blob &srcBlob); |
Creates a copy of a |
Parameter | Description |
---|---|
connectionp |
The connection pointer |
srcBlob |
The source |
13.7.2 append()
Appends a BLOB
to the end of the current BLOB
.
Syntax
void append( const Blob &srcBlob);
Parameter | Description |
---|---|
srcBlob |
The |
13.7.4 closeStream()
Closes the Stream object obtained from the BLOB
.
Syntax
void closeStream( Stream *stream);
Parameter | Description |
---|---|
stream |
The |
13.7.5 copy()
Copies a part or all of a BFILE
or BLOB
into the current BLOB
.
Syntax | Description |
---|---|
void copy( const Bfile &srcBfile, unsigned int numBytes, unsigned int dstOffset = 1, unsigned int srcOffset = 1); |
Copies a part of a |
void copy( const Blob &srcBlob, unsigned int numBytes, unsigned int dstOffset = 1, unsigned int srcOffset = 1); |
Copies a part of a If the destination |
Parameter | Description |
---|---|
srcBfile |
The |
srcBlob |
The |
numBytes |
The number of bytes to be copied from the source |
dstOffset |
The starting position at which to begin writing data into the current |
srcOffset |
The starting position at which to begin reading data from the source |
13.7.6 getChunkSize()
Returns the smallest data size to perform efficient writes to the BLOB
.
Syntax
unsigned int getChunkSize() const;
13.7.7 getContentType()
Returns the content type of the Blob
. If a content type has not been assigned, returns a NULL
string.
Syntax
string getContentType();
13.7.8 getOptions()
Returns the BLOB
's LobOptionValue
for a specified LobOptionType
.
Throws an exception if attempting to retrieve a value for an option that is not configured on the database column or partition that stores the BLOB
.
Syntax
LobOptionValue getOptions( LobOptionType optType);
13.7.9 getStream()
Returns a Stream
object from the BLOB
. If a stream is open, it is disallowed to open another stream on Blob object
, so the user must always close the stream before performing any Blob
object operations.
Syntax
Stream* getStream( unsigned int offset = 1, unsigned int amount = 0);
Parameter | Description |
---|---|
offset |
The starting position at which to begin reading data from the |
amount |
The total number of bytes to be read from the |
13.7.10 isInitialized()
Tests whether the Blob
object is initialized. If the Blob
object is initialized, then TRUE
is returned; otherwise, FALSE
is returned.
Syntax
bool isInitialized() const;
13.7.11 isNull()
Tests whether the Blob
object is atomically NULL
. If the Blob
object is atomically NULL
, then TRUE
is returned; otherwise, FALSE
is returned.
Syntax
bool isNull() const;
13.7.12 isOpen()
Tests whether the BLOB
is open. If the BLOB
is open, then TRUE
is returned; otherwise, FALSE
is returned.
Syntax
bool isOpen() const;
13.7.14 open()
Opens the BLOB
in read/write or read-only mode.
Syntax
void open( LobOpenMode mode = OCCI_LOB_READWRITE);
Parameter | Description |
---|---|
mode |
The mode the
|
13.7.15 operator=()
Assigns a BLOB
to the current BLOB
. The source BLOB
gets copied to the destination BLOB
only when the destination BLOB
gets stored in the table.
Syntax
Blob& operator=( const Blob &srcBlob);
Parameter | Description |
---|---|
srcBlob |
The source |
13.7.16 operator==()
Compares two Blob objects
for equality. Two Blob objects
are equal if they both refer to the same BLOB
. Two NULL
Blob objects
are not considered equal. If the Blob
objects are equal, then TRUE
is returned; otherwise, FALSE
is returned.
Syntax
bool operator==( const Blob &srcBlob) const;
Parameter | Description |
---|---|
srcBlob |
The source |
13.7.17 operator!= ()
Compares two Blob objects
for inequality. Two Blob objects
are equal if they both refer to the same BLOB
. Two NULL
Blob
objects are not considered equal. If the Blob
objects are not equal, then TRUE
is returned; otherwise, FALSE
is returned.
Syntax
bool operator!=( const Blob &srcBlob) const;
Parameter | Description |
---|---|
srcBlob |
The source |
13.7.18 read()
Reads a part or all of the BLOB
into a buffer. The actual number of bytes read is returned.
Syntax
unsigned int read( unsigned int amt, unsigned char *buffer, unsigned int bufsize, unsigned int offset = 1) const;
Parameter | Description |
---|---|
amt |
The number of bytes to be read. Valid values are numbers greater than or equal to |
buffer |
The buffer that the |
buffsize |
The size of the buffer that the |
offset |
The starting position at which to begin reading data from the |
13.7.19 setContentType()
Sets the content type of the Blob
. If the Blob
is not a SecureFile, throws an exception.
Syntax
void setContentType( const string contenttype);
Parameter | Description |
---|---|
contenttype |
The content type of the |
13.7.20 setEmpty()
Sets the Blob
object to empty.
Syntax | Description |
---|---|
void setEmpty(); |
Sets the |
void setEmpty( const Connection* connectionp); |
Sets the |
Parameter | Description |
---|---|
connectionp |
The new connection pointer for the |
13.7.22 setOptions()
Specifies a LobOptionValue
for a particular LobOptionType
. Enables advanced compression, encryption and deduplication of BLOB
s. See Table 7-1 and Table 7-2.
Throws an exception if attempting to set or un-set an option that is not configured on the database column or partition that stores the BLOB
.
Throws an exception if attempting to turn off encryption in an encrypted BLOB
column.
Syntax
void setOptions( LobOptionType optType, LobOptionValue optValue);
Parameter | Description |
---|---|
optType |
The |
optValue |
The |
13.7.23 trim()
Truncates the BLOB
to the new length specified.
Syntax
void trim( unsigned int newlen);
Parameter | Description |
---|---|
newlen |
The new length of the |
13.7.24 write()
Writes data from a buffer into a BLOB
. This method implicitly opens the BLOB
, copies the buffer into the BLOB
, and implicitly closes the BLOB
. If the BLOB
is open, use writeChunk() instead. The actual number of bytes written is returned.
Syntax
unsigned int write( unsigned int amt, unsigned char *buffer, unsigned int bufsize, unsigned int offset = 1);
Parameter | Description |
---|---|
amt |
The number of bytes to be written to the |
buffer |
The buffer containing the data to be written to the |
buffsize |
The size of the |
offset |
The starting position at which to begin writing data into the |
13.7.25 writeChunk()
Writes data from a buffer into a previously opened BLOB
. The actual number of bytes written is returned.
Syntax
unsigned int writeChunk( unsigned int amount, unsigned char *buffer, unsigned int bufsize, unsigned int offset = 1);
Parameter | Description |
---|---|
amt |
The number of bytes to be written to the |
buffer |
The buffer containing the data to be written to the |
buffsize |
The size of the buffer containing the data to be written to the |
offset |
The starting position at which to begin writing data into the |