sp_cursoropen (Transact-SQL)

Si applica a:SQL Server

Apre un cursore. sp_cursoropen definisce l'istruzione SQL associata alle opzioni cursore e 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 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 restituitoint.

cursore consente a più cursori di essere attivi 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 di 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	OTTIMISTICA (nota 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 per 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 valore di scrollopt AUTO_FETCH rappresenta il numero di righe da inserire nel buffer di recupero. Nota: >0 è un valore valido quando viene specificato AUTO_FETCH, ma viene altrimenti 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.

A
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 messaggi di 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 versione 7.0, 0xa0, 0xa1 (standard per le istruzioni SELECT) vengono restituiti insieme a flussi di token 0xa5 e 0xa4. Se si usa SQL Server 7.0, 0x81 viene restituito (standard per le istruzioni SELECT) insieme ai flussi di token 0xa5 e 0xa4.

Commenti

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 è specificato, è necessario usare un'istruzione Transact-SQL SELECT o EXECUTE per una stored procedure contenente un'unica istruzione SELECT. L'istruzione SELECT deve inoltre essere qualificata come cursore, ovvero non può contenere le parole chiave SELECT INTO o FOR BROWSE.

• Se viene specificato ALLOW_DIRECT, questo 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 scrollopt (KEYSEY, 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 è ON, almeno uno dei cinque valori scrollopt (KEYSET_ACCEPTABLE, DYNAMIC_ACCEPTABLE, FORWARD_ONLY_ACCEPTABLE, STATIC_ACCEPTABLE o FAST_FORWARD_ACCEPTABLE) deve anche essere ON.

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 reciprocamente.

Nota

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

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 ON.

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 OTTIMISTICA è il valore specificato, viene eseguita una funzione di controllo valuta ottimistica confrontando i valori timestamp o 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.

Esempio

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 per il nome della variabile locale nell'istruzione .

Vedere anche

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