Tektronix DASDLL Function Call Driver Users Guide

Download

DASDLL Function Call Driv er

USER’S GUIDE

DASDLL

Function Call Driver

User’s Guide

Revision A – December 1994

Part Number: 86590

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 using the DASDLL Function Call Driver. The DASDLL Function Call Driver supports the following Windows  -based languages:

●

Microsoft Visual C++  (Version 1.0 and higher) Microsoft Visual Basic for Windows (Version 3.0 and higher)

●

The manual is intended for application programmers using one of the following boards in an IBM

DAS-8 Series

●

DAS-16 Series

●

DAS-20

●

DAS-40 Series DAS-HRES

●

DDA-06

●

Series 500

●

PIO Series PDMA Series

●



PC AT



or compatible computer:

Throughout this manual, these boards are referred to as DASDLLsupported boards.

It is assumed that users

●

have read the External DAS Driver user’s guide and the user’s guide for their particular board to familiarize themselves with the board’s features.

have completed the appropriate hardware installation and

●

conﬁguration.

●

are experienced in programming in their selected language and are familiar with data acquisition principles.

The DASDLL Function Call Driver User’s Guide is organized as follows:

Chapter 1 provides an overview of the Function Call Driver and

●

describes the installation procedure. Information is included on setting up the board and how to get help, if necessary.

Chapter 2 describes the available operations and 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 and their

●

usage, arranged in alphabetical order. Appendix A contains a list of the error codes returned by the Function

●

Call Driver, along with speciﬁc causes and suggested solutions.

●

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

Appendix C provides board-speciﬁc operating speciﬁcations on gains

●

and channels.

●

Appendix D includes instructions for installing the Keithley Memory Manager.

An index completes this manual.

Note:

The DASDLL-supported boards vary in their features and operating parameters. Information presented in this manual is generic to cover ev ery board’ s requirements. F or board-speciﬁc information, refer to your board’s user’s guide and External DAS Driver user’s guide. Your board’s user’s guide is shipped with your board; the External DAS Driver user’s guide is shipped with the DASDLL software package.

Table of Contents

Preface

Getting Started

Installing the Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-2

Setting Up the Board and the Driver . . . . . . . . . . . . . . . . . . . . . .1-3

Getting Help. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-4

Available Operations

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

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

Initializing a Board . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-3

Retrieving Revision Levels . . . . . . . . . . . . . . . . . . . . . . . . . . .2-5

Handling Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-5

Analog Input Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-6

Operation Modes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-6

Memory Allocation and Management. . . . . . . . . . . . . . . . . . .2-8

Channels and Gains. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-10

Single Channel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-10

Multiple Channels Using a Group of

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

Multiple Channels Using a Channel-Gain Queue . . . . . .2-11

Pacer Clock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-12

Buffering Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-14

Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-14

Analog Trigger. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-15

Digital Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-16

Analog Output Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-17

Operation Modes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-17

Memory Allocation and Management. . . . . . . . . . . . . . . . . .2-18

Channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-20

Single Channel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-21

Multiple Channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-21

Pacer Clock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-21

Buffering Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-23

Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-24

iii

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

Operation Modes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-25

Memory Allocation and Management. . . . . . . . . . . . . . . . . .2-27

Channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-28

Pacer Clock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-30

Buffering Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-31

Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-32

Programming with the Function Call Driver

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

Programming Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-9

Preliminary Tasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-10

Operation-Speciﬁc Programming Tasks. . . . . . . . . . . . . . . . . . .3-10

Analog Input Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . .3-10

Single Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-11

Synchronous Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-11

Interrupt Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-13

DMA Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-15

Analog Output Operations . . . . . . . . . . . . . . . . . . . . . . . . . .3-17

Single Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-17

Synchronous Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-18

Interrupt Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-19

DMA Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-21

Digital I/O Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-23

Single Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-23

Synchronous Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-24

Interrupt Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-25

DMA Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-27

Language-Speciﬁc Programming Information. . . . . . . . . . . . . .3-29

Microsoft Visual C++ Language. . . . . . . . . . . . . . . . . . . . . .3-29

Allocating and Assigning Memory Buffers . . . . . . . . . . .3-30

Allocating the Memory Buffers. . . . . . . . . . . . . . . . . .3-30

Accessing the Data . . . . . . . . . . . . . . . . . . . . . . . . . . .3-31

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

Handling Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-32

Programming in Microsoft Visual C++ . . . . . . . . . . . . . .3-33

Microsoft Visual Basic for Windows. . . . . . . . . . . . . . . . . . .3-34

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

Allocating the Memory Buffers. . . . . . . . . . . . . . . . . .3-34

Accessing the Data . . . . . . . . . . . . . . . . . . . . . . . . . . .3-35

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

Handling Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-37

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

Function Reference

DASDLL_DevOpen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-7

DASDLL_DMAAlloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-9

DASDLL_DMAFree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-11

DASDLL_GetBoardName. . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-12

DASDLL_GetDevHandle . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-13

K_ADRead. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-15

K_ClearFrame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-17

K_CloseDriver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-18

K_ClrContRun . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-19

K_DASDevInit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-21

K_DAWrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-22

K_DIRead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-24

K_DMAStart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-26

K_DMAStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-27

K_DMAStop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-30

K_DOWrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-32

K_FormatChnGAry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-34

K_FreeDevHandle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-35

K_FreeFrame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-36

K_GetADFrame. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-37

K_GetADTrig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-38

K_GetBuf. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-40

K_GetBufB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-42

K_GetChn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-44

K_GetChnGAry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-45

K_GetClk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-46

K_GetClkRate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-48

K_GetContRun. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-50

K_GetDAFrame. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-52

K_GetDevHandle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-54

K_GetDIFrame. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-56

K_GetDOFrame. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-58

K_GetErrMsg. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-60

K_GetG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-61

K_GetShellVer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-63

K_GetStartStopChn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-65

K_GetStartStopG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-67

K_GetTrig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-69

K_GetVer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-71

K_IntStart. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-73

K_IntStatus. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-74

K_IntStop. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-77

K_MoveArrayToBuf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-79

K_MoveBufToArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-81

K_OpenDriver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-83

K_RestoreChnGAry. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-85

K_SetADTrig. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-86

K_SetBuf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-88

K_SetBufB. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-90

K_SetChn. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-92

K_SetChnGAry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-93

K_SetClk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-95

K_SetClkRate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-97

K_SetContRun . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-99

K_SetDMABuf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-101

K_SetDMABufB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-103

K_SetG. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-105

K_SetStartStopChn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-106

K_SetStartStopG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-108

K_SetTrig. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-110

K_SyncAlloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-112

K_SyncFree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-114

K_SyncStart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-115

Error/Status Codes

Data Formats

Converting Counts to Voltage. . . . . . . . . . . . . . . . . . . . . . . . . . . B-1

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

Operating Speciﬁcations

Gains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-1

Channels. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-8

Keithley Memory Manager

Installing and Setting Up the KMM. . . . . . . . . . . . . . . . . . . . . . D-2

Using KMMSETUP.EXE . . . . . . . . . . . . . . . . . . . . . . . . . . . D-2

Using a Text Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-3

Removing the KMM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-4

Index

List of Figures

Figure 2-1. Logical Board Numbers. . . . . . . . . . . . . . . . . . . . .2-4

Figure 2-2. Analog Trigger Conditions . . . . . . . . . . . . . . . . .2-16

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

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

List of Tables

Table 1-1. Boards Supported. . . . . . . . . . . . . . . . . . . . . . . . . .1-1

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

Table 2-2. Time Bases. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-12

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

Table 3-2. D/A Frame Elements . . . . . . . . . . . . . . . . . . . . . . .3-6

Table 3-3. DI Frame Elements . . . . . . . . . . . . . . . . . . . . . . . .3-7

Table 3-4. DO Frame Elements. . . . . . . . . . . . . . . . . . . . . . . .3-8

Table 3-5. Setup Functions for Synchronous-Mode

Analog Input Operations . . . . . . . . . . . . . . . . . . .3-12

Table 3-6. Setup Functions for Interrupt-Mode

Analog Input Operations . . . . . . . . . . . . . . . . . . .3-14

Table 3-7. Setup Functions for DMA-Mode

Analog Input Operations . . . . . . . . . . . . . . . . . . .3-16

Table 3-8. Setup Functions for Synchronous-Mode

Analog Output Operations. . . . . . . . . . . . . . . . . .3-18

Table 3-9. Setup Functions for Interrupt-Mode

Analog Output Operations. . . . . . . . . . . . . . . . . .3-20

Table 3-10. Setup Functions for DMA-Mode

Analog Output Operations. . . . . . . . . . . . . . . . . .3-22

Table 3-11. Setup Functions for Synchronous-Mode

Digital Input and Output Operations . . . . . . . . . .3-24

Table 3-12. Setup Functions for Interrupt-Mode

Digital Input and Digital Output Operations . . . .3-26

Table 3-13. Setup Functions for DMA-Mode

Digital Input and Digital Output Operations . . . .3-28

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

vii

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

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

Table B-1. Data Formats (Analog Input). . . . . . . . . . . . . . . . B-2

Table B-2. Full Scale Values . . . . . . . . . . . . . . . . . . . . . . . . . B-3

Table B-3. Data Formats (Analog Output) . . . . . . . . . . . . . . B-5

Table C-1. Gain Codes for DASDLL-Supported Boards . . . C-2

Table C-2. Gain Codes for Series 500 Boards. . . . . . . . . . . . C-6

Table C-3. Channels Available on

DASDLL-Supported Boards . . . . . . . . . . . . . . . . C-8

viii

Getting Started

The DASDLL Function Call Driver is a library of data acquisition and control functions (referred to as the Function Call Driver or FCD functions). Table 1-1 lists the Keithley DAS boards supported by the DASDLL Function Call Driver.

Table 1-1. Boards Supported

Series Boards

DAS-8 DAS-8, DAS-8LT, DAS-8PGA, DAS-8PGA-G2,

DAS-8/AO DAS-16 DAS-16, DAS-16F, DAS-16G1, DAS-16G2 DAS-20 DAS-20 DAS-40 DAS-40G1, DAS-40G2 DAS-HRES DAS-HRES DDA-06

500 AMM1A, AMM2, AIM2, AIM3A, AIM4, AIM6

PIO PIO-12, PIO-24, PIO-32, PIO-96, PIO-HV PDMA PDMA-16, PDMA-32

Throughout this manual, the boards in Table 1-1 are referred to as DASDLL-supported boards.

DDA-06

AIM7, AIM8, AIM9

1-1

The DASDLL software package contains the following:

Dynamic Link Libraries (DLLs) of FCD functions for Microsoft

●

Visual C++ and Microsoft Visual Basic for Windows.

●

Support ﬁles, containing program elements, such as function prototypes and deﬁnitions of variable types, that are required by the FCD functions.

●

Language-speciﬁc example programs.

