Japan Bank Holiday and Gotobi Library MT4

Japan Bank Holiday and Gotobi Library MT4 отвечает на календарные вопросы рынка иены прямо в вашем советнике, индикаторе или скрипте: выходной ли сегодня у японских банков, день ли готоби, когда следующий токийский фиксинг и сколько сейчас времени в Японии по серверу вашего брокера.

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

На что отвечает библиотека

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

Функции

• JpIsBankHoliday(date) - true в субботы, воскресенья, государственные праздники и с 31 декабря по 3 января.
• JpIsBusinessDay(date) - true в рабочие дни банков Токио.
• JpIsNationalHoliday(date) - true в государственные праздники, включая перенесённые и «народные» выходные.
• JpHolidayName(date) - английское название, например "Marine Day", "Substitute Holiday" или "Bank Holiday"; в остальные дни - пустая строка.
• JpIsGotobi(date) - true в дни готоби.
• JpGotobiDaysOfMonth(year, month, days[]) - все дни готоби месяца; возвращает их количество.
• JpNextGotobi(date) / JpPrevGotobi(date) - первый готоби в эту дату или позже / последний готоби в эту дату или раньше.
• JpTokyoFixing(date) - 09:55 по японскому времени этого дня.
• JpNowJst() - текущее японское время.
• JpServerToJst(time) / JpJstToServer(time) - перевод между серверным и японским временем.
• JpServerGmtOffsetSeconds() - смещение сервера от GMT в секундах (автоматически: TimeCurrent() - TimeGMT(), с округлением до 15 минут).
• JpSetServerGmtOffset(seconds) - постоянное смещение, например 7200 для GMT+2.
• JpSetServerTimeZone(seconds, rule) - смещение вне летнего времени и правило летнего времени: 0 - нет, 1 - США, 2 - ЕС.
• JpSetServerGmtOffsetAuto() - возврат к автоматическому смещению (по умолчанию).
• JpLibraryVersion() - версия, "1.00".

Аргументы-даты задаются в японском времени; можно передавать любое время суток. Даты праздников и готоби возвращаются как 00:00 по японскому времени.

Как использовать

Market устанавливает библиотеку в файл MQL4\Libraries\Market\Japan Bank Holiday and Gotobi Library MT4.ex4. Вставьте этот блок импорта в начало своей программы (или сохраните его как MQL4\Include\JpMarketCalendar.mqh и подключите этот файл):

#import "Market\\Japan Bank Holiday and Gotobi Library MT4.ex4"
string   JpLibraryVersion();
bool     JpIsNationalHoliday(datetime date_jst);
bool     JpIsBankHoliday(datetime date_jst);
bool     JpIsBusinessDay(datetime date_jst);
string   JpHolidayName(datetime date_jst);
bool     JpIsGotobi(datetime date_jst);
int      JpGotobiDaysOfMonth(int year, int month, datetime &out[]);
datetime JpNextGotobi(datetime from_jst);
datetime JpPrevGotobi(datetime from_jst);
datetime JpTokyoFixing(datetime date_jst);
int      JpServerGmtOffsetSeconds();
bool     JpSetServerGmtOffset(int seconds);
bool     JpSetServerTimeZone(int standard_offset_seconds, int dst_rule);
void     JpSetServerGmtOffsetAuto();
datetime JpServerToJst(datetime server_time);
datetime JpJstToServer(datetime jst);
datetime JpNowJst();
#import

Пример для советника:

int OnInit()
  {
   // In the Strategy Tester TimeGMT() returns server time: set the offset yourself
   if(MQLInfoInteger(MQL_TESTER))
      JpSetServerTimeZone(2 * 3600, 1);        // GMT+2, +1 hour in US summer time
   return(INIT_SUCCEEDED);
  }

void OnTick()
  {
   datetime jst = JpNowJst();                  // Japan time now
   if(JpIsGotobi(jst))
      Comment("Gotobi - Tokyo fixing at ",
              TimeToString(JpJstToServer(JpTokyoFixing(jst))), " server time");
   else if(JpIsBankHoliday(jst))
      Comment("Japanese bank holiday ", JpHolidayName(jst));
   else
      Comment("Next gotobi: ", TimeToString(JpNextGotobi(jst), TIME_DATE));
  }

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

• Закон Японии о государственных праздниках с поправками: фиксированные даты, праздники в понедельник (День совершеннолетия и День здоровья и спорта с 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 годов. Она даёт официальную дату во всех годах до 2027 и совпадает с астрономическим расчётом во всех годах до 2099. Правительство объявляет дни равноденствия в феврале предыдущего года.
• Выходные банков: субботы, воскресенья, государственные праздники и 31 декабря - 3 января (Закон о банках; текущее правило применяется ко всем годам).
• Готоби: если день выходной для банков, он переносится на предыдущий рабочий день того же месяца. Если 5 число пришлось бы перенести в предыдущий месяц (например, в мае 2027 года), этот рабочий день уже является готоби конца предыдущего месяца и указывается только там.

Что важно знать

• Допустимые годы: 1980-2099. Вне этого диапазона функции возвращают false, 0, пустую строку или -1.
• Тестер стратегий: в нём TimeGMT() возвращает серверное время, поэтому автоматическое смещение равно 0. Вызовите JpSetServerGmtOffset() или JpSetServerTimeZone() в OnInit(), как в примере. Если в тестере используется автоматическое смещение, библиотека один раз выводит напоминание в журнал тестера.
• В MT4 нет TimeTradeServer(), поэтому автоматическое смещение использует TimeCurrent() - время последней котировки. Оно верно, пока приходят котировки; сразу после запуска терминала или при закрытом рынке оно может быть неверным (значения вне диапазона от -12 до +14 часов игнорируются). В MT4 надёжнее задать смещение с помощью JpSetServerTimeZone().
• Автоматическое смещение - это текущее смещение. Чтобы переводить прошлые бары через переход на летнее время, задайте правило сервера с помощью JpSetServerTimeZone().
• Настройки действуют в той программе, которая их вызвала: вызывайте их в OnInit() каждого советника или индикатора.
• JpGotobiDaysOfMonth() требует динамический массив: datetime days[];
• Результаты кэшируются по годам; повторный вызов в пределах одного года занимает около 0,1 микросекунды.

Поддержка

Если что-то непонятно, отправьте мне личное сообщение на MQL5.