mexGetArray (MATLAB Application Program Interface)

Get a copy of a variable from another workspace

#include "mex.h"
mxArray *mexGetArray(const char *name, const char *workspace);

Arguments

name
Name of the variable to copy into the MEX-file workspace.

workspace
Specifies where mexGetArray should search in order to find variable name. The possible values are


`"base"`	Search for variable `name` in the current MATLAB workspace.
`"caller"`	Search for variable `name` in the workspace of whatever entity (M-file, another MEX-file, MATLAB) called this MEX-file.
`"global"`	Search for variable `name` in the list of global variables. If variable `name` exists but is not tagged as a global variable, then `mexGetArray` returns `NULL`.

Returns

A copy of the mxArray on success. Returns NULL on failure. A common cause of failure is specifying a name not currently in the workspace. Perhaps the variable was in the workspace at one time but has since been cleared.

Description

Call mexGetArray to copy the specified variable name into your MEX-file's workspace. Once inside your MEX-file's workspace, your MEX-file may examine or modify the variable's data and characteristics.

The returned mxArray contains a copy of all the data and characteristics that variable name had in the other workspace. mexGetArray initializes the name field of the returned mxArray to the variable name.

Examples

Consider a MEX-file named FrwdBack that uses mexGetArray to grab a variable named Tangerines from the MATLAB workspace. The MEX-file then manipulates the data in Tangerines, and finally calls mexPutArray to place Tangerines back into the MATLAB workspace.

void
mexFunction(int nlhs,mxArray *plhs[],int nrhs,const mxArray 
*prhs[])
{
 mxArray  *array_ptr;
 double   *pr;
 int       num_elements, c;
 const char     *n;
 
 /* Get variable "Tangerines" from the MATLAB workspace. */ 
   array_ptr = mexGetArray("Tangerines", "base");
   if (array_ptr == NULL)
     mexErrMsgTxt("Could not get Tangerines from MATLAB 
     workspace.");

 /* Manipulate Tangerine's real data. */ 
   num_elements = mxGetM(array_ptr) * mxGetN(array_ptr);
   pr = mxGetPr(array_ptr);
   pr++; 
   for (c=2; c<num_elements; c++)  {
      *pr = *(pr-1) + *(pr+1);
      pr++;
   } 

 /* Copy the modified "Tangerines" back to the MATLAB 
    workspace. */
   mexPutArray(array_ptr, "base");
}

In MATLAB, create a variable named Tangerines. Then, call FrwdBack:

>> Tangerines = 1:10;
>> FrwdBack;

The call to mexPutArray puts Tangerines back into MATLAB's workspace. The resulting value of Tangerines is:

>> Tangerines
        1     4     8    13    19    26    34    43    53    10

For an additional example, see mexgetarray.c in the mex subdirectory of the examples directory.