Share via

3.1.4.2.131 ApiMoveGroupEx (Opnum 132)

  • Article

(Protocol Version 3) The ApiMoveGroupEx method SHOULD<114> instruct the server to move ownership of the specified group to another node in the cluster.

The server MUST handle this method in the same manner as ApiMoveGroup (section 3.1.4.2.52) except as follows:

  • If the CLUSAPI_GROUP_MOVE_IGNORE_RESOURCE_STATUS flag is set in the dwMoveFlags parameter, the server MUST ignore the locked mode value of the group designated by the hGroup parameter.

  • If the CLUSAPI_GROUP_MOVE_RETURN_TO_SOURCE_NODE_ON_ERROR flag is set in the dwMoveFlags parameter, and if the designated group cannot be brought to its persistent state on the destination node selected by the server, the server MUST move the group back to the source node and bring the group to its persistent state on the source node.

  • If the CLUSAPI_GROUP_MOVE_QUEUE_ENABLED flag is set in the dwMoveFlags parameter, and if server implementation-specific policies preclude the move operation from proceeding, the server MUST retry the move operation until either the move succeeds, or the move fails due to a different reason, or the move is canceled.

  • If the CLUSAPI_GROUP_MOVE_HIGH_PRIORITY_START flag is set in the dwMoveFlags parameter, then on the destination node when bringing the group to its persistent state, the server SHOULD bring this group to its persistent state as soon as possible, regardless of other implementation-specific policies that govern the ordering and/or prioritization of bringing groups to their persistent states.

  • If the CLUSAPI_GROUP_MOVE_FAILBACK flag is set in the dwMoveFlags parameter, and if move group operation fails, the server MUST perform failback operation.

  • If the CLUSAPI_GROUP_MOVE_IGNORE_AFFINITY_RULE flag is set in the dwMoveFlags parameter, the server MUST ignore the affinity rule of the group designated by the hGroup parameter.

  • For each resource contained in the group designated by hGroup that is in the state ClusterResourceOnline (section 3.1.4.2.13), the server MUST provide the buffer designated by the lpInBuffer parameter to the server implementation-specific object that controls the resource operation while bringing the resource offline on the current node and when bringing the resource online on the destination node. How the server provides this buffer is implementation-specific.

The server accepts an ApiMoveGroupEx request only if it is in the read/write state, as specified in section 3.1.1.

The server MUST require that the access level associated with the hGroup parameter is "All" (section 3.1.4).

 error_status_t ApiMoveGroupEx(
   [in] HGROUP_RPC hGroup,
   [in] DWORD dwMoveFlags,
   [in, size_is(cbInBufferSize)] BYTE* lpInBuffer,
   [in] DWORD cbInBufferSize,
   [out] error_status_t *rpc_status
 );

hGroup: An HGROUP_RPC context handle that was obtained in a previous call to ApiOpenGroup (section 3.1.4.2.42), ApiOpenGroupEx (section 3.1.4.2.118), or ApiCreateGroup (section 3.1.4.2.43).

dwMoveFlags: A bitwise-OR of zero or more of the following flags, with the exception that CLUSAPI_GROUP_MOVE_IGNORE_RESOURCE_STATUS and CLUSAPI_GROUP_MOVE_QUEUE_ENABLED cannot be specified together and MUST be rejected by the server with the error 0x00000057 (ERROR_INVALID_PARAMETER).

Value

Description

0x00000001

CLUSAPI_GROUP_MOVE_IGNORE_RESOURCE_STATUS

The server MUST ignore the group locked mode as specified in section 3.1.1.1.4.

0x00000002

CLUSAPI_GROUP_MOVE_RETURN_TO_SOURCE_NODE_ON_ERROR

If the designated group cannot be brought to its persistent state on the destination node selected by the server, the server MUST move the group back to the source node and bring the group to its persistent state on the source node.

0x00000004

CLUSAPI_GROUP_MOVE_QUEUE_ENABLED

