.. include:: ../../../recorder.4.0/srcDoc/vars.rst

.. _section-converter_usage:

Usage
=====

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

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

.. _section-starting-converter:

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

|CONV| 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 |CONV| with a default configuration, enter:

.. code-block:: bash

    $NDDSHOME/bin/rticonverter

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

.. note::

   To run *Converter* 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.
     
.. _section-converter-command-line-parameters:

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

The following table describes all the command-line parameters available in
|CONV|. 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
    * - -cfgFile <string>
      - Semicolon-separated list of configuration file paths. |br|
        **Default:** Unspecified
    * - -cfgName
      - Configuration name.
        This name is used to find a matching ``<converter>``
        tag in the configuration file.
    * - -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.
    * - -help
      - Shows this help.
    * - -verbosity <service_level>[:<dds_level>]
      - Controls what type of messages are logged. |br|
        <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 program version and exits.

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

The built-in SQLite plugin implementation available in |CONV| is
prepared to handle any type size and storage format. However, when working with
large data types and massive files (or filesets), |CONV| 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 |CONV| on them. Indexing can massively
improve |CONV|'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)