26.3 LOB関数

表26-2は、この項で説明している、LOBロケータを使用するLOB関数を示しています。すべての新規アプリケーションには、「2」で終わる関数を使用します。

Oracle Database 12cリリース2 (12.2)以上では、ほとんどのLOB関数でアプリケーション・コンティニュイティがサポートされます(完全なリストは、「OCIのアプリケーション・コンティニュイティがフェイルオーバーできる場合」を参照してください)。このサポートには、互換性について「非推奨のLOB関数」にリストされている一部の非推奨のLOB関数も含まれます。

Oracle Database 12cリリース2 (12.2)以上では、OCI LOB関数によってリモートLOB (CLOB、BLOB)での分散操作がサポートされます(BFILES用のOCI LOB関数を除く)。これには、以前のリリースではエラーを戻していたリモートLOBロケータを選択する一定の問合せのサポートが含まれます。唯一の制限は、2つのロケータを受け入れるすべてのLOB関数で、両方のLOBが1つのデータベースに存在している必要があることです。次のLOB関数では、リモート・ロケータが渡されるとエラーがスローされます: OCILobAssign()、OCILobLocatorAssign()、OCILobArrayRead()、OCILobArrayWrite()およびOCILobLoadFromFile2()。

注意:

LOBへのアクセスには、LOB用のデータ・インタフェースを使用するというもう1つの方法があります。次の場所で説明するように、CLOB列の文字データまたはBLOB列のRAWデータをバインドまたは定義できます。

• INSERT文およびUPDATE文の使用方法および使用例は、LOBデータのバインドおよび定義についてを参照してください

• SELECT文の使用方法および使用例は、「LOBデータの定義について」を参照してください

• LOBおよびBFILEの操作

表26-2 LOB関数 

関数	用途
OCIDurationBegin()	一時LOBのためのユーザー期間を開始します。
OCIDurationEnd()	一時LOBのためのユーザー期間を終了します。
OCILobAppend()	1つのLOBを別のLOBの後に追加します。
OCILobArrayRead()	複数のロケータのLOBデータを読み取ります。
OCILobArrayWrite()	複数のロケータのLOBデータを書き込みます。
OCILobAssign()	1つのLOBロケータを別のLOBロケータに割り当てます。
OCILobCharSetForm()	LOBロケータからキャラクタ・セットを取得します。
OCILobCharSetId()	LOBロケータからキャラクタ・セットIDを取得します。
OCILobClose()	オープンされているLOBをクローズします。
OCILobCopy2()	LOBの一部または全部を別のLOBにコピーします。4GBを超えるサイズのLOBには、この関数を使用する必要があります。
OCILobCreateTemporary()	一時LOBを作成します。
OCILobErase2()	LOBの一部を消去します。4GBを超えるサイズのLOBには、この関数を使用する必要があります。
OCILobFileClose()	オープンされているBFILEをクローズします。
OCILobFileCloseAll()	オープンされているすべてのFILEをクローズします。
OCILobFileExists()	サーバー上のファイルの存在をチェックします。
OCILobFileGetName()	LOBロケータからディレクトリ・オブジェクトとファイル名を取得します。
OCILobFileIsOpen()	サーバー上のファイルがこのロケータでオープンされているかどうかをチェックします。
OCILobFileOpen()	BFILEをオープンします
OCILobFileSetName()	LOBロケータにディレクトリ・オブジェクトとファイル名を設定します。
OCILobFreeTemporary()	一時LOBを解放します。
OCILobGetChunkSize()	LOBのチャンク・サイズを取得します。
OCILobGetContentType()	SecureFileのユーザー指定コンテンツ・タイプ文字列(ファイル形式識別子)を取り出します。
OCILobGetLength2()	LOBの長さを取得します。4GBを超えるサイズのLOBには、この関数を使用する必要があります。
OCILobGetOptions()	SecureFileのオプション設定を取得します。
OCILobGetStorageLimit()	内部LOB (BLOB、CLOBまたはNCLOB)の最大長(バイト単位)を取得します。
OCILobIsEqual()	2つのLOBロケータが等しいか比較します。
OCILobIsOpen()	LOBがオープンされているかどうかをチェックします。
OCILobIsTemporary()	特定のLOBが一時LOBかどうかを判断します。
OCILobLoadFromFile2()	BFILEからLOBをロードします。4GBを超えるサイズのLOBには、この関数を使用する必要があります。
OCILobLocatorAssign()	1つのLOBロケータを別のLOBロケータに割り当てます。
OCILobLocatorIsInit()	LOBロケータが初期化されているかどうかをチェックします。
OCILobOpen()	LOBをオープンします
OCILobRead2()	LOBの一部を読み取ります。4GBを超えるサイズのLOBには、この関数を使用する必要があります。
OCILobSetContentType()	SecureFileのユーザー指定コンテンツ・タイプ文字列を格納します。
OCILobSetOptions()	既存のSecureFileと新規に作成されたSecureFileのオプション設定を有効化します。
OCILobTrim2()	LOBを切り捨てます。4GBを超えるサイズのLOBには、この関数を使用する必要があります。
OCILobWrite2()	LOBに書き込みます。4GBを超えるサイズのLOBには、この関数を使用する必要があります。
OCILobWriteAppend2()	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の読取りまたは書込みを行うことです。ストリームは、ポーリング・メカニズムを使用するか、またはユーザー定義コールバックを登録して実装できます。

26.3.1 OCIDurationBegin()

一時LOBのためのユーザー期間を開始します。

用途

一時LOBのためのユーザー期間を開始します。

構文

sword OCIDurationBegin ( OCIEnv              *env,
                         OCIError            *err,
                         const OCISvcCtx     *svc, 
                         OCIDuration          parent,
                         OCIDuration         *duration );

パラメータ

env (IN/OUT)

NULLポインタを渡します。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

svc (IN)

OCIサービス・コンテキスト・ハンドルです。NULL以外にしてください。

parent (IN)

親の継続時間の時間番号です。次のいずれかです。

• OCI_DURATION_STATEMENT

• OCI_DURATION_SESSION

duration (OUT)

新しく作成されたユーザー期間固有の識別子です。

コメント

この関数によってユーザー期間が開始されます。リリース8.1以上では、一時LOBを作成する際にユーザー期間を使用できます。ユーザーは複数のアクティブなユーザー期間を同時に利用できます。ユーザー期間をネストする必要はありません。durationパラメータは、このコールによって作成された期間を識別するための一意の番号を戻すために使用します。

26.3.2 OCIDurationEnd()

一時LOBのためのユーザー期間を終了します。

用途

一時LOBのためのユーザー期間を終了します。

構文

sword OCIDurationEnd ( OCIEnv             *env, 
                       OCIError           *err, 
                       const OCISvcCtx    *svc,
                       OCIDuration         duration );

パラメータ

env (IN/OUT)

NULLポインタを渡します。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

svc (IN)

OCIサービス・コンテキストです。これは、カートリッジ・サービスに対してNULLとして渡されます。

duration (IN)

ユーザー期間を識別するための番号です。

コメント

この関数によってユーザー期間が終了します。ユーザー期間に割り当てられていた一時LOBが解放されます。

26.3.3 OCILobAppend()

別のLOBの末尾にLOB値を指定どおりに追加します。

用途

別のLOBの末尾にLOB値を指定どおりに追加します。

構文

sword OCILobAppend ( OCISvcCtx        *svchp,
                     OCIError         *errhp,
                     OCILobLocator    *dst_locp,
                     OCILobLocator    *src_locp );

パラメータ

svchp (IN)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

dst_locp (IN/OUT)

一意に宛先LOBを参照する内部LOBロケータです。このロケータは、svchpに指定したサーバーから取得されたロケータにしてください。

src_locp (IN)

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

26.3.4 OCILobArrayRead()

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 );

パラメータ

svchp (IN/OUT)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

array_iter (IN/OUT)

IN - このパラメータは、LOBロケータ配列のサイズを指定します。ポーリングでは、このパラメータが関連するのは最初のコールのみで、後続のコールでは無視されます。

OUT - ポーリング・モードの場合に、このパラメータは読取り元の要素の配列索引を指定します。

locp_arr (IN)

LOBまたはBFILEロケータの配列です。

byte_amt_arr (IN/OUT)

oraub8変数の配列です。配列サイズは、ロケータの配列サイズと同じである必要があります。エントリは、ロケータのバイト数に対応します。

IN: データベースから読み取るバイト数です。BLOBおよびBFILEに対して常に使用されます。CLOBおよびNCLOBに対しては、char_amt_arrの該当値が0 (ゼロ)の場合のみ使用されます。

OUT: ユーザー・バッファに読み取られるバイト数です。

char_amt_arr (IN/OUT)

oraub8変数の配列です。配列サイズは、ロケータの配列サイズと同じである必要があります。エントリは、ロケータの文字数に対応します。

IN: ユーザー・バッファに読み取られる最大文字数です。BLOBおよびBFILEの場合は無視されます。

OUT: ユーザー・バッファに読み取られる文字数です。BLOBおよびBFILEの場合は未定義になります。

offset_arr (IN)

oraub8変数の配列です。配列サイズは、ロケータの配列サイズと同じである必要があります。文字LOB (CLOB、NCLOB)ではLOBの先頭からの文字数であり、バイナリLOBまたはBFILEではバイト数です。先頭位置は1です。

bufp _arr (IN/OUT)

ピースの読取り先バッファへのポインタの配列です。配列サイズは、ロケータの配列サイズと同じである必要があります。

bufl_arr (IN)

バッファ配列のバッファ長を示すoraub8変数の配列です。配列サイズは、ロケータの配列サイズと同じである必要があります。

piece (IN)

OCI_ONE_PIECE: コールではポーリングは想定されません。示された量がバッファ長より大きい場合、バッファには可能なかぎり格納されます。

ポーリングでは、最初にOCI_FIRST_PIECE、後続のコールでOCI_NEXT_PIECEを渡します。OCI_FIRST_PIECEはコールバックの使用時に渡される必要があります。

ctxp (IN)

コールバック関数用のコンテキスト・ポインタです。NULLにできます。

cbfp (IN)

各ピースに対してコールされるように登録できるコールバックです。これがNULLの場合は、ピースごとにOCI_NEED_DATAが戻ります。

コールバック関数は、OCI_CONTINUEを戻して読取りを続行する必要があります。これ以外のエラー・コードが戻った場合、LOBの読取りは終了します。

ctxp (IN)

コールバック関数用のコンテキストです。NULLにできます。

array_iter (IN)

読取り元の要素の索引です。

bufp (IN/OUT)

ピース用のバッファ・ポインタです。

lenp (IN)

bufpにおけるカレント・ピースのバイト長です。

piecep (IN)

ピースは、OCI_FIRST_PIECE、OCI_NEXT_PIECEまたはOCI_LAST_PIECEです。

changed_bufpp (OUT)

