DEALLOCATE (Transact-SQL)

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

Remove uma referência de cursor. Quando a última referência de cursor é desalocada, as estruturas de dados que compõem o cursor são liberadas pelo Microsoft SQL Server.

Convenções de sintaxe de Transact-SQL

Sintaxe

DEALLOCATE { { [ GLOBAL ] cursor_name } | @cursor_variable_name }  

Argumentos

cursor_name
É o nome de um cursor já declarado. Se houver um cursor global e um cursor local com cursor_name como seus nomes, o cursor_name se referirá ao cursor global se GLOBAL for especificado e ao cursor local se GLOBAL não for especificado.

@cursor_variable_name
É o nome de uma variável de cursor. @cursor_variable_name precisa ser do tipo cursor.

Comentários

As instruções que operam em cursores usam um nome de cursor ou uma variável de cursor para se referir ao cursor. DEALLOCATE remove a associação entre um cursor e o nome de cursor ou variável de cursor. Se um nome ou uma variável forem os últimos a referenciarem o cursor, ele será desalocado e qualquer recurso usado por ele será liberado. Os bloqueios de rolagem usados para proteger o isolamento de buscas são liberados em DEALLOCATE. Os bloqueios de transação usados para proteger atualizações, incluindo atualizações posicionadas feitas através do cursor, são mantidos até o fim da transação.

A instrução DECLARE CURSOR aloca e associa um cursor a um nome de cursor.

DECLARE abc SCROLL CURSOR FOR  
SELECT * FROM Person.Person;  

Depois que um nome de cursor é associado a um cursor, o nome não pode ser usado para outro cursor do mesmo escopo (global ou local) até que este tenha sido desalocado.

Uma variável de cursor é associada a um cursor usando um destes dois métodos:

• Pelo nome usando uma instrução SET que define um cursor como uma variável de cursor.

  DECLARE @MyCrsrRef CURSOR;  
  SET @MyCrsrRef = abc;  
  

• Um cursor também pode ser criado e associado a uma variável sem ter um nome de cursor definido.

  DECLARE @MyCursor CURSOR;  
  SET @MyCursor = CURSOR LOCAL SCROLL FOR  
  SELECT * FROM Person.Person;  
  

Uma instrução DEALLOCATE <@cursor_variable_name> remove somente a referência da variável nomeada ao cursor. A variável não é desalocada até que saia do escopo no fim do lote, procedimento armazenado ou gatilho. Depois de uma instrução DEALLOCATE <@cursor_variable_name>, a variável pode ser associada a outro cursor usando a instrução SET.

USE AdventureWorks2022;  
GO  
  
DECLARE @MyCursor CURSOR;  
SET @MyCursor = CURSOR LOCAL SCROLL FOR  
    SELECT * FROM Sales.SalesPerson;  
  
DEALLOCATE @MyCursor;  
  
SET @MyCursor = CURSOR LOCAL SCROLL FOR  
    SELECT * FROM Sales.SalesTerritory;  
GO  

Uma variável de cursor não precisa ser desalocada explicitamente. A variável é implicitamente desalocada quando sai de escopo.

Permissões

As permissões para DEALLOCATE são padronizadas para qualquer usuário válido.

Exemplos

O script a seguir mostra como os cursores persistem até o último nome ou até a variável que os referenciam ser desalocada.

USE AdventureWorks2022;  
GO  
-- Create and open a global named cursor that  
-- is visible outside the batch.  
DECLARE abc CURSOR GLOBAL SCROLL FOR  
    SELECT * FROM Sales.SalesPerson;  
OPEN abc;  
GO  
-- Reference the named cursor with a cursor variable.  
DECLARE @MyCrsrRef1 CURSOR;  
SET @MyCrsrRef1 = abc;  
-- Now deallocate the cursor reference.  
DEALLOCATE @MyCrsrRef1;  
-- Cursor abc still exists.  
FETCH NEXT FROM abc;  
GO  
-- Reference the named cursor again.  
DECLARE @MyCrsrRef2 CURSOR;  
SET @MyCrsrRef2 = abc;  
-- Now deallocate cursor name abc.  
DEALLOCATE abc;  
-- Cursor still exists, referenced by @MyCrsrRef2.  
FETCH NEXT FROM @MyCrsrRef2;  
-- Cursor finally is deallocated when last referencing  
-- variable goes out of scope at the end of the batch.  
GO  
-- Create an unnamed cursor.  
DECLARE @MyCursor CURSOR;  
SET @MyCursor = CURSOR LOCAL SCROLL FOR  
SELECT * FROM Sales.SalesTerritory;  
-- The following statement deallocates the cursor  
-- because no other variables reference it.  
DEALLOCATE @MyCursor;  
GO  

Consulte Também

CLOSE (Transact-SQL)
Cursores
DECLARE @local_variable (Transact-SQL)
FETCH (Transact-SQL)
OPEN (Transact-SQL)