sp_cursoropen (Transact-SQL)

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

Открывает курсор. sp_cursoropen определяет инструкцию SQL, связанную с параметрами курсора и курсора, а затем заполняет курсор. sp_cursoropen эквивалентен сочетанию инструкций Transact-SQL DECLARE_CURSOR и OPEN. Для вызова этой процедуры необходимо задать ID =2 в пакете потока табличных данных (TDS).

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

Синтаксис

  
sp_cursoropen cursor OUTPUT, stmt  
    [, scrollopt[ OUTPUT ] [ , ccopt[ OUTPUT ]  
    [ ,rowcount OUTPUT [ ,boundparam][,...n]]] ]]  

Аргументы

курсор
Идентификатор курсора, созданный на SQL Server. курсор — это значение дескриптора , которое должно быть предоставлено во всех последующих процедурах, связанных с курсором, например sp_cursorfetch. курсор является обязательным параметром с возвращаемым значением int .

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

stmt
Обязательный параметр, который определяет результирующий набор курсора. Любая допустимая строка запроса (синтаксис и привязка) любого типа строки (независимо от Юникода, размера и т. д.) может служить допустимым типом значения stmt .

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

значение	Описание
0x0001	KEYSET
0x0002	DYNAMIC
0x0004	FORWARD_ONLY
0x0008	STATIC
0x10	FAST_FORWARD
0x1000	PARAMETERIZED_STMT
0x2000	AUTO_FETCH
0x4000	AUTO_CLOSE
0x8000	CHECK_ACCEPTED_TYPES
0x10000	KEYSET_ACCEPTABLE
0x20000	DYNAMIC_ACCEPTABLE
0x40000	FORWARD_ONLY_ACCEPTABLE
0x80000	STATIC_ACCEPTABLE
0x100000	FAST_FORWARD_ACCEPTABLE

Из-за возможности, что запрошенное значение не подходит для курсора, определенного stmt, этот параметр служит как входными, так и выходными данными. В таких случаях SQL Server присваивает соответствующее значение.

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

значение	Описание
0x0001	READ_ONLY
0x0002	SCROLL_LOCKS (прежнее название — LOCKCC)
0x0004	ОПТИМИСТИЧНЫЙ (ранее известный как OPTCC)
0x0008	OPTIMISTIC (прежнее название — OPTCCVAL)
0x2000	ALLOW_DIRECT
0x4000	UPDT_IN_PLACE
0x8000	CHECK_ACCEPTED_OPTS
0x10000	READ_ONLY_ACCEPTABLE
0x20000	SCROLL_LOCKS_ACCEPTABLE
0x40000	OPTIMISTIC_ACCEPTABLE
0x80000	OPTIMISTIC_ACCEPTABLE

Как и при прокрутке, SQL Server может переопределить запрошенные значения ccopt .

Rowcount
Количество строк буфера выборки для AUTO_FETCH. Значение по умолчанию составляет 20 строк. Строка ведет себя по-разному при назначении в качестве входного значения и возвращаемого значения.

Как входное значение	Как возвращаемое значение
Если задано значение прокрутки AUTO_FETCH rowcount, представляет количество строк, которые нужно поместить в буфер получения. Примечание. >0 является допустимым значением при указании AUTO_FETCH, но в противном случае игнорируется.	Представляет количество строк в результирующем наборе, за исключением случаев, когда задано значение прокрутки AUTO_FETCH.

-

boundparam
Означает использование дополнительных параметров. boundparam является необязательным параметром, который следует указать, если значение scrollopt PARAMETERIZED_STMT имеет значение ON.

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

Если не возникло ошибок, то процедура sp_cursoropen возвращает одно из следующих значений.

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

0x0001
Ошибка во время выполнения (незначительная ошибка, недостаточная для того, чтобы создать ошибку операции).

0x0002
Выполняется асинхронная операция.

0x0002
Выполняется операция FETCH.

а
Этот курсор был освобожден SQL Server и недоступен.

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

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

-1
Возвращается, если количество строк неизвестно или неприменимо.

-n
Возвращается, если используется асинхронное заполнение. Представляет количество строк, которые были помещены в буфер получения при указании значения прокрутки AUTO_FETCH.

Если используется RPC, то возвращаются следующие значения.

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

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

2
Курсор, управляемый набором ключей, формируется асинхронно.

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

Примечание.

Если процедура sp_cursoropen выполнена успешно, отправляются параметры возврата RPC и результирующий набор с сведениями о формате столбца TDS (0xa0 и 0xa1 сообщениях). В случае ошибки отправляется одно или несколько сообщений TDS об ошибках. В любом случае данные строки не будут возвращены, и количество выполненных сообщений будет равно нулю. Если вы используете версию SQL Server ранее 7.0, 0xa0 0xa1 (стандартный для инструкций SELECT) возвращаются вместе с 0xa5 и потоками маркеров 0xa4. Если вы используете SQL Server 7.0, 0x81 возвращается (стандартный для инструкций SELECT) вместе с потоками маркеров 0xa5 и 0xa4 маркеров.

