Elektron SDK - C/C++

API Family: Elektron

EMA Quick Start - Connecting to Elektron Real Time in Cloud

Last Update April 2019
Environment Windows, Linux
Compiler C++, Cmake
Prerequisite

Setup your build environment as outlined in the ESDK Build System instructions OR access to Amazon EC2 instance based on the Refinitiv AMI

ERT in Cloud credentials i.e. Machine ID (username) and Password

The goal of this Quick Start tutorial is to guide you through initial steps required to execute an Elektron Message API (EMA) C++ example application in order to consume some data from Elektron RealTime (ERT in Cloud) services.

EMA is a sub-component of the ESDK (Elektron SDK) which includes several examples to demonstrate various functionalities of EMA.  Below we will invoke one of these ERT in Cloud specific examples, using your credentials, to request streaming market data content from ERT in Cloud.

The tutorial will cover both Linux and Windows environments as well as notes on how to run the example inside a Refinitiv AMI based Amazon EC2 instance.

Note for Amazon EC2 instance users

If you are using an Amazon EC2 instance (based on the Refinitiv AMI), this already contains ready built examples - so you can skip the next few steps and jump straight to Running the Example

Build and run an ERT in Cloud example

As per the Prerequisite, you should have worked through the ESDK Build System section which covers Downloading and Building the makefiles / solution files.

All EMA examples are in Cpp-C/Ema/Examples/Training subdirectory. The examples are provided for Consumers and Providers and are organized into different directories in order of increasing complexity. The Readme.txt file in each directory explains what that example is supposed to do.

Compile the sample

If you have not already compiled the examples, we will compile the simplest ERT in Cloud consumer example - 113__MarketPrice__SessionManagement . This relies on the EMA configuration file to specify a cloud location of a service provider. The service provider returns endpoint(s) to which the EMA connects, and sends Market Price request for an instrument. The output from this sample is dumped to standard out on the console.

Following is the path to relevant directories:

Paths
SDK Source Code  <ESDK root>\Cpp-C\Ema\Examples\Training\Consumer\100_Series\113__MarketPrice__SessionManagement
Configuration File  <ESDK root>\Cpp-C\Ema\Examples\Training\Consumer\100_Series\113__MarketPrice__SessionManagement\EmaConfig.xml
Generated project file   <ESDK root>\SOLUTION_FILES\Cpp-C\Ema\Examples\Training\Consumer\100_Series\113__MarketPrice__SessionManagement 
Output Binary  <ESDK root>\Cpp-C\Ema\Executables\ *
Libcurl library  <ESDK root>\installdb

To compile and build this example, navigate to directory SOLUTION_FILES\Cpp-C\Ema\Examples\Training\Consumer\100_Series\113__MarketPrice__SessionManagement and open & build the Cons113.vcxproj in the version of Visual Studio that you specified during the ESDK Build stage.

For Linux, run make in this directory.

The binary output will be in a sub directory of the  Cpp-C\Ema\Executables\ directory - the exact sub directory name location will vary depending on your OS, compiler and build type etc.

Libcurl Library files

The ERT in Cloud example has a dependency on the Libcurl library - therefore you will need to ensure the example is able to load the relevant library file as follows:

For Linux

Add the relevant subdirectory (as determined by your OS and build type) to LD_LIBRARY_PATH e.g. for RHEL Optimized build, it could be something like:

export LD_LIBRARY_PATH=<ESDK root>/installdb/RHEL6_64_GCC444/Optimized/lib64

The exact directory path will be determined by where you have unpacked the SDK, your OS and build type.

For Windows

Copy the library files to the relevant Executables subdirectory e.g. for a Visual Studio 2017 Release build, it could be something like:

copy <ESDK root>\installdb\WIN_64_VS150\bin\*.*  <ESDK root>\install\Cpp-C\Ema\Executables\WIN_64_VS150\Release_MD

The exact directory paths will be determined by where you have unpacked the SDK, your Visual Studio version and build type . 

ERT in Cloud Configuration

The SDK package includes a configuration file with the default config required to connect to ERT in Cloud - EmaConfig.xml in the source code folder - as noted in the Paths table above. 

Copy the  Cpp-C\Ema\Examples\Training\100_Series\113__MarketPrice__SessionManagement\EmaConfig.xml  file to relevant sub directory of  Cpp-C\Ema\Executables\.

ERT in Cloud user credentials

In order to execute this step, you need to have a valid Username and Password for ERT in Cloud. When you subscribed to ERT in Cloud, you should have received a Welcome Email with your 'Machine ID' (i.e. user name) and a link to activate your account & set your password. If you have not already done so, activate your account and set your password.

If you do not have that email please contact your Refinitiv account team, or if you are not a client please click Contact Us page if you would like to try our Elektron Real Time in Cloud service.

