Blob Cl ass

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 this BLOB into the table and then retrieving it using SELECT...FOR UPDATE. The write() method modifies the BLOB; 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.

Method	Summary
Blob()	`Blob` class constructor.
append()	Appends a specified `BLOB` to the end of the current `BLOB`.
close()	Closes a previously opened `BLOB`.
closeStream()	Closes the `Stream` object obtained from the `BLOB`.
copy()	Copies a specified portion of a `BFILE` or `BLOB` into the current `BLOB`.
getChunkSize()	Returns the smallest data size to perform efficient writes to the `BLOB`.
getContentType()	Returns the content type of the `Blob`.
getOptions()	Returns the `BLOB`'s `LobOptionValue` for a specified `LobOptionType`.
getStream()	Returns data from the `BLOB` as a `Stream` object.
isInitialized()	Tests whether the `Blob` object is initialized
isNull()	Tests whether the `Blob` object is atomically `NULL`.
isOpen()	Tests whether the `BLOB` is open.
length()	Returns the number of bytes in the `BLOB`.
open()	Opens the `BLOB` `with read or` read/write access.
operator=()	Assigns a `BLOB` locator to the `Blob` object.
operator==()	Tests whether two `Blob` objects are equal.
operator!= ()	Tests whether two `Blob` objects are not equal.
read()	Reads a portion of the `BLOB` into a buffer.
setContentType()	Sets the content type of the `Blob`.
setEmpty()	Sets the `Blob` object to empty.
setNull()	Sets the `Blob` object to atomically `NULL`.
setOptions()	Specifies a `LobOptionValue` for a particular `LobOptionType`. Enables advanced compression, encryption and deduplication of `BLOB`s.
trim()	Truncates the `BLOB` to a specified length.
write()	Writes a buffer into an unopened `BLOB`.
writeChunk()	Writes a buffer into an open `BLOB`.

Blob()

Blob class constructor.

Syntax	Description
Blob();	Creates a `NULL` `Blob` object.
Blob( const Connection *connectionp);	Creates an uninitialized `Blob` object.
Blob( const Blob &srcBlob);	Creates a copy of a `Blob` object.

Parameter	Description
connectionp	The connection pointer
srcBlob	The source `Blob` object.

LNCPP20642

append()

Appends a BLOB to the end of the current BLOB.

LNCPP20643Syntax

void append(
   const Blob &srcBlob);

Parameter	Description
srcBlob	The `BLOB` object to be appended to the current `BLOB` object.

LNCPP20644

close()

Closes a BLOB.

LNCPP20645Syntax

void close();

LNCPP20646

closeStream()

Closes the Stream object obtained from the BLOB.

LNCPP20647Syntax

void closeStream(
   Stream *stream);

Parameter	Description
stream	The `Stream` to be closed.

LNCPP20648

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 `BFILE` into the current `BLOB`.
void copy( const Blob &srcBlob, unsigned int numBytes, unsigned int dstOffset = 1, unsigned int srcOffset = 1);	Copies a part of a `BLOB` into the current `BLOB`. If the destination `BLOB` has deduplication enabled, and the source and destination `BLOB`s are in the same column, the new `BLOB` is created as copy-on-write. All other settings are inherited from the source `BLOB`. If the destination `BLOB` has deduplication disabled, it is a completely new copy of the `BLOB`.

Parameter	Description
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.

LNCPP20649

getChunkSize()

Returns the smallest data size to perform efficient writes to the BLOB.

LNCPP20650Syntax

unsigned int getChunkSize() const;

LNCPP20651

getContentType()

Returns the content type of the Blob. If a content type has not been assigned, returns a NULL string.

LNCPP20652Syntax

string getContentType();

LNCPP20653

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.

LNCPP20654Syntax

LobOptionValue getOptions(
   LobOptionType optType);

Parameter	Description
optType	The `LobOptionType` setting requested. These may be combined using bitwise `or` (`\|`) to avoid server round trips. See Table 7-1, "Values of Type LobOptionType" and Table 7-2, "Values of Type LobOptionValue"

LNCPP20655

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.

LNCPP20656Syntax

Stream* getStream(
   unsigned int offset = 1,
   unsigned int amount = 0);

