Tektronix DAS-TC Function Call Driver Users Guide

Download

DAS-TC Function Call Driv er

USER’S GUIDE

DAS-TC

Function Call Driver

User’s Guide

Revision A – March 1996

Part Number: 84080

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

The DAS-TC Function Call Driver User’s Guide describes how to write application programs for DAS-TC and DAS-TC/B boards using the DAS-TC Function Call Driver. The DAS-TC Function Call Driver supports the following DOS-based languages:

●

Microsoft



QuickBasic  (Version 4.5)

Microsoft Professional Basic (Version 7.0 and higher)

●

Microsoft C/C++ (Version 7.0 and higher)

●

Borland

●

Borland Turbo Pascal



C/C++ (Version 4.0 and higher)



for DOS (Version 6.0 and higher)

The DAS-TC Function Call Driver also supports the following Windows  -based languages:

●

Microsoft C/C++ (Version 7.0 and higher) Borland C/C++ (Version 4.0 and higher)

●

Microsoft Visual Basic for Windows

●

Microsoft Visual C++  (Version 1.5)

●

Borland Turbo Pascal for Windows (Version 1.0)



(Version 3.0 and higher)

The manual is intended for application programmers using a DAS-TC or DAS-TC/B board in an IBM



PC AT



or compatible computer. Before using this manual, read the user’s guide for your board to familiarize yourself with the board’s features and complete the appropriate hardw are installation and conﬁguration. It is assumed that you are experienced in programming in your selected language and that you are familiar with data acquisition principles.

vii

The DAS-TC Function Call Driver User’s Guide is organized as follows:

Chapter 1 contains the information needed to get started using the

●

DAS-TC Function Call Driver and to get help.

●

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

●

Chapter 3 contains programming guidelines and language-speciﬁc information related to using the DAS-TC Function Call Driver.

●

Chapter 4 contains detailed descriptions of the DAS-TC Function Call Driver functions, arranged in alphabetical order.

●

Appendix A contains a list of the error codes returned by DAS-TC Function Call Driver functions.

Appendix B contains information on the data formats used.

●

An index completes this manual.

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

●

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

Keyboard keys are represented in bold.

●

viii

Table of Contents

Preface

Getting Started

Available Operations

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

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

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

Retrieving Revision Levels . . . . . . . . . . . . . . . . . . . . . . . . . . .2-3

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

Analog Input Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-4

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

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

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

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

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

Dimensioning a Local Array . . . . . . . . . . . . . . . . . . . . . . .2-7

Dynamically Allocating a Memory Buffer. . . . . . . . . . . . .2-8

Assigning the Starting Address . . . . . . . . . . . . . . . . . . . . .2-9

Channels, Gains, and Inputs . . . . . . . . . . . . . . . . . . . . . . . . .2-10

Specifying a Single Channel or a Group of Consecutive

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

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

Buffering Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-13

Programming with the Function Call Driver

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

Programming Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-5

Preliminary Tasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-6

Analog Input Programming Tasks . . . . . . . . . . . . . . . . . . . . . . . .3-6

Single-Mode Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-6

Synchronous-Mode Operations. . . . . . . . . . . . . . . . . . . . . . . .3-7

Interrupt-Mode Operations . . . . . . . . . . . . . . . . . . . . . . . . . . .3-9

iii

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

Dimensioning and Assigning a Local Array . . . . . . . . . . . . .3-11

Dynamically Allocating and Assigning a Memory Buffer . .3-12

Allocating a Memory Buffer . . . . . . . . . . . . . . . . . . . . . .3-12

Accessing the Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-13

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

Handling Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-14

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

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

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

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

Turbo Pascal Programming Information . . . . . . . . . . . . . . . . . .3-20

Dimensioning and Assigning a Local Array . . . . . . . . . . . . .3-20

Dynamically Allocating and Assigning a Memory Buffer . .3-20

Reducing the Memory Heap . . . . . . . . . . . . . . . . . . . . . .3-21

Allocating a Memory Buffer . . . . . . . . . . . . . . . . . . . . . .3-22

Accessing the Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-23

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

Handling Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-24

Programming in Borland Turbo Pascal (for DOS) . . . . . . . .3-24

Programming in Borland Turbo Pascal for Windows . . . . . .3-25

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

Dimensioning and Assigning a Local Array . . . . . . . . . . . . .3-26

Dynamically Allocating and Assigning a Memory Buffer . .3-26

Allocating a Memory Buffer . . . . . . . . . . . . . . . . . . . . . .3-27

Accessing the Data from Buffers with Fewer than

64K Bytes3-27

Accessing the Data from Buffers with More than

64K Bytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-28

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

Handling Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-31

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

BASIC Programming Information. . . . . . . . . . . . . . . . . . . . . . .3-32

Dimensioning and Assigning a Local Array . . . . . . . . . . . . .3-32

Dynamically Allocating and Assigning a Memory Buffer . .3-32

Reducing the Memory Heap . . . . . . . . . . . . . . . . . . . . . .3-33

Allocating a Memory Buffer . . . . . . . . . . . . . . . . . . . . . .3-33

Accessing the Data from Buffers with Fewer

than 64K Bytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-34

Accessing the Data from Buffers with More

than 64K Bytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-34

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

Handling Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-38

Programming in Microsoft QuickBasic . . . . . . . . . . . . . . . .3-39

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

Function Reference

DASTC_DevOpen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-5

DASTC_GETCJC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-8

DASTC_GetDevHandle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-11

K_ADRead. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-13

K_ADReadL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-16

K_ADReadR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-19

K_ClearFrame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-22

K_CloseDriver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-24

K_ClrContRun . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-26

K_DASDevInit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-28

K_FormatChnGAry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-30

K_FreeDevHandle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-32

K_FreeFrame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-34

K_GetADFrame. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-36

K_GetDevHandle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-38

K_GetErrMsg. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-40

K_GetShellVer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-42

K_GetVer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-45

K_IntAlloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-48

K_IntFree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-51

K_IntStart. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-53

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

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

K_MoveBufToArrayL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-61

K_MoveBufToArrayR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-63

K_OpenDriver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-65

K_RestoreChnGAry. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-68

K_SetBuf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-70

K_SetBufL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-72

K_SetBufR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-74

K_SetChnGAry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-76

K_SetContRun . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-79

K_SetStartStopChn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-81

K_SyncStart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-84

Error/Status Codes

Data Formats

Integer Number Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1

Floating-Point Number Types . . . . . . . . . . . . . . . . . . . . . . . . . . B-2

Index

List of Figures

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

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

List of Tables

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

Table 2-2. Input Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-10

Table 2-3. Gain Codes for Voltage Inputs . . . . . . . . . . . . . .2-11

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

Table 3-2. Setup Functions for Synchronous-Mode

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

Table 3-3. Setup Functions for Interrupt-Mode

Analog Input Operations . . . . . . . . . . . . . . . . . . . .3-9

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

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

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

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

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

Table B-1. Integer Input Error Conditions. . . . . . . . . . . . . . . B-2

Table B-2. Floating-Point Input Error Conditions. . . . . . . . . B-2

Getting Started

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

●

DAS-TC standard software package - This is the software package

that is shipped with the DAS-TC and DAS-TC/B boards; it includes the following:

– Libraries of FCD functions for Microsoft QuickBasic and

Microsoft Professional Basic.

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

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

– Utility programs (DOS-based only) that allow you to conﬁgure

and test the features of DAS-TC and DAS-TC/B boards.

– Language-speciﬁc example programs.

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

●

for the DAS-TC boards. It includes the following: – Libraries of FCD functions for Microsoft C/C++, Borland

C/C++, and Borland Turbo Pascal.

– Dynamic Link Libraries (DLLs) of FCD functions for Microsoft

C/C++, Borland C/C++, Microsoft Visual Basic for Windows, Microsoft Visual C++, and Borland Turbo Pascal for Windows.

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

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

1-1

– Utility programs (DOS-based and Windows-based) that allow

you to conﬁgure and test the features of the DAS-TC and DAS-TC/B boards.

– Language-speciﬁc example programs.

Before you use the Function Call Driver, make sure that you have installed the software and your board using the procedures described in the user’s guide for your board.

If you need help installing or using the DAS-TC Function Call Driver, call your local sales ofﬁce or call the following number for technical support:

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

A.M.

- 6:00

P.M.

, Eastern Time

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

1-2 Getting Started

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

DAS-TC/B board

Computer

Operating system

Software package

Compiler (if applicable)

Model Serial # Revision code Base Address Interrupt Level Thermocouple type

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

DOS version Windows version

Name Serial # Version Invoice/Order #

Language Manufacturer Version

_____________________ _____________________ _____________________ _____________________ _____________________ _____________________

_____________________ 386 486 Pentium ____ ____________________ Yes No _____________________ EGA VGA SVGA _____________________ _____________________

