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: Top,  Next: Overview,  Prev: (dir),  Up: (dir)

   This guide documents the Waveform Database interface library (the
WFDB library).  This file contains the text of the Tenth Edition of the
`WFDB Programmer's Guide' (26 November 2002), with revisions for
release 10.3.0 of the WFDB library.

* Menu:

* Overview::			What is the WFDB library?
* Recent changes::              New material, not included in the most
                                recent printed edition of this guide.
* Usage::			How to compile and run a program that uses
				the WFDB library.
* Functions::			Call and return syntax of each function, with
				descriptions and program examples.
* Data Types::		        Simple and compound types, including annotator,
				calibration, and signal information structures,
				and annotation structures.
* Annotation Codes::    	Table of codes, descriptions of mapping macros.
* Database Files::		A description of the standard file types, and
				notes about reading from nonstandard sources.
* Examples::			Annotated example programs.
* Exercises::			Test yourself.
* Glossary::			So you think you know what `time' is, eh?
				A guide for the perplexed.
* Installation::		Notes on installing the WFDB software package.
* WFDB Applications::		Brief descriptions of the WFDB application
				programs provided with the WFDB software package.
* Extensions::			Notes on extending the capabilities of the
				WFDB library.
* Sources::			Where to get the WFDB software package, databases
				of ECGs and other signals, and related items.
Indices

* Concept Index::		An item for each concept.
* Function and Macro Index::	An item for each WFDB library function and macro.

* Copying::                     You can make copies of this guide.  Here are
                                the terms for doing so.


File: wpg,  Node: Overview,  Next: Recent changes,  Prev: Top,  Up: Top

Preface
*******

   This guide documents the Waveform Database interface library (the
"WFDB library"), a package of C-callable functions that provide clean
and uniform access to digitized, annotated signals stored in a variety
of formats.  These functions were originally designed for use with
databases of electrocardiograms, including the MIT-BIH Arrhythmia
Database ("MIT DB") and the AHA Database for the Evaluation of
Ventricular Arrhythmia Detectors ("AHA DB").  In February 1990, the
predefined annotation set was expanded to accommodate the needs of the
European ST-T Database ("ESC DB").  The WFDB library is sufficiently
general, however, to be useful for dealing with any similar collection
of digitized signals, which may or may not be annotated.  The WFDB
library has evolved to support the development of numerous other
databases that include signals such as blood pressure, respiration,
oxygen saturation, EEG, as well as ECGs.  Among these multi-parameter
databases are the MIT-BIH Polysomnographic Database, the MGH/Marquette
Foundation Waveform Database, and the MIMIC Database.  Thus the WFDB
library is considerably more than an _ECG_ database interface.

   This guide describes how to write C-language programs that use
databases of ECGs and other signals.  A standard set of such programs
is included in the WFDB Software Package, and is described in the `WFDB
Applications Guide'; other documents describe the databases themselves,
and existing programs that use them (*note Sources::, for information
about obtaining these and related items).

   There are a few important concepts that should be well understood
before going further.  These concepts include "records"; "signals",
"samples", and "time"; and "annotations".

* Menu:

* Concepts 1::			Records (``tapes'') and record names.
* Concepts 2::			Signals, samples, and time.
* Concepts 3::			Annotations and annotation files.

_If this is your first exposure to the WFDB library,
study the three nodes above before going on._

* Applications::		Examples of programs based on the WFDB library.
* Guide::			What's in this guide, and where.
                		What you need to know to get started.
				Acknowledgments, where to send your
				comments, and how to get your very own
				printed copy of this guide.


File: wpg,  Node: Concepts 1,  Next: Concepts 2,  Prev: Overview,  Up: Overview

Records
=======

   The databases for which the WFDB library was designed consist of a
small number of "records", each of which is quite large (typically a
megabyte or more).  Database records usually originate as multi-channel
analog tape recordings that have been digitized and stored as disk
files.  For this historical reason, they are often referred to as
"tapes".  Each record contains a continuous recording from a single
subject.  A typical application program accesses only a single record,
and most (if not all) of the access within the record is sequential.
Much less frequently, it may be of interest to compare the contents of
several records, or to select sets of records.  These databases are
therefore qualitatively different from those for which conventional
database management software is written.

   Records are identified by "record names", which are three-digit
numbers for MIT DB records, four-digit numbers for AHA DB records, and
four-digit numbers prefixed by `e' for ESC DB records.  You may create
database records with names containing letters, digits, and
underscores.  Case is significant in record names that contain letters,
even in environments such as MS-DOS for which case translation is
normally performed by the operating system on file names; thus `e0104'
is the name of a record found in the ESC DB, whereas `E0104' is not.  A
record is comprised of several files, which contain signals,
annotations, and specifications of signal attributes; each file
belonging to a given record normally includes the record name as the
first part of its name.  A record is an extensible collection of files,
which need not all be located in the same directory, or even on the
same physical device.  Thus it is possible, for example, to create on a
magnetic disk a file of your own annotations for a record distributed
on a CD-ROM, and to treat your file as part of the record.


