EcLib - библиотека для MetaTrader 4

Библиотека EcLib для языка MQL4 предназначена для работы с экономическим календарем и позволяет:

• создавать и обновлять базу данных новостей (включая указания на праздники), используя данные различных сайтов-источников
• используя локальную базу данных получать данные по интересующим новостям в разрезе стран, валют, значимости, источников, категорий
• просматривать историю экономической статистику используя справочник категорий
• тестировать стратегии, использующие информацию о выходе новостей, строить новостные торговые стратегии

• Перед применением библиотеки на реальных счетах проведите ее проверку на демо-счете или вручную.
• При ручном изменении справочника значения нужно добавлять в конце, чтобы не нарушить кодировку существующей базы данных
• для обеспечения целостности и сохранности данных дата и время всех событий в базе данных совпадает с внутренним временем сайта ec.forexprostools.com, а именно: GMT универсальное (+00:00). Используйте приведение к местному времени и/или времени сервера по необходимости
• Библиотека использует некоторое количество глобальных переменных терминала. Не удаляйте и не изменяйте их
• Для текущего автоматического недельного обновления сайт ec.forexprostools.com должен быть добавлен в список разрешенных url
• дата праздников указана по местному времени страны праздника; время 00:00 добавляется программно

Для обеспечения совместимости библиотеки с терминалом MT5 и обеспечения работы в режиме тестирования стратегий неисполняемые файлы (бд, справочник и проч.) должны быть расположены в общей папке всех клиентских терминалов \Terminal\Common\Files\ в выделенном для работы библиотеки подкаталоге \ec; итоговое расположение файлов должно быть следующим (жирным шрифтом выделены обязательные файлы):

Файлы .ex4 должны быть скомпилированы в .mq4

Путь к папке \Terminal\Common\Files\ можно узнать в том числе программно:

= TerminalInfoString(TERMINAL_COMMONDATA_PATH)

База данных календаря хранится в бинарном формате в файле ec0_db.dat в виде набора событий. Событие представляет собой переменную структуры ec_struct

Файл настроек библиотеки содержит ряд параметров, используемых разнличными функциями. Указание на параметр заключается в квадратные скобки [] и следующей строкой идет само значение (либо набор значений) параметра. В случае набора значений они перечисляются через ‘;’

Справочник содержит описание параметров события (страна, валюта и проч.) и коды этих параметров. В базе данных события хранятся в закодированном, соответственно, виде. Файл справочника - ref.csv – представляет собой набор слов, где каждая строка – перечисление значений одной статьи справочника, разделенные ‘;’. Каждая новая строка – новая статья. В самой первой строке хранится перечисление самих статей справочника так же через ‘;’

При работе библиотеки справочник загружается в двумерный массив, где первое измерение соответствует статье (например, «страна»), а второе – элементу данной категории (например, «Франция»). Кодировка в явном виде не хранится, она получается из порядкового номера элемента, причем начинается всегда с 1. Нулевой код (индекс) не используется (зарезервирован). Соответственно при изменении справочника элементы нужно добавлять строго в конце, нельзя удалять элементы или менять их порядок тем или иным способом, поскольку это нарушит работу базы данных (на самом деле можно, но не желательно. При реиндексации, которая последует за изменением справочника, все будет нормализовано)

Обновляться Справочник может как в ручном, так и в полуавтоматическом режиме в процессе обновления базы данных. Если функция EcUpdate() вызвана не из индикатора и не в режиме тестера стратегий и в новых данных обнаружены новые страны и/или валюты, она запросит разрешения на добавление элемента в Справочник. Если пользователь уверен, что страна/валюта правильные, он принимает предложение и обновление продолжается; в противном случае обновление прерывается и в созданный файл ec\ERROR.txt будет записано описание ошибки. В этом случае необходимо вручную добавить в файл ref.csv недостающие данные (см. раздел ВАЖНО! выше в этом документе)

При каждом вызове функции ref_load() (вызывается она почти всегда другими функциями библиотеки) справочник выгружается в текстовый файл ref.txt, где в явном виде перечислены все категории и элементы справочника с указанием кодов.

Строго говоря, функция ref_load() обычно обращается не напрямую к ref.csv а к его точной копии – ref00.csv. Если же ref.csv был изменен процедура обновления начинает переиндексацию базы, в ходе которой используюся оба этих файла; по окончании переиндексации ref00.csv снова содержит точную копию ref.csv.

Обычно любое событие, как мы его видим, например, на сайтах, содержит минимум одну текстовую строку-описание события (Title), например

Caixin Manufacturing PMI (Dec) бла-бла-бла

