【MQL5】ChartSetSymbolPeriod関数について

ChartSetSymbolPeriod関数の働き・役割
ChartSetSymbolPeriod関数の引数について
ChartSetSymbolPeriod関数の戻り値について
1. 成功時
2. 失敗時
ChartSetSymbolPeriod関数を使う際の注意点
ChartSetSymbolPeriod関数を使ったサンプルコード
サンプルコードに使われた関数や文法要素の簡単な解説

ChartSetSymbolPeriod関数の働き・役割

ChartSetSymbolPeriod関数は、指定されたチャートの銘柄値と期間を変更します。この関数は非同期的に動作し、コマンドを送信後に実行完了を待たずに、チャートメッセージキューに追加されます。

これにより、チャートに取り付けられたエキスパートアドバイザーの再初期化やインジケータの再計算が行われます。同じシンボルと時間枠で呼び出された場合は、チャートの更新として機能し、ティックがない場合でもチャート上のインジケータを計算できます。

ChartSetSymbolPeriod関数の引数について

bool ChartSetSymbolPeriod(
  long            chart_id,    // チャート識別子
  string          symbol,      // 銘柄名
  ENUM_TIMEFRAMES period       // 期間
);

引数1: chart_id

種類: long
説明: チャートの識別子を指定します。0を指定すると現在のチャートを意味します。他の値を使用することで特定のチャートを指定できます。

引数2: symbol

種類: string
説明: チャートシンボルを指定します。NULLを指定するとエキスパートアドバイザーが接続されている現在のチャートのシンボルを意味します。

引数3: period

種類: ENUM_TIMEFRAMES
説明: チャートの期間（時間軸）を指定します。ENUM_TIMEFRAMESのいずれかの値を使用します。0を指定すると現在のチャート期間を意味します。

ChartSetSymbolPeriod関数の戻り値について

ChartSetSymbolPeriod関数は、コマンドがチャートキューに追加されたかどうかを示すブール値を返します。戻り値の詳細は以下の通りです。

成功時

種類: bool
説明: コマンドがチャートキューに追加された場合はtrueを返します。これにより、指定された銘柄値と期間が変更される予定であることを示します。

失敗時

種類: bool
説明: コマンドがチャートキューに追加されなかった場合はfalseを返します。この場合、エラー情報を取得するためにはGetLastError関数を使用します。例えば、無効なチャート識別子やシンボルが指定された場合などが考えられます。

ChartSetSymbolPeriod関数を使う際の注意点

ChartSetSymbolPeriod関数は非同期的に動作し、コマンドがチャートメッセージキューに追加されます。そのため、コマンドの実行完了を待つ必要はありませんが、以前の全てのコマンドの処理後に実行されることを理解しておく必要があります。

銘柄や期間の変更は、チャートに取り付けられたエキスパートアドバイザーの再初期化を引き起こします。これにより、エキスパートアドバイザーが再度開始されるため、注意が必要です。

同じシンボルと時間枠でChartSetSymbolPeriod関数を呼び出すと、チャートの更新として機能します。これにより、チャート上のインジケータの再計算が行われます。ティックがない場合でも、例えば週末にインジケータを計算することができます。

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

以下に、ChartSetSymbolPeriod関数を使用してチャートの銘柄値と期間を変更するサンプルコードを示します。

//+------------------------------------------------------------------+
//| スクリプトプログラムを開始する関数                              |
//+------------------------------------------------------------------+
void OnStart()
{
  //--- 現在のチャートの識別子を取得
  long chart_id = 0; // 現在のチャートを指定
  
  //--- 新しい銘柄と期間を設定
  string new_symbol = "EURUSD"; // 新しい銘柄名
  ENUM_TIMEFRAMES new_period = PERIOD_H1; // 新しい期間（1時間足）
  
  //--- ChartSetSymbolPeriod関数を使用してチャートの銘柄値と期間を変更
  bool result = ChartSetSymbolPeriod(chart_id, new_symbol, new_period);
  
  //--- 結果をログに出力
  if (result)
  {
    Print("ChartSetSymbolPeriod succeeded: ", new_symbol, " on ", EnumToString(new_period));
  }
  else
  {
    Print("ChartSetSymbolPeriod failed. Error code: ", GetLastError());
  }
}

サンプルコードに使われた関数や文法要素の簡単な解説

OnStart関数

OnStart関数は、スクリプトの実行が開始されたときに自動的に呼び出される関数です。この関数内でスクリプトのメインロジックを実装します。

ローカル変数

chart_id: 現在のチャートを示す識別子です。このサンプルコードでは、現在のチャートを指定するために0が設定されています。
new_symbol: 新しい銘柄名を格納する変数です。このサンプルコードでは、”EURUSD”に設定されています。
new_period: 新しいチャートの期間（時間軸）を格納する変数です。このサンプルコードでは、1時間足（PERIOD_H1）に設定されています。

ChartSetSymbolPeriod関数

ChartSetSymbolPeriod関数は、指定されたチャートの銘柄値と期間を変更します。このサンプルコードでは、現在のチャート（chart_id = 0）に対して、新しい銘柄（EURUSD）と新しい期間（1時間足）を設定しています。

bool result = ChartSetSymbolPeriod(chart_id, new_symbol, new_period);

ChartSetSymbolPeriod関数を呼び出し、その結果をブール型変数resultに格納します。関数が正常に実行され、コマンドがチャートメッセージキューに追加された場合、resultはtrueになります。そうでない場合、resultはfalseになります。

EnumToString関数

EnumToString関数は、ENUM_TIMEFRAMES型の値を文字列に変換します。これにより、new_periodの値を文字列形式でログに出力することができます。

if文とelse文

if (result): ChartSetSymbolPeriod関数の実行結果がtrueの場合に実行されるブロックです。成功メッセージをログに出力します。
else: ChartSetSymbolPeriod関数の実行結果がfalseの場合に実行されるブロックです。エラーメッセージとエラーコードをログに出力します。

Print関数

Print関数は、指定されたメッセージをエキスパートログに出力します。このサンプルコードでは、ChartSetSymbolPeriod関数の実行結果をログに出力しています。成功した場合は”ChartSetSymbolPeriod succeeded”、失敗した場合は”ChartSetSymbolPeriod failed”というメッセージを出力します。