Often when generating a MultiCharts alert, we want to include a message with alert information. That message appears in the notification window, email alert, and Order and Position Tracker window. But how can those alert messages contain dates in an understandable format?

In this article:

Generating MultiCharts alert messages with date information

We generate alerts programmatically with the Alert() keyword (PowerLanguage Keyword Reference, 2016). Before a script can fire those alerts, we have to enable its alert settings and likely want to configure the alert settings too.

With Alert() we can generate alert messages that contain no text, or we can use a static or dynamic string in the alert message (PowerLanguage Keyword Reference, 2016). When we use both static and dynamic text (like "New high" with the bar’s high, for instance), then we either use the + operator or the Text() keyword to combine different text pieces into an alert message.

When we want those messages to contain dates, there’s a problem: dates in PowerLanguage are in a numerical format that’s hard to read. That’s because that date format is YYYMMdd, where YYY are the number of years since 1900, MM represents the month, and dd is the day of month (PowerLanguage Keyword Reference, 2016). And so a date of September 8, 2016, is returned as 1160908.

Some keywords that use that date format are (PowerLanguage Keyword Reference, 2016):

Keyword Description
CurrentDate Returns the computer’s current date as a numerical value in YYYMMdd format.
Date Returns the bar’s closing date as a numerical value in YYYMMdd format.

Especially in an alert that can disappear after a couple of seconds, that date format is hard to read. For instance, if we generate an alert message like this:


Alert(Text("The current date is: ", CurrentDate));

Then the notification window that pops up looks like:

Example of a standard MultiCharts alert with the date included

Luckily, it’s possible to format dates in any format we want. Let’s take a closer look at that.

Printing PowerLanguage dates in a custom, readable format

We format dates to a readable text with FormatDate(), a keyword that requires a DateTime value and a format string (PowerLanguage Keyword Reference, 2016).

The DateTime format is an alternative way for represent a time and a date combined in a single numerical value. For this a DateTime value consists out of a number with decimals. The integer part of that number represents the elapsed days since January 1, 1900, while the fractional part is the portion of the day that has elapsed since midnight (PowerLanguage Keyword Reference, 2016). These two combined make a DateTime value represent both a date and time of day.

To convert the dates returned by the Date and CurrentDate keywords (from the table above) to DateTime format, we use the DateToJulian(). That keyword has one parameter: the date in YYYMMdd format (PowerLanguage Keyword Reference, 2016).

Besides a DateTime value, the FormatDate() keyword also requires a format string that specifies how the DateTime value should be converted to a string. In that format string, we can use any of the following elements (PowerLanguage Keyword Reference, 2016):

Format element Value that the element is replaced with
d The day of the month as a digit without a leading zero for single-digits days.
dd The day of the month as a digit with a leading zero for single-digit days.
ddd The day of the week as a three-letter abbreviation, displayed with the computer’s regional settings.
dddd The day of the week as its full name, displayed in the format of the computer’s regional settings.
M The month of the date without a leading zero for single-digit months.
MM The month of the date with a leading zero for single-digit months.
MMM The month as a three letter abbreviation, in the region settings of the computer.
MMMM The month as its full name, displayed in the computer’s region and language settings.
y The year of the date as the last two digits without a leading zero for years less than 10.
yy The year of the date as the last two digits, with a leading zero for years that are less than 10.
yyyy The date’s year represented with four digits.

Before looking at how FormatDate() can format dates in alert messages, let’s summarise the different steps:

  • We get the bar’s date with Date while CurrentDate returns the computer’s date. Both keywords return those dates in YYYMMdd format.
  • To display those dates in a customised date format with FormatDate(), we need to convert those YYYMMdd values to DateTime. That conversion is done with DateToJulian().
  • Then we construct the format string that’s used with FormatDate() to specify how the date should appear. Common format strings are "dd-MM" (which prints October 7, 2016, as 07-10), "dd-MM-yy" (07-10-16), and "M/d/yyyy" (10/7/2016).

Say we want to use the bar’s date (Date) in an alert. We would use Alert(), together with FormatDate() and DateToJulian(), as follows:


Alert("This bar closes on " + FormatDate("dd-MM-yyyy", DateToJulian(Date)));

This generates an alert message like:

Example of a MultiCharts alert with custom date formatting

Now let’s explore how this approach can be used in a full programming example.

