2.1 Selecting Database Records

annopen

int annopen(char *record, const WFDB_Anninfo *aiarray,
            unsigned int nann)

Return:

0

Success

-3

Failure: unable to open input annotation file

-4

Failure: unable to open output annotation file

-5

Failure: illegal stat (in aiarray) specified for annotation file

-6

Failure: unable to sort output annotations (only if nann is 0)

-7

Failure: error writing annotation file (only if nann is 0)

This function opens input and output annotation files for a selected record. If record begins with ‘+’, previously opened annotation files are left open, and the record name is taken to be the remainder of record after discarding the ‘+’. Otherwise, annopen closes any previously opened annotation files, and takes all of record as the record name. aiarray is a pointer to an array of WFDB_Anninfo structures (see section Annotator Information Structures), one for each annotator to be opened. nann is the number of WFDB_Anninfo structures in aiarray. The caller must fill in the WFDB_Anninfo structures to specify the names of the annotators, and to indicate which annotators are to be read, and which are to be written. Input and output annotators may be listed in any order in aiarray. Annotator numbers (for both input and output annotators) are assigned in the order in which the annotators appear in aiarray. For example, this code fragment

…
char *record = "100s";
WFDB_Anninfo a[3];

a[0].name = "a"; a[0].stat = WFDB_READ;
a[1].name = "b"; a[1].stat = WFDB_WRITE;
a[2].name = "c"; a[2].stat = WFDB_READ;
if (annopen(record, a, 3) < 0)
…

attempts to open three annotation files for record ‘100s’. Annotator ‘a’ becomes input annotator 0, ‘b’ becomes output annotator 0, and ‘c’ becomes input annotator 1. Thus getann(1, &annot) (see section getann) will read an annotation from annotator ‘c’, and putann(0, &annot) will write an annotation for annotator ‘b’. Input annotation files will be found if they are located in any of the directories specified by WFDB (see section The Database Path and Other Environment Variables); output annotators are created in the current directory. Several of the example programs in chapter 6 illustrate the use of annopen; for example, see section Example 1: An Annotation Filter.

To close all annotation files and check that any output annotations were written successfully, invoke annopen("", NULL, 0). (Prior to WFDB library version 10.7.0, this would always return 0.) This can also be useful to force open annotation files to be closed without closing open signal files.

isigopen

int isigopen(char *record, WFDB_Siginfo *siarray, int nsig)

Return:

>0

Success: the returned value is the number of input signals (i.e., the number of valid entries in siarray)

0

Failure: no input signals available

-1

Failure: unable to read header file (probably incorrect record name)

-2

Failure: incorrect header file format

-3

Failure: internal limits exceeded (all signal files closed)

This function opens input signal files for a selected record. If record begins with ‘+’, previously opened input signal files are left open, and the record name is taken to be the remainder of record after discarding the ‘+’. Otherwise, isigopen closes any previously opened input signal files, and takes all of record as the record name. If the record name is ‘-’, isigopen reads the standard input rather than a ‘hea’ file. Siarray is a pointer to an array of WFDB_Siginfo structures (see section Signal Information Structures), one for each signal to be opened.

As a special case, if nsig is 0, siarray can be NULL. In this case, isigopen closes any open input signals, then returns the number of signals in record without opening them. Use this feature to determine the amount of storage needed for signal-related variables, as in the example below, or to force open input signal files to be closed without closing open annotation or output signal files. This action also sets internal WFDB library variables that record the base time and date, the length of the record, and the sampling and counter frequencies, so that time conversion functions such as strtim that depend on these quantities will work properly.

If nsig is greater than 0, isigopen normally returns the number of input signals it actually opened, which may be less than nsig but is never greater than nsig. The caller must allocate storage for the WFDB_Siginfo structures; isigopen will fill them in with information about the signals. Signal numbers are assigned in the order in which signals are specified in the ‘hea’ file for the record; on return from isigopen, information for signal i will be found in siarray[i]. For example, we can read the gain attributes of each signal in record ‘100s’ like this:

#include <stdio.h>
#include <wfdb/wfdb.h>

main()
{
    int i, nsig;
    WFDB_Siginfo *siarray;

    nsig = isigopen("100s", NULL, 0);
    if (nsig < 1)
        exit(1);
    siarray = (WFDB_Siginfo *)malloc(nsig * sizeof(WFDB_Siginfo));
    nsig = isigopen("100s", siarray, nsig);
    for (i = 0; i < nsig; i++)
        printf("signal %d gain = %g\n", i, siarray[i].gain);
    exit(0);
}

