sp_cursorfetch (Transact-SQL)

Применимо к:SQL Server

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

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

Синтаксис

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

Аргументы

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

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

Значение	Наименование	Описание
0x0001	ПЕРВЫЙ	Извлекает первый буфер строк nrows . Если nrows равно 0, курсор размещается перед результирующий набор и не возвращаются строки.
0x0002	ДАЛЕЕ	Извлекает следующий буфер строк nrows .
0x0004	PREV	Извлекает предыдущий буфер строк nrows . Примечание. Использование PREV для курсора FORWARD_ONLY возвращает сообщение об ошибке, так как FORWARD_ONLY поддерживает прокрутку только в одном направлении.
0x0008	ПОСЛЕДНЕЕ	Извлекает последний буфер строк nrows . Если nrows равно 0, курсор размещается после результирующий набор и не возвращаются строки. Примечание. Использование last для курсора FORWARD_ONLY возвращает сообщение об ошибке, так как FORWARD_ONLY поддерживает прокрутку только в одном направлении.
0x10	ABSOLUTE	Извлекает буфер строк nrows , начиная с строки rownum . Примечание. Использование ABSOLUTE для динамического курсора или курсора FORWARD_ONLY возвращает сообщение об ошибке, так как FORWARD_ONLY поддерживает прокрутку только в одном направлении.
0x20	Относительное значение	Извлекает буфер строк nrows, начиная с строки, указанной как значение строки строки из первой строки в текущем блоке. В этом случае строка может быть отрицательным числом. Примечание. Использование параметра RELATIVE для курсора FORWARD_ONLY возвращает сообщение об ошибке, так как FORWARD_ONLY поддерживает прокрутку только в одном направлении.
0x80	ОБНОВЛЕНИЕ	Перезаполняет буфер из базовых таблиц.
0x100	INFO	Извлекает сведения о курсоре. Эти сведения возвращаются с помощью параметров rownum и nrows . Поэтому при указании INFO строки и nrows становятся выходными параметрами .
0x200	PREV_NOADJUST	Используется как PREV. Но если вершина результирующего набора встретилась преждевременно, результаты могут отличаться.
0x400	SKIP_UPDT_CNCY	Необходимо использовать с одним из других значений набора данных , за исключением INFO.

Заметка

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

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

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

nrows
Необязательный параметр, используемый для указания количества выбираемых строк. Если nrows не указан, значение по умолчанию — 20 строк. Чтобы задать позицию без возврата данных, укажите значение 0. При применении nrows к запросу 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

За исключением 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

Значения выборки REFRESH и INFO игнорируют этот параметр.

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

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

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

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

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

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

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

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

значение	Description
0x0001	FETCH_SUCCEEDED
0x0002	FETCH_MISSING

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

Счетчик строк DONE всегда будет содержать ноль. Сообщение 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_cursorfetch PREV с 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)