Alarm/Event Control object

Use the Alarm/Event Control tool to add an Alarm or Event Control object to a project screen.

To create and configure an Alarm/Event Control object:

1. On the Draw tab of the ribbon, in the Data Objects group, click Alarm/Event Control.

2. Click in the display, and drag the mouse to create and adjust the object's shape.

3. Double-click on the object to open the following Object Properties dialog box.

   

   You can use this dialog box to specify the following parameters:

   • Select an alarm object mode in the Type group:

     • Alarm Online: Display only current alarm messages, as configured in your Alarm worksheets.

     • Alarm History: Display only alarm messages from the Alarm History database.

     • Alarm History + Event: Display both alarm messages from the Alarm History database and logged events from the Event History database.

     • Event: Display only logged events from the Event History database.

   • E-Sign checkbox: When this option is enabled, the user will be prompted to enter an E-Signature (User Name and Password) before acknowledging alarms.

   • Enable translation checkbox: When this option is enabled, the messages translated using the Translation Table. (For more information, see Project Localization.)

     Note: If you change languages while a project is running and you have filtered messages (see below), the filtered messages displayed will not change until either these events occur:

     - If a tag was specified during project development to filter the messages in the Filters dialog Message box (see below), the update will occur only after this tag value has changed.

     - If the filtering is set during runtime by a tag or value in the Message box of the runtime Filters dialog, the update will occur only after the value is changed manually and the change is confirmed by using the OK button to close the Filters dialog.

   • VK: Virtual Keyboard type used for this object. You need to select the Virtual Keyboard option in the Viewer settings (Viewer on the Project tab of the ribbon) before configuring the Virtual Keyboard for this interface.

     Tip:

     By default, an Alarm/Event Control object can display up to 16,000 messages at the same time in projects that are configured to run on the Windows target platform. If necessary, however, you can increase the maximum number of messages. To do this, manually edit your project file (<project name>.app) to add the following setting:

     [Objects]

     MaxMessagesAlarmControl=<number of messages>

     We have successfully tested projects with Alarm/Event Control objects that display up to 30,000 messages at the same time, but you can specify any number as long as the target device has sufficient system resources to run your project.

     Please note this setting applies only to projects that are configured to run on the Windows target platform. In projects that are configured to run on the Embedded target platform, the maximum number of messages is 1024 and it cannot be changed.

Filters

To filter alarm messages during runtime, click the Filters button. The Filters dialog box displays so you can specify filtering parameters for the Alarm/Event Control object.

• Use the Group field to filter messages by the Alarm group/worksheet number. The worksheets are organized in the Alarms folder, in the Tasks tab of the Project Explorer, starting with 1. If you specify a Group of 0, then all of the worksheets will be displayed. You can use commas and/or dashes to specify a range of groups (for example,1,3,5-6). This field accepts String expressions (tag only).

• Use the Selection field to filter messages by the Selection text configured on the Alarm worksheet. This field accepts String expressions (tag only).

• In the Priority group, use the From and To fields to filter messages by the Priority configured on the Alarm worksheet. Type numerical values into the these fields to delimit the priority range. You can enter integer tags in these fields.

• Use the Type field to filter messages by the alarm type (for example, HiHi, Hi, Lo, LoLo, Rate, Dev+, Dev-). You can use commas to specify more than one type; for example,HiHi,LoLo. You can enter a string tag in this field.

• Use the State field to filter messages by the alarm status:

  Value	Description
  0	All alarms (default)
  1	All active and unacknowledged alarms
  2	All active and acknowledged alarms
  3	All inactive and acknowledged alarms
  4	All inactive and unacknowledged alarms

  Leaving this field blank is effectively the same as entering a value of 0. You can enter an integer tag in this field.

• In the Search in columns group, use the Tagname, Message, and/or Username text fields to specify criteria for filtering messages. Type a tagname, message, and/or user name into these text fields. These fields accept String expressions (tag only).

  Note: If you use Message values that include string expressions, the message will not be translated unless there are translations of each exact value. For example, the Message Machine: {machine_position}, where the possible values of machine_position are left and right, will not be translated unless Machine: left and Machine: right are explicitly translated in the translation table. If only some of the possible string expression values are given translations, those messages will be translated, but messages with other values will not be translated.

