SQLPutData 函数

一致性
引入的版本：ODBC 1.0 标准符合性：ISO 92

总结
SQLPutData 允许应用程序在语句执行时向驱动程序发送参数或列的数据。 此函数可用于将部分中的字符或二进制数据值发送到具有字符、二进制或数据源特定数据类型的列（例如，SQL_LONGVARBINARY或SQL_LONGVARCHAR类型的参数）。 SQLPutData 支持绑定到 Unicode C 数据类型，即使基础驱动程序不支持 Unicode 数据。

语法

  
SQLRETURN SQLPutData(  
      SQLHSTMT     StatementHandle,  
      SQLPOINTER   DataPtr,  
      SQLLEN       StrLen_or_Ind);  

参数

StatementHandle
[输入]语句句柄。

DataPtr
[输入]指向包含参数或列的实际数据的缓冲区的指针。 数据必须位于 SQLBindParameter 的 ValueType 参数中指定的 C 数据类型（对于参数数据）或 SQLBindCol 的 TargetType 参数（对于列数据）。

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时，可以通过使用 handleType of SQL_HANDLE_STMT 和 StatementHandle 句柄调用 SQLGetDiagRec 来获取关联的 SQLSTATE 值。 下表列出了 SQLPutData 通常返回的 SQLSTATE 值，并解释此函数上下文中的每个值;表示法“（DM）”位于驱动程序管理器返回的 SQLSTATE 的说明之前。 除非另有说明，否则与每个 SQLSTATE 值关联的返回代码SQL_ERROR。

如果在 为 SQL 语句中的参数发送数据时调用 SQLPutData ，则它可以返回任何 SQLSTATE，该 SQLSTATE 可由调用的函数返回以执行语句（SQLExecute 或 SQLExecDirect）。 如果在发送更新或添加 SQLBulkOperations 或 SQLSetPos 更新列的数据时调用它，则它可以返回 SQLBulkOperations 或 SQLSetPos 可以返回的任何 SQLSTATE。

注释

可以调用 SQLPutData 来提供两个用途的数据执行数据：调用 SQLExecute 或 SQLExecDirect 时要使用的参数数据，或调用 SQLBulkOperations 或由对 SQLSetPos 的调用更新或添加行时使用的列数据。

当应用程序调用 SQLParamData 来确定它应发送的数据时，驱动程序将返回一个指示器，指示应用程序可用于确定要发送的参数数据或找到列数据的位置。 它还返回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 中的“使用书签执行批量更新”以及 Long Data 和 SQLSetPos 和 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 头文件