【MQL5】SeriesInfoInteger関数について

スポンサーリンク

SeriesInfoInteger関数の働き・役割

SeriesInfoInteger関数は、指定された銘柄と期間の履歴データに関する状態情報を取得するために使用されます。

この関数は、プロパティ値を直接返す形式と、プロパティ値を変数に格納する形式の2つの呼び出し方があります。これにより、履歴データの状態や特定のプロパティに関する詳細情報を取得することができます。例えば、バーの総数、最初の日付、サーバ上の最初の日付、データの同期状態などの情報を取得することができます。

SeriesInfoInteger関数の引数について

SeriesInfoInteger関数の引数は以下の通りです。この関数は2つの書式を持つオーバーロード関数です。

書式1

long  SeriesInfoInteger(
  string                    symbol_name,    // 銘柄名
  ENUM_TIMEFRAMES            timeframe,      // 期間
  ENUM_SERIES_INFO_INTEGER  prop_id,        // プロパティ識別子
  );

symbol_name

銘柄名を指定します。例えば、”EURUSD”や”GBPJPY”などのシンボル（特定の文字や記号）を指定します。

timeframe

時間枠を指定します。ENUM_TIMEFRAMES列挙型を使用し、M1（1分足）やD1（日足）などの期間を指定します。

prop_id

リクエストされたプロパティの識別子を指定します。ENUM_SERIES_INFO_INTEGER列挙型の値を使用します。

書式2

bool  SeriesInfoInteger(
  string                    symbol_name,    // 銘柄名
  ENUM_TIMEFRAMES            timeframe,      // 期間
  ENUM_SERIES_INFO_INTEGER  prop_id,        // プロパティ識別子
  long&                      long_var        // 情報を受け取る変数
  );

symbol_name

銘柄名を指定します。書式1と同様にシンボルを指定します。

timeframe

時間枠を指定します。書式1と同様にENUM_TIMEFRAMES列挙型を使用します。

prop_id

リクエストされたプロパティの識別子を指定します。書式1と同様にENUM_SERIES_INFO_INTEGER列挙型の値を使用します。

long_var

リクエストされたプロパティの値が格納される変数です。この変数にプロパティの値が配置されます。

ENUM_SERIES_INFO_INTEGERについて

ENUM_SERIES_INFO_INTEGERとは、SeriesInfoInteger関数で使用されるプロパティ識別子の列挙型です。この識別子を使用して、指定された銘柄と期間の履歴データに関する特定の情報を取得します。

SERIES_BARS_COUNT

SERIES_BARS_COUNTは、現在のシンボル期間におけるバーの総数を取得するための識別子です。この識別子を使用することで、指定した銘柄と時間枠に存在する全てのバーの数を確認することができます。戻り値はlong型です。例えば、過去のデータを分析する際に、この識別子を用いることでどれだけのバーが存在するかを把握することができます。

SERIES_FIRSTDATE

SERIES_FIRSTDATEは、現在のシンボル期間における最初の日付を取得するための識別子です。
この識別子を使用することで、指定した銘柄と時間枠における最初のバーの日付を確認できます。戻り値はdateTime型です。例えば、データの最初の日付を基準に分析を開始する場合に役立ちます。

SERIES_LASTBAR_DATE

SERIES_LASTBAR_DATEは、現在のシンボル期間における最終バーの開始時刻を取得するための識別子です。
この識別子を使用することで、指定した銘柄と時間枠における最新のバーの開始時刻を確認できます。戻り値はdateTime型です。最新データの取得タイミングを確認する際に有用です。

SERIES_SERVER_FIRSTDATE

SERIES_SERVER_FIRSTDATEは、時間軸に関係なく、サーバ上でのシンボル履歴の最初の日付を取得するための識別子です。この識別子を使用することで、指定した銘柄のサーバ上での履歴データがいつから存在するかを確認できます。戻り値はdateTime型です。サーバ上で利用可能な最古のデータの日付を知るために利用します。

SERIES_TERMINAL_FIRSTDATE

