What is new in version 3.02=

This document describes the changes in software betw= een versions 3.01 and 3.02.

In-process COM component supplied, and related changes

In earlier versions, EasyOPC-DA shipped as “local server” COM component only, which (in short) means that its objects were primarily intended to be used as out-of-process= COM objects. In the new version, the existing local server component is preserv= ed, and a new in-process server component is installed as well. Both server typ= es are registered with COM after fresh installation.

In the EasyOPC-DA Options = utility, there is a new “COM registration” tab that you can use to influ= ence how the component is registered.

COM clients can specify which server types they acce= pt (although usually they accept ALL types of clients). COM then chooses a type that is allowed by the client and registered by the server. If this process= in no usable server type, an object instantiation fails. If the process result= s in multiple usable server types, COM will make its own choice in selecting the server type. Usually, in-process server is preferably chosen by COM over the local server in such a case.

When in-process server is used, following differences should be considered as compared to the local server:

-&nb= sp; Function calls to (and callbacks from) the in-proce= ss server are much faster, because there is no associated switch of process contexts, and inter-process marshalling of data.

-&nb= sp; The in-process server has access to the memory of t= he owning process, which has implications on robustness (the component can cra= sh the client application and vice versa) and security (sensitive information = in the client application is acecssible to the com= ponent and vice versa).

-&nb= sp; There is no separate EasyOPC-DA process when in-process server is used. The component runs under the process that loaded it. The COM/DCOM security configuration has to be different (usually simpler, but not always).

-&nb= sp; When multiple client applications are run in separa= te processes, each client application will use its own instance of EasyOPC-DA “engine”. The advantage is tha= t this situation provides certain level of “isolation” between the cli= ent applications. The disadvantagee is that it effectively disables certain optimization and aggregation functions perform= ed by EasyOPC-DA. Consequently, when multiple clie= nt applications are run, the resulting demand on target OPC server(s) will be higher (each client application will make its own connections to the OPC servers).

Note that in .NET, multiple app= domains can run in single Windows process (although this is not typically the case = with simple WinForms applications). In-process serve= r is loaded just once into any Windows process. In this version, for internal implementation reasons, we do not recommend sharing the EasyOPC-DA in-process server across multiple .NET appdomains.

Introduced SubscribeServer/UnsubscribeServer and SubscribeItem/UnsubscribeItem methods

These methods provide simplified way of subscribing = to OPC servers and OPC items, with following advantages:

-&nb= sp; You can hook your event handlers just to the main EasyDA3 object. When you do it properly, before you subscribe, the EasyDA3 object is guaranteed to immediately start receiving all relevant notificati= ons.

-&nb= sp; When you subscribe, you do not need to store the returned object in order to keep the subscription alive. The subscription remains alive until you explicitly unsubscribe, or until the parent EasyDA3 object is destroyed.

The syntax is:

-&nb= sp; Server =3D EasyDA3.SubscribeServer(MachineName, ServerClass, Tag, Mode)

-&nb= sp; Item =3D EasyDA3.SubscribeServer(MachineName, ServerClass, ItemID= , AccessPath, DataType, Tag= , Mode)

-&nb= sp; UnsubscribeServer MachineName, ServerClass,= Tag, Mode

-&nb= sp; UnsubscribeItem MachineName, ServerClass,= ItemID, AccessPath, DataType, Tag, Mode

= ;

The arguments to EasyDA3.SubscribeServer are the sam= e as to EasyDA3.RequestServer method, and the arguments to EasyDA3.SubscribeItem= are the same as to EasyDA3.RequestItem (these methods have existed in earlier versions already). The methods return a Server or Item object, but you do n= ot keep reference to it. In fact, in most cases you can ignore the returned ob= ject altogether. The subscribed Server or Item object is kept internally in the EasyDA3 object, and it is passed to you when event notifications for the subscribed OPC server or OPC item are generated.

For the same combination of OPC server or OPC item identification parameters, it is not possible to subscribe more than once (= on the same easyDA3 object).

To unsubscribe, you call the EasyDA3.UnsubscribeServ= er or EasyDA3.UnsubscribeItem, giving it the same identification parameters as in= the related call that you used to subscribe. An error will be return if you att= empt to unsubscribe an OPC server or OPC item that is not subscribed.

Note that you should NOT hook events to Server or It= em objects returned by the SubscribeServer or SubscribeItem methods. Not only that the component= 217;s behavior is undefined if you do that, but also you lose the chance to catch= all events since the beginning of object’s lifetime, as they are generate= d, and as a result it is not guaranteed that your application will receive all data. Hook your event handlers to the main EasyDA3 object when you use SubscribeServer or SubscribeItem= .

Introduced UnsubscribeAllServers and UnsubscribeAllItems methods

You can unsubscribe all OPC servers (subscribed by EasyDA3.SubscribeServer calls) at once by calling EasyDA3.UnsubscribeAllServers. This is equivalent to repeatedly calling EasyDA3.UnsubscribeServer for all subscribed servers.

You can unsubscribe all OPC items (subscribed by EasyDA3.SubscribeItem calls) at once by calling EasyDA3.UnsubscribeAllItems. This is equivalent to repeatedly calling EasyDA3.UnsubscribeItem for all subscribed items.

Introduced FindSubscribedServer and FindSubscribedItem methods

These methods allow you to retrieve a Server or Item o= bject for an OPC server or OPC item that has been subscribed before. The methods = can be useful e.g. if you need to change the RequestedUpda= teRate property of any subscribed item.

Changed argument order in RequestServer and= RequestItem

In EasyDA3.RequestServer and Re= questItem methods, the order of Tag and Mode arguments is switched in the new version. Now, Mode is the last input argument. This change was done so that Mode can= be the last input argument in all methods that use it, for consistency.

RequestServer and Requ= estItem always provide new instance of the Server or Item object

In earlier versions, if you specified precisely the = same identification data for the OPC server or item, the EasyDA3.RequestServer o= r RequestItem method returned a reference to previously created Server or Item object. In the new version, EasyDA3.RequestServer an= d RequestItem methods always return a new instance of S= erver or Item object, make the behavior more predictable.

Objects returned by RequestServer and RequestItem do not fire events on “main” EasyDA3 object

