sp_describe_cursor (Transact-SQL)
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 = ] 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 recebimento da saída do cursor. output_cursor_variable é 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 aberto por um aplicativo ODBC que, em seguida, chamado de 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 de cursor Transact-SQL. Isso permite que lotes transact-SQL, procedimentos armazenados e gatilhos funcionem 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 estar 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 cursor de associação.
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. Em SQL Server, se o cursor tiver sido criado definindo uma variável de cursor como um cursor, cursor_name retornará 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 | 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 = Conjunto de chaves 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, confira @@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 saber mais, confira @@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 solicitar um tipo de cursor que SQL Server não pode dar suporte ao uso da instrução SELECT contida no CURSOR DECLARE. SQL Server converte implicitamente o cursor em um tipo que ele pode dar suporte usando a instrução SELECT. Se TYPE_WARNING for especificado na instrução DECLARE CURSOR, SQL Server enviará ao aplicativo uma mensagem informativa informando 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 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
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)
Comentários
https://aka.ms/ContentUserFeedback.
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulteEnviar e exibir comentários de