Japan Bank Holiday and Gotobi Library (MT5/MT4) : manuel d'utilisation, fonctions et exemples

Japan Bank Holiday and Gotobi Library est une bibliothèque gratuite pour MetaTrader 5 et MetaTrader 4. Elle répond aux questions de calendrier du marché du yen directement dans votre propre Expert Advisor, indicateur ou script. Ce manuel s'adresse aux développeurs et s'applique à la version 1.00 sur les deux plateformes.

Ce qu'elle indique

• Les jours fériés nationaux japonais, y compris les jours fériés de substitution, les jours fériés des citoyens et les jours fériés exceptionnels, avec le nom anglais de chacun.
• Les jours fériés bancaires japonais : samedis, dimanches, jours fériés nationaux et du 31 décembre au 3 janvier. Tous les autres jours sont des jours ouvrés à Tokyo.
• Les jours gotobi : le 5, le 10, le 15, le 20, le 25 et le dernier jour du mois. Lorsqu'il tombe un jour férié bancaire, le gotobi est avancé au jour ouvré précédent du même mois.
• L'heure du fixing de Tokyo, 09:55, heure du Japon, et la conversion de l'heure du serveur en heure du Japon et inversement. Le Japon n'a pas d'heure d'été (JST = UTC+9).

Années 1980 à 2099. Les règles sont calculées : il n'y a donc aucune table de jours fériés à mettre à jour. Pas de DLL, pas de requêtes web, pas de fichiers, pas de fonctions de trading.

Installation

