Japan Bank Holiday and Gotobi Library (MT5/MT4): руководство пользователя, функции и примеры

Japan Bank Holiday and Gotobi Library — бесплатная библиотека для MetaTrader 5 и MetaTrader 4. Она отвечает на календарные вопросы рынка иены прямо в вашем собственном советнике, индикаторе или скрипте. Это руководство предназначено для разработчиков и относится к версии 1.00 на обеих платформах.

На какие вопросы отвечает библиотека

• Государственные праздники Японии, включая перенесённые выходные, «народные выходные» и разовые праздники, с английским названием каждого.
• Выходные дни японских банков: субботы, воскресенья, государственные праздники и с 31 декабря по 3 января. Все остальные дни — рабочие дни в Токио.
• Дни gotobi: 5-е, 10-е, 15-е, 20-е, 25-е число и последний день месяца. Если такой день — банковский выходной, gotobi переносится на предыдущий рабочий день того же месяца.
• Время токийского фиксинга — 09:55 по японскому времени, а также перевод серверного времени в японское и обратно. В Японии нет летнего времени (JST = UTC+9).

Годы с 1980 по 2099. Правила вычисляются, поэтому таблицу праздников обновлять не нужно. Без DLL, без веб-запросов, без файлов, без торговых функций.

Установка

1. На странице продукта нажмите кнопку бесплатной загрузки (Free Download) — откроется MetaTrader — или найдите библиотеку в разделе Инструменты > Маркет (в MT4 это окно называется «Терминал»). MT5 и MT4 — отдельные продукты.
2. Маркет устанавливает библиотеку в файл MQL5\Libraries\Market\Japan Bank Holiday and Gotobi Library.ex5 (MT5) или MQL4\Libraries\Market\Japan Bank Holiday and Gotobi Library MT4.ex4 (MT4). Эти папки открываются через Файл > Открыть каталог данных.
3. Установленные продукты и их обновления находятся в разделе Инструменты > Маркет > Покупки.
4. Библиотека не устанавливается на график. Ваша собственная программа загружает её через блок импорта.

Импорт

Сохраните заголовочный файл для вашей платформы в папке Include и добавьте одну строку в начало своей программы:

• JpMarketCalendar_Market.mqh (MT5): сохраните его в MQL5\Include.
• JpMarketCalendar_Market_MT4.mqh (MT4): сохраните его в MQL4\Include.

#include <JpMarketCalendar_Market.mqh>       // MT5
#include <JpMarketCalendar_Market_MT4.mqh>   // MT4

Каждый заголовочный файл импортирует все 17 функций и определяет правила летнего времени JP_DST_NONE (0), JP_DST_US (1) и JP_DST_EU (2). Если вы вставляете блок импорта сами, его первая строка должна в точности соответствовать установленному файлу (две обратные косые черты): #import "Market\\Japan Bank Holiday and Gotobi Library.ex5" (MT5) или #import "Market\\Japan Bank Holiday and Gotobi Library MT4.ex4" (MT4).

Для начала — две программы, обе без ордеров:

• JpCalendarDemo.mq5 / JpCalendarDemo_MT4.mq4: скрипт, который выводит серверное и японское время, ближайшие фиксинги, а также праздники и дни gotobi за выбранные вами годы. Если он их выводит, библиотека установлена и импортирована правильно.
• JpCalendarExample.mq5 / JpCalendarExample_MT4.mq4: советник, который с помощью Comment() показывает время фиксинга в день gotobi, название праздника или следующий день gotobi.

Все шесть файлов компилируются с 0 ошибок и 0 предупреждений. Ниже — вывод демо-скрипта на демо-сервере MT5; версия для MT4 выводит те же строки.

Справочник функций

Аргументы-даты задаются в японском времени; можно передавать любое время суток. Вне диапазона 1980-2099 функции возвращают false, 0, "" или -1. Две функции установки принимают значение, кратное 900 секундам, от -43200 до 50400; при любом другом значении они выводят причину, возвращают false и сохраняют прежнюю настройку.

Примеры

Сегодня в Японии:

datetime jst = JpNowJst();                       // Japan time now
if(JpIsBankHoliday(jst))
   Print("Tokyo banks are closed: ", JpHolidayName(jst));   // "" on a plain weekend
else if(JpIsGotobi(jst) && jst < JpTokyoFixing(jst))
   Print("Gotobi morning, fixing at ", TimeToString(JpJstToServer(JpTokyoFixing(jst))), " server time");

Ближайший фиксинг в день gotobi, который ещё не прошёл:

datetime jst = JpNowJst();
datetime g   = JpNextGotobi(jst);                // today counts all day
if(g != 0 && JpTokyoFixing(g) < jst)             // today's fixing has passed
   g = JpNextGotobi(g + 86400);
Print("Next gotobi fixing: ", TimeToString(JpJstToServer(JpTokyoFixing(g))), " server time");

Дни gotobi одного месяца:

datetime days[];                                 // must be a dynamic array
int n = JpGotobiDaysOfMonth(2027, 5, days);      // 5 days: 10, 14, 20, 25 and 31
for(int i = 0; i < n; i++)
   Print(TimeToString(days[i], TIME_DATE));

