sp_describe_cursor (Transact-SQL)

Aplica-se a: simSQL Server (todas as versões compatíveis)

Informa os atributos de um cursor de servidor.

Ícone de link do tópico Convenções da 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 SAÍDA
É o nome de uma variável de cursor declarada para recebimento da saída do cursor. output_cursor_variable é o cursor, sem padrão e não deve ser associado a nenhum cursor no momento em 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 foi 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 chamado 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 do código de retorno

Nenhum

Cursores retornados

sp_describe_cursor encapsula seu conjunto de resultados em um parâmetro de saída do Transact-SQL cursor. Isso permite que lotes Transact-SQL, procedimentos armazenados e gatilhos trabalhem 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 de banco de dados. O parâmetro de saída do cursor deve ser vinculado a uma variável de programa, mas as APIs de banco de dados não são suportadas para associação de parâmetros de cursor ou variáveis.

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 , se o cursor tiver sido criado definindo uma variável de cursor como um cursor, cursor_name retornará o nome SQL Server 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 referenciado pelo nome do cursor ou pela 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 referenciado pelo nome ou pela variável do cursor está aberto, mas não contém linhas. Cursores dinâmicos nunca retornam esse valor.

-1 = O cursor referenciado pelo nome ou pela variável do cursor está fechado.

-2 = Aplicável somente a variáveis de cursor. Não há nenhum cursor atribuído à variável. Possivelmente, um parâmetro OUTPUT atribuiu um cursor à variável, mas o procedimento armazenado fechou o cursor antes de retornar.

-3 = Um cursor ou uma 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 = Keyset

3 = Dinâmico

4 = De avanço rápido
simultaneidade tinyint 1 = Somente leitura

2 = Bloqueios de rolagem

3 = Otimista
rolável tinyint 0 = Somente avanço

1 = Rolável
open_status tinyint 0 = Fechado

1 = Abrir
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 = A 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 = 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 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 obter 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 concluída. sp_describe_cursor pode ser chamado para determinar o tipo de cursor que foi implementado.

Permissões

Requer associação à função public.

Exemplos

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

USE AdventureWorks2012;  
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  

Consulte Também

Cursores
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)