Technical Report no. 13 Ravi Kochhar
April 9 1991 Department of Physiology
Rev. 1.04, Aug. 8 2000 University of Wisconsin
(rep013) Madison, Wi. 53706
TABLE OF CONTENTS
-----------------
(1) INTRODUCTION
(2) ACKNOWLEDGEMENTS
(3) USAGE NOTES
FUNCTIONAL GROUPING
(4) DESCRIPTION
AVRG(NCHAN,NUMAV,NSTART,RATE,NP,BUF,NER)
CALDIR(NPHON,ENTRY,NER)
CHVEC(CSTR,NC,IVEC,NW,NER)
CLOCSF(NER)
DWIF(ICBLK,NER)
ERMSG(NER,NPR,LUN)
GDATE(CDATE,NER)
GETUS(CID,NUNIT,NSEQ,NER)
GTIME(ITIME,NER)
GWRD(FNAME,LUN,ID,X,MAX,NP,TINT,KODE,NER)
GWRD2(ID,X,MAX,NP,TINT,KODE,NER)
GWRD3(NSEQ,X,MAX,NP,TINT,KODE,ID,NER)
GWSTOR(FNAME,LUN,ID,X,NP,TINT,KODE,NER)
GWSTOR2(LUN,ID,I2X,NP,TINT,KODE,NER)
INICSF(LUN,NER)
IPTERM(PNAME,NER)
LCSPL(NSS,F1,F2,RNGMAX,DBMAX,RNGDB,NER)
LHSPL(NPHON,F1,F2,SMAX,SMIN,NER)
MICSEL(N,NER)
MOTORS(N,NDIR,NSTEP,NWAIT,NER)
NEWID(KODE,OLDID,MASK,NEW,NER)
PHSCAL(NPHON,FREQ,PHAS,NER)
PHSTAB(NPHON,PHAS,MAX,NPHAS,NER)
QCSPL(NSS,F1,F2,RNGMAX,DBMAX,RNGDB,NER)
SPLMAX(NPHON,FREQ,MAXS,NER)
SPLTAB(NPHON,SPL,MAX,NSPL,NER)
STBDEL(NAMSTB,LUN,NER)
STBEN1(VARV,NV,NPT,NP,NER)
STBEN2(NX,NY,NPT4,NP,NER)
STBINI(NAMSTB,LUN,NTYP,NBLK,NV,NP,EDF,DSID,NY,NER)
STBINII(NAMSTB,LUN,NTYP,NBLK,NV,NP,EDF,DSID,NY,NER)
STBOPN(NAMSTB,LUN,NER)
STBTR(NAMSTB,LUN,LEDF,LOC,NSZW,NER)
WCBUF(ICBLK,NER)
(5) REFERENCES
(1) INTRODUCTION
DCPLIB is a library of routines on the VAX/VMS computer
that is used with most data collection and storage programs.
The routines are of a general enough nature that they are useful
with more than one application.
This report is a description of the routines in DCPLIB.
They may be linked with any program by specifying L:DCPLIB/L in
the LINK statement when linking a program. For example :
:
$ LINK myprogram,L:DCPLIB/L
:
(2) ACKNOWLEDGEMENTS
This work was done under the direction of Dr. W.S. Rhode,
and also benefited from the comments of the many users of the
Neurophysiology Auditory Laboratory. Support provided in part by
Grant XXXXXX from NIH.
(3) USAGE NOTES
The routines described below all exist in the library
DCPLIB, which can be included in your program at link time by
including L:DCPLIB/L in the LINK statement. In a few instances
(noted with the particular routines below) another library also
needs to be linked in. The second library should be specified
after DCPLIB in the LINK command. For example, to use routine
GWRD, you need to include DAFLIB as well. This should be done as
in the following example :
$ LINK myprog,L:DCPLIB/L,L:DAFLIB/L
All the parameters in the descriptions below follow the
FORTRAN typing convention (unless otherwise noted), i.e. names
that begin with I through N are assumed to type Integer*4 (32-
bit integers), all others are assumed to be single-precision
floating point variables.
The routines can be called from any program written in any
VAX standard language (e.g. FORTRAN, C, PASCAL etc.). When using
FORTRAN, use the CALL statement, e.g. CALL MICSEL(N,NER).
The routines all return a status (or error) code in
variable NER. The value of NER should be checked after each call
to the routines. A value of 0 (zero) indicates the routine
completed normally with no error. Any other value indicates some
other condition. The routine ERMSG (described below) can be used
to obtain a detailed description of the error code.
A few of the routines require that a file name be passed
as an integer array with the last byte (or word) set to zero.
This can be done easily as in the following FORTRAN example :
INTEGER FNAME(11)
:
READ(5,20) (FNAME(L),L1=1,10)
20 FORMAT(10A4)
FNAME(11)=0
CALL STBOPN(FNAME,LUN,NER)
:
FUNCTIONAL GROUPING
(a) Routines for GW file access
GWRD, GWRD2, GWRD3, GWSTOR, GWSTOR2.
(b) Routines for Calibration Table access
CALDIR, CLOCSF, INICSF, LCSPL, LHSPL, PHSCAL, PHSTAB, QCSPL,
SPLMAX, SPLTAB.
(c) Routines for STATUS Table access
STBDEL, STBEN1, STBEN2, STBINI, STBINII, STBOPN, STBTR.
(d) Routines for Inter-Process Communication
DWIF, IPTERM, WCBUF.
(e) Hardware Control Routines
MICSEL, MOTORS.
(f) Data Storage Routines
CHVEC, GDATE, GTIME, NEWID.
(g) Misc. Routines
AVRG, ERMSG, GETUS.
(4) DESCRIPTION
AVRG(NCHAN,NUMAV,NSTART,RATE,NP,BUF,NER)
Sample and average the signal applied to channel NCHAN of
the Analog-to-Digital (A/D) converter.
NCHAN : Channel number of the A/D (0 to 7)
NUMAV : Number of averages (1 or more)
NP : Number of points to sample/average
NSTART : Start input channel number of the rate generator
RATE : Sampling rate (samples/sec)
BUF : Array to hold averaged values
NER : Error code, normally zero
NCHAN, NUMAV, NP, NSTART and RATE must be supplied by the
calling program, while BUF and NER will be returned. The values
in BUF are returned in units of volts. You must connect the
signal to be sampled to channel NCHAN of the A/D converter, and
connect the external start pulse for averaging to channel NSTART
of the Rate Generator.
The library L:DSSLIB must also be linked along with
DCPLIB.
CALDIR(NPHON,ENTRY,NER)
Read the "directory entry" for the specified phone from
the Calibration Storage File (CSF).
NPHON : Entry (phone) number to be read.
ENTRY : 16 word integer*4 array to hold entry
NER : Error code, normally zero.
The value of NPHON must be supplied, while ENTRY and NER
will be returned. Routine INICSF must be called before calling
this routine.
For a description of the contents of each directory entry
in the CSF, see Ref. no. (5)
CHVEC(CSTR,NC,IVEC,NW,NER)
Form a "character vector" from the specified character
string.
CSTR : Character string (type character)
NC : No. of characters in CSTR
IVEC : Integer array to hold character vector (type character)
NW : No. of words in IVEC
NER : Error code, normally zero.
CSTR and NC must be supplied by the calling program, while
IVEC, NW and NER will be returned. The first 16 bits of IVEC
will hold the length of IVEC while the remainder will hold the
non-blank portion of CSTR. IVEC must be dimensioned to at least
NC/4.
CLOCSF(NER)
Close the Calibration Storage File (CSF), which was opened
by routine INICSF.
NER : Error code, normally zero.
For a description of the CSF, see ref no. (5)
DWIF(ICBLK,NER)
Determine where initiated from. This routine reads the
"Per Process Common Block" and returns it in array ICBLK.
ICBLK(1) determines where the program was initiated from. If
ICBLK(1) 0 then the routine zeroes out the first word in the per
process common block.
ICBLK : 63-word integer array. Will contain the communications
flags on return.
NER : Error code, normally zero.
Both ICBLK and NER are returned by this routine
ERMSG(NER,NPR,LUN)
Display detailed error message on terminal screen
corresponding to error code number NER.
NER : Error code number
NPR : Logical unit for output message (usually 6 for terminal)
LUN : Logical unit number to use for error file
The user must supply all parameters, NER, NPR and LUN.
This routine reads the error messages from the error file,
which is D:ERROR.TXT on the VAX.
A typical use of this routine is within a program where
other routines that return error codes as NER are being called.
For example :
:
CALL GWRD(.........,NER)
IF(NER.NE.0) THEN
CALL ERMSG(NER,6,11)
CALL EXIT
ENDIF
:
GDATE(CDATE,NER)
Get the current Date, in the format DD-MMMYY
CDATE : Current date (type character)
NER : Error code, normally zero.
Both CDATE and NER are returned by this routine, nothing
need be supplied. The format DD-MMMYY is the required format for
storing dates in headers of all data sets.
GETUS(CID,NUNIT,NSEQ,NER)
Extract the Unit number and Sequence number from specified
DSID.
CID : Data set ID (type character)
NUNIT : Unit number
NSEQ : Sequence number
NER : Error code, normally zero.
CID must be supplied, while NUNIT, NSEQ and NER will be
returned.
It is assumed that the Unit and Sequence numbers are separated
by a dash, and that the Unit number occurs before the sequence
number. Non-numeric characters (other than the dash) in the DSID
are ignored.
GTIME(ITIME,NER)
Get the current time, in tenths of seconds since midnight.
ITIME : Time in tenths of seconds (Integer*4)
NER : Error code, normally zero.
Both ITIME and NER are returned by this routine.
GWRD(FNAME,LUN,ID,X,MAX,NP,TINT,KODE,NER)
Read in a GW waveform from a file into the user array X.
FNAME : Data File name (type character)
LUN : Logical unit number to be used for file
ID : 12-character Data Set ID (type character)
X : Single precision floating point array to hold waveform
MAX : Max. no. of values X can hold (i.e. dimension of X)
NP : Number of values actually read into X
TINT : Time interval between successive values in X (microsecs)
KODE : Waveform type code (e.g. 11=Gaussian noise)
NER : Error code, normally zero.
FNAME, LUN, ID and MAX must be supplied. All other
values are returned by this routine.
Note : You also need to link L:DAFLIB along with DCPLIB to
use this routine.
GWRD2(ID,X,MAX,NP,TINT,KODE,NER)
Read in a GW waveform from a file into the user array X.
This routine is similar in every way to GWRD, except that here,
the file is assumed to have been opened earlier by a call to
routine INITDF or equivalent.
ID : 12-character Data Set ID (type character)
X : Single precision floating point array to hold waveform
MAX : Max. no. of values X can hold (i.e. dimension of X)
NP : Number of values actually read into X
TINT : Time interval between successive values in X (microsecs)
KODE : Waveform type code (e.g. 11=Gaussian noise)
NER : Error code, normally zero.
ID and MAX must be supplied. All other values are
returned by this routine.
Note : You also need to link L:DAFLIB along with DCPLIB to
use this routine.
GWRD3(NSEQ,X,MAX,NP,TINT,KODE,ID,NER)
Read in a GW waveform from a file into the user array X.
This routine is similar in every way to GWRD2, except that here,
the data set is specified by it's sequence number in the file.
Also, the DSID os the waveform is returned by this routine.
NSEQ : Sequence number of data set in file.
X : Single precision floating point array to hold waveform
MAX : Max. no. of values X can hold (i.e. dimension of X)
NP : Number of values actually read into X
TINT : Time interval between successive values in X (microsecs)
KODE : Waveform type code (e.g. 11=Gaussian noise)
ID : 12-character Data Set ID (type character)
NER : Error code, normally zero.
NSEQ and MAX must be supplied. All other values are
returned by this routine.
Note : You also need to link L:DAFLIB along with DCPLIB to
use this routine.
GWSTOR(FNAME,LUN,ID,X,NP,TINT,KODE,NER)
Store a new waveform in a GW compatible format data file.
FNAME : File name where waveform will be stored (type character)
LUN : Logical unit number to assign to file
ID : Data set ID (upto 12 characters) (type character)
X : Single precision floating point array containing waveform
NP : Number of values in X
TINT : Time interval between successive values in X (microsecs)
KODE : Waveform type code (see below)
NER : Error code, normally zero.
FNAME, LUN, ID, X, NP, TINT and KODE must be supplied by
the calling program, while NER will be returned by this routine.
The value of KODE is stored with the data for
informational purposes. The user must provide this value. If not
sure, use KODE=0. A more complete list of suggested KODE values
is available in ref (1).
Note : You also need to link L:DAFLIB along with DCPLIB to
use this routine.
GWSTOR2(LUN,ID,I2X,NP,TINT,KODE,NER)
Store the specified waveform as a new data set in a GW
format file. This routine is similar to GWSTOR, except here the
waveform is stored in GW format-2. Format-2 stores the amplitude
values as 16-bit integers, thereby conserving disc space.
LUN : Logical Unit number to which file has been assigned
ID : 12-character DSID (type character)
I2X : Integer*2 array containing waveform
NP : Number of points in I2X
TINT : Time interval between successive points in I2X (in secs)
KODE : Waveform type code (e.g. 0=unknown)
NER : Error code, normally zero.
All parameters except NER must be supplied by the calling
program. Routines INITDF or INITDFC must be called before this
routine is called. You also need to link library L:DAFLIB in
addition to DCPLIB to use this routine.
INICSF(LUN,NER)
Initialize the Calibration Storage File (CSF) for reading,
and assign it to logical unit number LUN.
LUN : LUN to which CSF will be assigned.
NER : Error code.
LUN must be supplied by the calling program. (The CSF is a
file named CALTAB.DAT in the D: directory on the VAX).
IPTERM(PNAME,NER)
Initiate the specified program and terminate the current one.
PNAME : Name of next program to be initiated (type character)
(upto 40 characters).
NER : Error code
The program which calls this routine will normally be
terminated, so NER will not be returned. However, if there is
some error in starting PNAME, then a non-zero value will be
returned in NER.
LCSPL(NSS,F1,F2,RNGMAX,DBMAX,RNGDB,NER)
Load the constant SPL table in the DSS, using calibration
values stored for Phone number NSS.
NSS : DSS number (1 or 2)
F1 : Low Frequency (Hz)
F2 : High Frequency (Hz)
RNGMAX : Max. dB range beyond which calibration table will be
"clipped" (dB). (If zero or negative then do not clip).
DBMAX : The max dB level which will be presented when the
attenuator is set to zero. (dB)
RNGDB : The range (in dB) between peak and valley of the
calibration table in the range (F1,F2). It may be
greater than RNGMAX.
NER : Error code, normally zero.
NSS, F1,F2 and RNGMAX must be supplied by the user, while
DBMAX, RNGDB and NER will be returned by this routine.
You must call INICSF before calling this routine. If
either F1 or F2 is negative then the entire calibration table is
loaded.
LHSPL(NPHON,F1,F2,SMAX,SMIN,NER)
Find the Highest and Lowest SPL in the current calibration
for phone NPHON.
NPHON : Phone (DSS) number (1 or 2)
F1 : Start Frequency (Hz)
F2 : End Frequency (Hz)
SMAX : Max SPL in the range F1 to F2 Hz (dB)
SMIN : Min SPL in the range F1 to F2 Hz (dB)
NER : Error code, normally zero
NPHON, F1 and F2 must be supplied, while SMAX, SMIN and
NER will be returned. This routine reads the most recent
calibration table for phone NPHON from the CSF and scans the
range F1 to F2 Hz only.
MICSEL(N,NER)
Select either the "left" or "right" microphone for
sampling.
N : Microphone number (1=left, 2=right)
NER : Error code, normally zero.
This routine is used to control the microphone selection
in the Anechoic Lab (room 18).
MOTORS(N,NDIR,NSTEP,NWAIT,NER)
Routine to control the "Superior" brand stepper motors in
the Anechoic Lab (room 18).
N : Motor number (1=Base, 2=Arm)
NDIR : Direction/Function code
-1=Move counter-clockwise
+1=Move clockwise
0=Set current position
2=Read current position
NSTEP : Number of steps to move (or, motor position if NDIR=0 or 2)
NWAIT : Time to wait between steps (in units of 1/100th sec)
NER : Error code, normally zero.
N, NDIR, NSTEP and NWAIT must be provided by the calling program.
(unless NDIR=2 in which case NSTEP will be returned), while NER
will be returned in all cases.
The motors are controlled via the DRV11 parallel I/O
interface which is plugged into the VAXstation Q-bus backplane.
NEWID(KODE,OLDID,MASK,NEW,NER)
Form a new Data Set ID from an older ID, given a mask.
KODE : 1 New Unit 2 New Sequence
OLDID : Old DSID (12 characters) (type character)
MASK : Mask (12 characters) (type character)
NEW : New DSID (12 characters) (type character)
NEW : Error code, normally zero
KODE, OLDID and MASK must be supplied, while NEW and NER
will be returned by this routine.
MASK can include wildcards as follows :
ID MASK
-- ----
U1-1 @#-%
3-22-NDC #-%-@@@
Note that # is the Unit Number and % is the Sequence Number.
PHSCAL(NPHON,FREQ,PHAS,NER)
Read the current calibration table from disc and return
the Phase at a specified frequency.
NPHON : Phone number (1 or 2)
FREQ : Frequency (Hz)
PHAS : Phase (in radians)
NER : Error code, normally zero.
NPHON and FREQ must be supplied by the calling program,
while PHAS and NER will be returned. Routine INICSF must be
called before this one. The value of PHAS is returned in radians
in the range 0 to 2 .
Some possible values for NER are as follows :
NER=111 FREQ out of range, nearest value returned
NER=421 INICSF must be called first
PHSTAB(NPHON,PHAS,MAX,NPHAS,NER)
Read the entire phase table from the current calibration
file for specified phone.
NPHON : Phone (DSS) number (1 or 2)
PHAS : Floating point array to hold phase values
MAX : Max. no. of values that PHAS can hold
(i..e. the dimension of PHAS)
NPHAS : No. of values actually returned
NER : Error code, normally zero.
NPHON and MAX must be supplied, while PHAS, NPHAS and NER
will be returned. The phase values are in units of radians.
Routine INICSF must be called before this one.
QCSPL(NSS,F1,F2,RNGMAX,DBMAX,RNGDB,NER)
"Query" the SPL calibration table.
This is similar to routine "LCSPL" in every way except
that here the table is not loaded into the DSS, just some
information is returned.
SPLMAX(NPHON,FREQ,MAXS,NER)
Read the calibration table from disc and return the Max-
SPL at the specified frequency.
NPHON : Phone number (1 or 2)
FREQ : Frequency (Hz)
MAXS : Max SPL possible at FREQ (dB) (Integer*4)
NER : Error code, normally zero.
NPHON and FREQ must be supplied by the calling program,
while MAXS and NER will be returned. Routine INICSF must be
called before calling this one.
Some possible values of NER are :
NER=421 INICSF must be called first
NER=111 Freq. is out of range, nearest value returned.
SPLTAB(NPHON,SPL,MAX,NSPL,NER)
Read the entire SPL table for the specified phone from the
Calibration Storage File (CSF).
NPHON : Phone (DSS) number (1 or 2)
SPL : Floating point array to hold SPL values
MAX : Max. no. of values that can be stored in array SPL
(i.e. the dimension of SPL)
NSPL : Number of values actually returned
NER : Error code, normally zero.
NPHON and MAX must be supplied by the calling program,
while SPL, NSPL and NER will be returned. Routine INICSF must be
called before this one is called.
STBDEL(NAMSTB,LUN,NER)
Delete the Status Table File (STBF).
NAMSTB : STBF Name (Integer array)
LUN : Logical Unit number to assign to STBF
(or, to which it was assigned by STBINI).
NER : Error code, normally zero.
NAMSTB and LUN must be supplied by the calling program,
while NER will be returned. Note that since NAMSTB is being
supplied as an integer array, it's last byte (or word) must be
set to zero.
STBEN1(VARV,NV,NPT,NP,NER)
Make an entry into a Type-1 Status Table
VARV : Values of variables (real array)
NV : Number of values in array VARV
NPT : Pointers (Integer*4 array)
NP : Number of pointers in NPT
NER : Error code, normally zero.
Everything except NER must be supplied by the calling program.
STBINI must be called at least once before STBEN1 is called.
For a description of STATUS tables see references (2) ,(3) and (4).
STBEN2(NX,NY,NPT4,NP,NER)
Make an entry in a type-2 Status Table.
NX : Row Number
NY : Column number
NPT4 : Pointers (I*4 array)
NP : No. of pointers in NPT4
NER : Error code, normally zero.
All parameters except NER must be supplied by the calling program.
STBINI must be called before this routine is called.
For a description of STATUS tables see references (2) ,(3)
and (4).
STBINI(NAMSTB,LUN,NTYP,NBLK,NV,NP,EDF,DSID,NY,NER)
Create a new Status Table File (STBF) on disc and initialize it.
NAMSTB : STBF file name (Character String)
LUN : Logical unit no. to which STBF will be assigned
NTYP : Type of Status Table (1 or 2)
NBLK : Size of Status Table (blocks)
NV : Number of variables (if type-1 table)
(or, No. of times X-varied (if type-2 table))
NP : Number of pointers
EDF : Data file name (Character String)
DSID : Data set ID (Character String)
NY : Number of times Y-varied (if type-2 table)
NER : Error code, normally zero.
All parameters except NER must be supplied by the calling
program.
For a description of STATUS tables see references (2) ,(3) and (4).
STBINII(NAMSTB,LUN,NTYP,NBLK,NV,NP,EDF,DSID,NY,NER)
Create a new Status Table File (STBF) on disc and initialize it.
This routine is similar to "STBINI" (see above) in every way,
except here NAMTSB and EDF are zero-terminated integer arrays
and DSID is a 12 character integer array.
STBOPN(NAMSTB,LUN,NER)
Open the STBF and prepare to make entries in it.
NAMSTB : STBF name (Integer array)
LUN : Logical Unit number to assign STBF
NER : Error code, normally zero.
NAMSTB and LUN must be supplied by the calling program,
while NER will be returned. Since NAMSTB is passed as an integer
array, its last byte (or word) must be set equal to zero.
This routine differs from STBINI in that STBOPN assumes
that the STBF has already been created and initialized by STBINI.
STBTR(NAMSTB,LUN,LEDF,LOC,NSZW,NER)
Transfer Status Table from STBF to data file.
NAMSTB : Status Table file name (Integer array)
LUN : Logical unit number to be assigned to STBF
LEDF : Logical Unit number to be assigned to data file (EDF).
LOC : Word location in data file start writing Status Table
NSZW : Size of Status Table (in units of 32-bit words)
NER : Error code, normally zero
NAMSTB, LUN, LEDF and LOC must be supplied by the calling
program, NSZW and NER will be returned.
Since NAMSTB is sent as an integer array, the last byte
(or word) of this array must contain a zero.
Note : The Status Table File (STBF) will be deleted after
a successful transfer.
WCBUF(ICBLK,NER)
Write the communications buffer for use by the next
program.
ICBLK : 63 word Integer*4 array containing communications buffer
NER : Error code, normally zero.
The communications buffer is written into the "per process
common block".
(5) REFERENCES
(1) "GWE - General-Waveform/Time-Series Analysis", R. Kochhar,
Tech. Report no. 15.
(2) "Unit Data Storage - Part I", R. Kochhar, Conversion
Report no. 10, Dept. of Neurophysiology, Sept. 1982.
(3) "Unit Data Storage - Part II", R. Kochhar, Conversion Report no. 15,
Dept. of Neurophysiology, July 1983.
(4) "STBF - Status Table File", R.Kochhar, Conversion Report
no. 17, Dept. of Neurophysiology, May 1984.
(5) "Calibration Storage File (CSF), and Calibration Editor
(ECAL)", R. Kochhar, Conversion Report no. 12, Dept. of
Neurophysiology, Feb. 1983.
If you have questions or suggestions about this document,
please send e-mail to
kochhar@physiology.wisc.edu
Return to Computing Page
Back to The Basement
This page last modified on : Aug. 8, 2000