Condividi tramite

SQLPutData Function

  • Articolo

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.

SQLSTATE Errore Descrizione
01000 Avviso generale Messaggio informativo specifico del driver. (La funzione restituisce SQL_SUCCESS_WITH_INFO.
01004 Dati stringa, troncati a destra I dati stringa o binari restituiti per un parametro di output hanno comportato il troncamento di dati binari non null o non NULL. Se si tratta di un valore stringa, è stato troncato a destra. (La funzione restituisce SQL_SUCCESS_WITH_INFO.
07006 Violazione dell'attributo del tipo di dati con restrizioni Impossibile convertire il valore dei dati identificato dall'argomento ValueType in SQLBindParameter per il parametro associato nel tipo di dati identificato dall'argomento ParameterType in SQLBindParameter.
07S01 Uso non valido del parametro predefinito Un valore del parametro, impostato con SQLBindParameter, è stato SQL_DEFAULT_PARAM e il parametro corrispondente non ha un valore predefinito.
08S01 Errore del collegamento di comunicazione Collegamento di comunicazione tra il driver e l'origine dati a cui è stato connesso il driver non è riuscito prima del completamento dell'elaborazione della funzione.
22001 Dati stringa, troncamento destro L'assegnazione di un carattere o di un valore binario a una colonna ha comportato il troncamento di caratteri o byte non null (carattere).

Il tipo di informazioni SQL_NEED_LONG_DATA_LEN in SQLGetInfo era "Y" e più dati sono stati inviati per un parametro long (il tipo di dati è stato SQL_LONGVARCHAR, SQL_LONGVARBINARY o un tipo di dati lungo specifico dell'origine dati) rispetto a quello specificato con l'argomento StrLen_or_IndPtr in SQLBindParameter.

Il tipo di informazioni SQL_NEED_LONG_DATA_LEN in SQLGetInfo era "Y" e più dati sono stati inviati per una colonna lunga (il tipo di dati è stato SQL_LONGVARCHAR, SQL_LONGVARBINARY o un tipo di dati specifico dell'origine dati lungo) rispetto a quello specificato nel buffer di lunghezza corrispondente a una colonna in una riga di dati aggiunti o aggiornati con SQLBulkOperations o aggiornati con SQLSetPos.
22003 Valore numerico non compreso nell'intervallo I dati inviati per un parametro numerico associato o una colonna hanno causato il troncamento dell'intera parte del numero, anziché frazionaria, quando assegnata alla colonna della tabella associata.

La restituzione di un valore numerico (come numerico o stringa) per uno o più parametri di input/output o output avrebbe causato il troncamento dell'intera parte (anziché frazionaria) del numero.
22007 Formato datetime non valido I dati inviati per un parametro o una colonna associati a una struttura di data, ora o timestamp erano rispettivamente una data, un'ora o un timestamp non validi.

Un parametro di input/output o di output è stato associato a una struttura di data, ora o timestamp C e un valore nel parametro restituito era, rispettivamente, una data, un'ora o un timestamp non validi. (La funzione restituisce SQL_SUCCESS_WITH_INFO.
22008 Overflow del campo Datetime Un'espressione datetime calcolata per un parametro di input/output o di output ha generato una struttura C di data, ora o timestamp non valida.
22012 Divisione per zero Un'espressione aritmetica calcolata per un parametro di input/output o di output ha generato una divisione per zero.
22015 Overflow del campo intervallo I dati inviati per una colonna o un parametro numerico o intervallo esatto a un tipo di dati SQL intervallo hanno causato una perdita di cifre significative.

I dati sono stati inviati per una colonna o un parametro di intervallo con più campi, sono stati convertiti in un tipo di dati numerico e non avevano alcuna rappresentazione nel tipo di dati numerico.

I dati inviati per i dati della colonna o del parametro sono stati assegnati a un tipo SQL di intervallo e non è stata fornita alcuna rappresentazione del valore del tipo C nel tipo SQL intervallo.

I dati inviati per una colonna o un parametro C numerico o intervallo esatto a un tipo C intervallo hanno causato una perdita di cifre significative.

I dati inviati per i dati della colonna o dei parametri sono stati assegnati a una struttura interval C e non sono presenti rappresentazioni dei dati nella struttura dei dati interval.
22018 Valore carattere non valido per la specifica del cast Il tipo C era un tipo numerico esatto o approssimativo, datetime o un tipo di dati interval; il tipo SQL della colonna era un tipo di dati carattere; e il valore nella colonna o nel parametro non era un valore letterale valido del tipo C associato.

Il tipo SQL era un tipo di dati numerico esatto o approssimativo, datetime o interval; il tipo C era SQL_C_CHAR; e il valore nella colonna o nel parametro non era un valore letterale valido del tipo SQL associato.
HY000 Errore generale: Si è verificato un errore per il quale non è stato specificato SQLSTATE e per il quale non è stato definito alcun SQLSTATE specifico dell'implementazione. Il messaggio di errore restituito da SQLGetDiagRec nel buffer *MessageText descrive l'errore e la relativa causa.
HY001 Errore di allocazione della memoria Il driver non è riuscito ad allocare memoria necessaria per supportare l'esecuzione o il completamento della funzione.
HY008 Operazione annullata L'elaborazione asincrona è stata abilitata per StatementHandle. La funzione è stata chiamata e prima di completare l'esecuzione, SQLCancel o SQLCancelHandle è stata chiamata in StatementHandle. La funzione è stata quindi chiamata di nuovo in StatementHandle.

La funzione è stata chiamata e prima del completamento dell'esecuzione, SQLCancel o SQLCancelHandle è stato chiamato su StatementHandle da un thread diverso in un'applicazione multithread.
HY009 Uso non valido del puntatore Null (DM) L'argomento DataPtr era un puntatore Null e l'argomento StrLen_or_Ind non era 0, SQL_DEFAULT_PARAM o SQL_NULL_DATA.
HY010 Errore della sequenza di funzioni (DM) La chiamata di funzione precedente non era una chiamata a SQLPutData o SQLParamData.

(DM) È stata chiamata una funzione in esecuzione asincrona per l'handle di connessione associato a StatementHandle. Questa funzione asincrona era ancora in esecuzione quando è stata chiamata la funzione SQLPutData.

(DM) SQLExecute, SQLExecDirect o SQLMoreResults è stato chiamato per StatementHandle e restituito SQL_PARAM_DATA_AVAILABLE. Questa funzione è stata chiamata prima del recupero dei dati per tutti i parametri trasmessi.

(DM) Una funzione in esecuzione asincrona (non questa) è stata chiamata per StatementHandle ed è ancora in esecuzione quando questa funzione è stata chiamata.
HY013 Errore di gestione della memoria Impossibile elaborare la chiamata di funzione perché non è stato possibile accedere agli oggetti di memoria sottostanti, probabilmente a causa di condizioni di memoria insufficiente.
HY019 Dati non di tipo carattere e non binari inviati in parti SQLPutData è stato chiamato più volte per un parametro o una colonna e non è stato usato per inviare dati C di tipo carattere a una colonna con un tipo di dati specifico dell'origine dati, binario o di origine dati o per inviare dati C binari a una colonna con un tipo di dati specifico dell'origine dati, binario o carattere.
HY020 Tentativo di concatenare un valore Null SQLPutData è stato chiamato più volte dalla chiamata che ha restituito SQL_NEED_DATA e, in una di queste chiamate, l'argomento StrLen_or_Ind conteneva SQL_NULL_DATA o SQL_DEFAULT_PARAM.
HY090 Lunghezza della stringa o del buffer non valida L'argomento DataPtr non era un puntatore Null e l'argomento StrLen_or_Ind era minore di 0, ma non uguale a SQL_NTS o SQL_NULL_DATA.
HY117 La connessione viene sospesa a causa dello stato sconosciuto della transazione. Sono consentite solo funzioni disconnesse e di sola lettura. (DM) Per altre informazioni sullo stato sospeso, vedere Funzione SQLEndTran.
HYT01 Il timeout della connessione è scaduto Periodo di timeout della connessione scaduto prima che l'origine dati rispondesse alla richiesta. Il periodo di timeout della connessione viene impostato tramite SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001 Il driver non supporta questa funzione (DM) Il driver associato a StatementHandle non supporta la funzione.
IM017 Il polling è disabilitato in modalità di notifica asincrona Ogni volta che viene usato il modello di notifica, il polling è disabilitato.
IM018 SQLCompleteAsync non è stato chiamato per completare l'operazione asincrona precedente su questo handle. Se la chiamata di funzione precedente sull'handle restituisce SQL_STILL_EXECUTING e se la modalità di notifica è abilitata, è necessario chiamare SQLCompleteAsync sull'handle per eseguire la post-elaborazione e completare l'operazione.

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.

Nota

Un'applicazione può usare SQLPutData per inviare dati in parti solo quando si inviano dati C carattere a una colonna con un tipo di dati specifico di un carattere, binario o un'origine dati specifica o quando si inviano dati binari C a una colonna con un tipo di dati specifico dell'origine dati, binario o carattere. Se SQLPutData viene chiamato più volte in qualsiasi altra condizione, restituisce SQL_ERROR e SQLSTATE HY019 (dati non carattere e non binari inviati in parti).

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);  
}
Per informazioni su Vedere
Associazione di un buffer a un parametro Funzione SQLBindParameter
Annullamento dell'elaborazione delle istruzioni Funzione SQLCancel
Esecuzione di un'istruzione SQL Funzione SQLExecDirect
Esecuzione di un'istruzione SQL preparata Funzione SQLExecute
Restituzione del parametro successivo per l'invio di dati per Funzione SQLParamData

Vedi anche

Riferimento API ODBC
File di intestazione ODBC