این اکسپرت (EA) برای حل یک کمبود اساسی در اکوسیستم متاتریدر ۵ طراحی شده است: تقویم اقتصادی داخلی MT5 تنها از طریق زبان MQL5 و تابع CalendarValueHistory() قابل دسترسی است و هیچ راه دیگری برای خواندن آن وجود ندارد. پکیج پایتون MetaTrader5 اگرچه قیمت‌ها، نمادها، سفارش‌ها و تاریخچه را ارائه می‌دهد، اما هیچ تابعی برای تقویم ندارد. بنابراین هر اسکریپت تحقیقاتی، داشبورد، ربات یا صفحه گسترده‌ای که نیاز دارد بداند رویداد مهم بعدی چه زمانی منتشر می‌شود، راهی برای پرسیدن از ترمینال ندارد. این اکسپرت به عنوان “پل گمشده” روی هر چارتی قرار می‌گیرد و به صورت دوره‌ای تقویم را در یک فایل CSV داخل پوشه MQL5\Files می‌نویسد تا هر ابزار خارجی بتواند آن را بخواند.

 نویسنده این اکسپرت را با دقت مهندسی‌شده از چهار اشتباه رایج محافظت کرده است: اول، خروجی را به صورت UTF-8 می‌نویسد نه کدپیج محلی، زیرا نام رویدادها به زبان ترمینال بازگردانده می‌شوند و در MT5 غیرانگلیسی حاوی کاراکترهای غیرلاتین هستند که با FILE_ANSI به بایت‌های نامعتبر UTF-8 تبدیل شده و در مصرف‌کننده‌هایی مثل پایتون یا اکسل باعث خطا یا خرابی می‌شوند. دوم، خروجی را بر اساس زمان مرتب می‌کند، چون تقویم به ازای هر ارز جداگانه پرس‌وجو می‌شود و خروجی طبیعی گروه‌بندی‌شده بر اساس ارز، پرش‌های زمانی دارد. سوم، کل فایل را در یک فراخوانی می‌نویسد تا خواننده‌ای که وسط نوشتن فایل را باز می‌کند، لیست ناقص نبیند و خط اول شامل timestamp و تعداد رویدادهاست تا تازگی فایل قابل تشخیص باشد. چهارم، موجودیت‌های HTML را در نام رویدادها رمزگشایی می‌کند، مثلاً & را به & تبدیل می‌کند تا نام‌هایی مثل “CFTC S&P 500” درست منتقل شوند.

 این اکسپرت با گروه‌بندی منظمی از پارامترها کنترل کامل را به کاربر می‌دهد. در بخش “What to include” می‌توان ارزها را با کاما جدا کرد (خالی = همه ارزها)، بازه زمانی را با InpHoursAhead (پیش‌رو) و InpHoursBack (پس‌رو برای داده‌های تازه منتشرشده) تنظیم کرد و حداقل اهمیت رویداد را با InpMinImportance (۰=هیچ، ۱=کم، ۲=متوسط، ۳=بالا) مشخص کرد. در بخش “Output” نیز نام فایل خروجی، بازه بازنویسی (InpRefreshSec با حداقل ۳۰ ثانیه) و انتخاب UTF-8 یا کدپیج ترمینال (InpUtf8) قابل تنظیم است. این طراحی اجازه می‌دهد کاربر بسته به نیاز، فقط رویدادهای با اهمیت بالا و ارزهای خاص را در بازه زمانی دلخواه دریافت کند.

معماری کد بر پایه یک ساختار Event بنا شده که هر ردیف خروجی را نگه می‌دارد تا کل مجموعه قبل از نوشتن قابل مرتب‌سازی باشد. تابع CurrencyOf با یک مکانیزم کش، ارز مربوط به هر کشور را فقط یک بار از ترمینال می‌پرسد چون هزاران مقدار تقویمی بین تعداد محدودی کشور مشترک هستند. تابع ImportanceWord مقادیر عددی importance را به کلمات خوانا (NONE/LOW/MEDIUM/HIGH) تبدیل می‌کند تا مصرف‌کننده مجبور نباشد CALENDAR_IMPORTANCE_HIGH را پاک‌سازی کند. تابع Unescape موجودیت‌های HTML را با ترتیب صحیح (amp در آخر برای جلوگیری از باگ double-decoding) رمزگشایی می‌کند. تابع Csv نیز نقل‌قول‌گذاری استاندارد CSV را انجام می‌دهد تا نام رویدادهایی که کاما دارند، دستکاری نشوند. تابع SortByTime از مرتب‌سازی درجی استفاده می‌کند که برای چند صد ردیف کارآمد است و ترتیب مساوی‌ها را حفظ می‌کند.

