ms_readmsr.3

C编写的格式转换程序

.TH MS_READMSR 3 2007/07/19 "Libmseed API"
.SH DESCRIPTION
Read Mini-SEED data from files

.SH SYNOPSIS
.nf
.B #include <libmseed.h>

.BI "int \fBms_readmsr\fP ( MSRecord **ppmsr, char *" msfile ", int " reclen ","
.BI "                 off_t *" fpos ", int *" last ", flag " skipnotdata ","
.BI "                 flag " dataflag ",flag " verbose " );"

.BI "int \fBms_readmsr_r\fP ( MSFileParam **ppmsfp, MSRecord **ppmsr, char *" msfile ","
.BI "                    int " reclen ", off_t *" fpos ", int *" last ","
.BI "                    flag " skipnotdata ", flag " dataflag ",flag " verbose " );"

.BI "int \fBms_readtraces\fP ( MSTraceGroup **ppmstg, char *" msfile ", int " reclen ", "
.BI "                    double " timetol ", double " sampratetol ","
.BI "                    flag " dataquality ", flag " skipnotdata ","
.BI "                    flag " dataflag ", flag " verbose " );"
.fi

.SH DESCRIPTION
Both \fBms_readmsr\fP and \fBms_readmsr_r\fP will open and read, with
subsequent calls, all Mini-SEED records from a specified file.
Standard input will be opened if \fImsfile\fP is "-" (dash).  As each
record is read it is unpacked using \fBmsr_unpack(3)\fP.  If the
MSRecord struct at \fI*ppmsr\fP has not been initialized it must be
set to NULL and it will be initialize it automatically.

The \fBms_readmsr\fP version is not thread safe.  The reentrant
\fBms_readmsr_r\fP version is thread safe and can be used to read more
than one file in parallel.  \fBms_readmsr_r\fP stores all static file
reading parameters in a MSFileParam struct.  A pointer to this struct
must be supplied by the caller (\fIppmsfp\fP), memory will be
allocated on the initial call if the pointer is NULL.

If \fIreclen\fP is 0 the length of the first record is automatically
detected, all subsequent records are then expected to have the same
length as the first.  If \fIreclen\fP is negative the length of every
record is automatically detected.  For record length auto detection
records are first searched for a Blockette 1000 and if none is found a
read-ahead method is used: a little more (48 bytes) of data is read
from the file and checked for a fixed section data header (the
existence of the next record or end-of-file implying the length of the
current record).  This read-ahead detection method is done for each
valid record length from 256 up to 8192 bytes in length.

If the \fIfpos\fP pointer is not NULL the value will be set to the
file position (offset from the beginning in bytes) from where the
returned record was read.

If the \fIlast\fP pointer is not NULL the value will be set to 1 when
the last record in the file is being returned, otherwise it will be 0.

If the \fIskipnotdata\fP flag is true (not 0) any data chunks read
that do not have valid data record indicators (i.e. D, R, or Q) will
be skipped.

The \fIdataflag\fP argument is passed directly to \fBmsr_unpack(3)\fP
and controls whether data samples are unpacked.

After reading all the input records the controlling program should
call it one last time with \fImsfile\fP set to NULL.  This will close
the file and cleanup allocated memory.

If \fBms_readmsr\fP or \fBms_readmsr_r\fP are called with a different
file than the one they currently has open they will close the
currently open file, open the new file and print an error message.
Properly coded applications should reset the function when the end of
file has been reached as described above and not rely on this
behavior.

\fBms_readtraces\fP simply reads all Mini-SEED records from a file
using \fBms_readmsr_r\fP and adds each one to a MSTraceGroup using
\fBmst_addmsrtogroup(3)\fP.  The \fImsfile\fP, \fIreclen\fP,
\fIskipnotdata\fP and \fIdataflag\fP arguments are passed directly to
\fBms_readmsr_r\fP.  The \fItimetol\fP, \fIsampratetol\fP and
\fIdataquality\fP arguments are passed directly to
\fBmst_addmsrtogroup(3)\fP.  If the MSTraceGroup struct at
\fI*ppmstg\fP has not been initialized it must be set to NULL and it
will be initialize it automatically.  The MSTraceGroup struct at
\fI*ppmstg\fP may already contain entries before \fBms_readtraces\fP
is called, in this case the MSTraceGroup is extended.
\fBms_readtraces\fP is thread safe.

