Japan Bank Holiday and Gotobi Library (MT5/MT4): Manual do usuário, funções e exemplos
Japan Bank Holiday and Gotobi Library é uma biblioteca gratuita para MetaTrader 5 e MetaTrader 4. Ela responde às perguntas de calendário do mercado do iene dentro do seu próprio Expert Advisor, indicador ou script. Este manual é para desenvolvedores e vale para a versão 1.00 nas duas plataformas.
O que ela responde
- Os feriados nacionais japoneses, incluindo os feriados substitutos, os feriados dos cidadãos e os feriados únicos, com o nome em inglês de cada um.
- Os feriados bancários japoneses: sábados, domingos, feriados nacionais e de 31 de dezembro a 3 de janeiro. Todos os outros dias são dias úteis em Tóquio.
- Os dias gotobi: os dias 5, 10, 15, 20, 25 e o último dia do mês. Em um feriado bancário, o gotobi passa para o dia útil anterior do mesmo mês.
- O horário do fixing de Tóquio, 09:55, horário do Japão, e a conversão do horário do servidor para o horário do Japão e vice-versa. O Japão não tem horário de verão (JST = UTC+9).
Anos de 1980 a 2099. As regras são calculadas, portanto não há tabela de feriados para atualizar. Sem DLL, sem requisições web, sem arquivos, sem funções de negociação.
Instalação
- Na página do produto, clique no botão de download gratuito (Free Download; isso abre o MetaTrader) ou encontre-a em Toolbox > Market (no MT4 essa janela se chama Terminal). MT5 e MT4 são produtos separados.
- O Market instala a biblioteca como 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 mostra essas pastas.
- Os produtos instalados e as atualizações deles ficam em Toolbox > Market > Purchased.
- Uma biblioteca não é colocada em um gráfico. O seu próprio programa a carrega pelo bloco de importação.
Como importar
Salve o arquivo de cabeçalho da sua plataforma na pasta Include e adicione uma linha no início do seu programa:
- JpMarketCalendar_Market.mqh (MT5): salve-o em MQL5\Include.
- JpMarketCalendar_Market_MT4.mqh (MT4): salve-o em MQL4\Include.
#include <JpMarketCalendar_Market.mqh> // MT5 #include <JpMarketCalendar_Market_MT4.mqh> // MT4
Cada cabeçalho importa as 17 funções e define as regras de horário de verão JP_DST_NONE (0), JP_DST_US (1) e JP_DST_EU (2). Se você mesmo colar o bloco de importação, a primeira linha dele precisa corresponder exatamente ao arquivo instalado (com duas barras invertidas): #import "Market\\Japan Bank Holiday and Gotobi Library.ex5" (MT5) ou #import "Market\\Japan Bank Holiday and Gotobi Library MT4.ex4" (MT4).
Dois programas para começar, ambos sem ordens:
- JpCalendarDemo.mq5 / JpCalendarDemo_MT4.mq4: um script que imprime o horário do servidor e o do Japão, os próximos fixings e os feriados e dias gotobi dos anos que você escolher. Se ele os imprimir, a biblioteca está instalada e importada corretamente.
- JpCalendarExample.mq5 / JpCalendarExample_MT4.mq4: um Expert Advisor que mostra com Comment() o horário do fixing gotobi, o nome do feriado ou o próximo gotobi.
Os seis arquivos compilam com 0 erros e 0 avisos. Abaixo está a saída do script de demonstração em um servidor demo do MT5; a versão MT4 imprime as mesmas linhas.
Referência das funções
| Função | Retorno | Observações |
|---|---|---|
| JpIsBankHoliday(datetime date_jst) | bool | true aos sábados, domingos, feriados nacionais e de 31 de dezembro a 3 de janeiro. |
| JpIsBusinessDay(datetime date_jst) | bool | true nos dias úteis de Tóquio. Fora de 1980-2099, esta função e JpIsBankHoliday() retornam false. |
| JpIsNationalHoliday(datetime date_jst) | bool | true nos feriados nacionais, incluindo os substitutos, os dos cidadãos e os únicos. |
| JpHolidayName(datetime date_jst) | string | O nome em inglês, por exemplo "Marine Day"; "Bank Holiday" em 31 de dezembro, 2 de janeiro e 3 de janeiro, a menos que sejam feriados nacionais; "" nos demais dias, inclusive nos fins de semana comuns. |
| JpIsGotobi(datetime date_jst) | bool | true nos dias gotobi, que são sempre dias úteis. |
| JpGotobiDaysOfMonth(int year, int month, datetime &out[]) | int | Preenche um array dinâmico com os dias gotobi do mês (00:00 JST, do mais antigo para o mais recente) e retorna a quantidade; -1 para um array estático, um ano fora de 1980-2099 ou um mês fora de 1-12. |
| JpNextGotobi(datetime from_jst) | datetime | O primeiro gotobi na data ou depois dela (00:00 JST). O próprio dia conta, mesmo depois das 09:55. 0 se não houver. |
| JpPrevGotobi(datetime from_jst) | datetime | O último gotobi na data ou antes dela (00:00 JST). 0 se não houver. |
| JpTokyoFixing(datetime date_jst) | datetime | 09:55 JST daquele dia, para qualquer dia; o fixing só é publicado em dias úteis. |
| JpNowJst() | datetime | O horário atual do Japão (a partir do horário do servidor; veja abaixo). |
| JpServerToJst(datetime server_time) | datetime | Horário do servidor para horário do Japão, com o deslocamento em uso. 0 para um horário inválido. |
| JpJstToServer(datetime jst) | datetime | Horário do Japão para horário do servidor. 0 para um horário inválido. |
| JpServerGmtOffsetSeconds() | int | O deslocamento GMT atual do servidor, em segundos. |
| JpSetServerGmtOffset(int seconds) | bool | Um único deslocamento para o ano todo, por exemplo 7200 para GMT+2. |
| JpSetServerTimeZone(int standard_offset_seconds, int dst_rule) | bool | O deslocamento fora do horário de verão e a regra: 0 nenhuma, 1 EUA, 2 UE (+1 hora no horário de verão). |
| JpSetServerGmtOffsetAuto() | void | Volta ao deslocamento automático (o padrão). |
| JpLibraryVersion() | string | "1.00" |
Os argumentos de data estão no horário do Japão; qualquer hora do dia pode ser passada. Fora de 1980-2099, as funções retornam false, 0, "" ou -1. As duas funções de configuração aceitam um múltiplo de 900 segundos de -43200 a 50400; para qualquer outro valor, elas imprimem o motivo, retornam false e mantêm a configuração anterior.
Exemplos
Hoje no Japão:
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"); O próximo fixing gotobi que ainda não passou:
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"); Os dias gotobi de um mês:
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));
Fusos horários e o Strategy Tester
- O horário do servidor não é o horário do Japão: na demonstração acima, o servidor mostra 21:43 de 13 de outubro, enquanto no Japão já são 03:43 de 14 de outubro. Converta com JpServerToJst() antes de perguntar sobre um dia, ou use JpNowJst().
- O deslocamento padrão é automático: TimeTradeServer() - TimeGMT() no MT5, arredondado a 15 minutos e lido novamente a cada chamada. Logo após o terminal iniciar, ele pode valer 0 por alguns segundos.
- O MT4 não tem TimeTradeServer() e usa TimeCurrent(), o horário da última cotação, que pode estar errado logo após a inicialização ou enquanto o mercado está fechado. No MT4, defina você mesmo o deslocamento.
- No Strategy Tester, TimeGMT() retorna o horário do servidor, então o deslocamento automático é 0. A biblioteca escreve um aviso no diário do testador. Defina o deslocamento em OnInit().
- O deslocamento automático é o deslocamento de hoje. Para barras passadas que atravessam 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.
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);
} Regra dos EUA: do segundo domingo de março ao primeiro domingo de novembro (antes de 2007, valiam outras datas nos EUA). Regra da UE: do último domingo de março ao último domingo de outubro (setembro antes de 1996). Um servidor em GMT+2 no inverno e em GMT+3 no horário de verão dos EUA é 7200 com a regra 1. O script de demonstração mostra o deslocamento atual do seu servidor; a sua corretora pode dizer qual horário de verão ela segue. Para manter o deslocamento automático ao vivo no MT5, chame a função de configuração somente quando MQLInfoInteger(MQL_TESTER) for true, como faz o EA de exemplo.
Regras usadas e como foram conferidas
- Lei dos Feriados Nacionais, 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 em um domingo, o próximo dia que não seja feriado nacional é feriado (desde 2007; antes disso, 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. 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 5 tivesse de passar para o mês anterior, esse dia já é o gotobi de fim de mês do mês anterior e aparece apenas lá. Por isso, maio de 2027 tem 5 dias gotobi.
- Estas são as regras em vigor quando a versão 1.00 foi feita (outubro de 2026).
Verificações antes do lançamento: as duas versões compilam com 0 erros e 0 avisos; a versão MT4 é feita a partir do mesmo código-fonte (só a função de horário é diferente). Todos os 789 feriados nacionais de 1980 a 2027 coincidem, dia a dia, com a lista do Gabinete do Japão; atualmente essa lista termina em 2027. A fórmula do equinócio dá a data oficial em todos os anos até 2027 e concorda com um cálculo astronômico em todos os anos até 2099. A importação pelo caminho do Market também carrega no Strategy Tester.
Perguntas frequentes dos desenvolvedores
- Meu programa para com um erro sobre a biblioteca. Verifique se a biblioteca está instalada e se a linha #import corresponde exatamente ao nome do arquivo. O nome do arquivo do MT4 termina com MT4.
- A data japonesa fica um dia errada à noite. Você passou o horário do servidor. Converta-o primeiro com JpServerToJst().
- JpGotobiDaysOfMonth() retorna -1. Passe um array dinâmico ( datetime days[]; ), um ano de 1980 a 2099 e um mês de 1 a 12.
- Ela é rápida o suficiente para OnTick()? Sim. Os resultados ficam em cache por ano. O cache guarda 2 anos, então um loop que salta entre muitos anos fica mais lento.
Páginas dos produtos: Japan Bank Holiday and Gotobi Library (MT5) e Japan Bank Holiday and Gotobi Library MT4. Se algo não estiver claro, envie-me uma mensagem privada no MQL5 com o código que você usa e as últimas linhas da aba Experts.
