unSystemIntegrity 9.2.0
System Integrity Alarm Description Documentation

Functionalities of unSystemIntegrity_alarmDescription.ctl script

A new script called unSystemIntegrity_alarmDescription.ctl has been implemented to register, update, set, and obtain alarm descriptions for system integrity alarms. The script can be divided into:

  • The unSystemIntegrity_AlarmDescriptionTimestamp structure were four parameters (time, atime, string, and int) are defined to store information about the alert information.
  • The UpdateAlarmDescription class, which is formed by the updateAlarmDescription(time timeStamp, atime aTimeStamp, string dpeAlert, int alarmValue) event and the triggerUpdateAlarmDesc(time timeStamp, atime aTimeStamp, string dpeAlert, int alarmValue) function to trigger the updateAlarmDescription event. The function and event have four input parameters to be able to propagate alert information to set the description later on.
  • The unSystemIntegrity_registerAlarmDescription(string dpeAlarm1, shared_ptr<unSystemIntegrity_UpdateAlarmDescription> updAlDesc, dyn_string &exceptionInfo) function calls the dpQueryConnectSingle(), using ‘"SELECT ALERT &rsquo;_alert_hdl.._value' FROM '" + dpeAlarm + "'"as query parameter, andunSystemIntegrity_updateAlarmDescriptionCBas callback function. When there is a change in the value of the alerts the callback function is triggered. The shared pointerupdAlDesc` is passed as input user data parameter.
  • The unSystemIntegrity_updateAlarmDescriptionCB(anytype userData, dyn_dyn_anytype alertInfo) function triggers the updateAlarmDescription(time timeStamp, atime aTimeStamp, string dpeAlert, int alarmValue) class event by calling the triggerUpdateAlarmDesc(time timeStamp, atime aTimeStamp, string dpeAlert, int alarmValue) class function.
  • The unSystemIntegrity_setAlarmDescription(string alarmDescription, time timeStamp, atime aTimeStamp, string dpeAlert) function sets the alarm description using alertSetWait() with the required parameters.
  • The unSystemIntegrity_getAlarmDescription(string dpeAlarm, dyn_string &exceptionInfo) function returns the alarm description for a given alarm datapoint element.

General Guidelines

The general guidelines for the alarm description implementation for system integrity alarms is to first call the unSystemIntegrity_registerAlarmDescription(string dpeAlarm, shared_ptr<UpdateAlarmDescription> updAlDesc, dyn_string &exceptionInfo) function inside the unSystemIntegrity_xxxxx.ctl script (being xxxxx the type of the system integrity alarm, for example api) right after processing the action of clicking the button to add or enable an alarm in the system integrity configuration panel. This function must be called inside unSystemIntegrity_xxxxx_checking before registering the checking callback function by _unSystemIntegrity_registerFunction, as the dpQueryConnectSingle that connects to the value of the alerts should be invoked before doing any potential change to the alarm value.

After unSystemIntegrity_registerAlarmDescription() function, the call to classConnect("unSystemIntegrity_xxxxx_alarmDescriptionCB", updAlDesc, UpdateAlarmDescription::updateAlarmDescription) must follow. The classConnect() is used as a ‘listener’, meaning that the callback function introduced as first parameter must be invoked whenever the updateAlarmDescription class event has been triggered. The unSystemIntegrity_xxxxx_alarmDescriptionCB(time timeStamp, atime aTimeStamp, string dpeAlert, int alarmValue) callback invokes the unSystemIntegrity_setAlarmDescription(string alarmDescription, time timeStamp, atime aTimeStamp, string dpeAlert) to write alarm descriptions.

If the buttons to disable or remove an alarm from the system integrity configuration panel have been pressed, the classDisconnect("unSystemIntegrity_xxxxx_alarmDescriptionCB", updAlDesc, UpdateAlarmDescription::updateAlarmDescription) function is called to stop updating alarm descriptions for that specific system integrity alarm type.

For most of the system integrity alarms, the alarm description is obtained from its corresponding catalog in /msg/en_US.utf8/ or /msg/en_US.isoXXXX/ directories using the function getCatStr().

To retrieve an alarm description, the unSystemIntegrity_getAlarmDescription(string dpeAlarm, dyn_string &exceptionInfo) function is called. This function returns a string with the alert text description of the system integrity alarm. The function has two parameters, the datapoint element for the alarm as input, and the exception message as output. At the moment, the unSystemIntegrity_getAlarmDescription function is only used in the applicationOperationDetail.pnl panel to have additional information in the menu list when right clicking on a particular alarm in the panel.

To summarize as shown below in Figure 1, the registerAlarmDescription() calls the dpQueryConnectSingle() which triggers the updateAlarmDescription class event whenever there is a change in an alarm value. The classConnect() starts listening to the updateAlarmDescription class event, and invokes the unSystemIntegrity_xxxxx_alarmDescriptionCB callback function whenever the class event has been triggered. The unSystemIntegrity_xxxxx_alarmDescriptionCB passes the alarmDescription string to the unSystemIntegrity_setAlarmDescription(). And finally, the unSystemIntegrity_setAlarmDescription() function calls the alertSetWait() to write the alarm description.

Figure 1. SI Alarm Description Sequence Diagram

Explanation of the logic implemented

The dpQueryConnectSingle, triggerClassEvent, and classConnect combination were implemented after discovering that after calling the dpSet to write the alarm's value, the alarm description using alertSetWait sometimes was not being properly set. After the initial investigation, it was found that the alert handler range and time that must be obtained to set alarm's descriptions could not be retrieved. A delay between the dpSet for the alarm's value and alertSetWait for the alarm's description was necessary. However, adding a delay to the logic is not a good practice, as depending on the systems or processes the time required might be shorter or longer. Therefore, to be more precise, robust, and avoid any future potential time issues, it was decided to implement a dpQueryConnectSingle, triggerClassEvent, and classEvent combination. Although this implementation is more complex, it allows to set the alarm's descriptions exactly after the alarm's value has changed without the need of adding any delay.

Code example for a SystemIntegrity alarm

First, to implement the alarm description for a SystemIntegrity alarm, the script unSystemIntegrity/unSystemIntegrity_alarmDescription.ctl must be loaded.

When a SystemIntegrity alarm is added or enabled, generally a function unSystemIntegrity_xxxxx_checking is called (being xxxxx the type of the system integrity alarm, for example ctrl). The following code must be added to register the alarm description function and the event class listener.

....
if(dynlen(exceptionInfo)<=0) {
// handle alarm description connection/disconnection
shared_ptr<unSystemIntegrity_UpdateAlarmDescription> updAlDesc = new unSystemIntegrity_UpdateAlarmDescription();
if (bRegister) {
// register alarm description
unSystemIntegrity_registerAlarmDescription(dp + ".alarm", updAlDesc, exceptionInfo);
classConnect("unSystemIntegrity_xxxxx_alarmDescriptionCB", updAlDesc unSystemIntegrity_UpdateAlarmDescription::updateAlarmDescription);
} else {
// unregister alarm description
classDisconnect("unSystemIntegrity_xxxxx_alarmDescriptionCB", updAlDesc, unSystemIntegrity_UpdateAlarmDescription::updateAlarmDescription);
}
_unSystemIntegrity_registerFunction(bRegister, "unSystemIntegrity_xxxxx_CheckingCallback", "",
g_unSystemIntegrity_xxxxxList, dp, exceptionInfo);
}
....

In the code above, a call to the new implemented function unSystemIntegrity_registerAlarmDescription is processed. Inside this function, there is a call to a dpQueryConnectSingle that 'listens' to any value changes in the _alert_hdl.._value of the dp + ".alarm" that has been passed as parameter.

The classConnect needs as first parameter a callback function that will be triggered when an event class is fired. In this case, the callback function should look like:

public void unSystemIntegrity_xxxxx_alarmDescriptionCB(time timeStamp, atime aTimeStamp, string dpeAlert, int alarmValue) {
string alarmDescription = getCatStr("xxxxx_systemIntegrity",xxxxx_pattern+alarmValue);
unSystemIntegrity_setAlarmDescription(alarmDescription, timeStamp, aTimeStamp, dpeAlert);
}

If the alarmDescription cannot be obtained from a catalog, then simply pass to the alarmDescription string a message containing the proper description of the alarm.

As stated above, the dpSet may change the value of the alarm. A value change triggers the callback function of the dpQueryConnectSingle inside the unSystemIntegrity_registerAlarmDescription(). This triggers a class event that is listened by the classConnect, and therefore the unSystemIntegrity_xxxxx_alarmDescriptionCB is executed. The function unSystemIntegrity_xxxxx_alarmDescriptionCB passes the alarmDescription string value to the new implemented function unSystemIntegrity_setAlarmDescription, which sets the description using alertSetWait.