Technical information

Programming - Advanced Topics
111
RMS Enterprise - NetLinx Programmer’s Guide
Programming - Advanced Topics
Listening for RMS Notification Events
RMS Enterprise introduces a SUBSCRIBER / EVENT LISTENER pattern for handling event notifications emitted from the RMS
Client via the RMS NetLinx Adapter as command data events over the (vdvRMS) RMS NetLinx virtual device interface. This
pattern is implemented via the inclusion of the RmsEventListener.axi Include File via the use of compiler directives and callback
methods.
To subscribe to an RMS event, you must include the RmsEventListener.axi Include File in your parent program (if it is not already
included).
Next include a #DEFINE INCLUDE_RMS_EVENT_XXXXX statement for each event that you want to handle. The list of
available event and #DEFINE directives can be found in the source code comments inside the RmsEventListener.axi Include File.
In this example, we will subscribe to two events: System Power Request and Client Online.
#DEFINE INCLUDE_RMS_EVENT_SYSTEM_POWER_REQUEST_CALLBACK
#DEFINE INCLUDE_RMS_EVENT_CLIENT_ONLINE_CALLBACK
This will effectively enable the callback method invocation to our main program anytime the RMS client reached the ONLINE
state, and when a SYSTEM POWER state change request has been made.
Enabling these two compiler directives will expose code in the RmsEventListener.axi Include File to perform calls to the following
method signatures (these are known as callback methods). These methods must be defined in your main program.
Internally, the RmsEventListener.axi Include File includes a NetLinx DATA_EVENT listener on the RMS NetLinx Virtual Device.
Upon receiving a COMMAND DATA_EVENT, this implementation code will parse the command header and any necessary event
arguments. It will then perform the appropriate the callback method.
// THIS CALLBACK METHOD IS INVOKED AUTOMATICALLY WHEN
// THE SYSTEM POWER STATE CHANGES
DEFINE_FUNCTION RmsEventSystemPowerChangeRequest(CHAR powerOn)
{
}
// THIS CALLBACK METHOD IS INVOKED AUTOMATICALLY WHEN
// RMS HAS REQUESTED THAT SYSTEM POWER BE CHANGEDT
DEFINE_FUNCTION RmsEventClientOnline()
{
}
The method signatures that correspond to each event are also listed in the source code comments in the RmsEventListener.axi
Include File.
You should place your custom implementation logic in the body of each of these callback methods.
Listening for RMS Exceptions
RMS Exceptions (Errors) encountered by the RMS Client (RMS Engine) are delivered to the RMS NetLinx Virtual Device via
COMMAND DATA EVENTS. The RmsEventListener.axi Include File provides an event callback to easily handle these events.
Refer to the documentation for RmsEventListener.axi and see the Listening for RMS Notification Events section on page 111 for
more details on the inner workings of the notification callbacks in RMS.
First, you must subscribe to the event notification. This is done using the following compiler directive. Make sure this is defined in
your user NetLinx program.
// SUBSCRIBE TO RMS EXCEPTION CALLBACK NOTIFICATIONS
#DEFINE INCLUDE_RMS_EVENT_EXCEPTION_CALLBACK
Next, you must define the following callback method in your user NetLinx program. The method will automatically be invoked by
the RMS SDK anytime a RMS Exception event is received. You should implement your custom handling logic inside this callback
method.
The event will include an exception textual message and the command header of the offending command sent to the RMS NetLinx
virtual device if one is present: