VBA – Agendando a execução de macros com a função OnTime

Introdução

Uma necessidade muito comum em aplicativos é utilizar critérios de tempo para execução de algumas rotinas. Esta é uma tarefa trivial em várias linguagens, mas poucos pensam em utilizá-la no VBA por achar muito complexo, tendo que envolver chamadas de API e outros recursos mais avançados da linguagem

Porém, o VBA do Microsoft Excel disponibiliza um método que facilita esse tipo de trabalho, o método OnTime().

O que é

O método OnTime programa um procedimento para ser executado em um momento especificado no futuro (seja em uma determinada hora do dia ou após uma quantidade específica de tempo decorrido).

A estrutura de chamada à função OnTime se faz da seguinte forma:

Application.OnTime([EarliestTime], [Procedure], [LatestTime], [Schedule])

Argumentos da função:

EarliestTime

Variant necessário. Especifica quando você deseja que esse procedimento seja executado.

Procedure

String necessário. O nome do procedimento a ser executado.

LatestTime

Variant opcional. Especifica até quando o procedimento pode ser executado. Por exemplo, se LatestTime estiver definido como EarliestTime + 30 e o Microsoft Excel não estiver em modo Pronto, Copiar, Recortar ou Localizar em EarliestTime devido a um outro procedimento estar sendo executado, o Microsoft Excel esperará 30 segundos para que o primeiro procedimento termine. Se o Microsoft Excel não estiver em modo Pronto dentro de 30 segundos, o procedimento não será executado. Se esse argumento for omitido, o Microsoft Excel esperará até que o procedimento possa ser executado.

Schedule

Variant opcional. True para programar um novo procedimento OnTime. False para limpar um procedimento definido anteriormente. O valor padrão é True.

Exemplo

