Japan Bank Holiday and Gotobi Library (MT5/MT4): manuale utente, funzioni ed esempi

Japan Bank Holiday and Gotobi Library è una libreria gratuita per MetaTrader 5 e MetaTrader 4. Risponde alle domande di calendario del mercato dello yen direttamente nel tuo Expert Advisor, indicatore o script. Questo manuale è per gli sviluppatori e vale per la versione 1.00 su entrambe le piattaforme.

A cosa risponde

• Le festività nazionali giapponesi, comprese le festività sostitutive, le festività dei cittadini e quelle una tantum, con il nome inglese di ciascuna.
• I giorni di chiusura delle banche giapponesi: sabati, domeniche, festività nazionali e dal 31 dicembre al 3 gennaio. Tutti gli altri giorni sono giorni lavorativi a Tokyo.
• 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 dello stesso mese.
• L'ora del fixing di Tokyo, le 09:55 ora del Giappone, e la conversione dall'ora del server all'ora del Giappone e viceversa. Il Giappone non ha l'ora legale (JST = UTC+9).

Anni dal 1980 al 2099. Le regole vengono calcolate, quindi non c'è alcuna tabella delle festività da aggiornare. Nessuna DLL, nessuna richiesta web, nessun file, nessuna funzione di trading.

Installazione

1. Nella pagina del prodotto fai clic su Free Download (si apre MetaTrader), oppure cercala in Toolbox > Market (in MT4 questa finestra si chiama Terminal). MT5 e MT4 sono prodotti separati.
2. Il Market installa la libreria come MQL5\Libraries\Market\Japan Bank Holiday and Gotobi Library.ex5 (MT5) o MQL4\Libraries\Market\Japan Bank Holiday and Gotobi Library MT4.ex4 (MT4). File > Open Data Folder mostra queste cartelle.
3. I prodotti installati e i loro aggiornamenti si trovano in Toolbox > Market > Purchased.
4. Una libreria non si applica a un grafico. È il tuo programma a caricarla tramite il blocco di importazione.

Come importarla

Salva il file header della tua piattaforma nella cartella Include e aggiungi una riga all'inizio del tuo programma:

• JpMarketCalendar_Market.mqh (MT5): salvalo in MQL5\Include.
• JpMarketCalendar_Market_MT4.mqh (MT4): salvalo in MQL4\Include.

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

Ogni header importa tutte le 17 funzioni e definisce le regole dell'ora legale JP_DST_NONE (0), JP_DST_US (1) e JP_DST_EU (2). Se incolli tu stesso il blocco di importazione, la sua prima riga deve corrispondere esattamente al file installato (due backslash): #import "Market\\Japan Bank Holiday and Gotobi Library.ex5" (MT5) o #import "Market\\Japan Bank Holiday and Gotobi Library MT4.ex4" (MT4).

Due programmi per iniziare, entrambi senza ordini:

• JpCalendarDemo.mq5 / JpCalendarDemo_MT4.mq4: uno script che stampa l'ora del server e del Giappone, i prossimi fixing e le festività e i giorni gotobi degli anni che scegli. Se li stampa, la libreria è installata e importata correttamente.
• JpCalendarExample.mq5 / JpCalendarExample_MT4.mq4: un Expert Advisor che mostra con Comment() l'ora del fixing gotobi, il nome della festività o il prossimo gotobi.

Tutti e sei i file vengono compilati con 0 errori e 0 avvisi. Qui sotto c'è l'output dello script demo su un server demo MT5; la versione MT4 stampa le stesse righe.

Riferimento delle funzioni

Gli argomenti data sono in ora del Giappone; si può passare qualsiasi ora del giorno. Fuori dal periodo 1980-2099 le funzioni restituiscono false, 0, "" o -1. Le due funzioni di impostazione accettano un multiplo di 900 secondi da -43200 a 50400; per qualsiasi altro valore stampano il motivo, restituiscono false e mantengono l'impostazione precedente.

