Symbols and timeframes

Timeseries with quotes are identified by two parameters: symbol name (financial instrument) and timeframe (period).

The user can see the list of symbols in the Market Watch window and edit it based on the general list provided by the broker (dialog Symbols). For MQL programs, there is a set of functions that can be used to do the same: search in all symbols, find out their properties and add or remove symbols to/from Market Watch. These features will be the subject of a separate chapter.

However, to request timeseries, it is enough to know the name of the symbol — this is a string containing the designation of an existing financial instrument. It, for example, can be set by the user in the input variable. In addition, the symbol of the current chart can be found from the built-in variable _Symbol (or the Symbol function) but for our convenience, all timeseries functions support the convention that the NULL value also corresponds to the symbol of the current chart.

Now let's turn to timeframes. There are 21 standard timeframes defined in the system: each is specified by an element in the special enumeration ENUM_TIMEFRAMES.

As we saw in the section on Predefined variables, the program can learn the period of the current chart from the built-in variable _Period (or the Period function). It is easy to see from the column of values that passing zero to the built-in functions that accept a timeframe will mean the period of the current chart.

The value for minute timeframes is the same as the number of minutes in them (for example, 30 means M30). For hourly timeframes, bit 0x4000 is set, and the lower byte contains the number of hours (for example, 0x4003 for H3). Day period D1 is encoded as 24 hours, that is 0x4018 (0x18 is equal to 24). Finally, the weekly and monthly timeframes have their own distinguishing bits 0x8000 and 0xC000, respectively, as unit indicators, and the count (in the low byte) is 1 in both cases.

For convenient conversion of enumeration elements into strings and back, a header file Periods.mqh is attached to the book (we have already used it in the example of working with files, and will use it in future examples). One of its functions, StringToPeriod, uses in its algorithm the above-described features of the internal bit representation of enumeration elements.

Note that the _Symbol and _Period variables contain actual data only in the MQL programs that run on charts, including scripts, Expert Advisors, and indicators. In services, these variables are empty, and therefore, to access timeseries, you must explicitly set the symbol name and period or get them somehow from outside.

The defining property of a timeframe is its duration (bar duration). MQL5 allows you to get the number of seconds that form one bar of a specific timeframe using the PeriodSeconds function.

int PeriodSeconds(ENUM_TIMEFRAMES period = PERIOD_CURRENT)

The period parameter specifies the period as an element of the ENUM_TIMEFRAMES enumeration. If the parameter is not specified, then the number of seconds of the current chart period on which the program is running is returned.

We will consider examples of using the function in the indicator IndDeltaVolume.mq5 in the section Waiting for data and managing visibility, as well as in the indicator UseM1MA.mq5 in the section Using built-in indicators.

To generate timeframes of non-standard duration that are not included in the specified list, the MQL5 API provides custom symbols, however, they do not allow you to trade like on standard charts without modifying Expert Advisors.

In addition, it is important to note that in MetaTrader 5 the duration of bars within a particular timeseries or on a chart is always the same. Therefore, to build charts in which bars are formed not according to time, but as other parameters accumulate, in particular, volumes (equivolume charts) or price movement in one direction in fixed steps (Renko), you can develop your own solutions based on indicators (for example, with the DRAW_CANDLES or DRAW_BARS render type) or using custom symbols.