.. 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 ``/bin``. .. code-block:: bash rtiroutingservice [options] In this section we will see: - How to Start |RS| (:numref:`section-starting-routing-service`). - How to Stop |RS| (:numref:`section-stopping-routing-service`). - |RS| Command-line Parameters (:numref:`section-routing-service-command-line-parameters`). .. _section-starting-routing-service: Starting Routing Service ------------------------ To start |RS| with a default configuration, enter: .. code-block:: bash $NDDSHOME/bin/rtiroutingservice This command will run |RS| indefinitely until you stop it. See :numref:`section-stopping-routing-service`. :numref:`TableCommandLineParameters` describes the command-line parameters. .. _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 * - :litrep:`-appName ` - 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| * - :litrep:`-cfgFile ` - Semicolon-separated list of configuration file paths. |br| **Default:** unspecified * - :litrep:`-cfgName ` - 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. * - :litrep:`-convertLegacyXml ` - 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``. * - :litrep:`-domainIdBase ` - 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 * - :litrep:`-D=` - 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. * - :litrep:`-heapSnapshotDir ` - Specifies the output directory where the heap monitoring snapshots are dumped. |br| The filename format is RTI_heap___. Used only if heap monitoring is enabled. |br| **Default**: current working directory * - :litrep:`-heapSnapshotPeriod ` - Specifies the period at which heap monitoring snapshots are dumped. For example, |RS| will generate a heap snapshot every . Enables heap monitoring if > 0. |br| **Default**: 0 (disabled) * - :litrep:`-help` - Prints this help and exits. * - :litrep:`-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 * - :litrep:`-ignoreXsdValidation` - Loads the configuration even if the XSD validation fails. * - :litrep:`-licenseFile` - Specifies the path to the license file, required for license-managed distributions. * - :litrep:`-listConfig` - Prints the available configurations and exits. * - :litrep:`-maxObjectsPerThread ` - Maximum number of thread-specific objects that can be created. |br| **Default:** 2048 * - :litrep:`-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 tag's "enabled" attribute in the configuration file. |br| **Default:** false * - :litrep:`-pluginSearchPath` - Specifies a directory where plug-in libraries are located. |br| **Default:** current working directory * - :litrep:`-remoteAdministrationDomainId ` - Enables remote administration and sets the domain ID for remote communication. |br| **Overrides:** This option overrides the tag's "enabled" attribute and / in the configuration file. |br| **Default:** unspecified * - :litrep:`-remoteMonitoringDomainId ` - Enables remote monitoring and sets the domain ID for status publication. |br| **Overrides:** This option overrides / and / in the configuration file. |br| **Default:** unspecified * - :litrep:`-skipDefaultFiles` - Skips attempting to load the default configuration files |br| **Default:** false * - :litrep:`-stopAfter ` - Number of seconds the |RS| runs before it stops. |br| **Default:** (infinite). * - :litrep:`-verbosity ` - Controls what type of messages are logged: |br| |br| 0. Silent |br| 1. Exceptions (*Connext DDS* and |RS|) |br| 2. Warnings (|RS|) |br| 3. Warnings (*Connext DDS*) |br| 4. Local (|RS|) |br| 5. Remote (|RS|) |br| 6. Activity (|RS|) and Local (*Connext DDS*) |br| |br| Each verbosity level, ``n``, includes all the verbosity levels smaller than ``n``. |br| **Default:** 1 (Exceptions) * - :litrep:`-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 :numref:`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 :numref:`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 ``/lib/``, where ```` is a valid and installed target architecture. If you are using the C API, see the example in ``/routing_service/routing_service_lib``. Example makefiles and project files for several architectures are provided. Also see the README.txt file in the ``routing_service_lib/src`` directory. Example ------- .. code-block:: 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);