MATLAB Application Program Interface Reference Help Desk

mexGetArray

Purpose

Get a copy of a variable from another workspace

C Syntax

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.

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

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

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

See Also

mexGetArrayPtr, mexPutArray



[ Previous | Help Desk | Next ]