Getting Started: Part 1

When people first start looking at OpenMAMA, they tend to begin with some very similar questions: "how do I get started?", "what can OpenMAMA really do?", "what does real data look like?". Over the past few months we've been working pretty hard on making the answers to these questions easier - updating our example apps, cleaning up the install process, and providing a sample of real world market data. Over the next few weeks I'll be presenting a series of blog posts that walk new users through the process of getting up and running with OpenMAMA, before diving a little deeper into some of our more interesting example applications.

Today though, we're just going to get started - download OpenMAMA, install it, and get some simple data flowing. The following steps detail the fastest route to getting OpenMAMA up and running, but in order to do so it does make some assumptions about your environment - mainly that you're working using Linux, and that you're working on a platform that supports RPM installations (RHEL and Centos 6). We also assume that you're using "bash" rather than a more esoteric shell. If you aren't sure you're using bash, don't know what a shell is, or don't understand the word 'esoteric', you're probably using bash, so don't worry about it.

Getting OpenMAMA

The first step is to grab the OpenMAMA RPM from the download area.

Install OpenMAMA

Once you have an appropriate OpenMAMA RPM for your system, you will need to install it. Depending on your platform you will likely issue one of two commands. For systems which support '''yum''', the appropriate command will generally be:

  sudo yum install openmama-(version/platform).rpm

For systems which use pure RPM, the command becomes:

  sudo rpm -iVh (version/platform).rpm

This will also potentially install a number of dependencies required by OpenMAMA, including libuuid, the QPID Proton messaging layer (libqpid-proton) and libevent. '''Note:''' In order to resolve a number of the dependencies, the RPM requires that Centos and Red Hat repos have access to the Fedora EPEL Repo. Check out the instructions here for help checking if it is available.

OpenMAMA Directories

At present the OpenMAMA RPM will install everything under ''/opt/openmama''. You should now be able to 'cd' into that directory and see the following directory structure:

Running OpenMAMA

