文関数
文関数をリストし、説明します。
表26-1は、この項で説明している文関数を示しています。すべての新規アプリケーションには、「2」で終わる関数を使用します。
表26-1 文関数
関数 | 用途 |
---|---|
実行する文をサーバーに送信します。 |
|
問合せから行をフェッチし、(スクロール可能な)結果セットから行をフェッチします。 |
|
実行されたPL/SQL文ハンドルから暗黙的な結果を戻します。 |
|
ピース単位操作のためのピース情報を取得します。 |
|
実行するSQL文またはPL/SQL文を準備します。有効な文キャッシュがある場合は、それを使用することもできます。 |
|
文ハンドルを解放します。 |
|
ピース単位操作のためのピース情報を設定します。 |
OCIStmtExecute()
アプリケーション要求をサーバーに対応付けます。
用途
アプリケーション要求をサーバーに対応付けます。
構文
sword OCIStmtExecute ( OCISvcCtx *svchp, OCIStmt *stmtp, OCIError *errhp, ub4 iters, ub4 rowoff, const OCISnapshot *snap_in, OCISnapshot *snap_out, ub4 mode );
パラメータ
- svchp (IN/OUT)
-
サービス・コンテキスト・ハンドルです。
- stmtp (IN/OUT)
-
文ハンドルです。サーバーで実行される文および対応付けられたデータを定義します。
svchp
がOracle7 Serverを指し示しているときに、リリース8.x以上でのみサポートされるデータ型のバインドを持つ文ハンドルを渡すと無効になります。 - errhp (IN/OUT)
-
エラー発生時の診断情報のために
OCIErrorGet()
に渡すエラー・ハンドルです。 - iters (IN)
-
SELECT
文以外の場合、この文が実行される回数は、iters
-rowoff
の場合と同じになります。SELECT
文では、iters
が0(ゼロ)以外の場合は、文ハンドルに対する定義を行う必要があります。実行すると、iters
が事前定義バッファにフェッチされ、プリフェッチ行カウントに従ってさらに行がプリフェッチされます。SELECT
文によって取り出される行数が不明の場合は、iters
を0 (ゼロ)に設定します。この関数は、
SELECT
文以外に対してiters
=0の場合は、エラーを戻します。この関数は、DDL文に対して
iters
が1以外の場合はエラーを戻します。ノート:
配列DML操作の場合は、
iters
<= 32767を設定することで、より高いパフォーマンスが得られます。 - rowoff (IN)
-
この複数行実行に関連する配列バインドのデータが始まる開始索引です。
- snap_in (IN)
-
このパラメータはオプションです。指定する場合は、
OCI_DTYPE_SNAP
型のスナップショット記述子を指示する必要があります。この記述子の内容は、直前のコールのsnap_out
パラメータから取得する必要があります。この記述子は、SQLがSELECT
文でない場合は無視されます。この機能を使用すると、Oracle Databaseへの複数サービス・コンテキストによって、データベースのコミット済データに関して同じ一貫性のあるスナップショットを参照できます。ただし、同じスナップショットを使用している場合でも、1つのコンテキスト内でコミットされていないデータは、他のコンテキストでは認識されません。 - snap_out (OUT)
-
このパラメータはオプションです。指定する場合は、
OCI_DTYPE_SNAP
型の記述子を指示する必要があります。この記述子には、現行のOracle Databaseのシステム変更番号(SCN)が暗号化されて格納されており、後続のOCIStmtExecute()
コールのsnap_in
への入力値として使用できます。「スナップショットが古すぎます」というエラーを回避するため、この記述子は必要以上に長く使用しないでください。 - mode (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()をコールしないで完了します。
関連トピック
関連項目:
OCIStmtFetch2()
(スクロール可能な)結果セットから行をフェッチします。
用途
(スクロール可能な)結果セットから行をフェッチします。非推奨になったOCIStmtFetch()
のかわりに、このフェッチ・コールを使用することをお薦めします。
構文
sword OCIStmtFetch2 ( OCIStmt *stmthp, OCIError *errhp, ub4 nrows, ub2 orientation, sb4 fetchOffset, ub4 mode );
パラメータ
- stmthp (IN/OUT)
-
これは(スクロール可能な)結果セットの文ハンドルです。
- errhp (IN/OUT)
-
エラー発生時の診断情報のために
OCIErrorGet()
に渡すエラー・ハンドルです。 - nrows (IN)
-
現行の位置からフェッチされる行数です。
- orientation (IN)
-
受け入れ可能な値は、次のとおりです。
-
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
を使用して、最後のフェッチ・コールでユーザーのバッファに正常にフェッチされた行数を検索します。
OCIStmtGetNextResult()
実行されたPL/SQL文ハンドルから暗黙的な結果を戻します。
用途
実行されたPL/SQL文ハンドルから暗黙的な結果を戻します。
構文
sword OCIStmtGetNextResult (OCIStmt *stmthp, OCIError *errhp, void **result, ub4 *rtype, ub4 mode)
パラメータ
コメント
各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
- すべての暗黙的な結果がトップレベルの文ハンドルから戻された場合
関連トピック
OCIStmtGetPieceInfo()
ピース単位操作用のピース情報を戻します。
用途
ピース単位操作用のピース情報を戻します。
構文
sword OCIStmtGetPieceInfo( const OCIStmt *stmtp, OCIError *errhp, void **hndlpp, ub4 *typep, ub1 *in_outp, ub4 *iterp, ub4 *idxp, ub1 *piecep );
パラメータ
- stmtp (IN)
-
戻された
OCI_NEED_DATA
が実行される際の文です。 - errhp (OUT)
-
エラー発生時の診断情報のために
OCIErrorGet()
に渡すエラー・ハンドルです。 - hndlpp (OUT)
-
バインド、バインドの定義ハンドル、またはランタイム・データが要求または提供されている定義のいずれかへのポインタを戻します。
- typep (OUT)
-
hndlpp
が指し示すハンドルのタイプです。タイプには、OCI_HTYPE_BIND
(バインド・ハンドル用)またはOCI_HTYPE_DEFINE
(定義ハンドル用)があります。 - in_outp (OUT)
-
INバインド値に対してデータが必要な場合、
OCI_PARAM_IN
を戻します。データがOUTバインド変数または定義位置値として取得できる場合はOCI_PARAM_OUT
が戻ります。 - iterp (OUT)
-
複数行操作の行数を戻します。
- idxp (OUT)
-
PL/SQL配列バインド操作の配列要素の索引です。
- piecep (OUT)
-
OCI_ONE_PIECE
、OCI_FIRST_PIECE
、OCI_NEXT_PIECE
またはOCI_LAST_PIECE
のいずれかの事前定義値を戻します。
コメント
実行コールまたはフェッチ・コールからOCI_NEED_DATA
が戻され、動的なバインド、定義の値またはピースが取得または戻されると、OCIStmtGetPieceInfo()
から、バインド・ハンドルまたは定義ハンドル、反復、索引番号、ピース情報などの関連情報が戻されます。
関連トピック
OCIStmtPrepare2()
実行する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 );
パラメータ
- svchp (IN)
-
文に関連付けるサービス・コンテキストです。
- stmthp (OUT)
-
戻される文ハンドルへのポインタです。
- errhp (IN)
-
診断のためのエラー・ハンドルへのポインタです。
- stmttext (IN)
-
文のテキストです。
stmttext
のセマンティックは、OCIStmtPrepare()
のセマンティックと同じです(つまり、文字列はNULL
で終了)。 - stmt_len (IN)
-
文のテキストの長さです。
- key (IN)
-
文キャッシュの場合のみ指定します。文キャッシュ内の文を検索するために使用されるキーです。このキーが指定されると、文のテキストおよび他のパラメータは無視され、このキーのみに基づいて検索が行われます。
- keylen (IN)
-
文キャッシュの場合のみ指定します。キーの長さです。
- language (IN)
-
V7構文またはネイティブ構文を指定します。有効な値は次のとおりです。
-
OCI_V7_SYNTAX
- V7 Oracle解析構文。 -
OCI_NTV_SYNTAX
- サーバーのバージョンに依存する構文。OCI_FOREIGN_SYNTAX
- セッションのSQL翻訳プロファイルに従って翻訳される文を指定します。
-
- mode (IN)
-
この関数では、文キャッシュを使用することも使用しないことも可能です。使用するかどうかは、接続またはセッション・プールの作成時に決まります。セッションに対してキャッシュが使用可能な場合はセッション内のすべての文がキャッシュ可能で、キャッシュが使用可能でない場合はすべての文がキャッシュされません。
有効なモードは次のとおりです。-
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サポート」を参照してください。
-
OCIStmtRelease()
OCIStmtPrepare2()
のコールで取得した文ハンドルを解放します。
用途
OCIStmtPrepare2()
のコールで取得した文ハンドルを解放します。
構文
sword OCIStmtRelease ( OCIStmt *stmthp, OCIError *errhp, const OraText *key, ub4 keylen, ub4 mode );
パラメータ
- stmthp (IN/OUT)
-
OCIStmtPrepare2()
によって戻される文ハンドルです。 - errhp (IN)
-
診断に使用するエラー・ハンドルです。
- key (IN)
-
文キャッシュの場合のみ有効です。キャッシュ内の文に関連付けられているキーです。これは、コール元によって渡されるSQL文字列です。
NULL
のキーが渡された場合、文はタグ付けされません。 - keylen (IN)
-
文キャッシュの場合のみ有効です。キーの長さです。
- mode (IN)
-
次のモードが有効です。
-
OCI_DEFAULT
-
OCI_STRLS_CACHE_DELETE
- 文キャッシュの場合のみ有効です。文は、それ以上キャッシュに保持されません。
関連トピック
OCIStmtSetPieceInfo()
ピース単位操作用のピース情報を設定します。
用途
ピース単位操作用のピース情報を設定します。
構文
sword OCIStmtSetPieceInfo ( void *hndlp, ub4 type, OCIError *errhp, const void *bufp, ub4 *alenp, ub1 piece, const void *indp, ub2 *rcodep );
パラメータ
- hndlp (IN/OUT)
-
バインド・ハンドルまたは定義ハンドルです。
- type (IN)
-
ハンドルのタイプです。
- errhp (OUT)
-
エラー発生時の診断情報のために
OCIErrorGet()
に渡すエラー・ハンドルです。 - bufp (IN/OUT)
-
データ値またはデータ・ピースがINバインド変数である場合、それを含む格納場所へのポインタです。そうでない場合、
bufp
が格納場所へのポインタになり、OUTバインド変数および定義変数のピースまたは値を取得します。名前付きデータ型またはREF
の場合、オブジェクトまたはREF
へのポインタが戻されます。 - alenp (IN/OUT)
-
ピースまたは値の長さです。同じSQL文を実行する間にこのパラメータを変更しないでください。
- piece (IN)
-
ピース・パラメータです。次の値が有効です。
-
OCI_ONE_PIECE
-
OCI_FIRST_PIECE
-
OCI_NEXT_PIECE
-
OCI_LAST_PIECE
このパラメータは、INバインド変数でのみ使用されます。
コメント
実行コールにより、動的IN/OUTバインド値またはピースを取得するOCI_NEED_DATA
が戻されると、OCIStmtSetPieceInfo()
により、バッファ、長さ、現在処理中のピース、インジケータおよびこの列のリターン・コードなどのピース情報が設定されます。
関連トピック