表17-2は、この項で説明している、LOBロケータを使用するLOB関数を示しています。すべての新規アプリケーションには、「2」で終わる関数を使用します。
注意:
LOBへのアクセスには、LOB用のデータ・インタフェースを使用するというもう1つの方法があります。次の場所で説明するように、CLOB
列の文字データまたはBLOB
列のRAW
データをバインドまたは定義できます。
INSERT
文およびUPDATE
文の使用方法および使用例は、「LOBデータのバインドについて」を参照してください
SELECT
文の使用方法および使用例は、「LOBデータの定義について」を参照してください
表17-2 LOB関数
関数 | 用途 |
---|---|
一時LOBのためのユーザー期間を開始します。 |
|
一時LOBのためのユーザー期間を終了します。 |
|
1つのLOBを別のLOBの後に追加します。 |
|
複数のロケータのLOBデータを読み取ります。 |
|
複数のロケータのLOBデータを書き込みます。 |
|
1つのLOBロケータを別のLOBロケータに割り当てます。 |
|
LOBロケータからキャラクタ・セットを取得します。 |
|
LOBロケータからキャラクタ・セットIDを取得します。 |
|
オープンされているLOBをクローズします。 |
|
LOBの一部または全部を別のLOBにコピーします。4GBを超えるサイズのLOBには、この関数を使用する必要があります。 |
|
一時LOBを作成します。 |
|
LOBバッファリングをオフにします。 |
|
LOBバッファリングをオンにします。 |
|
LOBの一部を消去します。4GBを超えるサイズのLOBには、この関数を使用する必要があります。 |
|
オープンされている |
|
オープンされているすべてのFILEをクローズします。 |
|
サーバー上のファイルの存在をチェックします。 |
|
LOBロケータからディレクトリ・オブジェクトとファイル名を取得します。 |
|
サーバー上のファイルがこのロケータでオープンされているかどうかをチェックします。 |
|
|
|
LOBロケータにディレクトリ・オブジェクトとファイル名を設定します。 |
|
LOBバッファをフラッシュします。 |
|
一時LOBを解放します。 |
|
LOBのチャンク・サイズを取得します。 |
|
SecureFileのユーザー指定コンテンツ・タイプ文字列(ファイル形式識別子)を取り出します。 |
|
LOBの長さを取得します。4GBを超えるサイズのLOBには、この関数を使用する必要があります。 |
|
SecureFileのオプション設定を取得します。 |
|
内部LOB (BLOB、CLOBまたはNCLOB)の最大長(バイト単位)を取得します。 |
|
2つのLOBロケータが等しいか比較します。 |
|
LOBがオープンされているかどうかをチェックします。 |
|
特定のLOBが一時LOBかどうかを判断します。 |
|
|
|
1つのLOBロケータを別のLOBロケータに割り当てます。 |
|
LOBロケータが初期化されているかどうかをチェックします。 |
|
LOBをオープンします。 |
|
LOBの一部を読み取ります。4GBを超えるサイズのLOBには、この関数を使用する必要があります。 |
|
SecureFileのユーザー指定コンテンツ・タイプ文字列を格納します。 |
|
既存のSecureFileと新規に作成されたSecureFileのオプション設定を有効化します。 |
|
LOBを切り捨てます。4GBを超えるサイズのLOBには、この関数を使用する必要があります。 |
|
LOBに書き込みます。4GBを超えるサイズのLOBには、この関数を使用する必要があります。 |
|
LOBの末尾からデータを書き込みます。4GBを超えるサイズのLOBには、この関数を使用する必要があります。 |
OCI LOBコールのパラメータについて、次の点に注意してください。
固定幅のクライアント側キャラクタ・セットの場合、offsetパラメータとamountパラメータは、CLOB
とNCLOB
では常に文字数、BLOB
とBFILE
では常にバイト数です。
可変幅のクライアント側キャラクタ・セットの場合は、一般に次のルールが適用されます。
amount (amtp
)パラメータ - amountパラメータがサーバー側のLOBを参照する場合、その内容は文字数です。amountパラメータがクライアント側のバッファを参照する場合、amountはバイト数です。
詳細は、OCILobGetLength() (非推奨)、OCILobGetLength2()、OCILobRead() (非推奨)、OCILobRead2()、OCILobWrite() (非推奨)、OCILobWrite2()などの各LOBコールを参照してください。
offset (offset
)パラメータ - クライアント側のキャラクタ・セットが可変幅かどうかに関係なく、offsetパラメータは、CLOB
とNCLOB
では常に文字数、BLOB
とBFILE
では常にバイト数です。
LOB操作では、多くの場合、クライアント側のキャラクタ・セットに関係なく、amountパラメータはCLOB
とNCLOB
の文字数です。これらのLOB操作には、OCILobCopy2()、OCILobErase2()、OCILobGetLength2()、OCILobLoadFromFile2()、OCILobTrim2()などがあります。これらのすべての操作では、サーバー上のLOBデータの量を参照します。
ストリーミング操作とは、ピース単位でLOBの読取りまたは書込みを行うことです。ストリームは、ポーリング・メカニズムを使用するか、またはユーザー定義コールバックを登録して実装できます。
一時LOBのためのユーザー期間を開始します。
用途
一時LOBのためのユーザー期間を開始します。
構文
sword OCIDurationBegin ( OCIEnv *env, OCIError *err, const OCISvcCtx *svc, OCIDuration parent, OCIDuration *duration );
パラメータ
NULL
ポインタを渡します。
OCIエラー・ハンドルです。エラーがある場合は、err
に記録され、OCI_ERROR
が戻されます。OCIErrorGet()
のコールによって診断情報を取得できます。
OCIサービス・コンテキスト・ハンドルです。NULL
以外にしてください。
親の継続時間の時間番号です。次のいずれかです。
OCI_DURATION_STATEMENT
OCI_DURATION_SESSION
コメント
この関数によってユーザー期間が開始されます。リリース8.1以上では、一時LOBを作成する際にユーザー期間を使用できます。ユーザーは複数のアクティブなユーザー期間を同時に利用できます。ユーザー期間をネストする必要はありません。duration
パラメータは、このコールによって作成された期間を識別するための一意の番号を戻すために使用します。
一時LOBのためのユーザー期間を終了します。
用途
一時LOBのためのユーザー期間を終了します。
構文
sword OCIDurationEnd ( OCIEnv *env, OCIError *err, const OCISvcCtx *svc, OCIDuration duration );
パラメータ
コメント
この関数によってユーザー期間が終了します。ユーザー期間に割り当てられていた一時LOBが解放されます。
用途
別のLOBの末尾にLOB値を指定どおりに追加します。
構文
sword OCILobAppend ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *dst_locp, OCILobLocator *src_locp );
パラメータ
サービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
一意に宛先LOBを参照する内部LOBロケータです。このロケータは、svchp
に指定したサーバーから取得されたロケータにしてください。
一意にソースLOBを参照する内部LOBロケータです。このロケータは、svchp
に指定したサーバーから取得されたロケータにしてください。
コメント
別のLOBの末尾にLOB値を指定どおりに追加します。データは、ソースから宛先の末尾にコピーされます。コピー元LOBおよびコピー先LOBは、すでに存在している必要があります。宛先LOBは、新たに書き込まれるデータにあわせて拡張されます。許される最大長(4GB)を超える宛先LOBの拡張とNULL
LOBのコピーはエラーになります。
ソースと宛先のLOBロケータは同じ型にしてください(つまり、両方ともBLOB
または両方ともCLOB
)。LOBバッファリングは、ロケータのどちらの型に対しても使用可能にしないでください。この関数では、ソースまたは宛先としてのBFILE
ロケータを受け入れません。
このLOB操作をオープン・コールまたはクローズ・コールで囲む必要はありません。この操作を実行する前にLOBをオープンしていない場合、LOB列のファンクション索引とドメイン索引はこのコール時に更新されます。ただし、この操作を実行する前にLOBをオープンしている場合は、トランザクションをコミットする前に、そのLOBをクローズする必要があります。内部LOBをクローズすると、LOB列のファンクション索引とドメイン索引が更新されます。
LOB操作をオープンAPIまたはクローズAPIで囲んでいない場合、ファンクション索引とドメイン索引は、LOBに書き込むたびに更新されます。これによって、パフォーマンスが低下する可能性があります。ファンクション索引とドメイン索引がある場合は、LOBへの書込み操作をオープン文またはクローズ文内に含めることをお薦めします。
関連関数
OCILobTrim() (非推奨)、OCILobTrim2()、OCILobWrite() (非推奨)、OCILobWrite2()、OCILobCopy() (非推奨)、OCILobCopy2()、OCIErrorGet()、OCILobWriteAppend() (非推奨)、OCILobWriteAppend2()
用途
1回のラウンドトリップで複数のロケータのLOBデータを読み取ります。この関数は、4GBのサイズ制限なしにすべてのLOBに対して使用できます。
構文
sword OCILobArrayRead ( OCISvcCtx *svchp, OCIError *errhp, ub4 *array_iter, OCILobLocator **locp_arr, oraub8 *byte_amt_arr, oraub8 *char_amt_arr, oraub8 *offset_arr, void **bufp_arr, oraub8 bufl_arr, ub1 piece, void *ctxp, OCICallbackLobArrayRead (cbfp) ( void *ctxp, ub4 array_iter, const void *bufp, oraub8 lenp, ub1 piecep void **changed_bufpp, oraub8 *changed_lenp ) ub2 csid, ub1 csfrm );
パラメータ
サービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
IN - このパラメータは、LOBロケータ配列のサイズを指定します。ポーリングでは、このパラメータが関連するのは最初のコールのみで、後続のコールでは無視されます。
OUT - ポーリング・モードの場合に、このパラメータは読取り元の要素の配列索引を指定します。
LOBまたはBFILE
ロケータの配列です。
oraub8
変数の配列です。配列サイズは、ロケータの配列サイズと同じである必要があります。エントリは、ロケータのバイト数に対応します。
IN: データベースから読み取るバイト数です。BLOB
およびBFILE
に対して常に使用されます。CLOB
およびNCLOB
に対しては、char_amt_arr
の該当値が0 (ゼロ)の場合のみ使用されます。
OUT: ユーザー・バッファに読み取られるバイト数です。
oraub8
変数の配列です。配列サイズは、ロケータの配列サイズと同じである必要があります。エントリは、ロケータの文字数に対応します。
IN: ユーザー・バッファに読み取られる最大文字数です。BLOB
およびBFILE
の場合は無視されます。
OUT: ユーザー・バッファに読み取られる文字数です。BLOB
およびBFILE
の場合は未定義になります。
oraub8
変数の配列です。配列サイズは、ロケータの配列サイズと同じである必要があります。文字LOB (CLOB
、NCLOB
)ではLOBの先頭からの文字数であり、バイナリLOBまたはBFILE
ではバイト数です。先頭位置は1です。
ピースの読取り先バッファへのポインタの配列です。配列サイズは、ロケータの配列サイズと同じである必要があります。
バッファ配列のバッファ長を示すoraub8
変数の配列です。配列サイズは、ロケータの配列サイズと同じである必要があります。
OCI_ONE_PIECE
: コールではポーリングは想定されません。示された量がバッファ長より大きい場合、バッファには可能なかぎり格納されます。
ポーリングでは、最初にOCI_FIRST_PIECE
、後続のコールでOCI_NEXT_PIECE
を渡します。OCI_FIRST_PIECE
はコールバックの使用時に渡される必要があります。
コールバック関数用のコンテキスト・ポインタです。NULL
にできます。
各ピースに対してコールされるように登録できるコールバックです。これがNULL
の場合は、ピースごとにOCI_NEED_DATA
が戻ります。
コールバック関数は、OCI_CONTINUE
を戻して読取りを続行する必要があります。これ以外のエラー・コードが戻った場合、LOBの読取りは終了します。
コールバック関数用のコンテキストです。NULL
にできます。
読取り元の要素の索引です。
ピース用のバッファ・ポインタです。
bufp
におけるカレント・ピースのバイト長です。
ピースは、OCI_FIRST_PIECE
、OCI_NEXT_PIECE
またはOCI_LAST_PIECE
です。
コールバック関数は、次に読み取るピースに新規バッファを使用することを選択した場合、新規バッファのアドレスを指定できます。このパラメータがNULL
に設定されている場合、デフォルトの旧バッファbufp
が使用されます。
新規バッファ(指定されている場合)の長さです。
バッファ・データのキャラクタ・セットIDです。この値が0 (ゼロ)の場合は、csfrm
の値に応じて、csid
にクライアントのNLS_LANG
値またはNLS_CHAR
値が設定されます。サーバーとクライアントの設定が同一である場合を除き、サーバーのキャラクタ・セットとはみなされません。
バッファ・データのキャラクタ・セット・フォームです。csfrm
パラメータは、LOBの型と一貫している必要があります。
csfrm
パラメータは、0 (ゼロ)以外の次の2つの値をとることができます。
デフォルト値はSQLCS_IMPLICIT
です。csfrm
が指定されていない場合は、デフォルトが使用されます。
コメント
NULL
属性のLOBまたはBFILE
から読み取るとエラーになります。
注意:
LOBを読み取るかまたは書き込むときは、指定されたキャラクタ・セット・フォーム(csfrm
)がロケータのフォームと一致している必要があります。
BFILE
の場合は、オペレーティング・システム・ファイルがサーバー上に存在しており、それらのファイルは、入力ロケータを使用して OCILobFileOpen()またはOCILobOpen()によってオープンされている必要があります。オペレーティング・システム・ファイルの読取り権限がOracle Databaseにあること、およびディレクトリ・オブジェクトの読取り許可がユーザーにあることが必要です。
OCILobArrayRead()
に対してポーリング・モードを使用するとき、最初のコールではoffset_arr
およびamt_arr
の値を指定する必要がありますが、その後のOCILobArrayRead()
のポーリング・コールではこれらの値を指定する必要はありません。
LOBがBLOB
の場合、csid
パラメータおよびcsfrm
パラメータは無視されます。
注意:
OCILobArrayRead()
操作を終了して文ハンドルを解放するには、OCIBreak()
コールを使用します。
次の点は、ストリーム・モードでのLOBデータの読取りに適用されます。
ポーリング・モードを使用する場合は、最初のOCILobArrayRead()
コールでのみchar_amt_arr
、byte_amt_arr
およびoffset_arr
パラメータを指定してください。後続のポーリング・コールでは、これらのパラメータは無視されます。byte_amt_arr
およびchar_amt_arr
の両方が0 (ゼロ)を指すように設定されており、OCI_FIRST_PIECE
が渡された場合、ポーリング・モードが想定され、LOBの末尾までデータが読み取られます。出力では、byte_amt_arr
は、現在のピースに読み取られるバイト数を示します。CLOB
およびNCLOB
では、char_amt_arr
は現在のピースに読み取られる文字数を示します。
コールバックを使用する場合、lenp
パラメータはコールバックへの入力で、バッファ内で格納されたバイト数を示します。バッファの空き領域を確認するため、コールバック処理中にlenp
パラメータをチェックします。
ポーリングを使用する場合、byte_amt_arr
パラメータを確認し、現在のピースでバッファに格納されている量を確認します。CLOB
およびNCLOB
では、char_amt_arr
はバッファに読み取られる文字数も戻します。
UTF-16形式でデータを読み取るには、csid
パラメータをOCI_UTF16ID
に設定します。csid
パラメータが設定された場合は、このパラメータによって環境変数NLS_LANG
が上書きされます。
関連項目:
Unicode形式の詳細は、「OCIでのPL/SQL REF CURSORおよびNESTED TABLE」を参照してください
BFILE
の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください
LOBの読取りおよび書込み方法を示したコード例については、Oracle Databaseインストレーションに含まれているデモ・プログラムを参照してください。
ピース単位のOCI操作の一般情報は、「OCIでのランタイム・データ割当てとピース単位操作」を参照してください
用途
1回のラウンドトリップで複数のロケータのLOBデータを書き込みます。この関数は、4GBのサイズ制限なしにすべてのLOBに対して使用できます。
構文
sword OCILobArrayWrite ( OCISvcCtx *svchp, OCIError *errhp, ub4 *array_iter, OCILobLocator **locp_arr, oraub8 *byte_amt_arr, oraub8 *char_amt_arr, oraub8 *offset_arr, void **bufp_arr, oraub8 *bufl_arr, ub1 piece, void *ctxp, OCICallbackLobArrayWrite (cbfp) ( void *ctxp, ub4 array_iter, void *bufp, oraub8 *lenp, ub1 *piecep void **changed_bufpp, oraub8 *changed_lenp ) ub2 csid, ub1 csfrm );
パラメータ
サービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
IN - このパラメータは、LOBロケータ配列のサイズを指定します。ポーリングでは、このパラメータが関連するのは最初のコールのみで、後続のコールでは無視されます。
OUT - ポーリング・モードの場合に、このパラメータは書込み先の要素の配列索引を指定します。
LOBロケータの配列です。
oraub8
変数へのポインタの配列です。配列サイズは、ロケータの配列サイズと同じである必要があります。エントリは、ロケータのバイト数に対応します。
IN: データベースに書き込むバイト数です。BLOB
では必ず使用されます。CLOB
およびNCLOB
に対しては、char_amt_arr
が0 (ゼロ)の場合のみ使用されます。
OUT: データベースに書き込むバイト数です。
oraub8
変数へのポインタの配列です。配列サイズは、ロケータの配列サイズと同じである必要があります。エントリは、ロケータの文字数に対応します。
IN: データベースに書き込む最大文字数です。BLOB
では無視されます。
OUT: データベースに書き込む文字数です。BLOB
では未定義となります。
oraub8
変数へのポインタの配列です。配列サイズは、ロケータの配列サイズと同じである必要があります。配列内の各エントリは、LOB値の先頭からの絶対オフセットです。文字LOB (CLOB
、NCLOB
)ではLOBの先頭からの文字数であり、BLOB
ではバイト数です。先頭位置は1です。
ロケータのピースが書き込まれるバッファへのポインタの配列です。配列サイズは、ロケータの配列サイズと同じである必要があります。
バッファ配列のバッファ長を示すoraub8
変数の配列です。配列サイズは、ロケータの配列サイズと同じである必要があります。
注意:
このパラメータは8ビット(1バイト)を仮定します。現行のオペレーティング・システムでこれより長いバイトを使用している場合は、bufl_arr
の値を必要に応じて調整する必要があります。
書込み中のバッファのピースです。このパラメータのデフォルト値は、バッファが単独のピースとして書き込まれることを示すOCI_ONE_PIECE
です。
ピース単位またはコールバック・モードで可能な他の値としては、OCI_FIRST_PIECE
、OCI_NEXT_PIECE
およびOCI_LAST_PIECE
があります。
コールバック関数用のコンテキストです。NULL
にできます。
各ピースに対してコールされるように登録できるコールバックです。これがNULL
の場合は、ピースごとにOCI_NEED_DATA
が戻ります。コールバック関数は、OCI_CONTINUE
を戻して書込みを続行する必要があります。これ以外のエラー・コードが戻った場合、LOBの書込みは終了します。
コールバックは、次のパラメータを取ります。
コールバック関数用のコンテキストです。NULL
にできます。
書込み先の要素の索引です。
ピース用のバッファ・ポインタです。このパラメータは、OCILobArrayWrite()
ルーチンに入力として渡されるbufp
と同じです。
buffer (IN)内のデータのバイト数、およびbufp
(OUT)内のカレント・ピースのバイト数です。
ピースはOCI_NEXT_PIECE
またはOCI_LAST_PIECE
です。
コールバック関数は、次に読み取るピースに新規バッファを使用することを選択した場合、新規バッファのアドレスを指定できます。このパラメータがNULL
に設定されている場合、デフォルトの旧バッファbufp
が使用されます。
新規バッファ(指定されている場合)の長さです。
バッファ内のデータのキャラクタ・セットIDです。この値が0 (ゼロ)の場合は、csfrm
の値に応じて、csid
にクライアントのNLS_LANG
値またはNLS_CHAR
値が設定されます。
バッファ・データのキャラクタ・セット・フォームです。csfrm
パラメータは、LOBの型と一貫している必要があります。
csfrm
パラメータは、0 (ゼロ)以外の次の2つの値をとることができます。
デフォルト値はSQLCS_IMPLICIT
です。
コメント
LOBにデータが存在する場合は、バッファに格納されたデータによって上書きされます。バッファは、このコールによって単独のピースとしてLOBに書き込むことも、コールバックまたは標準ポーリング・メソッドを使用してピース単位で提供することもできます。
注意:
LOBの読取りまたは書込みを行うときは、ロケータのフォームと一致するキャラクタ・セット・フォーム(csfrm
)を指定します。
piece
、csid
およびcsfrm
パラメータは、配列のすべてのロケータで同じです。
OCILobArrayWrite()
に対してポーリング・モードを使用するとき、最初のコールではoffset_arr
、byte_amt_arr
およびchar_amt_arr
の値を指定する必要がありますが、その後のOCILobArrayWrite()
のポーリング・コールではこれらの値を指定する必要はありません。
piece
パラメータの値がOCI_FIRST_PIECE
である場合、データによっては、コールバックまたはポーリングを介して提供される必要があります。
コールバック関数がcbfp
パラメータに定義されている場合は、パイプに1ピースが書き込まれるとこのコールバック関数が呼び出され、次のピースが取得されます。各ピースがbufp_arr
から書き込まれます。コールバック関数が定義されていない場合、OCILobArrayWrite()
は、OCI_NEED_DATA
エラー・コードを戻します。LOBのピースの書込みを続けるには、アプリケーションでOCILobArrayWrite()
を再度コールする必要があります。このモードでは、ピースが別々のサイズで複数の場所に読み取られる場合、コールごとにバッファ・ポインタと長さを変えることができます。
piece
パラメータの値がOCI_LAST_PIECE
のときは、ポーリングまたはコールバック方式が使用されているかどうかに関係なく、ピース単位書込み操作は終了します。
(どの入力方法を使用した場合も)データベースに渡されるデータの量が、byte_amt_arr
またはchar_amt_arr
パラメータに指定された量より少ない場合は、ORA-22993エラーが戻されます。
この関数は内部LOBでのみ有効です。BFILE
は読取り専用なので、取り扱えません。LOBがBLOB
の場合、csid
パラメータおよびcsfrm
パラメータは無視されます。
byte_amt_arr
およびchar_amt_arr
が0 (ゼロ)を指すように設定され、OCI_FIRST_PIECE
が入力として指定されている場合、ポーリング・モードが想定され、OCI_LAST_PIECE
を指定するまでデータが書き込まれます。CLOB
およびNCLOB
では、byte_amt_arr
およびchar_amt_arr
は、それぞれバイト数および文字数で、各ピースごとに書き込まれるデータを戻します。BLOB
では、byte_amt_arr
は各ピースごとに書き込まれるバイト数を戻しますが、出力についてchar_amt_arr
は未定義です。
UTF-16形式でデータを書き込むには、csid
パラメータをOCI_UTF16ID
に設定します。csid
パラメータが設定された場合は、このパラメータによって環境変数NLS_LANG
が上書きされます。
このLOB操作をオープン・コールまたはクローズ・コールで囲む必要はありません。この操作を実行する前にLOBをオープンしていない場合、LOB列のファンクション索引とドメイン索引はこのコール時に更新されます。ただし、この操作を実行する前にLOBをオープンしている場合は、トランザクションをコミットする前に、そのLOBをクローズする必要があります。内部LOBをクローズすると、LOB列のファンクション索引とドメイン索引が更新されます。
LOB操作をオープンAPIまたはクローズAPIで囲んでいない場合、ファンクション索引とドメイン索引は、LOBに書き込むたびに更新されます。これによって、パフォーマンスが低下する可能性があります。ファンクション索引とドメイン索引がある場合は、LOBへの書込み操作をオープン文またはクローズ文内に含めることをお薦めします。
関連項目:
Unicode形式の詳細は、「OCIでのPL/SQL REF CURSORおよびNESTED TABLE」を参照してください
LOBの読取りおよび書込み方法を示したコード例については、Oracle Databaseインストレーションに含まれているデモ・プログラムを参照してください。
ピース単位のOCI操作の一般情報は、「OCIでのランタイム・データ割当てとピース単位操作」を参照してください
用途
LOBまたはBFILE
ロケータを別のロケータに割り当てます。
構文
sword OCILobAssign ( OCIEnv *envhp, OCIError *errhp, const OCILobLocator *src_locp, OCILobLocator **dst_locpp );
パラメータ
OCI環境ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
コピー元のLOBまたはBFILE
ロケータです。
コピー先となるLOBまたはBFILE
ロケータです。コール元で、OCIDescriptorAlloc()をコールしてコピー先のロケータに領域を割り当てる必要があります。
コメント
ソース・ロケータを宛先ロケータに割り当てます。割当て後は、両方のロケータは同じLOB値を参照します。内部LOBの場合は、宛先 ロケータが表に格納されているときにのみ、ソース・ロケータのLOB値が宛先ロケータのLOB値にコピーされます。したがって、宛先ロケータが格納されているオブジェクトのフラッシュを発行すると、LOB値がコピーされます。
リモート・ロケータがそれに渡されると、OCILobAssign()
はエラーをスローします。
OCILobAssign()
は一時LOBには使用できません。OCI_INVALID_HANDLE
エラーが生成されます。一時LOBには、OCILobLocatorAssign()を使用します。
BFILE
では、ファイルを参照するロケータのみが表にコピーされます。オペレーティング・システム・ファイル自体はコピーされません。
BFILE
ロケータを内部LOBロケータに割り当てるとエラーが発生します(逆の場合も同様)。
ソース・ロケータがバッファリング可能な内部LOB用でLOBバッファリング・サブシステムを介したLOBデータの変更に使用されており、そのバッファが書込み後フラッシュされていない場合には、ソース・ロケータが宛先ロケータに割り当てられない場合があります。これは、LOBごとに1つのロケータしかLOBバッファリング・サブシステムを介してLOBデータを変更できないためです。
入力宛先ロケータの値は、OCIDescriptorAlloc()のコールによって割り当てられている必要があります。たとえば、次のように宣言します。
OCILobLocator *source_loc = (OCILobLocator *) 0; OCILobLocator *dest_loc = (OCILobLocator *) 0;
次のコード例は、アプリケーションによるsource_loc
ロケータの割当て方法を示しています。
source_locソース・ロケータの割当て
if (OCIDescriptorAlloc((void *) envhp, (void **) &source_loc, (ub4) OCI_DTYPE_LOB, (size_t) 0, (void **) 0)) handle_error;
次に、表のLOBがsource_loc
に選択され、初期化されます。次のコード例に示すように、アプリケーションでは、OCILobAssign()
コールを発行してsource_loc
の値をdest_loc
に割り当てる前に、宛先ロケータdest_loc
を割り当てる必要があります。
dest_loc宛先ロケータの割当て
if (OCIDescriptorAlloc((void *) envhp, (void **) &dest_loc, (ub4)OCI_DTYPE_LOB, (size_t) 0, (void **) 0)) handle_error; if (OCILobAssign(envhp, errhp, source_loc, &dest_loc)) handle_error
用途
LOBロケータのキャラクタ・セット・フォームを取得します。
構文
sword OCILobCharSetForm ( OCIEnv *envhp, OCIError *errhp, const OCILobLocator *locp, ub1 *csfrm );
パラメータ
OCI環境ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
キャラクタ・セット・フォームを取得するためのLOBロケータです。
入力LOBロケータのキャラクタ・セット・フォームです。入力ロケータのlocp
がBLOB
またはBFILE
用の場合、バイナリのLOBとBFILE
にはキャラクタ・セットという概念がないため、csfrm
には0 (ゼロ)が設定されます。コール元では、csfrm
(ub1
)用の領域を割り当てる必要があります。
csfrm
パラメータは、0 (ゼロ)以外の次の2つの値をとることができます。
コメント
入力CLOB
またはNCLOB
ロケータのキャラクタ・セット・フォームをcsfrm
出力パラメータに戻します。
用途
LOBロケータのデータベース・キャラクタ・セットIDを取得します。
構文
sword OCILobCharSetId ( OCIEnv *envhp, OCIError *errhp, const OCILobLocator *locp, ub2 *csid );
パラメータ
OCI環境ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
キャラクタ・セットIDを取得するためのLOBロケータです。
入力LOBロケータのデータベース・キャラクタ・セットIDです。入力ロケータがBLOB
またはBFILE
用の場合、バイナリLOBまたはバイナリ・ファイルにはキャラクタ・セットという概念がないため、csid
には0 (ゼロ)が設定されます。コール元は、csid
ub2
用の領域を割り当てる必要があります。
コメント
入力CLOB
またはNCLOB
ロケータのキャラクタ・セットIDをcsid
出力パラメータに戻します。
オープンしているLOBまたはBFILE
をクローズします。
用途
オープンしているLOBまたはBFILE
をクローズします。
構文
sword OCILobClose ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp );
パラメータ
コメント
オープンしている内部または外部LOBをクローズします。BFILE
は存在しているが、オープンしていない場合、エラーは戻りません。内部LOBがオープンしていない場合は、エラーが戻されます。
LOBのクローズでは、内部LOBと外部LOBのどちらに対してもサーバーへのラウンドトリップが必要です。内部LOBの場合、closeはクローズ・コールに依存するその他のコードをトリガーし、外部LOB (BFILE
)の場合、closeはサーバー側のオペレーティング・システム・ファイルを実際にクローズします。
すべてのLOB操作をオープン・コールまたはクローズ・コールで囲む必要はありません。ただし、LOBをオープンしている場合は、トランザクションをコミットする前に、そのLOBをクローズする必要があります。内部LOBをクローズすると、LOB列のファンクション索引とドメイン索引が更新されます。トランザクションによってオープンされたすべてのLOBをクローズする前にトランザクションをコミットすると、エラーが発生します。
エラーが戻された場合、それ以降LOBはオープンとしてマークは付けられませんが、トランザクションのコミットは正常に行われます。したがって、そのトランザクションにおけるLOBおよび非LOBデータの変更はすべてコミットされますが、ドメイン索引およびファンクションベースの索引は更新されません。これが起こった場合は、LOB列のファンクション索引とドメイン索引を再作成します。
LOB操作をオープンAPIまたはクローズAPIで囲んでいない場合、ファンクション索引とドメイン索引は、LOBに書き込むたびに更新されます。これによって、パフォーマンスが低下する可能性があるため、ファンクション索引とドメイン索引がある場合は、LOBへの書込み操作をオープン文またはクローズ文内に含めることをお薦めします。
用途
LOB値の全体または一部を別のLOB値にコピーします。4GBを超えるサイズのLOBには、この関数を使用する必要があります。4GB未満のLOBにもこの関数を使用できます。
構文
sword OCILobCopy2 ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *dst_locp, OCILobLocator *src_locp, oraub8 amount, oraub8 dst_offset, oraub8 src_offset );
パラメータ
サービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
一意に宛先LOBを参照する内部LOBロケータです。このロケータは、svchp
に指定したサーバーから取得されたロケータにしてください。
一意にソースLOBを参照する内部LOBロケータです。このロケータは、svchp
に指定したサーバーから取得されたロケータにしてください。
ソースLOBから宛先LOBにコピーされる文字数(CLOB
またはNCLOB
)またはバイト数(BLOB
)です。このパラメータが受け入れる最大値はUB8MAXVAL
(18446744073709551615)です。UB8MAXVAL
を指定することは、指定されたソースおよび宛先のオフセットを使用して、ソースLOBの全体を宛先LOBにコピーすることも意味します。
これは、宛先LOB用の絶対オフセットです。文字LOBでは、LOBの先頭から書込みを開始する位置までの文字数です。バイナリLOBでは、LOBの先頭から書込みを開始する位置までのバイト数です。オフセットは1から始まります。
これは、ソースLOBの絶対オフセットです。文字LOBでは、LOBの先頭からの文字数です。バイナリLOBでは、バイト数です。オフセットは1から始まります。
コメント
内部LOB値全体または一部を別の内部LOB値に指定されたとおりにコピーします。データは、ソースから宛先にコピーされます。ソース(src_locp
) LOBと宛先(dst_locp
) LOBが存在している必要があります。
重複除外を有効にした列またはパーティションの全SecureFileを同じ列またはパーティション内のLOBにコピーすると、コピー内容が重複除外されます。
宛先のコピー開始位置にデータが存在する場合は、ソース・データによって上書きされます。宛先のコピー開始位置がカレント・データの終了位置を超えている場合は、0 (ゼロ)バイトの充填文字(BLOB
の場合)または空白(CLOB
の場合)が、宛先LOBのカレント・データの末尾と、ソースから新たに書き込まれたデータの先頭との間に書き込まれます。新規に書き込むデータが宛先LOBの現行の長さよりも大きい場合、宛先LOBは、そのデータにあわせて拡張されます。許される最大長(つまり、4GB)を超える宛先LOBの拡張とNULL
LOBのコピーはエラーになります。LOBのサイズが4GBを超える場合は、OCILobCopy2()を使用します。
ソースと宛先のLOBロケータは同じ型にしてください(つまり、両方ともBLOB
または両方ともCLOB
)。LOBバッファリングは、ロケータのどちらに対しても使用可能にしないでください。
この関数では、ソースまたは宛先としてのBFILE
ロケータを受け入れません。
このLOB操作をオープン・コールまたはクローズ・コールで囲む必要はありません。この操作を実行する前にLOBをオープンしていない場合、LOB列のファンクション索引とドメイン索引はこのコール時に更新されます。ただし、この操作を実行する前にLOBをオープンしている場合は、トランザクションをコミットする前に、そのLOBをクローズする必要があります。内部LOBをクローズすると、LOB列のファンクション索引とドメイン索引が更新されます。
LOB操作をオープンAPIまたはクローズAPIで囲んでいない場合、ファンクション索引とドメイン索引は、LOBに書き込むたびに更新されます。これによって、パフォーマンスが低下する可能性があります。ファンクション索引とドメイン索引がある場合は、LOBへの書込み操作をオープン文またはクローズ文内に含めることをお薦めします。
注意:
ソースLOBの長さを判断するには、OCILobGetLength2()をコールします。
一時LOBを作成します。
用途
一時LOBを作成します。
構文
sword OCILobCreateTemporary(OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp, ub2 csid, ub1 csfrm, ub1 lobtype, boolean cache, OCIDuration duration);
パラメータ
OCIサービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()
に渡すエラー・ハンドルです。
一時LOBを指し示すロケータです。ロケータをこの関数に渡す前に、OCIDescriptorAlloc()
を使用してロケータを割り当てる必要があります。このロケータは、LOBを指し示しているかどうかに関係なく、いずれの場合も一時LOBにより上書きされます。
LOBキャラクタ・セットIDです。Oracle8i以上ではOCI_DEFAULT
を渡します。
バッファ・データのLOBキャラクタ・セット・フォームです。csfrm
パラメータは、0 (ゼロ)以外の次の2つの値をとることができます。
SQLCS_IMPLICIT
- CLOB
を作成するためのデータベース・キャラクタ・セットID。OCI_DEFAULT
を使用して、CLOB
を暗黙的に作成することもできます。
SQLCS_NCHAR
- NCLOB
を作成するためのNCHAR
キャラクタ・セットID。
デフォルト値はSQLCS_IMPLICIT
です。
OCI_TEMP_BLOB
- 一時BLOB
の場合
OCI_TEMP_CLOB
- 一時CLOB
またはNCLOB
の場合
一時LOBをキャッシュに読み取る必要がある場合はTRUE
を、その必要がない場合はFALSE
を渡します。NOCACHE
機能の場合、デフォルトはFALSE
です。
一時LOBの継続時間です。次に示す値が有効です。
OCI_DURATION_SESSION
OCI_DURATION_CALL
コメント
この関数は、ユーザーの一時表領域に一時LOBとそれに対応する索引を作成します。
この関数が完了すると、locp
パラメータは、長さが0 (ゼロ)の空の一時LOBを指し示します。
一時LOBの存続期間は、duration
パラメータによって決まります。一時LOBは、この期間の最後に解放されます。アプリケーションからOCILobFreeTemporary()
コールを使用すると、一時LOBをより早く解放できます。
LOBがBLOB
の場合、csid
パラメータおよびcsfrm
パラメータは無視されます。
関連項目:
一時LOBとその継続時間の詳細は、「一時LOBのサポート」を参照してください
用途
入力ロケータのLOBバッファリングを使用禁止にします。
構文
sword OCILobDisableBuffering ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp );
パラメータ
サービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
一意にLOBを参照する内部LOBロケータです。
コメント
入力内部LOBロケータのLOBバッファリングを使用禁止にします。次回入力ロケータを通してLOBに対してデータの読取りまたは書込みを行うときは、LOBバッファリング・サブシステムは使用されません。このコールでは、バッファリング・サブシステムでの変更は暗黙的にはフラッシュされません。ユーザーは、OCILobFlushBuffer()をコールして変更を明示的にフラッシュする必要があります。
この関数は、BFILE
ロケータを受け入れません。
用途
入力ロケータのLOBバッファリングを使用可能にします。
構文
sword OCILobEnableBuffering ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp );
パラメータ
サービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
一意にLOBを参照する内部LOBロケータです。
コメント
入力内部LOBロケータのLOBバッファリングを使用可能にします。次回入力ロケータを通してLOBに対してデータの読取りまたは書込みを行うときは、LOBバッファリング・サブシステムが使用されます。
ロケータのLOBバッファリングが使用可能な状態で、そのロケータがルーチンOCILobAppend()、OCILobCopy() (非推奨)、OCILobCopy2()、OCILobErase() (非推奨)、OCILobErase2()、OCILobGetLength() (非推奨)、OCILobGetLength2()、OCILobLoadFromFile() (非推奨)、OCILobLoadFromFile2()、OCILobTrim() (非推奨)、OCILobTrim2()、OCILobWriteAppend() (非推奨)またはOCILobWriteAppend2()のいずれかに渡されると、エラーが戻ります。
この関数は、BFILE
ロケータを受け入れません。
用途
内部LOBデータの一部を指定のオフセットの位置から消去します。4GBを超えるサイズのLOBには、この関数を使用する必要があります。4GB未満のLOBにもこの関数を使用できます。
構文
sword OCILobErase2 ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp, oraub8 *amount, oraub8 offset );
パラメータ
サービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
一意にLOBを参照する内部LOBロケータです。このロケータは、svchp
に指定したサーバーから取得されたロケータにしてください。
消去する文字数(CLOB
またはNCLOB
の場合)またはバイト数(BLOB
の場合)です。INでは、値は消去する文字数またはバイト数を表します。OUTでは、値は消去された実際の文字数またはバイト数です。
データの消去を開始するLOB値の、先頭からの絶対オフセット(CLOB
またはNCLOB
の場合は文字数、BLOB
の場合はバイト数)です。オフセットは1から始まります。
コメント
実際に消去した文字数またはバイト数が戻ります。BLOB
の場合、消去するということは、0 (ゼロ)バイトの充填文字で既存のLOB値を上書きするということです。CLOB
の場合は、既存のLOB値が空白で上書きされます。
この関数は内部LOBにのみ有効で、BFILE
には使用できません。
このLOB操作をオープン・コールまたはクローズ・コールで囲む必要はありません。この操作を実行する前にLOBをオープンしていない場合、LOB列のファンクション索引とドメイン索引はこのコール時に更新されます。ただし、この操作を実行する前にLOBをオープンしている場合は、トランザクションをコミットする前に、そのLOBをクローズする必要があります。内部LOBをクローズすると、LOB列のファンクション索引とドメイン索引が更新されます。
LOB操作をオープンAPIまたはクローズAPIで囲んでいない場合、ファンクション索引とドメイン索引は、LOBに書き込むたびに更新されます。これによって、パフォーマンスが低下する可能性があります。ファンクション索引とドメイン索引がある場合は、LOBへの書込み操作をオープン文またはクローズ文内に含めることをお薦めします。
オープンしているBFILE
をクローズします。
用途
オープンしているBFILE
をクローズします。
構文
sword OCILobFileClose ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *filep );
パラメータ
コメント
オープンしているBFILE
をクローズします。内部LOBに対してこの関数をコールするとエラーになります。BFILE
は存在しているが、オープンしていない場合、エラーは戻りません。
この関数は、特定のBFILE
ロケータに対して初めてコールしたときにかぎり有効です。同じBFILE
ロケータを使用してこの関数を続けてコールしても何も行われません。
関連項目:
BFILE
の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください
指定のサービス・コンテキストでオープンしているすべてのBFILE
をクローズします。
用途
指定のサービス・コンテキストでオープンしているすべてのBFILE
をクローズします。
構文
sword OCILobFileCLoseAll ( OCISvcCtx *svchp, OCIError *errhp );
コメント
指定のサービス・コンテキストでオープンしているすべてのBFILE
をクローズします。
関連項目:
BFILE
の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください
サーバーのオペレーティング・システムにBFILE
が存在するかどうかをテストします。
用途
サーバーのオペレーティング・システムにBFILE
が存在するかどうかをテストします。
構文
sword OCILobFileExists ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *filep, boolean *flag );
パラメータ
コメント
サーバーのファイル・システムにBFILE
が存在するかどうかをチェックします。内部LOBに対してこの関数をコールするとエラーになります。
関連項目:
BFILE
の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください
BFILE
ロケータのディレクトリ・オブジェクトおよびファイル名を取得します。
用途
BFILE
ロケータのディレクトリ・オブジェクトおよびファイル名を取得します。
構文
sword OCILobFileGetName ( OCIEnv *envhp, OCIError *errhp, const OCILobLocator *filep, OraText *dir_alias, ub2 *d_length, OraText *filename, ub2 *f_length );
パラメータ
OCI環境ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()
に渡すエラー・ハンドルです。
ディレクトリ・オブジェクトおよびファイル名を取得するためのBFILE
ロケータです。
ディレクトリ・オブジェクトが配置されているバッファです。これはUTF-16で可能です。ディレクトリ・オブジェクト用の十分な領域を割り当てる必要があります。ディレクトリ・オブジェクトの最大長は30バイトです。
次の用途に使用できます(Unicodeのコードポイントまたはバイト単位が可能です)。
IN: 入力dir_alias
文字列の長さ
OUT: 戻されるdir_alias
文字列の長さ
ファイル名が配置されているバッファです。ファイル名用の十分な領域を割り当てる必要があります。ファイル名の最大長は255バイトです。
次の用途に使用できます(バイト数単位)。
IN: 入力filename
バッファの長さ
OUT: 戻されるfilename
文字列の長さ
コメント
このBFILE
ロケータに対応付けられたディレクトリ・オブジェクトとファイル名を戻します。環境ハンドルによって、Unicodeかどうかが判断されます。内部LOBに対してこの関数をコールするとエラーになります。
関連項目:
BFILE
の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください
BFILE
がオープンしているかどうかをテストします。
用途
BFILE
がオープンしているかどうかをテストします。
構文
sword OCILobFileIsOpen ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *filep, boolean *flag );
パラメータ
コメント
サーバー上のファイルがfilep
BFILE
ロケータを使用してオープンされたかどうかをチェックします。内部LOBに対してこの関数をコールするとエラーになります。
OCILobFileOpen()
またはOCILobOpen()
コマンドに入力BFILE
ロケータが渡されなかった場合、ファイルはそのロケータによってオープンされていないとみなされます。ただし、別のロケータがそのファイルをオープンしていることがあります。オープンは、特定のロケータに対応付けられます。
関連項目:
BFILE
の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください
読取り専用アクセス用にサーバーのファイル・システム上のBFILE
をオープンします。
用途
読取り専用アクセス用にサーバーのファイル・システム上のBFILE
をオープンします。
構文
sword OCILobFileOpen ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *filep, ub1 mode );
パラメータ
コメント
サーバーのファイル・システムのBFILE
をオープンします。BFILE
は、読取り専用アクセス用にオープンできます。BFILE
は、Oracle Databaseを通して書き込むことはできません。内部LOBに対してこの関数をコールするとエラーになります。
この関数は、特定のBFILE
ロケータに対して初めてコールしたときにかぎり有効です。同じBFILE
ロケータを使用してこの関数を続けてコールしても何も行われません。
関連項目:
BFILE
の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください
BFILE
ロケータ内にディレクトリ・オブジェクトとファイル名を設定します。
用途
BFILE
ロケータ内にディレクトリ・オブジェクトとファイル名を設定します。
構文
sword OCILobFileSetName ( OCIEnv *envhp, OCIError *errhp, OCILobLocator **filepp, const OraText *dir_alias, ub2 d_length, const OraText *filename, ub2 f_length );
パラメータ
OCI環境ハンドルです。UTF-16設定が含まれます。
エラー発生時の診断情報のためにOCIErrorGet()
に渡すエラー・ハンドルです。
ディレクトリ・オブジェクトおよびファイル名を設定するBFILE
ロケータへのポインタです。
BFILE
ロケータに設定するディレクトリ・オブジェクト名(OCIEnvNlsCreate()の直前のコールのcharset
パラメータで指定されたエンコーディングが必要)が含まれたバッファです。
入力dir_alias
パラメータの長さ(バイト単位)です。
BFILE
ロケータに設定するファイル名(OCIEnvNlsCreate()
の直前のコールのcharset
パラメータで指定されたエンコーディングが必要)が含まれたバッファです。
入力filename
パラメータの長さ(バイト単位)です。
コメント
内部LOBに対してこの関数をコールするとエラーになります。
関連項目:
BFILE
の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください
用途
このLOBのすべてのバッファをサーバーにフラッシュするか、または書き込みます。
構文
sword OCILobFlushBuffer ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp ub4 flag );
パラメータ
サービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
LOBを一意に参照する内部ロケータです。
このフラグをOCI_LOB_BUFFER_FREE
に設定すると、LOBのバッファ・リソースは、フラッシュの後に解放されます。「コメント」の項を参照してください。
コメント
入力ロケータによって参照されるLOBに関連するバッファリング・サブシステムに加えられた変更を、サーバーにフラッシュします。このルーチンでは、バッファのデータをデータベースのLOBに実際に書き込みます。LOBバッファリングは入力LOBロケータに対して使用可能にしてください。
このフラッシュ操作のデフォルトでは、別のバッファLOB操作への再割当て用にバッファ・リソースは解放されません。バッファを明示的に解放する場合は、flagパラメータをOCI_LOB_BUFFER_FREE
に設定できます。
クライアント・アプリケーションでフラッシュ後のバッファ値を読み取る予定で、あらかじめバッファの現在値が望む値であることがわかっている場合、サーバーからデータを再度読み取る必要はありません。
バッファの解放による影響はユーザーにはほとんど認識されません。ただし、LOB内の同じ範囲に次にアクセスするときに、サーバーをラウンドトリップすることになり、バッファ・リソースの取得およびLOBから読み取られるデータによるバッファの初期化のための追加コストがかかります。このオプションは、オンボード・メモリーが少ないクライアント環境用です。
用途
一時LOBを解放します。
構文
sword OCILobFreeTemporary( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp);
パラメータ
OCIサービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
解放するLOBを一意に参照するロケータです。
コメント
このロケータが指し示す一時LOBの内容を解放します。ロケータ自体は、OCIDescriptorFree() がコールされるまで解放されません。
locp
パラメータで渡されるLOBロケータが一時LOBを指し示していない場合は、エラーを戻します。LOBロケータが次のようであることが原因である可能性があります。
永続LOBを指し示しています。
解放された一時LOBを指し示しています。
何も指し示していません。
LOBのチャンク・サイズを取得します。
用途
LOBのチャンク・サイズを取得します。
構文
sword OCILobGetChunkSize ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp, ub4 *chunk_size );
パラメータ
サービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()
に渡すエラー・ハンドルです。
使用可能なチャンク・サイズを取得する内部LOBです。
記憶域パラメータBASICFILE
を使用するLOBの場合、内部LOB値を格納するために使用するチャンク領域の量です。これは、ユーザーがLOB値の読取りまたは書込み時に使用する量です。可能な場合は、チャンクの先頭などのチャンクの境界で書込みを開始し、1つのチャンクを1回で書き込みます。
chunk_size
パラメータは、BLOB
、CLOB
およびNCLOB
に対して、バイト数で戻されます。
記憶域パラメータSECUREFILE
を使用するLOBの場合、chunk_size
は推奨サイズであり、下位互換性のために提供されています。
コメント
内部LOBを含む表を作成する際には、ユーザーがチャンク係数を指定できます。これは、Oracle Databaseのブロック数の倍数です。これは、LOB値のアクセス時または変更時にLOBデータ・レイヤーによって使用されるチャンク・サイズに対応します。チャンクの一部はシステム関連情報の格納に使用され、それ以外の部分にLOB値が格納されます。このファンクションは、LOB値を格納するLOBチャンクで使用される領域容量を戻します。アプリケーションがこのチャンク・サイズの倍数を使用して読取りまたは書込みリクエストを発行すると、パフォーマンスが向上します。LOBチャンクはバージョン化され、すべての書込みがチャンクを基準に行われると、余分なバージョン分割が行われず、重複もしないため、書込みの場合にはさらに利点があります。ユーザーは同一チャンクに対してwriteコールを複数回発行するかわりに、1つのチャンク内でwriteコールを十分な数だけまとめることができます。
用途
SecureFile内のデータのユーザー指定コンテンツ・タイプ文字列を取得します(設定されている場合)。
構文
sword OCILobGetContentType ( OCIEnv *envhp, OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *lobp, oratext *contenttypep, ub4 *contenttypelenp, ub4 mode );
パラメータ
環境ハンドルです。
サービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
一意にLOBを参照するLOBロケータです。
正常に実行された後、コンテンツ・タイプが格納されるバッファへのポインタです。この関数をコールする前に、バッファを割り当てる必要があります。割当てバッファのサイズは>= OCI_LOB_CONTENTTYPE_MAXSIZE
であることが必要です。
このフィールドをcontenttypep
バッファのサイズに設定します。コールが正常に実行された後、このフィールドは、戻されたcontenttypep
のサイズを保持します。
今後の使用のために確保されています。現時点では0 (ゼロ)を渡します。
コメント
この関数はSecureFileでのみ機能します。lobp
がSecureFileでない場合、SECUREFILE_WRONGTYPE
エラーが戻されます。lobp
がバッファリングされた一時LOBまたは抽象LOBである場合、SECUREFILE_BADLOB
エラーが戻されます。
SecureFileにcontenttype
が関連付けられていない場合、バッファcontenttypep
は変更されず、contenttype
の長さ(contenttypelenp
)が0 (ゼロ)で戻されます。
ContentType
文字列の最大可能サイズは次のように定義されています。
#define OCI_LOB_CONTENTTYPE_MAXSIZE 128
ContentType
はASCII (つまり、1バイトまたは7ビットUTF8)です。
用途
LOBの長さを取得します。4GBを超えるサイズのLOBには、この関数を使用する必要があります。4GB未満のLOBにもこの関数を使用できます。
構文
sword OCILobGetLength2 ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp, oraub8 *lenp );
パラメータ
サービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
一意にLOBを参照するLOBロケータです。内部LOBでは、このロケータは、svchp
に指定したサーバーから取得されたロケータにしてください。BFILE
の場合は、OCILobFileSetName()、SELECT
文またはOCIObjectPin()を使用してロケータを設定できます。
出力時、LOBがNULL
ではない場合、LOBの長さを示します。文字LOBでは文字数であり、バイナリLOBおよびBFILE
ではLOBのバイト数です。
コメント
LOBの長さを取得します。LOBがNULL
の場合、長さは未定義です。BFILE
の長さにはEOF (存在する場合)が含まれます。空の内部LOBの長さは0 (ゼロ)です。
クライアント側のキャラクタ・セットが可変幅かどうかに関係なく、出力の長さは、CLOB
とNCLOB
では文字数、BLOB
とBFILE
ではバイト数です。
注意:
以前のOCILobErase2()
またはOCILobWrite2()
のコールによってLOBに書き込まれた0 (ゼロ)バイトや空白の充填文字も、長さの一部になります。
用途
指定のSecureFile LOBについて指定の入力オプション・タイプに対応する、有効化された設定を取得します。
構文
sword OCILobGetOptions ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp, ub4 option_types, void *optionsp, ub4 optionslenp, ub4 mode );
パラメータ
サービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
一意にLOBまたはBFILE
を参照するLOBロケータまたはBFILE
ロケータです。このロケータは、svchp
に指定したサーバーから取得されるようにしてください。
ビット単位の包含OR
(記号「|」)で結合可能な指定のオプション・タイプです。
圧縮: OCI_LOB_OPT_COMPRESS
暗号化: OCI_LOB_OPT_ENCRYPT
重複除外: OCI_LOB_OPT_DEDUPLICATE
指定の各オプション・タイプの現行設定です。可能な値は次のとおりです。
OCI_LOB_OPT_COMPRESS_ON
OCI_LOB_OPT_ENCRYPT_ON
OCI_LOB_OPT_DEDUPLICATE_ON
optionsp
で示した値の長さです。
今後の使用のために確保されています。0 (ゼロ)を渡します。
コメント
指定できるのは、列で有効化されているオプション・タイプのみです。列で有効化されていないオプション・タイプの値を取得しようとすると、エラーが戻されます。たとえば、圧縮が有効化されているLOB列があり、option_types
パラメータにOCI_LOB_OPT_ENCRYPT
を設定してOCILobGetOptions()
をコールすると、エラーが発生します。
戻り値はvoid
ポインタとしてキャストされたub4
ポインタであり、今後のオプション・タイプおよび値の拡張が可能です。戻されるoptionslenp
はsizeof(ub4)
である必要があります。
内部LOB (BLOB
、CLOB
またはNCLOB
)の最大長(バイト単位)を取得します。
用途
内部LOB (BLOB
、CLOB
またはNCLOB
)の最大長(バイト単位)を取得します。
構文
sword OCILobGetStorageLimit ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp, oraub8 *limitp );
パラメータ
コメント
ブロック・サイズの範囲は2から32KBであるため、LOBの場合、最大LOBサイズの範囲は8から128TBです。
用途
2つのLOBまたはBFILE
ロケータの等価を比較します。
構文
sword OCILobIsEqual ( OCIEnv *envhp, const OCILobLocator *x, const OCILobLocator *y, boolean *is_equal );
パラメータ
コメント
指定されたLOBまたはBFILE
ロケータの等価を比較します。2つのLOBまたはBFILE
ロケータは、どちらも同じLOBまたはBFILE
値を参照している場合にのみ等価になります。
この関数では、2つのNULL
ロケータは等価とはみなされません。
LOBまたはBFILE
がオープンされているかどうかを確認します。
用途
LOBまたはBFILE
がオープンされているかどうかを確認します。
構文
sword OCILobIsOpen ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp, boolean *flag );
パラメータ
コメント
内部LOBがオープンされているかどうか、またはBFILE
が入力ロケータを使用してオープンされているかどうかをチェックします。
入力BFILE
ロケータがOCILobOpen()
またはOCILobFileOpen()
に渡されていない場合は、このBFILE
ロケータによってBFILE
はオープンされないとみなされます。ただし、別のBFILE
ロケータによってBFILE
がオープンされている場合はあります。別のロケータを使用して、そのBFILE
に対して複数のオープンが実行されることがあります。つまり、オープンはBFILE
の特定のロケータに関連付けられています。
オープンは、ロケータではなくLOBに関連付けられます。locator1
がLOBをオープンした場合は、locator2
もオープン時にそのLOBを参照します。
内部LOBの場合、このコールでは、サーバー上の状態によって、LOBがオープンしているかどうかを確認するため、サーバー・ラウンドトリップが必要です。外部LOB (BFILE
)の場合も、サーバー側のオペレーティング・システム・ファイルによってそのLOBがオープンされているかどうかを確認するため、ラウンドトリップが必要です。
用途
ロケータが一時LOBを指し示しているかどうかを確認します。
構文
sword OCILobIsTemporary(OCIEnv *envhp, OCIError *errhp, OCILobLocator *locp, boolean *is_temporary);
パラメータ
OCI環境ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
確認するロケータです。
ロケータが一時LOBを指し示している場合はTRUE
を、そうでない場合はFALSE
を戻します。
コメント
この関数は、ロケータが一時LOBを指し示しているかどうかを調べるためにロケータを確認します。指し示している場合は、is_temporary
がTRUE
に設定されます。そうでない場合は、is_temporary
がFALSE
に設定されます。
用途
ファイルの全体または一部を内部LOBにロードおよびコピーします。4GBを超えるサイズのLOBには、この関数を使用する必要があります。4GB未満のLOBにもこの関数を使用できます。
構文
sword OCILobLoadFromFile2 ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *dst_locp, OCILobLocator *src_locp, oraub8 amount, oraub8 dst_offset, oraub8 src_offset );
パラメータ
サービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
BLOB
型、CLOB
型またはNCLOB
型の宛先内部LOBを一意に参照するロケータです。
ソースBFILE
を一意に参照するロケータです。
ロードされるバイト数です。
これは、宛先LOB用の絶対オフセットです。文字LOBでは、LOBの先頭から書込みを開始する位置までの文字数です。バイナリLOBでは、LOBの先頭から読取りを開始する位置までのバイト数です。オフセットは1から始まります。
これは、ソースBFILE
の絶対オフセットです。BFILE
の先頭からのバイト数です。オフセットは1から始まります。
コメント
BFILE
値の一部またはすべてを指定どおりに内部LOBにロードおよびコピーします。データは、ソースBFILE
から宛先の内部LOB (BLOB
またはCLOB
)にコピーされます。BFILE
データをCLOB
またはNCLOB
にコピーするときに、キャラクタ・セットの変換は実行されません。バイナリ・データがBLOB
にロードされるときにも、キャラクタ・セット変換は実行されません。このため、BFILE
データは、データベースのLOBと同じキャラクタ・セットにする必要があります。これを検証するエラー・チェックは実行されません。
ソース(src_locp
) LOBと宛先(dst_locp
) LOBが存在している必要があります。宛先のコピー開始位置にデータが存在する場合は、ソース・データによって上書きされます。宛先のコピー開始位置がカレント・データの終了位置を超えている場合は、0 (ゼロ)バイトの充填文字(BLOB
の場合)または空白(CLOB
の場合)が、宛先LOBのデータの末尾と、ソースから新たに書き込まれたデータの先頭との間に書き込まれます。新規に書き込むデータが宛先LOBの現行の長さよりも大きい場合、宛先LOBは、そのデータにあわせて拡張されます。
許される最大長(4GB)を超える宛先LOBの拡張(4GBを超えるサイズのLOBに使用する場合はOCILobLoadFromFile2()を参照)と、NULL BFILE
のコピーは、エラーになります。
このLOB操作をオープン・コールまたはクローズ・コールで囲む必要はありません。この操作を実行する前にLOBをオープンしていない場合、LOB列のファンクション索引とドメイン索引はこのコール時に更新されます。ただし、この操作を実行する前にLOBをオープンしている場合は、トランザクションをコミットする前に、そのLOBをクローズする必要があります。内部LOBをクローズすると、LOB列のファンクション索引とドメイン索引が更新されます。
LOB操作をオープンAPIまたはクローズAPIで囲んでいない場合、ファンクション索引とドメイン索引は、LOBに書き込むたびに更新されます。これによって、パフォーマンスが低下する可能性があります。ファンクション索引とドメイン索引がある場合は、LOBへの書込み操作をオープン文またはクローズ文内に含めることをお薦めします。
用途
LOBまたはBFILE
ロケータを別のロケータに割り当てます。
構文
sword OCILobLocatorAssign ( OCISvcCtx *svchp, OCIError *errhp, const OCILobLocator *src_locp, OCILobLocator **dst_locpp );
パラメータ
OCIサービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
コピー元のLOBまたはBFILE
ロケータです。
コピー先となるLOBまたはBFILE
ロケータです。コール元で、OCIDescriptorAlloc()をコールしてOCILobLocator
に領域を割り当てる必要があります。
コメント
このコールは、ソース・ロケータを宛先ロケータに割り当てます。割当て後は、両方のロケータは同じLOBデータを参照します。内部LOBの場合は、宛先ロケータが表に格納されているときのみ、ソース・ロケータのLOBデータが宛先ロケータのLOBデータにコピーされます。このため、宛先ロケータが含まれているオブジェクトにフラッシュを発行すると、LOBデータがコピーされます。BFILE
の場合、オペレーティング・システム・ファイルを参照するロケータのみが表にコピーされ、オペレーティング・システム・ファイルはコピーされません。
このコールはOCILobAssign()と似ていますが、OCILobLocatorAssign()
はOCI環境ハンドル・ポインタではなく、OCIサービス・ハンドル・ポインタを使用します。また、OCILobLocatorAssign()
は一時LOBに対して使用できますが、OCILobAssign()は使用できません。
注意:
OCILobLocatorAssign()
関数が正常に終了しなかった場合、ターゲット・ロケータは以前の状態にはリストアされません。ターゲット・ロケータは、初期化しなおすまで、後続の操作で使用しないでください。
宛先ロケータが一時LOBに対するロケータの場合、宛先一時LOBは、ソースLOBロケータを割り当てる前に解放されます。
ソースLOBロケータから一時LOBを参照すると、宛先ロケータが一時LOBにも作成されます。ソース・ロケータと宛先ロケータは、理論的には異なる一時LOBになります。OCI_DEFAULT
モードでは、ソースの一時LOBがディープ・コピーされ、その一時LOBの新しいディープ・コピーを参照するために宛先ロケータが作成されます。したがって、OCILobLocatorAssign()
をコールした後は、OCILobIsEqual()でFALSE
が戻ります。ただし、OCI_OBJECT
モードの場合は、ディープ・コピー数を最小化するために最適化が行われるため、ソース・ロケータと宛先ロケータは、いずれかのLOBロケータを介して変更が行われるまで、同じLOBを指し示します。したがって、最初の変更が行われるまで、OCILobLocatorAssign()
直後のOCILobIsEqual()では、TRUE
が戻ります。これらのいずれの場合にも、OCILobLocatorAssign()
後のソースまたは宛先に対する変更は、他方(つまり、宛先またはソース)のLOBには反映されません。ソースおよび宛先が同じLOBを指し示し、変更を他方にも反映する場合は、等号を使用して、2つのLOBロケータ・ポインタが同じLOBロケータを参照するようにします。
指定されたLOBまたはBFILE
ロケータが初期化されているかどうかをテストします。
用途
指定されたLOBまたはBFILE
ロケータが初期化されているかどうかをテストします。
構文
sword OCILobLocatorIsInit ( OCIEnv *envhp, OCIError *errhp, const OCILobLocator *locp, boolean *is_initialized );
パラメータ
コメント
指定されたLOBまたはBFILE
ロケータが初期化されているかどうかをテストします。
内部LOBロケータは、次のいずれかの方法で初期化できます。
NULL
以外のLOBをロケータに選択します。
OCIObjectPin()
を使用して、LOB属性がNULL
以外のオブジェクトを確保します。
OCIAttrSet()
を使用して、ロケータをEmpty値に設定します。
関連項目:
BFILE
ロケータは、次のいずれかの方法で初期化できます。
NULL
以外のBFILE
をロケータに選択します。
OCIObjectPin()
を使用して、BFILE
属性がNULL
以外のオブジェクトを確保します。
OCILobFileSetName()をコールします。
指定されたモードでLOB (内部または外部)をオープンします。
用途
指定されたモードでLOB (内部または外部)をオープンします。
構文
sword OCILobOpen ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp, ub1 mode );
パラメータ
サービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()
に渡すエラー・ハンドルです。
オープンするLOBです。ロケータは、内部LOBまたは外部LOBを参照できます。
LOBまたはBFILE
をオープンするモードです。Oracle8i以上の場合、LOBに対する有効なモードは、OCI_LOB_READONLY
およびOCI_LOB_READWRITE
です。OCI_FILE_READONLY
は、OCILobFileOpen()
の入力モードとして使用します。入力ロケータがBFILE
に対するロケータの場合、OCI_FILE_READONLY
はOCILobOpen()
とともに使用できます。
コメント
同じLOBを2度オープンするとエラーが発生します。BFILE
は、読取り/書込みモードではオープンできません。読取り専用モードでオープンされているLOBまたはBFILE
に書込みを行うと、エラーが戻されます。
LOBのオープンでは、内部LOBと外部LOBのどちらに対してもサーバーへのラウンドトリップが必要です。内部LOBをオープンすると、そのオープン・コールに応じて他のコードが実行されます。外部LOB (BFILE
)をオープンすると、サーバー側のオペレーティング・システム・ファイルがオープンされるため、ラウンドトリップが必要です。
LOBを操作するために、LOBをオープンする必要はありません。ファンクション索引、拡張索引作成機能またはコンテキストを使用し、複数のコールを行ってLOBに対する更新または書込みを行う場合は、最初にOCILobOpen()
をコールし、次に、そのLOBを必要な回数だけ更新し、最後にOCILobClose()
をコールします。この一連の操作によって、索引は、書込み操作ごとに更新されるのではなく、すべての書込み操作の最後に1回更新されます。
すべてのLOB操作をオープン・コールとクローズ・コールで囲む必要はありません。ただし、LOBをオープンしている場合は、トランザクションをコミットする前に、そのLOBをクローズする必要があります。内部LOBをクローズすると、LOB列のファンクション索引とドメイン索引が更新されます。トランザクションによってオープンされたすべてのLOBをクローズする前にトランザクションをコミットすると、エラーが発生します。
エラーが戻された場合、それ以降LOBはオープンとしてマークは付けられませんが、トランザクションのコミットは正常に行われます。したがって、そのトランザクションにおけるLOBおよび非LOBデータの変更はすべてコミットされますが、ドメイン索引およびファンクションベースの索引は更新されません。これが起こった場合は、LOB列のファンクション索引とドメイン索引を再作成します。
LOB操作をオープンAPIまたはクローズAPIで囲んでいない場合、ファンクション索引とドメイン索引は、LOBに書き込むたびに更新されます。これによって、パフォーマンスが低下する可能性があるため、ファンクション索引とドメイン索引がある場合は、LOBへの書込み操作をオープン文またはクローズ文内に含めることをお薦めします。
LOBまたはBFILE
の一部をコールの指定どおりにバッファに読み取ります。4GBを超えるサイズのLOBには、この関数を使用する必要があります。
用途
4GB未満のLOBにもこの関数を使用できます。
構文
sword OCILobRead2 ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp, oraub8 *byte_amtp, oraub8 *char_amtp, oraub8 offset, void *bufp, oraub8 bufl, ub1 piece, void *ctxp, OCICallbackLobRead2 (cbfp) ( void *ctxp, const void *bufp, oraub8 lenp, ub1 piecep void **changed_bufpp, oraub8 *changed_lenp ) ub2 csid, ub1 csfrm );
パラメータ
サービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()
に渡すエラー・ハンドルです。
一意にLOBまたはBFILE
を参照するLOBまたはBFILE
ロケータです。このロケータは、svchp
に指定したサーバーから取得されたロケータにしてください。
IN: データベースから読み取るバイト数です。BLOB
およびBFILE
に対して常に使用されます。CLOB
およびNCLOB
,に対しては、char_amtp
が0 (ゼロ)の場合のみ使用されます。
OUT: ユーザー・バッファに読み取られるバイト数です。
IN: ユーザー・バッファに読み取られる最大文字数です。BLOB
およびBFILE
の場合は無視されます。
OUT: ユーザー・バッファに読み取られる文字数です。BLOB
およびBFILE
の場合は未定義になります。
入力時、これはLOB値の先頭からの絶対オフセットです。文字LOB (CLOB
、NCLOB
)ではLOBの先頭からの文字数であり、バイナリLOBまたはBFILE
ではバイト数です。先頭位置は1です。
ポーリングまたはコールバックによるストリームを使用する場合は、最初のコールでオフセットを指定します。後続のポーリング・コールでは、offsetパラメータは無視されます。コールバックを使用する場合、offsetパラメータはありません。
ピースの読取り先バッファへのポインタです。bufl
のメモリー長が割り当てられるとみなされます。
オクテットで示したバッファの長さです。bufl
パラメータがバイト数で指定され、amtp
パラメータが文字で指定されている場合、この値は、CLOB
およびNCLOB
のamtp
値(csfrm
=SQLCS_NCHAR
)とは異なります。
OCI_ONE_PIECE
: コールではポーリングは想定されません。示された量がバッファ長より大きい場合、バッファには可能なかぎり格納されます。
ポーリングでは、最初にOCI_FIRST_PIECE
、後続のコールでOCI_NEXT_PIECE
を渡します。OCI_FIRST_PIECE
はコールバックの使用時に渡される必要があります。
コールバック関数用のコンテキスト・ポインタです。NULL
にできます。
各ピースに対してコールされるように登録できるコールバックです。これがNULL
の場合は、ピースごとにOCI_NEED_DATA
が戻ります。
コールバック関数は、OCI_CONTINUE
を戻して読取りを続行する必要があります。これ以外のエラー・コードが戻った場合、LOBの読取りは終了します。
コールバック関数用のコンテキストです。NULL
にできます。
ピース用のバッファ・ポインタです。
bufp
におけるカレント・ピースのバイト長です。
ピースは、OCI_FIRST_PIECE
、OCI_NEXT_PIECE
またはOCI_LAST_PIECE
です。
コールバック関数は、次に読み取るピースに新規バッファを使用することを選択した場合、新規バッファのアドレスを指定できます。このパラメータがNULL
に設定されている場合、デフォルトの旧バッファbufp
が使用されます。
新規バッファ(指定されている場合)の長さです。
バッファ・データのキャラクタ・セットIDです。この値が0 (ゼロ)の場合は、csfrm
の値に応じて、csid
にクライアントのNLS_LANG
値またはNLS_CHAR
値が設定されます。サーバーとクライアントの設定が同一である場合を除き、サーバーのキャラクタ・セットとはみなされません。
バッファ・データのキャラクタ・セット・フォームです。csfrm
パラメータは、LOBの型と一貫している必要があります。
csfrm
パラメータは、0 (ゼロ)以外の次の2つの値をとることができます。
SQLCS_IMPLICIT
- データベース・キャラクタ・セットID
SQLCS_NCHAR
- NCHARキャラクタ・セットID
デフォルト値はSQLCS_IMPLICIT
です。csfrm
が指定されていない場合は、デフォルトが使用されます。
コメント
LOBまたはBFILE
の一部をコールの指定どおりにバッファに読み取ります。NULL
属性のLOBまたはBFILE
から読み取るとエラーになります。
注意:
LOBの読取りまたは書込みを行うときは、ロケータのフォームと一致するキャラクタ・セット・フォーム(csfrm
)を指定します。
BFILE
の場合は、オペレーティング・システム・ファイルがサーバー上に存在しており、それらのファイルは、入力ロケータを使用してOCILobFileOpen()
またはOCILobOpen()
によってオープンされている必要があります。オペレーティング・システム・ファイルの読取り権限がOracle Databaseにあること、およびディレクトリ・オブジェクトの読取り許可がユーザーにあることが必要です。
OCILobRead2()
に対してポーリング・モードを使用するとき、最初のコールではoffset
およびamtp
の値を指定する必要がありますが、その後のOCILobRead2()
のポーリング・コールではこれらの値を指定する必要はありません。
LOBがBLOB
の場合、csid
パラメータおよびcsfrm
パラメータは無視されます。
注意:
OCILobRead2()
操作を終了して文ハンドルを解放するには、OCIBreak()
コールを使用します。
次の点は、ストリーム・モードでのLOBデータの読取りに適用されます。
ポーリング・モードを使用する場合は、最初のOCILobRead2()
コールでchar_amtp
、byte_amtp
およびoffsetパラメータを指定してください。後続のポーリング・コールでは、これらのパラメータは無視されます。byte_amtp
およびchar_amtp
の両方が0 (ゼロ)を指すように設定されており、OCI_FIRST_PIECE
が渡された場合、ポーリング・モードが想定され、LOBの末尾までデータが読み取られます。出力では、byte_amtp
は、現在のピースに読み取られるバイト数を示します。
CLOB
およびNCLOB
では、char_amtp
は現在のピースに読み取られる文字数を示します。
CLOB
およびNCLOB
では、char_amtp
を渡さないとchar_amtp
はbyte_amtp
/max char width
として内部的に計算されるため、max char width
が4の場合、char_amtp
はbyte_amtp
/4として計算されます。このため、OCILobRead2()
では文字ごとに必要なバイト数を計算しません。かわりに、OCILobRead2()
は、byte_amtp
に格納可能な文字数を最悪の場合にフェッチします。バッファを埋めるには、byte_amtp
パラメータを確認してバッファに格納されている量を確認してから、もう一度OCILobRead2()
をコールして残りのバイトをフェッチします。
コールバックを使用する場合、len
パラメータはコールバックへの入力で、バッファ内で格納されたバイト数を示します。バッファの空き領域を確認するため、コールバック処理中にlen
パラメータをチェックします。
ポーリングを使用する場合、byte_amtp
パラメータを参照し、現在のピースでバッファに格納されている量を確認します。CLOB
およびNCLOB
では、char_amtp
はバッファに読み取られる文字数も戻します。
UTF-16形式でデータを読み取るには、csid
パラメータをOCI_UTF16ID
に設定します。csid
パラメータが設定された場合は、このパラメータによって環境変数NLS_LANG
が上書きされます。
関連項目:
Unicode形式の追加情報は、「OCIでのPL/SQL REF CURSORおよびNESTED TABLE」を参照してください
BFILE
の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください
LOBの読取りおよび書込み方法を示したコード例については、Oracle Databaseインストレーションに含まれているデモ・プログラムを参照してください。
ピース単位のOCI操作の一般情報は、「OCIでのランタイム・データ割当てとピース単位操作」を参照してください
用途
SecureFile内のデータのコンテンツ・タイプ文字列を、アプリケーションで使用できるものに設定します。
構文
sword OCILobSetContentType ( OCIEnv *envhp, OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *lobp, const oratext *contenttypep, ub4 contenttypelen, ub4 mode);
パラメータ
環境ハンドルです。
サービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
一意にLOBを参照するLOBロケータです。
指定のLOBに対して設定されるcontenttype
です。
バイトで示したcontenttype
のサイズです。このサイズはOCI_LOB_CONTENTTYPE_MAXSIZE
バイト以下であることが必要です。
今後の使用のために確保されています。現時点では0 (ゼロ)を渡します。
コメント
この関数はSecureFileでのみ機能します。lobp
がSecureFileでない場合、SECUREFILE_WRONGTYPE
エラーが戻されます。lobp
がバッファリングされた一時LOBまたは抽象LOBである場合、SECUREFILE_BADLOB
エラーが戻されます。
ContentType
文字列の最大可能サイズは次のように定義されています。
#define OCI_LOB_CONTENTTYPE_MAXSIZE 128
ContentType
はASCII (つまり、1バイトまたは7ビットUTF8)です。
SecureFileについて設定された既存のcontenttype
を消去するには、contenttypep
を(oratext *)0
、contenttypelen
を0
に設定したOCILobSetContentType()
をコールします。
用途
SecureFile LOBのオプション設定を有効化します。
構文
sword OCILobSetOptions ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp, ub4 option_types, void *optionsp, ub4 optionslen, ub4 mode );
パラメータ
サービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
一意にLOBを参照するLOBロケータです。このロケータは、svchp
に指定したサーバーから取得されたロケータにしてください。
ビット単位の包含OR (「|」)を使用して、複数のオプション・タイプと値を指定できます。LOB列で有効化されていないoption_types
値を指定すると、エラーになります。
圧縮: OCI_LOB_OPT_COMPRESS
暗号化: OCI_LOB_OPT_ENCRYPT
重複除外: OCI_LOB_OPT_DEDUPLICATE
割当てサイズ: OCI_LOB_OPT_ALLOCSIZE
コンテンツ・タイプ: OCI_LOB_OPT_CONTENTTYPE
変更時間: OCI_LOB_OPT_MODTIME
可能な設定は、次のとおりです。
OCI_LOB_OPT_COMPRESS_OFF
OCI_LOB_OPT_COMPRESS_ON
OCI_LOB_ENCRYPT_OFF
OCI_LOB_ENCRYPT_ON
OCI_LOB_OPT_DEDUPLICATE_OFF
OCI_LOB_OPT_DEDUPLICATE_ON
optionsp
で示した値の長さです。この時点で有効な長さはsizeof(ub4)
のみです。
今後の使用のために確保されています。0 (ゼロ)を渡します。
用途
LOB値を短い長さに切り捨てます。4GBを超えるサイズのLOBには、この関数を使用する必要があります。4GB未満のLOBにもこの関数を使用できます。
構文
sword OCILobTrim2 ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp, oraub8 newlen );
パラメータ
サービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
一意にLOBを参照する内部LOBロケータです。このロケータは、svchp
に指定したサーバーから取得されたロケータにしてください。
現在の長さ以下である必要がある、LOB値の新しい長さです。文字LOBでは文字数であり、バイナリLOBおよびBFILE
ではLOBのバイト数です。
コメント
この関数では、LOBデータを指定の長さに切り捨てます。newlen
が現行のLOBの長さより長い場合は、エラーが戻されます。この関数は内部LOBでのみ有効です。BFILE
には使用できません。
このLOB操作をオープン・コールまたはクローズ・コールで囲む必要はありません。この操作を実行する前にLOBをオープンしていない場合、LOB列のファンクション索引とドメイン索引はこのコール時に更新されます。ただし、この操作を実行する前にLOBをオープンしている場合は、トランザクションをコミットする前に、そのLOBをクローズする必要があります。内部LOBをクローズすると、LOB列のファンクション索引とドメイン索引が更新されます。
LOB操作をオープンAPIまたはクローズAPIで囲んでいない場合、ファンクション索引とドメイン索引は、LOBに書き込むたびに更新されます。これによって、パフォーマンスが低下する可能性があります。ファンクション索引とドメイン索引がある場合は、LOBへの書込み操作をオープン文またはクローズ文内に含めることをお薦めします。
バッファをLOBに書き込みます。4GBを超えるサイズのLOBには、この関数を使用する必要があります。
用途
4GB未満のLOBにもこの関数を使用できます。
構文
sword OCILobWrite2 ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp, oraub8 *byte_amtp, oraub8 *char_amtp, oraub8 offset, void *bufp, oraub8 buflen, ub1 piece, void *ctxp, OCICallbackLobWrite2 (cbfp) ( void *ctxp, void *bufp, oraub8 *lenp, ub1 *piecep void **changed_bufpp, oraub8 *changed_lenp ) ub2 csid, ub1 csfrm );
パラメータ
サービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()
に渡すエラー・ハンドルです。
一意にLOBを参照する内部LOBロケータです。このロケータは、svchp
に指定したサーバーから取得されたロケータにしてください。
IN: データベースに書き込むバイト数です。BLOB
では必ず使用されます。CLOB
およびNCLOB
に対しては、char_amtp
が0 (ゼロ)の場合のみ使用されます。
OUT: データベースに書き込むバイト数です。ポーリング・モードでは、バイト単位のピースの長さ(書込みのみ)です。
IN: データベースに書き込む最大文字数です。BLOB
では無視されます。
OUT: データベースに書き込む文字数です。BLOB
では未定義となります。ポーリング・モードでは、文字単位のピースの長さ(書込みのみ)です。
入力時、これはLOB値の先頭からの絶対オフセットです。文字LOBではLOBの先頭からの文字数であり、バイナリLOBではバイト数です。先頭位置は1です。
ポーリングまたはコールバックによるストリームを使用する場合は、最初のコールでオフセットを指定します。後続のポーリング・コールでは、offsetパラメータは無視されます。コールバックを使用する場合、offsetパラメータはありません。
ピースの書込み元バッファへのポインタです。バッファ内のデータの長さは、buflen
で渡された値であると想定しています。ポーリング・メソッドを使用してピース単位でデータが書き込まれている場合でも、bufp
にはこのコール起動時のLOBの最初のピースを含める必要があります。コールバックを指定した場合は、bufp
を使用してデータを指定しないでください。指定した場合、エラーが発生します。
バッファ内のデータの長さ(バイト数)です。量がchar_amtp
パラメータを使用して文字数で指定され、buflen
パラメータがバイト数で指定されている場合、この値は、CLOB
およびNCLOB
のchar_amtp
値とは異なります。
注意:
このパラメータは8ビット(1バイト)を仮定します。現行のオペレーティング・システムでこれより長いバイトを使用している場合は、buflen
の値を必要に応じて調整する必要があります。
書込み中のバッファのピースです。このパラメータのデフォルト値は、バッファが単独のピースとして書き込まれることを示すOCI_ONE_PIECE
です。
ピース単位またはコールバック・モードで可能な他の値としては、OCI_FIRST_PIECE
、OCI_NEXT_PIECE
およびOCI_LAST_PIECE
があります。
コールバック関数用のコンテキストです。NULL
にできます。
ピース単位書込みで各ピースに対してコールされるように登録できるコールバックです。これがNULL
の場合は、標準ポーリング・メソッドが使用されます。
コールバック関数は、OCI_CONTINUE
を戻して書込みを続行する必要があります。これ以外のエラー・コードが戻った場合、LOBの書込みは終了します。コールバックは、次のパラメータを取ります。
コールバック関数用のコンテキストです。NULL
にできます。
ピース用のバッファ・ポインタです。このパラメータは、OCILobWrite()
ルーチンに入力として渡されるbufp
と同じです。
buffer (IN)内のデータのバイト数、およびbufp
(OUT)内のカレント・ピースのバイト数です。
ピースはOCI_NEXT_PIECE
またはOCI_LAST_PIECE
です。
コールバック関数は、次に読み取るピースに新規バッファを使用することを選択した場合、新規バッファのアドレスを指定できます。このパラメータがNULL
に設定されている場合、デフォルトの旧バッファbufp
が使用されます。
新規バッファ(指定されている場合)の長さです。
バッファ内のデータのキャラクタ・セットIDです。この値が0 (ゼロ)の場合は、csfrm
の値に応じて、csid
にクライアントのNLS_LANG
値またはNLS_CHAR
値が設定されます。
バッファ・データのキャラクタ・セット・フォームです。csfrm
パラメータは、LOBの型と一貫している必要があります。
csfrm
パラメータは、0 (ゼロ)以外の次の2つの値をとることができます。
SQLCS_IMPLICIT
- データベース・キャラクタ・セットID
SQLCS_NCHAR
- NCHARキャラクタ・セットID
デフォルト値はSQLCS_IMPLICIT
です。
コメント
バッファを指定どおりに内部LOBに書き込みます。LOBにデータが存在する場合は、バッファに格納されたデータによって上書きされます。バッファは、このコールによって単独のピースとしてLOBに書き込むことも、コールバックまたは標準ポーリング・メソッドを使用してピース単位で提供することもできます。
注意:
LOBの読取りまたは書込みを行うときは、ロケータのフォームと一致するキャラクタ・セット・フォーム(csfrm
)を指定します。
OCILobWrite2()
に対してポーリング・モードを使用するとき、最初のコールではoffset
、byte_amtp
およびchar_amtp
の値を指定する必要がありますが、その後のOCILobWrite2()
のポーリング・コールではこれらの値を指定する必要はありません。
piece
パラメータの値がOCI_FIRST_PIECE
である場合、データによっては、コールバックまたはポーリングを介して提供される必要があります。
コールバック関数がcbfp
パラメータに定義されている場合は、パイプに1ピースが書き込まれるとこのコールバック関数が呼び出され、次のピースが取得されます。各ピースがbufp
から書き込まれます。コールバック関数が定義されていない場合、OCILobWrite2()
は、OCI_NEED_DATA
エラー・コードを戻します。LOBのピースの書込みを続けるには、アプリケーションでOCILobWrite2()
を再度コールする必要があります。このモードでは、ピースが別々のサイズで複数の場所に読み取られる場合、コールごとにバッファ・ポインタと長さを変えることができます。
piece
パラメータの値がOCI_LAST_PIECE
のときは、ポーリングまたはコールバック方式が使用されているかどうかに関係なく、ピース単位書込み操作は終了します。
(どの入力方法を使用した場合も)データベースに渡されるデータの量が、byte_amtp
またはchar_amtp
パラメータに指定された量より少ない場合は、ORA-22993エラーが戻されます。
この関数は内部LOBでのみ有効です。BFILE
は読取り専用のため、取り扱えません。LOBがBLOB
の場合、csid
パラメータおよびcsfrm
パラメータは無視されます。
byte_amtp
およびchar_amtp
が0 (ゼロ)を指すように設定され、OCI_FIRST_PIECE
が入力として指定されている場合、ポーリング・モードが想定され、OCI_LAST_PIECE
を指定するまでデータが書き込まれます。CLOB
およびNCLOB
では、byte_amtp
およびchar_amtp
は、それぞれバイト数および文字数で、各ピースごとに書き込まれるデータを戻します。BLOB
では、byte_amtp
は各ピースごとに書き込まれるバイト数を戻しますが、出力についてchar_amtp
は未定義です。
UTF-16形式でデータを書き込むには、csid
パラメータをOCI_UTF16ID
に設定します。csid
パラメータが設定された場合は、このパラメータによって環境変数NLS_LANG
が上書きされます。
このLOB操作をオープン・コールまたはクローズ・コールで囲む必要はありません。この操作を実行する前にLOBをオープンしていない場合、LOB列のファンクション索引とドメイン索引はこのコール時に更新されます。ただし、この操作を実行する前にLOBをオープンしている場合は、トランザクションをコミットする前に、そのLOBをクローズする必要があります。内部LOBをクローズすると、LOB列のファンクション索引とドメイン索引が更新されます。
LOB操作をオープンAPIまたはクローズAPIで囲んでいない場合、ファンクション索引とドメイン索引は、LOBに書き込むたびに更新されます。これによって、パフォーマンスが低下する可能性があります。ファンクション索引とドメイン索引がある場合は、LOBへの書込み操作をオープン文またはクローズ文内に含めることをお薦めします。
関連項目:
Unicode形式の追加情報は、「OCIでのPL/SQL REF CURSORおよびNESTED TABLE」を参照してください
LOBの読取りおよび書込み方法を示したコード例については、Oracle Databaseインストレーションに含まれているデモ・プログラムを参照してください。
ピース単位のOCI操作の一般情報は、「OCIでのランタイム・データ割当てとピース単位操作」を参照してください
LOBの末尾からデータの書込みを開始します。4GBを超えるサイズのLOBには、この関数を使用する必要があります。
用途
4GB未満のLOBにもこの関数を使用できます。
構文
sword OCILobWriteAppend2 ( OCISvcCtx *svchp, OCIError *errhp, OCILobLocator *locp, oraub8 *byte_amtp, oraub8 *char_amtp, void *bufp, oraub8 buflen, ub1 piece, void *ctxp, OCICallbackLobWrite2 (cbfp) ( void *ctxp, void *bufp, oraub8 *lenp, ub1 *piecep void **changed_bufpp, oraub8 *changed_lenp ) ub2 csid, ub1 csfrm);
パラメータ
サービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()
に渡すエラー・ハンドルです。
一意にLOBを参照する内部LOBロケータです。
IN: データベースに書き込むバイト数です。BLOB
で使用されます。CLOB
およびNCLOB
に対しては、char_amtp
が0 (ゼロ)の場合のみ使用されます。
OUT: データベースに書き込むバイト数です。
IN: データベースに書き込む最大文字数です。BLOB
では無視されます。
OUT: データベースに書き込む文字数です。BLOB
では未定義となります。
ピースの書込み元バッファへのポインタです。バッファ内のデータの長さは、buflen
で渡された値であると想定しています。ピース単位でデータが書き込まれている場合でも、bufp
にはこのコール起動時のLOBの最初のピースを含める必要があります。コールバックを指定した場合は、bufp
を使用してデータを指定しないでください。指定した場合、エラーが発生します。
バッファ内のデータの長さ(バイト数)です。このパラメータは8ビット(1バイト)を仮定します。現行のオペレーティング・システムでこれより長いバイトを使用している場合は、buflen
の値を必要に応じて調整する必要があります。
書込み中のバッファのピースです。このパラメータのデフォルト値は、バッファが単独のピースとして書き込まれることを示すOCI_ONE_PIECE
です。ピース単位またはコールバック・モードで可能な他の値としては、OCI_FIRST_PIECE
、OCI_NEXT_PIECE
およびOCI_LAST_PIECE
があります。
コールバック関数用のコンテキストです。NULL
にできます。
ピース単位書込みで各ピースに対してコールされるように登録できるコールバックです。これがNULL
の場合は、標準ポーリング・メソッドが使用されます。コールバック関数は、OCI_CONTINUE
を戻して書込みを続行する必要があります。これ以外のエラー・コードが戻った場合、LOBの書込みは終了します。コールバックは、次のパラメータを取ります。
コールバック関数用のコンテキストです。NULL
にできます。
ピース用のバッファ・ポインタです。
buffer (IN)内のデータのバイト数、およびbufp
(OUT)内のカレント・ピースのバイト数です。
ピースはOCI_NEXT_PIECE
またはOCI_LAST_PIECE
です。
コールバック関数は、次に書き込むピースに新規バッファを使用することを選択した場合、新規バッファのアドレスを指定できます。このパラメータがNULL
に設定されている場合、デフォルトの旧バッファbufp
が使用されます。
新規バッファ(指定されている場合)の長さです。
バッファ・データのキャラクタ・セットIDです。
バッファ・データのキャラクタ・セット・フォームです。
csfrm
パラメータは、0 (ゼロ)以外の次の2つの値をとることができます。
SQLCS_IMPLICIT
- データベース・キャラクタ・セットID
SQLCS_NCHAR
- NCHARキャラクタ・セットID
デフォルト値はSQLCS_IMPLICIT
です。
コメント
バッファは、このコールによって単独のピースとしてLOBに書き込むことも、コールバックまたは標準ポーリング・メソッドを使用してピース単位で提供することもできます。pieceパラメータの値がOCI_FIRST_PIECE
である場合、データによっては、コールバックまたはポーリングを介して提供される必要があります。コールバック関数がcbfp
パラメータに定義されている場合は、パイプに1ピースが書き込まれるとこのコールバック関数が呼び出され、次のピースが取得されます。各ピースがbufp
から書き込まれます。コールバック関数が定義されていない場合、OCILobWriteAppend2()
は、OCI_NEED_DATA
エラー・コードを戻します。
LOBのピースの書込みを続けるには、アプリケーションでOCILobWriteAppend2()
を再度コールする必要があります。このモードでは、ピースが別々のサイズで複数の場所に読み取られる場合、コールごとにバッファ・ポインタと長さを変えることができます。pieceパラメータの値がOCI_LAST_PIECE
のときは、ピース単位の書込みは終了します。
LOBバッファリングが有効な場合、OCILobWriteAppend2()
関数はサポートされません。
LOBがBLOB
の場合、csid
パラメータおよびcsfrm
パラメータは無視されます。
byte_amtp
およびchar_amtp
が0 (ゼロ)を指すように設定され、OCI_FIRST_PIECE
が入力として指定されている場合、ポーリング・モードが想定され、OCI_LAST_PIECE
を指定するまでデータが書き込まれます。CLOB
およびNCLOB
では、byte_amtp
およびchar_amtp
は、それぞれバイト数および文字数で、各ピースごとに書き込まれるデータを戻します。BLOB
では、byte_amtp
は各ピースごとに書き込まれるバイト数を戻しますが、出力についてchar_amtp
は未定義です。
このLOB操作をオープン・コールまたはクローズ・コールで囲む必要はありません。この操作を実行する前にLOBをオープンしていない場合、LOB列のファンクション索引とドメイン索引はこのコール時に更新されます。ただし、この操作を実行する前にLOBをオープンしている場合は、トランザクションをコミットする前に、そのLOBをクローズする必要があります。内部LOBをクローズすると、LOB列のファンクション索引とドメイン索引が更新されます。
LOB操作をオープンAPIまたはクローズAPIで囲んでいない場合、ファンクション索引とドメイン索引は、LOBに書き込むたびに更新されます。これによって、パフォーマンスが低下する可能性があります。ファンクション索引とドメイン索引がある場合は、LOBへの書込み操作をオープン文またはクローズ文内に含めることをお薦めします。