Getting Started With Portico C++

Introduction
The C++ interface provided by Portico is currently available and tested on Windows, Linux and Mac OS X. It is included in every version of the Portico distribution, with the appropriate artefacts in the standard locations depending on the platform you are targeting.

This article will give you just the bare essentials required to get a federate up and running with Portico C++. If you need to know how to download and install Portico see the Installing Portico guide. Please note that this is not a guide on how to use the HLA. We assume that you already have some HLA experience and are just wanting to get started with Portico.

Portico ships with some more comprehensive example federates. You can find out about them in the Example Federates Using Portico guide.

Writing Federates For Portico
Writing federates for Portico is the same as writing federates for DMSO RTI-NG. In fact, on Windows, Portico is binary drop-in compatible with RTI-NGv6. Any federates you have written and compiled for NGv6 can be run on Portico just by changing some environment variables! (this is discussed later on in this document).

So, with that out of the way, let's look at some basic code that creates, joins, resigns from and destroys a federation. This code provides all the necessary details required to get up and running with Portico C++. Beyond what is provided below, it is just a matter of making use of the standard interfaces and types.

Sample Code: main.cpp
This class contains the main logic driving out simple simulation:

 // main.cpp
 * 1) include
 * 2) include "RTI.hh"
 * 3) include "MyFedAmb.h"

using namespace std;

int main( int argc, char *argv[] ) {   // 1. create the RTIambassador that we are going to work with RTI::RTIambassador* rtiamb = 0; rtiamb = new RTI::RTIambassador;

// 2. create the federation execution rtiamb->createFederationExecution( "exampleFederation", "testfom.fed" ); cout << "Created federation" << endl;

// 3. join the federation execution RTI::FederateAmbassador* fedamb = new MyFedAmb; rtiamb->joinFederationExecution( "myFederate", "exampleFederation", fedamb ); cout << "Joined federation" << endl;

// 4. resign from the federation execution rtiamb->resignFederationExecution( RTI::DELETE_OBJECTS_AND_RELEASE_ATTRIBUTES ); cout << "Resigned from federation" << endl;

// 5. destroy the federation execution rtiamb->destroyFederationExecution( "exampleFederation" ); cout << "Destroyed federation" << endl;

// 6. do some cleanup and exit delete rtiamb; return 0; }

For anyone who has worked with the HLA in C++ before, this is pretty straight forward stuff

Sample Code MyFedAmb
As we are not doing anything in our federate ambassador, there isn't really much to the code:

 // MyFedAmb.h
 * 1) ifndef MyFedAmb_h
 * 2) define MyFedAmb_h


 * 1) include 
 * 2) include 

class MyFedAmb : public NullFederateAmbassador {	public: MyFedAmb; virtual ~MyFedAmb throw( RTI::FederateInternalError ); };


 * 1) endif

 // MyFedAmb.cpp
 * 1) include "MyFedAmb.h"

MyFedAmb::MyFedAmb { }

MyFedAmb::~MyFedAmb throw( RTI::FederateInternalError ) { }

Compiling Federates with Portico C++
Now that we've written our example federate, it's time to compile and run it. How exactly you go about compiling your C++ code is platform dependent. For each platform, there are a number of locations that contain the artefacts you need.

Windows

 * All the DLL files reside in
 * All the lib files reside in
 * All the header files reside in

On Windows (using VC6) you may have a compile command that looks like this:

cl /I%RTI_HOME%\include\ng6 /DRTI_USES_STD_FSTREAM /GX main.cpp ExampleCPPFederate.cpp ExampleFedAmb.cpp %RTI_HOME%\lib\libRTI-NG.lib %RTI_HOME%\lib\libFedTime.lib

Linux

 * All the .so libraries reside in
 * All the header files reside in

On Linux, you may have a compile command that looks like this:

g++ -O2 -fPIC -I$RTI_HOME/include/ng6 \ -DRTI_USES_STD_FSTREAM \ -lRTI-NG -L$RTI_HOME/lib \ MyFedAmb.cpp main.cpp -o myFederate

If you have a problem linking because GCC can't find libjvm, you will need to add  to you LD_LIBRARY_PATH (this is also a runtime requirement).

Mac OS X

 * The dylib and jnilib (symlink) reside in
 * All the header files reside in

On Mac OS X, you may have a compile command that looks like this:

g++ -O2 -fPIC -I$RTI_HOME/include/ng6 \ -DRTI_USES_STD_FSTREAM \ -lRTI-NG -L$RTI_HOME/lib \ MyFedAmb.cpp main.cpp -o myFederate

Running Federates with Portico C++
Once you have compiled your federate, there are only a couple more requirements that are needed before you can successfully execute it. You will need to set up some additional environment variables to make sure that all the requirements can be located at runtime.

As the Portico C++ interface is based on JNI and acts as a wrapper around the existing Java interface, you will need to have a Java Runtime Environment (JRE) installed, and to add an extra entry to your path.

The required environment variables (and their settings) are outlined below. MUST point to the directory where Portico is installed.

Windows
To execute federates on windows, you will need to have:


 * Set the  environment variable to point at where you installed Portico
 * Set the  environment variable to point at where you installed Java**
 * The DLL files in  should be on the
 * The directory containing  should also be on your path. This is typically in  **

 ** NOTE: If you used the standalone installer, it came with a a JRE. In this case, the jvm.dll can be located at  rather than.

For example, you might have a series of commands that looks like this:

C:\example> set RTI_HOME=C:\Program Files\portico\portico-1.0 C:\example> set JAVA_HOME=%RTI_HOME%\jre C:\example> set PATH=%RTI_HOME%\bin;%JAVA_HOME%\bin\client;%PATH% C:\example> test.exe Created federation Joined federation Resigned from federation Destroyed federation

Linux

 * Set the  environment variable to point at where you installed Portico
 * Set the  environment variable to point at where you installed Java
 * The directory containing the  and   files must be on  :
 * On Intel computers with the Sun JDK (not JRE) installed, this is:
 * On AMD64 computers with the Sun JDK (not JRE) installed, this is:

You don't have to edit the system-wide environment to add these entries, you just have to be sure they are part of the environment when executing your program. For example, you could write a shell script that extends the appropriate environment variables.

You might have a command that looks something like this:

[tim@zapp example]$ export RTI_HOME=/path/to/portico/install [tim@zapp example]$ export JAVA_HOME=/path/to/jdk/install [tim@zapp example]$ export LD_LIBRARY_PATH=$RTI_HOME/lib:$JAVA_HOME/jre/lib/i386/client [tim@zapp example]$ ./test Created federation Joined federation Resigned from federation Destroyed federation

Mac OS X

 * Set the  environment variable to point at where you installed Portico
 * The dylib and jnilib files must be on the

You don't have to edit the system-wide environment to add these entries, you just have to be sure they are part of the environment when executing your program. For example, you could write a shell script that extends the appropriate environment variables.

As an example, you could issue the following command line if you were on an Apple Mac to run a federate (where test was the executable):

[tim@zapp example]$ DYLD_LIBRARY_PATH="$RTI_HOME/lib" ./test Created federation Joined federation Resigned from federation Destroyed federation

Where Next?
From this point on, you should be able to make use of standard the standard HLA interfaces and types to get the functionality you require. Larger example federates are shipped with Portico, for more information in them, see Example Federates Using Portico.

If you need more help regarding Portico, see Support.