sp_cursoropen (Transact-SQL)

Si applica a: SQL Server

Apre un cursore. sp_cursoropen definisce l'istruzione SQL associata alle opzioni del cursore e del cursore e quindi popola il cursore. sp_cursoropen equivale alla combinazione delle istruzioni DECLARE_CURSOR Transact-SQL e OPEN. Questa procedura viene richiamata specificando ID = 2 in un pacchetto TDS (Tabular Data Stream).

Convenzioni relative alla sintassi Transact-SQL

Sintassi

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

Argomenti

cursor

Identificatore del cursore generato da SQL Server. cursor è un handle valore che deve essere fornito in tutte le procedure successive che coinvolgono il cursore, ad esempio sp_cursorfetch. Il parametro del cursore è int e non può essere NULL.

cursore consente di attivare più cursori in una singola connessione di database.

stmt

Parametro obbligatorio che definisce il set di risultati del cursore. Qualsiasi stringa di query valida (sintassi e associazione) di qualsiasi tipo stringa (indipendentemente da Unicode, dimensioni e così via) può fungere da tipo di valore stmt valido.

scrollopt

Opzione di scorrimento. Il parametro scrollopt è int, con un valore predefinito , NULLe può essere uno dei valori seguenti.

valore Descrizione
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

A causa della possibilità che il valore richiesto non sia appropriato per il cursore definito da stmt, questo parametro funge sia da input che da output. In questi casi, SQL Server assegna un valore appropriato.

ccopt

Opzioni del controllo della concorrenza. ccopt è un parametro facoltativo che richiede uno dei valori di input int seguenti.

valore Descrizione
0x0001 READ_ONLY
0x0002 SCROLL_LOCKS (noto in precedenza come LOCKCC)
0x0004 OPTIMISTIC (noto in precedenza come OPTCC)
0x0008 OPTIMISTIC (noto in precedenza come 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

Come con scrollopt, SQL Server può eseguire l'override dei valori ccopt richiesti.

conteggio righe

Numero di righe del buffer di recupero da usare con AUTO_FETCH. Il valore predefinito è 20 righe. rowcount si comporta in modo diverso quando assegnato come valore di input rispetto a un valore restituito.

Come valore di input Come valore restituito
Quando viene specificato il AUTO_FETCH valore scrollopt , rowcount rappresenta il numero di righe da inserire nel buffer di recupero.

Nota: > 0 è un valore valido quando AUTO_FETCH viene specificato, ma viene altrimenti ignorato.
Rappresenta il numero di righe nel set di risultati, tranne quando viene specificato il valore scrolloptAUTO_FETCH.

boundparam

Indica l'uso di parametri aggiuntivi. boundparam è un parametro facoltativo che deve essere specificato se il valore scrollopt PARAMETERIZED_STMT è impostato su ON.

Valori del codice restituito

Se non viene generato alcun errore, sp_cursoropen restituisce uno dei valori seguenti.

valore Descrizione
0 La routine è stata effettuata correttamente.
0x0001 Si verificato un errore durante l'esecuzione (un errore minore, non abbastanza grave da compromettere l'operazione).
0x0002 È in corso un'operazione asincrona.
0x0002 Un'operazione FETCH è in corso.
A Questo cursore è stato deallocato e non è disponibile.

Quando viene generato un errore, i valori restituiti potrebbero non essere coerenti e l'accuratezza non può essere garantita.

Quando il parametro rowcount viene specificato come valore restituito, si verifica il set di risultati seguente.

valore Descrizione
-1 Valore restituito se il numero di righe è sconosciuto o non applicabile.
-n Valore restituito quando un popolamento asincrono è attivo. Rappresenta il numero di righe inserite nel buffer di recupero quando viene specificato il valore scrolloptAUTO_FETCH.

Se RPC è in uso, i valori restituiti sono come segue.

valore Descrizione
0 La routine è stata eseguita correttamente.
1 La routine non è riuscita.
2 È in corso la generazione asincrona di un cursore keyset.
16 Un cursore di avanzamento è stato chiuso automaticamente.

Se la sp_cursoropen procedura viene eseguita correttamente, vengono inviati i parametri restituiti RPC e un set di risultati con informazioni sul formato di colonna TDS (0xa0 e 0xa1 messaggi). Se non riesce, vengono inviati uno o più messaggi di errore TDS. In entrambi i casi, non vengono restituiti dati di riga e il conteggio dei DONE messaggi è 0. 0x81 viene restituito (standard per SELECT le istruzioni) insieme ai 0xa5 flussi di token e 0xa4 .

Osservazioni:

Parametro stmt

Se stmt specifica l'esecuzione di una stored procedure, i parametri di input possono essere definiti come costanti come parte della stringa stmt o specificati come argomenti boundparam . È possibile passare variabili dichiarate come parametri associati in questo modo.

