4.2 Moving a Group
The following example illustrates how a protocol client ensures that a specific group is owned by a specific node, moving the group to that node if necessary. Assume that in this example, the client is managing a group that has the well-known name "Application Group". Assume that there are three nodes in the cluster that have the names "NodeA", "NodeB", and "NodeC", and all nodes are currently active. The client needs the group to be owned by NodeB.
The following diagram depicts the message flow.
Figure 7: Message flow: Moving a group
First, the client initializes an RPC connection to the cluster, as specified in section 3.2.3. The client knows the names of the nodes and can use either node to establish the connection.
The client next opens a context handle to the group by calling ApiOpenGroup (section 3.1.4.1.42 for protocol version 2, or 3.1.4.2.42 for protocol version 3) with the lpszGroupName parameter set to the null-terminated Unicode string "Application Group".
The client then determines which node currently owns the group by calling ApiGetGroupState (section 3.1.4.1.46 for protocol version 2, or 3.1.4.2.46 for protocol version 3). During this call the client passes the HGROUP_RPC context handle that was just obtained from ApiOpenGroup. Assume for this example that, in response to the ApiGetGroupState method, the server returns a current node name of "NodeA". Because the client needs the group to be owned by NodeB, the client now needs to move the group.
The client obtains an HNODE_RPC context handle for NodeB by calling ApiOpenNode (section 3.1.4.1.67 for protocol version 2, or 3.1.4.2.67 for protocol version 3) and setting the lpszNodeName parameter to the null-terminated Unicode string "NodeB". Then the client calls ApiMoveGroupToNode (section 3.1.4.1.53 for protocol version 2, or 3.1.4.2.53 for protocol version 3) indicating the group that is identified by the HGROUP_RPC and the destination node indicated by the HNODE_RPC.
Assume that the server returns status 0x000003E5 (ERROR_IO_PENDING), but the client is waiting until the move is complete. So the client polls by calling ApiGetGroupState every five seconds until the group is no longer in state ClusterGroupPending. Assuming that the group is now in state ClusterGroupOnline, the move is complete. If the group were in ClusterGroupFailed, the client could expect recovery action to be attempted to bring all resources in the group to their persistent states.