1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
|
.. 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.
|