The following sections describe how to install the software, how to set up a board to use the DASDLL Function Call Driver, and how to get help, if necessary.

Installing the Software

To install the DASDLL software package, perform the following steps:

1. Make a backup copy of the supplied disks. Use the copies as your working disks and store the originals as backup disks.

2. Insert disk #1 into the disk drive.

3. Start Windows, if necessary.

4. From the Program Manager menu, choose File and then choose Run.

5. Assuming that you are using disk drive A, type the following at the command line in the Run dialog box, and then select OK:

A:SETUP

The installation program prompts you for your installation preferences, including the drive and directory you want to copy the software to. It also prompts you to insert additional disks, as necessary.

1-2 Getting Started

6. Continue to insert disks and respond to prompts, as appropriate. When the installation program prompts you for a drive designation,

enter a designation of your choosing or accept the default drive C. When the installation program prompts you for a directory name, enter a name of your choosing or accept the default name.

The installation program creates a directory on the speciﬁed drive and copies all ﬁles, expanding any compressed ﬁles.

The installation program also creates a DASDLL family group; this group includes example Windows programs.

7. When the installation program notiﬁes you that the installation is complete, review the following ﬁles:

– FILES.TXT lists and describes all the ﬁles copied to the hard disk

by the installation program.

– README.TXT contains information that was not available when

this manual was printed.

Setting Up the Board and the Driver

Before you use the DASDLL Function Call Dri v er, you must perform the following tasks:

1. Set up your board’s hardware. Refer to your board’s user’s guide and your External DAS Driver user’s guide for information.

2. Exit Windows and return to DOS.

3. Run the conﬁguration program for your board from DOS. The conﬁguration program is shipped with the External DAS Driver for your board. Refer to your External DAS Driver user’s guide for information.

Note:

You cannot run the conﬁguration program or load the External DAS Driver from the MS-DOS Prompt when in Windows. You must exit Windows and return to DOS.

1-3

4. Load the External DAS Driver for your board from DOS. Refer to your External DAS Driver user’s guide for information.

5. Load Windo ws.

Getting Help

Note:

If you want to set up your AUTOEXEC.BAT ﬁle to automatically load the External DAS Driver, make sure that you include the line that loads the External DAS Driver before the line that loads Windows.

If you need help installing or using the DASDLL 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

, Eastern Time

P.M.

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

1-4 Getting Started

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

DASDLL-supported board conﬁguration

Computer

Operating system

Software package

Compiler (if applicable)

Model Serial # Revision code Base address setting Interrupt level setting Input conﬁguration Input range type DMA channel Other

Manufacturer CPU type Clock speed (MHz) Amount of RAM Video system BIOS type

DOS version Windows version Windows mode

Serial # Version Invoice/Order #

Language Manufacturer Version

_____________________ _____________________ _____________________ _____________________ _____________________ single-ended, differential unipolar, bipolar _____________________ _____________________

_____________________ _____________________ _____________________ _____________________ _____________________ _____________________

_____________________

3.0, 3.1 Standard, Enhanced

_____________________ _____________________ _____________________

Accessories

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

_____________________ _____________________ _____________________ _____________________ _____________________ _____________________ _____________________ _____________________

1-5

Available Operations

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

Table 2-1. Supported Operations

Operation Page Reference

System page 2-2 Analog input page 2-6 Analog output page 2-17 Digital input and output (I/O) page 2-25

Note:

operating parameters. Information presented in this chapter is generic to cover ev ery board’ s requirements. F or board-speciﬁc information, refer to your board’s user’s guide and External DAS Driver user’s guide. Your board’s user’s guide is shipped with your board; the External DAS Driver user’s guide is shipped with the DASDLL software package.

The DASDLL-supported boards vary in their features and

2-1

The following features are not supported by the DASDLL Function Call Driver, even though the External DAS Driver for your DASDLL may support them:

More than two memory buffers per frame

●

Simultaneous sample-and-hold (SSH)

●

Programmable external pacer clock polarity About-trigger acquisition

●

Hardware gate

●

Counter/timer functions

●

Timed interrupt functions Time of Day (TOD) functions

●

System Operations

This section describes the miscellaneous and general maintenance operations that apply to DASDLL-supported boards and to the DASDLL Function Call Driver. It includes information on the following operations:

Initializing the driver

●

Initializing a board

●

Retrieving revision levels

●

Handling errors

Initializing the Driver

You must initialize the DASDLL 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; the driver returns a unique identiﬁer for the driver (this identiﬁer is called the driver handle).

If a particular driver is no longer required and you want to free some memory , you can use the K_CloseDriver function to free a driver handle and close the associated driver. The driver is shut down and the DLLs associated with the driver are shut down and unloaded from memory.

2-2 Available Operations

Note:

driver and determine the number of boards found by the DASDLL Function Call Driver.

Initializing a Board

The number of boards supported by the DASDLL Function Call Driver depends on the number of External DAS Drivers you loaded and the number of boards supported by each External DAS Driver. You must use the K_GetDevHandle function to specify the boards you want to use. The driver returns a unique identiﬁer for each board; this identiﬁer is called the board handle.

You can also use the DASDLL_DevOpen function to initialize the

Board handles allow you to communicate with more than one board. You use the board handle returned by K_GetDevHandle in subsequent function calls related to the board.

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

Note:

You can also use the DASDLL_GetDevHandle function to

specify the boards you are using.

The board number you specify in K_GetDevHandle is a logical board number; it is determined by how you loaded your External DAS Drivers. For example, Figure 2-1 illustrates a system in which you ﬁrst loaded the DAS-8 External DAS Driver (conﬁgured for two boards) and then loaded the DAS-16 External DAS Driver (conﬁgured for two boards).

2-3

DAS-8 External DAS Driver

Note:

Board 1

Board 2

DAS-16 External DAS Driver

Board 1

Board 2

Figure 2-1. Logical Board Numbers

The DASDLL Function Call Driver treats Series 500 modules as

Logical Board Number = 0 Logical Board Number = 1

Logical Board Number = 2

Logical Board Number = 3

separate boards.

You can use the DASDLL_GetBoardName function to return information about the boards and drivers loaded in your system. When you enter a logical board number, the dri ver returns the name of the dri ver associated with the board. A NULL pointer is returned if no driver is associated with the board.

For example, if you set up a loop to return the names of the drivers associated with the boards shown in Figure 2-1, the driver returns four strings and a NULL pointer. The ﬁrst two strings represent the DAS-8 External DAS Dri v er; the ne xt two strings represent the DAS-16 External DAS Driver; the ﬁfth string is a NULL pointer.

The returned strings indicate that your system contains four boards. The ﬁrst two logical boards, 0 and 1, are DAS-8 Series boards; the next two, boards 2 and 3, are DAS-16 Series boards.

2-4 Available Operations

To reinitialize a board during an operation, use the K_DASDevInit function. K_GetDevHandle , DASDLL_GetDevHandle , and

K_DASDevInit perform the following tasks:

Abort all operations currently in progress that are associated with the

●

board identiﬁed by the board handle.

●

Verify that the board identiﬁed by the board handle is the board speciﬁed in the conﬁguration ﬁle.

Retrieving Revision Levels

If you are having problems with your application program, you may want to verify which versions of the Function Call Driv er , Keithle y D AS Driv er Speciﬁcation, and Keithley DAS Shell are used by your 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 is shared by all DASDLL-supported 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 programming language uses a different procedure for error checking. Refer to the following for information:

Visual C++ page 3-33 Visual Basic for Windows page 3-37

2-5

For Visual C++ only, the Function Call Driver provides the

K_GetErrMsg function, which gets the address of the string

corresponding to an error code.

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

Note:

operating parameters. For board-speciﬁc information, such as voltage input ranges, refer to your board’s user’s guide and External DAS Driver user’s guide.

Operation Modes

The operation mode determines which attributes you can specify for an analog input operation and how data is transferred from the board to computer memory . You can perform analog input operations in one of the following modes:

●

– Conversion mode – Clock source – Buffering mode – Trigger source

The DASDLL-supported boards vary in their features and

Single mode - In single mode, the board acquires a single sample

from an analog input channel. The driver initiates the conversion; you cannot perform any other operation until the single-mode operation is complete.

2-6 Available Operations

Use the K_ADRead function to start an analog input operation in single mode. You specify the board 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.

Synchronous mode - In synchronous mode, the board acquires a

●

single sample or multiple samples from one or more analog input channels. A hardware pacer clock initiates conversions. You cannot perform any other operation until the synchronous-mode operation is complete. After the driver transfers the speciﬁed number of samples to the host, the driver returns control to the application program, which reads the data.

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

Interrupt mode - In interrupt mode, the board 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.

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-14 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.

●

DMA mode - In DMA mode, the board acquires a single sample or

multiple samples from one or more analog input channels. A hardware clock initiates conv ersions. Once the analog input operation begins, control returns to your application program. DMA mode provides the fastest data transfer rates.

Use the K_DMAStart function to start an analog input operation in DMA mode.

You can specify either single-cycle or continuous buffering mode for DMA-mode operations. Refer to page 2-14 for more information on buffering modes. Use the K_DMAStop function to stop a continuous-mode DMA operation. Use the K_DMAStatus function to determine the current status of a DMA operation.

2-7

The converted data is stored as counts. For information on converting counts to voltage, refer to Appendix B.

Memory Allocation and Management

Interrupt-mode and DMA-mode analog input operations use one or two memory buffers to store acquired data; synchronous-mode analog input operations use one memory buffer to store acquired data. (You can use two memory buffers if your External DAS Driver supports double buffering; the dri ver automatically switches from the primary b uffer to the secondary buffer when the primary buffer is full.)

Note:

Except for DASDLL-40 Series boards, it is recommended that you always use a single memory buffer, particularly for analog input operations faster than 1 kHz.

Use one of the following functions to allocate memory:

●

K_SyncAlloc for synchronous-mode or interrupt-mode operations.

●

DASDLL_DMAAlloc for DMA-mode operations.

You specify the following:

●

Operation requiring the memory buffer. Number of samples to store in the memory buffer (up to 32,767).

●

The driver returns the starting address of the memory buffer and a unique identiﬁer for the buffer (this identiﬁer is called the memory handle).

When the memory buffer is no longer required, you can free the b uffer for another use by specifying the memory handle in one of the following functions:

K_SyncFree for synchronous-mode or interrupt-mode operations.

●

DASDLL_DMAFree for DMA-mode operations.

2-8 Available Operations

K_DMAStatus function (for DMA mode). Depending on the speed of

your operation and the particular board you are using, data may be lost when the driver switches from one memory buffer to the other. To determine whether any data has been lost, use the K_IntStatus function (for interrupt mode) or the K_DMAStatus function (for DMA mode).

Notes:

