Oracle® C++ Call Interface Programmer's Guide 10g Release 2 (10.2) Part Number B14294-02 |
|
|
View PDF |
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 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.
See Also:
In-depth discussion of LOB
s in the introductory chapter of Oracle Database Application Developer's Guide - Large Objects,
Table 12-8 Summary of Blob Methods
Method | Summary |
---|---|
|
|
|
Appends a specified |
|
Closes a previously opened |
|
Closes the |
|
Copies a specified portion of a |
|
Returns the chunk size of 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 |
|
Sets the |
|
Truncates the |
|
Writes a buffer into an unopened |
|
Writes a buffer into an open |
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. |
Appends a BLOB
to the end of the current BLOB
.
Syntax
void append( const Blob &srcBlob);
Parameter | Description |
---|---|
srcBlob |
The BLOB object to be appended to the current BLOB object. |
Closes a BLOB
.
Syntax
void close();
Closes the Stream object obtained from the BLOB
.
Syntax
void closeStream( Stream *stream);
Parameter | Description |
---|---|
stream |
The Stream to be closed. |
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 . |
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. |
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;
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);
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 will be read in a streamed mode from input offset until the end of the BLOB . |
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;
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;
Tests whether the BLOB
is open. If the BLOB
is open, then TRUE
is returned; otherwise, FALSE
is returned.
Syntax
bool isOpen() const;
Returns the number of bytes in the BLOB
.
Syntax
unsigned int length() const;
Opens the BLOB
in read/write or read-only mode.
Syntax
void open( LobOpenMode mode = OCCI_LOB_READWRITE);
Parameter | Description |
---|---|
mode |
The mode the BLOB is to be opened in. Valid values are:
|
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 BLOB from which to copy data. |
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 BLOB to be compared with the current BLOB . |
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 BLOB to be compared with the current BLOB . |
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 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 . |
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. |
Sets the Blob
object to atomically NULL
.
Syntax
void setNull();
Truncates the BLOB
to the new length specified.
Syntax
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 . |
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);
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. |
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 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 . |