コールバック関数は、次に読み取るピースに新規バッファを使用することを選択した場合、新規バッファのアドレスを指定できます。このパラメータがNULLに設定されている場合、デフォルトの旧バッファbufpが使用されます。

changed_lenp (OUT)

新規バッファ(指定されている場合)の長さです。

csid (IN)

バッファ・データのキャラクタ・セットIDです。この値が0 (ゼロ)の場合は、csfrmの値に応じて、csidにクライアントのNLS_LANG値またはNLS_CHAR値が設定されます。サーバーとクライアントの設定が同一である場合を除き、サーバーのキャラクタ・セットとはみなされません。

csfrm (IN)

バッファ・データのキャラクタ・セット・フォームです。csfrmパラメータは、LOBの型と一貫している必要があります。

csfrmパラメータは、0 (ゼロ)以外の次の2つの値をとることができます。

• SQLCS_IMPLICIT - データベース・キャラクタ・セットID

• SQLCS_NCHAR - NCHARキャラクタ・セットID

デフォルト値はSQLCS_IMPLICITです。csfrmが指定されていない場合は、デフォルトが使用されます。

コメント

NULL属性のLOBまたはBFILEから読み取るとエラーになります。

注意:

LOBを読み取るかまたは書き込むときは、指定されたキャラクタ・セット・フォーム(csfrm)がロケータのフォームと一致している必要があります。

OCILobArrayRead()では、リモート・ロケータが渡されるとエラーがスローされます。

BFILEの場合は、オペレーティング・システム・ファイルがサーバー上に存在しており、それらのファイルは、入力ロケータを使用してOCILobFileOpen()またはOCILobOpen()によってオープンされている必要があります。オペレーティング・システム・ファイルの読取り権限がOracle Databaseにあること、およびディレクトリ・オブジェクトの読取り許可がユーザーにあることが必要です。

OCILobArrayRead()に対してポーリング・モードを使用するとき、最初のコールではoffset_arrおよびamt_arrの値を指定する必要がありますが、その後のOCILobArrayRead()のポーリング・コールではこれらの値を指定する必要はありません。

LOBがBLOBの場合、csidパラメータおよびcsfrmパラメータは無視されます。

注意:

OCILobArrayRead()操作を終了して文ハンドルを解放するには、OCIBreak()コールを使用します。

次の点は、ストリーム・モードでのLOBデータの読取りに適用されます。

• ポーリング・モードを使用する場合は、最初のOCILobArrayRead()コールでのみchar_amt_arr、byte_amt_arrおよびoffset_arrパラメータを指定してください。後続のポーリング・コールでは、これらのパラメータは無視されます。byte_amt_arrおよびchar_amt_arrの両方が0 (ゼロ)を指すように設定されており、OCI_FIRST_PIECEが渡された場合、ポーリング・モードが想定され、LOBの末尾までデータが読み取られます。出力では、byte_amt_arrは、現在のピースに読み取られるバイト数を示します。CLOBおよびNCLOBでは、char_amt_arrは現在のピースに読み取られる文字数を示します。

• コールバックを使用する場合、lenpパラメータはコールバックへの入力で、バッファ内で格納されたバイト数を示します。バッファの空き領域を確認するため、コールバック処理中にlenpパラメータをチェックします。

• ポーリングを使用する場合、byte_amt_arrパラメータを確認し、現在のピースでバッファに格納されている量を確認します。CLOBおよびNCLOBでは、char_amt_arrはバッファに読み取られる文字数も戻します。

UTF-16形式でデータを読み取るには、csidパラメータをOCI_UTF16IDに設定します。csidパラメータが設定された場合は、このパラメータによって環境変数NLS_LANGが上書きされます。

関連項目:

• Unicode形式の追加情報は、「OCIでのPL/SQL REF CURSORおよびNESTED TABLE」を参照してください

• BFILEの詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください

• LOBの読取りおよび書込み方法を示したコード例については、Oracle Databaseインストレーションに含まれているデモ・プログラムを参照してください。

• OCIデモ・プログラム

• ピース単位のOCI操作の一般情報は、「OCIでのランタイム・データ割当てとピース単位操作」を参照してください

26.3.5 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 );

パラメータ

svchp (IN/OUT)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

array_iter (IN/OUT)

IN - このパラメータは、LOBロケータ配列のサイズを指定します。ポーリングでは、このパラメータが関連するのは最初のコールのみで、後続のコールでは無視されます。

OUT - ポーリング・モードの場合に、このパラメータは書込み先の要素の配列索引を指定します。

locp_arr (IN/OUT)

LOBロケータの配列です。

byte_amt_arr (IN/OUT)

oraub8変数へのポインタの配列です。配列サイズは、ロケータの配列サイズと同じである必要があります。エントリは、ロケータのバイト数に対応します。

IN: データベースに書き込むバイト数です。BLOBでは必ず使用されます。CLOBおよびNCLOBに対しては、char_amt_arrが0 (ゼロ)の場合のみ使用されます。

OUT: データベースに書き込むバイト数です。

char_amt (IN/OUT)

oraub8変数へのポインタの配列です。配列サイズは、ロケータの配列サイズと同じである必要があります。エントリは、ロケータの文字数に対応します。

IN: データベースに書き込む最大文字数です。BLOBでは無視されます。

OUT: データベースに書き込む文字数です。BLOBでは未定義となります。

offset_arr (IN)

oraub8変数へのポインタの配列です。配列サイズは、ロケータの配列サイズと同じである必要があります。配列内の各エントリは、LOB値の先頭からの絶対オフセットです。文字LOB (CLOB、NCLOB)ではLOBの先頭からの文字数であり、BLOBではバイト数です。先頭位置は1です。

bufp_arr (IN/OUT)

ロケータのピースが書き込まれるバッファへのポインタの配列です。配列サイズは、ロケータの配列サイズと同じである必要があります。

bufl_arr (IN)

バッファ配列のバッファ長を示すoraub8変数の配列です。配列サイズは、ロケータの配列サイズと同じである必要があります。

注意:

このパラメータは8ビット(1バイト)を仮定します。現行のオペレーティング・システムでこれより長いバイトを使用している場合は、bufl_arrの値を必要に応じて調整する必要があります。

piece (IN)

書込み中のバッファのピースです。このパラメータのデフォルト値は、バッファが単独のピースとして書き込まれることを示すOCI_ONE_PIECEです。

ピース単位またはコールバック・モードで可能な他の値としては、OCI_FIRST_PIECE、OCI_NEXT_PIECEおよびOCI_LAST_PIECEがあります。

ctxp (IN)

コールバック関数用のコンテキストです。NULLにできます。

cbfp (IN)

各ピースに対してコールされるように登録できるコールバックです。これがNULLの場合は、ピースごとにOCI_NEED_DATAが戻ります。コールバック関数は、OCI_CONTINUEを戻して書込みを続行する必要があります。これ以外のエラー・コードが戻った場合、LOBの書込みは終了します。

コールバックは、次のパラメータを取ります。

ctxp (IN)

コールバック関数用のコンテキストです。NULLにできます。

array_iter (IN)

書込み先の要素の索引です。

bufp (IN/OUT)

ピース用のバッファ・ポインタです。このパラメータは、OCILobArrayWrite()ルーチンに入力として渡されるbufpと同じです。

lenp (IN/OUT)

buffer (IN)内のデータのバイト数、およびbufp (OUT)内のカレント・ピースのバイト数です。

piecep (OUT)

ピースはOCI_NEXT_PIECEまたはOCI_LAST_PIECEです。

changed_bufpp (OUT)

コールバック関数は、次に読み取るピースに新規バッファを使用することを選択した場合、新規バッファのアドレスを指定できます。このパラメータがNULLに設定されている場合、デフォルトの旧バッファbufpが使用されます。

changed_lenp (OUT)

新規バッファ(指定されている場合)の長さです。

csid (IN)

バッファ内のデータのキャラクタ・セットIDです。この値が0 (ゼロ)の場合は、csfrmの値に応じて、csidにクライアントのNLS_LANG値またはNLS_CHAR値が設定されます。

csfrm (IN)

バッファ・データのキャラクタ・セット・フォームです。csfrmパラメータは、LOBの型と一貫している必要があります。

csfrmパラメータは、0 (ゼロ)以外の次の2つの値をとることができます。

• SQLCS_IMPLICIT - データベース・キャラクタ・セットID

• SQLCS_NCHAR - NCHARキャラクタ・セットID

デフォルト値はSQLCS_IMPLICITです。

コメント

LOBにデータが存在する場合は、バッファに格納されたデータによって上書きされます。バッファは、このコールによって単独のピースとしてLOBに書き込むことも、コールバックまたは標準ポーリング・メソッドを使用してピース単位で提供することもできます。

OCILobArrayWrite()では、リモート・ロケータが渡されるとエラーがスローされます。

注意:

LOBの読取りまたは書込みを行うときは、ロケータのフォームと一致するキャラクタ・セット・フォーム(csfrm)を指定します。

piece、csidおよびcsfrmパラメータは、配列のすべてのロケータで同じです。

OCILobArrayWrite()に対してポーリング・モードを使用するとき、最初のコールではoffset_arr、byte_amt_arrおよびchar_amt_arrの値を指定する必要がありますが、その後のOCILobArrayWrite()のポーリング・コールではこれらの値を指定する必要はありません。

pieceパラメータの値がOCI_FIRST_PIECEである場合、データによっては、コールバックまたはポーリングを介して提供される必要があります。

コールバック関数がcbfpパラメータに定義されている場合は、パイプに1ピースが書き込まれるとこのコールバック関数が呼び出され、次のピースが取得されます。各ピースがbufp_arrから書き込まれます。コールバック関数が定義されていない場合、OCILobArrayWrite()は、OCI_NEED_DATAエラー・コードを戻します。LOBのピースの書込みを続けるには、アプリケーションでOCILobArrayWrite()を再度コールする必要があります。このモードでは、ピースが別々のサイズで複数の場所に読み取られる場合、コールごとにバッファ・ポインタと長さを変えることができます。

pieceパラメータの値がOCI_LAST_PIECEのときは、ポーリングまたはコールバック方式が使用されているかどうかに関係なく、ピース単位書込み操作は終了します。

(どの入力方法を使用した場合も)データベースに渡されるデータの量が、byte_amt_arrまたはchar_amt_arrパラメータに指定された量より少ない場合は、ORA-22993エラーが戻されます。

この関数は内部LOBでのみ有効です。BFILEは読取り専用なので、取り扱えません。LOBがBLOBの場合、csidパラメータおよびcsfrmパラメータは無視されます。

byte_amt_arrおよびchar_amt_arrが0 (ゼロ)を指すように設定され、OCI_FIRST_PIECEが入力として指定されている場合、ポーリング・モードが想定され、OCI_LAST_PIECEを指定するまでデータが書き込まれます。CLOBおよびNCLOBでは、byte_amt_arrおよびchar_amt_arrは、それぞれバイト数および文字数で、各ピースごとに書き込まれるデータを戻します。BLOBでは、byte_amt_arrは各ピースごとに書き込まれるバイト数を戻しますが、出力についてchar_amt_arrは未定義です。

