Exception

Tango API exceptions

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 NamedDevFailedList 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.

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
DeviceProxy constructor	with database	TANGO_HOST not set	0	API_TangoHostNotSet
		Device not defined in db or Alias not defined in db	0	DB_DeviceNotDefined
			1	API_CommandFailed
			2	API_DeviceNotDefined
	with database specified in dev name	database server not running	0	API_CorbaException
			1	API_CantConnectToDatabase
	without database	Server running but device not defined in server	0	API_CorbaException
			1	API_DeviceNotExported
AttributeProxy constructor	with database	TANGO_HOST not set	0	API_TangoHostNotSet
		Device not defined in db	0	DB_DeviceNotDefined
			1	API_CommandFailed
			2	API_DeviceNotDefined
		Alias not defined in db	0	DB_SQLError
			1	API_CommandFailed
			2	API_AliasNotDefined
	with database specified in dev name	database server not running	0	API_CorbaException
			1	API_CantConnectToDatabase
DeviceProxy or AttributeProxy method call (except command_inout, read_attribute)	without database	Server not running	0	API_CorbaException
			1	API_ServerNotRunning
	with database	Server ot running	0	API_DeviceNotExported
		Dead server	0	API_CorbaException
			1	API_CantConnectToDevice
		Dead database server when reconnection needed	0	API_CorbaException
			1	API_CantConnectToDatabase
DeviceProxy command_inout and read_attribute or AttributeProxy read and write	without database	Server not running	0	API_DeviceNotExported
			1	API_ServerNotRunning
			2	API_CommandFailed
	with database	Server not running	0	API_DeviceNotExported
			1	API_CommandFailed
		Dead server	0	API_CorbaException
			1	API_CantConnectToDevice
			2	API_CommandFailed or API_AttributeFailed
		Dead database server when re-connection needed	0	API_DeviceNotExported
			1	API_CantConnectToDatabase
			2	API_CommandFailed

The desc DevError structure field allows a user to get more precise information. These informations are (according to the reason field) :

• 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

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

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

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.

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

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.

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

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.

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 subscribed 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

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 argument tof the write_attributes() method
• The error stack

The following piece of code is an example of how to use this class exception

catch (Tango::NamedDevFailedList &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;
      }
   }
}

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.

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 information on which API call generates the exception and device name.