<div class="content" name="ApiPauseNodeEx" uuid="88e34e18-d184-4826-aa82-9adc36dcf3a3"><p>(Protocol Version 3) The ApiPauseNodeEx method SHOULD<a id="Appendix_A_Target_105"></a><a aria-label="Product behavior note 105" href="1d58eff8-a042-478c-972c-8e9c76a3f978#Appendix_A_105" data-linktype="relative-path">&lt;105&gt;</a> 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.</p><p>The server MUST handle this method in the same manner as <span><a href="ea63e8f2-dfec-4d9d-bae9-b44164559023" data-linktype="relative-path">ApiPauseNode (section 3.1.4.1.70)</a></span>
except as specified in this section.</p><p>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 <i>bDrainNode</i> parameter to TRUE.
In this case, the server MUST move each group owned by the node designated by
the <i>hNode</i> parameter to a different node in the cluster.</p><p>If the client calls this method with <i>bDrainNode</i> set
to TRUE:</p><ul><li><p><span><span> 
</span></span>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 <i>dwPauseFlags</i>
parameter does not include the
CLUSAPI_NODE_PAUSE_REMAIN_ON_PAUSED_NODE_ON_MOVE_ERROR flag, the node
designated by the <i>hNode</i> parameter cannot host any groups.</p>
</li><li><p><span><span> 
</span></span>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 <span><a href="46f729d5-4f05-49ec-b5ed-e4359e24d105" data-linktype="relative-path">3.1.4.1.69</a></span>) other
than the node designated by the hNode parameter.</p>
</li></ul><p>Otherwise, if the client calls this method with <i>bDrainNode</i>
set to TRUE, the server MUST return ERROR_IO_PENDING (0x000003E5) and proceed
to move the groups asynchronously.</p><p>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 <span><a href="e204819c-2644-48f6-8766-3339a1377d1a" data-linktype="relative-path">ApiMoveGroup (section 3.1.4.1.52)</a></span>
or <span><a href="ba315e35-f381-477d-8c36-0c71dc434fa8" data-linktype="relative-path">ApiMoveGroupEx (section 3.1.4.2.131)</a></span>
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 <i>dwPauseFlags</i>
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.</p><p>The server MUST accept an ApiPauseNodeEx request only if its
<span><a href="694e5e7a-5833-4f3d-b47e-323ee1d452c2#gt_a93e2fea-3006-4a06-b48f-fdb36d9abac9" data-linktype="relative-path">protocol
server state</a></span> is read/write, as specified in section <span><a href="756547e7-ca64-4b7c-9f1b-2b1fbc6153d3" data-linktype="relative-path">3.1.1</a></span>.</p><p>The server MUST require that the access level associated
with the <i>hNode</i> parameter context handle is &#34;All&#34;, as specified
in section <span><a href="a249a463-3d3b-4058-abf6-3024d81806a0" data-linktype="relative-path">3.1.4</a></span>.</p><dl>
<dd>
<div><pre> error_status_t ApiPauseNodeEx(
   [in] HNODE_RPC hNode,
   [in] BOOL bDrainNode,
   [in] DWORD dwPauseFlags,
   [out] error_status_t *rpc_status
 );
</pre></div>
</dd></dl><p><b>hNode: </b>An HNODE_RPC context handle that was
obtained in a previous call to <span><a href="e687ff9d-9054-41ac-9c1e-bc621cade374" data-linktype="relative-path">ApiOpenNode (section 3.1.4.1.67)</a></span>
or <span><a href="a4e4a533-09b5-4b69-b4ae-3e5436ae2390" data-linktype="relative-path">ApiOpenNodeEx (section 3.1.4.2.117)</a></span>.</p><p><b>bDrainNode: </b>Indicates whether to evacuate the
node. If set to TRUE, the server MUST evacuate the node specified by the <i>hNode</i>
parameter as specified in this section.</p><p><b>dwPauseFlags: </b>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 <i>hNode</i>
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 <i>bDrainNode</i>
parameter is set to FALSE.</p><p><b>rpc_status: </b>A 32-bit integer used to indicate
success or failure. The <span><a href="694e5e7a-5833-4f3d-b47e-323ee1d452c2#gt_8a7f6700-8311-45bc-af10-82e10accd331" data-linktype="relative-path">RPC</a></span> 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 <span><a href="https://go.microsoft.com/fwlink/?LinkId=89824" data-linktype="external">[C706]</a></span>.</p><p><b>Return Values: </b>The method MUST return one of
the following error codes.</p><dl>
<dd>
<table><thead>
  <tr>
   <th>
   <p>Return value/code</p>
   </th>
   <th>
   <p>Description</p>
   </th>
  </tr>
 </thead><tbody><tr>
  <td>0x00000000 ERROR_SUCCESS</td>
  <td>The method completed successfully.</td>
 </tr><tr>
  <td>0x00000006 ERROR_INVALID_HANDLE</td>
  <td>The data that is designated by the hNode parameter does not represent a valid HNODE_RPC context handle.</td>
 </tr><tr>
  <td>0x000013BA ERROR_CLUSTER_NODE_DOWN</td>
  <td>There are no nodes in the cluster that are in the ClusterNodeUp state other than the node designated by the hNode parameter.</td>
 </tr><tr>
  <td>0x000003E5 ERROR_IO_PENDING</td>
  <td>The server is in the process of evacuating the specified node.</td>
 </tr><tr>
  <td>0x0000174A ERROR_CLUSTER_NODE_EVACUATION_IN_PROGRESS</td>
  <td>The server is already evacuating the specified node due to a prior call to this method.</td>
 </tr></tbody></table>
</dd></dl><p>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 <span><a href="ca75805a-4b39-4074-8b5b-dbaae6e81b1f" data-linktype="relative-path">3.2.4.6</a></span>
as recoverable errors and initiate the reconnect procedure as specified in that
section.</p></div>