UTF-16形式でデータを書き込むには、csidパラメータをOCI_UTF16IDに設定します。csidパラメータが設定された場合は、このパラメータによって環境変数NLS_LANGが上書きされます。

このLOB操作をオープン・コールまたはクローズ・コールで囲む必要はありません。この操作を実行する前にLOBをオープンしていない場合、LOB列のファンクション索引とドメイン索引はこのコール時に更新されます。ただし、この操作を実行する前にLOBをオープンしている場合は、トランザクションをコミットする前に、そのLOBをクローズする必要があります。内部LOBがクローズされるときに、LOB列のファンクション索引およびドメイン索引が更新されます。

LOB操作をオープンAPIまたはクローズAPIで囲んでいない場合、ファンクション索引とドメイン索引は、LOBに書き込むたびに更新されます。これにより、パフォーマンスに悪影響を及ぼす可能性があります。ファンクション索引とドメイン索引がある場合は、LOBへの書込み操作をオープン文またはクローズ文内に含めることをお薦めします。

関連項目:

• Unicode形式の追加情報は、「OCIでのPL/SQL REF CURSORおよびNESTED TABLE」を参照してください

• LOBの読取りおよび書込み方法を示したコード例については、Oracle Databaseインストレーションに含まれているデモ・プログラムを参照してください。

• OCIデモ・プログラム

• ピース単位のOCI操作の一般情報は、「OCIでのランタイム・データ割当てとピース単位操作」を参照してください

26.3.6 OCILobAssign()

LOBまたはBFILEロケータを別のロケータに割り当てます

用途

LOBまたはBFILEロケータを別のロケータに割り当てます。

構文

sword OCILobAssign ( OCIEnv                *envhp, 
                     OCIError              *errhp, 
                     const OCILobLocator   *src_locp, 
                     OCILobLocator        **dst_locpp );

パラメータ

envhp (IN/OUT)

OCI環境ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

src_locp (IN)

コピー元のLOBまたはBFILEロケータです。

dst_locpp (IN/OUT)

コピー先となるLOBまたはBFILEロケータです。コール元で、OCIDescriptorAlloc()をコールしてコピー先のロケータに領域を割り当てる必要があります。

コメント

ソース・ロケータを宛先ロケータに割り当てます。割当て後は、両方のロケータは同じLOB値を参照します。内部LOBの場合は、宛先ロケータが表に格納されているときにのみ、ソース・ロケータのLOB値が宛先ロケータのLOB値にコピーされます。したがって、宛先ロケータが格納されているオブジェクトのフラッシュを発行すると、LOB値がコピーされます。

OCILobAssign()では、リモート・ロケータが渡されるとエラーがスローされます。

OCILobAssign()は一時LOBには使用できません。OCI_INVALID_HANDLEエラーが生成されます。一時LOBには、OCILobLocatorAssign()を使用します。

BFILEでは、ファイルを参照するロケータのみが表にコピーされます。オペレーティング・システム・ファイル自体はコピーされません。

BFILEロケータを内部LOBロケータに割り当てるとエラーが発生します(逆の場合も同様)。

ソース・ロケータがバッファリング可能な内部LOB用でLOBバッファリング・サブシステムを介したLOBデータの変更に使用されており、そのバッファが書込み後フラッシュされていない場合には、ソース・ロケータが宛先ロケータに割り当てられない場合があります。これは、LOBごとに1つのロケータしかLOBバッファリング・サブシステムを介してLOBデータを変更できないためです。

入力宛先ロケータの値は、OCIDescriptorAlloc()のコールによって割り当てられている必要があります。たとえば、次のように宣言します。

OCILobLocator     *source_loc = (OCILobLocator *) 0;
OCILobLocator     *dest_loc = (OCILobLocator *) 0;

次のコード例は、アプリケーションによるsource_locロケータの割当て方法を示しています。

source_locソース・ロケータの割当て

if (OCIDescriptorAlloc((void  *) envhp, (void  **) &source_loc,
    (ub4) OCI_DTYPE_LOB, (size_t) 0, (void  **) 0))
    handle_error;

次に、表のLOBがsource_locに選択され、初期化されます。次のコード例に示すように、アプリケーションでは、OCILobAssign()コールを発行してsource_locの値をdest_locに割り当てる前に、宛先ロケータdest_locを割り当てる必要があります。

dest_loc宛先ロケータの割当て

if (OCIDescriptorAlloc((void  *) envhp, (void  **) &dest_loc,
    (ub4)OCI_DTYPE_LOB, (size_t) 0, (void  **) 0))
    handle_error;
if (OCILobAssign(envhp, errhp, source_loc, &dest_loc))
    handle_error

26.3.7 OCILobCharSetForm()

LOBロケータのキャラクタ・セット・フォームを取得します。

用途

LOBロケータのキャラクタ・セット・フォームを取得します。

構文

sword OCILobCharSetForm ( OCIEnv                *envhp, 
                          OCIError              *errhp, 
                          const OCILobLocator   *locp, 
                          ub1                   *csfrm );

パラメータ

envhp (IN/OUT)

OCI環境ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

locp (IN)

キャラクタ・セット・フォームを取得するためのLOBロケータです。

csfrm (OUT)

入力LOBロケータのキャラクタ・セット・フォームです。入力ロケータのlocpがBLOBまたはBFILE用の場合、バイナリのLOBとBFILEにはキャラクタ・セットという概念がないため、csfrmには0 (ゼロ)が設定されます。コール元では、csfrm (ub1)用の領域を割り当てる必要があります。

csfrmパラメータは、0 (ゼロ)以外の次の2つの値をとることができます。

• SQLCS_IMPLICIT - データベース・キャラクタ・セットID (デフォルト)

• SQLCS_NCHAR - NCHARキャラクタ・セットID

コメント

入力CLOBまたはNCLOBロケータのキャラクタ・セット・フォームをcsfrm出力パラメータに戻します。

26.3.8 OCILobCharSetId()

LOBロケータのデータベース・キャラクタ・セットIDを取得します。

用途

LOBロケータのデータベース・キャラクタ・セットIDを取得します。

構文

sword OCILobCharSetId ( OCIEnv                  *envhp, 
                        OCIError                *errhp, 
                        const OCILobLocator     *locp, 
                        ub2                     *csid );

パラメータ

envhp (IN/OUT)

OCI環境ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

locp (IN)

キャラクタ・セットIDを取得するためのLOBロケータです。

csid (OUT)

入力LOBロケータのデータベース・キャラクタ・セットIDです。入力ロケータがBLOBまたはBFILE用の場合、バイナリLOBまたはバイナリ・ファイルにはキャラクタ・セットという概念がないため、csidには0 (ゼロ)が設定されます。コール元は、csid ub2用の領域を割り当てる必要があります。

コメント

入力CLOBまたはNCLOBロケータのキャラクタ・セットIDをcsid出力パラメータに戻します。

26.3.9 OCILobClose()

オープンしているLOBまたはBFILEをクローズします。

用途

オープンしているLOBまたはBFILEをクローズします。

構文

sword OCILobClose ( OCISvcCtx      *svchp,
                    OCIError       *errhp, 
                    OCILobLocator  *locp );

パラメータ

svchp (IN)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

locp (IN/OUT)

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

26.3.10 OCILobCopy2()

LOB値の全体または一部を別のLOB値にコピーします。

用途

LOB値の全体または一部を別のLOB値にコピーします。4GBを超えるサイズのLOBには、この関数を使用する必要があります。4GB未満のLOBにもこの関数を使用できます。

構文

sword OCILobCopy2 ( OCISvcCtx        *svchp,
                    OCIError         *errhp,
                    OCILobLocator    *dst_locp,
                    OCILobLocator    *src_locp,
                    oraub8            amount,
                    oraub8            dst_offset,
                    oraub8            src_offset );

パラメータ

svchp (IN)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

dst_locp (IN/OUT)

一意に宛先LOBを参照する内部LOBロケータです。このロケータは、svchpに指定したサーバーから取得されたロケータにしてください。

src_locp (IN)

一意にソースLOBを参照する内部LOBロケータです。このロケータは、svchpに指定したサーバーから取得されたロケータにしてください。

amount (IN)

ソースLOBから宛先LOBにコピーされる文字数(CLOBまたはNCLOB)またはバイト数(BLOB)です。このパラメータが受け入れる最大値はUB8MAXVAL (18446744073709551615)です。UB8MAXVALを指定することは、指定されたソースおよび宛先のオフセットを使用して、ソースLOBの全体を宛先LOBにコピーすることも意味します。

dst_offset (IN)

これは、宛先LOB用の絶対オフセットです。文字LOBでは、LOBの先頭から書込みを開始する位置までの文字数です。バイナリLOBでは、LOBの先頭から書込みを開始する位置までのバイト数です。オフセットは1から始まります。

src_offset (IN)

これは、ソースLOBの絶対オフセットです。文字LOBでは、LOBの先頭からの文字数です。バイナリLOBでは、バイト数です。オフセットは1から始まります。

コメント

内部LOB値全体または一部を別の内部LOB値に指定されたとおりにコピーします。データは、ソースから宛先にコピーされます。ソース(src_locp) LOBと宛先(dst_locp) LOBが存在している必要があります。

重複除外を有効にした列またはパーティションの全SecureFileを同じ列またはパーティション内のLOBにコピーすると、コピー内容が重複除外されます。

宛先のコピー開始位置にデータが存在する場合は、ソース・データによって上書きされます。宛先のコピー開始位置がカレント・データの終了位置を超えている場合は、0 (ゼロ)バイトの充填文字(BLOBの場合)または空白(CLOBの場合)が、宛先LOBのカレント・データの末尾と、ソースから新たに書き込まれたデータの先頭との間に書き込まれます。新規に書き込むデータが宛先LOBの現行の長さよりも大きい場合、宛先LOBは、そのデータにあわせて拡張されます。許される最大長(つまり、4GB)を超える宛先LOBの拡張とNULL LOBのコピーはエラーになります。LOBのサイズが4GBを超える場合は、OCILobCopy2()を使用します。

ソースと宛先のLOBロケータは同じ型にしてください(つまり、両方ともBLOBまたは両方ともCLOB)。LOBバッファリングは、ロケータのどちらに対しても使用可能にしないでください。

この関数では、ソースまたは宛先としてのBFILEロケータを受け入れません。

このLOB操作をオープン・コールまたはクローズ・コールで囲む必要はありません。この操作を実行する前にLOBをオープンしていない場合、LOB列のファンクション索引とドメイン索引はこのコール時に更新されます。ただし、この操作を実行する前にLOBをオープンしている場合は、トランザクションをコミットする前に、そのLOBをクローズする必要があります。内部LOBがクローズされるときに、LOB列のファンクション索引およびドメイン索引が更新されます。

