Partilhar via

sp_cursoropen (Transact-SQL)

  • Artigo

Aplica-se a:SQL Server

Abre um cursor. sp_cursoropen define a instrução SQL associada às opções de cursor e cursor e, em seguida, preenche o cursor. sp_cursoropen é equivalente à combinação das declarações Transact-SQL DECLARE_CURSOR e OPEN. Este procedimento é invocado especificando ID = 2 em um pacote de fluxo de dados tabular (TDS).

Transact-SQL convenções de sintaxe

Sintaxe

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

Argumentos

Importante

Os argumentos para procedimentos armazenados estendidos devem ser inseridos na ordem específica, conforme descrito na seção de sintaxe. Se os parâmetros forem inseridos fora de ordem, ocorrerá uma mensagem de erro.

cursor

Um identificador de cursor gerado pelo SQL Server. cursor é um valor handle que deve ser fornecido em todos os procedimentos subsequentes que envolvem o cursor, como sp_cursorfetch. O cursor parâmetro é int e não pode ser NULL.

do cursor permite que vários cursores estejam ativos em uma única conexão de banco de dados.

stmt

Um parâmetro obrigatório que define o conjunto de resultados do cursor. Qualquer cadeia de caracteres de consulta válida (sintaxe e ligação) de qualquer tipo de cadeia de caracteres (independentemente de Unicode, tamanho, etc.) pode servir como um válido stmt tipo de valor.

scrollopt

Opção de rolagem. O parâmetro scrollopt é int, com um padrão de NULL, e pode ser um dos seguintes valores.

Valor Descrição
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

Devido à possibilidade de que o valor solicitado não seja apropriado para o cursor definido por stmt, esse parâmetro serve como entrada e saída. Nesses casos, o SQL Server atribui um valor apropriado.

CCOPT

Opção de controle de simultaneidade. ccopt é um parâmetro opcional que requer um dos seguintes valores de entrada int.

