Partage via

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 DECLARE_CURSOR Transact-SQL 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 handle valeur qui doit être fournie sur toutes les procédures suivantes impliquant le curseur, par sp_cursorfetchexemple . Le paramètre de curseur est int et ne peut pas être NULL.

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 du 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. Le paramètre scrollopt est int, avec une valeur par défaut NULL, et peut être l’une des valeurs 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 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 mémoire tampon de récupération à 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 scrollopt est spécifiée, le AUTO_FETCH nombre de lignes à placer dans la mémoire tampon d’extraction représente le nombre de lignes à placer.

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

boundparam

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

Valeurs des codes de retour

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

Valeur Description
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 FETCH opération est en cours.
A Ce curseur a été désalloué et n’est pas disponible.

Lorsqu’une erreur est générée, les valeurs de retour peuvent être incohérentes et la précision 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.

Valeur Description
-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 scrollopt AUTO_FETCH est spécifiée.

Si l'appel de procédure distante est utilisé, les valeurs de retour sont les suivantes.

Valeur Description
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 rapide vers l’avant a été automatiquement fermé.

Si la sp_cursoropen procédure s’exécute correctement, les paramètres de retour RPC et un jeu de résultats avec les informations de format de colonne TDS (0xa0 et 0xa1 les 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 DONE messages est 0. 0x81 est retourné (standard pour SELECT les instructions) ainsi que les 0xa5 flux de 0xa4 jetons.

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 en tant qu’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 la valeur de retour ccopt ALLOW_DIRECT a été liée au OR reste des valeurs ccopt :

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

  • Si ALLOW_DIRECT elle est spécifiée, cela peut entraîner une ou plusieurs instructions Transact-SQL, y compris les instructions qui exécutent d’autres procédures stockées avec plusieurs instructions. Les instructions non-instructionsSELECT ou toute SELECT instruction qui contient les mots clés SELECT INTO ou FOR BROWSE sont exécutées, et n’entraînent pas la création d’un curseur. Il en va de même pour toutes les SELECT instructions incluses dans un lot d’instructions multiples. Dans les cas où une SELECT instruction contient des clauses qui se rapportent uniquement aux 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 verrous de défilement, s’il n’existe qu’une seule SELECT instruction qui se qualifie comme curseur ou

    • Exécution d’une instruction directe s’il existe plusieurs instructions, une seule instruction non-instructionSELECT ou une SELECT instruction qui ne se qualifie pas comme curseur.

Paramètre scrollopt

Les cinq premières valeurs scrollopt (KEYSEY, , FORWARD_ONLYDYNAMIC, STATICet FAST_FORWARD) s’excluent mutuellement.

PARAMETERIZED_STMT et CHECK_ACCEPTED_TYPES peut être lié à OR l’une des cinq premières valeurs.

AUTO_FETCH et AUTO_CLOSE peut être lié par OR FAST_FORWARD.

Si CHECK_ACCEPTED_TYPES c’est ON, au moins l’une des cinq dernières valeurs scrollopt (KEYSET_ACCEPTABLE, DYNAMIC_ACCEPTABLE, FORWARD_ONLY_ACCEPTABLE, STATIC_ACCEPTABLEou FAST_FORWARD_ACCEPTABLE) doit également être ON.

STATIC les curseurs sont toujours ouverts en tant que 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_ONLYet SCROLL_LOCKSles deux OPTIMISTIC valeurs) 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 OPTIMISTIC.

ALLOW_DIRECT et CHECK_ACCEPTED_TYPES peut être lié à OR l’une des quatre premières valeurs.

UPDT_IN_PLACE peut être lié par OR READ_ONLY, SCROLL_LOCKSou l’une des OPTIMISTIC valeurs.

Si CHECK_ACCEPTED_TYPES c’est ONle cas, au moins l’une des quatre dernières valeurs ccopt (READ_ONLY_ACCEPTABLESCROLL_LOCKS_ACCEPTABLEet l’une OPTIMISTIC_ACCEPTABLE des valeurs) doit également être ON.

Position UPDATE et DELETE fonctions peuvent être effectuées SCROLL_LOCKS uniquement dans la mémoire tampon d’extraction et uniquement si la valeur ccopt est égale ou OPTIMISTIC. S’il SCROLL_LOCKS s’agit de la valeur spécifiée, l’opération est garantie de réussir. Si OPTIMISTIC la valeur spécifiée est spécifiée, l’opération échoue si la ligne a changé depuis sa dernière extraction.

La raison de cet échec est que, lorsqu’il OPTIMISTIC s’agit de la valeur spécifiée, une fonction de contrôle monétaire optimiste est effectuée en comparant les horodatages ou les valeurs 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 UPDT_IN_PLACE en tant que valeur de retour régit 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, ce qui modifie ces colonnes.

  • Si la valeur est définie ON, le curseur met à 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 lorsqu’il PARAMETERIZED_STMT est spécifié, en fonction du message d’erreur dans le code. Quand PARAMETERIZED_STMT ce n’est pas spécifié, aucun nom n’est spécifié dans le message d’erreur.

Considérations relatives à RPC

L’indicateur d’entrée RPC RETURN_METADATA peut être défini pour 0x0001 demander que les métadonnées de liste de sélection de curseur soient retournées dans le flux TDS.

Exemples

R. 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 :

<parameter_name> <data_type> [ ,... n ]

Les paramètres suivants sont utilisés pour transmettre les valeurs à remplacer par l’instruction <parameter_name> .

Contenu connexe