| Oracle® Call Interfaceプログラマーズ・ガイド 11g リリース2 (11.2) E50264-03 |
|
 前 |
 次 |
表17-2は、この項で説明している、LOBロケータを使用するLOB関数を示しています。すべての新規アプリケーションには、「2」で終わる関数を使用します。
|
注意: LOBへのアクセスには、LOB用のデータ・インタフェースを使用するというもう1つの方法があります。次の場所で説明するように、CLOB列の文字データまたはBLOB列のRAWデータをバインドまたは定義できます。
|
表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の読取りまたは書込みを行うことです。ストリームは、ポーリング・メカニズムを使用するか、またはユーザー定義コールバックを登録して実装できます。
構文
sword OCIDurationBegin ( OCIEnv *env,
OCIError *err,
const OCISvcCtx *svc,
OCIDuration parent,
OCIDuration *duration );
パラメータ
NULLポインタを渡します。
OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。
OCIサービス・コンテキスト・ハンドルです。NULL以外にしてください。
親の継続時間の時間番号です。次のいずれかです。
新しく作成されたユーザー期間固有の識別子です。
パラメータ
NULLポインタを渡します。
OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。
OCIサービス・コンテキストです。これは、カートリッジ・サービスに対してNULLとして渡されます。
ユーザー期間を識別するための番号です。
構文
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()
構文
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が上書きされます。
|
関連項目:
|
構文
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)を指定します。
|
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への書込み操作をオープン文またはクローズ文内に含めることをお薦めします。
|
関連項目:
|
構文
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()は一時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;
例17-1は、アプリケーションによるsource_locロケータの割当て方法を示しています。
例17-1 source_locソース・ロケータの割当て
if (OCIDescriptorAlloc((void *) envhp, (void **) &source_loc,
(ub4) OCI_DTYPE_LOB, (size_t) 0, (void **) 0))
handle_error;
次に、表のLOBがsource_locに選択され、初期化されます。例17-2に示すように、アプリケーションでは、OCILobAssign()コールを発行してsource_locの値をdest_locに割り当てる前に、宛先ロケータdest_locを割り当てる必要があります。
構文
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つの値をとることができます。
パラメータ
OCI環境ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
キャラクタ・セットIDを取得するためのLOBロケータです。
入力LOBロケータのデータベース・キャラクタ・セットIDです。入力ロケータがBLOBまたはBFILE用の場合、バイナリLOBまたはバイナリ・ファイルにはキャラクタ・セットという概念がないため、csidには0 (ゼロ)が設定されます。コール元は、csid ub2用の領域を割り当てる必要があります。
パラメータ
サービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
クローズするLOBです。ロケータは、内部LOBまたは外部LOBを参照できます。
コメント
オープンしている内部または外部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への書込み操作をオープン文またはクローズ文内に含めることをお薦めします。
構文
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への書込み操作をオープン文またはクローズ文内に含めることをお薦めします。
構文
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です。
作成するLOBの型です。次の値が有効です。
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パラメータは無視されます。
パラメータ
サービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
一意にLOBを参照する内部LOBロケータです。
コメント
入力内部LOBロケータのLOBバッファリングを使用禁止にします。次回入力ロケータを通してLOBに対してデータの読取りまたは書込みを行うときは、LOBバッファリング・サブシステムは使用されません。このコールでは、バッファリング・サブシステムでの変更は暗黙的にはフラッシュされません。ユーザーは、OCILobFlushBuffer()をコールして変更を明示的にフラッシュする必要があります。
この関数は、BFILEロケータを受け入れません。
パラメータ
サービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
一意にLOBを参照する内部LOBロケータです。
コメント
入力内部LOBロケータのLOBバッファリングを使用可能にします。次回入力ロケータを通してLOBに対してデータの読取りまたは書込みを行うときは、LOBバッファリング・サブシステムが使用されます。
ロケータのLOBバッファリングが使用可能な状態で、そのロケータがルーチンOCILobAppend()、OCILobCopy() (非推奨)、OCILobCopy2()、OCILobErase() (非推奨)、OCILobErase2()、OCILobGetLength() (非推奨)、OCILobGetLength2()、OCILobLoadFromFile() (非推奨)、OCILobLoadFromFile2()、OCILobTrim() (非推奨)、OCILobTrim2()、OCILobWriteAppend() (非推奨)またはOCILobWriteAppend2()のいずれかに渡されると、エラーが戻ります。
この関数は、BFILEロケータを受け入れません。
構文
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への書込み操作をオープン文またはクローズ文内に含めることをお薦めします。
パラメータ
サービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
クローズするBFILEを参照するBFILEロケータへのポインタです。
構文
sword OCILobFileExists ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *filep,
boolean *flag );
パラメータ
OCIサービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
ファイルを参照するBFILEロケータへのポインタです。
サーバーにBFILEが存在する場合はTRUEを、存在しない場合はFALSEを戻します。
構文
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文字列の長さ
構文
sword OCILobFileIsOpen ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *filep,
boolean *flag );
パラメータ
OCIサービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
確認するBFILEロケータへのポインタです。
この特定のロケータを使用してBFILEがオープンされた場合はTRUEを、オープンされなかった場合はFALSEを戻します。
コメント
サーバー上のファイルがfilep BFILEロケータを使用してオープンされたかどうかをチェックします。内部LOBに対してこの関数をコールするとエラーになります。
OCILobFileOpen()またはOCILobOpen()コマンドに入力BFILEロケータが渡されなかった場合、ファイルはそのロケータによってオープンされていないとみなされます。ただし、別のロケータがそのファイルをオープンしていることがあります。オープンは、特定のロケータに対応付けられます。
|
関連項目: BFILEの詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。 |
パラメータ
サービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
オープンするBFILEです。ロケータがBFILEを参照していない場合はエラーが発生します。
ファイルをオープンするモードです。有効なモードはOCI_FILE_READONLYのみです。
構文
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パラメータの長さ(バイト単位)です。
パラメータ
サービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
LOBを一意に参照する内部ロケータです。
このフラグをOCI_LOB_BUFFER_FREEに設定すると、LOBのバッファ・リソースは、フラッシュの後に解放されます。「コメント」の項を参照してください。
コメント
入力ロケータによって参照されるLOBに関連するバッファリング・サブシステムに加えられた変更を、サーバーにフラッシュします。このルーチンでは、バッファのデータをデータベースのLOBに実際に書き込みます。LOBバッファリングは入力LOBロケータに対して使用可能にしてください。
このフラッシュ操作のデフォルトでは、別のバッファLOB操作への再割当て用にバッファ・リソースは解放されません。バッファを明示的に解放する場合は、flagパラメータをOCI_LOB_BUFFER_FREEに設定できます。
クライアント・アプリケーションでフラッシュ後のバッファ値を読み取る予定で、あらかじめバッファの現在値が望む値であることがわかっている場合、サーバーからデータを再度読み取る必要はありません。
バッファの解放による影響はユーザーにはほとんど認識されません。ただし、LOB内の同じ範囲に次にアクセスするときに、サーバーをラウンドトリップすることになり、バッファ・リソースの取得およびLOBから読み取られるデータによるバッファの初期化のための追加コストがかかります。このオプションは、オンボード・メモリーが少ないクライアント環境用です。
パラメータ
OCIサービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
解放するLOBを一意に参照するロケータです。
コメント
このロケータが指し示す一時LOBの内容を解放します。ロケータ自体は、OCIDescriptorFree() がコールされるまで解放されません。
locpパラメータで渡される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コールを十分な数だけまとめることができます。
構文
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)です。
パラメータ
サービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
一意にLOBを参照するLOBロケータです。内部LOBでは、このロケータは、svchpに指定したサーバーから取得されたロケータにしてください。BFILEの場合は、OCILobFileSetName()、SELECT文またはOCIObjectPin()を使用してロケータを設定できます。
出力時、LOBがNULLではない場合、LOBの長さを示します。文字LOBでは文字数であり、バイナリLOBおよびBFILEでは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 (ゼロ)を渡します。
構文
sword OCILobGetStorageLimit ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
oraub8 *limitp );
パラメータ
サービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
一意にLOBを参照するLOBロケータです。このロケータは、svchpに指定したサーバーから取得されたロケータにしてください。
データベースに格納できるLOBの最大長(バイト単位)です。
構文
sword OCILobIsEqual ( OCIEnv *envhp,
const OCILobLocator *x,
const OCILobLocator *y,
boolean *is_equal );
パラメータ
OCI環境ハンドルです。
比較するLOBロケータです。
比較するLOBロケータです。
LOBロケータが等価の場合はTRUE、等価でない場合はFALSEです。
パラメータ
サービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
確認するLOBロケータへのポインタです。ロケータは、内部LOBまたは外部LOBを参照できます。
内部LOBがオープンされている場合、または入力ロケータを使用してBFILEがオープンされた場合は、TRUEを戻します。それ以外はFALSEを戻します。
コメント
内部LOBがオープンされているかどうか、またはBFILEが入力ロケータを使用してオープンされているかどうかをチェックします。
入力BFILEロケータがOCILobOpen()またはOCILobFileOpen()に渡されていない場合は、BFILEロケータによるBFILEのオープンは行わないとみなされます。ただし、別のBFILEロケータによってBFILEがオープンされている場合はあります。別のロケータを使用して、そのBFILEに対して複数のオープンが実行されることがあります。つまり、オープンはBFILEの特定のロケータに関連付けられています。
オープンは、ロケータではなくLOBに関連付けられます。locator1がLOBをオープンした場合は、locator2もオープン時にそのLOBを参照します。
内部LOBの場合、このコールでは、サーバー上の状態によって、LOBがオープンしているかどうかを確認するため、サーバー・ラウンドトリップが必要です。外部LOB (BFILE)の場合も、サーバー側のオペレーティング・システム・ファイルによってそのLOBがオープンされているかどうかを確認するため、ラウンドトリップが必要です。
構文
sword OCILobIsTemporary(OCIEnv *envhp,
OCIError *errhp,
OCILobLocator *locp,
boolean *is_temporary);
パラメータ
OCI環境ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
確認するロケータです。
ロケータが一時LOBを指し示している場合はTRUEを、そうでない場合はFALSEを戻します。
構文
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への書込み操作をオープン文またはクローズ文内に含めることをお薦めします。
構文
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ロケータを参照するようにします。
構文
sword OCILobLocatorIsInit ( OCIEnv *envhp,
OCIError *errhp,
const OCILobLocator *locp,
boolean *is_initialized );
パラメータ
OCI環境ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
確認するLOBまたはBFILEロケータです。
特定のLOBまたはBFILEロケータが初期化されているとTRUE、初期化されていないとFALSEを戻します。
コメント
指定されたLOBまたはBFILEロケータが初期化されているかどうかをテストします。
内部LOBロケータは、次のいずれかの方法で初期化できます。
NULL以外のLOBをロケータに選択します。
OCIObjectPin()を使用して、LOB属性がNULL以外のオブジェクトを確保します。
OCIAttrSet()を使用して、ロケータをEmpty値に設定します。
BFILEロケータは、次のいずれかの方法で初期化できます。
NULL以外のBFILEをロケータに選択します。
OCIObjectPin()を使用して、BFILE属性がNULL以外のオブジェクトを確保します。
OCILobFileSetName()をコールします。
パラメータ
サービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のために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への書込み操作をオープン文またはクローズ文内に含めることをお薦めします。
構文
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です。csfrmが指定されていない場合は、デフォルトが使用されます。
コメント
LOBまたはBFILEの一部をコールの指定どおりにバッファに読み取ります。NULL属性のLOBまたはBFILEから読み取るとエラーになります。
|
注意: LOBの読取りまたは書込みを行うときは、ロケータのフォームと一致するキャラクタ・セット・フォーム(csfrm)を指定します。 |
BFILEの場合は、オペレーティング・システム・ファイルがサーバー上に存在しており、それらのファイルは、入力ロケータを使用してOCILobFileOpen()またはOCILobOpen()によってオープンされている必要があります。オペレーティング・システム・ファイルの読取り権限がOracle Databaseにあること、およびディレクトリ・オブジェクトの読取り許可がユーザーにあることが必要です。
OCILobRead2()に対してポーリング・モードを使用するとき、最初のコールではoffsetおよびamtpの値を指定する必要がありますが、その後のOCILobRead2()のポーリング・コールではこれらの値を指定する必要はありません。
LOBがBLOBの場合、csidパラメータおよびcsfrmパラメータは無視されます。
次の点は、ストリーム・モードでのLOBデータの読取りに適用されます。
ポーリング・モードを使用する場合は、最初のOCILobRead2()コールでchar_amtp、byte_amtpおよびoffsetパラメータを指定してください。後続のポーリング・コールでは、これらのパラメータは無視されます。byte_amtpおよびchar_amtpの両方が0 (ゼロ)を指すように設定されており、OCI_FIRST_PIECEが渡された場合、ポーリング・モードが想定され、LOBの末尾までデータが読み取られます。出力では、byte_amtpは、現在のピースに読み取られるバイト数を示します。CLOBおよびNCLOBでは、char_amtpは現在のピースに読み取られる文字数を示します。
コールバックを使用する場合、lenパラメータはコールバックへの入力で、バッファ内で格納されたバイト数を示します。バッファの空き領域を確認するため、コールバック処理中にlenパラメータをチェックします。
ポーリングを使用する場合、byte_amtpパラメータを参照し、現在のピースでバッファに格納されている量を確認します。CLOBおよびNCLOBでは、char_amtpはバッファに読み取られる文字数も戻します。
UTF-16形式でデータを読み取るには、csidパラメータをOCI_UTF16IDに設定します。csidパラメータが設定された場合は、このパラメータによって環境変数NLS_LANGが上書きされます。
|
関連項目:
|
構文
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()をコールします。
構文
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_DEDUPLICATE
可能な設定は、次のとおりです。
OCI_LOB_OPT_COMPRESS_OFF
OCI_LOB_OPT_COMPRESS_ON
OCI_LOB_OPT_DEDUPLICATE_OFF
OCI_LOB_OPT_DEDUPLICATE_ON
optionspで示した値の長さです。この時点で有効な長さはsizeof(ub4)のみです。
今後の使用のために確保されています。0 (ゼロ)を渡します。
パラメータ
サービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のために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への書込み操作をオープン文またはクローズ文内に含めることをお薦めします。
構文
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です。
コメント
バッファを指定どおりに内部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への書込み操作をオープン文またはクローズ文内に含めることをお薦めします。
|
関連項目:
|
構文
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です。
コメント
バッファは、このコールによって単独のピースとして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への書込み操作をオープン文またはクローズ文内に含めることをお薦めします。
