1. プログラマーズ・ガイド
  2. 非推奨となったOCI機能および関数

E非推奨となったOCI機能および関数

非推奨となったOCI機能および関数は、今後のリリースで廃止になることがあります。該当する場合は、代替のOCI関数が言及されています。

Oracle Databaseリリース18c、バージョン18.1以上、結果セット記述子OCI_DTYPE_RSET。

Oracle Database 12cリリース1 (12.1)以上でのOCIリリース7.3 API。

表E-1は、特に記載のないかぎり、Oracle 11g R2 (11.2)より前のリリースで非推奨になったOCI関数を示しています。今後のリリースでは、これらの関数は使用されなくなる可能性があります。

表E-1 非推奨のOCI関数

関数グループ 非推奨の関数

初期化

OCIEnvInit()、OCIInitialize()

文

OCIStmtFetch()

Oracle Database 12cリリース2 (12.2)以上: OCIStmtPrepare()

Lob

OCILobCopy()、OCILobErase()、OCILobGetLength()、OCILobLoadFromFile()、OCILobRead()、OCILobTrim()、OCILobWrite()、OCILobWriteAppend()

Databaseアドバンスト・キューイング関数

OCIAQListen()
この項には次のトピックが含まれます:

E.1 非推奨の初期化関数

非推奨の初期化関数について説明します。

表E-2は、この項で説明している非推奨の初期化関数を示しています。

表E-2 非推奨の初期化関数

関数 用途

OCIEnvInit()

環境ハンドルを初期化します。

OCIInitialize()

OCIプロセス環境を初期化します。

E.1.1 OCIEnvInit()

この機能は、Oracle Database 11gリリース2 (11.2)より前のリリースでは非推奨です。

用途

OCI環境ハンドルを割り当て、初期化します。この関数は非推奨です。

構文

sword OCIEnvInit ( OCIEnv    **envhpp,
                   ub4         mode,
                   size_t      xtramemsz,
                   void      **usrmempp );

パラメータ

envhpp (OUT)

環境へのハンドルのポインタです。

mode (IN)

環境モードの初期化を指定します。次のモードが有効です。

  • OCI_DEFAULT

  • OCI_ENV_NO_UCB

OCI_DEFAULTモードの場合、OCIライブラリでハンドルが常にmutex化されます。

OCI_ENV_NO_UCBモードは、環境の初期化時に動的コールバック・ルーチンOCIEnvCallbackのコールを抑止するために使用します。デフォルトでは、このコールは抑止されません。

関連項目:

動的なコールバック登録

xtramemsz (IN)

環境の継続時間中に割り当てられるユーザー・メモリーの量を指定します。

usrmempp (OUT)

環境の継続時間中コールによってユーザー用に割り当てられた、xtramemszサイズのユーザー・メモリーのポインタを戻します。

コメント

注意:

OCIEnvCreate()は、OCIInitialize()コールおよびOCIEnvInit()コールのかわりに使用します。OCIInitialize()およびOCIEnvInit()コールは、下位互換性を保つためにサポートされています。

このコールは、OCI環境ハンドルの割当ておよび初期化を行います。初期化済のハンドルには何も行いません。OCI_ERRORまたはOCI_SUCCESS_WITH_INFOが戻った場合は、この環境ハンドルを使用してOracle固有のエラーおよび診断を取得できます。

これはローカルに処理され、サーバー・ラウンドトリップはありません。

環境ハンドルは、OCIHandleFree()を使用して解放できます。

関連トピック

関連項目:

xtramemszパラメータおよびユーザー・メモリー割当ての詳細は、「ユーザー・メモリーの割当て」を参照してください

E.1.2 OCIInitialize()

この機能は、Oracle Database 11gリリース2 (11.2)より前のリリースでは非推奨です。

用途

OCIプロセス環境を初期化します。この関数は非推奨です。

構文

sword OCIInitialize ( ub4            mode,
                      const void    *ctxp, 
                      const void    *(*malocfp) 
                                     ( void   *ctxp,
                                        size_t size ),
                      const void    *(*ralocfp)
                                     ( void  *ctxp,
                                       void  *memptr,
                                       size_t newsize ),
                      const void    (*mfreefp)
                                     ( void  *ctxp,
                                       void  *memptr ));

