ErrObject.Raise(Int32, Object, Object, Object, Object) Method

Reference

Definition

Namespace:: Microsoft.VisualBasic

Assembly:: Microsoft.VisualBasic.Core.dll

Assembly:: Microsoft.VisualBasic.dll

Source:: ErrObject.vb

Source:: ErrObject.vb

Source:: ErrObject.vb

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Generates a run-time error; can be used instead of the Error statement.

public void Raise (int Number, object? Source = default, object? Description = default, object? HelpFile = default, object? HelpContext = default);

public void Raise (int Number, object Source = default, object Description = default, object HelpFile = default, object HelpContext = default);

member this.Raise : int * obj * obj * obj * obj -> unit

Public Sub Raise (Number As Integer, Optional Source As Object = Nothing, Optional Description As Object = Nothing, Optional HelpFile As Object = Nothing, Optional HelpContext As Object = Nothing)

Parameters

Number: Int32

Required. Long integer that identifies the nature of the error. Visual Basic errors are in the range 0-65535; the range 0-512 is reserved for system errors; the range 513-65535 is available for user-defined errors. When setting the Number property to your own error code in a class module, you add your error code number to the vbObjectError constant. For example, to generate the error number 513, assign vbObjectError + 513 to the Number property.

Source: Object

Optional. String expression naming the object or application that generated the error. When setting this property for an object, use the form project.class. If Source is not specified, the process ID of the current Visual Basic project is used.

Description: Object

Optional. String expression describing the error. If unspecified, the value in the Number property is examined. If it can be mapped to a Visual Basic run-time error code, the string that would be returned by the Error function is used as the Description property. If there is no Visual Basic error corresponding to the Number property, the "Application-defined or object-defined error" message is used.

HelpFile: Object

Optional. The fully qualified path to the Help file in which help on this error can be found. If unspecified, Visual Basic uses the fully qualified drive, path, and file name of the Visual Basic Help file.

HelpContext: Object

Optional. The context ID identifying a topic within HelpFile that provides help for the error. If omitted, the Visual Basic Help-file context ID for the error corresponding to the Number property is used, if it exists.

Examples

This example uses the Err object's Raise method to generate an error within a function written in Visual Basic. The calling function can catch the error and report it to the user with a message box.

Module Module1

    Const WidthErrorNumber As Integer = 1000
    Const WidthHelpOffset As Object = 100

    Sub Main()
        CallingProcedure()
    End Sub

    Sub TestWidth(ByVal width As Integer)
        If width > 1000 Then
            ' Replace HelpFile.hlp with the full path to an appropriate
            ' help file for the error. Notice that you add the error 
            ' number you want to use to the vbObjectError constant. 
            ' This assures that it will not conflict with a Visual
            ' Basic error.
            Err.Raise(vbObjectError + WidthErrorNumber, "ConsoleApplication1.Module1.TestWidth", 
                "Width must be less than 1000.", "HelpFile.hlp", WidthHelpOffset)
        End If
    End Sub

    Sub CallingProcedure()
        Try
            ' The error is raised in TestWidth.
            TestWidth(2000)
        Catch ex As Exception
            ' The Err object can access a number of pieces of
            ' information about the error.
            Console.WriteLine("Information available from Err object:")
            Console.WriteLine(Err.Number)
            Console.WriteLine(Err.Description)
            Console.WriteLine(Err.Source)
            Console.WriteLine(Err.HelpFile)
            Console.WriteLine(Err.HelpContext)
            Console.WriteLine(Err.GetException)

            Console.WriteLine(vbCrLf & "Information available from Exception object:")
            Console.WriteLine(ex.Message)
            Console.WriteLine(ex.ToString)

            Err.Clear()
        End Try
    End Sub
End Module

' The example produces the following output:
' Information available from Err object:
' -2147220504
' Width must be less than 1000.
' ConsoleApplication1.Module1.TestWidth
' HelpFile.hlp
' 100
' System.Exception: Width must be less than 1000.
'    at Microsoft.VisualBasic.ErrObject.Raise(Int32 Number, Object Source, Object
' Description, Object HelpFile, Object HelpContext)
'    at ConsoleApplication1.Module1.TestWidth(Int32 width) in C:\Users\example\App
' Data\Local\Temporary Projects\ConsoleApplication1\Module1.vb:line 17
'    at ConsoleApplication1.Module1.CallingProcedure() in C:\Users\example\AppData
' \Local\Temporary Projects\ConsoleApplication1\Module1.vb:line 25
'
' Information available from Exception object:
' Width must be less than 1000.
' System.Exception: Width must be less than 1000.
'    at Microsoft.VisualBasic.ErrObject.Raise(Int32 Number, Object Source, Object
' Description, Object HelpFile, Object HelpContext)
'    at ConsoleApplication1.Module1.TestWidth(Int32 width) in C:\Users\example\App
' Data\Local\Temporary Projects\ConsoleApplication1\Module1.vb:line 17
'    at ConsoleApplication1.Module1.CallingProcedure() in C:\Users\example\AppData
' \Local\Temporary Projects\ConsoleApplication1\Module1.vb:line 25

Remarks

All of the Raise arguments except Number are optional. If you omit optional arguments, and the property settings of the Err object contain values that have not been cleared, those values serve as the values for your error.

Because the Err object gives richer information than when you generate errors with the Error statement, Raise is useful for generating errors when writing class modules. For example, with the Raise method, the source that generated the error can be specified in the Source property, online Help for the error can be referenced, and so on.

Applies to

Jaa