ДокументацияРазделы
Справочник MQL5Экономический календарьCalendarValueHistory 

CalendarValueHistory

Получает массив значений по всем событиям на заданном диапазоне времени с фильтром по стране и/или валюте.

int  CalendarValueHistory(
   MqlCalendarValue&  values[],              // массив для получения описаний значений 
   datetime           datetime_from,         // левая граница диапазона времени
   datetime           datetime_to=0          // правая граница диапазона времени
   const string       country_code=NULL,     // кодовое имя страны по ISO 3166-1 alpha-2
   const string       currency=NULL          // кодовое наименование валюты страны 
   );

Параметры

values[]

[out]  Массив типа MqlCalendarValue для получения значений событиий. Смотри пример обработки событий календаря.

datetime_from

[in]  Начальная дата диапазона времени, из которого выбираются события по заданному идентификатору, при этом datetime_from < datetime_to.

datetime_to=0

[in]  Конечная дата диапазона времени, из которого выбираются события по заданному идентификатору. Если параметр datetime_to не задан (или равен 0), то будут возвращены все значения событий от заданной даты datetime_from, имеющиеся в базе Календаря, в том числе и значения событий, которые запланированы на будущее.

country_code=NULL

[in]  Кодовое имя страны согласно ISO 3166-1 alpha-2

currency=NULL

[in]  Кодовое наименование валюты страны.

Возвращаемое значение

В случае успеха возвращает количество доступных значений в массиве values, иначе -1. Чтобы получить информацию об ошибке, необходимо вызвать функцию GetLastError(). Возможные ошибки:

  • 4001 – ERR_INTERNAL_ERROR  (общая ошибка исполняющей системы),
  • 4004 – ERR_NOT_ENOUGH_MEMORY (не достаточно памяти для выполнения запроса),
  • 5401 – ERR_CALENDAR_TIMEOUT (превышен лимит запроса по времени),
  • 5400 – ERR_CALENDAR_MORE_DATA (размер массива недостаточен для получения описаний всех значений, поэтому получили только то, что вместилось),
  • ошибки неудачного выполнения ArrayResize()

 

Примечание

Все функции для работы с Экономическим календарем используют время торгового сервера (TimeTradeServer). Это означает, что время в структуре MqlCalendarValue и входящие параметры времени в функциях CalendarValueHistoryByEvent/CalendarValueHistory задаются в таймзоне торгового сервера, а не в локальном времени пользователя.

Если в функцию был передан массив events[] фиксированной длины и в результате запроса не хватило места для сохранения всего результата, будет взведена ошибка ERR_CALENDAR_MORE_DATA (5400).

Если не задан параметр datetime_to (=0), то будут возвращены все значения событий от заданной даты datetime_from, имеющиеся в базе Календаря, в том числе и значения, которые запланированы на будущее.

Для фильтров country_code и currency значения NULL и "" равносильны – означают отсутствие фильтра.

Для country_code следует использовать поле code структуры MqlCalendarCountry, например "US", "RU" или "EU".

Для currency следует использовать поле currency структуры MqlCalendarCountry, например "USD", "RUB" или "EUR".

Фильтры применяются коньюкцией, т.е. через логическое 'И' выбираются значения только тех событий, для которых удовлетворяются одновременно оба условия – страна и валюта.

Структура MqlCalendarValue предоставляет методы для проверки и получения значений из полей actual_value, forecast_value, prev_value и revised_prev_value. Если значение поля не задано, то поле хранит значение LONG_MIN (-9223372036854775808).

При этом необходимо иметь в виду, что значения в этих полях хранятся увеличенными в миллион раз. Это означает, что при получении значений в MqlCalendarValue функциями CalendarValueById, CalendarValueHistoryByEvent, CalendarValueHistory, CalendarValueLastByEvent и CalendarValueLast, значения этих полей нужно проверять на равенство LONG_MIN, и если значение в поле задано, то для получения значения необходимо разделить значение поля на 1 000 000 (миллион). Другой способ получения значений – делать проверку и получать значения функциями самой структуры MqlCalendarValue.

Пример:

//+------------------------------------------------------------------+
//| Script program start function                                    |
//+------------------------------------------------------------------+
void OnStart()
  {
//--- код страны для Европейского союза по стандарту ISO 3166-1 Alpha-2 
   string EU_code="EU";
//--- получим все значения событий по Европейскому союзу
   MqlCalendarValue values[];
//--- зададим границы диапазона, из которого берем события
   datetime date_from=D'01.01.2018';  // берем все события с 2018 года
   datetime date_to=0;                // 0 означает все известные события, даже те, что не наступили еще 
//--- запросим историю события по Европейскому союзу с 2018 года
   if(CalendarValueHistory(values,date_from,date_to,EU_code))
     {
      PrintFormat("Получены значения событий по country_code=%s: %d",
                  EU_code,ArraySize(values));
      //--- уменьшим размер массива для вывода в Журнал
      ArrayResize(values,10);
//--- выведем значения событий в Журнал
      ArrayPrint(values);      
     }
   else
     {
      PrintFormat("Ошибка! Не удалось получить события по стране country_code=%s",EU_code);
      PrintFormat("Код ошибки: %d",GetLastError());
     }
//---
  }
/*
   Результат:
   Получены значения событий по country_code=EU: 1384
        [id] [event_id]           [time]               [period] [revision]   [actual_value] [prev_value] [revised_prev_value] [forecast_value] [impact_type] [reserved]
   [0] 54215  999500001 2018.01.02 09:00:00 2017.12.01 00:00:00          3       60600000     60600000 -9223372036854775808         60500000             1          0
   [1] 54221  999500002 2018.01.04 09:00:00 2017.12.01 00:00:00          3       56600000     56500000 -9223372036854775808         56000000             1          0
   [2] 54222  999500003 2018.01.04 09:00:00 2017.12.01 00:00:00          3       58100000     58000000 -9223372036854775808         58400000             2          0
   [3] 45123  999030005 2018.01.05 10:00:00 2017.11.01 00:00:00          0         600000       400000 -9223372036854775808           100000             1          0
   [4] 45124  999030006 2018.01.05 10:00:00 2017.11.01 00:00:00          0        2800000      2500000 -9223372036854775808          1500000             1          0
   [5] 45125  999030012 2018.01.05 10:00:00 2017.12.01 00:00:00          1         900000       900000 -9223372036854775808          1000000             2          0
   [6] 45126  999030013 2018.01.05 10:00:00 2017.12.01 00:00:00          1        1400000      1500000 -9223372036854775808          1500000             2          0
   [7] 54953  999520001 2018.01.05 20:30:00 2018.01.02 00:00:00          0      127900000     92100000 -9223372036854775808         76400000             0          0
   [8] 22230  999040003 2018.01.08 10:00:00 2017.12.01 00:00:00          0        9100000      8200000              8100000          7600000             1          0
   [9] 22231  999040004 2018.01.08 10:00:00 2017.12.01 00:00:00          0       18400000     16300000             16400000         16800000             1          0   
*/ 

Смотри также

CalendarCountries, CalendarEventByCountry, CalendarValueHistoryByEvent, CalendarEventById, CalendarValueById