2.7 Miscellaneous WFDB 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; see section Example 8: Creating a New Database Record, 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.

After calling newheader, you can call putinfo to add info strings to the header file. To close the header file, along with output signal files, and check that they were written successfully, invoke osigfopen(NULL, 0) (see section osigfopen).

setheader

int setheader(char *record, const 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; see section getinfo, and see section putinfo. (This function was first introduced in WFDB library version 5.0.)

To close the header file, along with output signal files, and check that they were written successfully, invoke osigfopen(NULL, 0) (see section osigfopen).

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 (see section 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.)

To close the header file, along with output signal files, and check that they were written successfully, invoke osigfopen(NULL, 0) (see section osigfopen).

getseginfo

int getseginfo(WFDB_Segment **psegarray)

Return:

(int)

number of segments belonging to the current input record

Invoking getseginfo(psegarray), where psegarray is declared to be of type **WFDB_Seginfo, sets *psegarray so that it points to an array of WFDB_Seginfo structures that describe the segments of the currently open (multi-segment) record. The return value indicates the number of segments (i.e., the number of valid WFDB_Seginfo structures in *psegarray. If there is no current input record, or if the current input record is not a multi-segment record, this function returns 0 and does not modify *psegarray.

contain the segments’ names, lengths, and starting sample numbers.

wfdbquit

void wfdbquit(void)

This function closes all open WFDB files and frees any memory allocated by other WFDB library functions. It also resets the following:

• the WFDB path (in versions 10.5.7 and later)
• 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); see section 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>’); see section aduphys and physadu
• internal variables used to determine output signal specifications; see section newheader.

If any annotations have been written out-of-order (see section 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. Note, however, that several WFDB library functions allocate memory that is maintained for later use by the library. This is not generally a problem, since these functions also free such memory if it is no longer needed on a subsequent call; thus these ‘memory leaks’ do not grow over time. Virtually all operating systems reclaim memory allocated by user-level applications on exit, so that a small and self-limiting leak is not a problem. Nevertheless, there are embedded systems and other environments in which memory is not reclaimed when a user application exits, and in these cases it is best to invoke wfdbquit() on exit from any WFDB application, even those that do not write output using the library. In an ANSI/ISO C environment, this can be ensured by including the line

	atexit(wfdbquit);

early in the code, before the first exit.

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 (see section 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.

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.)

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.

wfdbmemerr

void wfdbmemerr(int exit_on_error)

This function sets how the WFDB library behaves in the event of a memory allocation error. If exit_on_error is true (any non-zero value), then such an event causes the WFDB library to emit an appropriate error message and then terminate the running program. (This behavior is the default.)

If exit_on_error is false (zero), a subsequent memory allocation error will cause the WFDB library function in which it occurs to continue running if possible (after emitting an error message as above).

This function was first introduced in WFDB library version 10.4.6.

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 (see section timstr and strtim) for converting between sample intervals and seconds. See section Example 3: An Annotation Printer, 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 (see section setgvmode).

setsampfreq

int setsampfreq(WFDB_Frequency freq)

Return:

0

Success

-1

Failure: illegal frame frequency specified (freq must not be negative)

This function sets the frame frequency used by the time-conversion functions (see section timstr and strtim). Use setsampfreq before creating a new ‘hea’ file (see section newheader).

Note that despite the name of this function, the argument specifies the record frame frequency, not the sampling frequency; the two are not equivalent when reading or writing a multi-frequency record (see section Multi-Frequency Records).

See section Example 8: Creating a New Database Record, for an illustration of the use of setsampfreq.

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. (In versions 10.5.8 and later, it is not necessary to define the sampling frequency first.) (see section newheader). See section Example 8: Creating a New Database Record, for an illustration of the use of setbasetime.

There is no getbasetime function; use mstimstr(0) at any time after opening a record to convert the base date and time into a string.

findsig

int findsig(const char *string)

Return:

WFDB_Signal

Success

-1

Failure: signal not found

This function converts its argument to an input signal number. If string is numeric and can be interpreted as a valid input signal number, it is taken as such; otherwise, it is assumed to be a signal name, and if it is an exact match to the desc field of a currently open input signal’s siginfo structure, findsig returns the corresponding signal number. If two or more signals have identical matching names, findsig returns the lowest matching signal number.

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 (see section 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 (see section newheader). The effect of setbasecount is nullified by later invoking any of the functions that read ‘hea’ files.

setwfdb

void setwfdb(const char *string)

This function may be used to set or change the database path (see section The Database Path and Other Environment Variables) 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://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.) See section getwfdb for an example of the use of setwfdb.

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 ‘\\’.)

resetwfdb

void resetwfdb(void)

This function restores the WFDB path to its initial value (either the first value returned by getwfdb in the current process, or NULL).

wfdbfile

char *wfdbfile(const 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 (see section The Database Path and Other Environment Variables). 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.)

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.

getinfo

char *getinfo(char *record)

Return:

(char *)

pointer to an “info” string, or NULL

If record is not NULL, getinfo reads the first “info” string for record. If record is NULL, then getinfo reads the next available info string for the currently open record. Info strings are null-terminated and do not contain newline characters. Some records may contain no info strings; others may contain more than one info string. They may be stored within ‘hea’ or ‘info’ files; if any are contained in a record’s ‘hea’ file, they are returned first.

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));
…

