.. index::
   single: ecFlow variables (tutorial)
   single: ECF_HOME  (tutorial)

.. _tutorial-add-variable:

Adding a variable
=================

This section shows how to use :term:`Variables <variable>` to dynamically modify :term:`task scripts <ecf script>`.

There are three kinds of variables:

* variables that are used by :term:`ecFlow`, such as :code:`ECF_HOME` or :code:`ECF_INCLUDE`.
* variables that are generated by ecFlow, potentially to be used in the task scripts (e.g. :code:`ECF_DATE`, which contains the date of the suite).
* variables that are defined by the user, potentially to be used in the task scripts.

.. note::

   It is good practice to name all user defined variables with capital letters.

.. warning::

   User defined variables should **not** start with :code:`ECF_`.

   This prefix is reserved for ecFlow, and future versions of ecFlow may introduce new variables with this prefix.

This section will introduce a user defined variable :code:`SLEEP` to control the execution time for each task.
which includes the following steps:

#. Update the task scripts to use the variable.
#. Update the :term:`suite definition` with the new variable.

Update Task Scripts
-------------------

Update the existing tasks :code:`t1` and :code:`t2` to call the :code:`sleep` command with a :term:`variable` called SLEEP as a parameter:

.. code-block:: shell
   :caption: $HOME/course/f1/t1.ecf and t2.ecf (Task Script using Variable)

   %include <head.h>
   echo "I will now sleep for %SLEEP% seconds" 
   sleep %SLEEP% 
   %include <tail.h>

Update Suite Definition
-----------------------

.. tabs::

   .. tab:: Text

      Then add the :term:`variable` to the :term:`suite definition`:

      .. code-block:: shell

         # Definition of the suite test.
         suite test
            edit ECF_INCLUDE "{{HOME}}/course" # replace '{{HOME}}' appropriately
            edit ECF_HOME    "{{HOME}}/course"
            family f1
               task t1
                  edit SLEEP 20
               task t2
                  edit SLEEP 20
            endfamily
         endsuite

   .. tab:: Python

      .. literalinclude:: src/ecf-variables.py
         :language: python
         :caption: $HOME/course/test.py


**What to do**

#. Modify the task scripts :code:`t1` and :code:`t2` to use the variable :code:`SLEEP`, as shown above.
#. Modify the suite definition to include the variable :code:`SLEEP`, as shown above.
#. Replace the :term:`suite`, using:

   .. tabs::

      .. tab:: Text

         .. code-block:: shell

            ecflow_client --suspend /test
            ecflow_client --replace /test test.def

      .. tab:: Python

         .. code-block:: shell

            python3 test.py
            python3 client.py

#. Observe the task execution in :term:`ecflow_ui`.
   The tasks should remain in :term:`active` :term:`status` for 20 seconds.
   Inspect also the job output.
#. Temporarily update the variables :code:`SLEEP` using the :term:`ecflow_ui` to different values, and requeue the tasks.
   The tasks should now remain in :term:`active` :term:`status` according to the applicable sleep duration.