DataAcq SDK
User’s Manual
DASDK-900-01 Rev. A / January 2005
www.keithley.com
A GR
EATER MEASURE OF CONFIDENCE
WARRANTY
Keithley Instruments, Inc. warrants this product to be free from defects in material and workmanship for a period of 3 years from
date of shipment.
Keithley Instruments, Inc. warrants the following items for 90 days from the date of shipment: probes, cables, rechargeable batteries,
diskettes, and documentation.
During the warranty period, we will, at our option, either repair or replace any product that proves to be defective.
To exercise this warranty, write or call your local Keithley representative, or contact Keithley headquarters in Cleveland, Ohio.
You will be given prompt assistance and return instructions. Send the product, transportation prepaid, to the indicated service facility. Repairs will be made and the product returned, transportation prepaid. Repaired or replaced products are warranted for the balance of the original warranty period, or at least 90 days.
LIMITATION OF WARRANTY
This warranty does not apply to defects resulting from product modification without Keithley’s express written consent, or misuse
of any product or part. This warranty also does not apply to fuses, software, non-rechargeable batteries, damage from battery leakage, or problems arising from normal wear or failure to follow instructions.
THIS WARRANTY IS IN LIEU OF ALL OTHER WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING ANY IMPLIED
WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR USE. THE REMEDIES PROVIDED HEREIN
ARE BUYER’S SOLE AND EXCLUSIVE REMEDIES.
NEITHER KEITHLEY INSTRUMENTS, INC. NOR ANY OF ITS EMPLOYEES SHALL BE LIABLE FOR ANY DIRECT,
INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF ITS INSTRUMENTS AND SOFTWARE EVEN IF KEITHLEY INSTRUMENTS, INC., HAS BEEN ADVISED IN ADVANCE OF THE
POSSIBILITY OF SUCH DAMAGES. SUCH EXCLUDED DAMAGES SHALL INCLUDE, BUT ARE NOT LIMITED TO:
COSTS OF REMOVAL AND INSTALLATION, LOSSES SUSTAINED AS THE RESULT OF INJURY TO ANY PERSON,
OR DAMAGE TO PROPERTY.
A G R E A T E R M E A S U R E O F C O N F I D E N C E
Keithley Instruments, Inc.
Corporate Headquarters • 28775 Aurora Road • Cleveland, Ohio 44139
440-248-0400 • Fax: 440-248-6168 • 1-888-KEITHLEY (534-8453) • www.keithley.com
12/04
DataAcq SDK
User’s Manual
©2005, Keithley Instruments, Inc.
All rights reserved.
First Printing, January 2005
Cleveland, Ohio, U.S.A.
Document Number: DASDK-900-01
Rev. A
Manual Print History
The print history shown below lists the printing dates of all Revisions and Addenda created for this manual. The Revision Level letter increases alphabetically as the manual undergoes subsequent updates. Addenda, which are released
between Revisions, contain important change information that the user should incorporate immediately into the manual.
Addenda are numbered sequentially. When a new Revision is created, all Addenda associated with the previous Revision
of the manual are incorporated into the new Revision of the manual. Each new Revision includes a revised copy of this
print history page.
Revision A (Document Number DASDK-900-01A)........................................................................... January 2005
All Keithley product names are trademarks or registered trademarks of Keithley Instruments, Inc.
Other brand and product names are trademarks or registered trademarks of their respective holders.
Safety Precautions
The following safety precautions should be observed before using
this product and any associated instrumentation. Although some instruments and accessories would normally be used with non-hazardous voltages, there are situations where hazardous conditions
may be present.
This product is intended for use by qualified personnel who recognize shock hazards and are familiar with the safety precautions required to avoid possible injury. Read and follow all installation,
operation, and maintenance information carefully before using the
product. Refer to the manual for complete product specifications.
If the product is used in a manner not specified, the protection provided by the product may be impaired.
The types of product users are:
Responsible body is the individual or group responsible for the use
and maintenance of equipment, for ensuring that the equipment is
operated within its specifications and operating limits, and for ensuring that operators are adequately trained.
Operators use the product for its intended function. They must be
trained in electrical safety procedures and proper use of the instrument. They must be protected from electric shock and contact with
hazardous live circuits.
Maintenance personnel perform routine procedures on the product to keep it operating properly, for example, setting the line voltage or replacing consumable materials. Maintenance procedures
are described in the manual. The procedures explicitly state if the
operator may perform them. Otherwise, they should be performed
only by service personnel.
Service personnel are trained to work on live circuits, and perform
safe installations and repairs of products. Only properly trained service personnel may perform installation and service procedures.
Keithley products are designed for use with electrical signals that
are rated Measurement Category I and Measurement Category II, as
described in the International Electrotechnical Commission (IEC)
Standard IEC 60664. Most measurement, control, and data I/O signals are Measurement Category I and must not be directly connected to mains voltage or to voltage sources with high transient overvoltages. Measurement Category II connections require protection
for high transient over-voltages often associated with local AC
mains connections. Assume all measurement, control, and data I/O
connections are for connection to Category I sources unless otherwise marked or described in the Manual.
Exercise extreme caution when a shock hazard is present. Lethal
voltage may be present on cable connector jacks or test fixtures.
The American National Standards Institute (ANSI) states that a
shock hazard exists when voltage levels greater than 30V RMS,
42.4V peak, or 60VDC are present. A good safety practice is to ex-
pect that hazardous voltage is present in any unknown circuit
before measuring.
Operators of this product must be protected from electric shock at
all times. The responsible body must ensure that operators are prevented access and/or insulated from every connection point. In
some cases, connections must be exposed to potential human contact. Product operators in these circumstances must be trained to
protect themselves from the risk of electric shock. If the circuit is
capable of operating at or above 1000 volts, no conductive part of
the circuit may be exposed.
Do not connect switching cards directly to unlimited power circuits.
They are intended to be used with impedance limited sources.
NEVER connect switching cards directly to AC mains. When connecting sources to switching cards, install protective devices to limit
fault current and voltage to the card.
Before operating an instrument, make sure the line cord is connected to a properly grounded power receptacle. Inspect the connecting
cables, test leads, and jumpers for possible wear, cracks, or breaks
before each use.
When installing equipment where access to the main power cord is
restricted, such as rack mounting, a separate main input power disconnect device must be provided, in close proximity to the equipment and within easy reach of the operator.
For maximum safety, do not touch the product, test cables, or any
other instruments while power is applied to the circuit under test.
ALWAYS remove power from the entire test system and discharge
any capacitors before: connecting or disconnecting cables or jumpers, installing or removing switching cards, or making internal
changes, such as installing or removing jumpers.
Do not touch any object that could provide a current path to the common side of the circuit under test or power line (earth) ground. Always
make measurements with dry hands while standing on a dry, insulated
surface capable of withstanding the voltage being measured.
The instrument and accessories must be used in accordance with its
specifications and operating instructions or the safety of the equipment may be impaired.
Do not exceed the maximum signal levels of the instruments and accessories, as defined in the specifications and operating information, and as shown on the instrument or test fixture panels, or
switching card.
When fuses are used in a product, replace with same type and rating
for continued protection against fire hazard.
Chassis connections must only be used as shield connections for
measuring circuits, NOT as safety earth ground connections.
If you are using a test fixture, keep the lid closed while power is applied to the device under test. Safe operation requires the use of a
lid interlock.
5/03
If a screw is present, connect it to safety earth ground using the
wire recommended in the user documentation.
!
The symbol on an instrument indicates that the user should refer to the operating instructions located in the manual.
The symbol on an instrument shows that it can source or measure 1000 volts or more, including the combined effect of normal
and common mode voltages. Use standard safety precautions to
avoid personal contact with these voltages.
The symbol indicates a connection terminal to the equipment
frame.
The WARNING heading in a manual explains dangers that might
result in personal injury or death. Always read the associated information very carefully before performing the indicated procedure.
The CAUTION heading in a manual explains hazards that could
damage the instrument. Such damage may invalidate the warranty.
Instrumentation and accessories shall not be connected to humans.
Before performing any maintenance, disconnect the line cord and
all test cables.
To maintain protection from electric shock and fire, replacement
components in mains circuits, including the power transformer, test
leads, and input jacks, must be purchased from Keithley Instruments. Standard fuses, with applicable national safety approvals,
may be used if the rating and type are the same. Other components
that are not safety related may be purchased from other suppliers as
long as they are equivalent to the original component. (Note that selected parts should be purchased only through Keithley Instruments
to maintain accuracy and functionality of the product.) If you are
unsure about the applicability of a replacement component, call a
Keithley Instruments office for information.
To clean an instrument, use a damp cloth or mild, water based
cleaner. Clean the exterior of the instrument only. Do not apply
cleaner directly to the instrument or allow liquids to enter or spill on
the instrument. Products that consist of a circuit board with no case
or chassis (e.g., data acquisition board for installation into a computer) should never require cleaning if handled according to instructions. If the board becomes contaminated and operation is affected,
the board should be returned to the factory for proper cleaning/servicing.
Table of Contents
About this Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
Intended Audience. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
What You Should Learn from this Manual. . . . . . . . . . . . . . . . . xiii
Organization of this Manual. . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiv
Conventions Used in this Manual . . . . . . . . . . . . . . . . . . . . . . . . xiv
Related Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
Where to Get Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
Chapter 1: Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
What is the DataAcq SDK? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Using the DataAcq SDK Online Help . . . . . . . . . . . . . . . . . . . . . . . 4
About the Examples Programs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
About the Library Function Calling Conventions. . . . . . . . . . . . . 7
Chapter 2: Function Summary . . . . . . . . . . . . . . . . . . . . . . . . 9
Data Acquisition Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Information Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Initialization and Termination Functions . . . . . . . . . . . . . . . 21
Configuration Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Operation Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Data Conversion Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Data Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Buffer Management Functions . . . . . . . . . . . . . . . . . . . . . . . . 31
Buffer List Management Functions . . . . . . . . . . . . . . . . . . . . 33
vii
Contents
Chapter 3: Using the DataAcq SDK . . . . . . . . . . . . . . . . . . . 35
System Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Initializing a Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Specifying a Subsystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Configuring a Subsystem. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Handling Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Handling Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Releasing the Subsystem and the Driver. . . . . . . . . . . . . . . . 40
Analog and Digital I/O Operations . . . . . . . . . . . . . . . . . . . . . . . 41
Data Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Resolution. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Specifying the Channel Type . . . . . . . . . . . . . . . . . . . . . . 43
Specifying a Single Channel . . . . . . . . . . . . . . . . . . . . . . 44
Specifying One or More Channels . . . . . . . . . . . . . . . . . 44
Specifying the Channel List Size . . . . . . . . . . . . . . . 45
Specifying the Channels in the Channel List . . . . . 46
Inhibiting Channels in the Channel List . . . . . . . . . 47
Specifying Synchronous Digital I/O Values
in the Channel List . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Ranges. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Gains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Specifying the Gain for a Single Channel . . . . . . . . . . . 51
Specifying the Gain for One or More Channels . . . . . . 51
Filters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Data Flow Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Single-Value Operations . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Continuous Operations . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Continuous Post-Trigger Mode . . . . . . . . . . . . . . . . 57
Continuous Pre-Trigger Mode . . . . . . . . . . . . . . . . . 58
viii
Continuous About-Trigger Mode. . . . . . . . . . . . . . . 59
Triggered Scan Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Scan-Per-Trigger Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Internal Retrigger Mode . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Retrigger Extra Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Clock Sources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Internal Clock Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
External Clock Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Extra Clock Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Trigger Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Software (Internal) Trigger Source . . . . . . . . . . . . . . . . . 68
External Digital (TTL) Trigger Source . . . . . . . . . . . . . . 68
External Analog Threshold (Positive) Trigger Source . 69
External Analog Threshold (Negative) Trigger Source 69
Analog Event Trigger Source . . . . . . . . . . . . . . . . . . . . . . 70
Digital Event Trigger Source . . . . . . . . . . . . . . . . . . . . . . 70
Timer Event Trigger Source . . . . . . . . . . . . . . . . . . . . . . . 70
Extra Trigger Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Buffers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Ready Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Inprocess Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Done Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Buffer and Queue Management . . . . . . . . . . . . . . . . . . . 76
Buffer Wrap Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
DMA and Interrupt Resources . . . . . . . . . . . . . . . . . . . . . . . . 79
Counter/Timer Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Counter/Timer Operation Mode . . . . . . . . . . . . . . . . . . . . . . 82
Event Counting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Up/Down Counting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Contents
ix
Contents
Frequency Measurement . . . . . . . . . . . . . . . . . . . . . . . . . 86
Using the Windows Timer. . . . . . . . . . . . . . . . . . . . . 86
Using a Pulse of a Known Duration . . . . . . . . . . . . 87
Edge-to-Edge Measurement . . . . . . . . . . . . . . . . . . . . . . 90
Rate Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
One-Shot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Repetitive One-Shot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
C/T Clock Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Internal C/T Clock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
External C/T Clock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Internally Cascaded Clock . . . . . . . . . . . . . . . . . . . . . . . 103
Extra C/T Clock Source . . . . . . . . . . . . . . . . . . . . . . . . . 104
Gate Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Software Gate Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
High-Level Gate Type . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Low-Level Gate Type . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Low-Edge Gate Type . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
High-Edge Gate Type . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Any Level Gate Type . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
High-Level, Debounced Gate Type . . . . . . . . . . . . . . . 107
Low-Level, Debounced Gate Type . . . . . . . . . . . . . . . . 107
High-Edge, Debounced Gate Type . . . . . . . . . . . . . . . . 107
Low-Edge, Debounced Gate Type . . . . . . . . . . . . . . . . 108
Level, Debounced Gate Type . . . . . . . . . . . . . . . . . . . . . 108
Pulse Output Types and Duty Cycles . . . . . . . . . . . . . . . . . 108
Simultaneous Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Chapter 4: Programming Flowcharts. . . . . . . . . . . . . . . . . 113
Single-Value Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Continuous Buffered Input Operations . . . . . . . . . . . . . . . . . . . 117
x
Continuous Buffered Output Operations. . . . . . . . . . . . . . . . . . 119
Event Counting Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Up/Down Counting Operations . . . . . . . . . . . . . . . . . . . . . . . . . 123
Frequency Measurement Operations . . . . . . . . . . . . . . . . . . . . . 125
Edge-to-Edge Measurement Operations. . . . . . . . . . . . . . . . . . . 127
Pulse Output Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Simultaneous Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Chapter 5: Product Support . . . . . . . . . . . . . . . . . . . . . . . . 149
Appendix A: Sample Code . . . . . . . . . . . . . . . . . . . . . . . . . 153
Single-Value Analog Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
Declare Variables and User Functions . . . . . . . . . . . . . . . . . 154
Initialize the Driver. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Get a Handle to the Subsystem . . . . . . . . . . . . . . . . . . . . . . . 156
Set the DataFlow to Single Value . . . . . . . . . . . . . . . . . . . . . 156
Configure the Subsystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Acquire a Single Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Convert the Value to Voltage . . . . . . . . . . . . . . . . . . . . . . . . 157
Release the Subsystem and Terminate the Session. . . . . . . 158
Handle Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Continuous Analog Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
Declare Variables and User Functions . . . . . . . . . . . . . . . . . 159
Initialize the Driver. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Get a Handle to the Subsystem . . . . . . . . . . . . . . . . . . . . . . . 162
Set the DataFlow to Continuous . . . . . . . . . . . . . . . . . . . . . . 162
Specify the Channel List and Channel Parameters . . . . . . 162
Specify the Clocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Specify DMA Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Set Up Window Handle and Buffering . . . . . . . . . . . . . . . . 164
Configure the Subsystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Contents
xi
Contents
Start the Continuous Analog Input Operation . . . . . . . . . . 165
Deal with Messages and Buffers. . . . . . . . . . . . . . . . . . . . . . 165
Convert Values to Voltage . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Clean Up. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Handle Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
xii
This manual describes how to get started using the DataAcq SDKTM
(Software Development Kit) to develop application programs for
data acquisition devices that conform to the DT-Open Layers
standard.
Intended Audience
This document is intended for engineers, scientists, technicians,
OEMs, system integrators, or others responsible for developing
application programs using Microsoft® Developer’s Studio
(version 6.0 and higher) to perform data acquisition operations.
It is assumed that you are a proficient programmer, that you are
experienced programming in the Windows® 2000 or Windows XP
operating environment on the IBM PC or compatible computer
platform, and that you have familiarity with data acquisition
principles and the requirements of your application.
About this Manual
TM
What You Should Learn from this Manual
This manual provides installation instructions for Windows 2000 and
Windows XP, summarizes the functions provided by the DataAcq
SDK, and describes how to use the functions to develop a data
acquisition program. Using this manual, you should be able to
successfully install the DataAcq SDK and get started writing an
application program for data acquisition.
This manual is intended to be used with the online help for the
DataAcq SDK, which you can find in the same program group as the
DataAcq SDK software. The online help for the DataAcq SDK
contains all of the specific reference information for each of the
functions, error codes, and Windows messages.
xiii
About this Manual
Organization of this Manual
This manual is organized as follows:
• Chapter 1, “Overview,” tells how to install the DataAcq SDK in
Windows 2000 and Windows XP.
• Chapter 2, “Function Summary,” summarizes the functions
provided in the DataAcq SDK.
• Chapter 3, “Using the DataAcq SDK,” describes the operations
that you can perform using the DataAcq SDK.
• Chapter 4, “Programming Flowcharts,” provides programming
flowcharts for using the functions provided in the DataAcq SDK.
• Chapter 5, “Product Support,” describes how to get help if you
have trouble using the DataAcq SDK.
• Appendix A, “Sample Code,” provides code fragments that
illustrate the use of the functions in the DataAcq SDK.
• An index completes this manual.
xiv
Conventions Used in this Manual
The following conventions are used in this manual:
• Notes provide useful information that requires special emphasis,
cautions provide information to help you avoid losing data or
damaging your equipment, and warnings provide information to
help you avoid catastrophic damage to yourself or your
equipment.
• Items that you select or type are shown in bold. Function names
also appear in bold.
• Code fragments are shown in courier font.
Related Information
Refer to the following documentation for more information on using
the DataAcq SDK:
• DataAcq SDK Online Help. This Windows help file is located in
the same program group as the DataAcq SDK software and
contains all of the specific reference information for each of the
functions, error codes, and Windows messages provided by the
DataAcq SDK. Refer to page 4 for information on how to open
this help file.
• Device-specific documentation, which consists of a getting
started manual and a user’s manual. The getting started manual
describes how to install the data acquisition device, how to install
the device driver for the device, and how to get started using the
device. The user’s manual describes the features of the device
and the capabilities supported by the device driver for the device.
These manuals are on the Keithley CD
• Windows 2000 or Windows XP documentation.
• For C programmers, refer to Microsoft C Reference, Document
Number LN06515-1189, Microsoft Corporation, and The C
Programming Language, Brian W. Kernighan and Dennis Ritchie,
Prentice Hall, 1988, 1987 Bell Telephone Laboratories, Inc,
ISBN 0-13-109950-7.
TM
About this Manual
.
Where to Get Help
Should you run into problems installing or using the DataAcq SDK,
the Keithley Technical Support Department is available to provide
technical assistance.
xv
About this Manual
xvi
1
Overview
What is the DataAcq SDK? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Using the DataAcq SDK Online Help . . . . . . . . . . . . . . . . . . . . . . . 4
About the Examples Programs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
About the Library Function Calling Conventions. . . . . . . . . . . . . 7
1
Chapter 1
What is the DataAcq SDK?
The DataAcq SDK is a programmer’s DLL (Dynamic Linked Library)
that supports Keithley’s data acquisition devices under Microsoft
Windows 2000 and Windows XP.
The DataAcq SDK functions are fully compatible with DT-Open
Layers™, which is a set of standards for developing integrated,
modular application programs under Windows.
Because DT-Open Layers is modular and uses Windows DLLs, you
can add support for a new data acquisition device at any time. Just
add the new DT-Open Layers device driver, modify your code to
incorporate the features of the new device, and then recompile the
code. All calls to DataAcq SDK functions currently in your
application program can remain untouched.
2
Installation
The DataAcq SDK is installed automatically when you install the
device driver for the module. Refer to your getting started manual for
more information.
Overview
1
1
1
1
1
1
1
1
1
3
Chapter 1
Using the DataAcq SDK Online Help
The DataAcq SDK User’s Manual is intended to be used with the
online help for the DataAcq SDK. The online help contains all of the
specific reference information for each of the functions, error codes,
and Windows messages not included in this manual.
To open the online help file, select DataAcq SDK/DataAcq SDK
Help from the Windows Start menu.
4
About the Examples Programs
To help you understand more about using the functions of the
DataAcq SDK in an actual program, the DataAcq SDK provides a C
example program (CEXMPL32.EXE). This example program allows
you to configure any of the subsystems on the data acquisition
device. The source code is located in the \Examples\CExample
directory. Resource files are also provided.
Overview
1
1
In addition to CEXMPL.EXE, the following simple example programs
are also provided. These programs are designed to use minimum
Windows user interface code, while demonstrating the functionality
of the DataAcq SDK. Source code and resource files are provided for
each of these programs:
• ContAdc − Opens the first available DT-Open Layers device,
opens and configures an A/D subsystem, and performs
continuous operations. The results are displayed in a dialog box.
• ContDac − Opens the first available DT-Open Layers device,
opens and configures a D/A subsystem, and performs
continuous operations outputting a square wave. The results are
displayed in a dialog box.
• DtConsole − Opens the first available DT-Open Layers device,
opens and configures an A/D subsystem, and performs a
continuous A/D operation on a console screen.
• GenerateFreq − Opens the first available DT-Open Layers device,
opens and configures a C/T subsystem, and continuously
outputs a pulse. The results are displayed in a dialog box.
• MeasureFreq − Opens the first available DT-Open Layers device,
opens and configures a C/T subsystem, and continuously
measures a pulse. The results are displayed in a dialog box.
1
1
1
1
1
1
• SvAdc − Opens the first available DT-Open Layers device, opens
and configures an A/D subsystem, and performs a single-value
operation. The results are displayed in a message box.
1
5
Chapter 1
• SvDac − Opens the first available DT-Open Layers device, opens
and configures a D/A subsystem, and performs a single-value
operation with maximum positive and maximum negative range.
The results are displayed in a message box.
• SvDin − Opens the first available DT-Open Layers device, opens
and configures a DIN subsystem, and performs a single-value
operation. The results are displayed in a message box.
• SvDout − Opens the first available DT-Open Layers device, opens
and configures a DOUT subsystem, and performs a single-value
operation. The results are displayed in a message box.
• ThermoAdc − Opens the first available DT-Open Layers device,
opens and configures an A/D subsystem, and performs a
thermocouple measurement. The results are displayed in a dialog
box.
Each example program provided in the DataAcq SDK comes with the
MSVC.DSW (workspace) and MSVC.DSP (project) files for use in the
integrated development environment provided by the Microsoft
Developer’s Studio. No special switches are necessary beyond
instructing the IDE to create a Windows EXE or DLL.
Note: The DataAcq SDK installation program automatically
includes an environment variable (DA_SDK). All the example
programs use this environment variable; therefore, you can build the
example programs without adding any include or library files to
your projects.
6
About the Library Function Calling Conventions
The DataAcq SDK functions adhere to the Microsoft Pascal calling
conventions. You can find prototypes for these functions in the
include files OLDAAPI.H and OLMEM.H. It is recommended that
you follow these calling conventions for proper operation.
DataAcq SDK functions return an ECODE value, which is an
unsigned long value indicating the status of the requested function. It
is recommended that you check the return status value for an error
condition using the symbolic constants defined in the include files.
This practice is illustrated in the C example program
(CEXMPL32.EXE).
Note: For detailed information on the error codes, refer to the
DataAcq SDK online help.
Overview
1
1
1
1
1
1
1
1
1
7
Chapter 1
8
2
Function Summary
Data Acquisition Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Data Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
9
Chapter 2
Data Acquisition Functions
The following groups of data acquisition functions are available:
• Information functions,
• Initialization and Termination functions,
• Configuration functions,
• Operation functions, and
• Data Conversion functions.
These functions are briefly described in the following subsections.
Note: For specific information about each of these functions, refer
to the DataAcq SDK online help. See page 4 for information on
opening the online help file.
10
Information Functions
To determine the capabilities of your installed devices, subsystems
on each device, and software, use the Information functions listed in
Table 1.
Table 1: Information Functions
Query about Function Description
Devices olDaEnumBoards Lists all currently installed DT-Open
Layers data acquisition devices,
drivers, and driver parameters.
olGetBoardInfo Gets the driver name, model name,
and instance number of the specified
board, based on its board name.
Table 1: Information Functions (cont.)
Function Summary
Query about Function Description
Devices (cont.) olDaGetDeviceName Gets the full name of the specified
device (this name is set by the driver
as part of the installation procedure).
Subsystems olDaEnumSubSystems Lists the names, types, and element
number for each subsystem
supported by the specified device.
olDaGetDevCaps Returns the number of elements
available for the specified subsystem
on the specified device.
olDaGetSSCaps Returns information about whether
the specified subsystem capability is
supported and/or the number of
capabilities supported. Refer to
Ta b l e 2 for a list of possible
capabilities and return values.
olDaGetSSCapsEx Returns information about extended
subsystem capabilities. Refer to
Ta b l e 3 for a list of possible
capabilities and return values.
olDaEnumBoardsEx Lists all currently-installed DT-Open
Layers DataAcq drivers and returns
some registry information for each.
2
2
2
2
2
2
olDaEnumSSCaps Lists the possible settings for the
specified subsystem capabilities,
including filters, ranges, gains, and
resolution.
olDaGetDASSInfo Returns the subsystem type and
element number of the specified
subsystem with the specified device
handle.
2
2
2
11
Chapter 2
Table 1: Information Functions (cont.)
Query about Function Description
Subsystems
(cont.)
Software olDaGetDriverVersion Returns the device driver version
olDaGetQueueSize Returns the size of the specified
queue (ready, done or inprocess) for
the specified subsystem. The size
indicates the number of buffers on
the specified queue.
olDaEnumSSList Lists all subsystems on the
simultaneous start list.
number.
olDaGetVersion Returns the software version of the
DataAcq SDK.
olDaGetErrorString Returns the string that corresponds
to a device error code value.
Table 2 lists the subsystem capabilities that you can query using the
olDaGetSSCaps function; this function returns values as integers.
Table 3 lists the subsystem capabilities that you can query using the
olDaGetSSCapsEx function; this function returns values as
floating-point numbers. Note that capabilities may be added as new
devices are developed; for the most recent set of capabilities, refer to
the DataAcq SDK online help.
12
Table 2: Capabilities to Query with olDaGetSSCaps
Query about Capability Function Returns
Function Summary
2
Data Flow
Mode
Simultaneous
Operations
Pausing
Operations
Windows
Messaging
Buffering OLSSC_SUP_BUFFERING Nonzero if subsystem supports
OLSSC_SUP_SINGLEVALUE Nonzero if subsystem supports
single-value operations.
OLSSC_SUP_CONTINUOUS Nonzero if subsystem supports
continuous post-trigger
operations.
OLSSC_SUP_CONTINUOUS_
PRETRIG
OLSSC_SUP_CONTINUOUS_
ABOUTTRIG
OLSSC_SUP_
SIMULTANEOUS_START
OLSSC_SUP_PAUSE Nonzero if subsystem supports
OLSSC_SUP_POSTMESSAGE Nonzero if subsystem supports
OLSSC_SUP_WRPSINGLE Nonzero if subsystem supports
Nonzero if subsystem supports
continuous pre-trigger operations.
Nonzero if subsystem supports
continuous about-trigger (both
pre- and post-trigger) operations.
Nonzero if subsystem can be
started simultaneously with
another subsystem on the device.
pausing during continuous
operation.
asynchronous operations.
buffering.
single-buffer wrap mode.
2
2
2
2
2
2
OLSSC_SUP_WRPMULTIPLE Nonzero if subsystem supports
multiple-buffer wrap mode.
OLSSC_SUP_
INPROCESSFLUSH
Nonzero if subsystem supports
the transferring of data from a
buffer on a subsystem’s
inprocess queue.
2
2
13
Chapter 2
Table 2: Capabilities to Query with olDaGetSSCaps (cont.)
Query about Capability Function Returns
DMA OLSSC_NUMDMACHANS Number of DMA channels
supported.
Triggered
Scan Mode
OLSSC_SUP_GAPFREE_
NODMA
OLSSC_SUP_GAPFREE_
SINGLEDMA
OLSSC_SUP_GAPFREE_
DUALDMA
OLSSC_SUP_TRIGSCAN Nonzero if subsystem supports
OLSSC_MAXMULTISCAN Maximum number of scans per
OLSSC_SUP_RETRIGGER_
SCAN_PER_TRIGGER
OLSSC_SUP_RETRIGGER_
INTERNAL
Nonzero if subsystem supports
gap-free continuous operation
with no DMA.
Nonzero if subsystem supports
gap-free continuous operation
with a single DMA channel.
Nonzero if subsystem supports
gap-free continuous operation
with two DMA channels.
triggered scans.
trigger or retrigger supported by
the subsystem.
Nonzero if subsystem supports
scan-per-trigger triggered scan
mode (retrigger is the same as
the initial trigger source).
Nonzero if subsystem supports
internal retriggered scan mode.
(retrigger source is on the device;
initial trigger is any available
trigger source).
14
OLSSC_SUP_RETRIGGER_
EXTRA
Nonzero if subsystem supports
retrigger-extra triggered scan
mode (retrigger can be any
supported trigger source; initial
trigger is any available trigger
source).
Table 2: Capabilities to Query with olDaGetSSCaps (cont.)
Function Summary
Query about Capability Function Returns
Channel-Gain
List
Channel-Gain
List (cont.)
Gain OLSSC_SUP_PROGRAMGAIN Nonzero if subsystem supports
OLSSC_CGLDEPTH Number of entries in channel-gain
list.
OLSSC_SUP_RANDOM_CGL Nonzero if subsystem supports
random channel-gain list setup.
OLSSC_SUP_SEQUENTIAL_
CGL
OLSSC_SUP_
ZEROSEQUENTIAL_CGL
OLSSC_SUP_
SIMULTANEOUS_SH
OLSSC_SUP_CHANNELLIST_
INHIBIT
Nonzero if subsystem supports
sequential channel-gain list
setup.
Nonzero if subsystem supports
sequential channel-gain list setup
starting with channel zero.
Nonzero if subsystem supports
simultaneous sample-and-hold
operations.The channel-gain list
must be set up with both a
sample channel and a hold
channel.
Nonzero if subsystem supports
channel-gain list entry inhibition.
programmable gain.
2
2
2
2
2
2
OLSSC_NUMGAINS Number of gain selections.
OLSSC_SUP_SINGLEVALUE_
AUTORANGE
Synchronous
Digital I/O
I/O Channels OLSSC_NUMCHANNELS Number of I/O channels.
OLSSC_SUP_
SYNCHRONOUS_DIGITALIO
OLSSC_MAXDIGITALIOLIST_
VALU E
Nonzero if subsystem supports
autoranging operations.
Nonzero if subsystem supports
synchronous digital output
operations.
Maximum value for synchronous
digital output channel list entry.
2
2
2
15
Chapter 2
Table 2: Capabilities to Query with olDaGetSSCaps (cont.)
Query about Capability Function Returns
Channel Type OLSSC_SUP_SINGLEENDED Nonzero if subsystem supports
single-ended inputs.
OLSSC_MAXSECHANS Number of single-ended
channels.
OLSSC_SUP_DIFFERENTIAL Nonzero if subsystem supports
differential inputs.
OLSSC_MAXDICHANS Number of differential channels.
Filters OLSSC_SUP_
FILTERPERCHAN
OLSSC_NUMFILTERS Number of filter selections.
Ranges OLSSC_NUMRANGES Number of range selections.
OLSSC_SUP_
RANGEPERCHANNEL
Resolution OLSSC_SUP_
SWRESOLUTION
OLSSC_NUMRESOLUTIONS Number of different resolutions
Data
Encoding
OLSSC_SUP_BINARY Nonzero if subsystem supports
OLSSC_SUP_2SCOMP Nonzero if subsystem supports
Nonzero if subsystem supports
filtering per channel.
Nonzero if subsystem supports
different range settings for each
channel.
Nonzero if subsystem supports
software-programmable
resolution.
that you can program for the
subsystem.
binary encoding.
twos complement encoding.
16
Table 2: Capabilities to Query with olDaGetSSCaps (cont.)
Function Summary
Query about Capability Function Returns
Triggers OLSSC_SUP_SOFTTRIG Nonzero if subsystem supports
internal software trigger.
OLSSC_SUP_EXTERNTRIG Nonzero if subsystem supports
external digital (TTL) trigger.
OLSSC_SUP_
THRESHTRIGPOS
OLSSC_SUP_
THRESHTRIGNEG
OLSSC_SUP_
ANALOGEVENTTRIG
OLSSC_SUP_
DIGITALEVENTTRIG
OLSSC_SUP_
TIMEREVENTTRIG
OLSSC_
NUMEXTRATRIGGERS
Clocks OLSSC_SUP_INTCLOCK Nonzero if subsystem supports
Nonzero if subsystem supports
positive analog threshold trigger.
Nonzero if subsystem supports
negative analog threshold trigger.
Nonzero if subsystem supports
analog event trigger.
Nonzero if subsystem supports
digital event trigger.
Nonzero if subsystem supports
timer event trigger.
Number of extra trigger sources
supported.
internal clock.
2
2
2
2
2
2
OLSSC_SUP_EXTCLOCK Nonzero if subsystem supports
external clock.
OLSSC_NUMEXTRACLOCKS Number of extra clock sources.
OLSSC_SUP_
SIMULTANEOUS_CLOCKING
Non-zero if subsystem supports
simultaneous clocking of all
channels.
2
2
2
17
Chapter 2
Table 2: Capabilities to Query with olDaGetSSCaps (cont.)
Query about Capability Function Returns
Counter/Timer
Modes
OLSSC_SUP_CASCADING Nonzero if subsystem supports
cascading.
OLSSC_SUP_CTMODE_
COUNT
OLSSC_SUP_CTMODE_RATE Nonzero if subsystem supports
OLSSC_SUP_CTMODE_
ONESHOT
OLSSC_SUP_CTMODE_
ONESHOT_RPT
OLSSC_SUP_CTMODE_
UP_DOWN
OLSSC_SUP_CTMODE_
MEASURE
OLSSC_SUP_CTMODE_
CONT_MEASURE
Nonzero if subsystem supports
event counting mode.
rate generation (continuous pulse
output) mode.
Nonzero if subsystem supports
(single) one-shot mode.
Nonzero if subsystem supports
repetitive one-shot mode.
Nonzero if subsystem supports
up/down counting mode.
Returns a value indicating how
edge-to-edge measurement
mode is supported (see page 90
for more information).
Returns a value indicating how
edge-to-edge measurement
mode is supported (see page 90
for more information).
18
Counter/Timer
Pulse Output
Ty p es
OLSSC_SUP_PLS_HIGH2LOW Nonzero if subsystem supports
high-to-low output pulses.
OLSSC_SUP_PLS_LOW2HIGH Nonzero if subsystem supports
low-to-high output pulses
Table 2: Capabilities to Query with olDaGetSSCaps (cont.)
Function Summary
Query about Capability Function Returns
Counter/Timer
Gates
OLSSC_SUP_GATE_NONE Nonzero if subsystem supports
an internal (software) gate type.
OLSSC_SUP_GATE_HIGH_
LEVEL
OLSSC_SUP_GATE_LOW_
LEVEL
OLSSC_SUP_GATE_HIGH_
EDGE
OLSSC_SUP_GATE_LOW_
EDGE
OLSSC_SUP_GATE_LEVEL Nonzero if subsystem supports
OLSSC_SUP_GATE_HIGH_
LEVEL_DEBOUNCE
OLSSC_SUP_GATE_LOW_
LEVEL_DEBOUNCE
OLSSC_SUP_GATE_HIGH_
EDGE_DEBOUNCE
OLSSC_SUP_GATE_LOW_
EDGE_DEBOUNCE
Nonzero if subsystem supports
high-level gate type.
Nonzero if subsystem supports
low-level gate type.
Nonzero if subsystem supports
high-edge gate type.
Nonzero if subsystem supports
low-edge gate type.
level change gate type.
Nonzero if subsystem supports
high-level gate type with input
debounce.
Nonzero if subsystem supports
low-level gate type with input
debounce.
Nonzero if subsystem supports
high-edge gate type with input
debounce.
Nonzero if subsystem supports
low-edge gate type with input
debounce.
2
2
2
2
2
2
2
OLSSC_SUP_GATE_LEVEL_
DEBOUNCE
Interrupt OLSSC_SUP_INTERRUPT Nonzero if subsystem supports
Nonzero if subsystem supports
level change gate type with input
debounce.
interrupt-driven I/O.
2
2
19
Chapter 2
Table 2: Capabilities to Query with olDaGetSSCaps (cont.)
Query about Capability Function Returns
FIFOs OLSSC_SUP_FIFO Nonzero if subsystem has a FIFO
in the data path.
OLSSC_FIFO_SIZE_IN_K Size of the output FIFO, in
kilobytes.
Processors OLSSC_SUP_PROCESSOR Nonzero if subsystem has a
processor on device.
Software
Calibration
OLSSC_SUP_SWCAL Nonzero if subsystem supports
software calibration.
Table 3: Capabilities to Query with olDaGetSSCapsEx
Query about Capability Function Returns
Triggered
Scan Mode
Clocks OLSSCE_BASECLOCK Base clock frequency supported
OLSSCE_MAXRETRIGGER Maximum retrigger frequency
supported by the subsystem.
OLSSCE_MINRETRIGGER Minimum retrigger frequency
supported by the subsystem.
by the subsystem.
OLSSCE_MAXCLOCKDIVIDER Maximum external clock divider
supported by the subsystem.
OLSSCE_MINCLOCKDIVIDER Minimum external clock divider
supported by the subsystem.
OLSSCE_MAXTHROUGHPUT Maximum throughput supported
by the subsystem.
OLSSCE_MINTHROUGHPUT Minimum throughput supported
by the subsystem.
20
Initialization and Termination Functions
Function Summary
Once you have identified the available devices, use the Initialization
functions described in Table 4.
Table 4: Initialization Functions
Function Description
olDaInitialize Provides the means for the software to associate specific
requests with a particular device; it must be called before any
other function. This function loads a specified device's
software support and provides a “device handle” value. This
value is used to identify the device, and must be supplied as
an argument in all subsequent function calls that reference the
device.
olDaGetDASS Allocates a subsystem for use by returning a handle to the
subsystem.
When you are finished with your program, use the Termination
functions listed in Table 5.
Table 5: Termination Functions
2
2
2
2
2
2
Function Description
olDaReleaseDASS Releases the specified subsystem and relinquishes all
resources associated with it.
olDaTerminate Ends a session between your application and the specified
device. The device is returned to an inactive state and all
resources are returned to the system.
2
2
2
21
Chapter 2
Configuration Functions
Once you have initialized a subsystem and determined what its
capabilities are, set or get the value of the subsystem’s parameters by
calling the Configuration functions listed in Ta b l e 6 .
Table 6: Configuration Functions
Feature Function Description
Data Flow
Mode
Windows
Messaging
Buffer Wrap
Mode
DMA olDaSetDmaUsage Sets the number of DMA
olDaSetDataFlow Sets the data flow mode.
olDaGetDataFlow Gets the data flow mode.
olDaSetNotificationProcedure Specifies the notification
procedure to call for
information messages from
the subsystem.
olDaGetNotificationProcedure Gets the address of the
notification procedure.
olDaSetWndHandle Sets the window to which
information messages are
sent.
olDaGetWndHandle Gets the window handle.
olDaSetWrapMode Sets the buffer processing
wrap mode.
olDaGetWrapMode Gets the buffer processing
wrap mode.
channels to be used.
olDaGetDmaUsage Gets the number of DMA
channels to be used.
22
Table 6: Configuration Functions (cont.)
Function Summary
Feature Function Description
Triggered
Scans
ChannelGain List
olDaSetTriggeredScanUsage Enables or disables triggered
scan mode.
olDaGetTriggeredScanUsage Gets the triggered scan
mode setting.
olDaSetMultiscanCount Sets the number of times to
scan per trigger/retrigger.
olDaGetMultiscanCount Gets the number of times to
scan per trigger/retrigger.
olDaSetRetriggerMode Sets the retrigger mode.
olDaGetRetriggerMode Gets the retrigger mode.
olDaSetRetriggerFrequency Sets the frequency of the
internal retrigger when using
internal retrigger mode.
olDaGetRetriggerFrequency Gets the frequency of the
internal retrigger when using
internal retrigger mode.
olDaSetChannelListSize Sets the size of the
channel-gain list.
2
2
2
2
2
2
olDaGetChannelListSize Gets the size of the
channel-gain list.
olDaSetChannelListEntry Sets the channel number of
a channel-gain list entry.
olDaGetChannelListEntry Gets the channel number of
a channel-gain list entry.
olDaSetGainListEntry Sets a gain value for a
channel-gain list entry.
olDaGetGainListEntry Gets the gain value of a
channel-gain list entry.
2
2
2
23
Chapter 2
Table 6: Configuration Functions (cont.)
Feature Function Description
ChannelGain List
(cont.)
Synchronous
Digital I/O
Channel
Ty p e
olDaSetChannelListEntryInhibit Enables/disables channel
entry inhibition for a
channel-gain list entry.
olDaGetChannelListEntryInhibit Gets the channel entry
inhibition setting of a
channel-gain list entry.
olDaSetDigitalIOListEntry Sets the digital value to
output for the channel-gain
list entry.
olDaGetDigitalIOListEntry Gets the digital value to
output for the channel-gain
list entry.
olDaSetSynchronousDigitalIOUsage Enables or disables
synchronous digital I/O
operations.
olDaGetSynchronousDigitalIOUsage Gets the synchronous digital
I/O setting.
olDaSetChannelType Sets the channel
configuration type of a
channel.
olDaGetChannelType Gets the channel
configuration type of a
channel.
24
Filters olDaSetChannelFilter Sets the filter cut-off
frequency for a channel.
olDaGetChannelFilter Gets the filter cut-off
frequency for a channel.
Table 6: Configuration Functions (cont.)
Function Summary
Feature Function Description
Ranges olDaSetRange Sets the voltage range for a
subsystem.
olDaGetRange Gets the voltage range for a
subsystem.
olDaSetChannelRange Sets the voltage range for a
channel.
olDaGetChannelRange Gets the voltage range for a
channel.
Resolution olDaSetResolution Sets the number of bits of
resolution.
olDaGetResolution Gets the number of bits of
resolution.
Data
Encoding
Triggers olDaSetTrigger Sets the post-trigger source.
olDaSetEncoding Sets the data encoding type.
olDaGetEncoding Gets the data encoding type.
olDaGetTrigger Gets the post-trigger source.
olDaSetPretriggerSource Sets the pre-trigger source.
2
2
2
2
2
2
olDaGetPretriggerSource Gets the pre-trigger source.
olDaSetRetrigger Sets the retrigger source for
retrigger-extra retrigger
mode.
olDaGetRetrigger Gets the retrigger source for
retrigger-extra retrigger
mode.
2
2
2
25
Chapter 2
Table 6: Configuration Functions (cont.)
Feature Function Description
Clocks olDaSetClockSource Sets the clock source.
olDaGetClockSource Gets the clock source.
olDaSetClockFrequency Sets the frequency of the
internal clock or a
counter/timer’s output
frequency.
olDaGetClockFrequency Gets the frequency of the
internal clock or a
counter/timer’s output
frequency.
olDaSetExternalClockDivider Sets the input divider value
of the external clock.
olDaGetExternalClockDivider Gets the input divider value
of the external clock.
26
Counter/
Timers
olDaSetCTMode Sets the counter/timer mode.
olDaGetCTMode Gets the counter/timer mode.
olDaSetCascadeMode Sets the counter/timer
cascade mode.
olDaGetCascadeMode Gets the counter/timer
cascade mode.
olDaSetGateType Sets the gate type for the
counter/timer mode.
olDaGetGateType Gets the gate type for the
counter/timer mode.
olDaSetPulseType Sets the pulse type for the
counter/timer mode.
olDaGetPulseType Gets the pulse type for the
counter/timer mode.
Table 6: Configuration Functions (cont.)
Function Summary
Feature Function Description
Counter/
Timers
(cont.)
olDaSetPulseWidth Sets the pulse output width
for the counter/timer mode.
olDaGetPulseWidth Gets the pulse width for the
counter/timer mode.
olDaGetMeasureStartEdge Gets the start edge for
edge-to-edge measurement
operations.
olDaSetMeasureStartEdge Sets the start edge for
edge-to-edge measurement
operations.
olDaGetMeasureStopEdge Gets the stop edge for
edge-to-edge measurement
operations.
olDaSetMeasureStopEdge Sets the stop edge for
edge-to-edge measurement
operations.
Operation Functions
2
2
2
2
2
2
Once you have set the parameters of a subsystem, use the Operation
functions listed in Table 7.
2
2
2
27
Chapter 2
Table 7: Operation Functions
Operation Function Description
Single-Value
Operations
Configure
Operation
Start/Stop
Operations
olDaGetSingleValue Reads a single input value from
the specified subsystem channel.
olDaGetSingleValueEx Determines the appropriate gain
for the range (called
autoranging), if desired, reads a
single input value from the
specified subsystem channel,
and returns the value as both a
code and a voltage.
olDaPutSingleValue Writes a single output value to
the specified subsystem channel.
olDaConfig After setting up a specified
subsystem using the
configuration functions,
configures the subsystem with
new parameter values.
olDaStart Starts the operation for which the
subsystem has been configured.
olDaPause Pauses a continuous operation
on the subsystem.
olDaContinue Continues the previously paused
operation on the subsystem.
28
olDaStop Stops the operation and returns
the subsystem to the ready state.
olDaAbort Stops the subsystem’s operation
immediately.
olDaReset Causes the operation to
terminate immediately, and
re-initializes the subsystem.
Table 7: Operation Functions (cont.)
Function Summary
Operation Function Description
Buffer
Operations
Counter/
Timer
Operations
olDaGetBuffer Gets a completed buffer from the
done queue of the specified
subsystem.
olDaPutBuffer Assigns a data buffer for the
subsystem to the ready queue.
olDaFlushBuffers Transfers all data buffers held by
the subsystem to the done
queue.
olDaFlushFromBufferInprocess Copies all valid samples, up to a
given number of samples, from
the inprocess buffer to a
specified buffer. It also sets the
logical size of the buffer with
flushed data to the number of
samples copied and places the
inprocess buffer on the done
queue when it has been filled
with the remaining samples.
olDaReadEvents Gets the number of events that
have been counted since the
subsystem was started with
olDaStart.
2
2
2
2
2
2
olDaMeasureFrequency Measures the frequency of the
input clock source for the
selected counter/timer.
2
2
2
29
Chapter 2
Table 7: Operation Functions (cont.)
Operation Function Description
Simultaneous
Operations
olDaGetSSList Gets a handle to a simultaneous
olDaPutDassToSSList Puts the specified subsystem on
olDaSimultaneousPreStart Simultaneously prestarts
olDaSimultaneousStart Simultaneously starts all
olDaReleaseSSList Releases the specified
Data Conversion Functions
Once you have acquired data, you can use the functions listed in
Table 8 to convert the data, if desired.
start list.
the simultaneous start list.
(performs setup operations on)
all subsystems on the specified
simultaneous start list.
subsystems on the specified
simultaneous start list.
simultaneous start list and
relinquishes all resources
associated with it.
30
Table 8: Data Conversion Functions
Function Description
olDaCodeToVolts Converts a code value to voltage value,
using the range, gain, resolution, and
encoding you specify.
olDaVoltsToCode Converts a voltage value to code value,
using the range, gain, resolution, and
encoding you specify.
Data Management Functions
Data management functions the various layers of the DT-Open
Layers architecture together. The fundamental data object in the
DataAcq SDK is a buffer. All functions that create, manipulate, and
delete buffers are encapsulated in the data management portion of
the DataAcq SDK.
The following groups of data management functions are available:
Function Summary
2
2
• Buffer management functions, and
• List management functions.
The following subsections summarize these functions.
Note: For specific information about each of these functions, refer
to the DataAcq SDK online help. See page 4 for information on
launching the online help file.
Buffer Management Functions
The Buffer Management functions, listed in Table 9, are a set of
object-oriented tools intended for both application and system
programmers. When a buffer object is created, a buffer handle
(HBUF) is returned. This handle is used in all subsequent buffer
manipulation.
2
2
2
2
2
2
2
31
Chapter 2
Table 9: Buffer Management Functions
Function Description
olDmAllocBuffer Creates a buffer object of a specified number of
samples, where each sample is 2 bytes.
olDmCallocBuffer Creates a buffer object of a specified number of
samples of a specified size.
olDmCopyBuffer Copies data from the buffer to the specified array.
olDmCopyFromBuffer Copies data from the buffer to the specified array.
olDmCopyToBuffer Copies data from the specified array to the buffer.
olDmFreeBuffer Deletes a buffer object.
olDmGetBufferPtr Gets a pointer to the buffer data.
olDmGetBufferSize Gets the physical buffer size (in bytes).
olDmGetDataBits Gets the number of valid data bits.
olDmSetDataBits Sets the number of valid data bits.
32
olDmSetDataWidth Sets the width of each data sample.
olDmGetDataWidth Gets the width of each data sample.
olDmGetErrorString Gets the string corresponding to a data management
error code value.
olDmGetMaxSamples Gets the physical size of the buffer (in samples).
olDmGetTimeDateStamp Gets the time and date of the buffer's data.
olDmSetValidSamples Sets the number of valid samples in the buffer.
olDmGetValidSamples Gets the number of valid samples.
olDmGetVersion Gets the version of the data management library.
olDmMallocBuffer Creates a buffer object of a specified number of bytes.
olDmReAllocBuffer Reallocates a buffer object (alloc() interface).
Table 9: Buffer Management Functions (cont.)
Function Summary
Function Description
olDmReCallocBuffer Reallocates a buffer object (calloc() interface).
olDmReMallocBuffer Reallocates a buffer object (malloc() interface).
Buffer List Management Functions
Buffer List Management functions, described in Table 1 0 , provide a
straightforward mechanism for handling buffer lists, called queues,
that the software creates internally as well as other lists that you
might want to create. You are not required to use these functions;
however, you may find them helpful in your application. Buffer List
Management functions are particularly useful when dealing with a
device that acquires or outputs continuous data. Refer to Chapter 5
for more information on queues and other lists.
Table 10: Buffer List Management Functions
Function Description
olDmCreateList Creates a user-defined list object.
2
2
2
2
2
2
olDmEnumBuffers Enumerates all buffers on a queue or on a list
you created.
olDmEnumLists Enumerates all queues or lists.
olDmFreeList Deletes a user-defined list.
olDmGetBufferFromList Removes a buffer from the start of a queue or
user-defined list.
olDmGetListCount Gets the number of buffers on a queue or
user-defined list.
olDmGetListHandle Finds the queue or user-defined list that a
buffer is on.
2
2
2
33
Chapter 2
Table 10: Buffer List Management Functions (cont.)
Function Description
olDmGetListIds Gets a description of the queue or list.
olDmPeekBufferFromList Gets the handle of the first buffer in the queue
or list but does not remove the buffer from the
queue or list.
olDmPutBufferToList Adds a buffer to the end of a queue or list.
34
3
Using the DataAcq SDK
System Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Analog and Digital I/O Operations . . . . . . . . . . . . . . . . . . . . . . . 41
Counter/Timer Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Simultaneous Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
35
Chapter 3
This chapter provides conceptual information to describe the
following operations provided by the DataAcq SDK:
• System operations, described starting on page 37;
• Analog and digital I/O operations, described starting on page 41;
• Counter/timer operations described starting on page 81; and
• Simultaneous operations starting on page 110.
Use this information with the reference information provided in the
DataAcq SDK online help when programming your data acquisition
devices; refer to page 4 for more information on launching this help
file.
36
System Operations
This DataAcq SDK provides functions to perform the following
general system operations:
• Initializing a device,
• Specifying a subsystem,
•Configuring a subsystem,
Using the DataAcq SDK
3
3
•Handling errors,
• Handling messages, and
• Releasing a subsystem and driver.
The following subsections describe these operations in more detail.
Initializing a Device
To perform a data acquisition operation, your application program
must initialize the device driver for the device you are using with the
olDaInitialize function. This function returns a device handle, called
HDEV. You need one device handle for each device. Device handles
allow you to access more than one device in your system.
If you are unsure of the DT-Open Layers devices in your system, use
the olDaEnumBoards function, which lists the device name, device
driver name, and system resources used by each DT-Open Layers
device in your system, or the olDaGetBoardInfo function, which
returns the driver name, model name, and instance number of the
specified board, based on its board name.
Once you have initialized a device, you can specify a subsystem, as
described in the next section.
3
3
3
3
3
3
3
37
Chapter 3
Specifying a Subsystem
The DataAcq SDK allows you to define the following subsystems:
• Analog input (A/D subsystem),
• Analog output (D/A subsystem),
• Digital input (DIN subsystem),
• Digital output (DOUT subsystem),
• Counter/timer (C/T subsystem), and
• Serial port (SRL subsystem).
Note: The SRL subsystem is provided for future use. It is not
currently used by any DT-Open Layers compatible data acquisition
device.
A device can have multiple elements of the same subsystem type.
Each of these elements is a subsystem of its own and is identified by a
subsystem type and element number. Element numbering is
zero-based; that is, the first instance of the subsystem is called
element 0, the second instance of the subsystem is called element 1,
and so on. For example if two digital I/O ports are on your device,
two DIN or DOUT subsystems are available, differentiated as
element 0 and element 1.
38
Once you have initialized the device driver for the specified device,
you must specify the subsystem/element on the specified device
using the olDaGetDASS function. This function returns a subsystem
handle, called HDASS. To access a subsystem, you need one
subsystem handle for each subsystem. Subsystem handles allow you
to access more than one subsystem on a device.
Using the DataAcq SDK
If you are unsure of the subsystems on a device, use the
olDaEnumSubSystems or olDaGetDevCaps function.
olDaEnumSubSystems lists the names, types, and number of
elements for all subsystems supported by the specified device.
olDaGetDevCaps returns the number of elements for a specified
subsystem type on a specified device.
Note: You can call any function that contains HDASS as a
parameter for any subsystem. In some cases, however, the
subsystem may not support the particular capability. If this occurs,
the subsystem returns an error code indicating that it does not
support that function.
Once you have specified a subsystem/element, you can configure the
subsystem and perform a data acquisition operation, as described in
the following section.
3
3
3
3
3
Configuring a Subsystem
You configure a subsystem by setting its parameters or capabilities.
For more information on the capabilities you can query and specify,
refer to the following:
• For analog and digital I/O operations, refer to page 41;
• For the counter/timer operations, refer to page 81, and
• For simultaneous operations, refer to page 110.
Once you have set up the parameters appropriately for the operation
you want to perform, call the olDaConfig function to configure the
parameters before performing the operation.
3
3
3
3
39
Chapter 3
Handling Errors
An error code is returned by each function in the DataAcq SDK. An
error code of 0 indicates that the function executed successfully (no
error). Any other error code indicates that an error occurred. Your
application program should check the value returned by each
function and perform the appropriate action if an error occurs.
Refer to the DataAcq SDK online help for detailed information on the
returned error codes and how to proceed should they occur.
Handling Messages
The data acquisition device notifies your application of buffer
movement and other events by generating messages.
To determine if the subsystem can post messages, use the
olDaGetSSCaps function, specifying the capability
OLSSC_SUP_POSTMESSAGE. If this function returns a nonzero
value, the capability is supported.
40
Specify the window to receive messages using the
olDaSetWndHandle function or the procedure to handle these
messages using the olDaSetNotificationProcedure function.
Refer to the DataAcq SDK online help for more information on the
messages that can be generated and how to proceed should they
occur.
Releasing the Subsystem and the Driver
When you are finished performing data acquisition operations,
release the simultaneous start list, if used, using the
olDaReleaseSSList function. Then, release each subsystem using the
olDaReleaseDASS function. Release the driver and terminate the
session using the olDaTerminate function.
Analog and Digital I/O Operations
The DataAcq SDK defines the following capabilities that you can
query and/or specify for analog and/or digital I/O operations:
• Data encoding,
•Resolution,
• Channels (including channel type, channel list, channel inhibit
list, and synchronous digital I/O list),
•Ranges,
• Gains,
•Filters,
•Data flow modes,
• Triggered scan mode,
Using the DataAcq SDK
3
3
3
3
• Clock sources,
•Trigger sources,
• Buffers, and
• DMA and interrupt resources.
The following subsections describe these capabilities in more detail.
Data Encoding
For A/D and D/A subsystems only, the DataAcq SDK defines two
data encoding types: binary and twos complement.
To determine the data encoding types supported by the subsystem,
use the olDaGetSSCaps function, specifying the capability
OLSSC_SUP_BINARY for binary data encoding or
OLSSC_SUP_2SCOMP for twos complement data encoding. If this
function returns a nonzero value, the capability is supported. Use the
olDaSetEncoding function to specify the data encoding type.
3
3
3
3
3
41
Chapter 3
Resolution
To determine if the subsystem supports software-programmable
resolution, use the olDaGetSSCaps function, specifying the
capability OLSSC_SUP_SWRESOLUTION. If this function returns a
nonzero value, the capability is supported.
To determine the number of resolution settings supported by the
subsystem, use the olDaGetSSCaps function, specifying the
capability OLSSC_NUMRESOLUTION. To list the actual bits of
resolution supported, use the olDaEnumSSCaps function, specifying
the OL_ENUM_RESOLUTION capability.
Use the olDaSetResolution function to specify the number of bits of
resolution to use for the subsystem.
Channels
Each subsystem (or element of a subsystem type) can have multiple
channels. To determine how many channels the subsystem supports,
use the olDaGetSSCaps function, specifying the
OLSSC_NUMCHANNELS capability.
42
Specifying the Channel Type
Using the DataAcq SDK
The DataAcq SDK supports the following channel types:
• Single-ended - Use this configuration when you want to
measure high-level signals, noise is insignificant, the source of
the input is close to the device, and all the input signals are
referred to the same common ground.
To determine if the subsystem supports the single-ended channel
type, use the olDaGetSSCaps function, specifying the
OLSSC_SUP_SINGLEENDED capability. If this function returns
a nonzero value, the capability is supported.
To determine how many single-ended channels are supported by
the subsystem, use the olDaGetSSCaps function, specifying the
OLSSC_MAXSECHANS capability.
Specify the channel type as single-ended for each channel using
the olDaSetChannelType function.
• Differential - Use this configuration when you want to measure
low-level signals (less than 1 V), you are using an A/D converter
with high resolution (greater than 12 bits), noise is a significant
part of the signal, or common-mode voltage exists.
To determine if the subsystem supports the differential channel
type, use the olDaGetSSCaps function, specifying the
OLSSC_SUP_DIFFERENTIAL capability. If this function returns
a nonzero value, the capability is supported.
To determine how many differential channels are supported by
the subsystem, use the olDaGetSSCaps function, specifying the
OLSSC_MAXDICHANS capability.
3
3
3
3
3
3
3
Specify the channel type as differential for each channel using the
olDaSetChannelType function.
3
3
43
Chapter 3
Note: For pseudo-differential analog inputs, specify the
single-ended channel type; in this case, how you wire these signals
determines the configuration. This option provides less noise
rejection than the differential configuration, but twice as many
analog input channels.
For older model devices, this setting is jumper-selectable and must
be specified in the driver configuration dialog.
The channel list is not used to set the channel type.
The following subsections describe how to specify channels.
Specifying a Single Channel
The simplest way to acquire data from or output data to a single
channel is to specify the channel for a single-value operation; refer to
page 54 for more information on single-value operations.
44
You can also specify a single channel using a channel list, described
in the next section.
Specifying One or More Channels
You acquire data from or output data to one or more channels using a
channel list.
The DataAcq SDK provides features that allow you to group the
channels in the list sequentially (either starting with 0 or with any
other analog input channel) or randomly. In addition, the DataAcq
SDK allows you to specify a single channel or the same channel more
than once in the list. Your device, however, may limit the order in
which you can enter a channel in the channel list.
Using the DataAcq SDK
To determine how the channels can be ordered in the channel list for
your subsystem, use the olDaGetSSCaps function, specifying the
OLSSC_RANDOM_CGL capability. If this function returns a nonzero
value, the capability is supported; you can order the channels in the
channel list in any order, starting with any channel. If this capability
is not supported, use the olDaGetSSCaps function, specifying the
OLSSC_SUP_SEQUENTIAL_CGL capability. If this function returns
a nonzero value, the capability is supported; you must order the
channels in the channel list in sequential order, starting with any
channel. If this capability is not supported, use the olDaGetSSCaps
function, specifying the OLSSC_SUP_ZEROSEQUENTIAL_CGL
capability. If this function returns a nonzero value, the capability is
supported; you must order the channels in the channel list in
sequential order, starting with channel 0.
To determine if the subsystem supports simultaneous
sample-and-hold mode use the olDaGetSSCaps function, specifying
the OLSSC_SUP_SIMULTANEOUS_SH capability. If this function
returns a nonzero value, the capability is supported. You must enter
at least two channels in the channel list. Generally, the first channel is
the sample channel and the remaining channels are the hold
channels.
3
3
3
3
3
The following subsections describe how to specify channels in a
channel list.
Specifying the Channel List Size
To determine the maximum size of the channel list for the subsystem,
use the olDaGetSSCaps function, specifying the
OLSSC_CGLDEPTH capability.
Use the olDaSetChannelListSize function to specify the size of the
channel list.
3
3
3
3
45
Chapter 3
Note: The OLSSC_CGLDEPTH capability specifies the maximum
size of the channel list, channel inhibit list, synchronous digital I/O
list, and gain list.
Specifying the Channels in the Channel List
Use the olDaSetChannelListEntry function to specify the channels in
the channel list in the order you want to sample them or output data
from them.
The channels are sampled or output in order from the first entry to
the last entry in the channel list. Channel numbering is zero-based;
that is, the first entry in the channel list is entry 0, the second entry is
entry 1, and so on.
For example, if you want to sample channel 4 twice as frequently as
channels 5 and 6, you could program the channel list as follows:
46
Channel-List
Entry
0 4 Sample channel 4.
1 5 Sample channel 5.
2 4 Sample channel 4 again.
3 6 Sample channel 6.
Channel Description
In this example, channel 4 is sampled first, followed by channel 5,
channel 4 again, then channel 6.
Inhibiting Channels in the Channel List
Using the DataAcq SDK
If supported, you can set up a channel-inhibit list; this feature is
useful if you want to discard values acquired from specific channels,
as is typical in simultaneous sample-and-hold applications.
To determine if a subsystem supports a channel-inhibit list, use the
olDaGetSSCaps function, specifying the
OLSSC_SUP_CHANNELLIST_INHIBIT capability. If this function
returns a nonzero value, the capability is supported.
Using the olDaSetChannelListEntryInhibit function, you can enable
or disable inhibition for each entry in the channel list. If enabled, the
acquired value is discarded after the channel entry is sampled; if
disabled, the acquired value is stored after the channel entry is
sampled.
In the following example, the values acquired from channels 11 and 9
are discarded and the values acquired from channels 10 and 8 are
stored.
Channel-List
Entry
Channel
Channel Inhibit
Val ue
Description
3
3
3
3
3
3
0 11 Tr u e Sample channel 11 and discard
the value.
1 10 False Sample channel 10 and store the
value.
2 9 Tru e Sample channel 9 and discard the
value.
3 8 False Sample channel 8 and store the
value.
3
3
3
47
Chapter 3
Specifying Synchronous Digital I/O Values in the Channel List
If supported, you can set up a synchronous digital I/O list; this
feature is useful if you want to write a digital output value to
dynamic digital output channels when an analog input channel is
sampled.
To determine if the subsystem supports synchronous (dynamic)
digital output operations, use the olDaGetSSCaps function,
specifying the OLSSC_SUP_SYNCHRONOUSDIGITALIO capability.
If this function returns a nonzero value, the capability is supported.
Use the olDaSetSynchronousDigitalIOUsage function to enable or
disable synchronous (dynamic) digital output operation for a
specified subsystem.
Once you enable a synchronous digital output operation, specify the
values to write to the synchronous (dynamic) digital output channels
using the olDaSetDigitalIOListEntry function for each entry in the
channel list.
48
To determine the maximum digital output value that you can specify,
use the olDaGetSSCaps function, specifying the
OLSSC_MAXDIGITALIOLIST_VALUE capability.
As each entry in the channel list is scanned, the corresponding value
in the synchronous digital I/O list is output to the dynamic digital
output channels.
In the following example, when channel 7 is sampled, a value of 1 is
output to the dynamic digital output channels. When channel 5 is
sampled, a value of 1 is output to the dynamic digital output
channels. When channels 6 and 4 are sampled, a value of 0 is output
to the dynamic digital output channels.
Using the DataAcq SDK
Channel-List
Entry
0 7 1 Sample channel 7 and output a
1 5 1 Sample channel 5 and output a
2 6 0 Sample channel 6 and output a
3 4 0 Sample channel 4 and output a
Channel
If your device had two dynamic digital output channels and a value
of 1 is output (01 in binary format), a value of 1 is written to dynamic
digital output channel 0 and a value of 0 is written to dynamic digital
output channel 1. Similarly, if a value of 2 is output (10 in binary
format), a value of 0 is written to dynamic digital output channel 0
and a value of 1 is written to dynamic digital output channel 1.
Synchronous
Digital I/O Value
Description
value of 1 to the dynamic digital
output channels.
value of 1 to the dynamic digital
output channels.
value of 0 to the dynamic digital
output channels.
value of 0 to the dynamic digital
output channels.
3
3
3
3
3
3
Note: If you are controlling sample-and-hold devices with these
channels, you may need to program the first channel at the sample
logic level and the following channels at the hold logic level; see
your device/device driver documentation for details.
3
3
3
49
Chapter 3
Ranges
The range capability applies to A/D and D/A subsystems only.
Depending on your subsystem, you can set the range for the entire
subsystem or the range for each channel.
To determine if the subsystem supports the range-per-channel
capability, use the olDaGetSSCaps function, specifying the
OLSSC_SUP_RANGEPERCHANNEL capability. If this function
returns a nonzero value, the capability is supported.
To determine how many ranges the subsystem supports, use the
olDaGetSSCaps function, specifying the OLSSC_NUMRANGES
capability.
To list the minimum and maximum ranges supported by the
subsystem, use the olDaEnumSSCaps function, specifying the
OL_ENUM_RANGES capability.
Use olDaSetRange to specify the range for a subsystem. If your
subsystem supports the range-per-channel capability, use
olDaSetChannelRange to specify the range for each channel.
50
Notes: The channel list is not used to set the range for a channel.
For older device models, the range is jumper-selectable and must be
specified in the driver configuration dialog.
Gains
Using the DataAcq SDK
The range divided by the gain determines the effective range for the
entry in the channel list. For example, if your device provides a range
of ±10 V and you want to measure a ±1.5 V signal, specify a range of
±10 V and a gain of 4; the effective input range for this channel is then
±2.5 V (10/4), which provides the best sampling accuracy for that
channel.
The way you specify gain depends on how you specified the
channels, as described in the following subsections.
Note: If your device supports autoranging for single-value
operations, the device can determine the appropriate gain for your
range rather than you having to specify it. Refer to page 54 for more
information on autoranging.
Specifying the Gain for a Single Channel
The simplest way to specify gain for a single channel is to specify the
gain in a single-value operation; refer to page 54 for more
information on single-value operations.
3
3
3
3
3
3
You can also specify the gain for a single channel using a gain list,
described in the next section.
Specifying the Gain for One or More Channels
You can specify the gain for one or more channels using a gain list.
The gain list parallels the channel list. (The two lists together are
often referred to as the channel-gain list or CGL.)
3
3
3
51
Chapter 3
To determine if the subsystem supports programmable gain, use the
olDaGetSSCaps function, specifying the
OLSSC_SUP_PROGRAMGAIN capability. If this function returns a
nonzero value, the capability is supported.
To determine how many gains the subsystem supports, use the
olDaGetSSCaps function, specifying the OLSSC_NUMGAINS
capability.
To list the gains supported by the subsystem, use the
olDaEnumSSCaps function, specifying the OL_ENUM_GAINS
capability.
Specify the gain for each entry in the channel list using the
olDaSetGainListEntry function.
In the following example, a gain of 2 is applied to channel 5, a gain of
4 is applied to channel 6, and a gain of 1 is applied to channel 7.
Channel-List
Entry
Channel Gain Description
52
0 5 2 Sample channel 5 using a gain of 2.
1 6 4 Sample channel 6 using a gain of 4.
2 7 1 Sample channel 7 using a gain of 1.
Note: If your subsystem does not support programmable gain,
enter a value of 1 for all entries.
If your subsystem does not support the gain-per-channel capability,
set all entries in the gain list to the same value.
Filters
Using the DataAcq SDK
This capability applies to A/D and D/A subsystems only.
Depending on your subsystem, you can specify a filter for each
channel. To determine if the subsystem supports a filter for each
channel, use the olDaGetSSCaps function, specifying the
OLSSC_SUP_FILTERPERCHAN capability. If this function returns a
nonzero value, the capability is supported.
To determine how many filters the subsystem supports, use the
olDaGetSSCaps function, specifying the OLSSC_NUMFILTERS
capability.
To list the cut-off frequency of all filters supported by the subsystem,
use the olDaEnumSSCaps function, specifying the
OL_ENUM_FILTERS capability.
If the subsystem supports filtering per channel, specify the filter for
each channel using the olDaSetChannelFilter function. The filter is
equal to or greater than a cut-off frequency that you supply.
Notes: The channel list is not used to set the filter for a channel.
3
3
3
3
3
3
If the subsystem supports more than one filter but does not support
a filter per channel, the filter specified for channel 0 is used for all
channels.
3
3
3
53
Chapter 3
Data Flow Modes
The DataAcq SDK defines the following data flow modes for A/D,
D/A, DIN, and DOUT subsystems:
• Single value, and
• Continuous (post-trigger, pre-trigger, and about-trigger).
The following subsections describe these data flow modes in detail.
Single-Value Operations
Single-value operations are the simplest to use but offer the least
flexibility and efficiency. In a single-value operation, a single data
value is read or written at a time. The result is returned immediately.
To determine if the subsystem supports single-value operations, use
the olDaGetSSCaps function, specifying the capability
OLSSC_SUP_SINGLEVALUE. If this function returns a nonzero
value, the capability is supported.
54
Specify the operation mode as OL_DF_SINGLEVALUE using the
olDaSetDataFlow function.
Some devices also support autoranging for single-value analog input
operations, where the device determines the best gain for the
specified range. To determine if the subsystem supports autoranging
for single-value operations, use the olDaGetSSCaps function,
specifying the capability
OLSSC_SUP_SINGLEVALUE_AUTORANGE. If this function
returns a nonzero value, the capability is supported.
If autoranging is supported, use the olDaGetSingleValueEx function
to specify the range and analog input channel and to have the
software determine the best gain for the range. The device then
acquires the data from the specified channel and returns the result
immediately in both counts and engineering units (such as voltage).
Using the DataAcq SDK
If autoranging is not supported, use the olDaGetSingleValue
function to acquire a single value from an analog or digital input
channel. You specify the channel and gain, then the device acquires
the data from the specified channel and returns the result
immediately, in counts. If you later want to convert the count value to
engineering units, you can use the olDaCodeToVolts function.
Similarly, if you want to convert the engineering units to counts, you
can use the olDaVoltsToCode function.
To output a single value to an analog or digital output channel, use
the olDaPutSingleValue function. You specify the channel, gain, and
value, and the device outputs the single value to the specified analog
or digital channel immediately.
3
3
3
For a single-value operation, you cannot specify a channel-gain list,
clock source, trigger source, DMA channel, or buffer.
Single-value operations stop automatically when finished; you
cannot stop a single-value operation manually.
Continuous Operations
For a continuous operation, you can specify any supported
subsystem capability, including a channel-gain list, clock source,
trigger source, pre-trigger source, retrigger source, DMA channel,
and buffer.
Call the olDaStart function to start a continuous operation.
To stop a continuous operation, perform either an orderly stop using
the olDaStop function or an abrupt stop using the olDaAbort or
olDaReset function.
3
3
3
3
3
3
55
Chapter 3
In an orderly stop (olDaStop), the device finishes acquiring the
specified number of samples, stops all subsequent acquisition, and
transfers the acquired data to a buffer on the done queue; all
subsequent triggers or retriggers are ignored. (Refer to page 71 for
more information on buffers and queues.)
In an abrupt stop (olDaAbort), the device stops acquiring samples
immediately; the acquired data is transferred to a buffer and put on
the done queue; however, the buffer may not be completely filled. All
subsequent triggers or retriggers are ignored.
The olDaReset function reinitializes the subsystem after stopping it
abruptly.
Note: For analog output operations, you can also stop the operation
by not sending new data to the device. The operation stops when no
more data is available.
56
Some subsystems also allow you to pause the operation using the
olDaPause function and to resume the paused operation using the
olDaContinue function. To determine if pausing is supported, use
the olDaGetSSCaps function, specifying the OLSSC_SUP_PAUSE
capability. If this function returns a nonzero value, the capability is
supported.
The following continuous modes are supported by the DataAcq SDK:
continuous (post-trigger), continuous pre-trigger, and continuous
about-trigger. These modes are described in the following
subsections.
Continuous Post-Trigger Mode
Using the DataAcq SDK
Use continuous post-trigger when you want to acquire or output data
continuously when a trigger occurs.
To determine if the subsystem supports continuous (post-trigger)
operations, use the olDaGetSSCaps function, specifying the
capability OLSSC_SUP_CONTINUOUS. If this function returns a
nonzero value, the capability is supported.
For continuous (post-trigger) mode, specify the operation mode as
OL_DF_CONTINUOUS using the olDaSetDataFlow function.
Use the olDaSetTrigger function to specify the trigger source that
starts the operation. Refer to page 67 for more information on
supported trigger sources.
When the post-trigger event is detected, the device cycles through the
channel list, acquiring and/or outputting the value for each entry in
the channel list; this process is defined as a scan. The device then
wraps to the start of the channel list and repeats the process
continuously until either the allocated buffers are filled or you stop
the operation. Refer to page 44 for more information on channel lists;
refer to page 71 for more information on buffers.
3
3
3
3
3
3
Figure 1 illustrates continuous post-trigger mode using a channel list
of three entries: channel 0, channel 1, and channel 2. In this example,
post-trigger analog input data is acquired on each clock pulse of the
A/D sample clock; refer to page 65 for more information on clock
sources. The device wraps to the beginning of the channel list and
repeats continuously.
3
3
3
57
Chapter 3
Chan 0
A/D Sample
Clock
Post-trigger event occurs
Figure 1: Continuous Post-Trigger Mode
Continuous Pre-Trigger Mode
Use continuous pre-trigger mode when you want to acquire data
before a specific external event occurs.
To determine if the subsystem supports continuous pre-trigger mode,
use the olDaGetSSCaps function, specifying the
_SUP_CONTINUOUS_PRETRIG capability. If this function returns a
nonzero value, the capability is supported.
Specify the operation mode as OL_DF_CONTINUOUS_PRETRIG
using the olDaSetDataFlow function.
Chan 1
Chan 2
Chan 0
Chan 1
Post-trigger data acquired
continuously
Chan 2
Chan 0
Chan 1
Chan 2
Chan 0
Chan 1
Chan 2
58
Pre-trigger acquisition starts when the device detects the pre-trigger
source and stops when the device detects an external post-trigger
source, indicating that the first post-trigger sample was acquired (this
sample is ignored).
Use the olDaSetPretriggerSource function to specify the trigger
source that starts the pre-trigger operation (generally this is a
software trigger). Specify the post-trigger source that stops the
operation using olDaSetTrigger. Refer to page 67 and to your
device/driver documentation for supported pre-trigger and
post-trigger sources.
Using the DataAcq SDK
Figure 2 illustrates continuous pre-trigger mode using a channel list
of three entries: channel 0, channel 1, and channel 2. In this example,
pre-trigger analog input data is acquired on each clock pulse of the
A/D sample clock; refer to page 65 for more information on clock
sources. The device wraps to the beginning of the channel list and the
acquisition repeats continuously until the post-trigger event occurs.
When the post-trigger event occurs, acquisition stops.
3
3
Chan 0
A/D
Sample
Clock
Pre-trigger event occurs
Chan 1
Pre-trigger data acquired
Continuous About-Trigger Mode
Use continuous about-trigger mode when you want to acquire data
both before and after a specific external event occurs. This operation
is equivalent to doing both a pre-trigger and a post-trigger
acquisition.
To determine if the subsystem supports continuous about-trigger
mode, use the olDaGetSSCaps function, specifying the
OLSSC_SUP_CONTINUOUS_ABOUTTRIG capability. If this
function returns a nonzero value, the capability is supported.
Chan 2
Figure 2: Continuous Pre-Trigger Mode
Chan 0
Chan 2
Chan 0
Chan 1
Post-trigger event occurs
Acquisition stops
3
3
3
3
3
3
Specify the operation mode as OL_DF_CONTINUOUS_ABOUTTRIG
using the olDaSetDataFlow function.
3
59
Chapter 3
The about-trigger acquisition starts when the device detects the
pre-trigger source. When it detects an external post-trigger source,
the device stops acquiring pre-trigger data and starts acquiring
post-trigger data.
Use the olDaSetPretriggerSource function to specify the pre-trigger
source that starts the pre-trigger operation (this is generally a
software trigger) and olDaSetTrigger to specify the trigger source
that stops the pre-trigger acquisition and starts the post-trigger
acquisition. Refer to page 67 and to your device/driver
documentation for supported pre-trigger and post-trigger sources.
The about-trigger operation stops when the specified number of
post-trigger samples has been acquired or when you stop the
operation.
Figure 3 illustrates continuous about-trigger mode using a channel
list of three entries: channel 0, channel 1, and channel 2. In this
example, pre-trigger analog input data is acquired on each clock
pulse of the A/D sample clock. The device wraps to the beginning of
the channel list and the acquisition repeats continuously until the
post-trigger event occurs. When the post-trigger event occurs,
post-trigger acquisition begins on each clock pulse of the A/D
sample clock; refer to page 65 for more information on clock sources.
The device wraps to the beginning of the channel list and acquires
post-trigger data continuously.
60
Using the DataAcq SDK
Chan 0
A/D
Sample
Clock
Pre-trigger event occurs
Chan 0
Chan 1
Pre-trigger data acquired
Chan 1
Figure 3: Continuous About-Trigger Mode
Triggered Scan Mode
In triggered scan mode, the device scans the entries in a channel-gain
list a specified number of times when it detects the specified trigger
source, acquiring the data for each entry that is scanned.
To determine if the subsystem supports triggered scan mode, use the
olDaGetSSCaps function, specifying the OLSSC_SUP_TRIGSCAN
capability. If this function returns a nonzero value, the capability is
supported. Note that you cannot use triggered scan mode with
single-value operations.
Chan 0
Chan 0
Chan 1
Post-trigger event occurs
Chan 1
Chan 1
Chan 0
Chan 1
. . .
Chan 0
Post-trigger data acquired
3
3
3
3
3
3
To enable (or disable) triggered scan mode, use the
olDaSetTriggeredScanUsage function.
To determine the maximum number of times that the device can scan
the channel-gain list per trigger, use the olDaGetSSCaps function,
specifying the OLSSC_MAXMULTISCAN capability.
Use the olDaSetMultiscanCount function to specify the number of
times to scan the channel-gain list per trigger.
3
3
3
61
Chapter 3
The DataAcq SDK defines the following retrigger modes for a
triggered scan; these retrigger modes are described in the following
subsections:
• Scan-per-trigger,
• Internal retrigger, and
• Retrigger extra.
Note: If your device driver supports it, retrigger extra is the
preferred triggered scan mode.
Scan-Per-Trigger Mode
Use scan-per-trigger mode if you want to accurately control the
period between conversions of individual channels and retrigger the
scan based on an internal or external event. In this mode, the
retrigger source is the same as the initial trigger source.
62
To determine if the subsystem supports scan-per-trigger mode, use
the olDaGetSSCaps function, specifying the
OLSSC_SUP_RETRIGGER_SCAN_PER_TRIGGER capability. If this
function returns a nonzero value, the capability is supported.
Specify the retrigger mode as scan-per-trigger using the
olDaSetRetriggerMode function.
When it detects an initial trigger (post-trigger mode only), the device
scans the channel-gain list a specified number of times (determined
by the olDaSetMultiscanCount function), then stops. When the
external retrigger occurs, the process repeats.
Using the DataAcq SDK
The conversion rate of each channel in the scan is determined by the
frequency of the A/D sample clock; refer to page 65 for more
information on clock sources. The conversion rate of each scan is
determined by the period between retriggers; therefore, it cannot be
accurately controlled. The device ignores external triggers that occur
while it is acquiring data. Only retrigger events that occur when the
device is waiting for a trigger are detected and acted on. Some
devices may generate an OLDA_WM_TRIGGER_ERROR message.
3
3
Internal Retrigger Mode
Use internal retrigger mode if you want to accurately control both the
period between conversions of individual channels in a scan and the
period between each scan.
To determine if the subsystem supports internal retrigger mode, use
the olDaGetSSCaps function, specifying the
OLSSC_SUP_RETRIGGER_INTERNAL capability. If this function
returns a nonzero value, the capability is supported.
Specify the retrigger mode as internal using the
olDaSetRetriggerMode function.
The conversion rate of each channel in the scan is determined by the
frequency of the A/D sample clock; refer to page 65 for more
information on clock sources. The conversion rate between scans is
determined by the frequency of the internal retrigger clock on the
device. You specify the frequency on the internal retrigger clock
using the olDaSetRetriggerFrequency function.
When it detects an initial trigger (pre-trigger source or post-trigger
source), the device scans the channel-gain list a specified number of
times (determined by the olDaSetMultiscanCount function), then
stops. When the internal retrigger occurs, determined by the
frequency of the internal retrigger clock, the process repeats.
3
3
3
3
3
3
3
63
Chapter 3
It is recommended that you set the retrigger frequency as follows:
Min. Retrigger = # of CGL entries x # of CGLs per trigger + 2 µs
Period A/D sample clock frequency
Max. Retrigger = 1
Frequency Min. Retrigger Period
For example, if you are using 512 channels in the channel-gain list
(CGL), scanning the channel-gain list 256 times every trigger or
retrigger, and using an A/D sample clock with a frequency of 1 MHz,
set the maximum retrigger frequency to 7.62 Hz, since
7.62 Hz = 1_______
( 512 * 256) +2 µs
1 MHz
Retrigger Extra Mode
Use retrigger extra mode if you want to accurately control the period
between conversions of individual channels and retrigger the scan on
a specified retrigger source; the retrigger source can be any of the
supported trigger sources.
64
To determine if the subsystem supports retrigger extra mode, use the
olDaGetSSCaps function, specifying the
OLSSC_SUP_RETRIGGER_EXTRA capability. If this function returns
a nonzero value, the capability is supported.
Specify the retrigger mode as retrigger extra using the
olDaSetRetriggerMode function.
Use the olDaSetRetrigger function to specify the retrigger source.
Refer to page 67 and to your device/device driver documentation for
supported retrigger sources.
Using the DataAcq SDK
The conversion rate of each channel in the scan is determined by the
frequency of the A/D sample clock; refer to page 65 for more
information on clock sources. The conversion rate of each scan is
determined by the period between retriggers.
3
If you are using an internal retrigger, specify the period between
retriggers using olDaSetRetriggerFrequency (see page 63). If you are
using an external retrigger, the period between retriggers cannot be
accurately controlled. The device ignores external triggers that occur
while it is acquiring data. Only retrigger events that occur when the
device is waiting for a trigger are detected and acted on. Some
devices may generate an OLDA_WM_TRIGGER_ERROR message.
Clock Sources
The DataAcq SDK defines internal, external, and extra clock sources,
described in the following subsections. Note that you cannot specify
a clock source for single-value operations.
Internal Clock Source
The internal clock is the clock source on the device that paces data
acquisition or output for each entry in the channel-gain list.
To determine if the subsystem supports an internal clock, use the
olDaGetSSCaps function, specifying the OLSSC_SUP_INTCLOCK
capability. If this function returns a nonzero value, the capability is
supported.
3
3
3
3
3
3
Specify the clock source as internal using the olDaSetClockSource
function. Then, use the olDaSetClockFrequency function to specify
the frequency at which to pace the operation.
3
3
65
Chapter 3
To determine the maximum frequency that the subsystem supports,
use the olDaGetSSCapsEx function, specifying the
OLSSCE_MAXTHROUGHPUT capability. To determine the
minimum frequency that the subsystem supports, use the
olDaGetSSCapsEx function, specifying the
OLSSCE_MINTHROUGHPUT capability.
Note: According to sampling theory (Nyquist Theorem), you
should specify a frequency for an A/D signal that is at least twice as
fast as the input’s highest frequency component. For example, to
accurately sample a 20 kHz signal, specify a sampling frequency of
at least 40 kHz. Doing so avoids an error condition called aliasing, in
which high frequency input components erroneously appear as
lower frequencies after sampling.
External Clock Source
The external clock is a clock source attached to the device that paces
data acquisition or output for each entry in the channel-gain list. This
clock source is useful when you want to pace at rates not available
with the internal clock or if you want to pace at uneven intervals.
66
To determine if the subsystem supports an external clock, use the
olDaGetSSCaps function, specifying the OLSSC_SUP_EXTCLOCK
capability. If this function returns a nonzero value, the capability is
supported.
Specify the clock source as external using the olDaSetClockSource
function. Then, use the olDaSetExternalClockDivider to specify the
clock divider used to determine the frequency at which to pace the
operation; the clock input source divided by the clock divider
determines the frequency of the clock signal.
To determine the maximum clock divider that the subsystem
supports, use the olDaGetSSCapsEx function, specifying the
OLSSCE_MAXCLOCKDIVIDER capability. To determine the
minimum clock divider that the subsystem supports, use the
olDaGetSSCapsEx function, specifying the
OLSSCE_MINCLOCKDIVIDER capability.
Extra Clock Source
Using the DataAcq SDK
3
3
Your device driver may define extra clock sources that you can use to
pace acquisition or output operations.
To determine how many extra clock sources are supported by your
subsystem, use the olDaGetSSCaps function, specifying the
OLSSC_NUMEXTRACLOCKS capability. Refer to your
device/driver documentation for a description of the extra clock
sources.
The extra clock sources may be internal or external. Refer to the
previous sections for information on how to specify internal and
external clocks and their frequencies or clock dividers.
Trigg er S ources
The DataAcq SDK defines the following trigger sources:
• Software (internal) trigger,
• External digital (TTL) trigger,
• External analog threshold (positive) trigger,
• External analog threshold (negative) trigger,
3
3
3
3
3
3
• Analog event trigger,
• Digital event trigger,
• Timer event trigger, and
• Extra trigger.
3
67
Chapter 3
To specify a post-trigger source, use the olDaSetTrigger function;
refer to page 57 for more information. To specify a pre-trigger source,
use the olDaSetPretriggerSource function; see page 58 for more
information. To specify a retrigger source, use the olDaSetRetrigger
function; see page 64 for more information.
The following subsections describe these trigger sources. Note that
you cannot specify a trigger source for single-value operations.
Software (Internal) Trigger Source
A software trigger occurs when you start the operation; internally,
the computer writes to the device to begin the operation.
To determine if the subsystem supports a software trigger, use the
olDaGetSSCaps function, specifying the capability
OLSSC_SUP_SOFTTRIG. If this function returns a nonzero value, the
capability is supported.
External Digital (TTL) Trigger Source
68
An external digital trigger is a digital (TTL) signal attached to the
device.
To determine if the subsystem supports an external digital trigger,
use the olDaGetSSCaps function, specifying the capability
OLSSC_SUP_EXTERNTRIG. If this function returns a nonzero value,
the capability is supported.
Using the DataAcq SDK
External Analog Threshold (Positive) Trigger Source
An external analog threshold (positive) trigger is generally either an
analog signal from an analog input channel or an external analog
signal attached to the device. An analog trigger occurs when the
device detects a transition from a negative to positive value that
crosses a threshold value. The threshold level is generally set using a
D/A subsystem on the device.
To determine if the subsystem supports analog threshold triggering
(positive polarity), use the olDaGetSSCaps function, specifying the
capability OLSSC_SUP_THRESHTRIGPOS. If this function returns a
nonzero value, the capability is supported.
Refer to your device/device driver documentation for a description
of this trigger source.
External Analog Threshold (Negative) Trigger Source
An external analog threshold (negative) trigger is generally either an
analog signal from an analog input channel or an external analog
signal attached to the device. An analog trigger event occurs when
the device detects a transition from a positive to negative value that
crosses a threshold value. The threshold level is generally set using a
D/A subsystem on the device.
3
3
3
3
3
3
To determine if the subsystem supports analog threshold triggering
(negative polarity), use the olDaGetSSCaps function, specifying the
capability OLSSC_SUP_THRESHTRIGNEG. If this function returns a
nonzero value, the capability is supported.
Refer to your device/device driver documentation for a description
of this trigger source.
3
3
3
69
Chapter 3
Analog Event Trigger Source
For this trigger source, a trigger is generated when an analog event
occurs. To determine if the subsystem supports an analog event
trigger, use the olDaGetSSCaps function, specifying the capability
OLSSC_SUP_ANALOGEVENTTRIG. If this function returns a
nonzero value, the capability is supported.
Digital Event Trigger Source
For this trigger source, a trigger is generated when a digital event
occurs. To determine if the subsystem supports a digital event
trigger, use the olDaGetSSCaps function, specifying the capability
OLSSC_SUP_DIGITALEVENTTRIG. If this function returns a
nonzero value, the capability is supported.
Timer Event Trigger Source
For this trigger source, a trigger is generated when a counter/timer
event occurs. To determine if the subsystem supports a timer event
trigger, use the olDaGetSSCaps function, specifying the capability
OLSSC_SUP_TIMEREVENTTRIG. If this function returns a nonzero
value, the capability is supported.
70
Extra Trigger Source
Extra trigger sources may be defined by your device driver. To
determine how many extra triggers are supported by the subsystem,
use the olDaGetSSCaps function, specifying the capability
OLSSC_NUMEXTRATRIGGERS. Refer to your device/driver
documentation for a description of these triggers.
The extra trigger sources may be internal or external. Refer to the
previous sections for information on how to specify internal and
external triggers.
Buffers
Using the DataAcq SDK
The buffering capability usually applies to A/D and D/A subsystems
only. Note that you cannot use a buffer with single-value operations.
A data buffer is a memory location that you allocate in host memory.
This memory location is used to store data for continuous input and
output operations.
To determine if the subsystem supports buffers, use the
olDaGetSSCaps function, specifying the capability
OLSSC_SUP_BUFFERING. If this function returns a nonzero value,
the capability is supported.
Buffers are stored on one of three queues: the ready queue, the
inprocess queue, or the done queue. These queues are described in
more detail in the following subsections.
Ready Queue
For input operations, the ready queue holds buffers that are empty
and ready for input. For output operations, the ready queue holds
buffers that you have filled with data and that are ready for output.
3
3
3
3
3
3
Allocate the buffers using the olDmMallocBuffer, olDmAllocBuffer,
or olDmCallocBuffer function. olDmAllocBuffer allocates a buffer
of samples, where each sample is 2 bytes; olDmCallocBuffer
allocates a buffer of samples of a specified size; olDmMallocBuffer
allocates a buffer in bytes.
For analog input operations, it is recommended that you allocate a
minimum of three buffers; for analog output operations, you can
allocate one or more buffers. The size of the buffers should be at least
as large as the sampling or output rate; for example, if you are using a
sampling rate of 100 ksamples/s (100 kHz), specify a buffer size of
100,000 samples.
3
3
3
71
Chapter 3
Once you have allocated the buffers (and, for output operations,
filled them with data), put the buffers on the ready queue using the
olDaPutBuffer function.
For example, assume that you are performing an analog input
operation, that you allocated three buffers, and that you put these
buffers on the ready queue. The queues appear on the ready queue as
shown in Figure 4.
Ready Queue
Inprocess Queue
Done Queue
Figure 4: Example of the Ready Queue
Inprocess Queue
When you start a continuous (post-trigger, pre-trigger, or
about-trigger) operation, the data acquisition device takes the first
available buffer from the ready queue and places it on the inprocess
queue.
The inprocess queue holds the buffer that the specified data
acquisition device is currently filling (for input operations) or
outputting (for output operations). The buffer is filled or emptied at
the specified clock rate.
Buffer 1
Buffer 2
Buffer 3
72
Using the DataAcq SDK
Continuing with the previous example, when you start the analog
input operation, the driver takes the first available buffer (Buffer 1, in
this case), puts it on the inprocess queue, and starts filling it with
data. The queues appear as shown in Figure 5.
3
Ready Queue
Inprocess Queue
Done Queue
If required, you can use the olDaFlushFromBufferInprocess
function to transfer data from a partially-filled buffer on an inprocess
queue to a buffer you create (if this capability is supported).
Typically, you would use this function when your data acquisition
operation is running slowly.
To determine if the subsystem supports transferring data from a
buffer on the inprocess queue, use the olDaGetSSCaps function,
specifying the OLSSC_SUP_INPROCESSFLUSH capability. If this
function returns a nonzero value, this capability is supported.
Buffer 2
Buffer 1
Figure 5: Example of the Inprocess Queue
Buffer 3
3
3
3
3
3
3
3
3
73
Chapter 3
Note: Some devices transfer data to the host in segments instead of
one sample at a time. For example, data from some boards is
transferred to the host in 64 byte segments; the number of valid
samples is always a multiple of 64 depending on the number of
samples transferred to the host when
olDaFlushFromBufferInprocess was called. It is up to your
application to take this into account when flushing an inprocess
buffer. Refer to your device documentation for more information.
Done Queue
Once the data acquisition device has filled the buffer (for input
operations) or emptied the buffer (for output operations), the buffer
is moved from the inprocess queue to the done queue. Then, either
the OLDA_WM_BUFFER_DONE message is generated when the
buffer contains post-trigger data, or in the case of pre-trigger and
about-trigger acquisitions, an
OLDA_WM_PRETRIGGER_BUFFER_DONE message is generated
when the buffer contains pre-trigger data.
74
Note: For pre-trigger acquisitions only, when the operation
completes or you stop a pre-trigger acquisition, the
OLDA_WM_QUEUE_STOPPED message is also generated.
Continuing with the previous example, the queues appear as shown
in Figure 6 when you get the first OLDA_WM_BUFFER_DONE
message.
Using the DataAcq SDK
Ready Queue
Inprocess Queue
Done Queue
Then, the driver moves Buffer 2 from the ready queue to the
inprocess queue and starts filling it with data. When Buffer 2 is filled,
Buffer 2 is moved to the done queue and another
OLDA_WM_BUFFER_DONE message is generated.
The driver then moves Buffer 3 from the ready queue to the inprocess
queue and starts filling it with data. When Buffer 3 is filled, Buffer 3 is
moved to the done queue and another OLDA_WM_BUFFER_DONE
message is generated. Figure 7 shows how the buffers are moved.
Buffer 2
Buffer 1
Figure 6: Example of the Done Queue
Buffer 3
3
3
3
3
3
3
Ready Queue
Inprocess Queue
Done Queue
Figure 7: How Buffers are Moved to the Done Queue
Buffer 1
Buffer 2
3
3
Buffer 3
3
75
Chapter 3
If you transferred data from an inprocess queue to a new buffer using
olDaFlushFromBufferInprocess, the new buffer is put on the done
queue for your application to process. When the buffer on the
inprocess queue finishes being filled, this buffer is also put on the
done queue; the buffer contains only the samples that were not
previously transferred.
Buffer and Queue Management
Each time it gets an OLDA_WM_BUFFER_DONE message, your
application program should remove the buffers from the done queue
using the olDaGetBuffer buffer management function.
Your application program can then process the data in the buffer. For
an input operation, you can copy the data from the buffer to an array
in your application program using the olDmGetBufferPtr function.
For continuously paced analog output operations, you can fill the
buffer with new output data using the olDaGetBufferPtr function.
If you want to convert the count value to engineering units, you can
use the olDaCodeToVolts function. Similarly, if you want to convert
the engineering units to counts, you can use the olDaVoltsToCode
function.
76
When you are finished processing the data, you can put the buffer
back on the ready queue using the olDaPutBuffer function if you
want your operation to continue.
For example, assume that you processed the data from Buffer 1 and
put it back on the ready queue. The queues would appear as shown
in Figure 8.
Using the DataAcq SDK
Ready Queue
Inprocess Queue
Done Queue
Figure 8: Putting Buffers Back on the Ready Queue
When the data acquisition operation is finished, use the
olDaFlushBuffers function to transfer any data buffers left on the
subsystem’s ready queue to the done queue.
Once you have processed the data in the buffers, remove the buffers
from the done queue using the olDaFreeBuffer function.
Note: For analog output operations only, the
OLDA_WM_IO_COMPLETE message is generated when the last
data point has been output from the analog output channel. In some
cases, this message is generated well after the data is transferred
from the buffer (when the OLDA_WM_BUFFER_DONE and
OLDA_WM_QUEUE_DONE messages are generated.
Buffer 2
Buffer 3
Buffer 1
3
3
3
3
3
3
3
3
3
77
Chapter 3
Buffer Wrap Modes
Most Keithley data acquisition devices can provide gap-free data,
meaning no samples are missed when data is acquired or output. You
can acquire gap-free data by manipulating data buffers so that no
gaps exist between the last sample of the current buffer and the first
sample of the next buffer.
Note: The number of DMA channels, number of buffers, and buffer
size are critical to the device’s ability to provide gap-free data. It is
also critical that the application process the data in a timely fashion.
If you want to acquire gap-free input data, it is recommended that
you specify a buffer wrap mode of none using the
olDaSetWrapMode buffer management function. When a buffer
wrap mode of none is selected, if you process the buffers and put
them back on the ready queue in a timely manner, the operation
continues indefinitely. When no buffers are available on the ready
queue, the operation stops, and an OLDA_WM_QUEUE_DONE
message is generated.
78
If you want to continuously reuse the buffers in the queues and you
are not concerned with gap-free data, specify multiple buffer wrap
mode using olDaSetWrapMode. When multiple wrap mode is
selected and no buffers are available on the ready queue, the driver
moves the oldest buffer from the done queue to the inprocess queue
(regardless of whether you have processed its data), and overwrites
the data in the buffer. This process continues indefinitely unless you
stop it. When it reuses a buffer on the done queue, the driver
generates an OLDA_WM_BUFFER_REUSED message.
Using the DataAcq SDK
If you want to perform gap-free analog output operations, specify
single wrap mode using olDaSetWrapMode. When single wrap
mode is specified, a single buffer is reused continuously. In this case,
the driver moves the buffer from the ready queue to the inprocess
queue and outputs the data from the buffer. However, when the
buffer is emptied, the driver (or device) reuses the data and
continuously outputs it. This process repeats indefinitely until you
stop it. When you stop the operation, the buffer is moved to the done
queue. Typically, no messages are posted in this mode until you stop
the operation.
To determine the buffer wrap modes available for the subsystem, use
the olDaGetSSCaps function, specifying the capability
OLSSC_SUP_WRPSINGLE (for single wrap mode) or
OLSSC_SUP_WRPMULTIPLE (for multiple wrap mode). If this
function returns a nonzero value, the capability is supported.
3
3
3
3
DMA and Interrupt Resources
You cannot use DMA or interrupt resources for single-value
operations.
To determine if your subsystem supports interrupt resources, use the
olDaGetSSCaps function, specifying the capability
OLSSC_SUP_INTERRUPT. If this function returns a nonzero value,
the capability is supported.
Generally, you specify interrupt resources on the device itself or in
the driver configuration dialog.
To determine if gap-free data acquisition is supported, use the
olDaGetSSCaps function, specifying
OLSSC_SUP_GAPFREE_NODMA (for gap free data using no DMA
channels), OLSSC_SUP_GAPFREE_SINGLEDMA (for gap free data
using one DMA channel), or OLSSC_SUP_GAPFREE_DUALDMA
(for gap free data using two DMA channels). If this function returns a
nonzero value, the capability is supported.
3
3
3
3
3
79
Chapter 3
To determine how many DMA channels are supported, use the
olDaGetSSCaps function, specifying the capability
OLSSC_NUMDMACHANS.
Use the olDaSetDmaUsage function to specify the number of DMA
channels to use. These channels must also be specified in the driver
configuration dialog.
Note: DMA channels are a limited resource and the request may
not be honored if the requested number of channels is unavailable.
For example, suppose that a device that supports both A/D and
D/A subsystems provides hardware for two DMA channels, and
that one DMA channel is currently allocated to the A/D subsystem.
In this case, a request to the D/A subsystem to use two DMA
channels will fail.
80
Counter/Timer Operations
Each user counter/timer channel accepts a clock input signal and
gate input signal and outputs a clock output signal (also called a
pulse output signal), as shown in Figure 9.
Using the DataAcq SDK
3
3
Clock Input SIgnal
(internal, external, or
internally cascaded)
Each counter/timer channel corresponds to a counter/timer (C/T)
subsystem. To specify the counter to use in software, specify the
appropriate C/T subsystem. For example, counter 0 corresponds to
C/T subsystem element 0; counter 3 corresponds to C/T subsystem
element 3.
The DataAcq SDK defines the following capabilities that you can
query and/or configure for counter/timer operations:
• Counter/timer operation mode,
• Clock source,
Counter/Timer
Gate Input Signal
(software or
external input)
Figure 9: Counter/Timer Channel
Pulse Output Signal
3
3
3
3
3
3
• Gate source,
3
81
Chapter 3
• Pulse output type, and
• Pulse output duty cycle.
The following subsections describe these capabilities in more detail.
Counter/Timer Operation Mode
The DataAcq SDK supports the following counter/timer operations:
• Event counting,
• Up/down counting,
• Frequency measurement,
• Edge-to-edge measurement,
• Rate generation (continuous pulse output),
• One-shot, and
• Repetitive one-shot.
The following subsections describe these counter/timer operations.
82
Event Counting
Use event counting mode to count events from the counter’s
associated clock input source.
To determine if the subsystem supports event counting, use the
olDaGetSSCaps function, specifying the capability
OLSSC_SUP_CTMODE_COUNT. If this function returns a nonzero
value, the capability is supported.
To specify an event counting operation, use the olDaSetCTMode
function, specifying the OL_CTMODE_COUNT parameter.
Using the DataAcq SDK
Specify the C/T clock source for the operation. In event counting
mode, an external C/T clock source is more useful than the internal
C/T clock source; refer to page 101 for more information on
specifying the C/T clock source.
3
Also specify the gate type that enables the operation; refer to page 104
for more information on specifying the gate type.
Start an event counting operation using the olDaStart function. To
read the current number of events counted, use the olDaReadEvents
function.
To stop the event counting operation, call olDaStop, olDaAbort, or
olDaReset; olDaReset function stops the operation and reinitializes
the subsystem after stopping it.
Some subsystems also allow you to pause the operation using the
olDaPause function and then resume the paused operation using the
olDaContinue function. To determine if pausing is supported, use
the olDaGetSSCaps function, specifying the OLSSC_SUP_PAUSE
capability. If this function returns a nonzero value, the capability is
supported.
Figure 10 shows an example of an event counting operation. In this
example the gate type is low level.
3
3
3
3
3
3
3
3
83
Chapter 3
High level
disables operation
Gate Input
Signal
External C/T
Clock
Input Signal
Up/Down Counting
Low level
enables operation
3 events are counted while
the operation is enabled
Event counting
operation starts
Event counting
operation stops
Figure 10: Example of Event Counting
Use up/down counting mode to increment or decrement the number
of rising edges that occur on the counter’s associated clock input,
depending on the level of the counter’s associated gate signal. If the
gate signal is high, the C/T increments; if the gate signal is low, the
C/T decrements.
84
To determine if the subsystem supports up/down counting, use the
olDaGetSSCaps function, specifying the capability
OLSSC_SUP_CTMODE_UP_DOWN. If this function returns a
nonzero value, the capability is supported.
To specify an up/down counting operation, use the olDaSetCTMode
function, specifying the OL_CTMODE_UP_DOWN parameter.
Loading...