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

.. _quiesce_tasks:

Tasks/Commands for Quiescence/Un-quiescence
===========================================

Please refer to the `DataPower InfoCenter <http://pic.dhe.ibm.com/infocenter/wsdatap/v5r0m0/index.jsp?topic=%2Fcom.ibm.dp.xi.doc%2Fadministratorsguide.xi50158.htm&path%3D4_2_0_4_1_16/>`_ for the description of the quiescence process.

.. _quiesce:

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

These tasks quiesce/unquiesce services and objects defined by the nested ``object`` element. 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.

You can specify objects to quiesce/unquiesce using ``classPattern``/``namePattern`` attributes and/or using the nested ``object`` element.

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
   * - namePattern
     - Regular expression defining object names to quiesce/unquiesce.
     - 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 60 seconds for quiesce, 15 for unquiesce.
     - 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 -classPattern "HTTPSourceProtocolHa.*"  -namePattern "Test.*"

.. code-block:: xml

   <dp:quiesce>
       <object class="HTTPSourceProtocolHa.*" name="Test.*"/>
   </dp:quiesce>

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 a single domain. Upon this command, DataPower will automatically quiesce or unquiesce all protocol handlers running in the domain.

The domain name is provided using the ``domain`` attribute or :ref:`dp.domain property <connection_options>`.

You can also provide the timeout attribute explained :ref:`earlier <quiesce>`.

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.

Examples
^^^^^^^^

.. code-block:: xml

   <dp:quiesceDomain domain="testDomain" />

.. code-block:: bat

   dpbuddy unquiesceDomain -domain testDomain