DocumentaçãoSeções
Referência MQL5Séries Temporais e Acesso a IndicadoresCopySeries 

CopySeries

Obtém no conjunto de arrays especificado as séries temporais sincronizadas da estrutura MqlRates para o símbolo-período especificado na quantidade especificada. Os itens da posição inicial são contados do presente para o passado, ou seja, uma posição inicial de 0 significa a barra atual.

copyseries

Ao copiar antecipadamente uma quantidade desconhecida de dados, é recomendável usar como arrays receptores uma matriz dinâmica, já que se houver mais dados do que o array pode conter, é feita uma tentativa de redistribuir a matriz para que os dados solicitados se ajustem a todo o array.

Se uma quantidade pré-determinada de dados precisa ser copiada, é melhor fazê-lo em um buffer alocado estaticamente, para evitar a alocação global desnecessária de memória.

Não importa que propriedade o array receptor tenha, as_series=true ou as_series=false, os dados serão copiados para que o elemento da série temporal mais antiga seja copiado para o início da memória física alocada ao array.

int  CopySeries(
   string           symbol_name,       // nome do símbolo
   ENUM_TIMEFRAMES  timeframe,         // período
   int              start_pos,         // onde começamos 
   int              count,             // quanto copiamos
   ulong            rates_mask,        // combinação de sinalizadores para indicar a série solicitada
   void&            array1[],          // matriz onde serão copiados os dados da primeira série temporal
   void&            array2[]           // matriz onde os dados da segunda série temporal serão copiados
   ...
   );

Parâmetros

symbol_name

[in]  Símbolo.

timeframe

[in]  Período.

start_pos

[in]  Número do primeiro item copiado.

count

[in]  Número de itens a serem copiados.

rates_mask

[in]  Combinação de sinalizadores a partir da enumeração ENUM_COPY_RATES .

array1, array2,...

[out]  Matriz do tipo apropriado para recuperar as séries temporais a partir da estrutura MqlRates. A ordem dos arrays passados para a função deve corresponder à ordem dos campos na estrutura MqlRates.

Valor retornado

Número de elementos do array copiados ou -1 no caso de erro.

Observação

Se o intervalo de tempo solicitado estiver totalmente fora dos dados disponíveis no servidor, a função retorna -1. Se os dados solicitados estiverem fora do escopo TERMINAL_MAXBARS (número máximo de barras no gráfico), a função também retornará -1.

Ao solicitar dados do indicador, caso as séries temporais solicitadas ainda não tenham sido construídas ou precisem ser baixadas do servidor, a função retornará imediatamente -1, mas o próprio processo de carregamento/construção será iniciado.

Ao solicitar dados de um EA ou script, será iniciada um carregamento desde o servidor se o terminal não tiver esses dados localmente, ou será iniciada a construção da série temporal necessária se os dados puderem ser construídos a partir do histórico local, mas ainda não estiverem prontos. A função retornará a quantidade de dados que estarão prontos quando o tempo expirar, mas o carregamento do histórico continuará, e na próxima vez que uma solicitação semelhante for feita a função retornará mais dados.

Diferença entre CopySeries e CopyRates

A função CopySeries permite obter apenas as séries temporais necessárias de cada vez em diferentes arrays especificados, enquanto todos estão sincronizados entre si. Isso significa que todos os valores nos arrays resultantes em um índice específico N pertencerão à mesma barra no par Symbol/Timeframe especificado. Nesse caso, o programador não precisa garantir que todas as séries temporais recebidas sejam sincronizadas pelo tempo de abertura da barra.

Ao contrário de CopyRates, que retorna o conjunto completo de séries temporais como um array MqlRates, a função CopySeries permite que o programador obtenha apenas as séries temporais necessárias como arrays separados. Para fazer isso, você precisa especificar uma combinação de sinalizadores para especificar o tipo de série temporal solicitado . A ordem dos arrays passados para a função deve corresponder à ordem dos campos na estrutura MqlRates:

struct MqlRates
  {
   datetime time;         // início de período
   double   open;         // preço de abertura
   double   high;         // preço mais alto do período
   double   low;          // preço mais baixo do período
   double   close;        // preço de fechamento
   long     tick_volume;  // volume de tick
   int      spread;       // spread
   long     real_volume;  // volume de negociação
  }

