This is wpg, produced by makeinfo version 4.0b from wpg.tex.

INFO-DIR-SECTION Libraries
START-INFO-DIR-ENTRY
* WFDB library: (wpg).		The Waveform Database library.
END-INFO-DIR-ENTRY


File: wpg,  Node: timstr and strtim,  Next: datstr and strdat,  Prev: annstr and strann,  Up: conversion

   The next three functions convert between "standard time format"
strings and times in units of sample intervals.  Normally they should be
invoked after `isigopen', `wfdbinit', or `sampfreq', any of which will
determine the duration of a sample interval and the base time from a
header file, or after defining these quantities using `setsampfreq' and
`setbasetime'.  If this is not done, or if these time-conversion
functions are used after `wfdbquit', they will perform conversions in
units of seconds (i.e., the sample interval is taken to be one second
in such cases).

[ms]timstr
----------

     char *timstr(WFDB_Time T)
     char *mstimstr(WFDB_Time T)

*Return:*
(char *)
     pointer to a string that represents the time

These functions convert times or time intervals into null-terminated
ASCII strings.  If the argument, T, is greater than zero, it is treated
as a time interval, and converted directly into HH:MM:SS format by
`timstr', or to HH:MM:SS.SSS format by `mstimstr', with leading zero
digits and colons suppressed.  If T is zero or negative, it is taken to
represent negated elapsed time from the beginning of the record, and it
is converted to a time of day using the base time for the record as
indicated by the `hea' file or the caller (*note setbasetime::); in
this case, if the base time is defined, the string will contain all
digits even if there are leading zeroes, it will include the date if a
base date is defined, and it will be marked as a time of day by being
bracketed (e.g., `[08:45:00 23/04/1989]').  The result of the
conversion is truncated to a multiple of a second by `timstr', or to a
multiple of a millisecond by `mstimstr'.  Note in each case that the
returned pointer addresses static data (shared by `timstr' and
`mstimstr'), the contents of which are overwritten by subsequent calls.
*Note Example 3::, for an illustration of the use of `mstimstr'; also
*note Example 5::, for an example of the use of `timstr'.

strtim
------

     WFDB_Time strtim(char *STRING)

*Return:*
(WFDB_Time) >0
     number of sample intervals corresponding to the argument
     interpreted as a time interval

(WFDB_Time) <0
     (negated) elapsed time in sample intervals from the beginning of
     the record, corresponding to the argument interpreted as a time of
     day

(WFDB_Time)  0
     a legal return if the argument matches the base time;  otherwise
     an error return indicating an incorrectly formatted argument

This function converts an ASCII string in "standard time format" to a
time in units of sample intervals.  Examples of standard time format:
`2:14.875'
     2 minutes + 14.875 seconds

`[13:6:0]'
     13:06 (1:06 PM)

`[8:0:0 1]'
     8 AM on the day following the base date

`[12:0:0 1/3/1992]'
     noon on 1 March 1992

`143'
     143 seconds (2 minutes + 23 seconds)

`4:02:01'
     4 hours + 2 minutes + 1 second

`s12345'
     12345 sample intervals

`c350.5'
     counter value 350.5

`e'
     time of the end of the record (if defined)

`i'
     time of the next sample in input signal 0

`o'
     (the letter `o') time of the next sample in output signal 0

   If the argument is bracketed (as in the second, third, and fourth
examples), it is taken as a time of day, and `strtim' uses the base
time defined by the header file or by the caller (*note setbasetime::);
in this case, the value returned is zero or negative (and can be
converted into elapsed time from the beginning of the record by simply
negating it).  If the argument is not bracketed, it is taken as a time
interval, and converted directly into a positive number of sample
intervals.  These notations match those used by `timstr' and
`mstimstr', which are (approximately) inverse functions of `strtim'; in
fact, for MIT DB and AHA DB records (and any others with sampling
frequencies below 1 KHz), `strtim(mstimstr(T))' = T, for any T.  The
`s'-format (as in the seventh example above) is provided to allow
"conversion" of time intervals already expressed in sample intervals.
The similar `c'-format converts counter values (*note counter
conversion::) into sample intervals.  The length of the record in
sample intervals can be obtained using `strtim("e")', which evaluates
to zero if this quantity is undefined.  The sample number of the next
sample to be read or written can be determined using `strtim("i")' or
`strtim("o")'.  If the argument string is incorrectly formatted,
`strtim' returns zero (indistinguishable from a correct input that
evokes a zero output); this may be considered a feature.  Several of
the programs in chapter 6 illustrate the use of `strtim' (for example,
*note Example 7::).


File: wpg,  Node: datstr and strdat,  Next: aduphys and physadu,  Prev: timstr and strtim,  Up: conversion

   The next two functions convert between Julian dates and ASCII
strings.  Julian dates as defined by astronomers begin at noon GMT;
these begin at midnight local time.

datstr
------

     char *datstr(WFDB_Date DATE)

*Return:*
(char *)
     pointer to a string that represents the date

This function converts the Julian date represented by DATE into an
ASCII string in the form DD/MM/YYYY.

strdat
------

     WFDB_Date strdat(char *STRING)

*Return:*
(WFDB_Date)
     Julian date corresponding to the argument

This function converts STRING into a Julian date.  The argument should
be in the format used by `datstr'; if STRING is improperly formatted,
`strdat' returns zero.  Note that dates such as `15/3/89' refer to the
first century A.D., not the twentieth.  For example, the interval in
days between the events commemorated by the French and American
national holidays is `strdat("14/7/1789")' - `strdat("4/7/1776")'.




File: wpg,  Node: aduphys and physadu,  Prev: datstr and strdat,  Up: conversion

   The next four functions convert between analog-to-digital converter