LOB操作をオープンAPIまたはクローズAPIで囲んでいない場合、ファンクション索引とドメイン索引は、LOBに書き込むたびに更新されます。これにより、パフォーマンスに悪影響を及ぼす可能性があります。ファンクション索引とドメイン索引がある場合は、LOBへの書込み操作をオープン文またはクローズ文内に含めることをお薦めします。

注意:

ソースLOBの長さを判断するには、OCILobGetLength2()をコールします。

26.3.11 OCILobCreateTemporary()

一時LOBを作成します。

用途

一時LOBを作成します。

構文

sword OCILobCreateTemporary(OCISvcCtx          *svchp,
                            OCIError           *errhp,
                            OCILobLocator      *locp,
                            ub2                 csid,
                            ub1                 csfrm,
                            ub1                 lobtype,
                            boolean             cache,
                            OCIDuration         duration);

パラメータ

svchp (IN)

OCIサービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

locp (IN/OUT)

一時LOBを指し示すロケータです。ロケータをこの関数に渡す前に、OCIDescriptorAlloc()を使用してロケータを割り当てる必要があります。このロケータは、LOBを指し示しているかどうかに関係なく、いずれの場合も一時LOBにより上書きされます。

csid (IN)

LOBキャラクタ・セットIDです。Oracle8i以上ではOCI_DEFAULTを渡します。

csfrm (IN)

バッファ・データのLOBキャラクタ・セット・フォームです。csfrmパラメータは、0 (ゼロ)以外の次の2つの値をとることができます。

• SQLCS_IMPLICIT - CLOBを作成するためのデータベース・キャラクタ・セットID。OCI_DEFAULTを使用して、CLOBを暗黙的に作成することもできます。

• SQLCS_NCHAR - NCLOBを作成するためのNCHARキャラクタ・セットID。

デフォルト値はSQLCS_IMPLICITです。

lobtype (IN)

作成するLOBの型です。次の値が有効です。

• OCI_TEMP_BLOB - 一時BLOBの場合

• OCI_TEMP_CLOB - 一時CLOBまたはNCLOBの場合

cache (IN)

一時LOBをキャッシュに読み取る必要がある場合はTRUEを、その必要がない場合はFALSEを渡します。NOCACHE機能の場合、デフォルトはFALSEです。

duration (IN)

一時LOBの継続時間です。次に示す値が有効です。

• OCI_DURATION_SESSION

• OCI_DURATION_CALL

コメント

この関数は、ユーザーの一時表領域に一時LOBとそれに対応する索引を作成します。

この関数が完了すると、locpパラメータは、長さが0 (ゼロ)の空の一時LOBを指し示します。

一時LOBの存続期間は、durationパラメータによって決まります。一時LOBは、この期間の最後に解放されます。アプリケーションからOCILobFreeTemporary()コールを使用すると、一時LOBをより早く解放できます。

LOBがBLOBの場合、csidパラメータおよびcsfrmパラメータは無視されます。

関連項目:

一時LOBとその継続時間の詳細は、「一時LOBのサポート」を参照してください

26.3.12 OCILobErase2()

内部LOBデータの一部を指定のオフセットの位置から消去します。

用途

内部LOBデータの一部を指定のオフセットの位置から消去します。4GBを超えるサイズのLOBには、この関数を使用する必要があります。4GB未満のLOBにもこの関数を使用できます。

構文

sword OCILobErase2 ( OCISvcCtx       *svchp,
                     OCIError        *errhp,
                     OCILobLocator   *locp,
                     oraub8          *amount,
                     oraub8           offset );

パラメータ

svchp (IN)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

locp (IN/OUT)

一意にLOBを参照する内部LOBロケータです。このロケータは、svchpに指定したサーバーから取得されたロケータにしてください。

amount (IN/OUT)

消去する文字数(CLOBまたはNCLOBの場合)またはバイト数(BLOBの場合)です。INでは、値は消去する文字数またはバイト数を表します。OUTでは、値は消去された実際の文字数またはバイト数です。

offset (IN)

データの消去を開始するLOB値の、先頭からの絶対オフセット(CLOBまたはNCLOBの場合は文字数、BLOBの場合はバイト数)です。オフセットは1から始まります。

コメント

実際に消去した文字数またはバイト数が戻ります。BLOBの場合、消去するということは、0 (ゼロ)バイトの充填文字で既存のLOB値を上書きするということです。CLOBの場合は、既存のLOB値が空白で上書きされます。

この関数は内部LOBにのみ有効で、BFILEには使用できません。

このLOB操作をオープン・コールまたはクローズ・コールで囲む必要はありません。この操作を実行する前にLOBをオープンしていない場合、LOB列のファンクション索引とドメイン索引はこのコール時に更新されます。ただし、この操作を実行する前にLOBをオープンしている場合は、トランザクションをコミットする前に、そのLOBをクローズする必要があります。内部LOBがクローズされるときに、LOB列のファンクション索引およびドメイン索引が更新されます。

LOB操作をオープンAPIまたはクローズAPIで囲んでいない場合、ファンクション索引とドメイン索引は、LOBに書き込むたびに更新されます。これにより、パフォーマンスに悪影響を及ぼす可能性があります。ファンクション索引とドメイン索引がある場合は、LOBへの書込み操作をオープン文またはクローズ文内に含めることをお薦めします。

26.3.13 OCILobFileClose()

オープンしているBFILEをクローズします。

用途

オープンしているBFILEをクローズします。

構文

sword OCILobFileClose ( OCISvcCtx            *svchp,
                        OCIError             *errhp,
                        OCILobLocator        *filep );

パラメータ

svchp (IN)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

filep (IN/OUT)

クローズするBFILEを参照するBFILEロケータへのポインタです。

コメント

オープンしているBFILEをクローズします。内部LOBに対してこの関数をコールするとエラーになります。BFILEは存在しているが、オープンしていない場合、エラーは戻りません。

この関数は、特定のBFILEロケータに対して初めてコールしたときにかぎり有効です。同じBFILEロケータを使用してこの関数を続けてコールしても何も行われません。

関連項目:

BFILEの詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください

26.3.14 OCILobFileCloseAll()

指定のサービス・コンテキストでオープンしているすべてのBFILEをクローズします。

用途

指定のサービス・コンテキストでオープンしているすべてのBFILEをクローズします。

構文

sword OCILobFileCLoseAll ( OCISvcCtx   *svchp,
                           OCIError    *errhp );

パラメータ

svchp (IN)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

コメント

指定のサービス・コンテキストでオープンしているすべてのBFILEをクローズします。

関連項目:

BFILEの詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください

26.3.15 OCILobFileExists()

サーバーのオペレーティング・システムにBFILEが存在するかどうかをテストします。

用途

サーバーのオペレーティング・システムにBFILEが存在するかどうかをテストします。

構文

sword OCILobFileExists ( OCISvcCtx        *svchp,
                         OCIError         *errhp,
                         OCILobLocator    *filep,
                         boolean          *flag );

パラメータ

svchp (IN)

OCIサービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

filep (IN)

ファイルを参照するBFILEロケータへのポインタです。

flag (OUT)

サーバーにBFILEが存在する場合はTRUEを、存在しない場合はFALSEを戻します。

コメント

サーバーのファイル・システムにBFILEが存在するかどうかをチェックします。内部LOBに対してこの関数をコールするとエラーになります。

関連項目:

BFILEの詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください

26.3.16 OCILobFileGetName()

BFILEロケータのディレクトリ・オブジェクトおよびファイル名を取得します。

用途

BFILEロケータのディレクトリ・オブジェクトおよびファイル名を取得します。

構文

sword OCILobFileGetName ( OCIEnv                   *envhp,
                          OCIError                 *errhp, 
                          const OCILobLocator      *filep, 
                          OraText                  *dir_alias,
                          ub2                      *d_length, 
                          OraText                  *filename, 
                          ub2                      *f_length );

パラメータ

envhp (IN/OUT)

OCI環境ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

filep (IN)

ディレクトリ・オブジェクトおよびファイル名を取得するためのBFILEロケータです。

dir_alias (OUT)

ディレクトリ・オブジェクトが配置されているバッファです。これはUTF-16で可能です。ディレクトリ・オブジェクト用の十分な領域を割り当てる必要があります。ディレクトリ・オブジェクトの最大長は30バイトです。

d_length (IN/OUT)

次の用途に使用できます(Unicodeのコードポイントまたはバイト単位が可能です)。

• IN: 入力dir_alias文字列の長さ

• OUT: 戻されるdir_alias文字列の長さ

filename (OUT)

ファイル名が配置されているバッファです。ファイル名用の十分な領域を割り当てる必要があります。ファイル名の最大長は255バイトです。

f_length (IN/OUT)

次の用途に使用できます(バイト数単位)。

• IN: 入力filenameバッファの長さ

• OUT: 戻されるfilename文字列の長さ

コメント

このBFILEロケータに対応付けられたディレクトリ・オブジェクトとファイル名を戻します。環境ハンドルによって、Unicodeかどうかが判断されます。内部LOBに対してこの関数をコールするとエラーになります。

関連項目:

BFILEの詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください

26.3.17 OCILobFileIsOpen()

BFILEがオープンしているかどうかをテストします。

用途

BFILEがオープンしているかどうかをテストします。

構文

sword OCILobFileIsOpen ( OCISvcCtx        *svchp,
                         OCIError         *errhp,
                         OCILobLocator    *filep,
                         boolean          *flag );

パラメータ

svchp (IN)

OCIサービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

filep (IN)

確認するBFILEロケータへのポインタです。

flag (OUT)

この特定のロケータを使用してBFILEがオープンされた場合はTRUEを、オープンされなかった場合はFALSEを戻します。

コメント

サーバー上のファイルがfilep BFILEロケータを使用してオープンされたかどうかをチェックします。内部LOBに対してこの関数をコールするとエラーになります。

OCILobFileOpen()またはOCILobOpen()コマンドに入力BFILEロケータが渡されなかった場合、ファイルはそのロケータによってオープンされていないとみなされます。ただし、別のロケータがそのファイルをオープンしていることがあります。オープンは、特定のロケータに対応付けられます。

関連項目:

BFILEの詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください

26.3.18 OCILobFileOpen()

読取り専用アクセス用にサーバーのファイル・システム上のBFILEをオープンします。

用途

読取り専用アクセス用にサーバーのファイル・システム上のBFILEをオープンします。

構文

sword OCILobFileOpen ( OCISvcCtx            *svchp,
                       OCIError             *errhp,
                       OCILobLocator        *filep,
                       ub1                   mode );

パラメータ

svchp (IN)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

filep (IN/OUT)

オープンするBFILEです。ロケータがBFILEを参照していない場合はエラーが発生します。

mode (IN)