パラメータ

mode (IN)

モードの初期化を指定します。次のモードが有効です。

  • OCI_DEFAULT - デフォルト・モード。

  • OCI_THREADED - スレッド環境。このモードでは、ユーザーに公開されていない内部データ構造がマルチ・スレッドによって同時にアクセスされないように保護します。

  • OCI_OBJECT - オブジェクト機能を使用します。

  • OCI_EVENTS - パブリッシュ/サブスクライブ通知を利用します。

ctxp (IN)

メモリー・コールバック・ルーチン用のユーザー定義コンテキストです。

malocfp (IN)

ユーザー定義のメモリー割当て関数です。modeがOCI_THREADEDの場合、このメモリー割当てルーチンは、スレッド・セーフにしてください。

ctxp (IN/OUT)

ユーザー定義のメモリー割当て関数のためのコンテキスト・ポインタです。

size (IN)

ユーザー定義のメモリー割当て関数によって割り当てられるメモリーのサイズです。

ralocfp (IN)

ユーザー定義のメモリー再割当て関数です。modeがOCI_THREADEDの場合、このメモリー割当てルーチンは、スレッド・セーフにしてください。

ctxp (IN/OUT)

ユーザー定義のメモリー再割当て関数のためのコンテキスト・ポインタです。

memptr (IN/OUT)

メモリー・ブロックのポインタです。

newsize (IN)

新しく割り当てられるメモリーのサイズです。

mfreefp (IN)

ユーザー定義のメモリー解放関数です。modeがOCI_THREADEDの場合、このメモリー解放ルーチンは、スレッド・セーフにしてください。

ctxp (IN/OUT)

ユーザー定義のメモリー解放関数のためのコンテキスト・ポインタです。

memptr (IN/OUT)

解放されるメモリーへのポインタです。

コメント

注意:

OCIEnvCreate()は、非推奨のOCIInitialize()コールのかわりに使用します。OCIInitialize()コールは、下位互換性を保つためにサポートされています。

このコールは、OCIプロセス環境を初期化します。OCIInitialize()は、他のOCIをコールする前にコールする必要があります。

この関数を使用すると、アプリケーションでコールバックを使用して固有のメモリー管理関数を定義できます。アプリケーションでこのようなメモリー管理関数(つまりメモリー割当て、メモリー再割当ておよびメモリー解放)がすでに定義されている場合は、この関数のコールバック・パラメータを使用して登録する必要があります。

これらのメモリー・コールバックはオプションです。アプリケーションで、この関数のメモリー・コールバックにNULL値を渡すと、デフォルトのプロセス・メモリー割当てメカニズムが使用されます。

関連項目:

例

次の文は、ユーザー定義メモリー関数がない場合に、スレッド・モードおよびオブジェクト・モードでOCIInitialize()をコールする方法の例です。 

OCIInitialize((ub4) OCI_THREADED | OCI_OBJECT, (void  *)0,
     (void  * (*)()) 0, (void  * (*)()) 0,  (void (*)()) 0 );

関連トピック

E.2 非推奨の文関数

非推奨の文関数について説明します。

表E-3は、この項で説明している非推奨の文関数を示しています。

表E-3 非推奨の文関数

関数 用途

OCIStmtFetch()

問合せから行をフェッチします。

OCIStmtPrepare()

実行するSQL文またはPL/SQL文を準備します。

E.2.1 OCIStmtFetch()

この関数は、Oracle 11g R2 (11.2)より前のリリースでは非推奨です。

用途

問合せから行をフェッチします。この関数は非推奨です。OCIStmtFetch2()を使用してください。

構文

sword OCIStmtFetch ( OCIStmt     *stmtp,
                     OCIError    *errhp, 
                     ub4          nrows,
                     ub2          orientation,
                     ub4          mode );

パラメータ

stmtp (IN)

文(アプリケーション要求)ハンドルです。

