CopyRates

Obtém dados históricos de estrutura MqlRates de um ativo-período especificado na quantidade especificada no array rates_array. A ordenação dos elementos dos dados copiados é do presente para o passado, isto é, a posição de início 0 significa a barra corrente.

CopyRates

Ao copiar uma quantidade desconhecida de dados, é recomendável usar um array dinâmico como array destino, porque se a quantidade solicitada de dados for menor (ou maior) que o comprimento do array destino, a função tenta realocar a memória de qual forma que os dados solicitados caibam completamente.

Se você souber a quantidade de dados que você precisa para copiar, é melhor usar um buffer alocado estaticamente, a fim de evitar a alocação de memória excessiva.

Não importa qual seja a propriedade do array destino - como series=true ou como series=false. Os dados serão copiados de tal maneira que o elemento mais antigo será localizado no início da memória física alocada para o array. Exitem 3 variantes de chamada da função.

Chamar pela posição primeira e o número de elementos requeridos

int  CopyRates(
   string           symbol_name,       // nome do ativo
   ENUM_TIMEFRAMES  timeframe,         // período
   int              start_pos,         // posição de início
   int              count,             // quantidade de dados para copiar
   MqlRates         rates_array[]      // array destino para copiar
   );

Chamar pela data de início e o número de elementos requeridos

int  CopyRates(
   string           symbol_name,       // nome do ativo
   ENUM_TIMEFRAMES  timeframe,         // período
   datetime         start_time,        // data e hora de início
   int              count,             // quantidade de dados para copiar
   MqlRates         rates_array[]      // array destino para copiar
   );

Chamar pelas datas de início e término de um intervalo de tempo requerido

int  CopyRates(
   string           symbol_name,       // nome do ativo
   ENUM_TIMEFRAMES  timeframe,         // período
   datetime         start_time,        // data e hora de início
   datetime         stop_time,         // data e hora de término
   MqlRates         rates_array[]      // array destino para copiar
   );

Parâmetros

symbol_name

[in]  Nome do ativo.

timeframe

[in]  Período.

start_time

[in]  Hora da barra do primeiro elemento para copiar.

start_pos

[in]  A posição de início do primeiro elemento para copiar.

count

[in]  Quantidade de dados para copiar.

stop_time

[in]  Hora da barra, correspondente ao último elemento para copiar.

rates_array[]

[out]  Array de tipo MqlRates.

Valor do Retorno

Retorna o número de elementos copiados ou -1 no caso de um erro.

Observação

Se o intervalo inteiro de dados solicitados não estiver disponível no servidor, a função retorna -1. Se dados fora do TERMINAL_MAXBARS (número máximo de barras no gráfico) for solicitado, a função também retornará -1.

Ao solicitar dados de um indicador, se as séries de tempo solicitadas não estiverem ainda construídas ou elas precisarem serem baixadas do servidor, a função imediatamente retornará -1, mas o processo de download/construção será iniciado.

Ao solicitar dados de um Expert Advisor ou script, o download do servidor será iniciado se o terminal não tiver estes dados localmente, ou a construção da série de tempo solicitada iniciará, se os dados puderem ser construídas a partir do histórico local mas eles não estiverem prontos ainda. A função retornará a quantidade de dados que estará pronta no momento da expiração do tempo limite, mas o download do histórico continuará, e na próximo solicitação simular, a função retornará mais dados.

Ao solicitar dados através da data de início e do número de elementos requeridos, somente dados cuja data seja menor (anterior) ou igual a data especificada são retornados. Isso significa que a hora de abertura de qualquer barra, para cujo valor é retornado (volume, spread, valor no buffer de indicador, preços de Abertura, Máximo, Mínimo, Fechamento ou Hora de Abertura) é sempre menor ou igual ao valor especificado.

Ao solicitar dados em uma faixa especificada de datas, somente dados deste intervalo serão retornados. O intervalo é definido e contado em segundos. Isso significa que a hora de abertura de qualquer barra, para cujo valor é retornado (volume, spread, valor no buffer de indicador, preços de Abertura, Máximo, Mínimo, Fechamento ou Hora de Abertura) é sempre dentro do intervalo solicitado.

Assim, se o dia corrente for sábado, e em uma tentativa de copiar dados usando a janela de tempo semanal, você especificar start_time=Last_Tuesday e stop_time=Last_Friday, a função retornará 0, porque a hora de abertura em uma janela de tempo semanal é sempre domingo, e nenhum barra semanal cairá no intervalo especificado.

Se você precisar retornar o valor correspondente para a barra corrente incompleta, você pode usar a primeira forma de chamada, especificando start_pos=0 e count=1.

Exemplo:

void OnStart()
  {
//---
   MqlRates rates[];
   ArraySetAsSeries(rates,true);
   int copied=CopyRates(Symbol(),0,0,100,rates);
   if(copied>0)
     {
      Print("Barres copiados: "+copied);
      string format="open = %G, high = %G, low = %G, close = %G, volume = %d";
      string out;
      int size=fmin(copied,10);
      for(int i=0;i<size;i++)
        {
         out=i+":"+TimeToString(rates[i].time);
         out=out+" "+StringFormat(format,
                                  rates[i].open,
                                  rates[i].high,
                                  rates[i].low,
                                  rates[i].close,
                                  rates[i].tick_volume);
         Print(out);
        }
     }
   else Print("Falha ao receber dados históricos para o símbolo ",Symbol());
  }

Veja um exemplo detalhado de solicitação de dados históricos na seção Métodos de Vinculação de Objetos. O script disponível nesta seção mostra como obter os valores do indicador iFractals nas últimas 1000 barras e como exibir os últimos 10 fractais de alta e os últimos 10 fractais de baixa no gráfico. Uma técnica simular pode ser usada para todos os indicadores que têm dados faltantes e que são usualmente desenhados usando os seguintes estilos:

 

Também Veja

Estruturas e Classes, TimeToString, StringFormat