توضیحات طراح اکسپرت CalendarExport 

پنج جزئیات مهم در این ابزار وجود دارد. نخست، خروجی UTF-8 است، زیرا نام رویدادها توسط ترمینال بومی‌سازی می‌شوند و در MT5 غیرانگلیسی حاوی کاراکترهای دارای اعراب یا غیرلاتین هستند؛ اگر با کدپیج محلی نوشته شوند، به بایت‌هایی تبدیل می‌شوند که UTF-8 معتبر نیستند و بیشتر مصرف‌کننده‌ها یا خطا می‌دهند یا نام را بی‌صدا خراب می‌کنند. دوم، خروجی بر اساس زمان مرتب می‌شود، چون تقویم به ازای هر ارز یک بار پرس‌وجو می‌شود و خروجی طبیعی بر اساس ارز گروه‌بندی شده و در زمان جلو و عقب می‌پرد، اما این نسخه ترتیب زمانی دارد. سوم، فایل در یک فراخوانی واحد نوشته می‌شود؛ بدین ترتیب فایل در حافظه ساخته شده و یک‌جا نوشته می‌شود، در غیر این صورت خواننده‌ای که وسط نوشتن فایل را باز کند، لیست ناقصی می‌بیند و هیچ راهی برای فهمیدن آن ندارد. چهارم، موجودیت‌های HTML رمزگشایی شده‌اند، چون ترمینال نام رویدادها را escape شده ذخیره می‌کند و اگر بدون تغییر نوشته شود، به‌صورت اشتباه به هر مصرف‌کننده‌ای می‌رسد. پنجم، یک هدر تازگی وجود دارد که خط اول آن شامل زمان به‌روزرسانی، تعداد رویدادها و اختلاف UTC سرور است تا مصرف‌کننده بتواند فایل کهنه را از فایل جاری تشخیص دهد و متوجه شود که اکسپرت جدا شده، به‌جای اینکه تقویم قدیمی را طوری نشان دهد که گویی زنده است. زمان به‌روزرسانی از ساعت سرور معاملاتی خوانده می‌شود و نه از آخرین تیک، زیرا وقتی بازار بسته است آخرین تیک ثابت می‌ماند و فایلی که به آن روش تاریخ‌گذاری شده باشد در حالی که هر چند دقیقه بازنویسی می‌شود کهنه به نظر می‌رسد و پنجره رویداد در طول آخر هفته به عقب می‌لغزد.

ورودی‌ها

ورودی‌های این ابزار شامل InpCurrencies برای لیست جداشده با کاما مانند USD,EUR (برای همه ارزها خالی بگذارید)، InpHoursAhead برای میزان نگاه به جلو با پیش‌فرض ۴۸، InpHoursBack برای میزان نگاه به عقب جهت گرفتن داده‌های تازه منتشرشده با پیش‌فرض ۳، InpMinImportance با مقادیر ۰ برای هیچ، ۱ برای کم، ۲ برای متوسط و ۳ برای بالا با پیش‌فرض ۲، InpFile برای نام فایل خروجی داخل MQL5\Files، InpRefreshSec برای بازه بازنویسی بر حسب ثانیه با حداقل ۳۰، و InpUtf8 برای خروجی UTF-8 که فقط اگر مصرف‌کننده‌تان کدپیج محلی نیاز دارد خاموش می‌شود.

نکته‌ای درباره زبان

نام رویدادها به زبان ترمینال بازگردانده می‌شوند و MQL5 هیچ راهی برای درخواست زبان دیگر ارائه نمی‌دهد؛ اگر به کلیدی نیاز دارید که بین زبان‌ها و نصب‌های مختلف پایدار باشد، از ستون event_id استفاده کنید که دقیقاً به همین دلیل آنجاست.

