Alerts are a helpful tool to notify us about certain events. How can we have our script generate alerts programmatically for us?

In this article:

Generating an alert programmatically in MultiCharts

Alerts are a tool to bring certain happenings to our attention, like a moving average crossover or when a strategy’s automated trading is disabled. The kind of alerts that we can generate in MultiCharts are audio alerts, notification windows, and email alerts (MultiCharts Wiki, 2013).

While we can also generate alerts with manual drawings, it’s more common to trigger alerts programmatically. We do that with the Alert() keyword, which can trigger an alert whenever our script executes this keyword (MultiCharts Wiki, 2012a). Now whether the alert actually fires and how the alert appears is configured by the manual alert settings.

There are two ways to use the Alert() keyword (MultiCharts Wiki, 2012a):

  • Simply using Alert() can generate an alert with basic information (the name of the script that triggered the alert, the instrument and its resolution, and the current price).
  • When we provide a string (that is, text) between the parentheses of the Alert() keyword (like Alert("New high!")), then the alert message also contains our custom text besides that standard information. This makes it possible to create more meaningful alerts by including actionable information.
Tip: Before Alert() can generate any alert, the alert settings of the indicator or signal need to be enabled. Because that option cannot be set programmatically, some manual action is always needed before the script can generate alerts programmatically. See enabling MultiCharts alerts by hand for where to find the alert settings in the different MultiCharts contexts.

Other features of the Alert() keyword are:

  • Alert() only triggers alerts on the last bar of the data series (MultiCharts Wiki, 2012a) – it won’t generate alerts on historical bars. When we use the ‘Data Playback’ mode, however, we can simulate alert generation on historical bars.
  • Each time the script comes across the Alert() keyword, an alert can be generated. We can use the manual alert settings to place a limit on the number of alerts per bar, or deal with this programmatically (by limiting alerts to a certain number per bar or keeping a specific number of seconds between alerts).
  • Strictly speaking, the Alert() keyword only triggers the alert. If and how the alert generates (like in a notification window or email) is controlled by the MultiCharts program and configured in the script’s manual alert settings.
  • We can use Alert() in indicators, signals (that is, trading strategy scripts), and functions.

The Alert() keyword can trigger an alert in the following situations (MultiCharts Wiki, 2013):

  • When the workspace in which our script runs opens,
  • When we change the data series that script calculates on to another data series,
  • And when the current bar closes or a new tick is received (which of these two triggers the alert depends on the script’s manual alert settings).

For a better idea of how we can work with Alert(), let’s look at a few different ways in which this keyword can generate alerts.

Generating MultiCharts alert messages: static, dynamic, or no text

The Alert() keyword has an optional parameter: a string with the message to display when the alert generates (MultiCharts Wiki, 2012a). That text appears in the notification window and email alert (when these are enabled in the manual alert settings), and also shows up in the ‘Alerts’ tab of the Order and Position Tracker.

The text that we specify between that keyword’s parentheses can be a static text, dynamic text, or no text at all. Let’s examine those three ways closer.

Generating a static alert message with Alert()

The first way to use Alert() is to generate an alert message that contains a static string (that is, a text message which we directly typed in the code of our script). Since those hard-coded alerts won’t change while our script runs, the alert will always have the same message.

An example of generating a static alert message is:


if (Open <> Open[1]) then
    Alert(Text("Alerts are triggered with the 'Alert()' ", 
        "keyword in MultiCharts. Once an alert is triggered,",
        " we can use 'Cancel Alert' to prevent the alert",
        " from generating. In addition, ",
        "the 'AlertEnabled' and 'CheckAlert' keywords",
        " make it possible to check if the script can generate alerts."));

This if statement evaluates if the open of the current bar (Open) is unequal to (<>) the previous bar’s open (Open[1]). When that’s the case, we use Alert() to generate a static alert message that looks like:

Example of a static alert message in MultiCharts

Generating a dynamic alert message with Alert()

The second way to use Alert() is to create an alert message whose text differs each time the script runs. This allows for more relevant information in alert messages. For example:


