おススメのMT5・MQL5対応FX業者はコチラ↓
おススメのMT5・MQL5対応FX業者
【※この記事にはプロモーションが含まれています。】 MQL5を使って自作したEAをシステムトレードに利用するには、取引プラットフォームとしてMT5を提供しているFX会社に口座を開設しなくてはいけません。 MQL5にて開発した、MT5用EAを...
mqlinvestmentlab.com
2023.08.04

【MQL5】HistoryDealGetTicket関数について

MQL5リファレンス
2024.07.12
スポンサーリンク
スポンサーリンク

HistoryDealGetTicket関数の働き・役割

HistoryDealGetTicket関数は、取引履歴の中から特定の約定を選択し、その約定チケットを返します。この関数は、指定されたインデックス（通し番号）に基づいて履歴内の約定チケットを取得します。関数の実行が成功すると、取得した約定チケット番号が返され、失敗した場合は0が返されます。

この関数を使用する前に、HistorySelect関数またはHistorySelectByPosition関数を使用して取引履歴を選択する必要があります。これにより、約定と注文の履歴が受信されます。

HistoryDealGetTicket関数の引数について

書式

ulong HistoryDealGetTicket(
  int index  // 約定チケット
);

引数の詳細

index

リスト中の約定番号を指定します。これは、取引履歴内の特定の約定を一意（１つしか存在しない）に識別するための番号です。最初の約定はインデックス0に対応し、次の約定はインデックス1となります。

取引履歴リストのインデックス順序について

取引履歴リストは、過去に行われた取引（約定）の記録を含みます。このリストは、通常、時系列順に並んでいます。つまり、最も古い約定がインデックス0に対応し、次に古い約定がインデックス1に対応し、以下同様に続きます。最新の約定が最も大きいインデックス番号に対応します。

※取引履歴リストは通常、時系列順に並んでいますが、特定の環境や設定によって異なる場合もあります。

HistoryDealGetTicket関数の戻り値について

HistoryDealGetTicket関数は、指定されたインデックスに基づいて取引履歴の中から約定チケットを取得します。関数の戻り値は以下の通りです。

戻り値

ulong型の値

指定されたインデックスに対応する約定チケットが返されます。この値は、約定を一意（１つしか存在しない）に識別するための番号です。

戻り値の詳細

  • 成功した場合: 指定されたインデックスに対応する約定チケット番号が返されます。このチケット番号を使用して、約定の詳細情報にアクセスすることができます。
  • 失敗した場合: 0が返されます。これは、指定されたインデックスに対応する約定が存在しないか、他のエラーが発生したことを示します。エラーの詳細については、GetLastError関数を使用して確認できます。

注意事項

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

// OnStart関数はスクリプトの実行が開始されたときに自動的に呼び出されます
void OnStart()
{
    // 約定チケットを格納する変数を宣言します
    ulong deal_ticket;

    // 約定が実行された注文のチケットを格納する変数を宣言します
    ulong order_ticket;

    // 約定実行時刻を格納する変数を宣言します
    datetime transaction_time;

    // 取引操作の種類を格納する変数を宣言します
    long deal_type;

    // ポジション識別子を格納する変数を宣言します
    long position_ID;

    // 操作の説明を格納する変数を宣言します
    string deal_description;

    // 操作のボリュームを格納する変数を宣言します
    double volume;

    // 約定シンボルを格納する変数を宣言します
    string symbol;

    // 約定履歴をリクエストするための開始日と終了日を設定します
    datetime from_date = 0;         // 一番初めから
    datetime to_date = TimeCurrent(); // 今まで

    // 指定された期間の約定履歴をリクエストします
    if (!HistorySelect(from_date, to_date))
    {
        Print("履歴の選択に失敗しました。");
        return;
    }

    // リスト中の約定の数の合計を取得します
    int deals_total = HistoryDealsTotal();

    // 取引を一つずつ処理するためにループを使用します
    for (int i = 0; i < deals_total; i++)
    {
        // 指定されたインデックスの約定チケットを取得します
        deal_ticket = HistoryDealGetTicket(i);

        // 約定チケットが有効かどうかを確認します
        if (deal_ticket == 0)
        {
            Print("約定チケットの取得に失敗しました。インデックス: ", i);
            continue;
        }

        // 約定のボリュームを取得します
        volume = HistoryDealGetDouble(deal_ticket, DEAL_VOLUME);

        // 約定の実行時刻を取得します
        transaction_time = (datetime)HistoryDealGetInteger(deal_ticket, DEAL_TIME);

        // 約定が実行された注文のチケットを取得します
        order_ticket = HistoryDealGetInteger(deal_ticket, DEAL_ORDER);

        // 取引操作の種類を取得します
        deal_type = HistoryDealGetInteger(deal_ticket, DEAL_TYPE);

        // 約定シンボルを取得します
        symbol = HistoryDealGetString(deal_ticket, DEAL_SYMBOL);

        // ポジション識別子を取得します
        position_ID = HistoryDealGetInteger(deal_ticket, DEAL_POSITION_ID);

        // 操作の説明を生成する関数を呼び出します
        deal_description = GetDealDescription(deal_type, volume, symbol, order_ticket, position_ID);

        // 約定番号をフォーマットします
        string print_index = StringFormat("% 3d", i);

        // 約定の情報をログに表示します
        Print(print_index, ": 約定 #", deal_ticket, " 時刻: ", TimeToString(transaction_time, TIME_DATE|TIME_MINUTES), " ", deal_description);
    }
}

