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 da 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 ser aguardado. time_to_pass pode ser especificado em um dos formatos aceitáveis de 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 na qual a instrução WAITFOR é concluída. time_to_execute pode ser especificado em um dos formatos aceitáveis de 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 query wait, 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 Configurar a opção de configuração de servidor query wait. Para consultar os processos ativos e em espera, use sp_who.

Cada instrução WAITFOR tem um thread associado a ela. Se forem especificadas muitas instruções WAITFOR no mesmo servidor, muitos threads poderão ser parados aguardando pela execução dessas instruções. O SQL Server monitora o número de threads associados às instruções WAITFOR e seleciona aleatoriamente alguns desses threads para sair se o servidor começar a sofrer privação de thread.

Você poderá criar um deadlock executando uma consulta com WAITFOR em uma transação que também contenha bloqueios impedindo alterações no conjunto de linhas que a instrução WAITFOR está tentando acessar. O SQL Server identifica esses cenários e retorna um conjunto de resultados vazio, no caso de esse deadlock existir.

Cuidado
A inclusão de WAITFOR tornará mais lenta a conclusão do processo do SQL Server e pode resultar em uma mensagem de tempo limite no aplicativo. Se necessário, ajuste a configuração de tempo limite para a conexão em nível de aplicativo.

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 AdventureWorks2012;
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

Aqui está o 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)