Поделиться через

  • Статья

sp_cursorfetch (Transact-SQL)

Извлекает из базы данных буфер из одной или нескольких строк. Группа строк в этом буфере называется буфером выборки курсора. Хранимая процедура sp_cursorfetch вызывается указанием ID = 7 в пакете потока табличных данных (TDS).

Значок ссылки на разделСинтаксические обозначения Transact-SQL

Синтаксис

        sp_cursorfetch 
        cursor
        
        
            [ , fetchtype[ , rownum [ , nrows] ]]

Аргументы

  • cursor
    Значение дескриптора, сформированное системой SQL Server и возвращаемое процедурой sp_cursoropen. Параметр cursor является обязательным и требует входного значения типа int. Дополнительные сведения см. в подразделе «Примечания» далее в этом разделе.

  • fetchtype
    Указывает, какой буфер курсора выбирается. Параметр fetchtype является необязательным и требует одного из следующих целых входных значений.

    Значение

    Имя

    Описание

    0x0001

    FIRST

    Извлекает первый буфер в nrows строк. Если параметр nrows равен 0, то курсор позиционируется перед результирующим набором и строки не возвращаются.

    0x0002

    NEXT

    Извлекает следующий буфер в nrows строк.

    0x0004

    PREV

    Извлекает предыдущий буфер в nrows строк.

    ПримечаниеПримечание
       При использовании значения PREV для курсора FORWARD_ONLY возвращается сообщение об ошибке, поскольку FORWARD_ONLY поддерживает прокрутку только в одном направлении.

    0x0008

    LAST

    Извлекает последний буфер в nrows строк. Если параметр nrows равен 0, то курсор позиционируется после результирующего набора и строки не возвращаются.

    ПримечаниеПримечание
       При использовании значения LAST для курсора FORWARD_ONLY возвращается сообщение об ошибке, поскольку FORWARD_ONLY поддерживает прокрутку только в одном направлении.

    0x10

    ABSOLUTE

    Извлекает буфер в nrows строк, начиная со строки rownum.

    ПримечаниеПримечание
       При использовании значения ABSOLUTE для курсора DYNAMIC или FORWARD_ONLY возвращается сообщение об ошибке, поскольку FORWARD_ONLY поддерживает прокрутку только в одном направлении.

    0x20

    RELATIVE

    Извлекает буфер в nrows строк, начиная со строки, указанной в качестве значения параметра rownum от первой строки в текущем блоке. В этом случае параметр rownum может быть отрицательным числом.

    ПримечаниеПримечание
       При использовании значения RELATIVE для курсора FORWARD_ONLY возвращается сообщение об ошибке, поскольку FORWARD_ONLY поддерживает прокрутку только в одном направлении.

    0x80

    REFRESH

    Перезаполняет буфер из базовых таблиц.

    0x100

    INFO

    Извлекает сведения о курсоре. Эти сведения возвращаются в соответствии со значениями параметров rownum и nrows. Поэтому, когда указан параметр INFO, параметры rownum и nrows становятся выходными параметрами.

    0x200

    PREV_NOADJUST

    Используется как PREV. Но если вершина результирующего набора встретилась преждевременно, результаты могут отличаться.

    0x400

    SKIP_UPDT_CNCY

    Необходимо использоваться совместно с одним из других значений fetchtype, кроме INFO.
    ПримечаниеПримечание

       Поддержка значения 0x40 отсутствует.

    Дополнительные сведения см. в подразделе «Примечания» далее в этом разделе.

  • rownum
    Необязательный параметр, используемый для указания позиции строки для значений ABSOLUTE и INFO параметра fetchtype с применением числовых значений для входа, для выхода или для входа и выхода. Параметр rownum служит смещением строки для битового значения RELATIVE параметра fetchtype. Параметр rownum для всех остальных значений не учитывается. Дополнительные сведения см. в подразделе «Примечания» далее в этом разделе.

  • nrows
    Необязательный параметр, используемый для указания количества выбираемых строк. Если параметр nrows не указан, то значение по умолчанию равно 20 строкам. Чтобы установить позицию, не возвращая данные,укажите значение 0. Когда параметр nrows применяется в запросе fetchtype = INFO, он возвращает общее количество строк в этом запросе.

    ПримечаниеПримечание

       nrows не учитывается битовым значением REFRESH параметра fetchtype.

    Дополнительные сведения см. в подразделе «Примечания» далее в этом разделе.

Значения кодов возврата

Если указано битовое значение INFO, то могут возвращаться значения, показанные в следующих таблицах.

ПримечаниеПримечание

:   Если строки не возвращаются, то содержимое буфера остается прежним.

<rownum>

Установить в

Если не открыт

0

Если позиционирован перед результирующим набором

0

Если позиционирован после результирующего набора

-1

Для курсоров KEYSET и STATIC

Абсолютный номер строки в текущей позиции результирующего набора

Для курсоров DYNAMIC

1

Для ABSOLUTE

-1 возвращает последнюю строку в наборе.

-2 возвращает вторую от конца строку в наборе и так далее.

ПримечаниеПримечание
Если в этом случае запрашивается более одной строки, то возвращаются две последние строки результирующего набора.

<nrows>

Установить в

Если не открыт

0

Для курсоров KEYSET и STATIC

Обычно размер текущего набора ключей.

–m, если курсор находится в состоянии асинхронного создания с m строками, найденными до этой точки.

Для курсоров DYNAMIC

-1

Замечания

Параметр cursor

Перед началом операций выборки по умолчанию позиция курсора находится перед первой строкой результирующего набора.

Параметр fetchtype

Все значения параметра fetchtype, кроме SKIP_UPD_CNCY, взаимно исключают друг друга.

