CURSOR_STATUS (Transact-SQL)

Artigo
05/30/2023

Aplica-se a:SQL Server Banco de Dados SQL do Azure Instância Gerenciada de SQL do Azure

Para determinado parâmetro, CURSOR_STATUS mostra se uma declaração de cursor retornou ou não um cursor e conjunto de resultados.

Convenções de sintaxe de Transact-SQL

Sintaxe

CURSOR_STATUS   
     (  
          { 'local' , 'cursor_name' }   
          | { 'global' , 'cursor_name' }   
          | { 'variable' , 'cursor_variable' }   
     )

Observação

Para exibir a sintaxe do Transact-SQL para o SQL Server 2014 (12.x) e versões anteriores, confira a Documentação das versões anteriores.

Argumentos

'local'
Especifica uma constante indicando que a fonte do cursor é um nome de cursor local.

'cursor_name'
É o nome do cursor. Um nome de cursor deve estar em conformidade com as regras do identificador do banco de dados.

'global'
Especifica uma constante indicando que a fonte do cursor é um nome de cursor global.

'variável'
Especifica uma constante indicando que a fonte do cursor é uma variável local.

'cursor_variable'
É o nome da variável de cursor. Uma variável de cursor deve ser definida usando o tipo de dados cursor.

Tipos de retorno

smallint

Valor retornado	Cursor name	Variável de cursor
1	O conjunto de resultados do cursor tem, ao menos, uma linha. Para cursores insensitive e keyset, o conjunto de resultados terá ao menos uma linha. Para cursores dinâmicos, o conjunto de resultados pode ter zero, uma ou mais linhas.	O cursor alocado a esta variável está aberto. Para cursores insensitive e keyset, o conjunto de resultados terá ao menos uma linha. Para cursores dinâmicos, o conjunto de resultados pode ter zero, uma ou mais linhas.
0	O conjunto de resultados do cursor está vazio.*	O cursor alocado a esta variável está aberto, mas o conjunto de resultados está definitivamente vazio.*
-1	O cursor está fechado.	O cursor alocado a esta variável está fechado.
-2	Não aplicável.	Tem uma destas possibilidades: O procedimento chamado anteriormente não atribuiu um cursor a essa variável OUTPUT. O procedimento atribuído previamente atribuiu um cursor a essa variável OUTPUT, mas o cursor estava em estado de fechamento na conclusão do procedimento. Portanto, o cursor é desalocado, e não é retornado ao procedimento de chamada. Nenhum cursor é atribuído à variável de cursor declarada.
-3	Um cursor com o nome especificado não existe.	Uma variável de cursor com o nome especificado não existe ou, se existe, nenhum cursor foi alocado a ela ainda.

*Cursores dinâmicos nunca retornam esse resultado.

Exemplos

Este exemplo usa a função CURSOR_STATUS para mostrar o status de um cursor, após sua declaração, depois que ele é aberto e depois que é fechado.

CREATE TABLE #TMP  
(  
   ii INT  
)  
GO  
  
INSERT INTO #TMP(ii) VALUES(1)  
INSERT INTO #TMP(ii) VALUES(2)  
INSERT INTO #TMP(ii) VALUES(3)  
  
GO  
  
--Create a cursor.  
DECLARE cur CURSOR  
FOR SELECT * FROM #TMP  
  
--Display the status of the cursor before and after opening  
--closing the cursor.  
  
SELECT CURSOR_STATUS('global','cur') AS 'After declare'  
OPEN cur  
SELECT CURSOR_STATUS('global','cur') AS 'After Open'  
CLOSE cur  
SELECT CURSOR_STATUS('global','cur') AS 'After Close'  
  
--Remove the cursor.  
DEALLOCATE cur  
  
--Drop the table.  
DROP TABLE #TMP

Este é o conjunto de resultados.

After declare
---------------
-1  
  
After Open
----------
1  
  
After Close
-----------
-1

Confira também

funções de cursor (Transact-SQL)
Tipos de dados (Transact-SQL)