22.214.171.124.126 ApiPauseNodeWithEvacuationTarget (Opnum 127)
(Protocol Version 3) The ApiPauseNodeWithEvacuationTarget method instructs the server to suspend group ownership and failover activity on the designated target node and to move all groups from the designated node to a designated node in the cluster.
Servers SHOULD<96> support this method.
This server MUST handle this method in the same manner as ApiPauseNodeEx (section 126.96.36.199.125) except that the server MUST attempt to move groups hosted by the node specified by the hNode parameter to the node specified by the hNodeEvacuationTarget parameter. The server SHOULD move the groups according to preferences, limitations, and other policies as if ApiMoveGroupToNode (section 188.8.131.52.53) or ApiMoveGroupToNodeEx (section 184.108.40.206.132) had been called for each of these groups individually.
The server MUST fail this method with ERROR_HOST_NODE_NOT_AVAILABLE (0x0000138D) if the node designated by the hNodeEvacuationTarget parameter is not in the ClusterNodeUp state as specified in section 220.127.116.11.69.
The server MUST accept an ApiPauseNodeWithEvacuationTarget request only if its protocol server state is read/write, as specified in section 3.1.1.
The server MUST require that the access level associated with the hNodeEvacuationTarget parameter context handle is "All", as specified in section 3.1.4.
void ApiPauseNodeWithEvacuationTarget( [in] HNODE_RPC hNode, [in] DWORD dwPauseFlags, [in] HNODE_RPC hNodeEvacuationTarget, [out] error_status_t* rpc_status );
dwPauseFlags: This parameter can be set to CLUSAPI_NODE_PAUSE_REMAIN_ON_PAUSED_NODE_ON_MOVE_ERROR (0x00000001), indicating that the server MUST allow a group to remain on the node designated by the hNode parameter if policies prohibit moving the group to the node designated by the hNodeEvacuationTarget parameter. Otherwise, this parameter MUST be set to zero.
hNodeEvacuationTarget: An HNODE_RPC context handle to the destination node, obtained in a previous call to ApiOpenNode (section 18.104.22.168.67) or ApiOpenNodeEx (section 22.214.171.124.117). The hNodeEvacuationTarget parameter MUST NOT specify the same node as the hNode 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 one of the error codes returned by ApiPauseNodeEx (section 126.96.36.199.125) or one of the following values:
The node designated by the hNodeEvacuationTarget parameter is in an invalid state.
The node designated by the hNodeEvacuationTarget parameter is an invalid destination node for the evacuation. This method MUST return ERROR_INVALID_TARGET_HANDLE if the node designated by the hNodeEvacuationTarget parameter is the same as the node designated by the hNode parameter.
For any other condition, the server MUST return a value that is not one of the values listed in the preceding table. The client MUST behave identically for all return values that are not listed in the preceding table; however, the client SHOULD treat errors specified in section 188.8.131.52 as recoverable errors and initiate the reconnect procedure as specified in that section.