Clob Class

The Clob class defines the common properties of objects of type CLOB. A Clob is a large character object stored as a column value in a row of a database table. A Clob object contains a logical pointer to a CLOB, not the CLOB itself.

Methods of the Clob class enable you to perform specific tasks related to Clob objects, including methods for getting the length of a SQL CLOB, for materializing a CLOB on the client, and for extracting a part of the CLOB.

The only methods valid on a NULL CLOB object are setName(), isNull(), and operator=() .

Methods in the ResultSet and Statement classes, such as getClob() and setClob(), enable you to access an SQL CLOB value.

An uninitialized CLOB object can be initialized by:

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

See Also:

In-depth discussion of LOBs in the introductory chapter of Oracle Database Application Developer's Guide - Large Objects,

Table 10-8 Summary of Clob Methods

Method	Summary
Clob()	`Clob` class constructor.
append()	Append a `Clob` at the end of the current `Clob`.
close()	Close a previously opened `Clob`.
closeStream()	Close the `Stream` object obtained from the current `Clob`.
copy()	Copy all or a portion of a `Clob` or `BFILE` into the current `Clob`.
getCharSetForm()	Return the character set form of the `Clob`.
getCharSetId()	Return the character set ID of the `Clob`.
getChunkSize()	Return the chunk size of the `Clob`.
getStream()	Return data from the `CLOB` as a `Stream` object.
isInitialized()	Test whether the `Clob` object is initialized.
isNull()	Test whether the `Clob` object is atomically `NULL`.
isOpen()	Test whether the `Clob` is open.
length()	Return the number of characters in the current `CLOB`.
open()	Open the `CLOB` with read or read/write access.
operator=()	Assign a `CLOB` locator to the current `Clob` object.
operator==()	Test whether two `Clob` objects are equal.
operator!=()	Test whether two `Clob` objects are not equal.
read()	Read a portion of the `CLOB` into a buffer.
setCharSetId()	Sets the character set ID associated with the `Clob`.
setCharSetIdUString()	Sets the character set ID associated with the `Clob`; used when the environment character set is UTF16.
setCharSetForm()	Sets the character set form associated with the `Clob`.
setEmpty()	Set the `Clob` object to empty.
setEmpty()	Set the `Clob` object to empty and initialize the connection pointer to the passed parameter.
setNull()	Set the `Clob` object to atomically `NULL`.
trim()	Truncate the `Clob` to a specified length.
write()	Write a buffer into an unopened `CLOB`.
writeChunk()	Write a buffer into an open `CLOB`.

Clob()

Clob class constructor.

Syntax	Description
Clob();	Creates a `NULL` `Clob` object.
Clob( const Connection *connectionp);	Create an uninitialized `Clob` object.
Clob( const Clob *srcClob);	Create a copy of a `Clob` object.

Parameter	Description
connectionp	Connection pointer
srcClob	The source `Clob` object

append()

Appends a CLOB to the end of the current CLOB.

Syntax

void append(
   const Clob &srcClob);

Parameter	Description
srcClob	The `CLOB` to be appended to the current `CLOB`.

close()

Closes a CLOB.

Syntax

void close();

closeStream()

Closes the Stream object obtained from the CLOB.

Syntax

void closeStream(
   Stream *stream);

Parameter	Description
stream	The Stream object to be closed.

copy()

Copies a part or all of a BFILE or CLOB into the current CLOB.

Syntax Description

Syntax	Description
void copy( const Bfile &srcBfile, unsigned int numBytes, unsigned int dstOffset = 1, unsigned int srcOffset = 1);	Copies a `BFILE` into the current `CLOB`.
void copy( const Blob &srcClob, unsigned int numBytes, unsigned int dstOffset = 1, unsigned int srcOffset = 1);	Copies a `CLOB` into the current `CLOB`.

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

Copies a BFILE into the current CLOB.

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

Copies a CLOB into the current CLOB.

