control

The control service allows to control the behavior of the underlying systems. It provides read/write support for control channels and access to the list of alarms within the specified period. Basing on the current values of the channels (set-points) the system could adjust its behavior. Read/only channels can be used to report various system information before it would be logged into the database, and the alarms are used to report the special conditions in the system operation.

The control interface should be provided by the READER abstraction. If the control interface is not provided directly, the default behavior is to associate the most recent logged data with the control channels. All set-points are considered read-only and empty alarm list is returned upon the request.

Supported targets

  • get - Return the current values of specified controls
  • get_data - Return the last data stored in database as controls. control_group and control_mask point the data, but ID's returned by non-control list requests should be used.
  • set - Set the values of specified controls
  • send - Set the values of specified controls but do not return anything back and do not try to verify result
  • alarms - Get a detailed list of alarms for the specified period (for each alarm type all intervals when it was registered are listed)
  • alarms_summary - Get a brief list of alarms for the specified period (for each alarm only information how often it have been seen is presented)
  • alarms_current - Get a list of the existing special conditions (active alarms)
  • status - Return the current values of the specified controls and all active alarms

Mandatory Properties

Optional Properties

  • time_format - Specifies the format to return timestamps in, by default the UNIX timestamp (seconds since 1970-01-01) is used (fractal numbers are allowed).

get/set targets:

  • control_group ? - Control Group, the control groups can be and often are different from the loggroups
  • control_mask ? - The comma-separated mask of items within the control group, if mask is not specified all group items are considered

set target:

  • control_values ? - The comma-separated list of values to set. If the control_mask is specified, the list should only include values for items in the mask.
  • control_set ? - Alternative way of setting values. The parameter value should contain a comma separated list of equations uid=<value> where the uid is the unique identifier of the channel (the channel numbers are not supported). The error will be returned if the specified uid is not existing or not belonging to the specified control group. Example: control_set=TI350%3D0,TI351%3D4.2 (%3D is a url-encoded '=').
  • control_check ? - This property instructs ADEI to perform checks of current channel indications prior to setting the specified values. The property should contain a comma-separated list of checks. Each check could include references to one or more control channels and the channels are not limited to the group we are setting (see specification of channel addressing). If checks are failed the error will be returned. Example: control_check=TI350+TI351<10,TI352<TI353.

alaram targets:

  • severity ? - the minimal severity of alarms to report
  • limit ? - Limits the list of alarms to the specified amount
  • alarm_mask ? - Limit the list of alarms to the specified ID's (comma-separated list of ID's)

Returned Result

The XML document with the values of current set-points (get, set, and status targets) and the list of alarms (alarms* and status targets) is returned. The values are returned within the data xml node and the alarms within alarms node. See following example for details. We are requesting the list of active alarms and current values of the control_group with id 0. 

http://adei_server.net/adei/services/control.php?target=status&db_server=katrin&db_name=detectpr&control_group=0

and receiving as a result the following XML document: 

<result title="KATRIN Detector">
  <data>
    <Value db_server="katrin" db_name="detector" control_group="0" id="0" name="522-RTP-5-0001" value="0" timestamp="1252632977" verified="1252632977" obtained="1252632977"/>
    <Value db_server="katrin" db_name="detector" control_group="0" id="1" name="522-RTP-5-0002" value="0" timestamp="1252632976" verified="1252632977" obtained="1252632976"/>
    ...
  </data>
  <alarms>
    <Value severity="0" in="1248458852" out="" id="alarm1" name="Valve Status 8 off" description="Run away we are going to explode"/>
    ...
  </alarms>
</result>

If the error is occurred during request processing, the error message is returned. The following format is used: 

<result>
 <Error>Unknown control_group (0) is specified</Error>
</result>

The following properties are returned for each requested control channel:

  • db_server - data source / system
  • db_name - the database / subsystem
  • control_group - control group
  • id - the id of the control channel returned
  • name - the textual description of the control channel
  • value - the current value of the channel
  • timestamp - the time when the current value was set
  • verified - the time when the current value was last verified
  • obtained - the time when ADEI get the value from the underlying system

The following properties are returned for each alarm:

  • severity - importance of the alarm, the bigger number the more important it is
  • in - the time when the special condition was first seen
  • out - the time when the special condition has disappeared, empty value means the condition is still present
  • id - the alarm ID
  • name - the textual description of alarm
  • description - the detailed description of the alarm (advice of actions to perform, etc.)