sp_cursorfetch (Transact-SQL)

Ruft einen Puffer mit mindestens einer Zeile aus der Datenbank ab. Die Gruppe der Zeilen in diesem Puffer wird als Fetchpuffer des Cursors bezeichnet. sp_cursorfetch wird aufgerufen, indem ID = 7 in einem TDS (Tabular Data Stream)-Paket angegeben wird.

Transact-SQL-Syntaxkonventionen

Syntax

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

Argumente

• cursor
  Ein handle -Wert, der von SQL Server generiert und von sp_cursoropen zurückgegeben wird. cursor ist ein erforderlicher Parameter, der einen int-Eingabewert erfordert. Weitere Informationen finden Sie im Abschnitt mit den Hinweisen weiter unten in diesem Thema.

• fetchtype
  Gibt an, welcher Cursorpuffer abgerufen werden soll. fetchtype ist ein optionaler Parameter, der einen der folgenden ganzzahligen Eingabewerte erfordert.

  Wert	Name	Beschreibung
  0x0001	FIRST	Ruft den ersten Puffer mit nrows-Zeilen ab. Wenn nrows 0 entspricht, wird der Cursor vor dem Resultset positioniert, und es werden keine Zeilen zurückgegeben.
  0x0002	NEXT	Ruft den nächsten Puffer mit nrows-Zeilen ab.
  0x0004	PREV	Ruft den vorherigen Puffer mit nrows-Zeilen ab. Hinweis    Bei Verwendung von PREV für einen FORWARD_ONLY-Cursor wird eine Fehlermeldung zurückgegeben, weil FORWARD_ONLY nur den Bildlauf in einer Richtung unterstützt.
  0x0008	LAST	Ruft den letzten Puffer mit nrows-Zeilen ab. Wenn nrows 0 entspricht, wird der Cursor nach dem Resultset positioniert, und es werden keine Zeilen zurückgegeben. Hinweis    Bei Verwendung von LAST für einen FORWARD_ONLY-Cursor wird eine Fehlermeldung zurückgegeben, weil FORWARD_ONLY nur den Bildlauf in einer Richtung unterstützt.
  0x10	ABSOLUTE	Ruft ab der rownum-Zeile einen Puffer mit nrows-Zeilen ab. Hinweis    Bei Verwendung von ABSOLUTE für einen DYNAMIC-Cursor oder einen FORWARD_ONLY-Cursor wird eine Fehlermeldung zurückgegeben, weil FORWARD_ONLY nur den Bildlauf in einer Richtung unterstützt.
  0x20	RELATIVE	Ruft den Puffer mit nrows-Zeilen beginnend mit der als rownum-Zeilenwert angegebenen Zeile ab der ersten Zeile im aktuellen Block ab. In diesem Fall kann rownum eine negative Zahl sein. Hinweis    Bei Verwendung von RELATIVE für einen FORWARD_ONLY-Cursor wird eine Fehlermeldung zurückgegeben, weil FORWARD_ONLY nur den Bildlauf in einer Richtung unterstützt.
  0x80	REFRESH	Füllt den Puffer anhand zugrunde liegender Tabellen auf.
  0x100	INFO	Ruft Informationen zum Cursor ab. Diese Informationen werden mithilfe des rownum-Parameters und des nrows-Parameters zurückgegeben. Wenn INFO angegeben wird, werden rownum und nrows folglich zu Ausgabeparametern.
  0x200	PREV_NOADJUST	Wird analog zu PREV verwendet. Wenn der Anfang des Resultsets vorzeitig gefunden wird, können die Ergebnisse jedoch variieren.
  0x400	SKIP_UPDT_CNCY	Muss mit einem der anderen fetchtype-Werte außer INFO verwendet werden.

  Hinweis
  Der Wert 0x40 wird nicht unterstützt.

  Weitere Informationen finden Sie im Abschnitt mit den Hinweisen weiter unten in diesem Thema.

• rownum
  Ein optionaler Parameter, mit dem die Zeilenposition für die fetchtype-Werte ABSOLUTE und INFO angegeben wird, wobei für die Eingabe und/oder Ausgabe nur ganzzahlige Werte verwendet werden. rownum dient als Zeilenoffset für den fetchtype-Bitwert RELATIVE. rownum wird für alle anderen Werte ignoriert. Weitere Informationen finden Sie im Abschnitt mit den Hinweisen weiter unten in diesem Thema.

