SQLPutData-funktion

Överensstämmelse
Version introducerad: ODBC 1.0 Standardefterlevnad: ISO 92

Summary
SQLPutData gör det möjligt för en applikation att skicka data för en parameter eller kolumn till drivrutinen vid satsexekveringstidpunkten. Denna funktion kan användas för att skicka tecken- eller binära datavärden i delar till en kolumn med en tecken-, binär- eller datakällspecifik datatyp (till exempel parametrar för SQL_LONGVARBINARY- eller SQL_LONGVARCHAR-typerna). SQLPutData stödjer bindning till en Unicode C-datatyp, även om den underliggande drivrutinen inte stöder Unicode-data.

Syntax

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

Arguments

StatementHandle
[Indata] Instruktionshandtag.

DataPtr
[Input] Pekar på en buffert som innehåller den faktiska datan för parametern eller kolumnen. Datan måste finnas i C-datatypen som specificeras i ValueType-argumentet i SQLBindParameter (för parameterdata) eller TargetType-argumentet i SQLBindCol (för kolumndata).

StrLen_or_Ind
[Input] Längden på *DataPtr. Specificerar mängden data som skickas i ett anrop till SQLPutData. Mängden data kan variera vid varje anrop för en given parameter eller kolumn. StrLen_or_Ind ignoreras om den inte uppfyller något av följande villkor:

• StrLen_or_Ind är SQL_NTS, SQL_NULL_DATA eller SQL_DEFAULT_PARAM.

• C-datatypen som specificeras i SQLBindParameter eller SQLBindCol är SQL_C_CHAR eller SQL_C_BINARY.

• C-datatypen är SQL_C_DEFAULT, och standarddatatypen C för den angivna SQL-datatypen är SQL_C_CHAR eller SQL_C_BINARY.

För alla andra typer av C-data, om StrLen_or_Ind inte är SQL_NULL_DATA eller SQL_DEFAULT_PARAM, antar drivrutinen att storleken på *DataPtr-bufferten är storleken på C-datatypen som specificerats med ValueType eller TargetType och skickar hela datavärdet. För mer information, se Konvertera data från C till SQL-datatyper i bilaga D: Datatyper.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR eller SQL_INVALID_HANDLE.

Diagnostics

När SQLPutData returnerar SQL_ERROR eller SQL_SUCCESS_WITH_INFO kan ett associerat SQLSTATE-värde erhållas genom att anropa SQLGetDiagRec med en HandleType av SQL_HANDLE_STMT och ett Handle av StatementHandle. Följande tabell listar de SQLSTATE-värden som vanligtvis returneras av SQLPutData och förklarar var och en i kontexten av denna funktion; notationen "(DM)" föregår beskrivningarna av SQLSTATE som returneras av Driver Manager. Returkoden som är associerad med varje SQLSTATE-värde är SQL_ERROR, om inget annat anges.

Om SQLPutData anropas medan data för en parameter i en SQL-sats skickas kan den returnera vilken SQLSTATE som helst som kan returneras av funktionen som anropas för att köra satsen (SQLExecute eller SQLExecDirect). Om den anropas medan data skickas för en kolumn som uppdateras eller läggs till med SQLBulkOperations eller uppdateras med SQLSetPos, kan den returnera vilken SQLSTATE som helst som kan returneras av SQLBulkOperations eller SQLSetPos.

Comments

SQLPutData kan anropas för att tillhandahålla data vid exekveringsdata för två användningsområden: parameterdata som ska användas i ett anrop till SQLExecute eller SQLExecDirect, eller kolumndata som används när en rad uppdateras eller läggs till genom ett anrop till SQLBulkOperations eller uppdateras genom ett anrop till SQLSetPos.

När en applikation anropar SQLParamData för att avgöra vilken data den ska skicka, returnerar drivrutinen en indikator som applikationen kan använda för att avgöra vilka parameterdata som ska skickas eller var kolumndata kan hittas. Den returnerar också SQL_NEED_DATA, vilket är en indikator till applikationen att den ska anropa SQLPutData för att skicka data. I DataPtr-argumentet till SQLPutData skickar applikationen en pekare till bufferten som innehåller den faktiska datan för parametern eller kolumnen.

När drivrutinen returnerar SQL_SUCCESS för SQLPutData anropar applikationen SQLParamData igen. SQLParamData returnerar SQL_NEED_DATA om mer data behöver skickas, i vilket fall applikationen anropar SQLPutData igen. Den returnerar SQL_SUCCESS om all data vid exekveringen har skickats. Applikationen anropar sedan SQLParamData igen. Om drivrutinen returnerar SQL_NEED_DATA och en annan indikator i *ValuePtr, kräver den data för en annan parameter eller kolumn och SQLPutData anropas igen. Om drivrutinen returnerar SQL_SUCCESS har all data vid exekvering skickats och SQL-satsen kan exekveras eller anropet SQLBulkOperations eller SQLSetPos kan bearbetas.

För mer information om hur data-at-exekvering-parameterdata skickas vid satsexekveringstidpunkten, se "Passing Parameter Values" i SQLBindParameter och Sending Long Data. För mer information om hur data vid exekveringskolumn uppdateras eller läggs till, se avsnittet "Using SQLSetPos" i SQLSetPos, "Performing Bulk Updates Using Bookmarks" i SQLBulkOperations, samt Long Data och SQLSetPos och SQLBulkOperations.

Example

Följande exempel antar ett datakällnamn som heter Test. Den tillhörande databasen bör ha en tabell som du kan skapa, enligt följande:

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);  
}  

Relaterade funktioner

Relaterat innehåll

• ODBC API-referens
• ODBC-huvudfiler