MoveClusterGroup function (clusapi.h)

Article
10/13/2021

Moves a group and all of its resources from one node to another. The PCLUSAPI_MOVE_CLUSTER_GROUP type defines a pointer to this function.

Syntax

DWORD MoveClusterGroup(
  [in]           HGROUP hGroup,
  [in, optional] HNODE  hDestinationNode
);

Parameters

[in] hGroup

Handle to the group to be moved.

[in, optional] hDestinationNode

Handle to the node where the moved group should be brought back online or NULL.

Return value

If the operation succeeds, the function returns ERROR_SUCCESS.

If the operation fails, the function returns a system error code. The following is one of the possible error codes.

Return code	Description
ERROR_IO_PENDING	The reassignment of ownership of the group is in progress.

Remarks

The return value from the MoveClusterGroup function does not imply anything about the state of the group or any of its resources. The return value only indicates whether the change of ownership was successful. After returning from MoveClusterGroup, the cluster always attempts to return the group to the state it was before the move.

If you want your application to ensure a particular state for a resource or a group after a move:

Check the state prior to the move. The cluster will attempt to restore that state after the move.
Poll for the state after the move and adjust as necessary. Or create a notification port (see Receiving Cluster Events) and wait for a CLUSTER_CHANGE_GROUP_STATE event.

When hDestinationNode is set to NULL, MoveClusterGroup attempts to move the group to the best possible node. If there is no node available that can accept the group, the function fails. MoveClusterGroup also fails if MoveClusterGroup determines that the group cannot be brought online on the node identified by the hDestinationNode parameter.

Do not call MoveClusterGroup from a resource DLL. For more information, see Function Calls to Avoid in Resource DLLs.

Do not pass LPC and RPC handles to the same function call. Otherwise, the call will raise an RPC exception and can have additional destructive effects. For information on how LPC and RPC handles are created, see Using Object Handles and OpenCluster.

Requirements

Requirement	Value
Minimum supported client	None supported
Minimum supported server	Windows Server 2008 Enterprise, Windows Server 2008 Datacenter
Target Platform	Windows
Header	clusapi.h
Library	ClusAPI.lib
DLL	ClusAPI.dll