When generating MultiCharts alerts programmatically, these typically fire whenever the alert condition happens. But for a more efficient script that fires less alerts, how do we only calculate and generate alerts when the bar closes?

In this article:

Firing MultiCharts alerts when the price bar closed

We generate MultiCharts alerts programmatically with Alert() (MultiCharts Wiki, 2012a), but before that keyword can fire its alerts we do need to enable the script’s alert setting (see image below). Depending on the manual alert settings, the alert can generate as an audio alert, notification window, and/or email alert (MultiCharts Wiki, 2013).

Enabling the alerts of a MultiCharts indicator or strategy

After turning on that ‘Enable Alerts’ option, we use the ‘Alert Conditions Check’ setting just below it to specify when the alerts should fire: if the bar closes, with every tick, or once per bar.

But only generating alerts programmatically when the bar closes is possible too. That way we don’t have to configure that option on each chart that our script is added to. But more importantly: if we only execute the Alert() keyword when the bar closes, then we can also limit calculations to that ‘once per bar’ event. And that makes our script run much more efficient than performing those computations with every price update. After all, if we only want to generate alerts on bar close, then the alert conditions (and the values used by those conditions) also only have to be calculated once per bar.

Programmatically determining if the script calculates during the last price update of a bar is done with BarStatus. That keyword returns the status of the most recent tick in the current bar of the specified data series (MultiCharts Wiki, 2014). The price update that our script processes during its current calculation is called “bar status”, and this can be the bar’s opening tick, closing tick, or a price inside the bar.

There are two ways to use BarStatus: with and without parentheses. With parentheses just behind the keyword we can specify the data series number to get the bar status from. For instance, BarStatus(2) returns us the bar status of the second data series. Without parentheses (so just BarStatus), the keyword returns the bar status of the data series that the script already calculates on (MultiCharts Wiki, 2014).

Regardless of whether we use BarStatus() or BarStatus, the keyword typically returns one of three values (MultiCharts Wiki, 2014):

  • When our script processes a price update that’s the bar’s opening tick, BarStatus returns 0.
  • If the currently processed tick falls inside the bar, BarStatus returns 1.
  • And when the current price update marks the close of the price bar, then BarStatus returns 2.
Note: In rare cases, BarStatus returns -1. That bar status happens when the price bar of the specified data series has already closed but the script still calculates, for instance due to price bars of an additional data series being processed, a broker event happening, or a periodic recalculation with RecalcLastBarAfter() (e.g., Henry MultiCharts, 2015).

Now to programmatically determine if the price bar has closed (so we can generate an alert programmatically when that happens), we check whether BarStatus returns a value equal to 2. In other words, executing a piece of code only when the bar closes goes like:


if (BarStatus = 2) then begin

  // This code only executes
  // on the closing tick of the
  // price bar.

end;

Now let’s consider a programming example to see how we can use BarStatus to only generate alerts when the bar closes.

Example: generating ‘on bar close’ alerts for extreme prices

In the example below we plot the highest high and lowest low of the last 20 bars. Whenever the closing price is below the lowest low or above the highest high, we trigger an alert message. We use BarStatus to only have the script generate alerts and calculate the highest high and lowest low when the bar closes. That makes the script a bit more efficient, although the example script isn’t that complex to make this really noticeable.

The image below gives an idea of how the alerts generated by the script look like. After examining the code, we’ll take a closer look at the indicator’s behaviour.

Example of generating MultiCharts alerts only on bar close

Inputs:
    LookbackPeriod(20);
    
Variables:
    highestHigh(0),
    lowestLow(0);
    
// Only compute and trigger alerts on bar close
if (BarStatus(1) = 2) then begin

    highestHigh = Highest(High, LookbackPeriod)[1];
    lowestLow   = Lowest(Low, LookbackPeriod)[1];
    
    if (Close > highestHigh) then
        Alert("Bar has closed above the highest high @ " +
            NumToStr(highestHigh, 4));

    if (Close < lowestLow) then
        Alert("Close below lowest low (" + 
            NumToStr(lowestLow, 4) + ").");

end;

// Plot the indicator's values on every
// script calculation
Plot1(highestHigh, "Highest", DarkGreen);
Plot2(lowestLow, "Lowest", Red);

We start by creating an input option and two variables:


Inputs:
    LookbackPeriod(20);
    
Variables:
    highestHigh(0),
    lowestLow(0);

We give the LookbackPeriod numerical input option a default value of 20. Since we use this input later on with computing the highest high and lowest low, we can easily configure that script setting by hand without having to edit and recompile the code.

Both numerical variables are given a default of 0. We’ll use highestHigh later on to hold the 20-bar highest high, while lowestLow will track the lowest low price over the same period.

A large part of the indicator’s code is inside an if statement that makes that code only execute when the price bar of the first data series closes:


if (BarStatus(1) = 2) then begin

    // ...

end;

Here we evaluate whether BarStatus(1) returns a value equal to (=) 2. That comparison evaluates to true whenever the script calculates during a closing tick of the first data series (MultiCharts Wiki, 2014). That way we ensure that the code inside this if statement only executes once per bar, on bar close.

Now inside the if statement, we begin by calculating the extreme prices:


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

We assign the highestHigh variable the value returned by Highest(), a function that calculates a highest value based on two parameters: a series of values to process and a number that sets how many bars to calculate on. We set those parameters to the bar’s high prices (High) and the LookbackPeriod input option, which we gave a default value of 20 earlier.

Just behind the Highest() function call we place two square brackets ([ and ]) with a value of 1 between them. This makes the function return the highest high in the context of the previous, and not current, bar. We do this because later we’ll check if the bar closed above the 20-bar highest high. Should the highest high also include the current bar’s high, then the closing price can never cross that 20-bar high. And so we use [1] to offset the values returned by Highest() one bar into the past.

