Clobクラス

13.9 Clobクラス

Clobクラスは、CLOB型オブジェクトの共通プロパティを定義します。Clobは、データベース表の行の列値として格納されるラージ・キャラクタ・オブジェクトです。Clobオブジェクトには、CLOBへの論理ポインタが含まれていますが、CLOB自体は含まれていません。

Clobクラスのメソッドを使用すると、Clobオブジェクトに関連する特定のタスクを実行できます。これには、SQL CLOBの長さを取得するためのメソッド、クライアント上のCLOBをマテリアライズするためのメソッドおよびCLOBの一部を抽出するためのメソッドも含まれます。

NULLのCLOBオブジェクトに対して有効なメソッドは、setName()、isNull()およびoperator=()のみです。

getClob()やsetClob()など、ResultSetクラスとStatementクラスのメソッドによって、SQL CLOBの値にアクセスできます。

未初期化のCLOBオブジェクトは、次の方法で初期化できます。

setEmpty()メソッドを実行します。次に、このCLOBを表に挿入してCLOBを変更すると、SELECT...FOR UPDATEを使用してその内容を取り出すことができます。write()メソッドによってCLOBは変更されますが、変更されたデータは、トランザクションがコミットされたときにのみ表にフラッシュされます。INSERTは必要ありません。
初期化したClobオブジェクトを割り当てます。

メソッド	概要
Clob()	`Clob`クラスのコンストラクタです。
append()	`Clob`を現行の`Clob`の最後に追加します。
close()	前にオープンした`Clob`をクローズします。
closeStream()	現行の`Clob`から取得した`Stream`オブジェクトをクローズします。
copy()	`Clob`または`BFILE`のすべてまたは一部を現行の`Clob`にコピーします。
getCharSetForm()	`Clob`のキャラクタ・セット・フォームを戻します。
getCharSetId()	`Clob`のキャラクタ・セットIDを戻します。
getCharSetIdUString()	`Clob`で使用されるキャラクタ・セットの名前の`UString`バージョンを取得します。
getChunkSize()	`CLOB`への効率的な書込みを実行するための最小データ・サイズを戻します。
getContentType()	`Clob`のコンテンツ・タイプを戻します。
getOptions()	指定した`LobOptionType`に対する`CLOB`の`LobOptionValue`を戻します。
getStream()	`Stream`オブジェクトとして`CLOB`からデータを戻します。
isInitialized()	`Clob`オブジェクトが初期化されているかどうかを確認します。
isNull()	`Clob`オブジェクトがアトミック`NULL`かどうかをテストします。
isOpen()	`Clob`がオープンしているかどうかを確認します。
length()	現行の`CLOB`の文字数を戻します。
open()	`CLOB`を読取り専用または読取り/書込みアクセスでオープンします。
operator=()	`CLOB`ロケータを現行の`Clob`オブジェクトに割り当てます。
operator==()	2つの`Clob`オブジェクトが等しいかどうかを確認します。
operator!=()	2つの`Clob`オブジェクトが等しくないかどうかを確認します。
read()	`CLOB`の一部をバッファに読み取ります。
setCharSetId()	`Clob`に関連付けられたキャラクタ・セットIDを設定します。
setCharSetIdUString()	`Clob`に関連付けられたキャラクタ・セットIDを設定します。このIDは、環境のキャラクタ・セットがUTF16の場合に使用されます。
setCharSetForm()	`Clob`に関連付けられたキャラクタ・セット・フォームを設定します。
setContentType()	`Clob`のコンテンツ・タイプを設定します。
setEmpty()	`Clob`オブジェクトを空に設定します。
setNull()	`Clob`オブジェクトをアトミック`NULL`に設定します。
setOptions()	特定の`LobOptionType`に対して`LobOptionValue`を指定します。`CLOB`の高度な圧縮、暗号化および重複除外を有効化します。
trim()	`Clob`を指定した長さに切り捨てます。
write()	バッファをオープンされていない`CLOB`に書き込みます。
writeChunk()	バッファをオープンしている`CLOB`に書き込みます。

13.9.1 Clob()

Clobクラスのコンストラクタです。

