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:
The shell variable DB should be set and exported (see setdb(1) ).
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).
sample uses the DB 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 DB applications to verify the integrity of the signal files. During playback, the use of getvec permits sample to read any existing DB 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'?) DB 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.
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 DB 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 (determined by MAXSIG, defined in <ecg/db.h>). If you need to digitize a larger number of signals than is permitted by the current value of MAXSIG, modify the definition of MAXSIG in the copy of db.h that is in the lib directory, and recompile the DB library (as well as any applications that you wish to use with records created by sample).
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 dbl cdapl
and using Turbo
C 2.01, and Turbo C++ 1.01, with the command
tcc -O -A -ml sample.c dbl.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.
If you tell install (the MS-DOS installation program for the DB software package) to compile sample using Microsoft C, install looks for cdapl5.lib, and uses it in preference to cdapl.lib if both are present (thus you can have DAP libraries for both Microsoft C and Turbo C installed at the same time). install also detects the presence of oldnames.lib and adds it to the command line if necessary.
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:
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 DB software package.
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.