Parameter	Description
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`.
amount	The total number of bytes to be read from the `BLOB`; if `amount` is `0`, the data is read in a streamed mode from input `offset` until the end of the `BLOB`.

LNCPP20657

isInitialized()

Tests whether the Blob object is initialized. If the Blob object is initialized, then TRUE is returned; otherwise, FALSE is returned.

LNCPP20658Syntax

bool isInitialized() const;

LNCPP20659

isNull()

Tests whether the Blob object is atomically NULL. If the Blob object is atomically NULL, then TRUE is returned; otherwise, FALSE is returned.

LNCPP20660Syntax

bool isNull() const;

LNCPP20661

isOpen()

Tests whether the BLOB is open. If the BLOB is open, then TRUE is returned; otherwise, FALSE is returned.

LNCPP20662Syntax

bool isOpen() const;

LNCPP20663

length()

Returns the number of bytes in the BLOB.

LNCPP20664Syntax

unsigned int length() const;

LNCPP20665

open()

Opens the BLOB in read/write or read-only mode.

LNCPP20666Syntax

void open(
   LobOpenMode mode = OCCI_LOB_READWRITE);

Parameter	Description
mode	The mode the `BLOB` is to be opened in. Valid values are: `OCCI_LOB_READWRITE` `OCCI_LOB_READONLY`

LNCPP20667

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.

LNCPP20668Syntax

Blob& operator=(
   const Blob &srcBlob);

Parameter	Description
srcBlob	The source `BLOB` from which to copy data.

LNCPP20669

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.

LNCPP20670Syntax

bool operator==(
   const Blob &srcBlob) const;

Parameter	Description
srcBlob	The source `BLOB` to be compared with the current `BLOB`.

LNCPP20671

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.

LNCPP20672Syntax

bool operator!=(
   const Blob &srcBlob) const;

Parameter	Description
srcBlob	The source `BLOB` to be compared with the current `BLOB`.

LNCPP20673

read()

Reads a part or all of the BLOB into a buffer. The actual number of bytes read is returned.

LNCPP20674Syntax

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 `1`.
buffer	The buffer that the `BLOB` data is to be read into. Valid values are numbers greater than or equal to `amt`.
buffsize	The size of the buffer that the `BLOB` data is to be read into. Valid values are numbers greater than or equal to `amt`.
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`.

LNCPP20675

setContentType()

Sets the content type of the Blob. If the Blob is not a SecureFile, throws an exception.

LNCPP20676Syntax

void setContentType(
   const string contenttype);

Parameter	Description
contenttype	The content type of the `Blob`; an ASCII Mime compliant string.

LNCPP20677

setEmpty()

Sets the Blob object to empty.

Syntax	Description
void setEmpty();	Sets the `Blob` object to empty.
void setEmpty( const Connection* connectionp);	Sets the `Blob` object to empty and initializes the connection pointer to the passed parameter.

Parameter	Description
connectionp	The new connection pointer for the `BLOB` object.

LNCPP20678

setNull()

Sets the Blob object to atomically NULL.

LNCPP20679Syntax

void setNull();

LNCPP20680

setOptions()

Specifies a LobOptionValue for a particular LobOptionType. Enables advanced compression, encryption and deduplication of BLOBs. See Table 7-1, "Values of Type LobOptionType" and Table 7-2, "Values of Type LobOptionValue".

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.

LNCPP20681Syntax

void setOptions(
   LobOptionType optType,
   LobOptionValue optValue);

Parameter	Description
optType	The `LobOptionType` setting being specified. These may be combined using bitwise `or` (`\|`) to avoid server round trips.
optValue	The `LobOptionValue` setting for the `LobOptionType` specified by the `optType` parameter

LNCPP20682

trim()

Truncates the BLOB to the new length specified.

LNCPP20683Syntax

void trim(
   unsigned int newlen);

Parameter	Description
newlen	The new length of the `BLOB`. Valid values are numbers less than or equal to the current length of the `BLOB`.

LNCPP20684

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.

LNCPP20685Syntax

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 `BLOB`.
buffer	The buffer containing the data to be written to the `BLOB`.
buffsize	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.

LNCPP20686

writeChunk()

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

LNCPP20687Syntax

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 `BLOB`.
buffer	The buffer containing the data to be written to the `BLOB`.
buffsize	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`.

Blob Class