
Chapter 20. Working With Data
Prev	Cogent DataHub^™ software	Next

Chapter 20. Working With Data

This chapter gives an overview of how the DataHub program handles data and the various protocols it works with.

20.1. Data Points

Each value stored in the DataHub program is called a point. A point has the following attributes:

Name A character string. Currently the only limit on length is internal buffer size, about 1000 bytes by default.

Value An integer, floating-point number, or character string.


	All string values and point names in a DataHub instance are stored as UTF-16. They are transmitted using UTF-8, which means that custom applications that interact with a DataHub instance via a TCP connection need to encode strings and point names as UTF-8.

Time The date and time of the last significant change to the point's value, confidence, quality or other status information. In general, all timestamps in the DataHub program are in UTC time, and only converted to local time for the purpose of display.
Quality The quality of the connection, assigned by the DataHub program for this point, such as Good, Bad, Last known, Local override, etc. Please refer to the quality command documentation for a complete list.
Type A character string representing the Windows variant type of the point value. Please see below for a complete list.
Confidence A value from 0 to 100 that indicates as a percentage the probability that the value shown for the point is actually its true value. This feature can be accessed and changed only by using the API. The DataHub program never uses confidence itself, but carries it for use by client applications.

20.1.1. Creating New Points

A DataHub instance automatically creates a point whenever a connecting program tries to read, write, or create a point that doesn't exist. When the point is created, the DataHub instance assigns its value, time, quality, and confidence.


	The OPC UA protocol does not support the ability for a client to create OPC tags on a server. However, you can use the Automatically create unknown items requested by the client option in the DataHub OPC UA server Advanced configuration to enable it.

It is possible to have the DataHub instance create points and assign values to them at startup. Sometimes referred to as seeding, this is done with supplemental configuration files. Please refer to Section 1.8, “Configuration Files” for more details. It is also possible to create a point in a DataHub script, using the datahub_write function. In a similar way, sending a DataHub command like cset will create a point, if it does not already exist. Another option is to use the Bridging feature to create new points.

20.1.2. Deleting Points

You can delete data points from the Data Browser. Please see Deleting Points in the Data Browser chapter for details

However, it is not possible to completely delete points from a DataHub instance. This is because a connecting process may be using that point. Performance does not suffer if there are unused points in the system, but some users prefer to remove them to just keep things tidy. Should a point no longer be in use or requested by any participating program, when the DataHub instance is shut down and restarted, the point will no longer appear. For multiple DataHub instances connected via a tunnel/mirror connection, all of them must be shut down together to ensure that a point is deleted.

20.1.3. Viewing Data Points

You can view the values of all data points with the Data Browser. You can also create a dump of a DataHub instance's current point list by issuing this command in the Script Log entry field:

datahub_command("(dump \"c:/temp/datahub.dump\")", 1)

20.1.4. Point Size Limits

The DataHub program limits the size of a message to 128 MB. The size of a point message is the length of the value plus the length of the point name plus ~60 bytes. A string value may include escaped characters or non-ASCII UTF-8 characters, such that it takes more than one byte to represent a single character. The result is that the maximum length of the character-encoded value of a point could be substantially less than the 128 MB limit, depending on the characters being transmitted.

If you intend to share data with Linux computers through a custom connection, there is a limit of 128,000 bytes per message.

In any case, bear in mind that very large values will take some time to be transmitted over a network, and can impose a large CPU and memory burden on a DataHub instance.

20.1.5. Data Types

The DataHub program supports the following Windows variant data types:

Windows variant type	DataHub string	Description
`VT_BOOL`	`bool`	Boolean (1 = TRUE, 0 = FALSE)
`VT_BSTR`	`bstr`	Text string
`VT_BSTR`	`string`	Text string. All string values and point names in a DataHub instance are stored as UTF-16. They are transmitted using UTF-8, which means that custom applications that interact with a DataHub instance via a TCP connection need to encode strings and point names as UTF-8.
`VT_CY`	`cy`	Currency
`VT_DATE`	`date`	Date
`VT_DECIMAL`	`decimal`	Decimal number
`VT_EMPTY`	`any`	No type specified, or unknown
`VT_I1`	`i1`	1-byte signed character
`VT_I2`	`i2`	2-byte signed integer
`VT_I4`	`i4`	4-byte signed integer
`VT_I8`	`i8`	8-byte signed integer
`VT_INT`	`int`	Integer
`VT_R4`	`r4`	4-byte real number
`VT_R8`	`r8`	8-byte real number
`VT_UI1`	`ui1`	1-byte unsigned character
`VT_UI2`	`ui2`	2-byte unsigned integer
`VT_UI4`	`ui4`	4-byte unsigned integer
`VT_UI8`	`ui8`	8-byte unsigned integer
`VT_UINT`	`uint`	Unsigned integer
`VT_VARIANT`	`variant`	Variant
`VT_BOOL \| VT_ARRAY`	`bool array`	Boolean array
`VT_BSTR \| VT_ARRAY`	`bstr array`	Text string array
`VT_BSTR \| VT_ARRAY`	`string array`	Text string array
`VT_CY \| VT_ARRAY`	`cy array`	Currency array
`VT_DATE \| VT_ARRAY`	`date array`	Date array
`VT_DECIMAL \| VT_ARRAY`	`decimal array`	Decimal array
`VT_I1 \| VT_ARRAY`	`i1 array`	1-byte signed character array
`VT_I2 \| VT_ARRAY`	`i2 array`	2-byte signed integer array
`VT_I4 \| VT_ARRAY`	`i4 array`	4-byte signed integer array
`VT_I8 \| VT_ARRAY`	`i8 array`	8-byte signed integer array
`VT_INT \| VT_ARRAY`	`int array`	Integer array
`VT_R4 \| VT_ARRAY`	`r4 array`	4-byte real number array
`VT_R8 \| VT_ARRAY`	`r8 array`	8-byte real number array
`VT_UI1 \| VT_ARRAY`	`ui1 array`	1-byte unsigned character array
`VT_UI2 \| VT_ARRAY`	`ui2 array`	2-byte unsigned integer array
`VT_UI4 \| VT_ARRAY`	`ui4 array`	4-byte unsigned integer array
`VT_UI8 \| VT_ARRAY`	`ui8 array`	8-byte unsigned integer array
`VT_UINT \| VT_ARRAY`	`uint array`	Unsigned integer array
`VT_VARIANT \| VT_ARRAY`	`variant array`	Variant array

20.1.6. Coercing a Number to a `DATE` Type

Any number value sent to a DATE type is checked for type. If the value is not a DATE type, the DataHub engine coerces it to a DATE type as follows:

A value of 0 appears as Jan 1, 1970 (UNIX epoch start)
A value greater than 0 and less than or equal to 1,000,000 is treated as an OADate (days since midnight, December 30, 1899).
A value greater than 1,000,000 and less than or equal to 10,000,000,000 is treated as UNIX seconds.
All other values are treated as UNIX milliseconds (JSON timestamp)

Prev	Up	Next
19.3. DataHub Windows Scripting	Home	20.2. Data Communication Concepts