engGetFull, engPutFull

Purpose

Easier way to get and put full Matrices into an engine.

C Synopsis

#include "engine.h"
int engGetFull(ep,name,m,n,pr,pi)
  Engine *ep;
  char *name;
  int *m, *n;
  double **pr, **pi;
int engPutFull(ep,name,m,n,pr,pi)
  Engine *ep;
  char *name;
  int m, n;
  double *pr;
  double *pi;

Fortran Synopsis

integer*4 function engGetFull(ep,name,m,n,pr,pi)
integer*4 function engPutFull(ep,name,m,n,pr,pi)
integer*4 ep, m, n, pr, pi
character*(*) name

Arguments

ep
engine pointer
name
name of Matrix to get or put into engine's workspace
m
row dimension
n
column dimension
pr
pointer to real part
pi
pointer to imaginary part

Description

Most MATLAB applications work only with full (nonsparse) Matrices. These routines provide an easy way to write a full Matrix into a MATLAB engine process and to copy a full Matrix out. They offer an alternative to engGetMatrix and engPutMatrix, which do not require use of the Matrix structure.

engGetFull reads the named Matrix from the engine pointed to by ep and places the row dimensions, column dimensions, real array pointer, and imaginary array pointer into the locations specified by m, n, pr, and pi, respectively.

engGetFull returns 0 if successful, and 1 otherwise.

engGetFull allocates memory for the real and imaginary arrays using mxCalloc; use mxFree to return it when you are done.

If the Matrix is purely real, the imaginary pointer is given NULL.

engPutFull writes the Matrix with dimensions m-by-n, real data pr, and imaginary data pi into the workspace of engine ep with the specified name.

If the Matrix does not exist in the engine's workspace, it is created. If a Matrix with the same name already exists in the workspace, the existing Matrix is replaced with the new Matrix.

Examples

Send a simple Matrix to the engine, compute its eigenvalues, get back the vector containing the eigenvalues, and print the second one:

For UNIX and VMS systems:

/* engtest3.c */ 
#include <stdio.h>
#include "engine.h"
static double Areal[6] = {1,2,3,4,5,6};
main()
{
  Engine *ep;
  int m, n;
  double *Dreal, *Dimag;
  if (!(ep = engOpen("\0"))) {
   fprintf(stderr,"\nCan't start MATLAB engine");
   exit(-1);
  }
  engPutFull(ep,"A",3,2,Areal,NULL);
  engEvalString(ep,"d = eig(A*A')");
  engGetFull(ep,"d",&m,&n,&Dreal,&Dimag)
  engClose(ep);
  if (Dimag) {
   printf("Eigenval 2: %g+%gi",Dreal[1],Dimag[1]);
   mxFree(Dimag);
  } else {
   printf("Eigenval 2: %g\n",Dreal[1]);
  }
  mxFree(Dreal);
}
The Fortran version is in engtest3.f.

For MS-Windows on a PC:

/*ENGTEST3*/
#include <stdlib.h>
#include <stdio.h>
#include "engine.h"
static double Areal[6] = { 1, 2, 3, 4, 5, 6 };
int WINAPI WinMain (HANDLE hInstance,
                                         HANDLE hPrevInstance,
                                        LPSTR  lpszCmdLine,
                                        int    nCmdShow)
{
        Engine *ep;
        FOUR_BYTE_INT m, n;
        double *Dreal, *Dimag;
        char        buff[256];
        engWinInit (hInstance);
        if (!(ep = engOpen(lpszCmdLine))) {
                MessageBox ((HWND)NULL, 
                (LPSTR)"Can't start MATLAB engine", 
                        (LPSTR) "Engtest3.c", MB_OK);
        }
        else {
                engPutFull(ep, "A", 3, 2, Areal, NULL);
                engEvalString(ep, "d = eig(A*A')");
                engGetFull(ep, "d", &m, &n, &Dreal, &Dimag);
                engClose(ep);
                
                if (Dimag)
                        sprintf(buff,"Eigenval 2: %g+%gi\n",
                        Dreal[1],Dimag[1]);
                else
                        sprintf(buff,"Eigenval 2: %g\n",Dreal[1]);
                MessageBox ((HWND)NULL, (LPSTR)buff, 
                (LPSTR)"Engtest3.c", MB_OK);
                
                mxFree(Dreal);
                if (Dimag)
                        mxFree(Dimag);
        }
        return TRUE;
}

(c) Copyright 1994 by The MathWorks, Inc.