Funzione SQLFetchScroll
Conformità
Versione introdotta: Conformità agli standard ODBC 3.0: ISO 92
Riepilogo
SQLFetchScroll recupera il set di righe di dati specificato dal set di risultati e restituisce i dati per tutte le colonne associate. I set di righe possono essere specificati in una posizione assoluta o relativa o tramite segnalibro.
Quando si usa un driver ODBC 2.x, Gestione driver esegue il mapping di questa funzione a SQLExtendedFetch. Per altre informazioni, vedere Mapping di funzioni di sostituzione per la compatibilità con le versioni precedenti delle applicazioni.
Sintassi
SQLRETURN SQLFetchScroll(
SQLHSTMT StatementHandle,
SQLSMALLINT FetchOrientation,
SQLLEN FetchOffset);
Argomenti
StatementHandle
[Input] Handle di istruzione.
FetchOrientation
[Input]
Tipo di recupero:
SQL_FETCH_NEXT
SQL_FETCH_PRIOR
SQL_FETCH_FIRST
SQL_FETCH_LAST
SQL_FETCH_ABSOLUTE
SQL_FETCH_RELATIVE
SQL_FETCH_BOOKMARK
Per altre informazioni, vedere "Posizionamento del cursore" nella sezione "Commenti".
FetchOffset
[Input]
Numero della riga da recuperare. L'interpretazione di questo argomento dipende dal valore dell'argomento FetchOrientation . Per altre informazioni, vedere "Posizionamento del cursore" nella sezione "Commenti".
Valori restituiti
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR o SQL_INVALID_HANDLE.
Diagnostica
Quando SQLFetchScroll 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 SQLFetchScroll 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. Se si verifica un errore in una singola colonna, è possibile chiamare SQLGetDiagField con un DiagIdentifier di SQL_DIAG_COLUMN_NUMBER per determinare la colonna in cui si è verificato l'errore e SQLGetDiagField può essere chiamato con un DiagIdentifier di SQL_DIAG_ROW_NUMBER per determinare la riga contenente tale colonna.
Per tutti gli SQLSTATEs che possono restituire SQL_SUCCESS_WITH_INFO o SQL_ERROR (ad eccezione di 01xxx SQLSTATEs), SQL_SUCCESS_WITH_INFO viene restituito se si verifica un errore in una o più righe, ma non tutte, righe di un'operazione multirow e SQL_ERROR viene restituito se si verifica un errore in un'operazione a riga singola.
| 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 una colonna hanno comportato il troncamento di dati binari non null o non NULL. Se si tratta di un valore stringa, è stato troncato a destra. |
| 01S01 | Errore nella riga | Errore durante il recupero di una o più righe. Se questo SQLSTATE viene restituito quando un'applicazione ODBC 3*.x* utilizza un driver ODBC 2*.x*, può essere ignorata. |
| 01S06 | Tentativo di recupero prima che il set di risultati restituisca il primo set di righe | Il set di righe richiesto si sovrapponeva all'inizio del set di risultati quando FetchOrientation era SQL_FETCH_PRIOR, la posizione corrente superava la prima riga e il numero della riga corrente è minore o uguale alla dimensione del set di righe. Il set di righe richiesto si sovrapponeva all'inizio del set di risultati quando FetchOrientation era SQL_FETCH_PRIOR, la posizione corrente superava la fine del set di risultati e le dimensioni del set di righe erano maggiori delle dimensioni del set di risultati. Il set di righe richiesto si sovrapponeva all'inizio del set di risultati quando FetchOrientation era SQL_FETCH_RELATIVE, FetchOffset era negativo e il valore assoluto di FetchOffset era minore o uguale alla dimensione del set di righe. Il set di righe richiesto si sovrapponeva all'inizio del set di risultati quando FetchOrientation era SQL_FETCH_ABSOLUTE, FetchOffset era negativo e il valore assoluto di FetchOffset era maggiore delle dimensioni del set di risultati ma minore o uguale alle dimensioni del set di righe. (La funzione restituisce SQL_SUCCESS_WITH_INFO. |
| 01S07 | Troncamento frazionario | I dati restituiti per una colonna 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 | Impossibile convertire il valore di dati di una colonna nel set di risultati nel tipo di dati specificato da TargetType in SQLBindCol. La colonna 0 è stata associata a un tipo di dati di SQL_C_BOOKMARK e l'attributo dell'istruzione SQL_ATTR_USE_BOOKMARKS è stato impostato su SQL_UB_VARIABLE. La colonna 0 è stata associata a un tipo di dati di SQL_C_VARBOOKMARK e l'attributo dell'istruzione SQL_ATTR_USE_BOOKMARKS non è stato impostato su SQL_UB_VARIABLE. |
| 07009 | Indice descrittore non valido | Il driver era un driver ODBC 2*.x* che non supporta SQLExtendedFetch e un numero di colonna specificato nell'associazione per una colonna era 0. La colonna 0 è stata associata e l'attributo dell'istruzione SQL_ATTR_USE_BOOKMARKS è stato impostato su SQL_UB_OFF. |
| 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, troncati a destra | Un segnalibro a lunghezza variabile restituito per una colonna è stato troncato. |
| 22002 | Variabile indicatore obbligatoria ma non fornita | I dati NULL sono stati recuperati in una colonna il cui StrLen_or_IndPtr impostato da SQLBindCol (o SQL_DESC_INDICATOR_PTR impostato da SQLSetDescField o SQLSetDescRec) era un puntatore Null. |
| 22003 | Valore numerico non compreso nell'intervallo | La restituzione del valore numerico (come numerico o stringa) per una o più colonne associate avrebbe causato il troncamento dell'intera parte (anziché frazionaria) del numero. Per altre informazioni, vedere Conversione di dati da SQL a tipi di dati C nell'Appendice D: Tipi di dati. |
| 22007 | Formato datetime non valido | Una colonna di caratteri nel set di risultati è stata associata a una struttura data, ora o timestamp C e un valore nella colonna era, rispettivamente, una data, un'ora o un timestamp non valido. |
| 22012 | Divisione per zero | È stato restituito un valore di un'espressione aritmetica, che ha determinato 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 recuperano dati a un tipo C di 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 associata 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 | StatementHandle era in uno stato eseguito, ma nessun set di risultati era associato a StatementHandle. |
| 40001 | Errore di serializzazione | La transazione in cui è stato eseguito il recupero è stata terminata per impedire il deadlock. |
| 40003 | Completamento istruzione sconosciuto | La connessione associata non è riuscita durante l'esecuzione di questa funzione e non è possibile determinare lo stato della transazione. |
| 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. |
| HY010 | Errore della sequenza di funzioni | (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 SQLFetchScroll . (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) StatementHandle specificato non era in uno stato eseguito. La funzione è stata chiamata senza prima chiamare SQLExecDirect, SQLExecute o una funzione del catalogo. (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) SQLFetch è stato chiamato per StatementHandle dopo la chiamata a SQLExtendedFetch e prima della chiamata di SQLFreeStmt con l'opzione SQL_CLOSE. |
| 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 | L'attributo dell'istruzione SQL_ATTR_USE_BOOKMARK è stato impostato su SQL_UB_VARIABLE e la colonna 0 è stata associata a un buffer la cui lunghezza non è uguale alla lunghezza massima per il segnalibro per questo set di risultati. Questa lunghezza è disponibile nel campo SQL_DESC_OCTET_LENGTH di IRD e può essere ottenuta chiamando SQLDescribeCol, SQLColAttribute o SQLGetDescField. |
| HY106 | Recupero del tipo non compreso nell'intervallo | DM) Il valore specificato per l'argomento FetchOrientation non è valido. (DM) L'argomento FetchOrientation è stato SQL_FETCH_BOOKMARK e l'attributo dell'istruzione SQL_ATTR_USE_BOOKMARKS è stato impostato su SQL_UB_OFF. Il valore dell'attributo dell'istruzione SQL_ATTR_CURSOR_TYPE è stato SQL_CURSOR_FORWARD_ONLY e il valore dell'argomento FetchOrientation non è stato SQL_FETCH_NEXT. Il valore dell'attributo dell'istruzione SQL_ATTR_CURSOR_SCROLLABLE è stato SQL_NONSCROLLABLE e il valore dell'argomento FetchOrientation non è stato SQL_FETCH_NEXT. |
| HY107 | Valore di riga non compreso nell'intervallo | Il valore specificato con l'attributo di istruzione SQL_ATTR_CURSOR_TYPE è stato SQL_CURSOR_KEYSET_DRIVEN, ma il valore specificato con l'attributo di istruzione SQL_ATTR_KEYSET_SIZE è maggiore di 0 e minore del valore specificato con l'attributo di istruzione SQL_ATTR_ROW_ARRAY_SIZE. |
| HY111 | Valore segnalibro non valido | L'argomento FetchOrientation è stato SQL_FETCH_BOOKMARK e il segnalibro a cui punta il valore nell'attributo dell'istruzione SQL_ATTR_FETCH_BOOKMARK_PTR non era valido o era un puntatore Null. |
| 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 la conversione specificata dalla combinazione di TargetType in SQLBindCol e il tipo di dati SQL della colonna corrispondente. |
| HYT00 | Timeout scaduto | Periodo di timeout della query scaduto prima che l'origine dati restituisca il set di risultati richiesto. Il periodo di timeout viene impostato tramite SQLSetStmtAttr, SQL_ATTR_QUERY_TIMEOUT. |
| 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. |
Commenti
SQLFetchScroll restituisce un set di righe specificato dal set di risultati. I set di righe possono essere specificati dalla posizione assoluta o relativa o dal segnalibro. SQLFetchScroll può essere chiamato solo quando esiste un set di risultati, ovvero dopo una chiamata che crea un set di risultati e prima che il cursore su tale set di risultati venga chiuso. Se sono associate colonne, restituisce i dati in tali colonne. Se l'applicazione ha specificato un puntatore a una matrice di stato di riga o a un buffer in cui restituire il numero di righe recuperate, SQLFetchScroll restituisce anche queste informazioni. Le chiamate a SQLFetchScroll possono essere combinate con chiamate a SQLFetch , ma non possono essere combinate con le chiamate a SQLExtendedFetch.
Per altre informazioni, vedere Uso di cursori a blocchi e Uso di cursori scorrevoli.
Posizionamento del cursore
Quando viene creato il set di risultati, il cursore viene posizionato prima dell'inizio del set di risultati. SQLFetchScroll posiziona il cursore del blocco in base ai valori degli argomenti FetchOrientation e FetchOffset , come illustrato nella tabella seguente. Le regole esatte per determinare l'inizio del nuovo set di righe vengono visualizzate nella sezione successiva.
| FetchOrientation | significato |
|---|---|
| SQL_FETCH_NEXT | Restituisce il set di righe successivo. Equivale a chiamare SQLFetch. SQLFetchScroll ignora il valore di FetchOffset. |
| SQL_FETCH_PRIOR | Restituisce il set di righe precedente. SQLFetchScroll ignora il valore di FetchOffset. |
| SQL_FETCH_RELATIVE | Restituisce il set di righe FetchOffset dall'inizio del set di righe corrente. |
| SQL_FETCH_ABSOLUTE | Restituisce il set di righe a partire dalla riga FetchOffset. |
| SQL_FETCH_FIRST | Restituisce il primo set di righe nel set di risultati. SQLFetchScroll ignora il valore di FetchOffset. |
| SQL_FETCH_LAST | Restituisce l'ultimo set di righe completo nel set di risultati. SQLFetchScroll ignora il valore di FetchOffset. |
| SQL_FETCH_BOOKMARK | Restituisce il set di righe FetchOffset righe dal segnalibro specificato dall'attributo dell'istruzione SQL_ATTR_FETCH_BOOKMARK_PTR. |
I driver non sono necessari per supportare tutti gli orientamenti di recupero; Un'applicazione chiama SQLGetInfo con un tipo di informazioni di SQL_DYNAMIC_CURSOR_ATTRIBUTES1, SQL_KEYSET_CURSOR_ATTRIBUTES1 o SQL_STATIC_CURSOR_ATTRIBUTES1 (a seconda del tipo di cursore) per determinare quali orientamenti di recupero sono supportati dal driver. L'applicazione deve esaminare i SQL_CA1_NEXT, SQL_CA1_RELATIVE, SQL_CA1_ABSOLUTE e WQL_CA1_BOOKMARK maschera di bit in questi tipi di informazioni. Inoltre, se il cursore è forward-only e FetchOrientation non è SQL_FETCH_NEXT, SQLFetchScroll restituisce SQLSTATE HY106 (tipo di recupero non compreso nell'intervallo).
L'attributo dell'istruzione SQL_ATTR_ROW_ARRAY_SIZE specifica il numero di righe nel set di righe. Se il set di righe recuperato da SQLFetchScroll si sovrappone alla fine del set di risultati, SQLFetchScroll restituisce un set di righe parziale. Ovvero, se S + R - 1 è maggiore di L, dove S è la riga iniziale del set di righe recuperato, R è la dimensione del set di righe e L è l'ultima riga nel set di risultati, quindi solo la prima L - S + 1 righe del set di righe sono valide. Le righe rimanenti sono vuote e hanno uno stato di SQL_ROW_NOROW.
Dopo la restituzione di SQLFetchScroll , la riga corrente è la prima riga del set di righe.
Regole di posizionamento del cursore
Le sezioni seguenti descrivono le regole esatte per ogni valore di FetchOrientation. Queste regole usano la notazione seguente.
| Notazione | Significato |
|---|---|
| Prima di iniziare | Il cursore del blocco viene posizionato prima dell'inizio del set di risultati. Se la prima riga del nuovo set di righe è prima dell'inizio del set di risultati, SQLFetchScroll restituisce SQL_NO_DATA. |
| Dopo la fine | Il cursore del blocco viene posizionato dopo la fine del set di risultati. Se la prima riga del nuovo set di righe è successiva alla fine del set di risultati, SQLFetchScroll restituisce SQL_NO_DATA. |
| CurrRowsetStart | Numero della prima riga nel set di righe corrente. |
| LastResultRow | Numero dell'ultima riga nel set di risultati. |
| RowsetSize | Dimensioni del set di righe. |
| FetchOffset | Valore dell'argomento FetchOffset . |
| BookmarkRow | Riga corrispondente al segnalibro specificato dall'attributo dell'istruzione SQL_ATTR_FETCH_BOOKMARK_PTR. |
SQL_FETCH_NEXT
Si applicano le regole seguenti.
| Condizione | Prima riga del nuovo set di righe |
|---|---|
| Prima di iniziare | 1 |
| CurrRowsetStart + RowsetSize[1] <= LastResultRow | CurrRowsetStart + RowsetSize[1] |
| CurrRowsetStart + RowsetSize[1]> LastResultRow | Dopo la fine |
| Dopo la fine | Dopo la fine |
[1] Se le dimensioni del set di righe sono state modificate dopo la chiamata precedente per recuperare righe, si tratta delle dimensioni del set di righe usate con la chiamata precedente.
SQL_FETCH_PRIOR
Si applicano le regole seguenti.
| Condizione | Prima riga del nuovo set di righe |
|---|---|
| Prima di iniziare | Prima di iniziare |
| CurrRowsetStart = 1 | Prima di iniziare |
| 1 < CurrRowsetStart <= RowsetSize [2] | 1 [1] |
| CurrRowsetStart > RowsetSize [2] | CurrRowsetStart - RowsetSize [2] |
| After end AND LastResultRow < RowsetSize [2] | 1 [1] |
| After end AND LastResultRow >= RowsetSize [2] | LastResultRow - RowsetSize + 1 [2] |
[1] SQLFetchScroll restituisce SQLSTATE 01S06 (Tentativo di recupero prima del set di risultati restituito il primo set di righe) e SQL_SUCCESS_WITH_INFO.
[2] Se le dimensioni del set di righe sono state modificate dopo la chiamata precedente per recuperare le righe, si tratta della nuova dimensione del set di righe.
SQL_FETCH_RELATIVE
Si applicano le regole seguenti.
| Condizione | Prima riga del nuovo set di righe |
|---|---|
| (Prima di avviare AND FetchOffset > 0) OR (after end AND FetchOffset < 0) | --[1] |
| BeforeStart AND FetchOffset <= 0 | Prima di iniziare |
| CurrRowsetStart = 1 AND FetchOffset < 0 | Prima di iniziare |
| CurrRowsetStart > 1 AND CurrRowsetStart + FetchOffset < 1 AND | FetchOffset | > RowsetSize [3] | Prima di iniziare |
| CurrRowsetStart > 1 AND CurrRowsetStart + FetchOffset < 1 AND | FetchOffset | <= RowsetSize [3] | 1 [2] |
| 1 <= CurrRowsetStart + FetchOffset <= LastResultRow | CurrRowsetStart + FetchOffset |
| CurrRowsetStart + FetchOffset > LastResultRow | Dopo la fine |
| After end AND FetchOffset >= 0 | Dopo la fine |
[1] SQLFetchScroll restituisce lo stesso set di righe come se fosse stato chiamato con FetchOrientation impostato su SQL_FETCH_ABSOLUTE. Per altre informazioni, vedere la sezione "SQL_FETCH_ABSOLUTE".
[2] SQLFetchScroll restituisce SQLSTATE 01S06 (Tentativo di recupero prima del set di risultati restituito il primo set di righe) e SQL_SUCCESS_WITH_INFO.
[3] Se le dimensioni del set di righe sono state modificate dopo la chiamata precedente per recuperare le righe, si tratta della nuova dimensione del set di righe.
SQL_FETCH_ABSOLUTE
Si applicano le regole seguenti.
| Condizione | Prima riga del nuovo set di righe |
|---|---|
| FetchOffset < 0 AND | FetchOffset | <= LastResultRow | LastResultRow + FetchOffset + 1 |
| FetchOffset < 0 AND | FetchOffset | > LastResultRow AND | FetchOffset | > RowsetSize [2] | Prima di iniziare |
| FetchOffset < 0 AND | FetchOffset | > LastResultRow AND | FetchOffset | <= RowsetSize [2] | 1 [1] |
| FetchOffset = 0 | Prima di iniziare |
| 1 <= FetchOffset <= LastResultRow | FetchOffset |
| FetchOffset > LastResultRow | Dopo la fine |
[1] SQLFetchScroll restituisce SQLSTATE 01S06 (Tentativo di recupero prima del set di risultati restituito il primo set di righe) e SQL_SUCCESS_WITH_INFO.
[2] Se le dimensioni del set di righe sono state modificate dopo la chiamata precedente per recuperare le righe, si tratta della nuova dimensione del set di righe.
Un recupero assoluto eseguito su un cursore dinamico non può fornire il risultato richiesto perché le posizioni di riga in un cursore dinamico non sono determini. Tale operazione equivale a un recupero prima seguito da un recupero relativo; non è un'operazione atomica, come è un recupero assoluto su un cursore statico.
SQL_FETCH_FIRST
Si applicano le regole seguenti.
| Condizione | Prima riga del nuovo set di righe |
|---|---|
| Any | 1 |
SQL_FETCH_LAST
Si applicano le regole seguenti.
| Condizione | Prima riga del nuovo set di righe |
|---|---|
| RowsetSize [1]<= LastResultRow | LastResultRow - RowsetSize + 1 [1] |
| RowsetSize [1]> LastResultRow | 1 |
[1] Se le dimensioni del set di righe sono state modificate dopo la chiamata precedente per recuperare le righe, si tratta della nuova dimensione del set di righe.
SQL_FETCH_BOOKMARK
Si applicano le regole seguenti.
| Condizione | Prima riga del nuovo set di righe |
|---|---|
| BookmarkRow + FetchOffset < 1 | Prima di iniziare |
| 1 <= BookmarkRow + FetchOffset <= LastResultRow | BookmarkRow + FetchOffset |
| BookmarkRow + FetchOffset > LastResultRow | Dopo la fine |
Per informazioni sui segnalibri, vedere Segnalibri (ODBC).
Effetto delle righe eliminate, aggiunte ed errori sullo spostamento del cursore
I cursori statici e basati su keyset talvolta rilevano righe aggiunte al set di risultati e rimuovono le righe eliminate dal set di risultati. Chiamando SQLGetInfo con le opzioni di SQL_STATIC_CURSOR_ATTRIBUTES2 e SQL_KEYSET_CURSOR_ATTRIBUTES2 e esaminando le SQL_CA2_SENSITIVITY_ADDITIONS, le SQL_CA2_SENSITIVITY_DELETIONS e le SQL_CA2_SENSITIVITY_UPDATES maschera di bit, un'applicazione determina se i cursori implementati da un determinato driver eseguono questa operazione. Per i driver che possono rilevare le righe eliminate e rimuoverle, i paragrafi seguenti descrivono gli effetti di questo comportamento. Per i driver che possono rilevare righe eliminate ma non possono rimuoverle, le eliminazioni non hanno alcun effetto sui movimenti del cursore e i paragrafi seguenti non si applicano.
Se il cursore rileva righe aggiunte al set di risultati o rimuove le righe eliminate dal set di risultati, viene visualizzato come se rilevi queste modifiche solo quando recupera i dati. Ciò include il caso in cui SQLFetchScroll viene chiamato con FetchOrientation impostato su SQL_FETCH_RELATIVE e FetchOffset impostato su 0 per rifetch dello stesso set di righe, ma non include il caso in cui SQLSetPos viene chiamato con fOption impostato su SQL_REFRESH. In quest'ultimo caso, i dati nei buffer del set di righe vengono aggiornati, ma non recuperati e le righe eliminate non vengono rimosse dal set di risultati. Pertanto, quando una riga viene eliminata o inserita nel set di righe corrente, il cursore non modifica i buffer del set di righe. Rileva invece la modifica quando recupera qualsiasi set di righe che in precedenza includeva la riga eliminata o ora include la riga inserita.
Ad esempio:
// Fetch the next rowset.
SQLFetchScroll(hstmt, SQL_FETCH_NEXT, 0);
// Delete third row of the rowset. Does not modify the rowset buffers.
SQLSetPos(hstmt, 3, SQL_DELETE, SQL_LOCK_NO_CHANGE);
// The third row has a status of SQL_ROW_DELETED after this call.
SQLSetPos(hstmt, 3, SQL_REFRESH, SQL_LOCK_NO_CHANGE);
// Refetch the same rowset. The third row is removed, replaced by what
// was previously the fourth row.
SQLFetchScroll(hstmt, SQL_FETCH_RELATIVE, 0);
Quando SQLFetchScroll restituisce un nuovo set di righe con una posizione relativa al set di righe corrente, ovvero FetchOrientation è SQL_FETCH_NEXT, SQL_FETCH_PRIOR o SQL_FETCH_RELATIVE, non include modifiche al set di righe corrente durante il calcolo della posizione iniziale del nuovo set di righe. Tuttavia, include modifiche esterne al set di righe corrente, se è in grado di rilevarle. Inoltre, quando SQLFetchScroll restituisce un nuovo set di righe con una posizione indipendente dal set di righe corrente, ovvero FetchOrientation è SQL_FETCH_FIRST, SQL_FETCH_LAST, SQL_FETCH_ABSOLUTE o SQL_FETCH_BOOKMARK, include tutte le modifiche che è in grado di rilevare, anche se si trovano nel set di righe corrente.
Quando si determina se le righe appena aggiunte si trovano all'interno o all'esterno del set di righe corrente, un set di righe parziale viene considerato finale all'ultima riga valida; ovvero l'ultima riga per cui lo stato della riga non è SQL_ROW_NOROW. Si supponga, ad esempio, che il cursore sia in grado di rilevare le righe appena aggiunte, che il set di righe corrente sia un set di righe parziale, che l'applicazione aggiunge nuove righe e il cursore aggiunge queste righe alla fine del set di risultati. Se l'applicazione chiama SQLFetchScroll con FetchOrientation impostato su SQL_FETCH_NEXT, SQLFetchScroll restituisce il set di righe a partire dalla prima riga appena aggiunta.
Si supponga, ad esempio, che il set di righe corrente sia costituito da righe da 21 a 30, che la dimensione del set di righe sia 10, che il cursore rimuove le righe eliminate dal set di risultati e che il cursore rilevi le righe aggiunte al set di risultati. La tabella seguente illustra le righe restituite da SQLFetchScroll in varie situazioni.
| Modifica | Tipo di recupero | FetchOffset | Nuovo set di righe[1] |
|---|---|---|---|
| Eliminare la riga 21 | NEXT | 0 | Da 31 a 40 |
| Eliminare la riga 31 | NEXT | 0 | Da 32 a 41 |
| Inserire una riga tra le righe 21 e 22 | NEXT | 0 | Da 31 a 40 |
| Inserire una riga tra le righe 30 e 31 | NEXT | 0 | Riga inserita, da 31 a 39 |
| Eliminare la riga 21 | PRIOR | 0 | Da 11 a 20 |
| Elimina riga 20 | PRIOR | 0 | Da 10 a 19 |
| Inserire una riga tra le righe 21 e 22 | PRIOR | 0 | Da 11 a 20 |
| Inserire una riga tra le righe 20 e 21 | PRIOR | 0 | Da 12 a 20, riga inserita |
| Eliminare la riga 21 | RELATIVE | 0 | Da 22 a 31[2] |
| Eliminare la riga 21 | RELATIVE | 1 | Da 22 a 31 |
| Inserire una riga tra le righe 21 e 22 | RELATIVE | 0 | 21, riga inserita, da 22 a 29 |
| Inserire una riga tra le righe 21 e 22 | RELATIVE | 1 | Da 22 a 31 |
| Eliminare la riga 21 | ABSOLUTE | 21 | Da 22 a 31[2] |
| Eliminare la riga 22 | ABSOLUTE | 21 | Da 21 a 23 a 31 |
| Inserire una riga tra le righe 21 e 22 | ABSOLUTE | 22 | Riga inserita, da 22 a 29 |
[1] Questa colonna usa i numeri di riga prima dell'inserimento o dell'eliminazione delle righe.
[2] In questo caso, il cursore tenta di restituire righe a partire dalla riga 21. Poiché la riga 21 è stata eliminata, la prima riga restituita è la riga 22.
Le righe di errore (ovvero le righe con stato SQL_ROW_ERROR) non influiscono sullo spostamento del cursore. Ad esempio, se il set di righe corrente inizia con la riga 11 e lo stato della riga 11 è SQL_ROW_ERROR, chiamando SQLFetchScroll con FetchOrientation impostato su SQL_FETCH_RELATIVE e FetchOffset impostato su 5 restituisce il set di righe a partire dalla riga 16, esattamente come se lo stato della riga 11 fosse SQL_SUCCESS.
Restituzione di dati nelle colonne associate
SQLFetchScroll restituisce i dati in colonne associate nello stesso modo di SQLFetch. Per altre informazioni, vedere "Restituzione di dati in colonne associate" nella funzione SQLFetch.
Se non sono associate colonne, SQLFetchScroll non restituisce dati ma sposta il cursore del blocco nella posizione specificata. L'eventuale recupero dei dati da colonne non associate di un cursore a blocchi con SQLGetData dipende dal driver. Questa funzionalità è supportata se una chiamata a SQLGetInfo restituisce il bit di SQL_GD_BLOCK per il tipo di informazioni SQL_GETDATA_EXTENSIONS.
Indirizzi buffer
SQLFetchScroll usa la stessa formula per determinare l'indirizzo dei buffer di dati e lunghezza/indicatore come SQLFetch. Per altre informazioni, vedere "Indirizzi buffer" nella funzione SQLBindCol.
Matrice di stato riga
SQLFetchScroll imposta i valori nella matrice di stato della riga nello stesso modo di SQLFetch. Per altre informazioni, vedere "Row Status Array" nella funzione SQLFetch.
Buffer recuperato righe
SQLFetchScroll restituisce il numero di righe recuperate nel buffer recuperato nelle righe nello stesso modo di SQLFetch. Per altre informazioni, vedere "Rows Fetched Buffer" nella funzione SQLFetch.
Gestione errori
Quando un'applicazione chiama SQLFetchScroll in un driver ODBC 3.x, Gestione driver chiama SQLFetchScroll nel driver. Quando un'applicazione chiama SQLFetchScroll in un driver ODBC 2.x, Gestione driver chiama SQLExtendedFetch nel driver. Poiché SQLFetchScroll e SQLExtendedFetch gestiscono gli errori in modo leggermente diverso, l'applicazione rileva un comportamento di errore leggermente diverso quando chiama SQLFetchScroll nei driver ODBC 2.x e ODBC 3.x.
SQLFetchScroll restituisce errori e avvisi nello stesso modo di SQLFetch. Per altre informazioni, vedere "Gestione degli errori" in SQLFetch. SQLExtendedFetch restituisce errori nello stesso modo di SQLFetch, con le eccezioni seguenti:
Quando si verifica un avviso che si applica a una determinata riga nel set di righe, SQLExtendedFetch imposta la voce corrispondente nella matrice di stato della riga su SQL_ROW_SUCCESS, non SQL_ROW_SUCCESS_WITH_INFO.
Se si verificano errori in ogni riga del set di righe, SQLExtendedFetch restituisce SQL_SUCCESS_WITH_INFO, non SQL_ERROR.
In ogni gruppo di record di stato che si applica a una singola riga, il primo record di stato restituito da SQLExtendedFetch deve contenere SQLSTATE 01S01 (Errore nella riga); SQLFetchScroll non restituisce questo SQLSTATE. Se SQLExtendedFetch non è in grado di restituire sqlSTATEs aggiuntivi, deve comunque restituire questo SQLSTATE.
SQLFetchScroll e concorrenza ottimistica
Se un cursore usa la concorrenza ottimistica, ovvero l'attributo dell'istruzione SQL_ATTR_CONCURRENCY ha un valore SQL_CONCUR_VALUES o SQL_CONCUR_ROWVER - SQLFetchScroll aggiorna i valori di concorrenza ottimistica usati dall'origine dati per rilevare se una riga è stata modificata. Ciò si verifica ogni volta che SQLFetchScroll recupera un nuovo set di righe, incluso quando recupera il set di righe corrente. Viene chiamato con FetchOrientation impostato su SQL_FETCH_RELATIVE e FetchOffset impostato su 0.
Driver SQLFetchScroll e ODBC 2.x
Quando un'applicazione chiama SQLFetchScroll in un driver ODBC 2.x, Gestione driver esegue il mapping di questa chiamata a SQLExtendedFetch. Passa i valori seguenti per gli argomenti di SQLExtendedFetch.
| Argomento SQLExtendedFetch | Valore |
|---|---|
| StatementHandle | StatementHandle in SQLFetchScroll. |
| FetchOrientation | FetchOrientation in SQLFetchScroll. |
| FetchOffset | Se FetchOrientation non è SQL_FETCH_BOOKMARK, viene usato il valore dell'argomento FetchOffset in SQLFetchScroll . Se FetchOrientation è SQL_FETCH_BOOKMARK, viene utilizzato il valore archiviato nell'indirizzo specificato dall'attributo dell'istruzione SQL_ATTR_FETCH_BOOKMARK_PTR. |
| RowCountPtr | Indirizzo specificato dall'attributo dell'istruzione SQL_ATTR_ROWS_FETCHED_PTR. |
| RowStatusArray | Indirizzo specificato dall'attributo dell'istruzione SQL_ATTR_ROW_STATUS_PTR. |
Per altre informazioni, vedere Cursori rettangolari, cursori scorrevoli e compatibilità con le versioni precedenti nell'Appendice G: Linee guida del driver per la compatibilità con le versioni precedenti.
Descrittori e SQLFetchScroll
SQLFetchScroll interagisce con i descrittori nello stesso modo di SQLFetch. Per altre informazioni, vedere la sezione "Descrittori e SQLFetchScroll" in Funzione SQLFetch.
Esempio di codice
Vedere Binding a livello di colonna, binding a livello di riga, istruzioni di aggiornamento ed eliminazione posizionate e aggiornamento di righe nel set di righe con SQLSetPos.
Funzioni correlate
| Per informazioni su | Vedere |
|---|---|
| Associazione di un buffer a una colonna in un set di risultati | Funzione SQLBindCol |
| Esecuzione di operazioni di inserimento, aggiornamento o eliminazione bulk | Funzione SQLBulkOperations |
| Annullamento dell'elaborazione delle istruzioni | Funzione SQLCancel |
| Restituzione di informazioni su una colonna in un set di risultati | Funzione SQLDescribeCol |
| Esecuzione di un'istruzione SQL | Funzione SQLExecDirect |
| Esecuzione di un'istruzione SQL preparata | Funzione SQLExecute |
| Recupero di una singola riga o di un blocco di dati in una direzione forward-only | Funzione SQLFetch |
| Chiusura del cursore sull'istruzione | Funzione SQLFreeStmt |
| Restituzione del numero di colonne del set di risultati | Funzione SQLNumResultCols |
| Posizionamento del cursore, aggiornamento dei dati nel set di righe o aggiornamento o eliminazione di dati nel set di risultati | Funzione SQLSetPos |
| Impostazione di un attributo di istruzione | Funzione SQLSetStmtAttr |