DocumentaçãoSeções
Referência MQL5Calendário econômicoCalendarValueLast 

CalendarValueLast

Obtém um array de valores de todos os eventos com filtro por país e/ou moeda desde o momento em que criado do banco de dados do Calendário com o change_id definido.

int  CalendarValueLast(
   ulong&               change_id,             // identificador de alteração
   MqlCalendarValue&    values[],              // array para obter descrições de valores 
   const string         country_code=NULL,     // código do país segundo ISO 3166-1 alpha-2
   const string         currency=NULL          // código da moeda do país 
   );

Parâmetros

change_id

[in][out]  Identificador de alteração.

values[]

[out]  Array de tipo MqlCalendarValue para obter valores de eventos. Veja um exemplo de processamento de eventos de calendário.

country_code=NULL

[in]  Código do país segundo ISO 3166-1 alpha-2

currency=NULL

[in]  Código da moeda do país

Valor retornado

Número de valores de eventos recebidos. Para obter informações de erro, chame a função GetLastError(). Possíveis erros:

  • 4001 — ERR_INTERNAL_ERROR  (erro geral de tempo de execução),
  • 4004 — ERR_NOT_ENOUGH_MEMORY (memória insuficiente para execução da solicitação),
  • 5401 — ERR_CALENDAR_TIMEOUT (excedido tempo limite de solicitação),
  • 5400 — ERR_CALENDAR_MORE_DATA (tamanho de array insuficiente para obter descrições de todos os valores, portanto, eles recebem apenas o que contêm).

Observação

Todas as funções para trabalhar com o Calendário Econômico usam o horário do servidor de negociação (TimeTradeServer). Isso significa que o tempo na estrutura MqlCalendarValue e os parâmetros de tempo de entrada nas funções CalendarValueHistoryByEvent/CalendarValueHistory são definidos no fuso horário do servidor de negociação e não no horário local do usuário.

Se um array foi passado para a função events[] de comprimento fixo e, como resultado da solicitação, não havia espaço suficiente para salvar o resultado inteiro, é mostrado o erro ERR_CALENDAR_MORE_DATA (5400).

Se na função for passado change_id = 0, a função sempre retornará zero, mas ao mesmo tempo change_id retorna o estado atual do banco de dados do Calendário.

Para os filtros country_code e currency valores NULL e "" são equivalentes, eles indicam que não há filtro.

Para country_code deve ser usado o campo code da estrutura MqlCalendarCountry, por exemplo, "US", "RU" ou "EU".

Para currency deve ser usado o campo currency da estrutura MqlCalendarCountry, por exemplo, "USD", "RUB" ou "EUR".

Os filtros são aplicados por conjunção, ou seja, através do booliano 'E' são selecionados apenas os eventos para os quais ambas as condições são atendidas simultaneamente — país e moeda

A função retorna uma matriz de valores para as notícias especificadas e change_id novo que pode ser usado para chamadas subsequentes desta função para obter novos valores de notícias. Assim, chamando esta função com o último conhecido change_id, pode-se receber atualizações de valores para uma determinada notícia.

A estrutura MqlCalendarValue disponibiliza método para obter e verificar valores a partir dos campos actual_value, forecast_value, prev_value e revised_prev_value. Se o valor do campo não estiver definido, ele armazenará o valor LONG_MIN (-9223372036854775808).

Deve-se ter em mente que os valores nestes campos são armazenados multiplicados por um fator de um milhão. Isso significa que quando as funções CalendarValueById, CalendarValueHistoryByEvent, CalendarValueHistory, CalendarValueLastByEvent e CalendarValueLast recebem valores em MqlCalendarValue, é necessário verificar se os valores LONG_MIN desses campos são iguais; e se no campo estiver definido o valor, para obter o valor deve-se dividir o valor do campo por 1000 000 (um milhão). Outra maneira de obter valores é verificar e obter valores por funções da própria estrutura MqlCalendarValue.

Um exemplo de um EA que ouve a publicação de eventos do Calendário Econômico:

#property description "Exemplo de uso da função CalendarValueLast"
#property description " para criar um ouvinte de evento do Calendário Econômico."
#property description "Para fazer isso, você precisa obter o ID atual da alteração"
#property description " base do Calendário. Em seguida, obter segundo este identificador"
#property description " apenas novos eventos através de pesquisa no temporizador"
//+------------------------------------------------------------------+
//| Expert initialization function                                   |
//+------------------------------------------------------------------+
int OnInit()
  {
//--- create timer
   EventSetTimer(60);
//---
   return(INIT_SUCCEEDED);
  }
//+------------------------------------------------------------------+
//| Expert deinitialization function                                 |
//+------------------------------------------------------------------+
void OnDeinit(const int reason)
  {
//--- destroy timer
   EventKillTimer();
  }
