Owner manual

ManualsBrandsEchelon ManualsSoftwareOpenLNS

OpenLNS

Programmer's Reference

078-0437-01A

Summary of content (1081 pages)

PAGE 1
OpenLNS Programmer's Reference 078-0437-01A
PAGE 2
Echelon, LON, LonWorks, Neuron, 3120, 3150, i.LON, LNS, LonMaker, LONMARK, LonTalk, NodeBuilder, and the Echelon logo are trademarks of Echelon Corporation registered in the United States and other countries. LonSupport, OpenLDV, and LNS Powered by Echelon are trademarks of Echelon Corporation. Other brand and product names are trademarks or registered trademarks of their respective holders.
PAGE 3
Table of Contents Preface ................................................................................................ xxxi Purpose ...................................................................................................... xxxii Audience ..................................................................................................... xxxii System Requirements ................................................................................ xxxii OpenLNS SDK ...............................
PAGE 4
Alias ............................................................................................................... 21 Methods .................................................................................................. 21 Properties ................................................................................................ 21 ClassId .............................................................................................. 21 Index ..........................................................
PAGE 5
DetailInfo .......................................................................................... 74 Device Template............................................................................... 74 Extensions ........................................................................................ 74 Handle .............................................................................................. 75 HasBeenCommissioned ...................................................................
PAGE 6
State ............................................................................................... 103 BufferConfiguration...................................................................................... 104 Methods ................................................................................................ 105 Properties .............................................................................................. 105 ClassId .....................................................................
PAGE 7
ComponentApps .......................................................................................... 135 Methods ................................................................................................ 136 Add ................................................................................................. 136 Remove .......................................................................................... 137 Properties ...........................................................................
PAGE 8
BroadcastOptions ........................................................................... 176 ClassId ............................................................................................ 177 Description ...................................................................................... 178 Handle ............................................................................................ 178 MTHubs ..........................................................................................
PAGE 9
DatabaseValidationErrorInstance................................................................ 207 Methods ................................................................................................ 208 Properties .............................................................................................. 208 ClassId ............................................................................................ 208 ErrorType ..............................................................................
PAGE 10
DataValue .................................................................................................... 253 Methods ................................................................................................ 253 Properties .............................................................................................. 254 AppDevice ...................................................................................... 254 ClassId .....................................................................
PAGE 11
RegisteredComponent ................................................................... 282 SelfDocConsistency ....................................................................... 283 SelfDocumentation ......................................................................... 285 UserTypeFileName......................................................................... 285 XifPath ............................................................................................ 286 DeviceTemplates ..............
PAGE 12
Item ................................................................................................. 312 Parent ............................................................................................. 313 _NewEnum ..................................................................................... 313 FileTransfer ................................................................................................. 314 Methods ..............................................................................
PAGE 13
ClassId ............................................................................................ 357 Count .............................................................................................. 357 Item ................................................................................................. 357 Parent ............................................................................................. 358 _NewEnum .................................................................................
PAGE 14
Item ................................................................................................. 400 Parent ............................................................................................. 401 _NewEnum ..................................................................................... 401 LdrfLanguage .............................................................................................. 402 Methods .................................................................................
PAGE 15
ParentInterface ............................................................................... 432 PrincipalNv ..................................................................................... 433 ProgrammaticName........................................................................ 433 ReportMask .................................................................................... 434 Request ..........................................................................................
PAGE 16
Enable............................................................................................. 467 Open ............................................................................................... 468 Properties .............................................................................................. 470 ClassId ............................................................................................ 470 IsEnabled ..............................................................................
PAGE 17
UpdateErrorEvent ........................................................................... 505 UpdateEvent ................................................................................... 505 MsgMonitorPoints ........................................................................................ 508 Methods ................................................................................................ 508 Add ............................................................................................
PAGE 18
Parent ............................................................................................. 543 _NewEnum ..................................................................................... 544 NetworkInterface ......................................................................................... 544 Methods ................................................................................................ 545 Properties .............................................................................
PAGE 19
Properties .............................................................................................. 570 ClassId ............................................................................................ 570 Count .............................................................................................. 571 Item ................................................................................................. 571 Parent ..............................................................................
PAGE 20
Priority............................................................................................. 610 PriorityConfigFlag ........................................................................... 611 ProgrammaticName........................................................................ 612 Selector .......................................................................................... 613 SelfDocumentation ......................................................................... 613 ServiceType ..
PAGE 21
Events ................................................................................................... 653 UpdateErrorEvent ........................................................................... 654 UpdateEvent ................................................................................... 654 NvMonitorPoints .......................................................................................... 657 Methods .....................................................................................
PAGE 22
Object ............................................................................................. 685 Parent ............................................................................................. 685 RemoteFlag .................................................................................... 686 RemoteNetworks ............................................................................ 687 ResourceLanguageId ..................................................................... 688 TabIndex ....
PAGE 23
InOverride ....................................................................................... 737 InvalidId .......................................................................................... 738 InvalidRequest ................................................................................ 738 LockedOut ...................................................................................... 739 ManualControl ................................................................................
PAGE 24
ReplaceEx ...................................................................................... 773 Reset .............................................................................................. 774 Test ................................................................................................. 774 Properties .............................................................................................. 780 AttachmentStatus ........................................................................
PAGE 25
Methods ................................................................................................ 812 Properties .............................................................................................. 812 ClassId ............................................................................................ 812 Parent ............................................................................................. 813 QueuePosition .....................................................................
PAGE 26
Remove .......................................................................................... 838 Properties .............................................................................................. 839 ClassID ........................................................................................... 839 Count .............................................................................................. 839 Item ......................................................................................
PAGE 27
ClientId............................................................................................ 877 CommissionedDeviceCount ........................................................... 877 ComponentApps ............................................................................. 878 Connections.................................................................................... 878 CurrentAccount............................................................................... 878 CurrentDeviceCount ......
PAGE 28
ClassId ............................................................................................ 916 Count .............................................................................................. 917 Item ................................................................................................. 917 Parent ............................................................................................. 918 _NewEnum .................................................................................
PAGE 29
ToOwnerIndex ................................................................................ 953 UpgradeInfos ............................................................................................... 954 Methods ................................................................................................ 954 Properties .............................................................................................. 954 ClassId ..........................................................................
PAGE 30
OpenLNS Programmer’s Reference xxx
PAGE 31
Preface This document provides an overview of how to use the OpenLNS Object Server Active X control, and it contains detailed information on each object, property, method, event and constant you will use when writing OpenLNS applications. This includes information such as the syntax you should use when calling a method or writing to a property, and the version when each item was Added to API.
PAGE 32
Purpose This document provides reference information for writing OpenLNS applications. Audience This guide is intended for software developers creating OpenLNS applications. OpenLNS applications may be written in any language that supports COM Components or ActiveX controls, including Microsoft® Visual C# .NET, Visual C++ .NET, and Visual Basic .NET. Readers of this guide should have experience programming in these languages, and be familiar with LONWORKS® technology and COM/ActiveX control concepts.
PAGE 33
OpenLNS Server Computer (Smaller Network) System requirements for computers running the OpenLNS Server on a smaller network are as follows: • Windows 7 (64-bit and 32-bit), Windows Server 2008 SR2 64-bit and 32-bit (64-bit RNI required; U10/U20 desirable), Windows Vista with Service Pack (SP) 1, or Windows XP with SP3 (32-bit). • 100MHz processor or faster • 50 MB or more of free disk space. This does not account for the size of the OpenLNS application or the OpenLNS network databases.
PAGE 34
• Microsoft Visual Studio 2010 or Microsoft Visual Studio 2008 (.NET Framework 3.5) for development of Visual C# .NET, Visual C++ .NET, and Visual Basic .NET applications. • DVD-ROM drive • 1,024 x 768 or higher-resolution display with at least 256 colors. • Mouse or compatible pointing device • Local, remote, or IP-852 OpenLDV 4.0 network interface.
PAGE 35
If you have technical questions that are not answered by this document, the online help files provided with the OpenLNS Standard Developer’s Kit, or the Echelon OpenLNS Utilties ReadMe document, you can contact technical support. Free e-mail support is available or you can purchase phone support from Echelon or an Echelon support partner. See www.echelon.com/support for more information on Echelon support and training services.
PAGE 36
Content This guide includes the following content: • OpenLNS Object Server. Introduces the OpenLNS Object Server, describes the OpenLNS Object model, hierarchy, and naming conventions, and it • Objects. Describes the objects in the OpenLNS Object hierarchy, and details their methods, properties, and events. • Interfaces. Details each interface in the OpenLNS Object hierarchy. • OpenLNS Errors. Lists and describes the OpenLNS errors that may be generated by the various OpenLNS components.
PAGE 37
OpenLNS Programmer's Reference xxxvii
PAGE 38
1 OpenLNS Object Server This chapter introduces the OpenLNS Object Server, describes the OpenLNS Object model, hierarchy, and naming conventions.
PAGE 39
Introduction The OpenLNS Object Server ActiveX Control provides high-level services for installing, diagnosing, maintaining, and monitoring and controlling LONWORKS networks. This ActiveX control is an OpenLNS client application interface into the OpenLNS network operating system. The OpenLNS network operating system allows LONWORKS network tools to interoperate with one another, and interact with the managed LONWORKS network.
PAGE 40
The remainder of the OpenLNS Objects originate from the three Networks collections. A network is represented by an instance of the Network object, which contains both a systems and channels collection. A network defines a physical LONWORKS network, while a system is an entity, both logical and physical, that uses the network fabric. Each Network object has a MyVNI property which contains an AppDevice object which contains the MonitorSets collection for that network.
PAGE 41
a Subsystem. Different Subsystems can contain devices with the same name, however. For example, a building may consist of a Subsystem object for each room, with each room Subsystem including AppDevice objects called VAV and Thermostat. The NetworkServiceDevice class provides a logical representation of the OpenLNS Server and its NSI. The network service device, in turn, contains a NetworkInterface object. This network interface determines the driver name to be associated with the system, if any.
PAGE 42
Object Naming Convention While the documentation currently references most objects by their base names, it is important to note that this name is not the full class name. The full name, which must be used when declaring object types, includes the "Lca" prefix.
PAGE 43
OpenLNS Programmer's Reference 6
PAGE 44
2 Objects This chapter describes the objects in the OpenLNS Object hierarchy, and details their properties, methods, and events.
PAGE 45
Account Description Represents an OpenLNS licensing account. Reserved for future use. Added to API Prior to LNS Release 3.0. Accessed Through Accounts collection object System object Default Property Name property. Methods None Properties • • • • • AccountNumber Charges ClassID Description Name Methods The Account object does not contain any methods.
PAGE 46
example, when the object was accessed using the Parent property of another object). Availability Local, full, and lightweight clients. Syntax numCharges = acctObject.Charges Element Description numCharges A Long containing the number of charges. acctObject The Account object to be acted on. Data Type Long. Read/Write Read and write. Added to API Prior to LNS Release 3.0. Comments This property and the associated Account and Accounts objects are reserved for future use.
PAGE 47
stringValue A string description of the object. object The object to be acted on. Data Type Long. Read/Write Read and write. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. Comments This property is read only for Error objects. Name Summary Specifies the name of an object as a character string. Availability Local, full, lightweight, and independent clients.
PAGE 48
• • Add Remove Add Summary Adds an object to the specified collection. Availability Local, full, lightweight, and independent clients. Note that some collections are not available to Independent clients. Syntax objectColl.Add name Added to API Element Description objectColl The collection being acted upon. name A String value specifying the name of the object being added. Prior to LNS Release 3.0. Remove Summary Removes an object from the specified collection.
PAGE 49
Syntax classIdValue = object.ClassId Element Description classIdValue The object class of the object. The following value is defined for the Accounts object in the ConstClassIds constant: 55 lcaClassIdAccounts object The object to be acted on. Data Type Integer. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. Count Summary Returns the number of objects in a collection.
PAGE 50
Element Description retrievedObject The object retrieved from the collection. collObject The collection object to be acted on. index A Long type specifying the ordinal index of the object to retrieve. stringExpression A string type specifying the name of the object to retrieve. Data Type Object. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API.
PAGE 51
ActivationLicense An ActivationLicense object represents a snapshot of the current activation license and related information on the OpenLNS Server at the time it was first accessed. The following table summarizes the ActivationLicense object. Description A snapshot of the current activation license on the OpenLNS Server. Added to API OpenLNS. Accessed Through System object. Default Property None.
PAGE 52
• • • • • • • • • • DeviceCapacity DeviceCapacityConsumed ExpirationDate LicesnseId LicenseStatus IsTrialLicense MaxOpenSystems RequiredVersion RunTimeLimit RunTimeRemaining ActivatedVersion Summary The version number that the license covers. If there is no valid license, this value is an empty string. Availability Local, full, and lightweight clients. Syntax version = alObject.ActivatedVersion Element Description version The version number that the license covers.
PAGE 53
Comments This property allows the object type to be determined when it is unknown (for example, when the object was accessed using the Parent property of another object). DaysRemaining Summary Indicates the number of days remaining before the OpenLNS Server license expires. Availability Local, full, and lightweight clients. Syntax days = alObject.DaysRemaining Element Description days The number of days until the license expires.
PAGE 54
database, excluding NSDs and routers. A device that has been added without specifying both a device template and a channel is not considered “defined” until that device has been commissioned. Availability Local, full, and lightweight clients. Syntax numberDevices = alObject.DeviceCapacityConsumed Element Description numberDevices The number of devices that have been defined in the database. alObject The ActivationLicense object to be acted on. Data Type Integer. Read/Write Read only.
PAGE 55
Data Type String. Read/Write Read only. Added to API OpenLNS. LicenseStatus Summary Indicates whether the activation license is valid, and indicates why an activation license is invalid. Availability Local, full, and lightweight clients. Syntax stateValue = alObject.LicenseStatus Element Description stateValue The enumerated values for this element, which are contained in the ConstActivationLicenseStatus constant, are as follows: 0 lcaActivationLicenseStatusActivated The license is valid.
PAGE 56
whether the activation license is a trial license. TRUE. The activation license is a trial license. FALSE. The activation license is not a trial license. alObject Data Type Boolean. Read/Write Read only. Added to API OpenLNS. The ActivationLicense object to be acted on. MaxOpenSystems Summary Indicates the maximum number of local systems that can be opened at a given time on this computer. Availability Local, full, and lightweight clients. Syntax numberSystems = alObject.
PAGE 57
Data Type String. Read/Write Read only. Added to API OpenLNS. RunTimeLimit Summary The maximum number of minutes that the application can use LNS after opening the first network. Availability Local, full, and lightweight clients. Syntax timeValue = alObject. RunTimeLimit Element Description timeValue The maximum number of minutes that the application can use LNS after opening the first network. A value of lcaLicenseNoRestriction (-1) indicates that there is no runtime limit.
PAGE 58
Alias The following table summarizes the Alias object. Description Represents an alias in-use for a network variable on an application device. Added to API Prior to LNS Release 3.0. Accessed Through Aliases collection object Default Property Index property. Methods None. Properties • • • • ClassID Index Parent Selector Methods The Alias object does not contain any methods.
PAGE 59
Comments This property allows the object type to be determined when it is unknown (for example, when the object was accessed using the Parent property of another object). Index Summary Returns the index within an application device of the network variable alias. Availability Local, full, and lightweight clients. Syntax index = object.Index Valid Values Element Description object The object to be acted on. index Index of the message tag or network variable.
PAGE 60
added to the API. Comments The parent object is determined by the means in which a child object is accessed, not by the OpenLNS Object hierarchy. Selector Summary The network variable selector value assigned to this network variable alias. When a device is installed, selector values that represent unbound network variables are assigned to the network variables in that device. When placing the network variable in a connection, the OpenLNS Object Server assigns a value representing that connection.
PAGE 61
• • Parent _NewEnum Methods The Aliases object contains the following methods. • • ItemByIndex Refresh ItemByIndex Summary Retrieves an Alias object from an Aliases collection. The Alias object to be retrieved must be specified by its index value. Availability Local, full, and lightweight clients. Syntax itemObject = itemsColl.ItemByIndex index Added to API Element Description itemObject The Alias object retrieved from the collection. itemsColl The Aliases collection to be acted on.
PAGE 62
ClassId Summary Identifies the object class of this object. This property allows the object type to be determined when it is unknown (for example, when the object was accessed using the Parent property of another object). Availability Local, full, lightweight, and independent clients. Note that some objects containing this property are not available to Independent clients. Syntax classIdValue = object.ClassId Element Description classIdValue The object class of the object.
PAGE 63
property. Index values start at 1. Availability Local, full, lightweight, and independent clients. Note that some objects containing this property are not available to Independent clients. Syntax retrievedObject = collObject.Item(index) retrievedObject = collObject.Item(stringExpression) Element Description retrievedObject The object retrieved from the collection. collObject The collection object to be acted on. index A Long type specifying the ordinal index of the object to retrieve.
PAGE 64
you can browse a collection to find a particular item by using the _NewEnum property. See the IEnumVARIANT interface for details. • If you are developing your OpenLNS app in Visual Basic, you do not need to use the _NewEnum property because it is automatically used in the implementation of For Each ... Next statements. • If you are developing your OpenLNS app in C#, you do not need to use the _NewEnum property explicitly because it is automatically used in the implemention of foreach statements.
PAGE 65
Properties • • • • • • • • • • ReleasePendingUpdates Replace ReplaceEx ReplaceEx Reset ResyncToTemplate Test Upgrade UploadConfigProperties Wink • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • AliasCapacity AliasUseCount AppImagePath AttachmentStatus AuthenticationEnabled BitmapFilePath Channel ClassId CommissionStatus ConfigurationState ConnectionUpdateType Description DetailInfo DeviceTemplate Extensions Handle HasBeenCommissioned IconFilePath InitialAuthenticationK
PAGE 66
• • • Subnets Subsystems Upgrade Requirement Methods The AppDevice object contains the following methods. • • • • • • • • • • • • • • • • • • • • • • ClearStatus Commission CommissionEx Decommission DownloadConfigProperties GetMessagePoint Load MoveEx PostMove PreMove PropagateDeviceConfigUpdates Reboot ReleasePendingUpdates Replace ReplaceEx ReplaceEx Reset ResyncToTemplate Test Upgrade UploadConfigProperties Wink ClearStatus Summary Clears the status information stored in the device.
PAGE 67
image. Adding an application device to the system is a two-step operation. First, you should define the device and load the device’s application image with the Load or LoadEx methods. Then, you should commission it. You can use the Add methods of the AppDevices object to define the application device. You can then use the Commission method to assign that definition to an actual physical device.
PAGE 68
lcaConfigPropOptLoadValues and lcaConfigPropOptLoadUnknown download options when you call DownloadConfigProperties. This will set any unknown configuration properties in the AppDevice object in the OpenLNS database to the default values, and then set all configuration property information in the physical device on the network to match the information stored in the OpenLNS database.
PAGE 69
knowing its authentication key, since the device has authentication enabled. If the InitialAuthenticationKey is set prior to commissioning the device or router, OpenLNS will use this key to authenticate messages sent to the device or router during the commissioning process. See Chapters 5 and 6 of the OpenLNS Programmer’s Guide for more information on the steps you should take when installing devices on a network and commissioning those devices. Availability Local, full, and lightweight clients.
PAGE 70
lcaMgmtModeDeferConfigUpdates (1). 1 lcaCommissionFlagPropagate Propagates the device’s network image in the OpenLNS database to the physical device when the network management mode is set to lcaMgmtModeDeferConfigUpdates (1). If this will cause network inconsistencies, OpenLNS will defer the updates, and the NS, #4039 lcaErrNsUpdatesDeferred exception will be thrown.
PAGE 71
value that is based on the amount of time it will take for a request message to be sent on the channel, and for the response message to be sent back on the channel. You should also note that you can set the expected delay for a message to be sent to a specific device by writing to the Delay property of the AppDevice object. Availability Local, full, and lightweight clients. Syntax delayValue = channelObject.Delay Element Description delayValue The delay associated with the channel, in milliseconds.
PAGE 72
download Options An Integer value specifying the download options. These values can be ORed together; however, you must set the lcaConfigPropOptLoadValues (1) option for the values to be downloaded into the physical device. The values for this element, which are stored in the ConstConfigPropOptions constant, are as follows: 0 lcaConfigPropOptLoadDefinitions This option has no effect during a download.
PAGE 73
to fail. To exclude those configuration properties from a download, you should OR this value with the lcaConfigPropOptExcludeNvTypeDefa ults (512) value. 4 lcaConfigPropOptLoadUnknown Sets all unknown configuration property values in the AppDevice object to the default values stored in the DeviceTemplate, and then downloads all known values into the physical device (if the lcaConfigPropOptLoadValues flag is set).
PAGE 74
the network. 32 lcaConfigPropOptSetMfgOnlyUnknown Sets all manufacturing only configuration properties to unknown. The values will not be downloaded into the physical device. 64 lcaConfigPropOptExcludeDeviceSpecific Downloads only those configuration properties that do not have the device-specific attribute set into the device.
PAGE 75
operations initiated by other flags passed to the DownloadConfigProperties method. However, updates to the device initiated by the other flags will be cancelled. For example, when combining this value with lcaConfigPropOptSetDefaults (2), the operation will set the values in the database to their defaults, but the pending update flag on the device will be cleared. As a result, those values will not be loaded into the device.
PAGE 76
send a value on the created monitor point. The device does not need to be commissioned to call this method. The device's application determines how it will react to any messages sent using this MsgMonitorPoint object. Note that you cannot use the message point returned by this method to send a message to a Network Service Device. If you invoke this method on an AppDevice object contained by a NetworkServiceDevice object, the NS, #16 lcaErrNsNotImplemented exception will be thrown.
PAGE 77
Load Summary Loads the application image specified by the AppImagePath property into a device. This method loads the application image specified by the AppImagePath property into a device. The application image must be in the binary format used by OpenLNS, (an APB file type). A transaction is started implicitly when this method is called. If OpenLNS detects an error while the load is in progress, it automatically cancels the transaction.
PAGE 78
application download. The system image used by the device must be compatible with the application image being loaded for the operation to complete successfully. If it is not, the application image will fail to load and an NS error will be generated. However, some devices support the use of the LoadEx method, which will automatically upgrade the system image in the device if it is not compatible with the application image being loaded.
PAGE 79
LoadEx Summary Loads the application image specified by the AppImagePath property into a device. This method is the same as the Load method except that it provides additional options that you can choose from when commissioning the device. For example, you can specify options to upgrade the system image of the device if it is not compatible with the application image being loaded (see the description of the options element for more information).
PAGE 80
variants. Requires the system image to be stored in flash and to have at least 32K bytes of contiguous flash starting at location 0. • PL 3150 (Versions 14–19). Supports both 512 byte EEPROM and 2K EEPROM system image variants. Requires the system image to be stored in flash and to have at least 32K bytes of contiguous flash starting at location 0. See the Load method for more general information on loading application devices.
PAGE 81
You first need to invoke it with the lcaMovePrePhysical flag (analogous to the PreMove call), and then once the device has been moved, you need to invoke it again with the lcaMovePostPhysical flag. You should invoke the BeginSession method to begin a session before using the MoveEx method. This will allow your application to avoid some failure scenarios that may occur when devices or routers are moved. Availability Local, full, and lightweight clients. Syntax appDeviceObject.
PAGE 82
PostMove Summary Completes the move of an application device from one channel (or subnet) to another. As part of the move, the device’s network address may change; however, the device’s Handle property cannot change. To move a device from one channel to another, follow these steps: 1. Invoke the BeginSession method to begin a session. This will allow your application to avoid some failure scenarios that may occur when devices or routers are moved. 2. Invoke the PreMove method.
PAGE 83
element, and the new subnet as the newSubnetObject element. If this method is called while not attached to the network, this message will throw an exception. Ignore it and call the PostMove method to move a device while in engineered mode. See the PostMove method for more information on the steps required to move an application device. Availability Local, full, and lightweight clients. Syntax appDeviceObject.
PAGE 84
lcaErrNsUpdatesDeferred exception will be thrown. In this case, the changes will not be propagated to the device until the network management mode (MgmtMode property) is set to lcaMgmtModePropagateConfigUpdates (0). Availability Local, full, and lightweight clients. Syntax device.PropagateDeviceConfigUpdates Added to API Element Description device The AppDevice representing the physical device to which configuration changes are to be propagated. LNS Release 3.20.
PAGE 85
If you accept an xDriver session with the doPostponeUpdates field set to True, you should open the network involved in the session, and enable all the monitor sets you want to use. Then, call the ReleasePendingUpdates method on the AppDevice object contained by the network’s MyVni property. This will release the updates that were withheld. For an example of this, see the example uplink application in the OpenLDV Programmer’s Guide, xDriver Supplement.
PAGE 86
replacements automatically in most cases. For information on when you might need to manually replace a Network Service Device and how to accomplish this, see the PreReplace method. Note: Do not read or write the State property of the device in the same explicit transaction as the invocation of this method. Availability Local, full, and lightweight clients. Syntax object.Replace Added to API Element Description object The application device to be replaced. Prior to LNS Release 3.0.
PAGE 87
Enter this value if do not want to use any options. 1 lcaReplaceFlagCopy Copies the values of all configuration properties (CPs) from the old device to the new device. If the old device has no CPs, configuration network variables will be copied, if present. Dynamic configuration network variables will not be copied. This flag may be ORed with lcaReplaceFlagExcludeMfgOnly (2) and lcaReplaceFlagUpload (4).
PAGE 88
deconfigured, regardless if this option has been set. This flag should be ORed with lcaReplaceFlagCopy (1). If it is not, all configuration property information for the old device will be removed from the OpenLNS database during the replacement, and it will not be stored in the new device. Added to API Prior to LNS Release 3.0. Reset Summary Sends a reset command to the application device.
PAGE 89
Syntax appDevice.ResyncToTemplate options Element Description appDevice The AppDevice object to be re-synced to reso files. options A Long value specifying the options to use when re-synchronizing the device. You can use this element to determine which objects on the device will be re-named during the resynchronization. These options may be ORed together.
PAGE 90
exist on the network, and respond to queries. If the device is installed, it must contain the expected domain/subnet/node address, and respond to subnet/node messages on that address. It must also contain the expected program ID, and the expected network management authentication setting (enabled or disabled). If network management authentication is enabled on the device, it must contain the correct system authentication key.
PAGE 91
2 lcaTestResultCommNeuronId The OpenLNS Server was unable to communicate with the device using Neuron ID addressing. Because the device has not been added or defined, the OpenLNS Server could not test the device using subnet/node ID addressing. The OpenLNS Server might not be attached to the network, the Network Service Device might be unconfigured, the target device might not be attached to the network, the target device may be powered off, or the target device may be faulty.
PAGE 92
to be recomissioned or it may be in the middle of a two-phase move. It also might be caused by intermittent device or channel failures. You may want to retry this method to see if the error persists. 6 lcaTestResultDuplicateSnode The OpenLNS Server was able to communicate with the device using Neuron ID addressing. However, when using subnet/node addressing, the responding device contains a different Neuron ID.
PAGE 93
You can resolve this problem by physically removing the obsolete device. 9 lcaTestResultMismatchSnode The OpenLNS Server was able to communicate with the device using Neuron ID addressing, but could not communicate with the device using its subnet/node addressing. Through the use of Neuron ID addressed messages, the NSS has found that the subnet/node address configured in the device does not match the database. This result will be returned if the device’s domain address has not been configured.
PAGE 94
Neuron ID addressing and subnet/node addressing. However, the device has network management authentication enabled despite the fact that the device’s AuthenticationEnabled property is set to FALSE. The device may have enabled network management authentication itself, the device may have been reconfigured by another network management tool, or the device may be faulty. It may be possible to restore the device using the Commission method.
PAGE 95
17 lcaTestResultInterfaceNotOnline The OpenLNS network interface that the OpenLNS Server is attempting to use is not Online. Recommission the NetworkServiceDevice of the System object by calling the System.NetworkServiceDevice.AppDev ice.Commission method, and make sure that the State property of the NetworkServiceDevice object (NetworkServiceDevice.AppDevice.State) is set to lcaOnline.
PAGE 96
The UpgradeStatus object returned by this method contains information indicating whether or not the upgrade was successful, as well as information describing the changes that were made to each component (for example, LonMark object, network variable, message tag, configuration property, monitor set, and monitor point) of the external interface during the upgrade.
PAGE 97
Echelon recommends that you upgrade the device before loading the application image. This will allow you to verify that the upgrade completed successfully before you load the application. After a device has been successfully upgraded, and the device application has been loaded (if necessary), you should re-commission it with the Commission or CommissionEx methods. For more information on replacing devices, see the Replace and ReplaceEx methods.
PAGE 98
UploadConfigProperties method can be invoked using either the AppDevice object or the Interface object. You cannot call the UploadConfigProperties method on a device until you commission it with the Commission method. Availability Local, full, and lightweight clients. Syntax object.UploadConfigProperties options Element Description object The AppDevice object in the OpenLNS database to which configuration properties are to be uploaded. options An Integer value specifying the desired upload options.
PAGE 99
this case, only values that are unknown in the OpenLNS database will be uploaded from the physical device. Following that, all the values stored in the OpenLNS database for the device will be set as the defaults in the DeviceTemplate object. This includes the values uploaded by the call to UploadConfigProperties, as well as all values that were known in the OpenLNS database before the operation began.
PAGE 100
be ORed with lcaConfigPropOptExcludeDeviceSpecific (64). Added to API Prior to LNS Release 3.0. Wink Summary Invokes the device’s Wink task. You can use this method to invoke the device’s Wink task. Application devices may be programmed with a Wink task which facilitates the identification and installation of the device. Wink tasks are device specific, but they may include such actions as the flashing of a light, or sounding of an alarm. Availability Local, full, and lightweight clients.
PAGE 101
• • • • • • • • • • • • • • • • • • • • • • • • • • • • • • Handle HasBeenCommissioned IconFilePath InitialAuthenticationKey Interface Interfaces LastTestInfo LastUpgrade Status Location LocationInNeuron MonitorSets MtHubs Name NetworkServiceDevice NeuronId NodeId NonGroupRcvTimer NsiHandle NVHubs Parent PingClass PendingNeuronId Priority ProgramId SelfDocumentation State SubnetId Subnets Subsystems Upgrade Requirement AliasCapacity Summary Returns the number of network variable aliases available on the
PAGE 102
Read/Write Read only. Added to API LNS Release 3.20. AliasUseCount Summary Returns the number of network variable aliases currently in use on the device. The AliasCapacity property returns the total number of network variable aliases available on the device. This information will be useful to you when managing connections in large systems. For more on network variable aliases, see Chapter 7 of the OpenLNS Programmer’s Guide. Availability Local, full, and lightweight clients.
PAGE 103
DeviceTemplate object's XifPath property. If this application device was not created from a device template, this property will be empty and must be assigned by the OpenLNS application. AttachmentStatus Summary Indicates whether the device is attached and in the proper state. Availability Local, full, and lightweight clients. Syntax returnValue = object.Count Element Description attachmentStatus The attachment status of the device.
PAGE 104
object’s AuthenticationKey property. 2. Set the AuthenticationEnabled property of the AppDevice object that represents the System object’s NetworkServiceDevice object to True. This enables authentication for all Network Service Devices on the system. As a result, the authentication key used by each Full and Lightweight client application must match the authentication key established in Step 1 the next time any of those applications opens the network.
PAGE 105
be installed in the device or router side by some external means. Setting this property to False results in removing the system key from the device or router side and disabling network management authentication on the device or router side. Only application devices whose AuthenticationEnabled property is set to True are permitted to participate in authenticated connections. If an application device participates in authenticated connections, you cannot set this property to False.
PAGE 106
AppDevices collection. Availability Local, full, and lightweight clients. Syntax channelObject = object.Channel Element Description channelObject The channel object. object The AppDevice object. Data Type Channel object. Read/Write Read only. Added to API Prior to LNS Release 3.0. ClassId Summary Identifies the object class of this object.
PAGE 107
commissioning, and lcaCommissionUpdatesCurrent (0) after a successful commission. This property will be set to lcaCommissionUpdatesPending (1) if any changes have been made to the database that affect the configuration of a router or application device, and those changes have not yet been propagated to the device. Changes may not yet have been propagated to the device because the network management mode is set to lcaMgmtModeDeferConfigUpdates (1), or because the transaction has not yet been committed.
PAGE 108
changes. 2 lcaCommissionUpdatesFailed Commission updates are currently pending or in progress, and the most recent update attempt failed. Data Type Integer. Read/Write Read only. Added to API Prior to LNS Release 3.0. ConfigurationState Summary Identifies the current configuration state of an application device. Availability Local, full, and lightweight clients. Syntax configStateValue = appDeviceObject.
PAGE 109
ConnectionUpdateType Summary Specifies in which state the AppDevice is placed while performing a connection update. Normally, when connecting network variables, the devices containing the network variables are taken hard-offline prior to making the update. Once all affected devices are in this state, each device is updated, placed in the configured state, and, if they were previously online, will be placed online again.
PAGE 110
Read/Write Read/write. Added to API Prior to LNS Release 3.0. Delay Summary Represents the average number of milliseconds required for a packet to get sent to the application device once queued. This property allows OpenLNS applications to specify the number of milleseconds expected for an application to send a message and receive an acknowledgment from the device. This enables the automatic timer calculations made by OpenLNS to be adjusted accordingly.
PAGE 111
Added to API This depends on the object used to access the property. Generally, this property exists for the objects listed above as soon as they are added to the API. See the applicable object to determine what release it was introduced in. DetailInfo Summary Contains the DetailInfo object associated with the specified AppDevice object. The DetailInfo object contains an error log and communications status information for the AppDevice object.
PAGE 112
identifier set by the manufacturer Availability Local, full, lightweight, and independent clients. Syntax extensionsColl = object.Extensions Element Description extensionsColl The Extensions collection object. object The object whose Extensions collection is being returned. Data Type Extensions collection object. Read/Write Read only. Added to API Prior to LNS Release 3.0. Handle Summary Contains the handle associated with the AppDevice object.
PAGE 113
whether all database changes have been propagated to the physical device. Availability Local, full, and lightweight clients. Syntax cmValue = appDeviceObject.HasBeenCommissioned Element Description cmValue A Boolean type indicating the commission state. appDeviceObject The AppDevice object to be acted on. Data Type Boolean. Read/Write Read only. Added to API Prior to LNS Release 3.0. IconFilePath Summary Specifies the path and file name of an icon (*.ICO file) representation of the object.
PAGE 114
its authentication key because the device has authentication enabled. If the InitialAuthenticationKey is set prior to commissioning the device or router, OpenLNS will use this key to authenticate messages sent to the device or router during the commissioning process. This property does not affect the key stored in the device or router after a successful commission.
PAGE 115
and custom interfaces associated with the device. The Interfaces collection allows virtual and custom interfaces to be added to any device that supports dynamic network variables, dynamic message tags, or dynamic LonMarkObjects. You add custom interfaces to a device with the Add method. Availability Local, full, and lightweight clients. Syntax interfaceColl = object.Interfaces Element Description interfaceColl The Interfaces collection to be returned. object The AppDevice object to be acted on.
PAGE 116
monitor set, and monitor point) during the upgrade. If you have not called the Upgrade method on a device and attempt to read this property, a LCA, #6 ObjectNotFound exception is thrown. Availability Local, full, and lightweight clients. Syntax upgradeStatusObject = adObject.LastUpgradeStatus Element Description upgradeStatusObject The UpgradeStatus object returned the last time the external interface of the device was upgraded. adObject The AppDevice object to be acted on.
PAGE 117
appDevObject.LocationinNeuron = locationValue Element Description locationValue The location as read from the device as a hex string. object The AppDevice object to be acted on. Data Type String (6 bytes). Read/Write Read only. Added to API Prior to LNS Release 3.0. MonitorSets Summary Contains a collection of all the MonitorSet objects on this device. Devices that do not support monitor sets will return an empty collection for this property.
PAGE 118
Added to API LNS Release 3.0. Name Summary Specifies the name of an object as a character string. This property is case sensitive. Searches by name must match case. This property can be a maximum of 85 characters long, but it may not contain the forward slash (/), back slash (\), period (.), and colon (:) characters. Availability Local, full, lightweight, and independent clients. Note that some objects that contain this property are not available to Independent clients. Syntax stringValue = object.
PAGE 119
Availability Local, full, and lightweight clients. Syntax neuronIdValue = object.NeuronId Element Description neuronIdValue The NeuronId of the object. object The AppDevice object to be acted on. Data Type String. Read/Write Read/write. Added to API Prior to LNS Release 3.0. NodeId Summary Contains the node ID associated with an application device. The NodeId and SubnetId comprise the logical network address assigned to an AppDevice when the Add method is invoked on it.
PAGE 120
NonGroupRcvTimerNonGroupRcvTimer_Property Summary The value of the device's non-group receive timer. This determines the time period within which receiving devices will treat messages from the same source with the same reference ID, but from a different connection, as duplicate messages. The default is calculated based on the network topology, channel delays and current connections that the device is involved in.
PAGE 121
Syntax handleValue = nsdObject.NsiHandle Element Description handleValue The NSI’s handle. nsdObject The NetworkServiceDevice to be acted on Data Type Long. Read/Write Read only. Added to API Prior to LNS Release 3.0. NVHubs Summary The network variables in the connections of this application device that represent the hubs of those connections (note that the hubs are not necessarily on this application device).
PAGE 122
object Any object for which the parent is desired. Data Type Object. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for the objects listed above as soon as they are added to the API. PingClass Summary Determines the frequency with which a device is tested (pinged) to determine if it is still attached to the network. This property classifies devices based on the probability that the device may be detached.
PAGE 123
System object's PingIntervals property. Data Type Integer. Read/Write Read/write. Added to API Prior to LNS Release 3.0. PendingNeuronIdPendingNeuronId_Property Summary Contains the neuron ID that will be set when the device is commissioned. If a device is commissioned with one Neuron ID, then replaced, then the new Neuron ID is set, the NeuronId property will still show the old Neuron ID until the Commission method is called. This property allows the new Neuron ID to be read before commissioning.
PAGE 124
127 lcaLNSNodePriorityMax Represents the maximum number of priority slots on any LonTalk channel. Do not set the MaxPriority property to a value greater than this. 255 lcaLNSNodePriorityAny The Object Server will assign the AppDevice object the next available, or least used, priority slot on the channel. object The AppDevice object to be acted on. Data Type Integer. Read/Write Read/write. Added to API Prior to LNS Release 3.0. ProgramId Summary Stores the program ID for the application device.
PAGE 125
Availability Local, full, and lightweight clients. Syntax descriptionString = object.SelfDocumentation Element Description programIdValue The program ID value of the object. object The object to be acted on. Data Type String. Read/Write Read only. Added to API Prior to LNS Release 3.0. State Summary Describes the state of a device. You cannot set the state of a device in the same transaction as an Add, Commission, or Replace method.
PAGE 126
properties are read-only. 2 lcaStateUncnfg The application is loaded but the configuration is either not loaded, being reloaded, or deemed corrupted due to a configuration checksum error. A Neuron Chip also can make itself unconfigured by calling the Neuron C function go_unconfigured(). The device's service LED flashes at a one second rate in this state.
PAGE 127
mode). The device's service LED is off in this state. object The device to be acted on. Data Type Integer. Read/Write Read /write. Added to API Prior to LNS Release 3.0. SubnetId Summary Contains the ID of the subnet. The AppDevice object's SubnetId property identifies the subnet the device is part of. This property can be used in conjunction with the NodeId property to uniquely identify a device. Note: As of OpenLNS, you can write to this property.
PAGE 128
Subsystems Summary Contains the Subsystem collection object associated with the specified AppDevice. A Subsystem object can in turn contain a collection of Subsystems. A System object’s Subsystems collection contains two default Subsystems upon creation. These Subsystems are named "ALL", which lists all of the devices in the system and "Discovered", which lists all devices discovered by the object server that have not yet been associated with a subsystem.
PAGE 129
Syntax upgradeReqValue = adObject.UpgradeRequirement Element Description upgradeReqValue An enumerated value indicating whether the device's application matches the application information in the OpenLNS database. The values for this property, which are stored in the ConstUpgrade Requirement constant, are as follows: 0 lcaUgReqNotRequired Indicates that the device's application does not need to be upgraded.
PAGE 130
Methods The AppDevices object contains the following methods. • • • • • Add AddReference ItemByHandle ItemByNeuronID Remove Add Summary Defines a new AppDevice object. This method adds a device to the system, but does not install the physical device. The Commission method is used to install the physical device after that device is defined using this method. Adding an application device to the system is a two or three step operation: definition, loading (optional), and commissioning. 1.
PAGE 131
• The device’s network variables and message tags are unbound; • The device’s priority slot is set to zero. • The device’s state is set to lcaStateCnfgOffline. • The device’s use of network management authentication is disabled. • The device’s non-group receive timer to be set to 2,048 ms. Other parts of the network image are not modified.
PAGE 132
commissioned. You should specify the channel whenever possible. channelObject The Channel object of the channel in which the device is to be placed. subnetObject The Subnet object of the subnet to which the device is to be assigned. This parameter is optional, and is not typically specified. If not specified, the Object Server determines the subnet assignment, creating one if necessary. To explicitly assign the subnet, specify a previously defined subnetObject.
PAGE 133
Added to API Element Description collection The AppDevices collection to gain the reference. object The AppDevice object to be added. Prior to LNS Release 3.0. ItemByHandle Summary Retrieves an AppDevice object, specified by its handle, from an AppDevices collection. The AppDevice object to be retrieved must be specified by its handle. Availability Local, full, and lightweight clients. Syntax object = coll.
PAGE 134
If the application device in not a member of any other subsystem, then the application device is completely removed from the system. The device is removed from all connections, removed from the system domain, and placed in the unconfigured state; the device’s channel ID is set to 0. No other changes are made in the device’s network image. The NSS Handle is also freed and is available for use by the Object Server. An AppDevice object can only be removed from a "regular" subsystem.
PAGE 135
object The object to be acted on. Data Type Integer. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. Comments This property allows the object type to be determined when it is unknown (for example, when the object was accessed using the Parent property of another object). Count Summary Returns the number of objects in a collection.
PAGE 136
stringExpression A string type specifying the name of the object to retrieve. Data Type Object. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. Parent Summary Returns the object that spawned the current child object. Availability Local, full, lightweight, and independent clients. Note that some collection objects are not available to Independent clients.
PAGE 137
Availability Local, full, and lightweight clients. Syntax retrievedObject = collObject._NewEnum Element Description retrievedObject An expression that evaluates to the object retrieved. collObject An iterator object that can be used to access members of the collection. Data Type Object. Read/Write Read only. Added to API OpenLNS. Application Description Used to store application version, name, and state information. Added to API LNS Release 3.0.
PAGE 138
ClassId Summary Identifies the object class of this object. Availability Local, full, lightweight, and independent clients. Note that some objects containing this property are not available to Independent clients. Syntax classIdValue = object.ClassId Element Description classIdValue The object class of the object. The following value is defined for the Application object in the ConstClassIds constant: 70 lcaClassIdApplication object The object to be acted on. Data Type Integer.
PAGE 139
Syntax Added to API majVersion = appObject.MajorVersion Element Description majVersion The major version number of this application when it was compiled. appObject The Application object to be acted on. LNS Release 3.0. MinorAPIVersion Summary Contains the minor version of LNS used when the application was compiled. This property is used with the MajorApiVersion property to provide the full version information. This property is set to 255 if there is no available version information.
PAGE 140
Availability Local, full, lightweight, and independent clients. Note that some objects that contain this property are not available to Independent clients. Syntax stringValue = object.Name Element Description stringValue The name of the object. object The object to be acted on. Data Type String. Read/Write Read/write. Added to API Depends on the object used to access the property. Generally, this property exists for the objects listed above as soon as they are added to the API.
PAGE 141
ConstApplicationState constant, are as follows: 0 LcaApplOnline The application is currently executing. 1 LcaApplOffline The application is not currently executing. appObject Data Type Integer. Read/Write Read only. Added to API LNS Release 3.0. The Application object to be acted on. BufferConfiguration A BufferConfiguration object contains the communication buffer parameters for a RouterSide object. Changes made to the buffer count and size properties are temporary.
PAGE 142
Default Property None. Methods None. Properties • • • • • • • ClassId InputBufferCount InputBufferSize OutputBufferCount OutputBufferSize PriorityBufferCount PriorityBufferSize Methods The BufferConfiguration object does not contain any methods.
PAGE 143
InputBufferCount Summary Contains the value of the input buffer count used for router configuration. Changes made to this property are temporary. To save the new value and send it to the Router on the network, set the BufferConfiguration property of the RouterSide object to point to the modified BufferConfiguration object. The valid count values are discrete. If a specified value is invalid, the buffer count property will be rounded up to the next allowed value.
PAGE 144
Data Type Long. Read/Write Read/write. Added to API Prior to LNS Release 3.0. OutputBufferCount Summary Contains the value of the output buffer count used for router configuration. Changes made to this property are temporary. To save the new value and send it to the Router on the network, set the BufferConfiguration property of the original RouterSide object to point to the modified BufferConfiguration object. The valid count values are discrete.
PAGE 145
Element Description bufSize The output buffer size. bcObject The BufferConfiguration object to be acted on. Data Type Long. Read/Write Read/write. Added to API Prior to LNS Release 3.0. PriorityBufferCount Summary Contains the value of the priority buffer count used for router configuration. Changes made to this property are temporary.
PAGE 146
for more information. Availability Local, full, and lightweight clients. Syntax bufSize = bcObject.PriorityBufferCount Element Description bufSize The priority buffer size. bcObject The BufferConfiguration object to be acted on. Data Type Long. Read/Write Read/write. Added to API Prior to LNS Release 3.0. Channel A Channel object represents a single instance of a LONWORKS channel. Channel objects contain communication and transceiver information common to all devices on the channel.
PAGE 147
Properties The Channel object contains the following properties: • • • • • • • • • • • • • • AltPathType AppDevices BitmapFilePath ClassId Delay Description Extensions Handle IconFilePath MaxPriority Name Parent RouterDevices TransceiverId AltPathType Summary Specifies whether the channel requires an alternate path so that it can broadcast on separate frequencies. In some cases, the use of alternate frequencies improves communication on a channel.
PAGE 148
1 lcaChannelAltPathNotRequired This channel does not require use of the alternate path. This value should be set when a channel uses only PL-20s and PL-21s. These power line transceivers do not use the alternate path, but look the same to LNS as the PL-22, which does use the alternate path. 2 lcaChannelAltPathRequired This channel requires use of both the primary and alternate paths. This value should be set when using a custom transceiver that uses alternate frequencies. Data Type Integer.
PAGE 149
Syntax bmpFilePath = object.BitmapFilePath Element Description bmpFilePath The bitmap path and file name. object The object to be acted on. Data Type String. Read/Write Read/write. If you write to this property, you must specify the bitmap’s full path and file name (for example, C:\MyBMPs\Object.BMP). Added to API Prior to LNS Release 3.0. ClassId Summary Identifies the object class of this object. Availability Local, full, lightweight, and independent clients.
PAGE 150
size and channel transceiver type. When you write to this property, you should note that the delays for transactions on a given channel must be calculated as round-trip delays. Make sure you set this property to a value that is based on the amount of time it will take for a request message to be sent on the channel, and for the response message to be sent back on the channel.
PAGE 151
manufacturers. Each object is identified with a unique identifier set by the manufacturer Availability Local, full, lightweight, and independent clients. Syntax extensionsColl = object.Extensions Element Description extensionsColl The Extensions collection object. object The object whose Extensions collection is being returned. Data Type Extensions collection object. Read/Write Read only. Added to API Prior to LNS Release 3.0.
PAGE 152
The object to be acted on. object Data Type String. Read/Write Read/write. If you write to this property, you must specify the bitmap’s full path and file name (for example, C:\MyICOs\Object.ICO). The icon file should contain the following representations: • • • • Added to API Standard (32x32 pixels) with 256 colors Small (16x16) with 16 colors Monochrome (32x32) Large (48x48) with 256 colors Prior to LNS Release 3.0.
PAGE 153
Availability Local, full, lightweight, and independent clients. Note that some objects that contain this property are not available to Independent clients. Syntax stringValue = object.Name Element Description stringValue The name of the object. object The object to be acted on. Data Type String. Read/Write Read/write. Added to API Depends on the object used to access the property. Generally, this property exists for the objects listed above as soon as they are added to the API.
PAGE 154
routersCollection The Routers collection returned. Data Type Routers collection object. Read/Write Read only. Added to API Prior to LNS Release 3.0. TransceiverId Summary Contains the current transceiver ID of the channel. Availability Local, full, and lightweight clients. Syntax idValue = channelObject.TransceiverId Element Description idValue The transceiver ID value. The TransceiverId property can contain a standard transceiver ID (1-29) or a custom ID (30).
PAGE 155
transceiver. 11 lcaXcvrTP_RS485_1250 TP/RS485-1250 LonWork transceiver. 12 lcaXcvrTP_RS485_78 TP/RS-485-78 LONWORKS transceiver. 14 lcaXcvrPL_20A_LOW The low-powered PL-20A-LOW channel used with PLT-20, PLT-21, PLT-22, PLT-22A and Power Line Smart Transceivers using the CENELEC Aband. 15 lcaXcvrPL_20A The PL-20A channel used with PLT-20, PLT-21, PLT-22, PLT-22A and Power Line Smart Transceivers using the CENELEC A-band.
PAGE 156
29 lcaXcvrDC_1250 DC-1250 LONWORKS transceiver. channelObject Channel object to be acted upon. Data Type Long. Read/Write Read/write. Added to API Prior to LNS Release 3.0. Channels A Channels object is a collection of Channel objects. The instance of this collection accessed through the Network object contains all of the Channel objects in the network. Description Represents a collection of Channel objects. Added to API Prior to LNS Release 3.0.
PAGE 157
Element Description channelObject The newly defined channel object. channelsObject The Channels collection object. channelName A String containing the name of the channel. transceiverId A Long value indicating the transceiver type for the channel. The enumerated values for this element, which correspond to standard transceiver types, are stored in the ConstTransceiverId constant. The values are as follows: 1 lcaXcvrTP_XF_78 TP/XF-78 LONWORKS transceiver.
PAGE 158
CENELEC A-band. 16 lcaXcvrPL_20C PLT-20, PLT-21, and PLT-22 LONWORKS transceivers using CENELEC C-band. 17 lcaXcvrPL_20N PLT-20, PLT-21, and PLT-22 LONWORKS transceivers using Non-CENELEC band. 18 lcaXcvrPL_30 PLT-30 LONWORKS transceiver. 24 lcaXcvrFO_10 FO-10 LONWORKS transceiver. 25 lcaXcvrIP_10L IP-10 LAN Low Latency LONWORKS transceiver. 26 lcaXcvrIP_10W IP-10 WAN High Latency LONWORKS transceiver. 27 lcaXcvrDC_78 DC-78 LONWORKS transceiver. 28 lcaXcvrDC_625 DC-625 LONWORKS transceiver.
PAGE 159
Remove Summary Removes a channel from the network. A channel may only be removed if there are no devices or routers assigned to it. Availability Local, full, and lightweight clients. Syntax channelsColl.Remove indexName Added to API Element Description channelsColl The Channels collection object containing the channel to be removed. indexName A Long value specifying the collection index of the Channel object to remove, or a String value specifying the name of the Channel object to remove.
PAGE 160
added to the API. Comments This property allows the object type to be determined when it is unknown (for example, when the object was accessed using the Parent property of another object). Count Summary Returns the number of objects in a collection. You can use this property to enumerate a collection object. Availability Local, full, lightweight, and independent clients. Note that some collection objects are not available to Independent clients. Syntax returnValue = object.
PAGE 161
Syntax filterValue = channelsCollection.FilterType Element Description filterValue The active filter type. The valid values for this property, which are contained in the ConstChannelFilterTypes constant, are as follows: 0 lcaChannelFilterNone All objects in the collection are shown. 1 lcaChannelFilterAdjacent Only channels adjacent to RefChannel1 (as Channel object) are shown. 2 lcaChannelFilterPath Only channels connecting RefChannel1 (as Channel object) and RefChannel2 (as Channel object) are shown.
PAGE 162
collObject The Channels collection object to be acted on. index A Long type specifying the ordinal index of the Channel object to be retrieved. stringExpression A string type specifying the name of the Channel object to be retrieved. Data Type Object. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. Parent Summary Returns the object that spawned the current child object.
PAGE 163
• If the FilterType property is set to lcaChannelFilterPath, the Channels collection object will access all channels connecting the channels specified by RefChannel1 and RefChannel2. RefChannel1 is not used for any other value of the FilterType property. Availability Local, full, and lightweight clients. Syntax filterValue = channelsColl.RefChannel1 Element Description channelObject The Channel object to be used as a reference. channelsColl The Channels collection object.
PAGE 164
set to lcaChannelFilterTransceiver. When this is the case, the Channels collection object will access the Channel objects with the TransceiverId property equal to this property. Availability Local, full, and lightweight clients. Syntax rtTypeValue = channelsColl.RefTransceiverType Element Description channelsColl The Channels collection to be acted on. rtTypeValue Transceiver ID value Data Type Integer. Read/Write Read/write. Added to API Prior to LNS Release 3.0.
PAGE 165
ComponentApp This object describes a LONWORKS plug-in command. ComponentApps collection objects are contained in the ObjectServer, System, and DeviceTemplate objects. An LCA director application can determine what plug-in commands are available by examining the ComponentApp objects and can launch the plug-in using the RegisteredServer property. Plug-in commands to be used by all networks are listed in the ComponentApps collection in the ObjectServer object.
PAGE 166
ClassId Summary Identifies the object class of this object. Availability Local, full, lightweight, and independent clients. Note that some objects containing this property are not available to Independent clients. Syntax classIdValue = object.ClassId Element Description classIdValue The object class of the object. The following value is defined for the ComponentApp object in the ConstClassIds constant: 30 lcaClassIdComponentApp object The object to be acted on. Data Type Integer.
PAGE 167
1 lcaCommandIdNew 2 lcaCommandIdEditSource 10 lcaCommandIdBuildImage 11 lcaCommandIdCommission 12 lcaCommandIdLoad 13 lcaCommandIdConfigure 14 lcaCommandIdCalibrate 15 lcaCommandIdConnect 20 lcaCommandIdBrowse 21 lcaCommandIdMonitor 22 lcaCommandIdControl 23 lcaCommandIdReport 24 lcaCommandIdProperties 30 lcaCommandIdOnline 31 lcaCommandIdOffline 32 lcaCommandIdReset 33 lcaCommandIdTest 34 lcaCommandIdWink 35 lcaCommandIdDebug 40 lcaCommandIdUninstall 41 lcaCommandIdReplace 50 lcaCommandIdRegister 51 lcaCom
PAGE 168
6 lcaClassIdSubsystems 7 lcaClassIdAppDevice 8 lcaClassIdAppDevices 9 lcaClassIdRouter 10 lcaClassIdRouters 11 lcaClassIdRouterSide 12 lcaClassIdChannel 13 lcaClassIdChannels 14 lcaClassIdNetworkInterface 15 lcaClassIdNetworkInterfaces 16 lcaClassIdSubnet 17 lcaClassIdSubnets 18 lcaClassIdConnections 19 lcaClassIdInterface 20 lcaClassIdInterfaces 21 lcaClassIdTemplateLibrary 22 lcaClassIdNetworkVariable 23 lcaClassIdNetworkVariables 24 lcaClassIdMessageTag 25 lcaClassIdMessageTags 26 lcaClassIdConfigProp 27
PAGE 169
object 59 lcaClassIdAliases 69 lcaClassIdPingIntervals 70 lcaClassIdApplication 71 lcaClassIdTestInfo 72 lcaClassIdDataPoint 73 lcaClassIdFormatSpec 74 lcaClassIdMonitorSet 75 lcaClassIdMonitorSets 76 lcaClassIdMsgMonitorOptions 77 lcaClassIdMsgMonitorPoint 78 lcaClassIdMsgMonitorPoints 79 lcaClassIdNvMonitorOptions 80 lcaClassIdNvMonitorPoint 81 lcaClassIdNvMonitorPoints 82 lcaClassIdSourceAddress 83 lcaClassIdLdrfLanguage 84 lcaClassIdLdrfLanguages 85 lcaClassIdServiceStatus 86 lcaClassIdUpgradeStatus 87
PAGE 170
implements the default action compAppObject The ComponentApp object to be acted on. Data Type Boolean. Read/Write Read/write. Added to API Prior to LNS Release 3.0. Description Summary Stores description information about the ComponentApps object. Availability Local, full, lightweight, and independent clients. Note that some collections are not available to Independent clients. Syntax stringValue = object.
PAGE 171
Name Summary Specifies the name of a ComponentApp object as a character string. This property is case sensitive. Searches by name must match case. This property can be a maximum of 85 characters long, but it may not contain the forward slash (/), back slash (\), period (.), and colon (:) characters. Availability Local, full, lightweight, and independent clients. Note that some objects that contain this property are not available to Independent clients. Syntax stringValue = object.
PAGE 172
RegisteredServer Summary Contains the plug-in name that is stored in the Windows registry for this component application. Component applications must follow the Windows component registration guidelines. Availability Local, full, lightweight, and independent clients. Syntax serverName = compAppObject.RegisteredServer Element Description compAppObject The ComponentApp object to be acted on. serverName The registered name of the plug-in as a string. Data Type String. Read/Write Read/write.
PAGE 173
Note that the Interface property of all AppDevice objects contain a ComponentApps collection; however, the behavior of this collection is unspecified. The following table summarizes the ComponentApps object. Description A collection of objects. Added to API Prior to LNS Release 3.0.
PAGE 174
the ComponentApp object for the possible values. Added to API Prior to LNS Release 3.0. Remove Summary Removes an object from the specified collection. Availability Local, full, lightweight, and independent clients. Note that some collections are not available to Independent clients. Syntax objectColl.Remove indexName Added to API Element Description objectColl The collection containing the object to be removed.
PAGE 175
Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. Comments This property allows the object type to be determined when it is unknown (for example, when the object was accessed using the Parent property of another object). Count Summary Returns the number of objects in a collection. You can use this property to enumerate a collection object.
PAGE 176
Data Type Object. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. Parent Summary Returns the object that spawned the current child object. Availability Local, full, lightweight, and independent clients. Note that some collection objects are not available to Independent clients. Syntax parentObject = object.
PAGE 177
Syntax retrievedObject = collObject._NewEnum Element Description retrievedObject An expression that evaluates to the object retrieved. collObject An iterator object that can be used to access members of the collection. Data Type Object. Read/Write Read only. Added to API OpenLNS. ConfigProperties A ConfigProperties object is a collection of ConfigProperty objects. Configuration properties may be associated with a device, LonMark object, or network variable.
PAGE 178
handle A Long value specifying the handle of the ConfigProperty object to be retrieved. Added to API LNS Release 3.0. Added to API Prior to LNS Release 3.0. Properties The ConfigProperties object contains the following properties: • • • • • ClassId Count Item Parent _NewEnum ClassId Summary Identifies the object class of this object. Availability Local, full, lightweight, and independent clients. Note that some objects containing this property are not available to Independent clients.
PAGE 179
Syntax returnValue = object.Count Element Description returnValue The number of objects in the collection as a long integer. object The collection object to be acted on. Data Type Long. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. Item Summary Returns a ConfigProperty object from a ConfigProperties collection.
PAGE 180
Parent Summary Returns the object that spawned the current child object. Availability Local, full, lightweight, and independent clients. Note that some collection objects are not available to Independent clients. Syntax parentObject = object.Parent Element Description parentObject The object that is the parent of the specified object. object Any object for which the parent is desired. Data Type Object. Read/Write Read only. Added to API Depends on the object used to access the property.
PAGE 181
Data Type Object. Read/Write Read only. Added to API OpenLNS. ConfigProperty A ConfigProperty object represents a single configuration property, which may be either a standard configuration property type (SCPT) or a user configuration property type (UCPT). The configuration property can be implemented on the target AppDevice as a configuration network variable or as part of a configuration file (using sequential access, sequential/random access, or direct memory access).
PAGE 182
Methods The ConfigProperties object contains the following methods: • • • • GetDataPoint GetRawValuesEx SetRawValuesEx SetValueToUnknown GetDataPoint Summary Returns a DataPoint object that can be used to read or write the configuration property value. Use this method to read and write configuration property values instead of the deprecated ValueFromDevice, RawValueFromDevice, Value and RawValue properties.
PAGE 183
The value of the ConfigProperty will be updated in the OpenLNS database and in the physical device each time you write to the value of the DataPoint. If the source ConfigProperty is device-specific, the value will be read directly from the device when you read the value of the DataPoint. If the source ConfigProperty is not device-specific, the value will be read from the database, as long as it is stored there.
PAGE 184
value is recommended only when updating the database with a value that has just been read from the device. For more information on this, see the description of the lcaDataSourceOptionsFromDevice (1) value. If you read the value of the data point, and the value does not exist in the OpenLNS database, then the NS, #113 lcaErrNsCpValueNotFound exception is thrown.
PAGE 185
retrieved. If you specify an invalid index, an LCA, #90 lcaValueOutOfRange exception is thrown. count Specify the number of elements to be retrieved. If this number exceeds the value of the ConfigProperty object’s Dimension property, an LCA, #90 lcaValueOutOfRange exception is thrown. options Use this element to determine whether OpenLNS will read the raw values of the ConfigProperty array elements from the OpenLNS database or the physical application device.
PAGE 186
Added to API LNS Release 3.20. SetRawValuesEx Summary Sets the raw value for a range of elements in an array configuration property. You can specify configuration property values as either a byte array or a Variant containing a byte array (MFC type VT_UI1 | VT_ARRAY). The application is responsible for creating the raw byte array that corresponds to the desired configuration property values. Availability Local, full, and lightweight clients. Syntax cpObject.
PAGE 187
just been read from the device (for example, create a data point with the lcaDataSourceOptionsFromDevice (1) option set, then set the SourceOptions property of the data point to this value and call the SetRawValuesEx method). Added to API LNS Release 3.20. SetValueToUnknown Summary Sets the value of the ConfigProperty object to an unknown state. You can use this method to clear the value of a ConfigProperty object from the OpenLNS database.
PAGE 188
• • • • • • • • • • • • • • • • • • ConstantAttribute Description DeviceSpecificAttribute Dimension FlagsByte FormatName FuncProfileDescription FuncProfileName FuncProfileProgrammaticName Handle ImplementationType Mode Name Parent Precision TypeInherits TypeIndex ValueStatus AppliesTo Summary Returns the collection of objects to which the configuration property applies.
PAGE 189
AppDevice or DeviceTemplate as a whole, a collection of LonMarkObjects, or a collection of NetworkVariable objects. This property returns a (generic) collection of objects to which the configuration property applies. This property indicates ther type of objects the configuration property applies. To access the actual objects to which the configuration property applies, use the AppliesTo property. Availability Local, full, and lightweight clients. Syntax objectType = cpObject.
PAGE 190
ByteLength Summary Returns the length (in bytes) of a single configuration property element. Multiplying this length by the number returned by the Dimension property gives you the total length (in bytes) of this configuration property. If this configuration property is not an array, the Dimension property returns 1, and the ByteLength property returns the full length of the configuration property.
PAGE 191
added to the API. Comments This property allows the object type to be determined when it is unknown (for example, when the object was accessed using the Parent property of another object). ConfigFileOffset Summary Specifies the byte offset into the configuration value file that implements the ConfigProperty object. A ConfigProperty object is implemented by a configuration network variable or a configuration value file.
PAGE 192
Read/Write Read only. Added to API OpenLNS. ConfigFileType Summary Specifies the type of configuration value file that implements the ConfigProperty object. A ConfigProperty object is implemented by a configuration network variable or a configuration value file. To determine how the configuration property is implemented, read the ImplementationType property of the ConfigProperty object.
PAGE 193
Syntax fileType = cpObject.ConfigFileType Element Description fileType The type of the configuration value file implementing this configuration property. The possible values for this property, which are stored in the ConstConfigFileTypes constant, are as follows: 1 lcaConfigFileWritable The configuration property is stored in the writable value file, which is the mandatory (first) value file that is typically stored in the read-write memory on the device.
PAGE 194
implemented by an array of network variables, array elements will be implemented by consecutive network variables. This property returns the network variable that implements the first element. To retrieve the network variables for subsequent elements, increment the index of the network variable the appropriate number of times, and call the ItemByIndex method on the NetworkVariables property of the main Interface object.
PAGE 195
by an array of network variables, the array elements will be implemented by consecutive network variables. This property returns the network variable index of the first element. To determine the network variable index for subsequent elements, simply increment this network variable index the appropriate number of times. Note: This property is not currently available from within a DeviceTemplate object; therefore, it will throw a LCA, #38 LCA_APP_DEVICE_REQUIRED exception when accessed.
PAGE 196
organization at the time. As a result, LNS 3.20 allows applications such as device plug-ins to modify the constant attribute by writing to this property. Set this property to True to turn on the constant attribute. Set this property to False to turn off the constant attribute. When modifying this property, you should note that some configuration properties are stored in non-writable storage, such a ROM. In this case, OpenLNS cannot verify whether it is possible to update the value or not.
PAGE 197
Description Summary Stores description information about the ConfigProperty object. Availability Local, full, lightweight, and independent clients. Note that some collections are not available to Independent clients. Syntax stringValue = object.Description Element Description stringValue A string description of the ConfigProperty object. object The ConfigProperty object to be acted on. Data Type String. Read/Write Read/write.
PAGE 198
installation. Therefore, you can modify the device-specific attribute by writing to this property. Set this property to True to turn on the device-specific attribute. Set this property to False to turn it off. For more information on configuration property attributes, see the Configuration Property Flags section of the LonMark Application-Layer Interoperability Guidelines. Availability Local, full, and lightweight clients. Syntax deviceSpecific = cpObject.
PAGE 199
Dimension Summary Returns the length (in bytes) of a single configuration property element. Multiplying this length by the number returned by the Dimension property gives you the total length (in bytes) of this configuration property. If this configuration property is not an array, the Dimension property returns 1, and the ByteLength property returns the full length of the configuration property.
PAGE 200
The configuration property is offline. 4 lcaCpFlagsConstant The configuration property has the constant attribute set. You can use LNS to read or write the value of the constant attribute in some cases. See the ConstantAttribute and DeviceSpecificAttribute properties for more information. 8 lcaCpFlagsReset The configuration property has been reset. 16 lcaCpFlagsManufactureOnly The configuration property is a manufacturer-only configuration property.
PAGE 201
a SNVT_xxx type, it will be formatted as specified by the format file. 2. If the ConfigProperty object’s type does not appear in the Device Resource File Type and Format files, or if it appears but is designated as a SNVT_xxx type, the OpenLNS Server will check to see if it applies to a standard network variable. If it does, it will be formatted according to the SNVT format specification in STANDARD.FMT. 3. As a third option, OpenLNS will use the Hex Byte String format as the default.
PAGE 202
that has the same name as the underlying type. This is called the root format for the type, and may be different from the default format for that type. In order to explicitly use this root format, you will need to append the ‘#’ character to the format name to indicate that you are specifying the format name (and not the type name) for this type.
PAGE 203
Data Type String. Read/Write Read/write. Added to API Prior to LNS Release 3.0. FuncProfileDescription Summary Provides a desciptive comment of the functional profile associated with the ConfigProperty object. This property is accessed from the functional profile template file associated with the object. This property is language dependent. Set the System object's ResourceLanguageId to control the language. Availability Local, full, and lightweight clients. Syntax description = object.
PAGE 204
Read/Write Read-only. Added to API Prior to LNS Release 3.0. FuncProfileProgrammaticName Summary Returns the functional profile programmatic name associated with the ConfigProperty object. This name is accessed from the functional profile template file associated with the object. The programmatic name is the base name stored for the object; it is not language dependent like the FuncProfileName property. Availability Local, full, and lightweight clients. Syntax progNameValue = Object.
PAGE 205
Once the implementation type is known, a client can retrieve the appropriate addressing information for the configuration property by reading either the ConfigNvIndex property (for NV-based CPs), or the ConfigFileType and ConfigFileOffset properties (for file-based CPs). This information is useful for tools that need to access configuration property values when OpenLNS is not available.
PAGE 206
Added to API OpenLNS. Mode Summary Returns the scope of the LonMark resource file containing the definition of the type used by this configuration property. The value is acquired from the device during the import of the LonMark information during installation. Availability Local, full, lightweight, and independent clients. Note that some objects containing this property are not available to Independent clients. Syntax classMode = cpObject.
PAGE 207
subclass and model. -1 lcaResourceScopeUnknown The scope of the resource file is not known, or could not be found. cpObject The ConfigProperty object to be acted on. Data Type Integer. Read/Write Read only. Added to API Prior to LNS Release 3.0. Name Summary Specifies the name of an object as a character string. This property is case sensitive. Searches by name must match case.
PAGE 208
Data Type Object. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. Comments The parent object is determined by the means in which a child object is accessed, not by the OpenLNS Object hierarchy. Precision Summary Determines the precision of the ConfigProperty object.
PAGE 209
account for changes to the configuration property’s type. Only configuration properties that apply to network variables can inherit types. For example, consider a configuration property with the TypeInherits property set to 1. If an application changes the type of the network variable to which the configuration property belongs, then OpenLNS changes the type of the configuration property automatically, since the TypeInherits property is set to 1.
PAGE 210
ValueStatus Summary Determines the current state of the value stored in the OpenLNS database for the ConfigProperty object. In some cases, the stored value for a configuration property in the OpenLNS database may not match the actual value of the configuration property in the physical device on the network. You can use this property to determine the current state of the value stored in the OpenLNS database for the configuration property. Availability Local, full, lightweight, and independent clients.
PAGE 211
OpenLNS database by calling the UploadConfigProperties method, and specifying lcaConfigPropOptLoadUnknow n (4) as the options element. 1 lcaConfigPropertyValueMgmtStatu sPendingUpdate The configuration property value is stored in the OpenLNS database, and has been updated. This value needs to be written to the device. OpenLNS will write the value to the device automatically as part of its normal sweep operations.
PAGE 212
Description A generic connection description template that can be applied to multiple network variable connections. Added to API Prior to LNS Release 3.0. Accessed Through ConnectDescTemplates collection object. NetworkVariable object.
PAGE 213
• UsePriorityFlag AliasOptions Summary Specifies how network variable aliases should be used in the connection. OpenLNS determines how it will use aliasing for a network variable in a connection when the network variable is added to the connection. As a result, changing the value of this property in the ConnectDescTemplate object being used by a connection will not affect the status of network variables that have already been added to the connection.
PAGE 214
the ConstConnBroadcastOptions constant, are as follows: 0 lcaBroadcastNever No broadcast addressing will be used. 1 lcaBroadcastGroup If a group address is required, but no groups are available, broadcast addressing will be used. A subnet broadcast will be used if possible; otherwise, a domain broadcast will be used. 2 lcaBroadcastAlways Broadcast addressing will be used in all cases. A subnet broadcast will be used, if possible; otherwise, a domain broadcast will be used.
PAGE 215
is unknown (for example, when the object was accessed using the Parent property of another object). Description Summary Stores description information about the ConnectDescTemplate object. Availability Local, full, lightweight, and independent clients. Note that some collections are not available to Independent clients. Syntax updateType = appDeviceObject.ConnectionUpdateType Element Description stringValue A string description of the ConnectDescTemplate object.
PAGE 216
the list of hubs; therefore, you should update the cached copy of the complete hub list when you add or delete a hub. Availability Local, full, and lightweight clients. Syntax mtCollection = cdtObject.MTHubs Element Description mtCollection The returned MessageTags collection. cdtObject The specified ConnectDescTemplate object. Data Type MessageTags collection object. Read/Write Read only. Added to API LNS Release 3.0. Name Summary Specifies the name of an object as a character string.
PAGE 217
Syntax nvColl = cdtObject.NVHubs Element Description cdtObject The ConnectDescTemplate object to be acted on. nvColl The collection of NetworkVariables to be returned. Data Type NetworkVariables collection object. Read/Write Read only. Added to API LNS Release 3.0. Parent Summary Returns the object that spawned the current child object. Availability Local, full, lightweight, and independent clients. Note that some collection objects are not available to Independent clients.
PAGE 218
Syntax propOptionsValue = cdtObject.PropertyOptions Element Description cdtObject The ConnectDescTemplate object to be acted on. propOptionsValue The value indicating which attributes are active. Multiple options can be ORed together to form the set of attributes that will be considered active in the connection. For example, you could OR lcaConnPropsServiceType with lcaConnPropsPriority to activate the ServiceType and UsePriorityFlag properties.
PAGE 219
RepeatCount property of the ConnectDescTemplate object. 32 lcaConnPropsRepeatTimer Select this value to activate the RepeatTimer property of the ConnectDescTemplate object. 64 lcaConnPropsReceiveTimer Select this value to activate the ReceiveTimer property of the ConnectDescTemplate object. 128 lcaConnPropsTransmitTimer Select this value to activate the TransmitTimer property of the ConnectDescTemplate object. 256 lcaConnPropsSuppressSourceAddr This option is no longer supported. Data Type Integer.
PAGE 220
default receive timer is calculated based on the network topology, channel delays, and other connections that exist on the system. This property accepts a range of encoded values from 0 to 15. The encoded receive timer values are as follows: Encoded Value 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 Seconds 0.128 0.192 0.256 0.384 0.512 0.768 1.024 1.536 2.048 3.072 4.096 6.144 8.192 12.288 16.384 24.576 Data Type Integer. Read/Write Read/write.
PAGE 221
Syntax repeatCountValue= cdtObject.RepeatCount Element Description cdtObject The ConnectDescTemplate object to be acted on. repeatCountValue The number of times (0–15) the messages will be repeated. This property is used to establish the repeat count. Data Type Integer. Read/Write Read/write. Added to API Prior to LNS Release 3.0. RepeatTimer Summary The encoded value of the repeat timer used for network management messages.
PAGE 222
repeatTimerValue The encoded value of the repeat timer. The default value for this property is determined based on the network topology. It is recommended that you do not change this from the default value. If the default value is not suitable for your application, it is recommended that you use the Delay property of each Channel object on the network to ensure that each message is sent at the correct interval. However, this property does accept a range of encoded values from 0 to 15.
PAGE 223
RetryCount Summary Sets the maximum number of times to resend messages sent with the request/response, unacknowledged/repeat, or acknowledged messaging services. This also sets the retry count for polling. You can set the service type for a connection by writing to the ServiceType property of the ConnectDescTemplate object.
PAGE 224
ServiceType Summary Stores the messaging service to be used for the connection. Note: This property will only be read by the OpenLNS Object Server if the lcaConnPropsServiceType option is set in the ConnectDescTemplate object’s PropertyOptions property. If the lcaConnPropServiceType option is not set, then OpenLNS Object Server will determine the service type for connections using the ConnectDescTemplate object by reading the ServiceType property of the connection’s hub network variable.
PAGE 225
acknowledgment messages. Do not use this service type on channels that support altnerate frequencies because the message will only be sent using the primary path. See the AltPathType property for more information. 3 lcaSvcRequest Request/Response messaging service. You can use this value when sending explicit messages if the device receiving the message is designed to send a response message for the specified message code. object The ConnectDescTemplate object to be acted on. Data Type Integer.
PAGE 226
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 0.024 0.032 0.048 0.064 0.096 0.128 0.192 0.256 0.384 0.512 0.768 1.024 1.536 2.048 3.072 Data Type Integer. Read/Write Read/write. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. UseAuthenticationFlag Summary Indicates whether this connection uses authentication. Availability Local, full, and lightweight clients. Syntax useAuthFlag = cdtObject.
PAGE 227
AuthenticationFlag. This property is used for network variable connections only. Data Type Boolean. Read/Write Read/write. Added to API Prior to LNS Release 3.0. UsePriorityFlag Summary Indicates whether this connection uses priority messaging. With priority messaging, the device with the highest priority sends its packet before any other devices can send theirs.
PAGE 228
ConnectDescTemplates A ConnectDescTemplates object is a collection of ConnectDescTemplate objects. The instance of this object is accessed through the TemplateLibrary object holds all of the ConnectDescTemplate objects in the system. The following table summarizes the ConnectDescTemplates object. Description A collection of ConnectDescTemplate objects. Added to API Prior to LNS Release 3.0. Accessed Through TemplateLibrary object.
PAGE 229
ItemByHandle Summary Retrieves a ConnectDescTemplate object, specified by its handle, from a ConnectDescTemplates collection. The ConnectDescTemplate object to be retrieved must be specified by its handle. Availability Local, full, and lightweight clients. Syntax object = coll.ItemByHandle(handle) Element Description object The object retrieved from the collection. coll The collection object. handle A Long value specifying the handle of the object to be retrieved. Added to API LNS Release 3.0.
PAGE 230
Independent clients. Syntax classIdValue = object.ClassId Element Description classIdValue The object class of the object. The following value is defined for the ComponentApps object in the ConstClassIds constant: 43 lcaClassIdConnectDescTemplates object The object to be acted on. Data Type Integer. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API.
PAGE 231
passing the object’s name as a string expression Availability Local, full, lightweight, and independent clients. Note that some objects containing this property are not available to Independent clients. Syntax retrievedObject = collObject.Item(index) retrievedObject = collObject.Item(stringExpression) Element Description retrievedObject The object retrieved from the collection. collObject The collection object to be acted on.
PAGE 232
For Each ... Next statements. • If you are developing your OpenLNS app in Visual C++, you can browse a collection to find a particular item by using the _NewEnum property. See the IEnumVARIANT interface for details. • If you are developing your OpenLNS app in Visual Basic, you do not need to use the _NewEnum property because it is automatically used in the implementation of For Each ... Next statements.
PAGE 233
Methods The Connections object does not contain any methods. Properties The Connections object contains the following properties: • • • • ClassId MessageTags NetworkVariables Parent ClassId Summary Identifies the object class of this object. Availability Local, full, lightweight, and independent clients. Note that some objects containing this property are not available to Independent clients. Syntax classIdValue = object.ClassId Element Description classIdValue The object class of the object.
PAGE 234
Data Type MessageTags collection object. Read/Write Read only. Added to API Prior to LNS Release 3.0. NetworkVariables Summary Represents all of the network variable connections in the system with a NetworkVariables collection object that contains the hub network variables for all connections. Availability Local, full, and lightweight clients. Syntax nvCollection = object.NetworkVariables Element Description nvCollection The returned NetworkVariables collection.
PAGE 235
CreditInfo OpenLNS applications can determine a system’s current licensing status by reading the properties of the CreditInfo object. These properties return information indicating the number of days until the LNS activation license expires or the number of application devices defined in a system. Note: As of OpenLNS, the DeficitCredits, LicensedCredits, LicenseType, MaxDeficitCredits, and UsedCredits properties of the CreditInfo object have been deprecated and no longer provide any useful information.
PAGE 236
Syntax classIdValue = object.ClassId Element Description classIdValue The object class of the object. The following value is defined for the CreditInfo object in the ConstClassIds constant: 53 lcaClassIdCreditInfo object The object to be acted on. Data Type Integer. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API.
PAGE 237
always 0. creditObject The CreditInfo object to be acted on. Data Type Long. Read/Write Read only. Added to API Prior to LNS Release 3.0. LicensedCredits (Deprecated) Summary Returns the currently licensed capacity, which is typically either 6 for trial licenses, or 65,535 for non-trial licenses. Note: In previous LNS releases, this property indicated the number of credits defined in the LNS license. Availability Local, full, and lightweight clients. Syntax licValue = object.
PAGE 238
MaxDeficitCredits (Deprecated) Summary Returns 0. Note: In previous LNS releases, this property indicted the the maximum number of deficit credits. Availability Local, full, and lightweight clients. Syntax maxValue = object.MaxDeficitCredits Element Description maxValue The maximum number of deficit credits, which is always 0. creditObject The CreditInfo object to be acted on. Data Type Long. Read/Write Read only. Added to API Prior to LNS Release 3.0.
PAGE 239
All the other properties contain information describing the errors that were discovered in the database during the validation. This information includes how many errors were discovered during the validation, how many of the errors OpenLNS was able to repair, how many of the errors OpenLNS was not able to repair, and the ErrorSummaries property, which contains a collection of DatabaseValidationErrorSummary objects.
PAGE 240
filename to where the file is to be exported. This must be a valid system path overwriteExisting This element is implemented if you specify a path and filename that already exists when you call this method. It has a Boolean value indicating whether the exported report should overwrite any existing files. TRUE. The existing file is overwritten. FALSE. The existing file is not overwritten, and an exception is thrown. Added to API LNS Release 3.20.
PAGE 241
Data Type Integer. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. ErrorSummaries Summary Contains the DatabaseValidationErrorSummaries collection object returned by the database validation report. The DatabaseValidationErrorSummaries collection object contains a group of DatabaseValidationErrorSummary objects.
PAGE 242
Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. PassedValidation Summary Indicates whether the network passed the database validation. Availability Local clients. Syntax validated = validationReport.PassedValidation Element Description validated A Boolean value indicating whether the network passed the validation procedure. TRUE.
PAGE 243
Syntax repairedCount = validationReport.RepairedErrors Element Description repairedCount The number of errors discovered during the database validation that were repaired. validationReport The DatabaseValidationReport object to be acted upon. Data Type Long. Read/Write Read only. Added to API LNS Release 3.20. TotalObjectsValidated Summary Contains the number of objects that were validated during the database validation.
PAGE 244
UnrepairedErrors Summary Contains the number of errors discovered during the database validation that were not repaired by OpenLNS. This includes all errors OpenLNS did not attempt to repair, and all errors OpenLNS was not able to repair. You can initiate a database validation on a network by calling the Validate method on the Network object.
PAGE 245
Description Indicates whether OpenLNS was able to repair a specific error during a database validation. Added to API LNS Release 3.20. Accessed Through DatabaseValidationErrorSummaries object. Default Property None. Methods None.
PAGE 246
Syntax classIdValue = object.ClassId Element Description classIdValue The object class of the object. The following value is defined for the DatabaseValidationErrorInstance object in the ConstClassIds constant: 92 lcaClassIdDatabaseValidation ErrorInstance object The object to be acted on. Data Type Integer. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API.
PAGE 247
A duplicate dynamic network variable was found on a device’s interface. 3 lcaDbValidationError MissingNV An invalid reference to a network variable, or a missing network variable, was discovered on a dynamic interface. 4 lcaDbValidationError MissingLMO An invalid reference to a LonMark object, or a missing LonMark object, was discovered on a dynamic interface. 5 lcaDbValidationError MissingCP An invalid reference to a configuration property, or a missing configuration property, was discovered.
PAGE 248
discovered. This is an internal error. 13 lcaDbValidationErrorDuplicateDynamicLM O Duplicate LonMark object data was discovered. This is an internal error. 14 lcaDbValidationErrorBadInterfaceCount Incorrect interface count data was discovered. This is an internal error. 15 lcaDbValidationErrorDuplicate StaticNV Duplicate static network variable data was discovered. This is an internal error. 16 lcaDbValidationErrorMissing Subsystem An invalid reference to a subsystem, or a missing subsystem, was discovered.
PAGE 249
Integrity This is an internal error. 132 lcaDbValidationErrorNssLink Integrity This is an internal error. validationObjec t Data Type Long. Read/Writ e Read only. Added to API LNS Release 3.20. The DatabaseValidationErrorInstance object being acted upon. ObjectClassInvolved Summary Indicates the class ID of the object that caused the error, which is referenced by this DatabaseValidationErrorInstance object.
PAGE 250
ObjectInternalId Summary Indicates the internal ID of the object that caused the error, which is referenced by this DatabaseValidationErrorInstance object. For example, if the error type is lcaDbValidationErrorMissingLMO, this property would contain the internal ID of the missing LonMarkObject. Availability Local clients. Syntax internalId = errorInstance.ObjectInternalId Element Description internalId The internal ID of the object that caused the error.
PAGE 251
Parent Summary Returns the object that spawned the current child object. The parent object is determined by the means in which a child object is accessed, not by the OpenLNS Object hierarchy. Availability Local, full, lightweight, and independent clients. Note that some collection objects are not available to Independent clients. Syntax parentObject = object.Parent Element Description parentObject The object that is the parent of the specified object.
PAGE 252
ParentObjectClass Summary Indicates the class ID of the parent of the object that caused the error, which is referenced by this DatabaseValidationErrorInstance object. For example, if the error type is lcaDbValidationErrorMissingLMO, this property would contain the class ID of the parent of the missing LonMarkObject (the object the missing LonMarkObject should be accessed through).
PAGE 253
ParentObjectInternalId Summary Indicates the internal ID of the parent of the object that caused the error, which is referenced by this DatabaseValidationErrorInstance object. For example, if the error type is lcaDbValidationErrorMissingNv, this property would contain the internal ID of the parent object of the missing NetworkVariable object (the name of the object the missing NetworkVariable object should be accessed through).
PAGE 254
ParentObjectName Summary Indicates the name of the parent of the object that caused the error, which is referenced by this DatabaseValidationErrorInstance object. For example, if the error type is lcaDbValidationErrorMissingNv, this property would contain the name of the parent object of the missing NetworkVariable object (the name of the object the missing NetworkVariable object should be accessed through).
PAGE 255
Syntax isRepairable = validationObject.Repairable Element Description validationObject The DatabaseValidationErrorInstance object being acted upon. isRepairable A Boolean value indicating whether OpenLNS can repair errors of this type. TRUE. OpenLNS can automatically repair this type of error (or this specific instance of an error type) as part of the database validation procedure.
PAGE 256
RepairAttempted Summary Indicates whether OpenLNS attempted to repair errors of this type during the validation. If you call the Validate method to initiate a database validation procedure and set the validationFlags element to lcaDbValidateAndRepair (1), OpenLNS will attempt to repair some errors it finds automatically. LNS may not be able to repair all error types or all the specific instances of an error type it encounters during the validation.
PAGE 257
Syntax repaired = errorReport.Repairable Element Description errorReport The DatabaseValidationErrorInstance object being acted upon. repaired This element indicates the action LNS performed to repair the error. The possible values that can be returned as this element, which are contained in the ConstDbValidationRepairLevel constant, are as follows: 0 lcaDbValidationNotRepaired No repair was performed on the object that caused the error, or the repair was not completed successfully.
PAGE 258
index number. The index number will be in the range of 1 to x, where x represents the value stored in the Count property. The following table summarizes the DatabaseValidationErrorSummaries object. Description A collection of DatabaseValidationErrorSummary objects. Added to API LNS Release 3.0. Accessed Through DatabaseValidationErrorSummary object. Default Property Item. Methods None.
PAGE 259
Data Type Integer. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. Count Summary Returns the number of objects in a collection. You can use this property to enumerate a collection object. Availability Local, full, lightweight, and independent clients. Note that some collection objects are not available to Independent clients. Syntax returnValue = object.
PAGE 260
Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. Parent Summary Returns the object that spawned the current child object. The parent object is determined by the means in which a child object is accessed, not by the OpenLNS Object hierarchy. Availability Local, full, lightweight, and independent clients.
PAGE 261
Syntax retrievedObject = collObject._NewEnum Element Description retrievedObject An expression that evaluates to the object retrieved. collObject An iterator object that can be used to access members of the collection. Data Type Object. Read/Write Read only. Added to API OpenLNS. DatabaseValidationErrorSummary The DatabaseValidationErrorSummary object contains information describing a certain type of error that was encountered during the database validation.
PAGE 262
ObjectDetailsAvailable property. If you specify an invalid number as the index element when invoking this method, the LCA, #15 lcaErrInvalidCollectionIndex exception will be thrown. Availability Local clients. Syntax errorInstance = validationSummary.GetInstance index Element Description errorInstance The DatabaseValidationErrorInstance object returned by the method. This object will contain detailed information about an error discovered during the validation.
PAGE 263
Element Description classIdValue The object class of the object. The following value is defined for the DatabaseValidationErrorSummary object in the ConstClassIds constant: 91 lcaClassId DatabaseValidationErrorSummary object The object to be acted on. Data Type Integer. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API.
PAGE 264
2 lcaDbValidationError DuplicateDynamicNV A duplicate dynamic network variable was found on a device’s interface. 3 lcaDbValidationError MissingNV An invalid reference to a network variable, or a missing network variable, was discovered on a dynamic interface. 4 lcaDbValidationError MissingLMO An invalid reference to a LonMark object, or a missing LonMark object, was discovered on a dynamic interface.
PAGE 265
12 lcaDbValidationErrorDuplicateDyna micMT Duplicate dynamic message tag data was discovered. This is an internal error. 13 lcaDbValidationErrorDuplicateDyna micLMO Duplicate LonMark object data was discovered. This is an internal error. 14 lcaDbValidationErrorBadInterfaceC ount Incorrect interface count data was discovered. This is an internal error. 15 lcaDbValidationErrorDuplicate StaticNV Duplicate static network variable data was discovered. This is an internal error.
PAGE 266
This is an internal error. 129 lcaDbValidationError NssUniqueKeyIntegrity This is an internal error. 130 lcaDbValidationErrorNss NonUniqueKeyIntegrity This is an internal error. 131 lcaDbValidationErrorNssSet Integrity This is an internal error. 132 lcaDbValidationErrorNssLink Integrity This is an internal error. validationObject Data Type Long. Read/Write Read only. Added to API LNS Release 3.20. The DatabaseValidationErrorSummary object being acted upon.
PAGE 267
ObjectDetailsAvailable Summary Indicates whether you can retrieve specific information about each instance of the error type from the object. The availability of this information depends primarily on the error type that this DatabaseValidationErrorSummary object represents. To determine the error type, read the ErrorType property of the DatabaseValidationErrorSummary object. Availability Local clients. Syntax detailsAvailable = validationSummary.
PAGE 268
Data Type Object. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. Repairable Summary Indicates whether OpenLNS can repair errors of this type as part of the database validation procedure. Availability Local clients. Syntax isRepairable = validationObject.Repairable Element Description validationObject The DatabaseValidationErrorSummary object being acted upon.
PAGE 269
RepairAttempted Summary Indicates whether OpenLNS attempted to repair errors of this type during the validation. If you call the Validate method to initiate a database validation procedure and set the validationFlags element to lcaDbValidateAndRepair (1), OpenLNS will attempt to repair some errors it finds automatically. LNS may not be able to repair all error types or all the specific instances of an error type it encounters during the validation.
PAGE 270
the network device containing the source object) by default. You can change this behavior by setting the AutoRead and AutoWrite properties of the DataPoint object to False. If these properties are set to False, OpenLNS will not update the source object every time the value properties of the data point are updated. However, in this case, you can still use data point’s Write method to write the value stored in these properties to the data point’s source object.
PAGE 271
• Write GetField Summary Gets a DataPoint object containing one field if the DataPoint object contains a structure. The AutoWrite property of the returned DataPoint is set to False; therefore, the Write method must be called explicitly to write the information to the network variable. The number of fields in a DataPoint object can be determined from the FieldCount property. The name of a field can be determined by that field's FieldName property.
PAGE 272
Syntax Added to API dpObject.Read Element Description dpObject The DataPoint object being acted upon. LNS Release 3. 0. Write Summary Updates the value of the source object controlled by this data point to match the current value stored in the data point’s Value, RawValue, and FormattedValue properties. Writing to either of the Value, RawValue, and FormattedValue properties updates the values of all three so that they always match.
PAGE 273
• • • • • • • • • • • • • • AutoWrite ClassId FieldCount FieldName FormatSpec FormattedValue MaxValue MessageCode MinValue Parent SourceIndex SourceOptions TypeName Value AutoRead Summary Determines whether the Read method will be called automatically whenever the Value, FormattedValue, or RawValue properties are read. You can use either of these properties to read the data point’s value; however, they are formatted differently. See these individual properties for more information.
PAGE 274
method). Data Type Boolean. Read/Write Read/write. Added to API LNS Release 3.0. AutoWrite Summary Determines whether the Write method will be called automatically whenever the FormattedValue, RawValue, or Value properties are written. You can use either of these properties to write to the data point’s value; however, they are formatted differently. See these individual properties for more information. Availability Local, full, lightweight, and independent clients.
PAGE 275
ClassId Summary Identifies the object class of this object. This property allows the object type to be determined when it is unknown (for example, when the object was accessed using the Parent property of another object). Availability Local, full, lightweight, and independent clients. Note that some objects containing this property are not available to Independent clients. Syntax classIdValue = object.ClassId Element Description classIdValue The object class of the object.
PAGE 276
FieldName Summary Indicates the name of the field if the DataPoint object contains multiple fields. If a DataPoint object contains multiple fields, each field is represented by its own DataPoint object. Each DataPoint object representing a field has a name; for example, a DataPoint which contained the time could have three fields called "hour", "minute", and "second". When the GetField method is called, the fields can be accessed either by name or by index number.
PAGE 277
FormatSpec Summary Contains the format specification information for data read from the FormattedValue property in the DataPoint object. This property contains a FormatSpec object that determines the base type to use when reading the formatted values of the data point or monitor point. For data points acquired through NetworkVariable objects, the default settings for the FormatSpec object are determined based on the network variable’s TypeSpec property.
PAGE 278
FormattedValue Summary Contains the value of the data point as a Variant. To read the value of a data point’s source object (the value of the source object in the OpenLNS database and on the network device containing the source object) as a formatted value, call the DataPoint object's Read method, and then read this property. If the AutoRead is set to True, the Read method will be called automatically each time this property is read.
PAGE 279
Formatter#16 lcaErrFormatIllegalDataOnUnformat exception will be thrown. You should note that OpenLNS only performs this range checking on scalar types. If you are using data points to read and write the value of a network variable or configuration property whose type is a structure and you want LNS to perform this range checking, you will need to create a separate data point for each field. You can create data points to represent each field in a given structure with the GetField method.
PAGE 280
MaxValue Summary Contains the maximum value that can be applied to the FormattedValue property of the DataPoint object. • If the data point’s source object is a network variable, the default value for this property is determined based on the network variable’s type, meaning that the default value will be the maximum value supported by the type. This value may be overridden by the network variable's entry in the Functional Profile Template used by the device hosting the network variable.
PAGE 281
Availability Local, full, lightweight, and independent clients. Note that some collection objects are not available to Independent clients. Syntax maxValue = dataPoint.SourceIndex Element Description maxValue The maximum value that can be applied to the FormattedValue property. dataPoint The DataPoint object being acted upon. Data Type Double. Read/Write Read/write. Added to API LNS Release 3.20. MessageCode Summary Contains the message code of the message associated with this data point.
PAGE 282
MinValue Summary Contains the minimum value that can be applied to the FormattedValue property of the DataPoint object. • If the data point’s source object is a network variable, the default value for this property is determined based on the network variable’s type, meaning that the default value will be the maximum value supported by the type. This value may be overridden by the network variable's entry in the Functional Profile Template used by the device hosting the network variable.
PAGE 283
Availability Local, full, lightweight, and independent clients. Note that some collection objects are not available to Independent clients. Syntax minValue = dataPoint.SourceIndex Element Description minValue The minimum value that can be applied to the FormattedValue property. dataPoint The DataPoint object being acted upon. Data Type Double. Read/Write Read/write. Added to API LNS Release 3.20. Parent Summary Returns the object that spawned the current child object.
PAGE 284
RawValue Summary Contains the value of the DataPoint as a raw byte array. To read the value of the data point’s source object (the value of the source object in the OpenLNS database and on the network device containing the source object) as a raw byte array, call the DataPoint object's Read method, and then read this property. If the AutoRead property is set to True, the Read method will be called automatically each time this property is read.
PAGE 285
to avoid passing invalid data to data point. Availability Local, full, lightweight, and independent clients. Note that some objects containing this property are not available to Independent clients. Syntax value = dpObject.RawValue Element Description value The value of the data point as a raw byte array. dpObject The DataPoint object to be acted on. Data Type Variant. Read/Write Read/write. Added to API LNS Release 3.0.
PAGE 286
Data Type Integer. Read/Write Read/write. Added to API LNS Release 3.20. SourceOptions Summary You can use this property to determine which options were used when the DataPoint was created. In doing so, you can determine what information will be returned or altered when you read or write to the value of that DataPoint. This property is most useful for DataPoints that were acquired through ConfigProperty objects. You can create such DataPoints with the GetDataPoint method.
PAGE 287
device-specific, the value will be read from the database, as long as it is stored there. If its value does not exist in the database, then the value will read directly from the device, as long as the network management mode (MgmtMode property) is set to lcaMgmtModePropagateConfigUpdate s (0).
PAGE 288
thrown. 3 lcaDataSourceOptionsTypeDefaultValue The data point value is set to the default value of configuration properties using the same type as the source configuration property. The default value is generally read from the functional profile template on the device containing the configuration property, or from the type definition for this configuration property type. Data points created with this option set are read-only.
PAGE 289
To read the value of the data point’s source object (the value of the source object in the OpenLNS database and on the physical device containing the source object) as an unformatted numeric value, use the DataPoint object's Read method, and then read this property. If the AutoRead property is set to TRUE, the Read method will automatically be called each time this property is read.
PAGE 290
turn off this attribute using OpenLNS. You can use the MinValue and MaxValue properties to set the minimum and maximum possible values for the data point. However, OpenLNS will only enforce the range established by these properties when you write to the FormattedValue property. You should program your application to enforce this range for the Value property to avoid passing invalid data to data point. Availability Local, full, lightweight, and independent clients. Syntax value = dpObject.
PAGE 291
Properties The DataValue object contains the following properties: • • • • • • • • • • • • AppDevice ClassId Data DataType FloatValue IntValue Length MonitorTag NetworkVariable SourceNodeId SourceSubnetId StringValue AppDevice Summary Identifies the application device that is the source of the network variable update represented by this DataValue object. The DataValue object represents a value from a network variable that is being monitored. It is returned by the OnNetworkVariableUpdate Event.
PAGE 292
Syntax classIdValue = object.ClassId Element Description classIdValue The object class of the object. The following value is defined for the DataPoint object in the ConstClassIds constant: 49 lcaClassIdDataValue object The object to be acted on. Data Type Integer. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. Data Summary INTERNAL USE ONLY Data Type Integer.
PAGE 293
Length Summary INTERNAL USE ONLY Data Type Integer. Read/Write Read only. Added to API Prior to LNS Release 3.0. MonitorTag Summary Contains the monitor tag value assigned to the network variable via its DsMonitorTag property. Availability Local, full, and lightweight clients. Syntax tagValue = dvObject.MonitorTag Element Description dvObject The DataValue object to be acted on. tagValue The value of the monitor tag as a long. Data Type Long Read/Write Read only.
PAGE 294
SourceNodeId Summary Indicates the node ID of the device making a network variable update to a host network variable. This value is only meaningful if the network variable being monitored is a host network variable. This property, along with the SourceSubnetId property, allows a number of devices on the network to each have a network variable explicitly bound to a single network variable on the host.
PAGE 295
SourceSubnetId Summary Indicates the subnet ID of the device making a network variable update to a host network variable. This value is only meaningful if the network variable being monitored is a host network variable. This property, along with the SourceNodeId property, allows a number of devices on the network to each have a network variable explicitly bound to a single network variable on the host.
PAGE 296
Accessed Through AppDevice object RouterSide object Default Property None. Methods None. Properties • • • • • • • • • • • • ClassId ErrorLog LostMessage MissedMessages ModelNumber Parent ReceiveTxFull ResetCause State TransactionTimeouts VersionNumber XmitErrors Methods The DetailInfo object does not contain any methods.
PAGE 297
classIdValue The object class of the object. The following value is defined for the DataPoint object in the ConstClassIds constant: 48 lcaClassIdDetailInfo object The object to be acted on. Data Type Integer. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. ErrorLog Summary The most recently logged firmware error. Availability Local, full, and lightweight clients.
PAGE 298
Element Description numMessages The number of lost messages. detailInfoObject The DetailInfo object from which to get the information. Data Type Long. Read/Write Read only. Added to API Prior to LNS Release 3.0. MissedMessages Summary Contains the number of times a packet was received and no network input buffer was available. This data is available for application devices and router sides. Availability Local, full, and lightweight clients. Syntax numMessages = object.
PAGE 299
object 13 lcaNeuronModel3120E5 14 lcaNeuronModel3120E4 15 lcaNeuronModelPL3120E4 16 lcaNeuronModelCY7C53120 32 lcaNeuronModelFT5000 33 lcaNeuronModel 5000 128 lcaNonNeuronModelGeneric 129 lcaNonNeuronModelPentagon 130 lcaNonNeuronModelMIPS The DetailInfo object from which to get the information. Data Type Long. Read/Write Read only. Added to API Prior to LNS Release 3.0. Parent Summary Returns the object that spawned the current child object.
PAGE 300
object The DetailInfo object from which to get the information. Data Type Long. Read/Write Read only. Added to API Prior to LNS Release 3.0. ResetCause Summary Contains the cause of the most recent Neuron Chip reset. This data is available for application devices and router sides. Availability Local, full, and lightweight clients. Syntax resetType = detailInfoObject.ResetCause Element Description resetType The type of reset.
PAGE 301
State Summary Describes the state of a device, router side, router, or system. This data is available for application devices and router sides. Setting the Device State You cannot set the state of a device in the same transaction as an Add, Commission, or Replace method. The state change may fail if the device has not been completely updated due to a previous communication problem or if the device has not been commissioned. If a failure occurs, use the Commission method to force an update of the device.
PAGE 302
function go_unconfigured(). The device's service LED flashes at a one second rate in this state. 3 lcaStateNoApplUncnfg No application is loaded yet, the application is in the process of being loaded, or the application has been deemed corrupted due to an application checksum error or signature inconsistency. The application does not run in this state. The device's service LED is steadily on in this state. 4 lcaStateCnfgOnline Normal device state.
PAGE 303
Read/Write Read only. Added to API Prior to LNS Release 3.0. TransactionTimeouts Summary Contains the number of times an acknowledged or request/response message failed after all the retries. This data is available for application devices and router sides. Availability Local, full, and lightweight clients. Syntax messageCount = detailInfoObject.TransactionTimeouts Element Description messageCount The number of failed messages.
PAGE 304
Syntax errorCount = detailInfoObject.XmitErrors Element Description errorCount The number of errors. detailInfoObject The DetailInfo object from which to get the information. Data Type Long. Read/Write Read only. Added to API Prior to LNS Release 3.0. DeviceTemplate A DeviceTemplate object represents generic device type information that can be applied to multiple LONWORKS application devices.
PAGE 305
• • • • • RegisteredComponent SelfDocConsistency SelfDocumentation UserTypeFileName XifPath Methods The DeviceTemplate object contains the following methods: • • Import ResyncToResources Import Summary Import an external interface from an XIF or XFB file into a device template. This updates the property values of the device template with the information from the imported external interface. The XFB file must be version 3.0 or later.
PAGE 306
have been updated or modified since the device’s XIF was imported. This method allows you to update the DeviceTemplate whenever these situations occur, without having to re-import the XIF. The LdrfCatalogPath property points to the location of the device resource file catalog. You can browse the contents of this catalog with the NodeBuilder Resource Editor included with the Echelon device development software. Availability Local, full, and lightweight clients. Syntax devTemplateObject.
PAGE 307
resynchronization. Added to API LNS Release 3.20.
PAGE 308
BitmapFilePath Summary Specify the path and file name of a bitmap (*.BMP file) representation of the object. The bitmap files are used to store object images which may be accessed by a director level LNS component application. A bitmap may be of any size, although the recommended dimensions are 40x80 pixels. See the IconFilePath property for related information. Availability Local clients. Syntax bmpFilePath = object.BitmapFilePath Element Description bmpFilePath The bitmap path and file name.
PAGE 309
added to the API. ComponentApps Summary Contains the ComponentApps collection object associated with the specified DeviceTemplate. The ComponentApps collection is a list of LNS plug-in commands that are associated with a particular object type. Note that all LonMarkObject objects contain a ComponentApps property; however, the behavior of this property is unspecified when accessed through a LonMarkObject object. Availability Local, full, and lightweight clients. Syntax appsCollection = object.
PAGE 310
DeviceClass Summary Stores the device class for a device template. Availability Local, full, and lightweight clients. Syntax deviceClassValue = devTemplateObject.DeviceClass Element Description deviceClassValue The device class value devTemplateObject The DeviceTemplate object. Data Type String. Read/Write Read only. Added to API Prior to LNS Release 3.0. DeviceSubclass Summary Returns the device subclass for a device template. Availability Local, full, and lightweight clients.
PAGE 311
that specified by the application, and the program interface in the device matches the previously defined program interface for that program ID. This validation occurs to prevent users from configuring a device incorrectly. This validation, however, does require the transmission of a large number of messages between OpenLNS and the device. This can be very time consuming, particularly on slow media, and can greatly increase the time required to commission the devices on a network.
PAGE 312
database, the commission will fail, and the NS, #72 lcaErrNsWrongChannel exception will be thrown. 1 lcaDeviceValidationNoChannelV alidation Do not validate the channel if it is already known because either it has been specified by the application, or the device is already registered. If this option is selected and the channel is not specified, the channel isolation process will still be used. If this option is selected and a device has been placed on the wrong channel, OpenLNS will not detect this.
PAGE 313
option is set. Note that the lcaDeviceValidationNoChannelV alidation (1) and lcaDeviceValidationNoProgramI dValidation (4) flags have no effect during an application download. If this option is set and a device is using a program interface that is inconsistent with the device template, the device will be configured incorrectly, and unpredictable behavior will occur. In addition, device corruption may prevent the device from being loaded or upgraded in the future.
PAGE 314
Availability Local, full, and lightweight clients. Syntax dynamicNvSupValue = dtObject.DynamicNvSupported Element Description dynamicNvSupValue A value of 0 or 1. Long. Read/Write Read only. Added to API LNS Release 3.0. Devices based on this device template do not support dynamic network variables. 1 Devices based on this device template support network variables. The DeviceTemplate object to be acted on.
PAGE 315
values: 0 8 9 devTemplateObject Development program ID. LonMark approved program ID. LonMark prototype program ID. The DeviceTemplate object Data Type String. Read/Write Read only. Added to API Prior to LNS Release 3.0. Handle Summary Contains the handle associated with the DeviceTemplate object. This property enables the DeviceTemplate to be retrieved by the ItemByHandle method of the DeviceTemplates object. Availability Local, full, and lightweight clients.
PAGE 316
device. FALSE. Device is a Neuron hosted device. dtObject Data Type Boolean. Read/Write Read only. Added to API LNS Release 3.0. The DeviceTemplate object to be acted on. IconFilePath Summary Specifies the path and file name of an icon (*.ICO file) representation of the object. Availability Local clients. Syntax IconFilePathFileName = object.IconFilePath Element Description IconFilePathFileName Icon file and path name object The object to be acted on. Data Type String.
PAGE 317
object The AppDevice object to be acted on. Data Type Interface object. Read/Write Read only. Added to API Prior to LNS Release 3.0. ManufacturerID Summary Reads the manufacturer ID assigned to a device template or component application. This property is the manufacturer ID field of the standard program ID. See the LonMark Application Layer Interoperability Guidelines for more information. Availability Local, full, lightweight, and independent clients. Syntax idValue = object.
PAGE 318
may not contain the forward slash (/), back slash (\), period (.), and colon (:) characters. Availability Local, full, lightweight, and independent clients. Note that some objects that contain this property are not available to Independent clients. Syntax stringValue = object.Name Element Description stringValue The name of the object. object The object to be acted on. Data Type String. Read/Write Read/write. Added to API Depends on the object used to access the property.
PAGE 319
Availability Local, full, and lightweight clients. Syntax programIdValue = object.ProgramId Element Description programIdValue The program ID value of the object. object The object to be acted on. Data Type String. Read/Write Read only. Added to API Prior to LNS Release 3.0. ProgramType Summary Identifies the form or origin of the application program for this device.
PAGE 320
Each DeviceTemplate object in an OpenLNS database may have a single device control registered for it. A null value in this property indicates that there is no registered device control for this DeviceTemplate object. To support device controls, a director application must follow these steps when creating a new device: 1. Examine the RegisteredComponent property of the DeviceTemplate object for the new device.
PAGE 321
template. The valid values for this property, which are contained in the ConstSelfDocConsistency constant, are as follows: 0 lcaSelfDocConsistencyIdenticalOn AllDevices The self-documentation on devices using the device template must be identical. This is the most efficient, but least flexible, setting of this property. It is the default for all devices without a LonMark standard program ID.
PAGE 322
value that conflicts with the configurations of the devices using a template. If you set this property to a setting that violates the configuration of devices already using the template, then the NS, #59 lcaErrNsProgramIntfMismatch exception is thrown. devTemplateObject Data Type Integer. Read/Write Read/write. Added to API LNS Release 3.20. The DeviceTemplate object to be acted upon. SelfDocumentation Summary Stores the self-documentation string of the application device.
PAGE 323
base name of the formatting file (.fmt) instead of the default. devTemplateObject Data Type String. Read/Write Read/write. Added to API Prior to LNS Release 3.0. The DeviceTemplate object to be acted on. XifPath Summary Contains the path of the external interface file used by this device template. Availability Local, full, and lightweight clients. Syntax xifPathValue = dtObject.XifPath Element Description xifPathValue The external interface file path.
PAGE 324
• • Parent _NewEnum Methods The DeviceTemplates object contains the following methods. • • • • Add ItemByHandle ItemByProgramId Remove Add Summary Defines a new DeviceTemplate object. A DeviceTemplate object needs to be explicitly created with this method only if that DeviceTemplate is going to be initialized by importing an external interface file (.XIF and .XFB extensions).
PAGE 325
This value is not supported. Added to API Prior to LNS Release 3.0. ItemByHandle Summary Retrieves a DeviceTemplate object by its handle property from the DeviceTemplates collection. This may be particularly useful when processing events reported by OnChangeEvent with the objectType of lcaChangeEventDeviceTemplates. Availability Local, full, and lightweight clients. Syntax deviceTemplate = deviceTemplates.ItemByHandle Added to API Element Description deviceTemplate The DeviceTemplate object.
PAGE 326
name Added to API A Long value specifying the collection index of the object to remove, or a String value specifying the name of the object to remove. Prior to LNS Release 3.0. Properties The DeviceTemplates object contains the following properties: • • • • • ClassID Count Item Parent _NewEnum ClassId Summary Identifies the object class of this object.
PAGE 327
Element Description returnValue The number of objects in the collection as a long integer. object The collection object to be acted on. Data Type Long. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. Item Summary Returns a DeviceTemplate object from the DeviceTemplates collection.
PAGE 328
Availability Local, full, lightweight, and independent clients. Note that some collection objects are not available to Independent clients. Syntax parentObject = object.Parent Element Description parentObject The object that is the parent of the specified object. object Any object for which the parent is desired. Data Type Object. Read/Write Read only. Added to API Depends on the object used to access the property.
PAGE 329
Error An Error object represents the information for a single Object Server error. Errors are handled by LCA applications via the ActiveX exception mechanism. The Error object contains the standard code and description properties that are passed back in the last exception, as well as some additional information. The following table summarizes the Error object. Description The data for a single Object Server error. Added to API Prior to LNS Release 3.0. Accessed Through System object.
PAGE 330
Category Summary Contains the error category represented by the Error object. Availability Local, full, and lightweight clients. Syntax errCategory = errorObject.Category Element Description errCategory The error category. The valid values for this property, which are contained in the ConstErrCategories constant, are as follows: 0 lcaErrCategoryNs Network Server error. 1 lcaErrCategoryNi Network Interface error. 2 lcaErrCategoryConn Connection error. 3 lcaErrCategoryObjServer Object Server error.
PAGE 331
Syntax classIdValue = object.ClassId Element Description classIdValue The object class of the object. The following value is defined for the Error object in the ConstClassIds constant: 44 lcaClassIdError object The object to be acted on. Data Type Integer. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API.
PAGE 332
errObject The Error object to be acted on. Data Type Long. Read/Write Read only. Added to API Prior to LNS Release 3.0. ConnErrIndex1 Summary If the Error object represents a connection error (lcaErrCategoryConn), this property returns the index of the primary network variable or message tag in the error. Otherwise it returns 0. The ConnErrIndexType1 property indicates whether this index applies to a network variable or message tag, as well as the type of network variable or message tag.
PAGE 333
You can use the AppDevices collection object's ItemByHandle method to get the AppDevice corresponding to the device handle. Availability Local, full, and lightweight clients. Syntax index = errorObject.ConnErrIndex2 Element Description index The network variable or message tag index to be returned. errObject The Error object to be acted on. Data Type Long. Read/Write Read only. Added to API Prior to LNS Release 3.0.
PAGE 334
ConnErrIndex1 property is a message tag index. 2 lcaLNSIndexTypeDynamicMessageTag The index in the corresponding ConnErrIndex1 property is a dynamic message tag index. -1 lcaLNSIndexTypeInvalid The corresponding ConnErrIndex property contais invalid data. errObject The Error object to be acted on. Data Type Long. Read/Write Read only. Added to API Prior to LNS Release 3.0.
PAGE 335
The index in the corresponding ConnErrIndex2 property is a message tag index. 2 lcaLNSIndexTypeDynamicMessageTag The index in the corresponding ConnErrIndex2 property is a dynamic message tag index. -1 lcaLNSIndexTypeInvalid The corresponding ConnErrIndex2 property contais invalid data. errObject The Error object to be acted on. Data Type Long. Read/Write Read only. Added to API Prior to LNS Release 3.0. Description Summary Stores description information about the Error object.
PAGE 336
contained in the ConstClassIds constant, are as follows: 0 lcaClassIdObjectServer 1 lcaClassIdNetwork 2 lcaClassIdNetworks 3 lcaClassIdSyste 4 lcaClassIdSystem 5 lcaClassIdSubsyste 6 lcaClassIdSubsystem 7 lcaClassIdAppDevic 8 lcaClassIdAppDevice 9 lcaClassIdRoute 10 lcaClassIdRouters 11 lcaClassIdRouterSide 12 lcaClassIdChannel 13 lcaClassIdChannels 14 lcaClassIdNetworkInterface 15 lcaClassIdNetworkInterfaces 16 lcaClassIdSubnet 17 lcaClassIdSubnets 18 lcaClassIdConnections 19 lcaClassIdInterface 20 lcaClas
PAGE 337
51 lcaClassIdExtensions 52 lcaClassIdRecoveryStatus 53 lcaClassIdCreditInfo 54 lcaClassIdAccount 55 lcaClassIdAccounts 56 lcaClassIdBufferConfiguration 57 lcaClassIdFileTransfer 58 lcaClassIdAlias 59 lcaClassIdAliases 69 lcaClassIdPingIntervals 70 lcaClassIdApplication 71 lcaClassIdTestInfo 72 lcaClassIdDataPoint 73 lcaClassIdFormatSpec 74 lcaClassIdMonitorSet 75 lcaClassIdMonitorSets 76 lcaClassIdMsgMonitorOptions 77 lcaClassIdMsgMonitorPoint 78 lcaClassIdMsgMonitorPoints 79 lcaClassIdNvMonitorOptions 80 l
PAGE 338
Syntax errorId = errorObject.ErrorObjHandle Element Description errorObject The Error object to be acted on. errorId A short which indicates the handle of the object that caused the error. The class of object which raised the error is contained in the ErrObjClassId property. Data Type Short. Read/Write Read only. Added to API Prior to LNS Release 3.0. Number Summary Returns the LNS error number of the error represented by the Error object. Availability Local, full, and lightweight clients.
PAGE 339
Data Type Object. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. Extension An Extension object represents user-defined data. Each manufacturer can define any number of manufacturer specific data objects for application-specific data.
PAGE 340
• • Value2 Value3 ClassId Summary Identifies the object class of this object. This property allows the object type to be determined when it is unknown (for example, when the object was accessed using the Parent property of another object). Availability Local, full, lightweight, and independent clients. Note that some objects containing this property are not available to Independent clients. Syntax classIdValue = object.ClassId Element Description classIdValue The object class of the object.
PAGE 341
extension Data Type Boolean. Read/Write Read/write. Added to API LNS Release 3.20. The Extension object to be acted upon. Description Summary Stores description information about the Extension object. Availability Local, full, lightweight, and independent clients. Note that some collections are not available to Independent clients. Syntax stringValue = object.Description Element Description stringValue A string description of the Extension object. object The Extension object to be acted on.
PAGE 342
Handle Summary Contains the handle associated with the Extension object. This property enables the Extension to be retrieved by the ItemByHandle method of the Extensions object. Availability Local, full, and lightweight clients. Syntax returnValue = extension.Handle Element Description returnValue The NSS handle of the Extension object. object The Extension object to be acted on. Data Type Long. Read/Write Read only. Added to API OpenLNS.
PAGE 343
Extensions collection containing this Extension. To determine the object type before using this method, use the OwnerClassId property. Availability Local, full, and lightweight clients. Syntax object = extension.Owner Element Description extension The Extension object to be acted on. object The object that contains the Extension. Data Type Object. Read/Write Read only. Added to API OpenLNS.
PAGE 344
specified object. object Any object for which the parent is desired. Data Type Object. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. Value1 Summary Stores user-specified object data. Availability Local, full, and lightweight clients. Syntax userData = extensionObject.Value1 Element Description userData The user-specific data.
PAGE 345
Value2 Summary Stores user-specified object data. Availability Local, full, and lightweight clients. Syntax userData = extensionObject.Value2 Element Description userData The user-specific data. You can store data of any type supported by the Variant type in binary large objects (BLOBs) of up to 65,000 bytes. Values are tagged with a unique key to ensure that applications from multiple manufacturers do not overwrite each other's data.
PAGE 346
Variant type in binary large objects (BLOBs) of up to 65,000 bytes. Values are tagged with a unique key to ensure that applications from multiple manufacturers do not overwrite each other's data. The Value3 property supports the following Variant types: VT_BOOL VT_UI1 VT_I2 VT_I4 VT_CY VT_R4 VT_R8 VT_DATE VT_BSTR VT_ERROR VT_DISPATCH VT_UNKNOWN VT_EMPTY VT_NULL All single-dimensional Variant arrays, except for arrays of BSTRs. extensionObject The Extension object to operate on. Data Type Variant.
PAGE 347
ObjectServer object Router object Subnet object Subsystem object System object Default Property Item property. Methods • • • Add ItemByHandle Remove Properties • • • • • ClassID Count Item Parent _NewEnum Methods The Extensions object contains the following methods. • • • Add ItemByHandle Remove Add Summary Define a new Extension object. Availability Local, full, and lightweight clients. Syntax extensionObject = extensionsColl.
PAGE 348
handle Added to API The handle of the Extension to be retrieved. OpenLNS. Remove Summary Removes an object from the specified collection. Availability Local, full, lightweight, and independent clients. Note that some collections are not available to Independent clients. Syntax objectColl.Remove indexName Added to API Element Description objectColl The collection containing the object to be removed.
PAGE 349
Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. Count Summary Returns the number of objects in a collection. You can use this property to enumerate a collection object. Availability Local, full, lightweight, and independent clients. Note that some collection objects are not available to Independent clients. Syntax returnValue = object.
PAGE 350
Data Type Object. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. Parent Summary Returns the object that spawned the current child object. The parent object is determined by the means in which a child object is accessed, not by the OpenLNS Object hierarchy. Availability Local, full, lightweight, and independent clients.
PAGE 351
retrievedObject = collObject._NewEnum Syntax Element Description retrievedObject An expression that evaluates to the object retrieved. collObject An iterator object that can be used to access members of the collection. Data Type Object. Read/Write Read only. Added to API OpenLNS. FileTransfer A FileTransfer object represents a LonMark file transfer session involving a group of application devices.
PAGE 352
• TxTimeOut Methods The FileTransfer object contains the following methods: • • • • AddTarget ClearTargets ReadFile WriteFile AddTarget Summary Adds a target application device to the file transfer target list. Currently, you can perform file transfer implicitly without the use of a previously defined connection by the OpenLNS Server with only one device at a time.
PAGE 353
Availability Local, full, and lightweight clients. Syntax ftObject.ClearTargets Added to API Element Description ftObject The FileTransfer object. Prior to LNS Release 3.0. ReadFile Summary Reads a file from an AppDevice in the file transfer target list. You must first add the selected application device to the file transfer target list with the AddTarget method. You can use this method to read from one device at a time.
PAGE 354
WriteFile Summary Writes a file to an AppDevice in the file transfer target list. You must first add the selected application device to the file transfer target list with the AddTarget method of the FileTransfer object. The desired file transfer parameters (including the index number of the file to be written to on the app device) are set using the properties of the FileTransfer object. You can use this method to write a file buffer to more than one application device at a time.
PAGE 355
• • • • • • • • • • FileSize FileType HostTimeOut Parent PriorityFlag ReadBufferLength RetryCount RxTimeOut StartPosition TxTimeOut AuthenticationFlag Summary Specifies whether authenticated messages are used for the file transfer. Availability Local, full, and lightweight clients. Syntax authFlag = fileTransObject.AuthenticationFlag Element Description authFlag A Boolean value. TRUE. Authenticated messages are used to perform the file transfer.
PAGE 356
classIdValue The object class of the object. The following value is defined for the FileTransfer object in the ConstClassIds constant: 57 lcaClassIdFileTransfer object The object to be acted on. Data Type Integer. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API.
PAGE 357
FileIndex Summary Specifies the file index to be used during operations on the FileTransfer object. Note: OpenLNS does not support writing to the template file or the value file (or value files) because it would corrupt the configuration properties. Instead, OpenLNS provides the ConfigProperties object to provide transparent access to configuration properties implemented via configuration network variables, file transfer, and direct memory read/write.
PAGE 358
FileInfo Summary Returns a 16-byte string describing any of the files on the app devices that have been added to the FileTransfer object’s target list. The FileTransfer object has a list of targets, numbered from one to n. The nTarget element is an index within that list, which is used to get the node handle of the app device for which a file description is to be obtained. If the nTarget value is out of range, an exception is thrown. The app device identified by the nTarget element may have multiple files.
PAGE 359
files. This property will return the file size of the file that is using the value assigned to the FileIndex property as its index number. Data Type Long. Read/Write Read only. Added to API Prior to LNS Release 3.0. FileType Summary Returns the file type of any of the files on the app devices that have been added to the FileTransfer object’s target list. Availability Local, full, and lightweight clients. Syntax nFileTypeValue = ftObject.
PAGE 360
Syntax timeoutValue = fileTransObject.HostTimeOut Element Description timeoutValue The timeout value. The time-out value in seconds (0– 65,535). The number indicates the maximum number of seconds a file transfer setup or clearing request may take if the target is busy. The attempt will be made once per second. The default value is 30 seconds. fileTransObject The FileTransfer object to be acted on. Data Type Integer. Read/Write Read/write. Added to API Prior to LNS Release 3.0.
PAGE 361
Syntax priorityFlag = fileTransObject.PriorityFlag Element Description priorityFlag The returned priority flag, which is a Boolean value. TRUE. Priority messaging is used. FALSE. Priority messaging is not used. fileTransObject The FileTransfer object to be acted on. Data Type Boolean. Read/Write Read/write. Added to API Prior to LNS Release 3.0. ReadBufferLength Summary Specifies the read buffer length for file transfer.
PAGE 362
A value of 0 indicates that the number of retries will be calculated based on the network topology. The default value is 0. object The FileTransfer object to be acted on. Data Type Integer. Read/Write Read/write. Added to API Prior to LNS Release 3.0. RxTimeOut Summary Specifies the receive timeout value used for file transfer messages. Availability Local, full, and lightweight clients. Syntax timeoutValue = fileTransObject.
PAGE 363
This method requires network communication; however, you can invoke it while the network management mode (MgmtMode property) is set to lcaMgmtModeDeferConfigUpdate s (1). fileTransObject The FileTransfer object to be acted on. Data Type Long. Read/Write Read/write. Added to API Prior to LNS Release 3.0. TxTimeOut Summary Specifies the transmit timeout value used for file transfer messages.
PAGE 364
less than or equal to the receive timeout value. The default value is 0,which means that OpenLNS calculates the timeout period based on the network topology and channel delays. fileTransObject The FileTransfer object to be acted on. Data Type Integer. Read/Write Read/write. Added to API Prior to LNS Release 3.0. FormatLocale A FormatLocale object contains a series of properties that reflect a particular geographical area’s conventions for data display.
PAGE 365
• • • • • • • • • • • • • • • • • • • • • DateFormatSeparator DateFormatSeparatorSource DecimalPointCharacter DecimalPointCharacterSource DoubleFloatPrecision FallbackFormat FloatPrecision LanguageId LanguageIdSource ListSeparatorCharacter ListSeparatorCharacterSource MeasurementUnits MeasurementUnitsSource Name Parent ShortDateFormat ShortDateFormatSource ShortTimeFormat ShortTimeFormatSource TimeFormatSeparator TimeFormatSeparatorSource Methods The FormatLocale object does not contain any methods.
PAGE 366
CategoryPreferenceList Summary Establishes the format to be used when displaying the formatted value of a data point whose default type contains several alternate formats, such as SNVT_press. OpenLNS will initially choose the format to use for data points like this based on the setting of the MeasurementUnits property. This allows you to choose between U.S. or SI metric measurement units. You can also use localized formats whenever possible by writing to the CategoryPreferenceList property.
PAGE 367
search for matches for each alternate format specified starting with the first entry in the list. If you specify the same format more than once in the list you write to the CategoryPreferenceList property, the Formatter, #40 lcaErrFormatStringDuplicate exception will be thrown.
PAGE 368
Data Type Integer. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. DateFormatSeparator Summary Determines which symbol is used to separate the digits that represent months, days and years when the formatted value is displayed as a date. For example, if this property is set to the backslash (/) character, dates would be displayed as follows: 11/26/1977, 8/13/83, etc.
PAGE 369
formatLocale The FormatLocale object being acted upon. source The value of the DateFormatSeparatorSource property. The possible values for this element, which are contained in the ConstFormatLocaleSource constant, are as follows: 0 lcaFormatLocaleSource UserDefaultRegionalSetting Select this value to have OpenLNS set the associated property automatically, based on the Windows regional settings set by the user on the computer running your application.
PAGE 370
DecimalPointCharacter Summary Determines which will be used to indicate decimal places when a formatted value is displayed as a scalar number. For example, if this property is set to the period character, scalar values with decimal places would be displayed as follows: 100.34, 78.4, 99.6, and so on. This applies to format specifications that use the %f symbol in their text format specification, such as SNVT_temp#US: text("%f", *1.
PAGE 371
UserDefaultRegionalSetting Select this value to have OpenLNS set the associated property automatically, based on the Windows regional settings set by the user on the computer running your application. A user can change the regional settings on a computer from the system defaults using the Windows control panel Regional Options applet. This is the default.
PAGE 372
DoubleFloatPrecision Summary Determines the precision that will be used when displaying double-float values. This property is implemented when the data stored in the FormattedValue property is formatted as an ASCII representation of a double precision floating-point value. It specifies the default number of digits that will be used to display the value. Note: The FormatSpec object of each data point contains a Precision property.
PAGE 373
FallbackFormat Summary Specifies the default type that should be used to display a data point’s formatted value if the data point’s actual type cannot be determined. This may be necessary if a data point’s type is unknown, or if it cannot be found in the resource files. Typically, OpenLNS will automatically assign each data point a type based on the type of the network variable or configuration property associated with the data point.
PAGE 374
TAB character (0x09). 2 lcaFormatRawHexPacked Use "RAW_HEX_PACKED" as the fallback type. This is a text string format, just like the "RAW_HEX" format. Each byte of the network variable value (in big-endian format) appears as a text-formatted hex integer value from "0" through "ff". The value bytes are not separated by the TAB character when this type is used. Data Type Long. Read/Write Read/write. Added to API LNS Release 3.20.
PAGE 375
Data Type Long. Read/Write Read/write. Added to API LNS Release 3.20. LanguageId Summary Determines the language that will be used to display Windows localized settings that are stored in the formatted values. For example, if the formatted value contains a date, this would determine the language used to display the name of the month in the date. All language codes are three characters long. For example, you could enter "ENU" to display the information in U.S.
PAGE 376
code ldrfObject Data Type String. Read/Write Read only. Added to API LNS Release 3.20 A 3-letter identifier for the language specified for the FormatLocale object.
PAGE 377
formatLocale The FormatLocale object being acted upon. source The value of the LanguageIdSource property. The possible values for this element, which are contained in the ConstFormatLocaleSource constant, are as follows: 0 lcaFormatLocaleSource UserDefaultRegionalSetting Select this value to have OpenLNS set the associated property automatically, based on the Windows regional settings set by the user on the computer running your application.
PAGE 378
ListSeparatorCharacter Summary Determines which symbol is used to separate items in the formatted value that are returned as parts of a list. This applies to format specifications that use the bar character ("|") to represent a localized list separator character. A few examples of this are SNVT_hvac_status#LO and SNVT_magcard#LO. You can use the ListSeparatorCharacterSource property to determine how the ListSeparatorCharacter property should be filled in.
PAGE 379
based on the Windows regional settings set by the user on the computer running your application. A user can change the regional settings on a computer from the system defaults using the Windows control panel Regional Options applet. This is the default. 1 lcaFormatLocaleSource SystemDefaultRegionalSetting Select this value to have OpenLNS set the associated property automatically, based on the system default Windows regional settings of the computer running your application.
PAGE 380
MeasurementUnits Summary Determines the measurement units (Systeme Internationale [SI metric] or U.S.) that will be used to display the formatted values of data points when this FormatLocale object is used by an application. This is implemented when a data point is using a default type that has several alternate formats associated with it. For example, consider a case where a data point is using SNVT_temp as its default type.
PAGE 381
0 lcaMeasurementUnitsSI Displays the formatted values using the metric measurement system. 1 lcaMeasurementUnitsUS Displays the formatted values using the U.S. measurement system. Data Type Long. Read/Write Read/write. Added to API LNS Release 3.20. MeasurementUnitsSource Summary Determines whether OpenLNS should assign the MeasurementUnits property a value automatically based on the Windows control panel Regional Options settings. Availability Local, full, lightweight, and independent clients.
PAGE 382
running your application. The default settings may vary depending on which operating system is installed on the computer running the application. Consult the Microsoft Developer’s Network documentation for more information on this. 2 lcaFormatLocaleSource ManualSetting This value indicates that the value of the associated property has been set manually by your application. Data Type Long. Read/Write Read/write. Added to API LNS Release 3.20.
PAGE 383
clients. Syntax parentObject = object.Parent Element Description parentObject The object that is the parent of the specified object. object Any object for which the parent is desired. Data Type Object. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. ShortDateFormat Summary Determines how a formatted value will be displayed if it represents a date.
PAGE 384
Here are some example strings you could use for this property, with examples of how the short date would appear for each one. The following examples assume the DateFormatSeparator property is set to /. ShortDateFormat Example MM/dd/yy 08/26/03 d/M/yyyy 26/8/2003 MMM/dd/yyyy Aug/26/2003 yy/dd/MMMM 03/26/August If you specify a character other than M, d, y, or the DateFormatSeparator character when writing to this property, the LCA, #87 lcaErrStringInvalidChar exception will be thrown.
PAGE 385
source The value of the ShortDateFormatSource property. The possible values for this element, which are contained in the ConstFormatLocaleSource constant, are as follows: 0 lcaFormatLocaleSource UserDefaultRegionalSetting Select this value to have OpenLNS set the associated property automatically, based on the Windows regional settings set by the user on the computer running your application.
PAGE 386
restrictions to how each part of the time can be displayed. This applies to format specifications containing the time() macro in their text format specification, such as SNVT_Time_time#LO: text(time(hour, minute, second)) • When setting the format used to display hours, you can use the following formats: o o • • "H" to display the hours with as few digits as possible. "HH" to display the always hours with double digits, with leading zeros for hours 0-9.
PAGE 387
automatically update it with the new separator character for you. You can use the ShortTimeFormatSource property to determine how the ShortTimeFormat property should be filled in. Availability Local, full, and lightweight clients. Syntax formatLocale.ShortTimeFormat = timeFormat Element Description formatLocale The FormatLocale object being acted upon. timeFormat The format used to display dates.
PAGE 388
control panel Regional Options applet. This is the default. 1 lcaFormatLocaleSource SystemDefaultRegionalSetting Select this value to have OpenLNS set the associated property automatically, based on the system default Windows regional settings of the computer running your application. The default settings may vary depending on which operating system is installed on the computer running the application. Consult the Microsoft Developer’s Network documentation for more information on this.
PAGE 389
Syntax formatLocale.ShortTimeFormat = timeFormat Element Description formatLocale The FormatLocale object being acted upon. timeFormat The format used to display dates. The allowable characters are "H", "m", "s" and the character specified as the TimeFormatSeparator property. Data Type String. Read/Write Read/write. Added to API LNS Release 3.20.
PAGE 390
based on the system default Windows regional settings of the computer running your application. The default settings may vary depending on which operating system is installed on the computer running the application. Consult the Microsoft Developer’s Network documentation for more information on this. 2 lcaFormatLocaleSource ManualSetting This value indicates that the value of the associated property has been set manually by your application. Data Type Long. Read/Write Read/write.
PAGE 391
not available. In this case, Systeme Internationale measurement units, and U.S. options for everything else, will be used to display all formatted data. • Index 4, ISO8601DateAndTime. When you use this FormatLocale object as the CurrentFormatLocale, all properties will be set to be the same as the LonMark Compatibility settings, except for the localized time and date formats, which will be based on the ISO 8601 standard.
PAGE 392
such as the format used to display dates and times, and the unit of measurement associated with the formatted value. The default values assigned to the properties of the FormatLocale object match the settings of the pre-defined "UserDefaultRegionalSettings" FormatLocale object. This means that the default will be set based on the user-defined Windows regional settings on the computer running the application. For more information on these settings, see the OpenLNS Programmer’s Guide.
PAGE 393
FormatLocales collection. You can determine the name of a FormatLocale object by reading its Name property. Note that the FormatLocales collection contains 4 pre-defined FormatLocale objects, using indices 1–4, that cannot be deleted. If you attempt to delete these FormatLocale objects with this method, the LCA, #122 lcaErrReadOnlyInContext exception will be thrown.
PAGE 394
ClassId Summary Identifies the object class of this object. This property allows the object type to be determined when it is unknown (for example, when the object was accessed using the Parent property of another object). Availability Local, full, lightweight, and independent clients. Note that some objects containing this property are not available to Independent clients. Syntax classIdValue = object.ClassId Element Description classIdValue The object class of the object.
PAGE 395
FormatLocales collection by passing its index (ordinal position) within that collection as the argument for the Item property. Index values start at 1. You can also retrieve a FormatLocale object in FormatLocales collections that contain objects with the Name property by passing the object’s name as a string expression Availability Local, full, lightweight, and independent clients. Note that some objects containing this property are not available to Independent clients.
PAGE 396
Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. _NewEnum Summary Enables you to iterate over the objects in a collection using For Each ... Next statements. • If you are developing your OpenLNS app in Visual C++, you can browse a collection to find a particular item by using the _NewEnum property. See the IEnumVARIANT interface for details.
PAGE 397
Set fsObject = dpObject.FormatSpec fsObject.FormatName = "SNVT_temp_f#SI" Set dpObject.FormatSpec = fsObject After the FormatSpec object has been modified and passed back to the data point or monitor point, you can examine it to determine whether or not OpenLNS has found the specified format in the resource files. Because of changes to the behavior of the FormatSpec object since LNS Release 3.
PAGE 398
• • • • • • • • • • • ClassId FormatName FormatType Index Parent Precision ProgramId Scope Units UnitsAdder UnitsMultiplier AltFormatName Summary Contains an indexed list of all formats that can be applied to this data type. This allows you to search for other FormatSpec objects that contain alternate formats.
PAGE 399
Syntax altNameCount = fsObject.AltFormatNamesCount Element Description altNameCount The number of alternate formats contained in the AltFormatName property. fsObject The FormatSpec object to be acted on. Data Type Long. Read/Write Read only. Added to API LNS Release 3.0. ClassId Summary Identifies the object class of this object. This property allows the object type to be determined when it is unknown (for example, when the object was accessed using the Parent property of another object).
PAGE 400
FormatType property is set to lcaFormatTypeNamed (0). In that case, the Scope and ProgramId properties are used to identify the resource file containing the type’s definition. The way that OpenLNS determines the default value for this property, and the syntax you can use when writing to this property, varies depending on the type of object to which the FormatSpec applies: • NvMonitorPoint object or a DataPoint object that represents a network variable using a standard type.
PAGE 401
Element Description fsObject The FormatSpec object to be acted on. formNameValue The FormatName as a string. Data Type String. Read/Write Read/write. Added to API LNS Release 3.0. FormatType Summary Determines the base type of the data read from and written to FormattedValue property in the DataPoint or NvMonitorPoint object using the FormatSpec object. Availability Local, full, lightweight, and independent clients.
PAGE 402
The lcaFormatTypeNamed(0) value is the default value for user-defined network variables. 1 lcaFormatTypeNv The FormatSpec object contains a format for a standard network variable type. If the type is a Standard Network Variable Type (SNVT), set this property to lcaFormatTypeNv (1), and set the Index property to the SNVT index. The lcaFormatTypeNv (1) value is the default value for data points and monitor points acquired through standard network variables.
PAGE 403
Syntax indexValue = fsObject.Index Element Description fsObject The FormatSpec object to be acted on. indexValue The index of the SNVT or SCPT. Data Type Long. Read/Write Read/write. Added to API LNS Release 3.0. Parent Summary Returns the object that spawned the current child object. The parent object is determined by the means in which a child object is accessed, not by the OpenLNS Object hierarchy. Availability Local, full, lightweight, and independent clients.
PAGE 404
points in permanent monitor sets. Syntax precisionValue = object.Precision Element Description precisionValue The precision of the configuration property value. This element has a range between 0–17. object The FormatSpec or ConfigProperty object to be acted upon. Data Type Integer. Read/Write Read/write. Added to API Prior to LNS Release 3.0. ProgramId Summary Contains the program ID of the FormatSpec object.
PAGE 405
will be set to match the program ID of the device containing the monitor point or data point. • If the FormatSpec object applies to a data point obtained through a ConfigProperty object, the ProgramId property will be set to match the program ID of the resource file that defines the configuration property type. • If the FormatSpec object applies to a message monitor point, the ProgramId property will be set to 0000000000000000. Availability Local, full, and lightweight clients.
PAGE 406
2 lcaResourceScopeSubclass This scope applies to all devices of a specified device class and device subclass from any manufacturer. 3 lcaResourceScopeMfg This scope applies to all devices of a specified manufacturer. 4 lcaResourceScopeMfgClass This scope applies to all devices of a specified manufacturer and device class. 5 lcaResourceScopeMfgSubClass This scope applies to all devices of a specified manufacturer, device class and device subclass.
PAGE 407
Read/Write Read/write. Added to API LNS Release 3.0. Units Summary Indicates the name of the units that apply to values using this format specification. Availability Local, full, lightweight, and independent clients. Independent clients can only access FormatSpec objects through monitor points in permanent monitor sets. Syntax units = fsObject.Units Element Description units The name of the units. fsObject The FormatSpec object to be acted on. Data Type String. Read/Write Read only.
PAGE 408
Data Type Single. Read/Write Read only. Added to API LNS Release 3.0. UnitsMultiplier Summary Determines how the scaled value of the data point or monitor point will be unit-converted for display as a formatted value when your application reads the FormattedValue propery. When your application reads the FormattedValue property of a data point or monitor point, the OpenLNS Object Server converts the scaled value of the data point or monitor point so that it can be display as a formatted value.
PAGE 409
interfaces that cannot be modified. The custom interfaces that have been added to a device can be accessed through the device’s Interfaces property. In many cases, you can modify these interfaces by adding or removing objects from their NetworkVariables, LonMarkObjects, and MessageTags collections. Some of the information returned by the properties of each Interface object apply to the device as a whole, and not to the specific interface represented by the Interface object.
PAGE 410
Version • Methods The Interface object contains the following methods: • • • • • • • • • AddCompatibleNv AddCompatibleNvEx AddComplementaryNv AddComplementaryNvEx AddNvFromString CreateTypeSpec DownloadConfigProperties RemoveNv UploadConfigProperties AddCompatibleNv Summary Creates a NetworkVariable object that is compatible with a specified source network variable, and adds the new network variable to the specified Interface object.
PAGE 411
the ProgrammaticName property. sourceNvObj Added to API The NetworkVariable object which the new network variable is based upon. Prior to LNS Release 3.0. AddCompatibleNvEx Summary Creates a NetworkVariable object that is compatible with a specified source network variable and adds the new network variable to the specified Interface object. This method differs from AddCompatibleNv method in that this method allows you to set options. Availability Local, full, and lightweight clients.
PAGE 412
ConstLNSInterfaceCompNvEx constant, are as follows: 0 lcaLNS_PollPassthrough The created network variable will have the same value in IsPolled as the network variable it was based on. 1 lcaLNS_PollToggle The created network variable will have the opposite value in IsPolled as the network variable it was based on. 2 lcaLNS_PollClear The created network variable will have polling disabled. 3 lcaLNS_PollSet The created network variable will have polling enable. Added to API Prior to LNS Release 3.0.
PAGE 413
as the source network variable. This method is used to construct an interface object for a host application. interfaceObject The Interface object to be acted on. nvName A String containing the name of the added network variable. The name specified in this parameter can be a maximum of 16 characters, and it must not start with a number. In addition, it cannot include square brackets ([]), commas (,), or periods (.).
PAGE 414
Element Description nvObject The compatible network variable to be returned. A compatible network variable is one that is of the same type and direction as the source network variable. This method is used to construct an interface object for a host application. interfaceObject The Interface object to be acted on. nvName A String containing the name of the added network variable. The name specified in this parameter can be a maximum of 16 characters, and it must not start with a number.
PAGE 415
The created network variable will have polling enable. Added to API Prior to LNS Release 3.0. AddNvFromString Summary Adds a network variable to the interface using the string description created by the ToString method. The NetworkVariable object's ToString method exports the characteristics of a network variable to a text string. This string can be used to create a new network variable object using this method.
PAGE 416
Syntax newTypeSpec = interface.CreateTypeSpec(objectType) Element Description newTypeSpec newTypeSpec is the newly created TypeSpec object. interface The Interface object to be acted on. objectType The type of the TypeSpec object to be created. The possible values for this element, which are specified in the ConstTypeSpecObjectType constant, are as follows: 0 lcaTypeSpecNv The type applies to network variables.
PAGE 417
lcaConfigPropOptSetDefaults option), this method requires that the configuration property values be uploaded from the device (see the UploadConfigProperties method) or imported from the device’s external interface file (see the Import method). Availability Local, full, and lightweight clients. Syntax object.DownloadConfigProperties(downloadOptions) Element Description object The AppDevice object from which configuration properties are to be downloaded into a physical device.
PAGE 418
lcaConfigPropOptSetDefaults Sets the configuration property values in the AppDevice object to the default configuration property values stored in the DeviceTemplate, and downloads any changed values to the physical device on the network (if the lcaConfigPropOptLoadValues flag is set). Manufacturing-only configuration properties are not affected by this option unless it is ORed with lcaConfigPropOptIncludeMfgOn ly (8). This option should not be ORed with lcaConfigPropOptLoadUnknow n (4).
PAGE 419
default values may cause the download operation to fail. To exclude those configuration properties from a download, you should OR this value with the lcaConfigPropOptExcludeNvTy peDefaults (512) value. 8 lcaConfigPropOptIncludeMfgOnly Use this flag to in conjunction with the lcaConfigPropOptSetDefaults (2) and lcaConfigPropOptLoadUnknow n (4) options if you want the download operation to include manufacturing-only configuration properties.
PAGE 420
ORed with lcaConfigPropOptLoadUnknow n (4) and lcaConfigPropOptLoadValues (1), LNS would set all configuration properties that are not device-specific, and whose values are unknown to their default values, and then download those values into the device. This option should not be ORed with lcaConfigPropOptOnlyDeviceSp ecific (128). 128 lcaConfigPropOptOnlyDevice Specific Downloads only device-specific configuration properties into the device.
PAGE 421
However, updates to the device initiated by the other flags will be cancelled. For example, when combining this value with lcaConfigPropOptSetDefaults (2), the operation will set the values in the database to their defaults, but the pending update flag on the device will be cleared. As a result, those values will not be loaded into the device.
PAGE 422
Added to API Prior to LNS Release 3.0. RemoveNv Summary Removes a network variable from the Interface object. When this method is called, the network variable is removed from all connections containing it. If any affected connection then has only one remaining member, the connection is removed. You can only call this method on custom Interface objects (Interface objects accessed through the Interfaces property of an AppDevice or DeviceTemplate object) Availability Local, full, and lightweight clients.
PAGE 423
0 lcaConfigPropOptLoadDefinitions Reads the template file and loads the configuration property definitions for the device into the OpenLNS database if the configuration property template file on the device has not been imported or uploaded into the OpenLNS database. 1 lcaConfigPropOptLoadValues Uploads all configuration property values from the physical device on the network to the associated AppDevice object in the OpenLNS database.
PAGE 424
upload all unknown values in the OpenLNS database from the physical device on the network. Alternatively, you can OR this with the lcaConfigPropOptSetDefaults (2) values to upload all the unknown values into the OpenLNS database, and then set the uploaded values (as well as all values that were known in the database before the upload) as the device’s defaults in the OpenLNS database. Note that all configuration properties in an AppDevice object start in the unknown condition.
PAGE 425
• • • • • • • • MaxNvSupported MessageTags Name NetworkVariables Parent StaticNvCount SupportsDynamicNvsOnStaticLMOs Version ClassId Summary Identifies the object class of this object. This property allows the object type to be determined when it is unknown (for example, when the object was accessed using the Parent property of another object). Availability Local, full, lightweight, and independent clients. Note that some objects containing this property are not available to Independent clients.
PAGE 426
Added to API Prior to LNS Release 3.0. ConfigPropertiesAvailable Summary Indicates whether configuration property definitions are available for the device containing this Interface object. Availability Local, full, and lightweight clients. Syntax configPropsValue = intObject.ConfigPropertiesAvailable Element Description configPropsValue Boolean value. TRUE.
PAGE 427
CpByHandle Summary Retrieves the ConfigProperty object contained in the Interface property of an AppDevice object or in the Interface property of a DeviceTemplate object selected by its Handle property. Interface objects (belonging to AppDevice and DeviceTemplate objects), LonMarkObjects, and NetworkVariable objects each have a ConfigProperties collection that contains all of the configuration properties that apply to the object.
PAGE 428
DynamicLonMarkObjectCapacity Summary Indicates the number of dynamic LonMarkObject objects (functional blocks) that can be added to the device containing this interface. A functional block represents a collection of network variables and configuration properties on a device that perform a related function. For example, a digital input device with four switches could contain one functional block for each switch. In OpenLNS, functional blocks are represented by LonMarkObject objects.
PAGE 429
DynamicMessageTags Summary Returns the collection of dynamic MessageTag objects contained by this interface. Some custom interfaces support dynamic message tags, meaning that you can add message tags to them with the Add method. You cannot add dynamic message tags to a device’s main interface, and you cannot add them to some custom interfaces.
PAGE 430
Added to API Prior to LNS Release 3.0. MaxNvInUse Summary Indicates the current maximum network variable index in use on the device containing this Interface. This figure applies to all Interfaces on the device, and that this value reflects both static and dynamic network variables. The value of the MaxNvInUse property will always be equal to the value of the StaticNvCount property, minus 1, in Neuron hosted applications because they do not support dynamic network variables.
PAGE 431
Syntax maxNvValue = interfaceObject.MaxNvSupported Element Description interfaceObject The Interface object to be acted on. maxNvValue The maximum number of network variables supported. Data Type Integer. Read/Write Read only. Added to API Prior to LNS Release 3.0. MessageTags Summary Returns the collection of MessageTags associated with the object. This property contains the static message tags that belong to the interface.
PAGE 432
Data Type String. Read/Write Read/write. Added to API Depends on the object used to access the property. Generally, this property exists for the objects listed above as soon as they are added to the API. NetworkVariables Summary Returns the NetworkVariables collection object representing the network variables in that Interface object. Availability Local, full, and lightweight clients. Syntax nvCollection = interfaceObject.
PAGE 433
StaticNvCount Summary Indicates the number of network variables that are statically defined on the device that contains this Interface. Statically defined network variables have indexes ranging from 0 through n-1, where n is equal to the StaticNvCount property. These network variables cannot be removed from the device. Availability Local, full, and lightweight clients. Syntax staticNvCountValue = interfaceObject.StaticNvCount Element Description interfaceObject The Interface object to be acted on.
PAGE 434
You can determine if a LonMarkObject is static or dynamic by reading its IsDynamic property. FALSE. The static LonMarkObject objects (functional blocks) on the device containing this interface do not support the dynamic addition of network variables. Note: The only interface on a device that contains static LonMarkObjects is the device’s main interface (the Interface object is accessed through the device’s Interface property). Interface The Interface object to be acted upon. Data Type Integer.
PAGE 435
Interfaces The Interfaces object is a collection of Interface objects. This collection contains the set of custom interface objects that have been added to a device. You can use the Add method to create custom interfaces on any device that supports dynamic network variables, dynamic message tags, or dynamic LonMarkObjects. The following table summarizes the Interfaces object. Description Represents a collection of Interface objects. Added to API Prior to LNS Release 3.0.
PAGE 436
lcaErrDuplicateKey exception will be thrown. sourceInterfaceObj The existing Interface object used to create the new Interface object. If the sourceInterfaceObj element is specified, the new Interface object will be created with the same NetworkVariables collection as the Interface object referenced as the sourceInterfaceObj. If the sourceInterfaceObj is null, a new, empty Interface object will be created. Added to API Prior to LNS Release 3.0.
PAGE 437
some objects containing this property are not available to Independent clients. Syntax classIdValue = object.ClassId Element Description classIdValue The object class of the object. The following value is defined for the Intefaces object in the ConstClassIds constant: 20 lcaClassIdInterfaces object The object to be acted on. Data Type Integer. Read/Write Read only. Added to API Depends on the object used to access the property.
PAGE 438
Independent clients. Syntax retrievedObject = collObject.Item(index) retrievedObject = collObject.Item(stringExpression) Element Description retrievedObject The Interface object retrieved from the collection. collObject The Interfaces collection object to be acted on. index A Long type specifying the ordinal index of the Interface object to be retrieved. stringExpression A string type specifying the name of the Interface object to be retrieved. Data Type Object. Read/Write Read only.
PAGE 439
you can browse a collection to find a particular item by using the _NewEnum property. See the IEnumVARIANT interface for details. • If you are developing your OpenLNS app in Visual Basic, you do not need to use the _NewEnum property because it is automatically used in the implementation of For Each ... Next statements. • If you are developing your OpenLNS app in C#, you do not need to use the _NewEnum property explicitly because it is automatically used in the implemention of foreach statements.
PAGE 440
Properties The LdrfLanguage object contains the following properties: • • • • • • • ClassId Extension LanguageCode LanguageId LdrfId Name Parent ClassId Summary Identifies the object class of this object. This property allows the object type to be determined when it is unknown (for example, when the object was accessed using the Parent property of another object). Availability Local, full, lightweight, and independent clients.
PAGE 441
property types, functional profiles, and enumeration types can all reference text information used to describe their name, units, and function. This text information is contained in separate language files. There is one language file for every language supported by a resource file set. When a language file is translated, the references contained in the network variable types, configuration property types, and functional profiles still point to the appropriate strings.
PAGE 442
Data Type String. Read/Write Read only. Added to API LNS Release 3.0. LanguageCode Summary Contains the 3-letter language code for the language to which the LdrfLanguage object applies. Each LdrfLanguage object contains information about a language. For example, "ENU" is used for U.S. English. Availability Local, full, lightweight, and independent clients. Syntax ldrfCode = ldrfObject.
PAGE 443
ldrfCode A 3-letter identifier for the language that the LdrfLanguage object applies to.
PAGE 444
ldrfId The 32-bit ID representing this language. This value is not normally used by OpenLNS clients unless they directly access the Language Device Resource File API. ldrfObject Data Type Long. Read/Write Read only. Added to API LNS Release 3.0. The LdrfLanguage object to be acted on. Name Summary Specifies the name of an object as a character string. This property is case sensitive. Searches by name must match case.
PAGE 445
object Any object for which the parent is desired. Data Type Object. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. LdrfLanguages The LdrfLanguages object is a collection of LdrfLanguage objects. This collection represents all the languages known by OpenLNS and the Language Device Resource File API.
PAGE 446
Independent clients. Syntax classIdValue = object.ClassId Element Description classIdValue The object class of the object. The following value is defined for the LdrfLanguages object in the ConstClassIds constant: 84 lcaClassIdLdrfLanguages object The object to be acted on. Data Type Integer. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API.
PAGE 447
Independent clients. Syntax retrievedObject = collObject.Item(index) retrievedObject = collObject.Item(stringExpression) Element Description retrievedObject The LdrfLanguage object retrieved from the collection. collObject The LdrfLanguages collection object to be acted on. index A Long type specifying the ordinal index of the LdrfLanguage object to be retrieved. stringExpression A string type specifying the name of the LdrfLanguage object to be retrieved. Data Type Object.
PAGE 448
you can browse a collection to find a particular item by using the _NewEnum property. See the IEnumVARIANT interface for details. • If you are developing your OpenLNS app in Visual Basic, you do not need to use the _NewEnum property because it is automatically used in the implementation of For Each ... Next statements. • If you are developing your OpenLNS app in C#, you do not need to use the _NewEnum property explicitly because it is automatically used in the implemention of foreach statements.
PAGE 449
Methods The LonMarkAlarm object does not contain any methods. Properties The LonMarkObject object contains the following properties: • • • • • • • • • • AlarmType ClassId IndexToSNVT LimitValue Location ObjectId Parent PriorityLevel TimeStamp Value AlarmType Summary Identifies the alarm condition represented by the LonMarkAlarm object. Availability Local, full, and lightweight clients. Syntax typeValue = lmAlarm.AlarmType Element Description lmAlarm The LonMarkAlarm object to be acted on.
PAGE 450
255 lcaAlarmTypeNull Data Type Integer. Read/Write Read only. Added to API Prior to LNS Release 3.0. ClassId Summary Identifies the object class of this object. This property allows the object type to be determined when it is unknown (for example, when the object was accessed using the Parent property of another object). Availability Local, full, lightweight, and independent clients. Note that some objects containing this property are not available to Independent clients.
PAGE 451
LonMarkObject that caused the current alarm condition. LonMarkAlarm Data Type Long. Read/Write Read only. Added to API LNS Release 3.20. The LonMarkAlarm object being acted upon. LimitValue Summary Represents the data limit that the DataValue object was compared against in determining that an alarm condition exists. The format for this property is determined by the AlarmFormat property contained in the LonMarkObject object which contains the specified LonMarkAlarm object.
PAGE 452
ObjectId Summary Returns the ID of the LonMarkObject to which this LonMarkAlarm applies. On static interfaces, objects are numbered from 0 to n-1, where n is the number of objects in an AppDevice. On dynamic interfaces, the object index may be greater than or equal to the value n (the number of objects on the device). See the LonMark Application Layer Interoperability Guidelines for more information.
PAGE 453
this property exists for an object as soon as the object is added to the API. PriorityLevel Summary Returns the priority level of the Alarm. Availability Local, full, and lightweight clients. Syntax priorityLevelValue = lmaObject.PriorityLevel Element Description lmaObject The LonMarkAlarm object to be acted on. priorityLevelValue The priority level of the alarm as an integer.
PAGE 454
For example, the millisecond before the end of this millennium would be: 2999/12/31 23:59:59:999. Data Type String. Read/Write Read only. Added to API Prior to LNS Release 3.0. Value Summary Represents the data value that caused the alarm condition. The format of this property depends upon the AlarmFormat of the LonMarkObject object containing this LonMarkAlarm object. By default, it returns a string of 4 hex byte values. Availability Local, full, and lightweight clients.
PAGE 455
• • • • • • • • • • • • • • • • • • • • • • • • • ClassId ComponentApps ConfigProperties Description Extensions FuncProfileDescription FuncProfileIsDerived FuncProfileName FuncProfileProgrammaticName Index IsDynamic LonMarkAlarm Mode Name NetworkVariables Parent ParentInterface PrincipalNv ProgrammaticName ReportMask Request SelfTestResults Status TypeIndex TypeSpec Methods The LonMarkObject contains the following methods.
PAGE 456
The network variable and LonMarkObject must belong to the same device interface for this method to succeed. If they do not belong to the same interface, the LCA, #4 lcaErrInvalidOleObject exception will be thrown. You can move a LonMarkObject or network variable from one interface to another with the MoveToInterface method. Notes: If you use this method to assign a static network variable to a dynamic LonMarkObject, the NS, #286 lcaErrNsLmobjNvNotDynamic exception will be thrown.
PAGE 457
network variables and LonMarkObjects that reflect the device’s functionality on the network. You can use the MoveToInterface method to move a dynamic network variable or LonMarkObject from one custom interface on a device to another. An advantage of this is that you do not have to delete the network variable or LonMarkObject from the first custom interface, and then add it back to the second one.
PAGE 458
Syntax Added to API object.MoveToInterface newInterface Element Description object The LonMarkObject to be acted upon. newInterface The Interface object to which the object should be moved. LNS Release 3.20. UnassignNetworkVariable Summary Removes a dynamic network variable from a LonMarkObject object. The network variable to be removed must have first been added to the LonMarkObject with the AssignNetworkVariable method.
PAGE 459
• • • • • • • • • • • • • • • • Index IsDynamic LonMarkAlarm Mode Name NetworkVariables Parent ParentInterface PrincipalNv ProgrammaticName ReportMask Request SelfTestResults Status TypeIndex TypeSpec AlarmFormat Summary Determines the format of the LonMarkAlarm object contained by this LonMarkObject. A LonMarkAlarm object contains two properties that determine the reading that caused the alarm (Value) and the limit it exceeded (LimitValue).
PAGE 460
4 lcaAlarmFormatUShortStr 1-byte unsigned decimal string. 5 lcaAlarmFormatLong 2-byte integer. 6 lcaAlarmFormatLongStr 2-byte decimal string. 7 lcaAlarmFormatUlong 2-byte unsigned integer. 8 lcaAlarmFormatULongStr 2-byte unsigned decimal string. 9 lcaAlarmFormatS32 4-byte integer. 10 lcaAlarmFormatS32Str 4-byte decimal string. 11 lcaAlarmFormatFloat 4-byte real. 12 lcaAlarmFormatFloatStr 4-byte real format string. 13 lcaAlarmFormatBinary 4 binary bytes. lmObject The LonMarkObject to be acted on.
PAGE 461
object The object to be acted on. Data Type Integer. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. ComponentApps Summary Contains the ComponentApps collection object associated with the specified LonMarkObject. The ComponentApps collection is a list of LNS plug-in commands that are associated with a particular object type.
PAGE 462
Description Summary Stores description information about the LonMarkObject object. Availability Local, full, lightweight, and independent clients. Note that some collections are not available to Independent clients. Syntax stringValue = object.Description Element Description stringValue A string description of the LonMarkObject. object The LonMarkObject to be acted on. Data Type String. Read/Write Read/write. Added to API This depends on the object used to access the property.
PAGE 463
FuncProfileDescription Summary Provides a desciptive comment of the functional profile associated with the LonMarkObject. This property is accessed from the functional profile template file associated with the object. This property is language dependent. Set the System object's ResourceLanguageId to control the language. Availability Local, full, and lightweight clients. Syntax description = object.FuncProfileDescription Element Description object The LonMarkObject to be acted on.
PAGE 464
FuncProfileName Summary Returns the functional profile name associated with the LonMarkObject. This property is accessed from the functional profile template file associated with the object. The name returned by this property is accessed from the functional profile template file associated with this object. This property is language dependent. Set the System object's ResourceLanguageId to control the language. Availability Local, full, and lightweight clients. Syntax typeNameValue = object.
PAGE 465
Availability Local, full, and lightweight clients. Syntax indexValue = lmObject.Index Element Description lmObject The LonMarkObject to be acted on. indexValue The device index number of the LonMarkObject. Data Type Integer. Read/Write Read only. Added to API Prior to LNS Release 3.0. IsDynamic Summary Indicates whether the LonMarkObject is dynamic.
PAGE 466
Read/Write Read only. Added to API Prior to LNS Release 3.0. Mode Summary Returns the scope of the functional profile template resource file that defines the LonMarkObject. Availability Local, full, and lightweight clients. Syntax classMode = lmObject.Mode Element Description classMode The scope of the functional profile template resource file that defines the LonMarkObject.
PAGE 467
-1 lcaResourceScopeUnknown The scope of the resource file is not known, or could not be found. -2 lcaResourceScopeAutoDetermination Select this value to have LNS determine the value of the Mode property for the LonMarkObject automatically. If you select this value, OpenLNS will iterate through all the available resource files from most specific to most general (i.e. highest scope to lowest scope) until it finds the functional profile template resource file containing the LonMarkObject object’s definition.
PAGE 468
Added to API Prior to LNS Release 3.0. Name Summary Specifies the name of an object as a character string. This property is case sensitive. Searches by name must match case. This property can be a maximum of 85 characters long, but it may not contain the forward slash (/), back slash (\), period (.), and colon (:) characters. Availability Local, full, lightweight, and independent clients. Note that some objects that contain this property are not available to Independent clients.
PAGE 469
Syntax parentObject = object.Parent Element Description parentObject The object that is the parent of the specified object. object Any object for which the parent is desired. Data Type Object. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. Comments The parent object is determined by the means in which a child object is accessed, not by the OpenLNS Object hierarchy.
PAGE 470
Added to API LNS Release 3.20. PrincipalNv Summary Returns the principal NetworkVariable object associated with this LonMarkObject object. This information is accessed from the functional profile template file associated with this LonMarkObject object. Availability Local, full, and lightweight clients. Syntax nvObject = lmObject.PrincipalNv Element Description lmObject The LonMarkObject object to be acted on. nvObject The principal network variable of the LonMarkObject object.
PAGE 471
Element Description progName The programmatic name of the object. Object The LonMarkObject to be acted on. Data Type String. Read/Write Read-only for static LonMarkObject objects. Read/write for dynamic LonMarkObject objects. You can check if a LonMarkObject is dynamic or static by reading the IsDynamic property. When writing to this property, you should note that some devices, such as the SmartServer, require that all network variables within the device have a unique programmatic name.
PAGE 472
Syntax statusObject = lmObject.ReportMask Element Description statusObject The ObjectStatus object returned. lmObject The LonMarkObject object to be acted on. Data Type ObjectStatus object. Read/Write Read-only. Added to API Prior to LNS Release 3.0. Request Summary Requests a change to the functionality of a LonMarkObject, or requests an update of the information contained in the LonMarkObject. Availability Local, full, and lightweight clients. Syntax lmoObject.
PAGE 473
3 lcaLonMarkObjectRequestSelfTest Performs a self-test on the object. The SelfTestResults property of the LonMarkObject will be updated to reflect the results of the test. 4 lcaLonMarkObjectRequestUpdateAlarm Updates the alarm status of the LonMarkObject. In this case, the LonMarkAlarm property of the LonMarkObject will be updated to reflect the current alarm status of the LonMarkObject on the network. 5 lcaLonMarkObjectRequestReportMask Reports the status bit mask of the LonMarkObject.
PAGE 474
in the LonMarkAlarm property of the LonMarkObject will be cleared until the next alarm condition occurs. 11 lcaLonMarkObjectRequestAlarmNotify Enabled Enables alarm notification for the LonMarkObject. 12 lcaLonMarkObjectRequestAlarmNotify Disabled Disables alarm notification for the LonMarkObject. 13 lcaLonMarkObjectRequestManual Control Places the LonMarkObject under manual control. 14 lcaLonMarkObjectRequestRemote Control Places the LonMarkObject under remote control.
PAGE 475
To run a self-test on an object where the result may take more than 20 seconds to complete, follow these steps: 1. Request a self-test of the LonMarkObject by writing the lcaLonMarkObjectRequestSelfTest (3) value to the object’s Request property. 2. After the exception is raised, poll the SelfTestInProgress property of the ObjectStatus object until it returns False. 3. Check the FailSelfTest property of the ObjectStatus object to determine why the test failed.
PAGE 476
Status Summary Stores an ObjectStatus object which contains information reflecting the current status of the LonMarkObject object. Some LonMarkObjects do not support all of the status attributes reflected in an ObjectStatus object, and so some of the information contained in this object may not be useful. You can use the ReportMask property of the LonMarkObject to determine which status attributes are supported. The ReportMask property also contains an ObjectStatus object.
PAGE 477
TypeIndex Summary Returns the type index of the LonMark object. Each LonMarkObject object uses a type defined in the functional profile template resource files. This property returns the index assigned to that type in the functional profile template resource file containing its definition. See the LonMark Application Layer Interoperability Guidelines for more information on the different types of functional profile templates you can associate with a LonMarkObject.
PAGE 478
Data Type TypeSpec object. Read/Write Read only. Added to API OpenLNS. LonMarkObjects A LonMarkObjects object is a collection of LonMarkObject objects. An instance of this collection that is accessed through an Interface object contains the LonMarkObject (functional block) objects that define that interface. You can use the ItemByIndex method, the Item property, or the ItemByProgrammaticName method to retrieve a LonMarkObject from the collection.
PAGE 479
switch. In OpenLNS, function blocks are represented by LonMarkObject objects. Some custom device interfaces support dynamic LonMarkObject objects, which means that you can add them to the interface manually. You can determine if an interface supports dynamic LonMarkObject objects by reading the interface’s DynamicLonMarkObjectCapacity property.
PAGE 480
brackets ([ ]), periods (.) or commas (,). fbType Enter a value between 0-25,000. You can use this value to identify the functional profile template associated with the new LonMarkObject. See the LonMark Application Layer Interoperability Guidelines for more information on the different types of functional profile templates you can associate with a LonMarkObject. Added to API Prior to LNS Release 3.0. AddEx Summary Adds a dynamic LonMarkObject object to a custom interface containing this collection.
PAGE 481
lcaTypeSpecLmo, or it is invalid in any other way. Availability Local, full, and lightweight clients. Syntax newLonmarkObject = lonMarkObjects.AddFromTypeSpec(fbName, lmoTypeSpec) Added to API Element Description newLonMarkObjec t The new LonMarkObject object to be created. lonMarkObjects The collection of LonMarkObjects objects to be added. lmoName A String containing the name of the LonMarkObject. lmoTypeSpec The TypeSpec object to be used as the source for the new LonMarkObject. OpenLNS.
PAGE 482
Syntax retrievedObject = collection.ItemByProgrammaticName progName Element Description retrievedObject The LonMarkObject to be retrieved from the collection. collection The LonMarkObjects collection being acted upon. progName The programmatic name of the LonMarkObject to be retrieved. Data Type LonMarkObject object. Added to API LNS Release 3.20. Remove Summary Removes a LonMarkObject object from the specified LonMarkObjects collection.
PAGE 483
acted upon. deviceIndex A Long value indicating the device index number of the LonMarkObject to be deleted. removalFlags The removal options to be used when deleting the LonMarkObject. These options determine whether or not network variables assigned to the LonMarkObject will be deleted.
PAGE 484
ClassId Summary Identifies the object class of this object. This property allows the object type to be determined when it is unknown (for example, when the object was accessed using the Parent property of another object). Availability Local, full, lightweight, and independent clients. Note that some objects containing this property are not available to Independent clients. Syntax classIdValue = object.ClassId Element Description classIdValue The object class of the object.
PAGE 485
LonMarkObjects collection by passing its index (ordinal position) within that collection as the argument for the Item property. Index values start at 1. You can also retrieve a LonMarkObject object in LonMarkObjects collections that contain objects with the Name property by passing the object’s name as a string expression Availability Local, full, lightweight, and independent clients. Note that some objects containing this property are not available to Independent clients.
PAGE 486
Comments The parent object is determined by the means in which a child object is accessed, not by the OpenLNS Object hierarchy. _NewEnum Summary Enables you to iterate over the objects in a collection using For Each ... Next statements. • If you are developing your OpenLNS app in Visual C++, you can browse a collection to find a particular item by using the _NewEnum property. See the IEnumVARIANT interface for details.
PAGE 487
• • • • • • • • • • AppDeviceName ClassId ConnectDescTemplate Direction Index IsDynamic MtHubs MtTargets Name Parent Methods The MessageTag object contains the following methods. • • • AddTarget Connect Disconnect AddTarget Summary Adds a single MessageTag to a hub's pending target list. This method defines a hub message tag's pending target list. This list is used when the Connect or Disconnect method is invoked to create or remove a message tag connection.
PAGE 488
• A static or dynamic message tag may only appear in one connection (it may be a hub or target, but not both). A msg_in tag may appear in multiple connections. • If a static or dynamic tag is a hub, its targets may be a mix of declared tags, dynamic tags and msg_in tags. • When a msg_in tag is a hub, its targets must all be static tags or dynamic tags because the msg_in tag may only be used to receive messages. Note: These requirements prevent the creation of mirrored connections.
PAGE 489
You can use the OnNodeConnChangeEvent to track when connections are created or modified with this method. Availability Local, full, and lightweight clients. Syntax MtObject.Connect Added to API Element Description MtObject The hub MessageTag object to be connected. Prior to LNS Release 3.0. Disconnect Summary Removes a hub or message tag's entire connection or disconnects the message tags contained in the hub's pending target list.
PAGE 490
• • • • • • Index IsDynamic MtHubs MtTargets Name Parent AddressTableIndex Summary Contains the address table index value assigned to the message tag. Some devices communicate with one another by sending explicit messages on a message tag. When an OpenLNS application requests that a device should share information with another device via a dynamic message tag, an address table entry is created on the device sending the information. Note that address table entries for static message tags is pre-defined.
PAGE 491
AppDevice Summary Identifies the AppDevice object containing this message tag. Availability Local, full, and lightweight clients. Syntax appDevObject = object.AppDevice Element Description appDevObject The AppDevice object to be returned. object The MessageTag object to be acted on. Data Type AppDevice object. Read/Write Read only. Added to API Prior to LNS Release 3.0. AppDeviceName Summary Returns the name of an application device that contains the message tag.
PAGE 492
Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. ConnectDescTemplate Summary Contains the ConnectDescTemplate object associated with the specified MessageTag object. This template contains parameters used when creating connections.
PAGE 493
constant, are as follows: 0 lcaMtDirectionInput The message tag is an input message tag. 2 lcaMtDirectionOutput The message tag is an output message tag. object The MessageTag object. Data Type Integer. Read/Write Read only. Added to API Prior to LNS Release 3.0. Index Summary Returns the index within an application device of the message tag. Availability Local, full, and lightweight clients. Syntax index = object.Index Element Description object The object to be acted on.
PAGE 494
object Data Type Boolean. Read/Write Read only. Added to API LNS Release 3.0. The MessageTag object to be acted on. MtHubs Summary Returns a collection containing all message tag hubs for which the message tag is a target, including the message tag if it is the hub for a connection. Along with the MtTargets property, this property enables you to manage complex network connections involving multiple hubs and sets of targets.
PAGE 495
Name Summary Specifies the name of an object as a character string. This property is case sensitive. Searches by name must match case. This property can be a maximum of 85 characters long, but it may not contain the forward slash (/), back slash (\), period (.), and colon (:) characters. Availability Local, full, lightweight, and independent clients. Note that some objects that contain this property are not available to Independent clients. Syntax stringValue = object.
PAGE 496
MessageTags A MessageTags object is a collection of MessageTag objects. Note that the Interface object contains two MessageTags collections: 1. The MessageTags collections accessed through the MessageTags property, which contains the interface’s static message tags. 2. The MessageTags collections accessed through the DynamicMessageTags property, which contains the interface’s dynamic message tags. The following table summarizes the MessageTags object. Description A collection of MessageTag objects.
PAGE 497
devices is described in the OpenLNS Programmer’s Guide. The name of the new message tag (as specified with the name element) must be unique on the Interface object containing the MessageTags collection. If you attempt to add a message tag to a message tag collection on a static interface or a custom interface that does not support dynamic message tags, the LCA, #119 lcaErrInterfaceNotModifyable exception will be thrown.
PAGE 498
name Added to API A Long value specifying the collection index of the object to remove, or a String value specifying the name of the object to remove. Prior to LNS Release 3.0. Properties The MessageTags object contains the following properties: • • • • • ClassId Count Item Parent _NewEnum ClassId Summary Identifies the object class of this object.
PAGE 499
Element Description returnValue The number of objects in the collection as a long integer. object The collection object to be acted on. Data Type Long. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. Item Summary A MessageTags object is a collection of MessageTag objects.
PAGE 500
Parent Summary Returns the object that spawned the current child object. The parent object is determined by the means in which a child object is accessed, not by the OpenLNS Object hierarchy. Availability Local, full, lightweight, and independent clients. Note that some collection objects are not available to Independent clients. Syntax parentObject = object.Parent Element Description parentObject The object that is the parent of the specified object.
PAGE 501
Data Type Object. Read/Write Read only. Added to API OpenLNS. MonitorSet A MonitorSet object represents a set of network variable and message tag monitor points. You can use this object to maintain and monitor all of the monitor points it contains as a group (points can also be controlled individually). This object also contains the default settings that are applied to all monitor points as they are added to the set.
PAGE 502
use in multiple client sessions or that you intend to use multiple times, you should use the permanent MonitorSet objects described earlier in this section. However, if you do not need to re-use a monitor set, you should use temporary monitor sets, as it takes less time and network resources to create them.
PAGE 503
• • Parent Tag Methods The object contains the following methods. • • • • Close Disable Enable Open Close Summary Closes a MonitorSet object. For permanent MonitorSet objects, this method causes the monitor set to be closed, and all the monitor points (MsgMonitorPoint and NvMonitorPoint objects) in the set to be disabled. You can re-open and re-enable the monitor set later with the Open method.
PAGE 504
network variable monitor point. If you explicitly disable monitoring of a single monitor point, you can only re-enable monitoring of that monitor point by calling the Enable method on the monitor point. Availability Local, full, lightweight, and independent clients. Note that temporary MonitorSet objects and temporary monitor points are not available on Independent clients. Syntax object.Disable Added to API Element Description object The MonitorSet object to be disabled. LNS Release 3. 0.
PAGE 505
are not available on Independent clients. Syntax object.Enable doPoll Element Description object The MonitorSet object to be enabled. doPoll A Boolean value. TRUE. Turn on polled monitoring for the network variable monitor points in the monitor set. FALSE. Leave polled monitoring of this monitor set turned off. Added to API LNS Release 3. 0. Open Summary Opens a MonitorSet object, which causes all the monitor points in the monitor set to be instantiated.
PAGE 506
clients. Syntax monSetObject.Open doEnable, doPoll Element Description monSetObject The MonitorSet object to be closed. doEnable A Boolean value. TRUE. Automatically invokes the Enable method on the monitor set as it is opened. This enables monitoring on all of the network variable and message monitor points in the monitor set that have not been explicitly disabled with the Disable method.
PAGE 507
monitor the monitor points in the monitor set. Added to API LNS Release 3.0. Properties The MonitorSet object contains the following properties: • • • • • • • • • • • ClassId IsEnabled IsOpen IsPollingEnabled MsgMonitorPoints MsgOptions Name NvMonitorPoints NvOptions Parent Tag ClassId Summary Identifies the object class of this object. Availability Local, full, lightweight, and independent clients. Note that some objects containing this property are not available to Independent clients.
PAGE 508
IsEnabled Summary Indicates whether the monitor set is enabled. A monitor point must be enabled before polling, implicit bound monitoring, or explicit bound monitoring and control of the monitor point can be perfromed. You can enable all the monitor points in a monitor set at once using the MonitorSet object's Enable method. Alternatively, you can enable an individual network variable monitor point using the NvMonitorPoint object's Enable method. Message monitor points cannot be individually enabled.
PAGE 509
IsOpen Summary Indicates whether the specified object is currently open. You can open the MonitorSet object with the Open method, and you can close it with the Close method. When you create a MonitorSet as a temporary monitor set, OpenLNS automatically opens it. Once a temporary monitor set is closed, it will be deleted Availability Local, full, lightweight, and independent clients. Note that temporary MonitorSet objects are not available on Independent clients. Syntax isOpenFlag = Object.
PAGE 510
Element Description isPollingEnabledFlag A Boolean value indicating whether polled monitoring is enabled. TRUE. Polled monitoring is enabled. FALSE. Polled monitoring is not enabled. msObject Data Type Boolean. Read/Write Read only. Added to API LNS Release 3.0. The MonitorSet object to be acted on. MsgMonitorPoints Summary Contains the collection of all message tag monitor points (MsgMonitorPoint objects) that have been added to the monitor set.
PAGE 511
The MsgMonitorOptions object contained within this property is not passed by reference. If you acquire a MsgMonitorOptions object through the MsgOptions property and modify it, you must then explicitly assign the modified MsgMonitorOptions object back to the MsgOptions property for the changes to take effect. This following code sample demonstrates this procedure: Set msgOptions = monSet.MsgOptions msgOptions.Name = "Device 003" Set monSet.
PAGE 512
(.), and colon (:) characters. Availability Local, full, lightweight, and independent clients. Note that some objects that contain this property are not available to Independent clients. Syntax stringValue = object.Name Element Description stringValue The name of the object. object The object to be acted on. Data Type String. Read/Write Read/write. Added to API Depends on the object used to access the property.
PAGE 513
The NvMonitorOptions object contained within this property is not passed by reference. If you acquire a NvMonitorOptions object through the NvOptions property and modify it, you must then explicitly assign the modified NvMonitorOptions object back to the NvOptions property for the changes to take effect. This following code sample demonstrates this procedure: Set nvOptions = monSet.NvOptions nvOptions.Name = "Device 003" Set monSet.
PAGE 514
clients. Syntax parentObject = object.Parent Element Description parentObject The object that is the parent of the specified object. object Any object for which the parent is desired. Data Type Object. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. Tag Summary Stores any extra data associated with the monitor point or monitor set.
PAGE 515
Independent clients. Syntax tagValue = Object.Tag Element Description Object The monitor point or monitor set object to be acted on. tagValue The tag associated with the object. Data Type Variant. Read/Write Read/write. Added to API LNS Release 3.0. MonitorSets The MonitorSets object contains a collection of MonitorSet objects representing all the monitor sets on a device. If a device does not support monitor sets, an empty collection will be returned when you attempt to access this collection.
PAGE 516
lcaMgmtModeDeferConfigUpdates (1), you must change the management mode to lcaMgmtModePropagateConfigUpdates (0) before opening the monitor set. You can do so by setting the MgmtMode property of the System object to lcaMgmtModePropagateConfigUpdates (0). You can access the MonitorSets collection through the MyVNI and CurrentMonitorSets properties of the Network object. You should use the MyVNI property when you are going to add new MonitorSet objects to the collection.
PAGE 517
index of the MonitorSet object to be removed, or a String value specifying the name of the MonitorSet object to be removed. Added to API LNS Release 3.0. Properties The MonitorSets object contains the following properties: • • • • • ClassId Count Item Parent _NewEnum ClassId Summary Identifies the object class of this object. This property allows the object type to be determined when it is unknown (for example, when the object was accessed using the Parent property of another object).
PAGE 518
Element Description returnValue The number of objects in the collection as a long integer. object The collection object to be acted on. Data Type Long. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. Item Summary Returns a MonitorSet object from a MonitorSets collection.
PAGE 519
Parent Summary Returns the object that spawned the current child object. The parent object is determined by the means in which a child object is accessed, not by the OpenLNS Object hierarchy. Availability Local, full, lightweight, and independent clients. Note that some collection objects are not available to Independent clients. Syntax parentObject = object.Parent Element Description parentObject The object that is the parent of the specified object.
PAGE 520
Data Type Object. Read/Write Read only. Added to API OpenLNS. MsgMonitorOptions The MsgMonitorOptions object contains a set of monitoring options that can be applied to the message monitor points that OpenLNS is monitoring. Depending on how this object is accessed, writing to this it may affect the monitoring options used for an entire monitor set, or for an individual message tag monitor point.
PAGE 521
• UseAsyncSend Methods The MsgMonitorOptions object does not contain any methods. Properties The MsgMonitorOptions object contains the following properties: • • • • • • • • • • Authentication ClassId FilterByCode FilterBySource FilterCode Parent Priority Retries ServiceType UseAsyncSend Authentication Summary Determines whether the authenticated service will be used when sending a message monitor point updates using the Value property.
PAGE 522
Independent clients. Syntax classIdValue = object.ClassId Element Description classIdValue The object class of the object. The following value is defined for the MsgMonitorOptions object in the ConstClassIds constant: 76 lcaClassIdMsgMonitorOptions object The object to be acted on. Data Type Integer. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API.
PAGE 523
FilterBySource Summary Indicates whether message tag values will be filtered by the source device. This property can be combined with the FilterByCode property to allow only message tags with certain codes from certain sources to be passed to your client application via a MsgMonitorPoint object. Availability Local, full, lightweight, and independent clients. Note that temporary MonitorSet objects and temporary monitor points are not available on Independent clients. Syntax filterBySource =msgMonOpts.
PAGE 524
codes in the range 80–126 and 128–255 cannot be received by an OpenLNS application. This is because these codes are used for network management, diagnostic, and network variable messages, and they are processed directly by the NSD. msgMonOpts Data Type Long. Read/Write Read/write. Added to API LNS Release 3.0. The MsgMonitorOptions object. Parent Summary Returns the object that spawned the current child object.
PAGE 525
priorityValue A Boolean value. TRUE. Priority is used when polling or explicitly updating a message monitor point using the Value property. FALSE. Priority is not used. monOptsObject Data Type Boolean. Read/Write Read/write. Added to API LNS Release 3.0. The MsgMonitorOptions to be acted on. Retries Summary Specifies the number of retries to use for acknowledged, request/response, or repeated service messages. This applies to network management messages only.
PAGE 526
1–15. This property applies to network management messages only. monOptsObject Data Type Long. Read/Write Read/write. Added to API LNS Release 3.0. The MsgMonitorOptions object to be acted on. ServiceType Summary Determines the service type used when sending explicit messages with a message monitor point. You cannot set this property through the CurrentOptions property of a temporary monitor point, as the CurrentOptions properties of all temporary monitor points are not accessible.
PAGE 527
service. The device does not send acknowledgment messages; however, repeat messages are sent to the device after the initial message is sent to it to ensure that it reaches its destination. You can set the number of repeat messages to send, and the interval at which they will be sent, by writing to the RepeatCount and RepeatTimer properties. 2 lcaSvcUnackd Unacknowledged messaging service. The device does not send acknowledgment messages.
PAGE 528
been successfully sent, as described earlier. However, you can also use the OnMsgMonitorPointErrorEvent and OnNvMonitorPointErrorEvent events to determine when values are not successfully sent. These events are generated whenever there is a write failure on a monitor point. See the Monitor and Control chapter in the OpenLNS Programmer’s Guide for more information. Availability Local, full, lightweight, and independent clients.
PAGE 529
with the Write method because it reduces the time required to update the values on the network. FALSE. OpenLNS waits for the completion code to return after it sends each value before returning from the method, as with LNS versions prior to LNS 3.20. Other client applications will be able to successfully update the monitor point while your application is waiting for the completion code.
PAGE 530
MsgMonitorPoint A MsgMonitorPoint represents a single monitored or controlled message tag. You can use message monitor points to monitor LONWORKS messages from application devices on your network with your application. For an overview of message monitor points and how they work, see the Monitor and Control chapter in the OpenLNS Programmer’s Guide.
PAGE 531
Advise Summary Enables update and error events for an object that implements the ILcaMsgMonitorPointListener or ILcaNvMonitorPointListener interface. This method should only be used if the development environment supports multi-threading (such as Visual C++). When you call this method, OpenLNS will provide event notification of updates and update errors using callbacks, instead of Windows messaging.
PAGE 532
For example, if you call the Disable method on a MsgMonitorPoint object named Point A, and then call the Disable method on the monitor set containing Point A, Point A would not be enabled. All other monitor points in the monitor set, however, would be enabled. Once you have explicitly disabled a MsgMonitorPoint with the Disable method, you can only re-enable that monitor point by calling the Enable method on it, or by closing and re-opening the monitor set it belongs to.
PAGE 533
Syntax Added to API object.Ensable Element Description object The MsgMonitorPoint object to be enabled. LNS Release 3.20. SendMsgWait Summary Sends a message that requires a synchronous response on a MsgMonitorPoint object created using the GetMessagePoint method. The AppDevice object's GetMessagePoint method creates an MsgMonitorPoint object which can be used to send messages to the device.
PAGE 534
Syntax Added to API mpObject.Unadvise tag Element Description tag An Integer type. This tag parameter should use the tag that was returned when the Advise method was called. mpObject The MsgMonitorPoint object to be acted on. LNS Release 3.0.
PAGE 535
CurrentOptions Summary Contains the current monitoring options for this message monitor point. Once the monitor set containing a monitor point has been opened, you can use this property to set the monitoring options that will be used for the monitor point during that particular session. For monitor points in MonitorSet objects created as permanent monitor sets, the options contained in this property default to the options set in the DefaultOptions property of the MsgMonitorPoint.
PAGE 536
message monitor point is opened. These options are read when the monitor set containing the monitor point is opened. Changes to these options will not take effect until the next time the monitor set is opened. Use the CurrentOptions property to change the active monitoring options to use for a monitor point that is currently enabled. For message monitor points, the options contained in the DefaultOptions property default to the options set in the permanent monitor set’s MsgOptions property.
PAGE 537
InputFormatSpec Summary Contains the FormatSpec object used to determine the format for incoming messages for this MsgMonitorPoint object. The FormatSpec object contained within this property is not passed by reference. If you modify the values assigned to the properties of a local FormatSpec object, you must then explicitly assign the modified FormatSpec object back to the InputFormatSpec property of the MsgMonitorPoint for the changes to take effect.
PAGE 538
Data Type String. Read/Write Read/write. Added to API Depends on the object used to access the property. Generally, this property exists for the objects listed above as soon as they are added to the API. OutputDataPoint Summary Contains an OutputDataPoint object that can be used to send a message to the device monitored by the MsgMonitorPoint object, as long as the message does not require a response.
PAGE 539
msgMonitorPointObject.OutputFormatSpec fsObject.AltFormatName = "SNVT_temp_f#SI" Set msgMonitorPointObject.OutputFormatSpec = fsObject Availability Local, full, lightweight, and independent clients. Note that temporary MonitorSet objects and temporary monitor points are not available on Independent clients. Syntax fsObject = msgMpObject.OutputFormatSpec Element Description fsObject The FormatSpec object used to format outgoing messages. msgMpObject The MsgMonitorPoint object to be acted on.
PAGE 540
open in order for you to access this property. When the AppDevice object's GetMessagePoint method is called, the DataPoint object that is created can set this property to send a request message to the device monitored by this MsgMonitorPoint object. The AutoWrite property of this DataPoint object is set to False; therefore, you need to explicitly propagate the message to the network after the DataPoint object's Value, RawValue , or FormattedValue property is set.
PAGE 541
Tag Summary Stores any extra data associated with the monitor point or monitor set. The data stored in this property is not used by OpenLNS, and is available as soon as the data point or monitor set is created in a monitor and control session. You can use this property to store any data your application may need when using the monitor set or monitor point.
PAGE 542
Events The MsgMonitorPoint object contains the following events: • • UpdateErrorEvent UpdateEvent UpdateErrorEvent Summary Indicates that a write failure or a poll failure has occurred on the message monitor point that generated the event. This event can only be used in development environments that support events being generated on threads other than the client thread (such as Visual C++). In these environments, it is usually more efficient to generate events from a non-client thread.
PAGE 543
Element Description UpdateType This element always returns the value 0. The possible values for this parameter, which are contained in the ConstMonitorEventType constant, are as follows: 0 lcaMonitorEventTypeNull This value is not used. 1 lcaMonitorEventTypeQuit This value is not used. 2 lcaMonitorEventTypeAdd This value is not used. 3 lcaMonitorEventTypeRemove This value is not used. 4 lcaMonitorEventTypeMsCreate This value is not used. 5 lcaMonitorEventTypeMsDelete This value is not used.
PAGE 544
13 lcaMonitorEventTypeNvComplete A completion code has returned for the monitor point. 14 lcaMonitorEventTypeMsgCreate A message monitor point has been created. 15 lcaMonitorEventTypeMsgDelete A message monitor point has been removed. 16 lcaMonitorEventTypeMsgChange This value is not used. 17 lcaMonitorEventTypeMsgError A message monitor point has returned an error. See the OnMsgMonitorPointErrorEvent. 18 lcaMonitorEventTypeMsgUpdate A message monitor point has received an update.
PAGE 545
Added to API LNS Release 3.0. MsgMonitorPoints The MsgMonitorPoints object contains a collection of MsgMonitorPoint objects. This collection object contains all of the MsgMonitorPoint objects that have been added to a monitor set. Message monitor point objects represent message tags that may be used to monitor application LONWORKS messages from the device. For more information on monitor points, see the Monitor and Control chapter in the OpenLNS Programmer’s Guide.
PAGE 546
able to use the MsgMonitorPoint to send messages to all the devices that the MessageTag object is bound to at once. You will not be able to use the MsgMonitorPoint to receive messages from those devices. The dynamic MessageTag object must exist on the Network Service Device containing the monitor set you are adding the message point to. When you are adding MsgMonitorPoint objects to temporary monitor sets, you can only specify an AppDevice object as the targetDevice element.
PAGE 547
are not available on Independent clients. Syntax msgMpObject = msgMpColl.Add msgMpName targetDevice connDesc Element Description msgMpObject The newly defined MsgMonitorPoint object. msgMpColl The MsgMonitorPoints collection object. msgMpName The Name of the new MsgMonitorPoint object. targetDevice The AppDevice or dynamic MessageTag object that the MsgMonitorPoint will monitor. connDesc A ConnectDescTemplate object which determines how messages will be sent out through this monitor point.
PAGE 548
indexName Added to API A Long value specifying the collection index of the MsgMonitorPoint object to remove, or a String value specifying the name of the MsgMonitorPoint object to remove. Prior to LNS Release 3.0. Properties The MsgMonitorPoints object contains the following properties: • • • • • ClassId Count Item Parent _NewEnum ClassId Summary Identifies the object class of this object.
PAGE 549
Syntax returnValue = object.Count Element Description returnValue The number of objects in the collection as a long integer. object The collection object to be acted on. Data Type Long. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. Item Summary Returns a MsgMonitorPoint object from a MsgMonitorPoints collection.
PAGE 550
Parent Summary Returns the object that spawned the current child object. The parent object is determined by the means in which a child object is accessed, not by the OpenLNS Object hierarchy. Availability Local, full, lightweight, and independent clients. Note that some collection objects are not available to Independent clients. Syntax parentObject = object.Parent Element Description parentObject The object that is the parent of the specified object.
PAGE 551
Data Type Object. Read/Write Read only. Added to API OpenLNS. Network The Network object represents a single LONWORKS network. A network is a set of devices that interoperate via network variable and message tag connections. Network objects may be used to represent physically separate networks, or they may be used to represent multiple projects on the same physical network. The following table summarizes the Network object. Description A single LONWORKS network. Added to API Prior to LNS Release 3.
PAGE 552
• • ServerIdentifier System Methods The Network object contains the following methods. • • • • • • • • • • • Backup CancelValidation Close CloseIndependent CompactDb CreateTemporaryMonitorSet Open OpenIndependent PreReplace Replace Validate Backup Summary Make a backup copy of the network database, and exports it to a specified directory. The System object must be open when you invoke this method. If the System object is not open, the LCA #67 lcaErrSystemNotOpen exception will be thrown.
PAGE 553
network The Network object to be acted upon. systemPath The directory to which the backup is to be copied. The systemPath element must contain a valid system path. If the destination directory specified by this path does not exist, that directory will be created, as long as the first parent directory in the path exists. The directory permissions for this new folder will be the default permissions for the operating system on the computer you are using.
PAGE 554
Syntax Added to API network.CancelValidation Element Description network The Network object to be acted upon. LNS Release 3.20. Close Summary Closes the OpenLNS network database and terminates monitor set monitoring. You should close the network’s System object before invoking this method. Availability Local, full, and lightweight clients. Syntax network.Close Added to API Element Description network The Network object to be closed. Prior to LNS Release 3.0.
PAGE 555
Syntax Added to API network.CompactDb Element Description network The Network object to be acted on. Prior to LNS Release 3.0. CreateTemporaryMonitorSet Summary Creates a temporary MonitorSet object. If you need monitor points that will only be used in a single client session, you should use temporary MonitorSet objects. Temporary monitor sets are opened automatically by OpenLNS as they are created, and can only be accessed from the client that created them.
PAGE 556
collection. If this method is being invoked by a remote client, the application program must set the remote NetworkInterface for the ObjectServer (ObjectServer.ActiveRemoteNI) before invoking this method. Additionally, the OpenLNS Server must be running on the computer containing the OpenLNS Network Database. A network obtained from the VNINetworks collection cannot be opened with this method. It must instead be opened using the OpenIndependent method.
PAGE 557
computer without the OpenLNS Server running on the host. You may not access the network database. The same network should not be simultaneously opened in server-dependent and server-independent mode (with this method as well as the Open method). Doing this may cause unpredictable results. See the ObjectServer object's Open method for information on how to initialize the Object Server. Availability Independent clients. Syntax network.
PAGE 558
if you install a new network interface on the computer). In all other scenarios (e.g. when operating as a Local client and upgrading the computer or network interface card, or when moving a layer 5 network interface card from one computer to another) you will not need to perform this procedure. To re-associate a remote Full client with the correct network service device and re-attach the client to the network, follow these steps: 1.
PAGE 559
to use the NSD information which was previously associated with a remote client running on another computer (effectively moving the remote application and NSD configuration from one computer to another). An exception to this is if the original remote client used a layer 5 network interface, and you move the network interface to the new computer as well. In this case, OpenLNS will automatically associate the NSD in the database with the client based on the layer 5 network interface’s neuron ID.
PAGE 560
it is not open, the LCA, #67 lcaErrSystemNotOpen exception will be thrown. You should consider using the Validate method to repair your network database a last resort. You should backup the database with the Backup method before performing a validation with repairs. For more information on this procedure, see the Backup method. It is safer for the client application to remove invalid objects from the database (delete and recreate a device) than for the database validation method to attempt to do so.
PAGE 561
validation without attempting to repair any of the errors it discovers. In this case, the Validate method returns a DatabaseValidationReport object summarizing the results of the database validation. 1 lcaDbValidateAndRepair OpenLNS performs repairs on the errors and inconsistencies it discovers during the database validation.
PAGE 562
• • • • • • • • • • • • • • • • • • • • Channels ClassId CurrentMonitorSets DatabasePath Description EventInterval Extensions Handle IconFilePath IsOpen IsOpenIndependent MyVNI Name NetworkServiceDevices NsiTimeout OriginalName Parent RemoteNetworkName ServerIdentifier Systems AllowPropagateModeDuringRemote Summary Determines whether OpenLNS should change the network management mode to lcaMgmtModePropagateConfigUpdates (0) if it is necessary to open this network.
PAGE 563
order to successfully open this remote network. TRUE. OpenLNS changes the network management mode when necessary. Set this property to True if it is acceptable for OpenLNS to temporarily change the network management mode from lcaMgmtModeDeferConfigUpdates (1) to lcaMgmtModePropagateConfigUpdate s (0) when opening a network from such a client application in these situations. When the network management mode is changed, all pending configuration updates will applied to the physical devices on the network.
PAGE 564
C:\MyBMPs\Object.BMP). Added to API Prior to LNS Release 3.0. Channels Summary Contains the Channels collection object associated with the specified Network object. Availability Local, full, and lightweight clients. Syntax channelsColl = networkObject.Channels Element Description channelsColl The Channels collection object to be returned. networkObject The Network object. Data Type Channels collection object. Read/Write Read only Added to API Prior to LNS Release 3.0.
PAGE 565
commissioned into your client’s NSD for a given network. The CurrentMonitorSets property returns a MonitorSets object that contains all the MonitorSet objects on that network that are currently stored in your client’s NSD. This may be useful if you have created monitor sets while the network management mode is set to lcaMgmtModeDeferConfigUpdates (1). Although those monitor sets exist in the OpenLNS database and can also be accessed through the MyVNI property, they will not be commissioned into the NSD.
PAGE 566
Syntax dbPath = object.DatabasePath Element Description dbPath The full path of the global OpenLNS database. object The Network object. Data Type String. Read/Write Read only. Added to API Prior to LNS Release 3.0. Description Summary Stores description information about the Network object. Availability Local, full, lightweight, and independent clients. Note that some collections are not available to Independent clients. Syntax stringValue = object.
PAGE 567
EventInterval property expires, OpenLNS will not call the GetNextEvent service right away. Instead, it will wait until the next event (or set of events) occurs, deliver that event to the client, and then immediately call GetNextEvent (because the interval has already expired). Following that, OpenLNS will call the GetNextEvent service at the interval defined by this property. Note that as you set this property to lower and lower values, more and more request-response messages will be sent to the server.
PAGE 568
Element Description extensionsColl The Extensions collection object. object The object whose Extensions collection is being returned. Data Type Extensions collection object. Read/Write Read only. Added to API Prior to LNS Release 3.0. Handle Summary Contains the handle associated with the Network object. An OpenLNS Object that is part of a collection is assigned an index corresponding to its position within that collection. This index may be used when invoking the Item property.
PAGE 569
• Added to API Large (48x48) with 256 colors Prior to LNS Release 3.0. IsOpen Summary Indicates whether the specified Network object is currently open. You can open the Network object with the Open method, and you can close it with the Close method. Availability Local, full, lightweight, and independent clients. Note that temporary MonitorSet objects are not available on Independent clients. Syntax isOpenFlag = Object.IsOpe Element Description isOpenFlag Boolean value.
PAGE 570
Read/Write Read only. Added to API LNS Release 3.0. MyVNI Summary Contains the AppDevice object which is used to create MonitorSets on this network. This AppDevice object is the only one that supports the MonitorSets property. You should access your monitor sets through this property when you plan to create new monitor sets, or when you plan to modify the configuration of an existing monitor set. For actual monitor and control operations, you should use the CurrentMonitorSets property.
PAGE 571
they are added to the API. NetworkServiceDevices Summary Contains the NetworkServiceDevices collection object associated with the specified Network object. This is the collection of all NetworkServiceDevice objects (the NSS and all NSIs) on the network. Availability Local, full, lightweight, and independent clients. Syntax nsdColl = networkObject.NetworkServiceDevices Element Description adObject The AppDevice returned by the property.
PAGE 572
OriginalName Summary Contains the network's original name as defined on the OpenLNS Server. The property may only be accessed after the remote client has connected to the OpenLNS Server using the system's Open method. Availability Local, full, and lightweight clients. Syntax networkName = networkObject.OriginalName Element Description networkName The returned network name. networkObject The Network to be acted on. Data Type String. Read/Write Read/write.
PAGE 573
RemoteNetworkName Summary Allows the name of the network as seen in the RemoteNetworks and VNINetworks to be changed. When a Full client network is opened for the first time on a computer, an entry is made in the RemoteNetworks and VNINetworks collections which identifies the network as r_ (i.e. if the network name is HVAC, the name in the RemoteNetworks and VNINetworks collections will be r_HVAC).
PAGE 574
ServerIdentifier Summary Provides an identification string for the OpenLNS Server that has opened this network, which enables networks with the same name on different servers to be differentiated. When the ObjectServer object's RemoteFlag property is set to True before the ObjectServer is opened, the Networks collection will contain all of the remote full or lightweight client networks (see the Flags property) which have been opened by an OpenLNS Server application.
PAGE 575
Systems Summary Returns the Systems collection containing the System object. Only one System is allowed for each network (the Systems collection will always contain only one object). Availability Local, full, and lightweight clients. Syntax systemsCollection = networkObject.Systems Element Description systemsCollection Returned collection of System objects. networkObject Network object to be acted upon. Data Type Systems collection object. Read/Write Read only. Added to API LNS Release 3.0.
PAGE 576
Add Summary Defines a new Network object. You can create a new network, or import an existing network. Availability Local, full, and lightweight clients. Syntax networkObject = networksColl.Add(networkName, databasePath, createDatabase) Element Description networkObject The newly defined Network object. networksColl The Networks collection object. networkName A String representing the name of the new network.
PAGE 577
can be no more than 230 characters long, including any characters OpenLNS adds to create an absolute path. Otherwise the LCA, #23 lcaErrDatabasePathTooLong exception will be thrown. createDatabase A Boolean value indicating whether a new Network and a new OpenLNS database are to be created, or a new network is to be created based on an existing OpenLNS database. TRUE. Creates a new Network and a new OpenLNS network database. FALSE.
PAGE 578
identify the network to be deleted by its name, which is stored in the Name property of the Network object, or by its index number within the Networks collection. databaseOption Determines whether the network database is preserved or deleted.
PAGE 579
• • • • Count Item Parent _NewEnum ClassId Summary Identifies the object class of this object. This property allows the object type to be determined when it is unknown (for example, when the object was accessed using the Parent property of another object). Availability Local, full, lightweight, and independent clients. Note that some objects containing this property are not available to Independent clients. Syntax classIdValue = object.
PAGE 580
added to the API. Item Summary Returns a Network object from a Networks collection. You can retrieve a Network object from its Networks collection by passing its index (ordinal position) within that Networks collection as the argument for the Item property. Index values start at 1. You can also retrieve a Network object in Networks collections with the Name property by passing the object’s name as a string expression. Availability Local, full, lightweight, and independent clients.
PAGE 581
object Any object for which the parent is desired. Data Type Object. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. _NewEnum Summary Enables you to iterate over the objects in a collection using For Each ... Next statements. • If you are developing your OpenLNS app in Visual C++, you can browse a collection to find a particular item by using the _NewEnum property.
PAGE 582
Added to API Prior to LNS Release 3.0. Accessed Through NetworkInterfaces collection object. NetworkServiceDevice object. Default Property Name. Methods None. Properties • • • ClassId Name Parent Methods The NetworkInterface object does not contain any methods. Properties The NetworkInterface object contains the following properties: • • • ClassId Name Parent ClassId Summary Identifies the object class of this object.
PAGE 583
Name Summary Specifies the name of an object as a character string. This property is case sensitive. Searches by name must match case. This property can be a maximum of 85 characters long, but it may not contain the forward slash (/), back slash (\), period (.), and colon (:) characters. Availability Local, full, lightweight, and independent clients. Note that some objects that contain this property are not available to Independent clients. Syntax stringValue = object.
PAGE 584
NetworkInterfaces A NetworkInterfaces object represents a collection of NetworkInterface objects. This collection contains all of the network interfaces on the local computer that are available to the Object Server. This collection is constructed from entries in the Windows registry. Use the Item property to access a NetworkInterface object from this collection.
PAGE 585
• • • Count Item _NewEnum ClassId Summary Identifies the object class of this object. This property allows the object type to be determined when it is unknown (for example, when the object was accessed using the Parent property of another object). Availability Local, full, lightweight, and independent clients. Note that some objects containing this property are not available to Independent clients. Syntax classIdValue = object.
PAGE 586
Item Summary Returns a NetworkInterface object from a NetworkInterfaces collection. You can retrieve a NetworkInterface object from its NetworkInterfaces collection by passing its index (ordinal position) within that collection as the argument for the Item property. Index values start at 1. You can also retrieve a NetworkInterface object in NetworkInterfaces collections with the Name property by passing the object’s name as a string expression.
PAGE 587
foreach statements. Availability Local, full, and lightweight clients. Syntax retrievedObject = collObject._NewEnum Element Description retrievedObject An expression that evaluates to the object retrieved. collObject An iterator object that can be used to access members of the collection. Data Type Object. Read/Write Read only. Added to API OpenLNS. NetworkResources A NetworkResources contains information related to the network resources allocated on the system.
PAGE 588
Properties The NetworkResources object contains the following properties: • • • • • • • • • AppDeviceCount ClassId ExclusiveSelectorPoolSize ExclusiveSelectorsAvailable GroupIdsAllocated Parent RouterCount SharableSelectorPoolSize SubnetsAllocated AppDeviceCount Summary Indicates the number of AppDevice objects that have been installed on the system. This includes all devices that are installed in the OpenLNS database, and managed by OpenLNS. This does not include AppDevices contained in the Discovered.
PAGE 589
classIdValue The object class of the object. The following value is defined for the NetworkResources object in the ConstClassIds constant: 93 object lcaClassIdNetworkResources The object to be acted on. Data Type Integer. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API.
PAGE 590
Added to API LNS Release 3.20. ExclusiveSelectorsAvailable Summary Indicates the total number of exclusive selectors that are currently available in the system. A network variable selector is a 14-bit number used to identify connected network variables. Each connection in the system is assigned a selector value, and all network variables in a given connection must use the same selector. Intersecting connections must also use the same network variable selector.
PAGE 591
GroupIdsAllocated Summary Indicates the number of LonTalk group IDs that have been allocated on the system. Each set of connections in the system that use multicast addressing must have a unique group ID. As a result, the number of group IDs that have been allocated is critical to networks with large numbers of connections and devices.
PAGE 592
object Any object for which the parent is desired. Data Type Object. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. RouterCount Summary Indicates the number of Router objects that have been installed on the system. This includes all routers that are installed in the OpenLNS database, and managed by OpenLNS. This does not include Routers contained in the Discovered.
PAGE 593
count The number of selectors that can be used by more than one connection in the system. networkResources The NetworkResources object being acted upon. Data Type Long. Read/Write Read only. Added to API LNS Release 3.20. SubnetsAllocated Summary Indicates the number of subnets that have been allocated on the system. Subnets are the second component of the three-component LonTalk domain/subnet/device addressing hierarchy used by devices on LONWORKS networks.
PAGE 594
Added to API Prior to LNS Release 3.0. Accessed Through AppDevice object. NetworkServiceDevices object. System object. Default Property Name.
PAGE 595
EndResetEvent Summary Disables the OnNetworkServiceDeviceResetNew event. Availability Local, full, and lightweight clients. Syntax nsdObject.EndResetEvent Added to API Element Description nsdObject The NetworkServiceDevice object. Prior to LNS Release 3.0.
PAGE 596
Element Description appDevObject The AppDevice object to be returned. nsdObject The NetworkServiceDevice object to be acted on. Data Type AppDevice object. Read/Write Read only. Added to API Prior to LNS Release 3.0. BitmapFilePath Summary Specify the path and file name of a bitmap (*.BMP file) representation of the object. The bitmap files are used to store object images which may be accessed by a director level LNS component application.
PAGE 597
ConstClassIds constant: 40 object lcaClassIdNetworkServiceDevice The object to be acted on. Data Type Integer. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. DefaultApplication Summary Contains the default application information for this NetworkServiceDevice object.
PAGE 598
soon as they are added to the API. See the applicable object to determine what release it was introduced in. Dialup Summary Specifies whether the NetworkServiceDevice is communicating through a modem. This property allows applications to be designed such that they can check to see if communication with a device is taking place over a modem before making permanent connections or other communications decisions. Availability Local, full, and lightweight clients. Syntax dialupValue = nsdObject.
PAGE 599
Added to API Prior to LNS Release 3.0. IconFilePath Summary Specifies the path and file name of an icon (*.ICO file) representation of the object. Availability Local clients. Syntax IconFilePathFileName = object.IconFilePath Element Description IconFilePathFileName Icon file and path name object The object to be acted on. Data Type String. Read/Write Read/write. If you write to this property, you must specify the bitmap’s full path and file name (for example, C:\MyICOs\Object.ICO).
PAGE 600
LcaNsdType Summary Specifies the type of network service device, which determines whether its NSI is removed when the NSI client closes. Availability Local, full, and lightweight clients. Syntax interfaceColl = object.Interfaces Element Description nsdType A Long value indicating the NSD type.
PAGE 601
not using an OpenLNS high-performace network interface. nsdObject Data Type Boolean. Read/Write Read only. Added to API LNS Release 3.0. The NetworkServiceDevice object from which to get the information. Name Summary Specifies the name of an object as a character string. This property is case sensitive. Searches by name must match case. This property can be a maximum of 85 characters long, but it may not contain the forward slash (/), back slash (\), period (.),colon (:) characters.
PAGE 602
Read/Write Read/write. Added to API Prior to LNS Release 3.0. NetworkInterfaceFlag Summary Specifies whether the NetworkInterface has been set. Availability Local, full, and lightweight clients. Syntax netInterfaceFlag = nsdObject.NetworkInterfaceFlag Element Description netInterfaceFlag A Boolean value. TRUE. The NetworkInterface property in the specified NetworkServiceDevice has been set to a valid interface object. FALSE. The NetworkInterface property is not valid and should not be used.
PAGE 603
Added to API Prior to LNS Release 3.0. NsiHandle Summary Returns the unique identifier assigned to an NSI by the OpenLNS Server. This handle is different than the NodeHandle and Handle properties. Availability Local, full, and lightweight clients. Syntax handleValue = nsdObject.NsiHandle Element Description handleValue The NSI’s handle. nsdObject The NetworkServiceDevice to be acted on Data Type Long. Read/Write Read only. Added to API Prior to LNS Release 3.0.
PAGE 604
NsiSubnetId Summary Contains the subnet ID associated with the network services interface (NSI). The NsiNodeId and NsiSubnetId comprise the logical network subnet/node address the NSD will use to send subnet node and group addressed messages, if the NSD is using a high-performance network interface. This address is assigned to the network services interface when the Open ethod is invoked on the System object. The System object must be open for these properties to contain a valid value.
PAGE 605
Parent Summary Returns the object that spawned the current child object. The parent object is determined by the means in which a child object is accessed, not by the OpenLNS Object hierarchy. Availability Local, full, lightweight, and independent clients. Note that some collection objects are not available to Independent clients. Syntax parentObject = object.Parent Element Description parentObject The object that is the parent of the specified object.
PAGE 606
Class for nodes which move frequently. 2 lcaPingClassTemporary Class for temporary nodes. 3 lcaPingClassStationary Class for nodes which rarely move. This is the default value. 4 lcaPingClassPermanent Class for nodes which never move. Note: You change the ping interval that applies to each class with the System object's PingIntervals property. Data Type Integer. Read/Write Read/write. Added to API Prior to LNS Release 3.0.
PAGE 607
Remove Summary Removes an object from the specified collection. Availability Local, full, lightweight, and independent clients. Note that some collections are not available to Independent clients. Syntax objectColl.Remove indexName Added to API Element Description objectColl The collection containing the object to be removed. name A Long value specifying the collection index of the object to remove, or a String value specifying the name of the object to remove. Prior to LNS Release 3.0.
PAGE 608
added to the API. Count Summary Returns the number of objects in a collection. You can use this property to enumerate a collection object. Availability Local, full, lightweight, and independent clients. Note that some collection objects are not available to Independent clients. Syntax returnValue = object.Count Element Description returnValue The number of objects in the collection as a long integer. object The collection object to be acted on. Data Type Long. Read/Write Read only.
PAGE 609
stringExpression A string type specifying the name of the NetworkServiceDevice object to be retrieved. Data Type Object. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. Parent Summary Returns the object that spawned the current child object. The parent object is determined by the means in which a child object is accessed, not by the OpenLNS Object hierarchy.
PAGE 610
Availability Local, full, and lightweight clients. Syntax retrievedObject = collObject._NewEnum Element Description retrievedObject An expression that evaluates to the object retrieved. collObject An iterator object that can be used to access members of the collection. Data Type Object. Read/Write Read only. Added to API OpenLNS. NetworkVariable A NetworkVariable object represents a single instance of a network variable.
PAGE 611
• • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • AuthenticationFlag ChangeableTypeSupport ClassId ConfigClassFlag ConfigProperties ConnectDescTemplate Description Direction DsFormatType DsIsDefaultFormat DsPollInterval DsPriority EstimatedMaxRate EstimatedRate Extensions FuncProfileDescription FuncProfileName FuncProfileProgrammaticName ImplementsCp Index IsConfigProperty IsDynamic IsPolled Length LmNumberManufacturerAssigned LonMarkMemberIndex LonMarkMemberNumber
PAGE 612
• • • • • • Disconnect DsRestoreOptions DsSaveOption GetDataPoint MoveToInterface ToString AddTarget Summary Adds a single NetworkVariable to a hub's pending target list. This method defines a hub network variable's pending target list. This list is used when the Connect or Disconnect method is invoked to create or remove a network variable connection. Connections, as defined within OpenLNS, always consist of a single hub and one or more complementary targets.
PAGE 613
variable connections on a LonWorks network (subject to the constraints of the LonTalk protocol). This is accomplished by calling the AddTarget and Connect method with multiple hubs and overlapping targets. A consequence of the superposition of connections is that a network variable may find itself in a "mirrored" connection. This situation occurs when a network variable A is the hub of a connection containing target network variable B., and B is the hub of a connection containing A.
PAGE 614
connections are created or modified with this method. Availability Local, full, and lightweight clients. Syntax nvObject.Connect Added to API Element Description nvObject The hub NetworkVariable object to be connected. Prior to LNS Release 3.0. Disconnect Summary Removes a hub or network variable's entire connection or disconnects the network variables contained in the hub's pending target list.
PAGE 615
options. Availability Local, full, and lightweight clients. Syntax object.DsRestoreOptions Added to API Element Description object The NetworkVariable object to be acted on. Prior to LNS Release 3.0. DsSaveOptions Summary Saves the current set of data server options to the persistent database. Data server options are not persistent for NetworkVariable objects. For new option values to persist across data object instantiations, you must invoke the DsSaveOptions method.
PAGE 616
Syntax Added to API dpObject=networkVariable.DataPoint options Element Description dpObject The DataPoint object returned. networkVariable The NetworkVariable object being acted upon. options This field is fixed at 0, and it is reserved for future use. LNS Release 3.20. MoveToInterface Summary Moves a dynamic network variable from one custom interface on a device to another.
PAGE 617
variable, then the LCA, #119 lcaErrInterfaceNotModifyable exception will be thrown. You can determine if a LonMarkObject or network variable is dynamic by reading the object’s IsDynamic property.
PAGE 618
• • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • AppDeviceName AuthenticationConfigFlag AuthenticationFlag ChangeableTypeSupport ClassId ConfigClassFlag ConfigProperties ConnectDescTemplate Description Direction DsFormatType DsIsDefaultFormat DsPollInterval DsPriority EstimatedMaxRate EstimatedRate Extensions FuncProfileDescription FuncProfileName FuncProfileProgrammaticName ImplementsCp Index IsConfigProperty IsDynamic IsPolled Length LmNumberManufacturerAssi
PAGE 619
Aliases Summary Contains the Aliases collection object associated with the specified NetworkVariable object. The Aliases collection contains a collection of Alias objects, each one representing an alias used by the network variable. If the network variable is not using any aliases, the collection will be empty.
PAGE 620
AppDeviceName Summary Returns the name of an application device that contains the network variable. Availability Local, full, and lightweight clients. Syntax nvMtName = nvMtObject.AppDeviceName Element Description nvMtObject The NetworkVariable object to be acted upon. nvMtName The name of the network variable. Data Type String Read/Write Read only. Added to API Prior to LNS Release 3.0.
PAGE 621
AuthenticationFlag Summary Returns the network variable’s default authentication setting, which is specified by the device developer. If this property is set to True, the network variable uses authentication by default. You can override the default setting by writing to the UseAuthenticationFlag of the ConnectDescTemplate object used by the connections involving the network variable.
PAGE 622
constant, are as follows: 0 lcaNvChangeableTypeNone The network variable’s type cannot be changed. 1 lcaNvChangeableTypeSdOnly You can change the network variable’s type by writing to its TypeSpec or SnvtId property. When you write to this property, OpenLNS will change the type by modifying the self-documentation information of the device associated with the network variable. This is the value that will be returned by all dynamic network variables.
PAGE 623
cleared, • networkVariable Data Type Long. Read/Write Read only. Added to API LNS Release 3.20. The configuration property has been set to an invalid value explicitly by your application, or when your application downloaded or uploaded the default configuration property values with the DownloadConfigProperties or UploadConfigProperties methods. The NetworkVariable object to be acted upon. ClassId Summary Identifies the object class of this object.
PAGE 624
ConfigClassFlag Summary Indicates whether the network variable is a configuration network variable (CPNV). A CPNV is used for application configuration. This should not be confused with a configuration property that is implemented as a network variable, and the related IsConfigProperty property. Network variables that implement configuration properties are always CPNVs, and the ConfigClassFlag and IsConfigProperty properties for these network variables are set to True.
PAGE 625
ConfigProperties Summary Contains the ConfigProperties collection object associated with the specified NetworkVariable object. Availability Local, full, and lightweight clients. Syntax configPropsCollection = NetworkVariable.ConfigProperties Element Description configPropsCollection The returned ConfigProperties collection. NetworkVariable The NetworkVariable object to be acted on Data Type ConfigProperties collection object. Read/Write Read only. Added to API Prior to LNS Release 3.0.
PAGE 626
Added to API Prior to LNS Release 3.0. Description Summary Stores description information about the NetworkVariable object. Availability Local, full, lightweight, and independent clients. Note that some collections are not available to Independent clients. Syntax stringValue = object.Description Element Description stringValue A string description of the NetworkVariable object . object The NetworkVariable object to be acted on. Data Type String. Read/Write Read/write.
PAGE 627
DsFormatType Summary Specifies the type the OpenLNS Server will use in interpreting the value of the network variable. Availability Local, full, and lightweight clients. Syntax formatType = nvObject.DsFormatType Element Description formatType The type the OpenLNS Server will use in interpreting the value of the network variable. The DsFormatType parameter is a string defining the type that will be used to interpret the value of the network variable.
PAGE 628
OpenLNS uses the value of the Measurement System field (either U.S. or metric) on this tab to determine the default format to use for types such as SNVT_temp_f. You can also specify a full format name (i.e. SNVT_temp_f#SI for or SNVT_temp_f#US) to select a specific format for that type. For UNVTs, you must always specify a fully-qualified format name. 2. In some cases, a format exists for a given SNVT or UNVT that has the same name as the underlying type.
PAGE 629
of the program ID, and may be one of the following: 0 - Standard 1 - Device Class 2 - Device Class and Usage 3 - Manufacturer 4 - Manufacturer and Device Class 5 - Manufacturer, Device Class, and Device Subclass 6 - Manufacturer, Device Class, Device Subclass, and Device Model For example: #800001128000000[4].UNVT_date_event 4. The name of one of the built-in types used by the OpenLNS Server, which include "INT", "REAL", "DISCRETE", "BINARY", "RAW" and "RAW_HEX".
PAGE 630
correct path to the LonMark Device Resource File catalog. After you write to this property, you need to invoke the DsSaveOptions method to save the new value into the OpenLNS database. You can revert this property to the network variable's default type by writing an empty string to this property. You can check if the network variable is currently using its default type by reading the DsIsDefaultFormat property.
PAGE 631
was used for pre-LonMark resource files. nvObject The NetworkVariable object to be acted on. Data Type String. Read/Write Read/write. Added to API Prior to LNS Release 3.0. DsIsDefaultFormat Summary Indicates whether the network variable is using its default format. OpenLNS determines the default format to use for SNVT network variables by reading the SNVT ID of the network variable, and using it to locate the applicable entry for that SNVT type in the standard resource files.
PAGE 632
variable’s type, or it is set to the default format for the network variable given the locale settings currently in effect. FALSE. The DsFormatType property is not the same as the network variable’s type. For example, if the current locale settings are set to use US measurement units, then for a network variable of type SNVT_temp_f, the DsIsDefaultFormat property will return True if the DsFormatType property is set to SNVT_temp_f or SNVT_temp_f#US. nvObject The NetworkVariable object to be acted on.
PAGE 633
object’s DsPollInterval property. An exception will be raised if you attempt to do so. The System object's DsPollInterval property sets the default value which is applied when a NetworkVariable object's DsPollInterval property is left unspecified. Once an application has explicitly set the value of the DsPollInterval property of the System object, it will not be reverted back to the default value by OpenLNS, and must be maintained manually from that point on.
PAGE 634
DsPriority Summary Specifies whether the Data Server polls or updates a network variable using priority messages. Note: This property is deprecated because it was only useful with single-point monitoring. You should use temporary monitor sets instead of single-point monitoring. When doing so, you can use the Priority property to determine the priority assigned to each message. For more information on temporary monitor sets, see the OpenLNS Programmer’s Guide.
PAGE 635
EstimatedRate Summary The estimated sustained message rate (in tenths of messages per second) declared for the network variable. Availability Local, full, and lightweight clients. Syntax estimatedRateValue = nvObject.EstimatedRate Element Description estimatedRateValue Estimated sustained message rate. The valid values for this property are integers from 0 to 18780 (0 to 1878.0 messages per second). nvObject The NetworkVariable object to be acted on. Data Type Integer. Read/Write Read only.
PAGE 636
object The NetworkVariable object to be acted on. description The returned functional profile description string. Data Type String. Read/Write Read-only. Added to API Prior to LNS Release 3.0. FuncProfileName Summary Returns the functional profile name associated with the NetworkVariable object. This property is accessed from the functional profile template file associated with the object.
PAGE 637
on. Data Type String. Read/Write Read-only. Added to API Prior to LNS Release 3.0. ImplementsCp Summary If the network variable is a configuration network variable, returns the configuration property object (possibly a shared instance) implemented by this network variable. If this network variable is not a configuration network variable, then accessing this property throws an LCA, #166 error (“network variable does not implement a configuration property”).
PAGE 638
Syntax index = object.Index Element Description object The object to be acted on. index Index of the network variable. The valid values for this element are 0–14. Data Type Integer. Read/Write Read only. Added to API Prior to LNS Release 3.0. IsConfigProperty Summary Indicates whether the network variable implements a configuration property that conforms to the LonMark interoperability guidelines.
PAGE 639
implements a configuration property conforming to LonMark interoperability guidelines. FALSE. The network variable does not implement a configuration property. nvObject The NetworkVariable object to be acted on Data Type Boolean. Read/Write Read only. Added to API Prior to LNS Release 3.0. IsDynamic Summary Indicates whether the network variable is dynamic.
PAGE 640
nvObject Data Type Boolean. Read/Write Read only. Added to API LNS Release 3.0. 1 The network variable’s poll attribute on. If the Direction property is set to lcaNvDirectionOutput, this network variable will not send network variable update messages automatically; otherwise, this network variable may poll other network variables. 0 The network variable’s poll attribute off.
PAGE 641
LmNumberManufacturerAssigned Summary Indicates whether the member number within a LonMark object was assigned by the device manufacturer instead of being specified in the LonMark Application Layer Interoperability Guidelines or in a LonMark approved functional profile. Availability Local, full, and lightweight clients. Syntax lmNumberFlag = nvObject.LmNumberManufacturerAssigned Element Description lmNumberFlag A Boolean value indicating whether the member number is manufacturer assigned. TRUE.
PAGE 642
Syntax indexValue = nvObject.LonMarkMemberIndex Element Description indexValue The index value of the network variable as a long. On static interfaces, indexes are numbered from 0 to n-1, where n equals the number of network variables in the object. If dynamic network variables have been assigned and subsequently removed from a LonMarkObject, the member indexes may not be contigious, and some member indexes may be equal to or greater than the number of network variables in the object.
PAGE 643
Syntax memNumValue = nvObject.LonMarkMemberNumber Element Description memNumValue The member number of the network variable as a Long. nvObject The NetworkVariable object to be acted on. Data Type Long. Read/Write Read only. Added to API Prior to LNS Release 3.0. LonMarkObjectNumber Summary Contains the object number of the LonMarkObject to which this network variable is assigned. Objects on a device are generally numbered from 0 to n-1, where n is the number of objects on the device.
PAGE 644
support changeable types, then the value of the MaxLength property will always match the value of the Length property. You can determine if a network variable supports changeable types by reading the network variable’s ChangeableTypeSupport property. If the device supports changeable types, and the configuration properties are avaliable, then this property will be set to the maximum network variable length as defined by SCPTmaxNvLength configuration property reported by the device for that network variable.
PAGE 645
Element Description stringValue The name of the object. object The object to be acted on. Data Type String. Read/Write Read/write. Added to API Depends on the object used to access the property. Generally, this property exists for the objects listed above as soon as they are added to the API. NvHubs Summary Returns a collection containing all network variable hubs for which the network variable is a target, including the network variable if it is the hub for a connection.
PAGE 646
nvObject The specified NetworkVariable object. Data Type NetworkVariables collection object. Read/Write Read/write. Added to API Prior to LNS Release 3.0. OfflineFlag Summary Indicates whether the network variable should be updated only while the device’s State is set to lcaStateSoftOffline. Availability Local, full, and lightweight clients. Syntax offlineFlagValue = nvObject.
PAGE 647
desired. Data Type Object. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. ParentInterface Summary Returns the Interface object to which the NetworkVariable Object belongs.
PAGE 648
ConnectDescTemplate object. Availability Local, full, and lightweight clients. Syntax priorityValue = object.Priority Element Description priorityValue The default priority setting assigned to the network variable. object The AppDevice object to be acted on. Data Type Integer. Read/Write Read only Added to API Prior to LNS Release 3.0. PriorityConfigFlag Summary Indicates whether priority is configurable for the network variable. Availability Local, full, and lightweight clients.
PAGE 649
ProgrammaticName Summary Returns the programmatic name of the network variable. This property contains the orignal base name of the network variable as "programmed" in the device containing the object. • For static network variables, OpenLNS initially acquires the name from the functional profile template file or external interface associated with the device. • For dynamic network variables, you will specify the name to use when you create the object with the appropriate Add method.
PAGE 650
Selector Summary The network variable selector value assigned to this network variable alias. When a device is installed, selector values that represent unbound network variables are assigned to the network variables in that device. When placing the network variable in a connection, the OpenLNS Object Server assigns a value representing that connection. Availability Local, full, lightweight, and independent clients. Note that some objects containing this property are not available to Independent clients.
PAGE 651
ServiceType Summary Stores the messaging service to be used for the connection. Note: This property will only be read by the OpenLNS Object Server if the lcaConnPropsServiceType option is set in the ConnectDescTemplate object’s PropertyOptions property. If the lcaConnPropServiceType option is not set, then OpenLNS Object Server will determine the service type for connections using the ConnectDescTemplate object by reading the ServiceType property of the connection’s hub network variable.
PAGE 652
acknowledgment messages. Do not use this service type on channels that support altnerate frequencies because the message will only be sent using the primary path. See the AltPathType property for more information. 3 lcaSvcRequest Request/Response messaging service. You can use this value when sending explicit messages if the device receiving the message is designed to send a response message for the specified message code. object The NetworkVariable object to be acted on. Data Type Integer.
PAGE 653
SnvtId Summary Contains the ID of the standard network variable type (SNVT) used by the network variable. If the network variable is using a user-defined type (UNVT), this property returns the value 0. For more information on SNVTs and their IDs, go to the LONMARK Web site at www.lonmark.org. If the device supports modifiable types, this property may be modified.
PAGE 654
device associated with the network variable). Availability Local, full, and lightweight clients. Syntax snvtFlag = nvObject.SnvtTypeIsModifiable Element Description snvtFlag A Boolean value indicating whether the network variable’s type can be changed. TRUE. The SNVT type assigned to the network variable can be changed. FALSE. The SNVT type property may not be changed. nvObject NetworkVariable object. Data Type Boolean. Read/Write Read only. Added to API Prior to LNS Release 3.0.
PAGE 655
TypeSpec Summary Contains an object that defines the type used by the network variable. This includes the name of the network variable type, and the scope and program ID of the resource file that contains the definition of the type. OpenLNS uses this information to identify the type a network variable should use. In some cases, you can write to the properties of this object to change the network variable’s type.
PAGE 656
Accessed Through Connections object. Interface object. LonMarkObject object. Default Property Item Methods • • • • • Add ItemByIndex ItemByProgammaticName Remove RemoveByIndex Properties • • • • • ClassId Count Item Parent _NewEnum Methods The NetworkVariables object contains the following methods. • • • • • Add ItemByIndex ItemByProgammaticName Remove RemoveByIndex Add Summary Adds a network variable to the collection.
PAGE 657
unique user names. If you use this method to add a network variable to a collection on a static LonMarkObject or a device’s main interface, then the LCA#119 lcaErrInterfaceNotModifyable exception will be thrown, unless the device supports the addition of dynamic network variables to static LonMarkObject objects. You can check if a LonMarkObject is static or dynamic by reading the object’s IsDynamic property. Availability Local, full, and lightweight clients. Syntax newNV = networkVariables.
PAGE 658
used for updates to the network variable, as well as the network variable’s default polling, synchronization, priority and authentication settings. The valid values for this element, which are contained in the ConstNvOptionsFlags constant, are as follows (these options can be ORed together): Note: Values 0,1 and 2 in this constant are mutually exclusive. Selecting more than one of them will cause the LCA, #152 lcaErrInvalidServiceType exception to be thrown.
PAGE 659
4 lcaNvOptionsPolled Select this option to enable the network variable’s polling attribute. 8 lcaNvOptionsSynchronized Select this option to create the network variable as a synchronous network variable, meaning that all all updates to the network variable will be delivered to the application, not just the most recently received update (when earlier updates have been queued, but have not yet not delivered to the application).
PAGE 660
acted upon was obtained from a LonMarkObject; otherwise, it is ignored. Added to API LNS Release 3.20. ItemByIndex Summary Retrieves a NetworkVariable object from a NetworkVariables collection. The object to be retrieved must be specified by its index value. This property is only supported by NetworkVariables collections that belong to Interface or LonMarkObject objects.
PAGE 661
Syntax Added to API retrievedObject = collection.ItemByProgrammaticName progName Element Description retrievedObject The NetworkVariable object to be retrieved from the collection. collection The NetworkVariables collection being acted upon. progName The ProgrammaticName of the NetworkVariable object to be retrieved. LNS Release 3.20. Remove Summary Removes a NetworkVariable object from the NetworkVariables collection.
PAGE 662
Added to API networkVariables The NetworkVariables collection to be acted upon. indexName A Long value specifying the collection index of the NetworkVariable object to remove, or a String value specifying the name of the NetworkVariable object to remove. LNS Release 3.20. RemoveByIndex Summary Removes a NetworkVariable from the collection. You can specify the network variable to be deleted by its index number within the collection.
PAGE 663
ClassId Summary Identifies the object class of this object. This property allows the object type to be determined when it is unknown (for example, when the object was accessed using the Parent property of another object). Availability Local, full, lightweight, and independent clients. Note that some objects containing this property are not available to Independent clients. Syntax classIdValue = object.ClassId Element Description classIdValue The object class of the object.
PAGE 664
NetworkVariables collection by passing its index (ordinal position) within that collection as the argument for the Item property. Index values start at 1. You can also retrieve a NetworkVariable object in NetworkVariables collections with the Name property by passing the object’s name as a string expression. Availability Local, full, lightweight, and independent clients. Note that some objects containing this property are not available to Independent clients. Syntax retrievedObject = collObject.
PAGE 665
Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. _NewEnum Summary Enables you to iterate over the objects in a collection using For Each ... Next statements. • If you are developing your OpenLNS app in Visual C++, you can browse a collection to find a particular item by using the _NewEnum property. See the IEnumVARIANT interface for details.
PAGE 666
CurrentOptions properties of network variable monitor points in temporary monitor sets are not accessible, as temporary monitor sets are only used in a singe client session. You can change the monitoring options a NvMonitorPoint will use for an active monitoring session by writing to the NvMonitorOptions object accessed through the NvMonitorPoint object’s CurrentOptions property. Changes made to the current options take effect for the current session only, and are not stored persistently in memory.
PAGE 667
• • • • • • • ResetPollingIfUpdated Retries ServiceType SuppressPollingIfBound ThrottleInterval UseAsyncSend UseBoundUpdates Authentication Summary Determines whether the authenticated service will be used when sending a network variable monitor point updates using the Value property. See the Monitor and Control chapter in the OpenLNS Programmer’s Guide for more information on network variable monitor points. Availability Local, full, lightweight, and independent clients.
PAGE 668
Data Type Integer. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. GenerateInitialFetch Summary Determines if the network variable value is fetched automatically when the network variable monitor point is enabled. Availability Local, full, lightweight, and independent clients.
PAGE 669
Read/Write Read/write. Added to API LNS Release 3.0. Parent Summary Returns the object that spawned the current child object. The parent object is determined by the means in which a child object is accessed, not by the OpenLNS Object hierarchy. Availability Local, full, lightweight, and independent clients. Note that some collection objects are not available to Independent clients. Syntax parentObject = object.
PAGE 670
NvOptions property of the MonitorSet object. This may be useful if you want the poll interval for the monitor point to always match the default value stored in the MonitorSet object. However, this feature is not available in server-independent mode. When writing to this property, the amount of polling you can do on a network depends on the speed of the communication channels being used by the network, and the amount of traffic on those channels.
PAGE 671
You can set this property through the CurrentOptions property of a permanent or temporary network variable monitor point to determine the priority setting to use when sending network variable updates during the current monitoring session. See the Monitor and Control section of the OpenLNS Programmer’s Guide for more information. Availability Local, full, lightweight, and independent clients. Note that temporary MonitorSet objects and temporary monitor points are not available on Independent clients.
PAGE 672
This is the default. -1 The value is set to the value currently stored in the NvOptions property of the MonitorSet object. This occurs if this property is contained in the NvMonitorOptions object accessed through the DefaultOptions or CurrentOptions property of a NvMonitorPoint object. This value is stored in the ConstLNSMonitorSetOptionDefault constant.
PAGE 673
connection, or via a read operation. 0 The polling of the monitor point will continue at the prescribed interval, even if the value of the point is received between polling periods. This is the default. -1 The value is set to the value currently stored in the NvOptions property of the MonitorSet object. This occurs if this property is contained in the NvMonitorOptions object accessed through the DefaultOptions or CurrentOptions property of a NvMonitorPoint object.
PAGE 674
DefaultOptions properties of all temporary monitor points are not accessible. However, you can set this property through the NvOptions property of a temporary monitor set to determine the default retry count that will be applied to all temporary monitor points as they are added to the set. You can also set this property through the CurrentOptions property of a permanent or temporary monitor point to determine what retry count for the current monitoring session.
PAGE 675
retryValue The valid values for this property, which are enumerated in the ConstServiceTypes constant, are as follows: 0 lcaSvcAckd Acknowledged messaging service. The device sends an acknowledgment message after it has received the message. If your application will be sending messages to large numbers of devices at once, one of the unacknowledged messaging services may be desirable, as the acknowledgment messages may generate a significant amount of network traffic.
PAGE 676
monOptsObject Data Type Long. Read/Write Read/write. Added to API LNS Release 3.0. The NvMonitorOptions object to be acted on. SuppressPollingIfBound Summary Determines whether polling will be turned of if the network variable is bound to the host. Availability Local, full, lightweight, and independent clients. Note that temporary MonitorSet objects and temporary monitor points are not available on Independent clients. Syntax suppressValue = nvMonOptsObject.
PAGE 677
Read/Write Read/write. Note: OpenLNS sets this property automatically for message monitor points. For example, if you are sending a message via the SendMsgWait method, a response from the device is expected. Therefore, OpenLNS will set the UseAsyncSend property to False. Also, if you are writing to a message monitor point via the OutputDataPoint property, no response is expected; therefore, OpenLNS sets the property to True.
PAGE 678
Added to API LNS Release 3.0. UseAsyncSend Summary Determines whether OpenLNS will wait for a completion code to return after updating the value of a monitor point before sending its next update message. When sending the values of network variable and message monitor points prior to LNS 3.20, LNS would wait for the completion code for each message sent to be returned before returning to the user, regardless of the messaging service type being used.
PAGE 679
events to confirm that the values of your monitor points have been successfully sent. This approach may be useful if you are updating a large number of monitor points at once, and do not want to wait for a completion code to return after each update before moving to the next one. Setting this property to True therefore may be useful when writing to the values of large numbers of data points with the Write method because it reduces the time required to update the values on the network. FALSE.
PAGE 680
Read/Write Read/write. Note: OpenLNS sets this property automatically for message monitor points. For example, if you are sending a message via the SendMsgWait method, a response from the device is expected. Therefore, OpenLNS will set the UseAsyncSend property to False. Also, if you are writing to a message monitor point via the SendMsgWait property, no response is expected; therefore, OpenLNS sets the property to True.
PAGE 681
this set of options should use bound updates. FALSE. The monitor points using this set of options should not use bound updates. nvMonOptsObject Data Type Boolean. Read/Write Read/write. Added to API LNS Release 3.0. The NvMonitorOptions object to be acted on. NvMonitorPoint A NvMonitorPoint object represents a single monitored or controlled network variable.
PAGE 682
Events • • • Name Parent Tag • • UpdateErrorEvent UpdateEvent Methods The NvMonitorPoint contains the following methods. • • • • Advise Disable Enable Unadvise Advise Summary Enables update and error events for an object that implements the ILcaMsgMonitorPointListener or ILcaNvMonitorPointListener interface. This method should only be used if the development environment supports multi-threading (such as Visual C++).
PAGE 683
Added to API tag An Integer type mpObject The NvMonitorPoint object to be acted on. object An object that implements the ILcaNvMonitorPointListener interface. LNS Release 3.0. Disable Summary Disables monitoring of a network variable monitor point. When you disable monitoring of a network variable monitor point, you should note that this overrides subsequent calls to the MonitorSet object's Enable method.
PAGE 684
doEnable element to True when you open the monitor set. If the doEnable element is set to False, you can also enable the entire monitor set later by calling the Enable method on the MonitorSet object. You can disable monitoring of an individual network variable monitor point by calling the Disable method on it. For more details on opening and enabling monior sets and monitor points, see Chapter 9 of the OpenLNS Programmer’s Guide. Availability Local, full, lightweight, and independent clients.
PAGE 685
ClassId Summary Identifies the object class of this object. This property allows the object type to be determined when it is unknown (for example, when the object was accessed using the Parent property of another object). Availability Local, full, lightweight, and independent clients. Note that some objects containing this property are not available to Independent clients. Syntax classIdValue = object.ClassId Element Description classIdValue The object class of the object.
PAGE 686
demonstrates this procedure: Set curOptions = monPoint.CurrentOptions curOptions.Authentication = True curOptions.Retries = 5 Set monPoint.CurrentOptions = curOptions Availability Local, full, lightweight, and independent clients. Note that temporary MonitorSet objects and temporary monitor points are not available on Independent clients. Syntax curOptions = monPoint.CurrentOptions Element Description curOptions The NvMonitorOptions object containing the current options for this monitor point.
PAGE 687
DefaultOptions Summary Contains the default monitoring options that are applied each time the monitor set containing this network variable or network variable monitor point is opened. These options are read when the monitor set containing the monitor point is opened. Changes to these options will not take effect until the next time the monitor set is opened. Use the CurrentOptions property to change the active monitoring options to use for a monitor point that is currently enabled.
PAGE 688
Added to API LNS Release 3.0. FormatSpec Summary Contains the format specification information for data read from the FormattedValue property in the DataPoint or NvMonitorPoint object. This property contains a FormatSpec object that determines the base type to use when reading the formatted values of the data point or monitor point. For data points acquired through NetworkVariable objects, the default settings for the FormatSpec object are determined based on the network variable’s TypeSpec property.
PAGE 689
(.), and colon (:) characters. Availability Local, full, lightweight, and independent clients. Note that some objects that contain this property are not available to Independent clients. Syntax stringValue = object.Name Element Description stringValue The name of the object. object The object to be acted on. Data Type String. Read/Write Read/write. Added to API Depends on the object used to access the property.
PAGE 690
application device that a monitor set belongs to. The Tag properties for all NvMonitorPoint objects in permanent monitor sets are cached when the monitor set is opened. As a result, any changes made the Tag properties of these monitor points while the permanent monitor set is open will not be accessible until the monitor set is closed and re-opened. When initially created, monitor points and monitor sets will have a null Tag value.
PAGE 691
UpdateErrorEvent Summary Indicates that a write failure or a poll failure has occurred on the network variable monitor point that generated the event. This event can only be used in development environments that support events being generated on threads other than the client thread (such as Visual C++). In these environments, it is usually more efficient to generate events from a non-client thread.
PAGE 692
which are contained in the ConstMonitorEventType constant, are as follows: 0 lcaMonitorEventTypeNull This value is not used. 1 lcaMonitorEventTypeQuit This value is not used. 2 lcaMonitorEventTypeAdd This value is not used. 3 lcaMonitorEventTypeRemove This value is not used. 4 lcaMonitorEventTypeMsCreate This value is not used. 5 lcaMonitorEventTypeMsDelete This value is not used. 6 lcaMonitorEventTypeMsChange This value is not used. 7 lcaMonitorEventTypeMsError This value is not used.
PAGE 693
14 lcaMonitorEventTypeMsgCreate A message monitor point has been created. 15 lcaMonitorEventTypeMsgDelete A message monitor point has been removed. 16 lcaMonitorEventTypeMsgChange This value is not used. 17 lcaMonitorEventTypeMsgError A message monitor point has returned an error. See the OnMsgMonitorPointErrorEvent. 18 lcaMonitorEventTypeMsgUpdate A message monitor point has received an update. See the OnMsgMonitorPointUpdateEvent.
PAGE 694
NvMonitorPoints The NvMonitorPoints object contains a collection of NvMonitorPoint objects. This collection object contains all of the NvMonitorPoint objects that have been added to a monitor set. Network variable monitor points can be used for explicit reading and writing, polled monitoring, or implicit bound monitoring of network variables on devices in your network. For more information on network variable monitor points, see the Monitor and Control chapter of the OpenLNS Programmer’s Guide.
PAGE 695
automatically removed when the application shuts down. If a monitor point is not going to be used again, remove it with the Remove method before closing your application. This does not apply to monitor points in temporary monitor sets, as temporary monitor sets are deleted as soon as the application that created them shuts down. As a result, you should use temporary monitor points for monitor points you will only need to use once.
PAGE 696
Remove Summary Removes an NvMonitorPoint object from the collection. This method can only be called when connected to the network database (after the Network object's Open method has been called). This method only applies to network variable monitor points in permanent monitor sets. When an OpenLNS application is closed, all temporary monitor sets and temporary network variable monitor points created by that application are deleted automatically.
PAGE 697
NvMonitorPoints object in the ConstClassIds constant: 81 lcaClassIdNvMonitorPoints object The object to be acted on. Data Type Integer. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. Count Summary Returns the number of objects in a collection. You can use this property to enumerate a collection object. Availability Local, full, lightweight, and independent clients.
PAGE 698
retrievedObject The object retrieved from the collection. collObject The collection object to be acted on. index A Long type specifying the ordinal index of the object to retrieve. stringExpression A string type specifying the name of the object to retrieve. Data Type Object. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API.
PAGE 699
Each ... Next statements. • If you are developing your OpenLNS app in C#, you do not need to use the _NewEnum property explicitly because it is automatically used in the implemention of foreach statements. Availability Local, full, and lightweight clients. Syntax retrievedObject = collObject._NewEnum Element Description retrievedObject An expression that evaluates to the object retrieved. collObject An iterator object that can be used to access members of the collection. Data Type Object.
PAGE 700
Events • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • CausesValidation ClassId ComponentApps Container CurrentFormatLocale DatabasePath DragIcon DragMode Extensions Flags FormatLocales Height HelpContextID Index IsOpen LdrfLanguages LdrfCatalogPath Left Name NetworkInterfaces Networks Object Parent RemoteFlag RemoteNetworks ResourceLanguageId TabIndex TabStop Tag ToolTipText Top Version Visible VNINetworks WhatsThisHelpID Width • • • • • • • • • • • • • • • • DragDrop DragOver G
PAGE 701
• • • • • • • • • • • • • OnNetworkVariableStringUpdate OnNetworkVariableUpdate OnNodeConnChangeEvent OnNodeIntfChangeEvent OnNvMonitorPointErrorEvent OnNvMonitorPointEvent OnNvMonitorPointUpdateEvent OnNVUpdateError OnSessionChangeEvent OnSystemMgmtModeChangeEvent OnSystemNssIdle OnSystemServicePin Validate Methods The ObjectServer object contains the following methods.
PAGE 702
AcceptIncomingSession Summary Accepts or rejects an incoming uplink session request after you have registered your application for uplink session handling. You can use this method to accept or reject an uplink session request after a request has been received, and the OnIncomingSessionEvent event has been fired. If an uplink session request is rejected, the session will be terminated.
PAGE 703
being opened. TRUE. Suspends all monitor point update events while the uplink session is being opened. In this case, withheld monitor point updates must be released by calling the ReleasePendingUpdates method. FALSE. Deletes all monitor point update events that occur while the session is being initialized. Added to API LNS Release 3.06. BeginIncomingSessionEvents Summary Registers your application for incoming session event handling.
PAGE 704
Syntax objServer.AcceptIncomingSession tag, acceptUplink, postponeUpdates Element Description objServer The Object Server object being acted upon. xDriverProfileName An xDriver Profile name as a String. Your application will be informed of incoming session requests that come in on the TCP listener port assigned to the selected Profile. You can use the OpenLDV xDriver Profile Editor to create an xDriver Profile, enable it for incoming session handling, and assign it a listener port.
PAGE 705
CompactDb Summary Defragments and re-indexes OpenLNS global database. You may not call this method on an OpenLNS database that is open and in use by any client application. You should backup all OpenLNS databases before calling this method. Also, your computer should have at least twice as much free disc space as the size of the database when you call this method. Availability Local, full, lightweight, and independent clients. Syntax objServObject.
PAGE 706
ExtensionByHandle Summary Retrieves an Extension object by its Handle property. This method can be used to retrieve an extension record in the global database—regardless of the collection containing the Extension object. This may be particularly useful when processing events reported by OnChangeEvent with objectType of lcaChangeEventExtensions, and networkHandle equal to 0. Availability Local, full, and lightweight clients. Syntax extension = objectServer.
PAGE 707
connection update state, remote application transfer state and the Data Server remote-IP mode used by the LNS Server. However, if you plan to modify the current value of the Flags property, you must do so before opening the ObjectServer with this method. If you will be opening any networks with an OpenLNS application that is running as a Windows service, then the first application to open the OpenLNS Object Server must also be running as a Windows service.
PAGE 708
RebuildLdrfCatalog Summary The LonMark Device Resource Files catalog is used to keep track of all sets of LonMark Device Resource Files that are to be referenced by OpenLNS. Prior to OpenLNS, the catalog would be found at \Types folder. With OpenLNS and the introduction of the LonWorks Data Path, the catalog is now found at \Types.
PAGE 709
method before opening the Object Server if you plan on running your application in the standard licensing mode (Standard Mode). For Lightweight client applications, you must always call this method prior to opening the Object Server, as Lightweight client applications can only operate in Standard Mode. Note that this is the last step a Local, Lightweight or Full client application should take before opening the Object Server.
PAGE 710
Properties The ObjectServer object contains the following properties.
PAGE 711
Element Description networkObject The Network object designated as active. objServerObject The ObjectServer object to be acted on. Data Type Network object. Read/Write Read only. Added to API Prior to LNS Release 3.0. ActiveRemoteNI Summary Specifies the network interface your remote Full client application will use to communicate with the OpenLNS Server. You must set this property before accessing the Networks collection object if you are using a remote Full client application.
PAGE 712
CausesValidation Summary This is a standard ActiveX control event used for visual controls. This event is not applicable for the Object Server. ClassId Summary Identifies the object class of this object. This property allows the object type to be determined when it is unknown (for example, when the object was accessed using the Parent property of another object). Availability Local, full, lightweight, and independent clients.
PAGE 713
Read/Write Read only. Added to API Prior to LNS Release 3.0. Container Summary This is a standard ActiveX control property used for visual controls. This property is not applicable for the Object Server. CurrentFormatLocale Summary Determines which FormatLocale object will be used by your application as the active FormatLocale. Each FormatLocale object contains a group of properties that reflect a particular geographical area’s conventions for data display.
PAGE 714
Data Type String. Read/Write Read/write. Added to API LNS Release 3.20. DatabasePath Summary Contains the path of the global OpenLNS database. You can only set the global database path before invoking the Open method for the ObjectServer object. The default location of the global database is C:\LONWORKS\ObjectServer\GlobalDb. OpenLNS does not apply a length restriction to the global database path. Availability Local, full, lightweight, and independent clients. Syntax dbPath = object.
PAGE 715
extensionsColl The Extensions collection object. object The object whose Extensions collection is being returned. Data Type Extensions collection object. Read/Write Read only. Added to API Prior to LNS Release 3.0.
PAGE 716
connections are updated. You should not set this value to True because your application may then process or send network variable updates using inconsitent network variable configuration. This could lead to misinterpretation of network variable updates on this or another device. 16 lcaFlagsUseTCP Indicates that a remote client (see RemoteFlag) will access the OpenLNS Server via TCP/IP. This flag should not be ORed with the lcaFlagsUseNSI (32) flag.
PAGE 717
Service Device will be automatically upgraded whenever an upgrade is required. If this flag is not set, OpenLNS will perform the upgrades automatically. The flag is not set by default. If you set this flag, you will need to upgrade your client’s NetworkServiceDevices manually when any of the following situations occur: • A new version of OpenLNS is installed which changes the Network Service Device’s program interface. For example, OpenLNS 3.
PAGE 718
pre-defined FormatLocale objects, and you can create custom FormatLocale objects with the Add method. For more information, see the FormatLocales collection object. Note: You can only access this property after you have opened the Object Server. Availability Local, full, lightweight, and independent clients. Syntax flCollection = objectServer.FormatLocales Element Description flCollection The FormatLocales collection object returned. objectServer The ObjectServer object being acted upon.
PAGE 719
Element Description isOpenFlag Boolean value. Object A Boolean value indicating whether the ObjectServer object is currently open. TRUE. The ObjectServer object is currently open. FALSE. The ObjectServer object is currently closed. Data Type Boolean. Read/Write Read only. Added to API LNS Release 3.0. LdrfLanguages Summary Contains the LdrfLanguages collection representing the languages known by OpenLNS. You can only access this property after you have opened the Object Server.
PAGE 720
LdrfCatalogPath Summary Obtains the full path for the location of the LonMark device resource file catalog (ldrf.cat). You should not modify this path because the resource file catalog should always be stored in the LonWorks/Types folder. The LdrfCatalogPath property points this path by default; therefore, you should not write to this property under any circumstances.
PAGE 721
Availability Local, full, lightweight, and independent clients. Note that some objects that contain this property are not available to Independent clients. Syntax stringValue = object.Name Element Description stringValue The name of the object. object The object to be acted on. Data Type String. Read/Write Read/write. Added to API Depends on the object used to access the property. Generally, this property exists for the objects listed above as soon as they are added to the API.
PAGE 722
Data Type Networks collection object. Read/Write Read only. Added to API Prior to LNS Release 3.0. Object Summary Allows invocation of a control's method or property that has the same name as a method or property automatically extended by the control container. See your development tool's help for more information on this property. Availability Local, full, lightweight, and independent clients. Note that some objects that contain this property are not available to Independent clients.
PAGE 723
Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. RemoteFlag Summary Specifies whether the network will be opened locally or remotely. This property must be set prior to opening the OpenLNS Server. See the Open method for more information. The RemoteFlag property must be set to True for applications that are to be distributed as LNS Remote distributables.
PAGE 724
RemoteNetworks Summary Contains a collection of all remote full client networks that have been opened by an application running on this client's computer. The OpenLNS Object Server views the networks in this collection as local networks. To view this collection, you must set the RemoteFlag property to False. Availability Local, full, lightweight, and independent clients. Note that some collection objects are not available to Independent clients. Syntax parentObject = object.
PAGE 725
ResourceLanguageId Summary Controls which language should be used when displaying descriptive type information stored in device resource files. This property can contain one or more language codes that identify the language that should be used when displaying type information stored in resource files. When you pass multiple language codes to this property, they must be comma-separated, as in the following example: "frc, enz, rus.
PAGE 726
TabIndex Summary A standard ActiveX control property used for visual controls. This property is not applicable for the Object Server. TabStop Summary A standard ActiveX control property used for visual controls. This property is not applicable for the Object Server. Tag Summary Contains any extra data needed for your program. The data stored in this property is not used by the Object Server, and can be used for any purpose by the OpenLNS application.
PAGE 727
"4.00"). The version number is the same value as that returned in the About Box osObject The ObjectServer object to be acted on. Data Type String. Read/Write Read only. Added to API Prior to LNS Release 3.0. Visible Summary A standard ActiveX control property used for visual controls. This property is not applicable for the Object Server. VNINetworks Summary Contains the Networks collection containing all the Network objects which can be opened in server-independent mode.
PAGE 728
WhatsThisHelpID Summary This property returns or sets an associated context number for an object. You can use this property to provide context-sensitive help for your application for 32-bit Windows operating systems. This property is not supported by the Object Server. Width Summary A standard ActiveX control property used for visual controls. This property is not applicable for the Object Server.
PAGE 729
DragDrop Summary A standard ActiveX control event used for visual controls. This event is not applicable for the Object Server. DragOver Summary A standard ActiveX control event used for visual controls. This event is not applicable for the Object Server. GotFocus Summary A standard ActiveX control event used for visual controls. This event is not applicable for the Object Server. LostFocus Summary A standard ActiveX control event used for visual controls.
PAGE 730
Syntax OnAttachment(networkHandle As Long, systemHandle As Long, objectType as Integer, isAttached As Boolean, stateFailure as Boolean, objectHandle As Long) Element Description networkHandle Handle of the network in which the attached or unattached device or router resides. systemHandle The Handle of the system in which the attached or unattached device or router resides. objectType The type of object that was attached or unattached.
PAGE 731
and NodeId properties. If the state is lcaStateUncnfg or lcaStateCnfgOffline, you can resolve this by recomissioning the device or router with the Commission method. If the state of an application device is lcaStateNoApplUncnfg, and that device is a Neuron hosted device, you must reload the application with the Load method. After either operation, the state of the device or router will be lcaStateSoftOffline.
PAGE 732
constant, are as follows: 0 1 2 3 4 5 6 7 8 9 changeType lcaChangeEventAppDevices lcaChangeEventChannels lcaChangeEventRouters lcaChangeEventSubnets lcaChangeEventNsis lcaChangeEventSubsystems lcaChangeEventDeviceTemplates lcaChangeEventDomains lcaChangeEventConnectDescTemplates lcaChangeEventExtensions Indicates how the object changed. The enumerated values for this element, which are contained in the ConstObjectChangeTypes constant, are as follows: 0 lcaObjectCreate An object was created.
PAGE 733
OnCommission Summary Indicates that a device’s commission status has changed. You can register your application for the OnCommission event by invoking the BeginCommissionEvents method. You can subscribe or unsubscribe your application to this event by calling the System object’s BeginCommissionEvent and EndCommissionEvent methods.
PAGE 734
changes. The enumerated values for this element, which are contained in the ConstCommissionStatus constant, are as follows: 0 lcaCommissionUpdatesCurrent No outstanding commission updates are pending. The commission status changes lcaCommissionUpdatesCurrent (0) when database changes have been successfully propagated to the device 1 lcaCommissionUpdatesPending Commission updates are currently pending, or in progress.
PAGE 735
OnDbConversionEvent Summary Provides a client application the progress of an OpenLNS database conversion. When an OpenLNS database is opened using an application written with a newer version of OpenLNS, the database will be automatically upgraded to the new version of OpenLNS. For example, if an application running on OpenLNS calls the Open method to open a network using an LNS 3.20 database, the database would be upgraded automatically.
PAGE 736
OnDbValidationEvent Summary Provides a client application the progress of database validation. A database validation can be initiated with the Validate method. Depending on the size of a network database, a database validation can take a considerable amount of time to complete. You can use the information returned by this event to develop an idea of how long the database validation being performed will take.
PAGE 737
database validation that is currently being performed. The phase name will be returned as a string of up to 230 characters. thisStepName Added to API The step that is currently being performed. The step name will be returned as a string of up to 230 characters. Generally, this will be the name of the object in the database that is currently being validated. LNS Release 3.20.
PAGE 738
Syntax Added to API OnIncomingSessionEvent(xDriverProfileName, netName, intfName, tag) Element Description xDriverProfileName A String identifying the Profile that is using the TCP listener port this session came in on. This may be useful in an application that registers for uplink session event handling with multiple xDriver Profiles. netName A String that represents the OpenLNS network name of the network that has requested the uplink session.
PAGE 739
Syntax Added to API OnLonMarkObjectStatusChangeEvent(networkHandle, systemHandle, deviceHandle, LonMarkObjectIndex) Element Description networkHandle The handle of the Network containing the modified LonMarkObject. systemHandle The handle of the System containing the modified LonMarkObject. deviceHandle The handle of the AppDevice using the Interface that contains the modified LonMarkObject. LonMarkObjectInde x The device index number of the modified LonMarkObject.
PAGE 740
multi-threading (such as Visual C++), you can receive update events on a separate thread by creating an object which implements the ILcaNvMonitorPointListener . Syntax OnMsgMonitorPointErrorEvent(msgMonitorPoint As Object, ErrorType as Integer) Element Description msgMonitorPoint The MsgMonitorPoint object that reported an error. ErrorType The error type for the event.
PAGE 741
has returned an error. See the OnNvMonitorPointErrorEvent event. 12 lcaMonitorEventTypeNvUpdate A network variable monitor point has received an update. See the OnNvMonitorPointUpdateEvent event. 13 lcaMonitorEventTypeNvComplete A completion code has returned for the monitor point. 14 lcaMonitorEventTypeMsgCreate A message monitor point has been created. 15 lcaMonitorEventTypeMsgDelete A message monitor point has been removed. 16 lcaMonitorEventTypeMsgChange This value is not used.
PAGE 742
OnMsgMonitorPointEvent Summary An event that is generated whenever a message monitor point is created or removed from a permanent monitor set. The events are only fired in this case if the monitor set is open. In addition, when you close or open a permanent monitor set, this event will be fired for each message monitor point in the set, indicating that the monitor points have been removed from or created in memory.
PAGE 743
8 lcaMonitorEventTypeNvCreate A network variable monitor point has been created. 9 lcaMonitorEventTypeNvDelete A network variable monitor point has been removed. 10 lcaMonitorEventTypeNvChange This value is not used. 11 lcaMonitorEventTypeNvError A network variable monitor point has returned an error. See the OnNvMonitorPointErrorEvent event. 12 lcaMonitorEventTypeNvUpdate A network variable monitor point has received an update. See the OnNvMonitorPointUpdateEvent event.
PAGE 744
received a request message. 20 lcaMonitorEventTypeMsgResponse A message monitor point has received a reponse message. 21 lcaMonitorEventTypeMsgComplete This value is not used. Added to API LNS Release 3.0. OnMsgMonitorPointUpdateEvent Summary An event that is generated whenever a message tag monitor point update is received. The OnMsgMonitorPointEvent event is used to signify asynchronous successful completion code events for a message monitor point.
PAGE 745
Added to API LNS Release 3.0. OnNetworkServiceDeviceResetNew Summary Indicates that the local network interface has reset. This event is identical to the old OnNetworkServiceDeviceReset event, but it includes information regarding the network service device’s network, system, and object handles. Lightweight Client applications cannot receive the OnNetworkServiceDeviceResetNew event. You can enable this event for your application by calling the BeginResetEvent method.
PAGE 746
your application's main thread. Instead, a separate thread will be used for this event. When using the separate thread for these events, you should perform as little processing as possible within your event handler. However, you can use the PostMessage() or PostMessageThread() functions of the Win API to defer these events to the application's main thread. Consult the Windows documentation for more information on these functions.
PAGE 747
Syntax Added to API OnNetworkVariableUpdate (monitorTag As Long, value as Variant, dataUpdateInfo As Object) Element Description monitortag The monitor tag value assigned to the network variable. value Current data value of the network variable. dataUpdateInfo The DataValue object for this update. Prior to LNS Release 3.0. OnNodeConnChangeEvent Summary This event is generated whenever a connection is created or modified, or whenever the ConnectDescTemplate used by a connection is modified.
PAGE 748
TargetDeviceHandle The Handle of the AppDevice object whose connection changed. Version The version of the device's connection information. This is incremented by 1 whenever the device is added to or removed from a connection. ObjectChangeType Indicates how the connection was modified.
PAGE 749
or MessageTag. HubNvMtIndex Added to API The Index of the connection’s hub NetworkVariable or MessageTag. LNS Release 3.0. OnNodeIntfChangeEvent Summary This event is generated whenever a device's external interface is changed. You can enable this event with the BeginNodeIntfChangeEvent method. You can disable this event with the EndNodeIntfChangeEvent method.
PAGE 750
You can also determine the version of an Interface object by reading the Version property. ObjectChangeType Indicates how the interface changed. Changes that may be reported by the event include the addition, removal, or modification of a NetworkVariable, MessageTag, or LonMarkObject object on the interface. The possible values for this element, which are contained in the ConstNodeIntfChangeTypes constant, are as follows: 0 lcaNodeInterfaceNvAdded A NetworkVariable was added to the interface.
PAGE 751
affected network variable’s new user name. The user name is stored in the network variable’s Name property. The ObjectIndex element will contain the renamed network variable’s device index number. 4 lcaNodeInterfaceLonMarkObjec tAdded A LonMarkObject obect (dynamic function block) was added to the interface. The Name element will contain the added LonMarkObject’s ProgrammaticName. The ObjectIndex element will contain the new LonMarkObject object’s device index number.
PAGE 752
interface. The Name element will contain an empty string. The ObjectIndex element will contain the affected LonMarkObject object’s device index number. 8 lcaNodeInterfaceLonMarkObjec tRenamed The user name of a LonMarkObject on the interface was changed. The Name element will contain the LonMarkObject’s new user name. The user name is stored in the LonMarkObject’s Name property. The ObjectIndex element will contain the renamed LonMarkObject object’s device index number.
PAGE 753
moved A message tag was removed from the interface. The Name element will contain an empty string. The ObjectIndex element will contain the removed MessageTag object’s device index number. 12 lcaNodeInterface MessageTagRenamed Reserved for future use. 13 lcaNodeInterface CpRenamed The user name of a configuration property on the interface was modified. The Name element will contain the affected configuration property’s new user name. The user name is stored in the configuration property’s Name property.
PAGE 754
Name Added to API The name of the object that was modified. This may be the user name or the programmatic name of the object, depending on the ObjectChangeType that caused the event. In some cases, the Name element will contain an empty string. LNS Release 3.0. OnNvMonitorPointErrorEvent Summary This event is generated whenever there is a write or poll failure on a network variable monitor point.
PAGE 755
7 lcaMonitorEventTypeMsError This value is not used. 8 lcaMonitorEventTypeNvCreate A network variable monitor point has been created. 9 lcaMonitorEventTypeNvDelete A network variable monitor point has been removed. 10 lcaMonitorEventTypeNvChange This value is not used. 11 lcaMonitorEventTypeNvError A network variable monitor point has returned an error. See the OnNvMonitorPointErrorEvent event. 12 lcaMonitorEventTypeNvUpdate A network variable monitor point has received an update.
PAGE 756
19 lcaMonitorEventTypeMsgRequest A message monitor point has received a request message. 20 lcaMonitorEventTypeMsgResponse A message monitor point has received a reponse message. 21 lcaMonitorEventTypeMsgComplete This value is not used. Added to API LNS Release 3.0. OnNvMonitorPointEvent Summary This event is generated whenever a network variable monitor point is created, removed, enabled or disabled.
PAGE 757
This value is not used. 3 lcaMonitorEventTypeRemove This value is not used. 4 lcaMonitorEventTypeMsCreate This value is not used. 5 lcaMonitorEventTypeMsDelete This value is not used. 6 lcaMonitorEventTypeMsChange This value is not used. 7 lcaMonitorEventTypeMsError This value is not used. 8 lcaMonitorEventTypeNvCreate A network variable monitor point has been created. 9 lcaMonitorEventTypeNvDelete A network variable monitor point has been removed. 10 lcaMonitorEventTypeNvChange This value is not used.
PAGE 758
This value is not used. 17 lcaMonitorEventTypeMsgError A message monitor point has returned an error. See the OnMsgMonitorPointErrorEvent event. 18 lcaMonitorEventTypeMsgUpdate A message monitor point has received an update. See the OnMsgMonitorPointUpdateEvent event. 19 lcaMonitorEventTypeMsgRequest A message monitor point has received a request message. 20 lcaMonitorEventTypeMsgResponse A message monitor point has received a reponse message. 21 lcaMonitorEventTypeMsgComplete This value is not used.
PAGE 759
OnNvMonitorPointUpdateEvent Summary This event is generated whenever a network variable monitor point update is received. If you are using a programming environment which supports multi-threading (such as Visual C++), you can receive update events on a separate thread by creating an object which implements the ILcaMsgMonitorPointListener interface.
PAGE 760
This event is also fired each time the state of your client’s NetworkServiceDevice changes from the online state to the offline state, or vice versa. You could use this event to keep track of when the NetworkServiceDevice is offline, as polling is suspended, and monitor and control events will not be delivered to your application, while the NetworkServiceDevice is in the offline state.
PAGE 761
been lost, and recovery is either disabled, or it has timed out. Your application will no longer be able to communicate with the remote network. 4 lcaSessionStateOffline The NetworkServiceDevice has been taken offline, possibly because the device is being commissioned. Polling is suspended and monitor and control events will not be delivered to your application while the NetworkServiceDevice is offline. 5 lcaSessionStateOnline The NetworkServiceDevice has returned to the online state.
PAGE 762
applied to both the OpenLNS database and the physical devices. 1 lcaMgmtModeDeferConfigUpdates Network configuration changes are applied only to the OpenLNS network database. Added to API LNS Release 3.20. OnSystemNssIdle Summary Indicates that an OpenLNS Server idle message was raised. When you call the BeginNssIdleEvent method to enable this event, you will specify an interval. This event will then be fired at that interval while your application is waiting for lengthy network operations to complete.
PAGE 763
Syntax OnSystemNssIdle() Added to API Prior to LNS Release 3.0. OnSystemServicePin Summary Indicates that a qualifying service pin message has been received. You must call the System object’s BeginServicePinEvent method to enable service pin events. The appDeviceObject parameter contains the application device that originated the service pin event. The eventTag parameter contains the corresponding event tag. You can call the EndServicePinEvent method to disable the service pin events.
PAGE 764
Validate Summary This is a standard ActiveX control event used for visual controls. This event is not applicable for the Object Server. ObjectStatus An ObjectStatus object can be accessed through the Status property or the ReportMask property of a LonMarkObject. If the object was accessed through the Status property, the object represents a status report. In this case, the properties of the ObjectStatus object reflect the current status of the LonMarkObject.
PAGE 765
• • • • • • • • • • • • • • • • • • • • • InAlarm InOverride InvalidId InvalidRequest LockedOut ManualControl MechanicalFault ObjectId OpenCircuit OutOfLimits OutOfService OverRange Parent ProgrammingFail ProgrammingMode ReportMask ResetComplete SelfTestInProgress Summary UnableToMeasure UnderRange Methods The ObjectStatus object does contain any methods. Properties The ObjectStatus object contains the following properties.
PAGE 766
• • • • • ResetComplete SelfTestInProgress Summary UnableToMeasure UnderRange AlarmNotifyDisabled Summary Indicates whether alarm notification is disabled on the LonMarkObject, or whether alarm notification can be disabled on the LonMarkObject. This description of this property depends on whether it was accessed through the Status or ReportMask properties of a LonMarkObject. • Status property. Indicates whether alarm notification on the LonMarkObject is currently disabled.
PAGE 767
on. Data Type Boolean. Read/Write Read only. Added to API Prior to LNS Release 3.0. ClassId Summary Identifies the object class of this object. This property allows the object type to be determined when it is unknown (for example, when the object was accessed using the Parent property of another object). Availability Local, full, lightweight, and independent clients. Note that some objects containing this property are not available to Independent clients. Syntax classIdValue = object.
PAGE 768
CommFailure Summary Indicates whether there has been a communication failure on the LonMarkObject object, or whether the LonMarkObject could report such a failure. This description of this property depends on whether it was accessed through the Status or ReportMask properties of a LonMarkObject. • Status property. Indicates whether a communication failure on the LonMarkObject has occurred. If this property is True, then there has been a communication failure. • ReportMask property.
PAGE 769
Disabled Summary Indicates whether the LonMarkObject is currently disabled, or whether the LonMarkObject can be disabled. This description of this property depends on whether it was accessed through the Status or ReportMask properties of a LonMarkObject. • Status property. Indicates whether the LonMarkObject is currently disabled. If this property is True, then the LonMarkObject is currently disabled. • ReportMask property. Indicates whether the LonMarkObject can be disabled.
PAGE 770
ElectricalFault Summary Indicates whether an electrical fault has been detected in the LonMarkObject object, or whether the LonMarkObject could report an electrical fault. This description of this property depends on whether it was accessed through the Status or ReportMask properties of a LonMarkObject. • Status property. Indicates whether an electrical fault has been detected in the LonMarkObject. If this property is True, then an electrical fault has been detected in the LonMarkObject.
PAGE 771
FailSelfTest Summary Indicates whether the LonMarkObject passed its most recent self-test, or whether the LonMarkObject can perform a self-test. This description of this property depends on whether it was accessed through the Status or ReportMask properties of a LonMarkObject. • Status property. Indicates whether the LonMarkObject failed its most recent self-test. If this property is True, then the LonMarkObject failed the self-test. • ReportMask property.
PAGE 772
FeedbackFailure Summary Indicates whether the feedback signal of the LonMarkObject is being received, or whether the LonMarkObject is capable of reporting this information. This description of this property depends on whether it was accessed through the Status or ReportMask properties of a LonMarkObject. • Status property. Indicates whether the feedback signal of the LonMarkObject is being received. • ReportMask property.
PAGE 773
InAlarm Summary Indicates whether the LonMarkObject is currently in an alarm condition, or whether the LonMarkObject is capable of reporting an alarm condition. This description of this property depends on whether it was accessed through the Status or ReportMask properties of a LonMarkObject. • Status property. Indicates whether the LonMarkObject is an alarm condition. If this property is True, then the LonMarkObject is an alarm condition. • ReportMask property.
PAGE 774
InOverride Summary Indicates whether the LonMarkObject is currently in an override state, or whether the LonMarkObject can be overridden. This description of this property depends on whether it was accessed through the Status or ReportMask properties of a LonMarkObject. • Status property. Indicates whether the LonMarkObject is an override state. If this property is True, then the LonMarkObject is an override state. • ReportMask property. Indicates whether the LonMarkObject can be overridden.
PAGE 775
InvalidId Summary Indicates that the requested LonMarkObject does not exist. Availability Local, full, and lightweight clients. Syntax invalidIdFlag = statusObject.InvalidId Element Description invalidIdFlag A Boolean value indicating whether the LonMarkObject exists. TRUE. The ID used to reference the LonMarkObject is invalid; therefore, the LonMarkObject does not exist. FALSE. The LonMarkObject exists. statusObject The ObjectStatus object to be acted on. Data Type Boolean.
PAGE 776
been made. statusObject The ObjectStatus object to be acted on. Data Type Boolean. Read/Write Read only. Added to API Prior to LNS Release 3.0. LockedOut Summary Indicates whether the LonMarkObject is in an operable state, or whether the LonMarkObject can report this information. This description of this property depends on whether it was accessed through the Status or ReportMask properties of a LonMarkObject. • Status property. Indicates whether the LonMarkObject is an operable state.
PAGE 777
Data Type Boolean. Read/Write Read only. Added to API Prior to LNS Release 3.0. ManualControl Summary Indicates whether the LonMarkObject is under manual control, or whether the LonMarkObject can be placed under manual control. This description of this property depends on whether it was accessed through the Status or ReportMask properties of a LonMarkObject. • Status property. Indicates whether the LonMarkObject is under manual control.
PAGE 778
MechanicalFault Summary Indicates whether a mechanical fault has been detected in the LonMarkObject object, or whether the LonMarkObject could report a mechanical fault. This description of this property depends on whether it was accessed through the Status or ReportMask properties of a LonMarkObject. • Status property. Indicates whether a mechanical fault has been detected in the LonMarkObject. If this property is True, then a mechanical fault has been detected in the LonMarkObject.
PAGE 779
ObjectId Summary Contains the ID of the LonMarkObject to which this ObjectStatus object applies. Objects are numbered from 0 to n-1, where n is the number of objects in an AppDevice. See the LonMark Application Layer Interoperability Guidelines for more information. Availability Local, full, and lightweight clients. Syntax objectIdValue = statusObject.
PAGE 780
LonMarkObject object. FALSE. An open circuit has not been discovered. ReportMask Property TRUE. The LonMarkObject can report an open circuit. FALSE. The LonMarkObject can not report an open circuit. statusObject The ObjectStatus object to be acted on. Data Type Boolean. Read/Write Read only. Added to API Prior to LNS Release 3.0. OutOfLimits Summary Indicates whether the LonMarkObject has exceeded its alarm limits, or whether the LonMarkObject is capable of reporting this information.
PAGE 781
TRUE. The LonMarkObject can report that it has exceeded its alarm limits. FALSE. The LonMarkObject can not report that it has exceeded its alarm limits. statusObject The ObjectStatus object to be acted on. Data Type Boolean. Read/Write Read only. Added to API Prior to LNS Release 3.0. OutOfService Summary Indicates whether the LonMarkObject is currently operational, or whether the LonMarkObject is capable of reporting this information.
PAGE 782
report that it is inoperable. statusObject The ObjectStatus object to be acted on. Data Type Boolean. Read/Write Read only. Added to API Prior to LNS Release 3.0. OverRange Summary Indicates whether the value associated with the LonMarkObject is greater than its acceptable range, or whether the LonMarkObject is capable of reporting this information. This description of this property depends on whether it was accessed through the Status or ReportMask properties of a LonMarkObject.
PAGE 783
report that its value is over the acceptable range. statusObject The ObjectStatus object to be acted on. Data Type Boolean. Read/Write Read only. Added to API Prior to LNS Release 3.0. Parent Summary Returns the object that spawned the current child object. The parent object is determined by the means in which a child object is accessed, not by the OpenLNS Object hierarchy. Availability Local, full, lightweight, and independent clients.
PAGE 784
failure. Availability Local, full, and lightweight clients. Syntax progFailFlag= statusObject.ProgrammingFail Element Description progFailFlag A Boolean value indicating whether a programming failure on the LonMarkObject has occurred, or whether the LonMarkObject can report a programmings failure. Status Property TRUE. A programming failure on the LonMarkObject has occurred. FALSE. A programming failure has not occurred. ReportMaskProperty TRUE. The LonMarkObject can report a programmings failure.
PAGE 785
Syntax progModeFlag= statusObject.ProgrammingMode Element Description progModeFlag A Boolean value indicating whether the LonMarkObject is currently in programming mode, or whether the LonMarkObject can placed in programming mode. Status Property TRUE. The LonMarkObject is in programming mode. FALSE. The LonMarkObject is not in programming mode. ReportMask Property TRUE. The LonMarkObject can be placed in programming mode. FALSE. The LonMarkObject can not be placed in programming mode.
PAGE 786
can be accessed through the ReportMask property of the LonMarkObject FALSE. The ObjectStatus object represents a status report. The ObjectStatus object reflects the current status of the LonMarkObject. These ObjectStatus objects can be accessed through the Status property of the LonMarkObject. statusObject The ObjectStatus object to be acted on. Data Type Boolean. Read/Write Read only. Added to API Prior to LNS Release 3.0.
PAGE 787
LonMarkObject has been completed. FALSE. The reset has not been completed. ReportMask Property TRUE. The LonMarkObject can be reset. FALSE. The LonMarkObject can not be reset. statusObject The ObjectStatus object to be acted on. Data Type Boolean. Read/Write Read only. Added to API Prior to LNS Release 3.0. SelfTestInProgress Summary Indicates whether the most recent self-test of the LonMarkObject is still in progress, or whether a self-test can be performed on the LonMarkObject.
PAGE 788
TRUE. The most recent self-test of the LonMarkObject is still in progress. FALSE. The self-test has been completed. ReportMask Property TRUE. A self-test can be performed on the LonMarkObject. FALSE. A self-test can not be performed on the LonMarkObject. statusObject The ObjectStatus object to be acted on. Data Type Boolean. Read/Write Read only. Added to API Prior to LNS Release 3.0. Summary Summary A Long that encompasses all of the status bits in the ObjectStatus object.
PAGE 789
UnableToMeasure Summary Indicates whether an input/output line failure has been detected in the LonMarkObject object, or whether the LonMarkObject could report an input/output line failure. This description of this property depends on whether it was accessed through the Status or ReportMask properties of a LonMarkObject. • Status property. Indicates whether an input/output line failure has been detected in the LonMarkObject.
PAGE 790
UnderRange Summary Indicates whether the value associated with the LonMarkObject is less than its acceptable range, or whether the LonMarkObject is capable of reporting this information. This description of this property depends on whether it was accessed through the Status or ReportMask properties of a LonMarkObject. • Status property. Indicates whether the value associated with the LonMarkObject is lower than its acceptable range. • ReportMask property.
PAGE 791
Added to API Prior to LNS Release 3.0. PingIntervals The PingIntervals object defines the duration of the ping interval for each of the four ping classes. Each device and router defines its ping class using the PingClass property. Setting these values appropriately allows you to reduce network traffic. The following table summarizes the PingIntervals object. Description The ping interval defined for the four ping classes. Added to API Prior to LNS Release 3.0. Accessed Through System object.
PAGE 792
following value is defined for the PingInterval object in the ConstClassIds constant: 69 lcaClassIdPingIntervals object The object to be acted on. Data Type Integer. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. MobileClassPingInterval Summary The cycle time (in seconds) for pinging devices that may move.
PAGE 793
The default value is 60 seconds for private media, and 0 seconds for shared media. piObject Data Type Long. Read/Write Read/write. Added to API LNS Release 3.0. The PingIntervals object to be acted on. Parent Summary Returns the object that spawned the current child object. The parent object is determined by the means in which a child object is accessed, not by the OpenLNS Object hierarchy. Availability Local, full, lightweight, and independent clients.
PAGE 794
The minimum value is 900 seconds. 65535 (-1) means "do not change". piObject Data Type Long. Read/Write Read/write. Added to API LNS Release 3.0. The PingIntervals object to be acted on. StationaryClassPingInterval The cycle time in seconds for pinging devices which are expected to move rarely. This value will be used for all devices and routers that have their PingClass property set to lcaPingClassStationary Summary The cycle time (in seconds) for pinging devices that are expected to move rarely.
PAGE 795
tempPing The ping interval (in seconds) for the temporary ping class. Set this property to 0 seconds to disable pinging. The minimum value is 60 seconds. 65535 (-1) means "do not change". The default value is 120 seconds. piObject Data Type Long. Read/Write Read/write. Added to API LNS Release 3.0. The PingIntervals object to be acted on. RecoveryStatus A RecoveryStatus object reports status information about the current phase of OpenLNS database recovery.
PAGE 796
Methods The RecoveryStatus object does not contain any methods. Properties The RecoveryStatus object contains the following properties: • • • • • • • • • • • • • • ClassId CurrentPhaseNumber ItemsInPhase NumberPhases Parent PhaseType ProgressIndicator ProgressIndicatorType Status TotalAppDevices TotalChannels TotalConnections TotalNvMts TotalRouters ClassId Summary Identifies the object class of this object.
PAGE 797
CurrentPhaseNumber Summary An Integer indicating the current phase of the database recovery process. Availability Local, full, and lightweight clients. Syntax phaseNumValue = rsObject.CurrentPhaseNumber Element Description phaseNumValue The current phase number as an integer. Valid values from this property are 0 to the value in the NumberPhases property. This value can be used in conjunction with the NumberPhases property to provide a rough estimate of progress in the database recovery operation.
PAGE 798
NumbersPhases Summary The number of phases in the database recovery operation. This value can be used in conjunction with the CurrentPhaseNumber property to provide a rough estimate in the progress of a database recovery operation. Availability Local, full, and lightweight clients. Syntax itemsValue = rsObject.ItemsInPhase Element Description numPhaseValue The number of phases in the database recovery operation. rsObject The RecoveryStatus object to be acted on. Data Type Integer.
PAGE 799
Element Description phaseTypeValue The current phase.
PAGE 800
7 lcaClassIdAppDevice 9 lcaClassIdRouter 18 lcaClassIdConnections 22 lcaClassIdMessageTag 24 lcaClassIdNetworkVariable rsObject The RecoveryStatus object to be acted on. Data Type Long. Read/Write Read only. Added to API Prior to LNS Release 3.0. ProgressIndicatorType Summary Indicates the object type by which the status of a database recovery process will be measured. This property determines the units for the ItemsInPhase and ProgressIndicator properties.
PAGE 801
Syntax progIndicTypeValue = rsObject.ProgressIndicatorType Element Description rsObject The RecoveryStatus object to be acted on. statusValue The status of the database recovery process. The values for this element, which are contained in the ConstRecoveryStatus constant, are as follows: 0 1 2 3 lcaRecoveryStatusNone lcaRecoveryStatusActive lcaRecoveryStatusPending lcaRecoveryStatusComplete Data Type Integer. Read/Write Read only. Added to API Prior to LNS Release 3.0.
PAGE 802
Syntax totalChannelsValue = rsObject.TotalChannels Element Description rsObject The RecoveryStatus object to be acted on. totalChannelsValue The total number of channels discovered as a long. A value of -1 indicates that the number is unknown. Data Type Long. Read/Write Read only. Added to API Prior to LNS Release 3.0. TotalConnections Summary The total number of Connections reconstructed during the recovery. Availability Local, full, and lightweight clients.
PAGE 803
Data Type Long. Read/Write Read only. Added to API Prior to LNS Release 3.0. TotalRouters Summary The total number of Routers discovered during the recovery. Availability Local, full, and lightweight clients. Syntax totalRoutersValue = rsObject.TotalRouters Element Description rsObject The RecoveryStatus object to be acted on. totalRoutersValue The total number of routers discovered as a long. A value of -1 indicates that the number is unknown. Data Type Long. Read/Write Read only.
PAGE 804
• • • • • • • • • • • • • • CommissionStatus Description Extensions FarSide Handle IconFilePath InitialAuthenticationKey Location Name NearSide Parent PingClass State Subsystems Methods The Router object contains the following methods. • • • • • • • • • • • Commission CommissionEx Decommission MoveEx PostMove PreMove Reboot Replace ReplaceEx Reset Test Commission Summary Associates a Router object with a physical router, and loads the router’s network image.
PAGE 805
device has authentication enabled. If the InitialAuthenticationKey is set prior to commissioning the device or router, OpenLNS will use this key to authenticate messages sent to the device or router during the commissioning process. See the OpenLNS Programmer’s Guide for more information on the steps you should take when installing devices on a network and commissioning those devices. Availability Local, full, and lightweight clients. Syntax object.
PAGE 806
(1). 1 lcaCommissionFlagPropagate Propagates the device’s network image in the OpenLNS database to the physical device when the network management mode is set to lcaMgmtModeDeferConfigUpdates (1). If this will cause network inconsistencies, OpenLNS will defer the updates, and the NS, #4039 lcaErrNsUpdatesDeferred exception will be thrown.
PAGE 807
session before using the MoveEx method. This will allow your application to avoid some failure scenarios that may occur when routers are moved. Availability Local, full, and lightweight clients. Syntax routerObject.MoveEx newChannelObject, newSubnetObject, flags Element Description routerObject The router to be moved from channel to channel. oldNearChannel The old near side channel for the router. oldFarChannel The old far side channel for the router.
PAGE 808
move, this information is lost, and the router will be put online. Added to API Prior to LNS Release 3.0. PostMove Summary Completes the move of a router from one channel to another. As part of the move, the router’s network address may change; however, the router’s Handle property cannot change. To move a router from one channel to another, follow these steps: 1. Invoke the BeginSession method to begin a session.
PAGE 809
PostMove method to move a router while in engineered mode. See the PostMove method for more information on the steps required to move a router. Availability Local, full, and lightweight clients. Syntax routerObject.PreMove newNearChannel, newFarChannel Added to API Element Description routerObject The router to be moved from channel to channel. newNearChannel The new near side channel for the router. newFarChannel The new far side channel for the router. Prior to LNS Release 3.0.
PAGE 810
the same explicit transaction as the invocation of this method. Availability Local, full, and lightweight clients. Syntax object.Replace Added to API Element Description object The Router to be replaced. Prior to LNS Release 3.0. ReplaceEx Summary Replaces one router with another. This method is typically used to effect repair operations. The new router receives the same network address and routing configuration as the old router.
PAGE 811
lcaMgmtModePropagateConfigUpdate s (0). If the network management mode is set to lcaMgmtModePropagateConfigUpdate s (0) when you call the ReplaceEx method, the network image contained in the database will be propagated to the new router and the old router will be deconfigured, regardless if this option has been set. Added to API Prior to LNS Release 3.0. Reset Summary Sends a reset command to the router. Availability Local, full, and lightweight clients. Syntax object.
PAGE 812
normal, and can be expected while the management mode is lcaMgmtModeDeferConfigUpdates (1). These discrepancies will typically be resolved automatically when the system manage mode has been changed to lcaMgmtModePropagateConfigUpdates (0). For more information on the Test method, see the Detecting Devices and Detecting Device Failures section in the OpenLNS Programmer’s Guide. Availability Local, full, and lightweight clients. Syntax testStatus = routerToTest.
PAGE 813
subnet/node addressing, but could not communicate with the router using Neuron ID addressing. However, through the use of subnet/node addressed messages, the OpenLNS Server has verified that the router contains the expected Neuron ID. This might be caused by intermittent router or channel failures. You may want to retry this method to see if the error persists.
PAGE 814
could be caused by attaching a new router to the network which was previously configured as part of another network or by two networks sharing the same media and domain ID. This condition could also occur if the unexpected router was supposed to be removed from the system, but the OpenLNS Server was unable to update the router’s network image during a Remove method; meanwhile, the removed subnet/node address has been reused for the router being tested.
PAGE 815
match the database. This result will be returned if the router’s domain address has not been configured. 10 lcaTestResultNoNeuronId The router has not been assigned a Neuron ID. 11 lcaTestResultMismatchProgramId The OpenLNS Server was able to communicate with the router using both Neuron ID and subnet/node addressing. However, the router does not contain the expected program ID. The router’s program ID may have been changed by its application program.
PAGE 816
reconfigured by another network management tool, or the router may be faulty. It may be possible to restore the router using the Commission method. 14 lcaTestResultAuthDisabled The OpenLNS Server was able to communicate with the router using both Neuron ID addressing and subnet/node addressing. However, the router has network management authentication disabled despite the fact that the router's AuthenticationEnabled property is set to TRUE.
PAGE 817
object by calling the System.NetworkServiceRouter.Rout er.Commission method, and make sure that the State property of the NetworkServiceDevice object (NetworkServiceDevice.Router.State) is set to lcaOnline. 18 lcaTestResultInterfaceConfigError The OpenLNS network interface that the OpenLNS Server is attempting to use is not property configured. Recommission the NetworkServiceDevice of the System object by calling the System. NetworkServiceDevice.Router.Comm ission method.
PAGE 818
Syntax returnValue = object.Count Element Description attachmentStatu s The attachment status of the router. The values for this element, which are stored in the ConstDeviceAttachmentStatus constant, are as follows: 0 lcaDeviceAttached Indicates that the router that triggered the event is now attached and in the proper state. 1 lcaDeviceInImproperState Indicates that the router that triggered the event is now attached but not in the proper state.
PAGE 819
Full client remains connected to the server. 3. Set the AuthenticationEnabled property to True the AppDevice objects that will use authentication. Disabling Authentication To disable authentication for all the devices in a system, follow these steps: 1. Set the AuthenticationEnabled property to False on the AppDevice object that represents the System object’s NetworkServiceDevice. This disables authentication for all application devices, routers and Network Service Devices operating on the system. 2.
PAGE 820
Added to API Prior to LNS Release 3.0. BitmapFilePath Summary Specify the path and file name of a bitmap (*.BMP file) representation of the object. The bitmap files are used to store object images which may be accessed by a director level LNS component application. A bitmap may be of any size, although the recommended dimensions are 40x80 pixels. See the IconFilePath property for related information. Availability Local clients. Syntax bmpFilePath = object.
PAGE 821
lcaLearningRouter (1) value to this property, it will automatically be converted to lcaConfiguredRouter (0). A permanent repeater or bridge cannot be changed to a non-permanent class. Similarly, a non-permanent class cannot be changed to a permanent repeater or bridge. routerObject The Router object to be acted on. Data Type Integer. Read/Write Read only. Added to API Prior to LNS Release 3.0. ClassId Summary Identifies the object class of this object.
PAGE 822
Syntax commStatusValue = object.CommissionStatus Element Description object The router object to be acted on. commStatusValu e The commission status of this router. The values for this element, which are stored in the commStatusValue constant, are as follows: 0 lcaCommissionUpdatesCurrent No outstanding commission updates are pending. 1 lcaCommissionUpdatesPending Commission updates are currently pending, or in progress.
PAGE 823
Data Type String. Read/Write Read/write. Added to API This depends on the object used to access the property. Generally, this property exists for the objects listed above as soon as they are added to the API. See the applicable object to determine what release it was introduced in. Extensions Summary Contains the Extensions collection object associated with the specified Router. This property returns an Extensions collection.
PAGE 824
Read/Write Read-only. Added to API Prior to LNS Release 3.0. Handle Summary Contains the handle associated with the Router object. An OpenLNS Object that is part of a collection is assigned an index corresponding to its position within that collection. This index may be used when invoking the Item property and may also be read using the Index property. You can also use the ItemByHandle method to retrive Router objects. Availability Local, full, and lightweight clients. Syntax returnValue = object.
PAGE 825
InitialAuthenticationKey Summary Contains the initial authentication key to be used when commissioning a router. This property must be set prior to commissioning a router that has network management authentication enabled, and has been previously commissioned outside of OpenLNS, or commissioned on a different OpenLNS network. In these circumstances, OpenLNS will not be able to communicate with the router without knowing its authentication key because the router has authentication enabled.
PAGE 826
Data Type String (6 bytes). Read/Write Read only. Added to API Prior to LNS Release 3.0. Name Summary Specifies the name of an object as a character string. This property is case sensitive. Searches by name must match case. This property can be a maximum of 85 characters long, but it may not contain the forward slash (/), back slash (\), period (.), and colon (:) characters. Availability Local, full, lightweight, and independent clients.
PAGE 827
Read/Write Read-only. Added to API Prior to LNS Release 3.0. Parent Summary Returns the object that spawned the current child object. The parent object is determined by the means in which a child object is accessed, not by the OpenLNS Object hierarchy. For example, an AppDevice object's parent can be a NetworkServiceDevice object or a AppDevices collection object Availability Local, full, lightweight, and independent clients.
PAGE 828
property, OpenLNS will use the default lcaPingClassStationary (3) value. 1 lcaPingClassMobile Class for nodes which move frequently. 2 lcaPingClassTemporary Class for temporary nodes. 3 lcaPingClassStationary Class for nodes which rarely move. This is the default value. 4 lcaPingClassPermanent Class for nodes which never move. Note: You change the ping interval that applies to each class with the System object's PingIntervals property. Data Type Integer. Read/Write Read/write.
PAGE 829
properties are read-only. 2 lcaStateUncnfg The application is loaded but the configuration is either not loaded, being reloaded, or deemed corrupted due to a configuration checksum error. A Neuron Chip also can make itself unconfigured by calling the Neuron C function go_unconfigured(). The router's service LED flashes at a one second rate in this state.
PAGE 830
Data Type Integer. Read/Write Read /write. Added to API Prior to LNS Release 3.0. Subsystems Summary Contains the Subsystems collection object associated with the specified Router. A Subsystem object can in turn contain a collection of Subsystems. Subsystems collection objects accessed through Router objects represent the Subsystems that contain the specified Router. Availability Local, full, and lightweight clients. Syntax subsystemCollection = object.
PAGE 831
Methods The Routers object contains the following methods. • • • • • • • Add AddEx AddReference ItemByHandle ItemByNeuronID Remove RemoveEx Add Summary Defines a new Router object. A router consists of two halves, NearSide and FarSide. This method adds a router to the system, but does not install the physical router. The Commission method is used to install the physical router after that router is defined using this method.
PAGE 832
routerType An Integer value indicating the router type. The valid class values, which are contained in the ConstRouterClasses constant, are as follows: 0 lcaConfiguredRouter 1 lcaLearningRouter (*see notes) 2 lcaRepeater 3 lcaBridge 4 lcaPermanentRepeater 5 lcaPermanentBridge Notes: The lcaLearningRouter (1) value is not supported by OpenLNS. If you write the lcaLearningRouter (1) value to this property, it will automatically be converted to lcaConfiguredRouter (0).
PAGE 833
nearChannel The Channel object for the router's near channel. farChannel The Channel object for the router's far channel. routerType An Integer value indicating the router type. The valid class values, which are contained in the ConstRouterClasses constant, are as follows: 0 1 2 3 4 5 lcaConfiguredRouter lcaLearningRouter (*see notes) lcaRepeater lcaBridge lcaPermanentRepeater lcaPermanentBridge Notes: The lcaLearningRouter (1) value is not supported by OpenLNS.
PAGE 834
network management mode is set to lcaMgmtModePropagateConfigUpdate s (0). Added to API Prior to LNS Release 3.0. AddReference Summary Adds a Router object reference to a Routers collection. This method can be used to add an existing Router to multiple Subsystem objects (by invoking this method on the Routers collection in those Subsystem objects).
PAGE 835
Routers collection. Added to API coll The Routers collection object. handle A Long value specifying the handle of the Router object to be retrieved. LNS Release 3.0. ItemByNeuronID Summary Retrieves a Router object, specified by its NeuronID property, from a Routers collection. Availability Local, full, and lightweight clients. Syntax object = coll.ItemByNeuronId(neuronId) Added to API Element Description object The Router retrieved from the collection. coll The Routers collection object.
PAGE 836
the router to be removed. indexName Added to API A Long value specifying the collection index of the Router object to remove, or a String value specifying the name of the Router object to remove. Prior to LNS Release 3.0. RemoveEx Summary This method is identical to the Remove method of the Routers collection, but it allows you to set additional options when removing a router from the collection. Availability Local, full, and lightweight clients. Syntax routersColl.
PAGE 837
s (0). Added to API Prior to LNS Release 3.0. Properties The Routers object contains the following properties: • • • • ClassId Count Item _NewEnum ClassId Summary Identifies the object class of this object. This property allows the object type to be determined when it is unknown (for example, when the object was accessed using the Parent property of another object). Availability Local, full, lightweight, and independent clients.
PAGE 838
object The collection object to be acted on. Data Type Long. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. Item Summary Returns a Router object from a Routers collection. You can retrieve a Router object from its Routers collection by passing its index (ordinal position) within that collection as the argument for the Item property. Index values start at 1.
PAGE 839
you do not need to use the _NewEnum property because it is automatically used in the implementation of For Each ... Next statements. • If you are developing your OpenLNS app in C#, you do not need to use the _NewEnum property explicitly because it is automatically used in the implemention of foreach statements. Availability Local, full, and lightweight clients. Syntax retrievedObject = collObject._NewEnum Element Description retrievedObject An expression that evaluates to the object retrieved.
PAGE 840
Methods The RouterSide object contains the following method. • ClearStatus ClearStatus Summary Clears the status information stored in the router side. The clear status method causes a LonTalk Clear Status network diagnostic message to be sent to the specified router side. This clears the error log, last reset cause, and communication counters, which are generally accessed by reading the router side's DetailInfo object. Availability Local, full, and lightweight clients. Syntax object.
PAGE 841
The maximum buffer size for a router side is determined when the router's external interface file is imported. No changes may be made to a RouterSide object's BufferConfiguration property, which would cause the total memory usage value to be exceeded. If the router was defined without specifying an external interface, OpenLNS will not be able to determine much memory the router has, and will not allow any changes to the BufferConfiguration property.
PAGE 842
ClassId Summary Identifies the object class of this object. This property allows the object type to be determined when it is unknown (for example, when the object was accessed using the Parent property of another object). Availability Local, full, lightweight, and independent clients. Note that some objects containing this property are not available to Independent clients. Syntax classIdValue = object.ClassId Element Description classIdValue The object class of the object.
PAGE 843
LastTestInfo Summary Contains the TestInfo object containing the results of the last time the Test method was called for this router side. The AuxResultData property indicates which properties of the LastTestInfo object contain useful information. Availability Local, full, and lightweight clients. Syntax lastTestInfo = adObject.LastTestInfo Element Description lastTestInfo The TestInfo object containing the last test results.
PAGE 844
Element Description nodeIdValue The NodeId of the object. object The RouterSide object to be acted on. Data Type Integer. Read/Write Read/write. Added to API Prior to LNS Release 3.0. Parent Summary Returns the object that spawned the current child object. The parent object is determined by the means in which a child object is accessed, not by the OpenLNS Object hierarchy. Availability Local, full, lightweight, and independent clients.
PAGE 845
Data Type String. Read/Write Read only. Added to API LNS Release 3.0. Priority Summary Determines the router side’s priority assignment on its channel. An assignment of 0 indicates that the object is not assigned a priority slot. If the object is not assigned a priority slot, messages with priority will still use priority buffers, and will still be sent before messages without priority.
PAGE 846
the following format: FM:MM:MM:CC:CC:UU:TT:NN Note: You may not use colons when writing the program ID. For a device with a program ID of 80:00:01:01:28:80:04:02, you can write 8000010128800402 in this property. See the Devices Interfaces section in the OpenLNS Programmer’s Guide for a description of the format used to display program IDs. Availability Local, full, and lightweight clients. Syntax programIdValue = object.ProgramId Element Description programIdValue The program ID value of the object.
PAGE 847
properties are read-only. 2 lcaStateUncnfg The application is loaded but the configuration is either not loaded, being reloaded, or deemed corrupted due to a configuration checksum error. A Neuron Chip also can make itself unconfigured by calling the Neuron C function go_unconfigured(). The device's service LED flashes at a one second rate in this state.
PAGE 848
mode). The device's service LED is off in this state. object The RouterSide object to be acted on. Data Type Integer. Read/Write Read/write. Added to API Prior to LNS Release 3.0. SubnetId Summary Contains the ID of the subnet. The RouterSide object's SubnetId property identifies the subnet the device is part of. This property can be used in conjunction with the NodeId property to uniquely identify a device. Note: As of OpenLNS, you can write to this property.
PAGE 849
ServiceStatus A ServiceStatus object contains the status of the current service request for the System object. This object contains information regarding whether a service is waiting for a resource such as a transaction, (if so, which resource and how many other services are ahead of this one) or if a service is proceeding.
PAGE 850
classIdValue The object class of the object. The following value is defined for the ServiceStatus object in the ConstClassIds constant: 85 lcaClassIdServiceStatus object The object to be acted on. Data Type Integer. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. Parent Summary Returns the object that spawned the current child object.
PAGE 851
QueuePosition Summary Indicates the numbed of transactions that must be started and completed before this service can be executed. If the ServiceStatus object's Status property is set to lcaSrvcQueued, this property will indicate the number of unstarted transactions that need to be completed before this one. For example, if this property is set to 0, the service will start as soon as the current transaction is completed.
PAGE 852
indicates the number of unstarted transactions that must be completed before the service can execute. 1 lcaResServicePin Reserved for future use. The ServiceStatus object to be acted on. serviceStatusObject Data Type Integer. Read/Write Read only. Added to API LNS Release 3.0. Status Summary Indicates the status of the service that the System is currently executing. Availability Local, full, and lightweight clients. Syntax statusValue = ssObject.
PAGE 853
The service is unable to execute do to a communications failure. statusValue Data Type Integer. Read/Write Read only. Added to API LNS Release 3.0. The status of this service. SourceAddress The SourceAddress object is used to indicate the source device of an update reported by the OnMsgMonitorPointUpdateEvent or OnNvMonitorPointUpdateEvent events.
PAGE 854
ClassId Summary Identifies the object class of this object. This property allows the object type to be determined when it is unknown (for example, when the object was accessed using the Parent property of another object). Availability Local, full, lightweight, and independent clients. Note that some objects containing this property are not available to Independent clients. Syntax classIdValue = object.ClassId Element Description classIdValue The object class of the object.
PAGE 855
Added to API LNS Release 3.0. NodeId Summary Contains the node ID of the device that generated the network variable or message monitor point update. Availability Local, full, and lightweight clients. Syntax nodeIdValue = object.NodeId Element Description nodeIdValue The NodeId of the object. object The SourceAddress object to be acted on. Data Type Integer. Read/Write Read only. Added to API Prior to LNS Release 3.0.
PAGE 856
Summary Contains the subnet ID of the device that generated the network variable or message monitor point update. A device's SubnetId property identifies the subnet on which the device resides. This property can be used in conjunction with the NodeId property to uniquely identify a device. Availability Local, full, and lightweight clients. Syntax returnValue = object.SubnetId Element Description returnValue The subnet ID of the device. object The SourceAddress to be acted on. Data Type Integer.
PAGE 857
Methods The Subnet object does not contain any methods. Properties The Subnet object contains the following properties. • • • • • • • • • BitmapFilePath ClassId Description DomainId Extensions IconFilePath Name Parent SubnetId BitmapFilePath Summary Specify the path and file name of a bitmap (*.BMP file) representation of the object. The bitmap files are used to store object images which may be accessed by a director level LNS component application.
PAGE 858
Independent clients. Syntax classIdValue = object.ClassId Element Description classIdValue The object class of the object. The following value is defined for the Subnet object in the ConstClassIds constant: 16 lcaClassIdSubnet object The object to be acted on. Data Type Integer. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API.
PAGE 859
The Subnet object. subnetObject Data Type String. Read/Write Read only. Added to API Prior to LNS Release 3.0. Extensions Summary Contains the Extensions collection object associated with the specified Subnet. This property returns an Extensions collection. The objects in this collection represent user data reserved for manufacturers. Each object is identified with a unique identifier set by the manufacturer Availability Local, full, lightweight, and independent clients.
PAGE 860
• • • Added to API Small (16x16) with 16 colors Monochrome (32x32) Large (48x48) with 256 colors Prior to LNS Release 3.0. Name Summary Specifies the name of an object as a character string. This property is case sensitive. Searches by name must match case. This property can be a maximum of 85 characters long, but it may not contain the forward slash (/), back slash (\), period (.), and colon (:) characters. Availability Local, full, lightweight, and independent clients.
PAGE 861
Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. SubnetId Summary Contains the ID of the subnet. Availability Local, full, and lightweight clients. Syntax returnValue = object.SubnetId Element Description returnValue The subnet ID of the device. object The Subnet to be acted on. Data Type Integer. Read/Write Read only. Added to API Prior to LNS Release 3.0.
PAGE 862
Methods The Subnets object contains the following methods. • • Add Remove Add Summary Defines a new Subnet object. Subnets are typically added automatically when routers or devices are added. In most cases there is no reason for your application to manually allocate subnets. Subnets can be explicitly added using this method. You can then force a given set of devices onto the same subnet with the MoveEx method take advantage of subnet broadcast messaging.
PAGE 863
Added to API Prior to LNS Release 3.0. Properties The Subnets object contains the following properties: • • • • • ClassId Count Item Parent _NewEnum ClassId Summary Identifies the object class of this object. This property allows the object type to be determined when it is unknown (for example, when the object was accessed using the Parent property of another object). Availability Local, full, lightweight, and independent clients.
PAGE 864
object The collection object to be acted on. Data Type Long. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. Item Summary Returns a Subnet object from a Subnets collection. You can retrieve a Subnet object from its Subnets collection by passing its index (ordinal position) within that collection as the argument for the Item property. Index values start at 1.
PAGE 865
clients. Syntax parentObject = object.Parent Element Description parentObject The object that is the parent of the specified object. object Any object for which the parent is desired. Data Type Object. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. _NewEnum Summary Enables you to iterate over the objects in a collection using For Each ... Next statements.
PAGE 866
Subsystem The Subsystem object represents a logical grouping of devices and routers. Subsystems may be hierarchical. Each user-defined subsystem may itself contain additional user-defined subsystems. The System object's Subsystems collection contains the top-level subsystems in the user's subsystem hierarchy plus two pre-defined subsystems: the ALL and the Discovered subsystem.
PAGE 867
Note: The name of a top-level Subsystem can not be the same as the System object's name. See the Path property for more information. The following table summarizes the Subsystem object. Description Represents a logical grouping of devices and routers. Added to API Prior to LNS Release 3.0. Accessed Through Subsystems property. Default Property Name. Methods None.
PAGE 868
Syntax appDevicesCollection = object.AppDevices Element Description appDevicesCollection The AppDevices collection returned. object The Subsystem object to be acted on. Data Type AppDevices collection object. Read/Write Read only. Added to API Prior to LNS Release 3.0. BitmapFilePath Summary Specify the path and file name of a bitmap (*.BMP file) representation of the object. The bitmap files are used to store object images which may be accessed by a director level LNS component application.
PAGE 869
Subsystem object in the ConstClassIds constant: 5 lcaClassIdSubsystem object The object to be acted on. Data Type Integer. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. Description Summary Stores description information about the Subsystem object. Availability Local, full, lightweight, and independent clients.
PAGE 870
Read/Write Read only. Added to API Prior to LNS Release 3.0. Handle Summary Contains the handle associated with the Subsystem object. An OpenLNS Object that is part of a collection is assigned an index corresponding to its position within that collection. This index may be used when invoking the Item property. Some OpenLNS Objects are tracked internally by the OpenLNS Server using a unique handle. You can fetch objects using the ItemByHandle method. Availability Local, full, and lightweight clients.
PAGE 871
Name Summary Specifies the name of an object as a character string. This property is case sensitive. Searches by name must match case. This property can be a maximum of 85 characters long, but it may not contain the forward slash (/), back slash (\), period (.), and colon (:) characters. Availability Local, full, lightweight, and independent clients. Note that some objects that contain this property are not available to Independent clients. Syntax stringValue = object.
PAGE 872
Path Summary Contains the full system and subsystem pathname for this subsystem. Pathnames may be used in place of names when fetching Subsystem objects from the System's Subsystems collection via the Item property. The pathname for a subsystem is the system name and the subsystem hierarchy leading to that subsystem, with all names separated by periods. The system name is optional. An example pathname is MySystem.Discovered.Installed.
PAGE 873
Element Description object The Subsystem object to be acted on. routersCollection The Routers collection returned. Data Type Routers collection object. Read/Write Read only. Added to API Prior to LNS Release 3.0. Subsystems Summary Contains the Subsystems collection object associated with the specified Subsystem object. A Subsystems collection accessed through a Subsystem object can be used to represent and define subsystem hierarchy.
PAGE 874
The Subsystems collection accessed through the ALL subsystem contains all objects in the network database, including the subsystems in the system that are managed by the LNS client applications. This includes transient objects that OpenLNS uses that should not be accessed by client applications. In general, you should not use the ALL subsystem. The following table summarizes the Subsystems object. Description A collection of Subsystem objects. Added to API Prior to LNS Release 3.0.
PAGE 875
Syntax Added to API subsystemObject = subsystemsColl.Add(subsystemName) Element Description subsystemObject The newly defined Subsystem object. subsystemsColl The Subsystems collection object. subsystemName A String containing the name of the Subsystem. Prior to LNS Release 3.0. ItemByHandle Summary Retrieves a Subsystem object, specified by its handle, from a Subsystems collection. Availability Local, full, and lightweight clients. Syntax object = coll.
PAGE 876
Properties The Subsystems object contains the following properties: • • • • • ClassId Count Item Parent _NewEnum ClassID Summary Identifies the object class of this object. This property allows the object type to be determined when it is unknown (for example, when the object was accessed using the Parent property of another object). Availability Local, full, lightweight, and independent clients. Note that some objects containing this property are not available to Independent clients.
PAGE 877
Data Type Long. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. Item Summary Returns a Subsystem object from a Subsystems collection. You can retrieve a Subsystem object from its Subsystems collection by passing its index (ordinal position) within that collection as the argument for the Item property. Index values start at 1.
PAGE 878
Element Description parentObject The object that is the parent of the specified object. object Any object for which the parent is desired. Data Type Object. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. _NewEnum Summary Enables you to iterate over the objects in a collection using For Each ... Next statements.
PAGE 879
Added to API Prior to LNS Release 3.0. Accessed Through Systems collection object. Default Property Name.
PAGE 880
• • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • ClassId ClientId CommissionedDeviceCount ComponentApps Connections CurrentAccount CurrentDeviceCount CustomerId DebugTraceFlag Description DiscoveryInterval DiscoveryLimitedFlag DomainId DsPollInterval DsPriority DsRepeatTimer DsRetries DsRetryCount DsTxTimer Extensions FileTransfer Handle HostTimer ImportDirectory InstallOptions IsOpen LastError LaunchLcaServerFlag LdrfCatalogPath LdrfLanguages MgmtMode
PAGE 881
• • UninstalledDeviceCount UpdateInterval Methods The System object contains the following methods: • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • BeginAttachmentEvent BeginChangeEvent BeginCommissionEvent BeginLicenseEvent BeginLonMarkObjectStatusChangeEvent BeginMissedEvent BeginNodeConnChangeEvent BeginNodeIntfChangeEvent BeginNssIdleEvent BeginServicePinEvent BeginSession BeginSystemMgmtModeChangeEvent CancelTransaction Close CommittTransaction DeconfigNetwork Dis
PAGE 882
object type. To begin events for device and router attachments, you must call this method twice: once with the lcaAppDeviceEvent parameter, and once with the lcaRouter parameter. Availability Local, full, and lightweight clients. Syntax systemObject.BeginAttachmentEvent objectType Element Description systemObject The System object to be acted on. objectType An integer determining the object type for which to begin attachment events.
PAGE 883
object type. Availability Local, full, and lightweight clients. Syntax systemObject.BeginCommissionEvent objectType Element Description systemObject The System object to be acted on. objectType An integer determining the object type for which commission events will be enabled. The possible values for this element, which are contained in the ConstDeviceEventTypes constant, are as follows: 0 lcaAppDeviceEvent 1 lcaRouterEvent Added to API Prior to LNS Release 3.0.
PAGE 884
Syntax Added to API systemObject.BeginMissedEvent Element Description systemObject The System object to be acted on. Prior to LNS Release 3.0. BeginNodeConnChangeEvent Summary Enables the OnNodeConnChangeEvent for a system. Availability Local, full, and lightweight clients. Syntax systemObject.BeginNodeConnChangeEvent Added to API Element Description systemObject The System object to be acted on. Prior to LNS Release 3.0.
PAGE 885
this element is 0–65,535. Added to API Prior to LNS Release 3.0. BeginServicePinEvent Summary Enables the OnSystemServicePin event for a system. An event tag is returned from the method. Multiple service pin events can be enabled at one time, each having a different tag. When the service pin event is fired, the event tag is returned as one of the parameters. Availability Local, full, and lightweight clients. Syntax eventTag = systemObject.
PAGE 886
validated until the session is ended. The only network operations you can perform within sessions are those related to changes in the physical topology of your network. These operations include moving devices and routers, adding and removing routers, and setting the class of routers. As a result, the methods you can use within a session include the following: PreMove, MoveEx, PostMove, Add, and Remove. You can also write to the Class property of a router.
PAGE 887
CancelTransaction Summary Cancels an active transaction. When a transaction is canceled, either explicitly because of a reset, all network and database updates made since the call to the StartTransaction method are reversed. Once a transaction has been committed, it can no longer be cancelled.
PAGE 888
engineered system mode). Closing the system does not turn off monitor set monitoring and control. Monitor set monitoring and control continues until the Network object calls its Close method. Availability Local, full, and lightweight clients. Syntax systemObject.Close Added to API Element Description systemObject The System object to be closed. Prior to LNS Release 3.0. CommittTransaction Summary Commits the current transaction.
PAGE 889
discovery process (see the DiscoveryInterval property). Devices do not have to be installed by the OpenLNS Server to be deconfigured; however the following must be true: • The devices’ domain IDs must match the domain IDs referenced by the domainTypes or explicitDomain elements passed to this method. • The devices must be in the configured online or soft offline state. • The devices must not be authenticated.
PAGE 890
broadcast is used, all deconfigured devices will log a configuration checksum error (CNFG_CS_ERROR = 153) in their Neuron error log (see the DetailInfo object). This method does not deconfigure the OpenLNS Server's NetworkServiceDevice. In fact, the OpenLNS Server is not required to be configured on the domain whose devices will be deconfigured. During execution of the DeconfigNetwork method, the OpenLNS Server's local NSI will be configured on the specified domain.
PAGE 891
255 lcaExcludedDevTypeAll None of the above devices will be deconfigured. You can logically OR these constants to combine their effects. domainTypes An Integer value indicating the types of domains to be deconfigured. The valid values for this element, which are contained in the ConstDeconfigDomainTypes constant, are as follows: 1 lcaDeconfigDomainCommon Reserved for future use. 2 lcaDeconfigDomainAppl Use the DomainId property of the System object to execute this method.
PAGE 892
If a host-based device whose application is not running is installed on the network, OpenLNS may or may not be able to discover it. Whether OpenLNS can discover and register the device depends on how much of the device's LonTalk protocol stack is running at the time of the discovery. Discovering a device involves first the actual discovery of the device and then the registration of that device in the database.
PAGE 893
registration is used, an error will cause all device registrations to fail. If registration is done in the background, the background registration tasks are performed outside of the scope of the explicit transaction, so a registration failure will only impact the effected device. The other registration tasks will continue to completion (provided no additional errors occur). If the specified domainId string is an empty string, the OpenLNS Server will perform the discovery on the zero-length domain.
PAGE 894
This method resynchronizes the network. It should be called every 3 to 5 seconds. This method must be used for event synchronization and missed events to work. If the SetEventSyncMode method has been used to turn off event synchronization and missed events are not being used, this method need not be called. Availability Local, full, and lightweight clients. Syntax object.DoEventSync Added to API Element Description systemObject The System object which is to be synchronized. Prior to LNS Release 3.
PAGE 895
Added to API Prior to LNS Release 3.0. EndAttachmentEvent Summary Disables the OnAttachmentEvent for a system for a given object type. To end events for device and router attachments, you must call this method twice: once with the lcaAppDeviceEvent parameter, and once with the lcaRouter parameter. Availability Local, full, and lightweight clients. Syntax systemObject.EndAttachmentEvent objectType Element Description systemObject The System object to be acted on.
PAGE 896
Added to API Prior to LNS Release 3.0. EndCommissionEvent Summary Disables the OnCommission event for a system for a given object type. Availability Local, full, and lightweight clients. Syntax systemObject.EndCommissionEvent objectType Element Description systemObject The System object to be acted on. objectType An integer determining the object type for which commission events will be disabled.
PAGE 897
Added to API Prior to LNS Release 3.0. EndNodeConnChangeEvent Summary Disables the OnNodeConnChangeEvent for a system. Availability Local, full, and lightweight clients. Syntax systemObject. EndNodeConnChangeEvent Added to API Element Description systemObject The System object to be acted on. Prior to LNS Release 3.0. EndNodeIntfChangeEvent Summary Disables the OnNodeIntfChangeEvent for a system. Availability Local, full, and lightweight clients. Syntax systemObject.
PAGE 898
This event tag must be the one returned by the BeginServicePinEvent method. Added to API Prior to LNS Release 3.0. EndSession Summary Ends a session for methods and properties that must be grouped to avoid intermediate error conditions. All methods invoked and properties written between the BeginSession and EndSession methods are considered atomic.
PAGE 899
ExtensionByHandle Summary Retrieves an Extension object by its handle property. Extension records are defined for OpenLNS objects such as the Channel, DeviceTemplate, AppDevice, Subnet, Subsystem, LonMarkObject, and Router objects. You can use the ExtensionByHandle method of the System object to get an Extension object in the network database through its handle property—regardless of the collection containing the Extension object.
PAGE 900
of the local client ( for example "192.168.0.3"). Added to API Prior to LNS Release 3.0. GetProgramId Summary Returns the program ID contained within a specified external interface (XIF) file. You can only use this method with a text-based XIF (.XIF extension). You can not use it with a binary XIF (.XFB extension). Availability Local, full, and lightweight clients. Syntax programID = systemObject.GetProgId(XifPath ) Added to API Element Description programID A String containing the program ID.
PAGE 901
of the network interface is created. The value of the DomainId property cannot be changed if any devices have been commissioned. InstallOptions lcaPrivateMedia If this method is being invoked by a remote client, the application program needs to manage several additional properties. If the remote connection uses network management authentication, you must set the AuthenticationKey property before invoking this method. In addition, this method will set the Ping class for this client to Permanent.
PAGE 902
object’s NetworkServiceDevice object to identify the network interface for the new network. 3. Call the PrepareToRecoverFromNetwork method. Note that the Network object must be newly created; if objects have been added after creation, an error will result. 4. Call the Open method of the System object.
PAGE 903
Layer 2 network interface, an exception will be thrown. FALSE. OpenLNS will read the domain signature from the DomainId property. In this case, you should make sure the DomainId property is set to a valid value. Added to API Prior to LNS Release 3.0. RecoverFromNetwork Summary Recovers the OpenLNS database from the physical network.
PAGE 904
MgmtMode property will be set to lcaMgmtModeDeferConfigUpdates (1). You will need to set the property to lcaMgmtModePropagateConfigUpdates (0) before resuming normal operations. If the recovery operation is aborted (by the computer being turned off, for example), it is possible to resume recovery. To do this, follow these steps: 1. Call the Open method of the Network object on the appropriate network. 2. Call the Open method of the System object. 3.
PAGE 905
lcaRecoveryOptSmallNetwork Assume that the network is a small or medium sized network. This causes database recovery to use domain wide broadcast when discovering application nodes. This may not work if the system is very large, as the number of responses from the devices would overwhelm the network. If not set, the recovery process uses subnet broadcast on each of the 255 subnets, each of which must time out before going on to the next.
PAGE 906
This method cannot be part of an explicit transaction. For more information on explicit transactions, see the StartTransaction method. Normally, updates are only attempted while the network management mode (MgmtMode property) is set to lcaMgmtModePropagateConfigUpdates (0). You can try some updates, however, even while the network management mode is set to lcaMgmtModeDeferConfigUpdates (1).
PAGE 907
The possible values for this parameter, which is contained in the ConstEventSyncModes constant, are as follows: 0 lcaEventNoSyncMode Disables automatic event synchronization. If missed events are enabled, an OnMissedEvent will be sent for every missed event, including the periodic ping event. Missing a ping event will cause an OnMissedEvent to be sent with the isUnrecoverable parameter set to TRUE, and the numMissedEvents parameter set to 0. 1 lcaEventAutoSyncMode Enables automatic event synchronization.
PAGE 908
requests. You only use this parameter if the mode parameter is set to lcaEventAutoSyncMode. Added to API LNS Release 3.0. StartTransaction Summary Starts a transaction for the System object. You should call this method in combination with CommittTransaction to group method invocations and property modifications as part of the same transaction. If a transaction initiated by your client is already in progress for the System when you call this method, an exception will be thrown.
PAGE 909
transactions, see the Using Transactions and Sessions section in the OpenLNS Programmer’s Guide. You can use the OnSystemNssIdle event to allow your application to execute code while lengthy transactions are being performed. For example, you can use the ServiceStatus property to find out if this client is waiting on a transaction started by another client, or you can call CancelTransaction to cancel the operation. For more information on this, see the OnSystemNssIdle event.
PAGE 910
• • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • Description DiscoveryInterval DiscoveryLimitedFlag DomainId DsPollInterval DsPriority DsRepeatTimer DsRetries DsRetryCount DsTxTimer Extensions FileTransfer Handle HostTimer ImportDirectory InstallOptions IsOpen LastError LaunchLcaServerFlag LdrfCatalogPath LdrfLanguages MgmtMode Name NetworkResources NetworkServiceDevice NssDbVersion Parent PermissionString PingIntervals RecoveryStatus RegisterServicePin RemoteChanne
PAGE 911
Availability Local, full, and lightweight clients. Syntax acctsCollection = sysObject.Accounts Element Description acctsCollection The Accounts collection to be returned. sysObject The System object to be acted on. Data Type Accounts collection object. Read/Write Read only. Added to API LNS Release 3.0. ActivationLicense Summary Returns an ActivationLicense object that contains a snapshot of the activation license on the OpenLNS Server at the time it was first accessed.
PAGE 912
Availability Local, full, and lightweight clients. Syntax returnValue = sysObject.ApplicationHandle Element Description returnValue The handle of the application. sysObject The System object to be acted on. Data Type Long. Read/Write Read only. Added to API LNS Release 3.0. ApplicationName Summary The application name used by the Object Server when registering for an application handle with the NSS. If a name is not provided by the application using the Object Server, a default name is used.
PAGE 913
hexadecimal digit of the key. A key of ffff ffff ffff or ffff ffff ffff ffff ffff ffff indicates that authentication is disabled. Remote Full and Lightweight client applications that are connecting to an authenticated network must set this property before opening the system. If the application uses the wrong authentication key, the client must close the System, Network, and ObjectServer objects, re-acquire and re-open the ObjectServer and Network objects, and the re-acquire the System object.
PAGE 914
added to the API. ClientId Summary Contains the ClientId associated with the System object by the Object Server engine. If the OpenLNS application needs to directly invoke the services of the Object Server engine, the ClientId property may be needed depending upon the nature of the service invoked. Availability Local, full, and lightweight clients. Syntax clientIdValue = systemObject.ClientId Element Description clientIdValue The client Id assigned to the System object as a Long.
PAGE 915
Added to API Prior to LNS Release 3.0. ComponentApps Summary Contains the ComponentApps collection object associated with the specified System object. The ComponentApps collection is a list of LNS plug-in commands that are associated with a particular object type. Availability Local, full, and lightweight clients. Syntax appsCollection = object.ComponentApps Element Description appsCollection The ComponentApps collection to be returned. object The System object to be acted on.
PAGE 916
Syntax acctObject = systemObject.CurrentAccount Element Description acctObject The current Account object. systemObject The System object to be acted on. Data Type Account object. Read/Write Read only. Added to API Prior to LNS Release 3.0. CurrentDeviceCount Summary Returns the number of AppDevice objects currently defined, including network service devices. Availability Local, full, and lightweight clients. Syntax deviceCountValue = systemObject.
PAGE 917
Element Description systemObject The System object to be acted on. debugFlag A Boolean value that indicates whether trace should be turned on. TRUE. The trace should be turned on. Trace messages will be stored in the file "lcatrace.txt". FALSE. Trace should not be turned on. Data Type Boolean. Read/Write Read only. Added to API Prior to LNS Release 3.0. Description Summary Stores description information about the System object. Availability Local, full, lightweight, and independent clients.
PAGE 918
(4) sets this property to 180 seconds. Availability Local, full, and lightweight clients. Syntax intervalValue = systemObject.DiscoveryInterval systemObject.DiscoveryInterval = intervalValue Element Description intervalValue The new device discovery interval (in seconds). An interval of 0 turns off background discovery process. Valid values are 1 to 65,534. systemObject The System object to be acted on. Data Type Integer. Read/Write Read/write. Added to API Prior to LNS Release 3.0.
PAGE 919
FALSE. Device discovery has completed execution without being halted or the application has exited. systemObject The System object to be acted on Data Type Boolean. Read/Write Read only. Added to API Prior to LNS Release 3.0. DomainId Summary Identifies the domain ID. The domain ID is stored as a string of hexadecimal digits. For example, a 3-byte domain ID would be represented like this: "32a0cf". Domain IDs can be 1, 3, or 6 bytes in length.
PAGE 920
5. Use service pin, find, or other manual means of obtaining the actual Neuron ID of each device. 6. Iterate through the Discovered.Uninstalled Subsystem object to get the list of devices in the system that require their network images to be updated. If the device’s Neuron ID has not been specified, acquire it using the service pin, find/wink, or manual entry methods. Commission the device using the Commission method. 7. Add and connect any additional devices that are not defined by the basic configuration.
PAGE 921
developing a remote application that uses shared access mode (meaning that the DsMode property is set to lcaDsModeShared), you cannot set the NetworkVariable object’s DsPollInterval property. An exception will be raised if you attempt to do so. The System object's DsPollInterval property sets the default value, which is applied when a NetworkVariable object's DsPollInterval property is left unspecified.
PAGE 922
priorityFlag The priority flag value. TRUE. The Data Server uses priority messaging to update a network variable. FALSE. The Data Server polls a network variable. This is the default. object The System object to be acted on. Data Type Boolean. Read/Write Read/write. Added to API Prior to LNS Release 3.0. DsRepeatTimer Summary Sets the interval between repeated transmissions for messages sent using the unacknowledged/repeat message service.
PAGE 923
8 9 10 11 12 13 14 15 0.256 0.384 0.512 0.768 1.024 1.536 2.048 3.072 You can write the value 254 to the property at any time to restore it to the default. To set the number of repeats that will be sent, write to the RetryCount property of the System object. systemObject Data Type Integer. Read/Write Read/write. Added to API LNS Release 3.20. The System object to be acted upon.
PAGE 924
DsRetryCount Summary Sets the maximum number of times to retry messages sent using the request/response, unacknowledged/repeat, or acknowledged message services. This applies to messages sent during monitor and control operations for temporary monitor sets only. Availability Local, full, and lightweight clients. Syntax retryCountValue = systemObject.DsRetryCount Element Description retryCountValue The retry count value.
PAGE 925
Read/Write Read/write. Added to API LNS Release 3.20. DsTxTimer Summary Sets the interval between retries for acknowledged (lcaSvcAckd) and request (lcaSvcRequest) messages sent during monitor set operations involving temporary monitor sets. To set this value for network management messages, use the TxTimer property.
PAGE 926
15 3.072 You can write the value 254 to the property at any time to restore it to the default. To set the number of retries that will be sent for these message types, write to the DsRetryCount property. systemObject Data Type Integer. Read/Write Read/write. Added to API LNS Release 3.20. The System object to be acted upon. Extensions Summary Contains the Extensions collection object associated with the specified System object. This property returns an Extensions collection.
PAGE 927
Syntax fileTransObject = systemObject.FileTransfer Element Description fileTransObject The FileTransfer object. systemObject The System object to be acted on. Data Type FileTransfer object. Read/Write Read only. Added to API Prior to LNS Release 3.0. Handle Summary Contains the handle associated with the System object. An OpenLNS Object that is part of a collection is assigned an index corresponding to its position within that collection. This index may be used when invoking the Item property.
PAGE 928
Syntax hostTimerValue = systemObject.HostTimer Element Description hostTimerValue The host timer value in seconds. This property applies to network management messages only. This property accepts a range of values from 0 to 65,534 seconds. The default value is 15 seconds. You can write the value 65535 to this property without an exception being thrown. The value of the property, however, will not be changed from its current value. systemObject The System object to be acted upon. Data Type Integer.
PAGE 929
Disable and PingIntervals properties to 0. Disable automatic service pin registration by setting the system’s RegisterServicePin property to False. Availability Local, full, and lightweight clients. Syntax pathName = systemObject.ImportDirectory Element Description optionValue The value of the selected option.
PAGE 930
therefore, your application should set this property before calling the Open method of the System object for the first time. If you open a system with this property set to lcaPrivateMedia (4) and later decide you want the system to use shared media, you can accomplish this by setting the DomainIdSystem property of the System object to match the NetworkServiceDevice.NeuronId property of the OpenLNS Server computer. systemObject The System object for which the options apply. Data Type Integer.
PAGE 931
invocations. Availability Local, full, and lightweight clients. Syntax lastErrorObject = systemObject.LastError Element Description errorObject The last error generated by the system systemObject The System object to be acted upon. Data Type Error object. Read/Write Read only. Added to API Prior to LNS Release 3.0. LaunchLcaServerFlag Summary Indicates whether the OpenLNS Server should be launched when the Open method of the System object is called.
PAGE 932
Application available from the Echelon OpenLNS Utilities program folder. Data Type Boolean. Read/Write Read/write. Added to API Prior to LNS Release 3.0. LdrfCatalogPath Summary Obtains the full path for the location of the LonMark device resource file catalog (ldrf.cat). You should not modify this path because the resource file catalog should always be stored in the LonWorks/Types folder.
PAGE 933
LdrfLanguages Summary Contains the LdrfLanguages collection representing the languages known by OpenLNS. You can only access this property after you have opened the Object Server. Availability Local, full, lightweight, and independent clients. Syntax ldrfLang = osObject.LdrfLanguages Element Description ldrfLang The LdrfLanguages collection. osObject The System object to be acted on. Data Type Boolean. Read/Write Read only. Added to API LNS Release 3.0.
PAGE 934
modeType The Object Server management mode. The enumerated values for this parameter, which are contained in the ConstMgmtModes constant, are as follows: 0 lcaMgmtModePropagateConfigUpdates Network configuration changes are applied to both the OpenLNS database and the physical devices. Setting the management mode to this value also starts the background device discovery processes.
PAGE 935
Name Summary Specifies the name of an object as a character string. This property is case sensitive. Searches by name must match case. This property can be a maximum of 85 characters long, but it may not contain the forward slash (/), back slash (\), period (.), and colon (:) characters. Availability Local, full, lightweight, and independent clients. Note that some objects that contain this property are not available to Independent clients. Syntax stringValue = object.
PAGE 936
Data Type NetworkResources object. Read/Write Read only. Added to API LNS Release 3.20. NetworkServiceDevice Summary Returns the network service device, either an OpenLNS Server or NSI, attaching the OpenLNS ActiveX control to the network. The NetworkServiceDevice.NetworkInterface property of this object must be set before network communications are possible. Availability Local, full, and lightweight clients. Syntax nsdObject = systemObject.
PAGE 937
Added to API Prior to LNS Release 3.0. Parent Summary Returns the object that spawned the current child object. The parent object is determined by the means in which a child object is accessed, not by the OpenLNS Object hierarchy. Availability Local, full, lightweight, and independent clients. Note that some collection objects are not available to Independent clients. Syntax parentObject = object.Parent Element Description parentObject The object that is the parent of the specified object.
PAGE 938
permission value given by the first matching spec. This feature may be used to implement sophisticated permission scenarios. Some examples follow below. This spec gives permission to all IP address starting with 192.168: 192.168.0.0 255.255.0.0, 1 This spec denies access to IP 192.168.0.3: 192.168.0.3 255.255.255.255, 0 The following spec has no IP address which satisfies its rule, so an error will be generated upon assignment: 192.168.1.2 255.255.0.
PAGE 939
specified System object. The RecoveryStatus object provides status information on how a database recovery is proceeding. You can only access this property from a local client. You can read this property from an OnSystemNssIdle callback while the process that initiated the recovery is waiting for it to complete. Alternatively, another client, such as a plug-in application, can read it because plug-in applications always run as separate processes. Availability Local clients. Syntax rsObject = systemObject.
PAGE 940
invoked. This property defaults to True if the InstallOptions property was set to lcaSharedMedia (2) before the System was opened for the first time. Otherwise, it defaults to False. systemObject The System object to be acted on. Data Type Boolean. Read/Write Read/write. Added to API Prior to LNS Release 3.0. RemoteChannel Summary If you are developing a Full client application, you can use this property to specify the Channel to which your application’s NetworkServiceDevice is attached.
PAGE 941
RepeatTimer Summary Sets the repeat timer value that will be used on the system for network management messages only. You can set the number of repeat messages that will be sent by writing to the RetryCount property. Availability Local, full, and lightweight clients.
PAGE 942
Syntax repeatTimerValue = object.RepeatTimer Element Description repeatTimerValue The encoded value of the repeat timer. The default value for this property is determined based on the network topology. It is recommended that you do not change this from the default value. If the default value is not suitable for your application, it is recommended that you use the Delay property of each Channel object on the network to ensure that each message is sent at the correct interval.
PAGE 943
ResourceLanguageId Summary Controls which language should be used when displaying descriptive type information stored in device resource files. This property can contain one or more language codes that identify the language that should be used when displaying type information stored in resource files. When you pass multiple language codes to this property, they must be comma-separated, as in the following example: "frc, enz, rus.
PAGE 944
RetryCount Summary Sets the retry count used by the Object Server (and connections that use the default System value) for all network management messages that use the request/response, unacknowledged/repeat, or acknowledged message service types. You can set the interval for retry messages sent using the acknowledged or request messages by writing to the TxTimer property.
PAGE 945
TRUE is commissioned or replaced. 1 lcaSecurityLevelKeyDistribution Disabled Keys are never distributed over the network. For all devices that have their AuthenticationEnabled property set to TRUE, the installer is responsible for installing the authentication key. The key installed must match the value of the System object’s AuthenticationKey property.
PAGE 946
State Summary Describes the state of the system. Availability Local, full, and lightweight clients. Syntax stateValue = object.State Element Description stateValue The state of the system. The enumerated values for this property, which are stored in the ConstDeviceStates constant, are as follows: Note: The only two values that may be written to this property are lcaStateCnfgOnline(4) and lcaStateSoftOffline(12). All other properties are read-only.
PAGE 947
Application loaded but not running. The configuration is considered valid in this state; the network management authentication bit is honored. The device's service LED is off in this state. 12 lcaStateSoftOffline The device has an application, is configured, and is soft-offline. It will go online when it is reset or when requested to go online. The device's service LED is off in this state. 140 lcaStateCnfgBypass The application confirmed the offline request, but is still running (bypass mode).
PAGE 948
Subsystems Summary Contains the Subsystems collection object associated with the specified System. A Subsystem object can in turn contain a collection of Subsystems. A System object’s Subsystems collection contains two default Subsystems upon creation. These Subsystems are named "ALL", which lists all of the devices in the system and "Discovered", which lists all devices discovered by the object server that have not yet been associated with a subsystem.
PAGE 949
The System object to be acted on. systemObject Data Type TemplateLibrary object. Read/Write Read only. Added to API Prior to LNS Release 3.0. TxTimer Summary Sets the value of the transmit timer used for network management messages. You can use this property to specify the interval between between retries for acknowledged (lcaSvcAckd) and request (lcaSvcRequest) messages sent during network management operations.
PAGE 950
5 6 7 8 9 10 11 12 13 14 15 0.096 0.128 0.192 0.256 0.384 0.512 0.768 1.024 1.536 2.048 3.072 You can also write the value 254 to the property at any time to restore it to the default. timerValue The encoded value of the transmit timer. systemObject The System object to be acted on. Data Type Integer. Read/Write Read/write. Added to API Prior to LNS Release 3.0. UncommissionedDeviceCount Summary Returns the number of uncommissioned devices discovered by network recovery.
PAGE 951
UninstalledDeviceCount Summary Returns the number of devices uninstalled by network recovery. At the completion of network recovery, devices are grouped into three categories. • Installed devices that were recovered are counted by the CommissionedDeviceCount property. • Installed devices that could not be recovered, and had to be uninstalled, are counted by the UninstalledDeviceCount property.
PAGE 952
UpdateInterval Summary The rate (in seconds) at which the background database device image reconciliation process runs after a device update failure occurs on the network. A device update failure occurs when a transaction has been completed and committed to the OpenLNS database, but OpenLNS is unable to load the information into the physical device because of some error.
PAGE 953
Systems The Systems object represents a collection of System objects. Each Systems collection contains a single System object. The System object associated with a network has the same name as the network. The Systems object is automatically added when you add a new Network object. The following table summarizes the Systems object. Description A collection of System objects. Added to API Prior to LNS Release 3.0. Accessed Through Network object. Default Property Item. Methods None.
PAGE 954
3 lcaClassIdSystem object The object to be acted on. Data Type Integer. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. Count Summary Returns the number of objects in a collection. You can use this property to enumerate a collection object. Availability Local, full, lightweight, and independent clients.
PAGE 955
on. index A Long type specifying the ordinal index of the System object to be retrieved. stringExpression A string type specifying the name of the System object to be retrieved. Data Type Object. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. Parent Summary Returns the object that spawned the current child object.
PAGE 956
• If you are developing your OpenLNS app in C#, you do not need to use the _NewEnum property explicitly because it is automatically used in the implemention of foreach statements. Availability Local, full, and lightweight clients. Syntax retrievedObject = collObject._NewEnum Element Description retrievedObject An expression that evaluates to the object retrieved. collObject An iterator object that can be used to access members of the collection. Data Type Object. Read/Write Read only.
PAGE 957
ClassId Summary Identifies the object class of this object. This property allows the object type to be determined when it is unknown (for example, when the object was accessed using the Parent property of another object). Availability Local, full, lightweight, and independent clients. Note that some objects containing this property are not available to Independent clients. Syntax classIdValue = object.ClassId Element Description classIdValue The object class of the object.
PAGE 958
Availability Local, full, lightweight, and independent clients. Note that some collections are not available to Independent clients. Syntax stringValue = object.Description Element Description stringValue A string description of the TemplateLibrary object. object The TemplateLibrary object to be acted on. Data Type String. Read/Write Read/write. Added to API This depends on the object used to access the property.
PAGE 959
specified object. object Any object for which the parent is desired. Data Type Object. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. TestInfo The TestInfo object contains information describing the results of the last test on the AppDevice or RoutersSide object. You can initiate a test on an AppDevice or Router by calling the Test method on it.
PAGE 960
• • • • • • • • • • • • • ActualProgramId ActualSubnetId AuxResultData ClassId DetailInfo ExpectedDomainId ExpectedNeuronId ExpectedNodeId ExpectedProgramId ExpectedSubnetId IsDetailInfoValid Parent Status ActualDomainId Summary Contains the actual Domain ID of the tested device or router side if the AuxResultData is set to LcaDomainIdData. This property can be used in conjunction with the AuxResultData to analyze Domain ID discrepancies.
PAGE 961
Availability Local, full, and lightweight clients. Syntax neuronIdValue = toObject.ActualNeuronId Element Description toObject The TestInfo object to be acted on. neuronIdValue The actual Neuron ID of the tested device or router side. Data Type String. Read/Write Read only. Added to API LNS Release 3.0. ActualNodeId Summary Contains the actual node ID of the tested device or router side if the AuxResultData is set to LcaNodeData.
PAGE 962
Availability Local, full, and lightweight clients. Syntax progIdValue = toObject.ActualProgramId Element Description toObject The TestInfo object to be acted on. progIdValue The actual program ID of the tested device or router side. Data Type String. Read/Write Read only. Added to API LNS Release 3.0. ActualSubnetId Summary Contains the actual subnet ID of the tested device or router side if the AuxResultData is set to LcaSubnetData.
PAGE 963
are as follows: 0 lcaNoAuxData There is no useful information in the Actual/Expected properties of the LastTestInfo object. 1 lcaNeuronIdData The ActualNeuronId and ExpectedNeuronId properties contain information about a Neuron ID discrepancy. 2 lcaDomainIdData The ActualDomainId and ExpectedDomainId properties contain information about a Domain ID discrepancy.
PAGE 964
constant: 71 lcaClassIdTestInfo object The object to be acted on. Data Type Integer. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. DetailInfo Summary Contains the DetailInfo object associated with the specified AppDevice, RouterSide, or TestInfo object. The DetailInfo object contains an error log and communications status information for an AppDevice or RouterSide object.
PAGE 965
Availability Local, full, and lightweight clients. Syntax domainIdValue = toObject.AuxResultData Element Description toObject The TestInfo object to be acted on. domainIdValue The expected domain ID of the tested device or router side. Data Type String. Read/Write Read only. Added to API LNS Release 3.0. ExpectedNeuronId Summary Contains the expected Neuron ID of the tested device or router side if the AuxResultData is set to LcaNeuronIdData.
PAGE 966
Syntax nodeIdValue = toObject.ExpectedNodeId Element Description toObject The TestInfo object to be acted on. nodeIdValue The expected node ID of the tested device or router side. Data Type String. Read/Write Read only. Added to API LNS Release 3.0. ExpectedProgramId Summary Contains the expected program ID of the tested device or router side if the AuxResultData is set to LcaProgramIdData. This property can be used in conjunction with the ActualProgramId to analyze Program ID discrepancies.
PAGE 967
Syntax subnetIdValue = toObject.ExpectedSubnetId Element Description toObject The TestInfo object to be acted on. nodeIdValue The expected subnet ID of the tested device or router side. Data Type String. Read/Write Read only. Added to API LNS Release 3.0. IsDetailInfoValid Summary Indicates whether the TestInfo object's DetailInfo property contains valid information. Availability Local, full, and lightweight clients. Syntax validDetailValue = tiObject.
PAGE 968
specified object. object Any object for which the parent is desired. Data Type Object. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. Status Summary Indicates the test status reported by the Test method. Availability Local, full, and lightweight clients. Syntax statusValue = tiObject.Status Element Description toObject The TestInfo object to be acted on.
PAGE 969
The OpenLNS Server was able to communicate with the device using subnet/node addressing, but could not communicate with the device using Neuron ID addressing. However, through the use of subnet/node addressed messages, the OpenLNS Server has verified that the device contains the expected Neuron ID. This might be caused by intermittent device or channel failures. You may want to retry this method to see if the error persists.
PAGE 970
caused by attaching a new device to the network which was previously configured as part of another network or by two networks sharing the same media and domain ID. This condition could also occur if the unexpected device was supposed to be removed from the system, but the OpenLNS Server was unable to update the device’s network image during a Remove method; meanwhile, the removed subnet/node address has been reused for the device being tested.
PAGE 971
10 lcaTestResultNoNeuronId The device has not been assigned a Neuron ID. 11 lcaTestResultMismatchProgramId The OpenLNS Server was able to communicate with the device using both Neuron ID and subnet/node addressing. However, the device does not contain the expected program ID. The device’s program ID may have been changed by its application program. Host devices can modify the program ID of their attached network interface. The device should be Removed and Added.
PAGE 972
communicate with the device using both Neuron ID addressing and subnet/node addressing. However, the device has network management authentication disabled despite the fact that the device's AuthenticationEnabled property is set to TRUE. The device may have disabled network management authentication itself, the device may have been reconfigured by another network management tool, or the device may be faulty. The device may be restored using the Commission method.
PAGE 973
The OpenLNS network interface that the OpenLNS Server is attempting to use is not property configured. Recommission the NetworkServiceDevice of the System object by calling the System.NetworkServiceDevice. AppDevice.Commission method. Data Type Integer. Read/Write Read only. Added to API LNS Release 3.0. TypeSpec The TypeSpec object contains a group of properties that OpenLNS uses to identify the type a network variable should use.
PAGE 974
Methods • Lookup Properties • • • • • • • • • ClassId Index IsComplete Length ObjectType Parent ProgramId Scope TypeName Methods The TypeSpec object contains the following methods: • Lookup Lookup Summary Validates that the scope, program ID, and format name assigned to a TypeSpec object references a valid network variable type. Availability Local, full, and lightweight clients. Syntax typeSpec.Lookup Added to API Element Description typeSpec The TypeSpec object to be acted upon.
PAGE 975
Element Description classIdValue The object class of the object. The following value is defined for the TypeSpec object in the ConstClassIds constant: 94 lcaClassIdTypeSpec object The object to be acted on. Data Type Integer. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API.
PAGE 976
• TRUE. The TypeSpec object is complete. • FALSE. The TypeSpec object is incomplete. Several conditions may cause a TypeSpec object to be incomplete. For example, if you try to get a TypeSpec object for a network variable with a changeable UNVT type that uses a configuration property, and the category of the configuration property is either CAT_INITIAL or CAT_NULL, then the TypeSpec object would be incomplete. Availability Local, full, and lightweight clients. Syntax complete = typeSpec.
PAGE 977
ObjectType Summary Indicates the type of objects to which the type should be applied. When new values are written to the Scope, ProgramID, TypeName properties of the TypeSpec object and the TypeSpec object is passed back to the network variable, OpenLNS sets the ObjectType property automatically. Availability Local, full, and lightweight clients. Syntax objectType = typeSpec.ObjectType Element Description objectType The objects to which the type applies.
PAGE 978
parentObject The object that is the parent of the specified object. object Any object for which the parent is desired. Data Type Object. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API. ProgramId Summary Contains the program ID of the TypeSpec object. The program ID is stored as a unique 16-digit hexadecimal number in the following format: FM:MM:MM:CC:CC:UU:TT:NN.
PAGE 979
Scope Summary Each TypeSpec object references a type defined in a LonMark resource file. This property indicates the scope of the resource file that contains that type’s definition. The scope of a resource file determines which devices will use the types defined in that resource file. Availability Local, full, and lightweight clients. Syntax scopeValue = typeSpec.Scope Element Description scopeValue The scope of the device resource file containing the definition of this type.
PAGE 980
lcaResourceScopeAutoDeterminatio n This value applies to the Mode property of LonMarkObject objects only. Select this value to have LNS determine the value of the Mode property for the LonMarkObject automatically. If you select this value, OpenLNS will iterate through all the available resource files from most specific to most general ( highest scope to lowest scope) until it finds the functional profile template resource file containing the LonMarkObject object’s definition.
PAGE 981
UpgradeInfo Each time you call the Upgrade method to upgrade an AppDevice object’s external interface file, an UpgradeStatus object is returned. The UpgradeStatus object contains properties describing the results of the upgrade. This includes the UpgradeInfos property, which contains a collection of UpgradeInfo objects.
PAGE 982
• • • • Reason Status ToIndex ToOwnerIndex Class Summary Indicates the type of external interface component described by this UpgradeInfo object. You can use this property in conjunction with the ToIndex or FromIndex properties to determine the component in the new and old external interfaces that the UpgradeInfo object represents. Availability Local, full, and lightweight clients. Syntax classValue = uiObject.
PAGE 983
9 lcaUgClsDynamicMessageTag A dynamic MessageTag. uiObject The UpgradeInfo object to be acted on. Data Type Integer. Read/Write Read only. Added to API Prior to LNS Release 3.0. ClassId Summary Identifies the object class of this object. This property allows the object type to be determined when it is unknown (for example, when the object was accessed using the Parent property of another object). Availability Local, full, lightweight, and independent clients.
PAGE 984
configuration property. If the configuration property is contained by a LonMarkObject or network variable, the FromOwnerIndex property contains the device index assigned to the owner LonMarkObject or network variable in the upgraded external interface. Availability Local, full, and lightweight clients. Syntax indexValue = uiObject.FromIndex Element Description indexValue The device index value assigned to the external interface component before the upgrade.
PAGE 985
Parent Summary Returns the object that spawned the current child object. The parent object is determined by the means in which a child object is accessed, not by the OpenLNS Object hierarchy. Availability Local, full, lightweight, and independent clients. Note that some collection objects are not available to Independent clients. Syntax parentObject = object.Parent Element Description parentObject The object that is the parent of the specified object.
PAGE 986
components can not be matched if their types differ. 2 lcaUgRsName The external interface component was preserved because it matched the name of a component in the new external interface. 4 lcaUgRsIndex The external interface component was preserved because it matched the index of a component in the new external interface.
PAGE 987
name used for these custom interfaces is "LcaUpgrade", where is a sequential number reflecting the number of upgrades that the device has gone through since LNS 3.20 was installed. For example, the 3rd time the device is upgraded, this interface would be named "LcaUpgrade3." Note that static components are converted to dynamic components only if the new interface supports dynamic LonMark Objects, and the old interface did not.
PAGE 988
Status Summary Indicates whether the external interface component represented by the UpgradeInfo object was preserved or deleted during the external interface upgrade. It also indicates whether any other modifictions were made as a result of the upgrade (for example, the component was moved).
PAGE 989
any configuration property values will be preserved. 4 lcaUgStsRelocated The external interface component was preserved but relocated to a different index. See the ToIndex property and ToOwnerIndex property (if applicable) for the new location. 8 lcaUgStsNvAttribsMismatch The network variable was preserved, but the polled or authenticated attributes do not match. The network variable will be removed from any bound connections and the lcaUgStsDisconnNvAttrib value will be set.
PAGE 990
ToIndex Summary Returns the device index value assigned to the external interface component after the upgrade. This is the component in the external interface file that is represented by this UpgradeInfo object. If the Class property is set to lcaUgClsConfigProp (4), lcaUgClsLmObjConfigProp (5) or lcaUgClsNetVarConfigProp (6), the UpgradeInfo obect represents a configuration property.
PAGE 991
property that is contained within a LonMarkObject or network variable, but the Status property is set to lcaUgStsDeleted (1), the configuration proprty was deleted from the external interface file during the upgrade. In this case, this property will also return -1. Availability Local, full, and lightweight clients. Syntax indexValue = uiObject.ToIndex Element Description indexValue The device index value assigned to the external interface component after the upgrade.
PAGE 992
ClassId Summary Identifies the object class of this object. This property allows the object type to be determined when it is unknown (for example, when the object was accessed using the Parent property of another object). Availability Local, full, lightweight, and independent clients. Note that some objects containing this property are not available to Independent clients. Syntax classIdValue = object.ClassId Element Description classIdValue The object class of the object.
PAGE 993
collection by passing its index (ordinal position) within that collection as the argument for the Item property. Index values start at 1. Availability Local, full, lightweight, and independent clients. Note that some objects containing this property are not available to Independent clients. Syntax retrievedObject = collObject.Item(index) retrievedObject = collObject.Item(stringExpression) Element Description retrievedObject The UpgradeInfo object retrieved from the UpgradeInfos collection.
PAGE 994
added to the API. _NewEnum Summary Enables you to iterate over the objects in a collection using For Each ... Next statements. • If you are developing your OpenLNS app in Visual C++, you can browse a collection to find a particular item by using the _NewEnum property. See the IEnumVARIANT interface for details. • If you are developing your OpenLNS app in Visual Basic, you do not need to use the _NewEnum property because it is automatically used in the implementation of For Each ... Next statements.
PAGE 995
• • Sequence UpgradInfos Methods The UpgradeStatus object does not contain any methods. Properties The Upgrade Status object contains the following properties: • • • • • ClassId Parent Result Sequence UpgradInfos ClassId Summary Identifies the object class of this object. This property allows the object type to be determined when it is unknown (for example, when the object was accessed using the Parent property of another object). Availability Local, full, lightweight, and independent clients.
PAGE 996
clients. Syntax parentObject = object.Parent Element Description parentObject The object that is the parent of the specified object. object Any object for which the parent is desired. Data Type Object. Read/Write Read only. Added to API Depends on the object used to access the property. Generally, this property exists for an object as soon as the object is added to the API.
PAGE 997
usObject Data Type Integer. Read/Write Read/write. Added to API LNS Release 3.0. The UpgradeStatus object to be acted on. Sequence Summary Returns the number of times the external interface of the device containing the UpgradeStatus object has been upgraded since OpenLNS was installed on the client. If OpenOpenLNS has not been installed on the client, or if the device has not been upgraded since OpenLNS was installed, this property will return a value of 0.
PAGE 998
Syntax ioColl = uiObject.UpgradeInfos Element Description uiColl The UpgradeInfos collection to be returned. uiObject The UpgradeInfo object to be acted on. Data Type UpgradeInfos collection. Read/Write Read only. Added to API LNS Release 3.0.
PAGE 999
OpenLNS Programmer's Reference 962
PAGE 1000
3 Interfaces This chapter details each interface in the OpenLNS Object hierarchy.
PAGE 1001
ILcaMsgMonitorPointListener The ILcaMsgMonitorPointListener interface can be added to a COM object created in a multi-threaded programming environment such as Visual C++. You must then call the Advise method of the MsgMonitorPoint with the object that implements this interface as an argument. This will allow the object to receive updates from that message monitor point directly, rather than through the Object Server. The following table summarizes the ILcaMsgMonitorPointListener interface.
PAGE 1002
Syntax Added to API object.UpdateErrorEvent updateType Element Description object An object that implements the ILcaMsgMonitorPointListener interface. updateType A value indicating the type of monitor point update which returned an error. This will be set to 1. LNS Release 3.0. UpdateEvent Summary Allows an object to execute a callback for message monitor point updates. This can only be used in multi-threading programming environments such as Visual C++. It cannot be used in Visual Basic.
PAGE 1003
request/response message. The OutputDp parameter's AutoWrite property is set to True; therefore, it will be sent as a response when you write to this DataPoint object. srcAddr Added to API The SourceAddress object indicating the source device of the message monitor point update. LNS Release 3.0. ILcaNvMonitorPointListener The ILcaNvMonitorPointListener interface can be added to a COM object created in a multi-threaded programming environment such as Visual C++.
PAGE 1004
instead of Windows messaging. You must call the Advise method from the event handler that is handling the update error events for the network variable monitor point. For more information on this, see the Advise method of the NvMonitorPoint object. The object created in step 1 will now call this method whenever a network variable monitor point error is received. Availability Local and full clients. Syntax object.
PAGE 1005
be set to 0. inputDp The DataPoint object containing the network variable monitor point update. The InputDp parameter's AutoRead and AutoWrite properties are set to False. outputDp A DataPoint object that allows a response to be sent if the update is a request/response message. The OutputDp parameter's AutoWrite property is set to True; therefore, it will be sent as a response when you write to this DataPoint object.
PAGE 1006
follow these steps: 1. Create an object that implements the ILcaProgressListener interface. 2. Define the behavior of the object when the ProgressUpdate method is called. 3. Call the Validate method of the Network with the object created in step 1 as the progressCallback argument. The object created in step 1 will now call this method whenever a database validation update event is received, and will be updated with the information delivered through the update event. Availability Local clients.
PAGE 1007
The step name will be returned as a string of up to 128 characters. Added to API LNS Release 3.20.
PAGE 1008
4 OpenLNS Errors This chapter lists and describes the errors that may be generated by the various OpenLNS components.
PAGE 1009
Errors LNS errors may be produced by each of the LNS components. These are uniquely identified in the object server by the addition of a component offset value. Errors are therefore mapped into the following ranges: Range Error Type Mapping 1000-16499 Network Services Errors NS error 1 is LNS error 1001, NS error 2 is LNS error 1002, and so on. 16500-16599 Network Interface Errors NI error 1 is LNS error 16501, NI error 16502 is LNS error 1002, and so on.
PAGE 1010
The device was discovered to be applicationless, or not associated with a program. If you encounter this error, load the application into the device. For host-based nodes, ensure that the host application is running. lcaErrNsBadManagerId 6 The current manager ID does not correspond to a known manager. This is an internal error and should be reported to customer support. lcaErrNsResourceProblem 7 A problem occurred in resource allocation.
PAGE 1011
lcaErrNsNotImplemented 16 The specified service or option is not implemented by the specified server. This error could indicate a bad service parameter. This is an internal error and should be reported to customer support. lcaErrNsErrorInfo 17 The service failed. When you encounter this error, a service-specific error status is available in the LastError property of the System object. lcaErrNsServiceFailure 18 The requested service failed.
PAGE 1012
lcaErrNsUnsupportedInfo 28 The requested information is not available from an application node. For example, transceiver status, SI/SD data, and network variable names are not always stored in the node. lcaErrNsOutOfRange 29 The value assigned to a property or parameter is either out of range, or invalid. lcaErrNsEventFailure 30 The generation of an event failed. This is an internal error and should be reported to customer support.
PAGE 1013
lcaErrNsObjectInUse 39 A requested operation can't complete because the object involved in the operation is in use. For example, you may not be able to delete a node because that node is still included in connections. lcaErrNsNodeHasNoSiData 40 The node has no SI (self-information) data, when required. lcaErrNsDbError 41 An internal database error occurred. This is an internal error, and should be reported to customer support. lcaErrNsOutOfJournal 42 No more memory is available for journaling.
PAGE 1014
lcaErrNsProgramDblimit 55 This is an internal error, and should be reported to customer support. lcaErrNsNvmtNotFound 56 The network variable or message tag cannot be found. lcaErrNsNvmtDbLimit 57 This is an internal error, and should be reported to customer support. lcaErrNsChannelNotFound 58 The channel cannot be found. lcaErrNsProgramIntfMismatch 59 The new program interface does not match the previously defined program interface; i.e.
PAGE 1015
lcaErrNsRouterNotFound 70 The specified router handle does not exist. lcaErrNsTimerRange 71 The timer value computed for a connection or for the OpenLNS Object Server to communicate with a node exceeds the range supported by LONWORKS devices. This is an internal error, and should be reported to customer support. lcaErrNsWrongChannel 72 An attempt was made to add, commission, move, or replace a device that is on the wrong channel.
PAGE 1016
other channel by repeaters or permanent bridges. Also, this error will occur if the channel is not currently configured in the system. lcaErrNsRedundantRoutersMustBeConfigured 80 An attempt was made to add a redundant router that was not of the configured class, to change the class of a redundant router to the non-configured class, or to add a redundant router to an existing non-redundant, non-configured class router.
PAGE 1017
lcaErrNsCpDbLimit 93 The configuration property database limit has been exceeded. lcaErrNsCpRangeNotFound 94 The specified configuration property range does not exist. lcaErrNsCpRangeDblimit 95 The configuration property range database limit has been exceeded. lcaErrNsConnectionError 96 Connection rebinding failed for a set of moved nodes. Possible causes are: no more address table slots, no more groups, or broadcast violation.
PAGE 1018
The requested LonMark object member was not found. You will encounter this error if you try to use the UnassignNetworkVariable method to remove a network variable from a LonMarkObject, but the network variable was not previously assigned to the LonMarkObject. You can use the AssignNetworkVariable method to assign a network variable to a LonMarkObject. lcaErrNsStaleFileHandle 109 An attempt was made to use a stale file transfer handle. This is an internal error, and should be reported to customer support.
PAGE 1019
lcaErrNsNvNotLmobjMember 122 The network variable is not a member of a LonMark object. lcaErrNsHostResourceProblem 123 There is a resource problem in the API or application. lcaErrNsTxAlreadyCanceled 124 The specified transaction was already canceled. lcaErrNsFirmwareVersionMismatch 125 The device contains an incompatible firmware version.
PAGE 1020
lcaErrNsNsiInuse 136 Returned when an attempt is made to remove an NSI that is being used by other processes. lcaErrNsDialingFailure 137 Failed to call host. Probably due to busy, no answer, or recent failure. lcaErrNsNetworkInterfaceState 138 Local network interface is in the wrong state (e.g. unconfigured). When you encounter this error, set the network management mode to lcaMgmtModePropagateConfigUpdates (0) by writing to the MgmtMode property of the System object.
PAGE 1021
Note that you must stop the "CrypkeyLicense" service and "NetworkX" driver before deleting the Crypkey files. Certain conditions on the PC operating the license may also cause this error. For example, if the PC’s file system is corrupted or low on space, or if the license files have been manually deleted, tampered with in any way, or moved by some disk-defragmentation utilities, this error will occur. You can resolve these situations by ordering a replacement license key.
PAGE 1022
lcaErrNsMaxDbOpened 158 Exceeded the maximum number of databases lcaErrNsEventsNotInitialized 159 Event subsystem not initialized. lcaErrNsMcsNotFound 160 Monitor set cannot be found. lcaErrNsMcsDblimit 161 Max number of monitor points exceeded. lcaErrNsMcpNotFound 162 Monitor point cannot be found. lcaErrNsMcpDblimit 163 Max number of monitor points exceeded. lcaErrNsNvmtInUse 164 The network variable or monitor point is in use and cannot be used for current service.
PAGE 1023
An OpenLNS network interface uses an IP address not defined on this PC. lcaErrNsNsiNotConfigured 176 NSI needs to be added or re-commissioned. lcaErrNsNiDeviceOpenFailure 177 NI device driver open failure. lcaErrNsBadLength 178 Invalid length of parameter, data, service, or message. lcaErrNsBadName 179 Invalid name length, characters, or usage. lcaErrNsBadDomain 180 Invalid domain length, index, or usage.
PAGE 1024
However, the device will remain applicationless. You should load a new application image into the device with the Load or LoadEx methods in this case. lcaErrNsSysimageUpgradeFailed 188 This error will be generated when you invoke the LoadEx method on a device, and the new system image is successfully transferred to the device, but the switch from an old system image to a new system image fails.
PAGE 1025
Resource count exceeds capacity limits in self-identification data. lcaErrNsLmsdObjectRange 267 Invalid object range in the LonMark portion of a network variable self-documentation string. When specifying a range of objects, the lowest object index must appear before the highest object index. lcaErrNsLmsdObjectMemberNumber 268 Invalid object member in the LonMark portion of a network variable self-documentation string. The member number must be between 1 and 32767.
PAGE 1026
lcaErrNsCpsdTemplateVersion 279 The version of the CP template is unsupported. lcaErrNsGroupDblimit 280 The number of LonTalk groups has been exceeded. There is a limit of 255 LONtalk groups per domain. In some case you may form connections using subnet or domain broadcast, to limit the use of groups. You may also limit the use of groups by using network variable aliases. These options are specified in the connection description template used when forming connections.
PAGE 1027
The bound network variables must be disconnected before the LonMarkObject can be deleted. You can disconnect the network variables by specifying the lcaLonMarkObjectRemoveAndDisconnectNVs (3) option as the removalFlags element when you call the Remove or RemoveByIndex methods. lcaErrNsApplReadWriteProtected 288 This exception will be thrown if you call the Load method to load a new application into a device, but the device’s current application is read/write protected.
PAGE 1028
the device template was imported from an external interface file, the configuration property template file comes from the external interface file. Otherwise, the configuration property template file is loaded from the device. lcaErrNsWarningFirst 4030 A symbol denoting the beggining of the error number range reserved for warning codes. lcaErrNsUpdateCommError 4030 The database updates were successful, but one or more nodes were not updated because the NSS was unable to communicate with them.
PAGE 1029
persistent update failures on a device, you should re-commission the device with the Commission method. lcaErrNsUpdateFileXferError 4034 The database updates were successful, but an update error occurred. The NSS will continue to try to update the nodes in the background if the UpdateInterval property of the System object is set to a non-zero value, and you can force a retry with the RetryUpdates method.
PAGE 1030
lcaErrNsUpdateCpFailure 4038 The database updates were successful, but the configuration properties on one or more devices could not be updated as a result of invalid configuration property definitions. The NSS will continue to try to update the nodes in the background if the UpdateInterval property of the System object is set to a non-zero value, and you can force a retry with the RetryUpdates method.
PAGE 1031
Could not communicate with the network interface. A message timed out. lcaErrNiUplinkCmd 9 An uplink command was received from the NSS instead of a message. lcaErrNiInternalErr 10 An internal error occurred, probably an invalid completion code. lcaErrNiFileOpenErr 11 The log file could not be created or opened. lcaErrNiNotNss 12 The network interface received an LNS command, when no NSS was present. lcaErrNiInvalidData 13 The parameter or return data was invalid.
PAGE 1032
May not send implicit tags via NI layer. Must use a message monitor point. lcaErrNiUnimplemented 27 This is an internal error and should be reported to customer support. lcaErrNiBufferSize 28 The message length is too long. lcaErrNiNoMessages 29 Message not found. lcaErrNiNegativeResponse 30 Negative response. lcaErrNiStateError 31 Unable to change the state of the network interface. lcaErrNiReadBusy 32 Previous response messages have not been read.
PAGE 1033
Connection Errors Connection errors are errors returned when attempting to make network variable or message tag connections. These errors will appear in the format CONNERR: #. The LNS values for these errors are equal to the error number plus 16,500. lcaErrConnInvalidTargetCount 1 An incorrect number of targets were specified. You must specify at least one and no more than 25 targets when adding members. To add more members, you must invoke the Connect method multiple times.
PAGE 1034
If the connection members are not SNVTs, then all members must have the same length. lcaErrConnDirectionOrPollingMismatch 9 An input network variable can only be connected to an output network variable, a polled output network variable can only be connected to a polling input network variable, and the implicit message tag msg_in can only be connected to an explicitly declared message tag.
PAGE 1035
shared by connections that intersect each other. This error will be generated when an attempt is made to form a connection that violates this constraint, and no network variable alias was available to overcome the constraint. If network variable aliases are available on the devices in the connection, they will normally be automatically used to avoid this error. A selector is a number assigned to the network variable during the connection process in order to identify connected network variables.
PAGE 1036
A network can use up to 12288 selector values. Unrelated connections will normally require unique selector values. Intersecting connections automatically use the same selector Network variable aliases are used automatically to resolve selector conflicts on a node (i.e. to eliminate this exception from occurring), although this uses up one selector for each alias. Starting in LNS 2.0, selector values are grouped into categories, with one category being "shareable".
PAGE 1037
network variable may be received by connections and devices that it is not intended to. LNS attempts to avoid this problem by the appropriate allocation of network variable selectors. However, some connection intersections make the use of broadcast addressing impossible, and so you may need to avoid using broadcast addressing in some situations. One solution for this problem is to use aliases for unicast connections, instead of using multicast connections.
PAGE 1038
identical. If a polling input network variable is a member of multiple connections, the timer settings for those connections must also be identical. lcaErrConnConflictingBroadcastSettings 32 The connection descriptions for intersecting connections have incompatible settings for broadcast addressing. If an output network variable that is not declared as polled is a member of multiple connections, the broadcast options for all of those connections must be identical.
PAGE 1039
lcaErrUninitializedDb 5 Contact technical support. lcaErrObjectNotFound 6 An object has been requested by name, handle, or index, which could not be found in the databases. Typically, this would be a request from an OpenLNS collection object with a bad name, handle, or index. It should be noted that this error can also occur in a few implicit assignments.
PAGE 1040
Alternatively, the XFB file might be re-build from the XIF file, using the XIF32BIN.EXE utility. lcaErrInvalidPgmType 14 The ProgramType property contains an invalid value. lcaErrInvalidCollectionIndex 15 A query to an OpenLNS collection object has been made using an invalid index or handle. Valid indices start with 1 and end with the current item count. lcaErrCannotUpdateUnattachedObject 16 An attempt was made to update a device while not attached to the network.
PAGE 1041
lcaErrDatabase 25 An unexpected database error occurred. Please take a note of the full error message, and contact technical support at LonSupport@Echelon.com lcaErrInvalidDeviceTemplate 26 The DeviceTemplate object has been corrupted. lcaErrNoDatabase 27 The network database has not been found in the location previously registered. lcaErrNoDbDictionary 28 The LNS dictionary files _objects.dat and _objects.idx are missing or can not be found.
PAGE 1042
Contact customer support. lcaErrCompiler 41 Generic compiler error. See the LNS Field Compiler documentation for details. lcaErrProjectMgrNotAvailable 42 The LNS Field Compiler's project manager and dependency checker is unavailable. See the LNS Field Compiler documentation for details. lcaErrInvalidLinkerOptions 43 The options passed to the NEURON Linker were invalid. See the LNS Field Compiler documentation for details.
PAGE 1043
lcaErrCantCopyNssDirectory 54 Internal error. Contact customer support. lcaErrCantRecoverNotNewDb 55 A call to the RecoverFromNetwork method has been made, using a previously used network database. For the recovery process, a newly created network database is required. lcaErrCantRecoverMissingNssDbFiles 56 Some parts of the network database are lost and can not be recovered. The network must be re-build from scratch, should no backup be available.
PAGE 1044
lcaErrAnotherNetworkAlreadyOpen 66 An attempt to open a network database failed because another network object is still held open by the same client process. This error should not occur in LNS 3 or greater. If it does, contact customer support. lcaErrSystemNotOpen 67 A service has been accessed prior to successfully opening the system object, which requires the system to be open.
PAGE 1045
lcaErrCantLaunchLcaServer 79 The OpenLNS Server cannot be launched. lcaErrNoMemory 80 No more system memory available. lcaErrDbInvalidVersion 81 The database has an invalid version. Note that OpenLNS databases can be upgraded using the CompactDb method, but also note that OpenLNS databases are not backwards compatible. Once updated to version N+1, the database will not be accessible for a version N client any more.
PAGE 1046
removing items at runtime. It should be noted that this exception may also occur with collections which are usually write-enabled, as the context might not allow for changes. For example, the Subsystems collection would typically be seen in the hierarchy System ::Subsystems context, to which further items can be added using the Subsystems collection's Add method. The AppDevice and Router object's Subsystems collection objects, however, represent all subsystem objects to which the device belongs to.
PAGE 1047
lcaNeuronIdInUse 102 The NEURON ID assigned is already in use for another device in the network. lcaDbCantBeCompactedWhenOpen 103 CompactDb() methods must be called prior to opening the associated object. lcaDbCantBeRemovedWhenInUse 104 The object can not be removed as it still is in use. lcaErrCantRemoveDefaultAccount 105 The default Account object can not be removed. lcaErrCantRemoveAccountWithCharges 106 An account object needs to be empty for being removed.
PAGE 1048
A service which is only available local to the server or on a Full client has been requested from a Lightweight client. lcaNotAnNsiHost 118 The (hosted) device does not execute the NSI firmware, and the requested service can not be completed therefore. lcaErrInterfaceNotModifyable 119 An attempt to dynamically modify a static interface was made.
PAGE 1049
A network variable name is required for this service. LcaInternalErrBadExceptionCode 133 Internal error. LcaInternalErrBadHresultExceptionCode 134 Internal error. LcaInternalErrBadVNIDataServer 135 Internal error. LcaInternalErrBadNsdHandle 136 Internal error. LcaInternalErrStartTransaction 137 Internal error. LcaNotAllowedOnVniNetwork 138 An attempt was made to call the OpenIndependent method on a Network object which was not fetched from the VNINetworks collection.
PAGE 1050
The extension record is too large to be accessed remotely. Data Server Errors These are errors returned by the LNS Data Server. The Data Server handles network variable and message tag monitoring and control. These errors will appear in the format DS: #. The LNS values for these errors are equal to the error number plus 18,000. lcaErrDsBusy 1 Could not get semaphore to perform Data Server operation. lcaErrDsAlreadyStarted 2 Cannot start Data Server, as it was already started.
PAGE 1051
The operation specified was canceled interactively at the user interface. lcaErrDsVersionIncompatibility 16 Some of the DLLs used by the Data Server are older, incompatible versions. lcaErrDsInitValidationError 17 This indicates that the Data Server failed to initialize properly. This exception could be thrown if your application specifies an invalid name or index number when retrieving an object from the OpenLNS database. lcaErrDsUpdateRegistryFailure 18 Could not update the Windows registry.
PAGE 1052
A Network Services call to get type information for this network variable has failed. lcaErrDsStartNvObjectFailed 32 Could not start the network variable object. lcaErrDsDeleteNvObjectFailed 33 Could not delete the network variable object. lcaErrDsNvSetObjDataFailed 34 Failed to write data to the network variable object. lcaErrDsDataFormatFailure 35 An attempt to format the requested data has failed.
PAGE 1053
lcaErrDsObjectIsAlreadyStarted 49 Cannot start this object, as it is already started. lcaErrDsSetInvalidServiceType 50 Tried to set the service type to an invalid value. lcaErrDsNiIsBusy 51 Operation failed because the network interface was busy. lcaErrDsNiOpenFailure 52 Error opening the network interface. lcaErrDsNiUnknown 53 Error with the network interface. lcaErrDsCantWriteRemoteNvOutput 54 It is not possible to write a value to a remote output network variable.
PAGE 1054
lcaErrDsFmttypeHasNoFields 67 The format type specified does not contain information about fields. lcaErrDsEventSubscriptionFailed 68 Failed to subscribe to the specified event. lcaErrDsCantFindFormatCatalog 69 The format catalog could not be found. lcaErrDsCantFindStandardTypeFile 70 The specified standard type file could not be found. lcaErrDsEventDesubscriptionFailed 71 Failed to unsubscribe to the specified event.
PAGE 1055
lcaErrLnsDsNotImpl 368 Not implemented. lcaErrLnsDsPointer 369 Invalid pointer. lcaErrLnsDsInvalidArg 370 Invalid argument. One way this error can occur is if you call the Write method on a DataPoint object obtained from a NetworkVariable or NvMonitorPoint object before reading or setting its value with the DsIsDefaultFormat property, the RawValue property, or the Value property. This indicates that the DataPoint ’s buffer is empty. lcaErrLnsDsRange 371 Argument supplied is out of valid range.
PAGE 1056
Object not found. lcaErrLnsDsClientNotFound 385 Client not found. lcaErrLnsDsNetworkNotFound 386 Network not found. lcaErrLnsDsVniNotFound 387 VNI not found. lcaErrLnsDsMonitorSetNotFound 388 Monitor set not found. lcaErrLnsDsMonitorPointNotFound 389 Monitor point not found. lcaErrLnsDsNodeNotFound 390 Node not found. lcaErrLnsDsNetworkVariableNotFound 391 Network variable not found. lcaErrLnsDsAppMessageNotFound 392 Application message not found.
PAGE 1057
lcaErrLnsDsVniCloseFailed 402 There was an error closing the VNI. lcaErrLnsDsThreadCreateFailed 403 There was an error creating the thread. lcaErrLnsDsNotTemporaryMonitorSet 404 The requested operation can only be performed on temporary monitor sets. lcaErrLnsDsNotTemporaryMonitorPoint 405 The requested operation can only be performed on temporary monitor points. lcaErrLnsDsNssNotOpen 406 NSS must be opened before the requested operation can be carried out.
PAGE 1058
lcaErrLnsDsInvalidClientContext 420 Invalid or no client context was supplied. lcaErrLnsDsImplicitAddress 421 The requested operation is not allowed, as the monitor point uses implicit addressing. lcaErrLnsDsExplicitAddress 422 The requested operation is not allowed, as the monitor point uses explicit addressing. lcaErrLnsDsNotOwner 423 The requested operation is not allowed, as the client is not the owner of the object or process affected.
PAGE 1059
lcaErrFormatInvalidTypFile 5 Invalid type file. lcaErrFormatReferenceEnumScopeNotFound 6 Reference enumeration scope not found. lcaErrFormatTypeEntryNotFound 7 Type entry not found. lcaErrFormatFieldNotFound 8 Field not found. lcaErrFormatIllegalBaseType 9 Format specifier is not valid for this type or field. lcaErrFormatAchNotFound 10 Format file not found. lcaErrFormatStringIllegal 11 Illegal string. lcaErrFormatStringExceedsBounds 12 Array index exceeds array size.
PAGE 1060
lcaErrFormatNotBuiltInSpec 23 Not built in spec. lcaErrFormatInvalidPropSet 24 Invalid prop set. lcaErrFormatInvalidBaseType 25 Invalid base type. lcaErrFormatFmtNotFound 26 Format not found. lcaErrFormatInvalidDefaultType 27 Invalid default type. lcaErrFormatUnknownError 28 Unknown error. lcaErrFormatFileNotFoundInCatalog 29 File not found in catalog. lcaErrFormatCatalogNotOpened 30 Catalog not opened. lcaErrFormatEnumNotFound 31 Enumeration not found.
PAGE 1061
Duplicate string provided. This exception will be thrown if you write to the CategoryPreferenceList property and specify the same format more than once. lcaErrFormatLocaleStringNotFound 41 Locale string not found. lcaErrFormatCatalogNotFound 200 Catalog not found. lcaErrFormatInvalidProgramId 201 Invalid program ID. lcaErrFormatLdrfErr 202 LDRF error. lcaErrFormatLdrfErrParam 203 LDRF error: bad parameter. lcaErrFormatLdrfErrFileType 204 LDRF error: bad file type.
PAGE 1062
LDRF error: full. lcaErrFormatLdrfErrDuplicate 216 LDRF error: duplicate. lcaErrFormatLdrfErrNotCatalog 217 LDRF error: not catalog. lcaErrFormatLdrfErrNotResource 218 LDRF error: not resource. lcaErrFormatLdrfErrNotType 219 LDRF error: not type. lcaErrFormatLdrfErrNotFpt 220 LDRF error: not FTP. lcaErrFormatLdrfErrNotFormat 221 LDRF error: not format. lcaErrFormatLdrfErrTypeTree 222 LDRF error: bad type tree. lcaErrFormatLdrfErrIncomplete 223 LDRF error: incomplete.
PAGE 1063
Remote object does not exist. lcaErrRmoNoIpcMsgAvail 5 No Windows Inter Process Communication (IPC) message available. lcaErrRmoIpcUnknownError 6 Unknown Windows Inter Process Communication (IPC) error. lcaErrRmoIpcMsgError 7 Windows Inter Process Communication (IPC) messaging error. lcaErrRmoIpcResourceProblem 8 Windows Inter Process Communication (IPC) resource problem. lcaErrRmoIpcOutOfMemory 9 Windows Inter Process Communication (IPC) subsystem is out of memory.
PAGE 1064
LonTalk Adapter name too long. lcaErrLtaInvalidState 309 LonTalk Adapter invalid state. lcaErrLtaNoResources 310 LonTalk Adapter no resources. lcaErrLtaDuplicateObject 311 LonTalk Adapter duplicate object. lcaErrLtaNotImplemented 312 LonTalk Adapter not implemented. lcaErrLtaEndOfEnumeration 313 LonTalk Adapter end of enumeration. lcaErrLtaOwnerDoesNotExist 314 LonTalk Adapter owner does not exist. lcaErrLtaInvalidIndex 315 LonTalk Adapter invalid index.
PAGE 1065
LonTalk Adapter error log mask. lcaErrLtaNvLengthMismatch 430 LonTalk Adapter network variable length mismatch. lcaErrLtaNvMsgTooShort 431 LonTalk Adapter network variable message too short. lcaErrLtaEepromWriteFailure 432 LonTalk Adapter EEPROM write failure. lcaErrLtaBadAddressType 433 LonTalk Adapter bad address. lcaErrLtaInvalidDomain 438 LonTalk Adapter invalid domain. lcaErrLtaInvalidAddrTableIndex 441 LonTalk Adapter invalid address table index.
PAGE 1066
Out of memory (registry subsystem). lcaErrVniRegCantFindObject 604 Cannot find object (registry subsystem). lcaErrVniRegResourceProblem 605 Resource problem (registry subsystem). lcaErrVniRegOutOfRange 606 Parameter out of range (registry subsystem). lcaErrVniRegNoMoreEntries 607 No more entries (registry subsystem). lcaErrVniRegCantOpenRegistry 608 Cannot open registry. lcaErrVniRegUnknownRegistryError 609 Unknown error (registry subsystem).
PAGE 1067
Message monitor point not found. lcaErrVniMustSpecifyMsgTag 622 Must specify message tag. lcaErrVniMsgTagNotFound 623 Message tag not found. lcaErrVniOutOfTemporaryMonitorPoints 624 Monitor set ran out of temporary monitor points due to capacity constraints. lcaErrVniOutOfTemporaryMonitorSets 625 VNI stack ran out of temporary monitor sets due to capacity constraints. lcaErrVniAddPointToPersistentMonitorSet 626 Attempted to add a point to a persistent monitor set.
PAGE 1068
Configuration file could not be found. lcaErrVniRegCannotUpdateConfigFile 640 Configuration file could not be updated. lcaErrVniThreadCreationFailure 641 Failed to create thread. lcaErrVniDumpLtipXmlConfigFailed 642 XML configuration failed. lcaErrVniNotSupportedOnL5Mip 643 The requested operation is not supported on a Layer 5 network interface. lcaErrVniInvalidMessagePointOptions 644 Invalid message point options.
PAGE 1069
OpenLNS Programmer's Reference 1032
PAGE 1070
Appendix A Deprecated Items This appendix lists methods, properties, and objects that should no longer be used in OpenLNS.
PAGE 1071
Deprecated Items In OpenLNS and LNS Turbo Editions, some methods, objects, properties and events have been deprecated. This section provides a list of those items. Some have been deprecated because they were never implemented in LNS, or because they are no longer applicable or useful. Others have been deprecated because they have been replaced by new features with better functionality.
PAGE 1072
Deprecated Objects The following objects have been deprecated in OpenLNS and LNS Turno Editions (3.2). This means that you should no longer use the object, or any of its properties and methods, in your applications. Version Reason 3.2 U BuildTemplates 3.2 U HardwareTemplate 3.2 U HardwareTemplates 3.2 U NetworkVariableFiel d 3.2 BA Object BuildTemplate Substitute Feature Use DataPoint objects to read and write the values of the network variables and network variable fields on your network.
PAGE 1073
Deprecated Methods The following methods have been deprecated in OpenLNS and LNS Turbo Editions (3.2). This means that you should no longer use these methods in your applications. Note that the parent objects of these methods have not been deprecated unless those objects are listed in the Deprecated Objects section. Method Applicable Parent Object Version Reason BeginLicense System 4.0 NLA Build AppDevice System 3.2 U CloseComponent AppDevice 3.2 U DebitLicense System 4.
PAGE 1074
Method Applicable Parent Object Version Reason OpenComponent AppDevice 3.2 U Purge Interface 3.2 BA RecoverFromNssDb System 3.2 U Remove Networks 3.2 BA RestoreLicense System 4.0 NLA SetCapacity System 3.2 NLA SetCustomerInfo ObjectServer 4.0 NLA SetElement ConfigProperty 3.2 BA SetLicenseInfo ObjectServer 4.0 NLA SetLicenseInfoEx ObjectServer 4.0 NLA SetRawValues ConfigProperty 3.2 BA System 3.
PAGE 1075
Deprecated Properties The following propeties have been deprecated in OpenLNS and LNS Turbo Editions (3.2). This means that you should no longer use these properties in your applications. Note that the parent objects of these methods have not been deprecated unless those objects are listed in the Deprecated Objects section. Property Applicable Parent Object Version Reason ActiveXComponent AppDevice 3.2 U BuildStatus AppDevice DeviceTemplate ProgramTemplate ProgramTemplate System 3.2 U 3.
PAGE 1076
Property Applicable Parent Object Version Reason DataServerObjectHandle System 3.2 NLA DaysRemaining System 4.0 NLA DefecitCredits CreditInfo 4.0 NLA DsAuthenticate NetworkVariable NetworkVariableField 3.2 BA DsAutoUpdate NetworkVariable 3.2 U DsEventSubscription System 3.2 NLA DsFormatFilesPath System 3.2 NLA DsMessageOwner System 3.2 NLA DsMode System 3.2 NLA DsMonitorTag NetworkVariable NetworkVariableField 3.
PAGE 1077
Property Applicable Parent Object Version Reason Substitute Feature when displaying network variable values. DsPriority NetworkVariable NetworkVariableField 3.2 BA Use temporary monitor sets instead of singlepoint monitoring. You can use the Priority property of the MsgMonitorOptions and NvMonitorOptions objects to determine the priority assigned to each message. For more information on temporary monitor sets, see Chapter 9 of the OpenLNS Programmer’s Guide.
PAGE 1078
Property Applicable Parent Object Version Reason Substitute Feature DsService NetworkVariable NetworkVariableField System 3.2 BA Use temporary monitor sets instead of singlepoint monitoring. You can use the ServiceType property of the MsgMonitorOptions and NvMonitorOptions objects to determine the service type to apply to the temporary monitor points. For more information on temporary monitor sets, see Chapter 9 of the OpenLNS Programmer’s Guide.
PAGE 1079
Property Applicable Parent Object Version Reason MaxDefecitCredits CreditInfo 4.0 NLA MaximumDeviceCapacity System 4.0 NLA ProgramTemplate DeviceTemplate 3.2 U ProgramTemplates TemplateLibrary 3.2 U RawValue ConfigProperty 3.2 BA Use DataPoint objects to read and write to the values of all configuration properties and configuration property arrays. You can use the GetDataPoint method of the ConfigProperty object to begin this procedure. RemoteIgnorePendingUpdate Network 3.
PAGE 1080
Property ValueFromDevice Applicable Parent Object Version Reason Substitute Feature ConfigProperty 3.2 BA Use DataPoint objects to read and write the value of the ConfigProperty objects on your network. You can use the GetDataPoint method to acquire a DataPoint for reading or writing the value of a configuration property. Deprecated Events The following events have been deprecated in OpenLNS and LNS Turno Editions (3.2).
PAGE 1081
www.echelon.