6 The TANGO C++ Application Programmer Interface

1 Tango::DeviceProxy()

The high level object which provides the client with an easy-to-use interface to TANGO devices. DeviceProxy is a handle to the real Device (hence the name Proxy) and is not the real Device (of course). DeviceProxy provides interfaces to all TANGO Device interfaces. The DeviceProxy manages timeouts, stateless connections (new DeviceProxy() nearly always works), and reconnection if the device server is restarted.

1 Constructors

1 DeviceProxy::DeviceProxy(string &name, CORBA::ORB *orb=NULL)

Create a DeviceProxy to a device of the specified name. The TANGO_HOST environment variable is used to determine which TANGO database to connect to. The client can specify an ORB as argument if she wants to. The constructor will connect to the TANGO database, query for the client's network address and build a connection to the device. If the device is defined in the TANGO database but the device server is not running DeviceProxy will try to build a connection every time the client tries to access the device. If the device is not defined an exception is thrown. Example :

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: DeviceProxy *my_device = new DeviceProxy(``my/own/device'');

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

See appendix on device naming for all details about Tango device naming syntax. If an alias name is defined for the device, this alias name can be used to create the DeviceProxy instance.
Exception: WrongNameSyntax, ConnectionFailed

2 DeviceProxy::DeviceProxy(const char name, CORBA::ORB orb = NULL)

Idem previous call

2 Miscellaneous methods

1 DeviceInfo DeviceProxy::info()

A method which returns information on the device in a DeviceInfo structure. Example :

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: cout <<  device info :  << endl
DeviceInfo dev_info = my_device->info() << endl;
cout <<  dev_class  << dev_info.dev_class;
cout <<  server_id  << dev_info.server_id;
cout <<  server_host  << dev_info.server_host;
cout <<  server_version  << dev_info.server_version;
cout <<  doc_url  << dev_info.doc_url;
cout <<  device_type  << dev_info.dev_type;

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

All DeviceInfo fields are strings except for the server_version server_version which is a long integer.
Exception: Connection Failed, CommunicationFailed, DevFailed from device

2 DevState DeviceProxy::state()

A method which return the state of the device as a Tango::DevState type. Example :

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: dev_state = my_device->state() << endl;

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: ConnectionFailed, CommunicationFailed

3 string DeviceProxy::status()

A method which return the status of the device as a string. Example :

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: cout << device status << my_device->status() << endl;

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: ConnectionFailed, CommunicationFailed

4 int DeviceProxy::ping()

A method which sends a ping to the device and returns the time elapsed as microseconds. Example :

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: cout << device ping took << my_device->ping() << microseconds << endl;

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: ConnectionFailed, CommunicationFailed

5 void DeviceProxy::set_timeout_millis(int timeout)

Set client side timeout for device in milliseconds. Any method which takes longer than this time to execute will throw an exception.
Exception: none

6 int DeviceProxy::get_timeout_millis()

Get the client side timeout in milliseconds.
Exception: none

7 int DeviceProxy::get_idl_version()

Get the version of the Tango Device IDL interface implemented by the device
Exception: none

8 void DeviceProxy::set_source(DevSource source)

Set the data source (device, polling buffer, polling buffer than device) for command_inout and read_attribute methods. The DevSource is an enumerated type which can be one of {DEV, CACHE, CACHE_DEV}. The default value is CACHE_DEV. See chapter on Advanced Feature for all details regarding polling.
Exception: none

9 DevSource DeviceProxy::get_source()

Get the device data source used by command_inout or read_attribute methods. The DevSource is an enumerated type which can be one of {DEV, CACHE, CACHE_DEV}. See chapter on Advanced Feature for all details regarding polling.
Exception: none

10 vector<string> *DeviceProxy::black_box(int n)

Get the last n commands executed on the device server and return a pointer to a vector of strings containing the date, time, command, and from which client computer the command was executed. This method allocates memory for the vector of strings returned to the caller. It is the caller responsibility to delete this memory.
Exception: ConnectionFailed, CommunicationFailed, DevFailed from device

11 string DeviceProxy::name()

Return the device name (from the device itself)
Exception: ConnectionFailed, CommunicationFailed

12 string DeviceProxy::adm_name()

Returns the name of the corresponding administrator device. This is useful if you need to send an administration command to the device server e.g. restart it.
Exception: ConnectionFailed, CommunicationFailed

13 string DeviceProxy::dev_name()

Return the device name as it is stored locally

14 string DeviceProxy::description()

Returns the device description as a string.
Exception: ConnectionFailed, CommunicationFailed

15 DbDevImportInfo DeviceProxy::import_info()

Query the device for import info from the database. This method returns a DbDevImprtInfo type. The DbDevImportInfo type is a struct defined as follows :

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: class DbDevImportInfo {
public :
    string name;
    long exported;
    string ior;
    string version; };

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: NonDbDevice

16 void DeviceProxy::set_transparency_reconnection(bool flag)

If flag is true, no exception will be thrown in case of network communication error between client and server. The API will try to re-build the network connection between client and server as soon as an error is detected. See

more more details on reconnection and exception

17 bool DeviceProxy::get_transparency_reconnection()

Returns the transparency reconnection flag.

18 string DeviceProxy::alias()

Returns the device alias name if one is defined otherwise, throws a DevFailed exception with the reason field set to Db_AliasNotDefined.

19 AccessControlType DeviceProxy::get_access_right()

Returns the device access right. AccessControlType is one enumeration with 2 values which are ACCESS_READ and ACCESS_WRITE. In case the Tango Access Control systemis not used, ACCESS_WRITE is returned.

3 Synchronous command oriented methods

1 CommandInfo DeviceProxy::command_query(string command)

Query the device for information about a single command. This command returns a single CommandInfo type. The CommandInfo type is a struct described in command_list_query().
Exception: ConnectionFailed, CommunicationFailed, DevFailed from device

2 CommandInfoList *DeviceProxy::command_list_query()

Query the device for info on all commands. This method returns a vector of CommandInfo types. This method allocates memory for the vector of CommandInfo returned to the caller. It is the caller responsibility to delete this memory. The CommandInfo type is a struct defined as follows :

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: typedef _CommandInfo
{
    string           cmd_name;      /* command name as ascii string */
    long             cmd_tag;       /* command as binary value (for TACO) */
    long             in_type;       /* in type as binary value */
    long             out_type;      /* out type as binary value */
    string           in_type_desc;  /* description of in type (optional) */
    string           out_type_desc; /* description of out type (optional) */
    Tango::DispLevel disp_level;    /* Command display level */
} CommandInfo;
typedef CommandInfoList vector<CommandInfo>;

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: ConnectionFailed, CommunicationFailed, DevFailed from device

3 DeviceData DeviceProxy::command_inout(string)

Execute a command on a device which takes no input arguments (void). The result is returned in a DeviceData object (cf. below how to insert and extract data from DeviceData).
Exception: ConnectionFailed, CommunicationFailed, DeviceUnlocked, DevFailed from device

4 DeviceData DeviceProxy::command_inout(const char *)

Idem previous call

5 DeviceData Deviceproxy::command_inout(string, DeviceData &)

Execute a command on a device. Input arguments are passed in a DeviceData object, output is returned as a DeviceData object (see below on how to insert and extract data from DeviceData).
Exception: ConnectionFailed, CommunicationFailed, DeviceUnlocked, DevFailed from device

6 DeviceData DeviceProxy::command_inout(const char *, DeviceData &)

Idem previous call

7 vector<DeviceDataHistory> *command_history(string &, int)

Retrieve command history from the command polling buffer. The first argument is the command name. The second argument is the wanted history depth. This method returns a vector of DeviceDataHistory types. This method allocates memory for the vector of DeviceDataHistory returned to the caller. It is the caller responsibility to delete this memory. Class DeviceDataHistory is detailed on chapter

. See chapter on Advanced Feature for all details regarding polling.

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: DeviceProxy dev = new DeviceProxy(...);
vector<DeviceDataHistory> *hist;
hist = dev->command_history(Status,5);
for (int i = 0;i < 5;i++)
{

    bool fail = (*hist)[i].failed();
    if (fail == false)
    {
        string str;
        (*hist)[i] >> str;
        cout << Status =  << str << endl;
    }
    else
    {
        cout << Command failed ! << endl;
        cout << Error level 0 desc =  << ((*hist)[i].errors())[0].desc << endl;
    }
    cout << Date =  << (*hist)[i].date().tv_sec << endl;
}
delete hist;

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: NonSupportedFeature, ConnectionFailed, CommunicationFailed, DevFailed from device

8 DeviceDataHistoryList command_history(const char , int)

Idem previous call

4 Synchronous attribute related methods

1 Compatibility between Tango release 4 and release 5 regarding attribute properties

Between Tango V4 and Tango V5, attribute configuration has been modified to incorporate alarm and event related parameters. This explains why it exists two structure types for attribute configuration parameters. All Tango V4 parameters are defined in a structure called AttributeInfo and a new structure called AttributeInfoEx has been defined for all Tango V5 parameters. Nevertheless, AttributeInfoEx inherits from AttributeInfo and it is always possible to call the Tango V5 DeviceProxy::attribute_query() method and to store its result in one AttributeInfo structure thus allowing compatibility for client written for Tango V4 but linked with Tango V5. It is also possible for a client written and linked with Tango V5 to call Tango V5 DeviceProxy::attribute_query() method to all kind of Tango devices. For device using Tango V4, the alarm and event related parameters will be retrieved from the database instead of from the device.

2 AttributeInfoEx DeviceProxy::attribute_query(string attribute)

Query the device for information about a single attribute. This command returns a single AttributeInfoEx type which inherits from the AttributeInfo type. The AttributeInfoEx and AttributeInfo types are structures described in get_attribute_config() and get_attribute_config_ex().
Exception: ConnectionFailed, CommunicationFailed, DevFailed from device

3 AttributeInfoList * DeviceProxy::attribute_list_query()

Query the device for info on all attributes. This method returns a vector of AttributeInfo types. The AttributeInfo type is a structure described in get_attribute_config(). This method allocates memory for the vector of AttributeInfo structures returned to the caller. It is the caller responsibility to delete this memory.

4 AttributeInfoListEx * DeviceProxy::attribute_list_query_ex()

Query the device for info on all attributes. This method returns a vector of AttributeInfoEx types. The AttributeInfoEx type is a structure described in get_attribute_config_ex(). This method allocates memory for the vector of AttributeInfoEx structures returned to the caller. It is the caller responsibility to delete this memory.

5 vector<string> *DeviceProxy::get_attribute_list()

Return the names of all attributes implemented for this device as a vector of strings. This method allocates memory for the vector of strings returned to the caller. It is the caller responsibility to delete this memory.
Exception: ConnectionFailed, CommunicationFailed, DevFailed from device

6 AttributeInfoList *DeviceProxy::get_attribute_config(vector<string>&)

Return the attribute configuration for the list of specified attributes. To get all the attributes pass a vector containing the string AllAttr (defined in tango_const.h). This method allocates memory for the vector of AttributeInfo returned to the caller. It is the caller responsibility to delete this memory. AttributeInfo is a struct defined as follows :

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: typedef struct _AttributeInfo
{
   string             name;
   AttrWriteType      writable;
   AttrDataFormat     data_format;
   int                data_type;
   int                max_dim_x;
   int                max_dim_y;
   string             description;
   string             label;
   string             unit;
   string             standard_unit;
   string             display_unit;
   string             format;
   string             min_value;
   string             max_value;
   string             min_alarm;
   string             max_alarm;
   string             writable_attr_name;
   vector<string>     extensions;
   Tango::DispLevel   disp_level;
} AttributeInfo;

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: ConnectionFailed, CommunicationFailed, DevFailed from device

7 AttributeInfoListEx *DeviceProxy::get_attribute_config_ex(vector<string>&)

Return the extended attribute configuration for the list of specified attributes. To get all the attributes pass a vector containing the string AllAttr (defined in tango_const.h). This method allocates memory for the vector of AttributeInfoEx returned to the caller. It is the caller responsibility to delete this memory. AttributeInfoEx is a structure defined as follows :

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: struct AttributeInfoEx: public AttributeInfo
{
   AttributeAlarmInfo alarms;
   AttributeEventInfo events;
   vector<string>     sys_extensions;
};

struct AttributeAlarmInfo
{
   string           min_alarm;
   string           max_alarm;
   string           min_warning;
   string           max_warning;
   string           delta_t;
   string           delta_val;
   vector<string>   extensions;
};

struct AttributeEventInfo
{
   ChangeEventInfo     ch_event;
   PeriodicEventInfo   per_event;
   ArchiveEventInfo    arch_event;
};

struct ChangeEventInfo
{
   string           rel_change;
   string           abs_change;
   vector<string>   extensions;
};

struct PeriodicEventInfo
{
   string           period;
   vector<string>   extensions;
};

struct ArchiveEventInfo
{
   string           archive_rel_change;
   string           archive_abs_change;
   string           archive_period;
   vector<string>   extensions;
};

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: ConnectionFailed, CommunicationFailed, DevFailed from device

8 AttributeInfoEx DeviceProxy::get_attribute_config(string&)

Return the attribute configuration for a single attributes. The AttributeInfoEx is a structure defined above.
Exception: ConnectionFailed, CommunicationFailed, DevFailed from device

9 void DeviceProxy::set_attribute_config(AttributeInfoList &)

Change the attribute configuration for the specified attributes.
Exception: ConnectionFailed, CommunicationFailed, DeviceUnlocked, DevFailed from device

10 void DeviceProxy::set_attribute_config(AttributeInfoListEx &)

Change the attribute configuration for the specified attributes.
Exception: ConnectionFailed, CommunicationFailed, DeviceUnlocked, DevFailed from device

11 vector<DeviceAttribute> *DeviceProxy::read_attributes(vector<string>&)

Read the list of specified attributes. To extract the value you have to use the operator of the class DeviceAttribute which corresponds to the data type of the attribute. NOTE: There is no automatic type conversion from the attribute native type to user type e.g. if an attribute returns a short you cannot extract it as a double, you have to extract it as a short. By default, if the server reports error for one of the attribute in the list, this error will be passed to the user using exception when he (she) will try to extract the data form the corresponding See sub-chapter on DeviceAttribute to learn how to change this default behaviour. DeviceAttribute object. This method allocates memory for the vector of DeviceAttribute objects returned to the caller. This is the caller responsibility to delete this memory. Example :

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: vector<DeviceAttribute> *devattr;
vector<string> attr_names;

attr_names.push_back(attribute_1);
attr_names.push_back(attribute_2);
devattr = device->read_attributes(attr_names);
short short_attr_1;
long long_attr_2;
(*devattr)[0] >> short_attr_1;
(*devattr)[1] >> long_attr_2;
cout << my_attribute value << short_attr;
delete devattr;

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: ConnectionFailed, CommunicationFailed

12 DeviceAttribute DeviceProxy::read_attribute(string&)

Read a single attribute. To extract the value you have to use the operator of the class DeviceAttribute which corresponds to the data type of the attribute. NOTE: There is no automatic type conversion from the attribute native type to user type e.g. if an attribute returns a short you cannot extract it as a double (this will return 0) you have to extract it as a short. See example above.
Exception: ConnectionFailed, CommunicationFailed

13 DeviceAttribute DeviceProxy::read_attribute(const char *)

Idem previous call

14 void DeviceProxy::write_attributes(vector<DeviceAttribute>&)

Write the specified attributes. To insert the values to write you have to use the operator of the DeviceAttribute class which corresponds to the data type of the attribute. NOTE: There is no automatic type conversion from the user type to the attribute native type e.g. if an attribute expects a short you cannot insert it as a double (this will throw an exception) you have to insert it as a short. Note that this is the only API call which could throw a NamedDevFailedList exception. See

to get all the details on this exception. Example :

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: vector<DeviceAttribute> attr_in;
string att1_name(First_attr);
string att2_name(Second_attr);
short short_attr;
double double_attr; attr_in.push_back(DeviceAttribute(att1_name,short_attr));
attr_in.push_back(DeviceAttribute(att2_name,double_attr));
device->write_attributes(attr_in);

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: ConnectionFailed, CommunicationFailed, DeviceUnlocked, DevFailed or NamedDevFailedList from device

15 void DeviceProxy::write_attribute(DeviceAttribute&)

Write a single attribute. To insert the value to write you have to use the operator of the class DeviceAttribute which corresponds to the data type of the attribute. NOTE: There is no automatic type conversion from the user type to the attribute native type e.g. if an attribute expects a short you cannot insert it as a double (this will throw an exception) you have to insert it as a short. See example above.
Exception: ConnectionFailed, CommunicationFailed, DeviceUnlocked, DevFailed from device

16 DeviceAttribute DeviceProxy::write_read_attribute(DeviceAttribute&)

Write then read a single attribute in a single network call. By default (serialisation by device), the execution of this call in the server can't be interrupted by other clients. To insert/extract the value to write/read you have to use the operator of the class DeviceAttribute which corresponds to the data type of the attribute. NOTE: There is no automatic type conversion from the user type to the attribute native type e.g. if an attribute expects a short you cannot insert it as a double (this will throw an exception) you have to insert it as a short.
Exception: ConnectionFailed, CommunicationFailed, DeviceUnlocked, DevFailed from device

17 vector<DeviceAttributeHistory> *DeviceProxy::attribute_history(string &, int)

Retrieve attribute history from the attribute polling buffer. The first argument is the attribute name. The second argument is the wanted history depth. This method returns a vector of DeviceAttributeHistory types. This method allocates memory for the vector of DeviceAttributeHistory returned to the caller. It is the caller responsibility to delete this memory. Class DeviceAttributeHistory is detailed on chapter

See also chapter on Advanced Feature for all details regarding polling.

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: DeviceProxy dev = new DeviceProxy(...);
vector<DeviceAttributeHistory> *hist;
hist = dev->attribute_history(Current,5);
for (int i = 0;i < 5;i++)
{

    bool fail = (*hist)[i].has_failed();
    if (fail == false)
    {
        cout << Attribute name =  << (*hist)[i].get_name() << endl;
        cout << Attribute quality factor =  << (*hist)[i].get_quality() << endl;
        long value;
        (*hist)[i] >> value;
        cout << Current =  << value << endl;
    }
    else
    {
        cout << Attribute failed ! << endl;
        cout << Error level 0 desc =  << ((*hist)[i].get_err_stack())[0].desc << endl;
    }
    cout << Date =  << (*hist)[i].get_date().tv_sec << endl;
}
delete hist;

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: NonSupportedFeature, ConnectionFailed, CommunicationFailed, DevFailed from device

18 vector<DeviceAttributeHistory> DeviceProxy::attribute_history(const char , int)

Idem previous call

5 Asynchronous command oriented methods

1 long DeviceProxy::command_inout_asynch(string &name, bool forget)

Execute asynchronously (polling model) a command on a device which takes no input argument. The last argument is a fire and forget flag. If this flag is set to true, this means that the client does not care at all about the server answer and will even not try to get it. A false default value is provided. Please, note that device re-connection will not take place (in case it is needed) if the fire and forget mode is used. Therefore, an application using only fire and forget requests is not able to automatically re-connnect to device. This call returns an asynchronous call identifier which is needed to get the command result.
Exception: ConnectionFailed

2 long DeviceProxy::command_inout_asynch(const char *name, bool forget)

Idem previous call

3 long DeviceProxy::command_inout_asynch(string &name, DeviceData &argin, bool forget)

Execute asynchronously (polling model) a command on a device. Input arguments are passed in a DeviceData object (see following chapters on how to insert data into DeviceData object). The last argument is a fire and forget flag. If this flag is set to true, this means that the client does not care at all about the server answer and will even not try to get it. A false default value is provided. Please, note that device re-connection will not take place (in case it is needed) if the fire and forget mode is used. Therefore, an application using only fire and forget requests is not able to automatically re-connnect to device. This call returns an asynchronous call identifier which is needed to get the command result.
Exception: ConnectionFailed

4 long DeviceProxy::command_inout_asynch(const char *name, Devicedata &argin, bool forget)

Idem previous call

5 DeviceData DeviceProxy::command_inout_reply(long id)

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

:         Tango::DeviceProxy dev(...);
        long asyn_id;
        asyn_id = dev.command_inout_asynch(MyCmd);
        ...
        ...
        ...
        Tango::DeviceData arg;
        try
        {
                arg = dev.command_inout_reply(asyn_id);
        }
        catch(Tango::AsynReplyNotArrived)
        {
                cerr << Command not arrived ! << endl;
        }
        catch (Tango::DevFailed &e)
        {
                Tango::Except::print_exception(e);
        }

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: AsynCall, AsynReplyNotArrived, CommunicationFailed, DevFailed from device

6 DeviceData DeviceProxy::command_inout_reply(long id, long timeout)

Check if the answer of an asynchronous command_inout is arrived (polling model). id is the asynchronous call identifier. If the reply is arrived and if it is a valid reply, it is returned to the caller in a DeviceData object. If the reply is an exception, it is re-thrown by this call. If the reply is not yet arrived, the call will wait (blocking the process) for the time specified in timeout. If after timeout milliseconds, the reply is still not there, an exception is thrown. If timeout is set to 0, the call waits until the reply arrived.
Exception: AsynCall, AsynReplyNotArrived, CommunicationFailed, DevFailed from device

7 void DeviceProxy::command_inout_asynch(string &name, CallBack &cb)

Execute asynchronously (callback model) a command on a device which takes no input argument. The last argument is a reference to a callback object. This callback object should be an instance of a user class inheriting from the Tango::CallBack class with the cmd_ended() method overloaded.
Exception: ConnectionFailed

8 void DeviceProxy::command_inout_asynch(const char *name, CallBack &cb)

Idem previous call

9 void DeviceProxy::command_inout_asynch(string &name, DeviceData &argin, CallBack &cb)

