
.. _alter_cli:

alter
*****



.. rubric:: Description




The CLI command :code:`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 :code:`alter` command are specified as a sequence of space
separated options:

.. code-block:: shell

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

where

 - :code:`<operation>`, determines what operation is performed (one of :code:`delete`, :code:`change`, :code:`add`, :code:`set_flag`, :code:`clear_flag`, or :code:`sort`)
 - :code:`<type>`, specifies which type of attribute is being manipulated (the list of types possible depends on the type of command selected previously)
 - :code:`<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)
 - :code:`<value>`, is the value to be used in the operation (this option is not required for all commands, e.g. when deleting an attribute)
 - :code:`<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.



.. rubric:: Output of :code:`--help=alter`



The following help text is generated by :code:`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:
   
      ecflow_client --alter=add variable <variable-name> "value" /             # add server variable
      ecflow_client --alter=add variable <variable-name> "value" /path/to/node # add node variable
   
      ecflow_client --alter=add time "+00:20" /path/to/node
   
      ecflow_client --alter=add date "01.*.*" /path/to/node
   
      ecflow_client --alter=add day "sunday"  /path/to/node
   
      ecflow_client --alter=add label <label-name> "label_value" /path/to/node
   
      ecflow_client --alter=add event <event-name> "set"|"clear" /path/to/node
   
      ecflow_client --alter=add meter <meter-name> "<min>,<max>,value" /path/to/node
   
      ecflow_client --alter=add late "-s 00:01 -a 14:30 -c +00:01" /path/to/node
   
      ecflow_client --alter=add limit mars "100" /path/to/node
   
      ecflow_client --alter=add inlimit /path/to/node/withlimit:limit_name "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
   
      ecflow_client --alter=add zombie "ecf:fail::" /path/to/node     # ask system zombies to fail
      ecflow_client --alter=add zombie "user:fail::" /path/to/node    # ask user generated zombies to fail
      ecflow_client --alter=add zombie "path:fail::" /path/to/node    # ask path zombies to fail
   
      ecflow_client --alter=delete variable FRED /path/to/node  # delete variable FRED
      ecflow_client --alter=delete variable      /path/to/node  # delete *ALL* variables on the given snode
   
   
   The client considers, for both user and child 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.
   

