3.1.4.2.125 ApiPauseNodeEx (Opnum 126)

  • Article

(Protocol Version 3) The ApiPauseNodeEx method SHOULD<105> instruct the server to suspend group ownership and failover activity on the designated node and, optionally, to move groups on the designated node to different nodes in the cluster.

The server MUST handle this method in the same manner as ApiPauseNode (section 3.1.4.1.70) except as specified in this section.

This method enables the client to specify whether to evacuate the node by moving all the groups to other nodes in the cluster. The client requests evacuation by setting the bDrainNode parameter to TRUE. In this case, the server MUST move each group owned by the node designated by the hNode parameter to a different node in the cluster.

If the client calls this method with bDrainNode set to TRUE:

  • The server MUST fail this method with ERROR_CLUSTER_NODE_EVACUATION_IN_PROGRESS (0x0000174A) if evacuation is already in progress for the designated node. The way the server determines that evacuation is in progress is implementation-specific, although for evacuation to not be in progress, the following condition MUST be met: if the dwPauseFlags parameter does not include the CLUSAPI_NODE_PAUSE_REMAIN_ON_PAUSED_NODE_ON_MOVE_ERROR flag, the node designated by the hNode parameter cannot host any groups.

  • The server MUST fail this method with ERROR_CLUSTER_NODE_DOWN (0x000013BA) if there are no nodes in the cluster that are in the ClusterNodeUp state (as specified in section 3.1.4.1.69) other than the node designated by the hNode parameter.

Otherwise, if the client calls this method with bDrainNode set to TRUE, the server MUST return ERROR_IO_PENDING (0x000003E5) and proceed to move the groups asynchronously.

The server SHOULD move the groups according to preferences, limitations, and other policies that are configured and executed through implementation-specific methods between servers, as if ApiMoveGroup (section 3.1.4.1.52) or ApiMoveGroupEx (section 3.1.4.2.131) had been called for each of these groups individually. If a preference, limitation, or other policy would prevent the server from moving the group such that a call to ApiMoveGroup or ApiMoveGroupEx would fail, then unless the CLUSAPI_NODE_PAUSE_REMAIN_ON_PAUSED_NODE_ON_MOVE_ERROR flag is set in the dwPauseFlags parameter, the server MUST move the group to a different node anyway, even if the server does not bring the group to its persistent state on the destination node.

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

 error_status_t ApiPauseNodeEx(
   [in] HNODE_RPC hNode,
   [in] BOOL bDrainNode,
   [in] DWORD dwPauseFlags,
   [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).

bDrainNode: Indicates whether to evacuate the node. If set to TRUE, the server MUST evacuate the node specified by the hNode parameter as specified in this section.

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 any other nodes that are in the ClusterNodeUp state. Otherwise, this parameter MUST be set to zero. The server MUST ignore the value of this parameter entirely if the bDrainNode parameter is set to FALSE.

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 one of the following error codes.

Return value/code

Description

0x00000000

ERROR_SUCCESS

The method completed successfully.

0x00000006

ERROR_INVALID_HANDLE

The data that is designated by the hNode parameter does not represent a valid HNODE_RPC context handle.

0x000013BA

ERROR_CLUSTER_NODE_DOWN

There are no nodes in the cluster that are in the ClusterNodeUp state other than the node designated by the hNode parameter.

0x000003E5

ERROR_IO_PENDING

The server is in the process of evacuating the specified node.

0x0000174A

ERROR_CLUSTER_NODE_EVACUATION_IN_PROGRESS

The server is already evacuating the specified node due to a prior call to this method.

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.