Execute asynchronously (callback model) a command on a device. Input arguments are passed in a DeviceData object (see following chapters on how to insert data into DeviceData object). The last argument is a reference to a callback object. This callback object should be an instance of a user class inheriting from the Tango::CallBack class with the cmd_ended() method overloaded.
Exception: ConnectionFailed

10 void DeviceProxy::command_inout_asynch(const char *name, DeviceData &argin, Callback &cb)

Idem previous call

6 Asynchronous attribute related methods

1 long DeviceProxy::read_attribute_asynch(string &name)

Read asynchronously (polling model) a single attribute. This call returns an asynchronous call identifier which is needed to get the attribute value.
Exception: ConnectionFailed

2 long DeviceProxy::read_attribute_asynch(const char *name)

Idem previous call

3 long DeviceProxy::read_attributes_asynch(vector<string> &names)

Read asynchronously (polling model) the list of specified attributes. This call returns an asynchronous call identifier which is needed to get attributes value.
Exception: ConnectionFailed

4 DeviceAttribute *DeviceProxy::read_attribute_reply(long id)

Check if the answer of an asynchronous read_attribute is arrived (polling model). id is the asynchronous call identifier. If the reply is arrived and if it is a valid reply, it is returned to the caller in a DeviceAttribute object. If the reply is an exception, it is re-thrown by this call. An exception is also thrown in case of the reply is not yet arrived. To extract attribute value, you have to use the operator of the class DeviceAttribute which corresponds to the data type of the attribute. NOTE: There is no automatic type conversion from the attribute native type to user type e.g. if an attribute returns a short you cannot extract it as a double, you have to extract it as a short. Memory has been allocated for the DeviceAttribute object returned to the caller. This is the caller responsibility to delete this memory.
Exception: AsynCall, AsynReplyNotArrived, CommunicationFailed, DevFailed from device

5 DeviceAttribute *DeviceProxy::read_attribute_reply(long id, long timeout)

Check if the answer of an asynchronous read_attribute is arrived (polling model). id is the asynchronous call identifier. If the reply is arrived and if it is a valid reply, it is returned to the caller in a DeviceAttribute object. If the reply is an exception, it is re-thrown by this call. If the reply is not yet arrived, the call will wait (blocking the process) for the time specified in timeout. If after timeout milliseconds, the reply is still not there, an exception is thrown. If timeout is set to 0, the call waits until the reply arrived. To extract attribute value, you have to use the operator of the class DeviceAttribute which corresponds to the data type of the attribute. NOTE: There is no automatic type conversion from the attribute native type to user type e.g. if an attribute returns a short you cannot extract it as a double, you have to extract it as a short. Memory has been allocated for the DeviceAttribute object returned to the caller. This is the caller responsibility to delete this memory.
Exception: AsynCall, AsynReplyNotArrived, CommunicationFailed, DevFailed from device

6 vector<DeviceAttribute> *DeviceProxy::read_attributes_reply(long id)

Check if the answer of an asynchronous read_attributes is arrived (polling model). id is the asynchronous call identifier. If the reply is arrived and if it is a valid reply, it is returned to the caller in a vector<DeviceAttribute>. If the reply is an exception, it is re-thrown by this call. An exception is also thrown in case of the reply is not yet arrived. To extract attribute value, you have to use the operator of the class DeviceAttribute which corresponds to the data type of the attribute. NOTE: There is no automatic type conversion from the attribute native type to user type e.g. if an attribute returns a short you cannot extract it as a double, you have to extract it as a short. Memory has been allocated for the vector<DeviceAttribute> object returned to the caller. This is the caller responsibility to delete this memory.
Exception: AsynCall, AsynReplyNotArrived, CommunicationFailed, DevFailed from device

7 vector<DeviceAttribute> *DeviceProxy::read_attributes_reply(long id, long timeout)

Check if the answer of an asynchronous read_attributes is arrived (polling model). id is the asynchronous call identifier. If the reply is arrived and if it is a valid reply, it is returned to the caller in a vector<DeviceAttribute>. If the reply is an exception, it is re-thrown by this call. If the reply is not yet arrived, the call will wait (blocking the process) for the time specified in timeout. If after timeout milliseconds, the reply is still not there, an exception is thrown. If timeout is set to 0, the call waits until the reply arrived. To extract attribute value, you have to use the operator of the class DeviceAttribute which corresponds to the data type of the attribute. NOTE: There is no automatic type conversion from the attribute native type to user type e.g. if an attribute returns a short you cannot extract it as a double, you have to extract it as a short. Memory has been allocated for the vector<DeviceAttribute> object returned to the caller. This is the caller responsibility to delete this memory.
Exception: AsynCall, AsynReplyNotArrived, CommunicationFailed, DevFailed from device

8 long DeviceProxy::write_attribute_asynch(DeviceAttribute &argin)

Write asynchronously (polling model) a single attribute. To insert the value to write you have to use the operator of the class DeviceAttribute which corresponds to the data type of the attribute. NOTE: There is no automatic type conversion from the user type to the attribute native type e.g. if an attribute expects a short you cannot insert it as a double (this will throw an exception) you have to insert it as a short. This call returns an asynchronous call identifier which is needed to get the server reply.
Exception: ConnectionFailed

9 long DeviceProxy::write_attributes_asynch(vector<DeviceAttribute> &argin)

Write asynchronously (polling model) the specified attributes. To insert the value to write you have to use the operator of the class DeviceAttribute which corresponds to the data type of the attribute. NOTE: There is no automatic type conversion from the user type to the attribute native type e.g. if an attribute expects a short you cannot insert it as a double (this will throw an exception) you have to insert it as a short. This call returns an asynchronous call identifier which is needed to get the server reply.
Exception: ConnectionFailed

10 void DeviceProxy::write_attribute_reply(long id)

Check if the answer of an asynchronous write_attribute is arrived (polling model). id is the asynchronous call identifier. If the reply is arrived and if it is a valid reply, the call returned. If the reply is an exception, it is re-thrown by this call. An exception is also thrown in case of the reply is not yet arrived.
Exception: AsynCall, AsynReplyNotArrived, CommunicationFailed, DevFailed from device

11 void DeviceProxy::write_attribute_reply(long id, long timeout)

Check if the answer of an asynchronous write_attribute is arrived (polling model). id is the asynchronous call identifier. If the reply is arrived and if it is a valid reply, the call returned. If the reply is an exception, it is re-thrown by this call. If the reply is not yet arrived, the call will wait (blocking the process) for the time specified in timeout. If after timeout milliseconds, the reply is still not there, an exception is thrown. If timeout is set to 0, the call waits until the reply arrived.
Exception: AsynCall, AsynReplyNotArrived, CommunicationFailed, DevFailed from device

12 void DeviceProxy::write_attributes_reply(long id)

Check if the answer of an asynchronous write_attributes is arrived (polling model). id is the asynchronous call identifier. If the reply is arrived and if it is a valid reply, the call returned. If the reply is an exception, it is re-thrown by this call. An exception is also thrown in case of the reply is not yet arrived.
Exception: AsynCall, AsynReplyNotArrived, CommunicationFailed, DevFailed from device

13 void DeviceProxy::write_attributes_reply(long id, long timeout)

Check if the answer of an asynchronous write_attributes is arrived (polling model). id is the asynchronous call identifier. If the reply is arrived and if it is a valid reply, the call returned. If the reply is an exception, it is re-thrown by this call. If the reply is not yet arrived, the call will wait (blocking the process) for the time specified in timeout. If after timeout milliseconds, the reply is still not there, an exception is thrown. If timeout is set to 0, the call waits until the reply arrived.
Exception: AsynCall, AsynReplyNotArrived, CommunicationFailed, DevFailed from device

14 void DeviceProxy::read_attribute_asynch(string &name, CallBack &cb)

Read asynchronously (callback model) a single attribute. The last argument is a reference to a callback object. This callback object should be an instance of a user class inheriting from the Tango::CallBack class with the attr_read() method overloaded.
Exception: ConnectionFailed

15 void DeviceProxy::read_attribute_asynch(const char *name, CallBack &cb)

Idem previous call

16 void DeviceProxy::read_attributes_asynch(vector<string> &names, CallBack &cb)

Read asynchronously (callback model) an attribute list. The last argument is a reference to a callback object. This callback object should be an instance of a user class inheriting from the Tango::CallBack class with the attr_read() method overloaded.
Exception: ConnectionFailed

17 void DeviceProxy::write_attribute_asynch(DeviceAttribute &argin, CallBack &cb)

Write asynchronously (callback model) a single attribute. The last argument is a reference to a callback object. This callback object should be an instance of a user class inheriting from the Tango::CallBack class with the attr_written() method overloaded.
Exception: ConnectionFailed

18 void DeviceProxy::write_attributes_asynch(vector<DeviceAttribute> &argin, CallBack &cb)

Write asynchronously (callback model) an attribute list. The last argument is a reference to a callback object. This callback object should be an instance of a user class inheriting from the Tango::CallBack class with the attr_written() method overloaded.
Exception: ConnectionFailed

7 Miscellaneous asynchronous related methods

1 long DeviceProxy::pending_asynch_call(asyn_req_type req)

Return number of device asynchronous pending requests. The input parameter is an enumeration with three values which are:

[POLLING] : Returns only device polling model asynchronous request number
[CALLBACK] : Returns only device callback model asynchronous request number
[ALL_ASYNCH] : Returns device asynchronous request number

Exception: None

2 void DeviceProxy::get_asynch_replies()

Fire callback methods for device asynchronous requests with already arrived replied. Returns immediately if there is no replies already arrived or if there is no asynchronous request for the device. Example :

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: class MyCallBack: Tango::CallBack
{
public:
   MyCallback(double d):data(d) {};
   virtual void cmd_ended(Tango::CmdDoneEvent *);

private:
   double data;
};

void MyCallBack::cmd_ended(Tango CmdDoneEvent *cmd)
{
   if (cmd->err == true)
      Tango::Except::print_error_stack(cmd->errors);
   else
   {
      short cmd_result;
      cmd->argout >> cmd_result;
      cout << Command result =  << cmd_result << endl;
      cout << Callback personal data =  << data << endl;
   }
}

int main(int argc, char *argv[])
{
   ....
   ....
   Tango::DeviceProxy dev(...);
   double my_data = ...;
   MyCallBack cb(my_data);

   dev.command_inout_asynch(MyCmd,cb);
   ...
   ...
   ...
   dev.get_asynch_replies();
   ...
   ...
}

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: None, all errors are reported using the err and errors fields of the parameter passed to the callback method. See chapter

for details.

3 void DeviceProxy::get_asynch_replies(long timeout)

Fire callback methods for device asynchronous requests (command and attributes) with already arrived replied. Wait and block the caller for timeout milliseconds if they are some device asynchronous requests which are not yet arrived. Returns immediately if there is no asynchronous request for the device. If timeout is set to 0, the call waits until all the asynchronous requests sent to the device has received a reply.
Exception: AsynReplyNotArrived. All other errors are reported using the err and errors fields of the object passed to the callback methods. See chapter

for details.

4 void DeviceProxy::cancel_asynch_request(long id)

Cancel a pending asynchronous request. id is the asynchronous call identifier. This is a call local to the client. It simply allows the caller not to get the answer of the asynchronous request. It does not interrupt the call execution on the remote device.
Exception: AsynCall

5 void DeviceProxy::cancel_all_polling_asynch_request()

Cancel all pending polling asynchronous requests. This is a call local to the client. It simply allows the caller not to get the answers of the asynchronous requests. It does not interrupt the call execution on the remote devices.

8 Polling related methods

1 bool DeviceProxy::is_command_polled(string &cmd_name)

Returns true if the command cmd_name is polled. Otherwise, returns false.

2 bool DeviceProxy::is_command_polled(const char *cmd_name)

Idem previous call

3 bool DeviceProxy::is_attribute_polled(string &attr_name)

Returns true if the attribute attr_name is polled. Otherwise, returns false.

4 bool Deviceproxy::is_attribute_polled(const char *attr_name)

Idem previous call

5 int DeviceProxy::get_command_poll_period(string &cmd_name)

Returns the command cmd_name polling period in mS. If the command is not polled, it returns 0.

6 int DeviceProxy::get_command_poll_period(const char *cmd_name)

Idem previous call

7 int DeviceProxy::get_attribute_poll_period(string &attr_name)

Returns the attribute attr_name polling period in mS. If the attribute is not polled, it returns 0.

8 int Deviceproxy::get_attribute_poll_period(const char *attr_name)

Idem previous call

9 vector<string> *DeviceProxy::polling_status()

Returns the device polling status. There is one string for each polled command/attribute. Each string is multi-line string with :

The attribute/command name
The attribute/command polling period (in mS)
The attribute/command polling ring buffer depth
The time needed for the last command/attribute execution (in mS)
The time since data in the ring buffer has not been updated
The delta time between the last records in the ring buffer
The exception parameters in case of the last command/attribute execution failed

This method allocates memory for the vector of string(s) returned to the caller. It is the caller responsibility to delete this memory.

10 void DeviceProxy::poll_command(string &cmd_name,int period)

Add the command cmd_name to the list of polled command. The polling period is specified by period (in mS). If the command is already polled, this method will update the polling period according to period.

11 void DeviceProxy::poll_command(const char *cmd_name, int period)

Idem previous call

12 void DeviceProxy::poll_attribute(string &attr_name, int period)

Add the attribute attr_name to the list of polled attributes. The polling period is specified by period (in mS). If the attribute is already polled, this method will update the polling period according to period.

13 void DeviceProxy::poll_attribute(const char *attr_name, int period)

Idem previous call

14 void DeviceProxy::stop_poll_command(string &cmd_name)

Remove command cmd_name from the list of polled command.

15 void DeviceProxy::stop_poll_command(const char *cmd_name)

Idem previous call

16 void DeviceProxy::stop_poll_attribute(string &attr_name)

Remove attribute attr_name from the list of polled attributes.

17 void DeviceProxy::stop_poll_attribute(const char *attr_name)

Idem previous call

9 Event related methods

1 int DeviceProxy::subscribe_event(const string &attribute, EventType event, CallBack *cb)

The client call to subscribe for event reception in the push model. The client implements a callback method which is triggered when the event is received. Filtering is done based on the event type. For example when reading the state and the reason specified is change the event will be fired only when the state changes. Events consist of an attribute name and the event reason. A standard set of reasons are implemented by the system, additional device specific reasons can be implemented by device servers programmers.
The attribute parameter is the device attribute name which will be sent as an event e.g. ``current'', event parameter is the event reason and must be on the enumerated values:

Tango::CHANGE_EVENT
Tango::PERIODIC_EVENT
Tango::ARCHIVE_EVENT
Tango::ATTR_CONF_EVENT
Tango::DATA_READY_EVENT
Tango::USER_EVENT

cb is a pointer to a class inheriting from the Tango CallBack class and implementing a push_event() method.
The subscribe_event() call returns an event id which has to be specified when unsubscribing from this event. Please, note that the cb parameter is a pointer. The lifetime of the pointed to object must at least be equal to the time when events are requested because only the pointer is stored into the event machinery. The same thing is true for the DeviceProxy instance on which the subscribe_event() method is called.
Exception: EventSystemFailed
Note: For releases prior to Tango 8, a similar call with a forth argument (const vector<string> &filters) was available. This extra argument gave the user a way to define extra event filtering. For compatibility reason, this call still exist but the extra filtering features is not implemented.

2 int DeviceProxy::subscribe_event(const string &attribute, EventType event, CallBack *cb, bool stateless)

This subscribe event method has the same functionality as described in the last section. It adds an additional flag called stateless. When the stateless flag is set to false, an exception will be thrown when the event subscription encounters a problem.
With the stateless flag set to true, the event subscription will always succeed, even if the corresponding device server is not running. The keep alive thread will try every 10 seconds to subscribe for the specified event. At every subscription retry, a callback is executed which contains the corresponding exception.
Exception: EventSystemFailed
Note: For releases prior to Tango 8, a similar call with a fifth argument (const vector<string> &filters) was available. This extra argument gave the user a way to define extra event filtering and it was the forth argument in the argument list. For compatibility reason, this call still exist but the extra filtering features is not implemented.

3 int DeviceProxy::subscribe_event(const string &attribute, EventType event, int event_queue_size, bool stateless)

Event reception buffer size = 1 : The client is interested only in the value of the last event received. All other events that have been received since the last reading are discarded.
Event reception buffer size > 1 : The client has chosen to keep an event history of a given size. When more events arrive since the last reading, older events will be discarded.
Event reception buffer size = ALL_EVENTS : The client buffers all received events. The buffer size is unlimited and only restricted by the available memory for the client.

All other parameters are similar to the descriptions given in the last two sections.
Exception: EventSystemFailed
Note: For releases prior to Tango 8, a similar call with a fifth argument (const vector<string> &filters) was available. This extra argument gave the user a way to define extra event filtering and it was the forth argument in the argument list. For compatibility reason, this call still exist but the extra filtering features is not implemented.

4 void DeviceProxy::unsubscribe_event(int event_id)

Unsubscribe a client from receiving the event specified by event_id. event_id is the event identifier returned by the DeviceProxy::subscribe_event() method.
Exception: EventSystemFailed

5 void DeviceProxy::get_events(int event_id, CallBack *cb)

The method extracts all waiting events from the event reception buffer and executes the callback method cb for every event. During event subscription the client must have chosen the pull model for this event. event_id is the event identifier returned by the DeviceProxy::subscribe_event() method.
Exception: EventSystemFailed

6 void DeviceProxy::get_events(int event_id, EventDataList &event_list)

The method extracts all waiting events from the event reception buffer. The returned event_list is a vector of EventData pointers. The EventData object contains the event information as for the callback methods.
During event subscription the client must have chosen the pull model for this event. event_id is the event identifier returned by the DeviceProxy::subscribe_event() method.
Exception: EventSystemFailed

7 void DeviceProxy::get_events(int event_id, AttrConfEventDataList &event_list)

The method extracts all waiting attribute configuration events from the event reception buffer. The returned event_list is a vector of AttrConfEventData pointers. The AttrConfEventData object contains the event information as for the callback methods.
During event subscription the client must have chosen the pull model for this event. event_id is the event identifier returned by the DeviceProxy::subscribe_event() method.
Exception: EventSystemFailed

8 void DeviceProxy::get_events(int event_id, DataReadyEventDataList &event_list)

The method extracts all waiting attribute configuration events from the event reception buffer. The returned event_list is a vector of DataReadyEventData pointers. The DataReadyEventData object contains the event information as for the callback methods.
During event subscription the client must have chosen the pull model for this event. event_id is the event identifier returned by the DeviceProxy::subscribe_event() method.
Exception: EventSystemFailed

9 int DeviceProxy::event_queue_size(int event_id)

Returns the number of stored events in the event reception buffer. After every call to DeviceProxy:get_events(), the event queue size is 0.
During event subscription the client must have chosen the pull model for this event. event_id is the event identifier returned by the DeviceProxy::subscribe_event() method.
Exception: EventSystemFailed

10 TimeVal DeviceProxy::get_last_event_date(int event_id)

Returns the arrival time of the last event stored in the event reception buffer. After every call to DeviceProxy:get_events(), the event reception buffer is empty. In this case an exception will be returned.
During event subscription the client must have chosen the pull model for this event. event_id is the event identifier returned by the DeviceProxy::subscribe_event() method.
Exception: EventSystemFailed

11 bool DeviceProxy::is_event_queue_empty(int event_id)

Returns true when the event reception buffer is empty.
During event subscription the client must have chosen the pull model for this event. event_id is the event identifier returned by the DeviceProxy::subscribe_event() method.
Exception: EventSystemFailed

10 Property related methods

1 void DeviceProxy::get_property (string&, DbData&)

Get a single property for a device. The property to get is specified as a string. Refer to DbDevice::get_property() and DbData sections below for details on the DbData type.
Exception: NonDbDevice, ConnectionFailed (with database), CommunicationFailed (with database), DevFailed from database device

2 void DeviceProxy::get_property (vector<string>&, DbData&)

Get a list of properties for a device. The properties to get are specified as a vector of strings. Refer to DbDevice::get_property() and DbData sections below for details on the DbData type.
Exception: NonDbDevice, ConnectionFailed (with database), CommunicationFailed (with database), DevFailed from database device

3 void DeviceProxy::get_property(DbData&)

Get property(ies) for a device. Properties to get are specified using the DbData type. Refer to DbDevice::get_property() and DbData sections below for details.
Exception: NonDbDevice, ConnectionFailed (with database), CommunicationFailed (with database), DevFailed from database device

4 void DeviceProxy::put_property(DbData&)

Put property(ies) for a device. Properties to put are specified using the DbData type. Refer to DbDevice::put_property() and DbData sections below for details.
Exception: NonDbDevice, ConnectionFailed (with database), CommunicationFailed (with database), DevFailed from database device

5 void DeviceProxy::delete_property (string&)

Delete a single property for a device. The property to delete is specified as a string.
Exception: NonDbDevice, ConnectionFailed (with database), CommunicationFailed (with database), DevFailed from database device

6 void DeviceProxy::delete_property (vector<string>&)

Delete a list of properties for a device. The properties to delete are specified as a vector of strings.
Exception: NonDbDevice, ConnectionFailed (with database), CommunicationFailed (with database), DevFailed from database device

7 void DeviceProxy::delete_property(DbData&)

Delete property(ies) for a device. Properties to delete are specified using the DbData type. Refer to DbDevice::get_property() and DbData sections below for details.
Exception: NonDbDevice, ConnectionFailed (with database), CommunicationFailed (with database), DevFailed from database device

8 void DeviceProxy::get_property_list(const string &filter,vector<string> &prop_list)

