Item Property (Servers collection)

                

Retrieves a Server from the Servers collection by name, ServerID, or by Alias.

Syntax

object[.Item](index)

The Item property syntax has these parts:

Part

Description

object An object expression that evaluates to a Servers collection.

index A string that specifies either the server name, server path, serverID preceded by a '?', or alternate name from the Aliases table

Remarks

The Item property is the default property of the collection, so these expressions have the same meaning:
MyServers.Item("MyPIServer")
MyServers("MyPIServer")

By using the question mark prefix, you can search for servers based on their ServerID as stored in the Known Servers Table.  For example:
Set mysrv = Servers.Item("?34618")

If the passed index is not found in the collection of Servers, the Item call walks the Servers table looking for PI Collectives.  For each collective found, it compares the passed index to the names and ServerID fields of the collective member servers.  If it finds a match, the Server object representing the collective is returned. 

If the passed index is still not found, the Item call walks the Servers table checking for a matching path (FQDN) to a server or a collective member.

By adding entries in the Alias table, alternate names for servers can be recorded and are searched in this Item method.  This check is executed only  if the passed index was not found as a serverID, server name, name of a member of a collective, path to a server, or path to a collective member.   Note: Collective members are also added to the Alias table the first time a connection is made to a collective.

Starting with version 1.3.6, if none of the methods above locate the desired server, this method will add a new server to the Known Servers Table using the passed index as the name and the path.  Before proceeding it verifies that the passed index can be translated into a valid IP address.  While this gives some assurance of connectivity there is no guarantee that there is a running PI system on the node.  Both of these default behaviors (AutoAdd and CheckIP) can be turned off, temporarily or permanently using the IPISDKOptions interface of the PISDK object under the DirectoryOptions methods.  Attempts to automatically add the requested server are throttled to avoid delays when an application is repeatedly trying to address the same server which can't be resolved.   

 

Trappable Errors

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

Error

Description

pseNOEMPTYSTRINGS Empty strings not allowed.
pseSERVNOTFOUND The requested server was not found in the known servers table.
psePINSINKST A PINS node cannot be added to the Known Servers Table.

Enabling Operational Intelligence