Contenu principal

engEvalString (C)

R2026b

Evaluate expression in string

C Syntax

#include "engine.h"
int engEvalString(Engine *ep, const char *string);

Description

engEvalString evaluates the expression contained in string for the MATLAB® engine session, ep, previously started by engOpen.

UNIX Operating System

On a UNIX® system, engEvalString sends commands to the MATLAB workspace by writing down a pipe connected to the MATLAB stdin process. MATLAB reads back from stdout any output resulting from the command that ordinarily appears on the screen, into the buffer defined by engOutputBuffer.

To turn off output buffering in C, use:

engOutputBuffer(ep, NULL, 0);

Microsoft Windows Operating System

On a Windows® system, engEvalString communicates with MATLAB using a Component Object Model (COM) interface.

Note

The matlab::engine::MATLABEngine.eval function in the MATLAB Engine API for C++ is recommended over engEvalString. 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 engEvalString or the Engine API for C.

Input Arguments

expand all

Pointer to engine, specified as Engine *.

Expression to evaluate, specified as const char *.

Output Arguments

expand all

Status, returned as int. The function returns 1 if the engine session is no longer running or the engine pointer is invalid or NULL. Otherwise, returns 0 even if the MATLAB engine session cannot evaluate the command.

Examples

Evaluate MATLAB Function in C Engine Application on Windows

This C code shows how to pass MATLAB commands to plot data on a Windows system.

/*
 *	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
 */

Evaluate MATLAB Function in C Engine Application on Linux or macOS

This C code shows how to pass MATLAB commands to plot data on a Linux® or macOS system.

/*
 *	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