unSystemIntegrity 9.1.0
|
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:
unSystemIntegrity_AlarmDescriptionTimestamp
structure were four parameters (time, atime, string, and int) are defined to store information about the alert information.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.unSystemIntegrity_registerAlarmDescription(string dpeAlarm1, shared_ptr<unSystemIntegrity_UpdateAlarmDescription> updAlDesc, dyn_string &exceptionInfo)
function calls the dpQueryConnectSingle()
, using ‘"SELECT ALERT ’_alert_hdl.._value' FROM '" + dpeAlarm + "'"as query parameter, and
unSystemIntegrity_updateAlarmDescriptionCBas callback function. When there is a change in the value of the alerts the callback function is triggered. The shared pointer
updAlDesc` is passed as input user data parameter.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.unSystemIntegrity_setAlarmDescription(string alarmDescription, time timeStamp, atime aTimeStamp, string dpeAlert)
function sets the alarm description using alertSetWait()
with the required parameters.unSystemIntegrity_getAlarmDescription(string dpeAlarm, dyn_string &exceptionInfo)
function returns the alarm description for a given alarm datapoint element.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.
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.
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.
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:
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
.