HistoryDealGetString関数の働き・役割
HistoryDealGetString関数は、指定された約定のプロパティを取得するために使用されます。この関数は、約定プロパティが文字列型である場合に、その値を返します。
HistoryDealGetString関数には2つのバージョンがあり、一つはプロパティ値を直接返すもの、もう一つは関数の実行結果に応じて真偽値を返し、プロパティ値を参照によって渡された変数に格納するものです。
この関数を使用することで、取引の詳細な情報を取得し、分析や処理を行うことが可能となります。
HistoryDealGetString関数の引数について
HistoryDealGetString関数はオーバーロード関数（同じ名前で異なる引数リストを持つ関数）であり、2つの異なるバージョンがあります。それぞれの引数について詳しく説明します。
バージョン1
string HistoryDealGetString(
ulong ticket_number, // チケット
ENUM_DEAL_PROPERTY_STRING property_id // プロパティ識別子
);第1引数: ticket_number
種類: ulong
説明: 約定チケットを指定します。このチケットは、特定の約定を一意（一つしか存在しない）に識別するために使用されます。
第2引数: property_id
種類: ENUM_DEAL_PROPERTY_STRING
説明: 約定プロパティ識別子を指定します。この識別子は、取得したいプロパティを示します。ENUM_DEAL_PROPERTY_STRING列挙体のいずれかの値を使用します。
バージョン2
bool HistoryDealGetString(
ulong ticket_number, // チケット
ENUM_DEAL_PROPERTY_STRING property_id, // プロパティ識別子
string& string_var // プロパティ値を受け取る
);第1引数: ticket_number
種類: ulong
説明: 約定チケットを指定します。このチケットは、特定の約定を一意（一つしか存在しない）に識別するために使用されます。
第2引数: property_id
種類: ENUM_DEAL_PROPERTY_STRING
説明: 約定プロパティ識別子を指定します。この識別子は、取得したいプロパティを示します。ENUM_DEAL_PROPERTY_STRING列挙体のいずれかの値を使用します。
第3引数: string_var
種類: string&
説明: リクエストされたプロパティ値を受け取る文字列型の変数です。この変数には、関数実行の成功に応じてプロパティ値が格納されます。string_varは参照渡しで渡され、関数内で値が直接設定されます。
※参照渡しについての詳細は↓の記事をご参照ください。
ENUM_DEAL_PROPERTY_STRINGについて
ENUM_DEAL_PROPERTY_STRINGは、HistoryDealGetString関数で使用される約定プロパティ識別子の列挙型です。これにより、特定のプロパティを指定して約定の詳細情報を取得することができます。
DEAL_SYMBOL
種類: string
説明: DEAL_SYMBOLは、取引が行われた通貨ペアや銘柄を示します。
DEAL_COMMENT
種類: string
説明: DEAL_COMMENTは、取引に関するコメントやメモを示します。
HistoryDealGetString関数の戻り値について
HistoryDealGetString関数には2つのバージョンがあります。
バージョン1
最初のバージョンは、指定されたプロパティ値を直接返します。このバージョンの戻り値はstring型です。指定した約定チケットとプロパティ識別子に基づいて、約定の詳細情報を文字列として取得できます。
バージョン2
2番目のバージョンは、関数の実行が成功したかどうかを示すbool型の値を返します。成功した場合、プロパティ値は3番目の引数として参照渡しされたstring型の変数に格納されます。このバージョンを使用することで、関数の実行結果を確認しながら、プロパティ値を取得することができます。
HistoryDealGetString関数を使う際の注意点
約定、注文、およびポジションの違いを理解することが重要です。約定は注文が実行された結果です。ポジションは、複数の約定をまとめた結果としての持ち高です。これらの概念を混同しないようにしてください。
HistoryDealGetString関数を呼び出す前に、必ずHistorySelect関数またはHistorySelectByPosition関数を使用して、対象となる取引履歴を適切に選択する必要があります。これにより、指定された約定プロパティが正しく取得されるようになります。
また、ENUM_DEAL_PROPERTY_STRING列挙体の各プロパティ識別子が正しく指定されていることを確認してください。間違った識別子を指定すると、予期しない結果やエラーが発生する可能性があります。
2番目のバージョンのHistoryDealGetString関数を使用する場合、プロパティ値を受け取る変数が参照渡しで渡されるため、その変数が正しく初期化されていることを確認してください。関数の実行が成功した場合にのみ、この変数にプロパティ値が格納されます。
注文、約定、およびポジションの違いについて
注文、約定、およびポジションは、それぞれ異なる概念です。以下にその違いを詳しく解説します。
注文
注文は、取引を開始するためのリクエストです。トレーダーが特定の価格で資産を買う、または売る意思を表明するものです。注文が市場に出されると、取引が成立するまで待機します。
約定
約定は、注文が実際に市場で執行されることを指します。例えば、買い注文が売り手と一致した場合、その注文は約定となります。つまり、約定は注文が実際に取引された結果です。
約定の適用範囲
- 未決済のポジション
- 約定は、新規注文が実行されてポジションがオープンされたときに発生します。
- 例えば、買い注文が約定されて新たに買いポジションがオープンされる場合です。
- 決済済みのポジション
- 約定は、既存のポジションをクローズするための注文が実行されたときにも発生します。
- 例えば、保有していた買いポジションを売り注文で決済する場合です。
約定はまだ決済していないポジション（オープンポジション）にも、決済済みのポジション（クローズドポジション）にも適用される概念です。約定そのものは取引の成立を意味し、その結果としてポジションがオープンされたりクローズされたりします。
ポジション
ポジションは、1つ以上の約定の結果として保持される資産の総量です。例えば、複数の買い注文が約定された場合、それらの約定が集まって形成されるものがポジションです。ポジションは、トレーダーが市場で保有している全ての資産の状況を示します。
これらの概念を混同しないようにすることが重要です。注文は取引のリクエスト、約定はそのリクエストが市場で実行された結果、ポジションはその実行結果の合計として理解してください。
HistoryDealGetString関数を使ったサンプルコード
以下は、HistoryDealGetString関数を使用して約定プロパティを取得し、その結果をエキスパートログに出力するサンプルコードです。
void OnStart()
{
// 開始日を1970年1月1日（UNIXエポック時間）に設定
datetime start_date = 0;
// 終了日を現在の日時に設定
datetime end_date = TimeCurrent();
// 指定された期間内の取引履歴を選択
if (HistorySelect(start_date, end_date))
{
// 取引履歴の約定数を取得
int totalDeals = HistoryDealsTotal();
// 取引履歴の約定数をエキスパートログに出力
Print("履歴内の約定の総数: ", totalDeals);
// 全ての約定を処理
for (int i = 0; i < totalDeals; i++)
{
// 約定チケットを取得
ulong ticket = HistoryDealGetTicket(i);
// 約定シンボルを取得
string dealSymbol = HistoryDealGetString(ticket, DEAL_SYMBOL);
Print("約定チケット: ", ticket, " のシンボルは: ", dealSymbol);
// 約定コメントを取得
string dealComment;
bool result = HistoryDealGetString(ticket, DEAL_COMMENT, dealComment);
if (result)
{
Print("約定チケット: ", ticket, " のコメントは: ", dealComment);
}
else
{
Print("約定チケット: ", ticket, " のコメント取得に失敗しました。");
}
}
}
else
{
// 取引履歴の選択に失敗した場合のエラーメッセージをエキスパートログに出力
Print("取引履歴の選択に失敗しました。");
}
}
このサンプルコードでは、以下の手順でHistoryDealGetString関数を使用しています。
- 期間の設定:
- 開始日を1970年1月1日、終了日を現在の日時に設定します。
- 取引履歴の選択:
- HistorySelect関数を使用して、指定された期間内の取引履歴を選択します。
- 約定数の取得:
- HistoryDealsTotal関数を使用して、取引履歴内の約定の総数を取得し、エキスパートログに出力します。
- 全ての約定を処理:
- ループを使用して、全ての約定を処理します。
- HistoryDealGetTicket関数を使用して、各約定のチケットを取得します。
- HistoryDealGetString関数の1番目のバージョンを使用して、約定のシンボルを取得し、エキスパートログに出力します。
- HistoryDealGetString関数数の2番目のバージョンを使用して、約定のコメントを取得し、成功した場合はエキスパートログに出力し、失敗した場合はエラーメッセージを出力します。
- エラーハンドリング:
- 取引履歴の選択に失敗した場合、エラーメッセージをエキスパートログに出力します。
このサンプルコードにより、HistoryDealGetString関数の使い方を具体的に理解することができます。
