MQL5 ReferenceEconomic CalendarCalendarValueLastByEvent 

CalendarValueLastByEvent

Get the array of event values by its ID since the Calendar database status with a specified change_id.

int  CalendarValueLastByEvent(
   ulong                event_id,      // event ID 
   ulong&               change_id,     // Calendar change ID 
   MqlCalendarValue&    values[]       // array for value descriptions 
   );

Parameters

event_id

[in]  Event ID.

change_id

[in][out]  Change ID.

values[]

[out] MqlCalendarValue type array for receiving event values.

Return Value

Number of received event values. To get information about an error, call the GetLastError() function. Possible errors:

  • 4001 – ERR_INTERNAL_ERROR  (general runtime error),
  • 4004 – ERR_NOT_ENOUGH_MEMORY (not enough memory for executing a request),
  • 5401 – ERR_CALENDAR_TIMEOUT (request time limit exceeded),
  • 5400 – ERR_CALENDAR_MORE_DATA (array size is insufficient for receiving descriptions of all values, only the ones that managed to fit in were received),

Note

All functions for working with the economic calendar use the trade server time (TimeTradeServer). This means that the time in the MqlCalendarValue structure and the time inputs in the CalendarValueHistoryByEvent/CalendarValueHistory functions are set in a trade server timezone, rather than a user's local time.

If the events[] array of fixed length was passed to the function and there was not enough space to save the entire result, the ERR_CALENDAR_MORE_DATA (5400) error is activated.

If change_id = 0 is passed to the function, the function always returns zero but the current calendar database is returned to change_id.

The function returns the array for a specified news and a new change_id that can be used for subsequent calls of the function to receive the new values of the news. Thus, it is possible to update values for a specified news by calling this function with the last known change_id.

If an event value does not have any of the fields specified below

struct MqlCalendarValue
  {
   ...
   long              actual_value;              // event's actual value
   long              prev_value;                // event's previous value
   long              revised_prev_value;        // event's revised previous value
   long              forecast_value;            // event's forecast value
   ...
  };

then the value of the missing field is returned as INT64_MIN (-9223372036854775808).

The sample EA listening for the Nonfarm payrolls report release:

#property description "Example of using the CalendarValueLastByEvent function"
#property description " for tracking the release of the Nonfarm Payrolls report."
#property description "To achieve this, get the current change ID"
#property description " of the Calendar database. Then, use this ID to receive"
#property description " only new events via the timer survey"
//+------------------------------------------------------------------+
//| 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()
  {
//--- Calendar database change ID
   static ulong calendar_change_id=0;
//--- first launch attribute
   static bool first=true;
//--- event ID  
   static ulong event_id=0;
//--- event name  
   static string event_name=NULL;
//--- event value array
   MqlCalendarValue values[];
//--- perform initialization - get the current calendar_change_id
   if(first)
     {
      MqlCalendarEvent events[];
      //--- country code for USA (ISO 3166-1 Alpha-2) 
      string USA_code="US";
      //--- get events for USA    
      int events_count=CalendarEventByCountry(USA_code,events);
      //--- position of a necessary event in the 'events' array
      int event_pos=-1;
      //--- display USA events in the Journal
      if(events_count>0)
        {
         PrintFormat("%s: USA events: %d",__FUNCTION__,events_count);
         for(int i=0;i<events_count;i++)
           {
            string event_name_low=events[i].name;
            //--- change an event name to lower case            
            if(!StringToLower(event_name_low))
              {
               PrintFormat("StringToLower() returned %d error",GetLastError());
               //--- exit the function ahead of time
               return;
              }
            //--- look for the "Nonfarm Payrolls" event            
            if(StringFind(event_name_low,"nonfarm payrolls")!=-1)
              {
               //--- event found, remember its ID
               event_id=events[i].id;
               //--- write the "Nonfarm Payrolls" event name 
               event_name=events[i].name;
               //--- remember the events' position in the 'events[]' array               
               event_pos=i;
               //--- keep in mind that the Calendar features several events containing "nonfarm payrolls" in their names
               PrintFormat("Event \"Nonfarm Payrolls\" found: event_id=%d  event_name=%s",event_id,event_name);
               //--- view all the events by commenting out the 'break' operator to better understand this example
               break;
              }
           }
         //--- reduce the list by deleting events after "Nonfarm Payrolls"
         ArrayRemove(events,event_pos+1);
         //--- leave 9 events before "Nonfarm Payrolls" for more convenient analysis         
         ArrayRemove(events,0,event_pos-9);
         ArrayPrint(events);
        }
      else
        {
         PrintFormat("%s: CalendarEventByCountry(%s) returned 0 events, error code=%d",
                     USA_code,__FUNCTION__,GetLastError());
         //--- operation completed in a failure, try again during the next call of the timer         
         return;
        }
 
      //--- get the Calendar database change ID for the specified event   
      if(CalendarValueLastByEvent(event_id,calendar_change_id,values)>0)
        {
         //--- this code block cannot be executed during the first launch but let's add it anyway
         PrintFormat("%s: Received the Calendar database current ID: change_id=%d",
                     __FUNCTION__,calendar_change_id);
         //--- set the flag and exit before the timer's next event
         first=false;
         return;
        }
      else
        {
         //--- data are not received (this is normal for the first launch), check for an error
         int error_code=GetLastError();
         if(error_code==0)
           {
            PrintFormat("%s: Received the Calendar database current ID: change_id=%d",
                        __FUNCTION__,calendar_change_id);
            //--- set the flag and exit before the timer's next event
            first=false;
            //--- now we have the calendar_change_id value
            return;
           }
         else
           {
            //--- and this is really an error            
            PrintFormat("%s: Failed to get values for event_id=%d",__FUNCTION__,event_id);
            PrintFormat("Error code: %d",error_code);
            //--- operation completed in a failure, try again during the next call of the timer         
            return;
           }
        }
     }
 
//--- we have the last known value of the Calendar change ID (change_id)
   ulong old_change_id=calendar_change_id;
//--- check for a new Nonfarm Payrolls event value
   if(CalendarValueLastByEvent(event_id,calendar_change_id,values)>0)
     {
      PrintFormat("%s: Received new events for \"%s\": %d",
                  __FUNCTION__,event_name,ArraySize(values));
      //--- display data from the 'values' array in the Journal 
      ArrayPrint(values);
      //--- display the values of the previous and new Calendar IDs in the Journal
      PrintFormat("%s: Previous change_id=%d, new change_id=%d",
                  __FUNCTION__,old_change_id,calendar_change_id);
/* 
      write your code that is to handle "Nonfarm Payrolls" data release here
      */
     }
//---     
  }
/*
  Result:
   OnTimer: USA events: 202
  Event "Nonfarm Payrolls" found: 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: Received the Calendar database current ID: change_id=33986560
 
*/  

See also

CalendarValueLast, CalendarValueHistory, CalendarValueHistoryByEvent, CalendarValueById