| Oracle® Call Interfaceプログラマーズ・ガイド 12c リリース1 (12.1) B72465-07 |
|
 前 |
 次 |
文関数をリストし、説明します。
表17-1は、この項で説明している文関数を示しています。すべての新規アプリケーションには、「2」で終わる関数を使用します。
表17-1 文関数
| 関数 | 用途 |
|---|---|
実行する文をサーバーに送信します。 |
|
問合せから行をフェッチし、(スクロール可能な)結果セットから行をフェッチします。 |
|
実行された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 Databaseへの複数サービス・コンテキストによって、データベースのコミット済データに関して同じ一貫性のあるスナップショットを参照できます。ただし、同じスナップショットを使用している場合でも、1つのコンテキスト内でコミットされていないデータは、他のコンテキストでは認識されません。
このパラメータは、オプションです。指定する場合は、OCI_DTYPE_SNAP型の記述子を指示する必要があります。この記述子には、現行のOracle Databaseのシステム変更番号(SCN)が暗号化されて格納されており、後続のOCIStmtExecute()コールのsnap_inへの入力値として使用できます。「スナップショットが古すぎます」というエラーを回避するため、この記述子は必要以上に長く使用しないでください。
次のモードが有効です。
OCI_BATCH_ERRORS - このモードの詳細は、「バッチ・エラー・モードの使用」を参照してください。
OCI_COMMIT_ON_SUCCESS - このモードで文を実行した場合、実行が正常に終了すると、実行後にカレント・トランザクションがコミットされます。
OCI_DEFAULT - このモードでOCIStmtExecute()をコールすると文が実行されます。また、選択リストに関する記述情報が暗黙的に戻されます。
OCI_DESCRIBE_ONLY - このモードは、実行前に問合せを記述するユーザー用です。OCIStmtExecute()をこのモードでコールすると、文は実行されませんが、選択リスト記述は戻されます。パフォーマンスを最大にするために、アプリケーションではデフォルト・モードで文を実行し、実行に伴う暗黙的な記述を使用することをお薦めします。
OCI_EXACT_FETCH - アプリケーションが前もってフェッチしている行数を正確に認識している場合に使用します。このモードは、Oracle Databaseリリース8以上のモードではプリフェッチをオフにするため、実行コールの前に定義する必要があります。このmodeを使用すると、必要な行のフェッチ後にカーソルが消されるため、サーバー側のリソース使用率が低下する場合があります。
OCI_PARSE_ONLY - このモードを使用すると、ユーザーは実行前に問合せを解析できます。このモードで実行すると問合せが解析され、SQL内に解析エラーがある場合は、そのエラーが戻されます。このモードではサーバーへの追加ラウンドトリップが発生することに注意する必要があります。パフォーマンスを向上させるには、バンドル操作の一部として文を解析するデフォルト・モードで、文を実行することをお薦めします。
OCI_STMT_SCROLLABLE_READONLY - 結果セットをスクロール可能に設定する場合は必須です。結果セットは更新できません。このモードの詳細は、「結果のフェッチについて」を参照してください。このモードは、他のモードとの併用はできません。
OCI_RETURN_ROW_COUNT_ARRAY - このモードを使用すると、ユーザーは反復ごとにDML行カウントを取得できます。DMLではない文でこのモードを渡すとエラーが発生します。詳細は、「文ハンドル属性」を参照してください。このモードは、OCI_BATCH_ERRORSとともに使用できます。
これらのモードは相互排他的ではなく、組み合せて使用できます。ただし、OCI_STMT_SCROLLABLE_READONLYを除きます。
コメント
この関数は、プリコンパイルされたSQL文を実行するために使用します。アプリケーションは、実行コールを使用して要求をサーバーに対応付けます。
SELECT文が実行されると、選択リストの記述が応答として暗黙的に使用可能になります。この記述は、記述、フェッチおよび型変換定義用にクライアント側にバッファ処理されます。したがって、選択リストの記述は、実行後のみに行うのが最善の方法です。
関連項目:
SELECT文の場合は、一部の結果も暗黙的に使用可能となります。実行終了の時点で行が受け取られ、バッファ処理されます。行数が少ない問合せでは、プリフェッチすることでフェッチの最後に達したときにサーバー内のメモリーが解放され、これによってメモリーの使用量が削減されるように最適化できます。プリフェッチする行数を結果セットごとに設定する属性設定コールが定義されています。
SELECT文では、文ハンドルは、それが実行されたサービス・コンテキストに対する参照を実行終了時に暗黙的に保持しています。サービス・コンテキストの完全性は、開発者にメンテナンスの責任があります。暗黙的な参照は、文ハンドルが解放されるまたはフェッチが取り消される、あるいはフェッチ条件の最後に達するまで保持されます。
DDL文を再実行するには、OCIStmtPrepare2()を使用して文を再度準備する必要があります。
注意:
OCIStmtExecute()コール前に出力変数がSELECT文に対して定義されている場合は、itersで指定した行数が定義済の出力バッファに直接フェッチされ、プリフェッチ・カウントと同じ数の追加行がプリフェッチされます。追加行がない場合、フェッチはOCIStmtFetch2()または非推奨のOCIStmtFetch()をコールしないで完了します。
関連項目:
(スクロール可能な)結果セットから行をフェッチします。
用途
(スクロール可能な)結果セットから行をフェッチします。非推奨になった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パラメータで指定)をフェッチします。
コメント
フェッチ・コールは、非推奨の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_UB8_ROW_COUNTには、フェッチされた最上位の行の絶対値が含まれます。
OCI_FETCH_ABSOLUTEとOCI_FETCH_RELATIVEを除くすべてのorientationモードでは、fetchOffset値は無視されます。
このコールを使用すると、OCI_FETCH_LASTを使用してから、OCI_ATTR_CURRENT_POSITIONに対してOCIAttrGet()をコールすることで、結果セット内の行数を判断することもできます。ただし、このコールの応答時間はかなり長くなります。OCI_FETCH_LAST orientationを使用したnrowsが1より大きい値に設定されている場合、nrowsは1であるとみなされます。
リターン・コードは、非推奨のOCIStmtFetch()の場合と同じです。ただし、スクロール可能な文ハンドルのフェッチ(または実行)のたびに、リターン・コードOCI_NO_DATAを含むOER(1403)が戻されます。また、アプリケーションが要求するすべての行がフェッチされるわけではありません。
nrowsパラメータに0 (ゼロ)を設定してOCIStmtFetch2()をコールした場合は、カーソルが取り消されます。
サーバー側のリソースをスクロール・カーソル用に解放するには、スクロール可能な文ハンドルを明示的に取り消すか(つまり、0 (ゼロ)行でフェッチする)、または解放する必要があります。スクロール不可な文ハンドルは、OER(1403)を受け取ると暗黙的に取り消されます。
OCI_ATTR_ROWS_FETCHEDを使用して、最後のフェッチ・コールでユーザーのバッファに正常にフェッチされた行数を検索します。
用途
実行されたPL/SQL文ハンドルから暗黙的な結果を戻します。
構文
sword OCIStmtGetNextResult (OCIStmt *stmthp,
OCIError *errhp,
void **result,
ub4 *rtype,
ub4 mode)
パラメータ
実行された文ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
実行されたPL/SQL文からの次の暗黙的な結果です。
暗黙的な結果の型です。可能な値はOCI_RESULT_TYPE_SELECTのみです。
可能な値はOCI_DEFAULT (デフォルト・モード)のみです。
コメント
各OCIStmtGetNextResult()へのコールでは、PL/SQLプロシージャまたはブロックから戻される順に暗黙的な結果が1つずつ取り出されます。結果がない場合は、OCI_NO_DATAが戻されます。rtypeがOCI_RESULT_TYPE_SELECTの場合、戻された結果をOCI文としてキャストでき、OCIによって割り当てられます。アプリケーションで標準のOCI定義およびフェッチ・コールを行い、暗黙的な結果セットから行をフェッチできます。戻されたOCI文ハンドルは明示的に解放できません。トップレベルの文ハンドルが解放されると、すべての暗黙的な結果セットが自動的にクローズされます。
この文ハンドル属性の詳細は、「OCI_ATTR_IMPLICIT_RESULT_COUNT」を参照してください。これは、トップレベルのOCI文ハンドルで使用可能な暗黙的結果の合計数を戻します。
戻り値
次のいずれかが戻されます。
OCI_ERROR
OCI_SUCCESS
OCI_NO_DATA - すべての暗黙的な結果がトップレベルの文ハンドルから戻された場合
関連関数
ピース単位操作用のピース情報を戻します。
用途
ピース単位操作用のピース情報を戻します。
構文
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()から、バインド・ハンドルまたは定義ハンドル、反復、索引番号、ピース情報などの関連情報が戻されます。
実行するSQL文またはPL/SQL文を準備します。
用途
実行するSQL文またはPL/SQL文を準備します。有効な文キャッシュがある場合は、それを使用することもできます。
すべてのOCIアプリケーションで、非推奨コールOCIStmtPrepare()ではなくOCIStmtPrepare2()を使用することをお薦めします。
構文
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で終了)。
文のテキストの長さです。
文キャッシュの場合のみ指定します。文キャッシュ内の文を検索するために使用されるキーです。このキーが指定されると、文のテキストおよび他のパラメータは無視され、このキーのみに基づいて検索が行われます。
文キャッシュの場合のみ指定します。キーの長さです。
OCI_V7_SYNTAX - V7 Oracle解析構文。
OCI_NTV_SYNTAX - サーバーのバージョンに依存する構文。
OCI_FOREIGN_SYNTAX - セッションのSQL翻訳プロファイルに従って翻訳される文を指定します。
この関数では、文キャッシュを使用することも使用しないことも可能です。使用するかどうかは、接続またはセッション・プールの作成時に決まります。セッションに対してキャッシュが使用可能な場合はセッション内のすべての文がキャッシュ可能で、キャッシュが使用可能でない場合はすべての文がキャッシュされません。
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()で検索します。
OCI_PREP2_IMPL_RESULTS_CLIENT - このコールが外部プロシージャで作成され、暗黙的な結果を処理する必要がある場合、これらのモードはOCI_PREP2_IMPL_RESULTS_CLIENTとして渡される必要があります。詳細は、「暗黙的な結果のOCIサポート」を参照してください。
OCIStmtPrepare2()のコールで取得した文ハンドルを解放します。
用途
OCIStmtPrepare2()のコールで取得した文ハンドルを解放します。
構文
sword OCIStmtRelease ( OCIStmt *stmthp,
OCIError *errhp,
const OraText *key,
ub4 keylen,
ub4 mode );
パラメータ
OCIStmtPrepare2()によって戻される文ハンドルです。
診断に使用するエラー・ハンドルです。
文キャッシュの場合のみ有効です。キャッシュ内の文に関連付けられているキーです。これは、コール元によって渡されるSQL文字列です。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バインド変数でのみ使用されます。
コメント
実行コールにより、動的IN/OUTバインド値またはピースを取得するOCI_NEED_DATAが戻されると、OCIStmtSetPieceInfo()により、バッファ、長さ、現在処理中のピース、インジケータおよびこの列のリターン・コードなどのピース情報が設定されます。