.SH RETURN VALUES
On the sucessful read and parsing of a record \fBms_readmsr\fP and
\fBms_readmsr_r\fP return MS_NOERROR and populate the MSRecord struct
at \fI*ppmsr\fP.  Upon reaching the end of the input file these
routines return MS_ENDOFFILE.  On error these routines return a
libmseed error code (defined in libmseed.h)

On the sucessful read and parsing of a file \fBms_readtraces\fP
returns MS_NOERROR and populates the MSTraceGroup struct at
\fI*ppmstg\fP.  On error \fBms_readtraces\fP returns a libmseed error
code (defined in libmseed.h)

.SH PACKED FILES
\fBms_readmsr\fP and \fBms_readtraces\fP will read packed Mini-SEED
files, but only when the record length is being autodetected.  Packed
Mini-SEED is the indexed archive format used internally at the IRIS
Data Management Center and probably not used anywhere else.

.SH EXAMPLE
Skeleton code for reading a file with \fBms_readmsr(3)\fP:

.nf
main() {
  MSRecord *msr = NULL;
  int retcode;

  while ( (retcode = ms_readmsr (&msr, filename, 0, NULL, NULL, 1, 0, verbose)) == MS_NOERROR )
    {
       /* Do something with the record here, e.g. print */
       msr_print (msr, verbose);
    }

  if ( retcode != MS_ENDOFFILE )
    ms_log (2, "Error reading input file %s: %s\\n", filename, ms_errorstr(retcode));

  /* Cleanup memory and close file */
  ms_readmsr (&msr, NULL, 0, NULL, NULL, 0, 0, verbose);
}

For reading a file with the thread safe \fBms_readmsr_r(3)\fP:

.nf
main() {
  MSRecord *msr = NULL;
  MSFileParam *msfp = NULL;
  int retcode;

  while ( (retcode = ms_readmsr_r (&msfp, &msr, filename, 0, NULL, NULL, 1, 0, verbose)) == MS_NOERROR )
    {
       /* Do something with the record here, e.g. print */
       msr_print (msr, verbose);
    }

  if ( retcode != MS_ENDOFFILE )
    ms_log (2, "Error reading input file %s: %s\\n", filename, ms_errorstr(retcode));

  /* Cleanup memory and close file */
  ms_readmsr_r (&msfp, &msr, NULL, 0, NULL, NULL, 0, 0, verbose);
}

.fi
For reading a file with \fBms_readtraces(3)\fP:
.nf

main() {
  MSTraceGroup *mstg = NULL;
  int retcode;

  retcode = ms_readtraces (&mstg, filename, 0, -1.0, -1.0, 0, 1, 0, verbose);

  if ( retcode != MS_NOERROR )
    ms_log (2, "Error reading input file %s: %s\\n", filename, ms_errorstr(retcode));

  retcode = ms_readtraces (&mstg, filename2, 0, -1.0, -1.0, 0, 1, 0, verbose);

  if ( retcode != MS_NOERROR )
    ms_log (2, "Error reading input file %s: %s\\n", filename2, ms_errorstr(retcode));

  if ( ! mstg )
    {
      ms_log (2, "Error reading file\\n");
      return -1;
    }

  /* Do something with the traces here, e.g. print */
  mst_printtracelist (mstg, 0, verbose, 0);

  mst_freegroup (&mstg);
}
.fi

.SH SEE ALSO
\fBms_intro(3)\fP, \fBmsr_unpack(3)\fP, \fBmst_addmsrtogroup(3)\fP,
\fBms_log(3)\fP and \fBms_errorstr(3)\fP.

.SH AUTHOR
.nf
Chad Trabant
IRIS Data Management Center
.fi