Il contenuto consentito del parametro stmt dipende dal fatto che il valore restituito ccopt ALLOW_DIRECT sia stato collegato al OR resto dei valori ccopt :

  • Se ALLOW_DIRECT non viene specificato, è necessario usare un'istruzione Transact-SQL SELECT o EXECUTE una chiamata per una stored procedure contenente una singola SELECT istruzione. Inoltre, l'istruzione SELECT deve essere qualificata come cursore, ovvero non può contenere le parole chiave SELECT INTO o FOR BROWSE.

  • Se ALLOW_DIRECT viene specificato , questo potrebbe comportare una o più istruzioni Transact-SQL, incluse le istruzioni che eseguono altre stored procedure con più istruzioni. SELECT Istruzioni non o istruzioni SELECT che contengono le parole chiave SELECT INTO o FOR BROWSE vengono eseguite e non comportano la creazione di un cursore. Lo stesso vale per qualsiasi SELECT istruzione inclusa in un batch di più istruzioni. Nei casi in cui un'istruzione SELECT contiene clausole relative solo ai cursori, tali clausole vengono ignorate. Ad esempio, quando il valore di ccopt è 0x2002, si tratta di una richiesta per:

    • Cursore con blocchi di scorrimento, se è presente una sola SELECT istruzione che qualifica come cursore o

    • Esecuzione di istruzioni dirette se sono presenti più istruzioni, una singolaSELECT istruzione non o un'istruzione SELECT che non è idonea come cursore.

Parametro scrollopt

I primi cinque valori scrollopt (KEYSEY, DYNAMIC, FORWARD_ONLYSTATIC, e FAST_FORWARD) si escludono a vicenda.

PARAMETERIZED_STMT e CHECK_ACCEPTED_TYPES possono essere collegati da OR a uno dei primi cinque valori.

AUTO_FETCH e AUTO_CLOSE può essere collegato da OR a FAST_FORWARD.

Se CHECK_ACCEPTED_TYPES è ON, almeno uno degli ultimi cinque valori scrollopt (KEYSET_ACCEPTABLE, DYNAMIC_ACCEPTABLE, FORWARD_ONLY_ACCEPTABLESTATIC_ACCEPTABLE, o FAST_FORWARD_ACCEPTABLE) deve essere ONanche .

STATIC i cursori vengono sempre aperti come READ_ONLY. Ciò significa che la tabella sottostante non può essere aggiornata tramite questo cursore.

Parametro ccopt

I primi quattro valori ccopt (READ_ONLY, SCROLL_LOCKSe entrambi i OPTIMISTIC valori) si escludono a vicenda.

Nota

La scelta di uno dei primi quattro valori ccopt determina se il cursore è di sola lettura o se vengono utilizzati metodi di blocco o ottimistica per evitare aggiornamenti persi. Se non viene specificato un valore ccopt , il valore predefinito è OPTIMISTIC.

ALLOW_DIRECT e CHECK_ACCEPTED_TYPES possono essere collegati da OR a uno dei primi quattro valori.

UPDT_IN_PLACE può essere collegato da OR a READ_ONLY, SCROLL_LOCKSo da uno dei OPTIMISTIC valori .

Se CHECK_ACCEPTED_TYPES è ON, almeno uno degli ultimi quattro valori ccopt (READ_ONLY_ACCEPTABLE, SCROLL_LOCKS_ACCEPTABLEe uno dei OPTIMISTIC_ACCEPTABLE valori ) deve essere on.

Le funzioni e DELETE posizionate UPDATE possono essere eseguite solo all'interno del buffer di recupero e solo se il valore ccopt è uguale SCROLL_LOCKS a o OPTIMISTIC. Se SCROLL_LOCKS è il valore specificato, l'operazione avrà esito positivo. Se OPTIMISTIC è il valore specificato, l'operazione ha esito negativo se la riga è stata modificata dopo l'ultimo recupero.

Il motivo di questo errore è che quando OPTIMISTIC è il valore specificato, viene eseguita una funzione di controllo valuta ottimistica confrontando i timestamp o i valori di checksum, come determinato da SQL Server. Se una di queste righe non corrisponde, l'operazione non riesce.

UPDT_IN_PLACE Se si specifica come valore restituito, vengono regolati i risultati seguenti:

  • Se non viene impostato quando si esegue un aggiornamento posizionato in una tabella con un indice univoco, il cursore elimina la riga dalla tabella di lavoro e la inserisce alla fine di una delle colonne chiave utilizzate dal cursore, che modifica tali colonne.

  • Se impostata ON, il cursore aggiorna le colonne chiave nella riga originale della tabella di lavoro.

Parametro bound_param

Il nome del parametro deve essere paramdef quando PARAMETERIZED_STMT viene specificato, in base al messaggio di errore nel codice. Quando PARAMETERIZED_STMT non viene specificato, non viene specificato alcun nome nel messaggio di errore.

Considerazioni su RPC

Il flag di input RPC RETURN_METADATA può essere impostato su 0x0001 per richiedere che i metadati dell'elenco di selezione cursore vengano restituiti nel flusso TDS.

Esempi

R. Parametro bound_param

I parametri dopo il quinto vengono passati insieme sul piano dell'istruzione come parametri di input. Il primo parametro deve essere una stringa nel formato seguente:

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

I parametri successivi vengono usati per passare i valori da sostituire con nell'istruzione <parameter_name> .