= 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
 * ''set'' - Set the values of specified controls
 * ''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 ==
 * [wiki:adeiParam_target target] - Control target (see section above)
 * [wiki:adeiParam_db_server db_server ] - Data source / system
 * [wiki:adeiParam_db_name db_name ] - Database name / subsystem

== Optional Properties ==
 * [wiki:adeiParam_time_format 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''':
 * [wiki:adeiParam_control_group control_group ] - Control Group, the control groups can be and often are different from the loggroups
 * [wiki:adeiParam_control_mask control_mask ] - The comma-separated mask of items within the control group, if mask is not specified all group items are considered
'''set target''':
 * [wiki:adeiParam_control_values control_values ]
 * [wiki:adeiParam_control_set control_set ]
 * [wiki:adeiParam_control_check control_check ]
'''alaram targets''':
 * [wiki:adeiParam_severity severity ] - the minimal severity of alarms to report
 * [wiki:adeiParam_limit limit ] - Limits the list of alarms to the specified amount
 * [wiki:adeiParam_alarm_mask 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.)