MQL5 · Indicateurs
Handles d’indicateurs et CopyBuffer en MQL5 : lire les valeurs d’un indicateur
Créer un handle d’indicateur, copier ses buffers avec CopyBuffer, vérifier que les données sont prêtes et libérer la mémoire : le mécanisme commun à tous les indicateurs MQL5.
Pour lire un indicateur en MQL5, vous procédez en deux temps : vous créez un handle avec une fonction comme iMA() ou iRSI(), généralement dans OnInit(), puis vous copiez les valeurs calculées dans un tableau double avec CopyBuffer(), généralement dans OnTick(). Le handle est un simple entier qui désigne une copie de l’indicateur calculée et tenue à jour par le terminal ; CopyBuffer() renvoie le nombre de valeurs copiées, ou -1 en cas d’erreur. Cette page explique ce mécanisme en détail, car toutes les autres pages de la rubrique Indicateurs en MQL5 s’appuient dessus.
Qu’est-ce qu’un handle d’indicateur ?
La documentation MQL5 précise que toutes les fonctions comme iMA, iAC, iMACD ou iIchimoku créent une copie de l’indicateur technique correspondant dans le cache global du terminal. Si une copie avec exactement les mêmes paramètres existe déjà, aucune nouvelle copie n’est créée : le terminal incrémente seulement un compteur de références. Appeler plusieurs fois la même fonction avec les mêmes paramètres dans un même programme n’augmente ce compteur qu’une seule fois.
Le handle renvoyé est un int. S’il vaut INVALID_HANDLE, la création a échoué (symbole inexistant, paramètre invalide, mémoire insuffisante). Ce test est la première chose à faire : un EA qui continue avec un handle invalide ne lira jamais aucune valeur.
Point essentiel souligné par la documentation : on ne peut pas lire les données d’un indicateur immédiatement après sa création, car le calcul prend du temps. C’est pourquoi les handles se créent dans OnInit() et se lisent plus tard. Si vous débutez avec les fonctions événementielles, la page Les fonctions événementielles rappelle le rôle de OnInit(), OnTick() et OnDeinit().
La fonction CopyBuffer et ses trois variantes
CopyBuffer() existe en trois surcharges, qui diffèrent par la façon de désigner la plage à copier :
int CopyBuffer(int indicator_handle, int buffer_num, int start_pos, int count, double buffer[]);
int CopyBuffer(int indicator_handle, int buffer_num, datetime start_time, int count, double buffer[]);
int CopyBuffer(int indicator_handle, int buffer_num, datetime start_time, datetime stop_time, double buffer[]);
| Paramètre | Rôle |
|---|---|
| indicator_handle | handle renvoyé par la fonction iXXX |
| buffer_num | numéro du buffer à lire (0 pour la première ligne) |
| start_pos | position de départ, 0 = bougie en cours |
| count | nombre de valeurs à copier |
| start_time / stop_time | bornes temporelles de la copie |
| buffer[] | tableau de réception, de type double |
La première variante, par position, est de loin la plus utilisée dans les EA. La documentation indique que le comptage se fait du présent vers le passé : une position de départ égale à 0 désigne la bougie courante, donc la dernière valeur de l’indicateur. Les variantes par date servent surtout pour aligner des données de plusieurs unités de temps ou pour extraire une période précise dans un script d’analyse.
Le sens du tableau de réception
C’est le piège classique. Quelle que soit la propriété « série » du tableau, CopyBuffer() place l’élément le plus ancien au début de la mémoire physique. Si vous ne faites rien, buf[0] contient donc la valeur la plus ancienne copiée et la dernière case contient la bougie courante. Si vous appelez ArraySetAsSeries(buf, true) avant la lecture, l’indexation s’inverse : buf[0] devient la bougie courante, buf[1] la bougie précédente, etc. C’est la convention utilisée dans tous les exemples de cette rubrique, car elle correspond à la façon dont un trader désigne les bougies. La page ArraySetAsSeries et indexation des séries détaille ce comportement.
Tableau dynamique ou statique
Avec un tableau dynamique (double buf[];), CopyBuffer() redimensionne lui-même le tableau au nombre de valeurs copiées. Quand le nombre de valeurs est connu et faible (trois valeurs pour un croisement, par exemple), la documentation recommande un tableau statique pour éviter des allocations inutiles. Dans un EA, les deux fonctionnent ; l’important est de vérifier le nombre renvoyé.
Quand les données ne sont pas prêtes
La documentation distingue deux cas. Dans un indicateur, si les données demandées ne sont pas encore prêtes, CopyBuffer() renvoie immédiatement -1 et le terminal lance le téléchargement ou la construction de la série. Dans un script ou un EA, le terminal peut lancer un téléchargement depuis le serveur et la fonction renvoie la quantité de données prête à l’expiration d’un délai. Conséquence pratique : un EA doit toujours comparer la valeur renvoyée au nombre demandé, et non seulement tester -1.
Pour savoir si un indicateur a fini son calcul, BarsCalculated(handle) renvoie le nombre de valeurs calculées dans le buffer, ou -1 si les données ne sont pas encore calculées. Elle est utile dans un script, qui s’exécute une seule fois et ne peut pas « attendre le tick suivant ». Dans un EA, la règle la plus simple consiste à sortir de OnTick() quand la copie est incomplète : le tick suivant fera une nouvelle tentative.
Libérer un handle avec IndicatorRelease
IndicatorRelease(handle) supprime le handle et renvoie true en cas de succès. Le handle est retiré immédiatement ; le bloc de calcul est supprimé un peu plus tard s’il n’est plus utilisé par aucun programme. La documentation précise que dans le Strategy Tester, IndicatorRelease() n’est pas exécutée. Appelez-la dans OnDeinit() : c’est une bonne hygiène en compte réel, surtout pour un EA qui crée des handles sur plusieurs symboles.
Exemple complet : un squelette d’EA réutilisable
L’EA ci-dessous crée deux handles (une moyenne mobile et un RSI), vérifie leur validité, lit trois valeurs de chacun à chaque nouvelle bougie et les affiche. Il ne passe aucun ordre : c’est un gabarit à recopier pour n’importe quel indicateur.
//+------------------------------------------------------------------+
//| Squelette de lecture d'indicateurs avec CopyBuffer |
//+------------------------------------------------------------------+
input int InpMaPeriod = 50; // Période de la moyenne mobile
input int InpRsiPeriod = 14; // Période du RSI
int hMa = INVALID_HANDLE; // handle de la moyenne mobile
int hRsi = INVALID_HANDLE; // handle du RSI
int OnInit()
{
// Création des handles une seule fois
hMa = iMA(_Symbol, _Period, InpMaPeriod, 0, MODE_EMA, PRICE_CLOSE);
hRsi = iRSI(_Symbol, _Period, InpRsiPeriod, PRICE_CLOSE);
if(hMa == INVALID_HANDLE || hRsi == INVALID_HANDLE)
{
Print("Création des handles impossible, erreur ", GetLastError());
return(INIT_FAILED);
}
return(INIT_SUCCEEDED);
}
void OnDeinit(const int reason)
{
// Libération propre des handles
if(hMa != INVALID_HANDLE) IndicatorRelease(hMa);
if(hRsi != INVALID_HANDLE) IndicatorRelease(hRsi);
}
// Copie 'count' valeurs d'un buffer, indexées comme une série (0 = bougie en cours)
bool ReadBuffer(int handle, int buffer, int count, double &dest[])
{
ArraySetAsSeries(dest, true);
int copied = CopyBuffer(handle, buffer, 0, count, dest);
if(copied < count)
{
// -1 = erreur ou données pas prêtes ; moins que count = historique incomplet
PrintFormat("CopyBuffer : %d/%d valeurs (erreur %d)", copied, count, GetLastError());
return(false);
}
return(true);
}
void OnTick()
{
// On ne travaille qu'à l'ouverture d'une nouvelle bougie
static datetime lastBar = 0;
datetime barTime = iTime(_Symbol, _Period, 0);
if(barTime == lastBar) return;
double ma[], rsi[];
if(!ReadBuffer(hMa, 0, 3, ma)) return; // on réessaiera au tick suivant
if(!ReadBuffer(hRsi, 0, 3, rsi)) return;
lastBar = barTime; // bougie traitée seulement si la lecture a réussi
// Indice 1 = dernière bougie clôturée, valeur définitive
PrintFormat("Bougie clôturée : EMA=%.5f RSI=%.2f", ma[1], rsi[1]);
}
Remarquez que lastBar n’est mis à jour qu’après une lecture réussie. Si la copie échoue au premier tick de la bougie, l’EA réessaie au tick suivant au lieu de sauter la bougie entière. La méthode de détection elle-même est développée dans Détecter une nouvelle bougie.
Lire un indicateur à plusieurs buffers
Le paramètre buffer_num sélectionne la ligne. La documentation donne la correspondance pour chaque fonction : iMACD expose 0 pour la ligne principale et 1 pour la ligne de signal, iBands expose 0 pour la ligne médiane, 1 pour la bande haute et 2 pour la bande basse, iIchimoku en expose cinq. Pour certains indicateurs, la documentation autorise à passer un identifiant de ligne à la place du numéro (MAIN_LINE, SIGNAL_LINE, UPPER_BAND…). Ces constantes ne forment pas toujours une suite continue (pour iGator, LOWER_HISTOGRAM vaut 2) : utilisez toujours la valeur documentée plutôt que de supposer un ordre.
Bonnes pratiques et pièges fréquents
- Lire la bougie clôturée. La valeur d’indice 0 change à chaque tick. Un signal fondé sur elle peut apparaître puis disparaître pendant la bougie. Préférez l’indice 1 pour décider, et réservez l’indice 0 aux gestions intra-bougie (trailing stop, par exemple).
- Tester la quantité copiée.
if(CopyBuffer(...) <= 0)ne suffit pas : une copie partielle laisse des cases non remplies et provoque un Array out of range quand vous accédez à l’indice attendu. - Ne pas recréer les handles à chaque tick. Même si le cache évite un double calcul, la création répétée coûte du temps et complique le débogage.
- Gérer l’historique. En multi-unité de temps ou multi-symbole, la première lecture peut échouer tant que l’historique n’est pas chargé. Prévoyez des tentatives répétées plutôt qu’un arrêt de l’EA.
- Valeurs vides. Certains indicateurs, comme les fractales, remplissent les bougies sans signal avec
EMPTY_VALUE. Testez cette valeur avant de l’utiliser dans un calcul.
Alternative : IndicatorCreate
La documentation mentionne aussi IndicatorCreate(), une méthode universelle qui crée n’importe quel indicateur à partir d’un type (IND_MA, IND_RSI…) et d’un tableau de paramètres MqlParam. Elle sert surtout quand le type d’indicateur est choisi à l’exécution. Pour un EA classique, les fonctions iXXX sont plus lisibles et vérifiées à la compilation.
FAQ
Pourquoi CopyBuffer renvoie-t-il moins de valeurs que demandé ?
Dans un EA ou un script, la fonction renvoie la quantité de données prête à l’expiration du délai d’attente. L’historique peut être incomplet ou l’indicateur pas encore calculé. Testez toujours le nombre renvoyé et réessayez au tick suivant.
Dois-je appeler ArraySetAsSeries avant ou après CopyBuffer ?
Avant ou après fonctionne, car la propriété ne change que l’indexation d’accès. L’appeler juste avant la copie, comme dans l’exemple, évite de l’oublier. Sans cet appel, l’indice 0 désigne la valeur la plus ancienne copiée.
IndicatorRelease est-elle obligatoire ?
Non, mais elle libère la mémoire quand un handle n’est plus utilisé. Dans le Strategy Tester, la documentation précise qu’elle n’est pas exécutée. En réel, appelez-la dans OnDeinit().
Que vaut la position 0 dans CopyBuffer ?
La position 0 désigne la bougie courante, encore en formation. La position 1 désigne la dernière bougie clôturée.
- iMA : moyennes mobiles
- iRSI : Relative Strength Index
- iMACD
- iBands : bandes de Bollinger
- iATR : Average True Range
- iStochastic
- iADX
- iCCI
- iMomentum
- iIchimoku
- iSAR : Parabolic SAR
- iEnvelopes
- iWPR : Williams %R
- iAO : Awesome Oscillator
- iAC : Accelerator Oscillator
- iAlligator
- iFractals
- iOBV : On Balance Volume
- iMFI : Money Flow Index
- iVolumes
- iStdDev : écart-type
- iDeMarker
- iBearsPower et iBullsPower
- iForce
- iOsMA
- iRVI
- iAMA : moyenne mobile adaptative
- iDEMA et iTEMA
- iFrAMA
- iCustom : appeler un indicateur personnalisé
- Créer un indicateur personnalisé
- Buffers et styles de tracé
- OnCalculate et prev_calculated
- Indicateur multi-timeframe
- Objets graphiques (ObjectCreate)
