Japan Bank Holiday and Gotobi Library MT4

Japan Bank Holiday and Gotobi Library MT4 risponde alle domande di calendario del mercato dello yen direttamente nel tuo Expert Advisor, indicatore o script: oggi le banche giapponesi sono chiuse, è un giorno gotobi, quando è il prossimo fixing di Tokyo e che ora è in Giappone secondo il server del tuo broker.

Tutte le regole vengono calcolate, quindi non c'è alcuna tabella delle festività da aggiornare. Per il periodo 1980-2027 i risultati coincidono giorno per giorno con l'elenco delle festività nazionali dell'Ufficio di Gabinetto giapponese. Nessuna DLL, nessuna richiesta web, nessun file, nessuna funzione di trading.

A cosa risponde

• Le festività nazionali giapponesi, comprese le festività sostitutive e le «festività dei cittadini», con il nome inglese di ciascuna festività.
• I giorni di chiusura delle banche giapponesi: sabati, domeniche, festività nazionali e dal 31 dicembre al 3 gennaio. Tutti gli altri giorni sono lavorativi.
• I giorni gotobi: il 5, il 10, il 15, il 20, il 25 e l'ultimo giorno del mese. Se quel giorno le banche sono chiuse, il gotobi viene anticipato al giorno lavorativo precedente.
• L'ora del fixing di Tokyo: le 09:55, ora del Giappone.
• Conversione dell'ora del server del broker in ora del Giappone e viceversa. Il Giappone non ha l'ora legale (JST = UTC+9).

Funzioni

• JpIsBankHoliday(date) - true il sabato, la domenica, nelle festività nazionali e dal 31 dicembre al 3 gennaio.
• JpIsBusinessDay(date) - true nei giorni lavorativi delle banche di Tokyo.
• JpIsNationalHoliday(date) - true nelle festività nazionali, comprese quelle sostitutive e dei cittadini.
• JpHolidayName(date) - il nome inglese, ad esempio "Marine Day", "Substitute Holiday" o "Bank Holiday"; una stringa vuota negli altri giorni.
• JpIsGotobi(date) - true nei giorni gotobi.
• JpGotobiDaysOfMonth(year, month, days[]) - tutti i giorni gotobi di un mese; restituisce il loro numero.
• JpNextGotobi(date) / JpPrevGotobi(date) - il primo gotobi nella data o dopo / l'ultimo gotobi nella data o prima.
• JpTokyoFixing(date) - le 09:55, ora del Giappone, di quel giorno.
• JpNowJst() - l'ora attuale in Giappone.
• JpServerToJst(time) / JpJstToServer(time) - converte tra l'ora del server e l'ora del Giappone.
• JpServerGmtOffsetSeconds() - lo scostamento del server da GMT in secondi (automatico: TimeCurrent() - TimeGMT(), arrotondato a 15 minuti).
• JpSetServerGmtOffset(seconds) - uno scostamento fisso, ad esempio 7200 per GMT+2.
• JpSetServerTimeZone(seconds, rule) - lo scostamento fuori dall'ora legale e una regola per l'ora legale: 0 nessuna, 1 USA, 2 UE.
• JpSetServerGmtOffsetAuto() - torna allo scostamento automatico (predefinito).
• JpLibraryVersion() - la versione, "1.00".

Gli argomenti data sono in ora del Giappone; si può passare qualsiasi ora del giorno. Le date di festività e gotobi vengono restituite alle 00:00, ora del Giappone.

Come si usa

Il Market installa la libreria come MQL4\Libraries\Market\Japan Bank Holiday and Gotobi Library MT4.ex4. Incolla questo blocco di importazione all'inizio del tuo programma (oppure salvalo come MQL4\Include\JpMarketCalendar.mqh e includi quel file):

#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

Esempio per un Expert Advisor:

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

Regole utilizzate

• Legge giapponese sulle festività nazionali e sue modifiche: date fisse, festività di lunedì (Giorno della maggiore età e Giorno della salute e dello sport dal 2000, Giorno del mare e Giorno del rispetto per gli anziani dal 2003), Giorno della montagna dal 2016, il compleanno dell'Imperatore secondo l'era e i giorni spostati del 2020 e del 2021.
• Festività sostitutiva: quando una festività nazionale cade di domenica, è festivo il primo giorno successivo che non sia festività nazionale (dal 2007; prima, solo il giorno dopo).
• Festività dei cittadini: un giorno compreso tra due festività nazionali (dal 1986), ad esempio il 22 settembre 2026.
• Festività una tantum: 1989-02-24, 1990-11-12, 1993-06-09, 2019-05-01 e 2019-10-22.
• Equinozi: la formula di approssimazione standard, valida per il periodo 1980-2099. Fornisce la data ufficiale in ogni anno fino al 2027 e concorda con un calcolo astronomico in ogni anno fino al 2099. Il governo annuncia ogni data nel febbraio dell'anno precedente.
• Chiusura delle banche: sabati, domeniche, festività nazionali e dal 31 dicembre al 3 gennaio (legge bancaria; la regola attuale è applicata a tutti gli anni).
• Gotobi: se le banche sono chiuse, il giorno viene anticipato al giorno lavorativo precedente dello stesso mese. Se il giorno 5 dovesse finire nel mese precedente (ad esempio a maggio 2027), quel giorno lavorativo è già il gotobi di fine mese del mese precedente e compare solo lì.

Cose da sapere

• Anni validi: 1980-2099. Al di fuori di questo intervallo le funzioni restituiscono false, 0, una stringa vuota o -1.
• Strategy Tester: qui TimeGMT() restituisce l'ora del server, quindi lo scostamento automatico è 0. Chiama JpSetServerGmtOffset() o JpSetServerTimeZone() in OnInit(), come nell'esempio. Se nel tester si usa lo scostamento automatico, la libreria scrive un promemoria una sola volta nel suo giornale.
• MT4 non ha TimeTradeServer(), quindi lo scostamento automatico usa TimeCurrent(), l'ora dell'ultima quotazione. È corretto finché arrivano quotazioni; subito dopo l'avvio del terminale o a mercato chiuso può essere errato (i valori fuori da -12 a +14 ore vengono ignorati). In MT4 la scelta più sicura è impostare lo scostamento con JpSetServerTimeZone().
• Lo scostamento automatico è quello attuale. Per convertire barre passate attraverso un cambio dell'ora legale, imposta la regola del server con JpSetServerTimeZone().
• Le impostazioni valgono per il programma che le chiama: chiamale in OnInit() di ogni Expert Advisor o indicatore.
• JpGotobiDaysOfMonth() richiede un array dinamico: datetime days[];
• I risultati sono memorizzati in cache per anno; una chiamata ripetuta nello stesso anno richiede circa 0,1 microsecondi.

Supporto

Se qualcosa non è chiaro, inviami un messaggio privato su MQL5.