Examples of MAT-File Applications

List of Examples

The matlabroot/examples/eng_mat folder contains C/C++ and Fortran source code for examples demonstrating how to use the MAT-file routines. These examples create standalone programs. The source code is the same for both Windows and UNIX systems.

For tips about how to modify other MATLAB examples to work with an mxArray in your application, see Examples for Working with mxArrays.

Back to Top

Creating a MAT-File in C

The matcreat.c example illustrates how to use the library routines to create a MAT-file that you can load into the MATLAB workspace. The program also demonstrates how to check the return values of MAT-function calls for read or write failures. To see the code, open the file in MATLAB Editor.

To produce an executable version of this program, compile the file and link it with the appropriate library. For details on platform specifics, see Compiling and Linking MAT-File Programs.

After compiling and linking your MAT-file program, you can run the standalone application you just produced. This program creates mattest.mat, a MAT-file that you can load into MATLAB. To run the application, depending on your platform, either double-click its icon or enter matcreat at the system prompt:

matcreat
Creating file mattest.mat...

To verify the MAT-file, at the command prompt, type:

whos -file mattest.mat
  Name               Size         Bytes  Class

  GlobalDouble       3x3             72  double array (global)
  LocalDouble        3x3             72  double array
  LocalString        1x43            86  char array

Grand total is 61 elements using 230 bytes

Back to Top

Creating a MAT-File in C++

There is a C++ version of matcreat.c in the matlabroot\extern\examples\eng_mat folder. To see matcreat.cpp, open the file in MATLAB Editor.

Back to Top

Reading a MAT-File in C/C++

The matdgns.c example illustrates how to use the library routines to read and diagnose a MAT-file. To see the code, open the file in MATLAB Editor.

After compiling and linking this program, you can view its results:

matdgns mattest.mat
Reading file mattest.mat...
 
Directory of mattest.mat:
GlobalDouble
LocalString
LocalDouble
 
Examining the header for each variable:
According to its header, array GlobalDouble has 2 dimensions
  and was a global variable when saved
According to its header, array LocalString has 2 dimensions
  and was a local variable when saved
According to its header, array LocalDouble has 2 dimensions
  and was a local variable when saved
 
Reading in the actual array contents:
According to its contents, array GlobalDouble has 2 dimensions
  and was a global variable when saved
According to its contents, array LocalString has 2 dimensions
  and was a local variable when saved
According to its contents, array LocalDouble has 2 dimensions
  and was a local variable when saved
Done

Back to Top

Creating a MAT-File in Fortran

The matdemo1.F example creates the MAT-file, matdemo.mat. To see the code, you can open the file in MATLAB Editor.

After compiling and linking your MAT-file program, you can run the standalone application you just produced. This program creates a MAT-file, matdemo.mat, that you can load into MATLAB. To run the application, depending on your platform, either double-click its icon or enter matdemo1 at the system prompt:

matdemo1
Creating MAT-file matdemo.mat ...
Done creating MAT-file

To verify the MAT-file, at the command prompt, enter:

 whos -file matdemo.mat
 Name          Size         Bytes  Class
 
 Numeric       3x3             72  double array
 String        1x33            66  char array
 
Grand total is 42 elements using 138 bytes

Note   For an example of a Microsoft Windows standalone program (not MAT-file specific), see engwindemo.c in the matlabroot\extern\examples\eng_mat folder.

Back to Top

Reading a MAT-File in Fortran

The matdemo2.F example illustrates how to use the library routines to read the MAT-file created by matdemo1.F and describe its contents. To see the code, open the file in MATLAB Editor.

After compiling and linking this program, you can view its results:

 matdemo2
 Directory of Mat-file:
 String                          
 Numeric                         
 Getting full array contents:
   1
 Retrieved String                          
   With size   1-by-  33
   3
 Retrieved Numeric                         
   With size   3-by-  3

Back to Top

Examples for Working with mxArrays

The MAT-File Interface Library lets you access MATLAB arrays (type mxArray) in a MAT-file. To work directly with an mxArray in a C/C++ or Fortran application, use functions in the MX Matrix Library. The options files already link to this library, as described in What You Need.

You can find examples for working with mxArrays in the matlabroot/extern/examples/mex and matlabroot/extern/examples/mx folders. The following topics show C code examples, based on these MEX examples, for working with cells and structures. The examples show how to read cell and structure arrays and display information based on the type of the mxArray within each array element.

