Custom Alarm Hook API
In versions of VTScada prior to release 11.2, developers who wanted to add custom functionality to an alarm event would override a module of the Alarm Manager to add their code. That technique is now obsolete. Many existing overrides will continue to work, but should be tested before being put into production use with version 11.2 or later.
To add extra functionality to an alarm transaction, create an alarm hook module. A set of hook names has been defined within the Alarm Manager. If your application contains a module with a matching name, it will be called just before the transaction is logged, allowing you to perform extra work.
An alarm hook may not return INVALID. It should return TRUE to allow the transaction to proceed and be logged. Alarm hooks that return FALSE will stop the transaction from proceeding.
The module may be defined with one parameter, which VTScada will use to pass in the fully-populated transaction structure.
Defined alarm hooks:
- AlarmAckHook
- AlarmAckAllHook (*)
- AlarmActiveHook
- AlarmCellAckHook
- AlarmCommissionHook
- AlarmDecommissionHook
- AlarmDisableHook
- AlarmEnableHook
- AlarmEventHook
- AlarmModifyHook
- AlarmNormalHook
- AlarmNormalAckHook (**)
- AlarmNormalTripHook (**)
- AlarmOffNormalHook (***)
- AlarmPlaySoundFilterHook
- AlarmPurgeHook
- AlarmRearmHook
- AlarmShelveHook
- AlarmTripHook
- AlarmUnshelveHook
(*) AlarmAckAllHook is unlike the other alarm hooks. The other hooks are called at the time the alarm transaction takes place, can alter the transaction structure, and can return true or false depending on whether they want the transaction to be logged or not. The AlarmAckAllHook will be called before the acknowledgment transactions take place. It will not be able to alter any transaction structures. If AlarmAckAllHook returns TRUE or Invalid, the alarms will all be acknowledged. If it returns FALSE, the alarms will not be acknowledged.
Note that AlarmAckAllHook is called only on the workstation where Ack All is pressed. If this needs to be shared via remote procedure calls to a different workstation, then your module to implement AlarmAckAllHook must include that feature.
(**) If this hook is not defined, AlarmNormalHook will be called instead.
(***) If this hook is not defined, AlarmActiveHook will be called instead.
Examples:
Do something extra when the alarm closes:
<
AlarmNormalHook
(
{ parameter not required }
)
[
{ ... local variables ... }
]
Main
[
If 1;
[
{ Do something like write out a value to a PLC }
DoSomething();
{ Returning Invalid or TRUE allows the AlarmManager to log the Transaction when we’re done }
Return(TRUE);
]
]
>
Clear the alarm when it is acknowledged:
<
AlarmAckHook
(
TransactionStruct { transaction structure };
)
Main
[
If 1;
[
{ Acknowledge and Clear the alarm }
TransactionStruct\Transaction = Concat(TransactionStruct\Transaction, "Active-");
{ The additional transaction text is added to any that already exist. }
Return(TRUE);
]
]
>
To mute a subset of alarms, add a hook module named AlarmPlaySoundFilterHook.SRC to your application, declaring it in the AppRoot.SRC file. If this hook module exists in the application, it will be passed an alarm record for every alarm that could potentially be played. If the hook returns TRUE or Invalid, the alarm will be played, so long as the global Mute is not enabled. If it returns FALSE it will not be played. The parameter, Record, is documented in Alarm API Structure Definitions
The test within the hook might resemble the following generic example, where the Area property of the alarm record structure is being examined along with the name of the workstation. Alarms in the West area sound only on Server1 and alarms in the East area sound only on Server2.
<
AlarmPlaySoundFilterHook
(
Record { Alarm record };
)
Main
[
If 1;
[ CanPlay = Record.Area == "WEST" && WkStaInfo(0) == "SERVER1" || Record.Area == "EAST" && WkStaInfo(0) == "SERVER2";
Return(CanPlay); ] ] >
Alarm API Structure Definitions - Includes the transaction structure.