(ADC) units and physical units, using as a conversion factor the gain
for the specified input signal.  The first two (`aduphys' and
`physadu') are general-purpose functions that convert absolute levels
(i.e., they account for non-zero `baseline' values); the last two
(`adumuv' and `muvadu') are for use with millivolt-dimensioned signals
only, and convert potential differences (i.e., `adumuv(S, 0)' =
`muvadu(S, 0)' = 0 for all S, irrespective of the `baseline' values
specified in the header file).  Normally, these functions should be
invoked after `isigopen' or `wfdbinit', either of which will determine
the gain from the `hea' file.  If this is not done, or if the header
file indicates that the gain is uncalibrated, or if the specified input
signal is not currently open, a gain of `WFDB_DEFGAIN' (defined in
`<wfdb/wfdb.h>') ADC units per millivolt, and a baseline of zero, are
assumed.  If the physical units (*note WFDB_Siginfo structures::) are
not millivolts, `adumuv' and `muvadu' convert to and from thousandths
of the defined physical units.  Note that `adumuv' and `muvadu' deal
exclusively with integers, but `aduphys' returns and `physadu' accepts
double-precision floating point physical values.

aduphys
-------

     double aduphys(WFDB_Signal S, WFDB_Sample A)

*Return:*
(double)
     physical value corresponding to a sample value of A ADC units

This function converts the sample value A from ADC units to physical
units, based on the `gain' and `baseline' for input signal S.
(`aduphys' was first introduced in WFDB library version 6.0.)

physadu
-------

     WFDB_Sample physadu(WFDB_Signal S, double V)

*Return:*
(WFDB_Sample)
     sample value, in ADC units, corresponding to V, in physical units

This function converts the value V from physical units to ADC units,
based on the `gain' and `baseline' for input signal S.  (`physadu' was
first introduced in WFDB library version 6.0.)

adumuv
------

     int adumuv(WFDB_Signal S, WFDB_Sample A)

*Return:*
(int)
     number of microvolts corresponding to A ADC units

This function converts the potential difference A from ADC units to
microvolts, based on the `gain' for input signal S.

muvadu
------

     WFDB_Sample muvadu(WFDB_Signal S, int V)

*Return:*
(int)
     number of ADC units corresponding to V microvolts

This function converts the potential difference V from microvolts to
ADC units, based on the `gain' for input signal S.


File: wpg,  Node: calibration,  Next: miscellaneous functions,  Prev: conversion,  Up: Functions

Calibration Functions
=====================

   Functions in this section are used to determine specifications for
calibration pulses and customary scales for plotting signals.  All of
them make use of the "calibration list", which is maintained in memory
and which contains entries for various types of signals.

* Menu:

* calopen::			read a calibration file into list
* getcal::			retrieve calibration data from list
* putcal::			append calibration data to list
* newcal::			write calibration list to a file
* flushcal::			discard contents of calibration list


File: wpg,  Node: calopen,  Next: getcal,  Prev: calibration,  Up: calibration

calopen
-------

     int calopen(char *FILE)

*Return:*
 0
     Success

-1
     Failure: insufficient memory for calibration list

-2
     Failure: unable to open calibration file

This function reads the specified calibration FILE (which must be
located in one of the directories specified by `WFDB', *note WFDB
path::) into the calibration list.  If FILE is `NULL', the file named
by `WFDBCAL' is read.  Normally, the current contents of the
calibration list are discarded before reading the calibration file; if
FILE begins with `+', however, the `+' is stripped from the file name
and the contents of the file are appended to the current calibration
list.  If FILE is `-', `calopen' reads the standard input rather than a
calibration file.  (This function was first introduced in WFDB library
version 6.0.)


File: wpg,  Node: getcal,  Next: putcal,  Prev: calopen,  Up: calibration

getcal
------

     int getcal(char *DESC, char *UNITS, WFDB_Calinfo *CAL)

*Return:*
 0
     Success;  `*CAL' contains the requested data

-1
     Failure: no match found

This function attempts to find calibration data for signals of type
DESC, having physical units as given by UNITS.  If successful, it fills
in the contents of the `WFDB_Calinfo' structure (*note WFDB_Calinfo
structures::) pointed to by CAL.  The caller must allocate storage for
the `WFDB_Calinfo' structure, and must not modify the contents of the
strings addressed by the `sigtype' and `units' fields of the
`WFDB_Calinfo' structure after `getcal' returns.  `getcal' returns data
from the first entry in the calibration list that contains a `sigtype'
field that is either an exact match or a prefix of DESC, and a `units'
field that is an exact match of UNITS; if either DESC or UNITS is
`NULL', however, it is ignored for the purpose of finding a match.
`getcal' cannot succeed unless the calibration list has been
initialized by a previous invocation of `calopen' or `putcal'.  (This
function was first introduced in WFDB library version 6.0.)


File: wpg,  Node: putcal,  Next: newcal,  Prev: getcal,  Up: calibration

putcal
------

     int putcal(WFDB_Calinfo *CAL)

*Return:*
 0
     Success

-1
     Failure: insufficient memory

This function adds the `WFDB_Calinfo' structure pointed to by CAL to
the end of the calibration list.  (This function was first introduced
in WFDB library version 6.0.)


File: wpg,  Node: newcal,  Next: flushcal,  Prev: putcal,  Up: calibration

newcal
------

     int newcal(char *FILE)

*Return:*
 0
     Success

-1
     Failure: unable to open FILE

This function creates a new calibration FILE (in the current directory)
containing the contents of the calibration list (which is not
modified).  FILE must satisfy the standard conditions for a WFDB file
name, i.e., it may contain letters, digits, or underscores.  (This
function was first introduced in WFDB library version 6.0.)


File: wpg,  Node: flushcal,  Prev: newcal,  Up: calibration

flushcal
--------

     void flushcal()

This function discards the current calibration list and returns the
memory that it occupied to the heap.  Note that `wfdbquit' does _not_
perform the function of `flushcal'.  (This function was first
introduced in WFDB library version 6.0.)


File: wpg,  Node: miscellaneous functions,  Prev: calibration,  Up: Functions

Miscellaneous WFDB Functions
============================

* Menu:

* newheader::			Creating a `hea' file for a new WFDB
				record.
