| Oracle® Call Interfaceプログラマーズ・ガイド 11g リリース2 (11.2) E50264-03 |
|
 前 |
 次 |
表17-1は、この項で説明している文関数を示しています。すべての新規アプリケーションには、「2」で終わる関数を使用します。
表17-1 文関数
| 関数 | 用途 |
|---|---|
|
|
実行する文をサーバーに送信します。 |
|
|
問合せから行をフェッチし、(スクロール可能な)結果セットから行をフェッチします。 |
|
|
ピース単位操作のためのピース情報を取得します。 |
|
|
実行する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 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_STMT_SCROLLABLE_READONLYを除きます。
コメント
この関数は、プリコンパイルされたSQL文を実行するために使用します。アプリケーションは、実行コールを使用して要求をサーバーに対応付けます。
SELECT文が実行されると、選択リストの記述が応答として暗黙的に使用可能になります。この記述は、記述、フェッチおよび型変換定義用にクライアント側にバッファ処理されます。したがって、選択リストの記述は、実行後のみに行うのが最善の方法です。
SELECT文の場合は、一部の結果も暗黙的に使用可能となります。実行終了の時点で行が受け取られ、バッファ処理されます。行数が少ない問合せでは、プリフェッチすることでフェッチの最後に達したときにサーバー内のメモリーが解放され、これによってメモリーの使用量が削減されるように最適化できます。プリフェッチする行数を結果セットごとに設定する属性設定コールが定義されています。
SELECT文では、文ハンドルは、それが実行されたサービス・コンテキストに対する参照を実行終了時に暗黙的に保持しています。サービス・コンテキストの完全性は、ユーザーにメンテナンスの義務があります。暗黙的な参照は、文ハンドルが解放されるまたはフェッチが取り消される、あるいはフェッチ条件の最後に達するまで保持されます。
DDL文を再実行するには、OCIStmtPrepare()またはOCIStmtPrepare2()を使用して文を再度準備する必要があります。
|
注意: OCIStmtExecute()コール前に出力変数がSELECT文に対して定義されている場合は、itersで指定した行数が定義済の出力バッファに直接フェッチされ、プリフェッチ・カウントと同じ数の追加行がプリフェッチされます。追加行がない場合、フェッチはOCIStmtFetch2()または非推奨の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()をコールすることで、結果セット内の行数を判断することもできます。ただし、このコールの応答時間はかなり長くなります。OCI_FETCH_LAST orientationを使用したnrowsが1より大きい値に設定されている場合、nrowsは1であるとみなされます。
リターン・コードは、非推奨のOCIStmtFetch()の場合と同じです。ただし、スクロール可能な文ハンドルのフェッチ(または実行)のたびに、リターン・コードOCI_NO_DATAを含むOER(1403)が戻されます。また、アプリケーションが要求するすべての行がフェッチされるわけではありません。
nrowsパラメータに0 (ゼロ)を設定してOCIStmtFetch2()をコールした場合は、カーソルが取り消されます。
サーバー側のリソースをスクロール・カーソル用に解放するには、スクロール可能な文ハンドルを明示的に取り消すか(つまり、0 (ゼロ)行でフェッチする)、または解放する必要があります。スクロール不可な文ハンドルは、OER(1403)を受け取ると暗黙的に取り消されます。
OCI_ATTR_ROWS_FETCHEDを使用して、最後のフェッチ・コールでユーザーのバッファに正常にフェッチされた行数を検索します。
構文
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のいずれかの事前定義値を戻します。
構文
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構文またはネイティブ構文を指定します。可能な値は次のとおりです。
OCIEnvCreate()コールのmodeに類似しています。ただし、このコールは必然的に継承されたモード設定を上書きできるため、優先度が高くなります。
可能な値はOCI_DEFAULT (デフォルト・モード)のみです。文ハンドルstmtpは、親の環境ハンドルに指定されている内容を使用します。
コメント
このコールは、OCIアプリケーションで実行するSQL文またはPL/SQL文を準備するために使用します。OCIStmtPrepare()コールは、アプリケーション要求を定義します。
modeパラメータは、文の内容がUTF-16でエンコーディングされているかどうかを判断します。文の長さは、コードポイント数またはバイト数で、エンコーディングによって異なります。
文ハンドルは、親の環境ハンドルからエンコーディング設定を継承しますが、このコールのmodeによって、文ハンドル自体のエンコーディング設定も変更できます。
後続のバインド・コールで初期化されるこの文のデータ値は、この文ハンドルの設定をデフォルトとして使用するバインド・ハンドル内に格納されます。
このコールは、この文ハンドルと特定のサーバー間の対応付けは作成しません。
DDL文を再実行する前に、この関数の2回目のコールを実行してください。
構文
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で終了)。
文のテキストの長さです。
文キャッシュの場合のみ指定します。文キャッシュ内の文を検索するために使用されるキーです。このキーが指定されると、文のテキストおよび他のパラメータは無視され、このキーのみに基づいて検索が行われます。
文キャッシュの場合のみ指定します。キーの長さです。
V7構文またはネイティブ構文を指定します。可能な値は次のとおりです。
この関数では、文キャッシュを使用することも使用しないことも可能です。使用するかどうかは、接続またはセッション・プールの作成時に決まります。セッションに対してキャッシュが使用可能な場合はセッション内のすべての文がキャッシュ可能で、キャッシュが使用可能でない場合はすべての文がキャッシュされません。
有効なモードは次のとおりです。
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()で検索します。
構文
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バインド変数でのみ使用されます。
インジケータです。sb2値へのポインタまたは名前付きデータ型(SQLT_NTY)とREF (SQLT_REF)用のインジケータ構造体へのポインタです。つまり、データ型に応じて、*indpはsb2またはvoid *になります。
リターン・コードです。
