sp_cursorfetch (Transact-SQL)

Si applica a:SQL Server

Recupera un buffer di una o più righe dal database. Il gruppo di righe in questo buffer è denominato buffer di recupero del cursore. sp_cursorfetch viene richiamato specificando ID = 7 in un pacchetto TDS (Tabular Data Stream).

Convenzioni di sintassi Transact-SQL

Sintassi

  
sp_cursorfetch cursor  
    [ , fetchtype[ , rownum [ , nrows] ]]   

Argomenti

cursor
Valore handle generato da SQL Server e restituito da sp_cursoropen. cursor è un parametro obbligatorio che chiama per 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 integer seguenti.

Valore	Nome	Descrizione
0x0001	FIRST	Recupera il primo buffer di righe di rows . 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 righe di rows .
0x0004	PREV	Recupera il buffer precedente di righe di rows . Nota: l'uso di PREV per un cursore FORWARD_ONLY restituisce un messaggio di errore perché FORWARD_ONLY supporta solo lo scorrimento in una direzione.
0x0008	LAST	Recupera l'ultimo buffer di righe di rows . Se nrows è uguale a 0, il cursore viene posizionato dopo il set di risultati e non vengono restituite righe. Nota: l'uso di LAST per un cursore FORWARD_ONLY restituisce un messaggio di errore perché FORWARD_ONLY supporta solo lo scorrimento in una direzione.
0x10	ABSOLUTE	Recupera un buffer di righe che iniziano con la riga rownum . Nota: l'uso di ABSOLUTE per un cursore DYNAMIC o un cursore FORWARD_ONLY restituisce un messaggio di errore perché FORWARD_ONLY supporta solo lo scorrimento in una direzione.
0x20	RELATIVE	Recupera il buffer di righe di rows a partire dalla riga specificata come valore rownum delle righe della prima riga del blocco corrente. In questo caso il numero di riga può essere un numero negativo. Nota: l'uso di RELATIVE per un cursore FORWARD_ONLY restituisce un messaggio di errore perché FORWARD_ONLY supporta solo lo scorrimento in una direzione.
0x80	REFRESH	Reinserisce nel buffer dati delle tabelle sottostanti.
0x100	INFO	Recupera informazioni sul cursore. Queste informazioni vengono restituite usando i parametri rownum e nrows . Pertanto, quando si specifica INFO, il numero di righe e le row 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 fetchtype , ad eccezione di INFO.

Nota

Il valore 0x40 non è supportato.

Per ulteriori informazioni, vedere la sezione Osservazioni di seguito in questo argomento.

Rownum
Parametro facoltativo utilizzato per specificare la posizione della riga per i valori di fetchtype ABSOLUTE e INFO utilizzando solo valori integer per input o 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 non viene specificato nrows , il valore predefinito è 20 righe. Per impostare la posizione senza restituire dati, specificare il valore 0. Quando nrows viene applicato alla query fetchtype INFO, restituisce il numero totale di righe nella query.

Nota

nrows viene ignorato dal valore di bit refresh fetchtype .

Per ulteriori informazioni, vedere la sezione Osservazioni di seguito in questo argomento.

Valori del codice restituito

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 invariato.

<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 è necessario recuperare più righe in questo caso, 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 il cursore è in fase di creazione asincrona con m righe trovate 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 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 usa rownum, il buffer viene riempito a partire dalla riga specificata.

Il valore fetchtype ABSOLUTE fa riferimento 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 fetchtype RELATIVE fa riferimento alla posizione di rownum in relazione 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 di fetchtype REFRESH e INFO ignorano questo parametro.

Quando si specifica un valore fetchtype first con un valore di row pari a 0, il cursore viene posizionato prima del set di risultati senza righe nel buffer di recupero.

Quando si specifica un valore fetchtype last con valore nrow pari a 0, il cursore viene posizionato dopo il set di risultati senza righe nel buffer di recupero corrente.

Per i valori fetchtype di NEXT, PREV, ABSOLUTE, RELATIVE e PREV_NOADJUST, il valore nrow pari a 0 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, ovvero: 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. La colonna rowstat può avere 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

R. 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 contents  

Successivamente, una sp_cursorfetch PREV con un valore di rows pari a 5 posiziona 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 quelle richieste in row. Data la posizione corrente nell'esempio A precedente, quando si applica PREV, sp_cursorfetch(h2, 4, 1, 5) recupera le righe seguenti:

row1 contents   
row2 contents  
row3 contents  
row4 contents  
row5 contents  

Tuttavia, quando viene applicato PREV_NOADJUST, sp_cursorfetch(h2, 512, 6, 5) recupera solo le righe seguenti:

row1 contents   
row2 contents  
row3 contents   

Vedi anche

sp_cursoropen (Transact-SQL)
Stored procedure di sistema (Transact-SQL)