Each function description begins with an ANSI C function prototype, which specifies the types of any arguments as well as the type of the quantity returned by the function (see K&R, pp. 217--218). Note that many of these functions take pointer arguments. These can be traps for newcomers to C. Study the examples carefully! Often a function will return information to the caller in a variable or structure to which the pointer argument points. It is necessary in such cases for the caller to allocate storage for the variables or structures and to initialize the pointers so that they point to the allocated storage. If you fail to do so, the compiler probably will not warn you of your error; instead your program will fail mysteriously, probably with a core dump and an "illegal memory reference" error message.
With few exceptions, DB library functions return integers that indicate success or failure. The tables that follow the function prototypes list the possible returns and their meanings. By convention, a return code of -1 indicates end-of-file on input files, and no error message is printed. Other negative return codes signify other types of errors, and are usually accompanied by descriptive messages on the standard error output (but see section dbquiet). Zero may indicate success or failure, depending on context (see the descriptions of the individual functions below). Positive codes (returned by only a few functions) always indicate success.
A comprehensive discussion of database files appears later in this guide
(see section Database Files). Most readers should not need to learn about
the gruesome details of how the data are actually stored. You should
know, however, that there are files that contain digitized signals,
other files that contain annotations, and still others (called
`header' files) that describe attributes of the signals such as
sampling frequency. The database path lists directories in which
database files are found; the DB library functions can find them given
only the record (and annotator) names, provided that DB has been
properly set (see section The Database Path). DB library functions responsible for
opening signal files find them by reading the `header' file (which
contains their names) first.
The first part of this chapter describes functions that extract information from `header' files in order to gain access to signal and annotation files. The following two sections describe functions that deal with signal and annotation files. Many readers will not need to go any further; the remaining sections deal with special-purpose functions that exist to serve unusual applications.
Go to the first, previous, next, last section, table of contents.