In the same manner we update the lowestLow variable. Now we use Lowest(), a function that requires two parameters: a series of values to process and the number of bars to compute on. We set those parameters to the bar’s low prices (Low) and the LookbackPeriod input option. And to get the lowest low of the preceding 20 bars, we place [1] just behind Lowest(). This way we can also check later on whether the bar dropped below the 20-bar lowest low.

Inside the if statement with code that only executes when the bar closes, there are two nested if statements for generating an alert:


if (Close > highestHigh) then
    Alert("Bar has closed above the highest high @ " +
        NumToStr(highestHigh, 4));

if (Close < lowestLow) then
    Alert("Close below lowest low (" + 
        NumToStr(lowestLow, 4) + ").");   

The first if statement evaluates whether the bar’s closing price (Close) is greater than (>) the 20-bar highest high (highestHigh). When that’s the case, we execute Alert() to generate an alert programmatically (MultiCharts Wiki, 2012a).

The alert message that we specify between the parentheses of Alert() contains a static text combined with a dynamic value. That latter is the 20-bar highest high, which we format to a textual string here with NumToStr(). That keyword needs two parameters: a number to convert to a string and how many decimals the converted number should get (MultiCharts Wiki, 2012b).

We set those parameters to highestHigh and 4 to display the 20-bar highest high with 4 decimals in the alert message. Now if we didn’t use NumToStr() here, then MultiCharts would print highestHigh with 2 decimals by default. (If you use the example script on an instrument whose prices use more or less than 4 decimals, you’ll need to change this part.)

The other if statement checks if the bar closed below (<) the 20-bar lowest low (lowestLow). When it did, we generate another alert with Alert(). Here we also format numerical values in the alert message with NumToStr(). This time we convert the 20-bar lowest low (lowestLow) to a 4 decimal string. (See the image above for how this alert message looks like.)

Besides the previous code (which only executes when the price bar closes), the indicator also has a bit of code that executes with every script calculation. That part does the plotting:


Plot1(highestHigh, "Highest", DarkGreen);
Plot2(lowestLow, "Lowest", Red);

By plotting these values each time the script calculates, our highest high and lowest low values appear on the chart as soon as a new price bar begins. If we would only plot on bar close, the indicator would ‘wait’ till the end of the bar before plotting those values. Because we plot with the variables here (and not perform the calculations), the script still runs efficient by only calculating the extreme prices when the bar closes.

We plot the highestHigh and lowestLow values as a line with Plot1() and Plot2(), and use three parameters with those keywords: the value to plot, the plot’s name, and the plot’s colour (MultiCharts Wiki, 2012c).

The Plot1() statement shows the 20-bar highest high on the chart. We name that plot “Highest” and give it the DarkGreen standard MultiCharts colour. With the Plot2() keyword we display the 20-bar lowest lows in the Red colour, and name that plot “Lowest”.

Now let’s see how this example indicator behaves when added to a chart.

Example: fire MultiCharts alerts with code when the bar closes

When we add the above example indicator to the chart, we do need to manually enable the script’s settings so that the script can actually fire its alerts. When we do, the script’s manual alert setting of when the alert should fire (the ‘Alert Conditions Check’ option) is irrelevant. That’s because our indicator programmatically generates alerts when the bar closes, so it doesn’t matter if the manual option says the script may generate alerts on ‘Every Tick’.

The example script has the following input option:

Example of the script's input options

When we add the indicator to a chart, like a Euro/Australian Dollar chart, the plotted highest high and lowest low values look like:

Example MultiCharts chart with the indicator applied to it Another example chart with the indicator plotting highest high and lowest low lines

Then when a bar closes above the highest high or below the lowest low, the script generates alerts like the following:

Example alerts generated by the MultiCharts indicator

For a different approach that uses the bar’s status with alerts, see combining an intra-bar alert with one that only fires on bar close.

Summary

We generate alerts in MultiCharts programmatically with Alert(). This keyword can trigger an audio alert, notification window, and/or email alert. That does require that we manually enable the script’s alerts. Depending on those settings, each time the Alert() keyword executes another alert fires. The manual ‘Alert Conditions Check’ option allows us to prevent an alert from generating more than once per bar, or we can use BarStatus. With that keyword we can check if the script calculates during the bar’s opening tick, closing tick, or a price update that’s in between. With that information we can generate alerts programmatically only when BarStatus says the price bar has closed. And we can limit certain calculations to that once per bar event to make the script run more efficient.

Learn more:


References

Henry MultiCharts (2015, January 30). closing status of a bar sometimes takes too long – forum discussion. Retrieved on May 4, 2016, from http://www.multicharts.com/discussion/viewtopic.php?f=1&t=10642#p113092

MultiCharts Wiki (2012a, February 7). Alert. Retrieved on March 7, 2016, from http://www.multicharts.com/trading-software/index.php/Alert

MultiCharts Wiki (2012b, February 13). NumToStr. Retrieved on May 7, 2016, from https://www.multicharts.com/trading-software/index.php/NumToStr

MultiCharts Wiki (2012c, February 19). Plot. Retrieved on May 7, 2016, from https://www.multicharts.com/trading-software/index.php/Plot

MultiCharts Wiki (2013, May 10). Using Alerts. Retrieved on March 7, 2016, from https://www.multicharts.com/trading-software/index.php/Using_Alerts

MultiCharts Wiki (2014, August 12). BarStatus. Retrieved on May 3, 2016, from https://www.multicharts.com/trading-software/index.php/BarStatus