#LyX 2.1 created this file. For more info see http://www.lyx.org/
\lyxformat 474
\begin_document
\begin_header
\textclass book
\begin_preamble
\usepackage{a4wide}
\end_preamble
\use_default_options false
\maintain_unincluded_children false
\language english
\language_package default
\inputencoding utf8
\fontencoding global
\font_roman default
\font_sans default
\font_typewriter default
\font_math auto
\font_default_family default
\use_non_tex_fonts false
\font_sc false
\font_osf false
\font_sf_scale 100
\font_tt_scale 100
\graphics default
\default_output_format default
\output_sync 0
\bibtex_command default
\index_command default
\paperfontsize default
\spacing single
\use_hyperref false
\papersize default
\use_geometry false
\use_package amsmath 1
\use_package amssymb 1
\use_package cancel 1
\use_package esint 0
\use_package mathdots 1
\use_package mathtools 1
\use_package mhchem 1
\use_package stackrel 1
\use_package stmaryrd 1
\use_package undertilde 1
\cite_engine basic
\cite_engine_type default
\biblio_style plain
\use_bibtopic false
\use_indices false
\paperorientation portrait
\suppress_date false
\justification true
\use_refstyle 0
\index Index
\shortcut idx
\color #008000
\end_index
\secnumdepth 5
\tocdepth 5
\paragraph_separation indent
\paragraph_indentation default
\quotes_language english
\papercolumns 1
\papersides 2
\paperpagestyle default
\tracking_changes false
\output_changes false
\html_math_output 0
\html_css_as_file 0
\html_be_strict false
\end_header

\begin_body

\begin_layout Chapter
Writing a TANGO device server
\end_layout

\begin_layout Section
The device server framework
\end_layout

\begin_layout Standard
This chapter will present the TANGO device server framework.
 It will introduce what is the device server pattern and then it will describe
 a complete device server framework.
 A definition of classes used by the device server framework is given in
 this chapter.
 This manual is not intended to give the complete and detailed description
 of classes data member or methods, refer to 
\begin_inset CommandInset citation
LatexCommand cite
key "TANGO_ref_man"

\end_inset

 to get this full description.
 But first, the naming convention used in this project is detailed.
\end_layout

\begin_layout Standard
The aim of the class definition given in this chapter is only to help the
 reader to understand how a TANGO device server works.
 For a detailed description of these classes (and their methods), refer
 to chapter 
\begin_inset CommandInset ref
LatexCommand ref
reference "Writing_chapter"

\end_inset

 or to 
\begin_inset CommandInset citation
LatexCommand cite
key "TANGO_ref_man"

\end_inset

.
\end_layout

\begin_layout Subsection
Naming convention and programming language
\end_layout

\begin_layout Standard
TANGO fully supports three different programming languages which are 
\series bold
C++, Java
\series default
 and 
\series bold
Python
\series default
.
 This documentation focuses on C++ Tango class.
 For Java and Python Tango class, have a look at the 
\begin_inset CommandInset href
LatexCommand href
name "Tango web"
target "http://www.tango-controls.org"

\end_inset

 pages where similar chapter for Java and Python are available.
\end_layout

\begin_layout Standard
Every software project needs a naming
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
naming
\end_layout

\end_inset

 convention.
 The naming convention adopted for the TDSOM is very simple and only defines
 two guidelines which are:
\end_layout

\begin_layout Itemize
Class names start with uppercase and use capitalization for compound words
 (For instance MyClassName).
\end_layout

\begin_layout Itemize
Method names are in lowercase and use underscores for compound words (For
 instance my_method_name).
\end_layout

\begin_layout Subsection
The device pattern
\end_layout

\begin_layout Standard
Device server are written using the Device pattern
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
pattern
\end_layout

\end_inset

.
 The aim of this pattern is to provide the control programmer with a framework
 in which s/he can develop new control objects.
 The device pattern uses other design patterns like the Singleton
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
singleton
\end_layout

\end_inset

 and Command patterns.
 These patterns are fully described in 
\begin_inset CommandInset citation
LatexCommand cite
key "Patterns"

\end_inset

.
 The device pattern class diagram for stepper motor device is drawn in figure
 
\begin_inset CommandInset ref
LatexCommand ref
reference "Dvice pattern figure"

\end_inset


\begin_inset Float figure
wide false
sideways false
status open

\begin_layout Plain Layout
\align center
\begin_inset Float figure
wide false
sideways false
status open

\begin_layout Plain Layout
\begin_inset Caption Standard

\begin_layout Plain Layout
Device pattern class diagram
\end_layout

\end_inset


\end_layout

\begin_layout Plain Layout
\begin_inset Graphics
	filename device_et.eps
	width 14cm
	height 18cm

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Plain Layout
\begin_inset Caption Standard

\begin_layout Plain Layout
Device pattern class diagram
\begin_inset CommandInset label
LatexCommand label
name "Dvice pattern figure"

\end_inset


\end_layout

\end_inset


\end_layout

\end_inset

.
 In this figure, only classes surrounded with a dash line square are device
 specific.
 All the other classes are part of the TDSOM core and are developed by the
 Tango system team.
 Different kind of classes are used by the device pattern.
 
\end_layout

\begin_layout Itemize
Three of them are root classes and it is only necessary to inherit from
 them.
 These classes are the 
\series bold
DeviceImpl
\series default

\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DeviceImpl
\end_layout

\end_inset

, 
\series bold
DeviceClass
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DeviceClass
\end_layout

\end_inset


\series default
 and 
\series bold
Command
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Command
\end_layout

\end_inset


\series default
 classes.
 
\end_layout

\begin_layout Itemize
Classes necessary to implement commands
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
command
\end_layout

\end_inset

.
 The TDSOM supports two ways to create command : Using inheritance
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
inheritance
\end_layout

\end_inset

 or using the template
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
template
\end_layout

\end_inset

 command model.
 It is possible to mix model within the same device pattern
\end_layout

\begin_deeper
\begin_layout Enumerate
Using 
\series bold
inheritance
\series default
.
 This model of creating command heavily used the polymorphism offered by
 each modern object oriented programming language.
 In this schema, each command supported by a device via the command_inout
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
command-inout
\end_layout

\end_inset

 or command_inout_async
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
command-inout-async
\end_layout

\end_inset

 operation is implemented by a separate class.
 The Command
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Command
\end_layout

\end_inset

 class is the root class for each of these classes.
 It is an abstract class.
 A 
\emph on
execute
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
execute
\end_layout

\end_inset


\emph default
 method must be defined in each sub-class.
 A 
\emph on
is_allowed
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
is-allowed
\end_layout

\end_inset


\emph default
 method may also be re-defined in each class if the default one does not
 fulfill all the needs
\begin_inset Foot
status open

\begin_layout Plain Layout
The default is_allowed method behavior is to always allows the command
\end_layout

\end_inset

.
 In our stepper motor device server example, the DevReadPosition command
 follows this model.
\end_layout

\begin_layout Enumerate
Using the 
\series bold
template command
\series default
 model.
 Using this model, it is not necessary to write one class for each command.
 You create one instance of classes already defined in the TDSOM for each
 command.
 The link between command name and method which need to be executed is done
 through pointers to method.
 To support different kind of command, four classes are part of the TDSOM.
 These classes are :
\end_layout

\begin_deeper
\begin_layout Enumerate
The 
\series bold
TemplCommand
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
TemplCommand
\end_layout

\end_inset


\series default
 class for command without input or output parameter
\end_layout

\begin_layout Enumerate
The 
\series bold
TemplCommandIn
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
TemplCommandIn
\end_layout

\end_inset


\series default
 class for command with input parameter but without output parameter
\end_layout

\begin_layout Enumerate
The 
\series bold
TemplCommandOu
\series default
t
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
TemplCommandOut
\end_layout

\end_inset

 class for command with output parameter but without input parameter
\end_layout

\begin_layout Enumerate
The 
\series bold
TemplCommandInOut
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
TemplCommandInOut
\end_layout

\end_inset


\series default
 class for all the remaining commands
\end_layout

\end_deeper
\end_deeper
\begin_layout Itemize
Classes necessary to implement TANGO device attributes
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
attribute
\end_layout

\end_inset

.
 All these classes are part of the TANGO core classes.
 These classes are the 
\series bold
MultiAttribute
\series default

\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
MultiAttribute
\end_layout

\end_inset

, 
\series bold
Attribute
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Attribute
\end_layout

\end_inset


\series default
, 
\series bold
WAttribute
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
WAttribute
\end_layout

\end_inset


\series default
, 
\series bold
Attr
\series default

\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Attr
\end_layout

\end_inset

, 
\series bold
SpectrumAttr
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
SpectrumAttr
\end_layout

\end_inset


\series default
 and 
\series bold
ImageAttr
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
ImageAttr
\end_layout

\end_inset


\series default
 classes.
 The last three are used to create user attribute.
 Each attribute supported by a device is implemented by a separate class.
 The Attr class is the root class for each of these classes.
 According to the attribute data format, the user class implementing the
 attribute must inherit from the Attr, SpectrumAttr or ImageAtttr class.
 SpectrumAttr class inherits from Attr class and Image Attr class inherits
 from the SpectrumAttr class.
 The Attr base class defined three methods called 
\emph on
is_allowed
\emph default

\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
is-allowed
\end_layout

\end_inset

, 
\emph on
read
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
read
\end_layout

\end_inset


\emph default
 and 
\emph on
write
\emph default

\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
write
\end_layout

\end_inset

.
 These methods may be redefined in sub-classes in order to implement the
 attribute specific behaviour.
\end_layout

\begin_layout Itemize
The other are device specific.
 For stepper motor device, they are named StepperMotor, StepperMotorClass
 and DevReadPosition.
\end_layout

\begin_layout Subsubsection
The Tango base class (DeviceImpl
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DeviceImpl
\end_layout

\end_inset

 class)
\end_layout

\begin_layout Paragraph
Description
\end_layout

\begin_layout Standard
This class is the device root class and is the link between the Device pattern
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
pattern
\end_layout

\end_inset

 and CORBA
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
CORBA
\end_layout

\end_inset

.
 It inherits from CORBA classes and implements all the methods needed to
 execute CORBA operations and attributes.
 For instance, its method 
\emph on
command_inout
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
command-inout
\end_layout

\end_inset


\emph default
 is executed when a client requests a command_inout operation.
 The method 
\emph on
name
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
name
\end_layout

\end_inset


\emph default
 of the DeviceImpl class is executed when a client requests the name CORBA
 attribute.
 This class also encapsulates some key device data like its name
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
name
\end_layout

\end_inset

, its state
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
state
\end_layout

\end_inset

, its status
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
status
\end_layout

\end_inset

, its black box
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
black-box
\end_layout

\end_inset

....
 This class is an abstract class and cannot be instantiated as is.
 
\end_layout

\begin_layout Paragraph
Contents
\end_layout

\begin_layout Standard
The contents of this class can be summarized as :
\end_layout

\begin_layout Itemize
Different constructors and one destructor
\end_layout

\begin_layout Itemize
Methods to access instance data members outside the class or its derivate
 classes.
 These methods are necessary because data members are declared as protected.
\end_layout

\begin_layout Itemize
Methods triggered by CORBA attribute request
\end_layout

\begin_layout Itemize
Methods triggered by CORBA operation
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
operation
\end_layout

\end_inset

 request
\end_layout

\begin_layout Itemize
The 
\emph on
init_device
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
init-device
\end_layout

\end_inset

()
\emph default
 method.
 This method makes the class abstract.
 It should be implemented by a sub-class.
 It is used by the inherited classes constructors.
\end_layout

\begin_layout Itemize
Methods triggered by the automatically added State
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
State
\end_layout

\end_inset

 and Status
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Status
\end_layout

\end_inset

 commands.
 These methods are declared virtual and therefore can be redefined in sub-classe
s.
 These two commands are automatically added to the list of commands defined
 for a class of devices.
 They are discussed in chapter 
\begin_inset CommandInset ref
LatexCommand ref
reference "Auto_cmd"

\end_inset


\end_layout

\begin_layout Itemize
A method called 
\emph on
always_executed_hook()
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
always-executed-hook
\end_layout

\end_inset


\emph default
 always executed for each command before the device state is tested for
 command execution.
 This method gives the programmer a hook where he(she) can program some
 mandatory action which must be done before any command execution.
 An example of the such action is an hardware access to the device to read
 its real hardware state.
\end_layout

\begin_layout Itemize
A method called 
\emph on
read_attr_hardware()
\emph default

\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
read-attr-hardware
\end_layout

\end_inset

 triggered by the read_attributes
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
read-attributes
\end_layout

\end_inset

 CORBA operation.
 This method is called once for each read_attributes
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
read-attributes
\end_layout

\end_inset

 call.
 This method is virtual and may be redefined in sub-classes.
 
\end_layout

\begin_layout Itemize
A method called 
\emph on
write_attr_hardware()
\emph default

\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
write-attr-hardware
\end_layout

\end_inset

 triggered by the write_attributes
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
write-attributes
\end_layout

\end_inset

 CORBA operation.
 This method is called once for each write_attributes
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
write-attributes
\end_layout

\end_inset

 call.
 This method is virtual and may be redefined in sub-classes.
 
\end_layout

\begin_layout Itemize
Methods for signal
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
signal
\end_layout

\end_inset

 management (C++ specific) 
\end_layout

\begin_layout Itemize
Data members like the device name
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
name
\end_layout

\end_inset

, the device status
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
status
\end_layout

\end_inset

, the device state
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
state
\end_layout

\end_inset


\end_layout

\begin_layout Itemize
Some private methods and data members
\end_layout

\begin_layout Subsubsection
The DbDevice class
\end_layout

\begin_layout Standard
Each DeviceImpl instance is an aggregate with one instance of the DbDevice
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DbDevice
\end_layout

\end_inset

 class.
 This DbDevice class can be used to query or modify device properties
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
properties
\end_layout

\end_inset

.
 It provides an easy to use interface for device objects in the database.
 The description of this class can be found in the Tango API reference documenta
tion available on the Tango WEB pages.
\end_layout

\begin_layout Subsubsection
The Command class
\end_layout

\begin_layout Paragraph
Description of the inheritance
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
inheritance
\end_layout

\end_inset

 model
\end_layout

\begin_layout Standard
Within the TDSOM, each command
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
command
\end_layout

\end_inset

 supported by a device and implemented using the inheritance model is implemente
d by a separate class.
 The Command
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Command
\end_layout

\end_inset

 class is the root class for each of these classes.
 It is an abstract class.
 It stores the command name, the command argument types and description
 and mainly defines two methods which are the 
\emph on
execute
\emph default
 and 
\emph on
is_allowed
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
is-allowed
\end_layout

\end_inset


\emph default
 methods.
 The 
\emph on
execute
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
execute
\end_layout

\end_inset


\emph default
 method should be implemented in each sub-class.
 A default 
\emph on
is_allowed
\emph default
 method exists for command always allowed.
 A command also stores a parameter which is the command display type.
 It is also used to select if the command must be displayed according to
 the application mode (every day operation or expert mode).
\end_layout

\begin_layout Paragraph
Description of the template model
\end_layout

\begin_layout Standard
Using this method, it is not necessary to create a separate class for each
 device command.
 In this method, each command is represented by an instance of one of the
 template
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
template
\end_layout

\end_inset

 command classes.
 They are four template command classes.
 All these classes inherits from the Command class.
 These four classes are :
\end_layout

\begin_layout Enumerate
The 
\series bold
TemplCommand
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
TemplCommand
\end_layout

\end_inset


\series default
 class.
 One object of this class must be created for each command without input
 nor output parameters
\end_layout

\begin_layout Enumerate
The 
\series bold
TemplCommandIn
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
TemplCommandIn
\end_layout

\end_inset


\series default
 class.
 One object of this class must be created for each command without output
 parameter but with input parameter
\end_layout

\begin_layout Enumerate
The 
\series bold
TemplCommandOut
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
TemplCommandOut
\end_layout

\end_inset


\series default
 class.
 One object of this class must be created for each command without input
 parameter but with output parameter
\end_layout

\begin_layout Enumerate
The 
\series bold
TemplCommandInOut
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
TemplCommandInOut
\end_layout

\end_inset


\series default
 class.
 One object of this class must be created for each command with input and
 output parameters
\end_layout

\begin_layout Standard
These four classes redefine the 
\emph on
execute
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
execute
\end_layout

\end_inset


\emph default
 and 
\emph on
is_allowed
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
is-allowed
\end_layout

\end_inset


\emph default
 method of the Command class.
 These classes provides constructors which allow the user to :
\end_layout

\begin_layout Itemize
specify which method must be executed by these classes 
\emph on
execute
\emph default
 method
\end_layout

\begin_layout Itemize
optionally specify which method must be executed by these classes 
\emph on
is_allowed
\emph default
 method.
\end_layout

\begin_layout Standard
The method specification is done via pointer to method.
\end_layout

\begin_layout Standard
Remember that it is possible to mix command implementation method within
 the same device pattern.
\end_layout

\begin_layout Paragraph
Contents
\end_layout

\begin_layout Standard
The content of this class can be summarizes as :
\end_layout

\begin_layout Itemize
Class constructors and destructor
\end_layout

\begin_layout Itemize
Declaration of the 
\emph on
execute
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
execute
\end_layout

\end_inset


\emph default
 method
\end_layout

\begin_layout Itemize
Declaration of the 
\emph on
is_allowed
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
is-allowed
\end_layout

\end_inset


\emph default
 method
\end_layout

\begin_layout Itemize
Methods to read/set class data members
\end_layout

\begin_layout Itemize
Methods to extract
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
extract
\end_layout

\end_inset

 data from the object used to transfer data on the network
\end_layout

\begin_layout Itemize
Methods to insert
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
insert
\end_layout

\end_inset

 data into the object used to transfer data on the network
\end_layout

\begin_layout Itemize
Class data members like command name, command input data type, command input
 data description...
\end_layout

\begin_layout Subsubsection
The DeviceClass
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DeviceClass
\end_layout

\end_inset

 class
\end_layout

\begin_layout Paragraph
Description
\end_layout

\begin_layout Standard
This class implements all what is specific for a controlled object class.
 For instance, every device of the same class supports the same list of
 commands
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
command
\end_layout

\end_inset

 and therefore, this list of available commands is stored in this DeviceClass.
 The structure returned by the info operation contains a documentation URL
\begin_inset Foot
status open

\begin_layout Plain Layout
URL stands for 
\series bold
U
\series default
niform 
\series bold
R
\series default
esource 
\series bold
L
\series default
ocator
\end_layout

\end_inset

.
 This documentation
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
documentation
\end_layout

\end_inset

 URL
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
URL
\end_layout

\end_inset

 is the same for every device of the same class.
 Therefore, the documentation URL is a data member of this class.
 There should have only one instance of this class per device pattern implementa
tion.
 The device list is also stored in this class.
 It is an abstract class because the two methods 
\emph on
device_factory
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
device-factory
\end_layout

\end_inset

()
\emph default
 and 
\emph on
command_factory
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
command-factory
\end_layout

\end_inset

()
\emph default
 are declared as pure virtual.
 The rule of the 
\emph on
device_factory()
\emph default
 method is to create all the devices belonging to the device class.
 The rule of the 
\emph on
command_factory()
\emph default
 method is to create one instance of all the classes needed to support device
 commands.
 This class also stored the 
\emph on
attribute_factory
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
attribute-factory
\end_layout

\end_inset


\emph default
 method.
 The rule of this method is to store in a vector of strings, the name of
 all the device attributes.
 This method has a default implementation which is an empty body for device
 without attribute
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
attribute
\end_layout

\end_inset

.
\end_layout

\begin_layout Paragraph
Contents
\end_layout

\begin_layout Standard
The contents of this class can be summarize as :
\end_layout

\begin_layout Itemize
The 
\emph on
command_handler
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
command-handler
\end_layout

\end_inset


\emph default
 method
\end_layout

\begin_layout Itemize
Methods to access data members.
\end_layout

\begin_layout Itemize
Signal
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
signal
\end_layout

\end_inset

 related method (C++ specific)
\end_layout

\begin_layout Itemize
Class constructor.
 It is protected to implements the Singleton pattern
\end_layout

\begin_layout Itemize
Class data members like the class command list, the device list...
\end_layout

\begin_layout Subsubsection
The DbClass
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DbClass
\end_layout

\end_inset

 class
\end_layout

\begin_layout Standard
Each DeviceClass instance is an aggregate with one instance of the DbClass
 class.
 This DbClass class can be used to query or modify class properties
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
properties
\end_layout

\end_inset

.
 It provides an easy to use interface for device objects in the database.
 The description of this class can be found in the reference Tango C++ API
 documentation available in the Tango WEB pages.
\end_layout

\begin_layout Subsubsection
The MultiAttribute
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
MultiAttribute
\end_layout

\end_inset

 class
\end_layout

\begin_layout Paragraph
Description
\end_layout

\begin_layout Standard
This class is a container for all the TANGO attributes defined for the device.
 There is one instance of this class for each device.
 This class is mainly an aggregate of Attribute object(s).
 It has been developed to ease TANGO attribute management.
\end_layout

\begin_layout Paragraph
Contents
\end_layout

\begin_layout Standard
The class contents could be summarizes as :
\end_layout

\begin_layout Itemize
Miscellaneous methods to retrieve one attribute
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
attribute
\end_layout

\end_inset

 object in the aggregate
\end_layout

\begin_layout Itemize
Method to retrieve a list of attribute with an alarm level defined
\end_layout

\begin_layout Itemize
Get attribute number method
\end_layout

\begin_layout Itemize
Miscellaneous methods to check if an attribute value is outside the authorized
 limits
\end_layout

\begin_layout Itemize
Method to add messages for all attribute with an alarm set
\end_layout

\begin_layout Itemize
Data members with the attribute list
\end_layout

\begin_layout Subsubsection
The Attribute
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Attribute
\end_layout

\end_inset

 class
\end_layout

\begin_layout Paragraph
Description
\end_layout

\begin_layout Standard
There is one object of this class for each device attribute
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
attribute
\end_layout

\end_inset

.
 This class is used to store all the attribute properties
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
properties
\end_layout

\end_inset

, the attribute value and all the alarm
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
alarm
\end_layout

\end_inset

 related data.
 Like commands, this class also stores th attribute display type.
 It is foreseen to be used by future Tango graphical application toolkit
 to select if the attribute must be displayed according to the application
 mode (every day operation or expert mode).
\end_layout

\begin_layout Paragraph
Contents
\end_layout

\begin_layout Itemize
Miscellaneous method to get boolean attribute information
\end_layout

\begin_layout Itemize
Methods to access some data members
\end_layout

\begin_layout Itemize
Methods to get/set attribute properties
\end_layout

\begin_layout Itemize
Method to check if the attribute is in alarm condition
\end_layout

\begin_layout Itemize
Methods related to attribute data
\end_layout

\begin_layout Itemize
Friend function to print attribute properties
\end_layout

\begin_layout Itemize
Data members (properties value and attribute data)
\end_layout

\begin_layout Subsubsection
The WAttribute
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
WAttribute
\end_layout

\end_inset

 class
\end_layout

\begin_layout Paragraph
Description
\end_layout

\begin_layout Standard
This class inherits from the Attribute class.
 There is one instance of this class for each writable
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
writable
\end_layout

\end_inset

 device attribute.
 On top of all the data already managed by the Attribute class, this class
 stores the attribute set value.
\end_layout

\begin_layout Paragraph
Contents
\end_layout

\begin_layout Standard
Within this class, you will mainly find methods related to attribute
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
attribute
\end_layout

\end_inset

 set value storage and some data members.
\end_layout

\begin_layout Subsubsection
The Attr class
\end_layout

\begin_layout Standard
Within the TDSOM, each attribute
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
command
\end_layout

\end_inset

 supported by a device is implemented by a separate class.
 The Attr
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Attr
\end_layout

\end_inset

 class is the root class for each of these classes.
 It is used in conjonction with the Attribute and Wattribute classes to
 implement Tango attribute behaviour.
 It defines three methods which are the 
\emph on
is_allowed
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
is-allowed
\end_layout

\end_inset

, read
\emph default
 and 
\emph on
write
\emph default
 methods.
 A default 
\emph on
is_allowed
\emph default
 method exists for attribute always allowed.
 Default 
\emph on
read
\emph default
 and 
\emph on
write
\emph default
 empty methods are defined.
 For readable attribute, it is necessary to overwrite the 
\emph on
read
\emph default
 method.
 For writable attribute, it is necessary to overwrite the 
\emph on
write
\emph default
 method and for read and write attribute, both methods must be overwritten.
\end_layout

\begin_layout Subsubsection
The SpectrumAttr
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
SpectrumAttr
\end_layout

\end_inset

 class
\end_layout

\begin_layout Standard
This class inherits from the Attr class.
 It is the base class for user spectrum attribute.
 It is used in conjonction with the Attribute and WAttribute class to implement
 Tango spectrum attribute behaviour.
 From the Attr class, it inherits the Attr 
\emph on
is_allowed
\emph default
, 
\emph on
read
\emph default
 and 
\emph on
write
\emph default
 methods.
\end_layout

\begin_layout Subsubsection
The ImageAttr
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
ImageAttr
\end_layout

\end_inset

 class
\end_layout

\begin_layout Standard
This class inherits from the SpectrumAttr class.
 It is the base class for user image attribute.
 It is used in conjonction with the Attribute and WAttribute class to implement
 Tango image attribute behaviour.
 From the Attr class, it inherits the Attr 
\emph on
is_allowed
\emph default
, 
\emph on
read
\emph default
 and 
\emph on
write
\emph default
 methods.
\end_layout

\begin_layout Subsubsection
The StepperMotor class
\end_layout

\begin_layout Paragraph
Description
\end_layout

\begin_layout Standard
This class inherits from the DeviceImpl
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DeviceImpl
\end_layout

\end_inset

 class and is the class implementing the controlled object behavior.
 Each command will trigger a method in this class written by the device
 server programmer and specific to the object to be controlled.
 This class also stores all the device specific data.
\end_layout

\begin_layout Paragraph
Definition
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
1 class StepperMotor: public TANGO_BASE_CLASS
\end_layout

\begin_layout Verbatim
2 {
\end_layout

\begin_layout Verbatim
3 public :
\end_layout

\begin_layout Verbatim
4    StepperMotor(Tango::DeviceClass *,string &);
\end_layout

\begin_layout Verbatim
5    StepperMotor(Tango::DeviceClass *,const char *);
\end_layout

\begin_layout Verbatim
6    StepperMotor(Tango::DeviceClass *,const char *,const char *);
\end_layout

\begin_layout Verbatim
7    ~StepperMotor() {};
\end_layout

\begin_layout Verbatim
8 
\end_layout

\begin_layout Verbatim
9    DevLong dev_read_position(DevLong);
\end_layout

\begin_layout Verbatim
10   DevLong dev_read_direction(DevLong);
\end_layout

\begin_layout Verbatim
11   bool direct_cmd_allowed(const CORBA::Any &);
\end_layout

\begin_layout Verbatim
12 
\end_layout

\begin_layout Verbatim
13   virtual Tango::DevState dev_state();
\end_layout

\begin_layout Verbatim
14   virtual Tango::ConstDevString dev_status();
\end_layout

\begin_layout Verbatim
15 
\end_layout

\begin_layout Verbatim
16   virtual void always_executed_hook();
\end_layout

\begin_layout Verbatim
17 
\end_layout

\begin_layout Verbatim
18   virtual void read_attr_hardware(vector<long> &attr_list);
\end_layout

\begin_layout Verbatim
19   virtual void write_attr_hardware(vector<long> &attr_list);
\end_layout

\begin_layout Verbatim
20 
\end_layout

\begin_layout Verbatim
21   void read_position(Tango::Attribute &);
\end_layout

\begin_layout Verbatim
22   bool is_Position_allowed(Tango::AttReqType req);
\end_layout

\begin_layout Verbatim
23   void write_SetPosition(Tango::WAttribute &);
\end_layout

\begin_layout Verbatim
24   void read_Direction(Tango::Attribute &);
\end_layout

\begin_layout Verbatim
25 
\end_layout

\begin_layout Verbatim
26   virtual void init_device();
\end_layout

\begin_layout Verbatim
27   virtual void delete_device();
\end_layout

\begin_layout Verbatim
28 
\end_layout

\begin_layout Verbatim
29   void get_device_properties();
\end_layout

\begin_layout Verbatim
30 
\end_layout

\begin_layout Verbatim
31 protected : 
\end_layout

\begin_layout Verbatim
32   long axis[AGSM_MAX_MOTORS];
\end_layout

\begin_layout Verbatim
33   DevLong position[AGSM_MAX_MOTORS];
\end_layout

\begin_layout Verbatim
34   DevLong direction[AGSM_MAX_MOTORS];
\end_layout

\begin_layout Verbatim
35   long state[AGSM_MAX_MOTORS];
\end_layout

\begin_layout Verbatim
36 
\end_layout

\begin_layout Verbatim
37   Tango::DevLong *attr_Position_read;
\end_layout

\begin_layout Verbatim
38   Tango::DevLong *attr_Direction_read;
\end_layout

\begin_layout Verbatim
38   Tango::DevLong attr_SetPosition_write;
\end_layout

\begin_layout Verbatim
40 
\end_layout

\begin_layout Verbatim
41   Tango::DevLong min;
\end_layout

\begin_layout Verbatim
42   Tango::DevLong max;
\end_layout

\begin_layout Verbatim
43 
\end_layout

\begin_layout Verbatim
44   Tango::DevLong *ptr;
\end_layout

\begin_layout Verbatim
45 };
\end_layout

\begin_layout Verbatim
46 
\end_layout

\begin_layout Verbatim
47 } /* End of StepperMotor namespace */
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
Line 1 : The StepperMotor class inherits from the DeviceImpl class
\end_layout

\begin_layout Standard
Line 4-7 : Class constructors and destructor
\end_layout

\begin_layout Standard
Line 9 : Method triggered by the DevReadPosition command
\end_layout

\begin_layout Standard
Line 10-11 : Methods triggered by the DevReadDirection command
\end_layout

\begin_layout Standard
Line 13 : Redefinition of the 
\emph on
dev_state
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
dev-state
\end_layout

\end_inset


\emph default
 method of the DeviceImpl class.
 This method will be triggered by the State
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
State
\end_layout

\end_inset

 command
\end_layout

\begin_layout Standard
Line 14 : Redefinition of the 
\emph on
dev_statu
\emph default

\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
dev-status
\end_layout

\end_inset

s method of the DeviceImpl class.
 This method will be triggered by the Status
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Status
\end_layout

\end_inset

 command
\end_layout

\begin_layout Standard
Line 16 : Redefinition of the 
\emph on
always_executed_hook
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
always-executed-hook
\end_layout

\end_inset


\emph default
 method.
\end_layout

\begin_layout Standard
Line 26 : Definition of the 
\emph on
init_device
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
init-device
\end_layout

\end_inset


\emph default
 method (declared as pure virtual by the DeviceImpl class)
\end_layout

\begin_layout Standard
Line 27 : Definition of the 
\emph on
delete_device
\emph default

\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
delet-device
\end_layout

\end_inset

 method
\end_layout

\begin_layout Standard
Line 31-45 : Device data
\end_layout

\begin_layout Subsubsection
The StepperMotorClass class
\end_layout

\begin_layout Paragraph
Description
\end_layout

\begin_layout Standard
This class inherits from the DeviceClass
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DeviceClass
\end_layout

\end_inset

 class.
 Like the DeviceClass class, there should be only one instance of the StepperMot
orClass.
 This is ensured because this class is written following the Singleton
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
singleton
\end_layout

\end_inset

 pattern as defined in 
\begin_inset CommandInset citation
LatexCommand cite
key "Patterns"

\end_inset

.
 All controlled object class data which should be defined only once per
 class must be stored in this object.
\end_layout

\begin_layout Paragraph
Definition 
\end_layout

\begin_layout Standard
\begin_inset ERT
status collapsed

\begin_layout Plain Layout


\backslash
input{line.tex}
\end_layout

\end_inset


\end_layout

\begin_layout Standard
     1  class StepperMotorClass : public DeviceClass
\end_layout

\begin_layout Standard
     2  {
\end_layout

\begin_layout Standard
3  public:
\end_layout

\begin_layout Standard
     4          static StepperMotorClass *init(const char *);
\end_layout

\begin_layout Standard
     5          static StepperMotorClass *instance();
\end_layout

\begin_layout Standard
     6          ~StepperMotorClass() {_instance = NULL;}
\end_layout

\begin_layout Standard
     7          
\end_layout

\begin_layout Standard
     8  protected:
\end_layout

\begin_layout Standard
     9          StepperMotorClass(string &);
\end_layout

\begin_layout Standard
    10          static StepperMotorClass *_instance;
\end_layout

\begin_layout Standard
    11          void command_factory();
\end_layout

\begin_layout Standard
    12          
\end_layout

\begin_layout Standard
    13  private:
\end_layout

\begin_layout Standard
    14          void device_factory(Tango_DevVarStringArray *);
\end_layout

\begin_layout Standard
    15  };
\end_layout

\begin_layout Standard
\begin_inset ERT
status collapsed

\begin_layout Plain Layout


\backslash
input{line.tex}
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Line 1 : This class is a sub-class of the DeviceClass class
\end_layout

\begin_layout Standard
Line 4-5 and 9-10: Methods and data member necessary for the Singleton
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
singleton
\end_layout

\end_inset

 pattern
\end_layout

\begin_layout Standard
Line 6 : Class destructor
\end_layout

\begin_layout Standard
Line 11 : Definition of the 
\emph on
command_factor
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
command-factory
\end_layout

\end_inset

y
\emph default
 method declared as pure virtual in the DeviceClass call
\end_layout

\begin_layout Standard
Line 13-14 : Definition of the 
\emph on
device_factory
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
device-factory
\end_layout

\end_inset


\emph default
 method declared as pure virtual in the DeviceClass class
\end_layout

\begin_layout Subsubsection
The DevReadPosition class
\end_layout

\begin_layout Paragraph
Description
\end_layout

\begin_layout Standard
This is the class for the DevReadPosition command.
 This class implements the 
\emph on
execute
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
execute
\end_layout

\end_inset


\emph default
 and 
\emph on
is_allowed
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
is-allowed
\end_layout

\end_inset


\emph default
 methods defined by the Command
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Command
\end_layout

\end_inset

 class.
 This class is necessary because this command is implemented using the inheritan