For synchronous-mode and interrupt-mode operations and for DMA-mode operations on DAS-16 Series boards, memory is allocated from the ﬁrst 1MB of DOS memory only; therefore, the amount of memory you can allocate may be limited.

For DAS-20 and DAS-HRES boards that run in DMA mode, it is recommended that you use the Keithley Memory Manager before you begin programming to ensure that you can allocate large enough memory buffers. Refer to Appendix D for more information about the Keithley Memory Manager.

To eliminate page wrap conditions and to guarantee that memory is suitable for use by the computer’s controller, DASDLL_DMAAlloc may allocate an area twice as large as actually needed. Once the data in this buffer is processed and/or saved elsewhere, use DASDLL_DMAFree to free the memory for other uses.

For Visual Basic for Windows, the program cannot transfer data directly from the memory buffer . You must use the K_MoveBufToArray function to move the data from the memory buffer to the program’s local array; refer to page 4-81 for more information.

After you allocate your memory buffers, you must assign the starting address of the buffers and the number of samples to store in the buffers. Each supported programming language requires a particular procedure for allocating a memory buffer and assigning the starting address. Refer to the following for information:

Visual C++ page 3-33 Visual Basic for Windows page 3-37

2-9

Channels and Gains

Analog input channels on DASDLL-supported boards measure signals in several analog input ranges. The analog input range for a particular channel depends on the gain of the channel. The driver uses gain codes to represent the gain.

For example, on a DAS-8PGA analog input board, an analog input range of 0 to 10 V translates to a gain of 1 and a gain code of 9. Refer to Appendix C for a summary of the gain codes used by DASDLLsupported boards.

For most DASDLL-supported boards, channels can be conﬁgured as single-ended or differential. The number of channels supported depends on which conﬁguration you use.

Single Channel

If you require more than the supported number of channels, you can use expansion accessories to increase the number of available channels. Refer to your board’s user’s guide and to the appropriate expansion accessory documentation for more information.

Refer to Appendix C for a summary of the number of channels on DASDLL-supported boards.

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

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, interrupt-mode, and DMA-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.

2-10 Available Operations

Multiple Channels Using a Group of Consecutive Channels

For synchronous-mode, interrupt-mode, and DMA-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.

Use the K_SetG function to specify the gain code for all 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.

Multiple Channels Using a Channel-Gain Queue

For synchronous-mode, interrupt-mode, and DMA-mode analog input operations, you can acquire samples from channels in a 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 a gain code for each channel.

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 required number of samples is read.

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 for information:

Visual C++ page 3-33 Visual Basic for Windows page 3-37

2-11

Pacer Clock

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.

Note: You can use a channel-gain queue with DMA-mode operations on

DAS-20 and DAS-40 Series boards only.

The pacer clock determines the period between the conversion of one channel and the conversion of the next channel. For synchronous-mode, interrupt-mode, and DMA-mode analog input operations, use the K_SetClk function to specify one of the following pacer clocks:

● Internal pacer clock - The internal pacer clock uses an onboard

counter. You load a value into the counter to determine the period between conversions. Depending on the time base of the counter, each count represents a particular time period. T able 2-2 lists the time bases available on DASDLL-supported boards.

Table 2-2. Time Bases

Board Time Base

DAS-8 Depends on PC bus clock frequency DAS-8LT

DAS-8PGA DAS-8PGA-02 DAS-8/AO

DAS-16 Series 1 MHz or 10 MHz DAS-20 5 MHz DAS-40 Series 4 MHz DAS-HRES 1 MHz, 8 MHz, or 10 MHz DDA-06 Not applicable2 Series 500 1 MHz

2-12 Available Operations

1 MHz

Table 2-2. Time Bases (cont.)

Board Time Base

PIO Series Not applicable PDMA Series 10 MHz

Notes

Speciﬁed in the External DAS Driver conﬁguration.

DDA-06 and PIO Series boards do not support an internal

pacer clock.

Use the K_SetClkRate function to specify the number of counts (clock ticks) between conversions. For example, if you are using a DAS-8PGA board (1 MHz time base), each count represents 1.0 µs. If you specify a count of 30, the period between conversions is 30

µs

(33.33 ksamples/s). When using an internal pacer clock, use the following formula to

determine the number of counts to specify:

counts

time base

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

For example, if you want a conversion rate of 10 ksamples/s on a DAS-8PGA board, specify a count of 100, as shown in the following equation:

1 000 000,,

-------------------------- -100=

10 000,

The internal pacer clock is the default pacer clock.

● External pacer clock - You connect an external pacer clock to the

appropriate pin on the main I/O connector. When you start an analog input operation (using K_SyncStart,

K_IntStart, or K_DMAStart), conversions are armed. At the next active edge of the external pacer clock (and at e very subsequent acti ve edge of the external pacer clock), a conversion is initiated.

Refer to your DAS board’s user’s guide to determine which edge (positive or negative) is the active edge supported for your board.

2-13

Notes:

the analog-to-digital converter (ADC) can handle.

The rate at which the computer can reliably read data from the board depends on a number of factors, including your computer, the operating system/environment, the gains of the channels, and other software issues.

Buffering Modes

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

●

Make sure that the pacer clock initiates conversions at a rate that

Single-cycle mode - In single-cycle mode, after the board converts

the speciﬁed number of samples and stores them in the buffer, the operation stops automatically. Single-cycle mode is the default buffering mode.

Continuous mode - In continuous mode, the board 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.

Note:

Buffering modes are not meaningful for synchronous-mode

operations.

Triggers

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

●

Internal trigger - An internal trigger is a softw are trigger . The trigger

event occurs immediately after you start the analog input operation (using K_SyncStart , K_IntStart , or K_DMAStart ). The point at which conversions begin depends on the pacer clock; refer to page 2-12 for more information. The internal trigger is the default trigger source.

2-14 Available Operations

External trigger - When you start the analog input operation (using

●

K_SyncStart , K_IntStart or K_DMAStart ), the application

program waits until an external trigger event occurs. For Series 500 boards, the external trigger is an analog trigger; for DAS-8 Series, DAS-16 Series, D AS-20, D AS-40 Series, and D AS-HRES boards, the external trigger is a digital trigger. The point at which conversions begin depends on the pacer clock; refer to page 2-12 for more information.

Analog Trigger

Note:

DDA-06 and PIO Series boards do not support an external

trigger.

Analog and digital triggers are described in the following sections.

Only Series 500 boards support an external analog trigger. An analog trigger event occurs when a particular condition is met by the analog input signal on a speciﬁed analog trigger channel. Use the K_SetADTrig function to specify the following:

●

Analog input channel to use as the trigger channel.

●

Voltage level. You specify the voltage level as a count value between 0 and 8191, where 0 represents

●

Trigger polarity and sensitivity. Depending on your board, the trigger

−

10 V and 8191 represents +10 V.

event occurs when one of the following conditions is met: – Positive-edge trigger - The analog input signal rises above the

speciﬁed voltage level.

– Negative-edge trigger - The analog input signal falls below the

speciﬁed voltage level.

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

2-15

Level + 5 V

0 V

Digital Trigger

Negative-edge

Positive-edge trigger occurs

trigger occurs

Analog input operation start function is executed

Figure 2-2. Analog Trigger Conditions

DAS-8 Series, DAS-16 Series, DAS-20, DAS-40 Series, and D AS-HRES boards support an external digital trigger. A digital trigger event occurs when a particular condition is met by the digital trigger signal, which is connected to the appropriate pin on the main I/O connector. Depending on your board, the trigger event occurs when one of the following conditions is met:

● Positive-edge trigger - A rising edge occurs on the digital trigger

signal.

● Negative-edge trigger - A falling edge occurs on the digital trigger

signal.

● Positive-level trigger - The digital trigger signal is high.

● Negative-level trigger - The digital trigger signal is low.

Refer to your board’s user’s guide and External DAS Driver user’s guide for information about the digital trigger conditions supported for your board.

2-16 Available Operations

Analog Output Operations

This section describes the following:

● Analog output operation modes available.

● How to allocate and manage memory for analog output operations.

● How to specify the following for an analog output operation:

– Channel – Clock source – Buffering mode – Digital trigger condition

Operation Modes

The operation mode determines which attributes you can specify for an analog output operation. Y ou can perform analog output operations in one of the following modes:

● Single mode - In single mode, the driver writes a single value to an

analog output channel; you cannot perform any other operation until the single-mode operation is complete.

Use the K_DAWrite function to start an analog output operation in single mode. You specify the board you want to use, the analog output channel, and the value you want to write.

● Synchronous mode - In synchronous mode, the driv er writes a single

value or multiple values to an analog output channel. A hardware pacer clock paces the updating of the channel. You cannot perform any other operation until the synchronous-mode operation is complete. After the driver writes the speciﬁed number of values, the driver returns control to the application program.

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

● Interrupt mode - In interrupt mode, the driver writes a single value

or multiple values to an analog output channel. A hardware clock paces the updating of the channel. Once the analog output operation begins, control returns to your application program.

2-17

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

You can specify either single-cycle or continuous buffering mode for interrupt-mode operations. Refer to page 2-23 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.

● DMA mode - In DMA mode, the driver writes a single value or

multiple values to an analog output channel. A hardware clock paces the updating of the channel. Once the analog output operation begins, control returns to your application program. DMA mode provides the fastest data transfer rates.

Use the K_DMAStart function to start an analog output operation in DMA mode.

You can specify either single-cycle or continuous buffering mode for DMA-mode operations. Refer to page 2-23 for more information on buffering modes. Use the K_DMAStop function to stop a continuous-mode DMA operation. Use the K_DMAStatus function to determine the current status of a DMA operation.

For an analog output operation, the values are written as counts. For information on converting voltage to counts, refer to Appendix B.

Memory Allocation and Management

Interrupt-mode and DMA-mode analog output operations use one or two memory buffers to store acquired data; synchronous-mode analog output operations use one memory buffer to store acquired data. (You can use two memory buffers if your External DAS Driver supports double buffering; the dri ver automatically switches from the primary b uffer to the secondary buffer when the primary buffer is empty.)

Note: It is recommended that you always use a single memory buffer,

particularly for analog output operations faster than 1 kHz.

2-18 Available Operations

Use one of the following functions to allocate memory:

● K_SyncAlloc for synchronous-mode or interrupt-mode operations.

● DASDLL_DMAAlloc for DMA-mode operations.

You specify the following:

● Operation requiring the memory buffer.

● Number of samples to store in the memory buffer (up to 32,767).

The driver returns the starting address of the memory buffer and a unique identiﬁer for the buffer (this identiﬁer is called the memory handle).

When the memory buffer is no longer required, you can free the b uffer for another use by specifying the memory handle in one of the following functions:

● K_SyncFree for synchronous-mode or interrupt-mode operations.

● DASDLL_DMAFree for DMA-mode operations.

If you are using two memory buffers, you can w ork on data in the inactiv e buffer while the active buffer continues to collect data. To determine the active buffer, use the K_IntStatus function (for interrupt mode) or the K_DMAStatus function (for DMA mode). Depending on the speed of your operation and the particular board you are using, data may be lost when the driver switches from one memory buffer to the other. To determine whether any data has been lost, use the K_IntStatus function (for interrupt mode) or the K_DMAStatus function (for DMA mode).

If you are using a group of analog output channels, when you start the analog output operation (using K_SyncStart, K_IntStart, or K_DMAStart), the driver simultaneously writes one value to each channel in the group. The driver writes the ﬁrst value in the memory buffer to the ﬁrst channel, the second value in the buffer to the second channel, the third value in the buffer to the third channel, and so on. To ensure predictable results, make sure that the number of values stored in the memory buffer is an even multiple of the number of channels in the group.

2-19

Notes: For synchronous-mode and interrupt-mode operations, memory

is allocated from the ﬁrst 1MB of DOS memory only; therefore, the amount of memory you can allocate may be limited.

For DAS-20 boards that run in DMA mode, it is recommended that you use the Keithley Memory Manager before you begin programming to ensure that you can allocate large enough memory buffers. Refer to Appendix D for more information about the Keithley Memory Manager.

For Visual Basic for Windows, the program cannot transfer data directly to the memory buffer. You must use the K_MoveArrayToBuf function to move the data from the program’s local array to the memory buffer; refer to page 4-79 for more information.

After you allocate your memory buffers, you must assign the starting address of the buffers and the number of samples stored in the buffers. Each supported programming language requires a particular procedure for allocating a buffer. Refer to the following for information:

Visual C++ page 3-30 Visual Basic for Windows page 3-34

Channels

DASDLL-supported boards that perform analog output operations contain one or more digital-to-analog converters (DACs). Each DAC is associated with an analog output channel. You can perform the analog output operation on a single channel or on a group of multiple channels. The following subsections describe how to specify the channels you are using.

2-20 Available Operations

Single Channel

For single-mode analog output operations, you can write a single value to a single analog output channel. Use the K_DAWrite function to specify the channel.

For synchronous-mode, interrupt-mode, and DMA-mode analog output operations, you can write a single value or multiple values to a single analog output channel. Use the K_SetChn function to specify the channel. At each pulse of the pacer clock, the dri v er updates all the analog output channels and then writes a new value to the speciﬁed channel only.

Multiple Channels

For synchronous-mode, interrupt-mode, and DMA-mode analog output operations, you can write a single value or multiple values to a group of consecutive analog output channels. Use the K_SetStartStopChn function to specify the ﬁrst and last channels in the group. At each pulse of the pacer clock, the driver updates all the analog output channels and then writes new values to the channels in the group only.

For example, assume that the start channel is 0, the stop channel is 1, and your array contains two waveforms (0, 4095, 1, 4094, 2, 4093, . . 4095,

0). At the ﬁrst pulse of the pacer clock, the driver updates all the analog output channels and then simultaneously writes 0 to channel 0 and 4095 to channel 1; at the next pulse of the pacer clock, the driver updates all the analog output channels and then simultaneously writes 1 to channel 0 and 4094 to channel 1.

Pacer Clock

The pacer clock determines the period between updates of an analog output channel. For synchronous-mode, interrupt-mode, or DMA-mode analog output operations, use the K_SetClk function to specify one of the following pacer clocks:

● Internal pacer clock - The internal pacer clock uses an onboard

counter. You load a value into the counter to determine the period between updates. Depending on the time base of the counter, each count represents a particular time period. Refer to Table 2-2 on page 2-12 for a list of the time bases available on DASDLL-supported boards.

2-21

Use the K_SetClkRate function to specify the number of counts (clock ticks) between updates. For example, if you are using a DAS-8/AO board (1 MHz time base), each count represents 1.0 µs. If you specify a count of 30, the period between updates is 30

µs

(33.33 ksamples/s). When using an internal pacer clock, use the following formula to

determine the number of counts to specify:

counts

time base

--------------------------= update rate

For example, if you want an update rate of 10 ksamples/s on a DAS-8/AO board, specify a count of 100, as shown in the following equation:

1 000 000,,

-------------------------- -100=

10 000,

The internal pacer clock is the default pacer clock.

● External pacer clock - You connect an external pacer clock to the

appropriate pin on the main I/O connector. When you start an analog output operation (using K_SyncStart,

K_IntStart, or K_DMAStart), conversions are armed. At the next active edge of the external pacer clock (and at e very subsequent acti ve edge of the external pacer clock), the analog output channel is updated.

Refer to your DAS board’s user’s guide to determine which edge (positive or negative) is the active edge supported for your board.

2-22 Available Operations

Notes: At each pulse of the pacer clock, the driver updates all the analog

output channels on the board and then writes new values to the channels speciﬁed in K_SetChn or K_SetStartStopChn only.

You cannot use the internal pacer clock or the external pacer clock for analog output operations if the clock is being used by another operation.

The actual update rate also depends on other factors, including your computer, the operating system/environment, and other software issues.

Buffering Modes

The buffering mode determines how the driver writes the values in the host buffer to the analog output channel. For interrupt-mode and DMA-mode analog output operations, you can specify one of the following buffering modes:

● Single-cycle mode - In single-cycle mode, after the driver writes the

● Continuous mode - In continuous mode, the driver continuously

values stored in the buffer, the operation stops automatically. Single-cycle mode is the default buffering mode.

writes values from the buffer until the application program issues a stop function; when all the values in the buffer have been written, the driver writes the values again. Use the K_SetContRun function to specify continuous buffering mode.

Note: Buffering modes are not meaningful for synchronous-mode

operations.

2-23

Triggers

A trigger is an event that occurs based on a speciﬁed set of conditions. For synchronous-mode, interrupt-mode, and DMA-mode analog output 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 immediately after you start the analog output operation (using K_SyncStart, K_IntStart, or K_DMAStart). The point at which the channel is updated depends on the pacer clock; refer to page 2-21 for more information. The internal trigger is the default trigger source.

● External trigger - DAS-8/AO, DAS-16 Series, DAS-20, DAS-40

Series, and DAS-HRES boards support an external trigger. An external trigger is a digital trigger signal connected to the appropriate pin on the main I/O connector. When you start the analog output operation (using K_SyncStart, K_IntStart, or K_DMAStart), the application program waits until the trigger event occurs. Depending on your board, the trigger event occurs when one of the following conditions is met:

– Positive-edge trigger - A rising edge occurs on the digital trigger

signal.

– Negative-edge trigger - A falling edge occurs on the digital

trigger signal.

– Positive-level trigger - The digital trigger signal is high. – Negative-level trigger - The digital trigger signal is low.

Refer to your board’s user’s guide and External DAS Driver user’s guide for information about the digital trigger conditions supported for your board.

The point at which updates begin depends on the pacer clock; refer to page 2-21 for more information.

2-24 Available Operations

Digital I/O Operations

This section describes the following:

● Digital I/O operation modes available.

● How to allocate and manage memory for digital I/O operations.

● Digital I/O channels.

● How to specify the following for a digital I/O operation:

– Clock source – Buffering mode – Digital trigger condition

Operation Modes

The operation mode determines which attributes you can specify for a digital I/O operation. Y ou can perform digital I/O operations in one of the following modes:

● Single mode - In a single-mode digital input operation, the driver

reads the value of a digital input channel once; in a single-mode digital output operation, the driver writes a value to a digital output channel once. You cannot perform any other operation until the single-mode operation is complete.

Use the K_DIRead function to start a digital input operation in single mode; you specify the board you want to use, the digital input channel, and the variable in which to store the value. Use the K_DOWrite function to start a digital output operation in single mode; you specify the board you want to use, the digital output channel, and the digital output value.

2-25

● Synchronous mode - In a synchronous-mode digital input operation,

the driver reads the v alue of a digital input channel multiple times; in a synchronous-mode digital output operation, the driver writes a single value or multiple values to a digital output channel multiple times. A hardware pacer clock paces the digital I/O operation. You cannot perform any other operation until the synchronous-mode operation is complete.

Use the K_SyncStart function to start a digital I/O operation in synchronous mode.

● Interrupt mode - In an interrupt-mode digital input operation, the

driver reads the value of a digital input channel multiple times; in an interrupt-mode digital output operation, the driver writes a single value or multiple values to a digital output channel multiple times.

A hardware clock paces the digital I/O operation. Once the digital I/O operation begins, control returns to your application program.

Use the K_IntStart function to start a digital I/O operation in interrupt mode.

You can specify either single-cycle or continuous buffering mode for interrupt-mode operations. Refer to page 2-31 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.

● DMA mode - In a DMA-mode digital input operation, the driver

reads the value of a digital input channel multiple times; in a DMA-mode digital output operation, the driver writes a single value or multiple values to a digital output channel multiple times.

A hardware clock paces the digital I/O operation. Once the digital I/O operation begins, control returns to your application program. DMA mode provides the fastest data transfer rates.

Use the K_DMAStart function to start a digital I/O operation in DMA mode.

You can specify either single-cycle or continuous buffering mode for DMA-mode operations. Refer to page 2-31 for more information on buffering modes. Use the K_DMAStop function to stop a continuous-mode DMA operation. Use the K_DMAStatus function to determine the current status of a DMA operation.

2-26 Available Operations

Memory Allocation and Management

Interrupt-mode and DMA-mode digital I/O operations use one or two memory buffers to store the data to be read or written; synchronous-mode digital I/O operations use one memory buffer to store the data to be read or written. (You can use two memory buffers if your External D AS Dri ver supports double buffering; the driver automatically switches from the primary buffer to the secondary buffer when the primary buffer is full or empty.)

Note: It is recommended that you always use a single memory buffer,

particularly for digital I/O operations faster than 1 kHz.

Use one of the following functions to allocate memory:

● K_SyncAlloc for synchronous-mode or interrupt-mode operations.

● DASDLL_DMAAlloc for DMA-mode operations.

You specify the following:

● Operation requiring the memory buffer.

● Number of samples to store in the memory buffer (up to 32,767).

The driver returns the starting address of the memory buffer and a unique identiﬁer for the buffer (this identiﬁer is called the memory handle).

When the memory buffer is no longer required, you can free the b uffer for another use by specifying the memory handle in one of the following functions:

● K_SyncFree for synchronous-mode or interrupt-mode operations.

● DASDLL_DMAFree for DMA-mode operations.

2-27

Notes: For synchronous-mode and interrupt-mode operations, memory

is allocated from the ﬁrst 1MB of DOS memory only; therefore, the amount of memory you can allocate may be limited.

For Visual Basic for Windows, the data in the memory buffer is not directly accessible by your program. For digital input operations, you must use the K_MoveBufToArray function to move the data from the memory buffer to the program’s local array; refer to page 4-81 for more information. For digital output operations, you must use the K_MoveArrayToBuf function to move the data from the program’s local array to the memory buffer; refer to page 4-79 for more information.

