EMA NI Provider - Connecting to the ADH

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 - A barebones EMA NIP application shell 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, we will see how to use EMA to connect a NI Provider application to the LSEG Real-Time Distribution System. We will also describe the multiple actions EMA executes under the hood to simplify programmers’ life. Finally, we will teach you how to properly disconnect your application from the LSEG Real-Time Distribution System.

To this aim we will go through the following sections:

Introduction
Connect to the ADH
Understanding what happens under the hood
Disconnect from the ADH
The main workflow
Build and run the application

Introduction

*Non Interactive Provider Point to Point connection to the ADH*

Non-Interactive Providers publish information that is cached and re-distributed by the LSEG Real-Time Distribution System. This enables the implementation of very simple provider applications that do not have to go through the hassle of handling requests from consuming applications. NI Providers just publish the data they have and the LSEG Real-Time Distribution System does all the hard work: catching the data, managing the interactions with the consumer applications, and distributing the requested data.

In this context, the general process of a NI Provider is the following:

Establish network communication with the LSEG Real-Time Distribution System.
Perform the login process.
Acquire field dictionaries
Note: This step is optional and must be implemented by the provider application if it actually needs field dictionaries - See the Publishing our first Market Price tutorial for more.
Provide the source directory information.
Provide content.
Log out and shut down.

In this tutorial, we will see a very simple way to implement a NI Provider that performs steps 1, 2, 3, and 6 with very few EMA calls.

Connect to the ADH

The very first step a NI Provider must perform is to connect to the LSEG Real-Time Distribution System, or more precisely to the ADH (Advanced Data Hub) that is the component that provider applications are connected to. As shown in the diagram above, the ADH is also in charge of caching the data published by NI Providers. This connection can be done either via a point-to-point TCP connection or via a multicast connection. In this tutorial, we will demonstrate how to use the default connection mode, which is the TCP connection.

The ADH is a network component installed in your corporate area network. In order to connect to this ADH, you need its IP address, a port number, and a user name your application will use to perform the login process just after the connection. If you do not have this information, it can usually be provided by the administration team of your company.

The simplest way to connect your EMA NI Provider to the ADH is to instantiate an OmmProvider object with an OmmNiProviderConfig object that holds the ADH IP address, the port number, and the user name.

This is what we have done in the following connect() method that we added to the NIProvider class of this tutorial.

    	
            void NiProvider::connect() 
{
 
    // Exit the method if already connected
    if (_provider != 0)
        return;
 
    const char * host = "YOUR_ADH_IP_ADDRESS:14003";
    const char * userName = "YOUR_PROVIDER_USER_NAME";
 
    cout << "  Connecting Provider to ADH " << host << " as " << userName << endl;
 
    // Connect to the infrastructure using hardcoded parameters
    _provider = new OmmProvider(
                        OmmNiProviderConfig()
                            .host(host)
                            .username(userName));
}

As you can see, the ADH IP address, the port number, and the user name are hardcoded. This is something we will improve on in the next tutorials. But, for the sake of simplicity, we keep them hardcoded for now. Obviously, before you build and run this tutorial you will have to change the tutorial source code with your own ADH IP, port number, and user name. Let us say your ADH IP is 10.2.43.49 and your provider user name is nip-user, then the host and userName variables should be set this way:

    	
             const char * host = "10.2.43.49:14003"; 
const char * userName = "nip-user";

Note: The ADH IP address is followed by a colon and the port number the provider should connect to. In this example, the port number is set to 14003, which is the default port number for Non-Interactive Providers. Unless told otherwise by your LSEG Real-Time Distribution System Administrator, this is the port number you should use.

Once the OmmProvider object is created with these parameters, the EMA library connects to the ADH and logs in using the user name you provided. If the connection and login are successful, the NI Provider application can eventually publish data for the consuming applications. We will see how to publish data in the next tutorials.

The OmmProvider object is preserved in the _provider class member for later use.

Understanding what happens under the hood

Within the introduction, we explained the general process of a NI Provider, which is:

Establish network communication with the LSEG Real-Time Distribution System.
Perform the login process.
Provide the source directory information.
Acquire field dictionaries
Note: This step is optional and must be implemented by the provider application if it actually needs field dictionaries - See the Publishing our first Market Price tutorial for more.
Provide content.
Log out and shut down.

The first 3 steps of this process are actually executed under the hood by the EMA library when you create the OmmProvider object. Steps 1 and 2 are more obvious as we provided the ADH IP address, port number, and login user name when creating the OmmProvider object. This is less obvious for step 3 because we do not provide any source directory information such as the service name, or any RDM models supported by our Ni Provider application. Instead, EMA provides default settings for this information on behalf of the user. For example, even if our NI Provider application does not provide any source directory information, it declares a service named NI_PUB, as you will see when we will run and test our application in the Build and run the application section.

Disconnect from the ADH

In order to logout and disconnect from the ADH, you just have to delete the OmmProvider object created at the time of the connection. This is what we implemented in the disconnect() method that we added to the NiProvider class.

    	
            void NiProvider::disconnect() 
{ 
   // Exit the method if already disconnected 
   if (_provider == 0) 
      return;
 
 
   cout << " Disconnecting..." << endl; 
 
   delete _provider; 
   _provider = 0; cout << " Provider disconnected" << endl; 
}

The main workflow

The main workflow leverages these two new connect() and disconnect() methods to implement the following:

It creates a NiProvider,
It connects the provider to the infrastructure and waits for 60 seconds so that you have time to verify that the NI_PUB service goes up.
Then, it disconnects, it waits for 10 seconds and exits the application.

    	
            int main(int argc, char* argv[]) 
{ 
   . . . 
   NiProvider provider; 
   provider.connect(); 
   waitFor(60); 
   provider.disconnect(); 
   waitFor(10);
   . . . 
}

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 2 - Connecting to the ADH                    |

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

  Provider created

  Connecting Provider to ADH 10.2.43.49:14003 as nip-user

  Waiting for 60 seconds...

  Disconnecting...

  Waiting for 10 seconds...

  Exiting the application

Press any key to continue . . .

During the 60 seconds wait, open a consuming application that displays the services available on the infrastructure. After a short while, the NI_PUB service should go up.

Note: As we didn’t indicate which service our provider application should serve, the EMA library used its hardcoded default service name NI_PUB.

After the 60 seconds wait, the NI_PUB service should go down.
Press a key to close the console when you are prompted to.

Troubleshooting

Q: When I build the tutorial project, I get errors 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 is up and that you properly set the hardcoded host variable of the NiProvider::connect() method.

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.

Download tutorial source code

Click here to download