Controls different aspects of the alarm list displayed at a specified AN. Currently applies only to non-hardware alarm lists.
Syntax
INT AlarmSetInfo(INT AN, INT Type, STRING 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:
|
Display aspect |
Types |
|---|---|
|
Change display line and page offset |
0, 1 |
|
Formatting of alarms in the alarm list |
4, 5, 6 |
|
Filtering of alarms |
2, 3, 7, 8 Note: If a requested alarm filter is too complex (for example, it contains too many conditions or too many nested brackets), the filter is cleared (no filter is used). The hardware alarm "Too many alarms in filters" is generated on the client components, and a tracelog error message is logged. |
|
Sorting of alarms - to control the sorting aspect of the alarm list, type 9 and 10 should be used together. |
9, 10 |
|
Linking or unlinking to a named filter. |
12 |
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 via the Security activity, 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:
9 - Use the Value argument of the AlarmSetInfo() function to specify the sorting mode of the alarm list:
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 Citect SCADA to sort the alarms in the order specified.
Note: It is recommended that you sort an alarm summary or SOE list using the following order-by keys (as specified in the Value argument):
• Alarm summary – OnDate, OnTime, OnMilliseconds
• SOE – Date, Time, Milliseconds.
If you use any other fields as an order-by key, you will have to apply a time range to your query using the Alarm Filter Functions. Otherwise, your query will not return any results and the hardware error "Invalid Argument Passed" will be generated.
11 – Invalid to set this field.
12 – Associate or disassociate a named filter. By setting this field to text, you associate the specified AN to a named filter which is then applied to an alarm display list. Setting this type to empty text, will unlink from any named filter, but the disassociated alarm list will retain its value, hence the filter will still be in place until a new filter is applied. If setting the Value to text that does not correspond to a named filter, the value read back (using AlarmGetFilterName()) will be empty.
15 – Auto-refresh mode, where mode is:
Note: Type 15 is only in use if displaying the alarm summary (AlarmDsp Type 10).
16 – Invalid to set this field.
Value:
The meaning of the Value argument depends on the data type specified in the Type argument.
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 code 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.
Related Functions
See Also
Published June 2018