The SUCCEEDED macro does not correctly evaluate directory backup API return values in Windows 2000 Server (321250)

The information in this article applies to:

Microsoft Windows 2000 Server

This article was previously published under Q321250

SYMPTOMS

In Microsoft Windows 2000 Server, the SUCCEEDED macro does not correctly evaluate directory backup API return values. The SUCCEEDED macro may determine that a return value indicates a successful scenario even though the directory backup API returns a FAILED condition.

CAUSE

Some directory backup APIs return both Win32 values and HRESULT values. The following list describes the possible values for Win32 and HRESULT:

A negative HRESULT value indicates an unsuccessful scenario.
A zero or larger HRESULT value indicates a successful scenario.
A non-zero Win32 value indicates an unsuccessful scenario.
A zero Win32 value indicates a successful scenario.

A Win32 value that is any non-zero number indicates an unsuccessful scenario. However, the SUCCEEDED macro treats a return value of zero or larger as an indicator of a successful scenario. Therefore, if the directory backup API call returns a FAILED condition, and the Win32 value is a positive value, the SUCCEEDED macro may determine that the return value indicates a successful scenario.

WORKAROUND

To determine that no Win32 errors have occurred, you must verify that the return values that are larger than zero are HRESULT values and not Win32 values. To verify that your return values from directory backup APIs indicate a successful scenario, compare them to the hrNone return value or the ERROR_SUCCESS return value. Both the hrNone return value and the ERROR_SUCCESS return value indicate a successful scenario.

STATUS

This behavior is by design.

MORE INFORMATION

Most directory backup APIs return an HRESULT value. You can use the SUCCEEDED macro to validate the HRESULT value.

REFERENCES

For more information about the SUCCEEDED macro and about the directory backup APIs, visit the following Microsoft Developer Network (MSDN) Web sites:

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/com/htm/cmf_m2z_85gl.asp

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/ad/ad/directory_backup_functions.asp

Modification Type:	Major	Last Reviewed:	11/24/2004
Keywords:	kbtshoot kbActiveDirectory kbmacro kbAPI kbprb KB321250 kbAudDeveloper