3.1.4.2.126 ApiPauseNodeWithDrainTarget (Opnum 127)

  • Article

(Protocol Version 3) The ApiPauseNodeWithDrainTarget method SHOULD<106> instruct 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.

This server MUST handle this method in the same manner as ApiPauseNodeEx (section 3.1.4.2.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 hNodeDrainTarget parameter. The server SHOULD move the groups according to preferences, limitations, and other policies as if ApiMoveGroupToNode (section 3.1.4.2.53) or ApiMoveGroupToNodeEx (section 3.1.4.2.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 hNodeDrainTarget parameter is not in the ClusterNodeUp state as specified in section 3.1.4.2.69.

The server MUST accept an ApiPauseNodeWithDrainTarget 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 hNodeDrainTarget parameter context handle is "All", as specified in section 3.1.4.

 void ApiPauseNodeWithDrainTarget(
   [in] HNODE_RPC hNode,
   [in] DWORD dwPauseFlags,
   [in] HNODE_RPC hNodeDrainTarget,
   [out] error_status_t* rpc_status
 );

hNode: An HNODE_RPC context handle that was obtained in a previous call to ApiOpenNode (section 3.1.4.1.67) or ApiOpenNodeEx (section 3.1.4.2.117).

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 hNodeDrainTarget parameter. Otherwise, this parameter MUST be set to zero.

hNodeDrainTarget: An HNODE_RPC context handle to the destination node, obtained in a previous call to ApiOpenNode (section 3.1.4.1.67) or ApiOpenNodeEx (section 3.1.4.2.117). The hNodeDrainTarget 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 3.1.4.2.125) or one of the following values:

Return value/code

Description

0x0000138D

ERROR_HOST_NODE_NOT_AVAILABLE

The node designated by the hNodeDrainTarget parameter is in an invalid state.

0x00000072

ERROR_INVALID_TARGET_HANDLE

The node designated by the hNodeDrainTarget parameter is an invalid destination node. This method MUST return ERROR_INVALID_TARGET_HANDLE if the node designated by the hNodeDrainTarget parameter is the same as the node designated by the hNode parameter.

For any other condition, the server returns 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 3.2.4.6 as recoverable errors and initiate the reconnect procedure as specified in that section.