errhp (IN)

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

nrows (IN)

現行の位置からフェッチされる行数です。

orientation (IN)

リリース9.0より前で使用可能な値は、OCI_FETCH_NEXT (デフォルト値)のみです。

mode (IN)

OCI_DEFAULTを渡します。

コメント

プリフェッチされた行で間に合う場合、フェッチ・コールはローカル・コールになります。ただしこれは、アプリケーションに対して透過的に行われます。

LOB列が読み取られる場合、LOBロケータに対して実行される後続のLOB操作のために、それらのロケータがフェッチされます。LONG列の場合、プリフェッチはオフになります。

この関数は、次のエラーのいずれかが発生するとEOFのOCI_NO_DATAおよびOCI_SUCCESS_WITH_INFOを戻します。

  • ORA-24344 - 正常に終了しましたが、コンパイル・エラーがあります。

  • ORA-24345 - 切捨てまたはNULLフェッチ・エラーが発生しました。

  • ORA-24347 - 警告: グループ関数にNULL列があります。

nrowsパラメータに0 (ゼロ)を設定してOCIStmtFetch()をコールした場合は、カーソルが取り消されます。

OCI_ATTR_ROWS_FETCHEDを使用して、最後のフェッチ・コールでユーザーのバッファに正常にフェッチされた行数を検索します。

関連トピック

E.2.2 OCIStmtPrepare()

この関数は、Oracle Database 12cリリース2 (12.2)以上で非推奨となりました。

用途

実行するSQL文またはPL/SQL文を準備します。この関数は非推奨です。OCIStmtPrepare2()を使用してください。

構文

sword OCIStmtPrepare ( OCIStmt       *stmtp,
                       OCIError      *errhp,
                       const OraText *stmt, 
                       ub4            stmt_len,
                       ub4            language,
                       ub4            mode );

パラメータ

stmtp (IN)

実行対象の文に関連付けられた文ハンドルです。デフォルトでは、導出元の環境ハンドルのエンコーディング設定が含まれています。文をUTF-16エンコーディングで準備できるのは、UTF-16環境のみです。

errhp (IN)

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

stmt (IN)

実行されるSQL文またはPL/SQL文です。NULLで終了する文字列にしてください。つまり、最後の文字は、エンコーディングによってはNULLバイトの数値です。文は、OCIEnvNlsCreate()の直前のコールのcharsetパラメータで指定されたエンコーディングであることが必要です。

パラメータを必ず(text *)にキャストしてください。文がUTF-16で準備されると、バインド・バッファと定義バッファのキャラクタ・セットは、UTF-16にデフォルト設定されます。

stmt_len (IN)

文の長さです。エンコーディングによって、文字数またはバイト数の単位になります。0(ゼロ)以外の値である必要があります。

language (IN)

V7構文またはネイティブ構文を指定します。有効な値は次のとおりです。

  • OCI_V7_SYNTAX - V7 Oracle解析構文。

  • OCI_NTV_SYNTAX - サーバーのバージョンに依存する構文。

    OCI_FOREIGN_SYNTAX - セッションのSQL翻訳プロファイルに従って翻訳される文を指定します。

mode (IN)

OCIEnvCreate()コールのmodeに類似しています。ただし、このコールは必然的に継承されたモード設定を上書きできるため、優先度が高くなります。

可能な値はOCI_DEFAULT (デフォルト・モード)またはOCI_PREP2_IMPL_RESULTS_CLIENTです。このコールが外部プロシージャで作成され、暗黙的な結果を処理する必要がある場合、これらのモードはOCI_PREP2_IMPL_RESULTS_CLIENTとして渡される必要があります。詳細は、「暗黙的な結果のOCIサポート」を参照してください。文ハンドルstmtpは、親の環境ハンドルに指定されている内容を使用します。

コメント

このコールは、OCIアプリケーションで実行するSQL文またはPL/SQL文を準備するために使用します。OCIStmtPrepare()コールは、アプリケーション要求を定義します。