SERIES_TERMINAL_FIRSTDATEは、時間軸に関係なく、クライアント端末でのシンボル履歴の最初の日付を取得するための識別子です。この識別子を使用することで、指定した銘柄のクライアント端末上での履歴データがいつから存在するかを確認できます。戻り値はdateTime型です。クライアント端末上で利用可能な最古のデータの日付を知るために利用します。

SERIES_SYNCHRONIZED

SERIES_SYNCHRONIZEDは、現時点での銘柄と期間のデータがサーバと同期されているかどうかを示すフラグを取得するための識別子です。この識別子を使用することで、データが最新の状態に保たれているかを確認できます。戻り値はbool型で、同期されている場合はtrue、そうでない場合はfalseを返します。データの信頼性を確認する際に重要です。

SeriesInfoInteger関数の戻り値について

SeriesInfoInteger関数は、指定されたプロパティの値を取得するために使用されます。関数の戻り値は、呼び出し方によって異なります。

書式1の戻り値

この形式では、関数はリクエストされたプロパティの値を直接返します。戻り値の型はリクエストしたプロパティの種類に依存します。例えば、SERIES_BARS_COUNTの場合はlong型、SERIES_FIRSTDATEの場合はdateTime型です。

書式2の戻り値

この形式では、関数は実行の成功に応じてtrueまたはfalseを返します。指定されたプロパティが利用可能で、その値がlong_var変数に格納された場合はtrue、それ以外の場合はfalseを返します。エラーが発生した場合の詳細はGetLastError関数を使用して取得できます。

戻り値の詳細

• 書式1の例: SERIES_BARS_COUNTを使用すると、指定した銘柄と期間のバーの総数をlong型で返します。
• 書式2の例: SERIES_BARS_COUNTを使用して、成功した場合にtrueを返し、バーの総数をlong_var変数に格納します。

このように、SeriesInfoInteger関数の戻り値は、関数の呼び出し方とリクエストされたプロパティに応じて異なるため、目的に応じた形式を選択して使用します。

SeriesInfoInteger関数を使う際の注意点

プロパティ識別子には必ずENUM_SERIES_INFO_INTEGER列挙型の値を使用する必要があります。これにより、指定されたプロパティに関する正確な情報を取得できます。

リクエストされたプロパティのデータが存在しない場合や、取引サーバと同期されていない場合、関数はゼロまたはfalseを返すことがあります。このため、特定のプロパティ値が取得できない場合には、サーバとのデータ同期を確認する必要があります。

取得したプロパティ値の型に注意が必要です。各プロパティ識別子に対応する戻り値の型を確認し、適切にタイプキャストすることが求められます。例えば、SERIES_FIRSTDATEはdateTime型にタイプキャストする必要があります。

SeriesInfoInteger関数を頻繁に呼び出すとパフォーマンスに影響を与える可能性があるため、必要な情報を一度に取得し、再利用することを検討してください。

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

// OnStart関数はスクリプトの実行が開始されたときに自動的に呼び出されます
void OnStart()
{
    // 銘柄名と期間を指定してバーの総数を取得します
    long bars_count = SeriesInfoInteger(_Symbol, _Period, SERIES_BARS_COUNT);
    // 取得したバーの総数をエキスパートログに出力します
    Print("現在のシンボル-期間のバーの総数: ", bars_count);
    
    // 銘柄名と期間を指定して最初の日付を取得します
    datetime first_date = (datetime)SeriesInfoInteger(_Symbol, _Period, SERIES_FIRSTDATE);
    // 取得した最初の日付をエキスパートログに出力します
    Print("現在のシンボル-期間の最初の日付: ", first_date);
    
    // 銘柄名と期間を指定して最終バーの開始時刻を取得します
    datetime last_bar_date = (datetime)SeriesInfoInteger(_Symbol, _Period, SERIES_LASTBAR_DATE);
    // 取得した最終バーの開始時刻をエキスパートログに出力します
    Print("現在のシンボル-期間の最終バーの開始時刻: ", last_bar_date);
    
    // 銘柄名を指定してサーバ上の履歴の最初の日付を取得します
    datetime server_first_date = (datetime)SeriesInfoInteger(_Symbol, _Period, SERIES_SERVER_FIRSTDATE);
    // 取得したサーバ上の最初の日付をエキスパートログに出力します
    Print("サーバ上のシンボル履歴の最初の日付: ", server_first_date);
    
    // 銘柄名を指定して端末上の履歴の最初の日付を取得します
    datetime terminal_first_date = (datetime)SeriesInfoInteger(_Symbol, _Period, SERIES_TERMINAL_FIRSTDATE);
    // 取得した端末上の最初の日付をエキスパートログに出力します
    Print("端末上のシンボル履歴の最初の日付: ", terminal_first_date);
    
    // 銘柄名と期間を指定してデータの同期状態を取得します
    bool synchronized = (bool)SeriesInfoInteger(_Symbol, _Period, SERIES_SYNCHRONIZED);
    // 取得した同期状態をエキスパートログに出力します
    Print("現在のシンボル-期間のデータ同期状態: ", synchronized);
}

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

