README.NETFILES

file: README.NETFILES		G. Moody	14 September 1999
				Last revised:	 13 August 2012

WFDB software reads its input from files that can be located on local
disks or (if NETFILES support is present) on remote web and FTP servers.

This version of the WFDB software package contains NETFILES support in the
WFDB library, which is compiled if you have previously installed libcurl
(see http://curl.haxx.se/) or libwww (see http://www.w3.org/Library/).
NETFILES support is known to work well under FreeBSD, GNU/Linux, Mac OS X,
MS-Windows, and Solaris.

To use NETFILES once this software has been compiled and installed, the WFDB
path should contain one or more components that refer to remote files available
via http or ftp.  If NETFILES support is included, the default WFDB path
(defined in lib/wfdblib.h) is
	. /usr/database http://physionet.org/physiobank/database
(i.e., the first component is the current (local) directory, the second is
/usr/database in the local file system, and the third component is the
top-level PhysioBank database directory).  If you use a local PhysioBank
mirror, you may wish to change www.physionet.org to the hostname of your local
mirror in lib/wfdblib.h before compiling the WFDB library.  You may always
override this path by setting the WFDB environment variable.

Provided that a remote path component (one beginning with http:// or ftp://)
is included in the WFDB path, all WFDB applications that read local files will
then be able to read remote files with no other changes.  Note that the default
setting allows access by WFDB applications to any of the PhysioBank records by
prefixing the additional path information to the record name, as in these
examples:

	rdsamp -r mitdb/100 -t .1     (MIT-BIH Arrhythmia Database, record 100)
	rdann -r slpdb/slp67x -a st   (MIT-BIH Polysomnographic Database,
				       record slp67x)
	wave -r mimicdb/237/237	-a al (MIMIC Database, record 237 -- note that
				       since each MIMIC record is kept in its
				       own subdirectory of mimicdb, two levels
				       of additional path information are
				       necessary)
	wave -r mimicdb/237/ -a al    (MIMIC Database, record 237, as above;
	     		     	       allowed as a shortcut beginning in
				       version 10.5.6, November 2010)

NETFILES support was originally implemented by Michael Dakin as part of his
summer 1999 UROP project at MIT; version 10.0.1 of the WFDB library was the
first release to include this feature, in November, 1999.  Mike used the W3C's
libwww in his original implementation.  The libwww maintainers last updated the
library in June, 2002, and in January, 2004, the W3C formally announced that it
would not continue development of libwww, although the library remains freely
available.  In May, 2005, Benjamin Moody reimplemented NETFILES using libcurl.
The primary advantages of libcurl over libwww are that libcurl is smaller and
faster, it supports access to password-protected files (see below), and it is
actively maintained.  Both libraries are freely available on all popular
platforms.


Direct access from WFDB applications to password-protected files
----------------------------------------------------------------

If you have built the WFDB library using libcurl, version 7.12.0 or later,
then WFDB applications can also read password-protected files, such as those
within PhysioNetWorks shared or private projects.  The preferred way to do
this is to set the PNWUSER and PNWPASS environment variables as is done by
the pnwlogin script (see app/pnwlogin).  This method is usable with WFDB
library version 10.5.14 (August 2012) and later.  Versions 10.3.16 (June 2005)
through 10.5.13 can also provide access to password-protected files by use of
a text file named .netrc, but this method is less secure than the newer method,
which does not require the credentials to be kept in permanent storage.  The
use of .netrc is described in previous versions of this file;  it is not
recommended or supported in current installations.