SwitchMember Method (IPICollective interface)



The SwitchMember method is used to change the currently connected member of a collective without closing or invalidating any of the objects it parents.  This method takes optional arguments for a connection preference string and a CollectiveMember object as retrieved by ListMembers.


object.SwtichMember bstrConnect, MemberSrv

The SwtichMember method syntax has these parts:

Part Description
object An object expression that evaluates to an IPICollective interface.
bstrConnect A connection string for the selected server. A blank string will use defaults.  See options below:
MemberSrv A CollectiveMember object representing the collective member server where the new connection is desired.


The bstrConnect string may contain the string ServerRole=nnn where nnn is one of the following:

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.


The connection preference can contain the ServerRole=nnn syntax described under ConnectionPreference to determine the rule used to select the new member. Unlike when specifying this syntax in the connection string of an Open command, using a preference in this command does not set the IPICollective::ConnectionPreference property. However if the passed string does not contain a ServerRole specification or nothing is passed the method will observe the current ConnectionPreference property of the server which was either set explicitly or as a side-effect of the Open command.

The second argument, a CollectiveMember object,  is used to switch to a specific member. When this argument is passed it overrides any connection preference as the server selection rules are no longer needed. If the connection fails an error is returned without trying other members of the collective and the Server object remains disconnected. A subsequent call needing server access will automatically reconnect using the current ConnectionPreference property.

Trappable Errors

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

Error Description
pseSERVERNOTCOLLECTIVE The Server is not a collective

Enabling Operational Intelligence