3. Usage

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

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

3.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 Section 3.1.2.

Table 3.1 describes the command-line parameters.

3.1.2. Stopping Routing Service

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

3.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 3.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 Specifies the path to the license file, required for license-managed distributions.
-listConfig Prints the available configurations and exits.
-maxObjectsPerThread <int> Maximum number of thread-specific objects that can be created.
Default: 2048
-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 <int> Controls what type of messages are logged:

0. Silent
1. Exceptions (Connext DDS and Routing Service)
2. Warnings (Routing Service)
3. Warnings (Connext DDS)
4. Local (Routing Service)
5. Remote (Routing Service)
6. Activity (Routing Service) and Local (Connext DDS)

Each verbosity level, n, includes all the verbosity levels smaller than n.
Default: 1 (Exceptions)
-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 Section 4 for the set of XML elements that can be overridden with command-line parameters.

3.2. Routing Service Library

Routing Service can be deployed as a library linked into your application on selected architectures (see Section 13). 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.

If you are using the C API, see the example in <path to examples>/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.

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