Text preview for : 24460A(ASO_ADC16).pdf part of Keithley 24460A(ASO ADC16) Keithley Misc 24460A(ASO_ADC16).pdf
Back to : 24460A(ASO_ADC16).pdf | Home
ASO-ADC-16
User's Guide
Revision A
Printed February, 1333
Parr No. 24460
0 Keithley Data Acquisition 1993
WARNlNG
Keithley Data Acquisition assumes no liability for damages consequent to the
use of this Product. This Product is not designed with components of a level
of reliability that is suitable for use in life support or critical applications.
The information contained in this manual is believed to be accurate and reliable.
However, Keithley Data Acquisition assumes no responsibility for its use; nor for
any infringements or patents or other rights of third parties that may result from
its use. No license is granted by implication or otherwise under any patent rights
of Keithley Data Acquisition.
Keithley Data Acquisition does not warrant that the Product will meet the
Customer's requirements ot will operate in the combinations which may be
selected for use by the Customer or that the operation of the Program will be
uninterrupted or error free or that all Program defects will be corrected.
Keithley Data Acquisition does not and cannot warrant the performance or results
that may be obtained by using the Program. Accordingly, the Program and its
documentation ate sold "as is" without warranty as to their performance
merchantability, ot fitness for any particular purpose. The entire risk as to the
results and performance of the program is assumed by you.
All brand and product names mentioned in this manual are trademarks or
registered trademarks of their respective companies.
Reproduction or adaptation of any part of this documentation beyond that
permitted by Section 117 of the 1976 United States Copyright Act without
permission of Keirhley Data Acquisition is unlawful.
Keithley Data Acquisition l 440 Myles Standish Blvd. l Taunton, MA 02780
Telephone: (508) 880-3000 l Fax: (508) 880-0179
Contents
Chapter 1 Introduction ............................. 1
1.1 About the ASO-ADC-I6 ............................ 1
1.2 Prerequisites .................................... 3
1.3 Getting additional help ............................. 3
1.4 Installing the AS0 ................................ 5
Chapter 2 The Function CalI Driver .................... 7
2.1 Available operations ........................... ... 7
2.2 Overview of programming with the Function Call Driver ...... 9
2.3 General programming tasks ......................... 11
2.4 Operation-specific programming rasks .................. 11
2.5 Language-specific programming notes ............... .. 17
Chapter 3 Callable Functions ........................ 25
3.1 Functional grouping .............................. 25
3.2 Function reference ............................... 29
Chapter 4 File I/O Driver .......................... 65
4.1 Overview ..................................... 65
4.2 Loading and unloading the driver ..................... 66
4.3 Language-specific programming notes .................. 70
Chapter 5 Fiie I/O Commands ....................... 81
5.1 Functional grouping .............................. 81
5.2 Command reference .............................. 84
Appendix A Function CaIl Driver error messages ............ 97
Appendix B File I/O Command Driver error messages ......... 103
.; ,f
Introduction
About the ASO-ADC- 16
The ASO-ADC-16 is the Advanced Software Option (ASO) for the
ADC-16 analog input and digital l/O board. The AS0 includes a set of
software components that you can use, in conjunction with a programming
language, to create application programs that execute the operations
available on the ADC-16.
The two primary components of the AS0 are the Function Call Driver
and the File I/O Driver. These drivers represent two distinct methods of
providing your application program with high-level access to the
acquisition and control operations available on the ADC-16. The AS0 also
includes support files, example programs, and a configuration utility.
The Function Call Driver and the File I/O Driver are independent of each
other; your application program will use one or the other, but nor both.
The two drivers are implemented differently and provide slightly different
fmctionality. You should use whichever driver is appropriate for your
pt-ogramming skills and your application's requirements.
Function Call Driver The Function Call Driver enables your program to define and execute
board operations via calls to dl-iver-provided ftmctions. For example, your
program can call the driver-provided K-ADRead fwcrion to execute a
single-point, A/D input operation.
The AS0 includes several different versions of the Function Call
Driver. The .LIB and .TPU versions are provided for DOS application
development. The Dynamic Link Library (DLL) is provided for Windows
application development.
The AS0 and this manual provide the necessary tools, example programs
and information to develop Function Call Driver programs in the
following languages:
. Borland C++ (version 2.0 and higher)
. Borland Turbo C (version 2.01)
. Borland Ttlrbo Pascal (version 6.0)
. Borland Turbo Pascal for Windows (version 1.O)
. Microsoft C (version 5.1 and above)
w Microsoft Quick C for Windows (version 1.O)
. Microsoft Visual Basic (version 1.O and higher)
File I/O Driver Thr File I/O Driver enables your program to define, execute, and retrieve
the results of board operations by writing (to the driver) dl-iver
-provided File I/O Commands. For example, your program can wire the
Read Channel 1 command to execute a single-point, A/D input operation.
You can use the File l/O Driver to create DOS applications with any
language that supports file l/O. The AS0 and this manual provide the
necessary tools, example programs and information to develop File I/O
Driver programs in the following languages:
. Interpreted BASIC
m QuickBASIC
. Borland Turbo C
. Borland Txbo Pascal
n Microsoft C
. Microsoft Pascal
1.2 Prerequisites
-
The AS0 is designed exclusively for use with the ADC-16. This manuzal
ass~unesthat you understand the information presented in the ADC-I6
&r's Guide. Additionally, you must complete the board installation and
configuratioo procedures outlined in the ADC-I6 lherl Grride before you
attempt any of the procedures described in this manual.
The fmdamental goal of this manual is to provide you with the
information you need to write ADC-I6 application programs that u.w the
AS0 drivers. It is recommended that you proceed through this manual
according to the sequence suggested by the table of contems; this
will minimize the amount of time and effort required to develop your
ASO-ADC-16 application programs.
1.3 Getting additional help
-
The following resources provide information about using the ASO:
. this manual
. the ADC-I6 lherk Gaide
. the AS0 example programs (these are copied to your system's hard disk
during the installation procedure)
. the documentation for the programming language you arc using
Call our Technical Support Department if you need additional auistance
A Technical Support Engineer will help you diagnose and solve your
problem over the telephone.
Keithley Data Acquisition - Technical Support
508-880-3000
Monday - Friday, 8 A.M. - 7 P.M.
For the most efficient and IlelpfuJ assisraoce, please compile the following
information before calling our Technical Support Department:
Version
Invoice/Order #
ADC-16 Serial #
Base address setting
A/D fttll-scale setting i3.2768 V +5 V
STA-IX8 Number installed
Computer Manufacturer
CPU type 8088 286 386 486 0rhe1
Clock speed (MHz) 8 12 20 25 33 Otllel-
Math co-processor? Yes No
Amount of RAM
Video system CGA Het-c&s EGA VGA
Language
Manufacturer
Version
4 ASO-A[)(::-16 User's Guidr - Iicv. A
1.4 Installing the AS0
-
The files on these AS0 distribution diskettes are in compressed format.
You must use the installation program included oo the diskettes to insraIl
the AS0 software. Since the aggregate size of the expanded AS0 files is
approxtmately 1.O MB, check that there is at least this much space
available oo your PC's hard disk before you attempt to install the ASO.
Perform the following procedure to install the AS0 software (note that it
is assumed that the floppy drive is designaced A:):
1. Make a back-up copy of the distribution diskette(s).
2. Insert AS0 diskette #l into the floppy drive
3. Type the following commands at the DOS prompt:
A: 1~1
install [LEn!e~r&/
The installation program prompts you for your iostallarion preferrnccs.
including the name of the directory into which the AS0 files will br
copied. The installation program expands the files on the AS0 diskette(s)
and copies them into the directory you specified; refer to the IiIe
FIl.ES.IXK: in the AS0 installation directory for the names and
descriptions of these files.
The Function Call Driver
2.1 Available operations
The Function Call Driver provides functions through which an application
program can perform the following operations:
Immediateexecution operations
. Single-value A/D input
. Single-value digital input
n Single-value digital output
Frame-based operations
H Multi-value, interrupt-mode A/D iuput
n Multi-value, synchronous-mode A/D input
Immediate-execution operations and frame-based operations are described
in the following subsections.
immediate-execution The three immediate-execution operations and the Callable Function
operations associated with each are as follows:
l Single-value A/D input: K_&DRead
. Single-value dig&al input: K-DIRead
l Single-value digital output: K_DOWrite
The calling arguments for these functions define the attributes of the
associated operation. Upon receipt of a call to one of these hmctions. the
driver immediately executes the associated operation.
(:hapter 2 - The t;unction (:all I)rivcr 7
Frame-based The two frame-based operations and the Callable Function associated wirb
operations each are as follows:
. Multi-value, interrupt-mode A/D input: K-IntStart
. Multi-value, synchronous-mode A/D input: K-SyncStart
The description of frame-based operations requires the introduction of a
few new terms.
Afiume is a data structure whose elements correspond ro the defining
attributes of a board operation. The driver L~S two different types of
frames: A/D and Digital Output frames. The driver mainrains a pool of
four A/D frames and four Digital Output frames.
The values of a frame's elements define the operation? attributes. For
example, the elements contained in an A/D frame al-e as follows:
n Srdrt Channel - defines the first channel in a scan
n Stop Channel - defines the last channel in a scan
. Gain element - defines the gain applied to all channels in the scan
The driver provides fimctions that set the value of one or more elements.
For example, K-SetG sets the value of a frame's Gain elemeot, and
K_SetStarxStopChn sets the values of a frame's Start Channel and Stop
Channel elements.
A jmm handle is a variable whose value identifies a frame. The sole
purpose of a frame handle is to provide a mechanism through which
different function calls can reference the same frame.
A device handle is a variable whose value identifies an insrdlled board. The
sole purpose of a device handle is to provide a mechanism through whirl
different fitnction calls can reference the same board.
A frame-based operation is so-called because the function that pcrfol-ms the
ape!-atmn uses a frame handle as its single calling argument. The frdrnr
handle identifies a frame whose element values are the operation's
attributes. The values of all of a frame's elements must be set brfore that
frame's handle can be used as a calling argument to a funcrion that
exccutcs a frame-based operation.
2.2 Overview of programming with the Function Call Driver
The procedure to write a Function Call Driver program is a& followx
1. Define the application's requirements.
2. Write the program code.
3. Compile and link the program.
The subsections that follow describe the details of each of these wps.
Defining the Before you begin writing the program code. you should have a char idea
application's of the board operations you expect your program to execute. Additionally.
requirements you should determine the sequence in which these operations must be
executed and the characteristics (number of channels, gains. and ho on)
that define each operation. You may find it helpful to review the list of
available operations in Section 2. I and to browse through the short
descriptions of the Callable Functions in Section 3. I.
Writing the Several so~~rcesof information relate to this step:
program code . Section 2.3 explains the programming tasks that are common to all
Function Call Driver programs
. Section 2.4 describes the sequence of function calls requil-ed to execute
each of the available operations
. Section 3.2 provides detailed information on individual fimctions
. The AS0 includes several example source code files for Function Call
Driver programs. The FILIXIXK file in the AS0 installation directory
lists and describes the example programs.
The phrase ycneralprogrumming tasks, as it is used in this chapter, refers to
the programming tasks that every Function Call Driver program must
execute. The task of obtaining a device handle, for example, qualifies as a
general programming task, since the sequence of function calls required to
execute any of the available board operations includes at least one f&tion
whose calling arguments include a device handle. Section 2.3 provides the
details of the general-programming tasks.
Each available operation also has an associated set of tasks that the
program must perform to execute the operation; these are referred to as
operation-specific programming tasks. Section 2.4 provides the derails of the
operarlon-specific programming tasks for each available operation.
Compiling and linking Refer to Section 2.5 for compile and link instructions and other language-
the program specific considerations for each supported language.
- 2.3 General programming tasks
Every Function Call Driver program must execute the following
programming tasks:
I. Identify a function/variable type definition file
The method to identify this file is language-specific; refer to Section 2.5
for addirional information.
2. Declare/initialize program variables
3. Call ADCl6-DevOpen to initialize the driver
4. Call ADClb-GetDevHandle to initialize the board and get a device
handle for the board
The tasks listed are the minimum rasks your program must complete
before it attempts to execute any operarion-specific tasks. Your application
may require additional general-progralnmiIlg tasks. For example, if your
program requires access to two boards, then it mwst call
ADCl6_GetDevHandle for each board.
2.4 Operation-specific programming tasks
-
This section describes the set of programming casks char your program
must perform to execute the following operations:
n Single-value A/D input
n Single-value digital input
. Single-value digital output
. Interrupt-mode A/D input using channel-gain array
. Synchronous-mode A/D input using channel-gain array
n Interrupt-mode A/D input using start/stop channels
. SynchronoLts-mode A/D input using start/srop channels
The set of tasks listed for each operation are valid only if the application
program has already completed the general-programmitlg tasks.
Single-value A/D input
To execute a single-value A/D input, your program musr call K-ADRead.
The calling arguments identify the board that executes the operation, the
channel on which the value is acquired, the gain applied to that channel,
and the buffer in which the value is stored.
Single-value digital input
To execute a single-value digital input, your program must call K_DIRead.
The calling arguments identify the board that executes the operation, the
channel on which the value is acquired, and the buffer in which the value
is stored.
Single-value digital output
To execute a singk-value digital output, your program must call
K-DOW&. The calling arguments identify the boa!-d that executes the
operation, the channel on which the value is written, and the buffer f+om
which the value is written.
12 AS0ALX-I 6 User's Guide - Kev. A
Interrupt-mode A/D input using start/stop channels
Your program must perform the following tasks to execute an interrupr-
mode A/D input operarion whose channel-scanning sequencr is given by
the sequence's start and srop cl~annels:
1. Allocate a buffer in which rhe driver stores the A/D values. Use
K~INTAlloc if you want to allocate this buffer outside the program's
memory area (you must use K_INTAlloc if you are writing an application
that will execute in Windows standard mode).
2. Call K-GetADFtame to get the handle to an A/D frame
3. Call K-SetBuf'to assign the buffer address obtained io stt=p I to the Ruffer
Address element in the frame associated with [he frame hat& obtained in
srep 2.
4. Call K-SecStartStopG or K-SetStztStopChn and K-SetG to assign values
to the Start Channel, Srop Channel, and Gain elemenu in the frame
associated with the frame handle obtained in step 2.
5. Call K-INTStart to start the operation.
6. Call K-INTStatus to monitor the status of the operation,
7. (Optional for C and Pascal programs)
Call K-MoveDataBuf to transfer the acquired data from the buffer to a
user-defined array.
8. If K-INTAlloc was used to allocate a buffer io step 1, call KPINTFree to
deallocate the buffer.
9. Call K-FreeFrame to return the frame (associated with the frame handle
from srep 2) to the pool of available frames.
Chapter 2 - `l`hc Function (31 l)rivcr 13
Interrupt-mode A/D input using channel-gain array
Your program must perform the following tasks ro execute an interrupt-
mode A/D input operation whose cllannel-scannitl~ sequence is given by a
channel-gain array:
1. Define and assign values to a channel-gain array. The format and other
information pertaining to channel-gain arrays is listed tmder the reference
entry for K-SetChnGAry on page 60.
2. Allocate a buffer in which the driver stores the A/D values. Use
K_INTAlloc if you want to allocate this buffer outside the program's
memory area (you must use K-INTAlloc if you are writing an application
that will execute in Windows standard mode).
3. Call K-GetADFrame to get the handle to an A/D frame.
4. Call K_SetBufto assign the buffer address obtained in step 2 to the Buffet
Address element in the frame associated with the frame handle obtained in
step 3.
5. Call K_SerChnGAry to assign the channel-gain array from step 1 to the
Channel-Gain Array Address element in the frame associated with the
frame handle obtained in step 3.
6. Call K-INTStart to start the operation
7. Call K-INTStatus to monitor the stattts of the operation,
8. (Optional for C and Pascal programs)
Call K_MoveDaraBuf to transfer the acquired data from the buffer to a
user-defined array.
9. If K-INTAIIoc was used to allocate a buffer in step 2, call K-INTFree to
deallocate the buffer.
10. Call K-FreeFrame to return the frame (associated with the frame handle
from step 3) to the pool of available frames.
Synchronous-mode A/D input using start/stop channels
Your program must perform the following tasks to execute a synchronou+
mode A/D input operation whose channel-scanning sequencr i\ given by
the sequence's start and stop channels:
1, Allocate a buffer in which the driver stores the A/D values. Usr
K-INTAlloc if you want to allocate this buffer outside the program'\
memory area.
2. Call K-GetADFrame to get the handle to an A/D frame.
3. Call K_SetBuf to assign the buffer address obtained in step 1 to the Rufft-r
Address element in the frame associated with the frame handle obtained in
step 2.
4. Call K_SetSrartStopG or K~SetStarrStopChn and K_SetG to assign valurs
to the Starr Channel, Stop Channel, and Gain elements io the frame
associated with the frame handle obtained in step 2.
5. Call K-Sync&art to start the operation.
6. (Optional for C and Pascal programs)
Call K-MoveDataBuf to transfer the acquired data from the buffer to a
user-defined array.
7. If K-INTAIloc was used to allocate a buffer in step 1, call K_INTFree to
deallocate the buffer.
8. Call K_FreeFrame to return the frame (associated with the frame handlr
from step 2) to the pool of available frames.
Synchronous-mode A/D input using channel-gain array
Your program must perform the following tasks to execute a sy~~l~ronous-
mode A/D input operation whose channel-scanning sequence is given by a
channel-gain array:
1. Define and assign values to a channel-gain array. The format and other
information pertaining to channel-gain arrays is listed under the reference
entry for K-SetChnGAry oo page 60.
2. Allocate a buffer in which the driver stores the A/D values. Use
K~lNTAlloc if you want to allocate this buffer outside the program's
memory area.
3. Call K-GetADFrame to get the handle to an A/D frame.
4. Call K-SetBufto ass@ the buffer address obtained in step 2 to the Buffer
Address element in the frame associated with the frame handle obtained in
step 3.
5. Call K_SetChnGAry to assign the channel-gain array from step 1 to the
Channel-Gain Array Address element in the frame associated with the
frame handle obtained in step 3.
6. Call K_SyncStart to start the operation.
7. (Optional for C and Pascal programs)
Call K-MoveDataBuf to transfer the acquired data from the buffer to a
user-defined array.
8. If K~INTAUoc was used to allocate a buffer in step 1, call KPINTFree to
deallocate the buffer.
3. Call K-FreeFrame to return the fi-ame (associated with the frame handle
from step 3) to the pool of available frames.
2.5 language-specific programming notes
This section provides specific programming guidelines for each of the
supported languages. Additional programming information is available in
the AS0 example programs. Refer to the FILES.DOC tile for names and
descriptions of the AS0 example programs.
Borland C++, Microsoft C and Borland Turbo C
Related files ADCI6.LIB
DASRFACE.LIB
USERPROTH
Compile and link Borland C++:
instructions BCC -c -ml fi1ename.c
TLINK c0l+filename,filename..adcl6+dasrface+cl:
Microsoft C:
CL /AL /c fi1ename.c
LINK filename.,,ADC16+DASRFACE:
Turbo C:
TCC -c -ml fi1ename.c
TLINK cOl+filename,filename..adcl6+dasrface+cl:
Example program Execute a single A/D conversion
I* C include files *I
#include "8tdio.h"
i/include "std1ib.h"
I* ADC-16 driver include file i/
#include "userprot.h"
I* Local variables *I
DOH AOC16; I" Device Handle *I
char NumOfBoards: /* #boards in AOC16.CFG */
int Err: I' Function ret err flag *I
long Advalue: I* Storage for A/D value *I
I* Begin main module "I
main0
t
I* Initialize the hardware/software 'I
if (( Err = ADC16-DevOpen( "ADC16.CFG", &NumofBoards )) !=OJ
t
putch (7); printf( ' Error %X during DevOpen ', Err 1:
exit(Err1:
I
I* Establish communication with the driver .&I
I* through a device handle *I
if ( ( Err = ADC16-GetDevHandle( 0, &ADClG ) 1 != 0 1
i
putch (7): printf("Error %X during GetDevHandle ".Err);
exit(Err):
1
I* Read channel 0 at gain 1: store sample in Advalue *I
if ((Err = KmALlRead (ADC16, 0, 0, &ADvalue)) != 0)
1
putch(7): printf ("Error %X in Km~ADRead operation ", Err):
exit(Err);
I
I* Display ADvalue *I
printf ("A/D value from channel 0 is : %x\n". ADvalue):
I
Borland C++
If you want to compile a Borland C++ program as a standard C program.
refer to the information presented in the previous section. If you want to
compile your program as a Borland C++ program, refer to the informarion
presented in the previous section with the following exceprions:
1. Use the supplied file USERPROTBCP instead of USERPR0T.H.
2. Specify the C++ compilation in one of the following two way\:
a. Specify .CPP as the extension for your source file, or
b. Use the BCC 4' command line swirch.
Borland Turbo Pascal
Compile and link TPC ,filename.pas
instructions
Example program Execute a single A/D conversion
Program TPEXAMPLE;
[ UNITS USED BY THIS PROGRAM I
Uses Crt. ADC16:
I LOCAL VARIABLES I
Var
Devhandle : Longint: I Device Handle I
ConfigFile : String; I String to hold name of configuration file j
NumOfBoards : Integer:
BoardNumber : Integer:
Ertn : Word; I Error flag 1
Gain : Byte; I Overall gain 1
ADvalue : Longint; I Holds A/D sample I
Chan : Byte: ( A/D channel I
( BEGIN MAIN MODULE I
BEGIN
I STEP 1: This step is mandatory: it initializes the
internal data tables according to the information
contained in the configuration file ADCI6.CFG.
I
ConfigFile := 'ADC16.CFG' + #O:
Ertn := ADC16~DevOpen( ConfigFile[ll. NumOfEoards 1:
IF Ertn 0 0 THEN
BEGIN
writeln( 'Error ', Ertn. 'an Device open' ):
Halt(l):
END:
( STEP 2: This step is mandatory: it establishes
communication with the driver through the
Device Handle.
I
(hapter 2 - 'The hnction (:all Ikiver 19
BoardNumber := 0:
Ertn := ADCl66GetOevHandle( BoardNumber. Devhandle 1;
IF Ertn 0 0 THEN
BEGIN
writeln( 'Error ', Ertn. getting Device Handle' 1:
Halt(l):
END;
{ STEP 3: Read A/D sample from channel 0 at gain 1
(Gain Code 0) and store in local variable.
J
Chan := 0:
Gain := 0;
Ertn := KmADReadCDevhandle. Chap, Gain, ADvalue):
IF Ertn 0 0 THEN
BEGIN
writelnC^G. 'Error ii '.Ertn, 'Occurred during KKADRead call');
Halt(l):
END:
writeln('A/D VALUE : ', ADvalue):
END.
Borland Turbo Pascal for Windows
Related files ADCI6TPW.INC
ADCl6.DLL
NOkS If you use ADCI G.DLL, the information presented for Borland Turbo
Pascal applies here with the following additions:
n Use the compiler directive ($1 ,,. } to include the supplied includr file
ADCl6TPW:INC.
. Substitute `Wit&-t for the `Crt' unit; this is necessary in order that the
console 1/O procedures (writeln, readln, etc...) operate properly.
The following code fragment illustrates these additions:
Program TPW.~EX:
{ UNITS USED BY THIS PROGRAM 1
Uses WinCrt:
'1 LOCAL VARIABLES I
Var
1 ADC16 function prototypes that reference .OLL 1
($1 ADC16TPW.INCI
( BEGIN MAIN MODULE 1
BEGIN
20 ASO-AD(::-16 L&r's Guide - liev. A
If you use ADCl GTPW.INC, the information presented for Bol-land
Turbo Pascal applies here with the following exceptions:
n Substitute ADCl6TPW.INC for the ADCIG unit.
- Substitute `WinCrt' for the `Or unit: this is necessary in order that the
console 110 procedures (w&In. readln, etc...) operate properly.
The following code fragment illustrates these substitutions:
Program TPW-EX;
I UNITS USED BY THIS PROGRAM I
Uses WinCrt. ADC16TPW:
'I LOCAL VARIABLES I
yar
I BEGIN MAIN MODULE I
BEGIN
Microsoft Quick C for Windows
Related files ADCl6.DLL
Compile and Link 1. Load fi&une.c into the Quick C for Windows environment
instructions
2. Create a project file.
3. Select PI executed from within Windows.
Notes The programming procedure required to call the Callable Functions from
Quick C for Windows programs is identical to the procedure described for
Microsoft C.
(hpter 2 - 'l'he Funcri Microsoft Visual Basic for Windows
Related files ADClG.DLL
ADClGEX.BAS
Notes Before you begin coding your Visual Basic proogrm~, you must copy (from
inside the Visual Basic environment) the contents of ADClGEX.BAS into
your application's GLOBAL.BAS. Use the following procedure to add the
contents of ADCl6EX.BAS to GLOBAL.BAS (you should make a back-up
copy of GLOBAL.BAS before you modify it):
1. Select FILE h Arm FILE... from the Viswl Basic main menu.
2. Select ADClGEX.BAS.
3. Highlight the contents of the entire ADC16EX.BAS file.
4. Select Em b COPY to COPY the Comm of ADClGEX.BAS to the
Windows clipboard.
5. Double-click on GLORALRAS in the Project window.
6. Select Erm b PASTE.
7. S&XX FIII h SAVE PKOIEC:T.
22 AS0AM:- I6 User's (;uidr - Kcv. A
Example program Execute a single A/D conversion.
Sub CommandlLClick 0
board% = 0
Cls
For x = 0 to 9' Clear our buffer
Ibuffer = 0
Next x
MyErr = ADC16~~~devopen("..\ADC16.CFG". board%)
If MyErr 0 0 Then
MsgBox "ADCIG~~mdevopen Error", 48. "Error'
GoTo exyl
End If
Print
Print "Scanning Channels ': strtch: "-': stpch
MyErr = ADClbLgetdevhandle(0. adcl6)
If MyErr <> 0 Then
MsgBox "ADCl6mgetdevhandle Error", 48. "Error"
GoTo exyl
End If
Print
Print "AD Data :*
Print
For x = strtch to stpch
MyErr = K.-ADRead(adcl6. x. Chgain. retval)
lBuffer(x) = retval
Print ' Channel -; x; - = -; HexB(lBuffer(x))
Next x
Print
Print
exyl:
End Sub
Callable Functions 3
3.1 Functional grouping
The Callable Functions can be classified according to the f~mctionality that
each provides. This secriot~ lists each Callable Function as a mrmbcr of
one of the following groups:
n Initialization
n Memory management
n Frame management
n Frame-element management
m Frame-based operation comol
. Immcdiatc-execution operations
. Miscellaneous operations
This section provides short descriptions of each function; refer to Srction
3.2 for additional information on each function.
Initialization
ADCl b_DevOpen Initialize and configure the driver.
ADCl 6&GetDevHandle Obrain a device handle.
K-DASDevInit Reset and initialize the device and driver.
Memory management
K_lntAlloc Allocate a buffer suitable for an interrupt-
mode A/D operation.
K-IntFree De-allocate an interrupt buffer that was
previously allocated with K~lnrAlloc.
K-MoveDataBuf Transfer acquired A/D samples between a
menmy buffer and an array.
Frame management
K_FreeFrame Free the memory used by a frame and
return the frame it to the pool of
available frames.
K-GetADFrame Obtain the handle to an A/D frame.
K_GetDOFrame Obtain the handle to a digital output
frame.
Frame-element management
KPClearFrame Set all the elelnelm Of aI1 A/D frdIIle t0
their default values.
K-GetBuf Get the values of an A/D frame's Buffer
Address and Number of Samples
elements.
K-GetChn Get the value of an A/D frame's Start
Channel element.
K-GetChnGAry Get the value of an A/D frame's
Channel-Gain Array Address element,
K-GetDOCurVal Get the value of a digital output frame's
Digital Output Value element.
Frame-element management (cont'd)
K_GetG Get the value of an A/D frame's Gain
Code element.
K-GetStartStopChn Get the values of an A/D frame's Srart
Channel and Stop Cbannet ete~nenr\.
K_GetStartStopG Get the values of an A/D frame`> Srarr
Channel, Srop Channel. and Gain Code
etenw1ts.
K-InitFrame Initialize a board's A/D circuitry and >CI
an A/D frame's elements to their default
YdlweS.
K-SetBuf Set the values of an A/D frame's Huff&
Address and Number of Samples
elements.
K-SetChn Set the value of an A/D frame's Srarr
Channel etemenr.
K-SetChnGAry Set the value of a frame's Channel-Gain
Array Address element.
K_SetG Set fbe value of a11A/D frdIlW'~ Gdill
Code element.
K_SetStartStopChn Set the VatLIes Of all A/D frdllle's Srdrt
Channel and Stop Channel elements.
K-SerStartStopG Set the vatues of an A/D fi-ame's Start
Channel, Stop Channel, and Gain Code
elements.
Frame-based operation control
K_IntStart Start an interrupt-mode A/D operation.
K-IntStatus Determine the srdtus of an interrupt-
mode A/D operation.
K-IntStop Abort an interrupt-mode A/D operation.
KpSync.`%drt Start a synchronous-mode A/D operation.
Immediate-execution operations
K-ADRead Read a single A/D value.
K_DIRead Read a single digital value.
KPDOWrite Write a single digital value.
Miscellaneous operations
KPGetErrMsg Get the address of an error message string
(available only as C-language function).
K-GetVer Detemine the driver revision and drivel
specification.
3.2 Function reference
This section contains reference entries for the Callable Functions. Tbc
entries appear one pet page and in ascending alphabetical order (by
function name). These reference entries provide the derails associated with
the use of each function.
This section is not a good resource for general and conceptual information
about writing Function Call Driver programs. Moreover, much of tlw
information presented here requites a thorough understanding of the
concepts presented in Chapter 2. Do not ncprct to write n Function Cdl
Driver program merely, by consthing the reference for the jurcriom yorr
entries
expect to u*c in yore program.
The info!-mation related to the following topics pertains to srvcral Caltabtr
Functions:
. the format of A/D values and the procedure to determine the votragr
that produced a specific A/D value
. the gain codes the driver mes to represent gains and the A/D input
ranges that correspond to each gain
. the teturn value for every call to a Callable Function
These topics are described in the neyt several paragraphs and referred to
throughout the reference entries that follow.
A/D values and There are thtee Callable Functions through which your program cau
corresponding acquire A/D values: K-ADRead, K-IntStart, and K_SyncStart. Although
voltages the method to create/assign a storage buffer for the acquired value(s) is
different for each of these functiotls, they all state the A/D value in the
same format. Consequently, the interpretation of the A/D data is the same
regatdtess of the function with which it was acquired.
The driver configuration file specifies two attributes that affect how you
should interpret A/D values: the A/D Number Type and the A/D Full
Scale Range. The possible values for these attributes are as follows:
. A/D Number Type: Sign/Magnitude or 2i Complement
. A/D Full Scale Range: ~3.2767 VOF +5.0 V
The procedure to determine the voltage that produced a particular A/D
value depends on the A/D Number Type. The two cases are presented
below. The following variables are used in botlr cases:
n nzngc is the maximum voltage in the range specified by the A/D Full
Scale Range, which is either 3.2767 V or 5.0 V.
. ADvalue is the value acquired by the A/D operation
Case 1 A/D Number Type = Sign/Magnitude
If bit 15 = 0,
ADvalue AND 7FFF
volrdge = x range
- 32,767
If bit 15 = I,
ADvalue AND 7FFF
volrage = x range
32,767
Cave 2 A/D Number Type = 2's Complement
If bit 15 = 0,
ADvalue
voltage = x range
32,767
If bit 15 = I,
voltage = (ADuah& AND 7FFF
x range
- 32,767
Gain codes The Function Call Driver uses gain codes to indicate gains. The valid gain
codes are 0, 1, 2. The table below lists the gain that corresponds to rach
gain code. Additionally, this table shows the A/D input range for both
settings of the A/D Full Scale Range (the A/D Full SC& Range is qxcificd
by the driver configuration file).
A/D input range for A/D input range for
gain
gain 1-3.2767 V *5.0 v
code
lidI-scale range full-scale range
0 1 *3.2767 V +5 v
1 10 i327.67 mV *500 mv
2 100 i32.767 mV *50 mv
Every call to a Callable Function returns an integer-type (16.bir) mum
value. A return value of 0 indicates that the function executed sutrrs~t%lly;
a non-zero return value indicates an error. The non-zero return values
correspond to error codes; these error codes and their corresponding rrron
are listed in Appendix A. Your program should always check a funcrion
cdtt's return vdlur and, in rtle case of an error, perfort an appropriate
action.
ADC 16-DevOpen
Purpose Initialize and configure the driver.
Prototype C
DASErr far Pascal ADCl6_DevOpen( char far * cJsFlt,
char far * numDevices );
Pascal
Function ADC16PDevOpen( Var c&File : char;
Var numDevicer : Integer ) : Word;
Visual Basic for Windows
ADCIGPDevOpen Lib "ADClG.dll" (ByVal c&Filt$,
numDevices As Integer) As Integer
c&File Driver configuration file
numDevices Number of devices defined in c&File. Valid values: 1, 2
Notes ADCl6-DevOpen initializes the driver according to the information in cfKFile.
On return, numDevices contains the number of devices for which &File conrains
configuratioo information.
ADCl6~DevOpen writes a zero value to OPO and OPl; this turns off the
ADC-16's r-&y 0 and relay 1.
Specify -1 for c&Fib to set the driver to its default configuration; the default
configuration specifies that the device is set as follows:
Board number 0 1
Board name ADC16 ADC16
Base address 300 Hex 308 Hex
Range i3.2767 V +3.2767 V
A/D Number Type SignMagnitude SignMagnitude
Interrupt level AHex F Hex
Illstalled STA-EX8s 0 0
ADC 16-GetDevHandle
Purpose Obtain a device handle.
Prototype C
DASErr far Pascal ADClb-GetDevHandle ( int dtvNumber,
void far * far * &Handle );
Function ADCl6_GetDevHandle( devNwnber : Inreger;
Var devHandle : Longint ) : Word;
Visual BASIC for Windows
ADCl G_GetDevHandle Lib "ADClb.dll" (ByVal devilirmrber As Integer.
devHandle As Long) As Integer
Parameters deuNwnber Device number. Valid values: 0, 1
d&Handle Device handle
Notes On return, devHandle contains the handle associated with the device identified
by &vNmber.
The value returned in deoHandle is intended to be used exclusively as an
argument to functions that require a device handle. Your program should not
modify the value returned in &Handle.
The driver supports up to two devices: a unique handle is associated wirh each
supported device.
In addition to obtaining a device handle, ADClb-GetDevHandle performs the
following tasks:
. aborts all in-progress A/D operations
n writes a 0 to OF0 and OPl
. checks if device identified by deuHandle is present
. checks if settings in configuration file match actual board settings
. initializes the board to its default state
K-ADRead
Purpose Read a single A/D value.
Prototype C
DASErr fat pascal K-ADRead( DDH devHandle, unsigned chat &an,
unsigned chat gain&de, void far * ADvalue );
Pascal
Function K_ADRead( devHandle : Longint; than : Byte:
gaincode : Byte; Vat ADvalue : Longint ) : Word;
Visual BASIC for Windows
K_ADRead Lib "ADCl6.dll" (ByVal devHandle As Long, ByVal cban As Integer,
ByVal gainCode As Integer, ADvalue As Long) As Integer
Parameters devHandle Handle to acquisition device
than Input channel. Valid values: 0, l,..., 7(m+l), where m is the
number of connected STA-EXS.
gainCode Gain code. Valid values: 0 = lx, I = 10x, 2 = 100x
ADvalue Storage location of acquired A/D value
Notes On mum, ADvalue contains the value read from channel cl/an (at thr gain
indicated by gain code) of the device identified by devHandle.
See page 29 for the procedute to detetmine the voltage that produced the value
returned in ADvalue.
See page 31 for the A/D voltage ranges that cortespond to each gain.
34 AS0AD(I;- I6 User's (:;uide - Rev. A
K ClearFrame
Purpose Set all the elements of an A/D frame to their default values.
Prototype C
DASErr far Pascal KPClearFrame( FRAMEH @ameHarrdk );
Pascal
Function K_ClearFrame( flameHandle : Longint ) : Word;
Visual Basic for Windows
K_CleatFrame Lib "ADCl6.dII" (Byvdl /FameHandle As Long) As lntegrt
Parameters j?ameHandle Frame handle
Notes On retutn, the elements in the frame identified by frameHandle contain the
following values:
Buffet Address 0
Start Channel 0
Stop Channel 0
Gain Code 0
Channel-Gain Array Address 0
Purpose Reset and initialize the device and dtiver.
Prototype C
DASErr far Pascal KPDASDevlnit( DDH devHandle );
Pascal
Ftmction K-DASDevlnit( devHandle : Longint ) : Word;
Visual BASIC for Windows
KPDASDevlnit Lib "ADClG.dll" (ByVal ahHandle As Long)
As Integer
Parameters devHandle Device handle
Notes K_DASDevInit pet-forms the following tasks:
. Aborts all in-progress A/D operations
. Wtites a 0 to 01'0 and OPl
. Checks if device identified by devHandle is present
. Checks if settings in configuration file match actual board settings
. loitializes the board to its defaLllt state
36 AS0AlX- I6 User's (;uide - Rev. A
KpDlRead
Purpose Read a single digital value.
Prototype C
DASErr far pascal K_DIRead( DDH deuHandk, unsigned char chnn.
void far * Dlualr~c );
Pascal
Function K_DIRead( devHandle : Longint; than : Byte;
Var D/value : Longint ) : Word;
Visual Basic for Windows
K-DIRead Lib "ADClG.dII" (ByVal devHandle As Long,
ByVal than As Integer, Dlvnl~le As Long) As Integer
Parameters deuHandle Device handle
chan Digital inpur channel. Valid value: 0
Dlualue Digital input value. Valid values: 0, 1, 2, 3
Notes On return, D/value contains the digital value read from cbannrl c/ma of rbr
device identified by &uHandle.
D/value is a 32-bit variable. The acquired digital value is stored in bits 0 and I:
the values in the remaining bits of DIvaLle are not well-defined. Tbr figure
below illustrates the format of D/value.
K DOWrite
Purpose Write a single digital value.
Prototype C
DASErr far pascal K-DOWrite( DDH deuHandle, unsigned char chun,
long DOvalue );
Pascal
Function K-DOWrite( devHandle : Longint; than : Byte;,
DOvalue : Longint ) : Word;
Visual Basic for Windows
K_DOWrite Lib "ADCl6.dII" (ByVal devHundle As Long,
ByVal than As Integer, ByVal DOvalue As Long) As Integer
Parameters devHandle Device handle
than Digiral output channel. Valid value: 0
DOvalue Digital output value. Valid values: 0, l,..., 31
Notes K-DOWrite outputs the value in DOvalue to channel cban on the device
identified by deuHandle
DOvalue is a 32-bit variable; the significance of the bits in DOvalue depeods on
if there is a connection between the board and an STA-EX8:
If the board is not connected to an STA-EM:
The output value comprises the values in bits 0 - 4; the values in bits 5 31
are not significant. This format is illustrated in the following figute:
If the board is connected to me or more STA-EX8:
The output value comprises the values in bits 0 and 1; the values in bits
2 - 31 are not significant. This format is illustrated in the following figure:
K-FreeFrame
Purpose Free rhe memory used by a frame and return the frame it to rhe pool of available
frames.
Prototype C
DASErr far Pascal K_FreeFrame( FRAMEH j%meHandle ):
Pascal
Fun&on K-FreeFrame( fiameHandit : Longinr ) : Word:
Visual Basic for Windows
K_FreeFrame Lib "ADCl6.dll" (ByVal j%neHandk As Long) As Inrcger
Parameters j?ameHandle Frame handle
Notes K-FreeFrame frees the memory used by the frame identified by frameHand& the
frame is rhen rerurned to the pool of available frames. The pool of available
frames initially contains wo A/D frames and two digirat ourput frames.
K-GetADFrame
Purpose Obrain the handle to an A/D frame.
Prototype C
DASErr far Pascal K-GecADFrame( DDH deuHandle,
FRAMEH far * jiameHandle );
Pascal
Funcrion KPGetADFrame( &Handle : Longint:
Var jhneHandle : Longinr ) : Word;
Visual Basic for Windows
KPGetADFrame Lib "ADCl6.dlt" (ByVal dcvHandle As Long,
fiameHandle As Long) As Integer
Parameters deuHandle Device handle
fiameHandle Handle to A/D frame
Notes On return, fFameHandle contains the handle co an A/D frame associared with rhe
device identified by devHandle.
K GetBuf
Purpose Get the values of an A/D frame's Buffer Address and Number of Samples
elements.
Prototype C
DASErr far pascal K_GetBuf( FRAMEH jkmeHandlp, void far ' far ' brifAddr,
long far * sampler );
Function K_GetBuf( fFameHandlr : Longint; Var bufA&r : Integer;
Vat samples : Longint ) : Word;
Visual Basic for Windows
K-GetBuf Lib "ADCI6.dll" (ByVal jameHandle As Long, br@& As Long.
samples As Long) As Integer
Parameters jGamcHandk Frame handle
bufAddr Buffer Address
sampler Number of Samples
Notes On return, the following parameters contain the value of an cle~ne~~tin rhr frame
identified by JFameHandlr:
n bztfAddr contains the value of the Buffer Address elemenr
. samples contains the value of the Number of Samples elemeur
K-GetC hn
Purpose Get the value of an A/D frame's Srart Channel element
Prototype C
DASErr far pascal K_GetChn( FRAMEH fi ameHandle, short fal- * &an );
Pascal
Function K-GetChn( jkameHandle : Longint; Var cban : Word ) : Word;
Visual Basic for Windows
K-GetChn Lib "ADCI 6.dll" (ByVal fjameHandle As Long, than As Integer)
As Integer
Parameters frameHandle Handle to A/D frame
than Start Channel. Valid values: 0, 1,...,7(m+l), where m is the
number of connected STA-EX8.
Notes On return, than contains the value of the Stdl-t Channel elemeot in the frame
identified by frameHandle.
K-GetChnGAry
P