SQLPutData() - パラメーターのデータ値を渡す

SQLPutData() はパラメーター・データ値を提供します。 この関数を使用して、大きなパラメーター値を分割して送ることができます。 情報は、SQL 結果セットとして戻されます。 この結果セットは、 照会で生成される結果セットを処理するのと同じ関数を使用して、取り出すことができます。

SQLPutData() の ODBC 仕様

表 1. SQLPutData() の仕様
ODBC 仕様レベル X/Open CLI CAE 仕様 ISO CLI 仕様
1.0 あり あり

構文

31 ビット・アプリケーションの場合、次の構文を使用します。

SQLRETURN   SQLPutData       (SQLHSTMT          hstmt,
                              SQLPOINTER        rgbValue,
                              SQLINTEGER        cbValue);

64 ビット・アプリケーションの場合、次の構文を使用します。

SQLRETURN   SQLPutData       (SQLHSTMT          hstmt,
                              SQLPOINTER        rgbValue,
                              SQLLEN            cbValue);

関数の引数

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

表 2. SQLPutData() の引数
データ・タイプ 引数 使用法 説明
SQLHSTMT hstmt 入力 ステートメント・ハンドル。
SQLPOINTER rgbValue 入力 パラメーターの実際のデータ (またはデータの一部) を指すポインター。 このデータは、パラメーター指定時にアプリケーションが使用 した、SQLBindParameter() 呼び出しの中で指定した形式である必要があります。
SQLINTEGER (31 ビット) または SQLLEN (64 ビット) 1 cbValue 入力 rgbValue の長さ (バイト)。SQLPutData() への呼び出しで送られるデータ量を指定します。

データ量は、所定のパラメーターでの呼び出しごとに変えることが できます。アプリケーションは、cbValue に SQL_NTS また は SQL_NULL_DATA を指定することもできます。

cbValue は、日付、時刻、タイム・スタンプなどのすべ ての固定長 C バッファー・タイプ、およびすべての数値 C バッファー・タイプ では無視されます。

C バッファー・タイプが SQL_C_CHAR または SQL_C_BINARY の場合、 または SQL_C_DEFAULT が C バッファー・タイプとして指定されて、かつ、C バッファー・タイプ のデフォルトが SQL_C_CHAR または SQL_C_BINARY の場合、 これは rgbValue バッファー内のデータのバイト数になります。

注:
  1. 64 ビット・アプリケーションの場合、旧バージョンの Db2® で使用されていたデータ・タイプ SQLINTEGER は、引き続き有効です。ただし、アプリケーションのポータビリティーを最大限に引き出すために、SQLLEN の使用をお勧めします。

使用法

アプリケーションは SQL_NEED_DATA 状態で、SQLParamData() をステートメント上で呼び出した 後、SQLPutData() を呼び出して SQL_DATA_AT_EXEC パラメーターのデータ値を渡し ます。SQLPutData() への呼び出しを繰り返して使用することにより、長いデータを分割して送ることができます。 パラメーターのデータのすべての部分が送られた後、アプリケーション は SQLParamData() を再度呼び出して次の SQL_DATA_AT_EXEC パラメーターに進むか、あるいは、すべてのパラメーターにデータ値がある場合はそのステートメントを実行します。

SQLPutData() を SQL_C_LONG のような固定長 C バッファー・タイプに対して、2 回以上呼び出すことはできません。

SQLPutData() 呼び出しの後に有効な関数呼び出しは、SQLParamData()、SQLCancel()、あるいは 別の SQLPutData() (入力データが文字データまたはバイナリー・データの場合) のみ です。SQLParamData() の場合と同様に、このステートメント・ハンドルを 使用して他の関数呼び出しを行うと、すべて失敗します。 さらに、hstmt の親 hdbc を参照する関数呼び出しは、 その接続の属性または状態の変更があった場合、すべて失敗します。 すなわち、親 hdbc に関する以下の関数呼び出しも許可されません。
  • SQLAllocHandle()
  • SQLSetConnectAttr()
  • SQLNativeSql()
  • SQLEndTran()
