Update README.md

README.md

@@ -107,6 +107,61 @@ This improves performance on the server side (merging Json results from etheroge
 the interpretation of the Json response for the client. With this observation in mind, a dedicated paragraph will discuss *mixed
 method requests*.
 
+### <a href="conf_opts" />  Requests: configuration options
+
+The JSon *array* value associated to the *options* key within each *src* contains the *option* names that the client wants to set
+on the cumbia engine. Within the same *src*, each option defined in the *options* array shall be added as a *key* associated to the
+desired value.
+
+This approach (option key list first defined and then option values assigned) favors flexibility at the price of a longer JSon request.
+Options depend on the engine. They can be either added or removed and the adopted syntax decouples the client from the engine.
+
+The most common options are the following:
+
+##### value-only
+
+- "value-only":"true"  in the context of either *s* or *conf* method, the synchronous reply shall bear only the read value, without the
+  configuration associated to the source (in Tango, this means no database access for either attribute properties or command info);
+
+- "value-only":"false" [ default ] in the context of either *s* or *conf* method, the synchronous reply shall carry the 
+  *source configuration* alongside the source current *value*.
+
+Note: this option does not apply to the *read* method, which always reads the current source value and never its configuration
+
+The method *S* (capital *s*) can be used as an alternative to *s* to skip the *synchronous read*. 
+This implies avoiding the configuration phase yet involves a potentially delayed first update for the client (depending on the caserver
+*async* configuration).
+
+##### no-value
+
+- "no-value":"true"  in the context of either *s* or *conf* method, do not include the current *value* of the given *src*
+
+- "no-value":"false" [ default ] the reply contains the value of *src*. This is the default behaviour in *conf* and *s* methods.
+
+This option does not make sense within the *read* method.
+
+
+
+##### read-value
+
+- "read-value":"true"  *suggest* the engine that it is *always safe* to perform a reading contextually to a *subscribe* or *configuration*.
+
+- "read-value":"false" [ default ] use a safer approach (needed for Tango commands) that does not perform a *read* if the *src* is potentially a *command* (Tango).
+   The service uses the *CuTWriterConfFactory* if "read-value" is missing or set to false. If a command is detected (a/b/c->cmd), it is never
+   imparted by the *synchronous* service at configuration time, because that would imply the command execution, which is unwanted.
+
+When a client is sure that a (*Tango*) *command* can be *read* safely (without actually imparting any command), it shall set "read-value":"true" to get a 
+read value included in the synchronous reply. For example, the Tango *State* command in the context of a *reader*.
+
+##### period 
+
+- "period":"INT" an integer value suggesting the polling period desired for the given *src*.
+
+This is just a hint for the engine: according to the *async service* configuration, the polling period may be longer than required (lower frequency).
+Remember also that either quick or *big sized* arrays (where again, *big* depends on the service configuration) may switch communication over *Websocket*
+channels in *binary mode* (server version >= 1.5.0)
+
+
 ### <a href="subscribe" /> Subscribe requests, method: "s"
 
                           +----------+    s
@@ -159,21 +214,39 @@ and *srv-tango-ctrl-01:20000/test/device/1/long_scalar*, with the following payl
  {
      "channel":"qumbia-reader-ebe419b447235fec9b5f811c3468eb8c",
      "id":"223",
-     "srcs":[{"method":"s","options":["period","read-value"],"period":"1000","read-value":"true","src":"srv-tango-ctrl-01:20000/test/device/1/double_scalar"},
-     {"method":"s","options":["period","read-value"],"period":"1000","read-value":"true","src":"srv-tango-ctrl-01:20000/test/device/1/long_scalar"}]
+     "srcs":[{"method":"s","options":["period"],"period":"1000","src":"srv-tango-ctrl-01:20000/test/device/1/double_scalar"},
+     {"method":"s","options":["period"],"period":"1000","src":"srv-tango-ctrl-01:20000/test/device/1/long_scalar"}]
  }
 ```
 
 The expected reply is something like this:
 
 ```json
-[{"_class_":0,"abs_change":"0.01","activity":"property","archive_abs_change":"0.1","archive_period":"1000","archive_rel_change":"0.1","argins":[],"color":"dark_green","data":true,"delta_t":"Not specified","delta_val":"Not specified","description":"Un doppio scalare del device primo","device":"srv-tango-ctrl-01:20000/test/device/1","df":0,"dfs":"scalar","dim_x":1,"disp_level":0,"display_unit":"pq","dt":5,"err":false,"format":"%4.2f","is_command":false,"label":"Doppio Scalare3","max":"255","max_alarm":"Not specified","max_dim_x":1,"max_dim_y":0,"max_warning":"Not specified","method":"s","min":"-255","min_alarm":"Not specified","min_warning":"Not specified","msg":"CuTConfigActivity.execute (1): ","name":"double_scalar","options":["period","read-value"],"period":"1000","periodic_period":"1000","point":"double_scalar","properties":[],"q":2,"qc":"white","qs":"valid","read-value":"true","rel_change":"Not specified","root_attr_name":"Not specified","src":"srv-tango-ctrl-01:20000/test/device/1/double_scalar","standard_unit":"1.0","timestamp_ms":1642156353013.0,"timestamp_us":1642156353.01394,"type":"property","unit":"Pippoer","value":-66.25893320791678,"vt":10,"w_value":0.0,"writable":3,"writable_attr_name":"double_scalar"},{"_class_":0,"abs_change":"1","activity":"property","archive_abs_change":"1","archive_period":"2000","archive_rel_change":"1","argins":[],"color":"dark_green","data":true,"delta_t":"Not specified","delta_val":"Not specified","description":"No description","device":"srv-tango-ctrl-01:20000/test/device/1","df":0,"dfs":"scalar","dim_x":1,"disp_level":0,"display_unit":"km","dt":3,"err":false,"format":"%6d","is_command":false,"label":"long_scalar","max":"Not specified","max_alarm":"Not specified","max_dim_x":1,"max_dim_y":0,"max_warning":"Not specified","method":"s","min":"Not specified","min_alarm":"Not specified","min_warning":"Not specified","msg":"CuTConfigActivity.execute (1): ","name":"long_scalar","options":["period","read-value"],"period":"1000","periodic_period":"1000","point":"long_scalar","properties":[],"q":2,"qc":"white","qs":"valid","read-value":"true","rel_change":"1","root_attr_name":"Not specified","src":"srv-tango-ctrl-01:20000/test/device/1/long_scalar","standard_unit":"1.0","timestamp_ms":1642156353013.0,"timestamp_us":1642156353.013942,"type":"property","unit":"tapiocasUnit","value":237,"vt":5,"w_value":0,"writable":3,"writable_attr_name":"long_scalar"},{"count":2,"id":284,"msg":"ok","type":"async"}]
+[{"_class_":0,"abs_change":"0.01","activity":"property","archive_abs_change":"0.1","archive_period":"1000","archive_rel_change":"0.1","argins":[],"color":"dark_green","data":true,"delta_t":"Not specified","delta_val":"Not specified","description":"Un doppio scalare del device primo","device":"srv-tango-ctrl-01:20000/test/device/1","df":0,"dfs":"scalar","dim_x":1,"disp_level":0,"display_unit":"pq","dt":5,"err":false,"format":"%4.2f","is_command":false,"label":"Doppio Scalare3","max":"255","max_alarm":"Not specified","max_dim_x":1,"max_dim_y":0,"max_warning":"Not specified","method":"s","min":"-255","min_alarm":"Not specified","min_warning":"Not specified","msg":"CuTConfigActivity.execute (1): ","name":"double_scalar","options":["period"],"period":"1000","periodic_period":"1000","point":"double_scalar","properties":[],"q":2,"qc":"white","qs":"valid","rel_change":"Not specified","root_attr_name":"Not specified","src":"srv-tango-ctrl-01:20000/test/device/1/double_scalar","standard_unit":"1.0","timestamp_ms":1642156353013.0,"timestamp_us":1642156353.01394,"type":"property","unit":"Pippoer","value":-66.25893320791678,"vt":10,"w_value":0.0,"writable":3,"writable_attr_name":"double_scalar"},{"_class_":0,"abs_change":"1","activity":"property","archive_abs_change":"1","archive_period":"2000","archive_rel_change":"1","argins":[],"color":"dark_green","data":true,"delta_t":"Not specified","delta_val":"Not specified","description":"No description","device":"srv-tango-ctrl-01:20000/test/device/1","df":0,"dfs":"scalar","dim_x":1,"disp_level":0,"display_unit":"km","dt":3,"err":false,"format":"%6d","is_command":false,"label":"long_scalar","max":"Not specified","max_alarm":"Not specified","max_dim_x":1,"max_dim_y":0,"max_warning":"Not specified","method":"s","min":"Not specified","min_alarm":"Not specified","min_warning":"Not specified","msg":"CuTConfigActivity.execute (1): ","name":"long_scalar","options":["period"],"period":"1000","periodic_period":"1000","point":"long_scalar","properties":[],"q":2,"qc":"white","qs":"valid","rel_change":"1","root_attr_name":"Not specified","src":"srv-tango-ctrl-01:20000/test/device/1/long_scalar","standard_unit":"1.0","timestamp_ms":1642156353013.0,"timestamp_us":1642156353.013942,"type":"property","unit":"tapiocasUnit","value":237,"vt":5,"w_value":0,"writable":3,"writable_attr_name":"long_scalar"},{"count":2,"id":284,"msg":"ok","type":"async"}]
 ```
 
 The first two elements of the JSON array carry the data from *caserver sync*, the last one, with the key *type* set to *async* 
 is the reply from the *async* instance, simply indicating that monitoring has been scheduled (see also 
 [caserver async](#caserver-async)).
 
+##### value-only
+
+If the JSon request *options* key/value is modified as follows:
+
+```json
+"options":["period","value-only"],"period":"1000","value-only":"true",...
+```
+
+then the *src* configuration (min,max,label,format, ...) is not acquired.
+
+
+##### no-value
+
+If the JSon request *options* contains the *no-value* option and it is set to *true*, then the *caserver sync* will not perform a reading on the given src.
+If the request is a *s* (subscribe), this may imply a longer interval for the client to receive the first value from the *async* service (from the channel).
+
+If the configuration is only what you want, consider using the method *conf* instead.
+
 
 ##### <a href="ex_curl_webcon" /> Example 1 (curl + web console)
 
@@ -195,7 +268,7 @@ Within the time to live interval another call to the same URL shall be done in o
 
 If we issue a second *curl* within 300 seconds from the first one, specifying *242* in the *id* field:
 
-> curl http://woody.elettra.eu:8001/bu/src-bundle -d  $'{"channel":"rchan","id":"242","srcs":[{"method":"s","options":["period","read-value"],"period":"1000","read-value":"true","src":"srv-tango-ctrl-01:20000/test/device/1/double_scalar"},{"method":"s","options":["period","read-value"],"period":"1000","read-value":"true","src":"srv-tango-ctrl-01:20000/test/device/1/long_scalar"}]}'
+> curl http://woody.elettra.eu:8001/bu/src-bundle -d  $'{"channel":"rchan","id":"242","srcs":[{"method":"s","options":["period"],"period":"1000","src":"srv-tango-ctrl-01:20000/test/device/1/double_scalar"},{"method":"s","options":["period"],"period":"1000","src":"srv-tango-ctrl-01:20000/test/device/1/long_scalar"}]}'
 
 we will get the same reply seen above.