modeパラメータは、文の内容がUTF-16でエンコーディングされているかどうかを判断します。文の長さは、コードポイント数またはバイト数で、エンコーディングによって異なります。

文ハンドルは、親の環境ハンドルからエンコーディング設定を継承しますが、このコールのmodeによって、文ハンドル自体のエンコーディング設定も変更できます。

後続のバインド・コールで初期化されるこの文のデータ値は、この文ハンドルの設定をデフォルトとして使用するバインド・ハンドル内に格納されます。

このコールは、この文ハンドルと特定のサーバー間の対応付けは作成しません。

DDL文を再実行する前に、この関数の2回目のコールを実行してください。

このコールではアプリケーション・コンティニュイティはサポートされておらず、このコールが使用されると、「エラー - ORA-25412: OCIStmtPrepareへのコールにより、トランザクションの再実行が無効化されています」というエラーが戻されます。HAインフラストラクチャでアプリケーション・コンティニュイティの使用をサポートするには、OCIStmtPrepare2()コールを使用します。

関連トピック

関連項目:

このコールの使用方法の詳細は、「文の準備について」を参照してください

E.3 非推奨のLOB関数

非推奨のLOB関数について説明します。

表E-4は、この項で説明している非推奨のLOB関数を示しています。

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

表E-4 非推奨のLOB関数

関数 用途

OCILobCopy()

LOBの一部または全部を別のLOBにコピーします。アプリケーション・コンティニュイティをサポートします。

OCILobErase()

LOBの一部を消去します。アプリケーション・コンティニュイティをサポートします。

OCILobGetLength()

LOBの長さを取得します。

OCILobLoadFromFile()

BFILEからLOBをロードします。アプリケーション・コンティニュイティをサポートします。

OCILobRead()

LOBの一部を読み取ります。アプリケーション・コンティニュイティをサポートします。

OCILobTrim()

LOBを切り捨てます。アプリケーション・コンティニュイティをサポートします。

OCILobWrite()

LOBに書き込みます。アプリケーション・コンティニュイティをサポートします。

OCILobWriteAppend()

LOBの末尾からデータを書き込みます。

E.3.1 OCILobCopy()

この機能は、Oracle Database 11gリリース2 (11.2)より前のリリースでは非推奨です。

用途

LOB値の全体または一部を別のLOB値にコピーします。この関数は非推奨です。OCILobCopy2()を使用してください。

構文

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

パラメータ

関連トピック

E.3.2 OCILobErase()

この機能は、Oracle Database 11gリリース2 (11.2)より前のリリースでは非推奨です。

用途

内部LOBデータの一部を指定のオフセットの位置から消去します。この関数は非推奨です。OCILobErase2()を使用してください。

構文

sword OCILobErase ( OCISvcCtx       *svchp,
                    OCIError        *errhp,
                    OCILobLocator   *locp,
                    ub4             *amount,
                    ub4              offset );

パラメータ

関連トピック

E.3.3 OCILobGetLength()

この機能は、Oracle Database 11gリリース2 (11.2)より前のリリースでは非推奨です。

用途

LOBの長さを取得します。この関数は非推奨です。OCILobGetLength2()を使用してください。

構文

sword OCILobGetLength ( OCISvcCtx      *svchp,
                        OCIError       *errhp,
                        OCILobLocator  *locp,
                        ub4            *lenp );

パラメータ

関連トピック

E.3.4 OCILobLoadFromFile()

この機能は、Oracle Database 11gリリース2 (11.2)より前のリリースでは非推奨です。

用途

ファイルの全体または一部を内部LOBにロードおよびコピーします。この関数は非推奨です。OCILobLoadFromFile2()を使用してください。

構文 

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

パラメータ

関連トピック

E.3.5 OCILobRead()

この機能は、Oracle Database 11gリリース2 (11.2)より前のリリースでは非推奨です。

用途

LOBまたはBFILEの一部をコールの指定どおりにバッファに読み取ります。この関数は非推奨です。OCILobRead2()を使用してください。

構文

