.. include:: vars.rst

.. _section-usage:

Usage
*****

This chapter explains how to run |CDS| either from the distributed command-line
executable or as a library within your application.

.. _section-usage-executable:

Command-Line Executable
=======================

|CDS| runs as a separate application. The script to run the executable is in
``<NDDSHOME>/bin``.

.. code-block:: bash

    rticlouddiscoveryservice [options]

This section explains how to run *Cloud Discovery Service* from a
command-line tool. In particular, it describes:

- Starting *Cloud Discovery Service* (:numref:`section-starting-cloud-discovery-service`).
- Stopping *Cloud Discovery Service* (:numref:`section-stopping-cloud-discovery-service`).
- Command-line Options (:numref:`section-cloud-discovery-service-command-line-parameters`).

.. _section-starting-cloud-discovery-service:

Starting Cloud Discovery Service
---------------------------------
*Cloud Discovery Service* runs as a separate application. The script to run the
executable is in ``<NDDSHOME>/bin``.

.. code-block:: bash

    rticlouddiscoveryservice [options]

To start *Cloud Discovery Service* with a default configuration, enter:

.. code-block:: bash

    $NDDSHOME/bin/rticlouddiscoveryservice

This command will run *Cloud Discovery Service* indefinitely until you
stop it. See :numref:`section-stopping-cloud-discovery-service`.

.. note::

   *Cloud Discovery Service* is pre-loaded with a builtin configuration that
   has default settings. See :numref:`section-configuration-builtin`.

:numref:`TableCommandLineParameters` describes the command-line parameters.

.. _section-stopping-cloud-discovery-service:

Stopping Cloud Discovery Service
--------------------------------
To stop *Cloud Discovery Service*, press Ctrl-c. *Cloud Discovery Service*
will perform a clean shutdown.

.. _section-cloud-discovery-service-command-line-parameters:

Command-Line Options
-----------------------
The following table describes all the command-line parameters available in
*Cloud Discovery Service*. To list the available commands, run
``rticlouddiscoveryservice -h``.

.. list-table:: Cloud Discovery Service Command-line Options
    :name: TableCommandLineParameters
    :widths: 5 10
    :header-rows: 1

    * - Parameter
      - Description
    * - ``-allowDomain <string>``
      - Subset of domain IDs where |CDS| operates. |br|
        Use this argument in order to indicate which domain IDs |br|
        |CDS| should process announcements for. |br|
        Remaining ones will be automatically ignored. |br|
        **Default:** ``DOMAIN_LIST_ALL`` (forward all domains) |br|
    * - ``-appName <string>``
      - Assigns a name to the execution of the |CDS|. |br|
        Remote commands and status information will refer to the instances using
        this name. |br|
        **Default:** (same as configuration  name). |br|
    * - ``-cfgFile <string>``
      - Path to the configuration file. |br|
        **Default:** (unspecified)
    * - ``-cfgName <string>``
      - Name of the *Cloud Discovery Service* configuration to be loaded. |br|
        It must match a ``<cloud_discovery_service>`` tag in the configuration
        file. |br|
        **Default:** rti.cds.builtin.config.default.
    * - ``-denyDomain <string>``
      - Subset of domain IDs ignored by |CDS|. |br|
        Use this argument in order to indicate which domain IDs |br|
        |CDS| shouldn't process announcements from. |br|
        **Default:** Empty string (no domain IDs are ignored) |br|
        **Overrides:** ``domain_list/allow_domain_id`` or ``-allowDomain``
    * - ``-heapSnapshotDir <dir>``
      - Output directory where the heap monitoring snapshots are dumped. |br|
        The filename format is RTI_heap_<appName>_<processId>_<index>.
        Used only if heap monitoring is enabled. |br|
        **Default**: current working directory
    * - ``-heapSnapshotPeriod <sec>``
      - Period at which heap monitoring snapshots are dumped.
        Enables heap monitoring if > 0. |br|
        **Default**: 0 (disabled)
    * - ``-help``
      - Prints this help and exits.
    * - ``-ignoreXsdValidation``
      - Loads the configuration even if the XSD validation fails.
    * - ``-listConfig``
      - Prints the available configurations and exits.
    * - ``-logFormat <format>``
      - A mask to configure the format of the log messages for both
        the service and DDS. It allows the following values:

            - ``DEFAULT`` - Print message, method name, and activity context
            - ``VERBOSE`` - DEFAULT + module, thread ID and spreads the message over two lines.
            - ``TIMESTAMPED`` - VERBOSE + timestamped
            - ``MINIMAL`` - Print only message number and method name
            - ``MAXIMAL`` - Print all available fields

        **Default:** DEFAULT
    * - ``-maxObjectsPerThread <int>``
      - Maximum number of thread-specific objects that can be created. |br|
        **Default:** 2048
    * - ``-remoteAdministrationDomainId <int>``
      - Enables remote administration and sets the domain ID for communication. |br|
        **Overrides:** ``administration/domain_id``
    * - ``-remoteMonitoringDomainId <int>``
      - Enables remote monitoring and sets the domain ID for status publication. |br|
        **Overrides:** ``monitoring/domain_id``
    * - ``-stopAfter <int>``
      - Number of seconds the *Cloud Discovery Service* runs before it
        stops. |br|
        **Default:** (infinite).
    * - ``-transport <string>``
      - A comma separated list of transport resources, where each resource is
        specified in the form: ``[alias:]receive_port`` |br|
        **Default:**  udpv4:7400 |br|
        **Overrides:** ``transport``
    * - ``-licenseFile <string>``
      - Specifies the license file path to be used.
        See :ref:`section-Common-HowToUseLicenseFile-RTIServices`.
        **Default:**  Empty string
    * - ``-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 *Cloud Discovery Service* version and exits.

All the command-line options are optional; if specified, they override
the values of their corresponding settings in the loaded XML configuration.
See :numref:`section-configuration` for the set of XML elements that can be
overriden with command-line options.

.. _section-usage-cloud-discovery-service-library:

Cloud Discovery Service as a Library
=====================================

|CDS| can be deployed as a library linked into your application on selected
architectures (see :numref:`section-release-notes`). This allows you to create,
configure, and start |CDS| instances from your application.

To build your application, add the dependency with the |CDS| library under
``<NDDSHOME>/lib/<ARCHITECTURE>``, where ``<ARCHITECTURE>`` is a valid and
installed target architecture.

Here is an example of using |CDS| as a library with the Service API:

.. tabs::

    .. group-tab:: C

         .. code-block:: c

            struct RTI_CDS_Property property =
                    RTI_CDS_Property_INITIALIZER;
            struct RTI_CDS_Service *service = NULL;

            /* Initialize property */
            property.cfg_file     = "my_cds_service_cfg.xml";
            property.service_name = "my_cds_service";
            ...

            service = RTI_CDS_Service_new(&property);
            if(service == NULL) {
                /* Log error */
                ...
            }

            if(!RTI_CDS_Service_start(service)) {
                /* Log error */
                ...
            }

            while(keep_running) {
                sleep();
                ...
            }
            ...

            RTI_CDS_Service_delete(service);

    .. group-tab:: C++

         .. code-block:: c++

            using namespace rti::cds;

            CloudDiscoveryService service(
                    ServiceProperty()
                            .cfg_file("my_cds_service_cfg.xml")
                            .service_name("my_cds_service"));

            service.start();

Operating System Daemon
=======================

See generic instructions in :ref:`section-Common-Config-Deamon`.