Parameter	Description
srcBfile	The `BFILE` from which the data is to be copied.
srcClob	The `CLOB` from which the data is to be copied.
numBytes	The number of characters to be copied from the source `BFILE` `or` `CLOB.` Valid values are numbers greater than 0.
dstOffset	The starting position at which data is to be is at 0. The starting position at which to begin writing data into the current `CLOB` Valid values are numbers greater than or equal to 1 written in the destination buffer; the position of the first byte.
srcOffset	The starting position at which to begin reading data from the source `BFILE` or `CLOB`. Valid values are numbers greater than or equal to 1.

getCharSetForm()

Returns the character set form of the CLOB.

Syntax

CharSetForm getCharSetForm() const;

getCharSetId()

Returns the character set ID of the CLOB, in string form.

Syntax

string getCharSetId() const;

getChunkSize()

Returns the chunk size of the CLOB. When creating a table that contains a CLOB, 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 and modifying the CLOB.

Syntax

unsigned int getChunkSize() const;

getStream()

Returns a Stream object from the CLOB. If a stream is already open, it is disallowed to open another stream on CLOB object, so the user must always close the stream before performing any Clob object operations. The client's character set id and form will be used by default, unless they are explicitly set through setCharSetId() and setEmpty() calls.

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 `CLOB`. If `offset` is not specified, the data is written from the beginning of the `CLOB`. Valid values are numbers greater than or equal to 1.
amount	The total number of consecutive characters to be read. If `amount` is 0, the data will be read from the `offset` value until the end of the `CLOB`.

isInitialized()

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

Syntax

bool isInitialized() const;

isNull()

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

Syntax

bool isNull() const;

isOpen()

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

Syntax

bool isOpen() const;

length()

Returns the number of characters in the CLOB.

Syntax

unsigned int length() const;

open()

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

Syntax

void open(
   LObOpenMode mode = OCCI_LOB_READWRITE);

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

operator=()

Assigns a CLOB to the current CLOB. The source CLOB gets copied to the destination CLOB only when the destination CLOB gets stored in the table.

Syntax

Clob& operator=(
   const Clob &srcClob);

Parameter	Description
srcClob	The `Clob` from which the data must be copied.

operator==()

Compares two Clob objects for equality. Two Clob objects are equal if they both refer to the same CLOB. Two NULL Clob objects are not considered equal. If the Blob objects are equal, then TRUE is returned; otherwise, FALSE is returned.

Syntax

bool operator==(
   const Clob &srcClob) const;

Parameter	Description
srcClob	The `Clob` object to be compared with the current `Clob` object.

operator!=()

Compares two Clob objects for inequality. Two Clob objects are equal if they both refer to the same CLOB. Two NULL Clob objects are not considered equal. If the Clob objects are not equal, then TRUE is returned; otherwise, FALSE is returned.

Syntax

bool operator!=(
   const Clob &srcClob) const;

Parameter	Description
srcClob	The `Clob` object to be compared with the current `Clob` object.

read()

Reads a part or all of the CLOB into a buffer.

Returns the actual number of characters read for fixed-width charactersets, such as UTF16, or the number of bytes read for multibyte charactersets, including UTF8.

The client's character set id and form will be used by default, unless they are explicitly set through setCharSetId(), setCharSetIdUString() and setCharSetForm() calls.

Syntax	Description
unsigned int read( unsigned int amt, unsigned char *buffer, unsigned int bufsize, unsigned int offset=1) const;	Reads a part or all of the `CLOB` into a buffer.
unsigned int read( unsigned int amt, unsigned utext *buffer, unsigned int bufsize, unsigned int offset=1) const;	Reads a part or all of the `CLOB` into a buffer; globalization enabled. Should be called after setting character set to OCCIUTF16 using `setCharSetId()` method.

Note:

For the second version of the method, the return value represents either the number of characters read for fixed-width charactersets (UTF16), or the number of bytes read for multibyte charactersets (including UTF8).

Parameter	Description
amt	The number of bytes to be read. from the `CLOB`.
buffer	The buffer that the `CLOB` data is to be read into.
buffsize	The size of the buffer. Valid values are numbers greater than or equal to `amt`.
offset	The starting position at which to begin reading data from the `CLOB`. If `offset` is not specified, the data is written from the beginning of the `CLOB`. Valid values are numbers greater than or equal to 1.