これらの関数が、SQL_NEED_DATA シーケンスの際に呼び出された場合 には、SQLSTATE HY010 を伴った SQL_ERROR を 戻し、SQL_DATA_AT_EXEC パラメーターの処理は影響を受けません。

単一のパラメーターで SQLPutData() の呼び出しを 1 回以上行って結果が SQL_SUCCESS で あった場合に、cbValue を SQL_NULL_DATA に設定して SQLPutData() を同じパラメーター で呼び出そうとすると、SQLSTATE 22005 のエラーが生じます。このエラーでは、結果として状態は変化しません。 つまり、ステートメント・ハンドルはまだ データを必要とする 状態であり、 アプリケーションはパラメーター・データの送信を続けることができます。

戻りコード

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

診断

以下の診断条件の中には、SQLPutData() が呼び出された時点でなく 最後の SQLParamData() 呼び出しの時点で報告されるものもあり ます。次の表は、各 SQLSTATE について、 それぞれの値ごとの記述と説明とともに示しています。

表 3. SQLPutData() の SQLSTATE
SQLSTATE 説明 説明
01004 データが切り捨てられました。 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
  • 送信された数値パラメーターのデータが切り捨てられましたが、 有効数字は失われていません。
  • 日付または時刻の列に関する送られたタイム・スタンプ・ データが切り捨てられます。
(SQLPutData() は、この SQLSTATE で SQL_SUCCESS_WITH_INFO を戻します。)
08S01 通信リンクに障害が起きました。 関数が完了する前に、アプリケーションとデータ・ソース間の 通信リンクで障害が発生しました。
22001 ストリング・データの右側が切り捨てられました。 データ・ソースがその列についてサポートできる量以上のバイナリー・データ または文字データが送られています。
22008 日時形式が無効または日時フィールドがオーバーフローしました。 日付、時刻、またはタイム・スタンプの パラメーターに関する、送られたデータ値が無効です。
22018 割り当てにエラーがありました。 送られたパラメーターのデータは、関連した表の 列のデータ・タイプと互換性がありません。
HY001 メモリーの割り振りに失敗しました。 Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。
HY009 NULL ポインターの使用は無効です。 引数 rgbValue は NULL ポインターであり、 引数 cbValue は、0 および SQL_NULL_DATA のいずれで もありません。
HY010 関数シーケンス・エラーが発生しました。 ステートメント・ハンドル hstmt は、データを必要とする状態 でなければなりません。さらに、直前の SQLParamData() 呼び出し を使用して SQL_DATA_AT_EXEC パラメーターに位置付けておく必要があります。
HY019 数値が範囲外です。 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
  • 数値パラメーターのデータが送られると、数値の整数部分は、関連した列に 割り当てられると、切り捨てられます。
  • SQLPutData() が、固定長パラメーターで複数回呼び出されました。
HY090 ストリングまたはバッファーの長さが無効です。 引数 rgbValue は NULL ポインターではなく、 引数 cbValue は 0 より小さい値ですが、SQL_NTS または SQL_NULL_DATA と等しくありません。

制約事項

pcbValue の新しい値 SQL_DEFAULT_PARAM が ODBC 2.0 で導入されました。これは、 プロシージャーが、アプリケーションから送られた値ではなく、 パラメーターのデフォルト値を使用することを示し ます。Db2 ストアード・プロシージャーの引数にはデフォルト値の概念が適用されないため、 この値を引数 pcbValue に指定すると、SQL_DEFAULT_PARAM 値の長さが無効と 見なされて、CALL ステートメントの実行時にエラーとなります。

ODBC 2.0 には、引数 pcbValue と一緒に 使用する SQL_LEN_DATA_AT_EXEC(length) マクロも提供されています。 このマクロは、後続の SQLPutData() 呼び出しを使用して 送られる、文字またはバイナリー C データのデータ全体の長さ (バイト) の合計を 指定するために使用されます。 Db2 ODBC ドライバーではこの情報は不要なため、このマクロは不要です。ドライバーがこの情報を必要としているかどうかをチェックするには、 引数 InfoType を SQL_NEED_LONG_DATA_LEN に設定して、SQLGetInfo() を呼び出します。 Db2 ODBC ドライバーは、SQLPutData() ではこの情報が必要ないことを示す 'N' を戻します。

例

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