.. highlight:: xml
.. index:: Quiesce, Unquiesce

.. _quiesce_tasks:

Quiesce/Un-quiesce Commands
===========================

Please refer to the `DataPower knowledge center <https://www.ibm.com/support/knowledgecenter/en/SS9H2Y_7.6.0/com.ibm.dp.doc/quiescence_concept.html>`_ for the description of the quiescence process.

.. _quiesce:

``quiesce`` and ``unquiesce``
-----------------------------

These tasks quiesce/unquiesce services and objects defined by the ``objects`` option. This is equivalent to navigating to each "quiescable" object (such as an HTTP front side handler) in WebGUI and clicking on the "Quiesce" or "Unquiesce" link.

If you provide a name of a service, such as the name of a Web services proxy, DataPower will automatically quiesce/unquiesce all relevant handlers used by this service.

The tasks wait for the completion of the quiesce/unquiesce operation unless the ``timeout`` attributed is set to -1. The tasks will poll the device until all specified objects reach the "down" operational state for quiesce and "up" state for unquiesce.


Attributes/Options
^^^^^^^^^^^^^^^^^^

.. list-table::
   :widths: 20 80 8
   :header-rows: 1

   * - Name
     - Description
     - Required
   * - objects
     - Comma-delimited list of regexp patterns to quiesce/unquiesce in the format "class:name, class:name". Class and name could be optional, e.g., "class, class" or ":name".
     - No
   * - exclude
     - Comma-delimited list of regexp patterns to exclude from quiesce/unquiesce in the format "class:name, class:name".
     - No
   * - | classPattern
       | CLI alias: class
     - Regular expression defining what classes (types) to quiesce/unquiesce. Deprecated, use "objects" instead.
     - No
   * - | namePattern
       | CLI alias: name
     - Regular expression defining object names to quiesce/unquiesce. Deprecated, use "objects" instead.
     - No
   * - timeout
     - Time, in seconds, to wait for all objects to reach the desired operational state. Exception will be raised if at least one object remains in the invalid state after the timeout.

       -1 disables waiting and device polling.

       Defaults to 180 seconds for quiesce, 90 for unquiesce.
     - No
   * - ignoreDisabled
     - Do not quiesce/unquiesce disabled objects.

       Defaults to ``true``.
     - No

``object`` Nested Element
^^^^^^^^^^^^^^^^^^^^^^^^^

Each object element must match at least one DataPower configuration object.

.. list-table::
   :widths: 20 80 8
   :header-rows: 1

   * - Attribute
     - Description
     - Required
   * - class
     - Regular expression defining what classes (types) to quiesce/unquiesce.
     - Yes, unless ``name`` was provided.
   * - name
     - Regular expression defining object names to quiesce/unquiesce.
     - Yes, unless ``class`` was provided.

.. _examples_14_1_1:

Examples
^^^^^^^^

Quiesce all front-side HTTP handlers whose name starts with "Test".

.. code-block:: bat

   dpbuddy quiesce -objects "HTTPSourceProtocolHa.*:Test.*"

.. code-block:: xml

   <dp:quiesce  -objects="HTTPSourceProtocolHa.*:Test.*" />

You can find more examples under ``samples`` in your distribution or `online <http://myarch.com/dpbuddy-examples-quiesce/>`_.

.. _quiesceDomain:
.. _unquiesceDomain:

``quiesceDomain`` and ``unquiesceDomain``
-----------------------------------------

These tasks quiesce or unquiesce one or multiple domains. Upon this command, DataPower will automatically quiesce or unquiesce all protocol handlers running in the domains.

Please note that if you deleted a previously quiesced domain and then created the domain with the same name, you will not be able to quiesce it. Such a domain will be in the "up" state, but at the same time it will be "quiesced", which causes issues with the ``quiesceDomain``. You should always unquiesce a domain prior to deleting it.

Attributes/Options
^^^^^^^^^^^^^^^^^^

.. list-table::
   :widths: 20 80 8
   :header-rows: 1

   * - Name
     - Description
     - Required
   * - classPattern
     - Regular expression defining what classes (types) to quiesce/unquiesce.
     - No
   * - | domainPatterns
       | CLI alias: domains
     - Comma-delimited list of regular expression patterns defining which domains to quiesce/unquiesce.

       To quiesce/unquiesce all domains simply use ".*".

       Defaults to the current domain. The current domain is specified using the ``dpDomain`` property or ``domain`` attribute of the task.
     - No
   * - timeout
     - Time, in seconds, to wait for all objects to reach the desired operational state. Exception will be raised if at least one object remains in the invalid state after the timeout.

       -1 disables waiting and device polling.

       Defaults to 180 seconds for quiesce, 90 for unquiesce.
     - No

Examples
^^^^^^^^

.. code-block:: xml

   <dp:quiesceDomain domain="testDomain" />
   <dp:quiesceDomain domainPatterns="devDomain,testDomain" />
   <dp:quiesceDomain domainPatterns=".*" />
   <dp:unquiesceDomain domainPatterns=".*" />

.. code-block:: bat

   dpbuddy quiesceDomain -domain testDomain
   dpbuddy quiesceDomain -domainPatterns "devDomain,testDomain"
   dpbuddy quiesceDomain -domainPatterns ".*"
   dpbuddy unquiesceDomain -domainPatterns ".*"