構文	説明
Clob();	`NULL`の`Clob`オブジェクトを作成します。
Clob( const Connection *connectionp);	未初期化の`Clob`オブジェクトを構築します。
Clob( const Clob *srcClob);	`Clob`オブジェクトのコピーを作成します。

パラメータ	説明
connectionp	接続ポインタを指定します。
srcClob	コピー元の`Clob`オブジェクトを指定します。

13.9.2 append()

CLOBを現行のCLOBの最後に追加します。

構文

void append(
   const Clob &srcClob);

パラメータ	説明
srcClob	現行の`CLOB`に追加する`CLOB`を指定します。

13.9.3 close()

CLOBをクローズします。

構文

void close();

13.9.4 closeStream()

CLOBから取得したStreamオブジェクトをクローズします。

構文

void closeStream(
   Stream *stream);

パラメータ	説明
stream	クローズするStreamオブジェクトを指定します。

13.9.5 copy()

BFILEまたはCLOBの一部またはすべてを現行のCLOBにコピーします。

OCCIは、BfileからClobにデータをロードする際にキャラクタセット変換を実行しません。そのため、Bfileの内容がサーバーのClob記憶域キャラクタセット内の文字データであることを確認してください。

構文説明

構文	説明
void copy( const Bfile &srcBfile, unsigned int numBytes, unsigned int dstOffset = 1, unsigned int srcOffset = 1);	`BFILE`を現行の`CLOB`にコピーします。
void copy( const Clob &srcClob, unsigned int numBytes, unsigned int dstOffset = 1, unsigned int srcOffset = 1);	`CLOB`を現行の`CLOB`にコピーします。コピー先の`CLOB`が重複除外に対応しており、コピー元およびコピー先の`CLOB`が同じ列内にある場合、新規`CLOB`がコピー・オン・ライトとして作成されます。コピー元の`CLOB`から他のすべての設定が継承されます。コピー先の`CLOB`が重複除外に対応していない場合、`CLOB`の完全に新しいコピーとなります。

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

BFILEを現行のCLOBにコピーします。

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

CLOBを現行のCLOBにコピーします。

コピー先のCLOBが重複除外に対応しており、コピー元およびコピー先のCLOBが同じ列内にある場合、新規CLOBがコピー・オン・ライトとして作成されます。コピー元のCLOBから他のすべての設定が継承されます。コピー先のCLOBが重複除外に対応していない場合、CLOBの完全に新しいコピーとなります。

パラメータ	説明
srcBfile	データのコピー元の`BFILE`を指定します。
srcClob	データのコピー元の`CLOB`を指定します。
numBytes	コピー元の`BFILE`またはコピー元の`CLOB`からコピーするバイト数を指定します。有効な値は0(ゼロ)以上の数値です。
dstOffset	データの開始位置は0 (ゼロ)です。現行の`CLOB`に書き込むデータの開始位置を指定します。有効な値はコピー先バッファに書き込む最初のバイト位置を示す1以上の数値です。
srcOffset	ソース`BFILE`またはソース`CLOB`から読み取るデータの開始位置を指定します。有効な値は、1以上の数値です。

13.9.6 getCharSetForm()

CLOBのキャラクタ・セット・フォームを戻します。

構文

CharSetForm getCharSetForm() const;

13.9.7 getCharSetId()

CLOBのキャラクタ・セットIDを文字列形式で戻します。

構文

string getCharSetId() const;

13.9.8 getCharSetIdUString()

Clobで使用されるキャラクタ・セットの名前のUStringバージョンを取得します。

構文

UString getCharSetIdUString() const;

13.9.9 getChunkSize()

CLOBへの効率的な書込みを実行するための最小データ・サイズを戻します。

構文

unsigned int getChunkSize() const;

13.9.10 getContentType()

Clobのコンテンツ・タイプを戻します。コンテンツ・タイプが割り当てられていない場合は、NULL文字列を戻します。

構文

string getContentType();

13.9.11 getOptions()

指定したLobOptionTypeに対するCLOBのLobOptionValueを戻します。

CLOBが格納されたデータベース列またはパーティションに対して設定されていないオプションの値を取得しようとすると、例外が発生します。

