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.

bool  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.

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

Retorna true em caso de sucesso, caso contrário, false. 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

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.

Se, para o valor de evento, não houver algum dos campos abaixo

struct MqlCalendarValue
  {
   ...
   long              actual_value;              // valor atual do indicador
   long              prev_value;                // valor anterior do indicador
   long              revised_prev_value;        // valor do evento anterior revisado
   long              forecast_value;            // valor previsto do evento
   ...
  };

o valor do campo ausente será retornado como INT64_MIN (-9223372036854775808). Veja o exemplo abaixo para valores de campo revised_prev_value.

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