= 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 ==
 * [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 ] - 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.
 * [wiki:adeiParam_control_set 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 '=').
 * [wiki:adeiParam_control_check 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 [wiki:adeiAddressing channel addressing]). If checks are failed the error will be returned. Example: {{{control_check=TI350+TI351<10,TI352<TI353}}}.

'''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.)