構文

LobOptionValue getOptions(
   LobOptionType optType);

パラメータ	説明
optType	要求される`LobOptionType`の設定です。これらの設定は、サーバーのラウンドトリップを避けるために、ビット単位の`or` (`\|`)を使用して結合できます。表7-1と表7-2を参照してください

13.9.12 getStream()

CLOBからStreamオブジェクトを戻します。ストリームがオープンしている場合、別のストリームをCLOBオブジェクトでオープンすることはできません。したがって、ユーザーは、Clobオブジェクト操作を実行する前に、ストリームを常にクローズする必要があります。キャラクタ・セットIDとフォームは、setCharSetId()およびsetEmpty()のコールで明示的に設定されていない場合、デフォルトでクライアントのキャラクタ・セットIDとフォームが使用されます。

構文

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

パラメータ	説明
offset	`CLOB`から読み取るデータの開始位置を指定します。`offset`が未指定の場合、データは`CLOB`の最初から書き込まれます。有効な値は、1以上の数値です。
amount	連続して読み取る文字数の合計を指定します。`amount`が0 (ゼロ)の場合は、`offset`値から`CLOB`の最後までのデータが読み取られます。

13.9.13 isInitialized()

Clobオブジェクトが初期化されているかどうかを確認します。Clobオブジェクトが初期化されている場合はTRUEを、それ以外の場合はFALSEを戻します。

構文

bool isInitialized() const;

13.9.14 isNull()

ClobオブジェクトがアトミックNULLかどうかをテストします。ClobオブジェクトがアトミックNULLの場合はTRUEを、それ以外の場合はFALSEを戻します。

構文

bool isNull() const;

13.9.15 isOpen()

CLOBがオープンしているかどうかを確認します。CLOBがオープンしている場合はTRUEを、それ以外の場合はFALSEを戻します。

構文

bool isOpen() const;

13.9.16 length()

CLOBの文字数を戻します。

構文

unsigned int length() const;

13.9.17 open()

CLOBを読取り/書込みまたは読取り専用モードでオープンします。

構文

void open(
   LObOpenMode mode = OCCI_LOB_READWRITE);

パラメータ	説明
mode	`CLOB`をオープンするモードを指定します。有効な値は、次のとおりです。 `OCCI_LOB_READWRITE` `OCCI_LOB_READONLY`

13.9.18 operator=()

現行のCLOBにCLOBを割り当てます。割当て元CLOBは、割当て先CLOBが表に格納されているときにのみ、その割当て先CLOBにコピーされます。

構文

Clob& operator=(
   const Clob &srcClob);

パラメータ	説明
srcClob	データのコピー元の`Clob`を指定します。

13.9.19 operator==()

2つのClobオブジェクトを比較して、等しいかどうかを調べます。2つのClobオブジェクトが同じCLOBを参照している場合、それらのオブジェクトは等しいと判断されます。2つのClobオブジェクトがNULLの場合は、等しいとは判断されません。Blobオブジェクトが等しい場合はTRUEを、それ以外の場合はFALSEを戻します。

構文

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

パラメータ	説明
srcClob	現行の`Clob`オブジェクトと比較する`Clob`オブジェクトを指定します。

13.9.20 operator!=()

2つのClobオブジェクトを比較して、等しくないかどうかを調べます。2つのClobオブジェクトが同じCLOBを参照している場合、それらのオブジェクトは等しいと判断されます。2つのClobオブジェクトがNULLの場合は、等しいとは判断されません。2つのClobオブジェクトが等しくない場合はTRUEを、それ以外の場合はFALSEを戻します。

構文

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

パラメータ	説明
srcClob	現行の`Clob`オブジェクトと比較する`Clob`オブジェクトを指定します。

13.9.21 read()

CLOBの一部またはすべてをバッファに読み取ります。

UTF16などの固定幅キャラクタ・セットの場合は実際の文字数、UTF8などのマルチバイト・キャラクタ・セットの場合は読み取られたバイト数が戻されます。

