仕様: | DB2 CLI 2.1 | ODBC 1.0 | ISO CLI |
SQLParamData() は、長いデータを分割して送るために SQLPutData() と組み合わせて使用します。また、固定長データを送るときにも使用することができます。この入力方法の正確な順序に関する説明は、長形式データの分割送信 / 取り出しを参照してください。
構文
SQLRETURN SQLParamData (SQLHSTMT StatementHandle, SQLPOINTER FAR *ValuePtrPtr );
関数引き数
データ・タイプ | 引き数 | 使用法 | 説明 |
---|---|---|---|
SQLHSTMT | StatementHandle | 入力 | ステートメント・ハンドル。 |
SQLPOINTER * | ValuePtrPtr | 出力 | SQLBindParameter() (パラメーター・データの場合) に指定されている ParameterValuePtr バッファーのアドレス、または SQLBindCol() (列データの場合) に指定されている TargetValuePtr バッファーのアドレスを戻すためのバッファーを指すポインター。これらのアドレスは、SQL_DESC_DATA_PTR 記述子レコード・フィールドにあります。 |
使用法
SQLParamData() は、データがまだ割り当てられていない 1 つ以上の SQL_DATA_AT_EXEC パラメーターが存在する場合に SQL_NEED_DATA を戻します。この関数は、直前の SQLBindParameter() 呼び出し時にアプリケーションが提供した ValuePtrPtr の値を戻します。 SQLPutData() は、パラメーター・データを送信するため (長いデータの場合) 1 回または複数回にわたり呼び出されます。 SQLParamData() は、現行パラメーターに関するすべてのデータが送られたことを知らせるときと、次の SQL_DATA_AT_EXEC パラメーターに進むときに呼び出します。 SQL_SUCCESS は、すべてのパラメーターにデータ値が割り当てられ、関連したステートメントが正常に実行されたときに戻されます。実際のステートメント実行時かその前にエラーが発生すると、SQL_ERROR が戻されます。
SQLParamData() が SQL_NEED_DATA を戻すと、 SQLPutData() または SQLCancel() の呼び出しだけを行うことができます。このステートメントを使用する他の関数呼び出しはすべて失敗します。さらに、StatementHandle の親 hdbc を参照するすべての関数呼び出しに、属性や接続状況を変更する処理が関係している場合、これらの呼び出しは失敗します。つまり、親 hdbc に対する以下の関数も許可されません。
以下の関数が SQL_NEED_DATA シーケンス時に呼び出されると、 SQLSTATE HY010 の SQL_ERROR が戻され、 SQL_DATA_AT_EXEC パラメーターの処理は影響を受けません。
戻りコード
診断
SQLParamData() は、SQLExecDirect() 関数と SQLExecute() 関数から戻された SQLSTATE を戻すことができます。また、次の診断を生成することもできます。
SQLSTATE | 説明 | 解説 |
---|---|---|
07006 | 変換が無効です。 | DB2 CLI とアプリケーション変数の間でデータを転送すると、非互換のデータ変換が行われます。 |
22026 | ストリング・データ、長さの不一致 | SQLGetInfo() の SQL_NEED_LONG_DATA_LEN 情報タイプが 'Y' で、長いパラメーター (データ・タイプが SQL_LONGVARCHAR、SQL_LONGVARBINARY、その他の長いデータ・タイプ) に送られたデータが、
SQLBindParameter() で StrLen_or_IndPtr を使用して指定された値よりも短いデータでした。
SQLGetInfo() の SQL_NEED_LONG_DATA_LEN 情報タイプが 'Y' で、長い列 (データ・タイプが SQL_LONGVARCHAR、 SQL_LONGVARBINARY、その他の長いデータ・タイプ) に送られたデータが、 SQLSetPos() を使用して更新されたデータの行の列に対応する長さバッファーに指定された値よりも短いデータでした。 |
40001 | トランザクション・ロールバック。 | この SQL ステートメントが属するトランザクションは、デッドロックまたはタイムアウトが原因でロールバックされました。 |
40003 08S01 | 通信リンクに障害が起きました。 | アプリケーションとデータ・ソースとの間の通信リンクが、関数の完了する前に失敗しました。 |
HY000 | 一般的なエラーです。 | 特定の SQLSTATE が存在しなかったり、定義されなかった場合のエラーが発生しました。引き数 szErrorMsg 内の SQLError() から戻されたエラー・メッセージに、そのエラーと原因が記述されています。 |
HY001 | メモリーの割り振り失敗です。 | DB2 CLI は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。 |
HY008 | 操作が取り消しになりました。 |
非同期処理が StatementHandle に対して使用可能になりました。関数が呼び出され、その実行が完了する前に、 SQLCancel() が StatementHandle で呼び出されました。そして、関数が再び StatementHandle で呼び出されました。 関数が呼び出され、その実行が完了する前に、
SQLCancel() が複数スレッドのアプリケーション内の別のスレッドから、
StatementHandle で呼び出されました。
|
HY010 | 関数の順序エラーです。 | SQLParamData() を順不同で呼び出しました。この呼び出しは、SQLExecDirect() または SQLExecute() の後か、
SQLPutData() 呼び出しの後だけ有効です。
SQLExecDirect() または SQLExecute() 呼び出しの後にこの関数を呼び出しましたが、処理する SQL_DATA_AT_EXEC パラメーターがありません (残っていません) でした。 |
HY013 | 予期しないメモリーのハンドル・エラーが起きました。 | DB2 CLI は、関数の実行または完了をサポートするのに必要なメモリーを使用することができませんでした。 |
HY092 | オプション・タイプが範囲外です。 | 直前の SQLBindFileToParam() 操作の FileOptions 引き数が無効でした。 |
HY506 | ファイルのクローズ・エラーが起きました。 | 一時ファイルをクローズしようとしているときにエラーが発生しました。 |
HY509 | ファイルの削除エラーが起きました。 | 一時ファイルを削除しようとしているときにエラーが発生しました。 |
HYT00 | タイムアウトになりました。 | データ・ソースが結果セットを返す前に、タイムアウト期間が満了しました。タイムアウトは、 Windows 3.1 や Macintosh System 7 のようなマルチタスクではないシステム上でのみサポートされています。タイムアウト期間は、 SQLSetConnectAttr() の SQL_ATTR_QUERY_TIMEOUT 属性を使用して設定することができます。 |
制約
なし。
(ここで完全サンプル dtlob.c を使用することもできます 。)
/* From the CLI sample dtlob.c */
CLI サンプル dtlob.c を参照してください。
参照