Japan Bank Holiday and Gotobi Library (MT5/MT4): Manual de usuario, funciones y ejemplos

Japan Bank Holiday and Gotobi Library es una biblioteca gratuita para MetaTrader 5 y MetaTrader 4. Responde a las preguntas de calendario del mercado del yen dentro de su propio asesor experto, indicador o script. Este manual está dirigido a desarrolladores y corresponde a la versión 1.00 en ambas plataformas.

Qué responde

• Los festivos nacionales japoneses, incluidos los festivos sustitutos, los festivos de los ciudadanos y los festivos únicos, con el nombre en inglés de cada uno.
• Los festivos bancarios japoneses: sábados, domingos, festivos nacionales y del 31 de diciembre al 3 de enero. Todos los demás días son días hábiles en Tokio.
• Los días gotobi: el 5, 10, 15, 20, 25 y el último día del mes. Si cae en un festivo bancario, el gotobi pasa al día hábil anterior del mismo mes.
• La hora del fixing de Tokio, las 09:55, hora de Japón, y la conversión de la hora del servidor a la hora de Japón y viceversa. Japón no tiene horario de verano (JST = UTC+9).

Años de 1980 a 2099. Las reglas se calculan, así que no hay ninguna tabla de festivos que actualizar. Sin DLL, sin solicitudes web, sin archivos, sin funciones de trading.

Instalación

1. En la página del producto, haga clic en el botón de descarga gratuita (Free Download), que abre MetaTrader, o búsquela en Toolbox > Market (en MT4 esta ventana se llama Terminal). MT5 y MT4 son productos distintos.
2. El Market instala la biblioteca como 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 muestra estas carpetas.
3. Los productos instalados y sus actualizaciones están en Toolbox > Market > Purchased.
4. Una biblioteca no se coloca en un gráfico. Su propio programa la carga mediante el bloque de importación.

Cómo importarla

Guarde el archivo de cabecera de su plataforma en la carpeta Include y añada una línea al principio de su programa:

• JpMarketCalendar_Market.mqh (MT5): guárdelo en MQL5\Include.
• JpMarketCalendar_Market_MT4.mqh (MT4): guárdelo en MQL4\Include.

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

Cada archivo de cabecera importa las 17 funciones y define las reglas de horario de verano JP_DST_NONE (0), JP_DST_US (1) y JP_DST_EU (2). Si pega usted mismo el bloque de importación, su primera línea debe coincidir exactamente con el archivo instalado (dos barras invertidas): #import "Market\\Japan Bank Holiday and Gotobi Library.ex5" (MT5) o #import "Market\\Japan Bank Holiday and Gotobi Library MT4.ex4" (MT4).

Dos programas para empezar, ninguno de los cuales envía órdenes:

• JpCalendarDemo.mq5 / JpCalendarDemo_MT4.mq4: un script que imprime la hora del servidor y la de Japón, los próximos fixings, y los festivos y los días gotobi de los años que elija. Si los imprime, la biblioteca está instalada e importada correctamente.
• JpCalendarExample.mq5 / JpCalendarExample_MT4.mq4: un asesor experto que muestra con Comment() la hora del fixing gotobi, el nombre del festivo o el próximo gotobi.

Los seis archivos se compilan con 0 errores y 0 advertencias. Abajo se muestra la salida del script de demostración en un servidor demo de MT5; la versión MT4 imprime las mismas líneas.

Referencia de funciones

Los argumentos de fecha están en hora de Japón; se puede pasar cualquier hora del día. Fuera de 1980-2099, las funciones devuelven false, 0, "" o -1. Las dos funciones de configuración aceptan un múltiplo de 900 segundos de -43200 a 50400; con cualquier otro valor imprimen el motivo, devuelven false y mantienen el ajuste anterior.

Ejemplos

Hoy en Japón:

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

El próximo fixing gotobi que todavía no ha pasado:

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

Los días gotobi de un mes:

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

Zonas horarias y el Strategy Tester