In version 3.01, when you created a Server or an Ite= m object by calling EasyDA3.RequestServer or EasyDA3.RequestItem object, the events related to the OPC server or item were fired BOTH on the Server or Item obj= ect AND on the main EasyDA3 object, as long as the Item or Server object was not destroyed. In this new version, Item and Server objects created by EasyDA3.RequestServer or EasyDA3.RequestItem only fire events on themselves, and NOT on the main EasyDA3 object. If you want to work with events on main EasyDA3 object, use the new EasyDA3.SubscribeServer/UnsubscribeServer or SubscribeItem/UnsubscribeItem methods.

Note that, however, the “parent” EasyDA3 object must be kept referenced in your application as long as you want to receive events on Server or Item objects it created.

RequestServer and Requ= estItem do not automatically attach (or connect) to the underlying OPC object

In earlier versions, EasyDA3.RequestServer and RequestItem methods created a Server or Item object a= nd immediately attempted to connect to underlying OPC server or item. As a res= ult, it was difficult to assure that the client application receives all necessa= ry data, because at the moment the client application was given a chance to “hook” event handlers to an object, there may have been events fired that could not be sent anywhere.

The new version clearly distinguishes several states= of Item and Server objects, and separates the transitions between them, allowi= ng the client application to hook the event handlers at proper time and control the behavior at finer level.

-&nb= sp; Initially (after a RequestServ= er or RequestItem call), the Server or Item object= is in Detached state. In the Detached state, it has no communication to underlying physical OPC server or item, and it does not fire any events. In this state, the Server or an Item is a mere descriptor for the OPC server or item. Note that the fact that the object is in Detached sta= te does not ALWAYS imply that the EasyOPC-DA compo= nent will not communicate with the physical OPC server or item – that would only be the case if other conditions are fulfilled.

-&nb= sp; A Server or an Item object can be turned into Attac= hed state. In the Attached state, it is able to fire events, and can communicate with underlying OPC server or item. Note that being in an Attached state do= es not mean that the object MUST actively communicate with it: depending on the circumstances, it can be Connected or Disconnect= ed, as you will see later. Turning an object into an Attached state fires initial events on the object, guaranteeing that the client application will receive= all necessary data.

-&nb= sp; When the Server or Item is in an Attached state, it= can be Connected or Disconnected. These states reflect the real physical connec= tion to underlying OPC server item. For an OPC server to be considered connected, several conditions must be fulfilled, including: a corresponding OPCServer object must be successfully instantiated, i= t must support the necessary interfaces, the server must properly respond IOPCServer::GetStatus calls, and the returned status = must not be OPC_STATUS_FAILED. For an OPC item to be considered connected, its O= PC server must be connected first, a necessary OPCGroup object must be successfully added to the server, and corresponding OPCItem must be successfully added to the group.

Transitions between Attached and Detached state are = quick and have immediate effect. Certain methods or properties are only meaningfu= l in an Attached state, and the component returns error if the object is not attached when needed. In most cases you do not need to worry about attaching the object, as there is an auto-attach feature, controlled by the AutoAttach property (see further below).

Below is an illustrative, recommended sequence of st= eps that the client application should take in order to start and stop receiving events for an OPC item:

<= ![if !supportLists]>1.&n= bsp; Instantiate EasyDA3 object.

<= ![if !supportLists]>2.&n= bsp; Call EasyDA3.RequestItem method.

<= ![if !supportLists]>3.&n= bsp; Hook event handlers to the returned Item object.

<= ![if !supportLists]>4.&n= bsp; Call Item.Connect metho= d (see further below). In many cases, this call is the only difference to the code that was designed to work with earlier versions.

<= ![if !supportLists]>5.&n= bsp; The events will now fired and handled

<= ![if !supportLists]>6.&n= bsp; In .NET, call Item.Detach method (see further below). In COM, simply release the reference to the Item object.

Added Attached property to Server and Item objects

The Server.Attached and = Item.Attached properties return a Boolean value indic= ating whether the object is attached (True) or detached (False).

Ability to explicitly attach or detach to OPC servers and items – Attach and Detach methods

You can explicitly attach a Server or Item object by calling Server.Attach or I= tem.Attach method, and you can explicitly detach a Server or Item object by calling Server.Detach or Item.Detach method.

In most situations, you will not need to use this fe= ature, as by default, the AutoAttach property is set t= o True (see further below), and the Item and Server object will be automatically attached when the first OPC-operating method (such as Connect) is called. A= lso note that Item and Server objects created by the EasyDA3.SubscribeServer and EasyDA3.SubscribeItem methods cannot be attached or detached by the client application. These objects are automatically attached when they are subscri= bed, and detached when they are unsubscribed.

Auto-attachment, and AutoAttach property of Server and Item objects

The auto-attachment feature saves coding by automati= cally attaching a Server or Item object when a method that operates on physical O= PC server or item is called. Auto-attachment can be enabled or disabled for ev= ery Server and Item object by settings its AutoAttach property. By default, auto-attachment is enabled. This means that first OPC-operating method such as Server.Connect, Item.Connect or Item.Read= will also automatically attach the Server or Item object. Your code can therefore simply “request” the Server or Item and then operate on it, wit= hout actually calling Server.Attach or Item.Attach.

Auto-attachment (when enabled) is performed with fol= lowing methods:

-&nb= sp; Server.GetServerStatus,= Server.Connect, Server.Disconnec= t

-&nb= sp; Item.Read, Item.ReadValue, Item.WriteValue<= /span>, Item.InvokeRead, Item.InvokeRead= Value, Item.InvokeWriteValue, Ite= m.Connect, Item.Disconnect

Added Connect and Disconnect methods to Server and Item objects

Calling Server.Connect i= nstructs the component to attempt to connect to the physical OPC server. The method = is asynchronous with respect to the caller: The connection operation may be finished at some future point.

Calling Server.Disconnect instructs the component to attempt to disconnect from the physical OPC serv= er. The method is asynchronous with respect to the caller: The disconnection operation may be finished at some future point.

Calling Item.Connect ins= tructs the component to attempt to connect to the physical OPC item (includes connection to its OPC server first). The method is asynchronous with respec= t to the caller: The connection operation may be finished at some future point. = OPC items are kept connected by default as long as their corresponding OPC serv= er is connected, so you should have no need to call this method. It is provide= d for future expansion.

