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-SQLSELECTили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> инструкции.