MQL4 Reference Array Functions ArrayCopyRates

ArrayCopyRates

Copies rates data to the array and returns the amount of bars copied. There are 2 variants of the function:

int  ArrayCopyRates(
   MqlRates&  rates_array[],   // MqlRates array, passed by reference
   string     symbol=NULL,     // symbol
   int        timeframe=0      // timeframe
   );

Copies rates data to the RateInfo[][6] two-dimensional array of double type and returns the amount of bars copied.

int  ArrayCopyRates(
   void&     dest_array[][],    // destination array, passed by reference
   string    symbol=NULL,       // symbol
   int       timeframe=0        // timeframe
   );

Parameters

rates_array[]

[out] Destination array of MqlRates type.

dest_array[]

[out] Two-dimensional destination array of double type.

symbol=NULL

[in] Symbol name.

timeframe=0

[in] Timeframe. It can be any of ENUM_TIMEFRAMES enumeration values. 0 means the current chart timeframe.

Returned value

The function returns copied bars amount, or -1 if failed.

If data (symbol name and/or timeframe differ from the current ones) are requested from another chart, the situation is possible that the corresponding chart was not opened in the client terminal and the necessary data must be requested from the server. In this case, error ERR_HISTORY_WILL_UPDATED (4066 - the requested history data are under updating) will be placed in the last_error variable, and one will has to re-request (see example of ArrayCopySeries()).

Note

This rates array is normally used to pass data to a DLL function.

In the first variant of the function it performs the virtual data copying to the array of MqlRates type. It means that if timeseries data has been updated, rates_array[] array always will refer to the actual data.

In the second variant it performs the real data copying to dest_array[][] array. The destination array will be resized to the size of the timeseries (even if the destination array has been declared as static).

First dimension of RateInfo array contains bars amount, second dimension has 6 elements:

0 - time,
1 - open,
2 - low,
3 - high,
4 - close,
5 - volume.

Example:

#property copyright "Copyright © 2013, MetaQuotes Software Corp."
#property link      "https://www.mql5.com"
#property version   "1.00"
#property strict
#property description "Expert Advisor displaying two cases of"
#property description "ArrayCopyRates() function call"
//--- destination array for physical copying of historical data
double   double_array[][6];
//--- destination array for logical copying of historical data
MqlRates mqlrates_array[];
//--- first call flag
bool first_call;
//+------------------------------------------------------------------+
//| Expert initialization function                                   |
//+------------------------------------------------------------------+
int OnInit()
  {
//--- run this EA at chart with M1 timeframe
   if(Period()!=PeriodSeconds(PERIOD_M1)/60)
     {
     Alert("The Expert Advisor must be attached to M1 chart!");
     return(INIT_FAILED);
     }
//--- first call
   first_call=true;
//--- all ok
   return(INIT_SUCCEEDED);
  }
//+------------------------------------------------------------------+
//| Expert deinitialization function                                 |
//+------------------------------------------------------------------+
void OnDeinit(const int reason)
  {
//--- delete all comments
   Comment("");
  }
//+------------------------------------------------------------------+
//| Expert tick function                                             |
//+------------------------------------------------------------------+
void OnTick()
  {
//---
   if(first_call)
     {
      //--- copying physically  double_array
      ArrayCopyRates(double_array,NULL,0);
      //--- virtual copying -> mqlrates_array will contain the reference on the data
      ArrayCopyRates(mqlrates_array,NULL,0);
      //--- cancel first call flag
      first_call=false;
     }
   //--- at each tick print the values of the 0-th array element to see the difference
   Comment("The values of double_array[] are not changed (because of real data copying):\n",
           "0 - time: ",(datetime)double_array[0][0],"\n",
           "1 - open: ",double_array[0][1],"\n"
           "2 - low: ",double_array[0][2],"\n"
           "3 - high: ",double_array[0][3],"\n"
           "4 - close: ",double_array[0][4],"\n"
           "5 - volume: ",DoubleToString(double_array[0][5],0),"\n\n",
           "The values of mqlrates_array[] are changed (because of virtual data copying):\n",
           "0 - time: ",mqlrates_array[0].time,"\n",
           "1 - open: ",mqlrates_array[0].open,"\n"
           "2 - low: ",mqlrates_array[0].low,"\n"
           "3 - high: ",mqlrates_array[0].high,"\n"
           "4 - close: ",mqlrates_array[0].close,"\n"
           "5 - volume: ",mqlrates_array[0].tick_volume);
  }

ArrayCopyRates

ArraySortArrayCopySeries