If you create an application from one of the MEX examples, here are some tips for adapting the code to a standalone application.

• The MAT-file example, matdgns.c, shows how to open and read a MAT-file. For more information about the example, see Reading a MAT-File in C/C++.

• The MEX example, explore.c, has functions to read any MATLAB type using the mxClassID function. For more information about the example, see Using Data Types.

• Some MEX examples use functions, such as mexPrintf, from the MEX Library libmex. (For a complete list of these functions, see MEX Library.) You do not need to use these functions to work with an mxArray, but if your program calls any of them, you must link to the MEX Library. To do this, modify your options file to add libmex.lib to the link statement.

Read Structures from a MAT-File

The matreadstructarray.c example is based on the analyze_structure function in explore.c. For simplicity this example only processes real elements of type double; refer to the explore.c example for error checking and processing other types.

 matreadstructarray.c

/*
 * Read a structure array STRUCT from MATFILE and
 * sum the first real numeric value in FIELD for each 
 * record/element in the array.
 *
 * Calling syntax:
 *
 *   matreadstructarray <matfile> <struct> <field>
 *
 * Copyright 2012 The MathWorks, Inc.
 */

#include <stdlib.h>
#include "mat.h"

/* Analyze field FNAME in struct array SPTR. */
static void
analyzestructarray(const mxArray *sPtr, const char *fName)
{
    mwSize nElements;       /* number of elements in array */
    mwIndex eIdx;           /* element index */
    const mxArray *fPtr;    /* field pointer */
    double *realPtr;        /* pointer to data */
    double total;           /* value to calculate */
    
    total = 0;
    nElements = (mwSize)mxGetNumberOfElements(sPtr);
    for (eIdx = 0; eIdx < nElements; eIdx++) {
        fPtr = mxGetField(sPtr, eIdx, fName);
        if ((fPtr != NULL) 
            && (mxGetClassID(fPtr) == mxDOUBLE_CLASS) 
            && (!mxIsComplex(fPtr))) 
        {
            realPtr = mxGetPr(fPtr);
            total = total + realPtr[0];
        }
    }
    printf("Total for %s: %.2f\n", fName, total);
}

/* Find struct array ARR in MAT-file FILE.
 * Pass field name FIELD to analyzestructarray function. */
int findstructure(
        const char *file,
        const char *arr,
        const char *field) {
    
    MATFile *mfPtr; /* MAT-file pointer */
    mxArray *aPtr;  /* mxArray pointer */
    
    mfPtr = matOpen(file, "r");
    if (mfPtr == NULL) {
        printf("Error opening file %s\n", file);
        return(1);
    }
    
    aPtr = matGetVariable(mfPtr, arr);
    if (aPtr == NULL) {
        printf("mxArray not found: %s\n", arr);
        return(1);
    }
    
    if (mxGetClassID(aPtr) == mxSTRUCT_CLASS) {
        if (mxGetFieldNumber(aPtr, field) == -1) {
            printf("Field not found: %s\n", field);
        }
        else {
            analyzestructarray(aPtr, field);
        }
    } 
    else {
        printf("%s is not a structure\n", arr);
    }
    mxDestroyArray(aPtr);
    
    if (matClose(mfPtr) != 0) {
        printf("Error closing file %s\n", file);
        return(1);
    }
    return(0);
}

int main(int argc, char **argv)
{
/* argv[1] = MAT-file name
 * argv[2] = name of mxArray structure
 * argv[2] = name of field */

    int result;
    if (argc > 3)
        result = findstructure(argv[1], argv[2], argv[3]);
    else {
        result = 0;
        printf("Usage: matreadstructarray <matfile> <struct> <field>\n");
    }
    return (result==0)?EXIT_SUCCESS:EXIT_FAILURE;
}

After compiling and linking your MAT-file program, you can run the standalone application on the following MAT-file, testpatient.mat. Create a structure, patient, and save it:

patient(1).name = 'John Doe';
patient(1).billing = 127.00;
patient(1).test = [79 75 73; 180 178 177.5; 172 170 169];
patient(2).name = 'Ann Lane';
patient(2).billing = 28.50;
patient(2).test = [68 70 68; 118 118 119; 172 170 169];

