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:

How to Start Routing Service (Starting Routing Service).
How to Stop Routing Service (Stopping Routing Service).
Routing Service Command-line Parameters (Routing Service Command-Line Parameters).

7.1.1. Starting Routing Service

To start Routing Service with a default configuration, enter:

$ NDDSHOME/bin/rtiroutingservice

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

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 */
    ...
}

7.3. Operating System Daemon

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