Before our MultiCharts indicator or signal (trading strategy script) can generate alerts, we need to enable its alert setting. While it’s possible to programmatically check if that option is enabled, we can also have a piece of code only execute when alerts are enabled. Let’s take a closer look at that.

In this article:

Executing a MultiCharts code block only when alerts are enabled

We programmatically generate a MultiCharts alert with the Alert() keyword (MultiCharts Wiki, 2012a). Before that keyword can trigger any alert, we need to enable the script’s alert setting. Then, depending on how we’ve configured the alert options, the alert can appear as a notification window, email alert, and/or audio alert (MultiCharts Wiki, 2013).

The option for enabling an indicator’s or strategy’s alerts is the ‘Enable Alerts’ checkbox:

Enabling alerts in MultiCharts with the 'Enable Alerts' setting

We can use code to check if alerts are enabled. That, for example, allows us to create if statements with code that only executes when alerts are enabled. There are two keywords for that:

  • The CheckAlert keyword returns true when the ‘Enable Alerts’ setting is turned on and when the bar that’s currently processed by the script is the last bar of the data series (MultiCharts Wiki, 2012b). This keyword returns false when that option is turned off and/or when the current bar isn’t the last.
  • The AlertEnabled keyword returns true when the ‘Enable Alerts’ setting is turned on and returns false when that checkbox is disabled (MultiCharts Wiki, 2012c).

Besides these keywords, another way to execute code based on the ‘Enable Alerts’ option are the #BeginAlert and #End compiler directives. These are used to surround code that should only be executed when the script’s alerts are enabled (MultiCharts Support, personal communication, March 10, 2016).

Let’s step back to better understand what the #BeginAlert compiler directive does. Compiling is the process of turning the code that we can read into machine-readable code (Liberty & MacDonald, 2009). For our indicators and signals, that means translating the PowerLanguage code into a file that the MultiCharts program can use. That, in turn, makes it possible to add the script to the chart.

Now what a compiler directive does is specifying how the compiler should compile the code (Wikipedia, 2016). These directives start with the # symbol and are placed on a line of their own (Albahari & Albahari, 2012; Oualline, 2003). And conditional directives, like #BeginAlert and #End, provide us with a way to include or exclude certain regions from the code (Albahari & Albahari, 2012).

While that sounds complicated, all what #BeginAlert and #End do is specifying that the code between these directives should only execute when the script’s ‘Enable Alerts’ option is enabled. And when that option is disabled, then our script behaves as if all code between those directives is commented out or simply not there.

So that makes #BeginAlert and #End basically work like:


#BeginAlert

    // Our script only executes this code between
    // #BeginAlert and #End when 'Enable Alerts'
    // is enabled.

#End

Semantically, this is identical to using the CheckAlert keyword to programmatically check whether the script’s alerts are enabled (MultiCharts Wiki, 2012b). For instance:


if (CheckAlert) then begin

    // The code inside this if statement
    // is also only executed when the
    // 'Enable Alerts' option is enabled.

end;

Besides this similarity, there are also a couple of differences between these two approaches. First, we cannot access #BeginAlert to check if the script’s alerts are enabled – we need to use AlertEnabled or CheckAlert for that. Second, we cannot use #BeginAlert to execute code when alerts are disabled, which we can do with those two keywords (for instance, if (AlertEnabled = false) then …).

Note: If you want to execute certain code only when the ‘Enable Alerts’ option is on, then the #BeginAlert and #End compiler directives create a script that, in theory, is a bit quicker than using CheckAlert or AlertEnabled. That’s because those keywords still need to be processed by MultiCharts when the script runs, while the directives are processed once when the script compiles (but aren’t evaluated when during real-time calculations).

For a more practical explanation of #BeginAlert and #End, let’s look at an example indicator that uses these compiler directives to behave differently based on whether the script’s manual ‘Enable Alert’ setting is enabled or not.

Example: using the alert compiler directives in MultiCharts PowerLanguage

The example indicator below plots a volume histogram. While that makes for a basic indicator, as soon as the ‘Enable Alerts’ option is turned on, the script changes. It then also calculates and plot the average volume, colours the volume histogram based on that average volume, and generate alerts.

An example of those alerts is displayed below. After discussing the code, we’ll take a closer look at the appearance and behaviour of this indicator.

Examples of the alerts generated by the MultiCharts script

Inputs:
    Average_Volume(10);
    
Variables:
    avgVol(0);

// Plot volume
Plot1(Ticks);
SetPlotWidth(1, 3);

