sp_cursor (Transact-SQL)
Richiede aggiornamenti posizionati. Con questa routine è possibile effettuare operazioni in una o più righe all'interno del buffer di recupero di un cursore. sp_cursor viene richiamata specificando ID = 1 in un pacchetto del flusso TDS.
.gif "Icona di collegamento a un argomento")
Convenzioni della sintassi Transact-SQL
Sintassi
sp_cursor cursor, optype, rownum, table
[ , value [...n] ] ]
Argomenti
cursor
Handle del cursore. cursor è un parametro obbligatorio che richiede un valore di input int. cursor è il valore handle generato da SQL Server e restituito dalla routine sp_cursoropen.optype
Parametro obbligatorio che definisce l'operazione che verrà effettuata dal cursore. optype richiede uno dei valori di input int seguenti.Valore
Nome
Descrizione
0X0001
UPDATE
Consente di aggiornare una o più righe nel buffer di recupero. Si accede nuovamente alle righe specificate in rownum che vengono quindi aggiornate.
0x0002
DELETE
Consente di eliminare una o più righe nel buffer di recupero. Si accede nuovamente alle righe specificate in rownum che vengono quindi eliminate.
0X0004
INSERT
Inserisce dati senza compilare un'istruzione SQL INSERT.
0X0008
REFRESH
Consente di inserire nuovamente dati nel buffer dalle tabelle sottostanti e può essere utilizzato per aggiornare la riga nel caso in cui un aggiornamento o un'eliminazione non riesca a causa del controllo della concorrenza ottimistica oppure dopo un'operazione UPDATE.
0X10
LOCK
Determina l'acquisizione di un blocco U di SQL Server nella pagina che contiene la riga specificata. Tale blocco è compatibile con i blocchi S ma non con i blocchi X o con altri blocchi U. Può essere utilizzato per implementare la funzione di blocco a breve termine.
0X20
SETPOSITION
Viene utilizzato solo quando il programma sta per eseguire la successiva istruzione DELETE o UPDATE posizionata da SQL Server.
0X40
ABSOLUTE
Può essere utilizzato solo insieme ad UPDATE o DELETE. ABSOLUTE viene utilizzato solo con i cursori KEYSET, viene ignorato per i cursori DYNAMIC e i cursori STATIC non possono essere aggiornati.
[!NOTA]
Se ABSOLUTE viene specificato in una riga nel keyset che non è stata recuperata, è possibile che l'operazione non riesca a eseguire il controllo della concorrenza. Il risultato restituito non può pertanto essere garantito.
rownum
Specifica le righe del buffer di recupero che verranno utilizzate, aggiornate o eliminate mediante il cursore.[!NOTA]
Non influisce sul punto di partenza di qualsiasi operazione di recupero RELATIVE, NEXT o PREVIOUS, né su aggiornamenti o eliminazioni effettuati utilizzando sp_cursor.
rownum è un parametro obbligatorio che richiede un valore di input int.
1
Indica la prima riga del buffer di recupero.2
Indica la seconda riga del buffer di recupero.3, 4, 5
Indica la terza riga e così via.n
Indica l'ennesima riga del buffer di recupero.0
Indica tutte le righe del buffer di recupero.[!NOTA]
È valido solo per l'utilizzo con i valori UPDATE, DELETE, REFRESH o LOCK di optype.
table
Nome di tabella che identifica la tabella alla quale si applica optype quando la definizione del cursore comporta un join o vengono restituiti nomi di colonna ambigui dal parametro value. Se non è definita una tabella specifica, l'impostazione predefinita è la prima tabella nella clausola FROM. table è un parametro facoltativo che richiede un valore di input stringa. È possibile specificare la stringa come qualsiasi tipo di dati UNICODE o carattere. table può essere un nome di tabella in più parti.value
Utilizzato per inserire o aggiornare valori. Il parametro di stringa value viene utilizzato solo con i valori UPDATE e INSERT di optype. È possibile specificare la stringa come qualsiasi tipo di dati UNICODE o carattere.[!NOTA]
I nomi di parametro per value possono essere assegnati dall'utente.
Valori di codice restituiti
In caso di utilizzo di un RPC, un'operazione DELETE o UPDATE posizionata con un numero di buffer 0 restituirà un messaggio DONE con un valore rowcount pari a 0 (errore) o 1 (riuscito) per ogni riga nel buffer di recupero.
Osservazioni
Parametro optype
Fatta eccezione per le combinazioni di SETPOSITION con UPDATE, DELETE, REFRESH o LOCK oppure di ABSOLUTE con UPDATE o DELETE, i valori di optype si escludono a vicenda.
La clausola SET del valore UPDATE viene costruita dal parametro value.
Un vantaggio dell'utilizzo del valore INSERT per optype consiste nella possibilità di evitare la conversione dei dati non costituiti da caratteri in formato carattere per consentire gli inserimenti. I valori vengono specificati con le stesse modalità di UPDATE. Se non sono incluse colonne obbligatorie, l'operazione INSERT non riesce.
- Il valore SETPOSITION non influisce sul punto di partenza di qualsiasi operazione di recupero RELATIVE, NEXT o PREVIOUS, né su eliminazioni o aggiornamenti effettuati utilizzando l'interfaccia di sp_cursor. Qualsiasi numero che non specifichi una riga nel buffer di recupero comporterà l'impostazione della posizione su 1 senza restituzione di errori. Dopo l'esecuzione di SETPOSITION, la posizione rimane attiva fino alla successiva operazione sp_cursorfetch, FETCH T-SQL o SETPOSITION di sp_cursor tramite lo stesso cursore. Un'operazione sp_cursorfetch successiva imposterà la posizione del cursore sulla prima riga nel nuovo buffer di recupero, mentre le altre chiamate del cursore non influiranno sul valore della posizione. SETPOSITION può essere collegato da una clausola OR con REFRESH, UPDATE, DELETE o LOCK allo scopo di impostare il valore della posizione sull'ultima riga modificata.
Se non viene specificata una riga nel buffer di recupero mediante il parametro rownum la posizione verrà impostata su 1, senza restituzione di errori. Dopo l'impostazione, la posizione rimane attiva finché non verrà eseguita sullo stesso cursore la successiva operazione sp_cursorfetch, T-SQL FETCH o SETPOSITION di sp_cursor.
SETPOSITION può essere collegato da una clausola OR con REFRESH, UPDATE, DELETE o LOCK allo scopo di impostare la posizione del cursore sull'ultima riga modificata.
Parametro rownum
Se viene specificato, il parametro rownum può essere interpretato come numero di riga all'interno del keyset anziché come numero di riga all'interno del buffer di recupero. È responsabilità dell'utente garantire la gestione del controllo della concorrenza. Ciò significa che per i cursori SCROLL_LOCKS è necessario gestire indipendentemente un blocco nella riga specificata. Questa operazione può essere eseguita tramite una transazione. Per eseguire questa operazione con i cursori OPTIMISTIC, è necessario avere recuperato la riga precedentemente.
Parametro table
Se il valore di optype è UPDATE o INSERT e come parametro value viene inviata un'istruzione completa di aggiornamento o inserimento, il valore specificato per table viene ignorato.
[!NOTA]
È possibile modificare una sola tabella che partecipa a una vista. I nomi di colonna del parametro value devono riflettere i nomi di colonna della vista, tuttavia il nome di tabella può essere quello della tabella di base sottostante. In questo caso sp_cursor sostituirà il nome della vista.
Parametro value
Come accennato precedentemente nella sezione Argomenti, esistono due alternative alle regole per l'utilizzo del parametro value:
È possibile utilizzare un nome con il simbolo "@" anteposto al nome della colonna nell'elenco di selezione per qualsiasi parametro value denominato. Un vantaggio di questa alternativa consiste nella possibilità che la conversione di dati non sia necessaria.
È possibile utilizzare un parametro per inviare un'istruzione UPDATE o INSERT completa oppure più parametri per inviare parti di un'istruzione UPDATE o INSERT che in SQL Server verranno compilate in un'istruzione completa. È possibile trovare alcuni esempi nella sezione Esempi più avanti in questo argomento.
Esempi
Utilizzi alternativi del parametro value
Per UPDATE:
Quando viene utilizzato un solo parametro, si potrebbe inviare un'istruzione UPDATE utilizzando la sintassi seguente:
[ [ UPDATE <table name> ] SET ] {<column name> = expression} [,…n]
[!NOTA]
Se viene specificato UPDATE <table name>, qualsiasi valore specificato per il parametro table verrà ignorato.
Quando vengono utilizzati più parametri, il primo parametro deve essere una stringa nel formato seguente:
[ SET ] <column name> = expression [,... n]
e i parametri successivi devono essere nel formato:
<column name> = expression [,... n]
In questo caso, <table name> nell'istruzione di aggiornamento costruita è il valore specificato o impostato come valore predefinito dal parametro table.
Per INSERT:
Quando viene utilizzato un solo parametro, si potrebbe inviare un'istruzione INSERT utilizzando la sintassi seguente:
[ [ INSERT [INTO] <table name> ] VALUES ] ( <expression> [,... n] )
[!NOTA]
Se viene specificato INSERT <table name>, qualsiasi valore specificato per il parametro table verrà ignorato.
Quando vengono utilizzati più parametri, il primo parametro deve essere una stringa nel formato seguente:
[ VALUES ( ] <expression> [,... n]
e i parametri successivi devono essere nel formato:
expression [,... n]
ad eccezione dei casi in cui è stato specificato VALUES. In questo caso, l'ultima espressione deve essere seguita da una parentesi finale ")". In questo caso, <table name> nell'istruzione UPDATE costruita è il valore specificato o impostato come valore predefinito dal parametro table.
[!NOTA]
È possibile inviare un parametro come parametro denominato, ad esempio " @VALUES". In questo caso è possibile non utilizzare altri parametri denominati.