if (Close > Low[1]) then
    Alert(Text("Current close ", Close, 
        " is above the previous bar low (", Low[1], ")"));

Here the if statement checks whether the close of the current bar (Close) is greater than (>) the previous bar’s low (Low[1]). When that happens, we generate an alert with Alert(). Inside that keyword’s parentheses, we use the Text() keyword to combine several text pieces into one string (MultiCharts Wiki, 2012e).

Those text pieces include a static string ("Current close "), the dynamic value with the bar’s closing price (Close), another static string (" is above the previous bar low ("), the previous bar’s low (Low[1]), and another static string (")"). Combined, the alert message looks like:

Examples of dynamic alert messages in MultiCharts

What this example also shows is that we’re not limited to generating alerts with static or dynamic values, but can also create messages that contain both fixed text and dynamic values.

Triggering an alert without a message

The third approach is to use Alert() without specifying a message, and we do that by not providing a text between this keyword’s parentheses. For instance:


if (Close > Close[1]) then
    Alert();

Here we trigger an alert whenever the current bar’s close is greater than (>) the close of the previous bar (Close[1]). When that happens, the script simply executes Alert(). That generates an alert without a message. The basic information (source, instrument, resolution, and price), however, always shows in the alert notification window.

Example of an empty alert message in MultiCharts

Now let’s explore how we can generate MultiCharts alerts in a full programming example.

Example indicator: triggering MultiCharts alerts programmatically

In the example indicator below we generate an alert when there are three higher or three lower closes in a row. To see on which historical bars these alerts would have been triggered, we draw an up or down arrow whenever the alert condition occurs.

The image below shows how the generated alerts look like. After discussing the code we’ll take a closer look at the indicator and its manual alert settings.

Examples of the MultiCharts alerts generated by the indicator

Variables:
    higherCloses(false),
    lowerCloses(false);

// Determine conditions
higherCloses = (Close > Close[1]) and 
    (Close[1] > Close[2]) and (Close[2] > Close[3]);
    
lowerCloses  = (Close < Close[1]) and 
    (Close[1] < Close[2]) and (Close[2] < Close[3]);

// Check for higher closes on bar close
if (BarStatus = 2 and higherCloses) then begin

    // Generate alert and draw arrow
    Alert("Three consecutive higher closes.");
    
    Arw_New_s(Date, Time_s, High, true);

end;

// Check for lower closes on bar close
if (BarStatus = 2 and lowerCloses) then begin

    // Generate alert and draw arrow
    Alert("Three lower closes in a row.");
    
    Arw_New_s(Date, Time_s, Low, false);

end;

We start the example by creating two variables: higherCloses and lowerCloses. We give these true/false variables a default value of false.

Then we assign those variables a value based on two alert conditions:


higherCloses = (Close > Close[1]) and 
    (Close[1] > Close[2]) and (Close[2] > Close[3]);
    
lowerCloses  = (Close < Close[1]) and 
    (Close[1] < Close[2]) and (Close[2] < Close[3]);

The value of both variables depends on three expressions, which we combine with the and logical keyword. That keyword returns true when the value on its left and the value on its right are both true too. When one or both values are false, then and returns false too (MultiCharts Wiki, 2012f). For these alert condition variables, this means all three situations combined with and need to occur (that is, have to evaluate to true).

For the higherCloses variable, those situations are whether the current bar’s close (Close) is greater than (>) the previous bar’s close (Close[1]). The next expression checks whether that previous bar closed above its preceding bar (Close[1] > Close[2]), and the third requires that the close of two bars ago was higher than the bar before that (Close[2] > Close[3]).

When those three comparisons are true, the result combined with and is true too and the higherCloses variable is given a value of true. When one or more comparisons are false, then that variable’s value becomes false.

The value of the lowerCloses true/false variable is set similarly, except that now we require that there are three lower closes in a row. That is, Close < Close[1] and Close[1] < Close[2] and Close[2] < Close[3] all have to be true before lowerCloses is set to true too.

With the alert conditions translated into the higherCloses and lowerCloses variables, we come across the first if statement that can generate an alert:


