engGetVariable (C)

Copy variable from MATLAB engine workspace

C Syntax

#include "engine.h"
mxArray *engGetVariable(Engine *ep, const char *name);

Description

engGetVariable reads the named mxArray from the MATLAB^® engine session associated with ep.

The limit for the size of data transferred is 2 GB.

Use mxDestroyArray to destroy the mxArray created by this routine when you are finished with it.

Note

The matlab::engine::MATLABEngine.getVariable function in the MATLAB Engine API for C++ is recommended over engGetVariable. The MATLAB Engine API for C++ includes modern C++ features for writing engine applications. For more information, see Call MATLAB from C++. There are no plans to remove engGetVariable or the Engine API for C.

Input Arguments

ep — Pointer to engine

Engine *

Pointer to engine, specified as Engine *.

name — Name of mxArray

const char *

Name of mxArray to get from the MATLAB engine workspace, specified as const char *.

Output Arguments

ptr — Pointer to mxArray

mxArray * | NULL

Pointer to a newly allocated mxArray structure, returned as mxArray *. The function returns NULL if the attempt fails. engGetVariable fails if the named variable does not exist.

Examples

Read Variable in C Engine Application on Windows

This C code shows how to read a variable from a C engine application on a Windows^® system.

The code first starts the MATLAB engine and then sends data to MATLAB for analysis and visualization. After performing eigenvalue calculations, the code captures MATLAB output using engOutputBuffer and then copies the eigenvalue mxArray variable from the MATLAB engine session using engGetVariable. The C code then accesses and uses the copied eigenvalue data.

 engwindemo.c

/*
 *	engwindemo.c
 *
 *	This program illustrates how to call MATLAB
 *	Engine functions from a C program on Windows.
 *
 * Copyright 1984-2017 The MathWorks, Inc.
 */
#include <windows.h>
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include "engine.h"
#include <matrix.h>
#define BUFSIZE 256

static double Areal[6] = { 1, 2, 3, 4, 5, 6 };

int PASCAL WinMain (HINSTANCE hInstance,
                    HINSTANCE hPrevInstance,
                    LPSTR     lpszCmdLine,
                    int       nCmdShow)

{
	Engine *ep;
	mxArray *T = NULL, *a = NULL, *d = NULL;
	char buffer[BUFSIZE+1];
	double *Dreal, *Dimag;
	double time[10] = { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 };

	/*
	 * Start MATLAB engine
	 */
	if (!(ep = engOpen(NULL))) {
		MessageBox ((HWND)NULL, (LPSTR)"Can't start MATLAB engine",
			(LPSTR) "Engwindemo.c", MB_OK);
		exit(-1);
	}

	/*
	 * PART I
	 *
	 * For the first half of this demonstration, we will send data
	 * to MATLAB, analyze the data, and plot the result.
	 */

	/*
	 * Create a variable from our data
	 */
	T = mxCreateDoubleMatrix(1, 10, mxREAL);
	/*
	 * Copy data from time to matrix T
	 */
	#if MX_HAS_INTERLEAVED_COMPLEX
		memcpy(mxGetDoubles(T), time, 10*sizeof(double));
	#else
		memcpy(mxGetPr(T), time, 10*sizeof(double));
	#endif
	/*
	 * Place the variable T into the MATLAB workspace
	 */
	engPutVariable(ep, "T", T);

	/*
	 * Evaluate a function of time, distance = (1/2)g.*t.^2
	 * (g is the acceleration due to gravity)
	 */
	engEvalString(ep, "D = .5.*(-9.8).*T.^2;");

	/*
	 * Plot the result
	 */
	engEvalString(ep, "plot(T,D);");
	engEvalString(ep, "title('Position vs. Time for a falling object');");
	engEvalString(ep, "xlabel('Time (seconds)');");
	engEvalString(ep, "ylabel('Position (meters)');");

	/*
	 * PART II
	 *
	 * Create another mxArray, put it into MATLAB,
	 * and calculate its eigen values.
	 * 
	 */

	a = mxCreateDoubleMatrix(3, 2, mxREAL);
	/*
	 * Copy data from Areal to matrix a
	 */
	#if MX_HAS_INTERLEAVED_COMPLEX
		memcpy(mxGetDoubles(a), Areal, 6*sizeof(double));
	#else
		memcpy(mxGetPr(a), Areal, 6*sizeof(double));
	#endif
	engPutVariable(ep, "A", a);

	/*
	 * Calculate the eigen value
	 */
	engEvalString(ep, "d = eig(A*A')");

	/*
	 * Use engOutputBuffer to capture MATLAB output. Ensure first that
	 * the buffer is always NULL terminated.
	 */
	buffer[BUFSIZE] = '\0';
	engOutputBuffer(ep, buffer, BUFSIZE);

	/*
	 * the evaluate string returns the result into the
	 * output buffer.
	 */
	engEvalString(ep, "whos");
	MessageBox ((HWND)NULL, (LPSTR)buffer, (LPSTR) "MATLAB - whos", MB_OK);

	/*
	 * Get the eigen value mxArray
	 */
	d = engGetVariable(ep, "d");
	engClose(ep);

	if (d == NULL) {
		MessageBox ((HWND)NULL, (LPSTR)"Get Array Failed", (LPSTR)"Engwindemo.c", MB_OK);
	}
	else {
		/*
		 * Using interleaved complex representation we can access complex number
		 * with a single pointer instead of using two separate pointers.
		 */
		#if MX_HAS_INTERLEAVED_COMPLEX
			if (mxIsComplex(d)) {
				sprintf(buffer,"Eigenval 2: %g+%gi",mxGetComplexDoubles(d)[1].real,mxGetComplexDoubles(d)[1].imag);
			}
			else {
				sprintf(buffer,"Eigenval 2: %g",mxGetDoubles(d)[1]);
			}
		#else
			Dreal = mxGetPr(d);
			Dimag = mxGetPi(d);
			if (Dimag) {
				sprintf(buffer,"Eigenval 2: %g+%gi",Dreal[1],Dimag[1]);
			}
			else {
				sprintf(buffer,"Eigenval 2: %g",Dreal[1]);
			}
		#endif
		MessageBox ((HWND)NULL, (LPSTR)buffer, (LPSTR)"Engwindemo.c", MB_OK);
		mxDestroyArray(d);
	} 

	/*
	 * We're done! Free memory, close MATLAB engine and exit.
	 */
	mxDestroyArray(T);
	mxDestroyArray(a);

	return(0);
}