Если указано значение SKIP_UPDT_CNCY, то значения столбца отметки времени не записываются в таблицу набора ключей при выборке или обновлении строки. При обновлении строки набора ключей значения столбцов отметки времени остаются в качестве предыдущего значения. При выполнении вставки строки набора ключей значения для столбцов отметки времени не определены.

Для курсоров типа KEYSET это означает, что в таблице набора ключей имеются значения, установленные во время последней выполненной операции FETCH, если таковая была. В противном случае в ней имеются значения, установленные во время заполнения.

Для курсоров типа DYNAMIC это означает, что переход с обновлением даст такие же результаты, что и для KEYSET. Для любого другого типа выборки таблица набора ключей усекается. Это означает, что строки будут вставлены с неопределенными значениями отметки времени для одного или нескольких столбцов. Поэтому при запуске процедуры sp_cursorfetch для курсоров DYNAMIC избегайте использования SKIP_UPDT_CNCY для всех операций, кроме REFRESH.

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

Параметр rownum

При использовании параметра rownum буфер заполняется, начиная с указанной строки.

Параметр fetchtype со значением ABSOLUTE относится к позиции строки rownum во всем результирующем наборе. Если задано значение ABSOLUTE, то отрицательное число указывает на то, что операция считала строки от конца результирующего набора.

Параметр fetchtype со значением RELATIVE определяет позицию строки rownum относительно позиции курсора в начале текущего буфера. Если задано значение RELATIVE, то отрицательное число указывает на то, что курсор перемещается назад от текущей позиции курсора.

Параметр nrows

Если параметр fetchtype имеет значение REFRESH или INFO, то этот параметр не учитывается.

Если для параметра fetchtype указано значение FIRST, а значение параметра nrow равно 0, то курсор будет помещен перед результирующим набором, у которого нет строк в буфере выборки.

Если для параметра fetchtype указано значение LAST, а значение параметра nrow равно 0, то курсор будет помещен после результирующего набора, у которого нет строк в текущем буфере выборки.

Если значение параметра fetchtype равно NEXT, PREV, ABSOLUTE, RELATIVE или PREV_NOADJUST, то значение 0 для параметра nrow является недопустимым.

Замечания по RPC

Состояние возврата RPC указывает, является ли параметр размера набора ключей окончательным, то есть заполняется ли набор ключей или временная таблица асинхронно.

Для параметра состояния RPC устанавливается одно из значений, приведенных в следующей таблице.

Значение

Описание

0

Процедура успешно выполнена.

0x0001

Процедура завершилась ошибкой.

0x0002

Выборка в отрицательном направлении привела к тому, что позиция курсора оказалась в начале результирующего набора, когда выборка логически должна быть перед результатами.

0x10

Курсор FAST_FORWARD автоматически закрыт.

Строки возвращаются в виде типичного результирующего набора: формат столбцов (0x2a), строк (0xd1), за которым следует число обработанных (0xfd). Токены метаданных отправляются в том же формате, который указан для sp_cursoropen,, то есть 0x81, 0xa5 и 0xa4 для пользователей SQL Server 7.0 и так далее. Индикаторы состояния строк отправляются как скрытые столбцы, аналогично режиму BROWSE, в конце каждой строки с именем столбца rowstat и типом данных INT4. Столбец rowstat имеет одно из значений, приведенных в следующей таблице.

Значение

Описание

0x0001

FETCH_SUCCEEDED

0x0002

FETCH_MISSING

Поскольку протокол TDS не предусматривает способа отправки завершающего столбца состояния без отправки предшествующих столбцов, в отсутствующих столбцах отправляются фиктивные данные (поля, допускающие значение NULL, заполняются этим значением, в поля фиксированной длины записывается 0, пробел или значение по умолчанию для этого столбца соответственно).

Счетчик строк DONE всегда будет содержать ноль. Сообщение DONE содержит реальное число строк результирующего набора, информационные сообщения или сообщения об ошибках могут появляться между любыми сообщениями TDS.

Чтобы в потоке TDS возвращались запрошенные метаданные о списке выбора курсора, установите входной флажок RPC RETURN_METADATA в значение 1.

Примеры

A. Использование PREV для изменения позиции курсора

Предположим, курсор h2 сформирует результирующий набор со следующим содержимым и текущей позицией следующим образом.

row 1 contents    
row 2 contents
row 3 contents
row 4 contents  <-- current position
row 5 contents 
row 6 contents

Затем процедура sp_cursorfetch PREV, у которой значение параметра nrows равно 5, логически поместит курсор на две строки раньше первой строки результирующего набора. В таких случаях курсор настраивается так, чтобы начинаться у первой строки и возвращать запрошенное число строк. Часто это означает, что будут возвращены строки, которые были в буфере PRIOR.

ПримечаниеПримечание

 Это именно тот случай, когда параметр состояния RPC установлен в значение 2.

Б. Использование PREV_NOADJUST для возврата меньшего числа строк, чем PREV

PREV_NOADJUST никогда не включает строки, находящиеся в позиции курсора или за ней в блоке строк, который он возвращает. В случаях, когда PREV возвращает строки после текущей позиции, PREV_NOADJUST возвращает меньшее число строк, чем запрошено в параметре nrows. Если ранее в примере А задана текущая позиция, то при использовании PREV процедура sp_cursorfetch(h2, 4, 1, 5) выберет следующие строки:

row1 contents 
row2 contents
row3 contents
row4 contents
row5 contents

Но в том случае, если используется PREV_NOADJUST, хранимая процедура sp_cursorfetch(h2, 512, 6, 5) выберет только следующие строки:

row1 contents 
row2 contents
row3 contents

См. также

Справочник

Системные хранимые процедуры (Transact-SQL)

Другие ресурсы

sp_cursoropen (Transact-SQL)