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 modifies the CLOB; however, the modified data is flushed to the table only when the transaction is committed. Note that an insert is not required.
Assigning an initialized Clob object to it.

Method	Summary
Clob()	`Clob` class constructor.
append()	Appends a `Clob` at the end of the current `Clob`.
close()	Closes a previously opened `Clob`.
closeStream()	Closes the `Stream` object obtained from the current `Clob`.
copy()	Copies all or a portion of a `Clob` or `BFILE` into the current `Clob`.
getCharSetForm()	Returns the character set form of the `Clob`.
getCharSetId()	Returns the character set ID of the `Clob`.
getCharSetIdUString()	Retrieves the characterset name associated with the `Clob`; `UString` version.
getChunkSize()	Returns the smallest data size to perform efficient writes to the `CLOB`.
getContentType()	Returns the content type of the `Clob`.
getOptions()	Returns the `CLOB`'s `LobOptionValue` for a specified `LobOptionTyp`e.
getStream()	Returns data from the `CLOB` as a `Stream` object.
isInitialized()	Tests whether the `Clob` object is initialized.
isNull()	Tests whether the `Clob` object is atomically `NULL`.
isOpen()	Tests whether the `Clob` is open.
length()	Returns the number of characters in the current `CLOB`.
open()	Opens the `CLOB` with read or read/write access.
operator=()	Assigns a `CLOB` locator to the current `Clob` object.
operator==()	Tests whether two `Clob` objects are equal.
operator!=()	Tests whether two `Clob` objects are not equal.
read()	Reads 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`.
setContentType()	Sets the content type of the `Clob`.
setEmpty()	Sets the `Clob` object to empty.
setNull()	Sets the `Clob` object to atomically `NULL`.
setOptions()	Specifies a `LobOptionValue` for a particular `LobOptionType`. Enables advanced compression, encryption and deduplication of `CLOB`s.
trim()	Truncates the `Clob` to a specified length.
write()	Writes a buffer into an unopened `CLOB`.
writeChunk()	Writes a buffer into an open `CLOB`.

Clob()

Clob class constructor.

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

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

LNCPP20704

append()

Appends a CLOB to the end of the current CLOB.

LNCPP20705Syntax

void append(
   const Clob &srcClob);

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

LNCPP20706

close()

Closes a CLOB.

LNCPP20707Syntax

void close();

LNCPP20708

closeStream()

Closes the Stream object obtained from the CLOB.

LNCPP20709Syntax

void closeStream(
   Stream *stream);

Parameter	Description
stream	The Stream object to be closed.

LNCPP20710

copy()

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

OCCI does not perform any characterset conversions when loading data from a Bfile into a Clob; therefore, ensure that the contents of the Bfile are character data in the server's Clob storage characterset.

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

LNCPP20711

getCharSetForm()

Returns the character set form of the CLOB.

LNCPP20712Syntax

CharSetForm getCharSetForm() const;

LNCPP20713

getCharSetId()

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

LNCPP20714Syntax

string getCharSetId() const;

LNCPP20715

getCharSetIdUString()

Retrieves the characterset name associated with the Clob; UString version.

LNCPP20716Syntax

UString getCharSetIdUString() const;

LNCPP20717

getChunkSize()

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

LNCPP20718Syntax

unsigned int getChunkSize() const;

LNCPP20719

getContentType()

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

LNCPP20720Syntax

string getContentType();

LNCPP20721

getOptions()

Returns the CLOB'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 CLOB.

LNCPP20722Syntax

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"

LNCPP20723

getStream()

Returns a Stream object from the CLOB. If a stream is 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 is used by default, unless they are explicitly set through setCharSetId() and setEmpty() calls.

LNCPP20724Syntax

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 is read from the `offset` value until the end of the `CLOB`.

LNCPP20725

isInitialized()

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

LNCPP20726Syntax

bool isInitialized() const;

LNCPP20727

isNull()

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

LNCPP20728Syntax

bool isNull() const;

LNCPP20729

isOpen()

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

LNCPP20730Syntax

bool isOpen() const;

LNCPP20731

length()

Returns the number of characters in the CLOB.

LNCPP20732Syntax

unsigned int length() const;

LNCPP20733

open()

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

LNCPP20734Syntax

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`

LNCPP20735

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.

LNCPP20736Syntax

Clob& operator=(
   const Clob &srcClob);

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

LNCPP20737

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.

LNCPP20738Syntax

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

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

LNCPP20739

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.

LNCPP20740Syntax

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

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

LNCPP20741

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 is used by default, unless they are explicitly set through setCharSetId(), setCharSetIdUString() and setCharSetForm() calls.

Note that 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).

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.

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.

LNCPP20742

setCharSetId()

Sets the Character set Id associated with Clob. The characterset id set is 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.

LNCPP20743Syntax

void setCharSetId(
   const string &charset);

Parameter	Description
charset	Oracle supported characterset name, such as `E8DEC`, `ZHT16BIG5`, or `OCCIUTF16`.

LNCPP20744

setCharSetIdUString()

Sets the characterset id associated with Clob; used when the environment's characterset is UTF16. The charset id set is used for read, write and getStream() operations.

LNCPP20745Syntax

void setCharSetIdUSString(
   const string &charset);

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

LNCPP20746

setCharSetForm()

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

LNCPP20747Syntax

void setCharSetForm(
   CharSetForm csfrm );

Parameter	Description
csfrm	The charset form for `Clob`.

LNCPP20748

setContentType()

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

LNCPP20749Syntax

void setContentType(
   const string contenttype);

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

LNCPP20750

setEmpty()

Sets the Clob object to empty.

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

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

LNCPP20751

setNull()

Sets the Clob object to atomically NULL.

LNCPP20752Syntax

void setNull();

LNCPP20753

setOptions()

Specifies a LobOptionValue for a particular LobOptionType. Enables advanced compression, encryption and deduplication of CLOBs. 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 CLOB.

Throws an exception if attempting to turn off encryption in an encrypted CLOB column.

LNCPP20754Syntax

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

LNCPP20755

trim()

Truncates the CLOB to the new length specified.

LNCPP20756Syntax

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

LNCPP20757

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 open, use writeChunk() instead. The actual number of characters written is returned. The client's character set id and form is 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);	Writes data from a buffer into a `CLOB`.
unsigned int write( unsigned int amt, utext *buffer, unsigned int bufsize, unsigned int offset=1);	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.

LNCPP20758

writeChunk()

Writes data from a buffer into a previously opened CLOB. Returns the actual number of characters. The client's character set id and form is 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);	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);	Writes data from a UTF16 buffer into a `CLOB`; globalization enabled. Should be called after setting characterset to `OCCIUTF16` using setCharSetIdUString() method.

Parameter	Description
amt	The amount parameter represents either a number of characters written for fixed-width charactersets (UTF16) or a 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.