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されます。

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」を参照してください。

例

次の例では、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);  
}  

関連する関数

参照

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