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

SQLParamOptions は使用すべきでない関数です。これは SQLSetStmtAttr() に置き換えられます。

SQLParamOptions() の ODBC 仕様

表 1. SQLParamOptions() 仕様
ODBC 仕様レベル X/Open CLI CAE 仕様 ISO CLI 仕様
1.0 (「使用すべきでない」) いいえ いいえ

構文

SQLRETURN   SQLParamOptions  (SQLHSTMT          hstmt,
                              SQLUINTEGER       crow,
                              SQLUINTEGER  FAR  *pirow);

関数引数

次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。

表 2. SQLParamOptions() 引数
データ・タイプ 引数 使用 説明
SQLHSTMT hstmt input ステートメント・ハンドルを指定します。
SQLUINTEGER カラス input それぞれのパラメーターごとに、値の個数を指定します。 この値が1より大きい場合、 rgbValue 引数は SQLBindParameter() パラメータ値の配列を指し、 pcbValue 引数は長さの配列を指します。
SQLUINTEGER * pirow 出力(据え置き) 現行パラメーターの配列指標を入れるためのバッファーを指します。 パラメーター値の各セットが処理されると、この引数が設定されてそのセットの配列指標が入ります。 ステートメントが失敗した場合は、正常に処理されたステートメント数を、この値を使用して 判別することができます。 引数 pirow が NULL ポインターを指定している場合は、 値は戻されません。

使用法

SQLParamOptions() を使用して、あるステートメントを準備し、パラメーター・マーカーの配列に対して、 そのステートメントを繰り返し実行します。

ステートメントが実行されると、引数 pirow が指しているバッファーが設定されて、パラメーター値の 現行の配列指標が入ります。 配列の特定エレメント実行時にエラーが発生すると、実行は停止し、SQLExecute()、SQLExecDirect()、 または SQLParamData() は SQL_ERROR を戻します。

出力引数 pirow は、正常に処理されたパラメーターのセットの数を戻すバッファー を指します。 処理されたステートメントが照会の場合、pirow は、SQLMoreResults() が戻した 現行の結果セットに関連した配列指標を戻すバッファーを指します。 この値は、SQLMoreResults() が呼び出されるごとに、増分します。

以下の場合は、引数 pirow が指しているバッファーの値を使用します。
  • SQLParamData() が SQL_NEED_DATA を戻す場合は、この値を使用して、データを必要と するパラメーターを判別します。
  • SQLExecute() または SQLExecDirect() がエラーを戻す場合は、この値を使用して、 失敗したパラメーター値配列のエレメントを判別します。
  • この値は、SQLExecute()、SQLExecDirect()、SQLParamData()、または SQLPutData() が成功すると、 引数 crow が指定する値に設定され、配列のすべてのエレメントが正常に 処理されたことを示します。
SQLParamOptions() が参照するステートメントが、MERGE ステートメントの場合。
  • SQLParamOptions() を使用して、ターゲット表またはビューにマージするソース・データ内の行数を設定します。
  • MERGE ステートメントに、パラメーター・マーカーを使用する UPDATE または INSERT 文節が含まれている場合、SQLParamOptions() は、UPDATE または INSERT 文節内のパラメーター・マーカーに対して何もしません。
  • pirow が指すバッファーに MERGE によって影響がある行数が含まれます。

戻りコード

SQLParamOptions() は、呼び出された後、次のいずれかの値を戻します。
  • SQL_SUCCESS
  • SQL_SUCCESS_WITH_INFO
  • SQL_ERROR
  • SQL_INVALID_HANDLE

診断

次の表は、この関数が生成する各 SQLSTATE 値ごとに、 その記述と説明を一覧で記載してあります。

表 3. SQLParamOptions() SQLSTATE
SQLSTATE 説明 説明
08S01 通信リンク障害が発生しました。 関数が完了する前に、アプリケーションとデータ・ソース間の 通信リンクで障害が発生しました。
HY001 メモリーの割り振りが失敗しました。 DB2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。
HY010 関数のシーケンス・エラーです。 この関数は、実行時データの操作時に呼び出されました。 (すなわち、SQLParamData() または SQLPutData() 関数を使用するプロシージャー実行中に関数が呼び出されました。)
HY107 行の値が範囲外です。 引数 crow の値が 1 より小さい値です。

例

ODBC 3.0 では、 SQLParamOptions() の呼び出しは、SQLSetStmtAttr() の呼び出し 2 回に置き換えられます。

SQLSetStmtAttr(hstmt, SQL_ATTR_PARAMSET_SIZE, crow, 0);
SQLSetStmtAttr(hstmt, SQL_ATTR_PARAMS_PROCESSED_PTR, piRow, 0);