sp_cursoropen (Transact-SQL)

  • Article

S’applique à :SQL Server

Ouvre un curseur. sp_cursoropen définit l’instruction SQL associée aux options de curseur et de curseur, puis remplit le curseur. sp_cursoropen équivaut à la combinaison des instructions Transact-SQL DECLARE_CURSOR et OPEN. Cette procédure est appelée en spécifiant ID = 2 dans un paquet TDS (Tabular Data Stream).

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. le curseur est une valeur de handle qui doit être fournie sur toutes les procédures suivantes impliquant le curseur, telles que sp_cursorfetch. le curseur est un paramètre obligatoire avec une valeur de retour int .

le curseur permet à plusieurs curseurs d’être actifs sur une seule connexion de base de données.

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 n’importe quel type de chaîne (quel que soit Unicode, taille, etc.) peut servir de type valeur stmt valide.

scrollopt
Option de défilement. scrollopt est un paramètre facultatif qui nécessite 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 facultatif qui nécessite l’une des valeurs d’entrée int suivantes.

Valeur Description
0x0001 READ_ONLY
0x0002 SCROLL_LOCKS (précédemment appelé LOCKCC)
0x0004 OPTIMISTE (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 de 20 lignes. rowcount se comporte différemment lorsqu’il est affecté en tant que valeur d’entrée par rapport à une valeur de retour.

Comme une valeur d'entrée Comme une valeur de retour
Lorsque la valeur de défilement AUTO_FETCH est spécifiée, le nombre de lignes à placer dans la mémoire tampon d’extraction représente le nombre de lignes à placer.

Remarque : >0 est une valeur valide lorsque AUTO_FETCH est spécifié, mais est sinon ignoré.		 Représente le nombre de lignes du jeu de résultats, sauf lorsque la valeur de défilement AUTO_FETCH est spécifiée.

-

boundparam
Indique l'utilisation de paramètres supplémentaires. boundparam est un paramètre facultatif qui doit être spécifié si la valeur PARAMETERIZED_STMT scrollopt est définie sur ON.

Codet de retour

Si aucune erreur n'est générée, sp_cursoropen retourne l'une des valeurs suivantes.

0
La procédure s’est exécutée avec succès.

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é désalloué 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 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 qui ont été placées dans la mémoire tampon d’extraction lorsque la valeur de défilement 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é.

Remarque

Si la procédure sp_cursoropen s’exécute correctement, les paramètres de retour RPC et un jeu de résultats avec des informations de format de colonne TDS (0xa0 &0xa1 messages) 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 n’est retournée et le nombre de messages terminés est égal à zéro. Si vous utilisez une version de SQL Server antérieure à la version 7.0, 0xa0, 0xa1 (standard pour les instructions SELECT) sont retournées avec 0xa5 et 0xa4 flux de jetons. Si vous utilisez SQL Server 7.0, 0x81 est retourné (standard pour les instructions SELECT) ainsi que 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 en tant que constantes dans le cadre de la chaîne stmt, ou spécifiées 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 dépend du fait que le ccopt ALLOW_DIRECT valeur de retour a été lié par OR au reste des valeurs ccopt , c.-à-d. :

  • Si ALLOW_DIRECT n’est pas spécifié, une instruction Transact-SQL SELECT ou EXECUTE appelant une procédure stockée contenant une instruction SELECT unique doit être utilisée. En outre, l’instruction SELECT doit être qualifiée de curseur ; autrement dit, elle ne peut pas contenir les mot clé SELECT INTO ou FOR BROWSE.

  • Si ALLOW_DIRECT est spécifié, cela peut entraîner une ou plusieurs instructions Transact-SQL, y compris 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 de défilement (KEYSEY, 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 est activé, au moins l’une des cinq dernières valeurs de défilement (KEYSET_ACCEPTABLE DYNAMIC_ACCEPTABLE, , FORWARD_ONLY_ACCEPTABLE, STATIC_ACCEPTABLE ou FAST_FORWARD_ACCEPTABLE) doit également être activée.

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 OPTIMISTE) s’excluent mutuellement.

Remarque

Le choix de l’une des quatre premières valeurs ccopt détermine si le curseur est en lecture seule ou si les méthodes de verrouillage ou optimistes sont utilisées pour empêcher les mises à jour perdues. Si aucune valeur ccopt n’est spécifiée, la valeur par défaut est OPTIMISTE.

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 est ACTIVÉ, 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 être ON.

Les fonctions UPDATE et DELETE positionnées peuvent être effectuées uniquement dans la mémoire tampon d’extraction et uniquement si la valeur ccopt est égale à SCROLL_LOCKS ou OPTIMISTE. 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 lorsque l’optimiste est la valeur spécifiée, une fonction de contrôle monétaire optimiste est effectuée en comparant les horodatages ou les valeurs de case activée sum, 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 du paramètre doit être paramdef lorsque PARAMETERIZED_STMT est spécifié, en fonction du 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 :

{ type de données de nom de variable locale } [,... n]

Les paramètres suivants sont utilisés pour transmettre les valeurs à remplacer par le nom de la variable locale dans l’instruction.

Voir aussi

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