Замечания

Параметр stmt

Если stmt указывает выполнение хранимой процедуры, входные параметры могут быть определены как константы как часть строки stmt или указаны в качестве аргументов boundparam . Таким образом, объявленные переменные могут передаваться как связанные параметры.

Допустимое содержимое параметра stmt зависит от того, связан ли ccopt ALLOW_DIRECT возвращаемое значение or к остальным значениям ccopt, т. е.

• Если ALLOW_DIRECT не задано, необходимо использовать инструкцию Transact-SQL SELECT или EXECUTE для хранимой процедуры, содержащей одну инструкцию SELECT. Кроме того, оператор SELECT должен быть курсором; То есть он не может содержать ключевое слово SELECT INTO или FOR BROWSE.

• Если указана ALLOW_DIRECT, это может привести к одной или нескольким инструкциям Transact-SQL, включая те, которые, в свою очередь, выполняют другие хранимые процедуры с несколькими операторами. Инструкции, кроме SELECT, а также любая инструкция SELECT с ключевыми словами SELECT INTO или FOR BROWSE будут просто выполнены и не приведут к созданию курсора. Это относится и к любой инструкции SELECT, включенной в пакет из нескольких инструкций. Если инструкция SELECT содержит предложения, относящиеся только к курсорам, то эти предложения пропускаются. Например, если значение ccopt 0x2002, это запрос:

  • курсор с блокированием прокрутки, если только одна инструкция SELECT квалифицируется как курсор, или

  • прямое выполнение инструкции, если есть несколько инструкций, одна инструкция, не являющаяся инструкцией SELECT, или инструкция SELECT, которая не квалифицируется как курсор.

Параметр scrollopt

Первые пять значений прокрутки (KEYSEY, DYNAMIC, FORWARD_ONLY, STATIC и FAST_FORWARD) являются взаимоисключающими.

PARAMETERIZED_STMT и CHECK_ACCEPTED_TYPES не могут быть связаны ни с одним из пяти первых значений оператором OR.

AUTO_FETCH и AUTO_CLOSE могут быть связаны оператором OR только с FAST_FORWARD.

Если CHECK_ACCEPTED_TYPES имеет значение ON, необходимо также включить по крайней мере одно из последних пяти значений прокрутки (KEYSET_ACCEPTABLE, DYNAMIC_ACCEPTABLE, FORWARD_ONLY_ACCEPTABLE, STATIC_ACCEPTABLE или FAST_FORWARD_ACCEPTABLE).

Курсоры STATIC всегда открываются только для чтения. Это означает, что обновить базовую таблицу через этот курсор невозможно.

Параметр ccopt

Первые четыре значения ccopt (READ_ONLY, SCROLL_LOCKS и КАК ОПТИМИСТИЧЕСКИЕ значения) являются взаимоисключающими.

Примечание.

Выбор одного из первых четырех значений ccopt определяет, доступен ли курсор только для чтения, или если блокировка или оптимистичные методы используются для предотвращения потерянных обновлений. Если значение ccopt не указано, значение по умолчанию — ОПТИМИСТИЧНО.

ALLOW_DIRECT и CHECK_ACCEPTED_TYPES могут быть связаны оператором OR с любым из первых четырех значений.

Параметр UPDT_IN_PLACE может быть связан оператором OR с READ_ONLY, SCROLL_LOCKS и любым из значений OPTIMISTIC.

Если CHECK_ACCEPTED_TYPES имеет значение ON, то не менее одного из последних четырех значений ccopt (READ_ONLY_ACCEPTABLE, SCROLL_LOCKS_ACCEPTABLE и любого из значений OPTIMISTIC_ACCEPTABLE) также должно быть ON.

Размещенные функции UPDATE и DELETE могут выполняться только в буфере получения и только в том случае, если значение ccopt равно SCROLL_LOCKS или ОПТИМИСТИЧНО. Если заданное значение — SCROLL_LOCKS, то операция будет гарантированно выполнена успешно. Если задано значение OPTIMISTIC, то операция закончится ошибкой, если строка изменилась с момента последней выборки.

Причина этого сбоя заключается в том, что если ПАРАМЕТР ОПТИМИСТИЧНО является указанным значением, функция оптимистического управления валютой выполняется путем сравнения меток времени или значений проверка сумы, как определено SQL Server. Если какие-либо из этих строк не совпадают, то операция завершится ошибкой.

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

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

• Если параметр равен ON, то курсор просто обновит ключевые столбцы в исходной строке рабочей таблицы.

Параметр bound_param

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

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

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

Примеры

Параметр bound_param

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

{ тип данных имени локальной переменной } [,... n]

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

См. также

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