3.1.4.1.55 ApiSetGroupNodeList (Opnum 54)

  • Article

(Protocol Version 2) The ApiSetGroupNodeList method sets the specified list of nodes on which the designated group prefers to be hosted.

The server MUST overwrite any existing data in the set with the designated list. The set is emptied as specified in protocol version-specific information later in this section. The server SHOULD append, in any order, the remaining nodes to the list if the designated list does not include all configured nodes in the cluster.

The server SHOULD use the set when making placement decisions for the designated group. The server SHOULD place the group on the first node in the list when the group is moved by using the ApiMoveGroup method. The server SHOULD use the next node in the list, relative to the node that is currently hosting the group, if the group moves due to group and/or resource failure.

The server MUST return ERROR_INVALID_PARAMETER (0x00000057) for any input node list that is not properly formatted. An input node list is not properly formatted if it meets any of the following criteria:

  • The lpNodeList parameter is NULL.

  • The number of bytes in lpNodeList, as indicated by cchListSize, is not an even multiple of the size of a Unicode character.

  • The number of Unicode characters in lpNodeList, as determined by dividing cchListSize by the size of a Unicode character, is less than 1.

  • The last Unicode character, as indicated by cchListSize, in lpNodeList is not NULL.

  • The lpNodeList parameter contains more than one Unicode character, and the second-to-last Unicode character is not NULL. The number of Unicode characters contained in lpNodeList and the second-to-last Unicode character are both indicated by cchListSize.

The server MUST accept any other input. However, if any string specified by lpNodeList is not a valid node ID, then the server SHOULD ignore that particular string when performing group placement decisions as specified earlier in this section.

The server MUST treat the input as an empty list of nodes if lpNodeList contains only Unicode NULL characters and at least one Unicode NULL character.

The server MUST accept an ApiSetGroupNodeList request only if its protocol server state is read/write, as specified in section 3.1.1.

 error_status_t ApiSetGroupNodeList(
   [in] HGROUP_RPC hGroup,
   [in, unique, size_is(cbListSize)] UCHAR *lpNodeList,
   [in] DWORD cbListSize
 );

hGroup: An HGROUP_RPC context handle that was obtained in a previous ApiOpenGroup or ApiCreateGroup method call.

lpNodeList: A pointer to a buffer that contains a MULTI_SZ string of the IDs of the nodes in the preferred list. In both cases the Unicode node IDs are passed.

The node IDs are returned by the ApiGetNodeId method.

cchListSize: The total number of bytes, including all terminating NULL characters, in lpNodeList.

Return Values: The method MUST return the following error codes for the specified conditions.

Return value/code

Description

0x00000000

ERROR_SUCCESS

Success.

0x00000057

ERROR_INVALID_PARAMETER

Refer to the processing rules included earlier in this section for details about this return value.

0x0000055C

ERROR_SPECIAL_GROUP

Cannot perform this operation on this built-in special group (section 3.1.1.1.4).

0x00001394

ERROR_GROUP_NOT_AVAILABLE

The cluster group is not available for new requests.

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 section 3.2.4.6 as recoverable errors and initiate the reconnect procedure as specified in section 3.2.4.6.