sp_describe_cursor (Transact-SQL)

Informa os atributos de um cursor de servidor.

Convenções de sintaxe Transact-SQL

Sintaxe

sp_describe_cursor [ @cursor_return = ] output_cursor_variable OUTPUT 
     { [ , [ @cursor_source = ] N'local'
    , [ @cursor_identity = ] N'local_cursor_name' ] 
   | [ , [ @cursor_source = ] N'global'
    , [ @cursor_identity = ] N'global_cursor_name' ] 
   | [ , [ @cursor_source = ] N'variable'
     , [ @cursor_identity = ] N'input_cursor_variable' ] 
     } 

Argumentos

• [ @cursor_return = ] output_cursor_variable OUTPUT
  É o nome de uma variável de cursor declarada para receber a saída do curso. output_cursor_variable é cursor, sem padrão, e não deve estar associado a qualquer cursor no momento em que que sp_describe_cursor é chamado. O cursor retornado é um cursor rolável, dinâmico, somente leitura.

• [ @cursor_source = ] { N'local' | N'global' | N'variable' }
  Especifica se o cursor que está sendo relatado está especificado usando o nome de um cursor local, de um cursor global ou de uma variável de cursor. O parâmetro é nvarchar(30).

• [ @cursor_identity = ] N'local_cursor_name' ]
  É o nome de um cursor criado por uma instrução DECLARE CURSOR, que tem a palavra-chave LOCAL ou que adotou o padrão LOCAL. local_cursor_name é nvarchar(128).

• [ @cursor_identity = ] N'global_cursor_name' ]
  É o nome de um cursor criado por uma instrução DECLARE CURSOR, que tem a palavra-chave GLOBAL ou que adotou o padrão GLOBAL. global_cursor_name é nvarchar(128).

  global_cursor_name também pode ser o nome de um cursor de servidor de API que é aberto por um aplicativo ODBC que então nomeou chamando SQLSetCursorName.

• [ @cursor_identity = ] N'input_cursor_variable' ]
  É o nome de uma variável de cursor associada a um cursor aberto. input_cursor_variable é nvarchar(128).

Valores de código de retorno

Nenhum

Cursores retornados

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

A tabela a seguir mostra o formato do cursor retornado ao se usar sp_describe_cursor. O formato do cursor é o mesmo formato retornado ao se usar 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 for feita através do nome especificado em uma instrução DECLARE CURSOR, o nome de referência será igual ao nome de 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 instrução DECLARE CURSOR. No SQL Server, se o cursor foi criado configurando-se uma variável de cursor como um cursor, cursor_name retornará o nome da variável de cursor. Em versões mais recentes do SQL Server, essa coluna de saída retorna um nome gerado pelo sistema.
cursor_scope	tinyint	1 = LOCAL 2 = GLOBAL
status	int	Mesmos valores como relatado pela função do sistema CURSOR_STATUS: 1 = o cursor referido pelo nome do cursor ou variável de cursor está aberto. Se o cursor for insensível, estático, ou controlado por um conjunto de chaves, terá ao menos uma linha. Se o cursor for dinâmico, o conjunto de resultados terá zero ou mais linhas. 0 = o cursor referido pelo nome do cursor ou variável de cursor está aberto, mas não contém linhas. Cursores dinâmicos nunca retornam esse valor. -1 = o cursor referido pelo nome do cursor ou variável de cursor está fechado. -2 = só se aplica a variáveis de cursor. Não há nenhum cursor atribuído à variável. Possivelmente, um parâmetro OUTPUT nomeou 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 nenhum cursor foi alocado à variável de cursor.
modelo	tinyint	1 = Insensível (ou estático) 2 = Conjunto de chaves 3 = Dinâmico 4 = Avançar
simultaneidade	tinyint	1 = Apenas leitura 2 = Bloqueios de rolagem 3 = Otimista
rolável	tinyint	0 = Somente avanço 1 = Rolável
open_status	tinyint	0 = Fechado 1 = Abra
cursor_rows	decimal(10,0)	Número de linhas de qualificação no conjunto de resultados. Para obter mais informações, consulte @@CURSOR_ROWS (Transact-SQL).
fetch_status	smallint	Status da última busca nesse cursor. Para obter mais informações, consulte @@FETCH_STATUS (Transact-SQL). 0 = Busca bem sucedida. -1 = Busca falhou ou está além dos limites do cursor. -2 = A linha solicitada está ausente. -9 = Não houve busca 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 (Transact-SQL).
last_operation	tinyint	Última operação executada no cursor: 0 = Nenhum 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 globais a um cursor de servidor, como a habilidade para 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 de servidor Transact-SQL visíveis na conexão, use sp_cursor_list.

Uma instrução DECLARE CURSOR pode exigir um tipo de cursor que o SQL Server não suporta usando a instrução SELECT que está contida no DECLARE CURSOR. O SQL Server converte o cursor implicitamente a um tipo que ofereça suporte para usar a instrução SELECT. Se TYPE_WARNING for especificado na instrução DECLARE CURSOR, o SQL Server enviará ao aplicativo uma mensagem informativa de que uma conversão foi completada. sp_describe_cursor pode então ser chamado, para determinar o tipo de cursor implementado.

Permissões

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

Exemplos

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

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

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

Consulte também

Referência

CURSOR_STATUS (Transact-SQL)

DECLARE CURSOR (Transact-SQL)

sp_cursor_list (Transact-SQL)

sp_describe_cursor_columns (Transact-SQL)

sp_describe_cursor_tables (Transact-SQL)

Conceitos

Cursores (Mecanismo de Banco de Dados)