Tracking event changes by country or currency

As mentioned in the section on basic concepts of the calendar, the platform registers all event changes by some internal means. Each state is characterized by a change identifier (change_id). Among the MQL5 functions, there are two that allow you to find this identifier (at an arbitrary point in time) and then request calendar entries changed later. One of these functions is CalendarValueLast, which will be discussed in this section. The second one, CalendarValueLastByEvent, will be discussed in the next section.

int CalendarValueLast(ulong &change_id, MqlCalendarValue &values[],
  const string country = NULL, const string currency = NULL)

The CalendarValueLast function is designed for two purposes: getting the last known calendar change identifier change_id and filling the values array with modified records since the previous modification given by the passed ID in the same change_id. In other words, the change_id parameter works as both input and output. That is why it is a reference and requires a variable to be specified.

If we input change_id equal to 0 into the function, then the function will fill the variable with the current identifier but will not fill the array.

Optionally, using parameters country and currency, you can set filtering records by country and currency.

The function returns the number of copied calendar items. Since the array is not populated in the first operation mode (change_id = 0), returning 0 is not an error. We can also get 0 if the calendar has not been modified since the specified change. Therefore, to check for an error, you should analyze _LastError.

So the usual way to use the function is to loop through the calendar for changes.

This can be done in a loop, on a timer, or on other events.

Identifiers are constantly increasing, but they can go out of order, that is, jump over several values.

It is important to note that each calendar entry is always available in only one last state: the history of changes is not provided in MQL5. As a rule, this is not a problem, since the life cycle of each news is standard: adding to the database in advance for a sufficiently long time and supplementing with relevant data at the time of the event. However, in practice, various deviations can occur: editing the forecast, transferring time, or revising the values. It is impossible to find out exactly what time and what was changed in the record through the MQL5 API from the calendar history. Therefore, those trading systems that make decisions based on the momentary situation will require independent saving of the history of changes and its integration into an Expert Advisor for running in the tester.

Using the CalendarValueLast function, we can create a useful service, CalendarChangeSaver.mq5, which will check the calendar for changes at the specified intervals and, if any, save the change identifiers to the file along with the current server time. This will allow further use of the file information for more realistic testing of Expert Advisors on the history of the calendar. Of course, this will require organizing the export/import of the entire calendar database, which we will deal with over time.

Let's provide input variables for specifying the file name and the period between polls (in milliseconds).

At the beginning of the OnStart handler, we open the binary file for writing, or rather for appending (if it already exists). The format of an existing file is not checked here and thus you should add protection when embedding in a real application.

Here we should make a small digression.

Each time the calendar is changed, at least a pair of integer 8-byte numbers must be written to the file: the current time (datetime) and news ID (ulong), but there can be more than one record changed at the same time. Therefore, in addition to the date, the number of changed records is packed into the first number. This takes into account that dates fit in 0x7FFFFFFFF and therefore the upper 3 bytes are left unused. It is in the two most significant bytes (at a left offset of 48 bits) that the number of identifiers that the service will write after the corresponding timestamp is placed. The PACK_DATETIME_COUNTER macro creates an "extended" date, and the other two, DATETIME and COUNTER, we will need later when the archive of changes is read (by another program).

Now let's go back to the main service code. In a loop that is activated every PeriodMsc milliseconds, we request changes using CalendarValueLast. If there are changes, we write the current server time and the array of received identifiers to a file.

For a convenient presentation of information about each news event, we have written a helper function Description.

Thus, the log will display not only the identifier but also the country code, title, and scheduled time of the news.

It is assumed that the service should work for quite a long time in order to collect information for a period sufficient for testing (days, weeks, months). Unfortunately, just like with the order book, the platform does not provide a ready-made history of the order book or calendar edits, so their collection is left entirely to the developer of MQL programs.

Let's see the service in action. In the next fragment of the log (for the time period of 2022.06.28, 15:30 - 16:00), some news events relate to the distant future (they contain the values of the prev_value field, which is also the actual_value field of the current event of the same name). However, something else is more important: the actual time of a news release can differ significantly, sometimes by several minutes, from the planned one.

Of course, this is important not for all classes of trading strategies, but only for those that trade quickly in the market. For them, the created archive of calendar edits can provide more accurate testing of news Expert Advisors. We will discuss how you can "connect" the calendar to the tester in the future, but for now, we will show how to read the received file.

We will use the script CalendarChangeReader.mq5 to demonstrate the discussed functionality. In practice, the given source code should be placed in the Expert Advisor.

The input variables allow you to set the name of the file to be read and the start date of the scan. If the service continues to work (write the file), you need to copy the file under a different name or to another folder (in the example script, the file is renamed). If the Start parameter is blank, the reading of news changes will start from the beginning of the current day.

The ChangeState structure is described to store information about individual edits.

It is used in the ChangeFileReader class, which does the bulk of the work of reading the file and providing the caller with the changes that are appropriate for a particular point in time.

The file handle is passed as a parameter to the constructor, as is the start time of the test. Reading a file and populating the ChangeState structure for one calendar edit is performed in the readState method.

Method check reads the file until the next edit appears in the future. In this case, all previous (by timestamps) edits since the previous method call are placed in the output array records.

Here is how the class is used in OnStart.

Here are the results of the script for the same calendar changes that were saved by the service in the context of the previous log fragment.

The same identifiers are reproduced in virtual time with the same delay as online, although here you can see the rounding to 1 minute, which happened because we set an artificial step of this size in the loop. In theory, for reasons of efficiency, we can postpone checks until the time stored in the ChangeState current structure. The attached source code defines the getState method to get this time.