sp_cursoropen (Transact-SQL)

  • Artikel

Gilt für:SQL Server

Öffnet einen Cursor. sp_cursoropen definiert die SQL-Anweisung, die den Cursor- und Cursoroptionen zugeordnet ist, und füllt dann den Cursor auf. sp_cursoropen entspricht der Kombination der Transact-SQL-Anweisungen DECLARE_CURSOR und OPEN. Diese Prozedur wird aufgerufen, indem ID = 2 in einem Tabular Data Stream-Paket (TDS) angegeben wird.

Transact-SQL-Syntaxkonventionen

Syntax

  
sp_cursoropen cursor OUTPUT, stmt  
    [, scrollopt[ OUTPUT ] [ , ccopt[ OUTPUT ]  
    [ ,rowcount OUTPUT [ ,boundparam][,...n]]] ]]

Argumente

Cursor
Ein von SQL Server generierter Cursorbezeichner. cursor is a handle value that must be supplied on all subsequent procedures involving the cursor, such as sp_cursorfetch. Cursor ist ein erforderlicher Parameter mit einem Int-Rückgabewert .

Cursor ermöglicht es mehreren Cursorn, in einer einzigen Datenbankverbindung aktiv zu sein.

Stmt
Ein erforderlicher Parameter, der das Cursorresultset definiert. Jede gültige Abfragezeichenfolge (Syntax und Bindung) eines beliebigen Zeichenfolgentyps (unabhängig von Unicode, Größe usw.) kann als gültiger Stmt-Werttyp dienen.

scrollopt
Option für den Bildlauf. scrollopt ist ein optionaler Parameter, der einen der folgenden Int-Eingabewerte erfordert.

Wert Beschreibung
0x0001 KEYSET
0x0002 DYNAMIC
0x0004 FORWARD_ONLY
0x0008 STATIC
0x10 FAST_FORWARD
0x1000 PARAMETERIZED_STMT
0x2000 AUTO_FETCH
0x4000 AUTO_CLOSE
0x8000 CHECK_ACCEPTED_TYPES
0x10000 KEYSET_ACCEPTABLE
0x20000 DYNAMIC_ACCEPTABLE
0x40000 FORWARD_ONLY_ACCEPTABLE
0x80000 STATIC_ACCEPTABLE
0x100000 FAST_FORWARD_ACCEPTABLE

Aufgrund der Möglichkeit, dass der angeforderte Wert für den durch stmt definierten Cursor nicht geeignet ist, dient dieser Parameter sowohl als Eingabe als auch als Ausgabe. In solchen Fällen weist SQL Server einen passenden Wert zu.

Kcopt
Option für die Parallelitätssteuerung. ccopt ist ein optionaler Parameter, der einen der folgenden Int-Eingabewerte erfordert.

Wert Beschreibung
0x0001 READ_ONLY
0x0002 SCROLL_LOCKS (vormals bekannt als LOCKCC)
0x0004 OPTIMISTISCH (früher als OPTCC bezeichnet)
0x0008 OPTIMISTIC (vormals bekannt als OPTCCVAL)
0x2000 ALLOW_DIRECT
0x4000 UPDT_IN_PLACE
0x8000 CHECK_ACCEPTED_OPTS
0x10000 READ_ONLY_ACCEPTABLE
0x20000 SCROLL_LOCKS_ACCEPTABLE
0x40000 OPTIMISTIC_ACCEPTABLE
0x80000 OPTIMISITC_ACCEPTABLE

Wie bei scrollopt kann SQL Server die angeforderten Ccopt-Werte überschreiben.

Rowcount
Die Anzahl der mit AUTO_FETCH zu verwendenden Fetchpufferzeilen. Der Standardwert ist 20 Zeilen. Rowcount verhält sich anders, wenn ein Eingabewert als Eingabewert oder ein Rückgabewert zugewiesen wird.

Als Eingabewert Als Rückgabewert
Wenn der AUTO_FETCH Scrollopt-Wert angegeben ist, stellt rowcount die Anzahl der Zeilen dar, die in den Abrufpuffer eingefügt werden sollen.

Hinweis: >0 ist ein gültiger Wert, wenn AUTO_FETCH angegeben wird, andernfalls ignoriert wird.		 Stellt die Anzahl der Zeilen im Resultset dar, außer wenn der Bildlaufopt AUTO_FETCH Wert angegeben ist.

-

boundparam
Gibt die Verwendung zusätzlicher Parameter an. boundparam ist ein optionaler Parameter, der angegeben werden soll, wenn der Scrollopt-PARAMETERIZED_STMT Wert auf EIN festgelegt ist.

Rückgabecodewerte

Wenn kein Fehler ausgelöst wird, gibt sp_cursoropen einen der folgenden Werte zurück.

0
Die Prozedur wurde erfolgreich ausgeführt.

