sp_describe_cursor (Transact-SQL)

  • Artigo

Aplica-se a: SQL Server

Informa os atributos de um cursor de servidor.

Convenções de sintaxe de Transact-SQL

Sintaxe

sp_describe_cursor
    [ @cursor_return = ] cursor_return OUTPUT
    , [ @cursor_source = ] { N'local' | N'global' | N'*cursor_source*' }
    , [ @cursor_identity = ] N'cursor_identity'
[ ; ]

Argumentos

@cursor_return [ = ] cursor_return SAÍDA

O nome de uma variável de cursor declarada para receber a saída do cursor. @cursor_return é um parâmetro OUTPUT do tipo int, sem padrão, e não deve ser associado a nenhum cursor no momento sp_describe_cursor em que é chamado. O cursor retornado é um cursor rolável, dinâmico, somente leitura.

@cursor_source [ = ] { N'local' | N'global' | N'cursor_source' }

Especifica se o cursor que está sendo relatado é especificado usando o nome de um cursor local , um cursor global ou uma variável de cursor. @cursor_source é nvarchar(30), sem padrão.

@cursor_identity [ = ] N'cursor_identity'

O nome de um cursor criado por uma DECLARE CURSOR instrução. @cursor_identity é nvarchar(128), sem padrão.

  • Se cursor tiver a palavra-chave ou for padronizado LOCAL para LOCAL, @cursor_identity será local.

  • Se cursor tiver a palavra-chave ou for padronizado GLOBAL para GLOBAL, @cursor_identity será global. @cursor_identity também pode ser o nome de um cursor de servidor de API aberto por um aplicativo ODBC e, em seguida, nomeado chamando SQLSetCursorName.

  • Caso contrário, @cursor_identity é o nome de uma variável de cursor associada a um cursor aberto.

Valores do código de retorno

Nenhum.

Cursores retornados

sp_describe_cursor encapsula seu conjunto de resultados em um parâmetro de saída Transact-SQL cursor . Isso permite que lotes, procedimentos armazenados e gatilhos do Transact-SQL funcionem com a saída uma linha por vez. Isso também significa que o procedimento não pode ser chamado diretamente das funções da API do banco de dados. O cursor parâmetro de saída deve ser associado a uma variável de programa, mas as APIs de banco de dados não dão suporte a parâmetros ou variáveis de associação cursor .

A tabela a seguir mostra o formato do cursor retornado usando sp_describe_cursoro . O formato do cursor é o mesmo que o formato retornado usando sp_cursor_list.

Nome da coluna Tipo de dados Descrição
reference_name sysname Nome usado para se referir ao cursor. Se a referência ao cursor foi por meio do nome especificado em uma DECLARE CURSOR instrução, o nome da referência será o mesmo que o nome do cursor. Se a referência ao cursor for feita por uma variável, o nome de referência será o nome da variável.
cursor_name sysname Nome do cursor de uma DECLARE CURSOR instrução. Se o cursor foi criado definindo uma variável de cursor como um cursor, cursor_name retorna o nome da variável de cursor. Em versões anteriores do SQL Server, essa coluna de saída retorna um nome gerado pelo sistema.
cursor_scope tinyint 1 = LOCAL
2 = GLOBAL
status int Os mesmos valores relatados pela função do CURSOR_STATUS sistema:

1 = O cursor referenciado pelo nome ou variável do cursor está aberto. Se o cursor for insensível, estático ou conjunto de chaves, será pelo menos uma linha. Se o cursor for dinâmico, o conjunto de resultados terá zero ou mais linhas.
0 = O cursor referenciado pelo nome ou variável do cursor está aberto, mas não tem linhas. Cursores dinâmicos nunca retornam esse valor.
-1 = O cursor referenciado pelo nome ou variável do cursor é fechado.
-2 = Aplica-se somente a variáveis de cursor. Não há cursor atribuído à variável. Possivelmente, um OUTPUT parâmetro atribuiu um cursor à variável, mas o procedimento armazenado fechou o cursor antes de retornar.
-3 = Um cursor ou variável de cursor com o nome especificado não existe, ou a variável de cursor não tem um cursor alocado para ela.
model tinyint 1 = Insensível (ou estático)
2 = Conjunto de chaves
3 = Dinâmico
4 = Avanço rápido
concurrency tinyint 1 = Somente leitura
2 = Bloqueios de rolagem
3 = Otimista
scrollable tinyint 0 = Somente encaminhamento
1 = Rolável
open_status tinyint 0 = Fechado
1 = Aberto
cursor_rows decimal(10,0) Número de linhas de qualificação no conjunto de resultados. Para obter mais informações, consulte @@CURSOR_ROWS.
fetch_status smallint Status da última busca nesse cursor. Para obter mais informações, consulte @@FETCH_STATUS.

0 = Busca bem-sucedida.
-1 = A busca falhou ou está além dos limites do cursor.
-2 = A linha solicitada está faltando.
-9 = Nenhuma busca ocorreu no cursor.
column_count smallint Número de colunas no conjunto de resultados do cursor.
row_count decimal(10,0) Número de linhas afetadas pela última operação no cursor. Para obter mais informações, consulte @@ROWCOUNT.
last_operation tinyint Última operação executada no cursor:

0 = Nenhuma operação foi executada no cursor.
1 = OPEN
2 = FETCH
3 = INSERT
4 = UPDATE
5 = DELETE
6 = CLOSE
7 = DEALLOCATE
cursor_handle int Um valor exclusivo para o cursor dentro do escopo do servidor.

Comentários

sp_describe_cursor Descreve os atributos que são globais para um cursor de servidor, como a capacidade de rolar e atualizar. Use sp_describe_cursor_columns para uma descrição dos atributos do conjunto de resultados retornado pelo cursor. Use sp_describe_cursor_tables para um relatório das tabelas base referenciadas pelo cursor. Para obter um relatório dos cursores do servidor Transact-SQL visíveis na conexão, use sp_cursor_list.

Uma DECLARE CURSOR instrução pode solicitar um tipo de cursor ao qual o SQL Server não pode dar suporte usando a SELECT instrução contida no DECLARE CURSOR. O SQL Server converte implicitamente o cursor em um tipo ao qual ele pode dar suporte usando a SELECT instrução. Se TYPE_WARNING for especificado na instrução, o DECLARE CURSOR SQL Server enviará ao aplicativo uma mensagem informativa informando que uma conversão foi concluída. sp_describe_cursor pode então ser chamado para determinar o tipo de cursor que foi implementado.

Permissões

Requer associação à função pública .

Exemplos

O exemplo a seguir abre um cursor global e usa sp_describe_cursor para informar os atributos do cursor.

USE AdventureWorks2022;
GO
-- Declare and open a global cursor.
DECLARE abc CURSOR STATIC FOR
SELECT LastName
FROM Person.Person;

OPEN abc;

-- Declare a cursor variable to hold the cursor output variable
-- from sp_describe_cursor.
DECLARE @Report CURSOR;

-- Execute sp_describe_cursor into the cursor variable.
EXEC master.dbo.sp_describe_cursor
    @cursor_return = @Report OUTPUT,
    @cursor_source = N'global',
    @cursor_identity = N'abc';

-- Fetch all the rows from the sp_describe_cursor output cursor.
FETCH NEXT from @Report;
WHILE (@@FETCH_STATUS <> -1)
BEGIN
    FETCH NEXT from @Report;
END

-- Close and deallocate the cursor from sp_describe_cursor.
CLOSE @Report;
DEALLOCATE @Report;
GO

-- Close and deallocate the original cursor.
CLOSE abc;
DEALLOCATE abc;
GO

Conteúdo relacionado