Documentation:Tutorial:APIs:LabVIEW

From MdsWiki

(Difference between revisions)

Revision as of 16:02, 12 September 2012

1 The LabVIEW interface to MDSplus objects
2 Installation
3 Data classes
4 Tree Classes
5 Data and Tree instances deallocation
6 Event Classes

The LabVIEW interface to MDSplus objects

This new LabVIEW interface uses the recent LabVIEW Object Oriented interface called LVOOP. In LVOOP class methods are represented by Virtual Instruments (VIs) named Class Member VIs. The MDSplus interface provides a one-to-one mapping between MDSplus Data and Tree objects and the LabVIEW classes and we shall see how, thanks to the graphical interface of LabVIEW, this mapping become intuitive and easy to export the full functionality of MDSplus into LabVIEW. After an introduction of the basic concepts, this tutorial will explain the usage of this interface by means of some example, covering the most common use cases of MDSplus.

Installation

NOTE: the following installation steps refer to Windows version of LabVIEW 2010. Different platforms and version may require slightly different steps.
The LabVIEW interface is installed from the CVS distribution of MDSplus in the following steps:

Make sure that the latest version of MDSplus is installed, in particular that library MDSobjectsLVShr.dll is present;
From the CVS MDSplus distribution copy the whole directory <MDSplus root>\mdsobjects\labview\MDSplus into directory <LabVIEW root>\vi.lib;
From LabVIEW, open project <LabVIEW root>\vi.lib\MDSplus\MDSplus.lvproj

When the project is open, the following window is shown:

The folder Sample and utility VIs contains the examples which will be covered in this tutorial. MDSplus.lvlib contains the classes and the methods of the ionterface, which are further divided into folders Data (Data classes), Event (Event classes) Tree (Tree classes) and TreeNodeArray (still in development, not covered in this tutorial).
If we expand for example the Data folder the following is shown:

The displayed VIs represent the VIs to be used when manipulating Data objects. Data derived classes are stored in the shown subfolders (Array, Scalar, Compound, TreeNode). The direct class member VIs are contained in Data.lvclass, but it is recommended that users use the VIs outside the <Class name>.lvclass folder. See the following figure referring to Data class Int32.

The reason for using the library VIs instead of the class member VIs is subtle but nevertheless important: when using library VIs for MDSplus class methods the object instances are not passed directly, but a reference to the object is used instead. Even if this is transparent to the programmer, in the latter case possible deallocation errors (see deallocation section below) are trapped by LabVIEW and do not crash the application.
Class library VIs can be dragged directly from the project window, but a palette is also available. The following steps are required to install the palette:

Select Tool->Advanced->Edit Palette Set...
Within the shown window, select the popup menu Insert->Subpalette and select "Link to an existing palette file (.mnu)" option
Select <LabVIEW root>\vi.lib\MDSplus\MDSplus.mnu

Data classes

Most MDSplus class inherit from the Data class. MDSplus handles a large variety of data types, including scalars and multidimensional arrays, and other data types derive from the composition of data instances.
This flexible data management fits naturally into the Data class hierarchy. Every data item managed by MDSplus is seen as a generic instance of Data, its actual representation being carried out by the concrete Data subclass. This subclass may be as simple as a scalar 4-byte integer value represented by the Int32 class, or as complex as an expression representation formed to a hierarchy of data instances corresponding to the expression parse tree.
The Data superclass defines a set of generic methods for data evaluation which are then implemented by its subclasses. For example, Data method getInt() returning a C int type, will return the associated integer field for a Int32 class, and will imply the online evaluation of the associated expression for not atomic data classes. For the simplest data types, corresponding to scalars and arrays, the actual value of the data instance is typically passed as an argument to the class’ constructor.
The creation of a new Data instance in LabVIEW is quite similar. For example, the constructor VI of the following figure creates a new instance of the Float32 data type, representing a single precision floating point number. The VI has an input wire for the assigned numeric value and the created Data instance is returned in the output wire on the right. Another output wire brings error information, following the usual error management approach of LabVIEW.

Accessor (getter) methods allow retrieving the associated value from a Data instance. In the following figure the getFloat VI returns the content of the passed Data instance as a single precision floating point number. The input wires are the references to the Data object and the error stream, respectively. The output wires are the same reference to the Data instance, the returned value and the output error stream, respectively.

Composite Data instances are created in LabVIEW from the data instances of their components. For example, a Signal Data instance can be created from two Float32Array Data instances representing the Signal values and times, respectively. The two Float32Array instances are connected to the Signal Constructor VI via the input wires and the Signal instance is returned in the output wire.

Tree Classes

