Japan Bank Holiday and Gotobi Library (MT5/MT4): Benutzerhandbuch, Funktionen und Beispiele

Japan Bank Holiday and Gotobi Library ist eine kostenlose Bibliothek für MetaTrader 5 und MetaTrader 4. Sie beantwortet die Kalenderfragen des Yen-Markts direkt in Ihrem eigenen Expert Advisor, Indikator oder Skript. Dieses Handbuch richtet sich an Entwickler und gilt für Version 1.00 auf beiden Plattformen.

Was sie beantwortet

• Japanische Nationalfeiertage, einschließlich Ersatzfeiertagen, Bürgerfeiertagen und einmaligen Feiertagen, jeweils mit dem englischen Namen.
• Japanische Bankfeiertage: Samstage, Sonntage, Nationalfeiertage und 31. Dezember bis 3. Januar. Alle anderen Tage sind Tokioter Geschäftstage.
• Gotobi-Tage: der 5., 10., 15., 20., 25. und der letzte Tag des Monats. An einem Bankfeiertag verschiebt sich der gotobi-Tag auf den vorherigen Geschäftstag desselben Monats.
• Die Uhrzeit des Tokioter Fixings, 09:55 japanischer Zeit, sowie die Umrechnung von Serverzeit in japanische Zeit und zurück. Japan hat keine Sommerzeit (JST = UTC+9).

Jahre 1980 bis 2099. Die Regeln werden berechnet, daher gibt es keine Feiertagstabelle zu aktualisieren. Keine DLL, keine Webanfragen, keine Dateien, keine Handelsfunktionen.

Installation

1. Klicken Sie auf der Produktseite auf die Schaltfläche für den kostenlosen Download (Free Download; sie öffnet MetaTrader), oder suchen Sie die Bibliothek in Toolbox > Market (in MT4 heißt dieses Fenster Terminal). MT5 und MT4 sind getrennte Produkte.
2. Der Market installiert die Bibliothek als MQL5\Libraries\Market\Japan Bank Holiday and Gotobi Library.ex5 (MT5) bzw. MQL4\Libraries\Market\Japan Bank Holiday and Gotobi Library MT4.ex4 (MT4). File > Open Data Folder zeigt diese Ordner.
3. Installierte Produkte und ihre Updates finden Sie in Toolbox > Market > Purchased.
4. Eine Bibliothek wird nicht auf einen Chart gezogen. Ihr eigenes Programm lädt sie über den Importblock.

Importieren

Speichern Sie die Header-Datei für Ihre Plattform im Ordner Include und fügen Sie am Anfang Ihres Programms eine Zeile hinzu:

• JpMarketCalendar_Market.mqh (MT5): Speichern Sie die Datei in MQL5\Include.
• JpMarketCalendar_Market_MT4.mqh (MT4): Speichern Sie die Datei in MQL4\Include.

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

Jede Header-Datei importiert alle 17 Funktionen und definiert die Sommerzeitregeln JP_DST_NONE (0), JP_DST_US (1) und JP_DST_EU (2). Wenn Sie den Importblock selbst einfügen, muss seine erste Zeile genau zur installierten Datei passen (zwei Backslashes): #import "Market\\Japan Bank Holiday and Gotobi Library.ex5" (MT5) bzw. #import "Market\\Japan Bank Holiday and Gotobi Library MT4.ex4" (MT4).

Zwei Programme für den Einstieg, beide ohne Orders:

• JpCalendarDemo.mq5 / JpCalendarDemo_MT4.mq4: ein Skript, das die Serverzeit und die japanische Zeit, die nächsten Fixings sowie die Feiertage und gotobi-Tage der gewählten Jahre ausgibt. Gibt es sie aus, ist die Bibliothek richtig installiert und importiert.
• JpCalendarExample.mq5 / JpCalendarExample_MT4.mq4: ein Expert Advisor, der mit Comment() die Uhrzeit des gotobi-Fixings, den Namen des Feiertags oder den nächsten gotobi-Tag anzeigt.

Alle sechs Dateien kompilieren mit 0 Fehlern und 0 Warnungen. Unten sehen Sie die Ausgabe des Demo-Skripts auf einem MT5-Demoserver; die MT4-Version gibt dieselben Zeilen aus.

Funktionsreferenz

Datumsargumente sind japanische Zeit; jede Uhrzeit des Tages kann übergeben werden. Außerhalb von 1980-2099 geben die Funktionen false, 0, "" oder -1 zurück. Die beiden Setter akzeptieren ein Vielfaches von 900 Sekunden von -43200 bis 50400; bei jedem anderen Wert geben sie den Grund aus, liefern false zurück und behalten die vorherige Einstellung bei.

Beispiele

Heute in Japan:

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");

Das nächste gotobi-Fixing, das noch nicht vorbei ist:

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");

Die gotobi-Tage eines Monats:

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));

Zeitzonen und der Strategietester