Get the list of property names for the device. The parameter filter allows the user to filter the returned name list. The wildcard character is '*'. Only one wildcard character is allowed in the filter parameter. The name list is returned in the vector of strings passed as the method second argument.
Exception: NonDbDevice, WrongNameSyntax, ConnectionFailed (with database), CommunicationFailed (with database), DevFailed from database device

11 Logging related methods

1 void DeviceProxy::add_logging_target(const string &target_type_target_name)

Adds a new logging target to the device. The target_type_target_name input parameter must follow the format: target_type::target_name. Supported target types are: console, file and device. For a device target, the target_name part of the target_type_target_name parameter must contain the name of a log consumer device (as defined in

). For a file target, target_name is the full path to the file to log to. If omitted, the device's name is used to build the file name (which is something like domain_family_member.log). Finally, the target_name part of the target_type_target_name input parameter is ignored in case of a console target and can be omitted.
Exception: DevFailed from device

2 void DeviceProxy::add_logging_target (const char *target_type_target_name)

Idem previous call

3 void DeviceProxy::remove_logging_target(const string &target_type_target_name)

Removes a logging target from the device's target list. The target_type_target_name input parameter must follow the format: target_type::target_name. Supported target types are: console, file and device. For a device target, the target_name part of the target_type_target_name parameter must contain the name of a log consumer device (as defined in ). For a file target, target_name is the full path to the file to remove. If omitted, the default log file is removed. Finally, the target_name part of the target_type_target_name input parameter is ignored in case of a console target and can be omitted.
If target_name is set to *, all targets of the specified target_type are removed.

4 void DeviceProxy::remove_logging_target (const char *target_type_target_name)

Idem previous call

5 vector<string> DeviceProxy::get_logging_target ()

Returns a vector of string containing the current device's logging targets. Each vector element has the following format: target_type::target_name. An empty vector is returned is the device has no logging targets.

6 int DeviceProxy::get_logging_level ()

Returns the current device's logging level (0=OFF, 1=FATAL, 2=ERROR, 3=WARNING, 4=INFO, 5=DEBUG).

7 void DeviceProxy::set_logging_level (int level)

Changes the device's logging level. (0=OFF, 1=FATAL, 2=ERROR, 3=WARNING, 4=INFO, 5=DEBUG).

12 Locking related methods

1 void DeviceProxy::lock(int lock_validity = 10)

Lock a device. The lock_validity is the time (in seconds) the lock is kept valid after the previous lock call. A default value of 10 seconds is provided and should be fine in most cases. In case it is necessary to change the lock validity, it's not possible to ask for a validity less than a minimum value set to 2 seconds. The library provided an automatic system to periodically re lock the device until an unlock call. No code is needed to start/stop this automatic re-locking system. The locking system is re-entrant. It is then allowed to call this method on a device already locked by the same process. The locking system has the following features:

It is impossible to lock the database device or any device server process admin device
Destroying a locked DeviceProxy unlocks the device
Restarting a locked device keeps the lock
It is impossible to restart a device locked by someone else
Restarting a server breaks the lock

A locked device is protected against the following calls when executed by another client:

command_inout call except for device state and status requested via command and for the set of commands defined as allowed following the definition of allowed command in the Tango control access schema.
write_attribute call
write_read_attribute call
set_attribute_config call

2 void DeviceProxy::unlock(bool force = false)

Unlock a device. If used, the method argument provides a back door on the locking system. If this argument is set to true, the device will be unlocked even if the caller is not the locker. This feature is provided for administration purpopse and should be used very carefully. If this feature is used, the locker will receive a DeviceUnlocked during the next call which is normally protected by the locking Tango system.

3 string DeviceProxy::locking_status()

This method returns a plain string describing the device locking status. This string can be:

Device <device name> is not locked in case the device is not locked
Device <device name> is locked by CPP or Python client with PID <pid> from host <host name> in case the device is locked by a CPP client
Device <device name> is locked by JAVA client class <main class> from host <host name> in case the device is locked by a JAVA client

4 bool DeviceProxy::is_locked()

Returns true if the device is locked. Otherwise, returns false.

5 bool DeviceProxy::is_locked_by_me()

Returns true if the device is locked by the caller. Otherwise, returns false (device not locked or locked by someone else)

6 bool DeviceProxy::get_locker(LockerInfo &li)

If the device is locked, this method returns true an set some locker process informations in the structure passed as argument. If the device is not locked, the method returns false. The LockerInfo structure definition is

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: typedef union
{
   pid_t           LockerPid;
   unsigned long   UUID[4];
}LockerId;

enum LockerLanguage
{
   CPP,
   JAVA
};

struct LockerInfo
{
   LockerLanguage  ll;
   LockerId        li;
   string          locker_host;
   string          locker_class;
};

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

The structure ll field is set to either CPP or JAVA depending on the locker process language. In case of CPP client, the li union is set to the locker process pid (LockerPid field). In case of Java client, it is set to the Java client UUID (Universal Uniq IDentifier) in the UUID field. The locker_host field is initialised with the host name where the locker process is running (or its IP adress as a string if it is not possiblr to get the name associated with this address). The locker_class field is set to the Java virtual machine main class name when the locker client process is written in Java. For CPP client, it is set to the string Not defined.

2 Tango::DeviceData

This is the fundamental type for sending and receiving data from device commands. The values can be inserted and extracted using the operators << and >> respectively and insert() for mixed data types. A status flag indicates if there is data in the DbDatum object or not. An additional flag allows the user to activate exceptions.

1 Constructors, assignement operators and C++11

This class has a default constructor (DeviceData()), a copy constructor (DeviceData(const DeviceData &)) and one assignement operator (DeviceData & operator=(const DeviceData &)). Nevertheless, the assignement operator and the copy constructor does not really copy the data included in the instance. For efficiency reasons, they rather move the data from one instance to another. Starting with Tango 8 and if Tango is compiled with gcc release 4.3 or above (or Windows VC 10 and above), some move semantics from C++11 has been added. This means that:

A move constructor (DeviceData(DeviceData &&)) has been added.
A move assignement operator (DeviceData & operator=(DeviceData &&)) has been added.
The classical copy constructor and assignement operator really copy the data.

2 Operators

The insert and extract operators are specified for the following C++ types :

bool
short
unsigned short
DevLong
DevULong
DevLong64
DevULong64
float
double
string
char* (insert only)
const char *
vector<unsigned char>
vector<string>
vector<short>
vector<unsigned short>
vector<DevLong>
vector<DevULong>
vector<DevLong64>
vector<DevULong64>
vector<float>
vector<double>

Operators exist for inserting and extracting the native TANGO CORBA sequence types. These can be useful for programmers who want to use the TANGO api internally in their device servers and do not want to convert from CORBA to C++ types. Insert and extract operators exist for the following types :

DevVarUCharArray * (const DevVarUCharArray * for extraction)
DevVarShortArray * (const DevVarShortArray * for extraction)
DevVarUShortArray * (const DevVarUShortArray * for extraction)
DevVarLongArray * (const DevVarLongArray * for extraction)
DevVarULongArray * (const DevVarULongArray * for extraction)
DevVarLong64Array * (const DevVarLong64Array * for extraction)
DevVarULong64Array * (const DevVarULong64Array * for extraction)
DevVarFloatArray * (const DevVarFloatArray * for extraction)
DevVarDoubleArray * (const DevVarDoubleArray * for extraction)
DevVarStringArray * (const DevVarStringArray * for extraction)
DevVarLongStringArray * (const DevVarLongStringArray * for extraction)
DevVarDoubleStringArray * (const DevVarDoubleStringArray * for extraction)

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Note :
Insertion by pointers takes full ownership of the pointed to memory. The insertion copy the data in the DeviceData object and delete the pointed to memory. Therefore, the memory is not more usable after the insertion. Also note that when using extraction by pointers, the pointed to memory is inside the DeviceData object and its lifetime is the same than the DeviceData object lifetime.

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Operators also exist for inserting TANGO CORBA sequence type by reference. The insertion copy the data into the DeviceData object. Insert operator exist for the following types :

DevVarUCharArray &
DevVarShortArray &
DevVarUShortArray &
DevVarLongArray &
DevVarULongArray &
DevVarLong64Array &
DevVarULong64Array &
DevVarFloatArray &
DevVarDoubleArray &
DevVarStringArray &
DevVarLongStringArray &
DevVarDoubleStringArray &

Additional methods exist for inserting a mixture of strings and long (Tango::DevVarLongStringArray) and string and doubles (Tango::DevVarDoubleStringArray). These are :

insert(vector<long>&, vector<string>&)
insert(vector<double>&, vector<string>&)
extract(vector<long>&, vector<string>&)
extract(vector<double>&, vector<string>&)

All the extraction methods returns a boolean set to false if the extraction has failed (empty DeviceData, wrong data type...)
Special care has been taken to avoid memory copy between the network layer and the user application. Nevertheless, C++ vector types are not the CORBA native type and one copy is unavoidable when using vectors. Using the native TANGO CORBA sequence types avoid any copy. When using these TANGO CORBA sequence types, insertion into the DeviceData object consumes the memory pointed to by the pointer. After the insertion, it is not necessary to delete the memory. It will be done by the destruction of the DeviceData object. For extraction, the pointer used for the extraction points into memory inside the DeviceData object and you should not delete it
Here is an example of creating, inserting and extracting some data type from/into DeviceData object :

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: DeviceData my_short, my_long, my_string;
DeviceData my_float_vector, my_double_vector;
string a_string;
short a_short;
DevLong a_long;
vector<float> a_float_vector;
vector<double> a_double_vector;
my_short << 100; // insert a short
my_short >> a_short; // extract a short
my_long << 1000; // insert a long
my_long >> a_long; // extract a long
my_string << string(``estas lista a bailar el tango ?''); // insert a string
my_string >> a_string; // extract a string
my_float_vector << a_float_vector // insert a vector of floats
my_float_vector >> a_float_vector; // extract a vector of floats
my_double_vector << a_double_vector; // insert a vector of doubles
my_double_vector >> a_double_vector; // extract a vector of doubles
//
// Example of memory management with TANGO sequence types without memory leaks
//
for (int i = 0;i < 10;i++)
{
    DeviceData din,dout;
    DevVarLongArray *in = new DevVarLongArray();
    in->length(2);
    (*in)[0] = 2;
    (*in)[1] = 4;
    din << in;
    try
    {
        dout = device->command_inout(``Cmd'',din);
    }
    catch(DevFailed &e)
    {
       ....
    }
    const DevVarLongArray *out;
    dout >> out;
    cout << ``Received value = `` << (*out)[0];
}

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: WrongData if requested

3 bool DeviceData::is_empty()

is_empty() is a boolean method which returns true or false depending on whether the DeviceData object contains data or not. It can be used to test whether the DeviceData has been initialized or not e.g.

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: string string_read;
DeviceData sl_read = my_device->command_inout(``ReadLine'');
if (! sl_read.is_empty())
{
sl_read >> string_read;
}
else
{
cout << `` no data read from serial line !'' << endl;
}

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: WrongData if requested

4 int DeviceData::get_type()

This method returns the Tango data type of the data inside the DeviceData object

5 void DeviceData::exceptions(bitset<DeviceData::numFlags> )

Is a method which allows the user to switch on/off exception throwing when trying to extract data from an empty DeviceData object or using a wrong data type. The default is to not throw exception. The following flags are supported :

isempty_flag - throw a WrongData exception (reason = API_EmptyDeviceData) if user tries to extract data from an empty DeviceData object
wrongtype_flag - throw a WrongData exception (reason = API_IncompatibleCmdArgumentType) if user tries to extract data with a type different than the type used for insertion

6 bitset<DeviceData::numFlags> exceptions()

Returns the whole exception flags.

7 void DeviceData::reset_exceptions(DeviceData::except_flags fl)

Resets one exception flag

8 void DeviceData::set_exceptions(DeviceData::except_flags fl)

Sets one exception flag
The following is an example of how to use these exceptions related methods

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

:      1          DeviceData da;
     2
     3          bitset<DeviceData::numFlags> bs = da.exceptions();
     4          cout << bs =  << bs << endl;
     5
     6          da.set_exceptions(DeviceData::wrongtype_flag);
     7          bs = da.exceptions();
     8
     9          cout << bs =  << bs << endl;

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

9 ostream &operator«(ostream &, DeviceData &)

Is an utility function to easily print the contents of a DeviceData object. This function knows all types which could be inserted in a DeviceData object and print them accordingly. A special string is printed if the DeviceData object is empty

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: DeviceProxy *dev = new DeviceProxy(``...'');
DeviceData out;
out = dev->command_inout(``MyCommand'');
cout << ``Command returned: '' << out << endl;

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

3 Tango::DeviceDataHistory

This is the fundamental type for receiving data from device command polling buffers. This class inherits from the Tango::DeviceData class. One instance of this class is created for each command result history. Within this class, you find the command result data or the exception parameters, a flag indicating if the command has failed when it was invoked by the device server polling thread and the date when the command was executed. For history calls, it is not possible to returns command error as exception. See chapter on Advanced Features for all details regarding device polling. On top of the methods inherited from the DeviceData class, it offers the following methods

1 bool DeviceDataHistory::has_failed()

Returns true if the corresponding command has failed when it was executed by the device server polling thread. Otherwise returns false (amazing!)
Exception: none

2 TimeVal &DeviceDataHistory::get_date()

Returns the date when the device server polling thread has executed the command.
Exception: none

3 const DevErrorList &DeviceDataHistory::get_err_stack()

Return the error stack recorded by the device server polling thread in case of the command failed when it was invoked.
Exception: none

4 ostream &operator«(ostream &, DeviceDataHistory &)

Is an utility function to easily print the contents of a DeviceDataHistory object. This function knows all types which could be inserted in a DeviceDataHistory object and print them accordingly. It also prints date and error stack in case the command returned an error.

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: DeviceProxy *dev = new DeviceProxy(``...'');
int hist_depth = 4;
vector<DeviceDataHistory> *hist;
hist = dev->command_history(``MyCommand'',hist_depth);
for (int i = 0;i < hist_depth;i++)
{
cout << (*hist)[i] << endl;
}
delete hist;

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

4 Tango::DeviceAttribute

This is the fundamental type for sending and receiving data to and from device attributes. The values can be inserted and extracted using the operators << and >> respectively and insert() for mixed data types. There are two ways to check if the extraction operator succeed :

By testing the extractor operators return value. All the extractors operator returns a boolean value set to false in case of problem.
By asking the DeviceAttribute object to throw exception in case of problem. By default, DeviceAttribute throws exception :
1. when the user try to extract data and the server reported an error when the attribute was read.
2. When the user try to extract data from an empty DeviceAttribute

1 Constructors, assignement operators

Many constructors have been written for this class. The following constructors exist :

The C++ basic constructors
1. DeviceAttribute();
2. DeviceAttribute(const DeviceAttribute&);
Constructors for scalar type with name as C++ string or const char *
1. DeviceAttribute(string &, bool);
2. DeviceAttribute(string &, short);
3. DeviceAttribute(string &, DevLong);
4. DeviceAttribute(string &, DevLong64);
5. DeviceAttribute(string &, float);
6. DeviceAttribute(string &, double);
7. DeviceAttribute(string &, unsigned char);
8. DeviceAttribute(string &, unsigned short);
9. DeviceAttribute(string &, DevULong);
10. DeviceAttribute(string &, DevULong64);
11. DeviceAttribute(string &, string &);
12. DeviceAttribute(string &, DevState);
13. DeviceAttribute(string &, DevEncoded &);
14. DeviceAttribute(const char *, bool);
15. DeviceAttribute(const char *, short);
16. DeviceAttribute(const char *, DevLong);
17. DeviceAttribute(const char *, DevLong64);
18. DeviceAttribute(const char *, float);
19. DeviceAttribute(const char *, double);
20. DeviceAttribute(const char *, unsigned char);
21. DeviceAttribute(const char *, unsigned short);
22. DeviceAttribute(const char *, DevULong);
23. DeviceAttribute(const char *, DevULong64);
24. DeviceAttribute(const char *, string &);
25. DeviceAttribute(const char *, DevState);
26. DeviceAttribute(const char *,DevEncoded &);
Constructors for C++ vector types (for spectrum attribute) with name as C++ string or const char *
1. DeviceAttribute(string &, vector<bool> &);
2. DeviceAttribute(string &, vector<short> &);
3. DeviceAttribute(string &, vector<DevLong> &);
4. DeviceAttribute(string &, vector<DevLong64> &);
5. DeviceAttribute(string &, vector<float> &);
6. DeviceAttribute(string &, vector<double> &);
7. DeviceAttribute(string &, vector<unsigned char> &);
8. DeviceAttribute(string &, vector<unsigned short> &);
9. DeviceAttribute(string &, vector<DevULong> &);
10. DeviceAttribute(string &, vector<DevULong64> &);
11. DeviceAttribute(string &, vector<string> & );
12. DeviceAttribute(string &, vector<DevState> &);
13. DeviceAttribute(const char *, vector<bool> &);
14. DeviceAttribute(const char *, vector<short> &);
15. DeviceAttribute(const char *, vector<DevLong> &);
16. DeviceAttribute(const char *, vector<DevLong64> &);
17. DeviceAttribute(const char *, vector<float> &);
18. DeviceAttribute(const char *, vector<double> &);
19. DeviceAttribute(const char *, vector<unsigned char> &);
20. DeviceAttribute(const char *, vector<unsigned short> &);
21. DeviceAttribute(const char *, vector<DevULong> &);
22. DeviceAttribute(const char *, vector<DevULong64> &);
23. DeviceAttribute(const char *, vector<string> & );
24. DeviceAttribute(const char *, vector<DevState> &);
Constructors for C++ vector types (for image attribute) with name as C++ string or const char *. These constructors have two more parameters allowing the user to define the x and y image dimensions.
1. DeviceAttribute(string &, vector<bool> &, int, int);
2. DeviceAttribute(string &, vector<short> &, int, int);
3. DeviceAttribute(string &, vector<DevLong> &, int, int);
4. DeviceAttribute(string &, vector<DevLong64> &, int, int);
5. DeviceAttribute(string &, vector<float> &, int, int);
6. DeviceAttribute(string &, vector<double> &, int, int);
7. DeviceAttribute(string &, vector<unsigned char> &, int, int);
8. DeviceAttribute(string &, vector<unsigned short> &, int, int);
9. DeviceAttribute(string &, vector<DevULong> &, int, int);
10. DeviceAttribute(string &, vector<DevULong64> &, int, int);
11. DeviceAttribute(string &, vector<string> &, int, int );
12. DeviceAttribute(string &, vector<DevState> &, int, int);
13. DeviceAttribute(const char *, vector<bool> &, int, int);
14. DeviceAttribute(const char *, vector<short> &, int, int);
15. DeviceAttribute(const char *, vector<DevLong> &, int, int);
16. DeviceAttribute(const char *, vector<DevLong64> &, int, int);
17. DeviceAttribute(const char *, vector<float> &, int, int);
18. DeviceAttribute(const char *, vector<double> &, int, int);
19. DeviceAttribute(const char *, vector<unsigned char> &, int, int);
20. DeviceAttribute(const char *, vector<unsigned short> &, int, int);
21. DeviceAttribute(const char *, vector<DevULong> &, int, int);
22. DeviceAttribute(const char *, vector<DevULong64> &, int, int);
23. DeviceAttribute(const char *, vector<string> & , int, int);
24. DeviceAttribute(const char *, vector<DevState) &, int, int);

Note that the assignement operator and the copy constructor does not really copy the data included in the instance. For efficiency reasons, they rather move the data from one instance to another. Starting with Tango 8 and if Tango is compiled with gcc release 4.3 or above (or Windows VC 10 and above), some move semantics from C++11 has been added. This means that:

A move constructor (DeviceAttribute(DeviceAttribute &&)) has been added.
A move assignement operator (DeviceAttribute & operator=(DeviceAttribute &&)) has been added.
The classical copy constructor and assignement operator really copy the data.

2 Data Extraction and Insertion : Operators and Methods

Special care has been taken to avoid memory copy between the network layer and the user application. Nevertheless, C++ vector types are not the CORBA native type and one copy is unavoidable when using vectors. Using the native TANGO CORBA sequence types in most cases avoid any copy but needs some more care about memory usage.

For insertion into DeviceAttribute instance from TANGO CORBA sequence pointers, the DeviceAttribute object takes ownership of the pointed to memory. This means that the pointed to memory will be freed when the DeviceAttribute object is destroyed or when another data is inserted into it.
The insertion into DeviceAttribute instance from TANGO CORBA sequence reference copy the data into the DeviceAttribute object.
For extraction into TANGO CORBA sequence types, the extraction method consumes the memory allocated to store the data and it is the caller responsibility to delete this memory.

As it has been done for constructors, a lot of insertors operator for classical C++ data types have been defined :

Insert operators for the following scalar C++ types :
1. bool
2. short
3. DevLong
4. DevLong64
5. float
6. double
7. unsigned char
8. unsigned short
9. DevULong
10. DevULong64
11. string
12. DevState
13. DevEncoded
14. DevString
15. const char *
Insert operators for the following C++ vector types for spectrum attributes :
1. vector<bool>
2. vector<short>
3. vector<DevLong>
4. vector<DevLong64>
5. vector<float>
6. vector<double>
7. vector<unsigned char>
8. vector<unsigned short>
9. vector<DevULong>
10. vector<DevULong64>
11. vector<string>
12. vector<DevState>
Insert methods for the DevEncoded data type
1. insert(char *&, unsigned char *&, unsigned int)
  The last argument is the size of the buffer passed to the method as its second argument
