Runtime errors occur as your macro runs, and typically result from specific conditions present at that time. For example, if you prompt the user for a host name, and attempt to connect to that host, but the host is not available, the Connect method fails and Visual Basic generates a runtime error.

You should always include some form of error handling in your macros to deal with runtime errors. Without any error handling, a runtime error causes a macro to stop immediately, and gives the user little information.

To deal with runtime errors, you'll need to trap (catch) the errors, handle them, and then resume execution after the error is handled:

Trapping Runtime Errors

Handling Errors Inline

Using Error Handling Routines

Trapping Runtime Errors

The first step in dealing with runtime errors is to set a "trap" to catch the error. You do this by including an On Error statement in your macro. When a runtime error occurs, the On Error statement transfers control to an error-handling routine.

To trap errors, you must set your error trap above the point in the procedure where errors are likely to occur. A good practice is to place the error trap near the top of the procedure. To avoid having the error-handling routine execute even when no error occurs, you should include an Exit Sub or Exit Function statement just before the error-handling routine's label.

Sub ErrorDemo ()
  On Error GoTo MyHandler
  'Program code goes here. To avoid invoking the error handling routine after this
  'section is executed, include the following line just above the error-handler.
  Exit Sub

  MyHandler:
  'Error is handled and the macro terminates gracefully.
  Exit Sub
End Sub

Resuming a Procedure After an Error

After your macro successfully traps and handles an error, you can choose whether to have the macro exit the procedure (by including an Exit Sub or Exit Function statement in the handler) or resume the procedure (by including a resume statement). When you resume a procedure, you can also have the macro correct the error condition automatically, in which case the end user may never know that an error occurred.

Each of the following examples show the general structure of a procedure that includes an error trap and error-handling routine.

In this example, control resumes at the line following the statement that caused the runtime error.

Sub SampleResumeNext ()
  On Error GoTo MyHandler
  'Normal program code goes here. If an error
  'occurs, control is transferred to the handler.
  'When the handler is done, control resumes
  'at the next line here.
  Exit Sub

  MyHandler:
  'Error is handled, and control resumes at the line
  'after the statement that caused the error.
  Resume Next
End Sub

 In this example, control returns to the DoPrompt label after the error handler executes.

Sub SampleResumeToLabel ()
  On Error GoTo MyHandler
  DoPrompt:
  'Normal program code goes here. If an error occurs,
  'control is transferred to the handler.
  Exit Sub

  MyHandler:
  'Error is handled, and then control is transferred
  'to the DoPrompt label.
  Resume DoPrompt
End Sub

Handling Errors Inline

To cause a procedure to handle relatively simple runtime errors without branching to a separate error-handling routine, you can use a form of the On Error statement that lets you deal with errors inline; that is, directly in the code that caused the error, rather than in a separate routine.

To handle an error inline, use the Resume Next statement with On Error. Any errors that occur during runtime cause Reflection to continue executing the macro at the next statement. If an error occurs, it is handled by opening a dialog box, passing control to another procedure or to a routine within the same procedure.

This example checks for errors when saving an IBM 3270 or 5250 session document. If the save operation fails, an error message appears. If the save operation succeeds (Err.Number returns 0), a "Save complete" message appears.

Sub SaveSessionDemo()
  Dim theError As Integer
  On Error Resume Next
  ThisIbmTerminal.Save
  theError = Err.Number

  Select Case theError
    Case 0
     MsgBox "Save complete."
    Case Else
     MsgBox Err.Description & "."
  End Select
End Sub

Using Error Handling Routines

After you set an error trap, write the error-handling routine that will deal with errors that are likely to occur — in addition to unanticipated errors — when your macro runs. You can identify an error-handling routine by its line label.

Observe the following guidelines:

• Place error-handling routines near the end of the procedure, just before the End Sub or End Function statement.
• Avoid executing error-handling code when no error occurs by placing an Exit Sub or Exit Function statement just before the error handler's label. A Resume statement is typically used to continue execution of the macro after the error handler is done.
• Use the Err object to return specific information about the error. (See the Visual Basic Help for more information about the Err object.)

The following sample shows a simple error handling routine.

This simple error handler displays a custom error message and then terminates the macro:

Sub ExitOnError ()
  On Error GoTo MyHandler
  'Main body of procedure.
  Exit Sub

  MyHandler:
   MsgBox "Error occurred. Cannot complete operation."
  Exit Sub
End Sub