# matGetFull, matPutFull

## Purpose

Easiest way to get and put full Matrices into MAT-files.

## C Synopsis

    #include "matfile.h"
    int matGetFull(fp,name,m,n,pr,pi)
      MATFile *fp;
      char *name;
      int *m;
      int *n;
      double **pr;
      double **pi;
    int matPutFull(fp,name,m,n,pr,pi)
      MATFile *fp;
      char *name;
      int m;
      int n;
      double *pr;
      double *pi;

## Fortran Synopsis

    integer*4 function matGetFull(fp,name,m,n,pr,pi)
    integer*4 function matPutFull(fp,name,m,n,pr,pi)
    integer*4 fp,m,n,pr,pi
    character*(*) name

## Arguments

`fp`
  MAT-file handle
`m`
  row dimension
`n`
  column dimension
`name`
  name of Matrix to get or put to MAT-file
`pi`
  pointer to imaginary part
`pr`
  pointer to real part

## Description

Most MATLAB applications work only with full (non-sparse) Matrices. These routines provide an easy way to write a full Matrix into a MAT-file and to copy a full Matrix out of a MAT-file. They offer an alternative to `matGetMatrix` and `matPutMatrix`, which do not require use of the Matrix structure.

`matGetFull` reads the named Matrix from the MAT-file pointed to by `fp` 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.

`matGetFull` returns 0 if successful, and 1 if the named variable can't be found, the named variable is not a full Matrix, or there is a file read error.

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

If the Matrix is pure real, the imaginary pointer is `NULL`.

`matPutFull` writes the Matrix with dimensions `m`-by-`n`, real data `pr`, and imaginary data `pi` onto the MAT-file `fp` with the specified `name`.

If the Matrix does not exist on the MAT-file, it is appended to the end. If a Matrix with the same name already exists in the file, the existing Matrix is replaced with the new Matrix by rewriting the file.

## Examples

Read the Matrix `A` from one MAT-file and write it out to another:

    /* mattest4.c */
    #include "mat.h"
    main()
    {
      MATFile *fp1, *fp2;
      int m, n
      double *pr, *pi;
      fp1 = matOpen("foo.mat","r");
      fp2 = matOpen("foo2.mat","w");
      matGetFull(fp1,"A",&m,&n,&pr,&pi);
      matPutFull(fp2,"A",m,n,pr,pi);
      matClose(fp1);
      matClose(fp2);
    }

The Fortran code for this example is in `mattest4.f`:

      program main
      integer matOpen,matClose,matPutFull,matGetFull
      integer mf1, mf2, stat
      integer m, n, pr, pi
      mf1 = matOpen('foo.mat','r')
      mf2 = matOpen('foo2.mat','w')
      stat = matGetFull(mf1,'A',m,n,pr,pi)
      stat = matPutFull(mf2,'A',m,n,pr,pi)
      stat = matClose(mf1)
      stat = matClose(mf2)
    c
      stop
      end

Write a simple real Matrix into a MAT-file. Name the Matrix `A` and the MAT-file `foo.mat`:

    /* mattest5.c */
    #include "mat.h"
    static double Areal[6] = {1,2,3,4,5,6};
    main()
    {
      MATFile *fp;
      fp = matOpen("foo.mat","w");
      matPutFull(fp,"A",3,2,Areal,NULL);
      matClose(fp);
    }

To test, first run `mattest5`; then go to MATLAB and enter:

    load foo
    A
    A =
      1  4
      2  5
      3  6

The Fortran code for this example is in `mattest5.f`:

      integer matOpen, matClose, matPutFull
      integer fp, stat
      double precision Areal(6)
      data Areal / 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 /
    c
      fp = matOpen('foo.mat','w')
      stat = matPutFull(fp,'A',3,2,Areal,0)
      stat = matClose(fp)
    c
      stop
      end

(c) Copyright 1994 by The MathWorks, Inc.