File: wpg,  Node: Concepts 2,  Next: Concepts 3,  Prev: Concepts 1,  Up: Overview

Signals, Samples, and Time
==========================

   Signals are commonly understood to be functions of time obtained by
observation of physical variables.  In this guide, a "signal" is
defined more restrictively as a finite sequence of integer "samples",
usually obtained by digitizing a continuous observed function of time
at a fixed "sampling frequency" expressed in Hz (samples per second).
The time interval between any pair of adjacent samples in a given
signal is a "sample interval"; all sample intervals for a given signal
are equal.  The integer value of each sample is usually interpreted as
a voltage, and the units are called analog-to-digital converter units,
or "adu".  The "gain" defined for each signal specifies how many adus
correspond to one "physical unit" (usually one millivolt, the nominal
amplitude of a normal QRS complex on a body-surface ECG lead roughly
parallel to the mean cardiac electrical axis).  All signals in a given
record are usually sampled at the same frequency, but not necessarily
at the same gain (*note Multi-Frequency Records::, for exceptions to
this rule).  MIT DB records are sampled at 360 Hz; AHA and ESC DB
records are sampled at 250 Hz.

   The "sample number" is an attribute of a sample, defined as the
number of samples of the same signal that precede it;  thus the sample
number of the first sample in each signal is zero.  Within this guide,
the units of "time" are sample intervals;  hence the "time" of a sample
is synonymous with its sample number.

   Samples having the same sample number in different signals of the
same record are treated as simultaneous.  In truth, they are usually not
_precisely_ simultaneous, since most multi-channel digitizers sample
signals in "round-robin" fashion.  If this subtlety makes a difference
to you, you should be prepared to compensate for inter-signal sampling
skew in your programs.


File: wpg,  Node: Concepts 3,  Next: Applications,  Prev: Concepts 2,  Up: Overview

Annotations
===========

   MIT DB records are each 30 minutes in duration, and are "annotated"
throughout; by this we mean that each beat (QRS complex) is described by
a label called an "annotation".  Typically an "annotation file" for an
MIT DB record contains about 2000 beat annotations, and smaller numbers
of rhythm and signal quality annotations.  AHA DB records are either 35
minutes or 3 hours in duration, and only the last 30 minutes of each
record are annotated.  ESC DB records are each 2 hours long, and are
annotated throughout.  The "time" of an annotation is simply the sample
number of the sample with which the annotation is associated.
Annotations may be associated with a single signal, if desired.  Like
samples in signals, annotations are kept in time and signal order in
annotation files (but *note Annotation Order::, for exceptions to this
rule).  No more than one annotation in a given annotation file may be
associated with any given sample of any given signal.  There may be many
annotation files associated with the same record, however; they are
distinguished by "annotator names".  The annotator name `atr' is
reserved to identify "reference annotation files" supplied by the
developers of the databases to document correct beat labels.  You may
use other annotator names (which may contain letters, digits and
underscores, as for record names) to identify annotation files that you
create.  You may wish to adopt the convention that the annotator name is
the name of the file's creator (a program or a person).

   Annotations are visible to the WFDB library user as C structures, the
fields of which specify time, beat type, and several user-definable
variables.  The WFDB library performs efficient conversions between
these structures and a compact bit-packed representation used for
storage of annotations in annotation files.


File: wpg,  Node: Applications,  Next: Guide,  Prev: Concepts 3,  Up: Overview

Applications
============

   Some typical uses of the WFDB library are these:

   * A _waveform editor_, such as `wave' (*note Sources::), reads the
     digitized signals of a database record and displays them with
     annotations superimposed on the waveforms.  Such a program allows
     the user to select any portion of the signals for display at
     various scales, and to add, delete, or correct annotations.

   * _Signal processing programs_ (e.g., *note Example 7::) apply
     digital filters to the signals of a database record and then
     record the filtered signals as a new record.  Similar programs
     perform sampling frequency conversion.

   * _Analysis programs_ (e.g., *note Example 10::) read the digitized
     signals, analyze them, and then record their own annotations.

   * An _annotation comparator_, such as `bxb' (*note WFDB
     Applications::), reads two or more sets of annotations
     corresponding to a given record, and tabulates discrepancies
     between them.  If the reference annotations supplied with the
     database are compared in this way with annotations produced using
     an analysis program, this comparison is a means of establishing
     the accuracy of the analysis program's output.

   The WFDB library provides the means for programs such as those
described above to select a database record, read and write signals,
read and write annotations, jump to arbitrary points in the record, and
determine attributes of the signals such as the sampling frequency.
The library also provides a variety of other more specialized services
for programs that need them.  The library defines an interface between
programs and the database that is sufficiently powerful, general, and
efficient to eliminate the need for _ad hoc_ user-written database I/O.


File: wpg,  Node: Guide,  Prev: Applications,  Up: Overview

About this Guide
================

   You should have a good grasp of the C language in order to make the
best use of this guide.  If ANSI C prototypes, used here to document
the WFDB library functions, are unfamiliar to you, see pp. 217-218 in
the second edition of `The C Programming Language' by Kernighan and
Ritchie, Prentice Hall, 1988.  (This is the famous `K&R'; all `K&R'
references in this guide include page numbers for the second edition.
Newcomers to C should have a copy for ready reference while reading this
guide.)  It may also be helpful to have a copy of a database directory,
such as the `MIT-BIH Arrhythmia Database Directory'
(http://www.physionet.org/physiobank/database/html/mitdbdir/).  The
`WFDB Applications Guide' (http://www.physionet.org/physiotools/wag/)
will be useful as a reference for existing WFDB library-based
applications (available from PhysioNet, `http://www.physionet.org/').

   You should have access to a computer that has the WFDB library and at
least one or two database records on-line, or access to the World Wide
Web, where database records can be obtained from PhysioNet and other
sources.  (If you are installing the WFDB library on a new computer for
the first time, please read the installation notes supplied with the
WFDB library first, or *note Installing the WFDB Software Package:
Installation., then return here.)  You should know how to create a C
source file using your favorite editor, and you should know how to
compile it and how to run the resulting executable program.

   Resist all temptation to plunge into the esoteric details of file
formats.  (Those who find such details irresistible will find them in
Section 5 of the `WFDB Applications Guide'; note, however, that support
for new file formats is added to the WFDB library from time to time, so
that the information you find there may be incomplete.)  The WFDB
library provides an efficient means of reading and writing files in
many formats; it is not a trivial task to duplicate it, and time spent
doing so is time that could be spent doing something useful, enjoyable,
or possibly both.  If you really think you need to understand the file
formats in order to translate them into whatever the ECGWhizz Model 666
needs, consider instead writing a format translator using the WFDB
library to read the files; then you will at least have a program that
requires only recompilation with a new version of the WFDB library when
file formats change.  _In extremis_, use `rdann' and `rdsamp' --
available from PhysioNet in source and ready-to run formats -- to
translate files into text format.

   Chapter 1 of this guide begins with a simple example program that
