sp_cursorfetch (Transact-SQL)
S’applique à : 
SQL Server
Extrait une mémoire tampon d'une ou de plusieurs lignes de la base de données. Le groupe de lignes de cette mémoire tampon est appelé mémoire tampon d’extraction du curseur. sp_cursorfetch est appelé en spécifiant ID = 7 dans un paquet TDS (Tabular Data Stream).
Conventions de la syntaxe Transact-SQL
Syntaxe
sp_cursorfetch cursor
[ , fetchtype [ , rownum [ , nrows ] ] ]
[ ; ]
Arguments
cursor
Valeur de handle générée par SQL Server et retournée par sp_cursoropen. le curseur est un paramètre obligatoire qui appelle une valeur d’entrée int . Pour plus d’informations, consultez la section Remarques.
fetchtype
Spécifie la mémoire tampon de curseur à extraire. fetchtype est un paramètre facultatif qui nécessite l’une des valeurs d’entrée entière suivantes.
| Valeur | Nom | Description |
|---|---|---|
0x0001 |
FIRST |
Récupère la première mémoire tampon des lignes derows . Si les noyes sont égales à 0, le curseur est positionné avant le jeu de résultats et aucune ligne n’est retournée. |
0x0002 |
NEXT |
Récupère la mémoire tampon suivante des lignes derows . |
0x0004 |
PREV |
Récupère la mémoire tampon précédente des lignes derows. Remarque : L’utilisation PREV d’un FORWARD_ONLY curseur retourne un message d’erreur, car FORWARD_ONLY elle prend uniquement en charge le défilement dans une direction. |
0x0008 |
LAST |
Récupère la dernière mémoire tampon des lignes derows . Si nrows est égal à 0, le curseur est positionné après le jeu de résultats et aucune ligne n’est retournée. Remarque : L’utilisation LAST d’un FORWARD_ONLY curseur retourne un message d’erreur, car FORWARD_ONLY elle prend uniquement en charge le défilement dans une direction. |
0x10 |
ABSOLUTE |
Récupère une mémoire tampon de lignes nrows commençant par la ligne rownum . Remarque : L’utilisation ABSOLUTE d’un DYNAMIC curseur ou d’un FORWARD_ONLY curseur retourne un message d’erreur, car FORWARD_ONLY elle prend uniquement en charge le défilement dans une direction. |
0x20 |
RELATIVE |
Récupère la mémoire tampon des lignes nrows commençant par la ligne spécifiée comme étant la valeur rownum des lignes de la première ligne du bloc actuel. Dans ce cas, rownum peut être un nombre négatif. Remarque : L’utilisation RELATIVE d’un FORWARD_ONLY curseur retourne un message d’erreur, car FORWARD_ONLY elle prend uniquement en charge le défilement dans une direction. |
0x80 |
REFRESH |
Remplit la mémoire tampon à partir de tables sous-jacentes. |
0x100 |
INFO |
Récupère des informations sur le curseur. Ces informations sont retournées à l’aide des paramètres rownum et nrows . Par conséquent, quand INFO est spécifié, rownum et nrows deviennent des paramètres de sortie. |
0x200 |
PREV_NOADJUST |
Est utilisé comme PREV. Toutefois, si les premiers résultats du jeu sont trouvés prématurément, les résultats peuvent varier. |
0x400 |
SKIP_UPDT_CNCY |
Doit être utilisé avec l’une des autres valeurs fetchtype , à l’exception de INFO. |
Remarque
Il n’existe aucune prise en charge de la valeur 0x40.
Pour plus d’informations, consultez la section Remarques.
rownum
Paramètre facultatif utilisé pour spécifier la position de ligne pour les ABSOLUTE valeurs et INFO fetchtype en utilisant uniquement des valeurs entières pour l’entrée ou la sortie, ou les deux. rownum sert de décalage de ligne pour la valeur RELATIVEde bit fetchtype . rownum est ignoré pour toutes les autres valeurs. Pour plus d’informations, consultez la section Remarques.
noys
Paramètre facultatif utilisé pour spécifier le nombre de lignes à extraire. Si nrows n’est pas spécifié, la valeur par défaut est de 20 lignes. Pour définir la position sans retourner de données, spécifiez une valeur de 0. Lorsque lesrows sont appliqués à la requête fetchtypeINFO, il retourne le nombre total de lignes de cette requête.
nrows est ignoré par la valeur de REFRESH bit fetchtype . Pour plus d’informations, consultez la section Remarques.
Valeurs des codes de retour
Lorsque vous spécifiez la valeur INFOde bit, les valeurs qui peuvent être retournées sont affichées dans les tableaux suivants.
Si aucune ligne n’est retournée, le contenu de la mémoire tampon reste tel quel.
| <rownum> | Se mettre à |
|---|---|
| Si le curseur n'est pas ouvert | 0 |
| Si le curseur est positionné avant le jeu de résultats | 0 |
| Si le curseur est positionné après le jeu de résultats | -1 |
Pour KEYSET et STATIC curseurs |
Numéro de ligne absolu de la position actuelle dans le jeu de résultats |
Pour DYNAMIC les curseurs |
1 |
Pour ABSOLUTE |
-1 retourne la dernière ligne dans un jeu. -2 retourne la deuxième à la dernière ligne dans un jeu, et ainsi de suite. Remarque : Si plusieurs lignes sont demandées pour l’extraction dans ce cas, les deux dernières lignes du jeu de résultats sont retournées. |
<nrows> |
Se mettre à |
|---|---|
| Si le curseur n'est pas ouvert | 0 |
Pour KEYSET et STATIC curseurs |
En général, taille du jeu de clés actuel.-m si le curseur est en création asynchrone avec des lignes m trouvées à ce stade. |
Pour DYNAMIC les curseurs |
-1 |
Notes
Paramètre de curseur
Avant toutes les opérations d’extraction, la position par défaut d’un curseur est avant la première ligne du jeu de résultats.
Paramètre fetchtype
À l’exception de SKIP_UPD_CNCY, les valeurs fetchtype sont mutuellement exclusives.
Quand SKIP_UPDT_CNCY elle est spécifiée, les valeurs de colonne d’horodatage ne sont pas écrites dans la table du jeu de clés lorsqu’une ligne est extraite ou actualisée. Si la ligne de jeu de clés est mise à jour, les valeurs des colonnes timestamp restent inchangées. Si la ligne de jeu de clés est insérée, les valeurs des colonnes timestamp sont indéfinies.
Pour KEYSET les curseurs, cela signifie que la table de jeux de clés a les valeurs définies pendant le dernier non-skip FETCH, si une table a été effectuée. Si ce n’est pas le cas, il s’agit des valeurs définies pendant la population.
Pour DYNAMIC les curseurs, cela signifie que si l’skip est effectué avec une actualisation, il produit les mêmes résultats que KEYSET. Pour tout autre type d'extraction, la table de jeux de clés est tronquée. Cela signifie que les lignes sont insérées et que les valeurs des colonnes d’horodatage ne sont pas définies. Par conséquent, lorsque vous exécutez sp_cursorfetch des DYNAMIC curseurs, évitez d’utiliser SKIP_UPDT_CNCY pour toute opération autre que REFRESH.
Si une opération d'extraction échoue parce que la position de curseur demandée se situe au-delà du jeu de résultats, la position de curseur est définie juste après la dernière ligne. Si une opération d'extraction échoue parce que la position de curseur demandée se situe avant le jeu de résultats, la position de curseur est définie avant la première ligne.
Paramètre rownum
Lorsque vous utilisez rownum, la mémoire tampon est remplie à partir de la ligne spécifiée.
La valeur fetchtype fait référence à la position de rownum dans l’ensemble du jeu de résultats.ABSOLUTE Nombre négatif avec ABSOLUTE spécifie que l’opération compte les lignes de la fin du jeu de résultats.
La valeur RELATIVE fetchtype fait référence à la position de rownum par rapport à la position du curseur au début de la mémoire tampon actuelle. Nombre négatif avec RELATIVE spécifie que le curseur remonte à la position actuelle du curseur.
Paramètre nrows
Valeurs fetchtype REFRESH et INFO ignorer ce paramètre.
Lorsque vous spécifiez une valeur de type fetchtype de FIRST la valeur 0, le curseur est positionné avant le jeu de résultats qui n’a pas de lignes dans la mémoire tampon d’extraction.
Lorsque vous spécifiez une valeur de type fetchtype de LAST la valeur 0, le curseur est positionné après le jeu de résultats qui n’a pas de lignes dans la mémoire tampon d’extraction actuelle.
Pour les valeurs fetchtype de NEXT, , ABSOLUTEPREV, RELATIVEet PREV_NOADJUST, une valeur derow de 0 nrow n’est pas valide.
Considérations relatives à RPC
L’état de retour RPC indique si le paramètre de taille du jeu de clés est final ou non ; autrement dit, si le jeu de clés ou la table temporaire est rempli de façon asynchrone.
L'une des valeurs affichées dans le tableau suivant est affectée au paramètre d'état RPC.
| Valeur | Description |
|---|---|
0 |
La procédure a été correctement exécutée. |
0x0001 |
La procédure a échoué. |
0x0002 |
Une extraction dans une direction négative a provoqué la définition de la position du curseur au début du jeu de résultats, alors que l'extraction aurait dû se situer logiquement avant les résultats. |
0x10 |
Un curseur rapide vers l’avant a été automatiquement fermé. |
Les lignes sont retournées sous la forme d’un jeu de résultats classique : format de colonne (0x2a), lignes (0xd1), suivis de DONE (0xfd). Les jetons de métadonnées sont envoyés au même format que celui spécifié pour sp_cursoropen: 0x81, 0xa5 et 0xa4 pour les utilisateurs SQL Server, et ainsi de suite. Les indicateurs d’état de ligne sont envoyés sous forme de colonnes masquées, similaires au BROWSE mode, à la fin de chaque ligne avec le nom de colonne rowstat et le type de données int. Cette colonne rowstat comporte l’une des valeurs indiquées dans le tableau suivant.
| Valeur | Description |
|---|---|
0x0001 |
FETCH_SUCCEEDED |
0x0002 |
FETCH_MISSING |
Étant donné que le protocole TDS ne permet pas d’envoyer la colonne d’état de fin sans envoyer les colonnes précédentes, les données factices sont envoyées pour les lignes manquantes. Les champs nullables sont définis sur Null et les champs de longueur fixe sont définis 0sur , vides ou par défaut pour cette colonne, selon les besoins.
Le nombre de DONE lignes est toujours 0. Le DONE message contient le nombre réel de lignes du jeu de résultats, et les messages d’erreur ou d’information peuvent apparaître entre tous les messages TDS.
Pour demander que les métadonnées relatives à la liste de sélection du curseur soient retournées dans le flux TDS, définissez l’indicateur 1d’entrée RPC RETURN_METADATA sur .
Exemples
R. Utiliser PREV pour modifier la position d’un curseur
Imaginons qu'un curseur h2 produit un jeu de résultats avec le contenu suivant dont la position actuelle est indiquée ci-dessous :
row 1 contents
row 2 contents
row 3 contents
row 4 contents <-- current position
row 5 contents
row 6 contents
Ensuite, un sp_cursorfetch PREV emplacement où lesrows sont 5 positionnés logiquement le curseur deux lignes avant la première ligne du jeu de résultats. Dans ces cas, le curseur est ajusté pour démarrer à la première ligne et retourner le nombre de lignes demandé. Cela signifie fréquemment qu’elle retourne des lignes qui se trouvaient dans la mémoire tampon d’extraction PRIOR .
Remarque
Il s'agit précisément du cas où le paramètre d'état RPC a la valeur 2.
B. Utilisez PREV_NOADJUST pour retourner moins de lignes que PREV
PREV_NOADJUST n’inclut jamais les lignes à ou après la position actuelle du curseur dans le bloc de lignes qu’elle retourne. Dans les cas où PREV retourne des lignes après la position actuelle, PREV_NOADJUST retourne moins de lignes que demandées dans lesrows. Étant donné la position actuelle de l’exemple A précédemment, quand elle PREV est appliquée, sp_cursorfetch (h2, 4, 1, 5) extrait les lignes suivantes :
row1 contents
row2 contents
row3 contents
row4 contents
row5 contents
Toutefois, quand PREV_NOADJUST elle est appliquée, sp_cursorfetch (h2, 512, 6, 5) récupère uniquement les lignes suivantes :
row1 contents
row2 contents
row3 contents