| Oracle Call Interfaceプログラマーズ・ガイド 11g リリース1（11.1） E05677-02 |
|
 戻る |
 次へ |
この項では、LOBロケータを使用するLOB関数について説明します。すべての新規アプリケーションには、「2」で終わる関数を使用します。
|
注意: LOBへのアクセスには、LOB用のデータ・インタフェースを使用するというもう1つの方法があります。次の各項で説明するように、 CLOB列の文字データまたはBLOB列のRAWデータをバインドまたは定義できます。 |
|
関連項目:
|
表17-3 LOB関数
| 関数 | 用途 |
|---|---|
|
|
一時LOBのためのユーザー期間を開始します。 |
|
|
一時LOBのためのユーザー期間を終了します。 |
|
|
1つのLOBを別のLOBの後に追加します。 |
|
|
複数のロケータのLOBデータを読み取ります。 |
|
|
複数のロケータのLOBデータを書き込みます。 |
|
|
1つのLOBロケータを別のLOBロケータに割り当てます。 |
|
|
LOBロケータからキャラクタ・セットを取得します。 |
|
|
LOBロケータからキャラクタ・セットIDを取得します。 |
|
|
オープンされているLOBをクローズします。 |
|
|
LOBの一部または全部を別のLOBにコピーします。 |
|
|
LOBの一部または全部を別のLOBにコピーします。 |
|
|
一時LOBを作成します。 |
|
|
LOBバッファリングをオフにします。 |
|
|
LOBバッファリングをオンにします。 |
|
|
LOBの一部を消去します。 |
|
|
LOBの一部を消去します。 |
|
|
オープンされている |
|
|
オープンされているすべてのFILEをクローズします。 |
|
|
サーバー上のファイルの存在をチェックします。 |
|
|
LOBロケータからディレクトリ・オブジェクトとファイル名を取得します。 |
|
|
サーバー上のファイルがこのロケータでオープンされているかどうかをチェックします。 |
|
|
|
|
|
LOBロケータにディレクトリ・オブジェクトとファイル名を設定します。 |
|
|
LOBバッファをフラッシュします。 |
|
|
一時LOBを解放します。 |
|
|
LOBのチャンク・サイズを取得します。 |
|
|
LOBの長さを取得します。 |
|
|
LOBの長さを取得します。 |
|
|
SecureFileのオプション設定を取得します。 |
|
|
内部LOB（BLOB、CLOBまたはNCLOB）の最大長（バイト単位）を取得します。 |
|
|
2つのLOBロケータが等しいか比較します。 |
|
|
LOBがオープンされているかどうかをチェックします。 |
|
|
特定のLOBが一時LOBかどうかを判断します。 |
|
|
|
|
|
1つのLOBロケータを別のLOBロケータに割り当てます。 |
|
|
LOBロケータが初期化されているかどうかをチェックします。 |
|
|
LOBをオープンします。 |
|
|
LOBの一部を読み取ります。 |
|
|
LOBの一部を読み取ります。 |
|
|
既存のSecureFileと新規に作成されたSecureFileのオプション設定を有効化します。 |
|
|
LOBを切り捨てます。 |
|
|
LOBを切り捨てます。 |
|
|
LOBに書き込みます。 |
|
|
LOBに書き込みます。 |
|
|
LOBの末尾からデータを書き込みます。 |
|
|
LOBの末尾からデータを書き込みます。 |
OCI LOBコールのパラメータについて、次の点に注意してください。
固定幅のクライアント側キャラクタ・セットの場合、offsetパラメータとamountパラメータは、CLOBとNCLOBでは常に文字数、BLOBとBFILEでは常にバイト数です。
可変幅のクライアント側キャラクタ・セットの場合は、一般に次のルールが適用されます。
amount（amtp）パラメータ− amountパラメータがサーバー側のLOBを参照する場合、その内容は文字数です。amountパラメータがクライアント側のバッファを参照する場合、amountはバイト数です。
詳細は、OCILobGetLength()、OCILobRead()およびOCILobWrite()などの各LOBコールを参照してください。
offset（offset）パラメータ: クライアント側のキャラクタ・セットが可変幅かどうかに関係なく、offsetパラメータは、CLOBとNCLOBでは常に文字数、BLOBとBFILEでは常にバイト数です。
LOB操作では、多くの場合、クライアント側のキャラクタ・セットに関係なく、amountパラメータはCLOBとNCLOBの文字数です。これらのLOB操作にはOCILobCopy()、OCILobErase()、OCILobGetLength()、OCILobLoadFromFile()およびOCILobTrim()などがあります。これらのすべての操作では、サーバー上のLOBデータの量を参照します。
ストリーム操作は、ピース単位でのLOBの書込みや読取りを意味します。ストリームは、ポーリング・メカニズムを使用するか、またはユーザー定義コールバックを登録して実装できます。
用途
一時LOBのためのユーザー期間を開始します。
構文
sword OCIDurationBegin ( OCIEnv *env,
OCIError *err,
const OCISvcCtx *svc,
OCIDuration parent,
OCIDuration *duration );
パラメータ
NULLポインタを渡します。
OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。
OCIサービス・コンテキスト・ハンドルです。NULL以外にしてください。
親の継続時間の時間番号です。次のいずれかになります。
新しく作成されたユーザー期間固有の識別子です。
コメント
この関数によってユーザー期間が開始されます。リリース8.1以上では、一時LOBを作成する際にユーザー期間を使用できます。ユーザーは複数のアクティブなユーザー期間を同時に利用できます。ユーザー期間をネストする必要はありません。durパラメータは、このコールによって作成された継続時間を識別するための一意の番号を戻すのに使用します。
関連関数
用途
一時LOBのためのユーザー期間を終了します。
構文
sword OCIDurationEnd ( OCIEnv *env,
OCIError *err,
const OCISvcCtx *svc,
OCIDuration duration );
パラメータ
NULLポインタを渡します。
OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。
OCIサービス・コンテキストです。これは、カートリッジ・サービスに対してNULLとして渡されます。
ユーザー期間を識別するための番号です。
コメント
この関数によってユーザー期間が終了します。ユーザー期間に割り当てられていた一時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()、OCILobWrite()、OCILobCopy()、OCIErrorGet()、OCILobWriteAppend()
用途
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()によってオープンされている必要があります。オペレーティング・システム・ファイルの読取り権限がデータベースにあること、およびディレクトリ・オブジェクトの読取り許可がユーザーにあることが必要です。
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が上書きされます。
|
関連項目:
|
関連関数
OCIErrorGet()、OCILobWrite2()、OCILobFileSetName()、OCILobWriteAppend2()、OCILobArrayWrite()
用途
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つの値をとることができます。
コメント
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への書込み操作をオープン文またはクローズ文内に含めることをお薦めします。
|
関連項目:
|
関連関数
OCIErrorGet()、OCILobRead2()、OCILobAppend()、OCILobCopy()、OCILobWriteAppend2()、OCILobArrayRead()
用途
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()は一時LOBには使用できません。OCI_INVALID_HANDLEエラーが生成されます。一時LOBには、OCILobLocatorAssign()を使用します。
BFILEでは、ファイルを参照するロケータのみが表にコピーされます。オペレーティング・システム・ファイル自体はコピーされません。
BFILEロケータを内部LOBロケータに割り当てたり、LOBロケータをBFILEロケータに割り当てたりするとエラーになります。
ソース・ロケータがバッファリング可能な内部LOB用でLOBバッファリング・サブシステムを介したLOBデータの変更に使用されており、そのバッファが書込み後フラッシュされていない場合には、ソース・ロケータが宛先ロケータに割り当てられない場合があります。これは、LOBごとに1つのロケータしかLOBバッファリング・サブシステムを介してLOBデータを変更できないためです。
入力宛先ロケータの値は、OCIDescriptorAlloc()コールによってあらかじめ割り当てられている必要があります。たとえば、次のように宣言します。
OCILobLocator *source_loc = (OCILobLocator *) 0; OCILobLocator *dest_loc = (OCILobLocator *) 0;
アプリケーションでは、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を割り当てる必要があります。たとえば、次のようにします。
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;
関連関数
OCIErrorGet()、OCILobIsEqual()、OCILobLocatorAssign()、OCILobLocatorIsInit()、OCILobEnableBuffering()
用途
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出力パラメータに戻します。
関連関数
OCIErrorGet()、OCILobCharSetId()、OCILobLocatorIsInit()
用途
LOBロケータのデータベース・キャラクタ・セットIDを取得します。
構文
sword OCILobCharSetId ( OCIEnv *envhp,
OCIError *errhp,
const OCILobLocator *locp,
ub2 *csid );
パラメータ
OCI環境ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
キャラクタ・セットIDを取得するためのLOBロケータです。
入力LOBロケータのデータベース・キャラクタ・セットIDです。入力ロケータがBLOBまたはBFILE用の場合、バイナリのLOB/FILEにはキャラクタ・セットという概念がないため、csidには0（ゼロ）が設定されます。コール元は、csid ub2用の領域を割り当てる必要があります。
コメント
入力CLOBまたはNCLOBロケータのキャラクタ・セットIDをcsid出力パラメータに戻します。
関連関数
OCIErrorGet()、OCILobCharSetForm()、OCILobLocatorIsInit()
用途
オープンしているLOBまたはBFILEをクローズします。
構文
sword OCILobClose ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp );
パラメータ
サービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
クローズするLOBです。ロケータは、内部LOBまたは外部LOBを参照できます。
コメント
オープンしている内部または外部LOBをクローズします。BFILEは存在しているが、オープンしていない場合、エラーは戻りません。内部LOBがオープンしていない場合は、エラーが戻されます。
LOBをクローズするときは、内部LOBおよび外部LOBからサーバーへのラウンドトリップが必要です。内部LOBの場合は、LOBをクローズすると、クローズ・コールに依存している他のコードが実行されます。外部LOB（BFILE）の場合は、LOBをクローズすると、サーバー側のオペレーティング・システム・ファイルが実際にクローズされます。
すべてのLOB操作をオープン・コールまたはクローズ・コールで囲む必要はありません。ただし、LOBをオープンしている場合は、トランザクションをコミットまたはロールバックする前に、そのLOBをクローズする必要があります。内部LOBをクローズすると、LOB列のファンクション索引とドメイン索引が更新されます。トランザクションによってオープンされたすべてのLOBをクローズする前にトランザクションをコミットすると、エラーが発生します。
このエラーが戻されると、LOBはオープンとしてマークされなくなりますが、トランザクションは正常にコミットされます。したがって、トランザクションでLOBデータとLOB以外のデータに対して行われた変更はすべてコミットされます。ただし、ドメイン索引とファンクション索引は更新されません。このエラーが戻された場合は、LOB列のファンクション索引とドメイン索引を再作成してください。
LOB操作をオープンAPIまたはクローズAPIで囲んでいない場合、ファンクション索引とドメイン索引は、LOBに書き込むたびに更新されます。これによって、パフォーマンスが低下する可能性があるため、ファンクション索引とドメイン索引がある場合は、LOBへの書込み操作をオープン/クローズ文内に含めることをお薦めします。
関連関数
OCIErrorGet()、OCILobOpen()、OCILobIsOpen()
用途
LOB値の全体または一部を別のLOB値にコピーします。
構文
sword OCILobCopy ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *dst_locp,
OCILobLocator *src_locp,
ub4 amount,
ub4 dst_offset,
ub4 src_offset );
パラメータ
サービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
一意に宛先LOBを参照する内部LOBロケータです。このロケータは、svchpに指定したサーバーから取得されたロケータにしてください。
一意にソースLOBを参照する内部LOBロケータです。このロケータは、svchpに指定したサーバーから取得されたロケータにしてください。
ソースLOBから宛先LOBにコピーされる文字数（CLOBまたはNCLOB）またはバイト数（BLOB）です。
これは、宛先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ロケータは同じ型にしてください（つまり、両方ともBLOBまたは両方ともCLOB）。LOBバッファリングは、ロケータのどちらに対しても使用可能にしないでください。
この関数では、ソースまたは宛先としてのBFILEロケータを受け入れません。
このLOB操作をオープン・コールまたはクローズ・コールで囲む必要はありません。この操作を実行する前にLOBをオープンしていない場合、LOB列のファンクション索引とドメイン索引はこのコール時に更新されます。この操作を実行する前にLOBをオープンしている場合は、トランザクションをコミットまたはロールバックする前に、そのLOBをクローズする必要があります。内部LOBをクローズすると、LOB列のファンクション索引とドメイン索引が更新されます。
LOB操作をオープンAPIまたはクローズAPIで囲んでいない場合、ファンクション索引とドメイン索引は、LOBに書き込むたびに更新されます。これによって、パフォーマンスが低下する可能性があります。ファンクション索引とドメイン索引がある場合は、LOBへの書込み操作をオープン文またはクローズ文内に含めることをお薦めします。
|
注意: ソースLOBの長さを判断するには、 OCILobGetLength()をコールします。 |
関連関数
OCIErrorGet()、OCILobRead()、OCILobAppend()、OCILobCopy2()、OCILobWrite()、OCILobWriteAppend()
用途
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 );
パラメータ
用途
一時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キャラクタ・セット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パラメータは無視されます。
関連関数
OCILobFreeTemporary()、OCILobIsTemporary()、OCIDescriptorAlloc()、OCIErrorGet()
用途
入力ロケータのLOBバッファリングを使用禁止にします。
構文
sword OCILobDisableBuffering ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp );
パラメータ
サービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
一意にLOBを参照する内部LOBロケータです。
コメント
入力内部LOBロケータのLOBバッファリングを使用禁止にします。次回入力ロケータを通してLOBに対してデータの読取りまたは書込みを行うときは、LOBバッファリング・サブシステムは使用されません。このコールでは、バッファリング・サブシステムで行われた変更は暗黙的にフラッシュされません。ユーザーは、OCILobFlushBuffer()をコールして変更を明示的にフラッシュする必要があります。
この関数は、BFILEロケータを受け入れません。
関連関数
OCILobEnableBuffering()、OCIErrorGet()、OCILobFlushBuffer()
用途
入力ロケータのLOBバッファリングを使用可能にします。
構文
sword OCILobEnableBuffering ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp );
パラメータ
サービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
一意にLOBを参照する内部LOBロケータです。
コメント
入力内部LOBロケータのLOBバッファリングを使用可能にします。次回入力ロケータを通してLOBに対してデータの読取りまたは書込みを行うときは、LOBバッファリング・サブシステムが使用されます。
ロケータのLOBバッファリングが使用可能な状態で、そのロケータがルーチンOCILobAppend()、OCILobCopy()、OCILobErase()、OCILobGetLength()、OCILobLoadFromFile()、OCILobTrim()またはOCILobWriteAppend()のいずれかに渡されると、エラーが戻ります。
この関数は、BFILEロケータを受け入れません。
関連関数
OCILobDisableBuffering()、OCIErrorGet()、OCILobWrite()、OCILobRead()、OCILobFlushBuffer()、OCILobWriteAppend()
用途
内部LOBデータの一部を指定のオフセットの位置から消去します。
構文
sword OCILobErase ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
ub4 *amount,
ub4 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()、OCILobErase2()、OCILobRead()、OCILobAppend()、OCILobCopy()、OCILobWrite()、OCILobWriteAppend()
用途
内部LOBデータの一部を指定のオフセットの位置から消去します。4GBを超えるサイズのLOBには、この関数を使用する必要があります。4GB未満のLOBにもこの関数を使用できます。
構文
sword OCILobErase2 ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
oraub8 *amount,
oraub8 offset );
パラメータ
用途
オープンしているBFILEをクローズします。
構文
sword OCILobFileClose ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *filep );
パラメータ
サービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
クローズするBFILEを参照するBFILEロケータへのポインタです。
コメント
オープンしているBFILEをクローズします。内部LOBに対してこの関数をコールするとエラーになります。BFILEは存在しているが、オープンしていない場合、エラーは戻りません。
この関数は、特定のBFILEロケータに対して初めてコールしたときにかぎり有効です。同じBFILEロケータを使用してこの関数を続けてコールしても何も行われません。
関連関数
OCIErrorGet()、OCILobClose()、OCILobFileCloseAll()、OCILobFileExists()、OCILobFileIsOpen()、OCILobFileOpen()、OCILobOpen()、OCILobIsOpen()
用途
指定のサービス・コンテキストでオープンしているすべてのBFILEをクローズします。
構文
sword OCILobFileCLoseAll ( OCISvcCtx *svchp,
OCIError *errhp );
パラメータ
サービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
コメント
指定のサービス・コンテキストでオープンしているすべてのBFILEをクローズします。
関連関数
OCILobFileClose()、OCIErrorGet()、OCILobFileExists()、OCILobFileIsOpen()
用途
サーバーのオペレーティング・システムにBFILEが存在するかどうかをテストします。
構文
sword OCILobFileExists ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *filep,
boolean *flag );
パラメータ
OCIサービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
ファイルを参照するBFILEロケータへのポインタです。
サーバーにBFILEが存在する場合はTRUEを、存在しない場合はFALSEを戻します。
コメント
サーバーのファイル・システムにBFILEが存在するかどうかをチェックします。内部LOBに対してこの関数をコールするとエラーになります。
関連関数
OCIErrorGet()、OCILobFileClose()、OCILobFileCloseAll()、OCILobFileIsOpen()、OCILobOpen()、OCILobIsOpen()
用途
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に対してこの関数をコールするとエラーになります。
関連関数
OCILobFileSetName()、OCIErrorGet()
用途
BFILEがオープンしているかどうかをテストします。
構文
sword OCILobFileIsOpen ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *filep,
boolean *flag );
パラメータ
OCIサービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
確認するBFILEロケータへのポインタです。
この特定のロケータを使用してBFILEがオープンされた場合はTRUEを、オープンされなかった場合はFALSEを戻します。
コメント
サーバー上のファイルがfilep BFILEロケータを使用してオープンされたかどうかをチェックします。内部LOBに対してこの関数をコールするとエラーになります。
OCILobFileOpen()またはOCILobOpen()コマンドに入力BFILEロケータが渡されなかった場合、ファイルはそのロケータによってオープンされていないとみなされます。ただし、別のロケータがそのファイルをオープンしていることがあります。オープンは、特定のロケータに対応付けられます。
関連関数
OCIErrorGet()、OCILobClose()、OCILobFileCloseAll()、OCILobFileExists()、OCILobFileClose()、OCILobFileOpen()、OCILobOpen()、OCILobIsOpen()
用途
読取り専用アクセス用にサーバーのファイル・システム上のBFILEをオープンします。
構文
sword OCILobFileOpen ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *filep,
ub1 mode );
パラメータ
サービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
オープンするBFILEです。ロケータがBFILEを参照していない場合はエラーが発生します。
ファイルをオープンするモードです。有効なモードはOCI_FILE_READONLYのみです。
コメント
サーバーのファイル・システムのBFILEをオープンします。BFILEは、読取り専用アクセス用にオープンできます。BFILEでは、Oracleを介した書込みはできません。内部LOBに対してこの関数をコールするとエラーになります。
この関数は、特定のBFILEロケータに対して初めてコールしたときにかぎり有効です。同じBFILEロケータを使用してこの関数を続けてコールしても何も行われません。
関連関数
OCIErrorGet()、OCILobClose()、OCILobFileCloseAll()、OCILobFileExists()、OCILobFileClose()、OCILobFileIsOpen()、OCILobOpen()、OCILobIsOpen()
用途
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に対してこの関数をコールするとエラーになります。
関連関数
OCILobFileGetName()、OCIErrorGet()
用途
この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から読み取られるデータによる初期化のコストもかかります。このオプションは、オンボード・メモリーが少ないクライアント環境用です。
関連関数
OCILobEnableBuffering()、OCIErrorGet()、OCILobWrite()、OCILobRead()、OCILobDisableBuffering()、OCILobWriteAppend()
用途
一時LOBを解放します。
構文
sword OCILobFreeTemporary( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp);
パラメータ
OCIサービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
解放するLOBを一意に参照するロケータです。
コメント
このロケータが指し示す一時LOBの内容を解放します。ロケータ自体は、OCIDescriptorFree() がコールされるまで解放されません。
locpパラメータで渡されるLOBロケータが一時LOBを指し示していない場合は、エラーを戻します。次のいずれかが原因である可能性があります。
ロケータが永続LOBを指し示しています。
ロケータがすでに解放された一時LOBを指し示しています。
ロケータが何も指し示していません。
関連関数
OCILobCreateTemporary()、OCILobIsTemporary()、OCIErrorGet()
用途
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では文字数で戻されます。可変幅のキャラクタ・セットの場合は、チャンクと同じ大きさのUnicode文字数です。
記憶域パラメータSECUREFILEを使用するLOBの場合、chunk_sizeは推奨サイズであり、下位互換性のために提供されています。
コメント
内部LOBが格納される表を作成するときに、チャンク係数を指定できます。チャンク係数は、Oracleブロックの倍数で、LOB値に対するアクセスまたは修正時に、LOBデータ層によって使用されるチャンク・サイズに対応しています。チャンクの一部はシステム関連情報に使用され、残りのチャンクにはLOB値が格納されます。この関数では、LOB値が格納されるLOBチャンクで使用される領域の量を戻します。アプリケーションからこのチャンク・サイズの倍数を使用して読取りまたは書込み要求を発行すると、パフォーマンスが向上します。書込みの場合は、他にも利点があります。LOBチャンクはバージョン管理されているので、すべての書込みをチャンク単位で行うと、不要または重複したバージョニングが行われることがありません。同じチャンクに対して複数の書込みコールを発行するかわりに、チャンクがいっぱいになるまで書込みを蓄積することもできます。
関連関数
OCIErrorGet()、OCILobGetStorageLimit()、OCILobRead()、OCILobAppend()、OCILobCopy()、OCILobWrite()、OCILobWriteAppend()
用途
LOBの長さを取得します。
構文
sword OCILobGetLength ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
ub4 *lenp );
パラメータ
サービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
一意にLOBを参照するLOBロケータです。内部LOBでは、このロケータは、svchpに指定したサーバーから取得されたロケータにしてください。BFILEの場合は、OCILobFileSetName()、SELECT文またはOCIObjectPin()を使用してロケータを設定できます。
出力時にLOBがNULLでない場合は、LOBの長さです。文字のLOBの場合は、LOB内の文字数です。バイナリのLOBおよびBFILEの場合は、LOB内のバイト数です。
コメント
LOBの長さを取得します。LOBがNULLの場合、長さは未定義です。BFILEの長さにはEOF（存在する場合）が含まれます。空の内部LOBの長さは0（ゼロ）です。
クライアント側のキャラクタ・セットが可変幅かどうかに関係なく、出力の長さは、CLOBとNCLOBでは文字数、BLOBとBFILEではバイト数です。
|
注意: 以前の OCILobErase()またはOCILobWrite2()のコールによってLOBに書き込まれた0（ゼロ）バイトや空白の充填文字も、長さの一部になります。 |
関連関数
OCIErrorGet()、OCILobFileSetName()、OCILobGetLength2()、OCILobRead()、OCILobWrite()、OCILobCopy()、OCILobAppend()、OCILobLoadFromFile()、OCILobWriteAppend()
用途
LOBの長さを取得します。4GBを超えるサイズのLOBには、この関数を使用する必要があります。4GB未満のLOBにもこの関数を使用できます。
構文
sword OCILobGetLength2 ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
oraub8 *lenp );
パラメータ
用途
指定の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）の最大長（バイト単位）を取得します。
構文
sword OCILobGetStorageLimit ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
oraub8 *limitp );
パラメータ
サービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIError()に渡すエラー・ハンドルです。
一意にLOBを参照するLOBロケータです。このロケータは、svchpに指定したサーバーから取得されたロケータにしてください。
データベースに格納できるLOBの最大長（バイト単位）です。
コメント
ブロック・サイズの範囲は2〜32KBであるため、LOBの場合、最大LOBサイズの範囲は8〜128TBです。
関連関数
用途
2つのLOBまたはBFILEロケータの等価を比較します。
構文
sword OCILobIsEqual ( OCIEnv *envhp,
const OCILobLocator *x,
const OCILobLocator *y,
boolean *is_equal );
パラメータ
OCI環境ハンドルです。
比較するLOBロケータです。
比較するLOBロケータです。
LOBロケータが等価の場合はTRUE、等価でない場合はFALSEです。
コメント
指定されたLOBまたはBFILEロケータの等価を比較します。2つのLOBまたはBFILEロケータは、どちらも同じLOBまたはBFILE値を参照している場合のみ等価になります。
この関数では、2つのNULLロケータは等価とみなされません。
関連関数
OCILobAssign()、OCILobLocatorIsInit()
用途
LOBまたはBFILEがオープンされているかどうかを確認します。
構文
sword OCILobIsOpen ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
boolean *flag );
パラメータ
サービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のために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がオープンされているかどうかを確認するため、ラウンドトリップが必要です。
関連関数
OCIErrorGet()、OCILobClose()、OCILobFileCloseAll()、OCILobFileExists()、OCILobFileClose()、OCILobFileIsOpen()、OCILobFileOpen()、OCILobOpen()
用途
ロケータが一時LOBを指し示しているかどうかを確認します。
構文
sword OCILobIsTemporary(OCIEnv *envhp,
OCIError *errhp,
OCILobLocator *locp,
boolean *is_temporary);
パラメータ
OCI環境ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
確認するロケータです。
ロケータが一時LOBを指し示している場合はTRUEを、そうでない場合はFALSEを戻します。
コメント
この関数は、ロケータが一時LOBを指し示しているかどうかを調べるためにロケータを確認します。 指し示している場合は、is_temporaryがTRUEに設定されます。 そうでない場合は、is_temporaryがFALSEに設定されます。
関連関数
OCILobCreateTemporary()、OCILobFreeTemporary()
用途
ファイルの全体または一部を内部LOBにロードおよびコピーします。
構文
sword OCILobLoadFromFile ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *dst_locp,
OCILobLocator *src_locp,
ub4 amount,
ub4 dst_offset,
ub4 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の拡張とNULL BFILEのコピーはエラーになります。
このLOB操作をオープン・コールまたはクローズ・コールで囲む必要はありません。この操作を実行する前にLOBをオープンしていない場合、LOB列のファンクション索引とドメイン索引はこのコール時に更新されます。この操作を実行する前にLOBをオープンしている場合は、トランザクションをコミットまたはロールバックする前に、そのLOBをクローズする必要があります。内部LOBをクローズすると、LOB列のファンクション索引とドメイン索引が更新されます。
LOB操作をオープンAPIまたはクローズAPIで囲んでいない場合、ファンクション索引とドメイン索引は、LOBに書き込むたびに更新されます。これによって、パフォーマンスが低下する可能性があります。ファンクション索引とドメイン索引がある場合は、LOBへの書込み操作をオープン文またはクローズ文内に含めることをお薦めします。
関連関数
OCIErrorGet()、OCILobAppend()、OCILobWrite()、OCILobTrim()、OCILobCopy()、OCILobGetLength()、OCILobLoadFromFile2()、OCILobWriteAppend()
用途
ファイルの全体または一部を内部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 );
パラメータ
用途
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ロケータを参照するようにします。
関連関数
OCIErrorGet()、OCILobAssign()、OCILobIsEqual()、OCILobLocatorIsInit()
用途
指定されたLOBまたはBFILEロケータが初期化されているかどうかをテストします。
構文
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()をコールします。
関連関数
用途
指定されたモードで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または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への書込み操作をオープン文またはクローズ文内に含めることをお薦めします。
関連関数
OCIErrorGet()、OCILobClose()、OCILobFileCloseAll()、OCILobFileExists()、OCILobFileClose()、OCILobFileIsOpen()、OCILobFileOpen()、OCILobIsOpen()
用途
LOBまたはBFILEの一部をコールの指定どおりにバッファに読み取ります。
構文
sword OCILobRead ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
ub4 *amtp,
ub4 offset,
void *bufp,
ub4 bufl,
void *ctxp,
OCICallbackLobRead (cbfp)
( void *ctxp,
const void *bufp,
ub4 len,
ub1 piece
)
ub2 csid,
ub1 csfrm );
パラメータ
サービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
一意にLOBまたはBFILEを参照するLOBまたはBFILEロケータです。このロケータは、svchpに指定したサーバーから取得されたロケータにしてください。
次の表に示すように、amtpの値は、バイト数または文字数のいずれかで表される量です。
表17-4 amtpの文字数またはバイト数
| LOBまたはBFILE | 入力 | 固定幅のクライアント側キャラクタ・セットによる出力 | 可変幅のクライアント側キャラクタ・セットによる出力 |
|---|---|---|---|
|
|
バイト |
バイト |
バイト |
|
|
文字 |
文字 |
バイト（1） |
（1）入力量は、サーバー側のCLOBまたはNCLOBから読み取る文字数を示します。出力量は、バッファbufpに読み取られたバイト数を示します。
次の場合、*amtpは読み取られたデータの総量です。
データがストリーム・モードで読み取られない場合（1ピースのみ読み取られ、ポーリングまたはコールバックは行われません）。
データがコールバックによってストリーム・モードで読み取られる場合
データがポーリングを使用してストリーム・モードで読み取られる場合、*amtpは読み取られた最後のピースの長さです。
読み取られる量がバッファの長さより多い場合、ストリーム・モードでのLOBの読取りは、入力オフセットからLOBの終わりまでか、指定されたバイト数の読取りまで、いずれか先に達するところまで行われます。入力時にこの値が0（ゼロ）の場合は、入力オフセットからLOBの末尾までストリーム・モードでデータが読み取られます。
ストリーム・モード（ポーリングまたはコールバックのいずれかで実行）の場合、LOB値は入力オフセットから連続して読み取られます。
データがピース単位で読み取られる場合、*amtpには常に読み取られた各ピースの長さが含まれます。
コールバック関数が定義されている場合は、パイプからbuflバイトが読み取られるたびにそのコールバック関数が呼び出されます。各ピースがbufpに書き込まれます。
コールバック関数が定義されていない場合は、OCI_NEED_DATAエラー・コードが戻ります。アプリケーションでは、OCI_NEED_DATAエラー・コードが戻らなくなるまで何度もOCILobRead()をコールし、LOBのピースを読み取る必要があります。ピースのサイズを変えながら複数の場所を読み取る場合は、コールごとにバッファ・ポインタと長さを変えることができます。
入力時、これはLOB値の先頭からの絶対オフセットです。キャラクタLOB（CLOB、NCLOB）の場合は、LOBの先頭からの文字数です。バイナリLOBまたはBFILEの場合はバイト数です。先頭位置は1です。
ポーリングまたはコールバックによるストリームを使用する場合は、最初のコールでオフセットを指定します。後続のポーリング・コールでは、offsetパラメータは無視されます。コールバックを使用する場合、offsetパラメータはありません。
ピースの読取り先バッファへのポインタです。buflのメモリー長が割り当てられるとみなされます。
オクテットで示したバッファの長さです。 buflパラメータがバイト数で指定され、amtpパラメータが文字で指定されている場合、この値は、CLOBおよびNCLOBのamtp値（csfrm=SQLCS_NCHAR）とは異なります。
コールバック関数用のコンテキスト・ポインタです。NULLにできます。
各ピースに対してコールされるように登録できるコールバックです。これがNULLの場合は、ピースごとにOCI_NEED_DATAが戻ります。
コールバック関数は、OCI_CONTINUEを戻して読取りを続行する必要があります。これ以外のエラー・コードが戻った場合、LOBの読取りは終了します。
コールバック関数用のコンテキストです。NULLにできます。
ピース用のバッファ・ポインタです。
bufpにおけるカレント・ピースのバイト長です。
ピースは、OCI_FIRST_PIECE、OCI_NEXT_PIECEまたはOCI_LAST_PIECEです。
バッファ・データのキャラクタ・セット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にあること、およびディレクトリ・オブジェクトの読取り許可がユーザーにあることが必要です。
OCILobRead()に対してポーリング・モードを使用するとき、ユーザーは最初のコールではoffsetおよびamtpの値を指定する必要がありますが、その後のOCILobRead()のポーリング・コールではこれらの値を指定する必要はありません。
LOBがBLOBの場合、csidパラメータおよびcsfrmパラメータは無視されます。
|
注意: OCILobRead()操作を終了して文ハンドルを解放するには、OCIBreak()コールを使用します。 |
次のルールは、CLOBおよびNCLOBのクライアント側可変幅キャラクタ・セットに適用されます。
ポーリング・モードを使用する場合は、最初のOCILobRead()コールでamtpパラメータとoffsetパラメータのみ指定してください。後続のポーリング・コールでは、これらのパラメータは無視されます。
コールバックを使用する場合、lenパラメータはコールバックへの入力で、バッファ内で格納されたバイト数を示します。バッファの空き領域を確認するため、コールバック処理中にlenパラメータをチェックします。
次のルールは、CLOBおよびNCLOBのクライアント側の固定幅キャラクタ・セットおよび可変幅キャラクタ・セットに適用されます。
CLOB値またはNCLOB値を読み取る場合は、OCILobRead()をコールするたびにamtpパラメータを参照し、バッファに格納された量を確認します。戻り値が文字数の場合（クライアント側のキャラクタ・セットが固定幅の場合）は、この値をバイトに変換して、バッファに格納された量を判断します。コールバックを使用する場合は、常にlenパラメータをチェックしてバッファに格納された量を確認します。この値は、常にバイト単位です。
UTF-16形式でデータを読み取るには、csidパラメータをOCI_UTF16IDに設定します。csidパラメータが設定された場合は、このパラメータによって環境変数NLS_LANGが上書きされます。
|
関連項目:
|
関連関数
OCIErrorGet()、OCILobRead2()、OCILobWrite()、OCILobFileSetName()、OCILobWriteAppend()
用途
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です。csfrmが指定されていない場合は、デフォルトが使用されます。
コメント
LOBまたはBFILEの一部をコールの指定どおりにバッファに読み取ります。NULL属性のLOBまたはBFILEから読み取るとエラーになります。
|
注意: LOBを読み取るかまたは書き込むときは、指定されたキャラクタ・セット・フォーム（ csfrm）がロケータのフォームと一致している必要があります。 |
BFILEの場合は、すでにオペレーティング・システム・ファイルがサーバー上に存在しており、それらのファイルは、入力ロケータを使用してOCILobFileOpen()またはOCILobOpen()によってオープンされている必要があります。オペレーティング・システム・ファイルの読取り権限がOracleにあること、およびディレクトリ・オブジェクトの読取り許可がユーザーにあることが必要です。
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は現在のピースに読み取られる文字数を示します。
コールバックを使用する場合、lenパラメータはコールバックへの入力で、バッファ内で格納されたバイト数を示します。バッファの空き領域を確認するため、コールバック処理中にlenパラメータをチェックします。
ポーリングを使用する場合、byte_amtpパラメータを参照し、現在のピースでバッファに格納されている量を確認します。CLOBおよびNCLOBでは、char_amtpはバッファに読み取られる文字数も戻します。
UTF-16形式でデータを読み取るには、csidパラメータをOCI_UTF16IDに設定します。csidパラメータが設定された場合は、このパラメータによって環境変数NLS_LANGが上書きされます。
|
関連項目:
|
関連関数
OCIErrorGet()、OCILobWrite2()、OCILobFileSetName()、OCILobWriteAppend2()
用途
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_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（ゼロ）を渡します。
関連関数
用途
LOB値を短い長さに切り捨てます。
構文
sword OCILobTrim ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
ub4 newlen );
パラメータ
サービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
一意にLOBを参照する内部LOBロケータです。このロケータは、svchpに指定したサーバーから取得されたロケータにしてください。
LOB値の新しい長さ（現行の長さ以下）です。文字のLOBの場合は、LOB内の文字数です。バイナリのLOBおよびBFILEの場合は、LOB内のバイト数です。
コメント
この関数では、LOBデータを指定の長さに切り捨てます。newlenが現行のLOBの長さより長い場合は、エラーが戻されます。この関数は内部LOBでのみ有効です。BFILEには使用できません。
このLOB操作をオープン・コールまたはクローズ・コールで囲む必要はありません。この操作を実行する前にLOBをオープンしていない場合、LOB列のファンクション索引とドメイン索引はこのコール時に更新されます。この操作を実行する前にLOBをオープンしている場合は、トランザクションをコミットまたはロールバックする前に、そのLOBをクローズする必要があります。内部LOBをクローズすると、LOB列のファンクション索引とドメイン索引が更新されます。
LOB操作をオープンAPIまたはクローズAPIで囲んでいない場合、ファンクション索引とドメイン索引は、LOBに書き込むたびに更新されます。これによって、パフォーマンスが低下する可能性があります。ファンクション索引とドメイン索引がある場合は、LOBへの書込み操作をオープン文またはクローズ文内に含めることをお薦めします。
関連関数
OCIErrorGet()、OCILobRead()、OCILobAppend()、OCILobCopy()、OCILobErase()、OCILobTrim2()、OCILobWrite()、OCILobWriteAppend()
用途
LOB値を短い長さに切り捨てます。4GBを超えるサイズのLOBには、この関数を使用する必要があります。4GB未満のLOBにもこの関数を使用できます。
構文
sword OCILobTrim2 ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
oraub8 newlen );
パラメータ
用途
バッファをLOBに書き込みます。
構文
sword OCILobWrite ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
ub4 *amtp,
ub4 offset,
void *bufp,
ub4 buflen,
ub1 piece,
void *ctxp,
OCICallbackLobWrite (cbfp)
(
void *ctxp,
void *bufp,
ub4 *lenp,
ub1 *piecep
)
ub2 csid,
ub1 csfrm );
パラメータ
サービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
一意にLOBを参照する内部LOBロケータです。このロケータは、svchpに指定したサーバーから取得されたロケータにしてください。
次の表に示すように、amtpの値は、バイト数または文字数のいずれかで表される量です。
表17-5 amtpの文字数またはバイト数
| LOBまたはBFILE | 固定幅のクライアント側キャラクタ・セットを使用する入力 | 可変幅のクライアント側キャラクタ・セットを使用する入力 | 出力 |
|---|---|---|---|
|
|
バイト |
バイト |
バイト |
|
|
文字 |
バイト（1） |
文字 |
（1）入力量は、ユーザーがLOBに書き込むデータのバイト数で、bufp内のバイト数ではありません。bufp内のバイト数は、buflenによって指定されます。データがピースごとに読み取られる場合は、書き込むバイトの量は、buflenよりも大きくできます。出力量は、サーバー側のCLOBまたはNCLOBに書き込む文字数を指します。
このパラメータは常にNULL以外のポインタです。EOFまでの書込みを指定する場合は、変数を宣言してゼロを設定し、そのアドレスをこのパラメータに渡します。
入力時に量が指定されていて、データがピース単位で書き込まれる場合、*amtpにはコール終了時（最後のピースが書き込まれた時点）に各ピースの長さの合計が格納され、書込み途中は未定義になります。ピース単位の読取りとは異なることに注意してください。指定された量がサーバーに送信されない場合は、エラーが戻されます。
amtpが0（ゼロ）の場合は、ストリーム・モードが使用され、ユーザーがOCI_LAST_PIECEを指定するまでデータが書き込まれます。
入力時、これはLOB値の先頭からの絶対オフセットです。文字LOBではLOBの先頭からの文字数であり、バイナリLOBではバイト数です。先頭位置は1です。
ポーリングまたはコールバックによるストリームを使用する場合は、最初のコールでオフセットを指定します。後続のポーリング・コールでは、offsetパラメータは無視されます。コールバックを使用する場合、offsetパラメータはありません。
ピースの書込み元バッファへのポインタです。バッファ内のデータの長さがbuflenに渡された値であるとみなされます。データがポーリング・メソッドを使用してピース単位で書き込まれる場合でも、bufpは、このコールが呼び出されたときは、LOBの最初のピースを格納する必要があります。コールバックが使用される場合、データの提供にbufpは使用できません。使用するとエラーになります。
バッファ内のデータの長さ（バイト数）です。buflenパラメータがバイト数で指定され、amtpパラメータが文字数で指定されている場合、この値は、CLOBおよびNCLOBの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です。
バッファ内のデータのキャラクタ・セットIDです。この値が0（ゼロ）の場合は、csfrmの値に応じて、csidにクライアントのNLS_LANG値またはNLS_CHAR値が設定されます。
バッファ・データのキャラクタ・セット・フォームです。csfrmパラメータは、LOBの型と一貫している必要があります。
csfrmは、0（ゼロ）以外の次の2つの値をとることができます。
デフォルト値はSQLCS_IMPLICITです。
コメント
バッファを指定どおりに内部LOBに書き込みます。LOBにすでにデータが存在する場合は、バッファに格納されたデータによって上書きされます。バッファは、このコールによって単独のピースとしてLOBに書き込むことも、コールバックまたは標準ポーリング・メソッドを使用してピース単位で提供することもできます。
|
注意: LOBを読み取るかまたは書き込むときは、指定されたキャラクタ・セット・フォーム（ csfrm）がロケータのフォームと一致している必要があります。 |
OCILobWrite()に対してポーリング・モードを使用している場合、ユーザーは最初のコールではoffsetおよびamtpの値を指定する必要がありますが、その後のOCILobWrite()のコールでは指定する必要はありません。
pieceパラメータの値がOCI_FIRST_PIECEである場合、データによっては、コールバックまたはポーリングを介して提供される必要があります。
コールバック関数がcbfpパラメータに定義されている場合は、パイプに1ピースが書き込まれるとこのコールバック関数が呼び出され、次のピースが取得されます。各ピースがbufpから書き込まれます。コールバック関数が定義されていない場合、OCILobWrite()は、OCI_NEED_DATAエラー・コードを戻します。LOBのピースの書込みを続けるには、アプリケーションでOCILobWrite()を再度コールする必要があります。このモードでは、ピースが別々のサイズで複数の場所に読み取られる場合、コールごとにバッファ・ポインタと長さを変えることができます。
pieceパラメータの値がOCI_LAST_PIECEのときは、ポーリングまたはコールバック方式が使用されているかどうかに関係なく、ピース単位書込み操作は終了します。
（どの入力方法を使用した場合も）Oracleに渡されるデータの量が、amtpパラメータに指定された量より少ない場合は、ORA-22993エラーが戻されます。
この関数は内部LOBでのみ有効です。BFILEは読取り専用のため、取り扱えません。LOBがBLOBの場合、csidパラメータおよびcsfrmパラメータは無視されます。
クライアント側のキャラクタ・セットが可変幅の場合、CLOBおよびNCLOBについては、入力はバイト数で、出力は文字数で表されます。入力量は、ユーザーがLOBに書き込むデータのバイト数で、bufp内のバイト数ではありません。bufp内のバイト数は、buflenによって指定されます。データがピースごとに読み取られる場合は、書き込むバイトの量は、buflenよりも大きくできます。出力量は、サーバー側のCLOBまたはNCLOBに書き込む文字数を指します。
UTF-16形式でデータを書き込むには、csidパラメータをOCI_UTF16IDに設定します。csidパラメータが設定された場合は、このパラメータによって環境変数NLS_LANGが上書きされます。
このLOB操作をオープン・コールまたはクローズ・コールで囲む必要はありません。この操作を実行する前にLOBをオープンしていない場合、LOB列のファンクション索引とドメイン索引はこのコール時に更新されます。この操作を実行する前にLOBをオープンしている場合は、トランザクションをコミットまたはロールバックする前に、そのLOBをクローズする必要があります。内部LOBをクローズすると、LOB列のファンクション索引とドメイン索引が更新されます。
LOB操作をオープンAPIまたはクローズAPIで囲んでいない場合、ファンクション索引とドメイン索引は、LOBに書き込むたびに更新されます。これによって、パフォーマンスが低下する可能性があります。ファンクション索引とドメイン索引がある場合は、LOBへの書込み操作をオープン文またはクローズ文内に含めることをお薦めします。
|
関連項目:
|
関連関数
OCIErrorGet()、OCILobRead()、OCILobAppend()、OCILobCopy()、OCILobWriteAppend()、OCILobWrite2()
用途
バッファを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は使用できません。使用するとエラーになります。
バッファ内のデータの長さ（バイト数）です。buflenパラメータがバイト数で指定され、量がchar_amtpパラメータを使用して文字数で指定されている場合、この値は、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つの値をとることができます。
コメント
バッファを指定どおりに内部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への書込み操作をオープン文またはクローズ文内に含めることをお薦めします。
|
関連項目:
|
関連関数
OCIErrorGet()、OCILobRead2()、OCILobAppend()、OCILobCopy()、OCILobWriteAppend2()
用途
LOBの末尾からデータの書込みを開始します。
構文
sword OCILobWriteAppend ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
ub4 *amtp,
void *bufp,
ub4 buflen,
ub1 piece,
void *ctxp,
OCICallbackLobWrite (cbfp)
(
void *ctxp,
void *bufp,
ub4 *lenp,
ub1 *piecep
)
ub2 csid,
ub1 csfrm );
パラメータ
サービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
一意にLOBを参照する内部LOBロケータです。
次の表に示すように、amtpの値は、バイト数または文字数のいずれかで表される量です。
表17-6 amtpの文字数またはバイト数
| LOBまたはBFILE | 固定幅のクライアント側キャラクタ・セットを使用する入力 | 可変幅のクライアント側キャラクタ・セットを使用する入力 | 出力 |
|---|---|---|---|
|
|
バイト |
バイト |
バイト |
|
|
文字 |
バイト（1） |
文字 |
（1）入力量は、ユーザーがLOBに書き込むデータのバイト数で、bufp内のバイト数ではありません。bufp内のバイト数は、buflenによって指定されます。データがピースごとに読み取られる場合は、書き込むバイトの量は、buflenよりも大きくできます。出力量は、サーバー側のCLOBまたはNCLOBに書き込む文字数を指します。
入力時に量が指定されていて、データがピース単位で書き込まれる場合、*amtpにはコール終了時（最後のピースが書き込まれた時点）に各ピースの長さの合計が格納され、書込み途中は未定義になります（ピース単位の読取りとは異なることに注意してください）。指定された量がサーバーに送信されない場合は、エラーが戻されます。amtpが0（ゼロ）の場合は、ストリーム・モードが使用され、ユーザーがOCI_LAST_PIECEを指定するまでデータが書き込まれます。
クライアント側のキャラクタ・セットが可変幅の場合、CLOBまたはNCLOBの入力量は文字ではなくバイトで表されます。
ピースの書込み元バッファへのポインタです。バッファ内のデータの長さが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です。
バッファ・データのキャラクタ・セットIDです。
バッファ・データのキャラクタ・セット・フォームです。
csfrmは、0（ゼロ）以外の次の2つの値をとることができます。
デフォルト値はSQLCS_IMPLICITです。
コメント
バッファは、このコールによって単独のピースとしてLOBに書き込むことも、コールバックまたは標準ポーリング・メソッドを使用してピース単位で提供することもできます。pieceパラメータの値がOCI_FIRST_PIECEである場合、データによっては、コールバックまたはポーリングを介して提供される必要があります。コールバック関数がcbfpパラメータに定義されている場合は、パイプに1ピースが書き込まれるとこのコールバック関数が呼び出され、次のピースが取得されます。各ピースがbufpから書き込まれます。コールバック関数が定義されていない場合、OCILobWriteAppend()は、OCI_NEED_DATAエラー・コードを戻します。
LOBのピースの書込みを続けるには、アプリケーションでOCILobWriteAppend()を再度コールする必要があります。このモードでは、ピースが別々のサイズで複数の場所に読み取られる場合、コールごとにバッファ・ポインタと長さを変えることができます。pieceパラメータの値がOCI_LAST_PIECEのときは、ピース単位の書込みは終了します。
LOBバッファリングが有効な場合、OCILobWriteAppend()はサポートされません。
LOBがBLOBの場合、csidパラメータおよびcsfrmパラメータは無視されます。
クライアント側のキャラクタ・セットが可変幅の場合、CLOBまたはNCLOBの入力量は文字ではなくバイトで表されます。
このLOB操作をオープン・コールまたはクローズ・コールで囲む必要はありません。この操作を実行する前にLOBをオープンしていない場合、LOB列のファンクション索引とドメイン索引はこのコール時に更新されます。この操作を実行する前にLOBをオープンしている場合は、トランザクションをコミットまたはロールバックする前に、そのLOBをクローズする必要があります。内部LOBをクローズすると、LOB列のファンクション索引とドメイン索引が更新されます。
LOB操作をオープンAPIまたはクローズAPIで囲んでいない場合、ファンクション索引とドメイン索引は、LOBに書き込むたびに更新されます。これによって、パフォーマンスが低下する可能性があります。ファンクション索引とドメイン索引がある場合は、LOBへの書込み操作をオープン文またはクローズ文内に含めることをお薦めします。
関連関数
OCIErrorGet()、OCILobRead()、OCILobAppend()、OCILobCopy()、OCILobWrite()、OCILobWriteAppend2()
用途
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です。
コメント
バッファは、このコールによって単独のピースとして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への書込み操作をオープン文またはクローズ文内に含めることをお薦めします。
関連関数
OCIErrorGet()、OCILobRead2()、OCILobAppend()、OCILobCopy()、OCILobWrite2()