Item.Disconnect method is (besides some error checking and housekeeping) currently an empty operation (does not have any real effect). This method is provided for future expansi= on and will be fully implemented in future.

Be aware that EasyOPC-DA component can use the same physical connection for multiple Server and Item objects and for its internal use, and calling Connect or Disconnect on one object may also affect the connection status of other objects and the outco= me of EasyDA3.ReadItem, ReadItemValue and WriteItemValue calls. It is the programmer’s responsibility to use the Connect and Disconnect methods in a way that would not cause unwanted interference. One solution to this is the use of isolated OPC objects (described further down in this document). Note that future versions of the component may impose some (configurable) administrative lim= its to usage or behavior of Connect and Disconnect methods, especially on non-isolated objects.

Deterministic finalization in .NET

In earlier versions, the client application indicate= d that it is finished with a Server or Item object (returned by EasyDA3.RequestSer= ver or RequestItem method) by releasing all referen= ces to it. This was easy and straightforward to do in COM, but could cause problem= s in .NET, as the programmer does not have full control over object finalization= .

In the new version, two features were added to addre= ss this issue:

· For objects obtained via EasyAD3.RequestServ= er or RequestItem, you can call Server.Detach or Item.Detach. This will effectively tell EasyOPC-DA that you are done with the object.

· You can replace your use of EasyDA3.RequestServer and RequestItem with new methods, EasyDA3.SubscribeServer/UnsubscribeServer and SubscribeItem/UnsubscribeItem. In most cases your code will become cleaner, and you will not have to deal = with Server or Item objects at all. You will call the Unsub= scribeServer or UnsubscribeItem method to tell EasyOPC-DA that you are done with the server or item.

Added Read, ReadValue, WriteValue methods to Item object

It is now possible to perform OPC read and write operations directly on the Item object that you have previously obtained us= ing EasyDA3.RequestItem. If you have the Item object, the coding becomes much shorter as the methods require much less input arguments.

The syntax is:

-&nb= sp; VTQ =3D Item.Read(Mode)=

-&nb= sp; Value =3D Item.ReadValue(Mode)

-&nb= sp; Item.WriteValue Value

You can only call the Item.Read= , ReadValue and WriteMethods= when the Item object is in Attached state. This normally does not need any attention, since auto-attachment feature is turned on by default, and there= fore the component will attach the Item object automatically upon entering any of these methods. If you set AutoAttach property to False, you may then need to call Attach manually before calling any of these methods.

Added GetServerStatus method to Server obje= ct

There is a new method, Server.G= etServerStatus, which has the functionality of EasyDA3.GetServerStatus but allows easier co= ding when you already have a Server object available. Note the difference between the Server.Status property, and Server.GetServerStatus method: The Server.Status always returns the OPC server’s status from internal “cache” in the EasyOPC-DA component (the cache is periodically refre= shed), and therefore always returns quickly to the caller. If the OPC server is not connected at the moment when you are retrieving the Se= rver.Status property, you will receive an error. The Server.GetSer= verStatus method, however, will first attempt to connect to the server and obtain the status, which may take some time.

Calls to ReadItem, Rea= dItemValue and WriteItemValue can “hint” the expected update rate

The behavior is controlled by the Mode.ReadAutomaticUpdateRate, ReadValueAutomaticUpdateRate and WriteAutomaticUpdateRate properties. When you call the EasyDA3.ReadItem, ReadIt= emValue or WriteItemValue method, the component will us= e the value of corresponding property of the Mode argument as the initial desired update rate (in milliseconds) for OPC subscription. If the value is “infinite” (-1), the OPC subscription will not be turned on. Any other value specifies the desired update. If the Mode argument is not suppl= ied to the method call, the EasyDA3.DefaultMode content is used. At the startup, EasyDA3.DefaultMode is filled with configuration values that you can change= in EasyOPC-DA Options utility on the “Default engi= ne mode” tab.

Ability to specify “hold periods” after reads and writes, a= nd quicker disconnections with Item and Server objects

In earlier versions, EasyOPC-DA was keeping connections to unused OPC items and servers for periods that we= re only configurable globally, for the whole component. In versions 3.00 and 3= .01, the corresponding settings in EasyOPC-DA Options utility were the “Maximum age” value for “Topic objects” and “Client objects” on the “EasyOPC-DA engine” tab. The defaults in version= s 3.00 and 3.01 were set so that connections to unused OPC items were kept for 2 minutes, and connections to unused OPC servers were kept for 5 minutes. In versions 3.00 and 3.01, these “maximum ages” also applied to Se= rver and Item objects, i.e. after you have destroyed the object, EasyOPC-DA would keep the connection until the “maximum age” was reached.<= /p>

In version 3.02, the “maximum age” setti= ngs still exist and always apply, but are set to much shorter defaults: Connections to OPC items are kept for 1 second, and connections to OPC servers are kept for 5 seconds. When you work with Item = and Server objects (using EasyDA3.RequestItem, RequestServ= er, SubscribeItem, SubscribeServer methods), the “maximum ages” are normally = overriden by longer “hold periods” (see separate chapter).

For explicit reads and writes, = EasyOPC-DA now allows you to control for how long will the connect= ion be kept after the method call. This is using the Mode argument to the method (or DefaultMode if this argument is left out). = The corresponding properties are Mode.TopicReadHoldPeriod<= /span> (used after all reads) and Mode.TopicWriteHoldPeriod (used after all writes). After a fresh installation, both these hold periods are set to 2 minutes, giving behavior that similar to that of earlier versi= ons.

WriteItemValue does not activate OPC subscr= iption by default

In earlier versions, EasyOPC-DA expected that OPC items that were written will also be read, and turned on = OPC subscription on them. In the new version, you can specify the behavior you want. In addition, by default, EasyDA3.WriteItemValue will NOT turn OPC subscription on the item.

