ДокументацияРазделы
Справочник MQL5Доступ к таймсериям и индикаторамCopySeries 

CopySeries

Получает в указанный набор массивов синхронизированные таймсерии из структуры MqlRates для указанного символа-периода в указанном количестве. Отсчет элементов от стартовой позиции ведется от настоящего к прошлому, то есть стартовая позиция, равная 0, означает текущий бар.

copyseries

При копировании заранее неизвестного количества данных рекомендуется в качестве приемных массивов использовать динамический массив, так как если данных оказывается больше, чем вмещает массив, то производится попытка перераспределения массива таким образом, чтобы запрошенные данные поместились целиком и полностью.

Если необходимо копировать заранее известное количество данных, то лучше это делать в статически выделенный буфер, чтобы избежать излишнего перевыделения памяти.

Неважно, какое свойство имеет приемный массив – as_series=true или as_series=false, данные будут скопированы таким образом, что самый старый по времени элемент таймсерии будет скопирован в начало физической памяти, отведенной под массив.

int  CopySeries(
   string           symbol_name,       // имя символа
   ENUM_TIMEFRAMES  timeframe,         // период
   int              start_pos,         // откуда начнем 
   int              count,             // сколько копируем
   ulong            rates_mask,        // комбинация флагов для указания запрашиваемых серий
   void&            array1[],          // массив, куда будут скопированы данные первой таймсерии
   void&            array2[]           // массив, куда будут скопированы данные второй таймсерии
   ...
   );

Параметры

symbol_name

[in]  Символ.

timeframe

[in]  Период.

start_pos

[in]  Номер первого копируемого элемента.

count

[in]  Количество копируемых элементов.

rates_mask

[in]  Комбинация флагов из перечисления ENUM_COPY_RATES .

array1, array2,...

[out]  Массив cоответствующего типа для получения таймсерии из структуры MqlRates. Порядок массивов, передаваемых в функцию, должен соответствовать порядку полей в структуре MqlRates.

Возвращаемое значение

Количество скопированных элементов массива либо -1 в случае ошибки.

Примечание

Если интервал запрашиваемых таймсерий полностью находится вне доступных данных на сервере, то функция возвращает -1. В случае если запрашиваемые данные находятся за пределами TERMINAL_MAXBARS (максимальное количество баров на графике), функция также вернет -1.

При запросе данных из индикатора, если запрашиваемые таймсерии еще не построены или их необходимо загрузить с сервера, то функция сразу же вернет -1, но при этом сам процесс загрузки/построения будет инициирован.

При запросе данных из эксперта или скрипта, будет инициирована загрузка с сервера, если локально этих данных у терминала нет, либо начнется построение нужной таймсерии, если данные можно построить из локальной истории, но они еще не готовы. Функция вернет то количество данных, которые будут готовы к моменту истечения таймаута, но загрузка истории будет продолжаться, и при следующем аналогичном запросе функция вернет уже больше данных.

Разница между CopySeries и CopyRates

Функция CopySeries позволяет за один раз получать только нужные таймсерии в разные указанные массивы, при этом они все синхронизированы между собой. Это означает, что все значения в полученных массивах по конкретному индексу N будут принадлежать одному и тому же бару на указанной паре Символ/Таймрейм.  В этом случае программисту не требуется заботиться о том, чтобы все полученные таймсерии были синхронизированы по времени открытия бара.

В отличие от CopyRates, которая возвращает полный набор таймсерий в виде массива MqlRates, функция CopySeries позволяет программисту получать только нужные таймсерии в виде отдельных массивов, для этого необходимо указать комбинацию флагов для указания типа запрашиваемых таймсерий. При этом порядок массивов передаваемых в функцию должен соответствовать порядку полей в структуре MqlRates:

struct MqlRates
  {
   datetime time;         // время начала периода
   double   open;         // цена открытия
   double   high;         // наивысшая цена за период
   double   low;          // наименьшая цена за период
   double   close;        // цена закрытия
   long     tick_volume;  // тиковый объем
   int      spread;       // спред
   long     real_volume;  // биржевой объем
  }

Таким образом, если необходимо получить значения таймсерий time, close и real_volume для последних 100 баров текущего Символа/Таймфрема, то вызов должен быть следующим:

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

При этом важен порядок массивов "time, close, volume" — он должен соответствовать порядку полей в структуре MqlRates. А вот порядок значений в маске rates_mask значения не имеет, маска могла быть такой :

COPY_RATES_VOLUME_REAL|COPY_RATES_TIME|COPY_RATES_CLOSE

Пример:

//--- 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)
  {
//--- массивы для получения таймсерий из ценовой структуры MqlRates
   double   open[];
   double   close[];
   float    closef[];
   datetime time1[], time2[];
//---запросим цены закрытия в массив типа 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);
  
//--- теперь запросим еще цены открытия, а цены закрытия в массив типа 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);
//--- сравним полученные данные
   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]);
        }
     }
//--- Результат 
 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   |
//---
  }

Смотри также

Структуры и классы, CopyRates