# engOpen

## Purpose

Start a MATLAB engine.

## C Synopsis

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

## Fortran Synopsis

    integer*4 function engOpen(startcmd)
    integer*4 ep
    character*(*) startcmd

## Arguments

`ep`
  engine pointer
`startcmd`
  string to start MATLAB process

## Description

This routine allows you to start a MATLAB process for the purpose of

using MATLAB as a compute 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 the UNIX system, 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.

`engOpen` performs the following steps:

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

On the VMS system, if `startcmd` is `NULL` or the empty string, `engOpen` starts MATLAB using the command `MATLAB`.

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

`engOpen` performs the following steps:

  1. Creates two mailboxes.
  2. Spawns a new process using these mailboxes as input and output.
  3. Executes a command in the process to run MATLAB.

Under MS-Windows on a PC, `engOpen` opens a DDE channel to MATLAB.

## Examples

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

    /* engtest2.c */
    #include <stdio.h>
    #include "engine.h"
    main()
    {
      Engine ep;
      if (!(ep = engOpen("\0"))) {
       fprintf(stderr,"\nCan't start MATLAB engine");
       exit(-1);
      }

    }

The Fortran version of this example is in `engtest2.f`.

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'\"");

Start a MATLAB engine in MS-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;
            engWinInit (hInstance);
            if (!(ep = engOpen(lpszCmdLine))) {
                    MessageBox ((HWND)NULL, (LPSTR)"Can't start MATLAB
    engine",
                            (LPSTR) "Engtest2.c", MB_OK);
            }
            engClose(ep);
            return TRUE;
    }

(c) Copyright 1994 by The MathWorks, Inc.