3.1.4.2.53 ApiMoveGroupToNode (Opnum 52)

Article
04/27/2022

(Protocol Version 3) The ApiMoveGroupToNode method instructs the server to move ownership of the specified group to the specified node in the cluster. If the designated group is currently owned by the target destination node, the server MUST complete the method using ERROR_SUCCESS (0x00000000).

The server SHOULD fail this method if it maintains limitations on which nodes can own the resources in the group and the destination node is not identified as a potential owner. These policies are configured and executed by using implementation-specific methods between server.

The server MUST initiate transition of all resources that are contained in the ClusterResourceOnline group state to the ClusterResourceOffline state. When all the resources reach either the ClusterResourceOffline or ClusterResourceFailed state, the server MUST attempt to transfer ownership of the group to the destination node that is specified by hNode.

On the destination node, the server MUST initiate transition of each resource in the group to its persistent state. For example, if the persistent state of the resource is ClusterResourceOnline, the server MUST attempt to transition the resource from the ClusterResourceOffline state to the ClusterResourceOnline state. It is possible for the final group state on the destination node to be different from the group state prior to the move.

The server MAY return from this method while the move procedure is executed asynchronously. In this case, the server MUST return 0x000003E5 (ERROR_IO_PENDING). After the move procedure is completed, depending on whether the resources that are contained in the designated group were successfully brought to their persistent states, the server MUST set the group state as specified in section 3.1.4.2.46.

If the server executes the full move procedure synchronously, and if the server fails to bring the resources that are contained in the group to their persistent states, the server MUST return a nonzero error code other than 0x000003E5 and set the group state as specified in section 3.1.4.2.46.

Whether the move procedure is executed synchronously or asynchronously, it is possible for the resources in the group to fail to reach their persistent state on the destination node. In this case, the server SHOULD attempt recovery actions, such as moving the group to another node in the cluster, which might include moving the group to the node that was the owner prior to the move request.

If the destination node is in the ClusterNodePaused state, as specified in section 3.1.4.2.69, or if the current protocol server state of the server is not read/write, as specified in section 3.1.1, the server MUST fail this call using ERROR_SHARING_PAUSED. Otherwise, if the node is not in the ClusterNodeUp state, the server MUST fail this call using ERROR_HOST_NODE_NOT_AVAILABLE.

The server fails this method using ERROR_CLUSTER_RESOURCE_LOCKED_STATUS if the resource or any of its providers are in locked mode, as specified in section 3.1.1.1.4.

The server MUST accept an ApiMoveGroupToNode request only if its protocol server state is read/write, as specified in section 3.1.1.

The server SHOULD apply the following criteria to determine whether the client has a sufficient level of access for the ApiMoveGroupToNode request. Either the following two conditions are true:

The access level associated with the hGroup context handle is "All" (section 3.1.4).
The access level associated with the hNode context handle is "All" (section 3.1.4).

Or, the following three conditions are true:

The access level associated with the hGroup context handle is at least "Read with Backup Privilege" (section 3.1.4).
The access level associated with the hNode context handle is at least "Read with Backup Privilege" (section 3.1.4).
The hGroup context handle designates a group that contains a cluster shared volume resource, as specified in sections 3.1.4.2.122 and 3.1.4.2.162.
```
 error_status_t ApiMoveGroupToNode(
   [in] HGROUP_RPC hGroup,
   [in] HNODE_RPC hNode,
   [out] error_status_t *rpc_status
 );
```

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

hNode: An HNODE_RPC (section 2.2.1.2) context handle that was obtained in a previous ApiOpenNode (section 3.1.4.2.67) or ApiOpenNodeEx (section 3.1.4.2.117), method call indicating the node that will take ownership of the group.

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: The method MUST return the following error codes for the specified conditions.

Return value/code	Description
0x00000000 ERROR_SUCCESS	The move of the designated group to the designated node was successfully completed.
0x00000005 ERROR_ACCESS_DENIED	Access is denied.
0x00000006 ERROR_INVALID_HANDLE	The hGroup parameter and the hNode parameter represent a valid RPC context handle. The hGroup parameter is not of type HGROUP_RPC (section 2.2.1.3), or the hNode parameter is not of type HNODE_RPC (section 2.2.1.2), or both are not of the correct type.
0x00000046 ERROR_SHARING_PAUSED	Either the destination node that is specified by hNode is in the ClusterNodePaused state and cannot take ownership of the group that is identified by hGroup or the current protocol server state of the server is not read/write.
0x000003E5 ERROR_IO_PENDING	Ownership of the group is in transition.
0x0000138D ERROR_HOST_NODE_NOT_AVAILABLE	The destination node that is specified by hNode is not in either the ClusterNodeUp or the ClusterNodePaused state.
0x000013B2 ERROR_CLUSTER_NODE_NOT_FOUND	The destination node that is specified by hNode is no longer attached to the cluster.

For any other condition, this method MUST return a value that is not one of the values listed in the preceding table. The client MUST behave in one consistent, identical manner for all values that are not listed in the preceding table. The client SHOULD treat errors specified in 3.2.4.6 as recoverable errors, and initiate the reconnect procedure as specified in section 3.2.4.6.

3.1.4.2.53 ApiMoveGroupToNode (Opnum 52)

Additional resources