SQLPutData 関数

準拠
導入されたバージョン: 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
[入力]パラメーターまたは列の実際のデータを含むバッファーへのポインター。 データは、SQLBindParameterValueType 引数 (パラメーター データの場合) または SQLBindColTargetType 引数 (列データの場合) に指定された 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 の HandleTypeStatementHandleハンドルを使用して SQLGetDiagRec を呼び出します。 次の表に、 SQLPutData によって一般的に返される SQLSTATE 値の一覧を示し、この関数のコンテキストでそれぞれについて説明します。ドライバー マネージャーによって返される SQLSTATEs の説明の前に表記 "(DM)" が付きます。 特に記載がない限り、各 SQLSTATE 値に関連付けられている戻りコードはSQL_ERRORされます。

SQLSTATE エラー 説明
01000 一般的な警告 ドライバー固有の情報メッセージ。 (関数はSQL_SUCCESS_WITH_INFOを返します。
01004 文字列データ、右切り捨て 出力パラメーターに対して返された文字列またはバイナリ データは、非空白文字または NULL 以外のバイナリ データの切り捨てになります。 文字列値の場合は、右に切り捨てられました。 (関数はSQL_SUCCESS_WITH_INFOを返します。
07006 制限付きデータ型属性違反 バインドされたパラメーターの SQLBindParameterValueType 引数によって識別されるデータ値を、SQLBindParameterParameterType 引数で識別されるデータ型に変換できませんでした。
07S01 既定のパラメーターの使用が無効です SQLBindParameter で設定されたパラメーター値がSQL_DEFAULT_PARAMされ、対応するパラメーターに既定値が設定されていませんでした。
08S01 通信リンクエラー ドライバーとドライバーが接続されているデータ ソース間の通信リンクは、関数の処理が完了する前に失敗しました。
22001 文字列データ、右切り捨て 列に文字またはバイナリ値を割り当てると、非空白文字 (文字) または null 以外 (バイナリ) 文字またはバイトが切り捨てられました。

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、または長いデータ ソース固有のデータ型) に対して送信されたデータが増えました。
22003 範囲外の数値 バインドされた数値パラメーターまたは列に対して送信されたデータにより、関連付けられているテーブル列に割り当てられると、数値の部分全体 (小数部ではなく) が切り捨てられます。

1 つ以上の入力/出力パラメーターまたは出力パラメーターに対して数値 (数値または文字列) を返すと、数値の一部全体 (小数部ではなく) が切り捨てられます。
22007 datetime 形式が無効です 日付、時刻、またはタイムスタンプの構造体にバインドされたパラメーターまたは列に対して送信されたデータは、それぞれ無効な日付、時刻、またはタイムスタンプでした。

入出力パラメーターまたは出力パラメーターが日付、時刻、またはタイムスタンプ C 構造体にバインドされ、返されたパラメーターの値はそれぞれ無効な日付、時刻、またはタイムスタンプでした。 (関数はSQL_SUCCESS_WITH_INFOを返します。
22008 Datetime フィールドオーバーフロー 入力/出力パラメーターまたは出力パラメーターに対して計算された datetime 式の結果、無効な日付、時刻、またはタイムスタンプ C 構造体が生成されました。
22012 0 で除算しました 入出力パラメーターまたは出力パラメーターに対して計算された算術式の結果、0 除算が行われます。
22015 Interval フィールドオーバーフロー 正確な数値または間隔の列またはパラメーターに対してデータが間隔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 に対して非同期処理が有効になりました。 関数が呼び出され、実行が完了する前に、 SqlCancel または SQLCancelHandleStatementHandle で呼び出されました。 その後、 StatementHandle で関数が再び呼び出されました。

関数が呼び出され、実行が完了する前に、マルチスレッド アプリケーションの別のスレッドから StatementHandleSQLCancel または SQLCancelHandle が呼び出されました。
HY009 null ポインターの使用が無効です (DM) 引数 DataPtr が null ポインターであり、 引数StrLen_or_Ind が 0、SQL_DEFAULT_PARAM、またはSQL_NULL_DATAではありません。
HY010 関数シーケンス エラー (DM) 前の関数呼び出しは 、SQLPutData または SQLParamData の呼び出しではありません。

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

(DM) SQLExecuteSQLExecDirect、または SQLMoreResultsStatementHandle に対して呼び出され、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 接続のタイムアウト データ ソースが要求に応答する前に、接続タイムアウト期間の有効期限が切れています。 接続タイムアウト期間は、 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 を返すことができます。

コメント

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

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

ドライバーが 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 の「ブックマークを使用した一括更新の実行」、 および長いデータと SQLSetPos と SQLBulkOperations の「SQLSetPos の使用」セクションを参照してください。

注意

アプリケーションでは、 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 関数

参照

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