* setheader::			Creating or changing a `hea' file.
* setmsheader::                 Creating a `hea' for a multi-segment
                                record.
* wfdbquit::			Closing WFDB files.
* iannclose and oannclose::     Closing annotation files.
* wfdbquiet and wfdbverbose::	Suppressing error messages from the WFDB library.
* wfdberror::			Retrieving error messages from the WFDB library.
* sampfreq::			Reading the sampling frequency of a WFDB record.
* setsampfreq::			Setting the sampling frequency.
* setbasetime::			Setting the base time.
* counter conversion::		Functions for reading and setting counter
				conversion parameters.
* setwfdb::			Dynamically changing the database path.
* getwfdb::			Reading the database path.
* wfdbfile::			Obtaining the pathname of a WFDB file.
* wfdbflush::			Flushing buffered output annotations and
				samples.
* getinfo::			Reading info strings from a `hea' file.
* putinfo::			Writing info strings into a `hea' file.
* setibsize::			Setting the default input buffer size.
* setobsize::			Setting the default output buffer size.
* wfdbgetskew::                 Reading intersignal skew.
* wfdbsetskew::                 Recording intersignal skew.
* wfdbgetstart::                Reading the prolog size in a signal file.
* wfdbsetstart::                Recording the prolog size in a signal file.


File: wpg,  Node: newheader,  Next: setheader,  Prev: miscellaneous functions,  Up: miscellaneous functions

newheader
---------

     int newheader(char *RECORD)

*Return:*
 0
     Success

-1
     Failure: unable to create header file

This function creates a `hea' file (in the current directory, unless
RECORD includes path information).  Use `newheader' just after you have
finished writing the signal files, but before calling `wfdbquit'.  If
RECORD begins with `+', the `+' is discarded and the remainder of
RECORD is taken as the record name.  Otherwise, all of RECORD
(excluding any path information) is taken to be the record name.  If
the record name is `-', the header file is written to the standard
output.  Record names may include letters in lower or upper case,
digits, and underscores (`_'); they may not include any other
characters.  If RECORD does not conform to these requirements,
`newheader' will return -1; *note Example 8::, for an illustration of
the use of `newheader' to check the validity of a record name.  For
compatibility with the widest range of operating systems, keep record
names short (6 characters or less) and avoid those that are
distinguished by case alone.  To avoid confusion with MIT DB and AHA DB
records, do not use three- or four-digit record names.


File: wpg,  Node: setheader,  Next: setmsheader,  Prev: newheader,  Up: miscellaneous functions

setheader
---------

     int setheader(char *RECORD, WFDB_Siginfo *SIARRAY, unsigned int NSIG)

*Return:*
 0
     Success

-1
     Failure: unable to create header file

This function creates or recreates a header file (in the current
directory) for the specified RECORD, based on the contents of the first
NSIG members of SIARRAY.  The preferred way to create a header file for
a new record is using `newheader', which records signal checksum and
length variables maintained by `putvec'.  The intended use of
`setheader' is for editing header files, e.g., to change recorded
signal gains from a calibration program, or to add signal descriptions
or "info" strings.  In the following code fragment, the header file for
record `old' is used to create a header file for record `new':

     ...
     int nsig, status;
     WFDB_Siginfo *s;
     
     nsig = isigopen("old", NULL, 0);
     s = (WFDB_Siginfo *)malloc(nsig * sizeof(WFDB_Siginfo));
     nsig = isigopen("old", s, -nsig);
     if (nsig > 0) {
         s[0].gain = 100.0;
         status = setheader("new", s, (unsigned int)nsig);
     }
     ...

The header file for record `new' will contain the same signal
information as that for record `old', except that the `gain' for signal
0 will have been changed as shown.  Any "info" strings in the `hea'
file for record `old' must be copied explicitly; *note getinfo::, and
*note putinfo::.  (This function was first introduced in WFDB library
version 5.0.)


File: wpg,  Node: setmsheader,  Next: wfdbquit,  Prev: setheader,  Up: miscellaneous functions

setmsheader
-----------

     int setmsheader(char *RECORD, char *SNARRAY[], unsigned int NSEGMENTS)

*Return:*
 0
     Success

-1
     Failure: illegal record name, or no segments specified, or header
     not writable

-2
     Failure: segment name too long, or insufficient memory

-3
     Failure: attempt to nest multi-segment records, or unreadable
     segment header

-4
     Failure: segment length unspecified, or numbers of signals or
     sampling frequencies don't match between segments

This function creates a header file (in the current directory) for a
multi-segment RECORD (*note Multi-Segment Records::.  SNARRAY contains
the names of the segments, each of which must be an existing
(single-segment) record; NSEGMENTS specifies the number of segments in
SNARRAY.  Once a header has been created by `setmsheader', any WFDB
application can read the concatenated signal files of the constituent
segment simply by opening the multi-segment record (using `isigopen' or
`wfdbinit').  Note that the signal files themselves are not modified in
any way, nor are they copied; rather, the other WFDB library functions
that read signals (`getvec', `getframe', `isigsettime', and
`isgsettime') automatically switch among the signal files of the
segments as required.  For an example of the use of `setmsheader', see
`app/wfdbcollate.c' in the WFDB Software Package.  (This function was
first introduced in WFDB library version 9.1.)