عیب‌یابی

اگر فایل خالی بیرون آمد، MT5 تقویم را فقط زمانی پر می‌کند که ترمینال متصل باشد و برخی بروکرها آن را محدود می‌کنند، بنابراین در Tools → Options → Server بررسی کنید که تقویم فعال باشد.

تنظیمات اکسپرت CalendarExport

InpCurrencies — ارزهای مورد نظر برای استخراج از تقویم اقتصادی را به صورت جدا شده با کاما تعیین می‌کند. پیش‌فرض آن USD,EUR است. اگر این فیلد خالی بماند، تمام ارزهای موجود در تقویم استخراج می‌شوند.

InpHoursAhead — تعداد ساعاتی که به جلو (آینده) نگاه می‌شود تا رویدادهای اقتصادی پیش‌رو جمع‌آوری شوند. پیش‌فرض آن ۴۸ ساعت است.

InpHoursBack — تعداد ساعاتی که به عقب (گذشته) نگاه می‌شود تا داده‌های تازه منتشر شده نیز در خروجی گنجانده شوند. پیش‌فرض آن ۳ ساعت است.

InpMinImportance — حداقل اهمیت رویدادهای اقتصادی برای درج در فایل خروجی را تعیین می‌کند. مقدار ۰ به معنی «بدون فیلتر»، ۱ «کم»، ۲ «متوسط» و ۳ «زیاد» است. پیش‌فرض آن ۲ (متوسط) است.

InpFile — نام فایل CSV خروجی را مشخص می‌کند که در پوشه MQL5\Files همان ترمینال ذخیره می‌شود. پیش‌فرض آن calendar_export.csv است.

InpRefreshSec — بازه زمانی (به ثانیه) برای بازنویسی فایل خروجی را تعیین می‌کند. حداقل مقدار مجاز ۳۰ ثانیه است. پیش‌فرض آن ۳۰۰ ثانیه (۵ دقیقه) است.

InpUtf8 — فرمت رمزگذاری فایل خروجی را مشخص می‌کند. مقدار true (پیش‌فرض) خروجی را با رمزگذاری UTF-8 می‌نویسد که برای مصرف‌کنندگان خارجی مثل پایتون و اکسل توصیه می‌شود. مقدار false فایل را با کدپیج محلی ترمینال می‌نویسد.

این گروه مربوط به محل، نحوه‌ی نوشتن فایل خروجی و دوره‌ی به‌روزرسانی آن است.

InpFile — نام فایل خروجی را تعیین می‌کند که پیش‌فرض آن calendar_export.csv است و فایل همیشه در پوشه‌ی MQL5\Files همان ترمینالی که اکسپرت روی آن اجرا می‌شود ساخته می‌شود؛ این نام در تمام توابع نوشتن و پیام‌های خطا استفاده می‌گردد.

InpRefreshSec — فاصله‌ی زمانی بازنویسی فایل را بر حسب ثانیه تعیین می‌کند که پیش‌فرض آن ۳۰۰ ثانیه (۵ دقیقه) است و حداقل مجاز آن ۳۰ ثانیه است؛ اگر کاربر عددی کمتر وارد کند، عملاً ۳۰ ثانیه در نظر گرفته می‌شود تا از فشار بی‌مورد به ترمینال و نوشتن پیاپی روی دیسک جلوگیری شود.

InpUtf8 — نحوه‌ی رمزگذاری فایل خروجی را مشخص می‌کند که پیش‌فرض آن true است و باعث می‌شود فایل به‌صورت UTF-8 نوشته شود؛ چون نام رویدادها در MT5 به زبان ترمینال و با کاراکترهای غیرلاتین یا accent‌دار برمی‌گردند و اگر با کدپیج محلی (ANSI) نوشته شوند، برای مصرف‌کننده‌هایی مثل Python یا Excel که UTF-8 انتظار دارند، غیرقابل‌خوان یا مخدوش می‌شوند. با قرار دادن false، فایل با کدپیج محلی ترمینال نوشته می‌شود.