Часовые пояса и тестер стратегий

• Серверное время — это не японское время: в демо выше сервер показывает 21:43 13 октября, а в Японии в этот момент уже 03:43 14 октября. Прежде чем спрашивать о дне, переведите время с помощью JpServerToJst() или используйте JpNowJst().
• По умолчанию смещение автоматическое: TimeTradeServer() - TimeGMT() в MT5, с округлением до 15 минут; оно заново считывается при каждом вызове. Сразу после запуска терминала оно может несколько секунд быть равно 0.
• В MT4 нет TimeTradeServer(), поэтому используется TimeCurrent() — время последней котировки, которое может быть неверным после запуска или при закрытом рынке. В MT4 задавайте смещение сами.
• В тестере стратегий TimeGMT() возвращает серверное время, поэтому автоматическое смещение равно 0. Библиотека один раз записывает напоминание в журнал тестера. Задайте смещение в OnInit().
• Автоматическое смещение — это сегодняшнее смещение. Для прошлых баров, между которыми был переход на летнее время, задайте правило сервера с помощью JpSetServerTimeZone().
• Настройки действуют в той программе, которая их вызывает: вызывайте их в OnInit() каждого советника или индикатора.

input int ServerGmtWinter = 2;   // server GMT offset outside summer time, in hours
input int ServerDstRule   = 1;   // summer time rule: 0 none, 1 US, 2 EU

int OnInit()
  {
   if(!JpSetServerTimeZone(ServerGmtWinter * 3600, ServerDstRule))
      return(INIT_PARAMETERS_INCORRECT);         // the library printed the reason
   return(INIT_SUCCEEDED);
  }

Правило США: со второго воскресенья марта по первое воскресенье ноября (до 2007 года в США действовали более ранние даты). Правило ЕС: с последнего воскресенья марта по последнее воскресенье октября (до 1996 года — по последнее воскресенье сентября). Сервер с GMT+2 зимой и GMT+3 в период летнего времени США — это 7200 с правилом 1. Демо-скрипт показывает текущее смещение вашего сервера; какому летнему времени следует сервер, может сказать ваш брокер. Чтобы в MT5 при реальной работе сохранялось автоматическое смещение, вызывайте функцию установки только тогда, когда MQLInfoInteger(MQL_TESTER) равно true, как это делает пример советника.

Используемые правила и их проверка

• Закон Японии о государственных праздниках с поправками: фиксированные даты, праздники в понедельник (День совершеннолетия и День здоровья и спорта — с 2000 года, День моря и День почитания старших — с 2003 года), День гор с 2016 года, День рождения императора по эпохам и перенесённые дни 2020 и 2021 годов.
• Перенесённый выходной: если государственный праздник выпадает на воскресенье, выходным становится ближайший следующий день, который не является государственным праздником (с 2007 года; до этого — только следующий день).
• «Народный выходной»: день между двумя государственными праздниками (с 1986 года), например 22 сентября 2026 года.
• Разовые праздники: 1989-02-24, 1990-11-12, 1993-06-09, 2019-05-01 и 2019-10-22.
• Дни равноденствия: стандартная приближённая формула, действительная для 1980-2099 годов. Правительство объявляет каждый день равноденствия в феврале предыдущего года.
• Выходные банков: субботы, воскресенья, государственные праздники и с 31 декабря по 3 января (Закон о банках); текущее правило применяется ко всем годам.
• Gotobi: если 5-е число пришлось бы перенести в предыдущий месяц, этот день уже является gotobi конца предыдущего месяца и указывается только там. Поэтому в мае 2027 года 5 дней gotobi.
• Это правила, действовавшие на момент выпуска версии 1.00 (октябрь 2026 года).

Проверки перед выпуском: обе версии компилируются с 0 ошибок и 0 предупреждений; версия для MT4 собрана из того же исходного кода (отличается только функция времени). Все 789 государственных праздников с 1980 по 2027 год день в день совпадают со списком Кабинета министров Японии; сейчас этот список заканчивается 2027 годом. Формула равноденствия даёт официальную дату во всех годах до 2027 и совпадает с астрономическим расчётом во всех годах до 2099. Импорт по пути Маркета загружается и в тестере стратегий.

Вопросы разработчиков

• Моя программа останавливается с ошибкой, связанной с библиотекой. Проверьте, что библиотека установлена и что строка #import в точности совпадает с именем файла. Имя файла для MT4 заканчивается на MT4.
• Вечером японская дата сдвинута на один день. Вы передали серверное время. Сначала переведите его с помощью JpServerToJst().
• JpGotobiDaysOfMonth() возвращает -1. Передайте динамический массив ( datetime days[]; ), год от 1980 до 2099 и месяц от 1 до 12.
• Достаточно ли она быстрая для OnTick()? Да. Результаты кэшируются по годам. В кэше хранятся 2 года, поэтому цикл, который перескакивает между многими годами, работает медленнее.

Страницы продуктов: Japan Bank Holiday and Gotobi Library (MT5) и Japan Bank Holiday and Gotobi Library MT4. Если что-то непонятно, напишите мне личное сообщение на MQL5 и приложите используемый код и последние строки вкладки «Эксперты».