キャラクタ・セットIDとフォームは、setCharSetId()、setCharSetIdUString()およびsetCharSetForm()のコールで明示的に設定されていない場合、デフォルトでクライアントのキャラクタ・セットIDとフォームが使用されます。

このメソッドの2番目のバージョンでの戻り値は、固定幅キャラクタ・セット(UTF16)の場合は読み取られた文字数を表し、マルチバイト・キャラクタ・セット(UTF8など)の場合は読み取られたバイト数を表します。

構文	説明
unsigned int read( unsigned int amt, unsigned char *buffer, unsigned int bufsize, unsigned int offset=1) const;	`CLOB`の一部またはすべてをバッファに読み取ります。
unsigned int read( unsigned int amt, unsigned utext *buffer, unsigned int bufsize, unsigned int offset=1) const;	グローバリゼーションが有効化された状態で、`CLOB`の一部またはすべてをバッファに読み取ります。このメソッドは、`setCharSetId()`メソッドを使用してキャラクタ・セットをOCCIUTF16に設定した後にコールする必要があります。

パラメータ	説明
amt	`CLOB`から読み取るバイト数を指定します。
buffer	`CLOB`データを読み取るバッファを指定します。
buffsize	バッファのサイズを指定します。有効な値は、`amt`以上の数値です。
offset	`CLOB`から読み取るデータの開始位置を指定します。`offset`が未指定の場合、データは`CLOB`の最初から書き込まれます。有効な値は、1以上の数値です。

13.9.22 setCharSetId()

Clobに関連付けられたキャラクタ・セットIDを設定します。設定したキャラクタセットIDは、読取り/書込みおよびgetStream()操作で使用されます。値が明示的に設定されていない場合は、デフォルトのクライアントのキャラクタ・セットIDが使用されます。サポートされているキャラクタ・セットのリストは、『Oracle Databaseグローバリゼーション・サポート・ガイド』の付録Aを参照してください。

構文

void setCharSetId(
   const string &charset);

パラメータ	説明
charset	Oracleは、`E8DEC`、`ZHT16BIG5`または`OCCIUTF16`などのキャラクタ・セット名をサポートしています。

13.9.23 setCharSetIdUString()

Clobに関連付けられたキャラクタセットIDを設定します。このIDは、環境のキャラクタセットがUTF16の場合に使用されます。設定したcharsetIDは、読取り/書込みおよびgetStream()操作で使用されます。

構文

void setCharSetIdUSString(
   const string &charset);

パラメータ	説明
charset	Oracleは、`WE8DEC`、`ZHT16BIG5`または `OCCIUTF16`など、`UString` (UTF16キャラクタ・セット)のキャラクタ・セット名をサポートしています。

13.9.24 setCharSetForm()

CLOBに関連付けられたキャラクタ・セット・フォームを設定します。設定したキャラクタ・セット・フォームは、読取り/書込みおよびgetStream()操作で使用されます。値が明示的に設定されていない場合、デフォルトではOCCI_SQLCS_IMPLICITが使用されます。

構文

void setCharSetForm(
   CharSetForm csfrm );

パラメータ	説明
csfrm	`Clob`のキャラクタ・セット・フォームを指定します。

13.9.25 setContentType()

Clobのコンテンツ・タイプを設定します。ClobがSecureFileでない場合は、例外が発生します。

構文

void setContentType(
   const string contenttype);

パラメータ	説明
contenttype	`Clob`のコンテンツ・タイプを指定します。ASCII Mime対応の文字列です。

13.9.26 setEmpty()

Clobオブジェクトを空に設定します。

構文	説明
void setEmpty();	`Clob`オブジェクトを空に設定します。
void setEmpty( const Connection* connectionp);	`Clob`オブジェクトを空に設定し、渡されたパラメータへの接続ポインタを初期化します。

パラメータ	説明
connectionp	`Clob`オブジェクトの新しい接続ポインタを指定します。

13.9.27 setNull()

ClobオブジェクトをアトミックNULLに設定します。

構文

void setNull();

13.9.28 setOptions()

特定のLobOptionTypeに対してLobOptionValueを指定します。CLOBの高度な圧縮、暗号化および重複除外を有効化します。表7-1と表7-2を参照してください。

