SAMPLE(1)

NAME
sample - digitize and replay analog signals (MS-DOS only)

SYNOPSIS
sample [ options ... ] ]

DESCRIPTION

sample generates database records from analog signals, and generates analog signals from database records.

When used to digitize analog signals, the outputs of sample are one or more signal files and a header file. The record name, the number of input signals, the sampling frequency, the duration of the record, and the storage format may be specified interactively or by command-line options and configuration files.

When used to play back database records, the outputs of sample are one or more analog signals.

Options include:

-b  Batch mode (do not prompt to begin digitization or playback).

-d type
    Set up for use with the specified device. type must be one of `1200/2', `1200/2B', `1200/3', `1200/3B', `1200/4', `1200/4B', `2400/4', `2400/5', or `2400/6' (corresponding to Microstar DAP model numbers). Use a type ending with `B' only if you have a DAP 1200 series board configured for bipolar inputs. Use the option -d help to get a list of supported device types. If no -d option is given, sample uses the DAPL `hello' command to determine the device type automatically.

-f time
    Begin playback at the specified time (effective only in combination with the -i option).

-h  Print on-line help (a brief description of options).

-i record
    Play back the specified record (may not be used with the -n, -N, or -o options). Unless an analog output expansion board has been installed, and sample has been compiled with a suitably increased value of DAPOUTPUTS, or a DAPL program embedded in the header file for record (see below) specifies otherwise, playback is restricted to signals 0 and 1 only. Except when using `raw' format, the analog outputs are determined by the 12 least significant bits of each sample. (sample assumes that any record whose header file specifies format 16, ADC resolution 16, and all signals in the same signal file, is a `raw' format record.)

-n record
    Create the specified record (both signal and header files).

-N record
    Create a header file for the specified record, but do not digitize.

-o record
    Digitize, using signal specifications in the existing header file for record.

-p file
    Use the DAPL program in the specified file.

