Tektronix DASCard-1000 Series ASO Function Call Driver Users Guide

Download

D ASCard-1000 Series Function Call Driver

USER’S GUIDE

DASCard-1000 Series

Function Call Driver

User’s Guide

Revision A – June 1995

Part Number: 91880

New Contact Information

Keithley Instruments, Inc.

28775 Aurora Road

Cleveland, OH 44139

Technical Support: 1-888-KEITHLEY

Monday – Friday 8:00 a.m. to 5:00 p.m (EST)

Fax: (440) 248-6168

Visit our website at http://www.keithley.com

The information contained in this manual is believed to be accurate and reliable. However, Keithley Instruments, Inc., assumes no responsibility for its use or for any infringements of patents or other rights of third parties that may result from its use. No license is granted by implication or otherwise under any patent rights of Keithley Instruments, Inc.

KEITHLEY INSTRUMENTS, INC., SHALL NO T BE LIABLE FOR ANY SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES RELATED TO THE USE OF THIS PRODUCT. THIS PRODUCT IS NOT DESIGNED WITH COMPONENTS OF A LEVEL OF RELIABILITY SUITABLE FOR USE IN LIFE SUPPORT OR CRITICAL APPLICATIONS.

Refer to your Keithley Instruments license agreement for speciﬁc warranty and liability information.

MetraByte is a trademark of Keithley Instruments, Inc. All other brand and product names are trademarks or registered trademarks of their respective companies.

All rights reserved. Reproduction or adaptation of any part of this documentation beyond that permitted by Section 117 of the 1976 United States Copyright Act without permission of the Copyright owner is unlawful.

Keithley MetraByte Division

Keithley Instruments, Inc.

440 Myles Standish Blvd. Taunton, MA 02780

FAX: (508) 880-0179

Telephone: (508) 880-3000

●

Preface

This manual describes how to write application programs for the DASCard-1000 Series using the DASCard-1000 Series Function Call Driver. The DASCard-1000 Series Function Call Driver supports the following DOS-based languages:

●

Microsoft



QuickBasic  (Version 4.5)

Microsoft Professional Basic (Version 7.0)

●

Microsoft C/C++ (Versions 7.0 and 8.0)

●

Borland



C/C++ (Versions 3.1 and 4.0)

The DASCard-1000 Series Function Call Driver also supports the following W indows  -based languages:

Microsoft C/C++ (Versions 7.0 and 8.0)

●

Borland C/C++ (Versions 3.1 and 4.0) Microsoft Visual Basic

●

Microsoft Visual C++  (Version 1.5)

●



for Windows (Version 3.0)

The manual is intended for application programmers using a DASCard-1000 Series card in a notebook or desktop computer. It is assumed that users have read the DASCard-1000 Series User’s Guide to familiarize themselves with the card’s features and that they have completed the appropriate hardware and software installation and conﬁguration. It is also assumed that users are experienced in programming in their selected language and that they are familiar with PCMCIA and data acquisition principles.

The DASCard-1000 Series Function Call Driver User’s Guide is organized as follows:

●

Chapter 1 provides an overvie w of the Function Call Driv er , describes how to get started using the Function Call Driver, and describes how to get help.

●

Chapter 2 contains the background information needed to use the functions included in the Function Call Driver.

Chapter 3 contains programming guidelines and language-speciﬁc

●

information related to using the Function Call Driver.

●

Chapter 4 contains detailed descriptions of the functions, arranged in alphabetical order.

●

Appendix A contains a list of the error codes returned by the Function Call Driver.

●

Appendix B contains instructions for converting counts to v oltage and for converting voltage to counts.

An index completes this manual.

Keep the following conventions in mind as you use this manual:

References to DASCard-1000 Series cards apply to the

●

DASCard-1001, DASCard-1002, and DASCard-1003 cards. When a feature applies to a particular card, that card’s name is used.

References to BASIC apply to the DOS-based BASIC languages

●

(Microsoft QuickBasic and Microsoft Professional Basic). When a feature applies to a speciﬁc language, the complete language name is used. References to Visual Basic for Windows apply to Microsoft Visual Basic for Windows.

●

Keyboard keys are shown in bold typeface.

Table of Contents

Preface

Getting Started

Available Operations

System Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1

Initializing the Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-2

Initializing a Card . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-2

Retrieving Card Information. . . . . . . . . . . . . . . . . . . . . . . . . .2-3

Retrieving Revision Levels . . . . . . . . . . . . . . . . . . . . . . . . . . .2-4

Handling Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-4

Analog Input Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-5

Operation Modes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-5

Single Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-5

Synchronous Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-6

Interrupt Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-6

Memory Allocation and Management. . . . . . . . . . . . . . . . . . .2-7

Dimensioning Local Arrays. . . . . . . . . . . . . . . . . . . . . . . .2-7

Dynamically Allocating Memory Buffers . . . . . . . . . . . . .2-8

Assigning the Starting Addresses. . . . . . . . . . . . . . . . . . . .2-9

Gains and Ranges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-10

Channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-11

Specifying a Single Channel . . . . . . . . . . . . . . . . . . . . . .2-13

Specifying a Group of Consecutive Channels . . . . . . . . .2-13

Specifying Channels in a Channel-Gain Queue. . . . . . . .2-14

Pacer Clocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-15

Internal Pacer Clock. . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-16

External Pacer Clock . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-17

Buffering Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-17

Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-18

Analog Trigger. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-18

Digital Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-22

Data Correction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-22

Digital I/O Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-24

Digital Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-25

Digital Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-26

iii

Programming with the Function Call Driver

How the Driver Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-1

Programming Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-6

Preliminary Tasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-7

Analog Input Programming Tasks . . . . . . . . . . . . . . . . . . . . . . . .3-7

Single-Mode Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-7

Synchronous-Mode Operations. . . . . . . . . . . . . . . . . . . . . . . .3-8

Interrupt-Mode Operations . . . . . . . . . . . . . . . . . . . . . . . . . .3-10

Digital I/O Programming Tasks . . . . . . . . . . . . . . . . . . . . . . . . .3-12

C/C++ Programming Information . . . . . . . . . . . . . . . . . . . . . . .3-13

Dynamically Allocating and Assigning Memory Buffers. . .3-13

Allocating a Single Memory Buffer. . . . . . . . . . . . . . . . .3-13

Allocating Multiple Memory Buffers. . . . . . . . . . . . . . . .3-14

Accessing the Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-15

Dimensioning and Assigning Local Arrays. . . . . . . . . . . . . .3-15

Dimensioning a Single Array. . . . . . . . . . . . . . . . . . . . . .3-16

Dimensioning Multiple Arrays. . . . . . . . . . . . . . . . . . . . .3-16

Creating a Channel-Gain Queue . . . . . . . . . . . . . . . . . . . . . .3-17

Correcting Data (for DOS) . . . . . . . . . . . . . . . . . . . . . . . . . .3-18

Correcting Data (for Windows). . . . . . . . . . . . . . . . . . . . . . .3-19

Handling Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-20

Programming in Microsoft C/C++ (for DOS). . . . . . . . . . . .3-20

Programming in Microsoft C/C++ (for Windows) . . . . . . . .3-21

Programming in Borland C/C++ (for DOS) . . . . . . . . . . . . .3-23

Programming in Borland C/C++ (for Windows). . . . . . . . . .3-24

Visual Basic for Windows Programming Information. . . . . . . .3-25

Dynamically Allocating and Assigning Memory Buffers. . .3-25

Allocating a Single Memory Buffer. . . . . . . . . . . . . . . . .3-26

Allocating Multiple Memory Buffers. . . . . . . . . . . . . . . .3-26

Accessing the Data from Buffers with

Fewer than 64K Bytes . . . . . . . . . . . . . . . . . . . . . . . . . .3-27

Accessing the Data from Buffers with

More than 64K Bytes . . . . . . . . . . . . . . . . . . . . . . . . . . .3-28

Dimensioning and Assigning Local Arrays. . . . . . . . . . . . . .3-30

Dimensioning a Single Array. . . . . . . . . . . . . . . . . . . . . .3-30

Dimensioning Multiple Arrays. . . . . . . . . . . . . . . . . . . . .3-30

Creating a Channel-Gain Queue . . . . . . . . . . . . . . . . . . . . . .3-31

Correcting Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-32

Handling Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-33

Programming in Microsoft Visual Basic for Windows . . . . .3-33

BASIC Programming Information. . . . . . . . . . . . . . . . . . . . . . .3-34

Dynamically Allocating and Assigning Memory Buffers. . .3-34

Reducing the Memory Heap . . . . . . . . . . . . . . . . . . . . . .3-34

Allocating a Single Memory Buffer. . . . . . . . . . . . . . . . .3-34

Allocating Multiple Memory Buffers. . . . . . . . . . . . . . . .3-35

Accessing the Data from Buffers with

Fewer than 64K Bytes . . . . . . . . . . . . . . . . . . . . . . . . . .3-36

Accessing the Data from Buffers with

More than 64K Bytes . . . . . . . . . . . . . . . . . . . . . . . . . . .3-36

Dimensioning and Assigning Local Arrays. . . . . . . . . . . . . .3-39

Dimensioning a Single Array. . . . . . . . . . . . . . . . . . . . . .3-39

Dimensioning Multiple Arrays. . . . . . . . . . . . . . . . . . . . .3-39

Creating a Channel-Gain Queue . . . . . . . . . . . . . . . . . . . . . .3-40

Correcting Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-41

Handling Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-42

Programming in Microsoft QuickBasic . . . . . . . . . . . . . . . .3-42

Programming in Microsoft Professional Basic . . . . . . . . . . .3-43

Function Reference

DAS1000_DevOpen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-6

DAS1000_GetCardInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-8

DAS1000_GetDevHandle . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-10

K_ADRead. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-12

K_BufListAdd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-14

K_BufListReset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-16

K_ClearFrame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-18

K_CloseDriver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-19

K_ClrContRun . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-20

K_CorrectData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-22

K_DASDevInit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-24

K_DIRead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-25

K_DOWrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-27

K_FormatChnGAry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-29

K_FreeDevHandle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-31

K_FreeFrame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-32

K_GetADConﬁg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-33

K_GetADFrame. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-35

K_GetADMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-37

K_GetCalData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-39

K_GetClkRate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-42

K_GetDevHandle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-44

K_GetErrMsg. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-46

K_GetShellVer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-47

K_GetVer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-49

K_IntAlloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-51

K_IntFree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-53

K_IntStart. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-54

K_IntStatus. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-55

K_IntStop. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-58

K_MoveBufToArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-60

K_OpenDriver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-62

K_RestoreChnGAry. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-64

K_SetADConﬁg. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-65

K_SetADMode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-67

K_SetADTrig. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-69

K_SetBuf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-71

K_SetBufI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-73

K_SetCalMode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-75

K_SetChn. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-77

K_SetChnGAry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-79

K_SetClk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-81

K_SetClkRate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-83

K_SetContRun . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-85

K_SetDITrig. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-87

K_SetG. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-89

K_SetStartStopChn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-91

K_SetStartStopG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-93

K_SetTrig. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-96

K_SetTrigHyst . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-98

K_SyncStart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-100

Error/Status Codes

Data Formats

Converting Corrected Counts to Voltage . . . . . . . . . . . . . . . . . . B-2

Converting Voltage to Counts. . . . . . . . . . . . . . . . . . . . . . . . . . . B-4

Specifying a Trigger Level . . . . . . . . . . . . . . . . . . . . . . . . . . B-4

Specifying a Hysteresis Value . . . . . . . . . . . . . . . . . . . . . . . . B-5

Index

List of Figures

Figure 2-1. Analog Input Channels . . . . . . . . . . . . . . . . . . . .2-12

Figure 2-2. Analog Trigger Conditions . . . . . . . . . . . . . . . . .2-19

Figure 2-3. Using a Hysteresis Value. . . . . . . . . . . . . . . . . . .2-21

Figure 2-4. Digital Input Bits . . . . . . . . . . . . . . . . . . . . . . . . .2-25

Figure 2-5. Digital Output Bits. . . . . . . . . . . . . . . . . . . . . . . .2-26

Figure 3-1. Single-Mode Function . . . . . . . . . . . . . . . . . . . . . .3-2

Figure 3-2. Interrupt-Mode Operation . . . . . . . . . . . . . . . . . . .3-3

List of Tables

Table 2-1. Supported Operations . . . . . . . . . . . . . . . . . . . . . .2-1

Table 2-2. Analog Input Ranges . . . . . . . . . . . . . . . . . . . . . .2-10

Table 2-3. Logical Channels . . . . . . . . . . . . . . . . . . . . . . . . .2-12

Table 3-1. A/D Frame Elements . . . . . . . . . . . . . . . . . . . . . . .3-4

Table 3-2. Setup Functions for Synchronous-Mode

Analog Input Operations . . . . . . . . . . . . . . . . . . . .3-8

Table 3-3. Setup Functions for Interrupt-Mode

Analog Input Operations . . . . . . . . . . . . . . . . . . .3-11

Table 3-4. Protected-Mode Memory Architecture . . . . . . . .3-28

Table 3-5. Real-Mode Memory Architecture . . . . . . . . . . . .3-37

Table 4-1. Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-2

Table 4-2. Data Type Prefixes. . . . . . . . . . . . . . . . . . . . . . . . .4-5

Table A-1. Error/Status Codes. . . . . . . . . . . . . . . . . . . . . . . . A-1

Table B-1. Span Values for A/D Conversion Equations . . . . B-2

vii

Getting Started

The DASCard-1000 Series Function Call Driver is a library of data acquisition and control functions (referred to as the Function Call Driver or FCD functions). It is part of the following two software packages:

●

DASCard-1000 Series standard software package - This is the

software package that is shipped with DASCard-1000 Series cards; it includes the following:

– Libraries of FCD functions for Microsoft QuickBasic and

Microsoft Professional Basic.

– Support ﬁles, containing program elements, such as function

prototypes and deﬁnitions of variable types, that are required by the FCD functions.

– Utility programs, running under DOS and Windows, that allow

you to allocate resources for, conﬁgure, calibrate, and test the

features of DASCard-1000 Series cards. – Language-speciﬁc example programs. – Support ﬁles for using the DASCard-1000 Series cards with

Visual Test Extensions

ASO-1000 software package - This is the advanced software option

●

for the DASCard-1000 Series cards. It includes the following: – Libraries of FCD functions for Microsoft C/C++ and Borland

C/C++. – Dynamic Link Libraries (DLLs) of FCD functions for Microsoft

C/C++, Borland C/C++, Microsoft Visual Basic for Windows,

and Microsoft Visual C++. – Support ﬁles, containing program elements, such as function

prototypes and deﬁnitions of variable types, that are required by

the FCD functions.



