仕様: | DB2 CLI 2.1 | ODBC 1.0 | ISO CLI |
SQLPutData() を呼び出した後、SQLParamData() が呼び出され、 SQL_NEED_DATA を戻してパラメーター・データ値を渡します。この関数を使用して、大きなパラメーター値を分割して送ることができます。
情報は SQL 結果セット内に戻されますが、照会により作成された結果セットを処理するのに使用される関数と同じ関数を使用して情報を取り出すことができます。
構文
SQLRETURN SQLPutData ( SQLHSTMT StatementHandle, /* hstmt */ SQLPOINTER DataPtr, /* rgbValue */ SQLINTEGER StrLen_or_Ind); /* cbValue */
関数引き数
データ・タイプ | 引き数 | 使用法 | 説明 |
---|---|---|---|
SQLHSTMT | StatementHandle | 入力 | ステートメント・ハンドル。 |
SQLPOINTER | DataPtr | 入力 | パラメーターに関する実際のデータまたはデータの一部を指すポインター。データは、パラメーターを指定するときにアプリケーションが使用した、 SQLBindParameter() 呼び出しで指定されている書式でなければなりません。 |
SQLINTEGER | StrLen_or_Ind | 入力 | DataPtr の長さ。呼び出しで送られるデータの量を SQLPutData() に指定します。
データ量は、指定パラメーターでの呼び出しごとに違う場合があります。アプリケーションは、 StrLen_or_Ind に SQL_NTS または SQL_NULL_DATA を指定することもできます。
StrLen_or_Ind は、データ、時間、タイム・スタンプのようなすべての固定長 C バッファー・タイプ、およびすべての数値 C バッファー・タイプに対して無視されます。
C バッファー・タイプが SQL_C_CHAR または SQL_C_BINARY である場合、または SQL_C_DEFAULT を C バッファー・タイプとして指定し、 C バッファー・タイプの省略時値が SQL_C_CHAR または SQL_C_BINARY である場合、これは DataPtr バッファー内のデータのバイト数です。 |
使用法
SQLParamData() と SQLPutData() の順序については、 長形式データの分割送信 / 取り出しを参照してください。
アプリケーションは、SQL_NEED_DATA 状態のステートメントについて SQLParamData() を呼び出した後に SQLPutData() を呼び出して、 SQL_DATA_AT_EXEC パラメーターのデータ値を渡します。 SQLPutData() 呼び出しを繰り返して、長いデータを分割して送ることができます。パラメーター・データのすべての部分を送った後、アプリケーションは SQLParamData() を再度呼び出して SQL_DATA_AT_EXEC に進むか、または、すべてのパラメーターにデータ値がある場合はステートメントを実行します。
SQLPutData() を SQL_C_LONG のような固定長 C バッファー・タイプに対して 2 回以上呼び出すことはできません。
入力データが文字データまたは 2 進データの場合、 SQLPutData() 呼び出しの後で有効な関数呼び出しは SQLParamData()、 SQLCancel()、または別の SQLPutData() だけです。 SQLParamData() の場合と同様に、このステートメント・ハンドルを使用して他の関数呼び出しを行うと、すべて失敗します。 StatementHandle の親 hdbc を参照するすべての関数呼び出しに、属性や接続状況を変更する処理が関係している場合、これらの呼び出しは失敗します。つまり、親 hdbc に対する以下の関数も許可されません。
以下の関数が SQL_NEED_DATA シーケンス時に呼び出されると、 SQLSTATE HY010 の SQL_ERROR が戻され、 SQL_DATA_AT_EXEC パラメーターの処理は影響を受けません。
シングル・パラメーターについて 1 回以上 SQLPutData() 呼び出しを行って SQL_SUCCESS になった場合、同じパラメーターについて StrLen_or_Ind を SQL_NULL_DATA に設定して SQLPutData() を呼び出そうとすると、 SQLSTATE 22005 のエラーが発生します。このエラーでは、状態は変化しません。つまり、ステートメント・ハンドルはまだ Need Data 状態で、アプリケーションはパラメーター・データの送信を続けます。
戻りコード
診断
次の診断条件の中には、SQLPutData() を呼び出す時点でなく最後の SQLParamData() 呼び出しの時点で報告されるものがあります。
SQLSTATE | 説明 | 解説 |
---|---|---|
01004 | データが切り捨てられました。 | 数値パラメーターに送られるデータは、有効数字が失われないようにして切り捨てられます。
送信された日付と時刻の列に関するタイム・スタンプ・データが切り捨てられました。
関数は、 SQL_SUCCESS_WITH_INFO で戻ります。 |
22001 | ストリング・データの右側が切り捨てられました。 | 2 進データまたは文字データに、その列でデータ・ソースがサポートできるサイズより大きなデータが送られました。 |
22003 | 数値が範囲外です。 | 数値パラメーターに送られたデータが原因で、関連する列への割り当て時に数値の整数部分が切り捨てられました。
固定長パラメーターについて SQLPutData() を複数回呼び出しました。 |
22005 | 割り当てにエラーがありました。 | パラメーターに送られたデータには、関連した表の列のデータ・タイプとの互換がありませんでした。 |
22007 | 日時形式が無効です。 | 日付、時刻、またはタイム・スタンプのパラメーターに送られたデータ値は、無効でした。 |
40003 08S01 | 通信リンクに障害が起きました。 | アプリケーションとデータ・ソースとの間の通信リンクが、関数の完了する前に失敗しました。 |
HY001 | メモリーの割り振り失敗です。 | DB2 CLI は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。 |
HY008 | 操作が取り消しになりました。 |
非同期処理が StatementHandle に対して使用可能になりました。関数が呼び出され、その実行が完了する前に、 SQLCancel() が StatementHandle で呼び出されました。そして、関数が再び StatementHandle で呼び出されました。 関数が呼び出され、その実行が完了する前に、
SQLCancel() が複数スレッドのアプリケーション内の別のスレッドから、
StatementHandle で呼び出されました。
|
HY009 | 引き数値が無効です。 | 引き数 DataPtr がヌル・ポインターで、引き数 StrLen_or_Ind は 0 でも SQL_NULL_DATA でもありませんでした。 |
HY010 | 関数の順序エラーです。 | ステートメント・ハンドル StatementHandle は、データを必要としている状態でなければならず、直前の SQLParamData() 呼び出しによって SQL_DATA_AT_EXEC パラメーターに入れておく必要があります。 |
HY090 | ストリングまたはバッファー長が無効です。 | 引き数 DataPtr は NULL ポインターではなく、引き数 StrLen_or_Ind は、0 未満でしたが、 SQL_NTS または SQL_NULL_DATA と等しくありませんでした。 |
HYT00 | タイムアウトになりました。 | データ・ソースが結果セットを返す前に、タイムアウト期間が満了しました。タイムアウトは、 Windows 3.1 や Macintosh System 7 のようなマルチタスクではないシステム上でのみサポートされています。タイムアウト期間は、 SQLSetConnectAttr() の SQL_ATTR_QUERY_TIMEOUT 属性を使用して設定することができます。 |
制約
StrLen_or_Ind の新しい値 SQL_DEFAULT_PARAM が ODBC 2.0 に導入され、プロシージャーで使用する値をアプリケーションから送信された値ではなく、パラメーターの省略時値にするように指定できるようになりました。 DB2 ストアード・プロシージャー引き数には省略時値の概念がないので、
StrLen_or_Ind 引き数にこの値を指定すると、 SQL_DEFAULT_PARAM 値は無効な長さとみなされ、 CALL ステートメントを実行したときにエラーになります。
ODBC 2.0 には、 StrLen_or_Ind 引き数を指定して使用する SQL_LEN_DATA_AT_EXEC(length) マクロも導入されました。このマクロは、後続の SQLPutData() 呼び出しを経由して文字または C データ用に送信されるデータ全体の長さの合計を指定するために使用されます。 DB2 ODBC ドライバーではこの情報の必要がないため、このマクロは必要ありません。 ODBC アプリケーションは、 SQLGetInfo() に SQL_NEED_LONG_DATA_LEN オプションを指定して、ドライバーがこの情報を必要とするかどうかを調べます。 DB2 ODBC ドライバーは、この情報が SQLPutData() に必要ないことを示す場合、'N' を戻します。
(ここで完全サンプル dtlob.c を使用することもできます 。)
/* From the CLI sample dtlob.c */ /* ... */ /* * This paramter will use SQLPutData */ blobInd = SQL_DATA_AT_EXEC; sqlrc = SQLBindParameter(hstmt, 3, SQL_PARAM_INPUT, SQL_C_BINARY, SQL_BLOB, BUFSIZ, 0, (SQLPOINTER)inputParam, BUFSIZ, &blobInd);
参照