3.1.4.2.3 ApiSetClusterName (Opnum 2)

(Protocol Version 3) The ApiSetClusterName method changes the name of the cluster.

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

The server MUST require that the client have a security access level of "All" (section 3.1.4).

 error_status_t ApiSetClusterName(
   [in, string] LPCWSTR NewClusterName,
   [out] error_status_t *rpc_status
 );

NewClusterName: A pointer to a case-insensitive Unicode string indicating the new name for the cluster. The new name consists of a DNS host name (in the format of a label as specified in [RFC1035]) and MUST NOT exceed 128 bytes (64 Unicode characters), including the terminating null character.

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 returns the following error codes for the specified conditions.

Return value/code	Description
0x00000000 ERROR_SUCCESS	Success.
0x0000007B ERROR_INVALID_NAME	The NewClusterName parameter is already used as the name of a configured node.
0x000006CF RPC_S_STRING_TOO_LONG	The NewClusterName parameter exceeds 128 bytes (64 Unicode characters), including the terminating null character.
0x0000139B ERROR_RESOURCE_ONLINE	The cluster name could not be changed because the resource associated with the primary security principal of the cluster is in the ClusterResourceOnline state.
0x000013A0 ERROR_RESOURCE_PROPERTIES_STORED	The resource associated with the primary security principal of the cluster is in the ClusterResourceOnline or ClusterResourceOnlinePending state, and the value of the NewClusterName parameter is the same as the current name of the cluster. In this case, the server MUST ensure that the value of NewClusterName is stored in the nonvolatile cluster state and then return this error code.

For any other condition, the server MUST set Status to a value that is not one of the values listed in the preceding table. The client MUST treat all values that are not listed in the preceding table the same, except as specified in section 3.2.4.6.