Guia Técnico: Como usar HistoryDealGetInteger() na prática

Quando a rotina de negociação exige que você recupere rapidamente um valor inteiro de um histórico de negócios, a função HistoryDealGetInteger() costuma aparecer como a solução “pronta”. Na prática, porém, ela costuma gerar mais dúvidas que respostas: onde exatamente ela lê o dado, quais tipos de deal são elegíveis e, sobretudo, o que acontece quando o campo solicitado não existe. Este texto vai direto ao ponto, mostrando passo a passo o que fazer, onde o erro costuma surgir e como contornar as armadilhas mais comuns.

Objetivo da chamada

• O que a função devolve? Um int extraído de um campo específico de um deal armazenado no histórico.
• Quando usar? Em scripts que precisam de cálculo rápido (ex.: somatório de lotes, contagem de ordens executadas) sem abrir um loop completo sobre o histórico.

Estrutura mínima do deal

Um deal no MetaTrader 5 possui, entre outros, os campos deal, type, volume, price e comment. HistoryDealGetInteger() aceita dois parâmetros: deal_id e property_id. O property_id deve ser um dos valores enumerados em ENUM_DEAL_PROPERTY_INTEGER, como DEAL_VOLUME ou DEAL_TICKET. Qualquer divergência – por exemplo, solicitar DEAL_PRICE (que é double) – gera ERR_INVALID_PARAMETER.

Exemplo profissional

// Recupera o volume total de um trade fechado ulong ticket = 12345678; int volume = HistoryDealGetInteger(ticket, DEAL_VOLUME); if(volume==-1){ Print("Deal não encontrado ou campo inválido"); } else { Print("Volume negociado: ", volume); } 

Note que o código verifica o retorno -1, padrão de erro da API. Ignorar essa checagem costuma ser a causa de “valores fantasma” que aparecem nas estatísticas finais.

Limitações e armadilhas

• Escopo temporal: a função só acessa o histórico já carregado na memória da sessão. Se o histórico ainda não foi carregado (por exemplo, ao iniciar o EA), o retorno será -1 mesmo que o deal exista.
• Tipos incompatíveis: tentar ler um campo double ou string como inteiro não lança exceção, mas devolve zero, confundindo a lógica de controle.
• Permissões de leitura: em contas de demonstração com restrição de histórico, alguns campos são ocultados, provocando falhas silenciosas.

Quando a função falha – cenários reais

Imagine um script de “fechamento automático” que soma o volume de todos os trades do dia. Se o EA for iniciado às 09:55, antes do fechamento do primeiro candle, o histórico ainda não contém o trade de 09:30. O HistoryDealGetInteger() retornará -1, e o script, sem tratamento, considerará que o volume foi zero, resultando em um fechamento prematuro.

Dicas contra‑intuitivas

Em vez de chamar a função dentro de um for que itera sobre todos os tickets, prefira usar HistorySelect() para carregar um bloco de deals e, em seguida, HistoryDealGetInteger() apenas nos tickets filtrados por DEAL_TYPE. Essa combinação reduz chamadas de API em 70 % e elimina “picos” de latência que costumam derrubar EAs em momentos de alta volatilidade.

Próximo passo

Teste a chamada em um ambiente de demonstração, forçando um HistorySelect() com intervalo de 1 dia. Verifique o retorno para tickets inexistentes e registre o erro em um log próprio. Esse pequeno ajuste costuma transformar um script “quebrável” em um módulo robusto, pronto para produção.

Para aprofundar a leitura oficial, veja a documentação da API que detalha todos os property_id disponíveis.

Primeiros passos após a compra

1. Baixe o SDK da plataforma oficial e instale na pasta libs/ do seu projeto.

2. Verifique a versão do compilador: gcc >= 9.2 ou MSVC 2019. Incompatibilidades geram falhas silenciosas na extração de valores.

3. Abra o arquivo DealConfig.h e habilite a macro ENABLE_HISTORY_DEAL. Sem essa definição, HistoryDealGetInteger() sempre retorna 0.

Estrutura dos Deals

O HistoryDealGetInteger() busca o campo Value com base no DealID e no intervalo de tempo especificado.

Checklist operacional – rotina recomendada

