Recupero di una riga di dati
Per recuperare una riga di dati, un'applicazione chiama SQLFetch. SQLFetch può essere chiamato con qualsiasi tipo di cursore, ma sposta solo il cursore del set di righe in una direzione forward-only. SQLFetch sposta il cursore alla riga successiva e restituisce i dati per tutte le colonne associate con chiamate a SQLBindCol. Quando il cursore raggiunge la fine del set di risultati, SQLFetch restituisce SQL_NO_DATA. Per esempi di chiamata a SQLFetch, vedere Uso di SQLBindCol.
Il modo esatto in cui SQLFetch viene implementato è specifico del driver, ma il criterio generale prevede che il driver recuperi i dati di tutte le colonne associate dall'origine dati, li converta in base ai tipi delle variabili associate e inserisca i dati convertiti in tali variabili. Se il driver non è in grado di convertire dati, SQLFetch restituisce un errore. L'applicazione può continuare a recuperare righe, ma i dati per la riga corrente vengono persi. Ciò che accade ai dati per le colonne non associate dipende dal driver, ma la maggior parte dei driver li recupera e li ignora o non li recupera affatto.
Il driver imposta anche i valori di eventuali buffer di lunghezza/indicatore associati. Se il valore di dati per una colonna è NULL, il driver imposta il buffer di lunghezza/indicatore corrispondente su SQL_NULL_DATA. Se il valore dei dati non è NULL, il driver imposta il buffer di lunghezza/indicatore sulla lunghezza dei byte dei dati dopo la conversione. Se questa lunghezza non può essere determinata, come accade talvolta con dati lunghi recuperati da più chiamate di funzione, il driver imposta il buffer di lunghezza/indicatore su SQL_NO_TOTAL. Per i tipi di dati a lunghezza fissa, ad esempio numeri interi e strutture di data, la lunghezza dei byte è la dimensione del tipo di dati.
Per i dati a lunghezza variabile, ad esempio dati di tipo carattere e binario, il driver controlla la lunghezza in byte dei dati convertiti rispetto alla lunghezza in byte del buffer associato alla colonna; la lunghezza del buffer viene specificata nell'argomento BufferLength in SQLBindCol. Se la lunghezza in byte dei dati convertiti è superiore alla lunghezza in byte del buffer, il driver tronca i dati per adattarli al buffer, restituisce la lunghezza non troncata nel buffer di lunghezza/indicatore, restituisce SQL_SUCCESS_WITH_INFO e inserisce SQLSTATE 01004 (dati troncati) nella diagnostica. L'unica eccezione è se un segnalibro a lunghezza variabile viene troncato quando viene restituito da SQLFetch, che restituisce SQLSTATE 22001 (dati stringa troncati a destra).
I dati a lunghezza fissa non vengono mai troncati, perché il driver presuppone che le dimensioni del buffer associato siano le dimensioni del tipo di dati. Il troncamento dei dati tende a essere raro, perché l'applicazione associa in genere un buffer sufficientemente grande da contenere l'intero valore dei dati; determina le dimensioni necessarie dai metadati. Tuttavia, l'applicazione potrebbe associare in modo esplicito un buffer che sa essere troppo piccolo. Ad esempio, potrebbe recuperare e visualizzare i primi 20 caratteri di una descrizione della parte o i primi 100 caratteri di una colonna di testo lunga.
I dati di tipo carattere devono essere terminati con null dal driver prima che vengano restituiti all'applicazione, anche se sono stati troncati. Il carattere di terminazione Null non è incluso nella lunghezza dei byte restituiti, ma richiede spazio nel buffer associato. Ad esempio, supponiamo che un'applicazione utilizzi stringhe composte da dati di caratteri del gruppo di caratteri ASCII, che il driver abbia 50 caratteri di dati da restituire e che il buffer dell'applicazione sia lungo 25 byte. Nel buffer dell'applicazione, il driver restituisce i primi 24 caratteri seguiti da un carattere di terminazione Null. Nel buffer di lunghezza/indicatore restituisce una lunghezza pari a 50 byte.
L'applicazione può limitare il numero di righe nel set di risultati impostando l'attributo dell'istruzione SQL_ATTR_MAX_ROWS prima di eseguire l'istruzione che crea il set di risultati. Ad esempio, la modalità di anteprima in un'applicazione usata per formattare i report richiede solo dati sufficienti per visualizzare la prima pagina del report. Limitando le dimensioni del set di risultati, tale funzionalità verrebbe eseguita più velocemente. Questo attributo di istruzione è progettato per ridurre il traffico di rete e potrebbe non essere supportato da tutti i driver.