//+------------------------------------------------------------------+
//| Expert tick function                                             |
//+------------------------------------------------------------------+
void OnTick()
  {
//---
 
  }
//+------------------------------------------------------------------+
//| Timer function                                                   |
//+------------------------------------------------------------------+
void OnTimer()
  {
//--- ID da alteração da base do Calendário
   static ulong calendar_change_id=0;
//--- sinal da primeira inicialização
   static bool first=true;
//--- array de valores do evento
   MqlCalendarValue values[];
//--- inicialize - obtenha o calendar_change_id atual
   if(first)
     {
      //--- obtenha o ID da alteração da base do Calendário   
      if(CalendarValueLast(calendar_change_id,values)>0)
        {
         //--- este bloco de código não pode ser executado na primeira inicialização, mas ainda assim o escreveremos
         PrintFormat("%s: Obtido ID atual da base do calendário: change_id=%d",
                     __FUNCTION__,calendar_change_id);
         //--- defina o sinalizador e saia antes do próximo evento do temporizador
         first=false;
         return;
        }
      else
        {
         //--- dados não recebidos (para a primeira execução, isso é normal), verifique se há um erro
         int error_code=GetLastError();
         if(error_code==0)
           {
            PrintFormat("%s: Obtido ID atual da base do calendário: change_id=%d",
                        __FUNCTION__,calendar_change_id);
            //--- defina o sinalizador e saia antes do próximo evento do temporizador
            first=false;
            //--- agora você tem o valor calendar_change_id
            return;
           }
         else
           {
            //--- isso é realmente um erro            
            PrintFormat("%s: Falha ao obter eventos em CalendarValueLast. Código de erro: %d",
                        __FUNCTION__,error_code);
            //--- falha ao trabalhar, tente inicializar novamente na próxima vez que o temporizador for chamado         
            return;
           }
        }
     }
 
//--- você tem o último valor conhecido do ID de mudança do calendário (change_id)
   ulong old_change_id=calendar_change_id;
//--- verifique se apareceram novos eventos do Calendário
   if(CalendarValueLast(calendar_change_id,values)>0)
     {
      PrintFormat("%s: Obtidos novos eventos do Calendário: %d",
                  __FUNCTION__,ArraySize(values));
      //--- exiba no Diário informações do array values 
      ArrayPrint(values);
      //--- exiba no Diário os valores do ID do Calendário - o anterior e o novo
      PrintFormat("%s: Anterior change_id=%d, novo change_id=%d",
                  __FUNCTION__,old_change_id,calendar_change_id);
      //--- exiba no Diário novos eventos
      ArrayPrint(values);
      /* 
     escreva aqui o seu código que irá processar o surgimento dos eventos
      */
     }
//---     
  }
/*
  Exemplo para a operação do "ouvinte":
  OnTimer: Obtido ID atual da base do calendário: change_id=33281792
  OnTimer: Obtidos novos eventos para o Calendário: 1
        [id] [event_id]              [time]            [period] [revision] [actual_value] [prev_value] [revised_prev_value] [forecast_value] [impact_type] [reserved]
   [0] 91040   76020013 2019.03.20 15:30:00 1970.01.01 00:00:00          0       -5077000     -1913000 -9223372036854775808         -4077000             2          0
  OnTimer: Anterior change_id=33281792, novo change_id=33282048
        [id] [event_id]              [time]            [period] [revision] [actual_value] [prev_value] [revised_prev_value] [forecast_value] [impact_type] [reserved]
   [0] 91040   76020013 2019.03.20 15:30:00 1970.01.01 00:00:00          0       -5077000     -1913000 -9223372036854775808         -4077000             2          0
  OnTimer: Obtidos novos eventos para o Calendário: 1
        [id] [event_id]              [time]            [period] [revision]       [actual_value] [prev_value] [revised_prev_value] [forecast_value] [impact_type] [reserved]
   [0] 91041   76020013 2019.03.27 15:30:00 1970.01.01 00:00:00          0 -9223372036854775808     -5077000 -9223372036854775808         -7292000             0          0
  OnTimer: Anterior change_id=33282048, novo change_id=33282560
        [id] [event_id]              [time]            [period] [revision]       [actual_value] [prev_value] [revised_prev_value] [forecast_value] [impact_type] [reserved]
   [0] 91041   76020013 2019.03.27 15:30:00 1970.01.01 00:00:00          0 -9223372036854775808     -5077000 -9223372036854775808         -7292000             0          0
 
*/  

Veja também

CalendarValueLast, CalendarValueHistory, CalendarValueHistoryByEvent, CalendarValueById