Funzione SQLGetData

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

Summary
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 della colonna, è il numero della colonna per cui restituire i dati. Le colonne del set di risultati sono numerate in ordine crescente a partire da 1. La colonna del segnalibro è il numero di colonna 0. può essere specificato solo se i segnalibri sono abilitati.

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

Targettype
[Input] Identificatore di tipo del tipo di dati C del buffer *TargetValuePtr. Per un elenco dei tipi di dati C e degli identificatori di tipo 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 dell'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 non è SQL_C_DEFAULT, il driver seleziona il tipo di dati C predefinito in base SQL tipo di dati 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 la scrittura oltre la fine del buffer TargetValuePtr quando vengono restituiti dati a lunghezza variabile, ad esempio dati di tipo * carattere o binario. Si noti che il driver conta il carattere di terminazione Null quando 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 che l'applicazione alloca un buffer sufficientemente grande per i dati a lunghezza fissa oppure il driver scriverà oltre la fine del buffer.

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

StrLen_or_IndPtr
[Output] Puntatore al buffer in cui restituire il valore della lunghezza o 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 da restituire

  • SQL_NO_TOTAL

  • SQL_NULL_DATA

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

Restituisce

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 un HandleType di SQL_HANDLE_STMT e un Handle di StatementHandle. Nella tabella seguente sono elencati i valori SQLSTATE comunemente restituiti da SQLGetData e vengono illustrati 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, se non diversamente specificato.

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 "Commenti".
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 dei dati di una colonna nel set di risultati non può essere convertito nel tipo di dati C specificato dall'argomento TargetType.
07009 Indice del 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 Col_or_Param_Num valore non è uguale al numero ordinale del parametro disponibile.

(DM) La colonna specificata è stata associata. Questa descrizione non si applica ai driver che restituiscono SQL_GD_BOUND maschera di bit 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 SQL_GD_ANY_COLUMN bit 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 SQL_GD_ANY_ORDER bit per l'opzione SQL_GETDATA_EXTENSIONS in SQLGetInfo.

(DM) L'argomento TargetType SQL_ARD_TYPE e il record Col_or_Param_Num descrittore nell'ARD non ha superato la verifica di coerenza.

(DM) L'argomento TargetType SQL_ARD_TYPE e il valore nel campo SQL_DESC_COUNT dell'ARD è minore dell'argomento Col_or_Param_Num.
08S01 Errore del collegamento di comunicazione Il 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 sono stati recuperati dati NULL.
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 character 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 validi. Per altre informazioni, vedere Appendice D: Tipi di dati.
22012 Divisione per zero È stato restituito un valore di un'espressione aritmetica che ha restituito una divisione per zero.
22015 Overflow del campo intervallo L'assegnazione da un tipo numerico o SQL intervallo esatto a un tipo intervallo C ha causato la perdita di cifre significative nel campo iniziale.

Quando i dati vengono restituiti a un tipo C intervallo, non è presente alcuna rappresentazione del valore del tipo SQL nel tipo intervallo C.
22018 Valore di carattere non valido per la specifica del cast Una colonna di tipo carattere nel set di risultati è stata restituita a un buffer di caratteri C e la colonna contiene un carattere per il quale non esiste alcuna rappresentazione nel set di caratteri del buffer.

Il tipo C era un tipo di dati numerico esatto o approssimativo, un tipo di dati datetime o interval; il SQL della colonna era un tipo di dati carattere. e il valore nella colonna non è 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 necessaria.

(DM) StatementHandle era in uno stato eseguito, ma nessun set di risultati è stato associato a StatementHandle.