_____________________

3.0 3.1 95 _____________________

_____________________ _____________________ _____________________

Accessories

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

_____________________ _____________________ _____________________ _____________________ _____________________ _____________________ _____________________ _____________________

1-3

Available Operations

This chapter contains the background information you need to use the FCD functions to perform operations on DAS-TC and D AS-TC/B boards. Table 2-1 lists the supported operations.

System Operations

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

Initializing the driver

●

Initializing a board

●

Retrieving revision levels

●

Handling errors

Table 2-1. Supported Operations

Operation Page Reference

System page 2-1 Analog input page 2-4

System Operations 2-1

Initializing the Driver

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

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

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

Note:

K_OpenDriver and K_CloseDriver are not available. You must use the DASTC_DevOpen function instead. DASTC_DevOpen initializes the

DAS-TC Function Call Driver according to the conﬁguration ﬁle you specify. Refer to page 4-5 for more information. In BASIC and Turbo Pascal, closing the DAS-TC Function Call Driver is not required.

Initializing a Board

The DAS-TC Function Call Driver supports up to two DAS-TC or DAS-TC/B boards. 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 device handle.

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

K_GetDevHandle in subsequent function calls related to the board.

If you are programming in BASIC or Turbo Pascal,

2-2 Available Operations

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

Note:

K_GetDevHandle and K_FreeDevHandle are not available. You must

use the DASTC_GetDevHandle function instead. Refer to page 4-11 for more information. In BASIC or Turbo Pascal, freeing a device handle is not required.

Use K_GetDevHandle or DASTC_GetDevHandle the ﬁrst time you initialize a DAS-TC or DAS-TC/B board only. Once you have a device handle, you can reinitialize a board as needed by using the

K_DASDevInit function.

If you are programming in BASIC or Turbo Pascal,

Retrieving Revision Levels

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

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

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

System Operations 2-3

Handling Errors

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

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

C/C++ page 3-14 Turbo Pascal page 3-24 Visual Basic for Windows page 3-31 BASIC page 3-38

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

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 input range – Buffering mode

2-4 Available Operations

Operation Modes

The operation mode determines which attributes you can specify for an analog input operation and how data is transferred from the D AS-TC and DAS-TC/B boards to computer memory. You can perform analog input operations in single mode, synchronous mode, and interrupt mode, as described in the following sections.

Single Mode

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

Use the K_ADRead function that is appropriate to your programming language to start an analog input operation in single mode. For each function you specify the board you want to use, the analog input channel to read, the gain for that channel (for voltage inputs only), and the variable in which to store the converted data.

Note:

for thermocouple inputs.

Depending on your conﬁguration, the data is returned as a single voltage or temperature value in engineering units. Refer to Appendix B for more information on the format of the data returned.

If you wish, you can use a K_ADRead function with software looping to acquire more than one value from one or more channels. Typically, when acquiring more than one value you want more control over the data transfer than is possible with a single-mode function; in such cases, use either synchronous or interrupt mode, described in the next sections.

Note:

channel, use the single-mode function DASTC_GETCJC . You can use the resulting value to correct a temperature reading when you want to perform your own linearization.

Analog Input Operations 2-5

For thermocouple inputs, specify 0 for the gain; the gain is ignored

To read the value of the CJC (cold junction compensation)

Synchronous Mode

In synchronous mode, the board acquires a single sample or multiple samples from one or more analog input channels. After transferring the speciﬁed number of samples to computer memory, the driver returns control to the application program. You cannot perform any other operation until a synchronous-mode operation is complete.

The DAS-TC and DAS-TC/B boards transfer data in blocks, where the block size equals the number of channels speciﬁed. Suppose, for example, you requested 43 samples using 10 channels. The Function Call Driver actually acquires 50 values in ﬁve blocks of 10 samples each. The ﬁrst 40 values are transferred from the ﬁrst four blocks that were acquired and the remaining three samples are transferred from the ﬁfth acquired block of 10 samples.

Interrupt Mode

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

Depending on your conﬁguration, the data is returned as voltage or temperature values in engineering units. Refer to Appendix B for more information on the format of the data returned.

In interrupt mode, the board acquires a single sample or multiple samples from one or more analog input channels. Once the analog input operation begins, control returns to your application program. The hardware transfers the data from the board to a user-deﬁned buffer in computer memory using an interrupt service routine.

As in synchronous mode, in interrupt mode, the DAS-TC and DAS-TC/B boards transfer data in blocks, where the block size equals the number of channels speciﬁed.

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

Depending on your conﬁguration, the data is returned as voltage or temperature values in engineering units. Refer to Appendix B for more information on the format of the data returned.

2-6 Available Operations

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

Memory Allocation and Management

Synchronous-mode and interrupt-mode analog input operations on the DAS-TC and DAS-TC/B boards require a single array or memory buffer in which to store acquired data. The ways you can allocate and manage memory are described in the following sections.

Dimensioning a Local Array

For the DAS-TC and DAS-TC/B boards, the simplest way to reserve a memory buffer is to dimension an array within your application program. The advantage of this method is that the array is directly accessible to your application program. The limitations of this method are as follows:

Certain programming languages limit the size of local arrays.

●

Local arrays occupy permanent memory areas; these memory areas

●

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

Make sure that the array you dimension matches the data type (long integer or ﬂoating point) speciﬁed in the conﬁguration ﬁle. A single sample is four bytes long. Therefore, you should declare a local array as an array of four byte elements, the size of which is at least equal to the number of samples you are acquiring. For example, if you want to acquire 16,384 samples, you must dimension a 64K byte array.

Analog Input Operations 2-7

Dynamically Allocating a Memory Buffer

If you wish, you can also reserve a memory buffer by allocating it dynamically outside of your application program’s memory area. The advantages of this method are as follows:

●

The size of the buffer is limited by the amount of free physical memory available in your computer at run time.

A dynamically allocated memory buffer can be freed to make it

●

available to other programs or processes.

The limitation of this method is that for Visual Basic for Windows and BASIC, the data in a dynamically allocated memory buffer is not directly accessible to your program. You must use the K_MoveBufToArrayL function (for long integer arrays) or the K_MoveBufToArrayR function (for ﬂoating-point arrays) to move the data from the dynamically allocated memory buffer to the program’s local array. For Visual Basic for Windows, refer to page 3-26 for more information; for BASIC, refer to page 3-32 for more information.

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

Make sure that the pointers to the buffers allocated by K_IntAlloc are appropriate to the number type (long integer or ﬂoating point) speciﬁed in the conﬁguration ﬁle.

2-8 Available Operations

Notes:

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

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

GlobalAlloc API function to allocate the desired buffer size from the

global heap.

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

Assigning the Starting Address

After you dimension your array or allocate your buffer, you must assign the starting address of the array or buffer and the number of samples to store in the array or buffer. Each supported programming language requires a particular function and procedure for assigning the starting address; refer to the following table for more information:

Language Function Refer to

C/C++ K_SetBuf page 3-11 Turbo Pascal K_SetBuf page 3-20 Visual Basic for Windows K_SetBufL

K_SetBufR

BASIC K_SetBufL

K_SetBufR

Notes

Use K_SetBufL for long integer arrays or buffers; use

K_SetBufR for ﬂoating-point arrays or buffers.

Analog Input Operations 2-9

page 3-26

page 3-32

Channels, Gains, and Inputs

DAS-TC and DAS-TC/B boards are software-conﬁgurable for up to 16 differential analog input channels (numbered 0 through 15). You can mix and match thermocouple and voltage inputs. You conﬁgure the channels using the DASTCCFG.EXE conﬁguration utility; refer to the user’s guide for your board for more information. Table 2-2 lists the input types supported by the DAS-TC and DAS-TC/B boards.

Table 2-2. Input Types

Voltage Inputs − 2.5 V to 10 V

20 mV to 80 mV 15 mV to 60 mV

6.25 mV to 25 mV

−

Thermocouple Inputs

Type J Type K Type E T ype T Type R Type S Type B

The input range is usually determined by the settings in the conﬁguration ﬁle. However, for voltage inputs only, you can specify an input range using the gain and gain code, shown in Table 2-3. (The gain code is used by the FCD functions to represent the gain.) For thermocouple inputs, the gain is ignored; specify a gain code of 0 for thermocouple inputs.

2-10 Available Operations

Table 2-3. Gain Codes for Voltage Inputs

−

Gain Code Gain

0 1 1 125 2 166.67 −15 mV to 60 mV 3 400 −6.25 mV to 25 mV

Voltage Input Range

2.5 V to 10 V 20 mV to 80 mV

Depending on the settings in the conﬁguration ﬁle, data is returned in volts, degrees Celsius, or degrees Fahrenheit, as appropriate for the input types conﬁgured. Refer to Appendix B for information on the data formats.