2. insert(string &, vector<unsigned char SPMamp;>)
Insert methods for the following C++ vector types for image attributes allowing the specification of the x and y image dimensions :
1. insert(vector<bool> &,int, int)
2. insert(vector<short> &,int, int)
3. insert(vector<DevLong> &,int, int)
4. insert(vector<DevLong64> &,int, int)
5. insert(vector<float> &,int, int)
6. insert(vector<double> &,int, int)
7. insert(vector<unsigned char> &,int, int)
8. insert(vector<unsigned short> &,int, int)
9. insert(vector<DevULong> &,int, int)
10. insert(vector<DevULong64> &,int, int)
11. insert(vector<string> &,int, int)
12. insert(vector<DevState> &,int, int)

Extractor operators are specified for the following C++ basic types

Extract operators for the following scalar C++ types :
1. bool
2. short
3. DevLong
4. DevLong64
5. float
6. double
7. unsigned char
8. unsigned short
9. DevULong
10. DevULong64
11. string
12. Tango::DevState
13. Tango::DevEncoded
Extract operators for the following C++ vector types for spectrum and image attributes :
1. vector<bool>
2. vector<short>
3. vector<DevLong>
4. vector<DevLong64>
5. vector<float>
6. vector<double>
7. vector<unsigned char>
8. vector<unsigned short>
9. vector<DevULong>
10. vector<DevULong64>
11. vector<string>
12. vector<DevState>
Extract methods to extract only the read value of an attribute into a C++ vector. The dimension of the read value can be read by using the methods get_dim_x() and get_dim_y() or get_r_dimension(). The methods use the same return values as the extraction operators with exceptions triggered by the exception flags:
1. bool DeviceAttribute::extract_read (vector<bool>&);
2. bool DeviceAttribute::extract_read (vector<short>&);
3. bool DeviceAttribute::extract_read (vector<DevLong>&);
4. bool DeviceAttribute::extract_read (vector<DevLong64>&);
5. bool DeviceAttribute::extract_read (vector<float>&);
6. bool DeviceAttribute::extract_read (vector<double>&);
7. bool DeviceAttribute::extract_read (vector<unsigned char>&);
8. bool DeviceAttribute::extract_read (vector<unsigned short>&);
9. bool DeviceAttribute::extract_read (vector<DevULong>&);
10. bool DeviceAttribute::extract_read (vector<DevULong64>&);
11. bool DeviceAttribute::extract_read (vector<string>&);
12. bool DeviceAttribute::extract_read (vector<DevState>&);
13. bool DeviceAttribute::extract_read(string &, vector<unsigned char> &);
Extract methods to extract only the set value of an attribute into a C++ vector. The dimension of the set value can be read by using the methods get_written_dim_x() and get_written_dim_y() or get_w_dimension(). The methods use the same return values as the extraction operators with exceptions triggered by the exception flags:
1. bool DeviceAttribute::extract_set (vector<bool>&);
2. bool DeviceAttribute::extract_set (vector<short>&);
3. bool DeviceAttribute::extract_set (vector<DevLong>&);
4. bool DeviceAttribute::extract_set (vector<DevLong64>&);
5. bool DeviceAttribute::extract_set (vector<float>&);
6. bool DeviceAttribute::extract_set (vector<double>&);
7. bool DeviceAttribute::extract_set (vector<unsigned char>&);
8. bool DeviceAttribute::extract_set (vector<unsigned short>&);
9. bool DeviceAttribute::extract_set (vector<DevULong>&);
10. bool DeviceAttribute::extract_set (vector<DevULong64>&);
11. bool DeviceAttribute::extract_set (vector<string>&);
12. bool DeviceAttribute::extract_set (vector<DevState>&);
13. bool DeviceAttribute::extract_set(string &, vector<unsigned char> &);
Special extract method for the Tango::DevEncoded data type
1. bool DeviceAttribute::extract(const char *&, unsigned char *&, unsigned int &);
  The last argument is the size of the buffer passed to the method as its second argument
2. bool DeviceAttribute::extract(string &, vector<unsigned char> &);

Operators also exist for extracting some native TANGO CORBA sequence types. These can be useful for programmers who want to use the TANGO api internally in their device servers and do not want to convert from CORBA to C++ types.

Insert operators for spectrum attribute and for the following types by pointer :
1. DevVarBooleanArray *
2. DevVarShortArray *
3. DevVarLongArray *
4. DevVarLong64Array *
5. DevVarFloatArray *
6. DevVarDoubleArray *
7. DevVarUCharArray *
8. DevVarUShortArray *
9. DevVarULongArray *
10. DevVarULong64Array *
11. DevVarStringArray *
12. DevVarStateArray *
Insert operators for spectrum attribute and for the following types by reference :
1. const DevVarBooleanArray &
2. const DevVarShortArray &
3. const DevVarLongArray &
4. const DevVarLong64Array &
5. const DevVarFloatArray &
6. const DevVarDoubleArray &
7. const DevVarUCharArray &
8. const DevVarUShortArray &
9. const DevVarULongArray &
10. const DevVarULong64Array &
11. const DevVarStringArray &
12. const DevVarStateArray &
Insert methods for image attribute and pointers. These method allow the programmer to define the x and y image dimensions. The following methods are defined :
1. insert(DevVarBooleanArray *, int , int )
2. insert(DevVarShortArray *, int , int )
3. insert(DevVarLongArray *, int , int )
4. insert(DevVarLong64Array *, int, int )
5. insert(DevVarFloatArray *, int , int )
6. insert(DevVarDoubleArray *, int , int )
7. insert(DevVarUCharArray *, int , int )
8. insert(DevVarUShortArray *, int , int )
9. insert(DevVarULongArray *, int , int )
10. insert(DevVarULong64Array *, int, int )
11. insert(DevVarStringArray *, int , int )
12. insert(DevVarStateArray *, int, int)
Insert methods for image attribute and reference. These method allow the programmer to define the x and y image dimensions. The following methods are defined :
1. insert(const DevVarBooleanArray &, int , int )
2. insert(const DevVarShortArray &, int , int )
3. insert(const DevVarLongArray &, int , int )
4. insert(const DevVarLong64Array &, int, int )
5. insert(const DevVarFloatArray &, int , int )
6. insert(const DevVarDoubleArray &, int , int )
7. insert(const DevVarUCharArray &, int , int )
8. insert(const DevVarUShortArray &, int , int )
9. insert(const DevVarULongArray &, int , int )
10. insert(const DevVarULong64Array &, int, int )
11. insert(const DevVarStringArray &, int , int )
12. insert(const DevVarStateArray &, int, int )
Extract operators for the following types :
1. DevVarBooleanArray *
2. DevVarShortArray *
3. DevVarLongArray *
4. DevVarLong64Array *
5. DevVarFloatArray *
6. DevVarDoubleArray *
7. DevVarUCharArray *
8. DevVarUShortArray *
9. DevVarULongArray *
10. DevVarULong64Array *
11. DevVarStringArray *
12. DevVarStateArray *
13. DevVarEncodedArray *

Here is an example of creating, inserting and extracting some DeviceAttribute types :

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: DeviceAttribute my_short, my_long, my_string;
DeviceAttribute my_float_vector, my_double_vector;
string a_string;
short a_short;
DevLong a_long;
vector<float> a_float_vector;
vector<double> a_double_vector;
my_short << 100; // insert a short
my_short >> a_short; // extract a short
my_long << 1000; // insert a long
my_long >> a_long; // extract a DevLong
my_string << string(estas lista a bailar el tango ?); // insert a string
my_string >> a_string; // extract a string
my_float_vector << a_float_vector // insert a vector of floats
my_float_vector >> a_float_vector; // extract a vector of floats
my_double_vector << a_double_vector; // insert a vector of doubles
my_double_vector >> a_double_vector; // extract a vector of doubles
//
// Extract read and set value of an attribute separately
// and get their dimensions
//
vector<float> r_float_vector, w_float_vector;
my_float_vector.extract_read (r_float_vector) // extract read values
int dim_x = my_float_vector.get_dim_x();      // get x dimension
int dim_y = my_float_vector.get_dim_y();      // get y dimension
my_float_vector.extract_set  (w_float_vector) // extract set values
int w_dim_x = my_float_vector.get_written_dim_x();  // get x dimension
int W_dim_y = my_float_vector.get_written_dim_y();  // get y dimension
//
// Example of memory management with TANGO sequence types without memory leaks
//
for (int i = 0;i < 10;i++)
{
    DeviceAttribute da;
    DevVarLongArray *out;
    try
    {
        da = device->read_attribute(Attr);
        da >> out;
    }
    catch(DevFailed &e)
    {
       ....
    }
    cout << Received value =  << (*out)[0];
    delete out;
}

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: WrongData if requested

3 bool DeviceAttribute::is_empty()

is_empty() is a boolean method which returns true or false depending on whether the DeviceAttribute object contains data or not. It can be used to test whether the DeviceAttribute has been initialized or not e.g.

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: string parity;
DeviceAttribute sl_parity = my_device->read_attribute(parity);
if (! sl_read.is_empty())
{
sl_parity >> parity;
}
else
{
cout << no parity attribute defined for serial line ! << endl;
}

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: WrongData if requested

4 void DeviceAttribute::exceptions(bitset<DeviceAttribute::numFlags>)

Is a method which allows the user to switch on/off exception throwing when trying to extract data from an empty DeviceAttribute object or with a wrong data type. The following flags are supported :

isempty_flag - throw a WrongData exception (reason= API_EmptyDeviceAttribute) if user tries to extract data from an empty DeviceAttribute object. By default, this flag is set.
wrongtype_flag - throw a WrongData exception (reason = API_IncompatibleAttrArgumentType) if user tries to extract data with a type different than the type used for insertion. By default, this flag is not set.
failed_flag - throw an exception when the user try to extract data from the DeviceAttribute object and an error was reported by the server when the user try to read the attribute. The type of the exception thrown is the type of the error reported by the server. By default, this flag is set.
unknown_format_flag - throw an exception when the user try to get the attribute data format from the DeviceAttribute object when this information is not yet available. This information is available only after the read_attribute call has been sucessfully executed. The type of the exception thrown is WrongData exception (reason = API_EmptyDeviceAttribute). By default, this flag is not set.

5 bitset<DeviceAttribute::numFlags> exceptions()

Return the whole exception flags.

6 void DeviceAttribute::reset_exceptions(DeviceAttribute::except_flags fl)

Reset one exception flag

7 void DeviceAttribute::set_exceptions(DeviceAttribute::except_flags fl)

Set one exception flag
The following is an example of how to use these exceptions related methods

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

:      1  DeviceAttribute da;
     2
     3  bitset<DeviceAttribute::numFlags> bs = da.exceptions();
     4  cout << bs =  << bs << endl;
     5
     6  da.set_exceptions(DeviceAttribute::wrongtype_flag);
     7  bs = da.exceptions();
     8
     9  cout << bs =  << bs << endl;

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

8 bool DeviceAttribute::has_failed()

Returns a boolean set to true if the server report an error when the attribute was read.

9 const DevErrorList &DeviceAttribute::get_err_stack()

Returns the error stack reported by the server when the attribute was read.
The following is an example of the three available ways to get data out of a DeviceAttribute object.

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

:      1  DeviceAttribute da;
     2  vector<short> attr_data;
     3
     4  try
     5  {
     6      da = device->read_attribute(Attr);
     7      da >> attr_data;
     8  }
     9  catch (DevFailed &e)
    10  {
    11      ....
    12  }
    13
    14
    15  ------------------------------------
    16
    17  DeviceAttribute da;
    18  vector<short> attr_data;
    19
    20  da.reset_exceptions(DeviceAttribute::failed_flag);
    21
    22  try
    23  {
    24      da = device->read_attribute(Attr);
    25  }
    26  catch (DevFailed &e)
    27  {
    28      .....
    29  }
    30
    31  if (!(da >> attr_data))
    32  {
    33      DevErrorList &err = da.get_err_stack();
    34      .....
    35  }
    36  else
    37  {
    38      .....
    39  }
    40
    41  -----------------------------------
    42
    43  DeviceAttribute da;
    44  vector<short> attr_data;
    45
    46  try
    47  {
    48      da = device->read_attribute(Attr);
    49  }
    50  catch (DevFailed &e)
    51  {
    52      ......
    53  }
    54
    55  if (da.has_failed())
    56  {
    57      DevErrorList &err = da.get_err_stack();
    58      ....
    59  }
    60  else
    61  {
    62      da >> attr_data;
    63  }

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

The first way is coded between lines 1 and 13. It uses the default behaviour of the DeviceAttribute object which is to throw an exception when the user try to extract data when the server reports an error when the attribute was read. The second way is coded between line 17 and 40. The DeviceAttribute object now does not throw failed exception any more and the return value of the extractor operator is checked. The third way is coded between line 43 and 63. In this case, the attribute data validity is checked before trying to extract them.

10 string &DeviceAttribute::get_name()

Returns the name of the attribute

11 void DeviceAttribute::set_name(string &)

Sets attribute name

12 void DeviceAttribute::set_name(const char *)

Sets attribute name

13 AttrQuality &DeviceAttribute::get_quality()

Returns the quality of the attribute: an enumerate type which can be one of {ATTR_VALID, ATTR_INVALID, ATTR_ALARM, ATTR_CHANGING or ATTR_WARNING}.

14 int DeviceAttribute::get_dim_x()

Returns the attribute read x dimension

15 int DeviceAttribute::get_dim_y()

Returns the attribute read y dimension

16 int DeviceAttribute::get_written_dim_x()

Returns the attribute write x dimension

17 int DeviceAttribute::get_written_dim_y()

Returns the attribute write y dimension

18 AttributeDimension DeviceAttribute::get_r_dimension()

Returns the attribute read dimension

19 AttributeDimension DeviceAttribute::get_w_dimension()

Returns the attribute write dimension

20 long DeviceAttribute::get_nb_read()

Returns the number of read values

21 long DeviceAttribute::get_nb_written()

Returns the number of written values. Here is an example of these last methods usage.

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: 1  DeviceAttribute da;
2  vector<short> attr_data;
3
4  try
5  {
6     da = device->read_attribute(Attr);
7     da >> attr_data;
8  }
9  catch (DevFailed &e)
10  {
11     ....
12  }
13
14  long read = da.get_nb_read();
15  long written = da.get_nb_written();
16  size_t size = attr_data.size();
17
18  for (long i = 0;i < read;i++)
19     cout << Read value  << i+1 <<  =  << attr_data[i] <<  endl;
20
21  int ind;
22  for (long j = 0; j < written;j++)
23  {
24     size == 1 ? ind = j : ind = j + read;
25     cout << Last written value  << j+1 <<  =  << attr_data[ind] << endl;
26  }

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Line 24 is needed to cover the case of scalar write attribute where only one value is returned but both get_nb_read() and get_nb_written() methods return 1.

22 TimeVal &DeviceAttribute::get_date()

Returns a reference to the time when the attribute was read in server

23 int DeviceAttribute::get_type()

Returns the type of the attribute data.

24 AttrDataFormat DeviceAttribute::get_data_format()

Returns the attribute data format. Note that this information is valid only after the call to the device has been executed. Otherwise the FMT_UNKNOWN value of the AttrDataFormat enumeration is returned or an exception is thrown according to the object exception flags.

25 ostream &operator«(ostream &, DeviceAttribute &)

Is an utility function to easily print the contents of a DeviceAttribute object. This function knows all types which could be inserted in a DeviceAttribute object and print them accordingly if the data are valid. It also prints the date returned within the attribute, the attribute name, the dim_x and dim_y attribute parameter and its quality factor.

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: DeviceProxy *dev = new DeviceProxy(...);
DeviceAttribute attr;
attr = dev->read_attribute(MyAttribute);
cout << Attribute returned: << attr << endl;

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

5 Tango::DeviceAttributeHistory

This is the fundamental type for receiving data from device attribute polling buffers. This class inherits from the Tango::DeviceAttribute class. One instance of this class is created for each attribute result history. Within this class, you find the attribute result data or the exception parameters and a flag indicating if the attribute has failed when it was invoked by the device server polling thread. For history calls, it is not possible to returns attribute error as exception. See chapter on Advanced Features for all details regarding device polling. On top of the methods inherited from the DeviceAttribute class, it offers the following methods

1 ostream &operator«(ostream &, DeviceAttributeHistory &)

Is an utility function to easily print the contents of a DeviceAttributeHistory object. This function knows all types which could be inserted in a DeviceAttributeHistory object and print them accordingly. It also prints date, attribute name, attribute dim_x and dim_y parameters, attribute quality factor and error stack in case the attribute returned an error.

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: DeviceProxy *dev = new DeviceProxy(``...'');
int hist_depth = 4;
vector<DeviceAttributeHistory> *hist;
hist = dev->attribute_history(``MyAttribute'',hist_depth);
for (int i = 0;i < hist_depth;i++)
{
cout << (*hist)[i] << endl;
}
delete hist;

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

6 Tango::AttributeProxy()

The high level object which provides the client with an easy-to-use interface to TANGO device attributes. AttributeProxy is a handle to the real Attribute (hence the name Proxy) and is not the real Attribute (of course). The AttributeProxy manages timeouts, stateless connections (new AttributeProxy() nearly always works), and reconnection if the device server is restarted.

1 Constructors

1 AttributeProxy::AttributeProxy(string &name)

Create an AttributeProxy to an attribute of the specified name. The constructor will connect to the TANGO database, query for the device to which the attribute belongs to network address and build a connection to this device. If the device to which the attribute belongs to is defined in the TANGO database but the device server is not running, AttributeProxy will try to build a connection every time the client tries to access the attribute. If an alias name is defined for the attribute, this alias name can be used to create the AttributeProxy instance. If a device name alias is defined for the device, it can be used instead of the three fields device name. If the device to which the attribute belongs to is not defined in the database, an exception is thrown. Examples :

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: AttributeProxy *my_attr = new AttributeProxy(my/own/device/attr);
AttributeProxy *my_attr_bis = new AttributeProxy(attr_alias);
AttributeProxy *my_attr_ter = new AttributeProxy(dev_alias/attr);

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

See appendix on device/attribute naming for all details about Tango device or attribute naming syntax.
Exception: WrongNameSyntax, ConnectionFailed

2 AttributeProxy::AttributeProxy(const char *name)

Idem previous call

2 Miscellaneous methods

1 DevState AttributeProxy::state()

A method which returns the state of the device to which the attribute belongs to. This state is returned as a Tango::DevState type. Example :

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: dev_state = my_attr->state() << endl;

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: ConnectionFailed, CommunicationFailed

2 string AttributeProxy::status()

A method which return the status of the device to which the attribute belongs to. The status is returned as a string. Example :

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: cout << device status << my_attr->status() << endl;

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: ConnectionFailed, CommunicationFailed

3 int AttributeProxy::ping()

A method which sends a ping to the device to which the attribute belongs and returns the time elapsed in microseconds. Example :

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: cout << device ping took << my_device->ping() << `` microseconds'' << endl;

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: ConnectionFailed, CommunicationFailed

4 string AttributeProxy::name()

Returns the attribute name

5 DeviceProxy *get_device_proxy()

Returns the DeviceProxy instance used to communicate with the device to which the attributes belongs.

3 Synchronous related methods

1 AttributeInfo AttributeProxy::get_config()

Return the attribute configuration. AttributeInfo is a struct defined as follows :

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: typedef struct _AttributeInfo {
   string name;
   AttrWriteType writable;
   AttrDataFormat data_format;
   int data_type;
   int max_dim_x;
   int max_dim_y;
   string description;
   string label;
   string unit;
   string standard_unit;
   string display_unit;
   string format;
   string min_value;
   string max_value;
   string min_alarm;
   string max_alarm;
   string writable_attr_name;
   vector<string> extensions;
   Tango::DispLevel disp_level;
} AttributeInfo;

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: ConnectionFailed, CommunicationFailed, DevFailed from device

2 void AttributeProxy::set_config(AttributeInfo &)

Change the attribute configuration.
Exception: ConnectionFailed, CommunicationFailed, DeviceUnlocked, DevFailed from device

3 DeviceAttribute AttributeProxy::read()

Read the attribute. To extract the value you have to use the operator of the class DeviceAttribute which corresponds to the data type of the attribute. NOTE: There is no automatic type conversion from the attribute native type to user type e.g. if an attribute returns a short you cannot extract it as a double (this will return 0) you have to extract it as a short.
Exception: ConnectionFailed, CommunicationFailed, DevFailed from device

4 void AttributeProxy::write(DeviceAttribute&)

Write the attribute. To insert the value to write you have to use the operator of the class DeviceAttribute which corresponds to the data type of the attribute. NOTE: There is no automatic type conversion from the user type to the attribute native type e.g. if an attribute expects a short you cannot insert it as a double (this will throw an exception) you have to insert it as a short.
Exception: ConnectionFailed, CommunicationFailed, DeviceUnlocked, DevFailed from device

5 DeviceAttribute AttributeProxy::write_read(DeviceAttribute&)

6 vector<DeviceAttributeHistory> *AttributeProxy::history(int)

Retrieve attribute history from the attribute polling buffer. The argument is the wanted history depth. This method returns a vector of DeviceAttributeHistory types. This method allocates memory for the vector of DeviceAttributeHistory returned to the caller. It is the caller responsibility to delete this memory. Class DeviceAttributeHistory is detailed on chapter

See chapter on Advanced Feature for all details regarding polling.

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: AttributeProxy attr = new AttributeProxy(my/own/device/Current);
vector<DeviceAttributeHistory> *hist;
hist = attr->history(5);
for (int i = 0;i < 5;i++)
{

    bool fail = (*hist)[i].has_failed();
    if (fail == false)
    {
        cout << Attribute name =  << (*hist)[i].get_name() << endl;
        cout << Attribute quality factor =  << (*hist)[i].get_quality() << endl;
        long value;
        (*hist)[i] >> value;
        cout << Current =  << value << endl;
    }
    else
    {
        cout << Attribute failed ! << endl;
        cout << Error level 0 desc =  << ((*hist)[i].get_err_stack())[0].desc << endl;
    }
    cout << Date =  << (*hist)[i].get_date().tv_sec << endl;
}
delete hist;

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: NonSupportedFeature, ConnectionFailed, CommunicationFailed, DevFailed from device

