# matGetString, matPutString

## Purpose

Get and put string Matrices into MAT-files.

## C Synopsis

    #include "mat.h"
    int matGetString(fp,name,str,strlen)
      MATFile *fp;
      char *name;
      char *str;
      int strlen;
    int matPutString(fp,name,str)
      MATFile *fp;
      char *name;
      char *str;

## Fortran Synopsis

    integer*4 function matGetString(fp,name,str,strlen)
    integer*4 function matPutString(fp,name,str)
    integer*4 fp, strlen
    character*(*) name,str

## Arguments

`fp`
  MAT-file handle
`name`
  name of Matrix to get or put into MAT-file
`str`
  string to read or write to MAT-file
`strlen`
  length of the character array

## Description

`matGetString` reads the string Matrix with the specified `name` into `str` from the MAT-file `fp`. It returns zero if successful, and a nonzero value if an error occurs.

`matGetString` copies, converts, and terminates with a `NULL` character the string from Matrix `name` on file `fp` into the character array `str`. Storage space for `str` must be allocated previously.

Only up to `strlen` characters are copied, so ordinarily `strlen` is set to the dimension of the character array to prevent writing past the end of the array. If the string Matrix contains several rows, they are copied, one column at a time, into one long string array.

`matGetString` returns 0 if the copy is successful, and 1 if the copy has failed because the Matrix is not a string Matrix, 2 if the length of the string exceeds `strlen`, and 3 if there is a file read error.

`matPutString` writes the Matrix with the specified `name` and `str` to the MAT-file `fp`. It returns 0 if successful, and 1 if an error occurs.

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

If you execute the C code:

    /* mattest6.c */
    #include "mat.h"
    main()
    {
      MATFile *fp;
      fp = matOpen("foo.mat","w");
      matPutString(fp,"A","Hello, world");
      matClose(fp);
    }

Then you can go to MATLAB and enter:

    load foo
    A
    A =
      Hello, world

A Fortran version of this is in `mattest6.f`:

      program main
      integer matOpen, matClose, matPutString
      integer fp, stat
    c
      fp = matOpen('foo.mat', 'w')
      stat = matPutString(fp,'A','Hello, world')
      stat = matClose(fp)
    c
      stop
      end

(c) Copyright 1994 by The MathWorks, Inc.