220.127.116.11.52 ApiMoveGroup (Opnum 51)
(Protocol Version 3) The ApiMoveGroup method instructs the server to move ownership of the specified group to another node in the cluster. The server SHOULD select the destination node based on preferences and limitations on where the resources in the group can be owned and any preferred node that is associated with the group. These policies are configured and executed by using implementation-specific methods between servers.
The server MUST initiate transition of all resources that are contained in the ClusterResourceOnline group state to the ClusterResourceOffline state. When all the resources have reached either the ClusterResourceOffline or ClusterResourceFailed state, the server MUST attempt to transfer ownership of the group to another active node in the cluster.
On the destination node, the server MUST initiate transition of each resource in the group to its persistent state. That is, 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 completion of the move procedure, 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 18.104.22.168.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 22.214.171.124.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.
The server MUST fail this method if the specified group is in the ClusterGroupPending state, as specified in section 126.96.36.199.46, or if any of the group resources are in either the ClusterResourceOnlinePending or ClusterResourceOfflinePending states.
The server SHOULD apply the following criteria to determine whether the client has a sufficient level of access for the ApiMoveGroup request. Either the following condition is true:
The access level associated with the hGroup context handle is "All" (section 3.1.4).
Or, the following two conditions are true:
The access level associated with the hGroup context handle is at least "Read with Backup Privilege" (section 3.1.4).
error_status_t ApiMoveGroup( [in] HGROUP_RPC hGroup, [out] error_status_t* rpc_status );
hGroup: An HGROUP_RPC (section 188.8.131.52) context handle that is obtained in a previous ApiOpenGroup (section 184.108.40.206.42), ApiOpenGroupEx (section 220.127.116.11.118), or ApiCreateGroup (section 18.104.22.168.43) method call.
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
The move of the designated group was successfully completed.
Access is denied.
The hGroup parameter does not represent a valid HGROUP_RPC (section 22.214.171.124) context handle.
The ownership of the group is in transition.
A cluster node is not available for this operation.
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 126.96.36.199 as recoverable errors and initiate the reconnect procedure as specified in section 188.8.131.52.