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. Veja um exemplo de processamento de eventos de calendário.

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.

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