The TANGO Control System Manual Version 8.1 The TANGO Team June 27, 2013 Contents 1 Introduction 22 1.1 Introduction to device server................................. 22 1.2 Device server history..................................... 23 2 Getting Started 24 2.1 A Java TANGO client..................................... 24 2.2 A C++ TANGO client..................................... 25 2.3 A TANGO device server................................... 26 2.3.1 The commands and attributes code in C++...................... 26 2.3.1.1 The DevSimple command......................... 27 2.3.1.2 The DevArray command......................... 27 2.3.1.3 The DevString command......................... 28 2.3.1.4 The DevStrArray command........................ 28 2.3.1.5 The DevStruct command......................... 29 2.3.1.6 The three attributes............................ 30 2.3.2 The commands and attributes code in java...................... 31 2.3.2.1 The DevSimple command......................... 32 2.3.2.2 The DevArray command......................... 32 2.3.2.3 The DevString command......................... 33 2.3.2.4 The DevStrArray command........................ 33 2.3.2.5 The DevStruct command......................... 33 2.3.2.6 The three attributes............................ 34 3 The TANGO device server model 38 3.1 Introduction to CORBA.................................... 38 3.2 The model........................................... 39 3.3 The device........................................... 39 3.3.1 The commands.................................... 39 3.3.2 The TANGO attributes................................ 40 3.3.3 Command or attributes ?............................... 40 3.3.4 The CORBA attributes................................ 40 3.3.5 The remaining CORBA operations.......................... 41 3.3.6 The special case of the device state and status.................... 41 3.3.7 The device polling.................................. 41 3.4 The server........................................... 42 3.5 The Tango Logging Service.................................. 42 3.6 The database......................................... 42 3.7 The controlled access..................................... 43 3.8 The Application Programmers Interfaces........................... 43 3.8.1 Rules of the API................................... 43 3.8.2 Communication between client and server using the API.............. 44 3.8.3 Tango events..................................... 44 1 CONTENTS 2 4 Writing a TANGO client using TANGO APIs 48 4.1 Introduction.......................................... 48 4.2 Getting Started........................................ 48 4.3 Basic Philosophy....................................... 48 4.4 Data types........................................... 48 4.5 Request model........................................ 49 4.5.1 Synchronous model.................................. 50 4.5.2 Asynchronous model................................. 50 4.6 Events............................................. 51 4.6.1 Introduction...................................... 51 4.6.2 Event definition.................................... 51 4.6.3 Event types...................................... 51 4.6.4 Event filtering (Removed in Tango release 8 and above).............. 52 4.6.5 Application Programmer’s Interface......................... 53 4.6.5.1 Configuring events............................. 54 4.6.5.1.1 change.............................. 54 4.6.5.1.2 periodic............................. 54 4.6.5.1.3 archive.............................. 54 4.6.5.2 C++ Clients................................ 54 4.6.5.2.1 Subscribing to events...................... 55 4.6.5.2.2 The CallBack class....................... 55 4.6.5.2.3 Unsubscribing from an event.................. 56 4.6.5.2.4 Extract buffered event data................... 56 4.6.5.2.5 Example............................. 57 4.6.5.3 Java Clients................................ 59 4.6.5.3.1 Using CallBack......................... 59 4.6.5.3.2 Using listeners.......................... 59 4.7 Group............................................. 60 4.7.1 Getting started with Tango group.......................... 60 4.7.2 Forward or not forward?............................... 63 4.7.3 Executing a command................................ 63 4.7.3.1 Obtaining command results........................ 63 4.7.3.2 Case 1: a command, no argument..................... 65 4.7.3.3 A few words on error handling and data extraction............ 65 4.7.3.4 Case 2: a command, one argument.................... 70 4.7.3.5 Case 3: a command, several arguments.................. 71 4.7.4 Reading attribute(s)................................. 75 4.7.4.1 Obtaining attribute values......................... 75 4.7.4.2 A few words on error handling and data extraction............ 75 4.7.5 Writing an attribute................................. 78 4.7.5.1 Obtaining acknowledgement....................... 78 4.7.5.2 Case 1: one value for all devices..................... 78 4.7.5.3 Case 2: a specific value per device.................... 81 4.8 Device locking........................................ 83 4.9 Reconnection and exception................................. 84 4.10 Thread safety......................................... 84 4.11 Compiling and linking a Tango client............................. 85 5 TANGO Java API 86 5.1 Introduction.......................................... 87 5.1.1 Description...................................... 87 5.1.2 Basic Philosophy................................... 87 5.1.3 Classes........................................ 88 5.1.3.1 Data object classes............................. 88 CONTENTS 3 5.1.3.2 Asynchronous callback related classes.................. 88 5.1.3.3 Devices and Database access classes................... 88 5.1.4 Reporting errors................................... 88 5.1.5 Compiling a Java client................................ 89 5.1.5.1 Supported java release........................... 89 5.1.5.2 Setting CLASSPATH and other environment variables.......... 89 5.2 Reference manual....................................... 89 6 The TANGO C++ Application Programmer Interface 90 6.1 Tango::DeviceProxy()..................................... 90 6.1.1 Constructors..................................... 90 6.1.1.1 DeviceProxy::DeviceProxy(string &name, CORBA::ORB *orb=NULL) 90 6.1.1.2 DeviceProxy::DeviceProxy(const char *name, CORBA::ORB *orb = NULL) 90 6.1.2 Miscellaneous methods................................ 90 6.1.2.1 DeviceInfo DeviceProxy::info()...................... 90 6.1.2.2 DevState DeviceProxy::state()....................... 91 6.1.2.3 string DeviceProxy::status()........................ 91 6.1.2.4 int DeviceProxy::ping().......................... 91 6.1.2.5 void DeviceProxy::set_timeout_millis(int timeout)............ 91 6.1.2.6 int DeviceProxy::get_timeout_millis().................. 92 6.1.2.7 int DeviceProxy::get_idl_version().................... 92 6.1.2.8 void DeviceProxy::set_source(DevSource source)............ 92 6.1.2.9 DevSource DeviceProxy::get_source().................. 92 6.1.2.10 vector<string> *DeviceProxy::black_box(int n)............. 92 6.1.2.11 string DeviceProxy::name()........................ 92 6.1.2.12 string DeviceProxy::adm_name()..................... 92 6.1.2.13 string DeviceProxy::dev_name()..................... 92 6.1.2.14 string DeviceProxy::description()..................... 92 6.1.2.15 DbDevImportInfo DeviceProxy::import_info().............. 93 6.1.2.16 void DeviceProxy::set_transparency_reconnection(bool flag)...... 93 6.1.2.17 bool DeviceProxy::get_transparency_reconnection()........... 93 6.1.2.18 string DeviceProxy::alias()........................ 93 6.1.2.19 AccessControlType DeviceProxy::get_access_right().......... 93 6.1.3 Synchronous command oriented methods...................... 93 6.1.3.1 CommandInfo DeviceProxy::command_query(string command).... 93 6.1.3.2 CommandInfoList *DeviceProxy::command_list_query()........ 93 6.1.3.3 DeviceData DeviceProxy::command_inout(string)............ 94 6.1.3.4 DeviceData DeviceProxy::command_inout(const char *)........ 94 6.1.3.5 DeviceData Deviceproxy::command_inout(string, DeviceData &).... 94 6.1.3.6 DeviceData DeviceProxy::command_inout(const char *, DeviceData &) 94 6.1.3.7 vector<DeviceDataHistory> *command_history(string &, int)...... 94 6.1.3.8 DeviceDataHistoryList *command_history(const char *, int)...... 95 6.1.4 Synchronous attribute related methods........................ 95 6.1.4.1 Compatibility between Tango release 4 and release 5 regarding attribute properties................................. 95 6.1.4.2 AttributeInfoEx DeviceProxy::attribute_query(string attribute)..... 95 6.1.4.3 AttributeInfoList * DeviceProxy::attribute_list_query()......... 95 6.1.4.4 AttributeInfoListEx * DeviceProxy::attribute_list_query_ex()...... 95 6.1.4.5 vector<string> *DeviceProxy::get_attribute_list()............ 96 6.1.4.6 AttributeInfoList *DeviceProxy::get_attribute_config(vector<string>&) 96 6.1.4.7 AttributeInfoListEx *DeviceProxy::get_attribute_config_ex(vector<string>&) 96 6.1.4.8 AttributeInfoEx DeviceProxy::get_attribute_config(string&)....... 97 6.1.4.9 void DeviceProxy::set_attribute_config(AttributeInfoList &)...... 97 6.1.4.10 void DeviceProxy::set_attribute_config(AttributeInfoListEx &)..... 98 CONTENTS 4 6.1.4.11 vector<DeviceAttribute> *DeviceProxy::read_attributes(vector<string>&) 98 6.1.4.12 DeviceAttribute DeviceProxy::read_attribute(string&).......... 98 6.1.4.13 DeviceAttribute DeviceProxy::read_attribute(const char