ULRegisterErrorCallback function

Registers a callback function that handles errors.

Syntax

void ULRegisterErrorCallback (
    SQLCA * sqlca,
    ul_error_callback_fn callback,
    ul_void *   user_data,
    ul_char *   buffer,
    size_t   len 
);

Parameters

sqlca A pointer to the SQL Communications Area.
In the C++ API use the Sqlca.GetCA method.
callback The name of your callback function. For more information about the prototype of the function, see Callback function for ULRegisterErrorCallback.
A callback value of UL_NULL disables any previously registered callback function.
user_data An alternative to global variables to make any context information globally accessible. This is required because you can call the callback function from any location in your application. UltraLite does not modify the supplied data; it simply passes it to your callback function when it is invoked.
You can declare any data type and cast it into the correct type in your callback function. For example, you could include a line of the following form in your callback function:
MyContextType * context = (MyContextType *)user_data;
buffer A character array holding the substitution parameters for the error message, including a null terminator. To keep UltraLite as small as possible, UltraLite does not supply error messages. The substitution parameters depend on the specific error. For a complete list, see SQL Anywhere error messages.
The buffer must exist as long as UltraLite is active. Supply UL_NULL if you do not want to receive parameter information.
len The length of the buffer (preceding parameter), in ul_char characters. A value of 100 is large enough to hold most error parameters. If the buffer is too small, the parameters are truncated.

Remarks

Once you call this function, the user-supplied callback function is called whenever UltraLite signals an error. You should therefore call ULRegisterErrorCallback immediately after initializing the SQLCA.

Error handling with this callback technique is particularly helpful during development, as it ensures that your application is notified of any and all errors that occur. However, the callback function does not control execution flow, so the application should check the SQLCODE field in the SQLCA after all calls to UltraLite functions.

Example

The following code registers a callback function for an UltraLite C++ Component application:

int main() {
    ul_char buffer[100];
    DatabaseManager * dm;
    Connection * conn;
    Sqlca.Initialize();
    ULRegisterErrorCallback(
        Sqlca.GetCA(),
        MyErrorCallBack,
        UL_NULL,
        buffer,
        sizeof (buffer) );
    dm = ULInitDatabaseManager( Sqlca );
    ...
}

The following is a sample callback function:

ul_error_action UL_GENNED_FN_MOD MyErrorCallBack(
    SQLCA *     Sqlca,
    ul_void *   user_data,
    ul_char *   message_param )
{
    ul_error_action rc = 0;
    (void) user_data;
    
    switch( Sqlca->sqlcode ) {
        // The following error is used for flow control - don't report it here
        case SQLE_NOTFOUND:
            break;
        case SQLE_ULTRALITE_DATABASE_NOT_FOUND:
            _tprintf( _TEXT( "Error %ld: Database file %s not found\n" ), Sqlca->sqlcode, message_param ); 
            break;  
        default:
            _tprintf( _TEXT( "Error %ld: %s\n" ), Sqlca->sqlcode, message_param ); 
        break;
     }
    return rc;
}