AlarmSumAppend | Alarm Functions

Appends a new blank record to the alarm summary. Use this function to add new alarm summary entries, either for actual alarms or as special user summary entries.

If you specify a valid alarm tag in the sTag field, the summary entry is linked to the actual alarm. If you specify an asterisk '*' as the first letter of the tag, the summary entry becomes a user event.

User events are not attached to alarm records, so their status will not change. Manually change the status of the user event, by calling the AlarmSumSet() function with the index returned by AlarmSumAppend(). As user events are not attached to alarms, they don't have the alarm fields - so the AlarmSumGet() function will not return any field data.

The latest entry in the Alarm summary will reflect the events of the alarm whether the alarm summary entry was appended created by an actual alarm event.

You can use user events to keep a record of logins, or control operations that you need to display in the alarm summary etc. The fields of UserEvents needs to be set immediately after creation using the AlarmSumSet() function.

To give an appended alarm summary entry the appearance of having been Acknowledged set the Acknowledge time of the summary entry. When the summary entry is linked to an actual alarm the function AlmSummaryAck() can be used to acknowledge the actual alarm linked to the summary entry. However the AlmSummaryAck function will not directly affect the alarm summary entry.

AlarmSumAppend() can only be used if the Alarm Server is on the current machine. When the Alarm Server is not in the calling process, this function will become blocking and cannot be called from a foreground task. In this case, the return value will be undefined and a Cicode hardware alarm will be raised.

Note: The index passed to AlarmSum* functions must be current. ie either:
- the index returned by most recent call to AlarmSumFirst/Last/Find/Next/Prev, OR
- the index returned by the most recent call to AlarmSumAppend OR AlarmSumSplit

The AlarmSumNext and AlarmSumPrev Cicode functions are unable to use the index returned by AlarmSumAppend.

Note: This function will only work while the record is writable which is controlled by the ArchiveAfter Parameter. Refer to the topic Configure the Archiving Parameters in the main help for more information.

Note: In a redundant pair scenario, this function will return an error condition and not do anything if the current server is not main. You can call this function on the primary server and the standby server so that function can succeed on one of the two servers in the specified cluster. The change will be synchronised to the other server after a short period of time (typically in 5 seconds).

The alarm tag to append. Use an asterisk '*' as the first letter to append a user event to the alarm summary. Please be aware that the AlarmSumAppend function returns the alarm summary index - not the error code.

Specifies the name of the cluster in which the Alarm Server resides. This is optional if you have one cluster or are resolving the alarm server via the current cluster context. The argument is enclosed in quotation marks "".

The alarm OnTime (if omitted or is equal to 0, will default to current time, i.e. the time the function was invoked).

New alarm record is created on both redundant server instances. This parameter has been deprecated and is always set to true.

The index of the alarm summary entry, or -1 if the record could not be appended.

Note: The index is a 32-bit integer. Storing it in a variable that is smaller than 32 bit integer (such as a 16-bit integer) may cause overflow which may result in an incorrect value.

! Append alarm to summary display
AlarmSumAppend("CV101");
! Append user event
iIndex = AlarmSumAppend("*MyEvent");
AlarmSumSet(iIndex, "Comment", "My event comment");