Echelon LNS - Manual (Page 85)

LNS Programmer's Guide 71
Some properties and methods normally return an object, e.g. the Add() method of the
AppDevices collection, and some return a value. However, if an exception is generated,
the return value has no meaning and is not used, and the returned object (were it to be
non-zero) is not valid. Likewise, when you use the interface that returns HRESULT
codes instead of producing exceptions, the accessors return data results via pointers
(output parameters). In case the HRESULT code indicates failure, the result pointer does
not refer to valid data.
Note that when making changes inside of an explicit transaction, the updates are
deferred until the transaction is committed. Therefore, update warnings are never
thrown or returned when methods are called from within a transaction, but may be
thrown or returned when the CommitTransaction() method is called. However,
warnings or errors related to parameters provided to a method within the transaction
may be reported before you call the CommitTransaction() method. For example,
calling the AddTarget() method with a bad target reference parameter may result in an
immediate error condition.
You also need to consider the pairing requirements for open and close statements, and
StartTransaction() and CommitTransaction() statements. If an open operation
was successful, you should always make sure to invoke the matching close operation.
However, if the open failed, it may not make sense to perform the matching close
operation (although the close operation should not cause any problems in this case).
Transactions have a different requirement. After the StartTransaction() method has
been called, your application will eventually need to invoke the CommitTransaction()
method or the CancelTransaction() method. You should note that if the call to
CommitTransaction() fails, you still need to invoke the CancelTransaction()
method to cancel the transaction.
Terminating an LNS Application
You should terminate any LNS application, regardless of client type, by following these
steps:
1. Stop all monitoring and control tasks. If using permanent monitor sets,
those MonitorSet objects should be closed. For more information on
monitor and control, see Chapter 9, Monitor and Control.
2. If you are operating in server-dependent mode (i.e. not as an Independent
client), close each open System object by invoking its Close() method. If
the application is a Local or Full client, this detaches the LNS Object
Server from the network. If the application is a Local client, and the LNS
Server application was automatically launched by an LNS application,
this also shuts down the LNS Server application. For Lightweight clients,
this method de-registers the application from the LNS Server.
MySystem.Close()
3. Close each open Network with the Close() method. If you are running
an independent client, use the CloseIndependent() method.
MyNetwork.Close()
4. Close the ObjectServer control by invoking its Close() method.
ObjectServer.Close()