【MQL5】HistoryOrderGetInteger関数について

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

HistoryOrderGetInteger関数の働き・役割

HistoryOrderGetInteger関数は、取引履歴から特定の注文プロパティを取得するために使用されます。この関数は、指定された注文チケットとプロパティ識別子に基づいて、注文のプロパティ値を取得します。プロパティ値は、dateTime型またはint型でなければなりません。

HistoryOrderGetInteger関数には、2つのバージョンがあります。

1つ目のバージョンは、プロパティ値を直接返します。これは、プロパティ値が即座に必要な場合に便利です。

2つ目のバージョンは、関数の実行結果に応じてtrueまたはfalseを返します。関数が成功した場合、プロパティ値は参照渡しされた変数に格納されます。このバージョンは、関数の実行結果を確認しながらプロパティ値を取得する場合に使用されます。

HistoryOrderGetInteger関数の引数について

HistoryOrderGetInteger関数の引数構成は以下の通りです。この関数は複数の書式を持つオーバーロード関数です。

書式1

long  HistoryOrderGetInteger(
  ulong                        ticket_number,    // チケット
  ENUM_ORDER_PROPERTY_INTEGER  property_id        // プロパティ識別子
  );

ticket_numberは注文チケットを示します。これは、取引履歴から特定の注文を識別するために使用されます。

property_idは注文プロパティの識別子です。これは、ENUM_ORDER_PROPERTY_INTEGER列挙のいずれかの値を使用します。この識別子により、取得したい注文プロパティが特定されます。

※ENUM_ORDER_PROPERTY_INTEGERについての詳細は↓の記事をご参照ください。

書式2

bool  HistoryOrderGetInteger(
  ulong                        ticket_number,    // チケット
  ENUM_ORDER_PROPERTY_INTEGER  property_id,       // プロパティ識別子
  long&                        long_var          // プロパティ値を受け取る
  );

ticket_numberとproperty_idは書式1と同様です。

long_varは、プロパティ値を受け取るための変数です。この変数には、関数の実行が成功した場合に、指定されたプロパティの値が格納されます。

HistoryOrderGetInteger関数の戻り値について

HistoryOrderGetInteger関数は、指定された注文プロパティの値を返します。

書式1の戻り値

指定されたプロパティの値をlong型で直接返します。

書式2の戻り値

関数の実行が成功した場合にtrueを返し、プロパティ値は参照渡しされた変数に格納されます。失敗した場合はfalseを返します。

HistoryOrderGetInteger関数を使う際の注意点

取引履歴の注文と待機注文の混同
取引履歴の注文は、「ツールボックス」バーの「履歴」タブに表示されます。これは、既に取引が完了した注文や取り消された注文のリストです。一方、待機注文は「ツールボックス」バーの「取引」タブに表示されますので、これらを混同しないように注意が必要です。
適切な注文チケットの使用
HistoryOrderGetInteger関数を使用する際には、正しい注文チケット番号を指定する必要があります。誤ったチケット番号を使用すると、期待した結果が得られない場合があります。
プロパティ識別子の確認
プロパティ識別子はENUM_ORDER_PROPERTY_INTEGER列挙型の中から選択する必要があります。適切な識別子を使用しないと、関数はエラーを返すか、予期しない結果を返すことがあります。
戻り値の処理
関数の戻り値がfalseの場合、プロパティ値が取得できなかったことを示します。この場合、エラー処理を行う必要があります。特に、書式2のバージョンを使用する際には、関数の実行結果を確認することが重要です。
適切なデータ型の使用
HistoryOrderGetInteger関数はlong型のプロパティ値を返します。
返された値を適切に処理するために、long型の変数を使用する必要があります。異なるデータ型を使用すると、データの整合性が損なわれる可能性があります。

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

// OnStart関数はスクリプトの実行が開始されたときに自動的に呼び出されます
void OnStart()
{
    // 過去7日の取引履歴を選択します
    if(HistorySelect(TimeCurrent() - 7 * 24 * 60 * 60, TimeCurrent()))
    {
        // 取引履歴の総数を取得します
        int totalOrders = HistoryOrdersTotal();

        // 取引履歴を順番に処理するループ
        for(int i = 0; i < totalOrders; i++)
        {
            // 各取引の注文チケットを取得します
            ulong ticket = HistoryOrderGetTicket(i);
            
            // 注文を履歴から選択します
            if(HistoryOrderSelect(ticket))
            {
                // 注文の発注時刻（ミリ秒）を取得します
                long time_setup_msc = HistoryOrderGetInteger(ticket, ORDER_TIME_SETUP_MSC);
                PrintFormat("注文チケット: %d の発注時刻は: %s",
                            ticket, TimeToString(time_setup_msc / 1000));
                
                // 注文の実行/取消時刻（ミリ秒）を取得します
                long time_done_msc = HistoryOrderGetInteger(ticket, ORDER_TIME_DONE_MSC);
                PrintFormat("注文チケット: %d の実行/取消時刻は: %s",
                            ticket, TimeToString(time_done_msc / 1000));
            }
            else
            {
                // 注文の選択に失敗した場合のエラーメッセージ
                PrintFormat("注文チケット: %d の選択に失敗しました。エラーコード: %d",
                            ticket, GetLastError());
            }
        }
    }
    else
    {
        // 取引履歴の選択に失敗した場合のエラーメッセージ
        Print("取引履歴の選択に失敗しました。エラーコード: ", GetLastError());
    }
}

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

OnStart関数
OnStart関数は、スクリプトが実行されたときに自動的に呼び出されるエントリーポイントです。MQL5のスクリプトでは、主な処理をこの関数内に記述します。
HistorySelect関数
HistorySelect関数は、取引履歴の選択範囲を指定するために使用されます。この例では、TimeCurrent関数を使って現在の時刻を取得し、そこから7日分の秒数（7 * 24 * 60 * 60）を引くことで直近1週間の取引履歴を選択しています。
TimeCurrent関数
TimeCurrent関数は、サーバーの現在時刻を取得します。これはスクリプトが実行された瞬間の時刻を示します。
HistoryOrdersTotal関数
HistoryOrdersTotal関数は、選択された取引履歴の中で存在する注文の総数を取得します。この数値を使用して、後続のループで各注文を処理します。
forループ
forループは、取引履歴の各注文を順番に処理するために使用されます。ループの初期化部分でiを0に設定し、条件部分でiがtotalOrdersより小さい間ループを継続し、各ループ終了時にiを1増やします。
HistoryOrderGetTicket関数
HistoryOrderGetTicket関数は、指定されたインデックス（通し番号）の注文チケットを取得します。このチケット番号を使用して、特定の注文にアクセスします。
HistoryOrderSelect関数
HistoryOrderSelect関数は、指定された注文チケットに基づいて注文を選択します。選択に成功するとtrueを返し、失敗するとfalseを返します。
HistoryOrderGetInteger関数
HistoryOrderGetInteger関数は、指定された注文チケットとプロパティ識別子に基づいて注文のプロパティ値を取得します。このサンプルコードでは、発注時刻（ORDER_TIME_SETUP_MSC）と実行/取消時刻（ORDER_TIME_DONE_MSC）を取得しています。
- ORDER_TIME_SETUP_MSCは、注文が発注された時刻を示します。ミリ秒単位で表されます。
- ORDER_TIME_DONE_MSCは、注文が実行または取消された時刻を示します。これもミリ秒単位で表されます。
PrintFormat関数
PrintFormat関数は、フォーマットされた文字列をエキスパートログに出力するために使用されます。PrintFormat関数は、printf関数と同様の形式で文字列をフォーマットします。
- %dは、整数値を表示するためのフォーマット指定子です。
- %i64は、64ビット整数値を表示するためのフォーマット指定子です。
- %sは、文字列を表示するためのフォーマット指定子です。
TimeToString関数
TimeToString関数は、dateTime型の時刻を文字列に変換します。このサンプルコードでは、取得したミリ秒単位の時刻を秒単位に変換し、人間が読める形式の文字列に変換しています。
GetLastError関数
GetLastError関数は、最後に発生したエラーコードを返します。エラー処理の際に使用され、具体的な問題の診断に役立ちます。
条件文（if文）
if文は、指定された条件が真であるかどうかを確認し、条件が真の場合に特定のコードブロックを実行します。ここでは、HistorySelect関数やHistoryOrderSelect関数の結果を確認するために使用されています。
else文
else文は、if文の条件が偽である場合に実行されるコードブロックを指定します。ここでは、HistoryOrderSelect関数やHistorySelect関数が失敗した場合にエラーメッセージを出力するために使用されています。
コメントアウト
コメントアウトは、コードに対する説明や注釈を追加するために使用されます。//で始まる単一行コメントと、/*と*/で囲まれた複数行コメントがあります。このサンプルコードでは、日本語のコメントを使用して各行の説明を行っています。