È stato aperto un cursore in StatementHandle e sono stati chiamati 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 esiste un SQLSTATE specifico e per il quale non è stato definito 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 la memoria necessaria per supportare l'esecuzione o il completamento della funzione.
HY003 Tipo di programma non compreso nell'intervallo (DM) L'argomento TargetType non è un tipo di dati valido, SQL_C_DEFAULT, SQL_ARD_TYPE (in caso di recupero dei dati della 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 era SQL_C_BOOKMARK per un segnalibro a lunghezza fissa o un SQL_C_VARBOOKMARK per un segnalibro a lunghezza variabile.
HY008 Operation canceled L'elaborazione asincrona è stata abilitata per StatementHandle. La funzione è stata chiamata e prima del completamento dell'esecuzione, SQLCancel o SQLCancelHandle è stato chiamato su StatementHandle e quindi la funzione è stata chiamata nuovamente su 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 e quindi la funzione è stata chiamata nuovamente su StatementHandle.
HY009 Uso non valido del puntatore Null (DM) L'argomento TargetValuePtr è un puntatore Null.
HY010 Errore della sequenza di funzione (DM) L'oggetto StatementHandle specificato non è in uno stato eseguito. La funzione è stata chiamata senza prima chiamare SQLExecDirect, SQLExecute o una funzione di catalogo.

(DM) È stata chiamata una funzione in esecuzione in modo asincrono 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 in modo asincrono (non questa) è stata chiamata per StatementHandle ed era ancora in esecuzione quando è stata chiamata questa funzione.

(DM) SQLExecute, SQLExecDirect, SQLBulkOperations o SQLSetPos sono stati chiamati per StatementHandle e sono stati restituiti 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 è stato associato a StatementHandle.

Una chiamata a SQLExeceute, SQLExecDirect o SQLMoreResults ha restituito SQL_PARAM_DATA_AVAILABLE, ma è stato chiamato SQLGetData, anziché SQLParamData.
HY013 Errore di gestione della memoria Non è stato possibile 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 di stringa o buffer non valida (DM) Il valore specificato per l'argomento BufferLength è minore di 0.

Il valore specificato per l'argomento BufferLength è minore di 4, l'argomento Col_or_Param_Num è stato impostato su 0 e il driver è 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 era stata eliminata o che non è stato possibile recuperare.

Il cursore è un cursore forward-only e le dimensioni del set di righe sono maggiori di uno.
HY117 La connessione è stata sospesa a causa di uno stato di transazione sconosciuto. Sono consentite solo le funzioni di disconnessione 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 SQL_GD_BLOCK maschera di bit 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 SQL dati della colonna corrispondente. Questo errore si applica solo quando il SQL dati della colonna è stato mappato a un tipo di dati SQL driver.

Il driver supporta solo ODBC 2 .x e l'argomento TargetType è uno dei seguenti:

SQL_C_NUMERIC SQL_C_SBIGINT SQL_C_UBIGINT

e qualsiasi tipo di dati interval C elencato 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 Timeout della connessione scaduto Il periodo di timeout della connessione è scaduto prima che l'origine dati risponde 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 per essere restituiti 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 questo è soggetto 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 di 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; ciò significa che i dati devono essere recuperati in ordine crescente di numeri di colonna. Infine, se non sono supportate estensioni, non è possibile chiamare SQLGetData se le dimensioni del set di righe sono maggiori di 1.

I driver possono applicare una qualsiasi di queste restrizioni. Per determinare le restrizioni di un driver, un'applicazione chiama SQLGetInfo con una delle opzioni 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 precedenti all'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 infoType SQL_GETDATA_EXTENSIONS, il driver supporta le chiamate a SQLGetData quando le dimensioni del set di righe sono maggiori 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 le colonne non associate.

Esistono due eccezioni a queste restrizioni e la possibilità di un driver di allentarle. In primo luogo, SQLGetData non deve mai essere chiamato per un cursore forward-only quando le dimensioni del set di righe sono maggiori di 1. In secondo piano, 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 utilizza 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 viene mappato da Gestione driver ODBC 3 .x a SQLExtendedFetch con fetchOrientation di SQL_FETCH_NEXT e SQLGetData con un Col_or_Param_Num pari a 0 viene mappato da ODBC 3 .x Driver Manager a SQLGetStmt Opzione con fOption 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 riposizionare il cursore su tale riga.

Se l'argomento TargetType è un tipo di dati interval, per i dati vengono usati rispettivamente la precisione iniziale dell'intervallo predefinito (2) e la precisione predefinita dei secondi dell'intervallo (6), come impostato nei campi SQL_DESC_DATETIME_INTERVAL_PRECISION e SQL_DESC_PRECISION dell'ARD. Se l'argomento TargetType è un tipo di dati SQL_C_NUMERIC, per i dati vengono usati la precisione predefinita (definita dal driver) e la scala predefinita (0), come impostato nei campi SQL_DESC_PRECISION e SQL_DESC_SCALE dell'ARD. Se la precisione o la scala predefinita non è appropriata, l'applicazione deve impostare in modo esplicito il campo del 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 esegue i mapping appropriati, se necessario, in base alla versione dell'applicazione e del driver.

Recupero di Variable-Length dati in parti

SQLGetData può essere usato per recuperare dati da una colonna che contiene dati a lunghezza variabile in parti, ad esempio 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 di lunghezza variabile.

Per recuperare dati da una colonna in parti, l'applicazione chiama SQLGetData più volte in successione per la stessa colonna. A ogni chiamata, SQLGetData restituisce la parte successiva dei dati. L'applicazione deve riassemblare le parti, facendo attenzione a rimuovere il carattere di terminazione Null dalle 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. Né SQL_NO_TOTAL né zero possono essere restituiti nell'ultima chiamata valida per recuperare dati da una colonna, perché l'applicazione non avrebbe alcun modo di conoscere la quantità di dati nel buffer dell'applicazione valida. Se SQLGetData viene chiamato dopo questa operazione, 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 in 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).

Non è possibile usare SQLGetData 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 successive alla prima.

Recupero di parametri di output trasmessi

Se un driver supporta parametri di output trasmessi in streaming, un'applicazione può chiamare PIÙ volte SQLGetData con un buffer di piccole dimensioni per recuperare un valore di parametro di grandi dimensioni. Per altre informazioni sui parametri di output trasmessi, vedere Recupero di parametri di output tramite SQLGetData.

Recupero di dati con SQLGetData

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

  1. Restituisce SQL_NO_DATA se sono già stati restituiti tutti i dati per la colonna.

  2. Imposta * StrLen_or_IndPtr su SQL_NULL_DATA se i dati sono NULL. Se i dati sono NULL StrLen_or_IndPtr un puntatore Null, SQLGetData restituisce SQLSTATE 22002 (variabile indicatore obbligatoria ma non fornita).

    Se i dati per la colonna non sono NULL, SQLGetData procede al passaggio 3.

  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 in SQL_ATTR_MAX_LENGTH byte.

    Nota

    L SQL_ATTR_MAX_LENGTH'attributo dell'istruzione è destinato a ridurre il traffico di rete. Viene in genere implementata dall'origine dati, che tronca i dati prima di restituirlo in rete. I driver e le origini dati non sono necessari per supportarlo. Pertanto, per garantire che i dati vengono troncati a una determinata dimensione, un'applicazione deve allocare un buffer di tale dimensione e specificare le dimensioni nell'argomento BufferLength.

  4. Converte i dati nel tipo specificato in TargetType. Ai dati viene data la precisione e la scala predefinite per il tipo di dati. Se TargetType è SQL_ARD_TYPE, viene usato il tipo di dati nel campo SQL_DESC_CONCISE_TYPE dell'ARD. Se TargetType è SQL_ARD_TYPE, ai dati viene data la precisione e la scala nei campi SQL_DESC_DATETIME_INTERVAL_PRECISION, SQL_DESC_PRECISION e SQL_DESC_SCALE dell'ARD, a seconda del tipo di dati nel campo SQL_DESC_CONCISE_TYPE. Se la precisione o la scala predefinita non è appropriata, l'applicazione deve impostare in modo esplicito il campo del descrittore appropriato tramite una chiamata a SQLSetDescField o SQLSetDescRec.

  5. 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 a BufferLength meno la lunghezza di un carattere di terminazione Null. I dati vengono quindi terminati con null. Se la lunghezza dei dati binari supera la lunghezza del buffer di dati, SQLGetData lo tronca in byte BufferLength.

    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; presuppone sempre che la lunghezza di *TargetValuePtr sia la dimensione del tipo di dati.

  6. Inserisce i dati convertiti (ed eventualmente troncati) in * TargetValuePtr. Si noti che SQLGetData non può restituire dati non in linea.

  7. Inserisce 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 è in grado di determinare la lunghezza dei dati dopo la conversione, come in alcuni casi con i dati lunghi, restituisce SQL_SUCCESS_WITH_INFO e imposta la lunghezza su SQL_NO_TOTAL. L'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 dell'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. in altre informazioni, la lunghezza diminuisce a ogni chiamata successiva.

    • Per tutti gli altri tipi di dati, si tratta della lunghezza dei dati dopo la conversione. ovvero le dimensioni del tipo in cui sono stati convertiti i dati.

  8. Se i dati vengono troncati senza perdita di significatività 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 i campi del descrittore.

Se TargetType è SQL_ARD_TYPE, viene usato il tipo di dati nel campo SQL_DESC_CONCISE_TYPE dell'ARD. Se TargetType è SQL_ARD_TYPE o SQL_C_DEFAULT, ai dati viene data la precisione e la scala nei campi SQL_DESC_DATETIME_INTERVAL_PRECISION, SQL_DESC_PRECISION e SQL_DESC_SCALE di 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 di ID cliente, nomi e numeri di telefono ordinati in base a nome, ID e numero di telefono. Per ogni riga di dati, chiama SQLFetch per posizionare il cursore sulla riga successiva. Chiama SQLGetData per recuperare i dati recuperati. I buffer per i dati e il numero di byte restituiti 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 non correlate alla posizione del cursore a blocchi Sqlbulkoperations
Annullamento dell'elaborazione dell'istruzione 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

Vedere anche

Informazioni di riferimento sulle API ODBC
File di intestazione ODBC
Recupero di parametri di output tramite SQLGetData