File: wpg,  Node: wfdbquit,  Next: iannclose and oannclose,  Prev: setmsheader,  Up: miscellaneous functions

wfdbquit
--------

     void wfdbquit(void)

This function closes all open database files.  It also resets the
following:

   * the factors used for converting between samples, seconds, and
     counter values (reset to 1), the base time (reset to 0, i.e.,
     midnight), and the base counter value (reset to 0); (*note timstr
     and strtim::)

   * the parameters used for converting between adus and physical units
     (reset to `WFDB_DEFGAIN' adu/mV, a quantity defined in
     `<wfdb/wfdb.h>'); (*note aduphys and physadu::)

   * internal variables used to determine output signal specifications;
     *note newheader::.

   If any annotations have been written out-of-order (*note Annotation
Order::), this function attempts to run `sortann' (see the `WFDB
Applications Guide') as a subprocess to restore the annotations to
canonical order.  If this cannot be done, it prints a warning message
indicating that the annotations are not in order, and providing
instructions for putting them in order.

   Programs that do not write annotations or signals need not use
`wfdbquit'.


File: wpg,  Node: iannclose and oannclose,  Next: wfdbquiet and wfdbverbose,  Prev: wfdbquit,  Up: miscellaneous functions

iannclose
---------

     void iannclose(WFDB_Annotator AN)

This function closes the annotation file associated with input annotator
AN.  It was first introduced in WFDB library version 9.1.

oannclose
---------

     void oannclose(WFDB_Annotator AN)

This function closes the annotation file associated with output
annotator AN.  It was first introduced in WFDB library version 9.1.

   If any annotations have been written out-of-order (*note Annotation
Order::), this function attempts to run `sortann' (see the `WFDB
Applications Guide') as a subprocess to restore the annotations to
canonical order.  If this cannot be done, it prints a warning message
indicating that the annotations are not in order, and providing
instructions for putting them in order.


File: wpg,  Node: wfdbquiet and wfdbverbose,  Next: wfdberror,  Prev: iannclose and oannclose,  Up: miscellaneous functions

wfdbquiet
---------

     `void wfdbquiet(void)'

This function suppresses error reporting on the standard error output
from the WFDB library functions.

wfdbverbose
-----------

     `void wfdbverbose(void)'

This function can be used to restore normal error reporting after using
`wfdbquiet'.  (This function was first introduced in WFDB library
version 4.0.)


File: wpg,  Node: wfdberror,  Next: sampfreq,  Prev: wfdbquiet and wfdbverbose,  Up: miscellaneous functions

wfdberror
---------

     `char *wfdberror(void)'

*Return:*
(char *)
     pointer to error string

This function returns a pointer to a string containing the text of the
most recent WFDB library error message (or to a string containing the
WFDB library version number, if there have been no errors).  Function
`wfdberror' is primarily intended for use in applications for which the
standard error output is unavailable or inadequate, such as in X Window
System applications.  (Note that this function may be unnecessary for
MS-Windows applications, since the MS-Windows version of the WFDB
library generates a message box for error messages, unless `wfdbquiet'
has been used to silence them.)  This function was first introduced in
WFDB library version 4.5.  Versions earlier than 9.4 return an empty
string rather than the library version number if there have been no
errors.


File: wpg,  Node: sampfreq,  Next: setsampfreq,  Prev: wfdberror,  Up: miscellaneous functions

sampfreq
--------

     WFDB_Frequency sampfreq(char *RECORD)

*Return:*
(WFDB_Frequency)>0.
     Success: the returned value is the sampling frequency in Hz

(WFDB_Frequency)-1.
     Failure: unable to read header file

(WFDB_Frequency)-2.
     Failure: incorrect header file format

This function determines the sampling frequency (in Hz) for the record
specified by its argument.  If its argument is NULL, `sampfreq' returns
the currently defined sampling frequency, if any.  It also sets the
internal variables used by the time-conversion functions (*note timstr
and strtim::) for converting between sample intervals and seconds.
*Note Example 3::, for an illustration of the use of `sampfreq'.  Note
that the value returned by `sampfreq' for a multifrequency record
depends on the current `getvec' mode (*note setgvmode::).


File: wpg,  Node: setsampfreq,  Next: setbasetime,  Prev: sampfreq,  Up: miscellaneous functions

setsampfreq
-----------

     int setsampfreq(WFDB_Frequency FREQ)

*Return:*
 0
     Success

-1
     Failure:  illegal sampling frequency specified (FREQ must not be
     negative)