The behavior is controlled by the Mode.WriteAutomaticUpdateRate property. When you call EasyDA3.WriteItemValue method, the component will l= ook at value of the WriteAutomaticUpdateRate proper= ty of the Mode argument. If the value is “infinite” (-1), the OPC subscription will not be turned on. Any other value (in milliseconds) speci= fies the desired update rate for OPC subscription. If the Mode argument is not supplied to the EasyDA3.WriteItemValue method, the EasyDA3.DefaultMode cont= ent is used. At the startup, EasyDA3.DefaultMode is filled with configuration values that you can change in EasyOPC-DA Options utility. On the “Default engine mode” tab, the setting is label= ed “Update rates: Automatic – write”, and after a fresh installation, the checkbox is cleared and the edit box shows “Infinite”, meaning that WriteItemValue does not turn on OPC subscription.

Update rate can be specified directly in RequestIt= em and SubscribeItem calls

In order to specify the initial update rate in EasyDA3.RequestItem or SubscribeItem call, set = it into Mode.ManualUpdateRate property and pass th= e Mode object to the method call.

It is possible to specify “infinite” timeouts for method ca= lls

It is now possible to use the value -1 (“infinite”) with any of the timeouts that control the method calls. Specifically, the properties of interest are Mo= de.ClientAttachTimeout, TopicAttachTimeout, TopicR= eadCompleteTimeout, TopicFirstUpdateTimeout, T= opicNotBadUpdateTimeout, TopicGoodUpdateTimeout, To= picWriteCompleteTimeout, and ServerStatusFirstRefreshTimeout. Be aware t= hat when any of the timeouts that are relevant to particular method is set to “infinite”, it is possible that the method call will never fini= sh. This feature should only be used in very special circumstances, and future versions of the component may impose some (configurable) administrative lim= its on its usage.

Items can be made Inactive by specifying “infinite” update = rate

In the new version, a value of -1 always represents “infinite” with update rates. The infinite update rate transfor= ms to an Inactive OPC item (or an item in Inactive OPC group). This also appli= es to Item.RequestedUpdateRate property. You can therefore set this property to -1 in order to turn the OPC item Inactive.

Be aware that EasyOPC-DA component can use the same physical connection for Item objects and for its internal use. If the connection is shared, setting higher (or infinite) upd= ate rate on one Item only affects the actual update rate if there are no other = Item objects referring to the same OPC item that have lower update rate. If you = only create one Item object for a specific OPC item, and there are no other applications using the component, this behavior does not pose a problem. In other cases, if for some reason you want to enforce the update rate yoursel= f, the solution is to use the isolated OPC objects (described further down in = this document).

Value source can intelligently be selected by the component using “desired value age”

The discussion here applies to following methods:

-&nb= sp; EasyDA3.ReadItem, ReadItemValu= e, ReadMultipleItems, ReadMul= tipleItemValues

-&nb= sp; Item.Read, ReadValue, InvokeRead, InvokeReadValue

With the new version, there are three possible sourc= es of OPC values for the above “reading” methods:

-&nb= sp; OPC Device: The value is obtained by calling an OPC method indicating that the value should be read from Device.

-&nb= sp; OPC Cache: The value is obtained by calling an OPC method indicating that the value should be read from Cache.

-&nb= sp; EasyOPC-DA Memory: The = value that is cached inside EasyOPC-DA component. The Memory is refreshed with any value that comes from OPC server, including the periodic updates.

The earlier versions of the component have always re= turned the value from EasyOPC-DA M= emory, relying on periodic updates to supply the value (the component adjusts the update rate intelligently to match the rate of client reads). Returning val= ue from Memory is still the default behavior in the new behavior, although the default (“starting”) update rates have slowed down (see further below) in order to ease the load on OPC servers with slow communication channels.

In the new version, the client application can use a= parameter (“desired value age”) to fine-tune how the value should be obtained. This parameters is contained in the Mo= de argument to any of the above mentioned methods, and is represented by Mode.DesiredValueAge property. When the Mode argument= is not specified, value from EasyDA3.DefaultMode is used, and it can be config= ured using the “Default client mode” tab in the EasyOPC-DA Options utility. After a fresh installation, it has a default value of 1000 milliseconds (1 second), for performance and backwards compatibility.

By DesiredValueAge, you = tell the component what is the oldest age of value (in milliseconds) that you would = like to receive. The component will intelligently choose the source (Memory, Cac= he or Device) and attempt to obtain the value from it using the appropriate method. Depending on circumstances, it may not always be possible for the component to supply the value of the desired age or newer. In such case, the component will return its “best attempt”, the value as fresh as possible.

By setting DesiredValueAge to lower values, less reads will be fulfilled from Memory and more reads will = have to be fulfilled from Cache or even Device, increasing the load on the OPC server. It is the programmer’s responsibility to use the DesiredValueAge wisely, considering the effect it can= have on the OPC communications.

Note that the above decision mechanism, governed by = the DesiredValueAge value, is not in effect when a specif= ic data source is chosed (OPC cache or OPC device)= , as described further below.

Value source can be directly specified using the M= ode.DataSource property

In some applications you wo= uld like to control directly whether the value is read from OPC cache or OPC device.= For this purpose, you can bypass the decision mechanism used by EasyOPC-DA with “desired value age”, and specify the data source explicitl= y.

Mode.D= ataSource property can have following values:

-= = 0: “By value age”. EasyOPC-DA will use in-memory data, OPC cache or OPC device depending on Mode.DesiredValueAge.

-= = 1: “OPC cache”. Ea= syOPC-DA will always call the OPC server and specify read from “cache”.<= /p>

-= = 2: “OPC device”. E= asyOPC-DA will always call the OPC server and specify read from “device”.=

It is the programmer’s responsibility to use the Mode.DataSource wisel= y, considering the effect it can have on the OPC communications (reads from “device” should be used scarcely, and only as asynchronous OPC calls, baring extreme circumstances).

When you invoke a read oper= ation on an OPC item using EasyDA3 object, and Mode.DataSource<= /span> is set to “By value age”, the component takes the call into acc= ount for the purpose of automatically adjusting the update rate of the item. Whe= n Mode.DataSource is set to “OPC cache” or = “OPC device”, the read invocation does affect how the update rate is automatically adjusted by the component. This behavior allows for “si= ngle shot” reads be performed, especially if they are combined with settin= g Mode.ReadAutomaticUpdateRate or = Mode.ReadValueAutomaticUpdateRate set to -1.

