.. include:: ../../../router.1.0/srcDoc/vars.rst

.. _section-converter_usage:

Usage
=====

This section explains how to run *Converter* from a command line.
In particular, it describes:

- How to Start *Converter* (:numref:`section-starting-converter`).
- *Converter* command-line parameters (:numref:`section-converter-command-line-parameters`).

.. _section-starting-converter:

Starting Converter
------------------

*Converter* runs as a separate application. The script to run the
executable is in ``<NDDSHOME>/bin``. (See :numref:`section-doc-paths` for
the path to NDDSHOME.)

.. code-block:: bash

    rticonverter [options]


To start *Converter* with a default configuration, enter:

.. code-block:: bash

    $NDDSHOME/bin/rticonverter


.. note::
    *Converter* is pre-loaded with a builtin configuration that has default
    settings. See :numref:`section-builtin-config-converter`.

.. _section-converter-command-line-parameters:

Converter Command-Line Parameters
---------------------------------

The following table describes all the command-line parameters available in
*Converter*. To list the available parameters, run ``rticonverter -help``.

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

.. list-table:: Converter Command-Line Parameters
    :name: ConverterHelp
    :widths: 38 62
    :header-rows: 1
    :class: longtable

    * - Parameter
      - Description
    * - :litrep:`-cfgFile <string>`
      - Semicolon-separated list of configuration file paths. |br|
        **Default:** Unspecified
    * - :litrep:`-cfgName`
      - Configuration name.
        This name is used to find a matching ``<converter>``
        tag in the configuration file.
    * - :litrep:`-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.
    * - :litrep:`-help`
      - Shows this help.
    * - :litrep:`-verbosity [0-6]`
      - RTI Service verbosity
          - 0 - silent
          - 1 - exceptions (*Connext DDS* and *Converter*)
          - 2 - warnings (*Converter*)
          - 3 - information (*Converter*)
          - 4 - warnings (*Connext DDS* and *Converter*)
          - 5 - tracing (*Converter*)
          - 6 - tracing (Connext DDS* and *Converter*)

        **Default**: 1 (exceptions)

    * - :litrep:`-version`
      - Prints the program version and exits.

Working With Large Data
-----------------------

The built-in SQLite plugin implementation available in *Converter* is
prepared to handle any type size and storage format. However, when working with 
large data types and massive files (or filesets), *Converter* may take a while 
to prepare SQL statements to work with the data, resulting in a delay 
when starting the conversion process.

Because of this delay, it is recommended that you index the user data tables for 
those large topics before running *Converter* on them. Indexing can massively
improve *Converter*'s startup time for those topics. You can create the indexes 
offline, after Recording Service has finished recording all the data. Index the 
tables on the ``SampleInfo_reception_timestamp`` field. For example, imagine a 
table, ``VeryLargeTopic@0``, has been created by Recording Service; you can use 
the following index creation statement:

.. code-block:: sql

    CREATE INDEX IF NOT EXISTS [VeryLargeTopic@0_idx_rt] 
            ON [VeryLargeTopic@0] (SampleInfo_reception_timestamp)