Condividi tramite

sp_cursorfetch (Transact-SQL)

  • Articolo

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 relative alla 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 altre informazioni, vedere la sezione Osservazioni.

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 restituisce un FORWARD_ONLY 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 restituisce un FORWARD_ONLY 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 DYNAMIC cursore o un FORWARD_ONLY cursore 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, rownum può essere un numero negativo.

Nota: l'uso di RELATIVE per un cursore restituisce un FORWARD_ONLY 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 INFO viene specificato, rownum e nrows diventano parametri di output.
0x200 PREV_NOADJUST Viene usato 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 usato con uno degli altri valori fetchtype , ad eccezione di INFO.

Nota

Non è disponibile alcun supporto per il valore 0x40.

Per altre informazioni, vedere la sezione Osservazioni.

rownum

Parametro facoltativo utilizzato per specificare la posizione della riga per i ABSOLUTE valori e INFO fetchtype utilizzando solo valori integer per input o output o entrambi. rownum funge da offset di riga per il valore RELATIVEdi bit fetchtype . rownum viene ignorato per tutti gli altri valori. Per altre informazioni, vedere la sezione Osservazioni.

rows

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 la query fetchtype INFO viene applicata a nrows, restituisce il numero totale di righe nella query.

nrows viene ignorato dal REFRESH valore di bit fetchtype . Per altre informazioni, vedere la sezione Osservazioni.

Valori del codice restituito

Quando si specifica il valore INFOdi bit , i valori che potrebbero essere restituiti vengono visualizzati nelle tabelle seguenti.

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 KEYSET i cursori e STATIC Numero di riga assoluto della posizione corrente nel set di risultati
Per DYNAMIC i cursori 1
Per ABSOLUTE -1 restituisce l'ultima riga di un set.

-2 restituisce la penultima riga di un set e così via.

Nota: se sono richieste più righe per il recupero in questo caso, vengono restituite le ultime due righe del set di risultati.
<nrows> Impostare su
Se non aperto 0
Per KEYSET i cursori e STATIC In genere la dimensione del keyset corrente.

-m se il cursore è in fase di creazione asincrona con m righe trovate a questo punto.
Per DYNAMIC i cursori -1

Osservazioni:

Parametro del cursore

Prima di qualsiasi operazione di recupero, la posizione predefinita di un cursore è prima della prima riga del set di risultati.

Parametro fetchtype

Ad eccezione di SKIP_UPD_CNCY, i valori fetchtype si escludono a vicenda.

Quando SKIP_UPDT_CNCY viene specificato, i valori di colonna timestamp non vengono scritti nella tabella keyset quando una riga viene recuperata o aggiornata. 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 KEYSET i cursori, ciò significa che la tabella keyset ha i valori impostati durante l'ultimo nonskip FETCH, se ne è stata eseguita una. In caso contrario, si tratta dei valori impostati durante la popolazione.

Per DYNAMIC i cursori, ciò significa che se il skip viene eseguito con un aggiornamento, produce gli stessi risultati di KEYSET. Per qualsiasi altro tipo di recupero, la tabella di keyset viene troncata. Ciò significa che le righe vengono inserite e i valori per le colonne timestamp non sono definiti. Pertanto, quando si esegue sp_cursorfetch per DYNAMIC i cursori, evitare di usare 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 ABSOLUTE fetchtype fa riferimento alla posizione di rownum all'interno dell'intero set di risultati. Un numero negativo con ABSOLUTE specifica che l'operazione conta le righe dalla fine del set di risultati.

Il valore RELATIVE fetchtype fa riferimento alla posizione di rownum in relazione alla posizione del cursore all'inizio del buffer corrente. Un numero negativo con RELATIVE specifica che il cursore passa all'indietro dalla posizione corrente del cursore.

Parametro nrows

I valori REFRESH fetchtype e INFO ignorano questo parametro.

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

Quando si specifica un valore fetchtype pari LAST a 0, il cursore viene posizionato dopo il set di risultati che non contiene righe nel buffer di recupero corrente.

Per i valori fetchtype di NEXT, PREVABSOLUTE, RELATIVE, e PREV_NOADJUST, un valore nrow di 0 non è valido.

Considerazioni su RPC

Lo stato restituito RPC indica se il parametro keyset size è finale o meno; ovvero se il keyset o la tabella temporanea vengono popolati in modo asincrono.

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 di risultati tipico: formato di colonna (0x2a), righe (0xd1), seguito da DONE (0xfd). I token di metadati vengono inviati nello stesso formato specificato per sp_cursoropen: 0x810xa5 e 0xa4 per gli utenti di SQL Server e così via. Gli indicatori di stato della riga vengono inviati come colonne nascoste, in modo simile alla BROWSE modalità, alla fine di ogni riga con il nome della colonna rowstat e il tipo di dati int. Questa colonna rowstat include uno dei valori illustrati nella tabella seguente.

valore Descrizione
0x0001 FETCH_SUCCEEDED
0x0002 FETCH_MISSING

Poiché il protocollo TDS non consente di inviare la colonna di stato finale senza inviare le colonne precedenti, i dati fittizi vengono inviati per le righe mancanti. I campi nullable sono impostati su Null e i campi a lunghezza fissa vengono impostati su 0, vuoto o predefinito per tale colonna, in base alle esigenze.

Il conteggio delle DONE righe è sempre 0. Il DONE messaggio contiene il conteggio delle righe effettivo del set di risultati e potrebbero essere visualizzati messaggi di errore o informativi tra tutti i messaggi TDS.

Per richiedere che i metadati relativi all'elenco di selezione del cursore vengano restituiti nel flusso TDS, impostare il flag di input RPC RETURN_METADATA su 1.

Esempi

R. Usare 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, un oggetto sp_cursorfetch PREV in cui le rows sono 5 posizionate 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. Ciò significa spesso che restituisce righe presenti nel PRIOR buffer di recupero.

Nota

Si tratta esattamente del caso in cui il parametro di stato di RPC è impostato su 2.

B. Usare PREV_NOADJUST per restituire un numero inferiore di righe rispetto a PREV

PREV_NOADJUST non include mai alcuna delle righe in corrispondenza o dopo la posizione corrente del cursore nel blocco di righe restituite. 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 PREV viene applicata, sp_cursorfetch (h2, 4, 1, 5) recupera le righe seguenti:

row1 contents
row2 contents
row3 contents
row4 contents
row5 contents

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

row1 contents
row2 contents
row3 contents

Contenuto correlato