(See http://physionet.org/physiotools/wfdb/examples/pgain.c for a copy of this program.)

This program, unlike the example in the previous chapter, does not assume that the number of signals is known. The first invocation of isigopen determines this number (and the program quits if there are no signals). Next, the program allocates the array for the signal information, and then it opens the signals using the second invocation of isigopen, passing in the pointer siarray and the number of signals determined from the first call (nsig).

An error message is produced if isigopen is unable to open any of the signals listed in the header file. It is not considered an error if only some of the signals can be opened, however. A signal will not be opened if its signal file is unreadable, if an input buffer cannot be allocated for it, or if opening all of the signals in its group would exceed the limits defined by nsig. (Note, however, that most records have only one signal group; as a consequence, isigopen fails if nsig is less than the total number of signals in such cases.) If necessary, the caller can inspect the file names and signal descriptions in siarray to determine which signals were opened; see section Signal Information Structures. Several of the example programs in chapter 6 illustrate the use of isigopen; for example, see section Example 5: Reading Signal Specifications.

If the overall set of open signals exceeds internal limits (for example, the total number of samples per frame is greater than INT_MAX), isigopen returns -3 and closes all previously-opened input signals.

If nsig is less than 0, isigopen fills in up to -nsig members of siarray, based on information from the header file for record, but no signals are actually opened. The value returned in this case is the number of signals named in the ‘hea’ file. Note, however, that there is no guarantee that all (or indeed any) of the signals named in the ‘hea’ file are available to be opened. The features described in this paragraph were first introduced in version 4.4 of the WFDB library.

osigopen

int osigopen(char *record, WFDB_Siginfo *siarray, unsigned int nsig)

Return:

>0

Success: the returned value is the number of output signals; this number should match nsig

-1

Failure: unable to read header file

-2

Failure: incorrect header file format

-3

Failure: unable to open output signal(s)

This function opens output signal files. Use it only if signals are to be written using putvec. The signal specifications, including the file names, are read from the header file for a specified record. Unmodified MIT or AHA database ‘hea’ files cannot be used, since osigopen would attempt to overwrite the (write-protected) signal files named within. If record begins with ‘+’, previously opened output signal files are left open, and the record name is taken to be the remainder of record after discarding the ‘+’. Otherwise, osigopen closes any previously opened output signal files, and takes all of record as the record name. If the record name is ‘-’, osigopen reads the standard input rather than a ‘hea’ file. siarray is a pointer to an uninitialized array of WFDB_Siginfo structures; siarray must contain at least nsig members. The caller must allocate storage for the WFDB_Siginfo structures. On return, osigopen will have filled in the WFDB_Siginfo structures with the signal specifications.

No more than nsig (additional) output signals will be opened by osigopen, even if the header file contains specifications for more than nsig signals. For example, this code fragment

…
WFDB_Siginfo s[2];
int i, nsig;

nsig = osigopen("8l", s, 2);
for (i = 0; i < nsig; i++)
    printf("signal %d will be written into `%s'\n", i, s[i].fname);
…

creates 2 output signals named ‘data0’ and ‘data1’ (see section Piped and Local Records). See section Example 6: A Differentiator, and see section Example 7: A General-Purpose FIR Filter, for illustrations of the use of osigopen.

As a special case, if nsig is 0, siarray can be NULL. This can be useful to force open output signal files to be closed without closing open annotation or input signal files.

osigfopen

int osigfopen(const WFDB_Siginfo *siarray, unsigned int nsig)

Return:

>0

Success: the returned value is the number of output signals; this number should match nsig

-2

Failure: error in signal specification (fname or desc too long, illegal fmt or bsize, or incorrect signal group assignment)

-3

Failure: unable to open output signal(s)

-4

Failure: error writing signal file (only if nsig is 0)

This function opens output signals as does osigopen, but the signal specifications, including the signal file names, are supplied by the caller to osigfopen, rather than read from a header file as in osigopen. Any previously open output signals are closed by osigfopen. siarray is a pointer to an array of WFDB_Siginfo structures (see section Signal Information Structures), one for each signal to be opened. nsig is the number of WFDB_Siginfo structures in siarray.

Before invoking osigfopen, the caller must fill in the fields of the WFDB_Siginfo structures in siarray (see section Data Types; the initval, nsamp, and cksum fields may be left uninitialized, however). To make a multiplexed signal file, specify the same fname and group for each signal to be included (see section Multiplexed Signal Files). For ordinary (non-multiplexed) signal files, specify a unique fname and group for each signal. See section Example 8: Creating a New Database Record, for an illustration of the use of osigfopen.

To close all output signal and header files and check that they were written successfully, invoke osigfopen(NULL, 0). (Prior to WFDB library version 10.7.0, this would always return 0.) This can also be useful to force open output signal files to be closed without closing open annotation or input signal files.

wfdbinit

int wfdbinit(char *record,
             const WFDB_Anninfo *aiarray, unsigned int nann,
             WFDB_Siginfo *siarray, unsigned int nsig)

Return:

>0

Success: the returned value is the number of input signals (i.e., the number of valid entries in siarray)

0

Annotation files opened successfully, input signals unavailable (not an error for programs that don’t need them; no error message is printed if nsig is 0)

-1

Failure: unable to read header file (probably incorrect record name)

-2

Failure: incorrect header file format

-3

Failure: unable to open input annotation file

-4

Failure: unable to open output annotation file

-5

Failure: illegal stat (in aiarray) specified for annotation file (see section Annotator Information Structures)

This function opens database files other than output signal files for a selected record. The code

n = wfdbinit(record, a, na, s, ns);

is exactly equivalent to

n = annopen(record, a, na);
if (n == 0)
    n = isigopen(record, s, ns);

Avoid using wfdbinit and setifreq in the same program. See section Example 9: A Signal Averager, for an illustration of the use of wfdbinit. See section osigopen, and see section osigfopen, for methods of opening output signal files.