# matGetMatrix, matPutMatrix

## Purpose

Get and put Matrices into MAT-files.

## C Synopsis

    #include "mat.h"
    Matrix *matGetMatrix(fp,name)
      MATFile *fp;
      char *name;
    int matPutMatrix(fp,mp)
      MATFile *fp;
      Matrix *mp;

## Fortran Synopsis

    integer*4 function matGetMatrix(fp,name)
    integer*4 function matPutMatrix(fp,mp)
    integer*4 mp, fp
    character*(*) name

## Arguments

`fp`
  MAT-file handle
`mp`
  Matrix pointer
`name`
  name of Matrix to get from MAT-file

## Description

These routines allow you to put a Matrix into a MAT-file and to copy a Matrix out of a MAT-file.

`matGetMatrix` reads the named Matrix from the MAT-file pointed to by `fp` and returns a pointer to a newly allocated Matrix structure, or `NULL` if the attempt fails.

`matPutMatrix` writes Matrix `mp` to the MAT-file `fp`. If the Matrix does not exist in 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. The size of the new Matrix can be different than the existing Matrix.

`matPutMatrix` returns 0 if successful and 1 if an error occurs. Use `feof` and `ferror` from the Standard C Library to determine status.

Be careful in your code to free the Matrix created by this routine when you are finished with it.

## Examples

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

    /* mattest1.c */
    #include <string.h>
    #include "mat.h"
    static double Areal[6] = {1,2,3,4,5,6};
    main()
    {
      MATFile *fp;
      Matrix *a;
      fp = matOpen("foo.mat","w");
      a = mxCreateFull(3,2,REAL);
      memcpy(mxGetPr(a),Areal,6*sizeof(double));
      mxSetName(a,"A");
      matPutMatrix(fp,a);
      matClose(fp);
      mxFreeMatrix(a);
    }

To test, run this program; then go to MATLAB and enter:

    load foo
    A
    A =
      1  4
      2  5
      3  6

The Fortran version of this code is in `mattest1.f`:

      program main
      integer matOpen, mxCreateFull, matClose
      integer mxGetPr, matPutMatrix
      integer a, 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')
      a = mxCreateFull(3, 2, 0)
      call mxCopyReal8ToPtr(Areal, mxGetPr(a), 6)
      call mxSetName(a,'A')
      stat = matPutMatrix(fp,a)
      stat = matClose(fp)
      call mxFreeMatrix(a)
    c
      stop
      end

(c) Copyright 1994 by The MathWorks, Inc.