When the Mode argument is n= ot specified, value from EasyDA3.DataSource is used, and it can be configured using the “Default client mode” tab in the EasyOPC-DA Options utility.

The = Mode.DataSource property applies to following methods:

-&nb= sp; EasyDA3.ReadItem, ReadItemValu= e, ReadMultipleItems, ReadMul= tipleItemValues

-&nb= sp; Item.Read, ReadValue, InvokeRead, InvokeReadValue

OPC synchronous or asynchronous reads or writes can be selected

Earlier versions of EasyOPC-DA only used OPC subscription (periodic updates) to obtain the data values, so= no OPC Read was actually ever invoked. With the introduction of “desired value age” (see description above in this document), the client applications can now force to EasyOPC-DA compon= ent to actually use one of the OPC Read functions. The new version also gives you a choice between OPC synchronous and asynchronous Reads.

Earlier versions of EasyOPC-DA have only used synchronous OPC Writes. The new version gives you a choice between OPC synchronous and asynchronous Writes. Asynchronous Write is now = the default method.

The choice between synchronous and asynchronous OPC = method is made using three properties in Mode argument:

-&nb= sp; Mode.DesiredMethod is an integer tells the component whether you prefer synchronous OPC method (0) or asynchronous OPC method (1).

-&nb= sp; Mode.AllowSynchronousMethod is a Boolean value that tells the component whether you accept the choice of synchronous OPC method.

-&nb= sp; Mode.AllowAsynchronousMethod is a Boolean value that tells the component whether you accept the choice of asynchronous OPC method.

Be aware that the component is only guaranteed to actually = make the OPC Read call if the Mode.DataSource proper= ty is set to either “OPC cache” or “OPC device”. If it is= set to “By value age” (which is the default), the component will of= ten resort to providing the value from internal memory, resulting in no OPC Read call at all. Be sure to set the Mode.DataSource= to “OPC cache” or “OPC device”, if your intent is to force the OPC read call.

Note that in some situati= ons, depending on the data source (Cache or Device), and also version and level = of OPC specification supported by the OPC server, not all methods are availabl= e. For this reason, you should “allow” both methods if at all possible, as otherwise the component may not be able to fulfill your reques= t.

Following table makes it clear what the behavior is with different settings.

AllowSynchronousMethod	AllowAsynchronousMethod	DesiredMethod	behavior
False	False	any	Error
False	True	any	Performs the call using asynchronous OPC method if availa= ble
True	False	any	Performs the call using synchronous OPC method if availab= le
True	True	0 (synchronous)	Performs the call using synchronous OPC method if availab= le, otherwise attempts to perform the call using asynchronous OPC method
True	True	1 (synchronous)	Performs the call using asynchronous OPC method if availa= ble, otherwise attempts to perform the call using synchronous OPC method

When the Mode argument is not specified in the method call,= the value of DefaultMode property on the object is = used. The initial values in DefaultMode are taken fro= m the component’s configuration, as given in the EasyO= PC-DA Options utility. Navigate to “Default client mode” to configure= the relevant settings.

Note that the selection of OPC method (synchronous o= r asynchronous) has nothing to do with the way the actual EasyOPC-DA method call is performed with respect to the caller (client application). EasyOPC-DA always executes the OPC functions on separate threads, and reports the resu= lt back to the caller through internal synchronization mechanisms. This allows= to introduce timeouts into functions calls that do not have associated timeout= in OPC, and to transform between synchronous and asynchronous execution modes.= To further clarify how various EasyOPC-DA methods = work, refer to the text below.

With respect to the caller, methods listed below alw= ays perform in a SYNCHRONOUS way, with additional timeouts artificially imposed= by the EasyOPC-DA component.

-&nb= sp; EasyDA3.ReadItem, ReadItemValu= e, WriteItemValue, ReadMultip= leItems, ReadMultipleItemValues, Wr= iteMultipleItemValues, GetServerStatus

-&nb= sp; EasyDA3.BrowseServers, BrowseB= ranches, BrowseLeafs

-&nb= sp; Item.Read, Item.ReadValue, Item.WriteValue<= /span>

-&nb= sp; Server.GetServerStatus<= /p>

= ;

With respect to the caller, methods listed below alw= ays perform in an ASYNCHRONOUS way, with additional timeouts artificially impos= ed by the EasyOPC-DA component.

-&nb= sp; EasyDA3.SubscribeServer, Unsub= scribeServer, SubscribeItem, Unsubscribe= Item, UnsubscribeAllServer, Unsu= bscribeAllItems

-&nb= sp; Item.Connect, Item.Disconnect

-&nb= sp; Server.Connect, Server.Disconnect

-&nb= sp; Item.InvokeRead, InvokeReadValue, InvokeWriteValu= e

Methods listed below do not perform any physical OPC operat= ion, and work in a synchronous way with respect to the caller – however, f= or the reason just given, their execution is usually very quick. Setting or getting ANY property on any object also behaves in this way.

-&nb= sp; EasyDA3.RequestServer, Request= Item

-&nb= sp; EasyDA3.FindSubscribedServer, = FindSubscribedItem

-&nb= sp; Mode.Clone

-&nb= sp; Item.Attach, Detach

-&nb= sp; Server.Attach, Server.Detach

-&nb= sp; RaiseError method on ANY object

EasyOPC-DA Options utility now has “F= actory defaults” button

The = EasyOPC-DA Options utility now allows you to revert all set= tings back to the fresh post-installation state. To revert the settings, press the “Factory defaults” button located in the lower left corner of the dialog.

There is one exception: The “Factory defaults&= #8221; button has limited influence on the settings on “COM registrationR= 21; page.

EasyDA3 objects have separated internal queues

In earlier versions, events that are to be fired on = EasyDA3, Item and Server objects were placed in common, global queue. A problem in processing an event (such as lengthy processing or deadlock in client application) could prevent further processing of all events and “spread” to other parts of the system. The new version maintains separate event queue for each instance of EasyDA3 object.

Problematic connections to connection points are automatically suspende= d

In earlier versions, when there was a problem in cli= ent application consuming the events, EasyOPC-DA continued to fire events on the affected connection. In some situations, su= ch as when the out-of-process COM client had died, this lead to gradually increasing CPU usage. In new version, when an error (typically an RPC probl= em) is returned by the event handler, the EasyOPC-DA component will suspend the connection and will no longer fire events to it.=

