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 DB 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. If the entire DB Software Package is available, the ECG Database Applications Guide will be useful as a reference for existing DB library-based applications; if you have only a CD-ROM with MS-DOS binaries, refer to `bin.doc' (in the `bin' directory of your CD-ROM) for information on the available applications.
You should have access to a computer that has the DB library and at least one or two database records on-line. (If you are installing the DB library on a new computer for the first time, please read the installation notes supplied with the DB library first, or see section Installing the DB Software Package, 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 ECG Database Applications Guide; note, however, that support for new file formats is added to the DB library from time to time, so that the information you find there may be incomplete.) The DB 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 DB library to read the files; then you will at least have a program that requires only recompilation with a new version of the DB library when file formats change. In extremis, use `rdann' and `rdsamp' --- MS-DOS executables of which are included on all CD-ROM databases of ECGs --- 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 DB 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 (see section Glossary).
If the DB library has not yet been installed on your system, see section Installing the DB Software Package. Another appendix (see section DB Application Programs) includes brief descriptions of the application programs that are distributed with the DB library as part of the DB software package.
The DB 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, Linux, AIX, AUX, SCO, Coherent, and more), MS-DOS, MS-Windows, VMS, and the Macintosh OS. This guide was written for UNIX users (with notes for MS-DOS users where differences exist), but others should find only minor differences. One obvious difference between MS-DOS and other versions of the DB library is the file-naming convention: since record names can be longer than the three characters permitted in MS-DOS file name "extensions", MS-DOS names for DB files begin with the record name and end with a file type specifier (`hea' instead of `header', `atr' instead of `atruth', etc.), rather than the other way around. This difference is not particularly significant, however, since DB file names per se are never needed as DB library function arguments. So that database files on CD-ROMs may be read on all supported systems, the MS-DOS convention for naming DB files is recognized in addition to the "native" convention under UNIX, VMS, and on the Macintosh.
Another appendix discusses porting the DB library to new machines or operating systems, and includes notes on adding support for new file formats, annotation codes, and other enhancements (see section Extensions). At the end of the guide is a list of sources for databases and other materials that may be useful to readers (see section Sources).
Many friends have contributed to the development of the DB 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 the
Macintosh and the MS 32-bit Windows environments, respectively. 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.
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 DB 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 MIT Room 20A-113 Cambridge, MA 02139 USA (e-mail: george@hstbme.mit.edu)
If you use the GNU emacs editor, you can peruse a hypertext
version of this guide using info if it has been installed on your
system; among its many other features, emacs makes it easy to
copy code from the examples into your own programs. Installation
instructions are included in the DB Software Package; type C-h i
within GNU emacs to start up info (see section Sources, for
information about obtaining GNU emacs).
An HTML version of this guide, suitable for viewing using any web browser,
is included with the DB Software Package. The latest version may always be
viewed at http://ecg.mit.edu using your web browser.
Go to the first, previous, next, last section, table of contents.