sword OCILobRead ( OCISvcCtx          *svchp,
                   OCIError           *errhp,
                   OCILobLocator      *locp,
                   ub4                *amtp,
                   ub4                 offset,
                   void               *bufp,
                   ub4                 bufl,
                   void               *ctxp, 
                   OCICallbackLobRead (cbfp)
                                      ( void          *ctxp,
                                        const void    *bufp,
                                        ub4            len,
                                        ub1            piece 
                                      )
                   ub2                 csid,
                   ub1                 csfrm );

パラメータ

svchp (IN/OUT)

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

errhp (IN/OUT)

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

locp (IN)

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

amtp (IN/OUT)

表E-5に示すように、amtpの値は、バイト数または文字数のいずれかで表される量です。

表E-5 OCILobRead()のamtpの文字数またはバイト数

LOBまたはBFILE 入力 固定幅のクライアント側キャラクタ・セットによる出力 可変幅のクライアント側キャラクタ・セットによる出力

BLOBおよびBFILE

バイト

バイト

バイト

CLOBおよびNCLOB

文字

文字

バイト 脚注 1

脚注1

入力量は、サーバー側のCLOBまたはNCLOBから読み取る文字数を示します。出力量は、バッファbufpに読み取られたバイト数を示します。

次の場合、パラメータamtpは読み取られたデータの総量です。

  • データがストリーム・モードで読み取られない場合(1ピースのみ読み取られ、ポーリングまたはコールバックは行われません)。

  • データがコールバックによってストリーム・モードで読み取られる場合

データがポーリングを使用してストリーム・モードで読み取られる場合、パラメータamtpは読み取られた最後のピースの長さです。

読み取られる量がバッファの長さより多い場合、ストリーム・モードでのLOBの読取りは、入力オフセットからLOBの終わりまでか、指定されたバイト数の読取りまで、いずれか先に達するところまで行われます。入力時にこの値が0 (ゼロ)の場合は、入力オフセットからLOBの末尾までストリーム・モードでデータが読み取られます。

ストリーム・モード(ポーリングまたはコールバックのいずれかで実行)の場合、LOB値は入力オフセットから連続して読み取られます。

データがピース単位で読み取られる場合、amtpパラメータには常に読み取られた各ピースの長さが含まれます。

コールバック関数が定義されている場合は、パイプからbuflバイトが読み取られるたびにそのコールバック関数が呼び出されます。各ピースがbufpに書き込まれます。

コールバック関数が定義されていない場合は、OCI_NEED_DATAエラー・コードが戻ります。アプリケーションでは、OCI_NEED_DATAエラー・コードが戻らなくなるまで何度もOCILobRead()をコールし、LOBのピースを読み取る必要があります。ピースのサイズを変えながら複数の場所を読み取る場合は、コールごとにバッファ・ポインタと長さを変えることができます。

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)とは異なります。

ctxp (IN)

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

cbfp (IN)

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

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

ctxp (IN)

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

bufp (IN/OUT)

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

len (IN)

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

piece (IN)

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

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にあること、およびディレクトリ・オブジェクトの読取り許可がユーザーにあることが必要です。

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

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

注意:

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

次のルールは、CLOBおよびNCLOBのクライアント側可変幅キャラクタ・セットに適用されます。

  • ポーリング・モードを使用する場合は、最初のOCILobRead()コールでamtpパラメータとoffsetパラメータのみ指定してください。後続のポーリング・コールでは、これらのパラメータは無視されます。

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

次のルールは、CLOBおよびNCLOBのクライアント側の固定幅キャラクタ・セットおよびサーバー側の可変幅キャラクタ・セットに適用されます。

  • CLOB値またはNCLOB値を読み取る場合は、OCILobRead()をコールするたびにamtpパラメータを参照し、バッファに格納された量を確認します。戻り値が文字数の場合(クライアント側のキャラクタ・セットが固定幅の場合)は、この値をバイトに変換して、バッファに格納された量を判断します。コールバックを使用する場合は、常にlenパラメータをチェックしてバッファに格納された量を確認します。この値は、常にバイト単位です。

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

関連トピック

関連項目:

E.3.6 OCILobTrim()

この機能は、Oracle Database 11gリリース2 (11.2)より前のリリースでは非推奨です。

用途

LOB値を短い長さに切り捨てます。この関数は非推奨です。OCILobTrim2()を使用してください。

構文

sword OCILobTrim ( OCISvcCtx       *svchp,
                   OCIError        *errhp,
                   OCILobLocator   *locp,
                   ub4              newlen );

パラメータ

関連トピック

E.3.7 OCILobWrite()

この機能は、Oracle Database 11gリリース2 (11.2)より前のリリースでは非推奨です。

用途

バッファをLOBに書き込みます。この関数は非推奨です。OCILobWrite2()を使用してください。

構文

sword OCILobWrite ( OCISvcCtx       *svchp,
                    OCIError        *errhp,
                    OCILobLocator   *locp,
                    ub4             *amtp,
                    ub4              offset,
                    void            *bufp, 
                    ub4              buflen,
                    ub1              piece,
                    void            *ctxp, 
                    OCICallbackLobWrite      (cbfp)
                                    (
                                      void     *ctxp,
                                      void     *bufp,
                                      ub4      *lenp,
                                      ub1      *piecep
                                    ) 
                    ub2              csid,
                    ub1              csfrm );

パラメータ

svchp (IN/OUT)

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

errhp (IN/OUT)

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

locp (IN/OUT)

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

amtp (IN/OUT)

表E-6に示すように、amtpの値は、バイト数または文字数のいずれかで表される量です。

表E-6 OCILobWrite()のamtpの文字数またはバイト数

LOBまたはBFILE 固定幅のクライアント側キャラクタ・セットによる入力 可変幅のクライアント側キャラクタ・セットによる入力 出力

BLOBおよびBFILE

バイト

バイト

バイト

CLOBおよびNCLOB

文字

バイト 脚注 2

文字

脚注 2

入力量は、ユーザーがLOBに書き込むデータのバイト数であり、bufp内のバイト数ではありません。これはbuflenで指定します。データがピース単位で書き込まれる場合、書き込むバイト量はbuflenより大きくなることがあります。出力量は、サーバー側のCLOBまたはNCLOBに書き込まれた文字数を表します。

これは、常にNULL以外のポインタにする必要があります。EOFまでの書込みを指定する場合は、変数を宣言してゼロを設定し、そのアドレスをこのパラメータに渡します。

入力時に量が指定されていて、データがピース単位で書き込まれる場合、パラメータamtpにはコール終了時(最後のピースが書き込まれた時点)に各ピースの長さの合計が格納され、書込み途中は未定義になります。ピース単位の読取りとは異なることに注意してください。指定された量がサーバーに送信されない場合は、エラーが戻されます。

amtpが0 (ゼロ)の場合は、ストリーム・モードが使用され、ユーザーがOCI_LAST_PIECEを指定するまでデータが書き込まれます。

offset (IN)

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

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

bufp (IN)

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

buflen (IN)

バッファ内のデータの長さ(バイト数)です。buflenパラメータがバイト数で指定され、amtpパラメータが文字数で指定されている場合、この値は、CLOBおよびNCLOBの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です。

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)を指定します。

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

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

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

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

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

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

クライアント側のキャラクタ・セットが可変幅の場合、CLOBおよびNCLOBの入力量はバイト数で、出力量は文字数で表されます。入力量は、ユーザーがLOBに書き込むデータのバイト数であり、bufp内のバイト数ではありません。これはbuflenで指定します。データがピース単位で書き込まれる場合、書き込むバイト量はbuflenより大きくなることがあります。出力量は、サーバー側のCLOBまたはNCLOBに書き込まれた文字数を表します。

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

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

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

関連トピック

関連項目:

E.3.8 OCILobWriteAppend()

この機能は、Oracle Database 11gリリース2 (11.2)より前のリリースでは非推奨です。

用途

LOBの末尾からデータの書込みを開始します。この関数は非推奨です。OCILobWriteAppend2()を使用してください。

構文

