Skip to content

Error Handling in Managed Connections

The cConnection object has its own error handling. It traps errors in areas where things are likely to go wrong and identifies three kinds of errors:

  • User Errors: Most likely this is a login error. This is a handled error.

  • Configuration Errors: These are things like missing connections INI file, bad connection information, missing drivers, etc. These are problems that a user is likely to see when their application is not installed properly. We treat a configuration error as a variation of a user error. It is handled (no stack dump), but it attempts to provide enough information to identify the configuration problem. Fixing this usually requires configuration corrections.

  • Programming Errors: These are errors that occur when the programmer misuses the cConnection interface. These are unhandled. Fixing this usually requires code corrections.

Configuration Errors

A configuration error occurs when a cConnection error arises due to something being wrong with the configuration. Often, this will be a problem with the Connections INI file (bad INI format, missing keywords, missing connection ID, etc.), but it can also occur when the driver is bad or missing. When this happens, there is probably nothing wrong with your code. These are problems that need to be solved at the install and configuration level.

ConfigurationError

When a configuration error occurs, the ConfigurationError message is sent. ConfigurationError is passed an error number and an error description. By default, this presents a user error with a standard error configuration title and the error description. ConfigurationError can be augmented or replaced to customize its appearance, provide extra information, or log the error.

Error Trapping

An interface is provided that traps errors. It does this by surrounding code that might fail (like loading a driver) with a trap start and end message. After the error trapping is ended, you can check if an error occurred and handle it as desired. This interface is used by many of the methods in the class and can be used by the developer as well. Here is an example of how error trapping is used:

// low level load which does not register the driver - only loads
{ Visibility=Private }
Function LoadDriver String sDriver Returns Boolean
    Integer iErrorNumber
    Send TrapErrors
    Load_Driver sDriver
    Send UnTrapErrors
    Get piErrorNumber to iErrorNumber
    Function_Return (iErrorNumber=0)
End_Function

TrapErrors

TrapErrors starts error trapping. Any error that occurs is now sent to the cConnection object’s Error_Report event. TrapErrors sets piErrorNumber to 0. TrapErrors needs to be followed by UnTrapErrors. Normally, you want the code between these two events to be as short as possible.

Error_Report

When an error occurs with trapping enabled, the Error_Report event is called. This stores the error number, line number, and error description by setting the properties piErrorNumber, piErrorLine, and psErrorText.

UnTrapErrors

UnTrapErrors stops error trapping, and errors are now redirected to the standard error handler. After UnTrapErrors, you can test if an error occurred by checking if piErrorNumber is 0.

piErrorNumber, piErrorLine, and psErrorText

If an error occurs during error trapping, the properties piErrorNumber, piErrorLine, and psErrorText are set. This occurs inside of Error_Report. Usually, you will test piErrorNumber after error trapping is stopped. If it is non-zero, you can handle the error as you wish. If you wish to report the error, you can use psErrorText to provide an error description. Remember that these properties contain the last trapped error reported. When error trapping is started, piErrorNumber is set to 0.

Procedure LoginAll
    Boolean bOk
    Integer iError
    String sError
    Get LoginAllConnections to bOk
    If not bOk Begin
        Get psErrorText to sError
        Get piErrorNumber to iError
        Send UserError (C_$LoginAllFailedWillAbort + "\n\n" + sError)
        Abort
    End
End_Procedure

Previous Topic

Driver Management

Next Topic

Recommendations and Requirements