CLUSCTL_RESOURCE_STATE_CHANGE_REASON control code

Under certain circumstances, the cluster sends the CLUSCTL_RESOURCE_STATE_CHANGE_REASON control code to a resource DLL immediately before calling the Offline or Terminate entry-point function, providing the DLL with the reason for the state change. Because the control code is internal, applications cannot use it in a control code function.

Parameters

This control code has no parameters.

Return value

This control code does not return a value.

Remarks

ClusAPI.h defines the 32 bits of CLUSCTL_RESOURCE_STATE_CHANGE_REASON (0x0150004e) as follows.

ComponentBit locationValue

Object code

24–31

CLUS_OBJECT_RESOURCE (0x1)

Global bit

23

CLUS_NOT_GLOBAL (0x0)

Modify bit

22

CLUS_MODIFY (0x1)

User bit

21

CLCTL_CLUSTER_BASE (0x0)

Type bit

20

Internal (0x1)

Operation code

0–23

CLCTL_STATE_CHANGE_REASON (0x50004e)

Access code

0–1

CLUS_ACCESS_WRITE (0x2)

 

For more information, see Control Code Architecture.

Resource DLL Support

Optional. By default, resource DLLs do not receive the CLUSCTL_RESOURCE_STATE_CHANGE_REASON control code under any circumstances. To receive the control code, a resource DLL must report the following characteristic: CLUS_CHAR_REQUIRES_STATE_CHANGE_REASON.

For information on how to report characteristics for your resource DLL see CLUSCTL_RESOURCE_GET_CHARACTERISTICS.

The CLUSCTL_RESOURCE_STATE_CHANGE_REASON control code gives resource DLLs the option of implementing different shutdown procedures in response to different shutdown conditions. For example, a resource DLL may implement a graceful, clean shutdown under most circumstances, but if the Cluster service stops unexpectedly, the DLL may implement a fast and dirty brute-force shutdown to facilitate faster failover.

To support CLUSCTL_RESOURCE_STATE_CHANGE_REASON control code in your resource DLL, perform the following steps:

  • Initialize a CLUSCTL_RESOURCE_STATE_CHANGE_REASON_STRUCT structure for each resource managed by the resource DLL. Typically this structure is included in the resource DLL's resource structure.
  • In your implementation of ResourceControl:

    • Handle the CLUSCTL_RESOURCE_GET_CHARACTERISTICS control code and return a value that includes CLUS_CHAR_REQUIRES_STATE_CHANGE_REASON.
    • Handle the CLUSCTL_RESOURCE_STATE_CHANGE_REASON control code and store the reason code passed in the lpInBuffer parameter in the eReason member of the resource structure.
  • When implementing Offline and Terminate, read the eReason member of the resource structure and, if this member is not eResourceStateChangeReasonUnknown (from the CLUSTER_RESOURCE_STATE_CHANGE_REASON enumeration), perform any necessary operations. Before returning from Offline or Terminate, reset the eReason member of the resource structure to eResourceStateChangeReasonUnknown.

For more information on the ResourceControl entry point function, see Implementing ResourceControl.

Requirements

Minimum supported client

None supported

Minimum supported server

Windows Server 2008 Enterprise, Windows Server 2008 Datacenter

Header

ClusAPI.h

See also

Internal Resource Control Codes
ResourceControl
CLUSCTL_RESOURCE_STATE_CHANGE_REASON_STRUCT
CLUSTER_RESOURCE_STATE_CHANGE_REASON

 

 

Show: