sp_cursorfetch (Transact-SQL)
Extrait une mémoire tampon d'une ou de plusieurs lignes de la base de données. Le groupe de lignes dans cette mémoire tampon est appelé tampon d'extraction du curseur. sp_cursorfetch est appelé en spécifiant ID = 7 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_cursorfetch cursor
[ , fetchtype [ , rownum [ , nrows ] ] ]
Arguments
cursor
Valeur de handle générée par SQL Server et retournée par sp_cursoropen. cursor est un paramètre obligatoire qui demande une valeur d'entrée int. Pour plus d'informations, consultez la section Notes plus loin dans cette rubrique.fetchtype
Spécifie la mémoire tampon de curseur à extraire. fetchtype est un paramètre optionnel qui requiert l'une des valeurs d'entrée entières suivantes.Valeur
Nom
Description
0x0001
FIRST
Extrait la première mémoire tampon de nrows lignes. Si nrows est égal à 0, le curseur est positionné avant le jeu de résultats et aucune ligne n'est retournée.
0x0002
NEXT
Extrait la mémoire tampon suivante de nrows lignes.
0x0004
PREV
Extrait la mémoire tampon précédente de nrows lignes.
Notes
L'utilisation de PREV pour un curseur FORWARD_ONLY retourne un message d'erreur parce que FORWARD_ONLY prend seulement en charge le défilement dans une direction.
0x0008
LAST
Extrait la dernière mémoire tampon de nrows lignes. Si nrows est égal à 0, le curseur est positionné après le jeu de résultats et aucune ligne n'est retournée.
> [!NOTE] > <P> L'utilisation de LAST pour un curseur FORWARD_ONLY retourne un message d'erreur parce que FORWARD_ONLY prend seulement en charge le défilement dans une direction.</P>0x10
ABSOLUTE
Extrait une mémoire tampon de nrows lignes en commençant à la ligne rownum.
> [!NOTE] > <P> L'utilisation d'ABSOLUTE pour un curseur DYNAMIC ou un curseur FORWARD_ONLY retourne un message d'erreur parce que FORWARD_ONLY prend seulement en charge le défilement dans une direction.</P>0x20
RELATIVE
Extrait la mémoire tampon de nrows lignes en commençant à la ligne spécifiée comme étant la valeur rownum des lignes à partir de la première ligne dans le bloc actuel. Dans ce cas, rownum peut être un nombre négatif.
> [!NOTE] > <P> L'utilisation de RELATIVE pour un curseur FORWARD_ONLY retourne un message d'erreur parce que FORWARD_ONLY prend seulement en charge le défilement dans une direction.</P>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 nrows et rownum. Par conséquent, lorsque la valeur INFO est spécifiée, rownum et nrows deviennent des paramètres de sortie.
0x200
PREV_NOADJUST
Est utilisée 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ée avec l'une des autres valeurs fetchtype, à l'exception d'INFO.
> [!NOTE] > <P> Il n'existe aucune prise en charge de la valeur 0x40.</P> Pour plus d'informations, consultez la section Notes plus loin dans cette rubrique.rownum
Paramètre optionnel utilisé pour spécifier la position de ligne des valeurs fetchtype ABSOLUTE et INFO en utilisant uniquement des valeurs entières pour l'entrée ou la sortie, ou les deux. rownum sert de décalage de lignes à la valeur de bit fetchtype RELATIVE. rownum est ignoré pour toutes les autres valeurs. Pour plus d'informations, consultez la section Notes plus loin dans cette rubrique.nrows
Paramètre optionnel 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, indiquez la valeur 0. Lorsque nrows est appliqué à la requête fetchtype INFO, le nombre total de lignes dans cette requête est retourné.Notes
nrows est ignoré par la valeur de bit fetchtype REFRESH.
Pour plus d'informations, consultez la section Notes plus loin dans cette rubrique.
Valeurs des codes de retour
Lorsque vous spécifiez la valeur de bit INFO, les valeurs qui peuvent être retournées sont affichées dans les tableaux suivants.
Notes
: Si aucune ligne n'est retournée, le contenu de la mémoire tampon reste inchangé.
<rownum>
Valeur
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 les curseurs KEYSET et STATIC
Numéro de ligne absolu de la position actuelle dans le jeu de résultats
Pour les curseurs DYNAMIC
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.
Notes
Si plusieurs lignes doivent être extraites dans ce cas, les deux dernières lignes du jeu de résultats sont retournées.
<nrows>
Valeur
Si le curseur n'est pas ouvert
0
Pour les curseurs KEYSET et STATIC
En général, taille du jeu de clés actuel.
–m si le curseur est en création asynchrone avec m lignes trouvées à ce stade.
Pour les curseurs DYNAMIC
-1
Notes
Paramètre de curseur
Avant toute opération d'extraction, la position par défaut d'un curseur se situe avant la première ligne du jeu de résultats.
Paramètre fetchtype
À l'exception de SKIP_UPD_CNCY, les valeurs fetchtype s'excluent mutuellement.
Lorsque SKIP_UPDT_CNCY est spécifié, les valeurs de colonne timestamp ne sont pas écrites dans la table de jeux 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 les curseurs KEYSET, cela signifie que les valeurs de la table de jeux de clés sont définies pendant la dernière opération FETCH non ignorée, si celle-ci a été effectuée. Sinon, les valeurs sont définies pendant le remplissage.
Pour les curseurs DYNAMIC, cela signifie que si l'opération Skip est effectuée avec une actualisation, elle 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 de la ou des colonnes timestamp sont indéfinies. Par conséquent, lorsque vous exécutez sp_cursorfetch pour les curseurs DYNAMIC, é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 ABSOLUTE fait référence à la position de rownum dans le jeu de résultats entier. Un nombre négatif avec ABSOLUTE spécifie que l'opération compte les lignes à partir de la fin du jeu de résultats.
La valeur fetchtype RELATIVE fait référence à la position de rownum par rapport à la position du curseur au début de la mémoire tampon active. Un nombre négatif avec RELATIVE spécifie que le curseur retourne en arrière par rapport à sa position actuelle.
Paramètre nrows
Les valeurs fetchtype REFRESH et INFO ignorent ce paramètre.
Lorsque vous spécifiez la valeur fetchtype FIRST qui a une valeur nrow égale à 0, le curseur est positionné avant le jeu de résultats qui n'a aucune ligne dans le tampon d'extraction.
Lorsque vous spécifiez la valeur fetchtype LAST qui a une valeur nrow égale à 0, le curseur est positionné après le jeu de résultats qui n'a aucune ligne dans le tampon d'extraction actuel.
Pour les valeurs fetchtype NEXT, PREV, ABSOLUTE, RELATIVE et PREV_NOADJUST, une valeur nrow égale à 0 n'est pas valide.
Éléments RPC à prendre en considération
L'état de retour RPC indique si le paramètre de taille du jeu de clés est définitif ou pas, en d'autres termes 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 avance rapide a été automatiquement fermé.
Les lignes sont retournées comme un jeu de résultats classique, à savoir format de colonne (0x2a), lignes (0xd1), suivi de l'indication de fin (0xfd). Les jetons de métadonnées sont envoyés sous le même format que celui spécifié pour sp_cursoropen, à savoir 0x81, 0xa5 et 0xa4 pour les utilisateurs SQL Server 7.0, et ainsi de suite. Les indicateurs d'état de ligne sont envoyés en tant que colonnes masquées, comme en mode de navigation, à la fin de chaque ligne avec le rowstat du nom de la colonne et le type de données INT4. Cette colonne rowstat comporte l'une des valeurs affichées dans le tableau suivant.
Valeur
Description
0x0001
FETCH_SUCCEEDED
0x0002
FETCH_MISSING
Étant donné que le protocole TDS n'offre aucun moyen d'envoyer la colonne d'état de fin sans envoyer les colonnes précédentes, les données fictives sont envoyées à la place des lignes manquantes (champs Nullable avec une valeur Null, champs de longueur fixe avec une valeur 0, valeur vide, ou valeur par défaut pour cette colonne, selon le cas).
Le nombre de lignes DONE sera toujours égal à zéro. Le message DONE contient le nombre de lignes de jeu de résultats réel et des messages d'erreur ou d'information peuvent apparaître entre 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, affectez à l'indicateur d'entrée RPC RETURN_METADATA la valeur 1.
Exemples
A.Utilisation de PREV pour modifier une position de 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 contentsEnsuite, sp_cursorfetch PREV qui a la valeur nrows 5 positionne 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 souvent qu'il retourne des lignes qui étaient dans le tampon d'extraction PRIOR.
Notes
Il s'agit précisément du cas où le paramètre d'état RPC a la valeur 2.
B.Utilisation de PREV_NOADJUST pour retourner moins de lignes que PREV
PREV_NOADJUST n'inclut jamais aucune des lignes au niveau de la position de curseur actuelle ou après celle-ci dans le bloc des lignes qu'il retourne. Dans les cas où PREV retourne des lignes après la position actuelle, PREV_NOADJUST retourne moins de lignes que prévu dans nrows. En prenant la position actuelle dans l'exemple A plus haut, lorsque PREV est appliqué, sp_cursorfetch(h2, 4, 1, 5) extrait les lignes suivantes :
row1 contents row2 contents row3 contents row4 contents row5 contentsToutefois, lorsque PREV_NOADJUST est appliqué, sp_cursorfetch(h2, 512, 6, 5) extrait uniquement les lignes suivantes :
row1 contents row2 contents row3 contentsVoir aussi
Référence