<library>Initialize[WithHandlers]

Initialize MATLAB Runtime instance associated with library

Syntax

bool libraryInitialize()

bool libraryInitializeWithHandlers(mclOutputHandlerFcn error_handler, mclOutputHandlerFcn print_handler)

Description

bool libraryInitialize() creates a MATLAB^® Runtime instance associated with the generated C/C++ shared library library using the default print and error handlers.

Call this function in your C/C++ application after calling mclInitializeApplication and before calling any of the compiled functions exported by the library.

bool libraryInitializeWithHandlers(mclOutputHandlerFcn error_handler, mclOutputHandlerFcn print_handler) creates a MATLAB Runtime instance associated with library and allows you to specify how to handle error messages and printed text. The functions passed to libraryInitializeWithHandlers are installed in the MATLAB Runtime instance and called whenever error text or regular text outputs.

Examples

Initialize Library

Initialize the MATLAB Runtime instance associated with a C/C++ library named libtriangle.

Call the initialization function for the C library libtriangle in the main function of your C application code.

if (!libtriangleInitialize())
{
    fprintf(stderr, 
            "An error occurred while initializing: \n %s ",
            mclGetLastErrorMessage());
    return -2;
}

If initialization fails, an error message is printed to standard error.

Initialize Library With Handlers

By default, applications and shared libraries generated using MATLAB Compiler SDK™ send printed output to standard output and error messages to standard error. To change this behavior, write your own error and print handlers and pass them to libraryInitializeWithHandlers. To use a default handler, pass in mclDefaultPrintHandler or mclDefaultPrintHandler.

For a complete example, see the files located in matlabroot\extern\examples\compilersdk\c_cpp\catcherror.

Write a custom print handler function in your C/C++ application. This example code is written in C and uses two helper functions, StartMatlabOutput and EndMatlabOutput, to wrap a banner around the printed output.

static int PrintHandler(const char *s)
{
    /* Declare and initialize all variables */
    int len = 0;
    const char * prefix = "* ";
    int written = 0;

    if (s == NULL)
    {
        return 0;
    }

    len = strlen(s);

    /* DISP adds two carriage returns. Suppress the last one. */
    if (len >= 2 && s[len-1] == '\n' && s[len-2] == '\n')
    {
        len = len-1;
    }
    
    if (emitPrefix)
    {
        fwrite(prefix, sizeof(char), strlen(prefix), stdout);
    }
    
    written = fwrite(s, sizeof(char), len, stdout);

    if (s[len-1] == '\n')
    {
        emitPrefix = true;
    }
    else
    {
        emitPrefix = false;
    }

    return written;
}

static void StartMatlabOutput()
{
    const char *startBanner = "******** Start MATLAB output *******\n";
    emitPrefix = false;
    PrintHandler(startBanner);
}

static void EndMatlabOutput()
{
    const char *endBanner = "********* End MATLAB output ********\n";
    emitPrefix = false;
    PrintHandler(endBanner);
}

Write a custom error handler function.

static char LastError[2048];

static int ErrorHandler(const char *s)
{
    int len = 0;
    len = strlen(s);
    LastError[0] = '\0';
    strcpy(LastError, s);
    return len+1;
}

In your main function, after initializing variables, pass the print and error handlers to the libraryInitializeWithHandlers function.

if (!libcatcherrorInitializeWithHandlers(ErrorHandler, PrintHandler))
{
    fprintf(stderr,"Could not initialize the library.\n");
    return -2;
}
else
{
    /* Call the library function. */
    if (mlfRealacos(1, &out, in1))
    {
        /* Display the return value of the library function */
        printf("realacos(%6.4f) = \n", in1val);
        StartMatlabOutput();
        mlfReveal(out);
        EndMatlabOutput();
    }
    else
    {
        printf("Disaster! An unexpected error occurred.\n");
        printf("Error:\n%s\n", LastError);
    }

    /* Call the library termination routine */
    libcatcherrorTerminate();
        
    /* Free the memory allocated for the input variables. */
    mxDestroyArray(in1); 
    in1 = 0;
    mxDestroyArray(in2); 
    in2 = 0;
}

Input Arguments

library — Library name

Library name, specified as part of the function name. The library must be a C/C++ shared library generated by MATLAB Compiler SDK.

Example: libmatrix

error_handler — Error handler function

custom function | mclDefaultErrorHandler

Error handler function, specified as a custom user-written function or mclDefaultErrorHandler. The function must take a string and return the number of characters printed. For more details, see Print and Error Handling Functions.

Example: myErrorHandler

print_handler — Print handler function

custom function | mclDefaultPrintHandler

Print handler function, specified as a custom user-written function or mclDefaultPrintHandler. The function must take a string and return the number of characters printed. If the string sent to the standard error output stream does not end with a carriage return, the function must add one. For more details, see Print and Error Handling Functions.

Example: myPrintHandler

Output Arguments

bool — Initialization result

true | false

Initialization result, returned as a boolean value. Result indicates whether or not mcli initialization was successful. If the function returns false, calling any compiled functions results in unpredictable behavior.

Version History

Introduced in R2009a