#BeginAlert

    // Compute and plot values
    avgVol = AverageFC(Ticks, Average_Volume);

    Plot2(avgVol);
    
    // Set the volume histogram's colour
    if (avgVol > avgVol[1]) then
        SetPlotColor(1, darkgreen)
    else
        SetPlotColor(1, magenta);
    
    // Set the colour and width of the average volume
    SetPlotColor(2, RGB(65, 105, 225)); // Royal blue
    SetPlotWidth(2, 2);
    
    // Trigger alert
    if (avgVol > avgVol[1] and avgVol[1] > avgVol[2] and 
            avgVol[2] > avgVol[3]) then
        Alert("Volume has been rising three bars in a row");

#End

We begin by creating an input option and variable:


Inputs:
    Average_Volume(10);
    
Variables:
    avgVol(0);

The Average_Volume input variable is given a default value of 10, and we’ll use this input later on when calculating the average volume. In the avgVol numerical variable we’ll store the average volume.

Next we plot the bar’s volume:


Plot1(Ticks);
SetPlotWidth(1, 3);

We use the Plot1() keyword to plot the bar’s volume (MultiCharts Wiki, 2012d), and those volume values are returned by the Ticks keyword (MultiCharts Wiki, 2015). Then we change that plot’s size with SetPlotWidth(), a keyword that requires two parameters: the number of the plot to change and the new width that this plot should get, with a number ranging from 1 to 12 (MultiCharts Wiki, 2012e). With a value of 3 we make our plot two steps bigger than the default size.

Note:

Oddly enough, on tick, volume, and time-based charts (with a resolution less than 24 hours) the Volume keyword only returns the bar’s up volume (MultiCharts Wiki, 2012k). The Ticks keyword, on the other hand, does return the bar’s total volume (up volume plus down volume) (MultiCharts Wiki, 2015). That’s why we use Ticks here instead of Volume.

Now to have Ticks return the bar’s volume (and not the tick count), the chart’s ‘Build Volume On’ option has to be set to ‘Trade Volume’ (MultiCharts Wiki, 2015). To find that setting, right-click on a price bar of the instrument and choose ‘Format [symbol name]‘. This opens the ‘Format Instrument’ window, and there in the ‘Settings’ tab we find the ‘Build Volume On’ option:

Example of the Trade Volume setting in MultiCharts

After plotting the volume, the remainder of the indicator’s code is between #BeginAlert and #End. The code that’s between those directives calculates and plots a moving average, colours the histogram conditionally, and generates an alert.

And so only if the script’s alerts are enabled, the indicator calculates and plots a volume average:


avgVol = AverageFC(Ticks, Average_Volume);

Plot2(avgVol);

Here we set the avgVol variable to the value returned by AverageFC(), a function that computes a Simple Moving Average (SMA). For that it requires two parameters: a series of values to process (here set to the bar’s volume with Ticks) and the number of bars to calculate on (the Average_Volume input option, which has a default value of 10).

Then we plot that SMA value on the chart with the Plot2() keyword. Since we only specify the value to plot without other parameters, the average volume shows with the default plot settings (like its width and colour) (MultiCharts Wiki, 2012d).

Then we use that average volume to conditionally set the colour of the first plot (which shows the bar’s volume):


if (avgVol > avgVol[1]) then
    SetPlotColor(1, darkgreen)
else
    SetPlotColor(1, magenta);

SetPlotColor(2, RGB(65, 105, 225));
SetPlotWidth(2, 2);

With an if/else statement we determine which colour to give the first plot. The if statement’s condition evaluates whether the 10-bar volume SMA (avgVol) is greater than (>) its previous bar value (avgVol[1]). When the average volume has indeed been rising, we change the colour of the first plot with SetPlotColor().

That keyword requires two parameters: the plot number and the new colour for that plot (MultiCharts Wiki, 2012f). Now when the average volume has increased, we change the colour of the first plot (which plots the bar’s volume) to the darkgreen basic MultiCharts colour.

But when the 10-bar SMA hasn’t been increasing (the else portion of the if/else statement), then we set that plot’s colour to magenta. By colouring the first plot conditionally with SetPlotColor(), we can quickly see whether the volume’s moving average has been rising or not.

We also use SetPlotColor() to change the colour of the second plot. This time we specify the new colour with RGB(), a keyword that accepts three numerical values for the red, green, and blue colour component values. With values of 65, 105, and 225, we set our second plot – the volume’s moving average – to royal blue. Then we also increase the size of this plot with SetPlotWidth() to make it one step bigger than default (MultiCharts Wiki, 2012e).

We end the code block between #BeginAlert and #End by generating an alert programmatically:


if (avgVol > avgVol[1] and avgVol[1] > avgVol[2] and 
        avgVol[2] > avgVol[3]) then
    Alert("Volume has been rising three bars in a row");

