Partilhar via

sp_cursoropen (Transact-SQL)

  • Artigo

Aplica-se: SQL Server

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

Convenções de sintaxe de Transact-SQL

Sintaxe

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

Argumentos

cursor

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

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

stmt

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

scrollopt

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

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 acontece com scrollopt, o SQL Server pode substituir os valores ccopt solicitados.

contagem de linhas

O número de linhas de buffer de busca a serem usadas 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 retornado.

Como valor de entrada Como valor de retorno
Quando o AUTO_FETCH valor scrollopt é especificado, rowcount 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 scrollopt AUTO_FETCH é especificado.

boundparam

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

Valores do código de retorno

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

Valor Descrição
0 O procedimento foi executado com êxito.
0x0001 Ocorreu um erro durante a execução (um erro secundário, não grave o bastante para gerar um erro na operação).
0x0002 Uma operação síncrona está em andamento.
0x0002 Uma FETCH operação está em andamento.
A Esse cursor foi desalocado e não está disponível.

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

Quando o parâmetro rowcount é especificado como um valor retornado, 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 scrollopt AUTO_FETCH é especificado.

Se o RPC estiver em uso, os valores de retorno serão como se segue.

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

Se o sp_cursoropen procedimento for executado com êxito, os parâmetros de retorno RPC e um conjunto de resultados com informações de formato de coluna TDS (0xa0 e 0xa1 mensagens) serão enviados. Caso contrário, uma ou mais mensagens de erro TDS serão enviadas. Em ambos os casos, nenhum dado de linha é retornado e a contagem de DONE mensagens é 0. 0x81 é retornado (padrão para SELECT instruções) junto com os fluxos de 0xa5 token 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 . Variáveis declaradas podem ser passadas como parâmetros associados dessa forma.

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

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

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

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

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

O parâmetro scrollopt

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

PARAMETERIZED_STMT e CHECK_ACCEPTED_TYPES pode ser vinculado por OR a qualquer um dos cinco primeiros valores.

AUTO_FETCH e AUTO_CLOSE pode ser ligado por OR a FAST_FORWARD.

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

STATIC Os cursores são sempre abertos como READ_ONLY. Isso significa que a tabela subjacente não pode ser atualizada por meio desse cursor.

O parâmetro ccopt

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

Observação

A escolha de um dos quatro primeiros valores 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 ccopt não for especificado, o valor padrão será OPTIMISTIC.

ALLOW_DIRECT e CHECK_ACCEPTED_TYPES pode ser vinculado por OR a qualquer um dos quatro primeiros valores.

UPDT_IN_PLACE pode ser vinculado por OR a READ_ONLY, SCROLL_LOCKS, ou qualquer um dos OPTIMISTIC valores.

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

Posicionado UPDATE e DELETE as funções podem ser executadas somente dentro do buffer de busca e somente se o valor ccopt for SCROLL_LOCKS igual ou OPTIMISTIC. Se SCROLL_LOCKS for o valor especificado, a operação terá a garantia de ser bem-sucedida. 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 qualquer uma dessas linhas não corresponder, a operação falhará.

Especificar UPDT_IN_PLACE como o valor retornado rege os seguintes resultados:

  • Se não for 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 inserirá no final de qualquer uma das colunas-chave usadas pelo cursor, o que altera essas colunas.

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

O parâmetro bound_param

O nome do parâmetro deve ser paramdef quando PARAMETERIZED_STMT for 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

R. 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 parâmetro deve ser uma cadeia de caracteres no seguinte formato:

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

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

Conteúdo relacionado