AlarmSetInfo

Controls different aspects of the alarm list displayed at a specified AN.

Syntax

AlarmSetInfo(AN, Type, Value)

AN:

The AN where the alarm list originally commenced. (AN alarm page can contain more than one alarm list). You can also specify:

-1 - Change the display parameters of all alarm lists displayed on the page.

0 - Change the display parameters of the alarm list where the cursor is positioned.

Type:

The type of data. The aspects and related types are listed below:

0 - Alarm page number. The vertical offset (in pages) from the AN where the alarm list commenced.

1 - Alarm list offset. The vertical offset (in lines) from the AN where the alarm list commenced.

2 - Category of alarms displayed on the alarm list. To specify all categories use a value of 0.

You can use a group handle to display a group of categories. (A group can be defined using Groups - from the Project Editor System menu - or by using the GrpOpen() function.) Before you can display a group of categories, you need to first open the group using the GrpOpen() function. You would usually do this by entering the GrpOpen() function as the Page entry command for your alarm page (set using Page Properties). Be aware, however, that you should not close the group until you close the display page. If you do, the group will be lost and the group handle will become invalid. The page would then be unable to continue displaying the desired group. The handle may be reused for another group, which means the page may display a different category, or display all alarms.

You would normally close the group by entering the GrpClose() function as the Page exit command.

3 - Type of alarms displayed on the alarm list. See AlarmDsp() for a list of these types.

4 - Display all alarms according to the format and fonts specified for one category (specified in Value).

5 - The display format for all alarms specified by a format handle. All of the alarm categories will display in the same format.

6 - The display font for all user alarms specified by a font handle. All of the user alarms will appear in the same font and color.

7 - The priority of the alarms to be displayed in the alarm list. You can use a group number to display a group of priorities.

You can use a group handle to display a group of priorities. (A group can be defined using Groups - from the Project Editor System menu - or by using the GrpOpen() function.) Before you can display a group of priorities, you need to first open the group using the GrpOpen() function. You would usually do this by entering the GrpOpen() function as the Page entry command for your alarm page (set using Page Properties). Be aware, however, that you should not close the group until you close the display page. If you do, the group will be lost and the group handle will become invalid. The page would then be unable to continue displaying the desired group. You would normally close the group by entering the GrpClose() function as the Page exit command.

8 - Use the Value argument of the AlarmSetInfo() function to specify whether the display mode of the alarm list is based on Alarm Category or Priority:

• Set the Value argument to 0 (zero) to display by Category.
• Set the Value argument to 1 to display by Priority.

9 - Use the Value argument of the AlarmSetInfo() function to specify the sorting mode of the alarm list:

• Set the Value argument to 0 (zero) to display alarms sorted by ON time within their groups.
• Set the Value argument to 1 to display alarms sorted by the order-by keys. Please be aware that this option will only be meaningful if you have already called the AlarmSetInfo() function with a Type of 10 to set the order-by keys.

10 - Use the Alarm Order-by key specified in the Value argument of the AlarmSetInfo() function to determine the order in which the alarm list will be displayed.

The AlarmSetInfo() function should then be called again using a Type of 9 and a Value of 1 for CitectSCADA to sort the alarms in the order specified.

Be aware that you cannot sort Summary Alarms using this mode. Summary Alarms can only be sorted with the citect.ini settings [Alarm]SummarySort and [Alarm]SummarySortMode.

Value:

The meaning of the Value argument depends on the data type specified in the Type argument.

• If you set Type = 8, the Value argument determines whether alarms are displayed by category or priority:
• • 0 - Alarm list displayed by Category.
  • 1 - Alarm list displayed by Priority.
• If you set Type = 10, the Value argument specifies the order-by keys to be used in sorting. Up to sixteen keys may be specified:
  
  {KeyName [,SortDirection]}[ {KeyName [,SortDirection]}]

The Keyname argument specifies the name of the pre-defined order-by key to be used. The valid options are a subset of the alarm display fields: Tag, Name, Category, Priority, Area, Priv, Time, State.

The SortDirection argument is optional, and indicates whether the sort will be ascending or descending. Valid options are: 0 Descending (default), 1 Ascending.

For example:

{Time,0} : sorts by <Time> (descending)
{Tag,1} : sorts by <Tag> (ascending)
{Tag,1}{Time} : sorts by <Tag> (ascending), then <Time> (descending)

Return Value

0 (zero) if successful, otherwise an error is returned.

Related Functions

GrpOpen, AlarmDsp, AlarmGetInfo

Examples

In the following example, the alarm list is set to display in the order of the order-by key. Please be aware that this is a two-step process requiring two calls to the AlarmSetInfo() function, and that it applies only to non-hardware alarm lists.

! Set the order-by key.

AlarmSetInfo(21,10,"{Time}");

! Set the sorting mode.

AlarmSetInfo(21,9,1);

Type 8 of the function is used to set the display mode to either category or priority. This is helpful when filtering based on either of these fields. So In order to filter on category 2 we should use:

AlarmSetInfo(21, 8, 0);

AlarmSetInfo(21, 2, 2);

Once we do this the alarms with category 2 will be displayed in the alarm list and remaining although active will not be displayed.

Similarly if we want to filter on priority we set the mode to priority and then use type 7. For example to filter on priority 4 we should use:

AlarmSetInfo(21, 8, 1); ! priority mode

AlarmSetInfo(21, 7, 4); ! apply filter

In the following examples, the display parameters of the alarm list where the cursor is positioned are changed.

! Change the vertical offset (pages) to 2.

AlarmSetInfo(0,0,2);

! Change the vertical offset (lines) to 15.

AlarmSetInfo(0,1,15);

Change the alarm category to 10.

AlarmSetInfo(0,2,10);

Change the type of alarms displayed to type 5 (hardware alarms).

AlarmSetInfo(0,3,5);

In the following examples, the display parameters of the alarm list at AN 20 are changed.

! Display alarms with category 120 format and fonts

AlarmSetInfo(20, 4, 120);

! Display alarms with a new format

hFmt=FmtOpen("MyFormat","{Name}{Desc,20}",0);

AlarmSetInfo(20, 5, hFmt);

! Display alarms with a new font

hFont = DspFont("Times",-60,black,gray);

AlarmSetInfo(20, 6, hFont);

The following example displays alarms with categories 1-10, 20, or 25. Before AlarmSetInfo() is run, the page entry command for the alarm display page is configured as follows:

On page entry command: hGrp=GrpOpen("MyGrp",1); StrToGrp(hGrp,"1..10,20,25");

The page exit command for the alarm display page is configured as follows:

On page exit command: GrpClose(hGrp); AlarmSetInfo(20, 2, hGrp);

Note:hGrp is defined in the variables database.

See Also

Alarm Functions