Данная строка содержит как структурированную информацию, так и обычную. Структурированная информация здесь – во-первых - Manufacturing PMI - что представляет собой экономический показатель, во-вторых – (Dec) - что означает период, за который данный показатель представлен. Указание на источник данных (издатель новости) – Caixin. При кодировании базы данных библиотека анализирует подобные строки (описания) и вычленяет из них структурированную информацию. Например, Manufacturing PMI будет выделен как экономический показатель, закодирован и записан в поле .Cat_ID структуры события; также будет выделено слово (Dec) как период и записано в поле .Period_ID. Источник информации – агенство/институт или иное - Caixin - будет записан в поле .EventSource - старший байт составного поля .SOURCE_ID, а оставшиеся от исходной строки слова бла-бла-бла будут закодированы в поле .Words_ID события.

Поле .Words_ID служит для сохранения всей произвольной информации, которая осталась после вычленения из строки-описания структурированных данных, для которых предусмотрен Справочник. Представляет собой тип Ushort. Данный подход позволяет избавиться от текстовых строк и полностью перевести базу данных в числовой вид, что позволяет использовать бинарный формат хранения данных и значительно ускоряет работу всей библиотеки, равно как и снижает размер базы данных.

Каталог слов, соответственно, это хранилище подобных бла-бла-бла строк, организованное в файле words.csv. Индексация производится с нуля, подобно Справочнику в явном виде не хранится и рассчитывается автоматически при загрузке каталога в массив через позицию элемента (номер строки файла). Когда нужно распаковать базу данных в текстовый файл, например, программа сопоставляет полю .Word_ID строку из каталога, используя его код.

Следует также отметить, что строка-описание может хранить, помимо названных, еще и такие структурированные данные, как «сравнение». Сравнение представляет собой общепринятый экономический термин, показывающий как именно следует читать заявленный показатель, например YoY (Year over Year) означает, что показатель рассчитан за некий текущий период по отношению к такому же периоду предыдущего года, MoM – прирост по отношению к такому же периоду прошлого месяца.

Например

Retail Sales (YoY) (Nov)

Следует читать как «розничные продажи в ноябре по отношению к ноябрю прошлого года составили…» в процентах, а строка

Industrial Production (MoM) (Nov)

Содержит данные по промышленному производству за ноябрь по отношению к прошедшему месяцу (октябрю).

MoM или YoY будут выделены в категорию «сравнение» справочника, закодированы и записаны в поле .Compare_ID составного поля .PACK структуры события. Таким образом в структуре события наряду со «словесной» песочницей хранятся структурированные данные в отдельных полях, что позволяет организовать к ним доступ, выбрав, например, все данные за ноябрь по отношению к предыдущему году по определенному показателю.

Поскольку каталог слов хранит произвольную информацию – он обновляется автоматически и не требует ручного вмешательства.

Обновление базы данных

В текущей версии библиотеки доступны два способа обновления базы данных:

2. Автоматически, используя функцию FetchWeek(), которая загружает данные текущей недели в виде .html файла, затем надо вызвать функцию EcUpdate().

Подключение библиотеки

Функции библиотеки делятся на внешние и внутренние. Внутренние - это служебные (технические) части программы; внешние доступны для вызова из других программ при подключении библиотеки. Внешние функции в коде библиотеке имеют ключ export, соответственно можно функции внутренние сделать внешними.

Подключение (импорт) функций библиотеки в пользовательской программе в языке MQL4 осуществляется с помощью открывающей и закрывающей директивы #import, например:

#import     "EcLib.ex4"
int         EcUpdate(   uchar       Source);
void        error2log(  string      error_str);
bool        FetchWeek(  uchar       Source); 
void        dat2txt(    string      FileName,
                        datetime    TimeStart,
                        datetime    TimeEnd,
                        int         TimeShift,
                        int         PathFlag,
                        bool        Shrt);
void        ref_load(   string      &ref_array[][150],
                        string      &words_array[]);
#import

Можно подключать не все функции, а только те, которые будут использоваться. Функции необходимо объявлять полностью, с указанием параметров. Импорт функций начинается и заканчивается директивой #import, в первой строке указывается имя исполняемого файла библиотеки в папке MQL4\Libraries

Большинство функций не требуют описания структуры ec_struct в пользовательской программе; если потребность в этом возникла необходимо включить файл описания директивой #include <EcHeaders.mqh>

#include  <EcHeaders.mqh>

Функции

Внешние функции

EcUpdate

bool      EcUpdate(
uchar     Source)

Обновляет базу данных календаря и возвращает количество обновленных событий. Функция проверяет наличие .html выгрузок и, если такая выгрузка есть и/или обновлена, запускает процедуру обновления. Если база данных не существует – она будет создана. Предусмотрено полуавтоматическое обновление Справочника в процессе обновления базы данных. Если функция вызвана не из индикатора и не в режиме тестера стратегий и в новых данных обнаружены новые страны и/или валюты, функция запросит разрешения на добавление элемента в Справочник. Если пользователь уверен, что страна/валюта правильные, он принимает предложение и обновление продолжается; в противном случае обновление прервется и в созданный файл ec\ERROR.txt будет записано описание ошибки

