Referência MQL5Calendário econômicoCalendarValueLastByEvent 

CalendarValueLastByEvent

Obtém um array de valores do eventos por seu ID desde o momento em que criado do banco de dados do Calendário com o change_id definido.

int  CalendarValueLastByEvent(
   ulong                event_id,      // identificador de evento 
   ulong&               change_id,     // identificador do valor do evento 
   MqlCalendarValue&    values[]       // array para obter descrições de valores 
   );

Parâmetros

event_id

[in]  ID do evento.

change_id

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

values[]

[out]  Array de tipo MqlCalendarValue para obter valores de eventos.

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

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.

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.

Se, para o valor de evento, não houver algum dos campos abaixo

struct MqlCalendarValue
  {
   ...
   long              actual_value;              // valor atual do indicador
   long              prev_value;                // valor anterior do indicador
   long              revised_prev_value;        // valor do evento anterior revisado
   long              forecast_value;            // valor previsto do evento
   ...
  };

o valor do campo ausente será retornado como INT64_MIN (-9223372036854775808).

Um exemplo de um EA que ouve a publicação do Nonfarm payrolls:

#property description "Exemplo de uso da função CalendarValueLastByEvent"
#property description " para pegar a publicação do relatório do evento Nonfarm Payrolls."
#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;
//--- identificador de evento  
   static ulong event_id=0;
//--- nome do evento  
   static string event_name=NULL;
//--- array de valores do evento
   MqlCalendarValue values[];
//--- inicialize - obtenha o calendar_change_id atual
   if(first)
     {
      MqlCalendarEvent events[];
      //--- código do país para os EUA de acordo com a ISO 3166-1 Alpha-2 
      string USA_code="US";
      //--- obtenha eventos para os EUA    
      int events_count=CalendarEventByCountry(USA_code,events);
      //--- posição necessário no array de eventos events
      int event_pos=-1;
      //--- registre os eventos para os EUA no Diário
      if(events_count>0)
        {
         PrintFormat("%s: Eventos para os EUA: %d",__FUNCTION__,events_count);
         for(int i=0;i<events_count;i++)
           {
            string event_name_low=events[i].name;
            //--- insira o nome do evento em minúsculas            
            if(!StringToLower(event_name_low))
              {
               PrintFormat("StringToLower() retornou o erro %d",GetLastError());
               //--- antecipadamente saia da função
               return;
              }
            //--- procure o evento "Nonfarm Payrolls"            
            if(StringFind(event_name_low,"nonfarm payrolls")!=-1)
              {
               //--- evento encontrado, lembre-se de seu id
               event_id=events[i].id;
               //--- escreva para o evento "Nonfarm Payrolls" seu nome
               event_name=events[i].name;
               //--- lembre a posição do evento no array events[]               
               event_pos=i;
               //--- na verdade, no Calendário há vários eventos contendo o nome "nonfarm payrolls", considere
               PrintFormat("Evento \"Nonfarm Payrolls\" encontrado: event_id=%d  event_name=%s",event_id,event_name);
               //--- veja todos os eventos, comente o operador break, para entender melhor este exemplo
               break;
              }
           }
         //--- reduza a lista, apague os eventos após o evento"Nonfarm Payrolls"
         ArrayRemove(events,event_pos+1);
         //--- para facilitar o estudo, deixe 9 eventos antes de "Nonfarm Payrolls"         
         ArrayRemove(events,0,event_pos-9);
         ArrayPrint(events);
        }
      else
        {
         PrintFormat("%s: CalendarEventByCountry(%s) retornou 0 eventos, código de erro=%d",
                     USA_code,__FUNCTION__,GetLastError());
         //--- falha, tente novamente na próxima chamada do temporizador         
         return;
        }
 
      //--- obtenha, para o evento definido, o ID da alteração da base do Calendário   
      if(CalendarValueLastByEvent(event_id,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 valores para o evento event_id=%d",__FUNCTION__,event_id);
            PrintFormat("Código de erro: %d",error_code);
            //--- falha, tente novamente na próxima chamada do temporizador         
            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 surgiu um novo valor para o evento "Nonfarm Payrolls"
   if(CalendarValueLastByEvent(event_id,calendar_change_id,values)>0)
     {
      PrintFormat("%s: Obtidos novos eventos para \"%s\": %d",
                  __FUNCTION__,event_name,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);
/* 
      escreva aqui o código que processará a publicação de dados sobre o "Nonfarm Payrolls"
      */
     }
//---     
  }
/*
  Resultado:
   OnTimer: Eventos para EUA: 202
   Evento "Nonfarm Payrolls" encontrado: event_id=840030016  event_name=Nonfarm Payrolls
            [id] [type] [sector] [frequency] [time_mode] [country_id] [unit] [importance] [multiplier] [digits]          [source_url]                             [event_code]                   [name] [reserved]
   [0] 840030007      1        4           2           0          840      1            1            0        1 "https://www.bls.gov" "consumer-price-index-yy"                "CPI y/y"                         0
   [1] 840030008      1        4           2           0          840      1            1            0        1 "https://www.bls.gov" "consumer-price-index-ex-food-energy-yy" "Core CPI y/y"                    0
   [2] 840030009      1        4           2           0          840      0            1            0        3 "https://www.bls.gov" "consumer-price-index-nsa"               "CPI n.s.a."                      0
   [3] 840030010      1        4           2           0          840      0            1            0        3 "https://www.bls.gov" "consumer-price-index-ex-food-energy"    "Core CPI"                        0
   [4] 840030011      1        4           2           0          840      1            1            0        1 "https://www.bls.gov" "import-price-index-mm"                  "Import Price Index m/m"          0
   [5] 840030012      1        4           2           0          840      1            1            0        1 "https://www.bls.gov" "import-price-index-yy"                  "Import Price Index y/y"          0
   [6] 840030013      1        4           2           0          840      1            1            0        1 "https://www.bls.gov" "export-price-index-mm"                  "Export Price Index m/m"          0
   [7] 840030014      1        4           2           0          840      1            1            0        1 "https://www.bls.gov" "export-price-index-yy"                  "Export Price Index y/y"          0
   [8] 840030015      1        3           2           0          840      1            2            0        1 "https://www.bls.gov" "unemployment-rate"                      "Unemployment Rate"               0
   [9] 840030016      1        3           2           0          840      4            3            1        0 "https://www.bls.gov" "nonfarm-payrolls"                       "Nonfarm Payrolls"                0
   OnTimer: Recebido o ID atual da base do Calendário: change_id=33986560
 
*/  

Veja também

CalendarValueLast, CalendarValueHistory, CalendarValueHistoryByEvent, CalendarValueById