Adding a variable

This section shows how to use Variables to dynamically modify task scripts.

There are three kinds of variables:

variables that are used by ecFlow, such as ECF_HOME or ECF_INCLUDE.
variables that are generated by ecFlow, potentially to be used in the task scripts (e.g. 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 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 SLEEP to control the execution time for each task. which includes the following steps:

Update the task scripts to use the variable.
Update the suite definition with the new variable.

Update Task Scripts

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

Listing 23 $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

Then add the variable to the suite definition:

# 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

Listing 24 $HOME/course/test.py

import os
from ecflow import Defs, Suite, Family, Task, Edit


def create_family_f1():
    return Family("f1", Task("t1", Edit(SLEEP=20)), Task("t2", Edit(SLEEP=20)))


print("Creating suite definition")
home = os.path.join(os.getenv("HOME"), "course")
defs = Defs(Suite("test", Edit(ECF_INCLUDE=home, ECF_HOME=home), create_family_f1()))
print(defs)

print("Checking job creation: .ecf -> .job0")
print(defs.check_job_creation())

print("Saving definition to file 'test.def'")
defs.save_as_defs("test.def")

What to do

Modify the task scripts t1 and t2 to use the variable SLEEP, as shown above.
Modify the suite definition to include the variable SLEEP, as shown above.

Replace the suite, using:

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

python3 test.py
python3 client.py

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