Setting Properties

Setting properties is the process of writing new property values to the cluster database. Applications and resource DLLs set properties to change the cluster environment according to their needs.

The Failover Cluster API provides many ways to set the properties of a cluster object. The standard order of preference for cluster-aware applications recommends using control codes if possible. Therefore, the procedures described below use control codes exclusively. If you are writing a resource DLL, you should use the cluster database access functions and the cluster utility functions to work with properties.

The following generalized procedure describes how to set the properties for any object. Substitute the name of the object (that is, node, network, network interface, group, resource, or resource type ) for <Object>.

To set <Object> properties

1. Create a property list for the object. (See Creating Property Lists.)

2. Validate the property list to ensure that the formatting is correct and the values are appropriate. Call the control code function for the object, Cluster<Object>Control, specifying one of the following control codes as the dwControlCode parameter.

   Properties to set	Control code to use
   Common properties	CLUSCTL_<OBJECT>_VALIDATE_COMMON_PROPERTIES
   Private properties	CLUSCTL_<OBJECT>_VALIDATE_PRIVATE_PROPERTIES

    

3. If validation succeeds, set the properties by calling Cluster<Object>Control using one of the following control codes as the dwControlCode parameter.

   Properties to set	Control code to use
   Common properties	CLUSCTL_<OBJECT>_SET_COMMON_PROPERTIES
   Private properties	CLUSCTL_<OBJECT>_SET_PRIVATE_PROPERTIES

    

4. If Cluster<Object>Control returns ERROR_SUCCESS, the properties have been written to the cluster database.

5. If Cluster<Object>Control returns ERROR_RESOURCE_PROPERTIES_STORED, the properties have been written to the cluster database, but some or all of the new settings do not take effect until the next time the resource is brought online.

Example Code

The following example function sets group properties. It obtains a property list by calling the ClusDocEx_GrpCreatePropList example function from Creating Property Lists.

#include <windows.h>

///////////////////////////////////////////////////////////////////////////////////

#include "ClusDocEx.h"

///////////////////////////////////////////////////////////////////////////////////

#ifndef _CLUSDOCEX_GRPRESETPROPERTYDEFAULTS_CPP
#define _CLUSDOCEX_GRPRESETPROPERTYDEFAULTS_CPP
//---------------------------------------------------------------------------------
//
//  ClusDocEx_GrpResetPropertyDefaults
//
//  Sets all read/write common group properties to their default
//  values.
//
//  Arguments:
//       hGroup     Handle to group whose properties are to be set.
//
//  Return Value:               
//       Error code
//
//---------------------------------------------------------------------------------
DWORD ClusDocEx_GrpResetPropertyDefaults( IN HGROUP hGroup )
{
  DWORD dwResult = ERROR_SUCCESS;
  DWORD cbSize   = 0;

//  Obtain a property list with all values set to defaults.
//  For the ClusDocEx_GrpCreatePropertyList function see
//  "Creating Property Lists".

  LPVOID lpPropList = ClusDocEx_GrpCreatePropertyList( &amp;cbSize,
                                                       ClusterGroupPreventFailback,
                                                       L" ",
                                                       -1, 
                                                       -1,
                                                       6,
                                                       10,
                                                       FALSE );


//  Validate the property list.

   dwResult = ClusterGroupControl( hGroup, 
                                   NULL,
                                   CLUSCTL_GROUP_VALIDATE_COMMON_PROPERTIES,
                                   lpPropList, 
                                   cbSize, 
                                   NULL, 
                                   0, 
                                   NULL );

  if ( dwResult == ERROR_SUCCESS )
   {

    //  Set the properties.

    dwResult = ClusterGroupControl( hGroup, 
                                    NULL,
                                    CLUSCTL_GROUP_SET_COMMON_PROPERTIES,
                                    lpPropList, 
                                    cbSize, 
                                    NULL, 
                                    0, 
                                    NULL );
   }

  if ( dwResult != ERROR_SUCCESS )
   {
    ClusDocEx_DebugPrint( L"ClusDocEx_GrpResetPropertyDefaults", 
                          dwResult );
   }

//  Free the buffer returned by ClusDocEx_GrpCreatePropList

  LocalFree( lpPropList );

  return dwResult;

 }
//  end ClusDocEx_GrpResetPropertyDefaults
//----------------------------------------------------------------------------------
#endif