file: README            I. Henry and G. Moody    August 2005
                        Last revised:           5 April 2006

Name: wfdb-csharp -- WFDB wrappers for C# (and other .NET languages)

Purpose:

The WFDB library (http://physionet.org/physiotools/wfdb.shtml) provides uniform
access to digitized signals and annotations in a wide variety of formats,
including those in PhysioBank (http://physionet.org/physiobank/).  The WFDB
library is written in C and includes bindings for C++ and wrappers for Fortran.

This package provides an interface that allows use of the WFDB library
functions from C# programs (using .NET or Mono).  A previous version of this
package has also been tested successfully with Visual Basic;  other .NET
enabled languages should work but have not been tested.

Authors:

Isaac Henry (ihenry@physionet.org), George Moody (george@physionet.org)

Background literature:

The SWIG web site (http://www.swig.org/)
The WFDB Programmer's Guide (http://www.physionet.org/physiotools/wpg/)
The Mono web site (http://www.mono-project.com/)

Platforms:

GNU/Linux (Mono), Mac OS X (Mono), MS Windows (Mono or .NET).  Other platforms
supported by SWIG and Mono (including *BSD and Solaris) should also work but
have not been tested.

Code organization:

This is a subpackage of wfdb-swig (see ../README).  The file named Makefile
is used by 'make' to manage the build and installation processes (see INSTALL).
The wrappers themselves are generated by SWIG from ../wfdb.i.

URLs:
   code:
        http://physionet.org/wfdb-swig/wfdb-csharp
        http://physionet.org/wfdb-swig/wfdb.i
   test scripts and data:
        http://physionet.org/examples/*.cs
   docs:
        The WFDB Programmer's Guide (http://physionet.org/physiotools/wpg/);
        also see the notes below

Installation and Testing:

See INSTALL, in this directory.

.......................................................................

Requirements

All of the software required to create and use WFDB .NET applications is
freely available, open-source software.  Proprietary tools may be
substituted for some of the open-source tools if desired.

The WFDB .NET wrappers can be used on any operating system on which WFDB
and .NET are supported, including MS Windows, GNU/Linux, and Mac OS X.

To run precompiled applications that use the WFDB .NET wrappers, you will need
a WFDB dynamic library (http://www.physionet.org/physiotools/wfdb.shtml) for
your platform, and a .NET Runtime Environment for your platform.  Novell's
open-source implementation of .NET, Mono (http://go-mono.com/), is freely
available for MS Windows, GNU/Linux and Mac OS X.  Of course, on Windows, you
can also use the Microsoft framework.

To build applications that use the WFDB .NET wrappers, you must also have a
.NET compiler for your platform.  Suitable C# compilers include Mono's freely
available mcs (http://go-mono.com) on all platforms, and Microsoft's csc on
Windows.  Microsoft's Visual Basic.NET has also been tested with these
wrappers.

To build the WFDB .NET wrappers, you must also have an ANSI C compiler for your
platform.  The freely available GNU gcc (http://gcc.gnu.org/) is recommended
(also for compiling the WFDB library itself).  Other ANSI C compilers may also
work; please write to wfdb-swig@physionet.org and let us know what you discover
if you try another compiler.

_______________________________________________________________________

A Trivial Example Program in C#

This program is a translation to C# of Example 2 from the WFDB Programmer's
Guide (http://physionet.org/physiotools/wpg/).  It translates the `atr'
annotations for the record named in its argument into an AHA-format annotation
file with the annotator name `aha'.

 using System;
 using Wfdb;

 public class example2 {

    static void Main(string[] argv) {
	WFDB_AnninfoArray an = new WFDB_AnninfoArray(2);
	WFDB_Annotation annot = new WFDB_Annotation();
		
	if (argv.Length < 1) {
		Console.WriteLine("usage: " + "fixme" + " record");
		Environment.Exit(1);
	}
	WFDB_Anninfo a = an.getitem(0);
	a.name = "atr"; a.stat = wfdb.WFDB_READ;
	an.setitem(0, a);
	a = an.getitem(1);
	a.name = "aha"; a.stat = wfdb.WFDB_AHA_WRITE;
	an.setitem(1, a);
	if (wfdb.annopen(argv[0], an.cast(), 2) < 0)
		Environment.Exit(2);
	while (wfdb.getann(0, annot) == 0 && wfdb.putann(0,annot) == 0)
		;
	wfdb.wfdbquit();
    }
}

First, note that you must include the wfdb package with 'using Wfdb'.

The functions used in this example are described in detail in the WFDB
Programmer's Guide; all are methods of the "wfdb" class. For now, note that
wfdb.annopen prepares a record to read by wfdb.getann, which reads an
annotation each time it is called. Note that WFDB constants are also members
of the "wfdb" class.

The WFDB data types are described in the WFDB Programmer's Guide.  In C#, each
WFDB structure is paired with an accessor class that allows you to work with
pointers to the native C structures in memory.  These classes are often
referred to as "shadow classes".

In addition, there are several 'Array' special classes, which are used in place
of pointer arrays in C.  Note that the 'cast' method must be used when passing
an 'Array' object to a method, as in

  wfdb.annopen(argv[0], an.cast(), 2)

The items in the 'Array' object can be accessed using the 'getitem' and
'setitem' methods.  Special care must be taken when manipulating the members of
an array.  As shown in the example, you must first obtain a shadow class object
for an item using 'getitem', 

  WFDB_Anninfo a = an.getitem(0);

which can then be used to get or set structure members. 

  a.name = "atr"; a.stat = wfdb.WFDB_READ;

Take special note that you must use 'setitem' to copy your changes back to the
array. 

  an.setitem(0, a);

This may seem unintuitive, but remember that the Array classes only manipulate
underlying C structures.

A copy of this program is available as ../examples/example2.cs.
To compile it, type
        make examples

The ../examples directory also contains translations into C# of the other
examples from the WFDB Programmer's Guide.


Compiling a C# Program with the WFDB Library

To compile the example program with Mono's mcs compiler, we can say:

 mcs -r:/usr/lib/mono/wfdb-csharp/wfdb-csharp.dll example2.cs

to produce a executable class called example2.exe. You may use any
other compiler options you choose, but you must reference the full path
of the wfdb-csharp.dll.

.......................................................................

Running a C# Program with the WFDB Library

Executable .NET programs have names with the suffix 'exe' on all platforms, not
only MS Windows.  Under MS Windows you can run them as you would any other
application, but be sure that the wfdb and wfdbsharpglue DLLs must be in your
PATH (typically, in the directory where the .exe files that use the DLLs are
stored).

When using Mono under GNU/Linux and Mac OS X, make sure the libwfdbsharpglue
and libwfdb dynamic libraries are stored in directories in your dynamic library
load path (LD_LIBRARY_PATH under GNU/Linux, DYLD_LIBRARY_PATH under Mac OS X),
and that the wfdb-csharp.dll is installed within a directory in your MONO_PATH.
If you have installed the wrappers as described in 'INSTALL' without changing
the default directories (/usr/lib and /usr/lib/mono respectively), Mono will
be able to find them without any special settings.  If you have chosen other
installation directories, follow this example to set the necessary environment
variables:

 export LD_LIBRARY_PATH=/usr/local/lib
 export MONO_PATH=/usr/local/lib/mono

Having prepared the run-time environment with these settings, we can now
run the compiled 'example2' by

 mono example2.exe

The shell script 'csw' (in the 'examples' directory) can set the variables
and invoke mono to run the application;  if you use WFDB C# applications
frequently, you may wish to edit csw to reflect your installation, and then
copy it into a directory in your PATH, such as /usr/local/bin.  In this case,
you will be able to run the example program by typing:

   jw examples/example2