1.7 More About the WFDB Path

When a WFDB file must be opened for input, the WFDB library attempts to locate it by attaching each of the components of the WFDB path (one at a time) as a prefix to the file name. If two or more matching files exist in different locations in the WFDB path, the WFDB library opens only the file that resides in the first of these locations. Any other matching files are effectively invisible to WFDB applications unless the WFDB path is rearranged.

The default WFDB path is specified at the time the WFDB library is compiled, by defining a value for the symbol DEFWFDB in ‘wfdblib.h’. Current versions of the WFDB library are compiled with a three-component default WFDB path; the first component is empty (i.e., it refers to the current directory), the second component names the system-wide database directory (which contains the sample WFDB files supplied with the WFDB software package), and the third component is http://physionet.org/physiobank/database (referring to the PhysioBank data archives). Note that this default may be changed at the time the WFDB library is compiled. Normally, however, this means that any record available from PhysioBank is readable by any WFDB application provided that PhysioBank is accessible from the user’s computer and that the database name is included in the record name (for example, ‘slpdb/slp60’ or ‘nsrdb/16265’).

Under Unix and VMS, the WFDB path can be given as a colon-separated list of prefixes, in the format used for the Bourne shell’s PATH variable. Under MS-Windows, MS-DOS, and classic Mac OS, the WFDB path can be given in the format used for the MS-DOS PATH variable, with semicolons used to separate prefixes (colons retain their customary meanings, as drive letter suffixes under MS-DOS, or as directory separators on the Macintosh). Alternatively, components of the WFDB path may be separated by whitespace (under any operating system); this also implies that embedded spaces are not permitted within path components. For this reason, avoid using directories with names such as ‘My Documents’, or their subdirectories, to store WFDB files.

When WFDB applications write database files, these files are generally written to the current directory. (As an example, an application that analyzes one or more signals in a record may record its findings in an annotation file in the current directory.) If the record name (as provided by the application to the WFDB library) contains path information, however, output files are written to the corresponding subdirectory of the current directory. (For example, if a WFDB application writes an annotation file for record edb/e0103, the file will be written in the edb subdirectory of the current directory. The edb subdirectory will be created by the WFDB library if does not exist already. This feature was introduced in WFDB library version 10.2.0.)

Note particularly that the current directory is not necessarily part of the WFDB path. If you modify your WFDB path, you must explicitly include an empty (null) component, which corresponds to the current directory, in order to be sure that your WFDB applications can read any WFDB files that you have previously written. In most cases, this null component should be the first in the WFDB path. Thus, if you write into the current directory a modified version of an existing WFDB file, any later actions that would read this file will read your modified version rather than the original.

The WFDB path may contain http:// and ftp:// URL prefixes (other schema, such as file:// and https://, may also be supported if they are supported by your version of libcurl). If NETFILES support is not compiled into the WFDB library, any WFDB path components containing ‘://’ are ignored. (These features were first introduced in WFDB library version 10.1.0.)

If the WFDB library finds that the value assigned to the WFDB path is of the form ‘@file’, it replaces that value with the contents of the specified file. (This feature was first introduced in WFDB library version 8.0.) Indirect WFDB path files may be nested up to ten levels (this arbitrary limit is imposed to avoid infinite recursion if the contents of the indirect file are incorrect). This method of indirect assignment is useful under classic Mac OS, where recompilation of the WFDB library would otherwise be necessary in order to change the WFDB path. It may also be useful under MS-DOS to reduce the need for environment space, or if the length of the command needed to set the WFDB environment variable would otherwise approach or exceed the 128-byte limit for MS-DOS commands.

If a WFDB header file (see section Database Files) specifies that a signal file is to be found in a directory that is not already in the WFDB path, that directory is appended to the end of the WFDB path; in this case, if the WFDB path is not set, it is created with an initial null component followed by the directory that contains the signal file. (This feature was first introduced in WFDB library version 6.2.)

The string ‘%r’ is replaced by the current record name wherever it appears in the WFDB path; ‘%Nr’ is replaced by the first N digits of the record name, if N is a non-zero digit. For example, if (under Unix) the WFDB path is ‘:/cdrom/mimicdb/%3r:/cdrom/mitdb’, a request to read a file associated with record 055n will cause the WFDB library to look first in the current directory (since the WFDB path begins with an empty component), then in ‘/cdrom/mimicdb/055’, and then in ‘/cdrom/mitdb’. If ‘%’ is followed by any character other than ‘r’ or a non-zero digit followed by ‘r’, that character is used as is in the WFDB path; thus a literal ‘%’ can be included in the WFDB path by ‘escaping’ it as ‘%%’. (Substitutions of ‘%’-strings in the WFDB path were first introduced in WFDB library version 9.7.)