MATLAB Application Program Interface Reference

Start a MATLAB engine session

#include "engine.h"
Engine *engOpen(const char *startcmd);

Arguments

ep

Engine pointer.

startcmd

String to start MATLAB process.
Note: On Windows, this string must be NULL.

Description

This routine allows you to start a MATLAB process for the purpose of using MATLAB as a computational engine.

engOpen(startcmd) starts a MATLAB process using the command specified in the string startcmd, establishes a connection, and returns a unique engine identifier, or NULL if the open fails.

On UNIX systems, if startcmd is NULL or the empty string, engOpen starts MATLAB on the current host using the command matlab. If startcmd is a hostname, engOpen starts MATLAB on the designated host by embedding the specified hostname string into the larger string:

"rsh hostname \"/bin/csh -c 'setenv DISPLAY\
    hostname:0; matlab'\""

If startcmd is any other string (has white space in it, or nonalphanumeric characters), the string is executed literally to start MATLAB.

On UNIX systems, engOpen performs the following steps:

Creates two pipes.
Forks a new process and sets up the pipes to pass stdin and stdout from the child to two file descriptors in the parent.
Executes a command to run MATLAB (rsh for remote execution).

Under Windows on a PC, engOpen opens an ActiveX channel to MATLAB. This starts the MATLAB that was registered during installation. If you did not register during installation, on the command line you can enter the command:

matlab /regserver

See "ActiveX Automation for Windows" in the Application Program Interface Guide for additional details.

Examples

Start a MATLAB engine on the UNIX machine that you are currently logged into:

/* engtest2.c */ 
#include <stdio.h>
#include "engine.h"

void main()
{
    Engine ep;

    if (!(ep = engOpen("\0"))) {
     fprintf(stderr,"\nCan't start MATLAB engine");
     exit(-1);
    }
    
}

Call engOpen to start a process on the UNIX machine called labrea:

engOpen("labrea");

Call engOpen to run MATLAB on Fred's account on the UNIX machine called labrea, and set the X display to the machine called wilkinson:

engOpen("rsh -l fred labrea \"/bin/csh -c \
    'setenv DISPLAY wilkinson:0; matlab'\"");

See engdemo.c in the eng_mat subdirectory of the examples directory for a sample program that illustrates how to call the MATLAB engine functions from a C program on a UNIX machine.

Start a MATLAB engine in Windows on a PC:

/*ENGTEST2*/
#include <stdlib.h>
#include <stdio.h>
#include "engine.h"

int WINAPI WinMain   (HANDLE hInstance,
                HANDLE hPrevInstance,
                LPSTR lpszCmdLine,
                int nCmdShow)
{
    Engine *ep;

    if (!(ep = engOpen(NULL))) {
        MessageBox ((HWND)NULL, (LPSTR)"Can't start MATLAB 
engine", 
            (LPSTR) "Engtest2.c", MB_OK);
    }

    engClose(ep);
    return TRUE;
}

See engwindemo.c in the eng_mat subdirectory of the examples directory for a sample program that illustrates how to call the MATLAB engine functions from a C program in Windows.

[ Previous | Help Desk | Next ]