Manage MATLAB Data in C/C++ Clients
The MATLAB® Runtime works with a single object type: the MATLAB array. All MATLAB variables (including scalars, vectors, matrices, character arrays, cell
arrays, structures, and objects) are stored as MATLAB arrays. In the MATLAB
Production Server™ C/C++ client API, the MATLAB array is declared to be of type
mpsArray structure contains the following information about the
Data associated with the array
If numeric, whether the variable is real or complex
If sparse, its indices and nonzero maximum elements
If a structure or object, the number of fields and field names
To access the
mpsArray structure, use the
mpsArray API functions. These functions enable you to create,
read, and query information about the MATLAB data used by the client.
mpsArray API mirrors the
used by MATLAB
Compiler SDK™ and MATLAB external interfaces.
MATLAB stores data in a column-major (columnwise) numbering scheme. MATLAB internally stores data elements from the first column first, then data elements from the second column second, and so on, through the last column.
For example, given the matrix:
a=['house'; 'floor'; 'porch'] a = house floor porch
its dimensions are:
size(a) ans = 3 5
and its data is stored as:
If a matrix is N-dimensional, MATLAB represents the data in N-major order. Consider a three-dimensional array of capital letters having dimensions 4-by-2-by-3. You can visualize the data in three pages of 4-by-2 matrices, as shown in this figure:
MATLAB internally represents the data for this three-dimensional array in the following order:
mpsCalcSingleSubscript() function creates the offset from the
first element of an array to the desired element, using N-dimensional subscripting.
MATLAB indexing starts at 1 where C indexing starts at 0.
Complex Double-Precision Matrices
Complex double-precision, non-sparse matrices are of type double and have
dimensions m-by-n, where
m is the number of rows and
n is the number of columns. The data is stored as two vectors
of double-precision numbers—one contains the real data and one contains the
imaginary data. The pointers to this data are referred to as
(pointer to real data) and
pi (pointer to imaginary data),
respectively. A non-complex matrix is one whose
Numeric matrices are single-precision floating-point integers that can be 8-, 16-, 32, and 64-bit, both signed and unsigned. The data is stored in two vectors in the same manner as double-precision matrices.
logical data type represents a logical
false state using the numbers
0, respectively. Certain MATLAB functions and operators return logical
1 or logical
0 to indicate whether a certain condition was found to be
true or not. For example, the statement
(5 * 10) > 40 returns
MATLAB Character Arrays
MATLAB character arrays are of type
char and are stored in
a similar manner as unsigned 16-bit integers, except there is no imaginary data
component. Unlike C, MATLAB character arrays are not null terminated.
Cell arrays are a collection of MATLAB arrays where each
mpsArray is referred to as a
cell, enabling MATLAB arrays of different types to be stored together. Cell arrays are
stored in a similar manner to numeric matrices, except the data portion contains a
single vector of pointers to
mpsArrays. Members of this vector
are called cells. Each cell can be of any supported data type, even another cell
Structures are MATLAB arrays with elements accessed by textual field designators.
Following is an example of how structures are created in MATLAB:
S.name = 'Ed Plum'; S.score = 83; S.grade = 'B+'
creates a scalar structure with three fields:
S = name: 'Ed Plum' score: 83 grade: 'B+'
A 1-by-1 structure is stored in the same manner as a 1-by-
cell array where
n is the number of fields in the structure.
Members of the data vector are called fields. Each field is associated with a name
stored in the
A multidimensional array is a vector of integers where each element is the size of the corresponding dimension. The storage of the data is the same as matrices. MATLAB arrays of any type can be multidimensional.
MATLAB arrays of any type can be empty. An empty
is one with at least one dimension equal to zero. For example, a double-precision
mpsArray of type
NULL, is an empty array.
Sparse matrices have a different storage convention from that of full matrices in
MATLAB. The parameters
still arrays of double-precision numbers, but these arrays contain only nonzero data
elements. There are three additional parameters:
nzmaxis an integer that contains the length of
pr, and, if it exists,
pi. It is the maximum number of nonzero elements in the sparse matrix.
irpoints to an integer array of length
nzmaxcontaining the row indices of the corresponding elements in
jcpoints to an integer array of length
n+1, where n is the number of columns in the sparse matrix. The
jcarray contains column index information. If the
jth column of the sparse matrix has any nonzero elements,
jc[j]is the index in
piif it exists) of the first nonzero element in the
jth column, and
jc[j+1] - 1is the index of the last nonzero element in that column. For the
jth column of the sparse matrix,
jc[j]is the total number of nonzero elements in all preceding columns. The last element of the
jc[n], is equal to
nnz, the number of nonzero elements in the entire sparse matrix. If
nnzis less than
nzmax, more nonzero entries can be inserted into the array without allocating more storage.
Using Data Types
You can write MATLAB Production Server client applications in C/C++ that accept any class or data type supported by MATLAB (see MATLAB Types).
The MATLAB Runtime does not check the validity of MATLAB data structures created in C/C++. Using invalid syntax to create a MATLAB data structure can result in unexpected behavior.
Declaring Data Structures
To handle MATLAB arrays, use type
mpsArray. The following statement
To define the values of
myData, use one of the
mpsCreate* functions. Some useful array creation routines are
mpsCreateCharArray(). For example, the following statement
myData = mpsCreateDoubleMatrix(m, 1, mpsREAL);
C/C++ programmers should note that data in a MATLAB array is in column-major order. (For an illustration, see Data Storage.) Use the
mpsGet* array access routines
to read data from an
mpsGet* array access routines get references to the data in
mpsArray. Use these routines to modify data in your client
application. Each function provides access to specific information in the
mpsArray. Some useful functions are
following statements read the input character array
prhs into a
char *buf; int buflen; int status; buflen = mpsGetN(prhs)*sizeof(mpsChar)+1; buf = malloc(buflen); status = mpsGetString(prhs, buf, buflen);