Connecting to the Historian

Before any historian-related operation can be performed, a historian connection proxy object of class HistorianAccess must be created first. The existence of that object does not imply that an actual physical connection is established with the historian server. For example, the historian server computer may be unavailable at that time, but the managed HCAL application can still create and store streamed data locally in the provided store-and-forward folder. To initiate an asynchronous server connection, the OpenConnection() method of the HistorianAccess object must be called where a HistorianConnectionArgs object must be provided with connection arguments.

Example

HistorianAccess historian = new HistorianAccess();
HistorianConnectionArgs connectionArgs = new HistorianConnectionArgs();
connectionArgs.ServerName = "HistorianComputer";
connectionArgs.UserName = "MyDomain\\MyUserName";
connectionArgs.Password = "MyPassword";
HistorianAccessError error;
if (!historian.OpenConnection(connectionArgs, out error))
    Console.WriteLine("Failed to initiate historian connection: {0}", error.Description);

If your connection is made over a network with high latency ("ping" response times greater than 500 milliseconds), you can set additional properties to improve performance and stability. Setting the HighLatencyNetwork property to a value of true allows for longer connection timeouts. Setting the Compression property to a value of true causes data to be compressed before transmission, reducing the amount of network bandwidth used. You can use these properties independently of each other to meet your specific network requirements, but if you set the HighLatencyNetwork property to a value of true, it is highly recommended that you also set the Compression property to a value of true.

Using the HighLatencyNetwork property can have a negative impact on low-latency network performance, so it is only recommended if you regularly experience network timeout errors.

Example

HistorianAccess historian = new HistorianAccess();
HistorianConnectionArgs connectionArgs = new HistorianConnectionArgs();
connectionArgs.ServerName = "HistorianComputer";
connectionArgs.UserName = "MyDomain\\MyUserName";
connectionArgs.Password = "MyPassword";
connectionArgs.HighLatencyNetwork = true;
connectionArgs.Compression = true;
HistorianAccessError error;
if (!historian.OpenConnection(connectionArgs, out error))
    Console.WriteLine("Failed to initiate historian connection: {0}", error.Description);

The OpenConnection() call is asynchronous. Its returns true if the historian connection request was successfully initiated, but does not indicated whether the connection to the historian was established or not. To determine whether the historian connection was established or not, the application has to check the status of the initiated connection.

Example

HistorianConnectionStatus connectionStatus = new HistorianConnectionStatus();
for (;;)
{
    historian.GetConnectionStatus(ref connectionStatus);
    if (!connectionStatus.Pending)
        break;
    Console.WriteLine("Connection is pending");
    Thread.Sleep(1000);       
}

if (connectionStatus.ErrorOccurred)
    Console.WriteLine("Connection failed: {0}", connectionStatus.Error.ErrorDescription);

Console.WriteLine("Server = {0}, ServerStorage = {1}, StoreForward = {2}",
    connectionStatus.ConnectedToServer,
    connectionStatus.ConnectedToServerStorage,
    connectionStatus.ConnectedToStoreForward);  

After the HistorianAccess.GetConnectionStatus() call, the instance of the HistorianConnectionStatus class will contain the current status of the initiated connection. While its Pending property is true, it is not known yet whether the connection to the historian has been established or not. As soon as the Pending property becomes false, the application can check whether it was successful in connecting to the historian, historian server storage subsystem, or to the local store-and-forward subsystem.

While the Pending property is still true, the historian connection should not be used for creating tags or storing data, because the state of the connection is not determined yet and its behavior is undefined. That is why we strongly recommend not to start using the historian connection object until you make sure that it is no longer in the pending state.

If a connection to the historian server could not be established, the ErrorOccurred property is set to true and the Error property contains the error information.

The HistorianAccess.GetConnectionStatus() method can be called multiple times for the same connection during the application’s execution time, and the ConnectedToServer, ConnectedToServerStorage, and ConnectedToStoreForward properties may change during that time as well.