Visual C++ page 3-30 Visual Basic for Windows page 3-34

Channels

You can read values from or write values to one or more of the digital I/O lines on your board. Refer to your board’s user’s guide and External DAS Driver user’s guide for information about the number of digital I/O lines available on your board.

For Series 500 boards, the DASDLL Function Call Driver treats each 8-bit digital input port or 8-bit digital output port as a separate channel.

2-28 Available Operations

For DAS-8 Series, DAS-16 Series, DAS-20, DAS-40 Series, D AS-HRES, DDA-06, PIO Series, and PDMA Series boards, the DASDLL Function Call Driver supports one digital input channel and one digital output channel. When specifying your digital I/O ports in the External DAS Driver conﬁguration, you must make sure that all the digital I/O lines can be accommodated on a single channel. For example, if you want to use all 24 bits on a PIO-12 board for digital output, you must conﬁgure a single 24-bit channel. You cannot conﬁgure three 8-bit channels.

For single-mode digital I/O operations, use the K_DIRead function to specify a single digital input channel; use K_DOWrite to specify a single digital output channel. For synchronous-mode, interrupt-mode, and DMA-mode digital I/O operations, use the K_SetChn function to specify a single digital I/O channel or the K_SetStartStopChn function to specify multiple digital I/O channels.

Each bit in a digital I/O channel corresponds to one of the digital I/O lines on the board. The bits can be conﬁgured as digital inputs or digital outputs. A value of 1 in a bit position indicates that the input or output is high; a value of 0 in a bit position indicates that the input or output is low. If no signal is connected to a digital input line, the input appears high (value is 1).

Notes: On some DASDLL-supported boards, a digital I/O line may also

be used for another purpose, such as an external trigger. In these cases, you cannot use the digital I/O line for general-purpose digital I/O operations.

2-29

Pacer Clock

The pacer clock determines the period between reading the digital input channel or writing to the digital output channel. For synchronous-mode, interrupt-mode, and DMA-mode digital I/O operations, use the K_SetClk function to specify one of the following pacer clocks:

● Internal pacer clock - The internal pacer clock uses an onboard

counter. You load a value into the counter to determine the period between reads/writes. Depending on the time base of the counter, each count represents a particular time period. Refer to Table 2-2 on page 2-12 for a list of the time bases available on D ASDLL-supported boards.

Use the K_SetClkRate function to specify the number of counts (clock ticks) between reads/writes. For example, if you are using a DAS-8PGA board (1 MHz time base), each count represents 1.0 µs. If you specify a count of 30, the period between reads/writes is 30

µs

(33.33 ksamples/s). When using an internal pacer clock, use the following formula to

determine the number of counts to specify:

counts

time base

----------------------------------= read/write rate

For example, if you want a read/write rate of 10 ksamples/s on a DAS-8/AO board, specify a count of 100, as shown in the following equation:

1 000 000,,

-------------------------- -100=

10 000,

The internal pacer clock is the default pacer clock.

● External pacer clock - You connect an external pacer clock to the

appropriate pin on the main I/O connector. When you start a digital I/O operation (using K_SyncStart,

K_IntStart, or K_DMAStart), conversions are armed. At the next active edge of the external pacer clock (and at e very subsequent acti ve edge of the external pacer clock), a conversion is initiated. Refer to your board’s user’s guide to determine which edge (positive or negative) is the active edge supported for your board.

2-30 Available Operations

Notes: You cannot use the internal pacer clock or the external pacer

clock for digital I/O operations if the clock is being used by another operation.

The actual read/write rate also depends on other factors, including your computer, the operating system/environment, and other software issues.

Buffering Modes

The buffering mode determines how the driver reads or writes the values in the buffer. For interrupt-mode and DMA-mode digital I/O operations, you can specify one of the following buffering modes:

● Single-cycle mode - In a single-cycle-mode digital input operation,

● Continuous mode - In a continuous-mode digital input operation, the

after the driver ﬁlls the buffer, the operation stops automatically. In a single-cycle-mode digital output operation, after the driver writes the values stored in the buffer, the operation stops automatically. Single-cycle mode is the default buffering mode.

driver continuously reads a digital input channel and stores the v alues in the buffer until the application program issues a stop function; any values already stored in the buffer are overwritten. In a continuous mode digital output operation, the driver continuously writes values from the buffer to a digital output channel until the application program issues a stop function; when all the values in the buf fer have been written, the driver writes the values again. You use the K_SetContRun function to specify continuous buffering mode.

Note: Buffering modes are not meaningful for synchronous-mode

operations.

2-31

Triggers

A trigger is an event that occurs based on a speciﬁed set of conditions. For synchronous-mode and interrupt-mode digital I/O 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 immediately after you start the digital I/O operation (using K_SyncStart or K_IntStart). The point at which a value is read or written depends on the pacer clock; refer to page 2-30 for more information. The internal trigger is the default trigger source.

● External trigger - DAS-8 Series, DAS-16 Series, DAS-20, and

DAS-HRES boards support an external trigger. An external trigger is a digital trigger signal connected to the appropriate pin on the main I/O connector. When you start the digital I/O (using K_SyncStart, K_IntStart, or K_DMAStart), the application program waits until the trigger event occurs. Depending on your board, the trigger event occurs when one of the following conditions is met:

– Positive-edge trigger - A rising edge occurs on the digital trigger

signal.

– Negative-edge trigger - A falling edge occurs on the digital

trigger signal.

– Positive-level trigger - The digital trigger signal is high. – Negative-level trigger - The digital trigger signal is low.

Refer to your board’s user’s guide and External DAS Driver user’s guide for information about the digital trigger conditions supported for your board.

The point at which updates begin depends on the pacer clock; refer to page 2-30 for more information.

2-32 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

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 .

Single-Mode Function

K_ADRead (

board,

channel, gain, buffer)

Figure 3-1. Single-Mode Function

Attributes of Operation

Board number Analog input channel Gain applied to channel Buffer for data

3-1

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

Frames help you create structured application programs. You set up the attributes of the I/O 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 only available for I/O operations that use frames.

You indicate that you want to perform an I/O 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 I/O 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 I/O operation, you might use the K_SetChn setup function.

For each setup function, the Function Call Driver provides a readback function, which reads the current deﬁnition of a particular element. For example, the K_GetChn readback function reads the channel number speciﬁed for the I/O operation.

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

When you are ready to perform the I/O 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 .

3-2 Programming with the Function Call Driver

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

Different I/O operations require different types of frames. F or example, to perform a digital input operation, you use a digital input frame; to perform an analog output operation, you use an analog output frame.

For DASDLL-supported boards, synchronous-mode, interrupt-mode, and DMA-mode operations require frames. The DASDLL Function Call Driver provides the following types of frames:

●

Analog input frames, called A/D (analog-to-digital) frames. You use the K_GetADFrame function to access an available A/D frame and a frame handle.

●

Analog output frames, called D/A (digital-to-analog) frames. Y ou use the K_GetDAFrame function to access an available D/A frame and a frame handle.

●

Digital input frames, called DI frames. You use the K_GetDIFrame function to access an available DI frame and a frame handle.

●

Digital output frames, called DO frames. You use the

K_GetDOFrame function to access an available DO frame and a

frame handle.

3-3

If you want to perform a synchronous-mode, interrupt-mode, or DMA-mode operation and all frames of a particular type 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.

For DASDLL-supported boards, the elements for each speciﬁc frame type are listed as follows:

●

A/D frame elements - Table 3-1. D/A frame elements - Table 3-2 on page 3-6.

●

DI frame elements - Table 3-3 on page 3-7.

●

DO frame elements - Table 3-4 on page 3-8.

●

These tables also list the default values of each element, the setup functions used to deﬁne each element, and the readback functions used to read the current deﬁnition of the element.

Table 3-1. A/D Frame Elements

Element Default Value Setup Function Readback Function

Buffer

Number of Samples

Buffering Mode Single-cycle K_SetContRun

0 (NULL) K_SetBuf

K_SetBufB K_SetDMABuf K_SetDMABufB

0 K_SetBuf

K_SetBufB K_SetDMABuf K_SetDMABufB

K_ClrContRun

K_GetBuf K_GetBufB

K_GetContRun

Start Channel 0 K_SetChn

K_SetStartStopChn K_SetStartStopG

K_GetChn K_GetStartStopChn K_GetStartStopG

3-4 Programming with the Function Call Driver

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

Element Default Value Setup Function Readback Function

Stop Channel 0 K_SetStartStopChn

K_SetStartStopG

Gain 0 K_SetG

K_SetStartStopG

Channel-Gain

0 (NULL) K_SetChnGAry K_GetChnGAry

K_GetStartStopChn K_GetStartStopG

K_GetG K_GetStartStopG

Queue Clock Source Internal K_SetClk K_GetClk Pacer Clock Rate

0 K_SetClkRate K_GetClkRate Trigger Source Internal K_SetTrig K_GetTrig Trigger Type Digital K_SetADTrig

K_SetDITrig

K_GetADTrig K_GetDITrig

Trigger Channel 0 (for analog trigger) K_SetADTrig K_GetADTrig

0 (for digital trigger) K_SetDITrig K_GetDITrig Trigger Polarity

and Sensitivity

Positive edge (for

analog trigger)

Positive edge (for

K_SetADTrig K_GetADTrig

K_SetDITrig K_GetDITrig

digital trigger) Trigger Level 0 K_SetADTrig K_GetADTrig Trigger

0 K_SetTrigHyst K_GetTrigHyst Hysteresis

Notes

This element must be set.

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. Whene v er you clear a frame or get a ne w frame, this frame element is set to its default value automatically.

3-5

Table 3-2. D/A Frame Elements

Element Default Value Setup Function Readback Function

Buffer

0 (NULL) K_SetBuf

K_SetBufB K_SetDMABuf K_SetDMABufB

K_GetBuf K_GetBufB

Number of Samples 0 K_SetBuf

K_SetBufB

K_GetBuf

K_GetBufB K_SetDMABuf K_SetDMABufB

Buffering Mode Single-cycle K_SetContRun

K_ClrContRun

Start Channel 0 K_SetChn

K_SetStartStopChn

K_GetContRun

K_GetChn

K_GetStartStopChn

Stop Channel 0 K_SetStartStopChn K_GetStartStopChn Clock Source Internal K_SetClk K_GetClk Pacer Clock Rate

0 K_SetClkRate K_GetClkRate Trigger Source Internal K_SetTrig K_GetTrig Trigger Type Digital K_SetDITrig K_GetDITrig Trigger Channel 0 (for digital

K_SetDITrig K_GetDITrig

trigger) Trigger Polarity and

Positive edge K_SetDITrig K_GetDITrig Sensitivity

Notes

This element must be set.

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.

