DocumentaçãoSeções
Referência MQL5Calendário econômicoCalendarValueHistory 

CalendarValueHistory

Obtém uma matriz de valores de todos os eventos num determinado intervalo de tempo com um filtro por país e/ou moeda.

int  CalendarValueHistory(
   MqlCalendarValue&  values[],              // array para obter descrições de valores 
   datetime           datetime_from,         // borda esquerda do intervalo de tempo
   datetime           datetime_to=0          // borda direita do intervalo de tempo
   const string       country_code=NULL,     // código do país ISO 3166-1 alpha-2
   const string       currency=NULL          // código da moeda do país 
   );

Parâmetros

values[]

[out]  Matriz de tipo MqlCalendarValue para obter valores de eventos. Veja um exemplo de processamento de eventos de calendário.

datetime_from

[in]  Data de início do intervalo de tempo a partir do qual os eventos são selecionados pelo ID definido, enquanto datetime_from < datetime_to.

datetime_to=0

[in]   Data final do intervalo de tempo a partir do qual os eventos são selecionados pelo ID definido. Se não for especificado o parâmetro datetime_to (ou é igual a 0), serão retornados todos os valores de evento da data especificada datetime_from, disponível no banco de dados do Calendário, incluindo os valores dos eventos planejados para o futuro.

country_code=NULL

[in]  Código do país segundo ISO 3166-1 alpha-2

currency=NULL

[in]  Código da moeda do país

Valor retornado

Se bem-sucedido, retorna o número de valores disponíveis no array de valores, caso contrário -1.. Para obter informações de erro, chame a função GetLastError(). Possíveis erros:

  • 4001 — ERR_INTERNAL_ERROR  (erro geral de tempo de execução),
  • 4004 — ERR_NOT_ENOUGH_MEMORY (memória insuficiente para execução da solicitação),
  • 5401 — ERR_CALENDAR_TIMEOUT (excedido tempo limite de solicitação),
  • 5400 — ERR_CALENDAR_MORE_DATA (tamanho de array insuficiente para obter descrições de todos os valores, portanto, eles recebem apenas o que contêm).

 

Observação

Todas as funções para trabalhar com o Calendário Econômico usam o horário do servidor de negociação (TimeTradeServer). Isso significa que o tempo na estrutura MqlCalendarValue e os parâmetros de tempo de entrada nas funções CalendarValueHistoryByEvent/CalendarValueHistory são definidos no fuso horário do servidor de negociação e não no horário local do usuário.

Se um array foi passado para a função events[] de comprimento fixo e, como resultado da solicitação, não havia espaço suficiente para salvar o resultado inteiro, é mostrado o erro ERR_CALENDAR_MORE_DATA (5400).

Se não for especificado o parâmetro datetime_to (=0), serão retornados todos os valores de eventos a partir da data datetime_from disponível no banco de dados do Calendário, incluindo os valores planejados para o futuro.

Para os filtros country_code e currency valores NULL e "" são equivalentes, eles indicam que não há filtro.

Para country_code deve ser usado o campo code da estrutura MqlCalendarCountry, por exemplo, "US", "RU" ou "EU".

Para currency deve ser usado o campo currency da estrutura MqlCalendarCountry, por exemplo, "USD", "RUB" ou "EUR".

Os filtros são aplicados por conjunção, ou seja, através do booliano 'E' são selecionados apenas os eventos para os quais ambas as condições são atendidas simultaneamente — país e moeda.

A estrutura MqlCalendarValue disponibiliza método para obter e verificar valores a partir dos campos actual_value, forecast_value, prev_value e revised_prev_value. Se o valor do campo não estiver definido, ele armazenará o valor LONG_MIN (-9223372036854775808).

Deve-se ter em mente que os valores nestes campos são armazenados multiplicados por um fator de um milhão. Isso significa que quando as funções CalendarValueById, CalendarValueHistoryByEvent, CalendarValueHistory, CalendarValueLastByEvent e CalendarValueLast recebem valores em MqlCalendarValue, é necessário verificar se os valores LONG_MIN desses campos são iguais; e se no campo estiver definido o valor, para obter o valor deve-se dividir o valor do campo por 1000 000 (um milhão). Outra maneira de obter valores é verificar e obter valores por funções da própria estrutura MqlCalendarValue.

Exemplo:

//+------------------------------------------------------------------+
//| Script program start function                                    |
//+------------------------------------------------------------------+
void OnStart()
  {
//--- código do país para a União Europeia de acordo com a ISO 3166-1 Alpha-2
   string EU_code="EU";
//--- obtenha todos os valores de evento da União Europeia
   MqlCalendarValue values[];
//--- defina os limites do intervalo de onde são tomados os eventos
   datetime date_from=D'01.01.2018';  // defina todos os eventos de 2018
   datetime date_to=0;                // 0 indica que todos os eventos são conhecidos mesmo aqueles que ainda não chegaram
/ --- solicite o histórico do evento para a União Europeia desde 2018
   if(CalendarValueHistory(values,date_from,date_to,EU_code))
     {
      PrintFormat("Obtidos valores do evento para country_code=%s: %d",
                  EU_code,ArraySize(values));
      //--- reduza o tamanho do array para imprimir no Diário
      ArrayResize(values,10);
//--- imprima o valor dos eventos no Diário
      ArrayPrint(values);      
     }
   else
     {
      PrintFormat("Erro! Falha ao obter eventos do país country_code=%s",EU_code);
      PrintFormat("Código de erro: %d",GetLastError());
     }
//---
  }
/*
  Resultado:
  Obtidos os valores de eventos para country_code=EU: 1384
        [id] [event_id]           [time]               [period] [revision]   [actual_value] [prev_value] [revised_prev_value] [forecast_value] [impact_type] [reserved]
   [0] 54215  999500001 2018.01.02 09:00:00 2017.12.01 00:00:00          3       60600000     60600000 -9223372036854775808         60500000             1          0
   [1] 54221  999500002 2018.01.04 09:00:00 2017.12.01 00:00:00          3       56600000     56500000 -9223372036854775808         56000000             1          0
   [2] 54222  999500003 2018.01.04 09:00:00 2017.12.01 00:00:00          3       58100000     58000000 -9223372036854775808         58400000             2          0
   [3] 45123  999030005 2018.01.05 10:00:00 2017.11.01 00:00:00          0         600000       400000 -9223372036854775808           100000             1          0
   [4] 45124  999030006 2018.01.05 10:00:00 2017.11.01 00:00:00          0        2800000      2500000 -9223372036854775808          1500000             1          0
   [5] 45125  999030012 2018.01.05 10:00:00 2017.12.01 00:00:00          1         900000       900000 -9223372036854775808          1000000             2          0
   [6] 45126  999030013 2018.01.05 10:00:00 2017.12.01 00:00:00          1        1400000      1500000 -9223372036854775808          1500000             2          0
   [7] 54953  999520001 2018.01.05 20:30:00 2018.01.02 00:00:00          0      127900000     92100000 -9223372036854775808         76400000             0          0
   [8] 22230  999040003 2018.01.08 10:00:00 2017.12.01 00:00:00          0        9100000      8200000              8100000          7600000             1          0
   [9] 22231  999040004 2018.01.08 10:00:00 2017.12.01 00:00:00          0       18400000     16300000             16400000         16800000             1          0   
*/ 

Veja também

CalendarCountries, CalendarEventByCountry, CalendarValueHistoryByEvent, CalendarEventById, CalendarValueById