• nrows
  Ein optionaler Parameter, mit dem die Anzahl der abzurufenden Zeilen angegeben wird. Wenn nrows nicht angegeben wird, ist der Standardwert 20 Zeilen. Um die Position ohne Rückgabe von Daten festzulegen,geben Sie den Wert 0 an. Wenn nrows auf die fetchtype-Abfrage INFO angewendet wird, wird die Gesamtanzahl der Zeilen in dieser Abfrage zurückgegeben.

  Hinweis
  nrows wird vom fetchtype-Bitwert REFRESH ignoriert. Weitere Informationen finden Sie im Abschnitt mit den Hinweisen weiter unten in diesem Thema.

Rückgabecodewerte

In den folgenden Tabellen sind die Werte dargestellt, die bei Angabe des Bitwerts INFO zurückgegeben werden können.

Hinweis
:   Wenn keine Zeilen zurückgegeben werden, bleibt der Pufferinhalt unverändert.

<rownum>	Festlegen auf
Falls nicht geöffnet	0
Falls vor dem Resultset positioniert	0
Falls nach dem Resultset positioniert	-1
Für KEYSET- und STATIC-Cursor	Die absolute Zeilennummer der aktuellen Position im Resultset
Für DYNAMIC-Cursor	1
Für ABSOLUTE	-1 gibt die letzte Zeile in einem Satz zurück. -2 gibt die vorletzte Zeile in einem Satz zurück usw. Hinweis Wenn in diesem Fall mehr als eine Zeile abgerufen werden soll, werden die letzten beiden Zeilen des Resultsets zurückgegeben.

Hinweise

cursor-Parameter

Bevor Abrufvorgänge stattgefunden haben, befindet sich die Standardposition eines Cursors vor der ersten Zeile des Resultsets.

fetchtype-Parameter

Außer bei SKIP_UPD_CNCY schließen sich die fetchtype-Werte gegenseitig aus.

Wenn SKIP_UPDT_CNCY angegeben wird, werden die timestamp-Spaltenwerte nicht in die Keysettabelle geschrieben, wenn eine Zeile abgerufen oder aktualisiert wird. Wenn die Keysetzeile aktualisiert wird, wird für die Werte der timestamp-Spalten der vorherige Wert beibehalten. Wenn die Keysetzeile eingefügt wird, wird die Definition der Werte für die timestamp-Spalten aufgehoben.

Bei KEYSET-Cursorn bedeutet dies, dass die Werte der Keysettabelle während des letzten durchgehenden FETCH-Vorgangs festgelegt wurden, falls einer ausgeführt wurde. Andernfalls werden die Werte während der Auffüllung festgelegt.

Bei DYNAMIC-Cursorn bedeutet dies, dass die gleichen Ergebnisse erzeugt werden wie bei KEYSET, wenn der SKIP-Vorgang mit einer Aktualisierung ausgeführt wird. Bei jedem anderen Fetchtyp wird die Keysettabelle abgeschnitten. Dies bedeutet, dass die Zeilen eingefügt werden und die Definition der Werte für die timestamp-Spalte(n) aufgehoben wird. Wenn Sie sp_cursorfetch für DYNAMIC-Cursor ausführen, sollten Sie SKIP_UPDT_CNCY bei jedem anderen Vorgang als REFRESH folglich vermeiden.

Wenn ein Abrufvorgang fehlerhaft ist, weil die angeforderte Cursorposition außerhalb des Resultsets liegt, wird die Cursorposition unmittelbar nach der letzten Zeile festgelegt. Wenn ein Abrufvorgang fehlerhaft ist, weil die angeforderte Cursorposition vor dem Resultset liegt, wird die Cursorposition vor der ersten Zeile festgelegt.

rownum-Parameter

Wenn Sie rownum verwenden, wird der Puffer ab der angegebenen Zeile gefüllt.

Der fetchtype-Wert ABSOLUTE verweist auf die Position von rownum innerhalb des gesamten Resultsets. Eine negative Zahl mit ABSOLUTE gibt an, dass bei dem Vorgang Zeilen vom Ende des Resultsets gezählt werden.

Der fetchtype-Wert RELATIVE verweist relativ zur Cursorposition am Anfang des aktuellen Puffers auf die Position von rownum. Eine negative Zahl mit RELATIVE gibt an, dass sich der Cursor von der aktuellen Cursorposition rückwärts bewegt.

nrows-Parameter

Dieser Parameter wird von den fetchtype -Werten REFRESH und INFO ignoriert.