1. Sur la page du produit, cliquez sur le bouton de téléchargement gratuit (il ouvre MetaTrader), ou trouvez-la dans Boîte à outils > Market (dans MT4, cette fenêtre s'appelle Terminal). MT5 et MT4 sont des produits distincts.
2. Le Market installe la bibliothèque sous MQL5\Libraries\Market\Japan Bank Holiday and Gotobi Library.ex5 (MT5) ou MQL4\Libraries\Market\Japan Bank Holiday and Gotobi Library MT4.ex4 (MT4). File > Open Data Folder affiche ces dossiers.
3. Les produits installés et leurs mises à jour se trouvent dans Boîte à outils > Market > Achats.
4. Une bibliothèque ne se place pas sur un graphique. C'est votre propre programme qui la charge, par le bloc d'importation.

L'importer

Enregistrez le fichier d'en-tête de votre plateforme dans le dossier Include et ajoutez une ligne au début de votre programme :

• JpMarketCalendar_Market.mqh (MT5) : enregistrez-le dans MQL5\Include.
• JpMarketCalendar_Market_MT4.mqh (MT4) : enregistrez-le dans MQL4\Include.

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

Chaque fichier d'en-tête importe les 17 fonctions et définit les règles d'heure d'été JP_DST_NONE (0), JP_DST_US (1) et JP_DST_EU (2). Si vous collez vous-même le bloc d'importation, sa première ligne doit correspondre exactement au fichier installé (avec deux barres obliques inverses) : #import "Market\\Japan Bank Holiday and Gotobi Library.ex5" (MT5) ou #import "Market\\Japan Bank Holiday and Gotobi Library MT4.ex4" (MT4).

Deux programmes pour commencer, tous deux sans ordres :

• JpCalendarDemo.mq5 / JpCalendarDemo_MT4.mq4 : un script qui affiche l'heure du serveur et l'heure du Japon, les prochains fixings, ainsi que les jours fériés et les jours gotobi des années que vous choisissez. S'il les affiche, la bibliothèque est correctement installée et importée.
• JpCalendarExample.mq5 / JpCalendarExample_MT4.mq4 : un Expert Advisor qui affiche avec Comment() l'heure du fixing gotobi, le nom du jour férié ou le prochain gotobi.

Les six fichiers se compilent avec 0 erreur et 0 avertissement. Voici la sortie du script de démonstration sur un serveur de démo MT5 ; la version MT4 affiche les mêmes lignes.

Référence des fonctions

Les arguments de date sont en heure du Japon ; n'importe quelle heure de la journée peut être passée. En dehors de 1980-2099, les fonctions renvoient false, 0, "" ou -1. Les deux fonctions de réglage acceptent un multiple de 900 secondes de -43200 à 50400 ; pour toute autre valeur, elles écrivent la raison dans le journal, renvoient false et conservent le réglage précédent.

Exemples

Aujourd'hui au Japon :

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

Le prochain fixing gotobi qui n'est pas encore passé :

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

Les jours gotobi d'un mois :

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

Fuseaux horaires et Strategy Tester

• L'heure du serveur n'est pas l'heure du Japon : dans la démonstration ci-dessus, le serveur affiche 21:43 le 13 octobre alors qu'il est 03:43 le 14 octobre au Japon. Convertissez avec JpServerToJst() avant de poser une question sur un jour, ou utilisez JpNowJst().
• Le décalage par défaut est automatique : TimeTradeServer() - TimeGMT() sur MT5, arrondi à 15 minutes et relu à chaque appel. Juste après le démarrage du terminal, il peut valoir 0 pendant quelques secondes.
• MT4 n'a pas TimeTradeServer() et utilise TimeCurrent(), l'heure de la dernière cotation, qui peut être fausse après le démarrage ou lorsque le marché est fermé. Sur MT4, réglez vous-même le décalage.
• Dans le Strategy Tester, TimeGMT() renvoie l'heure du serveur : le décalage automatique vaut donc 0. La bibliothèque écrit un rappel dans le journal du testeur. Réglez le décalage dans OnInit().
• Le décalage automatique est celui d'aujourd'hui. Pour des barres passées situées de part et d'autre d'un changement d'heure d'été, définissez la règle du serveur avec JpSetServerTimeZone().
• Les réglages s'appliquent au programme qui les appelle : appelez-les dans OnInit() de chaque Expert Advisor ou indicateur.

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

Règle US : du deuxième dimanche de mars au premier dimanche de novembre (avant 2007, les anciennes dates américaines). Règle UE : du dernier dimanche de mars au dernier dimanche d'octobre (septembre avant 1996). Un serveur à GMT+2 en hiver et à GMT+3 pendant l'heure d'été américaine correspond à 7200 avec la règle 1. Le script de démonstration affiche le décalage actuel de votre serveur ; votre courtier peut vous dire quelle heure d'été il suit. Pour conserver le décalage automatique en réel sur MT5, n'appelez la fonction de réglage que lorsque MQLInfoInteger(MQL_TESTER) vaut true, comme le fait l'EA d'exemple.

Règles utilisées et vérifications

• Loi sur les jours fériés nationaux, avec ses modifications : dates fixes, jours fériés placés le lundi (Jour de la majorité et Jour de la santé et du sport depuis 2000, Jour de la mer et Jour du respect des personnes âgées depuis 2003), Jour de la montagne depuis 2016, l'anniversaire de l'Empereur selon l'ère et les jours déplacés de 2020 et 2021.
• Jour férié de substitution : lorsqu'un jour férié national tombe un dimanche, le jour suivant qui n'est pas un jour férié national est férié (depuis 2007 ; avant, seulement le lendemain).
• Jour férié des citoyens : un jour situé entre deux jours fériés nationaux (depuis 1986), par exemple le 22 septembre 2026.
• Jours fériés exceptionnels : 1989-02-24, 1990-11-12, 1993-06-09, 2019-05-01 et 2019-10-22.
• Jours d'équinoxe : la formule d'approximation standard, valable pour 1980-2099. Le gouvernement annonce chaque jour d'équinoxe en février de l'année précédente.
• Jours fériés bancaires : samedis, dimanches, jours fériés nationaux et du 31 décembre au 3 janvier (loi bancaire) ; la règle actuelle est appliquée à toutes les années.
• Gotobi : si le 5 devait être avancé dans le mois précédent, ce jour est déjà le gotobi de fin de mois du mois précédent et n'est listé que là. Mai 2027 compte donc 5 jours gotobi.
• Ce sont les règles en vigueur au moment de la création de la version 1.00 (octobre 2026).

Vérifications avant publication : les deux versions se compilent avec 0 erreur et 0 avertissement ; la version MT4 est produite à partir du même code source (seule la fonction d'heure diffère). Les 789 jours fériés nationaux de 1980 à 2027 correspondent jour par jour à la liste du Bureau du Cabinet ; cette liste s'arrête actuellement en 2027. La formule des équinoxes donne la date officielle pour chaque année jusqu'en 2027 et concorde avec un calcul astronomique pour chaque année jusqu'en 2099. L'importation depuis le chemin du Market se charge aussi dans le Strategy Tester.

Questions posées par les développeurs

• Mon programme s'arrête avec une erreur concernant la bibliothèque. Vérifiez que la bibliothèque est installée et que la ligne #import correspond exactement au nom du fichier. Le nom du fichier MT4 se termine par MT4.
• Le soir, la date japonaise est décalée d'un jour. Vous avez passé l'heure du serveur. Convertissez-la d'abord avec JpServerToJst().
• JpGotobiDaysOfMonth() renvoie -1. Passez un tableau dynamique ( datetime days[]; ), une année de 1980 à 2099 et un mois de 1 à 12.
• Est-elle assez rapide pour OnTick() ? Oui. Les résultats sont mis en cache par année. Le cache conserve 2 années : une boucle qui saute entre de nombreuses années est donc plus lente.

Pages des produits : Japan Bank Holiday and Gotobi Library (MT5) et Japan Bank Holiday and Gotobi Library MT4. Si quelque chose n'est pas clair, envoyez-moi un message privé sur MQL5 avec le code que vous utilisez et les dernières lignes de l'onglet Experts.