ファイルをオープンするモードです。有効なモードはOCI_FILE_READONLYのみです。

コメント

サーバーのファイル・システムのBFILEをオープンします。BFILEは、読取り専用アクセス用にオープンできます。BFILEは、Oracle Databaseを通して書き込むことはできません。内部LOBに対してこの関数をコールするとエラーになります。

この関数は、特定のBFILEロケータに対して初めてコールしたときにかぎり有効です。同じBFILEロケータを使用してこの関数を続けてコールしても何も行われません。

関連項目:

BFILEの詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください

26.3.19 OCILobFileSetName()

BFILEロケータ内にディレクトリ・オブジェクトとファイル名を設定します。

用途

BFILEロケータ内にディレクトリ・オブジェクトとファイル名を設定します。

構文

sword OCILobFileSetName ( OCIEnv             *envhp,
                          OCIError           *errhp,
                          OCILobLocator     **filepp,
                          const OraText      *dir_alias,
                          ub2                 d_length, 
                          const OraText      *filename, 
                          ub2                 f_length );

パラメータ

envhp (IN/OUT)

OCI環境ハンドルです。UTF-16設定が含まれます。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

filepp (IN/OUT)

ディレクトリ・オブジェクトおよびファイル名を設定するBFILEロケータへのポインタです。

dir_alias (IN)

BFILEロケータに設定するディレクトリ・オブジェクト名(OCIEnvNlsCreate()の直前のコールのcharsetパラメータで指定されたエンコーディングが必要)が含まれたバッファです。

d_length (IN)

入力dir_aliasパラメータの長さ(バイト単位)です。

filename (IN)

BFILEロケータに設定するファイル名(OCIEnvNlsCreate()の直前のコールのcharsetパラメータで指定されたエンコーディングが必要)が含まれたバッファです。

f_length (IN)

入力filenameパラメータの長さ(バイト単位)です。

コメント

内部LOBに対してこの関数をコールするとエラーになります。

関連項目:

BFILEの詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください

26.3.20 OCILobFreeTemporary()

一時LOBを解放します。

用途

一時LOBを解放します。

構文

sword OCILobFreeTemporary( OCISvcCtx          *svchp,
                           OCIError           *errhp,
                           OCILobLocator      *locp);

パラメータ

svchp (IN/OUT)

OCIサービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

locp (IN/OUT)

解放するLOBを一意に参照するロケータです。

コメント

このロケータが指し示す一時LOBの内容を解放します。ロケータ自体は、OCIDescriptorFree() がコールされるまで解放されません。OCIDescriptorFree()またはOCIArrayDescriptorFree()をコールする前に必ずOCILobFreeTemporary()をコールして、一時LOBの内容を解放する必要があります。詳細は、「一時LOBの解放について」を参照してください。

locpパラメータで渡されるLOBロケータが一時LOBを指し示していない場合は、エラーを戻します。LOBロケータが次のようであることが原因である可能性があります。

• 永続LOBを指し示しています。

• 解放された一時LOBを指し示しています。

• 何も指し示していません。

26.3.21 OCILobGetChunkSize()

LOBのチャンク・サイズを取得します。

用途

LOBのチャンク・サイズを取得します。

構文

sword OCILobGetChunkSize ( OCISvcCtx       *svchp,
                           OCIError        *errhp,
                           OCILobLocator   *locp,
                           ub4             *chunk_size );

パラメータ

svchp (IN)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

locp (IN/OUT)

使用可能なチャンク・サイズを取得する内部LOBです。

chunk_size (OUT)

記憶域パラメータ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コールを十分な数だけまとめることができます。

関連項目:

LOBの読取り/書込みパフォーマンスの向上について

26.3.22 OCILobGetContentType()

SecureFile内のデータのユーザー指定コンテンツ・タイプ文字列を取得します(設定されている場合)。

用途

SecureFile内のデータのユーザー指定コンテンツ・タイプ文字列を取得します(設定されている場合)。

構文

sword OCILobGetContentType ( OCIEnv         *envhp, 
                             OCISvcCtx      *svchp,  
                             OCIError       *errhp, 
                             OCILobLocator  *lobp, 
                             oratext        *contenttypep, 
                             ub4            *contenttypelenp,
                             ub4             mode );

パラメータ

envhp (IN)

環境ハンドルです。

svchp (IN)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

lobp (IN)

一意にLOBを参照するLOBロケータです。

contenttypep (IN/OUT)

正常に実行された後、コンテンツ・タイプが格納されるバッファへのポインタです。この関数をコールする前に、バッファを割り当てる必要があります。割当てバッファのサイズは>= OCI_LOB_CONTENTTYPE_MAXSIZEであることが必要です。

contenttypelenp (IN/OUT)

このフィールドをcontenttypepバッファのサイズに設定します。コールが正常に実行された後、このフィールドは、戻されたcontenttypepのサイズを保持します。

mode (IN)

今後の使用のために確保されています。現時点では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)です。

26.3.23 OCILobGetLength2()

LOBの長さを取得します。4GBを超えるサイズのLOBには、この関数を使用する必要があります。

用途

4GB未満のLOBにもこの関数を使用できます。

構文

sword OCILobGetLength2 ( OCISvcCtx      *svchp,
                         OCIError       *errhp,
                         OCILobLocator  *locp,
                         oraub8         *lenp );

パラメータ

svchp (IN)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

locp (IN)

一意にLOBを参照するLOBロケータです。内部LOBでは、このロケータは、svchpに指定したサーバーから取得されたロケータにしてください。BFILEの場合は、OCILobFileSetName()、SELECT文またはOCIObjectPin()を使用してロケータを設定できます。

lenp (OUT)

出力時、LOBがNULLではない場合、LOBの長さを示します。文字LOBでは文字数であり、バイナリLOBおよびBFILEではLOBのバイト数です。

コメント

LOBの長さを取得します。LOBがNULLの場合、長さは未定義です。BFILEの長さにはEOF (存在する場合)が含まれます。空の内部LOBの長さは0 (ゼロ)です。

クライアント側のキャラクタ・セットが可変幅かどうかに関係なく、出力の長さは、CLOBとNCLOBでは文字数、BLOBとBFILEではバイト数です。

注意:

以前のOCILobErase2()またはOCILobWrite2()のコールによってLOBに書き込まれた0 (ゼロ)バイトや空白の充填文字も、長さの一部になります。

26.3.24 OCILobGetOptions()

指定のSecureFile LOBについて指定の入力オプション・タイプに対応する、有効化された設定を取得します。

用途

指定のSecureFile LOBについて指定の入力オプション・タイプに対応する、有効化された設定を取得します。

構文

sword OCILobGetOptions ( OCISvcCtx         *svchp,
                         OCIError          *errhp,
                         OCILobLocator     *locp,
                         ub4                option_types,
                         void              *optionsp,
                         ub4                optionslenp,
                         ub4                mode );

パラメータ

svchp (IN/OUT)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

locp (IN/OUT)

一意にLOBまたはBFILEを参照するLOBロケータまたはBFILEロケータです。このロケータは、svchpに指定したサーバーから取得されるようにしてください。

option_types (IN)

ビット単位の包含OR (記号「|」)で結合可能な指定のオプション・タイプです。

• 圧縮: OCI_LOB_OPT_COMPRESS

• 暗号化: OCI_LOB_OPT_ENCRYPT

• 重複除外: OCI_LOB_OPT_DEDUPLICATE

optionsp (OUT)

指定の各オプション・タイプの現行設定です。可能な値は次のとおりです。

• OCI_LOB_OPT_COMPRESS_ON

• OCI_LOB_OPT_ENCRYPT_ON

• OCI_LOB_OPT_DEDUPLICATE_ON

optionslenp (OUT)

optionspで示した値の長さです。

mode (IN)

将来の使用のために予約されています。0 (ゼロ)を渡します。

コメント

指定できるのは、列で有効化されているオプション・タイプのみです。列で有効化されていないオプション・タイプの値を取得しようとすると、エラーが戻されます。たとえば、圧縮が有効化されているLOB列があり、option_typesパラメータにOCI_LOB_OPT_ENCRYPTを設定してOCILobGetOptions()をコールすると、エラーが発生します。

戻り値はvoidポインタとしてキャストされたub4ポインタであり、今後のオプション・タイプおよび値の拡張が可能です。戻されるoptionslenpはsizeof(ub4)である必要があります。

26.3.25 OCILobGetStorageLimit()

内部LOB (BLOB、CLOBまたはNCLOB)の最大長(バイト単位)を取得します。

用途

内部LOB (BLOB、CLOBまたはNCLOB)の最大長(バイト単位)を取得します。

構文

sword OCILobGetStorageLimit ( OCISvcCtx      *svchp,
                              OCIError       *errhp,
                              OCILobLocator  *locp,
                              oraub8         *limitp );

パラメータ

svchp (IN)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

locp (IN)

一意にLOBを参照するLOBロケータです。このロケータは、svchpに指定したサーバーから取得されたロケータにしてください。

limitp (OUT)

データベースに格納できるLOBの最大長(バイト単位)です。

コメント

ブロック・サイズの範囲は2から32KBであるため、LOBの場合、最大LOBサイズの範囲は8から128TBです。

26.3.26 OCILobIsEqual()

2つのLOBまたはBFILEロケータの等価を比較します。

用途

2つのLOBまたはBFILEロケータの等価を比較します。

構文

sword OCILobIsEqual ( OCIEnv                  *envhp,
                      const OCILobLocator     *x,
                      const OCILobLocator     *y,
                      boolean                 *is_equal );

パラメータ

envhp (IN)

OCI環境ハンドルです。

x (IN)

比較するLOBロケータです。

y (IN)

比較するLOBロケータです。

is_equal (OUT)

LOBロケータが等価の場合はTRUE、等価でない場合はFALSEです。

コメント

指定されたLOBまたはBFILEロケータの等価を比較します。2つのLOBまたはBFILEロケータは、どちらも同じLOBまたはBFILE値を参照している場合のみ等価になります。

この関数では、2つのNULLロケータは等価とはみなされません。

26.3.27 OCILobIsOpen()

LOBまたはBFILEがオープンされているかどうかを確認します。

用途

LOBまたはBFILEがオープンされているかどうかを確認します。

構文

sword OCILobIsOpen ( OCISvcCtx        *svchp,
                     OCIError         *errhp, 
                     OCILobLocator    *locp, 
                     boolean          *flag );

パラメータ

svchp (IN)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

locp (IN)

確認するLOBロケータへのポインタです。ロケータは、内部LOBまたは外部LOBを参照できます。

flag (OUT)

内部LOBがオープンされている場合、または入力ロケータを使用してBFILEがオープンされた場合は、TRUEを戻します。それ以外はFALSEを戻します。

コメント

内部LOBがオープンされているかどうか、またはBFILEが入力ロケータを使用してオープンされているかどうかをチェックします。

BFILEの場合