バーの総数の取得

この部分では、現在の銘柄と期間のバーの総数を取得しています。SeriesInfoInteger関数に銘柄名、期間、プロパティ識別子としてSERIES_BARS_COUNTを渡すことで、端末に存在する指定銘柄・期間のバーの総数を取得します。取得したバーの総数は、bars_count変数に格納され、その後エキスパートログに出力されます。

最初の日付の取得

この部分では、現在の銘柄と期間の最初の日付を取得しています。SeriesInfoInteger関数に銘柄名、期間、プロパティ識別子としてSERIES_FIRSTDATEを渡すことで、指定した銘柄と期間における最初のバーの日付を取得します。取得した日付はdateTime型にタイプキャストされ、first_date変数に格納されます。その後、エキスパートログに出力されます。

最終バーの開始時刻の取得

この部分では、現在の銘柄と期間の最終バーの開始時刻を取得しています。SeriesInfoInteger関数に銘柄名、期間、プロパティ識別子としてSERIES_LASTBAR_DATEを渡すことで、指定した銘柄と期間の最新バーの開始時刻を取得します。取得した時刻はdateTime型にタイプキャストされ、last_bar_date変数に格納されます。その後、エキスパートログに出力されます。

サーバ上の履歴の最初の日付の取得

この部分では、サーバ上のシンボル履歴の最初の日付を取得しています。SeriesInfoInteger関数に銘柄名、期間、プロパティ識別子としてSERIES_SERVER_FIRSTDATEを渡すことで、サーバに保存されている指定銘柄の最初の日付を取得します。取得した日付はdateTime型にタイプキャストされ、server_first_date変数に格納されます。その後、エキスパートログに出力されます。

端末上の履歴の最初の日付の取得

この部分では、端末上のシンボル履歴の最初の日付を取得しています。SeriesInfoInteger関数に銘柄名、期間、プロパティ識別子としてSERIES_TERMINAL_FIRSTDATEを渡すことで、端末に保存されている指定銘柄の最初の日付を取得します。取得した日付はdateTime型にタイプキャストされ、terminal_first_date変数に格納されます。その後、エキスパートログに出力されます。

データの同期状態の取得

この部分では、現在の銘柄と期間のデータがサーバと同期されているかどうかを確認しています。SeriesInfoInteger関数に銘柄名、期間、プロパティ識別子としてSERIES_SYNCHRONIZEDを渡すことで、指定したデータが同期されているかを示すフラグを取得します。取得したフラグはbool型にタイプキャストされ、synchronized変数に格納されます。その後、エキスパートログに出力されます。

定義済み変数

_Symbolは現在の銘柄名を表し、_Periodは現在の時間枠を表します。これらは定義済み変数であり、スクリプトの実行中に自動的に設定されます。これらを使用することで、現在アクティブな銘柄と時間枠を簡単に参照できます。

タイプキャスト

タイプキャストは、取得した戻り値を適切な型に変換するために使用されます。例えば、SERIES_FIRSTDATEやSERIES_SERVER_FIRSTDATEの戻り値はdateTime型にタイプキャストされ、SERIES_SYNCHRONIZEDの戻り値はbool型にタイプキャストされます。これにより、正しい型でデータを扱うことができます。

このサンプルコードでは、SeriesInfoInteger関数を使用して様々なプロパティの情報を取得し、それらの結果をエキスパートログに出力することで、履歴データの状態を確認しています。