This function sets the sampling frequency used by the time-conversion
functions (*note timstr and strtim::).  Use `setsampfreq' before
creating a new `hea' file (*note newheader::).  *Note Example 8::, for
an illustration of the use of `setsampfreq'.


File: wpg,  Node: setbasetime,  Next: counter conversion,  Prev: setsampfreq,  Up: miscellaneous functions

setbasetime
-----------

     int setbasetime(char *STRING)

*Return:*
 0
     Success

-1
     Failure: incorrect string format

This function sets the base time used by the time-conversion functions
`timstr' and `strtim'.  Its argument is a null-terminated ASCII string
in HH:MM:SS format.  An optional base date in DD/MM/YYYY format can
follow the time in STRING; if present, the date should be separated
from the time by a space or tab character.  If STRING is empty or
`NULL', the current date and time are read from the system clock.  Use
`setbasetime' after defining the sampling frequency and before creating
a header file (*note newheader::).  *Note Example 8::, for an
illustration of the use of `setbasetime'.




File: wpg,  Node: counter conversion,  Next: setwfdb,  Prev: setbasetime,  Up: miscellaneous functions

   Database records are sometimes obtained from analog tapes for which a
tape counter is available.  Since many analog tape recorders lack
elapsed time indicators, it is often useful to identify events in the
analog tape using counter values.  A similar situation may arise if a
chart recording or other hard copy with numbered pages is to be compared
with a database record.  To simplify cross-referencing between the
analog tape or chart and the digital database record, the WFDB library
supports conversion of counter values (or page numbers) to time.  For
this to be possible, the counter must be linear (i.e., it must change
at the same rate throughout the tape; this is not true of those that
count the number of revolutions of the supply or take-up reel), and the
base counter value (the counter value or page number corresponding to
sample 0) and the counter frequency (the difference between counter
values separated by a one-second interval, or the reciprocal of the
number of seconds per page) must be defined.  The following four
functions, first introduced in WFDB library version 5.2, are used to
obtain or set the values of these parameters.

getcfreq
--------

     WFDB_Frequency getcfreq(void)

*Return:*
(WFDB_Frequency)
     the counter frequency in Hz

This function returns the currently-defined counter frequency.  The
counter frequency is set by the functions that read header files, or by
`setcfreq'.  If the counter frequency has not been defined explicitly,
`getcfreq' returns the sampling frequency.

setcfreq
--------

     void setcfreq(WFDB_Frequency FREQ)

This function sets the counter frequency.  Use `setcfreq' before
creating a `hea' file (*note newheader::).  The effect of `setcfreq' is
nullified by later invoking any of the functions that read header
files.  If FREQ is zero or negative, the counter frequency is treated
as equivalent to the sampling frequency.

getbasecount
------------

     double getbasecount(void)

*Return:*
(double)
     base counter value

This function returns the base counter value, which is set by the
functions that read header files, or by `setbasecount'.  If the base
counter value has not been set explicitly, `getbasecount' returns zero.

setbasecount
------------

     void setbasecount(double COUNT)

This function sets the base counter value.  Use `setbasecount' before
creating a header file (*note newheader::).  The effect of
`setbasecount' is nullified by later invoking any of the functions that
read `hea' files.


File: wpg,  Node: setwfdb,  Next: getwfdb,  Prev: counter conversion,  Up: miscellaneous functions

setwfdb
-------

     void setwfdb(char *STRING)

This function may be used to set or change the database path (*note
WFDB path::) within a running program.  The argument points to a
null-terminated string that specifies the desired database path (but see
the next paragraph for an exception).  The string contains a list of
locations where input files may be found.  These locations may be
absolute directory names (such as `/usr/local/database' under Unix, or
`d:/database' under MS-DOS), relative directory names (e.g.,
`../mydata'), or URL prefixes (e.g.,
`http://www.physionet.org/physiobank/database').  If NETFILES support
is unavailable, any URL prefixes in the string are ignored.  The
special form `.' refers to the current directory.  Entries in the list
may be separated by whitespace or by semicolons; under Unix, colons may
also be used as separators.  An empty component, indicated by an
initial or terminal separator, or by two consecutive separators, will be
understood to specify the current directory (which may also be indicated
by a component consisting of a single `.').  If the string is empty or
`NULL', the database path is limited to the current directory.

   If STRING begins with `@', the remaining characters of STRING are
taken as the name of a file from which the WFDB path is to be read.
This file may contain either the WFDB path, as described in the
previous paragraph, or another indirect WFDB path specification.
Indirect WFDB path specifications may be nested no more than ten levels
deep (an arbitrary limit imposed to avoid infinite recursion).
Evaluation of indirect WFDB paths is deferred until `getwfdb' is
invoked, either explicitly or by the WFDB library while attempting to
open an input file (e.g., using `annopen' or `isigopen').  (The
features described in this paragraph were first introduced in WFDB
library version 8.0.)

   The `setwfdb' function does not copy the string itself, which must
therefore be kept valid by the caller, nor does it modify the
environment variable `WFDB', which will be inherited by any processes
spawned from the caller.  For portability, as well as efficiency, it is
better to use `setwfdb' than to manipulate `WFDB' directly (via
`putenv', for example); furthermore, doing the latter is ineffective
(within the current process) once the first WFDB file has been opened.
*Note getwfdb::, for an example of the use of `setwfdb'.


File: wpg,  Node: getwfdb,  Next: wfdbfile,  Prev: setwfdb,  Up: miscellaneous functions

getwfdb
-------

     char *getwfdb(void)

*Return:*
(char *)
     pointer to the database path string

This function returns the current database path.  For example, this code
fragment

     ...
     char *oldp, *newp;
     
     oldp = getwfdb();
     if (newp = malloc(strlen("/usr/mydb;") + strlen(oldp) + 1)) {
         sprintf(newp, "/usr/mydb;%s", oldp);
         setwfdb(newp);
     }
     ...

adds the directory `/usr/mydb' to the beginning of the database path.
(The standard `/' directory separator can be used, even under MS-DOS; if
you elect to use the alternate `\', remember to quote it within a C
string as `\\'.)


File: wpg,  Node: wfdbfile,  Next: wfdbflush,  Prev: getwfdb,  Up: miscellaneous functions

wfdbfile
--------

     char *wfdbfile(char *TYPE, char *RECORD)

*Return:*
(char *)
     pointer to a filename, or `NULL'

This function attempts to locate an existing WFDB file by searching the
database path (*note WFDB path::).  Normally, the file is specified by
its TYPE (e.g., `hea', or an annotator name such as `atr') and by the
RECORD to which it belongs.  A file that does not include a record name
as part of its name can be found by `wfdbfile' if the name is passed in
the TYPE variable and RECORD is `NULL'.  The string returned by
`wfdbfile' includes the appropriate component of the database path;
since the database path may include empty or non-absolute components,
the string is not necessarily an absolute pathname.  If the WFDB
library has been compiled with NETFILES support, and the WFDB path
includes one or more URL prefixes, the string returned may be a URL
rather than a pathname.  If the file cannot be found, `wfdbfile'
returns `NULL'.  (This function was first introduced in WFDB library
version 4.3.)


File: wpg,  Node: wfdbflush,  Next: getinfo,  Prev: wfdbfile,  Up: miscellaneous functions

wfdbflush
---------

     void wfdbflush(void)

This function brings database output files up-to-date by forcing any
output annotations or samples that are buffered to be written to the
output files.


File: wpg,  Node: getinfo,  Next: putinfo,  Prev: wfdbflush,  Up: miscellaneous functions

getinfo
-------

     char *getinfo(char *RECORD)

*Return:*
(char *)
     pointer to an "info" string, or `NULL'

