8. Example Applications

Connext TSS ships with example applications that run with either Connext DDS Professional or Connext DDS Micro. They demonstrate how to use the Connext TSS libraries with an application that uses a separate library to provide all Connext TSS plugins.

The actual FACE TSS application includes only the minimum necessary code to build a FACE UoP using Connext TSS.

The examples demonstrate how a TSS integrator can package additional functionality (plus the Connext TSS plugins) into a linkable library that can be used by FACE UoP. They also show how to combine multiple connections in the same application and how to setup a callback to process received data.

Note

RTI Connext TSS supports user data types in IDL files only. To convert other FACE data model formats to IDL, contact RTI Support or your local account team for assistance.

8.1. Prerequisites

  1. Build the Connext TSS libraries for the target architecture. Follow the steps in the Build section.

  2. RTITSSARCH environment variable is set to the name of the target architecture (e.g., x64Linux4gcc7.3.0 or x64Linux4gcc7.3.0FACE_GP).

  3. If running with Connext DDS Professional, it must be installed and it must conform with the intended FACE profile. The NDDSHOME environment variable is set to the location of the Connext DDS Professional installation. If the architecture Connext DDS Professional was built for differs from RTITSSARCH, NDDSARCH must be set to the Connext DDS Professional architecture.

  4. If running with Connext DDS Micro, it must be installed and it must conform with the intended FACE profile. The RTIMEHOME environment variable is set to the location of the Connext DDS Micro installation. If the architecture Connext DDS Micro was built for differs from RTITSSARCH, RTIMEARCH must be set to the Connext DDS Micro architecture.

  5. RTITSSHOME environment variable points to the location of the Connext TSS installation.

  6. JREHOME environment variable points to the location of the JRE included with Connext DDS Professional or Micro.

  7. CMake is installed.

8.2. Building and Running the examples

Please refer to the README files located in the example directories.

8.3. Further Modifications

8.3.1. DDS QoS

In general, QoS for underlying DDS entities are configured in the generated _TSSQosSupport.cpp source files. XML profiles may also be used for Connext DDS Professional.

8.3.2. Adding Connections

Each created connection creates an underlying DDS writer and/or reader, so resource limits QoS may need to be increased for additional connections.

8.4. Troubleshooting

This section has tips for working around some common issues.

8.4.1. Function returned an error

The example applications may return an error message of the format:

<function> returned an error: <return_code>

For example, the following error message is FACE::TS::Receive_Message() returning the FACE::RETURN_CODE_TYPE with value 2.

Receive_Message returned an error: 2

The return code can be found in a header file, and the return code of each function can be found in either source or the API Reference documentation.

So for the above example, searching the headers in include/FACE reveals the FACE::RETURN_CODE_TYPE enum in include/FACE/common.hpp, where 2 maps to NOT_AVAILABLE:

typedef enum RETURN_CODE_TYPE
  {
    NO_ERROR ,
    NO_ACTION ,
    NOT_AVAILABLE ,
    ADDR_IN_USE ,
    INVALID_PARAM ,
    INVALID_CONFIG ,
    PERMISSION_DENIED ,
    INVALID_MODE ,
    TIMED_OUT ,
    MESSAGE_STALE ,
    CONNECTION_IN_PROGRESS ,
    CONNECTION_CLOSED ,
    DATA_BUFFER_TOO_SMALL
  } RETURN_CODE_TYPE;