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.

To create a null Blob object, use the syntax:

Blob();

The only methods valid on a null Blob object are setNull(), isNull(), and operator=().

To create an uninitialized Blob object, use the syntax:

Blob(const Connection *connectionp);

An uninitialized Blob object can be initialized by:

• The setEmpty() method. The BLOB can then be modified by inserting this BLOB into the table and then retrieving it using SELECT ... FOR UPDATE. The write() method will modify the BLOB; however, the modified data will be flushed to the table only when the transaction is committed. Note that an update is not required.
• Assigning an initialized Blob object to it.

To create a copy of a Blob object, use the syntax:

Blob(const Blob &srcBlob);

Summary of Blob Methods

Table 8-3 Blob Methods  

Method	Summary
append()	Append a specified BLOB to the end of the current BLOB.
close()	Close a previously opened BLOB.
closeStream()	Close the Stream object obtained from the BLOB.
copy()	Copy a specified portion of a BFILE or BLOB into the current BLOB.
getChunkSize()	Return the chunk size of the BLOB.
getStream()	Return data from the BLOB as a Stream object.
isInitialized()	Test whether the Blob object is initialized
isNull()	Test whether the Blob object is atomically null.
isOpen()	Test whether the BLOB is open
length()	Return the number of bytes in the BLOB.
open()	Open the BLOB with read or read/write access.
operator=()	Assign a BLOB locator to the Blob object.
operator==()	Test whether two Blob objects are equal.
operator!= ()	Test whether two Blob objects are not equal.
read()	Read a portion of the BLOB into a buffer.
setEmpty()	Set the Blob object to empty.
setEmpty()	Set the Blob object to empty and initializes the connection pointer to the passed parameter.
setNull()	Set the Blob object to atomically null.
trim()	Truncate the BLOB to a specified length.
write()	Write a buffer into an unopened BLOB.
writeChunk()	Write a buffer into an open BLOB.

append()

This method appends a BLOB to the end of the current BLOB.

Syntax

void append(const Blob &srcBlob);

Parameters

srcBlob

The BLOB to be appended to the current BLOB.

close()

This method closes a BLOB.

Syntax

void close();

closeStream()

This method closes the Stream object obtained from the BLOB.

Syntax

void closeStream(Stream *stream);

Parameters

stream

The Stream object to be closed.

copy()

This method copies a part or all of the BFILE or BLOB into the current BLOB.

Syntax

There are variants of syntax:

void copy(const Bfile &srcBfile,
   unsigned int numBytes,
   unsigned int dstOffset = 1,
   unsigned int srcOffset = 1);

void copy(const Blob &srcBlob,
   unsigned int numBytes,
   unsigned int dstOffset = 1,
   unsigned int srcOffset = 1);

Parameters

srcBfile

The BFILE from which the data is to be copied.

srcBlob

The BLOB from which the data is to be copied.

numBytes

The number of bytes to be copied from the source BFILE or BLOB.

Valid values are:

Numbers greater than 0.

dstOffset

The starting position at which to begin writing data into the current BLOB.

Valid values are:

Numbers greater than or equal to 1.

srcOffset

The starting position at which to begin reading data from the source BFILE or BLOB.

Valid values are:

Numbers greater than or equal to 1.

getChunkSize()

This method returns the chunk size of the BLOB.

When creating a table that contains a BLOB, the user can specify the chunking factor, which can be a multiple of Oracle blocks. This corresponds to the chunk size used by the LOB data layer when accessing or modifying the BLOB.

Syntax

unsigned int getChunkSize() const;

getStream()

This method returns a Stream object from the BLOB. If a stream is already 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);

Parameters

offset

The starting position at which to begin reading data from the BLOB.

Valid values are:

Numbers greater than or equal to 1.

amount

The total number of consecutive bytes to be read. If amount is 0, the data will be read from the offset value until the end of the BLOB.

isInitialized()

This method 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;

isNull()

This method 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;

isOpen()

This method tests whether the BLOB is open. If the BLOB is open, then true is returned; otherwise, false is returned.

Syntax

bool isOpen() const;

length()

This method returns the number of bytes in the BLOB.

Syntax

unsigned int length() const;

open()

This method opens the BLOB in read/write or read-only mode.

Syntax

void open(LobOpenMode mode = OCCI_LOB_READWRITE);

Parameters

mode

The mode the BLOB is to be opened in.

Valid values are:

OCCI_LOB_READWRITE

OCCI_LOB_READONLY

operator=()

This method 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);

Parameters

srcBlob

The BLOB to copy data from.

operator==()

This method 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;

Parameters

srcBlob

The Blob object to be compared with the current Blob object.

operator!= ()

This method 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;

Parameters

srcBlob

The Blob object to be compared with the current Blob object.

read()

This method 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;

Parameters

amt

The number of consecutive bytes to be read from the BLOB.

buffer

The buffer into which the BLOB data is to be read.

bufsize

The size of the buffer.

Valid values are:

Numbers greater than or equal to amount.

offset

The starting position at which to begin reading data from the BLOB. If offset is not specified, the data is written from the beginning of the BLOB.

Valid values are:

Numbers greater than or equal to 1.

setEmpty()

This method sets the Blob object to empty.

Syntax

void setEmpty();

setEmpty()

This method sets the Blob object to empty and initializes the connection pointer to the passed parameter.

Syntax

void setEmpty(const Connection* connectionp);

Parameters

connectionp

The new connection pointer for the Blob object.

setNull()

This method sets the Blob object to atomically null.

Syntax

void setNull();

trim()

This method truncates the BLOB to the new length specified.

Syntax

void trim(unsigned int newlen);

Parameters

newlen

The new length of the BLOB.

Valid values are:

Numbers less than or equal to the current length of the BLOB.

write()

This method 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 already 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);

Parameters

amt

The number of consecutive bytes to be written to the BLOB.

buffer

The buffer containing the data to be written to the BLOB.

bufsize

The size of the buffer containing the data to be written to the BLOB.

Valid values are:

Numbers greater than or equal to amt.

offset

The starting position at which to begin writing data into the BLOB. If offset is not specified, the data is written from the beginning of the BLOB.

Valid values are:

Numbers greater than or equal to 1.

writeChunk()

This method writes data from a buffer into a previously opened BLOB. The actual number of bytes written is returned.

Syntax

unsigned int writeChunk(unsigned int amt,
   unsigned char *buffer,
   unsigned int bufsize,
   unsigned int offset = 1);

Parameters

amt

The number of consecutive bytes to be written to the BLOB.

buffer

The buffer containing the data to be written.

bufsize

The size of the buffer containing the data to be written.

Valid values are:

Numbers greater than or equal to amt.

offset

The starting position at which to begin writing data into the BLOB. If offset is not specified, the data is written from the beginning of the BLOB.

Valid values are:

Numbers greater than or equal to 1.