Référence MQL5Accès aux Séries de Données et aux IndicateursCopySeries

CopySeries

Retourne les timseries chronologiques de la structure MqlRates pour le symbole et la période spécifiés et pour la quantité demandée. Les données sont reçues dans les tableaux spécifiés. Les éléments sont comptés du présent vers le passé, ce qui signifie que la position de départ égale à 0 signifie la barre actuelle.

copyseries

Si la quantité de données à copier est inconnue, il est recommandé d'utiliser un tableau dynamique pour les tableaux destination, car si la quantité de données dépasse ce qu'un tableau peut contenir, cela peut entraîner la tentative de redistribution du tableau pour qu'il corresponde à toutes les données demandées.

Si vous avez besoin de copier une quantité prédéterminée de données, il est recommandé d'utiliser un buffer alloué statiquement pour éviter une réallocation de mémoire inutile.

La propriété du tableau destination – as_series=true ou as_series=false – sera ignorée : lors de la copie, l'élément de la série chronologique le plus ancien sera copié au début de la mémoire physique allouée au tableau.

int  CopySeries(
   string           symbol_name,       // nom du symbole
   ENUM_TIMEFRAMES  timeframe,         // période
   int              start_pos,         // position de départ
   int              count,             // quantité d'éléments à copier
   ulong            rates_mask,        // combinaison de flags pour spécifier les séries demandées
   void&            array1[],          // tableau destination de la première timeserie
   void&            array2[]           // tableau destination de la deuxième timeserie
   ...
   );

Paramètres

symbol_name

[in] Symbole.

timeframe

[in] Période.

start_pos

[in] Indice du premier élément copié.

count

[in] Nombre d'éléments copiés.

rates_mask

[in] une combinaison de flags de l'énumération ENUM_COPY_RATES.

array1, array2,...

[out] Tableaux destination des séries chronologiques d'éléments de type MqlRates. L'ordre des tableaux passés à la fonction doit correspondre à l'ordre des champs de la structure MqlRates.

Valeur de Retour

Le nombre d'éléments copiés ou -1 si une erreur se produit.

Note

Si l'intervalle entier des données demandées est au-delà des données disponibles sur le serveur, la fonction renvoie -1. Si les données demandées dépassent TERMINAL_MAXBARS (le nombre maximum de barres sur le graphique), la fonction renvoie également -1.

Lors de la demande de données à partir d'un indicateur, la fonction renvoie immédiatement -1 si les séries temporelles demandées ne sont pas encore construites ou si elles doivent être téléchargées depuis le serveur. Mais le téléchargement/la construction des données sera lancé.

Lorsque vous demandez des données à un Expert Advisor ou à un script, le téléchargement depuis le serveur est lancé si le terminal ne dispose pas localement des données correspondantes, ou la construction des données nécessaires est lancée si les données peuvent être construites à partir de l'historique local mais qu'elles ne sont pas encore prêtes. La fonction renvoie la quantité de données prêtes à l'expiration du délai d'attente. Mais le téléchargement de l'historique se poursuit et la fonction retourera plus de données lors de la prochaine requête similaire.

Différence entre CopySeries et CopyRates

La fonction CopySeries permet d'obtenir uniquement les séries temporelles nécessaires dans différents tableaux spécifiés au cours d'un appel, et toutes les données des séries temporelles seront synchronisées. Cela signifie que toutes les valeurs des tableaux destination à un certain indice N appartiendront à la même barre sur la paire Symbole/Timeframe spécifiée. Le développeur n'a donc pas besoin d'assurer la synchronisation de toutes les séries temporelles reçues par l'heure d'ouverture de la barre.

Contrairement à CopyRates, qui renvoie l'ensemble complet des séries temporelles sous forme de tableau MqlRates, la fonction CopySeries permet au programmeur d'obtenir uniquement les séries temporelles requises sous forme de tableaux séparés. Cela peut être fait en spécifiant une combinaison d'indicateurs pour sélectionner le type de séries chronologiques. L'ordre des tableaux passés à la fonction doit correspondre à l'ordre des champs dans la structure MqlRates :

struct MqlRates
  {
   datetime time;         // heure de début
   double   open;         // prix d'ouverture
   double   high;         // prix le plus haut pour la période
   double   low;          // prix le plus bas pour la période
   double   close;        // prix de clôture
   long     tick_volume;  // volume du tick
   int      spread;       // spread
   long     real_volume;  // volume d'échange
  }

Donc, si vous avez besoin d'obtenir les séries chronologiques des valeurs time, close et real_volume pour les 100 dernières barres du symbole/période actuels, vous devez utiliser l'appel suivant :

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

Faites bien attention à l'ordre des tableaux "time, close, volume" – il doit correspondre à l'ordre des champs dans la stucture MqlRates. L'ordre des valeurs dans rates_mask n'est pas important. Le masque pourrait être le suivant :

COPY_RATES_VOLUME_REAL|COPY_RATES_TIME|COPY_RATES_CLOSE

Exemple :

//--- paramètres d'entrée
input datetime InpDateFrom=D'2022.01.01 00:00:00';
input datetime InpDateTo  =D'2023.01.01 00:00:00';
input uint     InpCount   =20;
//+------------------------------------------------------------------+
//| Fonction de démarrage du programme |
//+------------------------------------------------------------------+
void OnStart(void)
  {
//--- tableaux destination des timeseries de la structure de prix MqlRates
   double   open[];
   double   close[];
   float    closef[];
   datetime time1[], time2[];
//--- demande des prîx de clôture dans un tableau d'éléments de type double
   ResetLastError();
   int res1=CopySeries(NULL, PERIOD_CURRENT, 0, InpCount,
                       COPY_RATES_TIME|COPY_RATES_CLOSE, time1, close);
   PrintFormat("1. CopySeries a retourné %d valeurs. Code d'erreur=%d", res1, GetLastError());
   ArrayPrint(close);

//--- demande maintenant les prix d'ouverture ; utilise un tableau de float pour les prix de clôture
   ResetLastError();
   int res2=CopySeries(NULL, PERIOD_CURRENT, 0, InpCount,
                       COPY_RATES_TIME|COPY_RATES_CLOSE|COPY_RATES_OPEN, time2, open, closef);
   PrintFormat("2. CopySeries a retourné %d valeurs. Code d'erreur=%d", res2, GetLastError());
   ArrayPrint(closef);
//--- Compare les données reçues
   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]);
        }
     }
//--- Résultat
1. CopySeries a retourné 20 valeurs. Code d'erreur=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 a retourné 20 valeurs. Code d'erreur=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   |
S3 | 2023.03.01 20:00 |   1.06654    |   1.06520    |   1.06520   |
S4 | 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   |
//---
  }

Voir aussi

Structures et classes, CopyRates

CopyRates

CopyTime