Item and Server objects are automatically detached when all connections= are suspended

When the client application dies, it can take COM/DC= OM up to 6 minutes to release all interface pointers to the server (in this case,= the server is the EasyOPC-DA component). In the new version, EasyOPC-DA component can sometimes det= ect the situation earlier – if there are connections to the object’s connection points, and they have all become suspended because of errors in calling their methods, it means that the client had dies. In this situation, the new version automatically detaches the Item or Server object or unsubscribes all items and server on the EasyDA3, whi= ch in turn causes their faster disconnection from the OPC server.

Internal queue lengths are limited, and configurable

EasyOPC-DA uses several = internal queues for passing information between the parallel threads. In earlier versions, the queue lengths were not limited. If the client application was= not able to consume the events fast enough, or if had blocked altogether, there= was a potential for EasyOPC-DA queues to grow indefinitely, which was manifested by symptoms similar to a “memory leak”. In the new version, all queues have their maximum sizes set to reasonable defaults, and the queues will not grow over the specified sizes.= In case of queue overflow, an entry is logged into the event log.

In some rare cases, such as when working with extrem= ely large numbers of OPC items, you may need to modify the maximum queue sizes.= In EasyOPC-DA Options utility, the maximum queue sizes a= re set at following locations:

-&nb= sp; “Handling OPC-DA servers” tab: “Q= ueue sizes: Topic requests” edit box.

-&nb= sp; “Handling OPC-DA servers” tab: “Q= ueue sizes: Topic responses” edit box.

-&nb= sp; “EasyOPC-DA engine” tab: “Default event queue size” edit box

-&nb= sp; “EasyOPC-DA engine” tab: “Async input queue size” edit box

Added Parent property to Item and Server objects

‘Parent’ is read-only property that cont= ains reference to the EasyDA3 object that created the Item or Server object. The ‘Parent’ property only maintains a weak reference on the parent: When the parent EasyDA3 object is destroyed, the ‘Parent’ prope= rty on Item or Server will return a null reference.

Item and Server objects now have their own Default= Mode property

As there are now methods on Item and Server object that accept the Mode argument, the DefaultMode prope= rty has been added to Item and Server objects as well. Its functionality is the same as EasyDA3.DefaultMode. The initial settings of I= tem.DefaultMode and Server.Default are always taken from the EasyOPC-DA configuration, not from the parent EasyDA3.DefaultMode or the Mode argument used when creating the Server or I= tem object.

Item and Server objects now also have RaiseError method

For consistency and future expansion, the EasyDA3.RaiseError method has been duplicated in Item and Server object. Its functionality on the Item and Server object is precisely the same as on the EasyDA3 object.

Integer argument in place of Mode for reading methods is interpreted as= DesiredValueAge

If an integer number is specified in place of the Mo= de argument of any reading method, it is assumed to be the desired value age. = The method call will work with the EasyDA3.DefaultMode values, but will use the supplied integer as the DesiredValueAge for this single method call. This way, you can easily specify different desired value ages with each method call, without having to create a separate Mode object= or modify the EasyDA3.DefaultMode property.

This feature applies to following methods:

-= = EasyDA3.ReadItem, ReadItemValu= e, WriteItemValue, ReadMultip= leItems, ReadMultipleItemValues

-= = Item.Read, Item.ReadValue

Integer argument in place of Mode for RequestItem<= /span> and SubscribeItem methods is interpreted as ManualUpdateRate

If an integer number is s= pecified in place of the Mode argument of EasyDA3.RequestItem or SubscribeItem methods, it is assumed to be the desired update rate. The method call will = work with the EasyDA3.DefaultMode values, but will use the supplied integer as t= he ManualUpdateRate for this single method call. This wa= y, you can easily specify different update rates with each method call, without ha= ving to create a separate Mode object or modify the EasyDA3.DefaultMode property= .

New properties in Mode object

New properties in Mode object were described at other places in this document. The list of supported properties in Mode object is= as follows:

· ClientAttachTimeout

· TopicAttachTimeout

· TopicReadCompleteTimeou= t

· TopicFirstUpdateTimeout=

· TopicNotBadUpdateTimeou= t

· TopicGoodUpdateTimeout<= /span>

· TopicWriteCompleteTimeo= ut

· ServerStatusFirstRefres= hTimeout

· TopicReadHoldPeriod

· TopicWriteHoldPeriod

· ReadAutomaticUpdateRate=

· ReadValueAutomaticUpdat= eRate

· ManualUpdateRate=

· DesiredMethod

· AllowSynchronousMethod<= /span>

· AllowAsynchronousMethod=

· DesiredValueAge<= /p>

· MaximumValueAge<= /p>

Different “default mode” values

After a fresh installation, some configuration values (especially those affecting the EasyDA3.DefaultMode initial value) have cha= nged in the new version. Some are of particular interest:

-= = DefaultMode.ReadAutomaticUpdat= eRate (used with EasyDA3.ReadItem and ReadMultipleItems) is now 10,000 milliseconds (10 seconds). This is much slower than in earlier versions.

-= = DefaultMode.ReadValueAutomatic= UpdateRate (used with EasyDA3.ReadItemValue and ReadMultipleItemV= alues) is now 1,000 milliseconds (1 second). This is also quite slower than in ear= lier versions.

-= = DefaultMode.WriteAutomaticUpda= teRate (used with EasyDA3.WriteItemValue and WriteMultipleIte= mValues) is now “infinite” (-1). This means that writing to an item does= not automatically turn on OPC subscription on it.

Timeouts are now adjusted according to number of work items, and moved = to separate page

In earlier EasyOPC-DA version, the timeouts for various operations were independent of number of items involved in the operation. In version 3.02, the component can increase the timeouts automatically, based on number of items that you specified in = the method call (such as ReadMultipleItems etc.). <= /p>

This new behavior makes it = easier to write applications that work with large number of items, and makes it le= ss likely that you receive timeout errors.

The time adjustments can no= w be specified together with the “constant” timeout values on a sepa= rate page in EasyOPC-DA Options utility.

