.. include:: vars.rst

.. _section-examples:

**************************
Example Applications
**************************

|TSS| ships with example applications that run with either
|CONNEXT| *Professional* or |CONNEXT_MICRO|. They demonstrate how to use the |TSS|
libraries with an application that uses a separate library to provide all |TSS|
plugins.

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

The examples demonstrate how a TSS integrator can package additional
functionality (plus the |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_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.

Prerequisites
=============
#. Build the |TSS| libraries for the target architecture. Follow
   the steps in the :ref:`section-build` section.
#. ``RTITSSARCH`` environment variable is set to the name of the
   target architecture (e.g., x64Linux4gcc7.3.0 or x64Linux4gcc7.3.0FACE_GP).
#. If running with |CONNEXT| *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| *Professional* installation.
   If the architecture |CONNEXT| *Professional* was built for differs from
   ``RTITSSARCH``, ``NDDSARCH`` must be set to the |CONNEXT| *Professional*
   architecture.
#. If running with |CONNEXT| *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| *Micro* installation.
   If the architecture |CONNEXT| *Micro* was built for differs from
   ``RTITSSARCH``, ``RTIMEARCH`` must be set to the |CONNEXT| *Micro*
   architecture.
#. ``RTITSSHOME`` environment variable points to the location of the |TSS|
   installation.
#. ``JREHOME`` environment variable points to the location of the JRE included with |CONNEXT| *Professional* or *Micro*.
#. `CMake <https://cmake.org>`_ is installed.

.. _label-example_hello_goodbye:

Building and Running the examples
=================================

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


Further Modifications
=====================

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| *Professional*.


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.

Troubleshooting
===============
This section has tips for working around some common issues.

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

.. code-block:: none

  <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.

.. code-block:: none

  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
:ref:`API Reference <section-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``:

.. code-block:: C++

  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;