How you specify a channel and the input range differs depending on the operation mode and the sequence of channels you want to use, as described in the following sections.

Specifying a Single Channel or a Group of Consecutive Channels

For single-mode operations, you can acquire a single sample from a single channel. Use the K_ADRead function appropriate to your programming language to specify an analog input channel and the gain for the channel (for voltage inputs only).

Note:

For thermocouple inputs, the gain is ignored; specify a gain code

of 0 for channels conﬁgured as thermocouple inputs.

For synchronous-mode and interrupt-mode analog input operations, you can acquire samples from a single channel or a group of consecutive channels. Use the K_SetStartStopChn function to specify the ﬁrst and last channels in the group; to read a single channel, specify the same channel as both the start and the stop channel. The input ranges of the channels are determined by the settings in the conﬁguration ﬁle.

Analog Input Operations 2-11

The channels are sampled in order from the ﬁrst to the last. For example, if the start channel is 10 and the stop channel is 15, the channels are sampled in the following order: 10, 11, 12, 13, 14, 15. If the start channel is 10 and the stop channel is 3, the channels are sampled in the following order: 10, 11, 12, 13, 14, 15, 0, 1, 2, 3. The channels are repeatedly sampled in the speciﬁed order until the required number of samples is read.

Note: When you use the K_SetStartStopChn function, the Function

Call Driver reads the conﬁguration ﬁle to determine whether the signal connected to the speciﬁed channel is a voltage input or a thermocouple input and to determine the appropriate gain for that channel. If you want to change the gain without changing the conﬁguration ﬁle, use a channel-gain queue, as described in the next section.

Specifying Channels in a Channel-Gain Queue

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

Note: For thermocouple inputs, the gain is ignored; specify a gain code

of 0 for channels conﬁgured as thermocouple inputs.

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

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

2-12 Available Operations

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

C/C++ page 3-13 Turbo Pascal page 3-23 Visual Basic for Windows page 3-30 BASIC page 3-37

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.

Buffering Modes

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

● Single-cycle mode- In single-cycle mode, after the board con verts the

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

● Continuous mode - In continuous mode, the board continuously

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

If you are using continuous buffering, as soon as the last block of samples is transferred, the following occur:

– the transfer count and buffer pointer are reset to zero – K_IntStatus returns zero instead of the requested sample size in

the index parameter

– the driver begins to overwrite your buffer’s data

Analog Input Operations 2-13

Therefore, if your application requires consecutive blocks of data, you should begin processing the buffer before the buffer is full, using K_IntStatus to determine how many blocks have been transferred (this function’s index parameter increments by the block size).

Note: Buffering modes are not meaningful for synchronous-mode

operations, since only single-cycle mode applies.

2-14 Available Operations

Programming with the

Function Call Driver

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

How the Driver Works

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

You can program one or more boards in your application program. Up to two DAS-TC or DAS-TC/B boards are supported. You initialize each board using a unique device handle to identify each board. Each device handle is associated with a particular driver.

The Function Call Driver allows you to perform operations in various operation modes. For single mode, the operation is performed with a single call to a function; the attributes of the 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 . The

K_ADReadL and K_ADReadR functions have the same syntax.

How the Driver Works 3-1

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

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

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

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

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

K_SetStartStopChn setup function.

3-2 Programming with the Function Call Driver

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

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

K_IntStart (

Start Channel Stop Channel Buffering Mode

Frame

. . .

frameHandle

)

Attributes of Operation

First analog input channel Last analog input channel Single cycle or continuous

. . .

Figure 3-2. Interrupt-Mode Operation

For DAS-TC and DAS-TC/B boards, synchronous-mode and interrupt-mode analog input operations require frames, called A/D (analog-to-digital) frames. Use the K_GetADFrame function to access an available A/D frame.

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

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

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

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

How the Driver Works 3-3

Table 3-1 lists the elements of an A/D frame for DAS-TC and DAS-TC/B boards. This table also lists the default value of each element and the setup function used to deﬁne each element.

Table 3-1. A/D Frame Elements

Element Default Value Setup Function

Buffer

0 (NULL)

K_SetBuf

K_SetBufL K_SetBufR

Number of Samples 0 K_SetBuf

K_SetBufL K_SetBufR

Buffering Mode Single-cycle K_SetContRun

K_ClrContRun

Start Channel 0 K_SetStartStopChn Stop Channel 0 K_SetStartStopChn Gain 0 Not applicable

Channel-Gain Queue 0 (NULL) K_SetChnGAry

Notes

You must set this element.

Use K_SetBuf for C/C++ and Turbo Pascal languages; use K_SetBufL (for

long integer arrays) or K_SetBufR (for ﬂoating-point arrays) for V isual Basic and BASIC languages.

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.

The gain value is ignored; the driver reads the value from the conﬁguration

ﬁle.

Note:

The DAS-TC Function Call Driver provides many other functions that are not related to controlling frames, deﬁning the elements of frames, or reading the values of frame elements. These functions include initialization functions, memory management functions, and miscellaneous functions.

3-4 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

To write an application program using the DAS-TC Function Call Driver , perform the following steps:

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

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

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

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

programming tasks that are common to all application programs.

– Analog Input Programming Tasks on page 3-6, which describes

operation-speciﬁc programming tasks and the sequence in which these tasks must be performed.

– Chapter 4, which contains detailed descriptions of the FCD

functions.

– The example programs in the DAS-TC standard software

package and the ASO-TC softw are package. The FILES.TXT ﬁle in the installation directory lists and describes the example programs.

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

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

C/C++ page 3-11 Turbo Pascal page 3-20 Visual Basic for Windows page 3-26 BASIC page 3-32

Programming Overview 3-5

Preliminary T asks

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

1. Include the function and variable type deﬁnition ﬁle for your

language. Depending on the speciﬁc language you are using, this ﬁle is included in the DAS-TC standard software package or the ASO-TC software package.

2. Declare and initialize program variables.

3. Use a driver initialization function ( K_OpenDriver or

DASTC_DevOpen ) to initialize the driver.

4. Use a board initialization function ( K_GetDevHandle or

DASTC_GetDevHandle ) to specify the DAS-TC or DAS-TC/B

board you want to use and to initialize the board. If you are using two DAS-TC or DAS-TC/B boards, repeat this step.

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

Analog Input Programming Tasks

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

Single-Mode Operations

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

1. Declare the array or variable in which to store the single analog input

value.

2. Use the appropriate K_ADRead function to read the single analog

input value; specify the attributes of the operation as ar guments to the function.

3-6 Programming with the Function Call Driver

The following table lists the three K_ADRead functions and explains when to use each function. For details on each function, refer to Chapter 4.

Function Use with

K_ADRead C/C++, Turbo Pascal, and Turbo Pascal for

Windows for any single-mode operation.

K_ADReadL Visual Basic for Windows and BASIC, when you

want to store the value read as a long integer.

K_ADReadR Visual Basic for Windows and BASIC, when you

want to store the value read as a ﬂoating-point number.

Synchronous-Mode Operations

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

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