/* LocalWords:  eigen eng Eigenval gi
 */

Read Variable in C Engine Application on Linux or macOS

This C code shows how to read a variable from a C engine application on a Linux^® or macOS system.

The code first starts the MATLAB engine and then sends data to MATLAB for analysis and visualization. Next, the code uses the MATLAB engine to evaluate a string. The code captures MATLAB output using engOutputBuffer and then copies an mxArray variable from the MATLAB engine session using engGetVariable. The C code then accesses and uses the copied variable data.

 engdemo.c

/*
 *	engdemo.c
 *
 *	A simple program to illustrate how to call MATLAB
 *	Engine functions from a C program.
 *
 * Copyright 1984-2016 The MathWorks, Inc.
 * All rights reserved
 */
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include "engine.h"
#define  BUFSIZE 256

int main()

{
	Engine *ep;
	mxArray *T = NULL, *result = NULL;
	char buffer[BUFSIZE+1];
	double time[10] = { 0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0 };

	/*
	 * Call engOpen with a NULL string. This starts a MATLAB process 
     * on the current host using the command "matlab".
	 */
	if (!(ep = engOpen(""))) {
		fprintf(stderr, "\nCan't start MATLAB engine\n");
		return EXIT_FAILURE;
	}

	/*
	 * PART I
	 *
	 * For the first half of this demonstration, send data
	 * to MATLAB, analyze the data, and plot the result.
	 */

	/* 
	 * Create a variable for the data
	 */
	T = mxCreateDoubleMatrix(1, 10, mxREAL);
	memcpy((void *)mxGetPr(T), (void *)time, sizeof(time));
	/*
	 * Place the variable T into the MATLAB workspace
	 */
	engPutVariable(ep, "T", T);

	/*
	 * Evaluate a function of time, distance = (1/2)g.*t.^2
	 * (g is the acceleration due to gravity)
	 */
	engEvalString(ep, "D = .5.*(-9.8).*T.^2;");

	/*
	 * Plot the result
	 */
	engEvalString(ep, "plot(T,D);");
	engEvalString(ep, "title('Position vs. Time for a falling object');");
	engEvalString(ep, "xlabel('Time (seconds)');");
	engEvalString(ep, "ylabel('Position (meters)');");

	/*
	 * use fgetc() to pause long enough to be
	 * able to see the plot
	 */
	printf("Hit return to continue\n\n");
	fgetc(stdin);
	/*
	 * We're done for Part I! Free memory, close MATLAB figure.
	 */
	printf("Done for Part I.\n");
	mxDestroyArray(T);
	engEvalString(ep, "close;");


	/*
	 * PART II
	 *
	 * For the second half of this demonstration, we will request
	 * a MATLAB string, which should define a variable X.  MATLAB
	 * will evaluate the string and create the variable.  We
	 * will then recover the variable, and determine its type.
	 */
	  
	/*
	 * Use engOutputBuffer to capture MATLAB output, so we can
	 * echo it back.  Ensure first that the buffer is always NULL
	 * terminated.
	 */

	buffer[BUFSIZE] = '\0';
	engOutputBuffer(ep, buffer, BUFSIZE);
	while (result == NULL) {
	    char str[BUFSIZE+1];
	    char *input = NULL;
	    /*
	     * Get a string input from the user
	     */
	    printf("Enter a MATLAB command to evaluate.  This command should\n");
	    printf("create a variable X.  This program will then determine\n");
	    printf("what kind of variable you created.\n");
	    printf("For example: X = 1:5\n");
	    printf(">> ");

	    input = fgets(str, BUFSIZE, stdin);
	  
	    /*
	     * Evaluate input with engEvalString
	     */
	    engEvalString(ep, str);
	    
	    /*
	     * Echo the output from the command.  
	     */
	    printf("%s", buffer);
	    
	    /*
	     * Get result of computation
	     */
	    printf("\nRetrieving X...\n");
	    if ((result = engGetVariable(ep,"X")) == NULL)
	      printf("Oops! You didn't create a variable X.\n\n");
	    else {
		printf("X is class %s\t\n", mxGetClassName(result));
	    }
	}

	/*
	 * We're done! Free memory, close MATLAB engine and exit.
	 */
	printf("Done!\n");
	mxDestroyArray(result);
	engClose(ep);
	
	return EXIT_SUCCESS;
}

Version History

Introduced before R2006a