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] 用于从MqlRates结构接收时间序列的相应类型的数组。传递到函数的数组顺序必须与MqlRates结构中字段的顺序相匹配。

返回值

已复制元素的数量或-1（如果发生错误）。

注意

如果请求数据的整个区间超出服务器上可用的数据，函数返回-1。如果请求数据超出TERMINAL_MAXBARS（图表上最大柱形图数），该函数也返回 -1。

从指标请求数据时，如果请求的时间序列尚未构建或应从服务器下载，则该函数会立即返回 -1。但是，这将启动数据下载/自身构建。

当从EA交易或脚本请求数据时，如果程序端在本地没有合适的数据，则启动从服务器下载，或者如果可以从本地历史构建数据，但数据尚未准备好，则开始构建必要的时间序列。该函数返回超时到期时准备就绪的数据量，但是历史下载继续，该函数在下一次类似请求期间返回更多数据。

CopySeries和CopyRates之间的区别

CopySeries函数允许在一次调用期间仅将必要的时间序列获取到不同的指定数组中，同时所有的时间序列数据将被同步。这意味着结果数组中特定索引N处的所有值将属于指定交易品种/时间周期对上的同一柱形图。因此，程序员无需通过柱形图开仓时间来确保所有接收到的时间序列同步。

与将完整时间序列集作为MqlRates数组返回的CopyRates不同，CopySeries函数允许程序员仅将所需的时间序列获取为单独的数组。这可以通过指定标识组合来选择时间序列的类型来完成。传递到函数的数组顺序必须与MqlRates结构中字段的顺序相匹配：

struct MqlRates
  {
   datetime time;         // 期初
   double   open;         // 开仓价
   double   high;         // 该时段的最高价
   double   low;          // 该时段的最低价
   double   close;        // 平仓价
   long     tick_volume;  // 报价量
   int      spread;       // 点差
   long     real_volume;  // 交易量
  }

因此，如果您需要获取当前交易品种/时间周期的最近100柱形图的time，close和real_volume时间序列的值，您应该使用以下调用：

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 datetime InpDateFrom=D'2022.01.01 00:00:00';
input datetime InpDateTo  =D'2023.01.01 00:00:00';
input uint     InpCount   =20;
//+------------------------------------------------------------------+
//| 脚本程序起始函数                                                   |
//+------------------------------------------------------------------+
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  返回20个值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  返回20个值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

CopyRates CopyTime