3-6 Programming with the Function Call Driver

Table 3-3. DI Frame Elements

Element Default Value Setup Function Readback Function

Buffer

0 (NULL) K_SetBuf

K_SetBufB K_SetDMABuf K_SetDMABufB

K_GetBuf K_GetBufB

Number of Samples 0 K_SetBuf

K_SetBufB

K_GetBuf

K_GetBufB K_SetDMABuf K_SetDMABufB

Buffering Mode Single-cycle K_SetContRun

K_ClrContRun

Start Channel 0 K_SetChn

K_SetStartStopChn

K_GetContRun

K_GetChn

K_GetStartStopChn

Stop Channel 0 K_SetStartStopChn K_GetStartStopChn Clock Source Internal K_SetClk K_GetClk Pacer Clock Rate

0 K_SetClkRate K_GetClkRate Trigger Source Internal K_SetTrig K_GetTrig Trigger Type Digital K_SetDITrig K_GetDITrig Trigger Channel 0 (for digital

K_SetDITrig K_GetDITrig

trigger) Trigger Polarity and

Positive edge K_SetDITrig K_GetDITrig Sensitivity

Notes

This element must be set.

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.

3-7

Table 3-4. DO Frame Elements

Element Default Value Setup Function Readback Function

Buffer

0 (NULL) K_SetBuf

K_SetBufB K_SetDMABuf K_SetDMABufB

K_GetBuf K_GetBufB

Number of Samples 0 K_SetBuf

K_GetBuf K_SetBufB K_SetDMABuf K_SetDMABufB

Buffering Mode Single-cycle K_SetContRun

K_ClrContRun

Start Channel 0 K_SetChn

K_SetStartStopChn

K_GetContRun

K_GetChn

K_GetStartStopChn

Stop Channel 0 K_SetStartStopChn K_GetStartStopChn Clock Source Internal K_SetClk K_GetClk Pacer Clock Rate

0 K_SetClkRate K_GetClkRate Trigger Source Internal K_SetTrig K_GetTrig Trigger Type Digital K_SetDITrig K_GetDITrig Trigger Polarity and

Positive edge K_SetDITrig K_GetDITrig Sensitivity

Notes

This element must be set.

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.

Note:

The DASDLL Function Call Dri ver pro vides man y 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, and miscellaneous functions.

3-8 Programming with the Function Call Driver

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.

Programming Overview

T o write an application program using the D ASDLL Function Call Driv er , perform the following steps:

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

description of the board 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, describes the programming

tasks that are common to all application programs.

– Operation-Speciﬁc Programming Tasks, on page 3-10, describes

operation-speciﬁc programming tasks and the sequence in which

these tasks must be performed. – Chapter 4 contains detailed descriptions of the FCD functions. – The DASDLL software package contains several example

programs. The FILES.TXT ﬁle in the installation directory lists

and describes the example programs.

3. Compile and link the program. Refer to Language-Specific Programming Information, starting on page 3-29, for compile and link statements and other language-specific considerations for each supported language.

3-9

Preliminary Tasks

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. This ﬁle is included in the DASDLL software package.

2. Declare and initialize program variables.

3. Use the K_DevOpen function to initialize the driver.

4. Use the K_GetDevHandle function to specify the board you want to use and to initialize the board. If you are using more than one board, use the K_GetDevHandle function once for each board you are using.

Operation-Speciﬁc Programming Tasks

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

Note:

operation-speciﬁc programming tasks can be used at any point in your application program.

Analog Input Operations

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

Any FCD functions that are not mentioned in the

3-10 Programming with the Function Call Driver

Single Mode

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

2. Use the K_ADRead function to read the single analog input value;

Synchronous Mode

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

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

value.

specify the attributes of the operation as arguments to the function.

2. Use the K_SyncAlloc function to allocate the buffers in which to store the acquired data.

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-11 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-5.

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-11

Table 3-5. Setup Functions for Synchronous-Mode

Analog Input Operations

Attribute Setup Functions

Buffer

Number of Samples K_SetBuf

Start Channel K_SetChn

Stop Channel K_SetStartStopChn

K_SetBuf K_SetBufB

K_SetBufB

K_SetStartStopChn K_StartStopG

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

K_SetDITrig

Trigger Polarity and Sensitivity

K_SetADTrig

K_SetDITrig Trigger Level K_SetADTrig Trigger Hysteresis K_SetTrigHyst

Notes

This element must be set.

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

3-12 Programming with the Function Call Driver

Interrupt Mode

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

6. If you are programming in Visual Basic for Windows , use the

K_MoveBufToArray function to transfer the acquired data from the

allocated buffer to the program’s local array.

7. Use the K_SyncFree function to deallocate the buffers.

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

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

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

2. Use the K_SyncAlloc function to allocate the buffers in which to store the acquired data.

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-11 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-6.

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.

3-13

Table 3-6. Setup Functions for Interrupt-Mode

Analog Input Operations

Attribute Setup Functions

Buffer

Number of Samples K_SetBuf

K_SetBuf K_SetBufB

K_SetBufB

Buffering Mode K_SetContRun

K_ClrContRun

Start Channel K_SetChn

K_SetStartStopChn K_StartStopG

Stop Channel K_SetStartStopChn

K_SetStartStopG

Gain K_SetG

K_SetStartStop 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

K_SetDITrig Trigger Polarity and

Sensitivity

K_SetADTrig

K_SetDITrig Trigger Level K_SetADTrig Trigger Hysteresis K_SetTrigHyst

Notes

This element must be set.

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.

3-14 Programming with the Function Call Driver

DMA Mode

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, use the

K_MoveBufToArray function to transfer the acquired data from the allocated buffer to the program’s local array.

9. Use the K_SyncFree function to deallocate the buffers.

10. Use the K_FreeFrame function to return the frame you accessed in

step 1 to the pool of available frames.

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

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

2. Use the DASDLL_DMAAlloc function to allocate the buffers in

which to store the acquired data.

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

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

3-15

Table 3-7. Setup Functions for DMA-Mode

Analog Input Operations

Attribute Setup Functions

Buffer

Number of Samples K_SetDMABuf

K_SetDMABuf K_SetDMABufB

K_SetDMABufB

Buffering Mode K_SetContRun

K_ClrContRun

Start Channel K_SetChn

K_SetStartStopChn K_StartStopG

Stop Channel K_SetStartStopChn

K_SetStartStopG

Gain K_SetG

K_SetStartStopG Clock Source K_SetClk Pacer Clock Rate

K_SetClkRate Trigger Source K_SetTrig Trigger Type K_SetADTrig

K_SetDITrig Trigger Channel K_SetADTrig

K_SetDITrig Trigger Polarity and

Sensitivity

K_SetADTrig

K_SetDITrig Trigger Level K_SetADTrig Trigger Hysteresis K_SetTrigHyst

Notes

This element must be set.

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.

3-16 Programming with the Function Call Driver

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

4. Use the K_DMAStart function to start the DMA-mode operation.

5. Use the K_DMAStatus function to monitor the status of the

DMA-mode operation.

6. If you speciﬁed continuous buffering mode, use the K_DMAStop

function to stop the DMA-mode operation when the appropriate number of samples has been acquired.

7. If you are programming in Visual Basic for Windows, use the

K_MoveBufToArray function to transfer the acquired data from the allocated buffer to the program’s local array.

8. Use the DASDLL_DMAFree function to deallocate the buffers.

9. Use the K_FreeFrame function to return the frame you accessed in

step 1 to the pool of available frames.

Analog Output Operations

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

Single Mode

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

1. Declare the buffer or variable in which to store the single analog output value.

2. Use the K_DAWrite function to write the single analog output value; specify the attributes of the operation as arguments to the function.

3-17

Synchronous Mode

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

1. Use the K_GetDAFrame function to access a D/A frame.

2. Use the K_SyncAlloc function to allocate the buffers in which to

3. Use the appropriate setup functions to specify the attributes of the

store the data to be written.

operation. The setup functions are listed in Table 3-8.

Note: When you access a new D/A 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-2 on page 3-6 for a list of the default values of D/A frame elements.

Table 3-8. Setup Functions for Synchronous-Mode

Analog Output Operations

Attribute Setup Functions

Buffer

K_SetBuf K_SetBufB

Number of Samples K_SetBuf

K_SetBufB

Start Channel K_SetChn

K_SetStartStopChn Stop Channel K_SetStartStopChn Clock Source K_SetClk Pacer Clock Rate Trigger Source K_SetTrig

3-18 Programming with the Function Call Driver

K_SetClkRate

Table 3-8. Setup Functions for Synchronous-Mode

Analog Output Operations (cont.)

Attribute Setup Functions

Trigger Type K_SetDITrig Trigger Channel K_SetDITrig

Interrupt Mode

Trigger Polarity and Sensitivity

Notes

This element must be set.

K_SetDITrig

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

4. If you are programming in Visual Basic for Windows, use the

K_MoveArrayToBuf function to transfer the data from the program’s local array to the allocated buffer.

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

operation.

6. Use the K_SyncFree function to deallocate the buffer.

7. Use the K_FreeFrame function to return the frame you accessed in

step 1 to the pool of available frames.

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

1. Use the K_GetDAFrame function to access a D/A frame.

2. Use the K_SyncAlloc function to allocate the buffers in which to

store the data to be written.

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

3-19

Note: When you access a new D/A 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-2 on page 3-6 for a list of the default values of D/A frame elements.

Table 3-9. Setup Functions for Interrupt-Mode

Analog Output Operations

Attribute Setup Functions

Buffer

Number of Samples K_SetBuf

K_SetBuf K_SetBufB

K_SetBufB

Buffering Mode K_SetContRun

K_ClrContRun

Start Channel K_SetChn

K_SetStartStopChn Stop Channel K_SetStartStopChn Clock Source K_SetClk Pacer Clock Rate

K_SetClkRate Trigger Source K_SetTrig Trigger Type K_SetDITrig Trigger Channel K_SetDITrig Trigger Polarity and

K_SetDITrig Sensitivity

Notes

This element must be set.

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.

3-20 Programming with the Function Call Driver

DMA Mode

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

4. If you are programming in Visual Basic for Windows, use the

K_MoveArrayToBuf function to transfer the data from the program’s local array to the allocated buffer.

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 written.

8. Use the K_SyncFree function to deallocate the buffers.

9. Use the K_FreeFrame function to return the frame you accessed in

step 1 to the pool of available frames.

For a DMA-mode analog output operation, perform the following tasks:

1. Use the K_GetDAFrame function to access a D/A frame.

2. Use the DASDLL_DMAAlloc function to allocate the buffers in

which to store the data to be written.

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

Note: When you access a new D/A 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-2 on page 3-6 for a list of the default values of D/A frame elements.

3-21

Table 3-10. Setup Functions for DMA-Mode

Analog Output Operations

Attribute Setup Functions

Buffer