入力BFILEロケータがOCILobOpen()またはOCILobFileOpen()に渡されていない場合は、このBFILEロケータによってBFILEはオープンされないとみなされます。ただし、別のBFILEロケータによってBFILEがオープンされている場合はあります。別のロケータを使用して、そのBFILEに対して複数のオープンが実行されることがあります。つまり、オープンはBFILEの特定のロケータに関連付けられています。

内部LOBの場合

オープンは、ロケータではなくLOBに関連付けられます。locator1がLOBをオープンした場合は、locator2もオープン時にそのLOBを参照します。

内部LOBの場合、このコールでは、サーバー上の状態によって、LOBがオープンしているかどうかを確認するため、サーバー・ラウンドトリップが必要です。外部LOB (BFILE)の場合も、サーバー側のオペレーティング・システム・ファイルによってそのLOBがオープンされているかどうかを確認するため、ラウンドトリップが必要です。

26.3.28 OCILobIsTemporary()

ロケータが一時LOBを指し示しているかどうかを確認します。

用途

ロケータが一時LOBを指し示しているかどうかを確認します。

構文

sword OCILobIsTemporary(OCIEnv            *envhp,
                        OCIError          *errhp,
                        OCILobLocator     *locp,
                        boolean           *is_temporary);

パラメータ

envhp (IN)

OCI環境ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

locp (IN)

確認するロケータです。

is_temporary (OUT)

ロケータが一時LOBを指し示している場合はTRUEを、そうでない場合はFALSEを戻します。

コメント

この関数は、ロケータが一時LOBを指し示しているかどうかを調べるためにロケータを確認します。指し示している場合は、is_temporaryがTRUEに設定されます。そうでない場合は、is_temporaryがFALSEに設定されます。

26.3.29 OCILobLoadFromFile2()

ファイルの全体または一部を内部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 ); 

パラメータ

svchp (IN)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

dst_locp (IN/OUT)

BLOB型、CLOB型またはNCLOB型の宛先内部LOBを一意に参照するロケータです。

src_locp (IN/OUT)

ソースBFILEを一意に参照するロケータです。

amount (IN)

ロードされるバイト数です。

dst_offset (IN)

これは、宛先LOB用の絶対オフセットです。文字LOBでは、LOBの先頭から書込みを開始する位置までの文字数です。バイナリLOBでは、LOBの先頭から読取りを開始する位置までのバイト数です。オフセットは1から始まります。

src_offset (IN)

これは、ソースBFILEの絶対オフセットです。BFILEの先頭からのバイト数です。オフセットは1から始まります。

コメント

BFILE値の一部またはすべてを指定どおりに内部LOBにロードおよびコピーします。データは、ソースBFILEから宛先の内部LOB (BLOBまたはCLOB)にコピーされます。BFILEデータをCLOBまたはNCLOBにコピーするときに、キャラクタ・セットの変換は実行されません。バイナリ・データがBLOBにロードされるときにも、キャラクタ・セット変換は実行されません。このため、BFILEデータは、データベースのLOBと同じキャラクタ・セットにする必要があります。これを検証するためのエラー・チェックは実行されません。

OCILobLoadFromFile2()では、リモート・ロケータが渡されるとエラーがスローされます。

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

26.3.30 OCILobLocatorAssign()

LOBまたはBFILEロケータを別のロケータに割り当てます。

用途

LOBまたはBFILEロケータを別のロケータに割り当てます。

構文

sword OCILobLocatorAssign ( OCISvcCtx              *svchp,
                            OCIError               *errhp,
                            const OCILobLocator    *src_locp,
                            OCILobLocator         **dst_locpp );

パラメータ

svchp (IN/OUT)

OCIサービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

src_locp (IN)

コピー元のLOBまたはBFILEロケータです。

dst_locpp (IN/OUT)

コピー先となるLOBまたはBFILEロケータです。コール元で、OCIDescriptorAlloc()をコールしてOCILobLocatorに領域を割り当てる必要があります。

コメント

このコールは、ソース・ロケータを宛先ロケータに割り当てます。割当て後は、両方のロケータは同じLOBデータを参照します。内部LOBの場合は、宛先ロケータが表に格納されているときのみ、ソース・ロケータのLOBデータが宛先ロケータのLOBデータにコピーされます。このため、宛先ロケータが含まれているオブジェクトにフラッシュを発行すると、LOBデータがコピーされます。BFILEの場合、オペレーティング・システム・ファイルを参照するロケータのみが表にコピーされ、オペレーティング・システム・ファイルはコピーされません。

OCILobLocatorAssign()では、リモート・ロケータが渡されるとエラーがスローされます。

このコールは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ロケータを参照するようにします。

26.3.31 OCILobLocatorIsInit()

指定されたLOBまたはBFILEロケータが初期化されているかどうかをテストします。

用途

指定されたLOBまたはBFILEロケータが初期化されているかどうかをテストします。

構文

sword OCILobLocatorIsInit ( OCIEnv               *envhp,
                            OCIError             *errhp,
                            const OCILobLocator  *locp,
                            boolean              *is_initialized );

パラメータ

envhp (IN/OUT)

OCI環境ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

locp (IN)

確認するLOBまたはBFILEロケータです。

is_initialized (OUT)

特定のLOBまたはBFILEロケータが初期化されているとTRUE、初期化されていないとFALSEを戻します。

コメント

指定されたLOBまたはBFILEロケータが初期化されているかどうかをテストします。

内部LOBロケータは、次のいずれかの方法で初期化できます。

• NULL以外のLOBをロケータに選択します。

• OCIObjectPin()を使用して、LOB属性がNULL以外のオブジェクトを確保します。

• OCIAttrSet()を使用して、ロケータをEmpty値に設定します。

  関連項目:

  LOB記述子属性およびLOBロケータ属性

BFILEロケータは、次のいずれかの方法で初期化できます。

• NULL以外のBFILEをロケータに選択します。

• OCIObjectPin()を使用して、BFILE属性がNULL以外のオブジェクトを確保します。

• OCILobFileSetName()をコールします

26.3.32 OCILobOpen()

指定されたモードでLOB (内部または外部)をオープンします。

用途

指定されたモードでLOB (内部または外部)をオープンします。

構文

sword OCILobOpen ( OCISvcCtx        *svchp,
                   OCIError         *errhp, 
                   OCILobLocator    *locp, 
                   ub1               mode );

パラメータ

svchp (IN)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

locp (IN/OUT)

オープンするLOBです。ロケータは、内部LOBまたは外部LOBを参照できます。

mode (IN)

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

26.3.33 OCILobRead2()

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 );

パラメータ

svchp (IN/OUT)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

locp (IN)

一意にLOBまたはBFILEを参照するLOBまたはBFILEロケータです。このロケータは、svchpに指定したサーバーから取得されたロケータにしてください。

byte_amtp(IN/OUT)

IN: データベースから読み取るバイト数です。BLOBおよびBFILEに対して常に使用されます。CLOBおよびNCLOB,に対しては、char_amtpが0 (ゼロ)の場合のみ使用されます。

OUT: ユーザー・バッファに読み取られるバイト数です。

char_amtp(IN/OUT)

IN: ユーザー・バッファに読み取られる最大文字数です。BLOBおよびBFILEの場合は無視されます。

OUT: ユーザー・バッファに読み取られる文字数です。BLOBおよびBFILEの場合は未定義になります。

offset (IN)

入力時、これはLOB値の先頭からの絶対オフセットです。文字LOB (CLOB、NCLOB)ではLOBの先頭からの文字数であり、バイナリLOBまたはBFILEではバイト数です。先頭位置は1です。

ポーリングまたはコールバックによるストリームを使用する場合は、最初のコールでオフセットを指定します。後続のポーリング・コールでは、offsetパラメータは無視されます。コールバックを使用する場合、offsetパラメータはありません。

bufp (IN/OUT)

ピースの読取り先バッファへのポインタです。buflのメモリー長が割り当てられるとみなされます。

bufl (IN)

オクテットで示したバッファの長さです。buflパラメータがバイト数で指定され、amtpパラメータが文字で指定されている場合、この値は、CLOBおよびNCLOBのamtp値(csfrm=SQLCS_NCHAR)とは異なります。

piece (IN)

OCI_ONE_PIECE: コールではポーリングは想定されません。示された量がバッファ長より大きい場合、バッファには可能なかぎり格納されます。

ポーリングでは、最初にOCI_FIRST_PIECE、後続のコールでOCI_NEXT_PIECEを渡します。OCI_FIRST_PIECEはコールバックの使用時に渡される必要があります。

ctxp (IN)

コールバック関数用のコンテキスト・ポインタです。NULLにできます。

cbfp (IN)

各ピースに対してコールされるように登録できるコールバックです。これがNULLの場合は、ピースごとにOCI_NEED_DATAが戻ります。

コールバック関数は、OCI_CONTINUEを戻して読取りを続行する必要があります。これ以外のエラー・コードが戻った場合、LOBの読取りは終了します。

ctxp (IN)

コールバック関数用のコンテキストです。NULLにできます。

bufp (IN/OUT)

ピース用のバッファ・ポインタです。

lenp (IN)

bufpにおけるカレント・ピースのバイト長です。

piecep (IN)

ピースは、OCI_FIRST_PIECE、OCI_NEXT_PIECEまたはOCI_LAST_PIECEです。

changed_bufpp (OUT)

コールバック関数は、次に読み取るピースに新規バッファを使用することを選択した場合、新規バッファのアドレスを指定できます。このパラメータがNULLに設定されている場合、デフォルトの旧バッファbufpが使用されます。

changed_lenp (OUT)

新規バッファ(指定されている場合)の長さです。

csid (IN)

バッファ・データのキャラクタ・セットIDです。この値が0 (ゼロ)の場合は、csfrmの値に応じて、csidにクライアントのNLS_LANG値またはNLS_CHAR値が設定されます。サーバーとクライアントの設定が同一である場合を除き、サーバーのキャラクタ・セットとはみなされません。

csfrm (IN)

バッファ・データのキャラクタ・セット・フォームです。csfrmパラメータは、LOBの型と一貫している必要があります。

csfrmパラメータは、0 (ゼロ)以外の次の2つの値をとることができます。

• SQLCS_IMPLICIT - データベース・キャラクタ・セットID

• SQLCS_NCHAR - NCHARキャラクタ・セットID

デフォルト値はSQLCS_IMPLICITです。csfrmが指定されていない場合は、デフォルトが使用されます。

コメント

LOBまたはBFILEの一部をコールの指定どおりにバッファに読み取ります。NULL属性のLOBまたはBFILEから読み取るとエラーになります。

注意:

LOBの読取りまたは書込みを行うときは、ロケータのフォームと一致するキャラクタ・セット・フォーム(csfrm)を指定します。

