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 入力 ステートメント・ハンドルを指定します。
SQLUINTEGER crow 入力 それぞれのパラメーターごとに、値の個数を指定します。 この値が 1 より大きい場合は、SQLBindParameter() の引数 rgbValue は、 複数のパラメーター値から構成された配列を指し、引数 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);