WAITFOR (Transact-SQL)

Bloqueia a execução de um lote, procedimento armazenado ou transação até que uma hora ou intervalo de tempo especificado seja alcançado ou que uma instrução especificada modifique ou retorne pelo menos uma linha.

Convenções de sintaxe Transact-SQL

Sintaxe

WAITFOR 
{
    DELAY 'time_to_pass' 
  | TIME 'time_to_execute' 
  | [ ( receive_statement ) | ( get_conversation_group_statement ) ] 
    [ , TIMEOUT timeout ]
}

Argumentos

• DELAY
  É o período de tempo especificado que deve decorrer, até no máximo 24 horas, antes que a execução de um lote, procedimento armazenado ou transação prossiga.

• 'time_to_pass'
  É o período de tempo a esperar. time_to_pass pode ser especificado em um dos formatos aceitáveis para dados datetime ou pode ser especificado como uma variável local. Não é possível especificar datas; assim, a parte de data do valor de datetime não é permitida.

• TIME
  É a hora especificada em que o lote, o procedimento armazenado ou a transação é executada.

• 'time_to_execute'
  É a hora em que a instrução WAIFOR é concluída. time_to_execute pode ser especificado em um dos formatos aceitáveis para dados datetime ou pode ser especificado como uma variável local. Não é possível especificar datas; assim, a parte de data do valor de datetime não é permitida.

• receive_statement
  É uma instrução RECEIVE válida.

  Importante
  WAITFOR com uma receive_statement só é aplicável a mensagens do Service Broker. Para obter mais informações, consulte RECEIVE (Transact-SQL).

• get_conversation_group_statement
  É uma instrução GET CONVERSATION GROUP válida.

  Importante
  WAITFOR com uma get_conversation_group_statement só é aplicável a mensagens do Service Broker. Para obter mais informações, consulte GET CONVERSATION GROUP (Transact-SQL).

• TIMEOUT timeout
  Especifica o período de hora, em milissegundos, a esperar pela chegada de uma mensagem na fila.

  Importante
  A especificação de WAITFOR com TIMEOUT só é aplicável a mensagens do Service Broker. Para obter mais informações, consulte RECEIVE (Transact-SQL) e GET CONVERSATION GROUP (Transact-SQL).

Comentários

Ao executar a instrução WAITFOR, a transação está em execução e nenhuma outra solicitação pode executar sob a mesma transação.

O atraso de hora real pode variar da hora especificada em time_to_pass, time_to_execute ou timeout e depende do nível de atividade do servidor. A contador de tempo inicia quando o thread associado à instrução WAITFOR estiver agendado. Se o servidor estiver ocupado, o thread pode não ser agendado imediatamente; portanto, o atraso de tempo pode ser maior que o tempo especificado.

WAITFOR não altera as semânticas de uma consulta. Se uma consulta não puder retornar nenhuma linha, WAITFOR esperará para sempre ou até que TIMEOUT seja alcançado, se for especificado.

Não é possível abrir cursores em instruções WAITFOR.

Não é possível definir exibições em instruções WAITFOR.

Quando a consulta exceder a opção querywait, o argumento da instrução WAITFOR poderá ser concluído sem executar. Para obter mais informações sobre a opção de configuração, consulte Opção query wait. Para consultar os processos ativos e em espera, use sp_who.

Cada instrução WAITFOR tem um thread associado a ela. Se muitas instruções WAITFOR forem especificadas no mesmo servidor, muitos threads poderão ser vinculados ao aguardar a execução dessas instruções. O SQL Server monitora o número de threads associados a instruções WAITFOR e selecionará aleatoriamente alguns desses threads para encerramento se o servidor começar a experimentar falta de threads.

É possível criar um deadlock pela execução de uma consulta com WAITFOR em uma transação que também contenha bloqueios que impeçam alterações no conjunto de linhas que a instrução WAITFOR está tentando acessar. O SQL Server identifica esses cenários e retornará um conjunto de resultados vazio se existir a chance de tal deadlock.

Exemplos

A. Usando WAITFOR TIME

O exemplo a seguir executa o procedimento armazenado sp_update_job às 22:20. (22:20).

USE msdb;
EXECUTE sp_add_job @job_name = 'TestJob';
BEGIN
    WAITFOR TIME '22:20';
    EXECUTE sp_update_job @job_name = 'TestJob',
        @new_name = 'UpdatedJob';
END;
GO

B. Usando WAITFOR DELAY

O exemplo a seguir executa o procedimento armazenado depois de um atraso de duas horas.

BEGIN
    WAITFOR DELAY '02:00';
    EXECUTE sp_helpdb;
END;
GO

C. Usando WAITFOR DELAY com uma variável local

O exemplo a seguir mostra como uma variável local pode ser usada com a opção WAITFOR DELAY. Um procedimento armazenado é criado para aguardar por um período de tempo variável e retorna informações ao usuário sobre o número de horas, minutos e segundos decorridos.

USE AdventureWorks;
GO
IF OBJECT_ID('dbo.TimeDelay_hh_mm_ss','P') IS NOT NULL
    DROP PROCEDURE dbo.TimeDelay_hh_mm_ss;
GO
CREATE PROCEDURE dbo.TimeDelay_hh_mm_ss 
    (
    @DelayLength char(8)= '00:00:00'
    )
AS
DECLARE @ReturnInfo varchar(255)
IF ISDATE('2000-01-01 ' + @DelayLength + '.000') = 0
    BEGIN
        SELECT @ReturnInfo = 'Invalid time ' + @DelayLength 
        + ',hh:mm:ss, submitted.';
        -- This PRINT statement is for testing, not use in production.
        PRINT @ReturnInfo 
        RETURN(1)
    END
BEGIN
    WAITFOR DELAY @DelayLength
    SELECT @ReturnInfo = 'A total time of ' + @DelayLength + ', 
        hh:mm:ss, has elapsed! Your time is up.'
    -- This PRINT statement is for testing, not use in production.
    PRINT @ReturnInfo;
END;
GO
/* This statement executes the dbo.TimeDelay_hh_mm_ss procedure. */
EXEC TimeDelay_hh_mm_ss '00:00:10';
GO

Conjunto de resultados.

A total time of 00:00:10, in hh:mm:ss, has elapsed. Your time is up.

Consulte também

Referência

Linguagem de controle de fluxo (Transact-SQL)

datetime (Transact-SQL)

sp_who (Transact-SQL)

Conceitos

Usando WAITFOR

Agendamento de tarefas ou lotes no SQL Server