Documentation

This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English verison of the page.

Note: This page has been translated by MathWorks. Please click here
To view all translated materals including this page, select Japan from the country navigator on the bottom of this page.

Call a Shared Library

To use a MATLAB® Compiler SDK™ generated shared library in your application:

  1. Include the generated header file for each library in your application.

    Each generated shared library has an associated header file named libname.h.

  2. Initialize the MATLAB Runtime proxy layer by calling mclmcrInitialize().

  3. Use mclRunMain() to call the C function where your MATLAB functions are used.

    mclRunMain() provides a convenient cross platform mechanism for wrapping the execution of MATLAB code.

    Caution

    Do not use mclRunMain() if your application brings up its own full graphical environment.

  4. Initialize the MATLAB Runtime and set the global settings by calling mclInitializeApplication() API function.

    Call the mclInitializeApplication() function once per application, and it must be called before calling any other MATLAB API functions. You may pass in application-level options to this function. mclInitializeApplication() returns a Boolean status code.

  5. For each MATLAB Compiler SDK generated shared library that you include in your application, call the initialization function for the library.

    The initialization function performs library-local initialization. It unpacks the deployable archive and starts a MATLAB Runtime instance with the necessary information to execute the code in that archive. The library initialization function is named libnameInitialize(). This function returns a Boolean status code.

    Note

    On Windows®, if you want to have your shared library call a MATLAB shared library, the MATLAB library initialization function (e.g., <libname>Initialize, <libname>Terminate, mclInitialize, mclTerminate) cannot be called from your shared library during the DllMain(DLL_ATTACH_PROCESS) call. This applies whether the intermediate shared library is implicitly or explicitly loaded. Place the call somewhere after DllMain().

  6. Call the exported functions of each library as needed.

  7. When your application no longer needs a given library, call the termination function for the library.

    The terminate function frees the resources associated with the libraries MATLAB Runtime instance. The library termination function is named libnameTerminate(). Once a library has been terminated, the functions exported by the library cannot be called again in the application.

  8. When your application no longer needs to call any MATLAB Compiler SDK generated libraries, call the mclTerminateApplication API function.

    This function frees application-level resources used by the MATLAB Runtime. Once you call this function, no further calls can be made to MATLAB Compiler SDK generated libraries in the application.

The following code example is from matrixdriver.c:

#include stdio.h

/* Include the MATLAB Runtime header file and the library specific header file 
 * as generated by MATLAB Compiler SDK */

#include "libmatrix.h"

/* This function is used to display a double matrix stored in an mxArray */

void display(const mxArray* in);

int run_main(int argc, char **argv)
{
    mxArray *in1, *in2; /* Define input parameters */
    mxArray *out = NULL;/* and output parameters to be passed to the library functions */
    
    double data[] = {1,2,3,4,5,6,7,8,9};
    
    /* Create the input data */
    in1 = mxCreateDoubleMatrix(3,3,mxREAL);
    in2 = mxCreateDoubleMatrix(3,3,mxREAL);
    memcpy(mxGetPr(in1), data, 9*sizeof(double));
    memcpy(mxGetPr(in2), data, 9*sizeof(double));
    
    /* Call the library initialization routine and make sure that the
     * library was initialized properly. */

    if (!libmatrixInitialize()){
        fprintf(stderr,"Could not initialize the library.\n");
        return -2;
    }
    else
    {
        /* Call the library function */
        mlfAddmatrix(1, &out, in1, in2);

    /* Display the return value of the library function */

        printf("The value of added matrix is:\n");
        display(out);

    /* Destroy the return value since this variable will be reused in
     * the next function call. Since we are going to reuse the variable,
     * we have to set it to NULL. Refer to MATLAB Compiler SDK documentation
     * for more information on this. */

        mxDestroyArray(out); out=0;
        mlfMultiplymatrix(1, &out, in1, in2);
        printf("The value of the multiplied matrix is:\n");
        display(out);
        mxDestroyArray(out); out=0;
        mlfEigmatrix(1, &out, in1);
        printf("The eigenvalues of the first matrix are:\n");
        display(out);
        mxDestroyArray(out); out=0;
        
    /* Call the library termination routine */
        libmatrixTerminate();
        
    /* Free the memory created */
        mxDestroyArray(in1); in1=0;
        mxDestroyArray(in2); in2 = 0;
    }

/* Note that you should call mclTerminate application at the end of
 * your application. */

    mclTerminateApplication();
    return 0;
}

/*DISPLAY This function will display the double matrix stored in an mxArray.
 * This function assumes that the mxArray passed as input contains double
 * array. */
 
void display(const mxArray* in)
{
    int i=0, j=0; /* loop index variables */
    int r=0, c=0; /* variables to store the row and column length of the matrix */
    double *data; /* variable to point to the double data stored within the mxArray */

    /* Get the size of the matrix */
    r = mxGetM(in);
    c = mxGetN(in);

    /* Get a pointer to the double data in mxArray */
    data = mxGetPr(in);
    
    /* Loop through the data and display the same in matrix format */
    for( i = 0; i < c; i++ ){
        for( j = 0; j < r; j++){
            printf("%4.2f\t",data[j*c+i]);
        }
        printf("\n");
    }
    printf("\n");
}

int main()
{
    /* Call the mclInitializeApplication routine. Make sure that the application
     * was initialized properly by checking the return status. This initialization
     * has to be done before calling any MATLAB API's or MATLAB Compiler SDK generated
     * shared library functions. */

    if( !mclInitializeApplication(NULL,0) )
    {
        fprintf(stderr, "Could not initialize the application.\n");
    	return -1;
    }
    return mclRunMain((mclMainFcnType)run_main,0,NULL);
}

Restrictions When Using MATLAB Function loadlibrary

You cannot use the MATLAB function loadlibrary inside of MATLAB to load a C shared library built with MATLAB Compiler SDK.

For more information about using loadlibrary, see Calling Shared Libraries in Deployed Applications (MATLAB Compiler).

Was this topic helpful?