Back to the Basement Computing Page
 

Documentation
 

Index
 
ASCII Table
AudMat
AudSDK
Basement Blog
BC - Behaving Cat
COM Data Collection
COMA Data Analysis
Correcting GW for phone
CSF format
DAFLIB
Data Schemas
DCP - Introduction
DCP - Tech Notes
DCP - Users Guide
DCPLIB
DSS-III Notes
DSS-III Prototype
DSSLIB
DSS3LIB
DSS4LIB
DSS4FLIB
Effective SPL computation
EP - Evoked Potential
Error Codes
Falling Cost of Computing
FF - Free Field
Fortran and C/C++ mix
GWE - Waveform Editor
Local FAQs
Mathematical Formulae
Minicomps. & Neurophys.
MISLIB
Numerical Constants
NUMLIB
PIN - Edge/Notch
PIN - Summary
Probe Tube Correction
RA - Introduction
RA - Tech Notes
RA - Users Guide
RAP - Users Guide
Rayleigh Test
SER - Search Stimulus
SERCOM - COM Search
Signal Analysis Review
Simulating Free Space
STATPK - Introduction
STATPK - Tech Notes
STATPK - Users Guide
Status Table Formats
SysInfo
 
Disclaimer
 
DSS4FLIB - Data Acquisition Library
Quick Links
Introduction
Usage
Description of Routines
Examples of Use
References
Feedback
Acknowledgements

Ravi Kochhar
Dept. of Physiology
University of Wisconsin - Madison
Nov. 23, 2004
rev. 1.02, Aug. 31, 2010
Technical Report no. 22

Introduction

DSS4FLIB is a library of routines for use with data collection hardware. At present it includes functions for controlling the Data Translation DT-321 Analog-to-Digital (A/D) converter, the Wisconsin Digital Stimulus System (DSS-4) and the Wisconsin Unit Event Timer (UET) as well as the Wisconsin Rate Generator and Timers. These are all essential components for data collection at the UW Auditory Physiology Labs. Additional routines for the Auditory Lab are available in DSS4LIB (DSS-4 and UET control), DAFLIB (data storage and retrieval), NUMLIB (numerical), DCPLIB (data collection), DSSLIB (hardware control) and PLTWIN and PLTMFC (graphing and plotting).

This document contains a description of the routines in DSS4FLIB as well as suggestions for how to use them. It is a work in progess, so not all routines may be listed here.

Some of the routines in DSS4FLIB are simply wrappers for functions in DSS4LIB, and this is done mainly to make them callable from Fortran as well as C/C++. You may need to consult the DSS4LIB documentation in those cases, which are noted below in the descriptions of individual functions.

All the functions/routines in DSS4FLIB are Windows (NT/2000/XP or later) compatible. They will not work on VMS or any other platform.

Back to Top

Usage

The library is available as a Windows static library in dss4flib.lib, which is part of the Auditory SDK (AudSDK). Before using for the first time, you should check if AudSDK is installed, and install it otherwise from: http://www.neurophys.wisc.edu/ftp/pub/audstuff/windows/audsdk/. (If there is a folder named "c:\program files\audstuff\audsdk" on your hard drive, then most likely AudSDK is already installed).

The next step is to tell MS Visual Studio to include this library during the link process. This is done as follows:

When linking with a MS Visual Studio project (e.g.) you should select Project -> Settings -> Link Tab. Then select Category -> Input and in the "Additonal library path" field, enter "$(audsdk)" and in the "Object/library modules" field, insert dss4flib.lib at the beginning of the list of libraries for the current project.

You will also need to include the header file dss4flib.h at the start of your C or CPP file. This is done as follows:

        #include "dss4flib.h"

and then specify the path in the project settings as follows:

In MS Visual Studio, select Project -> Settings -> C/C++ tab. Then select category -> Prepocessor and in the "Additional include paths" field, enter $(audsdk), or append it to what is already there.

In some of the routines described below, an error code value NER is returned. The value of NER indicates whether the routine completed successfully or whether an error condition was detected. In all cases, a value of NER=0 indicates successful completion. If NER is non-zero, it can indicate a variety of problems. A complete list of error code descriptions can found in file c:\audstuff\d\error.txt or in <path where audsdk installed>\error.txt

All integer arguments must be declared type INTEGER (Fortran) or int (C/C++). In Win32 this means 4-byte integers. In a few cases the integer arguments must be explicitly declared as INTEGER*2 or as INTEGER*4. These cases are mentioned with each routine where applicable.

The routines may be called from from either C/C++ or Fortran. When calling from C/C++ the case(upper/lower) of routine names must be preserved.

Examples of use are provided in a separate section below.

See below for a detailed description of the arguments of these routines.

Back to Top

Description

