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
|
.. index::
single: Client (tutorial)
.. _tutorial-understanding-the-client:
Understanding the client
========================
There are multiple ways to communicate with an :term:`ecflow_server`, including using CLI (Command Line Interface)
:term:`ecflow_client`, programmatically via the :ref:`Python API <python_api>` or using the GUI (Graphical User Interface)
:term:`ecflow_ui`.
For any kink of communication with the server, since there can be multiple servers running in parallel on the same machine,
the client needs to know the machine host name and port to access the server.
This section shows how to contact the server using the CLI client and via the Python API.
To configure the client (CLI and Python API) to contact a server on the given *host* and *port* consider the following:
* The default *host*:*port* is :code:`localhost:3141`.
* These defaults are overridden by setting the environment variables: :code:`ECF_HOST` and :code:`ECF_PORT`.
* The explicitly defined options :code:`--port` and :code:`--host` will always be used whenever provided.
.. tabs::
.. tab:: CLI
The :term:`ecflow_client` is a command line tool that allows sending commands to the :term:`ecflow_server`,
and retrieving information about the current state of the elements that compose the :term:`suite definition`.
A list of available commands, including their options, can be found by using the :code:`--help` option:
.. code-block:: shell
ecflow_client --help
ecflow_client --help child # to list the task (child) commands
ecflow_client --help user # to list the user commands
ecflow_client --help init # get details of the init (child) command
ecflow_client --help load # get details of the load (user) command
To assess the connectivity to a server, explicitly define the :code:`--port` and :code:`--host` options, and use the :code:`--ping` command:
.. code-block:: shell
:caption: Ping an ecFlow server using the Python API
ecflow_client --host machinex --port 4141 --ping
.. tab:: Python
The :ref:`Python API <python_api>` provides the same functionality as the CLI :term:`ecflow_client`,
with the added bonus that allows to leverage on Python for automation.
In terms of connectivity to the server, the :ref:`Python API <python_api>` uses the same logic as the CLI,
including the ability to explicitly set :code:`host` and :code:`port` options.
The class :py:class:`ecflow.Client` provides the interface to the :term:`ecflow_server`, such as assessing the connectivity to a server
using the :py:meth:`ecflow.Client.ping` method:
.. literalinclude:: src/understanding-the-client.py
:language: python
:caption: Ping an ecFlow server using the Python API
**What to do**
#. List the available commands of :term:`ecflow_client` using the :code:`--help` option.
#. Take the opportunity to learn about the different command categories (e.g. child commands, user commands).
- Use the :code:`--help` option with the :term:`ecflow_client` to explore the available command categories.
#. Take the opportunity to learn about the following commands: :code:`ping`, :code:`load`, :code:`replace`, :code:`begin`, and :code:`resume`.
- Use the :code:`--help` option with the :term:`ecflow_client` to explore the command descriptions.
#. Ping the :term:`ecflow_server` using the CLI :term:`ecflow_client`, explicitly defining the :code:`--host` and :code:`--port` options.
#. Ping the :term:`ecflow_server` using the CLI :term:`ecflow_client`, exporting environment variables :code:`ECF_HOST` and :code:`ECF_PORT`.
|
