Add Method (Servers collection)

                  

 

Creates a Server object and attaches it to the Servers collection. Returns a reference to the created Server object. Adds the server to the Known Servers Table for the machine.

 

Syntax

object.Add Name, ConnectString, ConnectType, Confirm

The Add method syntax has these parts:

Part

Description

object

An object expression that evaluates to a Servers object.

Name

A string containing the desired local name for the new server.

ConnectString

A string containing instructions that tells the PI-SDK how to connect to the server. The format of this string consists of sets of key values separated by semi-colons. A key value is a keyword followed by an equal sign followed by a value. The key values vary depending on the type of server, as described in Settings.

ConnectType

A string indicating the type of server. The server strings are taken from the registered server types on the machine found in the subkeys under \HKEY_LOCAL_MACHINE\SOFTWARE\PISystem\PI-SDK\1.0\ServerTypes. Typically these are "PI3" or "PI2".

Confirm

A boolean indicating whether the server ID should be determined (or confirmed if entered in the connectString) during the Add. If FALSE, (the default), the confirmation is deferred until the first connection attempt. [Optional]

 

Settings

The settings for connectString are as follows:

Setting

Description

UID

The name of the default user for connecting to this server.

PATH

The network path where this server resides. May be a fully qualified network path (e.g. unit1.company.com), an IP address (e.g. 123.252.231.76), or a host name which can be resolved in the local host table or by the DNS on the user's network.

PORT

The port on the server machine where the server responds.

DEFAULT

Indicates whether this should be known as the default server on this machine (“1” for TRUE, “0” for FALSE).

SERVERID

A specific server ID for this server. Typically a 0 is entered or the key is omitted and the server is queried for its ID either during the Add or during the first connection attempt. If a non zero server ID is specified and it does not match that returned by the server, the passed server ID will be added as an Alias for this server in the Known Servers Table, ServerAliasesKST_ServerAliases table.

 

Remarks

When this method is called, the OnAdd event is fired.

In order to store the new server in the Known Servers Table, this method modifies the system registry. You may need to log in from a privileged account in order to use this and other methods that enter or modify values in the Known Servers Table.

When a server which is a collective is added and confirmed by connecting, the configuration of the collective is sent to the client and stored in the Known Servers Table.  This consists of information about the collective as a whole and configuration of the various members of the collective.  The names of the collective members as specified in the collective configuration in the server are added as aliases in the Server.Aliases table.  This allows applications that have persisted the names of servers in displays, spreadsheets and reports, that subsequently become members of a collective, to still access the server.  The Servers.Item property will look in the Aliases collection if it does not find the passed index in the Servers collection itself. 

 

Trappable Errors

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

Error

Description

pseSERVTYPNOTIMPL

The connectType argument was not recognized or is not supported.

pseREGISTRYADDSERVER

Unable to add the server to the registry. More information is available in the error structure description field.

psePINSINKST A PINS node cannot be added to the Known Servers Table.

Enabling Operational Intelligence