SQLFetchScroll (libreria di cursori)
Importante
Questa funzionalità verrà rimossa nelle versioni future di Windows. Evitare di usare questa funzionalità nel nuovo lavoro di sviluppo e pianificare la modifica delle applicazioni che attualmente usano questa funzionalità. Microsoft consiglia di usare la funzionalità cursore del driver.
In questo argomento viene illustrato l'uso della funzione SQLFetchScroll nella libreria di cursori. Per informazioni generali su SQLFetchScroll, vedere Funzione SQLFetchScroll.
La libreria di cursori implementa SQLFetchScroll chiamando ripetutamente SQLFetch nel driver. Trasferisce i dati recuperati dal driver ai buffer del set di righe forniti dall'applicazione. Memorizza nella cache anche i dati nei file di memoria e disco. Quando un'applicazione richiede un nuovo set di righe, la libreria di cursori la recupera in base alle esigenze dal driver (se non è stata recuperata in precedenza) o dalla cache (se è stata recuperata in precedenza). Infine, la libreria di cursori mantiene lo stato dei dati memorizzati nella cache e restituisce queste informazioni all'applicazione nella matrice di stato della riga.
Quando viene usata la libreria di cursori, le chiamate a SQLFetchScroll non possono essere combinate con chiamate a SQLFetch o SQLExtendedFetch.
Quando si usa la libreria di cursori, le chiamate a SQLFetchScroll sono supportate entrambe per ODBC 2.x e per ODBC 3.x driver.
Buffer del set di righe
La libreria di cursori ottimizza il trasferimento dei dati dal driver al buffer del set di righe fornito dall'applicazione se:
L'applicazione usa l'associazione a livello di riga.
Non sono presenti byte inutilizzati tra i campi nella struttura che l'applicazione dichiara di contenere una riga di dati.
I campi in cui SQLFetch o SQLFetchScroll restituisce la lunghezza/indicatore per una colonna segue il buffer per tale colonna e precede il buffer per la colonna successiva. Questi campi sono facoltativi.
Quando l'applicazione richiede un nuovo set di righe, la libreria di cursori recupera i dati dalla cache e dal driver in base alle esigenze. Se i set di righe nuovi e vecchi si sovrappongono, la libreria di cursori può ottimizzare le prestazioni riutilizzando i dati delle sezioni sovrapposte dei buffer del set di righe. Pertanto, le modifiche non salvate ai buffer del set di righe vengono perse a meno che i set di righe nuovi e vecchi non si sovrappongano e le modifiche si trovino nelle sezioni sovrapposte dei buffer del set di righe. Per salvare le modifiche, un'applicazione invia un'istruzione update posizionata.
Si noti che la libreria di cursori aggiorna sempre i buffer del set di righe con i dati della cache quando un'applicazione chiama SQLFetchScroll con l'argomento FetchOrientation impostato su SQL_FETCH_RELATIVE e l'argomento FetchOffset impostato su 0.
La libreria di cursori supporta la chiamata a SQLSetStmtAttr con un attributo di SQL_ATTR_ROW_ARRAY_SIZE per modificare le dimensioni del set di righe mentre un cursore è aperto. La nuova dimensione del set di righe avrà effetto alla successiva chiamata di SQLFetchScroll .
Appartenenza al set di risultati
La libreria di cursori recupera i dati dal driver solo quando l'applicazione lo richiede. A seconda dell'origine dati e dell'impostazione dell'attributo dell'istruzione SQL_CONCURRENCY, le conseguenze sono le seguenti:
I dati recuperati dalla libreria di cursori potrebbero differire dai dati disponibili al momento dell'esecuzione dell'istruzione. Ad esempio, dopo l'apertura del cursore, le righe inserite in un punto oltre la posizione corrente del cursore possono essere recuperate da alcuni driver.
I dati nel set di risultati potrebbero essere bloccati dall'origine dati per la libreria di cursori e pertanto non sono disponibili per altri utenti.
Dopo che la libreria di cursori ha memorizzato nella cache una riga di dati, non è possibile rilevare le modifiche apportate a tale riga nell'origine dati sottostante (ad eccezione degli aggiornamenti posizionati e delle eliminazioni che operano nella cache dello stesso cursore). Ciò si verifica perché, per le chiamate a SQLFetchScroll, la libreria di cursori non recupera mai i dati dall'origine dati. Recupera invece i dati dalla cache.
Scorrimento in corso
La libreria di cursori supporta i tipi di recupero seguenti in SQLFetchScroll.
Tipo di cursore | Tipi di recupero |
---|---|
Forward-only | SQL_FETCH_NEXT |
Statico | SQL_FETCH_NEXT SQL_FETCH_PRIOR SQL_FETCH_FIRST SQL_FETCH_LAST SQL_FETCH_RELATIVE SQL_FETCH_ABSOLUTE SQL_FETCH_BOOKMARK |
Errori
Quando viene chiamato SQLFetchScroll e una delle chiamate a SQLFetch restituisce SQL_ERROR, la libreria di cursori procede come indicato di seguito. Al termine di questi passaggi, la libreria di cursori continua l'elaborazione.
Chiama SQLGetDiagRec per ottenere informazioni sull'errore dal driver e lo invia come record di diagnostica in Gestione driver.
Imposta il campo SQL_DIAG_ROW_NUMBER nel record di diagnostica sul valore appropriato.
Imposta il campo SQL_DIAG_COLUMN_NUMBER nel record di diagnostica sul valore appropriato, se applicabile; in caso contrario, lo imposta su 0.
Imposta il valore della riga in errore nella matrice di stato della riga su SQL_ROW_ERROR.
Dopo che la libreria di cursori ha chiamato SQLFetch più volte nell'implementazione di SQLFetchScroll, qualsiasi errore o avviso restituito da una delle chiamate a SQLFetch si troverà in un record di diagnostica e può essere recuperato da una chiamata a SQLGetDiagRec. Se i dati sono stati troncati al momento del recupero, i dati troncati si troveranno nella cache della libreria di cursori. Le chiamate successive a SQLFetchScroll per scorrere verso una riga con dati troncati restituiranno i dati troncati e non verrà generato alcun avviso perché i dati vengono recuperati dalla cache della libreria di cursori. Per tenere traccia della lunghezza dei dati restituiti in modo che possa determinare se i dati restituiti in un buffer sono stati troncati, un'applicazione deve associare il buffer di lunghezza/indicatore.
Operazioni segnalibro
La libreria di cursori supporta la chiamata a SQLFetchScroll con fetchOrientation di SQL_FETCH_BOOKMARK. Supporta anche la specifica di un offset nell'argomento FetchOffset che può essere usato nell'operazione di segnalibro. Questa è l'unica operazione segnalibro supportata dalla libreria di cursori. La libreria di cursori non supporta la chiamata a SQLBulkOperations.
Se l'applicazione ha impostato l'attributo di istruzione SQL_ATTR_USE_BOOKMARKS ed è associato alla colonna del segnalibro, la libreria di cursori genera un segnalibro a lunghezza fissa e la restituisce all'applicazione. La libreria di cursori crea e gestisce i segnalibri usati; non usa segnalibri mantenuti nell'origine dati. Quando viene chiamato SQLFetchScroll per recuperare un blocco di dati già recuperato dall'origine dati, recupera i dati dalla cache della libreria di cursori. Di conseguenza, il segnalibro usato in una chiamata a SQLFetchScroll con fetchOrientation di SQL_FETCH_BOOKMARK deve essere creato e gestito dalla libreria di cursori.
Interazione con altre funzioni
Un'applicazione deve chiamare SQLFetch o SQLFetchScroll prima di preparare o eseguire eventuali istruzioni di aggiornamento o eliminazione posizionate.