Copy External Data into MAT-File Format with Standalone Programs

Overview of matimport.c Example

This topic shows how to create a standalone program, matimport, to copy data from an external source into a MAT-file. The format of the data is custom, that is, it is not one of the file formats supported by MATLAB^®.

The matimport.c example:

Creates variables to read the external data.
Copies the data into mxArray variables.
Assigns a variable name to each mxArray. Use these variable names in the MATLAB workspace.
Writes the mxArray variables and associated variable names to the MAT-file.

To use the data in MATLAB:

Build the standalone program matimport.
Run matimport to create the MAT-file matimport.mat.
Open MATLAB.
Use one of the techniques described in Save and Load Workspace Variables.

The following topics describe these steps in detail. To see the code, open the file in the MATLAB Editor. The C statements in these topics are code snippets shown to illustrate a task. The statements in the topics are not necessarily sequential in the source file.

Declare Variables for External Data

There are two external data values, a string and an array of type double. The following table shows the relationship between the variables in this example.

External Data	Variable to Read External Data	mxArray Variable	MATLAB Variable Name
Array of type `double`	`extData`	`pVarNum`	`inputArray`
String	`extString`	`pVarChar`	`titleString`

The following statements declare the type and size for variables extString and extData.

#define BUFSIZE 256
char extString[BUFSIZE];
double extData[9];

Use these variables to read values from a file or a subroutine available from your product. This example uses initialization to create the external data.

const char *extString = "Data from External Device";
double extData[9] = { 1.0, 4.0, 7.0, 2.0, 5.0, 8.0, 3.0, 6.0, 9.0 };

Create mxArray Variables

Functions in the MAT-File API use pointers of type mxArray to reference MATLAB data. These statements declare pVarNum and pVarChar as pointers to an array of any size or type.

/*Pointer to the mxArray to read variable extData */
mxArray *pVarNum;
/*Pointer to the mxArray to read variable extString */
mxArray *pVarChar;

To create a variable of the proper size and type, select one of the mxCreate* functions from the MX Matrix Library.

The size of extData is 9, which the example copies into a 3-by-3 matrix. Use the mxCreateDoubleMatrix function to create a two-dimensional, double-precision, floating-point mxArray initialized to 0.

pVarNum = mxCreateDoubleMatrix(3,3,mxREAL);

Use the mxCreateString function to create an mxArray variable for extString.

pVarChar = mxCreateString(extString);

Create MATLAB Variable Names

matimport.c assigns variable names inputArray and titleString to the mxArray data. Use these names in the MATLAB workspace. For more information, see View Contents of MAT-File.

const char *myDouble = "inputArray";
const char *myString = "titleString";

Read External Data into mxArray Data

Copy data from the external source into each mxArray.

The C memcpy function copies blocks of memory. This function requires pointers to the variables extData and pVarNum. The pointer to extData is (void *)extData. To get a pointer to pVarNum, use one of the mxGet* functions from the Matrix API. Since the data contains only real values of type double, this example uses the mxGetPr function.

memcpy((void *)(mxGetPr(pVarNum)), (void *)extData, sizeof(extData));

The following statement initializes the pVarChar variable with the contents of extString.

pVarChar = mxCreateString(extString);

Variables pVarNum and pVarChar now contain the external data.

Create and Open MAT-File

The matOpen function creates a handle to a file of type MATFile. The following statements create a file pointer pmat, name the file matimport.mat, and open it for writing.

	MATFile *pmat;
	const char *myFile = "matimport.mat";
	pmat = matOpen(myFile, "w");

Write mxArray Data to File

The matPutVariable function writes the mxArray and variable name into the file.

	status = matPutVariable(pmat, myDouble, pVarNum);
	status = matPutVariable(pmat, myString, pVarChar);

Clean Up

To close the file:

matClose(pmat);

To free memory:

mxDestroyArray(pVarNum);
mxDestroyArray(pVarChar);

Build the Application

To build the application, use the mex function with the -client engine option.

copyfile(fullfile(matlabroot,'extern','examples','eng_mat','matimport.c'),'.','f')
mex -v -client engine matimport.c

Create the MAT-File

Run matimport to create the file matimport.mat. Either invoke the program from the system command prompt, or at the MATLAB command prompt, type:

!matimport

Import Data into MATLAB

Any user with a compatible version of MATLAB can read the matimport.mat file. Start MATLAB and use the load command to import the data into the workspace.

load matimport.mat

To display the variables, type:

whos

  Name             Size            Bytes  Class

  inputArray       3x3                72  double
  titleString      1x43               86  char