The mininum required command line parameters for the 113__MarketPrice__SessionManagement example are as follows:

  • Specify your user name (Machine ID)  with the --username  parameter
  • and the password you previously set with the  --password parameter 

The application subscribes to the  'IBM.N'  RIC code from ERT in Cloud by default. You can change this to an alternative RIC by modifying the main() method call to the registerClient() function. You can find the RIC Code of your interested instrument via the RIC Search page

Running the example

You can run the 113__MarketPrice__SessionManagement example with the following command from the relevant directory for your environment and build type

Windows

> cd <ESDK root>\Cpp-C\Ema\Executables\<build folder>
> Cons113 -username <Username/Machine ID> -password <Password>

Linux

$ cd <ESDK root>/Cpp-C/Ema/Executables/<build folder>
$./Cons113 -username <Username/Machine ID> -password <Password>

AmazonEC2

$ cd /home/ec2-user/Elektron-SDK/Cpp-C/Ema/Consumer113
$  ./runConsumer113.sh -username <username> -password <password>

Upon execution, you will be presented with a ChannelUp event, followed by some Market Price data in the form of a 'RefreshMsg' - for example 'IBM.N' from the service 'ELEKTRON_DD':

>./Cons113 --username <Username/Machine ID> --password <Password>

loggerMsg
    TimeStamp: 12:25:22.780
    ClientName: ChannelCallbackClient
    Severity: Success
    Text:    Received ChannelUp event on channel Channel_3
	Instance Name Consumer_3_1
	Connected component version: ads3.2.1.L1.linux.tis.rrg 64-bit
loggerMsgEnd

RefreshMsg
    streamId="5"
    domain="MarketPrice Domain"
    Solicited
    RefreshComplete
    ClearCache
    state="Open / Ok / None / '*All is well'"
    itemGroup="00 57"
    permissionData="03 01 01 62 C0"
    qos="RealTime/JustInTimeConflated"
    seqNum="29584"
    name="IBM.N"
    nameType="1"
    serviceId="257"
    serviceName="ELEKTRON_DD"
    Payload dataType="FieldList"
        FieldList FieldListNum="79" DictionaryId="1"
            FieldEntry fid="1" name="PROD_PERM" dataType="UInt" value="62"
            FieldEntry fid="2" name="RDNDISPLAY" dataType="UInt" value="64"
            FieldEntry fid="3" name="DSPLY_NAME" dataType="Rmtes" value="INTL BUS MACHINE"
            FieldEntry fid="4" name="RDN_EXCHID" dataType="Enum" value="2"
            FieldEntry fid="6" name="TRDPRC_1" dataType="Real" value="(blank data)"
            FieldEntry fid="7" name="TRDPRC_2" dataType="Real" value="(blank data)"
            FieldEntry fid="8" name="TRDPRC_3" dataType="Real" value="(blank data)"
            FieldEntry fid="9" name="TRDPRC_4" dataType="Real" value="(blank data)"
            FieldEntry fid="10" name="TRDPRC_5" dataType="Real" value="(blank data)"
...
...
            FieldEntry fid="32482" name="ELG_ACVOL" dataType="UInt" value="(blank data)"
            FieldEntry fid="32560" name="ELG_TNOV" dataType="Real" value="(blank data)"
            FieldEntry fid="32582" name="ODDTRN_UNS" dataType="Real" value="(blank data)"
            FieldEntry fid="32741" name="TRNOVR_UNS" dataType="Real" value="(blank data)"
            FieldEntry fid="32743" name="ACVOL_UNS" dataType="UInt" value="(blank data)"
        FieldListEnd

    PayloadEnd
RefreshMsgEnd

The RefreshMsg or initial image contains all fields (the output above is truncated) for the requested instrument representing the latest up-to-date market values. Following this image, you will begin to see UpdateMsgs or realtime updates reflecting changes in the market. 

You can (Ctrl+C) to exit the application at any time.

Troubleshooting

Q: How can I have Elektron Data Platform username and password

A: Please contact your Refinitiv Account Manager or Technical Relationship Manager to help you to access EDP account and services.

Q: My organisation requires the use of a Proxy server in order to connect to external data sources

A: The Cons113 example takes a set of optional Proxy related command line parameters - please consult the ReadMe.txt file in the source code folder.

Next Steps

Once you have successfully completed the steps above, you can further your learning by following the series of EMA tutorials.  

Amazon Cloud

If you plan to run your EMA C++ application within the Amazon Cloud, you can refer to the Setting Up an Amazon EC2 instance article for details. Once you have setup the EC2 instance, based on the Refinitiv AMI, you can find script files to run the above example within the Elektron-SDK sub-folder of the /home/ec2-user directory.

References

For further details, please check out the following resources:

For any question related to this quick start guide or Elektron Real Time in Cloud, please use the Developer Community Q&A Forum.