# ``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.