sp_cursorfetch (Transact-SQL)
Recupera un buffer di una o più righe dal database. Il gruppo di righe di questo buffer viene denominato fetch buffer del cursore. sp_cursorfetch viene richiamata specificando ID = 7 in un pacchetto del flusso TDS.
Si applica a: SQL Server (da SQL Server 2008 a versione corrente). |
.gif "Icona di collegamento a un argomento")
Convenzioni della sintassi Transact-SQL
Sintassi
sp_cursorfetch cursor
[ , fetchtype [ , rownum [ , nrows ] ] ]
Argomenti
cursor
Valore dell'handle generato da SQL Server e restituito da sp_cursoropen. cursor è un parametro obbligatorio che richiede un valore di input int. Per ulteriori informazioni, vedere la sezione Osservazioni di seguito in questo argomento.fetchtype
Specifica il buffer del cursore da recuperare. fetchtype è un parametro facoltativo che richiede uno dei valori di input interi seguenti.Valore
Nome
Descrizione
0x0001
FIRST
Recupera il primo buffer di nrows righe. Se nrows è uguale a 0, il cursore viene posizionato prima del set di risultati e non vengono restituite righe.
0x0002
NEXT
Recupera il buffer successivo di nrows righe.
0x0004
PREV
Recupera il buffer precedente di nrows righe.
Nota
Se si utilizza PREV per un cursore FORWARD_ONLY, viene restituito un messaggio di errore, in quanto FORWARD_ONLY supporta lo scorrimento in una sola direzione.
0x0008
LAST
Recupera l'ultimo buffer di nrows righe. Se nrows è uguale a 0, il cursore viene posizionato dopo il set di risultati e non vengono restituite righe.
> [!NOTE] > <P> Se si utilizza LAST per un cursore FORWARD_ONLY, viene restituito un messaggio di errore, in quanto FORWARD_ONLY supporta lo scorrimento in una sola direzione.</P>0x10
ABSOLUTE
Recupera un buffer di nrows righe a partire dalla riga rownum.
> [!NOTE] > <P> Se si utilizza ABSOLUTE per un cursore DYNAMIC o un cursore FORWARD_ONLY, viene restituito un messaggio di errore, in quanto FORWARD_ONLY supporta lo scorrimento in una sola direzione.</P>0x20
RELATIVE
Recupera il buffer di nrows righe a partire dalla riga specificata come valore rownum di righe a partire dalla prima riga del blocco corrente. In questo caso rownum può essere un numero negativo.
> [!NOTE] > <P> Se si utilizza RELATIVE per un cursore FORWARD_ONLY, viene restituito un messaggio di errore, in quanto FORWARD_ONLY supporta lo scorrimento in una sola direzione.</P>0x80
REFRESH
Reinserisce nel buffer dati delle tabelle sottostanti.
0x100
INFO
Recupera informazioni sul cursore. Tali informazioni vengono restituite tramite i parametri rownum e nrows. Pertanto, quando viene specificato INFO, rownum e nrows diventano parametri di output.
0x200
PREV_NOADJUST
Viene utilizzato come PREV. Se tuttavia l'inizio del set di risultati viene raggiunto prima del previsto, i risultati potrebbero variare.
0x400
SKIP_UPDT_CNCY
Deve essere utilizzato con uno degli altri valori di fetchtype, ad eccezione di INFO.
> [!NOTE] > <P> Il valore 0x40 non è supportato.</P> Per ulteriori informazioni, vedere la sezione Osservazioni di seguito in questo argomento.rownum
Parametro facoltativo utilizzato per specificare la posizione di riga dei valori ABSOLUTE e INFO di fetchtype esclusivamente mediante valori interi per input, output o entrambi. rownum funge da offset di riga per il valore di bit fetchtype RELATIVE. rownum viene ignorato per tutti gli altri valori. Per ulteriori informazioni, vedere la sezione Osservazioni di seguito in questo argomento.nrows
Parametro facoltativo utilizzato per specificare il numero di righe da recuperare. Se per nrows non viene specificato alcun valore, il valore predefinito è 20 righe. Per impostare la posizione senza restituire dati, specificare il valore 0. Quando nrows viene applicato alla query INFO fetchtype, restituisce il numero di righe complessivo della query.Nota
nrows viene ignorato dal valore di bit REFRESH di fetchtype.
Per ulteriori informazioni, vedere la sezione Osservazioni di seguito in questo argomento.
Valori di codice restituiti
Nelle tabelle seguenti vengono indicati i valori che possono essere restituiti quando si specifica il valore di bit INFO.
Nota
: Se non vengono restituite righe, il contenuto del buffer rimane inalterato.
<rownum>
Impostare su
Se non aperto
0
Se posizionato prima del set di risultati
0
Se posizionato dopo il set di risultati
-1
Per i cursori STATIC e KEYSET
Numero di riga assoluto della posizione corrente nel set di risultati
Peri cursori DYNAMIC
1
Per ABSOLUTE
-1 restituisce l'ultima riga di un set.
-2 restituisce la penultima riga di un set e così via.
Nota
Se in questo caso è richiesto il recupero di più di una riga, vengono restituite le ultime due righe del set di risultati.
<nrows>
Impostare su
Se non aperto
0
Per i cursori STATIC e KEYSET
In genere la dimensione del keyset corrente.
–m se la creazione del cursore è asincrona e sono state rilevate m righe fino a questo punto.
Peri cursori DYNAMIC
-1
Osservazioni
Parametro cursor
Prima dell'esecuzione di qualsiasi operazione di recupero, il cursore precede per impostazione predefinita la prima riga del set di risultati.
Parametro fetchtype
Ad eccezione di SKIP_UPD_CNCY, i valori di fetchtype si escludono a vicenda.
Quando viene specificato SKIP_UPDT_CNCY, i valori della colonna timestamp non vengono scritti nella tabella di keyset quando viene recuperata o aggiornata una riga. Se la riga di keyset viene aggiornata, i valori delle colonne timestamp rimangono inalterati. Se la riga di keyset viene inserita, i valori per le colonne timestamp non sono definiti.
Per i cursori KEYSET, ciò significa che per la tabella di keyset i valori vengono impostati durante l'ultima operazione FETCH non ignorata, se ne è stata eseguita una. In caso contrario, i valori vengono impostati durante il popolamento.
Per i cursori DYNAMIC, ciò significa che se l'operazione FETCH viene eseguita con l'aggiornamento, vengono prodotti gli stessi risultati di KEYSET. Per qualsiasi altro tipo di recupero, la tabella di keyset viene troncata. Ciò significa che è in corso l'inserimento delle righe e i valori delle colonne timestamp non vengono definiti. Pertanto, quando si esegue sp_cursorfetch per i cursori DYNAMIC, evitare di utilizzare SKIP_UPDT_CNCY per qualsiasi operazione diversa da REFRESH.
Se un'operazione di recupero non riesce perché la posizione del cursore richiesta è oltre il set di risultati, la posizione del cursore viene impostata subito dopo l'ultima riga. Se un'operazione di recupero non riesce perché la posizione del cursore richiesta è prima del set di risultati, la posizione del cursore viene impostata prima della prima riga.
Parametro rownum
Quando si utilizza rownum, i dati vengono inseriti nel buffer a partire dalla riga specificata.
Il valore ABSOLUTE di fetchtype si riferisce alla posizione di rownum all'interno dell'intero set di risultati. Un numero negativo per ABSOLUTE specifica che l'operazione inizia a contare le righe a partire dalla fine del set di risultati.
Il valore RELATIVE di fetchtype si riferisce alla posizione di rownum rispetto alla posizione del cursore all'inizio del buffer corrente. Un numero negativo per RELATIVE specifica che il cursore va all'indietro a partire dalla posizione corrente.
Parametro nrows
I valori REFRESH e INFO di fetchtype ignorano questo parametro.
Quando si specifica il valore FIRST di fetchtype, con un valore 0 per nrow, il cursore viene posizionato prima del set di risultati nel cui buffer di recupero non sono presenti righe.
Quando si specifica il valore LAST per fetchtype, con un valore 0 per nrow, il cursore viene posizionato dopo il set di risultati nel cui buffer di recupero corrente non sono presenti righe.
Per i valori NEXT, PREV, ABSOLUTE, RELATIVE e PREV_NOADJUST di fetchtype , il valore 0 per nrow non è valido.
Considerazioni su RPC
Lo stato restituito di RPC indica se il parametro di dimensione del keyset è finale oppure no, cioè se è in corso il popolamento asincrono nel keyset o nella tabella temporanea.
Il parametro di stato di RPC viene impostato su uno dei valori mostrati nella tabella seguente.
Valore
Descrizione
0
La routine è stata eseguita correttamente.
0x0001
La routine non è riuscita.
0x0002
Un recupero in direzione negativa ha impostato la posizione del cursore all'inizio del set di risultati, laddove logicamente il recupero avrebbe dovuto trovarsi prima dei risultati.
0x10
Un cursore di avanzamento è stato chiuso automaticamente.
Le righe vengono restituite come set tipico di risultati, ovvero il formato della colonna (0x2a), le righe (0xd1), infine done (0xfd). I token dei metadati vengono inviati nello stesso formato specificato per sp_cursoropen, cioè 0x81, 0xa5 e 0xa4 per gli utenti di SQL Server 7.0 e così via. Gli indicatori di stato delle righe vengono inviati come colonne nascoste, analogamente alla modalità BROWSE, alla fine di ogni riga con nome di colonna rowstat e tipo di dati INT4. Nella colonna rowstat è disponibile uno dei valori mostrati nella tabella seguente:
Valore
Descrizione
0x0001
FETCH_SUCCEEDED
0x0002
FETCH_MISSING
Poiché il protocollo TDS non consente di inviare la colonna dello stato finale senza inviare le colonne precedenti, per le righe mancanti vengono inviati dati fittizi, cioè campi che ammettono i valori Null, campi a lunghezza fissa impostati su 0, vuoti oppure il valore predefinito per quella colonna, a seconda della situazione specifica.
Il conteggio delle righe per DONE sarà sempre zero. Il messaggio DONE include il conteggio delle righe del set di risultati effettivo. Tra i messaggi TDS potrebbero essere visualizzati messaggi di errore o informativi.
Per richiedere che vengano restituiti metadati sull'elenco di selezione del cursore nel flusso TDS, impostare il flag di input RPC RETURN_METADATA su 1.
Esempi
A.Utilizzo di PREV per modificare una posizione del cursore
Si supponga che un cursore h2 produca un set di risultati con il contenuto seguente con la posizione corrente mostrata di seguito:
row 1 contents row 2 contents row 3 contents row 4 contents <-- current position row 5 contents row 6 contentsSi immagini che successivamente un'operazione PREV sp_cursorfetch con il valore di nrows impostato su 5 posizioni logicamente il cursore due righe prima della prima riga del set di risultati. In questi casi, il cursore viene regolato in modo da partire dalla prima riga e restituire il numero di righe richieste. Questo spesso significa che restituirà righe che si trovavano nel buffer di recupero di PRIOR.
Nota
Si tratta esattamente del caso in cui il parametro di stato di RPC è impostato su 2.
B.Utilizzo di PREV_NOADJUST per restituire un numero inferiore di righe rispetto a PREV
PREV_NOADJUST non include mai nel blocco di righe che restituisce le righe che si trovano in corrispondenza della posizione corrente del cursore o dopo tale posizione. Nei casi in cui PREV restituisce righe dopo la posizione corrente, PREV_NOADJUST restituisce un numero inferiore di righe rispetto a quanto richiesto in nrows. Presupponendo che la posizione corrente del cursore sia quella dell'esempio A precedente, quando viene applicato PREV, sp_cursorfetch(h2, 4, 1, 5) recupera le righe seguenti:
row1 contents row2 contents row3 contents row4 contents row5 contentsQuando invece viene applicato PREV_NOADJUST, sp_cursorfetch(h2, 512, 6, 5) recupera solo le righe seguenti:
row1 contents row2 contents row3 contentsVedere anche
Riferimento