alter

Description

The CLI command alter enables the manipulation of node attributes in an ecFlow suite, namely it allows to:

add new node attributes

remove existing node attributes

update some characteristics of existing node attributes

set/clear node flags

sort node attributes

The arguments to the alter command are specified as a sequence of space separated options:

ecflow_client --alter <operation> <type> <name> <value> <path>

where

<operation>, determines what operation is performed (one of delete, change, add, set_flag, clear_flag, or sort)

<type>, specifies which type of attribute is being manipulated (the list of types possible depends on the type of command selected previously)

<name>, is the name of the attribute being manipulated (in the case where the attribute is unnamed, e.g. Repeat, Complete, Trigger, this option should be omitted)

<value>, is the value to be used in the operation (this option is not required for all commands, e.g. when deleting an attribute)

<path> (<path> (...)), one or more paths to the nodes where the operation is to be performed

See more details about each argument in the next section.

Output of --help=alter

The following help text is generated by ecflow_client --help=alter

alter
-----

Alter the node according to the options.

arg1 = [ delete | change | add | set_flag | clear_flag | sort ]

arg2 = For delete:
       [ variable | time | today | date  | day | cron | event | meter | late | generic |
         queue | label | trigger | complete | repeat | limit | inlimit | limit_path |
         zombie | aviso | mirror ]

       For change:
       [ variable | clock_type | clock_gain | clock_date | clock_sync  | event | meter |
         label | trigger  | complete | repeat | limit_max | limit_value | defstatus |
         late | time | today | aviso | mirror ]

       For add:
       [ variable | time | today | date | day | zombie | event | meter | late | limit |
         inlimit | label | aviso | mirror ]

       For set_flag or clear_flag:
       [ force_aborted | user_edit | task_aborted | edit_failed | ecfcmd_failed |
         statuscmd_failed | killcmd_failed | no_script | killed | status | late |
         message complete | queue_limit | task_waiting | locked | zombie | archived |
         restored | threshold | log_error | checkpt_error ]

       For sort:
       [ event | meter | label | variable| limit | all ]

arg3 = [ <name> | <value> ]

arg4 = <new-value>

arg5 = <path> (<path> (...)) - at least one node path required.

*Important Notes*

 * All paths must start with a leading '/' character.

 * To update, create or remove server variables use '/' for path.

 * When updating unnamed attributes (Repeat, Trigger, Complete, ...) the name/arg3 is not necessary.

 * After changing the clock the suite needs to be re-queued for the change to take effect.

 * When adding or updating node attributes (e.g. variable, meter, event, label, limits, late)
   the name (arg3) and value (arg4) must be quoted.

 * When sorting attributes, 'recursive' can be used as the value (arg3).

 * When adding a meter, the value (arg4) is expected to be a comma-separated triplet
   of numerical values the form "<min>,<max>,<value>" (n.b. no spaces are allowed).

 * When adding an event, the non-optional value (arg4) must be either "set" or "clear".

 * When adding or updating aviso and mirror attributes, the value (arg4) is expected to be
   a quoted list of configuration options. For example:
   * for aviso, "--remote_path /s1/f1/t2 --remote_host host --polling 20 --remote_port 3141 --ssl)"
   * for mirror, "--listener '{ \"event\": \"mars\", \"request\": { \"class\": "od" } }'
                  --url http://aviso/ --schema /path/to/schema --polling 60"

 * For both aviso and mirror, the special value "reload" forces reloading the configuration.
   This is typically useful after updating variables used to configure these kind of attributes.

Usage:

    --alter=add variable <variable-name> "value" /             # add server variable
    --alter=add variable <variable-name> "value" /path/to/node # add node variable

    --alter=add time "+00:20" /path/to/node

    --alter=add date "01.*.*" /path/to/node

    --alter=add day "sunday"  /path/to/node

    --alter=add label <label-name> "label_value" /path/to/node

    --alter=add event <event-name> "set"|"clear" /path/to/node

    --alter=add meter <meter-name> "<min>,<max>,value" /path/to/node

    --alter=add late "-s 00:01 -a 14:30 -c +00:01" /path/to/node

    --alter=add limit mars "100" /path/to/node

    --alter=add inlimit /path/to/node/withlimit:limit_name "10" /path/to/node

    --alter=add inlimit /path/to/node/withlimit:limit_name "-s 10" /path/to/node

    --alter=add inlimit /path/to/node/withlimit:limit_name "-n 10" /path/to/node

    # zombie attributes have the following structure:
      `zombie_type`:(`client_side_action` | `server_side_action`):`child`:`zombie_life_time`
       zombie_type        = "user" | "ecf" | "path" | "ecf_pid" | "ecf_passwd" | "ecf_pid_passwd"
       client_side_action = "fob" | "fail" | "block"
       server_side_action = "adopt" | "delete" | "kill"
       child              = "init" | "event" | "meter" | "label" | "wait" | "abort" | "complete" | "queue"
       zombie_life_time   = unsigned integer default: user(300), ecf(3600), path(900)  minimum is 60

    --alter=add zombie "ecf:fail::" /path/to/node     # ask system zombies to fail
    --alter=add zombie "user:fail::" /path/to/node    # ask user generated zombies to fail
    --alter=add zombie "path:fail::" /path/to/node    # ask path zombies to fail

    --alter=delete variable FRED /path/to/node  # delete variable FRED
    --alter=delete variable      /path/to/node  # delete *ALL* variables on the given snode

The client considers, for both user and task commands, the following environment variables:

  ECF_HOST <string> [mandatory*]
    The main server hostname; default value is 'localhost'
  ECF_PORT <int> [mandatory*]
    The main server port; default value is '3141'
  ECF_SSL <any> [optional*]
    Enable secure communication between client and server.
  ECF_HOSTFILE <string> [optional]
    File that lists alternate hosts to try, if connection to main host fails
  ECF_HOSTFILE_POLICY <string> [optional]
    The policy ('task' or 'all') to define which commands consider using alternate hosts.

The options marked with (*) must be specified in order for the client to communicate
with the server, either by setting the environment variables or by specifying the
command line options.