Number of Samples K_SetDMABuf

Buffering Mode K_SetContRun

Start Channel K_SetChn

Stop Channel K_SetStartStopChn Clock Source K_SetClk Pacer Clock Rate Trigger Source K_SetTrig Trigger Type K_SetDITrig Trigger Channel K_SetDITrig

K_SetDMABuf K_SetDMABufB

K_SetDMABufB

K_ClrContRun2

K_SetStartStopChn

K_SetClkRate

Trigger Polarity and Sensitivity

Notes

This element must be set.

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.

K_SetDITrig

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

4. If you are programming in Visual Basic for Windows, use the K_MoveArrayToBuf function to transfer the data from the program’s local array to the allocated buffer.

5. Use the K_DMAStart function to start the DMA-mode operation.

3-22 Programming with the Function Call Driver

6. Use the K_DMAStatus function to monitor the status of the DMA-mode operation.

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

8. Use the DASDLL_DMAFree function to deallocate the buffers.

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

Digital I/O Operations

The following subsections describe the operation-speciﬁc programming tasks required to perform single-mode, synchronous-mode, interrupt-mode, and DMA-mode digital I/O operations.

Single Mode

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 K_DOWrite

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

3-23

Synchronous Mode

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

1. Use the K_GetDIFrame function to access a DI frame; use the

2. Use the K_SyncAlloc function to allocate the buffers in which to

3. Use the appropriate setup functions to specify the attributes of the

K_GetDOFrame function to access a DO frame.

store the data to be read or written.

operation. The setup functions are listed in Table 3-7.

Note: When you access a new DI or DO 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-3 on page 3-7 for a list of the default values of DI frame elements. Refer to Table 3-4 on page 3-8 for a list of the default values of DO frame elements.

Table 3-11. Setup Functions for Synchronous-Mode

Digital Input and Output Operations

Attribute Setup Functions

Buffer

Number of Samples K_SetBuf

Start Channel K_SetChn

Stop Channel K_SetStartStopChn Clock Source K_SetClk Pacer Clock Rate Trigger Source K_SetTrig Trigger Type K_SetDITrig

3-24 Programming with the Function Call Driver

K_SetBuf K_SetBufB

K_SetBufB

K_SetStartStopChn

K_SetClkRate

Table 3-11. Setup Functions for Synchronous-Mode

Digital Input and Output Operations (cont.)

Attribute Setup Functions

Trigger Channel K_SetDITrig Trigger Polarity and

Sensitivity

Notes

This element must be set.

K_SetDITrig

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

4. If you are performing a digital output operation and you are programming in Visual Basic for Windows, use the K_MoveArrayToBuf function to transfer the data from the program’s local array to the allocated buffer.

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

6. If you are performing a digital input operation and you are programming in Visual Basic for Windows, use the K_MoveBufToArray function to transfer the data from the allocated buffer to the program’s local array.

7. Use the K_SyncFree function to deallocate the buffers.

Interrupt Mode

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

For an interrupt-mode digital I/O operation, perform the following tasks:

1. Use the K_GetDIFrame function to access a DI frame; use the K_GetDOFrame function to access a DO frame.

2. Use the K_SyncAlloc function to allocate the buffers in which to store the data to be read or written.

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

3-25

Note: When you access a new DI or DO 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-3 on page 3-7 for a list of the default values of DI frame elements. Refer to Table 3-4 on page 3-8 for a list of the default values of DO frame elements.

Table 3-12. Setup Functions for Interrupt-Mode

Digital Input and Digital Output Operations

Attribute Setup Functions

Buffer

Number of Samples K_SetBuf

K_SetBuf K_SetBufB

K_SetBufB

Buffering Mode K_SetContRun

K_ClrContRun

Start Channel K_SetChn

K_SetStartStopChn Stop Channel K_SetStartStopChn Pacer Clock Rate

K_SetClkRate Trigger Source K_SetTrig Trigger Type K_SetDITrig Trigger Channel K_SetDITrig Trigger Polarity and

K_SetDITrig Sensitivity

Notes

This element must be set.

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.

3-26 Programming with the Function Call Driver

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 written.

8. If you are performing a digital input operation and you are programming in Visual Basic for Windows, use the K_MoveBufToArray function to transfer the data from the allocated buffer to the program’s local array.

9. Use the K_SyncFree function to deallocate the buffers.

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

DMA Mode

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

1. Use the K_GetDIFrame function to access a DI frame; use the K_GetDOFrame function to access a DO frame.

2. Use the DASDLL_DMAAlloc function to allocate the buffers in which to store the data to be read or written.

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

3-27

Note: When you access a new DI or DO 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-3 on page 3-7 for a list of the default values of DI frame elements. Refer to Table 3-4 on page 3-8 for a list of the default values of DO frame elements.

Table 3-13. Setup Functions for DMA-Mode

Digital Input and Digital Output Operations

Attribute Setup Functions

Buffer

Number of Samples K_SetDMABuf

K_SetDMABuf K_SetDMABufB

K_SetDMABufB

Buffering Mode K_SetContRun

K_ClrContRun

Start Channel K_SetChn

K_SetStartStopChn Stop Channel K_SetStartStopChn Pacer Clock Rate

K_SetClkRate Trigger Source K_SetTrig Trigger Type K_SetDITrig Trigger Channel K_SetDITrig Trigger Polarity and

K_SetDITrig Sensitivity

Notes

This element must be set.

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.

3-28 Programming with the Function Call Driver

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_DMAStart function to start the DMA-mode operation.

6. Use the K_DMAStatus function to monitor the status of the DMA-mode operation.

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

9. Use the DASDLL_DMAFree function to deallocate the buffers.

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

Language-Speciﬁc Programming Information

This section provides programming information for each of the supported languages. Note that the compilation procedures for each language assumes that the paths and/or environment variables are set correctly.

Microsoft Visual C++ Language

The following sections contain information you need to allocate and assign memory buffers and to create a channel-gain queue when programming in Microsoft Visual C++, as well as language-speciﬁc information for Microsoft Visual C++.

3-29

Note: When programming in Microsoft Visual C++, proper typecasting

may be required to avoid C++ type-mismatch warnings.

Allocating and Assigning Memory Buffers

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

Note: The code fragments assume that you are using DMA mode; the

code for synchronous-mode and interrupt mode is identical, except that you use the appropriate synchronous-mode or interrupt-mode functions instead of the DMA-mode functions.

Allocating the Memory Buffers

You can use a single memory buffer or two memory buffers for synchronous-mode, interrupt-mode, and DMA-mode analog I/O and digital I/O operations.

The following code fragment illustrates how to use DASDLL_DMAAlloc to allocate two buffers of size Samples for the frame deﬁned by hFrame and how to use K_SetDMABuf and K_SetDMABufB to assign the starting addresses of the buffers.

. . . void far *AcqBufA; //Declare pointer to first buffer void far *AcqBufB; //Declare pointer to second buffer WORD hMemA; //Declare word for first memory handle WORD hMemB; //Declare word for second memory handle . . . wDasErr = DASDLL_DMAAlloc (hFrame, Samples, &AcqBufA, &hMemA); wDasErr = K_SetDMABuf (hFrame, AcqBufA, Samples); wDasErr = DASDLL_DMAAlloc (hFrame, Samples, &AcqBufB, &hMemB); wDasErr = K_SetDMABufB (hFrame, AcqBufB, Samples); . . .

3-30 Programming with the Function Call Driver

The following code illustrates how to use DASDLL_DMAFree to later free the allocated buffers, using the memory handles stored by DASDLL_DMAAlloc.

. . . wDasErr = DASDLL_DMAFree (hMemA); wDasErr = DASDLL_DMAFree (hMemB); . . .

Accessing the Data

You access the data stored in an allocated buffer through pointer indirection. For example, assume that you want to display the ﬁrst 10 samples of the ﬁrst buffer described in the previous section (AcqBufA). The following code fragment illustrates how to access and display the data.

. . . int far *pData; //Declare a pointer called pData . . . pData = (int far *) AcqBufA; //Assign pData to 1st buffer for (i = 0; i < 10; i++)

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

. . .

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;

3-31

The following example illustrates how to create a channel-gain queue called MyChanGainQueue for a DAS-40G2 board 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, K_IntStart, or K_DMAStart), 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.

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 ((DASErr = K_GetDevHandle (hDrv, BoardNum, &hDev))! = 0)

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

. . .

3-32 Programming with the Function Call Driver

Programming in Microsoft Visual C++

To program in Microsoft Visual C++, you need the following ﬁles; these ﬁles are provided in the DASDLL software package.

File Description

DASSHELL.DLL Dynamic Link Library DASSUPRT.DLL Dynamic Link Library DASDLL.DLL Dynamic Link Library DASDECL.H Include ﬁle for C DASDLL.H Include ﬁle for C DASDECL.HPP Include ﬁle for C++ DASDLL.HPP Include ﬁle for C++ DASIMP.LIB DAS Shell Imports DASDLL.LIB DASDLL Imports

To create an executable ﬁle in Visual C++, perform the following steps:

1. Create a project ﬁle by choosing New from the Project menu. The project ﬁle should contain all necessary ﬁles, including ﬁlename.c,

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

2. 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-33

Microsoft Visual Basic for Windows

The following sections contain information you need to allocate and assign memory buffers and to create a channel-gain queue when programming in Microsoft Visual Basic for Windows, as well as language-speciﬁc information for Microsoft Visual Basic for Windows.

Allocating and Assigning Memory Buffers

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

Note: The code fragments assume that you are using DMA mode; the

code for synchronous-mode and interrupt mode is identical, except that you use the appropriate synchronous-mode or interrupt-mode functions instead of the DMA-mode functions.

Allocating the Memory Buffers

You can use a single memory buffer or two memory buffers for synchronous-mode, interrupt-mode, and DMA-mode analog I/O and digital I/O operations.

. . . Global AcqBufA As Long ’ Declare pointer to first buffer Global AcqBufB As Long ’ Declare pointer to second buffer Global hMemA As Integer ’ Declare integer for first memory handle Global hMemB As Integer ’ Declare integer for second memory handle . . . wDasErr = DASDLL_DMAAlloc (hFrame, Samples, AcqBufA, hMemA) wDasErr = K_SetDMABuf (hFrame, AcqBufA, Samples) wDasErr = DASDLL_DMAAlloc (hFrame, Samples, AcqBufB, hMemB) wDasErr = K_SetDMABuf (hFrame, AcqBufB, Samples) . . .

3-34 Programming with the Function Call Driver

The following code illustrates how to use DASDLL_DMAFree to later free the allocated buffers, using the memory handles stored by DASDLL_DMAAlloc.

. . . wDasErr = DASDLL_DMAFree (hMemA) wDasErr = DASDLL_DMAFree (hMemB) . . .

Accessing the Data