If server implementation-specific policies preclude the move operation from proceeding, the server MUST retry the move operation until either the move succeeds, or the move fails due to a different reason, or the move is canceled.

0x00000008

CLUSAPI_GROUP_MOVE_HIGH_PRIORITY_START

When bringing the group to its persistent state on the destination node, the server SHOULD bring this group to its persistent state as soon as possible without regard to implementation-specific policies that govern the ordering and/or prioritization of bringing groups to their persistent states.

CLUSAPI_GROUP_MOVE_FAILBACK

0x00000010

If move group operation fails, the server MUST perform failback operation.

CLUSAPI_GROUP_MOVE_IGNORE_AFFINITY_RULE

0x00000020

The server MUST ignore the affinity rule while performing move group operation.<115>

lpInBuffer: A pointer to a buffer that the server will provide to implementation-specific objects that control the resource operations for each resource in the group. The client SHOULD set this parameter to a PROPERTY_LIST (section 2.2.3.10). For each value in this list, the client sets the property name to the name of the resource type of one of the resources in the group. The client MAY provide a buffer that does not have a property value corresponding to each resource type in the group, and the client MAY provide a buffer that has multiple property values for the same resource type. Except for the following property values, the server MUST treat all property values provided by the client identically.

Property Name

CLUSTER_PROPERTY_FORMAT

Value

Description

Virtual Machine

CLUSPROP_FORMAT_DWORD

0x00000000

For a resource of resource type "Virtual Machine" in the group that is in the ClusterResourceOnline state (section 3.1.4.2.13), the server MUST turn off the corresponding virtual machine on the source node of the move operation.

Virtual Machine

CLUSPROP_FORMAT_DWORD

0x00000001

For a resource of resource type "Virtual Machine" in the group that is in the ClusterResourceOnline state (section 3.1.4.2.13), the server MUST save the corresponding virtual machine on the source node of the move operation.

Virtual Machine

CLUSPROP_FORMAT_DWORD

0x00000002

For a resource of resource type "Virtual Machine" in the group that is in the ClusterResourceOnline state (section 3.1.4.2.13), the server MUST shut down the corresponding virtual machine on the source node of the move operation.

Virtual Machine

CLUSPROP_FORMAT_DWORD

0x00000003

For a resource of resource type "Virtual Machine" in the group that is in the ClusterResourceOnline state (section 3.1.4.2.13), the server MUST forcibly shut down the corresponding virtual machine on the source node of the move operation.

Virtual Machine

CLUSPROP_FORMAT_DWORD

0x00000004

For a resource of resource type "Virtual Machine" in the group that is in the ClusterResourceOnline state (section 3.1.4.2.13), the server MUST migrate the corresponding virtual machine to a destination node chosen by the server.

If the client includes this property value in the lpInBuffer parameter, the client SHOULD also enable the CLUSAPI_GROUP_MOVE_RETURN_TO_SOURCE_NODE_ON_ERROR, CLUSAPI_GROUP_MOVE_QUEUE_ENABLED, and CLUSAPI_GROUP_MOVE_HIGH_PRIORITY_START flags in the dwMoveFlags parameter.

cbInBufferSize: The size in bytes of the buffer pointed to by the lpInBuffer parameter.

rpc_status: A 32-bit integer used to indicate success or failure. The RPC runtime MUST indicate, by writing to this parameter, whether it succeeded in executing this method on the server. The encoding of the value passed in this parameter MUST conform to encoding for comm_status and fault_status, as specified in Appendix E of [C706].

Return Values: This method MUST return the same error codes as specified for ApiMoveGroup (section 3.1.4.2.52), in addition to the following return value.

Return value/code

Description

0x00000057

ERROR_INVALID_PARAMETER

The client included both the CLUSAPI_GROUP_MOVE_IGNORE_RESOURCE_STATUS and CLUSAPI_GROUP_MOVE_QUEUE_ENABLED flags in the dwMoveFlags parameter.