sp_cursoropen (Transact-SQL)

  • Articolo

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 Transact-SQL DECLARE_CURSOR e OPEN. Questa routine viene richiamata specificando ID = 2 in un pacchetto del flusso TDS.

Convenzioni di 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 valore di handle che deve essere fornito in tutte le procedure successive che coinvolgono il cursore, ad esempio sp_cursorfetch. cursor è un parametro obbligatorio con un valore restituito int .

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. scrollopt è un parametro facoltativo che richiede uno dei valori di input int 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 (precedentemente noto come LOCKCC)
0x0004 OPTIMISTIC (noto in precedenza come OPTCC)
0x0008 OPTIMISTIC (precedentemente noto 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.

Rowcount
Numero di righe del buffer di recupero da utilizzare 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, il conteggio delle righe rappresenta il numero di righe da inserire nel buffer di recupero.

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

-

boundparam
Indica l'utilizzo 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.

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
È in corso l'elaborazione di un'operazione FETCH.

Un
Questo cursore è stato deallocato da SQL Server e non è disponibile.

Quando viene generato un errore, è possibile che i valori restituiti siano incoerenti. L'accuratezza non può pertanto essere garantita.

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

-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 scrollopt AUTO_FETCH.

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

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 rapido è stato chiuso automaticamente.

Nota

Se la procedura di sp_cursoropen viene eseguita correttamente, vengono inviati i parametri restituiti RPC e un set di risultati con informazioni sul formato di colonna TDS (0xa0 e messaggi 0xa1). Se non riesce, vengono inviati uno o più messaggi di errore TDS. In entrambi i casi, non verranno restituiti dati di riga e il conteggio dei messaggi completato sarà zero. Se si usa una versione di SQL Server precedente alla 7.0, 0xa0, 0xa1 (standard per le istruzioni edizione Standard LECT) vengono restituiti insieme a flussi di token 0xa5 e 0xa4. Se si usa SQL Server 7.0, 0x81 viene restituito (standard per le istruzioni edizione Standard LECT) insieme ai flussi di token 0xa5 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 ALLOW_DIRECT ccopt sia stato collegato da OR al resto dei valori ccopt , ad esempio:

  • Se ALLOW_DIRECT non viene specificato, è necessario utilizzare un'istruzione Transact-SQL edizione Standard LECT o EXECUTE che chiama per una stored procedure contenente una singola istruzione edizione Standard LECT. Inoltre, l'istruzione edizione Standard LECT deve essere qualificata come cursore, ovvero non può contenere le parole chiave edizione Standard LECT INTO o FOR BROW edizione Standard.

  • Se si specifica ALLOW_DIRECT, ciò può comportare una o più istruzioni Transact-SQL, incluse quelle che, a sua volta, eseguono altre stored procedure con più istruzioni. Le istruzioni non SELECT o qualsiasi istruzione SELECT che contenga le parole chiave SELECT INTO o FOR BROWSE verranno semplicemente eseguite e non comporteranno la creazione di un cursore. Questo vale per qualsiasi istruzione SELECT inclusa in un batch di più istruzioni. Nei casi in cui un'istruzione SELECT contiene clausole che riguardano solo i cursori, tali clausole vengono ignorate. Ad esempio, quando il valore di ccopt è 0x2002, si tratta di una richiesta per:

    • Un cursore con blocchi di scorrimento, se una sola istruzione SELECT è qualificata come cursore oppure

    • Un'esecuzione diretta di istruzioni in caso di presenza di più istruzioni, di una sola istruzione non SELECT o di un'istruzione SELECT non qualificata come cursore.

Parametro scrollopt

I primi cinque valori di scorrimento (KEY edizione Standard Y, DYNAMIC, FORWARD_ONLY, STATIC e FAST_FORWARD) si escludono a vicenda.

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

AUTO_FETCH e AUTO_CLOSE possono essere collegati tramite OR a FAST_FORWARD.

Se CHECK_ACCEPTED_TYPES è ATTIVATO, deve essere attivato almeno uno degli ultimi cinque valori di scorrimento (KEY edizione StandardT_ACCEPTABLE, DYNAMIC_ACCEPTABLE, FORWARD_ONLY_ACCEPTABLE, STATIC_ACCEPTABLE o FAST_FORWARD_ACCEPTABLE).

I cursori STATIC sono sempre aperti come READ_ONLY. Ciò significa che non è possibile aggiornare la tabella sottostante tramite questo cursore.

Parametro ccopt

I primi quattro valori ccopt (READ_ONLY, SCROLL_LOCKS e entrambi i valori OTTIMISTICI) 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 tramite OR a uno dei primi quattro valori.

UPDT_IN_PLACE può essere collegato tramite OR a READ_ONLY, SCROLL_LOCKS o a uno dei valori OPTIMISTIC.

Se CHECK_ACCEPTED_TYPES è ON, almeno uno degli ultimi quattro valori ccopt (READ_ONLY_ACCEPTABLE, SCROLL_LOCKS_ACCEPTABLE e uno dei valori di OPTIMISTIC_ACCEPTABLE) deve essere attivato.

Le funzioni UPDATE e DELETE posizionate possono essere eseguite solo all'interno del buffer di recupero e solo se il valore ccopt è uguale a SCROLL_LOCKS o OTTIMISTICA. Se SCROLL_LOCKS è il valore specificato, la riuscita dell'operazione è garantita. Se OPTIMISTIC è il valore specificato, l'operazione non riuscirà se la riga è stata modificata successivamente all'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 delle righe non corrisponde, l'operazione non riesce.

Specificando UPDT_IN_PLACE come valore restituito, si ottengono i risultati seguenti:

  • Se non viene impostato durante l'esecuzione di un aggiornamento posizionato in una tabella con un indice univoco, il cursore elimina la riga dalla rispettiva tabella di lavoro e la inserisce alla fine di una delle colonne chiave utilizzate dal cursore, modificando in questo modo le colonne.

  • Se impostato su ON, il cursore semplicemente aggiornerà le colonne chiave nella riga originale della tabella di lavoro.

Parametro bound_param

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

Considerazioni su RPC

Per richiedere che vengano restituiti metadati sull'elenco di selezione del cursore nel flusso TDS, è possibile impostare il flag di input RPC RETURN_METADATA su 0x0001.

Esempi

Parametro bound_param

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

{ tipo di dati nome variabile locale } [,... n]

I parametri successivi vengono usati per passare i valori da sostituire con il nome della variabile locale nell'istruzione .

Vedi anche

sp_cursorfetch (Transact-SQL)
Stored procedure di sistema (Transact-SQL)