if (BarStatus = 2 and higherCloses) then begin

    // Generate alert and draw arrow
    Alert("Three consecutive higher closes.");
    
    Arw_New_s(Date, Time_s, High, true);

end;

Before the code inside this if statement executes, two expressions combined with and have to evaluate to true. The first checks whether the BarStatus keyword returns a value equal to (=) 2. That value is returned by BarStatus when the script calculates on the closing tick of the current data series (MultiCharts Wiki, 2014). This way we check whether the bar has closed before we generate an alert inside the if statement (and this way our alerts are also generated once per bar, when the bar closes).

The other expression in the if statement’s condition is whether the higherCloses variable returns true, which it does when there are three higher closes in a row. The code inside the if statement executes when both expressions are true.

That code first generates an alert message with Alert() (MultiCharts Wiki, 2012a). The alert message that we use here is “Three consecutive higher closes.” (also see images below).

Then we draw an arrow to highlight that the alert condition occurred on the current bar. We make that arrow with Arw_New_s(), a keyword that requires four parameters: the date, time, and price of where to place the arrow, and true to make a downward-pointing arrow and false for an arrow that points up (MultiCharts Wiki, 2012g). We place that arrow at the date (Date), time (Time_s), and high (High) of the current bar, and with true as the fourth parameter have the arrow point down.

The example indicator ends with another if statement:


if (BarStatus = 2 and lowerCloses) then begin

    // Generate alert and draw arrow
    Alert("Three lower closes in a row.");
    
    Arw_New_s(Date, Time_s, Low, false);

end;

This if statement is much like the first. Here we also require that the bar has closed (BarStatus = 2) while the alert condition (lowerCloses) is true before executing the code inside the if statement.

That code begins with generating an alert with Alert(), and have the alert message say "Three lower closes in a row.". Next we use Arw_New_s() to draw another arrow on the chart, this time to highlight three consecutive lower closes. We place this drawing at the current bar’s date (Date), time (Time_s), and low (Low) while the false parameter makes the arrow point up.

This concludes the programming example that generates an alert for three higher closes and three lower closes in a row. Now let’s see how using the indicator looks like.

Example: generating MultiCharts alerts for higher and lower closes

When we add the above example indicator to the chart, we do so with the following manual alert settings. (To find these settings, right-click on the script’s name in the chart’s Status Line and select ‘Format [script name]‘. Then move to the ‘Alerts’ tab.)

Configuring the alert settings of the MultiCharts script
Note: Because the indicator generates alerts when the bar closes (that is, BarStatus = 2), the setting of the ‘Alert Conditions Check’ option doesn’t matter: when we set this option to ‘Every Tick’, our indicator would still only generate alerts when the bar closes. This shows that when an alert generates depends both on the manual alert settings as well as the script’s code.

When we add the indicator to a chart, like the Dow Jones Industrial Average Index CFD, it looks like:

Chart of the MultiCharts PowerLanguage example indicator

Here we have red downward-pointing arrows whenever there are three higher closes in a row, while three lower closes in a row are marked with blue arrow that points up.

Now when there are three higher or lower closes in real time, the script generates alerts like the following:

Examples of the alerts generated by the MultiCharts script

Should we be away from the computer when those alerts fire, we can also find them in the historical log in the ‘Alerts’ tab of the Order and Position Tracker window:

Example of the generated MultiCharts alerts in the Order and Position Tracker window

Summary

The Alert() keyword programmatically generates MultiCharts alerts, and inside its parentheses we can optionally specify the alert message. While Alert() fires the alert, it are the manual alert settings that determine whether the alert generates as a notification window, audio alert, and/or email. Furthermore, before a script can programmatically fire alerts, its ‘Enable Alerts’ checkbox has to be enabled. With that option turned on, the Alert() keyword can fire an alert once per bar or each time that the script executes this keyword (depending on the manual alert settings). MultiCharts can generate alerts when the last bar receives a new tick or closes, but also when the workspace with our script in it opens, or when the data series that the script computes on is replaced by another data series.

Learn more:


References

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

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

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

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

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

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

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 March 10, 2016, from https://www.multicharts.com/trading-software/index.php/BarStatus