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());
}
}
サンプルコードの解説
OnStart関数はスクリプトが実行されると最初に呼び出される関数です。ここでFrameAdd関数を利用しています。
frameLabelはフレームの識別ラベルです。これは、FrameFilter関数でフィルタリングする際に使用できます。
frameIDはフレームの識別IDで、データの識別情報として活用されます。
valueは評価値や数値データであり、フレームに保存するための数値としてFrameAdd関数に渡されます。
filename(ファイル名)とdataArray(配列)はそれぞれ異なるデータソースからフレームにデータを追加するために使用されます。
resultはFrameAdd関数の戻り値を格納し、追加処理が成功したかどうかを確認するための真偽値です。結果に応じてエキスパートログにメッセージを出力し、失敗時にはGetLastError関数でエラーコードを確認します。