| Oracle Call Interfaceプログラマーズ・ガイド 11g リリース1（11.1） E05677-02 |
|
 戻る |
 次へ |
この項では、文関数について説明します。
表17-2 文関数
| 関数 | 用途 |
|---|---|
|
|
実行する文をサーバーに送信します。 |
|
|
問合せから行をフェッチします（非推奨）。 |
|
|
問合せから行をフェッチします。 |
|
|
ピース単位操作のためのピース情報を取得します。 |
|
|
実行するSQL文またはPL/SQL文を準備します。 |
|
|
実行するSQL文またはPL/SQL文を準備します。 |
|
|
文ハンドルを解放します。 |
|
|
ピース単位操作のためのピース情報を設定します。 |
用途
このコールは、アプリケーション要求をサーバーに対応付けます。
構文
sword OCIStmtExecute ( OCISvcCtx *svchp,
OCIStmt *stmtp,
OCIError *errhp,
ub4 iters,
ub4 rowoff,
const OCISnapshot *snap_in,
OCISnapshot *snap_out,
ub4 mode );
パラメータ
サービス・コンテキスト・ハンドルです。
文ハンドルです。サーバーで実行される文および対応付けられたデータを定義します。svchpがOracle7 Serverを指し示しているときに、リリース8.x以上でのみサポートされるデータ型のバインドを持つ文ハンドルを渡すと無効になります。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
SELECT文以外の場合、この文が実行される回数は、iters - rowoffの場合と同じになります。
SELECT文では、itersが0（ゼロ）以外の場合は、文ハンドルに対する定義を行う必要があります。実行すると、itersが事前定義バッファにフェッチされ、プリフェッチ行カウントに従ってさらに行がプリフェッチされます。SELECT文によって取り出される行数が不明の場合は、itersを0（ゼロ）に設定します。
この関数は、SELECT文以外に対してiters=0の場合は、エラーを戻します。
|
注意: 配列DML操作の場合は、 iters <= 32767を設定することで、より高いパフォーマンスが得られます。 |
この複数行実行に関連する配列バインドのデータが始まる開始索引です。
このパラメータはオプションです。指定する場合は、OCI_DTYPE_SNAP型のスナップショット記述子を指示する必要があります。この記述子の内容は、直前のコールのsnap_outパラメータから取得する必要があります。この記述子は、SQLがSELECTでない場合は無視されます。この機能を使用すると、Oracleへの複数サービス・コンテキストによって、データベースのコミット済データに関して同じ一貫性のあるスナップショットを参照できます。ただし、あるコンテキストでコミットされていないデータは、同じスナップショットを使用しても別のコンテキストで参照できません。
このパラメータはオプションです。指定する場合は、OCI_DTYPE_SNAP型の記述子を指示する必要があります。この記述子には、現行のOracleのシステム変更番号が暗号化されて格納されており、後続のOCIStmtExecute()コールのsnap_inへの入力値として使用できます。この記述子は必要以上に長く使用しないでください。「スナップショットが古すぎます」というエラーが発生します。
次のモードが有効です。
OCI_BATCH_ERRORS− このモードの詳細は、「バッチ・エラー・モード」を参照してください。
OCI_COMMIT_ON_SUCCESS− このモードで文を実行した場合、実行が正常に終了すると、実行後にカレント・トランザクションがコミットされます。
OCI_DEFAULT− このモードでOCIStmtExecute()をコールすると文が実行されます。また、選択リストに関する記述情報が暗黙的に戻されます。
OCI_DESCRIBE_ONLY− このモードは、実行前に問合せを記述するユーザー用です。OCIStmtExecute()をこのモードでコールすると、文は実行されませんが、選択リスト記述は戻されます。パフォーマンスを最大にするために、アプリケーションではデフォルト・モードで文を実行し、実行に伴う暗黙的な記述を使用することをお薦めします。
OCI_EXACT_FETCH− アプリケーションでフェッチされる行数があらかじめ正確にわかっているときに使用します。このモードにより、Oracleリリース8.x以上のモードのプリフェッチがオフになります。また、実行コールの前に定義されている必要があります。このモードを使用すると要求した行がフェッチされた後カーソルが取り消されるため、サーバー側のリソース使用量を削減できます。
OCI_PARSE_ONLY− このモードを使用すると、ユーザーは実行前に問合せを解析できます。このモードで実行すると問合せが解析され、SQL内に解析エラーがある場合は、そのエラーが戻されます。このモードではサーバーへの追加ラウンドトリップが発生することに注意する必要があります。パフォーマンスを向上させるには、バンドル操作の一部として文を解析するデフォルト・モードで、文を実行することをお薦めします。
OCI_STMT_SCROLLABLE_READONLY− 結果セットをスクロール可能に設定する場合は必須です。結果セットは更新できません。詳細は、「結果のフェッチ」を参照してください。他のモードとの併用はできません。
これらのモードは相互排他的ではなく、組み合せて使用できます。ただし、OCI_STMT_SCROLLABLE_READONLYを除きます。
コメント
この関数は、プリコンパイルされたSQL文を実行するために使用します。アプリケーションは、実行コールを使用して要求をサーバーに対応付けます。
SELECT文が実行されると、選択リストの記述が応答として暗黙的に使用可能になります。この記述は、記述、フェッチおよび型変換定義用にクライアント側にバッファ処理されます。したがって、選択リストの記述は、実行後のみに行うのが最善の方法です。
SELECT文の場合は、一部の結果も暗黙的に使用可能となります。実行終了の時点で行が受け取られ、バッファ処理されます。行数が少ない問合せでは、プリフェッチすることでフェッチの最後に達したときにサーバー内のメモリーが解放され、これによってメモリーの使用量が削減されるように最適化できます。プリフェッチする行数を結果セットごとに設定する属性設定コールが定義されています。
SELECT文では、文ハンドルは、それが実行されたサービス・コンテキストに対する参照を実行終了時に暗黙的に保持しています。サービス・コンテキストの完全性は、ユーザーに保守の義務があります。暗黙的な参照は、文ハンドルが解放されるまたはフェッチが取り消される、あるいはフェッチ条件の最後に達するまで保持されます。
DDL文を再実行するには、OCIStmtPrepare()またはOCIStmtPrepare2()を使用して文を再度プリコンパイルする必要があります。
|
注意: OCIStmtExecute()のコール前にSELECT文に対して出力変数を定義すると、itersによって指定された行数が定義済出力バッファに直接フェッチされ、プリフェッチ件数と同じ数の追加行がプリフェッチされます。追加行がない場合、フェッチはOCIStmtFetch()をコールしないで完了します。 |
関連関数
用途
問合せから行をフェッチします。新しいフェッチ・コールOCIStmtFetch2()の使用をお薦めします。このコールは非推奨です。
構文
sword OCIStmtFetch ( OCIStmt *stmtp,
OCIError *errhp,
ub4 nrows,
ub2 orientation,
ub4 mode );
パラメータ
文（アプリケーション要求）ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
現行の位置からフェッチされる行数です。
リリース8.1.7以下で使用可能な値は、OCI_FETCH_NEXT（デフォルト値）のみです。
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を使用して、最後のフェッチ・コールでユーザーのバッファに正常にフェッチされた行数を検索します。
関連関数
用途
このコールは、（スクロール可能な）結果セットから行をフェッチします。非推奨になったOCIStmtFetch()のかわりに、このフェッチ・コールを使用することをお薦めします。
構文
sword OCIStmtFetch2 ( OCIStmt *stmthp,
OCIError *errhp,
ub4 nrows,
ub2 orientation,
sb4 fetchOffset,
ub4 mode );
パラメータ
これは（スクロール可能な）結果セットの文ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
現行の位置からフェッチされる行数です。
受け入れ可能な値は、次のとおりです。
OCI_DEFAULT− OCI_FETCH_NEXTと同じ結果が得られます。
OCI_FETCH_CURRENT− 現在行を取得します。
OCI_FETCH_NEXT− 現行位置の次の行を取得します。これは、デフォルトです（OCI_DEFAULTと同じ結果が得られます）。スクロール不可な文ハンドルに使用します。
OCI_FETCH_FIRST− 結果セットの最初の行を取得します。
OCI_FETCH_LAST− 結果セットの最後の行を取得します。
OCI_FETCH_PRIOR− 結果セットの現在行の前の行に結果セットを位置指定します。このモードを使用して、前の行からも複数の行をフェッチできます。
OCI_FETCH_ABSOLUTE− 絶対的な位置指定を使用して結果セットの行番号（fetchOffsetパラメータで指定）をフェッチします。
OCI_FETCH_RELATIVE− 相対的な位置指定を使用して結果セットの行番号（fetchOffsetパラメータで指定）をフェッチします。
現在行の位置を変更するためにorientationパラメータと併用するオフセットです。
OCI_DEFAULTを渡します。
コメント
フェッチ・コールは、OCIStmtFetch()コールにfetchOffsetパラメータを追加した場合と同じように機能します。スクロール可能かどうかに関係なく、すべての文ハンドルに使用できます。スクロール不可な文ハンドルの場合、唯一の受け入れ可能なorientation値は、OCI_FETCH_NEXTです。fetchOffsetパラメータは無視されます。
新しいアプリケーションには、この新しいコールOCIStmtFetch2()の使用をお薦めします。
orientationがOCI_FETCH_RELATIVEに設定されているfetchOffsetは、次のすべてのコールと等価です。
fetchOffsetの値が0（ゼロ）のOCI_FETCH_CURRENT。
fetchOffsetの値が1のOCI_FETCH_NEXT。
fetchOffsetの値が-1のOCI_FETCH_PRIOR。
OCI_ATTR_ROW_COUNTには、フェッチされた最上位の行の絶対値が含まれます。
OCI_FETCH_ABSOLUTEとOCI_FETCH_RELATIVEを除くすべてのorientationモードでは、fetchOffset値は無視されます。
このコールを使用すると、OCI_FETCH_LASTを使用してから、OCI_ATTR_CURRENT_POSITIONに対してOCIAttrGet()をコールすることで、結果セット内の行数を検索することもできます。ただし、このコールの応答時間はかなり長くなります。
リターン・コードは、OCIStmtFetch()の場合と同じです。ただし、スクロール可能な文ハンドルのフェッチ（または実行）のたびに、リターン・コードOCI_NO_DATAを含むOER（1403）が戻されます。また、アプリケーションが要求するすべての行がフェッチされるわけではありません。
nrowsパラメータに0（ゼロ）を設定してOCIStmtFetch2()をコールした場合は、カーソルが取り消されます。
サーバー側のリソースをスクロール・カーソル用に解放するには、スクロール可能な文ハンドルを明示的に取り消すか（つまり、0（ゼロ）行でフェッチする）、または解放する必要があります。スクロール不可な文ハンドルは、OER（1403）を受け取ると暗黙的に取り消されます。
OCI_ATTR_ROWS_FETCHEDを使用して、最後のフェッチ・コールでユーザーのバッファに正常にフェッチされた行数を検索します。
関連関数
OCIStmtExecute()、OCIBindByPos()
用途
ピース単位操作用のピース情報を戻します。
構文
sword OCIStmtGetPieceInfo( const OCIStmt *stmtp,
OCIError *errhp,
void **hndlpp,
ub4 *typep,
ub1 *in_outp,
ub4 *iterp,
ub4 *idxp,
ub1 *piecep );
パラメータ
戻されたOCI_NEED_DATAが実行される際の文です。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
バインド、バインドの定義ハンドル、またはランタイム・データが要求または提供されている定義のいずれかへのポインタを戻します。
hndlppが指し示すハンドルのタイプです。タイプには、OCI_HTYPE_BIND（バインド・ハンドル用）またはOCI_HTYPE_DEFINE（定義ハンドル用）があります。
INバインド値に対してデータが必要な場合、OCI_PARAM_INを戻します。データがOUTバインド変数または定義位置値として取得できる場合はOCI_PARAM_OUTが戻ります。
複数行操作の行数を戻します。
PL/SQL配列バインド操作の配列要素の索引です。
OCI_ONE_PIECE、OCI_FIRST_PIECE、OCI_NEXT_PIECEまたはOCI_LAST_PIECEのいずれかの事前定義値を戻します。
コメント
実行コールまたはフェッチ・コールからOCI_NEED_DATAが戻され、動的なバインドまたは定義の値、あるいはピースが取得または戻されると、OCIStmtGetPieceInfo()から、バインド・ハンドルまたは定義ハンドル、反復、索引番号、ピース情報などの関連情報が戻されます。
関連関数
OCIArrayDescriptorAlloc()、OCIAttrSet()、OCIStmtExecute()、OCIStmtFetch()、OCIStmtSetPieceInfo()
用途
このコールは、実行するSQL文またはPL/SQL文を準備します。
構文
sword OCIStmtPrepare ( OCIStmt *stmtp,
OCIError *errhp,
const OraText *stmt,
ub4 stmt_len,
ub4 language,
ub4 mode );
パラメータ
実行対象の文に関連付けられた文ハンドルです。デフォルトでは、導出元の環境ハンドルのエンコーディング設定が含まれています。文をUTF-16エンコーディングで準備できるのは、UTF-16環境のみです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
実行されるSQL文またはPL/SQL文です。NULLで終了する文字列にしてください。つまり、最後の文字は、エンコーディングによってはNULLバイトの数値です。文は、OCIEnvNlsCreate()の直前のコールのcharsetパラメータで指定されたエンコーディングであることが必要です。
パラメータを必ず（text *）にキャストしてください。文がUTF-16で準備されると、バインド・バッファと定義バッファのキャラクタ・セットは、UTF-16にデフォルト設定されます。
文の長さです。エンコーディングによって、文字数またはバイト数の単位になります。0（ゼロ）以外にする必要があります。
V7構文またはネイティブ構文を指定します。可能な値は次のとおりです。
OCI_V7_SYNTAX− V7 Oracle解析構文。
OCI_NTV_SYNTAX− サーバーのバージョンに依存する構文。
OCIEnvCreate()コールのmodeに類似しています。ただし、このコールは必然的に継承されたモード設定を上書きできるため、優先度が高くなります。
可能な値は次の値のみです。
OCI_DEFAULT− デフォルト・モード。文ハンドルstmtpは、親の環境ハンドルに指定されている内容を使用します。
コメント
このコールは、OCIアプリケーションで実行するSQL文またはPL/SQL文を準備するために使用します。OCIStmtPrepare()コールは、アプリケーション要求を定義します。
modeパラメータは、文の内容がUTF-16でエンコーディングされているかどうかを判断します。文の長さは、コードポイント数またはバイト数で、エンコーディングによって異なります。
文ハンドルは、親の環境ハンドルからエンコーディング設定を継承しますが、このコールのmodeによって、文ハンドル自体のエンコーディング設定も変更できます。
後続のバインド・コールで初期化されるこの文のデータ値は、この文ハンドルの設定をデフォルトとして使用するバインド・ハンドル内に格納されます。
このコールは、この文ハンドルと特定のサーバー間の対応付けは作成しません。
DDL文を再実行する前に、この関数の2回目のコールを実行してください。
関連関数
OCIArrayDescriptorAlloc()、OCIStmtExecute()
用途
このコールは、実行するSQL文またはPL/SQL文を準備します。有効な文キャッシュがある場合は、それを使用することもできます。
構文
sword OCIStmtPrepare2 ( OCISvcCtx *svchp,
OCIStmt **stmthp,
OCIError *errhp,
const OraText *stmttext,
ub4 stmt_len,
const OraText *key,
ub4 keylen,
ub4 language,
ub4 mode );
パラメータ
文に関連付けるサービス・コンテキストです。
診断のためのエラー・ハンドルへのポインタです。
戻される文ハンドルへのポインタです。
文のテキストです。stmttextのセマンティックは、OCIStmtPrepare()のセマンティックと同じです（つまり、文字列はNULLで終了）。
文のテキストの長さです。
文キャッシュの場合のみ指定します。キャッシュ内の戻された文に対するキーです。このパラメータは、その後のOCIStmtPrepare2()のコールに使用できます。この場合、文のテキストや関連するパラメータの指定は不要です。このキーが指定されると、文のテキストおよび他のパラメータは無視され、このキーのみに基づいて検索が行われます。
文キャッシュの場合のみ指定します。キーの長さです。
V7構文またはネイティブ構文を指定します。可能な値は次のとおりです。
OCI_V7_SYNTAX− V7 Oracle解析構文。
OCI_NTV_SYNTAX− サーバーのバージョンに依存する構文。
この関数では、文キャッシュを使用することも使用しないことも可能です。使用するかどうかは、接続またはセッション・プールの作成時に決まります。セッションに対してキャッシュが使用可能な場合はセッション内のすべての文がキャッシュ可能で、キャッシュが使用可能でない場合はすべての文がキャッシュされません。
次のモードが有効です。
OCI_DEFAULT− キャッシュしない場合は、これが唯一有効な設定です。文がキャッシュ内に見つからなかった場合は、文ハンドルが新しく割り当てられ、実行用の文ハンドルが準備されます。文がキャッシュで見つかった場合は、状況に従って次のようになります。
テキストのみが指定された場合: 新しい文が割り当てられて準備され、戻されます。タグはNULLになります。OCI_SUCCESSが戻ります。
タグのみが指定された場合: stmthpはNULLになります。OCI_ERRORが戻ります。
テキストとキーの両方が指定された場合: 新しい文が割り当てられて準備され、戻されます。タグはNULLになります。戻された文はタグがNULLである点で要求した文とは異なるため、OCI_SUCCESS_WITH_INFOが戻ります。
OCI_PREP2_CACHE_SEARCHONLY: このケースで、文が見つからなかった（NULLの文ハンドルが戻された）場合は、さらに処置が必要です。文が見つかった場合は、OCI_SUCCESSが戻ります。見つからない場合は、OCI_ERRORが戻ります。
OCI_PREP2_GET_PLSQL_WARNINGS− セッションで警告が有効になっており、PL/SQLプログラムがコンパイルされて警告が発行された場合、実行の戻りステータスはOCI_SUCCESS_WITH_INFOになります。警告に対応する新しいエラー番号をOCIErrorGet()で検索します。
関連関数
用途
OCIStmtPrepare2()のコールで取得した文ハンドルを解放します。
構文
sword OCIStmtRelease ( OCIStmt *stmthp,
OCIError *errhp,
const OraText *key,
ub4 keylen,
ub4 mode );
パラメータ
OCIStmtPrepare2()によって戻される文ハンドルです。
診断に使用するエラー・ハンドルです。
文キャッシュの場合のみ有効です。キャッシュ内の文に関連付けられているキーです。OCIStmtPrepare2()によって戻されるキー、または新しいキーを指定できます。NULLのキーが渡された場合、文はタグ付けされません。
文キャッシュの場合のみ有効です。キーの長さです。
次のモードが有効です。
OCI_DEFAULT
OCI_STRLS_CACHE_DELETE− 文キャッシュの場合のみ有効です。文は、それ以上キャッシュに保持されません。
関連関数
用途
ピース単位操作用のピース情報を設定します。
構文
sword OCIStmtSetPieceInfo ( void *hndlp,
ub4 type,
OCIError *errhp,
const void *bufp,
ub4 *alenp,
ub1 piece,
const void *indp,
ub2 *rcodep );
パラメータ
バインド・ハンドルまたは定義ハンドルです。
ハンドルのタイプです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
INバインド変数の場合はデータ値またはピースを含む記憶域のポインタです。それ以外の場合、bufpはOUTバインドおよび定義変数に対してピースまたはデータ値を取得するための記憶域のポインタです。名前付きデータ型またはREFの場合は、そのオブジェクトまたはREFへのポインタが戻ります。
ピースまたは値の長さです。同じSQL文を実行する間にこのパラメータを変更しないでください。
ピース・パラメータです。有効な値は次のとおりです。
OCI_ONE_PIECE
OCI_FIRST_PIECE
OCI_NEXT_PIECE
OCI_LAST_PIECE
このパラメータは、INバインド変数でのみ使用されます。
インジケータです。sb2値へのポインタまたは名前付きデータ型（SQLT_NTY）とREF（SQLT_REF）用のインジケータ構造体へのポインタです。つまり*indpは、データ型に応じて、sb2またはvoid *になります。
リターン・コードです。
コメント
実行コールにより、動的IN/OUTバインド値またはピースを取得するOCI_NEED_DATAが戻されると、OCIStmtSetPieceInfo()により、バッファ、長さ、現在処理中のピース、インジケータおよびこの列のリターン・コードなどのピース情報が設定されます。
関連関数
OCIArrayDescriptorAlloc()、OCIAttrSet()、OCIStmtExecute()、OCIStmtFetch()、OCIStmtGetPieceInfo()