-s n
    Record or play back 1 of every n samples in each signal (not effective with `raw' format I/O, see below).

-t time
    Stop digitization or playback at the specified time.

-x n
    Digitize or play back at n times real time (n > 0; default: 1). This option is not effective with -p, or when the header file specified by -i or -o contains a usable DAPL program (see below).

-1  Play back only one signal (signal 0; effective only with -i).

ENVIRONMENT

It may be necessary to set and export the shell variable WFDB (see setwfdb(1)).

  HARDWARE REQUIREMENTS

sample runs under MS-DOS on an ISA-bus (AT-bus) system that contains a Microstar DAP 1200 or 2400 series board (available from Microstar Laboratories, http://www.mstarlabs.com/). All DAP 1200 and 2400 series boards listed below include 12-bit analog-to-digital and digital-to-analog converters, analog multiplexers, programmable gain amplifiers, timers, and an Intel 80186 CPU; DAP 2400 series boards include a Motorola 56001 DSP and provisions for external triggering. All models have 8 differential (16 single-ended) analog inputs and 2 analog outputs, and 16 bits each of digital inputs and outputs. With expansion boards, a single DAP can have up to 256 differential or 512 single-ended analog inputs, 66 analog outputs, and 128 bits of digital input and output; it is also possible to use up to seven DAP boards in a single system.

The range of sampling frequencies available depends on the model. DAP 1200/2 and 1200/3 boards can digitize at aggregate rates of 31.25 to 50,000 Hz; for DAP 1200/4 and 2400/4 boards, the range is 38.46 to 156,000 Hz, and for DAP 2400/5 and 2400/6 boards, the range is 62.5 to 235,000 Hz. Although several hundred thousand samples can be acquired at the maximum input sampling frequency, the maximum sustained throughput to disk is considerably lower than the maximum sampling frequency specifications imply; using a 12 MHz 286-based system, a DAP 2400/5, a disk controller with 256K of cache, and a 16 msec disk, for example, the maximum sustained throughput is about 25 KHz (100 KHz using `raw' format, see below). The minimum sampling frequencies listed above refer only to those obtainable using the on-board timer and the DAPL program generated by sample (see below); if necessary, slower sampling can be achieved using an external clock with DAP 2400 boards, or by writing a special-purpose DAPL program.

The DAP 2400 is much better suited for playback than is the DAP 1200. Each of the two analog outputs of the DAP 1200 can accept samples at 1, 2, 5, 10, 25, 50, 125, or 250 Hz, but not at any other rates. Note that sample generates DAPL code for playback on DAP 2400 boards only, although DAP 1200 playback code can be provided by the user at run time if necessary (see below). sample can generate analog signals using a DAP 2400 at sustained rates up to about 3 KHz; much faster output (up to 250 KHz with a DAP 2400/6) is possible for short intervals (up to the amount that can be loaded into the DAP's local memory).

Microstar Laboratories produces DAP boards that do not include analog-to-digital or digital-to-analog converters; sample is not intended for use with these boards, which have model designations ending in `D'. DAP boards with protected analog inputs have model designations ending in `P'; these boards have slightly lower maximum sampling rates than the corresponding standard models.

Successful digitization always requires that the analog inputs be band-limited so that there is essentially no power at frequencies in excess of half of the sampling frequency. In almost all cases, this means that you must use properly designed analog antialiasing filters between the signal source and the DAP inputs. Before assuming that your inputs are band-limited because of known characteristics of the signals, consider carefully if your noise is also band-limited - it's probably not!

During playback, you may wish to use similar low-pass filters to reduce the `staircase' effect characteristic of signals generated by D/A converters.

sample has been tested using DAPL version 3.3; the digitization and single-channel playback functions have also been tested using DAPL version 3.2 (note that the multi-channel playback code generated by sample uses the `separate' command, which is new in DAPL 3.3).

  PERFORMANCE HINTS

sample uses the WFDB library functions getvec and putvec to read and write signal files. When digitizing, the advantages of using putvec are that it permits the use of a variety of standard, compact storage formats, and that it calculates signal checksums that are used subsequently by other WFDB applications to verify the integrity of the signal files. During playback, the use of getvec permits sample to read any existing WFDB record without the need to reformat it. When digitizing or playing back `raw' format records (compatible with Microstar's DAPview or DLOG binary files), getvec and putvec are bypassed with low-level read and write calls for maximum speed. A side effect of using `raw' format in digitization is that the generated header files for newly created records lack sample counts and checksums, since these are produced only by putvec. `Raw' format files can be converted to any standard (`cooked'?) WFDB signal file format using xform, which will generate sample counts and checksums. When using xform on `raw' format files, it is advantageous to set its output signal gains to 1/16 of those specified in the header file for the `raw' format record, in order to obtain right-justified 12-bit samples (DAP `raw' format consists of 12-bit samples left-justified in 16-bit words). If both sample and xform are allowed to use their default gain settings, this scaling is performed automatically by xform.

  COMPILATION

Please read this entire section before trying to compile sample!

To compile sample successfully, you will need Microsoft C, version 5.0 or later, or Turbo C/C++, and four files supplied by Microstar with all versions of the DAP 1200 and 2400 (Microstar's Advanced Development Toolkit is not required in order to compile or use this program). These files are c_lib.c, clock.h, and ioutil.h, which should be installed in a directory searched by your C compiler for #include <...> files (for Microsoft C, one of the directories specified by the INCLUDE environment variable); and cdapl.lib, which should be installed in a directory searched by your C compiler's link utility for libraries (for Microsoft C, one of the directories specified by the LIB environment variable). If you are using Microsoft C, copy cdapl5.lib from the Microstar distribution diskettes into your library directory and rename it cdapl.lib.

If you have not already done so, you must also compile and install a large memory model version of the WFDB library (see Makefile.dos in the lib directory). Although the program compiles and links successfully using the small memory model and Microstar's cdaps5.lib, there is apparently a bug in cdaps5.lib that wedges the DAP (a condition that can be remedied only by power-cycling the system).

If you have installed one or more analog expansion boards, modify the values of DAPINPUTS and DAPOUTPUTS as appropriate (see sample.c). Note that these constants specify the number of available inputs and outputs, not the number of signals that can be digitized or played back at once using sample (which imposes no fixed limits if compiled with WFDB library version 10.2 or later).

Efficiency, hence maximum output rate, is improved by using large I/O buffer sizes. By default, sample uses 10K-byte buffers; depending on your system's available memory and your disk controller, you may be able to improve your throughput by adjusting this value. Do so by redefining the symbol DBUFSIZE. Note that the default buffer size is overridden at run time by explicit (non-zero) block size specifications in the header file, if present (see header(5)).

This program has been successfully compiled and tested using Microsoft C 5.1, 6.0, and 7.0, with the command
    cl -Ox -Ml sample.c -link wfdbl cdapl
and using Turbo C 2.01, and Turbo C++ 1.01, with the command
    tcc -O -A -ml sample.c wfdbl.lib cdapl.lib
Note that you may need to use -I and -L options to instruct your compiler where to find #include files and libraries; see your compiler manual for further information. The symbols DAPINPUTS, DAPOUTPUTS, and DBUFSIZE may be redefined using command-line -D options with any of these compilers. If you compile using Microsoft C/C++ 7.0 (or later) with the -Za (ANSI C) option, add oldnames as a final command-line argument, to link a library containing aliases for functions such as open(), which have been renamed in the standard MSC 7.0 library to conform with ANSI namespace rules.

  DAPL Programs

DAP boards are controlled by programs written in Microstar's DAPL (DAP language), which are downloaded to the on-board 80186 for execution. sample follows this procedure for obtaining the DAPL program to be used:

1.  If you use the -p option to specify the name of a DAPL file, sample downloads the contents of that file. The first line of the file should contain a DAPL comment line of the form `; start a,b', which specifies the DAPL command required to begin execution of the program once it has been downloaded. If this line is missing, sample uses the command `start a'. Unless the DAPL file is unreadable or empty, sample skips steps 2 and 3, and the -x option has no effect.

2.  If you use the -i or -o options to specify the record name of an existing header file, sample will read info strings from the header file. If -i has been specified, and any of the info strings begin with `<', the initial `<' character in each such string is discarded, and the remainder is treated in the same manner as for a DAPL program specified using -p. Similarly, if -o has been specified, sample compiles the DAPL program from any info strings beginning with `>'. If sample finds any DAPL code in this step, it does not execute step 3, and the -x option has no effect.

3.  If sample has not obtained a DAPL program in steps 1 or 2, it generates one based on the signal specifications obtained from the header file read in step 2, if any, or interactively from the user. If specifications for digitization are obtained from a header file without an embedded DAPL program, sample assigns differential inputs D0, D1, ... to signals 0, 1, ..., provided that the number of signals does not exceed DAPINPUTS/2; otherwise, sample assigns single-ended inputs S0, S1, ... to signals 0, 1, .... Digital inputs (input `B') may be specified in a DAPL program or interactively. In playback mode, sample generates DAP 2400-compatible code only; to play back a record using a DAP 1200, you must supply DAPL code either in the header file or using -p.

When sample is used to create a record, it writes a copy of the DAPL program that it uses into the newly-created header file, as a set of info strings formatted as described in step 2 above. By using the -N option, a DAPL program may be written into a prototype header file without actually digitizing any signals. This is an easy way to bootstrap the design of a custom DAPL program for use with sample. Custom DAPL programs may be used for applications that perform operations such as digital filtering on-the-fly, or for low frequency sampling.

An example of a header file with a moderately complex embedded DAPL program is sample8.hea, in the app directory of the WFDB software package.

  DISCLAIMER

Please note that the author has no connection with Microstar Laboratories other than as a satisfied customer; specifically, neither MIT nor the author assumes any responsibility whatsoever for the performance of Microstar hardware or software.

BUGS
If no -d option is given, sample displays the diagnostic message ``Testing DAP ...'' briefly before printing the DAP type. If sample cannot establish communications with the DAP, however, it will stop after displaying the ``Testing DAP ...'' message; in this case, it is usually necessary to power-cycle the DAP (a system reset is usually not sufficient) in order to restore communications. This behavior of sample is not a bug in itself; the DAP board can be put into this uncommunicative (i.e., wedged) state by sample and other programs, however. The most likely reasons for the DAP to become wedged are attempting to use sampling frequencies that are too high (especially for playback) or improperly constructed custom DAPL programs in header files. It is also possible to run DAPL programs that take a very long time to execute; in this case, it may be difficult to know if the DAP is running or wedged.

SEE ALSO
setwfdb(1), xform(1), header(5)

AUTHOR
George B. Moody (george@mit.edu)

SOURCE
http://www.physionet.org/physiotools/wfdb/app/sample.c