• La hora del servidor no es la hora de Japón: en la demostración de arriba, el servidor muestra las 21:43 del 13 de octubre mientras que en Japón son las 03:43 del 14 de octubre. Convierta con JpServerToJst() antes de preguntar por un día, o use JpNowJst().
• El desfase por defecto es automático: TimeTradeServer() - TimeGMT() en MT5, redondeado a 15 minutos y leído de nuevo en cada llamada. Justo después de iniciarse el terminal, puede valer 0 durante unos segundos.
• MT4 no tiene TimeTradeServer() y usa TimeCurrent(), la hora de la última cotización, que puede ser incorrecta justo después del inicio o mientras el mercado está cerrado. En MT4, fije usted mismo el desfase.
• En el Strategy Tester, TimeGMT() devuelve la hora del servidor, así que el desfase automático es 0. La biblioteca escribe un aviso en el diario del Strategy Tester. Fije el desfase en OnInit().
• El desfase automático es el desfase de hoy. Para barras pasadas que cruzan un cambio de horario de verano, configure la regla del servidor con JpSetServerTimeZone().
• Los ajustes se aplican al programa que los llama: llámelos en OnInit() de cada asesor experto o 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);
  }

Regla de EE. UU.: del segundo domingo de marzo al primer domingo de noviembre (antes de 2007 regían otras fechas en EE. UU.). Regla de la UE: del último domingo de marzo al último domingo de octubre (septiembre antes de 1996). Un servidor en GMT+2 en invierno y GMT+3 en el horario de verano de EE. UU. es 7200 con la regla 1. El script de demostración muestra el desfase actual de su servidor; su bróker puede decirle qué horario de verano sigue. Para mantener el desfase automático en tiempo real en MT5, llame a la función de configuración solo cuando MQLInfoInteger(MQL_TESTER) sea true, como hace el EA de ejemplo.

Reglas utilizadas y cómo se comprobaron

• Ley de Festivos Nacionales con sus reformas: fechas fijas, festivos en lunes (el Día de la Mayoría de Edad y el Día de la Salud y el Deporte desde 2000, el Día del Mar y el Día del Respeto a los Mayores desde 2003), el Día de la Montaña desde 2016, el Cumpleaños del Emperador según la era y los días trasladados de 2020 y 2021.
• Festivo sustituto: cuando un festivo nacional cae en domingo, el siguiente día que no sea festivo nacional es festivo (desde 2007; antes, solo el día siguiente).
• Festivo de los ciudadanos: un día entre dos festivos nacionales (desde 1986), por ejemplo el 22 de septiembre de 2026.
• Festivos únicos: 1989-02-24, 1990-11-12, 1993-06-09, 2019-05-01 y 2019-10-22.
• Días de equinoccio: la fórmula de aproximación estándar, válida para 1980-2099. El Gobierno anuncia cada día de equinoccio en febrero del año anterior.
• Festivos bancarios: sábados, domingos, festivos nacionales y del 31 de diciembre al 3 de enero (Ley de Bancos); la regla actual se aplica a todos los años.
• Gotobi: si el día 5 tuviera que pasar al mes anterior, ese día ya es el gotobi de fin de mes del mes anterior y solo figura allí. Por eso mayo de 2027 tiene 5 días gotobi.
• Son las reglas vigentes cuando se creó la versión 1.00 (octubre de 2026).

Comprobaciones antes de la publicación: ambas versiones se compilan con 0 errores y 0 advertencias; la versión MT4 se genera a partir del mismo código fuente (solo cambia la función de hora). Los 789 festivos nacionales de 1980 a 2027 coinciden día a día con la lista de la Oficina del Gabinete; esa lista termina actualmente en 2027. La fórmula del equinoccio da la fecha oficial en todos los años hasta 2027 y coincide con un cálculo astronómico en todos los años hasta 2099. La importación desde la ruta del Market también se carga en el Strategy Tester.

Preguntas que hacen los desarrolladores

• Mi programa se detiene con un error sobre la biblioteca. Compruebe que la biblioteca está instalada y que la línea #import coincide exactamente con el nombre del archivo. El nombre del archivo de MT4 termina en MT4.
• Por la noche, la fecha japonesa tiene un día de diferencia. Ha pasado la hora del servidor. Conviértala primero con JpServerToJst().
• JpGotobiDaysOfMonth() devuelve -1. Pase un array dinámico ( datetime days[]; ), un año de 1980 a 2099 y un mes de 1 a 12.
• ¿Es lo bastante rápida para OnTick()? Sí. Los resultados se guardan en caché por año. La caché conserva 2 años, así que un bucle que salta entre muchos años es más lento.

Páginas del producto: Japan Bank Holiday and Gotobi Library (MT5) y Japan Bank Holiday and Gotobi Library MT4. Si algo no queda claro, envíeme un mensaje privado en MQL5 con el código que usa y las últimas líneas de la pestaña Experts.