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

.. _tutorial-add-variable:

ecFlow variables
================

| We already saw that ecFlow has some :term:`variable`\ s, like ECF_HOME. 
| There are three kinds of variables:

* The variables that are used by :term:`ecFlow`, like ECF_HOME.
* The variables that are defined by the user. They should **not** start with "ECF". It is good practice to name these variables with capital letters. 
* The variables that are generated by ecFlow, and that you can use in your jobs, like ECF_DATE which contains the date of the suite.

Ecf Script
----------

In the previous example, we have copied the file :file:`t1.ecf` to the file :file:`t2.ecf`.

Edit those two files so they call the unix sleep command with a :term:`variable` called SLEEP as a parameter:

.. code-block:: shell
   :caption: $HOME/course/f1/t1.ecf

   %include <head.h>
   echo "I will now sleep for %SLEEP% seconds" 
   sleep %SLEEP% 
   %include <tail.h>
   
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' with the path to your home directory
      edit ECF_HOME    "$HOME/course"
      family f1
         task t1
            edit SLEEP 20 
         task t2
            edit SLEEP 20 
      endfamily
   endsuite 
   
Python
------

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


**What to do**

#. Do the modifications
#. Replace the :term:`suite`. For Python use:

   ::

      python3 test.py
      python3 client.py

   For text use:
   
   ::
       
       ecflow_client --suspend=/test ;  ecflow_client --replace=/test test.def

#. Watch in :term:`ecflow_ui`. 
   You should see the tasks with a :term:`status` :term:`active` for 20 seconds. Look at the job output.