Funzione SQLGetData

Articolo
05/24/2023

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

Riepilogo
SQLGetData recupera i dati per una singola colonna nel set di risultati o per un singolo parametro dopo che SQLParamData restituisce SQL_PARAM_DATA_AVAILABLE. Può essere chiamato più volte per recuperare dati a lunghezza variabile in parti.

Sintassi

  
SQLRETURN SQLGetData(  
      SQLHSTMT       StatementHandle,  
      SQLUSMALLINT   Col_or_Param_Num,  
      SQLSMALLINT    TargetType,  
      SQLPOINTER     TargetValuePtr,  
      SQLLEN         BufferLength,  
      SQLLEN *       StrLen_or_IndPtr);

Argomenti

StatementHandle
[Input] Handle di istruzione.

Col_or_Param_Num
[Input] Per il recupero dei dati delle colonne, è il numero della colonna per cui restituire i dati. Le colonne del set di risultati vengono numerate in ordine di colonna crescente a partire da 1. La colonna del segnalibro è il numero di colonna 0; questa opzione può essere specificata solo se i segnalibri sono abilitati.

Per il recupero dei dati dei parametri, è l'ordinale del parametro, che inizia da 1.

TargetType
[Input] Identificatore del tipo di dati C del buffer *TargetValuePtr . Per un elenco di tipi di dati E identificatori di tipo C validi, vedere la sezione Tipi di dati C nell'Appendice D: Tipi di dati.

Se TargetType è SQL_ARD_TYPE, il driver usa l'identificatore di tipo specificato nel campo SQL_DESC_CONCISE_TYPE della ARD. Se TargetType è SQL_APD_TYPE, SQLGetData userà lo stesso tipo di dati C specificato in SQLBindParameter. In caso contrario, il tipo di dati C specificato in SQLGetData esegue l'override del tipo di dati C specificato in SQLBindParameter. Se è SQL_C_DEFAULT, il driver seleziona il tipo di dati C predefinito in base al tipo di dati SQL dell'origine.

È anche possibile specificare un tipo di dati C esteso. Per altre informazioni, vedere Tipi di dati C in ODBC.

TargetValuePtr
[Output] Puntatore al buffer in cui restituire i dati.

TargetValuePtr non può essere NULL.

BufferLength
[Input] Lunghezza del buffer *TargetValuePtr in byte.

Il driver usa BufferLength per evitare di scrivere oltre la fine del buffer *TargetValuePtr durante la restituzione di dati a lunghezza variabile, ad esempio dati di tipo carattere o binario. Si noti che il driver conta il carattere di terminazione Null quando si restituiscono dati di tipo carattere a *TargetValuePtr. *TargetValuePtr deve pertanto contenere spazio per il carattere di terminazione Null oppure il driver tronca i dati.

Quando il driver restituisce dati a lunghezza fissa, ad esempio un numero intero o una struttura di data, il driver ignora BufferLength e presuppone che il buffer sia sufficientemente grande da contenere i dati. È quindi importante per l'applicazione allocare un buffer sufficientemente grande per i dati a lunghezza fissa o il driver scriverà oltre la fine del buffer.

SQLGetData restituisce SQLSTATE HY090 (stringa o lunghezza buffer non valida) quando BufferLength è minore di 0, ma non quando BufferLength è 0.

StrLen_or_IndPtr
[Output] Puntatore al buffer in cui restituire la lunghezza o il valore dell'indicatore. Se si tratta di un puntatore Null, non viene restituito alcun valore di lunghezza o indicatore. Viene restituito un errore quando i dati recuperati sono NULL.

SQLGetData può restituire i valori seguenti nel buffer di lunghezza/indicatore:

Lunghezza dei dati disponibili per la restituzione
SQL_NO_TOTAL
SQL_NULL_DATA

Per altre informazioni, vedere Uso di valori di lunghezza/indicatore e "Commenti" in questo argomento.

Valori restituiti

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR o SQL_INVALID_HANDLE.

Diagnostica