• Use the settings in the Interval group to filter messages by the last x messages (Latest) or based on a period of time (Period). You can enter an integer tag in the Latest field, and string tags in the Period fields. If you do not specify any interval at all, then only the alarms for the current day will be displayed.

  Note: You can use wildcards (* and ?) when specifying values for the Selection, Tagname, Message, and Username fields.

• Use the Filter Expression to configure an expression that will filter unwanted messages out of the display. Only messages that satisfy the expression will be shown.

  To enter a filter expression, click Edit; the Alarm Filter Expression dialog box is displayed. The filter expression must follow the basic syntax of…

  [columnname]operator'value'

  …where the columnname is the name of a column in the Alarm/Event Control object and operator is any of the standard relational operators (for example, =, <, >, <=, >=, <>). For example:

  [Activation Time]>'08/17/2007 15:00'

  This filter will only show alarm messages with activation times greater (later) than 15:00 on 08/17/2007.

  Note: The Display Value and State columns are not supported in the filter expression.

  Tip: It is not necessary to use square brackets when columnname is one word (for example, Value), but doing so can make the filter expression easier to read.

  You can combine several conditions simultaneously by using the logical operators AND, OR, and NOT. You can also use parentheses to establish the order of operations. For example:

  [Type]='HiHi' OR [Type]='LoLo' AND [Activation Time]>'08/17/2007 15:00'

  ([Tag Name] Like 'Tag1') AND ([Tag Name] NOT Like 'Tag2') AND [Custom1]='MyCustomArea'

  You can use wildcards (* and ?) in the filter expression. You can also change the filter expression during run time by specifying project tags and/or built-in functions in curly brackets. For example:

  [Value]='{AlarmFilterValue}'

  [ActivationTime]<='{DateTime2UTC(Date + " " + Time)}'

  Please note that filtering by time works only if the Alarm/Event Control object is configured to show alarm history, and all times should be specified in Coordinated Universal Time (UTC), because that is how the alarm history is saved. If you need to convert between local time and UTC, you can use the Date and Time functions.

  The Alarm Filter Expression dialog box has a limit of 1024 characters. You can configure a filter expression of up to 2048 characters, however, by using the curly brackets syntax described above. The contents of the brackets will be evaluated during run time. So, for example, you can specify two or more project tags (String type) that contain parts of the overall expression and then use AND operators to combine the parts:

  {MyFilterExpression1} AND {MyFilterExpression2}

  Note: If your filter expression includes any dates, they must be in the current date format. If they are not, you might see unexpected behavior during run time. For more information, see About the date format and how to change it.

• Use the settings in the Initial Sort group to set the default sorting order. Select a sort type from the Column combo-box, and then select Asc or Desc to sort in ascending or descending order. You can configure up to three levels of sorting.

  Note: If you configure all three levels with sort types other than Activation Time, then the project will automatically sort on a fourth level according to Activation Time, in descending order.

  You cannot change the type of this fourth-level sort, but you can toggle its default order — from descending to ascending — by manually editing your project file (<project name>.app) to change the following setting:

  [Objects] DescendingAlarmListTime=TRUE or FALSE

  TRUE sorts in descending order, FALSE sorts in ascending order.

  Click the Allow sort in runtime checkbox if you want to allow the user to change the sort order during runtime.

Columns

Click the Columns button to open the Columns dialog box where you can specify display properties for columns in the object.

• The Available list contains all of the column types available for this object. The Visible list contains all of the column types currently in use for the object.

  Click the » and « buttons to move selections between the two lists.

  Tip: You can configure an Alarm Control object to display recently replaced values together with their new values. To do so, move both Value and Previous to the Visible list.

  Click the Move Up or Move Down buttons to rearrange the order of columns in the Visible list.

• Use the Label and Width fields in the Properties group to change the default column labels and widths at runtime.

