CalendarValueHistoryByEvent関数の働き・役割
CalendarValueHistoryByEvent関数は、指定されたイベントIDを基に、特定の期間内のすべての経済イベントの値を取得します。この関数は、過去のイベントデータを分析する際に利用されます。
取得した値は、MqlCalendarValue構造体型の配列として格納され、経済指標の実際の値、予測値、前回値などを扱うことができます。
また、期間の指定を柔軟に行えるため、開始日以降のすべてのイベントを取得したり、特定の期間に絞り込んだデータを取得することが可能です。この機能を活用することで、経済データを用いたトレード戦略を効率的に構築できます。
CalendarValueHistoryByEvent関数の引数について
bool CalendarValueHistoryByEvent(
ulong event_id, // イベントID
MqlCalendarValue& values[], // 値の説明の配列
datetime datetime_from, // 期間の左の境界
datetime datetime_to=0 // 期間の右の境界
);CalendarValueHistoryByEvent関数は以下の引数を取ります。
event_id
この引数は、対象となるイベントを特定するための識別子を指定します。イベントIDは事前に他のカレンダー関連の関数（例えば、CalendarEventByCountry関数）を使用して取得します。
values
MqlCalendarValue構造体型の配列で、指定されたイベントの値を受け取ります。この配列は呼び出し元で宣言しておき、取得されたデータが格納されます。
datetime_from
対象となる期間の開始日を指定します。この引数には、dateTime型の値を設定します。
datetime_to
対象となる期間の終了日を指定します。この引数が0の場合、datetime_from以降のすべてのイベント値が返されます。指定がない場合には、デフォルト値である0が適用されます。
CalendarValueHistoryByEvent関数を呼び出す際には、対象のイベントIDと期間の範囲を正確に設定する必要があります。また、values配列には十分なサイズを確保しておく必要があります。これは、エラーやデータ不足を防ぐために重要です。
CalendarValueHistoryByEvent関数の戻り値について
CalendarValueHistoryByEvent関数は、関数の実行結果に応じて以下のいずれかを返します。
true
指定したイベントIDと期間に基づいてデータを正常に取得できた場合に返されます。この場合、取得したデータはvalues配列に格納されます。
false
データ取得に失敗した場合に返されます。この場合、失敗の原因を特定するためにGetLastError関数を使用してエラーコードを確認する必要があります。
主なエラーコード
- 4001 (ERR_INTERNAL_ERROR): 一般的なランタイムエラー。
- 4004 (ERR_NOT_ENOUGH_MEMORY): メモリ不足により操作が失敗。
- 5401 (ERR_CALENDAR_TIMEOUT): リクエストが制限時間を超過。
- 5400 (ERR_CALENDAR_MORE_DATA): 配列サイズが不十分で、すべてのデータを格納できなかった場合。
戻り値を適切に確認し、falseが返された場合にはエラーコードを取得して原因を調査することが重要です。また、values配列のサイズが不十分な場合には、ArrayResize関数を使用してサイズを調整する必要があります。
CalendarValueHistoryByEvent関数を使う際の注意点
。
時間の基準について
この関数で使用されるすべての時刻は、取引サーバー時間帯に基づいています。つまり、指定する日時（dateTime型）や取得されるデータの時刻は、取引サーバー時間を基準にしているため、現地時間とは異なる可能性があります。
値の取り扱い
取得されるデータは、MqlCalendarValue構造体に格納されます。この構造体には、以下のような値が含まれます。
- 実際の値（actual_value）
- 予測値（forecast_value）
- 前回値（prev_value）
- 修正された前回値（revised_prev_value）
これらの値は、100万倍された状態で格納されています。実際の値を使用する際には、100万で割る必要があります。例えば、3750000という値は、3.75を意味します。
また、値が設定されていない場合、これらのフィールドには非常に小さい値（-9223372036854775808）が格納されます。この値が含まれている場合は、データが存在しないことを意味します。
配列サイズの管理
取得したデータは配列に格納されます。この配列のサイズが小さい場合、一部のデータが失われる可能性があります。このような状況が発生すると、エラーコード5400（ERR_CALENDAR_MORE_DATA）が返されます。その場合は、ArrayResize関数を使用して配列のサイズを大きくする必要があります。
エラーの確認
関数がfalseを返した場合、失敗の原因を調べるために、GetLastError関数を使用してエラーコードを取得することが必要です。たとえば、サーバの応答が遅れた場合は5401（ERR_CALENDAR_TIMEOUT）が返されます。
注意点を守ることで、この関数を正確に使い、データ取得時のトラブルを回避することができます。
CalendarValueHistoryByEvent関数を使ったサンプルコード
//+------------------------------------------------------------------+
//| スクリプトプログラム開始関数 |
//+------------------------------------------------------------------+
void OnStart()
{
//--- EUの国コード(ISO 3166-1 Alpha-2)を指定します
string EU_code="EU";
//--- EUイベントを取得するためのMqlCalendarEvent型配列を宣言します
MqlCalendarEvent events[];
//--- CalendarEventByCountry関数を使ってEUイベントを取得します
int events_count = CalendarEventByCountry(EU_code, events);
//--- 取得したEUイベントの数を確認します
if(events_count > 0)
{
//--- イベントの数をログに出力します
PrintFormat("EU events: %d", events_count);
//--- 分析には最初の10件のイベントだけで十分と仮定して配列をリサイズします
ArrayResize(events, 10);
//--- 配列の内容をログに表示します
ArrayPrint(events);
}
//--- 必要なイベントのIDと名前を取得します（例：ECB Interest Rate Decisionイベント）
ulong event_id = events[6].id; // カレンダーで指定した位置のイベントIDを取得します
string event_name = events[6].name; // カレンダーイベントの名前を取得します
PrintFormat("Get values for event_name=%s event_id=%d", event_name, event_id);
//--- イベント値を取得するためのMqlCalendarValue型配列を宣言します
MqlCalendarValue values[];
//--- 取得するイベントの期間を指定します
datetime date_from = 0; // 利用可能な履歴の初めからすべてのイベントを取得します
datetime date_to = D'01.01.2016'; // 2016年以降のイベントを取得します
//--- CalendarValueHistoryByEvent関数を呼び出してイベント値を取得します
if(CalendarValueHistoryByEvent(event_id, values, date_from, date_to))
{
//--- 正常に値を取得できた場合、取得した値の数をログに出力します
PrintFormat("Received values for %s: %d", event_name, ArraySize(values));
//--- 分析には最初の10件だけで十分と仮定して配列をリサイズします
ArrayResize(values, 10);
//--- 配列の内容をログに表示します
ArrayPrint(values);
}
else
{
//--- 値の取得に失敗した場合はエラーメッセージを出力します
PrintFormat("Error! Failed to get values for event_id=%d", event_id);
//--- GetLastError関数を使ってエラーコードを取得し、ログに表示します
PrintFormat("Error code: %d", GetLastError());
}
}
//---
このコードは、MQL5の経済指標カレンダーを利用して、EUに関連するイベントを取得し、その中から特定のイベント（例：ECBの金利決定）について、指定した期間内の値を取得するものです。取得したイベントと値は、ログに出力されます。
EUのイベントリストを取得し、その中から6番目のイベントを選択して、そのイベントのIDを使って期間内の値を取得します。取得が成功すれば、その値がログに出力され、失敗した場合はエラーコードが表示されます。
サンプルコード解説1
void OnStart()
{
//--- EUの国コード(ISO 3166-1 Alpha-2)を指定します
string EU_code="EU";
//--- EUイベントを取得するためのMqlCalendarEvent型配列を宣言します
MqlCalendarEvent events[];
//--- CalendarEventByCountry関数を使ってEUイベントを取得します
int events_count = CalendarEventByCountry(EU_code, events);この部分のコードは、MQL5の経済指標カレンダーを利用して、EUに関連する経済イベントを取得する初期処理を行っています。
国コードの指定
EUに関連するイベントを取得するために、取得対象となる国を指定しています。ISO3166-1 Alpha-2形式で国コードを指定する必要があり、ここではEU（ヨーロッパ連合）のコードを使用しています。
イベント配列の宣言
取得したイベントデータを格納するための配列を宣言しています。この配列は、MqlCalendarEvent構造体型を持ち、各イベントの詳細情報（イベントID、名前、重要度など）を格納するために使用されます。
イベントの取得
ここでは、CalendarEventByCountry関数を使用して、指定した国コード（この場合はEU）に関連するイベントを取得しています。この関数の戻り値は、取得されたイベントの件数です。また、イベントの詳細は配列に格納されます。
このコード部分の役割は、対象とする国に関連するイベント情報を取得し、後続の処理で利用できる形に整えることです。
サンプルコード解説2
//--- 取得したEUイベントの数を確認します
if(events_count > 0)
{
//--- イベントの数をログに出力します
PrintFormat("EU events: %d", events_count);
//--- 分析には最初の10件のイベントだけで十分と仮定して配列をリサイズします
ArrayResize(events, 10);
//--- 配列の内容をログに表示します
ArrayPrint(events);
}このコードは、取得したEUイベントの数が0より多い場合に、イベント数をログに出力し、分析用に最初の10件のイベントのみを表示する部分です。コードの詳細な動作を順を追って説明します。
- EUイベントの数を確認する
最初に、EUイベントの数が0より大きいかを確認しています。この条件を満たす場合、イベントが取得できたことになります。 - イベント数をログに出力する
文字列をフォーマットして出力する関数を使って、取得したEUイベントの数をログに出力しています。この場合、フォーマット指定子「%d」を使用して整数型の値を表示しています。
「%d」はフォーマット指定子の一つで、整数型（int型）の値を10進数の形式で表示する際に使用されます。例えば、イベント数が56の場合、「%d」の部分は「56」と置き換えられ、ログに出力されます。 - 配列のリサイズ
分析に必要なイベントの数は10件と仮定して、配列のサイズを10に変更しています。この操作によって、取得したイベントのうち最初の10件だけが保持され、残りは削除されます。 - 配列の内容をログに表示する
配列の中身を順番に出力してくれる関数を使って、リサイズ後の配列の内容をログに表示しています。この操作によって、最初の10件のEUイベント情報がログに出力されます。
この部分のコードでは、イベント数を確認し、表示するためにフォーマット指定子を使用して、リサイズした配列の内容を別の関数で表示しています。
サンプルコード解説3
//--- 必要なイベントのIDと名前を取得します（例：ECB Interest Rate Decisionイベント）
ulong event_id = events[6].id; // カレンダーで指定した位置のイベントIDを取得します
string event_name = events[6].name; // カレンダーイベントの名前を取得します
PrintFormat("Get values for event_name=%s event_id=%d", event_name, event_id);
//--- イベント値を取得するためのMqlCalendarValue型配列を宣言します
MqlCalendarValue values[];
//--- 取得するイベントの期間を指定します
datetime date_from = 0; // 利用可能な履歴の初めからすべてのイベントを取得します
datetime date_to = D'01.01.2016'; // 2016年以降のイベントを取得しますこの部分のコードは、取得したイベントリストから特定のイベントを選択し、そのイベントの値を取得するための準備を行っています。
必要なイベントのIDと名前を取得する
配列の特定のインデックス位置から、イベントIDとイベント名を取得しています。この例では、イベントリストの6番目（インデックス6）のイベントを指定しています。
イベントIDは、後に値を取得する際に使用される識別子で、イベント名はログやデバッグ出力などで使用されます。
文字列と整数を組み合わせて出力するため、フォーマット指定子を用いて文字列を整形しています。
例えば、イベント名が”ECB Interest Rate Decision”で、イベントIDが999010007の場合、ログには次のようなメッセージが出力されます。
Get values for event_name=ECB Interest Rate Decision event_id=999010007
イベント値を格納する配列を宣言する
イベントの値を格納するために、MqlCalendarValue構造体型の配列を宣言しています。この配列に後で取得したイベント値が格納されます。
イベントの期間を指定する
期間の開始日時（date_from）と終了日時（date_to）を指定しています。
- date_fromには0を指定しているため、取得可能な履歴の最初の日付からイベントを取得します。
- date_toには、2016年1月1日を指定しています。D’01.01.2016’は、日付リテラルを表現する記法で、Dの後にシングルクォートで囲んだ日付を指定します。（日付リテラルとは、特定の日付を直接コードに記述するための表現方法です）
この形式を使用することで、簡潔に特定の日付を設定できます。
例えば、D’01.01.2016’と書くと、dateTime型の値として2016年1月1日が格納されます。この形式は、コードの可読性を高めるためによく使われます。
これにより、取得するデータの期間を柔軟に設定できます。この準備に基づいて、指定期間内のイベント値を後続の処理で取得します。
サンプルコード解説4
//--- CalendarValueHistoryByEvent関数を呼び出してイベント値を取得します
if(CalendarValueHistoryByEvent(event_id, values, date_from, date_to))
{
//--- 正常に値を取得できた場合、取得した値の数をログに出力します
PrintFormat("Received values for %s: %d", event_name, ArraySize(values));
//--- 分析には最初の10件だけで十分と仮定して配列をリサイズします
ArrayResize(values, 10);
//--- 配列の内容をログに表示します
ArrayPrint(values);
}この部分のコードは、CalendarValueHistoryByEvent関数を使ってイベント値を取得し、取得結果を処理する内容です。
CalendarValueHistoryByEvent関数の呼び出し
CalendarValueHistoryByEvent関数を使用して、指定したイベントID、期間、格納先配列を基にイベント値を取得します。この関数は、正常に値を取得できた場合にtrueを返します。
正常に値を取得できた場合の処理
関数の戻り値がtrueの場合、取得したイベント値の数をログに出力します。ここでは、フォーマット指定子「%s」と「%d」を使用して、イベント名（文字列）と値の数（整数）を整形して表示しています。
配列のリサイズ
分析に必要な値は最初の10件だけと仮定し、ArrayResize関数で配列のサイズを10に変更しています。この操作によって、取得したイベント値のうち最初の10件だけを保持し、残りのデータを削除します。
配列の内容をログに表示
最後に、ArrayPrint関数を使って、リサイズ後の配列内容をログに出力します。この関数を利用すると、配列内の各値を確認することができます。これにより、取得したイベント値の詳細な情報をログで確認できます。
サンプルコード解説5
else
{
//--- 値の取得に失敗した場合はエラーメッセージを出力します
PrintFormat("Error! Failed to get values for event_id=%d", event_id);
//--- GetLastError関数を使ってエラーコードを取得し、ログに表示します
PrintFormat("Error code: %d", GetLastError());
}
}
//---
この部分のコードは、CalendarValueHistoryByEvent関数が失敗した場合のエラーハンドリングを行っています。
値の取得に失敗した場合の処理
CalendarValueHistoryByEvent関数がfalseを返した場合、値の取得に失敗したことを意味します。この場合、エラーメッセージをログに出力して、失敗した理由を調査できるようにします。
- エラーメッセージの出力
フォーマット指定子を使用して、失敗したイベントIDを含むメッセージを出力します。この際、整数を出力する指定子を使用して、イベントIDを表示します。 - エラーコードの取得と出力
GetLastError関数を使用して、失敗の原因を表すエラーコードを取得します。このエラーコードは、MQL5で定義されたエラー番号であり、問題の詳細を調査する際に使用されます。その後、取得したエラーコードをログに出力します。
このエラーハンドリング部分により、値の取得が失敗した場合でも、その原因を調査して適切な対応を行うことができます。特に、ログに出力されたエラーコードを基にデバッグを進めることが可能です。
CalendarValueHistoryByEvent関数を使ってEAを作る際のアイディア
CalendarValueHistoryByEvent関数を利用することで、過去の経済イベントデータを活用したトレーディング戦略を構築することが可能です。以下は、この関数を組み込んだエキスパートアドバイザー（EA）のアイディア例です。
経済イベントを基にしたボラティリティ戦略
過去の経済イベントのデータを分析し、特定のイベント（例：中央銀行の金利決定）後に市場がどのように反応するかを調査します。このデータを利用して、以下のような戦略を実装できます。
- 指定されたイベントの直前にポジションをクローズしてリスクを回避する。
- イベント後にボラティリティが上昇するタイミングを狙ってブレイクアウト戦略を採用する。
イベントデータを使った統計的アプローチ
CalendarValueHistoryByEvent関数で取得した過去のデータを使って、以下のような統計的手法を取り入れることができます。
- イベントの「実際の値」と「予測値」の差が大きい場合の市場の反応を分析し、その差に基づいてトレードを仕掛ける。
- 特定の経済イベントで繰り返し見られるパターンを検出し、そのパターンをトリガーにする。
通貨ペアごとの特定イベントへの反応を分析
経済イベントは通貨ペアによって異なる影響を与えます。例えば、ECBの金利決定がユーロ関連の通貨ペアに与える影響を分析し、そのデータを元に各通貨ペアで異なる戦略を実装できます。
過去のデータを使ったバックテスト
取得したイベントデータを使って、EAの戦略が過去のどのような状況で機能したかをバックテストします。イベント値（実際の値、予測値、前回値など）を参照し、イベント発生後の価格変動を再現することで、戦略の有効性を確認できます。
定期的なレポート生成
関数で取得した過去データを集計して、トレーダーが確認できる定期的なレポートを生成する機能を追加します。例えば、月ごとの主要イベントとその影響を一覧化したレポートを作成することで、トレーダーの意思決定を支援します。
CalendarValueHistoryByEvent関数をEAに活用することで、経済イベントに基づいた多様なトレーディング戦略を構築し、市場の動きに柔軟に対応できるようになります。
