CalendarEventById関数の働き・役割
CalendarEventById関数は、指定したイベントIDに基づいて経済カレンダーイベントの詳細な情報を取得するために使用されます。
この関数を使用することで、特定のイベントIDに対応するイベントの説明や属性情報を取得関数し、そのイベントが属する国やイベントの重要度、リリースモード、使用されている測定単位、発表元のURLなど、詳細なイベント情報にアクセスできます。
CalendarEventById関数の引数について
bool CalendarEventById(
ulong event_id, // イベントID
MqlCalendarEvent& event // イベントの説明を受け取るための変数
);
CalendarEventById関数は、2つの引数を取ります。
各引数の説明
- event_id
種類: ulong
説明: イベントIDを指定する引数です。このIDに対応するイベントの詳細情報を取得します。例えば、特定の経済イベントのIDを渡すことで、そのイベントの内容を取得できます。 - event
種類: MqlCalendarEvent構造体
説明: イベントの詳細を受け取るためのMqlCalendarEvent構造体の変数です。この引数には、指定したイベントIDに対応するイベントの説明や属性情報が格納されます。
MqlCalendarEvent構造体とは
MqlCalendarEvent構造体は、経済カレンダーイベントの詳細情報を格納するための構造体です。この構造体は、CalendarEventById関数、CalendarEventByCountry関数、CalendarEventByCurrency関数といった関数で使用され、特定のイベントに関連する様々な属性を表します。以下に、各メンバのデータ型と詳細について説明します。
id
データ型: ulong
イベントIDを表すメンバです。このIDは、特定の経済イベントを一意に識別するために使用されます。イベントの情報を取得する際には、このIDを基に詳細なデータを取得することができます。
type
データ型: ENUM_CALENDAR_EVENT_TYPE
イベントのタイプを示すメンバです。ENUM_CALENDAR_EVENT_TYPE列挙体を使用し、指標や政策発表などの異なるイベントの分類を識別するのに役立ちます。
sector
データ型: ENUM_CALENDAR_EVENT_SECTOR
イベントが関連する部門を表すメンバです。ENUM_CALENDAR_EVENT_SECTOR列挙体を使用して、ビジネス、消費者、金融などイベントが関係する経済部門を示します。
frequency
データ型: ENUM_CALENDAR_EVENT_FREQUENCY
イベントの発生頻度を示すメンバです。ENUM_CALENDAR_EVENT_FREQUENCY列挙体を使用して、月次、四半期ごと、年次などのイベント発生周期を示します。
time_mode
データ型: ENUM_CALENDAR_EVENT_TIMEMODE
イベントの時間モードを示すメンバです。ENUM_CALENDAR_EVENT_TIMEMODE列挙体を用いて、イベントが発表される時間やタイムゾーンなどの情報が含まれます。
country_id
データ型: ulong
イベントが関連する国を識別するための国IDを示すメンバです。このIDを使用してイベントの属する国や地域を特定します。
unit
データ型: ENUM_CALENDAR_EVENT_UNIT
イベントの経済指標の測定単位を示すメンバです。ENUM_CALENDAR_EVENT_UNIT列挙体を使用し、指標値がパーセンテージ、ドル、指数などの単位で表されることを示します。
importance
データ型: ENUM_CALENDAR_EVENT_IMPORTANCE
イベントの重要度を示すメンバです。ENUM_CALENDAR_EVENT_IMPORTANCE列挙体を用いて、イベントの重要度を高・中・低などのレベルで表し、マーケットへの影響度を示します。
multiplier
データ型: ENUM_CALENDAR_EVENT_MULTIPLIER
経済指標の乗数を示すメンバです。ENUM_CALENDAR_EVENT_MULTIPLIER列挙体を用いて、特定の指標値に適用される乗数(例:倍数)を設定します。
digits
データ型: uint
イベントの経済指標値における小数点以下の桁数を示すメンバです。数値の精度を表し、必要な桁数でデータが表示されるようにします。
source_url
データ型: string
イベント発表元のウェブサイトのURLを示すメンバです。この情報は、指標の詳細や発表元のデータにアクセスする際に利用できます。
event_code
データ型: string
イベントコードを示すメンバです。このコードは、発表される経済イベントを一意に識別するための文字列で、識別や参照に使用されます。
name
データ型: string
イベントの名前を示すメンバです。現在のターミナルエンコーディングに基づいた形式でイベント名が格納され、イベントの説明や識別に使用されます。
CalendarEventById関数の戻り値について
CalendarEventById関数は、指定されたイベントIDに基づくイベントの情報が正しく取得できた場合にtrueを返します。取得に失敗した場合はfalseが返されます。falseが返された場合、GetLastError関数を使用して詳細なエラー情報を取得することができます。
発生する可能性のあるエラーには以下のものがあります。
- エラーコード 4001: ERR_INTERNAL_ERROR
一般的なランタイムエラーが発生したことを意味します。 - エラーコード 5402: ERR_CALENDAR_NO_DATA
無効な国IDが指定された場合に発生します。指定した国IDに対応する国の情報が存在しない場合です。 - エラーコード 5401: ERR_CALENDAR_TIMEOUT
リクエストの処理が制限時間を超えた場合に発生します
このように、戻り値は処理の成否を判断するための重要な要素であり、失敗した場合のエラーコードに基づいて適切なエラーハンドリングを行うことが推奨されます。
CalendarEventById関数を使ったサンプルコード
//+------------------------------------------------------------------+
//| スクリプトプログラム開始関数 |
//+------------------------------------------------------------------+
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関数を使って、失敗の原因となったエラーコードが取得され、エラー内容がわかるようになっています。
これにより、イベント情報の取得に失敗した原因を特定しやすくなり、エラーコードに応じたデバッグが行いやすくなります。このエラーハンドリングは、イベント取得の成否に関するフィードバックを操作ログに提供するために重要です。
CalendarEventById関数を使ってEAを作る際のアイディア
CalendarEventById関数は経済イベントの詳細情報を取得できるため、この情報を活用してEA(エキスパートアドバイザー)に経済イベントに基づく自動取引の戦略を組み込むことが可能です。以下に、この関数を活用したEAのアイディアを紹介します。
アイディア1:高影響度イベントによるトレードポジションの管理
CalendarEventById関数を使って重要度の高い経済イベントを抽出し、そのイベント前後での取引を制御するEAを作成します。
具体的には、イベントの重要度が高い場合、その直前に新たなポジションを取らないように設定し、リスクを回避します。さらに、イベント直後の市場のボラティリティが高まるタイミングを見計らってポジションを調整することで、急激な価格変動から利益を得ることも可能です。
アイディア2:国別イベントに基づくクロス通貨ペア戦略
CalendarEventById関数で特定の国の経済イベントを取得し、その国に関係する通貨ペアの取引戦略をEAに組み込みます。
例えば、米国の重要な経済イベントが発表される直前または直後に、ドルが関係するクロス通貨ペア(EURUSD、USDJPYなど)で自動売買を行います。このEAでは、イベントの重要度や発表される指標に基づき、トレンドフォローや逆張りなどのポジションを自動的に決定できます。
アイディア3:頻度や種類ごとに異なる取引ロジックの設定
CalendarEventById関数を使用してイベントの頻度や種類(例:GDP、失業率、製造業PMIなど)を取得し、異なるイベントに合わせた取引ロジックを組み込んだEAを作成します。たとえば、毎月発表される失業率のイベントでは、直前の市場価格を確認しながら順張りの取引を行い、四半期ごとに発表されるGDPデータでは、発表後に逆張りを行うなどの柔軟な取引ロジックを実装することが可能です。
アイディア4:特定の経済指標単位に応じた資金管理
CalendarEventById関数で取得できる測定単位や倍率情報を活用し、指標の特性に応じてリスク管理を行うEAを作成します。例えば、パーセンテージ単位の指標に基づくイベントでは大きな値幅変動が予想されるため、リスク管理を強化してロット数を調整する、といった対応が可能です。これにより、経済指標ごとにリスクを最適化した取引ができるEAを構築できます。