This function reads an "info" string from the `hea' file for the
specified RECORD.  Info strings are null-terminated and do not contain
newline characters.  The `hea' files of some records may contain no
info strings;  others may contain more than one info string.  To read
additional info strings after the first, use `getinfo(NULL)'.  For
example, the following code fragment may be used to read and print all
of the info for record `100s':

     ...
     char *info;
     
     if (info = getinfo("100s"))
         do {
             puts(info);
         } while (info = getinfo(NULL));
     ...

   (This function was first introduced in WFDB library version 4.0.)


File: wpg,  Node: putinfo,  Next: setibsize,  Prev: getinfo,  Up: miscellaneous functions

putinfo
-------

     int putinfo(char *S)

*Return:*
 0
     Success

-1
     Failure: header not initialized

This function writes S as an "info" string into the `hea' file that was
created by the most recent invocation of `newheader'.  The string
argument, S, must be null-terminated and should not contain newline
characters.  No more than 254 characters may be written in a single
invocation of `putinfo'.  Two or more info strings may be written to
the same header by successive invocations of `putinfo'.  Note that
`newheader' or `setheader' must be used before `putinfo'.  (This
function was first introduced in WFDB library version 4.0.)


File: wpg,  Node: setibsize,  Next: setobsize,  Prev: putinfo,  Up: miscellaneous functions

setibsize
---------

     int setibsize(int SIZE)

*Return:*
>0
     Success: the returned value is the new input buffer size in bytes

-1
     Failure: buffer size could not be changed

-2
     Failure: illegal value for SIZE

This function can be used to change the default size of the input
buffers allocated by `getvec'.  It cannot be used while input signals
are open (i.e., after invoking `isigopen' or `wfdbinit' and before
invoking `wfdbquit').  If SIZE is positive, the default input buffers
will be SIZE bytes;  if SIZE is zero, the system default buffer size
(`BUFSIZ') is used.  Note that the default buffer size has no effect on
reading signals for which an explicit buffer size is given in the
header file, i.e., those for which the `bsize' field of the
`WFDB_Siginfo' structure (*note WFDB_Siginfo structures::) is non-zero.
(This function was first introduced in WFDB library version 5.0.)


File: wpg,  Node: setobsize,  Next: wfdbgetskew,  Prev: setibsize,  Up: miscellaneous functions

setobsize
---------

     int setobsize(int SIZE)

*Return:*
>0
     Success: the returned value is the new output buffer size in bytes

-1
     Failure: buffer size could not be changed

-2
     Failure: illegal value for SIZE

This function can be used to change the default size of the output
buffers allocated by `putvec'.  It cannot be used while output signals
are open (i.e., after invoking `osigopen' or `osigfopen' and before
invoking `wfdbquit').  If SIZE is positive, the default output buffers
will be SIZE bytes; if SIZE is zero, the system default buffer size
(`BUFSIZ') is used.  Note that the default buffer size has no effect on
writing signals for which an explicit buffer size is given in the `hea'
file read by `osigopen', or in the `bsize' field of the `WFDB_Siginfo'
structure (*note WFDB_Siginfo structures::) passed to `osigfopen'.
(This function was first introduced in WFDB library version 5.0.)


File: wpg,  Node: wfdbgetskew,  Next: wfdbsetskew,  Prev: setobsize,  Up: miscellaneous functions

wfdbgetskew
-----------

     int wfdbgetskew(WFDB_Signal S)

*Return:*
(int)
     the skew (in frames) for input signal S

