sp_cursor (Transact-SQL)

  • Article

S’applique à :SQL Server

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).
S’applique à : SQL Server (de SQL Server 2008 (10.0.x) à la version actuelle).

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 appelle 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 nécessite 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 sont ré-consultées et mises à jour.
0x0002 Suppression Utilisée pour supprimer une ou plusieurs lignes dans le tampon d'extraction. Les lignes spécifiées dans rownum sont à nouveau consultées et supprimées.
0X0004 INSERT Insère des données sans générer d’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 SQL Server U-Lock 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 Est utilisé uniquement lorsque le programme va émettre une instruction DELETE ou UPDATE SQL Server suivante positionnée.
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).

Remarque : si ABSOLUTE est spécifié sur une ligne du jeu de clés qui n’a pas été extrait, l’opération peut échouer à la vérification d’accès concurrentiel et le résultat du retour 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.

Notes

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

Notes

Est valide uniquement pour une utilisation avec les valeurs d’optype UPDATE, DELETE, REFRESH ou LOCK.

table
Nom de la table qui identifie la table à laquelle s’applique optype lorsque la définition du curseur implique une jointure ou 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 facultatif qui nécessite une valeur d’entrée String. 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 de valeur 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.

Notes

Les noms de paramètres de valeur peuvent être attribués par l’utilisateur.

Codet de retour

Lors de l’utilisation d’un RPC, une opération DELETE ou UPDATE positionnée avec un numéro de mémoire tampon 0 retourne un message DONE avec un nombre de lignes de 0 (échec) ou 1 (réussite) pour chaque ligne de la mémoire tampon d’extraction.

Remarques

Paramètre optype

À l’exception des combinaisons de SETPOSITION avec UPDATE, DELETE, REFRESH ou LOCK ; ou 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 .

L’un des avantages de l’utilisation de la valeur d’optype INSERT est que vous pouvez éviter de convertir des données autres que des caractères en format de caractères 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é, la position reste en vigueur jusqu’à l’opération de sp_cursorfetch suivante, l’opération T-SQL FETCH ou sp_cursor opération SETPOSITION 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 la mémoire tampon de récupération n’est pas spécifiée via le paramètre rownum , la position est définie sur 1, sans 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 le numéro de ligne dans le jeu de clés au lieu du numéro de ligne dans la mémoire 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.

Notes

En ce qui concerne les vues, une seule table qui participe à la vue peut être modifiée. Les noms de colonnes des paramètres de valeur doivent refléter les noms des colonnes dans 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 la valeur , comme indiqué précédemment dans la section Arguments :

  1. Vous pouvez utiliser un nom qui est « @ » pré-suspendu au nom de la colonne dans la liste de sélection pour tous les paramètres de valeur nommée. Un avantage de cette alternative est que la conversion des données peut ne pas être nécessaire.

  2. Utilisez un paramètre pour envoyer une instruction UPDATE ou INSERT complète ou utiliser plusieurs paramètres pour envoyer des parties d’une instruction UPDATE ou INSERT qui SQL Server sera ensuite intégrée dans 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]

Notes

Si le nom> de la table UPDATE <est spécifié, toute valeur spécifiée pour le paramètre de table est 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, le nom> de la <table dans l’instruction de mise à jour construite est celui 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] )

Notes

Si le nom> de la table INSERT< est spécifié, toute valeur spécifiée pour le paramètre de table est 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, le nom> de la< table dans l’instruction UPDATE construite est celui spécifié ou défini par défaut par le paramètre table.

Notes

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

Voir aussi

sp_cursoropen (Transact-SQL)
sp_cursorfetch (Transact-SQL)
Procédures stockées système (Transact-SQL)