sp_cursoropen (Transact-SQL)
Открывает курсор. Процедура sp_cursoropen определяет инструкцию SQL, связанную с курсором и параметрами курсора, а затем заполняет курсор. Хранимая процедура sp_cursoropenэквивалентна сочетанию инструкций Transact-SQL DECLARE_CURSOR и OPEN. Для вызова этой процедуры необходимо задать ID =2 в пакете потока табличных данных (TDS).
.gif "Значок ссылки на раздел")
Синтаксис
sp_cursoropen
cursor OUTPUT
,
stmt
[, scrollopt[ OUTPUT ] [ , ccopt[ OUTPUT ] [ ,rowcount OUTPUT [ ,boundparam][,...n]]] ]]
Аргументы
cursor
Идентификатор курсора, созданный системой SQL Server. Параметр cursor — это значение дескриптора, который должен передаваться при вызове всех последующих процедур, использующих курсор, например sp_cursorfetch. Параметр cursor является обязательным и требует возвращаемого значения типа int.Параметр cursor допускает несколько активных курсоров на одном соединении с базой данных.
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
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
OPTIMISTIC_ACCEPTABLE
Как и в случае с параметром scrollopt, SQL Server может переопределить запрошенные значения ccopt.
rowcount
Количество строк буфера выборки для AUTO_FETCH. Значение по умолчанию — 20 строк. Интерпретация параметра rowcount зависит от того, назначено значение как входное или как возвращаемое.Как входное значение
Как возвращаемое значение
Если задан параметр AUTO_FETCH, то параметр scrollopt, rowcount указывает количество строк, которое будет помещено в буфер выборки.
.gif "Примечание")
Примечание
>0 — допустимое значение, если задан параметр AUTO_FETCH; в противном случае это значение не используется.Представляет количество строк в результирующем наборе, за исключением случая, когда задается значение AUTO_FETCH для scrollopt.
boundparam
Обозначает использование дополнительных параметров. Параметр boundparam является необязательным и указывается в том случае, когда значение PARAMETERIZED_STMT для scrollopt равно ON.
Значения кодов возврата
Если не возникло ошибок, то процедура sp_cursoropen возвращает одно из следующих значений.
0
Процедура успешно выполнена.0x0001
Ошибка во время выполнения (незначительная ошибка, недостаточная для того, чтобы создать ошибку операции).0x0002
Выполняется асинхронная операция.0x0002
Выполняется операция FETCH.A
Курсор освобожден SQL Server и недоступен.
Если возникла ошибка, то возвращаемые значения могут быть несогласованными и точность не гарантируется.
Если параметр rowcount задан как возвращаемое значение, то результирующий набор будет следующим.
-1
Возвращается, если количество строк неизвестно или неприменимо.-n
Возвращается, если используется асинхронное заполнение. Представляет число строк, помещаемых в буфер выборки, если задано значение AUTO_FETCH для scrollopt.
Если используется RPC, то возвращаются следующие значения.
0
Процедура успешно выполнена.1
Процедура завершилась ошибкой.2
Курсор, управляемый набором ключей, формируется асинхронно.16
Курсор FAST_FORWARD автоматически закрыт.
| Примечание |
|---|
Если процедура sp_cursoropen выполнена успешно, то отправляются возвращаемые параметры RPC и результирующий набор с данными в виде столбцов TDS (сообщения 0xa0 и 0xa1). В случае ошибки отправляется одно или несколько сообщений TDS об ошибках. В обоих случаях данные строк не возвращаются, а счетчик сообщений done будет равен нулю. Если используется версия SQL Server ранее 7.0, то возвращаются сообщения 0xa0 и 0xa1 (стандартные для инструкции SELECT) с потоками токенов 0xa5 и 0xa4. Если используется SQL Server версии 7.0, то возвращается сообщение 0x81 (стандартное для инструкций SELECT) с потоками токенов 0xa5 и 0xa4. |
Замечания
Параметр stmt
Если параметр stmt задает выполнение хранимой процедуры, то входные параметры могут быть определены как константы в строке stmt или заданы как аргументы boundparam. Таким образом, объявленные переменные могут передаваться как связанные параметры.
Допустимое содержимое параметра stmt зависит от того, было ли возвращаемое значение ALLOW_DIRECT для ccopt связано с остальными значениями параметра ccopt оператором OR, т. e.:
Если параметр ALLOW_DIRECT не задан, то должна использоваться инструкция Transact-SQL SELECT или EXECUTE, вызывающая хранимую процедуру, в которой содержится одна инструкция SELECT. Кроме того, инструкция SELECT должна квалифицироваться как курсор, т. е. не может содержать ключевые слова SELECT INTO, FOR BROWSE или COMPUTE.
Если параметр ALLOW_DIRECT задан, то результатом может быть одна или несколько инструкций Transact-SQL, включая те, которые в свою очередь выполняют другие хранимые процедуры с большим количеством инструкций. Инструкции, кроме SELECT, а также любая инструкция SELECT с ключевыми словами SELECT INTO, FOR BROWSE или COMPUTE будут просто выполнены и не приведут к созданию курсора. Это относится и к любой инструкции SELECT, включенной в пакет из нескольких инструкций. Если инструкция SELECT содержит предложения, относящиеся только к курсорам, то эти предложения пропускаются. Например, если параметр ccopt равен 0x2002, то запрашивается:
курсор с блокированием прокрутки, если только одна инструкция SELECT квалифицируется как курсор, или
прямое выполнение инструкции, если есть несколько инструкций, одна инструкция, не являющаяся инструкцией SELECT, или инструкция SELECT, которая не квалифицируется как курсор.
Параметр scrollopt
Первые пять значений 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, то хотя бы одно из последних пяти значений scrollopt (KEYSET_ACCEPTABLE, DYNAMIC_ACCEPTABLE, FORWARD_ONLY_ACCEPTABLE, STATIC_ACCEPTABLE или FAST_FORWARD_ACCEPTABLE) также должно быть равно ON.
Курсоры STATIC всегда открываются только для чтения. Это означает, что обновить базовую таблицу через этот курсор невозможно.
Параметр 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 задан, то имя параметра должно быть равно paramdef в соответствии с сообщением об ошибке в коде. Если PARAMETERIZED_STMT не задан, то имя в сообщении об ошибке не указывается.
Замечания по RPC
Входной флажок RPC RETURN_METADATA может быть установлен в 0x0001, чтобы в потоке TDS возвращались метаданные списка выбора курсора.
Примеры
Параметр bound_param
Все параметры после пятого передаются в план инструкции как входные. Первый параметр должен представлять собой строку следующего вида:
{ тип данных имени локальной переменной } [,…n]
Последующие параметры используются для передачи значений, которые должны заменить local variable name в инструкции.
См. также