【MQL5】CalendarCountryById関数について

CalendarCountryById関数の働き・役割
CalendarCountryById関数の引数について
MqlCalendarCountry構造体について
CalendarCountryById関数の戻り値について
CalendarCountryById関数を使ったサンプルコード
サンプルコード解説１
サンプルコード解説2
サンプルコード解説3
CalendarCountryById関数を使ってEAを作る際のアイディア

CalendarCountryById関数の働き・役割

CalendarCountryById関数は、指定された国のIDを使って、その国に関する詳細な情報を取得するための関数です。国のIDはISO3166-1形式で指定され、これは国や地域を表すための標準化されたコードを指します。このISO3166-1形式は、たとえば「US」（アメリカ合衆国）や「JP」（日本）など、国ごとに固有のコードが割り当てられています。

この関数を利用することで、国の名前やコード、通貨、通貨のシンボル、さらに関連するウェブリンク名などの情報を簡単に取得することができます。たとえば、経済指標カレンダーを作成する際に、この関数で国ごとの情報を取得し、ユーザーに分かりやすく表示することが可能です。

CalendarCountryById関数の引数について

bool  CalendarCountryById(
  const long          country_id,    // 国ID
  MqlCalendarCountry&  country       // 国の説明を受け取るための配列
  );

CalendarCountryById関数には、国IDと国の説明を受け取るための変数が引数として指定されます。それぞれの引数の詳細は次の通りです。

第1引数
country_id
この引数には、ISO3166-1形式の国IDを指定します。この形式は、各国や地域に固有の2文字または3文字のコードです。例えば、日本は「JP」、アメリカは「US」として定義されています。このIDを使うことで、関数は指定された国の情報を取得します。

第2引数
country
この引数には、MqlCalendarCountry構造体型の変数を指定し、取得した国の説明情報をこの変数に格納します。取得される情報には、国の名前、コード、通貨、通貨シンボル、URL名などの項目が含まれます。この引数は、関数の実行後に国の説明が格納されるため、変数として準備しておきます。

MqlCalendarCountry構造体について

MqlCalendarCountry構造体は、CalendarCountryById関数を使用して取得できる国の詳細情報をまとめるための構造体です。この構造体には、国に関する様々な情報が含まれており、それぞれのメンバを利用して国の特性を把握することができます。以下に、各メンバの説明を解説します。

id

このメンバは、国を識別するためのIDで、ISO3166-1形式の番号です。

ISO 3166-1とは

ISO3166-1とは、国や地域を特定するための国際標準コードの一つです。このIDを利用することで、他の情報と区別して国を指定することができます。

name

このメンバは、その国の名前を示します。たとえば、「Japan」や「United States」など、国の正式な名称がターミナルのエンコーディングに合わせて表示されます。このnameメンバを使用すれば、ユーザーが理解しやすい形で国名を表示することが可能です。

code

このメンバには、ISO3166-1 alpha-2形式の国コードが入ります。この形式は、国や地域を2文字で表したコードで、日本なら「JP」、アメリカなら「US」といった具合に、短いコードで国を識別することができます。

currency

このメンバには、該当する国の通貨コードが格納されます。通貨コードは、国際的に定められた3文字のアルファベットで、日本円なら「JPY」、アメリカドルなら「USD」のように表されます。この情報を活用することで、各国の通貨に関するデータを扱うことができます。

currency_symbol

このメンバは、国の通貨シンボルを表しています。たとえば、日本円のシンボルは「¥」、アメリカドルのシンボルは「$」です。このcurrency_symbolを利用することで、金額表示の際にシンボルをつけてわかりやすく表示することが可能です。

url_name

このメンバには、mql5.comのウェブサイトURLで使用される国名が格納されています。例えば、EU（欧州連合）の場合、「european-union」のようにURLに使いやすい形で名前が設定されています。ウェブサイト上でのリンク作成や、特定の国に関するページを参照する際に便利な情報です。

CalendarCountryById関数の戻り値について

CalendarCountryById関数の戻り値は、処理が成功したかどうかを示す論理値です。この関数が成功した場合は「true」を返し、指定された国IDに対応する国の情報が取得され、MqlCalendarCountry構造体に格納されます。反対に、処理が失敗した場合には「false」を返します。