ce
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
inheritance
\end_layout

\end_inset

 model.
\end_layout

\begin_layout Paragraph
Definition
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
1  class DevReadPositionCmd : public Command
\end_layout

\begin_layout Verbatim
2  {
\end_layout

\begin_layout Verbatim
3  public:
\end_layout

\begin_layout Verbatim
4      DevReadPositionCmd(const char *,Tango_CmdArgType, Tango_CmdArgType,
 const char *, const char*);
\end_layout

\begin_layout Verbatim
5      ~DevReadPositionCmd() {};
\end_layout

\begin_layout Verbatim
6          
\end_layout

\begin_layout Verbatim
7      virtual bool is_allowed (DeviceImpl *, const CORBA::Any &);
\end_layout

\begin_layout Verbatim
8      virtual CORBA::Any *execute (DeviceImpl *, const CORBA::Any &);
\end_layout

\begin_layout Verbatim
9  };
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
Line 1 : The class is a sub class of the Command class
\end_layout

\begin_layout Standard
Line 4-5 : Class constructor and destructor
\end_layout

\begin_layout Standard
Line 7-8 : Definition of the 
\emph on
is_allowed
\emph default
 and 
\emph on
execute
\emph default
 method declared as pure virtual in the Command class.
\end_layout

\begin_layout Subsubsection
The PositionAttr class
\end_layout

\begin_layout Paragraph
Description
\end_layout

\begin_layout Standard
This is the class for the Position attribute.
 This attribute is a scalar attribute and therefore inherits from the Attr
 base class.
 This class implements the 
\emph on
read
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
execute
\end_layout

\end_inset


\emph default
 and 
\emph on
is_allowed
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
is-allowed
\end_layout

\end_inset


\emph default
 methods defined by the Attr
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Command
\end_layout

\end_inset

 class.
\end_layout

\begin_layout Paragraph
Definition
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
     1  class PositionAttr: public Tango::Attr
\end_layout

\begin_layout Verbatim
     2  {
\end_layout

\begin_layout Verbatim
     3  public:
\end_layout

\begin_layout Verbatim
     4     PositionAttr():Attr("Position",Tango::DEV_LONG,Tango::READ);
\end_layout

\begin_layout Verbatim
     5     ~PositionAttr() {};
\end_layout

\begin_layout Verbatim
     6          
\end_layout

\begin_layout Verbatim
     7     virtual void read(Tango::DeviceImpl *dev,Tango::Attribute &att)
\end_layout

\begin_layout Verbatim
     8     {(static_cast<StepperMotor *>(dev))->read_Position(att);}
\end_layout

\begin_layout Verbatim
     9     virtual bool is_allowed(Tango::DeviceImpl *dev,Tango::AttReqType
 ty)
\end_layout

\begin_layout Verbatim
    10     {return (static_cast<StepperMotor *>(dev))->is_Position_allowed(ty);}
\end_layout

\begin_layout Verbatim
    11  };
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
Line 1 : The class is a sub class of the Attr class
\end_layout

\begin_layout Standard
Line 4-5 : Class constructor and destructor
\end_layout

\begin_layout Standard
Line 7 : Re-definition of the 
\emph on
read
\emph default
 method defined in the Attr class.
 This is simply a "forward" to the 
\emph on
read_Position
\emph default
 method of the StepperMotor class
\end_layout

\begin_layout Standard
Line 9 : Re-definition of the 
\emph on
is_allowed
\emph default
 method defined in the Attr class.
 This is also a "forward" to the 
\emph on
is_Position_allowed
\emph default
 method of the StepperMotor class
\end_layout

\begin_layout Subsection
Startup of a device pattern
\begin_inset CommandInset label
LatexCommand label
name "Pattern startup"

\end_inset


\end_layout

\begin_layout Standard
To start the device pattern implementation for stepper motor device, four
 methods of the StepperMotorClass class must be executed.
 These methods are :
\end_layout

\begin_layout Enumerate
The creation of the StepperMethodClass singleton
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
singleton
\end_layout

\end_inset

 via its 
\emph on
init
\emph default
() method
\end_layout

\begin_layout Enumerate
The 
\emph on
command_factory
\emph default
()
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
command-factory
\end_layout

\end_inset

 method of the StepperMotorClass class
\end_layout

\begin_layout Enumerate
The 
\emph on
attribute_factory
\emph default

\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
attribute-factory
\end_layout

\end_inset

() method of the StepperMotorClass class.
 This method has a default empty body for device class without attributes.
\end_layout

\begin_layout Enumerate
The 
\emph on
device_factory
\emph default

\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
device-factory
\end_layout

\end_inset

() method of the StepperMotorClass class
\end_layout

\begin_layout Standard
This startup procedure is described in figure 
\begin_inset CommandInset ref
LatexCommand ref
reference "pattern_startup_fig"

\end_inset


\begin_inset Float figure
wide false
sideways false
status open

\begin_layout Plain Layout
\align center
\begin_inset Graphics
	filename startup.eps
	width 14cm
	height 10cm

\end_inset


\end_layout

\begin_layout Plain Layout
\begin_inset Caption Standard

\begin_layout Plain Layout
Device pattern startup sequence
\begin_inset CommandInset label
LatexCommand label
name "pattern_startup_fig"

\end_inset


\end_layout

\end_inset


\end_layout

\end_inset

 .
 The creation of the StepperMotorClass will automatically create an instance
 of the DeviceClass class.
 The constructor of the DeviceClass
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DeviceClass
\end_layout

\end_inset

 class will create the Status
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Status
\end_layout

\end_inset

, State
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
State
\end_layout

\end_inset

 and Init
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Init
\end_layout

\end_inset

 command objects and store them in its command list.
\end_layout

\begin_layout Standard
The 
\emph on
command_factory
\emph default
() method will simply create all the user defined commands and add them
 in the command list.
\end_layout

\begin_layout Standard
The 
\emph on
attribute_factory
\emph default
() method will simply build a list of device attribute names.
\end_layout

\begin_layout Standard
The 
\emph on
device_factory
\emph default
() method will create each StepperMotor object and store them in the StepperMoto
rClass instance device list.
 The list of devices to be created and their names is passed to the 
\emph on
device_factory
\emph default
 method in its input argument.
 StepperMotor is a sub-class of DeviceImpl class.
 Therefore, when a StepperMotor object is created, a DeviceImpl object is
 also created.
 The DeviceImpl constructor builds all the device attribute object(s) from
 the attribute list built by the 
\emph on
attribute_factory()
\emph default
 method.
\end_layout

\begin_layout Subsection
Command execution sequence
\end_layout

\begin_layout Standard
The figure 
\begin_inset CommandInset ref
LatexCommand ref
reference "command_timing_fig"

\end_inset


\begin_inset Float figure
placement H
wide false
sideways false
status open

\begin_layout Plain Layout
\align center
\begin_inset Graphics
	filename command.eps
	width 14cm
	height 8cm

\end_inset


\end_layout

\begin_layout Plain Layout
\begin_inset Caption Standard

\begin_layout Plain Layout
Command execution timing
\begin_inset CommandInset label
LatexCommand label
name "command_timing_fig"

\end_inset


\end_layout

\end_inset


\end_layout

\end_inset

 described how the method implementing a command is executed when a command_inou
t
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
command-inout
\end_layout

\end_inset

 CORBA operation is requested by a client.
 The 
\emph on
command_inout
\emph default
 method of the StepperMotor object (inherited from the DeviceImpl class)
 is triggered by an instance of a class generated by the CORBA
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
CORBA
\end_layout

\end_inset

 IDL compiler.
 This method calls the 
\emph on
command_handler
\emph default
()
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
command-handler
\end_layout

\end_inset

 method of the StepperMotorClass object (inherited from the DeviceClass
 class).
 The 
\emph on
command_handler
\emph default
 method searches in its command
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
command
\end_layout

\end_inset

 list for the wanted command (using its name).
 If the command is found, the 
\emph on
always_executed_hook
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
always-executed-hook
\end_layout

\end_inset


\emph default
 method of the StepperMotor object is called.
 Then, the 
\emph on
is_allowed
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
is-allowed
\end_layout

\end_inset


\emph default
 method of the wanted command is executed.
 If the 
\emph on
is_allowed
\emph default
 method returns correctly, the 
\emph on
execute
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
execute
\end_layout

\end_inset


\emph default
 method is executed.
 The 
\emph on
execute
\emph default
 method extracts the incoming data from the CORBA object use to transmit
 data over the network and calls the user written method which implements
 the command.
\end_layout

\begin_layout Subsection
The automatically added commands
\begin_inset CommandInset label
LatexCommand label
name "Auto_cmd"

\end_inset


\end_layout

\begin_layout Standard
In order to increase the common behavior of every kind of devices in a TANGO
 control system, three commands are automatically added to each class of
 devices.
 These commands are :
\end_layout

\begin_layout Itemize
State
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
State
\end_layout

\end_inset


\end_layout

\begin_layout Itemize
Status
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Status
\end_layout

\end_inset


\end_layout

\begin_layout Itemize
Init
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Init
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The default behavior of the method called by the State command depends on
 the device state.
 If the device state is ON or ALARM
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
ALARM
\end_layout

\end_inset

, the method will :
\end_layout

\begin_layout Itemize
read the attribute(s) with an alarm
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
alarm
\end_layout

\end_inset

 level defined
\end_layout

\begin_layout Itemize
check if the read value is above/below the alarm level and eventually change
 the device state to ALARM.
\end_layout

\begin_layout Itemize
returns the device state.
\end_layout

\begin_layout Standard
For all the other device state
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
state
\end_layout

\end_inset

, the method simply returns the device state stored in the DeviceImpl class.
 Nevertheless, the method used to return this state (called 
\emph on
dev_state
\emph default

\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
state
\end_layout

\end_inset

) is defined as virtual and can be redefined in DeviceImpl sub-class.
 The difference between the default State command and the state CORBA attribute
 is the ability of the State
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
State
\end_layout

\end_inset

 command to signal an error to the caller by throwing an exception.
\end_layout

\begin_layout Standard
The default behavior of the method called by the Status
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Status
\end_layout

\end_inset

 command depends on the device state.
 If the device state is ON or ALARM
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
ALARM
\end_layout

\end_inset

, the method returns the device status stored in the DeviceImpl class plus
 additional message(s) for all the attributes which are in alarm condition.
 For all the other device state, the method simply returns the device status
 as it is stored in the DeviceImpl class.
 Nevertheless, the method used to return this status (called 
\emph on
dev_status
\emph default

\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
status
\end_layout

\end_inset

) is defined as virtual and can be redefined in DeviceImpl sub-class.
 The difference between the default Status command and the status CORBA
 attribute is the ability of the Status command to signal an error to the
 caller by throwing an exception.
\end_layout

\begin_layout Standard
The Init
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Init
\end_layout

\end_inset

 command is used to re-initialize a device without changing its network
 connection.
 This command calls the device 
\emph on
delete_device
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
delete-device
\end_layout

\end_inset


\emph default
 method and the device 
\emph on
init_device
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
init-device
\end_layout

\end_inset


\emph default
 method.
 The rule of the 
\emph on
delete_device
\emph default
 method is to free memory allocated in the 
\emph on
init_device
\emph default
 method in order to avoid memory leak.
\end_layout

\begin_layout Subsection
Reading/Writing attributes
\end_layout

\begin_layout Subsubsection
Reading attributes
\end_layout

\begin_layout Standard
A Tango client is able to read Tango attribute
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
attribute
\end_layout

\end_inset

(s) with the CORBA read_attributes
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
read-attributes
\end_layout

\end_inset

 call.
 Inside the device server, this call will trigger several methods of the
 device class (StepperMotor in our example) :
\end_layout

\begin_layout Enumerate
The 
\emph on
always_executed_hook()
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
allways-executed-hook
\end_layout

\end_inset


\emph default
 method.
 
\end_layout

\begin_layout Enumerate
A method call 
\emph on
read_attr_hardware()
\emph default

\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
read-attr-hardware
\end_layout

\end_inset

.
 This method is called one time per read_attributes CORBA call.
 The aim of this method is to read the device hardware and to store the
 result in a device class data member.
\end_layout

\begin_layout Enumerate
For each attribute to be read
\end_layout

\begin_deeper
\begin_layout Enumerate
A method called 
\emph on
is_<att name>_allowed()
\emph default
.
 The rule of this method is to allow (or disallow) the next method to be
 executed.
 It is usefull for device with some attributes which can be read only in
 some precise conditions.
 It has one parameter which is the request type (read or write)
\end_layout

\begin_layout Enumerate
A method called 
\emph on
read_<att name>()
\emph default
.
 The aim of this method is to extract the real attribute value from the
 hardware read-out and to store the attribute value into the attribute object.
 It has one parameter which is a reference to the Attribute object to be
 read.
\end_layout

\end_deeper
\begin_layout Standard
The figure 
\begin_inset CommandInset ref
LatexCommand ref
reference "r_attribute_timing_fig"

\end_inset

 is a drawing of these method calls sequencing.
 For attribute always readable, a default 
\emph on
is_allowed
\emph default
 method is provided.
 This method always returns true.
\begin_inset Float figure
placement H
wide false
sideways false
status open

\begin_layout Plain Layout
\align center
\begin_inset Graphics
	filename r_attribute.eps
	scale 70

\end_inset


\end_layout

\begin_layout Plain Layout
\begin_inset Caption Standard

\begin_layout Plain Layout
Read attribute sequencing
\begin_inset CommandInset label
LatexCommand label
name "r_attribute_timing_fig"

\end_inset


\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Subsubsection
Writing attributes
\end_layout

\begin_layout Standard
A Tango client is able to write Tango attribute(s) with the CORBA write_attribut
es
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
write-attributes
\end_layout

\end_inset

 call.
 Inside a device server, this call will trigger several methods of the device
 class (StepperMotor in our example)
\end_layout

\begin_layout Enumerate
The 
\emph on
always_executed_hook()
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
allways-executed-hook
\end_layout

\end_inset


\emph default
 method.
 
\end_layout

\begin_layout Enumerate
For each attribute to be written
\end_layout

\begin_deeper
\begin_layout Enumerate
A method called 
\emph on
is_<att name>_allowed()
\emph default
.
 The rule of this method is to allow (or disallow) the next method to be
 executed.
 It is usefull for device with some attributes which can be written only
 in some precise conditions.
 It has one parameter which is the request type (read or write)
\end_layout

\begin_layout Enumerate
A method called 
\emph on
write_<att name>()
\emph default
.
 It has one parameter which is a reference to the WAttribute object to be
 written.
 The aim of this method is to get the data to be written from the WAttribute
 object and to write this value into the corresponding hardware.
 If the hardware support writing several data in one go, code the hardware
 access in the 
\emph on
write_attr_harware()
\emph default
 method.
\end_layout

\end_deeper
\begin_layout Enumerate
The write_attr_hardware()
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
write-attr-hardware
\end_layout

\end_inset

 method.
 The rule of this method is to effectively write the hardware in case it
 is able to support writing several data in one go.
 If this is not the case, don't code this method (a default implementation
 is coded in the Tango base class) and code the real hardware access in
 each 
\emph on
write_<att name>()
\emph default
 method.
\end_layout

\begin_layout Standard
The figure 
\begin_inset CommandInset ref
LatexCommand ref
reference "w_attribute_timing_fig"

\end_inset

 is a drawing of these method calls sequencing.
 For attribute always writeable, a default is_allowed method is provided.
 This method always allways returns true.
\begin_inset Float figure
placement H
wide false
sideways false
status open

\begin_layout Plain Layout
\align center
\begin_inset Graphics
	filename w_attribute.eps
	scale 70

\end_inset


\end_layout

\begin_layout Plain Layout
\begin_inset Caption Standard

\begin_layout Plain Layout
Write attribute sequencing
\begin_inset CommandInset label
LatexCommand label
name "w_attribute_timing_fig"

\end_inset


\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Subsection
The device server framework
\end_layout

\begin_layout Subsubsection
Vocabulary
\begin_inset CommandInset label
LatexCommand label
name "Voc"

\end_inset


\end_layout

\begin_layout Standard
A device server
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
server
\end_layout

\end_inset

 pattern implementation is embedded in a process called a 
\series bold
device server
\series default
.
 Several instances of the same device server process can be used in a TANGO
 control system.
 To identify instances, a device server process is started with an 
\series bold
instance name
\series default
 which is different for each instance.
 The device server name is the couple device server executable
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
executable
\end_layout

\end_inset

 name/device server instance
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
instance
\end_layout

\end_inset

 name.
 For instance, a device server started with the following command 
\begin_inset ERT
status collapsed

\begin_layout Plain Layout


\backslash
begin{center}
\end_layout

\end_inset

Perkin id11
\begin_inset ERT
status collapsed

\begin_layout Plain Layout


\backslash
end{center}
\end_layout

\end_inset

 starts a device server process with an instance name id11, an executable
 name Perkin and a device server name Perkin/id11.
\end_layout

\begin_layout Subsubsection
The DServer class
\begin_inset CommandInset label
LatexCommand label
name "DServer_class"

\end_inset


\end_layout

\begin_layout Standard
In order to simplify device server process administration, a device of the
 DServer
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DServer
\end_layout

\end_inset

 class is automatically added to each device server process.
 Thus, every device server process supports the same set of administration
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
administration
\end_layout

\end_inset

 commands.
 The implementation of this DServer class follows the device pattern and
 therefore, its device behaves like any other devices.
 The device name is 
\begin_inset ERT
status collapsed

\begin_layout Plain Layout


\backslash
begin{center}
\end_layout

\end_inset

dserver/device server executable name/device server instance name
\begin_inset ERT
status collapsed

\begin_layout Plain Layout


\backslash
end{center}
\end_layout

\end_inset

For instance, for the device server process described in chapter 
\begin_inset CommandInset ref
LatexCommand ref
reference "Voc"

\end_inset

, the dserver device name is dserver/perkin/id11.
 This name is returned by the adm_name
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
adm-name
\end_layout

\end_inset

 CORBA attribute available for every device.
 On top of the three automatically added commands, this device supports
 the following commands :
\end_layout

\begin_layout Itemize
DevRestart
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DevRestart
\end_layout

\end_inset


\end_layout

\begin_layout Itemize
RestartServer
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
RestartServer
\end_layout

\end_inset


\end_layout

\begin_layout Itemize
QueryClass
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
QueryClass
\end_layout

\end_inset


\end_layout

\begin_layout Itemize
QueryDevice
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
QueryDevice
\end_layout

\end_inset


\end_layout

\begin_layout Itemize
Kill
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Kill
\end_layout

\end_inset


\end_layout

\begin_layout Itemize
AddLoggingTarget (C++ server only)
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
AddLoggingTarget
\end_layout

\end_inset


\end_layout

\begin_layout Itemize
RemoveLoggingTarget (C++ server only)
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
RemoveLoggingTarget
\end_layout

\end_inset


\end_layout

\begin_layout Itemize
GetLoggingTarget (C++ server only)
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
GetLoggingTarget
\end_layout

\end_inset


\end_layout

\begin_layout Itemize
GetLoggingLevel (C++ server only)
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
GetLoggingLevel
\end_layout

\end_inset


\end_layout

\begin_layout Itemize
SetLoggingLevel (C++ server only)
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
SetLoggingLevel
\end_layout

\end_inset


\end_layout

\begin_layout Itemize
StopLogging (C++ server only)
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
StopLogging
\end_layout

\end_inset


\end_layout

\begin_layout Itemize
StartLogging (C++ server only)
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
StartLogging
\end_layout

\end_inset


\end_layout

\begin_layout Itemize
PolledDevice
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
PolledDevice
\end_layout

\end_inset


\end_layout

\begin_layout Itemize
DevPollStatus
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DevPollStatus
\end_layout

\end_inset


\end_layout

\begin_layout Itemize
AddObjPolling
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
AddObjPolling
\end_layout

\end_inset


\end_layout

\begin_layout Itemize
RemObjPolling
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
RemObjPolling
\end_layout

\end_inset


\end_layout

\begin_layout Itemize
UpdObjPollingPeriod
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
UpdObjPollingPeriod
\end_layout

\end_inset


\end_layout

\begin_layout Itemize
StartPolling
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
StartPolling
\end_layout

\end_inset


\end_layout

\begin_layout Itemize
StopPolling
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
StopPolling
\end_layout

\end_inset


\end_layout

\begin_layout Itemize
EventSubscriptionChange
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
EventSubscriptionChange
\end_layout

\end_inset


\end_layout

\begin_layout Itemize
ZmqEventSubscriptionChange
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
ZmqEventSubscriptionChange
\end_layout

\end_inset


\end_layout

\begin_layout Itemize
LockDevice
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
LockDevice
\end_layout

\end_inset


\end_layout

\begin_layout Itemize
UnLockDevice
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
UnLockDevice
\end_layout

\end_inset


\end_layout

\begin_layout Itemize
ReLockDevices
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
ReLockDevices
\end_layout

\end_inset


\end_layout

\begin_layout Itemize
DevLockStatus
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DevLockStatus
\end_layout

\end_inset


\end_layout

\begin_layout Standard
These commands will be fully described later in this document.
\end_layout

\begin_layout Standard
Several controlled object classes can be embedded within the same device
 server process and it is the rule of this device to create all these device
 server patterns and to call their command and device factories as described
 in 
\begin_inset CommandInset ref
LatexCommand ref
reference "Pattern startup"

\end_inset

.
 The name and number of all the classes to be created is known to this device
 after the execution of a method called 
\emph on
class_factory
\emph default

\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
class-factory
\end_layout

\end_inset

.
 It is the user responsibility to write this method.
\end_layout

\begin_layout Subsubsection
The Tango::Util
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Util
\end_layout

\end_inset

 class
\end_layout

\begin_layout Paragraph
Description
\end_layout

\begin_layout Standard
This class merges a complete set of utilities in the same class.
 It is implemented as a singleton
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
singleton
\end_layout

\end_inset

 and there is only one instance of this class per device server process.
 It is mandatory to create this instance in order to run a device server.
 The description of all the methods implemented in this class can be found
 in 
\begin_inset CommandInset citation
LatexCommand cite
key "TANGO_ref_man"

\end_inset

.
\end_layout

\begin_layout Paragraph
Contents
\end_layout

\begin_layout Standard
Within this class, you can find :
\end_layout

\begin_layout Itemize
Static method to create/retrieve the singleton object
\end_layout

\begin_layout Itemize
Miscellaneous utility methods like getting the server output trace level,
 getting the CORBA
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
CORBA
\end_layout

\end_inset

 ORB pointer, retrieving device server instance name, getting the server
 PID and more.
 Please, refer to 
\begin_inset CommandInset citation
LatexCommand cite
key "TANGO_ref_man"

\end_inset

 to get a complete list of all these utility methods.
\end_layout

\begin_layout Itemize
Method to create the device pattern implementing the DServer class (
\emph on
server_init()
\emph default

\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
server-init
\end_layout

\end_inset

)
\end_layout

\begin_layout Itemize
Method to start the server (
\emph on
server_run()
\emph default

\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
server-run
\end_layout

\end_inset

)
\end_layout

\begin_layout Itemize
TANGO database related methods
\end_layout

\begin_layout Subsubsection
A complete device server
\end_layout

\begin_layout Standard
Within a complete device server, at least two implementations of the device
 server pattern are created (one for the dserver object and the other for
 the class of devices to control).
 On top of that, one instance of the Tango::Util
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Util
\end_layout

\end_inset

 class must also be created.
\begin_inset Float figure
wide false
sideways false
status open

\begin_layout Plain Layout
\align center
\begin_inset Graphics
	filename complete_server.eps
	width 14cm
	height 10cm

\end_inset


\end_layout

\begin_layout Plain Layout
\begin_inset Caption Standard

\begin_layout Plain Layout
A complete device server
\begin_inset CommandInset label
LatexCommand label
name "completeDS"

\end_inset


\end_layout

\end_inset


\end_layout

\end_inset

 A drawing of a complete device server is in figure 
\begin_inset CommandInset ref
LatexCommand ref
reference "completeDS"

\end_inset


\end_layout

\begin_layout Subsubsection
Device server startup sequence
\begin_inset CommandInset label
LatexCommand label
name "Server_startup"

\end_inset


\end_layout

\begin_layout Standard
The device server startup sequence is the following :
\end_layout

\begin_layout Enumerate
Create an instance of the Tango::Util class.
 This will initialize the CORBA Object Request Broker
\end_layout

\begin_layout Enumerate
Called the 
\emph on
server_init
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
init
\end_layout

\end_inset


\emph default
 method of the Tango::Util instance The call to this method will :
\end_layout

\begin_deeper
\begin_layout Enumerate
Create the DServerClass object of the device pattern implementing the DServer
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DServer
\end_layout

\end_inset

 class.
 This will create the dserver object which during its construction will
 :
\end_layout

\begin_deeper
\begin_layout Enumerate
Called the 
\emph on
class_factory
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
class-factory
\end_layout

\end_inset


\emph default
 method of the DServer object.
 This method must create all the xxxClass instance for all the device pattern
 implementation embedded in the device server process.
\end_layout

\begin_layout Enumerate
Call the 
\emph on
command_factory
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
command-factory
\end_layout

\end_inset


\emph default
 and 
\emph on
device_factory
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
device-factory
\end_layout

\end_inset


\emph default
 of all the classes previously created.
 The list of devices passed to each call to the 
\emph on
device_factory
\emph default
 method is retrieved from the TANGO database.
\end_layout

\end_deeper
\end_deeper
\begin_layout Enumerate
Wait for incoming request with the 
\emph on
server_run()
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
server-run
\end_layout

\end_inset


\emph default
 method of the Tango::Util class.
\end_layout

\begin_layout Section
Exchanging data between client and server
\begin_inset CommandInset label
LatexCommand label
name "Data exchange"

\end_inset


\end_layout

\begin_layout Standard
Exchanging data between clients and server means most of the time passing
 data between processes running on different computer using the network.
 Tango limits the type of data exchanged between client and server and defines
 a way to exchange these data.
 This chapter details these features.
 Memory allocation and error reporting are also discussed.
\end_layout

\begin_layout Standard

\series bold
All the rules described in this chapter are valid only for data exchanged
 between client and server.
 For device server internal data, classical C++ types can be used.
\end_layout

\begin_layout Subsection
Command / Attribute data types
\end_layout

\begin_layout Standard
Commands have a fixed calling syntax - consisting of one input argument
 and one output argument.
 Arguments type must be chosen out of a fixed set of 24 data types.
 Attributes support a sub-set of these data types (those are the data type
 with the (1) note) plus the DevEnum data type.
 The following table details type name, code and the corresponding CORBA
 IDL types.
\end_layout

\begin_layout Standard
The type name used in the type name column of this table is the C++ name.
 In the IDL file, all the Tango definition are grouped in a IDL
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
IDL
\end_layout

\end_inset

 module named Tango.
 The IDL module maps to C++ namespace
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
namespace
\end_layout

\end_inset

.
 Therefore, all the data type are parts of a namespace called Tango.
\end_layout

\begin_layout Standard
\begin_inset VSpace 0.3cm
\end_inset


\end_layout

\begin_layout Standard
\align center
\begin_inset Text

\begin_layout Standard
\begin_inset Tabular
<lyxtabular version="3" rows="26" columns="2">
<features rotate="0" islongtable="true" longtabularalignment="center">
<column alignment="center" valignment="top" width="0pt">
<column alignment="left" valignment="top" width="0pt">
<row>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Type name
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
IDL type
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Tango::DevBoolean (1)
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
boolean
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Tango::DevShort (1)
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
short
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Tango::DevEnum (2)
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
short (See chapter on advanced features)
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Tango::DevLong (1)
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
long
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Tango::DevLong64 (1)
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
long long
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Tango::DevFloat (1)
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
float
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Tango::DevDouble (1)
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
double
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Tango::DevUShort (1)
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
unsigned short
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Tango::DevULong (1)
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
unsigned long
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Tango::DevULong64 (1)
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
unsigned long long
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Tango::DevString (1)
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
string
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Tango::DevVarCharArray
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
sequence of unsigned char
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Tango::DevVarShortArray
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
sequence of short
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Tango::DevVarLongArray
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
sequence of long
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Tango::DevVarLong64Array
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
sequence of long long
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Tango::DevVarFloatArray
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
sequence of float
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Tango::DevVarDoubleArray
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
sequence of double
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Tango::DevVarUShortArray
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
sequence of unsigned short
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Tango::DevVarULongArray
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
sequence of unsigned long
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Tango::DevVarULong64Array
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
sequence of unsigned long long
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Tango::DevVarStringArray
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
sequence of string
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Tango::DevVarLongStringArray
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
structure with a sequence of long and a sequence of string
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Tango::DevVarDoubleStringArray
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
structure with a sequence of double and a sequence of string
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Tango::DevState (1)
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
enumeration
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Tango::DevEncoded (1)
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
structure with a string and a sequence of char
\end_layout

\end_inset
</cell>
</row>
</lyxtabular>

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset VSpace 0.3cm
\end_inset


\end_layout

\begin_layout Standard
The CORBA Interface Definition Language uses a type called 
\series bold
sequence
\series default
 for variable length array.
 The Tango::DevUxxx types are used for unsigned types.
 The Tango::DevVarxxxxArray must be used when the data to be transferred
 are variable length array.
 The Tango::DevVarLongStringArray
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Tango::DevVarLongStringArray
\end_layout

\end_inset

 and Tango::DevVarDoubleStringArray
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Tango::DevVarDoubleStringArray
\end_layout

\end_inset

 are structures with two fields which are variable length array of Tango
 long (32 bits) and variable length array of strings for the Tango::DevVarLongSt
ringArray and variable length array of double and variable length array
 of string for the Tango::DevVarDoubleStringArray.
 The Tango::State
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Tango::DevState
\end_layout

\end_inset

 type is used by the State
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
State
\end_layout

\end_inset

 command to return the device state.
 
\end_layout

\begin_layout Subsubsection
Using data types with C++
\end_layout

\begin_layout Standard
Unfortunately, the mapping between IDL and C++ was defined before the C++
 class library had been standardized.
 This explains why the standard C++ string class or vector classes are not
 used in the IDL to C++ mapping.
\end_layout

\begin_layout Standard
TANGO commands/attributes argument types can be grouped on five groups depending
 on the IDL data type used.
 These groups are :
\end_layout

\begin_layout Enumerate
Data type using basic types (Tango::DevBoolean, Tango::DevShort, Tango::DevEnum,
 Tango::DevLong, Tango::DevFloat, Tango::DevDouble, Tango::DevUshort and
 Tango::DevULong)
\end_layout

\begin_layout Enumerate
Data type using strings (Tango::DevString type)
\end_layout

\begin_layout Enumerate
Data types using sequences
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
sequence
\end_layout

\end_inset

 (Tango::DevVarxxxArray types except Tango::DevVarLongStringArray and Tango::Dev
VarDoubleStringArray)
\end_layout

\begin_layout Enumerate
Data types using structures (Tango::DevVarLongStringArray and Tango::DevVarDoubl
eStringArray types)
\end_layout

\begin_layout Enumerate
Data type using IDL enumeration (Tango::DevState type)
\end_layout

\begin_layout Standard
In the following sub chapters, only summaries of the IDL to C++ mapping
 are given.
 For a full description of the C++ mapping, please refer to 
\begin_inset CommandInset citation
LatexCommand cite
key "Henning"

\end_inset


\end_layout

\begin_layout Paragraph
Basic types
\end_layout

\begin_layout Standard
For these types, the mapping between IDL and C++ is obvious and defined
 in the following table.
\end_layout

\begin_layout Standard
\begin_inset VSpace 0.3cm
\end_inset


\end_layout

\begin_layout Standard
\align center
\begin_inset Tabular
<lyxtabular version="3" rows="11" columns="4">
<features rotate="0" islongtable="true" longtabularalignment="center">
<column alignment="center" valignment="top" width="0pt">
<column alignment="center" valignment="top" width="0pt">
<column alignment="center" valignment="top" width="0pt">
<column alignment="center" valignment="top" width="0pt">
<row>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Tango type name
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
IDL type
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
C++
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
typedef
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Tango::DevBoolean
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
boolean
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
CORBA::Boolean
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
unsigned char
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Tango::DevShort
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
short
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
CORBA::Short
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
short
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Tango::DevEnum
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
short
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
CORBA::Short
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Tango::DevLong
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
long
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
CORBA::Long
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
int
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Tango::DevLong64
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
long long
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
CORBA::LongLong
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
long long or long (64 bits chip)
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Tango::DevFloat
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
float
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
CORBA::Float
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
float
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Tango::DevDouble
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
double
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
CORBA::Double
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
double
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Tango::DevUShort
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
unsigned short
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
CORBA::UShort
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
unsigned short
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Tango::DevULong
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
unsigned long
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
CORBA::ULong
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
unsigned long
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Tango::DevULong64
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
unsigned long long
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
CORBA:ULongLong
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
unsigned long long or unsigned long (64 bits chip)
\end_layout

\end_inset
</cell>
</row>
</lyxtabular>

\end_inset


\end_layout

\begin_layout Standard
\begin_inset VSpace 0.3cm
\end_inset


\end_layout

\begin_layout Standard
The types defined in the column named C++ should be used for a better portabilit
y.
 All these types are defined in the CORBA namespace and therefore their
 qualified names is CORBA::xxx.
 The Tango data type DevEnum
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DevEnum
\end_layout

\end_inset

 is a special case described in detail in the chapter about advanced features.
\end_layout

\begin_layout Paragraph
Strings
\end_layout

\begin_layout Standard
Strings are mapped to 
\series bold
char *
\series default
.
 The use of 
\emph on
new
\emph default
 and 
\emph on
delete
\emph default
 for dynamic allocation of strings is not portable.
 Instead, you must use helper functions defined by CORBA (in the CORBA namespace
).
 These functions are :
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
    char *CORBA::string_alloc(unsigned long len);
\end_layout

\begin_layout Verbatim
    char *CORBA::string_dup(const char *);
\end_layout

\begin_layout Verbatim
    void CORBA::string_free(char *);
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
These functions handle dynamic memory for strings.
 The 
\emph on
string_alloc
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
string-alloc
\end_layout

\end_inset


\emph default
 function allocates one more byte than requested by the len parameter (for
 the trailing 0).
 The function 
\emph on
string_dup
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
string-dup
\end_layout

\end_inset


\emph default
 combines the allocation and copy.
 Both 
\emph on
string_alloc
\emph default
 and 