Assim, se for necessário obter os valores das séries temporais time, close e real_volume para as últimas 100 barras do Symbol/Timeframe atual, a chamada deve ser a seguinte:

datetime time[];
double   close[];
long     volume[];
CopySeries(NULL,0,0,100,COPY_RATES_TIME|COPY_RATES_CLOSE|COPY_RATES_VOLUME_REAL,time,close,volume);

A ordem das matrizes é importante "time, close, volume" – deve estar de acordo com a ordem dos campos na estrutura MqlRates. Já a ordem dos valores na máscara rates_mask não importa, a máscara poderia ser assim:

COPY_RATES_VOLUME_REAL|COPY_RATES_TIME|COPY_RATES_CLOSE

Exemplo:

//--- input parameters
input datetime InpDateFrom=D'2022.01.01 00:00:00';
input datetime InpDateTo  =D'2023.01.01 00:00:00';
input uint     InpCount   =20;
//+------------------------------------------------------------------+
//| Script program start function                                    |
//+------------------------------------------------------------------+
void OnStart(void)
  {
//--- arrays para obter séries temporais da estrutura de preços MqlRates
   double   open[];
   double   close[];
   float    closef[];
   datetime time1[], time2[];
//--- solicitamos preços de fechamento para um array do tipo double
   ResetLastError();
   int res1=CopySeries(NULL, PERIOD_CURRENT, 0, InpCount,
                       COPY_RATES_TIME|COPY_RATES_CLOSE, time1, close);
   PrintFormat("1. CopySeries  returns %d values. Error code=%d", res1, GetLastError());
   ArrayPrint(close);
  
//--- agora solicitamos mais preços de abertura e preços de fechamento em um array do tipo float
   ResetLastError();
   int res2=CopySeries(NULL, PERIOD_CURRENT, 0, InpCount,
                       COPY_RATES_TIME|COPY_RATES_CLOSE|COPY_RATES_OPEN, time2, open, closef);
   PrintFormat("2. CopySeries  returns %d values. Error code=%d", res2, GetLastError());
   ArrayPrint(closef);
//--- comparamos os dados
   if((res1==res2) && (time1[0]==time2[0]))
     {
      Print("  | Time             |    Open      | Close double | Close float |");
      for(int i=0; i<10; i++)
        {
         PrintFormat("%d | %s |   %.5f    |   %.5f    |   %.5f   |",
                     i, TimeToString(time1[i]), open[i], close[i], closef[i]);
        }
     }
//--- Resultado
 1. CopySeries  returns 20 values. Error code=0
 [ 0] 1.06722 1.06733 1.06653 1.06520 1.06573 1.06649 1.06694 1.06675 1.06684 1.06604
 [10] 1.06514 1.06557 1.06456 1.06481 1.06414 1.06394 1.06364 1.06386 1.06239 1.06247
 2. CopySeries  returns 20 values. Error code=0
 [ 0] 1.06722 1.06733 1.06653 1.06520 1.06573 1.06649 1.06694 1.06675 1.06684 1.06604
 [10] 1.06514 1.06557 1.06456 1.06481 1.06414 1.06394 1.06364 1.06386 1.06239 1.06247
   | Time             |    Open      | Close double | Close float |
 0 | 2023.03.01 17:00 |   1.06660    |   1.06722    |   1.06722   |
 1 | 2023.03.01 18:00 |   1.06722    |   1.06733    |   1.06733   |
 2 | 2023.03.01 19:00 |   1.06734    |   1.06653    |   1.06653   |
 3 | 2023.03.01 20:00 |   1.06654    |   1.06520    |   1.06520   |
 4 | 2023.03.01 21:00 |   1.06520    |   1.06573    |   1.06573   |
 5 | 2023.03.01 22:00 |   1.06572    |   1.06649    |   1.06649   |
 6 | 2023.03.01 23:00 |   1.06649    |   1.06694    |   1.06694   |
 7 | 2023.03.02 00:00 |   1.06683    |   1.06675    |   1.06675   |
 8 | 2023.03.02 01:00 |   1.06675    |   1.06684    |   1.06684   |
 9 | 2023.03.02 02:00 |   1.06687    |   1.06604    |   1.06604   |
//---
  }

Ver também

Estruturas e classes, CopyRates