Japan Bank Holiday and Gotobi Library는 MetaTrader 5와 MetaTrader 4용 무료 라이브러리입니다. 엔화 시장의 달력에 관한 질문에 사용자의 Expert Advisor, 인디케이터, 스크립트 안에서 답합니다. 이 설명서는 개발자를 위한 것이며, 두 플랫폼 모두 버전 1.00 기준입니다.
답할 수 있는 질문
- 일본의 국민 공휴일(대체 휴일, 국민의 휴일, 일회성 휴일 포함)과 각 공휴일의 영어 이름.
- 일본의 은행 휴일: 토요일, 일요일, 국민 공휴일, 12월 31일부터 1월 3일까지. 그 밖의 날은 모두 도쿄 영업일입니다.
- gotobi 일: 매월 5일, 10일, 15일, 20일, 25일과 말일. 은행 휴일과 겹치면 gotobi는 같은 달의 직전 영업일로 앞당겨집니다.
- 도쿄 픽싱 시각(일본 시간 09:55), 그리고 서버 시간과 일본 시간의 상호 변환. 일본에는 서머타임이 없습니다(JST = UTC+9).
대상 연도는 1980년부터 2099년까지입니다. 규칙을 계산으로 처리하므로 갱신해야 할 휴일 표가 없습니다. DLL, 웹 요청, 파일, 매매 함수를 사용하지 않습니다.
설치
- 상품 페이지에서 Free Download를 클릭하거나(MetaTrader가 열립니다), Toolbox > Market에서 찾습니다(MT4에서는 이 창의 이름이 Terminal입니다). MT5와 MT4는 별개의 상품입니다.
- Market은 라이브러리를 MQL5\Libraries\Market\Japan Bank Holiday and Gotobi Library.ex5(MT5) 또는 MQL4\Libraries\Market\Japan Bank Holiday and Gotobi Library MT4.ex4(MT4)로 설치합니다. File > Open Data Folder에서 이 폴더들을 볼 수 있습니다.
- 설치한 상품과 업데이트는 Toolbox > Market > Purchased에 있습니다.
- 라이브러리는 차트에 적용하지 않습니다. 사용자의 프로그램이 import 블록을 통해 불러옵니다.
불러오기(import)
사용하는 플랫폼용 헤더 파일을 Include 폴더에 저장하고, 프로그램 맨 앞에 다음 한 줄을 추가합니다.
- JpMarketCalendar_Market.mqh (MT5): MQL5\Include에 저장합니다.
- JpMarketCalendar_Market_MT4.mqh (MT4): MQL4\Include에 저장합니다.
#include <JpMarketCalendar_Market.mqh> // MT5 #include <JpMarketCalendar_Market_MT4.mqh> // MT4
각 헤더는 17개 함수를 모두 import하고, 서머타임 규칙 JP_DST_NONE (0), JP_DST_US (1), JP_DST_EU (2)를 정의합니다. import 블록을 직접 붙여 넣는 경우에는 첫 줄이 설치된 파일과 정확히 일치해야 합니다(백슬래시 두 개): #import "Market\\Japan Bank Holiday and Gotobi Library.ex5" (MT5) 또는 #import "Market\\Japan Bank Holiday and Gotobi Library MT4.ex4" (MT4).
처음 시작할 때 쓸 수 있는 프로그램 두 가지(둘 다 주문을 내지 않음):
- JpCalendarDemo.mq5 / JpCalendarDemo_MT4.mq4: 서버 시간과 일본 시간, 다음 픽싱들, 그리고 선택한 연도의 휴일과 gotobi 일을 출력하는 스크립트입니다. 이것들이 출력되면 라이브러리가 올바르게 설치되고 import된 것입니다.
- JpCalendarExample.mq5 / JpCalendarExample_MT4.mq4: gotobi의 픽싱 시각, 휴일 이름 또는 다음 gotobi를 Comment()로 표시하는 Expert Advisor입니다.
여섯 파일 모두 오류 0개, 경고 0개로 컴파일됩니다. 아래는 MT5 데모 서버에서 실행한 데모 스크립트의 출력이며, MT4 버전도 같은 줄을 출력합니다.
함수 레퍼런스
| 함수 | 반환값 | 설명 |
|---|---|---|
| JpIsBankHoliday(datetime date_jst) | bool | 토요일, 일요일, 국민 공휴일, 12월 31일부터 1월 3일까지는 true. |
| JpIsBusinessDay(datetime date_jst) | bool | 도쿄 영업일이면 true. 1980-2099 범위 밖에서는 이 함수와 JpIsBankHoliday()가 모두 false를 반환합니다. |
| JpIsNationalHoliday(datetime date_jst) | bool | 국민 공휴일(대체 휴일, 국민의 휴일, 일회성 휴일 포함)이면 true. |
| JpHolidayName(datetime date_jst) | string | 영어 이름(예: "Marine Day"). 12월 31일, 1월 2일, 1월 3일은 국민 공휴일이 아니면 "Bank Holiday". 그 밖의 날에는 ""이며, 공휴일이 아닌 보통 주말도 마찬가지입니다. |
| JpIsGotobi(datetime date_jst) | bool | gotobi 일이면 true. gotobi 일은 항상 영업일입니다. |
| JpGotobiDaysOfMonth(int year, int month, datetime &out[]) | int | 동적 배열에 그 달의 gotobi 일(JST 00:00, 오래된 순)을 채우고 개수를 반환합니다. 정적 배열이거나, 연도가 1980-2099 범위 밖이거나, 월이 1-12 범위 밖이면 -1. |
| JpNextGotobi(datetime from_jst) | datetime | 그 날짜 또는 그 이후의 첫 gotobi(JST 00:00). 그날 자체도 포함되며, 09:55 이후에도 마찬가지입니다. 없으면 0. |
| JpPrevGotobi(datetime from_jst) | datetime | 그 날짜 또는 그 이전의 마지막 gotobi(JST 00:00). 없으면 0. |
| JpTokyoFixing(datetime date_jst) | datetime | 그날의 JST 09:55. 어느 날이든 반환하지만, 픽싱은 영업일에만 공표됩니다. |
| JpNowJst() | datetime | 현재 일본 시간(서버 시간에서 구함. 아래 참조). |
| JpServerToJst(datetime server_time) | datetime | 사용 중인 오프셋으로 서버 시간을 일본 시간으로 변환합니다. 잘못된 시간이면 0. |
| JpJstToServer(datetime jst) | datetime | 일본 시간을 서버 시간으로 변환합니다. 잘못된 시간이면 0. |
| JpServerGmtOffsetSeconds() | int | 현재 서버의 GMT 오프셋(초). |
| JpSetServerGmtOffset(int seconds) | bool | 연중 하나의 오프셋을 지정합니다(예: GMT+2는 7200). |
| JpSetServerTimeZone(int standard_offset_seconds, int dst_rule) | bool | 서머타임이 아닐 때의 오프셋과 규칙: 0 없음, 1 미국, 2 유럽(서머타임 중 +1시간). |
| JpSetServerGmtOffsetAuto() | void | 자동 오프셋(기본값)으로 되돌립니다. |
| JpLibraryVersion() | string | "1.00" |
날짜 인수는 일본 시간이며, 그날의 어느 시각을 넘겨도 됩니다. 1980-2099 범위 밖에서는 함수가 false, 0, "" 또는 -1을 반환합니다. 두 설정 함수는 -43200부터 50400까지의 900초 배수를 받으며, 그 밖의 값이면 이유를 출력하고 false를 반환하며 이전 설정을 유지합니다.
예제
오늘 일본은 어떤 날인지:
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"); 아직 지나지 않은 다음 gotobi 픽싱:
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"); 한 달의 gotobi 일:
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));
시간대와 Strategy Tester
- 서버 시간은 일본 시간이 아닙니다. 위의 데모에서 서버는 10월 13일 21:43을 표시하지만, 일본은 10월 14일 03:43입니다. 날짜를 조회하기 전에 JpServerToJst()로 변환하거나 JpNowJst()를 사용하십시오.
- 기본 오프셋은 자동입니다. MT5에서는 TimeTradeServer() - TimeGMT()를 15분 단위로 반올림한 값이며, 호출할 때마다 다시 읽습니다. 터미널을 시작한 직후 몇 초 동안은 0으로 읽힐 수 있습니다.
- MT4에는 TimeTradeServer()가 없으므로 마지막 시세의 시각인 TimeCurrent()를 사용하는데, 이 값은 시작 직후나 시장이 닫혀 있는 동안 틀릴 수 있습니다. MT4에서는 오프셋을 직접 지정하십시오.
- Strategy Tester에서는 TimeGMT()가 서버 시간을 반환하므로 자동 오프셋이 0이 됩니다. 라이브러리는 테스터 저널에 안내를 한 번 기록합니다. OnInit()에서 오프셋을 지정하십시오.
- 자동 오프셋은 오늘의 오프셋입니다. 서머타임 전환을 넘는 과거 봉에는 JpSetServerTimeZone()으로 서버의 규칙을 지정하십시오.
- 설정은 그것을 호출한 프로그램에만 적용되므로, 각 Expert Advisor나 인디케이터의 OnInit()에서 호출하십시오.
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);
} 미국 규칙: 3월 둘째 일요일부터 11월 첫째 일요일까지(2007년 이전에는 미국의 예전 날짜). 유럽 규칙: 3월 마지막 일요일부터 10월 마지막 일요일까지(1996년 이전에는 9월). 겨울에 GMT+2, 미국 서머타임 중에 GMT+3인 서버는 7200과 규칙 1입니다. 데모 스크립트는 현재 서버의 오프셋을 보여 주며, 어떤 서머타임을 따르는지는 브로커에게 물어보면 알 수 있습니다. MT5에서 자동 오프셋을 실시간으로 유지하려면, 예제 EA처럼 MQLInfoInteger(MQL_TESTER) 가 true일 때만 설정 함수를 호출하십시오.
사용한 규칙과 검증 방법
- 개정된 「국민의 공휴일에 관한 법률」: 날짜가 고정된 공휴일, 월요일 공휴일(성인의 날과 체육의 날은 2000년부터, 바다의 날과 경로의 날은 2003년부터), 2016년부터의 산의 날, 연호별 천황 탄생일, 그리고 2020년과 2021년에 옮겨진 날.
- 대체 휴일: 국민 공휴일이 일요일과 겹치면, 그 뒤의 날 중 국민 공휴일이 아닌 첫날이 휴일이 됩니다(2007년부터. 그 이전에는 다음 날만).
- 국민의 휴일: 두 국민 공휴일 사이에 낀 날(1986년부터). 예: 2026년 9월 22일.
- 일회성 휴일: 1989-02-24, 1990-11-12, 1993-06-09, 2019-05-01, 2019-10-22.
- 춘분의 날과 추분의 날: 1980-2099년에 유효한 표준 근사식을 사용합니다. 정부는 각 날짜를 전년도 2월에 발표합니다.
- 은행 휴일: 토요일, 일요일, 국민 공휴일, 12월 31일부터 1월 3일까지(은행법). 현재의 규칙을 모든 연도에 적용합니다.
- gotobi: 5일분이 전달로 앞당겨지는 경우, 그날은 이미 전달 말일의 gotobi이므로 전달에만 포함됩니다. 따라서 2027년 5월의 gotobi는 5개입니다.
- 이는 버전 1.00을 만든 시점(2026년 10월)에 시행 중인 규칙입니다.
공개 전 확인 사항: 두 버전 모두 오류 0개, 경고 0개로 컴파일되며, MT4 버전은 같은 소스로 만들었습니다(시간 함수만 다름). 1980년부터 2027년까지의 국민 공휴일 789일이 모두 일본 내각부의 목록과 하루 단위로 일치합니다. 이 목록은 현재 2027년까지만 있습니다. 춘분·추분 계산식은 2027년까지 모든 해에서 공식 날짜와 같은 결과를 내고, 2099년까지 모든 해에서 천문 계산과 일치합니다. Market 경로에서의 import는 Strategy Tester에서도 불러와집니다.
개발자가 자주 묻는 질문
- 프로그램이 라이브러리 관련 오류로 멈춥니다. 라이브러리가 설치되어 있는지, #import 줄이 파일 이름과 정확히 일치하는지 확인하십시오. MT4용 파일 이름은 MT4로 끝납니다.
- 저녁 시간대에 일본 날짜가 하루 어긋납니다. 서버 시간을 넘긴 것입니다. 먼저 JpServerToJst()로 변환하십시오.
- JpGotobiDaysOfMonth()가 -1을 반환합니다. 동적 배열( datetime days[]; ), 1980~2099의 연도, 1~12의 월을 넘기십시오.
- OnTick()에서 써도 될 만큼 빠릅니까? 네. 결과는 연도별로 캐시됩니다. 캐시는 2년분을 보관하므로, 여러 해를 오가는 루프에서는 더 느려집니다.
상품 페이지: Japan Bank Holiday and Gotobi Library (MT5), Japan Bank Holiday and Gotobi Library MT4. 궁금한 점이 있으면 사용 중인 코드와 Experts 탭의 마지막 몇 줄을 MQL5 개인 메시지로 보내 주십시오.
