SQLParamData 関数
準拠
導入されたバージョン: ODBC 1.0 Standards Compliance: ISO 92
まとめ
SQLParamData は SQLPutData と共に使用され、ステートメントの実行時にパラメーター データを提供し、 SQLGetData を使用してストリーム出力パラメーター データを取得します。
構文
SQLRETURN SQLParamData(
SQLHSTMT StatementHandle,
SQLPOINTER * ValuePtrPtr);
引数
StatementHandle
[入力]ステートメント ハンドル。
ValuePtrPtr
[出力]SQLBindParameter で指定された ParameterValuePtr バッファーのアドレス (パラメーター データの場合) または SQLBindCol で指定された TargetValuePtr バッファーのアドレス (列データの場合) を返すバッファーへのポインター。これは、SQL_DESC_DATA_PTR記述子レコード フィールドに含まれています。
戻り値
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NEED_DATA、SQL_NO_DATA、SQL_STILL_EXECUTING、SQL_ERROR、SQL_INVALID_HANDLE、またはSQL_PARAM_DATA_AVAILABLE。
診断
SQLParamData がSQL_ERRORまたはSQL_SUCCESS_WITH_INFOを返す場合、関連付けられた SQLSTATE 値を取得するには、SQL_HANDLE_STMTの HandleType と StatementHandle の Handle を指定して SQLGetDiagRec を呼び出します。 次の表に、 SQLParamData によって通常返される SQLSTATE 値の一覧を示し、この関数のコンテキストでそれぞれについて説明します。表記 "(DM)" は、ドライバー マネージャーによって返される SQLSTATEs の説明の前にあります。 特に明記されていない限り、各 SQLSTATE 値に関連付けられている戻りコードはSQL_ERRORされます。
| SQLSTATE | エラー | 説明 |
|---|---|---|
| 01000 | 一般的な警告 | ドライバー固有の情報メッセージ。 (関数はSQL_SUCCESS_WITH_INFOを返します。 |
| 07006 | 制限付きデータ型の属性違反 | バインドされたパラメーターの SQLBindParameter の ValueType 引数によって識別されるデータ値を、SQLBindParameter の ParameterType 引数で識別されるデータ型に変換できませんでした。 SQL_PARAM_INPUT_OUTPUTまたはSQL_PARAM_OUTPUTとしてバインドされたパラメーターに対して返されたデータ値を、SQLBindParameter の ValueType 引数で識別されるデータ型に変換できませんでした。 (1 つ以上の行のデータ値を変換できなかったが、1 つ以上の行が正常に返された場合、この関数はSQL_SUCCESS_WITH_INFOを返します)。 |
| 08S01 | 通信リンクエラー | ドライバーとドライバーが接続されたデータ ソース間の通信リンクは、関数の処理が完了する前に失敗しました。 |
| 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、または長いデータ ソース固有のデータ型) に対して送信されたデータが、SQLBulkOperations で追加または更新または SQLSetPos で更新されたデータ行の列に対応する長さバッファーで指定されたデータよりも少なくなりました。 |
| 40001 | シリアル化エラー | 別のトランザクションでリソースのデッドロックが発生したため、トランザクションがロールバックされました。 |
| 40003 | ステートメントの完了が不明です | この関数の実行中に関連付けられた接続が失敗し、トランザクションの状態を特定できません。 |
| HY000 | 一般的なエラー | 特定の SQLSTATE がなく、実装固有の SQLSTATE が定義されていないエラーが発生しました。 *MessageText バッファー内の SQLGetDiagRec によって返されるエラー メッセージは、エラーとその原因を説明します。 |
| HY001 | メモリ割り当てエラー | ドライバーは、関数の実行または完了をサポートするために必要なメモリを割り当てることができませんでした。 |
| HY008 | 操作が取り消されました | StatementHandle に対して非同期処理が有効になりました。 関数が呼び出され、実行が完了する前に、 SQLCancel または SQLCancelHandle が StatementHandle で呼び出されました。その後、関数は StatementHandle で再度呼び出されました。 関数が呼び出され、実行が完了する前に、マルチスレッド アプリケーション内の別のスレッドから StatementHandle で SQLCancel または SQLCancelHandle が呼び出されました。 |
| HY010 | 関数シーケンス エラー | (DM) 前の関数呼び出しは、戻りコードがSQL_NEED_DATAされた SQLExecDirect、 SQLExecute、 SQLBulkOperations、または SQLSetPos の呼び出しではなかったか、以前の関数呼び出しが SQLPutData の呼び出しでした。 前の関数呼び出しは 、SQLParamData の呼び出しでした。 (DM) StatementHandle に関連付けられている接続ハンドルに対して非同期実行関数が呼び出されました。 この非同期関数は、 SQLParamData 関数が呼び出されたときにまだ実行されていました。 (DM) 非同期実行関数 (この関数ではなく) が StatementHandle に対して呼び出され、この関数が呼び出されたときにはまだ実行されていました。 StatementHandle に対して SQLExecute、SQLExecDirect、SQLBulkOperations、または SQLSetPos が呼び出され、SQL_NEED_DATA返されました。 SQLCancel は、すべての実行時データ パラメーターまたは列に対してデータが送信される前に呼び出されました。 |
| HY013 | メモリ管理エラー | メモリ不足の可能性があるため、基になるメモリ オブジェクトにアクセスできなかったため、関数呼び出しを処理できませんでした。 |
| HY117 | 不明なトランザクション状態が原因で接続が中断されます。 切断関数と読み取り専用関数のみが許可されます。 | (DM) 中断状態の詳細については、「 SQLEndTran 関数」を参照してください。 |
| HYT01 | 接続のタイムアウト | データ ソースが要求に応答する前に、接続タイムアウト期間の有効期限が切れています。 接続タイムアウト期間は、 SQLSetConnectAttr (SQL_ATTR_CONNECTION_TIMEOUT) によって設定されます。 |
| IM001 | ドライバーは、この関数をサポートしていません | (DM) StatementHandle に対応するドライバーは、 関数をサポートしていません。 |
| IM017 | 非同期通知モードでポーリングが無効になっている | 通知モデルを使用するたびに、ポーリングは無効になります。 |
| IM018 | SQLCompleteAsync は、このハンドルに対する以前の非同期操作を完了するために呼び出されていません。 | ハンドルの前の関数呼び出しがSQL_STILL_EXECUTINGを返し、通知モードが有効になっている場合は、後処理を実行して操作を完了するために、ハンドルで SQLCompleteAsync を呼び出す必要があります。 |
SQL ステートメントのパラメーターのデータの送信中に SQLParamData が呼び出された場合、ステートメントを実行するために呼び出された関数によって返される任意の SQLSTATE (SQLExecute または SQLExecDirect) を返すことができます。 SQLBulkOperations で更新または追加される列のデータの送信中または SQLSetPos による更新中に呼び出された場合は、SQLBulkOperations または SQLSetPos によって返される任意の SQLSTATE を返すことができます。
説明
SQLParamData を呼び出して、 SQLExecute または SQLExecDirect の呼び出しで使用されるパラメーター データ、または SQLBulkOperations の呼び出しまたは SQLSetPos の呼び出しによって行が更新または追加されたときに使用される列データの 2 つの用途で、実行時データを提供できます。 実行時に、 SQLParamData は、ドライバーが必要とするデータを示すインジケーターをアプリケーションに返します。
アプリケーションが SQLExecute、SQLExecDirect、SQLBulkOperations、または SQLSetPos を呼び出すと、実行時データが必要な場合、ドライバーはSQL_NEED_DATAを返します。 その後、アプリケーションは SQLParamData を呼び出して、送信するデータを決定します。 ドライバーでパラメーター データが必要な場合、ドライバーは、アプリケーションが行セット バッファーに格納した値を *ValuePtrPtr 出力バッファーで返します。 アプリケーションでは、この値を使用して、ドライバーが要求しているパラメーター データを決定できます。 ドライバーで列データが必要な場合、ドライバーは *ValuePtrPtr バッファーで、列が最初にバインドされたアドレスを次のように返します。
バインドされたアドレス + バインディング オフセット + ((行番号 - 1) x 要素サイズ)
ここで、変数は次の表に示すように定義されています。
| 変数 | 説明 |
|---|---|
| バインドされたアドレス | SQLBindCol の TargetValuePtr 引数で指定されたアドレス。 |
| バインディング オフセット | SQL_ATTR_ROW_BIND_OFFSET_PTR ステートメント属性で指定されたアドレスに格納される値。 |
| Row Number | 行セット内の行の 1 から始まる番号。 単一行フェッチの場合(既定値)、これは 1 です。 |
| 要素のサイズ | データ バッファーと長さ/インジケーター バッファーの両方のSQL_ATTR_ROW_BIND_TYPE ステートメント属性の値。 |
また、データを送信するために SQLPutData を呼び出す必要があることをアプリケーションに示すSQL_NEED_DATAも返します。
アプリケーションは、 SQLPutData を必要な回数だけ呼び出して、列またはパラメーターの実行時データを送信します。 列またはパラメーターのすべてのデータが送信されると、アプリケーションは SQLParamData を再度呼び出します。 SQLParamData が再びSQL_NEED_DATAを返す場合は、別のパラメーターまたは列に対してデータを送信する必要があります。 したがって、アプリケーションは再び SQLPutData を呼び出します。 すべてのパラメーターまたは列に対してすべての実行時データが送信された場合、 SQLParamData はSQL_SUCCESSまたはSQL_SUCCESS_WITH_INFOを返します。 *ValuePtrPtr の値は未定義であり、SQL ステートメントを実行することも、 SQLBulkOperations または SQLSetPos 呼び出しを処理することもできます。
SQLParamData が、データ ソースの行に影響を与えない検索された更新または削除ステートメントのパラメーター データを提供する場合、SQLParamData の呼び出しはSQL_NO_DATAを返します。
ステートメントの実行時に実行データのパラメーター データを渡す方法の詳細については、「 SQLBindParameter のパラメーター値の受け渡し」と「 長いデータの送信」を参照してください。 実行時のデータ列データの更新または追加方法の詳細については、SQLSetPos の「SQLSetPos の使用」、SQLBulkOperations の「ブックマークを使用した一括更新の実行」、および「Long Data and SQLSetPos and SQLBulkOperations」のセクションを参照してください。
SQLParamData を呼び出して、ストリーム出力パラメーターを取得できます。 SQLMoreResults、SQLExecute、SQLGetData、または SQLExecDirect がSQL_PARAM_DATA_AVAILABLEを返す場合は、SQLParamData を呼び出して、使用可能な値を持つパラメーターを確認します。 SQL_PARAM_DATA_AVAILABLEおよびストリーム出力パラメーターの詳細については、「 SQLGetData を使用した出力パラメーターの取得」を参照してください。
コード例
「SQLPutData」を参照してください。
関連する関数
| 対象 | 解決方法については、 |
|---|---|
| バッファーをパラメーターにバインドする | SQLBindParameter 関数 |
| ステートメント処理の取り消し | SQLCancel 関数 |
| ステートメント内のパラメーターに関する情報を返す | SQLDescribeParam 関数 |
| SQL ステートメントの実行 | SQLExecDirect 関数 |
| 準備された SQL ステートメントの実行 | SQLExecute 関数 |
| 実行時にパラメーター データを送信する | SQLPutData 関数 |
参照
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示