4 Asynchronous methods

1 long AttributeProxy::read_asynch()

Read the attribute asynchronously (polling model). This call returns an asynchronous call identifier which is needed to get the attribute value.
Exception: ConnectionFailed

2 DeviceAttribute *AttributeProxy::read_reply(long id)

Check if the answer of an asynchronous read is arrived (polling model). id is the asynchronous call identifier. If the reply is arrived and if it is a valid reply, it is returned to the caller in a DeviceAttribute object. If the reply is an exception, it is re-thrown by this call. An exception is also thrown in case of the reply is not yet arrived. To extract attribute value, you have to use the operator of the class DeviceAttribute which corresponds to the data type of the attribute. NOTE: There is no automatic type conversion from the attribute native type to user type e.g. if an attribute returns a short you cannot extract it as a double, you have to extract it as a short. Memory has been allocated for the DeviceAttribute object returned to the caller. This is the caller responsibility to delete this memory.
Exception: AsynCall, AsynReplyNotArrived, CommunicationFailed, DevFailed from device

3 DeviceAttribute *AttributeProxy::read_reply(long id, long timeout)

Check if the answer of an asynchronous read is arrived (polling model). id is the asynchronous call identifier. If the reply is arrived and if it is a valid reply, it is returned to the caller in a DeviceAttribute object. If the reply is an exception, it is re-thrown by this call. If the reply is not yet arrived, the call will wait (blocking the process) for the time specified in timeout. If after timeout milliseconds, the reply is still not there, an exception is thrown. If timeout is set to 0, the call waits until the reply arrived. To extract attribute value, you have to use the operator of the class DeviceAttribute which corresponds to the data type of the attribute. NOTE: There is no automatic type conversion from the attribute native type to user type e.g. if an attribute returns a short you cannot extract it as a double, you have to extract it as a short. Memory has been allocated for the DeviceAttribute object returned to the caller. This is the caller responsibility to delete this memory.
Exception: AsynCall, AsynReplyNotArrived, CommunicationFailed, DevFailed from device

4 long AttributeProxy::write_asynch(DeviceAttribute &argin)

Write the attribute asynchronously (polling model). To insert the value to write you have to use the operator of the class DeviceAttribute which corresponds to the data type of the attribute. NOTE: There is no automatic type conversion from the user type to the attribute native type e.g. if an attribute expects a short you cannot insert it as a double (this will throw an exception) you have to insert it as a short. This call returns an asynchronous call identifier which is needed to get the server reply.
Exception: ConnectionFailed

5 void AttributeProxy::write_reply(long id)

Check if the answer of an asynchronous write is arrived (polling model). id is the asynchronous call identifier. If the reply is arrived and if it is a valid reply, the call returned. If the reply is an exception, it is re-thrown by this call. An exception is also thrown in case of the reply is not yet arrived.
Exception: AsynCall, AsynReplyNotArrived, CommunicationFailed, DevFailed from device

6 void AttributeProxy::write_reply(long id, long timeout)

Check if the answer of an asynchronous write is arrived (polling model). id is the asynchronous call identifier. If the reply is arrived and if it is a valid reply, the call returned. If the reply is an exception, it is re-thrown by this call. If the reply is not yet arrived, the call will wait (blocking the process) for the time specified in timeout. If after timeout milliseconds, the reply is still not there, an exception is thrown. If timeout is set to 0, the call waits until the reply arrived.
Exception: AsynCall, AsynReplyNotArrived, CommunicationFailed, DevFailed from device

7 void AttributeProxy::read_asynch(CallBack &cb)

Read the attribute asynchronously using the callback model. The argument is a reference to a callback object. This callback object should be an instance of a user class inheriting from the Tango::CallBack class with the attr_read() method overloaded.
Exception: ConnectionFailed

8 void AttributeProxy::write_asynch(DeviceAttribute &argin, CallBack &cb)

Write the attribute asynchronously using the callback model. The argument is a reference to a callback object. This callback object should be an instance of a user class inheriting from the Tango::CallBack class with the attr_written() method overloaded.
Exception: ConnectionFailed

5 Polling related methods

1 bool AttributeProxy::is_polled()

Returns true if the attribute is polled. Otherwise, returns false.

2 int AttributeProxy::get_poll_period()

Returns the attribute polling period in mS. If the attribute is not polled, it returns 0.

3 void AttributeProxy::poll(int period)

Add the attribute to the list of polled attributes. The polling period is specified by period (in mS). If the attribute is already polled, this method will update the polling period according to period.

4 void AttributeProxy::stop_poll()

Remove attribute from the list of polled attributes.

6 Event related methods

1 int AttributeProxy::subscribe_event(EventType event, CallBack *cb)

The client call to subscribe for event reception in the push model. The client implements a callback method which is triggered when the event is received either by polling or a dedicated thread. Filtering is done based on the reason specified and the event type. For example when reading the state and the reason specified is change the event will be fired only when the state changes. Events consist of an attribute name and the event reason. A standard set of reasons are implemented by the system, additional device specific reasons can be implemented by device servers programmers.
The event parameter is the event reason and must be on the enumerated values:

Tango::CHANGE_EVENT
Tango::PERIODIC_EVENT
Tango::ARCHIVE_EVENT
Tango::ATTR_CONF_EVENT

cb is a pointer to a class inheriting from the Tango CallBack class and implementing a push_event() method, filters is a variable list of name,value pairs which define additional filters for events. The subscribe_event() call returns an event id which has to be specified when unsubscribing from this event.
Exception: EventSystemFailed
Note: For releases prior to Tango 8, a similar call with a third argument (const vector<string> &filters) was available. This extra argument gave the user a way to define extra event filtering. For compatibility reason, this call still exist but the extra filtering features is not implemented.

2 int AttributeProxy::subscribe_event(EventType event, CallBack *cb, bool stateless)

This subscribe event method has the same functionality as described in the last section. It adds an additional flag called stateless. When the stateless flag is set to false, an exception will be thrown when the event subscription encounters a problem.
With the stateless flag set to true, the event subscription will always succeed, even if the corresponding device server is not running. The keep alive thread will try every 10 seconds to subscribe for the specified event. At every subscription retry, a callback is executed which contains the corresponding exception.
Exception: EventSystemFailed
Note: For releases prior to Tango 8, a similar call with a forth argument (const vector<string> &filters) was available. This extra argument gave the user a way to define extra event filtering and it was the third argument in the argument list. For compatibility reason, this call still exist but the extra filtering features is not implemented.

3 int AttributeProxy::subscribe_event(EventType event, int event_queue_size, bool stateless)

The client call to subscribe for event reception in the pull model. Instead of a callback method the client has to specify the size of the event reception buffer.
The event reception buffer is implemented as a round robin buffer. This way the client can set-up different ways to receive events.
Event reception buffer size = 1 : The client is interested only in the value of the last event received. All other events that have been received since the last reading are discarded.
Event reception buffer size > 1 : The client has chosen to keep an event history of a given size. When more events arrive since the last reading, older events will be discarded.
Event reception buffer size = ALL_EVENTS : The client buffers all received events. The buffer size is unlimited and only restricted by the available memory for the client.
All other parameters are similar to the descriptions given in the last two sections.
Exception: EventSystemFailed
Note: For releases prior to Tango 8, a similar call with a forth argument (const vector<string> &filters) was available. This extra argument gave the user a way to define extra event filtering and it was the third argument in the argument list. For compatibility reason, this call still exist but the extra filtering features is not implemented.

4 void AttributeProxy::unsubscribe_event(int event_id)

Unsubscribe a client from receiving the event specified by event_id. event_id is the event identifier returned by the AttributeProxy::subscribe_event() method.
Exception: EventSystemFailed

5 void AttributeProxy::get_events(int event_id, CallBack *cb)

The method extracts all waiting events from the event reception buffer and executes the callback method cb for every event. During event subscription the client must have chosen the pull model for this event. event_id is the event identifier returned by the AttributeProxy::subscribe_event() method.
Exception: EventSystemFailed

6 void AttributeProxy::get_events(int event_id, EventDataList &event_list)

The method extracts all waiting events from the event reception buffer. The returned event_list is a vector of EventData pointers. The EventData object contains the event information as for the callback methods.
During event subscription the client must have chosen the pull model for this event. event_id is the event identifier returned by the AttributeProxy::subscribe_event() method.
Exception: EventSystemFailed

7 void AttributeProxy::get_events(int event_id, AttrConfEventDataList &event_list)

The method extracts all waiting attribute configuration events from the event reception buffer. The returned event_list is a vector of AttrConfEventData pointers. The AttrConfEventData object contains the event information as for the callback methods.
During event subscription the client must have chosen the pull model for this event. event_id is the event identifier returned by the AttributeProxy::subscribe_event() method.
Exception: EventSystemFailed

8 int AttributeProxy::event_queue_size(int event_id)

Returns the number of stored events in the event reception buffer. After every call to DeviceProxy:get_events(), the event queue size is 0.
During event subscription the client must have chosen the pull model for this event. event_id is the event identifier returned by the AttributeProxy::subscribe_event() method.
Exception: EventSystemFailed

9 TimeVal AttributeProxy::get_last_event_date(int event_id)

Returns the arrival time of the last event stored in the event reception buffer. After every call to DeviceProxy:get_events(), the event reception buffer is empty. In this case an exception will be returned.
During event subscription the client must have chosen the pull model for this event. event_id is the event identifier returned by the AttributeProxy::subscribe_event() method.
Exception: EventSystemFailed

10 bool AttributeProxy::is_event_queue_empty(int event_id)

Returns true when the event reception buffer is empty.
During event subscription the client must have chosen the pull model for this event. event_id is the event identifier returned by the AttributeProxy::subscribe_event() method.
Exception: EventSystemFailed

7 Property related methods

1 void AttributeProxy::get_property (string&, DbData&)

Get a single property for the attribute. The property to get is specified as a string. Refer to DbDevice::get_property() and DbData sections below for details on the DbData type.
Exception: NonDbDevice, ConnectionFailed (with database), CommunicationFailed (with database), DevFailed from database device

2 void AttributeProxy::get_property (vector<string>&, DbData&)

Get a list of properties for the attribute. The properties to get are specified as a vector of strings. Refer to DbDevice::get_property() and DbData sections below for details on the DbData type.
Exception: NonDbDevice, ConnectionFailed (with database), CommunicationFailed (with database), DevFailed from database device

3 void AttributeProxy::get_property(DbData&)

Get property(ies) for the attribute. Properties to get are specified using the DbData type. Refer to DbDevice::get_property() and DbData sections below for details.
Exception: NonDbDevice, ConnectionFailed (with database), CommunicationFailed (with database), DevFailed from database device

4 void AttributeProxy::put_property(DbData&)

Put property(ies) for an attribute. Properties to put are specified using the DbData type. Refer to DbDevice::put_property() and DbData sections below for details.
Exception: NonDbDevice, ConnectionFailed (with database), CommunicationFailed (with database), DevFailed from database device

5 void AttributeProxy::delete_property (string&, DbData&)

Delete a single property for an attribute. The property to delete is specified as a string. Refer to DbDevice::delete_property() and DbData sections below for details on the DbData type.
Exception: NonDbDevice, ConnectionFailed (with database), CommunicationFailed (with database), DevFailed from database device

6 void AttributeProxy::delete_property (vector<string>&, DbData&)

Delete a list of properties for an attribute. The properties to delete are specified as a vector of strings. Refer to DbDevice::get_property() and DbData sections below for details on the DbData type.
Exception: NonDbDevice, ConnectionFailed (with database), CommunicationFailed (with database), DevFailed from database device

7 void AttributeProxy::delete_property(DbData&)

Delete property(ies) for an attribute. Properties to delete are specified using the DbData type. Refer to DbDevice::get_property() and DbData sections below for details.
Exception: NonDbDevice, ConnectionFailed (with database), CommunicationFailed (with database), DevFailed from database device

7 Tango::ApiUtil

This class is a singleton. Therefore, it is not necessary to create it. It will be automatically done. A static method allows a user to retrieve the instance

1 static ApiUtil *ApiUtil::instance()

Return the ApiUtil singleton instance.

2 static void ApiUtil::cleanup()

Destroy the ApiUtil singleton instance.

3 long ApiUtil::pending_asynch_call(asyn_req_type req)

Return number of asynchronous pending requests (any device). The input parameter is an enumeration with three values which are:

[POLLING] : Return only polling model asynchronous request number
[CALL_BACK] : Return only callback model asynchronous request number
[ALL_ASYNCH] : Return all asynchronous request number

Exception: None

4 void ApiUtil::get_asynch_replies()

Fire callback methods for all (any device) asynchronous requests (command and attribute) with already arrived replied. Returns immediately if there is no replies already arrived or if there is no asynchronous requests.
Exception: None, all errors are reported using the err and errors fields of the parameter passed to the callback method. See chapter

for details.

5 void ApiUtil::get_asynch_replies(long timeout)

Fire callback methods for all (any device) asynchronous requests (command and attributes) with already arrived replied. Wait and block the caller for timeout milliseconds if they are some device asynchronous requests which are not yet arrived. Returns immediately if there is no asynchronous request. If timeout is set to 0, the call waits until all the asynchronous requests sent has received a reply.
Exception: AsynReplyNotArrived. All other errors are reported using the err and errors fields of the object passed to the callback methods. See chapter

for details.

6 void ApiUtil::set_asynch_cb_sub_model(cb_sub_model model)

Set the asynchronous callback sub-model between the pull and push sub-model. See chapter

to read the definition of these sub-model. The cb_sub_model data type is an enumeration with two values which are :

[PUSH_CALLBACK] : The push sub-model
[PULL_CALLBACK] : The pull sub-model

By default, all Tango client using asynchronous callback model are in pull sub-model. This call must be used to switch to the push sub-model. NOTE that in push sub-model, a separate thread is spawned to deal with server replies.
Exception: None

7 cb_sub_model ApiUtil::get_asynch_cb_sub_model()

Get the asynchronous callback sub-model.
Exception: None

8 static int ApiUtil::get_env_var(const char *name,string &value)

Get environment variable. On Unixes OS, this call tries to get the variable in the caller environment then in a file .tangorc in the user home directory and finally in a file /etc/tangorc. On Windows, this call looks in the user environment then in a file stored in %TANGO_HOME%/tangorc. This method returns 0 of the environment variable is found. Otherwise, it returns -1.
Exception: None

9 void set_event_buffer_hwm(DevLong val)

Set the client event buffer high water mark (HWM)

8 Asynchronous callback related classes

1 Tango::CallBack

When using the event push model (callback automatically executed), there are some cases (same callback used for events coming from different devices hosted in device server process running on different hosts) where the callback method could be executed concurently by different threads started by the ORB. The user has to code his callback method in a thread safe manner.

1 void CallBack::cmd_ended(CmdDoneEvent *event)

This method is defined as being empty and must be overloaded by the user when the asynchronous callback model is used. This is the method which will be executed when the server reply from a command_inout is received in both push and pull sub-mode.

2 void CallBack::attr_read(AttrReadEvent *event)

This method is defined as being empty and must be overloaded by the user when the asynchronous callback model is used. This is the method which will be executed when the server reply from a read_attribute(s) is received in both push and pull sub-mode.

3 void CallBack::attr_written(AttrWrittenEvent *event)

This method is defined as being empty and must be overloaded by the user when the asynchronous callback model is used. This is the method which will be executed when the server reply from a write_attribute(s) is received in both push and pull sub-mode.

4 void CallBack::push_event(EventData *event)

This method is defined as being empty and must be overloaded by the user when events are used. This is the method which will be executed when the server send event(s) to the client.

5 void CallBack::push_event(AttrConfEventData *event)

This method is defined as being empty and must be overloaded by the user when events are used. This is the method which will be executed when the server send attribute configuration change event(s) to the client.

6 void CallBack::push_event(DataReadyEventData *event)

This method is defined as being empty and must be overloaded by the user when events are used. This is the method which will be executed when the server send attribute data ready event(s) to the client.

2 Tango::CmdDoneEvent

This class is used to pass data to the callback method in asynchronous callback model for command execution. It contains the following public field

[device] : The DeviceProxy object on which the call was executed (Tango::DeviceProxy *)
[cmd_name] : The command name (string &)
[argout] : The command argout (DeviceData &)
[err] : A boolean flag set to true if the command failed. False otherwise (bool)
[errors] : The error stack (DevErrorList &)

3 Tango::AttrReadEvent

This class is used to pass data to the callback method in asynchronous callback model for read_attribute(s) execution. It contains the following public field

[device] : The DeviceProxy object on which the call was executed (Tango::DeviceProxy *)
[attr_names] : The attribute name list (vector<string> &)
[argout] : The attribute data (vector<DeviceAttribute> *)
[err] : A boolean flag set to true if the request failed. False otherwise (bool)
[errors] : The error stack (DevErrorList &)

To extract attribute value(s), you have to use the operator of the class DeviceAttribute which corresponds to the data type of the attribute. NOTE: There is no automatic type conversion from the attribute native type to user type e.g. if an attribute returns a short you cannot extract it as a double, you have to extract it as a short. Memory has been allocated for the vector of DeviceAttribute objects passed to the caller. This is the caller responsibility to delete this memory.

4 Tango::AttrWrittenEvent

This class is used to pass data to the callback method in asynchronous callback model for write_attribute(s) execution. It contains the following public field

[device] : The DeviceProxy object on which the call was executed (Tango::DeviceProxy *)
[attr_names] : The attribute name list (vector<string> &)
[err] : A boolean flag set to true if the request failed. False otherwise (bool)
[errors] : The error stack (DevErrorList &)

5 Tango::EventData

This class is used to pass data to the callback method when an event is sent to the client. It contains the following public field

[device] : The DeviceProxy object on which the call was executed (Tango::DeviceProxy *)
[attr_name] : The attribute name (std::string &)
[event] : The event name (std::string &)
[attr_value] : The attribute data (DeviceAttribute *)
[err] : A boolean flag set to true if the request failed. False otherwise (bool)
[errors] : The error stack (DevErrorList &)

6 Tango::AttrConfEventData

This class is used to pass data to the callback method when an attribute configuration event is sent to the client. It contains the following public field

[device] : The DeviceProxy object on which the call was executed (Tango::DeviceProxy *)
[attr_name] : The attribute name (std::string &)
[event] : The event name (std::string &)
[attr_conf] : The attribute configuration (AttributeInfoEx *)
[err] : A boolean flag set to true if the request failed. False otherwise (bool)
[errors] : The error stack (DevErrorList &)

7 Tango::DataReadyEventData

This class is used to pass data to the callback method when an attribute data ready event is sent to the client. It contains the following public field

[device] : The DeviceProxy object on which the call was executed (Tango::DeviceProxy *)
[attr_name] : The attribute name (std::string &)
[event] : The event name (std::string &)
[attr_data_type] :The attribute data type (int)
[ctr] : The user counter. Set to 0 if not defined when sent by the server (int)
[err] : A boolean flag set to true if the request failed. False otherwise (bool)
[errors] : The error stack (DevErrorList &)

9 Tango::Group

1 Constructor and Destructor

1 Group::Group (const std::string& name)

Instanciate an empty group. The group name allows retrieving a sub-group in the hierarchy.
See also: Group::~Group(), Group::get_group().

2 Group::~Group ()

Delete a group and all its elements.
Be aware that a group always gets the ownership of its children and deletes them when it is itself deleted. Therefore, never try to delete a Group (respectively a DeviceProxy) returned by a call to Tango::Group::get_group() (respectively to Tango::Group::get_device()). Use the Tango::Group::remove() method instead.
See also: Group::Group(), Group::remove(), Group::remove_all().

2 Group Management Related Methods

1 void Group::add (Group* group, int timeout_ms = -1)

Attaches a (sub)group.
Be aware that a group always gets the ownership of its children and deletes them when it is itself deleted. Therefore, never try to delete a Group attached to a Group. Use the Group::remove() method instead.
If timeout_ms parameter is different from -1, the client side timeout associated to each device composing the group added is set to timeout_ms milliseconds. If timeout_ms is -1, timeouts are not changed.
This method does nothing if the specified group is already attached (i.e. it is silently ignored) and timeout_ms = -1.
If the specified group is already attached and timeout_ms is different from -1, the client side timeout of each device composing the group given in parameter is set to timeout_ms milliseconds.
See also: all other forms of Group::add() and Group::set_timeout_millis().

2 void Group::add (const std::string& pattern, int timeout_ms = -1)

Attaches any device which name matches the specified pattern.
The pattern parameter can be a simple device name or a device name pattern (e.g. domain_*/ family/member_*).
This method first asks to the Tango database the list of device names matching the pattern. Devices are then attached to the group in the order in which they are returned by the database.
Any device already present in the hierarchy (i.e. a device belonging to the group or to one of its subgroups) is silently ignored but its client side timeout is set to timeout_ms milliseconds if timeout_ms is different from -1.
Set the client side timeout of each device matching the specified pattern to timeout_ms milliseconds if timeout_ms is different from -1.
See also: all other forms of Group::add() and Group::set_timeout_millis().

3 void Group::add (const std::vector<std::string>& patterns, int timeout_ms = -1)