• Configuração inicial: carregue o arquivo deals.db via HistoryDealLoad() antes de qualquer chamada.
• Validação de parâmetros: sempre teste dealId > 0 e startTs < endTs. Use assert() em modo debug.
• Cache local: habilite HistoryDealCacheEnable(256) para reduzir I/O em leituras consecutivas.
• Log de auditoria: registre o retorno da função em audit.log para rastrear discrepâncias.
• Limpeza periódica: execute HistoryDealPurge(30) a cada 30 dias para excluir registros obsoletos.

Exemplo profissional – código completo

O snippet abaixo demonstra a extração segura de um valor inteiro de um deal histórico, com tratamento de erro e fallback.

#include "HistoryDeal.h" #include  int main(void) { if (!HistoryDealLoad("deals.db")) { fprintf(stderr, "Falha ao carregar o banco de dados.\n"); return 1; } int dealId = 1024; long start = 1622505600000; // 01/06/2021 00:00:00 GMT long end = 1625097600000; // 01/07/2021 00:00:00 GMT int value = HistoryDealGetInteger(dealId, start, end); if (value == HISTORY_DEAL_ERROR) { fprintf(stderr, "Deal não encontrado ou intervalo inválido.\n"); // fallback: buscar valor padrão value = 0; } printf("Valor extraído: %d\n", value); HistoryDealUnload(); return 0; } 

Erros comuns e como evitá‑los

• Ignorar o carregamento prévio: chamar HistoryDealGetInteger() sem HistoryDealLoad() gera retorno -1 silencioso.
• Intervalo invertido: startTs maior que endTs causa falha de validação interna.
• Overflow de ID: IDs acima de 2^31‑1 ultrapassam o tipo int e corrompem a busca.
• Desativar cache em produção: perda de performance notável em ambientes de alta taxa de consulta.

Sinais de progresso – mini dashboard textual

Quando todas as metas forem atingidas, considere escalar o pool de threads para paralelizar consultas em lote.

Perfil ideal e limitações de HistoryDealGetInteger()

Se o seu workflow depende de extração numérica de históricos de negócios em tempo real, este método pode ser a chave. Não é para amadores que só precisam de um int básico; é para quem já está imerso no ecossistema de deals e precisa de precisão cirúrgica.

Quem deve usar

• Desenvolvedores de plataformas de negociação que manipulam grandes volumes de transações;
• Analistas que criam dashboards avançados com métricas de histórico de preço;
• Equipes de integração que precisam mapear valores inteiros entre sistemas legados e modernos.

Quem não terá bom aproveitamento

• Iniciantes que ainda não dominam a estrutura de Deal e confundem tipos de dado;
• Projetos de baixa escala onde a sobrecarga de chamada à API supera o ganho de precisão;
• Casos onde o histórico é exclusivamente textual ou qualitativo.

Limitações práticas

O método só funciona se o deal contém um campo inteiro previamente definido; ausência gera exceção não tratada. Não há fallback automático para 0 ou null. Além disso, ele não suporta filtros por intervalo de datas – o usuário tem que pré‑filtrar o vetor de deals.

FAQ contextual

Checklist rápido antes de usar

• Confirmação de que o campo alvo está marcado como inteiro no schema;
• Validação prévia de existência com HistoryDealHasField();
• Tratamento de exceções para DealNotFoundException;
• Limite de 5 ms por chamada em ambientes de alta frequência (benchmark interno).

Mini cenários reais

Um trader automatizado precisava filtrar apenas negócios acima de 1 000 USD. Usando HistoryDealGetInteger() ele evitou transformar strings em números, reduzindo a latência em 12 ms por ciclo.

Já numa fintech que consolidava contratos, o método falhou ao encontrar campos nulos, provocando parada do pipeline. A solução foi envolver a chamada em try/catch e fallback para -1.

Observações práticas e próximos passos

Implementar um wrapper que verifica a presença do campo e aplica fallback pode elevar a robustez em 30 %. Para quem busca performance, combine com cache de resultados frequentes; o método em si não possui cache interno.

Pronto para testar? Acesse a documentação oficial e baixe o SDK atualizado aqui.

Decisão editorial: HistoryDealGetInteger() é indispensável para pipelines que exigem números puros de históricos de negócios, mas exige maturidade no manejo de exceções e validação de atributos. Use se sua arquitetura já lida com dados estruturados; caso contrário, opte por abordagens mais tolerantes.