.TH DBCOLLATE 1 "30 November 1994" "MIT DB software 9.3" "DB applications"
.SH NAME
dbcollate \- collate DB records into a multi-segment record
.SH SYNOPSIS
\fBdbcollate -i \fIirec\fR [ \fIirec\fR ... ] \fB-o \fIorec\fR [ \fB-a
\fIannotator\fR ]
.br
\fBdbcollate \fIorec first last\fR [ \fB-a \fIannotator\fR ]
.SH DESCRIPTION
A multi-segment record is the concatenation of one or more ordinary
records.  A multi-segment record is a ``virtual'' record, in the sense
that it has no signal files of its own.  Its header file contains a
list of the records that comprise the multi-segment record.  A
multi-segment record may have associated annotation files, but these
are independent of any annotation files that may exist for its
constituent segments.  It is permissible (though not particularly
useful) to create a multi-segment record with only one segment; it is
not permissible to use a multi-segment record as a segment within a
multi-segment record, however.
.PP
\fIdbcollate\fR simply constructs an array of segment names, passing
it to the DB library function \fIsetmsheader\fR (see \fIdb\fR(3)) to create a
multi-segment header file.  In the first form of the command,
\fIorec\fR is the name of the multi-segment (output) record to be
created, and the \fIirec\fR arguments are the names of the
(single-segment) input records that are to be included in the output
record.  At least one input record name must be specified.
.PP
In the second form of the command, \fIorec\fR is again the name of the
multi-segment (output) record to be created, and \fIfirst\fR and
\fIlast\fR are numbers between 1 and 99999.  In this case, \fIorec\fR
must be 3 characters or fewer (longer names are truncated), and the
names of the input records are derived by appending \fIfirst\fR,
\fIfirst\fR+1, ..., \fIlast\fR to \fIorec\fR (representing
\fIfirst\fR, ..., as 5-digit zero-padded decimal numbers).  Thus the
command
.br
     \fBdbcollate xyz 9 12\fR
.br
is equivalent to
.br
     \fBdbcollate -o xyz -i xyz00009 xyz00010 xyz00011 xyz00012\fR
.PP
Each segment must contain the same number of signals, and the sampling
frequency must be the same for each segment.  Each input record header
must specify its record length (use \fIdbdesc\fR(1) to determine the
input record length if necessary, then edit the input record header to
include this information before using \fIdbcollate\fR). In most cases
you will want to be sure that corresponding signals match in each
segment, and that the gains, ADC zero levels, and numbers of samples
per frame (see \fIheader\fR(5)) also match.  It is not necessary that
the signal file formats match, however.
.PP
In both forms, \fB-a \fIannotator\fR is optional; if included, it
specifies the annotator name of annotation files associated with the
input records, files to be concatenated to form a similarly-named
annotation file for \fIorec\fR.  Note that all of the files to be
concatenated must have the same annotator name.  It is not necessary
that this annotator exist for each input record, however.
.PP
In most cases, multi-segment records are indistinguishable from
single-segment records, from the point of view of applications built
using the DB library (version 9.1 or later).  Use \fIxform\fR(1) to
generate a single-segment record from a multi-segment record if
necessary (for example, to make it readable by an application built
using an earlier version of the DB library).  Note, however, that
older applications can generally be updated without source changes
simply by recompiling them and linking them with the current DB
library.
.PP
The shell variable \fBDB\fR should be set and exported (see \fIsetdb\fR(1)).
.SH FILES
.TP 22
header.\fIorec\fR
output header file (\fIorec\fR.hea under MS-DOS)
.TP
header.\fIirec\fR or \fIirec\fR.hea
input header file(s)
.SH BUGS
Under MS-DOS, this program is known as \fIdbcoll8\fR.
.SH SEE ALSO
dbdesc(1), xform(1), db(3), header(5)
.SH AVAILABILITY
.PP
This program is included in the DB Software Package, version 9.0 and later.