sp_cursoropen (Transact-SQL)

Открывает курсор. Процедура 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]]] ]]

Аргументы

• 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 указывает количество строк, которое будет помещено в буфер выборки. Примечание >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 в инструкции.

См. также

Справочник

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

Другие ресурсы

sp_cursorfetch (Transact-SQL)