処理が失敗するケースとしては、無効な国IDが指定された場合やリクエストの制限時間が超過した場合などが考えられます。失敗した場合の詳細なエラー情報はGetLastError関数を使って取得することができます。

以下は、考えられるエラーとそのコードです：

エラーコード 4001: ERR_INTERNAL_ERROR
一般的なランタイムエラーが発生したことを意味します。
エラーコード 5402: ERR_CALENDAR_NO_DATA
無効な国IDが指定された場合に発生します。指定した国IDに対応する国の情報が存在しない場合です。
エラーコード 5401: ERR_CALENDAR_TIMEOUT
リクエストの処理が制限時間を超えた場合に発生します。

CalendarCountryById関数を使ったサンプルコード

//+------------------------------------------------------------------+
//| スクリプトプログラム開始関数                                     |
//+------------------------------------------------------------------+
void OnStart()
 {
  //--- 経済指標カレンダーから国のリストを取得するための配列を宣言する
  MqlCalendarCountry countries[];
  
  //--- CalendarCountries関数を使って国のリストを取得し、結果をcountに格納する
  int count = CalendarCountries(countries);

  //--- 国のリスト取得結果を確認する
  // countが0の場合、リストが取得できなかったと判断し、エラー内容を表示する
  if(count == 0)
    PrintFormat("CalendarCountries() returned 0! Error: %d", GetLastError());

  //--- 国が2つ以上存在する場合に処理を続ける
  if(count >= 2)
    {
    //--- MqlCalendarCountry型の変数countryを宣言して、特定の国の情報を格納する準備をする
    MqlCalendarCountry country;
    
    //--- CalendarCountryById関数を使って、特定の国IDに基づく国の情報を取得する
    // countries[1].id はリスト内の2番目の国のIDを示している
    if(CalendarCountryById(countries[1].id, country))
       {
        //--- 国の説明を文字列として準備する
        // IntegerToString関数を使ってIDを文字列に変換し、情報を順に追加していく
        string descr = "id = " + IntegerToString(country.id) + "\n";
        descr += ("name = " + country.name + "\n");            // 国の名前
        descr += ("code = " + country.code + "\n");            // 国のコード
        descr += ("currency = " + country.currency + "\n");    // 国の通貨コード
        descr += ("currency_symbol = " + country.currency_symbol + "\n"); // 通貨のシンボル
        descr += ("url_name = " + country.url_name);           // ウェブサイトURLに使用される国名
        
        //--- 準備した国の説明をエキスパートログに表示する
        Print(descr);
       }
    else
       //--- CalendarCountryById関数が失敗した場合、エラー内容をエキスパートログに表示する
       Print("CalendarCountryById() failed. Error: ", GetLastError());
    }
  //--- 以上でスクリプトの処理を終了
 }
 /*
  実行結果の例:
  id = 999
  name = European Union
  code = EU
  currency = EUR
  currency_symbol = €
  url_name = european-union
 */

このコードは、経済指標カレンダーから国情報を取得し、特定の国の詳細を表示します。

まず、国の一覧を取得し、2つ以上の国が存在する場合は、そのうち2番目の国の情報を「IDで指定して」取得します。そして、その国の名前や通貨コード、通貨のシンボル、ウェブサイトURLなどの情報をエキスパートログに出力します。

もし情報取得が失敗した場合は、エラーメッセージをエキスパートログに表示します。

サンプルコード解説１