If the ‘hea’ file was opened by another WFDB function, such as isigopen, annopen, sampfreq, or wfdbinit, the record argument can be NULL even for the first getinfo, like this:

…
char *info;
WFDB_Frequency sps;

if (sps = sampfreq("100s")
    while (info = getinfo(NULL))
        puts(info);
…

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

putinfo

int putinfo(const char *s)

Return:

0

Success

-1

Failure: header not initialized

This function writes s as an “info” string associated with the current output record. If setinfo has been called more recently than newheader or setheader, the info string is written to the ‘info’ file; otherwise, it is written to the ‘hea’ file, unless none of these three functions has been called (which results in an error). 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 or info file by successive invocations of putinfo. (This function was first introduced in WFDB library version 4.0.)

setinfo

int setinfo(char *record)

Return:

0

Success

-1

Failure: illegal record name, or info file could not be opened

-2

Failure: error writing info file (only if record is NULL)

This function opens the ‘info’ file for the specified record for writing using putinfo. If record.info does not exist in the current directory, it is created; otherwise, it is opened for appending (i.e., so that anything putinfo writes is added at the end of the file rather than overwriting any existing contents).

The file opened by setinfo can be used to store arbitrary information associated with record, without altering record’s header file. (setinfo was first introduced in WFDB library version 10.5.11.)

To close the ‘info’ file and check that it was written successfully, invoke setinfo(NULL). (Prior to WFDB library version 10.7.0, this would always return 0.)

wfdb_freeinfo

void wfdb_freeinfo()

This function releases memory allocated by getinfo, and closes the file opened by setinfo, if any. After calling it, getinfo behaves as it does on its initial call, (re)reading the info for the specified record (or the currently open record, if no record is specified). wfdb_freeinfo is invoked by wfdbquit. (This function was first introduced in WFDB library version 10.5.11.)

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 (see section Signal Information Structures) is non-zero. (This function was first introduced in WFDB library version 5.0.)

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 (see section Signal Information Structures) passed to osigfopen. (This function was first introduced in WFDB library version 5.0.)

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.)

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, see section 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.)

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, see section wfdbgetskew. (This function was first introduced in WFDB library version 9.4.)

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, see section 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.)

wfdbputprolog

void wfdbputprolog(const char *prolog, long bytes,
                   WFDB_Signal s)

This function writes the specified prolog of length bytes to the signal file for the specified output signal s, and invokes wfdbsetstart(s, bytes). (This function was first introduced in WFDB library version 10.4.15.)