2. Dimension the array in which to store the acquired data. (Use the

K_IntAlloc function if you want to allocate the buffer dynamically

outside your program's memory area.)

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

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

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

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

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

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

Analog Input Programming Tasks 3-7

Table 3-2. Setup Functions for Synchronous-Mode

Analog Input Operations

Attribute Setup Functions

Buffer

Number of Samples K_SetBuf

Start Channel K_SetStartStopChn Stop Channel K_SetStartStopChn Channel-Gain Queue K_SetChnGAry

Notes

Use K_SetBuf for C/C++ and Turbo Pascal languages;

use K_SetBufL (for long integer arrays) or K_SetBufR (for ﬂoating-point arrays) for Visual Basic and BASIC languages.

K_SetBuf K_SetBufL K_SetBufR

K_SetBufL K_SetBufR

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

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

operation.

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

you used K_IntAlloc to allocate your buffer , use the

K_MoveBufToArrayL function (for long integer arrays) or the K_MoveBufToArrayR function (for floating-point arrays) to

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

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

function to deallocate the buffer.

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

step 1 to the pool of available frames.

3-8 Programming with the Function Call Driver

Interrupt-Mode Operations

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

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

2. Dimension the array in which to store the acquired data. (Use the

K_IntAlloc function if you want to allocate a buffer dynamically

outside your program's memory area.)

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

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

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

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

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

Note:

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

Table 3-3. Setup Functions for Interrupt-Mode

Analog Input Operations

Attribute Setup Functions

Buffer

Number of Samples K_SetBuf

Buffering Mode K_SetContRun

Start Channel K_SetStartStopChn

K_SetBuf K_SetBufL K_SetBufR

K_SetBufL K_SetBufR

K_ClrContRun

Analog Input Programming Tasks 3-9

Table 3-3. Setup Functions for Interrupt-Mode

Analog Input Operations (cont.)

Attribute Setup Functions

Stop Channel K_SetStartStopChn Channel-Gain Queue K_SetChnGAry

Notes

Use K_SetBuf for C/C++ and Turbo Pascal

languages; use K_SetBufL (for long integer arrays) or K_SetBufR (for ﬂoating-point arrays) for Visual Basic and BASIC languages.

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

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

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

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

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

you used K_IntAlloc to allocate your buffer , use the

K_MoveBufToArrayL function (for long integer arrays) or the K_MoveBufToArrayR function (for floating-point arrays) to

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

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

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

3-10 Programming with the Function Call Driver

C/C++ Programming Information

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

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

type-mismatch warnings.

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

Dimensioning and Assigning a Local Array

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

You can use a single, local array for synchronous-mode and interrupt-mode analog input operations. The following code fragment illustrates how to dimension an array of 10,000 samples for the frame deﬁned by hFrame and how to use K_SetBuf to assign the starting address of the array.

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

C/C++ Programming Information 3-11

Dynamically Allocating and Assigning a Memory Buffer

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

Note: If you are using a large memory buffer, you may be limited in the

amount of memory you can allocate. It is recommended that you install the Keithley Memory Manager before you begin programming to ensure that you can allocate a large enough buffer. Refer to the user’s guide for your board for more information on the Keithley Memory Manager.

Allocating a Memory Buffer

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

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

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

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

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

3-12 Programming with the Function Call Driver

Accessing the Data

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

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

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

. . .

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

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

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{

byte Chan; char Gain;

} GainChanAry[256];

} GainChanTable;

C/C++ Programming Information 3-13

The following example illustrates how to create a channel-gain queue called MyChanGainQueue for a DAS-TC or DAS-TC/B board by declaring and initializing a variable of type GainChanTable:

GainChanTable MyChanGainQueue =

{8, //Number of entries 0, 0, //Channel 0, gain is ignored for

//thermocouples 1, 3, //Channel 1, gain of 400 2, 2, //Channel 2, gain of 166.67 3, 1, //Channel 3, gain of 125 3, 0, //Channel 3, gain of 1 2, 3, //Channel 2, gain of 400 1, 3, //Channel 1, gain of 400 0, 0}; //Channel 0, gain is ignored

//for thermocouples

Note: Gain for thermocouple inputs is ignored; specify a gain code of 0

for channels conﬁgured as thermocouple inputs.

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

wDasErr = K_SetChnGAry (hFrame, &MyChanGainQueue);

When you start the next analog input operation (using K_SyncStart or K_IntStart), the channels are sampled in the following order: channel 0,

1, 2, 3, 3, 2, 1, 0.

Handling Errors

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

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

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

3-14 Programming with the Function Call Driver

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

. . . if ((wDasErr = K_SetStartStopChn (hAD, 2, 15) ! = 0)

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

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

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

File Description

DASTC.LIB Linkable driver DASRFACE.LIB Linkable driver DASDECL.H Include ﬁle when compiling in C DTCDECL.H Include ﬁle when compiling in C DASDECL.HPP Include ﬁle when compiling in C++ DASTC.HPP Include ﬁle when compiling in C++ USEDASTC.OBJ Linkable object

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

Type of Compile Compile and Link Statements

C CL /c ﬁlename.c

LINK ﬁlename+usetc.obj,,,dastc+dasrface;

C++ CL /c ﬁlename.cpp

LINK ﬁlename+usetc.obj,,,dastc+dasrface;

C/C++ Programming Information 3-15

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

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

File Description

DASSHELL.DLL Dynamic Link Library DASSUPRT.DLL Dynamic Link Library DASTC.DLL Dynamic Link Library DASDECL.H Include ﬁle when compiling in C DTCDECL.H Include ﬁle when compiling in C DASDECL.HPP Include ﬁle when compiling in C++ DASTC.HPP Include ﬁle when compiling in C++ DASIMP.LIB DAS Shell Imports DASTCIMP.LIB DAS-TC Imports

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

Type of Compile Compile and Link Statements

C CL /c ﬁlename.c

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

C++ CL /c ﬁlename.cpp

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

3-16 Programming with the Function Call Driver

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

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

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

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

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

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

File Description

C/C++ Programming Information 3-17

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

Type of Compile Compile and Link Statements

C BCC ﬁlename.c usetc.obj dastc.lib dasrface.lib C++ BCC ﬁlename.cpp usetc.obj dastc.lib dasrface.lib

Notes

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

model is acceptable.

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

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

File Description

DASSHELL.DLL Dynamic Link Library DASSUPRT.DLL Dynamic Link Library DASTC.DLL Dynamic Link Library DASDECL.H Include ﬁle when compiling in C DTCDECL.H Include ﬁle when compiling in C DASDECL.HPP Include ﬁle when compiling in C++ DASTC.HPP Include ﬁle when compiling in C++ DASTCIMP.LIB DAS Shell Imports DTCIMP.LIB DAS-TC Imports

3-18 Programming with the Function Call Driver

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

Type of Compile Compile and Link Statements

C BCC -c ﬁlename.c

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

C++ BCC -c ﬁlename.cpp

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

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

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

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

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

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

4. From the Options menu, select Project.

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

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

C/C++ Programming Information 3-19

Turbo Pascal Programming Information

The following sections contain information you need to dimension an array or allocate a memory buffer, to create channel-gain queues, and to handle errors when programming in Turbo Pascal, as well as language-speciﬁc information for Borland Turbo Pascal (for DOS) and Borland Turbo Pascal for Windows.

Dimensioning and Assigning a Local Array

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

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

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

. . . Data : Array[0..9999] of Longint; . . . wDasErr := K_SetBuf (hFrame, Data(0), 10000); . . .

Dynamically Allocating and Assigning a Memory Buffer

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

3-20 Programming with the Function Call Driver

Note: If you are using a large buffer and you are programming in

Borland Turbo Pascal for Windows, you may be limited in the amount of memory you can allocate. It is recommended that you use the Keithley Memory Manager before you begin programming to ensure that you can allocate a large enough buf fer. Refer to the user’s guide for your board for more information about the Keithley Memory Manager.

Reducing the Memory Heap

Note: Reducing the memory heap is recommended for Borland Turbo

Pascal (for DOS) only; if you are programming in Borland Turbo Pascal for Windows, reducing the memory heap is not required.

By default, when Borland T urbo P ascal (for DOS) programs be gin to run, Pascal reserves all av ailable DOS memory for use by the internal memory manager; this allows you to perform GetMem and FreeMem operations. Pascal uses the compiler directive $M to distribute the available memory. The default conﬁguration is {$M 16384, 0, 655360}, where 16384 bytes is the stack size, 0 bytes is the minimum heap size, and 655360 is the maximum heap size.

It is recommended that you use the compiler directive $M to reduce the maximum heap reserved by Pascal to zero bytes by entering the following:

{$M (16384, 0, 0)}

Reducing the maximum heap size to zero bytes makes all far heap memory available to DOS (and therefore available to the driver) and allows your application program to take maximum advantage of the K_IntAlloc function. You can reserve some space for the internal memory manager or for DOS, if desired. Refer to your Borland Turbo Pascal (for DOS) documentation for more information.

Turbo Pascal Programming Information 3-21

Allocating a Memory Buffer

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

It is recommended that you declare a dummy type array of ^Integer. The dimension of this array is irrelevant; it is used only to satisfy Pascal’s type-checking requirements.

{$m (16384, 0, 0)} { Turbo Pascal for DOS only } . . . Type

IntArray = Array[0..1] of Longint; . . . Var

AcqBuf : ^IntArray; { Declare buffer of dummy type }

hMem : Word; { Declare word for memory handle, hMem } . . . wDasErr := K_IntAlloc (hFrame, Samples, @AcqBuf, hMem); wDasErr := K_SetBuf (hFrame, AcqBuf, Samples); . . .

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

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

3-22 Programming with the Function Call Driver

Accessing the Data

You access the data stored in a dynamically allocated buffer through Pascal pointer indirection. For example, assume that you want to display the ﬁrst 10 samples of the buffer in the operation described in the pre vious section (AcqBuf). The following code fragment illustrates how to access and display the data.

. . . for i := 0 to 9 do begin

writeln (’Sample #’, i,’ =’, AcqBuf^[i]); End; . . .

Creating a Channel-Gain Queue

The following example illustrates how to create a channel-gain queue called MyChanGainQueue for a DAS-TC or DAS-TC/B board by deﬁning a Record as a new type. You must use K_SetChnGAry to assign the starting address of MyChanGainQueue to the frame deﬁned by hFrame.

Type GainChanTable = Record num_of_codes : Integer; queue : Array[0..255] of Byte; end; . . . Const MyChanGainQueue : GainChanTable = ( num_of_codes : (8); { Number of entries } queue :(0, 0, { Channel 0, gain is ignored for thermocouples}

1, 3, { Channel 1, gain of 400} 2, 2, { Channel 2, gain of 166.67} 3, 1, { Channel 3, gain of 125} 3, 0, { Channel 3, gain of 1} 2, 3, { Channel 2, gain of 400} 1, 3, { Channel 1, gain of 400} 0, 0) { Channel 0, gain is ignored for thermocouples} ); . . .

wDasErr := K_SetChnGAry (hFrame, MyChanGainQueue.num_of_codes);

Turbo Pascal Programming Information 3-23

Note: Gain for thermocouple inputs is ignored; specify a gain code of 0

for channels conﬁgured as thermocouple inputs.

When you start the next analog input operation (using K_SyncStart or K_IntStart), the channels are sampled in the following order: channel 0, 1, 2, 3, 3, 2, 1, 0.

Handling Errors

... wDasErr := DASTC_GetDevHandle (0, hDev); if wDasErr <> 0 then BEGIN FormatStr (HexErr, ' %4x ', wDasErr); writeln ('Error', HexErr, 'during DASTC_GetDevHandle'); Halt (1); END; ...

Programming in Borland Turbo Pascal (for DOS)

To program in Borland Turbo Pascal, you need the ﬁle DASTC.TPU, which is the T urbo Pascal unit for Version 6.0. This ﬁle is provided in the ASO-TC software package.

To create an executable ﬁle in Borland Turbo Pascal, use the following compile and link statement:

TPC filename.pas

where ﬁlename indicates the name of your application program.

3-24 Programming with the Function Call Driver

Programming in Borland Turbo Pascal for Windows

To program in Borland Turbo Pascal for Windows, you need the following ﬁles; these ﬁles are provided in the ASO-TC software package.

File Description

DASSHELL.DLL Dynamic Link Library DASSUPRT.DLL Dynamic Link Library DASTC.DLL Dynamic Link Library DASDECL.INC Include ﬁle DASTC.INC Include ﬁle

To create an executable ﬁle in Borland Turbo Pascal for Windows, perform the following steps:

1. Load ﬁlename.pas into the Borland Turbo Pascal for Windows environment, where ﬁlename indicates the name of your application program.

2. From the Compile menu, choose Make.

Turbo Pascal Programming Information 3-25

Visual Basic for Windows Programming Information

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

Dimensioning and Assigning a Local Array

This section provides code fragments that describe how to dimension and assign a local array when programming in Microsoft Visual Basic for Windows. Note that the code fragments assume Option Base 0. Refer to the example programs on disk for more information.

You can use a single, local array for synchronous-mode and interrupt-mode analog input operations. The following code fragment illustrates how to dimension a long integer array of 10,000 samples for the frame deﬁned by hFrame and how to use K_SetBufL to assign the starting address of the long integer array.

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

Dynamically Allocating and Assigning a Memory Buffer

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

Note: If you are using a large b uf fer , you may be limited in the amount of

memory you can allocate. It is recommended that you use the Keithley Memory Manager before you begin programming to ensure that you can allocate large enough buf fers. Refer to the user’s guide for your board for more information about the Keithley Memory Manager.

3-26 Programming with the Function Call Driver

Allocating a Memory Buffer

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

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

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

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

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

Accessing the Data from Buffers with Fewer than 64K Bytes

In Microsoft Visual Basic for Windo ws, you cannot directly access analog input samples stored in a dynamically allocated memory buffer. You must use either the K_MoveBufT oArrayL function (for long inte ger arrays) or the K_MoveBufT oArrayR function (for ﬂoating-point arrays) to move a subset (up to 32,767 samples) of the data into a local array as required. The following code fragment illustrates how to move the ﬁrst 100 samples of the buffer in the operation described in the previous section (AcqBuf) to a local array.

. . . Dim Buffer(1000) As Long’ Declare local memory buffer . . . wDasErr = K_MoveBufToArrayL (Buffer(0), AcqBuf, 100) . . .

Visual Basic for Windows Programming Information 3-27

Accessing the Data from Buffers with More than 64K Bytes

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

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

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

Table 3-4. Protected-Mode Memory Architecture

Selector:Offset 32-Bit Linear Address

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

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

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

3-28 Programming with the Function Call Driver

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

Dim AcqBuf As Long Dim NumSamps As Long

Dim Array(999) As Long

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

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

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

To move more than 32,767 values from the memory buffer to the program’s local array, the program must call K_MoveBufToArrayL more than once. For example, assume that pBuf is a pointer to a dynamically allocated buffer that contains 65,536 values. The following code fragment illustrates how to move 65,536 values from the dynamically allocated buffer to the program’s local array:

... Dim Data [2, 32768] As Long ... wDasErr = K_MoveBufToArrayL (Data(0,0), pBuf, 32768)

’Add 8 to selector, offset = 0: add &h80000 wDasErr = K_MoveBufToArrayL (Data(1,0), pBuf + &h80000, 32768)

’Add 8 to selector, offset=0: add &h100000 wDasErr = K_MoveBufToArrayL (Data(2,0), pBuf + &h100000, 32768)

Visual Basic for Windows Programming Information 3-29

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

The following code fragment illustrates how to create a four-entry channel-gain queue called MyChanGainQueue for a DAS-TC or DAS-TC/B 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 ’(4 channels x 2) + 1 . . . MyChanGainQueue(0) = 4 ’ Number of channel-gain pairs MyChanGainQueue(1) = 0 ’ Channel 0 MyChanGainQueue(2) = 0 ’ Gain ignored for thermocouples MyChanGainQueue(3) = 1 ’ Channel 1 MyChanGainQueue(4) = 3 ’ Gain of 400 MyChanGainQueue(5) = 2 ’ Channel 2 MyChanGainQueue(6) = 2 ’ Gain of 166.67 MyChanGainQueue(7) = 2 ’ Channel 2 MyChanGainQueue(8) = 0 ’ Gain of 1 . . . wDasErr = K_FormatChnGAry (MyChanGainQueue(0)) wDasErr = K_SetChnGAry (hFrame, MyChanGainQueue(0)) . . .

Note: Gain for thermocouple inputs is ignored; specify a gain code of 0

for channels conﬁgured as thermocouple inputs.

3-30 Programming with the Function Call Driver

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

When you start the next analog input operation (using K_SyncStart or K_IntStart), the channels are sampled in the following order: channel 0, 1, 2, 2.

Handling Errors

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

MsgBox "K_GetDevHandle Error: " + Hex$ (wDasErr),

MB_ICONSTOP, "DAS-TC/B ERROR"

End End If . . .

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

Programming in Microsoft Visual Basic for Windows

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

File Description

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

Visual Basic for Windows Programming Information 3-31

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

BASIC Programming Information

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

Dimensioning and Assigning a Local Array

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

You can use a single, local array for synchronous-mode and interrupt-mode analog input operations. The following code fragment illustrates how to dimension a long array of 10,000 samples for the frame deﬁned by hFrame and how to use KSetBufL to assign the starting address of the long integer array.

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

Dynamically Allocating and Assigning a Memory Buffer

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

3-32 Programming with the Function Call Driver

Reducing the Memory Heap

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

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

Allocating a Memory Buffer

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

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

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

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

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

BASIC Programming Information 3-33

Accessing the Data from Buffers with Fewer than 64K Bytes

In BASIC, you cannot directly access analog input samples stored in a dynamically allocated memory buffer. You must use either the

KMoveBufToArrayL function (for long integer arrays) or the KMoveBufToArrayR function (for ﬂoating-point arrays) to move a

subset of the data (up to 32,767 samples) into a local array . The follo wing code fragment illustrates how to move the ﬁrst 100 samples of the buffer in the operation described in the previous section (AcqBuf) into a local memory buffer.

. . . Dim Buffer(99) As Long ’ Declare local memory buffer . . . wDasErr = KMoveBufToArrayL% (Buffer(0), AcqBuf, 100) . . .

Accessing the Data from Buffers with More than 64K Bytes

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

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

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

3-34 Programming with the Function Call Driver

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

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

Table 3-5. Real-Mode Memory Architecture

Segment:Offset 20-Bit Linear Address

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

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

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

Dim Array(999) As Long . . . ’Initialize array with desired values

NumSamps = 50000 wDasErr = KIntAlloc% (hFrame, NumSamps, AcqBuf, hMem)

DesiredSamp = 40000 DesiredByte = DesiredSamp * 4 ’Number of bytes into buffer

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

BASIC Programming Information 3-35

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

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

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

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

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

In this method, you add &h10000000 to the buffer address for each 64K byte page and then add the remainder of the buffer.

... Dim Data [2, 32768] As Long ... wDasErr = KMoveBufToArrayL% (Data(0,0), pBuf, 32768)

’Add 8 to selector, offset = 0: add &h80000 wDasErr = KMoveBufToArrayL% (Data(1,0), pBuf + &h80000, 32768)

’Add 8 to selector, offset=0: add &h100000 wDasErr = KMoveBufToArrayL% (Data(2,0), pBuf + &h100000, 32768)

3-36 Programming with the Function Call Driver

Creating a Channel-Gain Queue

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

The following code fragment illustrates how to create a four-entry channel-gain queue called MyChanGainQueue for a DAS-TC or DAS-TC/B board and how to use KSetChnGAry to assign the starting address of MyChanGainQueue to the frame deﬁned by hFrame.

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

Note: Gain is ignored for thermocouple inputs; specify a gain code of 0

for channels conﬁgured as thermocouple inputs.

BASIC Programming Information 3-37

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

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

When you start the next analog input operation (using KSyncStart or KIntStart), the channels are sampled in the following order: channel 0, 1,

2, 2.

Handling Errors

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

3-38 Programming with the Function Call Driver

Programming in Microsoft QuickBasic

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

File Description

DTCQ45.LIB Linkable driver for QuickBasic (Version 4.5)

stand-alone, executable (.EXE) programs

DTCQ45.QLB Command-line loadable dri ver for the QuickBasic

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

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

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

1. Enter the following to invoke the environment:

QB /L DTCQ45 filename.bas

where ﬁlename indicates the name of your application program.

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

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

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

where ﬁlename indicates the name of your application program.

BASIC Programming Information 3-39

Programming in Microsoft Professional Basic

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

File Description

DTCQBX.LIB Linkable driver for Professional Basic,

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

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

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

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

1. Enter the following to invoke the environment:

QBX /L DTCQBX filename.bas

where ﬁlename indicates the name of your application program.

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

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

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

where ﬁlename indicates the name of your application program.

3-40 Programming with the Function Call Driver

Function Reference

The FCD functions are organized into the following groups:

Initialization functions

●

Operation functions

●

Frame management functions Memory management functions

●

Buffer address functions

●

Buffering mode functions

●

Channel and gain functions 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 DASTC_DevOpen page 4-5

DASTC_GetDevHandle page 4-11 K_OpenDriver page 4-65 K_CloseDriver page 4-24 K_GetDevHandle page 4-38 K_FreeDevHandle page 4-32 K_DASDevInit page 4-28

Operation K_ADRead page 4-13

K_ADReadL page 4-16 K_ADReadR page 4-19 K_SyncStart page 4-84 K_IntStart page 4-53 K_IntStatus page 4-55 K_IntStop page 4-58

Frame Management K_GetADFrame page 4-36

K_FreeFrame page 4-34 K_ClearFrame page 4-22

Memory Management K_IntAlloc page 4-48

K_IntFree page 4-51 K_MoveBufToArrayL page 4-61 K_MoveBufToArrayR page 4-63

Buffer Address K_SetBuf page 4-70

K_SetBufL page 4-72 K_SetBufR page 4-74

4-2 Function Reference

Table 4-1. Functions (cont.)

Function Type Function Name Page Number

Buffering Mode K_SetContRun page 4-79

K_ClrContRun page 4-26

Channel and Gain K_SetStartStopChn page 4-81

K_SetChnGAry page 4-76 K_FormatChnGAry page 4-30 K_RestoreChnGAry page 4-68

Miscellaneous K_GetErrMsg page 4-40

K_GetVer page 4-45 K_GetShellVer page 4-42 DASTC_GETCJC page 4-8

Keep the following conventions in mind throughout this chapter:

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

●

the underscores in the BASIC languages. The data types DWORD, WORD, and BYTE are deﬁned in the

●

language-speciﬁc include ﬁles.

●

Variable names are shown in italics.

●

The return value for all FCD functions is an integer error/status code. Error/status code 0 indicates that the function executed successfully. A nonzero error/status code indicates that an error occurred. Refer to Appendix A for additional information.

In the usage section, the variables are not deﬁned. It is assumed that

●

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

. 4-3

Table 4-2. Data Type Preﬁxes

Preﬁx Data T ype Comments

sz Pointer to string terminated by

zero

h Handle to device, frame, and

memory block

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

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

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

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

a Array This data type is typically used in conjunction with

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

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

to get a driver handle, a frame handle, a memory handle, or a device 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-4 Function Reference

DASTC_DevOpen

Purpose

Prototype C/C++

Initializes the DAS-TC Function Call Driver.

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

Turbo Pascal

Function DASTC_DevOpen (Var szCfgFile : char; Var pBoards : Integer) : Word; far; external 'DASTC';

Turbo Pascal for Windows

Function DASTC_DevOpen (Var szCfgFile : char; Var pBoards : Integer) : Word; far; external 'DASTC';

Visual Basic for Windows

Declare Function DASTC_DevOpen Lib "DASTC.DLL" (ByVal szCfgFile As String, pBoards As Integer) As Integer

BASIC

DECLARE FUNCTION DASTCDEVOPEN% ALIAS "DASTC_DevOpen" (BYVAL szCfgFile AS LONG, SEG pBoards AS INTEGER)

Parameters

Return Value

Remarks

szCfgFile

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

pBoards

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

Error/status code. Refer to Appendix A.

This function initializes the driver according to the information in the configuration file specified by szCfgFile and stores the number of DAS-TC or DAS-TC/B boards defined in szCfgFile in pBoards .

4-5

DASTC_DevOpen (cont.)

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

szCfgFile =

conﬁguration ﬁle in the current directory. If szCfgFile =

DASTC_DevOpen uses the default conﬁguration settings. Refer to the

user’s guide for your board for more information about conﬁguration ﬁles and settings.

DASTC_DevOpen looks for the DASTC.CFG

−1

See Also

Usage C/C++

K_OpenDriver

#include "DTCDECL.H" // Use DASTC.HPP for C++ ... char nBoards; ... wDasErr = DASTC_DevOpen ("DASTC.CFG", &nBoards);

Turbo Pascal

uses DTCTPU; ... szCfgName : String; nBoards : Integer; ... szCfgName := 'DASTC.CFG' + #0; wDasErr := DASTC_DevOpen (szCfgName[1], nBoards);

Turbo Pascal for Windows

{$I DASTC.INC} ... szCfgName : String; nBoards : Integer; ... szCfgName := 'DASTC.CFG' + #0; wDasErr := DASTC_DevOpen (szCfgName[1], nBoards);

4-6 Function Reference

DASTC_DevOpen (cont.)

Visual Basic for Windows

(Add DTCDECL.BAS to your project)

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

BASIC

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

4-7

DASTC_GETCJC

Purpose

Returns the value of the CJC on the DAS-TC or DAS-TC/B board in degrees Celsius; this value is used to correct temperature input values.

Prototype C/C++

DASErr far pascal DASTC_GETCJC (int nBrdNum , ﬂoat far *pCJCtemp );

Turbo Pascal

Function DASTC_GETCJC ( nBrdNum : Integer; Var pCJCtemp : Real) : Word; far; external 'DASTC';

Turbo Pascal for Windows

Function DASTC_GETCJC nBrdNum : Integer; Var pCJCtemp : Single) : Word; far; external 'DASTC';

Visual Basic for Windows

Declare Function DASTC_GETCJC Lib "DASTC.DLL" (ByVal nBrdNum As Integer, pCJCtemp As Single) As Integer

BASIC

DECLARE FUNCTION DASTCGETCJC% ALIAS "D ASTC_GETCJC" (BYVAL nBrdNum AS INTEGER, BYVAL pCJCtemp AS SINGLE)

Parameters

nBrdNum

Board number. Valid values: 0 or 1

Return Value

Remarks

pCJCtemp

Error/status code. Refer to Appendix A.

For the DAS-TC or D AS-TC/B board speciﬁed by nBrdNum , this function

CJC sensor temperatures in degrees Celsius.

reads the cold junction compensation temperature at the STA-TC, STC-TC, STA-TC/B, or STC-TC/B terminals connected to the board and stores the value in pCJCtemp .

The board number speciﬁed in nBrdNum refers to the board number speciﬁed in the conﬁguration ﬁle.

4-8 Function Reference

The value stored in pCJCtemp is ﬂoating point regardless of the format speciﬁed in the conﬁguration ﬁle.

In order to obtain a temperature reading from a thermocouple type not recognized by the Function Call Driver, you need to perform your own linearization by calling DASTC_GETCJC and using the resulting value to correct the linearization.

Depending on the volatility of the ambient temperature where the CJC resides, use DASTC_GETCJC more often as you take more samples.

Usage C/C++

#include "DTCDECL.H" // Use DASTC.HPP for C++ ... float hTemp; ... wDasErr = DASTC_GETCJC (0, &hTemp);

DASTC_GETCJC (cont.)

Turbo Pascal

uses DTCTPU; ... hTemp : Real; {CJC Temperature} ... wDasErr := DASTC_GETCJC (0, hTemp);

Turbo Pascal for Windows

{$I DASDECL.INC} ... hTemp : Single; { CJC Temperature } ... wDasErr := DASTC_GETCJC (0, hTemp);

Visual Basic for Windows

(Add DTCDECL.BAS to your project)

... Global hTemp As Single ' CJC Temperature ... wDasErr = DASTC_GETCJC (0, hTemp)

4-9

DASTC_GETCJC (cont.)

BASIC

' $INCLUDE: 'DASTC.BI' ... DIM hTemp AS Single' CJC Temperature ... wDasErr = DASTCGETDEVHANDLE% (0, hTemp)

4-10 Function Reference

DASTC_GetDevHandle

Purpose

Prototype C/C++

Initializes a DAS-TC or DAS-TC/B board.

DASErr far pascal DASTC_GetDevHandle (WORD nBrdNum, void far * far *phDev);

Turbo Pascal

Function DASTC_GetDevHandle (nBrdNum : Word; Var phDev : Longint) : Word; far; external 'DASTC';

Turbo Pascal for Windows

Function DASTC_GetDevHandle (nBrdNum : Word; Var phDev : Longint) : Word; far; external 'DASTC';

Visual Basic for Windows

Declare Function DASTC_GetDevHandle Lib "DASTC.DLL" (ByVal nBrdNum As Integer, phDev As Long) As Integer

BASIC

DECLARE FUNCTION DASTCGETDEVHANDLE% ALIAS "DASTC_GetDevHandle" (BYVAL nBrdNum AS INTEGER, SEG phDev AS LONG)

Parameters

Return Value

Remarks

nBrdNum Board number.

Valid values: 0 or 1

phDev Handle associated with the board.

Error/status code. Refer to Appendix A.

This function initializes the DAS-TC or DAS-TC/B board speciﬁed by nBrdNum and stores the device handle of the speciﬁed board in phDev.

The board number speciﬁed in nBrdNum refers to the board number speciﬁed in the conﬁguration ﬁle.

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

4-11

DASTC_GetDevHandle (cont.)

See Also

Usage C/C++

K_GetDevHandle

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

Turbo Pascal

uses DTCTPU; ... hDev : Longint; { Device Handle } ... wDasErr := DASTC_GetDevHandle (0, hDev);

Turbo Pascal for Windows

{$I DASTC.INC} ... hDev : Longint; { Device Handle } ... wDasErr := DASTC_GetDevHandle (0, hDev);

Visual Basic for Windows

(Add DTCDECL.BAS to your project)

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

BASIC

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

4-12 Function Reference

K_ADRead

Purpose

For use with the C/C++, Turbo Pascal, and Turbo Pascal for Windows languages only, reads a single analog input value.

Prototype C/C++

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

Turbo Pascal

Function K_ADRead (hDev : Longint; nChan : Byte; nGain : Byte; pData : Pointer) : Word;

Turbo Pascal for Windows

Function K_ADRead (hDev : Longint; nChan : Byte; nGain : Byte; pData : Pointer) : Word; far; external 'DASSHELL';

Visual Basic for Windows

Not supported. Use K_ADReadL or K_ADReadR instead.

BASIC

Not supported. Use K_ADReadL or K_ADReadR instead.

Parameters

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

Valid values: 0 to 15

4-13

K_ADRead (cont.)

nGain Gain code.

Valid values are listed in the table below. For thermocouple inputs, gain is ignored; specify a gain code of 0 for thermocouple inputs.

Return Value

Remarks

See Also

Gain Code

0 1 −2.5 V to 10 V 1 125 −20 mV to 80 mV 2 166.67 −15 mV to 60 mV 3 400 −6.25 mV to 25 mV

Gain Voltage

Input Range

pData Acquired analog input value.

Error/status code. Refer to Appendix A.

This function reads the analog input channel nChan on the DAS-TC or DAS-TC/B board speciﬁed by hDev and stores the value in pData.

Depending on the input type speciﬁed in the conﬁguration ﬁle, the value stored in pData is in microvolts or in hundredths of degrees for integer types and is not scaled for ﬂoating point. Refer to Appendix B for more information on the format of acquired data.

K_IntStart, K_SyncStart

Usage C/C++

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

4-14 Function Reference

K_ADRead (cont.)

Turbo Pascal

uses DTCTPU; ... dwADValue : Long; ... wDasErr := K_ADRead (hDev, 0, 0, @dwADValue);

Turbo Pascal for Windows

{$I DASDECL.INC} ... dwADValue : Long; ... wDasErr := K_ADRead (hDev, 0, 0, @dwADValue);

4-15

K_ADReadL

Purpose

For use with the Visual Basic for Windows and BASIC languages only, reads a single analog input value. Use K_ADReadL when you want to store the value as a long integer.

Prototype C/C++

Not supported. Use K_ADRead instead.

Turbo Pascal

Not supported. Use K_ADRead instead.

Turbo Pascal for Windows

Not supported. Use K_ADRead instead.

Visual Basic for Windows

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

BASIC

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

Parameters

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

Valid values: 0 to 15

4-16 Function Reference

nGain Gain code.

Valid values are listed in the table below. For thermocouple inputs, gain is ignored; specify a gain code of 0 for thermocouple inputs.

K_ADReadL (cont.)

Return Value

Remarks

See Also

Gain Code

0 1 −2.5 V to 10 V 1 125 −20 mV to 80 mV 2 166.67 −15 mV to 60 mV 3 400 −6.25 mV to 25 mV

Gain Voltage

Input Range

pData Acquired analog input value.

Error/status code. Refer to Appendix A.

This function reads the analog input channel nChan on the DAS-TC or DAS-TC/B board speciﬁed by hDev and stores the value in pData.

Depending on the input type speciﬁed in the conﬁguration ﬁle, the value stored in pData is in microvolts or in hundredths of degrees for long integer types. Refer to Appendix B for more information on the format of acquired data.

K_ADReadR, K_IntStart, K_SyncStart

Usage Visual Basic for Windows

(Add DASDECL.BAS to your project)

... Global dwADValue As Long ... wDasErr = K_ADReadL (hDev, 0, 0, dwADValue)

4-17

K_ADReadL (cont.)

BASIC

' $INCLUDE: 'DASDECL.BI' ... DIM dwADValue AS LONG ... wDasErr = KADREADL% (hDev, 0, 0, dwADValue)

4-18 Function Reference

K_ADReadR

Purpose

For use with the Visual Basic for Windows and BASIC languages only, reads a single analog input value. Use K_ADReadR when you want to store the value using a ﬂoating-point (real) data type.

Prototype C/C++

Not supported. Use K_ADRead instead.

Turbo Pascal

Not supported. Use K_ADRead instead.

Turbo Pascal for Windows

Not supported. Use K_ADRead instead.

Visual Basic for Windows

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

BASIC

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

Parameters

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

Valid values: 0 to 15

4-19

K_ADReadR (cont.)

nGain Gain code.

Valid values are listed in the table below. For thermocouple inputs, gain is ignored; specify a gain code of 0 for thermocouple inputs.

pData Acquired analog input value.

Return Value

Remarks

Error/status code. Refer to Appendix A.

This function reads the analog input channel nChan on the DAS-TC or DAS-TC/B board speciﬁed by hDev and stores the value in pData.

The value stored in pData is not scaled for ﬂoating point. Refer to Appendix B for more information on the format of acquired data.

See Also

Usage Visual Basic for Windows

K_ADReadL, K_IntStart, K_SyncStart

(Add DASDECL.BAS to your project)

... Global dwADValue As Single ... wDasErr = K_ADReadR (hDev, 0, 0, dwADValue)

Gain Code

0 1 −2.5 V to 10 V 1 125 −20 mV to 80 mV 2 166.67 −15 mV to 60 mV 3 400 −6.25 mV to 25 mV

Gain Voltage

Input Range

4-20 Function Reference

K_ADReadR (cont.)

BASIC

' $INCLUDE: 'DASDECL.BI' ... DIM dwADValue AS SINGLE ... wDasErr = KADREADR% (hDev, 0, 0, dwADValue)

4-21

K_ClearFrame

Purpose

Prototype C/C++

Sets the elements of a frame to their default values.

DASErr far pascal K_ClearFrame (DWORD hFrame);

Turbo Pascal

Function K_ClearFrame (hFrame : Longint) : Word;

Turbo Pascal for Windows

Function K_ClearFrame (hFrame : Longint) : Word; far; external 'DASSHELL';

Visual Basic for Windows

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

BASIC

DECLARE FUNCTION KCLEARFRAME% ALIAS "K_ClearFrame" (BYVAL hFrame AS LONG)

Parameters

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

Return Value

Remarks

Error/status code. Refer to Appendix A.

This function sets the elements of the frame speciﬁed by hFrame to their default values.

Refer to Table 3-1 on page 3-4 for the default values of an A/D frame.

See Also

Usage C/C++

4-22 Function Reference

K_GetADFrame

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

Turbo Pascal

uses DTCTPU; ... wDasErr := K_ClearFrame (hAD);

Turbo Pascal for Windows

{$I DASDECL.INC} ... wDasErr := K_ClearFrame (hAD);

Visual Basic for Windows

(Add DASDECL.BAS to your project)

... wDasErr = K_ClearFrame (hAD)

BASIC

' $INCLUDE: 'DASDECL.BI' ... wDasErr = KCLEARFRAME% (hAD)

K_ClearFrame (cont.)

4-23

K_CloseDriver

Purpose

Prototype C/C++

Closes a previously initialized Keithley DAS Function Call Driver.

DASErr far pascal K_CloseDriver (DWORD hDrv);

Turbo Pascal

Not supported

Turbo Pascal for Windows

Function K_CloseDriver (hDrv : Longint) : Word; far; external 'DASSHELL';

Visual Basic for Windows

Declare Function K_CloseDriver Lib "DASSHELL.DLL" (ByVal hDrv As Long) As Integer

BASIC

Not supported

Parameters

Return Value

hDrv Driver handle you want to free.

Error/status code. Refer to Appendix A.

Remarks

This function frees the driver handle speciﬁed by hDrv and closes the associated use of the Function Call Driver. This function also frees all device handles and frame handles associated with hDrv.

If hDrv is the last driver handle speciﬁed for the Function Call Driver, the driver is shut down (for all languages) and unloaded (for Windows-based languages only).

See Also

4-24 Function Reference

K_FreeDevHandle

Usage C/C++

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

Turbo Pascal for Windows

{$I DASDECL.INC} ... wDasErr := K_CloseDriver (hDrv);

Visual Basic for Windows

(Add DASDECL.BAS to your project)

... wDasErr = K_CloseDriver (hDrv)

K_CloseDriver (cont.)

4-25

K_ClrContRun

Purpose

Prototype C/C++

Speciﬁes single-cycle buffering mode.

DASErr far pascal K_ClrContRun (DWORD hFrame);

Turbo Pascal

Function K_ClrContRun (hFrame : Longint) : Word;

Turbo Pascal for Windows

Function K_ClrContRun (hFrame : Longint) : Word; far; external 'DASSHELL';

Visual Basic for Windows

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

BASIC

DECLARE FUNCTION KCLRCONTRUN% ALIAS "K_ClrContRun" (BYVAL hFrame AS LONG)

Parameters

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

Return Value

Remarks

Error/status code. Refer to Appendix A.

This function sets the buffering mode for the operation deﬁned by hF rame to single-cycle mode and sets the Buffering Mode element in the frame accordingly.

K_GetADFrame and K_ClearFrame also enable single-cycle buffering mode.

Refer to page 2-13 for more information on buffering modes.

See Also

4-26 Function Reference

K_SetContRun

Usage C/C++

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

Turbo Pascal

uses DTCTPU; ... wDasErr := K_ClrContRun (hAD);

Turbo Pascal for Windows

{$I DASDECL.INC} ... wDasErr := K_ClrContRun (hAD);

Visual Basic for Windows

(Add DASDECL.BAS to your project)

... wDasErr = K_ClrContRun (hAD)

K_ClrContRun (cont.)

BASIC

' $INCLUDE: 'DASDECL.BI' ... wDasErr = KCLRCONTRUN% (hAD)

4-27

K_DASDevInit

Purpose

Prototype C/C++

Reinitializes a Keithley MetraByte DAS board.

DASErr far pascal K_DASDevInit (DWORD hDev);

Turbo Pascal

Function K_DASDevInit (hDev : Longint) : Longint;

Turbo Pascal for Windows

Function K_DASDevInit (hDev : Longint) : Longint; far; external 'DASSHELL';

Visual Basic for Windows

Declare Function K_DASDevInit Lib "DASSHELL.DLL" (ByVal hDev As Long) As Integer

BASIC

DECLARE FUNCTION KDASDEVINIT% ALIAS "K_DASDevInit" (BYVAL hDev AS LONG)

Parameters

hDev Handle associated with the board.

Return Value

Remarks

Error/status code. Refer to Appendix A.

Use K_GetDevHandle or DASTC_GetDevHandle the ﬁrst time you initialize the board only . Once you ha v e a de vice handle, use this function to reinitialize the board.

Usage C/C++

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

Turbo Pascal

uses DTCTPU; ... wDasErr := K_DASDevInit (hDev);

4-28 Function Reference

Turbo Pascal for Windows

{$I DASDECL.INC} ... wDasErr := K_DASDevInit (hDev);

Visual Basic for Windows

(Add DASDECL.BAS to your project)

... wDasErr = K_DASDevInit (hDev)

BASIC

' $INCLUDE: 'DASDECL.BI' ... wDasErr = KDASDEVINIT% (hDev)

K_DASDevInit (cont.)

4-29

K_FormatChnGAry

Purpose

Prototype C/C++

Converts the format of a channel-gain queue.

Not supported

Turbo Pascal

Not supported

Turbo Pascal for Windows

Not supported

Visual Basic for Windows

Declare Function K_FormatChnGAry Lib "DASSHELL.DLL" (pArray As Integer) As Integer

BASIC

DECLARE FUNCTION KFORMATCHNGARY% ALIAS "K_FormatChnGAry" (SEG pArray AS INTEGER)

Parameters

Return Value

pArray Channel-gain queue starting address.

Error/status code. Refer to Appendix A.

Remarks

This function converts a channel-gain queue created in BASIC or Visual Basic for Windows using 16-bit values to a channel-gain queue of 8-bit values that the K_SetChnGAry function can use, and stores the starting address of the converted channel-gain queue in pArray.

After you use this function, your program can no longer read the converted channel-gain queue. You must use the K_RestoreChnGAry function to return the queue to its original format. Refer to page 3-30 for more information on creating channel-gain queues in Visual Basic; refer to page 3-37 for more information on creating channel-gain queues in BASIC.

See Also

4-30 Function Reference

K_SetChnGAry, K_RestoreChnGAry

K_FormatChnGAry (cont.)

Usage

Visual Basic for Windows

(Add DASDECL.BAS to your project)

... Global ChanGainArray(16) As Integer ' Chan/Gain array ... ' Create the array of channel/gain pairs ChanGainArray(0) = 2 ' # of chan/gain pairs ChanGainArray(1) = 0: ChanGainArray(2) = 0 ChanGainArray(3) = 1: ChanGainArray(4) = 3 wDasErr = K_FormatChnGAry (ChanGainArray(0))

BASIC

' $INCLUDE: 'DASDECL.BI' ... DIM ChanGainArray(16) AS INTEGER ' Chan/Gain array ... ' Create the array of channel/gain pairs ChanGainArray(0) = 2 ' # of chan/gain pairs ChanGainArray(1) = 0: ChanGainArray(2) = 0 ChanGainArray(3) = 1: ChanGainArray(4) = 3 wDasErr = KFORMATCHNGARY% (ChanGainArray(0))

4-31

K_FreeDevHandle

Purpose

Prototype C/C++

Frees a previously speciﬁed device handle.

DASErr far pascal K_FreeDevHandle (DWORD phDev);

Turbo Pascal

Not supported

Turbo Pascal for Windows

Function K_FreeDevHandle (phDev : Longint) : Word; far; external 'DASSHELL';

Visual Basic for Windows

Declare Function K_FreeDevHandle Lib "DASSHELL.DLL" (ByVal phDev As Long) As Integer

BASIC

Not supported

Parameters

Return Value

phDev Device handle you want to free.

Error/status code. Refer to Appendix A.

Remarks

This function frees the device handle speciﬁed by phDev as well as all frame handles associated with phDev.

See Also

Usage C/C++

4-32 Function Reference

K_GetDevHandle

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

Turbo Pascal for Windows

{$I DASDECL.INC} ... wDasErr := K_FreeDevHandle (hDev);

K_FreeDevHandle (cont.)

Visual Basic for Windows

(Add DASDECL.BAS to your project)

... wDasErr = K_FreeDevHandle (hDev)

4-33

Tektronix DAS-TC Function Call Driver Users Guide

Specifications and Main Features

Frequently Asked Questions

User Manual