Japan Bank Holiday and Gotobi Library MT4

Japan Bank Holiday and Gotobi Library MT4 responde às perguntas de calendário do mercado do iene dentro do seu próprio Expert Advisor, indicador ou script: se hoje é feriado bancário no Japão, se é um dia gotobi, quando é o próximo fixing de Tóquio e que horas são no Japão segundo o servidor da sua corretora.

Todas as regras são calculadas, portanto não há tabela de feriados para atualizar. De 1980 a 2027 os resultados coincidem, dia a dia, com a lista de feriados nacionais do Gabinete do Japão. Sem DLL, sem requisições web, sem arquivos e sem funções de negociação.

O que ela responde

• Os feriados nacionais do Japão, incluindo feriados substitutos e «feriados dos cidadãos», com o nome em inglês de cada feriado.
• Os feriados bancários do Japão: sábados, domingos, feriados nacionais e de 31 de dezembro a 3 de janeiro. Todos os outros dias são dias úteis.
• Os dias gotobi: os dias 5, 10, 15, 20, 25 e o último dia do mês. Quando esse dia é feriado bancário, o gotobi passa para o dia útil anterior.
• O horário do fixing de Tóquio: 09:55, horário do Japão.
• Horário do servidor da corretora para o horário do Japão e vice-versa. O Japão não tem horário de verão (JST = UTC+9).

Funções

• JpIsBankHoliday(date) - true aos sábados, domingos, feriados nacionais e de 31 de dezembro a 3 de janeiro.
• JpIsBusinessDay(date) - true nos dias úteis dos bancos de Tóquio.
• JpIsNationalHoliday(date) - true nos feriados nacionais, incluindo os substitutos e os dos cidadãos.
• JpHolidayName(date) - o nome em inglês, por exemplo "Marine Day", "Substitute Holiday" ou "Bank Holiday"; uma string vazia nos demais dias.
• JpIsGotobi(date) - true nos dias gotobi.
• JpGotobiDaysOfMonth(year, month, days[]) - todos os dias gotobi de um mês; retorna a quantidade.
• JpNextGotobi(date) / JpPrevGotobi(date) - o primeiro gotobi na data ou depois / o último gotobi na data ou antes.
• JpTokyoFixing(date) - 09:55, horário do Japão, daquele dia.
• JpNowJst() - o horário atual do Japão.
• JpServerToJst(time) / JpJstToServer(time) - converte entre o horário do servidor e o horário do Japão.
• JpServerGmtOffsetSeconds() - o deslocamento do servidor em relação ao GMT, em segundos (automático: TimeCurrent() - TimeGMT(), arredondado a 15 minutos).
• JpSetServerGmtOffset(seconds) - um deslocamento fixo, por exemplo 7200 para GMT+2.
• JpSetServerTimeZone(seconds, rule) - o deslocamento fora do horário de verão e uma regra de horário de verão: 0 nenhuma, 1 EUA, 2 UE.
• JpSetServerGmtOffsetAuto() - volta ao deslocamento automático (padrão).
• JpLibraryVersion() - a versão, "1.00".

Os argumentos de data estão no horário do Japão; qualquer hora do dia pode ser passada. As datas de feriados e de gotobi são retornadas como 00:00, horário do Japão.

Como usar

O Market instala a biblioteca como MQL4\Libraries\Market\Japan Bank Holiday and Gotobi Library MT4.ex4. Cole este bloco de importação no início do seu programa (ou salve-o como MQL4\Include\JpMarketCalendar.mqh e inclua esse arquivo):

#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

Exemplo para um 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));
  }

Regras utilizadas

• Lei dos Feriados Nacionais do Japão, com as alterações: datas fixas, feriados às segundas-feiras (Dia da Maioridade e Dia da Saúde e do Esporte desde 2000, Dia do Mar e Dia do Respeito aos Idosos desde 2003), Dia da Montanha desde 2016, o Aniversário do Imperador conforme a era e os dias transferidos de 2020 e 2021.
• Feriado substituto: quando um feriado nacional cai num domingo, é feriado o próximo dia que não seja feriado nacional (desde 2007; antes, apenas o dia seguinte).
• Feriado dos cidadãos: um dia entre dois feriados nacionais (desde 1986), por exemplo 22 de setembro de 2026.
• Feriados únicos: 1989-02-24, 1990-11-12, 1993-06-09, 2019-05-01 e 2019-10-22.
• Dias de equinócio: a fórmula de aproximação padrão, válida para 1980-2099. Ela dá a data oficial em todos os anos até 2027 e concorda com um cálculo astronômico em todos os anos até 2099. O governo anuncia cada dia de equinócio em fevereiro do ano anterior.
• Feriados bancários: sábados, domingos, feriados nacionais e de 31 de dezembro a 3 de janeiro (Lei Bancária; a regra atual é aplicada a todos os anos).
• Gotobi: se o dia for feriado bancário, passa para o dia útil anterior do mesmo mês. Se o dia 5 tivesse de passar para o mês anterior (por exemplo, em maio de 2027), esse dia útil já é o gotobi de fim do mês anterior e aparece apenas lá.

O que é bom saber

• Anos válidos: 1980-2099. Fora desse intervalo as funções retornam false, 0, uma string vazia ou -1.
• Testador de estratégias: nele TimeGMT() retorna o horário do servidor, então o deslocamento automático é 0. Chame JpSetServerGmtOffset() ou JpSetServerTimeZone() em OnInit(), como no exemplo. Se o deslocamento automático for usado no testador, a biblioteca escreve um aviso uma vez no diário dele.
• O MT4 não tem TimeTradeServer(), por isso o deslocamento automático usa TimeCurrent(), o horário da última cotação. Ele está certo enquanto chegam cotações; logo após o terminal iniciar ou com o mercado fechado pode estar errado (valores fora de -12 a +14 horas são ignorados). No MT4, o mais seguro é definir o deslocamento com JpSetServerTimeZone().
• O deslocamento automático é o deslocamento atual. Para converter barras passadas através de uma mudança de horário de verão, defina a regra do servidor com JpSetServerTimeZone().
• As configurações valem para o programa que as chama: chame-as em OnInit() de cada Expert Advisor ou indicador.
• JpGotobiDaysOfMonth() precisa de um array dinâmico: datetime days[];
• Os resultados ficam em cache por ano; uma chamada repetida dentro do mesmo ano leva cerca de 0,1 microssegundo.

Suporte

Se algo não estiver claro, envie-me uma mensagem privada no MQL5.