CLI の手引きおよび解説書

SQLParamOptions - パラメーターに入力配列を指定する

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 */

関数引き数


表 134. SQLParamOptions 引き数
データ・タイプ 引き数 使用法 説明
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 より小さい値でした。

制約

なし。

配列の入力例を参照してください。

参照


[ ページのトップ | 前ページ | 次ページ | 目次 | 索引 ]