reads a few samples from a database record.  This example should help
you understand the mechanics of compiling and using a program that does
something with an ECG database.  Chapter 2 introduces the library
functions themselves, with a number of brief examples; you may wish to
skim through this material on a first reading to get acquainted with
what is available, and then refer to it as needed while writing your
programs.  Data structures for annotations and for signal and annotator
attributes are described in chapter 3.  Chapter 4 contains a table of
annotation types and descriptions of several annotation-mapping macros.
Database files and related topics are discussed in chapter 5, which can
be skipped on a first reading.  Chapter 6 contains additional example
programs that illuminate a few of the darker corners of the WFDB
library.  The glossary defines the ordinary-sounding words such as
"signal" that have specialized meanings in this guide; such words are
"emphasized" in their first appearances in order to warn you that you
should look them up in the glossary on a first reading (*note
Glossary::).

   If the WFDB library has not yet been installed on your system, *note
Installing the WFDB Software Package: Installation..  Another appendix
(*note WFDB Applications::) includes brief descriptions of the
application programs that are distributed with the WFDB library as part
of the WFDB software package.

   Another appendix discusses porting the WFDB library to new machines
or operating systems, and includes notes on adding support for new file
formats, annotation codes, and other enhancements (*note Extensions::).
The WFDB library has been written with portability in mind.  It runs on
a wide variety of machines and operating systems, including Unix (BSD
4.x, System V, SunOS, Solaris, HP-UX, OSF/1, Version 7, XENIX, VENIX,
ULTRIX, GNU/Linux, OpenBSD, IRIX, AIX, AUX, Darwin, MacOS/X, SCO,
Coherent, and more), MS-DOS, MS-Windows, VMS, and classic MacOS.  This
guide was written for Unix users (with notes for MS-Windows and MS-DOS
users where differences exist), but others should find only minor
differences.

   At the end of the guide is a list of sources for databases and other
materials that may be useful to readers (*note Sources::).

   Many friends have contributed to the development of the WFDB
library.  Thanks to Paul Albrecht, Ted Baker, Phil Devlin, Scott
Greenwald, David Israel, Roger Mark, Joe Mietus, Warren Muldrow, and
especially to Paul Schluter, whose elegant 8080 assembly language
functions inspired these (long live `getann'!).  Pat Hamilton and Bob
Farrell contributed ports, to classic MacOS and the MS 32-bit Windows
environments, respectively.  Jose Garcia Moros and Salvador Olmos
contributed Matlab/Octave reimplementations of a useful subset of the
WFDB library.  Thanks also to the many readers of earlier versions of
this guide; if this edition answers your questions, it is because
someone else has already asked them, and hounded the author until he
produced comprehensible answers.

   Before May, 1999, and the release of version 10.0.0 of the library,
the WFDB library was known as the DB library, and this guide was the
`ECG Database Programmer's Guide'.  The name of the library was changed
because of confusion caused by the recent proliferation of another
library with the same name (a reimplementation of the Berkeley Unix DBM
library).  The names of this guide, and of the `WFDB Applications
Guide' (formerly the `ECG Database Applications Guide'), have been
changed in view of the increasingly broad range of applications in
which the library is being used.

   The first edition of this guide was written as a tutorial for MIT
students using the ECG databases for a variety of signal-processing and
analysis projects.  The guide, and the WFDB library itself, have been
extensively revised since they first appeared in 1981.  Your comments
and suggestions are welcome.  Please send them to:

     George B. Moody  <<george@mit.edu>>
     MIT Room E25-505A
     Cambridge, MA 02139
     USA

   An HTML version of this guide, suitable for viewing using any web
browser, is included with the WFDB Software Package.  The latest
version may always be viewed at
`http://www.physionet.org/physiotools/wpg/' using your web browser.

   You can format and print copies of this guide using TeX if you have
it (see `makefile' in the `doc' directory of the library distribution
for instructions on doing so).  You may obtain a preformatted version
suitable for output on any PostScript device from
`http://www.physionet.org/'.


File: wpg,  Node: Recent changes,  Next: Usage,  Prev: Overview,  Up: Top

Recent changes
==============

   This section contains a brief summary of changes to the WFDB library
and to this guide since the first printing of the tenth edition of this
guide in June, 1999.  See `NEWS', in the top-level directory of the
WFDB Software Package distribution, for information on any more recent
changes that may not be described here.

