Up: Catalog of documents

Installing and using the DB Software Package and WAVE under Linux

For general information on the DB Software Package and WAVE, see the Software notes.

Linux is a freely available clone of the UNIX operating system for 386 and later PCs. For general information on Linux, see the Linux INFO-SHEET. (If you do not have an Internet connection, see the plain text version of this page, which includes the version of the Linux INFO-SHEET that was up-to-date as of the publication of this CD-ROM.)

Compiling the DB Software Package (optional)

Both sources and Linux binaries for the DB Software Package, version 9.7, are provided on this disk (in software/db). If you wish, you can compile the sources using gcc under Linux without modification; see software/db/Makefile for details. You can compile the DB Software Package, including making a shared DB library, using either old-style `a.out' binary format or the newer ELF binary format, depending on which format your versions of Linux and `gcc' support. (If you don't know, one way to find out is to run the command 
	file `which gcc`
If the output contains the word `ELF', you have an ELF-capable Linux and gcc.) If you have a choice of formats, ELF is recommended, since `a.out' format is rapidly becoming obsolete.

If you wish to compile the shared DB library in `a.out' format, you will need the programs `getvars', `getfuncs', `getsize', `jumpas' `mkimage', `mkstubs', and `verify-shlib'. If these programs are not installed on your system, they may be unpacked from `linuxmsc/tools216.tgz', a gzip-compressed `tar' archive. The most recent version may be retrieved by anonymous FTP from tsx-11.mit.edu; get `pub/linux/packages/GCC/src/tools-2.NN.tar.gz'. Be sure to replace `slib' with `slib-linux' in LIBTARGETS within `software/db/Makefile' if you choose to use `a.out' format.

If you wish to compile the shared DB library in ELF format, you do not need to do anything special. Leave `slib' (*not* `slib-linux') in LIBTARGETS, and follow the instructions in `software/db/Makefile' to set other variables appropriately.

Installing the DB Software Package and WAVE

To simplify typical installations, a complete set of Linux binaries in ELF for the DB Software Package (version 9.7) and WAVE (version 6.1) is included in the `software' directory of this disk (in `linux.tar'; an older set of `a.out' binaries is in `linuxold.tar'). To use the ELF binaries, you must have installed (in /lib or /usr/lib) the standard C library, libc.so.5.0.9 or later; to use the a.out binaries, you must have libc.so.4.5.26 or later. At least one of these has been included with most if not all distributions of Linux since mid-1994.

In order to use WAVE, you must also have installed X11R5 or X11R6, and XView 3.2 (a freely available Open Look toolkit for X11), on your Linux system. Current Linux distributions include XFree86 version 3.x (X11R6); older a.out kernels may have either XFree86 version 3.x or version 2.1.1 (X11R5). Compatible versions of XView 3.2 are included in most distributions. Three versions of WAVE are provided on this disk. `wave.r5' (in linuxold.tar) is an a.out binary intended for use with X11R5, although you may use it with X11R6 if you have the R5 shared libraries. `wave.r6' (also in linuxold.tar) is an a.out binary that requires the X11R6 libraries, and is a better choice if you have installed R6. If your system supports ELF, `wave' (in linux.tar) is the best choice; it requires the X11R6 libraries (standard with Linux ELF distributions).

To use any version of WAVE, the following shared libraries must have been installed:

If your distribution is missing the XView and Open Look graphics libraries, you can compile them from the sources in `linuxmsc'. Precompiled ELF-format versions of these libraries may also be found in that directory. Make sure that your system supports ELF before attempting to use them; to do so, simply copy them into any directory used for shared libraries on your system (/lib and /usr/lib are good choices) and run /sbin/ldconfig after doing so.

