E 非推奨のOCI関数
非推奨のOCI関数は今後のリリースで使用されなくなる可能性があります。該当する場合は、代替のOCI関数が言及されています。
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() Oracle Database 12cリリース2 (12.2)以上: OCILobDisableBuffering()、OCILobEnableBuffering()、OCILobFlushBuffer() |
|
Streamsアドバンスト・キューイング関数 |
非推奨の初期化関数
非推奨の初期化関数について説明します。
表E-2は、この項で説明している非推奨の初期化関数を示しています。
表E-2 非推奨の初期化関数
| 関数 | 用途 |
|---|---|
|
環境ハンドルを初期化します。 |
|
|
OCIプロセス環境を初期化します。 |
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パラメータおよびユーザー・メモリー割当ての詳細は、「ユーザー・メモリーの割当て」を参照してください
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-3は、この項で説明している非推奨の文関数を示しています。
表E-3 非推奨の文関数
| 関数 | 用途 |
|---|---|
|
問合せから行をフェッチします。 |
|
|
実行するSQL文またはPL/SQL文を準備します。 |
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を使用して、最後のフェッチ・コールでユーザーのバッファに正常にフェッチされた行数を検索します。
関連トピック
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()コールを使用します。
関連トピック
関連項目:
このコールの使用方法の詳細は、「文の準備について」を参照してください
非推奨のLOB関数
非推奨のLOB関数について説明します。
表E-4は、この項で説明している非推奨のLOB関数を示しています。
Oracle Database 12cリリース2 (12.2)以上では、次の表に示すとおり、一部の非推奨のLOB関数を含むほとんどのLOB関数でアプリケーション・コンティニュイティがサポートされます(完全なリストは、「アプリケーション・コンティニュイティでサポートされるLOB関数」を参照してください)。
表E-4 非推奨のLOB関数
| 関数 | 用途 |
|---|---|
|
LOBの一部または全部を別のLOBにコピーします。アプリケーション・コンティニュイティをサポートします。 |
|
|
入力ロケータのLOBバッファリングを使用禁止にします。 |
|
|
入力ロケータのLOBバッファリングを使用可能にします。 |
|
|
LOBの一部を消去します。アプリケーション・コンティニュイティをサポートします。 |
|
|
このLOBのすべてのバッファをサーバーにフラッシュするか、または書き込みます。 |
|
|
LOBの長さを取得します。 |
|
|
|
|
|
LOBの一部を読み取ります。アプリケーション・コンティニュイティをサポートします。 |
|
|
LOBを切り捨てます。アプリケーション・コンティニュイティをサポートします。 |
|
|
LOBに書き込みます。アプリケーション・コンティニュイティをサポートします。 |
|
|
LOBの末尾からデータを書き込みます。 |
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 );パラメータ
関連トピック
OCILobDisableBuffering()
この関数は、Oracle Database12cリリース2 (12.2)以降で非推奨となりました。
用途
入力ロケータのLOBバッファリングを使用禁止にします。この関数は非推奨です。
構文
sword OCILobDisableBuffering ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp ); パラメータ
- svchp (IN)
-
サービス・コンテキスト・ハンドルです。
- errhp (IN/OUT)
-
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
- locp (IN/OUT)
-
一意にLOBを参照する内部LOBロケータです。
コメント
入力内部LOBロケータのLOBバッファリングを使用禁止にします。次回入力ロケータを通してLOBに対してデータの読取りまたは書込みを行うときは、LOBバッファリング・サブシステムは使用されません。このコールでは、バッファリング・サブシステムでの変更は暗黙的にはフラッシュされません。ユーザーは、OCILobFlushBuffer()をコールして変更を明示的にフラッシュする必要があります。
OCILobDisableBuffering()では、リモート・ロケータが渡されるとエラーがスローされます。
この関数は、BFILEロケータを受け入れません。
OCILobEnableBuffering()
この関数は、Oracle Database12cリリース2 (12.2)以降で非推奨となりました。
用途
入力ロケータのLOBバッファリングを使用可能にします。この関数は非推奨です。
構文
sword OCILobEnableBuffering ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp ); パラメータ
- svchp (IN)
-
サービス・コンテキスト・ハンドルです。
- errhp (IN/OUT)
-
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
- locp (IN/OUT)
-
一意にLOBを参照する内部LOBロケータです。
コメント
入力内部LOBロケータのLOBバッファリングを使用可能にします。次回入力ロケータを通してLOBに対してデータの読取りまたは書込みを行うときは、LOBバッファリング・サブシステムが使用されます。
OCILobEnableBuffering()では、リモート・ロケータが渡されるとエラーがスローされます。
ロケータのLOBバッファリングが使用可能な状態で、そのロケータがルーチンOCILobAppend()、OCILobCopy() (非推奨)、OCILobCopy2()、OCILobErase() (非推奨)、OCILobErase2()、OCILobGetLength() (非推奨)、OCILobGetLength2()、OCILobLoadFromFile() (非推奨)、OCILobLoadFromFile2()、OCILobTrim() (非推奨)、OCILobTrim2()、OCILobWriteAppend() (非推奨)またはOCILobWriteAppend2()のいずれかに渡されると、エラーが戻ります。
この関数は、BFILEロケータを受け入れません。
OCILobErase()
この機能は、Oracle Database 11gリリース2 (11.2)より前のリリースでは非推奨です。
用途
内部LOBデータの一部を指定のオフセットの位置から消去します。この関数は非推奨です。OCILobErase2()を使用してください。
構文
sword OCILobErase ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
ub4 *amount,
ub4 offset );パラメータ
関連トピック
OCILobFlushBuffer()
この関数は、Oracle Database12cリリース2 (12.2)以降で非推奨となりました。
用途
このLOBのすべてのバッファをサーバーにフラッシュするか、または書き込みます。この関数は非推奨です。
構文
sword OCILobFlushBuffer ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp
ub4 flag ); パラメータ
コメント
入力ロケータによって参照されるLOBに関連するバッファリング・サブシステムに加えられた変更を、サーバーにフラッシュします。このルーチンでは、バッファのデータをデータベースのLOBに実際に書き込みます。LOBバッファリングは入力LOBロケータに対して使用可能にしてください。
OCILobFlushBuffer()では、リモート・ロケータが渡されるとエラーがスローされます。
このフラッシュ操作のデフォルトでは、別のバッファLOB操作への再割当て用にバッファ・リソースは解放されません。バッファを明示的に解放する場合は、flagパラメータをOCI_LOB_BUFFER_FREEに設定できます。
クライアント・アプリケーションでフラッシュ後のバッファ値を読み取る予定で、あらかじめバッファの現在値が望む値であることがわかっている場合、サーバーからデータを再度読み取る必要はありません。
バッファの解放による影響はユーザーにはほとんど認識されません。ただし、LOB内の同じ範囲に次にアクセスするときに、サーバーをラウンドトリップすることになり、バッファ・リソースの取得およびLOBから読み取られるデータによるバッファの初期化のための追加コストがかかります。このオプションは、オンボード・メモリーが少ないクライアント環境用です。
OCILobGetLength()
この機能は、Oracle Database 11gリリース2 (11.2)より前のリリースでは非推奨です。
用途
LOBの長さを取得します。この関数は非推奨です。OCILobGetLength2()を使用してください。
構文
sword OCILobGetLength ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
ub4 *lenp );パラメータ
関連トピック
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 ); パラメータ
関連トピック
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でのランタイム・データ割当てとピース単位操作」を参照してください
OCILobTrim()
この機能は、Oracle Database 11gリリース2 (11.2)より前のリリースでは非推奨です。
用途
LOB値を短い長さに切り捨てます。この関数は非推奨です。OCILobTrim2()を使用してください。
構文
sword OCILobTrim ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
ub4 newlen );パラメータ
関連トピック
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でのランタイム・データ割当てとピース単位操作」を参照してください
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への書込み操作をオープン文またはクローズ文内に含めることをお薦めします。
関連トピック
非推奨のStreamsアドバンスト・キューイング関数
非推奨のOracle Streamsアドバンスト・キューイング関数について説明します。
表E-8は、この項で説明している非推奨のStreamsアドバンスト・キューイング関数を示しています。
表E-8 非推奨のStreamsアドバンスト・キューイング関数
| 関数 | 用途 |
|---|---|
|
リストのエージェントの代理として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として渡されます。
コメント
これは、リスト内のエージェントについて消費可能なメッセージがあるときに返されるブロック化コールです。待機時間が終了してもメッセージが検出されない場合は、エラーが戻されます。
関連トピック