Проверка корректности запроса: OrderCheck

Для выполнения любой торговой операции MQL-программа должна предварительно заполнить необходимыми данными структуру MqlTradeRequest. Перед отправкой на сервер с помощью торговых функций её имеет смысл проверить на формальную корректность и оценить последствия выполнения запроса, в частности, размер залога, который потребуется, и оставшихся свободных средств. Данную проверку выполняет функция OrderCheck.

bool OrderCheck(const MqlTradeRequest &request, MqlTradeCheckResult &result)

В случае нехватки средств или ошибочно заполненных параметров функция возвращает false. Кроме того, функция реагирует отказом и при отключенном разрешении торговать — как в терминале в целом, так и для конкретной программы. Конкретный код ошибки смотрите в поле retcode структуры result.

Успешная проверка структуры request и торгового окружения завершается со статусом true, однако это не гарантирует, что запрашиваемая операция непременно выполнится успешно, если её повторить с помощью функций OrderSend или OrderSendAsync. Между вызовами могут измениться торговые условия или у брокера на сервере применены настройки для конкретной внешней торговой системы, которые невозможно учесть в алгоритме формальной проверки, которую делает OrderCheck.

Для получения описания предполагаемого финансового результата следует анализировать поля структуры result.

В отличие от функции OrderCalcMargin, которая рассчитывает оценку требуемого залога только под одну предполагаемую позицию или ордер, OrderCheck учитывает, хоть и в упрощенном режиме, общее состояние торгового счета. Так, она заполняет поле margin в структуре MqlTradeCheckResult и прочие связанные поля (margin_free, margin_level) совокупными показателями, которые сложатся после выполнение приказа. Например, если уже открыта позиция по какому-либо инструменту на момент вызова OrderCheck и проверяемый запрос наращивает позицию, поле margin отразит сумму залога, включая прежние маржинальные обязательства. Если же новый приказ содержит операцию в противоположном направлении, размер маржи не увеличится (в реальности он должен уменьшится, потому что на неттинговом счете позиция таким образом может вообще закрыться, а на счете с хеджингом — применится хеджирующая маржа для встречных позиций, однако столь точный расчет функция не выполняет).

Прежде всего, OrderCheck пригодится программистам на начальном этапе знакомства с торговым API, чтобы экспериментировать с запросами, не отправляя их на сервер.

Протестируем работу функции OrderCheck с помощью простого неторгующего эксперта CustomOrderCheck.mq5. Мы сделали его именно экспертом, а не скриптом, для удобства пользования — так он будет оставаться на графике после прикрепления с текущими настройками, и их легко редактировать, меняя отдельные входные параметры. Если бы это был скрипт, нам пришлось бы каждый раз начинать заново установку нескольких полей со значений по умолчанию.

Чтобы запустить проверку, установим в OnInit таймер.

А в обработчике таймера будет реализован основной алгоритм, причем в самом начале мы отменяем таймер, поскольку нам нужно, чтобы код выполнился один раз, а затем ждал, пока пользователь поменяет параметры.

Входные параметры эксперта полностью повторяют набор полей структуры торгового запроса.

Многие из них не влияют на проверку и финансовые показатели, но оставлены, чтобы можно было в этом убедиться.

По умолчанию состояние переменных соответствует запросу на открытие позиции минимальным лотом текущего инструмента. В частности, параметр Type в отсутствие явной инициализации получит значение 0, которое равно элементу ORDER_TYPE_BUY структуры ENUM_ORDER_TYPE. В параметре Action мы задали явную инициализацию, потому что 0 не соответствует ни одному элементу перечисления ENUM_TRADE_REQUEST_ACTIONS (первый элемент TRADE_ACTION_DEAL равен 1).

Заполняем структуру. В реальных роботах обычно требуется присвоить только несколько полей, но поскольку этот тест носит универсальный характер, мы должны обеспечить передачу любых параметров, которые введет пользователь.

Обратите внимание, что здесь мы пока не делаем нормализацию цен и лотов, хотя в реальной программе она требуется. Тем самым данный тест дает возможность ввести "неровные" значения и убедиться, что они приводят к ошибке. В последующих примерах нормализация уже будет включена.

Затем вызываем OrderCheck и выводим в журнал структуры request и result. Из последней нас интересует, на самом деле, только поле retcode, поэтому оно дополнительно печатается с "расшифровкой" в виде текста, макросом TRCSTR (TradeRetcode.mqh). Вы также можете анализировать строковое поле comment, но его формат может меняться, так что оно в большей степени подойдёт для отображения пользователю.

Вывод структур обеспечивает вспомогательная функция StructPrint, которая основана на ArrayPrint. Из-за этого мы пока получим "сырое" отображение данных — в частности, элементы перечислений представлены числами "как есть". Позднее мы разработаем функцию для более дружественного (понятного для пользователя) вывода структуры MqlTradeRequest (см. TradeUtils.mqh).

Чтобы облегчить анализ результатов, в начале функции OnTimer выведем текущее состояние счета, а в конце для сравнения — вычислим для заданной торговой операции маржу с помощью функции OrderCalcMargin.

Ниже представлен пример вывода в журнал на "XAUUSD" с настройками по умолчанию.

А вот пример с оценкой предполагаемого увеличения маржи на счете, где уже есть открытая позиция, и мы её собираемся удвоить.

Попробуйте менять любые параметры запроса и посмотрите, является ли запрос успешным. Некорректные сочетания параметров будут вызывать коды ошибок из стандартного перечня, но поскольку неверных вариантов гораздо больше, чем зарезервированных (самых распространенных ошибок), функция часто может возвращать обобщенный код TRADE_RETCODE_INVALID (10013). В связи с этим рекомендуется реализовать собственные проверки структуры с большей степенью диагностики.

При отправке реальных запросов на сервер этот же код TRADE_RETCODE_INVALID используется при различных непредвиденных обстоятельствах, например, при попытке повторно изменить ордер, операция изменения которого уже запущена (но еще не завершилась) во внешней торговой системе.