0x0001
Fehler während der Ausführung (geringfügiger Fehler, nicht schwerwiegend genug, um einen Fehler im Betriebsablauf auszulösen).

0x0002
Ein asynchroner Vorgang wird ausgeführt.

0x0002
Ein FETCH-Vorgang wird ausgeführt.

A
Dieser Cursor wurde von SQL Server abgeglichen und ist nicht verfügbar.

Wenn ein Fehler ausgelöst wird, sind die Rückgabewerte möglicherweise inkonsistent, und die Genauigkeit kann nicht gewährleistet werden.

Wenn der Parameter "rowcount " als Rückgabewert angegeben wird, tritt das folgende Resultset auf.

-1
Wird zurückgegeben, wenn die Anzahl der Zeilen unbekannt oder nicht anwendbar ist.

-n
Wird zurückgegeben, wenn eine asynchrone Auffüllung aktiviert ist. Stellt die Anzahl der Zeilen dar, die im Abrufpuffer platziert wurden, wenn der Scrollopt-AUTO_FETCH Wert angegeben wird.

Wenn RPC verwendet wird, lauten die Rückgabewerte wie folgt.

0
Die Prozedur ist erfolgreich.

1
Fehler bei der Prozedur.

2
Ein KEYSET-Cursor wird asynchron generiert.

16
Ein FAST_FORWARD-Cursor wurde automatisch geschlossen.

Hinweis

Wenn die sp_cursoropen-Prozedur erfolgreich ausgeführt wird, werden die RPC-Rückgabeparameter und ein Resultset mit TDS-Spaltenformatinformationen (0xa0 und 0xa1 Nachrichten) gesendet. Andernfalls wird mindestens eine TDS-Fehlermeldung gesendet. In beiden Fällen werden keine Zeilendaten zurückgegeben, und die Anzahl der erledigten Nachrichten ist null. Wenn Sie eine Version von SQL Server vor 7.0 verwenden, 0xa0 werden 0xa1 (Standard für SELECT-Anweisungen) zusammen mit 0xa5- und 0xa4 Tokenstreams zurückgegeben. Wenn Sie SQL Server 7.0 verwenden, wird 0x81 (Standard für SELECT-Anweisungen) zusammen mit den 0xa5- und 0xa4 Tokenstreams zurückgegeben.

Hinweise

stmt-Parameter

Wenn stmt die Ausführung einer gespeicherten Prozedur angibt, können die Eingabeparameter entweder als Konstanten als Teil der stmt-Zeichenfolge definiert oder als Boundparam-Argumente angegeben werden. Deklarierte Variablen können auf diese Weise als gebundene Parameter übergeben werden.

Der zulässige Inhalt des stmt-Parameters hängt davon ab, ob der Ccopt ALLOW_DIRECT Rückgabewert von OR mit den restlichen Ccopt-Werten verknüpft wurde, d. h.:

  • Wenn ALLOW_DIRECT nicht angegeben ist, muss entweder eine Transact-SQL SELECT- oder EXECUTE-Anweisung verwendet werden, die eine gespeicherte Prozedur mit einer einzelnen SELECT-Anweisung aufruft. Darüber hinaus muss die SELECT-Anweisung als Cursor gelten; d. h. sie kann die Schlüsselwort (keyword)s SELECT INTO oder FOR BROWSE nicht enthalten.

  • Wenn ALLOW_DIRECT angegeben ist, kann dies zu einer oder mehreren Transact-SQL-Anweisungen führen, einschließlich derer, die wiederum andere gespeicherte Prozeduren mit mehreren Anweisungen ausführen. Nicht-SELECT-Anweisungen oder beliebige SELECT-Anweisungen, die die Schlüsselwörter SELECT INTO oder FOR BROWSE enthalten, werden einfach ausgeführt und führen nicht zur Erstellung eines Cursors. Dies trifft auch auf jede SELECT-Anweisung zu, die in einem aus mehreren Anweisungen bestehenden Batch enthalten ist. Wenn eine SELECT-Anweisung Klauseln enthält, die nur Cursor betreffen, werden diese Klauseln ignoriert. Wenn beispielsweise der Wert von Ccopt 0x2002 ist, ist dies eine Anforderung für:

    • Ein Cursor mit Bildlaufsperren, wenn es nur eine einzelne SELECT-Anweisung gibt, die sich als Cursor qualifiziert, oder

    • Eine direkte Anweisungsausführung, wenn mehrere Anweisungen, eine einzelne Nicht-SELECT-Anweisung oder eine SELECT-Anweisung, die sich nicht als Cursor qualifiziert, vorhanden sind.

scrollopt-Parameter

Die ersten fünf Bildlaufoptwerte (KEYSEY, DYNAMIC, FORWARD_ONLY, STATIC und FAST_FORWARD) schließen sich gegenseitig aus.