In addition, the time adjustments also have their corresponding properties in the Mode object. The property names use the nam= e of the “constant” timeout value, plus the suffix “PerWorkItem” (e.g. TopicRe= adCompleteTimeoutPerWorkItem).

Slight change in “bucketing” algorithm for update rates mak= es it more precise

EasyOPC-DA modifies the = update rates given by its callers, in order to prevent creation of too many groups with very close update rates. In earlier versions, when you specified an up= date rate (in milliseconds) that was a precise power of 10, the computation algorithm always modified it to the nearest faster internal “bucket”. For example, when you specified 100 milliseconds, the actual OPC update rate used was 69 milliseconds. In version 3.02, the “bucketing” algorithm is improved so that in this common case, = the specified rate is not modified (when you specify 100 milliseconds, it will = be used “as is”).

Events in .NET are now [Globals.]EasyDAEventHandler (and accept directly EasyDAEventArgs)

In earlier EasyOPC-DA versions, event handlers in .NET were of type System.E= ventHandler, accepting a generic sender argument and a generic Syst= em.EventArgs argument. In order to retrieve information specific to EasyOPC-DA, you had to cast the EventArgs to EasyDAEventArgs.

In version 3.02, the second argument to event handlers is now directly EasyDAEvent= Args (in OPCLabs.EasyOPCDANet namespace). This allows direct access to event information without casting. The delegate type corresponding to EasyOPC-DA event handlers is <= span class=3DSpellE>Globals.EasyDAEventHandler (in O= PCLabs.EasyOPCDANet namespace).

Events no longer fire after trial times out

Version 3.02 no longer fires any (OPC-related) events = when the maximum run time period (used with trial versions of the software) is o= ver.

Asynchronous execution of EasyOPC-DA method= s

In version 3.02, it is now = possible to invoke OPC reads and writes asynchronously with respect to the caller. T= he method call returns quickly, while the OPC operation is being performed in = the background. The outcome of the operation (either positive or negative) is returned via an event. The events that indicate completion of asynchronous operations are described further below in this document.

Following methods execute asynchronously with respect to the caller:

-&nb= sp; EasyDA3.InvokeReadItem(Machine= Name, ServerClass, ItemID= , AccessPath, DataType, Inf= o, Mode)

-&nb= sp; EasyDA3.InvokeReadItemValue(Ma= chineName, ServerClass, ItemID= , AccessPath, DataType, Inf= o, Mode)

-&nb= sp; EasyDA3.InvokeWriteItemValue(M= achineName, ServerClass, ItemID= , Value, AccessPath, DataType, Info, Mode)

-&nb= sp; Item.InvokeRead(Info, M= ode)

= -&nb= sp; Item.InvokeReadValue(In= fo, Mode)

= -&nb= sp; Item.InvokeWriteValue(V= alue, Info, Mode)

In addition to arguments accepted by the synchronous counterparts, these methods accept an addition Info argument, which can be = any value. This value is then made available to you in the completion event, and can be used e.g. to distinguish between multiple asynchronous calls on the = same object.

The asynchronous methods on= ly perform very basic checking on the validity of their arguments during the method call. Anything that requires actual communication to the OPC server = is left to the execution phase, performed in the background.

Note that EasyOPC-DA distinguishes between the underlying OPC read/write method (synchronous or asynchronous) and the way a specific EasyOPC-DA method works (synchronously or asynchronously). These two aspects are independent of each other, and you can control them separately.

You choose the way you want= the results returned by selecting proper EasyOPC-DA method (for instance, Item.Read versus Item.InvokeRead). You choose the way the results will= be obtained (through OPC) by using properties of the Mode argument, such as DesiredMethod (described at other place in this docum= ent).

New events that indicate completion of asynchronous methods

Asynchronous methods invoke= d on the EasyDA3 object indicate their completion via following events (argument lis= ts apply to COM; for .NET use, see the note below):

-= = EasyDA3.ItemReadComplete(EasyD= A, Item, Info, VTQ)

-= = EasyDA3.ItemReadValueComplete(= EasyDA, Item, Info, Value)

-= = EasyDA3.ItemWriteValueComplete(EasyDA, Item, Info, Result)

Asynchronous methods invoke= d on the Item object indicate their completion via following events (argument lists apply to COM; for .NET use, see the note below):

-= = Item.ReadComplete(Item,= Info, VTQ)

-= = Item.ReadValueComplete(= Item, Info, Value)

-= = Item.WriteValueComplete= (Item, Info, Result)

As with other EasyOPC-DA e= vents, the arguments differ in .NET: All .NET events accept a Sender argument, identifying either the EasyDA3 or Item object on which = the asynchronous method was invoked, and an EasyDAE= ventArgs argument, which holds detailed information about the event. Use the Info and Result properties of the EasyDAEventArgs object= to obtain the detailed information.

For successful operations, = the return value of the operation is in the VTQ, Value or Result arguments (COM= ) or in the Result property (.NET). The result is an empty object for successful “writes”.

For failed operations, the = error indication is “wrapped” in the VTQ, Value, or Result arguments (COM) or in= the Result property (.NET) again, but is not directly accessible. Use the RaiseError method with the result value to check for operation successes/failures. If the RaiseError method throws an exception, the operation completed with a failure, and the exception carries further information about the error. If the RaiseError method succeeds, the operation completed w= ith a success, and the result value is directly usable.

AsyncActivity objects

Some development tools do not have the ability to hook= to events but would still greatly benefit of having means to perform OPC operations and retrieve results asynchronously; typical example of such a t= ool is Active Server Pages (ASP). In ASP, you can invoke the asynchronous metho= ds of EasyOPC-DA in the usual way. However there i= s no means of hooking to completion events.

In order to emulate as clos= ely as possible the asynchronous completion events for such development tools, EasyOPC-DA version 3.02 introduces AsyncActivity objects. Every method that invokes an asynchronous OPC operation returns an= AsyncActivity object that can be later used to check = the status of the operation and retrieve the results.

The As= yncActivity object has following read-only properties:

-= = Target: Returns a reference to the Item or Server object that is the target of the operation.

-= = Info: Returns application-supplied data provided as argument in the asynchronous invocation method.

-= = IsCompleted: Returns Bo= olean value indicating whether the operation is completed (either with success or failure).