save('testpatient.mat')

To calculate the total of the billing field, type:

!matreadstruct testpatient.mat patient billing

Total for billing: 155.50 

Read Cell Arrays from a MAT-File

The matreadcellarray.c example is based on the analyze_cell function in explore.c.

 matreadcellarray.c

/*
 * Read a cell array CELL from MATFILE and
 * display class for each element.
 *
 * Calling syntax:
 *
 *   matreadcellarray <matfile> <cell>
 *
 * See the MATLAB External Interfaces Guide for 
 * compiling information.
 *
 * Copyright 2012 The MathWorks, Inc.
 */

#include <stdlib.h>
#include "mat.h"

/* Access each cell in cell array CPTR. */
static void
analyzecellarray(const mxArray *cPtr)
{
    mwSize nCells;          /* number of cells in array */
    mwIndex cIdx;           /* cell index */
    const mxArray *ePtr;    /* element pointer */
    mxClassID category;     /* class ID */
    
    nCells = (mwSize)mxGetNumberOfElements(cPtr);
    for (cIdx = 0; cIdx < nCells; cIdx++) {
        ePtr = mxGetCell(cPtr, cIdx);
        if (ePtr == NULL) {
            printf("Empty Cell\n");
            break;
        }
        category = mxGetClassID(ePtr);
        printf("%d: ", cIdx);
        switch (category) {
            case mxCHAR_CLASS:
                printf("string\n");
                //see revord.c
                break;
            case mxSTRUCT_CLASS:
                printf("structure\n");
                //see analyzestructure.c
                break;
            case mxCELL_CLASS:
                printf("cell\n");
                printf("{\n");
                analyzecellarray(ePtr);
                printf("}\n");
                break;
            case mxUNKNOWN_CLASS:
                printf("Unknown class\n");
                break;
            default:
                if (mxIsSparse(ePtr)) {
                    printf("sparse array\n");
                    //see mxsetnzmax.c
                } 
                else {
                    printf("numeric class\n");
                }
                break;
        }
    }
}

/* Find cell array ARR in MAT-file FILE. */
int findcell(const char *file, const char *arr) {
    
    MATFile *mfPtr; /* MAT-file pointer */
    mxArray *aPtr;  /* mxArray pointer */
    
    mfPtr = matOpen(file, "r");
    if (mfPtr == NULL) {
        printf("Error opening file %s\n", file);
        return(1);
    }
    
    aPtr = matGetVariable(mfPtr, arr);
    if (aPtr == NULL) {
        printf("mxArray not found: %s\n", arr);
        return(1);
    }
    
    if (mxGetClassID(aPtr) == mxCELL_CLASS) {
        analyzecellarray(aPtr);
    } 
    else {
        printf("%s is not a cell array\n", arr);
    }
    mxDestroyArray(aPtr);
    
    if (matClose(mfPtr) != 0) {
        printf("Error closing file %s\n", file);
        return(1);
    }
    return(0);
}

int main(int argc, char **argv)
{
/* argv[1] = MAT-file name
 * argv[2] = name of mxArray cell array */

    int result;
    if (argc > 2)
        result = findcell(argv[1], argv[2]);
    else {
        result = 0;
        printf("Usage: matreadcellarray <matfile> <cell>\n");
    }
    return (result==0)?EXIT_SUCCESS:EXIT_FAILURE;
}

After compiling and linking your MAT-file program, you can run the standalone application on the following MAT-file, testcells.mat. Create 3 cell variables and save:

cellvar = {'hello'; [2 3 4 6 8 9]; [2; 4; 5]};
structvar = {'cell with a structure'; patient; [2; 4; 5]};
multicellvar = {'cell with a cell'; cellvar; patient};
save('testcells.mat','cellvar','structvar','multicellvar')

To display the mxArray type for the contents of cell cellvar, type:

!matreadcell testcells.mat cellvar

0: string 
1: numeric class 
2: numeric class

Back to Top

Copying External Data into MAT-File Format with Standalone Programs

Compiling and Linking MAT-File Programs

Recommended Products

• MATLAB
• Signal Processing Toolbox
• Optimization Toolbox
• Statistics Toolbox
• Control System Toolbox

Get MATLAB trial software

Includes the most popular MATLAB recorded presentations with Q&A sessions led by MATLAB experts.

Get the Interactive Kit