Freigeben über

sp_cursoropen (Transact-SQL)

  • Artikel

Öffnet einen Cursor. sp_cursoropen definiert die dem Cursor und den Cursoroptionen zugeordnete SQL-Anweisung und füllt dann den Cursor auf. sp_cursoropenentspricht 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.

Themenlink (Symbol) 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 Handlewert, der für alle nachfolgenden Prozeduren bereitgestellt werden muss, in die der Cursor involviert ist, z. B. sp_cursorfetch. cursor ist ein erforderlicher Parameter mit einem int-Rückgabewert.

    Bei cursor können mehrere Cursor über eine einzelne Datenbankverbindung aktiv sein.

  • stmt
    Ein erforderlicher Parameter, der das Cursorresultset definiert. Eine beliebige 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

    Da es möglich ist, dass der angeforderte Wert nicht für den von stmt definierten Cursor geeignet ist, dient dieser Parameter sowohl als Eingabe- als auch als Ausgabeparameter. In solchen Fällen weist SQL Server einen passenden Wert zu.

  • ccopt
    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

    OPTIMISTIC (vormals bekannt als OPTCC)

    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 Das Verhalten von rowcount ist unterschiedlich, je nachdem, ob der Parameter als Eingabewert oder Rückgabewert zugewiesen wird.

    Als Eingabewert

    Als Rückgabewert

    Wenn der scrollopt-Wert AUTO_FETCH angegeben wird, stellt rowcount die Anzahl der Zeilen dar, die im Fetchpuffer platziert werden sollen.

    HinweisHinweis

    >0 ist ein gültiger Wert, wenn AUTO_FETCH angegeben ist, wird jedoch andernfalls ignoriert.

    Stellt die Anzahl der Zeilen im Resultset dar, außer wenn der scrollopt-Wert AUTO_FETCH angegeben wird.

  • boundparam
    Gibt die Verwendung zusätzlicher Parameter an. boundparam ist ein optionaler Parameter, der anzugeben ist, wenn der PARAMETERIZED_STMT-Wert von scrollopt auf ON festgelegt wird.

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
    Die Zuordnung dieses Cursors wurde von SQL Server aufgehoben, und er 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 rowcount-Parameter 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 bei Angabe des scrollopt-Werts AUTO-FETCH im Fetchpuffer platziert wurden.

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.

HinweisHinweis

Wenn die Prozedur sp_cursoropen erfolgreich ausgeführt wird, werden die RPC-Rückgabeparameter und ein Resultset mit TDS-Spaltenformatinformationen (Meldungen 0xa0 & 0xa1) gesendet. Andernfalls wird mindestens eine TDS-Fehlermeldung gesendet. Zeilendaten werden in keinem der beiden Fälle zurückgegeben, und die Anzahl der done-Meldungen ist 0 (null). Wenn Sie eine SQL Server-Version vor 7.0 verwenden, werden 0xa0 und 0xa1 (Standard für SELECT-Anweisungen) zusammen mit den Tokendatenströmen 0xa5 und 0xa4 zurückgegeben. Wenn Sie SQL Server 7.0 verwenden, wird 0x81 (Standard für SELECT-Anweisungen) zusammen mit den Tokendatenströmen 0xa5 und 0xa4 zurückgegeben.

Hinweise

stmt-Parameter

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

Ob der Inhalt des stmt-Parameters zulässig ist, hängt davon ab, ob der ccopt ALLOW_DIRECT-Rückgabewert durch OR mit den übrigen ccopt-Werten verknüpft wurde, d. h.:

  • Wenn ALLOW_DIRECT nicht angegeben wird, muss die Transact-SQL-Anweisung SELECT oder EXECUTE verwendet werden, die eine gespeicherte Prozedur mit einer einzelnen SELECT-Anweisung erfordert. Weiterhin muss sich die SELECT-Anweisung als Cursor qualifizieren; d. h., sie darf nicht die Schlüsselwörter SELECT INTO oder FOR BROWSE enthalten.

  • Wenn ALLOW_DIRECT angegeben wird, kann dies zu mindestens einer Transact-SQL-Anweisung führen, einschließlich der Anweisungen, die ihrerseits 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 der Wert von ccopt 0x2002 lautet, wird dadurch z. B. Folgendes angefordert:

    • 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 scrollopt-Werte (KEYSET, 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 den Wert ON hat, muss mindestens einer der letzten fünf scrollopt-Werte (KEYSET_ACCEPTABLE, DYNAMIC_ACCEPTABLE, FORWARD_ONLY_ACCEPTABLE, STATIC_ACCEPTABLE oder FAST_FORWARD_ACCEPTABLE) auch ON 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 ccopt-Werte (READ_ONLY, SCROLL_LOCKS und beide OPTIMISTIC-Werte) schließen sich gegenseitig aus.

HinweisHinweis

Durch Auswahl eines der ersten vier ccopt-Werte wird bestimmt, ob der Cursor schreibgeschützt ist oder ob LOCK- oder OPTIMISTIC-Methoden angewendet werden, um verloren gegangene Updates zu vermeiden. Wenn ein ccopt -Wert nicht angegeben wird, lautet der Standardwert OPTIMISTIC.

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 den Wert ON hat, muss mindestens einer der letzten vier ccopt-Werte (READ_ONLY_ACCEPTABLE, SCROLL_LOCKS_ACCEPTABLE und einer der OPTIMISTIC_ACCEPTABLE-Werte) auch ON sein.

Positionierte UPDATE- und DELETE-Funktionen dürfen nur innerhalb des Fetchpuffers und auch nur dann ausgeführt werden, wenn der ccopt-Wert SCROLL_LOCKS oder OPTIMISTIC entspricht. 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.

Die Fehlerursache liegt darin, dass bei Angabe des Werts OPTIMISTIC eine Funktion für die Steuerung durch vollständige Parallelität ausgeführt wird, indem entsprechend der Vorgabe in SQL Server Zeitstempel oder Prüfsummenwerte verglichen werden. 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

Entsprechend der Fehlermeldung im Code sollte der Parametername paramdef sein, wenn PARAMETERIZED_STMT angegeben ist. 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:

{ local variable name data type } [,…n]

Nachfolgende Parameter werden zur Übergabe der Werte verwendet, die in der Anweisung an die Stelle von local variable name gesetzt werden sollen.

Siehe auch

Verweis

sp_cursorfetch (Transact-SQL)

Gespeicherte Systemprozeduren (Transact-SQL)