SQLPutData() - パラメーターのデータ値を渡す
SQLPutData() はパラメーター・データ値を提供します。 この関数を使用して、大きなパラメーター値を分割して送ることができます。 情報は、SQL 結果セットとして戻されます。 この結果セットは、 照会で生成される結果セットを処理するのと同じ関数を使用して、取り出すことができます。
SQLPutData() の ODBC 仕様
| 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);
関数の引数
次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。
| データ・タイプ | 引数 | 使用法 | 説明 |
|---|---|---|---|
| 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 バッファー内のデータのバイト数になります。 |
注:
|
|||
使用法
アプリケーションは SQL_NEED_DATA 状態で、SQLParamData() をステートメント上で呼び出した 後、SQLPutData() を呼び出して SQL_DATA_AT_EXEC パラメーターのデータ値を渡し ます。SQLPutData() への呼び出しを繰り返して使用することにより、長いデータを分割して送ることができます。 パラメーターのデータのすべての部分が送られた後、アプリケーション は SQLParamData() を再度呼び出して次の SQL_DATA_AT_EXEC パラメーターに進むか、あるいは、すべてのパラメーターにデータ値がある場合はそのステートメントを実行します。
SQLPutData() を SQL_C_LONG のような固定長 C バッファー・タイプに対して、2 回以上呼び出すことはできません。
- SQLAllocHandle()
- SQLSetConnectAttr()
- SQLNativeSql()
- SQLEndTran()
単一のパラメーターで SQLPutData() の呼び出しを 1 回以上行って結果が SQL_SUCCESS で あった場合に、cbValue を SQL_NULL_DATA に設定して SQLPutData() を同じパラメーター で呼び出そうとすると、SQLSTATE 22005 のエラーが生じます。このエラーでは、結果として状態は変化しません。 つまり、ステートメント・ハンドルはまだ データを必要とする 状態であり、 アプリケーションはパラメーター・データの送信を続けることができます。
戻りコード
- SQL_SUCCESS
- SQL_SUCCESS_WITH_INFO
- SQL_ERROR
- SQL_INVALID_HANDLE
診断
以下の診断条件の中には、SQLPutData() が呼び出された時点でなく 最後の SQLParamData() 呼び出しの時点で報告されるものもあり ます。次の表は、各 SQLSTATE について、 それぞれの値ごとの記述と説明とともに示しています。
| SQLSTATE | 説明 | 説明 |
|---|---|---|
| 01004 | データが切り捨てられました。 | 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
|
| 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 が戻されます。
|
| 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() を参照してください。