Manual de referencia de MQL5Procesamiento de eventosOnBookEvent

OnBookEvent

Se llama en los indicadores y expertos al suceder el evento BookEvent. La función está pensada para el procesamiento de los cambios de la profundidad del mercado (Depth of Market).

void  OnBookEvent(
   const string&  symbol         // símbolo
   );

Parámetros

symbol

[in] Nombre del instrumento financiero según el cual ha tenido lugar el evento BookEvent

Valor retornado

No hay valor retornado

Observación

Para obtener el evento BookEvent de cualquier símbolo, basta con suscribirse preliminarmente para recibir estos eventos para este símbolo con la ayuda de la función MarketBookAdd(). Si queremos anular la suscripción para recibir el evento BookEvent de un símbolo concreto, debemos llamar la función MarketBookRelease().

El evento BookEvent retransmite dentro de los límites del gráfico. Esto significa que basta con que una aplicación en el gráfico se suscriba para recibir el evento BookEvent con la ayuda de la función MarketBookAdd, y todos los demás indicadores y expertos iniciados en este gráfico y que además tengan el manejador OnBookEvent() recibirán este evento. Por eso mismo, es necesario analizar el nombre del símbolo que se transmite al manejador OnBookEvent() como parámetro symbol.

Para todas las aplicaciones iniciadas en un gráfico se dispone de contadores aparte para recibir los eventos BookEvent para cada símbolo por separado. Esto significa que en cada gráfico puede haber varias suscripciones a varios símbolos, y para cada símbolo hay un contador propio. La suscripción y la baja de la suscripción de los eventos de BookEvent solo cambian el contador de suscripciones de los símbolos indicados, pero en este caso, además, solo dentro de los límites del gráfico. Esto significa que en dos gráficos colindantes puede haber suscripciones a los eventos BookEvent en el mismo símbolo, pero con diferentes valores en los contadores de suscripciones.

El valor inicial del contador de suscripciones es igual a cero. Con cada llamada de MarketBookAdd(), el contador de suscripciones para el símbolo indicado en cada gráfico aumenta en una unidad (el símbolo del gráfico y el símbolo en MarketBookAdd() no deben coincidir obligatoriamente). Al llamar a MarketBookRelease(), el contador de suscripciones del símbolo indicado en los límites del gráfico disminuye en una unidad. La transmisión de los eventos BookEvent de cualquier símbolo dentro del gráfico continúa hasta que el contador de suscripciones del símbolo dado no sea igual a cero. Por eso, es importante que cada programa MQL5 que contenga llamadas a MarketBookAdd(), al finalizar su funcionamiento deje de estar suscrita para recibir eventos de cada símbolo utilizado con la ayuda de MarketBookRelease(). Para ello, basta con que el número de llamadas a MarketBookAdd() y MarketBookRelease() de cada llamada sea par durante el tiempo de vida útil del programa MQL5. El uso de banderas o contadores propios de suscripciones dentro del programa permite trabajar de forma segura con los eventos de BookEvent y previene contra la desactivación de las suscripciones para obtener este evento en terceros programas dentro de un mismo gráfico.

Los eventos BookEvent nunca se omiten y siempre se ponen en la cola, incluso si en este momento aún no ha finalizado el procesamiento del anterior evento BookEvent. En este caso, además, es necesario tener en cuenta que los eventos BookEvent se entregan por sí mismos y no portan en ellos el estado de la profundidad de mercado. Esto significa que la llamada a MarketBookGet() desde el manejador OnBookEvent() permite recibir el estado actual de la profundidad de mercado en el momento de la llamada, y no el estado de la profundidad de mercado que provocó el envío del evento BookEvent. Para recibir todos los estados únicos de la profundidad de mercado de forma garantizada, la función OnBookEvent() deberá ser lo más rápida posible.

Ejemplo