Quando SQLGetData 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 SQLGetData 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	Non tutti i dati per la colonna specificata, Col_or_Param_Num, possono essere recuperati in una singola chiamata alla funzione. SQL_NO_TOTAL o la lunghezza dei dati rimanenti nella colonna specificata prima della chiamata corrente a SQLGetData viene restituita in *StrLen_or_IndPtr. (La funzione restituisce SQL_SUCCESS_WITH_INFO. Per altre informazioni sull'uso di più chiamate a SQLGetData per una singola colonna, vedere "Comments".
01S07	Troncamento frazionario	I dati restituiti per una o più colonne sono stati troncati. Per i tipi di dati numerici, la parte frazionaria del numero è stata troncata. Per i tipi di dati time, timestamp e interval contenenti un componente time, la parte frazionaria dell'ora è stata troncata. (La funzione restituisce SQL_SUCCESS_WITH_INFO.
07006	Violazione dell'attributo del tipo di dati con restrizioni	Il valore di dati di una colonna nel set di risultati non può essere convertito nel tipo di dati C specificato dall'argomento TargetType.
07009	Indice descrittore non valido	Il valore specificato per l'argomento Col_or_Param_Num era 0 e l'attributo dell'istruzione SQL_ATTR_USE_BOOKMARKS è stato impostato su SQL_UB_OFF. Il valore specificato per l'argomento Col_or_Param_Num è maggiore del numero di colonne nel set di risultati. Il valore Col_or_Param_Num non è uguale all'ordinale del parametro disponibile. (DM) La colonna specificata è stata associata. Questa descrizione non si applica ai driver che restituiscono la maschera di bit SQL_GD_BOUND per l'opzione SQL_GETDATA_EXTENSIONS in SQLGetInfo. (DM) Il numero della colonna specificata è minore o uguale al numero della colonna associata più alta. Questa descrizione non si applica ai driver che restituiscono la maschera di bit SQL_GD_ANY_COLUMN per l'opzione SQL_GETDATA_EXTENSIONS in SQLGetInfo. (DM) L'applicazione ha già chiamato SQLGetData per la riga corrente; il numero della colonna specificata nella chiamata corrente è minore del numero della colonna specificata nella chiamata precedente e il driver non restituisce la maschera di bit SQL_GD_ANY_ORDER per l'opzione SQL_GETDATA_EXTENSIONS in SQLGetInfo. (DM) L'argomento TargetType è stato SQL_ARD_TYPE e il record del descrittore di Col_or_Param_Num nella ARD non è riuscito a verificare la coerenza. (DM) L'argomento TargetType è stato SQL_ARD_TYPE e il valore nel campo SQL_DESC_COUNT della ARD era minore dell'argomento Col_or_Param_Num .
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.
22002	Variabile indicatore obbligatoria ma non fornita	StrLen_or_IndPtr era un puntatore Null e i dati NULL sono stati recuperati.
22003	Valore numerico non compreso nell'intervallo	La restituzione del valore numerico (come numerico o stringa) per la colonna avrebbe causato il troncamento dell'intera parte (anziché frazionaria) del numero. Per altre informazioni, vedere Appendice D: Tipi di dati.
22007	Formato datetime non valido	La colonna di caratteri nel set di risultati è stata associata a una struttura di data, ora o timestamp C e il valore nella colonna era rispettivamente una data, un'ora o un timestamp non valido. Per altre informazioni, vedere Appendice D: Tipi di dati.
22012	Divisione per zero	È stato restituito un valore di un'espressione aritmetica che ha generato la divisione per zero.
22015	Overflow del campo intervallo	L'assegnazione da un tipo SQL numerico o intervallo esatto a un tipo C intervallo ha causato una perdita di cifre significative nel campo iniziale. Quando si restituiscono dati a un tipo C intervallo, non è presente alcuna rappresentazione del valore del tipo SQL nel tipo C intervallo.
22018	Valore carattere non valido per la specifica del cast	Una colonna di caratteri nel set di risultati è stata restituita a un buffer C di caratteri e la colonna contiene un carattere per il quale non è presente alcuna rappresentazione nel set di caratteri del buffer. 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 non era un valore letterale valido del tipo C associato.
24000	Stato del cursore non valido	(DM) La funzione è stata chiamata senza prima chiamare SQLFetch o SQLFetchScroll per posizionare il cursore sulla riga di dati richiesta. (DM) StatementHandle era in uno stato eseguito, ma nessun set di risultati era associato a StatementHandle. È stato aperto un cursore in StatementHandle e SQLFetch o SQLFetchScroll , ma il cursore è stato posizionato prima dell'inizio del set di risultati o dopo la fine del set di risultati.
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.
HY003	Tipo di programma non compreso nell'intervallo	(DM) L'argomento TargetType non era un tipo di dati valido, SQL_C_DEFAULT, SQL_ARD_TYPE (in caso di recupero di dati di colonna) o SQL_APD_TYPE (in caso di recupero dei dati dei parametri). (DM) L'argomento Col_or_Param_Num era 0 e l'argomento TargetType non è stato SQL_C_BOOKMARK per un segnalibro a lunghezza fissa o SQL_C_VARBOOKMARK per un segnalibro a lunghezza variabile.
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 su StatementHandle e quindi la funzione è stata chiamata nuovamente in StatementHandle. La funzione è stata chiamata e prima di completare l'esecuzione, SQLCancel o SQLCancelHandle è stato chiamato su StatementHandle *da un thread diverso in un'applicazione multithread e quindi la funzione è stata chiamata nuovamente in StatementHandle.*
HY009	Uso non valido del puntatore Null	(DM) L'argomento TargetValuePtr è un puntatore Null.
HY010	Errore della sequenza di funzioni	(DM) StatementHandle specificato non era in uno stato eseguito. La funzione è stata chiamata senza prima chiamare SQLExecDirect, SQLExecute o una funzione del catalogo. (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 SQLGetData . (DM) Una funzione in esecuzione asincrona (non questa) è stata chiamata per StatementHandle ed è ancora in esecuzione quando questa funzione è stata chiamata. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations o SQLSetPos è stato chiamato per StatementHandle e restituito SQL_NEED_DATA. Questa funzione è stata chiamata prima dell'invio dei dati per tutti i parametri o le colonne data-at-execution. (DM) StatementHandle era in uno stato eseguito, ma nessun set di risultati era associato a StatementHandle. Una chiamata a SQLExeceute, SQLExecDirect o SQLMoreResults ha restituito SQL_PARAM_DATA_AVAILABLE, ma SQLGetData è stato chiamato, anziché SQLParamData.
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.
HY090	Lunghezza della stringa o del buffer non valida	(DM) Il valore specificato per l'argomento BufferLength è minore di 0. Il valore specificato per l'argomento BufferLength era minore di 4, l'argomento Col_or_Param_Num era impostato su 0 e il driver era un driver ODBC 2.x.
HY109	Posizione del cursore non valida	Il cursore è stato posizionato (da SQLSetPos, SQLFetch, SQLFetchScroll o SQLBulkOperations) in una riga che è stata eliminata o che non è stato possibile recuperare. Il cursore era un cursore forward-only e le dimensioni del set di righe erano maggiori di una.
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.
HYC00	Funzionalità facoltativa non implementata	Il driver o l'origine dati non supporta l'uso di SQLGetData con più righe in SQLFetchScroll. Questa descrizione non si applica ai driver che restituiscono la maschera di bit SQL_GD_BLOCK per l'opzione SQL_GETDATA_EXTENSIONS in SQLGetInfo. Il driver o l'origine dati non supporta la conversione specificata dalla combinazione dell'argomento TargetType e del tipo di dati SQL della colonna corrispondente. Questo errore si applica solo quando è stato eseguito il mapping del tipo di dati SQL della colonna a un tipo di dati SQL specifico del driver. Il driver supporta solo ODBC 2.xe l'argomento TargetType è uno dei seguenti: SQL_C_NUMERIC SQL_C_SBIGINT SQL_C_UBIGINT e uno qualsiasi dei tipi di dati C intervallo elencati in Tipi di dati C nell'Appendice D: Tipi di dati. Il driver supporta solo le versioni ODBC precedenti alla 3.50 e l'argomento TargetType è stato SQL_C_GUID.
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 corrispondente 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.

Commenti

SQLGetData restituisce i dati in una colonna specificata. SQLGetData può essere chiamato solo dopo che una o più righe sono state recuperate dal set di risultati da SQLFetch, SQLFetchScroll o SQLExtendedFetch. Se i dati a lunghezza variabile sono troppo grandi da restituire in una singola chiamata a SQLGetData (a causa di una limitazione nell'applicazione), SQLGetData può recuperarlo in parti. È possibile associare alcune colonne in una riga e chiamare SQLGetData per altre, anche se questa operazione è soggetta ad alcune restrizioni. Per altre informazioni, vedere Recupero di dati lunghi.

Per informazioni sull'uso di SQLGetData con parametri di output trasmessi, vedere Recupero di parametri di output tramite SQLGetData.

Uso di SQLGetData

Se il driver non supporta le estensioni a SQLGetData, la funzione può restituire dati solo per le colonne non associate con un numero maggiore di quello dell'ultima colonna associata. Inoltre, all'interno di una riga di dati, il valore dell'argomento Col_or_Param_Num in ogni chiamata a SQLGetData deve essere maggiore o uguale al valore di Col_or_Param_Num nella chiamata precedente, ovvero i dati devono essere recuperati in ordine crescente di numeri di colonna. Infine, se non sono supportate estensioni, non è possibile chiamare SQLGetData se la dimensione del set di righe è maggiore di 1.

I driver possono rilassare una qualsiasi di queste restrizioni. Per determinare quali restrizioni un driver riduce, un'applicazione chiama SQLGetInfo con una delle opzioni di SQL_GETDATA_EXTENSIONS seguenti:

SQL_GD_OUTPUT_PARAMS = SQLGetData può essere chiamato per restituire i valori dei parametri di output. Per altre informazioni, vedere Recupero di parametri di output tramite SQLGetData.
SQL_GD_ANY_COLUMN. Se viene restituita questa opzione, è possibile chiamare SQLGetData per qualsiasi colonna non associata, incluse quelle prima dell'ultima colonna associata.
SQL_GD_ANY_ORDER. Se viene restituita questa opzione, è possibile chiamare SQLGetData per le colonne non associate in qualsiasi ordine.
SQL_GD_BLOCK. Se questa opzione viene restituita da SQLGetInfo per il SQL_GETDATA_EXTENSIONS InfoType, il driver supporta le chiamate a SQLGetData quando la dimensione del set di righe è maggiore di 1 e l'applicazione può chiamare SQLSetPos con l'opzione SQL_POSITION per posizionare il cursore sulla riga corretta prima di chiamare SQLGetData.
SQL_GD_BOUND. Se viene restituita questa opzione, è possibile chiamare SQLGetData per le colonne associate e per le colonne non associate.

Ci sono due eccezioni a queste restrizioni e la capacità di un conducente di rilassarli. In primo luogo, SQLGetData non deve mai essere chiamato per un cursore forward-only quando la dimensione del set di righe è maggiore di 1. In secondo luogo, se un driver supporta i segnalibri, deve sempre supportare la possibilità di chiamare SQLGetData per la colonna 0, anche se non consente alle applicazioni di chiamare SQLGetData per altre colonne prima dell'ultima colonna associata. Quando un'applicazione usa un driver ODBC 2*.x*, SQLGetData restituirà correttamente un segnalibro quando viene chiamato con Col_or_Param_Num uguale a 0 dopo una chiamata a SQLFetch, perché SQLFetch è mappato da ODBC 3*.x* Driver Manager a SQLExtendedFetch con un fetchOrientation di SQL_FETCH_NEXT e SQLGetData con un Col_or_Param_Num di 0 viene mappato da ODBC 3*.x* Driver Manager a SQLGetStmtOption con un'opzione di SQL_GET_BOOKMARK.

Non è possibile usare SQLGetData per recuperare il segnalibro per una riga appena inserita chiamando SQLBulkOperations con l'opzione SQL_ADD, perché il cursore non è posizionato sulla riga. Un'applicazione può recuperare il segnalibro per tale riga associando la colonna 0 prima di chiamare SQLBulkOperations con SQL_ADD, nel qual caso SQLBulkOperations restituisce il segnalibro nel buffer associato. SQLFetchScroll può quindi essere chiamato con SQL_FETCH_BOOKMARK per riposizionare il cursore su tale riga.

Se l'argomento TargetType è un tipo di dati interval, per i dati vengono utilizzati rispettivamente il valore predefinito di precisione iniziale intervallo (2) e la precisione predefinita dei secondi di intervallo (6), come impostato nei campi SQL_DESC_DATETIME_INTERVAL_PRECISION e SQL_DESC_PRECISION della ARD. Se l'argomento TargetType è un tipo di dati SQL_C_NUMERIC, la precisione predefinita (definita dal driver) e la scala predefinita (0), come impostato nei campi SQL_DESC_PRECISION e SQL_DESC_SCALE della ARD, vengono utilizzati per i dati. Se una precisione o una scala predefinita non è appropriata, l'applicazione deve impostare in modo esplicito il campo descrittore appropriato tramite una chiamata a SQLSetDescField o SQLSetDescRec. Può impostare il campo SQL_DESC_CONCISE_TYPE su SQL_C_NUMERIC e chiamare SQLGetData con un argomento TargetType di SQL_ARD_TYPE, che causerà l'uso dei valori di precisione e scala nei campi del descrittore.

Nota

In ODBC 2*.x*, le applicazioni impostano TargetType su SQL_C_DATE, SQL_C_TIME o SQL_C_TIMESTAMP per indicare che *TargetValuePtr è una struttura di data, ora o timestamp. In ODBC 3*.x*, le applicazioni impostano TargetType su SQL_C_TYPE_DATE, SQL_C_TYPE_TIME o SQL_C_TYPE_TIMESTAMP. Gestione driver crea mapping appropriati, se necessario, in base alla versione dell'applicazione e del driver.

Recupero di dati a lunghezza variabile in parti

SQLGetData può essere usato per recuperare dati da una colonna contenente dati a lunghezza variabile in parti, ovvero quando l'identificatore del tipo di dati SQL della colonna è SQL_CHAR, SQL_VARCHAR, SQL_LONGVARCHAR, SQL_WCHAR, SQL_WVARCHAR, SQL_WLONGVARCHAR, SQL_BINARY, SQL_VARBINARY, SQL_LONGVARBINARY o un identificatore specifico del driver per un tipo a lunghezza variabile.

Per recuperare i dati da una colonna in parti, l'applicazione chiama SQLGetData più volte in successione per la stessa colonna. In ogni chiamata, SQLGetData restituisce la parte successiva dei dati. Spetta all'applicazione riassemblare le parti, prendendo cura di rimuovere il carattere di terminazione Null da parti intermedie dei dati di tipo carattere. Se sono presenti più dati da restituire o non è stato allocato un buffer sufficiente per il carattere di terminazione, SQLGetData restituisce SQL_SUCCESS_WITH_INFO e SQLSTATE 01004 (dati troncati). Quando restituisce l'ultima parte dei dati, SQLGetData restituisce SQL_SUCCESS. Non è possibile restituire né SQL_NO_TOTAL né zero nell'ultima chiamata valida per recuperare i dati da una colonna, perché l'applicazione non avrebbe modo di conoscere la quantità di dati nel buffer dell'applicazione valida. Se sqlGetData viene chiamato in seguito, restituisce SQL_NO_DATA. Per altre informazioni, vedere la sezione successiva "Recupero di dati con SQLGetData".

I segnalibri a lunghezza variabile possono essere restituiti in parti da SQLGetData. Come per altri dati, una chiamata a SQLGetData per restituire segnalibri a lunghezza variabile nelle parti restituirà SQLSTATE 01004 (dati stringa, troncati a destra) e SQL_SUCCESS_WITH_INFO quando sono presenti più dati da restituire. Questo è diverso dal caso in cui un segnalibro a lunghezza variabile viene troncato da una chiamata a SQLFetch o SQLFetchScroll, che restituisce SQL_ERROR e SQLSTATE 22001 (dati stringa troncati a destra).

SqlGetData non può essere usato per restituire dati a lunghezza fissa in parti. Se SQLGetData viene chiamato più volte in una riga per una colonna contenente dati a lunghezza fissa, restituisce SQL_NO_DATA per tutte le chiamate dopo la prima.

Recupero di parametri di output trasmessi

Se un driver supporta parametri di output trasmessi, un'applicazione può chiamare SQLGetData con un buffer ridotto molte volte per recuperare un valore di parametro di grandi dimensioni. Per altre informazioni sul parametro di output trasmesso, vedere Recupero di parametri di output tramite SQLGetData.

Recupero di dati con SQLGetData

Per restituire i dati per la colonna specificata, SQLGetData esegue la sequenza di passaggi seguente:

Restituisce SQL_NO_DATA se sono già stati restituiti tutti i dati per la colonna.
Imposta *StrLen_or_IndPtr su SQL_NULL_DATA se i dati sono NULL. Se i dati sono NULL e StrLen_or_IndPtr è un puntatore Null, SQLGetData restituisce SQLSTATE 22002 (variabile indicatore obbligatoria ma non specificata).

Se i dati per la colonna non sono NULL, SQLGetData procede con il passaggio 3.
Se l'attributo dell'istruzione SQL_ATTR_MAX_LENGTH è impostato su un valore diverso da zero, se la colonna contiene dati di tipo carattere o binario e se SQLGetData non è stato chiamato in precedenza per la colonna, i dati vengono troncati a SQL_ATTR_MAX_LENGTH byte.

Nota

L'attributo di istruzione SQL_ATTR_MAX_LENGTH è progettato per ridurre il traffico di rete. Viene in genere implementato dall'origine dati, che tronca i dati prima di restituirli attraverso la rete. I driver e le origini dati non sono necessari per supportarli. Pertanto, per garantire che i dati vengano troncati a una determinata dimensione, un'applicazione deve allocare un buffer di tale dimensione e specificare le dimensioni nell'argomento BufferLength .
Converte i dati nel tipo specificato in TargetType. Ai dati viene assegnata la precisione e la scala predefinite per il tipo di dati. Se TargetType è SQL_ARD_TYPE, viene utilizzato il tipo di dati nel campo SQL_DESC_CONCISE_TYPE della ARD. Se TargetType è SQL_ARD_TYPE, ai dati viene assegnata la precisione e la scala nei campi SQL_DESC_DATETIME_INTERVAL_PRECISION, SQL_DESC_PRECISION e SQL_DESC_SCALE della ARD, a seconda del tipo di dati nel campo SQL_DESC_CONCISE_TYPE. Se una precisione o una scala predefinita non è appropriata, l'applicazione deve impostare in modo esplicito il campo descrittore appropriato tramite una chiamata a SQLSetDescField o SQLSetDescRec.
Se i dati sono stati convertiti in un tipo di dati a lunghezza variabile, ad esempio carattere o binario, SQLGetData verifica se la lunghezza dei dati supera BufferLength. Se la lunghezza dei dati di tipo carattere (incluso il carattere di terminazione Null) supera BufferLength, SQLGetData tronca i dati in BufferLength meno la lunghezza di un carattere di terminazione Null. Termina quindi i dati. Se la lunghezza dei dati binari supera la lunghezza del buffer di dati, SQLGetData lo tronca a BufferLength byte.

Se il buffer di dati fornito è troppo piccolo per contenere il carattere di terminazione Null, SQLGetData restituisce SQL_SUCCESS_WITH_INFO e SQLSTATE 01004.

SQLGetData non tronca mai i dati convertiti in tipi di dati a lunghezza fissa. Si presuppone sempre che la lunghezza di *TargetValuePtr sia la dimensione del tipo di dati.
Inserisce i dati convertiti (ed eventualmente troncati) in *TargetValuePtr. Si noti che SQLGetData non può restituire dati fuori riga.
Posiziona la lunghezza dei dati in *StrLen_or_IndPtr. Se StrLen_or_IndPtr è un puntatore Null, SQLGetData non restituisce la lunghezza.
- Per i dati di tipo carattere o binario, si tratta della lunghezza dei dati dopo la conversione e prima del troncamento a causa di BufferLength. Se il driver non riesce a determinare la lunghezza dei dati dopo la conversione, come accade talvolta con dati lunghi, restituisce SQL_SUCCESS_WITH_INFO e imposta la lunghezza su SQL_NO_TOTAL. (Ultima chiamata a SQLGetData deve restituire sempre la lunghezza dei dati, non zero o SQL_NO_TOTAL. Se i dati sono stati troncati a causa dell'attributo di istruzione SQL_ATTR_MAX_LENGTH, il valore di questo attributo, anziché la lunghezza effettiva, viene inserito in *StrLen_or_IndPtr. Questo perché questo attributo è progettato per troncare i dati nel server prima della conversione, quindi il driver non ha modo di capire qual è la lunghezza effettiva. Quando SQLGetData viene chiamato più volte in successione per la stessa colonna, si tratta della lunghezza dei dati disponibili all'inizio della chiamata corrente, ovvero la lunghezza diminuisce con ogni chiamata successiva.
- Per tutti gli altri tipi di dati, si tratta della lunghezza dei dati dopo la conversione; ovvero è la dimensione del tipo in cui sono stati convertiti i dati.
Se i dati vengono troncati senza perdita di significato durante la conversione (ad esempio, il numero reale 1,234 viene troncato quando viene convertito nell'intero 1) o perché BufferLength è troppo piccolo (ad esempio, la stringa "abcdef" viene inserita in un buffer a 4 byte), SQLGetData restituisce SQLSTATE 01004 (dati troncati) e SQL_SUCCESS_WITH_INFO. Se i dati vengono troncati senza perdita di significato a causa dell'attributo dell'istruzione SQL_ATTR_MAX_LENGTH, SQLGetData restituisce SQL_SUCCESS e non restituisce SQLSTATE 01004 (dati troncati).

Il contenuto del buffer di dati associato (se SQLGetData viene chiamato su una colonna associata) e il buffer di lunghezza/indicatore non è definito se SQLGetData non restituisce SQL_SUCCESS o SQL_SUCCESS_WITH_INFO.

Le chiamate successive a SQLGetData recupereranno i dati dall'ultima colonna richiesta. Gli offset precedenti diventano non validi. Ad esempio, quando viene eseguita la sequenza seguente:

SQLGetData(icol=n), SQLGetData(icol=m), SQLGetData(icol=n)

la seconda chiamata a SQLGetData(icol=n) recupera i dati dall'inizio della colonna n. Qualsiasi offset nei dati dovuto a chiamate precedenti a SQLGetData per la colonna non è più valido.

Descrittori e SQLGetData

SQLGetData non interagisce direttamente con alcun campo descrittore.

Se TargetType è SQL_ARD_TYPE, viene utilizzato il tipo di dati nel campo SQL_DESC_CONCISE_TYPE della ARD. Se TargetType è SQL_ARD_TYPE o SQL_C_DEFAULT, ai dati viene assegnata la precisione e la scala nei campi SQL_DESC_DATETIME_INTERVAL_PRECISION, SQL_DESC_PRECISION e SQL_DESC_SCALE della ARD, a seconda del tipo di dati nel campo SQL_DESC_CONCISE_TYPE.

Esempio di codice

Nell'esempio seguente un'applicazione esegue un'istruzione SELECT per restituire un set di risultati degli ID, dei nomi e dei numeri di telefono dei clienti ordinati in base al nome, all'ID e al numero di telefono. Per ogni riga di dati, chiama SQLFetch per posizionare il cursore alla riga successiva. Chiama SQLGetData per recuperare i dati recuperati. I buffer per i dati e il numero restituito di byte vengono specificati nella chiamata a SQLGetData. Infine, stampa il nome, l'ID e il numero di telefono di ogni dipendente.

#define NAME_LEN 50  
#define PHONE_LEN 50  
  
SQLCHAR      szName[NAME_LEN], szPhone[PHONE_LEN];  
SQLINTEGER   sCustID, cbName, cbAge, cbBirthday;  
SQLRETURN    retcode;  
SQLHSTMT     hstmt;  
  
retcode = SQLExecDirect(hstmt,  
   "SELECT CUSTID, NAME, PHONE FROM CUSTOMERS ORDER BY 2, 1, 3",  
   SQL_NTS);  
  
if (retcode == SQL_SUCCESS) {  
   while (TRUE) {  
      retcode = SQLFetch(hstmt);  
      if (retcode == SQL_ERROR || retcode == SQL_SUCCESS_WITH_INFO) {  
         show_error();  
      }  
      if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO){  
  
         /* Get data for columns 1, 2, and 3 */  
  
         SQLGetData(hstmt, 1, SQL_C_ULONG, &sCustID, 0, &cbCustID);  
         SQLGetData(hstmt, 2, SQL_C_CHAR, szName, NAME_LEN, &cbName);  
         SQLGetData(hstmt, 3, SQL_C_CHAR, szPhone, PHONE_LEN,  
            &cbPhone);  
  
         /* Print the row of data */  
  
         fprintf(out, "%-5d %-*s %*s", sCustID, NAME_LEN-1, szName,   
            PHONE_LEN-1, szPhone);  
      } else {  
         break;  
      }  
   }  
}

Per informazioni su	Vedere
Assegnazione dell'archiviazione per una colonna in un set di risultati	SQLBindCol
Esecuzione di operazioni bulk che non sono correlate alla posizione del cursore del blocco	SQLBulkOperations
Annullamento dell'elaborazione delle istruzioni	SQLCancel
Esecuzione di un'istruzione SQL	SQLExecDirect
Esecuzione di un'istruzione SQL preparata	SQLExecute
Recupero di un blocco di dati o scorrimento di un set di risultati	SQLFetchScroll
Recupero di una singola riga di dati o di un blocco di dati in una direzione forward-only	SQLFetch
Invio dei dati dei parametri in fase di esecuzione	SQLPutData
Posizionamento del cursore, aggiornamento dei dati nel set di righe o aggiornamento o eliminazione di dati nel set di righe	SQLSetPos

Vedi anche

Riferimento API ODBC
File di intestazione ODBC
Recupero di parametri di output tramite SQLGetData

Condividi tramite

Funzione SQLGetData

Sintassi

Argomenti

Valori restituiti

Diagnostica

Commenti

Uso di SQLGetData

Recupero di dati a lunghezza variabile in parti

Recupero di parametri di output trasmessi

Recupero di dati con SQLGetData

Descrittori e SQLGetData

Esempio di codice

Vedi anche

Commenti e suggerimenti

Risorse aggiuntive

Condividi tramite

Funzione SQLGetData

Sintassi

Argomenti

Valori restituiti

Diagnostica

Commenti

Uso di SQLGetData

Recupero di dati a lunghezza variabile in parti

Recupero di parametri di output trasmessi

Recupero di dati con SQLGetData

Descrittori e SQLGetData

Esempio di codice

Funzioni correlate

Vedi anche

Commenti e suggerimenti

Risorse aggiuntive