Setting up WVSCRIPT

This document describes how to set up wvscript, a ``wrapper'' for WVIEW that provides Windows users with some of the functionality that wavescript and WAVE provide to Linux, Solaris, and SunOS users. Specifically, wvscript can be installed as a viewer for your Web browser and for Windows 95 Explorer by following the steps outlined below. Once you have done so, you can follow links such as this one:

If you are using Windows 95 and Netscape 3.x, you should be able to follow the steps exactly as shown here. If you use another version of Windows or another browser, you will need to adapt these instructions to your situation. If you use Linux, Solaris, or SunOS, then use WAVE and wavescript, not WVIEW and wvscript.

Installing WVSCRIPT

If you have not already done so, download wvscript.exe and save it in a directory in your command execution path (such as the directory where you previously installed wview.exe). If you prefer, you can compile wvscript.exe from the source, wvscript.c.

Adding the xws file type to the Windows registry

Double-click on the My computer icon, and open the Options dialog box (from the View menu). Click on the File Types tab, and on the Add new type... button. The Add New File Type dialog appears.

Fill in the text fields of this dialog box exactly as shown above. (Note that the MIME type is application/x-wavescript, not application/x-wvscript.) When you have finished, define an action by clicking on New.... The New Action dialog appears.

Again, fill in the text fields as shown. If you did not install the WFDB applications in c:\bin, provide the correct path to wvscript. When you have done so, click on OK.

Optional: If you wish to set the icon for xws files, click on Change Icon... in the Add New File Type dialog. A warning message will appear when you do so:

Dismiss the message box by clicking on OK. The Change Icon dialog appears.

Enter the path to the WVIEW executable file (normally as shown above), then click on OK.

To record your changes, click on OK in the Add New File Type dialog box. Once you have done so, try out wvscript and WVIEW by opening the directory in which this page of instructions is found using Windows Explorer. Within Explorer, double-click on the file example.xws; this should cause an MS-DOS window to appear briefly (when wvscript runs); WVIEW should then display record 100s, with annotator atr, beginning at 0:22 (as specified in example.xws). If this does not happen, check the previous steps carefully and correct the problem before continuing.

Registering wvscript as a Netscape helper

Start Netscape. Open the Preferences dialog from the Options menu, and click on the Helpers tab.

Click on Create New Type... to open the New Type dialog.

In the New Type dialog, specify application as the MIME type, and x-wavescript as the MIME subtype; then click on OK.

In the Preferences dialog, select Launch the Application as the action, and enter the correct path for the wscript executable, as shown below.

When you have finished, click on OK to register your changes. You may now test your setup by clicking on the icon below:

The first time you do this, Netscape may open a message box to warn you that running software from untrusted sources may compromise your system's security. This warning may be safely ignored in this case.

Note for Netscape Communicator 4.0 users

The procedure for adding a helper application is slightly different than shown above if you are using Netscape Communicator 4.0, since the menus have been reorganized. The Preferences dialog is now opened from the Edit menu. Select Navigator/Applications from the Preferences dialog to open the Helpers page, then click on New Type to open the New Type dialog.

The New Type dialog for Netscape 4.0 contains these fields:

Description of type

enter WAVEScript, or any other description of your choice

File extension

enter xws

MIME Type

(rather than separate type and subtype fields) enter application/x-wavescript

Application to use

enter c:/bin/wavescript.exe

After filling in these fields, click on the OK buttons in the New Type and Preferences dialogs to register your changes.

How wvscript works

To embed a link such as those shown above in your own web pages, simply insert HTML code such as:

    <a href="example.xws">
    <img src="wave.png" alt="click here to view waveforms"></a>

The file example.xws, to which this link refers, is a text file that looks like this:

    # file: example.xws
    #
    # Sample `wavescript' script.  Use this script by the command
    #    wavescript example.xws
    # (under UNIX), or
    #    wvscript example.xws
    # (under MS-Windows).
    #
    # The first character in each action line in a wavescript script begins with
    # a `-';  any other lines are ignored.  Only one action may appear on any line.
    -r 100s
    -a atr
    -f 0:22

The contents of example.xws specify the record to be opened (in this case, 100s), the annotator to be opened (in this case, atr), and the starting time of the segment to be displayed (in this case, 0:22).

When wvscript is invoked (whether by Netscape, Windows Explorer, or from the command line) it reads the script file named by its first command-line argument, extracts the record name, annotator name, and starting time, and invokes WVIEW. If the annotator name is not specified in the script, wvscript uses `-' as the annotator name passed to wview; this special ``annotator'' is ignored by WVIEW. The source for wvscript (wvscript.c) may be found in the app directory of the WFDB Software Package, if you wish to modify it.

Note that the syntax of wavescript scripts allows for more than one record to be specified, using an action line of the form

    -r 100+101+102

Although WAVE (under UNIX) can open more than one record (in this case, it would open records 100, 101, and 102 in separate windows), WVIEW cannot do this. wvscript identifies the first record name in such an action line, and invokes WVIEW so as to open that record only.

Multiple instances of WVIEW: use with caution

Another difference between UNIX wavescript and Windows wvscript is that wvscript will always launch a new instance of WVIEW even if WVIEW is already running, whereas wavescript starts a new WAVE process only if WAVE is not already running. Multiple instances of WVIEW running at the same time can interfere with each other and should generally be avoided.

Only one instance of WVIEW can be run reliably at a time, because of limitations in using 16-bit large memory model DLLs such as the version of the WFDB library used by WVIEW. For this reason, you should normally be careful to exit from WVIEW before starting another copy of it, whether from Netscape, Windows Explorer, or the command line.

It is possible, however, to run multiple copies of WVIEW, provided that all copies have the same record and annotator (if any) open. This can be useful if you wish to compare two or more segments of a record side-by-side, and it is for this reason that multiple instances of WVIEW are allowed. If you use this feature, close (iconify) any instances that are no longer needed, rather than quitting (exiting). To exit cleanly, make sure that all instances have been closed, then quit each instance without reopening the window (this is necessary since repainting the window requires rereading the signal and annotation files, which cannot be done once they have been closed by the action of quitting any instance of WVIEW).

If you encounter problems related to interference between simultaneous instances of WVIEW, the only solution may be to use the Windows Task Manager to quit from all instances of WVIEW. If necessary, you can open the Task Manager window by pressing the Control, Alt, and Delete keys simultaneously (if your system has become unresponsive, wait for up to 20 seconds, then press Control, Alt, and Delete once again).