Download tutorial source code |
Click here to download |
| Last update | Dec 2020 |
| Compilers | Visual Studio 2015 |
| Prerequisites | EMA NI Provider - Publishing a Source Directory Declare the NI_PUB and TEST_NI_PUB services in your LSEG Real-Time Distribution System (see Before you start). |
Tutorial purpose
In this tutorial, you will learn how to update a market price data item after you sent the initial refresh message.
To this aim we will go through the following sections:
- Introduction
- Update messages
- The Item class
- The NiProvider class
- The main workflow
- Build and run the application
Introduction
In the Publishing our first Market Price tutorial we described the message flow that takes place between NI Providers and Consumer applications. We also explained how to send the refresh messages that convey the initial data of market price data items. In this tutorial, we will teach you how to encode and publish update messages your NI Provider must send when a market price data item changes.
Update messages
Update messages are sent by providers to notify the distribution system and the consumer applications that a data item has changed. For the sake of efficiency, these messages only convey the data that actually changed (for example, an update message of a market price item only contains the fields with new values). This is the most important difference between Update messages and Refresh messages.
Another notable difference is that NI Providers do not have to indicate the service name, the item name (RIC), and the domain type in the update messages they send. Indeed, as this information has already been sent in the initial refresh message, there is no absolute need to repeat it in the updates. However, repeating the service name and the item name is a good practice that may help the ADH to rebuild its cache in case of failover. This is especially true when the connection to the ADH is done via an RSSL_RELIABLE_MCAST channel. Because of the multicast connection, the provider application may not be aware when an ADH fails. Consequently, it will not send any refresh message for its data items when the ADH goes up again. Thus, the ADH that failed over will have to rebuild its cache based on the updates it receives. Adding the service name and the item name to the updates will help this process. This is a good practice we encourage and that we implemented in the update() method below.
So, basically, update messages sent by NI Providers just need to transport the fields that changed and the handle that uniquely identifies the item stream. However, adding the service name and the item name is a good practice we encourage.
The Item class
In the Publishing our first Market Price tutorial we published a single refresh message with hardcoded values. Now that we want to publish updates, we need a source of changing data. To this aim, we introduced an Item class that simulates a live data item. This class is in charge of:
- generating random data for 5 predefined fields (Display name, Bid, Ask, Open price, Close price),
- simulating changes for two of these fields (Bid and Ask),
- generating the handle that uniquely identifies each item stream.
The NiProvider class
The only item
As this tutorial uses only one item, the NiProvider holds only one instance of the Item class, that is preserved in its _theOnlyOneItem private member.
Item _theOnlyOneItem;
This object is used by the refresh() and update() methods described below. It provides the RIC, the handle and the field values these methods need to build and send data for the item.
The Field IDs
For better readability, and because we now use field IDs in two different part of the code, we introduced a Fields enumeration to describe them. It is used by the refresh() method and the new update() method (see below) that build and send refresh and update messages.
enum Fields
{
DSPLY_NAME = 3,
BID = 22,
ASK = 25,
OPEN_PRC = 19,
HST_CLOSE = 21
};
The refresh() method
We refactored the refresh method so that it uses the new Item class and the Fields enumeration. We also added a test at the beginning of the method to verify that we will publish a message for the right item (_theOnlyOneItem). If not, we exit the method.
void NiProvider::refresh(const std::string & itemName)
{
if (!isConnected())
{
cerr << " ERROR: Can't refresh " << itemName << ". The provider is not connected." << endl;
return;
}
if (itemName != _theOnlyOneItem.getName())
{
cerr << " ERROR: Can't refresh " << itemName << ". Unknown item name." << endl;
return;
}
Item & item = _theOnlyOneItem;
cout << " Refreshing " << item.getName() << endl;
_provider->submit(
RefreshMsg()
.serviceName(getServiceName().c_str())
.name(item.getName().c_str())
.domainType(MMT_MARKET_PRICE)
.state(
OmmState::OpenEnum,
OmmState::OkEnum,
OmmState::NoneEnum,
"UnSolicited Refresh Completed")
.payload(FieldList()
.addAscii(
DSPLY_NAME,
item.getDisplayName().c_str())
.addReal(
BID,
item.getBidPrice(),
OmmReal::ExponentNeg2Enum)
.addReal(
ASK,
item.getAskPrice(),
OmmReal::ExponentNeg2Enum)
.addReal(
OPEN_PRC,
item.getOpenPrice(),
OmmReal::ExponentNeg2Enum)
.addReal(
HST_CLOSE,
item.getClosePrice(),
OmmReal::ExponentNeg2Enum)
.complete())
.complete(),
item.getHandle());
}
We added an update() method to the NiProvider class for publishing market price update messages. This method is a kind of simplified version of the refresh() method. It uses the UpdateMsg class instead of the RefreshMsg class to build the message. An overloaded version of the submit() method of the OmmProvider is used to send the message.
Note that before sending the message we call the generateNextTick() method of the item to compute new random values for the Bid price and Ask price.
void NiProvider::update(const std::string & itemName)
{
if (!isConnected())
{
cerr << " ERROR: Can't update " << itemName << ". The provider is not connected." << endl;
return;
}
if (itemName != _theOnlyOneItem.getName())
{
cerr << " ERROR: Can't update " << itemName << ". Unknown item name." << endl;
return;
}
Item & item = _theOnlyOneItem;
cout << " Updating " << item.getName() << endl;
item.generateNextTick();
_provider->submit(
UpdateMsg()
.serviceName(getServiceName().c_str())
.name(item.getName().c_str())
.payload(FieldList()
.addReal(
BID,
item.getBidPrice(),
OmmReal::ExponentNeg2Enum)
.addReal(
ASK,
item.getAskPrice(),
OmmReal::ExponentNeg2Enum)
.complete()),
item.getHandle());
}
The data item stream
The refresh and update messages published for a data item are part of the same stream of messages. Each data item has its own stream that is identified by a unique handle. This handle is unique at the provider level. When you want to publish a new message for an item, you must indicate this handle as the second parameter of the submit() method. In our case, this handle is held by the _theOnlyOneItem object and can be retrieved thanks to the getHandle() method. As we use the same handle for the refresh message and the update messages, all these messages are part of the same item stream, updating the values of the same data item.
The main workflow
The main workflow now leverages the new refresh() method of the NiProvider to publish updates for our single MarketPrice item. After having published the refresh, the workflow waits for 1 second and publishes 30 updates, one every second. Then, it disconnects and exits the application as usual.
int main(int argc, char* argv[])
{
.
.
.
NiProvider provider;
provider.setServiceName("TEST_NI_PUB");
provider.connectAs("YOUR_PROVIDER_USER_NAME");
waitFor(5);
provider.refresh("SHARE-0");
waitFor(1);
for (int i = 0; i < 30; ++i)
{
provider.update("SHARE-0");
waitFor(1);
}
provider.disconnect();
.
.
.
}
Build and run the application
Build the application and start it. Please refer to the Build and Run section within the first tutorial of this series (A barebones EMA NIP application shell) for detailed instructions.
This is what you should get:
- A console application should open and display something like:
-------------------------------------------------------------------------------
| Non Interactive Provider EMA Tutorial |
| |
| Tutorial 7 - Publishing updates |
-------------------------------------------------------------------------------
Provider created
Connecting Provider to ADH 10.2.43.49:14003 as nip-user
Waiting for 5 seconds...
Provider is connected. OmmState:Open / Ok / None / 'Refresh Completed'
Refreshing SHARE-0
Waiting for 1 seconds...
Updating SHARE-0
Waiting for 1 seconds...
Updating SHARE-0
Waiting for 1 seconds...
.
.
.
Updating SHARE-0
Waiting for 1 seconds...
Disconnecting...
Provider is disconnected. OmmState:Open / Suspect / None / 'channel down'
Exiting the application
Press any key to continue . . .
Open a consuming application and subscribe to the SHARE-0 market price item of the TEST_NI_PUB service. After a short while, you should receive values for the 5 fields (DSPLY_NAME/3, OPEN_PRC/19, HST_CLOSE/21, BID/22 and ASK/25) published by the Ni Provider. Then, every second the BID and ASK fields are updated.
As an example, this is a screenshot of the Eikon Quote object that we used to subscribe to TEST_NI_PUB/SHARE-0. In this Eikon, updated fields are displayed in yellow for a short while:
3. After the 30 updates, the TEST_NI_PUB service goes down and the application exits.
4. Press a key to close the console when you are prompted to.
Troubleshooting
Q: When I build the tutorial project, I get errors like:
error MSB3073: The command "copy "\Ema\Libs\WIN_64_VS140\Debug_MDd\Shared\*.*" .\Debug_WIN_64_VS140_Shared\
A: The ElektronSDKInstallPath environment variable is not set or set to the wrong path. See Setup the development environment.
Q: The application is stuck after the "Connecting Provider to ADH…" message is displayed.
After a while the application displays an error like:
Exception Type='OmmInvalidUsageException', Text='login failed (timed out after waiting 45000 milliseconds) for 10.2.43.149:14003)'
A: Verify that the ADH of your LSEG Real-Time Distribution System infrastructure is up and that you properly set the host parameter in the EmaConfig.xml file.
You can also use the telnet command tool to verify that your NIP application machine can connect to the ADH (telnet <ADH host> <port>). If the telnet succeeds but you still can’t connect, verify that you don’t have any firewall blocking the messages sent/received by the application.
Ultimately, ask your administrator to help you to investigate with monitoring tools like adhmon.
Q: The “Waiting for 5 seconds...” message and the “Provider is connected” message get mixed up when displayed in the console.
A: This is perfectly normal and actually caused by the EMA background thread that prints the “Provider is connected” message at the same time the main application thread prints the “Waiting for 30 seconds...” message. This can be fixed either by choosing a mono threaded application model (see the Message Processing - dispatch section of the Requesting MarketPrice data EMA Consumer tutorial) or by printing these messages atomically (use critical sections or a single cout << call to print the whole message).