sword OCILobWriteAppend ( OCISvcCtx     *svchp,
                          OCIError      *errhp,
                          OCILobLocator *locp,
                          ub4           *amtp,
                          void          *bufp, 
                          ub4            buflen, 
                          ub1            piece, 
                          void          *ctxp, 
                          OCICallbackLobWrite       (cbfp)
                                         (
                                           void     *ctxp,
                                           void     *bufp,
                                           ub4      *lenp,
                                           ub1      *piecep
                                         ) 
                          ub2            csid, 
                          ub1            csfrm );

パラメータ

svchp (IN)

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

errhp (IN/OUT)

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

locp (IN/OUT)

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

amtp (IN/OUT)

表E-7に示すように、amtpの値は、バイト数または文字数のいずれかで表される量です。

表E-7 OCILobWriteAppend()のamtpの文字数またはバイト数

LOBまたはBFILE 固定幅のクライアント側キャラクタ・セットによる入力 可変幅のクライアント側キャラクタ・セットによる入力 出力

BLOBおよびBFILE

バイト

バイト

バイト

CLOBおよびNCLOB

文字

バイト 脚注 3

文字

脚注 3

入力量は、ユーザーがLOBに書き込むデータのバイト数であり、bufp内のバイト数ではありません。これはbuflenで指定します。データがピース単位で書き込まれる場合、書き込むバイト量はbuflenより大きくなることがあります。出力量は、サーバー側のCLOBまたはNCLOBに書き込まれた文字数を表します。

入力時に量が指定されていて、データがピース単位で書き込まれる場合、パラメータamtpにはコール終了時(最後のピースが書き込まれた時点)に各ピースの長さの合計が格納され、書込み途中は未定義になります。(ピース単位の読取りとは異なることに注意してください)。指定された量がサーバーに送信されない場合は、エラーが戻されます。amtpが0 (ゼロ)の場合は、ストリーム・モードが使用され、ユーザーがOCI_LAST_PIECEを指定するまでデータが書き込まれます。

クライアント側のキャラクタ・セットが可変幅の場合、CLOBまたはNCLOBの入力量は文字ではなくバイトで表されます。

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です。

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から書き込まれます。コールバック関数が定義されていない場合、OCILobWriteAppend()は、OCI_NEED_DATAエラー・コードを戻します。

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

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

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

クライアント側のキャラクタ・セットが可変幅の場合、CLOBまたはNCLOBの入力量は文字ではなくバイトで表されます。

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

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

関連トピック

関連項目:

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

E.4 非推奨のDatabaseアドバンスト・キューイング関数

非推奨のOracle Databaseアドバンスト・キューイング関数について説明します。

表E-8は、この項で説明している非推奨のDatabaseアドバンスト・キューイング関数を示しています。

表E-8 非推奨のDatabaseアドバンスト・キューイング関数

関数 用途

OCIAQListen()

リストのエージェントの代理として1つ以上のキューをリスニングします。

E.4.1 OCIAQListen()

この機能は、Oracle Database 11gリリース2 (11.2)より前のリリースでは非推奨です。

用途

リストのエージェントのかわりに1つ以上のキューをリスニングします。この関数は非推奨です。OCIAQListen2()を使用してください。

構文

sword OCIAQListen (OCISvcCtx      *svchp, 
                   OCIError       *errhp,
                   OCIAQAgent    **agent_list, 
                   ub4             num_agents,
                   sb4             wait, 
                   OCIAQAgent    **agent,
                   ub4             flags);

パラメータ

svchpp (IN/OUT)

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

errhp (IN/OUT)

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

agent_list (IN)

メッセージを監視するエージェントのリストです。

num_agents (IN)

エージェント・リスト内のエージェント数です。

wait (IN)

リスニング・コールのタイムアウト時間です。

agent (OUT)

メッセージの出力先のエージェントです。OCIAgentはOCI記述子です。

flags (IN)

現行では使用されていません。OCI_DEFAULTとして渡されます。

コメント

これは、リスト内のエージェントについて消費可能なメッセージがあるときに返されるブロック化コールです。待機時間が終了してもメッセージが検出されない場合は、エラーが戻されます。

関連トピック