7. Usage

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

7.1. Command-Line Executable

Routing Service runs as a separate application. The script to run the executable is in <NDDSHOME>/bin.

rtiroutingservice [options]

In this section we will see:

7.1.1. Starting Routing Service

To start Routing Service with a default configuration, enter:

$ NDDSHOME/bin/rtiroutingservice

This command will run Routing Service indefinitely until you stop it. See Stopping Routing Service.

Table 7.1 describes the command-line parameters.

Note

To run Routing Service 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.

7.1.2. Stopping Routing Service

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

7.1.3. Routing Service Command-Line Parameters

The following table describes all the command-line parameters available in Routing Service. To list the available commands, run rtiroutingservice -h.

Table 7.1 Routing Service Command-Line Parameters

Parameter

Description

-appName <string>

Assigns a name to the execution of the Routing Service.
Remote commands and status information will refer to the instances using this name.
In addition, the names of DomainParticipants created by the service will be based on this name.
Default: empty string (uses configuration name).

-cfgFile <string>

Semicolon-separated list of configuration file paths.
Default: unspecified

-cfgName <string>

Specifies the name of the Routing Service configuration to be loaded.
It must match a <routing_service> tag in the configuration file.
Default: rti.routingservice.builtin.config.default.

-convertLegacyXml <string>

Converts the legacy XML specified with -cfgFile and produces the result in the specified output path.
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.
This value is added to the domain IDs for all the DataReader’s DomainParticipants in the configuration file.
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.
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).
Note that definitions in the environment take precedence over these definitions.

-heapSnapshotDir <dir>

Specifies the output directory where the heap monitoring snapshots are dumped.
The filename format is RTI_heap_<appName>_<processId>_<index>. Used only if heap monitoring is enabled.
Default: current working directory

-heapSnapshotPeriod <sec>

Specifies the period at which heap monitoring snapshots are dumped. For example, Routing Service will generate a heap snapshot every <sec>. Enables heap monitoring if > 0.
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.
For example: MyRoutingService_myhost_20024
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 How to use a License File with RTI Services.

-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.
Default: Same as the Connext DDS default for max_objects_per_thread

-noAutoEnable

Starts Routing Service in a disabled state.
Use this option if you plan to enable the service remotely.
Overrides: This option overrides the <routing_service> tag’s “enabled” attribute in the configuration file.
Default: false

-pluginSearchPath

<path> Specifies a directory where plug-in libraries are located.
Default: current working directory

-remoteAdministrationDomainId <int>

Enables remote administration and sets the domain ID for remote communication.
Overrides: This option overrides the <administration> tag’s “enabled” attribute and <administration>/<domain_id> in the configuration file.
Default: unspecified

-remoteMonitoringDomainId <int>

Enables remote monitoring and sets the domain ID for status publication.
Overrides: This option overrides <monitoring>/<enabled> and <monitoring>/<domain_id> in the configuration file.
Default: unspecified

-skipDefaultFiles

Skips attempting to load the default configuration files
Default: false

-stopAfter <int>

Number of seconds the Routing Service runs before it stops.
Default: (infinite).

-verbosity <service_level>[:<dds_level>]

Controls what type of messages are logged.
<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 Configuration for the set of XML elements that can be overridden with command-line parameters.

7.2. Routing Service Library

Routing Service can be deployed as a library linked into your application on selected architectures (see Release Notes). This allows you to create, configure, and start Routing Service instances from your application.

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

7.2.1. Example

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);

7.3. Operating System Daemon

See generic instructions in How to Run as an Operating System Daemon.