• Use the Align combo box to specify alignment (Left, Center, or Right) for the alarm message text within a specified column.

• Click (enable) the Available during runtime checkbox to allow the user to add selected columns to the visible list during runtime.

• Use the Key box to assign a shortcut to each column. This allows you to sort the information on the Alarm Control object by any column, using keyboard keys instead of the mouse cursor.

When you are finished, click OK to close the Column dialog box.

Tip: You can associate text labels with priority values, so that more meaningful information is displayed in the Priority column of the Alarm Control. To do this, manually edit your project file (<project name>.APP) to add the following entries:

[Alarm] PriorityLabelCount=N (total number of labels)

PriorityValue1=value

PriorityLabel1=label

...

PriorityValueN=value

PriorityLabelN=label

Here is an example:

[Alarm]

PriorityLabelCount=3

PriorityValue1=490

PriorityLabel1=ALMTest

PriorityValue2=480

PriorityLabel2=Test2

PriorityValue3=470

PriorityLabel3=Test100

Advanced

Click the Advanced button to open the Advanced dialog box where you can specify advanced properties for the Alarm/Event Control object.

• Use the settings in the Date and Time Format group to control which date and time information displays in the alarm message. Click (enable) a checkbox to include that element in the display. Note: MS stands for milliseconds.

  Tip: Watch the Sample text to preview how the information will look in the alarm message.

• Use the settings in the Delete Message group to control who can delete alarm messages from the Alarm History:

  • Security: Use this field to specify which security level can delete alarm messages. Only those users with the specified security level will be allowed to delete an alarm message.

  • Confirm: Select this option to require the user to confirm a message deletion.

• Use the settings in the Acknowledgement group to control how alarms are acknowledged:

  • Ack All trigger box: Type a tag to receive a value. When the tag value changes, it indicates that all messages in the alarm object have been acknowledged.

  • Ack trigger box: Type a tag to receive a value. When the tag value changes, it indicates that the message at the top of the alarm object has been acknowledged.

  • Ack comment list: Select Disabled, Optional, or Mandatory to determine whether the user can or must enter comments after acknowledging alarms.

  • Disable ack on double click box: Type either a numeric value or a tag/expression. When it evaluates as TRUE (non-zero), the user cannot acknowledge alarms by double-clicking (or double-tapping) them. This option may be used, for example, either to force the operator to click another button to acknowledge the alarm or to prevent alarms from being acknowledged on thin clients.

  • Security box: Type a numeric value to specify which security level can acknowledge an alarm message. Only those users with the specified level can respond.

  • Require confirmation checkbox: Select this option to display a confirmation dialog when the user tries to acknowledge a single alarm.

• Use the settings in the Run-time returned values group to get information about the alarms during run time:

  • Total items box: Type an integer tag to see how many alarms remain after filtering the alarm object using parameters specified on the Filters dialog box.

  • Selected tag box: Type a string tag to enable the end user to click on an alarm message to see the name of the tag associated with that message.

  • First Row Text box: Type the name of a project tag or array (String type). That tag or array will receive the contents of the columns of the first row of the Alarm/Event Control. If you specify a tag, the columns will be separated by tabs. If you specify an array, the array elements will each receive one column. If the array is not large enough to receive all of the columns, the remaining columns will be discarded. Whenever the first row changes — either due to a new Alarm/Event, or simply because the rows are reordered — the specified array is updated.

  • Selected Row Text box: Type the name of a project tag or array (String type). That tag or array will receive the contents of the columns of the selected row (that is, the row that the user has clicked/tapped) of the Alarm/Event Control. If you specify a tag, the columns will be separated by tabs. If you specify an array, the array elements will each receive one column. If the array is not large enough to receive all of the columns, the remaining columns will be discarded. Whenever the selected row changes — that is, whenever the user clicks/taps another row — the specified array is updated.

  • Summary Changes box: Type the name of a project tag (Integer type). That tag will receive a running count of the number of changes in the Alarm/Event Control. For example, when a new Alarm occurs or when an Alarm is acknowledged, the value of the configured tag will be incremented. Reordering the rows is not counted as a change.

