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

.. _section-storageutils-tutorials:

Tutorials
=========

.. _section-storageutils-tutorials-csv:

Using the CSV storage utility plugin with Converter
----------------------------------------------------

If you have a recorded database in any of the binary CDR serialized formats, 
it is pretty difficult to analyze the recorded data without replaying it. 
While there is an option to convert the recorded database to JSON 
(see :numref:`section-builtin-config-converter`), you can also convert it to 
CSV format.

The *Converter* can convert an XCDR database to CSV format using a default 
configuration called ``sqliteToCsv``.

.. _section-storageutils-tutorials-csv-setup:

Setup
^^^^^^

We need to make sure ``rtistorageutils`` can be loaded dynamically by 
``rticonverter``, set the library search path variable as follows:

.. tabs::

    .. group-tab:: Linux

        .. code-block:: bash

            export LD_LIBRARY_PATH=$LD_LIBRARY_PATH;<NDDSHOME>/lib/<architecture>

    .. group-tab:: macOS

        .. code-block:: bash

            export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH;<NDDSHOME>/lib/<architecture>

    .. group-tab:: Windows

        .. code-block:: bash

            set PATH=%PATH%;<NDDSHOME>\lib\<architecture>

.. note::
    ``<NDDSHOME>`` is described in section :numref:`section-doc-paths`.

Execution
^^^^^^^^^^
To demonstrate the functionality we first need to record some data. Run 
|SHAPESDEMO| with the default configuration and publish some Triangles and 
Circles (using |SHAPESDEMO| is described in :numref:`section-record-getting-started-shapes`). 
Once |SHAPESDEMO| has started, run |RECS| as follows:

    .. code-block:: bash

        <NDDSHOME>/bin/rtirecordingservice

The default configuration should record data in a directory called ``cdr_recording``.

Now run *Converter* to perform the conversion of the previously generated 
database into a single text file in ``CSV`` format:

    .. code-block:: bash

        <NDDSHOME>/bin/rticonverter -cfgName sqliteToCsv

If you need to customize the behavior of this configuration, you can do so by adding user 
variables to the command, as shown:

.. code-block:: bash

        <NDDSHOME>/bin/rticonverter -cfgName sqliteToCsv -DCSV_WORKSPACE_DIR=my_custom_dir 
                -DCSV_MERGE_FILES=false -DINPUT_DIR=my_cdr_recording_dir

Wait until conversion of the entire input database is performed and ``rticonverter`` 
exits automatically. Upon successful conversion, you will find a folder in the current 
directory with the name ``csv_output``. That folder will contain a file called 
``csv_converted.csv`` containing topic data for the Triangles and Circles published 
earlier by the |SHAPESDEMO| and recorded by ``rtirecordingservice``. This can be verified by 
opening the file using an editor of your choice.