sp_cursor_list (Transact-SQL)

Aplica-se: SQL Server

Informa os atributos de cursores de servidor atualmente abertos para a conexão.

Convenções de sintaxe de Transact-SQL

Sintaxe

sp_cursor_list
    [ @cursor_return = ] cursor_return OUTPUT
    , [ @cursor_scope = ] cursor_scope
[ ; ]

Argumentos

@cursor_return [ = ] cursor_return SAÍDA

O nome de uma variável de cursor declarada. @cursor_return é um parâmetro OUTPUT do tipo CURSOR. O cursor é um cursor rolável, dinâmico, somente leitura.

@cursor_scope [ = ] cursor_scope

Especifica o nível dos cursores a serem relatados. @cursor_scope é int, sem padrão, e pode ser um desses valores.

Valor Descrição
1 Informar todos os cursores locais.
2 Informar todos os cursores globais.
3 Informar cursores locais e globais.

Valores do código de retorno

Nenhum.

Cursores retornados

sp_cursor_list retorna seu relatório como um parâmetro de saída de cursor Transact-SQL, não como um conjunto de resultados. 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 parâmetro de saída do cursor deve ser associado a uma variável de programa, mas as APIs de banco de dados não dão suporte à associação de parâmetros ou variáveis do cursor.

Este é o formato do cursor retornado por sp_cursor_list. O formato do cursor é o mesmo que o formato retornado por sp_describe_cursor.

Nome da coluna Tipo de dados Descrição
reference_name sysname O nome usado para se referir ao cursor. Se a referência ao cursor foi por meio do nome fornecido em uma DECLARE CURSOR instrução, o nome da referência é o mesmo que o nome do cursor. Se a referência ao cursor foi feita por uma variável, o nome da referência será o nome da variável do cursor.
cursor_name sysname O nome do cursor de uma DECLARE CURSOR instrução. No SQL Server, 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, essa coluna de saída retorna um nome gerado pelo sistema.
cursor_scope smallint 1 = LOCAL
2 = GLOBAL
status smallint 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 smallint 1 = Insensível (ou estático)
2 = Conjunto de chaves
3 = Dinâmico
4 = Avanço rápido
concurrency smallint 1 = Somente leitura
2 = Bloqueios de rolagem
3 = Otimista
scrollable smallint 0 = Somente encaminhamento
1 = Rolável
open_status smallint 0 = Fechado
1 = Aberto
cursor_rows int O número de linhas de qualificação no conjunto de resultados. Para obter mais informações, consulte @@CURSOR_ROWS.
fetch_status smallint O 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 = Não houve busca no cursor.
column_count smallint O número de colunas no conjunto de resultados do cursor.
row_count smallint O número de linhas afetadas pela última operação no cursor. Para obter mais informações, consulte @@ROWCOUNT.
last_operation smallint A ú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 que identifica o cursor dentro do escopo do servidor.

Comentários

sp_cursor_list Produz uma lista dos cursores de servidor atuais abertos pela conexão e descreve os atributos globais para cada cursor, como a capacidade de rolagem e atualização do cursor. Os cursores listados incluem sp_cursor_list :

  • Cursores do servidor Transact-SQL.

  • Cursores de servidor de API abertos por um aplicativo ODBC que é chamado SQLSetCursorName para nomear o cursor.

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. sp_describe_cursor relata as mesmas informações que sp_cursor_list, mas apenas para um cursor especificado.

Permissões

As permissões de execução têm como padrão a função public .

Exemplos

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

USE AdventureWorks2022;
GO

-- Declare and open a keyset-driven cursor.
DECLARE abc CURSOR KEYSET
FOR
SELECT LastName
FROM Person.Person
WHERE LastName LIKE 'S%';

OPEN abc;

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

-- Execute sp_cursor_list into the cursor variable.
EXEC master.dbo.sp_cursor_list
    @cursor_return = @Report OUTPUT,
    @cursor_scope = 2;

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

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

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