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