Error Handling

In Microsoft® Visual Basic® a method call either succeeds or it fails. If the call fails, an error is raised, and an error number is set in the global Visual Basic Err object. Your application must then branch to an error handler that examines the Err object and deals with the error, or execution terminates. However, underlying every Microsoft DirectX® Visual Basic method is a C++ method that handles errors somewhat differently. In some cases, you will need to know something about C++ return values to interpret Visual Basic errors.

In C and C++, every method call returns an HRESULT value. This value is an integer with a specific format that indicates the outcome of the operation. In some cases, the HRESULT that a method returns simply indicates whether the operation succeeded or failed. However, methods may sometimes use many HRESULT values to indicate a variety of success or failure modes. There may, in fact, be more than one return value that indicates success. Many of HRESULT values are system standards, and are defined in the Winerror.h header file. System standard values typically use an S_ prefix for success codes and an E_ prefix for failure. For example, S_OK and E_FAIL are commonly used codes for success and failure, respectively. When the C++ code that typically underlies a Visual Basic method returns a standard HRESULT value, the Visual Basic run time traps that value, and sets a standard Visual Basic error code.

Many DirectX methods also support one or more non-standard HRESULT values. These values are normally defined in an enumeration, and the meaning of each value is given in the method reference. Because they are not standard values, there is no corresponding Visual Basic error code. Instead, the Visual Basic run time sets Err.Number to the HRESULT value. Refer to the method reference for the meaning of the value. For more information on HRESULT values, see the COM documentation in the Microsoft Platform Software Development Kit (SDK).