SQLPutData 関数
準拠
導入されたバージョン: ODBC 1.0 Standards Compliance: ISO 92
まとめ
SQLPutData を使用すると、アプリケーションはステートメントの実行時にパラメーターまたは列のデータをドライバーに送信できます。 この関数を使用すると、文字、バイナリ、またはデータ ソース固有のデータ型 (たとえば、SQL_LONGVARBINARYのパラメーターやSQL_LONGVARCHAR型) を持つ列に、パーツ内の文字またはバイナリ データ値を送信できます。 SQLPutData では、基になるドライバーが Unicode データをサポートしていない場合でも、Unicode C データ型へのバインドがサポートされます。
構文
SQLRETURN SQLPutData(
SQLHSTMT StatementHandle,
SQLPOINTER DataPtr,
SQLLEN StrLen_or_Ind);
引数
StatementHandle
[入力]ステートメント ハンドル。
DataPtr
[入力]パラメーターまたは列の実際のデータを含むバッファーへのポインター。 データは、SQLBindParameter の ValueType 引数 (パラメーター データの場合) または SQLBindCol の TargetType 引数 (列データの場合) で指定された C データ型に含まれている必要があります。
StrLen_or_Ind
[入力]*DataPtr の長さ。 SQLPutData の呼び出しで送信されるデータの量を指定します。 データの量は、特定のパラメーターまたは列の呼び出しごとに異なる場合があります。 StrLen_or_Ind は、次のいずれかの条件を満たさない限り無視されます。
StrLen_or_Ind は、SQL_NTS、SQL_NULL_DATA、またはSQL_DEFAULT_PARAMです。
SQLBindParameter または SQLBindCol で指定された C データ型がSQL_C_CHARまたはSQL_C_BINARY。
C データ型がSQL_C_DEFAULTされ、指定された SQL データ型の既定の C データ型がSQL_C_CHARまたはSQL_C_BINARY。
他のすべての種類の C データについて、StrLen_or_IndがSQL_NULL_DATAまたはSQL_DEFAULT_PARAMされていない場合、ドライバーは *DataPtr バッファーのサイズが ValueType または TargetType で指定された C データ型のサイズであると見なし、データ値全体を送信します。 詳細については、「付録 D: データ型」の「 C から SQL データ型へのデータの変換 」を参照してください。
戻り値
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR、またはSQL_INVALID_HANDLE。
診断
SQLPutData がSQL_ERRORまたはSQL_SUCCESS_WITH_INFOを返す場合、関連付けられた SQLSTATE 値を取得するには、HandleType が SQL_HANDLE_STMT で、Handle of StatementHandle を指定して SQLGetDiagRec を呼び出します。 次の表に、 SQLPutData によって一般的に返される SQLSTATE 値の一覧を示し、この関数のコンテキストでそれぞれについて説明します。"(DM)" という表記は、ドライバー マネージャーによって返される SQLSTATEs の説明の前にあります。 特に明記されていない限り、各 SQLSTATE 値に関連付けられた戻りコードはSQL_ERRORされます。
| SQLSTATE | エラー | 説明 |
|---|---|---|
| 01000 | 一般的な警告 | ドライバー固有の情報メッセージ。 (関数はSQL_SUCCESS_WITH_INFOを返します。 |
| 01004 | 文字列データ、右切り捨て | 出力パラメーターに対して返される文字列データまたはバイナリ データは、空白以外の文字または NULL 以外のバイナリ データの切り捨てが発生しました。 文字列値の場合は、右に切り捨てられました。 (関数はSQL_SUCCESS_WITH_INFOを返します。 |
| 07006 | 制限付きデータ型属性違反 | バインドされたパラメーターの SQLBindParameter の ValueType 引数で識別されるデータ値を、SQLBindParameter の ParameterType 引数で識別されるデータ型に変換できませんでした。 |
| 07S01 | 既定のパラメーターの使用が無効です | SQLBindParameter で設定されたパラメーター値がSQL_DEFAULT_PARAMされ、対応するパラメーターに既定値が設定されていませんでした。 |
| 08S01 | 通信リンクエラー | ドライバーとドライバーが接続されているデータ ソース間の通信リンクは、関数の処理が完了する前に失敗しました。 |
| 22001 | 文字列データ、右切り捨て | 列に文字またはバイナリ値を割り当てると、非空白文字 (文字) または null 以外 (バイナリ) 文字またはバイトが切り捨てられました。 SQLGetInfo のSQL_NEED_LONG_DATA_LEN情報型は "Y" で、長いパラメーター (データ型がSQL_LONGVARCHAR、SQL_LONGVARBINARY、または長いデータ ソース固有のデータ型) に対して送信されたデータが、SQLBindParameter の StrLen_or_IndPtr 引数で指定されたデータよりも多く送信されました。 SQLGetInfo のSQL_NEED_LONG_DATA_LEN情報の種類は "Y" で、SQLBulkOperations で追加または更新されたデータ行の列に対応する長さバッファーで指定されたデータよりも、長い列 (データ型がSQL_LONGVARCHAR、SQL_LONGVARBINARY、または長いデータ ソース固有のデータ型) に対して送信されたデータが増えました。 |
| 22003 | 範囲外の数値 | バインドされた数値パラメーターまたは列に対して送信されたデータにより、関連付けられたテーブル列に割り当てられると、数値の一部全体 (小数部ではなく) が切り捨てられます。 1 つ以上の入出力パラメーターまたは出力パラメーターに対して数値 (数値または文字列) を返すと、数値の一部全体 (小数部ではなく) が切り捨てられます。 |
| 22007 | datetime 形式が無効です | 日付、時刻、またはタイムスタンプ構造にバインドされたパラメーターまたは列に対して送信されたデータは、それぞれ無効な日付、時刻、またはタイムスタンプでした。 入出力パラメーターまたは出力パラメーターが日付、時刻、またはタイムスタンプ C 構造体にバインドされ、返されたパラメーターの値はそれぞれ無効な日付、時刻、またはタイムスタンプでした。 (関数はSQL_SUCCESS_WITH_INFOを返します。 |
| 22008 | Datetime フィールドオーバーフロー | 入出力パラメーターまたは出力パラメーターに対して計算された datetime 式の結果、無効な日付、時刻、またはタイムスタンプ C 構造体が生成されました。 |
| 22012 | 0 で除算しました | 入出力パラメーターまたは出力パラメーターに対して計算された算術式の結果、0 で除算されました。 |
| 22015 | 間隔フィールドのオーバーフロー | 正確な数値または間隔の列またはパラメーターに対して間隔 SQL データ型に送信されたデータにより、有効桁数が失われます。 複数のフィールドを持つ間隔列またはパラメーターに対してデータが送信され、数値データ型に変換され、数値データ型に表現がありませんでした。 列またはパラメーター データに対して送信されたデータは、間隔 SQL 型に割り当てられ、間隔 SQL 型の C 型の値の表現はありませんでした。 正確な数値または間隔 C の列またはパラメーターに対して間隔 C 型に送信されたデータによって、有効桁数が失われます。 列またはパラメーター のデータに対して送信されたデータは、間隔 C 構造体に割り当てられ、間隔データ構造内のデータの表現が存在しません。 |
| 22018 | キャスト指定の文字値が無効です | C 型は、正確または近似数値、datetime、または間隔データ型でした。列の SQL 型は文字データ型でした。列またはパラメーターの値が、バインドされた C 型の有効なリテラルではありません。 SQL 型は、正確または近似数値、datetime、または間隔データ型でした。C 型はSQL_C_CHARされました。列またはパラメーターの値が、バインドされた SQL 型の有効なリテラルではありません。 |
| HY000 | 一般的なエラー | 特定の SQLSTATE がなく、実装固有の SQLSTATE が定義されていないエラーが発生しました。 *MessageText バッファー内の SQLGetDiagRec によって返されるエラー メッセージは、エラーとその原因を説明します。 |
| HY001 | メモリ割り当てエラー | ドライバーは、関数の実行または完了をサポートするために必要なメモリを割り当てることができませんでした。 |
| HY008 | 操作が取り消されました | StatementHandle に対して非同期処理が有効になりました。 関数が呼び出され、実行が完了する前に、 StatementHandle で SQLCancel または SQLCancelHandle が呼び出されました。 その後、 StatementHandle で関数が再度呼び出されました。 関数が呼び出され、実行が完了する前に、マルチスレッド アプリケーションの別のスレッドから StatementHandle で SQLCancel または SQLCancelHandle が呼び出されました。 |
| HY009 | null ポインターの使用が無効です | (DM) 引数 DataPtr が null ポインターであり、引数 StrLen_or_Ind が 0、SQL_DEFAULT_PARAM、またはSQL_NULL_DATAではありません。 |
| HY010 | 関数シーケンス エラー | (DM) 前の関数呼び出しは、SQLPutData または SQLParamData の呼び出しではありません。 (DM) StatementHandle に関連付けられている接続ハンドルに対して非同期実行関数が呼び出されました。 この非同期関数は、SQLPutData 関数が呼び出されたときにまだ実行されていました。 (DM) StatementHandle に対して SQLExecute、SQLExecDirect、または SQLMoreResults が呼び出され、SQL_PARAM_DATA_AVAILABLE返されました。 この関数は、すべてのストリーミング パラメーターのデータが取得される前に呼び出されました。 (DM) 非同期実行関数 (この関数ではなく) が StatementHandle に対して呼び出され、この関数が呼び出されたときにまだ実行されていました。 |
| HY013 | メモリ管理エラー | メモリが不足している可能性があるため、基になるメモリ オブジェクトにアクセスできなかったため、関数呼び出しを処理できませんでした。 |
| HY019 | 文字以外のデータとバイナリ以外のデータを分割して送信する | SQLPutData は、パラメーターまたは列に対して複数回呼び出され、文字、バイナリ、またはデータ ソース固有のデータ型を持つ列に文字 C データを送信したり、文字、バイナリ、またはデータ ソース固有のデータ型を持つ列にバイナリ C データを送信したりするために使用されていませんでした。 |
| HY020 | null 値の連結を試みます | SQLPutData は、SQL_NEED_DATAを返した呼び出し以降に複数回呼び出されました。これらの呼び出しの 1 つでは、 StrLen_or_Ind 引数には SQL_NULL_DATA または SQL_DEFAULT_PARAMが含まれていました。 |
| HY090 | 文字列またはバッファーの長さが無効です | 引数 DataPtr は null ポインターではなく、 StrLen_or_Ind 引数は 0 未満ですが、SQL_NTSまたはSQL_NULL_DATAと等しくありません。 |
| HY117 | トランザクションの状態が不明なため、接続が中断されます。 切断と読み取り専用の関数のみが許可されます。 | (DM) 中断状態の詳細については、「 SQLEndTran 関数」を参照してください。 |
| HYT01 | 接続のタイムアウト | データ ソースが要求に応答する前に、接続タイムアウト期間の有効期限が切れています。 接続タイムアウト期間は、 SQLSetConnectAttr (SQL_ATTR_CONNECTION_TIMEOUT) によって設定されます。 |
| IM001 | ドライバーは、この関数をサポートしていません | (DM) StatementHandle に関連付けられているドライバーは、 関数をサポートしていません。 |
| IM017 | 非同期通知モードでポーリングが無効になっている | 通知モデルが使用されるたびに、ポーリングは無効になります。 |
| IM018 | SQLCompleteAsync は、このハンドルで前の非同期操作を完了するために呼び出されていません。 | ハンドルの前の関数呼び出しがSQL_STILL_EXECUTINGを返し、通知モードが有効になっている場合は、処理後に処理を実行して操作を完了するために、 SQLCompleteAsync をハンドルで呼び出す必要があります。 |
SQL ステートメントのパラメーターのデータの送信中に SQLPutData が呼び出された場合は、ステートメントを実行するために呼び出された関数によって返される任意の SQLSTATE (SQLExecute または SQLExecDirect) を返すことができます。 SQLBulkOperations で更新または追加される列のデータの送信中または SQLSetPos による更新中に呼び出された場合は、SQLBulkOperations または SQLSetPos によって返すことができる任意の SQLSTATE を返すことができます。
説明
SQLPutData を呼び出して、 SQLExecute または SQLExecDirect の呼び出しで使用されるパラメーター データ、または SQLBulkOperations の呼び出しによって行が更新または追加されたとき、または SQLSetPos の呼び出しによって更新されるときに使用される列データの 2 つの用途に対して、実行時データを提供できます。
アプリケーションが SQLParamData を呼び出して送信するデータを決定すると、ドライバーは、送信するパラメーター データまたは列データが見つかる場所を判断するためにアプリケーションが使用できるインジケーターを返します。 また、SQL_NEED_DATAが返されます。これは、 SQLPutData を呼び出してデータを送信する必要があることをアプリケーションに示すインジケーターです。 DataPtr 引数を SQLPutData に渡す場合、アプリケーションはパラメーターまたは列の実際のデータを含むバッファーへのポインターを渡します。
ドライバーが SQLPutData のSQL_SUCCESSを返すと、アプリケーションは SQLParamData を再度呼び出します。 SQLParamData は 、より多くのデータを送信する必要がある場合にSQL_NEED_DATAを返します。その場合、アプリケーションは SQLPutData を再度呼び出します。 実行中のすべてのデータが送信された場合は、SQL_SUCCESSが返されます。 その後、アプリケーションは SQLParamData を再度呼び出します。 ドライバーが SQL_NEED_DATA と *ValuePtrPtr 内の別のインジケーターを返す場合は、別のパラメーターまたは列のデータが必要になり、 SQLPutData が再度呼び出されます。 ドライバーがSQL_SUCCESSを返す場合は、実行中のすべてのデータが送信され、SQL ステートメントを実行するか、 SQLBulkOperations または SQLSetPos 呼び出しを処理できます。
ステートメントの実行時にデータ実行時のパラメーター データを渡す方法の詳細については、「 SQLBindParameter のパラメーター値の受け渡し」と「 長いデータの送信」を参照してください。 実行時のデータ列データの更新または追加方法の詳細については、「SQLSetPos の SQLSetPos の使用」、SQLBulkOperations の「ブックマークを使用した一括更新の実行」、および「Long Data and SQLSetPos and SQLBulkOperations」を参照してください。
Note
アプリケーションでは 、SQLPutData を使用して、文字、バイナリ、またはデータ ソース固有のデータ型を持つ列に文字 C データを送信する場合、または文字、バイナリ、またはデータ ソース固有のデータ型を持つ列にバイナリ C データを送信する場合にのみ、パーツ内のデータを送信できます。 SQLPutData が他の条件で複数回呼び出された場合は、SQL_ERRORと SQLSTATE HY019 (文字以外のデータとバイナリ以外のデータが一括で送信) を返します。
例
次の例では、Test というデータ ソース名を前提としています。 関連付けられているデータベースには、次のように作成できるテーブルが必要です。
CREATE TABLE emp4 (NAME char(30), AGE int, BIRTHDAY datetime, Memo1 text)
// SQLPutData.cpp
// compile with: odbc32.lib user32.lib
#include <stdio.h>
#include <windows.h>
#include <sqlext.h>
#include <odbcss.h>
#define TEXTSIZE 12000
#define MAXBUFLEN 256
SQLHENV henv = SQL_NULL_HENV;
SQLHDBC hdbc1 = SQL_NULL_HDBC;
SQLHSTMT hstmt1 = SQL_NULL_HSTMT;
void Cleanup() {
if (hstmt1 != SQL_NULL_HSTMT)
SQLFreeHandle(SQL_HANDLE_STMT, hstmt1);
if (hdbc1 != SQL_NULL_HDBC) {
SQLDisconnect(hdbc1);
SQLFreeHandle(SQL_HANDLE_DBC, hdbc1);
}
if (henv != SQL_NULL_HENV)
SQLFreeHandle(SQL_HANDLE_ENV, henv);
}
int main() {
RETCODE retcode;
// SQLBindParameter variables.
SQLLEN cbTextSize, lbytes;
// SQLParamData variable.
PTR pParmID;
// SQLPutData variables.
UCHAR Data[] =
"abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz"
"abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz"
"abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz"
"abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz"
"abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz"
"abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz"
"abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz"
"abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz"
"abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz"
"abcdefghijklmnopqrstuvwxyz";
SDWORD cbBatch = (SDWORD)sizeof(Data) - 1;
// Allocate the ODBC environment and save handle.
retcode = SQLAllocHandle (SQL_HANDLE_ENV, NULL, &henv);
if ( (retcode != SQL_SUCCESS_WITH_INFO) && (retcode != SQL_SUCCESS)) {
printf("SQLAllocHandle(Env) Failed\n\n");
Cleanup();
return(9);
}
// Notify ODBC that this is an ODBC 3.0 app.
retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER) SQL_OV_ODBC3, SQL_IS_INTEGER);
if ( (retcode != SQL_SUCCESS_WITH_INFO) && (retcode != SQL_SUCCESS)) {
printf("SQLSetEnvAttr(ODBC version) Failed\n\n");
Cleanup();
return(9);
}
// Allocate ODBC connection handle and connect.
retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc1);
if ( (retcode != SQL_SUCCESS_WITH_INFO) && (retcode != SQL_SUCCESS)) {
printf("SQLAllocHandle(hdbc1) Failed\n\n");
Cleanup();
return(9);
}
// Sample uses Integrated Security, create SQL Server DSN using Windows NT authentication.
retcode = SQLConnect(hdbc1, (UCHAR*)"Test", SQL_NTS, (UCHAR*)"",SQL_NTS, (UCHAR*)"", SQL_NTS);
if ( (retcode != SQL_SUCCESS) && (retcode != SQL_SUCCESS_WITH_INFO) ) {
printf("SQLConnect() Failed\n\n");
Cleanup();
return(9);
}
// Allocate statement handle.
retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc1, &hstmt1);
if ( (retcode != SQL_SUCCESS) && (retcode != SQL_SUCCESS_WITH_INFO) ) {
printf("SQLAllocHandle(hstmt1) Failed\n\n");
Cleanup();
return(9);
}
// Set parameters based on total data to send.
lbytes = (SDWORD)TEXTSIZE;
cbTextSize = SQL_LEN_DATA_AT_EXEC(lbytes);
// Bind the parameter marker.
retcode = SQLBindParameter (hstmt1, // hstmt
1, // ipar
SQL_PARAM_INPUT, // fParamType
SQL_C_CHAR, // fCType
SQL_LONGVARCHAR, // FSqlType
lbytes, // cbColDef
0, // ibScale
(VOID *)1, // rgbValue
0, // cbValueMax
&cbTextSize); // pcbValue
if ( (retcode != SQL_SUCCESS) && (retcode != SQL_SUCCESS_WITH_INFO) ) {
printf("SQLBindParameter Failed\n\n");
Cleanup();
return(9);
}
// Execute the command.
retcode =
SQLExecDirect(hstmt1, (UCHAR*)"INSERT INTO emp4 VALUES('Paul Borm', 46,'1950-11-12 00:00:00', ?)", SQL_NTS);
if ( (retcode != SQL_SUCCESS) && (retcode != SQL_NEED_DATA) && (retcode != SQL_SUCCESS_WITH_INFO) ) {
printf("SQLExecDirect Failed\n\n");
Cleanup();
return(9);
}
// Check to see if NEED_DATA; if yes, use SQLPutData.
retcode = SQLParamData(hstmt1, &pParmID);
if (retcode == SQL_NEED_DATA) {
while (lbytes > cbBatch) {
SQLPutData(hstmt1, Data, cbBatch);
lbytes -= cbBatch;
}
// Put final batch.
retcode = SQLPutData(hstmt1, Data, lbytes);
}
if ( (retcode != SQL_SUCCESS) && (retcode != SQL_SUCCESS_WITH_INFO) ) {
printf("SQLParamData Failed\n\n");
Cleanup();
return(9);
}
// Make final SQLParamData call.
retcode = SQLParamData(hstmt1, &pParmID);
if ( (retcode != SQL_SUCCESS) && (retcode != SQL_SUCCESS_WITH_INFO) ) {
printf("Final SQLParamData Failed\n\n");
Cleanup();
return(9);
}
// Clean up.
SQLFreeHandle(SQL_HANDLE_STMT, hstmt1);
SQLDisconnect(hdbc1);
SQLFreeHandle(SQL_HANDLE_DBC, hdbc1);
SQLFreeHandle(SQL_HANDLE_ENV, henv);
}
関連する関数
| 対象 | 解決方法については、 |
|---|---|
| バッファーをパラメーターにバインドする | SQLBindParameter 関数 |
| ステートメント処理の取り消し | SQLCancel 関数 |
| SQL ステートメントの実行 | SQLExecDirect 関数 |
| 準備された SQL ステートメントの実行 | SQLExecute 関数 |
| データを送信する次のパラメーターを返す | SQLParamData 関数 |
参照
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示