Using the C Math Library

Replacing the Default Library Error Handler 

The default error handling behavior of the MATLAB C Math Library routines is implemented by the default library error handler routine. You can further customize error handling by replacing the default library error handler routine with one of your own design.

Note    Because of the error handling capabilities provided by the library try/catch mechanism, applications typically do not need to replace the default error handler. However, in some instances, it can be useful. For example, you can write an error handler that directs error messages to a file.

To replace the default error handler you must:

• Write an error handler
• Register your error handler so that library routines call it when they encounter an error.

Writing an Error Handler

When you write an error handler, you must conform to the library prototype for error handling routines:

void MyErrorHandler( const char *msg, bool isError  )
{
    /* Your code */
}

In this prototype, note the following:

• An error handling routine must not return a value (return void).
• An error handling routine accepts two arguments, a const string and a Boolean value. The string is the text of the error message. When the value of this Boolean value is TRUE, it indicates an error message. If this value is FALSE, it indicates a warning message.

Registering Your Error Handler

After writing an error handler, you must register it with the MATLAB C Math Library so that the library routines can call it when they encounter an error condition at runtime. You register an error handler using the mlfSetErrorHandler() routine.

mlfSetErrorHandler(MyErrorHandler);

Example - Adding an Error Handler

The following example program adds an error handler to the sample program introduced on page 8-3. This error handler writes error messages to a log file, identifying each message as an error or warning. An error handler like this allows a program to run unattended, since any errors produced are recorded in a file for future examination. More complex error-handling schemes are also possible. For example, you can use two files, one for the messages sent to the print handler and one for errors, or you can pipe the error message to an e-mail program that sends a notification of the error to the user who started the program.

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "matlab.h"

FILE *stream;                                            /* 1 */

void MyErrorHandler(const char *msg, bool isError  )     /* 2 */
{
    if(isError)
    {
        fprintf( stream, "ERROR: %s \n", msg );
    }
    else
    {
        fprintf( stream, "WARNING: %s \n", msg );
    }
}
static double data[] = { 1, 2, 3, 4, 5, 6 };

main()
{
    mxArray *mat0 = NULL;
    mxArray *mat1 = NULL;
    mxArray *volatile mat2 = NULL;

    mlfSetErrorHandler(MyErrorHandler);

    stream = fopen("myerrlog.out","w");

    mlfEnterNewContext(0,0);                             /* 3 */

    mlfAssign(&mat0, mlfDoubleMatrix(2, 3, data, NULL)); /* 4 */
    mlfAssign(&mat1, mlfDoubleMatrix(3, 2, data, NULL));
    mlfTry 
    {
        mlfAssign(&mat2, mlfRdivide(mat1, mlfScalar(0)));
        printf("Return to try block after warning.\n");

        mlfPrintMatrix(mlfPlus(mat0, mat1));

        mxDestroyArray(mat2);
    }
    mlfCatch 
    {
        mlfPrintf("In catch block. Caught an error: ");
        mlfPrintMatrix(mlfLasterr(NULL));

        if (mat2)
            mxDestroyArray(mat2);
    }
    mlfEndCatch

    mlfPrintf("Now in application after catch block.");

    mxDestroyArray(mat0);
    mxDestroyArray(mat1);
    mlfRestorePreviousContext(0, 0);

    fclose(stream);
    return(EXIT_SUCCESS);
}

The numbered items in the list below correspond to the numbered comments in the code example:

1. The example program declares a variable, stream, that is a pointer to the output log file.
2. The error handling routine, MyErrorHandler, determines the type of error message, and writes warnings and errors to a log file.
3. The main program opens the log file, named myerrlog.out. The program calls fclose() to close the log file before exiting.
4. Register the error handler with the MATLAB C Math Library with this call to mlfSetErrorHandler().

   Output

The program produces this output.

In MyErrorHandler. WARNING: Divide by zero.
Logging the warning to a file.
Returning to try block after warning.
In MyErrorHandler. Logging the error to a file.
In catch block. Caught an error: Matrix dimensions must agree.
Now in application after catch block.

Example - Defining Try/Catch Blocks (ex6.c)

Defining a Print Handler