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

.. _section-record_usage:

Usage
=====

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

- How to Start *Recording Service* (:numref:`section-starting-recording-service`)
- How to Stop *Recording Service* (:numref:`section-stopping-recording-service`)
- *Recording Service* command-line parameters
  (:numref:`section-recording-service-command-line-parameters`)

.. _section-starting-recording-service:

Starting Recording Service
--------------------------

*Recording Service* 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.)


To start *Recording Service* with a default configuration, enter:

.. code-block:: bash

    rtirecordingservice

This command will run *Recording Service* indefinitely until you stop it.

You can run *Recording Service* using the command-line parameters defined below.

.. note::
    *Recording Service* is pre-loaded with a builtin configuration that has default
    settings. See :numref:`section-builtin-config-recording-service`.

.. _section-stopping-recording-service:

Stopping Recording Service
--------------------------

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

.. _section-recording-service-command-line-parameters:

Recording Service Command-Line Parameters
-----------------------------------------

The following table describes all the command-line parameters available in
*Recording Service*. To list the available parameters, run
``rtirecordingservice -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-record-config-XML-tags` for the XML elements that
can be overridden with command-line parameters.

.. list-table:: Recording Service Command-Line Parameters
    :name: RecordingServiceHelp
    :widths: 38 62
    :header-rows: 1
    :class: longtable

    * - Parameter
      - Description
    * - :litrep:`-appName <string>`
      - Application name used to identify this execution for
        remote administration and to name the *Connext DDS* participant.
    * - :litrep:`-cfgFile <string>`
      - Semicolon-separated list of configuration file paths. |br|
        **Default:** unspecified
    * - :litrep:`-cfgName`
      - Configuration name used to find a ``<recording_service>``
        matching tag in the configuration file.
    * - :litrep:`-domainIdBase <int>`
      - This value is added to the domain IDs in the ``<domain_participant>``
        tag in the configuration file. For example, if you set -domainIdBase
        to 50 and use domain IDs 0 and 1 in the configuration file, then
        *Recording Service* will use domains 50 and 51 for recording (though
        the recorded data will appear as though it was recorded in domains 0
        and 1). |br|
        **Default:** 0
    * - :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:`-heapSnapshotDir`
      - Output directory where the heap monitoring snapshots are dumped.
        The filename format is: |br|
        RTI_heap_<appName>_<processId>_<index>.log
    * - :litrep:`-heapSnapshotPeriod <sec>`
      - Period at which heap monitoring snapshots
        are dumped. Enables heap monitoring if > 0. |br|
        **Default:** 0 (disabled)
    * - :litrep:`-logFormat <format>`
      - A mask to configure the format of the log
        messages for both *Recording Service* and *Connext DDS*:

          - DEFAULT - Print message, method name,
            and activity context
          - TIMESTAMPED - Print message, method name,
            activity context, and timestamp
          - MINIMAL - Print only message number
            and method name
          - MAXIMAL - Print all available fields

        **Default:** DEFAULT
    * - :litrep:`-maxObjectsPerThread <int>`
      - Maximum number of thread-specific
        objects that can be created. |br|
        **Default**: 1024.
    * - :litrep:`-remoteAdministrationDomainId <int>`
      - Enables remote administration and
        sets the domain ID for communication. |br|
        **Default**: Remote administration is not enabled.
    * - :litrep:`-remoteMonitoringDomainId <int>`
      - Enables remote monitoring and
        sets the domain ID for status publication. |br|
        **Default**: Remote monitoring is not enabled.
    * - :litrep:`-verbosity [0-6]`
      - RTI Service verbosity
          - 0 - silent
          - 1 - exceptions (*Connext DDS* and *Recording Service*)
          - 2 - warnings (*Recording Service*)
          - 3 - information (*Recording Service*)
          - 4 - warnings (*Connext DDS* and *Recording Service*)
          - 5 - tracing (*Recording Service*)
          - 6 - tracing (*Connext DDS* and *Recording Service*)

        **Default**: 1 (exceptions)

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