PARAMETERIZED_STMT und CHECK_ACCEPTED_TYPES können durch OR mit einem der ersten fünf Werte verknüpft werden.

AUTO_FETCH und AUTO_CLOSE können durch OR mit FAST_FORWARD verknüpft werden.

Wenn CHECK_ACCEPTED_TYPES aktiviert ist, müssen mindestens eine der letzten fünf Bildlaufoptwerte (KEYSET_ACCEPTABLE, DYNAMIC_ACCEPTABLE, FORWARD_ONLY_ACCEPTABLE, STATIC_ACCEPTABLE oder FAST_FORWARD_ACCEPTABLE) ebenfalls EIN sein.

STATIC-Cursor werden immer als READ_ONLY geöffnet. Dies bedeutet, dass die zugrunde liegende Tabelle über diesen Cursor nicht aktualisiert werden kann.

ccopt-Parameter

Die ersten vier Kcoptwerte (READ_ONLY, SCROLL_LOCKS und beide OPTIMISTISCHe Werte) schließen sich gegenseitig aus.

Hinweis

Wenn Sie einen der ersten vier Ccopt-Werte auswählen, wird festgelegt, ob der Cursor schreibgeschützt ist, oder ob sperrungs- oder optimistische Methoden verwendet werden, um verlorene Updates zu verhindern. Wenn kein Ccopt-Wert angegeben ist, ist der Standardwert OPTIMISTISCH.

ALLOW_DIRECT und CHECK_ACCEPTED_TYPES können durch OR mit einem der ersten vier Werte verknüpft werden.

UPDT_IN_PLACE kann durch OR mit READ_ONLY, SCROLL_LOCKS oder einem der OPTIMISTIC-Werte verknüpft werden.

Wenn CHECK_ACCEPTED_TYPES eins ist, muss mindestens einer der letzten vier Kcoptwerte (READ_ONLY_ACCEPTABLE, SCROLL_LOCKS_ACCEPTABLE und eines der OPTIMISTIC_ACCEPTABLE Werte) ebenfalls EIN sein.

Positionierte UPDATE- und DELETE-Funktionen können nur innerhalb des Abrufpuffers ausgeführt werden und nur, wenn der Ccopt-Wert SCROLL_LOCKS oder OPTIMISTISCH ist. Wenn SCROLL_LOCKS als Wert angegeben wird, verläuft der Vorgang mit Sicherheit erfolgreich. Wenn OPTIMISTIC als Wert angegeben wird, ist der Vorgang fehlerhaft, wenn die Zeile seit dem letzten Abruf geändert wurde.

Der Grund für diesen Fehler besteht darin, dass bei OPTIMISTISCH der angegebene Wert eine optimistische Währungssteuerungsfunktion durchgeführt wird, indem Zeitstempel oder Prüfsummenwerte verglichen werden, wie von SQL Server bestimmt. Wenn beliebige dieser Zeilen nicht übereinstimmen, ist der Vorgang fehlerhaft.

Wenn UPDT_IN_PLACE als Rückgabewert angegeben wird, sind die Ergebnisse wie folgt:

  • Wenn der Parameter beim Ausführen eines positionierten Updates für eine Tabelle mit einem eindeutigen Index nicht festgelegt ist, löscht der Cursor die Zeile aus seiner Arbeitstabelle und fügt sie am Ende einer beliebigen vom Cursor verwendeten Schlüsselspalte ein. Dabei werden die Spalten geändert.

  • Wenn der Parameter auf ON festgelegt ist, aktualisiert der Cursor einfach die Schlüsselspalten in der ursprünglichen Zeile der Arbeitstabelle.

bound_param-Parameter

Der Parametername sollte paramdef sein, wenn PARAMETERIZED_STMT gemäß der Fehlermeldung im Code angegeben wird. Wenn PARAMETERIZED_STMT nicht angegeben ist, wird kein Name in der Fehlermeldung angegeben.

Überlegungen zu RPC

Das RPC-RETURN_METADATA-Eingabeflag kann auf 0x0001 festgelegt werden. Dadurch wird angefordert, dass Metadaten zur SELECT-Liste des Cursors im TDS-Datenstrom zurückgegeben werden.

Beispiele

bound_param-Parameter

Alle nach dem fünften Parameter übergebenen Parameter werden als Eingabeparameter an den Anweisungsplan übergeben. Der erste derartige Parameter muss eine Zeichenfolge im folgenden Format sein:

{ Datentyp des lokalen Variablennamens } [,... n]

Nachfolgende Parameter werden verwendet, um die Werte zu übergeben, die durch den lokalen Variablennamen in der Anweisung ersetzt werden sollen.

Weitere Informationen

sp_cursorfetch (Transact-SQL)
Gespeicherte Systemprozeduren (Transact-SQL)