This function returns the "skew" (as recorded in the `hea' file, but in
frame intervals rather than in sample intervals) of the specified input
signal, or 0 if S is not a valid input signal number.  Since sample
vectors returned by `getvec' or `getframe' are already corrected for
skew, `wfdbgetskew' is useful primarily for programs that need to
rewrite existing `hea' files, where it is necessary to preserve the
previously recorded skews.  The following code fragment demonstrates
how this can be done:

     char *record;
     int nsig;
     WFDB_Signal s;
     static WFDB_Siginfo *si;
     
     ...
     
     if ((nsig = isigopen(record, NULL, 0)) < 1)
         exit(1);
     si = (WFDB_Siginfo *)malloc(nsig * sizeof(WFDB_Siginfo));
     if (si == NULL || isigopen(record, siarray, nsig)!= nsig)
         exit(1);
     for (s = 0; s < nsig; s++) {
         wfdbsetskew(s, wfdbgetskew(s));
         wfdbsetstart(s, wfdbgetstart(s));
     }
     setheader(record, siarray, (unsigned)nsig);

Note that this function does not _determine_ the skew between signals;
the problem of doing so is not possible to solve in the general case.
`wfdbgetskew' merely reports what has previously been determined by
other means and recorded in the header file for the input record.
(This function was first introduced in WFDB library version 9.4.)


File: wpg,  Node: wfdbsetskew,  Next: wfdbgetstart,  Prev: wfdbgetskew,  Up: miscellaneous functions

wfdbsetskew
-----------

     void wfdbsetskew(WFDB_Signal S, int SKEW)

This function sets the specified SKEW (in frames) to be recorded by
`newheader' or `setheader' for signal S.  For an example of the use of
`wfdbsetskew', *note wfdbgetskew::.  Note that `wfdbsetskew' has no
effect on the skew correction performed by `getframe' (or `getvec'),
which is determined solely by the skews that were recorded in the
header file at the time the input signals were opened.  (This function
was first introduced in WFDB library version 9.4.)


File: wpg,  Node: wfdbgetstart,  Next: wfdbsetstart,  Prev: wfdbsetskew,  Up: miscellaneous functions

wfdbgetstart
------------

     long wfdbgetstart(WFDB_Signal S)

*Return:*
(long)
     the length of the prolog of the file that contains input signal S

This function returns the number of bytes in the "prolog" of the signal
file that contains the specified input signal, as recorded in the
header file.  Note that `wfdbgetstart' does not _determine_ the length
of the prolog by inspection of the signal file; it merely reports what
has been determined by other means and recorded in the `hea' file.
Since the prolog is not readable using the WFDB library, and since
functions such as `isigopen' and `isigsettime' take the prolog into
account when calculating byte offsets for `getframe' and `getvec',
`wfdbgetstart' is useful primarily for programs that need to rewrite
existing `hea' files, where it is necessary to preserve the previously
recorded byte offsets.  For an example of how this can be done, *note
wfdbgetskew::.  (This function was first introduced in WFDB library
version 9.4.)


File: wpg,  Node: wfdbsetstart,  Prev: wfdbgetstart,  Up: miscellaneous functions

wfdbsetstart
------------

     void wfdbsetstart(WFDB_Signal S, long BYTES)

This function sets the specified prolog length (BYTES) to be recorded
by `newheader' or `setheader' for signal S.  For an example of the use
of `wfdbsetstart', *note wfdbgetskew::.  Note that `wfdbsetstart' has
no effect on the calculations of byte offsets within signal files as
performed by `isigsettime', which are determined solely by the contents
of the `hea' file at the time the signals were opened.  (This function
was first introduced in WFDB library version 9.4.)


File: wpg,  Node: Data Types,  Next: Annotation Codes,  Prev: Functions,  Up: Top

Data Types
**********

_Simple data types_ used by the WFDB library are defined in
`<wfdb/wfdb.h>'.  These include:

`WFDB_Sample'
     a signed integer type (at least 16 bits) used to represent sample
     values, in units of adus.

`WFDB_Time'
     a signed integer type (at least 32 bits) used to represent times
     and time intervals, in units of sample intervals.  Only the
     magnitude is significant;  the sign of a `WFDB_Time' variable
     indicates how it is to be printed by `timstr' or `mstimstr'.

`WFDB_Date'
     a signed integer type (at least 32 bits) used to represent Julian
     dates, in units of days.

`WFDB_Frequency'
     a floating point type used to represent sampling and counter
     frequencies, in units of Hz.

`WFDB_Gain'
     a floating point type used to represent signal gains, in units of
     adus per physical unit.

`WFDB_Group'
     an unsigned integer type used to represent signal group numbers.

`WFDB_Signal'
     an unsigned integer type used to represent signal numbers.

`WFDB_Annotator'
     an unsigned integer type used to represent annotator numbers.

_Composite data types_ used by the WFDB library are also defined in
`<wfdb/wfdb.h>'.  These types, described in detail in the following
sections, include:

`WFDB_Siginfo'
     an object containing the name and global attributes of a given
     signal.

`WFDB_Calinfo'
     an object containing calibration specifications for signals of a
     given type.

`WFDB_Anninfo'
     an object containing the name and attributes of a given annotator.

`WFDB_Annotation'
     an object describing one or more attributes of one or more signals
     at a given time.

* Menu:

* WFDB_Siginfo structures::		Signal names and attributes.
* WFDB_Calinfo structures::		Signal calibration specifications.
* WFDB_Anninfo structures::		Annotator names and file types.
* WFDB_Annotation structures::		Annotation contents.


File: wpg,  Node: WFDB_Siginfo structures,  Next: WFDB_Calinfo structures,  Prev: Data Types,  Up: Data Types

Signal Information Structures
=============================

   The SIARRAY argument for `isigopen', `osigopen', `wfdbinit', and
`osigfopen' is a pointer to an array of objects of type `WFDB_Siginfo'.
The first three of these functions fill in the `WFDB_Siginfo' objects
to which SIARRAY points, but the caller must supply initialized
`WFDB_Siginfo' objects to `osigfopen'.  Each object specifies the
attributes of a signal:

`char *fname'
     a pointer to a null-terminated string that names the file in which
     samples of the associated signal are stored.  Input signal files
     are found by prefixing `fname' with each of the components of the
     database path in turn (*note WFDB path::).  `fname' may include
     relative or absolute path specifications if necessary; the use of
     an absolute pathname, combined with an initial null component in
     `WFDB', reduces the time needed to find the signal file to a
     minimum.  If `fname' is `-', it refers to the standard input or
     output.

