Open Method (Server object)

                 

 

Open a connection to the server to allow sending and retrieving data. Most useful operations require an open connection and most programs will initially determine the Server or servers of interest and immediately establish a connection with them using the Open method. The Open method takes a connection string and attempts to open a connection to the server specified by the Server object. The connection string contains the parameters for the desired connection. An empty string (“”) may be used indicating that default connection parameters from the Known Servers Table or the trust relations or identity mappings on the server should be used. Upon successful return a connection is established with the privileges of the user: either specified directly in the connection string (explicit); or determined implicitly by an identity mapping or trust specified on the server, or default user specified on the client (implicit).

Syntax

object.Open [connectionString]

The Open method syntax has these parts:

Part Description

object

An object expression that evaluates to a Server object.

connectionString

An optional string containing the parameters for the Open in the format parameter1=Value1;parameter2=Value2

Settings

The settings for connectionString are:

Setting Description

UID

User name to use in connection. Omitting this setting indicates an implicit connection should be attempted.

PWD

Password to use in connection along with a passed UID

SERVERROLE Connection preference for PI Collectives - only supported with PI server version 3.4.375 and above. See allowed values and their meaning below.

 

The values for SERVERROLE are:

Setting Description
Any No preference in member server.  Use the individual priority settings of the member servers to select the target for connection.
PreferPrimary If the primary member server is available connect to that.  If not, then act as if Any were specified.
RequirePrimary Only the primary member server is acceptable for a connection.  If a primary member is not available return an error.

Remarks

Explicit Connection / Explicit Open:

A program makes an explicit connection by directly calling Server.Open.  An explicit open is a call to Server.Open where the connection string contains the UID keyword indicating the desire to connect as a particular user. 

 

Implicit Connection:

When an application retrieves a Server from the Known Servers Table and accesses a property or invokes a method that requires server access before Server.Open is called explicitly, an implicit connection is attempted. A program may also call Server.Open directly but not pass a UID keyword in the connection string indicating the SDK should attempt an implicit connection.  The implicit connection uses the last connection string used in a successful open for this Server in this process or if no successful connections have been made, it follows the configured rules for an implicit connection.  Implicit connection methods are:

Implicit connection methods, by default, are attempted in the following order.  When an implicit connection attempt fails the next implicit method is automatically tried until a connection is established or all methods fail.

PI Servers 3.4.375 and earlier

PI Servers 3.4.380 and later

With PI-SDK 1.3.6 and later, the choice of implicit methods attempted and the order in which they are tried can be set for a particular machine.  This can be done programmatically using IPISDKOptions.SetAuthenticationOptions or using utilities provided with the PI-SDK installation.

When an implicit connection is successful the name of the credential obtained can be found in the Server.CurrentUser property.  This may be either a PIUser or a string containing one or more PIIdentities.  See the documentation on CurrentUser, and Authentication. 


PI Trusts and PI Identity Mappings

PI Trusts (PI Server version 3.3. and later) and PI Identity Mappings (PI Server version 3.4.380 and later) provide a mechanism for automatic unattended client logins to the server based on the Windows user credentials, and for trusts, client system identification.  This relationship between the O/S identified user and the PI user is configured on the server (see PI Server System Management documentation).  The mechanism assumes that a user who has successfully logged into Windows should automatically be given the mapped access to the corresponding configured PI user. 

 

Close:

When a connection to a server is no longer needed or before an application terminates it may be closed using the Server.Close method. This allows freeing of unneeded resources.  Typically an application which will use a connection during operation, obtaining data from the server periodically, will not close the server until it exits. Opening a server connection and retrieving objects is relatively expensive compared to retrieving information from previously retrieved objects on an open server.

 

Reconnection:

In general, when a PI-SDK application loses a connection to the server, subsequent calls that require the server will attempt to reconnect using the original connection method, however this reconnection mechanism is throttled.  The Server object keeps track of the time at which a disconnection occurs. If reconnection is attempted either implicitly by accessing a method or property which needs server support or explicitly by calling Server.Open before the throttling interval elapses, reconnection is not attempted and pseRECONNECTTOOEARLY is returned to the call. Currently, the throttling interval is set to 60 seconds. This prevents applications from becoming unresponsive while the PI-SDK times out attempting to reconnect to the PI server. For details on automatic reconnection behavior see the topic "Reconnection" referenced in the See Also section of this page.

 

Collectives:

Starting with PI Server version 3.4.375, it is possible to define a Collective PI Server which consists of a primary server and one or more secondary servers which replicate configuration data and are used to make the stored data highly available.  With this version and beyond, the Open command will act on a new syntax used to specify the desired connection.  Because secondary servers do not support all the features of the primary, it becomes necessary to provide applications with the ability to influence the connection process.  The ServerRole= syntax, described above meets this purpose.  For more information on the PI-SDK behavior when using Collective Servers see the topic on High Availability.

 

Events:

When this method is called and the connection attempt is successful, the OnOpen event is fired.  When a connection is explicitly closed (Server.Close) the OnClose event is fired.  When the PI-SDK detects that a connection to a server has been lost the OnDisconnect event is fired..

 

Encryption:

Open takes a COM system string (BSTR) as an argument and that connection string can contain sensitive password information.  The scope (lifetime) of system strings can be influenced but not precisely controlled by the PI-SDK.  Because of this an alternate method, Open_s,  is provided with the IServerConnect interface which takes an array of bytes for the connection string.  Programs that allow the user to provide sensitive data for use in a connection string should consider using this alternate method. When calling this routine the programmer is responsible for clearing variables that they use that hold sensitive data.  Typically the passed connection string should be cleared immediately after the Open_s call returns.  Be careful to understand the compiler optimizations being used as code which clears a variable and never uses it again could be optimized out of the program leaving the secret text in memory unencrypted. 

Trappable Errors

In addition to generic errors (such as Out of Memory), the following errors may occur:

Error Description
pseSERVERIDMISMATCH ServerID in the Known Servers Table does not match that returned by the server.  The connection is left open.  This is an informative error indicating the clients notion of the server does not necessarily agree with the Server connected to.  See the Servers.Aliases collection.
pseBSTRTOPISTRING Unable to translate one of the supplied arguments in the connection string.
pseNOSESSIONMGR No global session manager was found. Fatal error.

pseSERVEROPEN

Unable to open a connection to the server. More detailed information is included in the description field of the raised error.

pseRECONNECTTOOEARLY

Too soon to attempt reconnection. The PI server connection was broken and the retry timeout interval has not yet elapsed. This prevents excessive connection attempts to the server that may make the PI-SDK application unresponsive.

pseSERVEROPENWINSOCK

A Winsock error occurred while trying to open a connection. This represents a low-level communication error, possibly the servers network name is not recognized. The Winsock error number is reported in the description field of the raised error.

0x80070005

This is a generic access denied message and generally means improper login credentials were provided with the call.

Enabling Operational Intelligence