SQLParamData 関数

準拠
導入されたバージョン: ODBC 1.0 標準準拠: ISO 92

まとめ
SQLParamDataSQLPutData と共に使用され、ステートメントの実行時にパラメーター データを提供し、 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 の HandleTypeStatementHandleハンドルを使用して SQLGetDiagRec を呼び出します。 次の表に、 SQLParamData によって通常返される SQLSTATE 値の一覧を示し、この関数のコンテキストでそれぞれについて説明します。ドライバー マネージャーによって返される SQLSTATEs の説明の前に表記 "(DM)" が付きます。 特に記載がない限り、各 SQLSTATE 値に関連付けられている戻りコードはSQL_ERRORされます。

SQLSTATE エラー 説明
01000 一般的な警告 ドライバー固有の情報メッセージ。 (関数はSQL_SUCCESS_WITH_INFOを返します。
07006 制限付きデータ型属性違反 バインドされたパラメーターの SQLBindParameterValueType 引数によって識別されるデータ値を、SQLBindParameterParameterType 引数で識別されるデータ型に変換できませんでした。

SQL_PARAM_INPUT_OUTPUTまたはSQL_PARAM_OUTPUTとしてバインドされたパラメーターに対して返されたデータ値は、SQLBindParameterValueType 引数で識別されるデータ型に変換できませんでした。

(1 つ以上の行のデータ値を変換できなかったが、1 つ以上の行が正常に返された場合、この関数はSQL_SUCCESS_WITH_INFOを返します)。
08S01 通信リンクエラー ドライバーとドライバーが接続されているデータ ソース間の通信リンクは、関数の処理が完了する前に失敗しました。
22026 文字列データの長さが合致しません SQLGetInfo のSQL_NEED_LONG_DATA_LEN情報型は "Y" で、長いパラメーター (データ型がSQL_LONGVARCHAR、SQL_LONGVARBINARY、または長いデータ ソース固有のデータ型) に対して送信されるデータが、SQLBindParameterStrLen_or_IndPtr引数で指定されたデータよりも少なくなりました。

SQLGetInfo のSQL_NEED_LONG_DATA_LEN情報型は "Y" であり、SQLBulkOperations で追加または更新または SQLSetPos で更新されたデータ行の列に対応する長さバッファーで指定された長い列 (データ型がSQL_LONGVARCHAR、SQL_LONGVARBINARY、または長いデータ ソース固有のデータ型) に対して送信されるデータが少なくなりました。
40001 シリアル化エラー リソースが別のトランザクションとデッドロックしたため、トランザクションがロールバックされました。
40003 ステートメントの入力候補が不明 この関数の実行中に関連付けられている接続が失敗し、トランザクションの状態を特定できません。
HY000 一般的なエラー 特定の SQLSTATE がなく、実装固有の SQLSTATE が定義されていないエラーが発生しました。 *MessageText バッファー内の SQLGetDiagRec によって返されるエラー メッセージは、エラーとその原因について説明します。
HY001 メモリ割り当てエラー ドライバーは、関数の実行または完了をサポートするために必要なメモリを割り当てませんでした。
HY008 操作が取り消されました StatementHandle に対して非同期処理が有効になりました。 関数が呼び出され、実行が完了する前に、 SQLCancel または SQLCancelHandleStatementHandle で呼び出されました。その後、 StatementHandle で関数が再び呼び出されました。

関数が呼び出され、実行が完了する前に、マルチスレッド アプリケーションの別のスレッドから StatementHandleSQLCancel または SQLCancelHandle が呼び出されました。
HY010 関数シーケンス エラー (DM) 前の関数呼び出しは、戻りコードがSQL_NEED_DATAされた SQLExecDirectSQLExecuteSQLBulkOperations、または SQLSetPos の呼び出しでなかったか、前の関数呼び出しが SQLPutData の呼び出しでした。

前の関数呼び出しは SQLParamData の呼び出しでした。

(DM) StatementHandle に関連付けられている接続ハンドルに対して非同期に実行される関数が呼び出されました。 この非同期関数は、 SQLParamData 関数が呼び出されたときにまだ実行されていました。

(DM) 非同期で実行される関数 (この関数ではなく) が StatementHandle に対して呼び出され、この関数が呼び出されたときにまだ実行されていました。

SQLExecuteSQLExecDirectSQLBulkOperations、または SQLSetPosStatementHandle に対して呼び出され、SQL_NEED_DATA返されました。 SQLCancel は、実行時のすべてのパラメーターまたは列に対してデータが送信される前に呼び出されました。
HY013 メモリ管理エラー 基になるメモリ オブジェクトにアクセスできなかったため、メモリの状態が低いため、関数呼び出しを処理できませんでした。
HY117 不明なトランザクション状態のため、接続が中断されます。 切断および読み取り専用の関数のみが許可されます。 (DM) 中断状態の詳細については、 SQLEndTran 関数を参照してください。
HYT01 接続のタイムアウト データ ソースが要求に応答する前に、接続タイムアウト期間の有効期限が切れています。 接続タイムアウト期間は、 SQL_ATTR_CONNECTION_TIMEOUT SQLSetConnectAttr を介して設定されます。
IM001 ドライバーは、この関数をサポートしていません (DM) StatementHandle に対応するドライバーは、関数をサポートしていません。
IM017 非同期通知モードでポーリングが無効になっている 通知モデルが使用されるたびに、ポーリングは無効になります。
IM018 SQLCompleteAsync は、このハンドルに対する前の非同期操作を完了するために呼び出されていません。 ハンドルの前の関数呼び出しがSQL_STILL_EXECUTINGを返し、通知モードが有効になっている場合は、処理後の処理を実行して操作を完了するには、そのハンドルで SQLCompleteAsync を呼び出す必要があります。

SQL ステートメント内のパラメーターのデータの送信中に SQLParamData が呼び出された場合は、ステートメント (SQLExecute または SQLExecDirect) を実行するために呼び出された関数から返すことができる任意の SQLSTATE を返すことができます。 SQLBulkOperations で更新または追加される列のデータの送信中または SQLSetPos での更新中に呼び出された場合は、SQLBulkOperations または SQLSetPos から返すことができる任意の SQLSTATE を返すことができます。

コメント

SQLParamData を呼び出して、SQLExecute または SQLExecDirect の呼び出しで使用されるパラメーター データ、または SQLBulkOperations の呼び出しまたは SQLSetPos の呼び出しによって行が更新または追加されたときに使用される列データの 2 つの用途に対して、実行時データを提供できます。 実行時に、 SQLParamData は、ドライバーが必要とするデータのインジケーターをアプリケーションに返します。

アプリケーションが SQLExecuteSQLExecDirectSQLBulkOperations、または SQLSetPos を呼び出すと、実行時データが必要な場合、ドライバーはSQL_NEED_DATAを返します。 その後、アプリケーションは SQLParamData を 呼び出して、送信するデータを決定します。 ドライバーでパラメーター データが必要な場合、ドライバーは *ValuePtrPtr 出力バッファーに、アプリケーションが行セット バッファーに格納した値を返します。 アプリケーションはこの値を使用して、ドライバーが要求しているパラメーター データを決定できます。 ドライバーで列データが必要な場合、ドライバーは 、次のように、列が最初にバインドされたアドレス を *ValuePtrPtr バッファーで返します。

バインドされたアドレス + バインディング オフセット + ((行番号 - 1) x 要素サイズ)

ここで、変数は次の表に示すように定義されます。

変数 説明
バインドされたアドレス SQLBindColTargetValuePtr 引数で指定されたアドレス。
バインディング オフセット 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 の「ブックマークを使用した一括更新の実行」、および 長いデータと SQLSetPos および SQLBulkOperations の「SQLSetPos の使用」セクションを参照してください。

SQLParamData を呼び出して、ストリーミングされた出力パラメーターを取得できます。 SQLMoreResultsSQLExecuteSQLGetData、または SQLExecDirect がSQL_PARAM_DATA_AVAILABLEを返す場合は、SQLParamData を呼び出して、使用可能な値を持つパラメーターを特定します。 SQL_PARAM_DATA_AVAILABLEおよびストリーム出力パラメーターの詳細については、「 SQLGetData を使用した出力パラメーターの取得」を参照してください。

コード例

SQLPutData を参照してください。

対象 解決方法については、
パラメーターへのバッファーのバインド SQLBindParameter 関数
ステートメント処理の取り消し SQLCancel 関数
ステートメント内のパラメーターに関する情報を返す SQLDescribeParam 関数
SQL ステートメントの実行 SQLExecDirect 関数
準備されたSQLステートメントの実行 SQLExecute 関数
実行時のパラメーター データの送信 SQLPutData 関数

参照

ODBC API リファレンス
ODBC ヘッダー ファイル
SQLGetData を使用した出力パラメーターの取得