sp_cursorfetch (Transact-SQL)

Область применения:SQL Server

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

Соглашения о синтаксисе Transact-SQL

Синтаксис

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

Аргументы

Важный

Аргументы для расширенных хранимых процедур необходимо ввести в определенном порядке, как описано в разделе Синтаксис. Если параметры введены вне порядка, возникает сообщение об ошибке.

курсор

Значение дескриптора, созданное sp_cursoropen cursor — это обязательный параметр, вызывающий входное значение int . Дополнительные сведения см. в разделе с примечаниями.

получение типа

Указывает, какой буфер курсора выбирается. 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, начиная с строки, указанной как значение строки строки из первой строки в текущем блоке. В этом случае строка может быть отрицательным числом. Примечание. Использование RELATIVE курсора возвращает сообщение об ошибке FORWARD_ONLY , так как FORWARD_ONLY поддерживает прокрутку только в одном направлении.
0x80	REFRESH	Перезаполняет буфер из базовых таблиц.
0x100	INFO	Извлекает сведения о курсоре. Эти сведения возвращаются с помощью параметров rownum и nrows . Поэтому, если INFO задано, rownum и nrows становятся выходными параметрами .
0x200	PREV_NOADJUST	Используется как PREV. Но если вершина результирующего набора встретилась преждевременно, результаты могут отличаться.
0x400	SKIP_UPDT_CNCY	Необходимо использовать с одним из других значений набора данных, за исключением INFO.

Примечание.

Значение не поддерживается 0x40.

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

rownum

Необязательный параметр, используемый для указания позиции строки для значений и ABSOLUTEINFO значений типа, используя только целочисленные значения для входных или выходных данных или обоих значений. rownum служит смещением строки для битового RELATIVE. rownum игнорируется для всех остальных значений. Дополнительные сведения см. в разделе с примечаниями.

nrows

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

nrows игнорируется значением REFRESHбита извлечения . Дополнительные сведения см. в разделе с примечаниями.

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

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

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

<rownum>	Установить в
Если не открыт	0
Если позиционирован перед результирующим набором	0
Если позиционирован после результирующего набора	-1
Для KEYSET и STATIC курсоров	Абсолютный номер строки в текущей позиции результирующего набора
Для DYNAMIC курсоров	1
При анализе служб ABSOLUTE	-1 возвращает последнюю строку в наборе. -2 возвращает вторую от конца строку в наборе и так далее. Примечание. Если запрашивается несколько строк для получения в этом случае, возвращаются последние две строки результирующих наборов.

<nrows>	Установить в
Если не открыт	0
Для KEYSET и STATIC курсоров	Обычно размер текущего набора ключей. -m Если курсор находится в асинхронном создании с строками m , найденными до этой точки.
Для DYNAMIC курсоров	-1

Замечания

Параметр курсора

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

Параметр fetchtype

SKIP_UPD_CNCYЗа исключением значений типа получения, являются взаимоисключающими.

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

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

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

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

Параметр rownum

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

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

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

Параметр nrows

Значения REFRESH и INFO пропускают этот параметр.

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

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

Для значений набора значений NEXT, PREV, ABSOLUTERELATIVEи PREV_NOADJUST, nrow0 не является допустимым.

Рекомендации по RPC

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

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

Значение	Описание
0	Процедура успешно выполнена.
0x0001	Процедура завершилась ошибкой.
0x0002	Выборка в отрицательном направлении привела к тому, что позиция курсора оказалась в начале результирующего набора, когда выборка логически должна быть перед результатами.
0x10	Курсор FAST_FORWARD автоматически закрыт.

Строки возвращаются как типичный результирующий набор: формат столбца (), строки (0x2a0xd1), а затем DONE (0xfd). Маркеры метаданных отправляются в том же формате, что и для sp_cursoropenпользователей 0x81SQL Server, 0xa5 и 0xa4 т. д. Индикаторы состояния строки отправляются как скрытые столбцы, аналогичные BROWSE режиму, в конце каждой строки с строкой имени столбца и типом данных int. Этот столбец rowstat имеет одно из значений, показанных в следующей таблице.

Значение	Описание
0x0001	FETCH_SUCCEEDED
0x0002	FETCH_MISSING

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

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

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

Примеры

А. Изменение положения курсора с помощью PREV

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

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

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

Примечание.

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

B. Используйте PREV_NOADJUST для возврата меньше строк, чем PREV

PREV_NOADJUST никогда не включает ни одну из строк в блоке возвращаемых строк или после текущей позиции курсора. В случаях, когда PREV возвращает строки после текущей позиции, возвращает меньше строк, PREV_NOADJUST чем запрашивается в nrows. Учитывая текущую позицию в примере A ранее, 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

Связанный контент

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