EMA NI Provider - Publishing a Source Directory

Download tutorial source code

Click here to download
Last update Dec 2020
Compilers

Visual Studio 2015
For other compilers settings, please check out the EMA C++ Compiler Settings tutorial.
Prerequisites EMA NI Provider - Publishing our first Market Price
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 the concepts related to a provider's Source Directory and how to use EMA to publish this information.

To this aim we will go through the following sections:

Introduction

The Source Directory sometimes referred to as the Service Directory, describes the services published by Provider applications. Up to now, we relied on the default Source Directory provided by the EMA library. In this tutorial, we will teach you how to customize this information using the EMA configuration file.

More about Source Directories

The Source Directory is a Domain Model (RDM) that conveys the description of services and capabilities published by provider applications. This includes information like the service names, the domain types supported within a service, the service’s state, etc. This information must be provided to the infrastructure, just after the connection/login phase.

As explained in the Understand what happens under the hood section of the Connecting to the ADH tutorial, the EMA library automatically sends a default Source Directory if neither the provider application nor the EMA configuration file provides this information.

Note: The default Source Directory declares a single service that is named NI_PUB, which provides the following capabilities: MMT_MARKET_PRICE, MMT_MARKET_BY_ORDER, MMT_MARKET_BY_PRICE, and MMT_MARKET_MAKER.

In the previous tutorial, we kept these details hidden and relied on the default service name (NI_PUB for NI Providers). But, if you try to publish an item for another service name with the previous tutorial application, it will fail with an OmmInvalidUsageException. Using the default NI_PUB service name is perfectly fine for an example application. But in a production environment, however, you will probably want to use a service name that is meaningful regarding the instruments and the capabilities published by your application.

The good news is that you can change the Source Directory of your application by just changing the EmaConfig.xml file. Read the sections below to understand how to proceed.

Note: The Source Directory information can also be set programmatically via the OmmNiProviderConfig class. Please consult the EMA C++ Configuration Guide for details.

Source Directories description in the EmaConfig.xml file

In order to change the Source Directory information published by your provider, you must describe this directory in the EmaConfig.xml file. Then, you must associate this directory with the <NiProvider> node already defined for your application.

  • The <DirectoryGroup>
    This is the group where source directories are defined. The <DirectoryGroup> may define one or several directories that are contained in the <DirectoryList> node.
    In our case, we only have one directory (Directory_1) that will be associated with NiProvider_1.
  • The <Directory> node
    This is the node where you define the Service Directory. In the <Directory> node you must define a name and one or several services. The name will be used to associate the Service Directory with a provider. Each service is defined in a <Service> node as explained below. 
    Note: The exhaustive list of <Directory> nodes parameters is defined in the EMA C++ Configuration Guide.
  • The <Service> node
    In this node, you define one of the services published by your provider. For each service, you must define a name and the available capabilities of this service (e.g. MMT_MARKET_PRICE or MMT_MARKET_BY_ORDER). Capabilities are defined as <CapabilitiesEntry> nodes. Their values come from the RDM message model types defined in the Ema\Src\Rdm\Include\EmaRdm.h file of your RTSDK package (see the MMT_XXXX constants).

Below is the complete EmaConfig.xml file for this tutorial. In this file, we declared a single directory named Directory_1 that contains a single TEST_NI_PUB service that only provides market prices. This directory is associated with NiProvider_1 thanks to the <Directory> parameter of the <NiProvider> node:

    	
            
<?xml version="1.0" encoding="UTF-8"?>


<EmaConfig>


 


    <NiProviderGroup>


        <DefaultNiProvider value="NiProvider_1" />


        <NiProviderList>


            <NiProvider>


                <Name value="NiProvider_1" />


                <Channel value="Channel_1" />


                <Directory value="Directory_1" />


            </NiProvider>


        </NiProviderList>


    </NiProviderGroup>


 


    <ChannelGroup>


        <ChannelList>


            <Channel>


                <Name value="Channel_1" />


                <ChannelType value="ChannelType::RSSL_SOCKET" />


                <Host value="YOUR_ADH_IP_ADDRESS" />


                <Port value="14003" />


            </Channel>


        </ChannelList>


    </ChannelGroup>


 


    <DirectoryGroup>


        <DefaultDirectory value="Directory_1" />


        <DirectoryList>


            <Directory>


                <Name value="Directory_1" />


                <Service>


                    <Name value="TEST_NI_PUB" />


                    <InfoFilter>


                        <Capabilities>


                            <CapabilitiesEntry value="MMT_MARKET_PRICE" />


                        </Capabilities>


                    </InfoFilter>


                </Service>


            </Directory>


        </DirectoryList>


    </DirectoryGroup>


 


</EmaConfig>

The main workflow

Compared to the previous tutorial, we just changed the main workflow a bit so that it publishes a refresh message for the TEST_NI_PUB service instead of NI_PUB. 

    	
            
int main(int argc, char* argv[])


{


    .


    .


    .


 


        NiProvider provider;


 


        provider.connectAs("YOUR_PROVIDER_USER_NAME");


 


        waitFor(5);


 


        provider.refresh("TEST_NI_PUB", "SHARE-0");


 


        waitFor(30);


 


        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:

  1. A console application should open and display something like:
    	
            
-------------------------------------------------------------------------------


|                      Non Interactive Provider EMA Tutorial                  |


|                                                                             |


|                   Tutorial 6 - Publishing a Source Directory                |


-------------------------------------------------------------------------------


  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 60 seconds...


  Disconnecting...


  Provider is disconnected. OmmState:Open / Suspect / None / 'channel down'


  Exiting the application


Press any key to continue . . .

During the 60 seconds wait, open a LSEG Real-Time Distribution System 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.

As an example, this is a screenshot of the Eikon Quote object that we used to subscribe to TEST_NI_PUB/SHARE-0. In the Eikon configuration, the TEST_NI_PUB service has been associated with the 'T' key letter:

3. After 60 seconds, 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).