FETCH (Transact-SQL)
Récupère une ligne spécifique d'un curseur de serveur Transact-SQL.
Syntaxe
FETCH
[ [ NEXT | PRIOR | FIRST | LAST
| ABSOLUTE { n | @nvar }
| RELATIVE { n | @nvar }
]
FROM
]
{ { [ GLOBAL ] cursor_name } | @cursor_variable_name }
[ INTO @variable_name [ ,...n ] ]
Arguments
- NEXT
Renvoie la ligne de résultats immédiatement après la ligne courante et incrémente cette dernière sur la ligne renvoyée. Si FETCH NEXT est la première extraction effectuée sur un curseur, cette instruction renvoie la première ligne dans le jeu de résultats. NEXT est l'option d'extraction du curseur par défaut.
- PRIOR
Renvoie la ligne de résultats immédiatement avant la ligne courante, et décrémente cette dernière sur la ligne renvoyée. Si FETCH PRIOR est la première extraction effectuée sur un curseur, aucune ligne n'est renvoyée et le curseur reste placé avant la première ligne.
- FIRST
Renvoie la première ligne dans le curseur et la transforme en ligne courante.
- LAST
Renvoie la dernière ligne dans le curseur et la transforme en ligne courante.
- ABSOLUTE { n | **@**nvar}
Si n ou @nvar est un nombre positif, cela renvoie la ligne n depuis le début du curseur et transforme la ligne renvoyée en nouvelle ligne courante. Si n ou @nvar est un nombre négatif, cela renvoie la ligne n avant la fin du curseur et transforme la ligne renvoyée en nouvelle ligne courante. Si n ou @nvar est égal à 0, aucune ligne n'est renvoyée. n doit correspondre à une constante entière et @nvar doit être de type smallint, tinyint ou int.
- RELATIVE { n | **@**nvar}
Si n ou @nvar est un nombre positif, cela renvoie la ligne n à partir de la ligne courante et transforme la ligne renvoyée en nouvelle ligne courante. Si n ou @nvar est un nombre négatif, cela renvoie la ligne n avant la ligne courante et transforme la ligne renvoyée en nouvelle ligne courante. Si n ou @nvar est égal à 0, la ligne courante est renvoyée. Si FETCH RELATIVE est spécifié avec n ou @nvar défini avec un nombre négatif ou égal à 0 lors de la première extraction effectuée sur un curseur, aucune ligne n'est renvoyée. n doit correspondre à une constante entière et @nvar doit être de type smallint, tinyint ou int.
- GLOBAL
Précise que cursor_name renvoie à un curseur global.
- cursor_name
Nom du curseur ouvert grâce auquel s'effectue l'extraction. Si deux curseurs, un global et un local, existent avec pour nom cursor_name, **ce dernier renvoie au curseur global si GLOBAL est précisé, et au curseur local dans tous les autres cas.
- @cursor_variable_name
Nom d'une variable de curseur qui fait référence au curseur ouvert à partir duquel l'extraction doit être effectuée.
- INTO @variable_name[ ,...n]
Permet aux données issues des colonnes d'une extraction d'être placées dans des variables locales. Chaque variable de la liste (de gauche à droite) est associée à la colonne correspondante dans le jeu de résultats du curseur. Le type de données de chaque variable doit correspondre ou être une conversion implicite du type de données de la colonne du jeu de résultats correspondante. Le nombre de variables doit correspondre au nombre de colonnes dans la liste de sélection du curseur.
Notes
Si l'option SCROLL n'est pas précisée dans une instruction DECLARE CURSOR de style SQL-92, NEXT est la seule option FETCH prise en charge. Si SCROLL est précisée dans une instruction DECLARE CURSOR de style SQL-92, toutes les options FETCH sont prises en charge.
Lorsque les extensions de curseur Transact-SQL DECLARE sont utilisées, les règles suivantes sont respectées :
- si FORWARD_ONLY ou FAST_FORWARD est précisé, NEXT est la seule option FETCH prise en charge ;
- si DYNAMIC, FORWARD_ONLY ou FAST_FORWARD ne sont pas précisés, et que KEYSET, STATIC ou SCROLL sont spécifiés, toutes les options FETCH sont prises en charge ;
- les curseurs DYNAMIC SCROLL prennent en charge toutes les options FETCH sauf ABSOLUTE.
La fonction @@FETCH_STATUS établit un rapport d'état de la dernière instruction FETCH. Les mêmes informations sont enregistrées dans la colonne fetch_status du curseur renvoyé par sp_describe_cursor. Ces informations d'état doivent être utilisées pour déterminer la validité des données renvoyées par une instruction FETCH avant de tenter toute opération sur ces données. Pour plus d'informations, consultez @@FETCH_STATUS.
Autorisations
Les autorisations FETCH reviennent par défaut à tous les utilisateurs valides.
Exemples
A. Utilisation de FETCH dans un curseur simple
Cet exemple déclare un curseur simple pour les lignes de la table Person.Contact dont le nom commence par B, et il utilise FETCH NEXT pour parcourir les lignes. L'instruction FETCH renvoie la valeur de la colonne spécifiée dans DECLARE CURSOR comme un jeu de résultats sur une seule ligne.
USE AdventureWorks
GO
DECLARE contact_cursor CURSOR FOR
SELECT LastName FROM Person.Contact
WHERE LastName LIKE 'B%'
ORDER BY LastName
OPEN contact_cursor
-- Perform the first fetch.
FETCH NEXT FROM contact_cursor
-- Check @@FETCH_STATUS to see if there are any more rows to fetch.
WHILE @@FETCH_STATUS = 0
BEGIN
-- This is executed as long as the previous fetch succeeds.
FETCH NEXT FROM contact_cursor
END
CLOSE contact_cursor
DEALLOCATE contact_cursor
GO
B. Utilisation de FETCH pour stocker des valeurs dans des variables
Cet exemple ressemble au précédent, excepté que le résultat des instructions FETCH est stocké dans des variables locales plutôt que d'être directement renvoyé au client. L'instruction PRINT combine les variables dans une chaîne unique et les renvoie au client.
USE AdventureWorks
GO
-- Declare the variables to store the values returned by FETCH.
DECLARE @LastName varchar(50), @FirstName varchar(50)
DECLARE contact_cursor CURSOR FOR
SELECT LastName, FirstName FROM Person.Contact
WHERE LastName LIKE 'B%'
ORDER BY LastName, FirstName
OPEN contact_cursor
-- Perform the first fetch and store the values in variables.
-- Note: The variables are in the same order as the columns
-- in the SELECT statement.
FETCH NEXT FROM contact_cursor
INTO @LastName, @FirstName
-- Check @@FETCH_STATUS to see if there are any more rows to fetch.
WHILE @@FETCH_STATUS = 0
BEGIN
-- Concatenate and display the current values in the variables.
PRINT 'Contact Name: ' + @FirstName + ' ' + @LastName
-- This is executed as long as the previous fetch succeeds.
FETCH NEXT FROM contact_cursor
INTO @LastName, @FirstName
END
CLOSE contact_cursor
DEALLOCATE contact_cursor
GO
C. Déclaration d'un curseur SCROLL et utilisation des autres options FETCH
Cet exemple crée un curseur SCROLL pour permettre le défilement complet grâce aux options LAST, PRIOR, RELATIVE et ABSOLUTE.
USE AdventureWorks
GO
-- Execute the SELECT statement alone to show the
-- full result set that is used by the cursor.
SELECT LastName, FirstName FROM Person.Contact
ORDER BY LastName, FirstName
-- Declare the cursor.
DECLARE contact_cursor SCROLL CURSOR FOR
SELECT LastName, FirstName FROM Person.Contact
ORDER BY LastName, FirstName
OPEN contact_cursor
-- Fetch the last row in the cursor.
FETCH LAST FROM contact_cursor
-- Fetch the row immediately prior to the current row in the cursor.
FETCH PRIOR FROM contact_cursor
-- Fetch the second row in the cursor.
FETCH ABSOLUTE 2 FROM contact_cursor
-- Fetch the row that is three rows after the current row.
FETCH RELATIVE 3 FROM contact_cursor
-- Fetch the row that is two rows prior to the current row.
FETCH RELATIVE -2 FROM contact_cursor
CLOSE contact_cursor
DEALLOCATE contact_cursor
GO
Voir aussi
Référence
CLOSE (Transact-SQL)
DEALLOCATE (Transact-SQL)
DECLARE CURSOR (Transact-SQL)
OPEN (Transact-SQL)