//+------------------------------------------------------------------+
//|                                           OnBookEvent_Sample.mq5 |
//|                        Copyright 2018, MetaQuotes Software Corp. |
//|                                             https://www.mql5.com |
//+------------------------------------------------------------------+
#property copyright "Copyright 2000-2024, MetaQuotes Ltd."
#property link      "https://www.mql5.com/es/articles/2635"
#property version   "1.00"
#property description "Ejemplo de medición de la velocidad de la actualización de la profundidad de mercado con la ayuda de OnBookEvent()"
#property description "El código se ha tomado del artículo https://www.mql5.com/es/articles/2635"
//--- parámetros de entrada
input ulong ExtCollectTime   =30;  // tiempo de simulación en segundos
input ulong ExtSkipFirstTicks=10;  // número de ticks omitidos al inicio
//--- bandera de inicio de suscripción para recibir los eventos de BookEvent
bool book_subscribed=false;
//--- matriz para recibir las solicitudes de la profundidad de mercado
MqlBookInfo  book[];
//+------------------------------------------------------------------+
//| Expert initialization function                                   |
//+------------------------------------------------------------------+
int OnInit()
  {
//--- mostramos el inicio
   Comment(StringFormat("Esperamos la llegada de los primeros %I64u ticks",ExtSkipFirstTicks));
   PrintFormat("Esperamos la llegada de los primeros %I64u ticks",ExtSkipFirstTicks);
//--- activamos la retransmisión de la profundidad de mercado
   if(MarketBookAdd(_Symbol))
     {
      book_subscribed=true;
      PrintFormat("%s: la función MarketBookAdd(%s) ha retornado true",__FUNCTION__,_Symbol);
     }
   else
      PrintFormat("%s: la función MarketBookAdd(%s) ha retornado false! GetLastError()=%d",__FUNCTION__,_Symbol,GetLastError());
//--- la inicialización ha tenido éxito
   return(INIT_SUCCEEDED);
  }
//+------------------------------------------------------------------+
//| Deinitialize expert                                              |
//+------------------------------------------------------------------+
void OnDeinit(const int reason)
  {
//--- mostramos el código del motivo de la desinicialización
   Print(__FUNCTION__,": Código del motivo de la desinicialización = ",reason);
//--- cancelamos nuestra suscripción para recibir los eventos de la profundidad del mercado
   if(book_subscribed)
     {
      if(!MarketBookRelease(_Symbol))
         PrintFormat("%s: MarketBookRelease(%s) ha retornado false! GetLastError()=%d",_Symbol,GetLastError());
      else
         book_subscribed=false;
     }
//---
  }
//+------------------------------------------------------------------+
//| BookEvent function                                               |
//+------------------------------------------------------------------+
void OnBookEvent(const string &symbol)
  {
   static ulong starttime=0;             // hora de inicio de la simulación
   static ulong tickcounter=0;           // contador de actualizaciones de la profundidad de mercado
//--- trabajamos con los eventos de la profundidad de mercado solo en el caso de que nos hayamos suscrito a esta por nosotros mismos
   if(!book_subscribed)
      return;
//--- calculamos las actualizaciones solo de nuestro símbolo
   if(symbol!=_Symbol)
      return;
//--- omitimos los primeros ticks para realizar la limpieza primaria de la cola y el calentamiento
   tickcounter++;
   if(tickcounter<ExtSkipFirstTicks)
      return;
//--- recordamos la hora de inicio
   if(tickcounter==ExtSkipFirstTicks)
      starttime=GetMicrosecondCount();
//--- solicitamos los datos de la profundidad de mercado
   MarketBookGet(symbol,book);
//--- ¿cuando debemos detenernos?
   ulong endtime=GetMicrosecondCount()-starttime;
   ulong ticks  =1+tickcounter-ExtSkipFirstTicks;
// ¿cuánto tiempo ha pasado en microsegundos desde el inicio de la simulación?
   if(endtime>ExtCollectTime*1000*1000)
     {
      PrintFormat("%I64u ticks for %.1f seconds: %.1f ticks/sec ",ticks,endtime/1000.0/1000.0,ticks*1000.0*1000.0/endtime);
      ExpertRemove();
      return;
     }
//--- mostrar los contadores en el campo del comentario
   if(endtime>0)
      Comment(StringFormat("%I64u ticks for %.1f seconds: %.1f ticks/sec ",ticks,endtime/1000.0/1000.0,ticks*1000.0*1000.0/endtime));
  }

Ver también

MarketBookAdd, MarketBookRelease, MarketBookGet, OnTrade, OnTradeTransaction, OnTick, funciones de procesamiento de eventos, Ejecución de programas, Eventos del terminal de cliente

OnTradeTransaction

OnChartEvent