mexGetVariablePtr (C and Fortran)

Read-only pointer to variable from another workspace

C Syntax

#include "mex.h"
const mxArray *mexGetVariablePtr(const char *workspace, 
  const char *varname);

Fortran Syntax

#include "fintrf.h"
mwPointer mexGetVariablePtr(workspace, varname)
character*(*) workspace, varname

Description

Call mexGetVariablePtr to get a read-only pointer to the specified variable, varname, into your MEX-file workspace. This command is useful for examining an mxArray's data and characteristics. If you want to change data or characteristics, use mexGetVariable (along with mexPutVariable) instead of mexGetVariablePtr.

If you simply want to examine data or characteristics, mexGetVariablePtr offers superior performance because the caller wants to pass only a pointer to the array.

Input Arguments

workspace — Workspace name

const char* | character*(*)

Workspace name you want mexGetVariablePtr to search, specified as const char* in C or character*(*) in Fortran. The possible values are:

base	Search for the variable in the base workspace.
caller	Search for the variable in the caller workspace.
global	Search for the variable in the global workspace.

varname — Variable name

const char* | character*(*)

Name of a variable in another workspace, specified as const char* in C or character*(*) in Fortran. This is a variable name, not an mxArray pointer.

Output Arguments

mxArray — Pointer to mxArray

const mxArray* | mwPointer | NULL

Read-only pointer to the mxArray on success, returned as const mxArray* in C or mwPointer in Fortran. Returns NULL in C or 0 in Fortran on failure.

Note

mexGetVariablePtr returns a pointer to a const mxArray owned by the MATLAB^® workspace and must only be used inside the MEX function. Do not store the pointer for use after the MEX function returns to MATLAB. Likewise, if your MEX function calls mexCallMATLAB, do not use the variable pointer after the call to MATLAB.

Limitations

• If you use this function in Simulink^® S-functions, do not store the resulting plhs mxArray pointers in any S-function block state that persists after the MEX function finishes. Outputs of this function have temporary scope and are automatically destroyed at the end of the MEX function call.

Version History

Introduced before R2006a