Understanding the client

There are multiple ways to communicate with an ecflow_server, including using CLI (Command Line Interface) ecflow_client, programmatically via the Python API or using the GUI (Graphical User Interface) 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 localhost:3141.
These defaults are overridden by setting the environment variables: ECF_HOST and ECF_PORT.
The explicitly defined options --port and --host will always be used whenever provided.

The ecflow_client is a command line tool that allows sending commands to the ecflow_server, and retrieving information about the current state of the elements that compose the suite definition.

A list of available commands, including their options, can be found by using the --help option:

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 --port and --host options, and use the --ping command:

Listing 7 Ping an ecFlow server using the Python API

ecflow_client --host machinex --port 4141  --ping

The Python API provides the same functionality as the CLI ecflow_client, with the added bonus that allows to leverage on Python for automation.

In terms of connectivity to the server, the Python API uses the same logic as the CLI, including the ability to explicitly set host and port options.

The class ecflow.Client provides the interface to the ecflow_server, such as assessing the connectivity to a server using the ecflow.Client.ping() method:

Listing 8 Ping an ecFlow server using the Python API

#!/usr/bin/env python3

from ecflow import Client

if __name__ == "__main__":

    try:
        # The default is to contact localhost:3141, but will
        # use ECF_HOST and/or ECF_PORT env variables if set.
        ci = Client()
        ci.ping()

        # Explicitly set host and port (n.b. reuses the existing Client)
        ci.set_host_port("machineX:4141")
        ci.ping()

        # Explicitly set host and port when creating the Client
        ci = Client("oetzi:3444")
        ci.ping()

        # Ping inlined
        Client("polonius:4266").ping()

    except RuntimeError as e:
        print(f"ping failed: {e}", )

What to do

List the available commands of ecflow_client using the --help option.
Take the opportunity to learn about the different command categories (e.g. child commands, user commands).
- Use the --help option with the ecflow_client to explore the available command categories.
Take the opportunity to learn about the following commands: ping, load, replace, begin, and resume.
- Use the --help option with the ecflow_client to explore the command descriptions.
Ping the ecflow_server using the CLI ecflow_client, explicitly defining the --host and --port options.
Ping the ecflow_server using the CLI ecflow_client, exporting environment variables ECF_HOST and ECF_PORT.