SQLPutData 関数

[アーティクル]
05/23/2023

準拠
導入されたバージョン: ODBC 1.0 標準コンプライアンス: 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 値を取得するには、SQL_HANDLE_STMTの HandleType と 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" で、長い列 (データ型はSQL_LONGVARCHAR、SQL_LONGVARBINARY、または長いデータソース固有のデータ型) に対して、SQLBulkOperations で追加または更新または SQLSetPos で更新されたデータ行の列に対応する長さバッファーで指定されたデータよりも多くのデータが送信されました。
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 で関数が再度呼び出されました。関数が呼び出され、実行が完了する前に、SQLCancel または SQLCancelHandle がマルチスレッドアプリケーション内の別のスレッドから StatementHandle で呼び出されました。
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を返した呼び出し以降に複数回呼び出されました。これらの呼び出しのいずれかで、 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	接続のタイムアウト	データソースが要求に応答する前に、接続タイムアウト期間の有効期限が切れています。接続タイムアウト期間は、SQL_ATTR_CONNECTION_TIMEOUT SQLSetConnectAttr を使用して設定されます。
IM001	ドライバーは、この関数をサポートしていません	(DM) StatementHandle に関連付けられているドライバーは、関数をサポートしていません。
IM017	非同期通知モードでポーリングが無効になっている	通知モデルが使用されるたびに、ポーリングは無効になります。
IM018	SQLCompleteAsync は、このハンドルに対する前の非同期操作を完了するために呼び出されていません。	ハンドルに対する前の関数呼び出しがSQL_STILL_EXECUTINGを返し、通知モードが有効になっている場合は、後処理を実行して操作を完了するために、ハンドルで SQLCompleteAsync を呼び出す必要があります。

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

Comments

SQLPutData を呼び出して、SQLExecute または SQLExecDirect の呼び出しで使用されるパラメーターデータ、または SQLBulkOperations の呼び出しによって行が更新または追加されたとき、または SQLSetPos の呼び出しによって更新されるときに使用される列データの 2 つの用途に対して、実行時データを提供できます。

アプリケーションが SQLParamData を呼び出して送信するデータを決定すると、ドライバーは、送信するパラメーターデータまたは列データが見つかる場所を判断するためにアプリケーションが使用できるインジケーターを返します。また、データを送信するために SQLPutData を呼び出す必要があることをアプリケーションに示すSQL_NEED_DATAも返します。 SQLPutData への DataPtr 引数では、アプリケーションはパラメーターまたは列の実際のデータを含むバッファーへのポインターを渡します。

ドライバーが SQLPutData のSQL_SUCCESSを返すと、アプリケーションは SQLParamData をもう一度呼び出します。 SQLParamData は、より多くのデータを送信する必要がある場合にSQL_NEED_DATAを返します。その場合、アプリケーションは SQLPutData を再度呼び出します。実行中のすべてのデータが送信された場合は、SQL_SUCCESSが返されます。その後、アプリケーションは SQLParamData を再度呼び出します。ドライバーが *ValuePtrPtr でSQL_NEED_DATAと別のインジケーターを返す場合は、別のパラメーターまたは列のデータが必要であり、SQLPutData が再度呼び出されます。ドライバーからSQL_SUCCESSが返された場合、実行中のすべてのデータが送信され、SQL ステートメントを実行することも 、SQLBulkOperations または SQLSetPos 呼び出しを処理することもできます。

ステートメントの実行時に実行時のデータパラメーターデータを渡す方法の詳細については、「SQLBindParameter でのパラメーター値の受け渡し」と「長いデータの送信」を参照してください。実行時データ列データの更新または追加方法の詳細については、SQLSetPos の「SQLSetPos の使用」、SQLBulkOperations の「ブックマークを使用した一括更新の実行」、および長いデータと SQLSetPos および SQLBulkOperations のセクションを参照してください。

Note

アプリケーションでは、文字、バイナリ、またはデータソース固有のデータ型を持つ列に文字 C データを送信する場合、または文字、バイナリ、またはデータソース固有のデータ型を持つ列にバイナリ C データを送信する場合にのみ、SQLPutData を使用してデータをパートで送信できます。 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 関数

参照

ODBC API リファレンス
 ODBC ヘッダーファイル

次の方法で共有

SQLPutData 関数

構文

引数

返品

診断

Comments

例

参照

フィードバック

その他のリソース

次の方法で共有

SQLPutData 関数

構文

引数

返品

診断

Comments

例

関連する関数

参照

フィードバック

その他のリソース