Part-I    A/D functions


	int OPENAD() 

	Open/Initialize the A/D converter

        This should be the first function called, before any other
        A/D functions are called. It opens a connection to the
        Data Translation A/D.

        Normally you need to call this only once. After that the
        A/D can be started and stopped multiple times. You must
        call OPENAD() again if you call CLOSAD() or if you 
        exit and retstart the program.

        A return value of 0 indicates success. Other codes are
        described in the error.txt file.

        Notes: 
        (1) Call CLOSAD() before terminating the program.

        Compatibility: C/C++ and Fortran
        Hardware: Data Translation model DT-321 A/D
        Header: dss4flib.h
        Link: dss4flib.lib


	int INITAD(int *iREnable,float *fpRate,int *iNumBuf,
                    int *iNumS,int *iTrigMode)

	Initialize A/D with sampling params and prepare for sampling.

        iREnable   : Rate Gen. mode. If=1 then use external rate gen, 
                     if=2 then on-board.
        fpRate     : Sampling rate (samples/sec) (floating point)
        iNumBuf    : Number of memory buffers to use (usually 1)
        iNumS      : Number of samples to acquire
        iTrigMode  : Start mode, if=1 then software start, 
                     if=2 then external start

        All parameter values must be supplied by the user.
        For normal applications, iREnable should be 1, and the 
        external Rate generator should to be connected to the 
        BNC connector labeled "A/D Clock" on the A/D front panel. 
        Also, for normal applications, iTrigMode should be 
        specified as 2, and the external start cable should be 
        connected to the BNC labeled "A/D Trigger" on 
        the front panel.

        The return value is "0" for success. A non-zero return
        indicates error or failure. See error.txt for details.

        Notes: 
        (1) You must call INITAD() once for each sampling episode.
        (2) OPENAD() must be called at least once before INITAD()
        (3) The upper limit on the value of iNumS is 500,000. 
        (4) The upper limit on the sampling rate is 
            250,000 samples/sec. This is a hardware limitation of 
            the DT-321 A/D converter.
        (5) iNumS is the overall number of samples for all channels.
            If 2 channels are sampled, e.g., then there will be 
            iNumS/2 points per channel.
        (6) The channels to be sampled should be specified with 
            ADSETCHAN() which should be called after INITAD()

        Compatibility: C/C++ and Fortran
        Hardware: Data Translation model DT-321 A/D
        Header: dss4flib.h
        Link: dss4flib.lib

	int ADSETCHAN(int* iNumChan,int* iChanList) 

	Set A/D channel numbers

        iNumChan   : Number of Channels to use (normally 1)
        iChanList  : List of channel numbers (integer array)

        Both iNumChan and iChanList must be provided by the user.
        iNumChan is the number of entries in "iChanList".
        iChanList is an integer array that holds the channel
        numbers (and the order in which they are sampled).
        For example, to sample just one channel (channel 0),
        set iNumChan to 1, and the first element of iChanList to 0.
        To sample two channels (channels 0 and 3), set iNumChan
        to 2, and set iChanList[0]=0 and iChanList[1]=3.

        The return value is "0" for success. A non-zero return
        indicates error or failure. See error.txt for details.

        Notes: 
        (1) You must call ADSETCHAN() even if only channel 0 alone
            is to be sampled.
        (2) OPENAD() and INITAD() must be called before ADSETCHAN()
        (3) The upper limit on the value of iNumChan is 1024. 
            This is much larger than the actual number of 
            A/D channels, which is 8. You can specify the same 
            channel more than once. For example, to sample 
            channel 0 twice as often as channel 3, specify 
            iNumChan=3, and iChanList[0]=0, iChanList[1]=0 and
            iChanList[2]=3.
        (4) Only one channel is sampled per trigger (from the rate 
            generator). Thus, if you specify two channels, and a 
            sampling rate of 1000, the actual rate will be 
            500 samples/sec per channel. If you really meant to 
            sample at 1000 samples/sec, then multiply the sampling
            rate by the number of channels.
        (5) As per note (4) above, there can be a time shift between 
            the channels proportional to the sampling interval. 
            If two channels are sampled at 500 samples/sec (each), 
            the time shift is equal to 1/500 = 2 millisecs.
        (6) The A/D channels are numbered from 0 to 7 
            (for a total of 8 channels)

        Compatibility: C/C++ and Fortran
        Hardware: Data Translation model DT-321 A/D
        Header: dss4flib.h
        Link: dss4flib.lib


	int CLOSAD() 

	Closes the A/D converter

        This should be the last function called, after all A/D
        sampling has been completed. It closes the connection
        that was opened by INITAD().

        A return value of 0 indicates success. Other codes are
        described in the error.txt file.

        Notes: 
        (1) If you must sample again after calling CLOSAD()
            then start by calling INITAD() again.

        Compatibility: C/C++ and Fortran
        Hardware: Data Translation model DT-321 A/D
        Header: dss4flib.h
        Link: dss4flib.lib


Back to Top

Examples of Use

The following are examples of C and FORTRAN programs used to fetch some basic information from a data file and a data set. In these examples the checking for error codes (NER) has been omitted for brevity. In a real case, you should always check the value of NER after every call to a MISLIB routine which returns NER.

<...The examples will be added in a future version...>

Back to Top

References

  1. "DSS4LIB - DSS-4 and UET routines for Windows", Jane Sekulski, 2003.
  2. "AudSDK Error Codes", Ravi Kochhar, Technical Report no. 23, Nov. 2004.

Back to Top

Feedback

Please send feedback/suggestions/questions/complaints to the author via email, at kochhar@physiology.wisc.edu

Back to Top

Acknowledgements

This work was done at the University of Wisconsin - Madison under the direction of Dr. W.S.Rhode. Supported in part by a grant from NIH.

(This page last modified on Aug. 31, 2010)

 
Back to Top
Back to The Basement Computing Page
Back to The Basement

Please send questions, complaints or comments to rkochhar@wisc.edu