Once you have OpenMAMA installed, you'll want to see it in action. For this we're going to make use of the QPID Proton middleware bridge, which comes bundled with the OpenMAMA RPM (the Proton libraries (libqpid-proton.so) should also be installed with the RPM - if they aren't check out the Proton website for more information). We've tried to ensure the sample configuration works on as many platforms as possible, so you should be able to get up and running using the following steps:

First, open two separate terminal instances, and cd into the /opt/openmama directory. In the first run the following:

  cd /opt/openmama
  source config/profile.openmama
  mamapublisherc -tport pub -m qpid

Then in the second run:

  cd /opt/openmama
  source config/profile.openmama
  mamasubscriberc -tport sub -m qpid

With a bit of luck you should see the following in your two terminals:

[damian@openmama openmama]$ mamapublisherc -tport pub -m qpid
Starting Publisher with:
topic: MAMA_TOPIC
inbound topic: MAMA_INBOUND_TOPIC
interval 0.500000
transport: pub
2013-12-19 09:56:36:
*******************************************************************
Note: This build of the MAMA API is not enforcing entitlement checks. Please see the Licensing file for details
*******************************************************************
CONNECTION ERROR connection aborted
Created inbound subscription.
Publishing message 0 to MAMA_TOPIC.
  msg=({{MdMsgStatus,2,0},{MdSeqNum,10,0},{PublisherTopic,10002,MAMA_TOPIC}}
Publishing message 1 to MAMA_TOPIC.
  msg=({{MdMsgStatus,2,0},{MdSeqNum,10,1},{PublisherTopic,10002,MAMA_TOPIC}}
Publishing message 2 to MAMA_TOPIC.
  msg=({{MdMsgStatus,2,0},{MdSeqNum,10,2},{PublisherTopic,10002,MAMA_TOPIC}}
Publishing message 3 to MAMA_TOPIC.
  msg=({{MdMsgStatus,2,0},{MdSeqNum,10,3},{PublisherTopic,10002,MAMA_TOPIC}}
Publishing message 4 to MAMA_TOPIC.
  msg=({{MdMsgStatus,2,0},{MdSeqNum,10,4},{PublisherTopic,10002,MAMA_TOPIC}}
Publishing message 5 to MAMA_TOPIC.
  msg=({{MdMsgStatus,2,0},{MdSeqNum,10,5},{PublisherTopic,10002,MAMA_TOPIC}}
Publishing message 6 to MAMA_TOPIC.
  msg=({{MdMsgStatus,2,0},{MdSeqNum,10,6},{PublisherTopic,10002,MAMA_TOPIC}}
Publishing message 7 to MAMA_TOPIC.
 msg=({{MdMsgStatus,2,0},{MdSeqNum,10,7},{PublisherTopic,10002,MAMA_TOPIC}}
Publishing message 8 to MAMA_TOPIC.
 msg=({{MdMsgStatus,2,0},{MdSeqNum,10,8},{PublisherTopic,10002,MAMA_TOPIC}}

[damian@openmama openmama]$ mamasubscriberc -m qpid -tport sub
Starting Subscriber with:
topic: MAMA_TOPIC
transport: sub
2013-12-19 09:56:38:
**************************************************************************
Note: This build of the MAMA API is not enforcing entitlement checks. Please see the Licensing file for details
**************************************************************************
mamasubscriberc: Created inbound subscription.
mamasubscriberc: Recieved msg.
  MdMsgStatus 2 I32 0 MdSeqNum 10 I32 5 PublisherTopic 10002 STRING MAMA_TOPIC
mamasubscriberc: Recieved msg.
  MdMsgStatus 2 I32 0 MdSeqNum 10 I32 6 PublisherTopic 10002 STRING MAMA_TOPIC
mamasubscriberc: Recieved msg.
  MdMsgStatus 2 I32 0 MdSeqNum 10 I32 7 PublisherTopic 10002 STRING MAMA_TOPIC
mamasubscriberc: Recieved msg.
  MdMsgStatus 2 I32 0 MdSeqNum 10 I32 8 PublisherTopic 10002 STRING MAMA_TOPIC

Explanation

Now that we've gotten some data flowing between our servers, it makes sense to understand exactly what's happening in the above example. A typical OpenMAMA environment will consist of at least two processes, the first sending messages out (the publisher) and the second receiving them (the subscriber). This distinction isn't always as clear cut, but for our purposes it will suffice. So, in each of our terminals we create one of each type of process.

Publisher

The first application we start is mamapublisherc, a simple test data publisher, into which we pass the name of the middleware bridge we wish to have loaded ('qpid' via the '-m' command line option) along with the name of the transport we wish to use ('pub' via the '-tport' command line option). The transport name is essentially an identifier for a group of related properties which MAMA then gathers (generally from the mama.properties file) and uses as the configuration for the underlying middleware.

mamapublisherc -m qpid -tport pub

The publisher in this case is a basic publisher, sending messages out at a preset interval, on a pre-determined symbol. This will continue until we terminate the application (typically with a "ctrl-c").

Subscriber

The command line for our basic subscriber is almost identical to the publisher, expect in this case we pass in a different transport. As the current QPID Proton bridge is a point-to-point implementation, the transport we choose must be complementary (so the parameters should be matching). As a result we choose the "sub" transport, giving a command line of:

mamasubscriberc -m qpid -tport sub

The subscriber in this instance is making a connection to the publisher, and registering it's interest in the same test topic as that of the publisher.

Conclusion

At this stage you'll hopefully have noticed how easy it is to get data flowing with OpenMAMA. While these examples may seem quite simple, there's actually a lot of power on display. For example, in this instance you're running on top of the open source Qpid Proton middleware, but in order to use it you don't need to know anything about how it works, nor how the data is encoded. Want to switch to the Avis middleware? Change the command line to say '-m avis'. The same is true for any number of open and commercial platforms, simply specify and alternate bridge and continue as you were. Powerful indeed...

Part two of the Quick Start series will explore this idea a little further, looking at example OpenMAMA was born around - market data messaging. Building on the setup we have running now, it will introduce the capturereplayc application, along with some of the other common OpenMAMA examples - mamalistenc and bookviewer.

Damian