\emph on
string_dup
\emph default
 return a null pointer if allocation fails.
 The 
\emph on
string_free
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
string-free
\end_layout

\end_inset


\emph default
 function must be used to free memory allocated with 
\emph on
string_alloc
\emph default
 and 
\emph on
string_dup
\emph default
.
 Calling 
\emph on
string_free
\emph default
 for a null pointer is safe and does nothing.
 The following code fragment is an example of the Tango::DevString
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Tango::DevString
\end_layout

\end_inset

 type usage
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
     1     Tango::DevString str = CORBA::string_alloc(5);
\end_layout

\begin_layout Verbatim
     2     strcpy(str,"TANGO");
\end_layout

\begin_layout Verbatim
     3  
\end_layout

\begin_layout Verbatim
     4     Tango::DevString str1 = CORBA::string_dup("Do you want to danse
 TANGO?");
\end_layout

\begin_layout Verbatim
     5  
\end_layout

\begin_layout Verbatim
     6     CORBA::string_free(str);
\end_layout

\begin_layout Verbatim
     7     CORBA::string_free(str1);
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
Line 1-2 : TANGO is a five letters string.
 The CORBA::string_alloc function parameter is 5 but the function allocates
 6 bytes
\end_layout

\begin_layout Standard
Line 4 : Example of the CORBA::string_dup function
\end_layout

\begin_layout Standard
Line 6-7 : Memory deallocation
\end_layout

\begin_layout Paragraph
Sequences
\end_layout

\begin_layout Standard
IDL sequences
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
sequence
\end_layout

\end_inset

 are mapped to C++ classes that behave like vectors with a variable number
 of elements.
 Each IDL sequence type results in a separate C++ class.
 Within each class representing a IDL sequence types, you find the following
 method (only the main methods are related here) :
\end_layout

\begin_layout Enumerate
Four constructors.
 
\end_layout

\begin_deeper
\begin_layout Enumerate
A default constructor which creates an empty sequence.
\end_layout

\begin_layout Enumerate
The maximum constructor which creates a sequence with memory allocated for
 at least the number of elements passed as argument.
 This does not limit the number of element in the sequence but only the
 way how memory is allocated to store element
\end_layout

\begin_layout Enumerate
A sophisticated constructor where it is possible to assign the memory used
 by the sequence with a preallocated buffer.
\end_layout

\begin_layout Enumerate
A copy constructor which does a deep copy
\end_layout

\end_deeper
\begin_layout Enumerate
An assignment operator which does a deep copy
\end_layout

\begin_layout Enumerate
A 
\emph on
length
\emph default
 accessor which simply returns the current number of elements in the sequence
\end_layout

\begin_layout Enumerate
A 
\emph on
length
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
length
\end_layout

\end_inset


\emph default
 modifier which changes the length of the sequence (which is different than
 the number of elements in the sequence)
\end_layout

\begin_layout Enumerate
Overloading of the [] operator.
 The subscript operator [] provides access to the sequence element.
 For a sequence containing elements of type T, the [] operator is overloaded
 twice to return value of type T & and const T &.
 Insertion into a sequence using the [] operator for the const T & make
 a deep copy.
 Sequence are numbered between 0 and 
\emph on
length
\emph default
() -1.
\end_layout

\begin_layout Standard
Note that using the maximum constructor will not prevent you from setting
 the length of the sequence with a call to the length modifier.
 The following code fragment is an example of how to use a Tango::DevVarLongArra
y
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Tango::DevVarLongArray
\end_layout

\end_inset

 type
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
     1     Tango::DevVarLongArray *mylongseq_ptr;
\end_layout

\begin_layout Verbatim
     2     mylongseq_ptr = new Tango::DevVarLongArray();
\end_layout

\begin_layout Verbatim
     3     mylongseq_ptr->length(4);
\end_layout

\begin_layout Verbatim
     4  
\end_layout

\begin_layout Verbatim
     5     (*mylongseq_ptr)[0] = 1;
\end_layout

\begin_layout Verbatim
     6     (*mylongseq_ptr)[1] = 2;
\end_layout

\begin_layout Verbatim
     7     (*mylongseq_ptr)[2] = 3;
\end_layout

\begin_layout Verbatim
     8     (*mylongseq_ptr)[3] = 4;
\end_layout

\begin_layout Verbatim
     9  
\end_layout

\begin_layout Verbatim
    10     // (*mylongseq_ptr)[4] = 5;
\end_layout

\begin_layout Verbatim
    11  
\end_layout

\begin_layout Verbatim
    12     CORBA::Long nb_elt = mylongseq_ptr->length();
\end_layout

\begin_layout Verbatim
    13  
\end_layout

\begin_layout Verbatim
    14     mylongseq_ptr->length(5);
\end_layout

\begin_layout Verbatim
    15     (*mylongseq_ptr)[4] = 5;
\end_layout

\begin_layout Verbatim
    16  
\end_layout

\begin_layout Verbatim
    17     for (int i = 0;i < mylongseq_ptr->length();i++)
\end_layout

\begin_layout Verbatim
    18          cout << "Sequence elt " << i + 1 << " = " << (*mylongseq_ptr)[i]
 << endl;
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
Line 1 : Declare a pointer to Tango::DevVarLongArray type which is a sequence
 of long
\end_layout

\begin_layout Standard
Line 2 : Create an empty sequence
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
sequence
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Line 3 : Change the length
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
length
\end_layout

\end_inset

 of the sequence to 4
\end_layout

\begin_layout Standard
Line 5 - 8 : Initialize sequence elements
\end_layout

\begin_layout Standard
Line 10 ; Oups !!! The length of the sequence is 4.
 The behavior of this line is undefined and may be a core can be dumped
 at run time
\end_layout

\begin_layout Standard
Line 12 : Get the number of element actually stored in the sequence
\end_layout

\begin_layout Standard
Line 14-15 : Grow the sequence to five elements and initialize element number
 5
\end_layout

\begin_layout Standard
Line 17-18 : Print sequence element
\end_layout

\begin_layout Standard
Another example for the Tango::DevVarStringArray
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Tango::DevVarStringArray
\end_layout

\end_inset

 type is given
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
     1     Tango::DevVarStringArray mystrseq(4);
\end_layout

\begin_layout Verbatim
     2     mystrseq.length(4);
\end_layout

\begin_layout Verbatim
     3  
\end_layout

\begin_layout Verbatim
     4     mystrseq[0] = CORBA::string_dup("Rock and Roll");
\end_layout

\begin_layout Verbatim
     5     mystrseq[1] = CORBA::string_dup("Bossa Nova");
\end_layout

\begin_layout Verbatim
     6     mystrseq[2] = CORBA::string_dup(
\begin_inset Quotes eld
\end_inset

Waltz
\begin_inset Quotes erd
\end_inset

);
\end_layout

\begin_layout Verbatim
     7     mystrseq[3] = CORBA::string_dup("Tango");
\end_layout

\begin_layout Verbatim
     8  
\end_layout

\begin_layout Verbatim
     9     CORBA::Long nb_elt = mystrseq.length();
\end_layout

\begin_layout Verbatim
    10  
\end_layout

\begin_layout Verbatim
    11     for (int i = 0;i < mystrseq.length();i++)
\end_layout

\begin_layout Verbatim
    12          cout << "Sequence elt " << i + 1 << " = " << mystrseq[i]
 << endl;
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
Line 1 : Create a sequence using the maximum constructor
\end_layout

\begin_layout Standard
Line 2 : Set the sequence length to 4.
 This is mandatory even if you used the maximum constructor.
\end_layout

\begin_layout Standard
Line 4-7 : Populate the sequence
\end_layout

\begin_layout Standard
Line 9 : Get how many strings are stored into the sequence
\end_layout

\begin_layout Standard
Line 11-12 : Print sequence elements.
\end_layout

\begin_layout Paragraph
Structures
\end_layout

\begin_layout Standard
Only three TANGO types are defined as structures.
 These types are the Tango::DevVarLongStringArray
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Tango::DevVarLongStringArray
\end_layout

\end_inset

, the Tango::DevVarDoubleStringArray
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Tango::DevVarDoubleStringArray
\end_layout

\end_inset

 and the Tango::DevEncoded
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Tango::DevEncoded
\end_layout

\end_inset

 data type.
 IDL structures map to C++ structures with corresponding members.
 For the Tango::DevVarLongStringArray, the two members are named 
\emph on
svalue
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
svalue
\end_layout

\end_inset


\emph default
 for the sequence of strings and 
\emph on
lvalue
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
lvalue
\end_layout

\end_inset


\emph default
 for the sequence of longs.
 For the Tango::DevVarDoubleStringArray, the two structure members are called
 
\emph on
svalue
\emph default
 for the sequence of strings and 
\emph on
dvalue
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
dvalue
\end_layout

\end_inset


\emph default
 for the sequence of double.
 For the Tango::DevEncoded, the two structure members are called 
\emph on
encoded_format
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
encoded-format
\end_layout

\end_inset


\emph default
 for a string describing the data coding and 
\emph on
encoded_data
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
encoded-data
\end_layout

\end_inset


\emph default
 for the data themselves.
 The encoded_data field type is a Tango::DevVarCharArray.
 An example of the usage of the Tango::DevVarLongStringArray type is detailed
 below.
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
     1     Tango::DevVarLongStringArray my_vl;
\end_layout

\begin_layout Verbatim
     2  
\end_layout

\begin_layout Verbatim
     3     myvl.svalue.length(2);
\end_layout

\begin_layout Verbatim
     4     myvl.svalue[0] = CORBA_string_dup("Samba");
\end_layout

\begin_layout Verbatim
     5     myvl.svalue[1] = CORBA_string_dup("Rumba");
\end_layout

\begin_layout Verbatim
     6  
\end_layout

\begin_layout Verbatim
     7     myvl.lvalue.length(1);
\end_layout

\begin_layout Verbatim
     8     myvl.lvalue[0] = 10;
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
Line 1 : Declaration of the structure
\end_layout

\begin_layout Standard
Line 3-5 : Initialization of two strings in the sequence of string member
\end_layout

\begin_layout Standard
Line 7-8 : Initialization of one long in the sequence of long member
\end_layout

\begin_layout Paragraph
The DevState data type
\end_layout

\begin_layout Standard
The Tango::DevState
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Tango::DevState
\end_layout

\end_inset

 data type is used to transfer device state between client and server.
 It is a IDL enumeration.
 IDL enumerated types map to C++ enumerations (amazing no!) with a trailing
 dummy enumerator to force enumeration to be a 32 bit type.
 The first enumerator will have the value 0, the next one will have the
 value 1 and so on.
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
     1     Tango::DevState state;
\end_layout

\begin_layout Verbatim
     2  
\end_layout

\begin_layout Verbatim
     3     state = Tango::ON;
\end_layout

\begin_layout Verbatim
     4     state = Tango::FAULT;
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Subsection
Passing data between client and server
\end_layout

\begin_layout Standard
In order to have one definition of the CORBA operation used to send a command
 to a device whatever the command data type is, TANGO uses CORBA IDL 
\series bold
any
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
any
\end_layout

\end_inset


\series default
 object.
 The IDL type 
\emph on
any
\emph default
 provides a universal type that can hold a value of arbitrary IDL types.
 Type 
\emph on
any
\emph default
 therefore allows you to send and receive values whose types are not fixed
 at compile time.
\end_layout

\begin_layout Standard
Type 
\emph on
any
\emph default
 is often compared to a void * in C.
 Like a pointer to void, an 
\emph on
any
\emph default
 value can denote a datum of any type.
 However, there is an important difference; whereas a void * denotes a completel
y untyped value that can be interpreted only with advance knowledge of its
 type, values of type 
\emph on
any
\emph default
 maintain type safety.
 For example, if a sender places a string value into an 
\emph on
any
\emph default
, the receiver cannot extract the string as a value of the wrong type.
 Attempt to read the contents of an 
\emph on
any
\emph default
 as the wrong type cause a run-time error.
\end_layout

\begin_layout Standard
Internally, a value of type 
\emph on
any
\emph default
 consists of a pair of values.
 One member of the pair is the actual value contained inside the 
\emph on
any
\emph default
 and the other member of the pair is the type code.
 The type code is a description of the value's type.
 The type description is used to enforce type safety when the receiver extracts
 the value.
 Extraction of the value succeeds only if the receiver extracts the value
 as a type that matches the information in the type code.
\end_layout

\begin_layout Standard
Within TANGO, the command input and output parameters are objects of the
 IDL 
\emph on
any
\emph default
 type.
 Only insertion/extraction of all types defined as command data types is
 possible into/from these 
\emph on
any
\emph default
 objects.
\end_layout

\begin_layout Subsubsection
C++ mapping for IDL any type
\end_layout

\begin_layout Standard
The IDL any
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
any
\end_layout

\end_inset

 maps to the C++ class 
\series bold
CORBA::Any
\series default
.
 This class contains a large number of methods with mainly methods to insert/ext
ract data into/from the any.
 It provides a default constructor which builds an any which contains no
 value and a type code that indicates 
\begin_inset Quotes eld
\end_inset

no value
\begin_inset Quotes erd
\end_inset

.
 Such an any must be used for command which does not need input or output
 parameter.
 The operator 
\series bold
<<=
\series default
 is overloaded many times to insert data into an any object.
 The operator 
\series bold
>>=
\series default
 is overloaded many times to extract data from an any object.
\end_layout

\begin_layout Paragraph
Inserting/Extracting TANGO basic types
\end_layout

\begin_layout Standard
The insertion or extraction of TANGO basic types is straight forward using
 the <<= or >>= operators.
 Nevertheless, the Tango::DevBoolean type is mapped to a unsigned char and
 other IDL types are also mapped to char C++ type (The unsigned is not taken
 into account in the C++ overloading algorithm).
 Therefore, it is not possible to use operator overloading for these IDL
 types which map to C++ char.
 For the Tango::DevBoolean type, you must use the 
\emph on
CORBA::Any::from_boolean
\emph default
 or 
\emph on
CORBA::Any::to_boolean
\emph default
 intermediate objects defined in the CORBA::Any class.
\end_layout

\begin_layout Paragraph
Inserting/Extracting TANGO strings
\end_layout

\begin_layout Standard
The <<= operator is overloaded for const char * and always makes a deep
 copy.
 This deep copy is done using the CORBA::
\emph on
string_dup
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
string-dup
\end_layout

\end_inset


\emph default
 function.
 The extraction of strings uses the >>= overloaded operator.
 The main point is that the Any
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
any
\end_layout

\end_inset

 object retains ownership of the string, so the returned pointer points
 at memory
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
memory
\end_layout

\end_inset

 inside the Any.
 This means that you must not deallocate the extracted string and you must
 treat the extracted string as read-only.
\end_layout

\begin_layout Paragraph
Inserting/Extracting TANGO sequences
\end_layout

\begin_layout Standard
Insertion and extraction of sequences
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
sequence
\end_layout

\end_inset

 also uses the overloaded <<= and >>= operators.
 The insertion operator is overloaded twice: once for insertion by reference
 and once for insertion by pointer.
 If you insert a value by reference, the insertion makes a deep copy.
 If you insert a value by pointer, the Any
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
any
\end_layout

\end_inset

 assumes the ownership of the pointed-to memory
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
memory
\end_layout

\end_inset

.
 
\end_layout

\begin_layout Standard
Extraction is always by pointer.
 As with strings, you must treat the extracted pointer as read-only and
 must not deallocate it because the pointer points at memory internal to
 the Any.
\end_layout

\begin_layout Paragraph
Inserting/Extracting TANGO structures
\end_layout

\begin_layout Standard
This is identical to inserting/extracting sequences.
\end_layout

\begin_layout Paragraph
Inserting/Extracting TANGO enumeration
\end_layout

\begin_layout Standard
This is identical to inserting/extracting basic types
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
     1    CORBA::Any a;
\end_layout

\begin_layout Verbatim
     2    Tango::DevLong l1,l2;
\end_layout

\begin_layout Verbatim
     3    l1 = 2;
\end_layout

\begin_layout Verbatim
     4    a <<= l1;
\end_layout

\begin_layout Verbatim
     5    a >>= l2;
\end_layout

\begin_layout Verbatim
     6  
\end_layout

\begin_layout Verbatim
     7    CORBA::Any b;
\end_layout

\begin_layout Verbatim
     8    Tango::DevBoolean b1,b2;
\end_layout

\begin_layout Verbatim
     9    b1 = true;
\end_layout

\begin_layout Verbatim
    10    b <<= CORBA::Any::from_boolean(b1);
\end_layout

\begin_layout Verbatim
    11    b >>= CORBA::Any::to_boolean(b2);
\end_layout

\begin_layout Verbatim
    12  
\end_layout

\begin_layout Verbatim
    13    CORBA::Any s;
\end_layout

\begin_layout Verbatim
    14    Tango::DevString str1,str2;
\end_layout

\begin_layout Verbatim
    15    str1 = "I like dancing TANGO";
\end_layout

\begin_layout Verbatim
    16    s <<= str1;
\end_layout

\begin_layout Verbatim
    17    s >>= str2;
\end_layout

\begin_layout Verbatim
    18  
\end_layout

\begin_layout Verbatim
    19  //   CORBA::string_free(str2);
\end_layout

\begin_layout Verbatim
    20  //   a <<= CORBA::string_dup("Oups");
\end_layout

\begin_layout Verbatim
    21  
\end_layout

\begin_layout Verbatim
    22    CORBA::Any seq;
\end_layout

\begin_layout Verbatim
    23    Tango::DevVarFloatArray fl_arr1;
\end_layout

\begin_layout Verbatim
    24    fl_arr1.length(2);
\end_layout

\begin_layout Verbatim
    25    fl_arr1[0] = 1.0;
\end_layout

\begin_layout Verbatim
    26    fl_arr1[1] = 2.0;
\end_layout

\begin_layout Verbatim
    27    seq <<= fl_arr1;
\end_layout

\begin_layout Verbatim
    28    const Tango::DevVarFloatArray *fl_arr_ptr;
\end_layout

\begin_layout Verbatim
    29    seq >>= fl_arr_ptr;
\end_layout

\begin_layout Verbatim
    30  
\end_layout

\begin_layout Verbatim
    31  //   delete fl_arr_ptr;
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
Line 1-5 : Insertion and extraction of Tango::DevLong type
\end_layout

\begin_layout Standard
Line 7-11 Insertion and extraction of Tango::DevBoolean type using the CORBA::An
y::from_boolean and CORBA::Any::to_boolean intermediate structure
\end_layout

\begin_layout Standard
Line 13-17 : Insertion and extraction of Tango::DevString type
\end_layout

\begin_layout Standard
Line 19 : Wrong ! You should not deallocate a string extracted from an any
\end_layout

\begin_layout Standard
Line 20 : Wrong ! Memory leak because the <<= operator will do the copy.
 
\end_layout

\begin_layout Standard
Line 22-29 : Insertion and extraction of Tango::DevVarxxxArray types.
 This is an insertion by reference and the use of the <<= operator makes
 a deep copy of the sequence.
 Therefore, after line 27, it is possible to deallocate the sequence
\end_layout

\begin_layout Standard
Line 31: Wrong.! You should not deallocate a sequence extracted from an any
\end_layout

\begin_layout Subsubsection
The insert and extract methods of the Command class
\end_layout

\begin_layout Standard
In order to simplify the insertion/extraction into/from Any
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
any
\end_layout

\end_inset

 objects, small helper methods have been written in the Command
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Command
\end_layout

\end_inset

 class.
 The signatures of these methods are :
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
     1          void extract
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
extract
\end_layout

\end_inset

(const CORBA::Any &,<Tango type> &);
\end_layout

\begin_layout Verbatim
     2          CORBA::Any *insert
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
insert
\end_layout

\end_inset

(<Tango type>);
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
An 
\emph on
extract
\emph default
 method has been written for all Tango types.
 These method extract the data from the Any object passed as parameter and
 throw an exception if the Any data type is incompatible with the awaiting
 type.
 An 
\emph on
insert
\emph default
 method have been written for all Tango types.
 These method create an Any object, insert the data into the Any and return
 a pointer to the created Any.
 For Tango types mapped to sequences or structures, two 
\emph on
insert
\emph default
 methods have been written: one for the insertion from pointer and the other
 for the insertion from reference.
 For Tango strings, two 
\emph on
insert
\emph default
 methods have been written: one for insertion from a classical Tango::DevString
 type and the other from a const Tango::DevString type.
 The first one deallocate the memory after the insert into the Any object.
 The second one only inserts the string into the Any object.
 
\end_layout

\begin_layout Standard
The previous example can be rewritten using the insert/extract helper methods
 (We suppose that we can use the Command class insert/extract methods)
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
     1    Tango::DevLong l1,l2;
\end_layout

\begin_layout Verbatim
     2    l1 = 2;
\end_layout

\begin_layout Verbatim
     3    CORBA::Any *a_ptr = insert(l1);
\end_layout

\begin_layout Verbatim
     4    extract(*a_ptr,l2);
\end_layout

\begin_layout Verbatim
     5  
\end_layout

\begin_layout Verbatim
     6    Tango::DevBoolean b1,b2;
\end_layout

\begin_layout Verbatim
     7    b1 = true;
\end_layout

\begin_layout Verbatim
     8    CORBA::Any *b_ptr = insert(b1);
\end_layout

\begin_layout Verbatim
     9    extract(*b_ptr,b2);
\end_layout

\begin_layout Verbatim
    10  
\end_layout

\begin_layout Verbatim
    11    Tango::DevString str1,str2;
\end_layout

\begin_layout Verbatim
    12    str1 = "I like dancing TANGO";
\end_layout

\begin_layout Verbatim
    13    CORBA::Any *s_ptr = insert(str1);
\end_layout

\begin_layout Verbatim
    14    extract(*s_ptr,str2);
\end_layout

\begin_layout Verbatim
    15  
\end_layout

\begin_layout Verbatim
    16    Tango::DevVarFloatArray fl_arr1;
\end_layout

\begin_layout Verbatim
    17    fl_arr1.length(2);
\end_layout

\begin_layout Verbatim
    18    fl_arr1[0] = 1.0;
\end_layout

\begin_layout Verbatim
    19    fl_arr1[1] = 2.0;
\end_layout

\begin_layout Verbatim
    20    insert(fl_arr1);
\end_layout

\begin_layout Verbatim
    21    CORBA::Any *seq_ptr = insert(fl_arr1);
\end_layout

\begin_layout Verbatim
    22    Tango::DevVarFloatArray *fl_arr_ptr;
\end_layout

\begin_layout Verbatim
    23    extract(*seq_ptr,fl_arr_ptr);
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
Line 1-4 : Insertion and extraction of Tango::DevLong type
\end_layout

\begin_layout Standard
Line 6-9 : Insertion and extraction of Tango::DevBoolean type 
\end_layout

\begin_layout Standard
Line 11-14 : Insertion and extraction of Tango::DevString type
\end_layout

\begin_layout Standard
Line 16-23 : Insertion and extraction of Tango::DevVarxxxArray types.
 This is an insertion by reference which makes a deep copy of the sequence.
 Therefore, after line 20, it is possible to deallocate the sequence
\end_layout

\begin_layout Subsection
C++ memory management
\end_layout

\begin_layout Standard
The rule described here are valid for variable length command data types
 like Tango::DevString or all the Tango:: DevVarxxxxArray types.
\end_layout

\begin_layout Standard
The method executing the command must allocate the memory used to pass data
 back to the client or use static memory (like buffer declares as object
 data member.
 If necessary, the ORB will deallocate this memory after the data have been
 sent to the caller.
 Fortunately, for incoming data, the method have no memory
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
memory
\end_layout

\end_inset

 management responsibilities.
 The details about memory management given in this chapter assume that the
 insert/extract methods of the Tango::Command class are used and only the
 method in the device object is discussed.
\end_layout

\begin_layout Subsubsection
For string
\end_layout

\begin_layout Standard
Example of a method receiving a Tango::DevString
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Tango::DevString
\end_layout

\end_inset

 and returning a Tango::DevString is detailed just below
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
     1  Tango::DevString MyDev::dev_string(Tango::DevString argin)
\end_layout

\begin_layout Verbatim
     2  {
\end_layout

\begin_layout Verbatim
     3      Tango::DevString        argout;
\end_layout

\begin_layout Verbatim
     4  
\end_layout

\begin_layout Verbatim
     5      cout << "the received string is " << argin << endl;
\end_layout

\begin_layout Verbatim
     6          
\end_layout

\begin_layout Verbatim
     7      string str("Am I a good Tango dancer ?");
\end_layout

\begin_layout Verbatim
     8      argout = new char[str.size() + 1];
\end_layout

\begin_layout Verbatim
     9      strcpy(argout,str.c_str());
\end_layout

\begin_layout Verbatim
    10          
\end_layout

\begin_layout Verbatim
    11      return argout;
\end_layout

\begin_layout Verbatim
    12  }
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
Note that there is no need to deallocate the memory used by the incoming
 string.
 Memory for the outgoing string is allocated at line 8, then it is initialized
 at the following line.
 The memory allocated at line 8 will be automatically freed by the usage
 of the 
\emph on
Command::insert
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
insert
\end_layout

\end_inset

()
\emph default
 method.
 Using this schema, memory
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
memory
\end_layout

\end_inset

 is allocated/freed each time the command is executed.
 For constant string length, a statically allocated buffer can be used.
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
     1  Tango::ConstDevString MyDev::dev_string(Tango::DevString argin)
\end_layout

\begin_layout Verbatim
     2  {
\end_layout

\begin_layout Verbatim
     3      Tango::ConstDevString   argout;
\end_layout

\begin_layout Verbatim
     4  
\end_layout

\begin_layout Verbatim
     5      cout << "the received string is " << argin << endl;
\end_layout

\begin_layout Verbatim
     6          
\end_layout

\begin_layout Verbatim
     7      argout = "Hello world"; 
\end_layout

\begin_layout Verbatim
     8      return argout;
\end_layout

\begin_layout Verbatim
     9  }
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
A Tango::ConstDevString
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Tango::ConstDevString
\end_layout

\end_inset

 data type is used.
 It is not a new data Tango data type.
 It has been introduced only to allows 
\emph on
Command::insert()
\emph default
 method overloading.
 The argout pointer is initialized at line 7 with memory statically allocated.
 In this case, no memory will be freed by the 
\emph on
Command::insert()
\emph default
 method.
 There is also no memory
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
memory
\end_layout

\end_inset

 copy in the contrary of the previous example.
 A buffer defined as object data member can also be used to set the argout
 pointer.
\end_layout

\begin_layout Subsubsection
For array/sequence
\end_layout

\begin_layout Standard
Example of a method returning a Tango::DevVarLongArray
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Tango::DevVarLongArray
\end_layout

\end_inset

 is detailed just below
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
     1  Tango::DevVarLongArray *MyDev::dev_array()
\end_layout

\begin_layout Verbatim
     2  {
\end_layout

\begin_layout Verbatim
     3      Tango::DevVarLongArray  *argout  = new Tango::DevVarLongArray();
\end_layout

\begin_layout Verbatim
     4                  
\end_layout

\begin_layout Verbatim
     5      long output_array_length = ...;
\end_layout

\begin_layout Verbatim
     6      argout->length(output_array_length);
\end_layout

\begin_layout Verbatim
     7      for (int i = 0;i < output_array_length;i++)
\end_layout

\begin_layout Verbatim
     8          (*argout)[i] = i;
\end_layout

\begin_layout Verbatim
     9  
\end_layout

\begin_layout Verbatim
    10      return argout;
\end_layout

\begin_layout Verbatim
    11  }
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
In this case, memory is allocated at line 3 and 6.
 Then, the sequence
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
sequence
\end_layout

\end_inset

 is populated.
 The sequence is created and returned using pointer.
 The 
\emph on
Command::insert()
\emph default
 method will insert the sequence into the CORBA::Any object using this pointer.
 Therefore, the CORBA::Any object will take ownership of the allocated memory.
 It will free it when it will be destroyed by the CORBA ORB after the data
 have been sent away.
 It is also possible to use a statically allocated memory
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
memory
\end_layout

\end_inset

 and to avoid copying in the sequence used to returned the data.
 This is explained in the following example assuming a buffer of long data
 is declared as device data member and named buffer.
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
     1  Tango::DevVarLongArray *MyDev::dev_array()
\end_layout

\begin_layout Verbatim
     2  {
\end_layout

\begin_layout Verbatim
     3      Tango::DevVarLongArray  *argout;
\end_layout

\begin_layout Verbatim
     4                  
\end_layout

\begin_layout Verbatim
     5      long output_array_length = ...;
\end_layout

\begin_layout Verbatim
     6      argout = create_DevVarLongArray(buffer,output_array_length);
\end_layout

\begin_layout Verbatim
     7      return argout;
\end_layout

\begin_layout Verbatim
     8  }
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
At line 3 only a pointer to a DevVarLongArray is defined.
 This pointer is set at line 6 using the 
\emph on
create_DevVarLongArray()
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
create-DevVarLongArray
\end_layout

\end_inset


\emph default
 method.
 This method will create a sequence using this buffer without memory allocation
 and with minimum copying.
 The 
\emph on
Command::insert()
\emph default
 method used here is the same than the one used in the previous example.
 The sequence is created in a way that the destruction of the CORBA::Any
 object in which the sequence will be inserted will not destroy the buffer.
 The following create_xxx methods are defined in the DeviceImpl class :
\end_layout

\begin_layout Standard
\begin_inset VSpace 0.3cm
\end_inset


\end_layout

\begin_layout Standard
\align center
\begin_inset Tabular
<lyxtabular version="3" rows="10" columns="2">
<features rotate="0" islongtable="true" longtabularalignment="center">
<column alignment="center" valignment="top" width="0pt">
<column alignment="center" valignment="top" width="0pt">
<row>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Method name
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
data type
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
create_DevVarCharArray()
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
unsigned char
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
create_DevVarShortArray()
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
short
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
create_DevVarLongArray()
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
DevLong
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
create_DevVarLong64Array()
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
DevLong64
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
create_DevVarFloatArray()
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
float
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
create_DevVarDoubleArray()
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
double
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
create_DevVarUShortArray()
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
unsigned short
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
create_DevVarULongArray()
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
DevULong
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
create_DevVarULong64Array()
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
DevULong64
\end_layout

\end_inset
</cell>
</row>
</lyxtabular>

\end_inset


\end_layout

\begin_layout Standard
\begin_inset VSpace 0.3cm
\end_inset


\end_layout

\begin_layout Subsubsection
For string array/sequence
\end_layout

\begin_layout Standard
Example of a method returning a Tango::DevVarStringArray
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Tango::DevVarStringArray
\end_layout

\end_inset

 is detailed just below
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
     1  Tango::DevVarStringArray *MyDev::dev_str_array()
\end_layout

\begin_layout Verbatim
     2  {
\end_layout

\begin_layout Verbatim
     3     Tango::DevVarStringArray *argout  = new Tango::DevVarStringArray();
\end_layout

\begin_layout Verbatim
     4  
\end_layout

\begin_layout Verbatim
     5     argout->length(3);
\end_layout

\begin_layout Verbatim
     6     (*argout)[0] = CORBA::string_dup("Rumba");
\end_layout

\begin_layout Verbatim
     7     (*argout)[1] = CORBA::string_dup("Waltz");
\end_layout

\begin_layout Verbatim
     8     string str("Jerck");
\end_layout

\begin_layout Verbatim
     9     (*argout)[2] = CORBA::string_dup(str.c_str());
\end_layout

\begin_layout Verbatim
    10     return argout;
\end_layout

\begin_layout Verbatim
    11  }
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
Memory is allocated at line 3 and 5.
 Then, the sequence
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
sequence
\end_layout

\end_inset

 is populated at lines 6,7 and 9.
 The usage of the 
\emph on
CORBA::string_dup
\emph default
 function also allocates memory.
 The sequence is created and returned using pointer.
 The 
\emph on
Command::insert()
\emph default
 method will insert the sequence into the CORBA::Any object using this pointer.
 Therefore, the CORBA::Any object will take ownership of the allocated memory.
 It will free it when it will be destroyed by the CORBA ORB after the data
 have been sent away.
 For portability reason, the ORB uses the 
\emph on
CORBA::string_free
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
string-free
\end_layout

\end_inset


\emph default
 function to free the memory
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
memory
\end_layout

\end_inset

 allocated for each string.
 This is why the corresponding 
\emph on
CORBA::string_du
\emph default
p
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
string-dup
\end_layout

\end_inset

 or 
\emph on
CORBA::string_alloc
\emph default
 function must be used to reserve this memory.It is also possible to use
 a statically allocated memory and to avoid copying in the sequence used
 to returned the data.
 This is explained in the following example assuming a buffer of pointer
 to char is declared as device data member and named int_buffer.
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
     1  Tango::DevVarStringArray *DocDs::dev_str_array()
\end_layout

\begin_layout Verbatim
     2  {
\end_layout

\begin_layout Verbatim
     3     int_buffer[0] = "first";
\end_layout

\begin_layout Verbatim
     4     int_buffer[1] = "second";
\end_layout

\begin_layout Verbatim
     5  
\end_layout

\begin_layout Verbatim
     6     Tango::DevVarStringArray *argout;
\end_layout

\begin_layout Verbatim
     7     argout = create_DevVarStringArray(int_buffer,2);
\end_layout

\begin_layout Verbatim
     8     return argout;
\end_layout

\begin_layout Verbatim
     9  }
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
The intermediate buffer is initialized with statically allocated memory
 at lines 3 and 4.
 The returned sequence is created at line 7 with the 
\emph on
create_DevVarStringArray()
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
create-DevVarStringArray
\end_layout

\end_inset


\emph default
 method.
 Like for classical array, the sequence is created in a way that the destruction
 of the CORBA::Any
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
any
\end_layout

\end_inset

 object in which the sequence will be inserted will not destroy the buffer.
\end_layout

\begin_layout Subsubsection
For Tango composed types
\end_layout

\begin_layout Standard
Tango supports only two composed types which are Tango::DevVarLongStringArray
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Tango::DevVarLongStringArray
\end_layout

\end_inset

 and Tango::DevVarDoubleStringArray
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Tango::DevVarDoubleStringArray
\end_layout

\end_inset

.
 These types are translated to C++ structure with two sequences.
 It is not possible to use memory statically allocated for these types.
 Each structure element must be initialized as described in the previous
 sub-chapters using the dynamically allocated memory case.
\end_layout

\begin_layout Subsection
Reporting errors
\begin_inset CommandInset label
LatexCommand label
name "sub:Reporting-errors"

\end_inset


\end_layout

\begin_layout Standard
Tango uses the C++ try/catch plus exception
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
exception
\end_layout

\end_inset

 mechanism to report errors.
 Two kind of errors can be transmitted between client and server :
\end_layout

\begin_layout Enumerate
CORBA system error.
 These exceptions are raised by the ORB and indicates major failures (A
 communication failure, An invalid object reference...)
\end_layout

\begin_layout Enumerate
CORBA user exception.
 These kind of exceptions are defined in the IDL file.
 This allows an exception to contain an arbitrary amount of error information
 of arbitrary type.
\end_layout

\begin_layout Standard
TANGO defines one user exception called 
\series bold
DevFailed
\series default

\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DevFailed
\end_layout

\end_inset

.
 This exception is a variable length array of 
\series bold
DevError
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DevError
\end_layout

\end_inset


\series default
 type (a sequence of DevError).
 The DevError type is a four fields structure.
 These fields are :
\end_layout

\begin_layout Enumerate
A string describing the type of the error.
 This string replaces an error code and allows a more easy management of
 include files.
\end_layout

\begin_layout Enumerate
The error severity.
 It is an enumeration with the three values which are WARN, ERR or PANIC.
\end_layout

\begin_layout Enumerate
A string describing in plain text the reason of the error
\end_layout

\begin_layout Enumerate
A string describing the origin of the error
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
error
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The Tango::DevFailed type is a sequence of DevError structures in order
 to transmit to the client what is the primary error reason when several
 classes are used within a command.
 The sequence element 0 must be the DevError structure describing the primary
 error.
 A method called 
\emph on
print_exception
\emph default
()
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
print-exception
\end_layout

\end_inset

 defined in the Tango::Except
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Except
\end_layout

\end_inset

 class prints the content of exception (CORBA system exception or Tango::DevFail
ed exception).
 Some static methods of the Tango::Except class called 
\emph on
throw_exception
\emph default
()
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
throw-exception
\end_layout

\end_inset

 can be used to throw Tango::DevFailed exception.
 Some other static methods called 
\emph on
re_throw_exception()
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
re-throw-exception
\end_layout

\end_inset


\emph default
 may also be used when the user want to add a new element in the exception
 sequence and re-throw the exception.
 Details on these methods can be found in 
\begin_inset CommandInset citation
LatexCommand cite
key "TANGO_ref_man"

\end_inset

.
\end_layout

\begin_layout Subsubsection
Example of throwing exception
\end_layout

\begin_layout Standard
This example is a piece of code from the 
\emph on
command_handler
\emph default
() method of the DeviceImpl class.
 An exception
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
exception
\end_layout

\end_inset

 is thrown to the client to indicate that the requested command is not defined
 in the command list.
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
     1    TangoSys_OMemStream o;
\end_layout

\begin_layout Verbatim
     2                  
\end_layout

\begin_layout Verbatim
     3    o << "Command " << command << " not found" << ends;
\end_layout

\begin_layout Verbatim
     4    Tango::Except::throw_exception("API_CommandNotFound",
\end_layout

\begin_layout Verbatim
     5                                o.str(),
\end_layout

\begin_layout Verbatim
     6                                "DeviceClass::command_handler");
\end_layout

\begin_layout Verbatim
     7  
\end_layout

\begin_layout Verbatim
     8  
\end_layout

\begin_layout Verbatim
     9    try
\end_layout

\begin_layout Verbatim
    10    {
\end_layout

\begin_layout Verbatim
    11        .....
\end_layout

\begin_layout Verbatim
    12    }
\end_layout

\begin_layout Verbatim
    13    catch (Tango::DevFailed &e)
\end_layout

\begin_layout Verbatim
    14    {
\end_layout

\begin_layout Verbatim
    15        TangoSys_OMemStream o;
\end_layout

\begin_layout Verbatim
    16                  
\end_layout

\begin_layout Verbatim
    17        o << "Command " << command << " not found" << ends;
\end_layout

\begin_layout Verbatim
    18        Tango::Except::re_throw_exception(e,
\end_layout

\begin_layout Verbatim
    19                                  "API_CommandNotFound",
\end_layout

\begin_layout Verbatim
    20                                  o.str(),
\end_layout

\begin_layout Verbatim
    21                                  "DeviceClass::command_handler");
\end_layout

\begin_layout Verbatim
    22    }
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
Line 1 : Build a memory stream.
 Use the TangoSys_MemStream because memory streams are not managed the same
 way between Windows and Unix
\end_layout

\begin_layout Standard
Line 3 : Build the reason string in the memory stream
\end_layout

\begin_layout Standard
Line 4-5 : Throw the exception to client using one of the 
\emph on
throw_exception
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
throw-exception
\end_layout

\end_inset


\emph default
 static method of the Except
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Except
\end_layout

\end_inset

 class.
 This throw_exception method used here allows the definition of the error
 type string, the reason string and the origin string of the DevError structure.
 The remaining DevError field (the error severity) will be set to its default
 value.
 Note that the first and third parameters are casted to a 
\emph on
const char *
\emph default
.
 Standard C++ defines that such a string is already a 
\emph on
const char *
\emph default
 but the GNU C++ compiler (release 2.95) does not use this type inside its
 function overloading but rather uses a 
\emph on
char *
\emph default
 which leads to calling the wrong function.
\end_layout

\begin_layout Standard
Line 13-22 : Re-throw an already catched tango::DevFailed exception with
 one more element in the exception sequence.
\end_layout

\begin_layout Section
The Tango Logging
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
logging
\end_layout

\end_inset

 Service 
\begin_inset CommandInset label
LatexCommand label
name "The-Tango-Logging chapter"

\end_inset


\end_layout

\begin_layout Standard
A first introduction about this logging service has been done in chapter
 
\begin_inset CommandInset ref
LatexCommand ref
reference "sec:The-Tango-Logging"

\end_inset


\end_layout

\begin_layout Standard
The TANGO Logging Service (TLS) gives the user the control over how much
 information is actually generated and to where it goes.
 In practice, the TLS allows to select both the logging level and targets
 of any device within the control system.
\end_layout

\begin_layout Subsection
Logging Targets
\end_layout

\begin_layout Standard
The TLS implementation allows each device logging requests to print simultaneous
ly to multiple destinations.
 In the TANGO terminology, an output destination is called a 
\series bold
logging target
\series default
.
 Currently, targets exist for console, file and log consumer device.
 
\end_layout

\begin_layout Standard
CONSOLE: logs are printed to the console (i.e.
 the standard output),
\end_layout

\begin_layout Standard
FILE: logs are stored in a XML file.
 A rolling mechanism is used to backup the log file when it reaches a certain
 size (see below), 
\end_layout

\begin_layout Standard
DEVICE: logs are sent to a device implementing a well known TANGO interface
 (see section 
\begin_inset CommandInset ref
LatexCommand ref
reference "sec:Tango-log-consumer"

\end_inset

 for a definition of the log consumer interface).
 One implementation of a log consumer associated to a graphical user interface
 is available within the Tango package.
 It is called the LogViewer
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
LogViewer
\end_layout

\end_inset

.
\end_layout

\begin_layout Standard
The device's logging behavior can be control by adding and/or removing targets.
\end_layout

\begin_layout Standard
Note : When the size of a log file (for file logging target) reaches the
 so-called rolling-file-threshold (rft), it is backuped as "current_log_file_nam
e" + "_1" and a new "current_log_file_name" is opened.
 Obviously, there is only one backup file at a time (i.e.
 any existing backup is destroyed before the current log file is backuped).
 The default threshold is 20 Mb, the minimum is 500 Kb and the maximum is
 1000 Mb.
\end_layout

\begin_layout Subsection
Logging Levels
\end_layout

\begin_layout Standard
Devices can be assigned a logging level.
 It acts as a filter to control the kind of information sent to the targets.
 Since, there are (usually) much more low level log statements than high
 level statements, the logging level also control the amount of information
 produced by the device.
 The TLS provides the following levels (semantic is just given to be indicative
 of what could be log at each level):
\end_layout

\begin_layout Standard
OFF: Nothing is logged
\end_layout

\begin_layout Standard
FATAL: A fatal error occurred.
 The process is about to abort
\end_layout

\begin_layout Standard
ERROR: An (unrecoverable) error occurred but the process is still alive
\end_layout

\begin_layout Standard
WARN: An error occurred but could be recovered locally
\end_layout

\begin_layout Standard
INFO: Provides information on important actions performed
\end_layout

\begin_layout Standard
DEBUG: Generates detailed information describing the internal behavior of
 a device
\end_layout

\begin_layout Standard
Levels are ordered the following way: 
\begin_inset ERT
status collapsed

\begin_layout Plain Layout


\backslash
begin{center}
\end_layout

\end_inset

DEBUG < INFO < WARN < ERROR < FATAL < OFF
\begin_inset ERT
status collapsed

\begin_layout Plain Layout


\backslash
end{center}
\end_layout

\end_inset


\end_layout

\begin_layout Standard
For a given device, a level is said to be enabled if it is greater or equal
 to the logging level assigned to this device.
 In other words, any logging request which level is lower than the device's
 logging level is ignored.
 
\end_layout

\begin_layout Standard
Note: The logging level can't be controlled at target level.
 The device's targets shared the same device logging level.
\end_layout

\begin_layout Subsection
Sending TANGO Logging Messages
\end_layout

\begin_layout Subsubsection
Logging macros in C++
\end_layout

\begin_layout Standard
The TLS provides the user with easy to use C++ macros with 
\emph on
printf
\emph default
 and 
\emph on
stream
\emph default
 like syntax.
 For each logging level, a macro is defined in both styles:
\end_layout

\begin_layout Itemize
LOG_{FATAL, ERROR, WARN, INFO or DEBUG}
\end_layout

\begin_layout Itemize
{FATAL, ERROR, WARN, INFO or DEBUG}_STREAM
\end_layout

\begin_layout Standard
These macros are supposed to be used within the device's main implementation
 class (i.e.
 the class that inherits (directly or indirectly) from the Tango::DeviceImpl
 class).
 In this context, they produce logging messages containing the device name.
 In other words, they automatically identify the log source.
 Section 
\begin_inset CommandInset ref
LatexCommand ref
reference "sub:C++-logging-in"

\end_inset

 gives a trick to log in the name of device outside its main implementation
 class.
 Printf like example:
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
LOG_DEBUG(("Msg#%d - Hello world", i++));
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
Stream like example:
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
DEBUG_STREAM << "Msg#" << i++ << "- Hello world" << endl;   
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
These two logging requests are equivalent.
 Note the double parenthesis in the printf version.
\end_layout

\begin_layout Subsubsection
C++ logging in the name of a device
\begin_inset CommandInset label
LatexCommand label
name "sub:C++-logging-in"

\end_inset


\end_layout

\begin_layout Standard
A device implementation is sometimes spread over several classes.
 Since all these classes implement the same device, their logging requests
 should be associated with this device name.
 Unfortunately, the C++ logging macros can't be used because they are outside
 the device's main implementation class.
 The Tango::LogAdapter class is a workaround for this limitation.
\end_layout

\begin_layout Standard
Any method not member of the device's main implementation class, which send
 log messages associated to a device must be a member of a class inheriting
 from the Tango::LogAdapter class.
 Here is an example:
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
1 class MyDeviceActualImpl: public Tango::LogAdapter
\end_layout

\begin_layout Verbatim
2 {
\end_layout

\begin_layout Verbatim
3 public :
\end_layout

\begin_layout Verbatim
4    MyDeviceActualImpl(...,Tango::DeviceImpl *device,...)
\end_layout

\begin_layout Verbatim
5    :Tango::LogAdpater(device)
\end_layout

\begin_layout Verbatim
6    {
\end_layout

\begin_layout Verbatim
7          ....
\end_layout

\begin_layout Verbatim
8 //
\end_layout

\begin_layout Verbatim
9 // The following log is associated to the device passed to the constructor
\end_layout

\begin_layout Verbatim
10 //
\end_layout

\begin_layout Verbatim
11         DEBUG_STREAM << "In MyDeviceActualImpl constructor" << endl;
\end_layout

\begin_layout Verbatim
12 
\end_layout

\begin_layout Verbatim
13         ....
\end_layout

\begin_layout Verbatim
14    }
\end_layout

\begin_layout Verbatim
15 };
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Section
Writing a device server process
\begin_inset CommandInset label
LatexCommand label
name "Writing_chapter"

\end_inset


\end_layout

\begin_layout Standard
Writing a device server can be made easier by adopting the correct approach.
 This chapter will describe how to write a device server process.
 It is divided into the following parts : understanding the device, defining
 device commands/attributes/pipes, choosing device state and writing the
 necessary classes.
 All along this chapter, examples will be given using the stepper motor
 device server.
 Writing a device server for our stepper motor example device means writing
 :
\end_layout

\begin_layout Itemize
The 
\emph on
main
\emph default
 function
\end_layout

\begin_layout Itemize
The 
\emph on
class_factory
\emph default
 method (only for C++ device server)
\end_layout

\begin_layout Itemize
The 
\emph on
StepperMotorClass
\emph default
 class
\end_layout

\begin_layout Itemize
The 
\emph on
DevReadPositionCmd
\emph default
 and 
\emph on
DevReadDirectionCmd
\emph default
 classes
\end_layout

\begin_layout Itemize
The 
\emph on
PositionAttr
\emph default
, 
\emph on
SetPositionAttr
\emph default
 and 
\emph on
DirectionAttr
\emph default
 classes
\end_layout

\begin_layout Itemize
The 
\emph on
StepperMotor
\emph default
 class.
 
\end_layout

\begin_layout Standard
All these functions and classes will be detailed.
 The stepper motor device server described in this chapter supports 2 commands
 and 3 attributes which are :
\end_layout

\begin_layout Itemize
Command DevReadPosition implemented using the inheritance
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
inheritance
\end_layout

\end_inset

 model
\end_layout

\begin_layout Itemize
Command DevReadDirection implemented using the template
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
template
\end_layout

\end_inset

 command model
\end_layout

\begin_layout Itemize
Attribute Position (position of the first motor).
 This attribute
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
attribute
\end_layout

\end_inset

 is readable and is linked with a writable attribute (called SetPosition).
 When the value of this attribute is requested by the client, the value
 of the associated writable attribute is also returned.
\end_layout

\begin_layout Itemize
Attribute SetPosition (writable attribute linked with the Position attribute).
 This attribute has some properties with user defined default value.
\end_layout

\begin_layout Itemize
Attribute Direction (direction of the first motor)
\end_layout

\begin_layout Standard
As the reader will understand during the reading of the following sub-chapters,
 the command and attributes classes (
\emph on
DevReadPositionCmd
\emph default
, 
\emph on
DevReadDirectionCmd
\emph default
, 
\emph on
PositionAttr
\emph default
, 
\emph on
SetPositionAttr
\emph default
 and 
\emph on
DirectionAttr
\emph default
) are very simple classes.
 A tool called 
\series bold
Pogo
\series default
 has been developped to automatically generate/maintain these classes and
 to write part of the code needed in the remaining one.
 See xx to know more on this Pogo tool.
\end_layout

\begin_layout Standard
In order to also gives an example of how the database objects part of the
 Tango device pattern could be used, our device have two properties.
 These properties are of the Tango long data types and are named 
\begin_inset Quotes eld
\end_inset

Max
\begin_inset Quotes erd
\end_inset

 and 
\begin_inset Quotes eld
\end_inset

Min
\begin_inset Quotes erd
\end_inset

.
\end_layout

\begin_layout Subsection
Understanding the device
\end_layout

\begin_layout Standard
The first step before writing a device server is to develop an understanding
 of the hardware to be programmed.
 The Equipment Responsible should have description of the hardware and its
 operating modes (manuals, spec sheets etc.).
 The Equipment Responsible must also provide specifications of what the
 device server should do.
 The Device Server Programmer should demand an exact description of the
 registers, alarms, interlocks and any timing constraints which have to
 be kept.
 It is very important to have a good understanding of the device interfacing
 before starting designing a new class.
 
\end_layout

\begin_layout Standard
Once the Device Server Programmer has understood the hardware the next important
 step is to define what is a logical device i.e.
 what part of the hardware will be abstracted out and treated as a logical
 device.
 In doing so the following points of the TDSOM should be kept in mind 
\end_layout

\begin_layout Itemize
Each device is known and accessed by its ascii name.
\end_layout

\begin_layout Itemize
The device is exported onto the network to be imported by applications.
\end_layout

\begin_layout Itemize
Each device belongs to a class.
\end_layout

\begin_layout Itemize
A list of commands exists per device.
\end_layout

\begin_layout Itemize
Applications use the device server api to execute commands on a device.
 
\end_layout

\begin_layout Standard
The above points have to be taken into account when designing the level
 of device abstraction.
 The definition of what is a device for a certain hardware is primarily
 the job of the Device Server Programmer and the Applications Programmer
 but can also involve the Equipment Responsible.
 The Device Server Programmer should make sure that the Applications Programmer
 agrees with her definition of what is a device.
\end_layout

\begin_layout Standard
Here are some guidelines to follow while defining the level of device abstractio
n - 
\end_layout

\begin_layout Itemize

\series bold
efficiency
\series default
, make sure that not a too fine level of device abstraction has been chosen.
 If possible group as many attributes together to form a device.
 Discuss this with the Applications Programmer to find out what is efficient
 for her application.
\end_layout

\begin_layout Itemize

\series bold
hardware independency
\series default
, one of the main reasons for writing device servers is to provide the Applicati
ons Programmer with a 
\emph on
software
\emph default
 interface as opposed to a 
\emph on
hardware
\emph default
 interface.
 Hide the hardware structure of the device.
 For example if the user is only interested in a single channel of a multichanne
l device then define each channel to be a logical device.
 The user should not be aware of hardware addresses or cabling details.
 The user is very often a scientist who has a physics-oriented world view
 and not a hardware-oriented world view.
 Hardware independency also has the advantage that applications are immune
 to hardware changes to the device 
\end_layout

\begin_layout Itemize

\series bold
object oriented world view
\series default
, another 
\emph on
raison d'etre
\emph default
 behind the device server model is to build up an object oriented view of
 the world.
 The device should resemble the user's view of the object as closely as
 possible.
 In the case of the ESRF's beam lines for example, the devices should resemble
 beam line scientist's view of the machine.
 
\end_layout

\begin_layout Itemize

\series bold
atomism
\series default
, each device can be considered like an atom - is a independent object.
 It should appear independent to the client even if behind the scenes it
 shares some hardware or software with other objects.
 This is often the case with multichannel devices where the user would like
 to see each channel as a device but it is obvious that the channels cannot
 be programmed completely independently.
 The logical device is there to hide or make transparent this fact.
 If it is impossible to send commands to one device without modifying another
 device then a single device should be made out the two devices.
 
\end_layout

\begin_layout Itemize

\series bold
tailored
\series default
 
\emph on
vs
\emph default
 
\series bold
general
\series default
, one of the philosophies of the TDSOM is to provide tailored solutions.
 For example instead of writing one 
\emph on
serial line
\emph default
 class which treats the general case of a serial line device and leaving
 the device protocol to be implemented in the client the TDSOM advocates
 implementing a device class which handles the protocol of the device.
 This way the client only has to know the commands of the class and not
 the details of the protocol.
 Nothing prevents the device class from using a general purpose serial line
 class if it exists of course.
\end_layout

\begin_layout Subsection
Defining device commands
\end_layout

\begin_layout Standard
Each device has a list of commands which can be executed by the application
 across the network or locally.
 These commands are the Application Programmer's network knobs and dials
 for interacting with the device.
\end_layout

\begin_layout Standard
The list of commands to be implemented depends on the capabilities of the
 hardware, the list of sensible functions which can be executed at a distance
 and of course the functionality required by the application.
 This implies a close collaboration between the Equipment Responsible, Device
 Server Programmer and the Application Programmer.
\end_layout

\begin_layout Standard
When drawing up the list of commands particular attention should be paid
 to the following points 
\end_layout

\begin_layout Itemize

\series bold
performance
\series default
, no single command should monopolize the device server for a long time
 (a nominal value for long is one second).
 Commands should be implemented in such a way that it executes immediately
 returning with a response.
 At best try to keep command execution time down to less than the typical
 overhead of an rpc call i.e.
 som milliseconds.
 This of course is not always possible e.g.
 a serial line device could require 100 milliseconds of protocol exchange.
 The Device Server Programmer should find the best trade-off between the
 users requirements and the devices capabilities.
 If a command implies a sequence of events which could last for a long time
 then implement the sequence of events in another thread - don't block the
 device server.
\end_layout

\begin_layout Itemize

\series bold
robustness
\series default
, should be provided which allow the client to recover from error conditions
 and or do a warm startup.
\end_layout

\begin_layout Subsubsection
Standard commands
\end_layout

\begin_layout Standard
A minimum set of three commands exist for all devices.
 These commands are 
\end_layout

\begin_layout Itemize
State
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
State
\end_layout

\end_inset

 which returns the state of a device
\end_layout

\begin_layout Itemize
Status
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Status
\end_layout

\end_inset

 which returns the status of the device as a formatted ascii string
\end_layout

\begin_layout Itemize
Init
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Init
\end_layout

\end_inset

 which re-initialize a device without changing its network connection
\end_layout

\begin_layout Standard
These commands have already been discussed in 
\begin_inset CommandInset ref
LatexCommand ref
reference "Auto_cmd"

\end_inset


\end_layout

\begin_layout Subsection
Choosing device state
\end_layout

\begin_layout Standard
The device state
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
state
\end_layout

\end_inset

 is a number which reflects the availability of the device.
 To simplify the coding for generic application, a predefined set of states
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
state
\end_layout

\end_inset

 are supported by TANGO.
 This list has 14 members which are
\end_layout

\begin_layout Standard
\begin_inset VSpace 0.3cm
\end_inset


\end_layout

\begin_layout Standard
\align center
\begin_inset Tabular
<lyxtabular version="3" rows="15" columns="1">
<features rotate="0" islongtable="true" longtabularalignment="center">
<column alignment="center" valignment="top" width="0pt">
<row>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
State name
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
ON
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
OFF
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
CLOSE
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
OPEN
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
INSERT
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
EXTRACT
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
MOVING
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
STANDBY
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
FAULT
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
INIT
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
RUNNING
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
ALARM
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
DISABLE
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
UNKNOWN
\end_layout

\end_inset
</cell>
</row>
</lyxtabular>

\end_inset


\end_layout

\begin_layout Standard
\begin_inset VSpace 0.3cm
\end_inset


\end_layout

\begin_layout Standard
The names used here have obvious meaning.
\end_layout

\begin_layout Subsection
Device server utilities to ease coding/debugging
\end_layout

\begin_layout Standard
The device server framework supports one set of utilities to ease the process
 of coding and debugging
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
debug
\end_layout

\end_inset

 device server code.
 This utility is :
\end_layout

\begin_layout Enumerate
The device server verbose
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
verbose
\end_layout

\end_inset

 option
\end_layout

\begin_layout Standard
Using this facility avoids the usage of the classical 
\begin_inset Quotes eld
\end_inset

#ifdef DEBUG
\begin_inset Quotes erd
\end_inset

 style which makes code less readable.
\end_layout

\begin_layout Subsubsection
The device server verbose option
\end_layout

\begin_layout Standard
Each device server supports a verbose
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
verbose
\end_layout

\end_inset

 option called 
\series bold
-v
\series default

\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
-v
\end_layout

\end_inset

.
 Four verbose levels are defined from 1 to 4.
 Level 4 is the most talkative one.
 If you use the -v option without specifying level, level 4 will be assumed.
\end_layout

\begin_layout Standard
Since Tango release 3, a Tango Logging Service has been introduced (detailed
 in chapter 
\begin_inset CommandInset ref
LatexCommand ref
reference "The-Tango-Logging chapter"

\end_inset

).
 This -v option set-up the logging service.
 If it used, it will automatically add a 
\emph on
console
\emph default
 target to all devices embedded within the device server process.
 Level 1 and 2 will set the logging level to all devices embedded within
 the device server to INFO.
 Level 3 and 4 will set the logging
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
logging
\end_layout

\end_inset

 level to all devices embedded within the device server to DEBUG.
 All messages sent by the API layer are associated to the administration
 device.
\end_layout

\begin_layout Subsubsection
C++ utilities to ease device server coding
\end_layout

\begin_layout Standard
Some utilities functions have been added in the C++ release to ease Tango
 device server development.
 These utilities allow the user to
\end_layout

\begin_layout Itemize
Init a C++ vector from a data of one of the Tango DevVarXXXArray data types
 
\end_layout

\begin_layout Itemize
Init a data of one of the Tango::DevVarxxxArray data type from a C++ vector
\end_layout

\begin_layout Itemize
Print a data of one of Tango::DevVarxxxArray data type
\end_layout

\begin_layout Standard
They mainly used the 
\begin_inset Quotes eld
\end_inset

<<
\begin_inset Quotes erd
\end_inset


\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
<<
\end_layout

\end_inset

 operator overloading features.
 The following code lines are an example of usage of these utilities.
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
     1    vector<string> v1;
\end_layout

\begin_layout Verbatim
     2    v1.push_back("one");
\end_layout

\begin_layout Verbatim
     3    v1.push_back("two");
\end_layout

\begin_layout Verbatim
     4    v1.push_back("three");
\end_layout

\begin_layout Verbatim
     5          
\end_layout

\begin_layout Verbatim
     6    Tango::DevVarStringArray s;
\end_layout

\begin_layout Verbatim
     7    s << v1;
\end_layout

\begin_layout Verbatim
     8    cout << s << endl;
\end_layout

\begin_layout Verbatim
     9  
\end_layout

\begin_layout Verbatim
    10    vector<string> v2;
\end_layout

\begin_layout Verbatim
    11    v2 << s;
\end_layout

\begin_layout Verbatim
    12          
\end_layout

\begin_layout Verbatim
    13    for (int i = 0;i < v2.size();i++)
\end_layout

\begin_layout Verbatim
    14       cout << "vector element = " << v2[i] << endl;
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
Line 1-4 : Create and Init a C++ string vector
\end_layout

\begin_layout Standard
Line 7 : Init a Tango::DevVarStringArray data from the C++ vector
\end_layout

\begin_layout Standard
Line 8 : Print all the Tango::DevVarStringArray element in one line of code.
\end_layout

\begin_layout Standard
Line 11 : Init a second empty C++ string vector with the content of the
 Tango::DevVarStringArray
\end_layout

\begin_layout Standard
Line 13-14 : Print vector element
\begin_inset Newline newline
\end_inset


\end_layout

\begin_layout Standard

\series bold
Warning
\series default
: Note that due to a strange behavior of the Windows VC++ compiler compared
 to other compilers, to use these utilities with the Windows VC++ compiler,
 you must add the line 
\begin_inset Quotes eld
\end_inset

using namespace tango
\begin_inset Quotes erd
\end_inset

 at the beginning of your source file.
\end_layout

\begin_layout Subsection
Avoiding name conflicts
\end_layout

\begin_layout Standard
Namespace are used to avoid name conflicts.
 Each device pattern implementation is defined within its own namespace
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
namespace
\end_layout

\end_inset

.
 The name of the namespace is the device pattern class name.
 In our example, the namespace name is 
\emph on
StepperMotor.
\end_layout

\begin_layout Subsection
The device server main function
\end_layout

\begin_layout Standard
A device server main
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
main
\end_layout

\end_inset

 function (or method) always follows the same framework.
 It exactly implements all the action described in chapter 
\begin_inset CommandInset ref
LatexCommand ref
reference "Server_startup"

\end_inset

.
 Even if it could be always the same, it has not been included in the library
 because some linkers are perturbed by the presence of two main functions.
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard

\end_layout

\begin_layout Verbatim
     1  #include <tango.h>
\end_layout

\begin_layout Verbatim
     2  
\end_layout

\begin_layout Verbatim
     3  int main(int argc,char *argv[])
\end_layout

\begin_layout Verbatim
     4  {
\end_layout

\begin_layout Verbatim
     5  
\end_layout

\begin_layout Verbatim
     6      Tango::Util *tg;
\end_layout

\begin_layout Verbatim
     7          
\end_layout

\begin_layout Verbatim
     8      try
\end_layout

\begin_layout Verbatim
     9      {
\end_layout

\begin_layout Verbatim
    10          
\end_layout

\begin_layout Verbatim
    11          tg = Tango::Util::init(argc,argv);
\end_layout

\begin_layout Verbatim
    12  
\end_layout

\begin_layout Verbatim
    13          tg->server_init();
\end_layout

\begin_layout Verbatim
    14  
\end_layout

\begin_layout Verbatim
    15          cout << "Ready to accept request" << endl;
\end_layout

\begin_layout Verbatim
    16          tg->server_run();
\end_layout

\begin_layout Verbatim
    17      }
\end_layout

\begin_layout Verbatim
    18      catch (bad_alloc)
\end_layout

\begin_layout Verbatim
    19      {
\end_layout

\begin_layout Verbatim
    20           cout << "Can't allocate memory!!!" << endl;
\end_layout

\begin_layout Verbatim
    21           cout << "Exiting" << endl;
\end_layout

\begin_layout Verbatim
    22      }
\end_layout

\begin_layout Verbatim
    23      catch (CORBA::Exception &e)
\end_layout

\begin_layout Verbatim
    24      {
\end_layout

\begin_layout Verbatim
    25           Tango::Except::print_exception(e);
\end_layout

\begin_layout Verbatim
    26                  
\end_layout

\begin_layout Verbatim
    27           cout << "Received a CORBA::Exception" << endl;
\end_layout

\begin_layout Verbatim
    28           cout << "Exiting" << endl;
\end_layout

\begin_layout Verbatim
    29      }
\end_layout

\begin_layout Verbatim
    30  
\end_layout

\begin_layout Verbatim
    31      tg->server_cleanup();
\end_layout

\begin_layout Verbatim
    32                  
\end_layout

\begin_layout Verbatim
    33      return(0);
\end_layout

\begin_layout Verbatim
    34  }
\end_layout

\begin_layout Standard

\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
Line 1 : Include the 
\series bold
tango.h
\series default
 file.
 This file is a master include file.
 It includes several other files.
 The list of files included by tango.h can be found in 
\begin_inset CommandInset citation
LatexCommand cite
key "TANGO_ref_man"

\end_inset


\end_layout

\begin_layout Standard
Line 11 : Create the instance of the Tango::Util
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Util
\end_layout

\end_inset

 class (a singleton).
 Passing argc,argv to this method is mandatory because the device server
 command line is checked when the Tango::Util object is constructed.
\end_layout

\begin_layout Standard
Line 13 : Start all the device pattern creation and initialization with
 the 
\emph on
server_init()
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
server-init
\end_layout

\end_inset


\emph default
 method
\end_layout

\begin_layout Standard
Line 16 : Put the server in a endless waiting loop with the 
\emph on
server_run()
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
server-run
\end_layout

\end_inset


\emph default
 method.
 In normal case, the process should never returns from this line.
\end_layout

\begin_layout Standard
Line 18-22 : Catch all exceptions due to memory allocation error, display
 a message to the user and exit
\end_layout

\begin_layout Standard
Line 23 : Catch all standard TANGO exception which could occur during device
 pattern creation and initialization
\end_layout

\begin_layout Standard
Line 25 : Print exception parameters
\end_layout

\begin_layout Standard
Line 27-28 : Print an additional message
\end_layout

\begin_layout Standard
Line 31 : Cleanup the server before exiting by calling the 
\emph on
server_cleanup()
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
server-cleanup
\end_layout

\end_inset


\emph default
 method.
\end_layout

\begin_layout Subsection
The DServer::class_factory method
\end_layout

\begin_layout Standard
As described in chapter 
\begin_inset CommandInset ref
LatexCommand ref
reference "DServer_class"

\end_inset

, C++ device server needs a 
\emph on
class_factory
\emph default
() method.
 This method creates all the device pattern implemented in the device server
 by calling their 
\emph on
init
\emph default
()
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
init
\end_layout

\end_inset

 method.
 The following is an example of a 
\emph on
class_factory
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
class-factory
\end_layout

\end_inset


\emph default
 method for a device server with one implementation of the device server
 pattern for stepper motor device.
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
     1  #include <tango.h>
\end_layout

\begin_layout Verbatim
     2  #include <steppermotorclass.h>
\end_layout

\begin_layout Verbatim
     3  
\end_layout

\begin_layout Verbatim
     4  void Tango::DServer::class_factory()
\end_layout

\begin_layout Verbatim
     5  {
\end_layout

\begin_layout Verbatim
     6  
\end_layout

\begin_layout Verbatim
     7     add_class(StepperMotor::StepperMotorClass::init("StepperMotor"));
\end_layout

\begin_layout Verbatim
     8  
\end_layout

\begin_layout Verbatim
     9  }
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
Line 1 : Include the Tango master include file
\end_layout

\begin_layout Standard
Line 2 : Include the steppermotorclass class definition file
\end_layout

\begin_layout Standard
Line 7 : Create the StepperMotorClass singleton by calling its 
\emph on
init
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
init
\end_layout

\end_inset


\emph default
 method and stores the returned pointer into the DServer object.
 Remember that all classes for the device pattern implementation for the
 stepper motor class is defined within a namespace
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
namespace
\end_layout

\end_inset

 called 
\emph on
StepperMotor
\emph default
.
\end_layout

\begin_layout Subsection
Writing the StepperMotorClass class
\begin_inset CommandInset label
LatexCommand label
name "Command fact"

\end_inset


\end_layout

\begin_layout Subsubsection
The class declaration file
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
     1  #include <tango.h>
\end_layout

\begin_layout Verbatim
     2  
\end_layout

\begin_layout Verbatim
     3  namespace StepperMotor
\end_layout

\begin_layout Verbatim
     4  {
\end_layout

\begin_layout Verbatim
     5  
\end_layout

\begin_layout Verbatim
     6  class StepperMotorClass : public Tango::DeviceClass
\end_layout

\begin_layout Verbatim
     7  {
\end_layout

\begin_layout Verbatim
     8  public:
\end_layout

\begin_layout Verbatim
     9      static StepperMotorClass *init(const char *);
\end_layout

\begin_layout Verbatim
    10      static StepperMotorClass *instance();
\end_layout

\begin_layout Verbatim
    11      ~StepperMotorClass() {_instance = NULL;}
\end_layout

\begin_layout Verbatim
    12          
\end_layout

\begin_layout Verbatim
    13  protected:
\end_layout

\begin_layout Verbatim
    14      StepperMotorClass(string &);
\end_layout

\begin_layout Verbatim
    15      static StepperMotorClass *_instance;
\end_layout

\begin_layout Verbatim
    16      void command_factory();
\end_layout

\begin_layout Verbatim
    17      void attribute_factory(vector<Tango::Attr *> &);
\end_layout

\begin_layout Verbatim
    18          
\end_layout

\begin_layout Verbatim
    19  public:
\end_layout

\begin_layout Verbatim
    20      void device_factory(const Tango::DevVarStringArray *);
\end_layout

\begin_layout Verbatim
    21  };
\end_layout

\begin_layout Verbatim
    22  
\end_layout

\begin_layout Verbatim
    23  } /* End of StepperMotor namespace */
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
Line 1 : Include the Tango master include file
\end_layout

\begin_layout Standard
Line 3 : This class is defined within the 
\emph on
StepperMotor
\emph default
 namespace
\end_layout

\begin_layout Standard
Line 6 : Class StepperMotorClass inherits from Tango::DeviceClass
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DeviceClass
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Line 9-10 : Definition of the 
\emph on
init
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
init
\end_layout

\end_inset


\emph default
 and 
\emph on
instance
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
instance
\end_layout

\end_inset


\emph default
 methods.
 These methods are static and can be called even if the object is not already
 constructed.
\end_layout

\begin_layout Standard
Line 11: The destructor
\end_layout

\begin_layout Standard
Line 14 : The class constructor.
 It is protected and can't be called from outside the class.
 Only the 
\emph on
init
\emph default
 method allows a user to create an instance of this class.
 See 
\begin_inset CommandInset citation
LatexCommand cite
key "Patterns"

\end_inset

 to get details about the singleton design pattern.
\end_layout

\begin_layout Standard
Line 15 : The instance pointer.
 It is static in order to set it to NULL during process initialization phase
\end_layout

\begin_layout Standard
Line 16 : Definition of the 
\emph on
command_factory
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
command-factory
\end_layout

\end_inset


\emph default
 method
\end_layout

\begin_layout Standard
Line 17 : Definition of the 
\emph on
attribute_factory
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
attribute-factory
\end_layout

\end_inset


\emph default
 method
\end_layout

\begin_layout Standard
Line 20 : Definition of the 
\emph on
device_factory
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
device-factory
\end_layout

\end_inset


\emph default
 method
\end_layout

\begin_layout Subsubsection
The singleton related methods
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
 
\end_layout

\begin_layout Verbatim
     1  #include <tango.h>
\end_layout

\begin_layout Verbatim
     2  
\end_layout

\begin_layout Verbatim
     3  #include <steppermotor.h>
\end_layout

\begin_layout Verbatim
     4  #include <steppermotorclass.h>
\end_layout

\begin_layout Verbatim
     5  
\end_layout

\begin_layout Verbatim
     6  namespace StepperMotor
\end_layout

\begin_layout Verbatim
     7  {
\end_layout

\begin_layout Verbatim
     8  
\end_layout

\begin_layout Verbatim
     9  StepperMotorClass *StepperMotorClass::_instance = NULL;
\end_layout

\begin_layout Verbatim
    10  
\end_layout

\begin_layout Verbatim
    11  StepperMotorClass::StepperMotorClass(string &s):
\end_layout

\begin_layout Verbatim
    12  Tango::DeviceClass(s)
\end_layout

\begin_layout Verbatim
    13  {
\end_layout

\begin_layout Verbatim
    14      INFO_STREAM << "Entering StepperMotorClass constructor" << endl;
\end_layout

\begin_layout Verbatim
    15          
\end_layout

\begin_layout Verbatim
    16      INFO_STREAM << "Leaving StepperMotorClass constructor" << endl;
\end_layout

\begin_layout Verbatim
    17  }
\end_layout

\begin_layout Verbatim
    18  
\end_layout

\begin_layout Verbatim
    19  
\end_layout

\begin_layout Verbatim
    20  StepperMotorClass *StepperMotorClass::init(const char *name)
\end_layout

\begin_layout Verbatim
    21  {
\end_layout

\begin_layout Verbatim
    22      if (_instance == NULL)
\end_layout

\begin_layout Verbatim
    23      {
\end_layout

\begin_layout Verbatim
    24            try
\end_layout

\begin_layout Verbatim
    25            {
\end_layout

\begin_layout Verbatim
    26                 string s(name);
\end_layout

\begin_layout Verbatim
    27                 _instance = new StepperMotorClass(s);
\end_layout

\begin_layout Verbatim
    28            }
\end_layout

\begin_layout Verbatim
    29            catch (bad_alloc)
\end_layout

\begin_layout Verbatim
    30            {
\end_layout

\begin_layout Verbatim
    31                 throw;
\end_layout

\begin_layout Verbatim
    32            }               
\end_layout

\begin_layout Verbatim
    33      }               
\end_layout

\begin_layout Verbatim
    34      return _instance;
\end_layout

\begin_layout Verbatim
    35  }
\end_layout

\begin_layout Verbatim
    36  
\end_layout

\begin_layout Verbatim
    37  StepperMotorClass *StepperMotorClass::instance()
\end_layout

\begin_layout Verbatim
    38  {
\end_layout

\begin_layout Verbatim
    39      if (_instance == NULL)
\end_layout

\begin_layout Verbatim
    40      {
\end_layout

\begin_layout Verbatim
    41            cerr << "Class is not initialised !!" << endl;
\end_layout

\begin_layout Verbatim
    42            exit(-1);
\end_layout

\begin_layout Verbatim
    43      }
\end_layout

\begin_layout Verbatim
    44      return _instance;
\end_layout

\begin_layout Verbatim
    45  }
\end_layout

\begin_layout Verbatim
 
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
Line 1-4 : include files: the Tango master include file (tango.h), the StepperMot
orClass class definition file (steppermotorclass.h) and the StepperMotor
 class definition file (steppermotor.h)
\end_layout

\begin_layout Standard
Line 6 : Open the 
\emph on
StepperMotor
\emph default
 namespace.
\end_layout

\begin_layout Standard
Line 9 : Initialize the static _instance field of the StepperMotorClass
 class to NULL
\end_layout

\begin_layout Standard
Line 11-18 : The class constructor.
 It takes an input parameter which is the controlled device class name.
 This parameter is passed to the constructor of the DeviceClass
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DeviceClass
\end_layout

\end_inset

 class.
 Otherwise, the constructor does nothing except printing a message
\end_layout

\begin_layout Standard
Line 20-35 : The 
\emph on
init
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
init
\end_layout

\end_inset


\emph default
 method.
 This method needs an input parameter which is the controlled device class
 name (StepperMotor in this case).
 This method checks is the instance is already constructed by testing the
 _instance data member.
 If the instance is not constructed, it creates one.
 If the instance is already constructed, the method simply returns a pointer
 to it.
\end_layout

\begin_layout Standard
Line 37-45 : The 
\emph on
instance
\emph default
 method.
 This method is very similar to the 
\emph on
init
\emph default
 method except that if the instance is not already constructed.
 the method print a message and abort the process.
\end_layout

\begin_layout Standard
As you can understand, it is not possible to construct more than one instance
 of the StepperMotorClass (it is a singleton
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
singleton
\end_layout

\end_inset

) and the 
\emph on
init
\emph default
 method must be called prior to any other method.
\end_layout

\begin_layout Subsubsection
The command_factory method
\end_layout

\begin_layout Standard
Within our example, the stepper motor device supports two commands
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
command
\end_layout

\end_inset

 which are called DevReadPosition and DevReadDirection.
 These two command takes a Tango::DevLong argument as input and output parameter.
 The first command is created using the inheritance
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
inheritance
\end_layout

\end_inset

 model and the second command is created using the template
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
template
\end_layout

\end_inset

 command model.
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
     1  
\end_layout

\begin_layout Verbatim
     2  void StepperMotorClass::command_factory()
\end_layout

\begin_layout Verbatim
     3  {
\end_layout

\begin_layout Verbatim
     4          command_list.push_back(new DevReadPositionCmd("DevReadPosition",
\end_layout

\begin_layout Verbatim
     5                                                        Tango::DEV_LONG,
\end_layout

\begin_layout Verbatim
     6                                                        Tango::DEV_LONG,
\end_layout

\begin_layout Verbatim
     7                                                        "Motor number
 (0-7)",
\end_layout

\begin_layout Verbatim
     8                                                        "Motor position"))
;
\end_layout

\begin_layout Verbatim
     9                                                        
\end_layout

\begin_layout Verbatim
    10          command_list.push_back(
\end_layout

\begin_layout Verbatim
    11              new TemplCommandInOut<Tango::DevLong,Tango::DevLong>
\end_layout

\begin_layout Verbatim
    12                  ((const char *)"DevReadDirection",
\end_layout

\begin_layout Verbatim
    13                   static_cast<Tango::Lg_CmdMethPtr_Lg>
\end_layout

\begin_layout Verbatim
    14                          (&StepperMotor::dev_read_direction),
\end_layout

\begin_layout Verbatim
    15                   static_cast<Tango::StateMethPtr>
\end_layout

\begin_layout Verbatim
    16                          (&StepperMotor::direct_cmd_allowed))
\end_layout

\begin_layout Verbatim
    17                                );
\end_layout

\begin_layout Verbatim
    18  }
\end_layout

\begin_layout Verbatim
    19  
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
Line 4 : Creation of one instance of the DevReadPositionCmd class.
 The class is created with five arguments which are the command name, the
 command type code for its input and output parameters and two strings which
 are the command input and output parameters description.
 The pointer returned by the new C++ keyword is added to the vector of available
 command.
\end_layout

\begin_layout Standard
Line 10-14 : Creation of the object used for the DevReadDirection command.
 This command has one input and output parameter.
 Therefore the created object is an instance of the TemplCommandInOut class.
 This class is a C++ template class.
 The first template parameter is the command input parameter type, the second
 template parameter is the command output parameter type.
 The second TemplCommandInOut
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
TemplCommandInOut
\end_layout

\end_inset

 class constructor parameter (set at line 13) is a pointer to the method
 to be executed when the command is requested.
 A casting is necessary to store this pointer as a pointer to a method of
 the DeviceImpl class
\begin_inset Foot
status open

\begin_layout Plain Layout
The StepperMotor class inherits from the DeviceImpl class and therefore
 is a DeviceImpl
\end_layout

\end_inset

.
 The third TemplCommandInOut class constructor parameter (set at line 15)
 is a pointer to the method to be executed to check if the command is allowed.
 This is necessary only if the default behavior (command always allowed)
 does not fulfill the needs.
 A casting is necessary to store this pointer as a pointer to a method of
 the DeviceImpl
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DeviceImpl
\end_layout

\end_inset

 class.
 When a command is created using the template command method, the input
 and output parameters type are determined from the template C++ class parameter
s.
\end_layout

\begin_layout Subsubsection
The device_factory method
\end_layout

\begin_layout Standard
The 
\emph on
device_factory
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
device-factory
\end_layout

\end_inset


\emph default
 method has one input parameter.
 It is a pointer to Tango::DevVarStringArray data which is the device name
 list for this class and the instance of the device server process.
 This list is fetch from the Tango database.
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
     1  void StepperMotorClass::device_factory(const Tango::_DevVarStringArray
 *devlist_ptr)
\end_layout

\begin_layout Verbatim
     2  {
\end_layout

\begin_layout Verbatim
     3          
\end_layout

\begin_layout Verbatim
     4      for (long i = 0;i < devlist_ptr->length();i++)
\end_layout

\begin_layout Verbatim
     5      {
\end_layout

\begin_layout Verbatim
     6           DEBUG_STREAM << "Device name : " << (*devlist_ptr)[i] <<
 endl;
\end_layout

\begin_layout Verbatim
     7                                                  
\end_layout

\begin_layout Verbatim
     8           device_list.push_back(new StepperMotor(this,(*devlist_ptr)[i]));
       9  
\end_layout

\begin_layout Verbatim
    10           if (Tango::Util::_UseDb == true)
\end_layout

\begin_layout Verbatim
    11                export_device(device_list.back());
\end_layout

\begin_layout Verbatim
    12           else
\end_layout

\begin_layout Verbatim
    13                export_device(device_list.back(),(*devlist_ptr[i]));
\end_layout

\begin_layout Verbatim
    14      }
\end_layout

\begin_layout Verbatim
    15  }
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
Line 4 : A loop for each device
\end_layout

\begin_layout Standard
Line 8 : Create the device object using a StepperMotor class constructor
 which needs two arguments.
 These two arguments are a pointer to the StepperMotorClass instance and
 the device name.
 The pointer to the constructed object is then added to the device list
 vector
\end_layout

\begin_layout Standard
Line 10-13 : Export device to the outside world using the 
\emph on
export_device
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
export-device
\end_layout

\end_inset


\emph default
 method of the DeviceClass class.
\end_layout

\begin_layout Subsubsection
The attribute_factory
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
attribute-factory
\end_layout

\end_inset

 method
\end_layout

\begin_layout Standard
The rule of this method is to fulfill a vector of pointer to attributes.
 A reference to this vector is passed as argument to this method.
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
     1  void StepperMotorClass::attribute_factory(vector<Tango::Attr *>
 &att_list)
\end_layout

\begin_layout Verbatim
     2  {
\end_layout

\begin_layout Verbatim
     3      att_list.push_back(new PositionAttr());
\end_layout

\begin_layout Verbatim
     4  
\end_layout

\begin_layout Verbatim
     5      Tango::UserDefaultAttrProp def_prop;
\end_layout

\begin_layout Verbatim
     6      def_prop.set_label("Set the motor position");
\end_layout

\begin_layout Verbatim
     7      def_prop.set_format("scientific;setprecision(4)");
\end_layout

\begin_layout Verbatim
     8      Tango::Attr *at = new SetPositionAttr();
\end_layout

\begin_layout Verbatim
     9      at->set_default_properties(def_prop);
\end_layout

\begin_layout Verbatim
    10      att_list.push_back(at);
\end_layout

\begin_layout Verbatim
    11  
\end_layout

\begin_layout Verbatim
    12      att_list.push_back(new DirectcionAttr());
\end_layout

\begin_layout Verbatim
    13  }
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
Line 3 : Create the PositionAttr class and store the pointer to this object
 into the attribute pointer vector.
\end_layout

\begin_layout Standard
Line 5-7 : Create a Tango::UserDefaultAttrProp instance and set the label
 and format properties default values in this object
\end_layout

\begin_layout Standard
Line 8 : Create the SetPositionAttr attribute.
 
\end_layout

\begin_layout Standard
Line 9 : Set attribute user default value with the 
\emph on
set_default_properties()
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
set-default-properties
\end_layout

\end_inset


\emph default
 method of the Tango::Attr class.
\end_layout

\begin_layout Standard
Line 10 : Store the pointer to this object into the attribute pointer vector.
\end_layout

\begin_layout Standard
Line 12 : Create the DirectionAttr class and store the pointer to this object
 into the attribute pointer vector.
\end_layout

\begin_layout Standard
Please, note that in some rare case, it is necessary to add attribute to
 this list during the device server life cycle.
 This 
\emph on
attribute_factory()
\emph default
 method is called once during device server start-up.
 A method 
\emph on
add_attribute()
\emph default
 of the DeviceImpl class allows the user to add a new attribute to the attribute
 list outside of this 
\emph on
attribute_factory()
\emph default
 method.
 See 
\begin_inset CommandInset citation
LatexCommand cite
key "TANGO_ref_man"

\end_inset

 for more information on this method.
\end_layout

\begin_layout Subsection
The DevReadPositionCmd class
\end_layout

\begin_layout Subsubsection
The class declaration file
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
     1  #include <tango.h>
\end_layout

\begin_layout Verbatim
     2  
\end_layout

\begin_layout Verbatim
     3  namespace StepperMotor
\end_layout

\begin_layout Verbatim
     4  {
\end_layout

\begin_layout Verbatim
     5  
\end_layout

\begin_layout Verbatim
     6  class DevReadPositionCmd : public Tango::Command
\end_layout

\begin_layout Verbatim
     7  {
\end_layout

\begin_layout Verbatim
     8  public:
\end_layout

\begin_layout Verbatim
     9      DevReadPositionCmd(const char *,Tango::CmdArgType,
\end_layout

\begin_layout Verbatim
    10                             Tango::CmdArgType,
\end_layout

\begin_layout Verbatim
    11                             const char *,const char *);
\end_layout

\begin_layout Verbatim
    12      ~DevReadPositionCmd() {};
\end_layout

\begin_layout Verbatim
    13          
\end_layout

\begin_layout Verbatim
    14      virtual bool is_allowed (Tango::DeviceImpl *, const CORBA::Any
 &);
\end_layout

\begin_layout Verbatim
    15      virtual CORBA::Any *execute (Tango::DeviceImpl *, const CORBA::Any
 &);
\end_layout

\begin_layout Verbatim
    16  };
\end_layout

\begin_layout Verbatim
    17  
\end_layout

\begin_layout Verbatim
    18  } /* End of StepperMotor namespace */
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
Line 1 : Include the tango master include file
\end_layout

\begin_layout Standard
Line 3 : Open the 
\emph on
StepperMotor
\emph default
 namespace.
\end_layout

\begin_layout Standard
Line 6 : The DevReadPositionCmd class inherits from the Tango::Command class
\end_layout

\begin_layout Standard
Line 9 : The constructor
\end_layout

\begin_layout Standard
Line 12 : The destructor
\end_layout

\begin_layout Standard
Line 14 : The definition of the 
\emph on
is_allowed
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
is-allowed
\end_layout

\end_inset


\emph default
 method.
 This method is not necessary if the default behavior implemented by the
 default 
\emph on
is_allowed
\emph default
 method fulfill the requirements.
 The default behavior is to always allows the command execution (always
 return true).
\end_layout

\begin_layout Standard
Line 15: The definition of the 
\emph on
execute
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
execute
\end_layout

\end_inset


\emph default
 method
\end_layout

\begin_layout Subsubsection
The class constructor
\end_layout

\begin_layout Standard
The class constructor does nothing.
 It simply invoke the Command
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Command
\end_layout

\end_inset

 constructor by passing it its five arguments which are:
\end_layout

\begin_layout Enumerate
The command name
\end_layout

\begin_layout Enumerate
The command
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
command
\end_layout

\end_inset

 input type code
\end_layout

\begin_layout Enumerate
The command output type code
\end_layout

\begin_layout Enumerate
The command input parameter description
\end_layout

\begin_layout Enumerate
The command output parameter description
\end_layout

\begin_layout Standard
With this 5 parameters command class constructor, the command display level
 is not specified.
 Therefore it is set to its default value (OPERATOR).
 If the command does not have input or output parameter, it is not possible
 to use the Command class constructor defined with five parameters.
 In this case, the command constructor execute the Command class constructor
 with three elements (class name, input type, output type) and set the input
 or output parameter description fields with the 
\emph on
set_in_type_desc
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
set-in-type-desc
\end_layout

\end_inset


\emph default
 or 
\emph on
set_out_type_desc
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
set-out-type-desc
\end_layout

\end_inset


\emph default
 Command class methods.
 To set the command display level, it is possible to use a 6 parameters
 constructor or it is also possible to set it in the constructor code with
 the 
\emph on
set_disp_level
\emph default

\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
set-disp-level
\end_layout

\end_inset

 method.
 Many Command class constructors are defined.
 See 
\begin_inset CommandInset citation
LatexCommand cite
key "TANGO_ref_man"

\end_inset

for a complete list.
\end_layout

\begin_layout Subsubsection
The is_allowed
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
is-allowed
\end_layout

\end_inset

 method
\end_layout

\begin_layout Standard
In our example, the DevReadPosition command is allowed only if the device
 is in the ON state.
 This method receives two argument which are a pointer to the device object
 on which the command must be executed and a reference to the command input
 Any object.
 This method returns a boolean which must be set to true if the command
 is allowed.
 If this boolean is set to false, the DeviceClass
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DeviceClass
\end_layout

\end_inset

 
\emph on
command_handle
\emph default
r
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
command-handler
\end_layout

\end_inset

 method will automatically send an exception to the caller.
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
     1  bool DevReadPositionCmd::is_allowed(Tango::DeviceImpl *device,
\end_layout

\begin_layout Verbatim
     2                                      const CORBA::Any &in_any)
\end_layout

\begin_layout Verbatim
     3  {
\end_layout

\begin_layout Verbatim
     4       if (device->get_state() == Tango::ON)
\end_layout

\begin_layout Verbatim
     5            return true;
\end_layout

\begin_layout Verbatim
     6       else
\end_layout

\begin_layout Verbatim
     7            return false;
\end_layout

\begin_layout Verbatim
     8  }
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
Line 4 : Call the 
\emph on
get_state
\emph default
 method of the DeviceImpl class which simply returns the device state
\end_layout

\begin_layout Standard
Line 5 : Authorize command if the device state is ON
\end_layout

\begin_layout Standard
Line 7 : Refuse command execution in all other cases.
 
\end_layout

\begin_layout Subsubsection
The execute
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
execute
\end_layout

\end_inset

 method
\end_layout

\begin_layout Standard
This method receives two arguments which are a pointer to the device object
 on which the command must be executed and a reference to the command input
 Any object.
 This method returns a pointer to an any object which must be initialized
 with the data to be returned to the caller.
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
     1  CORBA::Any *DevReadPositionCmd::execute(
\end_layout

\begin_layout Verbatim
     2                          Tango::DeviceImpl *device,
\end_layout

\begin_layout Verbatim
     3                          const CORBA::Any &in_any)
\end_layout

\begin_layout Verbatim
     4  {       
\end_layout

\begin_layout Verbatim
     5       INFO_STREAM << "DevReadPositionCmd::execute(): arrived" <<
 endl;
\end_layout

\begin_layout Verbatim
     6       Tango::DevLong motor;
\end_layout

\begin_layout Verbatim
     7  
\end_layout

\begin_layout Verbatim
     8       extract(in_any,motor);
\end_layout

\begin_layout Verbatim
     9       return insert(
\end_layout

\begin_layout Verbatim
    10          (static_cast<StepperMotor *>(device))->dev_read_position(motor))
;
\end_layout

\begin_layout Verbatim
    11  }
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
Line 8 : Extract incoming data from the input any object using a Command
 class 
\emph on
extract
\emph default
 helper method.
 If the type of the data in the Any object is not a Tango::DevLong, the
 
\emph on
extract
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
extract
\end_layout

\end_inset


\emph default
 method will throw an exception to the client.
\end_layout

\begin_layout Standard
Line 9 : Call the stepper motor object method which execute the DevReadPosition
 command and insert the returned value into an allocated Any object.
 The Any object allocation is done by the 
\emph on
insert
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
insert
\end_layout

\end_inset


\emph default
 method which return a pointer to this Any.
\end_layout

\begin_layout Subsection
The PositionAttr class
\end_layout

\begin_layout Subsubsection
The class declaration file
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
     1  #include <tango.h>
\end_layout

\begin_layout Verbatim
     2  #include <steppermotor.h>
\end_layout

\begin_layout Verbatim
     3  
\end_layout

\begin_layout Verbatim
     4  namespace StepperMotor
\end_layout

\begin_layout Verbatim
     5  {
\end_layout

\begin_layout Verbatim
     6  
\end_layout

\begin_layout Verbatim
     7  
\end_layout

\begin_layout Verbatim
     8  class PositionAttr: public Tango::Attr
\end_layout

\begin_layout Verbatim
     9  {
\end_layout

\begin_layout Verbatim
    10  public:
\end_layout

\begin_layout Verbatim
    11      PositionAttr():Attr("Position",
\end_layout

\begin_layout Verbatim
    12                          Tango::DEV_LONG,
\end_layout

\begin_layout Verbatim
    13                          Tango::READ_WITH_WRITE,
\end_layout

\begin_layout Verbatim
    14                          "SetPosition") {};
\end_layout

\begin_layout Verbatim
    15      ~PositionAttr() {};
\end_layout

\begin_layout Verbatim
    16          
\end_layout

\begin_layout Verbatim
    17      virtual void read(Tango::DeviceImpl *dev,Tango::Attribute &att)
\end_layout

\begin_layout Verbatim
    18      {(static_cast<StepperMotor *>(dev))->read_Position(att);}
\end_layout

\begin_layout Verbatim
    19      virtual bool is_allowed(Tango::DeviceImpl *dev,Tango::AttReqType
 ty)
\end_layout

\begin_layout Verbatim
    20      {return (static_cast<StepperMotor *>(dev))->is_Position_allowed(ty);
}
\end_layout

\begin_layout Verbatim
    21  };
\end_layout

\begin_layout Verbatim
    22  
\end_layout

\begin_layout Verbatim
    23  } /* End of StepperMotor namespace */
\end_layout

\begin_layout Verbatim
    24  
\end_layout

\begin_layout Verbatim
    25  #endif // _STEPPERMOTORCLASS_H
\end_layout

\begin_layout Standard

\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
Line 1-2 : Include the tango master include file and the steppermotor class
 definition include file
\end_layout

\begin_layout Standard
Line 4 : Open the 
\emph on
StepperMotor
\emph default
 namespace.
\end_layout

\begin_layout Standard
Line 8 : The PosiitionAttr class inherits from the Tango::Attr class
\end_layout

\begin_layout Standard
Line 11-14 : The constructor with 4 arguments
\end_layout

\begin_layout Standard
Line 15 : The destructor
\end_layout

\begin_layout Standard
Line 17 : The definition of the 
\emph on
read
\emph default
 method.
 This method forwards the call to a StepperMotor class method called 
\emph on
read_Position()
\end_layout

\begin_layout Standard
Line 19 : The definition of the 
\emph on
is_allowed
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
is-allowed
\end_layout

\end_inset


\emph default
 method.
 This method is not necessary if the default behaviour implemented by the
 default 
\emph on
is_allowed
\emph default
 method fulfills the requirements.
 The default behaviour is to always allows the attribute reading (always
 return true).
 This method forwards the call to a StepperMotor class method called 
\emph on
is_Position_allowed()
\end_layout

\begin_layout Subsubsection
The class constructor
\end_layout

\begin_layout Standard
The class constructor does nothing.
 It simply invoke the Attr
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Attr
\end_layout

\end_inset

 constructor by passing it its four arguments which are:
\end_layout

\begin_layout Enumerate
The attribute name
\end_layout

\begin_layout Enumerate
The attribute data type code
\end_layout

\begin_layout Enumerate
The attribute writable type code
\end_layout

\begin_layout Enumerate
The name of the associated write attribute
\end_layout

\begin_layout Standard
With this 4 parameters Attr class constructor, the attribute display level
 is not specified.
 Therefore it is set to its default value (OPERATOR).
 To set the attribute display level, it is possible to use in the constructor
 code the 
\emph on
set_disp_level
\emph default

\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
set-disp-level
\end_layout

\end_inset

 method.
 Many Attr class constructors are defined.
 See 
\begin_inset CommandInset citation
LatexCommand cite
key "TANGO_ref_man"

\end_inset

for a complete list.
\end_layout

\begin_layout Standard
This Position attribute is a scalar attribute.
 For spectrum attribute, instead of inheriting from the Attr class, the
 class must inherits from the SpectrumAttr
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
SpectrumAttr
\end_layout

\end_inset

 class.
 Many SpectrumAttr class constructors are defined.
 See 
\begin_inset CommandInset citation
LatexCommand cite
key "TANGO_ref_man"

\end_inset

for a complete list.
\end_layout

\begin_layout Standard
For Image attribute, instead of inheriting from the Attr class, the class
 must inherits from the ImageAttr class.
 Many ImageAttr
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
ImageAttr
\end_layout

\end_inset

 class constructors are defined.
 See 
\begin_inset CommandInset citation
LatexCommand cite
key "TANGO_ref_man"

\end_inset

for a complete list.
 
\end_layout

\begin_layout Subsubsection
The is_allowed
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
is-allowed
\end_layout

\end_inset

 method
\end_layout

\begin_layout Standard
This method receives two argument which are a pointer to the device object
 to which the attribute belongs to and the type of request (read or write).
 In the PositionAttr class, this method simply "forwards" the request to
 a method of the StepperMotor class called 
\emph on
is_Position_allowed()
\emph default
 passing the request type to this method.
 This method returns a boolean which must be set to true if the attribute
 is allowed.
 If this boolean is set to false, the DeviceImpl
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DeviceImpl
\end_layout

\end_inset

 read_attribute
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
read-attribute
\end_layout

\end_inset

 method will automatically send an exception to the caller.
\end_layout

\begin_layout Subsubsection
The read
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
execute
\end_layout

\end_inset

 method
\end_layout

\begin_layout Standard
This method receives two arguments which are a pointer to the device object
 to which the attribute belongs to and a reference to the corresponding
 attribute object.
 This method "forwards" the request to a StepperMotor class called 
\emph on
read_Position()
\emph default
 passing it the reference on the attribute object.
\end_layout

\begin_layout Standard

\end_layout

\begin_layout Subsection
The StepperMotor class
\end_layout

\begin_layout Subsubsection
The class declaration file
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
1 #include <tango.h>
\end_layout

\begin_layout Verbatim
2 
\end_layout

\begin_layout Verbatim
3 #define AGSM_MAX_MOTORS 8 // maximum number of motors per device
\end_layout

\begin_layout Verbatim
4 
\end_layout

\begin_layout Verbatim
5 namespace StepperMotor
\end_layout

\begin_layout Verbatim
6 {
\end_layout

\begin_layout Verbatim
7 
\end_layout

\begin_layout Verbatim
8 class StepperMotor: public TANGO_BASE_CLASS
\end_layout

\begin_layout Verbatim
9 {
\end_layout

\begin_layout Verbatim
10 public :
\end_layout

\begin_layout Verbatim
11    StepperMotor(Tango::DeviceClass *,string &);
\end_layout

\begin_layout Verbatim
12    StepperMotor(Tango::DeviceClass *,const char *);
\end_layout

\begin_layout Verbatim
13    StepperMotor(Tango::DeviceClass *,const char *,const char *);
\end_layout

\begin_layout Verbatim
14    ~StepperMotor() {};
\end_layout

\begin_layout Verbatim
15 
\end_layout

\begin_layout Verbatim
16    DevLong dev_read_position(DevLong);
\end_layout

\begin_layout Verbatim
17    DevLong dev_read_direction(DevLong);
\end_layout

\begin_layout Verbatim
18    bool direct_cmd_allowed(const CORBA::Any &);
\end_layout

\begin_layout Verbatim
19 
\end_layout

\begin_layout Verbatim
20    virtual Tango::DevState dev_state();
\end_layout

\begin_layout Verbatim
21    virtual Tango::ConstDevString dev_status();
\end_layout

\begin_layout Verbatim
22 
\end_layout

\begin_layout Verbatim
23    virtual void always_executed_hook();
\end_layout

\begin_layout Verbatim
24 
\end_layout

\begin_layout Verbatim
25    virtual void read_attr_hardware(vector<long> &attr_list);
\end_layout

\begin_layout Verbatim
26    virtual void write_attr_hardware(vector<long> &attr_list);
\end_layout

\begin_layout Verbatim
27 
\end_layout

\begin_layout Verbatim
28    void read_position(Tango::Attribute &);
\end_layout

\begin_layout Verbatim
29    bool is_Position_allowed(Tango::AttReqType req);
\end_layout

\begin_layout Verbatim
30    void write_SetPosition(Tango::WAttribute &);
\end_layout

\begin_layout Verbatim
31    void read_Direction(Tango::Attribute &);
\end_layout

\begin_layout Verbatim
32 
\end_layout

\begin_layout Verbatim
33    virtual void init_device();
\end_layout

\begin_layout Verbatim
34    virtual void delete_device();
\end_layout

\begin_layout Verbatim
35 
\end_layout

\begin_layout Verbatim
36    void get_device_properties();
\end_layout

\begin_layout Verbatim
37 
\end_layout

\begin_layout Verbatim
38 protected : 
\end_layout

\begin_layout Verbatim
39    long axis[AGSM_MAX_MOTORS];
\end_layout

\begin_layout Verbatim
40    DevLong position[AGSM_MAX_MOTORS];
\end_layout

\begin_layout Verbatim
41    DevLong direction[AGSM_MAX_MOTORS];
\end_layout

\begin_layout Verbatim
42    long state[AGSM_MAX_MOTORS];
\end_layout

\begin_layout Verbatim
43 
\end_layout

\begin_layout Verbatim
44    Tango::DevLong *attr_Position_read;
\end_layout

\begin_layout Verbatim
45    Tango::DevLong *attr_Direction_read;
\end_layout

\begin_layout Verbatim
46    Tango::DevLong attr_SetPosition_write;
\end_layout

\begin_layout Verbatim
47 
\end_layout

\begin_layout Verbatim
48    Tango::DevLong min;
\end_layout

\begin_layout Verbatim
49    Tango::DevLong max;
\end_layout

\begin_layout Verbatim
50 
\end_layout

\begin_layout Verbatim
51    Tango::DevLong *ptr;
\end_layout

\begin_layout Verbatim
52 };
\end_layout

\begin_layout Verbatim
53 
\end_layout

\begin_layout Verbatim
54 } /* End of StepperMotor namespace */
\end_layout

\begin_layout Standard

\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
Line 1 : Include the Tango master include file
\end_layout

\begin_layout Standard
Line 5 : Open the 
\emph on
StepperMotor
\emph default
 namespace.
\end_layout

\begin_layout Standard
Line 8 : The StepperMotor class inherits from a Tango base class
\end_layout

\begin_layout Standard
Line 11-13 : Three different object constructors
\end_layout

\begin_layout Standard
Line 14 : The destructor which calls the 
\emph on
delete_device()
\emph default
 method
\end_layout

\begin_layout Standard
Line 16 : The method to be called for the execution of the DevReadPosition
 command.
 This method must be declared as virtual if it is needed to redefine it
 in a class inheriting from StepperMotor.
 See chapter 
\begin_inset CommandInset ref
LatexCommand ref
reference "Inheriting"

\end_inset

 for more details about inheriting.
\end_layout

\begin_layout Standard
Line 17 : The method to be called for the execution of the DevReadDirection
 command
\end_layout

\begin_layout Standard
Line 18 : The method called to check if the execution of the DevReadDirection
 command is allowed.
 This method is necessary because the DevReadDirection command is created
 using the template command method and the default behavior is not acceptable
\end_layout

\begin_layout Standard
Line 20 : Redefinition of the 
\emph on
dev_state
\emph default

\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
dev-state
\end_layout

\end_inset

.
 This method is used by the State
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
State
\end_layout

\end_inset

 command
\end_layout

\begin_layout Standard
Line 21 : Redefinition of the 
\emph on
dev_status
\emph default

\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
dev-status
\end_layout

\end_inset

.
 This method is used by the Status
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Status
\end_layout

\end_inset

 command
\end_layout

\begin_layout Standard
Line 23 : Redefinition of the 
\emph on
always_executed_hook
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
always-executed-hook
\end_layout

\end_inset


\emph default
 method.
 This method is the place to code mandatory action which must be executed
 prior to any command.
\end_layout

\begin_layout Standard
Line 25-31 : Attribute related methods
\end_layout

\begin_layout Standard
Line 32 : Definition of the 
\emph on
init_device
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
init-device
\end_layout

\end_inset


\emph default
 method.
\end_layout

\begin_layout Standard
Line 33 : Definition of the 
\emph on
delete_device
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
delete-device
\end_layout

\end_inset


\emph default
 method
\end_layout

\begin_layout Standard
Line 35 : Definition of the 
\emph on
get_device_properties
\emph default
 method
\end_layout

\begin_layout Standard
Line 38-50 : Data members.
 
\end_layout

\begin_layout Standard
Line 43-44 : Pointers to data for readable attributes Position and Direction
\end_layout

\begin_layout Standard
Line 45 : Data for the SetPosition attribute
\end_layout

\begin_layout Standard
Line 47-48 : Data members for the two device properties
\end_layout

\begin_layout Subsubsection
The constructors
\end_layout

\begin_layout Standard
Three constructors are defined here.
 It is not mandatory to defined three constructors.
 But at least one is mandatory.
 The three constructors take a pointer to the StepperMotorClass instance
 as first parameter
\begin_inset Foot
status open

\begin_layout Plain Layout
The StepperMotorClass inherits from the DeviceClass and therefore is a DeviceCla
ss
\end_layout

\end_inset

.
 The second parameter is the device name as a C++ string or as a classical
 pointer to char array.
 The third parameter necessary only for the third form of constructor is
 the device description string passed as a classical pointer to a char array.
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
1  #include <tango.h>
\end_layout

\begin_layout Verbatim
2  #include <steppermotor.h>
\end_layout

\begin_layout Verbatim
3 
\end_layout

\begin_layout Verbatim
4  namespace StepperMotor
\end_layout

\begin_layout Verbatim
5  {
\end_layout

\begin_layout Verbatim
6 
\end_layout

\begin_layout Verbatim
7  StepperMotor::StepperMotor(Tango::DeviceClass *cl,string &s)
\end_layout

\begin_layout Verbatim
8  :TANGO_BASE_CLASS(cl,s.c_str())
\end_layout

\begin_layout Verbatim
9  {
\end_layout

\begin_layout Verbatim
10    init_device();
\end_layout

\begin_layout Verbatim
11 }
\end_layout

\begin_layout Verbatim
12 
\end_layout

\begin_layout Verbatim
13 StepperMotor::StepperMotor(Tango::DeviceClass *cl,const char *s)
\end_layout

\begin_layout Verbatim
14 :TANGO_BASE_CLASS(cl,s)
\end_layout

\begin_layout Verbatim
15 {
\end_layout

\begin_layout Verbatim
16    init_device();
\end_layout

\begin_layout Verbatim
17 }
\end_layout

\begin_layout Verbatim
18 
\end_layout

\begin_layout Verbatim
19 StepperMotor::StepperMotor(Tango::DeviceClass *cl,const char *s,const
 char *d)
\end_layout

\begin_layout Verbatim
20 :TANGO_BASE_CLASS(cl,s,d)
\end_layout

\begin_layout Verbatim
21 {
\end_layout

\begin_layout Verbatim
22    init_device();
\end_layout

\begin_layout Verbatim
23 }
\end_layout

\begin_layout Verbatim
24 
\end_layout

\begin_layout Verbatim
25 void StepperMotor::init_device()
\end_layout

\begin_layout Verbatim
26 {
\end_layout

\begin_layout Verbatim
27    cout << "StepperMotor::StepperMotor() create " << device_name << endl;
\end_layout

\begin_layout Verbatim
28 
\end_layout

\begin_layout Verbatim
29    long i;
\end_layout

\begin_layout Verbatim
30 
\end_layout

\begin_layout Verbatim
31    for (i=0; i< AGSM_MAX_MOTORS; i++)
\end_layout

\begin_layout Verbatim
32    {
\end_layout

\begin_layout Verbatim
33       axis[i] = 0;
\end_layout

\begin_layout Verbatim
34       position[i] = 0;
\end_layout

\begin_layout Verbatim
35       direction[i] = 0;
\end_layout

\begin_layout Verbatim
36    }
\end_layout

\begin_layout Verbatim
37 
\end_layout

\begin_layout Verbatim
38    ptr = new Tango::DevLong[10];
\end_layout

\begin_layout Verbatim
39 
\end_layout

\begin_layout Verbatim
40    get_device_properties();
\end_layout

\begin_layout Verbatim
41 }
\end_layout

\begin_layout Verbatim
42 
\end_layout

\begin_layout Verbatim
43 void StepperMotor::delete_device()
\end_layout

\begin_layout Verbatim
44 {
\end_layout

\begin_layout Verbatim
45    delete [] ptr;
\end_layout

\begin_layout Verbatim
46 }
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
Line 1-2 : Include the Tango master include file (tango.h) and the StepperMotor
 class definition file (steppermotor.h)
\end_layout

\begin_layout Standard
Line 4 : Open the 
\emph on
StepperMotor
\emph default
 namespace
\end_layout

\begin_layout Standard
Line 7-11 : The first form of the class constructor.
 It execute the Tango base class constructor with the two parameters.
 Note that the device name passed to this constructor as a C++ string is
 passed to the Tango::DeviceImpl
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DeviceImpl
\end_layout

\end_inset

 constructor as a classical C string.
 Then the 
\emph on
init_device
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
init-device
\end_layout

\end_inset


\emph default
 method is executed.
\end_layout

\begin_layout Standard
Line 13-17 : The second form of the class constructor.
 It execute the Tango base class constructor with its two parameters.
 Then the 
\emph on
init_device
\emph default
 method is executed.
\end_layout

\begin_layout Standard
Line 19-23: The third form of constructor.
 Again, it execute the Tango base class constructor with its three parameters.
 Then the 
\emph on
init_device
\emph default
 method is executed.
\end_layout

\begin_layout Standard
Line 25-41 : The 
\emph on
init_device
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
init-device
\end_layout

\end_inset


\emph default
 method.
 All the device data initialization is done in this method.
 The device properties are also retrieved from database with a call to the
 
\emph on
get_device_properties
\emph default
 method at line 40.
 The device data member called 
\emph on
ptr
\emph default
 is initialized with allocated memory at line 38.
 It is not needed to have this pointer, it has been added only for educational
 purpose.
\end_layout

\begin_layout Standard
Line 43-46 : The 
\emph on
delete_device
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
delete-device
\end_layout

\end_inset


\emph default
 method.
 The rule of this method is to free memory allocated in the 
\emph on
init_device
\emph default
 method.
 In our case , only the device data member 
\emph on
ptr
\emph default
 is allocated in the 
\emph on
init_device
\emph default
 method.
 Therefore, its memory is freed at line 45.
 This method is called by the automatically added Init command before it
 calls the 
\emph on
init_device
\emph default
 method.
 It is also called by the device destructor.
\end_layout

\begin_layout Subsubsection
The methods used for the DevReadDirection command
\end_layout

\begin_layout Standard
The DevReadDirection command is created using the template command method.
 Therefore, there is no specific class needed for this command but only
 one object of the TemplCommandInOut class.
 This command needs two methods which are the 
\emph on
dev_read_direction
\emph default
 method and the 
\emph on
direct_cmd_allowed
\emph default
 method.
 The 
\emph on
direct_cmd_allowed
\emph default
 method defines here implements exactly the same behavior than the default
 one.
 This method has been used only for pedagogic issue.
 The 
\emph on
dev_read_direction
\emph default
 method will be executed by the 
\emph on
execute
\emph default
 method of the TemplCommandInOut
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
TemplCommandInOut
\end_layout

\end_inset

 class.
 The 
\emph on
direct_cmd_allowed
\emph default
 method will be executed by the 
\emph on
is_allowed
\emph default
 method of the TemplCommandInOut class.
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
     1  DevLong StepperMotor::dev_read_direction(DevLong axis)
\end_layout

\begin_layout Verbatim
     2  {
\end_layout

\begin_layout Verbatim
     3     if (axis < 0 || axis > AGSM_MAX_MOTORS)
\end_layout

\begin_layout Verbatim
     4     {
\end_layout

\begin_layout Verbatim
     5         WARNING_STREAM << "Steppermotor::dev_read_direction(): axis
 out of range !";
\end_layout

\begin_layout Verbatim
     6         WARNING_STREAM << endl;
\end_layout

\begin_layout Verbatim
     7         TangoSys_OMemStream o;
\end_layout

\begin_layout Verbatim
     8                  
\end_layout

\begin_layout Verbatim
     9         o << "Axis number " << axis << " out of range" << ends;
\end_layout

\begin_layout Verbatim
    10         throw_exception("StepperMotor_OutOfRange",
\end_layout

\begin_layout Verbatim
    11                         o.str(),
\end_layout

\begin_layout Verbatim
    12                         "StepperMotor::dev_read_direction");
\end_layout

\begin_layout Verbatim
    13      }
\end_layout

\begin_layout Verbatim
    14  
\end_layout

\begin_layout Verbatim
    15      return direction[axis];
\end_layout

\begin_layout Verbatim
    16  }
\end_layout

\begin_layout Verbatim
    17  
\end_layout

\begin_layout Verbatim
    18  
\end_layout

\begin_layout Verbatim
    19  bool StepperMotor::direct_cmd_allowed(const CORBA::Any &in_data)
\end_layout

\begin_layout Verbatim
    20  {
\end_layout

\begin_layout Verbatim
    21      INFO_STREAM << "In direct_cmd_allowed() method" << endl;
\end_layout

\begin_layout Verbatim
    22          
\end_layout

\begin_layout Verbatim
    23      return true;
\end_layout

\begin_layout Verbatim
    24  }
\end_layout

\begin_layout Verbatim
    25  
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
Line 1-16 : The 
\emph on
dev_read_direction
\emph default
 method
\end_layout

\begin_layout Standard
Line 5-12 : Throw exception to client if the received axis number is out
 of range
\end_layout

\begin_layout Standard
Line 7 : A TangoSys_OMemStream is used as stream.
 The TangoSys_OMemStream has been defined in improve portability across
 platform.
 For Unix like operating system, it is a ostrtream type.
 For operating system with a full implementation of the standard library,
 it is a ostringstream type.
\end_layout

\begin_layout Standard
Line 19-24 : The 
\emph on
direct_cmd_allowed
\emph default
 method.
 The command input data is passed to this method in case of it is needed
 to take the decision.
 This data is still packed into the CORBA Any object.
\end_layout

\begin_layout Subsubsection
The methods used for the Position attribute
\end_layout

\begin_layout Standard
To enable reading of attributes
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
attribute
\end_layout

\end_inset

, the StepperMotor class must re-define two or three methods called 
\emph on
read_attr_hardware
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
read-attr-hardware
\end_layout

\end_inset

(), read_<Attribute_name>()
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
read-Position
\end_layout

\end_inset


\emph default
 and if necessary a method called 
\begin_inset Newline newline
\end_inset


\emph on
is_<Attribute_name>_allowed().

\emph default
 The aim of the first one is to read the hardware.
 It will be called only once at the beginning of each read_attribute CORBA
 call.
 The second method aim is to build the exact data for the wanted attribute
 and to store this value into the Attribute object.
 Special care has been taken in order to minimize the number of data copy
 and allocation.
 The data passed to the Attribute object as attribute value is passed using
 pointers.
 It must be allocated by the method
\begin_inset Foot
status open

\begin_layout Plain Layout
It can also be data declared as object data members or memory declared as
 static
\end_layout

\end_inset

 and the Attribute
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Attribute
\end_layout

\end_inset

 object will not free this memory.
 Data members called attr_<Attribute_name>_read are foreseen for this usage.
 The 
\emph on
read_attr_hardware()
\emph default
 method receives a vector of long which are indexes into the main attributes
 vector of the attributes to be read.
 The 
\emph on
read_Position()
\emph default
 method receives a reference to the Attribute object.
 The third method (
\emph on
is_Position_allowed()
\emph default
) aim is to allow or dis-allow, the attribute reading.
 In some cases, some attributes can be read only if some conditions are
 met.
 If this method returns true, the 
\emph on
read_<Attribute_name>()
\emph default
 method will be called.
 Otherwise, an error will be generated for the attribute.
 This method receives one argument which is an emumeration describing the
 attribute request type (read or write).
 In our example, the reading of the Position attribute is allowed only if
 the device state is ON.
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
     1  void StepperMotor::read_attr_hardware(vector<long> &attr_list)
\end_layout

\begin_layout Verbatim
     2  {
\end_layout

\begin_layout Verbatim
     3     INFO_STREAM << "In read_attr_hardware for " << attr_list.size();
\end_layout

\begin_layout Verbatim
     4     INFO_STREAM << " attribute(s)" << endl;
\end_layout

\begin_layout Verbatim
     5  
\end_layout

\begin_layout Verbatim
     6     for (long i = 0;i < attr_list.size();i++)
\end_layout

\begin_layout Verbatim
     7     {
\end_layout

\begin_layout Verbatim
     8        string attr_name;
\end_layout

\begin_layout Verbatim
     9        attr_name = dev_attr->get_attr_by_ind(attr_list[i]).get_name();
\end_layout

\begin_layout Verbatim
    10  
\end_layout

\begin_layout Verbatim
    11        if (attr_name == "Position")
\end_layout

\begin_layout Verbatim
    12        {
\end_layout

\begin_layout Verbatim
    13           attr_Position_read = &(position[0]);
\end_layout

\begin_layout Verbatim
    14        }
\end_layout

\begin_layout Verbatim
    15        else if (attr_name == "Direction")
\end_layout

\begin_layout Verbatim
    16        {
\end_layout

\begin_layout Verbatim
    17           attr_Direction_read = &(direction[0]);
\end_layout

\begin_layout Verbatim
    18        }
\end_layout

\begin_layout Verbatim
    19     }
\end_layout

\begin_layout Verbatim
    20  }
\end_layout

\begin_layout Verbatim
    21  
\end_layout

\begin_layout Verbatim
    22  void read_Position(Tango::Attribute &att)
\end_layout

\begin_layout Verbatim
    23  {
\end_layout

\begin_layout Verbatim
    24     att.set_value(attr_Position_read);
\end_layout

\begin_layout Verbatim
    25  }
\end_layout

\begin_layout Verbatim
    26  
\end_layout

\begin_layout Verbatim
    27  bool is_Position_allowed(Tango::AttReqType req)
\end_layout

\begin_layout Verbatim
    28  {
\end_layout

\begin_layout Verbatim
    29     if (req == Tango::WRITE_REQ)
\end_layout

\begin_layout Verbatim
    30        return false;
\end_layout

\begin_layout Verbatim
    31     else
\end_layout

\begin_layout Verbatim
    32     {
\end_layout

\begin_layout Verbatim
    33        if (get_state() == Tango::ON)
\end_layout

\begin_layout Verbatim
    34           return true;
\end_layout

\begin_layout Verbatim
    35        else
\end_layout

\begin_layout Verbatim
    36           return false;
\end_layout

\begin_layout Verbatim
    37     }
\end_layout

\begin_layout Verbatim
    38  }
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
Line 6 : A loop on each attribute to be read
\end_layout

\begin_layout Standard
Line 9 : Get attribute name
\end_layout

\begin_layout Standard
Line 11 : Test on attribute name
\end_layout

\begin_layout Standard
Line 13 : Read hardware (pretty simple in our case)
\end_layout

\begin_layout Standard
Line 24 : Set attribute value in Attribute object using the 
\emph on
set_value()
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
set-value
\end_layout

\end_inset


\emph default
 method.
 This method will also initializes the attribute quality factor to Tango::ATTR_V
ALID
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
ATTR-VALID
\end_layout

\end_inset

 if no alarm level are defined and will set the attribute returned date.
 It is also possible to use a method called 
\emph on
set_value_date_quality()
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
set-value-date-quality
\end_layout

\end_inset


\emph default
 which allows the user to set the attribute quality factor as well as the
 attribute date.
\end_layout

\begin_layout Standard
Line 33 : Test on device state
\end_layout

\begin_layout Subsubsection
The methods used for the SetPosition attribute
\end_layout

\begin_layout Standard
To enable writing of attributes
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
attribute
\end_layout

\end_inset

, the StepperMotor class must re-define one or two methods called 
\emph on
write_<Attribute_name>()
\emph default
 and if necessary a method called 
\emph on
is_<Attribute_name>_allowed().

\emph default
 The aim of the first one is to write the hardware.
 The 
\emph on
write_Position()
\emph default
 method receives a reference to the WAttribute object.
 The value to write is in this WAttribute object.
 The third method (
\emph on
is_Position_allowed()
\emph default
) aim is to allow or dis-allow, the attribute writing.
 In some cases, some attributes can be write only if some conditions are
 met.
 If this method returns true, the 
\emph on
write_<Attribute_name>()
\emph default
 method will be called.
 Otherwise, an error will be generated for the attribute.
 This method receives one argument which is an emumeration describing the
 attribute request type (read or write).
 For read/write attribute, this method is the same for reading and writing.
 The input argument value makes the difference.
\end_layout

\begin_layout Standard
For our example, it is always possible to write the SetPosition attribute.
 Therefore, the StepperMotor class only defines a 
\emph on
write_SetPosition()
\emph default
 method.
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
1 void StepperMotor::write_SetPosition(Tango::WAttribute &att)
\end_layout

\begin_layout Verbatim
2 {
\end_layout

\begin_layout Verbatim
3    att.get_write_value(sttr_SetPosition_write);
\end_layout

\begin_layout Verbatim
4 
\end_layout

\begin_layout Verbatim
5    DEBUG_STREAM << "Attribute SetPosition value = ";
\end_layout

\begin_layout Verbatim
6    DEBUG_STREAM << attr_SetPosition_write << endl;
\end_layout

\begin_layout Verbatim
7 
\end_layout

\begin_layout Verbatim
8    position[0] = attr_SetPosition_write;
\end_layout

\begin_layout Verbatim
9 }
\end_layout

\begin_layout Verbatim
10 
\end_layout

\begin_layout Verbatim
11 void StepperMotor::write_attr_hardware(vector<long> &attr_list)
\end_layout

\begin_layout Verbatim
12 {
\end_layout

\begin_layout Verbatim
13 
\end_layout

\begin_layout Verbatim
14 }
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
Line 3 : Retrieve new attribute value
\end_layout

\begin_layout Standard
Line 5-6 : Send some messages using Tango Logging system
\end_layout

\begin_layout Standard
Line 8 : Set the hardware (pretty simple in our case)
\end_layout

\begin_layout Standard
Line 11 - 14: The write_attr_hardware() method.
 
\begin_inset Newline newline
\end_inset


\end_layout

\begin_layout Standard
In our case, we don't have to do anything in the 
\emph on
write_attr_hardware()
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
write-attr-hardware
\end_layout

\end_inset


\emph default
 method.
 It is coded here just for educational purpose.
 When its not needed, this method has a default implementation in the Tango
 base class and it is not mandatory to declare and defin it in your own
 Tango class
\end_layout

\begin_layout Subsubsection
Retrieving device properties
\end_layout

\begin_layout Standard
Retrieving properties
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
properties
\end_layout

\end_inset

 is fairly simple with the use of the database object.
 Each Tango device is an aggregate with a DbDevice object (see figure 
\begin_inset CommandInset ref
LatexCommand ref
reference "Dvice pattern figure"

\end_inset

).
 This has been grouped in a method called 
\emph on
get_device_properties
\emph default
().
 The classes and methods of the Dbxxx objects are described in the Tango
 API documentation.
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
     1  void DocDs::get_device_property()
\end_layout

\begin_layout Verbatim
     2  {
\end_layout

\begin_layout Verbatim
     3     Tango::DbData   data;
\end_layout

\begin_layout Verbatim
     4     data.push_back(DbDatum("Max"));
\end_layout

\begin_layout Verbatim
     5     data.push_back(DbDatum("Min"));
\end_layout

\begin_layout Verbatim
     6  
\end_layout

\begin_layout Verbatim
     7     get_db_device()->get_property(data);
\end_layout

\begin_layout Verbatim
     8  
\end_layout

\begin_layout Verbatim
     9     if (data[0].is_empty()==false)
\end_layout

\begin_layout Verbatim
    10        data[0]  >>  max;
\end_layout

\begin_layout Verbatim
    11     if (data[1].is_empty()==false)
\end_layout

\begin_layout Verbatim
    12        data[1]  >>  min;
\end_layout

\begin_layout Verbatim
    13  }
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
Line 4-5 : Two DbDatum (one per property) are stored into a DbData object
\end_layout

\begin_layout Standard
Line 7 : Call the database to retrieve properties value
\end_layout

\begin_layout Standard
Line 9-10 : If the Max property is defined in the database, extract its
 value from the DbDatum object and store it in a device data member
\end_layout

\begin_layout Standard
Line 11-12 : If the Min property is defined in the database, extract its
 value from the DbDatum object and store it in a device data member
\end_layout

\begin_layout Subsubsection
The remaining methods
\end_layout

\begin_layout Standard
The remaining methods are the 
\emph on
dev_state, dev_status, always_executed_hook
\emph default
, 
\emph on
dev_read_position
\emph default
 and 
\emph on
read_Direction()
\emph default
 methods.
 The 
\emph on
dev_state
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
dev-state
\end_layout

\end_inset


\emph default
 method parameters are fixed.
 It does not receive any input parameter and must return a Tango_DevState
 data type.
 The 
\emph on
dev_status
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
dev-status
\end_layout

\end_inset


\emph default
 parameters are also fixed.
 It does not receive any input parameter and must return a Tango string.
 The 
\emph on
always_executed_hook
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
always-executed-hook
\end_layout

\end_inset


\emph default
 receives nothing and return nothing.
 The 
\emph on
dev_read_position
\emph default
 method input parameter is the motor number as a long and the returned parameter
 is the motor position also as a long data type.
 The 
\emph on
read_Direction()
\emph default
 method is the method for reading the Direction attribute.
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
1  DevLong StepperMotor::dev_read_position(DevLong axis)
\end_layout

\begin_layout Verbatim
     2  {
\end_layout

\begin_layout Verbatim
     3  
\end_layout

\begin_layout Verbatim
     4     if (axis < 0 || axis > AGSM_MAX_MOTORS)
\end_layout

\begin_layout Verbatim
     5     {
\end_layout

\begin_layout Verbatim
     6          WARNING_STREAM << "Steppermotor::dev_read_position(): axis
 out of range !";
\end_layout

\begin_layout Verbatim
     7          WARNING_STREAM << endl;
\end_layout

\begin_layout Verbatim
     8                  
\end_layout

\begin_layout Verbatim
     9          TangoSys_OMemStream o;
\end_layout

\begin_layout Verbatim
    10                  
\end_layout

\begin_layout Verbatim
    11          o << "Axis number " << axis << " out of range" << ends;
\end_layout

\begin_layout Verbatim
    12          throw_exception("StepperMotor_OutOfRange",
\end_layout

\begin_layout Verbatim
    13                          o.str(),
\end_layout

\begin_layout Verbatim
    14                          "StepperMotor::dev_read_position");
\end_layout

\begin_layout Verbatim
    15     }
\end_layout

\begin_layout Verbatim
    16  
\end_layout

\begin_layout Verbatim
    17     return position[axis];
\end_layout

\begin_layout Verbatim
    18  }
\end_layout

\begin_layout Verbatim
    19  
\end_layout

\begin_layout Verbatim
    20  void always_executed_hook()
\end_layout

\begin_layout Verbatim
    21  {
\end_layout

\begin_layout Verbatim
    22     INFO_STREAM << "In the always_executed_hook method << endl;
\end_layout

\begin_layout Verbatim
    23  }
\end_layout

\begin_layout Verbatim
    24  
\end_layout

\begin_layout Verbatim
    25  Tango_DevState StepperMotor::dev_state()
\end_layout

\begin_layout Verbatim
    26  {
\end_layout

\begin_layout Verbatim
    27     INFO_STREAM << "In StepperMotor state command" << endl;
\end_layout

\begin_layout Verbatim
    28     return DeviceImpl::dev_state();
\end_layout

\begin_layout Verbatim
    29  }
\end_layout

\begin_layout Verbatim
    30  
\end_layout

\begin_layout Verbatim
    31  Tango_DevString StepperMotor::dev_status()
\end_layout

\begin_layout Verbatim
    32  {
\end_layout

\begin_layout Verbatim
    33     INFO_STREAM << "In StepperMotor status command" << endl;
\end_layout

\begin_layout Verbatim
    34     return DeviceImpl::dev_status();
\end_layout

\begin_layout Verbatim
    35  }
\end_layout

\begin_layout Verbatim
    36  
\end_layout

\begin_layout Verbatim
    37  void read_Direction(Tango::Attribute att)
\end_layout

\begin_layout Verbatim
    38  {
\end_layout

\begin_layout Verbatim
    39     att.set_value(attr_Direction_read);
\end_layout

\begin_layout Verbatim
    40  }
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
Line 1-18 : The 
\emph on
dev_read_position
\emph default
 method
\end_layout

\begin_layout Standard
Line 6-14 : Throw exception to client if the received axis number is out
 of range
\end_layout

\begin_layout Standard
Line 9 : A TangoSys_OMemStream is used as stream.
 The TangoSys_OMemStream has been defined in improve portability across
 platform.
 For Unix like operating system, it is a ostrtream type.
 For operating system with a full implementation of the standard library,
 it is a ostringstream type.
\end_layout

\begin_layout Standard
Line 20-23 : The 
\emph on
always_executed_hook
\emph default
 method.
 It does nothing.
 It has been included here only as pedagogic usage.
\end_layout

\begin_layout Standard
Line 25-29 : The 
\emph on
dev_state
\emph default
 method.
 It does exactly what the default 
\emph on
dev_state
\emph default
 does.
 It has been included here only as pedagogic usage
\end_layout

\begin_layout Standard
Line 31-35 : The 
\emph on
dev_status
\emph default
 method.
 It does exactly what the default 
\emph on
dev_statu
\emph default
s does.
 It has been included here only as pedagogic usage
\end_layout

\begin_layout Standard
Line 37-40 : The 
\emph on
read_Direction
\emph default
 method.
 Simply set the Attribute object internal value
\end_layout

\begin_layout Section
Device server under Windows
\end_layout

\begin_layout Standard
Two kind of programs are available under Windows
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Windows
\end_layout

\end_inset

.
 These kinds of programs are called console
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
console
\end_layout

\end_inset

 application or Windows application.
 A console application is started from a MS-DOS window and is very similar
 to classical UNIX program.
 A Windows application is most of the time not started from a MS-DOS window
 and is generally a graphical application without standard input/output.
 Writing a device server in a console application is straight forward following
 the rules described in the previous sub-chapters.
 Writing a device server in a Windows application needs some changes detailed
 in the following sub-chapters.
\end_layout

\begin_layout Subsection
The Tango device server graphical
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
graphical
\end_layout

\end_inset

 interface
\end_layout

\begin_layout Standard
Within the Windows operating system, most of the running application has
 a window user interface.
 This is also true for the Windows Tango device server.
 Using or not this interface is up to the device server programmer.
 The choice is done with an argument to the 
\emph on
server_init
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
server-init
\end_layout

\end_inset

()
\emph default
 method of the Tango::Util
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Util
\end_layout

\end_inset

 class.
 This interface is pretty simple and is based on three windows which are
 :
\end_layout

\begin_layout Itemize
The device server main window
\end_layout

\begin_layout Itemize
The device server console window
\end_layout

\begin_layout Itemize
The device server help window
\end_layout

\begin_layout Subsubsection
The device server main window
\end_layout

\begin_layout Standard
This window looks like :
\end_layout

\begin_layout Standard
\begin_inset VSpace 0.3cm
\end_inset


\end_layout

\begin_layout Standard
\align center
\begin_inset Float figure
wide false
sideways false
status open

\begin_layout Plain Layout
\begin_inset Caption Standard

\begin_layout Plain Layout
Tango device server main window
\end_layout

\end_inset


\end_layout

\begin_layout Plain Layout
\begin_inset Graphics
	filename nt_server/main.ps
	width 10cm

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset VSpace 0.3cm
\end_inset


\end_layout

\begin_layout Standard
Four menus are available in this window.
 The File menu allows the user to exit the device server.
 The View menu allows you to display/hide the device server console window.
 The Debug menu allows the user to change the server output verbose
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
verbose
\end_layout

\end_inset

 level.
 All the outputs goes to the console window even if it is hidden.
 The Help menu displays the help window.
 The device server name is displayed in the window title.
 The text displayed at the bottom of the window has a default value (the
 one displayed in this window dump) but may be changed by the device server
 programmer using the 
\emph on
set_main_window_text(
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
set-main-window-text
\end_layout

\end_inset

)
\emph default
 method of the Tango::Util class.
 If used, this method must be called prior to the call of the 
\emph on
server_init()
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
server-init
\end_layout

\end_inset


\emph default
 method.
 Refer to 
\begin_inset CommandInset citation
LatexCommand cite
key "TANGO_ref_man"

\end_inset

 for a complete description of this method.
\end_layout

\begin_layout Subsubsection
The console window
\end_layout

\begin_layout Standard
This window looks like :
\end_layout

\begin_layout Standard
\begin_inset VSpace 0.3cm
\end_inset


\end_layout

\begin_layout Standard
\align center
\begin_inset Graphics
	filename nt_server/cons.ps
	width 14cm

\end_inset


\end_layout

\begin_layout Standard
\begin_inset VSpace 0.3cm
\end_inset


\end_layout

\begin_layout Standard
It simply displays all the logging
\emph on

\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
logging
\end_layout

\end_inset


\emph default
 message when a console target is used in the device server.
 
\end_layout

\begin_layout Subsubsection
The help window
\end_layout

\begin_layout Standard
This window looks like :
\end_layout

\begin_layout Standard
\begin_inset VSpace 0.3cm
\end_inset


\end_layout

\begin_layout Standard
\align center
\begin_inset Graphics
	filename nt_server/help.ps
	width 9cm

\end_inset


\end_layout

\begin_layout Standard

\end_layout

\begin_layout Standard
\begin_inset VSpace 0.3cm
\end_inset


\end_layout

\begin_layout Standard
This window displays 
\end_layout

\begin_layout Itemize
The device server name
\end_layout

\begin_layout Itemize
The Tango library release
\end_layout

\begin_layout Itemize
The Tango IDL definition release
\end_layout

\begin_layout Itemize
The device server release.
 The device server programmer may set this release number using the 
\emph on
set_server_version()
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
set-server-version
\end_layout

\end_inset


\emph default
 method of the Tango::Util
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Util
\end_layout

\end_inset

 class.
 If used, this must be done prior to the call of the 
\emph on
server_init()
\emph default
 method.
 If the 
\emph on
set_server_version()
\emph default
 method is not used, x.y is displays as version number.
 Refer to 
\begin_inset CommandInset citation
LatexCommand cite
key "TANGO_ref_man"

\end_inset

 for a complete description of this method.
\end_layout

\begin_layout Subsection
MFC device server
\end_layout

\begin_layout Standard
There is no 
\emph on
main
\emph default
 function within a classical MFC
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
MFC
\end_layout

\end_inset

 program.
 Most of the time, your application is represented by one instance of a
 C++ class which inherits from the MFC CWinApp class.
 This CWinApp class has several methods that you may overload in your applicatio
n class.
 For a device server to run correctly, you must overload two methods of
 the CWinApp class.
 These methods are the 
\emph on
InitInstance()
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
InitInstance
\end_layout

\end_inset


\emph default
 and 
\emph on
ExitInstance()
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
ExitInstance
\end_layout

\end_inset


\emph default
 methods.
 The rule of these methods is obvious following their names.
\end_layout

\begin_layout Standard

\series bold
Remember that if the Tango device server graphical user interface is used,
 you must link your device server with the Tango windows resource
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
resource
\end_layout

\end_inset

 file
\series default
.
 This is done by adding the Tango resource file to the Project Settings/Link/Inp
ut/Object, library modules window in VC++.
\end_layout

\begin_layout Subsubsection
The InitInstance method
\end_layout

\begin_layout Standard
The code to be added here is the equivalent of the code written in a classical
 
\emph on
main()
\emph default
 function.
 Don't forget to add the 
\emph on
tango.h
\emph default
 file in the list of included files.
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
     1 BOOL FluidsApp::InitInstance()
\end_layout

\begin_layout Verbatim
     2 {
\end_layout

\begin_layout Verbatim
     3    AfxEnableControlContainer();
\end_layout

\begin_layout Verbatim
     4  
\end_layout

\begin_layout Verbatim
     5 // Standard initialization
\end_layout

\begin_layout Verbatim
     6 // If you are not using these features and wish to reduce the size
\end_layout

\begin_layout Verbatim
     7 //  of your final executable, you should remove from the following
\end_layout

\begin_layout Verbatim
     8 //  the specific initialization routines you do not need.
\end_layout

\begin_layout Verbatim
     9  
\end_layout

\begin_layout Verbatim
    10  #ifdef _AFXDLL
\end_layout

\begin_layout Verbatim
    11    Enable3dControls();          // Call this when using MFC in a
 shared DLL
\end_layout

\begin_layout Verbatim
    12  #else
\end_layout

\begin_layout Verbatim
    13    Enable3dControlsStatic();    // Call this when linking to MFC
 statically
\end_layout

\begin_layout Verbatim
    14  #endif
\end_layout

\begin_layout Verbatim
    15    Tango::Util *tg;
\end_layout

\begin_layout Verbatim
    16    try
\end_layout

\begin_layout Verbatim
    17    {
\end_layout

\begin_layout Verbatim
    18          
\end_layout

\begin_layout Verbatim
    19        tg = Tango::Util::init(m_hInstance,m_nCmdShow);
\end_layout

\begin_layout Verbatim
    20  
\end_layout

\begin_layout Verbatim
    21        tg->server_init(true);
\end_layout

\begin_layout Verbatim
    22  
\end_layout

\begin_layout Verbatim
    23        tg->server_run();
\end_layout

\begin_layout Verbatim
    24  
\end_layout

\begin_layout Verbatim
    25    }
\end_layout

\begin_layout Verbatim
    26    catch (bad_alloc)
\end_layout

\begin_layout Verbatim
    27    {
\end_layout

\begin_layout Verbatim
    28        MessageBox((HWND)NULL,"Memory error","Command line",MB_ICONSTOP);
\end_layout

\begin_layout Verbatim
    29        return(FALSE);
\end_layout

\begin_layout Verbatim
    30    }
\end_layout

\begin_layout Verbatim
    31    catch (Tango::DevFailed &e)
\end_layout

\begin_layout Verbatim
    32    {
\end_layout

\begin_layout Verbatim
    33        MessageBox((HWND)NULL,,e.errors[0].desc.in(),"Command line",MB_ICONST
OP);
\end_layout

\begin_layout Verbatim
    34        return(FALSE);
\end_layout

\begin_layout Verbatim
    35    }
\end_layout

\begin_layout Verbatim
    36    catch (CORBA::Exception &)
\end_layout

\begin_layout Verbatim
    37    {
\end_layout

\begin_layout Verbatim
    38        MessageBox((HWND)NULL,"Exception CORBA","Command line",MB_ICONSTOP
);
\end_layout

\begin_layout Verbatim
    39        return(FALSE);
\end_layout

\begin_layout Verbatim
    40    }
\end_layout

\begin_layout Verbatim
    41  
\end_layout

\begin_layout Verbatim
    42    m_pMainWnd = new CWnd;
\end_layout

\begin_layout Verbatim
    43    m_pMainWnd->Attach(tg->get_ds_main_window());
\end_layout

\begin_layout Verbatim
    44  
\end_layout

\begin_layout Verbatim
    45    return TRUE;
\end_layout

\begin_layout Verbatim
    46  }
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
Line 19 : Initialise Tango system.
 This method also analises the argument used in command line.
\end_layout

\begin_layout Standard
Line 21 : Create Tango classes requesting the Tango Windows graphical
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
graphical
\end_layout

\end_inset

 interface to be used
\end_layout

\begin_layout Standard
Line 23 : Start Network listener.
 Note that under NT, this call returns in the contrary of UNIX like operating
 system.
\end_layout

\begin_layout Standard
Line 26-30 : Display a message box in case of memory allocation error and
 leave method with a return value set to false in order to stop the process
\end_layout

\begin_layout Standard
Line 31-35 : Display a message box in case of error during server initialization
 phase.
\end_layout

\begin_layout Standard
Line 36-40 : Display a message box in case of error other than memory allocation.
 Leave method with a return value set to false in order to stop the process.
\end_layout

\begin_layout Standard
Line 37-38 : Create a MFC
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
MFC
\end_layout

\end_inset

 main window and attach the Tango graphical interface main window to this
 MFC window.
\end_layout

\begin_layout Subsubsection
The ExitInstance
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
ExitInstance
\end_layout

\end_inset

 method
\end_layout

\begin_layout Standard
This method is called when the application is stopped.
 For Tango device server, its rule is to destroy the Tango::Util singleton
 if this one has been correctly constructed.
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
     1  int FluidsApp::ExitInstance()
\end_layout

\begin_layout Verbatim
     2  {
\end_layout

\begin_layout Verbatim
     3     bool del = true;
\end_layout

\begin_layout Verbatim
     4  
\end_layout

\begin_layout Verbatim
     5     try
\end_layout

\begin_layout Verbatim
     6     {
\end_layout

\begin_layout Verbatim
     7         Tango::Util *tg = Tango::Util::instance();
\end_layout

\begin_layout Verbatim
     8     }
\end_layout

\begin_layout Verbatim
     9     catch(Tango::DevFailed)
\end_layout

\begin_layout Verbatim
    10     {
\end_layout

\begin_layout Verbatim
    11         del = false;
\end_layout

\begin_layout Verbatim
    12     }
\end_layout

\begin_layout Verbatim
    13  
\end_layout

\begin_layout Verbatim
    14     if (del == true)
\end_layout

\begin_layout Verbatim
    15         delete (Tango::Util::instance());
\end_layout

\begin_layout Verbatim
    16  
\end_layout

\begin_layout Verbatim
    17     return CWinApp::ExitInstance();
\end_layout

\begin_layout Verbatim
    18  }
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
Line 7 : Try to retrieve the Tango::Util singleton.
 If this one has not been constructed correctly, this call will throw an
 exception.
\end_layout

\begin_layout Standard
Line 9-12 : Catch the exception in case of incomplete Tango::Util singleton
 construction
\end_layout

\begin_layout Standard
Line 14-15 : Delete the Tango::Util singleton.
 This will unregister the Tango device server from the Tango database.
\end_layout

\begin_layout Standard
Line 17 : Execute the 
\emph on
ExitInstance
\emph default
 method of the CWinApp class.
\end_layout

\begin_layout Standard
If you don't want to use the Tango device server graphical interface, do
 not pass any parameter to the 
\emph on
server_init()
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
server-init
\end_layout

\end_inset


\emph default
 method and instead of the code display in lines 37 and 38 in the previous
 example of the 
\emph on
InitInstance()
\emph default
 method, use your own code to initialize your own application.
\end_layout

\begin_layout Subsubsection
Example of how to build a Windows device server MFC based
\end_layout

\begin_layout Standard
This sub-chapter gives an example of what it is needed to do to build a
 MFC Windows device server.
 Rather than being a list of actions to strictly follow, this is some general
 rules of how using VC++ to build a Tango device server using MFC.
\end_layout

\begin_layout Enumerate
Create your device server using Pogo.
 For a class named MyMotor, the following files will be needed : 
\emph on
class_factory.cpp
\emph default
, 
\emph on
MyMotorClass.h
\emph default
, 
\emph on
MyMotorClass.cpp
\emph default
, 
\emph on
MyMotor.h
\emph default
 and 
\emph on
MyMotor.cpp.
\end_layout

\begin_layout Enumerate
On a Windows computer running VC++, create a new project of type 
\begin_inset Quotes eld
\end_inset

MFC app Wizard (exe)
\begin_inset Quotes erd
\end_inset

 using static MFC
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
MFC
\end_layout

\end_inset

 libs.
 Ask for a dialog based project without ActiveX controls.
\end_layout

\begin_layout Enumerate
Copy the five files generated by Pogo to the Windows computer and add them
 to your project
\end_layout

\begin_layout Enumerate
Remove the dialog window files (xxxDlg.cpp and xxxDlg.h), the Resource include
 file and the resource script file from your project
\end_layout

\begin_layout Enumerate
Add #include <stdafx.h> as first line of the include files list in 
\emph on
class_factory.cpp
\emph default
, 
\emph on
MyMotorClass.cpp
\emph default
 and 
\emph on
MyMotor.cpp
\emph default
 file.
 Also add your own directory and the Tango include directory to the project
 pre-compiler include directories list.
\end_layout

\begin_layout Enumerate
Enable RTTI in your project settings (see chapter 
\begin_inset CommandInset ref
LatexCommand ref
reference "Compiling NT"

\end_inset

)
\end_layout

\begin_layout Enumerate
Change your application class: 
\end_layout

\begin_deeper
\begin_layout Enumerate
Add the definition of an 
\emph on
ExitInstance
\emph default
 method in the declaration file.
 (xxx.h file)
\end_layout

\begin_layout Enumerate
Remove the include of the dialog window file in the xxx.cpp file and add
 an include of the Tango master include files (tango.h)
\end_layout

\begin_layout Enumerate
Replace the 
\emph on
InitInstance
\emph default
() method as described in previous sub-chapter.
 (xx.cpp file)
\end_layout

\begin_layout Enumerate
Add an 
\emph on
ExitInstance()
\emph default
 method as described in previous sub-chapter (xxx.cpp file)
\end_layout

\end_deeper
\begin_layout Enumerate
Add all the libraries needed to compile a Tango device server (see chapter
 
\begin_inset CommandInset ref
LatexCommand ref
reference "Compiling NT"

\end_inset

) and the Tango resource file to the linker Object/Libraries modules.
\end_layout

\begin_layout Subsection
Win32 application
\end_layout

\begin_layout Standard
Even if it is more natural to use the C++ structure of the MFC class to
 write a Tango device server, it is possible to write a device server as
 a Win32
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Win32
\end_layout

\end_inset

 application.
 Instead of having a 
\emph on
main()
\emph default
 function as the application entry point, the operating system, provides
 a 
\emph on
WinMain()
\emph default
 function as the application entry point.
 Some code must be added to this 
\emph on
WinMain
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
WinMain
\end_layout

\end_inset


\emph default
 function in order to support Tango device server.
 Don't forget to add the 
\emph on
tango
\emph default
.
\emph on
h
\emph default
 file in the list of included files.
 If you are using the project files generated by Pogo, don't forget to change
 the linker SUBSYSTEM option to "Windows" (Under Linker/System in the project
 properties window).
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
     1  int APIENTRY WinMain(HINSTANCE hInstance,
\end_layout

\begin_layout Verbatim
     2                       HINSTANCE hPrevInstance,
\end_layout

\begin_layout Verbatim
     3                       LPSTR     lpCmdLine,
\end_layout

\begin_layout Verbatim
     4                       int       nCmdShow)
\end_layout

\begin_layout Verbatim
     5  {
\end_layout

\begin_layout Verbatim
     6     MSG msg;
\end_layout

\begin_layout Verbatim
     7     Tango::Util *tg;
\end_layout

\begin_layout Verbatim
     8  
\end_layout

\begin_layout Verbatim
     9     try
\end_layout

\begin_layout Verbatim
    10     {
\end_layout

\begin_layout Verbatim
    11         tg = Tango::Util::init(hInstance,nCmdShow);
\end_layout

\begin_layout Verbatim
    12  
\end_layout

\begin_layout Verbatim
    13         string txt;
\end_layout

\begin_layout Verbatim
    14         txt = "Blabla first line
\backslash
n";
\end_layout

\begin_layout Verbatim
    15         txt = txt + "Blabla second line
\backslash
n";
\end_layout

\begin_layout Verbatim
    16         txt = txt + "Blabla third line
\backslash
n";
\end_layout

\begin_layout Verbatim
    17         tg->set_main_window_text(txt);
\end_layout

\begin_layout Verbatim
    18         tg->set_server_version("2.2");
\end_layout

\begin_layout Verbatim
    19  
\end_layout

\begin_layout Verbatim
    20         tg->server_init(true);
\end_layout

\begin_layout Verbatim
    21  
\end_layout

\begin_layout Verbatim
    22         tg->server_run();
\end_layout

\begin_layout Verbatim
    23  
\end_layout

\begin_layout Verbatim
    24     }
\end_layout

\begin_layout Verbatim
    25     catch (bad_alloc)
\end_layout

\begin_layout Verbatim
    26     {
\end_layout

\begin_layout Verbatim
    27         MessageBox((HWND)NULL,"Memory error","Command line",MB_ICONSTOP);
\end_layout

\begin_layout Verbatim
    28         return (FALSE);
\end_layout

\begin_layout Verbatim
    29     }
\end_layout

\begin_layout Verbatim
    30     catch (Tango::DevFailed &e)
\end_layout

\begin_layout Verbatim
    31     {
\end_layout

\begin_layout Verbatim
    32         MessageBox((HWND)NULL,e.errors[0].desc.in(),"Command line",MB_ICONST
OP);
\end_layout

\begin_layout Verbatim
    33         return (FALSE);
\end_layout

\begin_layout Verbatim
    34     }
\end_layout

\begin_layout Verbatim
    35     catch (CORBA::Exception &)
\end_layout

\begin_layout Verbatim
    36     {
\end_layout

\begin_layout Verbatim
    37         MessageBox((HWND)NULL,"Exception CORBA","Command line",MB_ICONSTO
P);
\end_layout

\begin_layout Verbatim
    38         return(FALSE);
\end_layout

\begin_layout Verbatim
    39     }
\end_layout

\begin_layout Verbatim
    40  
\end_layout

\begin_layout Verbatim
    41     while (GetMessage(&msg, NULL, 0, 0)) 
\end_layout

\begin_layout Verbatim
    42     {
\end_layout

\begin_layout Verbatim
    43         TranslateMessage(&msg);
\end_layout

\begin_layout Verbatim
    44         DispatchMessage(&msg);
\end_layout

\begin_layout Verbatim
    45     }
\end_layout

\begin_layout Verbatim
    46  
\end_layout

\begin_layout Verbatim
    47     delete tg;
\end_layout

\begin_layout Verbatim
    48  
\end_layout

\begin_layout Verbatim
    49     return msg.wParam;
\end_layout

\begin_layout Verbatim
    50  }
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
Line 11 : Create the Tango::Util
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Util
\end_layout

\end_inset

 singleton
\end_layout

\begin_layout Standard
Line 13-18 : Set parameters for the graphical interface
\end_layout

\begin_layout Standard
Line 20 : Initialize Tango device server requesting the display of the graphical
 interface
\end_layout

\begin_layout Standard
Line 22 : Run the device server
\end_layout

\begin_layout Standard
Line 25-39 : Display a message box for all the kinds of error during Tango
 device server initialization phase and exit WinMain
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
WinMain
\end_layout

\end_inset

 function.
\end_layout

\begin_layout Standard
Line 41-45 : The Windows message loop
\end_layout

\begin_layout Standard
Line 47 : Delete the Tango::Util singleton.
 This class destructor unregisters the device server from the Tango database.
\end_layout

\begin_layout Standard

\series bold
Remember that if the Tango device server graphical user interface is used,
 you must add the Tango windows resource
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
resource
\end_layout

\end_inset

 file
\series default
 
\series bold
to your project
\series default
.
\end_layout

\begin_layout Standard
If you don't want to use the tango device server graphical user interface,
 do not use any parameter in the call of the 
\emph on
server_init()
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
server-init
\end_layout

\end_inset


\emph default
 method and do not link your device server with the Tango Windows resource
 file.
\end_layout

\begin_layout Subsection
Device server as service
\end_layout

\begin_layout Standard
With Windows, if you want to have processes which survive to logoff sequence
 and/or are automatically started during computer startup sequence, you
 have to write them as service
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
service
\end_layout

\end_inset

.
 It is possible to write Tango device server as service.
 You need to
\end_layout

\begin_layout Enumerate
Write a class which inherits from a pre-written Tango class called NTService.
 This class must have a 
\emph on
start
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
start
\end_layout

\end_inset


\emph default
 method.
 
\end_layout

\begin_layout Enumerate
Write a main function following a predefined skeleton.
\end_layout

\begin_layout Subsubsection
The service class
\end_layout

\begin_layout Standard
It must inherits from the 
\emph on
NTService
\emph default
 class and defines a 
\emph on
start
\emph default
 method.
 The NTService
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
NTService
\end_layout

\end_inset

 class must be constructed with one argument which is the device server
 executable
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
executable
\end_layout

\end_inset

 name.
 The 
\emph on
start
\emph default
 method has three arguments which are the number of arguments passed to
 the method, the argument list and a reference to an object used to log
 info in the NT event system.
 The first two args must be passed to the Tango::Util::init method and the
 last one is used to log error or info messages.
 The class definition file looks like
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
     1  #include <tango.h>
\end_layout

\begin_layout Verbatim
     2  #include <ntservice.h>
\end_layout

\begin_layout Verbatim
     3  
\end_layout

\begin_layout Verbatim
     4  class MYService: public Tango::NTService
\end_layout

\begin_layout Verbatim
     5  {
\end_layout

\begin_layout Verbatim
     6  public:
\end_layout

\begin_layout Verbatim
     7     MYService(char *);
\end_layout

\begin_layout Verbatim
     8  
\end_layout

\begin_layout Verbatim
     9     void start(int,char **,Tango::NTEventLogger *);
\end_layout

\begin_layout Verbatim
    10  };
\end_layout

\begin_layout Standard

\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
Line 1-2 : Some include files
\end_layout

\begin_layout Standard
Line 4 : The MYService class inherits from 
\emph on
Tango::NTService
\emph default
 class
\end_layout

\begin_layout Standard
Line 7 : Constructor with one parameter
\end_layout

\begin_layout Standard
Line 9 : The 
\emph on
start()
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
start
\end_layout

\end_inset


\emph default
 method
\begin_inset Newline newline
\end_inset


\end_layout

\begin_layout Standard
The class source code looks like
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
     1  #include <myservice.h>
\end_layout

\begin_layout Verbatim
     2  #include <tango.h>
\end_layout

\begin_layout Verbatim
     3  
\end_layout

\begin_layout Verbatim
     4  using namespace std;
\end_layout

\begin_layout Verbatim
     5  
\end_layout

\begin_layout Verbatim
     6  MYService::MYService(char *exec_name):NTService(exec_name)
\end_layout

\begin_layout Verbatim
     7  {
\end_layout

\begin_layout Verbatim
     8  }
\end_layout

\begin_layout Verbatim
     9  
\end_layout

\begin_layout Verbatim
    10  void MYService::start(int argc,char **argv,Tango::NTEventLogger
 *logger)
\end_layout

\begin_layout Verbatim
    11  {
\end_layout

\begin_layout Verbatim
    12     Tango::Util *tg;
\end_layout

\begin_layout Verbatim
    13     try
\end_layout

\begin_layout Verbatim
    14     {
\end_layout

\begin_layout Verbatim
    15        Tango::Util::_service = true;
\end_layout

\begin_layout Verbatim
    16  
\end_layout

\begin_layout Verbatim
    17        tg = Tango::Util::init(argc,argv);
\end_layout

\begin_layout Verbatim
    18  
\end_layout

\begin_layout Verbatim
    19        tg->server_init();
\end_layout

\begin_layout Verbatim
    20  
\end_layout

\begin_layout Verbatim
    21        tg->server_run();
\end_layout

\begin_layout Verbatim
    22     }
\end_layout

\begin_layout Verbatim
    23     catch (bad_alloc)
\end_layout

\begin_layout Verbatim
    24     {
\end_layout

\begin_layout Verbatim
    25        logger->error("Can't allocate memory to store device object");
\end_layout

\begin_layout Verbatim
    26     }
\end_layout

\begin_layout Verbatim
    27     catch (Tango::DevFailed &e)
\end_layout

\begin_layout Verbatim
    28     {
\end_layout

\begin_layout Verbatim
    29        logger->error(e.errors[0].desc.in());
\end_layout

\begin_layout Verbatim
    30     }
\end_layout

\begin_layout Verbatim
    31     catch (CORBA::Exception &)
\end_layout

\begin_layout Verbatim
    32     {
\end_layout

\begin_layout Verbatim
    33        logger->error("CORBA Exception");
\end_layout

\begin_layout Verbatim
    34     }
\end_layout

\begin_layout Verbatim
    35  }
\end_layout

\begin_layout Standard

\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
Line 6-8 : The MYService class constructor code.
\end_layout

\begin_layout Standard
Line 15 : Set to true the 
\emph on
_service
\emph default
 static variable of the 
\emph on
Tango::Util
\emph default
 class.
\end_layout

\begin_layout Standard
Line 17-21 : Classical Tango device server startup code
\end_layout

\begin_layout Standard
Line 23-34 : Exception management.
 Please, note that within a service.
 it is not possible to print data on a console.
 This method receives a reference to a logger
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
logger
\end_layout

\end_inset

 object.
 This object sends all its output to the Windows event
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
event
\end_layout

\end_inset

 system.
 It is used to send messages when an exception has occurred.
\end_layout

\begin_layout Subsubsection
The main function
\end_layout

\begin_layout Standard
The main function is used to create one instance of the class describing
 the service, to check the service option and to run the service.
 The code looks like :
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
     1  #include <tango.h>
\end_layout

\begin_layout Verbatim
     2  #include <MYService.h>
\end_layout

\begin_layout Verbatim
     3  
\end_layout

\begin_layout Verbatim
     4  using namespace std;
\end_layout

\begin_layout Verbatim
     5  
\end_layout

\begin_layout Verbatim
     6  
\end_layout

\begin_layout Verbatim
     7  int main(int argc,char *argv[])
\end_layout

\begin_layout Verbatim
     8  {
\end_layout

\begin_layout Verbatim
     9     MYService service(argv[0]);
\end_layout

\begin_layout Verbatim
    10          
\end_layout

\begin_layout Verbatim
    11     int ret;
\end_layout

\begin_layout Verbatim
    12     if ((ret = service.options(argc,argv)) <= 0)
\end_layout

\begin_layout Verbatim
    13         return ret;
\end_layout

\begin_layout Verbatim
    14          
\end_layout

\begin_layout Verbatim
    15     service.run(argc,argv);
\end_layout

\begin_layout Verbatim
    16          
\end_layout

\begin_layout Verbatim
    17     return 0;
\end_layout

\begin_layout Verbatim
    18  }
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
Line 9 : Create one instance of the MYService class with the executable
 name as parameter
\end_layout

\begin_layout Standard
Line 12 : Check service option with the 
\emph on
options()
\emph default
 method inherited from the NTService
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
NTService
\end_layout

\end_inset

 class.
\end_layout

\begin_layout Standard
Line 15 : Run the service.
 The 
\emph on
run()
\emph default
 method is inherited from the NTService class.
 This method will after some NT initialization sequence execute the user
 
\emph on
start()
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
start
\end_layout

\end_inset


\emph default
 method.
\end_layout

\begin_layout Subsubsection
Service options and messages
\end_layout

\begin_layout Standard
When a Tango device server is written as a Windows service, it supports
 several new options.
 These option are linked to Windows service
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
service
\end_layout

\end_inset

 usage.
\end_layout

\begin_layout Standard
Before it can be used, a service must be installed.
 A name and a title is associated to each service.
 For Tango device server used as service, the service name is build from
 the executable name followed by the underscore character and the instance
 name.
 For example, a device server service executable file named 
\begin_inset Quotes eld
\end_inset

opc
\begin_inset Quotes erd
\end_inset

 and started with 
\begin_inset Quotes eld
\end_inset

fluids
\begin_inset Quotes erd
\end_inset

 as instance name, will be named 
\begin_inset Quotes eld
\end_inset

opc_fluids
\begin_inset Quotes erd
\end_inset

.
 The title string is built from the service executable name followed by
 the sentence 
\begin_inset Quotes eld
\end_inset

Tango device server
\begin_inset Quotes erd
\end_inset

 and the instance name between parenthesis.
 In the previous example, the service title will be 
\begin_inset Quotes eld
\end_inset

opc Tango device server (fluids)
\begin_inset Quotes erd
\end_inset

.
 Once a service is installed, you can configure it with the 
\begin_inset Quotes eld
\end_inset

Services
\begin_inset Quotes erd
\end_inset

 application of the control panel.
 Services title are displayed by this application and allow the user to
 select one specific service.
 Once a service is selected, it is possible to start/stop it and to configure
 its startup type as manual (with the Services application) or as automatic.
 When the automatic mode is chosen, the service starts when the computer
 is started.
 In this case, the service executable code must resides on the computer
 local disk.
\end_layout

\begin_layout Standard
Tango device server logs message in the Windows event
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
event
\end_layout

\end_inset

 system when the service is started or stopped.
 You can see these messages with the 
\begin_inset Quotes eld
\end_inset

Event Viewer
\begin_inset Quotes erd
\end_inset

 application (Start->Programs->Administrative tools->Event Viewer) and choose
 the Application events.
\end_layout

\begin_layout Standard
The new options are -i, -s, -u, -h and -d.
\end_layout

\begin_layout Itemize
-i : Install the service
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
service
\end_layout

\end_inset


\end_layout

\begin_layout Itemize
-s : Install the service and choose the automatic startup mode
\end_layout

\begin_layout Itemize
-u : Un-install the service
\end_layout

\begin_layout Itemize
-dbg : Run in console mode to debug service.
 The service must have been installed prior to used it.
 The classical -v device server option can be used with the -d option.
\end_layout

\begin_layout Standard
On the command line, all these options must be used after the device server
 instance name (
\begin_inset Quotes eld
\end_inset

opc fluids -i
\begin_inset Quotes erd
\end_inset

 to install the service, 
\begin_inset Quotes eld
\end_inset

opc fluids -u
\begin_inset Quotes erd
\end_inset

 to un-install the service, 
\begin_inset Quotes eld
\end_inset

opc fluids -v -d
\begin_inset Quotes erd
\end_inset

 to debug the service)
\end_layout

\begin_layout Subsubsection
Tango device server using MFC as Windows service
\end_layout

\begin_layout Standard
If your Tango device server uses MFC
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
MFC
\end_layout

\end_inset

 and must be written as a Windows NT service, follow these rules :
\end_layout

\begin_layout Itemize
Don't forget to add the 
\emph on
stdafx.h
\emph default
 file as the first file included in all the source files making the project.
\end_layout

\begin_layout Itemize
Comment out the definition of VC_EXTRALEAN in the 
\emph on
stdafx.h
\emph default
 file.
\end_layout

\begin_layout Itemize
Change the pre-processor definitions, replace _WINDOWS by _CONSOLE
\end_layout

\begin_layout Itemize
Add the /SUBSYSTEM:CONSOLE option in the linker options window of the project
 settings.
\end_layout

\begin_layout Itemize
Add a call to initialize the MFC (
\emph on
AfxWinInit()
\emph default
) in the service main function
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
     1  int main(int argc,char *argv[])
\end_layout

\begin_layout Verbatim
     2  {
\end_layout

\begin_layout Verbatim
     3     if (!AfxWinInit(::GetModuleHandle(NULL),NULL,::GetCommandLine(),0))
\end_layout

\begin_layout Verbatim
     4     {
\end_layout

\begin_layout Verbatim
     5        cerr << "Can't initialise MFC !" << endl;
\end_layout

\begin_layout Verbatim
     6        return -1;
\end_layout

\begin_layout Verbatim
     7     }
\end_layout

\begin_layout Verbatim
     8  
\end_layout

\begin_layout Verbatim
     9     service serv(argv[0]);
\end_layout

\begin_layout Verbatim
    10  
\end_layout

\begin_layout Verbatim
    11     int ret;
\end_layout

\begin_layout Verbatim
    12     if ((ret = serv.options(argc,argv)) <= 0)
\end_layout

\begin_layout Verbatim
    13          return ret;
\end_layout

\begin_layout Verbatim
    14  
\end_layout

\begin_layout Verbatim
    15     serv.run(argc,argv);
\end_layout

\begin_layout Verbatim
    16  
\end_layout

\begin_layout Verbatim
    17     return 0;
\end_layout

\begin_layout Verbatim
    18  }
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
Line 3 : The MFC classes are initialized with the 
\emph on
AfxWinInit()
\emph default
 function call.
\end_layout

\begin_layout Section
Compiling, linking and executing a TANGO device server process
\begin_inset CommandInset label
LatexCommand label
name "sec:Compiling,-linking-and"

\end_inset


\end_layout

\begin_layout Subsection
Compiling and linking a C++ device server
\end_layout

\begin_layout Subsubsection
On UNIX like operating system 
\end_layout

\begin_layout Paragraph
Supported development tools
\end_layout

\begin_layout Standard
The supported compiler for Linux is 
\series bold
gcc
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
gcc
\end_layout

\end_inset


\series default
 release 3.3 and above.
 Please, note that to debug a Tango device server running under Linux
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Linux
\end_layout

\end_inset

, 
\series bold
gdb
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
gdb
\end_layout

\end_inset


\series default
 release 7 and above is needed in order to correctly handle threads.
\end_layout

\begin_layout Paragraph
Compiling
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
compiling
\end_layout

\end_inset


\end_layout

\begin_layout Standard
TANGO for C++ uses omniORB (release 4) as underlying CORBA Object Request
 Broker 
\begin_inset CommandInset citation
LatexCommand cite
key "OOC page"

\end_inset

 and starting with Tango 8, the ZMQ library.
 To compile a TANGO device server, your include search path must be set
 to :
\end_layout

\begin_layout Itemize
The omniORB include directory
\end_layout

\begin_layout Itemize
The ZMQ
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
ZMQ
\end_layout

\end_inset

 include directory
\end_layout

\begin_layout Itemize
The Tango include directory
\end_layout

\begin_layout Itemize
Your development directory
\end_layout

\begin_layout Paragraph
Linking
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
linking
\end_layout

\end_inset

 
\end_layout

\begin_layout Standard
To build a running device server process, you need to link your code with
 several libraries.
 Nine of them are always the same whatever the operating system used is.
 These nine libraries are:
\end_layout

\begin_layout Itemize
The Tango libraries (called 
\series bold
libtango
\series default
 and 
\series bold
liblog4tango
\series default
)
\end_layout

\begin_layout Itemize
Three omniORB
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
omniORB
\end_layout

\end_inset

 package libraries (called 
\series bold
libomniORB4
\series default
, 
\series bold
libomniDynamic4
\series default
 and 
\series bold
libCOS4)
\end_layout

\begin_layout Itemize
The omniORB threading library (called 
\series bold
libomnithread
\series default
)
\end_layout

\begin_layout Itemize
The ZMQ library (callled 
\series bold
libzmq
\series default
)
\end_layout

\begin_layout Standard
On top of that, you need additional libraries depending on the operating
 system :
\end_layout

\begin_layout Itemize
For Linux, add the posix thread library (
\series bold
libpthread
\series default
)
\end_layout

\begin_layout Standard
The following table summarizes the necessary options to compile a Tango
 C++ device server.
 Please, note that starting with Tango 8 and for gcc release 4.3 and later,
 some C++11
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
C++11
\end_layout

\end_inset

 code has been used.
 This requires the compiler option "-std=c++0x".
 Obviously, the options -I and -L must be updated to reflect your file system
 organization.
 
\end_layout

\begin_layout Standard
\begin_inset VSpace 0.3cm
\end_inset


\end_layout

\begin_layout Standard
\align center
\begin_inset Tabular
<lyxtabular version="3" rows="2" columns="3">
<features rotate="0" islongtable="true" longtabularalignment="center">
<column alignment="center" valignment="top" width="0pt">
<column alignment="center" valignment="top" width="0pt">
<column alignment="block" valignment="middle" width="70mm">
<row>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Operating system
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Compiling option
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Linking option
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Linux gcc
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
-D_REENTRANT -std=c++0x -I..
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
-L..
 -ltango -llog4tango -lomniORB4 -lomniDynamic4 -lCOS4 -lomnithread -lzmq
 -lpthread
\end_layout

\end_inset
</cell>
</row>
</lyxtabular>

\end_inset


\end_layout

\begin_layout Standard
\begin_inset VSpace 0.3cm
\end_inset


\end_layout

\begin_layout Standard
The following is an example of a Makefile for Linux.
 Obviously, all the paths are set to the ESRF file system structure.
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
1 #
\end_layout

\begin_layout Verbatim
2 # Makefile to generate a Tango server
\end_layout

\begin_layout Verbatim
3 #
\end_layout

\begin_layout Verbatim
4 
\end_layout

\begin_layout Verbatim
5 CC = c++
\end_layout

\begin_layout Verbatim
6 BIN_DIR = ubuntu1104
\end_layout

\begin_layout Verbatim
7 TANGO_HOME = /segfs/tango
\end_layout

\begin_layout Verbatim
8 
\end_layout

\begin_layout Verbatim
9 INCLUDE_DIRS = -I $(TANGO_HOME)/include/$(BIN_DIR) -I .
\end_layout

\begin_layout Verbatim
10
\end_layout

\begin_layout Verbatim
11 
\end_layout

\begin_layout Verbatim
12 LIB_DIRS = -L $(TANGO_HOME)/lib/$(BIN_DIR)
\end_layout

\begin_layout Verbatim
13 
\end_layout

\begin_layout Verbatim
14 
\end_layout

\begin_layout Verbatim
15 CXXFLAGS = -D_REENTRANT -std=c++0x $(INCLUDE_DIRS)
\end_layout

\begin_layout Verbatim
16 LFLAGS = $(LIB_DIRS) -ltango 
\backslash

\end_layout

\begin_layout Verbatim
17                      -llog4tango 
\backslash

\end_layout

\begin_layout Verbatim
18                      -lomniORB4 
\backslash

\end_layout

\begin_layout Verbatim
19                      -lomniDynamic4 
\backslash

\end_layout

\begin_layout Verbatim
20                      -lCOS4 
\backslash

\end_layout

\begin_layout Verbatim
21                      -lomnithread 
\backslash

\end_layout

\begin_layout Verbatim
22                      -lzmq 
\backslash

\end_layout

\begin_layout Verbatim
23                      -lpthread
\end_layout

\begin_layout Verbatim
24 
\end_layout

\begin_layout Verbatim
25 
\end_layout

\begin_layout Verbatim
26 SVC_OBJS = main.o 
\backslash

\end_layout

\begin_layout Verbatim
27            ClassFactory.o 
\backslash

\end_layout

\begin_layout Verbatim
28            SteppermotorClass.o 
\backslash

\end_layout

\begin_layout Verbatim
29            Steppermotor.o 
\backslash

\end_layout

\begin_layout Verbatim
30            SteppermotorStateMachine.o
\end_layout

\begin_layout Verbatim
31 
\end_layout

\begin_layout Verbatim
32 
\end_layout

\begin_layout Verbatim
33 .SUFFIXES: .o .cpp
\end_layout

\begin_layout Verbatim
34 .cpp.o:
\end_layout

\begin_layout Verbatim
35     $(CC) $(CXXFLAGS) -c $<
\end_layout

\begin_layout Verbatim
36 
\end_layout

\begin_layout Verbatim
37 
\end_layout

\begin_layout Verbatim
38 all: StepperMotor
\end_layout

\begin_layout Verbatim
39 
\end_layout

\begin_layout Verbatim
40 StepperMotor: $(SVC_OBJS)
\end_layout

\begin_layout Verbatim
41     $(CC) $(SVC_OBJS) -o $(BIN_DIR)/StepperMotor $(LFLAGS)
\end_layout

\begin_layout Verbatim
42 
\end_layout

\begin_layout Verbatim
43 clean:
\end_layout

\begin_layout Verbatim
44     rm -f *.o core
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard

\end_layout

\begin_layout Standard
Line 5-7 : Define Makefile macros
\end_layout

\begin_layout Standard
Line 9-10 : Set the include file search path
\end_layout

\begin_layout Standard
Line 12 : Set the linker library search path
\end_layout

\begin_layout Standard
Line 15 : The compiler option setting
\end_layout

\begin_layout Standard
Line 16-23 : The linker option setting
\end_layout

\begin_layout Standard
Line 26-30 : All the object files needed to build the executable
\end_layout

\begin_layout Standard
Line 33-35 : Define rules to generate object files
\end_layout

\begin_layout Standard
Line 38 : Define a 
\begin_inset Quotes eld
\end_inset

all
\begin_inset Quotes erd
\end_inset

 dependency
\end_layout

\begin_layout Standard
Line 40-41 : How to generate the StepperMotor device server executable
\end_layout

\begin_layout Standard
Line 43-44 : Define a 
\begin_inset Quotes eld
\end_inset

clean
\begin_inset Quotes erd
\end_inset

 dependency
\end_layout

\begin_layout Subsubsection
On Windows using Visual Studio
\begin_inset CommandInset label
LatexCommand label
name "Compiling NT"

\end_inset


\end_layout

\begin_layout Standard
Supported Windows
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
Windows
\end_layout

\end_inset

 compiler for Tango is Visual Studio 2008 (VC 9), Visual Studio 2010 (VC10)
 and Visual Studio 2013 (VC12).
 Most problems in building a Windows device server revolve around the /M
 compiler switch family.
 This switch family controls which run-time library names are embedded in
 the object files, and consequently which libraries are used during linking
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
linking
\end_layout

\end_inset

.
 Attempt to mix and match compiler settings and libraries can cause link
 error and even if successful, may produce undefined run-time behavior.
\end_layout

\begin_layout Standard
Selecting the correct /M switch in Visual Studio is done through a dialog
 box.
 To open this dialog box, click on the 
\begin_inset Quotes eld
\end_inset

Project
\begin_inset Quotes erd
\end_inset

 menu (once the correct project is selected in the Solution Explorer window)
 and select the 
\begin_inset Quotes eld
\end_inset

Properties
\begin_inset Quotes erd
\end_inset

 option.
 To change the compiler switch open the 
\begin_inset Quotes eld
\end_inset

C/C++
\begin_inset Quotes erd
\end_inset

 tree and select 
\begin_inset Quotes eld
\end_inset

Code Generation
\begin_inset Quotes erd
\end_inset

.
 The following options are supported.
\end_layout

\begin_layout Itemize
Multithreaded = /MT
\end_layout

\begin_layout Itemize
Multithreaded DLL = /MD
\end_layout

\begin_layout Itemize
Debug Multithreaded = /MTd
\end_layout

\begin_layout Itemize
Debug Multithreaded DLL = /MDd
\end_layout

\begin_layout Standard
Compiling a file with a value of the /M switch family will impose at link
 phase the use of libraries also compiled with the same value of the /M
 switch family.
 If you compiled your source code with the /MT option (Multithreaded), you
 must link it with libraries also compiled with the /MT option.
\end_layout

\begin_layout Standard
On both 32 or 64 bits computer, omniORB and TANGO relies on the preprocessor
 identifier 
\series bold
WIN32
\series default

\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
WIN32
\end_layout

\end_inset

 being defined in order to configure itself.
 If you build an application using static libraries (option /MT or /MTd),
 you must add 
\series bold
_WINSTATIC
\series default
 to the list of the preprocessor identifiers.
 If you build an application using DLL
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DLL
\end_layout

\end_inset

 (option /MD or /MDd), you must add 
\series bold
LOG4TANGO_HAS_DLL
\series default
 and 
\series bold
TANGO_HAS_DLL
\series default
 to the list of preprocessor identifiers.
\end_layout

\begin_layout Standard
To build a running device server process, you need to link your code with
 several libraries on top of the Windows libraries.
 These libraries are:
\end_layout

\begin_layout Itemize
The Tango libraries (called 
\series bold
tango.lib
\series default
 and 
\series bold
log4tango.lib
\series default
 or 
\series bold
tangod.lib
\series default
 and 
\series bold
log4tangod.lib
\series default
 for debug mode)
\end_layout

\begin_layout Itemize
The omniORB
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
omniORB
\end_layout

\end_inset

 package libraries (see next table)
\begin_inset Newline newline
\end_inset


\end_layout

\begin_layout Standard
\align center
\begin_inset Tabular
<lyxtabular version="3" rows="7" columns="2">
<features rotate="0" islongtable="true" longtabularalignment="center">
<column alignment="center" valignment="top" width="0pt">
<column alignment="center" valignment="top" width="0pt">
<row>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Compile mode
\end_layout

\end_inset
</cell>
<cell alignment="left" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Libraries
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Debug Multithreaded
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
omniORB4d.lib, omniDynamic4d.lib, omnithreadd.lib and COS4d.lib
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Multithreaded
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
omniORB4.lib, omniDynamic4.lib, omnithread.lib and COS4.lib
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Debug Multithreaded DLL
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
omniORB420_rtd.lib, omniDynamic420_rtd.lib, omnithread40_rtd.lib,
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
and COS420_rtd.lib
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Multithreaded DLL
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
omniORB420_rt.lib, omniDynamic420_rt.lib, omnithread40_rt.lib
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" bottomline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
and COS420_rt.lib
\end_layout

\end_inset
</cell>
</row>
</lyxtabular>

\end_inset


\end_layout

\begin_layout Itemize
The ZMQ library (
\series bold
zmq.lib
\series default
 or 
\series bold
zmqd.lib
\series default
 for debug mode)
\end_layout

\begin_layout Itemize
Windows network libraries (
\series bold
mswsock.lib
\series default
 and 
\series bold
ws2_32.lib
\series default
)
\end_layout

\begin_layout Itemize
Windows graphic library (
\series bold
comctl32.lib
\series default
)
\end_layout

\begin_layout Standard
To add these libraries in Visual Studio, open the project property pages
 dialog box and open the 
\begin_inset Quotes eld
\end_inset

Link
\begin_inset Quotes erd
\end_inset

 tree.
 Select 
\begin_inset Quotes eld
\end_inset

Input
\begin_inset Quotes erd
\end_inset

 and add these library names to the list of library in the 
\begin_inset Quotes eld
\end_inset

Additional Dependencies
\begin_inset Quotes erd
\end_inset

 box.
 
\end_layout

\begin_layout Standard
The 
\begin_inset Quotes eld
\end_inset

Win32 Debug
\begin_inset Quotes erd
\end_inset

 or 
\begin_inset Quotes eld
\end_inset

Win32 Release
\begin_inset Quotes erd
\end_inset

 configuration that you change within the "Configuration Manager" window
 changes the /M switch compiler.
 For instance, if you select a 
\begin_inset Quotes eld
\end_inset

Win32 Debug
\begin_inset Quotes erd
\end_inset

 configuration in a "non-DLL" project, use the omniORB4d.lib, omniDynamic4d.lib
 and omnithreadd.lib libraries plus the tangod.lib, log4tangod.lib and zmqd.lib
 libraries.
 If you select the 
\begin_inset Quotes eld
\end_inset

Win32 Release
\begin_inset Quotes erd
\end_inset

 configuration, use the omniORB4.lib, omniDynamic4.lib and omnithread.lib libraries
 plus the tango.lib, log4tango.lib and zmq.lib libraries.
\end_layout

\begin_layout Standard

\series bold
WARNING
\series default
: In some cases, the Microsoft Visual Studio wizard used during project
 creation generates one include file called 
\emph on
Stdafx.h
\emph default
.
 If this file itself includes windows.h file, you have to add the preprocessor
 macro _WIN32_WINNT
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
-WIN32-WINNT
\end_layout

\end_inset

 and set it to 0x0500.
\end_layout

\begin_layout Subsection
Running a C++ device server
\begin_inset CommandInset label
LatexCommand label
name "Env variable"

\end_inset


\end_layout

\begin_layout Standard
To run a C++ Tango device server, you must set an environment variable.
 This environment variable is called 
\series bold
TANGO_HOST
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
TANGO-HOST
\end_layout

\end_inset


\series default
 and has a fixed syntax which is
\begin_inset ERT
status collapsed

\begin_layout Plain Layout

 
\backslash
begin{center}
\end_layout

\end_inset

TANGO_HOST=<host>:<port>
\begin_inset ERT
status collapsed

\begin_layout Plain Layout


\backslash
end{center}
\end_layout

\end_inset

The host field is the host name where the TANGO database device server is
 running.
 The port field is the port number on which this server is listening.
 For instance, a valid syntax is TANGO_HOST=dumela:10000.
 For UNIX like operating system, setting environment variable is possible
 with the 
\emph on
export
\emph default
 or 
\emph on
setenv
\emph default
 command depending on the shell used.
 For Windows, setting environment variable is possible with the 
\begin_inset Quotes eld
\end_inset

Environment
\begin_inset Quotes erd
\end_inset

 tab of the 
\begin_inset Quotes eld
\end_inset

System
\begin_inset Quotes erd
\end_inset

 application in the control panel.
\end_layout

\begin_layout Standard
If you need to start a Tango device server on a pre-defined port
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
port
\end_layout

\end_inset

 (For Tango database device server or device server without database usage),
 you must use one of the underlying ORB option 
\emph on
endPoint
\emph default
 like 
\begin_inset ERT
status collapsed

\begin_layout Plain Layout


\backslash
begin{center}
\end_layout

\end_inset

myserver myinstance_name -ORBendPoint giop:tcp::<port number>
\begin_inset ERT
status collapsed

\begin_layout Plain Layout


\backslash
end{center}
\end_layout

\end_inset


\end_layout

\begin_layout Section
Advanced programming techniques
\end_layout

\begin_layout Standard
The basic techniques for implementing device server pattern are required
 by each device server programmer.
 In certain situations, it is however necessary to do things out of the
 ordinary.
 This chapter will look into programming techniques which permit the device
 server serve more than simply the network.
\end_layout

\begin_layout Subsection
Receiving signal
\end_layout

\begin_layout Standard
It is 
\series bold
UNSAFE
\series default
 to use any CORBA call in a signal handler.
 It is also UNSAFE to use some system calls in a signal handler.
 Tango device server solved this problem by using threads
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
thread
\end_layout

\end_inset

.
 A specific thread is started to handle signals
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
signal
\end_layout

\end_inset

.
 Therefore, every Tango device server is automatically a threaded process.
 This allows the programmer to write the code which must be executed when
 a signal is received as ordinary code.
 All device server threads masks all signals except the specific signal
 thread which is permanently waiting for signal.
 If a signal is sent to a device server process, only the signal thread
 will receive it because it is the single thread which does not mask signals.
\end_layout

\begin_layout Standard
Nevertheless, signal management is not trivial and some care have to be
 taken.
 The signal management differs from operating system to operating system.
 It is not recommended that you install your own signal routine using any
 of the signal routines provided by the operating system calls or library.
 
\end_layout

\begin_layout Subsubsection
Using signal
\end_layout

\begin_layout Standard
It is possible for C++ device server to receive signals from drivers or
 other processes.
 The TDSOM supports receiving signal at two levels: the device level and
 the class level.
 Supporting signal at the device level means that it is possible to specify
 interest into receiving signal on a device basis.
 This feature is supported via three methods defined in the DeviceImpl
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DeviceImpl
\end_layout

\end_inset

 class.
 These methods are called 
\emph on
register_signal
\emph default
, 
\emph on
unregister_signal
\emph default
 and s
\emph on
ignal_handler
\emph default
.
\end_layout

\begin_layout Standard
The 
\series bold
\emph on
register_signal
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
register-signal
\end_layout

\end_inset


\series default
\emph default
 method has one parameter which is the signal number.
 This method informs the device server signal system that the device want
 to be informed when the signal passed as parameter is received by the process.
 There is a special case for Linux as explained in the previous sub-chapter.
 It is possible to register a signal to be executed in the a signal handler
 context (with all its restrictions).
 This is done with a second parameter to this 
\emph on
register_signal
\emph default
 method.
 This second parameter is simply a boolean data.
 If it is true, the signal_handler will be executed in a signal handler
 context in the device server main thread.
 A default value (false) has been defined for this parameter.
\end_layout

\begin_layout Standard
The 
\series bold
\emph on
unregister_signal
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
unregister-signal
\end_layout

\end_inset


\series default
\emph default
 method also have an input parameter which is the signal number.
 This method removes the device from the list of object which should be
 warned when the signal is received by the process.
\end_layout

\begin_layout Standard
The 
\series bold
\emph on
signal_handler
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
signal-handler
\end_layout

\end_inset


\series default
\emph default
 method is the method which is triggered when a signal is received if the
 corresponding 
\emph on
register_signal
\emph default
 has been executed.
 This method is defined as virtual and can be redefined by the user.
 It has one input argument which is the signal number.
\end_layout

\begin_layout Standard
The same three methods also exist in the DeviceClass
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
DeviceClass
\end_layout

\end_inset

 class.
 Their action and their usage are similar to the DeviceImpl class methods.
 Installing a signal at the class level does not mean that all the device
 belonging to this class will receive the signal.
 This only means that the 
\emph on
signal_handler
\emph default
 method of the DeviceClass instance will be executed.
 This is useful if an action has to be executed once for a class of devices
 when a signal is received.
\end_layout

\begin_layout Standard
The following code is an example with our stepper motor device server configured
 via the database to serve three motors.
 These motors have the following names : id04/motor/01, id04/motor/02 and
 id04/motor/03.
 The signal SIGALRM (alarm signal) must be propagated only to the motor
 number 2 (id04/motor/02)
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
 1  void StepperMotor::init_device()
\end_layout

\begin_layout Verbatim
 2  {
\end_layout

\begin_layout Verbatim
 3      cout << "StepperMotor::StepperMotor() create motor " << dev_name
 << endl;
\end_layout

\begin_layout Verbatim
 4  
\end_layout

\begin_layout Verbatim
 5      long i;
\end_layout

\begin_layout Verbatim
 6  
\end_layout

\begin_layout Verbatim
 7      for (i=0; i< AGSM_MAX_MOTORS; i++)
\end_layout

\begin_layout Verbatim
 8      {
\end_layout

\begin_layout Verbatim
 9          axis[i] = 0;
\end_layout

\begin_layout Verbatim
10          position[i] = 0;
\end_layout

\begin_layout Verbatim
11          direction[i] = 0;
\end_layout

\begin_layout Verbatim
12      }
\end_layout

\begin_layout Verbatim
13  
\end_layout

\begin_layout Verbatim
14      if (dev_name == "id04/motor/02")
\end_layout

\begin_layout Verbatim
15          register_signal(SIGALRM);
\end_layout

\begin_layout Verbatim
16  }
\end_layout

\begin_layout Verbatim
17  
\end_layout

\begin_layout Verbatim
18  StepperMotor::~StepperMotor()
\end_layout

\begin_layout Verbatim
19  {
\end_layout

\begin_layout Verbatim
20      unregister_signal(SIGALRM);
\end_layout

\begin_layout Verbatim
21  }
\end_layout

\begin_layout Verbatim
22  
\end_layout

\begin_layout Verbatim
23  void StepperMotor::signal_handler(long signo)
\end_layout

\begin_layout Verbatim
24  {
\end_layout

\begin_layout Verbatim
25      INFO_STREAM << "Inside signal handler for signal " << signo << endl;
\end_layout

\begin_layout Verbatim
26  
\end_layout

\begin_layout Verbatim
27  //  Do what you want here
\end_layout

\begin_layout Verbatim
28  
\end_layout

\begin_layout Verbatim
29  }
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
The 
\emph on
init_device
\emph default
 method is modified.
\end_layout

\begin_layout Standard
Line 14-15 : The device name is checked and if it is the correct name, the
 device is registered in the list of device wanted to receive the SIGALARM
 signal.
\end_layout

\begin_layout Standard
The destructor is also modified
\end_layout

\begin_layout Standard
Line 20 : Unregister the device from the list of devices which should receives
 the SIGALRM signal.
 Note that unregister a signal for a device which has not previously registered
 its interest for this signal does nothing.
\end_layout

\begin_layout Standard
The 
\emph on
signal_handler
\emph default
 method is redefined
\end_layout

\begin_layout Standard
Line 25 : Print signal number
\end_layout

\begin_layout Standard
Line 27 : Do what you have to do when the signal SIGALRM is received.
\end_layout

\begin_layout Standard
If all devices must be warned when the device server process receives the
 signal SIGALRM, removes line 14 in the 
\emph on
init_device
\emph default
 method.
\end_layout

\begin_layout Subsubsection
Exiting a device server gracefully
\end_layout

\begin_layout Standard
A device server
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
server
\end_layout

\end_inset

 has to exit
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
exit
\end_layout

\end_inset

 gracefully by unregistering itself from the database.
 The necessary action to gracefully exit are automatically executed on reception
 of the following signal
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
signal
\end_layout

\end_inset

 :
\end_layout

\begin_layout Itemize
SIGINT, SIGTERM and SIGQUIT for device server running on Linux
\end_layout

\begin_layout Itemize
SIGINT, SIGTERM, SIGABRT and SIGBREAK for device server running on Windows
\end_layout

\begin_layout Standard
This does not prevents device server to also register interest at device
 or class levels for those signals.
 The user installed 
\emph on
signal_handler
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
signal-handler
\end_layout

\end_inset


\emph default
 method will first be called before the graceful exit.
\end_layout

\begin_layout Subsection
Inheriting
\begin_inset CommandInset label
LatexCommand label
name "Inheriting"

\end_inset


\end_layout

\begin_layout Standard
This sub-chapter details how it is possible to inherit
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
inherit
\end_layout

\end_inset

 from an existing device pattern implementation.
 As the device pattern includes more than a single class, inheriting from
 an existing device pattern needs some explanations.
\end_layout

\begin_layout Standard
Let us suppose that the existing device pattern implementation is for devices
 of class A.
 This means that classes A and AClass already exists plus classes for all
 commands offered by device of class A.
 One new device pattern
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
pattern
\end_layout

\end_inset

 implementation for device of class B must be written with all the features
 offered by class A plus some new one.
 This is easily done with the inheritance.
 Writing a device pattern implementation for device of class B which inherits
 from device of class A means :
\end_layout

\begin_layout Itemize
Write the BClass class
\end_layout

\begin_layout Itemize
Write the B class
\end_layout

\begin_layout Itemize
Write B class specific commands
\end_layout

\begin_layout Itemize
Eventually redefine A class commands
\end_layout

\begin_layout Standard
The miscellaneous code fragments given below detail only what has to be
 updated to support device pattern inheritance
\end_layout

\begin_layout Subsubsection
Writing the BClass
\end_layout

\begin_layout Standard
As you can guess, BClass has to inherit from AClass.
 The 
\emph on
command_factory
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
command-factory
\end_layout

\end_inset


\emph default
 method must also be adapted.
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
     1  namespace B
\end_layout

\begin_layout Verbatim
     2  {
\end_layout

\begin_layout Verbatim
     3  
\end_layout

\begin_layout Verbatim
     4  class BClass : public A::AClass
\end_layout

\begin_layout Verbatim
     5  {
\end_layout

\begin_layout Verbatim
     6  .....
\end_layout

\begin_layout Verbatim
     7  }
\end_layout

\begin_layout Verbatim
     8  
\end_layout

\begin_layout Verbatim
     9  BClass::command_factory()
\end_layout

\begin_layout Verbatim
    10  {
\end_layout

\begin_layout Verbatim
    11      A::AClass::command_factory();
\end_layout

\begin_layout Verbatim
    12  
\end_layout

\begin_layout Verbatim
    13      command_list.push_back(....);
\end_layout

\begin_layout Verbatim
    14  }
\end_layout

\begin_layout Verbatim
    15  
\end_layout

\begin_layout Verbatim
    16  } /* End of B namespace */
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
Line 1 : Open the B namespace
\end_layout

\begin_layout Standard
Line 4 : BClass inherits from AClass which is defined in the A namespace.
\end_layout

\begin_layout Standard
Line 11 : Only the 
\emph on
command_factory
\emph default
 method of the BClass will be called at start-up.
 To create the AClass commands, the 
\emph on
command_factory
\emph default
 method of the AClass must also be executed.
 This is the reason of the line
\end_layout

\begin_layout Standard
Line 13 : Create BClass commands
\end_layout

\begin_layout Subsubsection
Writing the B class
\end_layout

\begin_layout Standard
As you can guess, B has to inherits
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
inherit
\end_layout

\end_inset

 from A.
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
     1  namespace B
\end_layout

\begin_layout Verbatim
     2  {
\end_layout

\begin_layout Verbatim
     3  
\end_layout

\begin_layout Verbatim
     4  class B : public A:A
\end_layout

\begin_layout Verbatim
     5  {
\end_layout

\begin_layout Verbatim
     6     .....
\end_layout

\begin_layout Verbatim
     7  };
\end_layout

\begin_layout Verbatim
     8  
\end_layout

\begin_layout Verbatim
     9  B::B(Tango::DeviceClass *cl,const char *s):A::A(cl,s)
\end_layout

\begin_layout Verbatim
    10  {
\end_layout

\begin_layout Verbatim
    11     ....
\end_layout

\begin_layout Verbatim
    12     init_device();
\end_layout

\begin_layout Verbatim
    13  }
\end_layout

\begin_layout Verbatim
    14  
\end_layout

\begin_layout Verbatim
    15  void B::init_device()
\end_layout

\begin_layout Verbatim
    16  {
\end_layout

\begin_layout Verbatim
    17     ....
\end_layout

\begin_layout Verbatim
    18  }
\end_layout

\begin_layout Verbatim
    19  
\end_layout

\begin_layout Verbatim
    20  } /* End of B namespace */
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
Line 1 : Open the B namespace.
\end_layout

\begin_layout Standard
Line 4 : B inherits from A which is defined in the A namespace
\end_layout

\begin_layout Standard
Line 9 : The B constructor calls the right A constructor
\end_layout

\begin_layout Subsubsection
Writing B class specific command
\end_layout

\begin_layout Standard
Noting special here.
 Write these classes as usual
\end_layout

\begin_layout Subsubsection
Redefining A class command
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
command
\end_layout

\end_inset


\end_layout

\begin_layout Standard
It is possible to redefine a command which already exist in class A 
\series bold
only if the command is created
\series default
 
\series bold
using the inheritance
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
inheritance
\end_layout

\end_inset

 model
\series default
 (but keeping its input and output argument types).
 The method which really execute the class A command is a method implemented
 in the A class.
 This method must be defined as 
\series bold
virtual.

\series default
 In class B, you can redefine the method executing the command and implement
 it following the needs of the B class.
\end_layout

\begin_layout Standard

\end_layout

\begin_layout Subsection
Using another device pattern implementation within the same server
\end_layout

\begin_layout Standard
It is often necessary that inside the same device server
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
server
\end_layout

\end_inset

, a method executing a command needs a command of another class to be executed.
 For instance, a device pattern implementation for a device driven by a
 serial line class can use the command offered by a serial line class embedded
 within the same device server process.
 To execute one of the command (or any other CORBA
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
CORBA
\end_layout

\end_inset

 operations/attributes) of the serial line class, just call it as a normal
 client will do by using one instance of the DeviceProxy class
\emph on
.

\emph default
 The ORB will recognize that all the devices are inside the same process
 and will execute calls as a local
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
local
\end_layout

\end_inset

 calls.
 To create the DeviceProxy class instance, the only thing you need to know
 is the name of the device you gave to the serial line device.
 Retrieving this could be easily done by a Tango device property.
 The DeviceProxy class is fully described in Tango Application Programming
 Interface (API) reference WEB pages
\end_layout

\begin_layout Subsection
Device pipe
\begin_inset Index idx
status open

\begin_layout Plain Layout
pipe
\end_layout

\end_inset


\end_layout

\begin_layout Standard
What a Tango device pipe is has been defined in the Chapter 3 about device
 server model.
 How you read or write a pipe in a client software is documented in chapter
 4 about the Tango API.
 In this section, we describe how you can read/write into/from a device
 pipe on the server side (In a Tango class with pipe).
\end_layout

\begin_layout Subsubsection
Client reading a pipe
\end_layout

\begin_layout Standard
When a client reads a pipe, the following methods are executed in the Tango
 class:
\end_layout

\begin_layout Enumerate
The 
\emph on
always_executed_hook()
\emph default
 method.
\end_layout

\begin_layout Enumerate
A method called 
\emph on
is_<pipe_name>_allowed()
\emph default
.
 The rule of this method is to allow (or disallow) the next method to be
 executed.
 It is usefull for device with some pipes which can be read only in some
 precise conditions.
 It has one parameter which is the request type (read or write)
\end_layout

\begin_layout Enumerate
A method called 
\emph on
read_<pipe_name>()
\emph default
.
 The aim of this method is to store the pipe data in the pipe object.
 It has one parameter which is a reference to the Pipe object to be read.
\end_layout

\begin_layout Standard
The figure 
\begin_inset CommandInset ref
LatexCommand ref
reference "r_pipe_timing_fig-1"

\end_inset

 is a drawing of these method calls sequencing for our class StepperMotor
 with one pipe named DynData.
\begin_inset Float figure
placement H
wide false
sideways false
status collapsed

\begin_layout Plain Layout
\align center
\begin_inset Graphics
	filename r_pipe.eps
	scale 70

\end_inset


\end_layout

\begin_layout Plain Layout
\begin_inset Caption Standard

\begin_layout Plain Layout
Read pipe sequencing
\begin_inset CommandInset label
LatexCommand label
name "r_pipe_timing_fig-1"

\end_inset


\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
The class DynDataPipe is a simple class which follow the same skeleton from
 one Tango class to another.
 Therefore, this class is generated by the Tango code generator Pogo and
 the Tango class developper does not have to modify it.
 The method 
\emph on
is_DynData_allowed()
\emph default
 is relatively simple and in most cases the default code generated by Pogo
 is enough.
 The method 
\emph on
read_DynData()
\emph default
 is the method on which the Tango class developper has to concentrate on.
 The following code is one example of these two methods.
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
     1  bool StepperMotor::is_DynData_allowed(Tango::PipeReqType req)
\end_layout

\begin_layout Verbatim
     2  {
\end_layout

\begin_layout Verbatim
     3      if (get_state() == Tango::ON)
\end_layout

\begin_layout Verbatim
     4          return true;
\end_layout

\begin_layout Verbatim
     5      else
\end_layout

\begin_layout Verbatim
     6          return false;
\end_layout

\begin_layout Verbatim
     7  }
\end_layout

\begin_layout Verbatim
     8
\end_layout

\begin_layout Verbatim
     9  void StepperMotor::read_DynData(Tango::Pipe &pipe)
\end_layout

\begin_layout Verbatim
    10  {
\end_layout

\begin_layout Verbatim
    11      nb_call++;
\end_layout

\begin_layout Verbatim
    12      if (nb_call % 2 == 0)
\end_layout

\begin_layout Verbatim
    13      {
\end_layout

\begin_layout Verbatim
    14          pipe.set_root_blob_name(
\begin_inset Quotes eld
\end_inset

BlobCaseEven
\begin_inset Quotes erd
\end_inset

);
\end_layout

\begin_layout Verbatim
    15
\end_layout

\begin_layout Verbatim
    16          vector<string> de_names {
\begin_inset Quotes erd
\end_inset

EvenFirstDE
\begin_inset Quotes erd
\end_inset

,
\begin_inset Quotes erd
\end_inset

EvenSecondDE
\begin_inset Quotes erd
\end_inset

};
\end_layout

\begin_layout Verbatim
    17          pipe.set_data_elt_names(de_names);
\end_layout

\begin_layout Verbatim
    18
\end_layout

\begin_layout Verbatim
    19          dl = 666;
\end_layout

\begin_layout Verbatim
    20          v_db.clear();
\end_layout

\begin_layout Verbatim
    21          v_db.push_back(1.11);
\end_layout

\begin_layout Verbatim
    22          v_db.push_back(2.22);
\end_layout

\begin_layout Verbatim
    23
\end_layout

\begin_layout Verbatim
    24          pipe << dl << v_db;
\end_layout

\begin_layout Verbatim
    25      }
\end_layout

\begin_layout Verbatim
    26      else
\end_layout

\begin_layout Verbatim
    27      {
\end_layout

\begin_layout Verbatim
    28          pipe.set_root_blob_name(
\begin_inset Quotes eld
\end_inset

BlobCaseOdd
\begin_inset Quotes erd
\end_inset

);
\end_layout

\begin_layout Verbatim
    29
\end_layout

\begin_layout Verbatim
    30          vector<string> de_names {
\begin_inset Quotes erd
\end_inset

OddFirstDE
\begin_inset Quotes erd
\end_inset

};
\end_layout

\begin_layout Verbatim
    31          pipe.set_data_elt_names(de_names);
\end_layout

\begin_layout Verbatim
    32
\end_layout

\begin_layout Verbatim
    33          v_str.clear();
\end_layout

\begin_layout Verbatim
    34          v_str.push_back(
\begin_inset Quotes eld
\end_inset

Hola
\begin_inset Quotes erd
\end_inset

);
\end_layout

\begin_layout Verbatim
    35          v_str.push_back(
\begin_inset Quotes eld
\end_inset

Salut
\begin_inset Quotes erd
\end_inset

);
\end_layout

\begin_layout Verbatim
    36          v_str.push_back(
\begin_inset Quotes eld
\end_inset

Hi
\begin_inset Quotes erd
\end_inset

);
\end_layout

\begin_layout Verbatim
    37
\end_layout

\begin_layout Verbatim
    38          pipe << v_str;
\end_layout

\begin_layout Verbatim
    39      }
\end_layout

\begin_layout Verbatim
    40  }
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
The 
\emph on
is_DynData_allowed
\emph default
 method is defined between lines 1 and 7.
 It is allowed to read or write the pipe only is the device state is ON.
 Note that the input parameter req is not used.
 The parameter allows the user to know the type of request.
 The data type PipeReqType is one enumeration with two possible values which
 are READ_REQ and WRITE_REQ.
\end_layout

\begin_layout Standard
The 
\emph on
read_DynData
\emph default
 method is defined between lines 9 and 40.
 If the number of times this method has been called is even, the pipe contains
 two data elements.
 The first one is named EvenFirstDE and its data is a long.
 The second one is named EvenSecondDE and its data is an array of double.
 If the number of call is odd, the pipe contains only one data element.
 Its name is OddFirstDe and its data is an array of strings.
 Data are inserted into the pipe at lines 24 and 38.
 The variables nb_call, dl, v_db and v_str are device data member and therefore
 declare in the .h file.
 Refer to pipe section in chapter 3 and to the API reference documentation
 (in Tango WEB pages) to learn more on how you can insert data into a pipe
 and to know how data are organized within a pipe.
\end_layout

\begin_layout Subsubsection
Client writing a pipe
\end_layout

\begin_layout Standard
When a client writes a pipe, the following methods are executed in the Tango
 class:
\end_layout

\begin_layout Enumerate
The 
\emph on
always_executed_hook()
\emph default
 method.
\end_layout

\begin_layout Enumerate
A method called 
\emph on
is_<pipe_name>_allowed()
\emph default
.
 The rule of this method is to allow (or disallow) the next method to be
 executed.
 It is usefull for device with some pipes which can be read only in some
 precise conditions.
 It has one parameter which is the request type (read or write)
\end_layout

\begin_layout Enumerate
A method called 
\emph on
write_<pipe_name>()
\emph default
.
 It has one parameter which is a reference to the WPipe object to be written.
 The aim of this method is to get the data to be written from the WPipe
 oject and to write them into the corresponding Tango class objects.
\end_layout

\begin_layout Standard
The figure 
\begin_inset CommandInset ref
LatexCommand ref
reference "w_pipe_timing_fig-1-1"

\end_inset

 is a drawing of these method calls sequencing for our class StepperMotor
 with one pipe named DynData.
\begin_inset Float figure
placement H
wide false
sideways false
status collapsed

\begin_layout Plain Layout
\align center
\begin_inset Graphics
	filename w_pipe.eps
	scale 70

\end_inset


\end_layout

\begin_layout Plain Layout
\begin_inset Caption Standard

\begin_layout Plain Layout
Write pipe sequencing
\begin_inset CommandInset label
LatexCommand label
name "w_pipe_timing_fig-1-1"

\end_inset


\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
The class DynDataPipe is a simple class which follow the same skeleton from
 one Tango class to another.
 Therefore, this class is generated by the Tango code generator Pogo and
 the Tango class developper does not have to modify it.
 The method 
\emph on
is_DynData_allowed()
\emph default
 is relatively simple and in most cases the default code generated by Pogo
 is enough.
 The method 
\emph on
write_DynData()
\emph default
 is the method on which the Tango class developper has to concentrate on.
 The following code is one example of the 
\emph on
write_DynData()
\emph default
 method.
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Verbatim
     1  void StepperMotor::write_DynData(Tango::WPipe &w_pipe)
\end_layout

\begin_layout Verbatim
     2  {
\end_layout

\begin_layout Verbatim
     3     string str;
\end_layout

\begin_layout Verbatim
     4     vector<float> v_fl;
\end_layout

\begin_layout Verbatim
     5
\end_layout

\begin_layout Verbatim
     6     w_pipe >> str >> v_fl;
\end_layout

\begin_layout Verbatim
     7     .....
\end_layout

\begin_layout Verbatim
     8  }
\end_layout

\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "line.tex"

\end_inset


\end_layout

\begin_layout Standard
In this example, we know that the pipe will always contain a srting followed
 by one array of float.
 On top of that, we are not niterested by the
\end_layout

\begin_layout Standard
data element names.
 Data are extracted from the pipe at line 6 and are available for further
 use starting at line 7.
 If the content of the pipe is not a string followed by one array of float,
 the data extraction line (6) will throw one exception which will be reported
 to the client who has tried to write the pipe.
 Refer to pipe section in chapter 3 and to the API reference documentation
 (in Tango WEB pages) to learn more on how you can insert data into a pipe
 and to know how data are organized within a pipe.
\end_layout

\begin_layout Standard
\begin_inset VSpace bigskip
\end_inset


\end_layout

\begin_layout Standard
\begin_inset ERT
status open

\begin_layout Plain Layout


\backslash
begin{center}
\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset CommandInset label
LatexCommand label
name "BlackPicture"

\end_inset


\begin_inset Graphics
	filename ../dance/tango-08-39.jpg
	lyxscale 60
	scale 60

\end_inset


\end_layout

\begin_layout Standard
\begin_inset ERT
status open

\begin_layout Plain Layout


\backslash
end{center}
\end_layout

\end_inset


\end_layout

\end_body
\end_document
