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
|
.. index::
single: Load the file (tutorial)
single: Loading Suite created in python (tutorial)
single: Client (tutorial)
single: add_variable (tutorial)
single: add_task (tutorial)
.. _tutorial-load-file:
Loading the suite
=================
The next step is to *load* the :term:`suite definition` to the :term:`ecflow_server`, and thus inform the server about the :term:`suite` structure and components.
As part of loading the :term:`suite definition`, the :term:`ecflow_server` performs several validation steps, and only if the validation is successful will the :term:`suite definition` be accepted.
There are several options to load the :term:`suite definition` to the :term:`ecflow_server`.
If a :term:`suite definition` file, such as :file:`test.def`, was manually created then the CLI :term:`ecflow_client` provides the :code:`--load` command.
If the :term:`suite definition` was programmatically generated, e.g. by a Python script using the :ref:`Python API <python_api>`, the same script can load the :term:`suite definition` file.
.. note::
Choose only one of two methods below to avoid errors associated with loading :term:`suite definition` twice.
.. tabs::
.. tab:: CLI
Load the :file:`test.def` using the command line interface :term:`ecflow_client`:
.. code-block:: shell
cd $HOME/course
ecflow_client --load test.def
The :term:`suite definition` will be validated and loaded into the :term:`ecflow_server`. If the validation fails, the suite is not loaded.
.. tab:: Python
As seen previously, the :ref:`Python API <python_api>` can be used to generate the :term:`suite definition` file.
This file can be loaded into the server as described earlier using the the :ref:`Python API <python_api>`,
as done with the CLI :term:`ecflow_client`. The following code snippet shows how to load the :term:`suite definition` file
:file:`test.def` into the server using the :ref:`Python API <python_api>`.
.. literalinclude:: src/load-the-file.py
:language: python
:caption: $HOME/course/client.py
When the script is executed, the :term:`suite definition` will be validated and loaded into the :term:`ecflow_server`.
If the validation fails, the suite is not loaded.
Notice that, when using the :ref:`Python API <python_api>`, the :term:`suite definition` is generated in memory
and can be directly loaded into the server. However it is **highly recommended** to effectively save the :term:`suite definition`
to a file before loading it into the server, and thus separate the following steps:
* the generation of the :term:`suite definition`,
* loading the :term:`suite definition` into the server.
.. code-block:: python
:caption: Example of how to load the in-memory definition into the server
defs = ... # create the suite definition in memory
try:
ci = Client()
print("[1] Load the in memory definition(defs) into the server")
ci.load(defs) # load the in memory python definition(def) into server
except RuntimeError as e:
print("Failed:",e)
**What to do**
#. Load the :term:`suite definition` file using the CLI :term:`ecflow_client`
#. (Optional) Create the :code:`$HOME/course/client.py` script and :term:`suite definition` file.
#. Inspect the :term:`ecflow_server` log file, and check that the :term:`suite definition` was successfully loaded.
.. warning::
The same :term:`suite definition` cannot be loaded multiple times.
If a suite :code:`test` already exists on the server, it can be deleted before loading the :term:`suite definition`
again, using the :code:`--delete` command:
.. code-block:: shell
ecflow_client --delete /test
# find more about the --delete command with: ecflow_client --help delete
Alternatively, the :code:`--replace` command can be used to re-load part or all of the suite, as as follows:
.. code-block:: shell
ecflow_client --replace /test test.def # replace the suite test
ecflow_client --replace /test/t1 test.def # replace just task t1
# find more about the --replace command with: ecflow_client --help replace
|
