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.
Resi
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 handleTypedi 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);
}
Funzioni correlate
| 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
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per