Japan Bank Holiday and Gotobi Library (MT5/MT4): Kullanım Kılavuzu, Fonksiyonlar ve Örnekler
Japan Bank Holiday and Gotobi Library, MetaTrader 5 ve MetaTrader 4 için ücretsiz bir kütüphanedir. Yen piyasasının takvimle ilgili sorularını kendi Uzman Danışmanınızın (EA), göstergenizin veya betiğinizin (script) içinde yanıtlar. Bu kılavuz geliştiriciler içindir ve her iki platformda 1.00 sürümü için geçerlidir.
Neleri yanıtlar
- Japonya'daki resmî tatiller (telafi tatilleri, vatandaş tatilleri ve bir kerelik tatiller dâhil), her birinin İngilizce adıyla.
- Japon banka tatilleri: cumartesiler, pazarlar, resmî tatiller ve 31 Aralık–3 Ocak arası. Diğer tüm günler Tokyo iş günüdür.
- Gotobi günleri: ayın 5'i, 10'u, 15'i, 20'si, 25'i ve son günü. Banka tatiline denk gelen gotobi, aynı ayın bir önceki iş gününe kaydırılır.
- Japonya saatiyle 09:55 olan Tokyo fixing saati ve sunucu saatinden Japonya saatine, Japonya saatinden sunucu saatine dönüşüm. Japonya'da yaz saati yoktur (JST = UTC+9).
1980 ile 2099 arasındaki yıllar. Kurallar hesaplanır; bu yüzden güncellenmesi gereken bir tatil tablosu yoktur. DLL yok, web isteği yok, dosya yok, işlem fonksiyonu yok.
Kurulum
- Ürün sayfasında Ücretsiz İndir (Free Download) düğmesine tıklayın (MetaTrader açılır) ya da ürünü Araç kutusu > Mağaza (Toolbox > Market) içinde bulun (MT4'te bu pencerenin adı Terminal'dir). MT5 ve MT4 ayrı ürünlerdir.
- Mağaza, kütüphaneyi MQL5\Libraries\Market\Japan Bank Holiday and Gotobi Library.ex5 (MT5) veya MQL4\Libraries\Market\Japan Bank Holiday and Gotobi Library MT4.ex4 (MT4) olarak kurar. Bu klasörleri Dosya > Veri Klasörünü Aç (File > Open Data Folder) ile görebilirsiniz.
- Kurulu ürünler ve güncellemeleri Araç kutusu > Mağaza > Satın Alınanlar (Toolbox > Market > Purchased) içindedir.
- Kütüphane bir grafiğe eklenmez. Onu kendi programınız import bloğu aracılığıyla yükler.
İçe aktarma (import)
Platformunuza uygun başlık dosyasını (header) Include klasörüne kaydedin ve programınızın en üstüne bir satır ekleyin:
- JpMarketCalendar_Market.mqh (MT5): MQL5\Include klasörüne kaydedin.
- JpMarketCalendar_Market_MT4.mqh (MT4): MQL4\Include klasörüne kaydedin.
#include <JpMarketCalendar_Market.mqh> // MT5 #include <JpMarketCalendar_Market_MT4.mqh> // MT4
Her başlık dosyası 17 fonksiyonun tamamını içe aktarır ve yaz saati kurallarını tanımlar: JP_DST_NONE (0), JP_DST_US (1) ve JP_DST_EU (2). Import bloğunu kendiniz yapıştırırsanız bloğun ilk satırı kurulu dosyayla birebir eşleşmelidir (iki ters eğik çizgi): #import "Market\\Japan Bank Holiday and Gotobi Library.ex5" (MT5) veya #import "Market\\Japan Bank Holiday and Gotobi Library MT4.ex4" (MT4).
Başlamak için iki program; ikisi de emir göndermez:
- JpCalendarDemo.mq5 / JpCalendarDemo_MT4.mq4: sunucu saatini ve Japonya saatini, sonraki fixing'leri ve seçtiğiniz yılların tatillerini ve gotobi günlerini yazdıran bir betik (script). Bunları yazdırıyorsa kütüphane doğru kurulmuş ve içe aktarılmıştır.
- JpCalendarExample.mq5 / JpCalendarExample_MT4.mq4: gotobi fixing saatini, tatilin adını veya bir sonraki gotobi gününü Comment() ile gösteren bir Uzman Danışman.
Altı dosyanın tümü 0 hata ve 0 uyarıyla derlenir. Aşağıda demo betiğinin bir MT5 demo sunucusundaki çıktısı yer alıyor; MT4 sürümü aynı satırları yazdırır.
Fonksiyon başvurusu
| Fonksiyon | Döndürür | Notlar |
|---|---|---|
| JpIsBankHoliday(datetime date_jst) | bool | Cumartesi, pazar, resmî tatiller ve 31 Aralık–3 Ocak arasında true. |
| JpIsBusinessDay(datetime date_jst) | bool | Tokyo iş günlerinde true. 1980-2099 dışında hem bu fonksiyon hem JpIsBankHoliday() false döndürür. |
| JpIsNationalHoliday(datetime date_jst) | bool | Resmî tatillerde true (telafi, vatandaş ve bir kerelik tatiller dâhil). |
| JpHolidayName(datetime date_jst) | string | İngilizce ad, örneğin "Marine Day"; resmî tatil olmadıkları sürece 31 Aralık, 2 Ocak ve 3 Ocak'ta "Bank Holiday"; diğer günlerde, sıradan hafta sonları dâhil, "". |
| JpIsGotobi(datetime date_jst) | bool | Gotobi günlerinde true; gotobi günleri her zaman iş günüdür. |
| JpGotobiDaysOfMonth(int year, int month, datetime &out[]) | int | Dinamik bir diziyi ayın gotobi günleriyle (00:00 JST, en eskisi önce) doldurur ve sayılarını döndürür; statik bir dizi, 1980-2099 dışında bir yıl veya 1-12 dışında bir ay için -1. |
| JpNextGotobi(datetime from_jst) | datetime | O tarihte veya sonrasındaki ilk gotobi (00:00 JST). Günün kendisi de sayılır, 09:55'ten sonra da. Yoksa 0. |
| JpPrevGotobi(datetime from_jst) | datetime | O tarihte veya öncesindeki son gotobi (00:00 JST). Yoksa 0. |
| JpTokyoFixing(datetime date_jst) | datetime | Herhangi bir gün için o günün 09:55 JST'si; fixing yalnızca iş günlerinde yayımlanır. |
| JpNowJst() | datetime | Güncel Japonya saati (sunucu saatinden; aşağıya bakın). |
| JpServerToJst(datetime server_time) | datetime | Kullanılan farkla sunucu saatini Japonya saatine çevirir. Geçersiz bir saat için 0. |
| JpJstToServer(datetime jst) | datetime | Japonya saatini sunucu saatine çevirir. Geçersiz bir saat için 0. |
| JpServerGmtOffsetSeconds() | int | Sunucunun şu anki GMT farkı, saniye cinsinden. |
| JpSetServerGmtOffset(int seconds) | bool | Yıl boyunca tek bir fark, örneğin GMT+2 için 7200. |
| JpSetServerTimeZone(int standard_offset_seconds, int dst_rule) | bool | Yaz saati dışındaki fark ve kural: 0 yok, 1 ABD, 2 AB (yaz saatinde +1 saat). |
| JpSetServerGmtOffsetAuto() | void | Otomatik farka geri döner (varsayılan). |
| JpLibraryVersion() | string | "1.00" |
Tarih argümanları Japonya saatidir; günün herhangi bir saati verilebilir. 1980-2099 dışında fonksiyonlar false, 0, "" veya -1 döndürür. İki ayarlayıcı (setter) fonksiyon, -43200 ile 50400 arasında 900 saniyenin katlarını kabul eder; başka bir değer için nedeni yazdırır, false döndürür ve önceki ayarı korur.
Örnekler
Japonya'da bugü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"); Henüz geçmemiş bir sonraki gotobi fixing'i:
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"); Bir ayın gotobi günleri:
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));
Saat dilimleri ve Strateji Sınayıcı
- Sunucu saati Japonya saati değildir: yukarıdaki demoda sunucu 13 Ekim 21:43'ü gösterirken Japonya'da saat 14 Ekim 03:43'tür. Bir günü sorgulamadan önce JpServerToJst() ile dönüştürün ya da JpNowJst() kullanın.
- Varsayılan fark otomatiktir: MT5'te TimeTradeServer() - TimeGMT(); 15 dakikaya yuvarlanır ve her çağrıda yeniden okunur. Terminal başladıktan hemen sonra birkaç saniye boyunca 0 okunabilir.
- MT4'te TimeTradeServer() yoktur; onun yerine son kotasyonun zamanı olan TimeCurrent() kullanılır ve bu değer başlangıçtan sonra veya piyasa kapalıyken yanlış olabilir. MT4'te farkı kendiniz ayarlayın.
- Strateji Sınayıcı'da TimeGMT() sunucu saatini döndürür; bu yüzden otomatik fark 0'dır. Kütüphane sınayıcının günlüğüne (Journal) bir kez hatırlatma yazar. Farkı OnInit() içinde ayarlayın.
- Otomatik fark bugünün farkıdır. Yaz saati değişikliğini kapsayan geçmiş barlar için sunucunun kuralını JpSetServerTimeZone() ile ayarlayın.
- Ayarlar yalnızca onları çağıran programa uygulanır: her Uzman Danışmanın veya göstergenin OnInit() fonksiyonunda çağırın.
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);
} ABD kuralı: mart ayının ikinci pazarından kasım ayının ilk pazarına kadar (2007'den önce ABD'de geçerli olan eski tarihler). AB kuralı: mart ayının son pazarından ekim ayının son pazarına kadar (1996'dan önce bitiş eylül ayındaydı). Kışın GMT+2, ABD yaz saatinde GMT+3 olan bir sunucu için değer 7200, kural 1'dir. Demo betiği sunucunuzun şu anki farkını gösterir; hangi yaz saatini izlediğini aracı kurumunuz söyleyebilir. MT5'te otomatik farkı canlıda korumak için ayarlayıcıyı yalnızca MQLInfoInteger(MQL_TESTER) true olduğunda çağırın; örnek EA da bunu yapar.
Kullanılan kurallar ve nasıl kontrol edildikleri
- Resmî Tatiller Kanunu ve değişiklikleri: sabit tarihler, pazartesiye alınan tatiller (2000'den itibaren Reşit Olma Günü ve Sağlık ve Spor Günü, 2003'ten itibaren Deniz Günü ve Yaşlılara Saygı Günü), 2016'dan itibaren Dağ Günü, döneme göre İmparatorun Doğum Günü ve 2020 ile 2021'de taşınan günler.
- Telafi tatili: bir resmî tatil pazara denk gelirse, sonraki ilk resmî tatil olmayan gün tatil olur (2007'den itibaren; öncesinde yalnızca ertesi gün).
- Vatandaş tatili: iki resmî tatil arasında kalan gün (1986'dan itibaren), örneğin 22 Eylül 2026.
- Bir kerelik tatiller: 1989-02-24, 1990-11-12, 1993-06-09, 2019-05-01 ve 2019-10-22.
- Ekinoks günleri: 1980-2099 için geçerli standart yaklaşık formül. Hükûmet her ekinoks gününü bir önceki yılın şubat ayında açıklar.
- Banka tatilleri: cumartesiler, pazarlar, resmî tatiller ve 31 Aralık–3 Ocak arası (Bankacılık Kanunu); bugünkü kural her yıla uygulanır.
- Gotobi: ayın 5'i bir önceki aya kayacaksa o gün zaten önceki ayın ay sonu gotobisidir ve yalnızca orada listelenir. Bu yüzden Mayıs 2027'de 5 gotobi günü vardır.
- Bunlar, 1.00 sürümü hazırlandığında (Ekim 2026) yürürlükte olan kurallardır.
Yayın öncesi kontroller: her iki sürüm de 0 hata ve 0 uyarıyla derlenir; MT4 sürümü aynı kaynak koddan üretilir (yalnızca saat fonksiyonu farklıdır). 1980'den 2027'ye kadarki 789 resmî tatilin tamamı Kabine Ofisi'nin listesiyle gün gün eşleşir; bu liste şu anda 2027'de bitiyor. Ekinoks formülü 2027'ye kadar her yıl resmî tarihi verir ve 2099'a kadar her yıl astronomik bir hesaplamayla uyuşur. Market yolundan yapılan import, Strateji Sınayıcı'da da yüklenir.
Geliştiricilerin sorduğu sorular
- Programım kütüphaneyle ilgili bir hatayla duruyor. Kütüphanenin kurulu olduğunu ve #import satırının dosya adıyla birebir eşleştiğini kontrol edin. MT4 dosya adı MT4 ile biter.
- Akşamları Japon tarihi bir gün kayık çıkıyor. Sunucu saatini vermişsiniz. Önce JpServerToJst() ile dönüştürün.
- JpGotobiDaysOfMonth() -1 döndürüyor. Dinamik bir dizi ( datetime days[]; ), 1980 ile 2099 arasında bir yıl ve 1 ile 12 arasında bir ay verin.
- OnTick() için yeterince hızlı mı? Evet. Sonuçlar yıl bazında önbelleğe alınır. Önbellek 2 yılı tutar; bu yüzden birçok yıl arasında atlayan bir döngü daha yavaştır.
Ürün sayfaları: Japan Bank Holiday and Gotobi Library (MT5) ve Japan Bank Holiday and Gotobi Library MT4. Anlaşılmayan bir şey olursa lütfen kullandığınız kodu ve Uzmanlar (Experts) sekmesinin son satırlarını ekleyerek MQL5 üzerinden bana özel mesaj gönderin.