Esempi

Oggi in Giappone:

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

Il prossimo fixing gotobi non ancora passato:

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

I giorni gotobi di un mese:

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

Fusi orari e Strategy Tester

• L'ora del server non è l'ora del Giappone: nella demo qui sopra il server mostra le 21:43 del 13 ottobre, mentre in Giappone sono le 03:43 del 14 ottobre. Converti con JpServerToJst() prima di interrogare la libreria su un giorno, oppure usa JpNowJst().
• L'offset predefinito è automatico: TimeTradeServer() - TimeGMT() su MT5, arrotondato a 15 minuti e riletto a ogni chiamata. Subito dopo l'avvio del terminale può valere 0 per qualche secondo.
• MT4 non ha TimeTradeServer() e usa TimeCurrent(), l'ora dell'ultima quotazione, che può essere errata dopo l'avvio o a mercato chiuso. Su MT4 imposta tu l'offset.
• Nello Strategy Tester TimeGMT() restituisce l'ora del server, quindi l'offset automatico è 0. La libreria scrive un solo promemoria nel giornale del tester. Imposta l'offset in OnInit().
• L'offset automatico è quello di oggi. Per le barre passate a cavallo di 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.

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

Regola USA: dalla seconda domenica di marzo alla prima domenica di novembre (prima del 2007 valgono le date USA precedenti). Regola UE: dall'ultima domenica di marzo all'ultima domenica di ottobre (settembre prima del 1996). Un server a GMT+2 in inverno e a GMT+3 durante l'ora legale USA corrisponde a 7200 con la regola 1. Lo script demo mostra l'offset attuale del tuo server; il tuo broker può dirti quale ora legale segue. Per mantenere attivo l'offset automatico su MT5, chiama la funzione di impostazione solo quando MQLInfoInteger(MQL_TESTER) è true, come fa l'EA di esempio.

Regole utilizzate e come sono state verificate

• Legge 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, il primo giorno successivo che non è una festività nazionale è festivo (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. Il governo annuncia ogni giorno di equinozio 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 il 5 dovesse spostarsi nel mese precedente, quel giorno è già il gotobi di fine mese del mese precedente e compare solo lì. Per questo maggio 2027 ha 5 giorni gotobi.
• Sono le regole in vigore quando è stata realizzata la versione 1.00 (ottobre 2026).

Verifiche prima del rilascio: entrambe le versioni vengono compilate con 0 errori e 0 avvisi; la versione MT4 è ricavata dallo stesso sorgente (cambia solo la funzione dell'ora). Tutte le 789 festività nazionali dal 1980 al 2027 coincidono giorno per giorno con l'elenco dell'Ufficio di Gabinetto; quell'elenco al momento termina nel 2027. La formula degli equinozi fornisce la data ufficiale in ogni anno fino al 2027 e concorda con un calcolo astronomico in ogni anno fino al 2099. L'importazione dal percorso del Market si carica anche nello Strategy Tester.

Domande degli sviluppatori

• Il mio programma si ferma con un errore relativo alla libreria. Verifica che la libreria sia installata e che la riga #import corrisponda esattamente al nome del file. Il nome del file MT4 termina con MT4.
• La sera la data giapponese è sbagliata di un giorno. Hai passato l'ora del server. Convertila prima con JpServerToJst().
• JpGotobiDaysOfMonth() restituisce -1. Passa un array dinamico ( datetime days[]; ), un anno dal 1980 al 2099 e un mese da 1 a 12.
• È abbastanza veloce per OnTick()? Sì. I risultati sono memorizzati in cache per anno. La cache conserva 2 anni, quindi un ciclo che salta tra molti anni è più lento.

Pagine del prodotto: Japan Bank Holiday and Gotobi Library (MT5) e Japan Bank Holiday and Gotobi Library MT4. Se qualcosa non è chiaro, inviami un messaggio privato su MQL5 con il codice che usi e le ultime righe della scheda Experts.