BFILEの場合は、オペレーティング・システム・ファイルがサーバー上に存在しており、それらのファイルは、入力ロケータを使用してOCILobFileOpen()またはOCILobOpen()によってオープンされている必要があります。オペレーティング・システム・ファイルの読取り権限がOracle Databaseにあること、およびディレクトリ・オブジェクトの読取り許可がユーザーにあることが必要です。

OCILobRead2()に対してポーリング・モードを使用するとき、最初のコールではoffsetおよびamtpの値を指定する必要がありますが、その後のOCILobRead2()のポーリング・コールではこれらの値を指定する必要はありません。

LOBがBLOBの場合、csidパラメータおよびcsfrmパラメータは無視されます。

注意:

OCILobRead2()操作を終了して文ハンドルを解放するには、OCIBreak()コールを使用します。

次の点は、ストリーム・モードでのLOBデータの読取りに適用されます。

• ポーリング・モードを使用する場合は、最初のOCILobRead2()コールでchar_amtp、byte_amtpおよびoffsetパラメータを指定してください。後続のポーリング・コールでは、これらのパラメータは無視されます。byte_amtpおよびchar_amtpの両方が0 (ゼロ)を指すように設定されており、OCI_FIRST_PIECEが渡された場合、ポーリング・モードが想定され、LOBの末尾までデータが読み取られます。出力では、byte_amtpは、現在のピースに読み取られるバイト数を示します。

  CLOBおよびNCLOBでは、char_amtpは現在のピースに読み取られる文字数を示します。

  CLOBおよびNCLOBでは、char_amtpを渡さないとchar_amtpはbyte_amtp/max char widthとして内部的に計算されるため、max char widthが4の場合、char_amtpはbyte_amtp/4として計算されます。このため、OCILobRead2()では文字ごとに必要なバイト数を計算しません。かわりに、OCILobRead2()は、byte_amtpに格納可能な文字数を最悪の場合にフェッチします。バッファを埋めるには、byte_amtpパラメータを確認してバッファに格納されている量を確認してから、もう一度OCILobRead2()をコールして残りのバイトをフェッチします。

• コールバックを使用する場合、lenパラメータはコールバックへの入力で、バッファ内で格納されたバイト数を示します。バッファの空き領域を確認するため、コールバック処理中にlenパラメータをチェックします。

• ポーリングを使用する場合、byte_amtpパラメータを参照し、現在のピースでバッファに格納されている量を確認します。CLOBおよびNCLOBでは、char_amtpはバッファに読み取られる文字数も戻します。

UTF-16形式でデータを読み取るには、csidパラメータをOCI_UTF16IDに設定します。csidパラメータが設定された場合は、このパラメータによって環境変数NLS_LANGが上書きされます。

関連項目:

• Unicode形式の追加情報は、「OCIでのPL/SQL REF CURSORおよびNESTED TABLE」を参照してください

• BFILEの詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください

• LOBの読取りおよび書込み方法を示したコード例については、Oracle Databaseインストレーションに含まれているデモ・プログラムを参照してください。

• OCIデモ・プログラム

• ピース単位のOCI操作の一般情報は、「OCIでのランタイム・データ割当てとピース単位操作」を参照してください

• OCIでのポーリング・モード操作

26.3.34 OCILobSetContentType()

SecureFile内のデータのコンテンツ・タイプ文字列を、アプリケーションで使用できるものに設定します。

用途

SecureFile内のデータのコンテンツ・タイプ文字列を、アプリケーションで使用できるものに設定します。

構文

sword OCILobSetContentType ( OCIEnv        *envhp, 
                             OCISvcCtx     *svchp, 
                             OCIError      *errhp, 
                             OCILobLocator *lobp, 
                             const oratext *contenttypep, 
                             ub4            contenttypelen,
                             ub4            mode);

パラメータ

envhp (IN)

環境ハンドルです。

svchp (IN)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

lobp (IN)

一意にLOBを参照するLOBロケータです。

contenttypep (IN)

指定のLOBに対して設定されるcontenttypeです。

contenttypelen (IN)

バイトで示したcontenttypeのサイズです。このサイズはOCI_LOB_CONTENTTYPE_MAXSIZEバイト以下であることが必要です。

mode (IN)

今後の使用のために確保されています。現時点では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()をコールします。

26.3.35 OCILobSetOptions()

SecureFile LOBのオプション設定を有効化します。

用途

SecureFile LOBのオプション設定を有効化します。

構文

sword OCILobSetOptions ( OCISvcCtx       *svchp,
                         OCIError        *errhp,
                         OCILobLocator   *locp,
                         ub4              option_types,
                         void            *optionsp,
                         ub4              optionslen,
                         ub4              mode );

パラメータ

svchp (IN/OUT)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

locp (IN/OUT)

一意にLOBを参照するLOBロケータです。このロケータは、svchpに指定したサーバーから取得されたロケータにしてください。

option_types (IN)

ビット単位の包含OR (「|」)を使用して、複数のオプション・タイプと値を指定できます。LOB列で有効化されていないoption_types値を指定すると、エラーになります。

• 圧縮: OCI_LOB_OPT_COMPRESS

• 暗号化: OCI_LOB_OPT_ENCRYPT

• 重複除外: OCI_LOB_OPT_DEDUPLICATE

• 割当てサイズ: OCI_LOB_OPT_ALLOCSIZE

• コンテンツ・タイプ: OCI_LOB_OPT_CONTENTTYPE

• 変更時間: OCI_LOB_OPT_MODTIME

optionsp (IN)

可能な設定は、次のとおりです。

• OCI_LOB_OPT_COMPRESS_OFF

• OCI_LOB_OPT_COMPRESS_ON

• OCI_LOB_ENCRYPT_OFF

• OCI_LOB_ENCRYPT_ON

• OCI_LOB_OPT_DEDUPLICATE_OFF

• OCI_LOB_OPT_DEDUPLICATE_ON

optionslen (IN)

optionspで示した値の長さです。この時点で有効な長さはsizeof(ub4)のみです。

mode (IN)

将来の使用のために予約されています。0 (ゼロ)を渡します。

26.3.36 OCILobTrim2()

LOB値を短い長さに切り捨てます。4GBを超えるサイズのLOBには、この関数を使用する必要があります。

用途

4GB未満のLOBにもこの関数を使用できます。

構文

sword OCILobTrim2 ( OCISvcCtx       *svchp,
                    OCIError        *errhp,
                    OCILobLocator   *locp,
                    oraub8           newlen );

パラメータ

svchp (IN)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

locp (IN/OUT)

一意にLOBを参照する内部LOBロケータです。このロケータは、svchpに指定したサーバーから取得されたロケータにしてください。

newlen (IN)

現在の長さ以下である必要がある、LOB値の新しい長さです。文字LOBでは文字数であり、バイナリLOBおよびBFILEではLOBのバイト数です。

コメント

この関数では、LOBデータを指定の長さに切り捨てます。newlenが現行のLOBの長さより長い場合は、エラーが戻されます。この関数は内部LOBでのみ有効です。BFILEには使用できません。

このLOB操作をオープン・コールまたはクローズ・コールで囲む必要はありません。この操作を実行する前にLOBをオープンしていない場合、LOB列のファンクション索引とドメイン索引はこのコール時に更新されます。ただし、この操作を実行する前にLOBをオープンしている場合は、トランザクションをコミットする前に、そのLOBをクローズする必要があります。内部LOBがクローズされるときに、LOB列のファンクション索引およびドメイン索引が更新されます。

LOB操作をオープンAPIまたはクローズAPIで囲んでいない場合、ファンクション索引とドメイン索引は、LOBに書き込むたびに更新されます。これにより、パフォーマンスに悪影響を及ぼす可能性があります。ファンクション索引とドメイン索引がある場合は、LOBへの書込み操作をオープン文またはクローズ文内に含めることをお薦めします。

26.3.37 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 );

パラメータ

svchp (IN/OUT)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

locp (IN/OUT)

一意にLOBを参照する内部LOBロケータです。このロケータは、svchpに指定したサーバーから取得されたロケータにしてください。

byte_amtp(IN/OUT)

IN: データベースに書き込むバイト数です。BLOBでは必ず使用されます。CLOBおよびNCLOBに対しては、char_amtpが0 (ゼロ)の場合のみ使用されます。

OUT: データベースに書き込むバイト数です。ポーリング・モードでは、バイト単位のピースの長さ(書込みのみ)です。

char_amtp(IN/OUT)

IN: データベースに書き込む最大文字数です。BLOBでは無視されます。

OUT: データベースに書き込む文字数です。BLOBでは未定義となります。ポーリング・モードでは、文字単位のピースの長さ(書込みのみ)です。

offset (IN)

入力時、これはLOB値の先頭からの絶対オフセットです。文字LOBではLOBの先頭からの文字数であり、バイナリLOBではバイト数です。先頭位置は1です。

ポーリングまたはコールバックによるストリームを使用する場合は、最初のコールでオフセットを指定します。後続のポーリング・コールでは、offsetパラメータは無視されます。コールバックを使用する場合、offsetパラメータはありません。

bufp (IN)

ピースの書込み元バッファへのポインタです。バッファ内のデータの長さは、buflenで渡された値であると想定しています。ポーリング・メソッドを使用してピース単位でデータが書き込まれている場合でも、bufpにはこのコール起動時のLOBの最初のピースを含める必要があります。コールバックを指定した場合は、bufpを使用してデータを指定しないでください。指定した場合、エラーが発生します。

buflen (IN)

バッファ内のデータの長さ(バイト数)です。量がchar_amtpパラメータを使用して文字数で指定され、buflenパラメータがバイト数で指定されている場合、この値は、CLOBおよびNCLOBのchar_amtp値とは異なります。

注意:

このパラメータは8ビット(1バイト)を仮定します。現行のオペレーティング・システムでこれより長いバイトを使用している場合は、buflenの値を必要に応じて調整する必要があります。

piece (IN)

書込み中のバッファのピースです。このパラメータのデフォルト値は、バッファが単独のピースとして書き込まれることを示すOCI_ONE_PIECEです。

ピース単位またはコールバック・モードで可能な他の値としては、OCI_FIRST_PIECE、OCI_NEXT_PIECEおよびOCI_LAST_PIECEがあります。

ctxp (IN)

コールバック関数用のコンテキストです。NULLにできます。

cbfp (IN)

ピース単位書込みで各ピースに対してコールされるように登録できるコールバックです。これがNULLの場合は、標準ポーリング・メソッドが使用されます。

コールバック関数は、OCI_CONTINUEを戻して書込みを続行する必要があります。これ以外のエラー・コードが戻った場合、LOBの書込みは終了します。コールバックは、次のパラメータを取ります。

ctxp (IN)

コールバック関数用のコンテキストです。NULLにできます。

bufp (IN/OUT)

ピース用のバッファ・ポインタです。このパラメータは、OCILobWrite()ルーチンに入力として渡されるbufpと同じです。

lenp (IN/OUT)

buffer (IN)内のデータのバイト数、およびbufp (OUT)内のカレント・ピースのバイト数です。

