SQLPutData Function

Conformità
Versione introdotta: Conformità agli standard ODBC 1.0: ISO 92

Riepilogo
SQLPutData consente a un'applicazione di inviare dati per un parametro o una colonna al driver in fase di esecuzione dell'istruzione. Questa funzione può essere usata per inviare valori di dati di tipo carattere o binario in parti a una colonna con un tipo di dati specifico dell'origine dati, ad esempio parametri dei tipi SQL_LONGVARBINARY o SQL_LONGVARCHAR. SQLPutData supporta l'associazione a un tipo di dati Unicode C, anche se il driver sottostante non supporta i dati Unicode.

Sintassi

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

Argomenti

StatementHandle
[Input] Handle di istruzione.

DataPtr
[Input] Puntatore a un buffer contenente i dati effettivi per il parametro o la colonna. I dati devono essere nel tipo di dati C specificato nell'argomento ValueType di SQLBindParameter (per i dati dei parametri) o nell'argomento TargetType di SQLBindCol (per i dati della colonna).

StrLen_or_Ind
[Input] Lunghezza di *DataPtr. Specifica la quantità di dati inviati in una chiamata a SQLPutData. La quantità di dati può variare con ogni chiamata per un determinato parametro o colonna. StrLen_or_Ind viene ignorato a meno che non soddisfi una delle condizioni seguenti:

• StrLen_or_Ind è SQL_NTS, SQL_NULL_DATA o SQL_DEFAULT_PARAM.

• Il tipo di dati C specificato in SQLBindParameter o SQLBindCol è SQL_C_CHAR o SQL_C_BINARY.

• Il tipo di dati C è SQL_C_DEFAULT e il tipo di dati C predefinito per il tipo di dati SQL specificato è SQL_C_CHAR o SQL_C_BINARY.

Per tutti gli altri tipi di dati C, se StrLen_or_Ind non è SQL_NULL_DATA o SQL_DEFAULT_PARAM, il driver presuppone che le dimensioni del buffer *DataPtr siano le dimensioni del tipo di dati C specificato con ValueType o TargetType e invii l'intero valore di dati. Per altre informazioni, vedere Conversione di dati da C a tipi di dati SQL nell'Appendice D: Tipi di dati.

Valori restituiti

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR o SQL_INVALID_HANDLE.

Diagnostica

Quando SQLPutData restituisce SQL_ERROR o SQL_SUCCESS_WITH_INFO, è possibile ottenere un valore SQLSTATE associato chiamando SQLGetDiagRec con handleType di SQL_HANDLE_STMT e handle di StatementHandle. La tabella seguente elenca i valori SQLSTATE comunemente restituiti da SQLPutData e ne spiega ognuno nel contesto di questa funzione. La notazione "(DM)" precede le descrizioni di SQLSTATEs restituite da Gestione driver. Il codice restituito associato a ogni valore SQLSTATE è SQL_ERROR, a meno che non sia specificato diversamente.

Se SQLPutData viene chiamato durante l'invio di dati per un parametro in un'istruzione SQL, può restituire qualsiasi SQLSTATE che può essere restituito dalla funzione chiamata per eseguire l'istruzione (SQLExecute o SQLExecDirect). Se viene chiamato durante l'invio di dati per una colonna da aggiornare o aggiungere con SQLBulkOperations o in fase di aggiornamento con SQLSetPos, può restituire qualsiasi SQLSTATE che può essere restituito da SQLBulkOperations o SQLSetPos.

Commenti

SQLPutData può essere chiamato per fornire dati in fase di esecuzione per due usi: dati dei parametri da usare in una chiamata a SQLExecute o SQLExecDirect o dati di colonna da usare quando una riga viene aggiornata o aggiunta da una chiamata a SQLBulkOperations o viene aggiornata da una chiamata a SQLSetPos.

Quando un'applicazione chiama SQLParamData per determinare i dati da inviare, il driver restituisce un indicatore che l'applicazione può usare per determinare quali dati dei parametri inviare o dove trovare i dati delle colonne. Restituisce anche SQL_NEED_DATA, che è un indicatore all'applicazione che deve chiamare SQLPutData per inviare i dati. Nell'argomento DataPtr a SQLPutData, l'applicazione passa un puntatore al buffer contenente i dati effettivi per il parametro o la colonna.

Quando il driver restituisce SQL_SUCCESS per SQLPutData, l'applicazione chiama di nuovo SQLParamData . SQLParamData restituisce SQL_NEED_DATA se è necessario inviare più dati, nel qual caso l'applicazione chiama di nuovo SQLPutData . Restituisce SQL_SUCCESS se sono stati inviati tutti i dati in fase di esecuzione. L'applicazione chiama quindi di nuovo SQLParamData . Se il driver restituisce SQL_NEED_DATA e un altro indicatore in *ValuePtrPtr, sono necessari dati per un altro parametro o colonna e SQLPutData viene chiamato di nuovo. Se il driver restituisce SQL_SUCCESS, tutti i dati in fase di esecuzione sono stati inviati e l'istruzione SQL può essere eseguita oppure è possibile elaborare la chiamata SQLBulkOperations o SQLSetPos .

Per altre informazioni sul passaggio dei dati dei parametri di esecuzione in fase di esecuzione dell'istruzione, vedere "Passaggio dei valori dei parametri" in SQLBindParameter e Invio di dati lunghi. Per altre informazioni sull'aggiornamento o l'aggiunta dei dati delle colonne di data-at-execution, vedere la sezione "Uso di SQLSetPos" in SQLSetPos, "Esecuzione di aggiornamenti in blocco tramite segnalibri" in SQLBulkOperations e Dati lunghi e SQLSetPos e SQLBulkOperations.

Esempio

Nell'esempio seguente si presuppone un nome di origine dati denominato Test. Il database associato deve avere una tabella che è possibile creare, come indicato di seguito:

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

Funzioni correlate

Vedi anche

Riferimento API ODBC
File di intestazione ODBC