表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への書込み操作をオープン文またはクローズ文内に含めることをお薦めします。