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