Class Tree represents an instance of pulse file, which is open when the class is instantiated. Class Tree is not used directly to read and write data, but TreeNode instances can be obtained from the Tree instance, each representing a given data item in the pulse file hierarchy, and used to read and write data.
Every TreeNode may contain a data expression, and TreeNode’s methods getData() and putData() will read and write instances of Data objects, represented by any Data derived class instance.
The usage of Tree and TreeNode LabVIEW objects is shown in the example below.

A Tree instance is first created by the Tree constructor VI, whose input wires specify the name and the shot number of the corresponding pulse file, and whose output wires bring the created Tree instance and the error stream. The Tree instance is the input wire of the TreeNode constructor VI, which accepts also as input the path name of the corresponding data item in the pulse file hierarchy. The output wire bringing the TreeNode instance is then used (from left to right) to write a float scalar and to read it back. A Data input wire for the putData VI specifies the data item to be written in the pulse file, and a data wire is returned by getData VI which reads the data item corresponding to the passed TreeNode instance. Finally, Data accessor getFloatValue VI is used to retrieve the data content as a float value.
The Data instance is then deallocated as well as the Tree and TreeNode instances. Refer to the following section for a more detailed discussion.

Data and Tree instances deallocation

In LabVIEW memory resources are automatically freed when no more needed, and deallocation is therefore not controlled by the user program. It is however not possible to delegate memory resource allocation control in the MDSplus object layer because here memory is not only allocated by LabVIEW, but also by the underlying C++ library. For this reason a set of deallocator VIs is available and should be used to avoid memory leaks.
Tree and TreeNode instances should be deallocated when no more needed, as well as every Data instance. In practice, freeing every Data object would complicate programming quite a bit. For this reason, deallocations are carried ou by the MDSplus method VIs when Data objects are received as input.
The programmer’s rules becomes therefore the following:

Tree and TreeNodes instances are deallocated when no more required in the program;
Data objects returned by accessor (getter) methods of other Data objects are not deallocated (e.g. the returned dimension of a Signal Data object);
Data objects created in the program or returned by TreeNode methods should be deallocated when no more used ONLY when NOT passed to any other VI.

The above example shows a correct deallocation policy where Float32 Data objects passed to putData VI are not explicitly deallocated. Conversely, the Data object returned by getData VI is deallocated when no more used, i.e. after extracting its associated float value. Tree and TreeNode are deallocated in the program when no more needed, i.e. when the pulse file, is closed.

Event Classes

MDSplus events are based on UDP messages (recall that env variable UDP_EVENTS must be set to 1) and are used to synchronize separate components in data acquisition systems. An event is uniquely identified by its name and can bring any Data instance whose byte size is not greater than a UDP datagram (64 kBytes).
Event management is carried out by class Event, whose constructor requires the name of the event. Event Wait VI suspends the execution of the calling thread until an event with the corresponding name is generated. Event Wait Data VI, in addition, returns the Data instance associated with the event (if any). Static method VI Event Set Event (i.e. not necessarily requiring an Event instance) will issue an event corresponding to the name. Method VI Event Set Event(Data) accepts also the Data instance to be passed along with the event.

In the following example an Event object is created (Event Creator) and the returned instance is used to wait the corresponding event and the associated data, which is then displayed converted to a float value.

The generation of an Event with associated data is shown below. Here, an instance of Int32 Data is passed to the Set Event VI. Observe that since Set Event is a static method there is no need to create an Event instance before.

Retrieved from "https://www.mdsplus.org/index.php/Documentation:Tutorial:APIs:LabVIEW"

 Event management is carried out by class ''Event'', whose constructor requires the name of the event. ''Event Wait'' VI  suspends the execution of the calling thread until an event with the corresponding name is generated. ''Event Wait Data'' VI, in addition, returns the Data instance associated with the event (if any). Static method VI Event Set Event (i.e. not necessarily requiring an Event instance) will issue an event corresponding to the name. Method VI ''Event Set Event(Data)'' accepts also the Data instance to be passed along with the event.<br /><br />
 In the following example an Event object is created (Event Creator) and the returned instance is used to wait the corresponding event and the associated data, which is then displayed converted to a float value.<br />
-[[Image:LabVIEW_Fig8.jpg]]<br />
+[[Image:LabVIEW_Fig8.gif]]<br />
 The generation of an Event with associated data is shown below. Here, an instance of Int32 Data is passed to the Set Event VI. Observe that since Set Event is a static method there is no need to create an  Event instance before.<br />
-[[Image:LabVIEW_Fig9.jpg]]<br />
+[[Image:LabVIEW_Fig9.gif]]<br />

Navigation

Search

Personal tools