1. Инициализация

• По умолчанию устанавливает режим обновления ADD_NONE (обновление не требуется)
• Проверяет настройки ec.ini в разделе [SourceSource] и если .html выгрузка по источнику изменилась включает режим обновления ADD_MIX
• Если база данных не найдена включает режим ADD_CREATE
• Если изменился ref.csv по отношению к своей зеркальной копии – ref00.csv – запускает реиндексацию базы данных

2. Загрузка

• Если обновление требуется, база данных найдена и .html выгрузка существует читает базу данных 0 (исходную) в память
• Запускает преобразования из .html выгрузки в базу данных 1 (новая)
• читает базу данных 1 (новая) в память
• При чтении обеих баз данных вычисляет их временные границы и по умолчанию устанавливает бит обновления .Upd_bit для всех событий

3. Обновление в режиме ADD_MIX

• Разбивает процесс обновления на три этапа:
• I. Копируются все ранние события из одной из двух баз (в зависимости от того, чей временной интервал начинается раньше) до начала пересечения временных интервалов
• II. Попарно сравнивает события двух баз по ряду параметров в интервале плюс минус сутки (чтобы найти событие даже если время изменилось). Если обнаруживает совпадение то, в зависимости от того, где содержатся более свежие данные, выключает бит обновления .Upd_bit для устаревшего события в одной из двух баз. Таким образом событие не попадет в обновленную базу данных. Записывает событие в обновленную базу данных
• III. Копируются все поздние события из одной из двух баз (в зависимости от того, чей временной интервал простирается дальше) после окончания пересечения временных интервалов

• Просто создает базу данных 0 и копирует в нее базу данных 1

FetchWeek

bool      FetchWeek(uchar Source)

Подключается к заданному источнику и загружает .html страницу с данными текущей недели. Использует функцию WebRequest языка MQL4, поэтому ее нельзя использовать в индикаторах и в режиме тестера стратегий. Функция настраивается в файле ec.ini в разделе [FetchWeek] (можно указать источники, страны и важность событий, которые надо загружать).

В текущей версии библиотеки не рекомендуется использовать другие источники кроме 1. Возможны ошибки

EcCopy

int        EcCopy(
datetime   TimeStart,
datetime   TimeEnd,
ec_struct  &ec_array[])

Копирует из базы данных события (включая праздники) в массив структур типа ec_struct; возвращает количество скопированных событий.

EcNewsCount

int        EcNewsCount(
datetime   TimeStart,
datetime   TimeEnd,
uchar      DaysAhead,
uchar      Currency_ID,
uchar      Volatility_ID,
uint       &EventTime[],
uchar      &EventCurrency[],
uchar      &EventVolatility[])

Возвращает количество событий новостного типа (EventType_ID = 2) по указанной валюте указанной значимости за указанный интервал. Использует упреждающее чтение бд для минимизации обращений к файлам (задается пользователем через параметр DaysAhead). При каждом вызове функция проверяет наличие в буферных массивах нужных данных и если не находит – производит чтение бд и добавляет данные, в противном случае сразу вычисляет результат через буферные массивы в памяти.

Принудительно обнуляет буферные массивы и заполняет их заново в следующих случаях:

1. При обновлении бд
2. при Currency_ID = NULL
3. Если интервал (TimeStart, TimeEnd) за пределами временного интервала ранее прочитанного в бд и сохраненного в EventTime[0] и EventTime[1]

При очередном чтении бд функция будет заполнять буферные массивы событиями в интервале:

• от TimeStart до TimeEnd+DaysAhead (в секундах), если буферные массивы были пустые (при первом вызове функции или принудительном обнулении (см. выше)
• от EventTime[0] до EventTime[1], если в буферных массивах уже были данные и проверка на временной интервал пройдена, т.е. (TimeStart, TimeEnd) внутри (EventTime[0], EventTime[1])

dat2txt

void      dat2txt(
string    FileName,
datetime  TimeStart,
datetime  TimeEnd),
int       TimeShift,
int       PathFlag
bool      Shrt)

Выгружает базу данных из файла FileName.dat за указанный интервал в текстовый файл; в качестве разделителя по умолчанию используется знак ‘;’ (можно исправить в коде функции, переменная uchar delimiter). Вывод производится в файл с расширением .csv и легко открывается в MS Excel.

ref_load

void      ref_load(
string    &ref_array[][150],
string    &words_array[])

Читает файлы справочника и каталога слов; загружает их в массивы; выгружает справочник в текстовый файл ref.txt.

int        EcDbReIndex()