sp_cursoropen (Transact-SQL)

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

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

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

Синтаксис

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

Аргументы

курсор

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

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

stmt

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

scrollopt

Параметр прокрутки. Параметр scrollopt имеет значение int, значение по умолчанию NULLи может быть одним из следующих значений.

значение Описание
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 OPTIMISTIC (ранее известный как 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 OPTIMISITC_ACCEPTABLE

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

строка

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

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

Примечание. > 0 Допустимое значение при AUTO_FETCH указании, но в противном случае игнорируется.
Представляет количество строк в результирующем наборе, за исключением случаев, когда задано значение прокруткиAUTO_FETCH.

boundparam

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

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

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

значение Описание
0 Процедура успешно выполнена.
0x0001 Ошибка во время выполнения (незначительная ошибка, недостаточная для того, чтобы создать ошибку операции).
0x0002 Выполняется асинхронная операция.
0x0002 Операция FETCH выполняется.
A Этот курсор был освобожден и недоступен.

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

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

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

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

значение Описание
0 Процедура успешно выполнена.
1 Процедура завершилась ошибкой.
2 Курсор, управляемый набором ключей, формируется асинхронно.
16 Курсор FAST_FORWARD автоматически закрыт.

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

Замечания

Параметр stmt

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

Допустимое содержимое параметра stmt зависит от того, было ли возвращаемое значение ccopt связано с остальными значениями OR ccoptALLOW_DIRECT:

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

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

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

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

Параметр scrollopt

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

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

AUTO_FETCH и AUTO_CLOSE может быть связан с OR FAST_FORWARD.

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

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

Параметр ccopt

Первые четыре значения ccopt (READ_ONLY, SCROLL_LOCKSи оба значения) являются взаимоисключающими OPTIMISTIC .

Примечание.

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

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 или OPTIMISTIC. Если SCROLL_LOCKS задано значение, операция гарантированно будет выполнена успешно. Если OPTIMISTIC задано значение, операция завершается ошибкой, если строка изменилась после последнего получения.

Причина этого сбоя заключается в том, что при OPTIMISTIC указании значения функция оптимистического управления валютой выполняется путем сравнения меток времени или значений контрольной суммы, как определено SQL Server. Если какая-либо из этих строк не соответствует, операция завершается ошибкой.

Указание UPDT_IN_PLACE в качестве возвращаемого значения управляет следующими результатами:

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

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

Параметр bound_param

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

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

Флаг ввода RPC RETURN_METADATA можно задать для 0x0001 запроса того, что метаданные списка выбора курсора возвращаются в потоке TDS.

Примеры

А. Параметр bound_param

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

<parameter_name> <data_type> [ ,... n ]

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