Share via

  • Artigo

sp_cursoropen (Transact-SQL)

Abre um cursor. sp_cursoropen define a instrução SQL associada ao cursor e às opções do cursor e, em seguida, popula o cursor. sp_cursoropené equivalente à combinação das instruções Transact-SQL DECLARE_CURSOR e OPEN. Esse procedimento é invocado pela especificação de ID = 2 em um pacote TDS.

Ícone de vínculo de tópicoConvenções de sintaxe 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 valor de identificador que deve ser fornecido em todos os procedimentos subsequentes relacionados ao cursor, por exemplo, sp_cursorfetch. cursor é um parâmetro obrigatório com um valor de retorno int.

    cursor permite vários cursores 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 associação) de qualquer tipo (independentemente de Unicode, tamanho, etc.) pode servir como um tipo de valor stmt válido.

  • scrollopt
    Opção de rolagem. scrollopt é um parâmetro opcional que requer um dos valores de entrada int 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 o valor solicitado não ser apropriado para o cursor definido por stmt, este 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 valores de entrada int a seguir.

    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 ccopt solicitados.

  • rowcount
    O número de linhas do buffer de busca a serem usadas com AUTO_FETCH. O padrão é 20 linhas. rowcount se comporta de modo 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_FETCH de scrollopt é especificado, rowcount representa o número de linhas a serem colocadas no buffer de busca.

    ObservaçãoObservação
    >0 é um valor válido quando AUTO_FETCH é especificado; caso contrário, é ignorado.

    Representa o número de linhas no conjunto de resultados, exceto quando o valor AUTO_FETCH de scrollopt é especificado.

  • boundparam
    Significa o uso de parâmetros adicionais. boundparam é um parâmetro opcional que deverá ser especificado se o valor PARAMETERIZED_STMT de scrollopt for definido como ON.

Valores do código de retorno

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

  • 0
    Procedimento 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 operação FETCH está em andamento.

  • A
    Este cursor foi desalocado pelo SQL Server e não está disponível.

Quando um erro ocorrer, os valores de retorno poderão estar inconsistentes e a exatidão não pode ser garantida.

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

  • -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 colocadas no buffer de busca quando o valor AUTO_FETCH de scrollopt é especificado.

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

  • 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 foi fechado automaticamente.

ObservaçãoObservação

Se o procedimento sp_cursoropen for executado com êxito, serão enviados os parâmetros de retorno RPC e um conjunto de resultados com informações de formato de coluna TDS (mensagens 0xa1 e 0xa0). Caso contrário, uma ou mais mensagens de erro TDS serão enviadas. Em qualquer um dos casos, não serão retornados dados de linha e a contagem de mensagens concluídas será zero. Se você estiver usando uma versão do SQL Server anterior à 7.0, 0xa0 e 0xa1 (padrão para instruções SELECT) serão retornadas junto com os fluxos de token 0xa5 e 0xa4. Se você estiver usando o SQL Server 7.0, 0x81 será retornado (padrão para instruções SELECT) junto com os fluxos de token 0xa5 e 0xa4.

Comentários

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.

Os conteúdo permitido do parâmetro stmt depende de o valor de retorno ALLOW_DIRECT de ccopt ter sido vinculado por OR ao restante dos valores ccopt, isto é:

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

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

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

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

Parâmetro scrollopt

Os primeiros cinco valores scrollopt (KEYSEY, DYNAMIC, FORWARD_ONLY, STATIC e 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 vinculados 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_ACCEPTABLE ou FAST_FORWARD_ACCEPTABLE) também deverá ser ON.

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

Parâmetro ccopt

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

ObservaçãoObservação

A escolha de um dos quatro primeiros valores ccopt dita se o cursor é somente leitura, ou se são usados métodos de bloqueio ou otimistas para evitar atualizações perdidas. Se um valor ccopt não for especificado, o 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 pode ser vinculado por OR a READ_ONLY, SCROLL_LOCKS ou qualquer um dos valores OPTIMISTIC.

Se CHECK_ACCEPTED_TYPES for ON, pelo menos um dos últimos quatro valores ccopt (READ_ONLY_ACCEPTABLE, SCROLL_LOCKS_ACCEPTABLE e um dos valores OPTIMISTIC_ACCEPTABLE) também deverá ser ON.

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

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 da soma de verificação, conforme determinado pelo SQL Server. Se qualquer uma dessas linhas não corresponder, a operação falhará.

A especificação de UPDT_IN_PLACE como o valor de retorno controla os seguintes resultados:

  • Se não estiver definido durante a execução de uma atualização posicionada em uma tabela com um índice exclusivo, o cursor excluirá a linha de sua tabela de trabalho e a inserirá ao final de qualquer uma das colunas-chave usadas pelo cursor, alterando assim essas colunas.

  • Se estiver definido como ON, o cursor simplesmente atualizará as colunas-chave na linha original da tabela de trabalho.

Parâmetro bound_param

O nome de parâmetro deverá 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 de cursor sejam retornados no fluxo TDS.

Exemplos

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 neste formato:

{ tipo de dados local variable name } [,…n]

São usados parâmetros subsequentes para passar os valores a serem substituídos pelo local variable name na instrução.