• Use the settings in the Run-time dialog triggers group to allow the user to customize the object during run time:

  • Columns box: Type a tag name. When the tag value changes, it opens a dialog box allowing the user to customize the columns visible in the object.

  • Filters box: Type a tag name. When the tag value changes, it opens a dialog box allowing the user to filter the columns visible in the object.

• Auto Format checkbox: When checked, decimal values in the Display Value, Previous and Value columns of the object will be formatted according to the virtual table created by the function SetDecimalPoints.

• Use the Save / Print group to control the printing of alarms during run time:

  • Print Trigger: When the tag configured in this field is toggled, the current state of the Alarm/Event Control object is sent to the default printer.

  • PDF Trigger box: When the tag configured in this field is toggled, the current state of the Alarm/Event Control object is saved as a PDF file at the location specified by PDF Filename.

  • PDF Filename box: Enter a complete file path and name where the PDF file is to be saved. This field accepts String expressions.

    Note: PDF Trigger and PDF Filename are not supported in projects running on Windows Embedded or on Thin Clients.

  • Multiline checkbox: When this option is checked, the print output or PDF will be formatted according to the available column space, and the text within each cell will be wrapped so that all of it is shown.

• Click the Navigation Triggers button to open the following dialog box:

  

  You can make the on-screen Alarm Control object scroll up, scroll down, page up, page down, go to home (beginning) of page, or go to end of page by configuring tags in the corresponding fields. Whenever the values of the configured tags change, the Alarm Control object will navigate that way. This is useful for adding navigation controls to the screen; for example, if you configure the same tag to the Up field in this dialog box and a Pushbutton object, then the Alarm Control object will scroll up whenever the Pushbutton object is pressed.

When you are finished, click OK to close the Advanced dialog box.

Fonts

Click the Fonts button to open a standard Fonts interface where you can specify display properties for the message text.

Format

Use the Format area of the object properties to configure the appearance of the Alarm/Event Control object during run time:

• Select Show header to show a header on the object. The header displays the column labels.

  

• Select Show gridlines to show gridlines in the object. Gridlines can make it easier to distinguish individual rows and columns in the object.

  

• Use the Background color box to select a background color for the object. Click the box to open the color palette pop-up, then click a color to select it.

• Click Colors to open the Colors dialog box, which you can use to select background and foreground colors for specific alarms. These colors will override the default colors that you selected in your Alarm worksheet(s). This is useful for highlighting special alarms.

  

  Note: This feature is not supported in projects running on Windows Embedded target systems.

  In each row of this table, you can configure a subset of alarms using similar criteria as in the Filters dialog box, and then for that subset you can select custom background and foreground colors:

  1. In the Group box, type the number of the Alarm group/worksheet. You may use commas and/or dashes to specify a range of groups.

  2. In the Active box, select All (both active and normalized alarms), Active (active alarms only), or Norm (normalized alarms only).

  3. In the Ack box, select All (both acknowledged and unacknowledged alarms), Acked (acknowledged alarms only), or Unacked (unacknowledged alarms only).

  4. In the Selection box, type the selection text that you configured in the Alarm worksheet. You may leave this box empty.

  5. In the Priority box, type the priority number that you configured in the Alarm worksheet. You may leave this box empty.

  6. Click the BG Color box to open a color picker, and then select the color that you want to be the background color of the alarm message.

  7. Click the FG Color box to open a color picker, and then select the color that you want to be the foreground color of the alarm message.

  8. Select Blink if you want the alarm message to blink. This will make it more noticeable.

  Please note that the subsets you configure here must pass any filters that you previously configured in the Filters dialog box. For example, if you configured the filters to show groups 1-6 in the Alarm/Event Control object, then configuring a subset of group 7 here will have no effect.

  Also, the colors that you select will be used to indicate all possible alarm states (that is, activation, acknowledgement, and normalization), if you configure the subset to include all of those states. Therefore, if you want different colors for different alarm states, then you must configure additional subsets.