DB2 CLI バージョン 5 以降におけるこの関数の状況
注: |
ODBC バージョン 3 では、SQLParamOptions() は使用すべきでない関数であり、 SQLSetStmtAttr() に置き換えられました。 SQLSetStmtAttr - ステートメントに関連したオプションの設定を参照してください。
このバージョンの DB2 CLI では引き続き SQLParamOptions() をサポートしていますが、 DB2 CLI プログラムでは SQLSetStmtAttr() を使い始め、最新の規格に従うようお勧めします。
上記の関数と、その他の使用すべきでない関数の詳細については、 バージョン 5 で使用すべきでない DB2 CLI 関数を参照してください。 |
目的
仕様: | DB2 CLI 2.1 | ODBC 1.0 |
SQLParamOptions() には、 SQLBindParameter() がパラメーターの集合ごとに複数値を設定できるようにする機能があります。このため、アプリケーションは準備、実行、および SQLBindParameter() 呼び出しという 1 組の操作で同一 SQL ステートメントのバッチ処理を行うことができます。
構文
SQLRETURN SQLParamOptions (SQLHSTMT StatementHandle, /* hstmt */ SQLUINTEGER Crow, /* crow */ SQLUINTEGER FAR *FetchOffsetPtr); /* pirow */
関数引き数
データ・タイプ | 引き数 | 使用法 | 説明 |
---|---|---|---|
SQLHSTMT | StatementHandle | 入力 | ステートメント・ハンドル。 |
SQLUINTEGER | Crow | 入力 | 各パラメーターの値の個数。これが 1 より大きい場合、 SQLBindParameter() の rgbValue 引き数はパラメーター値の配列を指し、 pcbValue は長さの配列を指します。 |
SQLUINTEGER * | FetchOffsetPtr | 出力 (据え置き) | 現行パラメーター配列指数の保管用のバッファーを指すポインター。パラメーター値の個々の集合を処理するたびに、 FetchOffsetPtr をその集合の配列指数に設定します。ステートメントが失敗すると、FetchOffsetPtr を使用して、正常に処理されたステートメントの個数を判別することができます。 FetchOffsetPtr ポインターが NULL の場合は、何も戻されません。 |
使用法
ステートメントを実行するときに、 FetchOffsetPtr をパラメーター値の現行配列の索引に設定します。配列内の特定の要素の実行時にエラーが発生すると、実行が停止し、 SQLExecute()、SQLExecDirect()、または SQLParamData() は SQL_ERROR を戻します。
FetchOffsetPtr の内容には、次の使用法があります。
出力引き数 FetchOffsetPtr は、正常に処理されたパラメーターの集合の個数を示します。処理されたステートメントが照会である場合、 FetchOffsetPtr は、 SQLMoreResults() が戻した現行結果セットと関連付けられた配列指数を示しており、 SQLMoreResults() が呼び出されるたびに増加します。
基礎サポートにより複合 SQL (DB2 ユニバーサル・データベース、または DB2 コネクト V2.3 での DRDA 環境) を行える環境であれば、実行要求とともに配列されているすべてのデータは、 1 つのネットワーク・フローとしてともにパッケージされます。
DB2 ユニバーサル・データベース V2.1 以降に接続した場合、アプリケーションは ATOMIC または NOT ATOMIC 複合 SQL を選択できます。 ATOMIC 複合 SQL (これは省略時値) がある場合、配列のすべての要素の処理が成功するか、すべて失敗するかのどちらかです。 NOT ATOMIC 複合 SQL があれば、中間配列要素の 1 つにエラーが検出される場合にも、実行は継続します。アプリケーションは、 SQLSetStmtAttr() 呼び出しの SQL_ATTR_PARAMOPT_ATOMIC 属性を設定して、複合 SQL のタイプを選択できます。
DRDA 環境の場合、基礎複合 SQL サポートは常に NOT ATOMIC COMPOUND SQL (ゆえに DRDA シナリオにおける省略時値) です。
アプリケーションで SQL_ATTR_PARAMOPT_ATOMIC 属性の現行値が分からない場合は、 SQLGetStmtOption() を呼び出してください。
複合 SQL をサポートしていないサーバーに接続したときには、 DB2 CLI はステートメントを準備し、パラメーター・マーカーの配列用に繰り返し実行します。
戻りコード
診断
表 135. SQLParamOptions SQLSTATE
SQLSTATE | 説明 | 解説 |
---|---|---|
40003 08S01 | 通信リンクに障害が起きました。 | アプリケーションとデータ・ソースとの間の通信リンクが、関数の完了する前に失敗しました。 |
HY001 | メモリーの割り振り失敗です。 | DB2 CLI は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。 |
HY010 | 関数の順序エラーです。 | 実行時データ (SQLParamData()、
SQLPutData()) 操作中に、関数が呼び出されました。
BEGIN COMPOUND と END COMPOUND の SQL 操作中に、関数が呼び出されました。 |
HY107 | 行の値が範囲外です。 | 引き数 Crow の値は、1 より小さい値でした。 |
制約
なし。
配列の入力例を参照してください。
参照