// 操作の説明を文字列として返す関数を定義します
string GetDealDescription(long deal_type, double volume, string symbol, ulong ticket, long pos_ID)
{
    string descr;

    // 取引操作の種類に基づいて説明を生成します
    switch (deal_type)
    {
        case DEAL_TYPE_BALANCE:                 return ("バランス調整");
        case DEAL_TYPE_CREDIT:                  return ("クレジット");
        case DEAL_TYPE_CHARGE:                  return ("手数料");
        case DEAL_TYPE_CORRECTION:              return ("訂正");
        case DEAL_TYPE_BUY:                     descr = "買い"; break;
        case DEAL_TYPE_SELL:                    descr = "売り"; break;
        case DEAL_TYPE_BONUS:                   return ("ボーナス");
        case DEAL_TYPE_COMMISSION:              return ("追加手数料");
        case DEAL_TYPE_COMMISSION_DAILY:        return ("日次手数料");
        case DEAL_TYPE_COMMISSION_MONTHLY:      return ("月次手数料");
        case DEAL_TYPE_COMMISSION_AGENT_DAILY:  return ("日次代理店手数料");
        case DEAL_TYPE_COMMISSION_AGENT_MONTHLY:return ("月次代理店手数料");
        case DEAL_TYPE_INTEREST:                return ("利息");
        case DEAL_TYPE_BUY_CANCELED:            descr = "キャンセルされた買い約定"; break;
        case DEAL_TYPE_SELL_CANCELED:           descr = "キャンセルされた売り約定"; break;
        default:                                return ("未知の取引タイプ");
    }

    // 詳細な説明をフォーマットします
    descr = StringFormat("%s %G %s (注文 #%d, ポジションID %d)", 
                         descr, // 現在の説明
                         volume, // 約定高
                         symbol, // 約定シンボル
                         ticket, // 約定が実行された注文のチケット
                         pos_ID // 約定が含まれたポジションの識別子
                        );
    return descr;
}

このサンプルコードでは、指定した期間内の取引履歴を取得し、その中の各約定について詳細情報を取得してログに出力しています。

サンプルコード解説1：OnStart関数の中１

