SQLPutData-Funktion

Konformität
Version eingeführt: ODBC 1.0 Standards Compliance: ISO 92

Zusammenfassung
SQLPutData ermöglicht einer Anwendung das Senden von Daten für einen Parameter oder eine Spalte an den Treiber zur Ausführungszeit der Anweisung. Diese Funktion kann verwendet werden, um Zeichen- oder Binärdatenwerte in Teilen an eine Spalte mit einem zeichen-, binären oder datenquellenspezifischen Datentyp zu senden (z. B. Parameter der SQL_LONGVARBINARY- oder SQL_LONGVARCHAR-Typen). SQLPutData unterstützt die Bindung an einen Unicode C-Datentyp, auch wenn der zugrunde liegende Treiber Unicode-Daten nicht unterstützt.

Syntax

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

Argumente

StatementHandle
[Eingabe] Anweisungshandle.

DataPtr
[Eingabe] Zeigen Sie auf einen Puffer, der die tatsächlichen Daten für den Parameter oder die Spalte enthält. Die Daten müssen sich im C-Datentyp befinden, der im ValueType-Argument von SQLBindParameter (für Parameterdaten) oder das TargetType-Argument von SQLBindCol (für Spaltendaten) angegeben ist.

StrLen_or_Ind
[Eingabe] Länge von *DataPtr. Gibt die Datenmenge an, die in einem Aufruf von SQLPutData gesendet wird. Die Datenmenge kann je nach Aufruf für einen bestimmten Parameter oder eine bestimmte Spalte variieren. StrLen_or_Ind wird ignoriert, es sei denn, sie erfüllt eine der folgenden Bedingungen:

• StrLen_or_Ind ist SQL_NTS, SQL_NULL_DATA oder SQL_DEFAULT_PARAM.

• Der in SQLBindParameter oder SQLBindCol angegebene C-Datentyp ist SQL_C_CHAR oder SQL_C_BINARY.

• Der C-Datentyp ist SQL_C_DEFAULT, und der Standardmäßige C-Datentyp für den angegebenen SQL-Datentyp ist SQL_C_CHAR oder SQL_C_BINARY.

Wenn StrLen_or_Ind für alle anderen Typen von C-Daten nicht SQL_NULL_DATA oder SQL_DEFAULT_PARAM ist, geht der Treiber davon aus, dass die Größe des *DataPtr-Puffers die Größe des mit ValueType oder TargetType angegebenen C-Datentyps ist und den gesamten Datenwert sendet. Weitere Informationen finden Sie unter Konvertieren von Daten aus C in SQL-Datentypen in Anhang D: Datentypen.

Gibt zurück

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR oder SQL_INVALID_HANDLE.

Diagnostik

Wenn SQLPutData SQL_ERROR oder SQL_SUCCESS_WITH_INFO zurückgibt, kann ein zugeordneter SQLSTATE-Wert durch Aufrufen von SQLGetDiagRec mit einem HandleType von SQL_HANDLE_STMT und einem Handle of StatementHandle abgerufen werden. In der folgenden Tabelle sind die sqlSTATE-Werte aufgeführt, die häufig von SQLPutData zurückgegeben werden, und jede wird im Kontext dieser Funktion erläutert. Die Notation "(DM)" steht vor den Beschreibungen von SQLSTATEs, die vom Treiber-Manager zurückgegeben werden. Der rückgabecode, der jedem SQLSTATE-Wert zugeordnet ist, ist SQL_ERROR, sofern nicht anders angegeben.

Wenn SQLPutData während des Sendens von Daten für einen Parameter in einer SQL-Anweisung aufgerufen wird, kann jeder SQLSTATE zurückgegeben werden, der von der Funktion zurückgegeben werden kann, die aufgerufen wird, um die Anweisung auszuführen (SQLExecute oder SQLExecDirect). Wenn sie beim Senden von Daten für eine Spalte aufgerufen wird, die aktualisiert oder mit SQLBulkOperations hinzugefügt oder mit SQLSetPos aktualisiert wird, kann jeder SQLSTATE zurückgegeben werden, der von SQLBulkOperations oder SQLSetPos zurückgegeben werden kann.

Kommentare

SQLPutData kann aufgerufen werden, um Daten zur Ausführung von Daten für zwei Verwendungen anzugeben: Parameterdaten, die in einem Aufruf von SQLExecute oder SQLExecDirect verwendet werden sollen, oder Spaltendaten, die verwendet werden sollen, wenn eine Zeile aktualisiert oder von einem Aufruf von SQLBulkOperations hinzugefügt oder von einem Aufruf von SQLSetPos aktualisiert wird.

Wenn eine Anwendung SQLParamData aufruft, um zu bestimmen, welche Daten gesendet werden sollen, gibt der Treiber einen Indikator zurück, mit dem die Anwendung bestimmen kann, welche Parameterdaten gesendet werden sollen oder wo Spaltendaten gefunden werden können. Sie gibt auch SQL_NEED_DATA zurück, bei dem es sich um einen Indikator für die Anwendung handelt, mit dem SQLPutData aufgerufen werden soll, um die Daten zu senden. Im DataPtr-Argument an SQLPutData übergibt die Anwendung einen Zeiger an den Puffer, der die tatsächlichen Daten für den Parameter oder die Spalte enthält.

Wenn der Treiber SQL_SUCCESS für SQLPutData zurückgibt, ruft die Anwendung SQLParamData erneut auf. SQLParamData gibt SQL_NEED_DATA zurück, wenn weitere Daten gesendet werden müssen, in diesem Fall ruft die Anwendung SQLPutData erneut auf. Sie gibt SQL_SUCCESS zurück, wenn alle Daten zur Ausführung gesendet wurden. Die Anwendung ruft dann SQLParamData erneut auf. Wenn der Treiber SQL_NEED_DATA und einen anderen Indikator in *ValuePtrPtr zurückgibt, sind Daten für einen anderen Parameter oder eine andere Spalte erforderlich, und SQLPutData wird erneut aufgerufen. Wenn der Treiber SQL_SUCCESS zurückgibt, wurden alle Daten zur Ausführung gesendet, und die SQL-Anweisung kann ausgeführt werden, oder der SQLBulkOperations - oder SQLSetPos-Aufruf kann verarbeitet werden.

Weitere Informationen dazu, wie Daten bei ausführungsparameterdaten zur Ausführungszeit der Anweisung übergeben werden, finden Sie unter "Passing Parameter Values" in SQLBindParameter and Sending Long Data. Weitere Informationen zum Aktualisieren oder Hinzufügen von Daten zur Ausführung von Spaltendaten finden Sie im Abschnitt "Verwenden von SQLSetPos" in SQLSetPos, "Ausführen von Massenaktualisierungen mithilfe von Lesezeichen" in SQLBulkOperations und long Data and SQLSetPos und SQLBulkOperations.

Beispiel

Im folgenden Beispiel wird ein Datenquellenname namens "Test" angenommen. Die zugeordnete Datenbank sollte über eine Tabelle verfügen, die Sie wie folgt erstellen können:

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

Verwandte Funktionen

Weitere Informationen

ODBC-API-Referenz
ODBC-Headerdateien