sp_cursoropen (Transact-SQL)

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 in einem TDS-Paket (Tabular Data Stream) angegeben ID = 2 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 ist ein handle Wert, der für alle nachfolgenden Prozeduren mit dem Cursor angegeben werden muss, z sp_cursorfetch. B. . Der Cursorparameter ist int und kann nicht sein NULL.

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

stmt

Ein erforderlicher Parameter, der den Cursorergebnissatz 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. Der Scrollopt-Parameter ist int, mit einem Standardwert von NULL, und kann einer der folgenden Werte sein.

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 (früher bekannt als LOCKCC)
0x0004 OPTIMISTIC (früher bekannt als OPTCC)
0x0008 OPTIMISTIC (früher 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 abzurufenden Pufferzeilen, die mit AUTO_FETCH. 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 wird, 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 wird er ignoriert.
Stellt die Anzahl der Zeilen im Resultset dar, außer wenn der Bildlaufoptwert AUTO_FETCH angegeben wird.

boundparam

Kennzeichnet die Verwendung zusätzlicher Parameter. boundparam ist ein optionaler Parameter, der angegeben werden soll, wenn der Scrollopt-Wert PARAMETERIZED_STMT auf ON

Rückgabecodewerte

Wenn kein Fehler ausgelöst wird, sp_cursoropen wird eins der folgenden Werte zurückgegeben.

Wert Beschreibung
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 deallocated und ist nicht verfügbar.

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

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

Wert Beschreibung
-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 beim Angeben des Scrollopt-Werts AUTO_FETCH in den Abrufpuffer eingefügt wurden.

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

Wert Beschreibung
0 Die Prozedur ist erfolgreich.
1 Fehler bei der Prozedur.
2 Ein KEYSET-Cursor wird asynchron generiert.
16 Ein Schneller Vorwärtscursor wurde automatisch geschlossen.

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 DONE Nachrichtenanzahl ist 0. 0x81wird zusammen mit den 0xa5 Tokendatenströmen 0xa4 (Standard für SELECT Anweisungen) zurückgegeben.

Hinweise

Der 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 Rückgabewert des Ccopt mit OR den restlichen Ccopt-Werten ALLOW_DIRECT verknüpft wurde.

  • Falls ALLOW_DIRECT nicht angegeben, muss entweder eine Transact-SQL- oder EXECUTE Eine Transact-SQL-AnweisungSELECT, die eine gespeicherte Prozedur mit einer einzelnen SELECT Anweisung enthält, verwendet werden. Darüber hinaus muss die SELECT Anweisung als Cursor gelten, d. h., sie darf nicht die Schlüsselwörter SELECT INTO oder FOR BROWSE.

  • Wenn ALLOW_DIRECT angegeben, kann dies zu einer oder mehreren Transact-SQL-Anweisungen führen, einschließlich Anweisungen, die andere gespeicherte Prozeduren mit mehreren Anweisungen ausführen. SELECT Keine Anweisungen oder eine AnweisungSELECT, die die Schlüsselwörter SELECT INTO enthält oder FOR BROWSE ausgeführt werden, und führen nicht zur Erstellung eines Cursors. Das gleiche gilt für jede SELECT Anweisung, die in einem Batch mehrerer Anweisungen enthalten ist. In Fällen, in denen eine SELECT Anweisung Klauseln enthält, die nur zu Cursorn gehören, werden diese Klauseln ignoriert. Wenn beispielsweise der Wert von Ccopt lautet 0x2002, ist dies eine Anforderung für:

    • Ein Cursor mit Bildlaufsperren, wenn nur eine einzelne SELECT Anweisung vorhanden ist, die als Cursor qualifiziert ist oder

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

Der Scrollopt-Parameter

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

PARAMETERIZED_STMT und CHECK_ACCEPTED_TYPES kann mit OR einem der ersten fünf Werte verknüpft werden.

AUTO_FETCH und AUTO_CLOSE kann mit OR FAST_FORWARD.

Ist CHECK_ACCEPTED_TYPES dies ONder Fall, muss mindestens einer der letzten fünf Bildlaufoptwerte (KEYSET_ACCEPTABLE, DYNAMIC_ACCEPTABLE, FORWARD_ONLY_ACCEPTABLE, STATIC_ACCEPTABLEoder FAST_FORWARD_ACCEPTABLE) ebenfalls sein ON.

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

Der Ccopt-Parameter

Die ersten vier Kcoptwerte (READ_ONLY, SCROLL_LOCKSund beide OPTIMISTIC 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, lautet OPTIMISTICder Standardwert .

ALLOW_DIRECT und CHECK_ACCEPTED_TYPES kann mit OR einem der ersten vier Werte verknüpft werden.

UPDT_IN_PLACE kann mit OR READ_ONLY, SCROLL_LOCKSoder mit einem der OPTIMISTIC Werte verknüpft werden.

Ist CHECK_ACCEPTED_TYPES dies ONder Wert , muss mindestens einer der letzten vier Ccopt-Werte (READ_ONLY_ACCEPTABLE, SCROLL_LOCKS_ACCEPTABLEund eines der OPTIMISTIC_ACCEPTABLE Werte) ebenfalls EIN sein.

Positioniert UPDATE und DELETE Funktionen können nur innerhalb des Abrufpuffers und nur ausgeführt werden, wenn der Ccopt-Wert gleich SCROLL_LOCKS oder OPTIMISTIC. Wenn SCROLL_LOCKS der angegebene Wert angegeben ist, wird der Vorgang garantiert erfolgreich ausgeführt. Wenn OPTIMISTIC der angegebene Wert angegeben ist, schlägt der Vorgang fehl, wenn die Zeile seit dem letzten Abruf geändert wurde.

Der Grund für diesen Fehler besteht darin, dass beim OPTIMISTIC Angeben des angegebenen Werts eine optimistische Währungssteuerungsfunktion durchgeführt wird, indem Zeitstempel oder Prüfsummenwerte verglichen werden, wie von SQL Server bestimmt. Wenn eine dieser Zeilen nicht übereinstimmt, schlägt der Vorgang fehl.

Die Angabe UPDT_IN_PLACE als Rückgabewert steuert die folgenden Ergebnisse:

  • Wenn beim Ausführen einer positionierten Aktualisierung einer Tabelle mit einem eindeutigen Index nicht festgelegt wird, löscht der Cursor die Zeile aus der Arbeitstabelle und fügt sie am Ende einer der schlüsselspalten ein, die vom Cursor verwendet werden, wodurch diese Spalten geändert werden.

  • Bei Festlegung ONaktualisiert der Cursor die Schlüsselspalten in der ursprünglichen Zeile der Arbeitstabelle.

Der parameter bound_param

Der Parametername sollte paramdef sein, wenn PARAMETERIZED_STMT er angegeben wird, entsprechend der Fehlermeldung im Code. Wenn PARAMETERIZED_STMT sie nicht angegeben ist, wird in der Fehlermeldung kein Name angegeben.

RPC-Überlegungen

Das RPC-Eingabeflagge RETURN_METADATA kann so festgelegt 0x0001 werden, dass die Cursorauswahllistenmetadaten im TDS-Datenstrom zurückgegeben werden.

Beispiele

A. Der parameter bound_param

Alle nach dem fünften Parameter übergebenen Parameter werden als Eingabeparameter an den Anweisungsplan übergeben. Der erste parameter muss eine Zeichenfolge in der folgenden Form sein:

<parameter_name> <data_type> [ ,... n ]

Nachfolgende Parameter werden verwendet, um die Werte zu übergeben, die durch die <parameter_name> in der Anweisung ersetzt werden sollen.