// OnStart関数はスクリプトの実行が開始されたときに自動的に呼び出されます
void OnStart()
{
    // 約定チケットを格納する変数を宣言します
    ulong deal_ticket;

    // 約定が実行された注文のチケットを格納する変数を宣言します
    ulong order_ticket;

    // 約定実行時刻を格納する変数を宣言します
    datetime transaction_time;

    // 取引操作の種類を格納する変数を宣言します
    long deal_type;

    // ポジション識別子を格納する変数を宣言します
    long position_ID;

    // 操作の説明を格納する変数を宣言します
    string deal_description;

    // 操作のボリュームを格納する変数を宣言します
    double volume;

    // 約定シンボルを格納する変数を宣言します
    string symbol;

    // 約定履歴をリクエストするための開始日と終了日を設定します
    datetime from_date = 0;         // 一番初めから
    datetime to_date = TimeCurrent(); // 今まで

OnStart関数

OnStart関数は、スクリプトの実行が開始されたときに自動的に呼び出される関数です。MQL5のスクリプトでは、メインのエントリーポイントとなります。この関数内に必要な処理を記述します。

変数宣言

以下の変数は、取引履歴の情報を格納するために使用されます。それぞれの変数がどのような情報を保持するかを説明します。

deal_ticket: 約定チケットを格納する変数です。約定を一意に識別する番号が格納されます。

order_ticket: 約定が実行された注文のチケットを格納する変数です。対応する注文チケット番号が格納されます。

transaction_time: 約定実行時刻を格納する変数です。約定が行われた日時を格納します。

deal_type: 取引操作の種類を格納する変数です。約定の種類（例えば、買い、売りなど）を示す識別子が格納されます。

position_ID: ポジションの識別子を格納する変数です。ポジションを一意に識別する番号が格納されます。

deal_description: 操作の説明を格納する変数です。取引の詳細な説明が格納されます。

volume: 操作のボリュームを格納する変数です。取引の数量が格納されます。

symbol: 約定シンボルを格納する変数です。取引された通貨ペアや金融商品のシンボルが格納されます。

期間設定

約定履歴をリクエストするための開始日と終了日を設定します。from_dateは履歴の開始日を示し、to_dateは履歴の終了日を示します。ここでは、最も初期の日時から現在までの期間を設定しています。

datetime from_date = 0;         // 一番初めから
datetime to_date = TimeCurrent(); // 今まで

これにより、取引履歴を最初から現在までのすべての取引に対して取得する準備が整います。

サンプルコード解説2: OnStart関数の中2

// 指定された期間の約定履歴をリクエストします
if (!HistorySelect(from_date, to_date))
{
    Print("履歴の選択に失敗しました。");
    return;
}

// リスト中の約定の数の合計を取得します
int deals_total = HistoryDealsTotal();

HistorySelect関数

この部分では、指定された期間の取引履歴を選択しています。from_dateからto_dateまでの期間に行われた取引を対象とします。

HistorySelect関数は、指定した期間内の取引履歴を選択するために使用されます。関数が成功するとtrueを返し、失敗するとfalseを返します。

このif文では、HistorySelect関数がfalseを返した場合に、「履歴の選択に失敗しました」というメッセージをエキスパートログに出力し、スクリプトの実行を終了します。

Print関数とreturn文

Print関数は、指定したメッセージをエキスパートログに出力します。ここでは、履歴の選択に失敗したことを通知しています。return文は、スクリプトの実行を終了します。

HistoryDealsTotal関数

次に、選択された取引履歴の中で、約定の総数を取得します。これにより、履歴に含まれる約定の数がdeals_total変数に格納されます。

HistoryDealsTotal関数は、選択された取引履歴の中の約定の総数を取得します。

このコードにより、deals_totalには選択された期間内の約定の数が格納されます。これを基にして、次の処理で各約定にアクセスし、その詳細を取得していきます。

サンプルコード解説3: OnStart関数の中3

 // 取引を一つずつ処理するためにループを使用します
for (int i = 0; i < deals_total; i++)
{
    // 指定されたインデックスの約定チケットを取得します
    deal_ticket = HistoryDealGetTicket(i);

    // 約定チケットが有効かどうかを確認します
    if (deal_ticket == 0)
    {
        Print("約定チケットの取得に失敗しました。インデックス: ", i);
        continue;
    }

    // 約定のボリュームを取得します
    volume = HistoryDealGetDouble(deal_ticket, DEAL_VOLUME);

    // 約定の実行時刻を取得します
    transaction_time = (datetime)HistoryDealGetInteger(deal_ticket, DEAL_TIME);

    // 約定が実行された注文のチケットを取得します
    order_ticket = HistoryDealGetInteger(deal_ticket, DEAL_ORDER);

    // 取引操作の種類を取得します
    deal_type = HistoryDealGetInteger(deal_ticket, DEAL_TYPE);

    // 約定シンボルを取得します
    symbol = HistoryDealGetString(deal_ticket, DEAL_SYMBOL);

    // ポジション識別子を取得します
    position_ID = HistoryDealGetInteger(deal_ticket, DEAL_POSITION_ID);

    // 操作の説明を生成する関数を呼び出します
    deal_description = GetDealDescription(deal_type, volume, symbol, order_ticket, position_ID);

    // 約定番号をフォーマットします
    string print_index = StringFormat("% 3d", i);

    // 約定の情報をログに表示します
    Print(print_index, ": 約定 #", deal_ticket, " 時刻: ", TimeToString(transaction_time, TIME_DATE|TIME_MINUTES), " ", deal_description);
}
}

