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
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
|
.. _query_cli:
query
*****
.. rubric:: Description
Currently, the ecflow python API provides quite extensive functionality.
However sometimes we just want to query simple state on the command
line, and using the full-blown python API, can seem like overkill.
Query can be used in these simple cases
Query the status of attributes i.e. state, dstate, repeat,event, meter,
variable, limit , limit_max or trigger expression without blocking
- state return [unknown \| complete \| queued \| aborted \|
submitted \| active] to standard out
- dstate return [unknown \| complete \| queued \| aborted \|
submitted \| active \| suspended] to standard out
- | repeat returns current value as a string to standard out, can
also retrieve the next and previous value of the repeat. See
examples below
| The next/prev will always stay within repeat bounds. hence calling
'next' on the last value of the repeat, will return last value.
| Likewise calling 'prev' on a repeat that has not started, will
return the first/start value.
- event return 'set' \| 'clear' to standard out
- meter return value of the meter to standard out
- limit return the current value of the limit
- limit_max return the maximum value of the limit
- label return new value otherwise the old value
- variable return value of the variable, repeat or generated
variable to standard out, will search up the node tree
- trigger returns 'true' if the expression is true, otherwise
'false'
If this command is called within a '.ecf' script we will additionally log the task calling this command
This is required to aid debugging for excessive use of this command
The command will fail if the node path to the attribute does not exist
in the definition and if:
- repeat The repeat is not found
- event The event is not found
- meter The meter is not found
- limit/limit_max The limit is not found
- label The label is not found
- variable No user or generated variable or repeat of that name found
on node, or any of its parents
- trigger Trigger does not parse, or reference to nodes/attributes in
the expression are not valid
Arguments:
- arg1 = [ state \| event \| meter \| label \| variable \| trigger \|
limit \| limit_max ]
- arg2 = <path> \| <path>:name where name is name of a event,
meter,limit or variable
- arg3 = trigger expression (optional) \| prev \| next # prev,next
only used when arg1 is repeat
Usage:
.. code-block:: shell
state=$(ecflow_client --query state /path/to/node) # return node state to standard out
dstate=$(ecflow_client --query dstate /path/to/node) # state that can includes suspended
value=$(ecflow_client --query repeat /path/to/node ) # return the current value as a string
value=$(ecflow_client --query repeat /path/to/node prev ) # return the previous value as a string, does not modify real repeat
value=$(ecflow_client --query repeat /path/to/node next) # return the next value as a string, does not modify real repeat
event=$(ecflow_client --query event /path/to/task/with/event:event_name) # return set | clear to standard out
meter=$(ecflow_client --query meter /path/to/task/with/meter:meter_name) # returns the current value of the meter to standard out
value=$(ecflow_client --query variable /path/to/task/with/var:var_name ) # returns the variable value to standard out
limit_value=$(ecflow_client --query limit /path/to/task/with/limit:limit_name) # returns the current value of the limit to standard out
limit_max=$(ecflow_client --query limit_max /path/to/task/with/limit:limit_name) # returns the max value of the limit to standard out
label_value=$(ecflow_client --query label %ECF_NAME%:label_name) # returns the current value of the label to standard out
value=$(ecflow_client --query trigger /path/to/node/with/trigger \"/suite/task == complete\") # return true if expression evaluates false otherwise
.. rubric:: Output of :code:`--help=query`
The following help text is generated by :code:`ecflow_client --help=query`
::
query
-----
Query the status of attributes
i.e state,dstate,repeat,event,meter,label,variable or trigger expression without blocking
- state return [unknown | complete | queued | aborted | submitted | active] to standard out
- dstate return [unknown | complete | queued | suspended | aborted | submitted | active] to standard out
- repeat returns current value as a string to standard out
- event return 'set' | 'clear' to standard out
- meter return value of the meter to standard out
- limit return current value of limit to standard out
- limit_max return limit max value to standard out
- label return new value otherwise the old value
- variable return value of the variable, repeat or generated variable to standard out,
will search up the node tree
- trigger returns 'true' if the expression is true, otherwise 'false'
If this command is called within a '.ecf' script we will additionally log the task calling this command
This is required to aid debugging for excessive use of this command
The command will fail if the node path to the attribute does not exist in the definition and if:
- repeat The repeat is not found
- event The event is not found
- meter The meter is not found
- limit/limit_max The limit is not found
- label The label is not found
- variable No user or generated variable or repeat of that name found on node, or any of its parents
- trigger Trigger does not parse, or reference to nodes/attributes in the expression are not valid
Arguments:
arg1 = [ state | dstate | repeat | event | meter | label | variable | trigger | limit | limit_max ]
arg2 = <path> | <path>:name where name is name of a event, meter, label, limit or variable
arg3 = trigger expression | prev | next # prev,next only used when arg1 is repeat
Usage:
ecflow_client --query state / # return top level state to standard out
ecflow_client --query state /path/to/node # return node state to standard out
ecflow_client --query dstate /path/to/node # state that can included suspended
ecflow_client --query repeat /path/to/node # return the current value as a string
ecflow_client --query repeat /path/to/node prev # return the previous value as a string
ecflow_client --query repeat /path/to/node next # return the next value as a string
ecflow_client --query event /path/to/task/with/event:event_name # return set | clear to standard out
ecflow_client --query meter /path/to/task/with/meter:meter_name # returns the current value of the meter to standard out
ecflow_client --query limit /path/to/task/with/limit:limit_name # returns the current value of the limit to standard out
ecflow_client --query limit_max /path/to/task/with/limit:limit_name # returns the max value of the limit to standard out
ecflow_client --query label /path/to/task/with/label:label_name # returns the current value of the label to standard out
ecflow_client --query variable /path/to/task/with/var:var_name # returns the variable value to standard out
ecflow_client --query trigger /path/to/node/with/trigger "/suite/task == complete" # return true if expression evaluates false otherwise
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.
|
