Calling Library Routines (Using the C Math Library)

Using the C Math Library

Example - Calling Library Routines (ex3.c)

This example program illustrates how to call library routines that take multiple, optional arguments. The example uses the singular value decomposition function mlfSvd.

You can find the code for this example in the
<matlab>/extern/examples/cmath directory on UNIX systems or the <matlab>\extern\examples\cmath directory on PCs, where <matlab> represents the top-level directory of your installation. See Building Stand-Alone C Applications in Chapter 2 for information on building the examples.

/* ex3.c */

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "matlab.h"                                      /* 1 */

static double data[] = { 1, 3, 5, 7, 2, 4, 6, 8 };       /* 2 */

main()
{
    mxArray *X = NULL;                                   /* 3 */
    mxArray *U = NULL, *S = NULL, *V = NULL;

    mlfEnterNewContext(0, 0);
    mlfAssign(&X, mlfDoubleMatrix(4, 2, data, NULL));

    mlfAssign(&U, mlfSvd(NULL, NULL, X, NULL));          /* 4 */
    mlfPrintf("One input, one output:\nU = \n");
    mlfPrintMatrix(U);

    mlfAssign(&U, mlfSvd(&S, &V, X, NULL));              /* 5 */
    mlfPrintf("One input, three outputs:\n");
    mlfPrintf("U = \n"); mlfPrintMatrix(U); 
    mlfPrintf("S = \n"); mlfPrintMatrix(S);
    mlfPrintf("V = \n"); mlfPrintMatrix(V);

    mlfAssign(&U, mlfSvd(&S, &V, X, mlfScalar(0.0)));    /* 6 */
    mlfPrintf("Two inputs, three outputs:\n");
    mlfPrintf("U = \n"); mlfPrintMatrix(U);
    mlfPrintf("S = \n"); mlfPrintMatrix(S);
    mlfPrintf("V = \n"); mlfPrintMatrix(V);

    mxDestroyArray(X);                                   /* 7 */
    mxDestroyArray(U);
    mxDestroyArray(S);
    mxDestroyArray(V);
    mlfRestorePreviousContext(0, 0);
    return(EXIT_SUCCESS);
}

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

Include "matlab.h". This file contains the declaration of the mxArray data structure and the prototypes for all the functions in the library. stdlib.h contains the definition of EXIT_SUCCESS.
Declare the eight-element static array that subsequently initializes the mlfSvd input matrix. The elements in this array appear in column-major order. The MATLAB C Math Library stores its array data in column-major order, unlike C, which stores array data in row-major order.
Declare and initialize the mlfSvd input array, X. Declare and initialize mxArray* variables, U, S, and V, to be used as output arguments in later calls to mlfSvd.
mlfSvd can be called in three different ways. Call it the first way, with one input matrix and one output matrix. Note that the optional inputs and outputs in the parameter list are set to NULL. Optional, in this case, does not mean that the arguments can be omitted from the parameter list; instead it means that the argument is optional to the workings of the function and that it can be set to NULL.

Print the result of the call to mlfSvd().

If you want to know more about the function mlfSvd() or the calling conventions for the library, refer to the online MATLAB C Math Library Reference.

Call mlfSvd the second way, with three output arguments and one input argument. The additional output arguments, S and V, appear first in the argument list. Because the return value from mlfSvd corresponds to the first output argument, U, only two output arguments, S and V, appear in the argument list, bringing the total number of outputs to three. The next argument, X, is the required input argument. Only the final argument, the optional input, is passed as NULL.

Print all of the output matrices.

Call mlfSvd the third way, with three output arguments and two input arguments. Print all of the output matrices.

Notice that in this call, as in the previous one, an ampersand (&) precedes the two additional output arguments. An ampersand always precedes each output argument because the address of the mxArray* is passed. The presence of an & is a reliable way to distinguish between input and output arguments. Input arguments never have an & in front of them.

Last of all, free all of the matrices that have been bound to variables.
Output

When the program is run, it produces this output.

One input, one output:
U = 
   14.2691
    0.6268
 
One input, three outputs:
U = 
    0.1525    0.8226   -0.3945   -0.3800
    0.3499    0.4214    0.2428    0.8007
    0.5474    0.0201    0.6979   -0.4614
    0.7448   -0.3812   -0.5462    0.0407
 
S = 
   14.2691         0
         0    0.6268
         0         0
         0         0
 
V = 
    0.6414   -0.7672
    0.7672    0.6414
 
Two inputs, three outputs:
U = 
    0.1525    0.8226
    0.3499    0.4214
    0.5474    0.0201
    0.7448   -0.3812
 
S = 
   14.2691         0
         0    0.6268
 
V = 
    0.6414   -0.7672
    0.7672    0.6414

Summary of Library Calling Conventions Calling Operators