Using the C Math Library

Example - Saving and Loading Data (ex5.c)

This example demonstrates how to use the functions mlfSave() and mlfLoad()to write data to a disk file and read it back again.

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.

/* ex5.c */

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

main()
{
    mxArray *x = NULL, *y = NULL, *z = NULL;            /* 2 */
    mxArray *a = NULL, *b = NULL, *c = NULL;

    mlfEnterNewContext(0, 0);

    mlfAssign(&x, 
           mlfRand(mlfScalar(4),mlfScalar(4),NULL));    /* 3 */
    mlfAssign(&y, mlfMagic(mlfScalar(7)));
    mlfAssign(&z, mlfEig(NULL, x, NULL));

    mlfSave(mxCreateString("ex5.mat"), "w",
               "x", x, "y", y, "z", z, NULL);           /* 4 */

    mlfLoad(mxCreateString("ex5.mat"),
               "x", &a, "y", &b, "z", &c, NULL);        /* 5 */

    if (mlfTobool(mlfIsequal(a, x, NULL)) &&            /* 6 */
        mlfTobool(mlfIsequal(b, y, NULL)) && 
        mlfTobool(mlfIsequal(c, z, NULL)))
    {
        mlfPrintf("Success: all variables equal.\n");
    }
    else
    {
        mlfPrintf("Failure: loaded values not equal to saved 
                   values.\n");
    }

    mxDestroyArray(x);                                  /* 7 */
    mxDestroyArray(y);
    mxDestroyArray(z);
    mxDestroyArray(a);
    mxDestroyArray(b);
    mxDestroyArray(c);

    mlfRestorePreviousContext(0, 0);

    return(EXIT_SUCCESS);
}

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

1. 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.
2. Declare and initialize variables.  x, y, and z will be written to the MAT-file using mlfSave(). a, b, and c will store the data read from the MAT-file by mlfLoad().
3. Assign data to the variables that will be saved to a file. x stores a 4-by-4 array that contains randomly generated numbers. y stores a 7-by-7 magic square. z contains the eigenvalues of x. Note that mlfRand() is a varargin function; you must terminate the argument list with NULL.

The MATLAB C Math Library utility function mlfScalar() creates 1-by-1 arrays that hold an integer or double value.

4. Save three variables to the file "ex5.mat". You can save any number of variables to the file identified by the first argument to mlfSave(). The second argument specifies the mode for writing to the file. Here "w" indicates that mlfSave() should overwrite the data. Other values include "u" to update (append) and "w4" to overwrite using V4 format. Subsequent arguments come in pairs: the first argument in the pair (a string) labels the variable in the file; the contents of the second argument is written to the file. A NULL terminates the argument list.

Note that you must provide a name for each variable you save. When you retrieve data from a file, you must provide the name of the variable you want to load. You can choose any name for the variable; it does not have to correspond to the name of the variable within the program. Unlike arguments to most MATLAB C Math Library functions, the variable names and mode are not mxArray arguments; you can pass a C string directly to mlfSave() and mlfLoad().

5. Load the named variables from the MAT-file. As arguments, you pass the name of the MAT-file (the string ex5.mat), the name/variable pairs, and a NULL to terminate the argument list. Note that, because you're loading data into a variable, mlfLoad() needs the address of the variables: &a, &b, &c. Notice how the name of the output argument does not have to match the name of the variable in the MAT-file.

Note    mlfLoad() is not a type-safe function. It is declared as mlfLoad(mxArray *file, ... ). The compiler will not complain if you forget to include an & in front of the output arguments. However, your application will fail at runtime.

6. Compare the data loaded from the file to the original data that was written to the file. a, b, and c contain the loaded data. x, y, and z contain the original data. Each call to mlfIsEqual() returns a temporary scalar mxArray containing TRUE if the compared arrays are the same type and size, with identical contents. mlfTobool() returns the Boolean value contained in the array. The calls to mlfTobool() are necessary because C requires that the condition for an if statement be a scalar Boolean, not a scalar mxArray.
7. Free each of the matrices used in the examples.

   Output

When run, the program produces this output:

Success: all variables equal.

Reading Data from a MAT-File

Handling Errors and Writing a Print Handler