sp_cursoropen (Transact-SQL)
Apre un cursore. sp_cursoropen definisce l'istruzione SQL associata al cursore e alle opzioni del cursore, quindi popola il cursore. sp_cursoropen è equivalente alla combinazione delle istruzioni Transact-SQL DECLARE_CURSOR e OPEN. Questa routine viene richiamata specificando ID = 2 in un pacchetto del flusso TDS.
.gif "Icona di collegamento a un argomento")
Convenzioni della 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 routine successive che comportano l'uso del cursore, ad esempio sp_cursorfetch. cursor è un parametro obbligatorio con valore restituito int.cursor consente a più cursori di essere attivi in un'unica 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 (indipendentemente da Unicode, dimensione e così via) può essere un 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
Il valore richiesto potrebbe non essere appropriato per il cursore definito da stmt, pertanto questo parametro funge sia da input sia da output. In questi casi, SQL Server assegna un valore appropriato.
ccopt
Opzione di 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 (precedentemente noto 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 accade per scrollopt, in SQL Server è possibile eseguire l'override dei valori di 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 viene assegnato come valore di input rispetto a quando viene assegnato come valore restituito.Come valore di input
Come valore restituito
Quando viene specificato il valore AUTO_FETCH per scrollopt, rowcount rappresenta il numero di righe da inserire nel buffer di recupero.
[!NOTA]
>0 è un valore valido se viene specificato AUTO_FETCH. In caso contrario, viene ignorato.
Rappresenta il numero di righe nel set di risultati, tranne quando viene specificato il valore AUTO_FETCH per scrollopt.
boundparam
Indica l'utilizzo di parametri aggiuntivi. boundparam è un parametro facoltativo che deve essere specificato se il valore PARAMETERIZED_STMT di scrollopt è impostato su ON.
Valori di codice restituiti
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 come valore restituito viene specificato il parametro rowcount, si ottiene 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. Quando viene specificato il valore AUTO_FETCH per scrollopt, rappresenta il numero di righe inserite nel buffer di recupero.
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 routine sp_cursoropen viene eseguita correttamente, vengono inviati i parametri restituiti RPC e un set di risultati con informazioni sul formato di colonna TDS (messaggi 0xa0 e 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 del messaggio done sarà zero. Se si utilizza una versione di SQL Server precedente a 7.0, vengono restituiti i messaggi 0xa0, 0xa1 (standard per le istruzioni SELECT) insieme ai flussi di token 0xa5 e 0xa4. Se si utilizza SQL Server 7.0, viene restituito 0x81 (standard per le istruzioni SELECT) insieme ai flussi di token 0xa5 e 0xa4.
Osservazioni
Parametro stmt
Se stmt specifica l'esecuzione di una stored procedure, è possibile che i parametri di input siano definiti come costanti come parte della stringa stmt oppure specificati come argomenti boundparam. È possibile passare variabili dichiarate come parametri associati in questo modo.
Il contenuto consentito del parametro stmt dipende dall'eventuale collegamento del valore restituito ALLOW_DIRECT di ccopt tramite OR al resto dei valori di ccopt, ovvero:
Se non è specificato ALLOW_DIRECT, è necessario utilizzare un'istruzione Transact-SQL SELECT o EXECUTE che chiama una stored procedure contenente una sola 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, è possibile che vengano eseguite una o più istruzioni Transact-SQL, incluse quelle che, a loro 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. Quando ad esempio 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 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, è necessario che sia ON almeno uno degli ultimi cinque valori di scrollopt (KEYSET_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 di ccopt (READ_ONLY, SCROLL_LOCKS ed entrambi i valori OPTIMISTIC) si escludono a vicenda.
[!NOTA]
Il valore scelto tra i primi quattro valori di ccopt determina l'impostazione del cursore come di sola lettura o l'utilizzo dei metodi di blocco o ottimistici per impedire la perdita di aggiornamenti. Se per ccopt non viene specificato alcun valore, 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, è necessario che sia ON almeno uno degli ultimi quattro valori di ccopt (READ_ONLY_ACCEPTABLE, SCROLL_LOCKS_ACCEPTABLE e uno dei valori OPTIMISTIC_ACCEPTABLE).
Le funzioni UPDATE e DELETE posizionate possono essere eseguite solo all'interno del buffer di recupero e solo se il valore di ccopt è uguale a SCROLL_LOCKS o OPTIMISTIC. 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 il valore specificato è OPTIMISTIC, viene eseguita una funzione di controllo della concorrenza ottimistica mediante il confronto di timestamp o 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:
{ local variable name data type } [,…n]
I parametri successivi vengono utilizzati per passare i valori da sostituire per local variable name nell'istruzione.