OCCI Classes and Methods, 5 of 22

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.

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

To create a null Clob object, use the syntax:

Clob();

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

To create an uninitialized Clob object, use the syntax:

Clob(const Connection *connectionp);

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.

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

Clob(const Clob &srcClob);

Summary of Clob Methods

Table 8-5 Clob Methods

Method	Summary
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.
setCharSetForm()	Sets the character set form associated with the CLOB.
setCharSetForm()	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.

append()

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

Syntax

void append(const Clob &srcClob);

Parameters

srcClob

The CLOB to be appended to the current CLOB.

close()

This method closes a CLOB.

Syntax

void close();

closeStream()

This method closes the Stream object obtained from the CLOB.

Syntax

void closeStream(Stream *stream);

Parameters

stream

The Stream object to be closed.

copy()

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

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 Clob &srcClob,
   unsigned int numBytes,
   unsigned int dstOffset = 1,
   unsigned int srcOffset = 1);

Parameters

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 to begin writing data into the current CLOB.

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 CLOB.

Valid values are:

Numbers greater than or equal to 1.

getCharSetForm()

This method returns the character set form of the CLOB.

Syntax

CharSetForm getCharSetForm() const;

getCharSetId()

This method returns the character set ID of the CLOB, in string form.

Syntax

string getCharSetId() const;

getChunkSize()

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

This method 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 explicityly set through setCharSetId() and setCharSetForm() calls.

Syntax

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

Parameter

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()

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

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

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

Syntax

bool isOpen() const;

length()

This method returns the number of characters in the CLOB.

Syntax

unsigned int length() const;

open()

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

Syntax

void open(LObOpenMode mode = OCCI_LOB_READWRITE);

Parameters

mode

The mode the CLOB is to be opened in.

Valid values are:

OCCI_LOB_READWRITE

OCCI_LOB_READONLY

operator=()

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

Parameters

srcClob

The CLOB to copy data from.

operator==()

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

Parameters

srcClob

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

operator!=()

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

Parameters

srcClob

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

read()

This method reads a part or all of the CLOB into a buffer. The actual number of characters read is returned. The client's character set id and form will be used by default, unless they are explicityly set through setCharSetId() and setCharSetForm() calls.

Syntax

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

Parameters

amt

The number of consecutive characters to be read from the CLOB.

buffer

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

bufsize

The size of the buffer.

Valid values are:

Numbers greater than or equal to amt.

offset

The position at which to begin reading data from the CLOB. If offset is not specified, the data is read from the beginning of the CLOB.

Valid values are:

Numbers greater than or equal to 1.

setCharSetId()

This method sets the Character set Id associated with Clob. The charset id set will be used for readread/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 OCCI_STD_NAMESPACE::string &charset);

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

Parameters

csfrm

The char set form for Clob.

setEmpty()

This method sets the Clob object to empty.

Syntax

void setEmpty();

setEmpty()

This method sets the Clob 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 Clob object.

setNull()

This method sets the Clob object to atomically null.

Syntax

void setNull();

trim()

This method truncates the CLOB to the new length specified.

Syntax

void trim(unsigned int newlen);

Parameters

newlen

The new length of the CLOB.

Valid values are:

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

write()

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

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

Parameters

amt

The number of consecutive characters to be written to the CLOB.

buffer

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

bufsize

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 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()

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

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

Parameters

amt

The number of consecutive characters to be written to the CLOB.

buffer

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

bufsize

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