Valor Descrição
0x0001 READ_ONLY
0x0002 SCROLL_LOCKS (anteriormente conhecido como LOCKCC)
0x0004 OPTIMISTIC (anteriormente conhecido como OPTCC)
0x0008 OPTIMISTIC (anteriormente conhecido como 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

Assim como scrollopt, o SQL Server pode substituir os valores de solicitados ccopt.

contagem de linhas

O número de linhas de buffer de busca para usar com AUTO_FETCH. O padrão é 20 linhas. rowcount se comporta de forma diferente quando atribuído como um valor de entrada versus um valor de retorno.

Como valor de entrada Como valor de retorno
Quando o valor AUTO_FETCHscrollopt é especificado, de contagem de linhas representa o número de linhas a serem colocadas no buffer de busca.

Nota:> 0 é um valor válido quando AUTO_FETCH é especificado, mas é ignorado.		 Representa o número de linhas no conjunto de resultados, exceto quando o valor scrolloptAUTO_FETCH é especificado.

boundparam

Significa o uso de parâmetros extras. boundparam é um parâmetro opcional que deve ser especificado se o valor scrolloptPARAMETERIZED_STMT estiver definido como ON.

Valores de código de retorno

Se nenhum erro for gerado, sp_cursoropen retornará um dos seguintes valores.

Valor Descrição
0 O procedimento foi executado com êxito.
0x0001 Ocorreu um erro durante a execução (um pequeno erro, não grave o suficiente para gerar um erro na operação).
0x0002 Uma operação assíncrona está em andamento.
0x0002 Está em curso uma operação FETCH.
A Este cursor foi desalocado e não está disponível.

Quando um erro é gerado, os valores de retorno podem ser inconsistentes e a precisão não pode ser garantida.

Quando o parâmetro rowcount é especificado como um valor de retorno, ocorre o seguinte conjunto de resultados.

Valor Descrição
-1 Retornado se o número de linhas for desconhecido ou não aplicável.
-n Retornado quando uma população assíncrona está em vigor. Representa o número de linhas que foram colocadas no buffer de busca quando o valor scrolloptAUTO_FETCH é especificado.

Se o RPC estiver em uso, os valores de retorno serão os seguintes.

Valor Descrição
0 O procedimento foi bem-sucedido.
1 Falha no procedimento.
2 Um cursor do conjunto de teclas está sendo gerado de forma assíncrona.
16 Um cursor de avanço rápido foi fechado automaticamente.

Se o procedimento sp_cursoropen for executado com êxito, os parâmetros de retorno RPC e um conjunto de resultados com informações de formato de coluna TDS (mensagens0xa0 e 0xa1) serão enviados. Se não tiver êxito, uma ou mais mensagens de erro TDS são enviadas. Em ambos os casos, nenhum dado de linha é retornado e a contagem de mensagens DONE é 0. 0x81 é retornado (padrão para instruções SELECT) juntamente com os fluxos de token 0xa5 e 0xa4.

Comentários

O parâmetro stmt

Se stmt especificar a execução de um procedimento armazenado, os parâmetros de entrada poderão ser definidos como constantes como parte da cadeia de caracteres stmt ou especificados como argumentos boundparam. As variáveis declaradas podem ser passadas como parâmetros vinculados desta forma.

O conteúdo permitido do parâmetro stmt depende se o valor de retorno ALLOW_DIRECT ccoptfoi ou não vinculado por OR ao resto dos valores de ccopt:

  • Se ALLOW_DIRECT não for especificado, uma instrução Transact-SQL SELECT ou EXECUTE chamando para um procedimento armazenado contendo uma única instrução SELECT deverá ser usada. Além disso, a declaração SELECT deve ser qualificada como um cursor; ou seja, não pode conter as palavras-chave SELECT INTO ou FOR BROWSE.

  • Se ALLOW_DIRECT for especificado, isso pode resultar em uma ou mais instruções Transact-SQL, incluindo instruções que executam outros procedimentos armazenados com várias instruções. Instruções nãoSELECT ou qualquer instrução SELECT que contenha as palavras-chave SELECT INTO ou FOR BROWSE são executadas e não resultam na criação de um cursor. O mesmo é verdadeiro para qualquer instrução SELECT incluída em um lote de várias instruções. Nos casos em que uma declaração SELECT contém cláusulas que dizem respeito apenas a cursores, essas cláusulas são ignoradas. Por exemplo, quando o valor de ccopt é 0x2002, trata-se de um pedido de:

    • Um cursor com bloqueios de rolagem, se houver apenas uma única instrução SELECT que se qualifique como cursor, ou

    • Uma execução direta de instrução se houver várias instruções, uma única instrução nãoSELECT ou uma instrução SELECT que não se qualifique como um cursor.

O parâmetro scrollopt

Os cinco primeiros valores scrollopt (KEYSEY, DYNAMIC, FORWARD_ONLY, STATICe FAST_FORWARD) são mutuamente exclusivos.

PARAMETERIZED_STMT e CHECK_ACCEPTED_TYPES podem ser vinculados por OR a qualquer um dos cinco primeiros valores.

AUTO_FETCH e AUTO_CLOSE podem ser ligados por OR a FAST_FORWARD.

Se CHECK_ACCEPTED_TYPES for ON, pelo menos um dos últimos cinco valores de scrollopt (KEYSET_ACCEPTABLE, DYNAMIC_ACCEPTABLE, FORWARD_ONLY_ACCEPTABLE, STATIC_ACCEPTABLEou FAST_FORWARD_ACCEPTABLE) também deve ser ON.

STATIC cursores são sempre abertos como READ_ONLY. Isto significa que a tabela subjacente não pode ser atualizada através deste cursor.

O parâmetro ccopt

Os quatro primeiros valores ccopt (READ_ONLY, SCROLL_LOCKSe ambos os valores OPTIMISTIC) são mutuamente exclusivos.

Observação

A escolha de um dos quatro primeiros valores de ccopt determina se o cursor é somente leitura ou se métodos de bloqueio ou otimistas são usados para evitar atualizações perdidas. Se um valor de ccopt não for especificado, o valor padrão será OPTIMISTIC.

ALLOW_DIRECT e CHECK_ACCEPTED_TYPES podem ser vinculados por OR a qualquer um dos quatro primeiros valores.

UPDT_IN_PLACE podem ser vinculados por OR a READ_ONLY, SCROLL_LOCKSou qualquer um dos valores OPTIMISTIC.

Se CHECK_ACCEPTED_TYPES for ON, pelo menos um dos últimos quatro valores de ccopt (READ_ONLY_ACCEPTABLE, SCROLL_LOCKS_ACCEPTABLEe qualquer um dos OPTIMISTIC_ACCEPTABLE valores) também deve estar ON.

As funções UPDATE e DELETE posicionadas podem ser executadas somente dentro do buffer de busca e somente se o valor ccopt for igual a SCROLL_LOCKS ou OPTIMISTIC. Se SCROLL_LOCKS for o valor especificado, a operação terá a garantia de êxito. Se OPTIMISTIC for o valor especificado, a operação falhará se a linha tiver sido alterada desde a última busca.

O motivo dessa falha é que, quando OPTIMISTIC é o valor especificado, uma função de controle de moeda otimista é executada comparando carimbos de data/hora ou valores de soma de verificação, conforme determinado pelo SQL Server. Se alguma dessas linhas não corresponder, a operação falhará.

Especificar UPDT_IN_PLACE como o valor de retorno rege os seguintes resultados:

  • Se não estiver definido ao executar uma atualização posicionada em uma tabela com um índice exclusivo, o cursor excluirá a linha de sua tabela de trabalho e a insere no final de qualquer uma das colunas de chave usadas pelo cursor, o que altera essas colunas.

  • Se definido ON, o cursor atualiza as colunas de teclas na linha original da tabela de trabalho.

O parâmetro bound_param

O nome do parâmetro deve ser paramdef quando PARAMETERIZED_STMT é especificado, de acordo com a mensagem de erro no código. Quando PARAMETERIZED_STMT não é especificado, nenhum nome é especificado na mensagem de erro.

Considerações sobre RPC

O sinalizador de entrada RPC RETURN_METADATA pode ser definido como 0x0001 para solicitar que os metadados da lista de seleção do cursor sejam retornados no fluxo TDS.

Exemplos

Um. O parâmetro bound_param

Quaisquer parâmetros após o quinto são passados para o plano de instrução como parâmetros de entrada. O primeiro desses parâmetros deve ser uma cadeia de caracteres na seguinte forma:

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

Os parâmetros subsequentes são usados para passar os valores a serem substituídos para o <parameter_name> na instrução.

Conteúdo relacionado