Example: generating MultiCharts alerts messages with a custom date

In the indicator below we plot the highest high and lowest low, and those values are calculated on the recent 125 bars. We also track the date that accompanies those extreme prices. Then when the price bar reaches a new highest low or lowest low, we generate an alert message that includes the date of when the previous extreme high or low was reached.

The image below gives an example of those alert messages. After discussing the code we’ll take a closer look at the indicator’s behaviour and appearance.

Example of an alert generated by the MultiCharts indicator

Inputs:
    LookbackPeriod(125);
    
Variables:
    highestHigh(0),
    lowestLow(0),
    dateHigh(0),
    dateLow(0);

// Compute and plot values
highestHigh = Highest(High, LookbackPeriod);
lowestLow   = Lowest(Low, LookbackPeriod);

Plot1(highestHigh, "Highest high", green, default, 2);
Plot2(lowestLow, "Lowest low", red, default, 2);

// Generate alerts for new extreme prices
if (High = highestHigh) then begin

    dateHigh = DateToJulian(Date);

    Alert("This bar reached a new high since " +
        FormatDate("d-M-y", dateHigh[1]));    

end

else if (Low = lowestLow) then begin

    dateLow = DateToJulian(Date);
    
    Alert("New lowest low since " + 
        FormatDate("MMM ddd d", dateLow[1]));

end;

We begin the script with creating an input option and several variables:


Inputs:
    LookbackPeriod(125);
    
Variables:
    highestHigh(0),
    lowestLow(0),
    dateHigh(0),
    dateLow(0);

With the LookbackPeriod input option we can, in the script’s settings, easily configure how many bars the indicator should compute the highest high and lowest low on.

We create four numerical variables. The highestHigh and lowestLow variables will hold the extreme prices. And with dateHigh and dateLow we track the date on which those highest highs and lowest lows happen.

Then we calculate and plot the extreme prices:


highestHigh = Highest(High, LookbackPeriod);
lowestLow   = Lowest(Low, LookbackPeriod);

Plot1(highestHigh, "Highest high", green, default, 2);
Plot2(lowestLow, "Lowest low", red, default, 2);

We compute the highest high with the Highest() function, which works with two parameters: a series of values to process and an integer that specifies the number of bars to calculate on. Here we set those parameters to the bar’s high prices (High) and set the length with the LookbackPeriod input option. We store that extreme price in the highestHigh variable.

The lowestLow variable has its value set in the same manner. Here we use Lowest(), and that function also requires a series of values and the amount of bars to calculate on as parameters. With the Low and LookbackPeriod parameters we have that function calculate on the bar’s low prices for a length set by the input option. That lowest low value is tracked with the lowestLow variable.

Next we plot both values on the chart with the Plot1() and Plot2() keywords. Both accept a range of parameters, of which we use five here: the value to plot, the plot’s name, the colour of the plot, the background colour when used in the Scanner/Watchlist window, and the plot’s size (MultiCharts Wiki, 2012). While we have no need for that background colour, we do need to specify it if we want to set the width of the plot with the fifth parameter.

With the Plot1() keyword we plot the value of the highestHigh variable on the chart. We name this plot “Highest high” and give it the green basic MultiCharts colour. With default we use the same background colour as the Scanner/Watchlist window already has, and with 2 the plot’s size is one step bigger than the default size (MultiCharts Wiki, 2012).

The Plot2() statement is much the same: with it we plot the lowestLow values on the chart in the red colour, and aptly name the plot “Lowest low”.

Next is an if statement for generating the first alert:


if (High = highestHigh) then begin

    dateHigh = DateToJulian(Date);

    Alert("This bar reached a new high since " +
        FormatDate("d-M-y", dateHigh[1]));    

end

This if statement evaluates whether the high of the current bar (High) equals (=) highestHigh, the variable that holds the 125-bar highest high. That situation happens whenever the current bar’s high is a new 125-bar high.

Before generating a ‘new high’ alert, we first update the dateHigh variable to the current bar’s DateTime value. For that we use the Date keyword (which holds the bar’s closing date in YYYMMdd format), converted to DateTime with DateToJulian() (PowerLanguage Keyword Reference, 2016). By doing this every time a new highest high is reached, we can access that variable’s previous values to get the date of the preceding highest high.

