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時，可以藉由呼叫 SQLGetDiagRec 搭配SQL_HANDLE_STMT的 HandleType 和 StatementHandle 句柄來取得相關聯的 SQLSTATE 值。 下表列出 SQLPutData 通常傳回的 SQLSTATE 值，並說明此函式內容中的每個值;表示法 “（DM）” 在驅動程式管理員傳回的 SQLSTATE 描述之前。 除非另有說明，否則與每個 SQLSTATE 值相關聯的傳回碼會SQL_ERROR。

如果在 SQL 語句中傳送參數的數據時呼叫 SQLPutData ，它可以傳回由呼叫的函式傳回的任何 SQLSTATE 來執行語句 （SQLExecute 或 SQLExecDirect）。 如果在傳送要更新或加入 SQLBulkOperations 的數據行數據或以 SQLSetPos 進行更新時呼叫，它可以傳回 SQLBulkOperations 或 SQLSetPos 可傳回的任何 SQLSTATE。

註解

您可以呼叫 SQLPutData 來提供兩個用途的數據執行數據：呼叫 SQLExecute 或 SQLExecDirect 時要使用的參數數據，或呼叫 SQLBulkOperations 或呼叫 SQLSetPos 時所要使用的數據行數據。

當應用程式呼叫 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 和 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 標頭檔