Japan Bank Holiday and Gotobi Library

Japan Bank Holiday and Gotobi Library 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: TimeTradeServer() - 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 MQL5\Libraries\Market\Japan Bank Holiday and Gotobi Library.ex5. Cole este bloco de importação no início do seu programa (ou salve-o como MQL5\Include\JpMarketCalendar.mqh e inclua esse arquivo):

#import "Market\\Japan Bank Holiday and Gotobi Library.ex5"
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 deslocamento automático precisa de um terminal sincronizado com o servidor de negociação. Logo após o terminal iniciar, ele pode valer 0 por alguns segundos; é lido novamente a cada chamada.
• 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,01 microssegundo.

Suporte

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