sp_cursoropen (Transact-SQL)
Ouvre un curseur. sp_cursoropen définit l'instruction SQL associée au curseur et à ses options, puis remplit le curseur. sp_cursoropen est équivalent à la combinaison d'instructions DECLARE_CURSOR et OPEN de Transact-SQL. Cette procédure est appelée en spécifiant ID = 2 dans un paquet TDS (Tabular Data Stream).
S'applique à : SQL Server (SQL Server 2008 via la version actuelle). |
.gif "Icône Lien de rubrique")
Conventions de la syntaxe Transact-SQL
Syntaxe
sp_cursoropen cursor OUTPUT, stmt
[, scrollopt [ OUTPUT ] [ , ccopt [ OUTPUT ]
[ ,rowcount OUTPUT [ ,boundparam] [,...n] ] ] ] ]
Arguments
cursor
Identificateur de curseur généré par SQL Server. cursor est une valeur handle qui doit être fournie dans toutes les procédures suivantes impliquant le curseur, par exemple sp_cursorfetch. cursor est un paramètre obligatoire avec une valeur de retour int.cursor permet à plusieurs curseurs d'être actifs sur une connexion de base de données unique.
stmt
Paramètre obligatoire qui définit le jeu de résultats de curseur. Toute chaîne de requête valide (syntaxe et liaison) de tout type chaîne (indépendamment des données Unicode, de taille, etc.) peut servir de type de valeur stmt valide.scrollopt
Option de défilement. scrollopt est un paramètre optionnel qui requiert l'une des valeurs d'entrée int suivantes.Valeur
Description
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
En raison de la possibilité que la valeur demandée ne soit pas appropriée pour le curseur défini par stmt, ce paramètre sert à la fois d'entrée et de sortie. Dans de tels cas, SQL Server affecte une valeur appropriée.
ccopt
Option de contrôle en matière d'accès concurrentiel. ccopt est un paramètre optionnel qui requiert l'une des valeurs d'entrée int suivantes.Valeur
Description
0x0001
READ_ONLY
0x0002
SCROLL_LOCKS (précédemment appelé LOCKCC)
0x0004
OPTIMISTIC (précédemment appelé OPTCC)
0x0008
OPTIMISTIC (précédemment appelé 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
Comme avec scrollopt, SQL Server peut remplacer les valeurs ccopt demandées.
rowcount
Nombre de lignes de tampon d'extraction à utiliser avec AUTO_FETCH. La valeur par défaut est 20 lignes. rowcount se comporte différemment selon qu'il est attribué comme une valeur d'entrée ou comme une valeur de retour.
-Comme une valeur d'entrée
Comme une valeur de retour
Lorsque la valeur scrollopt AUTO_FETCH est spécifiée, rowcount représente le nombre de lignes à placer dans le tampon d'extraction.
Notes
>0 est une valeur valide quand AUTO_FETCH est spécifiée, mais est sinon ignoré.
Représente le nombre de lignes dans le jeu de résultats, sauf lorsque la valeur scrollopt AUTO_FETCH est spécifiée.
- boundparam
Indique l'utilisation de paramètres supplémentaires. boundparam est un paramètre optionnel qui doit être spécifié si la valeur de scrollopt PARAMETERIZED_STMT est définie sur ON.
Valeurs des codes de retour
Si aucune erreur n'est déclenchée, sp_cursoropen retourne l'une des valeurs suivantes.
0
La procédure a été correctement exécutée.0x0001
Une erreur s'est produite pendant l'exécution (une erreur mineure, pas assez grave pour générer une erreur dans l'opération).0x0002
Une opération asynchrone est en cours.0x0002
Une opération FETCH est en cours.A
Ce curseur a été libéré par SQL Server et n'est pas disponible.
Lorsqu'une erreur est générée, les valeurs de retour peuvent être incohérentes et l'exactitude ne peut pas être garantie.
Lorsque le paramètre rowcount est spécifié comme une valeur de retour, le jeu de résultats suivant se produit.
-1
Retourné si le nombre de lignes est inconnu ou non applicable.-n
Retourné lorsqu'un remplissage asynchrone est appliqué. Représente le nombre de lignes placées dans le tampon d'extraction lorsque la valeur scrollopt AUTO_FETCH est spécifiée.
Si l'appel de procédure distante est utilisé, les valeurs de retour sont les suivantes.
0
La procédure est réussie.1
La procédure a échoué.2
Un curseur de jeu de clés est généré de façon asynchrone.16
Un curseur avance rapide a été automatiquement fermé.
Notes
Si la procédure sp_cursoropen a été correctement exécutée, les paramètres de retour RPC et un jeu de résultats avec des informations de format de colonne TDS (messages 0xa0 & 0xa1) sont envoyés.En cas d'échec, un ou plusieurs messages d'erreur TDS sont envoyés.Dans les deux cas, aucune donnée de ligne ne sera retournée et le nombre de messages terminé sera égal à zéro.Si vous utilisez une version de SQL Server antérieure à 7.0, 0xa0, 0xa1 (standard pour les instructions SELECT) sont retournés avec les flux de jetons 0xa5 et 0xa4.Si vous utilisez SQL Server 7.0, 0x81 est retourné (standard pour les instructions SELECT) avec les flux de jetons 0xa5 et 0xa4.
Notes
Paramètre stmt
Si stmt spécifie l'exécution d'une procédure stockée, les paramètres d'entrée peuvent être définis comme constantes dans le cadre de la chaîne stmt ou spécifiés comme arguments boundparam. Les variables déclarées peuvent être passées comme paramètres liés de cette façon.
Le contenu autorisé du paramètre stmt varie selon si la valeur de retour ccopt ALLOW_DIRECT a été liée par OR au reste des valeurs ccopt, autrement dit :
Si ALLOW_DIRECT n'est pas spécifiée, une instruction Transact-SQL SELECT ou EXECUTE appelant une procédure stockée qui contient une instruction SELECT unique doit être utilisée. En outre, l'instruction SELECT doit obtenir la qualification de curseur, c'est-à-dire qu'elle ne peut pas contenir les mots clés SELECT INTO ou FOR BROWSE.
Si ALLOW_DIRECT est spécifiée, cela peut générer une ou plusieurs instructions Transact-SQL, notamment celles qui, à leur tour, exécutent d'autres procédures stockées avec plusieurs instructions. Les instructions autres que SELECT ou toute instruction SELECT qui contient les mots clés SELECT INTO ou FOR BROWSE seront simplement exécutées et n'aboutiront pas à la création d'un curseur. Cela s'applique aussi à toute instruction SELECT incluse dans un lot de plusieurs instructions. Dans les cas où une instruction SELECT contient des clauses qui concernent uniquement les curseurs, ces clauses sont ignorées. Par exemple, lorsque la valeur de ccopt est 0x2002, il s'agit d'une demande pour :
un curseur avec des arrêts de défilement, si une seule instruction SELECT obtient la qualification de curseur, ou
une exécution d'instruction directe s'il existe plusieurs instructions, une instruction autre que SELECT unique ou une instruction SELECT qui n'obtient pas la qualification de curseur.
Paramètre scrollopt
Les cinq premières valeurs scrollopt (KEYSET, DYNAMIC, FORWARD_ONLY, STATIC et FAST_FORWARD) s'excluent mutuellement.
PARAMETERIZED_STMT et CHECK_ACCEPTED_TYPES peuvent être liés par OR à chacune des cinq premières valeurs.
AUTO_FETCH et AUTO_CLOSE peuvent être liés par OR à FAST_FORWARD.
Si CHECK_ACCEPTED_TYPES a la valeur ON, au moins l'une des cinq dernières valeurs scrollopt (KEYSET_ACCEPTABLE, DYNAMIC_ACCEPTABLE, FORWARD_ONLY_ACCEPTABLE, STATIC_ACCEPTABLE ou FAST_FORWARD_ACCEPTABLE) doit également avoir la valeur ON.
Les curseurs STATIC sont toujours ouverts comme READ_ONLY. Cela signifie que la table sous-jacente ne peut pas être mise à jour via ce curseur.
Paramètre ccopt
Les quatre premières valeurs ccopt (READ_ONLY, SCROLL_LOCKS, et les deux valeurs OPTIMISTIC) s'excluent mutuellement.
Notes
Le choix de l'une des quatre premières valeurs ccopt détermine si le curseur est en lecture seule, ou si des méthodes de verrouillage ou optimistes sont utilisées pour empêcher des mises à jour perdues.Si aucune valeur ccopt n'est spécifiée, la valeur par défaut est OPTIMISTIC.
ALLOW_DIRECT et CHECK_ACCEPTED_TYPES peuvent être liés par OR à chacune des quatre premières valeurs.
UPDT_IN_PLACE peut être lié par OR à READ_ONLY, SCROLL_LOCKS, ou l'une des valeurs OPTIMISTIC.
Si CHECK_ACCEPTED_TYPES a la valeur ON, au moins l'une des quatre dernières valeurs ccopt (READ_ONLY_ACCEPTABLE, SCROLL_LOCKS_ACCEPTABLE, et l'une des valeurs OPTIMISTIC_ACCEPTABLE) doit également avoir la valeur ON.
Les fonctions UPDATE et DELETE positionnées peuvent être exécutées uniquement dans le tampon d'extraction et uniquement si la valeur ccopt est égale à SCROLL_LOCKS ou OPTIMISTIC. Si SCROLL_LOCKS est la valeur spécifiée, la réussite de l'opération est garantie. Si OPTIMISTIC est la valeur spécifiée, l'opération échoue si la ligne a changé depuis la dernière extraction.
La raison de cet échec est que, lorsqu'OPTIMISTIC est la valeur spécifiée, une fonction de contrôle d'accès concurrentiel optimiste est exécutée en comparant les valeurs d'horodatage ou de somme de contrôle, comme déterminé par SQL Server. Si l'une de ces lignes ne correspond pas, l'opération échoue.
La spécification d'UPDT_IN_PLACE comme valeur de retour détermine les résultats suivants :
S'il n'est pas défini lors de l'exécution d'une mise à jour positionnée sur une table avec un index unique, le curseur supprime la ligne de sa table de travail et l'insère à la fin de l'une des colonnes clés utilisées par le curseur, en modifiant ainsi ces colonnes.
S'il a la valeur ON, le curseur met simplement à jour les colonnes clés dans la ligne d'origine de la table de travail.
Paramètre bound_param
Le nom de paramètre doit être paramdef lorsque PARAMETERIZED_STMT est spécifié, d'après le message d'erreur dans le code. Lorsque PARAMETERIZED_STMT n'est pas spécifié, aucun nom n'est spécifié dans le message d'erreur.
Éléments RPC à prendre en considération
Il est possible d'affecter à l'indicateur d'entrée RPC RETURN_METADATA la valeur 0x0001 pour demander que les métadonnées relatives à la liste de sélection du curseur soient retournées dans le flux TDS.
Exemples
Paramètre bound_param
Tous les paramètres après le cinquième sont passés au plan d'instruction comme paramètres d'entrée. Le premier paramètre de ce type doit être une chaîne sous la forme suivante :
{ local variable name data type } [,…n]
Les paramètres suivants sont utilisés pour passer les valeurs à substituer au local variable name dans l'instruction.
Voir aussi
Référence
- boundparam