HistorianConnect

(Engine-Level Function)

Description	Opens a logging connection and controls the lifetime of all resources associated with that connection.
Warning	This function should be used only by advanced programmers. The functions, WriteHistory and GetTagHistory and GetLog are recommended for most uses.
Returns	Invalid if the parameters are invalid, 0 otherwise
Usage	Script Only.
Threaded	Yes
Function Groups	Logging
Related to:	HistorianDeleteRecords \| HistorianGetData \| HistorianGetInfo \| HistorianReadRecords \| HistorianWriteRecords
Format	HistorianConnect(ConnectionType, ConnectionString, HistorianName, Namespace, HistorianHandle, Error[, SchemaToTableNameDict, UptimeTagName])
Parameters

ConnectionType

A text keyword that indicates the storage methodology required. Permitted values are

FileDB for storage on a local or networked hard drive, using the VTScada proprietary database format.
ODBC for storage using a local or networked DBMS, accessed via ODBC drivers.

The keywords are not case-sensitive.

ConnectionString

A text string that provides the information required to connect to the database specified by the ConnectionType. (Non-ASCII characters will be removed.)

ConnectionType	ConnectionString
FileDB	The root path to the storage folder. If a relative path is provided, then it is relative to the VTScada installation directory
ODBC	Any valid ODBC connection string. This may begin with DSN= to specify a data source name, or it may be a complete connection string.

HistorianName

An ASCII text string (letters and numbers only) providing the Historian Tag Name. This string is used as part of the full path to a file-based data store and is also the name of the UpTime table in the database.

Namespace

The top-level namespace in which to store data (may be an empty string).

Non-ASCII characters will be removed.

HistorianHandle

Historian Connection handle value. For the VTScada proprietary data store, this will be invalidated on an "out of disk space" error, or on loss of access to the file storage. For other databases, this will be invalidated on any connection loss.

Error

A value in which the error code, (if any) will be returned.

Defined error codes are provided in the reference chapter. See: Historian Error Codes

SchemaToTableNameDict

Optional dictionary. Maps historian schema strings to table names for use with ODBC-backed historians. Typically assembled from the HistorianODBCTableNames0 ... HistorianODBCTableNamesN settings, with the dictionary key consisting of the schema string and the value specifying the table name.

UptimeTagName

Optional Text. Specifies the table name to use when accessing VTScada uptime history. When not specified the value given in the HistorianName parameter is substituted.

Comments

The connection to the data store is done asynchronously. HistorianHandle will become valid when the connection has been made. If the connection fails Error will be set to some sort of error information.
Each separate connection will create its own thread for writing data. Invalidating the connection handle will flush all pending write data and then terminate the thread, DB connections etc.
The Namespace parameter may be used to allow the same root storage location to be shared by multiple applications or machines or both.

The UptimeTagName parameter ensures that the uptime can be obtained regardless of whether StorageName parameters vary from one server to another for the same Historian. Without this parameter, and with a typical Historian tag configuration, the HistorianName is derived from the Historian tag's "Storage Name" parameter. If this varies by machine (for example where a parameter expression is used to derive a different values across workstations), it can lead to an incomplete view of the overall VTScada uptime and in turn lead to inconsistent invalidation of data returned from the historian depending on the workstation performing the query.

Example:

No example provided. WriteHistory and GetTagHistory are recommended for most use.