CLI の手引きおよび解説書

SQLParamData - データ値が必要な次のパラメーターを入手する

目的


仕様: DB2 CLI 2.1 ODBC 1.0 ISO CLI

SQLParamData() は、長いデータを分割して送るために SQLPutData() と組み合わせて使用します。また、固定長データを送るときにも使用することができます。この入力方法の正確な順序に関する説明は、長形式データの分割送信 / 取り出しを参照してください。

構文

SQLRETURN   SQLParamData     (SQLHSTMT          StatementHandle,
                              SQLPOINTER   FAR  *ValuePtrPtr );

関数引き数


表 132. SQLParamData 引き数
データ・タイプ 引き数 使用法 説明
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 を戻すことができます。また、次の診断を生成することもできます。


表 133. SQLParamData 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 属性を使用して設定することができます。

制約

なし。

CLI サンプル dtlob.c

(ここで完全サンプル dtlob.c を使用することもできます 。)

/* From the CLI sample dtlob.c */
 

CLI サンプル dtlob.c を参照してください。

参照


[ ページのトップ | 前ページ | 次ページ | 目次 | 索引 ]