CLOBが格納されたデータベース列またはパーティションに対して設定されていないオプションを設定または設定解除しようとすると、例外が発生します。

暗号化されたCLOB列で暗号化をオフにしようとすると、例外が発生します。

構文

void setOptions(
   LobOptionType optType,
   LobOptionValue optValue);

パラメータ	説明
optType	指定されている`LobOptionType`の設定です。これらの設定は、サーバーのラウンドトリップを避けるために、ビット単位の`or` (`\|`)を使用して結合できます。
optValue	`optType`パラメータで指定された`LobOptionType`の`LobOptionValue`設定です。

13.9.29 trim()

CLOBを新しく指定した長さに切り捨てます。

構文

void trim(
   unsigned int newlen);

パラメータ	説明
newlen	`CLOB`の新しい長さを指定します。有効な値は、`CLOB`の現在の長さ以下の数値です。

13.9.30 write()

バッファのデータをCLOBに書き込みます。

このメソッドは、CLOBを暗黙的にオープンしてバッファのデータをCLOBにコピーし、CLOBを暗黙的にクローズします。CLOBがオープンしている場合は、かわりにwriteChunk()を使用します。実際に書き込まれた文字数が戻ります。キャラクタ・セットIDとフォームは、setCharSetId()およびsetCharSetForm()のコールで明示的に設定されていない場合、デフォルトでクライアントのキャラクタ・セットIDとフォームが使用されます。

構文	説明
unsigned int write( unsigned int amt, unsigned char *buffer, unsigned int bufsize, unsigned int offset=1);	バッファのデータを`CLOB`に書き込みます。
unsigned int write( unsigned int amt, utext *buffer, unsigned int bufsize, unsigned int offset=1);	グローバリゼーションが有効化されている状態で、UTF16バッファのデータを`CLOB`に書き込みます。このメソッドは、setCharSetIdUString()メソッドを使用してキャラクタ・セットをOCCIUTF16に設定した後にコールする必要があります。

パラメータ	説明
amt	amountパラメータは次の数を表します。固定幅キャラクタ・セット(UTF16)の場合は書き込む文字数マルチバイト・キャラクタ・セット(UTF8など)の場合は書き込むバイト数
buffer	`CLOB`に書き込むデータが含まれているバッファを指定します。
buffsize	`CLOB`に書き込むデータが含まれているバッファのサイズを指定します。有効な値は、`amt`以上の数値です。
offset	`CLOB`に書き込むデータの開始位置を指定します。`offset`が未指定の場合、データは`CLOB`の最初から書き込まれます。有効な値は、1以上の数値です。

13.9.31 writeChunk()

バッファのデータを前にオープンしたCLOBに書き込みます。実際の文字数を戻します。キャラクタ・セットIDとフォームは、setCharSetId()およびsetCharSetForm()のコールで明示的に設定されていない場合、デフォルトでクライアントのキャラクタ・セットIDとフォームが使用されます。

構文	説明
unsigned int writeChunk( unsigned int amt, unsigned char *buffer, unsigned int bufsize, unsigned int offset=1);	バッファのデータを前にオープンした`CLOB`に書き込みます。
unsigned int writeChunk( unsigned int amt, utext *buffer, unsigned int bufsize, unsigned int offset=1);	グローバリゼーションが有効化されている状態で、UTF16バッファのデータを`CLOB`に書き込みます。このメソッドは、setCharSetIdUString()メソッドを使用してキャラクタ・セットを`OCCIUTF16`に設定した後にコールする必要があります。

パラメータ	説明
amt	amtパラメータは、固定幅キャラクタセット(UTF16)の場合は書き込まれた文字数、マルチバイト・キャラクタセット(UTF8など)の場合は書き込まれたバイト数を表します。
buffer	`CLOB`に書き込むデータが含まれているバッファを指定します。
buffsize	`CLOB`に書き込むデータが含まれているバッファのサイズを指定します。有効な値は、`amt`以上の数値です。
offset	`CLOB`に書き込むデータの開始位置を指定します。`offset`が未指定の場合、データは`CLOB`の最初から書き込まれます。有効な値は、1以上の数値です。