• Serverzeit ist nicht japanische Zeit: In der Demo oben zeigt der Server 21:43 am 13. Oktober, während es in Japan 03:43 am 14. Oktober ist. Rechnen Sie mit JpServerToJst() um, bevor Sie nach einem Tag fragen, oder verwenden Sie JpNowJst().
• Der Standardversatz ist automatisch: TimeTradeServer() - TimeGMT() in MT5, auf 15 Minuten gerundet und bei jedem Aufruf neu gelesen. Direkt nach dem Start des Terminals kann er einige Sekunden lang 0 betragen.
• MT4 hat kein TimeTradeServer() und verwendet TimeCurrent(), die Zeit des letzten Kurses, die nach dem Start oder bei geschlossenem Markt falsch sein kann. Legen Sie in MT4 den Versatz selbst fest.
• Im Strategietester liefert TimeGMT() die Serverzeit, daher ist der automatische Versatz 0. Die Bibliothek schreibt einmal einen Hinweis in das Testerjournal. Legen Sie den Versatz in OnInit() fest.
• Der automatische Versatz ist der heutige Versatz. Für vergangene Bars über einen Sommerzeitwechsel hinweg legen Sie die Regel des Servers mit JpSetServerTimeZone() fest.
• Einstellungen gelten für das Programm, das sie aufruft: Rufen Sie sie in OnInit() jedes Expert Advisors oder Indikators auf.

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);
  }

US-Regel: zweiter Sonntag im März bis erster Sonntag im November (vor 2007 galten in den USA andere Daten). EU-Regel: letzter Sonntag im März bis letzter Sonntag im Oktober (vor 1996 bis zum letzten Sonntag im September). Für einen Server mit GMT+2 im Winter und GMT+3 in der US-Sommerzeit gilt 7200 mit Regel 1. Das Demo-Skript zeigt den aktuellen Versatz Ihres Servers; Ihr Broker kann Ihnen sagen, welcher Sommerzeit er folgt. Um in MT5 den automatischen Versatz im Live-Betrieb zu behalten, rufen Sie den Setter nur auf, wenn MQLInfoInteger(MQL_TESTER) true ist, wie es der Beispiel-EA tut.

Verwendete Regeln und wie sie geprüft wurden

• Gesetz über die Nationalfeiertage in seiner geänderten Fassung: feste Daten, Montagsfeiertage (Tag der Volljährigkeit und Tag des Sports ab 2000, Tag des Meeres und Tag der Ehrung der Alten ab 2003), Tag der Berge ab 2016, der Geburtstag des Kaisers je nach Ära und die verlegten Tage von 2020 und 2021.
• Ersatzfeiertag: Fällt ein Nationalfeiertag auf einen Sonntag, ist der nächste Tag, der kein Nationalfeiertag ist, ein Feiertag (ab 2007; davor nur der Folgetag).
• Bürgerfeiertag: ein Tag zwischen zwei Nationalfeiertagen (ab 1986), zum Beispiel der 22. September 2026.
• Einmalige Feiertage: 1989-02-24, 1990-11-12, 1993-06-09, 2019-05-01 und 2019-10-22.
• Tage der Tagundnachtgleiche: die übliche Näherungsformel, gültig für 1980-2099. Die Regierung gibt jeden dieser Tage im Februar des Vorjahres bekannt.
• Bankfeiertage: Samstage, Sonntage, Nationalfeiertage und 31. Dezember bis 3. Januar (Bankengesetz); die heutige Regel wird auf alle Jahre angewendet.
• Gotobi: Würde sich der 5. in den Vormonat verschieben, ist dieser Tag bereits der gotobi-Tag zum Monatsende des Vormonats und wird nur dort aufgeführt. Der Mai 2027 hat daher 5 gotobi-Tage.
• Dies sind die Regeln, die galten, als Version 1.00 erstellt wurde (Oktober 2026).

Prüfungen vor der Veröffentlichung: Beide Versionen kompilieren mit 0 Fehlern und 0 Warnungen; die MT4-Version wird aus demselben Quelltext erstellt (nur die Zeitfunktion unterscheidet sich). Alle 789 Nationalfeiertage von 1980 bis 2027 stimmen Tag für Tag mit der Liste des japanischen Kabinettsbüros überein; diese Liste endet derzeit 2027. Die Formel für die Tagundnachtgleiche liefert in jedem Jahr bis 2027 das offizielle Datum und stimmt in jedem Jahr bis 2099 mit einer astronomischen Berechnung überein. Der Import über den Market-Pfad wird auch im Strategietester geladen.

Fragen von Entwicklern

• Mein Programm bricht mit einem Fehler zur Bibliothek ab. Prüfen Sie, ob die Bibliothek installiert ist und ob die Zeile #import genau zum Dateinamen passt. Der Dateiname für MT4 endet auf MT4.
• Das japanische Datum liegt abends um einen Tag daneben. Sie haben die Serverzeit übergeben. Rechnen Sie sie zuerst mit JpServerToJst() um.
• JpGotobiDaysOfMonth() gibt -1 zurück. Übergeben Sie ein dynamisches Array ( datetime days[]; ), ein Jahr von 1980 bis 2099 und einen Monat von 1 bis 12.
• Ist sie schnell genug für OnTick()? Ja. Die Ergebnisse werden pro Jahr zwischengespeichert. Der Cache hält 2 Jahre, daher ist eine Schleife, die zwischen vielen Jahren springt, langsamer.

Produktseiten: Japan Bank Holiday and Gotobi Library (MT5) und Japan Bank Holiday and Gotobi Library MT4. Wenn etwas unklar ist, senden Sie mir bitte eine private Nachricht auf MQL5 mit dem Code, den Sie verwenden, und den letzten Zeilen aus dem Tab Experten.