Attaches any device which name matches one of the specified patterns.
The patterns parameter can be an array of device names and/or device name patterns.
This method first asks to the Tango database the list of device names matching one the patterns. Devices are then attached to the group in the order in which they are returned by the database.
Any device already present in the hierarchy (i.e. a device belonging to the group or to one of its subgroups), is silently ignored but its client side timeout is set to timeout_ms milliseconds if timeout_ms is different from -1.
If timeout_ms is different from -1, the client side timeouts of all devices matching the specified patterns are set to timeout_ms milliseconds.
See also: all other forms of Group::add() and Group::set_timeout_millis().

4 void Group::remove (const std::string& pattern, bool fwd = true)

Removes any group or device which name matches the specified pattern.
The pattern parameter can be a group name, a device name or a device name pattern (e.g domain_*/family/member_*).
Since we can have groups with the same name in the hierarchy, a group name can be fully qualified to specify which group should be removed. Considering the following group:

: -> gauges
   | -> cell-01
   |     |-> penning
   |     |    |-> ...
   |     |-> pirani
   |          |-> ...
   | -> cell-02
   |     |-> penning
   |     |    |-> ...
   |     |-> pirani
   |          |-> ...
   | -> cell-03
   |     |-> ...
   |
   | -> ...

A call to gauges->remove(penning) will remove any group named penning in the hierarchy while gauges->remove(gauges.cell-02.penning) will only remove the specified group.
If fwd is set to true (the default), the remove request is also forwarded to subgroups. Otherwise, it is only applied to the local set of elements. For instance, the following code remove any stepper motor in the hierarchy:

: root_group->remove(*/stepper_motor/*);

See also: all other forms of Group::remove().

5 void Group::remove (const std::vector<std::string>& patterns, bool fwd = true)

Removes any group or device which name matches the specified patterns.
The patterns parameter can be an array of group names and/or device names and/or device name patterns.
Since we can have groups with the same name in the hierarchy, a group name can be fully qualified to specify which group should be removed. See previous method for details.
If fwd is set to true (the default), the remove request is also forwarded to subgroups. Otherwise, it is only applied to the local set of elements.
See also: all other forms of Group::remove().

6 void Group::remove_all (void)

Removes all elements in the group. After such a call, the group is empty.
See also: all forms of Group::remove().

7 bool Group::contains (const std::string& pattern, bool fwd = true)

Returns true if the hierarchy contains groups and/or devices which name matches the specified pattern. Returns false otherwise.
The pattern can be a fully qualified or simple group name, a device name or a device name pattern.
If fwd is set to true (the default), the request is also forwarded to subgroups. Otherwise, it is only applied to the local set of elements.
See also: Group::get_device(), Group::get_group().

8 DeviceProxy* Group::get_device (const std::string& device_name)

Returns a reference to the specified device or NULL if there is no device by that name in the group. This method may throw an exception in case the specified device belongs to the group but can't be reached (not registered, down...). See example below. See also the Tango::DeviceProxy class documentation for details.

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: try
{
  Tango::DeviceProxy *dp = g->get_device(my/device/01);
  if (dp == 0)
  {
// my/device/01 doe snot belongs to the group
  {
}
catch (const Tango::DevFailed &df)
{
// my/device/01 belongs to the group but can't be reached
}

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

The request is systematically forwarded to subgroups (i.e. if no device named device_name could be found in the local set of devices, the request is forwarded to subgroups).
Be aware that a group always gets the ownership of its children and deletes them when it is itself deleted. Therefore, never try to delete a DeviceProxy returned by the Group::get_device() method. Use the Tango::Group::remove() method instead.
See also: other form of Group::get_device(), Group::get_size(), Group::get_group(), Group::contains().

9 DeviceProxy* Group::get_device (long idx)

Returns a reference to the idx-th device in the hierarchy or NULL if the hierarchy contains less than idx devices. This method may throw an exception in case the specified device belongs to the group but can't be reached (not registered, down...). See previous example. See also the Tango::DeviceProxy class documentation for details.
The request is systematically forwarded to subgroups (i.e. if the local set of devices contains less than idx devices, the request is forwarded to subgroups).
Be aware that a group always gets the ownership of its children and deletes them when it is itself deleted. Therefore, never try to delete a DeviceProxy returned by the Group::get_device() method. Use the Tango::Group::remove() method instead.
See also: other form of Group::get_device(), Group::get_size(), Group::get_group, Group::contains().

10 DeviceProxy* Group::operator[] (long i)

Returns a reference to the idx-th device in the hierarchy or NULL if the hierarchy contains less than idx devices. See the Tango::DeviceProxy class documentation for details.
The request is systematically forwarded to subgroups (i.e. if the local set of devices contains less than idx devices, the request is forwarded to subgroups).
Be aware that a group always gets the ownership of its children and deletes them when it is itself deleted. Therefore, never try to delete a DeviceProxy returned by the Group::get_device() method. Use the Tango::Group::remove() method instead.
See also: other form of Group::get_device(), Group::get_size(), Group::get_group(), Group::contains().

11 Group* Group::get_group (const std::string& group_name)

Returns a reference to the specified group or NULL if there is no group by that name. The group_name can be a fully qualified name.
Considering the following group:

: -> gauges
    |-> cell-01
    |    |-> penning
    |    |    |-> ...
    |    |-> pirani
    |    |-> ...
    |-> cell-02
    |    |-> penning
    |    |    |-> ...
    |    |-> pirani
    |    |-> ...
    | -> cell-03
    |    |-> ...
    |
    | -> ...

A call to gauges->get_group(penning) returns the first group named penning in the hierarchy (i.e. gauges.cell-01.penning) while gauges->get_group(gauges.cell-02.penning'') returns the specified group.
The request is systematically forwarded to subgroups (i.e. if no group named group_name could be found in the local set of elements, the request is forwarded to subgroups).
Be aware that a group always gets the ownership of its children and deletes them when it is itself deleted. Therefore, never try to delete a Group returned by the Group::get_group() method. Use the Tango::Group::remove() method instead.
See also: Group::get_device(), Group::contains().

12 long Group::get_size (bool fwd = true)

Return the number of devices in the hierarchy (respectively the number of device in the group) if the forward option is set to true (respectively set to false).

13 std::vector<std::string> Group::get_device_list (bool fwd = true)

Returns the list of devices currently in the hierarchy.
If fwd is set to true (the default) the request is forwarded to subgroups. Otherwise, it is only applied to the local set of devices.
Considering the following hierarchy:

: g2->add(my/device/04); g2->add(my/device/05);

g4->add(my/device/08); g4->add(my/device/09);

g3->add(my/device/06);
g3->addg(g4);
g3->add(my/device/07);

g1->add(my/device/01);
g1->add(g2);
g1->add(my/device/03);
g1->add(g3);
g1->add(my/device/02);

The returned vector content depends on the value of the forward option. If set to true, the results will be organized as follows:

: std::vector<std::string> dl = g1->get_device_list(true);

dl[0] contains my/device/01 which belongs to g1
dl[1] contains my/device/04 which belongs to g1.g2
dl[2] contains my/device/05 which belongs to g1.g2
dl[3] contains my/device/03 which belongs to g1
dl[4] contains my/device/06 which belongs to g1.g3
dl[5] contains my/device/08 which belongs to g1.g3.g4
dl[6] contains my/device/09 which belongs to g1.g3.g4
dl[7] contains my/device/07 which belongs to g1.g3
dl[8] contains my/device/02 which belongs to g1
If the forward option is set to false, the results are:

: std::vector<std::string> dl = g1->get_device_list(false);

dl[0] contains my/device/01 which belongs to g1
dl[1] contains my/device/03 which belongs to g1
dl[2] contains my/device/02 which belongs to g1

3 A la DeviceProxy Methods

1 bool Group::ping (bool fwd = true)

Ping all devices in a group. This method returns true if all devices in the group are alive, false otherwise.
If fwd is set to true (the default), the request is also forwarded to subgroups. Otherwise, it is only applied to the local set of devices.

2 void Group::set_timeout_millis(int timeout_ms)

Set client side timeout for all devices composing the group in milliseconds. Any method which takes longer than this time to execute will throw an exception.
Exception: none (errors are ignored).

3 GroupCmdReplyList Group::command_inout (const std::string& c, bool fwd = true)

Executes a Tango command on a group. This method is synchronous and does not return until replies are obtained or timeouts occurred.
The parameter c is the name of the command.
If fwd is set to true (the default), the request is also forwarded to subgroups. Otherwise, it is only applied to the local set of devices.
Command results are returned in a GroupCmdReplyList. See Obtaining command result for details (

). See also Case 1 of executing a command (

) for an example.

4 GroupCmdReplyList Group::command_inout (const std::string& c, const DeviceData& d, bool fwd = true)

Executes a Tango command on each device in the group. This method is synchronous and does not return until replies are obtained or timeouts occurred.
The parameter c is the name of the command.
The second parameter d is a Tango generic container for command carrying the command argument. See the Tango::DeviceData documentation.
If fwd is set to true (the default), the request is also forwarded to subgroups. Otherwise, it is only applied to the local set of devices.
Command results are returned in a GroupCmdReplyList. See Obtaining command results (

) for details. See also Case 2 of executing a command (

) for an example.

5 template<typename T> GroupCmdReplyList Group::command_inout (const std::string& c, const std::vector<T>& d, bool fwd = true)

Executes a Tango command on each device in the group. This method is synchronous and does not return until replies are obtained or timeouts occurred.
This implementation of command_inout allows passing a specific input argument to each device in the group. In order to use this form of command_inout, the user must have an a priori and perfect knowledge of the devices order in the group.
The parameter c is the name of the command.
The std::vector d contains a specific argument value for each device in the group. Since this method is a template, d is able to contain any Tango command argument type. Its size must equal Group::get_size(fwd). Otherwise, an exception is thrown. The order of the argument values must follows the order of the devices in the group (d[0] => 1st device, d[1] => 2nd device and so on).
If fwd is set to true (the default), the request is also forwarded to subgroups. Otherwise, it is only applied to the local set of devices.
Command results are returned in a GroupCmdReplyList. See Obtaining command results (

) for details. See also Case 3 of executing a command (

) for an example of this special form of command_inout.

6 long Group::command_inout_asynch (const std::string& c, bool fgt = false, bool fwd = true, long rsv = -1)

Executes a Tango command on each device in the group asynchronously. The method sends the request to all devices and returns immediately. Pass the returned request id to Group::command_inout_reply() to obtain the results.
The parameter c is the name of the command.
The parameter fgt is a fire and forget flag. If set to true, it means that no reply is expected (i.e. the caller does not care about it and will not even try to get it). A false default value is provided.
If the parameter fwd is set to true (the default) request is forwarded to subgroups. Otherwise, it is only applied to the local set of devices.
Finally, rsv is reserved for internal purpose and should not be modify. This parameter may disappear in a near future.
See Case 1 of Executing a command (

) for an example.

7 long Group::command_inout_asynch (const std::string& c, const DeviceData& d, bool fgt = false, bool fwd = true, long rsv = -1)

Executes a Tango command on each device in the group asynchronously. The method sends the request to all devices and returns immediately. Pass the returned request id to Group::command_inout_reply() to obtain the results.
The parameter c is the name of the command.
The second parameter d is a Tango generic container for command carrying the command argument. See the Tango::DeviceData documentation for details.
The parameter fgt is a fire and forget flag. If set to true, it means that no reply is expected (i.e. the caller does not care about it and will not even try to get it). A false default value is provided.
If the parameter fwd is set to true (the default) request is forwarded to subgroups. Otherwise, it is only applied to the local set of devices.
Finally, rsv is reserved for internal purpose and should not be modify. This parameter may disappear in a near future.
See Case 2 of Executing a command (

) for an example.

8 long Group::command_inout_asynch (const std::string& c, const std::vector<T>& d, fgt = false, bool fwd = true)

Executes a Tango command on each device in the group asynchronously. The method send the request to all devices and return immediately. Pass the returned request id to Group::command_inout_reply to obtain the results.
This implementation of command_inout allows passing a specific input argument to each device in the group. In order to use this form of command_inout_asynch, the user must have an a priori and perfect knowledge of the devices order in the group.
The parameter c is the name of the command.
The std::vector d contains a specific argument value for each device in the group. d is able to contain any Tango command argument type. Its size must equal Group::get_size(fwd). Otherwise, an exception is thrown. The order of the argument values must follows the order of the devices in the group (d[0] => 1st device, d[1] => 2nd device and so on).
The parameter fgt is a fire and forget flag. If set to true, it means that no reply is expected (i.e. the caller does not care about it and will not even try to get it). A false default value is provided.
If fwd is set to true (the default), the request is also forwarded to subgroups. Otherwise, it is only applied to the local set of devices.
See Case 3 of Executing a command (

) for an example of this special form of command_inout.

9 GroupCmdReplyList Group::command_inout_reply (long req_id, long timeout_ms = 0)

Returns the results of an asynchronous command.
The first parameter req_id is a request identifier previously returned by one of the command_inout_asynch methods.
For each device in the hierarchy, if the command result is not yet available, command_inout_reply wait timeout_ms milliseconds before throwing an exception. This exception will be part of the global reply. If timeout_ms is set to 0, command_inout_reply waits indefinitely.
Command results are returned in a GroupCmdReplyList. See Obtaining command results (

) for details.

10 GroupAttrReplyList Group::read_attribute (const std::string& a, bool fwd = true)

Reads an attribute on each device in the group. This method is synchronous and does not return until replies are obtained or timeouts occurred.
The parameter a is the name of the attribute to read.
If fwd is set to true (the default) request is forwarded to subgroups. Otherwise, it is only applied to the local set of devices.
Attribute values are returned in a GroupAttrReplyList. See Obtaining attribute values (

) for details. See also Reading an attribute (

) for an example.

11 long Group::read_attribute_asynch (const std::string& a, bool fwd = true, long rsv = -1)

Reads an attribute on each device in the group asynchronously. The method sends the request to all devices and returns immediately. Pass the returned request id to Group::read_attribute_reply() to obtain the results.
The parameter a is the name of the attribute to read.
If fwd is set to true (the default) request is forwarded to subgroups. Otherwise, it is only applied to the local set of devices.
The last parameter (rsv) is reserved for internal purpose and should not be modify. It may disappear in a near future.
See Reading an attribute (

) for an example.

12 GroupAttrReplyList Group::read_attribute_reply (long req_id, long timeout_ms = 0)

Returns the results of an asynchronous attribute reading.
The first parameter req_id is a request identifier previously returned by read_attribute_asynch.
For each device in the hierarchy, if the attribute value is not yet available, read_attribute_reply wait timeout_ms milliseconds before throwing an exception. This exception will be part of the global reply. If timeout_ms is set to 0, read_attribute_reply waits indefinitely.
Replies are returned in a GroupAttrReplyList. See Obtaining attribute values (

) for details.

13 GroupReplyList Group::write_attribute (const DeviceAttribute& d, bool fwd = true)

Writes an attribute on each device in the group. This method is synchronous and does not return until acknowledgements are obtained or timeouts occurred.
The first parameter d is a Tango generic container for attribute carrying both the attribute name and the value. See the Tango::DeviceAttribute documentation for details.
If fwd is set to true (the default) request is forwarded to subgroups. Otherwise, it is only applied to the local set of devices.
Acknowledgements are returned in a GroupReplyList. See Obtaining acknowledgements (

) for details. See also Case 1 of Writing an attribute (

) for an example.

14 GroupReplyList Group::write_attribute (const std::string& a, const std::vector<T>& d, bool fwd = true)

Writes an attribute on each device in the group. This method is synchronous and does not return until replies are obtained or timeouts occurred.
This implementation of write_attribute allows writing a specific value to each device in the group. In order to use this form of write_attribute, the user must have an a priori and perfect knowledge of the devices order in the group.
The parameter a is the name of the attribute.
The std::vector d contains a specific value for each device in the group. Since this method is a template, d is able to contain any Tango attribute type. Its size must equal Group::get_size(fwd). Otherwise, an exception is thrown. The order of the attribute values must follows the order of the devices in the group (d[0] => 1st device, d[1] => 2nd device and so on).
If fwd is set to true (the default) request is forwarded to subgroups. Otherwise, it is only applied to the local set of devices.
Acknowledgements are returned in a GroupReplyList. See Obtaining acknowledgements (

) for details. See also Case 2 of Writing an attribute (

) for an example.

15 long Group::write_attribute_asynch (const DeviceAttribute& d, bool fwd = true, long rsv = -1)

Writes an attribute on each device in the group asynchronously. The method sends the request to all devices and returns immediately. Pass the returned request id to Group::write_attribute_reply() to obtain the acknowledgements.
The first parameter d is a Tango generic container for attribute carrying both the attribute name and the value. See the Tango::DeviceAttribute documentation for details.
If fwd is set to true (the default) request is forwarded to subgroups. Otherwise, it is only applied to the local set of devices.
The last parameter rsv is reserved for internal purpose and should not be modify. It may disappear in a near future.
See Case 1 of Writing an attribute (

) for an example.

16 long Group::write_attribute_asynch (const std::string& a, const std::vector<T>& d, bool fwd = true)

Writes an attribute on each device in the group asynchronously. The method sends the request to all devices and returns immediately. Pass the returned request id to Group::write_attribute_reply() to obtain the acknowledgements.
This implementation of write_attribute_asynch allows writing a specific value to each device in the group. In order to use this form of write_attribute_asynch, the user must have an a priori and perfect knowledge of the devices order in the group.
The parameter a is the name of the attribute.
The std::vector d contains a specific value for each device in the group. Since this method is a template, d is able to contain any Tango attribute type. Its size must equal Group::get_size(fwd). Otherwise, an exception is thrown. The order of the attribute values must follows the order of the devices in the group (d[0] => 1st device, d[1] => 2nd device and so on).
If fwd is set to true (the default) request is forwarded to subgroups. Otherwise, it is only applied to the local set of devices.
See Case2 of Writing an attribute (

) for an example.

17 GroupReplyList Group::write_attribute_reply (long req_id, long timeout_ms = 0)

Returns the acknowledgements of an asynchronous attribute writing.
The first parameter req_id is a request identifier previously returned by one of the write_attribute_asynch implementation.
For each device in the hierarchy, if the acknowledgement is not yet available, write_attribute_reply wait timeout_ms milliseconds before throwing an exception. This exception will be part of the global reply. If timeout_ms is set to 0, write_attribute_reply waits indefinitely.
Acknowledgements are returned in a GroupReplyList. See Obtaining acknowledgements

for details.

18 GroupAttrReplyList Group::read_attributes (const std::vector<std::string>& al, bool fwd = true)

Reads several attributes on each device in the group. This method is synchronous and does not return until replies are obtained or timeouts occurred.
The parameter al is a vector containing the name of the attributes to be read.
If fwd is set to true (the default) request is forwarded to subgroups. Otherwise, it is only applied to the local set of devices.
Attribute values are returned in a GroupAttrReplyList. See Obtaining attribute values (

) for details. See also Reading an attribute (

) for an example. The order of attribute value returned in the GroupAttrReplyList is all attributes for first element in the group followed by all attributes for the second group element and so on.

19 long Group::read_attributes_asynch (const std::vector<std::string>& al, bool fwd = true, long rsv = -1)

Reads several attributes on each device in the group asynchronously. The method sends the request to all devices and returns immediately. Pass the returned request id to Group::read_attributes_reply() to obtain the results.
The parameter al is a vector containing the name of the attributes to be read.
If fwd is set to true (the default) request is forwarded to subgroups. Otherwise, it is only applied to the local set of devices.
The last parameter (rsv) is reserved for internal purpose and should not be modify. It may disappear in a near future.
See Reading an attribute (

) for an example.

20 GroupAttrReplyList Group::read_attributes_reply (long req_id, long timeout_ms = 0)

Returns the results of an asynchronous attribute reading.
The first parameter req_id is a request identifier previously returned by read_attributes_asynch.
For each device in the hierarchy, if the attribute value is not yet available, read_attributes_reply wait timeout_ms milliseconds before throwing an exception. This exception will be part of the global reply. If timeout_ms is set to 0, read_attributes_reply waits indefinitely.
Replies are returned in a GroupAttrReplyList. See Obtaining attribute values (

) for details. The order of attribute value returned in the GroupAttrReplyList is all attributes for first element in the group followed by all attributes for the second group element and so on.

10 Tango::Database

A high level object which contains the link to the database. It has methods for all database commands e.g. get_device_property(), device_list(), info(), etc.

1 Database::Database()

Create a TANGO Database object. The constructor uses the environment variable ``TANGO_HOST'' to determine which instance of the TANGO database to connect to. Example :

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: using namespace Tango;
Database *db = new Database();

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

The Database class also has a copy constructor and one assignement operator defined.

2 string Database::get_info()

Query the database for some general info about the tables in the database. Result is returned as a string. Example :

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: cout << db->get_info() << endl;

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

will return information like this :

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: Running since 2000-11-06 14:10:46

Devices defined  = 115
Devices exported  = 41
Device servers defined  = 47
Device servers exported  = 17

Class properties defined  = 5
Device properties defined  = 130
Class attribute properties defined  = 20
Device attribute properties defined  = 92

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

3 void Database::add_device(DbDevInfo&)

Add a device to the database. The device name, server and class are specified in the DbDevInfo structure. Example :

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: DbDevInfo my_device_info;
my_device_info.name = ``my/own/device'';
my_device_info._class = ``MyDevice'';
my_device_info.server = ``MyServer/test'';
db->add_device(my_device_info);

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: ConnectionFailed, CommunicationFailed, DevFailed from device

4 void Database::delete_device(string)

Delete the device of the specified name from the database. Example

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: db->delete_device(``my/own/device'');

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError, DB_DeviceNotDefined)

5 DbDevImportInfo Database::import_device(string &)

Query the database for the export info of the specified device. The command returns the information in a DbDevImportInfo structure. Example :

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: DbDevImportInfo my_device_import;
my_device_import = db->import_device(``my/own/device'');
cout << `` device '' << my_device_import.name;
cout << ``exported '' << my_device_import.exported;
cout << ``ior '' << my_device_import.ior;
cout << ``version '' << my_device_import.version;
cout << endl;

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device ( DB_SQLError, DB_DeviceNotDefined)

6 void Database::export_device(DbDevExportInfo&)

Update the export info for this device in the database. Device name, server, class, pid and version are specified in the DbDevExportInfo structure. Example :

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: DbDevExportInfo my_device_export;
my_device_export.name = ``my/own/device'';
my_device_export.ior = ``the real ior'';
my_device_export.host = ``dumela'';
my_device_export.version = ``1.0'';
my_device_export.pid = get_pid();
db->export_device(my_device_export);

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError, DB_DeviceNotDefined)

7 void Database::unexport_device(string)

Mark the specified device as un-exported in the database. Example :

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: db->unexport_device(``my/own/device'');

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

8 void Database::add_server(string &, DbDevInfos&)

Add a group of devices to the database. The device names, server names and classes are specified in the vector of DbDevInfo structures.
Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

9 void Database::delete_server(string &)

Delete the device server and its associated devices from the database.
Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

10 void Database::export_server( DbDevExportInfos &)

Export a group of devices to the database. The device names, IOR, class, server name, pid etc. are specified in the vector of DbDevExportInfo structures.
Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

11 void Database::unexport_server(string &)

Mark all devices exported for this server as unexported.
Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

12 DbDatum Database::get_services(string &servicename,string &instname)

Query database for specified services.The instname parameter can be a wildcard character (*).

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: string servicename(HdbManager);
string instname(ctrm);
DbDatum db_datum = db->get_services(servicename,instname);
vector<string> service_list;
db_datum >> service_list;

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: ConnectionFailed, CommunicationFailed, DevFailed from device

13 void Database::register_service(string &servicename,string &instname,string &devname)

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: string servicename(HdbManager);
string instname(ctrm);
string devname(sys/hdb/1);
db->register_service(servicename,instname,devname);

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: ConnectionFailed, CommunicationFailed, DevFailed from device

14 void Database::unregister_service(string &servicename,string &instname)

Unregister the specified service from the database.

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: string servicename(HdbManager);
string instname(ctrm);
db->unregister_service(servicename,instname);

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: ConnectionFailed, CommunicationFailed, DevFailed from device

15 DbDatum Database::get_host_list()

Returns the list of all host names registered in the database.

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: DbDatum db_datum = db->get_host_list();
vector<string> host_list;
db_datum >> host_list;

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: ConnectionFailed, CommunicationFailed, DevFailed from device

16 DbDatum Database::get_host_list(string &wildcard)

Returns the list of all host names registered in the database which match the specified wildcard (eg: l-c0*).

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: string wildcard(l-c0*);
DbDatum db_datum = db->get_host_list(wildcard);
vector<string> host_list;
db_datum >> host_list;

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: ConnectionFailed, CommunicationFailed, DevFailed from device

17 DbDatum Database::get_server_class_list(string &server)

Query the database for a list of classes instancied by the specified server. The DServer class exists in all TANGO servers and for this reason this class is removed from the returned list.

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: string server(Serial/1);
DbDatum db_datum = db->get_server_class_list(server);
vector<string> class_list;
db_datum >> class_list;

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: ConnectionFailed, CommunicationFailed, DevFailed from device

18 DbDatum Database::get_server_name_list()

Return the list of all server names registered in the database.

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: DbDatum db_datum = db->get_server_name_list();
vector<string> server_list;
db_datum >> server_list;

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: ConnectionFailed, CommunicationFailed, DevFailed from device

19 DbDatum Database::get_instance_name_list(string &servername)

Return the list of all instance names existing in the database for the specifed server.

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: string servername(Serial);
DbDatum db_datum = db->get_instance_name_list(servername);
vector<string> instance_list;
db_datum >> instance_list;

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: ConnectionFailed, CommunicationFailed, DevFailed from device

20 DbDatum Database::get_server_list()

Return the list of all servers registered in the database.

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: DbDatum db_datum = db->get_server_list();
vector<string> server_list;
db_datum >> server_list;

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: ConnectionFailed, CommunicationFailed, DevFailed from device

21 DbDatum Database::get_server_list(string &wildcard)

Return the list of all servers registered in the database which match the specified wildcard (eg: Serial/*).

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: string wildcard(Serial/*);
DbDatum db_datum = db->get_server_list(wildcard);
vector<string> server_list;
db_datum >> server_list;

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: ConnectionFailed, CommunicationFailed, DevFailed from device

22 DbDatum Database::get_host_server_list(string &hostname)

Query the database for a list of servers registred on the specified host.

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: string host(kidiboo);
DbDatum db_datum = db->get_host_server_list(wildcard);
vector<string> server_list;
db_datum >> server_list;

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: ConnectionFailed, CommunicationFailed, DevFailed from device

23 DbServerInfo Database::get_server_info(string &server)

Query the database for server information.

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: string server(Serial/1);
DbServerInfo info = db->get_server_info(server);

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: ConnectionFailed, CommunicationFailed, DevFailed from device

24 void Database::put_server_info(DbServerInfo &info)

Add/update server information in the database.

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: DbServerInfo info;
info.name = Serial/1; // Server (name/instance)
info.host = kidiboo; // Register on host kidiboo
info.mode = 1; // Controlled by Astor flag (0 or 1)
info.level = 3; // Startup level (Used by Astor)
db->put_server_info(info);

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: ConnectionFailed, CommunicationFailed, DevFailed from device

25 void Database::delete_server_info(string &server)

Delete server information of the specifed server from the database.

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: string server(Serial/1);
db->delete_server_info(server);

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: ConnectionFailed, CommunicationFailed, DevFailed from device

26 DbDatum Database::get_device_name(string &, string &)

Query the database for a list of devices served by the specified server (1st parameter) and of the specified class (2nd parameter). The method returns a DbDatum type. The device names are stored as an array of strings. Here is two code example of how to extract the names from the DbDatum type :

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: vector<string> device_names;
device_names << db_datum;

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

or :

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: for (int i=0; i< db_datum.size(); i++)
{
device_name[i] = db_datum.value_string[i];
}

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: ConnectionFailed, CommunicationFailed, DevFailed from device

27 DbDatum Database::get_device_exported(string &)

Query the database for a list of exported devices whose names satisfy the supplied filter (* is wildcard for any character(s)). This method returns a DbDatum type. See the method get_device_name() for an example of how to extract the list of aliases from the DbDatum type.
Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

28 DbDatum Database::get_device_domain(string &)

Query the database for a list of device domain names which match the wildcard provided. Wildcard character is * and matches any number of characters. Domain names are case insensitive. This method returns a DbDatum type. See the method get_device_name() for an example of how to extract the list of aliases from the DbDatum type.
Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

29 DbDatum Database::get_device_family(string &)

Query the database for a list of device family names which match the wildcard provided. Wildcard character is * and matches any number of characters. Family names are case insensitive. This method returns a DbDatum type. See the method get_device_name() for an example of how to extract the list of aliases from the DbDatum type.
Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

30 DbDatum Database::get_device_member(string &)

Query the database for a list of device member names which match the wildcard provided. Wildcard characters is * and matches any number of characters. Member names are case insensitive. This method returns a DbDatum type. See the method get_device_name() for an example of how to extract the list of aliases from the DbDatum type.
Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

31 DbDatum Database::get_device_class_list(string &server)

Query the database for a list of devices and classes served by the specified server. Return a list with the following structure: {device name,class name,device name,class name,...}

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: string server(Serial/1);
DbDatum db_datum = db->get_device_class_list(server);
vector<string> dev_list;
db_datum >> dev_list;

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: ConnectionFailed, CommunicationFailed, DevFailed from device

32 string Database::get_class_for_device(string &devname)

Return the class of the specified device.

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: string devname(sr/rf-cavity/1);
string classname = db->get_class_for_device(devname);

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: ConnectionFailed, CommunicationFailed, DevFailed from device

33 DbDatum Database::get_class_inheritance_for_device(string &devname)

Return the class inheritance scheme of the specified device.

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: string devname(sr/rf-cavity/1);
DbDatum db_datum = db->get_class_inheritance_for_device(devname);
vector<string> class_list;
db_datum >> class_list;

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: ConnectionFailed, CommunicationFailed, DevFailed from device

34 DbDatum Database::get_device_exported_for_class(string &classname)

Query database for list of exported devices for the specified class.

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: string classname(MyClass);
DbDatum db_datum = db->get_device_exported_for_class(classname);
vector<string> dev_list;
db_datum >> dev_list;

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: ConnectionFailed, CommunicationFailed, DevFailed from device

35 DbDatum Database::get_object_list(string &wildcard)

Query the database for a list of object (free properties) for which properties are defined and which match the specified wildcard.

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: string wildcard(Optic*);
DbDatum db_datum = db->get_object_list(wildcard);
vector<string> obj_list;
db_datum >> obj_list;

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: ConnectionFailed, CommunicationFailed, DevFailed from device

36 DbDatum Database::get_object_property_list(string &objectname,string &wildcard)

Query the database for a list of properties defined for the specified object and which match the specified wildcard.

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: string objname(OpticID9);
string wildcard(Delta*);
DbDatum db_datum = db->get_object_property_list(objname,wildcard);
vector<string> prop_list;
db_datum >> prop_list;

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: ConnectionFailed, CommunicationFailed, DevFailed from device

37 void Database::get_property(string, DbData&)

Query the database for a list of object (i.e. non-device) properties for the specified object. The property names are specified by the vector of DbDatum structures. The method returns the properties in the same DbDatum structures. To retrieve the properties use the extract operator >>. Here is an example of how to use the DbData type to specify and extract properties :

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: DbData db_data;
db_data.push_back(DbDatum(``velocity''));
db_data.push_back(DbDatum(``acceleration''));
db->get_property(``mymotor'', db_data);
float velocity, acceleration;
db_data[0] >> velocity;
db_data[1] >> acceleration;

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

38 void Database::put_property(string, DbData&)

Insert or update a list of properties for the specified object. The property names and their values are specified by the vector of DbDatum structures. Use the insert operator >> to insert the properties into the DbDatum structures. Here is an example of how to insert properties into the database using this method :

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: DbDatum velocity(``velocity''), acceleration(``acceleration'');
DbData db_data;
velocity << 100000.0;
acceleration << 500000.0;
db_data.push_back(velocity);
db_data.push_back(acceleration);
db->put_property(``mymotor'', db_data);

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

39 void Database::delete_property(string, DbData&)

Delete a list of properties for the specified object. The property names are specified by the vector of DbDatum structures. Here is an example of how to delete properties from the database using this method :

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: DbData db_data;
db_data.push_back(DbDatum(``velocity''));
db_data.push_back(DbDatum(``acceleration''));
db->delete_property(``mymotor'', db_data);

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device

40 vector<DbHistory> Database::get_property_history(string &objname, string &propname)

Get the list of the last 10 modifications of the specifed object property. Note that propname can contain a wildcard character (eg: prop*).

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: vector<DbHistory> hist;
DbDatum result;
string objname(jlptest);
string propname(test_prop);
hist = db->get_property_history(objname,propname);
// Print the modification history of the specified property
for(int i=0;i<hist.size();i++) {
  cout << Name: << hist[i].get_name() << endl;
  cout << Date: << hist[i].get_date() << endl;
  if( hist[i].is_deleted() ) {
    cout << Deleted ! << endl;
  } else {
    hist[i].get_value() >> result;
    for (int j=0; j<result.size(); j++)
      cout << Value: << result[j] << endl;
  }
}

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device

41 void Database::get_device_property(string, DbData&)

Query the database for a list of device properties for the specified object. The property names are specified by the vector of DbDatum structures. The method returns the properties in the same DbDatum structures. To retrieve the properties use the extract operator >>. Here is an example of how to use the DbData type to specify and extract properties :

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: DbData db_data;
db_data.push_back(DbDatum(``velocity''));
db_data.push_back(DbDatum(``acceleration''));
db->get_device_property(``id11/motor/1'', db_data);
float velocity, acceleration;
db_data[0] >> velocity;
db_data[1] >> acceleration;

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

42 void Database::put_device_property(string, DbData&)

Insert or update a list of properties for the specified device. The property names and their values are specified by the vector of DbDatum structures. Use the insert operator >> to insert the properties into the DbDatum structures. Here is an example of how to insert properties into the database using this method :

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: DbDatum velocity(``velocity''), acceleration(``acceleration'');
DbData db_data;
velocity << 100000.0;
acceleration << 500000.0;
db_data.push_back(velocity);
db_data.push_back(acceleration);
db->put_device_property(``id11/motor/1'', db_data);

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

43 void Database::delete_device_property(string, DbData&)

Delete a list of properties for the specified device. The property names are specified by the vector of DbDatum structures. Here is an example of how to delete properties from the database using this method :

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: DbData db_data;
db_data.push_back(DbDatum(``velocity''));
db_data.push_back(DbDatum(``acceleration''));
db->delete_device_property(``id11/motor/1'', db_data);

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

44 vector<DbHistory> Database::get_device_property_history(string &devname, string &propname)

Get the list of the last 10 modifications of the specifed device property. Note that propname can contain a wildcard character (eg: prop*). An example of usage of a similar function can be found in the documentation of the get_property_history() function.
Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device

45 void Database::get_device_attribute_property(string, DbData&)

Query the database for a list of device attribute properties for the specified object. The attribute names are specified by the vector of DbDatum structures. The method returns all the properties for the specified attributes. The attribute names are returned with the number of properties specified as their value. The first DbDatum element of the returned DbData vector contains the first attribute name and the first attribute property number. The following DbDatum element contains the first attribute property name and property values. To retrieve the properties use the extract operator >>. Here is an example of how to use the DbData type to specify and extract attribute properties :

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: DbData db_data;
db_data.push_back(DbDatum(velocity));
db_data.push_back(DbDatum(acceleration));

db->get_device_attribute_property(id11/motor/1, db_data);

float vel_max, vel_min, acc_max, acc_min;

for (int i=0;i < db_data.size();)
{
     long nb_prop;
     string &att_name = db_data[i].name;
     db_data[i] >> nb_prop;
     i++;
     for (int k=0;k < nb_prop;k++)
     {
         string &prop_name = db_data[i].name;
         if (att_name == velocity)
         {
             if (prop_name == min)
                 db_data[i] >>  vel_min;
             else if (att_name == max)
                 db_data[i] >> vel_max;
         }
         else
         {
             if (prop_name == min)
                 db_data[i] >> acc_min;
             else
                 db_data[i] >> acc_max;
         }
         i++;
     }
}

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

46 void Database::put_device_attribute_property(string, DbData&)

Insert or update a list of attribute properties for the specified device. The attribute property names and their values are specified by the vector of DbDatum structures. Use the insert operator >> to insert the properties into the DbDatum structures. Here is an example of how to insert/update properties min, max for attribute velocity and properties min, max for attribute acceleration of device id11/motor/1 into the database using this method :

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: DbDatum velocity(velocity), vel_min(min), vel_max(max);
DbDatum acceleration(acceleration), acc_min(min), acc_max(max);
DbData db_data;
velocity << 2;
vel_min << 0.0;
vel_max << 1000000.0;
db_data.push_back(velocity);
db_data.push_back(vel_min);
db_data.push_back(vel_max);
acceleration << 2;
acc_min << 0.0;
acc_max << 8000000;
db_data.push_back(acceleration);
db_data.push_back(acc_min);
db_data.push_back(acc_max);
db->put_device_attribute_property(``id11/motor/1'', db_data);

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

47 void Database::delete_device_attribute_property(string, DbData&)

Delete a list of attribute properties for the specified device. The attribute names are specified by the vector of DbDatum structures. Here is an example of how to delete the unit property of the velocity attribute of the id11/motor/1 device using this method :

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: DbData db_data;
db_data.push_back(DbDatum(velocity));
db_data.push_back(DbDatum(unit));
db->delete_device_attribute_property(id11/motor/1, db_data);

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

48 vector<DbHistory> Database::get_device_attribute_property_history(string &devname, string &attname, string &propname)

Get the list of the last 10 modifications of the specifed device attribute property. Note that propname and attname can contain a wildcard character (eg: prop*). An example of usage of a similar function can be found in the documentation of the get_property_history() function.
Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device

49 DbDatum Database::get_class_list(string &wildcard)

Query the database for a list of classes which match the specified wildcard.

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: string wildcard(Motor*);
DbDatum db_datum = db->get_class_list(wildcard);
vector<string> class_list;
db_datum >> class_list;

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: ConnectionFailed, CommunicationFailed, DevFailed from device

50 DbDatum Database::get_class_property_list(string &classname)

Query the database for a list of properties defined for the specified class.

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: string classname(MyClass);
DbDatum db_datum = db->get_class_property_list(classname);
vector<string> prop_list;
db_datum >> prop_list;

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: ConnectionFailed, CommunicationFailed, DevFailed from device

51 void Database::get_class_property(string, DbData&)

Query the database for a list of class properties. The property names are specified by the vector of DbDatum structures. The method returns the properties in the same DbDatum structures. To retrieve the properties use the extract operator >>. Here is an example of how to use the DbData type to specify and extract properties :

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: DbData db_data;
db_data.push_back(DbDatum(velocity));
db_data.push_back(DbDatum(acceleration));
db->get_class_property(StepperMotor, db_data);
float velocity, acceleration;
db_data[0] >> velocity;
db_data[1] >> acceleration;

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

52 void Database::put_class_property(string, DbData&)

Insert or update a list of properties for the specified class. The property names and their values are specified by the vector of DbDatum structures. Use the insert operator >> to insert the properties into the DbDatum structures. Here is an example of how to insert properties into the database using this method :

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: DbDatum velocity(velocity), acceleration(acceleration);
DbData db_data;
velocity << 100000.0;
acceleration << 500000.0;
db_data.push_back(velocity);
db_data.push_back(acceleration);
db->put_class_property(StepperMotor, db_data);

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

53 void Database::delete_class_property(string, DbData&)

Delete a list of properties for the specified class. The property names are specified by the vector of DbDatum structures. Here is an example of how to delete properties from the database using this method :

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: DbData db_data;
db_data.push_back(DbDatum(velocity));
db_data.push_back(DbDatum(acceleration));
db->delete_class_property(StepperMotor, db_data);

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

54 vector<DbHistory> Database::get_class_property_history(string &classname, string &propname)

Get the list of the last 10 modifications of the specifed class property. Note that propname can contain a wildcard character (eg: prop*). An example of usage of a similar function can be found in the documentation of the get_property_history() function.
Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device

55 DbDatum Database::get_class_attribute_list(string &classname,string &wildcard)

Query the database for a list of attributes defined for the specified class which match the specified wildcard.

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: string classname(MyClass);
string wildcard(*);
DbDatum db_datum = db->get_class_attribute_list(classname,wildcard);
vector<string> att_list;
db_datum >> att_list;

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: ConnectionFailed, CommunicationFailed, DevFailed from device

56 void Database::get_class_attribute_property(string, DbData&)

Query the database for a list of class attribute properties for the specified object. The attribute names are specified by the vector of DbDatum structures. The method returns all the properties for the specified attributes. The attribute names are returned with the number of properties specified as their value. The first DbDatum element of the returned DbData vector contains the first attribute name and the first attribute property number. The following DbDatum element contains the first attribute property name and property values. To retrieve the properties use the extract operator >>. Here is an example of how to use the DbData type to specify and extract attribute properties :

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: DbData db_data;
db_data.push_back(DbDatum(velocity));
db_data.push_back(DbDatum(acceleration));

db->get_class_attribute_property(StepperMotor, db_data);

float vel_max, vel_min, acc_max, acc_min;

for (int i=0; i< db_data.size(); i++)
{
     long nb_prop;
     string &att_name = db_data[i].name;
     db_data[i] >> nb_prop;
     i++;
     for (int k=0;k < nb_prop;k++)
     {
         string &prop_name = db_data[i].name;
         if (att_name == velocity)
         {
             if (prop_name == min)
                 db_data[i] >>  vel_min;
             else if (att_name == max)
                 db_data[i] >> vel_max;
         }
         else
         {
             if (prop_name == min)
                 db_data[i] >> acc_min;
             else
                 db_data[i] >> acc_max;
         }
         i++;
     }
}

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

57 void Database::put_class_attribute_property(string, DbData&)

Insert or update a list of attribute properties for the specified class. The attribute property names and their values are specified by the vector of DbDatum structures. Use the insert operator >> to insert the properties into the DbDatum structures. Here is an example of how to insert/update min, max properties for attribute velocity and min, max properties for attribute acceleration properties belonging to class StepperMotor into the database using this method :

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: DbDatum velocity(velocity), vel_min(min), vel_max(max);
DbDatum acceleration(acceleration), acc_min(min), acc_max(max);
DbData db_data;
velocity << 2;
vel_min << 0.0;
vel_max << 1000000.0;
db_data.push_back(velocity);
db_data.push_back(vel_min);
db_data.push_back(vel_max);
acceleration << 2;
acc_min << 0.0;
acc_max << 8000000;
db_data.push_back(acceleration);
db_data.push_back(acc_min);
db_data.push_back(acc_max);
db->put_class_attribute_property(StepperMotor, db_data);

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

58 void Database::delete_class_attribute_property(string, DbData&)

Delete a list of attribute properties for the specified class. The attribute names are specified by the vector of DbDatum structures. All properties belonging to the listed attributes are deleted. Here is an example of how to delete the unit property of the velocity attribute of the StepperMotor class from the database using this method :

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: DbData db_data;
db_data.push_back(DbDatum(velocity));
db_data.push_back(DbDatum(unit));
db->delete_class_attribute_property(StepperMotor, db_data);

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

59 vector<DbHistory> Database::get_class_attribute_property_history(string &devname, string &attname, string &propname)

Get the list of the last 10 modifications of the specifed class attribute property. Note that propname and attname can contain a wildcard character (eg: prop*). An example of usage of a similar function can be found in the documentation of the get_property_history() function.
Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device

60 void Database::get_alias(string dev_name, string &dev_alias)

Get the device alias name from its name. The device name is specified by dev_name and the device alias name is returned in dev_alias. If there is no alias defined for the device, a DevFailed exception is thrown.
Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_AliasNotDefined)

61 void Database::get_device_alias(string dev_alias, string &dev_name)

Get the device name from an alias. The device alias is specified by dev_alias and the device name is returned in dev_name. If there is no device with the given alias, a DevFailed exception is thrown.
Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_DeviceNotDefined)

62 void Database::get_attribute_alias(string attr_alias, string &attr_name)

Get the full attribute name from an alias. The attribute alias is specified by attr_alias and the full attribute name is returned in attr_name. If there is no attribute with the given alias, a DevFailed exception is thrown.
Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

63 void Database::put_attribute_alias(string &att_name, string &alias_name)

Set an alias for an attribute name. The attribute alias is specified by alias_name and the attribute name is specifed by att_name. If the given alias already exists, a DevFailed exception is thrown.
Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

64 void Database::delete_attribute_alias(string &alias_name)

Remove the alias associated to an attribute name.
Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

65 DbDatum Database::get_device_alias_list(string &filter)

Get device alias list. The parameter alias is a string to filter the alias list returned. Wildcard (*) is supported. For instance, if the string alias passed as the method parameter is initialised with only the * character, all the defined device alias will be returned. The DbDatum returned by this method is initialised with an array of strings and must be extracted into a vector<string>. If there is no alias with the given filter, the returned array will have a 0 size.

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: DbData db_data;
string filter(*);

db_data = db->get_device_alias_list(filter);
vector<string> al_list;
db_data >> al_list;
cout << al_list.size() << device alias defined in db << endl;
for (int i=0;i < al_list.size();i++)
cout << alias = << al_list[i] << endl;

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

66 DbDatum Database::get_attribute_alias_list(string &filter)

Get attribute alias list. The parameter alias is a string to filter the alias list returned. Wildcard (*) is supported. For instance, if the string alias passed as the method parameter is initialised with only the * character, all the defined attribute alias will be returned. The DbDatum returned by this method is initialised with an array of strings and must be extracted into a vector<string>. If there is no alias with the given filter, the returned array will have a 0 size.
Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

67 void Database::put_device_alias(string &dev_name,string &alias_name)

Create a device alias. Alias name has to be uniq within a Tango control system and you will receive an exception if the alias is already defined.
Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

68 void Database::delete_device_alias(string &alias_name)

Delete a device alias.
Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

11 Tango::DbDevice

A database object for a device which can be used to query or modify properties, import and export information for a device. This class provides an easy to use interface for device objects in the database. It uses the methods of the Database class therefore the reader is referred to these for the exact calling syntax and examples. The following methods are defined for the DbDevice class :

1 DbDevice::DbDevice(string &)

A constructor for a DbDevice object for a device in the TANGO database specified by the TANGO_HOST environment variable.

2 DbDevice::DbDevice(string &, Database *)

A constructor for a DbDevice object for the device in the specified database. This method reuses the Database supplied by the programmer.

3 DbDevImportInfo DbDevice::import_device()

Query the database for the import info of this device. Returns a DbDevImportInfo structure.
Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

4 void DbDevice::export_device(DbDevExportInfo&)

Update the export info for this device in the database.
Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

5 void DbDevice::add_device(DbDevInfo&)

Add/Update this device to the database.
Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

6 void DbDevice::delete_device()

Delete this device from the database.
Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

7 void DbDevice::get_property(DbData&)

Query the database for the list of properties of this device. See Database::get_device_property() for an example of how to specify and retrieve the properties.
Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

8 void DbDevice::put_property(DbData&)

Update the list of properties for this device in the database. See Database::put_device_property() for an example of how to specify the properties.
Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

9 void DbDevice::delete_property(DbData&)

Delete the list of specified properties for this device in the database. See Database::delete_property() for an example of how to specify the properties.
Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

10 void DbDevice::get_attribute_property(DbData&)

Query the database for the list of attribute properties of this device. See Database::get_device_attribute_property() for an example of how to specify and retrieve the properties.
Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

11 void DbDevice::put_attribute_property(DbData&)

Update the list of attribute properties for this device in the database. See Database::put_device_attribute_property() for an example of how to specify the properties.
Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

12 void DbDevice::delete_attribute_property(DbData&)

Delete all properties for the list of specified attributes for this device in the database. See Database::delete_device_attribute_property() for an example of how to specify the properties.
Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

12 Tango::DbClass

A database object for a class which can be used to query or modify class properties.

1 DbClass::DbClass(string)

A constructor for a DbClass object for a class in the TANGO database specified by the TANGO_HOST environment variable.

2 DbClass::DbClass(string, Database *)

A constructor for a DbClass object for the class in the specified database. This method reuses the Database supplied by the programmer.

3 void DbClass::get_property(DbData&)

Query the database for the list of properties of this class. See Database::get_class_property() for an example of how to specify and retrieve the properties.
Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

4 void DbClass::put_property(DbData&)

Update the list of properties for this class in the database. See Database::put_class_property() for an example of how to specify the properties.
Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

5 void DbClass::delete_property(DbData&)

Delete the list of specified properties for this class in the database. See Database::delete_property() for an example of how to specify the properties.
Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

6 void DbClass::get_attribute_property(DbData&)

Query the database for the list of attribute properties of this class. See Database::get_class_attribute_property() for an example of how to specify and retrieve the properties.
Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

7 void DbClass::put_attribute_property(DbData&)

Update the list of attribute properties for this class in the database. See Database::put_class_attribute_property() for an example of how to specify the properties.
Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

8 void DbClass::delete_attribute_property(DbData&)

Delete all properties for the list of specified attributes for this class in the database. See Database::delete_class_attribute_property() for an example of how to specify the properties.
Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

13 Tango::DbServer

A database object for a device server which can be used to query or modify server database information.

1 DbServer::DbServer(string)

A constructor for a DbServer object for a server in the TANGO database specified by the TANGO_HOST environment variable.

2 DbServer::DbServer(string, Database *)

A constructor for a DbServer object for the server in the specified database. This method reuses the Database supplied by the programmer.

3 void DbServer::add_server(DbDevInfos &)

4 void DbServer::delete_server()

Delete the device server and its associated devices from the database.
Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

5 void DbServer::export_server(DbDevExportInfos &)

Export a group of device to the database. The device names, IOR, class, server name, pid etc. are specified in the vector of DbDevExportInfo structures.
Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

6 void DbServer::unexport_server()

Mark all the devices exported by the server as un exported.
Exceptions: ConnectionFailed, CommunicationFailed, DevFailed from device (DB_SQLError)

14 Tango::DbDatum

A single database value which has a name, type, address and value and methods for inserting and extracting C++ native types. This is the fundamental type for specifying database properties. Every property has a name and has one or more values associated with it. The values can be inserted and extracted using the operators << and >> respectively. A status flag indicates if there is data in the DbDatum object or not. An additional flag allows the user to activate exceptions.

1 Operators

The insert and extract operators are specified for the following C++ types :

boolean
unsigned char
short
unsigned short
DevLong
DevULong
DevLong64
DevULong64
float
double
string
char* (insert only)
const char *
vector<string>
vector<short>
vector<unsigned short>
vector<DevLong>
vector<DevULong>
vector<DevLong64>
vector<DevULong64>
vector<float>
vector<double>

Here is an example of creating, inserting and extracting some DbDatum types :

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: DbDatum my_short(my_short), my_long(``my_long''), my_string(my_string);
DbDatum my_float_vector(my_float_vector), my_double_vector(my_double_vector);
string a_string;
short a_short;
DevLong a_long;
vector<float> a_float_vector;
vector<double> a_double_vector;
my_short << 100; // insert a short
my_short >> a_short; // extract a short
my_long << 1000; // insert a DevLong
my_long >> a_long; // extract a long
my_string << string(estas lista a bailar el tango ?); // insert a string
my_string >> a_string; // extract a string
my_float_vector << a_float_vector // insert a vector of floats
my_float_vector >> a_float_vector; // extract a vector of floats
my_double_vector << a_double_vector; // insert a vector of doubles
my_double_vector >> a_double_vector; // extract a vector of doubles

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: WrongData if requested

2 bool DbDatum::is_empty()

is_empty() is a boolean method which trues true or false depending on whether the DbDatum object contains data or not. It can be used to test whether a property is defined in the database or not e.g.

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: sl_props.push_back(parity_prop);
dbase->get_device_property(device_name, sl_props);
if (! parity_prop.is_empty())
{
parity_prop >> parity;
}
else
{
cout << device_name << has no parity defined in database ! << endl;
}

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

Exception: WrongData if requested

3 void DbDatum::exceptions(bitset<DbDatum::numFlags>)

Is a method which allows the user to switch on/off exception throwing for trying to extract data from an empty DbDatum object. The default is to not throw exception. The following flags are supported :

isempty_flag - throw a WrongData exception (reason = API_EmptyDbDatum) if user tries to extract data from an empty DbDatum object
wrongtype_flag - throw a WrongData exception (reason = API_IncompatibleArgumentType) if user tries to extract data with a type different than the type used for insertion

4 bitset<DbDatum::numFlags> exceptions()

Returns the whole exception flags.

5 void DbDatum::reset_exceptions(DbDatum::except_flags fl)

Resets one exception flag

6 void DbDatum::set_exceptions(DbDatum::except_flags fl)

Sets one exception flag
The following is an example of how to use these exceptions related methods

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

:      1  DbDatum da;
     2
     3  bitset<DbDatum::numFlags> bs = da.exceptions();
     4  cout << bs =  << bs << endl;
     5
     6  da.set_exceptions(DbDatum::wrongtype_flag);
     7  bs = da.exceptions();
     8
     9  cout << bs =  << bs << endl;

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

15 Tango::DbData

A vector of Tango::DbDatum structures. DbData is used to send or return one or more database properties or information. It is the standard input and output type for all methods which query and/or update properties in the database.

16 Exception

All the exception thrown by this API are Tango::DevFailed exception. This exception is a variable length array of Tango::DevError type. The Tango::DevError type is a four fields structure. These fields are :

A string describing the error type. This string replaces an error code and allows a more easy management of include files. This field is called reason
A string describing in plain text the reason of the error. This field is called desc
A string giving the name of the method which thrown the exception. This field is named origin
The error severity. This is an enumeration with three values which are WARN, ERR or PANIC. Its name is severity

This is a variable length array in order to transmit to the client what is the primary error reason. The sequence element 0 describes the primary error. An exception class hierarchy has been implemented within the API to ease API programmers task. All the exception classes inherits from the Tango::DevFailed class. Except for the NamedDevFaildeList exception class, they don't add any new fields to the exception, they just allow easy catching. Exception classes thrown only by the API layer are :

ConnectionFailed
CommunicationFailed
WrongNameSyntax
NonDbDevice
WrongData
NonSupportedFeature
AsynCall
AsynReplyNotArrived
EventSystemFailed
NamedDevFailedList
DeviceUnlocked

On top of these classes, exception thrown by the device (Tango::DevFailed exception) are directly passed to the client.

1 The ConnectionFailed exception

This exception is thrown when a problem occurs during the connection establishment between the application and the device. The API is stateless. This means that DeviceProxy constructors filter most of the exception except for cases described in the following table.

Method name	device type	error type	Level	reason
		TANGO_HOST not set	0	API_TangoHostNotSet
	with	Device not defined in db	0	DB_DeviceNotDefined
	database	or	1	API_CommandFailed
DeviceProxy		Alias not defined in db	2	API_DeviceNotDefined
constructor	with database	Database server	0	API_CorbaException
	specified in dev name	not running	1	API_CantConnectToDatabase
	without	Server running but device	0	API_CorbaException
	database	not defined in server	1	API_DeviceNotExported
		TANGO_HOST not set	0	API_TangoHostNotSet
			0	DB_DeviceNotDefined
		Device not defined in db	1	API_CommandFailed
AttributeProxy	with		2	API_DeviceNotDefined
constructor	database		0	DB_SQLError
		Alias not defined in db	1	API_CommandFailed
			2	API_AliasNotDefined
	with database	Database server	0	API_CorbaException
	specified in dev name	not running	1	API_CantConnectToDatabase
DeviceProxy	without	Server not	0	API_CorbaException
or	database	running	1	API_ServerNotRunning
AttributeProxy		Server not running	0	API_DeviceNotExported
method call	with	Dead	0	API_CorbaException
(except	database	server	1	API_CantConnectToDevice
cmd_inout		Dead database server	0	API_CorbaException
read_attribute)		when reconnection needed	1	API_CantConnectToDatabase
	without	Server	0	API_CorbaException
DeviceProxy	database	not	1	API_ServerNotRunning
cmd_inout		running	2	API_CommandFailed
and		Server	0	API_DeviceNotExported
read_attribute		not running	1	API_CommandFailed
			0	API_CorbaException
or	with	Dead	1	API_CantConnectToDevice
AttributeProxy	database	server	2	API_CommandFailed
read				or API_AttributeFailed
and		Dead database	0	API_CorbaException
write		server when reconnection	1	API_CantConnectToDatabase
		needed	2	API_CommandFailed

The desc DevError structure field allows a user to get more precise information. These informations are :

DB_DeviceNotDefined: The name of the device not defined in the database
API_CommandFailed: The device and command name
API_CantConnectToDevice: The device name
API_CorbaException: The name of the CORBA exception, its reason, its locality, its completed flag and its minor code
API_CantConnectToDatabase: The database server host and its port number
API_DeviceNotExported: The device name

2 The CommunicationFailed exception

This exception is thrown when a communication problem is detected during the communication between the client application and the device server. It is a two levels Tango::DevError structure. In case of time-out, the DevError structures fields are:

Level	Reason	Desc	Severity
0	API_CorbaException	CORBA exception fields translated into a string	ERR
1	API_DeviceTimedOut	String with time-out value and device name	ERR

For all other communication errors, the DevError structures fields are:

Level	Reason	Desc	Severity
0	API_CorbaException	CORBA exception fields translated into a string	ERR
1	API_CommunicationFailed	String with device, method, command/attribute name	ERR

3 The WrongNameSyntax exception

This exception has only one level of Tango::DevError structure. The possible value for the reason field are :

API_UnsupportedProtocol: This error occurs when trying to build a DeviceProxy or an AttributeProxy instance for a device with an unsupported protocol. Refer to the appendix on device naming syntax to get the list of supported database modifier
API_UnsupportedDBaseModifier: This error occurs when trying to build a DeviceProxy or an AttributeProxy instance for a device/attribute with a database modifier unsupported. Refer to the appendix on device naming syntax to get the list of supported database modifier
API_WrongDeviceNameSyntax: This error occurs for all the other error in device name syntax. It is thrown by the DeviceProxy class constructor.
API_WrongAttributeNameSyntax: This error occurs for all the other error in attribute name syntax. It is thrown by the AttributeProxy class constructor.
API_WrongWildcardUsage: This error occurs if there is a bad usage of the wildcard character

4 The NonDbDevice exception

This exception has only one level of Tango::DevError structure. The reason field is set to API_NonDatabaseDevice. This exception is thrown by the API when using the DeviceProxy or AttributeProxy class database access for non-database device.

5 The WrongData exception

This exception has only one level of Tango::DevError structure. The possible value for the reason field are :

API_EmptyDbDatum: This error occurs when trying to extract data from an empty DbDatum object
API_IncompatibleArgumentType: This error occurs when trying to extract data with a type different than the type used to send the data
API_EmptyDeviceAttribute: This error occurs when trying to extract data from an empty DeviceAttribute object
API_IncompatibleAttrArgumentType: This error occurs when trying to extract attribute data with a type different than the type used to send the data
API_EmptyDeviceData: This error occurs when trying to extract data from an empty DeviceData object
API_IncompatibleCmdArgumentType: This error occurs when trying to extract command data with a type different than the type used to send the data

6 The NonSupportedFeature exception

This exception is thrown by the API layer when a request to a feature implemented in Tango device interface release n is requested for a device implementing Tango device interface n-x. There is one possible value for the reason field which is API_UnsupportedFeature.

7 The AsynCall exception

This exception is thrown by the API layer when a the asynchronous model id badly used. This exception has only one level of Tango::DevError structure. The possible value for the reason field are :

API_BadAsynPollId: This error occurs when using an asynchronous request identifier which is not valid any more.
API_BadAsyn: This error occurs when trying to fire callback when no callback has been previously registered
API_BadAsynReqType: This error occurs when trying to get result of an asynchronous request with an asynchronous request identifier returned by a non-coherent asynchronous request (For instance, using the asynchronous request identifier returned by a command_inout_asynch() method with a read_attribute_reply() attribute).

8 The AsynReplyNotArrived exception

This exception is thrown by the API layer when:

a request to get asynchronous reply is made and the reply is not yet arrived
a blocking wait with timeout for asynchronous reply is made and the timeout expired.

There is one possible value for the reason field which is API_AsynReplyNotArrived.

9 The EventSystemFailed exception

This exception is thrown by the API layer when subscribing or unsubscribing from an event failed. This exception has only one level of Tango::DevError structure. The possible value for the reason field are :

API_NotificationServiceFailed: This error occurs when the subscribe_event() method failed trying to access the CORBA notification service
API_EventNotFound: This error occurs when you are using an incorrect event_id in the unsubscribe_event() method
API_InvalidArgs: This error occurs when NULL pointers are passed to the subscribe or unsubscribe event methods
API_MethodArgument: This error occurs when trying to subscribe to an event which has already been subsribed to
API_DSFailedRegisteringEvent: This error means that the device server to which the device belongs to failed when it tries to register the event. Most likely, it means that there is no event property defined
API_EventNotFound: Occurs when using a wrong event identifier in the unsubscribe_event method

10 The NamedDevFailedList exception

This exception is only thrown by the DeviceProxy::write_attributes() method. In this case, it is necessary to have a new class of exception to transfer the error stack for several attribute(s) which failed during the writing. Therefore, this exception class contains for each attributes which failed :

The name of the attribute
Its index in the vector passed as argumen tof the write_attributes() method
The error stack as described in

1 long NamedDevFailedList::get_faulty_attr_nb()

Returns the number of attributes which failed during the write_attribute call.

2 vector<NamedDevFailed> NamedDevErrorList::err_list

Public data member of the NamedDevFailedList. There is one element in this vector for each attribute which failed during its writing.

3 string NamedDevFailed::name

Public data member of the NamedDevFailed class. It contains the name of the attribute which failed.

4 long NamedDevFailed::idx_in_call

Public data member of the NamedDevFailed class. It contains the index in the write_attributes method parameter vector of the attribute which failed.

5 DevErrorList NamedDevFailed::err_stack

Public data member of the NamedDevFailed class. This is the error stack.
The following piece of code is an example of how to use this class exception

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

: catch (Tango::NamedDevFailed &e)
{
   long nb_faulty = e.get_faulty_attr_nb();
   for (long i = 0;i < nb_faulty;i++)
   {
       cout << Attribute  << e.err_list[i].name <<  failed! << endl;
       for (long j = 0;j < e.err_list[i].err_stack.length();j++)
       {
           cout << Reason [ << j << ] =  << e.err_list[i].err_stack[j].reason;
           cout << Desc [ << j << ] =  << e.err_list[i].err_stack[j].desc;
       }
   }
}

$\begin{picture}(0,0)\thicklines \put(0,0){\line(1,0){400}} \end{picture}$

This exception inherits from Tango::DevFailed. It is possible to catch it with a catch DevFailed catch block. In this case, like any other DevFailed exception, there is only one error stack. This stack is initialised with the name of all the attributes which failed in its reason field.

11 The DeviceUnlocked exception

This exception is thrown by the API layer when a device locked by the process has been unlocked by an admin client. This exception has two levels of Tango::DevError structure. There is only possible value for the reason field which is

API_DeviceUnlocked: The device has been unlocked by another client (administration client)

The first level is the message reported by the Tango kernel from the server side. The second layer is added by the client API layer with informations on which API call generates the exception and device name.

17 Reconnection and exception

The Tango API automatically manages re-connection between client and server in case of communication error during a network access between a client and a server. The transparency reconnection mode allows a user to be (or not be) informed that automatic reconnection took place. If the transparency reconnection mode is not set, when a communication error occurs, an exception is returned to the caller and the connection is internally marked as bad. On the next try to contact the device, the API will try to re-build the network connection. If the transparency reconnection mode is set, the API will try to re-build the network connection has soon as the communication error occurs and the caller is not informed. Several cases are possible. They are summarized in the following table:

Case	Server state	call nb	exception (transparency false)	exception (transparency true)
	Server killed before call n	n	CommunicationFailed	ConnectionFailed
Server killed	down	n+1	ConnectionFailed(2 levels)	idem
and re-started	down	n + 2	idem	idem
	Running	n + x	No exception	No exception
	Server died before call n	n	CommunicationFailed	ConnectionFailed
Server died	died	n + 1	ConnectionFailed (3 levels)	idem
and re-started	died	n + 2	idem	idem
	Running	n + x	No exception	No exception
Server killed	Server killed and re-started before call n	n	CommunicationFailed	No exception
and re-started	Running	n+x	No exception	No exception
Server died	Server died and re-started before call n	n	CommunicationFailed	No exception
and re-started	Running	n + x	No exception	No exception

Please note that the timeout case is managed differently because it will not enter the re-connection system. The transparency reconnection mode is set by default to true for Tango version 5.5!

Emmanuel Taurel 2012-06-06