Para informar ao VBA um valor de data válido para execução do método OnTime, usa-se a propriedade Now do VBA juntamente com a função TimeValue( . Somando as duas, é possível programar o procedimento para ser executado quando uma quantidade de tempo específica (contando a partir de agora) tiver decorrido.

Caso seja necessário informar uma hora específica, por exemplo, 3 da tarde (ou 15:00), usa-se TimeValue(time) onde time é um valor de hora informado através de uma String.

Veja os exemplos de código abaixo:

Public Sub ExecutaOnTime()
MsgBox "Opa! Executou."
End Sub
Public Sub TesteOnTime()
Call Application.OnTime(Now +
TimeValue("00:00:10"), "ExecutaOnTime")
End Sub

Execute a função TesteOnTime, deixando o cursor do mouse sobre ele (linha 5 a 6) e clicando em F5. Se tudo der certo, em 10 segundos você deverá ver esta mensagem:

Pronto! Conforme configuramos o OnTime para executar 10 segundos após a hora atual (linha 6) pois, Now retorna a data e hora atual e TimeValue(“00:00:10”) representa para o VBA 10 segundos, após executar a função TesteOnTime, ela programa a função ExecutaOnTime (linha 1) para ser executada neste tempo.

Para efeitos de teste, configure outros valores de tempo, mas tome o cuidado que sejam pequenos pois, se configurar para executar daqui a 24 horas (“24:00:00”), vai ter que esperar um bom tempo.

Para fazer outro teste interessante do OnTime, mude o código para ficar desta forma:

Public Sub ExecutaOnTime()
MsgBox "Opa!
Executou."
End Sub
Public Sub TesteOnTime()
Call Application.OnTime(TimeValue("13:00:00"),
"ExecutaOnTime")
End Sub

Da forma que está, o código irá configurar a função ExecutaOnTime (linha 1) para ser executada às na próxima 13:00 do computador em que está sendo executada. Como este é apenas um exemplo, configure uma hora que estiver mais próxima para não esperar muito.

É possível também cancelar a execução de uma macro agendada com o OnTime. O exemplo de código abaixo cancela a definição de OnTime do exemplo anterior, ou seja, caso a execução da função ExecutaOnTime estiver agendada, executar a função CancelaOnTime fará com que esta programação seja cancelada. isso é feito passando o valor False para o parâmetro Schedule (linha 10):

Public Sub</span> ExecutaOnTime()
MsgBox "Opa! Executou."
End Sub
Public Sub TesteOnTime()
Call Application.OnTime(TimeValue("13:00:00"),
"ExecutaOnTime")
End Sub
Public Sub</span> CancelaOnTime()
Call Application.OnTime(EarliestTime:=TimeValue("13:00:00"),
Procedure:="ExecutaOnTime", Schedule:=False)
End Sub

Conclusão

Com este recurso em mãos, é possível atender a algumas necessidades que no contexto do Excel pareciam inviáveis. Um exemplo típico é uma tela de apresentação ou SplashScreen como é conhecida que apresenta o programa e fecha em alguns segundos. Este é um bom teste para experimentar o uso do OnTime. Fica aí um desafio.

Como implementar um atraso/espera no VBA

Excel-Sleep

A necessidade é um fato e pouca documentação há sobre isso. De fato as linguagens de programação mais usadas gozam facilmente de um método Sleep, que facilmente pausa a execução do código por algum momento.

No VBA isso não é tão intuitivo, mas existem algumas alternativas para fazê-lo.

Método 1: Usar um loop For… Next vazio

Uma desvantagem para este método é que não existe como determinar a quantidade exata de tempo que o programa leva para executar o executar um loop. A quantidade de tempo depende da velocidade do seu computador. O seguinte código executa um loop que faz nada, mas segura o processamento por algum tempo.

1
2
3
4
Sub MyDelayMacro
 For iCount = 1 to 1000
 Next iCount
End Sub

Método 2: Usar uma chamada API para suspender a execução

Utilizar um chamar API para suspender a execução por uma quantidade fixa de tempo.

O kernel32 contém uma função que pausa execução um programa do para uma quantidade especificada de tempo em milissegundos. Para que você possa usar a função, ele deve primeiro ser declarado na seção General Declarations do módulo no qual será usado:

1
2
   Declare Sub Sleep Lib "kernel32" Alias "Sleep" _
 (ByVal dwMilliseconds As Long)

Use a seguinte sintaxe para chamar a função Sleep :

1
2
3
Sub Sleep()
 Sleep 1000   'Faz o código esperar por 1 segundo
 End Sub

Método 3: Usar o método OnTime

Use o método OnTime para definir uma quantidade de tempo a pausa. O método OnTime usa a seguinte sintaxe:

expressão .OnTime (quando, nome, tolerância a falhas)

Por requerer nome de uma macro para o argumento nome executar, você deve criar duas macros: a primeira macro para conter o chamar método OnTime e outros comandos relevantes para sua macro, e a segunda macro para executar quando o tempo alocado tiver passado. A segunda macro pode ser uma macro “fantasma” que não fará nada além de chamar o método OnTime para fazer o agendameto..

Este exemplo executa o macro nomeado ” MyDelayMacro ” 15 segundos desde o tempo é o exemplo executar.

1
2
3
4
5
6
7
8
Sub MyMainMacro()
 ' Pausa por 15 segundos.
 Application.OnTime Now + TimeValue("00:00:15"), "MyDelayMacro"
 End Sub
Public Sub MyDelayMacro()
 ' Macro executada sob o agendamento.
 MsgBox "Esta macro foi executada após 15 segundos."
 End Sub

Método 4: Usar o método Application.Wait

Trabalha da mesma similar ao Sleep, porém é preciso “montar” um objeto TimeValue a ser passado com parâmetro, e o código esperará até o tempo definido neste para executar, simulando um comportamente de “esperar até”, ao contrário do Sleep que tem um comportamento “esperar por X tempo”

1
2
3
4
5
6
7
Sub MyWaitMacro()
newHour = Hour(Now())
newMinute = Minute(Now())
newSecond = Second(Now()) + 3
waitTime = TimeSerial(newHour, newMinute, newSecond)
Application.Wait waitTime
End Sub

Para obter mais informações sobre como usar o método OnTime, leia este artigo: https://www.tomasvasquez.com.br/blog/microsoft-office/vba-agendando-a-execucao-de-macros-com-a-funcao-ontime

Bom proveito!