Wenn Sie den fetchtype-Wert FIRST angeben, der über den nrow-Wert 0 verfügt, wird der Cursor vor dem Resultset positioniert, das über keine Zeilen im Fetchpuffer verfügt.

Wenn Sie den fetchtype-Wert LAST angeben, der über den nrow-Wert 0 verfügt, wird der Cursor nach dem Resultset positioniert, das über keine Zeilen im aktuellen Fetchpuffer verfügt.

Für die fetchtype -Werte NEXT, PREV, ABSOLUTE, RELATIVE und PREV_NOADJUST ist der nrow-Wert 0 nicht gültig.

Überlegungen zu RPC

Der RPC-Rückgabestatus gibt an, ob der KEYSET_SIZE-Parameter abgeschlossen ist, d. h., ob das Keyset oder die temporäre Tabelle asynchron aufgefüllt wird.

Der RPC-Statusparameter wird auf einen der Werte in der folgenden Tabelle festgelegt.

Die Zeilen werden als typisches Resultset zurückgegeben: Spaltenformat (0x2a), Zeilen (0xd1) gefolgt vom fertigen Resultset (0xfd). Metadatentoken werden im gleichen Format gesendet wie für sp_cursoropen, angegeben: 0x81, 0xa5 und 0xa4 für SQL Server 7.0-Benutzer usw. Die Zeilenstatusindikatoren werden ähnlich dem BROWSE-Modus als ausgeblendete Spalten am Ende jeder Zeile mit dem Spaltennamen "rowstat" und dem Datentyp INT4 gesendet. Diese rowstat-Spalte verfügt über einen der Werte aus der folgenden Tabelle.

Weil das TDS-Protokoll keine Möglichkeit bietet, die nachfolgende Statusspalte ohne die vorherigen Spalten zu senden, werden Pseudodaten für fehlende Zeilen gesendet (auf NULL festlegbare Felder sind auf NULL, Felder fester Datenlänge auf 0 (leer) oder ggf. den Standardwert für diese Spalte festgelegt).

Die DONE-Zeilenanzahl ist immer 0 (null). Die DONE-Meldung enthält die tatsächliche Zeilenanzahl des Resultsets, und Fehler- oder Informationsmeldungen können zwischen allen TDS-Meldungen angezeigt werden.

Damit die Metadaten zur SELECT-Liste des Cursors im TDS-Datenstrom zurückgegeben werden, legen Sie das RPC RETURN_METADATA-Eingabeflag auf 1 fest.

Beispiele

A.Ändern einer Cursorposition mithilfe von PREV

Angenommen, der Cursor h2 würde ein Resultset erzeugen, das über den folgenden Inhalt mit der angegebenen aktuellen Position verfügt:

row 1 contents    
row 2 contents
row 3 contents
row 4 contents  <-- current position
row 5 contents 
row 6 contents

Ein sp_cursorfetch-Vorgang PREV mit dem nrows-Wert 5 würde den Cursor als Nächstes logisch zwei Zeilen vor der ersten Zeile des Resultsets positionieren. In diesen Fällen wird der Cursor so eingerichtet, dass er an der ersten Zeile beginnt und die angeforderte Zeilenanzahl zurückgibt. Häufig bedeutet dies, dass er Zeilen aus dem PRIOR-Fetchpuffer zurückgibt.

Hinweis
Genau in diesem Fall wird der RPC-Statusparameter auf 2 festgelegt.

B.Zurückgeben von weniger Zeilen als PREV mithilfe von PREV_NOADJUST

PREV_NOADJUST schließt nie Zeilen ein, die sich an oder nach der aktuellen Cursorposition im Block zurückgegebener Zeilen befinden. Wenn PREV Zeilen nach der aktuellen Position zurückgibt, gibt PREV_NOADJUST weniger Zeilen zurück als in nrows angefordert wurden. Bei der aktuellen Position in Beispiel A oben ruft sp_cursorfetch(h2, 4, 1, 5) die folgenden Zeilen ab, wenn PREV angegeben ist:

row1 contents 
row2 contents
row3 contents
row4 contents
row5 contents

Wenn jedoch PREV_NOADJUST angewendet wird, ruft sp_cursorfetch(h2, 512, 6, 5) nur die folgenden Zeilen ab:

row1 contents 
row2 contents
row3 contents 

Siehe auch

Verweis

sp_cursoropen (Transact-SQL)

Gespeicherte Systemprozeduren (Transact-SQL)