![SWTB_logo_rgb_color_mode-wPadding-2000x961.png]](https://help.softwaretoolbox.com/hs-fs/hubfs/SWTB_General/Images/Press_Kit/SWTB_logo_rgb_color_mode-wPadding-2000x961.png?height=50&name=SWTB_logo_rgb_color_mode-wPadding-2000x961.png){kind=logo}
Table of Contents
Introduction [Back to top]
TOP Server makes available a number of auto-generated tags that give insight into the status of communications, and track diagnostics information to help show the current and past state of the server. This exposes valuable information to client applications, which can be used to not only monitor server communications, but can be used to help identify problems before they start having a financial impact. This document is intended to give an overview of the System and Statistic Tags that are available in TOP Server. This document will focus on the general – server level – tags that exist in the TOP Server, and will not cover the driver specific tags that some drivers expose. Please refer to the appropriate driver help file for a list of additional system/statistic tags that are available.
The rest of the document is structured to show at what level the tags can be found, and give a short description what information the tag exposes. More information on these tags can be found in the TOP Server help file, or by contacting our support team.
Server Level Tags [Back to top]
Server Level System Tags [Back to top]
The server level system tags can be accessed by accessing the _System tag group, browsable when a client connects to the TOP Server:
These tags will provide information on the current project, clients that are connected, and overall server information.
Server level system tags include:
Tag Name |
Tag Access |
Description |
| _ActiveTagCount | Read | The number of tags that are currently active in the server. |
| _ClientCount | Read | The number of clients that are currently connected to the server. |
| _Date | Read | The current date of the system that the server is running on. |
| _DateTime | Read | The GMT date and time of the system that the server is running on. |
| _DateTimeLocal | Read | The localized date and time of the system that the server is running on. |
| _Date_Day | Read | The current day of the month of the system on which the server is running. |
| _Date_Month | Read | The current numeric month of the system on which the server is running. |
| _Date_Year2 | Read | The last two digits of the current year of the system on which the server is running |
| _Date_Year4 | Read | The current year of the system on which the server is running |
| _FullProjectName | Read | The fully qualified path and file name to the currently loaded project. |
| _IsDemo | Read | The _IsDemo tag indicates whether the server is running in Demo Mode. 1 = Currently In Demo Mode, 0 = Not in demo mode. |
| _OpcClientNames | Read | The names of all OPC clients that connect to the server and register their name. |
| _ProjectName | Read | The currently loaded project file name and does not include path information. |
| _ProjectTitle | Read | The title of the project that is currently loaded. |
| _Time | Read | The current time of the system that the server is running on. |
| _TotalTagCount | Read | The total number of tags that are currently being accessed. These tags can be active or inactive. |
| _Time_Hour | Read | The current hour of the system on which the server is running. |
| _Time_Hour24 | Read | The current hour of the system on which the server is running in a 24 hour format. |
| _Time_Minute | Read | The current minute of the system on which the server is running. |
| _Time_PM | Read | The current AM/PM status of the system on which the server is running. 0 = AM, 1 = PM |
| _Time_Second | Read | The current second of the system on which the server is running. |
Channel System Tags [Back to top]
Channel level system tags can be accessed via the _System tag group found at the channel level:
These tags give control over channel and driver level settings from client applications. What tags are available will vary depending if a Serial or Ethernet protocol was chosen.
Changes that are made to these tags will affect channel wide settings, and thereby all devices configured for the Channel.
Serial Channels [Back to top]
TOP Server Channels configured for a Serial protocol will expose the following tags:
Tag Name |
Tag Access |
Description |
| _AvailableNetworkAdapters | Read | Lists the available NICs including NICs with multiple IPs assigned to them. |
| _BaudRate | Read/Write | Changes the baud rate of the driver. Valid baud rates are: 300, 600, 1200, 2400, 4800, 9600, 19200, 38400, 56000, 56700, 115200, 128000, and 256000. |
| _ComId | Read/Write | Changes the COM port selection for the driver. Should be in the format: COM # |
| _DataBits | Read/Write | Changes the data bits of the driver. Valid values are 5, 6, 7 and 8. |
| _EnableDiagnostics | Read/Write | Enables (1)/Disables (0) Channel Diagnostics. |
| _EthernetEncapsulationPort | Read/Write | Sets the Ethernet port that has been opened to allow connections. The valid range is 0 to 65535. |
| _EthernetEncapsulationProtocol | Read/Write | Sets the Ethernet protocol used to connect to the Unsolicited Encapsulation Port. Options include TCP/IP and UDP. |
| _FloatHandlingType | Read/Write | Sets how the Driver will handle Non-normalized Float values. Valid Strings are "Unmodified" or "Replaced with zero" |
| _FlowControl | Read/Write | Changes the flow control setting of the driver.Valid strings are: None, DTR, RTS, "DTR, RTS," RTS Always, and RTS Manual. Not all drivers support the RTS Manual mode of operation. |
| _InterDeviceDelayMS | Read/Write | Specifies the amount of time that the channel will wait before polling the next device on the channel. The valid range is 0 (default) to 60000 milliseconds. This tag is only available on channels that support Inter-Device delay |
| _NetworkAdapter | Read/Write | Changes the current NIC adapter in use by the driver. The name of the newly desired NIC adapter must be written to this tag in string format and must match the exact description of the new adapter. For a serial driver, this tag will only be used if Ethernet Encapsulation is selected. When changing the NIC selection the driver will be forced to break all current device connections and reconnect. |
| _Parity | Read/Write | Changes the parity of the driver. Valid string entries are: None, Odd or Even. |
| _ReportComErrors | Read/Write | Enables (1)/Disables (0) the reporting of low level communications errors such as parity and framing errors. If the environment contains significant interference, this feature can be disabled to prevent the Event Log from filling with error messages. |
| _RtsLineDrop | Read/Write | Lowers the RTS Line for a user-specified period of time after the driver attempts to transmit a message. This tag will only be effective for drivers that support Manual RTS mode. The valid range is 0 to 9999 milliseconds. The Manual RTS mode has been designed for use with radio modems. |
| _RtsLinePollDelay | Read/Write | Introduces a user specified pause after each message sent from the driver. This tag will only be effective for drivers that support Manual RTS mode. The valid range is 0 to 9999 milliseconds. The Manual RTS mode has been designed for use with radio modems. |
| _RtsLineRaise | Read/Write | Raises the RTS line for the specified period of time before the driver attempts to transmit a message. This tag will only be effective for drivers that support Manual RTS mode. The valid range is 0 to 9999 milliseconds. The Manual RTS mode has been designed for use with radio modems. |
| _SharedConnection | Read | Indicates that the port settings are being shared with another channel. |
| _StopBits | Read/Write | Sets the number of stop bits of the driver. Valid entries are 1 and 2 |
| _WriteOptimizationDutyCycle | Read/Write | Sets the number of writes that will be performed for every one read. Valid range is 1-10 |
Ethernet Channels [Back to top]
TOP Server Channels configured for an Ethernet protocol will expose the following tags:
Tag Name |
Tag Access |
Description |
| _AvailableNetworkAdapters | Read | Lists the available NICs including NICs with multiple IPs assigned to them. |
| _EnableDiagnostics | Read/Write | Enables (1)/Disables (0) Channel Diagnostics. |
| _FloatHandlingType | Read/Write | Sets how the Driver will handle Non-normalized Float values. Valid Strings are "Unmodified" or "Replaced with zero" |
| _InterDeviceDelayMS | Read/Write | Specifies the amount of time that the channel will wait before polling the next device on the channel. The valid range is 0 (default) to 60000 milliseconds. This tag is only available on channels that support Inter-Device delay |
| _NetworkAdapter | Read/Write | Changes the current NIC adapter in use by the driver.The name of the newly desired NIC adapter must be written to this tag in string format and must mach the exact description of the new adapter. For a serial driver, this tag will only be used if Ethernet Encapsulation is selected. When changing the NIC selection the driver will be forced to break all current device connections and reconnect. |
| _WriteOptimizationDutyCycle | Read/Write | Sets the number of writes that will be performed for every one read. Valid range is 1-10 |
Serial and Ethernet Device System Tags [Back to top]
Device level system tags can be accessed via the _System tag group found at the device level:
These tags will give insight into the current state of the device, and give control over device settings – allowing changes to be made from client applications.
Changes that are made to these tags will only change settings for the device they were changed for. The available tags may change slightly depending on the model of device, and the channel level protocol settings:
Tag Name |
Tag Access |
Description |
| _AutoCreateTagDatabase | Read/Write | When set to True (1), the driver will attempt to automatically generate an OPC tag database for this device. This tag will not appear for drivers that do not support Automatic OPC Tag Database Generation. |
| _AutoDemoted | Read | When False (0), the device is not demoted and is being scanned by the driver. When set True(1), the device is demoted and not being scanned by the driver. |
| _AutoDemotionDiscardWrites | Read/Write | Enables (1)/Disables (0) the discarding of write requests while a device is demoted. When False writes will be performed regardless of the demotion state. |
| _AutoDemotionEnabled | Read/Write | Determines whether a device should be automatically demoted for a specific time period when the device is unresponsive. 0 = Do not auto-demote, 1 = Auto-demote |
| _AutoDemotedFailureCount | Read/Write | Specifies how many successive failures it takes to demote a device. The valid range is 1 to 30 and can only be written to if _AutoDemotionEnabled is set to True. |
| _AutoDemotionIntervalMS | Read/Write | Specifics how long, in milliseconds, a device will be demoted before re-attempting to communicate with the device. The valid range is 100 to 3600000 milliseconds. This tag can only be written to if _AutoDemotionEnabled is set to True. |
| _ConnectTimeout | Read/Write | Sets how long to wait, when making an IP connection to a device, before timing out. This tag is available when either a native Ethernet driver is in use or a serial driver is in Ethernet Encapsulation mode. The valid range is 1 to 30 seconds. |
| _DemandPoll | Read/Write | Issues a device read to all the active client items associated with the device. This is the equivalent of a client performing an asynchronous device read for those items. It takes priority over any scheduled reads that are supposed to occur for items that are being actively scanned. This tag will stay high (1) while the poll is executing, and will then automatically reset (0). |
| _DeviceId | Read/Write | Changes the ID of the device and thereby changes the target field device for the server. For most serial devices this tag will be a Long data type. For Ethernet drivers this tag will be a string tag, allowing the entry of an IP address. |
| _Enabled | Read/Write | Determines whether the device is active or not (Turned on or off). When False (0), all user-defined tags and data from this device will be marked as invalid and writes will not be accepted for the device. |
| _EncapsulationIp | Read/Write | Specifies the IP Address of a remote terminal server. This tag is only valid for a serial driver in Ethernet Encapsulation mode. |
| _EncapsulationPort | Read/Write | Sets the port number of the remote terminal server. The valid range is 0 to 65535. This tag is only valid for a serial driver in Ethernet Encapsulation mode. |
| _EncapsulationProtocol | Read/Write | Sets the IP protocol used for Ethernet Encapsulation. Valid string entries are "TCP/IP" or "UDP". This tag is only valid for a serial driver in Ethernet Encapsulation mode. |
| _Error | Read | Indicates whether a device is in an error state. When False (0), the device is operating properly. When True (1), the device has gone through a complete cycle of request timeouts and retries without a response. |
| _FailedConnection | Read | Specifies whether the connection has failed. It is not available for all drivers. |
| _InterRequestDelay | Read/Write | Sets the time interval between device transactions. The valid range is 0 to 30000 milliseconds. This tag only applies to drivers that support this feature. |
| _RequestAttempts | Read/Write | Sets the number of retry attempts when requesting data from a device. The valid range is 1 to 10 retries. This tag applies to all drivers equally. |
| _RequestTimeout | Read/Write | Sets the timeout period when requesting data from the device. The valid range is 100 to 30000 milliseconds. This tag applies to all drivers equally. |
| _NoError | Read | Indicates whether a device is in an error state. When True (1), the device is operating properly. When False (0), the device has gone through a complete cycle of request timeouts and retries without a response. |
| _ScanMode | Read | This tag specifies the scan method that will be used for updates. Valid string entries are: "UseClientRate", "UseFloorRate", "ForceAllToFloorRate" |
| _ScanRateMs | Read | When the _ScanMode parameter is set to "Request data no faster than x" or "Request all data at x" this tag determines the Scan Rate in milliseconds. The default setting is 1000 milliseconds. |
| _SecondsInError | Read | The number of seconds since the device entered an error state. This tag displays 0 when the device is not in an error state. |
| _Simulated | Read | Determines whether the device is in simulate mode. When True (1) the device is in simulate mode and the server will return good quality data but not attempt to communicate with the actual device. When False (0), communication with the physical device will be active. |
Channel Statistics Tags [Back to top]
Similar to Channel-level System tags, Channel-level statistic tags can be accessed via the _Statistics tag group at the channel level.
These tags will keep track of key statistics for the channel, a summation of the statistics of all devices configured thereunder, and will give an indication of how the channel is performing to client applications. These statistics can be used to proactively identify potential problems such as polling queues (pending reads and writes), or connection problems (failing reads and writes). In order for these tags to be active, the Communication Diagnostics have to be enabled in the channel properties, found in the TOP Server configuration.
Tag Name |
Tag Access |
Description |
| _SuccessfulReads | Read | A count of the number of reads this channel has completed successfully since the start of the application or since the last time the _Reset tag was invoked. |
| _SuccessfulWrites | Read | A count of the number of writes this channel has completed successfully since the start of the application or since the last time the _Reset tag was invoked |
| _FailedReads | Read | A count of the number of reads this channel has failed to complete since the start of the application or since the last time the _Reset tag was invoked. This count is only incremented after the channel has failed the request based on the configured timeout and retry count for the device. |
| _FailedWrites | Read | A count of the number of writes this channel has failed to complete since the start of the application or since the last time the _Reset tag was invoked. This count is only incremented after the channel has failed the request based on the configured timeout and retry count for the device. |
| _RxBytes* | Read | A count of the number of bytes the channel has received from connected devices since the start of the application or since the last time the _Reset tag was invoked. |
| _TxBytes | Read | A count of the number of bytes the channel has sent to connected devices since the start of the application or since the last time the _Reset tag was invoked. |
| _Reset | Read/Write | Writing a non-zero value to this tag will reset all diagnostic counters for the Channel. |
| _MaxPendingReads | Read | A count of the maximum number of pending read requests for the channel since the start of the application (or the _Reset tag) was invoked. |
| _MaxPendingWrites | Read | A count of the maximum number of pending write requests for the channel since the start of the application (or the _Reset tag) was invoked |
| _PendingReads | Read | A count of the current pending read requests for the channel. |
| _PendingWrites | Read | A count of the current pending write requests for the channel. |
Device Specific Statistics Tags [Back to top]
The Device-level Statistics tags, similar to the channel level ones, can be accessed via the _Statistics tag group found at the Device level.
These tags take the Channel-level statistics and break them down to a ‘per device’ basis. They can be used to track device specific performance from a client application, and identify problem devices that may be affecting communications on the channel. Similar to the Channel-level tags, the Communication diagnostics have to be enabled in the Channel properties in order for these tags to be active.
Tag Name |
Tag Access |
Description |
| _SuccessfulReads | Read | A count of the number of reads this channel has completed successfully since the start of the application or since the last time the _Reset tag was invoked. |
| _SuccessfulWrites | Read | A count of the number of writes this channel has completed successfully since the start of the application or since the last time the _Reset tag was invoked. |
| _FailedReads | Read | A count of the number of reads this channel has failed to complete since the start of the application or since the last time the _Reset tag was invoked. This count is only incremented after the channel has failed the request based on the configured timeout and retry count for the device. |
| _FailedWrites | Read | A count of the number of writes this channel has failed to complete since the start of the application or since the last time the _Reset tag was invoked. This count is only incremented after the channel has failed the request based on the configured timeout and retry count for the device. |
| _RxBytes* | Read | A count of the number of bytes the channel has received from connected devices since the start of the application or since the last time the _Reset tag was invoked. |
| _TxBytes | Read | A count of the number of bytes the channel has sent to connected devices since the start of the application or since the last time the _Reset tag was invoked. |
| _Reset | Read/Write | Writing a non-zero value to this tag will reset all diagnostic counters for the Device. |
Virtual Network (_Serialization) [Back to top]
In system architectures where a “single channel multiple devices” configuration, and a virtual network configuration are possible, the virtual network should always be preferred due to the additional diagnostics that’s that are available. These additional tags can be accessed via the _CommunicationSerialization tab at the Channel level.
These tags will give statistic information on the performance of the virtual network (such as how long a channel had ownership of communications). The _NetworkOwner tag in particular is noteworthy, as it will allow a client application to monitor which channel/device is currently active.
The additional tags exposed in a virtual network configuration are listed below:
Tag Name |
Tag Access |
Description |
| _NetworkOwner | Read | Indicates if the channel currently owns control of communications on the network. |
| _Registered | Read | Indicates whether the channel is currently registered to a virtual network. This tag is False (0) if _VirtualNetwork is None. |
| _RegisteredTo | Read | Indicates the virtual network to which the channel is currently registered. This tag reads N/A if _VirtualNetwork is None. |
| _StatisticAvgNetworkOwnershipTimeSec | Read | Indicates the average period of time the channel holds ownership of control since the start of the application (or since the last time _StatisticsReset was written to). This tag helps identify busy channels/bottlenecks. |
| _StatisticNetworkOwnershipCount | Read | Indicates the number of times the channel has been granted control of communications since the start of the application (or since the last time _StatisticsReset was written to). |
| _StatisticNetworkOwnershipTimeSec | Read | Indicates how long in seconds the channel has held ownership since the start of the application (or since the last time _StatisticsReset was written to). |
| _StatisticsReset | Read/Write | Writing a non-zero value to this tag will reset all serialization statistic tags for the Channel |
| _TransactionsPerCycle | Read/Write | Indicates the number of read/write transactions that occur on the channel when taking turns with other channels in a virtual network. Valid range is 1 (default) to 99. |
| _VirtualNetwork | Read/Write | Allows the virtual network selection for the channel to be changed by a client. Valid strings are: "None", "Network 1", "Network 2", … , "Network 50". To disable communication serialization, select None. |
Conclusion [Back to top]
This document is intended to give an overview on the Statistic and System tags that are available in TOP Server. This list is fairly comprehensive, but the TOP Server help file should be consulted for further information on any tags that are not specifically described in this document.
The Software Toolbox Support team would also be more than happy to provide any additional information on the use of these tags, and can be reached via: