.. include:: vars.rst

.. _section-usage:

Usage
*****

This chapter explains how to run |RS| either from the distributed command-line
executable or from a library.

.. _section-usage-executable:

Command-Line Executable
=======================

|RS| runs as a separate application. The script to run the executable is in
``<NDDSHOME>/bin``.

.. code-block:: bash

    rtiroutingservice [options]

In this section we will see:

- How to Start |RS| (:ref:`section-starting-routing-service`).
- How to Stop |RS| (:ref:`section-stopping-routing-service`).
- |RS| Command-line Parameters (:ref:`section-routing-service-command-line-parameters`).

.. _section-starting-routing-service:

Starting Routing Service
------------------------

To start |RS| with a default configuration, enter:

.. tabs::

    .. group-tab:: Linux/macOS
    
         .. code-block::  console

            $ NDDSHOME/bin/rtiroutingservice

    .. group-tab:: Windows

         .. code-block:: doscon

            > %NDDSHOME%\bin\rtiroutingservice


This command will run |RS| indefinitely until you
stop it. See :ref:`section-stopping-routing-service`.

:numref:`TableCommandLineParameters` describes the command-line parameters.

.. note::

   To run |RS| on a *target* system (not your host development platform), 
   you must first select the target architecture. To do so, either: 
  
   * Set the environment variable ``CONNEXTDDS_ARCH`` to the name of the 
     target architecture. (Do this for each command shell you will be using.) 
  
   * Or set the variable ``connextdds_architecture`` in the file 
     ``rticommon_config.[sh/bat]`` to the name of the target architecture. 
     (The file is ``resource/scripts/rticommon_config.sh`` on Linux or 
     macOS systems, ``resource/scripts/rticommon_config.bat`` on Windows 
     systems.) If the ``CONNEXTDDS_ARCH`` environment variable is set, the 
     architecture in this file will be ignored.

.. _section-stopping-routing-service:

Stopping Routing Service
--------------------------------
To stop |RS|, press Ctrl-c. |RS|
will perform a clean shutdown.

.. _section-routing-service-command-line-parameters:

Routing Service Command-Line Parameters
-----------------------------------------------
The following table describes all the command-line parameters available in
|RS|. To list the available commands, run
``rtiroutingservice -h``.