-= = Result: Only accessible when I= sCompleted =3D True. Returns result of the operation. With any operation, the result c= an be an error object, and your code should use RaiseError(Result) to check for errors. For successful OPC “read”, the result is the VTQ3 object. For successful OPC “read value”, the result is the value itself. For successful OPC “write”, the result is an empty object.

Note that AsyncActivity objects are only available in COM (are not available in .NET).

“Hold periods” now also apply to Request/Subscribe

Earlier versions of EasyOPC-DA component used single approach for automat= ic disconnecting from OPC items and servers that were not longer in used. For “one-time” OPC reads and writes, and also for items and servers obtained through RequestItem and RequestServer methods, the component always held the connection active for the same, relatively long time.

Version 3.02 now has separa= te “hold periods” that apply to objects obtained through RequestItem/SubscribeItem and Re= questServer/SubscribeServer methods. These periods are, by default, much shorter. Connection to an item= is held for 5 seconds after it is released or unsubscribed, and connection to a server is held for 30 seconds after it is released or unsubscribed.

You can influence these hold periods by Mode.ServerDetachHoldPeriod and Mode.ItemDetachHoldPeriod properties (in milliseconds= ), or using the EasyOPC-DA Options utility. Note that (somewhat counter-intuitively), the above values should be passed in the Mode argument to RequestItem/S= ubscribeItem and RequestServer/SubscribeServer methods (NOT = the UnsubscribeItem and UnsubscribeS= erver methods). The actual interpretation of the values takes place later - at the moment the object is released or unsubscribed.

Isolated OPC server objects

Earlier versions of the component always used a shared connection to OPC server. As long as the OPC server was addressed using precisely the same machine name and server class parameters, the same connection to OPC server was shared among all client applications and EasyD= A3 objects. This is still the default behavior in the new version.

In version 3.02, it is now = possible to specify that you wish to work with an “isolated” connection = to the OPC server, i.e. one that is not shared with other client applications = or even other connections in your own application. The isolated connection is always specific to a single instance of the EasyDA3 object; if your application need to maintain more isolated connections to the same server, = it can be done by instantiating multiple EasyDA3 objects.

To indicate that the isolat= ed OPC server connection should be used, set the IsolatedServ= er property of the Mode argument to True. If the Mode argument is not specifie= d, value from DefaultMode property of the EasyDA3 = object is used; this value is initialized from the setting made in EasyOPC-DA Options utility.

Note that IsolatedServer must be set with ALL function calls that are supposed to work with the isol= ated connection. If you forget to set IsolatedServer= at one place, a second (shared) connection will be used. Simply setting EasyDA3.DefaultMode.IsolatedServer to True early enough will work well with most applications.

It is possible to disconnec= t from the isolated OPC server by calling Server.Disconnect. The same call for a server that is not isolated is ignored.

Documentation for EasyOPC-DA Options utilit= y now shipped with the product

Settings in the EasyOPC-DA Options utility are now documented in manuals, and help is also directly accessible from the utility.

New “OPC-DA Controls” for .NET Windows Forms

If you use the EasyOPC-DA component in .NET Windows forms, you must observe the general Windows Forms rule: (user interface) controls can only be accessed from the thread that created them. For this reason, it is not safely possible to update user interface controls directly from EasyOPC-DA eve= nt handlers, as the events firing and handling code may be (and usually is) running on different threads.

The standard solution to th= is is to use the Control.Invoke method or some of related methods to execute a delegate on the thread that owns the control’s underlying window handle. This technique works well, but unnecessary complicates the application code.

In order to make programmin= g with Windows Forms and EasyOPC-DA easier, version 3.= 02 introduces a new component for .NET Windows Forms. This is a (non-visual) component named OPCDAComponent (in OPCLabs.OPCDAControls namespace). OPCDAComponent support the same interfaces as EasyDA3 object, but with following differenc= es:

-= = Reference the OPCLabs.OPCDACon= trols assembly in order to use the component.

-= = All event handlers run on a thread that owns the control that you specify (typically, the Form itself).

-= = The component can be used in VS.NET 2003 visual designer (you can drag it from the Toolbox onto a design surface, and confi= gure its properties interactively).

-= = Remember to always set the Par= entControl property. This property determines the thread on which the event handlers w= ill run. Normally you will click on this property in the Properties Window, and select the Form control as the parent control.

-= = By placing the component onto a design surface, it = is already instantiated for you, so you do not have to write code that creates= the object.

-= = The component assumes that you will be working with= OPC data directly through COM. If you want to use the Web Service instead, set = the AutoCreate property to False, and in your code, insta= ntiate the EasyDAWS object and assign it to the EasyDA property of the OPCDAComp= onent object.

-= = As the OPCDAComponent w= orks with the visual designer, you will be able to hook events to it without manually typing the code – just select the component and the event fr= om the drop-down list boxes above the code view, and the visual designer will = take you to the right event handler or will create a skeleton of it for you.

Examples updated and enhanced to reflect the changes

All examples have been upda= ted so that they work properly with latest version of the software. We have added examples for new features, and will continue adding examples after the init= ial software release.

Enhancements to Mode object projected to OPCDAProv= ider keywords

All relevant new properties of the Mode object are also available through the Web Service as “keywords” used with OPCDAProvider component input arguments. The new keyw= ords are:

-= = AllowAsynchronousMethod=

-= = AllowSynchronousMethod<= /p>

-= = DataSource

-= = DesiredMethod

-= = DesiredValueAge

-= = IsolatedServer

-= = ReadAutomaticUpdateRate=

-= = ReadValueAutomaticUpdateRate

-= = ReadCompleteTimeout

-= = ReadHoldPeriod

-= = WriteCompleteTimeout

-= = WriteHoldPeriod

-= = WriteAutomaticUpdateRate

-= = all timeouts with “…PerWorkItem” suffix

Various other internal changes, small enhancements and bug fixes

Documentation addendum

The notes here applies to previous version as well, it= is included as general documentation enhancement.

-= = If you want to impose certain order of OPC reads or writes, your application should perform the operations sequentially, and al= ways wait until the previous operation completes (with success or failure) before executing next one. In other situations, the order of OPC operations is not guaranteed to be the same as the order of method calls.