CalendarEventByCountry関数の働き・役割
CalendarEventByCountry関数は、指定された国コードに対応する経済カレンダーイベントの情報を取得するために使用されます。
この関数は、ISO3166-1 alpha-2形式で与えられた国コードに基づき、その国の経済イベントに関する説明を配列で取得します。
例えば、EUやUSといった国コードを使用して欧州連合やアメリカの経済イベント情報を取得することが可能です。
CalendarEventByCountry関数の引数について
CalendarEventByCountry関数の引数構成は以下の通りです。
int CalendarEventByCountry(
string country_code, // 国コード名(ISO 3166-1 alpha-2)
MqlCalendarEvent& events[] // 説明配列を受け取るための変数
);引数の詳細
country_code
この引数は、取得したい国のコードをISO3166-1 alpha-2形式で指定します。国コードは2文字のアルファベットで表され、例えば、欧州連合ならばEU、アメリカ合衆国ならばUSと指定します。この国コードに基づいて、該当する国の経済イベント情報が抽出されます。
events[]
この引数は、取得したイベント情報を格納するためのMqlCalendarEvent構造体型配列です。この配列は、CalendarEventByCountry関数を実行する際に空の配列として渡され、関数が実行されると、指定した国に関するイベント情報が配列に格納されます。配列内には、各イベントの詳細がMqlCalendarEvent構造体型として保存され、後の操作や表示に利用できます。
CalendarEventByCountry関数の戻り値について
CalendarEventByCountry関数は、指定した国コードに対応するイベントの説明が格納された配列の要素数を整数型で返します。
取得したイベントの数が戻り値となり、0以上の値が返る場合、正常にイベントが取得できたことを示しています。例えば、戻り値が56の場合、56個のイベントが取得されたことになります。
エラーが発生した場合、戻り値として0が返されます。その際、エラーの詳細を確認するにはGetLastError関数を使用してエラーコードを取得します。以下に、関数実行時に発生する可能性のあるエラーコードとその内容を示します。
- 4001 (ERR_INTERNAL_ERROR)
一般的なランタイムエラーです。内部的なエラーが発生したことを示します。 - 4004 (ERR_NOT_ENOUGH_MEMORY)
メモリが不足しているため、操作を完了できません。 - 5401 (ERR_CALENDAR_TIMEOUT)
リクエストがタイムアウトしたことを示します。データの取得に時間がかかりすぎた場合に発生します。
また、取得したイベント数が0の場合、指定した国コードが無効であるか、該当するイベントが存在しない可能性があります。この場合もエラーコードで詳細を確認することが推奨されます。
CalendarEventByCountry関数を使ったサンプルコード
//+------------------------------------------------------------------+
//| スクリプトプログラム開始関数 |
//+------------------------------------------------------------------+
void OnStart()
{
//--- ドイツの国コード(ISO 3166-1 Alpha-2)を指定
string germany_code = "DE";
//--- ドイツの経済イベントを格納するためのMqlCalendarEvent構造体の配列を用意
MqlCalendarEvent events[];
//--- ドイツの経済イベントを取得し、配列に格納。取得したイベント数をevents_countに代入
int events_count = CalendarEventByCountry(germany_code, events);
//--- 取得したイベントが存在するかを確認
if (events_count > 0)
{
//--- イベント数を操作ログに表示
PrintFormat("Germany events: %d", events_count);
//--- イベントの詳細を配列の内容として表示
ArrayPrint(events);
}
else
{
//--- イベントが取得できなかった場合、エラーメッセージを表示し、スクリプトを終了
PrintFormat("Failed to receive events for the country code %s, error %d",
germany_code, GetLastError());
return;
}
//--- 配列eventsの最後のイベントのIDを取得
MqlCalendarEvent event;
ulong event_id = events[events_count - 1].id;
//--- 取得したIDを基に、イベントの詳細をevent変数に格納
if (CalendarEventById(event_id, event))
{
//--- イベントの国に関する情報を格納するMqlCalendarCountry構造体を宣言
MqlCalendarCountry country;
//--- イベントのcountry_idを基に、国情報を取得してcountry変数に格納
CalendarCountryById(event.country_id, country);
//--- イベント情報の詳細を操作ログに出力
PrintFormat("Event description with event_id=%d received", event_id);
//--- イベントが関連する国の名前とIDを表示
PrintFormat("Country: %s (country code = %d)", country.name, event.country_id);
//--- イベント名を表示
PrintFormat("Event name: %s", event.name);
//--- イベントコードを表示
PrintFormat("Event code: %s", event.event_code);
//--- イベントの重要度を列挙体の名称で表示
PrintFormat("Event importance: %s", EnumToString((ENUM_CALENDAR_EVENT_IMPORTANCE)event.importance));
//--- イベントのタイプを列挙体の名称で表示
PrintFormat("Event type: %s", EnumToString((ENUM_CALENDAR_EVENT_TYPE)event.type));
//--- イベントが関連する部門を列挙体の名称で表示
PrintFormat("Event sector: %s", EnumToString((ENUM_CALENDAR_EVENT_SECTOR)event.sector));
//--- イベントの発生頻度を列挙体の名称で表示
PrintFormat("Event frequency: %s", EnumToString((ENUM_CALENDAR_EVENT_FREQUENCY)event.frequency));
//--- イベントの発表時間モードを列挙体の名称で表示
PrintFormat("Event release mode: %s", EnumToString((ENUM_CALENDAR_EVENT_TIMEMODE)event.time_mode));
//--- イベントの測定単位を列挙体の名称で表示
PrintFormat("Event measurement unit: %s", EnumToString((ENUM_CALENDAR_EVENT_UNIT)event.unit));
//--- イベント数値の小数点以下の桁数を表示
PrintFormat("Number of decimal places: %d", event.digits);
//--- イベントの値の乗数を列挙体の名称で表示
PrintFormat("Event multiplier: %s", EnumToString((ENUM_CALENDAR_EVENT_MULTIPLIER)event.multiplier));
//--- イベント発表元のURLを表示
PrintFormat("Source URL: %s", event.source_url);
}
else
{
//--- イベントの詳細取得が失敗した場合、エラーメッセージを表示
PrintFormat("Failed to get event description for event_id=%d, error %d",
event_id, GetLastError());
}
}
このコードは、MQL5環境で実行されるスクリプトで、ドイツの経済カレンダーから最新の経済イベント情報を取得し、操作ログに出力します。
まず、指定した国コード「DE」に基づいて経済イベントを取得します。取得したイベント数が1件以上であれば、その中で最も新しい（最後の）イベントの詳細情報をイベントIDを使って取得します。
取得したイベントの情報には、関連する国の名前やイベント名、コード、重要度、発表元のURLなどが含まれ、それぞれが操作ログに出力されます。
もしイベント情報の取得が失敗した場合や該当するイベントがなかった場合には、操作ログにエラーメッセージが表示され、スクリプトは終了します。
サンプルコード解説1
//+------------------------------------------------------------------+
//| スクリプトプログラム開始関数 |
//+------------------------------------------------------------------+
void OnStart()
{
//--- ドイツの国コード(ISO 3166-1 Alpha-2)を指定
string germany_code = "DE";
//--- ドイツの経済イベントを格納するためのMqlCalendarEvent構造体の配列を用意
MqlCalendarEvent events[];
//--- ドイツの経済イベントを取得し、配列に格納。取得したイベント数をevents_countに代入
int events_count = CalendarEventByCountry(germany_code, events);このコードの冒頭部分は、ドイツの経済カレンダーイベントを取得し、その情報を操作ログに出力する準備を整えています。ここでは、特にドイツの経済イベントを取得するための国コード指定と、経済イベントデータを格納するための配列準備を行っています。
国コードの指定
コードの最初の部分で、変数germany_codeに「DE」という国コードが代入されています。この「DE」はISO3166-1 Alpha-2形式のドイツを表す国コードで、CalendarEventByCountry関数を使って特定の国に関する経済イベント情報を取得する際に利用されます。
経済イベントデータの格納準備
次に、MqlCalendarEvent構造体型の配列eventsが宣言されています。MqlCalendarEvent構造体は、特定の経済イベントに関する詳細な情報を保持するための構造体で、配列eventsは複数のイベント情報を格納するために使用されます。各イベントには、IDや国ID、イベント名、重要度、発表元URLなど、さまざまな属性情報が含まれています。
CalendarEventByCountry関数の使用
CalendarEventByCountry関数が呼び出されており、最初の引数には国コード（germany_code）、次に取得したイベント情報を格納するための配列eventsが指定されています。この関数は指定した国に関連するすべての経済イベントを取得し、そのイベント数を戻り値として返します。
関数の実行が成功すると、取得されたイベントデータが配列eventsに格納され、戻り値であるevents_countにそのイベントの数が代入されます。これにより、後続のコードでイベント数に応じた処理を行うことが可能になります。
サンプルコード解説2
//--- 取得したイベントが存在するかを確認
if (events_count > 0)
{
//--- イベント数を操作ログに表示
PrintFormat("Germany events: %d", events_count);
//--- イベントの詳細を配列の内容として表示
ArrayPrint(events);
}この部分のコードは、取得した経済イベントの数を確認し、その情報を操作ログに出力する処理を行っています。ドイツの経済カレンダーイベントが1件以上取得できているかどうかを条件としてチェックし、イベントの詳細を表示する準備を整えます。
イベント数の確認
まず、if文で取得されたイベントの数を確認しています。events_countが0より大きい場合、つまり1件以上のイベントが取得されている場合には、そのイベント情報が操作ログに出力される流れになります。
操作ログへのイベント数の出力
条件が満たされた場合、PrintFormat関数を使って「Germany events: 数」として取得したイベントの総数を操作ログに表示します。PrintFormat関数は、指定したフォーマット指定子に従って文字列を生成し、操作ログに出力する関数で、ここではイベント数をログに出すために利用しています。
イベントの詳細出力
次に、ArrayPrint関数を用いて配列eventsに格納された各イベントの詳細を出力します。ArrayPrint関数は、配列の全要素を操作ログに出力するため、配列eventsに含まれるイベント情報（イベントID、国ID、イベント名など）が全て操作ログに表示されます。
このコードにより、取得したドイツの経済イベントが操作ログにわかりやすく一覧として出力され、デバッグやイベント情報の確認が容易になります。
サンプルコード解説3
else
{
//--- イベントが取得できなかった場合、エラーメッセージを表示し、スクリプトを終了
PrintFormat("Failed to receive events for the country code %s, error %d",
germany_code, GetLastError());
return;
}この部分のコードは、ドイツの経済イベントが取得できなかった場合の処理を示しています。もしイベント情報の取得が失敗した場合には、エラーメッセージを操作ログに出力し、スクリプトを終了させます。
イベント取得失敗時の処理
if文でevents_countが0以下の場合、つまり経済イベントが1件も取得できなかった場合には、elseブロックが実行されます。このブロックの中では、イベント情報の取得が失敗した原因を特定するために、エラーメッセージを表示する処理が行われます。
エラーメッセージの出力
PrintFormat関数を使用して、「Failed to receive events for the country code DE, error X」といった形式でエラーメッセージが操作ログに表示されます。
ここで使用されているGetLastError関数は、直前に発生したエラーコードを取得する関数で、関数呼び出しが失敗した理由を調べる際に役立ちます。
このコードにより、指定した国コード「DE」に関連するイベント情報が取得できなかった場合のエラーメッセージが操作ログに表示され、スクリプトの実行が即座に終了します。
サンプルコード解説4
//--- 配列eventsの最後のイベントのIDを取得
MqlCalendarEvent event;
ulong event_id = events[events_count - 1].id;この部分のコードは、取得した経済イベントの中から最後のイベントのIDを取り出し、後続の詳細取得に使用するための準備を行っています。
最後のイベントIDの取得
まず、配列eventsの最後の要素からイベントIDを取得しています。events配列は複数のイベント情報を格納しており、そのインデックスは0から始まります。したがって、最後のイベントはインデックスがevents_count – 1で示されます。このインデックスを使い、最後のイベントにアクセスしてIDを取得し、event_id変数に格納しています。
MqlCalendarEvent構造体の変数宣言
続いて、MqlCalendarEvent構造体型の変数変数eventを宣言しています。この変数は、後でCalendarEventById関数を使って特定のイベントの詳細情報を取得し、格納するために用意されているものです。
このコードによって、取得済みのイベントの中から最新のイベントのIDが特定され、後に続く処理でこのIDに基づいて詳細なイベント情報が取得できる準備が整います。
サンプルコード解説5
この部分のコードでは、CalendarEventById関数を使用して取得したイベントIDを基に、該当するイベントの詳細情報をevent変数に格納しています。また、イベントに関連する国の情報を取得するための準備も行っています。
イベントの詳細情報取得
CalendarEventById関数を用いて、前のステップで取得した最後のイベントID（event_id）に基づいて詳細情報を取得し、MqlCalendarEvent構造体型のevent変数に格納します。この関数がtrueを返すと、指定したIDに対応するイベント情報の取得が成功したことを意味します。
国情報の格納準備
次に、MqlCalendarCountry構造体のcountry変数を宣言しています。この変数は、イベントに関連する国の情報（国名や国IDなど）を格納するためのもので、CalendarCountryById関数を使用してイベントが属する国の詳細を取得する際に利用されます。
CalendarCountryById関数による国情報の取得
CalendarCountryById関数が、イベントのcountry_idを使用してその国の詳細情報をcountry変数に格納します。これにより、イベントがどの国に関連しているかを把握でき、後続の処理で国名やIDを出力できる準備が整います。
サンプルコード解説6
//--- イベント情報の詳細を操作ログに出力
PrintFormat("Event description with event_id=%d received", event_id);
//--- イベントが関連する国の名前とIDを表示
PrintFormat("Country: %s (country code = %d)", country.name, event.country_id);
//--- イベント名を表示
PrintFormat("Event name: %s", event.name);
//--- イベントコードを表示
PrintFormat("Event code: %s", event.event_code);
//--- イベントの重要度を列挙体の名称で表示
PrintFormat("Event importance: %s", EnumToString((ENUM_CALENDAR_EVENT_IMPORTANCE)event.importance));
//--- イベントのタイプを列挙体の名称で表示
PrintFormat("Event type: %s", EnumToString((ENUM_CALENDAR_EVENT_TYPE)event.type));
//--- イベントが関連する部門を列挙体の名称で表示
PrintFormat("Event sector: %s", EnumToString((ENUM_CALENDAR_EVENT_SECTOR)event.sector));
//--- イベントの発生頻度を列挙体の名称で表示
PrintFormat("Event frequency: %s", EnumToString((ENUM_CALENDAR_EVENT_FREQUENCY)event.frequency));
//--- イベントの発表時間モードを列挙体の名称で表示
PrintFormat("Event release mode: %s", EnumToString((ENUM_CALENDAR_EVENT_TIMEMODE)event.time_mode));
//--- イベントの測定単位を列挙体の名称で表示
PrintFormat("Event measurement unit: %s", EnumToString((ENUM_CALENDAR_EVENT_UNIT)event.unit));
//--- イベント数値の小数点以下の桁数を表示
PrintFormat("Number of decimal places: %d", event.digits);
//--- イベントの値の乗数を列挙体の名称で表示
PrintFormat("Event multiplier: %s", EnumToString((ENUM_CALENDAR_EVENT_MULTIPLIER)event.multiplier));
//--- イベント発表元のURLを表示
PrintFormat("Source URL: %s", event.source_url);
}この部分のコードでは、取得したイベントの詳細情報を操作ログに表示しています。各情報はPrintFormat関数を使用して出力され、フォーマット指定子と値のペアで詳細が表示されます。また、列挙体（ENUM）で格納された情報は、EnumToString関数を用いて文字列に変換されています。
PrintFormatによるイベントIDの表示
このPrintFormat関数は、取得したイベントID（event_id）を操作ログに出力しています。フォーマット指定子%dは整数を示し、ここではevent_idの値が挿入されます。この行により、「指定されたイベントIDのイベント情報が取得された」ことが確認できます。
イベントの関連国の名前とIDの表示
イベントの国情報を示す行です。国名と国コードが出力され、%sは文字列（country.name）に、%dは整数値（event.country_id）に対応します。この情報はCalendarCountryById関数を使って取得され、特定の国に関連するイベント情報であることを示します。
イベント名の表示
イベントの名称（event.name）を出力しています。%sフォーマット指定子は、構造体のメンバevent.nameに対応し、イベント名を文字列としてログに表示します。このイベント名はユーザーが内容を把握するための重要な情報です。
イベントコードの表示
イベントに関連付けられた識別コード（event.event_code）を表示します。このコードは、%sフォーマット指定子で文字列として出力され、イベントを一意に特定するための文字列です。
イベントの重要度の表示
イベントの重要度を列挙体の名称で表示しています。EnumToString関数は列挙体の数値を文字列に変換するもので、ここではENUM_CALENDAR_EVENT_IMPORTANCE列挙体に基づく重要度をわかりやすい文字列で出力します。これにより、イベントの市場影響度が視覚的に確認できます。
イベントのタイプの表示
イベントの種類（event.type）をEnumToString関数で文字列に変換して出力しています。この変換によって、ENUM_CALENDAR_EVENT_TYPE列挙体に基づくイベントの種類（指標、政策発表など）が文字列で表示され、イベントの分類が理解しやすくなります。
イベントの関連部門の表示
イベントが関連する部門（event.sector）を表示しています。ENUM_CALENDAR_EVENT_SECTOR列挙体に基づき、ビジネスや金融など、どの経済部門に属するイベントであるかを文字列で確認できます。
イベントの発生頻度の表示
イベントの発生頻度を示す行です。ENUM_CALENDAR_EVENT_FREQUENCY列挙体の内容を文字列に変換して表示することで、イベントの発表頻度（月次、年次など）が確認できます。
イベントの発表時間モードの表示
イベントの発表時間モード（event.time_mode）を表示しています。ENUM_CALENDAR_EVENT_TIMEMODE列挙体を文字列に変換することで、タイムゾーンや日付形式が明示され、発表時間のモードが確認できます。
イベントの測定単位の表示
イベントで使用される測定単位（event.unit）を表示しています。ENUM_CALENDAR_EVENT_UNIT列挙体を使用し、パーセンテージ、指数などの単位がわかりやすい形で表示されます。
小数点以下の桁数の表示
イベント数値の小数点以下の桁数（event.digits）を出力しています。%dフォーマット指定子により整数として出力され、指標データがどの程度の精度で表示されるかを確認できます。
イベント値の乗数の表示
イベントの値の乗数（event.multiplier）を表示しています。ENUM_CALENDAR_EVENT_MULTIPLIER列挙体を用いて、数値に適用される倍率を文字列で出力し、指標のスケールが理解しやすくなっています。
発表元URLの表示
イベントの発表元URL（event.source_url）を出力します。%sフォーマット指定子によりURLが文字列として表示され、イベントの出典情報が操作ログで確認できます。
サンプルコード解説7
else
{
//--- イベントの詳細取得が失敗した場合、エラーメッセージを表示
PrintFormat("Failed to get event description for event_id=%d, error %d",
event_id, GetLastError());
}
}この部分のコードでは、イベント詳細の取得が失敗した場合のエラーハンドリングが行われています。もしCalendarEventById関数がイベント詳細を取得できなかった場合に、エラーメッセージが操作ログに表示され、スクリプトの異常がわかるようになっています。
エラーメッセージの表示
PrintFormat関数を使用して、取得に失敗したイベントID（event_id）とエラーコードを操作ログに出力しています。フォーマット指定子%dが2つあり、最初の%dは失敗したイベントIDに、2つ目の%dはエラーコードに対応します。GetLastError関数を使って、失敗の原因となったエラーコードが取得され、エラー内容がわかるようになっています。
これにより、イベント情報の取得に失敗した原因を特定しやすくなり、エラーコードに応じたデバッグが行いやすくなります。このエラーハンドリングは、イベント取得の成否に関するフィードバックを操作ログに提供するために重要です。
CalendarEventByCountry関数を使ってEAを作る際のアイディア
CalendarEventByCountry関数を使用することで、特定の国の経済イベントに基づいたエキスパートアドバイザー（EA）を作成することができます。この関数を用いて国ごとの重要な経済イベントを収集し、相場の動きに応じた取引戦略を実装するアイディアとして以下のものが考えられます。
- 経済イベントに基づいた自動取引
国の経済イベントが市場に影響を与える可能性が高いため、CalendarEventByCountry関数を使用して重要なイベント（例えば、中央銀行の政策決定会議や経済指標の発表）をチェックし、発表直前の市場動向に基づいて取引を自動化します。EAは、発表前後のボラティリティの変化に合わせてエントリーやエグジットポイントを調整するようなアルゴリズムを構築できます。 - イベントの重要度を考慮した取引ポジションの管理
MqlCalendarEvent型にはイベントの重要度（importance）が含まれています。イベントの重要度に基づいてポジションサイズやリスク管理を調整するEAを作成することも有効です。例えば、重要度の高いイベントが控えている場合にはポジションサイズを減らしたり、ストップロスを設定するなどのリスク管理を行います。 - 国別の経済イベントフィルターによるポートフォリオ管理
CalendarEventByCountry関数を使って複数の国の経済イベントを取得し、特定の国のイベントのみをフィルタリングして管理するEAを開発することも可能です。例えば、アメリカと欧州連合の経済イベントのみに反応する取引ポートフォリオを組み、これに応じた通貨ペアのポジションを取るといったアイディアが考えられます。 - ニュースやイベントの頻度によるボラティリティ予測モデルの作成
取得した経済イベントのデータを使い、特定の国のニュース頻度とボラティリティとの関係を分析するEAも構築できます。経済イベントの発生頻度が高まるとボラティリティが上昇する傾向があるため、この関数を使ってイベント数をカウントし、一定以上の場合に取引を控えたり、逆に取引を行うタイミングとする戦略を構築することができます。 - トレンド転換の可能性を示唆するイベント検出によるエントリーポイントの選定
重要な経済イベントはトレンド転換のきっかけになることが多いため、CalendarEventByCountry関数で特定のイベント（例えば、GDP発表や金利政策決定）を検出し、そのイベントをトリガーとしてエントリーするタイミングをEAで設定します。