//+------------------------------------------------------------------+
//| スクリプトプログラム開始関数                                     |
//+------------------------------------------------------------------+
void OnStart()
 {
  //--- 経済指標カレンダーから国のリストを取得するための配列を宣言する
  MqlCalendarCountry countries[];
  
  //--- CalendarCountries関数を使って国のリストを取得し、結果をcountに格納する
  int count = CalendarCountries(countries);

このセクションでは、OnStart関数の冒頭部分について詳しく解説します。

OnStart関数の開始部分

OnStart関数は、スクリプトで実行が開始されると自動的に呼び出されるメインの関数です。この関数内にコードを記述することで、スクリプトの動作を制御します。以下のコードは、経済指標カレンダーから国のリストを取得する準備を行っています。

MqlCalendarCountry型配列 countries の宣言

MqlCalendarCountry構造体型の配列countries を宣言しています。この配列は、後ほど CalendarCountries関数を使って取得する国情報を格納するためのものです。MqlCalendarCountry構造体は、国に関する情報を保持するための構造体で、国名や国コード、通貨コードなどが格納されます。

CalendarCountries関数で国リストを取得

次に、CalendarCountries関数を呼び出し、経済指標カレンダーから利用可能な国の一覧を取得しています。この関数は、countries配列に国情報を格納し、配列に格納された国の数を整数として返します。この結果を count 変数に代入することで、取得した国の総数を後で確認できるようにしています。

以上のコードは、次の処理に備えて、国のリストを取得するための準備を整える役割を果たしています。

サンプルコード解説2

  //--- 国のリスト取得結果を確認する
  // countが0の場合、リストが取得できなかったと判断し、エラー内容を表示する
  if(count == 0)
    PrintFormat("CalendarCountries() returned 0! Error: %d", GetLastError());

  //--- 国が2つ以上存在する場合に処理を続ける
  if(count >= 2)
    {
    //--- MqlCalendarCountry型の変数countryを宣言して、特定の国の情報を格納する準備をする
    MqlCalendarCountry country;

このセクションでは、取得した国のリストの結果を確認し、特定の条件に応じた処理を行うコード部分について解説します。

国のリスト取得結果を確認

まず、国のリスト取得結果が0であるかどうかを確認します。countが0の場合、国のリストが取得できなかったことを意味します。そのため、エラー内容を確認するために、PrintFormat関数とGetLastError関数を使用し、エラーコードをエキスパートログに出力しています。

国が2つ以上存在する場合の処理

次に、取得した国の数が2つ以上であることを確認します。この条件を満たす場合にのみ、後続の処理を続けます。countが2以上であることは、少なくとも2つ以上の国のデータが取得できていることを意味します。

MqlCalendarCountry型変数 country の宣言

次に、MqlCalendarCountry構造体型のインスタンスcountry を宣言しています。このインスタンスは、特定の国IDを基に取得した国の詳細情報を格納するためのものです。

サンプルコード解説3

//--- CalendarCountryById関数を使って、特定の国IDに基づく国の情報を取得する
    // countries[1].id はリスト内の2番目の国のIDを示している
    if(CalendarCountryById(countries[1].id, country))
       {
        //--- 国の説明を文字列として準備する
        // IntegerToString関数を使ってIDを文字列に変換し、情報を順に追加していく
        string descr = "id = " + IntegerToString(country.id) + "\n";
        descr += ("name = " + country.name + "\n");            // 国の名前
        descr += ("code = " + country.code + "\n");            // 国のコード
        descr += ("currency = " + country.currency + "\n");    // 国の通貨コード
        descr += ("currency_symbol = " + country.currency_symbol + "\n"); // 通貨のシンボル
        descr += ("url_name = " + country.url_name);           // ウェブサイトURLに使用される国名
        
        //--- 準備した国の説明をエキスパートログに表示する
        Print(descr);
       }
    else
       //--- CalendarCountryById関数が失敗した場合、エラー内容をエキスパートログに表示する
       Print("CalendarCountryById() failed. Error: ", GetLastError());
    }
  //--- 以上でスクリプトの処理を終了
 }
 /*
  実行結果の例:
  id = 999
  name = European Union
  code = EU
  currency = EUR
  currency_symbol = €
  url_name = european-union
 */

ここでは、CalendarCountryById関数を使って取得した国の情報をエキスパートログに表示する部分について、使用されている文法や関数、countryのメンバ呼び出しの文法についても解説します。

CalendarCountryById関数で特定の国情報を取得

まず、CalendarCountryById関数を使って、特定の国IDに基づいた国情報を取得します。countries[1].idはリスト内の2番目の国のIDを示しています。

CalendarCountryById関数は、このIDに基づいて該当する国の詳細情報をMqlCalendarCountry構造体のインスタンスであるcountryに格納します。情報の取得に成功すると、次のステップでこの情報を整えて出力します。

情報を文字列として準備する

取得した国の情報を見やすい形式に整え、descrという名前の文字列に格納していきます。この部分で使われている文法要素について解説します。

IntegerToString関数