Changes in version 10.3.0
-------------------------

   Fixed bugs in `lib/sample.c' that caused improper accounting of
signal group numbers when reading from two or more records at the same
time (as in `nst'), a bug that caused a segfault in `nst', and a bug
that referenced uninitialized memory in `newheader' if `nsig' = 0.

   The WFDB Software Package has been ported to MacOS/X (Darwin),
version 10.2 (the port should also work under 10.1 but this has not
been tested and will not be supported).

   It is now possible to generate a shared WFDB library (DLL) under
MS-Windows using Cygwin/gcc.

   Added functions `sample' and `sample_valid' to the WFDB library (in
`lib/signal.c').  `sample(s, t)' returns the sample at time (sample
number) `t' from signal `s', handling all necessary buffering
internally and allowing the caller to treat the signal file as a
virtual array of randomly accessible samples.  `sample_valid' can be
invoked to check if the most recent value returned by `sample' was
valid (e.g., to see if the end of the input was reached).  For an
example of the use of these functions, see `app/wqrs.c'.

Changes in version 10.2.9
-------------------------

   Fixed a bug in example 9 in this guide (introduced in version
10.2.0).

   Updated `lib/wfdbdll.def' and the `Makefile.dos' files in several
directories.  These have not been tested in recent years and may need
further revisions; feedback is welcome.

   Corrected persistent problems with generating PDF versions of the
manuals for the desired page size, and added hyperlinks to the PDF
version of this guide.

   (WFDB library version 10.2.8 was identical to 10.2.7.)

Changes in version 10.2.7
-------------------------

   Added a workaround to `wfdb_fclose' (in `lib/wfdbio.c') so that
closing `stdin' after using `freopen' doesn't trigger a core dump.

   If out-of-order annotations were written and automatic annotation
sorting was suppressed, the warning produced by `oannclose' (in
`lib/annot.c') once again includes the correct `sortann' command needed
to put the annotations into order.  (This feature was broken by a
previous revision.)

Changes in version 10.2.6
-------------------------

   The new functions `setifreq' and `getifreq' allow an application to
choose any convenient sampling frequency for reading input signals.
Samples read from signal files using `getvec' are buffered, resampled,
and delivered to the calling application as if the original signals had
been sampled at the desired frequency.  Times expressed in sample
intervals passed to or from other WFDB library functions (`getann',
`putann', `mstimstr', `timstr', and `strtim') are rescaled as needed to
match intervals corresponding to the chosen frequency.  Thanks to Pat
Hamilton for the inspiration!

   The WFDB library now records the base time with millisecond precision
(previous versions did so with one-second precision), and `xform'
provides starting times to the library function `setbasetime' with
millisecond precision.  Thanks to Allavatam Venugopal for providing
examples that illustrated the need for these features.

   Fixed deskewing buffer initialization in `getframe', broken by the
10.2.0 update, which introduced an infinite loop when reading a record
that requires skew correction starting at sample 0.  Thanks to Andrew
Walsh for finding an example that triggered this bug.

   Fixed rounding errors in `adumuv', `muvadu', and `physadu'.
Previous versions rounded negative values toward zero;  to obtain
consistent conversions, however, it is necessary to round all values
down (e.g., from -1.5 to -2 rather than up to -1).

   Fixed a memory leak in `wfdb_fclose' (in `lib/wfdbio.h').  Thanks to
Ion Gaztan~aga.

Changes in version 10.2.5
-------------------------

   Additions and fixes in `wfdbf.c' (the Fortran wrappers for the WFDB
library).

Changes in version 10.2.4
-------------------------

   Code in `wfdbio.c' that required the use of the string `header' to
identify a header file has been revised so that the standard `hea' is
now usable for this purpose in all cases.

Changes in version 10.2.3
-------------------------

   Portability fixes in `wfdblib.h'.  (WFDB library version 10.2.2 was
identical to 10.2.1.)

Changes in version 10.2.1
-------------------------

   Most users will no longer need to set the WFDB path explicitly, as a