サンプルコード解説3: OnStart関数の中3

ループ処理では、選択された取引履歴の中で、各約定を一つずつ処理するためにforループを使用します。ループは、0からdeals_total未満の間で繰り返されます。

HistoryDealGetTicket関数とdeal_ticket変数

HistoryDealGetTicket関数は指定されたインデックスに対応する約定チケットを取得します。この関数は、約定を一意に識別するためのチケット番号を返します。取得したチケット番号はdeal_ticket変数に格納されます。

有効な約定チケットの確認

取得した約定チケットが有効かどうかを確認します。約定チケットが0の場合は無効とみなし、エラーメッセージを出力して次のループに進みます。これにより、無効な約定チケットが処理されるのを防ぎます。

HistoryDealGetDouble関数とvolume変数

約定のボリューム（取引数量）を取得します。HistoryDealGetDouble関数は、deal_ticketとDEAL_VOLUMEを引数に取り、約定の取引数量を返します。取得した値はvolume変数に格納されます。

HistoryDealGetInteger関数とtransaction_time変数

約定の実行時刻を取得します。HistoryDealGetInteger関数は、deal_ticketとDEAL_TIMEを引数に取り、約定が実行された日時を返します。取得した日時はtransaction_time変数に格納されます。

HistoryDealGetInteger関数とorder_ticket変数

約定が実行された注文のチケットを取得します。この関数は、deal_ticketとDEAL_ORDERを引数に取り、注文チケット番号を返します。取得した注文チケット番号はorder_ticket変数に格納されます。

HistoryDealGetInteger関数とdeal_type変数

取引操作の種類を取得します。この関数は、deal_ticketとDEAL_TYPEを引数に取り、取引の種類を返します。取得した取引の種類はdeal_type変数に格納されます。

HistoryDealGetString関数とsymbol変数

約定シンボル（取引された通貨ペアや金融商品）を取得します。この関数は、deal_ticketとDEAL_SYMBOLを引数に取り、約定シンボルを返します。取得したシンボルはsymbol変数に格納されます。

HistoryDealGetInteger関数とposition_ID変数

ポジションの識別子を取得します。この関数は、deal_ticketとDEAL_POSITION_IDを引数に取り、ポジションの識別子を返します。取得したポジションの識別子はposition_ID変数に格納されます。

GetDealDescription関数とdeal_description変数

取得した情報を基に、取引操作の説明を生成する関数を呼び出します。

GetDealDescription関数は、取引の詳細を人間が理解しやすい形式の説明に変換します。この関数により生成された説明はdeal_description変数に格納されます。

StringFormat関数とprint_index変数

約定番号を見やすい形式にフォーマットします。StringFormat関数を使用して、インデックス番号を指定した形式で文字列に変換します。この結果はprint_index変数に格納されます。

Print関数

取得した約定の詳細情報をエキスパートログに表示します。Print関数を使用して、各約定の情報をログに出力します。これにより、選択された取引履歴内の各約定に対して詳細情報を取得し、その情報をログに表示する処理が完了します。

サンプルコード解説4: GetDealDescription関数（オリジナル関数）