piecep (OUT)

ピースはOCI_NEXT_PIECEまたはOCI_LAST_PIECEです。

changed_bufpp (OUT)

コールバック関数は、次に読み取るピースに新規バッファを使用することを選択した場合、新規バッファのアドレスを指定できます。このパラメータがNULLに設定されている場合、デフォルトの旧バッファbufpが使用されます。

changed_lenp (OUT)

新規バッファ(指定されている場合)の長さです。

csid (IN)

バッファ内のデータのキャラクタ・セットIDです。この値が0 (ゼロ)の場合は、csfrmの値に応じて、csidにクライアントのNLS_LANG値またはNLS_CHAR値が設定されます。

csfrm (IN)

バッファ・データのキャラクタ・セット・フォームです。csfrmパラメータは、LOBの型と一貫している必要があります。

csfrmパラメータは、0 (ゼロ)以外の次の2つの値をとることができます。

• SQLCS_IMPLICIT - データベース・キャラクタ・セットID

• SQLCS_NCHAR - NCHARキャラクタ・セットID

デフォルト値はSQLCS_IMPLICITです。

コメント

バッファを指定どおりに内部LOBに書き込みます。LOBにデータが存在する場合は、バッファに格納されたデータによって上書きされます。バッファは、このコールによって単独のピースとしてLOBに書き込むことも、コールバックまたは標準ポーリング・メソッドを使用してピース単位で提供することもできます。

注意:

LOBの読取りまたは書込みを行うときは、ロケータのフォームと一致するキャラクタ・セット・フォーム(csfrm)を指定します。

OCILobWrite2()に対してポーリング・モードを使用するとき、最初のコールではoffset、byte_amtpおよびchar_amtpの値を指定する必要がありますが、その後のOCILobWrite2()のポーリング・コールではこれらの値を指定する必要はありません。

pieceパラメータの値がOCI_FIRST_PIECEである場合、データによっては、コールバックまたはポーリングを介して提供される必要があります。

コールバック関数がcbfpパラメータに定義されている場合は、パイプに1ピースが書き込まれるとこのコールバック関数が呼び出され、次のピースが取得されます。各ピースがbufpから書き込まれます。コールバック関数が定義されていない場合、OCILobWrite2()は、OCI_NEED_DATAエラー・コードを戻します。LOBのピースの書込みを続けるには、アプリケーションでOCILobWrite2()を再度コールする必要があります。このモードでは、ピースが別々のサイズで複数の場所に読み取られる場合、コールごとにバッファ・ポインタと長さを変えることができます。

pieceパラメータの値がOCI_LAST_PIECEのときは、ポーリングまたはコールバック方式が使用されているかどうかに関係なく、ピース単位書込み操作は終了します。

(どの入力方法を使用した場合も)データベースに渡されるデータの量が、byte_amtpまたはchar_amtpパラメータに指定された量より少ない場合は、ORA-22993エラーが戻されます。

この関数は内部LOBでのみ有効です。BFILEは読取り専用のため、取り扱えません。LOBがBLOBの場合、csidパラメータおよびcsfrmパラメータは無視されます。

byte_amtpおよびchar_amtpが0 (ゼロ)を指すように設定され、OCI_FIRST_PIECEが入力として指定されている場合、ポーリング・モードが想定され、OCI_LAST_PIECEを指定するまでデータが書き込まれます。CLOBおよびNCLOBでは、byte_amtpおよびchar_amtpは、それぞれバイト数および文字数で、各ピースごとに書き込まれるデータを戻します。BLOBでは、byte_amtpは各ピースごとに書き込まれるバイト数を戻しますが、出力についてchar_amtpは未定義です。

UTF-16形式でデータを書き込むには、csidパラメータをOCI_UTF16IDに設定します。csidパラメータが設定された場合は、このパラメータによって環境変数NLS_LANGが上書きされます。

このLOB操作をオープン・コールまたはクローズ・コールで囲む必要はありません。この操作を実行する前にLOBをオープンしていない場合、LOB列のファンクション索引とドメイン索引はこのコール時に更新されます。ただし、この操作を実行する前にLOBをオープンしている場合は、トランザクションをコミットする前に、そのLOBをクローズする必要があります。内部LOBがクローズされるときに、LOB列のファンクション索引およびドメイン索引が更新されます。

LOB操作をオープンAPIまたはクローズAPIで囲んでいない場合、ファンクション索引とドメイン索引は、LOBに書き込むたびに更新されます。これにより、パフォーマンスに悪影響を及ぼす可能性があります。ファンクション索引とドメイン索引がある場合は、LOBへの書込み操作をオープン文またはクローズ文内に含めることをお薦めします。

関連項目:

• Unicode形式の追加情報は、「OCIでのPL/SQL REF CURSORおよびNESTED TABLE」を参照してください

• LOBの読取りおよび書込み方法を示したコード例については、Oracle Databaseインストレーションに含まれているデモ・プログラムを参照してください。

• OCIデモ・プログラム

• ピース単位のOCI操作の一般情報は、「OCIでのランタイム・データ割当てとピース単位操作」を参照してください

• OCIでのポーリング・モード操作

26.3.38 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);

パラメータ

svchp (IN)

サービス・コンテキスト・ハンドルです。

errhp (IN/OUT)

エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。

locp (IN/OUT)

一意にLOBを参照する内部LOBロケータです。

byte_amtp(IN/OUT)

IN: データベースに書き込むバイト数です。BLOBで使用されます。CLOBおよびNCLOBに対しては、char_amtpが0 (ゼロ)の場合のみ使用されます。

OUT: データベースに書き込むバイト数です。

char_amtp(IN/OUT)

IN: データベースに書き込む最大文字数です。BLOBでは無視されます。

OUT: データベースに書き込む文字数です。BLOBでは未定義となります。

bufp (IN)

ピースの書込み元バッファへのポインタです。バッファ内のデータの長さは、buflenで渡された値であると想定しています。ピース単位でデータが書き込まれている場合でも、bufpにはこのコール起動時のLOBの最初のピースを含める必要があります。コールバックを指定した場合は、bufpを使用してデータを指定しないでください。指定した場合、エラーが発生します。

buflen (IN)

バッファ内のデータの長さ(バイト数)です。このパラメータは8ビット(1バイト)を仮定します。現行のオペレーティング・システムでこれより長いバイトを使用している場合は、buflenの値を必要に応じて調整する必要があります。

piece (IN)

書込み中のバッファのピースです。このパラメータのデフォルト値は、バッファが単独のピースとして書き込まれることを示すOCI_ONE_PIECEです。ピース単位またはコールバック・モードで可能な他の値としては、OCI_FIRST_PIECE、OCI_NEXT_PIECEおよびOCI_LAST_PIECEがあります。

ctxp (IN)

コールバック関数用のコンテキストです。NULLにできます。

cbfp (IN)

ピース単位書込みで各ピースに対してコールされるように登録できるコールバックです。これがNULLの場合は、標準ポーリング・メソッドが使用されます。コールバック関数は、OCI_CONTINUEを戻して書込みを続行する必要があります。これ以外のエラー・コードが戻った場合、LOBの書込みは終了します。コールバックは、次のパラメータを取ります。

ctxp (IN)

コールバック関数用のコンテキストです。NULLにできます。

bufp (IN/OUT)

ピース用のバッファ・ポインタです。

lenp (IN/OUT)

buffer (IN)内のデータのバイト数、およびbufp (OUT)内のカレント・ピースのバイト数です。

piecep (OUT)

ピースはOCI_NEXT_PIECEまたはOCI_LAST_PIECEです。

changed_bufpp (OUT)

コールバック関数は、次に書き込むピースに新規バッファを使用することを選択した場合、新規バッファのアドレスを指定できます。このパラメータがNULLに設定されている場合、デフォルトの旧バッファbufpが使用されます。

changed_lenp (OUT)

新規バッファ(指定されている場合)の長さです。

csid (IN)

バッファ・データのキャラクタ・セットIDです。

csfrm (IN)

バッファ・データのキャラクタ・セット・フォームです。

csfrmパラメータは、0 (ゼロ)以外の次の2つの値をとることができます。

• SQLCS_IMPLICIT - データベース・キャラクタ・セットID

• SQLCS_NCHAR - NCHARキャラクタ・セットID

デフォルト値はSQLCS_IMPLICITです。

コメント

バッファは、このコールによって単独のピースとしてLOBに書き込むことも、コールバックまたは標準ポーリング・メソッドを使用してピース単位で提供することもできます。pieceパラメータの値がOCI_FIRST_PIECEである場合、データによっては、コールバックまたはポーリングを介して提供される必要があります。コールバック関数がcbfpパラメータに定義されている場合は、パイプに1ピースが書き込まれるとこのコールバック関数が呼び出され、次のピースが取得されます。各ピースがbufpから書き込まれます。コールバック関数が定義されていない場合、OCILobWriteAppend2()は、OCI_NEED_DATAエラー・コードを戻します。

LOBのピースの書込みを続けるには、アプリケーションでOCILobWriteAppend2()を再度コールする必要があります。このモードでは、ピースが別々のサイズで複数の場所に読み取られる場合、コールごとにバッファ・ポインタと長さを変えることができます。pieceパラメータの値がOCI_LAST_PIECEのときは、ピース単位の書込みは終了します。

LOBバッファリングが有効な場合、OCILobWriteAppend2()関数はサポートされません。

LOBがBLOBの場合、csidパラメータおよびcsfrmパラメータは無視されます。

byte_amtpおよびchar_amtpが0 (ゼロ)を指すように設定され、OCI_FIRST_PIECEが入力として指定されている場合、ポーリング・モードが想定され、OCI_LAST_PIECEを指定するまでデータが書き込まれます。CLOBおよびNCLOBでは、byte_amtpおよびchar_amtpは、それぞれバイト数および文字数で、各ピースごとに書き込まれるデータを戻します。BLOBでは、byte_amtpは各ピースごとに書き込まれるバイト数を戻しますが、出力についてchar_amtpは未定義です。

このLOB操作をオープン・コールまたはクローズ・コールで囲む必要はありません。この操作を実行する前にLOBをオープンしていない場合、LOB列のファンクション索引とドメイン索引はこのコール時に更新されます。ただし、この操作を実行する前にLOBをオープンしている場合は、トランザクションをコミットする前に、そのLOBをクローズする必要があります。内部LOBがクローズされるときに、LOB列のファンクション索引およびドメイン索引が更新されます。

LOB操作をオープンAPIまたはクローズAPIで囲んでいない場合、ファンクション索引とドメイン索引は、LOBに書き込むたびに更新されます。これにより、パフォーマンスに悪影響を及ぼす可能性があります。ファンクション索引とドメイン索引がある場合は、LOBへの書込み操作をオープン文またはクローズ文内に含めることをお薦めします。

関連項目:

LOBの読取り/書込みパフォーマンスの向上について