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

.. _section-replay_usage:

Usage
=====


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

- How to Start *Replay Service* (:numref:`section-starting-replay-service`).
- How to Stop *Replay Service* (:numref:`section-stopping-replay-service`).
- *Replay Service* command-line parameters (:numref:`section-replay-service-command-line`).


.. _section-starting-replay-service:

Starting Replay Service
-----------------------

*Replay 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.)


.. code-block:: bash

    rtireplayservice [options]


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

.. code-block:: bash

    $NDDSHOME/bin/rtireplayservice

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

.. note::

    *Replay Service* is pre-loaded with a built-in configuration that has default settings.

.. _section-stopping-replay-service:

Stopping Replay Service
-----------------------

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

.. _section-replay-service-command-line:

Replay Service Command-Line Parameters
--------------------------------------

The following table describes all the command-line parameters available in
*Replay Service*. To list the available parameters, run ``rtireplayservice -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-xml-tags-for-configuring-replay-service`
for the XML elements that can be overridden with command-line parameters.


.. list-table:: Replay Service Command-Line Parameters
    :name: ReplayServiceHelp
    :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 ``<replay_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, *Replay Service* will read domains 0 and 1
        from the database, but will replay that data into domains
        50 and 51. |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 |br|
    * - :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 *Replay 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 *Replay Service*)
          - 2 - warnings (*Replay Service*)
          - 3 - information (*Replay Service*)
          - 4 - warnings (*Connext DDS* and *Replay Service*)
          - 5 - tracing (*Replay Service*)
          - 6 - tracing (*Connext DDS* and *Replay Service*)

        **Default**: 1 (exceptions)
    * - :litrep:`-version`
      - Prints the program version and exits.

.. _section-replay-service-runtime-behavior:

Replay Service Runtime Behavior
-------------------------------

*Replay Service* currently does not delete *DataWriters*, even if all original
*DataWriters* were deleted in the recorded database.