In Microsoft Visual Basic for Windows, you cannot directly access samples stored in an allocated memory buffer. For analog input operations, you must use K_MoveBufToArray to move a subset of the data into the program’s local array as required. The following code fragment illustrates how to move the ﬁrst 100 samples of the ﬁrst buffer described in the previous section (AcqBufA) to the program’s local array.

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

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 DASDLL Function Call Driver.

3-35

The following code fragment illustrates how to create a four-entry channel-gain queue called MyChanGainQueue for a DAS-16G2 board 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 ’Maximum # of entries . . . 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 the channel-gain queue is formatted, your Visual Basic for Windo ws program can no longer read it. To read or modify the array after it has been formatted, you must use K_RestoreChnGAry as follows:

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

When you start the next analog input operation (using K_SyncStart, K_IntStart, or K_DMAStart), 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.

3-36 Programming with the Function Call Driver

Handling Errors

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

MsgBox “K_GetDevHandle Error: “ + Hex$ (DASErr),

MB_ICONSTOP, “DASDLL 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 D ASDLL software package.

File Description

DASSHELL.DLL Dynamic Link Library DASSUPRT.DLL Dynamic Link Library DASDLL.DLL Dynamic Link Library DASDECL.BAS Include ﬁle; must be added to the Project List DASDLL.BAS Include ﬁle; must be added to the Project List

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

3-37

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

●

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 K_OpenDriver page 4-83

K_CloseDriver page 4-18 DASDLL_DevOpen page 4-7 K_GetDevHandle page 4-54 K_FreeDevHandle page 4-35 DASDLL_GetDevHandle page 4-13 DASDLL_GetBoardName page 4-12 K_DASDevInit page 4-21

Operation K_ADRead page 4-15

K_DAWrite page 4-22 K_DIRead page 4-24 K_DOWrite page 4-32 K_DMAStart page 4-26 K_DMAStatus page 4-27 K_DMAStop page 4-30 K_IntStart page 4-73 K_IntStatus page 4-74 K_IntStop page 4-77 K_SyncStart page 4-115

Frame Management K_GetADFrame page 4-37

K_GetDAFrame page 4-52 K_GetDIFrame page 4-56 K_GetDOFrame page 4-58 K_FreeFrame page 4-36 K_ClearFrame page 4-17

4-2 Function Reference

Table 4-1. Functions (cont.)

Function Type Function Name Page Number

Memory Management DASDLL_DMAAlloc page 4-9

DASDLL_DMAFree page 4-11 K_SyncAlloc page 4-112 K_SyncFree page 4-114 K_MoveArrayToBuf page 4-79 K_MoveBufToArray page 4-81

Buffer Address K_SetBuf page 4-88

K_SetBufB page 4-90 K_GetBuf page 4-40 K_GetBufB page 4-42 K_SetDMABuf page 4-101 K_SetDMABufB page 4-103

Buffering Mode K_SetContRun page 4-99

K_ClrContRun page 4-19 K_GetContRun page 4-50

. 4-3

Table 4-1. Functions (cont.)

Function Type Function Name Page Number

Channel and Gain K_SetChn page 4-92

K_SetStartStopChn page 4-106 K_SetG page 4-105 K_SetStartStopG page 4-108 K_SetChnGAry page 4-93 K_FormatChnGAry page 4-34 K_RestoreChnGAry page 4-85 K_GetChn page 4-44 K_GetStartStopChn page 4-65 K_GetG page 4-61 K_GetStartStopG page 4-67 K_GetChnGAry page 4-45

Clock K_SetClk page 4-95

K_SetClkRate page 4-97 K_GetClk page 4-46 K_GetClkRate page 4-48

Trigger K_SetTrig page 4-110

K_SetADTrig page 4-86 K_GetTrig page 4-69 K_GetADTrig page 4-38

Miscellaneous K_GetErrMsg page 4-60

K_GetVer page 4-71 K_GetShellVer page 4-63

4-4 Function Reference

Keep the following conventions in mind throughout this chapter:

If DAS-8 Series, DAS-16 Series, DAS-40 Series, PIO Series, or

●

PDMA Series is listed in the Boards Supported section, all boards in the series are supported. For Series 500, refer to your Series 500 documentation for information on which speciﬁc Series 500 modules are supported for a particular function.

The data types DWORD, WORD, and BYTE are deﬁned in the

●

language-speciﬁc include ﬁles. Variable names are shown in italics.

●

For valid value and value stored information, refer to the board’s user’s guide and the External DAS Driver user’s guide for that board.

●

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

●

they are deﬁned as shown in the syntax. 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-5

Table 4-2. Data Type Preﬁxes

Preﬁx Data Type 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-6 Function Reference

DASDLL_DevOpen

Boards Supported

Purpose

Prototype Visual C++

All

Opens the driver and returns the number of boards found.

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

Visual Basic for Windows

Declare Function DASDLL_DevOpen Lib "DASDLL.DLL" (ByVal szCfgFile As String, pBoards As Integer) As Integer

Parameters

szCfgFile pBoards

Return Value

Remarks

Error/status code. Refer to Appendix A.

This function opens the DASDLL Function Call Driver and stores the number of boards found in pBoards .

The DASDLL Function Call Dri ver does not use a conﬁguration ﬁle. It is recommended that you enter a NULL string for szCfgFile.

Driver conﬁguration ﬁle. Number of boards found.

See Also

K_OpenDriver

4-7

DASDLL_DevOpen (cont.)

Usage

Visual C++

#include "DASDECL.H" // Use DASDECL.HPP for C++ #include "DASDLL.H" // Use DASDLL.HPP for C++ ... char nBoards; ... wDasErr = DASDLL_DevOpen ("", &nBoards);

Visual Basic for Windows

(Include DASDECL.BAS and DASDLL.BAS in your program make ﬁle)

... DIM nBoards AS INTEGER ... wDasErr = DASDLL_DevOpen ("", nBoards)

4-8 Function Reference

DASDLL_DMAAlloc

Boards Supported

Purpose

Prototype Visual C++

DAS-16 Series, DAS-20, DAS-40 Series, DAS-HRES, PDMA Series

Allocates a buffer for a DMA-mode operation.

DASErr far pascal DASDLL_DMAAlloc (DWORD hFrame , DWORD dwSamples , void far * far *pBuf , WORD far * phMem );

Visual Basic for Windows

Declare Function DASDLL_DMAAlloc Lib "DASSHELL.DLL" (ByVal hFrame As Long, ByVal dwSamples As Long, pBuf As Long,

phMem As Integer) As Integer

Parameters

hFrame dwSamples

pBuf phMem

Handle to the frame that deﬁnes the operation. Number of samples.

Valid values: 1 to 32767 Starting address of the allocated buffer. Handle associated with the allocated buffer.

Return Value

Remarks

See Also

Error/status code. Refer to Appendix A.

For the operation deﬁned by hFrame , this function allocates a memory block (a buffer of the size dwSamples ) from the available memory heap. On return, pBuf contains the address of a buffer that is suitable for a DMA-mode operation and phMem contains the handle associated with the allocated buffer.

Use K_SetDMABuf or K_SetDMABufB to assign pBuf to a frame. You can use phMem to free the allocated memory block by calling

DASDLL_DMAFree .

DASDLL_DMAFree, K_SetDMABuf, K_SetDMABufB

4-9

DASDLL_DMAAlloc (cont.)

Usage

Visual C++

#include "DASDECL.H" // Use DASDECL.HPP for C++ ... void far *pBuf; // Pointer to allocated DMA buffer WORD hMem; // Memory Handle to buffer ... wDasErr = DASDLL_DMAAlloc (hFrame, dwSamples, &pBuf, &hMem);

Visual Basic for Windows

(Include DASDECL.BAS in your program make ﬁle)

... Global pBuf As Long Global hMem As Integer ... wDasErr = DASDLL_DMAAlloc (hFrame, dwSamples, pBuf, hMem)

4-10 Function Reference

DASDLL_DMAFree

Boards Supported

Purpose

Prototype Visual C++

DAS-16 Series, DAS-20, DAS-40 Series, DAS-HRES, PDMA Series

Frees a buffer allocated for a DMA-mode operation.

DASErr far pascal DASDLL_DMAFree (WORD hMem );

Visual Basic for Windows

Declare Function DASDLL_DMAFree Lib "DASSHELL.DLL" (ByVal hMem As Integer) As Integer

Parameters

Return Value

Remarks

hMem

Error/status code. Refer to Appendix A.

This function frees the buffer speciﬁed by hMem ; the buffer was previously allocated using DASDLL_DMAAlloc .

See Also

DASDLL_DMAAlloc, K_SetDMABuf, K_SetDMABufB

Handle to DMA buffer.

Usage Visual C++

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

Visual Basic for Windows

(Include DASDECL.BAS in your program make ﬁle)

... wDasErr = DASDLL_DMAFree (hMem)

4-11

DASDLL_GetBoardName

Boards Supported

Purpose

Prototype Visual C++

All

Returns information about the boards and drivers loaded in your system.

DASErr far pascal DASDLL_GetBoardName (WORD nBrdNum, char far *far* pDrvName);

Visual Basic for Windows

Not supported

Parameters

nBrdNum Logical board number. pDrvName Driver associated with board.

Return Value

Remarks

Error/status code. Refer to Appendix A.

This function gets the name of the driver associated with the board speciﬁed by nBrdNum and stores the name in pDrvName.

See Also

K_GetDevHandle, DASDLL_GetDevHandle

Usage Visual C++

#include "DASDECL.H" // Use DASDECL.HPP for C++ ... char *pDrvName; ... wDasErr = DASDLL_GetBoardName (0, &pDrvName);

4-12 Function Reference

DASDLL_GetDevHandle

Boards Supported

Purpose

Prototype Visual C++

All

Initializes a DASDLL-supported board.

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

Visual Basic for Windows

Declare Function DASDLL_GetDevHandle Lib "DASDLL.DLL" (ByVal nBrdNum As Integer, phDev As Long) As Integer

Parameters

nBrdNum Logical board number. phDev Handle associated with the board.

Return Value

Remarks

Error/status code. Refer to Appendix A.

This function initializes the board speciﬁed by nBrdNum, and stores the board handle of the speciﬁed board in phDev.

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

See Also

K_GetDevHandle, DASDLL_GetBoardName, K_DASDevInit

4-13

DASDLL_GetDevHandle (cont.)

Usage Visual C++

#include "DASDECL.H" // Use DASDECL.HPP for C++ #include "DASDLL.H" // Use DASDLL.HPP for C++ ... void far *phDev; ... wDasErr = DASDLL_GetDevHandle (0, &phDev);

Visual Basic for Windows

(Include DASDECL.BAS and DASDLL.BAS in your program make ﬁle)

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

4-14 Function Reference

Tektronix DASDLL Function Call Driver Users Guide

Specifications and Main Features

Frequently Asked Questions

User Manual