Echelon LNS - Manual (Page 81)

LNS Programmer's Guide 67
Echelon recommends that you use the handle or name assigned to an object to retrieve it
from a collection. The handle may be most desirable, since it is a static, unique value.
However, if you need to iterate through a collection using index numbers to retrieve each
object, you should do so within a transaction. If another client application adds or
removes an object from a collection while your application is iterating through it, you
may encounter invalid or repeated data as LNS adjusts the indices assigned to other
objects in the collection. Exceptions you might encounter in this situation are the
LCA:#96 lcaErrObjectDeleted, LCA:#15 lcaErrInvalidCollectionIndex, and
LCA:#6 lcaErrObjectNotFound exceptions. If you iterate through the collection
within a transaction, your application will maintain a consistent view of the collection
during the transaction, and it will not be affected if other client applications modify the
collection. In addition, using a transaction will result in better performance.
Managing Sessions
A given client can have at most one session in progress at a time. A session must be part
of an explicit transaction, and each transaction can contain more than one session.
Changes made in a session will not be committed until the transaction that contains the
session is committed. Sessions can be used to group operations that are within the same
transaction.
To begin a session within an explicit transaction, call the System object's
BeginSession() method. This method takes one argument, sessionClass, which
must be set to lcaSessionMove. Once a session is started, certain methods and
properties may be invoked, and these methods and properties will be considered part of
the session until the session is ended.
Consider a case where you are moving a large number of devices with subnet broadcast
connections from one channel to another, using the unacknowledged repeat messaging
service. If only some of these devices are moved, your application would detect that not
all of the devices are on the same subnet and the move would fail (since unacknowledged
repeat service for domain wide broadcast is not allowed). By grouping the moves in a
session, the actual connecting and validation does not take place until the session ends,
and so the network configuration is not affected if the operation fails.
The only network operations you should perform within sessions are those related to
changes in the physical topology of your network. This includes moving devices and
routers, adding and removing routers, and setting router classes. As a result, the
methods you can use within a session include the following methods of the AppDevices
and Routers collections: PreMove(), MoveEx(), PostMove(), Add(), and Remove().
You can also write to the Class property of a Router object within a session.
To end a session, call the EndSession() method. This method also takes the
sessionClass argument, which must be set to lcaSessionMove. When this method is
called, LNS checks for any error conditions that may have resulted from all method and
property calls that were made since the BeginSession() method was called, and
applies the changes caused by those calls to the LNS database.
Event Handling
LNS uses events to inform the application of a variety of network occurrences, such as
the arrival of service pin messages, or changes to the network’s configuration. You can