sp_cursor (Transact-SQL)
Demande des mises à jour positionnées. Cette procédure effectue des opérations sur une ou plusieurs lignes dans le tampon d'extraction d'un curseur. sp_cursor est appelé en spécifiant ID = 1 dans un paquet TDS (Tabular Data Stream).
.gif "Icône Lien de rubrique")
Conventions de la syntaxe Transact-SQL
Syntaxe
sp_cursor cursor, optype, rownum, table
[ , value [...n] ] ]
Arguments
cursor
Handle de curseur. cursor est un paramètre obligatoire qui demande une valeur d'entrée int. cursor est la valeur de handle générée par SQL Server et retournée par la procédure sp_cursoropen.optype
Paramètre obligatoire qui désigne quelle opération le curseur effectuera. optype requiert l'une des valeurs d'entrée int suivantes.Valeur
Nom
Description
0X0001
UPDATE
Utilisée pour mettre à jour une ou plusieurs lignes dans le tampon d'extraction. Les lignes spécifiées dans rownum font l'objet d'un nouvel accès et sont mises à jour.
0x0002
DELETE
Utilisée pour supprimer une ou plusieurs lignes dans le tampon d'extraction. Les lignes spécifiées dans rownum font l'objet d'un nouvel accès et sont supprimées.
0X0004
INSERT
Insère des données sans générer une instruction SQL INSERT.
0X0008
REFRESH
Utilisée pour remplir la mémoire tampon à partir de tables sous-jacentes et peut être utilisée pour actualiser la ligne si une mise à jour ou une suppression échoue en raison d'un contrôle d'accès concurrentiel optimiste, ou après une opération UPDATE.
0X10
LOCK
Entraîne l'acquisition d'un verrou U-Lock SQL Server sur la page contenant la ligne spécifiée. Ce verrou est compatible avec les verrous S-Lock mais pas avec les verrous X-Lock ou autres verrous U-Lock. Permet d'implémenter le verrouillage à court terme.
0X20
SETPOSITION
Utilisée uniquement lorsque le programme va émettre une instruction SQL ServerDELETE ou UPDATE positionnée suivante.
0X40
ABSOLUTE
Peut uniquement être utilisée avec UPDATE ou DELETE. ABSOLUTE est utilisée uniquement avec les curseurs KEYSET (est ignorée pour les curseurs DYNAMIC et les curseurs STATIC ne peuvent pas être mis à jour).
.gif "Remarque")
Remarque
Si ABSOLUTE est spécifiée sur une ligne dans le jeu de clés qui n'a pas été extrait, l'opération peut entraîner l'échec du contrôle d'accès concurrentiel et le résultat obtenu ne peut pas être garanti.rownum
Spécifie les lignes dans le tampon d'extraction sur lesquelles le curseur interviendra, qu'il mettra à jour ou supprimera.[!REMARQUE]
Cela n'affecte pas le point de départ de toute opération d'extraction RELATIVE, NEXT ou PREVIOUS, ni les mises à jour ou suppressions effectuées à l'aide de sp_cursor.
rownum est un paramètre obligatoire qui demande une valeur d'entrée int.
1
Indique la première ligne dans le tampon d'extraction.2
Indique la deuxième ligne dans le tampon d'extraction.3, 4, 5
Indique la troisième ligne, etc.n
Indique la énième ligne dans le tampon d'extraction.0
Indique toutes les lignes dans le tampon d'extraction.[!REMARQUE]
Valide uniquement pour une utilisation avec les valeurs optype UPDATE, DELETE, REFRESH ou LOCK.
table
Nom de table qui identifie la table à laquelle optype s'applique lorsque la définition de curseur implique une jointure ou que des noms de colonnes ambigus sont retournés par le paramètre value. Si aucune table spécifique n'est désignée, la valeur par défaut est la première table dans la clause FROM. table est un paramètre optionnel qui requiert une valeur d'entrée de chaîne. La chaîne peut être spécifiée comme tout caractère ou type de données UNICODE. table peut être un nom de table en plusieurs parties.value
Permet d'insérer ou de mettre à jour des valeurs. Le paramètre de chaîne value est utilisé uniquement avec les valeurs optype UPDATE et INSERT. La chaîne peut être spécifiée comme tout caractère ou type de données UNICODE.[!REMARQUE]
Les noms de paramètres pour value peuvent être affectés par l'utilisateur.
Valeurs des codes de retour
Lors de l'utilisation d'un appel de procédure distante, une opération DELETE ou UPDATE positionnée avec le numéro de mémoire tampon 0 retournera un message DONE avec une valeur rowcount égale à 0 (échec) ou 1 (réussite) pour chaque ligne dans le tampon d'extraction.
Notes
Paramètre optype
À l'exception des combinaisons de SETPOSITION avec UPDATE, DELETE, REFRESH ou LOCK, ou d'ABSOLUTE avec UPDATE ou DELETE, les valeurs optype s'excluent mutuellement.
La clause SET de la valeur UPDATE est construite à partir du paramètre value.
Un avantage de l'utilisation de la valeur optype INSERT est que vous pouvez éviter de convertir des données non-caractères en format caractère pour les insertions. Les valeurs sont spécifiées de la même façon qu'UPDATE. Si une colonne requise n'est pas incluse, INSERT échoue.
- La valeur SETPOSITION n'affecte pas le point de départ de toute opération d'extraction RELATIVE, NEXT ou PREVIOUS, ni les mises à jour ou suppressions effectuées à l'aide de l'interface sp_cursor. Tout numéro qui ne spécifie pas de ligne dans le tampon d'extraction entraînera l'affectation de la valeur 1 à la position, sans aucune erreur retournée. Une fois SETPOSITION exécutée, la position reste effective jusqu'à l'opération sp_cursorfetch, T-SQL FETCH ou sp_cursor SETPOSITION suivante via le même curseur. Une opération sp_cursorfetch suivante définira la position du curseur sur la première ligne dans le nouveau tampon d'extraction alors que d'autres appels de curseur n'affecteront pas la valeur de la position. SETPOSITION peut être liée par une clause OR avec REFRESH, UPDATE, DELETE ou LOCK pour définir la valeur de la position sur la dernière ligne modifiée.
Si une ligne dans le tampon d'extraction n'est pas spécifiée via le paramètre rownum, la position aura la valeur 1, sans aucune erreur retournée. Une fois la position définie, elle reste effective jusqu'à l'exécution de l'opération sp_cursorfetch, T-SQL FETCH ou sp_cursor SETPOSITION suivante sur le même curseur.
SETPOSITION peut être liée par une clause OR avec REFRESH, UPDATE, DELETE ou LOCK pour définir la position du curseur sur la dernière ligne modifiée.
Paramètre rownum
S'il est spécifié, le paramètre rownum peut être interprété comme numéro de ligne dans le jeu de clés au lieu du numéro de ligne dans le tampon d'extraction. L'utilisateur est chargé de garantir que le contrôle d'accès concurrentiel est tenu à jour. Cela signifie que, pour les curseurs SCROLL_LOCKS, vous devez maintenir indépendamment un verrou sur la ligne donnée (cette opération peut être effectuée via une transaction). Pour les curseurs OPTIMISTIC, vous devez avoir au préalable extrait la ligne pour effectuer cette opération.
Paramètre table
Si la valeur optype est UPDATE ou INSERT et qu'une instruction de mise à jour ou d'insertion complète est envoyée en tant que paramètre value, la valeur spécifiée pour table est ignorée.
[!REMARQUE]
En ce qui concerne les vues, une seule table qui participe à la vue peut être modifiée. Les noms de colonnes du paramètre value doivent refléter ceux de la vue, mais le nom de la table peut être celui de la table de base sous-jacente (auquel cas sp_cursor remplacera le nom de la vue).
Paramètre value
Il existe deux alternatives aux règles d'utilisation de value comme énoncé plus haut dans la section Arguments :
Vous pouvez utiliser un nom auquel '@' a été ajouté au nom de la colonne dans la liste de sélection pour tous les paramètres value nommés. Un avantage de cette alternative est que la conversion des données peut ne pas être nécessaire.
Utilisez un paramètre pour envoyer une instruction UPDATE ou INSERT complète, ou utilisez plusieurs paramètres pour envoyer des parties d'une instruction UPDATE ou INSERT que SQL Server intégrera ensuite à une instruction complète. Vous trouverez des exemples dans la section Exemples plus loin dans cette rubrique.
Exemples
Autres utilisations de paramètres de valeurs
Pour UPDATE :
Lorsqu'un paramètre unique est utilisé, une instruction UPDATE peut être envoyée à l'aide de la syntaxe suivante :
[ [ UPDATE <table name> ] SET ] {<column name> = expression} [,…n]
[!REMARQUE]
Si UPDATE <table name> est spécifié, toute valeur spécifiée pour le paramètre table sera ignorée.
Lorsque plusieurs paramètres sont utilisés, le premier paramètre doit être une chaîne sous la forme suivante :
[ SET ] <column name> = expression [,... n]
et les paramètres suivants doivent être sous la forme :
<column name> = expression [,... n]
Dans ce cas, <table name> dans l'instruction de mise à jour construite est le nom spécifié ou défini par défaut par le paramètre table.
Pour INSERT :
Lorsqu'un paramètre unique est utilisé, une instruction INSERT peut être envoyée à l'aide de la syntaxe suivante :
[ [ INSERT [INTO] <table name> ] VALUES ] ( <expression> [,... n] )
[!REMARQUE]
Si INSERT <table name> est spécifié, toute valeur spécifiée pour le paramètre table sera ignorée.
Lorsque plusieurs paramètres sont utilisés, le premier paramètre doit être une chaîne sous la forme suivante :
[ VALUES ( ] <expression> [,... n]
et les paramètres suivants doivent être sous la forme :
expression [,... n]
sauf lorsque VALUES a été spécifié, auquel cas une « ) » de fin est nécessaire après la dernière expression. Dans ce cas, <table name> dans l'instruction UDPATE construite est le nom spécifié ou défini par défaut par le paramètre table.
[!REMARQUE]
Il est possible d'envoyer un paramètre comme paramètre nommé, c'est-à-dire « @VALUES ». Dans ce cas, aucun autre paramètre nommé ne peut être utilisé.