result of several minor changes in the default path and in the
installer for the WFDB Software Package.

   The environment variable `WFDBNOSORT' was replaced by `WFDBANNSORT',
and the environment variable `WFDBGVMODE' was introduced (*note
Annotation Order::, and *note Multi-Frequency Records::, for details).

Changes in version 10.2.0
-------------------------

   There are no longer any fixed limits on the numbers of signals or
annotation files that can be opened simultaneously, or on the number of
samples per signal per frame.  In previous versions of the WFDB
library, the symbols `WFDB_MAXSIG', `WFDB_MAXANN', and `WFDB_MAXSPF'
(all defined in `<wfdb/wfdb.h>') specified limits on these parameters
that could be modified only by recompiling the WFDB library.  These
symbols are still defined for compatibility with older applications
that use them (typically to determine the size of static arrays).

   Since version 10.1.1, record names may include path information (see
the notes for version 10.1.1 below), but if such names are used to
generate names of WFDB output files, the user has been required to
ensure that the target directory exists.  This requirement is
eliminated in version 10.2.0.  If an output file is specified to be
located in a non-existent directory, the WFDB library will attempt to
create the directory (including, if necessary, any non-existent parent
directories).  This feature simplifies the use of record names that
include directory information, as is common when reading data from a
CD-ROM or a web server such as PhysioNet.  For example, using the WFDB
path (`. http://www.physionet.org/physiobank/database'), if the current
directory, `.', does not contain a subdirectory named `mitdb', the
command:

     sqrs -r mitdb/100

will read its input from
`http://www.physionet.org/physiobank/database/mitdb/', will create a
directory named `mitdb' within the current directory, and will write
its output annotation file (`100.qrs') into this newly-created
directory.  If we then use the command:

     rdann -r mitdb/100 -a qrs

the header file is still read from the remote directory, but the
annotation file is read from `./mitdb'.  (The programs `sqrs' and
`rdann' are standard applications that use the WFDB library;  see the
`WFDB Applications Guide' for details.)

   Also new is the WFDB test suite (located in the `checkpkg' directory
of the WFDB source tree, at the same level as the `lib' directory
containing the WFDB library sources).  This set of programs can be used
to help verify that a newly-installed version of the WFDB library
behaves properly.

Changes in version 10.1.6
-------------------------

   The WFDB library requires that the record name specified in the
first line of a header file must match the name of the record with
which the header file is associated (this is done in order to detect
corrupted or erroneously renamed header files).  Version 10.1.6
requires that only the final portion of the record name (stripped of
any path information) must match.

Changes in version 10.1.5
-------------------------

   More changes in the `make' description files, for Cygwin
compatibility.

Changes in version 10.1.4
-------------------------

   The symbol `WFDB_NETFILES' replaces the old `NETFILES'.

Changes in version 10.1.3
-------------------------

   More changes in the `make' description files, to support a
configuration script.

Changes in version 10.1.2
-------------------------

   Changes in the `make' description files.

Changes in version 10.1.1
-------------------------

   Record names may contain (absolute or relative) path information as
a prefix, and if (as a result) an input file is found in a location
that does not appear explicitly in the WFDB path, that location is
appended to the end of the WFDB path.  For example, if the WFDB path is
`. http://www.physionet.org/physiobank/database', and the record name
`mitdb/100' is supplied to `wfdbinit', the WFDB library will find the
header file at
`http://www.physionet.org/physiobank/database/mitdb/100.hea', and will
then add `http://www.physionet.org/physiobank/database/mitdb/' to the
end of the WFDB path so that the signal file (specified as `100.dat' in
the header file) can be found.

Changes in version 10.1.0
-------------------------

   Version 10.1.0 supports a new signal file format (311), and contains
numerous minor changes in the NETFILES support code introduced in
10.0.1.

Changes in version 10.0.1
-------------------------

   Beginning with version 10.0.1, the WFDB library supports reading not
only local files, but also remote files made available by web (HTTP) or
FTP servers.  To make use of this feature, link your application with
both the WFDB library and the `libwww' library (freely available for
all versions of Unix, and for most recent versions of MS Windows, from
`http://www.w3.org/Library', or from
`http://www.physionet.org/physiotools/libwww/').  (In some cases,
notably under GNU/Linux, `libwww' is linked together with the
dynamically-loaded version of the WFDB library, so that you do not need
to link `libwww' explicitly.)  All access to remote files is read-only.
If you do not wish to allow access to remote files, or if `libwww' is
not available for your OS, simply do not define the symbol NETFILES
when compiling the WFDB library.  For further details, see `wfdbio.c'
in the WFDB library sources.

   The WFDB environment variable may now contain whitespace (space,
tab, or newline characters) as path component separators under any OS.
Multiple consecutive whitespace characters are treated as a single path
component separator.  Use a `.' to specify the current directory as a
path component when using whitespace as a path component separator.  A
semicolon (`;') is also acceptable as a path component separator under
any OS.  A colon (`:') is still acceptable as a path component
separator under Unix (Linux, etc.), provided only that the colon is not
immediately followed by `//'.

   If the WFDB path includes components of the forms
`http://somewhere.net/mydata' or `ftp://somewhere.else/yourdata', the
sequence `://' is explicitly recognized as part of a URL prefix (under
any OS), and the `:' and `/' characters within the `://' are not
interpreted further.  Note that the MS-DOS `\' is _not_ acceptable as
an alternative to `/' in a URL prefix.  To make WFDB paths containing
URL prefixes more easily (human) readable, use whitespace for path
component separators.

   Previous versions of the WFDB library that were compiled for
environments other than MS-DOS used file names in the format
TYPE.RECORD.  This file name format is no longer supported.

Changes in version 10.0.0
-------------------------

   Beginning with version 10.0.0, the name of the library is WFDB.  All
earlier versions were named DB.  All library symbols have been similarly
renamed, with `WFDB' and `wfdb' replacing `DB' and `db' everywhere, in
names of library functions, constants, type and structure definitions,
library source file names, and names of environment variables (e.g.,
the DB environment variable is now the WFDB environment variable).

   Version 10.0.0 of the WFDB library is functionally identical with the
final release (version 9.7.4) of the DB library, except for the name
changes.  It should be possible to recompile existing applications
written for DB library version 9.x without modification, and to link
them with WFDB library version 10.0.0.  This is possible because two
sets of `#include' files are provided with the WFDB library.  The first
set, accessible via `#include <wfdb/...>', works with applications
written as described in this guide.  The alternate set, accessible via
`#include <ecg/...>', is compatible with DB 9.x applications as
described in previous editions of this guide.


File: wpg,  Node: Usage,  Next: Functions,  Prev: Recent changes,  Up: Top

Using the WFDB Library
**********************

   This chapter gives a brief overview of the steps needed to compile,
load, and run a program that uses the WFDB library.  It assumes that you
are able to log onto a Unix-based computer on which the WFDB Software
Package has been installed (*note Installing the WFDB Software Package:
Installation.), and that you know how to create a source file using a
text editor such as `emacs' or `vi'.  If you are using an MS-DOS
system, there are a few differences noted below.

* Menu:

* print samples::		A trivial example program.
* compiling::			Compiling a C program with the WFDB library.
* other languages::             Using the WFDB library with C++ or Fortran.
* WFDB path::			WFDB library environment variables.
* running example::		Running the example program.
* name restrictions::		Names to avoid when writing your programs.
* WFDB path syntax::		Customizing the WFDB path.
* exercises 1::			A few questions.


File: wpg,  Node: print samples,  Next: compiling,  Prev: Usage,  Up: Usage

A Trivial Example Program in C
==============================

   Suppose we wish to print the first ten samples of record `100s'.
(Record `100s' is the first minute of MIT-BIH Arrhythmia Database
record `100', supplied as a sample in the `data' directory of all
source distributions of the WFDB Software Package.)  We might begin by
creating a source file called `psamples.c' that contains:

     #include <wfdb/wfdb.h>
     
     main()
     {
         int i;
         WFDB_Sample v[2];
         WFDB_Siginfo s[2];
     
         if (isigopen("100s", s, 2) < 1)
             exit(1);
         for (i = 0; i < 10; i++) {
             if (getvec(v) < 0)
                 break;
             printf("%d\t%d\n", v[0], v[1]);
         }
         exit(0);
     }

(See `http://www.physionet.org/physiotools/wfdb/examples/psamples.c'
for a copy of this program.)

   All programs that use the WFDB library _must_ include the statement

     #include <wfdb/wfdb.h>

which defines function interfaces, data types (such as the
`WFDB_Sample' and `WFDB_Siginfo' types used in this example), and a few
useful constants.  (Most MS-DOS C compilers accept `/' as a directory
separator.  If you prefer to use the non-portable `\' under MS-DOS,
remember to quote it: `#include <wfdb\\wfdb.h>'.)

   The functions used in the example are described in detail in the next
chapter, and the data types are described in the following chapter
(*note Data Types::).  For now, note that `isigopen' prepares a record
to be read by `getvec', which reads a sample from each of the two
signals each time it is called.


File: wpg,  Node: compiling,  Next: other languages,  Prev: print samples,  Up: Usage

Compiling a Program with the WFDB Library
=========================================

   To compile the example program on a Unix system, we can say:

     cc -o psamples psamples.c -lwfdb

to produce an executable program called `psamples'.  (Your C compiler
may be named `gcc', `acc', `CC', or something else, rather than `cc',
but under any version of Unix, it will almost certainly work as shown
above.)  You may use any other compiler options you choose, but the
`-lwfdb' option must appear in the `cc' command line following any and
all source (`*.c') and object (`*.o') file names, in order to instruct
the loader to search the WFDB library for any functions that the
program needs (in this case, `isigopen' and `getvec').  Some programs
will need additional libraries, and the corresponding `-l' options can
usually be given before or after the `-lwfdb' option.

   If the WFDB library was installed with NETFILES support, it will make
use of functions contained in the `libwww' libraries.  If you have
dynamically linkable versions of the `libwww' libraries, as under
GNU/Linux, these will be loaded automatically when you run `psamples'.
If you have only static versions of these libraries, as under Solaris
or MS-Windows, however, it is necessary to provide additional arguments
in the `cc' command line in order to compile successfully.  One way to
do this is to follow the model used to compile the standard WFDB
applications supplied with the WFDB library; see `Makefile' in the
`app' directory of the WFDB software package source tree.

   If you are using WFDB version 10.2.6 or a later version and `gcc' or
a compatible compiler, the `wfdb-config' utility is available to help
construct commands for compiling programs that use the WFDB library
(and the `libwww' libraries, if available).  Use it like this:

     gcc `wfdb-config --cflags` -o psamples psamples.c `wfdb-config --libs`

Note that this command contains backticks (`), not apostrophes (').
`wfdb-config' is particularly useful if the WFDB library or its `*.h'
files are installed in non-standard locations, or if you have only
static `libwww' libraries.

   Under MS-Windows, it will be easiest to use `gcc', the GNU C/C++
compiler, which is included in the freely available Cygwin software
development system (`http://www.cygwin.com/'), and also in the freely
available MinGW package (`http://www.mingw.org/').  An MS-DOS version
of `gcc' is available in the free djgpp package
(`http://www.delorie.com/djgpp/'). These are used within a Cygwin
terminal emulator window or an MS-DOS box in exactly the same way as
described above for Unix C compilers.

   The WFDB library is developed and tested using `gcc', but careful
attention has been given to making it usable with any K&R or ANSI/ISO C
compiler.  Note, however, that binary versions of the WFDB library that
have been compiled using `gcc' are _not_ compatible with most
proprietary C/C++ compilers (except under Unix).  Since `gcc' is free,
high quality, and supported, it is highly recommended that you use it
for compiling your WFDB applications.

   If you choose to use an incompatible proprietary compiler, you are on
your own!  You may be able to create a linkable version of the WFDB
library from the sources in the `lib' directory of the WFDB source tree
using a proprietary compiler, but doing so is unsupported (see your
compiler's documentation, and if you are using MS-DOS or MS-Windows, see
`Makefile.dos' for hints).  If you are not able to build the WFDB
library using your compiler, you can compile the library sources
together with the source file(s) for your application.  It may be
easiest to copy the library sources (both the `*.c' and the `*.h'
files) into the same directory as the application sources.  If you
follow this approach, find the directory that contains `stdio.h' on
your system and make a `wfdb' subdirectory within that directory, then
copy the WFDB library's `*.h' files into the `wfdb' subdirectory (this
is necessary so that statements of the form `#include <wfdb/wfdb.h>'
will be handled properly by your compiler).  For example, to compile
`psamples.c' with Microsoft C/C++, set up the WFDB library source files
as just described, then use this command:

     cl psamples.c wfdbio.c signal.c annot.c calib.c wfdbinit.c

With Borland C/C++ or Turbo C or C++, substitute `bcc' or `tcc',
respectively, for `cl' in the command above.  You will find that some
WFDB applications do not need to be compiled with all of the WFDB
library sources (for example, `psamples' needs only `wfdbio.c' and
`signal.c'); in such cases, you may omit the unneeded sources for
faster compilation and smaller executable binaries.


File: wpg,  Node: other languages,  Next: WFDB path,  Prev: compiling,  Up: Usage

Using the WFDB library with other languages
===========================================

   If you prefer to write your applications in C++, you may do so, but
note that the WFDB library is written in C.  (Most C++ compilers can be
run in ANSI/ISO C compatibility mode in order to compile the WFDB
library itself.)  Each C++ source file that uses WFDB library functions
must include `<wfdb/wfdb.h>', in order to instruct your compiler to use
C conventions for argument passing and to use unmangled names for the
WFDB library functions.  In order for this to work, your C++ compiler
should predefine `__cplusplus' or `c_plusplus'; if it predefines
neither of these symbols, modify `<wfdb/wfdb.h>' so that the symbols
`wfdb_CPP' and `wfdb_PROTO' are defined at the top of the file, or
define `__cplusplus' in each of your source files before including
`<wfdb/wfdb.h>'.  Compile and link your program using whatever standard
methods are supported by your compiler for linking C++ programs with C
libraries.  See your compiler manual for further information.

   A set of wrapper functions is also available for those who wish to
use the WFDB library together with applications written in Fortran.
These functions, defined in `wfdbf.c'
(http://www.physionet.org/physiotools/wfdb/fortran/wfdbf.c), provide a
thin `wrapper' around the WFDB library functions, by accepting
Fortran-compatible arguments (there are no structures, and all
arguments are passed by reference rather than by value).  For example,
here is the Fortran equivalent of the example program in the previous
section:

             integer i, v(2), g
     
             i = isigopen("100s", 2)
             do i = 1, 10
              g = getvec(v)
              write (6,3) v(1), v(2)
      3      format("v(1) = ", i4, "    v(2) = ", i4)
             end do
             end

(See `http://www.physionet.org/physiotools/wfdb/fortran/fsamples.f' for
a copy of this program;  an extensively commented version of this
program is also available, at
`http://www.physionet.org/physiotools/wfdb/fortran/example.f'.)

To compile this program using `g77' (the GNU Fortran compiler), save it
as `fsamples.f' in the current directory, copy `wfdbf.c'
(http://www.physionet.org/physiotools/wfdb/fortran/wfdbf.c) to the
current directory, then type:

     g77 -o fsamples -fwritable-strings fsamples.f wfdbf.c -lwfdb

The Fortran wrapper functions are not discussed in this guide; for
further information, refer to fortran/README
(http://www.physionet.org/physiotools/wfdb/fortran/README) in the WFDB
Software Package.

   It should be possible to write a similar set of wrapper functions
for use with Matlab, Octave (a freely available open-source language
that is compatible with Matlab, available from
`http://www.che.wisc.edu/octave/'), or Scilab (an open-source
scientific software package for numerical computations, with a language
similar to that of Matlab, available from
`http://www-rocq.inria.fr/scilab/').  At this time, such wrappers are
not available, but a reimplementation of a useful subset of the WFDB
library in native m-code (contributed by Jose Garcia Moros and Salvador
Olmos) is available from
`http://www.physionet.org/physiotools/matlab/'.  Jesus Olivan Palacios
has written a tutorial (available at
`http://www.neurotraces.com/scilab/sciteam/') on using the WFDB
Software Package with Scilab.


File: wpg,  Node: WFDB path,  Next: running example,  Prev: other languages,  Up: Usage

The Database Path and Other Environment Variables
=================================================

   WFDB applications make use of several "environment variables", which
are named `WFDB', `WFDBCAL', `WFDBGVMODE', and `WFDBANNSORT'.  If these
variables have not been otherwise defined by the user, their values are
those given by `DEFWFDB', `DEFWFDBCAL', `DEFWFDBGVMODE', and
`DEFWFDBANNSORT' (defined in `wfdblib.h' at the time the WFDB library
was compiled).  Unless you have a non-standard setup, you may not need
to set these variables, but it will be helpful to read this section to
understand how they influence the behavior of WFDB applications.

   When WFDB applications _read_ database files, they must be able to
find them in various locations that may vary from system to system.  The
WFDB library refers to a character string that consists of an ordered
list of locations to be searched _for input files_.  This string is
called the "database path", or the "WFDB path".

   On most systems, the environment variable `WFDB', if set, specifies
the value of the WFDB path, and overrides the default value.  If you
need to use a non-default WFDB path, you must set the `WFDB'
environment variable appropriately before running any WFDB applications,
so that the WFDB path can be examined by the running program.  The WFDB
software package includes easily customizable shell scripts (batch
files) that illustrate how to do this for popular shells and command
interpreters; see _setwfdb_(1), in the `WFDB Applications Guide'.
(Under classic MacOS, for which the concept of environment variables is
foreign, the WFDB path may be set only by using `DEFWFDB'.)  For
further information, *note WFDB path syntax::.

   The shell scripts that set `WFDB' also set the `WFDBCAL' environment
variable, which is important if you make use of records that contain
signals other than ECGs.  `WFDBCAL' names a "calibration file" located
in one of the directories named by `WFDB'.  (The symbol `DEFWFDBCAL' is
usually defined in `wfdblib.h' to specify the name of a default
calibration file, to be used by the WFDB library if `WFDBCAL' has not
been set.)  Each signal type may be represented by an entry in the
calibration file.  Entries specify the characteristics of any
calibration pulses that may be present, and customary scales for
plotting the signals.

   The other environment variables are less frequently used than `WFDB'
and `WFDBCAL', and in most cases, the compiled-in defaults will be
appropriate (*note Annotation Order::, and *note Multi-Frequency
Records::, for details).


File: wpg,  Node: running example,  Next: name restrictions,  Prev: WFDB path,  Up: Usage

Running the Example Program
===========================

   If `WFDB' is properly set, MIT DB record `100s' is on-line and
readable, and the example program was compiled correctly, it can be run
by typing

     psamples

(Try `./psamples' if `psamples' doesn't work.)  Its output will appear
as:

     995     1011
     995     1011
     995     1011
     995     1011
     995     1011
     995     1011
     995     1011
     995     1011
     1000    1008
     997     1008

   The left column contains samples from signal 0, and the right column
contains those from signal 1.


File: wpg,  Node: name restrictions,  Next: WFDB path syntax,  Prev: running example,  Up: Usage

A Note on Identifiers
=====================

   External identifiers that begin with the underscore (`_') character
are reserved under the rules of ANSI C to the compiler and libraries.
In order to make the WFDB library as portable as possible, its own
external identifiers do not begin with underscores (since otherwise
they might conflict with external identifiers used by a standard
library).

   External identifiers beginning with `wfdb_' are reserved for the use
of the WFDB library.  These names are used for functions and global
variables that are intended for the private use of the WFDB library;
your programs should not need to use them.  You should avoid defining
functions or global variables with such names in your programs.

   External identifiers beginning with `WFDB_' are used for constants
and data types defined within `<wfdb/wfdb.h>'.  Use these identifiers
as needed in your programs, but avoid redefining them.