Then we generate an alert programmatically with Alert(). The alert message consists out of a static string and the date, combined together with the + operator. We use the FormatDate() keyword to format that date to "d-M-y". That format string corresponds to the day as a digit without a leading zero, the month as a digit without a leading zero, and the last two digits of the year (PowerLanguage Keyword Reference, 2016).

For the second parameter of FormatDate(), the DateTime value, we use dateHigh[1]. As we saw earlier, the dateHigh variable contains the date (in DateTime format) of when the highest high is reached. By placing a 1 in the square brackets ([ and ]) after this variable we get its previous bar value. Since on that bar the indicator was still working with the previous highest high values (in other words, the dateHigh variable wasn’t updated yet on that bar), dateHigh[1] returns the date of when the previous highest high was reached.

With the second if statement we generate the lowest low alert:


else if (Low = lowestLow) then begin

    dateLow = DateToJulian(Date);
    
    Alert("New lowest low since " + 
        FormatDate("MMM ddd d", dateLow[1]));

end;

This if statement is much like the previous. Here we check whether the current bar’s low (Low) equals (=) the lowestLow variable. That’s the case when the current bar has formed a new 125-bar lowest low.

Inside the if statement, we first update the dateLow variable to the DateTime value of the current bar (DateToJulian(Date)). Then we generate an alert with Alert(). Inside that keyword’s parentheses, we use the + operator to combine a static string with a date.

That date value is again formatted with the FormatDate() keyword. Now we set this keyword’s format string to "MMM ddd d". That represents the month as a three letter abbreviation in the language settings of the computer (MMM), the day of week as a three-letter abbreviation in the computer’s language (ddd), and d marks the day of month as a digit without a leading zero for single-digit days (Language Keyword Reference, 2016).

We set the second parameter of FormatDate() to the dateLow[1] variable. That returns the date before the new lowest low happened. And in effect that gives us the date of when the previous lowest low happened (because we only update the dateLow variable to a new value whenever there’s a new 125-bar lowest low).

Example: MultiCharts alerts with dates in readable format

Now let’s see how working with the example indicator goes. First, when we add the script to the chart, we use the following manual alert settings:

Configuring the alert settings of the MultiCharts script

The script’s input option that configures the lookback period is:

Setting the input options of the MultiCharts indicator

When we add the indicator to a chart, it plots the highest high and lowest low for confirmation. Now when a new lowest low occurs, like this:

Example chart in MultiCharts with the indicator applied to it

Then the script generates the following alert:

Example alert generated by the MultiCharts indicator

(Because my computer uses the Dutch version of Windows, the alert uses ‘aug’ and ‘wo’ as Dutch abbreviations for August and Wednesday. Unfortunately, it’s currently not possible in MultiCharts to configure which language FormatDate() should use when converting a DateTime value to a string.)

And when the instrument forms a new highest high, like it did here:

Example chart of EUR/GBP with the indicator added to it

Then the indicator generates an alert message like the following:

Example alert when reaching a new highest high in MultiCharts

Here the alert contains the day of month (10), the month as a single number (8), and the year as two digits (16). For other ways in which we can configure the text in a MultiCharts alert message, see formatting numbers in alerts and including times in alert messages.

Summary

We programmatically generate alerts with Alert(), but that does require that the script’s manual alert settings are enabled. When we want to include the date of a price bar or the computer’s date in an alert message, we can use the Date and CurrentDate keywords. Both keywords, however, return the date in PowerLanguage’s YYYMMdd format where YYY stands for the number of years since 1900, MM is the month (with a leading zero for single digit months), and dd is the day of the month, with a leading zero for single-digit days. This date format is hard to read, especially when it quickly pops up in an alert window. Luckily, we can use our own custom date format with FormatDate(). This keyword’s first parameter is a string that specifies how to format the date, while a DateTime value is used for the second parameter. We can convert dates that are in YYYMMdd format to DateTime with the DateToJulian() keyword, and that way we can use FormatDate() to print any date in a custom, readable format.

Learn more:


References

MultiCharts Wiki (2012, February 19). Plot. Retrieved on September 8, 2016, from http://www.multicharts.com/trading-software/index.php/Plot

PowerLanguage Keyword Reference (2016). Retrieved on May 25, 2016, from http://www.multicharts.com/trading-software/images/c/c6/PowerLanguage_Keyword_Reference.pdf