WAVE and all of the applications in the DB Software Package use the shared version of the DB library in order to read the recordings on this disk and others in a variety of supported formats. Since the sources for the library are provided (in `software/db/lib'), you can modify the library, for example to add support for additional file formats, without the need to recompile the applications that use it. Root permissions are needed in order to install the shared library in /usr/lib and in order to run `ldconfig' after doing so.

To install the binaries in the standard places, log in with root permissions, and (from the `software' directory) type 

	sh install.unx
The installation script detects if you have ELF support and installs the proper binaries. If you have only a.out support the script also checks if you have X11R6, and links the correct WAVE binary to `wave'. Sources for WAVE are not included; if you wish to install WAVE, you must do so from the binaries provided.

Using the DB Software Package under Linux

Refer to the ECG Database Programmer's Guide and the ECG Database Applications Guide for details on using the applications provided and on writing your own applications to read the recordings on this disk.

Using WAVE under Linux

For general information about using WAVE, refer to the WAVE User's Guide. Type wave with no command-line arguments to get a brief summary of options and instructions for printing a concise on-line manual.

There are a few quirks in using WAVE under Linux, described briefly below. Since all of these appear to be related to the X11 server or the XView library, you may not encounter them on your system. Please send details of any other problems (and work-arounds, if possible) to me (address below).

Window managers

I haven't explored all of the possibilities yet (Linux offers many), but past experience suggests that WAVE will probably coexist most happily with an Open Look window manager. Linux distributions usually include both `olwm' and `olvwm'; both work well with WAVE. To try out `olvwm', it is usually sufficient to type the command `openwin' in a text mode session; this starts the X server and the window manager. (If you have heavily customized your `.xinitrc', you may need to replace it with a bare-bones version in order to get `openwin' to work properly.) If you find problems related to using WAVE with other window managers, please let me know about them, especially if you have discovered solutions or work-arounds.

Two-button mice

XFree86 can make a two-button mouse emulate a three-button mouse. When this feature is enabled, press both buttons simultaneously to simulate pressing the middle button. To make it possible for XFree86 to recognize this even if the button-down events are not exactly simultaneous, each button-down event is delayed pending the next mouse event (a button-down or button-up event, or a mouse motion event). As a result, annotation editing in WAVE may be awkward, particularly if you are accustomed to using WAVE with a three-button mouse. You may wish to replace your two-button mouse with a Logitech or other three-button mouse in this case; if you do so, be sure to remove the line "Emulate3Buttons" from your `Xconfig' or `XF86Config' file (see the XFree86 documentation for details).

Enabling XView spot help

In at least some XFree86 distributions, XView spot help is not enabled. (This feature, if enabled, opens a help window describing the XView control to which the pointer points, whenever a special "Help" key is pressed. WAVE includes full support for XView spot help.) To enable XView spot help when you press the F1 key, type: 
	xmodmap -e "keysym F1 = Help"
Once you have tested the effect of this command, you can make this change permanent for future sessions by typing: 
	xmodmap >~/.Xmodmap
(This file is read by your `.xinitrc' whenever you start the X window system; see `.xinitrc' for details.) To make this behavior a default for all users, copy .Xmodmap into the directory /usr/X386/lib/X11/xinit (be sure the copy is readable by all users).

To enable spot help for other XView applications, you may need to set the environment variable HELPPATH. If you use sh or bash, do this by: 

	HELPPATH=/usr/openwin/lib/help 
	export HELPPATH
Include these commands in your .profile so that they are executed whenever you log in. If you use csh or tcsh, add the command 
	setenv HELPPATH /usr/openwin/lib/help
to your .cshrc.

Using function keys and the numeric keypad in WAVE

WAVE can be controlled using the mouse and the normal alphanumeric keys only, but there are a few alternate controls that use function keys and the numeric keypad. The on-line help for WAVE generally describes how to use these functions on a Sun keyboard. On a PC keyboard, some substitutions must be made: 
 
 Action					PC key			Sun key 
 
 Open spot help                         <F1>                    <Help> 
 Simulate middle mouse button click     <F2>                    keypad <5> 
 Move editing cursor left               <F3>                    keypad <=> 
 Move editing cursor right              <F4>                    keypad <*> 
 Copy selected annotation to template   <F6>                    <Copy> 
 Search forward                         <F9>                    <Find> 
 Advance to the end of the record       <shift><F9>             <End> 
 Search backward                        <ctrl><F9>              <ctrl><Find> 
 Move to the beginning of the record    <ctrl><shift><F9>       <Home> 
 Advance half a screen                  <F10>                   <PgDn> 
 Advance a full screen                  <ctrl><F10>             <ctrl><PgDn> 
 Move back half a screen                <shift><F10>            <PgUp> 
 Move back a full screen                <ctrl><shift><F10>      <ctrl><PgUp>
These PC equivalents are also usable on Sun keyboards. In addition, all of the actions that can be performed using the Sun arrow keys can also be performed using the PC arrow keys.

Extraneous error messages

Messages of the form 
	ttysw_sigwinch, can't get tty process group: Not a typewriter
may appear in a terminal window of a controlling process while running WAVE (or other XView applications) under Linux. These messages may be safely ignored.

Special considerations for XFree86 version 2.1.1 (X11R5)

Dotted lines used by WAVE (and other applications such as olvwm) are improperly rendered by some versions of the XFree86 server. WAVE normally uses dotted lines to draw annotation marker bars (enabled by selecting `markers' in the `View' panel); if these bars are not uniform for all annotations, your X11 server has this bug. As a work-around in this case, add the line 
	Wave.AllowDottedLines: False
to the `.Xdefaults' file in your home directory, or to the system-wide file `/usr/openwin/lib/app-defaults/Wave'.

Note that the WAVE binary for X11R5 is not up-to-date; in particular, it lacks the enhanced functions of the scope window, as described near the beginning of the "What's New" item in WAVE's on-line help, and most of the PC keyboard equivalents listed above. Since X11R6 servers are now standard in Linux installations, I do not plan to update the WAVE binary for X11R5.

Special considerations for XFree86 version 3.1.x (X11R6)

The precompiled XView 3.2p1-X11R6 binaries (available from sunsite.unc.edu, tsx-11.mit.edu, and many other sources, and included in the Slackware Linux 2.1 and 2.2 releases) do not properly render server images created from Sun icon files, as a result of byte ordering differences between Sparc and Intel processors. This bug affects most XView icons, cursors created as XView server images, and the XView spot help "magnifying glass". The version of WAVE on this disk correctly renders its icons, cursors, and spot help from architecture-independent X bitmaps; if you are currently using WAVE version 5.4 or earlier, you should install the version on this disk to correct this problem, and to be able to use new features of WAVE. Note that spot help for window decorations (title bars, borders, resize handles, and the like) is rendered via an external process (olwmslave), not by WAVE.

If you use `olwm' or `olvwm' (recommended) as your X11 window manager, or if you use other XView applications under Linux, you may wish to update your XView libraries so that these applications can also display icons, spot help, and other server images properly. The easiest way to do this is by installing WAVE and the DB Software Package first, then by unpacking the corrected Linux binaries in linuxmsc/xv32r6b.tgz (contributed by Alex Shah, ashah@scripps.edu). Follow the directions in the README file contained in this archive to install libxv3.so.3.0 (the shared library) and libxview.a (the statically linked library). Alternatively, you can unpack the sources in xview32.tgz, apply the patches for Linux in linuxmsc/xv32pat.tgz, and compile them (be sure to define the symbol `i386' when doing so, in order to avoid the server image rendering bug). It is not necessary to recompile XView applications after installing the corrected library unless they were statically linked to libxview.a.

The problem with rendering dotted lines appears to have been partially fixed in XFree86 version 3.1, at least when using a color or greyscale display. If you use WAVE and XFree86 on a monochrome display, or with the `-m' option to simulate monochrome output, you may need to disallow rendering of dotted lines as described for X11R5 above.

George B. Moody (george@mit.edu)
25 May 1997 (Links edited 11 November 1999 for PhysioNet)