This if statement’s condition has three true/false expressions combined with the and logical keyword. That keyword only returns true when the value on its left and the value on its right are true too, while and returns false when one (or both) of the values is false (MultiCharts Wiki, 2012g). That means each of these three expressions have to be true before the code below the if statement executes.

The first expression checks whether the current bar’s average volume (avgVol) is greater than (>) its previous bar value (avgVol[1]). The next evaluates if the average volume on the previous bar was above the bar before it (avgVol[1] > avgVol[2]), and the last expression checks if the average volume of two bars ago also increased (avgVol[2] > avgVol[3]).

When all three of those situations are the case, we generate an alert with Alert(). Inside the parentheses of that keyword we place the static alert message that the volume has been rising three bars in a row.

Creating a histogram plot in MultiCharts PowerLanguage

Now that we discussed the programming example, there’s one thing left to do before adding the script to the chart: setting the first plot (the one with the volume values) to a histogram. Unfortunately, that’s something that we currently cannot do programmatically.

Instead, we have to right-click somewhere in the PowerLanguage Editor and choose ‘Properties…’:

Opening the Properties window in the MultiCharts PowerLanguage Editor

This opens the ‘Properties’ window. Here we change the ‘Type’ setting of the first plot from ‘Line’ to ‘Histogram’:

Setting a plot to Histogram in the PowerLanguage Editor

After that we save and compile the indicator. Now let’s see how it looks on a chart.

Example: executing MultiCharts code only when alerts are enabled

Our example indicator has the following input option:

Example of the script's input options

When we add the indicator with that default setting to the chart and don’t enable the indicator’s alerts, then the script looks like:

Example chart of the MultiCharts indicator

Here we see it only plots volume histogram bars. Because the script’s alerts aren’t enabled, it doesn’t plot the average volume nor colours the histogram bars based on that average volume.

However, let’s enable the script’s alert settings in the ‘Alerts’ tab of the indicator properties window:

Configuring the alert settings in MultiCharts by hand

Once we check that ‘Enable Alerts’ checkbox and confirm our settings, the indicator recalculates and looks like:

Example chart of the indicator when alerts are enabled

Now it does plot the average volume and change the colour of some histogram bars. Furthermore, the indicator now also generates alerts like the following:

Examples of the alerts generated by the MultiCharts indicator

Other ways to execute code conditionally based on the ‘Enable Alerts’ option are the CheckAlert and AlertEnabled keywords, which both programmatically check whether a script’s alerts are enabled (MultiCharts Wiki, 2012b, 2012c).

Summary

We generate MultiCharts alerts programmatically with Alert(), but before that keyword can actually fire alerts we have to turn on the ‘Enable Alerts’ checkbox. We can programmatically check whether the script’s alerts are enabled with the CheckAlert and AlertEnabled keywords, but we can also have a piece of code only execute when that alert setting is enabled. That’s done with two compiler directives: #BeginAlert and #End. These directives influence how our programming code translates into an executable script. By using them to declare which code should only be executed when the script’s alerts are enabled, our script runs more efficient when alerts are disabled.

Learn more:


References

Albahari, J. & Albahari, B. (2012). C# 5.0 in a Nutshell: The Definitive Reference (5th edition). Sebastopol, CA: O’Reilly Media.

Liberty, J. & MacDonald, B. (2009). Learning C# 3.0: Master the Fundamentals of C# 3.0. Sebastopol, CA: O’Reilly Media.

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 7). CheckAlert. Retrieved on March 11, 2016, from http://www.multicharts.com/trading-software/index.php/CheckAlert

MultiCharts Wiki (2012c, February 26). AlertEnabled. Retrieved on March 11, 2016, from http://www.multicharts.com/trading-software/index.php/AlertEnabled

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

MultiCharts Wiki (2012e, February 19). SetPlotWidth. Retrieved on March 25, 2016, from http://www.multicharts.com/trading-software/index.php/SetPlotWidth

MultiCharts Wiki (2012f, February 19). SetPlotColor. Retrieved on March 25, 2016, from https://www.multicharts.com/trading-software/index.php/SetPlotColor

MultiCharts Wiki (2012g, February 19). And. Retrieved on March 25, 2016, from http://www.multicharts.com/trading-software/index.php/And

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

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 (2015, November 20). Ticks. Retrieved on September 8, 2016, from http://www.multicharts.com/trading-software/index.php/Ticks

MultiCharts Wiki (2016, February 22). How Scripts Work. Retrieved on March 18, 2016, from https://www.multicharts.com/trading-software/index.php/How_Scripts_Work

Oualline, S. (2003). Practical C++ Programming (2nd edition). Sebastopol, CA: O’Reilly.

Wikipedia (2016, January 8). Directive (programming). Retrieved on March 19, 2016, from https://en.wikipedia.org/wiki/Directive_%28programming%29