【MQL5】FrameAdd関数について

FrameAdd関数の働き・役割
FrameAdd関数の引数について
1. 書式1：ファイルからのデータ追加
2. 書式2：任意型の配列からのデータ追加
FrameAdd関数の戻り値について
FrameAdd関数を使ったサンプルコード
サンプルコードの解説

FrameAdd関数の働き・役割

FrameAdd関数は、指定されたデータをフレームに追加するために使用されます。この関数はバックテストやシグナル分析などで生成されたデータを記録し、後で集計やフィルタリングを行う際に便利です。また、FrameAdd関数には2つのバージョンがあり、それぞれ異なるデータソースからフレームにデータを追加することができます。

1つ目のバージョンはファイルからのデータ追加を行い、指定されたファイル内のデータをフレームに格納します。
2つ目のバージョンは任意の型の配列からのデータ追加をサポートし、配列内のデータを直接フレームに保存します。いずれの場合も、フレームには指定されたラベル（name）と識別子（id）が付加され、FrameFilter関数によってフィルタリングする際に活用できます。

FrameAdd関数の引数について

FrameAdd関数には2つの書式が存在し、それぞれ異なるデータソースからフレームにデータを追加します。以下、それぞれの書式について引数の構成を説明します。

書式1：ファイルからのデータ追加

bool FrameAdd(
  const string  name,        // Public 名称・レベル
  long          id,          // パブリック ID
  double        value,       // 値
  const string  filename     // データファイル名
);

nameはPublicフレームラベルで、FrameFilter関数によるフィルタリングに使用されます。このラベルはデータの識別情報として役立ちます。

idはパブリックIDで、特定のフレームを識別するための番号です。FrameFilter関数でデータを抽出する際に活用できます。

valueはフレームに追加する数値で、例えばOnTester関数を通じて送信される評価値や計測値などを指定します。

filenameはフレームに追加するデータを含むファイルの名称で、MQL5ディレクトリのFilesフォルダ内に保存されている必要があります。このファイルの内容をフレームに読み込み、データとして使用します。

書式2：任意型の配列からのデータ追加

bool FrameAdd(
  const string  name,        // Public 名称・レベル
  long          id,          // パブリック ID
  double        value,       // 値
  const void&   data[]       // 任意型の配列
);

nameは書式1と同様に、Publicフレームラベルで、FrameFilter関数でのフィルタリングに使用されます。データ識別用の情報として指定します。

idはパブリックIDで、フレームの識別子として活用されますFrameFilter関数を使用して特定のデータを抽出する際に使用できます。

valueはフレームに記録する数値で、テスト結果や評価指標などの数値データをフレームに追加するために用いられます。

dataはフレームに追加する任意型の配列です。この配列は参照で渡され、フレームに記録されるデータの内容を構成します。配列には、構造体や複数の値を含むデータを指定できます。

どちらの書式も処理が成功した場合にはtrueを、失敗した場合にはfalseを返します。エラーが発生した場合には、GetLastError関数を使用してエラー情報を確認することができます。

FrameAdd関数の戻り値について

FrameAdd関数は、指定されたデータのフレーム追加処理が成功したかどうかを示す真偽値を返します。

成功した場合はtrueを返します。これにより、データが正しくフレームに追加されたことが確認できます。
失敗した場合はfalseを返します。エラーが発生した場合、追加に失敗した理由を把握するために、GetLastError関数を用いるとエラーコードが取得できます。

falseが返された際の典型的な理由として、指定されたファイルが見つからない、データの形式が一致しない、または書き込みアクセス権がない場合などが考えられます。

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

以下は、FrameAdd関数を使用して、ファイルからのデータおよび配列からのデータをフレームに追加するサンプルコードです。それぞれの書式について詳細な日本語コメントを付与しています。

// サンプルコード：FrameAdd関数でファイルからのデータをフレームに追加する場合

void OnStart()
{
    // フレームに使用する識別ラベルを指定
    string frameLabel = "TestFrame";  // フレームラベルとして使用する名前

    // フレームの識別子としてIDを設定
    long frameID = 1001;  // フレーム識別用のID番号

    // フレームに追加する評価値
    double value = 99.9;  // フレームに保存する評価指標の値

    // 追加するデータを格納するファイル名を指定
    string filename = "testdata.csv";  // MQL5/Filesディレクトリ内に配置されたファイル名

    // FrameAdd関数を使用してファイルのデータをフレームに追加
    bool result = FrameAdd(frameLabel, frameID, value, filename);

    // 関数の実行結果を確認し、エキスパートログにメッセージを出力
    if(result)
    {
        // 成功時のメッセージをエキスパートログに出力
        Print("データがフレームに正常に追加されました。");
    }
    else
    {
        // 失敗時のエラーメッセージをエキスパートログに出力し、エラー情報を取得
        Print("データの追加に失敗しました。エラーコード: ", GetLastError());
    }
}

// サンプルコード：FrameAdd関数で任意型の配列からのデータをフレームに追加する場合

void OnStart()
{
    // フレームに使用する識別ラベルを指定
    string frameLabel = "ArrayFrame";  // フレームの識別ラベル名

    // フレームの識別子としてIDを設定
    long frameID = 2002;  // フレーム識別用のID番号

    // フレームに追加する評価値
    double value = 75.5;  // フレームに保存する評価指標の値

    // 任意型の配列を作成し、フレームに追加するデータを格納
    int dataArray[] = {1, 2, 3, 4, 5};  // 追加する任意型の配列（整数型の例）

    // FrameAdd関数を使用して配列のデータをフレームに追加
    bool result = FrameAdd(frameLabel, frameID, value, dataArray);

    // 関数の実行結果を確認し、エキスパートログにメッセージを出力
    if(result)
    {
        // 成功時のメッセージをエキスパートログに出力
        Print("配列データがフレームに正常に追加されました。");
    }
    else
    {
        // 失敗時のエラーメッセージをエキスパートログに出力し、エラー情報を取得
        Print("配列データの追加に失敗しました。エラーコード: ", GetLastError());
    }
}