.. list-table:: Routing Service Command-Line Parameters
    :name: TableCommandLineParameters
    :widths: 38 62
    :header-rows: 1
    :class: longtable

    * - Parameter
      - Description
    * - -appName <string>
      - Assigns a name to the execution of the Routing Service. |br|
        Remote commands and status information will refer to the instances using
        this name. |br|
        In addition, the names of |DPs| created by the service will be based on
        this name. |br|
        **Default:** empty string (uses configuration name). |br|
    * - -cfgFile <string>
      - Semicolon-separated list of configuration file paths. |br|
        **Default:** unspecified
    * - -cfgName <string>
      - Specifies the name of the |RS| configuration to be loaded. |br|
        It must match a |SERVICE_TAG| tag in the configuration
        file. |br|
        **Default:** rti.routingservice.builtin.config.default.
    * - -convertLegacyXml <string>
      - Converts the legacy XML specified with ``-cfgFile`` and produces the
        result in the specified output path. |br|
        If no output path is provided, the converted file will be in the same
        path than -cfgFile with the suffix ``converted``.
    * - -domainIdBase <int>
      - Sets the base domain ID. |br|
        This value is added to the domain IDs for all the |DR|'s |DPs| in the
        configuration file. |br|
        For example, if you set -domainIdBase to 50 and use domain IDs 0 and 1
        in the configuration file, then the Routing Service will use domains
        50 and 51.  |br|
        **Default:** 0
    * - -D<name>=<value>
      - Defines a variable that can be used as an alternate replacement for
        XML environment variables, specified in the form $(VAR_NAME). |br|
        Note that definitions in the environment take precedence over these
        definitions.
    * - -heapSnapshotDir <dir>
      - Specifies the output directory where the heap monitoring snapshots are dumped. |br|
        The filename format is RTI_heap_<appName>_<processId>_<index>.
        Used only if heap monitoring is enabled. |br|
        **Default**: current working directory
    * - -heapSnapshotPeriod <sec>
      - Specifies the period at which heap monitoring snapshots are dumped. For example, |RS|
        will generate a heap snapshot every <sec>. Enables heap monitoring if > 0. |br|
        **Default**: 0 (disabled)
    * - -help
      - Prints this help and exits.
    * - -identifyExecution
      - Appends the host name and process ID to the service name provided with
        the -appName option. This option helps ensure unique names for remote
        administration and monitoring. |br|
        For example: MyRoutingService_myhost_20024 |br|
        **Default:** false
    * - -ignoreXsdValidation
      - Loads the configuration even if the XSD validation fails.
    * - -licenseFile <path>
      - Specifies the path to the license file, required for license-managed
        distributions. See :ref:`section-Common-HowToUseLicenseFile-RTIServices`.
    * - -listConfig
      - Prints the available configurations and exits.
    * - -logFile <file>
      - Redirects logging to the specified file.
    * - -logFormat <string>
      - A mask to configure the format of the log messages for both the service 
        and DDS.

          * ``DEFAULT`` - Print message, method name, log level, 
            activity context, and logging category
          * ``VERBOSE`` - Print ``DEFAULT`` information, plus the following: module, thread ID, 
            and message location (and spread the message over two lines)
          * ``TIMESTAMPED`` - Print ``VERBOSE`` information, timestamped
          * ``MINIMAL`` - Print only message number and message location
          * ``MAXIMAL`` - Print all available fields

    * - -maxObjectsPerThread <int>
      - Maximum number of thread-specific objects that can be created. |br|
        **Default:** Same as the Connext DDS default for max_objects_per_thread
    * - -noAutoEnable
      - Starts Routing Service in a disabled state. |br|
        Use this option if you plan to enable the service remotely. |br|
        **Overrides:** This option overrides the <routing_service> tag's
        "enabled" attribute in the configuration file. |br|
        **Default:** false
    * - -pluginSearchPath
      - <path> Specifies a directory where plug-in libraries are located. |br|
        **Default:** current working directory
    * - -remoteAdministrationDomainId <int>
      - Enables remote administration and sets the domain ID for remote
        communication. |br|
        **Overrides:** This option overrides the <administration> tag's
        "enabled" attribute and <administration>/<domain_id> in the
        configuration file. |br|
        **Default:** unspecified
    * - -remoteMonitoringDomainId <int>
      - Enables remote monitoring and sets the domain ID for status publication. |br|
        **Overrides:** This option overrides <monitoring>/<enabled> and
        <monitoring>/<domain_id> in the configuration file. |br|
        **Default:** unspecified
    * - -skipDefaultFiles
      - Skips attempting to load the default configuration files |br|
        **Default:** false
    * - -stopAfter <int>
      - Number of seconds the |RS| runs before it stops. |br|
        **Default:** (infinite).
    * - -verbosity <service_level>[:<dds_level>]
      - Controls what type of messages are logged. |br|
        <service_level> is the verbosity level for the service logs and
        <dds_level> is the verbosity level for the DDS logs. Both can take any
        of the following values:

            - ``SILENT``
            - ``ERROR``
            - ``WARN``
            - ``LOCAL``
            - ``REMOTE``
            - ``ALL``

        **Default:** ``ERROR:ERROR``
    * - -version
      - Prints the *Routing Service* version number and exits.

All the command-line parameters are optional; if specified, they override
the values of their corresponding settings in the loaded XML configuration.
See :ref:`section-configuration` for the set of XML elements that can be
overridden with command-line parameters.


.. _section-routing-service-library:

Routing Service Library
=======================

|RS| can be deployed as a library linked into your application on selected
architectures (see :ref:`section-release-notes`). This allows you to create,
configure, and start |RS| instances from your application.

To build your application, add the dependency with the |RS| library under
``<NDDSHOME>/lib/<ARCHITECTURE>``, where ``<ARCHITECTURE>`` is a valid and
installed target architecture.


Example
-------

.. tabs::

    .. code-tab:: c

        struct RTI_RoutingServiceProperty property =
                RTI_RoutingServiceProperty_INITIALIZER;
        struct RTI_RoutingService * service = NULL;

        /* initialize property */
        property.cfg_file     = "my_routing_service_cfg.xml";
        property.service_name = "my_routing_service";
        ...

        service = RTI_RoutingService_new(&property);
        if(service == NULL) {
            /* log error */
            ...
        }

        if(!RTI_RoutingService_start(service)) {
            /* log error */
            ...
        }

        while(keep_running) {
            sleep();
            ...
        }
        ...

        RTI_RoutingService_delete(service);

    .. code-tab:: c++

        using namespace rti::routing;

        ServiceProperty property;
        uint32_t running_seconds = 60;
        property.cfg_file("my_routing_service_cfg.xml");
        property.service_name("my_routing_service");
        try {
            Service service(property);
            service.start();
            // Wait for 'running_seconds' seconds
            std::this_thread::sleep_for(std::chrono::seconds(running_seconds));
        } catch (const std::exception &ex) {
            /* log error */
            ...
        }

        
Operating System Daemon
=======================

See generic instructions in :ref:`section-Common-Config-Deamon`.