FETCH (Transact-SQL)

Получает определенную строку из серверного курсора Transact-SQL.

Синтаксические обозначения в Transact-SQL

Синтаксис

FETCH 
          [ [ NEXT | PRIOR | FIRST | LAST 
                    | ABSOLUTE { n | @nvar } 
                    | RELATIVE { n | @nvar } 
               ] 
               FROM 
          ] 
{ { [ GLOBAL ] cursor_name } | @cursor_variable_name } 
[ INTO @variable_name [ ,...n ] ] 

Аргументы

• NEXT
  Возвращает строку результата сразу же за текущей строкой и перемещает указатель текущей строки на возвращенную строку. Если инструкция FETCH NEXT выполняет первую выборку в отношении курсора, она возвращает первую строку в результирующем наборе. NEXT является параметром по умолчанию выборки из курсора.

• PRIOR
  Возвращает строку результата, находящуюся непосредственно перед текущей строкой и перемещает указатель текущей строки на возвращенную строку. Если инструкция FETCH PRIOR выполняет первую выборку из курсора, не возвращается никакая строка и положение курсора остается перед первой строкой.

• FIRST
  Возвращает первую строку в курсоре и делает ее текущей.

• LAST
  Возвращает последнюю строку в курсоре, и делает ее текущей.

• ABSOLUTE { n| @nvar}
  Если n или @nvar имеет положительное значение, возвращает строку, отстоящую на n строк от начала курсора, и делает возвращенную строку новой текущей строкой. Если n или @nvar имеет отрицательное значение, возвращает строку, отстоящую на n строк от конца курсора, и делает возвращенную строку новой текущей строкой. Если n или @nvar равно 0, строки не возвращаются. Значение n должно быть целочисленной константой, а значение @nvar должно иметь тип smallint, tinyint или int.

• RELATIVE { n| @nvar}
  Если n или @nvar имеет положительное значение, возвращает строку, отстоящую на n строк от текущей строки, и делает возвращенную строку новой текущей строкой. Если n или @nvar имеют отрицательное значение, возвращает строку, предшествующую на n строк текущей строке, и делает возвращенную строку новой текущей строкой. Если n или @nvar равно 0, возвращает текущую строку. Если при первой выборке из курсора инструкция FETCH RELATIVE указывается с отрицательными или равными нулю значениями n или @nvar , строки не возвращаются. Значение n должно быть целочисленной константой, а значение @nvar должно иметь тип smallint, tinyint или int.

• GLOBAL
  Указывает, что аргумент cursor_name ссылается на глобальный курсор.

• cursor_name
  Имя открытого курсора, из которого должна быть произведена выборка. Если существуют как глобальный, так и локальный курсоры с именем cursor_name, имя cursor_name будет указывать на глобальный курсор, если указано ключевое слово GLOBAL, и на локальный курсор, если не указано.

• @cursor_variable_name
  Имя переменной курсора, ссылающейся на открытый курсор, из которого должна быть произведена выборка.

• INTO @variable_name\[ ,...n]
  Позволяет поместить данные из столбцов выборки в локальные переменные. Каждая переменная из списка, слева направо, связывается с соответствующим столбцом в результирующем наборе курсора. Тип данных каждой переменной должен соответствовать типу данных соответствующего столбца результирующего набора, или должна обеспечиваться поддержка неявного преобразования в тип данных этого столбца. Количество переменных должно совпадать с количеством столбцов в списке выбора курсора.

Замечания

Если в инструкции DECLARE CURSOR в стиле ISO не указан параметр SCROLL, единственным поддерживаемым параметром инструкции FETCH является NEXT. Если в инструкции DECLARE CURSOR в стиле ISO параметр SCROLL указан, поддерживаются все параметры инструкции FETCH.

При использовании расширений курсора Transact-SQL DECLARE применимы следующие правила.

• Если указан FORWARD_ONLY или FAST_FORWARD, единственным поддерживаемым параметром инструкции FETCH является NEXT.

• Если DYNAMIC, FORWARD_ONLY или FAST_FORWARD не указаны и указан один из параметров KEYSET, STATIC или SCROLL, поддерживаются все параметры инструкции FETCH.

• Курсоры DYNAMIC SCROLL поддерживают все параметры инструкции FETCH, за исключением параметра ABSOLUTE.

Функция @@FETCH_STATUS возвращает состояние последней инструкции FETCH. Те же данные записываются в столбец fetch_status в курсоре, возвращаемом процедурой sp_describe_cursor. Эти сведения о состоянии должны использоваться для определения действительности данных, возвращаемых инструкцией FETCH перед попыткой выполнения любой операции над этими данными. Дополнительные сведения см. в разделе @@FETCH_STATUS (Transact-SQL).

Разрешения

Разрешения на инструкцию FETCH по умолчанию предоставляются всем допустимым пользователям.

Примеры

А. Использование инструкции FETCH в простом курсоре

В следующем примере показано, как объявить простой курсор для строк таблицы Person.Person, содержащих фамилии, которые начинаются с буквы B, и использовать инструкцию FETCH NEXT для пошагового перемещения по строкам. Инструкции FETCH возвращают значение для столбца, указанного в инструкции DECLARE CURSOR в качестве однострочного результирующего набора.

USE AdventureWorks2008R2;
GO
DECLARE contact_cursor CURSOR FOR
SELECT LastName FROM Person.Person
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

Б. Использование инструкции FETCH для сохранения значений в переменных

Следующий пример аналогичен примеру A, за исключением того, что выход инструкций FETCH сохраняется в локальных переменных, а не возвращается непосредственно клиенту. Инструкция PRINT объединяет переменные в одну строку и возвращает их клиенту.

USE AdventureWorks2008R2;
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.Person
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

В. Объявление курсора SCROLL и использование других параметров инструкции FETCH

В следующем примере создается курсор SCROLL, с помощью которого можно получить полные возможности прокрутки с помощью параметров LAST, PRIOR, RELATIVE и ABSOLUTE.

USE AdventureWorks2008R2;
GO
-- Execute the SELECT statement alone to show the 
-- full result set that is used by the cursor.
SELECT LastName, FirstName FROM Person.Person
ORDER BY LastName, FirstName;

-- Declare the cursor.
DECLARE contact_cursor SCROLL CURSOR FOR
SELECT LastName, FirstName FROM Person.Person
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

См. также

Справочник

CLOSE (Transact-SQL)

DEALLOCATE (Transact-SQL)

DECLARE CURSOR (Transact-SQL)

OPEN (Transact-SQL)

Основные понятия

Курсоры языка Transact-SQL