`char *desc'
     a pointer to a null-terminated string without embedded newlines
     (e.g., `ECG lead V1' or `trans-thoracic impedance').  The length of
     the `desc' string is restricted to a maximum of `WFDB_MAXDSL'
     (defined in `<wfdb/wfdb.h>') characters, not including the null.

`char *units'
     a pointer to a null-terminated string without embedded whitespace.
     The string specifies the physical units of the signal; if NULL,
     the units are assumed to be millivolts.  The length of the `units'
     string is restricted to a maximum of `WFDB_MAXUSL' (defined in
     `<wfdb/wfdb.h>') characters (not including the null).

`WFDB_Gain gain'
     the number of analog-to-digital converter units (adus) per
     physical unit (see previous item) relative to the original analog
     signal; for an ECG, this is roughly equal to the amplitude of a
     normal QRS complex.  If `gain' is zero, no amplitude calibration
     is available; in this case, a `gain' of `WFDB_DEFGAIN' (defined in
     `<wfdb/wfdb.h>') may be assumed.

`WFDB_Sample initval'
     the initial value of the associated signal (i.e., the value of
     sample number 0).

`WFDB_Group group'
     the signal group number.  All signals in a given group are stored
     in the same file.  If there are two or more signals in a group,
     the file is called a "multiplexed signal file".  Group numbers
     begin at 0; arrays of `WFDB_Siginfo' structures are always kept
     ordered with respect to the group number, so that signals
     belonging to the same group are described by consecutive entries
     in SIARRAY.

`int fmt'
     the signal storage format.  The most commonly-used formats are
     format 8 (8-bit first differences), format 16 (16-bit amplitudes),
     and format 212 (pairs of 12-bit amplitudes bit-packed into byte
     triplets).  See `<wfdb/wfdb.h>' for a complete list of supported
     formats.  All signals belonging to the same group must be stored
     in the same format.

`int spf'
     the number of samples per frame.  This is 1, for all except
     oversampled signals in multi-frequency records, for which `spf'
     may be any positive integer.  Note that non-integer values are not
     permitted (thus the frame rate must be chosen such that all
     sampling frequencies used in the record are integer multiples of
     the frame rate).

`int bsize'
     the block size, in bytes.  For signal files that reside on Unix
     character device special files (or their equivalents), the `bsize'
     field indicates how many bytes must be read or written at a time
     (*note Special Files::).  For ordinary disk files, `bsize' is zero.
     All signals belonging to a given group have the same `bsize'.

`int adcres'
     the ADC resolution in bits.  Typical ADCs have resolutions between
     8 and 16 bits inclusive.

`int adczero'
     the ADC output given an input that falls exactly at the center of
     the ADC range (normally 0 VDC).  Bipolar ADCs produce two's
     complement output; for these, `adczero' is usually zero.  For the
     MIT DB, however, an offset binary ADC was used, and `adczero' was
     1024.

`int baseline'
     the value of ADC output that would map to 0 physical units input.
     The value of `adczero' is not synonymous with that of `baseline'
     (the isoelectric or physical zero level of the signal);  the
     `baseline' is a characteristic of the _signal_, while `adczero' is
     a characteristic of the _digitizer_.  The value of `baseline' need
     not necessarily lie within the output range of the ADC;  for
     example, if the `units' are `degrees_Kelvin', and the ADC range is
     200-300 degrees Kelvin, `baseline' corresponds to absolute zero,
     and lies well outside the range of values actually produced by the
     ADC.

`long nsamp'
     the number of samples in the signal.  (Exception: in
     multi-frequency records, `nsamp' is the number of samples divided
     by `spf', see above, i.e., the number of frames.)  All signals in
     a given record must have the same `nsamp'.  If `nsamp' is zero,
     the number of samples is unspecified, and the `cksum' (see the
     next item) is not used; this is useful for specifying signals that
     are obtained from pipes, for which the length may not be known.

`int cksum'
     a 16-bit checksum of all samples.  This field is not usually
     accessed by application programs; `newheader' records checksums
     calculated by `putvec' when it creates a new `hea' file, and
     `getvec' compares checksums that it calculates against `cksum' at
     the end of the record, provided that the entire record was read
     through without skipping samples.

   The number of `WFDB_Siginfo' structures in SIARRAY is given by the
NSIG argument of the functions that open signal files.  Input and
output signal numbers are assigned beginning with 0 in the order in
which the signals are given in SIARRAY.  Note that input signal 0 and
output signal 0 are distinct.  Input signal numbers are supplied to
`aduphys', `physadu', `adumuv', and `muvadu' in their first arguments.
*Note Example 5::, for an illustration of how to read signal
specifications from `WFDB_Siginfo' structures.


File: wpg,  Node: WFDB_Calinfo structures,  Next: WFDB_Anninfo structures,  Prev: WFDB_Siginfo structures,  Up: Data Types

Calibration Information Structures
==================================

   The CAL argument for `getcal' and `putcal' is a pointer to an object
of type `WFDB_Calinfo'.  A `WFDB_Calinfo' object contains information
about signals of a specified type:

`char *sigtype'
     a pointer to a null-terminated string without embedded tabs or
     newlines.  This field describes the type(s) of signals to which
     the calibration specifications apply.  Usually, `sigtype' is an
     exact match to (or a prefix of) the `desc' field of the
     `WFDB_Siginfo' object that describes a matching signal.

`char *units'
     a pointer to a null-terminated string without embedded whitespace.
     This field specifies the physical units of signals to which the
     calibration specifications apply.  Usually, the `units' field of a
     `WFDB_Calinfo' structure must exactly match the `units' field of
     the `WFDB_Siginfo' structure that describes a matching signal.

`double scale'
     the customary plotting scale, in physical units per centimeter.
     WFDB applications that produce graphical output may use `scale' as
     a default.  Except in unusual circumstances, signals of different
     types should be plotted at equal multiples of their respective
     `scale's.

`double low'
`double high'
     values (in physical units) corresponding to the low and high
     levels of a calibration pulse.  If the signal is AC-coupled (see
     below), `low' is zero, and `high' is the pulse amplitude.

`int caltype'
     a small integer that specifies the shape of the calibration pulse
     (see `<wfdb/wfdb.h>' for definitions).  `caltype' is even if
     signals of the corresponding `sigtype' are AC-coupled, and odd if
     they are DC-coupled.

   The calibration list is a memory-resident linked list of
`WFDB_Calinfo' structures.  It is accessible only via `calopen',
`getcal', `putcal', `newcal', and `flushcal'.

