SQLParamData() - データ値が必要な次のパラメーターを取得する

SQLParamData() は SQLPutData() と一緒に使用して、長いデータを分割して送ります。 また、この関数を使用して、固定長データを送ることもできます。

SQLParamData() の ODBC 仕様

表 1. SQLParamData() 仕様
ODBC 仕様レベル X/Open CLI CAE 仕様 ISO CLI 仕様
1.0 はい はい

構文

SQLRETURN   SQLParamData     (SQLHSTMT          hstmt,
                              SQLPOINTER  FAR   *prgbValue);

関数引数

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

表 2. SQLParamData() 引数
データ・タイプ 引数 使用 説明
SQLHSTMT hstmt input ステートメント・ハンドルを指定します。
SQLPOINTER * prgbValue 出力 rgbValue 引数が SQLBindParameter() 呼び出しを示します。

使用法

SQLParamData() は、データが割り当てられていない SQL_DATA_AT_EXEC パラメーター が少なくとも 1 つある場合、SQL_NEED_DATA を戻します。 この関数は、 SQLBindParameter() のコールで指定された prgbValueの値を返します。 長いデータを分割して送る場合は、SQLPutData() を 1 回以上呼び出します。 SQLPutData() 呼び出しの後、SQLParamData() を呼び出して、現行パラメーターのデータが すべて送られたことを知らせ、次の SQL_DATA_AT_EXEC パラメーターに進みます。

すべてのパラメーターにデータ値を割り当てられ、関連したステートメントが正常に実行 されると、SQLParamData() は SQL_SUCCESS を戻します。 実際のステートメントの実行時かその前にエラーが発生すると、SQLParamData() は SQL_ERROR を戻します。

次の SQL_DATA_AT_EXEC パラメーターに進むと、SQLParamData() は SQL_NEED_DATA を 戻します。 トランザクション内では、この時点で SQLPutData() または SQLCancel() のみしか呼び出すことはできません。 引数 hstmt が指定する同じステートメント・ハンドルを使用して、 他の関数を呼び出しても、すべて失敗します。 さらに、引数 hstmt が参照するステートメントの親接続ハンドルを参照する関数が、 属性またはその接続の状態に何らかの変更を行った場合は、すべて失敗します。 親接続ハンドルを参照する関数が失敗したため、SQL_NEED_DATA シーケンス実行時に、 以下の関数を親接続ハンドルで使用しないでください。
  • SQLAllocHandle()
  • SQLSetConnectAttr()
  • SQLNativeSql()
  • SQLEndTran()
これらの関数を SQL_NEED_DATA シーケンス実行時に呼び出した場合 は、SQLSTATE HY010 を伴う SQL_ERROR を戻して、SQL_DATA_AT_EXEC パラメーター の処理は影響を受けません。

戻りコード

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

診断

SQLParamData() は、SQLExecDirect() および SQLExecute() が生成する SQLSTATE は、 いずれも戻すことができます。 次の表には、SQLParamData() が生成可能な追加 SQLSTATE とその説明および各値の説明が一覧で記載してあります。

表 3. SQLParamData() SQLSTATE
SQLSTATE 説明 説明
08S01 通信リンク障害が発生しました。 関数が完了する前に、アプリケーションとデータ・ソース間の 通信リンクで障害が発生しました。
4000 1 トランザクション・ロールバック。 この SQL ステートメントが属しているトランザクションが、 デッドロックまたはタイムアウトのためにロールバックされました。
HY001 メモリーの割り振りが失敗しました。 DB2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。
HY010 関数のシーケンス・エラーです。 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
  • SQLParamData() の呼び出しの順序が誤っています。 この呼び出しは、 SQLExecDirect() または SQLExecute()の後、あるいは SQLPutData() 呼び出しの後にのみ有効です。
  • SQLExecDirect() または SQLExecute() 呼び出しの後に SQLParamData() が呼び出されましたが、 処理すべき SQL_DATA_AT_EXEC パラメーターがありません。

例

関連例については、関連 SQLGetData() を参照してください。