(VTX



1-1

– Utility programs, running under DOS and Windows, that allow

you to allocate resources for, conﬁgure, calibrate, and test the

features of the DASCard-1000 Series cards. – Language-speciﬁc example programs. – Support ﬁles for using the DASCard-1000 Series cards with

VTX.

Before you use the Function Call Driver, make sure that you have installed the software and your DASCard-1000 Series cards using the procedures described in Chapter 3 of the DASCard-1000 Series User’s

Guide .

If you need help installing or using the DASCard-1000 Series Function Call Driver, call your local sales ofﬁce or the Keithley MetraByte Applications Engineering Department at:

(508) 880-3000 Monday - Friday, 8:00

A.M.

- 6:00

P.M.

, Eastern Time

An applications engineer will help you diagnose and resolve your problem over the telephone.

1-2 Getting Started

Please make sure that you have the follo wing information av ailable before you call:

DASCard-1000 Series card

Computer

Operating system

Card and socket services

Software package

Model Serial # Revision code Input conﬁguration Input range type

Manufacturer CPU type Clock speed (MHz) Math coprocessor Amount of RAM Video system BIOS type PCMCIA controller Memory manager

DOS version Windows version Windows mode

Type Version

Name Serial # Version Invoice/Order #

_____________________ _____________________ _____________________ Single-ended Differential Unipolar Bipolar

_____________________ 386 486 Pentium 20 25 33 50 66 75 100 Yes No _____________________ EGA VGA SVGA _____________________ _____________________ _____________________

_____________________

3.0 3.1 Standard Enhanced

_____________________ _____________________

_____________________ _____________________ _____________________ _____________________

Compiler (if applicable)

Accessories

Language Manufacturer Version

Type/Number Type/Number Type/Number Type/Number Type/Number Type/Number Type/Number Type/Number

_____________________ _____________________ _____________________

_____________________ _____________________ _____________________ _____________________ _____________________ _____________________ _____________________ _____________________

1-3

Available Operations

This chapter contains the background information you need to use the FCD functions to perform operations on DASCard-1000 Series cards. The supported operations are listed in Table 2-1.

System Operations

This section describes the miscellaneous and general maintenance operations that apply to DASCard-1000 Series cards and to the DASCard-1000 Series Function Call Driver. It includes information on the following operations:

Initializing the driver

●

Initializing a card

●

Retrieving card information Retrieving revision levels

●

Table 2-1. Supported Operations

Operation Page Reference

System page 2-1 Analog input page 2-5 Digital input and output (I/O) page 2-24

●

Handling errors

System Operations 2-1

Initializing the Driver

You must initialize the DASCard-1000 Series Function Call Driver and any other Keithley DAS Function Call Drivers you are using in your application program. To initialize the drivers, use the K_OpenDriver function. You specify the driver you are using and the conﬁguration ﬁle that deﬁnes the use of the driver. The driver returns a unique identiﬁer for the driver; this identiﬁer is called the driver handle.

You can specify a maximum of 30 driver handles for all the Keithley MetraByte drivers initialized from all your application programs. If you no longer require a driver and you want to free some memory or if you have used all 30 driver handles, you can use the K_CloseDriver function to free a driver handle and close the associated driver.

If the driver handle you free is the last driver handle speciﬁed for a Function Call Driver, the driver is shut down. (For Windows-based languages only, the DLLs associated with the Function Call Driver are shut down and unloaded from memory.)

Note:

K_CloseDriver are not available. You must use the DAS1000_DevOpen

function instead. DAS1000_DevOpen initializes the DASCard-1000 Series Function Call Driver according to the conﬁguration ﬁle you specify. Refer to page 4-6 for more information. In BASIC, closing the DASCard-1000 Series Function Call Driver is not required.

Initializing a Card

The DASCard-1000 Series Function Call Driver supports up to two DASCard-1000 Series cards. You must use the K_GetDevHandle function to specify the cards you want to use. The driver returns a unique identiﬁer for each card; this identiﬁer is called the device handle.

Device handles allow you to communicate with more than one Keithley MetraByte DAS card or board. You use the device handle returned by

K_GetDevHandle in subsequent function calls related to the card or

board.

If you are programming in BASIC, K_OpenDriver and

2-2 Available Operations

You can specify a maximum of 30 device handles for all the Keithley MetraByte DAS cards or boards accessed from all your application programs. If a card or board is no longer being used and you want to free some memory or if you have used all 30 device handles, you can use the

K_FreeDevHandle function to free a device handle.

Note:

If you are programming in BASIC, K_GetDevHandle and

K_FreeDevHandle are not available. You must use the DAS1000_GetDevHandle function instead. Refer to page 4-10 for more

information. In BASIC, freeing a device handle is not required.

To reinitialize a Keithley MetraByte DAS card or board during an operation, use the K_DASDevInit function. DAS1000_GetDevHandle ,

K_GetDevHandle , and K_DASDevInit perform the following tasks:

●

Abort all operations currently in progress that are associated with the card or board identiﬁed by the device handle.

Verify that the card or board identiﬁed by the device handle is the

●

device speciﬁed in the conﬁguration ﬁle associated with the device.

Retrieving Card Information

The Keithley MetraByte Enabler (KMENABLE.EXE) requests a base address, interrupt level, and memory segment address for each DASCard-1000 Series card from PCMCIA Card Services and then provides information about the assigned resources to your application program. To determine which system resources PCMCIA Card Services assigned, you can use the DAS1000_GetCardInfo function in your application program. Y ou specify a D ASCard-1000 Series card; the dri v er returns the socket in which the card is installed, the interrupt level, the base address, the memory segment address, and the card type. Refer to the DASCard-1000 Series User’s Guide for more information about the Enabler.

System Operations 2-3

Retrieving Revision Levels

If you are using functions from different Keithley DAS Function Call Drivers in the same application program or if you are having problems with your application program, you may want to verify which versions of the Function Call Driver, Keithley DAS Driver Speciﬁcation, and Keithley DAS Shell are used by your Keithley MetraByte DAS card or board.

The K_GetVer function allows you to get both the revision number of the Function Call Driver and the re vision number of the K eithley DAS Driver Speciﬁcation to which the driver conforms.

The K_GetShellVer function allows you to get the revision number of the Keithley DAS Shell (the Keithley DAS Shell is a group of functions that are shared by all Keithley MetraByte DAS cards and boards).

Handling Errors

Each FCD function returns a code indicating the status of the function. To ensure that your application program runs successfully, it is recommended that you check the returned code after the execution of each function. If the status code equals 0, the function executed successfully and your program can proceed. If the status code does not equal 0, an error occurred; ensure that your application program takes the appropriate action. Refer to Appendix A for a complete list of error codes.

Each supported language uses a different procedure for error checking; refer to the following pages for more information:

C/C++ page 3-20 Visual Basic for Windows page 3-33 BASIC page 3-42

For C-language application programs only, the Function Call Driver provides the K_GetErrMsg function, which gets the address of the string corresponding to an error code.

2-4 Available Operations

Analog Input Operations

This section describes the following:

●

Analog input operation modes available. How to allocate and manage memory for analog input operations.

●

How to specify the following for an analog input operation: – Channels and gains – Clock source – Buffering mode – Trigger source

●

How to correct analog input data using calibration factors.

Operation Modes

The operation mode determines which attributes you can specify for an analog input operation and how data is transferred from the DASCard-1000 Series card to computer memory. You can perform analog input operations in single mode, synchronous mode, and interrupt mode, as described in the following sections.

Single Mode

In single mode, the card acquires a single sample from an analog input channel. The driver initiates the con v ersion; you cannot perform any other operation until the single-mode operation is complete.

Use the K_ADRead function to start an analog input operation in single mode. Y ou specify the card you want to use, the analog input channel, the gain at which you want to read the signal, and the variable in which to store the converted data.

Analog Input Operations 2-5

Synchronous Mode

In synchronous mode, the card acquires a single sample or multiple samples from one or more analog input channels. A hardw are pacer clock initiates conversions. The hardware temporarily stores the acquired data in the 512-word FIFO (ﬁrst-in, ﬁrst-out data buffer) on the card, and then transfers the data from the FIFO to a user-deﬁned buffer in computer memory. After the driver transfers the speciﬁed number of samples to computer memory, the driver returns control to the application program. You cannot perform any other operation until a synchronous-mode operation is complete.

Use the K_SyncStart function to start an analog input operation in synchronous mode.

Interrupt Mode

In interrupt mode, the card acquires a single sample or multiple samples from one or more analog input channels. A hardware clock initiates conversions. Once the analog input operation begins, control returns to your application program. The hardware temporarily stores the acquired data in the FIFO, and then transfers the data from the FIFO to a user-deﬁned buffer in computer memory using an interrupt service routine.

Use the K_IntStart function to start an analog input operation in interrupt mode.

You can specify either single-cycle or continuous buffering mode for interrupt-mode operations. Refer to page 2-17 for more information on buffering modes. Use the K_IntStop function to stop a continuous-mode interrupt operation. Use the K_IntStatus function to determine the current status of an interrupt operation.

2-6 Available Operations

Memory Allocation and Management

Analog input operations require memory buffers in which to store acquired data. For synchronous mode and interrupt mode, you can allocate a single memory buffer; for interrupt mode only, you can allocate multiple buffers (up to a maximum of 150) to increase the number of samples you can acquire. The ways you allocate and manage memory are described in the following sections.

Note:

For interrupt-mode operations, the hardware transfers data either when the FIFO is half full (the number of samples is greater than or equal to 256) or when the FIFO has any data (when the number of samples is between 1 and 255). For best performance when using multiple-buffer or continuous-mode operations to acquire data, it is recommended that you allocate a buffer equal to or greater than 256 samples, even if you are not acquiring 256 samples. For single-buffer or single-cycle operations, you can allocate a buffer of any allowable size.

Dimensioning Local Arrays

The simplest way to reserve memory buf fers is to dimension arrays within your application program. The advantage of this method is that the arrays are directly accessible to your application program. The limitations of this method are as follows:

●

Certain programming languages limit the size of local arrays. Local arrays occupy permanent memory areas; these memory areas

●

cannot be freed to make them available to other programs or processes.

Since the DASCard-1000 Series Function Call Dri ver stores data in 16-bit integers (12 bits of which determine the data), you must dimension all local arrays as integers.

Analog Input Operations 2-7

Dynamically Allocating Memory Buffers

The recommended way to reserve memory buffers is to allocate them dynamically outside of your application program’s memory area. The advantages of this method are as follows:

●

The number of memory buffers and the size of the b uffers are limited by the amount of free physical memory available in your computer at run-time.

●

Dynamically allocated memory buffers can be freed to make them available to other programs or processes.

The limitation of this method is that for Visual Basic for Windows and BASIC, the data in a dynamically allocated memory buffer is not directly accessible to your program. You must use the K_MoveBufToArray function to move the data from the dynamically allocated memory buffer to the program’s local array. For Visual Basic for Windows, refer to page 3-27 for more information; for BASIC, refer to page 3-36 for more information.

Use the K_IntAlloc function to dynamically allocate a memory buffer for a synchronous-mode or interrupt-mode operation. You specify the operation requiring the buffer and the number of samples to store in the buffer (maximum of 5,000,000 for interrupt mode or 32,767 for synchronous mode). The driver returns the starting address of the buffer and a unique identiﬁer for the buffer; this identiﬁer is called the memory handle. When the buffer is no longer required, you can free the buffer for another use by specifying this memory handle in the K_IntFree function.

2-8 Available Operations

Notes:

For DOS-based languages, the area used for dynamically allocated memory buffers is referred to as the far heap; for Windows-based languages, this area is referred to as the global heap. These heaps are areas of memory left unoccupied as your application program and other programs run.

For DOS-based languages, the K_IntAlloc function uses the DOS Int 21h function 48h to dynamically allocate far heap memory. For Windows-based languages, the K_IntAlloc function calls the

GlobalAlloc API function to allocate the desired buffer size from the

global heap.

For Windows-based languages, dynamically allocated memory is guaranteed to be ﬁxed and locked in memory.

Assigning the Starting Addresses

After you allocate your buffers or dimension your arrays, you must assign the starting addresses of the arrays or buffers and the number of samples to store in the arrays or buffers. Each supported programming language requires a particular procedure for assigning the starting addresses; refer to the following pages for more information:

C/C++ page 3-13 Visual Basic for Windows page 3-25 BASIC page 3-34

If you are using multiple buffers, use the K_BufListAdd function to add each buffer to the list of multiple buffers associated with each operation and to assign the starting address of each buffer. Use the K_BufListReset function to clear the list of multiple buffers.

Analog Input Operations 2-9

Gains and Ranges

Each channel on a DASCard-1001 or D ASCard-1002 can measure analog input signals in one of four, software-selectable unipolar or bipolar analog input ranges. Each channel on a DASCard-1003 can measure analog input signals in one unipolar or bipolar analog input range. You specify the input range type (unipolar or bipolar) for the card in the conﬁguration ﬁle. Refer to your DASCard-1000 Series User’s Guide for more information. To set the input range type in your application program, use the

K_SetADMode function.

Table 2-2 lists the analog input ranges supported by DASCard-1000 Series cards and the gain and gain code associated with each range. Gain codes are used by the FCD functions to represent the gain.

Table 2-2. Analog Input Ranges

Analog Input Range

Card

DASCard-1001 ±5.0 V 0.0 to +5.0 V 1 0

±0.5 V 0.0 to +0.5 V 10 1 ±50 mV 0 to +50 mV 100 2 ±5 mV 0 to +5 mV 1000 3

DASCard-1002 ±5.0 V 0.0 to +5.0 V 1 0

±2.5 V 0.0 to +2.5 V 2 1 ±1.25 V 0.0 to +1.25 V 4 2 ±0.625 V 0.0 to +0.625 V 8 3

DASCard-1003 ±5.0 V 0.0 to +5.0 V 1 0

Gain

Gain CodeBipolar Unipolar

2-10 Available Operations

Channels

For single-mode operations, you specify the gain code in the K_ADRead function.

For synchronous-mode and interrupt-mode analog input operations, you specify the gain code in the K_SetG or K_SetStartStopG function; the function you use depends on how you specify the channels, as described in the following section.

DASCard-1000 Series cards are software-conﬁgurable for either 16 single-ended analog input channels (numbered 0 through 15) or eight differential analog input channels (numbered 0 through 7).

You specify the input conﬁguration (single-ended or differential) in the conﬁguration ﬁle. Refer to the DASCard-1000 Series User’s Guide for more information. To set the input conﬁguration in your application program, use the K_SetADConﬁg function.

If you require more than the 16 single-ended or eight differential channels, you can use up to 16 EXP-1600 expansion accessories to increase the number of available channels to a maximum of 256.

T o use EXP-1600 e xpansion accessories, the analog input channels on the DASCard-1000 Series card must be conﬁgured as single-ended. You assign expansion accessories to consecutive channels on the card, beginning with channel 0. You can also use the remaining channels on the card. Refer to the DASCard-1000 Series User’s Guide and to the

EXP-800/1600 User’s Guide for more information on using expansion

accessories.

The maximum supported conﬁguration is 16 EXP-1600 expansion accessories. Table 2-3 lists the software (or logical) channels associated with each expansion accessory.

Analog Input Operations 2-11

Table 2-3. Logical Channels

Physical Channel on Card

Software (Logical) Channels

Physical Channel on Card

Software (Logical) Channels

0 0 to 15 8 128 to 143 1 16 to 31 9 144 to 159 2 32 to 47 10 160 to 175 3 48 to 63 11 176 to 191 4 64 to 79 12 192 to 207 5 80 to 95 13 208 to 223 6 96 to 111 14 224 to 239 7 112 to 127 15 240 to 255

Figure 2-1 illustrates the use of three EXP-1600 expansion accessories on a DASCard-1000 Series card conﬁgured for single-ended mode.

EXP-1600 channels 0 to 15

EXP-1600 channels 16 to 31

EXP-1600 channels 32 to 47

DASCard-1000 Series Card

0 1 2 3 . . .

Channels (on the card) 48 to 60

Figure 2-1. Analog Input Channels

2-12 Available Operations

Note: Because of the overhead required to perform interrupt-mode

operations under Windows, it is recommended that you use EXP-1600 expansion accessories in single mode or synchronous mode. The throughput of your DASCard-1000 Series card is reduced when using EXP-1600 expansion accessories.

You can perform an analog input operation on a single channel or on a group of multiple channels. The following sections describe how to specify the channels you are using.

Specifying a Single Channel

You can acquire a single sample or multiple samples from a single analog input channel.

For single-mode analog input operations, you can acquire a single sample from a single analog input channel. Use the K_ADRead function to specify the channel and the gain code.

For synchronous-mode and interrupt-mode analog input operations, you can acquire a single sample or multiple samples from a single analog input channel. Use the K_SetChn function to specify the channel and the K_SetG function to specify the gain code.

Specifying a Group of Consecutive Channels

For synchronous-mode and interrupt-mode analog input operations, you can acquire samples from a group of consecutive channels. Use the K_SetStartStopChn function to specify the ﬁrst and last channels in the group. The channels are sampled in order from ﬁrst to last; the channels are then sampled again until the required number of samples is read.

For example, assume that you have an EXP-1600 expansion accessory attached to channel 0 on a DASCard-1000 Series card conﬁgured for single-ended mode. You specify the start channel as 14, the stop channel as 17, and you want to acquire ﬁve samples. Your program reads data ﬁrst from channels 14 and 15 (on the EXP-1600), then from channels 16 and 17 (physical channels 1 and 2 on the DASCard-1000 Series card), and ﬁnally from channel 14 again.

Analog Input Operations 2-13

You can specify a start channel that is higher than the stop channel. For example, assume that you are not using any expansion accessories, the card uses a differential input conﬁguration, the start channel is 7, the stop channel is 2, and you want to acquire ﬁve samples. Your program reads data ﬁrst from channel 7 then from channels 0, 1, and 2, and ﬁnally from channel 7 again.

Use the K_SetG function to specify the gain code for all the channels in the group. (All channels must use the same gain code.) Use the K_SetStartStopG function to specify the gain code, the start channel, and the stop channel in a single function call.

Refer to Table 2-2 on page 2-10 for a list of the analog input ranges supported by the DASCard-1000 Series and the gain code associated with each range.

Specifying Channels in a Channel-Gain Queue

For synchronous-mode and interrupt-mode analog input operations, you can acquire samples from channels in a software channel-gain queue. In the channel-gain queue, you specify the channels you want to sample, the order in which you want to sample them, and the gain code for each channel.

Note: Because of the overhead required to perform interrupt-mode

operations under Windows, it is recommended that you use channel-gain queues in synchronous mode. The throughput of the DASCard-1000 Series card is reduced when using a channel-gain queue. However, performance is optimized when the channels in the channel-gain queue are sequential and when the gains of all the channels are the same.

You can set up the channels in a channel-gain queue either in consecutive order or in nonconsecutive order. You can also specify the same channel more than once.

The channels are sampled in order from the ﬁrst channel in the queue to the last channel in the queue; the channels in the queue are then sampled again until the speciﬁed number of samples is read.

2-14 Available Operations

Pacer Clocks

Refer to Table 2-2 on page 2-10 for a list of the analog input ranges supported by the DASCard-1000 Series and the gain code associated with each range.

The way that you specify the channels and gains in a channel-gain queue depends on the language you are using. Refer to the following pages for more information:

C/C++ page 3-17 Visual Basic for Windows page 3-31 BASIC page 3-40

After you create the channel-gain queue in your program, use the K_SetChnGAry function to specify the starting address of the channel-gain queue.

For synchronous-mode and interrupt-mode analog input operations, the pacer clock determines the period between conversions. Use the K_SetClk function to specify an internal or an external pacer clock. The internal pacer clock is the default pacer clock.

The internal and external pacer clocks are described in the following sections; refer to the DASCard-1000 Series User’s Guide for more information.

Note: The rate at which the computer can reliably read data from the card

depends on a number of factors, including your computer, the operating system/environment, the number of channels you are using, the gains of the channels, and other software issues.

Analog Input Operations 2-15

Internal Pacer Clock

The internal pacer clock uses a 16-bit counter on the card. The counter is normally in an idle state. When you start the analog input operation (using K_SyncStart or K_IntStart), the counter is loaded with its initial value and begins counting down. When the counter counts down to 0, the ﬁrst conversion is initiated. After the ﬁrst conversion is initiated, the counter is loaded again and the process repeats.

Use the K_SetClkRate function to specify a count value, which represents the number of clock ticks between conversions; each clock tick represents 0.1 period between conversions is 987.6

If you are using a DASCard-1003 or if you are using a single channel on a DASCard-1001 or DASCard-1002, you can specify a count value between 71 and 655,350 (7.1 are using multiple channels on a DASCard-1001 or DASCard-1002, you can specify a count value between 294 and 655,350 (29.4 between conversions).

Use the following formula to determine the number of clock ticks to specify:

µs. For example, if you specify 9,876 clock ticks, the

µs.

µs to 65.54 ms between conversions). If you

µs to 65.54 ms

Number of clock ticks

10 000 000,,

------------------------------------= conversion rate

For example, if you want a conversion rate of 1 ksamples/s, specify 10,000 clock ticks, as shown in the following equation:

10 000 000,,

----------------------------- -10000,= 1 000,

The conversion rate is the rate at which the analog-to-digital converter (ADC) initiates conversions; it does not take into account the number of channels you are using. For example, if you are using ﬁve channels and want a conversion rate of 1 ksamples/second per channel, specify 2,000 clock ticks, as shown in the following equation:

10 000 000,,



----------------------------- -



1 000,

2-16 Available Operations

5÷ 2 000,=

The hardware may not be able to conv ert the analog input channels at the exact rate determined by the number of clock ticks you specify. However, the driver calculates a rate that is as close as possible to the number you specify. To determine the actual number of clock ticks used by the internal pacer clock, use the K_GetClkRate function after you start the analog input operation. Refer to page 4-42 for more information.

External Pacer Clock

You connect an external pacer clock to the XCLK/PI0 line of the DASCard-1000 Series card.

When you start an analog input operation (using K_SyncStart or K_IntStart), conversions are armed. At the next falling edge of the external pacer clock (and at every subsequent falling edge of the external pacer clock), a conversion is initiated.

Note: For the DASCard-1001 and DASCard-1002, the ADC can acquire

samples at a maximum of 34 ksamples/s; for the DASCard-1003, the ADC can acquire samples at a maximum of 140 ksamples/s. If you are using an external pacer clock, make sure that the clock initiates conversions at a rate that the ADC can handle.

Buffering Modes

The buffering mode determines how the driver stores the converted data in the buffer. For interrupt-mode analog input operations, you can specify one of the following buffering modes:

● Single-cycle mode - In single-cycle mode, after the card con v erts the

speciﬁed number of samples and stores them in the buffer, the operation stops automatically. Single-cycle mode is the default buffering mode. To reset the buffering mode to single-cycle, use the K_ClrContRun function.

● Continuous mode - In continuous mode, the card continuously

converts samples and stores them in the buffer until it receives a stop function; any values already stored in the buffer are overwritten. Use the K_SetContRun function to specify continuous buffering mode.

Analog Input Operations 2-17

Triggers

Note: Buffering modes are not meaningful for synchronous-mode

operations, since only single-cycle mode applies.

A trigger is an event that occurs based on a speciﬁed set of conditions. For synchronous-mode and interrupt-mode analog input operations, use the K_SetTrig function to specify one of the following trigger sources:

● Internal trigger - An internal trigger is a software trigger; the trigger

event occurs when you start the analog input operation using K_SyncStart or K_IntStart. Note that a slight delay occurs between the time you start the operation and the time the trigger event occurs. The point at which conversions begin depends on the pacer clock; refer to page 2-15 for more information on the pacer clock. The internal trigger is the default trigger source.

● External trigger - An external trigger is either an analog trigger or a

digital trigger; when you start the analog input operation using K_SyncStart or K_IntStart, the application program waits until a trigger event occurs. The point at which conversions begin depends on the pacer clock; refer to page 2-15 for more information on the pacer clock.

Analog and digital triggers are described in the following sections.

Analog T rigger

An analog trigger event occurs when one of the following conditions is met by the analog input signal on a speciﬁed analog trigger channel:

● The analog input signal rises above a speciﬁed voltage level

(positive-edge trigger).

● The analog input signal falls below a speciﬁed voltage level

(negative-edge trigger).

● The analog input signal is above a speciﬁed voltage level

(positive-level trigger).

● The analog input signal is below a speciﬁed voltage level

(negative-level trigger).

2-18 Available Operations

Figure 2-2 illustrates these analog trigger conditions, where the speciﬁed voltage level is +2.5 V.

Positive-level trigger occurs

Level + 2.5 V

0 V

Negative-edge or negative-level trigger occurs

Analog input operation start function is executed

Positive-edge trigger occurs

Figure 2-2. Analog Trigger Conditions

Use the K_SetADTrig function to specify the following:

● Analog input channel to use as the trigger channel - The trigger

channel always measures signals at a gain of 1.

● Voltage level - You specify the voltage level as a count value. For a

bipolar input range type, you specify a count value between and 2047, where

−2048 represents −5 V and 2047 represents 5 V; for a

−2048

unipolar input range type, you specify a count value between 0 and 4095, where 0 represents 0 V and 4095 represents 5 V. Refer to Appendix B for information on how to convert a voltage value to a count value.

● Trigger polarity and sensitivity - The trigger can be a positive-edge,

negative-edge, positive-level, or negative-level trigger.

Analog Input Operations 2-19

For positive-edge and ne gati ve-edge triggers, you can specify a hysteresis value to prevent noise from triggering an operation. Use the K_SetTrigHyst function to specify the hysteresis value. The point at which the trigger event occurs is described as follows:

● Positiv e-edge trigger - The analog signal must be below the speciﬁed

voltage level by at least the amount of the hysteresis value and then rise above the voltage level before the trigger event occurs.

● Negative-edge trigger - The analog signal must be above the

speciﬁed voltage level by at least the amount of the hysteresis value and then fall below the voltage level before the trigger event occurs.

The hysteresis value is an absolute number, which you specify as a count value. For a bipolar input range type, you specify a count v alue between 0 and 2047, where 0 represents 0 V and 2047 represents 5 V; for a unipolar input range type, you specify a count value between 0 and 4095, where 0 represents 0 V and 4095 represents 5 V. When you add the hysteresis value to the voltage level (for a negative-edge trigger) or subtract the hysteresis value from the voltage level (for a positive-edge trigger), the resulting value must also be between 0 and 2047 for a bipolar input range type or between 0 and 4095 for a unipolar input range type.

For example, assume that you are using a negative-edge trigger on a channel conﬁgured for an analog input range of 0 to 5 V. If the voltage level is +4.8 V (3932 counts), you can specify a hysteresis value of 0.1 V (82 counts) because 3932 + 82 is less than 4095, but you cannot specify a hysteresis value of 0.3 V (246 counts) because 3932 + 246 is greater than

4095. Refer to Appendix B for information on how to convert a voltage value to a count value.

In Figure 2-3, the speciﬁed voltage level is +4 V and the hysteresis value is 0.1 V. The analog signal must be below +3.9 V and then rise above +4 V before a positive-edge trigger event occurs, the analog signal must be above +4.1 V and then fall below +4 V before a negative-edge trigger event occurs.

2-20 Available Operations

Level +4 V

+3.9 V

+4.1 V

Level +4 V

Positive-edge trigger occurs

Hysteresis = 0.1 V

Negative-edge trigger occurs

Analog input operation start function is executed

Figure 2-3. Using a Hysteresis Value

Note: The analog trigger is a software-based trigger. When you start the

analog input operation (using K_IntStart or K_SyncStart), the driver samples the speciﬁed trigger channel until the trigger condition is met. If you are performing an operation in interrupt mode, control does not return to your application program until the trigger condition is met. (To terminate the operation if a trigger event does not occur, press Ctrl + Break.) In addition, a slight time delay occurs between the time the trigger condition is met and the time the driver realizes the trigger condition is met and begins conversions.

Analog Input Operations 2-21

Digital T rigger

A digital trigger event occurs when a negative edge is detected on the digital trigger signal connected to the XTRIG/PI1 line of the DASCard-1000 Series card.

Use the K_SetDITrig function to specify a digital trigger.

Data Correction

For synchronous-mode and interrupt-mode analog input operations, the data acquired by the card must be corrected to ensure that the data stored in the user-deﬁned buffer is valid. The data is corrected using the calibration factors that are stored in computer memory for each analog input range.

The analog input data can be corrected in one of the following ways:

● Automatic correction of data - If speed is not an issue and you are

programming under Windows, the driver can automatically correct data as it is acquired. The driver stores the corrected data in the user-deﬁned buffer. By default, automatic data correction is enabled.

● Correction of data by the driver after the operation is complete -

If you cannot acquire data fast enough using automatic data correction and you are programming under Windows, the driver can store uncorrected data in the user-deﬁned buffer and then correct the data after the operation is complete. Use the K_SetCalMode function to disable automatic data correction, and then use the K_CorrectData function to correct the data at an appropriate point in your program. The driver overwrites the uncorrected data in the user-deﬁned buffer with the corrected data.

● Correction of data by the application program after the

operation is complete - If you are programming under Windows and want more control over the correction of your data, the driver can store uncorrected data in the user-deﬁned buffer and the application program can correct the data after the operation is complete. If you are programming under DOS, the driver always stores uncorrected data in the user-deﬁned buffer and the application program must correct the data after the operation is complete.

2-22 Available Operations

The application program corrects the data by performing the following steps:

1. If you are programming under W indo ws, use the K_SetCalMode

function to disable automatic data correction.

2. Use the K_GetCalData function to return the calibration factors

for a speciﬁed analog input range to a two-element array; the ﬁrst calibration factor in the array is the gain to apply to the uncorrected data and the second calibration factor in the array is the offset. Note that the gain value returned represents a gain, not a gain code. Refer to page 4-39 for more information about K_GetCalData.

3. Since dealing with ﬂoating point numbers is language-dependent

in DOS, if you are programming under DOS, K_GetCalData returns the gain value as a twos complement integer between

−127 and +127. Use the following formula to calculate the actual

gain to apply to the uncorrected data:

actual gain 1.0 gain returned by K_GetCalData 0.001×()+=

If you are programming under Windows, the gain returned by K_GetCalData is the actual gain, which is returned as a ﬂoating point number; go to step 4.

4. Use one of the following formulas to correct a data value:

For a bipolar input range type:

corrected data gain uncorrected data×()offset+=

For a unipolar input range type:

corrected data gain uncorrected data 2048–()×()offset 2048++=

If you are programming under DOS, the gain used in the formula is the gain value calculated in step 3. If you are programming under Windows, the gain used in the formula is the gain value returned by K_GetCalData.

The offset value is alw ays the offset returned by K_GetCalData.

Analog Input Operations 2-23

Notes: For automatic correction of data and correction of data by the

driver after the operation is complete, you must be programming under Windows. If you are programming under DOS, the application program must correct data after the operation is complete. When programming under DOS, it is not necessary to use K_SetCalMode to disable automatic data correction.

If you are programming under Windows and using K_ADRead to perform a single-mode analog input operation, data is automatically corrected before it is stored in the variable. If you are programming under DOS and using K_ADRead, uncorrected data is stored in the variable and the application program must correct the data.

It is recommended that you periodically update the calibration factors stored in computer memory using the CAL1000.EXE utility. Refer to the DASCard-1000 Series User’s Guide for more information.

Each supported language uses a different procedure for correcting data; refer to the following pages for more information:

C/C++ page 3-19 Visual Basic for Windows page 3-32 BASIC page 3-41

You can convert the corrected count values to v oltage, if desired. Refer to Appendix B for more information.

Digital I/O Operations

DASCard-1000 Series cards contain four digital input lines (XCLK/PI0, XTRIG/PI1, PI2, and PI3) and eight digital output lines (PO0 through PO7). If you are not using the digital I/O lines to support an analog input operation, you can use them for general-purpose digital I/O, as described in the following sections.

2-24 Available Operations

Digital Input

You can perform a digital input operation in single mode only. Use the K_DIRead function to read the value of digital input channel 0, which contains all the digital input lines. You specify the card you want to use, the digital input channel, and the variable in which to store the value. Only bits 0, 1, 2, and 3 of the digital input value are meaningful. Figure 2-4 shows how the digital input bits correspond to the digital input lines.

bit 7 bit 6 bit 5 bit 4 bit 3 bit 2 bit 1 bit 0

PI3 PI2 XTRIG/

PI1

Figure 2-4. Digital Input Bits

XCLK/ PI0

A value of 1 in the bit position indicates that the input is high; a value of 0 in the bit position indicates that the input is low. For example, if the value is 5 (00000101), the input at XCLK/PI0 and PI2 is high and the input at XTRIG/PI1 and PI3 is low.

If you are using an external pacer clock, you cannot use XCLK/PI0 for general-purpose digital input operations. If you are using an external digital trigger, you cannot use XTRIG/PI1 for general-purpose digital input operations.

If no signal is connected to a digital input line, the input appears high (value is 1).

Digital I/O Operations 2-25

Digital Output

You can perform a digital output operation in single mode only. Use the K_DOWrite function to write a value to digital output channel 0, which contains all the digital output lines. Y ou specify the card you want to use, the digital output channel, and the digital output value. Figure 2-5 shows how the digital output bits correspond to the digital output lines.

bit 7 bit 6 bit 5 bit 4 bit 3 bit 2 bit 1 bit 0

PO0PO1PO2PO3PO4PO5PO6PO7

Figure 2-5. Digital Output Bits

A value of 1 in the bit position indicates that the output is high; a value of 0 in the bit position indicates that the output is low. For example, if the value written is 12 (00001100), the output at PO2 and PO3 is forced high, while the output of all other lines is forced low.

If you are using an EXP-1600 expansion accessory for an analog input operation, the driver uses four digital output lines (P0 to P3) to specify the expansion accessory channel that is acquiring data; in this case, you cannot use these digital output lines for general-purpose digital output operations while acquiring analog input data.

2-26 Available Operations

Programming with the

Function Call Driver

This chapter contains an overview of the structure of the Function Call Driver, as well as programming guidelines and language-speciﬁc information to assist you when writing application programs with the Function Call Driver.

How the Driver Works

When writing application programs, you can use functions from one or more Keithley MetraByte DAS Function Call Drivers. You initialize each driver using a particular conﬁguration ﬁle. If you are using more than one driver or more than one conﬁguration ﬁle with a single driver, the driver handle uniquely identiﬁes each driver or each use of the driver.

You can program one or more Keithley MetraByte DAS cards or boards in your application program. You initialize each card or board using a device handle that uniquely identiﬁes it. Each device handle is associated with a particular driver.

The Function Call Driver allo ws you to perform I/O operations in v arious operation modes. For single mode, the I/O operation is performed with a single call to a function; the attributes of the I/O operation are speciﬁed as arguments to the function. Figure 3-1 illustrates the syntax of the single-mode, analog input operation function K_ADRead .

How the Driver Works 3-1

Single-Mode Function

K_ADRead (card,

channel,

gain,

buffer)

Figure 3-1. Single-Mode Function

Attributes of Operation

Card number

Analog input channel

Gain applied to channel

Buffer for data

For other operation modes, such as synchronous and interrupt mode, the driver uses frames to perform the operation. A frame is a data structure whose elements deﬁne the attributes of the operation. Each frame is associated with a particular card or board, and therefore, to a particular driver.

Frames help you create structured application programs. You set up the attributes of the operation in advance, using a separate function call for each attribute, and then start the operation at an appropriate point in your program.

Frames are useful for operations that have many deﬁning attrib utes, since providing a separate argument for each attribute could make a function’s argument list unmanageably long. In addition, some attributes, such as the clock source and trigger source, are available only for operations that use frames.

You indicate that you want to perform an operation by getting an available frame for the dri ver. The driver returns a unique identiﬁer for the frame; this identiﬁer is called the frame handle. You then specify the attributes of the operation by using setup functions to deﬁne the elements of the frame associated with the operation. For example, to specify the channel on which to perform an operation, you might use the K_SetChn setup function.

You use the frame handle you speciﬁed when accessing the frame in all setup functions and other functions related to the operation. This ensures that you are deﬁning the same operation.

3-2 Programming with the Function Call Driver

When you are ready to perform the operation you have set up, you can start the operation in the appropriate operation mode, referencing the appropriate frame handle. Figure 3-2 illustrates the syntax of the interrupt-mode operation function K_IntStart .

K_IntStart (

Start Channel

Stop Channel

Clock Source

Trigger Source . .

Frame

frameHandle

)

Attributes of Operation

First analog input channel

Last analog input channel

Pacer clock source

Trigger source . .

Figure 3-2. Interrupt-Mode Operation

For DASCard-1000 Series cards, synchronous-mode and interrupt-mode analog input operations require frames, called A/D (analog-to-digital) frames. Use the K_GetADFrame function to access an available A/D frame.

If you want to perform a synchronous-mode or interrupt-mode analog input operation and all A/D frames have been accessed, you can use the

K_FreeFrame function to free a frame that is no longer in use. You can

then redeﬁne the elements of the frame for the next operation.

When you access a frame, the elements are set to their default values. You can also use the K_ClearFrame function to reset all the elements of a frame to their default values.

How the Driver Works 3-3

Table 3-1 lists the elements of an A/D frame for DASCard-1000 Series cards. This table also lists the default value of each element and the setup functions used to deﬁne each element.

Table 3-1. A/D Frame Elements

Element Default Value Setup Function

Buffer

Number of Samples 0 K_SetBuf

0 (NULL) K_SetBuf

K_SetBufI K_BufListAdd

Buffering Mode Single-cycle K_SetContRun

K_ClrContRun

Start Channel 0 K_SetChn

K_SetStartStopChn K_SetStartStopG

Stop Channel 0 K_SetStartStopChn

K_SetStartStopG

Gain 0 (gain of 1) K_SetG

K_SetStartStopG

Channel-Gain

0 (NULL) K_SetChnGAry

Queue Clock Source Internal K_SetClk Pacer Clock Rate 0 K_SetClkRate Trigger Source Internal K_SetTrig Trigger Type Digital K_SetADTrig

K_SetDITrig

Trigger Channel 0 (for analog trigger) K_SetADTrig

0 (for digital trigger) Not applicable

Trigger Polarity Positive edge (for

K_SetADTrig

analog trigger) Positive edge (for

Not applicable

digital trigger)

3-4 Programming with the Function Call Driver

Table 3-1. A/D Frame Elements (cont.)

Element Default Value Setup Function

Trigger Level 0 K_SetADTrig Trigger Hysteresis 0 K_SetTrigHyst Calibration Mode

Notes

You must set this element.

Use this function to reset the value of this particular frame element to its

default setting without clearing the frame or getting a new frame. Whenever you clear a frame or get a new frame, this frame element is set to its default value automatically.

Since only negative-edge digital triggers are supported by the hardware,

the value of this element is ignored.

This element is valid only when programming under Windows.

Enabled K_SetCalMode

Note:

The DASCard-1000 Series Function Call Driver provides many other functions that are not related to controlling frames, deﬁning the elements of frames, or reading the values of frame elements. These functions include single-mode operation functions, initialization functions, memory management functions, data correction functions, and miscellaneous functions.

For information about using the FCD functions in your application program, refer to the following sections of this chapter. For detailed information about the syntax of FCD functions, refer to Chapter 4.

How the Driver Works 3-5

Programming Overview

To write an application program using the DASCard-1000 Series Function Call Driver, perform the following steps:

1. Deﬁne the application's requirements. Refer to Chapter 2 for a

description of the operations supported by the Function Call Driver and the functions that you can use to deﬁne each operation.

2. Write your application program. Refer to the following for additional

information: – Preliminary Tasks, the next section, which describes the

programming tasks that are common to all application programs.

– Analog Input Programming Tasks on page 3-7 and Digital I/O

Programming Tasks on page 3-12, which describe operation-speciﬁc programming tasks and the sequence in which these tasks must be performed.

– Chapter 4, which contains detailed descriptions of the FCD

functions.

– The example programs in the DASCard-1000 Series standard

software package and the ASO-1000 software package. The FILES.TXT ﬁle in the installation directory lists and describes the example programs.

3. Compile and link the program. Refer to the following for information

on compile and link statements and other language-specific considerations:

– C/C++ Programming Information on page 3-13. – Visual Basic for Windows Programming Information on

page 3-25. – BASIC Programming Information on page 3-34. – The EXAMPLES.TXT ﬁle located in the installation directory.

3-6 Programming with the Function Call Driver

Preliminary T asks

For every Function Call Driver application program, you must perform the following preliminary tasks:

1. Include the function and variable type deﬁnition ﬁle for your language. Depending on the speciﬁc language you are using, this ﬁle is included in the DASCard-1000 Series standard software package or the ASO-1000 software package.

2. Declare and initialize program variables.

3. Use a driver initialization function ( K_OpenDriver or

DAS1000_DevOpen ) to initialize the driver.

4. Use a card initialization function ( K_GetDevHandle or

DAS1000_GetDevHandle ) to specify DASCard-1000 Series card

you want to use and to initialize the card. If you are using two cards, use the initialization function twice.

After completing the preliminary tasks, perform the appropriate operation-speciﬁc programming tasks. The operation-speciﬁc tasks for analog input and digital I/O operations are described in the following sections.

Analog Input Programming Tasks

The following sections describe the operation-speciﬁc programming tasks required to perform single-mode, synchronous-mode, and interrupt-mode analog input operations.

Single-Mode Operations

For a single-mode analog input operation, perform the following tasks:

1. Declare the buffer or v ariable in which to store the single analog input value.

2. Use the K_ADRead function to read the single analog input value; specify the attributes of the operation as arguments to the function.

Preliminary Tasks 3-7

Synchronous-Mode Operations

For a synchronous-mode analog input operation, perform the following tasks:

1. Use the K_GetADFrame function to access an A/D frame.

2. Allocate the buffer or dimension the array in which to store the acquired data. Use the K_IntAlloc function if you want to allocate the buffer dynamically outside your program's memory area.

3. If you want to use a channel-gain queue to specify the channels

acquiring data , deﬁne and assign the appropriate values to the queue

and note the starting address. Refer to page 2-14 for more information about channel-gain queues.

4. Use the appropriate setup functions to specify the attributes of the operation. The setup functions are listed in Table 3-2 on page 3-8.

Note:

When you access a new A/D frame, the frame elements contain default values. If the default value of a particular element is suitable for your operation, you do not have to use the setup function associated with that element. Refer to Table 3-1 on page 3-4 for a list of the default values of A/D frame elements.

Table 3-2. Setup Functions for Synchronous-Mode

Analog Input Operations

Attribute Setup Functions

Buffer K_SetBuf

K_SetBufI

Number of Samples K_SetBuf

K_SetBufI

Start Channel K_SetChn

K_SetStartStopChn K_SetStartStopG

Stop Channel K_SetStartStopChn

K_SetStartStopG

3-8 Programming with the Function Call Driver

Table 3-2. Setup Functions for Synchronous-Mode

Analog Input Operations (cont.)

Attribute Setup Functions

Gain K_SetG

K_SetStartStopG Channel-Gain Queue K_SetChnGAry Clock Source K_SetClk Pacer Clock Rate K_SetClkRate Trigger Source K_SetTrig Trigger Type K_SetADTrig

K_SetDITrig Trigger Channel K_SetADTrig Trigger Polarity K_SetADTrig

K_SetDITrig Trigger Level K_SetADTrig Trigger Hysteresis K_SetTrigHyst Calibration Mode K_SetCalMode

Refer to Chapter 2 for background information about the setup functions; refer to Chapter 4 for detailed descriptions of the setup functions.

5. Use the K_SyncStart function to start the synchronous-mode operation.

6. If you are programming in Visual Basic for Windows or BASIC and

you used K_IntAlloc to allocate your buffer , use the

K_MoveBufToArray function to transfer the acquired data from the

allocated buffer to the program’s local array.

7. If you are programming in C/C++ for DOS or BASIC , use the

K_GetCalData function to get the calibration factors, and then

correct the data. Refer to page 2-22 for more information.

Analog Input Programming Tasks 3-9

If you used K_IntAlloc to allocate your buffer , use the K_IntFree

function to deallocate the buffer.

9. Use the K_FreeFrame function to return the frame you accessed in step 1 to the pool of available frames.

Interrupt-Mode Operations

For an interrupt-mode analog input operation, perform the following tasks:

1. Use the K_GetADFrame function to access an A/D frame.

2. Allocate the buffers or dimension the arrays in which to store the acquired data. Use the K_IntAlloc function if you want to allocate buffers dynamically outside your program's memory area.

3. If you want to use a channel-gain queue to specify the channels

acquiring data , deﬁne and assign the appropriate values to the queue

and note the starting address. Refer to page 2-14 for more information about channel-gain queues.

4. Use the appropriate setup functions to specify the attributes of the operation. The setup functions are listed in Table 3-3.

Note:

contain default values. If the default value of a particular element is suitable for your operation, you do not have to use the setup function associated with that element. Refer to Table 3-1 on page 3-4 for a list of the default values of A/D frame elements.

When you access a new A/D frame, the frame elements

3-10 Programming with the Function Call Driver

Table 3-3. Setup Functions for Interrupt-Mode

Analog Input Operations

Attribute Setup Functions

Buffer K_SetBuf

K_SetBufI K_BufListAdd

Number of Samples K_SetBuf

K_SetBufI K_BufListAdd

Buffering Mode K_SetContRun

K_ClrContRun

Start Channel K_SetChn

K_SetStartStopChn K_SetStartStopG

Stop Channel K_SetStartStopChn

K_SetStartStopG

Gain K_SetG

K_SetStartStopG Channel-Gain Queue K_SetChnGAry Clock Source K_SetClk Pacer Clock Rate K_SetClkRate Trigger Source K_SetTrig Trigger Type K_SetADTrig

K_SetDITrig Trigger Channel K_SetADTrig Trigger Polarity K_SetADTrig

K_SetDITrig Trigger Level K_SetADTrig Trigger Hysteresis K_SetTrigHyst Calibration Mode K_SetCalMode

Analog Input Programming Tasks 3-11

Refer to Chapter 2 for background information about the setup functions; refer to Chapter 4 for detailed descriptions of the setup functions.

5. Use the K_IntStart function to start the interrupt-mode operation.

6. Use the K_IntStatus function to monitor the status of the interrupt-mode operation.

7. If you speciﬁed continuous buffering mode , use the K_IntStop function to stop the interrupt-mode operation when the appropriate number of samples has been acquired.

8. If you are programming in Visual Basic for Windows or BASIC and

you used K_IntAlloc to allocate your buffer , use the

K_MoveBufToArray function to transfer the acquired data from the

allocated buffer to the program’s local array.

9. If you are programming in C/C++ for DOS or BASIC , use the

K_GetCalData function to get the calibration factors, and then

correct the data. Refer to page 2-22 for more information.

10. If you used K_IntAlloc to allocate your buffer , use the K_IntFree function to deallocate the buffer.

11. If you used K_BufListAdd to specify a list of multiple buffers , use the

K_BufListReset function to clear the list.

12. Use the K_FreeFrame function to return the frame you accessed in step 1 to the pool of available frames.

Digital I/O Programming Tasks

For a single-mode digital I/O operation, perform the following tasks:

1. Declare the buffer or variable in which to store the single digital I/O value.

2. Use one of the following digital I/O single-mode operation functions, specifying the attributes of the operation as arguments to the function:

Function Purpose

K_DIRead Reads a single digital input value. K_DOWrite Writes a single digital output value.

3-12 Programming with the Function Call Driver

C/C++ Programming Information

The following sections contain information you need to allocate and assign memory buffers, to create channel-gain queues, and to handle errors in C or C++, as well as other language-speciﬁc information for Microsoft C/C++ and Borland C/C++.

Notes:

type-mismatch warnings.

Make sure that linker options are set so that case-sensitivity is disabled.

Make sure that you use proper typecasting to prevent C/C++

Dynamically Allocating and Assigning Memory Buffers

This section provides code fragments that describe how to allocate and assign dynamically allocated memory buffers when programming in C or C++. Refer to the example programs on disk for more information.

Note:

programming in Windows Enhanced mode, you may be limited in the amount of memory you can allocate. It is recommended that you install the Keithley Memory Manager before you begin programming to ensure that you can allocate a large enough buffer or buffers. Refer to the

DASCard-1000 Series User’s Guide for more information about the

Keithley Memory Manager.

If you are using large or multiple memory buffers and you are

Allocating a Single Memory Buffer

You can use a single, dynamically allocated memory buffer for synchronous-mode and interrupt-mode analog input operations.

The following code fragment illustrates how to use K_IntAlloc to allocate a buffer of size Samples for the frame deﬁned by hFrame and how to use K_SetBuf to assign the starting address of the buffer.

C/C++ Programming Information 3-13

. . . void far *AcqBuf; //Declare pointer to buffer WORD hMem; //Declare word for memory handle . . . wDasErr = K_IntAlloc (hFrame, Samples, &AcqBuf, &hMem); wDasErr = K_SetBuf (hFrame, AcqBuf, Samples); . . .

The following code illustrates how to use K_IntFree to later free the allocated buffer, using the memory handle stored by K_IntAlloc.

. . . wDasErr = K_IntFree (hMem); . . .

Allocating Multiple Memory Buffers

You can use multiple, dynamically allocated memory buffers for interrupt-mode analog input operations.

The following code fragment illustrates how to use K_IntAlloc to allocate ﬁve buffers of size Samples each for the frame deﬁned by hADFrame and how to use K_BufListAdd to assign the starting addresses of the ﬁve buffers.

. . . void far *AcqBuf[5]; //Declare 5 pointers to 5 buffers WORD hMem[5]; //Declare 5 words for 5 memory handles . . . for (i = 0; i < 5; i++) { wDasErr = K_IntAlloc (hADFrame, Samples, &AcqBuf[i],&hMem[i]); wDasErr = K_BufListAdd (hADFrame, AcqBuf[i], Samples); } . . .

3-14 Programming with the Function Call Driver

The following code illustrates how to use K_IntFree to later free the allocated buffers, using the memory handles stored by K_IntAlloc. If you free the allocated buffers, you must also use K_BufListReset to reset the buffer list associated with the frame.

Accessing the Data

You access the data stored in dynamically allocated buffers through C/C++ pointer indirection. For example, assume that you want to display the ﬁrst 10 samples of the second buffer in the multiple-buffer operation described in the previous section (AcqBuf [1]). The following code fragment illustrates how to access and display the data.

int huge *pData; //Declare a pointer called pData . . . pData = (int huge*) AcqBuf[1]; //Assign pData to 2nd buffer for (i = 0; i < 10; i++)

printf ("Sample #%d %X", i, *(pData+i));

. . .

. . . for (i = 0; i < 5; i++) {

wDasErr = K_IntFree (hMem[i]); } wDasErr = K_BufListReset (hADFrame); . . .

Note: Declaring pData as a huge pointer allows the program to directly

access all data in the buffer, regardless of the buffer size.

Dimensioning and Assigning Local Arrays

This section provides code fragments that describe how to dimension and assign local arrays when programming in C or C++. Refer to the example programs on disk for more information.

C/C++ Programming Information 3-15

Dimensioning a Single Array

You can use a single, local array for synchronous-mode and interrupt-mode analog input operations.

The following code fragment illustrates how to dimension an array of 10,000 samples for the frame deﬁned by hFrame and how to use K_SetBuf to assign the starting address of the array.

. . . int Data[10000]; //Dimension array of 10,000 samples . . . wDasErr = K_SetBuf (hFrame, Data, 10000); . . .

Dimensioning Multiple Arrays

You can use multiple, local arrays for interrupt-mode analog input operations.

The following code fragment illustrates how to allocate two arrays of 32,000 samples each for the frame deﬁned by hADFrame and how to use K_BufListAdd to assign the starting addresses of the arrays.

. . . int Data1[32000]; //Allocate Array #1 of 32,000 samples int Data2[32000]; //Allocate Array #2 of 32,000 samples . . . wDasErr = K_BufListAdd (hADFrame, Data1, 32000); wDasErr = K_BufListAdd (hADFrame, Data2, 32000);

3-16 Programming with the Function Call Driver

Creating a Channel-Gain Queue

The DASDECL.H and DASDECL.HPP ﬁles deﬁne a special data type (GainChanTable) that you can use to declare your channel-gain queue. GainChanTable is deﬁned as follows:

typedef struct GainChanTable {

WORD num_of_codes; struct{

char Chan;

char Gain; } GainChanAry[256];

} GainChanTable;

The following example illustrates how to create a channel-gain queue called MyChanGainQueue for a DASCard-1002 card by declaring and initializing a variable of type GainChanTable:

GainChanTable MyChanGainQueue =

{8, //Number of entries 0, 0, //Channel 0, gain of 1 1, 1, //Channel 1, gain of 2 2, 2, //Channel 2, gain of 4 3, 3, //Channel 3, gain of 8 3, 0, //Channel 3, gain of 1 2, 1, //Channel 2, gain of 2 1, 2, //Channel 1, gain of 4 0, 3}; //Channel 0, gain of 8

After you create MyChanGainQueue, you must assign the starting address of MyChanGainQueue to the frame deﬁned by hFrame, as follows:

wDasErr = K_SetChnGAry (hFrame, &MyChanGainQueue);

When you start the next analog input operation (using K_SyncStart or K_IntStart), channel 0 is sampled at a gain of 1, channel 1 is sampled at

a gain of 2, channel 2 is sampled at a gain of 4, and so on.

C/C++ Programming Information 3-17

Correcting Data (for DOS)

If you are using C/C++ for DOS, the application program must correct the data after the operation is complete. The following code fragment illustrates how to correct the data and how to convert the corrected data to volts.

void far *pIntBuf; /* Pointer to allocated buffer */ WORD hMem; /* Allocated memory handle */ int far *pData; /* Temporary pointer to data */ int nCounts;

int nCalData[2]; /* Contains calibration values */ float fGainVal; int nOffsetVal; . . . /* Data pointed to by pIntBuf */ wDasErr = K_IntAlloc (hAD, dwSamples, &pIntBuf, &hMem); . . . wDasErr = K_IntStart (hAD); . . . /* Gets gain and offset values */ wDasErr = K_GetCalData (hAD, 0, 0, NULL, nCalData); . . . /* Determines the actual gain to apply to the data */ fGainVal = (float) (1.0 + (float) nCalData[0] * 0.001); nOffsetVal = nCalData[1]; . . . /* Corrects the data and converts counts to volts; assumes that */ /* you are using a bipolar +/-5 V analog input range */ pData = (int far *) pIntBuf; /* Pointer to 1st sample in buffer */ nCounts= (int) ((float)*pData * fGainVal) + nOffsetVal; /*Corrects*/ fVolts = (float) nCounts * (10.0 / 4096.0); /*Converts*/ printf (“Sample = %x counts, %.3f volts\n”, *pData, fVolts);

3-18 Programming with the Function Call Driver

Correcting Data (for Windows)

If you are using C/C++ for Windows and have disabled automatic data correction, the application program must correct the data after the operation is complete. The following code fragment illustrates how to correct the data and how to convert the corrected data to volts.

void far *pIntBuf; /* Pointer to allocated buffer */ WORD hMem; /* Allocated memory handle */ int far *pData; /* Temporary pointer to data */ int nCounts;

float fCalData[2]; /* Contains calibration values */ float fGainVal; float fOffsetVal; . . . /* Data pointed to by pIntBuf */ wDasErr = K_IntAlloc (hAD, dwSamples, &pIntBuf, &hMem); . . . wDasErr = K_SetCalMode (hAD, 0); /* Disables correction by driver */ . . . wDasErr = K_IntStart (hAD); . . . /* Gets gain and offset values */ wDasErr = K_GetCalData (hAD, 0, 0, NULL, fCalData); fGainVal = fCalData[0]; fOffsetVal = fCalData[1]; . . . /* Corrects the data and converts counts to volts; assumes that */ /* you are using a bipolar +/-5 V analog input range */ pData = (int far *) pIntBuf; /* Pointer to 1st sample in buffer */ nCounts= (int) ((float)*pData * fGainVal) + fOffsetVal; /*Corrects*/ fVolts = (float) nCounts * (10.0 / 4096.0); /*Converts*/ printf (“Sample = %x counts, %.3f volts\n”, *pData, fVolts);

C/C++ Programming Information 3-19

Handling Errors

It is recommended that you always check the returned value (wDasErr in the previous examples) for possible errors. The following code fragment illustrates how to check the returned value of the K_GetDevHandle function.

. . . if ((wDasErr = K_GetDevHandle (hDrv, BoardNum, &hDev)) ! = 0)

{ printf (“Error %X during K_GetDevHandle”, wDasErr); exit (1); }

The following code fragment illustrates how to use the K_GetErrMsg function to access the string corresponding to an error code.

. . . if ((wDasErr = K_SetChn (hAD, 2) ! = 0)

{ Error = K_GetErrMsg (hDev, wDasErr, &pMessage); printf (“%s”, pMessage); exit (1); }

Programming in Microsoft C/C++ (for DOS)

To program in Microsoft C/C++ (for DOS), you need the following ﬁles; these ﬁles are provided in the ASO-1000 software package.

File Description

DAS1000.LIB Linkable driver DASRFACE.LIB Linkable driver DASDECL.H Include ﬁle when compiling in C (.c programs) DAS1000.H Include ﬁle when compiling in C (.c programs) DASDECL.HPP Include ﬁle when compiling in C++ (.cpp programs) DAS1000.HPP Include ﬁle when compiling in C++ (.cpp programs) USE1000.OBJ Linkable object

3-20 Programming with the Function Call Driver

To create an executable ﬁle in Microsoft C/C++ (for DOS), use the following compile and link statements. Note that ﬁlename indicates the name of your application program.

Type of Compile Compile and Link Statements

C CL /c ﬁlename.c

LINK ﬁlename+use1000.obj,,,das1000+dasrface;

C++ CL /c ﬁlename.cpp

LINK ﬁlename+use1000.obj,,,das1000+dasrface;

Programming in Microsoft C/C++ (for Windows)

To program in Microsoft C/C++ (for Windows), including Microsoft Visual C++, you need the following ﬁles; these ﬁles are provided in the ASO-1000 software package.

File Description

DASSHELL.DLL Dynamic Link Library DASSUPRT.DLL Dynamic Link Library DAS1000.DLL Dynamic Link Library DASDECL.H Include ﬁle when compiling in C (.c programs) DAS1000.H Include ﬁle when compiling in C (.c programs) DASDECL.HPP Include ﬁle when compiling in C++ (.cpp programs) DAS1000.HPP Include ﬁle when compiling in C++ (.cpp programs) DASIMP.LIB DAS Shell Imports D1000IMP.LIB DASCard-1000 Imports

C/C++ Programming Information 3-21

To create an executable ﬁle in Microsoft C/C++ (for Windows), use the following compile and link statements. Note that ﬁlename indicates the name of your application program.

Type of Compile Compile and Link Statements

C CL /c ﬁlename.c

LINK ﬁlename,,,d1000imp+dasimp,ﬁlename.def; RC −r ﬁlename.rc RC −30 ﬁlename.res

C++ CL /c ﬁlename.cpp

LINK ﬁlename,,,d1000imp+dasimp,ﬁlename.def; RC −r ﬁlename.rc RC −30 ﬁlename.res

To create an executable ﬁle in the Microsoft C/C++ (for Windows) environment, perform the following steps:

1. Create a project ﬁle by choosing New from the Project menu.

2. Add all necessary ﬁles to the project make ﬁle by choosing Edit from the Project menu. Make sure that you include ﬁlename.c (or ﬁlename.cpp), ﬁlename.rc, ﬁlename.def, DASIMP.LIB, and D1000IMP.LIB, where ﬁlename indicates the name of your application program.

3. From the Project menu, choose Rebuild All FILENAME.EXE to create a stand-alone executable ﬁle (.EXE) that you can execute from within Windo ws.

3-22 Programming with the Function Call Driver

Programming in Borland C/C++ (for DOS)

To program in Borland C/C++ (for DOS), you need the following ﬁles; these ﬁles are provided in the ASO-1000 software package.

File Description

To create an executable ﬁle in Borland C/C++ (for DOS), use the following compile and link statements. Note that ﬁlename indicates the name of your application program.

Type of Compile Compile and Link Statements

C BCC -ml ﬁlename.c use1000.obj das1000.lib dasrface.lib C++ BCC -ml ﬁlename.cpp use1000.obj das1000.lib dasrface.lib

Notes

These statements assume a large memory model; however, any memory

model is acceptable.

C/C++ Programming Information 3-23

Programming in Borland C/C++ (for Windows)

To program in Borland C/C++ (for Windows), you need the following ﬁles; these ﬁles are provided in the ASO-1000 software package.

File Description

To create an executable ﬁle in Borland C/C++ (for Windows), use the following compile and link statements. Note that ﬁlename indicates the name of your application program.

Type of Compile Compile and Link Statements

C BCC -c ﬁlename.c

TLINK ﬁlename,,,d1000imp+dasimp, ﬁlename.def; BRC -r ﬁlename.rc BRC -30 ﬁlename.res

C++ BCC -c ﬁlename.cpp

TLINK ﬁlename,,,d1000imp+dasimp, ﬁlename.def; BRC -r ﬁlename.rc BRC -30 ﬁlename.res

3-24 Programming with the Function Call Driver

To create an executable ﬁle in the Borland C/C++ (for Windows) environment, perform the following steps:

1. Create a project ﬁle by choosing New from the Project menu.

2. Inside the Project window, select the project name and click on the right mouse button.

3. Select the Add node option and add all necessary ﬁles to the project make ﬁle. Make sure that you include ﬁlename.c (or ﬁlename.cpp),

ﬁlename.rc, ﬁlename.def, DASIMP.LIB, and D1000IMP.LIB, where ﬁlename indicates the name of your application program.

4. From the Options menu, select Project.

5. From the Project Options dialog box, select Linker\General and make sure that you turn OFF both the Case sensitive link and Case sensiti ve exports and imports options.

6. From the Project menu, choose Build All to create a stand-alone executable ﬁle (.EXE) that you can execute from within Windows.

Visual Basic for Windows Programming Information

The following sections contain information you need to allocate and assign memory buffers, to create channel-gain queues, and to handle errors in Microsoft Visual Basic for Windows, as well as other language-speciﬁc information for Microsoft Visual Basic for Windows.

Dynamically Allocating and Assigning Memory Buffers

This section provides code fragments that describe how to allocate and assign dynamically allocated memory buffers when programming in Microsoft Visual Basic for Windows. Refer to the example programs on disk for more information.

Visual Basic for Windows Programming Information 3-25

Note: If you are using large or multiple memory buffers and you are

programming in Windows Enhanced mode, you may be limited in the amount of memory you can allocate. It is recommended that you use the Keithley Memory Manager before you begin programming to ensure that you can allocate a large enough buffer. Refer to your DASCard-1000 Series User’s Guide for more information about the Keithley Memory Manager.

Allocating a Single Memory Buffer

You can use a single, dynamically allocated memory buffer for synchronous-mode and interrupt-mode analog input operations.

. . . Global AcqBuf As Long ’ Declare pointer to buffer Global hMem As Integer ’ Declare integer for memory handle . . . wDasErr = K_IntAlloc (hFrame, Samples, AcqBuf, hMem) wDasErr = K_SetBuf (hFrame, AcqBuf, Samples) . . .

The following code illustrates how to use K_IntFree to later free the allocated buffer, using the memory handle stored by K_IntAlloc.

. . . wDasErr = K_IntFree (hMem) . . .

Allocating Multiple Memory Buffers

You can use multiple, dynamically allocated memory buffers for interrupt-mode analog input operations.

3-26 Programming with the Function Call Driver

. . . Global AcqBuf(4) As Long ’ Declare 5 pointers to 5 buffers Global hMem(4) As Integer ’ Declare 5 memory handles . . . for i% = 0 to 4 wDasErr = K_IntAlloc (hFrame, Samples, AcqBuf(i%), hMem(i%)) wDasErr = K_BufListAdd (hFrame, AcqBuf(i%), Samples) next i% . . .

The following code illustrates how to use K_IntFree to later free the allocated buffers, using the memory handles stored by K_IntAlloc; if you free the allocated buffers, you must also use K_BufListReset to reset the buffer list associated with the frame.

. . . for i% = 0 to 4

wDasErr = K_IntFree (hMem(i%)) next i% wDasErr = K_BufListReset (hADFrame) . . .

Accessing the Data from Buffers with Fewer than 64K Bytes

In Microsoft Visual Basic for Windo ws, you cannot directly access analog input samples stored in dynamically allocated memory buffers. You must use K_MoveBufToArray to move a subset (up to 32,766 samples) of the data into a local array as required. The following code fragment illustrates how to move the ﬁrst 100 samples of the second buffer in the multiple-buffer operation described in the previous section (AcqBuf(1)) to a local array.

. . . Dim Buffer(1000) As Integer ’ Declare local memory buffer . . . wDasErr = K_MoveBufToArray (Buffer(0), AcqBuf(1), 100) . . .

Visual Basic for Windows Programming Information 3-27

Accessing the Data from Buffers with More than 64K Bytes

When Windows is running, the CPU operates in 16-bit protected mode. Memory is addressed using a 32-bit selector:offset pair. The selector is the CPU’s handle to a 64K byte memory page; it is a code whose value is signiﬁcant only to the CPU. No mathematical relationship exists between a selector and the memory location it is associated with. In general, even consecutively allocated selectors have no relationship to each other.

When a memory buffer of more than 64K bytes (32K values) is used, multiple selectors are required. Under Windows, K_IntAlloc uses a “tiled” method to allocate memory whereby a mathematical relationship does exist among the selectors. Speciﬁcally, if you allocate a buffer of more than 64K bytes, each selector that is allocated has an arithmetic value that is eight greater than the previous one. The format of the address is a 32-bit value whose high word is the 16-bit selector value and low word is the 16-bit offset value. When the offset reaches 64K bytes, the next consecutive memory address location can be accessed by adding eight to the selector and resetting the offset to zero; to do this, add &h80000 to the buffer starting address.

Table 3-4 illustrates the mapping of consecutive memory locations in protected-mode “tiled” memory, where xxxxxxxx indicates the address calculated by the CPU memory mapping mechanism.

Table 3-4. Protected-Mode Memory Architecture

Selector:Offset 32-Bit Linear Address

. . . . : . . . . . . . . .

32E6:FFFE xxxxxxxx 32E6:FFFF xxxxxxxx + 1 32EE:0000 xxxxxxxx + 2 32EE:0001 xxxxxxxx + 3

. . . . : . . . . . . . . .

3-28 Programming with the Function Call Driver

The following code fragment illustrates moving 1,000 values from a memory buffer (AcqBuf) allocated with 50,000 values to the program’s local array (Array), starting at sample number 40,000. First, start with the buffer address passed in K_SetBuf. Then, determine how deep (in 64K byte pages) into the buffer the desired sample number (40,000) is located and add &h80000 to the buffer address for each 64K byte page. Finally, add any additional offset after the 64K byte pages to the buffer address.

Dim AcqBuf As Long Dim NumSamps As Long

Dim Array (1000) As Integer NumSamps = 50000 wDasErr = K_IntAlloc (hFrame, NumSamps, AcqBuf, hMem) . . . ’Acquisition routine . . . DesiredSamp = 40000 DesiredByte = DesiredSamp * 2 ’Number of bytes into buffer AddSelector = DesiredByte / &h10000 ’Number of 64K pages into buffer RemainingOffset = DesiredByte Mod &h10000 ’Additional offset

DesiredBuffLoc = AcqBuf + (AddSelector * &h80000) + RemainingOffset

wDasErr = K_MoveBufToArray (Array(0), DesiredBuffLoc, 1000)

To move more than 32,766 values from the memory buffer to the program’s local array, the program must call K_MoveBufToArray more than once. For example, assume that pBuf is a pointer to a dynamically allocated buffer that contains 65,536 v alues. The follo wing code fragment illustrates how to move 65,536 values from the dynamically allocated buffer to the program’s local array.

... Dim Data [3, 16384] As Integer ... wDasErr = K_MoveBufToArray (Data(0,0), pBuf, 16384)

’Same selector, add 32,768 bytes to offset: add &h8000 wDasErr = K_MoveBufToArray (Data(1,0), pBuf + &h8000, 16384)

’Add 8 to selector, offset = 0: add &h80000 wDasErr = K_MoveBufToArray (Data(2,0), pBuf + &h80000, 16384) ’Add 8 to selector, add 32,768 bytes to offset: add &h88000 wDasErr = K_MoveBufToArray (Data(3,0), pBuf + &h88000, 16384)

Visual Basic for Windows Programming Information 3-29

Dimensioning and Assigning Local Arrays

This section provides code fragments that describe how to dimension and assign local arrays when programming in Microsoft Visual Basic for Windows. Refer to the example programs on disk for more information.

Dimensioning a Single Array

You can use a single, local array for synchronous-mode and interrupt-mode analog input operations.

The following code fragment illustrates how to dimension an array of 10,000 samples for the frame deﬁned by hFrame and how to use K_SetBufI to assign the starting address of the array.

. . . Global Data(9999) As Integer ’ Allocate array . . . wDasErr = K_SetBufI (hFrame, Data(0), 10000) . . .

Dimensioning Multiple Arrays

You can use multiple, local arrays for interrupt-mode analog input operations.

The following code fragment illustrates how to dimension two arrays of 32,000 samples each for the frame deﬁned by hADFrame and how to use K_BufListAdd to assign the starting addresses of the arrays.

. . . Global Data1(31999) As Integer ’ Allocate Array #1 Global Data2(31999) As Integer ’ Allocate Array #2 . . . wDasErr = K_BufListAdd (hADFrame, Data1(0), 32000) wDasErr = K_BufListAdd (hADFrame, Data2(0), 32000) . . .

3-30 Programming with the Function Call Driver

Creating a Channel-Gain Queue

Before you create your channel-gain queue, you must declare an array of integers to accommodate the required number of entries. It is recommended that you declare an array two times the number of entries plus one. For example, to accommodate a channel-gain queue of 256 entries, you should declare an array of 513 integers ((256 x 2) + 1).

Next, you must ﬁll the array with the channel-gain information. After you create the channel-gain queue, you must use K_FormatChnGAry to reformat the channel-gain queue so that it can be used by the DASCard-1000 Series Function Call Driver.

The following code fragment illustrates how to create a four-entry channel-gain queue called MyChanGainQueue for a DASCard-1002 card and how to use K_SetChnGAry to assign the starting address of MyChanGainQueue to the frame deﬁned by hFrame.

. . . Global MyChanGainQueue(9) As Integer ’(4 channels x 2) + 1 . . . MyChanGainQueue(0) = 4 ’ Number of channel-gain pairs MyChanGainQueue(1) = 0 ’ Channel 0 MyChanGainQueue(2) = 0 ’ Gain of 1 MyChanGainQueue(3) = 1 ’ Channel 1 MyChanGainQueue(4) = 1 ’ Gain of 2 MyChanGainQueue(5) = 2 ’ Channel 2 MyChanGainQueue(6) = 2 ’ Gain of 4 MyChanGainQueue(7) = 2 ’ Channel 2 MyChanGainQueue(8) = 3 ’ Gain of 8 . . . wDasErr = K_FormatChnGAry (MyChanGainQueue(0)) wDasErr = K_SetChnGAry (hFrame, MyChanGainQueue(0)) . . .

Once formatted, your Visual Basic for Windows program can no longer read the channel-gain queue. To read or modify the array after it has been formatted, you must use K_RestoreChnGAry as follows:

. . . wDasErr = K_RestoreChnGAry (MyChanGainQueue(0)) . . .

Visual Basic for Windows Programming Information 3-31

When you start the next analog input operation (using K_SyncStart or K_IntStart), channel 0 is sampled at a gain of 1, channel 1 is sampled at

a gain of 2, channel 2 is sampled at a gain of 4, and so on.

Correcting Data

If you are using Visual Basic for Windows and have disabled automatic data correction, the application program must correct the data after the operation is complete. The following code fragment illustrates how to correct the data and how to convert the corrected data to volts.

Dim fCalData(2) As Single ’ Contains calibration values Dim fGainVal As Single ’ Gain value to apply Dim fOffsetVal As Single ’ Offset value to apply Dim nCounts As Integer ’ Count value to convert

. . . wDasErr = K_SetCalMode (hAD, 0) ’ Disables correction by driver . . . ’ Gets gain and offset values wDasErr = K_GetCalData (hAD, 0, 0, 0, fCalData) . . . fGainVal = fCalData(0) fOffsetVal = fCalData(1) . . . wDasErr = K_MoveBufToArray (aDataBuf(0), dwBufAddr(0), 100) . . . ’ Corrects the data and converts counts to volts; assumes that ’ you are using a bipolar +/-5 V analog input range nCounts = aDataBuf(0) nCounts = nCounts * fGainVal + fOffsetVal ’ Corrects data PRINT nCounts * 0.00244 ’ 1 count = 0.00244 volts

3-32 Programming with the Function Call Driver

Handling Errors

. . . wDasErr = K_GetDevHandle (hDrv, BoardNum, hDev) If (wDasErr <> 0) Then

MsgBox “K_GetDevHandle Error: ” + Hex$ (wDasErr),

MB_ICONSTOP, “DASCARD-1000 ERROR”

End End If . . .

Programming in Microsoft Visual Basic for Windows

To program in Microsoft Visual Basic for Windows, you need the following ﬁles; these ﬁles are provided in the ASO-1000 software package.

File Description

DASSHELL.DLL Dynamic Link Library DASSUPRT.DLL Dynamic Link Library DAS1000.DLL Dynamic Link Library DASDECL.BAS Include ﬁle; must be added to the project DAS1000.BAS Include ﬁle; must be added to the project

To create an executable ﬁle from the Microsoft Visual Basic for Windows environment, choose Make EXE File from the File menu.

Visual Basic for Windows Programming Information 3-33

BASIC Programming Information

The following sections contain information you need to allocate and assign memory buffers, to create channel-gain queues, and to handle errors in BASIC, as well as other language-speciﬁc information for Microsoft QuickBasic and Microsoft Professional Basic.

Dynamically Allocating and Assigning Memory Buffers

This section provides code fragments that describe how to allocate and assign dynamically allocated memory buffers when programming in BASIC. Refer to the example programs on disk for more information.

Reducing the Memory Heap

By default, when BASIC programs run, all available memory is left for use by the internal memory manager. BASIC provides the SetMem function to distribute the av ailable memory (the Far Heap). It is necessary to redistribute the Far Heap if you want to use dynamically allocated buffers. It is recommended that you include the following code at the beginning of BASIC programs to free the Far Heap for the driver’s use.

FarHeapSize& = SetMem(0) NewFarHeapSize& = SetMem(–FarHeapSize&/2)

Allocating a Single Memory Buffer

You can use a single, dynamically allocated memory buffer for synchronous-mode and interrupt-mode analog input operations.

The following code fragment illustrates how to use KIntAlloc to allocate a buffer of size Samples for the frame deﬁned by hFrame and how to use KSetBuf to assign the starting address of the buffer.

. . . Dim AcqBuf As Long ’ Declare pointer to buffer Dim hMem As Integer ’ Declare integer for memory handle . . . wDasErr = KIntAlloc% (hFrame, Samples, AcqBuf, hMem) wDasErr = KSetBuf% (hFrame, AcqBuf, Samples) . . .

3-34 Programming with the Function Call Driver

The following code illustrates how to use KIntFree to later free the allocated buffer, using the memory handle stored by KIntAlloc.

. . . wDasErr = KIntFree% (hMem) . . .

Allocating Multiple Memory Buffers

You can use multiple, dynamically allocated memory buffers for interrupt-mode analog input operations.

The following code fragment illustrates how to use KIntAlloc to allocate ﬁve buffers of size Samples each for the frame deﬁned by hADFrame and how to use KBufListAdd to assign the starting addresses of the ﬁve buffers.

. . . Dim AcqBuf(4) As Long ’ Declare 5 pointers to 5 buffers Dim hMem(4) As Integer ’ Declare 5 memory handles . . . for i% = 0 to 4 wDasErr = KIntAlloc% (hFrame, Samples, AcqBuf(i%), hMem(i%)) wDasErr = KBufListAdd% (hFrame, AcqBuf(i%), Samples) next i% . . .

The following code illustrates how to use KIntFree to later free the allocated buffers, using the memory handles stored by KIntAlloc; if you free the allocated buffers, you must also use KBufListReset to reset the buffer list associated with the frame.

. . . for i% = 0 to 4

wDasErr = KIntFree% (hMem(i%)) next i% wDasErr = KBufListReset% (hADFrame) . . .

BASIC Programming Information 3-35

Accessing the Data from Buffers with Fewer than 64K Bytes

In BASIC, you cannot directly access analog input samples stored in a dynamically allocated memory buffer. You must use KMoveBufToArray to move a subset of the data (up to 32,766 samples) into a local array. The following code fragment illustrates how to move the ﬁrst 100 samples of the second buffer in the multiple-buffer operation described in the previous section (AcqBuf(1)) into a local memory buffer.

. . . Dim Buffer(1000) As Integer ’ Declare local memory buffer . . . wDasErr = KMoveBufToArray% (Buffer(0), AcqBuf(1), 100) . . .

Accessing the Data from Buffers with More than 64K Bytes

Under DOS, the CPU operates in real mode. Memory is addressed using a 32-bit segment:offset pair. Memory is allocated from the far heap, the reserve of conventional memory that occupies the ﬁrst 640K bytes of the 1M byte of memory that the CPU can address in real mode. In the segmented real-mode architecture, the 16-bit segment:16-bit offset pair combines into a 20-bit linear address using an overlapping scheme. For a given segment value, you can address 64K bytes of memory by varying the offset.

When a memory buffer of more than 64K bytes (32K integer values) is used, multiple segments are required. When an offset reaches 64K bytes, the next linear memory address location can be accessed by adding &h1000 to the buffer segment and resetting the offset to zero.

Table 3-5 illustrates the mapping of consecutive memory locations at a segment page boundary.

3-36 Programming with the Function Call Driver

The following code fragment illustrates how to mo v e 1,000 v alues from a memory buffer (AcqBuf) allocated with 50,000 values to the program’s local array (Array), starting at the sample at buffer index 40,000. You must ﬁrst calculate the linear address of the buffer’s starting point, then add the number of bytes deep into the buffer that the desired starting sample is located, and ﬁnally convert this adjusted linear address to a segment:offset format.

Dim AcqBuf As Long Dim NumSamps As Long Dim LinAddrBuff As Long Dim DesLocAddr As Long Dim AdjSegOffset As Long

Table 3-5. Real-Mode Memory Architecture

Segment:Offset 20-Bit Linear Address

. . . . : . . . . . . . . .

74E4:FFFE 84E3E 74E4:FFFF 84E3F 84E4:0000 84E40 84E4:0001 84E41

. . . . : . . . . . . . . .

Dim Array(1000) As Integer . . . ’Initialize array with desired values NumSamps = 50000 wDasErr = KIntAlloc% (hFrame, NumSamps, AcqBuf, hMem) . . . ’Acquisition routine . . . DesiredSamp = 40000 DesiredByte = DesiredSamp * 2 ’Number of bytes into buffer

’To obtain the 20-bit linear address of the buffer, shift the ’segment:offset to the right 16 bits (leaves segment only), ’multiply by 16, then add offset LinAddrBuff = (AcqBuf / &h10000) * 16 + (AcqBuf AND &hFFFF)

BASIC Programming Information 3-37

’20-bit linear address of desired location in buffer DesLocAddr = LinAddrBuff + DesiredByte

’Convert desired location to segment:offset format AdjSegOffset = (DesLocAddr / 16) * &h10000 + (DesLocAddr AND &hF)

wDasErr = KMoveBufToArray% (Array(0), AdjSegOffset, 1000)

To move more than 32,767 values from the memory buffer to the program’s local array, the program must call KMoveBufToArray more than once. For example, assume that pBuf is a pointer to a dynamically allocated buffer that contains 65,536 v alues. The follo wing code fragment illustrates how to move 65,536 values from the memory buffer to the program’s local array (Data).

Although it is recommended that you perform all calculations on the linear address and then convert the result to the segment:offset format (as shown in the previous code fragment), this example illustrates an alternative method of calculating the address by working on the segment:offset form of the address directly. You can use this method if you already know how deep you want to go into the buffer with each move and the offset of the starting buffer address is zero, as is the case when the buffer is allocated with KIntAlloc. In this method, you add &h10000000 to the buffer address for each 64K byte page and then add the remainder of the buffer.

... Dim Data[3,16384] As Integer ... wDasErr = KMoveBufToArray% (Data(0,0), pBuf, 16384)

’Same segment, add 32,768 bytes to offset: add &h8000 wDasErr = KMoveBufToArray% (Data(1,0), pBuf + &h8000, 16384)

’Next segment, offset = 0: add &h10000000 wDasErr = KMoveBufToArray% (Data(2,0), pBuf + &h10000000, 16384)

’Next segment, remainder = 32,768 bytes: add &h10008000 wDasErr = KMoveBufToArray% (Data(3,0), pBuf + &h10008000, 16384)

3-38 Programming with the Function Call Driver

Dimensioning and Assigning Local Arrays

This section provides code fragments that describe how to dimension and assign local arrays when programming in BASIC. Refer to the example programs on disk for more information.

Dimensioning a Single Array

You can use a single, local array for synchronous-mode and interrupt-mode analog input operations.

The following code fragment illustrates how to dimension an array of 10,000 samples for the frame deﬁned by hFrame and how to use KSetBufI to assign the starting address of the array.

. . . Dim Data(9999) As Integer ’ Allocate array . . . wDasErr = KSetBufI% (hFrame, Data(0), 10000) . . .

Dimensioning Multiple Arrays

You can use multiple, local arrays for interrupt-mode analog input operations.

The following code fragment illustrates how to dimension two arrays of 32,000 samples each for the frame deﬁned by hADFrame and how to use KBufListAdd to assign the starting addresses of the arrays.

. . . Dim Data1(31999) As Integer ’ Allocate Array #1 Dim Data2(31999) As Integer ’ Allocate Array #2 . . . wDasErr = KBufListAdd% (hADFrame, Data1(0), 32000) wDasErr = KBufListAdd% (hADFrame, Data2(0), 32000) . . .

Note: The declaration of the second parameter of the KBufListAdd

function in the DASDECL.BI ﬁle is not applicable to local arrays. You must change the declaration of pBuf from BYVAL pBuf AS LONG to SEG pBuf AS INTEGER.

BASIC Programming Information 3-39

Creating a Channel-Gain Queue

Next, you must ﬁll the array with the channel-gain information. After you create the channel-gain queue, you must use KFormatChnGAry to reformat the channel-gain queue so that it can be used by the DASCard-1000 Series Function Call Driver.

The following code fragment illustrates how to create a four-entry channel-gain queue called MyChanGainQueue for a DASCard-1002 card and how to use KSetChnGAry to assign the starting address of MyChanGainQueue to the frame deﬁned by hFrame.

. . . Dim MyChanGainQueue(9) As Integer ’(4 channels x 2) + 1 . . . MyChanGainQueue(0) = 4 ’ Number of channel-gain pairs MyChanGainQueue(1) = 0 ’ Channel 0 MyChanGainQueue(2) = 0 ’ Gain of 1 MyChanGainQueue(3) = 1 ’ Channel 1 MyChanGainQueue(4) = 1 ’ Gain of 2 MyChanGainQueue(5) = 2 ’ Channel 2 MyChanGainQueue(6) = 2 ’ Gain of 4 MyChanGainQueue(7) = 2 ’ Channel 2 MyChanGainQueue(8) = 3 ’ Gain of 8 . . . wDasErr = KFormatChnGAry% (MyChanGainQueue(0)) wDasErr = KSetChnGAry% (hFrame, MyChanGainQueue(0)) . . .

Once formatted, your BASIC program can no longer read the channel-gain array. To read or modify the array after it has been formatted, you must use KRestoreChnGAry as follows:

. . . wDasErr = KRestoreChnGAry% (MyChanGainQueue(0)) . . .

3-40 Programming with the Function Call Driver

When you start the next analog input operation (using KSyncStart or KIntStart), channel 0 is sampled at a gain of 1, channel 1 is sampled at a

gain of 2, channel 2 is sampled at a gain of 4, and so on.

Correcting Data

If you are using BASIC, the application program must correct the data after the operation is complete. The following code fragment illustrates how to correct the data and how to convert the corrected data to volts.

DIM nCalData(2) AS INTEGER ’ Contains calibration values DIM fGainVal AS SINGLE ’ Gain value to apply DIM nOffsetVal AS INTEGER ’ Offset value to apply DIM nCounts AS INTEGER ’ Count value to convert

. . . ’ Gets gain and offset values wDasErr = KGETCALDATA% (hAD, 0, 0, 0, nCalData) . . . ’ Determines the actual gain to apply to the data fGainVal = 1! + nCalData(0) * 0.001 nOffsetVal = nCalData(1) . . . wDasErr = KMOVEBUFTOARRAY% (aDataBuf(0), dwBufAddr(0), 100) . . . ’ Corrects the data and converts counts to volts; assumes that ’ you are using a bipolar +/-5 V analog input range nCounts = aDataBuf(0) nCounts = nCounts * fGainVal + nOffsetVal /* Corrects data */ PRINT nCounts * 0.00244 ’ 1 count = 0.00244 volts

BASIC Programming Information 3-41

Handling Errors

. . . wDasErr = DAS1000GETDEVHANDLE% (BoardNum, hDev) IF (wDasErr <> 0) THEN BEEP PRINT “Error”;HEX$(wDasErr);“occurred during‘DAS1000GETDEVHANDLE%’” END END IF . . .

Programming in Microsoft QuickBasic

To program in Microsoft QuickBasic, you need the following ﬁles; these ﬁles are provided in the DASCard-1000 Series standard software package.

File Description

D1000Q45.LIB Linkable driver for QuickBasic (Version 4.5)

stand-alone, executable (.EXE) programs

D1000Q45.QLB Command-line loadable driver for the QuickBasic

(Version 4.5) integrated environment QB4DECL.BI Include ﬁle DASDECL.BI Include ﬁle DAS1000.BI Include ﬁle

3-42 Programming with the Function Call Driver

For Microsoft QuickBasic, you can create an executable ﬁle from within the programming environment, or you can use a compile and link statement.

To create an executable ﬁle from within the programming environment, perform the following steps:

1. Enter the following to invoke the environment:

QB /L D1000Q45

filename

.bas

where ﬁlename indicates the name of your application program.

2. From the Run menu, choose Make EXE File.

To use a compile and link statement, enter the following:

BC ﬁlename.bas /O Link ﬁlename.obj,,,D1000Q45.lib+BCOM45.lib;

where ﬁlename indicates the name of your application program.

Programming in Microsoft Professional Basic

T o program in Microsoft Professional Basic, you need the follo wing ﬁles; these ﬁles are provided in the DASCard-1000 Series standard software package.

File Description

D1000QBX.LIB Linkable driver for Professional Basic,

stand-alone, executable (.EXE) programs D1000QBX.QLB Command-line loadable driver for the Professional

Basic integrated environment DASDECL.BI Include ﬁle DAS1000.BI Include ﬁle

BASIC Programming Information 3-43

For Microsoft Professional Basic, you can create an executable ﬁle from within the programming environment, or you can use a compile and link statement.

To create an executable ﬁle from within the programming environment, perform the following steps:

1. Enter the following to invoke the environment:

QBX /L D1000QBX

filename

.bas

where ﬁlename indicates the name of your application program.

2. From the Run menu, choose Make EXE File.

To use a compile and link statement, enter the following:

BC ﬁlename.bas /o; Link ﬁlename.obj,,,D1000QBX.lib;

where ﬁlename indicates the name of your application program.

3-44 Programming with the Function Call Driver

Function Reference

The FCD functions are organized into the following groups:

Initialization functions

●

Operation functions

●

Frame management functions Memory management functions

●

Buffer address functions

●

Buffering mode functions

●

Channel and gain functions Clock functions

●

Trigger functions

●

Data correction functions Miscellaneous functions

●

The particular functions associated with each function group are presented in Table 4-1. The remainder of the chapter presents detailed descriptions of all the FCD functions, arranged in alphabetical order.

. 4-1

Table 4-1. Functions

Function Type Function Name Page Number

Initialization DAS1000_DevOpen page 4-6

DAS1000_GetDevHandle page 4-10 K_OpenDriver page 4-62 K_CloseDriver page 4-19 K_GetDevHandle page 4-44 K_FreeDevHandle page 4-31 K_DASDevInit page 4-24

Operation K_ADRead page 4-12

K_DIRead page 4-25 K_DOWrite page 4-27 K_SyncStart page 4-100 K_IntStart page 4-54 K_IntStatus page 4-55 K_IntStop page 4-58

Frame Management K_GetADFrame page 4-35

K_FreeFrame page 4-32 K_ClearFrame page 4-18

Memory Management K_IntAlloc page 4-51

K_IntFree page 4-53 K_MoveBufToArray page 4-60

Buffer Address K_SetBuf page 4-71

K_SetBufI page 4-73 K_BufListAdd page 4-14 K_BufListReset page 4-16

Buffering Mode K_SetContRun page 4-85

K_ClrContRun page 4-20

4-2 Function Reference

Table 4-1. Functions (cont.)

Function Type Function Name Page Number

Channel and Gain K_SetChn page 4-77

K_SetStartStopChn page 4-91 K_SetG page 4-89 K_SetStartStopG page 4-93 K_SetChnGAry page 4-79 K_FormatChnGAry page 4-29 K_RestoreChnGAry page 4-64 K_SetADConﬁg page 4-65 K_SetADMode page 4-67 K_GetADConﬁg page 4-33 K_GetADMode page 4-37

Clock K_SetClk page 4-81

K_SetClkRate page 4-83 K_GetClkRate page 4-42

Trigger K_SetTrig page 4-96

K_SetADTrig page 4-69 K_SetTrigHyst page 4-98 K_SetDITrig page 4-87

Data Correction K_CorrectData page 4-22

K_GetCalData page 4-39 K_SetCalMode page 4-75

Miscellaneous K_GetErrMsg page 4-46

K_GetVer page 4-49 K_GetShellVer page 4-47 DAS1000_GetCardInfo page 4-8

. 4-3

Keep the following conventions in mind throughout this chapter:

Although the function names are shown with underscores, do not use

●

the underscores in the BASIC languages.

●

The data types DWORD, WORD, and BYTE are deﬁned in the language-speciﬁc include ﬁles.

●

Variable names are shown in italics. The return value for all FCD functions is an integer error/status code.

●

Error/status code 0 indicates that the function executed successfully. A nonzero error/status code indicates that an error occurred. Refer to Appendix A for additional information.

●

In the usage section, the variables are not deﬁned. It is assumed that the variables are deﬁned as shown in the prototype. The name of each variable in both the prototype and usage sections includes a preﬁx that indicates the associated data type. These preﬁxes are described in Table 4-2.

4-4 Function Reference

Table 4-2. Data Type Preﬁxes

Preﬁx Data T ype Comments

sz Pointer to string terminated by

zero

h Handle to device, frame, and

memory block

ph Pointer to a handle-type variable This data type is used when calling the FCD functions

p Pointer to a variable This data type is used for pointers to all types of

n Number value This data type is used when passing a number,

w 16-bit word This data type is typically used when passing an

a Array This data type is typically used in conjunction with

This data type is typically used for variables that specify the driver's conﬁguration ﬁle name.

This data type is used for handle-type variables. You declare handle-type variables in your program as long or DWORD, depending on the language you are using. The actual variable is passed to the driver by value.

to get a driver handle, a frame handle, or a memory handle. The actual variable is passed to the driver by reference.

variables, except handles (h). It is typically used when passing a parameter of any type to the driver by reference.

typically a byte, to the driver by value.

unsigned integer to the driver by value.

other preﬁxes listed here; for example, anVar denotes an array of numbers.

f Float This data type denotes a single-precision ﬂoating-point

number.

d Double This data type denotes a double-precision

ﬂoating-point number.

dw 32-bit double word This data type is typically used when passing an

unsigned long to the driver by value.

. 4-5

DAS1000_DevOpen

Purpose

Prototype C/C++

Initializes the DASCard-1000 Series Function Call Driver.

DASErr far pascal DAS1000_DevOpen (char far *szCfgFile , char far *pBoards );

Visual Basic for Windows

Declare Function DAS1000_DevOpen Lib "DAS1000.DLL" (ByVal szCfgFile As String, pBoards As Integer) As Integer

BASIC

DECLARE FUNCTION DAS1000DEVOPEN% ALIAS "DAS1000_DevOpen" (BYVAL szCfgFile AS LONG, SEG pBoards AS INTEGER)

Parameters

szCfgFile

pBoards

Driver conﬁguration ﬁle. Valid values: The name of a conﬁguration ﬁle.

for DAS1000.CFG

Number of cards deﬁned in szCfgFile . Value stored: 1 or 2

Return Value

Remarks

Error/status code. Refer to Appendix A.

This function initializes the driver according to the information in the configuration file specified by szCfgFile and stores the number of DASCard-1000 Series cards defined in szCfgFile in pBoards .

You create a conﬁguration ﬁle using the CFG1000.EXE utility. If

szCfgFile = 0, DAS1000_DevOpen looks for the DAS1000.CFG

conﬁguration ﬁle in the current directory and uses those settings, if available. Refer to your DASCard-1000 Series User’s Guide for more information about conﬁguration ﬁles.

See Also

4-6 Function Reference

K_OpenDriver

Usage C/C++

#include "DAS1000.H" // Use DAS1000.HPP for C++ ... char nBoards; ... wDasErr = DAS1000_DevOpen ("DAS1002.CFG", &nBoards);

Visual Basic for Windows

(Add DAS1000.BAS to your project)

... DIM szCfgName AS STRING DIM nBoards AS INTEGER ... szCfgName = "DAS1002.CFG" + CHR$(0) wDasErr = DAS1000_DevOpen(szCfgName, nBoards)

DAS1000_DevOpen (cont.)

BASIC

' $INCLUDE: 'DAS1000.BI' ... DIM szCfgName AS STRING DIM nBoards AS INTEGER ... szCfgName = "DAS1002.CFG" + CHR$(0) wDasErr = DAS1000DEVOPEN%(SSEGADD(szCfgName),nBoards)

4-7

DAS1000_GetCardInfo

Purpose

Prototype C/C++

Gets the system resources allocated for a DASCard-1000 Series card.

DASErr far pascal DAS1000_GetCardInfo (WORD nBrdNum , short far *pSocket , short far * pIRQ , short far * pIOBase , short far * pMemBase , short far * pBrdType );

Visual Basic for Windows

Declare Function DAS1000_GetCardInfo Lib "DAS1000.DLL" (ByVal nBrdNum As Integer, pSocket As Integer, pIRQ As Integer,

pIOBase As Integer, pMemBase As Integer, pBrdType As Integer)

As Integer

BASIC

DECLARE FUNCTION DAS1000GETCARDINFO% ALIAS "DAS1000_GetCardInfo" (BYVAL nBrdNum AS INTEGER, SEG pSocket AS INTEGER, SEG pIRQ AS INTEGER, SEG pIOBase AS INTEGER, SEG pMemBase AS INTEGER, SEG pBrdType AS INTEGER)

Parameters

nBrdNum

Card number. Valid values: 0 or 1

pSocket pIRQ pIOBase pMemBase

Socket in which the card is installed. Interrupt level allocated by PCMCIA software. Base address allocated by PCMCIA software. Memory segment address allocated by PCMCIA

software.

pBrdType

Card type. Value stored: 0 for DASCard-1001

for DASCard-1002 for DASCard-1003

Return Value

4-8 Function Reference

Error/status code. Refer to Appendix A.

DAS1000_GetCardInfo (cont.)

Remarks

For the DASCard-1000 Series card speciﬁed by nBrdNum , this function stores the socket number in pSocket , the interrupt level in pIRQ , the base address in pIOBase , the memory segment address in pMemBase, and the card type in pBrdType.

The card number speciﬁed in nBrdNum refers to the card number speciﬁed in the conﬁguration ﬁle. If you are using one card, nBrdNum is always 0; if you are using two cards, nBrdNum is the same as the socket number.

Usage

C/C++

#include "DAS1000.H" // Use DAS1000.HPP for C++ ... WORD wSock, wIRQ, wIO, wMem, wType; ... wDasErr = DAS1000_GetCardInfo (0,&wSock,&wIRQ,&wIO,&wMem,&wType);

Visual Basic for Windows

(Add DAS1000.BAS to your project)

... Global wSock As Integer Global wIRQ As Integer Global wIO As Integer Global wMem As Integer Global wType As Integer ... wDasErr = DAS1000_GetCardInfo (0, wSock, wIRQ, wIO, wMem, wType)

BASIC

' $INCLUDE: 'DAS1000.BI' ... DIM wSock AS INTEGER DIM wIRQ AS INTEGER DIM wIO AS INTEGER DIM wMem AS INTEGER DIM wType AS INTEGER ... wDasErr = DAS1000GETCARDINFO% (0, wSock, wIRQ, wIO, wMem, wType)

4-9

DAS1000_GetDevHandle

Purpose

Prototype C/C++

Initializes a DASCard-1000 Series card.

DASErr far pascal DAS1000_GetDevHandle (WORD nBrdNum, DWORD far *phDev);

Visual Basic for Windows

Declare Function DAS1000_GetDevHandle Lib "DAS1000.DLL" (ByVal nBrdNum As Integer, phDev As Long) As Integer

BASIC

DECLARE FUNCTION DAS1000GETDEVHANDLE% ALIAS "DAS1000_GetDevHandle" (BYVAL nBrdNum AS INTEGER, SEG phDev AS LONG)

Parameters

nBrdNum Card number.

phDev Handle associated with the card.

Return Value

Error/status code. Refer to Appendix A.

Valid values: 0 or 1

Remarks

This function initializes the DASCard-1000 Series card speciﬁed by nBrdNum and stores the device handle of the speciﬁed card in phDev.

The value stored in phDev is intended to be used exclusively as an argument to functions that require a device handle. Your program should not modify the value stored in phDev.

See Also

4-10 Function Reference

K_GetDevHandle

Usage C/C++

#include "DAS1000.H" // Use DAS1000.HPP for C++ ... DWORD hDev; ... wDasErr = DAS1000_GetDevHandle (0, &hDev);

Visual Basic for Windows

(Add DAS1000.BAS to your project)

... Global hDev As Long ' Device Handle ... wDasErr = DAS1000_GetDevHandle (0, hDev)

BASIC

' $INCLUDE: 'DAS1000.BI' ... DIM hDev AS LONG ' Device Handle ... wDasErr = DAS1000GETDEVHANDLE% (0, hDev)

DAS1000_GetDevHandle (cont.)

4-11

K_ADRead

Purpose

Prototype C/C++

Reads a single analog input value.

DASErr far pascal K_ADRead (DWORD hDev, BYTE nChan, BYTE nGain, void far *pData);

Visual Basic for Windows

Declare Function K_ADRead Lib "DASSHELL.DLL" (ByVal hDev As Long, ByVal nChan As Integer, ByV al nGain As Integer , pData As Integer) As Integer

BASIC

DECLARE FUNCTION KADREAD% ALIAS "K_ADRead" (BYVAL hDev AS LONG, BYVAL nChan AS INTEGER, BYVAL nGain AS INTEGER, SEG pData AS INTEGER)

Parameters

hDev Handle associated with the card. nChan Analog input channel.

nGain Gain code.

Valid values: 0 to 255

Valid values:

Card Gain Gain Code

DASCard-1001 1 0

10 1 100 2 500 3

DASCard-1002 1 0

2 1 4 2 8 3

DASCard-1003 1 0

4-12 Function Reference

K_ADRead (cont.)

pData Acquired analog input value.

Return Value

Remarks

Error/status code. Refer to Appendix A.

This function reads the analog input channel nChan on the DASCard-1000 Series card speciﬁed by hDev at the gain represented by nGain, and stores the count value in pData.

If you are programming under Windows, the count value in pData is the corrected count value. If you are programming under DOS, the count value in pData is uncorrected and the application program must correct it. Refer to page 2-22 for information.

Refer to Appendix B for information on converting the corrected count value stored in pData to voltage.

See Also

Usage C/C++

K_IntStart, K_SyncStart

#include "DASDECL.H" // Use DASDECL.HPP for C++ ... int wADValue; ... wDasErr = K_ADRead (hDev, 0, 0, &wADValue);

Visual Basic for Windows

(Add DASDECL.BAS to your project)

... Global wADValue As Integer ... wDasErr = K_ADRead (hDev, 0, 0, wADValue)

BASIC

' $INCLUDE: 'DASDECL.BI' ... DIM wADValue AS INTEGER ... wDasErr = KADREAD% (hDev, 0, 0, wADValue)

4-13

K_BufListAdd

Purpose

Prototype C/C++

Adds a buffer or array to the list of multiple buffers/arrays.

DASErr far pascal K_BufListAdd (DWORD hFrame, void far *pBuf, DWORD dwSamples);

Visual Basic for Windows

Declare Function K_BufListAdd Lib "DASSHELL.DLL" (ByVal hFrame As Long, ByVal pBuf As Long, ByV al dwSamples As Long) As Integer

BASIC

DECLARE FUNCTION KBUFLISTADD% ALIAS "K_BufListAdd" (BYVAL hFrame AS LONG, BYVAL pBuf AS LONG, BYVAL dwSamples AS LONG)

Parameters

hFr ame Handle to the frame that deﬁnes the operation. pBuf Starting address of buffer or array. dwSamples Number of samples in the buffer or array.

Valid values: 1 to 5000000

Return Value

Remarks

Error/status code. Refer to Appendix A.

For the interrupt-mode operation deﬁned by hFrame, this function adds the buffer or array at the address pointed to by pBuf to the list of multiple buffers/arrays; the number of samples in the buffer/array is speciﬁed in dwSamples.

Since multiple buffers/arrays are not supported in synchronous mode, you cannot use this function for synchronous-mode operations.

Before you add the buffer or array to the list, you must either allocate the buffer dynamically using K_IntAlloc, or dimension the array locally.

If you are programming in BASIC and using this function to specify the starting address of a local array, the declaration of pBuf in the DASDECL.BI ﬁle is not applicable. You must change the declaration of pBuf from BYVAL pBuf AS LONG to SEG pBuf AS INTEGER.

4-14 Function Reference

K_BufListAdd (cont.)

Make sure that you add buffers or arrays to the list in the order in which you want to use them. The ﬁrst buffer/array you add is #1, the second buffer you add is #2, and so on. You can add up to 149 buffers. You can use K_IntStatus to determine which buffer/array is currently in use.

See Also

Usage

C/C++

#include "DASDECL.H" // Use "DASDECL.HPP for C++ ... void far *pBuf[5]; // Buffer pointers WORD hMem[5]; // Buffer handles ... for (i = 0; i < 5; i++) { wDasErr = K_IntAlloc (hAD, dwSamples, &pBuf[i], &hMem[i]); wDasErr = K_BufListAdd (hAD, pBuf[i], dwSamples); }

Visual Basic for Windows

K_BufListReset, K_IntAlloc

(Add DASDECL.BAS to your project)

... Global pBuf(4) As Long ' Buffer pointers Global hMem(4) As Integer ' Buffer handles ... For I% = 0 To 4 wDasErr = K_IntAlloc (hAD, dwSamples, pBuf(I%), hMem(I%)) wDasErr = K_BufListAdd (hAD, pBuf(I%), dwSamples) Next I%

BASIC

' $INCLUDE: 'DASDECL.BI' ... DIM pBuf(4) AS LONG ' Buffer pointers DIM hMem(4) AS INTEGER ' Buffer handles ... FOR I% = 0 TO 4 wDasErr = KINTALLOC% (hAD, dwSamples, pBuf(I%), hMem(I%)) wDasErr = KBUFLISTADD% (hAD, pBuf(I%), dwSamples) NEXT I%

4-15

K_BufListReset

Purpose

Prototype C/C++

Clears the list of multiple buffers/arrays.

DASErr far pascal K_BufListReset (DWORD hFrame);

Visual Basic for Windows

Declare Function K_BufListReset Lib "DASSHELL.DLL" (ByVal hFrame As Long) As Integer

BASIC

DECLARE FUNCTION KBUFLISTRESET% ALIAS "K_BufListReset" (BYVAL hFr ame AS LONG)

Parameters

Return Value

Remarks

hFr ame Handle to the frame that deﬁnes the operation.

Error/status code. Refer to Appendix A.

For the interrupt-mode operation deﬁned by hFrame, this function clears all buffers or arrays from the list of multiple buffers/arrays.

This function does not deallocate buffers in the list. If dynamically allocated buffers are no longer needed, you can use K_IntFree to free the buffers before resetting the list.

See Also

Usage C/C++

K_BufListAdd

#include "DASDECL.H" // Use "DASDECL.HPP for C++ ... wDasErr = K_BufListReset (hAD);

Visual Basic for Windows

(Add DASDECL.BAS to your project)

... wDasErr = K_BufListReset (hAD)

4-16 Function Reference

Tektronix DASCard-1000 Series ASO Function Call Driver Users Guide

Specifications and Main Features

Frequently Asked Questions

User Manual