Share via

Visual Basic Concepts

  • Article

Guidelines for Raising Errors from Your Component

Use the Raise method of the Err object to raise errors that can be trapped by client applications. When you call the Raise method in the error handler of one of your methods or Property procedures, or when error handling is turned off (On Error GoTo 0), the error will be raised in the client application, in the procedure that directly called your method.

If the procedure that called your method has no error handler, the error condition moves up the call tree of the client until it reaches a procedure that has an error handler, just as any other error would.

When raising an error condition from your component, you don’t need to worry about whether the client is written in Visual Basic, Microsoft Visual C++, or another programming language. Any client application can receive the errors your component raises.

Here are a few guidelines you should follow when raising errors from a component.

  • The error number you return to client applications is generated by adding an intrinsic constant (vbObjectError) to your internal error number. The resulting value is the one you should document for your users.

  • The internal error numbers you add to vbObjectError should be in the range 512 to 65535 (&H200 to &HFFFF). Numbers below 512 may conflict with values reserved for use by the system.

  • Establish a "fatal error" or "general failure" code and message for conditions from which your component can’t recover.

  • When calling Err.Raise, supply both an error number and a text string describing the error.

  • Document your errors in the Help file for your component. For the convenience of your users, you may want to show error numbers in both decimal and hexadecimal format.

For example, you might implement the SpinDirection property of the Widget object as a Property procedure, to ensure that it accepts only certain values, as in the following code fragment from the Widget class module of the hypothetical SmallMechanicals component.

' Enumeration for SpinDirection property values.
'   (The prefix "sm" identifies it as belonging to the
'   SmallMechanicals component.)
Public Enum smSpinDirection
   smSDClockwise
   smSDCounterClockwise
End Enum

' Module-level storage for SpinDirection property.
Private msdSpinDirection As smSpinDirection

' Implementation of the SpinDirection property.
Property Get SpinDirection() As smSpinDirection
   SpinDirection = msdSpinDirection
End Property

Property Let SpinDirection(ByVal sdNew As _
      smSpinDirection)
   ' The Select Case does nothing if sdNew contains
   ' a valid value.
   Select Case sdNew
      Case smSDClockwise
      Case smSDCounterClockwise
      Case Else
         Err.Raise _
            (ERR_SPN_INVALID + vbObjectError), _
            CMP_SOURCENAME, _
            LoadResString(ERR_SPN_INVALID)
   End Select
   ' If no error, assign the new property value.
   msdSpinDirection = sdNew
End Property

The code above assumes that ERR_SPN_INVALID and CMP_SOURCENAME are public constants declared in a standard module, and that error text strings are stored in a resource file.

Because there is no error handler in the Property Let procedure used to set the value of the SpinDirection property, the error is raised in the client application, in the procedure that attempted to set the invalid value.

The text string for the error message is loaded from the component project’s resource file, using the internal error number as an index. This technique reduces the amount of memory required to run the component. By concentrating all the text strings in one place, it also simplifies the creation of international versions of the component.

Note   Programmers who have used the C++ language will recognize vbObjectError as facility interface (FACILITY_ITF), the base constant for the range of errors reserved for a component’s interface.

For More Information   "Handling Errors in a Component" discusses the handling of internal errors, particularly those raised by components your component is using. For more on the Err object and resource files, see "Err object" in the Language Reference and "resource files" in the index.

Providing error messages in multiple languages is discussed in "Localizing Components," later in this chapter, and in "International Issues" in the Visual Basic Programmer’s Guide.