// 操作の説明を文字列として返す関数を定義します
string GetDealDescription(long deal_type, double volume, string symbol, ulong ticket, long pos_ID)
{
    string descr;
    
    // 取引操作の種類に基づいて説明を生成します
    switch (deal_type)
    {
        case DEAL_TYPE_BALANCE:                 return ("口座調整");
        case DEAL_TYPE_CREDIT:                  return ("クレジット");
        case DEAL_TYPE_CHARGE:                  return ("手数料");
        case DEAL_TYPE_CORRECTION:              return ("訂正");
        case DEAL_TYPE_BUY:                     descr = "買い"; break;
        case DEAL_TYPE_SELL:                    descr = "売り"; break;
        case DEAL_TYPE_BONUS:                   return ("ボーナス");
        case DEAL_TYPE_COMMISSION:              return ("追加手数料");
        case DEAL_TYPE_COMMISSION_DAILY:        return ("日次手数料");
        case DEAL_TYPE_COMMISSION_MONTHLY:      return ("月次手数料");
        case DEAL_TYPE_COMMISSION_AGENT_DAILY:  return ("日次代理手数料");
        case DEAL_TYPE_COMMISSION_AGENT_MONTHLY:return ("月次代理手数料");
        case DEAL_TYPE_INTEREST:                return ("利息");
        case DEAL_TYPE_BUY_CANCELED:            descr = "キャンセルされた買い約定"; break;
        case DEAL_TYPE_SELL_CANCELED:           descr = "キャンセルされた売り約定"; break;
        default:                                return ("未知の取引タイプ");
    }
    
    // 詳細な説明をフォーマットします
    descr = StringFormat("%s %G %s (注文 #%d, ポジションID %d)", 
                         descr, // 現在の説明
                         volume, // 約定高
                         symbol, // 約定シンボル
                         ticket, // 約定が実行された注文のチケット
                         pos_ID // 約定が含まれたポジションの識別子
                        );
    return descr;
}

関数の概要

GetDealDescription関数は、取引操作の種類に基づいて操作の説明を生成し、その説明を文字列として返す関数です。この関数は、取引の詳細情報を人間が理解しやすい形式に変換します。

引数

  • deal_type: 取引操作の種類を示す識別子です。これは、取引のタイプ（例：買い、売り、手数料など）を表します。
  • volume: 約定の取引数量を示します。
  • symbol: 約定された通貨ペアや金融商品のシンボルを示します。
  • ticket: 約定が実行された注文のチケット番号を示します。
  • pos_ID: 約定が含まれたポジションの識別子を示します。

関数の処理

初期化

まず、操作の説明を格納するための変数descrを宣言します。

取引操作の種類に基づく説明生成

switch文を使用して、deal_typeの値に基づいて取引操作の説明を生成します。各ケースでは、特定の取引タイプに対応する説明を返します。

  • return文: 即座に関数を終了し、指定した文字列を返します。例えば、手数料や利息などの取引タイプでは、単純に説明を返すだけで良いため、return文が使用されます。
  • break文: 取引タイプが「買い」や「売り」の場合、説明文字列を設定し、その後の処理で詳細な説明を生成します。このため、break文を使用してswitch文から抜け出します。

詳細な説明のフォーマット

取引タイプが「買い」や「売り」の場合、詳細な説明をフォーマットします。StringFormat関数を使用して、取引数量、シンボル、注文チケット、ポジションIDを含む詳細な説明を生成します。

なぜ、識別子によって、returnとbreakが別れているのか

  • return文を使用する場合: 取引タイプの説明が単純で、追加の情報を含める必要がない場合に使用します。この場合、すぐに関数を終了して説明を返します。例：手数料、利息、クレジットなど。
  • break文を使用する場合: 取引タイプが「買い」や「売り」のように、追加の情報（取引数量、シンボル、注文チケット、ポジションID）を含む詳細な説明を生成する必要がある場合に使用します。この場合、まず説明文字列を設定し、その後の処理で詳細な説明を生成します。

詳細な説明のフォーマット

最後に、StringFormat関数を使用して詳細な説明をフォーマットし、descr変数に格納します。生成された説明は、取引数量、シンボル、注文チケット、およびポジションIDを含む形式になります。この説明を関数の戻り値として返します。

結果を戻り値として返す

生成された説明文字列を返します。これにより、呼び出し元のコードは、取引操作の詳細な説明を取得することができます。

このようにして、GetDealDescription関数は、取引操作の種類に基づいて適切な説明を生成し、それを返す役割を果たします。

スポンサーリンク
タイトルとURLをコピーしました