SQLParamOptions() - パラメーターの入力配列を指定する
SQLParamOptions は使用すべきでない関数です。これは SQLSetStmtAttr() に置き換えられます。
SQLParamOptions() の ODBC 仕様
| ODBC 仕様レベル | X/Open CLI CAE 仕様 | ISO CLI 仕様 |
|---|---|---|
| 1.0 (「使用すべきでない」) | なし | なし |
構文
SQLRETURN SQLParamOptions (SQLHSTMT hstmt,
SQLUINTEGER crow,
SQLUINTEGER FAR *pirow);
関数の引数
次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。
| データ・タイプ | 引数 | 使用法 | 説明 |
|---|---|---|---|
| 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 値ごとに、 その記述と説明を一覧で記載してあります。
| 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);