まず、国ID（数値データ）を文字列に変換するために、IntegerToString関数が使われています。国IDは数値のため、文字列として他の情報と一緒に表示するには変換が必要です。この関数を使うことで、数値を簡単に文字列に変えることができます。

改行文字「\n」

各情報の最後に「\n」という文字が追加されています。これは改行文字と呼ばれ、ログに出力される際に次の行に改行するために使用されます。これによって、IDや名前、コードなどの情報が別々の行に表示され、見やすく整えられます。

複合代入演算子「+=」

descrには最初に国IDを格納し、その後「+=」という記号を使って他の情報を順番に追加していきます。この「+=」は、現在の内容に新しい文字列を追加するための「複合代入演算子」と呼ばれるものです。これを使うことで、descrという文字列に次々と情報を追加できます。

MqlCalendarCountry構造体のインスタンス country からのメンバ呼び出し

MqlCalendarCountry構造体のインスタンスであるcountryから、各メンバの情報（id、name、code、currency、currency_symbol、url_name）が呼び出されています。

ここでの「country.id」や「country.name」のような表記は、インスタンスcountryが持っている各メンバを示すための文法です。具体的には、以下のようにしてメンバが呼び出されます。

MqlCalendarCountry構造体に定義されたメンバには、それぞれ国ID、国名、国コード、通貨コード、通貨シンボル、ウェブサイト用のURL名が含まれます。
MqlCalendarCountry構造体のインスタンスcountryにドット「.」を使ってメンバを指定することで、そのインスタンス内のデータ（この場合は特定の国の情報）を呼び出すことができます。
たとえば、country.nameとすると、MqlCalendarCountry構造体のnameメンバに格納された国名データが呼び出されます。

これによって、MqlCalendarCountry構造体のインスタンスから必要な情報を取り出し、各情報を適切に表示することが可能になります。

Print関数で情報をエキスパートログに表示

最後に、準備したdescrをPrint関数を使ってエキスパートログに表示します。Print関数は、指定した内容をエキスパートログに出力するための関数で、ログに出力された内容を確認できるようにするために使われます。

CalendarCountryById関数が失敗した場合の処理

もしCalendarCountryById関数が失敗した場合には、else文内でGetLastError関数を使ってエラーコードを取得し、Print関数でエラー内容を表示します。エラーコードを確認することで、なぜ取得に失敗したかを把握することができます。

CalendarCountryById関数を使ってEAを作る際のアイディア

CalendarCountryById関数を活用することで、特定の国に関する経済情報をEA内で柔軟に扱うことが可能になります。以下に、CalendarCountryById関数を用いたエキスパートアドバイザー（EA）作成のアイディアをいくつか紹介します。

特定の国に基づいたニュース連動型の取引戦略

CalendarCountryById関数を用いて特定の国のIDを取得し、その国の経済ニュースに連動する取引戦略を構築できます。たとえば、米国や欧州連合（EU）に関連するニュースが発表されたタイミングで自動的にポジションを調整する機能をEAに追加することができます。主要経済圏に関連するイベントに素早く反応できるため、イベントドリブンの取引を行いたい場合に有用です。

各国の通貨を考慮したリスク管理の強化

CalendarCountryById関数で取得した国の通貨情報を活用して、取引リスクを管理するEAを作成できます。例えば、リスクの高いイベントが予想される国に関連する通貨ペアでの取引を控えたり、取引量を減らす設定を行うことができます。これにより、特定の通貨に関連するリスクを自動で調整することが可能になります。

国別情報によるポートフォリオの分散管理

CalendarCountryById関数を使用して、特定の国に関連する取引のみをピックアップし、ポートフォリオの分散管理に役立てるEAを構築することもできます。たとえば、経済状況が異なる複数の国に分散して取引を行うことで、特定の地域や経済圏に依存しすぎないポートフォリオを形成するサポートが可能です。

ダッシュボードでの国情報表示

CalendarCountryById関数を使って取得した国情報を、視覚的に表示するダッシュボード機能を備えたEAを開発することもできます。たとえば、トレード画面上にその国の通貨や経済状況などの情報を表示し、トレーダーがリアルタイムで参考にできるようにすることが可能です。これにより、各国ごとの経済状況を把握しながら柔軟な取引判断を行うことができます。