setCharSetId()

Sets the Character set Id associated with Clob. The charset id set will be used for read/write and getStream() operations. If no value is set explicitly, the default client's character set id is used. List of character sets supported is given in Globalization Support Guide Appendix A.

Syntax

void setCharSetId(
   const string &charset);

Parameter	Description
charset	Oracle supported characterset name (WE8DEC, ZHT16BIG5), or "OCCIUTF16".

setCharSetIdUString()

Sets the Character set Id associated with Clob; used when the environment's charset is UTF16. The charset id set will be used for read/write and getStream() operations.

Syntax

void setCharSetIdUSString(
   const string &charset);

Parameter	Description
charset	Oracle supported characterset name (WE8DEC, ZHT16BIG5), or "OCCIUTF16" in `UString` (UTF16 characterset).

setCharSetForm()

Sets the character set form associated with the CLOB. The charset form set will be used for read/write and getStream() operations. If no value is set explicitly, by default, OCCI_SQLCS_IMPLICIT will be used.

Syntax

void setCharSetForm(
   CharSetForm csfrm );

Parameter	Description
csfrm	The char set form for `Clob`.

setEmpty()

Sets the Clob object to empty.

Syntax

void setEmpty();

setEmpty()

Sets the Clob object to empty and initializes the connection pointer to the passed parameter.

Syntax

void setEmpty(
   const Connection* connectionp);

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

setNull()

Sets the Clob object to atomically NULL.

Syntax

void setNull();

trim()

Truncates the CLOB to the new length specified.

Syntax

void trim(
   unsigned int newlen);

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

write()

Writes data from a buffer into a CLOB.

This method implicitly opens the CLOB, copies the buffer into the CLOB, and implicitly closes the CLOB. If the CLOB is already open, use writeChunk() instead. The actual number of characters written is returned. The client's character set id and form will be used by default, unless they are explicitly set through setCharSetId() and setCharSetForm() calls.

Syntax	Description
unsigned int write( unsigned int amt, unsigned char *buffer, unsigned int bufsize, unsigned int offset=1) const;	Writes data from a buffer into a `CLOB`.
unsigned int write( unsigned int amt, utext *buffer, unsigned int bufsize, unsigned int offset=1) const;	Writes data from a UTF16 buffer into a `CLOB`; globalization enabled. Should be called after setting character set to OCCIUTF16 using setCharSetIdUString() method.

Parameter	Description
amt	The amount parameter represents: number of characters written for fixed-width charactersets (UTF16) number of bytes written for multibyte charactersets (including UTF8)
buffer	The buffer containing the data to be written to the `CLOB`.
buffsize	The size of the buffer containing the data to be written to the `CLOB.` Valid values are numbers greater than or equal to `amt`.
offset	The starting position at which to begin writing data into the `CLOB`. If `offset` is not specified, the data is written from the beginning of the `CLOB`. Valid values are numbers greater than or equal to 1.

writeChunk()

Writes data from a buffer into a previously opened CLOB.

The actual number of characters written is returned. The client's character set id and form will be used by default, unless they are explicitly set through setCharSetId() and setCharSetForm() calls.

Syntax	Description
unsigned int writeChunk( unsigned int amt, unsigned char *buffer, unsigned int bufsize, unsigned int offset=1) const;	Writes data from a buffer into a previously opened `CLOB`.
unsigned int writeChunk( unsigned int amt, utext *buffer, unsigned int bufsize, unsigned int offset=1) const;	Writes data from a UTF16 buffer into a `CLOB`; globalization enabled. Should be called after setting character set to OCCIUTF16 using setCharSetIdUString() method.

Parameter	Description
amt	The amount parameter represents number of characters written for fixed-width charactersets (UTF16) number of bytes written for multibyte charactersets (including UTF8)
buffer	The buffer containing the data to be written to the `CLOB`.
buffsize	The size of the buffer containing the data to be written to the `CLOB.` Valid values are numbers greater than or equal to `amt`.
offset	The starting position at which to begin writing data into the `CLOB`. If `offset` is not specified, the data is written from the beginning of the `CLOB`. Valid values are numbers greater than or equal to 1.