1. Auto-Connection - Reconnection - Close

Calling PI-SDK methods and properties that require data from a PI Server, before calling for an explicit connection with that server using Server.Open, will cause the PI-SDK to attempt to connect automatically. In this case the PI-SDK calls Open automatically on behalf of the application initially passing an empty connection string. This results in the implicit connection attempt sequence described in the preceding sections If successful the method or property call will continue. If the implicit connection fails, the call will fail with an access error.

In some cases, an application may explicitly connect to a server using a connection string, which may contain a user name and password. Changes in the network environment or the server's availability may result in the PI-SDK becoming disconnected. When this occurs the PI-SDK will detect on its next server access that the connection has been lost and will set the Connected property of the server accordingly. Successive calls to that server will then attempt to reconnect to the server. This reconnection will be attempted with the same connection string that was used in the previous successful connection. This allows a secure connection to be reestablished automatically after a network connection break.


Note this reconnection mechanism is throttled by the PI-SDK so that reconnection attempts outside of High Availability (HA) PI servers can only occur once a minute. This prevents an application that has lost connection and is rapidly making calls from monopolizing the server's connection mechanism. When an application tries to automatically reconnect within a minute of its last try, whichever call has caused the connection attempt will receive the error, pseRECONNECTTOOEARLY.  In an HA environment, alternate member servers are tried immediately when a reconnection is needed and a delay only occurs if all suitable members of a collective are unavailable.


In some cases, an application will wish to initially log in as one user, and then switch to a different user for subsequent calls. To accomplish this, the program must call Server.Close before the second connection. This call tells the PI-SDK that the caller is no longer interested in the connection or the ability to reconnect under the original user name. The program can then successfully call Server.Open with a new connection string. If a program does not call Close but instead calls Server.Open on a server that has already been opened, specifying a different connection string, an error is returned. (For convenience in programming you may call Server.Open successfully many times in succession, as long as the connection string does not change).

Prior to version 1.4 of the PI-SDK, objects obtained under an initial set of login credentials were no longer considered valid after Server.Close is called. For those versions, typically, an application should let go of these objects and obtain new objects after a successful Server.Open. To enforce this behavior, the PI-SDK, starting with version 1.3.2, continued to provide any data already retrieved from the server that was cached within the object (for example fetched PointAttributes) but actions which required obtaining new data from the server returned the error pseDISCONNECTEDOBJECT. These "disconnected objects", informally referred to as zombies, could not be reconnected. References to disconnected objects needed to be dropped and new objects retrieved from the Server object after calling Server.Open. Basically zombies could not be brought back to life.

Version 1.4 of the PI-SDK relaxes this behavior and objects obtained from a Server object will attempt to make an implicit reconnection after a call to Server.Close when calls to fetch server data are made. Any objects the PI-SDK has cached for the Server but aren't being referenced by the calling program are cleared but a program's previously referenced objects can now continue to be used.  There is no longer a requirement to explicitly call Server.Open after Server.Close has been called.  This new behavior is as secure as in previous versions because the underlying session and user token are destroyed on Close.  Implicit reconnection is based on either the authenticated Windows user identity, the criteria configured in the server's PI Trust or a default user with a blank password.

The Connection object from the SDK Dialogs offers a menu item that allows reconnection to the server as a different user. Using the Connection dialog in an application exposes the program to the possibility of disconnected objects. In order to be notified that an end user may be "switching users" an application can sign up for the OnOpen and OnClose events for a Server or the Servers collection.

In summary, the Server.Open and Server.Close calls are used to explicitly log in and out of a PI Server. Automatic initial implicit connections are supported when server calls are made without calling Open.  These behave as Open calls using a blank connection string. Automatic reconnections are supported for lost connections using the prior credentials. Where security concerns do not dictate passwords on all users or Trusts are configured appropriately, or SSPI is supported and configured, an application can omit the Open and Close calls subject to the default behaviors described above. In PI-SDK versions prior to 1.4, explicitly closing a connection results in disconnected objects which should be released and new objects obtained when needed from a newly opened connection.

Enabling Operational Intelligence