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関数
関数グループ | 非推奨の関数 |
---|---|
初期化 |
|
文 |
Oracle Database 12cリリース2 (12.2)以上: OCIStmtPrepare() |
Lob |
OCILobCopy()、OCILobErase()、OCILobGetLength()、OCILobLoadFromFile()、OCILobRead()、OCILobTrim()、OCILobWrite()、OCILobWriteAppend() |
Databaseアドバンスト・キューイング関数 |
E.1 非推奨の初期化関数
非推奨の初期化関数について説明します。
表E-2は、この項で説明している非推奨の初期化関数を示しています。
表E-2 非推奨の初期化関数
関数 | 用途 |
---|---|
環境ハンドルを初期化します。 |
|
OCIプロセス環境を初期化します。 |
E.1.1 OCIEnvInit()
この機能は、Oracle Database 11gリリース2 (11.2)より前のリリースでは非推奨です。
用途
OCI環境ハンドルを割り当て、初期化します。この関数は非推奨です。
構文
sword OCIEnvInit ( OCIEnv **envhpp, ub4 mode, size_t xtramemsz, void **usrmempp );
パラメータ
-
OCI_DEFAULT
-
OCI_ENV_NO_UCB
OCI_DEFAULT
モードの場合、OCIライブラリでハンドルが常にmutex化されます。
OCI_ENV_NO_UCB
モードは、環境の初期化時に動的コールバック・ルーチンOCIEnvCallback
のコールを抑止するために使用します。デフォルトでは、このコールは抑止されません。
関連項目:
コメント
注意:
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 ));
パラメータ
-
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
値を渡すと、デフォルトのプロセス・メモリー割当てメカニズムが使用されます。
関連項目:
-
OCIを使用したマルチスレッド・アプリケーションのプログラミングの詳細は、「OCIマルチスレッド開発の概要」を参照してください
-
オブジェクトを使用したOCIプログラミングの詳細は、「OCIオブジェクト・リレーショナル・プログラミング」を参照してください
例
次の文は、ユーザー定義メモリー関数がない場合に、スレッド・モードおよびオブジェクト・モードでOCIInitialize()
をコールする方法の例です。
OCIInitialize((ub4) OCI_THREADED | OCI_OBJECT, (void *)0, (void * (*)()) 0, (void * (*)()) 0, (void (*)()) 0 );
E.2 非推奨の文関数
非推奨の文関数について説明します。
表E-3は、この項で説明している非推奨の文関数を示しています。
表E-3 非推奨の文関数
関数 | 用途 |
---|---|
問合せから行をフェッチします。 |
|
実行する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関数
関数 | 用途 |
---|---|
LOBの一部または全部を別のLOBにコピーします。アプリケーション・コンティニュイティをサポートします。 |
|
LOBの一部を消去します。アプリケーション・コンティニュイティをサポートします。 |
|
LOBの長さを取得します。 |
|
|
|
LOBの一部を読み取ります。アプリケーション・コンティニュイティをサポートします。 |
|
LOBを切り捨てます。アプリケーション・コンティニュイティをサポートします。 |
|
LOBに書き込みます。アプリケーション・コンティニュイティをサポートします。 |
|
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 | 入力 | 固定幅のクライアント側キャラクタ・セットによる出力 | 可変幅のクライアント側キャラクタ・セットによる出力 |
---|---|---|---|
|
バイト |
バイト |
バイト |
|
文字 |
文字 |
バイト 脚注 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
が上書きされます。
関連トピック
関連項目:
-
Unicode形式の追加情報は、「OCIでのPL/SQL REF CURSORおよびNESTED TABLE」を参照してください
-
BFILE
の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください -
LOBの読取りおよび書込み方法を示したコード例については、Oracle Databaseインストレーションに含まれているデモ・プログラムを参照してください。
-
ピース単位のOCI操作の一般情報は、「OCIでのランタイム・データ割当てとピース単位操作」を参照してください
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 | 固定幅のクライアント側キャラクタ・セットによる入力 | 可変幅のクライアント側キャラクタ・セットによる入力 | 出力 |
---|---|---|---|
|
バイト |
バイト |
バイト |
|
文字 |
バイト 脚注 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への書込み操作をオープン文またはクローズ文内に含めることをお薦めします。
関連トピック
関連項目:
-
Unicode形式の追加情報は、「OCIでのPL/SQL REF CURSORおよびNESTED TABLE」を参照してください
-
LOBの読取りおよび書込み方法を示したコード例については、Oracle Databaseインストレーションに含まれているデモ・プログラムを参照してください。
-
ピース単位のOCI操作の一般情報は、「OCIでのランタイム・データ割当てとピース単位操作」を参照してください
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 | 固定幅のクライアント側キャラクタ・セットによる入力 | 可変幅のクライアント側キャラクタ・セットによる入力 | 出力 |
---|---|---|---|
|
バイト |
バイト |
バイト |
|
文字 |
バイト 脚注 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への書込み操作をオープン文またはクローズ文内に含めることをお薦めします。
関連トピック
E.4 非推奨のDatabaseアドバンスト・キューイング関数
非推奨のOracle Databaseアドバンスト・キューイング関数について説明します。
表E-8は、この項で説明している非推奨のDatabaseアドバンスト・キューイング関数を示しています。
表E-8 非推奨のDatabaseアドバンスト・キューイング関数
関数 | 用途 |
---|---|
リストのエージェントの代理として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
として渡されます。
コメント
これは、リスト内のエージェントについて消費可能なメッセージがあるときに返されるブロック化コールです。待機時間が終了してもメッセージが検出されない場合は、エラーが戻されます。
関連トピック