Subscribing Tasks
Subscribing to a Channel
Once you have installed the Universal Messaging RTD server, the server will be available for use in any Excel spreadsheet on the system. To start subscribing you need to use the RTD function in Excel. The RTD function is used in the same way as any other Excel function. By entering the function with the correct parameters into a cell, you will immediately subscribe to the specified channel and receive the value associated with the specified property contained in the event.
RTD Function
The RTD function is a built in Excel function but the parameters are specific to the Universal Messaging RTD server. To subscribe to a Universal Messaging channel you need to use the following structure:
=RTD("Universal MessagingRTD",,RNAME,Channel,Property,Key,Value,Key2,Value2 ...)
The parameters are explained below:
"Universal MessagingRTD"
This is the CLSID which has been registered for the Universal Messaging RTD server. By specifying this ID, Excel will lookup the Universal Messaging RTD server in the Windows Registry.
Second Parameter
The second parameter is left blank because the Universal Messaging RTD server is installed on the local machine. If it were installed remotely, the server would be specified here.
RNAME
The RNAME of the realm which the cell should connect to. You may also specify certain configurations for the session in this field. The RNAME is of the form:
protocol://host:port?property=value&property2=value2...
The following properties are available:
user - this is the username that will be used to connect to the realm
Channel
The name of the Universal Messaging Channel which you wish to connect to. You may also specify channel specific configuration properties in this field. The Channel field has the form:
/folder/channelname?property=value&property2=value2...
The following properties are available:
eid - the eid for which to start subscribing. This value is -1 by default which means subscription starts from the last eid of the channel (will not receive any events currently on the channel). -2 will mean the last event published on the channel is consumed as well as any further events published and hence -3 will mean the last 2 are consumed etc. A positive value will cause mean events from that eid onward are consumed so 0 means all events on the channel will be consumed.
hwmark - the high water mark for the event queue of the channel. This ensures that the event queues do not grow too large without dropping any events. For more information see
Queue watermarks.
lwmark - once the event queue has reached high watermark, no more events will be added to the event queue. Once the queue length reaches lwmark (low watermark) the listener is notified to continue receiving events.
Key, Value
The Universal Messaging RTD server allows you to filter events based on key-value pairs. Here the value of Property is only shown if the event properties contains each key and the value associated with that key.
A Universal Messaging Event can contain nEventProperties which themselves can contain nested nEventProperties. These nested properties are accessed by a key in the same way as the values are accessed. In order to access the key-value pairs contained within the inner properties using the RTD server, you should use the syntax shown below:
...,propsA.Key,value,propsA.propsB.key,value,...
Here propsA is found inside the main nEventProperties for the nConsumeEvent. Inside propsA is a set of key-value pairs but also another nEventProperties object called propsB which itself contains key-value pairs and possibly further nEventProperties.